activegraph 1.4.0__tar.gz → 1.6.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: activegraph
-Version: 1.4.0
+Version: 1.6.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.4.0 → activegraph-1.6.0}/activegraph/__init__.py

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

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

@@ -27,6 +27,9 @@ from __future__ import annotations
 import copy
 import inspect
 import json
+import logging
+import sys
+from pathlib import Path
 from typing import TYPE_CHECKING, Any, Callable, Optional
 
 from pydantic import BaseModel, ValidationError
@@ -309,9 +312,114 @@ def load_pack_into_runtime(
             timestamp=rt.graph.clock.now(),
         )
     )
+
+    # ---- 6. manifest warning tier (CONTRACT v1.6 #1) ----------------------
+    _warn_on_manifest_violations(pack)
     return True
 
 
+# --------------------------------------------- manifest warning tier
+# CONTRACT v1.6 #1: when a manifest.toml is discoverable next to the
+# pack's defining modules, load_pack runs load_manifest +
+# verify_surface and WARNs on violations — structured, once per pack
+# per process, never an error before 2.0. Absent manifest: silent.
+# Hash verification (content/bundle) stays host/CI territory: the
+# loader never re-hashes a pack directory on the hot path.
+
+_manifest_log = logging.getLogger("activegraph.packs.manifest")
+
+# (pack name, pack version, manifest path) triples already validated
+# this process — clean or not, the tier runs once per pack.
+_manifest_checked: set[tuple[str, str, str]] = set()
+
+
+def _locate_pack_manifest(pack: Pack) -> Optional[Path]:
+    """Best-effort pack-root discovery: resolve the modules that define
+    the pack's components and walk up (while still inside the package)
+    looking for a sibling ``manifest.toml``. Returns None when the
+    pack has no discoverable manifest — which is not a violation.
+    """
+    components: list[Any] = [getattr(b, "fn", None) for b in pack.behaviors]
+    components += [getattr(t, "fn", None) for t in pack.tools]
+    if pack.settings_schema is not EmptySettings:
+        components.append(pack.settings_schema)
+    components += [ot.schema for ot in pack.object_types]
+
+    seen_modules: set[str] = set()
+    for comp in components:
+        mod_name = getattr(comp, "__module__", None)
+        if not mod_name or mod_name == "__main__" or mod_name in seen_modules:
+            continue
+        seen_modules.add(mod_name)
+        mod_file = getattr(sys.modules.get(mod_name), "__file__", None)
+        if not mod_file:
+            continue
+        directory = Path(mod_file).resolve().parent
+        while True:
+            candidate = directory / "manifest.toml"
+            if candidate.is_file():
+                return candidate
+            # Stop once we step outside the package: the manifest
+            # lives at the pack root, and the pack root is a package.
+            if not (directory / "__init__.py").is_file():
+                break
+            if directory.parent == directory:
+                break
+            directory = directory.parent
+    return None
+
+
+def _warn_on_manifest_violations(pack: Pack) -> None:
+    """The warning tier itself. Never raises: a broken manifest (or a
+    bug in discovery) must not break ``load_pack`` before 2.0.
+    """
+    try:
+        manifest_path = _locate_pack_manifest(pack)
+        if manifest_path is None:
+            return  # no manifest: silent, per the Q2 schedule
+        key = (pack.name, pack.version, str(manifest_path))
+        if key in _manifest_checked:
+            return
+        _manifest_checked.add(key)
+        from activegraph.packs.manifest import (
+            PackManifestError,
+            load_manifest,
+            verify_surface,
+        )
+
+        try:
+            manifest = load_manifest(manifest_path)
+            verify_surface(manifest, pack)
+        except PackManifestError as err:
+            _manifest_log.warning(
+                "pack %s@%s: manifest.toml found at %s but validation "
+                "failed with %d violation(s). The pack still loads — "
+                "this stays a warning until activegraph 2.0. First "
+                "violation: %s",
+                pack.name,
+                pack.version,
+                manifest_path,
+                len(err.violations),
+                err.violations[0] if err.violations else "",
+                extra={
+                    "pack": pack.name,
+                    "pack_version": pack.version,
+                    "manifest_path": str(manifest_path),
+                    "violations": list(err.violations),
+                    "reason": "pack.manifest_invalid",
+                },
+            )
+    except Exception:
+        # The tier is advisory; discovery/IO surprises are debug noise,
+        # not load failures.
+        _manifest_log.debug(
+            "manifest warning tier errored for pack %s@%s",
+            pack.name,
+            pack.version,
+            exc_info=True,
+        )
+
+
 # ---------------------------------------------------------------- state
 
 

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

@@ -2550,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)
@@ -2707,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)
@@ -3416,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,
@@ -3538,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.
 

activegraph-1.6.0/activegraph/sandbox/__init__.py

@@ -0,0 +1,257 @@
+"""Subprocess fork-trial isolation. CONTRACT v1.5 #1.
+
+Implements ``trial-isolation-design.md``: candidate pack code trials
+run in a **fresh interpreter**, against a fork of the parent run,
+materialized from artifacts pinned by the bundle hash — so the parent
+process is out of the blast radius of the T1 accident class (runaway
+memory/CPU, corrupted in-process state) and the bytes trialed are the
+bytes the proposal recorded.
+
+The division of authority is the design's:
+
+  * **The parent forks.** The child receives only the fork's run id —
+    it never gets fork authority, and it appends only to that run.
+  * **The child is a fresh interpreter** (``sys.executable -m
+    activegraph.sandbox._child``), not ``os.fork()`` — no inherited
+    Python state, no shared clients. Environment is allow-list only.
+  * **Three independent nets**: ``resource.setrlimit`` (address
+    space + CPU, POSIX; degrade to the other two nets on Windows),
+    parent-side wall-clock kill, and the runtime's own event/LLM
+    budgets inside the child.
+  * **The store is the record.** The child's stdout tail is a signal;
+    the parent re-reads the fork run from the store and the store's
+    numbers win any disagreement.
+
+HONEST LIMITS (the design's §5, restated where users will read it):
+this is crash/state isolation, **not a security sandbox**. A fresh
+interpreter with rlimits does not stop a malicious candidate from
+opening sockets or reading the filesystem — syscall and network
+confinement are host territory (containers, seccomp), and this module
+does not imitate them. The child can also, in principle, open the
+shared SQLite file directly and touch other runs; per-run
+authorization inside one SQLite file is not something SQLite gives us
+honestly, so that caveat is stated rather than solved. The evolution
+pack's static gates remain the pre-execution filter.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+
+#: The closed outcome set. ``crashed`` is the implementation's one
+#: addition over the design draft: a child that dies without a
+#: parseable tail (segfault, os._exit, kill) is reported as what it
+#: is, never guessed into a neater bucket.
+TRIAL_OUTCOMES = (
+    "completed",
+    "scenario_failed",
+    "limits_exceeded",
+    "materialization_failed",
+    "crashed",
+)
+
+# Child exit codes, mirrored in _child.py. Anything else → crashed.
+_EXIT_TO_OUTCOME = {
+    0: "completed",
+    30: "scenario_failed",
+    40: "limits_exceeded",
+    50: "materialization_failed",
+}
+
+
+@dataclass(frozen=True)
+class PackSource:
+    """Where the child materializes the candidate pack from.
+
+    ``expected_bundle_hash`` is the external pin (the §4 walk WITH
+    ``manifest.toml``, per the v1.4 bundle-hash amendment) — the child
+    verifies it via ``activegraph.packs.manifest.verify_bundle_hash``
+    before importing anything, so the bytes trialed are the bytes the
+    proposal recorded. ``manifest_required=True`` additionally runs
+    ``load_manifest`` + ``verify_surface`` against the live ``Pack``,
+    making the trial child the first consumer of the full manifest
+    chain end-to-end.
+    """
+
+    root_dir: str
+    expected_bundle_hash: str = ""
+    manifest_required: bool = True
+
+
+@dataclass(frozen=True)
+class TrialLimits:
+    """The trial's resource nets. Zero/None disables a given net.
+
+    ``max_llm_calls=0`` (the default) means key-freedom is
+    STRUCTURAL: the child configures no LLM provider at all, so a
+    candidate with LLM behaviors fails loud at registration
+    (``MissingProviderError``) rather than reaching a network. A
+    positive cap is accepted and recorded for a future
+    provider-wiring seam; the v1 child never configures a live
+    provider either way. ``env_passthrough`` is the ONLY parent environment
+    forwarded beyond interpreter mechanics (PATH/PYTHONPATH) — the
+    helper never forwards the environment wholesale, so parent API
+    keys don't leak into candidate code by default.
+    """
+
+    wall_clock_seconds: float = 120.0
+    max_rss_bytes: Optional[int] = None
+    max_events: Optional[int] = 2_000
+    max_llm_calls: Optional[int] = 0
+    env_passthrough: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class TrialReport:
+    """What a trial produced. Store-derived numbers, child-signaled shape.
+
+    ``events_appended`` and ``behavior_failures`` are re-read from the
+    fork's run in the store by the parent AFTER the child exits — the
+    stdout tail is a signal only, and any disagreement resolves in
+    favor of the store. Richer evidence (tracebacks, diffs) is read
+    from the fork's log directly: ``Runtime.load(store, run_id=
+    report.fork_run_id)`` then ``trace.failures()`` / ``diff()``.
+    """
+
+    outcome: str
+    fork_run_id: str
+    events_appended: int
+    behavior_failures: int
+    detail: str
+    exit_code: Optional[int]
+
+
+def run_forked_trial(
+    store_path: str,
+    *,
+    parent_run_id: str,
+    at_event: str,
+    pack_source: PackSource,
+    scenario: str = "",
+    limits: TrialLimits = TrialLimits(),
+    label: str = "trial",
+) -> TrialReport:
+    """Fork the parent at ``at_event`` and trial the candidate pack in
+    a fresh subprocess. CONTRACT v1.5 #1.
+
+    The fork is created HERE, in the parent process, with full
+    ``fork()`` semantics (lineage recorded, promote-block cut guard);
+    the child receives only the fork's run id. ``scenario`` is
+    ``"relative/path.py"`` or ``"relative/path.py::func"`` inside the
+    pack root — the function (default ``main``) is called with the
+    fork's ``Runtime`` and drives the trial; empty means just
+    ``run_until_idle()``. The scenario contract is
+    ``def main(rt): ...``.
+
+    Deterministic and key-free by default (``max_llm_calls=0``, empty
+    environment pass-through). Returns a :class:`TrialReport`; never
+    raises for in-trial failures — those are outcomes. Raises only
+    for parent-side setup problems (bad store, bad fork point), with
+    the same errors ``Runtime.load`` / ``fork()`` raise.
+    """
+    from activegraph.runtime.runtime import Runtime
+
+    parent_rt = Runtime.load(store_path, run_id=parent_run_id, behaviors=[])
+    fork_rt = parent_rt.fork(at_event=at_event, label=label, behaviors=[])
+    fork_run_id = fork_rt.run_id
+    initial_events = len(fork_rt.graph.events)
+    del fork_rt  # the child owns the fork from here
+
+    job = {
+        "store_path": store_path,
+        "fork_run_id": fork_run_id,
+        "initial_events": initial_events,
+        "pack_root": str(Path(pack_source.root_dir).resolve()),
+        "expected_bundle_hash": pack_source.expected_bundle_hash,
+        "manifest_required": pack_source.manifest_required,
+        "scenario": scenario,
+        "limits": {
+            "max_rss_bytes": limits.max_rss_bytes,
+            "max_events": limits.max_events,
+            "max_llm_calls": limits.max_llm_calls,
+            "cpu_seconds": int(limits.wall_clock_seconds) + 5,
+        },
+    }
+    env = {
+        key: os.environ[key]
+        for key in ("PATH", "PYTHONPATH", "HOME", "LANG")
+        if key in os.environ
+    }
+    for key in limits.env_passthrough:
+        if key in os.environ:
+            env[key] = os.environ[key]
+
+    proc = subprocess.Popen(
+        [sys.executable, "-m", "activegraph.sandbox._child"],
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.DEVNULL,
+        env=env,
+        text=True,
+    )
+    try:
+        stdout, _ = proc.communicate(
+            input=json.dumps(job), timeout=limits.wall_clock_seconds
+        )
+        exit_code: Optional[int] = proc.returncode
+        timed_out = False
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        stdout, _ = proc.communicate()
+        exit_code = proc.returncode
+        timed_out = True
+
+    tail: dict[str, object] = {}
+    for line in reversed((stdout or "").strip().splitlines()):
+        try:
+            parsed = json.loads(line)
+            if isinstance(parsed, dict) and "outcome" in parsed:
+                tail = parsed
+                break
+        except json.JSONDecodeError:
+            continue
+
+    if timed_out:
+        outcome = "limits_exceeded"
+        detail = (
+            f"wall clock exceeded {limits.wall_clock_seconds}s; child killed"
+        )
+    elif tail:
+        outcome = str(tail.get("outcome", "crashed"))
+        if outcome not in TRIAL_OUTCOMES:
+            outcome = "crashed"
+        detail = str(tail.get("detail", ""))
+    else:
+        outcome = _EXIT_TO_OUTCOME.get(exit_code or -1, "crashed")
+        if outcome == "completed":
+            # Exit 0 with no tail is itself suspicious; say so.
+            outcome = "crashed"
+        detail = f"child exited {exit_code} with no report tail"
+
+    # The store is the record: re-read the fork run for the numbers.
+    events_appended = 0
+    behavior_failures = 0
+    try:
+        fork_view = Runtime.load(store_path, run_id=fork_run_id, behaviors=[])
+        events_appended = max(
+            0, len(fork_view.graph.events) - initial_events
+        )
+        behavior_failures = len(fork_view.trace.failures())
+    except Exception as e:  # noqa: BLE001 — report, never mask the trial
+        detail = f"{detail} (store re-read failed: {e})".strip()
+
+    return TrialReport(
+        outcome=outcome,
+        fork_run_id=fork_run_id,
+        events_appended=events_appended,
+        behavior_failures=behavior_failures,
+        detail=detail,
+        exit_code=exit_code,
+    )