activegraph 1.3.0__tar.gz → 1.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: activegraph
-Version: 1.3.0
+Version: 1.5.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.5.0}/activegraph/__init__.py

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

{activegraph-1.3.0 → activegraph-1.5.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.5.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.5.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.5.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.
 
@@ -2419,6 +2550,11 @@ class Runtime:
         store = _open_sqlite_store(path, run_id=chosen)
         graph = Graph(ids=IDGen(), run_id=chosen, graph_store=graph_store)
         events = list(store.iter_events())
+        # CONTRACT v1.5 #2: a compacted run's hot log begins with its
+        # runtime.snapshot event; project the snapshot state first so
+        # the suffix replays against the base it was recorded on.
+        if events and events[0].type == "runtime.snapshot":
+            _materialize_snapshot(graph, store, events[0])
         for ev in events:
             graph._replay_event(ev)  # noqa: SLF001 — internal seam
         graph.ids.reseed_from_events(events)
@@ -2576,6 +2712,11 @@ class Runtime:
         fork_store = SQLiteEventStore(store.path, run_id=new_run_id)
         fork_graph = Graph(ids=IDGen(), run_id=new_run_id, graph_store=graph_store)
         events = list(fork_store.iter_events())
+        # CONTRACT v1.5 #2: forking a compacted parent copies its
+        # runtime.snapshot event; the fork's base state comes from the
+        # shared snapshot sidecar exactly as a load would.
+        if events and events[0].type == "runtime.snapshot":
+            _materialize_snapshot(fork_graph, fork_store, events[0])
         for ev in events:
             fork_graph._replay_event(ev)  # noqa: SLF001
         fork_graph.ids.reseed_from_events(events)
@@ -3285,6 +3426,13 @@ def _verify_replay(
     cache = LLMCache.from_events(recorded_events)
 
     fresh = Graph(ids=IDGen(), run_id="verify_" + loaded_graph.run_id)
+    # CONTRACT v1.5 #2: compacted runs verify their post-snapshot
+    # suffix against the snapshot base; the archived prefix is
+    # verified separately by store.retention.verify_snapshot.
+    if recorded_events and recorded_events[0].type == "runtime.snapshot":
+        _materialize_snapshot(
+            fresh, loaded_graph.store, recorded_events[0]
+        )
     fresh_rt = Runtime(
         fresh,
         behaviors=behaviors,
@@ -3407,6 +3555,69 @@ def _is_lifecycle(e: Event) -> bool:
     )
 
 
+def _materialize_snapshot(graph: Graph, store: Any, snapshot_event: Event) -> None:
+    """Rebuild a compacted run's base state from its snapshot blob.
+
+    CONTRACT v1.5 #2: the blob is fetched from the store's snapshot
+    sidecar by the hash recorded in the ``runtime.snapshot`` event,
+    verified against that hash (fail-loud on mismatch — a corrupted
+    sidecar must never silently produce wrong state), and projected
+    into the graph before the post-snapshot suffix replays. Id
+    counters recorded at compact time prime the generators so fresh
+    mints can't collide with archived history.
+    """
+    from activegraph.core.graph import Object, Relation
+    from activegraph.store.retention import (
+        SnapshotIntegrityError,
+        state_hash_of,
+    )
+
+    payload = snapshot_event.payload or {}
+    expected = str(payload.get("state_hash", ""))
+    blob = store.get_snapshot(expected) if store is not None else None
+    if blob is None:
+        raise SnapshotIntegrityError(
+            run_id=graph.run_id,
+            expected=expected,
+            detail="the snapshot blob is missing from the sidecar table.",
+        )
+    if state_hash_of(blob) != expected:
+        raise SnapshotIntegrityError(
+            run_id=graph.run_id,
+            expected=expected,
+            detail="the stored blob does not hash to the recorded state hash.",
+        )
+    state = json.loads(blob)
+    for o in state.get("objects", []):
+        graph._state.put_object(  # noqa: SLF001 — the replay seam
+            Object(
+                id=o["id"],
+                type=o["type"],
+                data=o["data"],
+                version=o.get("version", 1),
+                provenance=o.get("provenance", {}),
+            )
+        )
+    for r in state.get("relations", []):
+        graph._state.put_relation(  # noqa: SLF001
+            Relation(
+                id=r["id"],
+                source=r["source"],
+                target=r["target"],
+                type=r["type"],
+                data=r.get("data", {}),
+                provenance=r.get("provenance", {}),
+            )
+        )
+    counters = payload.get("id_counters", {})
+    ids = graph.ids
+    ids._object_counter = max(ids._object_counter, int(counters.get("object", 0)))  # noqa: SLF001
+    ids._event_counter = max(ids._event_counter, int(counters.get("event", 0)))  # noqa: SLF001
+    ids._relation_counter = max(ids._relation_counter, int(counters.get("relation", 0)))  # noqa: SLF001
+    ids._patch_counter = max(ids._patch_counter, int(counters.get("patch", 0)))  # noqa: SLF001
+    ids._frame_counter = max(ids._frame_counter, int(counters.get("frame", 0)))  # noqa: SLF001
+
+
 def _rebuild_pending_approvals(rt: "Runtime", events: list[Event]) -> None:
     """Reconstruct the pending-approval queue from the event log. v1.4.