feat(semantic): add agent-system vocabulary seed — JSON-LD [T0-3]

Makefile

@@ -1,8 +1,11 @@
-.PHONY: validate validate-resource-contract validate-measurement validate-value-type validate-source-locator validate-sourceos-repo-manifest validate-mesh-action-registry 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-epistemic-kernel-examples validate-ab-update-examples validate-device-service-examples validate-duplicate-schema-ids validate-lawful-dispatch-receipt validate-architectural-building-block validate-agent-passport-examples validate-seam-definition-examples validate-measurement
+.PHONY: validate validate-resource-contract validate-measurement validate-value-type validate-source-locator validate-sourceos-repo-manifest validate-mesh-action-registry 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-epistemic-kernel-examples validate-ab-update-examples validate-device-service-examples validate-duplicate-schema-ids validate-lawful-dispatch-receipt validate-architectural-building-block validate-agent-passport-examples validate-seam-definition-examples validate-agent-system-vocabulary validate-measurement
 
-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-epistemic-kernel-examples validate-ab-update-examples validate-device-service-examples validate-duplicate-schema-ids validate-value-type validate-source-locator validate-sourceos-repo-manifest validate-mesh-action-registry validate-lawful-dispatch-receipt validate-architectural-building-block validate-agent-passport-examples validate-seam-definition-examples validate-measurement validate-resource-contract
+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-epistemic-kernel-examples validate-ab-update-examples validate-device-service-examples validate-duplicate-schema-ids validate-value-type validate-source-locator validate-sourceos-repo-manifest validate-mesh-action-registry validate-lawful-dispatch-receipt validate-architectural-building-block validate-agent-passport-examples validate-seam-definition-examples validate-agent-system-vocabulary validate-measurement validate-resource-contract
 	@echo "OK: validate"
 
+validate-agent-system-vocabulary:
+	python3 tools/validate_agent_system_vocabulary.py
+
 validate-agent-passport-examples:
 	python3 -m pip install --user jsonschema >/dev/null
 	python3 tools/validate_agent_passport_examples.py

semantic/agent-system-vocabulary.jsonld

@@ -0,0 +1,49 @@
+{
+  "@context": {
+    "agentsys": "https://spec.sourceos.dev/vocab/agent-system#",
+    "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
+    "owl": "http://www.w3.org/2002/07/owl#"
+  },
+  "@id": "https://spec.sourceos.dev/vocab/agent-system",
+  "@type": "owl:Ontology",
+  "rdfs:label": "Agent System Vocabulary",
+  "rdfs:comment": "JSON-LD vocabulary seed for the agent-system domain: host-level typed agent classification, permission flags, spatial authorization, seams, capability exceptions, and bundle identity. Anchors the URN namespace urn:srcos:agent-passport:* and is realized as OWL/SHACL in ontogenesis (T1). Complementary to the Agent Plane family, which operates at workflow/session level.",
+  "@graph": [
+    {
+      "@id": "agentsys:AgentClass",
+      "@type": "owl:Class",
+      "rdfs:label": "Agent Class",
+      "rdfs:comment": "The typed classification of a host agent, one of the five classes: system_core, intelligence_automation, app_helper, legacy_bridge, third_party. Governs execution authorization, spatial permissions, and intelligence constraints."
+    },
+    {
+      "@id": "agentsys:PermissionFlag",
+      "@type": "owl:Class",
+      "rdfs:label": "Permission Flag",
+      "rdfs:comment": "A boolean permission attribute governing a host agent: is_daemon, is_apple_signed, suppress_user_authorization_prompt, system_bundle. Flag combinations are constrained by class (e.g. third_party may not set system_bundle)."
+    },
+    {
+      "@id": "agentsys:ManagedSpace",
+      "@type": "owl:Class",
+      "rdfs:label": "Managed Space",
+      "rdfs:comment": "A CGSSpace spatial authorization context (with an associated display UUID) an agent may present in. Not merely a UI concept: an authorization boundary whose stability is subject to SEAM-008 (displayUUID instability)."
+    },
+    {
+      "@id": "agentsys:SeamDefinition",
+      "@type": "owl:Class",
+      "rdfs:label": "Seam Definition",
+      "rdfs:comment": "An ungated boundary between two system layers that represents an attack surface. Names where trust is not yet enforced, the vector that exploits it, and the gate that would close it."
+    },
+    {
+      "@id": "agentsys:CapabilityException",
+      "@type": "owl:Class",
+      "rdfs:label": "Capability Exception",
+      "rdfs:comment": "An explicit, scoped, attributable capability grant that deviates from an agent class default. Carries capability, granted_by, granted_at, scope, and optional expiry."
+    },
+    {
+      "@id": "agentsys:BundleIdentity",
+      "@type": "owl:Class",
+      "rdfs:label": "Bundle Identity",
+      "rdfs:comment": "The stable process identity (bundle_id) of a host agent, e.g. com.anthropic.claudefordesktop. The slug basis for the URN urn:srcos:agent-passport:<bundle_id_slug>. Distinct from pid, which is session-scoped and non-stable."
+    }
+  ]
+}

tools/validate_agent_system_vocabulary.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Validate the agent-system JSON-LD vocabulary seed (T0-3).
+
+Asserts the vocabulary is well-formed JSON-LD and that every required term is
+present AND complete (@type + rdfs:label + rdfs:comment). A term declared
+without a label or comment is a silent gap, so it is rejected here rather than
+shipped.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+VOCAB_PATH = REPO_ROOT / "semantic" / "agent-system-vocabulary.jsonld"
+BASE_NS = "https://spec.sourceos.dev/vocab/agent-system#"
+REQUIRED_TERMS = {
+    "AgentClass",
+    "PermissionFlag",
+    "ManagedSpace",
+    "SeamDefinition",
+    "CapabilityException",
+    "BundleIdentity",
+}
+REQUIRED_FIELDS = {"@type", "rdfs:label", "rdfs:comment"}
+
+
+def fail(msg: str) -> None:
+    print(f"FAIL: {msg}")
+    sys.exit(1)
+
+
+def main() -> int:
+    try:
+        doc = json.loads(VOCAB_PATH.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        fail(f"{VOCAB_PATH.name} is not valid JSON: {exc}")
+
+    ctx = doc.get("@context")
+    if not isinstance(ctx, dict) or ctx.get("agentsys") != BASE_NS:
+        fail(f"@context must map agentsys -> {BASE_NS}")
+
+    graph = doc.get("@graph")
+    if not isinstance(graph, list) or not graph:
+        fail("@graph must be a non-empty array of term definitions")
+
+    seen = {}
+    for node in graph:
+        if not isinstance(node, dict):
+            fail("each @graph entry must be an object")
+        node_id = str(node.get("@id", ""))
+        if not node_id.startswith("agentsys:"):
+            fail(f"term @id must be in the agentsys namespace, got {node_id!r}")
+        term = node_id.split(":", 1)[1]
+        missing = REQUIRED_FIELDS - set(node)
+        if missing:
+            fail(f"term {term} is missing required field(s): {sorted(missing)}")
+        for field in ("rdfs:label", "rdfs:comment"):
+            if not str(node.get(field, "")).strip():
+                fail(f"term {term} has an empty {field}")
+        seen[term] = node
+
+    missing_terms = REQUIRED_TERMS - set(seen)
+    if missing_terms:
+        fail(f"missing required terms: {sorted(missing_terms)}")
+
+    print(
+        f"OK: agent-system vocabulary valid; {len(REQUIRED_TERMS)} terms defined "
+        f"with @type + rdfs:label + rdfs:comment ({', '.join(sorted(REQUIRED_TERMS))})"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())