Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
2 changes: 1 addition & 1 deletion docs/architecture/persisted-contracts.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ A golden over the current writer does not protect these. A reader can stop accep
| Board | the board database (`board.db`, with the WAL a killed run leaves): items in every state a release's `board add` / `run` / `update` / `import-review-candidates` leave them (gate evidence passing and failing, the agent's `done` and `review` blocks with handoff and outputs, an agent failure, a killed and a reclaimed claim, a SIGINT and an orchestration crash, manual evidence and sign-off, dependencies including a missing one, imported review candidates), their transitions, decisions including a superseded one, the run ledger, and from v0.2.0 the compaction rollups and counters (partly compacted: a count needs both the live audit and the rollups). No release wrote the lesson columns (`project_id`, `provenance_json`, `source_key`); `test_lessons.py::test_an_old_board_gains_the_lesson_columns` and `::test_a_damaged_provenance_reads_as_not_recorded` cover those readers, and the mixed-project tests there the project filter. Every release writes a claim's ledger row in the claim's transaction, so the ledger backfill's positive branch stays covered by the synthetic tests in `test_board.py`; no release writer produces damaged JSON or a malformed evidence entry either | HEAD's first open (columns and tables added, every released cell kept, a second open a no-op), `Board.get` / `list` / `transitions` (`_row_to_item`, `_load_list`, `_load_evidence`) compared field by field with what the release's own interpreter read from the same database and with the raw cells, `board list` / `show`, `active_decisions` and `_row_to_decision` on every row (retired ones included), `board decisions`, `project_lessons` (empty: no released decision is a lesson), `stats` at fixed clocks including both sides of the aging cutoff, and `board stats` at a fresh and an aged clock; the human path on released rows: `update --state done` counting stored evidence or refused without it, `--sign-off`, `--clear-human-required`, an annotate keeping a released lease, `decide --supersedes` in and out of scope, a re-import skipped, and refused when the stored provenance differs. HEAD operating a released board: `board run` dispatch (FIFO order, skipping human-required items and unmet or missing dependencies, `--goal`, `--id`) with the released handoff, inputs and active decisions in the prompt and the run's outcome added to the released row, an agent's `done` counted only with this run's gate; a released running lease reclaimed exactly at its timeout (the ledger's `reclaimed_at` stamped, on v0.1.2 in the column HEAD added), redispatch counted, `apply_update`, the crash block and `renew_claim` fenced by the released lease; the scratch GC over the released ledger (purged runs never collected, a live lease never, a reclaimed run after one lease timeout of grace, a failed purge scheduled and then cleared in the columns HEAD added); `board compact` of released history (stats unchanged, rollups and counters added to, a cutoff between two claims); the gateway `board_list` / `board_get` / `board_stats`, `dashboard.take_snapshot` and the TUI board tab; a lesson promoted onto a released board leaves the released decisions unbound, and cannot supersede one (scope refused before project). Not covered: a run v0.1.2 reclaimed but never purged (its `reclaimed_at` is NULL, so HEAD collects it with no grace; v0.1.2 had none either, and its own GC purged every such run in the fixtures); `room promote` onto a released board (needs a room; `test_lessons.py` covers the CLI); the memory a released board run wrote (outside `board.db`) | `test_frozen_board.py`, `test_frozen_board_ops.py` (v0.1.2, v0.2.0, v0.3.0) |
| Memory backends | Mem0 and LangGraph stored payloads | the backends' read paths | not yet |
| TUI jobs | job documents, `schema_version` 1 and 2 | `JobStore.list_jobs` | not yet |
| Run envelope | report run directories as a release's `run` and `board run` leave them with recording on: `envelope.json` (completed, no change, route failure, gate passed and failed, a compete team, a file trace, a Phoenix export error, a trace error, breaker and multiple degradations, a board block, the skeleton a SIGKILL leaves, a SIGINT's finalized crash), `result.json`, `trace.otlp.json`, and a trace-only run with no envelope; v0.1.2 wrote no `.syncmill-run-dir` sentinel. Preflight blocks only as `disabled` (the released preflight records are not frozen yet) | HEAD's `contracts/run-envelope.schema.json` (and the release's own, frozen beside it), `load_envelope` returning the stored document, `report show` and `report list` compared with what the release's own CLI printed, including the refusal for a run without an envelope, the TUI Reports tab and the dashboard REPORT pane; retention ownership (`_is_run_dir`) through `RunReporter.start` and the Supervisor's trace-only sweep: a sentinel or, for v0.1.2, an envelope with syncmill's `kind` naming its own directory makes a run dir removable, and a v0.1.2 trace-only run dir (neither) is never removed; a custom `trace.dir` is never swept. Not covered: `trace.otlp.json` semantics (tracegraph's reader); `report list` also lists a foreign directory holding any nonempty JSON-object `envelope.json` (observed, unchanged) | `test_frozen_envelope.py` (v0.1.2, v0.2.0, v0.3.0) |
| Run envelope | report run directories as a release's `run` and `board run` leave them with recording on: `envelope.json` (completed, no change, route failure, gate passed and failed, a compete team, a file trace, a Phoenix export error, a trace error, breaker and multiple degradations, a board block, the skeleton a SIGKILL leaves, a SIGINT's finalized crash), `result.json`, `trace.otlp.json`, and a trace-only run with no envelope; v0.1.2 wrote no `.syncmill-run-dir` sentinel. Under `<release>/preflight/`, its own reports root: run dirs with a real preflight block from the release's `run` against a fake `toolgraph` answering with the release's vendored goldens (advisory ok, drift, unresolved, unmapped, error, timeout; strict allow, warn, block, timeout, unresolved, unavailable under both policies, two identities, a generation mismatch, an unmapped participant; from v0.2.0 control-plan allow, findings, error, timeout, both modes), the persistence failures reached by making the release's own writer fail one write (v0.1.2 and v0.2.0+ leave different files), and a SIGKILL after a strict preflight; `preflight.json`, `preflight/eval-NNN.json`, `control-plan.json`, `control-preflight.json`. A few producer replies are synthetic and named in its `index.json` | HEAD's `contracts/run-envelope.schema.json` (and the release's own, frozen beside it), `load_envelope` returning the stored document, `report show` and `report list` compared with what the release's own CLI printed, including the refusal for a run without an envelope, the TUI Reports tab and the dashboard REPORT pane; retention ownership (`_is_run_dir`) through `RunReporter.start` and the Supervisor's trace-only sweep: a sentinel or, for v0.1.2, an envelope with syncmill's `kind` naming its own directory makes a run dir removable, and a v0.1.2 trace-only run dir (neither) is never removed; a custom `trace.dir` is never swept; for the preflight runs, the same schema, loader, `report show` / `report list` and UI checks, and retention removing a released dir whole with its nested `preflight/` directory. Not covered: `trace.otlp.json` semantics (tracegraph's reader); `report list` also lists a foreign directory holding any nonempty JSON-object `envelope.json` (observed, unchanged); no HEAD code reads the preflight files back, so their checks are fixture integrity; `report show` prints `Preflight: ok` for a strict run that enforcement blocked (observed, unchanged) | `test_frozen_envelope.py`, `test_frozen_preflight_envelope.py` (v0.1.2, v0.2.0, v0.3.0) |

### How a family is frozen

Expand Down
Loading
Loading