feat/sourceos-shell-api-events

README.md

@@ -36,6 +36,7 @@ sourceos-spec/
 ├── asyncapi.agent-plane.patch.yaml   # Agent-plane event channels
 ├── asyncapi.fog.patch.yaml           # Fog-layer event channels
 │
+├── schemas/                          # 64 JSON Schema (draft 2020-12) files
 ├── schemas/                          # Top-level JSON Schema files (draft 2020-12)
 │   └── README.md                     # Schema catalog and URN patterns
 │
@@ -110,19 +111,21 @@ python tools/validate_interaction_flow_reference.py
 
 ## Schema families
 
+The current schema set is organised into families that map directly to the platform layers and exchange surfaces:
 The schemas are organised into domain-oriented families that map to the SourceOS / SociOS contract surface:
 
 | # | Family | Key schemas |
 |---|--------|-------------|
 | 1 | **Physical Assets** | `Connector`, `PhysicalAsset` |
 | 2 | **Glossary** | `GlossaryTerm`, `AuthorityLink` |
 | 3 | **Governance** | `Policy`, `Rule`, `PolicyCondition`, `PolicyDecision`, `CapabilityToken`, `Obligation`, `Exception` |
-| 4 | **Collaboration** | `Comment`, `Rating`, `Community` |
+| 4 | **Collaboration** | `Comment`, `Rating`, `Community`, `CommentSignal` |
 | 5 | **Models / Schemas** | `SchemaDefinition`, `EntityField`, `Field`, `ValidValues`, `TagAssignment`, `QualityMetric`, `ProfileStats` |
 | 6 | **Agreements** | `Agreement`, `Party` |
 | + | **Execution / Provenance** | `Dataset`, `RunRecord`, `WorkflowSpec`, `WorkflowNode`, `WorkflowEdge`, `WorkloadSpec`, `DataSphere`, `ProvenanceRecord`, `EventEnvelope`, `MappingSpec` |
 | + | **Agent Plane** | `AgentSession`, `ExecutionDecision`, `ExecutionSurface`, `SkillManifest`, `MemoryEntry`, `SessionReceipt`, `SessionReview`, `TelemetryEvent`, `FrustrationSignal` |
 | + | **Release / Experiments** | `ExperimentFlag`, `RolloutPolicy`, `ReleaseReceipt` |
+| + | **Shell / Document / Publication** | `ArtifactManifest`, `SignedArtifact`, `PdfValidationReport`, `AnnotationExport`, `RunReport`, `NoetherDiagnostic`, `PublishDecision`, `MirrorReceipt`, `SearchRouteDecision` |
 | + | **Fog Layer** | `Topic`, `TopicEnvelope`, `ReplicationPolicy`, `ContentRef`, `Offer`, `WorkOrder`, `UsageReceipt`, `SettlementEvent` |
 | + | **Agentic Graph Foundation** | `SourceOSRepoManifest`, `SyncEngineManifest`, `SourceChannelEnvelope`, `SourceGraphWrite`, `AgentCapabilityLease`, `AuditEvent` |
 | + | **Interaction Substrate** | `SourceOSInteractionEvent` |

examples/README.md

@@ -6,6 +6,9 @@ This directory contains one conforming JSON example payload for each top-level s
 
 ## What the examples show
 
+The examples are designed to tell a coherent end-to-end story: a personal health dataset is catalogued, governed, transformed by an obfuscation workload, and released — all within an agent session. They share cross-reference URNs so you can trace the full lifecycle.
+
+The example set now also includes shell/document/publication objects so the same storyline can extend into artifact derivation, signing, validation, annotation export, run reporting, publish decisions, and mirror receipts.
 The examples are designed to tell coherent end-to-end stories. The original example set catalogs, governs, transforms, and releases a personal health dataset within an agent session. Newer SourceOS examples show a SourceOS Workstation artifact flowing from content intent through overlays, build request, release manifest, evidence bundle, catalog entry, and access profile. The control-plane examples add the local-first lifecycle proof path: a `ReleaseSet` assigned to an M2 demo device, a `BootReleaseSet` for the recovery/provisioning lane, an `EnrollmentToken` authorizing one-time recovery access, and a `Fingerprint` reporting the realized post-apply state. Compression Commons examples add an artifact-versus-baseline evaluation record that references existing governance, execution, provenance, and content-reference contracts. SourceOS Interaction examples add the noetic/chat/task event projection shared by Noetica and AgentTerm.
 
 Desktop/workstation examples may include bounded Mac-on-Linux polish metadata. These are contract signals only: concrete implementation authority remains in `SociOS-Linux/source-os`, and the examples do not claim full macOS parity.
@@ -40,6 +43,14 @@ agent_session.json  ──►  execution_decision.json  ──►  session_recei
                                                           ▼
                                                    session_review.json
 
+artifact-manifest.json  ──►  signed-artifact.json
+         │                          │
+         ▼                          ▼
+pdf-validation-report.json    publish-decision.json
+         │                          │
+         └──────────────► mirror-receipt.json
+
+annotation-export.json ──► run-report.json ──► noether-diagnostic.json
 sourceos-interaction-event.json ──► Noetica / AgentTerm governance trace
 
 content_spec.json ──► overlay_bundle.json ──► build_request.json ──► release_manifest.json
@@ -157,13 +168,16 @@ These examples illustrate the shared object family used by SourceOS artifact bui
 | `access_profile.json` | AccessProfile | Access profile for SourceOS build operators and agentplane executor obligations |
 | `agreement.json` | Agreement | Default personal-data agreement |
 | `agent_session.json` | AgentSession | An executor session running the obfuscation workflow |
+| `annotation-export.json` | AnnotationExport | Export bundle for annotations captured from review surfaces |
+| `artifact-manifest.json` | ArtifactManifest | Manifest describing a derived shell/document artifact |
 | `apple_silicon_adapter_evidence.json` | AppleSiliconAdapterEvidence | Apple Silicon adapter evidence for an M2 device running SourceOS via Asahi |
 | `artifact_cache_record.json` | ArtifactCacheRecord | Cached Linux kernel artifact for the M2 demo device |
 | `asset.json` | PhysicalAsset | Lakehouse asset for curated health observations |
 | `boot_proof_record.json` | BootProofRecord | Verified boot proof for SourceOS M2 device via NLBoot Asahi path |
 | `boot_release_set.json` | BootReleaseSet | SourceOS Recovery Environment boot artifact set for secure recovery/provisioning |
 | `build_request.json` | BuildRequest | SourceOS Workstation build request with agentplane and Katello refs |
 | `capability_token.json` | CapabilityToken | Access token scoped to the health dataset export operation |
+| `comment-signal.json` | CommentSignal | Example author/reviewer signal payload |
 | `catalog_entry.json` | CatalogEntry | Catalog entry for the SourceOS Workstation dev release |
 | `comment.json` | Comment | A review note on a field mapping |
 | `community.json` | Community | The data-governance team community |
@@ -186,22 +200,29 @@ These examples illustrate the shared object family used by SourceOS artifact bui
 | `glossary.json` | GlossaryTerm | Glossary term for "Date of Birth" |
 | `mapping.json` | MappingSpec | A field mapping between two dataset fields |
 | `memory_entry.json` | MemoryEntry | A learned memory entry from an agent session |
+| `mirror-receipt.json` | MirrorReceipt | Receipt for a mirrored artifact publication |
+| `noether-diagnostic.json` | NoetherDiagnostic | Example conservation/invariance diagnostic reading |
+| `pdf-validation-report.json` | PdfValidationReport | Validation results for a derived PDF artifact |
 | `nlboot_plan.json` | NLBootPlan | NLBoot boot plan for SourceOS M2 demo device via Asahi path |
 | `offer.json` | Offer | FogCompute provider offer |
 | `overlay_bundle.json` | OverlayBundle | Customer branding overlay applied to the workstation flavor |
 | `policy.json` | Policy | Health export must be obfuscated |
 | `policy_decision.json` | PolicyDecision | An `export` permit decision with an obfuscation obligation |
 | `provenance.json` | ProvenanceRecord | Provenance record for the obfuscation run |
+| `publish-decision.json` | PublishDecision | Publish-lane decision across openness dimensions |
 | `rating.json` | Rating | A 5-star rating on the health observations dataset |
 | `release_manifest.json` | ReleaseManifest | Draft release manifest with Katello artifact refs and agentplane evidence refs |
 | `release_receipt.json` | ReleaseReceipt | Release receipt for spec version 2.0.0 |
 | `release_set.json` | ReleaseSet | Assigned M2 demo release set with source, targets, profile refs, and artifact refs |
 | `replication_policy.json` | ReplicationPolicy | Fog topic replication/retention policy example |
 | `rollout_policy.json` | RolloutPolicy | Rollout rules for the obfuscation experiment flag |
+| `run-report.json` | RunReport | Publication-oriented summary of a completed run |
 | `run.json` | RunRecord | The obfuscation workload run record |
 | `schema.json` | SchemaDefinition | The schema for health observations |
+| `search-route-decision.json` | SearchRouteDecision | Scope-based shell routing decision |
 | `session_receipt.json` | SessionReceipt | Receipt for the completed agent session |
 | `session_review.json` | SessionReview | Post-session learning review |
+| `signed-artifact.json` | SignedArtifact | Signature metadata for a signed artifact |
 | `settlement_event.json` | Optional receipt-to-settlement mapping |
 | `skill_manifest.json` | SkillManifest | The obfuscation skill manifest |
 | `sourceos-interaction-event.json` | SourceOSInteractionEvent | Noetica standalone provider completion event with governance trace fields consumable by AgentTerm |
@@ -233,6 +254,7 @@ make validate-control-plane-examples
 ## Adding a new example
 
 See [CONTRIBUTING.md](../CONTRIBUTING.md#writing-examples) for the full guide. Key rules:
+1. The filename must be the schema `title` lowercased or the established example naming convention, e.g. `AgentSession` → `agent_session.json`.
 1. The filename should match the schema title in the repository’s naming convention.
 2. All required fields must be present and valid.
 3. Use coherent cross-reference URNs where possible so the example set stays navigable.

schemas/README.md

@@ -1,5 +1,6 @@
 # Schema Catalog
 
+This directory contains all 64 JSON Schema (draft 2020-12) files that make up the SourceOS/SociOS Typed Contracts specification.
 This directory contains the JSON Schema (draft 2020-12) files that make up the SourceOS/SociOS Typed Contracts specification.
 
 ---
@@ -87,12 +88,15 @@ These types support:
 |------|------|-----------|
 | `AgentSession.json` | AgentSession | `urn:srcos:session:` |
 | `Agreement.json` | Agreement | `urn:srcos:agreement:` |
+| `AnnotationExport.json` | AnnotationExport | `urn:srcos:schema:AnnotationExport` |
+| `ArtifactManifest.json` | ArtifactManifest | `urn:srcos:schema:ArtifactManifest` |
 | `AppleSiliconAdapterEvidence.json` | AppleSiliconAdapterEvidence | `urn:srcos:as-adapter-evidence:` |
 | `ArtifactCacheRecord.json` | ArtifactCacheRecord | `urn:srcos:artifact-cache:` |
 | `AuthorityLink.json` | AuthorityLink | _(sub-object, no top-level id)_ |
 | `BootProofRecord.json` | BootProofRecord | `urn:srcos:boot-proof:` |
 | `CapabilityToken.json` | CapabilityToken | _(plain `tokenId` string)_ |
 | `Comment.json` | Comment | `urn:srcos:comment:` |
+| `CommentSignal.json` | CommentSignal | `urn:srcos:schema:CommentSignal` |
 | `Community.json` | Community | `urn:srcos:community:` |
 | `CompressionEvaluation.json` | CompressionEvaluation | `urn:srcos:compression-eval:` |
 | `ConfigSource.json` | ConfigSource | `urn:srcos:config-source:` |
@@ -120,20 +124,24 @@ These types support:
 | `MappingEvidence.json` | MappingEvidence | _(sub-object inside MappingSpec)_ |
 | `MappingSpec.json` | MappingSpec | `urn:srcos:mapping:` |
 | `MemoryEntry.json` | MemoryEntry | `urn:srcos:memory:` |
+| `MirrorReceipt.json` | MirrorReceipt | `urn:srcos:schema:MirrorReceipt` |
+| `NoetherDiagnostic.json` | NoetherDiagnostic | `urn:srcos:schema:NoetherDiagnostic` |
 | `NLBootPlan.json` | NLBootPlan | `urn:srcos:nlboot-plan:` |
 | `ObjectContext.json` | ObjectContext | _(sub-object, no id)_ |
 | `ObjectSelector.json` | ObjectSelector | _(sub-object inside Policy scope)_ |
 | `Obligation.json` | Obligation | _(sub-object, no id)_ |
 | `Offer.json` | Offer | `urn:srcos:offer:` |
 | `PackageManifest.json` | PackageManifest | `urn:srcos:package-manifest:` |
 | `Party.json` | Party | `urn:srcos:party:` |
+| `PdfValidationReport.json` | PdfValidationReport | `urn:srcos:schema:PdfValidationReport` |
 | `PhysicalAsset.json` | PhysicalAsset | `urn:srcos:asset:` |
 | `Policy.json` | Policy | `urn:srcos:policy:` |
 | `PolicyBinding.json` | PolicyBinding | _(sub-object inside WorkflowSpec)_ |
 | `PolicyCondition.json` | PolicyCondition | _(sub-object inside Rule)_ |
 | `PolicyDecision.json` | PolicyDecision | `urn:srcos:decision:` |
 | `ProfileStats.json` | ProfileStats | _(sub-object inside Field.quality)_ |
 | `ProvenanceRecord.json` | ProvenanceRecord | `urn:srcos:prov:` |
+| `PublishDecision.json` | PublishDecision | `urn:srcos:schema:PublishDecision` |
 | `QualityMetric.json` | QualityMetric | _(sub-object inside Field.quality)_ |
 | `Rating.json` | Rating | `urn:srcos:rating:` |
 | `ReleaseManifest.json` | ReleaseManifest | `urn:srcos:release:` |
@@ -143,9 +151,12 @@ These types support:
 | `RolloutPolicy.json` | RolloutPolicy | `urn:srcos:rollout:` |
 | `Rule.json` | Rule | _(sub-object inside Policy)_ |
 | `RunRecord.json` | RunRecord | `urn:srcos:run:` |
+| `RunReport.json` | RunReport | `urn:srcos:schema:RunReport` |
 | `SchemaDefinition.json` | SchemaDefinition | `urn:srcos:schema:` |
+| `SearchRouteDecision.json` | SearchRouteDecision | `urn:srcos:schema:SearchRouteDecision` |
 | `SessionReceipt.json` | SessionReceipt | `urn:srcos:receipt:session:` |
 | `SessionReview.json` | SessionReview | `urn:srcos:session-review:` |
+| `SignedArtifact.json` | SignedArtifact | `urn:srcos:schema:SignedArtifact` |
 | `SettlementEvent.json` | SettlementEvent | `urn:srcos:settlement:` |
 | `SkillManifest.json` | SkillManifest | `urn:srcos:skill:` |
 | `SourceOSInteractionEvent.json` | SourceOSInteractionEvent | `urn:srcos:interaction-event:` |
@@ -205,6 +216,7 @@ These types support:
 | Schema | Description |
 |--------|-------------|
 | `Comment` | A free-text annotation on any addressable object |
+| `CommentSignal` | A reviewer or author signal payload exposing genuine/sarcasm/experience state |
 | `Rating` | A 1–5 star rating on any addressable object |
 | `Community` | A named group of subject URNs |
 
@@ -281,6 +293,19 @@ These types support:
 | `RolloutPolicy` | Audience-based percentage rollout rules for an `ExperimentFlag` |
 | `ReleaseReceipt` | A verified release record with artifact hashes and gate check results |
 
+### Shell / Document / Publication
+
+| Schema | Description |
+|--------|-------------|
+| `ArtifactManifest` | Canonical manifest for a derived shell/document artifact |
+| `SignedArtifact` | Signature metadata associated with a signed artifact |
+| `PdfValidationReport` | Validation report produced for a derived PDF artifact |
+| `AnnotationExport` | Export bundle for PDF/HTML review annotations |
+| `RunReport` | Publication-ready summary of a workflow or execution run |
+| `NoetherDiagnostic` | Measured conservation or invariance reading for a declared model charge |
+| `PublishDecision` | Publish-lane decision across knowledge/value/ecosystem openness |
+| `MirrorReceipt` | Receipt showing artifact mirroring outcome for a downstream channel |
+| `SearchRouteDecision` | Routing decision for scope-based shell search dispatch |
 ### Boot / NLBoot
 
 | Schema | Description |