diff --git a/Makefile b/Makefile index 8943bc0..e0c4dae 100644 --- a/Makefile +++ b/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 diff --git a/semantic/agent-system-vocabulary.jsonld b/semantic/agent-system-vocabulary.jsonld new file mode 100644 index 0000000..8a8eb8b --- /dev/null +++ b/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:. Distinct from pid, which is session-scoped and non-stable." + } + ] +} diff --git a/tools/validate_agent_system_vocabulary.py b/tools/validate_agent_system_vocabulary.py new file mode 100644 index 0000000..203bed4 --- /dev/null +++ b/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())