activegraph 1.4.0__tar.gz → 1.5.0__tar.gz

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

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

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

{activegraph-1.4.0 → activegraph-1.5.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.5.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,
+    )

activegraph-1.5.0/activegraph/sandbox/_child.py

@@ -0,0 +1,234 @@
+"""The trial child: fresh-interpreter half of the sandbox. v1.5 #1.
+
+Reads one JSON job spec from stdin, applies rlimits, materializes the
+candidate pack from artifacts (bundle-hash-pinned, manifest-verified),
+loads the fork run, runs the scenario under budgets, and prints one
+JSON report line to stdout. Everything richer than the report tail is
+already in the store — the child's trial activity is ordinary events
+in the fork's run.
+
+Exit codes (mirrored in ``activegraph.sandbox._EXIT_TO_OUTCOME``):
+0 completed, 30 scenario_failed, 40 limits_exceeded,
+50 materialization_failed. Anything else reads as ``crashed``.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+import traceback
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+
+def _report(
+    outcome: str,
+    *,
+    fork_run_id: str,
+    events_appended: int,
+    behavior_failures: int,
+    detail: str,
+    exit_code: int,
+) -> None:
+    print(
+        json.dumps(
+            {
+                "outcome": outcome,
+                "fork_run_id": fork_run_id,
+                "events_appended": events_appended,
+                "behavior_failures": behavior_failures,
+                "detail": detail[:500],
+            }
+        ),
+        flush=True,
+    )
+    raise SystemExit(exit_code)
+
+
+def _apply_rlimits(limits: dict[str, Any]) -> None:
+    """POSIX resource caps; on platforms without ``resource`` the
+    wall-clock and budget nets still hold (stated in the design)."""
+    try:
+        import resource
+    except ImportError:  # pragma: no cover — Windows
+        return
+    max_rss = limits.get("max_rss_bytes")
+    if max_rss:
+        resource.setrlimit(resource.RLIMIT_AS, (max_rss, max_rss))
+    cpu = limits.get("cpu_seconds")
+    if cpu:
+        resource.setrlimit(resource.RLIMIT_CPU, (cpu, cpu))
+
+
+def _materialize_pack(job: dict[str, Any]) -> Any:
+    """Verify pins, then import the candidate and return its Pack.
+
+    Order is the design's §3: bundle hash BEFORE any import (the pin
+    covers manifest.toml per the v1.4 amendment), then manifest schema,
+    then import, then the two-way surface check against the live Pack.
+    """
+    from activegraph.packs import Pack
+    from activegraph.packs.manifest import (
+        load_manifest,
+        verify_bundle_hash,
+        verify_surface,
+    )
+
+    root = Path(job["pack_root"])
+    manifest = None
+    if job.get("expected_bundle_hash"):
+        verify_bundle_hash(job["expected_bundle_hash"], root)
+    if job.get("manifest_required", True):
+        manifest = load_manifest(root)
+
+    spec = importlib.util.spec_from_file_location(
+        manifest.name if manifest else root.name,
+        root / "__init__.py",
+        submodule_search_locations=[str(root)],
+    )
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"cannot import pack module at {root}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+
+    packs = [v for v in vars(module).values() if isinstance(v, Pack)]
+    if manifest is not None:
+        packs = [p for p in packs if p.name == manifest.name]
+    if len(packs) != 1:
+        raise RuntimeError(
+            f"pack module must expose exactly one module-level Pack"
+            f"{' named ' + manifest.name if manifest else ''}; "
+            f"found {len(packs)}"
+        )
+    pack = packs[0]
+    if manifest is not None:
+        verify_surface(manifest, pack)
+    return pack
+
+
+def _resolve_scenario(
+    root: Path, scenario: str
+) -> Optional[Callable[[Any], None]]:
+    if not scenario:
+        return None
+    path_part, _, func_name = scenario.partition("::")
+    func_name = func_name or "main"
+    scenario_path = (root / path_part).resolve()
+    spec = importlib.util.spec_from_file_location(
+        "_trial_scenario", scenario_path
+    )
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"cannot import scenario at {scenario_path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    fn = getattr(module, func_name, None)
+    if not callable(fn):
+        raise RuntimeError(
+            f"scenario {scenario!r} has no callable {func_name!r}"
+        )
+    return fn
+
+
+def main() -> None:
+    job = json.loads(sys.stdin.read())
+    fork_run_id = str(job["fork_run_id"])
+    initial = int(job.get("initial_events", 0))
+    _apply_rlimits(job.get("limits", {}))
+
+    def counts(rt: Any) -> tuple[int, int]:
+        return (
+            max(0, len(rt.graph.events) - initial),
+            len(rt.trace.failures()),
+        )
+
+    try:
+        pack = _materialize_pack(job)
+    except Exception as e:  # noqa: BLE001 — outcome, not crash
+        _report(
+            "materialization_failed",
+            fork_run_id=fork_run_id,
+            events_appended=0,
+            behavior_failures=0,
+            detail=f"{type(e).__name__}: {e}",
+            exit_code=50,
+        )
+
+    from activegraph.runtime.runtime import Runtime
+
+    budget: dict[str, Any] = {}
+    if job["limits"].get("max_events"):
+        budget["max_events"] = job["limits"]["max_events"]
+    # max_llm_calls=0 (the default) needs no budget dimension: the
+    # child configures NO llm_provider, so key-freedom is structural —
+    # an LLM behavior in the candidate fails loud at registration
+    # (MissingProviderError), it cannot silently reach a network. A
+    # positive cap is recorded for a future provider-wiring seam.
+    if job["limits"].get("max_llm_calls"):
+        budget["max_llm_calls"] = job["limits"]["max_llm_calls"]
+
+    rt = Runtime.load(
+        job["store_path"],
+        run_id=fork_run_id,
+        behaviors=[],
+        budget=budget or None,
+    )
+    rt.load_pack(pack)
+
+    try:
+        scenario_fn = _resolve_scenario(
+            Path(job["pack_root"]), job.get("scenario", "")
+        )
+        if scenario_fn is not None:
+            scenario_fn(rt)
+        else:
+            rt.run_until_idle()
+    except MemoryError:
+        appended, failures = counts(rt)
+        _report(
+            "limits_exceeded",
+            fork_run_id=fork_run_id,
+            events_appended=appended,
+            behavior_failures=failures,
+            detail="MemoryError under RLIMIT_AS",
+            exit_code=40,
+        )
+    except Exception as e:  # noqa: BLE001 — outcome, not crash
+        appended, failures = counts(rt)
+        _report(
+            "scenario_failed",
+            fork_run_id=fork_run_id,
+            events_appended=appended,
+            behavior_failures=failures,
+            detail=f"{type(e).__name__}: {e}\n"
+            + traceback.format_exc(limit=3),
+            exit_code=30,
+        )
+
+    appended, failures = counts(rt)
+    exhausted = any(
+        e.type == "runtime.budget_exhausted"
+        for e in rt.graph.events[initial:]
+    )
+    if exhausted:
+        _report(
+            "limits_exceeded",
+            fork_run_id=fork_run_id,
+            events_appended=appended,
+            behavior_failures=failures,
+            detail="trial budget exhausted (see runtime.budget_exhausted)",
+            exit_code=40,
+        )
+    _report(
+        "completed",
+        fork_run_id=fork_run_id,
+        events_appended=appended,
+        behavior_failures=failures,
+        detail="",
+        exit_code=0,
+    )
+
+
+if __name__ == "__main__":
+    main()