activegraph 1.3.0__tar.gz → 1.4.0__tar.gz

{activegraph-1.3.0/activegraph.egg-info → activegraph-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: activegraph
-Version: 1.3.0
+Version: 1.4.0
 Summary: An event-sourced reactive graph runtime for long-running, auditable, agentic systems.
 Author: Active Graph contributors
 License-Expression: Apache-2.0

{activegraph-1.3.0 → activegraph-1.4.0}/activegraph/__init__.py

@@ -242,4 +242,4 @@ __all__ = [
     "tool",
 ]
 
-__version__ = "1.3.0"
+__version__ = "1.4.0"

{activegraph-1.3.0 → activegraph-1.4.0}/activegraph/packs/__init__.py

@@ -570,10 +570,20 @@ class Pack:
     policies: tuple[Any, ...] = ()
     prompts: tuple[Any, ...] = ()
     settings_schema: type = EmptySettings
+    # v1.4: the DECLARATIVE half of gateway-capability registration
+    # (manifest spec Q8). Entries are CapabilityDecl instances from
+    # activegraph.packs.manifest. The runtime never registers these —
+    # registration stays imperative host wiring — but the declaration
+    # is loader-introspectable: verify_surface two-way checks it
+    # against the manifest, and load_pack records it in the
+    # pack.loaded payload so decision surfaces read a pack's declared
+    # outbound reach from the graph. The gateway-side check ("did the
+    # registering pack declare this?") is downstream's half.
+    capabilities: tuple[Any, ...] = ()
 
     def __post_init__(self) -> None:
         # list → tuple conversion (frozen requires object.__setattr__)
-        for f in ("object_types", "relation_types", "behaviors", "tools", "policies", "prompts"):
+        for f in ("object_types", "relation_types", "behaviors", "tools", "policies", "prompts", "capabilities"):
             v = getattr(self, f)
             if isinstance(v, list):
                 object.__setattr__(self, f, tuple(v))
@@ -625,6 +635,32 @@ class Pack:
                     f"activegraph.packs.tool (use activegraph.packs.tool, not activegraph.tool)"
                 )
 
+        # v1.4: capabilities are CapabilityDecl entries with a valid
+        # risk class; (provider, capability) pairs unique within the
+        # pack. Lazy import — manifest.py imports nothing from this
+        # module at import time, but keep the seam one-directional.
+        if self.capabilities:
+            from activegraph.packs.manifest import _RISK_CLASSES, CapabilityDecl
+
+            for c in self.capabilities:
+                if not isinstance(c, CapabilityDecl):
+                    raise PackValidationError(
+                        f"Pack {self.name!r}: capabilities entries must be "
+                        f"activegraph.packs.manifest.CapabilityDecl, got {c!r}"
+                    )
+                if c.risk_class not in _RISK_CLASSES:
+                    raise PackValidationError(
+                        f"Pack {self.name!r}: capability "
+                        f"{c.provider}.{c.capability} has risk_class "
+                        f"{c.risk_class!r}; must be one of "
+                        f"low|medium|high|critical"
+                    )
+            _check_unique(
+                [f"{c.provider}.{c.capability}" for c in self.capabilities],
+                "capability",
+                self.name,
+            )
+
     # identity by (name, version) — CONTRACT v0.9 #2 / #6
     def __eq__(self, other: Any) -> bool:
         if not isinstance(other, Pack):

{activegraph-1.3.0 → activegraph-1.4.0}/activegraph/packs/loader.py

@@ -240,6 +240,8 @@ def load_pack_into_runtime(
 
     state.loaded_packs[pack.name] = pack
     state.pack_settings[pack.name] = settings_obj
+    # v1.4: re-loading is how a disabled pack comes back.
+    state.disabled_packs.discard(pack.name)
 
     # behaviors: wrap with typed-settings injection, rename to canonical
     canonical_to_pack_behavior: dict[str, Any] = {}
@@ -258,6 +260,9 @@ def load_pack_into_runtime(
     for t in pack.tools:
         canonical = f"{pack.name}.{t.name}"
         renamed = _rename_tool(t, canonical)
+        # v1.4: ownership stamp, symmetric with behaviors — this is
+        # what disable_pack filters on.
+        renamed._pack_owner = pack.name  # type: ignore[attr-defined]
         rt._pack_tools.append(renamed)
         state.tool_owners[canonical] = pack.name
         _add_short_name(state.tool_short_to_canonical, t.name, canonical)
@@ -336,6 +341,10 @@ class PackRuntimeState:
         # pending approvals
         self.pending_approvals: list[PendingApproval] = []
         self._next_approval_n: int = 1
+        # v1.4: packs deregistered by runtime.disable_pack. Names stay
+        # here so a second disable is an idempotent no-op instead of a
+        # not-loaded error; load_pack clears the flag on re-load.
+        self.disabled_packs: set[str] = set()
 
 
 def _ensure_pack_state(rt: "Runtime") -> PackRuntimeState:
@@ -782,6 +791,18 @@ def _build_pack_loaded_payload(pack: Pack, settings_obj: BaseModel) -> dict:
         "policies": [f"{pack.name}.{p.name}" for p in pack.policies],
         "prompts": pack.prompt_manifest(),
         "settings": _canonical_settings_dump(settings_obj),
+        # v1.4: the declared gateway-capability surface (manifest spec
+        # Q8) — graph-readable, so decision surfaces and catalogs read
+        # a pack's declared outbound reach without importing it.
+        "capabilities": [
+            {
+                "provider": c.provider,
+                "capability": c.capability,
+                "risk_class": c.risk_class,
+                "credential_ref": c.credential_ref,
+            }
+            for c in getattr(pack, "capabilities", ())
+        ],
     }
 
 

{activegraph-1.3.0 → activegraph-1.4.0}/activegraph/packs/manifest.py

@@ -402,33 +402,58 @@ def verify_surface(manifest: PackManifest, pack: Any) -> None:
             f"settings_schema: declared {manifest.settings_schema!r}, "
             f"Pack has {actual_settings!r}"
         )
+    # v1.4 (spec Q8, runtime half): Pack.capabilities is declarative,
+    # so the loader can two-way check it exactly like behaviors/tools.
+    # Keyed by (provider, capability); a declared pair must also agree
+    # on risk_class — a relabeled risk class is precisely the swap the
+    # decision surface needs to catch.
+    declared_caps = {
+        (c.provider, c.capability): c.risk_class for c in manifest.capabilities
+    }
+    actual_caps = {
+        (c.provider, c.capability): c.risk_class
+        for c in getattr(pack, "capabilities", ())
+    }
+    for key in sorted(set(declared_caps) - set(actual_caps)):
+        violations.append(
+            f"capabilities: declared {key[0]}.{key[1]} not on Pack"
+        )
+    for key in sorted(set(actual_caps) - set(declared_caps)):
+        violations.append(
+            f"capabilities: Pack declares {key[0]}.{key[1]} undeclared "
+            f"in manifest"
+        )
+    for key in sorted(set(declared_caps) & set(actual_caps)):
+        if declared_caps[key] != actual_caps[key]:
+            violations.append(
+                f"capabilities: {key[0]}.{key[1]} risk_class mismatch — "
+                f"manifest {declared_caps[key]!r}, Pack {actual_caps[key]!r}"
+            )
     if violations:
         raise PackManifestError(
             source=f"{manifest.name}@{manifest.version}", violations=violations
         )
 
 
-def compute_content_hash(pack_root: str | Path) -> str:
-    """The spec §4 content hash over a pack directory, byte-exact.
+def _hash_pack_dir(pack_root: str | Path, *, include_manifest: bool) -> str:
+    """The shared §4 canonical byte stream over a pack directory.
 
-    PROVISIONAL — this function is the normative reference for all
-    three recomputation sites (loader, downstream CI, evolution
-    gates). Canonicalization:
+    ``include_manifest=False`` is the manifest-internal content hash
+    (a hash cannot cover itself); ``True`` is the bundle hash external
+    pins use (spec amendment: the manifest is the very document the
+    reviewer approves, so an external pin that excludes it pins
+    nothing that matters). Everything else is identical:
 
     1. Every regular file under the root, recursively, excluding
-       ``manifest.toml`` itself, ``__pycache__`` directories,
-       ``*.pyc``, and hidden (``.``-prefixed) files and directories.
-    2. Symlinks — file OR directory — are rejected loudly (the spec
-       names files; this implementation extends the rejection to
-       directory symlinks, which could otherwise smuggle unhashed
-       content into the walk).
+       ``__pycache__`` directories, ``*.pyc``, and hidden
+       (``.``-prefixed) files and directories.
+    2. Symlinks — file OR directory — are rejected loudly (directory
+       symlinks could otherwise smuggle unhashed content).
     3. Paths must be UTF-8-encodable and NFC-normalized; anything
        else is rejected loudly rather than hashed ambiguously across
        platforms.
     4. Relative POSIX paths sorted lexicographically by UTF-8 bytes;
        per file: path bytes, NUL, 8-byte big-endian length, raw bytes.
-
-    Returns ``"sha256:" + 64 hex chars``.
     """
     root = Path(pack_root)
     if not root.is_dir():
@@ -455,7 +480,7 @@ def compute_content_hash(pack_root: str | Path) -> str:
                 continue  # sockets, fifos: not regular files
             if child.name.endswith(".pyc"):
                 continue
-            if rel == "manifest.toml":
+            if rel == "manifest.toml" and not include_manifest:
                 continue
             if unicodedata.normalize("NFC", rel) != rel:
                 violations.append(f"path not NFC-normalized: {rel!r}")
@@ -481,6 +506,71 @@ def compute_content_hash(pack_root: str | Path) -> str:
     return _HASH_PREFIX + h.hexdigest()
 
 
+def compute_content_hash(pack_root: str | Path) -> str:
+    """The spec §4 content hash over a pack directory, byte-exact.
+
+    PROVISIONAL — this function is the normative reference for every
+    recomputation site (loader, downstream CI, evolution gates).
+    ``manifest.toml`` is EXCLUDED (a hash cannot cover itself); see
+    :func:`_hash_pack_dir` for the full canonicalization, including
+    this implementation's amendments over the spec draft. This is the
+    hash the manifest's own ``[pack.integrity].content_hash`` pins —
+    internal consistency only, never authenticity. External pins use
+    :func:`compute_bundle_hash`.
+
+    Returns ``"sha256:" + 64 hex chars``.
+    """
+    return _hash_pack_dir(pack_root, include_manifest=False)
+
+
+def compute_bundle_hash(pack_root: str | Path) -> str:
+    """The bundle hash external pins use: the §4 walk WITHOUT the
+    manifest exclusion. PROVISIONAL.
+
+    Spec-review finding, accepted downstream: the content hash
+    excludes ``manifest.toml`` by necessity (self-reference), so an
+    external pin over it leaves the manifest — the very document a
+    reviewer approves, carrying risk classes, ``consumes``, and
+    ``authored_by`` — swappable without detection. ``[load.pins]``
+    entries, the evolution pack's proposal pins, and any resolver
+    verifying a fetched pack pin THIS hash instead. Same
+    canonicalization, same amendments, one file more.
+
+    Returns ``"sha256:" + 64 hex chars``.
+    """
+    return _hash_pack_dir(pack_root, include_manifest=True)
+
+
+def verify_bundle_hash(expected: str, pack_root: str | Path) -> None:
+    """Recompute the bundle hash over ``pack_root`` and compare to an
+    EXTERNAL pin. Raises :class:`PackManifestError` on mismatch.
+
+    PROVISIONAL. ``expected`` comes from outside the pack directory —
+    a ``[load.pins]`` entry, a proposal record, an approval surface —
+    which is what makes this an authenticity check rather than the
+    internal-consistency check :func:`verify_content_hash` performs.
+    """
+    if not expected.startswith(_HASH_PREFIX) or not re.fullmatch(
+        r"[0-9a-f]{64}", expected[len(_HASH_PREFIX):]
+    ):
+        raise PackManifestError(
+            source=str(pack_root),
+            violations=[
+                f"external pin {expected!r} must be 'sha256:' + 64 "
+                f"lowercase hex chars"
+            ],
+        )
+    actual = compute_bundle_hash(pack_root)
+    if actual != expected:
+        raise PackManifestError(
+            source=str(pack_root),
+            violations=[
+                f"bundle hash mismatch: external pin is {expected}, "
+                f"directory (manifest included) hashes to {actual}"
+            ],
+        )
+
+
 def verify_content_hash(
     manifest: PackManifest, pack_root: str | Path
 ) -> None:

{activegraph-1.3.0 → activegraph-1.4.0}/activegraph/runtime/runtime.py

@@ -2044,6 +2044,137 @@ class Runtime:
             return []
         return list(self._pack_state.loaded_packs.values())
 
+    def disable_pack(self, name: str) -> bool:
+        """Deregister a loaded pack: its behaviors stop firing NOW.
+
+        CONTRACT v1.4 #3. The pack's behaviors, tools, typed-object
+        schemas, relation specs, gating policies, and settings are
+        removed from this runtime's live registries and the registry
+        is rebuilt — nothing pack-owned matches another event from
+        this call onward. What deliberately does NOT happen:
+
+        - **State is untouched.** Objects and relations the pack
+          created remain; disabling code never rewrites history.
+        - **Memory is not reclaimed.** Python cannot honestly unload
+          imported code; the objects stay in memory, inert. Restart
+          to evict (hosts doing boot-time pack loading key off the
+          ``pack.disabled`` event this method emits).
+        - **Pending approvals remain pending** — resolvable or not,
+          they are recorded state, not registry state.
+
+        Emits ``pack.disabled`` (queue-visible, like ``pack.loaded``)
+        with the deregistered surface, so behaviors and boot loaders
+        can react from the log. Idempotent: disabling an
+        already-disabled pack returns ``False`` and emits nothing.
+        Re-enabling is ``load_pack`` again (which clears the disabled
+        flag). Raises
+        :class:`~activegraph.packs.PackNotFoundError` for a name this
+        runtime never loaded.
+
+        Returns ``True`` when the pack was live and is now disabled.
+        """
+        from activegraph.packs import PackNotFoundError
+        from activegraph.packs.loader import AMBIGUOUS
+
+        state = self._pack_state
+        if state is None or name not in state.loaded_packs:
+            if state is not None and name in state.disabled_packs:
+                return False  # idempotent second disable
+            loaded = tuple(state.loaded_packs.keys()) if state else ()
+            raise PackNotFoundError(name, installed=loaded)
+
+        pack = state.loaded_packs.pop(name)
+        state.pack_settings.pop(name, None)
+
+        removed_behaviors = sorted(
+            c for c, owner in state.behavior_owners.items() if owner == name
+        )
+        removed_tools = sorted(
+            c for c, owner in state.tool_owners.items() if owner == name
+        )
+        removed_object_types = sorted(
+            t for t, owner in state.object_type_owners.items() if owner == name
+        )
+        removed_relation_types = sorted(
+            t
+            for t, owner in state.relation_type_owners.items()
+            if owner == name
+        )
+        for c in removed_behaviors:
+            state.behavior_owners.pop(c, None)
+        for c in removed_tools:
+            state.tool_owners.pop(c, None)
+        for t in removed_object_types:
+            state.object_type_owners.pop(t, None)
+            state.object_type_schemas.pop(t, None)
+        for t in removed_relation_types:
+            state.relation_type_owners.pop(t, None)
+            state.relation_type_specs.pop(t, None)
+        for c in [
+            c for c, owner in state.policy_owners.items() if owner == name
+        ]:
+            state.policy_owners.pop(c, None)
+        prefix = f"{name}."
+        for otype in list(state.gated_object_types):
+            remaining = [
+                p
+                for p in state.gated_object_types[otype]
+                if not p.startswith(prefix)
+            ]
+            if remaining:
+                state.gated_object_types[otype] = remaining
+            else:
+                del state.gated_object_types[otype]
+
+        # Short-name maps: recompute from the surviving canonicals —
+        # removal can RESOLVE an ambiguity, not just delete entries.
+        def _rebuild_shorts(owners: dict[str, str]) -> dict[str, str]:
+            shorts: dict[str, str] = {}
+            for canonical in owners:
+                short = canonical.split(".", 1)[1]
+                shorts[short] = (
+                    AMBIGUOUS if short in shorts else canonical
+                )
+            return shorts
+
+        state.behavior_short_to_canonical = _rebuild_shorts(
+            state.behavior_owners
+        )
+        state.tool_short_to_canonical = _rebuild_shorts(state.tool_owners)
+
+        self._pack_behaviors = [
+            b
+            for b in self._pack_behaviors
+            if getattr(b, "_pack_owner", None) != name
+        ]
+        self._pack_tools = [
+            t
+            for t in self._pack_tools
+            if getattr(t, "_pack_owner", None) != name
+        ]
+        state.disabled_packs.add(name)
+        self._ensure_registry()
+
+        self.graph.emit(
+            Event(
+                id=self.graph.ids.event(),
+                type="pack.disabled",
+                payload={
+                    "name": name,
+                    "version": pack.version,
+                    "behaviors": removed_behaviors,
+                    "tools": removed_tools,
+                    "object_types": removed_object_types,
+                    "relation_types": removed_relation_types,
+                },
+                actor="runtime",
+                frame_id=self.frame.id if self.frame else None,
+                caused_by=None,
+                timestamp=self.graph.clock.now(),
+            )
+        )
+        return True
+
     def get_behavior(self, name: str) -> Any:
         """Look up a registered behavior by canonical or short name.
 

{activegraph-1.3.0 → activegraph-1.4.0/activegraph.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: activegraph
-Version: 1.3.0
+Version: 1.4.0
 Summary: An event-sourced reactive graph runtime for long-running, auditable, agentic systems.
 Author: Active Graph contributors
 License-Expression: Apache-2.0

{activegraph-1.3.0 → activegraph-1.4.0}/activegraph.egg-info/SOURCES.txt

@@ -111,6 +111,7 @@ tests/test_clock.py
 tests/test_diff.py
 tests/test_diligence_pack.py
 tests/test_diligence_with_tools.py
+tests/test_disable_pack.py
 tests/test_doc_links.py
 tests/test_doc_python_snippets.py
 tests/test_doc_site_reachable.py

{activegraph-1.3.0 → activegraph-1.4.0}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "activegraph"
-version = "1.3.0"
+version = "1.4.0"
 description = "An event-sourced reactive graph runtime for long-running, auditable, agentic systems."
 readme = "README.md"
 requires-python = ">=3.11"

activegraph-1.4.0/tests/test_disable_pack.py

@@ -0,0 +1,155 @@
+"""runtime.disable_pack: deregistration, not unload (CONTRACT v1.4 #3).
+
+Behaviors stop firing immediately, tools stop resolving, typed
+validation reverts to untyped, state stays, memory is not reclaimed
+(restart to evict), re-enable = load_pack, idempotent second disable.
+"""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import BaseModel
+
+from activegraph import Graph, Runtime, clear_registry
+from activegraph import ToolNotFoundError
+from activegraph.packs import (
+    ObjectType,
+    Pack,
+    PackNotFoundError,
+    behavior as pack_behavior,
+)
+
+
+class _NoteSchema(BaseModel):
+    text: str
+
+
+def _candidate_pack(hits: list[str]) -> Pack:
+    @pack_behavior(name="echo", on=["goal.created"])
+    def echo(event, graph, ctx):
+        hits.append(event.payload.get("goal", ""))
+        graph.add_object("echo_note", {"text": "hi"})
+
+    from activegraph.packs import tool as pack_tool
+
+    @pack_tool(name="shout")
+    def shout(args, ctx):
+        return {"ok": True}
+
+    return Pack(
+        name="candidate",
+        version="1.0",
+        object_types=(ObjectType(name="typed_note", schema=_NoteSchema),),
+        behaviors=(echo,),
+        tools=(shout,),
+    )
+
+
+def test_disable_stops_behaviors_and_tools_immediately():
+    clear_registry()
+    hits: list[str] = []
+    rt = Runtime(Graph())
+    rt.load_pack(_candidate_pack(hits))
+
+    rt.run_goal("first")
+    assert hits == ["first"]
+    assert rt.get_tool("candidate.shout").name == "candidate.shout"
+
+    assert rt.disable_pack("candidate") is True
+    rt.run_goal("second")
+    assert hits == ["first"]  # behavior no longer fires
+    with pytest.raises(ToolNotFoundError):
+        rt.get_tool("candidate.shout")
+    with pytest.raises(ToolNotFoundError):
+        rt.get_tool("shout")
+    assert rt.loaded_packs() == []
+
+
+def test_disable_leaves_state_and_reverts_typing():
+    clear_registry()
+    hits: list[str] = []
+    rt = Runtime(Graph())
+    rt.load_pack(_candidate_pack(hits))
+    rt.run_goal("go")
+    created = next(
+        o for o in rt.graph.all_objects() if o.type == "echo_note"
+    )
+
+    # Typed while loaded: schema enforced.
+    from activegraph.packs import PackSchemaViolation
+
+    with pytest.raises(PackSchemaViolation):
+        rt.graph.add_object("typed_note", {"wrong_field": 1})
+
+    rt.disable_pack("candidate")
+    # Pack-created state is untouched...
+    assert rt.graph.get_object(created.id) is not None
+    # ...and the type reverts to v0.9 untyped semantics.
+    obj = rt.graph.add_object("typed_note", {"wrong_field": 1})
+    assert rt.graph.get_object(obj.id) is not None
+
+
+def test_disable_emits_event_and_is_idempotent():
+    clear_registry()
+    rt = Runtime(Graph())
+    rt.load_pack(_candidate_pack([]))
+
+    assert rt.disable_pack("candidate") is True
+    ev = next(e for e in rt.graph.events if e.type == "pack.disabled")
+    assert ev.payload["name"] == "candidate"
+    assert ev.payload["behaviors"] == ["candidate.echo"]
+    assert ev.payload["tools"] == ["candidate.shout"]
+    assert ev.payload["object_types"] == ["typed_note"]
+
+    # Idempotent second call: False, no second event.
+    assert rt.disable_pack("candidate") is False
+    assert (
+        len([e for e in rt.graph.events if e.type == "pack.disabled"]) == 1
+    )
+
+
+def test_disable_unknown_pack_is_loud():
+    clear_registry()
+    rt = Runtime(Graph())
+    with pytest.raises(PackNotFoundError):
+        rt.disable_pack("never_loaded")
+
+
+def test_reload_reenables():
+    clear_registry()
+    hits: list[str] = []
+    pack = _candidate_pack(hits)
+    rt = Runtime(Graph())
+    rt.load_pack(pack)
+    rt.disable_pack("candidate")
+
+    assert rt.load_pack(pack) is True  # fresh load, not idempotent skip
+    rt.run_goal("after re-enable")
+    assert hits == ["after re-enable"]
+    assert rt.get_tool("candidate.shout").name == "candidate.shout"
+    # And it can be disabled again.
+    assert rt.disable_pack("candidate") is True
+
+
+def test_disable_resolves_short_name_ambiguity():
+    # Two packs export a behavior with the same short name; disabling
+    # one must RESOLVE the ambiguity, not leave a stale sentinel.
+    clear_registry()
+
+    def mk(pack_name):
+        @pack_behavior(name="worker", on=["goal.created"])
+        def worker(event, graph, ctx):
+            pass
+
+        return Pack(name=pack_name, version="1.0", behaviors=(worker,))
+
+    rt = Runtime(Graph())
+    rt.load_pack(mk("alpha"))
+    rt.load_pack(mk("beta"))
+    from activegraph.runtime.registration_errors import AmbiguousBehaviorError
+
+    with pytest.raises(AmbiguousBehaviorError):
+        rt.get_behavior("worker")
+
+    rt.disable_pack("alpha")
+    assert rt.get_behavior("worker").name == "beta.worker"