schemas: KnowledgeNugget + SemanticAction v0.1 — L2 content grain + typed-action registry

CHANGELOG.md

@@ -9,6 +9,8 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Thi
 ## [Unreleased]
 
 ### Added
+- KnowledgeNugget contract v0.1 (the estate's L2 content grain): warrant-typed knowledge fragments generalizing the production IFM warrant-typed extraction — content-addressed source spans (`docRef` + span + `sha256-` content hash), a closed four-kind warrant taxonomy (`direct-quote`/`computed`/`inferred`/`model-generated`) with evidence refs and confidence, ontology type refs (`kkoTypeRefs`), normalized `canonicalPayload`, typed provenance chain links, and `wallTime`/`logicalTime` carried verbatim from the MPCC `ConversationEvent` envelope (parity machine-enforced). Normative: `model-generated` nuggets MUST stay visibly distinguishable downstream (admissibility discounting), and `computed`/`inferred` warrants must cite evidence (schema-enforced). Includes direct-quote and model-generated examples, negative conformance vectors (`fixtures/knowledge-nugget/conformance.json`), a `validate-knowledge-nugget-examples` target, and a normative spec note (`specs/knowledge-nugget-contract.md`).
+- SemanticAction contract v0.1 (the declarative typed-action registry for the NL→plan compiler): ontology-typed inputs and output (KKO concept URIs recommended, shared with `KnowledgeNugget.kkoTypeRefs`), a closed constraint taxonomy (`subClassOf`/`instanceOf`/`sameAs` — polymorphism via subsumption), executor binding, registry metadata (owner + deprecated), and a two-value effect posture: actions are side-effect-free at plan-search time, and `sideEffects: "effect-request"` declares the executor emits an MPCC `EffectRequest` and defers to an `EffectDecision` rather than acting directly — no direct-mutation vocabulary exists (validator-pinned). Includes pure-lookup and effect-request examples, negative conformance vectors (`fixtures/semantic-action/conformance.json`), a `validate-semantic-action-examples` target, and a normative spec note (`specs/semantic-action-contract.md`).
 - MPCC event contract v0.1 (conversation + trading event family): `ConversationEvent` (the canonical 26-field conversation-fabric event — causal parents, authority context with delegation chain, visibility scope, requested/approved/actual effect references, modality, speech act), `EffectRequest` / `EffectDecision` / `EffectRecord` (the requested → approved → actual → compensated effect lifecycle with idempotency keys, referencing `PolicyDecision` / `ExecutionDecision` rather than duplicating them), `NullAbsenceRecord` (12-kind null/absence taxonomy), and the trading families `MarketDataEvent`, `OrderIntent`, `ExecutionReport`, `PositionChange`, `ReconciliationRecord` as profiles of the ConversationEvent envelope (one shared envelope vocabulary; parity machine-enforced). Includes canonical examples telling one end-to-end governed trade story, negative conformance vectors (`fixtures/mpcc-event-contract/conformance.json`), a `validate-mpcc-event-examples` target, and a normative spec note (`specs/mpcc-event-contract.md`). Provenance: SocioProphet/profit-mpcc, hardened to the policy-integrity tranche-0001 strictness bar.
 - Epistemic Assay contracts: `ReasoningAssay` (a typed verdict on a claim over five orthogonal axes — method, binding, verifier, agreement, authority — whose `ok`/`sad`/`bad` `projectedState` is a render-time projection, not a stored scalar) and `AssayStandard` (a verifier's measured, versioned reliability — the calibration reference every assay must point at). Includes canonical `ok`/`sad`/`bad` examples, ADR (`docs/adr/ADR-epistemic-assay-verdict-v0-1.md`), and a `validate-reasoning-examples` target that also enforces projection soundness (recomputes `assay()` from the stored axes and fails on drift) and retroactively brings the existing reasoning family under `make validate`.
 - `ReasoningReceipt.assay` (optional) — the reserved receipt landing spot for the Assay: a render-time, run-level epistemic summary that references its run's `ReasoningAssay` records by URN (`assayRefs`) and surfaces the projected `overallState`, weakest-link `binding`, verifier `calibrationRef`, per-state `counts`, and `projectedAt`. A cache of the referenced verdicts, not authoritative over them — re-projectable when an `AssayStandard` improves. Backward-compatible (optional field). The assay's `authority` axis continues to mirror `EventEnvelope.actor`/`integrity`, so the envelope needs no structural change.

Makefile

@@ -1,8 +1,16 @@
-.PHONY: validate validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples validate-reasoning-examples validate-mpcc-event-examples
+.PHONY: validate validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples validate-reasoning-examples validate-mpcc-event-examples validate-knowledge-nugget-examples validate-semantic-action-examples
 
-validate: validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples validate-reasoning-examples validate-mpcc-event-examples
+validate: validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples validate-reasoning-examples validate-mpcc-event-examples validate-knowledge-nugget-examples validate-semantic-action-examples
 	@echo "OK: validate"
 
+validate-knowledge-nugget-examples:
+	python3 -m pip install --user jsonschema >/dev/null
+	python3 tools/validate_knowledge_nugget_examples.py
+
+validate-semantic-action-examples:
+	python3 -m pip install --user jsonschema >/dev/null
+	python3 tools/validate_semantic_action_examples.py
+
 validate-mpcc-event-examples:
 	python3 -m pip install --user jsonschema >/dev/null
 	python3 tools/validate_mpcc_event_examples.py

examples/knowledge_nugget.json

@@ -0,0 +1,49 @@
+{
+ "id": "urn:srcos:knowledge-nugget:gyg_fy2025_network_sales_quote_0001",
+ "type": "KnowledgeNugget",
+ "specVersion": "0.1.0",
+ "sourceRef": {
+ "docRef": "urn:srcos:dataset:gyg_asx_fy2025_annual_report",
+ "span": {
+ "start": 48210,
+ "end": 48323,
+ "page": 74
+ },
+ "contentHash": "sha256-0d863a1cca056ffe7948415a29d795c2581fbfcda7e3e30f544cd078333d1337"
+ },
+ "warrant": {
+ "type": "direct-quote",
+ "evidence": [
+ "urn:srcos:prov:ifm_extract_run_000412"
+ ],
+ "confidence": 0.99
+ },
+ "text": "Network sales grew 22.6% to $1,138.9 million, with comparable sales growth of 9.4% across the Australian segment.",
+ "kkoTypeRefs": [
+ "http://kbpedia.org/kko/rc/Business",
+ "https://schemas.srcos.ai/ont/ifm/FilingMetricObservation"
+ ],
+ "canonicalPayload": {
+ "metric": "network_sales",
+ "value": 1138900000,
+ "unit": "AUD",
+ "growthPct": 22.6,
+ "normalizationRegime": "ifm-metric-v1"
+ },
+ "provenance": [
+ {
+ "rel": "derived_from",
+ "ref": "urn:srcos:dataset:gyg_asx_fy2025_annual_report"
+ },
+ {
+ "rel": "extracted_by",
+ "ref": "urn:srcos:run:ifm_extract_run_000412"
+ }
+ ],
+ "policyLabels": [
+ "source:public-filing"
+ ],
+ "createdBy": "urn:srcos:agent:ifm_extractor_v2",
+ "wallTime": "2026-07-29T09:15:00.000Z",
+ "logicalTime": 4021
+}

examples/knowledge_nugget.model_generated.json

@@ -0,0 +1,39 @@
+{
+ "id": "urn:srcos:knowledge-nugget:gyg_fy2026_outlook_synthesis_0007",
+ "type": "KnowledgeNugget",
+ "specVersion": "0.1.0",
+ "sourceRef": {
+ "docRef": "urn:srcos:dataset:gyg_asx_fy2025_annual_report",
+ "span": {
+ "start": 46800,
+ "end": 52400,
+ "page": 73
+ },
+ "contentHash": "sha256-b8b7fefebb4e8f612ea0a89fd6f465a9c0e57a09630ce7c565e9c5de86a7fc92"
+ },
+ "warrant": {
+ "type": "model-generated",
+ "evidence": [],
+ "confidence": 0.62
+ },
+ "text": "Management appears to expect continued store rollout to sustain double-digit network sales growth into FY2026.",
+ "kkoTypeRefs": [
+ "http://kbpedia.org/kko/rc/Business"
+ ],
+ "provenance": [
+ {
+ "rel": "conditioned_on",
+ "ref": "urn:srcos:dataset:gyg_asx_fy2025_annual_report"
+ },
+ {
+ "rel": "generated_by",
+ "ref": "urn:srcos:run:ifm_synthesis_run_000413"
+ }
+ ],
+ "policyLabels": [
+ "source:public-filing"
+ ],
+ "createdBy": "urn:srcos:agent:ifm_synthesizer_v1",
+ "wallTime": "2026-07-29T09:16:30.000Z",
+ "logicalTime": 4022
+}

examples/semantic_action.effect_request.json

@@ -0,0 +1,38 @@
+{
+ "id": "urn:srcos:semantic-action:trading_place_order_1.2.0",
+ "type": "SemanticAction",
+ "specVersion": "0.1.0",
+ "name": "trading.place_order",
+ "version": "1.2.0",
+ "inputs": [
+ {
+ "name": "instrument",
+ "typeRef": "http://kbpedia.org/kko/rc/FinancialInstrument",
+ "required": true,
+ "cardinality": "one"
+ },
+ {
+ "name": "orderParameters",
+ "typeRef": "https://schemas.srcos.ai/ont/trading/OrderParameters",
+ "required": true,
+ "cardinality": "one"
+ }
+ ],
+ "output": {
+ "typeRef": "https://schemas.srcos.ai/v2/EffectRequest.json",
+ "cardinality": "one"
+ },
+ "constraints": [
+ {
+ "kind": "subClassOf",
+ "subject": "output",
+ "typeRef": "https://schemas.srcos.ai/v2/EffectRequest.json"
+ }
+ ],
+ "executorRef": "urn:srcos:skill:trading_order_gateway_adapter",
+ "sideEffects": "effect-request",
+ "registry": {
+ "owner": "urn:srcos:party:desk_alpha_ops",
+ "deprecated": false
+ }
+}

examples/semantic_action.json

@@ -0,0 +1,44 @@
+{
+ "id": "urn:srcos:semantic-action:kb_lookup_filing_metric_1.0.0",
+ "type": "SemanticAction",
+ "specVersion": "0.1.0",
+ "name": "kb.lookup_filing_metric",
+ "version": "1.0.0",
+ "inputs": [
+ {
+ "name": "company",
+ "typeRef": "http://kbpedia.org/kko/rc/Business",
+ "required": true,
+ "cardinality": "one"
+ },
+ {
+ "name": "metric",
+ "typeRef": "https://schemas.srcos.ai/ont/ifm/FilingMetricKind",
+ "required": true,
+ "cardinality": "one"
+ },
+ {
+ "name": "period",
+ "typeRef": "https://schemas.srcos.ai/ont/ifm/FiscalPeriod",
+ "required": false,
+ "cardinality": "one"
+ }
+ ],
+ "output": {
+ "typeRef": "https://schemas.srcos.ai/ont/ifm/FilingMetricObservation",
+ "cardinality": "many"
+ },
+ "constraints": [
+ {
+ "kind": "subClassOf",
+ "subject": "company",
+ "typeRef": "http://kbpedia.org/kko/rc/Organization"
+ }
+ ],
+ "executorRef": "urn:srcos:skill:ifm_filing_metric_lookup",
+ "sideEffects": "none",
+ "registry": {
+ "owner": "urn:srcos:party:ifm_platform_team",
+ "deprecated": false
+ }
+}

fixtures/knowledge-nugget/conformance.json

@@ -0,0 +1,106 @@
+{
+ "description": "Negative conformance vectors for the KnowledgeNugget contract v0.1. Each document MUST FAIL validation against its schema for the stated reason; tools/validate_knowledge_nugget_examples.py enforces this. These vectors keep the content-grain bar executable: closed objects, pinned contract version, a closed warrant taxonomy, content-addressed sources, and the derivation-grounding invariant (computed/inferred warrants must cite evidence).",
+ "cases": [
+ {
+ "schema": "KnowledgeNugget.json",
+ "reason": "Unknown top-level property must be rejected (additionalProperties: false).",
+ "document": {
+ "id": "urn:srcos:knowledge-nugget:neg_unknown_prop",
+ "type": "KnowledgeNugget",
+ "specVersion": "0.1.0",
+ "sourceRef": {
+ "docRef": "urn:srcos:dataset:gyg_asx_fy2025_annual_report",
+ "span": { "start": 10, "end": 20 },
+ "contentHash": "sha256-0d863a1cca056ffe7948415a29d795c2581fbfcda7e3e30f544cd078333d1337"
+ },
+ "warrant": { "type": "direct-quote", "evidence": [], "confidence": 0.9 },
+ "text": "spanselect",
+ "policyLabels": [],
+ "createdBy": "urn:srcos:agent:ifm_extractor_v2",
+ "wallTime": "2026-07-29T09:15:00.000Z",
+ "logicalTime": 4021,
+ "vibeScore": 11
+ }
+ },
+ {
+ "schema": "KnowledgeNugget.json",
+ "reason": "The warrant taxonomy is closed: warrant types outside the four-kind enum must fail.",
+ "document": {
+ "id": "urn:srcos:knowledge-nugget:neg_unknown_warrant_kind",
+ "type": "KnowledgeNugget",
+ "specVersion": "0.1.0",
+ "sourceRef": {
+ "docRef": "urn:srcos:dataset:gyg_asx_fy2025_annual_report",
+ "span": { "start": 10, "end": 20 },
+ "contentHash": "sha256-0d863a1cca056ffe7948415a29d795c2581fbfcda7e3e30f544cd078333d1337"
+ },
+ "warrant": { "type": "hearsay", "evidence": [], "confidence": 0.5 },
+ "text": "spanselect",
+ "policyLabels": [],
+ "createdBy": "urn:srcos:agent:ifm_extractor_v2",
+ "wallTime": "2026-07-29T09:15:00.000Z",
+ "logicalTime": 4021
+ }
+ },
+ {
+ "schema": "KnowledgeNugget.json",
+ "reason": "Derivation grounding: an inferred warrant with empty evidence must fail (computed/inferred require at least one evidence ref).",
+ "document": {
+ "id": "urn:srcos:knowledge-nugget:neg_ungrounded_inference",
+ "type": "KnowledgeNugget",
+ "specVersion": "0.1.0",
+ "sourceRef": {
+ "docRef": "urn:srcos:dataset:gyg_asx_fy2025_annual_report",
+ "span": { "start": 10, "end": 20 },
+ "contentHash": "sha256-0d863a1cca056ffe7948415a29d795c2581fbfcda7e3e30f544cd078333d1337"
+ },
+ "warrant": { "type": "inferred", "evidence": [], "confidence": 0.8 },
+ "text": "Segment growth implies store-level margins expanded.",
+ "policyLabels": [],
+ "createdBy": "urn:srcos:agent:ifm_extractor_v2",
+ "wallTime": "2026-07-29T09:15:00.000Z",
+ "logicalTime": 4021
+ }
+ },
+ {
+ "schema": "KnowledgeNugget.json",
+ "reason": "Content addressing is sha256-only: a non-sha256 contentHash must fail the anchored pattern.",
+ "document": {
+ "id": "urn:srcos:knowledge-nugget:neg_weak_content_hash",
+ "type": "KnowledgeNugget",
+ "specVersion": "0.1.0",
+ "sourceRef": {
+ "docRef": "urn:srcos:dataset:gyg_asx_fy2025_annual_report",
+ "span": { "start": 10, "end": 20 },
+ "contentHash": "md5-d41d8cd98f00b204e9800998ecf8427e"
+ },
+ "warrant": { "type": "direct-quote", "evidence": [], "confidence": 0.9 },
+ "text": "spanselect",
+ "policyLabels": [],
+ "createdBy": "urn:srcos:agent:ifm_extractor_v2",
+ "wallTime": "2026-07-29T09:15:00.000Z",
+ "logicalTime": 4021
+ }
+ },
+ {
+ "schema": "KnowledgeNugget.json",
+ "reason": "specVersion is pinned: any value other than the 0.1.0 const must fail.",
+ "document": {
+ "id": "urn:srcos:knowledge-nugget:neg_wrong_spec_version",
+ "type": "KnowledgeNugget",
+ "specVersion": "0.2.0",
+ "sourceRef": {
+ "docRef": "urn:srcos:dataset:gyg_asx_fy2025_annual_report",
+ "span": { "start": 10, "end": 20 },
+ "contentHash": "sha256-0d863a1cca056ffe7948415a29d795c2581fbfcda7e3e30f544cd078333d1337"
+ },
+ "warrant": { "type": "direct-quote", "evidence": [], "confidence": 0.9 },
+ "text": "spanselect",
+ "policyLabels": [],
+ "createdBy": "urn:srcos:agent:ifm_extractor_v2",
+ "wallTime": "2026-07-29T09:15:00.000Z",
+ "logicalTime": 4021
+ }
+ }
+ ]
+}