feat/sourceos-shell-contracts-bootstrap

docs/adr/0002-sourceos-shell-api-event-backlog.md

@@ -0,0 +1,24 @@
+# ADR 0002 — sourceos-shell API and event backlog
+
+## Status
+Accepted
+
+## Context
+
+The shell/document/provenance workflow now has an initial schema cut, but downstream implementations also need a clear backlog for the API and event surfaces that should be added to OpenAPI and AsyncAPI.
+
+## Decision
+
+Queue the following surfaces for future OpenAPI/AsyncAPI additions:
+
+- artifact sign/validate status
+- annotation export
+- run-report publication
+- publish decisions
+- mirror receipts
+- Noether diagnostic publication
+- search route decisions
+
+## Consequences
+
+The schema layer can land incrementally while API/event surfaces are added in follow-on patches without re-defining the objects elsewhere.

examples/annotation-export.json

@@ -0,0 +1,9 @@
+{
+  "exportId": "ann-export-001",
+  "target": "demo-report",
+  "format": "w3c-web-annotation",
+  "annotations": [
+    {"id": "ann-1", "type": "Annotation", "body": {"type": "TextualBody", "value": "needs evidence"}}
+  ],
+  "exportedAt": "2026-04-18T01:30:00Z"
+}

examples/mirror-receipt.json

@@ -0,0 +1,8 @@
+{
+  "receiptId": "mirror-001",
+  "artifactId": "demo-report",
+  "channel": "urbit",
+  "status": "mirrored",
+  "mirroredAt": "2026-04-18T01:34:00Z",
+  "detail": "Mirrored to ship-local Clay cache."
+}

examples/noether-diagnostic.json

@@ -0,0 +1,9 @@
+{
+  "diagnosticId": "diag-001",
+  "layer": "h_block_1",
+  "charge": "angular_momentum",
+  "value": 0.998,
+  "measuredAt": "2026-04-18T01:32:00Z",
+  "tolerance": 0.01,
+  "pass": true
+}

examples/publish-decision.json

@@ -0,0 +1,8 @@
+{
+  "decisionId": "pub-001",
+  "artifactId": "demo-report",
+  "knowledge": "open",
+  "value": "restricted",
+  "ecosystem": "open",
+  "decidedAt": "2026-04-18T01:33:00Z"
+}

examples/run-report.json

@@ -0,0 +1,7 @@
+{
+  "runId": "run-001",
+  "workflowId": "wf-search-summarize",
+  "artifacts": ["demo-report", "demo-report.signed.pdf"],
+  "generatedAt": "2026-04-18T01:31:00Z",
+  "summary": "Search and summarize run completed successfully."
+}

schemas/AnnotationExport.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:srcos:schema:AnnotationExport",
+  "title": "AnnotationExport",
+  "type": "object",
+  "required": ["exportId", "target", "format", "annotations"],
+  "properties": {
+    "exportId": {"type": "string"},
+    "target": {"type": "string"},
+    "format": {"type": "string", "enum": ["w3c-web-annotation", "rdf-jsonld"]},
+    "annotations": {"type": "array", "items": {"type": "object"}},
+    "exportedAt": {"type": ["string", "null"], "format": "date-time"}
+  },
+  "additionalProperties": false
+}

schemas/MirrorReceipt.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:srcos:schema:MirrorReceipt",
+  "title": "MirrorReceipt",
+  "type": "object",
+  "required": ["receiptId", "artifactId", "channel", "status"],
+  "properties": {
+    "receiptId": {"type": "string"},
+    "artifactId": {"type": "string"},
+    "channel": {"type": "string"},
+    "status": {"type": "string"},
+    "mirroredAt": {"type": ["string", "null"], "format": "date-time"},
+    "detail": {"type": ["string", "null"]}
+  },
+  "additionalProperties": false
+}

schemas/NoetherDiagnostic.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:srcos:schema:NoetherDiagnostic",
+  "title": "NoetherDiagnostic",
+  "type": "object",
+  "required": ["diagnosticId", "layer", "charge", "value", "measuredAt"],
+  "properties": {
+    "diagnosticId": {"type": "string"},
+    "layer": {"type": "string"},
+    "charge": {"type": "string"},
+    "value": {"type": "number"},
+    "measuredAt": {"type": "string", "format": "date-time"},
+    "tolerance": {"type": ["number", "null"]},
+    "pass": {"type": ["boolean", "null"]}
+  },
+  "additionalProperties": false
+}

schemas/PublishDecision.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:srcos:schema:PublishDecision",
+  "title": "PublishDecision",
+  "type": "object",
+  "required": ["decisionId", "artifactId", "knowledge", "value", "ecosystem"],
+  "properties": {
+    "decisionId": {"type": "string"},
+    "artifactId": {"type": "string"},
+    "knowledge": {"type": "string", "enum": ["open", "restricted", "sealed"]},
+    "value": {"type": "string", "enum": ["open", "restricted", "sealed"]},
+    "ecosystem": {"type": "string", "enum": ["open", "restricted", "sealed"]},
+    "decidedAt": {"type": ["string", "null"], "format": "date-time"}
+  },
+  "additionalProperties": false
+}

schemas/RunReport.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:srcos:schema:RunReport",
+  "title": "RunReport",
+  "type": "object",
+  "required": ["runId", "workflowId", "artifacts", "generatedAt"],
+  "properties": {
+    "runId": {"type": "string"},
+    "workflowId": {"type": "string"},
+    "artifacts": {"type": "array", "items": {"type": "string"}},
+    "generatedAt": {"type": "string", "format": "date-time"},
+    "summary": {"type": ["string", "null"]}
+  },
+  "additionalProperties": false
+}