loop-engineer 0.9.0__tar.gz → 0.10.0__tar.gz

{loop_engineer-0.9.0 → loop_engineer-0.10.0}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "loop-engineer",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Design, launch, verify, repair, and improve agent loops. A Claude-Code-native architect+operator for long-running, verifiable, self-improving agentic-coding systems.",
   "author": {
     "name": "Sollan Systems",

{loop_engineer-0.9.0 → loop_engineer-0.10.0}/CHANGELOG.md

@@ -14,6 +14,90 @@ All notable changes to `loop-engineer` are documented here.
   `WORKFLOW.md` and `README.md` are reworded to describe the mechanism; the 0.3.4
   history is left intact.
 
+## 0.10.0 — 2026-07-25
+
+**The hash-linked event chain.** Every `loop-engineer/event@1` row now carries
+`prev_event_hash` and `event_hash` — a sha256 over a canonical JSON preimage of
+the event's hashed fields, `prev_event_hash` among them. Canonical form is
+`json.dumps(sort_keys=True, separators=(",", ":"), ensure_ascii=False,
+allow_nan=False)` encoded UTF-8, pinned normatively with conformance vectors in
+`reference/repo-os-contract.md` §16. The digest is computed **inside the store on
+append**, never supplied by a caller, and the deterministic reducer re-verifies
+each link as it folds: a spliced, reordered, or edited row raises
+`ChainBreakError` and stops the fold instead of projecting a plausible state.
+`loop.chain` is stdlib-only and imports no other module of this package, so
+`verify_chain()` re-verifies an exported event stream without the store code
+(#82).
+
+**Store generations and `loop migrate`.** A fresh store stamps `PRAGMA
+user_version = 2` and widens the `events` DDL with `event_hash TEXT NOT NULL`.
+`loop migrate` is the only store-upgrade path — explicit, idempotent, and
+non-rewriting: it adds the two columns and stamps `user_version = 2`, but never
+backfills hashes onto existing rows, because the append-only `BEFORE UPDATE`
+trigger forbids it. Pre-migration rows therefore stay an **unchained prefix**
+that doctor reports rather than elides, and the first post-migration append is a
+chain genesis.
+
+**Anchored doctor gate.** `loop doctor` gains an `event_store.chain` block
+(`head`, `unchained_prefix`) and a `--expect-chain-head SHA256` flag — also
+accepted by `validate` and `verify` — that fails the gate unless the store's head
+equals an externally remembered anchor. Four new issue codes: `event_chain_broken`
+(a link does not verify), `chain_anchor_mismatch` (the head differs from the
+supplied anchor, or an anchor was supplied with no readable store),
+`missing_event_store` (`events.db` is absent while SQLite sidecars remain — the
+store was deleted), and `chain_columns_missing` (the store still declares
+generation 2 with its chain columns gone — the lazy downgrade). The composite
+action publishes the observed head as a `chain-head` output on every run and
+optionally enforces one through an `expect-chain-head` input.
+
+**Integrity boundary.** The chain is **tamper-evident relative to an anchored
+head** — a detection property, not a prevention one, and scoped to the anchor.
+It detects splicing, reordering, an edit that does not recompute every downstream
+digest, and byte corruption of any hashed field; given an anchor it detects *any*
+divergence from the head that anchor names, including tail truncation, which is
+otherwise invisible because deleting trailing events leaves a shorter but
+internally valid chain. It does **not** detect a full in-workspace recompute, a
+chain-column downgrade that also resets `user_version`, deletion of the store when
+no sidecars remain and no anchor is supplied, well-formed lies (nothing in the
+chain judges whether a payload is true), or anything in a never-migrated prefix.
+And the window stays open at the head: "An anchor certifies the log only up to the
+anchored head. Everything appended after the last externally-read anchor —
+including a rewrite of the suffix — is unverified until the next anchor is read
+and remembered outside the workspace. The chain narrows the tampering window; it
+does not close it." `scripts/test_adversarial_chain.py` pins both sides — the
+attacks that are caught and four `PINNED LIMITATION` cases that are not. The full
+boundary, with the anchor's trust assumptions, is normative in
+`reference/repo-os-contract.md` §16.
+
+**Stricter reads.** `status`, `replay`, and `doctor` now **reject** a store
+containing any schema-invalid event, raising `invalid_event` instead of silently
+folding past it as they did in 0.9.0. Validation runs before the fold, so a tamper
+that also violates `event@1` surfaces as `invalid_event` rather than
+`event_chain_broken`.
+
+**Sidecars resolved.** Read verbs no longer leave `-wal`/`-shm` files beside a
+clean `.loop/events.db` — the 0.9.0 known limitation recorded below. #80 landed
+the first half, opening read-only connections with `immutable=1` when no WAL
+sidecar exists; this release completes it with a two-stage retry so that a lost
+`immutable=1` race against a live writer retries plainly as `mode=ro` before
+anything may be called corruption, the same read path in the runner, and a
+zero-carve-out tripwire proving every read verb leaves a clean store
+byte-identical on both store generations.
+
+**Compatibility, both directions.** Pre-0.10.0 *readers* can read a v2 store:
+their explicit ten-column `SELECT` is unaffected by the two added columns.
+Pre-0.10.0 *writers* must not append to a chained store. A fresh v0.10.0 store
+refuses such an append at the database, because `event_hash` is `NOT NULL`; a
+*migrated* store keeps its columns nullable, so the append succeeds and produces a
+permanent, unrepairable `event_chain_broken` — the row cannot be re-linked
+afterwards, since `UPDATE` is trigger-blocked. Pin your `loop-engineer` and action
+version per store.
+
+Test baseline: 1021 passed / 16 skipped with the `yaml`+`schemas` extras;
+951 / 86 in structural-fallback mode (PyYAML only). Both measured in a fresh
+worktree; a live checkout reads +2 passed / −2 skipped through two
+checked-when-present tests.
+
 ## 0.9.0 — 2026-07-17
 
 **The event-sourced kernel.** The contract gains a durable runtime substrate:
@@ -71,7 +155,7 @@ least-privilege workflow permissions (#46, #47).
 `-wal`/`-shm` sidecars next to `.loop/events.db` (read-only connections
 recreate them and cannot checkpoint on close). Store content is never
 mutated, but tree-byte-identity checks over a store-backed workspace will
-notice them.
+notice them. *(Resolved in 0.10.0 — see "Sidecars resolved" above.)*
 
 Test baseline: 933 passed / 16 skipped with the `yaml`+`schemas` extras;
 864 / 85 in structural-fallback mode (PyYAML only).

{loop_engineer-0.9.0 → loop_engineer-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loop-engineer
-Version: 0.9.0
+Version: 0.10.0
 Summary: Portable Loop Contract Core: validate and inspect repo-native operating contracts for agent loops.
 Project-URL: Homepage, https://github.com/SollanSystems/loop-engineer
 Project-URL: Repository, https://github.com/SollanSystems/loop-engineer
@@ -44,7 +44,7 @@ Description-Content-Type: text/markdown
 [![CI](https://github.com/SollanSystems/loop-engineer/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/SollanSystems/loop-engineer/actions/workflows/ci.yml)
 [![Python 3.10–3.12](https://img.shields.io/badge/python-3.10%E2%80%933.12-blue)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
-[![Release](https://img.shields.io/badge/release-0.9.0-blue)](https://github.com/SollanSystems/loop-engineer/tags)
+[![Release](https://img.shields.io/badge/release-0.10.0-blue)](https://github.com/SollanSystems/loop-engineer/tags)
 
 Long-running agents commit **false completion**. After context compaction they
 forget what "done" meant, optimize to the visible test, patch in circles, and
@@ -63,7 +63,11 @@ ships, on disk and runnable today:
 - an **event-sourced runtime** — `run`, `status`, `replay`, `simulate`, and
   approve/pause/resume/cancel over an append-only SQLite event log
   (`.loop/events.db`), folded by a deterministic reducer that enforces the same
-  completion gate as the writers, with crash-safe single-step resume.
+  completion gate as the writers, with crash-safe single-step resume. Events are
+  hash-chained; `loop doctor --expect-chain-head` verifies the log against an
+  externally anchored head. The chain is tamper-evident **relative to an
+  anchor** — an adversary with workspace write access can rewrite an unanchored
+  log.
 
 ![The inspector scores a self-asserted DIY loop 0/weak, then the gate-backed example 90/strong — both runs live](docs/demo.gif)
 
@@ -367,7 +371,7 @@ present. Recipe:
 **CI** — one workflow step validates the contract and publishes a scorecard:
 
 ```yaml
-- uses: SollanSystems/loop-engineer@v0.9.0
+- uses: SollanSystems/loop-engineer@v0.10.0
   with:
     path: "."
 ```
@@ -460,8 +464,8 @@ doctor` and the contract's own `verify-*` scripts).
 
 ## Status
 
-- Version: `0.9.0`
-- Release tag: `v0.9.0` (PyPI publish trigger; plugin tags through 0.6.0 used `loop-engineer--v<version>`)
+- Version: `0.10.0`
+- Release tag: `v0.10.0` (PyPI publish trigger; plugin tags through 0.6.0 used `loop-engineer--v<version>`)
 - License: MIT
 - Primary interface: Claude Code plugin
 - Portable core: Python CLI + JSON schemas

{loop_engineer-0.9.0 → loop_engineer-0.10.0}/README.md

@@ -5,7 +5,7 @@
 [![CI](https://github.com/SollanSystems/loop-engineer/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/SollanSystems/loop-engineer/actions/workflows/ci.yml)
 [![Python 3.10–3.12](https://img.shields.io/badge/python-3.10%E2%80%933.12-blue)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
-[![Release](https://img.shields.io/badge/release-0.9.0-blue)](https://github.com/SollanSystems/loop-engineer/tags)
+[![Release](https://img.shields.io/badge/release-0.10.0-blue)](https://github.com/SollanSystems/loop-engineer/tags)
 
 Long-running agents commit **false completion**. After context compaction they
 forget what "done" meant, optimize to the visible test, patch in circles, and
@@ -24,7 +24,11 @@ ships, on disk and runnable today:
 - an **event-sourced runtime** — `run`, `status`, `replay`, `simulate`, and
   approve/pause/resume/cancel over an append-only SQLite event log
   (`.loop/events.db`), folded by a deterministic reducer that enforces the same
-  completion gate as the writers, with crash-safe single-step resume.
+  completion gate as the writers, with crash-safe single-step resume. Events are
+  hash-chained; `loop doctor --expect-chain-head` verifies the log against an
+  externally anchored head. The chain is tamper-evident **relative to an
+  anchor** — an adversary with workspace write access can rewrite an unanchored
+  log.
 
 ![The inspector scores a self-asserted DIY loop 0/weak, then the gate-backed example 90/strong — both runs live](docs/demo.gif)
 
@@ -328,7 +332,7 @@ present. Recipe:
 **CI** — one workflow step validates the contract and publishes a scorecard:
 
 ```yaml
-- uses: SollanSystems/loop-engineer@v0.9.0
+- uses: SollanSystems/loop-engineer@v0.10.0
   with:
     path: "."
 ```
@@ -421,8 +425,8 @@ doctor` and the contract's own `verify-*` scripts).
 
 ## Status
 
-- Version: `0.9.0`
-- Release tag: `v0.9.0` (PyPI publish trigger; plugin tags through 0.6.0 used `loop-engineer--v<version>`)
+- Version: `0.10.0`
+- Release tag: `v0.10.0` (PyPI publish trigger; plugin tags through 0.6.0 used `loop-engineer--v<version>`)
 - License: MIT
 - Primary interface: Claude Code plugin
 - Portable core: Python CLI + JSON schemas

{loop_engineer-0.9.0 → loop_engineer-0.10.0}/action.yml

@@ -25,6 +25,18 @@ inputs:
     description: "Token for the optional PR scorecard comment. Empty skips the comment."
     required: false
     default: ""
+  expect-chain-head:
+    description: >-
+      Fail the gate unless the store's chain head equals this 64-hex value (an
+      externally remembered anchor). Empty performs NO cross-run tamper
+      detection — the gate then only records the head for a later comparison.
+    required: false
+    default: ""
+
+outputs:
+  chain-head:
+    description: "Chain head event_hash observed by this gate run ('' when the store has no chained events)."
+    value: ${{ steps.chain-head.outputs.chain-head }}
 
 runs:
   using: "composite"
@@ -50,12 +62,17 @@ runs:
       shell: bash
       env:
         LOOP_PATH: "${{ inputs.path }}"
+        LOOP_EXPECT_HEAD: "${{ inputs.expect-chain-head }}"
       run: |
         # -eo pipefail (GitHub's bash default) makes a doctor failure fail the step
         # despite the tee. Then assert the strict validation path actually ran, so a
         # future packaging regression that drops the extras fails loudly here. The
         # check reads one fixed field from doctor's own JSON — no fragile parsing.
-        loop doctor "$LOOP_PATH" | tee "${RUNNER_TEMP}/doctor.json"
+        if [ -n "$LOOP_EXPECT_HEAD" ]; then
+          loop doctor --expect-chain-head "$LOOP_EXPECT_HEAD" "$LOOP_PATH" | tee "${RUNNER_TEMP}/doctor.json"
+        else
+          loop doctor "$LOOP_PATH" | tee "${RUNNER_TEMP}/doctor.json"
+        fi
         python - "${RUNNER_TEMP}/doctor.json" <<'PY'
         import json, sys
         mode = json.load(open(sys.argv[1])).get("validation_mode")
@@ -65,6 +82,30 @@ runs:
             raise SystemExit(1)
         PY
 
+    - name: chain head (anchor surface)
+      id: chain-head
+      if: always()
+      shell: bash
+      run: |
+        # Runs even when doctor failed: an anchor MISMATCH is exactly the run whose
+        # observed head an operator needs recorded. Absent/empty doctor.json (doctor
+        # never got to write one) is a silent no-op, not an error.
+        [ -s "${RUNNER_TEMP}/doctor.json" ] || exit 0
+        python - "${RUNNER_TEMP}/doctor.json" "$GITHUB_STEP_SUMMARY" "$GITHUB_OUTPUT" <<'PY'
+        import json, sys
+        try:
+            doctor = json.load(open(sys.argv[1]))
+        except (OSError, json.JSONDecodeError):
+            doctor = {}
+        chain = (doctor.get("event_store") or {}).get("chain") or {}
+        head = chain.get("head") or {}
+        value = head.get("event_hash") or ""
+        line = (f"**loop-engineer chain head:** `{value}` (sequence {head.get('sequence')})"
+                if value else "**loop-engineer chain head:** none (no chained events)")
+        open(sys.argv[2], "a").write(line + "\n")
+        open(sys.argv[3], "a").write(f"chain-head={value}\n")
+        PY
+
     - name: loop inspect (scorecard)
       shell: bash
       env:

{loop_engineer-0.9.0 → loop_engineer-0.10.0}/loop/__main__.py

@@ -12,19 +12,20 @@ from .runcontrol import RunControlError
 
 _PROG = "python3 -m loop"
 
-_COMMANDS = ("scaffold", "doctor", "validate", "verify", "inspect", "metrics", "plan-lint", "status", "replay", "simulate", "run", "approve", "pause", "resume", "cancel", "architect")
+_COMMANDS = ("scaffold", "doctor", "validate", "verify", "inspect", "metrics", "plan-lint", "status", "replay", "simulate", "run", "approve", "pause", "resume", "cancel", "migrate", "architect")
 
 # Read commands operate on an EXISTING contract dir; scaffold CREATES one, so it
 # is exempt from the "target must exist" guard.
-_READ_COMMANDS = ("doctor", "validate", "verify", "inspect", "metrics", "plan-lint", "status", "replay", "simulate", "run", "approve", "pause", "resume", "cancel")
+_READ_COMMANDS = ("doctor", "validate", "verify", "inspect", "metrics", "plan-lint", "status", "replay", "simulate", "run", "approve", "pause", "resume", "cancel", "migrate")
 
-_USAGE = f"usage: {_PROG} <scaffold|doctor|validate|verify|inspect|metrics|plan-lint|status|replay|simulate|run|approve|pause|resume|cancel|architect> <target>"
+_USAGE = f"usage: {_PROG} <scaffold|doctor|validate|verify|inspect|metrics|plan-lint|status|replay|simulate|run|approve|pause|resume|cancel|migrate|architect> <target>"
 
 _HELP = f"""{_PROG} — validate, inspect, and measure a portable repo-OS loop contract.
 
 {_USAGE}
        {_PROG} metrics [--baseline] <workspace-or-.loop>
-       {_PROG} doctor|validate|verify [--mode basic|strict|release] <workspace-or-.loop>
+       {_PROG} doctor|validate|verify [--mode basic|strict|release]
+              [--expect-chain-head SHA256] <workspace-or-.loop>
        {_PROG} status [--mode basic|strict|release] <workspace>
        {_PROG} replay [--mode basic|strict|release] <workspace>
        {_PROG} simulate [--mode basic|strict|release] <workspace>
@@ -33,6 +34,7 @@ _HELP = f"""{_PROG} — validate, inspect, and measure a portable repo-OS loop c
        {_PROG} pause --reason REASON [--mode basic|strict|release] <workspace>
        {_PROG} resume [--note NOTE] [--mode basic|strict|release] <workspace>
        {_PROG} cancel [--reason REASON] [--mode basic|strict|release] <workspace>
+       {_PROG} migrate <workspace>
        {_PROG} plan-lint [--mode basic|strict|release] <plan-file>
 
 commands:
@@ -57,6 +59,7 @@ commands:
   pause      Pause a non-terminal run.
   resume     Resume a paused run.
   cancel     Terminate a non-terminal run as AbortedByHuman.
+  migrate    Add hash-chain columns to a legacy events.db (explicit, idempotent; the only store-upgrade path).
   architect  Not implemented by this CLI: architecture classification and ADR
              authorship require agentic judgment, not deterministic code. See
              the loop-architect skill.
@@ -69,6 +72,10 @@ options:
   --mode {{basic,strict,release}}
                 (doctor/validate/verify/plan-lint/status/replay/simulate/run) basic forces structural
                 checks; strict/release require jsonschema. Default: auto-detect.
+  --expect-chain-head SHA256
+                (doctor/validate/verify) fail unless the event store's chain head
+                is exactly this 64-character lowercase hex hash. A missing,
+                unreadable, unchained, or diverged store fails the gate.
   --baseline    (metrics only) write docs/metrics-baseline.json over a gate-backed
                 run; exits non-zero and writes nothing otherwise.
   -h, --help    Show this help and exit.
@@ -238,6 +245,26 @@ def main(argv: list[str] | None = None) -> int:
             print(_USAGE, file=sys.stderr)
             return 2
 
+    expect_chain_head = None
+    if command in {"doctor", "validate", "verify"}:
+        try:
+            expect_chain_head, argv = _extract_value_flag(argv, "--expect-chain-head")
+        except ValueError as exc:
+            print(f"{command}: {exc}", file=sys.stderr)
+            print(_USAGE, file=sys.stderr)
+            return 2
+        if expect_chain_head is not None and re.fullmatch(r"[0-9a-f]{64}", expect_chain_head) is None:
+            print(f"{command}: --expect-chain-head must be a 64-character lowercase hex sha256",
+                  file=sys.stderr)
+            return 2
+    elif any(a == "--expect-chain-head" or a.startswith("--expect-chain-head=") for a in argv):
+        # No generic unknown-flag guard exists for the other commands, and scaffold
+        # would otherwise CREATE a directory named after the flag.
+        print(f"{command}: --expect-chain-head is only valid for doctor/validate/verify",
+              file=sys.stderr)
+        print(_USAGE, file=sys.stderr)
+        return 2
+
     decision = resume_target = reason = note = None
     if command in {"approve", "pause", "resume", "cancel"}:
         try:
@@ -308,7 +335,7 @@ def main(argv: list[str] | None = None) -> int:
 
     if command in {"doctor", "validate", "verify"}:
         try:
-            return _print_json(doctor_report(target, mode=mode))
+            return _print_json(doctor_report(target, mode=mode, expect_chain_head=expect_chain_head))
         except ValidationModeError as exc:
             print(f"{command}: {exc}", file=sys.stderr)
             return 2
@@ -320,6 +347,14 @@ def main(argv: list[str] | None = None) -> int:
             print(f"{command}: {exc}", file=sys.stderr)
             return 2
 
+    if command == "migrate":
+        from .migrate import migrate_store
+        try:
+            return _print_json(migrate_store(target))
+        except RuntimeStoreError as exc:
+            print(f"migrate: {exc}", file=sys.stderr)
+            return 2
+
     if command in {"status", "replay", "simulate"}:
         from .runner import RunnerError
         try:

loop_engineer-0.10.0/loop/chain.py

@@ -0,0 +1,88 @@
+"""Pure hash-chain canonicalization and verification for event@1 records.
+
+Stdlib-only and import-free of other loop modules: verify_chain() must work over
+any ordered event list (a SQLite read or a JSONL export) so third parties can
+re-verify a chain without this package's store code. Canonical form is
+json.dumps(sort_keys, separators=(",",":"), ensure_ascii=False, allow_nan=False)
+encoded UTF-8 — pinned normatively in reference/repo-os-contract.md #16.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any, Iterable, Mapping
+
+_PREIMAGE_FIELDS = (
+    "schema", "run_id", "sequence", "event_id", "type", "actor", "ts",
+    "causation_id", "correlation_id", "payload", "artifact_hashes",
+    "prev_event_hash",
+)
+
+
+class ChainHashError(ValueError):
+    """A value cannot be canonically hashed (non-JSON type, non-finite float, lone surrogate)."""
+
+
+def canonical_json(value: Any) -> str:
+    try:
+        text = json.dumps(value, sort_keys=True, separators=(",", ":"),
+                          ensure_ascii=False, allow_nan=False)
+    except (TypeError, ValueError) as exc:
+        raise ChainHashError(f"value is not canonically serializable: {exc}") from exc
+    try:
+        text.encode("utf-8")
+    except UnicodeEncodeError as exc:
+        raise ChainHashError(f"value contains a lone surrogate: {exc}") from exc
+    return text
+
+
+def compute_event_hash(record: Mapping[str, Any]) -> str:
+    preimage = {field: record.get(field) for field in _PREIMAGE_FIELDS}
+    return hashlib.sha256(canonical_json(preimage).encode("utf-8")).hexdigest()
+
+
+def link_issue(record: Mapping[str, Any], prev_head: Mapping[str, Any] | None) -> str | None:
+    """One incremental chain check; None means record legally extends prev_head."""
+    sequence = record.get("sequence")
+    stored = record.get("event_hash")
+    if stored is None:
+        if prev_head is None:
+            return None
+        return (f"unchained event after chained prefix at sequence {sequence!r} "
+                "(a pre-0.10.0 writer appended to a chained store, or the row was tampered)")
+    expected_prev = prev_head["event_hash"] if prev_head is not None else None
+    if record.get("prev_event_hash") != expected_prev:
+        return f"prev_event_hash mismatch at sequence {sequence!r}"
+    try:
+        recomputed = compute_event_hash(record)
+    except ChainHashError as exc:
+        return f"unhashable record at sequence {sequence!r}: {exc}"
+    if recomputed != stored:
+        return f"event_hash mismatch at sequence {sequence!r}"
+    return None
+
+
+def verify_chain(events: Iterable[Mapping[str, Any]], *, expected_head: str | None = None) -> dict[str, Any]:
+    """Verify a COMPLETE run stream's hash chain (sequence 0 onward); pure, I/O-free."""
+    issues: list[str] = []
+    unchained_prefix = 0
+    chained_events = 0
+    head: dict[str, Any] | None = None
+    for record in events:
+        issue = link_issue(record, head)
+        if issue is not None:
+            issues.append(issue)
+            break
+        if record.get("event_hash") is None:
+            unchained_prefix += 1
+            continue
+        chained_events += 1
+        head = {"sequence": record.get("sequence"), "event_hash": record["event_hash"]}
+    if expected_head is not None and not issues:
+        if head is None:
+            issues.append("expected chain head, but the stream has no chained events")
+        elif head["event_hash"] != expected_head:
+            issues.append(f"chain head {head['event_hash']} does not match expected {expected_head}")
+    return {"ok": not issues, "issues": issues, "chained_events": chained_events,
+            "unchained_prefix": unchained_prefix, "head": head}

{loop_engineer-0.9.0 → loop_engineer-0.10.0}/loop/contract.py

@@ -749,11 +749,13 @@ def validate_contract(target: str | Path, *, mode: str | None = None) -> dict[st
     }
 
 
-def doctor_report(target: str | Path, *, mode: str | None = None) -> dict[str, Any]:
+def doctor_report(target: str | Path, *, mode: str | None = None,
+                  expect_chain_head: str | None = None) -> dict[str, Any]:
     report = validate_contract(target, mode=mode)
     from .runtime import event_consistency_issues
 
-    event_store, event_issues = event_consistency_issues(target, mode=mode)
+    event_store, event_issues = event_consistency_issues(
+        target, mode=mode, expect_chain_head=expect_chain_head)
     issues = report["issues"] + list(event_issues) if event_issues else report["issues"]
     return {**report, "event_store": event_store, "issues": issues,
             "ok": report["ok"] and not event_issues}

{loop_engineer-0.9.0 → loop_engineer-0.10.0}/loop/events.py

@@ -10,6 +10,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Mapping, Protocol, Sequence, runtime_checkable
 
+from . import chain
 from .contract import ContractIssue, _resolve_requested_mode, _schemas_dir
 from .emit import _ITERATION_OUTCOMES, _RECEIPT_OUTCOMES, _RECEIPT_ROLES
 
@@ -41,6 +42,8 @@ CREATE TABLE IF NOT EXISTS events (
     ts TEXT NOT NULL,
     payload TEXT NOT NULL,
     artifact_hashes TEXT NOT NULL,
+    prev_event_hash TEXT,
+    event_hash TEXT NOT NULL,
     PRIMARY KEY (run_id, sequence)
 )
 """
@@ -66,6 +69,14 @@ class SequenceConflictError(ValueError):
     """expected_sequence differed from the atomically assigned next sequence."""
 
 
+class EventRowDecodeError(ValueError):
+    """A stored payload/artifact_hashes column is not valid JSON."""
+
+
+class EventStoreOperationalError(RuntimeError):
+    """The events table exists but cannot service this operation (schema drift, lock)."""
+
+
 @runtime_checkable
 class EventStore(Protocol):
     def append(self, run_id: str, event_type: str, payload: Mapping[str, Any], *, actor: str,
@@ -191,6 +202,11 @@ def _structural_validate_event(data: dict[str, Any]) -> list[str]:
     for field in ("causation_id", "correlation_id"):
         if field in data and data[field] is not None and not isinstance(data[field], str):
             issues.append(f"{field} must be a string or null")
+    for field in ("prev_event_hash", "event_hash"):
+        if field in data and data[field] is not None and (
+                not isinstance(data[field], str)
+                or re.search(r"^[0-9a-f]{64}$", data[field]) is None):
+            issues.append(f"{field} must be null or a 64-character lowercase hex sha256")
     hashes = data.get("artifact_hashes", [])
     if not isinstance(hashes, list):
         issues.append("artifact_hashes must be an array")
@@ -234,6 +250,45 @@ def validate_event(data: dict[str, Any], *, mode: str | None = None) -> dict[str
     return _validate_event_dict(data, mode=mode)
 
 
+def has_chain_columns(conn: sqlite3.Connection) -> bool:
+    return any(row[1] == "event_hash" for row in conn.execute("PRAGMA table_info(events)"))
+
+
+def store_user_version(conn: sqlite3.Connection) -> int:
+    return int(conn.execute("PRAGMA user_version").fetchone()[0])
+
+
+_BASE_COLUMNS = ("run_id", "sequence", "event_id", "type", "actor", "causation_id",
+                 "correlation_id", "ts", "payload", "artifact_hashes")
+
+
+def read_event_rows(conn: sqlite3.Connection, run_id: str, *,
+                    since_sequence: int | None = None) -> list[dict[str, Any]]:
+    """The single event-row projection shared by store, runtime, and runner reads.
+
+    Records always carry prev_event_hash/event_hash keys; legacy stores project
+    None. Owns the JSON-decode translation every call site used to repeat.
+    """
+    chained = has_chain_columns(conn)
+    columns = _BASE_COLUMNS + (("prev_event_hash", "event_hash") if chained else ())
+    operator, cursor = (">=", 0) if since_sequence is None else (">", since_sequence)
+    rows = conn.execute(
+        f"SELECT {', '.join(columns)} FROM events WHERE run_id = ? AND sequence {operator} ? "
+        "ORDER BY sequence ASC", (run_id, cursor)).fetchall()
+    records: list[dict[str, Any]] = []
+    try:
+        for row in rows:
+            records.append({
+                "schema": EVENT_SCHEMA_ID, "run_id": row[0], "sequence": row[1], "event_id": row[2],
+                "type": row[3], "actor": row[4], "causation_id": row[5], "correlation_id": row[6],
+                "ts": row[7], "payload": json.loads(row[8]), "artifact_hashes": json.loads(row[9]),
+                "prev_event_hash": row[10] if chained else None,
+                "event_hash": row[11] if chained else None})
+    except (TypeError, json.JSONDecodeError) as exc:
+        raise EventRowDecodeError(f"event row is not decodable: {exc}") from exc
+    return records
+
+
 class SQLiteEventStore:
     """A transactional SQLite/WAL event store with DB-enforced append-only rows."""
 
@@ -245,9 +300,13 @@ class SQLiteEventStore:
         conn.execute("PRAGMA journal_mode=WAL")
         conn.execute("PRAGMA synchronous=FULL")
         conn.execute("PRAGMA busy_timeout=5000")
+        fresh = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name='events'").fetchone() is None
         conn.execute(_CREATE_EVENTS_TABLE)
         conn.execute(_CREATE_NO_UPDATE_TRIGGER)
         conn.execute(_CREATE_NO_DELETE_TRIGGER)
+        if fresh:
+            conn.execute("PRAGMA user_version = 2")
         return conn
 
     def append(self, run_id: str, event_type: str, payload: Mapping[str, Any], *, actor: str,
@@ -275,15 +334,39 @@ class SQLiteEventStore:
                 conn.execute("ROLLBACK")
                 raise SequenceConflictError(f"expected next sequence {next_sequence} for run_id {run_id!r}, caller supplied {expected_sequence}")
             record["sequence"] = next_sequence
+            chained = has_chain_columns(conn)
+            if chained:
+                prev_row = conn.execute(
+                    "SELECT event_hash FROM events WHERE run_id = ? AND sequence = ?",
+                    (run_id, next_sequence - 1)).fetchone() if next_sequence else None
+                record["prev_event_hash"] = prev_row[0] if prev_row else None
+                try:
+                    record["event_hash"] = chain.compute_event_hash(record)
+                except chain.ChainHashError as exc:
+                    conn.execute("ROLLBACK")
+                    raise EventValidationError(str(exc)) from exc
+            else:
+                record["prev_event_hash"] = None
+                record["event_hash"] = None
             payload_json = json.dumps(record["payload"], sort_keys=True)
             hashes_json = json.dumps([dict(item) for item in record["artifact_hashes"]], sort_keys=True)
             try:
-                conn.execute("INSERT INTO events (run_id, sequence, event_id, type, actor, causation_id, correlation_id, ts, payload, artifact_hashes) VALUES (?,?,?,?,?,?,?,?,?,?)",
-                             (record["run_id"], record["sequence"], record["event_id"], record["type"], record["actor"], record["causation_id"], record["correlation_id"], record["ts"], payload_json, hashes_json))
+                if chained:
+                    conn.execute("INSERT INTO events (run_id, sequence, event_id, type, actor, causation_id, correlation_id, ts, payload, artifact_hashes, prev_event_hash, event_hash) VALUES (?,?,?,?,?,?,?,?,?,?,?,?)",
+                                 (record["run_id"], record["sequence"], record["event_id"], record["type"], record["actor"], record["causation_id"], record["correlation_id"], record["ts"], payload_json, hashes_json, record["prev_event_hash"], record["event_hash"]))
+                else:
+                    conn.execute("INSERT INTO events (run_id, sequence, event_id, type, actor, causation_id, correlation_id, ts, payload, artifact_hashes) VALUES (?,?,?,?,?,?,?,?,?,?)",
+                                 (record["run_id"], record["sequence"], record["event_id"], record["type"], record["actor"], record["causation_id"], record["correlation_id"], record["ts"], payload_json, hashes_json))
             except sqlite3.IntegrityError as exc:
                 conn.execute("ROLLBACK")
                 raise DuplicateEventError(record["event_id"]) from exc
             conn.execute("COMMIT")
+        except sqlite3.OperationalError as exc:
+            try:
+                conn.execute("ROLLBACK")
+            except sqlite3.Error:
+                pass
+            raise EventStoreOperationalError(f"event store cannot accept appends: {exc}") from exc
         finally:
             conn.close()
         return record
@@ -292,11 +375,9 @@ class SQLiteEventStore:
         """Read the full stream for None, or events strictly after an integer cursor."""
         conn = self._connect()
         try:
-            operator, cursor = (">=", 0) if since_sequence is None else (">", since_sequence)
-            rows = conn.execute(f"SELECT run_id, sequence, event_id, type, actor, causation_id, correlation_id, ts, payload, artifact_hashes FROM events WHERE run_id = ? AND sequence {operator} ? ORDER BY sequence ASC", (run_id, cursor)).fetchall()
+            return read_event_rows(conn, run_id, since_sequence=since_sequence)
         finally:
             conn.close()
-        return [{"schema": EVENT_SCHEMA_ID, "run_id": row[0], "sequence": row[1], "event_id": row[2], "type": row[3], "actor": row[4], "causation_id": row[5], "correlation_id": row[6], "ts": row[7], "payload": json.loads(row[8]), "artifact_hashes": json.loads(row[9])} for row in rows]
 
     def latest_sequence(self, run_id: str) -> int | None:
         conn = self._connect()