Add instrument calibration graph guard

instrument-calibration-graph-guard/README.md

@@ -0,0 +1,50 @@
+# Instrument Calibration Graph Guard
+
+This module adds a focused Scientific Knowledge Graph Integration slice for instrument calibration provenance.
+
+It answers:
+
+> Can an instrument/tool node and its experiment edges be published or used for recommendations without misleading researchers about calibration validity?
+
+## Scope
+
+This is distinct from broad entity extraction, ontology aliasing, sample custody, chemical identity, image metadata, software dependency, funding provenance, protocol-deviation, and temporal-validity slices. It focuses only on instrument/tool graph nodes and calibration certificate evidence.
+
+The guard checks:
+
+- instrument nodes have stable identifiers and serial/model metadata
+- each public experiment edge points to a calibration certificate
+- certificate hashes and issuers are present
+- calibration validity covers the experiment timestamp
+- certificates are not revoked
+- measurement units match the instrument capability profile
+- recommendation/publication edges are held when calibration evidence is missing or expired
+
+## Decisions
+
+- `PUBLISH_GRAPH_EDGE`: graph node and experiment edge are safe to publish.
+- `HOLD_FOR_CURATOR`: evidence is incomplete or stale but recoverable.
+- `BLOCK_RECOMMENDATION`: publishing would create a misleading recommendation or entity page.
+
+## Run
+
+```bash
+npm test
+npm run demo
+```
+
+Demo outputs are written to `artifacts/`:
+
+- `instrument-calibration-results.json`
+- `instrument-calibration-report.md`
+- `instrument-calibration-summary.svg`
+- `instrument-calibration-demo.mp4`
+
+## Boundaries
+
+- synthetic graph packets only
+- no lab system integration
+- no private experiment data
+- no external APIs
+- no credentials
+- no live compliance claims

instrument-calibration-graph-guard/artifacts/instrument-calibration-report.md

@@ -0,0 +1,59 @@
+# Instrument Calibration Graph Guard Report
+
+Generated: 2026-06-12T00:00:00Z
+
+## Summary
+
+- Blocking findings: 4
+- Review findings: 2
+- Passing findings: 12
+
+## Instrument Decisions
+
+### instrument:mass-spec:orbitrap-0021
+
+- Decision: PUBLISH_GRAPH_EDGE
+- Instrument type: mass_spectrometer
+- Certificate: cal-2026-ms-0021
+- Experiment edges: 1
+
+| Severity | Code | Message | Remediation |
+| --- | --- | --- | --- |
+| pass | instrument_identity_ready | Instrument node has stable model, serial, type, and graph ID metadata. | No remediation required. |
+| pass | calibration_certificate_present | Calibration certificate metadata and artifact hash are present. | No remediation required. |
+| pass | calibration_current | Calibration certificate is current at review time. | No remediation required. |
+| pass | experiment_edges_covered | All experiment edges fall inside the calibration validity window. | No remediation required. |
+| pass | unit_compatibility_ready | Experiment measurement units match declared instrument capabilities. | No remediation required. |
+| pass | recommendation_controls_ready | Recommendation targets can be held when calibration evidence is not publishable. | No remediation required. |
+
+### instrument:microscope:confocal-17
+
+- Decision: HOLD_FOR_CURATOR
+- Instrument type: confocal_microscope
+- Certificate: cal-2025-micro-17
+- Experiment edges: 1
+
+| Severity | Code | Message | Remediation |
+| --- | --- | --- | --- |
+| pass | instrument_identity_ready | Instrument node has stable model, serial, type, and graph ID metadata. | No remediation required. |
+| pass | calibration_certificate_present | Calibration certificate metadata and artifact hash are present. | No remediation required. |
+| review | calibration_expired | Calibration certificate expired at 2025-12-31T23:59:59.000Z. | Refresh calibration evidence or hold graph publication for affected instrument edges. |
+| pass | experiment_edges_covered | All experiment edges fall inside the calibration validity window. | No remediation required. |
+| pass | unit_compatibility_ready | Experiment measurement units match declared instrument capabilities. | No remediation required. |
+| pass | recommendation_controls_ready | Recommendation targets can be held when calibration evidence is not publishable. | No remediation required. |
+
+### instrument:sequencer:seq-09
+
+- Decision: BLOCK_RECOMMENDATION
+- Instrument type: sequencer
+- Certificate: cal-2026-seq-09
+- Experiment edges: 1
+
+| Severity | Code | Message | Remediation |
+| --- | --- | --- | --- |
+| pass | instrument_identity_ready | Instrument node has stable model, serial, type, and graph ID metadata. | No remediation required. |
+| block | calibration_certificate_missing | Calibration certificate evidence missing: artifactHash. | Attach calibration certificate ID, issuer, artifact hash, and validity dates. |
+| block | calibration_revoked | Calibration certificate is revoked. | Remove the instrument from public recommendations until a valid replacement certificate is attached. |
+| block | experiment_outside_calibration_window | Experiment edges outside calibration window: edge:rnaseq-run-19. | Split or hold experiment edges measured outside the calibration validity window. |
+| review | unit_incompatible | Measurement units not declared for instrument capability: edge:rnaseq-run-19:cycles. | Normalize units or route the graph packet to a curator for capability review. |
+| block | recommendation_without_hold_control | Recommendation targets need hold controls before publication: recommend:single-cell-pipeline. | Add hold controls so recommendation edges are suppressed when calibration evidence fails. |

instrument-calibration-graph-guard/artifacts/instrument-calibration-results.json

@@ -0,0 +1,164 @@
+[
+  {
+    "graphNodeId": "instrument:mass-spec:orbitrap-0021",
+    "decision": "PUBLISH_GRAPH_EDGE",
+    "checkedAt": "2026-06-12T00:00:00.000Z",
+    "summary": {
+      "blocks": 0,
+      "reviews": 0,
+      "passes": 6
+    },
+    "findings": [
+      {
+        "code": "instrument_identity_ready",
+        "severity": "pass",
+        "message": "Instrument node has stable model, serial, type, and graph ID metadata.",
+        "remediation": "No remediation required."
+      },
+      {
+        "code": "calibration_certificate_present",
+        "severity": "pass",
+        "message": "Calibration certificate metadata and artifact hash are present.",
+        "remediation": "No remediation required."
+      },
+      {
+        "code": "calibration_current",
+        "severity": "pass",
+        "message": "Calibration certificate is current at review time.",
+        "remediation": "No remediation required."
+      },
+      {
+        "code": "experiment_edges_covered",
+        "severity": "pass",
+        "message": "All experiment edges fall inside the calibration validity window.",
+        "remediation": "No remediation required."
+      },
+      {
+        "code": "unit_compatibility_ready",
+        "severity": "pass",
+        "message": "Experiment measurement units match declared instrument capabilities.",
+        "remediation": "No remediation required."
+      },
+      {
+        "code": "recommendation_controls_ready",
+        "severity": "pass",
+        "message": "Recommendation targets can be held when calibration evidence is not publishable.",
+        "remediation": "No remediation required."
+      }
+    ],
+    "audit": {
+      "instrumentType": "mass_spectrometer",
+      "certificateId": "cal-2026-ms-0021",
+      "experimentCount": 1,
+      "recommendationTargets": 1
+    }
+  },
+  {
+    "graphNodeId": "instrument:microscope:confocal-17",
+    "decision": "HOLD_FOR_CURATOR",
+    "checkedAt": "2026-06-12T00:00:00.000Z",
+    "summary": {
+      "blocks": 0,
+      "reviews": 1,
+      "passes": 5
+    },
+    "findings": [
+      {
+        "code": "instrument_identity_ready",
+        "severity": "pass",
+        "message": "Instrument node has stable model, serial, type, and graph ID metadata.",
+        "remediation": "No remediation required."
+      },
+      {
+        "code": "calibration_certificate_present",
+        "severity": "pass",
+        "message": "Calibration certificate metadata and artifact hash are present.",
+        "remediation": "No remediation required."
+      },
+      {
+        "code": "calibration_expired",
+        "severity": "review",
+        "message": "Calibration certificate expired at 2025-12-31T23:59:59.000Z.",
+        "remediation": "Refresh calibration evidence or hold graph publication for affected instrument edges."
+      },
+      {
+        "code": "experiment_edges_covered",
+        "severity": "pass",
+        "message": "All experiment edges fall inside the calibration validity window.",
+        "remediation": "No remediation required."
+      },
+      {
+        "code": "unit_compatibility_ready",
+        "severity": "pass",
+        "message": "Experiment measurement units match declared instrument capabilities.",
+        "remediation": "No remediation required."
+      },
+      {
+        "code": "recommendation_controls_ready",
+        "severity": "pass",
+        "message": "Recommendation targets can be held when calibration evidence is not publishable.",
+        "remediation": "No remediation required."
+      }
+    ],
+    "audit": {
+      "instrumentType": "confocal_microscope",
+      "certificateId": "cal-2025-micro-17",
+      "experimentCount": 1,
+      "recommendationTargets": 1
+    }
+  },
+  {
+    "graphNodeId": "instrument:sequencer:seq-09",
+    "decision": "BLOCK_RECOMMENDATION",
+    "checkedAt": "2026-06-12T00:00:00.000Z",
+    "summary": {
+      "blocks": 4,
+      "reviews": 1,
+      "passes": 1
+    },
+    "findings": [
+      {
+        "code": "instrument_identity_ready",
+        "severity": "pass",
+        "message": "Instrument node has stable model, serial, type, and graph ID metadata.",
+        "remediation": "No remediation required."
+      },
+      {
+        "code": "calibration_certificate_missing",
+        "severity": "block",
+        "message": "Calibration certificate evidence missing: artifactHash.",
+        "remediation": "Attach calibration certificate ID, issuer, artifact hash, and validity dates."
+      },
+      {
+        "code": "calibration_revoked",
+        "severity": "block",
+        "message": "Calibration certificate is revoked.",
+        "remediation": "Remove the instrument from public recommendations until a valid replacement certificate is attached."
+      },
+      {
+        "code": "experiment_outside_calibration_window",
+        "severity": "block",
+        "message": "Experiment edges outside calibration window: edge:rnaseq-run-19.",
+        "remediation": "Split or hold experiment edges measured outside the calibration validity window."
+      },
+      {
+        "code": "unit_incompatible",
+        "severity": "review",
+        "message": "Measurement units not declared for instrument capability: edge:rnaseq-run-19:cycles.",
+        "remediation": "Normalize units or route the graph packet to a curator for capability review."
+      },
+      {
+        "code": "recommendation_without_hold_control",
+        "severity": "block",
+        "message": "Recommendation targets need hold controls before publication: recommend:single-cell-pipeline.",
+        "remediation": "Add hold controls so recommendation edges are suppressed when calibration evidence fails."
+      }
+    ],
+    "audit": {
+      "instrumentType": "sequencer",
+      "certificateId": "cal-2026-seq-09",
+      "experimentCount": 1,
+      "recommendationTargets": 1
+    }
+  }
+]