[codex] Add knowledge graph retraction guard

README.md

@@ -1,2 +1,6 @@
 # deepevents.ai
 deepevents.ai main codebase
+
+## Scientific knowledge graph additions
+
+- `knowledge-graph-retraction-guard`: retraction and correction propagation guard for suppressing unsafe knowledge graph recommendations and producing curator-ready evidence.

knowledge-graph-retraction-guard/README.md

@@ -0,0 +1,25 @@
+# Knowledge Graph Retraction Guard
+
+Scientific knowledge graphs need to react when a paper is retracted, corrected, or flagged with an expression of concern. This module adds a deterministic retraction and correction propagation guard for graph edges, entity pages, and AI recommendation payloads.
+
+The guard is self-contained and credential-free. It consumes synthetic graph entities, evidence relationships, recommendation candidates, and publication notices, then emits:
+
+- retraction/correction findings tied to graph entities and evidence edges
+- suppressed or review-only recommendation decisions
+- curator actions for entity pages, relationship evidence, and digest exports
+- JSON-LD style evidence output for downstream graph and audit systems
+- a deterministic evidence digest for reproducible review
+
+## Run
+
+```bash
+npm run check
+npm test
+npm run demo
+```
+
+The demo reads `data/sample-knowledge-graph.json`. Visual review artifacts are in `docs/demo.svg` and `docs/demo.gif`.
+
+## Fit For Issue #17
+
+This targets the Scientific Knowledge Graph Integration requirements for cited references, entity pages, graph navigation, and AI recommendations. It is distinct from prior extractor, navigator, link-audit, ontology-drift, conflict-arbiter, author-affiliation, knowledge-gap, and artifact-lineage slices because it focuses specifically on propagating publication safety notices through graph recommendations.

knowledge-graph-retraction-guard/data/sample-knowledge-graph.json

@@ -0,0 +1,136 @@
+{
+  "generatedAt": "2026-05-16T14:30:00Z",
+  "workspace": "SCIBASE translational neuroscience graph",
+  "entities": [
+    {
+      "id": "paper-alpha",
+      "type": "paper",
+      "label": "Alpha-synuclein organoid response atlas",
+      "doi": "10.5555/alpha.2023.101",
+      "domain": "neuroscience",
+      "projectIds": ["proj-organoid-map"]
+    },
+    {
+      "id": "dataset-dopamine",
+      "type": "dataset",
+      "label": "Dopamine neuron morphology panel",
+      "doi": "10.5555/data.2024.220",
+      "domain": "neuroscience",
+      "projectIds": ["proj-organoid-map", "proj-neurochip"]
+    },
+    {
+      "id": "protocol-immunostain",
+      "type": "protocol",
+      "label": "High-throughput immunostaining v2",
+      "doi": "10.5555/protocol.2022.014",
+      "domain": "cell-biology",
+      "projectIds": ["proj-organoid-map"]
+    },
+    {
+      "id": "paper-beta",
+      "type": "paper",
+      "label": "CRISPR screen for synaptic rescue",
+      "doi": "10.5555/beta.2024.017",
+      "domain": "genomics",
+      "projectIds": ["proj-neurochip"]
+    },
+    {
+      "id": "tool-labpipe",
+      "type": "software",
+      "label": "LabPipe notebook runner",
+      "doi": "10.5555/tool.2021.002",
+      "domain": "software",
+      "projectIds": ["proj-metabolomics"]
+    }
+  ],
+  "relationships": [
+    {
+      "id": "rel-alpha-dataset",
+      "sourceId": "paper-alpha",
+      "targetId": "dataset-dopamine",
+      "type": "uses_dataset",
+      "evidenceDoi": "10.5555/alpha.2023.101",
+      "confidence": 0.91,
+      "recommendationId": "rec-organoid-reuse"
+    },
+    {
+      "id": "rel-dataset-protocol",
+      "sourceId": "dataset-dopamine",
+      "targetId": "protocol-immunostain",
+      "type": "validated_by_protocol",
+      "evidenceDoi": "10.5555/protocol.2022.014",
+      "confidence": 0.74,
+      "recommendationId": "rec-protocol-transfer"
+    },
+    {
+      "id": "rel-beta-dataset",
+      "sourceId": "paper-beta",
+      "targetId": "dataset-dopamine",
+      "type": "cites_dataset",
+      "evidenceDoi": "10.5555/beta.2024.017",
+      "confidence": 0.82,
+      "recommendationId": "rec-crispr-collab"
+    },
+    {
+      "id": "rel-tool-dataset",
+      "sourceId": "tool-labpipe",
+      "targetId": "dataset-dopamine",
+      "type": "processes_dataset",
+      "evidenceDoi": "10.5555/tool.2021.002",
+      "confidence": 0.68,
+      "recommendationId": "rec-runner-adoption"
+    }
+  ],
+  "recommendations": [
+    {
+      "id": "rec-organoid-reuse",
+      "title": "Reuse dopamine morphology panel for organoid comparison",
+      "relationshipIds": ["rel-alpha-dataset", "rel-dataset-protocol"],
+      "audience": "project-sidebar"
+    },
+    {
+      "id": "rec-protocol-transfer",
+      "title": "Transfer immunostaining protocol into neurochip workflow",
+      "relationshipIds": ["rel-dataset-protocol"],
+      "audience": "weekly-digest"
+    },
+    {
+      "id": "rec-crispr-collab",
+      "title": "Invite CRISPR rescue team to validate morphology findings",
+      "relationshipIds": ["rel-beta-dataset"],
+      "audience": "discovery-mode"
+    },
+    {
+      "id": "rec-runner-adoption",
+      "title": "Adopt LabPipe runner for dataset refresh jobs",
+      "relationshipIds": ["rel-tool-dataset"],
+      "audience": "admin-dashboard"
+    }
+  ],
+  "publicationNotices": [
+    {
+      "doi": "10.5555/alpha.2023.101",
+      "type": "retraction",
+      "severity": "critical",
+      "publishedAt": "2026-05-12",
+      "source": "Crossmark synthetic notice",
+      "reason": "Image panel duplication invalidates primary evidence"
+    },
+    {
+      "doi": "10.5555/protocol.2022.014",
+      "type": "expression_of_concern",
+      "severity": "high",
+      "publishedAt": "2026-05-09",
+      "source": "Publisher synthetic alert",
+      "reason": "Protocol reagent concentration under investigation"
+    },
+    {
+      "doi": "10.5555/tool.2021.002",
+      "type": "correction",
+      "severity": "medium",
+      "publishedAt": "2026-05-01",
+      "source": "Software release note",
+      "reason": "Default notebook kernel version corrected"
+    }
+  ]
+}

knowledge-graph-retraction-guard/docs/requirement-map.md

@@ -0,0 +1,14 @@
+# Requirement Map
+
+| Issue #17 capability | Implementation evidence |
+| --- | --- |
+| Cited references and DOIs | `publicationNotices` and relationship `evidenceDoi` matching in `src/retraction-signal-guard.js` |
+| Entity pages with aggregated context | `entity_publication_notice` findings and `annotate_entity_page` curator actions |
+| Graph navigation safety | relationship findings suppress or review graph edges that rely on unsafe evidence |
+| AI recommendations | recommendation decisions emit `allow`, `annotate`, `review`, or `suppress` for sidebar, digest, and discovery recommendations |
+| Linked data / schema.org metadata | JSON-LD style export is produced in `report.jsonLd` |
+| Auditability | deterministic `evidenceDigest`, sorted findings, sample data, CLI demo, and Node tests |
+
+## Distinctness
+
+This module is not a broad extractor, navigator, ontology migration, conflict arbiter, author disambiguation, knowledge-gap explorer, or artifact-lineage tracker. It focuses on publication safety notices and how those notices propagate through graph edges and recommendations.

knowledge-graph-retraction-guard/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "knowledge-graph-retraction-guard",
+  "version": "1.0.0",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "check": "node --check src/retraction-signal-guard.js && node --check scripts/demo.js && node --check test/retraction-signal-guard.test.js",
+    "test": "node --test test/retraction-signal-guard.test.js",
+    "demo": "node scripts/demo.js"
+  }
+}

knowledge-graph-retraction-guard/scripts/demo.js

@@ -0,0 +1,17 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { analyzeRetractionSignals } from "../src/retraction-signal-guard.js";
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const input = JSON.parse(readFileSync(join(root, "data", "sample-knowledge-graph.json"), "utf8"));
+const report = analyzeRetractionSignals(input);
+
+console.log(`${report.workspace} retraction guard`);
+console.log(`Evidence digest: ${report.evidenceDigest}`);
+console.log(`Findings: ${report.summary.findings} (${report.summary.criticalFindings} critical, ${report.summary.highFindings} high)`);
+console.log(`Recommendations: ${report.summary.suppressedRecommendations} suppressed, ${report.summary.reviewRecommendations} review`);
+console.log("Top curator actions:");
+for (const action of report.curatorActions.slice(0, 5)) {
+  console.log(`- [${action.severity}] ${action.action}: ${action.subject}`);
+}