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

[mdheller]

What changed

Two spec-first contract families feeding platform Waves 6 and 7, held to the exact bar exercised by the MPCC event contract (#204): additionalProperties: false on every object, specVersion pinned to the 0.1.0 const, anchored urn:srcos: id patterns, type const == title, fixtures-backed negative vectors, per-family validator wired into make validate, schemas/README.md "Recent additions" section, CHANGELOG entry, and a normative spec note per family.

KnowledgeNugget (schemas/KnowledgeNugget.json, urn:srcos:knowledge-nugget:) — the estate's L2 content grain, generalizing the production IFM warrant-typed extraction:

• sourceRef = doc URN + character span (+ optional page) + sha256-<64hex> content hash, required for every warrant type (a model-generated nugget must still pin its conditioning window).
• Closed warrant taxonomy direct-quote | computed | inferred | model-generated + evidence refs + confidence 0..1. Normative: model-generated MUST stay visibly distinguishable downstream (admissibility discounting); computed/inferred must cite ≥1 evidence ref (schema-enforced if/then); a direct-quote span must be exactly as long as its text (validator-enforced).
• kkoTypeRefs (ontology concept URIs), canonicalPayload, typed {rel, ref} provenance chain links, policyLabels (required, empty allowed, per the tranche-0001 bar), createdBy actorRef, and wallTime/logicalTimebyte-identical to the ConversationEvent envelope, parity machine-enforced (same discipline as the MPCC trading profiles).

SemanticAction (schemas/SemanticAction.json, urn:srcos:semantic-action:) — the declarative typed-action registry for the NL→plan compiler:

• Ontology-typed inputs[]/output (fully declared slots: name/typeRef/required/cardinality one|many), closed constraint taxonomy subClassOf | instanceOf | sameAs (polymorphism via subsumption; subjects resolve to input names or "output", validator-enforced), executorRef URN, registry metadata (owner + deprecated).
• Search-time purity (normative): actions are side-effect-free at plan-search time.sideEffects is exactly "none" | "effect-request" — "effect-request" declares the executor emits an EffectRequest and defers to an EffectDecision (decision before action) rather than acting directly. No "direct" value exists; the validator pins the enum so one can never land silently, and the canonical effect-request example's output is typed by the EffectRequest contract URI itself.

Support files: 2+2 canonical examples (direct-quote vs model-generated; pure lookup vs effect-request), negative vectors in fixtures/knowledge-nugget/conformance.json + fixtures/semantic-action/conformance.json (5 each), validators tools/validate_knowledge_nugget_examples.py + tools/validate_semantic_action_examples.py, Makefile targets validate-knowledge-nugget-examples + validate-semantic-action-examples added to validate, specs specs/knowledge-nugget-contract.md + specs/semantic-action-contract.md (incl. overlap-decision tables: ProvenanceRecord/MemoryEntry/ContentRef/ReasoningAssay and SkillManifest/LauncherAction/WorkflowSpec/Effect lifecycle are referenced, not duplicated).

Exact commands run

make validate
python3 tools/validate_knowledge_nugget_examples.py
python3 tools/validate_semantic_action_examples.py
python3 scripts/check_duplicate_schema_ids.py
python3 scripts/validate_control_plane_wrapper_ids.py
# CI parity: ajv-cli@5 compile per new schema with all other schemas as -r refs
npx -y ajv-cli@5 compile -s schemas/KnowledgeNugget.json --strict=false --spec=draft2020 -r ...
npx -y ajv-cli@5 compile -s schemas/SemanticAction.json --strict=false --spec=draft2020 -r ...
# CI parity: the validate.yml "Validate examples against schemas" python step, verbatim

Pass/fail output summary

• make validate → OK: validate (all 19 family targets green, including both new ones; re-run after rebasing onto 66ea10a).
• validate_knowledge_nugget_examples.py → "ok": true, 11/11 checks (2 examples, strictness, wallTime+logicalTime envelope parity, warrant soundness, 5 negative vectors FAIL as required).
• validate_semantic_action_examples.py → "ok": true, 12/12 checks (2 examples, strictness, binding soundness, purity posture, 5 negative vectors FAIL as required).
• check_duplicate_schema_ids.py → OK: 302 unique schema $id values.
• validate_control_plane_wrapper_ids.py → all wrappers resolve, end-to-end OK.
• ajv compile (CI command) → both new schemas ok.
• CI examples step (verbatim) → Results: 194 passed, 82 skipped, 0 failed (the 4 new examples all ok; baseline before this PR had 0 failures too — no regressions).

Known gaps (deliberate, v0.1 — mirrored in the spec notes)

• No OpenAPI/AsyncAPI operations and no semantic/context.jsonld mappings yet — matches how schemas: MPCC event contract v0.1 — conversation + trading event family #204 and the other recent families landed (the JSON-LD CI step warns, does not fail); wiring follows once names settle.
• subClassOf/instanceOf subsumption is resolved by the planner against the ontology, not in CI — CI validates structure and subject resolution only.
• docRef and warrant.evidence entries are free-form-within-URN-grammar stable refs pending dedicated document-identity and step-ref contracts.
• Ontology URIs in examples under https://schemas.srcos.ai/ont/... are illustrative estate-namespace concept URIs, not yet a published ontology.

Blocked

Nothing blocked. Do not merge without review (this PR is intentionally left unmerged).

🤖 Generated with Claude Code