activegraph 1.6.0__tar.gz → 1.7.0__tar.gz

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

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

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

activegraph-1.7.0/activegraph/sandbox/__init__.py

@@ -0,0 +1,440 @@
+"""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.
+
+TWO CHANNELS, KEPT SEPARATE (v1.7, the Replit soak fix):
+
+  * **The environment allow-list stays CLOSED.** Only ``PATH``,
+    ``HOME``, ``LANG`` plus an explicit ``env_passthrough`` cross the
+    boundary. No ambient parent env — secrets, API keys, platform
+    config like ``REPLIT_*`` — leaks into a child running hostile
+    candidate code. This is a security control and does not widen.
+  * **Code location is an EXPLICIT channel, not an ambient one.** A
+    child must be able to import ``activegraph`` (and its deps) on any
+    box where the *parent* could — but on some platforms (Replit,
+    Nix) the package is discoverable only via a platform env var the
+    allow-list correctly strips, so a naive child dies at import
+    before running. The parent therefore RESOLVES the ``sys.path``
+    entries that make its own code importable and passes them to the
+    child as a computed ``PYTHONPATH`` (see :func:`_child_env`).
+    ``PYTHONPATH`` is thus derived from the parent's resolved
+    ``sys.path``, never forwarded from ambient env — code locations
+    are not secrets, and making the child's discovery of its own code
+    an explicit input keeps the allow-list closed while fixing the
+    restricted-env break. Call :func:`preflight` once at boot to
+    verify a child can start under this env and fail loud if not.
+
+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 ambient parent
+    environment forwarded beyond the closed allow-list
+    (``PATH``/``HOME``/``LANG``) — the helper never forwards the
+    environment wholesale, so parent API keys don't leak into
+    candidate code by default. The child's ``PYTHONPATH`` is NOT an
+    ambient forward: it is computed from the parent's resolved
+    ``sys.path`` so the child can import its own code (see the module
+    docstring's "two channels").
+    """
+
+    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]
+
+
+class SandboxStartupError(RuntimeError):
+    """A trial child could not START under the sandbox env.
+
+    Raised by :func:`preflight` when the child fails before it can run
+    any trial — the common cause is the sandbox env being unable to
+    import ``activegraph`` on this box (the exact restricted-env break
+    the explicit package-path channel exists to prevent). The message
+    carries the child's stderr tail so the cause is never opaque.
+    """
+
+
+def _child_code_paths() -> list[str]:
+    """The ``sys.path`` entries a child needs to import the parent's
+    code, resolved in the parent (v1.7 explicit package-path channel).
+
+    ``activegraph``'s own root comes first, resolved from
+    ``activegraph.__file__`` — this is what an editable install or a
+    platform that surfaces packages via a stripped env var (Replit's
+    ``REPLIT_PYTHONPATH``) would otherwise hide from the child. The
+    parent's real ``sys.path`` directories follow so third-party deps
+    resolve too. Non-directory entries (namespace-finder hooks, the
+    empty CWD entry, zip imports) are dropped: they either don't help
+    a fresh child or would import from its CWD, which we do not want.
+    """
+    import activegraph
+
+    ordered: list[str] = []
+    ag_root = str(Path(activegraph.__file__).resolve().parent.parent)
+    ordered.append(ag_root)
+    for entry in sys.path:
+        if entry and os.path.isdir(entry) and entry not in ordered:
+            ordered.append(entry)
+    return ordered
+
+
+def _child_env(limits: TrialLimits) -> dict[str, str]:
+    """Build the child's environment: closed allow-list + the computed
+    ``PYTHONPATH`` code channel. See the module docstring's "two
+    channels".
+
+    The allow-list is ``PATH``/``HOME``/``LANG`` plus the caller's
+    explicit ``env_passthrough`` — no other ambient env crosses. Then
+    ``PYTHONPATH`` is set from :func:`_child_code_paths` (the parent's
+    resolved code locations), prepended before any ``PYTHONPATH`` the
+    caller opted to pass through, so the child imports the same code
+    the parent can regardless of platform package discovery.
+    """
+    env = {
+        key: os.environ[key]
+        for key in ("PATH", "HOME", "LANG")
+        if key in os.environ
+    }
+    for key in limits.env_passthrough:
+        if key in os.environ:
+            env[key] = os.environ[key]
+    channel = os.pathsep.join(_child_code_paths())
+    passed_through = env.get("PYTHONPATH", "")
+    env["PYTHONPATH"] = (
+        channel + os.pathsep + passed_through if passed_through else channel
+    )
+    return env
+
+
+def _stderr_tail(stderr: str, *, max_lines: int = 20, max_chars: int = 1500) -> str:
+    """The last few lines of a child's stderr, capped — the actual
+    cause of a pre-``_report`` crash the DEVNULL default used to lose.
+    """
+    text = (stderr or "").strip()
+    if not text:
+        return ""
+    lines = text.splitlines()[-max_lines:]
+    tail = "\n".join(lines)
+    return tail[-max_chars:]
+
+
+def _parse_report_tail(stdout: str) -> dict[str, object]:
+    """The child's last valid JSON report line, or ``{}``."""
+    for line in reversed((stdout or "").strip().splitlines()):
+        try:
+            parsed = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(parsed, dict) and (
+            "outcome" in parsed or "preflight" in parsed
+        ):
+            return parsed
+    return {}
+
+
+def _run_child(
+    job: dict[str, object],
+    *,
+    env: dict[str, str],
+    wall_clock: float,
+    python_flags: tuple[str, ...] = (),
+) -> tuple[Optional[int], str, str, bool]:
+    """Spawn the trial child, feed it ``job`` on stdin, and return
+    ``(exit_code, stdout, stderr, timed_out)``.
+
+    Shared by :func:`run_forked_trial` and :func:`preflight`. stderr is
+    PIPED (never DEVNULL) so a pre-``_report`` crash's cause survives.
+    ``python_flags`` is an interpreter-flag seam used by tests to
+    reproduce a restricted env (``-S``); production passes none.
+    """
+    proc = subprocess.Popen(
+        [sys.executable, *python_flags, "-m", "activegraph.sandbox._child"],
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        env=env,
+        text=True,
+    )
+    try:
+        stdout, stderr = proc.communicate(
+            input=json.dumps(job), timeout=wall_clock
+        )
+        return proc.returncode, stdout, stderr, False
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        stdout, stderr = proc.communicate()
+        return proc.returncode, stdout, stderr, True
+
+
+def _preflight_with(
+    env: dict[str, str],
+    *,
+    python_flags: tuple[str, ...] = (),
+    timeout: float = 30.0,
+) -> None:
+    """The preflight check against a specific ``env`` (the testable
+    seam under :func:`preflight`). Raises :class:`SandboxStartupError`
+    if a child cannot start and report ``preflight: ok``.
+    """
+    exit_code, stdout, stderr, timed_out = _run_child(
+        {"preflight": True}, env=env, wall_clock=timeout, python_flags=python_flags
+    )
+    tail = _parse_report_tail(stdout)
+    if not timed_out and exit_code == 0 and tail.get("preflight") == "ok":
+        return
+    cause = _stderr_tail(stderr) or (
+        "child timed out" if timed_out else "no preflight tail on stdout"
+    )
+    raise SandboxStartupError(
+        f"trial child could not start (exit {exit_code}): {cause}"
+    )
+
+
+def preflight(*, limits: TrialLimits = TrialLimits(), timeout: float = 30.0) -> None:
+    """Verify a trial child can START under the sandbox env on this box.
+
+    Spawns the child with a null job (no fork, no store, no candidate):
+    it imports ``activegraph``, echoes ``preflight: ok``, and exits 0.
+    Returns ``None`` on success; raises :class:`SandboxStartupError`
+    with the child's stderr tail otherwise. Consumers call this once at
+    boot so a broken sandbox env (e.g. a platform whose package
+    discovery the allow-list strips) fails LOUD here instead of showing
+    up as an opaque ``crashed`` on the first real trial.
+    """
+    _preflight_with(_child_env(limits), timeout=timeout)
+
+
+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",
+    extra_packs: tuple[PackSource, ...] = (),
+) -> 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
+    CANDIDATE's 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): ...``.
+
+    **The default is candidate-only isolation**: the child loads
+    nothing but the candidate, so the trial exercises it apart from
+    every other pack's behaviors. ``extra_packs`` is the opt-in for
+    cross-pack interaction trials (CONTRACT v1.5 #1 addendum 1b):
+    each entry is materialized in the child exactly like the
+    candidate — bundle hash verified before import, manifest schema
+    + two-way surface check when required — and loaded, in order,
+    BEFORE the candidate. Any extra pack failing its pins is
+    ``materialization_failed`` for the whole trial; the scenario
+    still resolves inside the candidate's root only.
+
+    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,
+        "extra_packs": [
+            {
+                "pack_root": str(Path(p.root_dir).resolve()),
+                "expected_bundle_hash": p.expected_bundle_hash,
+                "manifest_required": p.manifest_required,
+            }
+            for p in extra_packs
+        ],
+        "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,
+        },
+    }
+    exit_code, stdout, stderr, timed_out = _run_child(
+        job, env=_child_env(limits), wall_clock=limits.wall_clock_seconds
+    )
+    tail = _parse_report_tail(stdout)
+
+    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 pre-execution gate must never swallow its own failure cause:
+    # when the child crashed before it could _report (module-import
+    # failure, rlimit setup, anything pre-main), the actual exception
+    # is on the child's stderr, not in any tail. Fold it into detail so
+    # it reaches the caller's recorded gate_result (v1.7 fix 1).
+    if outcome == "crashed":
+        err_tail = _stderr_tail(stderr)
+        if err_tail:
+            detail = f"{detail}; child stderr:\n{err_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.6.0 → activegraph-1.7.0}/activegraph/sandbox/_child.py

@@ -62,11 +62,15 @@ def _apply_rlimits(limits: dict[str, Any]) -> None:
 
 
 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.
+    """Verify pins, then import one pack source and return its Pack.
+
+    ``job`` carries ``pack_root`` / ``expected_bundle_hash`` /
+    ``manifest_required`` — the top-level job spec for the candidate,
+    or one ``extra_packs`` entry (v1.7 addendum 1b), which uses the
+    identical chain. 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 (
@@ -133,6 +137,16 @@ def _resolve_scenario(
 
 def main() -> None:
     job = json.loads(sys.stdin.read())
+
+    # Preflight (v1.7): a null job that only proves the child could
+    # START — i.e. that importing activegraph under the sandbox env
+    # succeeded, which happens before this function even runs. Reaching
+    # here at all means the heavy import chain worked; echo the marker
+    # and exit clean. No fork, no store, no candidate touched.
+    if job.get("preflight"):
+        print(json.dumps({"preflight": "ok"}), flush=True)
+        raise SystemExit(0)
+
     fork_run_id = str(job["fork_run_id"])
     initial = int(job.get("initial_events", 0))
     _apply_rlimits(job.get("limits", {}))
@@ -144,6 +158,9 @@ def main() -> None:
         )
 
     try:
+        # Extra packs first (addendum 1b): each pinned and verified
+        # exactly like the candidate, loaded before it below.
+        extra = [_materialize_pack(p) for p in job.get("extra_packs", [])]
         pack = _materialize_pack(job)
     except Exception as e:  # noqa: BLE001 — outcome, not crash
         _report(
@@ -174,6 +191,8 @@ def main() -> None:
         behaviors=[],
         budget=budget or None,
     )
+    for trusted in extra:
+        rt.load_pack(trusted)
     rt.load_pack(pack)
 
     try:

{activegraph-1.6.0 → activegraph-1.7.0}/activegraph/store/retention.py

@@ -2,7 +2,7 @@
 
 CONTRACT v1.5 #2, phase 1 of ``compaction-design.md``. Three offline
 operations over a SQLite store (no self-compaction under a live
-dispatcher — run these against a store no runtime is attached to):
+dispatcher — run these against runs no runtime is attached to):
 
   * :func:`compact` — emit a ``runtime.snapshot`` event capturing the
     run's projected state, store the blob in the snapshot sidecar,
@@ -26,6 +26,40 @@ horizon stop at it); there is no CLI yet; and patch records from the
 archived prefix are not reconstructed after compaction (``compact``
 refuses runs with patches still in ``proposed`` status, and applied/
 rejected patch history remains queryable via the archive).
+
+**What "offline" means — the attachment rule is per-RUN, not
+per-file** (v1.6.x ruling; CONTRACT v1.5 #2 addendum 2b). These
+operations must not run against a run that has a live runtime
+attached; OTHER runs in the same store file may hold live runtimes
+throughout. Why that is safe, from the implementation: every event-
+row statement is scoped ``WHERE run_id = ?``; the store runs in WAL
+mode, so the readers these functions open never block a live run's
+writer and never see torn state; a live runtime appends via single-
+statement autocommit transactions and never re-reads its own log
+mid-dispatch; and the archive move is one short ``BEGIN IMMEDIATE``
+transaction that a contending writer simply waits out (sqlite3's
+default 5-second busy timeout — exhausted, it raises
+``OperationalError``, never corrupting). What per-run attachment
+actually protects against is the SAME-run case: a runtime attached
+to the run being compacted mints the same event id as the snapshot
+event (``UNIQUE(id, run_id)`` — ``IntegrityError``) and never learns
+the horizon exists; a runtime attached to a run being retired would
+keep appending to a log the operator believes empty.
+
+Two caveats stay the caller's responsibility:
+
+  * ``pins`` → archive is check-then-act, not one atomic unit. Do
+    not race a pin-creating operation against retirement of the
+    same run — a promote from the fork, or a new fork of it, landing
+    between the pin check and the archive move would be archived-
+    while-pinned. Retire after decisions on that run are final. (A
+    lost race degrades audit walks — ``causal_chain`` does not read
+    the archive — but destroys no bytes: archiving is a move, and
+    the rows stay readable via ``iter_archived``.)
+  * A very large run's archive move holds the write lock for the
+    duration of its one transaction; a concurrent writer that
+    exhausts its busy timeout gets ``OperationalError``, not
+    corruption. Size housekeeping windows accordingly.
 """
 
 from __future__ import annotations
@@ -148,6 +182,10 @@ def pins(path: str, run_id: str) -> list[str]:
     Empty list = unpinned. The same computation the refusals in
     :func:`compact` / :func:`retire` run — design §5's "why can't I
     retire this run?" API.
+
+    Read-only, safe to call while any run in the file holds a live
+    runtime (WAL readers never block or tear). The answer is
+    point-in-time: a pin created after it returns is not in it.
     """
     reasons: list[str] = []
     store = SQLiteEventStore(path, run_id=run_id)
@@ -220,8 +258,12 @@ def compact(path: str, run_id: str) -> str:
     design's crash-safe one: snapshot event, then blob, then the
     archive move (idempotent). Returns the snapshot event id.
 
-    Offline operation: run against a store no live runtime is
-    attached to.
+    Offline operation, per-RUN: no live runtime may be attached to
+    ``run_id`` itself — the snapshot event would collide with the
+    ids a live runtime mints (``UNIQUE(id, run_id)``), and that
+    runtime's projection would never learn the horizon exists. Other
+    runs in the same file may hold live runtimes; see the module
+    docstring for the full reasoning.
     """
     reasons = pins(path, run_id)
     if reasons:
@@ -272,6 +314,16 @@ def retire(path: str, run_id: str) -> int:
 
     The typical subject is a rejected fork trial that was never
     promoted. Pinned runs refuse with the full reason list.
+
+    Offline operation, per-RUN: no live runtime may be attached to
+    ``run_id`` itself, and no pin-creating operation (a promote from
+    this run, a fork of it) may race the retirement. Other runs in
+    the same file may hold live runtimes throughout — retiring a
+    finished fork while the parent run's runtime is live is
+    sanctioned usage (see the module docstring for the transaction
+    reasoning, and ``test_compaction.py``'s
+    ``test_retire_fork_per_run_while_parent_runtime_is_live`` for
+    the pinned behavior).
     """
     reasons = pins(path, run_id)
     if reasons:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: activegraph
-Version: 1.6.0
+Version: 1.7.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.6.0 → activegraph-1.7.0}/pyproject.toml

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

{activegraph-1.6.0 → activegraph-1.7.0}/tests/test_compaction.py

@@ -181,6 +181,41 @@ def test_unpromoted_rejected_fork_retires_cleanly(tmp_path):
     assert len(parent_view.graph.events) == n_parent
 
 
+def test_retire_fork_per_run_while_parent_runtime_is_live(tmp_path):
+    # The downstream housekeeping pattern (v1.6.x ruling, CONTRACT
+    # v1.5 #2 addendum 2b): the offline rule is per-RUN, not
+    # per-file. pins()/retire() on a finished fork run while the
+    # PARENT run holds a live runtime on the same SQLite file is
+    # sanctioned — WAL + per-run row scoping + single-statement
+    # appends. What stays forbidden is a runtime attached to the run
+    # being retired/compacted itself.
+    path, parent = _seeded_runtime(tmp_path)
+    rejected = parent.fork(at_event=parent.trace.events()[-1].id)
+    rejected.graph.add_object("note", {"text": "never adopted"})
+    fork_run = rejected.run_id
+    n_fork = len(rejected.graph.events)
+    del rejected  # trial over: nothing attached to the FORK run
+
+    # Parent stays LIVE — attached store connection, no teardown.
+    assert pins(path, fork_run) == []
+    moved = retire(path, fork_run)
+    assert moved == n_fork
+
+    # The live parent keeps working through its open attachment:
+    # appends land, save succeeds, nothing about its run was touched.
+    parent.run_goal("second")
+    parent.save_state(path)
+    n_parent = len(parent.graph.events)
+
+    store = SQLiteEventStore(path, run_id=fork_run)
+    assert list(store.iter_events()) == []
+    assert store.has_archived()  # moved, never deleted
+    reloaded = Runtime.load(path, run_id=parent.run_id, behaviors=[])
+    assert len(reloaded.graph.events) == n_parent
+    # And the retired fork no longer pins the still-live parent.
+    assert not any("live-lineage" in r for r in pins(path, parent.run_id))
+
+
 def test_live_lineage_pins_the_parent_until_children_retire(tmp_path):
     path, parent = _seeded_runtime(tmp_path)
     child = parent.fork(at_event=parent.trace.events()[-1].id)