feat: ship portable Actors ontology v0.1

portable_ontology/__init__.py

@@ -0,0 +1 @@
+"""Portable semantic ontology release contracts."""

portable_ontology/actors.py

@@ -0,0 +1,132 @@
+"""Validation for the clean Actors-family ontology release.
+
+This module validates release artifacts and inventory candidates.  It does not
+rewrite an existing graph or admit semantic records; admission remains with the
+instance human gate.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+
+MANIFEST_PATH = Path(__file__).parent / "manifests" / "actors_family_v0_1.json"
+CANONICAL_ACTOR_TYPES = ("person", "organization", "agent")
+TAXONOMY_FIELDS = ("phylum", "class", "order", "genus", "species")
+LEGACY_AGENT_NODE_TYPES = {
+    "agent_instance",
+    "agent_taxon",
+    "agent_phylum",
+    "agent_class",
+    "agent_order",
+    "agent_genus",
+    "agent_family",
+    "agent_species",
+}
+
+
+def load_manifest(path: Path = MANIFEST_PATH) -> dict[str, Any]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def manifest_digest(manifest: dict[str, Any]) -> str:
+    unsigned = json.loads(json.dumps(manifest))
+    unsigned["integrity"]["manifest_sha256"] = None
+    canonical = json.dumps(
+        unsigned, ensure_ascii=False, sort_keys=True, separators=(",", ":")
+    ).encode("utf-8")
+    return hashlib.sha256(canonical).hexdigest()
+
+
+def validate_manifest(manifest: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    if manifest.get("schema_version") != "mycelium-portable-ontology/v0.1":
+        errors.append("unexpected schema_version")
+    if manifest.get("release_id") != "actors_family_v0_1":
+        errors.append("unexpected release_id")
+    actors = manifest.get("actors_family", {})
+    if tuple(actors.get("canonical_types", ())) != CANONICAL_ACTOR_TYPES:
+        errors.append("Actors canonical types must be exactly person, organization, agent")
+    noncanonical = set(actors.get("noncanonical_agent_node_types", ()))
+    if not {"provider", "model", "lane", "persona", "instance", "agent_instance", "agent_taxon"} <= noncanonical:
+        errors.append("agent facet/noncanonical-type boundary is incomplete")
+
+    card = manifest.get("agent_registration_card", {})
+    if card.get("is_actor_type") is not False:
+        errors.append("registration card must not become a fourth Actors type")
+    if tuple(card.get("required_taxonomy_fields", ())) != TAXONOMY_FIELDS:
+        errors.append("registration card taxonomy must be phylum/class/order/genus/species")
+    if "Do not copy legacy agent_* taxonomy nodes" not in card.get("legacy_import_rule", ""):
+        errors.append("legacy taxonomy-node exclusion is missing")
+
+    relations = manifest.get("required_agent_topology", {}).get("relations", {})
+    organization = relations.get("organization", {})
+    registration = relations.get("registration_card", {})
+    lineage = relations.get("lineage", {})
+    if organization.get("minimum") != 1 or organization.get("evidence_backed") is not True:
+        errors.append("every agent must have an evidence-backed organization relation")
+    if registration.get("minimum") != 1 or registration.get("maximum") != 1:
+        errors.append("every agent must instantiate exactly one registration card")
+    if registration.get("evidence_backed") is not True:
+        errors.append("registration-card relation must be evidence-backed")
+    if lineage.get("relation_type") != "subagent_of" or lineage.get("queryable") is not True:
+        errors.append("parent/subagent lineage must be explicit and queryable")
+
+    growth = manifest.get("growth_admission", {})
+    if growth.get("instance_human_gate_is_only_admission_authority") is not True:
+        errors.append("instance human gate must remain the only admission authority")
+    if growth.get("credentials_are_content") is not False:
+        errors.append("credentials must not be ontology content")
+    if growth.get("cross_instance_publication_does_not_canonicalize_destination") is not True:
+        errors.append("cross-instance publication boundary is missing")
+
+    expected = manifest_digest(manifest)
+    if manifest.get("integrity", {}).get("manifest_sha256") != expected:
+        errors.append("integrity.manifest_sha256 digest mismatch")
+    return errors
+
+
+def validate_agent_candidate(candidate: dict[str, Any]) -> list[str]:
+    """Validate a clean-instance agent inventory row before gate admission.
+
+    Relations are represented by IDs here so an inventory diff can use the
+    same contract without inventing or mutating graph edges.
+    """
+
+    errors: list[str] = []
+    if candidate.get("type") != "agent":
+        if candidate.get("type") in LEGACY_AGENT_NODE_TYPES:
+            errors.append("legacy agent taxonomy node types are not canonical")
+        else:
+            errors.append("candidate type must be agent")
+        return errors
+
+    agent_id = candidate.get("id")
+    if not isinstance(agent_id, str) or not agent_id.strip():
+        errors.append("agent id is required")
+    organizations = candidate.get("organization_ids")
+    if not isinstance(organizations, list) or not organizations or not all(
+        isinstance(value, str) and value.strip() for value in organizations
+    ):
+        errors.append("at least one organization_id is required")
+
+    card = candidate.get("registration_card")
+    if not isinstance(card, dict):
+        errors.append("one registration_card is required")
+    else:
+        missing = [field for field in TAXONOMY_FIELDS if not isinstance(card.get(field), str) or not card[field].strip()]
+        if missing:
+            errors.append("registration_card missing taxonomy fields: " + ", ".join(missing))
+
+    lineage_kind = candidate.get("lineage_kind")
+    parent_id = candidate.get("parent_agent_id")
+    if lineage_kind not in {"root", "subagent"}:
+        errors.append("lineage_kind must be root or subagent")
+    elif lineage_kind == "root" and parent_id is not None:
+        errors.append("root agent must not have parent_agent_id")
+    elif lineage_kind == "subagent" and (not isinstance(parent_id, str) or not parent_id.strip()):
+        errors.append("subagent requires parent_agent_id")
+    return errors

portable_ontology/manifests/actors_family_v0_1.json

@@ -0,0 +1,113 @@
+{
+  "schema_version": "mycelium-portable-ontology/v0.1",
+  "release_id": "actors_family_v0_1",
+  "release_status": "canonical_portable_release",
+  "released_at": "2026-08-17",
+  "scope": "Clean Blank Mycelium and Noam Spore instances only",
+  "actors_family": {
+    "canonical_types": [
+      "person",
+      "organization",
+      "agent"
+    ],
+    "definitions": {
+      "person": "One identifiable human being only.",
+      "organization": "An organization actor; product, model, agent, and organization identities remain distinct.",
+      "agent": "Any named AI operational identity that can participate in work or provenance."
+    },
+    "type_exclusions": {
+      "person": [
+        "AI or computational agent",
+        "organization",
+        "role",
+        "audience segment",
+        "fictional persona"
+      ],
+      "agent": [
+        "human being",
+        "organization",
+        "role",
+        "product",
+        "unnamed model class"
+      ]
+    },
+    "noncanonical_agent_node_types": [
+      "provider",
+      "model",
+      "lane",
+      "persona",
+      "instance",
+      "agent_instance",
+      "agent_taxon"
+    ]
+  },
+  "agent_registration_card": {
+    "record_kind": "reusable_registration_card",
+    "is_actor_type": false,
+    "required_taxonomy_fields": [
+      "phylum",
+      "class",
+      "order",
+      "genus",
+      "species"
+    ],
+    "reuse_rule": "One registration card may be instantiated by multiple individually tracked agents.",
+    "legacy_import_rule": "Do not copy legacy agent_* taxonomy nodes from Adi's live graph; map reviewed values into registration-card fields."
+  },
+  "required_agent_topology": {
+    "individually_trackable": true,
+    "relations": {
+      "organization": {
+        "relation_type": "associated_with_organization",
+        "target_type": "organization",
+        "minimum": 1,
+        "evidence_backed": true
+      },
+      "registration_card": {
+        "relation_type": "instantiates_registration_card",
+        "target_record_kind": "reusable_registration_card",
+        "minimum": 1,
+        "maximum": 1,
+        "evidence_backed": true
+      },
+      "lineage": {
+        "relation_type": "subagent_of",
+        "target_type": "agent",
+        "rule": "Every agent declares lineage_kind=root or lineage_kind=subagent; subagents require exactly one parent agent and roots require none.",
+        "queryable": true
+      }
+    },
+    "facets_preserved": [
+      "provider",
+      "model",
+      "lane",
+      "persona",
+      "instance"
+    ]
+  },
+  "growth_admission": {
+    "credentials_are_content": false,
+    "user_authorized_provider_credentials_may_open_bounded_candidate_lanes": true,
+    "agents_may_propose_names_and_registration_cards": true,
+    "instance_human_gate_is_only_admission_authority": true,
+    "cross_instance_publication_does_not_canonicalize_destination": true
+  },
+  "source_evidence": [
+    "ev_146b4d8547ed4585a80c07b313e39f6d",
+    "ev_afe89570b16740d8b078832a634e7ee9",
+    "ev_8a025c5dd6304957b019b172276dec83",
+    "ev_d99208305c6e46c59d7f75c3954c36f1",
+    "ev_dd7a27dbad984e4db32fad69767c06c4"
+  ],
+  "explicit_exclusions": [
+    "No Adi live-graph mutation",
+    "No legacy agent_* taxonomy-node import",
+    "No provider credentials or secrets",
+    "No automatic cross-instance canonicalization",
+    "No rewrite of existing noncompliant graphs"
+  ],
+  "integrity": {
+    "canonicalization": "UTF-8 JSON, recursively sorted object keys, compact separators, SHA-256; manifest_sha256 excludes itself",
+    "manifest_sha256": "90904b4e4c18de6b482e47d49cdcd7d7cecbf0e798caa407f965c16edf5ff1c2"
+  }
+}

test_actors_ontology.py

@@ -0,0 +1,73 @@
+import copy
+import unittest
+
+from portable_ontology.actors import (
+    LEGACY_AGENT_NODE_TYPES,
+    load_manifest,
+    manifest_digest,
+    validate_agent_candidate,
+    validate_manifest,
+)
+
+
+VALID_ROOT = {
+    "id": "agent_example_001",
+    "type": "agent",
+    "organization_ids": ["org_example"],
+    "registration_card": {
+        "phylum": "ExampleProvider",
+        "class": "API",
+        "order": "weaver",
+        "genus": "shuttle",
+        "species": "example",
+    },
+    "lineage_kind": "root",
+    "parent_agent_id": None,
+}
+
+
+class ActorsOntologyTests(unittest.TestCase):
+    def test_release_manifest_and_digest(self):
+        manifest = load_manifest()
+        self.assertEqual([], validate_manifest(manifest))
+        self.assertEqual(manifest_digest(manifest), manifest["integrity"]["manifest_sha256"])
+
+    def test_valid_root_and_subagent(self):
+        self.assertEqual([], validate_agent_candidate(VALID_ROOT))
+        child = copy.deepcopy(VALID_ROOT)
+        child.update(id="agent_example_002", lineage_kind="subagent", parent_agent_id="agent_example_001")
+        self.assertEqual([], validate_agent_candidate(child))
+
+    def test_registration_card_can_be_reused_by_distinct_agents(self):
+        first = copy.deepcopy(VALID_ROOT)
+        second = copy.deepcopy(VALID_ROOT)
+        second["id"] = "agent_example_002"
+        self.assertEqual(first["registration_card"], second["registration_card"])
+        self.assertEqual([], validate_agent_candidate(first))
+        self.assertEqual([], validate_agent_candidate(second))
+
+    def test_missing_required_wiring_fails_closed(self):
+        for field in ("organization_ids", "registration_card", "lineage_kind"):
+            with self.subTest(field=field):
+                candidate = copy.deepcopy(VALID_ROOT)
+                candidate.pop(field)
+                self.assertTrue(validate_agent_candidate(candidate))
+
+    def test_legacy_taxonomy_node_types_are_rejected(self):
+        for legacy_type in LEGACY_AGENT_NODE_TYPES:
+            with self.subTest(legacy_type=legacy_type):
+                candidate = copy.deepcopy(VALID_ROOT)
+                candidate["type"] = legacy_type
+                self.assertIn(
+                    "legacy agent taxonomy node types are not canonical",
+                    validate_agent_candidate(candidate),
+                )
+
+    def test_manifest_contains_no_legacy_taxonomy_seed_ids(self):
+        manifest_text = __import__("json").dumps(load_manifest())
+        for prefix in ("agent_species_", "agent_genus_", "agent_order_", "agent_phylum_", "agent_class_"):
+            self.assertNotIn(prefix, manifest_text)
+
+
+if __name__ == "__main__":
+    unittest.main()