From 3c3a3ee49f4aab58319e4c36df60d9ddc0064879 Mon Sep 17 00:00:00 2001 From: sykosyber Date: Mon, 2 Nov 2026 01:02:25 -0800 Subject: [PATCH 1/8] Factory goal gate: owner-approved promotion over ledger-resolved verdicts, digest-checked artifacts, an isolated and sealed candidate run, recomputed policy on verify, reviewer independence by provider family, scrubbed journals (the #154 verification's S1-S9) The factory may propose a spec; it may promote none. `spec promote`, `canonize` and `retire` now take a human actor (`kind:id`, resolved to a principal) and an approval that verifies: `factory approve` signs, with the owner's seed through the certificate module's Ed25519 and DSSE, a payload naming the spec (id, version, digest as on disk), the operation and the verdict ids; `spec promote` verifies it under `--owner-public`, requires the approver to be the actor, resolves every `--verdict` on the ledger to a `review` that accepted the very variant on disk (the `validate` event's digest must match), refuses an approver who proposed or reviewed it, stores the approval under `approvals/` and cites its `approval_recorded` hash from the `spec_changed`. `transition` accepts only the `Approved` record `verify_approval` returns. The variant loop no longer hints `--actor model:`. Ledger: every artifact load checks the file against the digest the ledger recorded (`load_run`, `load_space`; `set_baseline` goes through `load_run`), `verify` covers Space graphs, journals, their blobs, attestations and approvals, `problems()` says which, and `factory check` verifies the ledger before the candidate runs and again after it exits. Appends go through the kernel journal's writer (`syberlabs.journal.Journal`: cross-process lock, fsync, torn-tail repair); the SQLite projection rebuilds when the log it was built from moved (a `meta` row) and keeps the `features` table. Harness: the candidate runs under `python -I` in a host-owned scratch directory outside the worktree and the ledger and is never told the ledger's path; the parent moves the journal in afterwards. Every record carries a seal (HMAC chained from the previous record under a per-run key the parent generated); `verify_journal` refuses a planted line, an edited line, a torn tail or an empty file, and such a journal is not delivered. The report comes back over a private pipe bound by the run's nonce (the hidden checks' pattern); a line on stdout is output, and the status in the report must agree with the `end` record the parent reads itself. Timeouts stop the process tree (`checks._stop`, now a declared `factory -> git` edge). Subprocess argv and cwd, socket addresses and the tests tail are scrubbed of credential shapes (`_patterns.SECRET`, bearer tokens, PEM keys, credential `KEY=value`, the value after a credential flag) before they are journaled or attested. Attestation: `verify` recomputes the policy from the evidence and the gate and refuses a statement whose written policy says more; `record_attestation` logs `signed: true` only when the signature verifies under the key it is given, else `envelope: true, signed: false`. `independence(proposer, reviewer)` (`factory/independence.py`) judges by the provider family the command declared (`model` or `signal.harness.model`) and refuses an unknown family; `judge` uses it; `critic` is unchanged. The viewer builds its DOM with textContent and carries effects by digest, not payloads. `bootstrap` carries the contract's own tests timeout, `full_suite` means the suite ran to completion, and a hanging suite is stopped with its tree. Tests: 45 in tests/test_factory.py (35 before). New: the gate (model actor, human without approval, dict for an approval, wrong operation, wrong verdicts, wrong key, approver not the actor, approver who proposed), verdict resolution, principals, independence by family, edited golden (verify, load_run, set_baseline, projection, the check refuses before the candidate runs), projection staleness, three forging candidates refused and an honest one passing, the seal itself, scrubbing, a candidate forging its report through the Kit, a hanging suite stopped at the contract's timeout, the self-graded statement refused by verify, the end-to-end promote through approve. Fixture proposers declare their model; `fxapp/variants.py` holds the forgers. docs/FACTORY.md says 45 tests (it said 18), documents the gate and the trust boundary; spec/GAPS.md 65 records what remains (the approval is a signature, not yet a kernel `approved` event; the recorder shares the candidate's memory; the behavior-change label is per contract; no cross-process lock before this). Co-Authored-By: Claude Fable 5.1 --- docs/FACTORY.md | 78 +++- docs/architecture.declared.json | 1 + spec/GAPS.md | 1 + syberlabs/factory/attest.py | 10 + syberlabs/factory/cli.py | 192 ++++++-- syberlabs/factory/harness.py | 467 +++++++++++++++---- syberlabs/factory/independence.py | 63 +++ syberlabs/factory/ledger.py | 249 +++++++--- syberlabs/factory/spec.py | 170 ++++++- syberlabs/static/factory.html | 28 +- tests/fixtures/factory_app/fxapp/variants.py | 41 +- tests/fixtures/factory_app/proposers.py | 13 +- tests/test_factory.py | 449 +++++++++++++++++- 13 files changed, 1499 insertions(+), 263 deletions(-) create mode 100644 syberlabs/factory/independence.py diff --git a/docs/FACTORY.md b/docs/FACTORY.md index e6c20cc..0982f5a 100644 --- a/docs/FACTORY.md +++ b/docs/FACTORY.md @@ -12,7 +12,7 @@ architecture conformance, spec-driven development, attestation, ledger storage) are in the architecture plan this slice was built from. This page is what the repository does today. Package: `syberlabs/factory/`. Standard library only. `syberlabs` still does not import `syberwork`. -Claim ceiling for this page: **implemented** and **tested** (`tests/test_factory.py`, 18 tests, and the +Claim ceiling for this page: **implemented** and **tested** (`tests/test_factory.py`, 45 tests, and the CLI run below). Nothing here is measured, deployed or externally validated. ## The v0 slice @@ -43,8 +43,10 @@ python -m syberlabs.factory show RUN_A # the python -m syberlabs.factory at RUN_A --seq 10 # main.run and effects.submit are open python -m syberlabs.factory replay RUN_A --entry fxapp.main:run --fixture fixture.json # effects come from the journal python -m syberlabs.factory spec validate spec.json -python -m syberlabs.factory spec promote spec.json --verdict review-1 --actor model:reviewer -python -m syberlabs.factory ticket spec.json --req R1 --baseline RUN_A --owner mateo --out ticket.json +python -m syberlabs.factory variants spec.json --proposer claude=CMD --reviewer gpt=CMD # writes spec.v2.json, prints the verdict id +python -m syberlabs.factory approve spec.v2.json --verdict VERDICT --actor human:mateo --seed-env SYBERLABS_FACTORY_OWNER_SEED --out approval.json +python -m syberlabs.factory spec promote spec.v2.json --verdict VERDICT --actor human:mateo --approval approval.json --owner-public owner.pub +python -m syberlabs.factory ticket spec.v2.json --req R1 --baseline RUN_A --owner mateo --out ticket.json python -m syberlabs.factory record --entry fxapp.main:run --fixture fixture.json --revision candidate1 python -m syberlabs.factory attest --baseline RUN_A --candidate RUN_B --ticket ticket.json --commit candidate1 \ --seed-env SYBERLABS_FACTORY_SEED --out attestation.json # exit 0: diff empty, promote True @@ -57,9 +59,40 @@ An entrypoint is `module:function`, imported from the root and called as `functi hook installed after the import so the import is not part of the run, or a script run as `__main__` whose own body is its first span and which takes its context from `syberlabs.factory.harness.current()`. Effects go through `ctx.run(name, fn, ...)`; that is the only instrumentation a program needs, and the only part -replay cannot do without. The child inherits the caller's environment, as provider commands do; it is not a -sandbox. The signing seed is read from the named environment variable the way `syberlabs certify` reads -it; only the name is recorded. +replay cannot do without. The child inherits the caller's environment, as provider commands do (`-I` drops +the `PYTHON*` variables); it is not a sandbox. The signing seed is read from the named environment variable +the way `syberlabs certify` reads it; only the name is recorded. + +## The goal gate + +The factory may propose a spec at any level; it may promote none. `spec promote`, `canonize` and `retire` +take a human `--actor` (`kind:id`, resolved to a principal; free text is refused) and an approval that +verifies: `factory approve` signs, with the owner's seed, a payload naming the spec (id, version and its +digest as it is on disk), the operation and the verdict ids; `spec promote` verifies it under +`--owner-public`, requires the approver to be the actor, and resolves each `--verdict` on the ledger to a +`review` event that accepted the very variant the file is (the `validate` event's digest must match, so a +spec edited after review is refused), whose proposers and reviewer the approver is not. The approval is +stored under `approvals/` and logged as `approval_recorded`; the `spec_changed` cites that event's hash. A +model actor, a missing approval, a verdict that is a string rather than a review, or an approval under +another key each refuse, and the variant loop no longer suggests that the reviewer promote what it reviewed. +The intended source of the approval is a kernel `approved` event on a goal case (approver not proposer, +`session.py`); until the factory has a case to hang it on, the owner's signature stands in (`spec/GAPS.md`). + +## The candidate is not trusted + +The candidate's program runs in a child the parent does not believe. The child runs `python -I` in a +host-owned scratch directory outside the worktree and outside the ledger, and is never told where the +ledger is; the parent moves the journal into `runs/` afterwards. Every journal record carries a seal, an +HMAC chained from the previous record under a per-run key the parent generated, and the parent refuses a +journal with a line written around the recorder, a line edited afterwards, a torn tail, or no `end`. The +child's report travels over a private pipe and must carry the run's nonce; a line printed to stdout is +output, never a report, and the status it claims must agree with the `end` record the parent reads itself. +`factory check` verifies the ledger, chain and artifacts, before the candidate runs and again after it +exits, and refuses if anything moved in between. Every artifact load checks the file against the digest the +ledger recorded, so an edited golden journal cannot become a baseline (`load_run` refuses it, `verify` +names it). The residual is memory: code in the child can reach the recorder and its key through +`sys.modules`, because io observation has to run in the candidate's process. That is recorded in +`spec/GAPS.md`, and this is still not a sandbox. The repository checks itself the same way. `docs/architecture.declared.json` declares four components (`syberlabs`, `syberlabs.eval`, `syberlabs.factory`, `syberwork`) and the edges allowed between them; @@ -197,12 +230,16 @@ removed, footprint hint, rationale). Each delta becomes a variant through `mutat the latest Space graph (findings stay on the variant rather than hiding it), and is logged as `spec_changed` with the proposer as actor; a proposer that returns no JSON is logged as a failed mutate and the loop continues. The reviewer is one command that sees every variant with its findings and answers -a verdict per variant. `judge` enforces three rules: the reviewer did not propose any variant (the critic -rule's independence), a variant with findings cannot be accepted, and at most one variant is accepted. The -accepted variant is validated to candidate and written as the spec's next version; `spec promote` with the -verdict id then opens its tickets. `tests/fixtures/factory_app/proposers.py` stands in for the models, and -`tests/test_factory.py::Variants` runs the loop with one sound proposer, one that overreaches, and one that -breaks. Nothing here imports a model SDK; the adapter for a real model is the command. +a verdict per variant. `judge` enforces three rules: the reviewer is independent of every proposer by +provider family (`factory/independence.py`: the family is read from the model the command declared in its +answer, `model` or `signal.harness.model`; two names on one family are not independent, and a party whose +family is not recorded refuses rather than passes), a variant with findings cannot be accepted, and at most +one variant is accepted. The accepted variant is validated to candidate and written as the spec's next +version; the owner then approves and promotes it (the goal gate above) and the promotion opens its tickets. +`tests/fixtures/factory_app/proposers.py` stands in for the models, and `tests/test_factory.py::Variants` +runs the loop with one sound proposer, one that overreaches, and one that breaks. Nothing here imports a +model SDK; the adapter for a real model is the command. `independence()` is small and importable so that +`critic.independent` can adopt it; `critic` is unchanged here. ## Where this departs from the plan, and why @@ -230,7 +267,8 @@ breaks. Nothing here imports a model SDK; the adapter for a real model is the co be converted to it later. - **Spec variants are commands.** The plan had Claude, Grok and Cursor propose and GPT review. They do, as commands at a process boundary, which is how this repository treats every model; the `--proposer` and - `--reviewer` names are what the ledger records as actors. + `--reviewer` names are what the ledger records as actors, beside the model and provider family each + command declared. ## What a cell is, exactly @@ -246,9 +284,17 @@ component nothing called at a revision has no cells there, and that absence is i through `ctx.run` as an effect result, which is the right boundary anyway. - Python only. A function call is a span; a module's import runs as one `` span; statements outside any function in an already-imported module are not visible. -- Replay re-executes the program's own code. It is not a sandbox and nothing here is. -- One writer per ledger at a time. The ledger refuses to append to a log whose chain does not verify, but - it has no cross-process lock; the harness journal is written by the process that records. +- Replay re-executes the program's own code. It is not a sandbox and nothing here is; the trust boundary + above raises the cost of a forged run, and the residual (the recorder shares the candidate's memory) is + in `spec/GAPS.md`. +- Ledger appends go through the kernel journal's writer (lock, fsync, torn-tail repair), so two factory + commands on one home serialize; the harness journal is written by the recorder in the child and sealed + under the parent's per-run key. +- Subprocess argv and cwd, socket addresses and the test runner's output tail are scrubbed of credential + shapes (the kernel's shared pattern, bearer tokens, PEM keys, `KEY=value` with a credential key, the value + after a credential flag) before they are journaled or attested; a credential in some other shape is not. +- The behavior-change label is a flag on the check's argv, so it is per contract, not per ticket; a ticket + that intends a behavior change cannot yet say so on its own. - The trace diff compares component transitions (or function names), effect result digests and masked io keys. It does not compare arguments or return values of ordinary calls, or timing, so two runs that differ only in what a pure function returned diff empty. The spec's scenarios and the tests evidence kind diff --git a/docs/architecture.declared.json b/docs/architecture.declared.json index a267a86..485175b 100644 --- a/docs/architecture.declared.json +++ b/docs/architecture.declared.json @@ -45,6 +45,7 @@ {"from": "syberlabs-eval", "to": "syberlabs-primitives"}, {"from": "syberlabs-eval", "to": "syberlabs-signing"}, {"from": "syberlabs-factory", "to": "syberlabs-build-thread"}, + {"from": "syberlabs-factory", "to": "syberlabs-git"}, {"from": "syberlabs-factory", "to": "syberlabs-primitives"}, {"from": "syberlabs-factory", "to": "syberlabs-signing"}, {"from": "syberlabs-git", "to": "syberlabs-admission"}, diff --git a/spec/GAPS.md b/spec/GAPS.md index 28ce3d0..8f7e233 100644 --- a/spec/GAPS.md +++ b/spec/GAPS.md @@ -126,3 +126,4 @@ The schemas describe SyberWork as it behaves. They are not enforced at runtime e 63. **The GitHits pilot's example pacing and license reading rest on GitHits' documentation, not on observed traffic.** (1) The host paces `example` calls to one per 40 s per host (`syberlabs/githits_pace.py`, called by the launcher entry); GitHits' limit is per organization, so two hosts, or an operator's own `syberlabs githits example` (not paced), share the organization's budget without seeing each other's slots. (2) A loopback base URL is not paced unless `SYBERLABS_GITHITS_PACE_SECONDS` asks: a loopback proxy that forwards to GitHits would go unpaced. (3) Calls queued behind several others wait one interval each, so a Bash tool timeout shorter than the queue ends a call before it is sent, and the host then flags it `githits_unrecorded`. (4) The time file is plain text a process of the same user can rewrite; it paces cooperating processes and is no security boundary. (5) The license reading admits an example's `References`/`Sources` links by their `(SPDX)` and passes an example with neither code (a fenced, indented or HTML block) nor a source; inline code in prose is not read as code, and the three documented shapes (`complete`, `degraded`, `no_example` in the pinned OpenAPI document) are the only evidence of what real responses look like until the first live example is recorded. (6) The engineering smoke pins Claude Code 2.1.312 exactly because the host and the pilot VM run it; that version's flags were not re-checked here. 64. **The GitHits launcher fails closed before the network, and the treatment runs on a hooked API lane; neither is verified live, and other lookups on a `--bare` lane are still caught only after the fact.** The live canary of 2026-10-30 (Claude Code 2.1.312 on a Freestyle Linux VM) settled 56 (2): a `--settings` `PreToolUse` hook does not run under `--bare`, so `propose --claude-code --bare --githits` let the model run the launcher with no guard, and the client sent the lookup (`sent: true`) before the host stopped the run `provider_guard_inactive`. Now the launcher's entry sends nothing without claiming the hook's MAC-verified decision for its exact argv (`query_guard.claim_launch`; refused calls are recorded `status: unguarded`, `sent: false`), and `--githits` refuses `--bare` and runs on `--lane api-hooked` (the API key without `--bare`, a fresh `CLAUDE_CONFIG_DIR` and home per call, `--disable-slash-commands`; `docs/CLAUDE_CODE.md`). Not solved: (1) a decision is bound to the launcher's arguments (their SHA-256) and claimed once, not to a tool use id, which the launcher cannot see; a process holding the per-call key (a stdio MCP server, a shell under `--allow-code-tools-with-mcp`) can still sign a decision for its own arguments, as it could before; (2) the hook's words and the launcher's argv agree for plain words and quoted strings under a POSIX shell; a shell or platform that hands over different bytes (Git Bash's argument conversion to a Windows process, a non-UTF-8 byte) refuses a legitimate lookup (fail closed), which no live run has exercised; (3) WebSearch, WebFetch and `--mcp-config` (`mcp__githits__*`) lookups on a `--bare` lane have no pre-send gate: the hook does not run, so they still leave and are flagged `unguarded` afterwards; only `--githits` refuses `--bare`, and `api-hooked` or a login lane is where those tools are guarded; (4) `api-hooked` has run only against the stand-in `claude`: whether 2.1.312 with an empty config directory and home starts headless on `ANTHROPIC_API_KEY` (`apiKeySource`) and runs the hook is for its first live call, and the flags were read from 2.1.309's `--help` because 2.1.312's was not on the building machine; managed (policy) settings still load, `--setting-sources` has no value meaning `--settings` alone, `USERPROFILE` moves only on Windows, and the worktree's memory files (`CLAUDE.md`) are read in both arms, so the lane needs `--trusted-tree`; (5) the example license parser now reads any ATX or bold heading that names a source or reference ("## Source code" included) as a sources section and a fenced or indented block inside a blockquote as code, both of which can only drop more examples (fail closed); how often that drops a usable GitHits example is not measured; (6) the default deny-list (`SyberLabs`, `sykosyber`, `pypi:syberwork`, `deepwiki.com`, `deepwiki.org`) detects a fork of a SyberLabs repository only by its name (`githits.FORK_NAMES`) in a result's URL or a target, so a renamed fork, a vendored copy, or SyberLabs code mirrored under another name and site still passes, and no mirror or front-end other than DeepWiki is listed. +65. **The factory's goal gate is an owner signature, not yet a kernel approval; the candidate's process still shares memory with its recorder; the behavior-change label is per contract.** `factory-goal-gate` (2026-11-02, on the factory slice of #154) closes the slice's verification findings: `spec promote`, `canonize` and `retire` need a human actor and an approval that verifies (`factory approve` signs it with the owner's seed through the certificate module's Ed25519 and DSSE; `spec promote` verifies it under `--owner-public`, resolves every `--verdict` to a ledger `review` that accepted the very variant on disk, refuses an approver who proposed or reviewed it, stores the approval under `approvals/` and cites its `approval_recorded` hash from the `spec_changed`); every artifact load checks the file against the digest the ledger recorded and `verify` covers artifacts, so an edited golden journal refuses the check instead of becoming its baseline; the candidate runs under `python -I` in a host-owned scratch directory, is never told the ledger's path, writes a journal sealed per record under a per-run key the parent holds, reports over a nonce-bound private pipe, and the parent reads the `end` record itself and refuses a journal with no end, a planted line or a mismatching report; `verify` recomputes the policy from the evidence and `signed: true` needs a verifying signature; reviewer independence is the provider family the command declared, not the caller's name, and an unrecorded family refuses; subprocess argv, cwd, socket addresses and the tests tail are scrubbed of credential shapes; the viewer builds its DOM with `textContent` and carries no payloads; ledger appends use the kernel journal's lock, fsync and torn-tail repair, and the projection rebuilds when the log moved; the tests check honours the contract's timeout, `full_suite` means the suite ran to completion, and a timed-out suite or recording has its process tree stopped. What remains: (1) the approval is the owner's signature over the spec digest, not an `approved` event on a kernel goal case, because the factory has no case to hang one on; the ledger event is the citation the consolidation's §1.2 asks for, the journal hash is not; (2) io observation runs in the candidate's process, so code there can reach `_factory_harness._CURRENT[-1]` and its key through `sys.modules` and write records the seal accepts, or call the recorder's own `__exit__`; the seal and the channel raise the cost of a forgery, they are not a sandbox, and the recommendation on the open owner question stands: evidence with a person in the path, not the auto class; (3) a candidate that learns the ledger's absolute path from the contract in its worktree can still write to it between the check's two verifications only by forging a consistent unkeyed chain and matching digests, which `verify` does not distinguish from an honest ledger across runs; anchoring the chain head in `tlog`/`witness` is the fix; (4) the behavior-change label is `--behavior-change` on the check's argv, per contract, not a field of the ticket; (5) `independence` reads the model the command declared, so a command that lies about its model passes as it does for `model_usage`; (6) `verify_journal` reads text, so a journal whose line endings were rewritten verifies by content while the ledger's byte digest refuses it, which is the intended division; (7) before this packet the ledger had no cross-process lock (two commands on one home could fork the chain, detected by `append` but not prevented) and `docs/FACTORY.md` said 18 tests where the file defined 35; both are fixed here. The consolidation's other C1 items (`serves`, `mission_ref`, `done_when` on specs, mandatory `human_owner` on tickets, `promote` renamed `pass`, `tickets.py`, `codemap.py`) are not in this packet. diff --git a/syberlabs/factory/attest.py b/syberlabs/factory/attest.py index 199dc62..58bd9fd 100644 --- a/syberlabs/factory/attest.py +++ b/syberlabs/factory/attest.py @@ -171,6 +171,16 @@ def policy(predicate: dict, *, require_tests: bool = False, mutation_threshold: return {"promote": promote, "reasons": reasons} +GATE_PARAMETERS = ("require_tests", "mutation_threshold", "max_drift", "level") + + +def recompute(predicate: dict) -> dict: + """The policy's result computed again from the predicate's evidence and gate, so a verifier compares + what the signer wrote under ``policy`` with what the evidence says. Unknown gate keys are ignored.""" + gate = {k: v for k, v in (predicate.get("gate") or {}).items() if k in GATE_PARAMETERS} + return policy(predicate, **gate) + + def sign(document: dict, seed: bytes) -> dict: """A one-signature DSSE envelope over the canonical statement. ``keyid`` is the public key, hex.""" return sign_dsse(PAYLOAD_TYPE, canonical(document).encode("utf-8"), seed) diff --git a/syberlabs/factory/cli.py b/syberlabs/factory/cli.py index 4f200cb..231cd7b 100644 --- a/syberlabs/factory/cli.py +++ b/syberlabs/factory/cli.py @@ -7,7 +7,9 @@ syberlabs factory show RUN # the worldline, one line per step syberlabs factory at RUN --seq 12 # what was active at a logical time syberlabs factory export RUN --chrome trace.json | --view run.html - syberlabs factory spec validate|promote|canonize|retire spec.json + syberlabs factory spec validate spec.json + syberlabs factory approve spec.json --verdict V --actor human:mateo --seed-env NAME --out approval.json + syberlabs factory spec promote|canonize|retire spec.json --actor human:mateo --approval approval.json --owner-public KEY syberlabs factory ticket spec.json --req R1 --out ticket.json syberlabs factory attest --baseline A --candidate B --ticket ticket.json --commit SHA syberlabs factory verify attestation.json --public KEY @@ -117,11 +119,14 @@ def populate(factory) -> None: export.add_argument("--chrome", metavar="FILE") export.add_argument("--view", metavar="FILE", help="write an HTML page that scrubs the run over its Space graph") - sp = steps.add_parser("spec", help="move a spec file through its lifecycle; each step is logged") + sp = steps.add_parser("spec", help="move a spec file through its lifecycle; each step is logged. promote, canonize and " + "retire are owner acts: a human --actor plus --approval and --owner-public") sp.add_argument("operation", choices=sorted(specmod.TRANSITIONS)) sp.add_argument("spec", help="the spec JSON file; rewritten in place") - sp.add_argument("--actor", default="human:operator", help="kind:id (default human:operator)") - sp.add_argument("--verdict", action="append", default=[], help="a review verdict id promotion rests on") + sp.add_argument("--actor", default="human:operator", help="kind:id, kind in human|model|compiled (default human:operator)") + sp.add_argument("--verdict", action="append", default=[], help="a review verdict id promotion rests on; resolved on the ledger") + sp.add_argument("--approval", metavar="FILE", help="the owner's signed approval from `factory approve` (promote, canonize, retire)") + sp.add_argument("--owner-public", metavar="KEY", help="the owner's .pub file the approval must verify under") sp.add_argument("--reason") sp.add_argument("--superseded-by") sp.add_argument("--tickets", metavar="DIR", help="on promote: open one ticket per requirement into DIR, footprint " @@ -129,6 +134,15 @@ def populate(factory) -> None: sp.add_argument("--baseline", default="golden", help="the golden run or label the tickets diff against (default golden)") sp.add_argument("--owner", help="the accountable human on the tickets") + ap = steps.add_parser("approve", help="sign the owner's approval of a promote, canonize or retire of a spec as it is on disk; " + "the seed is read from an environment variable and never written") + ap.add_argument("spec") + ap.add_argument("--operation", choices=sorted(specmod.GATED), default="promote") + ap.add_argument("--verdict", action="append", default=[], help="the verdict ids the promotion rests on (must match `spec promote`)") + ap.add_argument("--actor", default="human:operator", help="the approving human, human:id (default human:operator)") + ap.add_argument("--seed-env", required=True, metavar="NAME", help="the owner's signing seed, as `syberlabs certify` reads it") + ap.add_argument("--out", required=True, help="where to write the approval envelope") + var = steps.add_parser("variants", help="several proposers each mutate a parent spec; one reviewer judges; the accepted " "variant is written as the spec's next version. Proposers and the reviewer are " "commands reading JSON on stdin and writing JSON on stdout (process boundary, no SDK)") @@ -169,7 +183,9 @@ def populate(factory) -> None: boot.add_argument("--max-drift", type=float, default=None) boot.add_argument("--level", choices=harness.LEVELS, default="component") boot.add_argument("--tests-argv", metavar="JSON", help="the suite the check runs in the worktree (tests evidence); " - "'contract' copies the existing contract's tests check") + "'contract' copies the existing contract's tests check and its timeout") + boot.add_argument("--tests-timeout", type=int, default=1800, help="seconds for a --tests-argv suite (default 1800; " + "'contract' takes the contract's own)") boot.add_argument("--thread-home", default=".syberlabs", help="the Build Thread home holding contracts/ (default .syberlabs)") boot.add_argument("--contract", default="repo-change", help="the contract id to extend (default repo-change)") boot.add_argument("--python", default=None, help="the interpreter the check argv names (default: this one)") @@ -340,6 +356,9 @@ def _run(args) -> int: if command == "spec": return _spec(args, home) + if command == "approve": + return _approve(args) + if command == "variants": return _variants(args, home) @@ -375,10 +394,17 @@ def _run(args) -> int: print("signature does not verify under that key, or the payload is not a statement") return 1 predicate = document["predicate"] + # The signer's own policy line is not the verdict: compute it again from the evidence and the gate the + # statement carries, and refuse a statement whose written policy says more than its evidence does. + recomputed = attest.recompute(predicate) + written = predicate.get("policy") or {} print(f"verified: {document['subject'][0]['name']} spec {predicate['spec']['spec_id']} v{predicate['spec']['version']}" - f" ticket {predicate.get('ticket')} promote {predicate['policy']['promote']}") - for reason in predicate["policy"]["reasons"]: + f" ticket {predicate.get('ticket')} promote {recomputed['promote']} (recomputed from the evidence)") + for reason in recomputed["reasons"]: print(f" {reason}") + if written.get("promote") != recomputed["promote"] or list(written.get("reasons") or []) != recomputed["reasons"]: + print(f"policy mismatch: the statement says promote {written.get('promote')}; the evidence says {recomputed['promote']}") + return 1 return 0 if command == "status": @@ -454,6 +480,14 @@ def _check(args, home: ledger.Ledger) -> int: baseline_id = args.baseline if is_run_id else home.baseline(args.baseline) if baseline_id is None: raise Rejected("baseline_missing", f"no baseline {args.baseline!r}: record the golden run, then `factory baseline RUN`") + # The ledger is verified, chain and artifacts, before the candidate runs, and the baseline is read then; the + # candidate's process never learns the ledger's path, but the ledger is checked again after it exits so + # that anything that did reach it in the meantime refuses the check rather than becoming its baseline. + before = home.events() + problems = home.problems(before) + if problems: + raise Rejected("ledger_corrupt", f"the ledger does not verify before the check: {problems[0]}") + baseline_records = home.load_run(baseline_id) fixture = _read_json(args.fixture, "fixture") if args.fixture else {} run_id = harness.new_run_id() recorded = harness.record(root, home.run_path(run_id), args.entry, @@ -462,13 +496,17 @@ def _check(args, home: ledger.Ledger) -> int: blobs=home.home / "blobs") if recorded.get("stdout"): print(recorded["stdout"]) + after = home.events() + if home.head(after) != home.head(before) or len(after) != len(before) or home.problems(after): + print("the ledger changed while the candidate ran: refuse", file=sys.stderr) + return 1 if recorded["status"] == "killed" or not home.run_path(run_id).exists(): print(f"no journal: {recorded.get('error')}", file=sys.stderr) return 1 run_event = home.record_run(run_id) ticket = _read_json(args.ticket, "ticket") if args.ticket else None footprint = ticket.get("footprint") if ticket else None - evidence = {"trace_diff": attest.trace_diff(home.load_run(baseline_id), home.load_run(run_id), footprint, args.level), + evidence = {"trace_diff": attest.trace_diff(baseline_records, home.load_run(run_id), footprint, args.level), "drift": attest.drift_evidence(report, commit)} if recorded.get("error"): evidence["run"] = {"kind": "run", "status": recorded["status"], "error": recorded["error"]} @@ -490,10 +528,11 @@ def _check(args, home: ledger.Ledger) -> int: footprint=footprint, evidence=evidence, builder=builder, ticket=ticket["ticket_id"] if ticket else None, behavior_change_label=args.behavior_change, gate=gate) - written = document + written, public = document, None if args.seed_env: - written = attest.sign(document, certificate.load_seed(args.seed_env)) - event = home.record_attestation(written) + seed = certificate.load_seed(args.seed_env) + written, public = attest.sign(document, seed), public_from_seed(seed) + event = home.record_attestation(written, public) policy = document["predicate"]["policy"] promote = policy["promote"] and recorded["status"] == "ok" diff = evidence["trace_diff"] @@ -552,10 +591,12 @@ def _bootstrap(args, home: ledger.Ledger) -> int: if args.level != "component": argv += ["--level", args.level] tests_argv = args.tests_argv + tests_timeout = 0 if tests_argv == "contract": - tests_argv = None # resolved from the contract below + tests_argv = None # resolved from the contract below, with its own timeout elif tests_argv: - argv += ["--tests-argv", tests_argv] + tests_timeout = args.tests_timeout + argv += ["--tests-argv", tests_argv, "--tests-timeout", str(tests_timeout)] if args.no_contract: print("check argv: " + json.dumps(argv)) return 0 @@ -571,9 +612,11 @@ def _bootstrap(args, home: ledger.Ledger) -> int: if args.tests_argv == "contract": if "tests" not in checks: raise Rejected("tests_missing", f"{versions[-1].name} has no tests check to copy") - argv += ["--tests-argv", json.dumps(checks["tests"]["argv"])] - checks.pop("tests") # the factory check runs it and records it as evidence; no second run - checks["factory"] = {"argv": argv, "timeout_seconds": 600 + (checks.get("tests", {}).get("timeout_seconds", 0) if args.tests_argv != "contract" else 1800)} + # The contract's own tests check moves into the factory check with its own timeout; no second run. + tests_timeout = int(checks["tests"].get("timeout_seconds") or args.tests_timeout) + argv += ["--tests-argv", json.dumps(checks["tests"]["argv"]), "--tests-timeout", str(tests_timeout)] + checks.pop("tests") + checks["factory"] = {"argv": argv, "timeout_seconds": 600 + tests_timeout} required = [name for name in evaluation.get("required", []) if name in checks] if "factory" not in required: required.append("factory") @@ -587,12 +630,20 @@ def _bootstrap(args, home: ledger.Ledger) -> int: return 0 +TESTS_TAIL_CHARS = 2000 + + def _run_tests(root: Path, argv_json: str, timeout: int) -> dict: """Run the suite the contract names, in the worktree, and reduce it to a tests evidence entry. The exit code - is the verdict (a runner's own counts are not parsed); the output digest lets a reviewer find the log.""" + is the verdict (a runner's own counts are not parsed); the output digest lets a reviewer find the log, and + the tail that enters the attestation is capped and scrubbed of credential shapes. ``full_suite`` is true + only when the suite ran to completion: a timed-out or unstartable run is not a full suite. On timeout the + whole process tree is stopped, as the Build Thread's own checks do.""" import hashlib import subprocess + import tempfile import time + from syberlabs.checks import _stop as stop_tree try: argv = json.loads(argv_json) if not isinstance(argv, list) or not all(isinstance(a, str) for a in argv) or not argv: @@ -600,17 +651,31 @@ def _run_tests(root: Path, argv_json: str, timeout: int) -> dict: except ValueError: raise Rejected("tests_argv", "--tests-argv is a JSON list of strings") from None started = time.monotonic() - try: - done = subprocess.run(argv, cwd=str(root), capture_output=True, timeout=timeout) - exit_code, output = done.returncode, (done.stdout + done.stderr) - except subprocess.TimeoutExpired as exc: - exit_code, output = None, (exc.stdout or b"") + (exc.stderr or b"") - except OSError as exc: - exit_code, output = None, str(exc).encode() - return {"kind": "tests", "argv": argv, "exit_code": exit_code, "full_suite": True, - "fail": 0 if exit_code == 0 else 1, "timed_out": exit_code is None, + exit_code, timed_out = None, False + with tempfile.TemporaryFile() as log: + try: + proc = subprocess.Popen(argv, cwd=str(root), stdin=subprocess.DEVNULL, stdout=log, stderr=subprocess.STDOUT, + start_new_session=hasattr(os, "setsid")) + except OSError as exc: + log.write(f"could not start {argv[0]!r}: {exc.strerror or exc}\n".encode()) + else: + deadline = started + timeout + while True: + try: + exit_code = proc.wait(timeout=0.05) + break + except subprocess.TimeoutExpired: + pass + if time.monotonic() > deadline: + stop_tree(proc) + timed_out = True + break + log.seek(0) + output = log.read() + return {"kind": "tests", "argv": harness.scrub_argv(argv), "exit_code": exit_code, "full_suite": exit_code is not None, + "fail": 0 if exit_code == 0 else 1, "timed_out": timed_out, "seconds": round(time.monotonic() - started, 1), "output_digest": hashlib.sha256(output).hexdigest(), - "output_tail": output[-2000:].decode(errors="replace")} + "output_tail": harness.scrub_text(output[-TESTS_TAIL_CHARS * 4:].decode(errors="replace"), TESTS_TAIL_CHARS)} def _map(args, home: ledger.Ledger) -> int: @@ -691,7 +756,7 @@ def _variants(args, home: ledger.Ledger) -> int: name, _, command = entry.partition("=") if not name or not command: raise Rejected("variants_proposers", f"a proposer is NAME=COMMAND, not {entry!r}") - proposer = {"kind": "model", "id": name} + proposer = specmod.party("model", name, None) try: delta = run_json(split_command(command), request, timeout=args.timeout) except Rejected as exc: @@ -699,6 +764,11 @@ def _variants(args, home: ledger.Ledger) -> int: home.append("spec_changed", {"spec_id": parent["spec_id"], "version": parent["version"], "operation": "mutate", "actor": proposer, "from": parent["state"], "to": None, "failed": exc.code}) continue + # The command declares the model that served it (``model`` or ``signal.harness.model``); the family it + # belongs to is what independence is judged on. The declaration is the adapter's, as ``model_usage`` is. + proposer = specmod.party("model", name, delta) + if isinstance(delta, dict): + delta = {k: v for k, v in delta.items() if k not in ("model", "signal", "provider")} try: variant = specmod.make_variant(parent, delta, proposer, graph) except Rejected as exc: @@ -718,10 +788,10 @@ def _variants(args, home: ledger.Ledger) -> int: print(f"{len(variants)} variant(s) written to {out}; review with --reviewer, or pick one and `spec validate` it") return 0 name, _, command = args.reviewer.partition("=") - reviewer = {"kind": "model", "id": name} answer = run_json(split_command(command), specmod.review_request(parent, variants, args.objective), timeout=args.timeout) if not isinstance(answer, dict) or not isinstance(answer.get("verdicts"), list): raise Rejected("review_invalid", "the reviewer answers {\"verdicts\": [...]}") + reviewer = specmod.party("model", name, answer) review = specmod.judge(variants, answer["verdicts"], reviewer) (out / "review.json").write_text(json.dumps(review, indent=2, sort_keys=True) + "\n", encoding="utf-8") for verdict in review["verdicts"]: @@ -742,8 +812,10 @@ def _variants(args, home: ledger.Ledger) -> int: home.append("spec_changed", {"spec_id": chosen["spec_id"], "version": chosen["version"], "operation": "validate", "actor": reviewer, "from": "mutated", "to": "candidate", "spec_digest": specmod.spec_digest(chosen), "accepted_variant": review["accepted"], "verdict_id": verdict_id}) - print(f"accepted {review['accepted']} -> {target.name} (candidate); promote with: " - f"factory spec promote {target.name} --verdict {verdict_id} --actor model:{name} --tickets DIR") + print(f"accepted {review['accepted']} -> {target.name} (candidate); the owner promotes it: " + f"factory approve {target.name} --verdict {verdict_id} --actor human:OWNER --seed-env NAME --out approval.json, then " + f"factory spec promote {target.name} --verdict {verdict_id} --actor human:OWNER --approval approval.json " + f"--owner-public KEY --tickets DIR") return 0 @@ -758,10 +830,24 @@ def _describe_side(entry: dict | None) -> str: return f"{entry['kind']} {entry['name']}: {json.dumps(payload, sort_keys=True, default=str)[:160]}" +def _approve(args) -> int: + """The owner signs an approval of one gated operation on a spec as it is on disk. Nothing touches the + ledger here; `spec promote` verifies and records the approval.""" + document = _read_json(args.spec, "spec") + actor = specmod.principal(args.actor) + payload = specmod.approval_payload(document, args.operation, actor, verdict_ids=args.verdict) + seed = certificate.load_seed(args.seed_env) + envelope = specmod.sign_approval(payload, seed) + Path(args.out).write_text(json.dumps(envelope, indent=2, sort_keys=True) + "\n", encoding="utf-8") + print(f"approved {args.operation} of {document['spec_id']} v{document['version']} (digest {payload['spec_digest'][:12]}) " + f"by {actor['id']}, key {public_from_seed(seed).hex()[:10]}, seed from ${args.seed_env}; wrote {args.out}") + return 0 + + def _spec(args, home: ledger.Ledger) -> int: document = _read_json(args.spec, "spec") - kind, _, actor_id = args.actor.partition(":") - actor = {"kind": kind or "human", "id": actor_id or "operator"} + actor = specmod.principal(args.actor) + before_digest = specmod.spec_digest(document) # the spec as reviewed and as approved, before the footprint moves detail = {} if args.operation == "validate": detail["space"] = home.latest_space() @@ -771,6 +857,18 @@ def _spec(args, home: ledger.Ledger) -> int: detail["reason"] = args.reason if args.superseded_by: detail["superseded_by"] = args.superseded_by + approval_event = None + if args.operation in specmod.GATED: + if actor["kind"] != "human": + raise Rejected("spec_actor", f"{args.operation} is an owner act: the actor's kind is human, not {actor['kind']!r}") + if not args.approval or not args.owner_public: + raise Rejected("spec_approval", f"{args.operation} is an owner act: pass --approval FILE (from `factory approve`) and --owner-public KEY") + envelope = _read_json(args.approval, "approval") + approval, resolved = specmod.gate(document, args.operation, actor, home.events(), envelope, certificate.read_public(args.owner_public), + verdict_ids=args.verdict, spec_digest_value=before_digest) + detail["approval"] = approval + detail["spec_digest"] = before_digest + detail["resolved_verdicts"] = resolved graph = None if args.operation == "promote": graph = home.latest_space() @@ -778,6 +876,9 @@ def _spec(args, home: ledger.Ledger) -> int: raise Rejected("space_missing", "promotion resolves the footprint; index the repository first") specmod.resolve_footprint(document, graph) record = specmod.transition(document, args.operation, actor, **detail) + if args.operation in specmod.GATED: + approval_event = home.record_approval(envelope, detail["approval"]) + record["approval"] = {**record["approval"], "event_hash": approval_event["hash"], "approval_digest": approval_event["body"]["approval_digest"]} Path(args.spec).write_text(json.dumps(document, indent=2, sort_keys=True) + "\n", encoding="utf-8") home.append("spec_changed", {"spec_id": document["spec_id"], "version": document["version"], **record, "spec_digest": specmod.spec_digest(document), @@ -811,13 +912,13 @@ def _attest(args, home: ledger.Ledger) -> int: document = attest.statement(subject_commit=args.commit, repository=args.repository or Path(args.root).resolve().name, spec_ref=ticket["spec_ref"], footprint=ticket.get("footprint"), evidence=evidence, builder=builder, ticket=ticket["ticket_id"], behavior_change_label=args.behavior_change) - written = document + written, public = document, None note = "unsigned" if args.seed_env: seed = certificate.load_seed(args.seed_env) - written = attest.sign(document, seed) - note = f"signed, key {public_from_seed(seed).hex()[:10]}, seed from ${args.seed_env}" - event = home.record_attestation(written) + written, public = attest.sign(document, seed), public_from_seed(seed) + note = f"signed, key {public.hex()[:10]}, seed from ${args.seed_env}" + event = home.record_attestation(written, public) out = Path(args.out) if args.out else home.home / "attestations" / f"{event['body']['attestation_digest']}.json" if args.out: out.write_text(json.dumps(written, indent=2, sort_keys=True) + "\n", encoding="utf-8") @@ -832,10 +933,21 @@ def _attest(args, home: ledger.Ledger) -> int: def viewer_page(records: list[dict], graph: dict | None) -> str: - """A self-contained HTML page: the Space graph with components lit as a slider scrubs the run.""" + """A self-contained HTML page: the Space graph with components lit as a slider scrubs the run. Effects are + referenced (seq, name, digest), never embedded: an io record shows its masked argv and nothing else, so a + payload that reached the journal does not travel with the page.""" template = Path(__file__).resolve().parents[1] / "static" / "factory.html" - data = {"run": records[0] if records else {}, "spans": harness.spans(records), - "effects": [r for r in records if r.get("t") in ("effect", "marker", "io")], + effects = [] + for record in records: + if record.get("t") not in ("effect", "marker", "io"): + continue + entry = {"t": record["t"], "seq": record["seq"], "span": record.get("span"), "name": record["name"], + "digest": record["digest"], "replayed": bool(record.get("replayed"))} + payload = record.get("payload") + if record["t"] == "io" and isinstance(payload, dict) and isinstance(payload.get("argv"), list): + entry["argv"] = [harness.mask(harness.scrub(str(a))) for a in payload["argv"][:8]] + effects.append(entry) + data = {"run": records[0] if records else {}, "spans": harness.spans(records), "effects": effects, "end": records[-1] if records and records[-1].get("t") == "end" else None, "components": [{"id": c["id"], "label": c["label"], "files": len(c["files"])} for c in (graph or {}).get("components", {}).values()], diff --git a/syberlabs/factory/harness.py b/syberlabs/factory/harness.py index f05f3c7..7ad0d2c 100644 --- a/syberlabs/factory/harness.py +++ b/syberlabs/factory/harness.py @@ -28,23 +28,48 @@ ``sys.setprofile``, runs the entrypoint, and reports; the parent only reads the journal the child wrote. A program that wants to record itself in process can install ``recorder.hook`` the same way, outside this repository. + +The child is the candidate's process, so nothing it says is taken on trust: + +- it runs under ``python -I`` (no site customisation, no ``PYTHON*`` variables, + no current directory on ``sys.path``) in a host-owned scratch directory that + is outside the worktree and outside the ledger; the child is never told where + the ledger is, and the parent moves the journal into the ledger afterwards; +- every journal record carries a seal, an HMAC chained from the previous + record under a per-run key the parent generated; ``verify_journal`` refuses a + journal with a record written around the recorder; +- the child's report comes back over a private pipe and must carry the run's + nonce; a line printed to stdout is never a report, and the status in the + report must agree with the ``end`` record the parent reads from the journal. + +The residual is memory: code in the child can reach the recorder (and its key) +through ``sys.modules``, because io observation needs to run in the candidate's +process. That is recorded in ``spec/GAPS.md``; a sandbox is not claimed. """ from __future__ import annotations +import hashlib +import hmac import json import os import re import secrets +import shutil import subprocess import sys +import tempfile +import threading import time from pathlib import Path +from syberlabs._patterns import SECRET from syberlabs.canonical import canonical, digest from syberlabs.errors import Rejected -RECORDER_VERSION = "profile-0.2" +RECORDER_VERSION = "profile-0.3" +MAX_CHANNEL_BYTES = 4 * 1024 * 1024 +MAX_TAIL_CHARS = 4000 # What the child observes without the program's cooperation. Each is a wrapper installed in the child before # the run: a subprocess's argv and cwd, a socket's peer. Observed, journaled as ``io``, never replayed. OBSERVERS = ("subprocess", "socket") @@ -99,6 +124,56 @@ def mask(token: str) -> str: return _HEX_INSIDE.sub("", token) +REDACTED = "" +_CREDENTIAL_KEY = re.compile(r"(?i)(token|secret|passw(or)?d|api[_-]?key|authorization|credential|bearer|extraheader|cookie)") +_CREDENTIAL_FLAGS = frozenset({"--token", "--password", "--passwd", "--secret", "--api-key", "--apikey", "--auth-token", + "--access-token", "--bearer", "-H", "--header", "--cookie"}) +_BEARER = re.compile(r"\bBearer\s+[A-Za-z0-9._~+/=-]{20,}") +_PEM = re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----.*?(?:-----END [A-Z ]*PRIVATE KEY-----|$)", re.S) + + +def scrub(text): + """``text`` with credential shapes removed before it is journaled: the kernel's shared credential pattern + (``syberlabs._patterns.SECRET``, the one ``metrics`` and the query guard use), bearer tokens, PEM private + keys, and the value of a ``KEY=value`` pair whose key names a credential (``GITHUB_TOKEN=``, + ``http.extraheader=``). Anything that is not a string is returned as it is.""" + if not isinstance(text, str): + return text + text = _PEM.sub(REDACTED, _BEARER.sub("Bearer " + REDACTED, SECRET.sub(REDACTED, text))) + head, sep, tail = text.partition("=") + if sep and tail and " " not in head and _CREDENTIAL_KEY.search(head): + return head + "=" + REDACTED + return text + + +def scrub_argv(argv) -> list[str]: + """A subprocess argv with credentials removed: the value after a credential flag (``--token X``, ``-H + 'Authorization: ...'``), the value of ``--flag=X`` for the same flags, and :func:`scrub` on the rest.""" + out = [] + redact_next = False + for item in argv: + item = str(item) + if redact_next: + out.append(REDACTED) + redact_next = False + continue + flag, sep, _value = item.partition("=") + if item in _CREDENTIAL_FLAGS: + out.append(item) + redact_next = True + elif sep and flag in _CREDENTIAL_FLAGS: + out.append(flag + "=" + REDACTED) + else: + out.append(scrub(item)) + return out + + +def scrub_text(text: str, limit: int = MAX_TAIL_CHARS) -> str: + """A bounded tail of free text (a test runner's output) with credential shapes removed, line by line.""" + tail = text[-limit:] if limit else text + return "\n".join(scrub(line) for line in tail.split("\n")) + + def new_run_id() -> str: """Time-ordered, unique: microseconds since the epoch in hex, then 8 random hex digits.""" return f"{int(time.time() * 1_000_000):014x}{secrets.token_hex(4)}" @@ -138,8 +213,12 @@ class Recorder: def __init__(self, root: str | Path, journal: str | Path, file_components: dict | None = None, *, run_id: str | None = None, revision: str | None = None, entrypoint: str | None = None, fixture_digest: str | None = None, space_digest: str | None = None, - replay_of: str | Path | None = None, blobs: str | Path | None = None): + replay_of: str | Path | None = None, blobs: str | Path | None = None, key: str | None = None): self.root = Path(root).resolve() + # The seal: each record's HMAC, chained from the previous record's, under the per-run key ``record`` + # generated in the parent. A line written to the journal file around the recorder has no valid seal. + self._key = key.encode("ascii") if key else None + self._mac = "" self._root_prefix = str(self.root) + os.sep self.journal = Path(journal) self.file_components = dict(file_components or {}) @@ -174,7 +253,7 @@ def __enter__(self) -> "Recorder": "entrypoint": self.entrypoint, "fixture_digest": self.fixture_digest, "space_digest": self.space_digest, "recorder": RECORDER_VERSION, "replay_of": self._replayed_run, "started_at": int(time.time() * 1_000_000), - "root": self.root.name, "python": sys.version.split()[0]} + "root": self.root.name, "python": sys.version.split()[0], "sealed": self._key is not None} self._write(header) _CURRENT.append(self) return self @@ -205,7 +284,11 @@ def _now(self) -> int: def _write(self, record: dict) -> None: if self.seq > MAX_RECORDS: raise Rejected("journal_too_long", f"more than {MAX_RECORDS} records; stop the run") - self._handle.write(json.dumps(record, separators=(",", ":"), ensure_ascii=False, default=str) + "\n") + line = json.dumps(record, separators=(",", ":"), ensure_ascii=False, default=str) + if self._key is not None: + self._mac = _seal(self._key, self._mac, line) + line = line[:-1] + ',"m":"' + self._mac + '"}' + self._handle.write(line + "\n") # -- the profile hook ------------------------------------------------------------------------------------ @@ -334,87 +417,208 @@ def _replay_next(self, kind: str, name: str): # -- recording in a child process ---------------------------------------------------------------------------- +def _seal(key: bytes, previous: str, line: str) -> str: + """The seal of one journal line: HMAC-SHA256 over the previous seal and the line, under the run's key.""" + return hmac.new(key, (previous + line).encode("utf-8"), hashlib.sha256).hexdigest()[:32] + + +def verify_journal(path: str | Path, key: str) -> str | None: + """None when every line of the journal carries the seal the run's key gives it, else the first problem. + A last line without a newline is torn (the child died writing it), which is a problem too: a sealed + journal ends with its ``end`` record.""" + secret = key.encode("ascii") + previous = "" + text = Path(path).read_text(encoding="utf-8") + if not text: + return "the journal is empty" + lines = text.split("\n") + if lines[-1] == "": + lines.pop() + else: + return f"line {len(lines)} is torn" + for index, line in enumerate(lines, 1): + body, sep, tail = line.rpartition(',"m":"') + if not sep or len(tail) != 34 or not tail.endswith('"}'): + return f"line {index} carries no seal" + expected = _seal(secret, previous, body + "}") + if not hmac.compare_digest(expected, tail[:32]): + return f"line {index} was not written by this run's recorder" + previous = expected + return None + + # The child's whole program. It is a string so that no importable file in this repository installs a profile -# hook (see the module docstring). The parent hands it one JSON object on stdin; it prints one JSON line. +# hook (see the module docstring). The parent hands it one JSON object on stdin; it answers one JSON line over +# the private channel, never on stdout. Everything lives in one function so that the program under test finds +# no configuration, key or channel in ``__main__``; what it can still reach is the recorder itself. BOOTSTRAP = r""" -import importlib, importlib.util, json, runpy, sys -config = json.loads(sys.stdin.read()) -# The recorder is the host's, loaded by file under a private name; the program under test then imports -# whatever ``syberlabs`` its own tree holds (on this repository, the candidate's). The two never share a name. -sys.path.insert(0, config["syberlabs_parent"]) -_spec = importlib.util.spec_from_file_location("_factory_harness", config["harness_path"]) -harness = importlib.util.module_from_spec(_spec) -sys.modules["_factory_harness"] = harness -_spec.loader.exec_module(harness) -for _name in [n for n in sys.modules if n == "syberlabs" or n.startswith("syberlabs.")]: - del sys.modules[_name] -sys.path.remove(config["syberlabs_parent"]) -sys.path.insert(0, config["root"]) -recorder = harness.Recorder(config["root"], config["journal"], config["file_components"], run_id=config["run_id"], - revision=config["revision"], entrypoint=config["entry"], fixture_digest=config["fixture_digest"], - space_digest=config["space_digest"], replay_of=config["replay_of"], blobs=config["blobs"]) -report = {"run_id": config["run_id"], "status": None, "error": None, "outcome": None, "counts": None} -if "subprocess" in config["observe"]: - import subprocess as _sp - _popen_init = _sp.Popen.__init__ - def _observed_init(self, args, *rest, **kwargs): - argv = [str(a) for a in (args if isinstance(args, (list, tuple)) else [args])] - recorder.io("subprocess", {"argv": argv[:64], "cwd": str(kwargs.get("cwd") or "")}, - key={"argv": [harness.mask(a) for a in argv[:64]]}) - return _popen_init(self, args, *rest, **kwargs) - _sp.Popen.__init__ = _observed_init -if "socket" in config["observe"]: - import socket as _so - _connect = _so.socket.connect - def _observed_connect(self, address): - recorder.io("socket.connect", {"address": str(address)}) - return _connect(self, address) - _so.socket.connect = _observed_connect -try: - with recorder: - if config["function"]: - # The import is not the run: resolve the function first, then record only the call. - module = importlib.import_module(config["module"]) - function = getattr(module, config["function"]) - sys.setprofile(recorder.hook) - try: - if config["function"]: - outcome = function(recorder.context, config["fixture"]) - try: - json.dumps(outcome) - report["outcome"] = outcome - except (TypeError, ValueError): - report["outcome"] = repr(outcome)[:2000] - else: - runpy.run_path(config["script"], run_name="__main__") - finally: - sys.setprofile(None) -except harness.Diverged as exc: - report["error"] = exc.detail -except SystemExit as exc: - if exc.code not in (None, 0): - report["error"] = "exited with " + str(exc.code) -except BaseException as exc: - report["error"] = type(exc).__name__ + ": " + str(exc)[:300] -report["status"] = recorder.status -report["counts"] = recorder.counts -sys.stdout.write("\n" + json.dumps(report) + "\n") +def _main(): + import importlib, importlib.util, json, os, runpy, sys + config = json.loads(sys.stdin.read()) + if os.name == "nt": + import msvcrt + channel_fd = msvcrt.open_osfhandle(config["channel"], os.O_WRONLY) + os.set_handle_inheritable(config["channel"], False) # a process the program starts does not get it + else: + channel_fd = config["channel"] + os.set_inheritable(channel_fd, False) + channel = os.fdopen(channel_fd, "wb", buffering=0) + nonce = config["nonce"] + # The recorder is the host's, loaded by file under a private name; the program under test then imports + # whatever ``syberlabs`` its own tree holds (on this repository, the candidate's). The two never share a name. + sys.path.insert(0, config["syberlabs_parent"]) + spec = importlib.util.spec_from_file_location("_factory_harness", config["harness_path"]) + harness = importlib.util.module_from_spec(spec) + sys.modules["_factory_harness"] = harness + spec.loader.exec_module(harness) + for name in [n for n in sys.modules if n == "syberlabs" or n.startswith("syberlabs.")]: + del sys.modules[name] + sys.path.remove(config["syberlabs_parent"]) + sys.path.insert(0, config["root"]) + recorder = harness.Recorder(config["root"], config["journal"], config["file_components"], run_id=config["run_id"], + revision=config["revision"], entrypoint=config["entry"], fixture_digest=config["fixture_digest"], + space_digest=config["space_digest"], replay_of=config["replay_of"], blobs=config["blobs"], + key=config["key"]) + report = {"n": nonce, "run_id": config["run_id"], "status": None, "error": None, "outcome": None, "counts": None} + if "subprocess" in config["observe"]: + import subprocess as _sp + _popen_init = _sp.Popen.__init__ + def _observed_init(self, args, *rest, **kwargs): + argv = harness.scrub_argv([str(a) for a in (args if isinstance(args, (list, tuple)) else [args])][:64]) + recorder.io("subprocess", {"argv": argv, "cwd": harness.scrub(str(kwargs.get("cwd") or ""))}, + key={"argv": [harness.mask(a) for a in argv]}) + return _popen_init(self, args, *rest, **kwargs) + _sp.Popen.__init__ = _observed_init + if "socket" in config["observe"]: + import socket as _so + _connect = _so.socket.connect + def _observed_connect(self, address): + recorder.io("socket.connect", {"address": harness.scrub(str(address))}) + return _connect(self, address) + _so.socket.connect = _observed_connect + function = config["function"] + module_name, script, fixture = config["module"], config["script"], config["fixture"] + del config + try: + with recorder: + if function: + # The import is not the run: resolve the function first, then record only the call. + target = getattr(importlib.import_module(module_name), function) + sys.setprofile(recorder.hook) + try: + if function: + outcome = target(recorder.context, fixture) + try: + json.dumps(outcome) + report["outcome"] = outcome + except (TypeError, ValueError): + report["outcome"] = repr(outcome)[:2000] + else: + runpy.run_path(script, run_name="__main__") + finally: + sys.setprofile(None) + except harness.Diverged as exc: + report["error"] = exc.detail + except SystemExit as exc: + if exc.code not in (None, 0): + report["error"] = "exited with " + str(exc.code) + except BaseException as exc: + report["error"] = type(exc).__name__ + ": " + str(exc)[:300] + report["status"] = recorder.status + report["counts"] = recorder.counts + channel.write((json.dumps(report) + "\n").encode("utf-8")) + channel.close() +_main() """ +class _Channel: + """The parent's end of the private pipe: the child inherits only the write end, a thread collects the + lines, and ``report`` accepts exactly one message that carries this run's nonce.""" + + def __init__(self): + self._read, self._write = os.pipe() + self.lines: list[bytes] = [] + self.overflow = False + if os.name == "nt": + import msvcrt + self.handle = msvcrt.get_osfhandle(self._write) + os.set_handle_inheritable(self.handle, True) + info = subprocess.STARTUPINFO() + info.lpAttributeList = {"handle_list": [self.handle]} # only this pipe is inherited, beside the std handles + self.popen_kwargs = {"startupinfo": info} + else: + self.handle = self._write + self.popen_kwargs = {"pass_fds": (self._write,)} + self._reader = threading.Thread(target=self._collect, daemon=True) + + def started(self) -> None: + """The child holds the write end now (or never will): drop the parent's copy and start reading.""" + os.close(self._write) + self._reader.start() + + def _collect(self) -> None: + total = 0 + with os.fdopen(self._read, "rb") as stream: + for line in stream: + total += len(line) + if total > MAX_CHANNEL_BYTES: + self.overflow = True + continue + self.lines.append(line) + + def report(self, nonce: str) -> tuple[dict | None, str | None]: + """The one report bound to ``nonce``, or the reason there is none.""" + self._reader.join(timeout=30) + if self._reader.is_alive(): + return None, "the channel stayed open after the child exited" + if self.overflow: + return None, f"the channel carried more than {MAX_CHANNEL_BYTES} bytes" + if len(self.lines) != 1: + return None, f"the channel carried {len(self.lines)} messages, not one" + try: + message = json.loads(self.lines[0]) + except ValueError: + return None, "the message is not JSON" + if not isinstance(message, dict) or not hmac.compare_digest(str(message.get("n")), nonce): + return None, "the message does not carry this run's nonce" + message.pop("n", None) + return message, None + + +def _tail(path: Path) -> str: + try: + size = path.stat().st_size + with path.open("rb") as handle: + handle.seek(max(0, size - MAX_TAIL_CHARS * 4)) + return handle.read().decode("utf-8", errors="replace")[-MAX_TAIL_CHARS:] + except OSError: + return "" + + def record(root: str | Path, journal: str | Path, entry: str, *, file_components: dict | None = None, fixture: dict | None = None, run_id: str | None = None, revision: str | None = None, space_digest: str | None = None, replay_of: str | Path | None = None, blobs: str | Path | None = None, python: str | None = None, timeout: float = 3600.0, observe: tuple = OBSERVERS) -> dict: - """Run ``entry`` under the recorder in a child interpreter and return its report. + """Run ``entry`` under the recorder in an isolated child interpreter and return its report. ``entry`` is ``module:function`` (imported from ``root``, called as ``function(ctx, fixture)``) or a script path (run as ``__main__``; it takes its context from :func:`current`). The report has ``run_id``, ``status`` - (``ok``, ``diverged``, ``error``, or ``killed`` on timeout), ``counts``, ``outcome`` and ``error``. The - journal is at ``journal`` whatever happened. ``observe`` names the io observers the child installs - (default: subprocesses and socket connections); pass ``()`` for none. The child inherits this process's environment: a program's - own secrets stay its own, and nothing here is a sandbox.""" + (``ok``, ``diverged``, ``error``, or ``killed`` on timeout), ``counts``, ``outcome``, ``error``, and the tails + of ``stdout`` and ``stderr``. ``observe`` names the io observers the child installs (default: subprocesses + and socket connections); pass ``()`` for none. + + The child runs ``python -I`` in a host-owned scratch directory and writes its journal and blobs there; it is + never told where ``journal`` or ``blobs`` are. Afterwards the parent verifies the journal's seal under the + per-run key, reads the ``end`` record itself, requires the child's report (one message on a private pipe, + bound by the run's nonce) to agree with it, and only then moves the journal to ``journal`` and the blobs to + ``blobs``. A journal that fails its seal is not delivered. On timeout the whole process tree is stopped. + The child inherits this process's environment (``-I`` drops the ``PYTHON*`` variables): a program's own + secrets stay its own, and nothing here is a sandbox.""" + from syberlabs.checks import _stop as stop_tree # the Build Thread's own tree kill; parent side only + root = Path(root).resolve() + destination = Path(journal).resolve() run_id = run_id or new_run_id() module = function = script = None if ":" in entry and not Path(entry).exists(): @@ -423,37 +627,98 @@ def record(root: str | Path, journal: str | Path, entry: str, *, file_components script = str(Path(entry).resolve()) if not Path(script).exists(): raise Rejected("entry_missing", f"{entry} is neither module:function nor a file") - config = { - "root": str(root), "journal": str(Path(journal).resolve()), "file_components": dict(file_components or {}), - "run_id": run_id, "revision": revision, "entry": entry, "fixture": fixture if fixture is not None else {}, - "fixture_digest": digest(fixture if fixture is not None else {}), "space_digest": space_digest, - "replay_of": str(Path(replay_of).resolve()) if replay_of else None, "blobs": str(Path(blobs).resolve()) if blobs else None, - "module": module, "function": function, "script": script, "observe": list(observe), - "syberlabs_parent": str(Path(__file__).resolve().parents[2]), "harness_path": str(Path(__file__).resolve()), - } - Path(journal).parent.mkdir(parents=True, exist_ok=True) + nonce, key = secrets.token_hex(16), secrets.token_hex(32) + report = {"run_id": run_id, "status": "error", "error": None, "counts": None, "outcome": None, + "stdout": "", "stderr": "", "returncode": None} + scratch = Path(tempfile.mkdtemp(prefix="syberlabs-factory-")) # host-owned: outside the worktree and the ledger try: - done = subprocess.run([python or sys.executable, "-c", BOOTSTRAP], input=json.dumps(config), capture_output=True, - text=True, cwd=str(root), timeout=timeout, encoding="utf-8", errors="replace") - except subprocess.TimeoutExpired: - return {"run_id": run_id, "status": "killed", "error": f"no end after {timeout} seconds", "counts": None, - "outcome": None, "stdout": "", "stderr": ""} - lines = done.stdout.splitlines() - report = None - for index in range(len(lines) - 1, -1, -1): - if lines[index].startswith("{") and '"run_id"' in lines[index]: + child_journal = scratch / "journal.jsonl" + child_blobs = scratch / "blobs" if blobs is not None else None + child_replay = None + if replay_of is not None: + child_replay = scratch / "replay.jsonl" + shutil.copyfile(replay_of, child_replay) + if blobs is not None: + child_blobs.mkdir() + for recorded in read_journal(child_replay): + blob = recorded.get("blob") + if blob and (Path(blobs) / blob).exists(): + shutil.copyfile(Path(blobs) / blob, child_blobs / blob) + config = { + "root": str(root), "journal": str(child_journal), "file_components": dict(file_components or {}), + "run_id": run_id, "revision": revision, "entry": entry, "fixture": fixture if fixture is not None else {}, + "fixture_digest": digest(fixture if fixture is not None else {}), "space_digest": space_digest, + "replay_of": str(child_replay) if child_replay else None, "blobs": str(child_blobs) if child_blobs else None, + "module": module, "function": function, "script": script, "observe": list(observe), + "syberlabs_parent": str(Path(__file__).resolve().parents[2]), "harness_path": str(Path(__file__).resolve()), + "nonce": nonce, "key": key, + } + channel = _Channel() + killed = False + with (scratch / "stdout").open("wb") as out, (scratch / "stderr").open("wb") as err: try: - report = json.loads(lines[index]) - except ValueError: - continue - lines = lines[:index] - break - if report is None: - report = {"run_id": run_id, "status": "error", "error": f"the child exited {done.returncode} without a report", - "counts": None, "outcome": None} - report["stdout"] = "\n".join(lines) - report["stderr"] = done.stderr[-4000:] - report["returncode"] = done.returncode + proc = subprocess.Popen([python or sys.executable, "-I", "-c", BOOTSTRAP], stdin=subprocess.PIPE, stdout=out, + stderr=err, cwd=str(root), close_fds=True, start_new_session=hasattr(os, "setsid"), + **channel.popen_kwargs) + finally: + channel.started() + try: + proc.stdin.write(json.dumps({**config, "channel": channel.handle}).encode("utf-8")) + proc.stdin.close() + except OSError: + pass # the child is already gone; its missing report says so + deadline = time.monotonic() + timeout + while True: + try: + report["returncode"] = proc.wait(timeout=0.05) + break + except subprocess.TimeoutExpired: + pass + if time.monotonic() > deadline: + stop_tree(proc) + killed = True + break + report["stdout"], report["stderr"] = _tail(scratch / "stdout"), _tail(scratch / "stderr") + message, problem = channel.report(nonce) + deliver = child_journal.exists() + if killed: + report["status"], report["error"] = "killed", f"no end after {timeout} seconds" + elif not deliver: + report["error"] = "the child wrote no journal" + else: + unsealed = verify_journal(child_journal, key) + if unsealed is not None: + report["error"] = f"journal_unsealed: {unsealed}" + deliver = False + else: + records = read_journal(child_journal) + end = records[-1] if records and records[-1].get("t") == "end" else None + if end is None or records[0].get("t") != "run" or records[0].get("run_id") != run_id: + report["error"] = "the journal has no end record for this run" + deliver = False # a journal the recorder never closed is not evidence of a run + else: + report["status"], report["counts"] = end["status"], end.get("counts") + if message is None: + report["error"] = report["error"] or f"no report over the private channel: {problem}" + if report["status"] == "ok": + report["status"] = "error" + elif message.get("run_id") != run_id or message.get("status") != report["status"]: + if report["status"] != "killed": + report["status"] = "error" + report["error"] = report["error"] or "the child's report does not match its journal" + else: + report["outcome"] = message.get("outcome") + report["error"] = report["error"] or message.get("error") + if deliver: + destination.parent.mkdir(parents=True, exist_ok=True) + shutil.move(str(child_journal), str(destination)) + if child_blobs is not None and child_blobs.exists(): + Path(blobs).mkdir(parents=True, exist_ok=True) + for blob in child_blobs.iterdir(): + if not (Path(blobs) / blob.name).exists(): + shutil.move(str(blob), str(Path(blobs) / blob.name)) + finally: + shutil.rmtree(scratch, ignore_errors=True) return report diff --git a/syberlabs/factory/independence.py b/syberlabs/factory/independence.py new file mode 100644 index 0000000..8e73932 --- /dev/null +++ b/syberlabs/factory/independence.py @@ -0,0 +1,63 @@ +"""Reviewer independence by provider family, not by the name a caller typed. + +A proposer and a reviewer are independent when the models that served them belong to different provider +families. The family is read from what was recorded about the party: a kernel candidate's +``signal.harness.model`` (``docs/EVOLUTION.md``), a party's own ``model`` or ``family``, or its +``provider.model``. A party whose family cannot be told is not independent of anyone: the check refuses +rather than guesses. Small and importable on purpose, so ``syberlabs.critic.independent`` can adopt it; this +module changes nothing in ``critic``. +""" + +from __future__ import annotations + +FAMILIES = { + "anthropic": ("claude",), + "openai": ("gpt-", "gpt4", "gpt5", "o1", "o3", "o4", "chatgpt", "codex"), + "google": ("gemini", "gemma"), + "xai": ("grok",), + "meta": ("llama",), + "mistral": ("mistral", "mixtral", "codestral", "devstral"), + "deepseek": ("deepseek",), + "alibaba": ("qwen",), + "amazon": ("nova",), + "cohere": ("command",), +} + + +def model_of(party: dict | None) -> str | None: + """The model id recorded for a party: ``signal.harness.model``, ``model``, or ``provider.model``.""" + if not isinstance(party, dict): + return None + harness = (party.get("signal") or {}).get("harness") if isinstance(party.get("signal"), dict) else None + for candidate in ((harness or {}).get("model"), party.get("model"), (party.get("provider") or {}).get("model") + if isinstance(party.get("provider"), dict) else None): + if isinstance(candidate, str) and candidate.strip(): + return candidate.strip() + return None + + +def family(party: dict | None) -> str | None: + """The provider family of a party, or None when it is not recorded and cannot be told from the model id. + An explicit ``family`` wins over the model id; an unknown family name is still None.""" + if isinstance(party, dict) and isinstance(party.get("family"), str) and party["family"].lower() in FAMILIES: + return party["family"].lower() + model = model_of(party) + if model is None: + return None + lowered = model.lower() + for name, prefixes in FAMILIES.items(): + if any(lowered.startswith(prefix) or ("/" + prefix) in lowered for prefix in prefixes): + return name + return None + + +def independence(proposer: dict | None, reviewer: dict | None) -> tuple[bool, str]: + """Whether ``reviewer`` may judge what ``proposer`` made, and why. Independent only when both families + are known and differ; an unknown family refuses.""" + a, b = family(proposer), family(reviewer) + if a is None or b is None: + who = "the proposer" if a is None else "the reviewer" + return False, f"{who}'s provider family is not recorded (no model id or an unknown one): refuse" + if a == b: + return False, f"the proposer and the reviewer are both served by {a}: not independent" + return True, f"proposer {a}, reviewer {b}" diff --git a/syberlabs/factory/ledger.py b/syberlabs/factory/ledger.py index bf81093..9ab4191 100644 --- a/syberlabs/factory/ledger.py +++ b/syberlabs/factory/ledger.py @@ -7,36 +7,48 @@ runs/.jsonl harness journals blobs/ effect payloads too large to inline attestations/.json + approvals/.json the owner's signed approvals a promotion rests on index.sqlite3 the projection: components, runs, steps, cells, edges; rebuilt from the above + .journal/ the kernel journal's lock file for this ledger (``syberlabs.journal``) The event log is the system of record. Every event carries ``seq``, ``kind``, ``body``, ``at`` (integer -microseconds), ``previous`` and ``hash``; ``verify`` walks the chain. Bodies hold digests and ids, not -payloads, so the log stays small while artifacts stay content-addressed. +microseconds), ``previous`` and ``hash``; ``verify`` walks the chain and then every artifact an event names, +comparing the file with the digest the event recorded. Bodies hold digests and ids, not payloads, so the log +stays small while artifacts stay content-addressed. An artifact is never read by name alone: ``load_run`` +and ``load_space`` refuse a file whose digest is not the one on the ledger, so an edited golden journal cannot +become a gate's baseline. + +Appends go through the kernel journal's writer (``syberlabs.journal.Journal``): a cross-process lock (``flock`` +or ``msvcrt.locking``), flush and fsync per record, and truncation of a torn final line before the next read. +Two factory commands on one home therefore serialize instead of forking the chain. A cell is (component, step, commit): one span of one run, attributed to the component that owned its file at that run's revision. The grid is sparse; only steps that ran become cells. ``cells_for`` slices by component -across commits, ``worldline`` slices by run, ``active_at`` slices by step. - -One process writes a ledger at a time. There is no cross-process lock here, by design: the factory runs as a -CLI or a test, not a service, and a lock that works on Windows and POSIX alike is the journal's job, not this -file's. +across commits, ``worldline`` slices by run, ``active_at`` slices by step. The projection is rebuilt when the +log it was built from has moved on (its ``meta`` row records the chain head it reflects); the ``features`` +table ``features.build`` keeps in the same file survives a rebuild. """ from __future__ import annotations +import hashlib import json import sqlite3 import time +from contextlib import contextmanager from pathlib import Path +from syberlabs import journal as kernel_journal from syberlabs.canonical import canonical, digest from syberlabs.errors import Rejected -from syberlabs.factory import PROTOCOL, harness, space +from syberlabs.factory import PROTOCOL, attest, harness, space GENESIS = "0" * 64 EVENT_FIELDS = ("seq", "kind", "body", "at", "previous") +RUN_KINDS = frozenset({"run_recorded", "run_replayed"}) KINDS = frozenset({"space_indexed", "run_recorded", "run_replayed", "spec_changed", "ticket_opened", - "attested", "drift_reported", "baseline_set", "note"}) + "attested", "drift_reported", "baseline_set", "approval_recorded", "note"}) +PROJECTION_TABLES = ("components", "edges", "runs", "steps", "effects", "cells", "meta") def event_digest(event: dict) -> str: @@ -55,44 +67,101 @@ def _verify_chain(events: list[dict]) -> bool: return True +def _file_digest(path: Path) -> str: + return hashlib.sha256(path.read_bytes()).hexdigest() + + class Ledger: def __init__(self, home: str | Path = ".syberlabs/factory"): self.home = Path(home) - for name in ("space", "runs", "blobs", "attestations"): + for name in ("space", "runs", "blobs", "attestations", "approvals"): (self.home / name).mkdir(parents=True, exist_ok=True) self.log = self.home / "ledger.jsonl" self.database = self.home / "index.sqlite3" # -- the event log ----------------------------------------------------------------------------------------- + @contextmanager + def _locked(self): + """The kernel journal's lock over this ledger, held for one read or one read-then-append. A fresh + ``Journal`` per operation: every command reads the ledger from its first byte anyway, and no lock + handle outlives the call (a held handle would pin the directory on Windows).""" + writer = kernel_journal.Journal(self.home / ".journal") + try: + with writer.locked(): + yield writer + finally: + writer.close() + + def _read(self, writer: kernel_journal.Journal) -> list[dict]: + try: + return writer.read_new(self.log) + except Rejected as exc: + raise Rejected("ledger_unreadable", f"{self.log}: {exc.detail}") from None + def events(self) -> list[dict]: - if not self.log.exists(): - return [] - out = [] - for number, line in enumerate(self.log.read_text(encoding="utf-8").splitlines(), 1): - if not line.strip(): - continue + with self._locked() as writer: + return self._read(writer) + + def head(self, events: list[dict] | None = None) -> str: + events = self.events() if events is None else events + return events[-1]["hash"] if events else GENESIS + + def problems(self, events: list[dict] | None = None) -> list[str]: + """Why the ledger does not verify: the chain first, then every artifact an event names whose file is + missing or whose digest is not the recorded one (Space graphs, journals and the blobs they reference, + attestations, approvals). Empty when everything holds.""" + events = self.events() if events is None else events + if not _verify_chain(events): + return ["the event chain does not verify"] + found = [] + for event in events: + body, kind = event["body"], event["kind"] try: - out.append(json.loads(line)) - except ValueError: - raise Rejected("ledger_unreadable", f"{self.log}: line {number} is not JSON") from None - return out + if kind == "space_indexed": + path = self.space_path(body["space_digest"]) + if not path.exists(): + found.append(f"space/{body['space_digest'][:12]} is missing") + elif space.graph_digest(json.loads(path.read_text(encoding="utf-8"))) != body["space_digest"]: + found.append(f"space/{body['space_digest'][:12]} does not match its digest") + elif kind in RUN_KINDS: + path = self.run_path(body["run_id"]) + if not path.exists(): + found.append(f"runs/{body['run_id']} is missing") + elif _file_digest(path) != body["journal_digest"]: + found.append(f"runs/{body['run_id']} does not match the digest recorded at seq {event['seq']}") + else: + for record in harness.read_journal(path): + blob = record.get("blob") + if blob and (not (self.home / "blobs" / blob).exists() or _file_digest(self.home / "blobs" / blob) != blob): + found.append(f"blobs/{blob[:12]} of run {body['run_id']} is missing or does not match") + elif kind in ("attested", "approval_recorded"): + folder, key = ("attestations", "attestation_digest") if kind == "attested" else ("approvals", "approval_digest") + path = self.home / folder / f"{body[key]}.json" + if not path.exists(): + found.append(f"{folder}/{body[key][:12]} is missing") + elif digest(json.loads(path.read_text(encoding="utf-8"))) != body[key]: + found.append(f"{folder}/{body[key][:12]} does not match its digest") + except (KeyError, TypeError, ValueError, OSError, Rejected) as exc: + found.append(f"seq {event['seq']} ({kind}): {type(exc).__name__}") + return found - def verify(self) -> bool: - return _verify_chain(self.events()) + def verify(self, events: list[dict] | None = None) -> bool: + """True when the chain verifies and every artifact the events name matches its recorded digest.""" + return not self.problems(events) def append(self, kind: str, body: dict) -> dict: if kind not in KINDS: raise Rejected("ledger_kind", f"unknown event kind {kind!r}") - events = self.events() - previous = events[-1]["hash"] if events else GENESIS - if not _verify_chain(events): - raise Rejected("ledger_corrupt", "the hash chain does not verify; refusing to append to an edited ledger") - event = {"seq": len(events) + 1, "kind": kind, "body": body, "at": int(time.time() * 1_000_000), - "previous": previous} - event["hash"] = event_digest(event) - with self.log.open("a", encoding="utf-8", newline="\n") as handle: - handle.write(canonical(event) + "\n") + with self._locked() as writer: + events = self._read(writer) + if not _verify_chain(events): + raise Rejected("ledger_corrupt", "the hash chain does not verify; refusing to append to an edited ledger") + event = {"seq": len(events) + 1, "kind": kind, "body": body, "at": int(time.time() * 1_000_000), + "previous": events[-1]["hash"] if events else GENESIS} + event["hash"] = event_digest(event) + # The kernel journal's append: flushed, fsynced, and refused if another writer slipped in between. + writer._write(self.log, event) return event # -- artifacts ----------------------------------------------------------------------------------------------- @@ -110,13 +179,19 @@ def record_space(self, graph: dict, declared_digest: str | None = None) -> dict: return self.append("space_indexed", body) def space_path(self, sha: str) -> Path: + if not sha or any(c not in "0123456789abcdef" for c in sha): + raise Rejected("space_digest", f"a Space digest is lowercase hex, not {sha!r}") return self.home / "space" / f"{sha}.json" def load_space(self, sha: str) -> dict: + """The Space graph named ``sha``, refused unless its content digests to that name.""" path = self.space_path(sha) if not path.exists(): raise Rejected("space_missing", f"no Space graph {sha[:12]} in {self.home}") - return json.loads(path.read_text(encoding="utf-8")) + graph = json.loads(path.read_text(encoding="utf-8")) + if space.graph_digest(graph) != sha: + raise Rejected("artifact_tampered", f"space/{sha[:12]}.json does not digest to its name") + return graph def latest_space(self, revision: str | None = None) -> dict | None: """The most recently logged Space graph, or the most recent one for ``revision``.""" @@ -131,32 +206,50 @@ def run_path(self, run_id: str) -> Path: return self.home / "runs" / f"{run_id}.jsonl" def record_run(self, run_id: str, replay_of: str | None = None) -> dict: - """Log a journal the harness wrote into ``runs/``. Returns the event.""" + """Log a journal the harness delivered into ``runs/``. Returns the event. The digest recorded here is + what every later ``load_run`` checks the file against.""" path = self.run_path(run_id) + if not path.exists(): + raise Rejected("run_missing", f"no run {run_id} in {self.home}") records = harness.read_journal(path) if not records or records[0].get("t") != "run" or records[0].get("run_id") != run_id: raise Rejected("journal_unreadable", f"{path} is not the journal of run {run_id}") header, tail = records[0], records[-1] - body = {"run_id": run_id, "journal_digest": harness.journal_digest(path), "revision": header.get("revision"), + body = {"run_id": run_id, "journal_digest": _file_digest(path), "revision": header.get("revision"), "entrypoint": header.get("entrypoint"), "space_digest": header.get("space_digest"), "fixture_digest": header.get("fixture_digest"), "status": tail.get("status") if tail.get("t") == "end" else "open", - "counts": tail.get("counts") if tail.get("t") == "end" else None, "replay_of": replay_of or header.get("replay_of")} + "counts": tail.get("counts") if tail.get("t") == "end" else None, "replay_of": replay_of or header.get("replay_of"), + "sealed": bool(header.get("sealed"))} return self.append("run_replayed" if body["replay_of"] else "run_recorded", body) + def run_record(self, run_id: str, events: list[dict] | None = None) -> dict | None: + """The ledger's record of ``run_id`` (the newest ``run_recorded`` or ``run_replayed`` body), or None.""" + for event in reversed(self.events() if events is None else events): + if event["kind"] in RUN_KINDS and event["body"].get("run_id") == run_id: + return event["body"] + return None + def load_run(self, run_id: str) -> list[dict]: + """A recorded run's journal, refused when the ledger never logged it or the file no longer matches the + digest the ledger recorded.""" path = self.run_path(run_id) if not path.exists(): raise Rejected("run_missing", f"no run {run_id} in {self.home}") + recorded = self.run_record(run_id) + if recorded is None: + raise Rejected("run_unrecorded", f"run {run_id} is in runs/ but not on the ledger; refusing to read an unlogged journal") + if _file_digest(path) != recorded["journal_digest"]: + raise Rejected("artifact_tampered", f"runs/{run_id}.jsonl does not match the digest the ledger recorded") return harness.read_journal(path) def runs(self) -> list[dict]: - return [e["body"] for e in self.events() if e["kind"] in ("run_recorded", "run_replayed")] + return [e["body"] for e in self.events() if e["kind"] in RUN_KINDS] def set_baseline(self, run_id: str, label: str = "golden") -> dict: """Name a recorded run as the golden a later ``check`` diffs against. Labels are free text; the - newest ``baseline_set`` for a label wins, so re-pointing is one more event, never an edit.""" - if not self.run_path(run_id).exists(): - raise Rejected("run_missing", f"no run {run_id} in {self.home}") + newest ``baseline_set`` for a label wins, so re-pointing is one more event, never an edit. The run + must be on the ledger and intact (``load_run``).""" + self.load_run(run_id) if not label or any(c in label for c in " /\\"): raise Rejected("baseline_label", f"a label is one word, not {label!r}") return self.append("baseline_set", {"label": label, "run_id": run_id}) @@ -168,31 +261,49 @@ def baseline(self, label: str = "golden") -> str | None: return event["body"]["run_id"] return None - def record_attestation(self, document: dict) -> dict: - """Store an attestation (a statement or its DSSE envelope) by digest and log it.""" + def record_attestation(self, document: dict, public: bytes | None = None) -> dict: + """Store an attestation (a statement or its DSSE envelope) by digest and log it. ``signed`` is true + only when the envelope's signature verifies under ``public``; an envelope recorded without the key, + or one that does not verify, is logged ``signed: false`` with ``envelope: true``.""" sha = digest(document) (self.home / "attestations" / f"{sha}.json").write_text(canonical(document), encoding="utf-8") - statement = document - if "payloadType" in document: - import base64 - statement = json.loads(base64.standard_b64decode(document["payload"])) + envelope = "payloadType" in document + statement = attest.verify(document, public) if envelope and public is not None else None + signed = statement is not None + if statement is None: + try: + statement = attest.unwrap(document) + except (ValueError, TypeError, KeyError): + raise Rejected("attestation_unreadable", "the envelope's payload is not a statement") from None predicate = statement.get("predicate", {}) - body = {"attestation_digest": sha, "signed": "payloadType" in document, + body = {"attestation_digest": sha, "signed": signed, "envelope": envelope, + "keyid": public.hex() if signed else None, "subject": [s.get("name") for s in statement.get("subject", [])], "spec": predicate.get("spec", {}).get("spec_id"), "ticket": predicate.get("ticket"), "diff_empty": (predicate.get("evidence", {}).get("trace_diff") or {}).get("diff_empty"), "promote": (predicate.get("policy") or {}).get("promote")} return self.append("attested", body) + def record_approval(self, envelope: dict, approval: dict) -> dict: + """Store a verified owner approval (its DSSE envelope) by digest and log it; ``approval`` is the + payload :func:`spec.verify_approval` returned. The event's hash is what the ``spec_changed`` cites.""" + sha = digest(envelope) + (self.home / "approvals" / f"{sha}.json").write_text(canonical(envelope), encoding="utf-8") + body = {"approval_digest": sha, "keyid": approval["keyid"], "approver": approval["approver"], + "operation": approval["operation"], "spec_id": approval["spec_id"], "version": approval["version"], + "spec_digest": approval["spec_digest"], "verdict_ids": list(approval.get("verdict_ids") or [])} + return self.append("approval_recorded", body) + # -- the projection ----------------------------------------------------------------------------------------- - def project(self) -> dict: - """Rebuild ``index.sqlite3`` from the log and its artifacts. Returns row counts.""" - if self.database.exists(): - self.database.unlink() + def project(self, events: list[dict] | None = None) -> dict: + """Rebuild the projection tables in ``index.sqlite3`` from the log and its artifacts. Returns row + counts. Tables other modules keep in the same file (``features``) are left alone.""" + events = self.events() if events is None else events connection = sqlite3.connect(self.database) try: - connection.executescript(""" + connection.executescript("".join(f"DROP TABLE IF EXISTS {table};" for table in PROJECTION_TABLES) + """ + CREATE TABLE meta (head TEXT, count INTEGER); CREATE TABLE components (space_digest TEXT, revision TEXT, id TEXT, label TEXT, files INTEGER); CREATE TABLE edges (space_digest TEXT, src TEXT, dst TEXT, count INTEGER, declared INTEGER); CREATE TABLE runs (run_id TEXT PRIMARY KEY, revision TEXT, entrypoint TEXT, space_digest TEXT, @@ -206,7 +317,7 @@ def project(self) -> dict: CREATE INDEX steps_run ON steps (run_id, seq_start); """) counts = {"components": 0, "edges": 0, "runs": 0, "steps": 0, "effects": 0, "cells": 0} - for event in self.events(): + for event in events: body = event["body"] if event["kind"] == "space_indexed": graph = self.load_space(body["space_digest"]) @@ -221,10 +332,10 @@ def project(self) -> dict: (body["space_digest"], edge["from"], edge["to"], edge["count"], int((edge["from"], edge["to"]) in declared))) counts["edges"] += 1 - elif event["kind"] in ("run_recorded", "run_replayed"): + elif event["kind"] in RUN_KINDS: path = self.run_path(body["run_id"]) - if not path.exists(): - continue + if not path.exists() or _file_digest(path) != body["journal_digest"]: + continue # a missing or edited journal projects nothing; ``verify`` names it records = harness.read_journal(path) connection.execute("INSERT OR REPLACE INTO runs VALUES (?,?,?,?,?,?,?)", (body["run_id"], body.get("revision"), body.get("entrypoint"), @@ -247,14 +358,29 @@ def project(self) -> dict: (body["run_id"], record["seq"], record.get("span"), record["t"], record["name"], record["digest"])) counts["effects"] += 1 + connection.execute("INSERT INTO meta VALUES (?, ?)", (self.head(events), len(events))) connection.commit() finally: connection.close() return counts - def _query(self, sql: str, params: tuple = ()) -> list[tuple]: + def _stale(self, events: list[dict]) -> bool: + """True when the projection is missing or was built from a shorter or different log.""" if not self.database.exists(): - self.project() + return True + connection = sqlite3.connect(self.database) + try: + row = connection.execute("SELECT head, count FROM meta").fetchone() + except sqlite3.Error: + return True + finally: + connection.close() + return row is None or row[0] != self.head(events) or row[1] != len(events) + + def _query(self, sql: str, params: tuple = ()) -> list[tuple]: + events = self.events() + if self._stale(events): + self.project(events) connection = sqlite3.connect(self.database) try: return connection.execute(sql, params).fetchall() @@ -285,8 +411,11 @@ def components_at(self, revision: str) -> list[str]: def describe(self) -> dict: events = self.events() - return {"protocol": PROTOCOL, "home": str(self.home), "events": len(events), "verified": self.verify(), + problems = self.problems(events) + return {"protocol": PROTOCOL, "home": str(self.home), "events": len(events), "verified": not problems, + "problems": len(problems), "spaces": sum(1 for e in events if e["kind"] == "space_indexed"), - "runs": sum(1 for e in events if e["kind"] in ("run_recorded", "run_replayed")), + "runs": sum(1 for e in events if e["kind"] in RUN_KINDS), "attestations": sum(1 for e in events if e["kind"] == "attested"), - "head": events[-1]["hash"] if events else GENESIS} + "approvals": sum(1 for e in events if e["kind"] == "approval_recorded"), + "head": self.head(events)} diff --git a/syberlabs/factory/spec.py b/syberlabs/factory/spec.py index fb59c16..7ee5b35 100644 --- a/syberlabs/factory/spec.py +++ b/syberlabs/factory/spec.py @@ -10,17 +10,31 @@ a promoted spec with the footprint resolved, the acceptance criteria copied from the scenarios, and one exit criterion per evidence kind. Agents are delegated to; a human stays the owner. +The goal gate. The factory may propose a spec at any level; it may promote none. ``promote``, ``canonize`` +and ``retire`` (``GATED``) take a human actor and an approval that verifies: a DSSE envelope the owner signed +over exactly this spec (its digest before the operation), this operation and, for a promotion, the verdict +ids it rests on, each resolved on the ledger to a ``review`` event that accepted this very variant. The +approver may not be a proposer or the reviewer of that variant. ``transition`` accepts only the ``Approved`` +record :func:`verify_approval` returns, so a caller cannot hand it a dictionary of its own. The owner's +public key is the caller's (``--owner-public``); the signing seed never enters this module. A kernel +``approved`` event on a goal case is the intended source of this approval once the factory has a case to +hang it on; until then the signature stands in, and ``spec/GAPS.md`` records the gap. + v0 implements the lifecycle a single spec needs: draft, revise, validate (to candidate), promote, canonize, -retire. Mutation (several models proposing variants of one parent) is the v1 addition; the fields are here. +retire, and the variant loop (several models proposing variants of one parent, one independent reviewer). """ from __future__ import annotations import json +import re +import time -from syberlabs.canonical import digest +from syberlabs.canonical import canonical, digest +from syberlabs.dsse import sign_dsse, verified_payload from syberlabs.errors import Rejected from syberlabs.factory import PROTOCOL +from syberlabs.factory.independence import family, independence, model_of STATES = ("draft", "revised", "mutated", "candidate", "promoted", "canonical", "retired") EVIDENCE_KINDS = frozenset({"trace_diff", "drift", "tests", "mutation", "critic", "replay"}) @@ -32,6 +46,113 @@ "canonize": ({"promoted"}, "canonical"), "retire": ({"canonical", "promoted", "candidate"}, "retired"), } +GATED = frozenset({"promote", "canonize", "retire"}) +ACTOR_KINDS = ("human", "model", "compiled") +APPROVAL_PROTOCOL = "syberlabs.space/factory/approval/v0" +APPROVAL_PAYLOAD_TYPE = "application/vnd.syberlabs.factory-approval+json" +_PRINCIPAL_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._@+-]{0,63}$") + + +def principal(text: str) -> dict: + """``kind:id`` as a principal: ``kind`` is human, model or compiled and ``id`` is one token of at most 64 + characters. Free text is refused, so an actor on the ledger is always a resolvable identity.""" + kind, sep, actor_id = (text or "").partition(":") + if not sep or kind not in ACTOR_KINDS or not _PRINCIPAL_ID.match(actor_id): + raise Rejected("actor_invalid", f"an actor is kind:id with kind in {ACTOR_KINDS} and a one-token id, not {text!r}") + return {"kind": kind, "id": actor_id} + + +class Approved(dict): + """A verified approval. Only :func:`verify_approval` makes one; ``transition`` accepts no other.""" + + +def approval_payload(spec: dict, operation: str, approver: dict, *, verdict_ids: list[str] | None = None, + spec_digest_value: str | None = None) -> dict: + """What the owner signs: this spec (by id, version and digest), this operation, the verdicts a promotion + rests on, and who approves. The digest is the spec's as it is on disk before the operation.""" + if operation not in GATED: + raise Rejected("spec_operation", f"an approval covers one of {sorted(GATED)}, not {operation!r}") + if approver.get("kind") != "human": + raise Rejected("approval_actor", "an approval is a human act; the approver's kind is human") + return {"protocol": APPROVAL_PROTOCOL, "operation": operation, "spec_id": spec["spec_id"], "version": spec["version"], + "spec_digest": spec_digest_value or spec_digest(spec), "verdict_ids": sorted(verdict_ids or []), + "approver": {"kind": "human", "id": approver["id"]}, "at": int(time.time() * 1_000_000)} + + +def sign_approval(payload: dict, seed: bytes) -> dict: + """The owner's DSSE envelope over the canonical approval payload (the certificate module's Ed25519).""" + return sign_dsse(APPROVAL_PAYLOAD_TYPE, canonical(payload).encode("utf-8"), seed) + + +def verify_approval(envelope: dict, public: bytes, spec: dict, operation: str, *, verdict_ids: list[str] | None = None, + spec_digest_value: str | None = None) -> Approved: + """The approval inside ``envelope`` when its signature verifies under the owner's ``public`` key and it + covers exactly this spec, this operation and these verdicts. Anything else is refused.""" + payload = verified_payload(envelope, public, APPROVAL_PAYLOAD_TYPE) + if payload is None: + raise Rejected("approval_unverified", "the approval does not verify under the owner's public key") + try: + approval = json.loads(payload) + except ValueError: + raise Rejected("approval_unverified", "the approval payload is not JSON") from None + if not isinstance(approval, dict) or approval.get("protocol") != APPROVAL_PROTOCOL: + raise Rejected("approval_unverified", "the approval payload is not a factory approval") + expected = {"operation": operation, "spec_id": spec["spec_id"], "version": spec["version"], + "spec_digest": spec_digest_value or spec_digest(spec), "verdict_ids": sorted(verdict_ids or [])} + for key, value in expected.items(): + if approval.get(key) != value: + raise Rejected("approval_mismatch", f"the approval's {key} is {approval.get(key)!r}; this {operation} has {value!r}") + approver = approval.get("approver") + if not isinstance(approver, dict) or approver.get("kind") != "human" or not _PRINCIPAL_ID.match(str(approver.get("id"))): + raise Rejected("approval_actor", "the approval names no human approver") + return Approved({**approval, "keyid": public.hex()}) + + +def resolve_verdicts(events: list[dict], spec: dict, verdict_ids: list[str], spec_digest_value: str | None = None) -> list[dict]: + """Each verdict id resolved on the ledger: a ``spec_changed`` ``review`` event that accepted a variant, and + the ``validate`` event that wrote that variant as the candidate whose digest is this spec's. Returns one + record per verdict (``verdict_id``, ``variant_id``, ``reviewer``, ``proposers``); refuses an unknown, + rejecting or mismatched verdict, and refuses when no verdict is given.""" + if not verdict_ids: + raise Rejected("spec_verdict", "promotion records the review verdicts it rests on; none given") + current = spec_digest_value or spec_digest(spec) + changes = [e["body"] for e in events if e["kind"] == "spec_changed" and e["body"].get("spec_id") == spec["spec_id"]] + resolved = [] + for verdict_id in verdict_ids: + review = next((c for c in changes if c.get("operation") == "review" and c.get("verdict_id") == verdict_id), None) + if review is None: + raise Rejected("spec_verdict", f"verdict {verdict_id!r} is not a review on the ledger for spec {spec['spec_id']}") + if review.get("decision") != "accept": + raise Rejected("spec_verdict", f"verdict {verdict_id!r} did not accept (decision {review.get('decision')!r})") + variant_id = review.get("variant_id") + validated = next((c for c in changes if c.get("operation") == "validate" and c.get("accepted_variant") == variant_id + and c.get("verdict_id") == verdict_id), None) + if validated is None or validated.get("spec_digest") != current: + raise Rejected("spec_verdict", f"verdict {verdict_id!r} accepted variant {variant_id}, which is not this spec " + f"(digest {current[:12]}); the file was edited after review or never written by the loop") + proposers = sorted({c["actor"].get("id") for c in changes if c.get("operation") == "mutate" + and c.get("variant_id") == variant_id and isinstance(c.get("actor"), dict)}) + resolved.append({"verdict_id": verdict_id, "variant_id": variant_id, "reviewer": review.get("actor"), + "proposers": proposers}) + return resolved + + +def gate(spec: dict, operation: str, actor: dict, events: list[dict], envelope: dict, owner_public: bytes, *, + verdict_ids: list[str] | None = None, spec_digest_value: str | None = None) -> tuple[Approved, list[dict]]: + """The goal gate in one call: the actor is human and is the approver, the approval verifies and covers this + spec and operation, and (on promote) every verdict resolves to an accepting review of this variant whose + proposers and reviewer are not the approver. Returns the approval and the resolved verdicts.""" + if actor.get("kind") != "human": + raise Rejected("spec_actor", f"{operation} is an owner act: the actor's kind is human, not {actor.get('kind')!r}") + resolved = resolve_verdicts(events, spec, list(verdict_ids or []), spec_digest_value) if operation == "promote" else [] + approval = verify_approval(envelope, owner_public, spec, operation, verdict_ids=verdict_ids, spec_digest_value=spec_digest_value) + if approval["approver"]["id"] != actor.get("id"): + raise Rejected("approval_actor", f"the approval was signed for {approval['approver']['id']!r}, not the actor {actor.get('id')!r}") + for record in resolved: + parties = set(record["proposers"]) | {(record.get("reviewer") or {}).get("id")} + if actor["id"] in parties: + raise Rejected("approval_not_independent", f"{actor['id']} proposed or reviewed variant {record['variant_id']} and cannot approve it") + return approval, resolved def new_spec(spec_id: str, capability: str, requirements: list[dict], footprint_hint: list[str], *, @@ -72,6 +193,21 @@ def transition(spec: dict, operation: str, actor: dict, **detail) -> dict: allowed, target = TRANSITIONS[operation] if spec["state"] not in allowed: raise Rejected("spec_state", f"{operation} is not allowed from state {spec['state']!r} (needs one of {sorted(allowed)})") + if operation in GATED: + # The goal gate: a human actor and the approval ``verify_approval`` (or ``gate``) returned for this very + # operation on this very spec. A model actor, a missing approval, or a dictionary that is not an + # ``Approved`` is refused here, whatever the caller said on argv. + if actor.get("kind") != "human": + raise Rejected("spec_actor", f"{operation} is an owner act: the actor's kind is human, not {actor.get('kind')!r}") + approval = detail.get("approval") + if not isinstance(approval, Approved): + raise Rejected("spec_approval", f"{operation} needs the owner's verified approval (see `factory approve`); none given") + if approval["operation"] != operation or approval["spec_id"] != spec["spec_id"] or approval["version"] != spec["version"]: + raise Rejected("approval_mismatch", f"the approval covers {approval['operation']} of {approval['spec_id']} v{approval['version']}") + if approval["approver"]["id"] != actor.get("id"): + raise Rejected("approval_actor", f"the approval was signed for {approval['approver']['id']!r}, not {actor.get('id')!r}") + if operation == "promote" and sorted(detail.get("verdict_ids") or []) != approval["verdict_ids"]: + raise Rejected("spec_verdict", "promotion records the review verdicts the approval covers; they differ or none were given") if operation == "revise": delta = detail.get("delta") or {} _apply_delta(spec, delta) @@ -86,14 +222,14 @@ def transition(spec: dict, operation: str, actor: dict, **detail) -> dict: findings = validate(spec, detail.get("space")) if findings: raise Rejected("spec_invalid", "; ".join(findings)) - elif operation == "promote": - if not detail.get("verdict_ids"): - raise Rejected("spec_verdict", "promotion records the review verdicts it rests on; none given") elif operation == "retire": spec["supersedes"] = detail.get("superseded_by") record = {"operation": operation, "actor": actor, "from": spec["state"], "to": target, "version": spec["version"], - "input_digest": digest({k: v for k, v in detail.items() if k != "space"}), + "input_digest": digest({k: v for k, v in detail.items() if k not in ("space", "approval")}), "reason": detail.get("reason")} + if operation in GATED: + record["approval"] = {"keyid": detail["approval"]["keyid"], "approver": detail["approval"]["approver"], + "spec_digest": detail["approval"]["spec_digest"], "verdict_ids": detail["approval"]["verdict_ids"]} spec["state"] = target spec["history"].append(record) return record @@ -260,14 +396,26 @@ def review_request(parent: dict, variants: list[dict], objective: str | None) -> "variants": [{k: v for k, v in variant.items() if k != "history"} for variant in variants]} +def party(kind: str, name: str, answer: dict | None) -> dict: + """A proposer or reviewer as the ledger records it: the caller's name, and the model and provider family + the command declared in its answer (``model``, or ``signal.harness.model``). The family is what + independence is judged on; a command that declares no model has none and cannot be judged independent.""" + recorded = {"kind": kind, "id": name, "model": model_of(answer) if isinstance(answer, dict) else None} + recorded["family"] = family(recorded) + return recorded + + def judge(variants: list[dict], verdicts: list[dict], reviewer: dict) -> dict: - """Apply a reviewer's verdicts. The reviewer may not have proposed any of the variants (independence, as - the critic rule has it), a variant with findings cannot be accepted, and at most one variant is accepted. - Returns ``{"accepted": variant_id or None, "verdicts": [...]}`` with each verdict stamped by the reviewer.""" + """Apply a reviewer's verdicts. The reviewer is independent of every proposer by provider family + (``independence``: both families recorded and different; an unknown family refuses), a variant with + findings cannot be accepted, and at most one variant is accepted. Returns ``{"accepted": variant_id or + None, "verdicts": [...]}`` with each verdict stamped by the reviewer.""" by_id = {v["variant_id"]: v for v in variants} for variant in variants: - if variant.get("proposer", {}).get("id") == reviewer.get("id") and variant.get("proposer", {}).get("kind") == reviewer.get("kind"): - raise Rejected("reviewer_not_independent", f"{reviewer.get('id')} proposed variant {variant['variant_id']} and cannot review it") + independent, reason = independence(variant.get("proposer"), reviewer) + if not independent: + raise Rejected("reviewer_not_independent", f"{reviewer.get('id')} cannot review variant {variant['variant_id']} " + f"by {variant.get('proposer', {}).get('id')}: {reason}") accepted = None stamped = [] for verdict in verdicts: diff --git a/syberlabs/static/factory.html b/syberlabs/static/factory.html index ce66516..e967f47 100644 --- a/syberlabs/static/factory.html +++ b/syberlabs/static/factory.html @@ -129,13 +129,29 @@

Effects, markers and io so far

for (const { e, line } of edgeEls) { const on = litEdges.has(e.from + '->' + e.to); line.classList.toggle('lit', on); if (on) line.setAttribute('marker-end', 'url(#a-lit)'); else line.setAttribute('marker-end', e.kind === 'divergent' ? 'url(#a-bad)' : 'url(#a-line)'); } document.getElementById('seqlabel').textContent = `seq ${seq} / ${maxSeq}`; const top = active[active.length - 1]; - document.getElementById('stepinfo').innerHTML = top ? `${top.file}:${top.line} in ${top.component || '(unmapped)'}` : (seq === 0 ? 'run start' : (seq >= maxSeq ? 'run end' : 'between spans')); - const stack = document.getElementById('stack'); stack.innerHTML = ''; - for (const s of active) { const li = document.createElement('li'); li.className = 'active'; li.innerHTML = `${s.component || '(unmapped)'} ${s.fn} ${s.start}..${s.end === null ? '' : s.end}`; stack.appendChild(li); } - const list = document.getElementById('effects'); list.innerHTML = ''; + // Recorded strings (file names, function names, component ids, io argv) come from the recorded program: + // every one goes in through textContent, never through markup. + const node = (tag, text, attrs) => { const n = document.createElement(tag); n.textContent = text; for (const k in (attrs || {})) n.setAttribute(k, attrs[k]); return n; }; + const fill = (parent, ...children) => { parent.replaceChildren(); for (const c of children) parent.appendChild(typeof c === 'string' ? document.createTextNode(c) : c); }; + const info = document.getElementById('stepinfo'); + if (top) { fill(info, node('code', `${top.file}:${top.line}`), ' in ', node('b', top.component || '(unmapped)')); } + else { fill(info, seq === 0 ? 'run start' : (seq >= maxSeq ? 'run end' : 'between spans')); } + const stack = document.getElementById('stack'); stack.replaceChildren(); + for (const s of active) { + const li = node('li', '', { class: 'active' }); + fill(li, `${s.component || '(unmapped)'} `, node('code', String(s.fn)), ' ', node('span', `${s.start}..${s.end === null ? '' : s.end}`, { style: 'color:var(--quiet)' })); + stack.appendChild(li); + } + const list = document.getElementById('effects'); list.replaceChildren(); const shown = effects.filter(e => e.seq <= seq); const tail = shown.slice(-40); - if (shown.length > tail.length) { const li = document.createElement('li'); li.style.color = 'var(--quiet)'; li.textContent = `${shown.length - tail.length} earlier`; list.appendChild(li); } - for (const e of tail) { const li = document.createElement('li'); const what = e.t === 'io' && e.payload && e.payload.argv ? e.payload.argv.filter(a => !a.startsWith('-') && !a.includes('/') && !/^[0-9a-f]{7,}/.test(a)).slice(0, 3).join(' ') : (e.digest || '').slice(0, 10); li.innerHTML = `${e.seq} ${e.t} ${e.name} ${what}${e.replayed ? ' (replayed)' : ''}`; list.appendChild(li); } + if (shown.length > tail.length) { list.appendChild(node('li', `${shown.length - tail.length} earlier`, { style: 'color:var(--quiet)' })); } + for (const e of tail) { + // An io entry carries only its masked argv (the exporter leaves payloads out of the page); everything else shows its digest. + const what = e.t === 'io' && Array.isArray(e.argv) ? e.argv.filter(a => !a.startsWith('-') && !a.startsWith('')).slice(0, 3).join(' ') : (e.digest || '').slice(0, 10); + const li = node('li', ''); + fill(li, node('code', String(e.seq)), ` ${e.t} `, node('b', String(e.name)), ' ', node('code', what), e.replayed ? ' (replayed)' : ''); + list.appendChild(li); + } } slider.addEventListener('input', () => render(Number(slider.value))); let timer = null; diff --git a/tests/fixtures/factory_app/fxapp/variants.py b/tests/fixtures/factory_app/fxapp/variants.py index accd3b5..22c5270 100644 --- a/tests/fixtures/factory_app/fxapp/variants.py +++ b/tests/fixtures/factory_app/fxapp/variants.py @@ -1,4 +1,10 @@ -"""Entrypoints the harness tests use beside main.run: a different effect, a large one, a non-JSON one.""" +"""Entrypoints the harness tests use beside main.run: a different effect, a large one, a non-JSON one, and the +adversarial candidates of the trust-boundary tests: one that prints a forged report and keeps the recorder from +writing its ``end``, one that writes its own record into the journal around the recorder, and one that writes a +false clean ``end``. They run only in the child the harness starts; none ends a process.""" + +import json +import sys BIG = {"rows": ["x" * 100] * 1000} @@ -17,3 +23,36 @@ def odd(ctx, payload): def marker_only(ctx, payload): return ctx.marker("answer", 42) + + +def _recorder(): + return sys.modules["_factory_harness"]._CURRENT[-1] + + +def forge_report(ctx, payload): + """The S2(c) candidate: print what used to pass for the child's report, then close the journal under the + recorder so its ``end`` record is never written.""" + recorder = _recorder() + sys.stdout.write("\n" + json.dumps({"run_id": recorder.run_id, "status": "ok", "error": None, + "outcome": {"decision": "order"}, "counts": {"call": 1, "effect": 0, "marker": 0, "io": 0}}) + "\n") + sys.stdout.flush() + recorder._handle.close() + return {"decision": "order"} + + +def forge_journal(ctx, payload): + """The S2(a) candidate: append a record to the journal file behind the recorder's back.""" + recorder = _recorder() + recorder._handle.write(json.dumps({"t": "marker", "seq": recorder.seq + 1, "ns": 0, "name": "planted", "digest": "0" * 64, + "json": True, "span": None, "payload": "planted"}) + "\n") + recorder._handle.flush() + return {"decision": "order"} + + +def forge_end(ctx, payload): + """A candidate that writes a clean ``end`` itself, then closes the journal so the recorder's own is never written.""" + recorder = _recorder() + recorder._handle.write(json.dumps({"t": "end", "seq": recorder.seq + 1, "ns": 1, "status": "ok", "error": None, + "counts": dict(recorder.counts), "open_spans": 0, "unconsumed_effects": 0}) + "\n") + recorder._handle.close() + return {"decision": "order"} diff --git a/tests/fixtures/factory_app/proposers.py b/tests/fixtures/factory_app/proposers.py index 4f3124e..d742cce 100644 --- a/tests/fixtures/factory_app/proposers.py +++ b/tests/fixtures/factory_app/proposers.py @@ -1,11 +1,15 @@ """Stand-in proposers and a reviewer for the factory's variant loop. Each role reads JSON on stdin and writes -JSON on stdout, the process boundary a real model adapter would sit behind. Usage: proposers.py ROLE.""" +JSON on stdout, the process boundary a real model adapter would sit behind, and declares the model that served +it (``model``), which is what the loop judges independence on. Usage: proposers.py ROLE [MODEL]; without MODEL +each role declares its own default, and ``MODEL`` may be ``none`` to declare nothing.""" import json import sys +DEFAULT_MODELS = {"tighten": "claude-sonnet-4-5", "overreach": "grok-4", "review": "gpt-5", "review-all": "gpt-5"} -def main(role: str) -> int: + +def main(role: str, model: str | None = None) -> int: request = json.load(sys.stdin) if role == "tighten": # A sound proposal: one requirement made testable, nothing else touched. @@ -33,9 +37,12 @@ def main(role: str) -> int: out = {"verdicts": [{"variant_id": v["variant_id"], "decision": "accept"} for v in request["variants"]]} else: return 2 + declared = DEFAULT_MODELS.get(role) if model is None else model + if declared and declared != "none": + out["model"] = declared json.dump(out, sys.stdout) return 0 if __name__ == "__main__": - sys.exit(main(sys.argv[1] if len(sys.argv) > 1 else "")) + sys.exit(main(sys.argv[1] if len(sys.argv) > 1 else "", sys.argv[2] if len(sys.argv) > 2 else None)) diff --git a/tests/test_factory.py b/tests/test_factory.py index 8110f3d..4c9862a 100644 --- a/tests/test_factory.py +++ b/tests/test_factory.py @@ -4,6 +4,7 @@ import json import os import shutil +import sys import tempfile import unittest from contextlib import redirect_stdout, redirect_stderr @@ -11,7 +12,7 @@ from syberlabs.ed25519 import generate from syberlabs.errors import Rejected -from syberlabs.factory import attest, features, harness, ledger, space +from syberlabs.factory import attest, features, harness, independence, ledger, space from syberlabs.factory import cli as factory_cli from syberlabs.factory import spec as specmod @@ -19,6 +20,15 @@ FIXTURE = ROOT / "tests" / "fixtures" / "factory_app" DECLARED = json.loads((FIXTURE / "architecture.json").read_text(encoding="utf-8")) ACTOR = {"kind": "human", "id": "tester"} +OWNER_SEED, OWNER_PUBLIC = generate() + + +def approved(document, operation, verdict_ids=(), approver=ACTOR, seed=OWNER_SEED, public=OWNER_PUBLIC): + """An owner approval of ``operation`` on ``document`` as it is now, signed and verified: what ``transition`` + takes for a gated operation.""" + payload = specmod.approval_payload(document, operation, approver, verdict_ids=list(verdict_ids)) + envelope = specmod.sign_approval(payload, seed) + return specmod.verify_approval(envelope, public, document, operation, verdict_ids=list(verdict_ids)) def indexed(root=FIXTURE, revision="fixture"): @@ -226,6 +236,83 @@ def test_a_subprocess_is_observed_as_io_and_counts_in_the_diff(self): home.record_run(run_b) self.assertEqual(home.project()["effects"], 4) + def test_a_forging_candidate_is_refused_and_an_honest_one_passes(self): + """S2: the candidate's process cannot pass by printing a report, by writing journal lines around the + recorder, or by writing its own clean end; the honest program still passes. The child is never told the + ledger's path, and the journal it wrote is sealed under a key the parent holds.""" + home = ledger.Ledger(self.scratch / "ledger") + graph = indexed() + honest, outcome, report = self.record(home, graph=graph) + self.assertEqual((report["status"], outcome["decision"]), ("ok", "order")) + records = home.load_run(honest) + self.assertTrue(records[0]["sealed"]) + self.assertTrue(all("m" in r for r in records), "every record carries its seal") + forged = harness.new_run_id() + report = harness.record(FIXTURE, home.run_path(forged), "fxapp.variants:forge_report", file_components=file_components(graph), + fixture={"part": "p-104", "quantity": 2}, run_id=forged, revision="fixture", blobs=home.home / "blobs") + self.assertEqual(report["status"], "error", report) + self.assertTrue(any(s in report["error"] for s in ("no end record", "journal is empty", "torn")), report["error"]) + self.assertFalse(home.run_path(forged).exists(), "a journal the recorder never closed is not delivered") + self.assertIsNone(report["outcome"], "the printed line is stdout, not a report") + self.assertIn('"status": "ok"', report["stdout"]) + planted = harness.new_run_id() + report = harness.record(FIXTURE, home.run_path(planted), "fxapp.variants:forge_journal", file_components=file_components(graph), + fixture={}, run_id=planted, revision="fixture", blobs=home.home / "blobs") + self.assertEqual(report["status"], "error", report) + self.assertIn("journal_unsealed", report["error"]) + self.assertFalse(home.run_path(planted).exists(), "an unsealed journal is not delivered to the ledger") + false_end = harness.new_run_id() + report = harness.record(FIXTURE, home.run_path(false_end), "fxapp.variants:forge_end", file_components=file_components(graph), + fixture={}, run_id=false_end, revision="fixture", blobs=home.home / "blobs") + self.assertEqual(report["status"], "error", report) + self.assertIn("journal_unsealed", report["error"]) + self.assertFalse(home.run_path(false_end).exists()) + # The seal itself, with a known key: intact verifies; an edited line, an unsealed line and a torn tail do not. + sealed = self.scratch / "sealed.jsonl" + with harness.Recorder(FIXTURE, sealed, key="ab" * 32) as recorder: + recorder.io("x", {"a": 1}) + recorder.io("y", {"b": 2}) + self.assertIsNone(harness.verify_journal(sealed, "ab" * 32)) + self.assertIn("line 1", harness.verify_journal(sealed, "cd" * 32)) + lines = sealed.read_text(encoding="utf-8").splitlines() + edited = lines[:1] + [lines[1].replace('"name":"x"', '"name":"z"', 1)] + lines[2:] + sealed.write_text("\n".join(edited) + "\n", encoding="utf-8") + self.assertIn("line 2", harness.verify_journal(sealed, "ab" * 32)) + sealed.write_text("\n".join(lines) + '\n{"t":"marker","seq":9}\n', encoding="utf-8") + self.assertIn("carries no seal", harness.verify_journal(sealed, "ab" * 32)) + sealed.write_text("\n".join(lines) + "\n" + lines[-1][:20], encoding="utf-8") + self.assertIn("torn", harness.verify_journal(sealed, "ab" * 32)) + + def test_scrub(self): + self.assertEqual(harness.scrub("ghp_abcdefghijklmnopqrstuvwxyz0123456789"), "") + self.assertEqual(harness.scrub("GITHUB_TOKEN=whatever"), "GITHUB_TOKEN=") + self.assertEqual(harness.scrub("http.extraheader=AUTHORIZATION: basic abc"), "http.extraheader=") + self.assertEqual(harness.scrub("Authorization: Bearer abcdefghijklmnopqrstuvwxyz0123"), "Authorization: Bearer ") + self.assertEqual(harness.scrub("core.hooksPath=.githooks"), "core.hooksPath=.githooks") + self.assertEqual(harness.scrub("--format=%(refname)"), "--format=%(refname)") + self.assertEqual(harness.scrub_argv(["git", "-c", "http.extraheader=AUTHORIZATION: basic abc", "fetch"]), + ["git", "-c", "http.extraheader=", "fetch"]) + self.assertEqual(harness.scrub_argv(["curl", "-H", "Authorization: Bearer x", "--token=abc", "--password", "p", "https://h/"]), + ["curl", "-H", "", "--token=", "--password", "", "https://h/"]) + self.assertEqual(harness.scrub_text("a\nkey sk-ant-abcdefghijklmnop\nb", 100), "a\nkey \nb") + self.assertEqual(len(harness.scrub_text("x" * 5000, 100)), 100) + + def test_a_subprocess_argv_is_scrubbed_before_it_is_journaled(self): + home = ledger.Ledger(self.scratch / "ledger") + script = self.scratch / "leaky.py" + script.write_text("import subprocess, sys\n" + "subprocess.run([sys.executable, '-c', 'pass', '--token', 'ghp_abcdefghijklmnopqrstuvwxyz0123456789'," + " 'API_KEY=sk-ant-abcdefghijklmnopqrstuvwxyz'], check=True)\n", encoding="utf-8") + run_id = harness.new_run_id() + report = harness.record(self.scratch, home.run_path(run_id), str(script), run_id=run_id) + self.assertEqual(report["status"], "ok", report) + text = home.run_path(run_id).read_text(encoding="utf-8") + self.assertNotIn("ghp_", text) + self.assertNotIn("sk-ant-", text) + home.record_run(run_id) + [io_record] = [r for r in home.load_run(run_id) if r["t"] == "io"] + self.assertEqual(io_record["payload"]["argv"][3:], ["--token", "", "API_KEY="]) + def test_large_payload_goes_to_a_blob_and_replays(self): home = ledger.Ledger(self.scratch / "ledger") big = {"rows": ["x" * 100] * 1000} @@ -296,6 +383,60 @@ def test_chain_verifies_and_detects_tampering(self): with self.assertRaises(Rejected): ledger.Ledger(self.scratch / "other").append("not_a_kind", {}) + def test_artifacts_are_checked_against_their_recorded_digests(self): + """S1: an edited golden journal fails verify and cannot be loaded, so it cannot become a baseline; an + edited Space graph and an unlogged journal are refused the same way; a torn ledger tail is repaired.""" + home = ledger.Ledger(self.scratch / "ledger") + graph = indexed() + home.record_space(graph) + run_id, _, _ = self.record(home, graph=graph) + home.set_baseline(run_id) + self.assertTrue(home.verify()) + path = home.run_path(run_id) + original = path.read_bytes() + self.assertIn(b'"status":201', original) + path.write_bytes(original.replace(b'"status":201', b'"status":500', 1)) # one byte of the golden's effect result + self.assertFalse(home.verify()) + self.assertTrue(any(f"runs/{run_id}" in p for p in home.problems()), home.problems()) + with self.assertRaises(Rejected) as refused: + home.load_run(run_id) + self.assertEqual(refused.exception.code, "artifact_tampered") + with self.assertRaises(Rejected): + home.set_baseline(run_id) + self.assertEqual(home.project()["runs"], 0, "an edited journal projects nothing") + path.write_bytes(original) + self.assertTrue(home.verify()) + space_path = home.space_path(space.graph_digest(graph)) + edited = json.loads(space_path.read_text(encoding="utf-8")) + edited["revision"] = "elsewhere" + space_path.write_text(json.dumps(edited), encoding="utf-8") + with self.assertRaises(Rejected) as refused: + home.latest_space() + self.assertEqual(refused.exception.code, "artifact_tampered") + self.assertFalse(home.verify()) + space_path.write_text(space.dumps(graph), encoding="utf-8") + stray = harness.new_run_id() + shutil.copyfile(path, home.run_path(stray)) + with self.assertRaises(Rejected) as refused: + home.load_run(stray) + self.assertEqual(refused.exception.code, "run_unrecorded") + with home.log.open("a", encoding="utf-8") as handle: + handle.write('{"seq": 99, "torn') + self.assertEqual(len(home.events()), 3, "the torn tail is truncated on the next locked read, as the journal does") + home.append("note", {"text": "after the tear"}) + self.assertTrue(home.verify()) + self.assertEqual(home.describe()["problems"], 0) + + def test_projection_follows_the_log(self): + home = ledger.Ledger(self.scratch / "ledger") + graph = indexed() + home.record_space(graph) + run_a, _, _ = self.record(home, graph=graph) + self.assertEqual(len(home.worldline(run_a)), 7) + run_b, _, _ = self.record(home, graph=graph, revision="second") + self.assertEqual(len(home.worldline(run_b)), 7, "a run appended after the projection was built is queryable") + self.assertEqual({c["revision"] for c in home.cells_for("rules")}, {"fixture", "second"}) + def test_projection_and_queries(self): home = ledger.Ledger(self.scratch / "ledger") graph = indexed() @@ -333,23 +474,112 @@ def test_lifecycle(self): graph = indexed() self.assertEqual(document["state"], "draft") with self.assertRaises(Rejected): - specmod.transition(document, "promote", ACTOR, verdict_ids=["v1"]) + specmod.transition(document, "promote", ACTOR, verdict_ids=["v1"], approval=approved(document, "promote", ["v1"])) specmod.transition(document, "revise", ACTOR, delta={"added": [{"req_id": "R2", "text": "Reject zero quantity."}]}) self.assertEqual(document["version"], 2) self.assertEqual([r["req_id"] for r in document["requirements"]], ["R1", "R2"]) specmod.transition(document, "validate", ACTOR, space=graph) self.assertEqual(document["state"], "candidate") + # The goal gate: a model actor is refused whatever it carries; a human without the owner's approval is + # refused; a dictionary shaped like an approval is refused; an approval of another operation, another + # version or other verdicts is refused; the approver must be the actor. + approval = approved(document, "promote", ["v1"]) + with self.assertRaises(Rejected) as refused: + specmod.transition(document, "promote", {"kind": "model", "id": "reviewer"}, verdict_ids=["v1"], approval=approval) + self.assertEqual(refused.exception.code, "spec_actor") + with self.assertRaises(Rejected) as refused: + specmod.transition(document, "promote", ACTOR, verdict_ids=["v1"]) + self.assertEqual(refused.exception.code, "spec_approval") + with self.assertRaises(Rejected) as refused: + specmod.transition(document, "promote", ACTOR, verdict_ids=["v1"], approval=dict(approval)) + self.assertEqual(refused.exception.code, "spec_approval") + with self.assertRaises(Rejected) as refused: + specmod.transition(document, "promote", ACTOR, verdict_ids=["v2"], approval=approval) + self.assertEqual(refused.exception.code, "spec_verdict") + with self.assertRaises(Rejected) as refused: + specmod.transition(document, "promote", ACTOR, verdict_ids=["v1"], approval=approved(document, "canonize")) + self.assertEqual(refused.exception.code, "approval_mismatch") + with self.assertRaises(Rejected) as refused: + specmod.transition(document, "promote", {"kind": "human", "id": "someone-else"}, verdict_ids=["v1"], approval=approval) + self.assertEqual(refused.exception.code, "approval_actor") + with self.assertRaises(Rejected): + approved(document, "promote", ["v1"], approver={"kind": "model", "id": "reviewer"}) + with self.assertRaises(Rejected) as refused: + approved(document, "promote", ["v1"], public=generate()[1]) + self.assertEqual(refused.exception.code, "approval_unverified") + self.assertEqual(document["state"], "candidate", "nothing above moved the spec") + record = specmod.transition(document, "promote", ACTOR, verdict_ids=["v1"], approval=approval) + self.assertEqual(record["approval"]["approver"], ACTOR) + self.assertEqual(record["approval"]["keyid"], OWNER_PUBLIC.hex()) with self.assertRaises(Rejected): - specmod.transition(document, "promote", ACTOR) - specmod.transition(document, "promote", {"kind": "model", "id": "reviewer"}, verdict_ids=["v1"]) - specmod.transition(document, "canonize", ACTOR) - specmod.transition(document, "retire", ACTOR, superseded_by="order-path:3") + specmod.transition(document, "canonize", ACTOR) + specmod.transition(document, "canonize", ACTOR, approval=approved(document, "canonize")) + specmod.transition(document, "retire", ACTOR, superseded_by="order-path:3", approval=approved(document, "retire")) self.assertEqual([h["operation"] for h in document["history"]], ["revise", "validate", "promote", "canonize", "retire"]) self.assertEqual(document["supersedes"], "order-path:3") with self.assertRaises(Rejected): specmod.transition(document, "bogus", ACTOR) + def test_principal(self): + self.assertEqual(specmod.principal("human:mateo"), {"kind": "human", "id": "mateo"}) + self.assertEqual(specmod.principal("model:claude-sonnet-4-5"), {"kind": "model", "id": "claude-sonnet-4-5"}) + for bad in ("operator", "owner:mateo", "human:", "human:has space", "model:" + "x" * 65, ""): + with self.assertRaises(Rejected, msg=bad): + specmod.principal(bad) + + def test_verdicts_resolve_against_the_ledger(self): + """A promotion's verdict ids are not strings: each is a review on the ledger that accepted the very variant + this spec is, and the approver may not have proposed or reviewed it.""" + document = self.spec() + current = specmod.spec_digest(document) + reviewer = {"kind": "model", "id": "gpt", "model": "gpt-5", "family": "openai"} + events = [ + {"kind": "spec_changed", "body": {"spec_id": "order-path", "operation": "mutate", "variant_id": "var1", + "actor": {"kind": "model", "id": "claude"}}}, + {"kind": "spec_changed", "body": {"spec_id": "order-path", "operation": "review", "verdict_id": "ok1", + "variant_id": "var1", "decision": "accept", "actor": reviewer}}, + {"kind": "spec_changed", "body": {"spec_id": "order-path", "operation": "review", "verdict_id": "no1", + "variant_id": "var2", "decision": "reject", "actor": reviewer}}, + {"kind": "spec_changed", "body": {"spec_id": "order-path", "operation": "validate", "accepted_variant": "var1", + "verdict_id": "ok1", "spec_digest": current}}, + ] + [resolved] = specmod.resolve_verdicts(events, document, ["ok1"]) + self.assertEqual((resolved["variant_id"], resolved["proposers"]), ("var1", ["claude"])) + for ids, why in (([], "none given"), (["ghost"], "not a review"), (["no1"], "did not accept")): + with self.assertRaises(Rejected, msg=why) as refused: + specmod.resolve_verdicts(events, document, ids) + self.assertEqual(refused.exception.code, "spec_verdict") + edited = dict(document, capability="something else") + with self.assertRaises(Rejected): + specmod.resolve_verdicts(events, edited, ["ok1"]) + envelope = specmod.sign_approval(specmod.approval_payload(document, "promote", ACTOR, verdict_ids=["ok1"]), OWNER_SEED) + approval, found = specmod.gate(document, "promote", ACTOR, events, envelope, OWNER_PUBLIC, verdict_ids=["ok1"]) + self.assertIsInstance(approval, specmod.Approved) + self.assertEqual(found[0]["verdict_id"], "ok1") + proposer_as_owner = {"kind": "human", "id": "claude"} + own = specmod.sign_approval(specmod.approval_payload(document, "promote", proposer_as_owner, verdict_ids=["ok1"]), OWNER_SEED) + with self.assertRaises(Rejected) as refused: + specmod.gate(document, "promote", proposer_as_owner, events, own, OWNER_PUBLIC, verdict_ids=["ok1"]) + self.assertEqual(refused.exception.code, "approval_not_independent") + with self.assertRaises(Rejected) as refused: + specmod.gate(document, "promote", {"kind": "model", "id": "gpt"}, events, envelope, OWNER_PUBLIC, verdict_ids=["ok1"]) + self.assertEqual(refused.exception.code, "spec_actor") + + def test_independence_is_by_provider_family(self): + claude = {"kind": "model", "id": "a", "model": "claude-sonnet-4-5"} + gpt = {"kind": "model", "id": "b", "model": "gpt-5"} + self.assertEqual(independence.family(claude), "anthropic") + self.assertEqual(independence.family({"signal": {"harness": {"model": "grok-4"}}}), "xai") + self.assertEqual(independence.family({"provider": {"model": "openrouter/google/gemini-2.5-pro"}}), "google") + self.assertEqual(independence.family({"family": "OpenAI"}), "openai") + self.assertIsNone(independence.family({"kind": "model", "id": "mystery"})) + self.assertIsNone(independence.family({"model": "frobnicator-9"})) + self.assertTrue(independence.independence(claude, gpt)[0]) + self.assertFalse(independence.independence(claude, {"id": "other-name", "model": "claude-opus-4-1"})[0], "same family, other name") + self.assertFalse(independence.independence(claude, {"id": "unknown"})[0], "an unknown family refuses") + self.assertFalse(independence.independence(None, gpt)[0]) + def test_validation_findings(self): document = specmod.new_spec("x", "y", [{"req_id": "R1", "text": " "}], ["nowhere"]) findings = specmod.validate(document, indexed()) @@ -366,7 +596,7 @@ def test_footprint_and_ticket(self): with self.assertRaises(Rejected): specmod.ticket_from_spec(document, "R1") specmod.transition(document, "validate", ACTOR, space=graph) - specmod.transition(document, "promote", ACTOR, verdict_ids=["v1"]) + specmod.transition(document, "promote", ACTOR, verdict_ids=["v1"], approval=approved(document, "promote", ["v1"])) with self.assertRaises(Rejected): specmod.ticket_from_spec(document, "R1") footprint = specmod.resolve_footprint(document, graph) @@ -423,12 +653,22 @@ def test_trace_diff_statement_policy_and_signature(self): self.assertIsNone(attest.verify(envelope, generate()[1])) self.assertEqual(attest.unwrap(envelope), promoted) self.assertEqual(attest.unwrap(promoted), promoted) - event = home.record_attestation(envelope) + event = home.record_attestation(envelope, public) self.assertEqual(event["body"]["signed"], True) + self.assertEqual(event["body"]["keyid"], public.hex()) self.assertEqual(event["body"]["promote"], True) self.assertEqual(event["body"]["subject"], ["git:fx@cand"]) self.assertTrue((home.home / "attestations" / f"{event['body']['attestation_digest']}.json").exists()) + unchecked = home.record_attestation(envelope) + self.assertEqual((unchecked["body"]["signed"], unchecked["body"]["envelope"]), (False, True), + "envelope shape alone is not a signature") + self.assertFalse(home.record_attestation(envelope, generate()[1])["body"]["signed"], "the wrong key is not a signature") self.assertTrue(home.verify()) + # A signed statement whose written policy says more than its evidence: verify recomputes and refuses. + forged = json.loads(json.dumps(refused)) + forged["predicate"]["policy"] = {"promote": True, "reasons": ["looks fine"]} + self.assertFalse(attest.recompute(forged["predicate"])["promote"]) + self.assertTrue(attest.recompute(promoted["predicate"])["promote"]) class CliTests(Scratch): @@ -475,16 +715,68 @@ def test_end_to_end(self): self.assertIn("worldline matches the recording", out) code, out, err = self.run_cli("spec", "validate", "spec.json", cwd=tree) self.assertEqual(code, 0, err) - code, out, err = self.run_cli("spec", "promote", "spec.json", "--verdict", "v1", "--actor", "model:reviewer", + # Promotion is an owner act over a reviewed variant: a model actor is refused, a human without the owner's + # approval is refused, a verdict that is not on the ledger is refused, and the reviewed, approved variant passes. + seed, public = generate() + os.environ["SYBERLABS_FACTORY_TEST_SEED"] = seed.hex() + self.addCleanup(os.environ.pop, "SYBERLABS_FACTORY_TEST_SEED", None) + (tree / "owner.pub").write_text(public.hex(), encoding="utf-8") + code, out, err = self.run_cli("spec", "promote", "spec.json", "--verdict", "v1", "--actor", "model:reviewer", cwd=tree) + self.assertEqual(code, 2) + self.assertIn("spec_actor", err) + code, out, err = self.run_cli("spec", "promote", "spec.json", "--verdict", "v1", "--actor", "human:tester", cwd=tree) + self.assertEqual(code, 2) + self.assertIn("spec_approval", err) + code, out, err = self.run_cli("approve", "spec.json", "--verdict", "v1", "--actor", "human:tester", + "--seed-env", "SYBERLABS_FACTORY_TEST_SEED", "--out", "approval.json", cwd=tree) + self.assertEqual(code, 0, err) + code, out, err = self.run_cli("spec", "promote", "spec.json", "--verdict", "v1", "--actor", "human:tester", + "--approval", "approval.json", "--owner-public", "owner.pub", cwd=tree) + self.assertEqual(code, 2) + self.assertIn("spec_verdict", err, "v1 is a string, not a review on the ledger") + self.assertEqual(json.loads(spec_path.read_text(encoding="utf-8"))["state"], "candidate") + run = lambda role: f"{sys.executable} {tree / 'proposers.py'} {role}" + code, out, err = self.run_cli("variants", "spec.json", "--proposer", f"claude={run('tighten')}", + "--reviewer", f"gpt={run('review')}", cwd=tree) + self.assertEqual(code, 0, err + out) + self.assertNotIn("--actor model:", out, "the loop no longer hints at a model promoting") + verdict_id = out.split("--verdict ")[1].split()[0] + candidate_spec = "order-path.v2.json" + code, out, err = self.run_cli("approve", candidate_spec, "--verdict", verdict_id, "--actor", "human:tester", + "--seed-env", "SYBERLABS_FACTORY_TEST_SEED", "--out", "approval.json", cwd=tree) + self.assertEqual(code, 0, err) + code, out, err = self.run_cli("spec", "promote", candidate_spec, "--verdict", verdict_id, "--actor", "human:claude", + "--approval", "approval.json", "--owner-public", "owner.pub", cwd=tree) + self.assertEqual(code, 2) + self.assertIn("approval_actor", err, "the approval names tester, not the actor") + (tree / "other.pub").write_text(generate()[1].hex(), encoding="utf-8") + code, out, err = self.run_cli("spec", "promote", candidate_spec, "--verdict", verdict_id, "--actor", "human:tester", + "--approval", "approval.json", "--owner-public", "other.pub", cwd=tree) + self.assertEqual(code, 2) + self.assertIn("approval_unverified", err, "an approval under another key is no approval") + code, out, err = self.run_cli("spec", "promote", candidate_spec, "--verdict", verdict_id, "--actor", "human:tester", + "--approval", "approval.json", "--owner-public", "owner.pub", "--tickets", "tickets", "--baseline", run_a, "--owner", "tester", cwd=tree) self.assertEqual(code, 0, err) self.assertIn("candidate -> promoted", out) self.assertIn("ticket ", out) + promoted = json.loads((tree / candidate_spec).read_text(encoding="utf-8")) + self.assertEqual(promoted["state"], "promoted") + self.assertEqual(promoted["history"][-1]["approval"]["approver"], {"kind": "human", "id": "tester"}) + home = ledger.Ledger(tree / ".syberlabs" / "factory") + approvals = [e for e in home.events() if e["kind"] == "approval_recorded"] + self.assertEqual(len(approvals), 1) + promotion = [e for e in home.events() if e["kind"] == "spec_changed" and e["body"].get("to") == "promoted"][-1] + self.assertEqual(promotion["body"]["approval"]["event_hash"], approvals[0]["hash"], "the promotion cites the approval event") + self.assertTrue(home.verify()) + code, out, err = self.run_cli("spec", "promote", candidate_spec, "--verdict", verdict_id, "--actor", "human:tester", + "--approval", "approval.json", "--owner-public", "owner.pub", cwd=tree) + self.assertEqual(code, 2, "a promoted spec is not promoted twice") [auto] = list((tree / "tickets").glob("*.json")) auto_ticket = json.loads(auto.read_text(encoding="utf-8")) self.assertEqual((auto_ticket["spec_ref"]["req_ids"], auto_ticket["repro"]["baseline_run"]), (["R1"], run_a)) self.assertEqual(auto_ticket["footprint"]["components"], ["effects", "ingest", "rules"]) - code, out, err = self.run_cli("ticket", "spec.json", "--req", "R1", "--baseline", run_a, "--owner", "tester", + code, out, err = self.run_cli("ticket", candidate_spec, "--req", "R1", "--baseline", run_a, "--owner", "tester", "--out", "ticket.json", cwd=tree) self.assertEqual(code, 0, err) ticket = json.loads((tree / "ticket.json").read_text(encoding="utf-8")) @@ -493,26 +785,36 @@ def test_end_to_end(self): "--revision", "cand", cwd=tree) self.assertEqual(code, 0, err) run_b = out.split("recorded run ")[1].split()[0] - seed, public = generate() - os.environ["SYBERLABS_FACTORY_TEST_SEED"] = seed.hex() - self.addCleanup(os.environ.pop, "SYBERLABS_FACTORY_TEST_SEED", None) code, out, err = self.run_cli("attest", "--baseline", run_a, "--candidate", run_b, "--ticket", "ticket.json", "--commit", "cand", "--seed-env", "SYBERLABS_FACTORY_TEST_SEED", "--out", "attestation.json", cwd=tree) self.assertEqual(code, 0, err) self.assertIn("promote True", out) + attested = [e for e in ledger.Ledger(tree / ".syberlabs" / "factory").events() if e["kind"] == "attested"][-1] + self.assertEqual((attested["body"]["signed"], attested["body"]["keyid"]), (True, public.hex())) (tree / "key.pub").write_text(public.hex(), encoding="utf-8") code, out, err = self.run_cli("verify", "attestation.json", "--public", "key.pub", cwd=tree) self.assertEqual(code, 0, err) self.assertIn("verified: git:tree@cand", out) + self.assertIn("recomputed from the evidence", out) (tree / "wrong.pub").write_text(generate()[1].hex(), encoding="utf-8") code, out, _ = self.run_cli("verify", "attestation.json", "--public", "wrong.pub", cwd=tree) self.assertEqual(code, 1) + # A statement the signer graded itself: signed with the right key, but its policy says more than its evidence. + self_graded = json.loads((tree / "attestation.json").read_text(encoding="utf-8")) + statement = attest.unwrap(self_graded) + statement["predicate"]["evidence"]["trace_diff"]["diff_empty"] = False + (tree / "graded.json").write_text(json.dumps(attest.sign(statement, seed)), encoding="utf-8") + code, out, _ = self.run_cli("verify", "graded.json", "--public", "key.pub", cwd=tree) + self.assertEqual(code, 1) + self.assertIn("policy mismatch", out) code, out, err = self.run_cli("export", run_a, "--chrome", "trace.json", "--view", "run.html", cwd=tree) self.assertEqual(code, 0, err) page = (tree / "run.html").read_text(encoding="utf-8") self.assertIn('"run_id": "' + run_a + '"', page) self.assertNotIn("/*__FACTORY_DATA__*/null", page) + self.assertNotIn('"payload"', page, "the viewer references effects by digest; payloads stay in the journal") + self.assertNotIn("innerHTML", page) self.assertEqual(json.loads((tree / "trace.json").read_text(encoding="utf-8"))["metadata"]["run_id"], run_a) code, out, _ = self.run_cli("status", cwd=tree) self.assertIn("verified True", out) @@ -620,6 +922,47 @@ def test_a_behavior_preserving_candidate_passes_and_a_changed_one_is_refused(sel self.assertFalse(last["body"]["diff_empty"]) self.assertTrue(home.verify()) + def test_an_edited_golden_refuses_the_check(self): + """S1 through the seam: the golden journal is edited after the baseline was set; the check refuses before + the candidate runs, and nothing is attested.""" + home, golden = self.golden() + path = home.run_path(golden) + original = path.read_bytes() + self.assertIn(b'"status":201', original) + path.write_bytes(original.replace(b'"status":201', b'"status":500', 1)) + self.assertFalse(home.verify()) + kit = self.kit() + thread = kit.start("Tidy", paths=["fxapp/"]) + rules = (self.project / "fxapp" / "rules.py").read_text(encoding="utf-8") + [candidate] = thread.propose(changes={"fxapp/rules.py": rules + "\n"}) + verdict = thread.check(candidate.id) + self.assertFalse(verdict.acceptable, verdict.summary()) + self.assertEqual(verdict.reason, "candidate_check_failed:factory") + self.assertIn("ledger_corrupt", verdict.checks[0].output_tail) + self.assertIn(f"runs/{golden}", verdict.checks[0].output_tail) + self.assertEqual([e for e in home.events() if e["kind"] == "attested"], [], "nothing was attested over an edited baseline") + + def test_a_candidate_that_forges_its_report_is_refused(self): + """S2 through the seam: the candidate rewrites the recorded entrypoint to print a clean report and exit. The + check reads the journal's end record itself and takes the report only over the nonce-bound channel.""" + home, _ = self.golden() + kit = self.kit() + thread = kit.start("Make the gate happy", paths=["fxapp/"]) + main = (self.project / "fxapp" / "main.py").read_text(encoding="utf-8") + forged = main.replace("from fxapp import rules\n", "from fxapp import rules\nfrom fxapp import variants\n") \ + .replace("def run(ctx, payload):\n", "def run(ctx, payload):\n return variants.forge_report(ctx, payload)\n") + self.assertNotEqual(main, forged) + [candidate] = thread.propose(changes={"fxapp/main.py": forged}) + verdict = thread.check(candidate.id) + self.assertFalse(verdict.acceptable, verdict.summary()) + self.assertEqual(verdict.reason, "candidate_check_failed:factory") + tail = verdict.checks[0].output_tail + self.assertIn("no journal:", tail, "the forged line on stdout is not a report, and a journal without an end is not delivered") + self.assertIn('"status": "ok"', tail, "what the candidate printed is in the log, as output, not as a verdict") + self.assertEqual([e for e in home.events() if e["kind"] == "attested"], [], "nothing was attested") + self.assertEqual([r for r in home.runs() if r["revision"] == candidate.commit], [], "the forged run is not on the ledger") + self.assertTrue(home.verify()) + def test_tests_argv_is_recorded_as_evidence_and_required(self): import sys as _sys home, _ = self.golden() @@ -643,6 +986,20 @@ def test_tests_argv_is_recorded_as_evidence_and_required(self): verdict = thread.check(candidate.id) self.assertFalse(verdict.acceptable) self.assertIn("tests did not run the full suite green: refuse", verdict.checks[0].output_tail) + # A suite that hangs is stopped at the contract's timeout, with its process tree, and is not a full suite. + hanging = json.dumps([_sys.executable, "-c", "import subprocess, sys, time; subprocess.Popen([sys.executable, '-c', 'import time; time.sleep(60)']); time.sleep(60)"]) + kit = self.kit(extra_argv=["--tests-argv", hanging, "--tests-timeout", "2"], version=3) + thread = kit.start("Hang", paths=["fxapp/"]) + [candidate] = thread.propose(changes={"fxapp/rules.py": rules + "\n\n\n"}) + import time as _time + started = _time.monotonic() + verdict = thread.check(candidate.id) + self.assertLess(_time.monotonic() - started, 40) + self.assertFalse(verdict.acceptable) + attested = [e for e in home.events() if e["kind"] == "attested"][-1] + document = json.loads((home.home / "attestations" / f"{attested['body']['attestation_digest']}.json").read_text(encoding="utf-8")) + tests = document["predicate"]["evidence"]["tests"] + self.assertEqual((tests["timed_out"], tests["full_suite"], tests["exit_code"]), (True, False, None)) def test_drift_bound_refuses_an_undeclared_dependency(self): self.golden() @@ -723,6 +1080,8 @@ def test_bootstrap_publishes_the_contract_and_a_thread_runs_the_check(self): self.assertEqual(argv[1:4], ["-P", "-m", "syberlabs.factory"], "the host's factory runs, not the candidate's") self.assertIn(str(self.ledger_home), argv) self.assertEqual(json.loads(argv[argv.index("--tests-argv") + 1])[1:], ["-c", "pass"]) + self.assertEqual(argv[argv.index("--tests-timeout") + 1], "60", "the contract's own tests timeout, not 1800") + self.assertEqual(document["evolution"]["evaluation"]["checks"]["factory"]["timeout_seconds"], 660) home = ledger.Ledger(self.ledger_home) self.assertIsNotNone(home.baseline()) # Swap the interpreter for the launcher so the check finds this checkout, then run a thread on v2. @@ -774,10 +1133,12 @@ def test_the_self_check_program_sees_a_rerun_policy_change(self): "def check(self, candidate: str, *, rerun: bool = True, run: bool = True,") self.assertNotEqual(text, changed) build.write_text(changed, encoding="utf-8") + home.record_run(golden) candidate = harness.new_run_id() report = harness.record(tree, home.run_path(candidate), str(tree / "examples" / "factory_self_check.py"), file_components=file_components(graph), run_id=candidate, revision="rerun", blobs=home.home / "blobs") self.assertEqual(report["status"], "ok", report.get("error")) + home.record_run(candidate) self.assertGreater(report["counts"]["io"], [r for r in home.load_run(golden) if r["t"] == "io"].__len__(), "rerunning by default starts more check processes") diff = attest.trace_diff(home.load_run(golden), home.load_run(candidate), None) @@ -801,6 +1162,7 @@ def test_build_thread_example_records_and_a_weakened_accept_is_caught(self): again = harness.new_run_id() harness.record(ROOT, home.run_path(again), str(ROOT / "examples" / "build_thread.py"), file_components=file_components(graph), run_id=again, revision="checkout", blobs=home.home / "blobs") + home.record_run(again) same = attest.trace_diff(home.load_run(golden), home.load_run(again), None) self.assertTrue(same["diff_empty"], same["divergence_detail"]) self.assertTrue(same["function_level_equal"], "the example is deterministic once io keys are masked") @@ -818,6 +1180,7 @@ def test_build_thread_example_records_and_a_weakened_accept_is_caught(self): file_components=file_components(graph), run_id=candidate, revision="weakened", blobs=home.home / "blobs") self.assertEqual(report["status"], "ok", report.get("error")) + home.record_run(candidate) changed = attest.trace_diff(home.load_run(golden), home.load_run(candidate), None) self.assertFalse(changed["diff_empty"]) detail = changed["divergence_detail"] @@ -861,16 +1224,18 @@ def cli(self, *argv): def test_primitives(self): parent = json.loads(self.spec_path.read_text(encoding="utf-8")) graph = self.home.latest_space() - good = specmod.make_variant(parent, {"modified": [{"req_id": "R1", "text": "tighter"}], "rationale": "r"}, - {"kind": "model", "id": "a"}, graph) - bad = specmod.make_variant(parent, {"footprint_hint": ["ghost"]}, {"kind": "model", "id": "b"}, graph) + a, b = specmod.party("model", "a", {"model": "claude-sonnet-4-5"}), specmod.party("model", "b", {"model": "grok-4"}) + self.assertEqual((a["family"], b["family"]), ("anthropic", "xai")) + good = specmod.make_variant(parent, {"modified": [{"req_id": "R1", "text": "tighter"}], "rationale": "r"}, a, graph) + bad = specmod.make_variant(parent, {"footprint_hint": ["ghost"]}, b, graph) self.assertEqual((good["state"], good["version"], good["findings"]), ("mutated", 2, [])) self.assertTrue(bad["findings"]) self.assertNotEqual(good["variant_id"], bad["variant_id"]) self.assertEqual(parent["version"], 1, "the parent is untouched") with self.assertRaises(Rejected): - specmod.make_variant(parent, {"rationale": "nothing"}, {"kind": "model", "id": "a"}, graph) - reviewer = {"kind": "model", "id": "r"} + specmod.make_variant(parent, {"rationale": "nothing"}, a, graph) + reviewer = specmod.party("model", "r", {"signal": {"harness": {"model": "gpt-5"}}}) + self.assertEqual(reviewer["family"], "openai") review = specmod.judge([good, bad], [{"variant_id": good["variant_id"], "decision": "accept"}, {"variant_id": bad["variant_id"], "decision": "reject"}], reviewer) self.assertEqual(review["accepted"], good["variant_id"]) @@ -879,8 +1244,12 @@ def test_primitives(self): {"variant_id": good["variant_id"], "decision": "reject"}], reviewer) with self.assertRaises(Rejected): specmod.judge([good, bad], [{"variant_id": good["variant_id"], "decision": "accept"}], reviewer) - with self.assertRaises(Rejected): - specmod.judge([good], [{"variant_id": good["variant_id"], "decision": "accept"}], {"kind": "model", "id": "a"}) + # Independence is the provider family, not the name: another name on the proposer's family is refused, and + # so is a reviewer whose family is not recorded. + for not_independent in (specmod.party("model", "other", {"model": "claude-opus-4-1"}), specmod.party("model", "r", None)): + with self.assertRaises(Rejected) as refused: + specmod.judge([good], [{"variant_id": good["variant_id"], "decision": "accept"}], not_independent) + self.assertEqual(refused.exception.code, "reviewer_not_independent") def test_loop_through_the_cli(self): run = lambda role: f"{self.py} {self.proposers} {role}" @@ -898,9 +1267,10 @@ def test_loop_through_the_cli(self): self.assertEqual(accepted["state"], "candidate") self.assertIn("exactly one order", accepted["requirements"][0]["text"]) self.assertEqual([h["operation"] for h in accepted["history"]], ["validate", "mutate", "validate"]) - self.assertEqual(accepted["history"][1]["actor"], {"kind": "model", "id": "claude"}) + self.assertEqual(accepted["history"][1]["actor"], {"kind": "model", "id": "claude", "model": "claude-sonnet-4-5", "family": "anthropic"}) review = json.loads((self.tree / "order-path.variants" / "review.json").read_text(encoding="utf-8")) self.assertEqual({v["decision"] for v in review["verdicts"]}, {"accept", "reject"}) + self.assertEqual(review["verdicts"][0]["reviewer"]["family"], "openai") kinds = [(e["body"]["operation"], e["body"].get("to"), e["body"]["actor"]["id"]) for e in self.home.events() if e["kind"] == "spec_changed"] self.assertIn(("mutate", "mutated", "claude"), kinds) self.assertIn(("mutate", "mutated", "grok"), kinds) @@ -908,17 +1278,46 @@ def test_loop_through_the_cli(self): self.assertIn(("review", None, "gpt"), kinds) self.assertEqual(kinds[-1][:2], ("validate", "candidate")) verdict_id = out.split("--verdict ")[1].split()[0] + self.assertNotIn("--actor model:", out) code, out, err = self.cli("spec", "promote", str(target), "--verdict", verdict_id, "--actor", "model:gpt", "--tickets", str(self.tree / "tickets")) + self.assertEqual(code, 2, "the reviewer cannot promote what it reviewed, nor can any model") + self.assertIn("spec_actor", err) + os.environ["SYBERLABS_FACTORY_TEST_SEED"] = OWNER_SEED.hex() + self.addCleanup(os.environ.pop, "SYBERLABS_FACTORY_TEST_SEED", None) + (self.tree / "owner.pub").write_text(OWNER_PUBLIC.hex(), encoding="utf-8") + approval = self.tree / "approval.json" + code, out, err = self.cli("approve", str(target), "--verdict", verdict_id, "--actor", "human:mateo", + "--seed-env", "SYBERLABS_FACTORY_TEST_SEED", "--out", str(approval)) + self.assertEqual(code, 0, err) + # The spec edited after review is not the variant that was reviewed. + edited = json.loads(target.read_text(encoding="utf-8")) + edited["requirements"][0]["text"] += " (and something the reviewer never saw)" + target.write_text(json.dumps(edited), encoding="utf-8") + code, out, err = self.cli("spec", "promote", str(target), "--verdict", verdict_id, "--actor", "human:mateo", + "--approval", str(approval), "--owner-public", str(self.tree / "owner.pub")) + self.assertEqual(code, 2) + self.assertIn("spec_verdict", err) + target.write_text(json.dumps(accepted, indent=2, sort_keys=True) + "\n", encoding="utf-8") + code, out, err = self.cli("spec", "promote", str(target), "--verdict", verdict_id, "--actor", "human:mateo", + "--approval", str(approval), "--owner-public", str(self.tree / "owner.pub"), + "--tickets", str(self.tree / "tickets")) self.assertEqual(code, 0, err) self.assertEqual(len(list((self.tree / "tickets").glob("*.json"))), 1) + self.assertTrue(self.home.verify()) - def test_a_reviewer_who_proposed_is_refused_and_a_review_accepting_two_is_refused(self): - run = lambda role: f"{self.py} {self.proposers} {role}" - code, out, err = self.cli("variants", str(self.spec_path), "--proposer", f"gpt={run('tighten')}", - "--reviewer", f"gpt={run('review')}") + def test_a_reviewer_of_the_proposers_family_is_refused_and_a_review_accepting_two_is_refused(self): + run = lambda role, model="": f"{self.py} {self.proposers} {role} {model}".rstrip() + code, out, err = self.cli("variants", str(self.spec_path), "--proposer", f"a={run('tighten', 'gpt-5')}", + "--reviewer", f"b={run('review')}") + self.assertEqual(code, 2) + self.assertIn("reviewer_not_independent", err) + self.assertIn("both served by openai", err, "same family under two names") + code, out, err = self.cli("variants", str(self.spec_path), "--proposer", f"a={run('tighten')}", + "--reviewer", f"r={run('review', 'none')}") self.assertEqual(code, 2) self.assertIn("reviewer_not_independent", err) + self.assertIn("not recorded", err, "a reviewer that declares no model is refused, not trusted") code, out, err = self.cli("variants", str(self.spec_path), "--proposer", f"a={run('tighten')}", "--proposer", f"b={run('tighten')}", "--reviewer", f"r={run('review-all')}") self.assertEqual(code, 2) From c78268a2cd4293b7d6c7d84b259ec4f272a5bda2 Mon Sep 17 00:00:00 2001 From: sykosyber Date: Mon, 2 Nov 2026 01:53:40 -0800 Subject: [PATCH 2/8] Factory goal gate, after the #164 verification: pin the owner key on the ledger (owner_key_set; bootstrap once, rotation signed by the pinned key; owner_key_unset and owner_key_mismatch refuse), run the candidate and its test suite under the scrubbed check environment without the host's seed, deliver no journal for a killed run, make Approved constructible by verify_approval only, name checks.stop_tree, and record the content-digest binding and the deferred C1 items M1: the approval verifies under the key the ledger pins, read from the events, never a key the caller names. `factory owner --public KEY` (or the first `--owner-public`) pins it once; `factory owner --public NEW --seed-env OLD` rotates under the pinned key's signature, stored under approvals/ and checked by verify. M2: harness.record and the tests runner build the child's environment from checks.scrubbed_environment and strip SYBERLABS_CERTIFICATE_SEED and the check's --seed-env variable. L1: deliver=False on the kill branch. L2: Approved takes a module-private token; transition checks it. L3: FACTORY.md says content digest (parsed, history excluded) and why the bytes are not bound. L5: checks.stop_tree and checks.scrubbed_environment are the public names. GAPS 65 states the trust model; the entry keeps its number on this branch. Co-Authored-By: Claude Fable 5.1 --- docs/FACTORY.md | 69 ++++++++++++---- spec/GAPS.md | 2 +- syberlabs/checks.py | 6 ++ syberlabs/factory/cli.py | 88 +++++++++++++++----- syberlabs/factory/harness.py | 28 +++++-- syberlabs/factory/ledger.py | 47 +++++++++-- syberlabs/factory/spec.py | 109 +++++++++++++++++++++---- tests/test_factory.py | 151 +++++++++++++++++++++++++++++++++-- 8 files changed, 430 insertions(+), 70 deletions(-) diff --git a/docs/FACTORY.md b/docs/FACTORY.md index 0982f5a..6576649 100644 --- a/docs/FACTORY.md +++ b/docs/FACTORY.md @@ -12,7 +12,7 @@ architecture conformance, spec-driven development, attestation, ledger storage) are in the architecture plan this slice was built from. This page is what the repository does today. Package: `syberlabs/factory/`. Standard library only. `syberlabs` still does not import `syberwork`. -Claim ceiling for this page: **implemented** and **tested** (`tests/test_factory.py`, 45 tests, and the +Claim ceiling for this page: **implemented** and **tested** (`tests/test_factory.py`, 48 tests, and the CLI run below). Nothing here is measured, deployed or externally validated. ## The v0 slice @@ -44,8 +44,9 @@ python -m syberlabs.factory at RUN_A --seq 10 # main python -m syberlabs.factory replay RUN_A --entry fxapp.main:run --fixture fixture.json # effects come from the journal python -m syberlabs.factory spec validate spec.json python -m syberlabs.factory variants spec.json --proposer claude=CMD --reviewer gpt=CMD # writes spec.v2.json, prints the verdict id +python -m syberlabs.factory owner --public owner.pub # pin the owner key, once; the gate trusts no other python -m syberlabs.factory approve spec.v2.json --verdict VERDICT --actor human:mateo --seed-env SYBERLABS_FACTORY_OWNER_SEED --out approval.json -python -m syberlabs.factory spec promote spec.v2.json --verdict VERDICT --actor human:mateo --approval approval.json --owner-public owner.pub +python -m syberlabs.factory spec promote spec.v2.json --verdict VERDICT --actor human:mateo --approval approval.json python -m syberlabs.factory ticket spec.v2.json --req R1 --baseline RUN_A --owner mateo --out ticket.json python -m syberlabs.factory record --entry fxapp.main:run --fixture fixture.json --revision candidate1 python -m syberlabs.factory attest --baseline RUN_A --candidate RUN_B --ticket ticket.json --commit candidate1 \ @@ -59,24 +60,51 @@ An entrypoint is `module:function`, imported from the root and called as `functi hook installed after the import so the import is not part of the run, or a script run as `__main__` whose own body is its first span and which takes its context from `syberlabs.factory.harness.current()`. Effects go through `ctx.run(name, fn, ...)`; that is the only instrumentation a program needs, and the only part -replay cannot do without. The child inherits the caller's environment, as provider commands do (`-I` drops -the `PYTHON*` variables); it is not a sandbox. The signing seed is read from the named environment variable -the way `syberlabs certify` reads it; only the name is recorded. +replay cannot do without. The child runs under the Build Thread's scrubbed environment +(`checks.scrubbed_environment`: `PATH`, the locale, the package managers' cache variables, a temporary `HOME` +and `TMP` inside the host-owned scratch directory, `SYBERLABS_CANDIDATE` and `SYBERLABS_BASE` as the host has +them), not the caller's whole environment, and `-I` drops the `PYTHON*` variables besides; the host's signing +seed (`SYBERLABS_CERTIFICATE_SEED`) and a check's `--seed-env` variable are never in it. It is not a sandbox. +The signing seed is read from the named environment variable the way `syberlabs certify` reads it; only the +name is recorded. ## The goal gate The factory may propose a spec at any level; it may promote none. `spec promote`, `canonize` and `retire` take a human `--actor` (`kind:id`, resolved to a principal; free text is refused) and an approval that verifies: `factory approve` signs, with the owner's seed, a payload naming the spec (id, version and its -digest as it is on disk), the operation and the verdict ids; `spec promote` verifies it under -`--owner-public`, requires the approver to be the actor, and resolves each `--verdict` on the ledger to a -`review` event that accepted the very variant the file is (the `validate` event's digest must match, so a -spec edited after review is refused), whose proposers and reviewer the approver is not. The approval is -stored under `approvals/` and logged as `approval_recorded`; the `spec_changed` cites that event's hash. A -model actor, a missing approval, a verdict that is a string rather than a review, or an approval under -another key each refuse, and the variant loop no longer suggests that the reviewer promote what it reviewed. -The intended source of the approval is a kernel `approved` event on a goal case (approver not proposer, -`session.py`); until the factory has a case to hang it on, the owner's signature stands in (`spec/GAPS.md`). +content digest: the parsed document without `history`, so a re-serialized file is the same spec), the +operation and the verdict ids; `spec promote` verifies it under the owner key the ledger pins, requires the +approver to be the actor, and resolves each `--verdict` on the ledger to a `review` event that accepted the +very variant the file is (the `validate` event's digest must match, so a spec edited after review is +refused), whose proposers and reviewer the approver is not. The approval is stored under `approvals/` and +logged as `approval_recorded`; the `spec_changed` cites that event's hash. A model actor, a missing +approval, a verdict that is a string rather than a review, or an approval under another key each refuse, and +the variant loop no longer suggests that the reviewer promote what it reviewed. + +**The trust model.** Promotion is bound to the owner key the ledger pins, not to whoever runs the host +command. The key lives on the ledger as an `owner_key_set` event: `factory owner --public KEY` (or the first +`--owner-public` a `spec promote` sees) pins it once, and that bootstrap is the one unsigned act, done by the +operator by hand on a ledger that pins none (a Class C act: whoever pins first owns that ledger). From then on +`spec.gate` reads the pinned key from the ledger's events and verifies under it only: a ledger with no pinned +key refuses (`owner_key_unset`), an approval signed under any other key refuses (`owner_key_mismatch`), and +`--owner-public` naming a different key refuses the same way rather than being believed. Rotation is +`factory owner --public NEW --seed-env OLD`: the key pinned now signs the handover, the ledger stores that +signature under `approvals/` and cites it from the new `owner_key_set`, and `verify` checks it like any +artifact; a rotation the pinned key did not sign is refused (`owner_key_rotation`). The verifier's repro of +#164 (generate a keypair, approve with it, promote with `--owner-public mine.pub`) is refused at +`owner_key_mismatch`, and `tests/test_factory.py::CliTests::test_the_owner_key_is_pinned_and_rotates_only_under_the_old_key` +pins that. `Approved`, the record `transition` takes for a gated operation, is made by `verify_approval` only: +its constructor demands a module-private token, and `transition` checks the token, so neither a dictionary nor +an instance made around the constructor passes the gate. + +The approval covers the spec's **content** digest, parsed and with `history` excluded, not the file's bytes; +both sides digest the same way, so a re-indented or re-keyed file still promotes, and an edit to the file's +`history` between signing and promotion is invisible to the approval. That is deliberate: the ledger's +`spec_changed` events are the history of record, the file's copy is a convenience the promotion rewrites +anyway, and binding the bytes would refuse the re-serialized file for nothing gained. The intended source of +the approval is a kernel `approved` event on a goal case (approver not proposer, `session.py`); until the +factory has a case to hang it on, the owner's signature stands in (`spec/GAPS.md`). ## The candidate is not trusted @@ -88,7 +116,10 @@ journal with a line written around the recorder, a line edited afterwards, a tor child's report travels over a private pipe and must carry the run's nonce; a line printed to stdout is output, never a report, and the status it claims must agree with the `end` record the parent reads itself. `factory check` verifies the ledger, chain and artifacts, before the candidate runs and again after it -exits, and refuses if anything moved in between. Every artifact load checks the file against the digest the +exits, and refuses if anything moved in between. A run stopped at its timeout has no `end` record, and its +journal is not delivered either. The child's environment is the Build Thread's scrubbed one, without the +host's signing seed or the check's `--seed-env` variable, so the recorded program and the test suite it is +followed by cannot read the seed that signs the attestation; the same scrubbed environment runs the suite. Every artifact load checks the file against the digest the ledger recorded, so an edited golden journal cannot become a baseline (`load_run` refuses it, `verify` names it). The residual is memory: code in the child can reach the recorder and its key through `sys.modules`, because io observation has to run in the candidate's process. That is recorded in @@ -315,3 +346,11 @@ step, mutation score in the gate, change coupling from git history in `impact`, Barn reading attestations. The open decision upstream of all of it is whether a host-run trace diff over a declared footprint counts as independent review for MasterMind's auto class; if it does, the loop closes without changing who promotes. + +Deferred from the consolidation packet, explicitly, so the next packet picks them up rather than rediscovers +them: `serves`, `mission_ref` and `done_when` on specs; a mandatory `human_owner` on tickets; `promote` +renamed `pass`; `tickets.py` and `codemap.py` as modules of their own; the kernel approval seam (an `approved` +event on a goal case in place of the owner's signature); the behavior-change label moving from the check's +argv to the ticket (today it is per contract, `spec/GAPS.md` 65); and signing the ledger's chain head through +`witness`/`tlog` so a consistent forged chain is distinguishable from an honest one across runs (D1, +`spec/GAPS.md` 65). diff --git a/spec/GAPS.md b/spec/GAPS.md index 8f7e233..f545038 100644 --- a/spec/GAPS.md +++ b/spec/GAPS.md @@ -126,4 +126,4 @@ The schemas describe SyberWork as it behaves. They are not enforced at runtime e 63. **The GitHits pilot's example pacing and license reading rest on GitHits' documentation, not on observed traffic.** (1) The host paces `example` calls to one per 40 s per host (`syberlabs/githits_pace.py`, called by the launcher entry); GitHits' limit is per organization, so two hosts, or an operator's own `syberlabs githits example` (not paced), share the organization's budget without seeing each other's slots. (2) A loopback base URL is not paced unless `SYBERLABS_GITHITS_PACE_SECONDS` asks: a loopback proxy that forwards to GitHits would go unpaced. (3) Calls queued behind several others wait one interval each, so a Bash tool timeout shorter than the queue ends a call before it is sent, and the host then flags it `githits_unrecorded`. (4) The time file is plain text a process of the same user can rewrite; it paces cooperating processes and is no security boundary. (5) The license reading admits an example's `References`/`Sources` links by their `(SPDX)` and passes an example with neither code (a fenced, indented or HTML block) nor a source; inline code in prose is not read as code, and the three documented shapes (`complete`, `degraded`, `no_example` in the pinned OpenAPI document) are the only evidence of what real responses look like until the first live example is recorded. (6) The engineering smoke pins Claude Code 2.1.312 exactly because the host and the pilot VM run it; that version's flags were not re-checked here. 64. **The GitHits launcher fails closed before the network, and the treatment runs on a hooked API lane; neither is verified live, and other lookups on a `--bare` lane are still caught only after the fact.** The live canary of 2026-10-30 (Claude Code 2.1.312 on a Freestyle Linux VM) settled 56 (2): a `--settings` `PreToolUse` hook does not run under `--bare`, so `propose --claude-code --bare --githits` let the model run the launcher with no guard, and the client sent the lookup (`sent: true`) before the host stopped the run `provider_guard_inactive`. Now the launcher's entry sends nothing without claiming the hook's MAC-verified decision for its exact argv (`query_guard.claim_launch`; refused calls are recorded `status: unguarded`, `sent: false`), and `--githits` refuses `--bare` and runs on `--lane api-hooked` (the API key without `--bare`, a fresh `CLAUDE_CONFIG_DIR` and home per call, `--disable-slash-commands`; `docs/CLAUDE_CODE.md`). Not solved: (1) a decision is bound to the launcher's arguments (their SHA-256) and claimed once, not to a tool use id, which the launcher cannot see; a process holding the per-call key (a stdio MCP server, a shell under `--allow-code-tools-with-mcp`) can still sign a decision for its own arguments, as it could before; (2) the hook's words and the launcher's argv agree for plain words and quoted strings under a POSIX shell; a shell or platform that hands over different bytes (Git Bash's argument conversion to a Windows process, a non-UTF-8 byte) refuses a legitimate lookup (fail closed), which no live run has exercised; (3) WebSearch, WebFetch and `--mcp-config` (`mcp__githits__*`) lookups on a `--bare` lane have no pre-send gate: the hook does not run, so they still leave and are flagged `unguarded` afterwards; only `--githits` refuses `--bare`, and `api-hooked` or a login lane is where those tools are guarded; (4) `api-hooked` has run only against the stand-in `claude`: whether 2.1.312 with an empty config directory and home starts headless on `ANTHROPIC_API_KEY` (`apiKeySource`) and runs the hook is for its first live call, and the flags were read from 2.1.309's `--help` because 2.1.312's was not on the building machine; managed (policy) settings still load, `--setting-sources` has no value meaning `--settings` alone, `USERPROFILE` moves only on Windows, and the worktree's memory files (`CLAUDE.md`) are read in both arms, so the lane needs `--trusted-tree`; (5) the example license parser now reads any ATX or bold heading that names a source or reference ("## Source code" included) as a sources section and a fenced or indented block inside a blockquote as code, both of which can only drop more examples (fail closed); how often that drops a usable GitHits example is not measured; (6) the default deny-list (`SyberLabs`, `sykosyber`, `pypi:syberwork`, `deepwiki.com`, `deepwiki.org`) detects a fork of a SyberLabs repository only by its name (`githits.FORK_NAMES`) in a result's URL or a target, so a renamed fork, a vendored copy, or SyberLabs code mirrored under another name and site still passes, and no mirror or front-end other than DeepWiki is listed. -65. **The factory's goal gate is an owner signature, not yet a kernel approval; the candidate's process still shares memory with its recorder; the behavior-change label is per contract.** `factory-goal-gate` (2026-11-02, on the factory slice of #154) closes the slice's verification findings: `spec promote`, `canonize` and `retire` need a human actor and an approval that verifies (`factory approve` signs it with the owner's seed through the certificate module's Ed25519 and DSSE; `spec promote` verifies it under `--owner-public`, resolves every `--verdict` to a ledger `review` that accepted the very variant on disk, refuses an approver who proposed or reviewed it, stores the approval under `approvals/` and cites its `approval_recorded` hash from the `spec_changed`); every artifact load checks the file against the digest the ledger recorded and `verify` covers artifacts, so an edited golden journal refuses the check instead of becoming its baseline; the candidate runs under `python -I` in a host-owned scratch directory, is never told the ledger's path, writes a journal sealed per record under a per-run key the parent holds, reports over a nonce-bound private pipe, and the parent reads the `end` record itself and refuses a journal with no end, a planted line or a mismatching report; `verify` recomputes the policy from the evidence and `signed: true` needs a verifying signature; reviewer independence is the provider family the command declared, not the caller's name, and an unrecorded family refuses; subprocess argv, cwd, socket addresses and the tests tail are scrubbed of credential shapes; the viewer builds its DOM with `textContent` and carries no payloads; ledger appends use the kernel journal's lock, fsync and torn-tail repair, and the projection rebuilds when the log moved; the tests check honours the contract's timeout, `full_suite` means the suite ran to completion, and a timed-out suite or recording has its process tree stopped. What remains: (1) the approval is the owner's signature over the spec digest, not an `approved` event on a kernel goal case, because the factory has no case to hang one on; the ledger event is the citation the consolidation's §1.2 asks for, the journal hash is not; (2) io observation runs in the candidate's process, so code there can reach `_factory_harness._CURRENT[-1]` and its key through `sys.modules` and write records the seal accepts, or call the recorder's own `__exit__`; the seal and the channel raise the cost of a forgery, they are not a sandbox, and the recommendation on the open owner question stands: evidence with a person in the path, not the auto class; (3) a candidate that learns the ledger's absolute path from the contract in its worktree can still write to it between the check's two verifications only by forging a consistent unkeyed chain and matching digests, which `verify` does not distinguish from an honest ledger across runs; anchoring the chain head in `tlog`/`witness` is the fix; (4) the behavior-change label is `--behavior-change` on the check's argv, per contract, not a field of the ticket; (5) `independence` reads the model the command declared, so a command that lies about its model passes as it does for `model_usage`; (6) `verify_journal` reads text, so a journal whose line endings were rewritten verifies by content while the ledger's byte digest refuses it, which is the intended division; (7) before this packet the ledger had no cross-process lock (two commands on one home could fork the chain, detected by `append` but not prevented) and `docs/FACTORY.md` said 18 tests where the file defined 35; both are fixed here. The consolidation's other C1 items (`serves`, `mission_ref`, `done_when` on specs, mandatory `human_owner` on tickets, `promote` renamed `pass`, `tickets.py`, `codemap.py`) are not in this packet. +65. **The factory's goal gate is an owner signature, not yet a kernel approval; the candidate's process still shares memory with its recorder; the behavior-change label is per contract.** `factory-goal-gate` (2026-11-02, on the factory slice of #154) closes the slice's verification findings: `spec promote`, `canonize` and `retire` need a human actor and an approval that verifies (`factory approve` signs it with the owner's seed through the certificate module's Ed25519 and DSSE; `spec promote` verifies it under the owner key the ledger pins (`owner_key_set`; `factory owner`), never a key the caller names, resolves every `--verdict` to a ledger `review` that accepted the very variant on disk, refuses an approver who proposed or reviewed it, stores the approval under `approvals/` and cites its `approval_recorded` hash from the `spec_changed`); every artifact load checks the file against the digest the ledger recorded and `verify` covers artifacts, so an edited golden journal refuses the check instead of becoming its baseline; the candidate runs under `python -I` in a host-owned scratch directory, is never told the ledger's path, writes a journal sealed per record under a per-run key the parent holds, reports over a nonce-bound private pipe, and the parent reads the `end` record itself and refuses a journal with no end, a planted line or a mismatching report; `verify` recomputes the policy from the evidence and `signed: true` needs a verifying signature; reviewer independence is the provider family the command declared, not the caller's name, and an unrecorded family refuses; subprocess argv, cwd, socket addresses and the tests tail are scrubbed of credential shapes; the viewer builds its DOM with `textContent` and carries no payloads; ledger appends use the kernel journal's lock, fsync and torn-tail repair, and the projection rebuilds when the log moved; the tests check honours the contract's timeout, `full_suite` means the suite ran to completion, and a timed-out suite or recording has its process tree stopped; after the independent verification of #164 (2026-11-02), the candidate's process and the test suite run under the Build Thread's scrubbed environment without the host's signing seed or the check's `--seed-env` variable, a killed run's journal is not delivered, and `Approved` is constructible by `verify_approval` only. What remains: (1) the approval is the owner's signature over the spec's content digest, not an `approved` event on a kernel goal case, because the factory has no case to hang one on; the trust model is exactly this: promotion is bound to the owner key the ledger pins, not to the caller of the host CLI; the pin's bootstrap (`factory owner --public KEY`, or the first `--owner-public` on a ledger that pins none) is the one unsigned act, done by the operator by hand, so whoever pins first on an empty ledger owns it (a Class C act), after which only the pinned key approves (`owner_key_mismatch` otherwise, `owner_key_unset` before any pin) and only the pinned key rotates (`owner_key_rotation` otherwise); the ledger event is the citation the consolidation's §1.2 asks for, the journal hash is not; (2) io observation runs in the candidate's process, so code there can reach `_factory_harness._CURRENT[-1]` and its key through `sys.modules` and write records the seal accepts, or call the recorder's own `__exit__`; the seal and the channel raise the cost of a forgery, they are not a sandbox, and the recommendation on the open owner question stands: evidence with a person in the path, not the auto class; (3) a candidate that learns the ledger's absolute path from the contract in its worktree can still write to it between the check's two verifications only by forging a consistent unkeyed chain and matching digests, which `verify` does not distinguish from an honest ledger across runs; anchoring the chain head in `tlog`/`witness` is the fix; (4) the behavior-change label is `--behavior-change` on the check's argv, per contract, not a field of the ticket; (5) `independence` reads the model the command declared, so a command that lies about its model passes as it does for `model_usage`; (6) `verify_journal` reads text, so a journal whose line endings were rewritten verifies by content while the ledger's byte digest refuses it, which is the intended division, and the approval likewise covers the spec's content digest (parsed, `history` excluded), so a re-serialized file is the same spec and an edit to the file's `history` after signing is not covered, the ledger's `spec_changed` events being the history of record; (7) before this packet the ledger had no cross-process lock (two commands on one home could fork the chain, detected by `append` but not prevented) and `docs/FACTORY.md` said 18 tests where the file defined 35; both are fixed here. The consolidation's other C1 items (`serves`, `mission_ref`, `done_when` on specs, mandatory `human_owner` on tickets, `promote` renamed `pass`, `tickets.py`, `codemap.py`) are not in this packet. diff --git a/syberlabs/checks.py b/syberlabs/checks.py index dd16eee..8430806 100644 --- a/syberlabs/checks.py +++ b/syberlabs/checks.py @@ -117,6 +117,12 @@ def _stop(proc: subprocess.Popen) -> None: proc.wait() +# The two routines another host-side runner reuses (the factory's harness and its tests runner), under public +# names: the scrubbed environment a check runs under, and the stop of a check's whole process tree. +scrubbed_environment = _environment +stop_tree = _stop + + def run_check(argv: list[str], cwd: Path, env: dict, timeout: int, max_output: int, log: Path, stdin: Path | None = None) -> dict: """Run one check. ``stdin`` is a file handed to the command's standard input; without one it reads nothing.""" diff --git a/syberlabs/factory/cli.py b/syberlabs/factory/cli.py index 231cd7b..6842868 100644 --- a/syberlabs/factory/cli.py +++ b/syberlabs/factory/cli.py @@ -8,8 +8,9 @@ syberlabs factory at RUN --seq 12 # what was active at a logical time syberlabs factory export RUN --chrome trace.json | --view run.html syberlabs factory spec validate spec.json + syberlabs factory owner --public owner.pub # pin the owner key (once); --seed-env OLD rotates syberlabs factory approve spec.json --verdict V --actor human:mateo --seed-env NAME --out approval.json - syberlabs factory spec promote|canonize|retire spec.json --actor human:mateo --approval approval.json --owner-public KEY + syberlabs factory spec promote|canonize|retire spec.json --actor human:mateo --approval approval.json syberlabs factory ticket spec.json --req R1 --out ticket.json syberlabs factory attest --baseline A --candidate B --ticket ticket.json --commit SHA syberlabs factory verify attestation.json --public KEY @@ -120,13 +121,16 @@ def populate(factory) -> None: export.add_argument("--view", metavar="FILE", help="write an HTML page that scrubs the run over its Space graph") sp = steps.add_parser("spec", help="move a spec file through its lifecycle; each step is logged. promote, canonize and " - "retire are owner acts: a human --actor plus --approval and --owner-public") + "retire are owner acts: a human --actor plus --approval, verified under the owner key " + "the ledger pins (see `owner`)") sp.add_argument("operation", choices=sorted(specmod.TRANSITIONS)) sp.add_argument("spec", help="the spec JSON file; rewritten in place") sp.add_argument("--actor", default="human:operator", help="kind:id, kind in human|model|compiled (default human:operator)") sp.add_argument("--verdict", action="append", default=[], help="a review verdict id promotion rests on; resolved on the ledger") sp.add_argument("--approval", metavar="FILE", help="the owner's signed approval from `factory approve` (promote, canonize, retire)") - sp.add_argument("--owner-public", metavar="KEY", help="the owner's .pub file the approval must verify under") + sp.add_argument("--owner-public", metavar="KEY", help="bootstrap only: pin this .pub as the owner key when the ledger pins " + "none (the same as `factory owner --public KEY`); a pinned ledger " + "refuses a different key here, rotation goes through `owner`") sp.add_argument("--reason") sp.add_argument("--superseded-by") sp.add_argument("--tickets", metavar="DIR", help="on promote: open one ticket per requirement into DIR, footprint " @@ -134,8 +138,13 @@ def populate(factory) -> None: sp.add_argument("--baseline", default="golden", help="the golden run or label the tickets diff against (default golden)") sp.add_argument("--owner", help="the accountable human on the tickets") - ap = steps.add_parser("approve", help="sign the owner's approval of a promote, canonize or retire of a spec as it is on disk; " - "the seed is read from an environment variable and never written") + own = steps.add_parser("owner", help="the owner key the ledger pins: print it; --public KEY pins it once (bootstrap); " + "--public NEW --seed-env OLD rotates, signed by the key pinned now") + own.add_argument("--public", metavar="KEY", help="the owner's .pub file (64 hex characters)") + own.add_argument("--seed-env", metavar="NAME", help="on rotation: the variable holding the seed of the key pinned now") + + ap = steps.add_parser("approve", help="sign the owner's approval of a promote, canonize or retire of a spec by its content " + "digest; the seed is read from an environment variable and never written") ap.add_argument("spec") ap.add_argument("--operation", choices=sorted(specmod.GATED), default="promote") ap.add_argument("--verdict", action="append", default=[], help="the verdict ids the promotion rests on (must match `spec promote`)") @@ -356,6 +365,9 @@ def _run(args) -> int: if command == "spec": return _spec(args, home) + if command == "owner": + return _owner(args, home) + if command == "approve": return _approve(args) @@ -490,10 +502,11 @@ def _check(args, home: ledger.Ledger) -> int: baseline_records = home.load_run(baseline_id) fixture = _read_json(args.fixture, "fixture") if args.fixture else {} run_id = harness.new_run_id() + strip_env = (args.seed_env,) if args.seed_env else () # the check's own seed never reaches the candidate or its suite recorded = harness.record(root, home.run_path(run_id), args.entry, file_components={p: r.get("component") for p, r in graph["files"].items()}, fixture=fixture, run_id=run_id, revision=commit, space_digest=space_event["body"]["space_digest"], - blobs=home.home / "blobs") + blobs=home.home / "blobs", strip_env=strip_env) if recorded.get("stdout"): print(recorded["stdout"]) after = home.events() @@ -511,7 +524,7 @@ def _check(args, home: ledger.Ledger) -> int: if recorded.get("error"): evidence["run"] = {"kind": "run", "status": recorded["status"], "error": recorded["error"]} if args.tests_argv: - evidence["tests"] = _run_tests(root, args.tests_argv, args.tests_timeout) + evidence["tests"] = _run_tests(root, args.tests_argv, args.tests_timeout, strip_env=strip_env) print(f"tests: {' '.join(harness.mask(a) for a in evidence['tests']['argv'])} -> exit {evidence['tests']['exit_code']}" f" in {evidence['tests']['seconds']}s") builder_text = args.builder or os.environ.get("SYBERLABS_CANDIDATE") or "operator" @@ -633,17 +646,21 @@ def _bootstrap(args, home: ledger.Ledger) -> int: TESTS_TAIL_CHARS = 2000 -def _run_tests(root: Path, argv_json: str, timeout: int) -> dict: +def _run_tests(root: Path, argv_json: str, timeout: int, strip_env: tuple = ()) -> dict: """Run the suite the contract names, in the worktree, and reduce it to a tests evidence entry. The exit code is the verdict (a runner's own counts are not parsed); the output digest lets a reviewer find the log, and the tail that enters the attestation is capped and scrubbed of credential shapes. ``full_suite`` is true only when the suite ran to completion: a timed-out or unstartable run is not a full suite. On timeout the - whole process tree is stopped, as the Build Thread's own checks do.""" + whole process tree is stopped, as the Build Thread's own checks do. The suite runs under the Build + Thread's scrubbed environment (``checks.scrubbed_environment``, with ``SYBERLABS_CANDIDATE`` and + ``SYBERLABS_BASE`` as the host has them, so a floor runner still sees its base) without the host's signing + seed or any variable in ``strip_env``.""" import hashlib import subprocess import tempfile import time - from syberlabs.checks import _stop as stop_tree + from syberlabs.certificate import DEFAULT_SEED_ENV + from syberlabs.checks import scrubbed_environment, stop_tree try: argv = json.loads(argv_json) if not isinstance(argv, list) or not all(isinstance(a, str) for a in argv) or not argv: @@ -652,9 +669,12 @@ def _run_tests(root: Path, argv_json: str, timeout: int) -> dict: raise Rejected("tests_argv", "--tests-argv is a JSON list of strings") from None started = time.monotonic() exit_code, timed_out = None, False - with tempfile.TemporaryFile() as log: + with tempfile.TemporaryDirectory(prefix="syberlabs-factory-tests-") as home, tempfile.TemporaryFile() as log: + env = scrubbed_environment(Path(home), os.environ.get("SYBERLABS_CANDIDATE") or "operator", os.environ.get("SYBERLABS_BASE")) + for name in (DEFAULT_SEED_ENV, *strip_env): + env.pop(name, None) try: - proc = subprocess.Popen(argv, cwd=str(root), stdin=subprocess.DEVNULL, stdout=log, stderr=subprocess.STDOUT, + proc = subprocess.Popen(argv, cwd=str(root), env=env, stdin=subprocess.DEVNULL, stdout=log, stderr=subprocess.STDOUT, start_new_session=hasattr(os, "setsid")) except OSError as exc: log.write(f"could not start {argv[0]!r}: {exc.strerror or exc}\n".encode()) @@ -815,7 +835,7 @@ def _variants(args, home: ledger.Ledger) -> int: print(f"accepted {review['accepted']} -> {target.name} (candidate); the owner promotes it: " f"factory approve {target.name} --verdict {verdict_id} --actor human:OWNER --seed-env NAME --out approval.json, then " f"factory spec promote {target.name} --verdict {verdict_id} --actor human:OWNER --approval approval.json " - f"--owner-public KEY --tickets DIR") + f"--tickets DIR") return 0 @@ -830,9 +850,30 @@ def _describe_side(entry: dict | None) -> str: return f"{entry['kind']} {entry['name']}: {json.dumps(payload, sort_keys=True, default=str)[:160]}" +def _owner(args, home: ledger.Ledger) -> int: + """The owner key the ledger pins. Without ``--public``: print it. With it on a ledger that pins none: the + bootstrap, pinned once and from then on the only key the gate trusts (a Class C act: whoever runs this + first on an empty ledger is its owner, which is why it is one explicit command). With it on a pinned + ledger: a rotation, signed by the seed of the key pinned now (``--seed-env``) or refused.""" + current = home.owner_key() + if not args.public: + print(f"owner key: {current or '(unset)'}") + return 0 if current else 1 + public = certificate.read_public(args.public) + if current == public.hex(): + print(f"owner key: {current} (already pinned)") + return 0 + seed = certificate.load_seed(args.seed_env) if args.seed_env else None + event = home.set_owner_key(public, seed=seed) + body = event["body"] + what = f"rotated from {body['previous'][:10]} (rotation {body['rotation_digest'][:12]})" if body["previous"] else "pinned (bootstrap)" + print(f"owner key: {body['keyid']} {what} (ledger seq {event['seq']})") + return 0 + + def _approve(args) -> int: - """The owner signs an approval of one gated operation on a spec as it is on disk. Nothing touches the - ledger here; `spec promote` verifies and records the approval.""" + """The owner signs an approval of one gated operation on a spec by its content digest. Nothing touches the + ledger here; `spec promote` verifies it under the key the ledger pins and records it.""" document = _read_json(args.spec, "spec") actor = specmod.principal(args.actor) payload = specmod.approval_payload(document, args.operation, actor, verdict_ids=args.verdict) @@ -861,10 +902,21 @@ def _spec(args, home: ledger.Ledger) -> int: if args.operation in specmod.GATED: if actor["kind"] != "human": raise Rejected("spec_actor", f"{args.operation} is an owner act: the actor's kind is human, not {actor['kind']!r}") - if not args.approval or not args.owner_public: - raise Rejected("spec_approval", f"{args.operation} is an owner act: pass --approval FILE (from `factory approve`) and --owner-public KEY") + if not args.approval: + raise Rejected("spec_approval", f"{args.operation} is an owner act: pass --approval FILE (from `factory approve`)") envelope = _read_json(args.approval, "approval") - approval, resolved = specmod.gate(document, args.operation, actor, home.events(), envelope, certificate.read_public(args.owner_public), + if args.owner_public: + # Bootstrap only: the first key a ledger sees is pinned. A pinned ledger takes the same key as a no-op + # and refuses any other here; rotation is `factory owner --public NEW --seed-env OLD`, never this flag. + public = certificate.read_public(args.owner_public) + pinned = home.owner_key() + if pinned is None: + event = home.set_owner_key(public) + print(f"owner key {public.hex()[:10]} pinned (bootstrap; ledger seq {event['seq']})") + elif pinned != public.hex(): + raise Rejected("owner_key_mismatch", f"the ledger pins owner key {pinned[:10]}, not {public.hex()[:10]}; " + "rotate with `factory owner --public NEW --seed-env OLD`") + approval, resolved = specmod.gate(document, args.operation, actor, home.events(), envelope, verdict_ids=args.verdict, spec_digest_value=before_digest) detail["approval"] = approval detail["spec_digest"] = before_digest diff --git a/syberlabs/factory/harness.py b/syberlabs/factory/harness.py index 7ad0d2c..1cd2902 100644 --- a/syberlabs/factory/harness.py +++ b/syberlabs/factory/harness.py @@ -599,7 +599,8 @@ def _tail(path: Path) -> str: def record(root: str | Path, journal: str | Path, entry: str, *, file_components: dict | None = None, fixture: dict | None = None, run_id: str | None = None, revision: str | None = None, space_digest: str | None = None, replay_of: str | Path | None = None, blobs: str | Path | None = None, - python: str | None = None, timeout: float = 3600.0, observe: tuple = OBSERVERS) -> dict: + python: str | None = None, timeout: float = 3600.0, observe: tuple = OBSERVERS, + strip_env: tuple = ()) -> dict: """Run ``entry`` under the recorder in an isolated child interpreter and return its report. ``entry`` is ``module:function`` (imported from ``root``, called as ``function(ctx, fixture)``) or a script @@ -612,10 +613,17 @@ def record(root: str | Path, journal: str | Path, entry: str, *, file_components never told where ``journal`` or ``blobs`` are. Afterwards the parent verifies the journal's seal under the per-run key, reads the ``end`` record itself, requires the child's report (one message on a private pipe, bound by the run's nonce) to agree with it, and only then moves the journal to ``journal`` and the blobs to - ``blobs``. A journal that fails its seal is not delivered. On timeout the whole process tree is stopped. - The child inherits this process's environment (``-I`` drops the ``PYTHON*`` variables): a program's own - secrets stay its own, and nothing here is a sandbox.""" - from syberlabs.checks import _stop as stop_tree # the Build Thread's own tree kill; parent side only + ``blobs``. A journal that fails its seal is not delivered, and neither is the journal of a run that was + killed. On timeout the whole process tree is stopped. + + The child runs under the Build Thread's scrubbed environment (``checks.scrubbed_environment``: ``PATH``, + the locale, the package managers' cache variables, a temporary ``HOME`` and ``TMP`` inside the scratch + directory, ``SYBERLABS_CANDIDATE`` and ``SYBERLABS_BASE`` as the host has them), never this process's + whole environment: the host's signing seed (``certificate.DEFAULT_SEED_ENV``) and every variable named in + ``strip_env`` (a ``--seed-env``) are not in it, whatever the host holds. ``-I`` drops the ``PYTHON*`` + variables besides. This is still not a sandbox.""" + from syberlabs.certificate import DEFAULT_SEED_ENV + from syberlabs.checks import scrubbed_environment, stop_tree # the Build Thread's own; parent side only root = Path(root).resolve() destination = Path(journal).resolve() @@ -632,6 +640,11 @@ def record(root: str | Path, journal: str | Path, entry: str, *, file_components "stdout": "", "stderr": "", "returncode": None} scratch = Path(tempfile.mkdtemp(prefix="syberlabs-factory-")) # host-owned: outside the worktree and the ledger try: + child_home = scratch / "home" + child_home.mkdir() + env = scrubbed_environment(child_home, os.environ.get("SYBERLABS_CANDIDATE") or run_id, os.environ.get("SYBERLABS_BASE")) + for name in (DEFAULT_SEED_ENV, *strip_env): + env.pop(name, None) child_journal = scratch / "journal.jsonl" child_blobs = scratch / "blobs" if blobs is not None else None child_replay = None @@ -658,8 +671,8 @@ def record(root: str | Path, journal: str | Path, entry: str, *, file_components with (scratch / "stdout").open("wb") as out, (scratch / "stderr").open("wb") as err: try: proc = subprocess.Popen([python or sys.executable, "-I", "-c", BOOTSTRAP], stdin=subprocess.PIPE, stdout=out, - stderr=err, cwd=str(root), close_fds=True, start_new_session=hasattr(os, "setsid"), - **channel.popen_kwargs) + stderr=err, cwd=str(root), env=env, close_fds=True, + start_new_session=hasattr(os, "setsid"), **channel.popen_kwargs) finally: channel.started() try: @@ -683,6 +696,7 @@ def record(root: str | Path, journal: str | Path, entry: str, *, file_components deliver = child_journal.exists() if killed: report["status"], report["error"] = "killed", f"no end after {timeout} seconds" + deliver = False # a run that was stopped has no end record; its journal is not evidence and is not delivered elif not deliver: report["error"] = "the child wrote no journal" else: diff --git a/syberlabs/factory/ledger.py b/syberlabs/factory/ledger.py index 9ab4191..7ffea3c 100644 --- a/syberlabs/factory/ledger.py +++ b/syberlabs/factory/ledger.py @@ -7,7 +7,7 @@ runs/.jsonl harness journals blobs/ effect payloads too large to inline attestations/.json - approvals/.json the owner's signed approvals a promotion rests on + approvals/.json the owner's signed approvals a promotion rests on, and signed owner-key rotations index.sqlite3 the projection: components, runs, steps, cells, edges; rebuilt from the above .journal/ the kernel journal's lock file for this ledger (``syberlabs.journal``) @@ -18,6 +18,10 @@ and ``load_space`` refuse a file whose digest is not the one on the ledger, so an edited golden journal cannot become a gate's baseline. +The owner's public key is pinned here (``owner_key_set``): the first such event is the ledger's trust root and +every later one is a rotation signed by the key it replaces (``set_owner_key``), so the goal gate verifies +approvals under a key the ledger names rather than one the caller passes. + Appends go through the kernel journal's writer (``syberlabs.journal.Journal``): a cross-process lock (``flock`` or ``msvcrt.locking``), flush and fsync per record, and truncation of a torn final line before the next read. Two factory commands on one home therefore serialize instead of forking the chain. @@ -42,12 +46,13 @@ from syberlabs.canonical import canonical, digest from syberlabs.errors import Rejected from syberlabs.factory import PROTOCOL, attest, harness, space +from syberlabs.factory import spec as specmod GENESIS = "0" * 64 EVENT_FIELDS = ("seq", "kind", "body", "at", "previous") RUN_KINDS = frozenset({"run_recorded", "run_replayed"}) KINDS = frozenset({"space_indexed", "run_recorded", "run_replayed", "spec_changed", "ticket_opened", - "attested", "drift_reported", "baseline_set", "approval_recorded", "note"}) + "attested", "drift_reported", "baseline_set", "approval_recorded", "owner_key_set", "note"}) PROJECTION_TABLES = ("components", "edges", "runs", "steps", "effects", "cells", "meta") @@ -135,8 +140,9 @@ def problems(self, events: list[dict] | None = None) -> list[str]: blob = record.get("blob") if blob and (not (self.home / "blobs" / blob).exists() or _file_digest(self.home / "blobs" / blob) != blob): found.append(f"blobs/{blob[:12]} of run {body['run_id']} is missing or does not match") - elif kind in ("attested", "approval_recorded"): - folder, key = ("attestations", "attestation_digest") if kind == "attested" else ("approvals", "approval_digest") + elif kind in ("attested", "approval_recorded") or (kind == "owner_key_set" and body.get("rotation_digest")): + folder, key = {"attested": ("attestations", "attestation_digest"), "approval_recorded": ("approvals", "approval_digest"), + "owner_key_set": ("approvals", "rotation_digest")}[kind] path = self.home / folder / f"{body[key]}.json" if not path.exists(): found.append(f"{folder}/{body[key][:12]} is missing") @@ -294,6 +300,37 @@ def record_approval(self, envelope: dict, approval: dict) -> dict: "spec_digest": approval["spec_digest"], "verdict_ids": list(approval.get("verdict_ids") or [])} return self.append("approval_recorded", body) + # -- the owner key ------------------------------------------------------------------------------------------- + + def owner_key(self, events: list[dict] | None = None) -> str | None: + """The owner's public key (hex) this ledger pins, or None before the first ``owner_key_set``.""" + return specmod.pinned_owner_key(self.events() if events is None else events) + + def set_owner_key(self, public: bytes, *, seed: bytes | None = None) -> dict: + """Pin ``public`` as the owner key. On a ledger that pins none this is the bootstrap: one event, no + signature, and from then on the goal gate trusts this key and no other. On a ledger that pins a key + it is a rotation and needs ``seed``, the seed of the key pinned now: the handover is signed by that + key (``spec.sign_rotation``), verified, stored under ``approvals/`` and cited by the event. Refused + when the seed is not the pinned key's (``owner_key_rotation``) or the key is already pinned + (``owner_key_pinned``). Returns the event.""" + from syberlabs.ed25519 import public_from_seed + + keyid = public.hex() + current = self.owner_key() + if current is None: + return self.append("owner_key_set", {"keyid": keyid, "previous": None, "rotation_digest": None}) + if current == keyid: + raise Rejected("owner_key_pinned", f"the ledger already pins {keyid[:10]}") + if seed is None: + raise Rejected("owner_key_rotation", f"the ledger pins {current[:10]}; rotating to {keyid[:10]} needs that key's seed (--seed-env)") + if public_from_seed(seed).hex() != current: + raise Rejected("owner_key_rotation", f"the seed given is not the pinned owner key's ({current[:10]}); only the pinned key rotates") + envelope = specmod.sign_rotation(specmod.rotation_payload(bytes.fromhex(current), public), seed) + specmod.verify_rotation(envelope, bytes.fromhex(current), public) + sha = digest(envelope) + (self.home / "approvals" / f"{sha}.json").write_text(canonical(envelope), encoding="utf-8") + return self.append("owner_key_set", {"keyid": keyid, "previous": current, "rotation_digest": sha}) + # -- the projection ----------------------------------------------------------------------------------------- def project(self, events: list[dict] | None = None) -> dict: @@ -418,4 +455,4 @@ def describe(self) -> dict: "runs": sum(1 for e in events if e["kind"] in RUN_KINDS), "attestations": sum(1 for e in events if e["kind"] == "attested"), "approvals": sum(1 for e in events if e["kind"] == "approval_recorded"), - "head": self.head(events)} + "owner_key": self.owner_key(events), "head": self.head(events)} diff --git a/syberlabs/factory/spec.py b/syberlabs/factory/spec.py index 7ee5b35..07c17cc 100644 --- a/syberlabs/factory/spec.py +++ b/syberlabs/factory/spec.py @@ -12,13 +12,20 @@ The goal gate. The factory may propose a spec at any level; it may promote none. ``promote``, ``canonize`` and ``retire`` (``GATED``) take a human actor and an approval that verifies: a DSSE envelope the owner signed -over exactly this spec (its digest before the operation), this operation and, for a promotion, the verdict -ids it rests on, each resolved on the ledger to a ``review`` event that accepted this very variant. The -approver may not be a proposer or the reviewer of that variant. ``transition`` accepts only the ``Approved`` -record :func:`verify_approval` returns, so a caller cannot hand it a dictionary of its own. The owner's -public key is the caller's (``--owner-public``); the signing seed never enters this module. A kernel -``approved`` event on a goal case is the intended source of this approval once the factory has a case to -hang it on; until then the signature stands in, and ``spec/GAPS.md`` records the gap. +over exactly this spec (its content digest before the operation), this operation and, for a promotion, the +verdict ids it rests on, each resolved on the ledger to a ``review`` event that accepted this very variant. +The approver may not be a proposer or the reviewer of that variant. ``transition`` accepts only the +``Approved`` record :func:`verify_approval` returns, which nothing outside this module can construct, so a +caller cannot hand it a dictionary of its own. + +The owner's public key is pinned on the ledger, not supplied by the caller: an ``owner_key_set`` event names +it (:func:`pinned_owner_key`), the first one is the trust root of that ledger (bootstrap, written once), and +a later one is a rotation the previous key signed (:func:`verify_rotation`). :func:`gate` verifies every +approval under the pinned key only; a ledger with no pinned key refuses (``owner_key_unset``) and an approval +under any other key refuses (``owner_key_mismatch``), whoever runs the host command. The signing seed never +enters this module. A kernel ``approved`` event on a goal case is the intended source of this approval once +the factory has a case to hang it on; until then the signature stands in, and ``spec/GAPS.md`` records the +gap. v0 implements the lifecycle a single spec needs: draft, revise, validate (to candidate), promote, canonize, retire, and the variant loop (several models proposing variants of one parent, one independent reviewer). @@ -50,7 +57,12 @@ ACTOR_KINDS = ("human", "model", "compiled") APPROVAL_PROTOCOL = "syberlabs.space/factory/approval/v0" APPROVAL_PAYLOAD_TYPE = "application/vnd.syberlabs.factory-approval+json" +OWNER_KEY_PROTOCOL = "syberlabs.space/factory/owner-key/v0" +OWNER_KEY_PAYLOAD_TYPE = "application/vnd.syberlabs.factory-owner-key+json" _PRINCIPAL_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._@+-]{0,63}$") +_HEX_KEY = re.compile(r"^[0-9a-f]{64}$") +# The module-private token ``Approved`` demands: only :func:`verify_approval` holds it. +_ISSUED = object() def principal(text: str) -> dict: @@ -63,13 +75,67 @@ def principal(text: str) -> dict: class Approved(dict): - """A verified approval. Only :func:`verify_approval` makes one; ``transition`` accepts no other.""" + """A verified approval: what :func:`verify_approval` returns and the only thing ``transition`` takes for a + gated operation. The constructor demands a module-private token, so ``Approved({...})`` anywhere else + raises ``approval_forged`` instead of producing something the gate would accept; ``transition`` checks + the token again, so an instance made around the constructor is refused too.""" + + __slots__ = ("_issued",) + + def __init__(self, payload: dict, *, _token: object = None): + if _token is not _ISSUED: + raise Rejected("approval_forged", "an Approved is made by verify_approval only; a verified approval is not a dictionary a caller writes") + super().__init__(payload) + self._issued = _ISSUED + + +def _is_issued(approval: object) -> bool: + return isinstance(approval, Approved) and getattr(approval, "_issued", None) is _ISSUED + + +def pinned_owner_key(events: list[dict]) -> str | None: + """The owner's public key (hex) the ledger pins: the newest ``owner_key_set`` event's ``keyid``, or None + when the ledger has pinned none. The first such event is the ledger's trust root; every later one is a + rotation the previous key signed (``previous`` and ``rotation_digest`` on the event).""" + for event in reversed(events): + if event.get("kind") == "owner_key_set": + keyid = (event.get("body") or {}).get("keyid") + return keyid if isinstance(keyid, str) and _HEX_KEY.match(keyid) else None + return None + + +def rotation_payload(previous: bytes, next_key: bytes) -> dict: + """What the current owner signs to hand the ledger to a new key: the key being replaced and the key that + replaces it. Signed by ``previous``; nothing else can rotate.""" + return {"protocol": OWNER_KEY_PROTOCOL, "previous": previous.hex(), "next": next_key.hex(), "at": int(time.time() * 1_000_000)} + + +def sign_rotation(payload: dict, seed: bytes) -> dict: + return sign_dsse(OWNER_KEY_PAYLOAD_TYPE, canonical(payload).encode("utf-8"), seed) + + +def verify_rotation(envelope: dict, previous: bytes, next_key: bytes) -> dict: + """The rotation payload when ``envelope`` verifies under ``previous`` (the pinned key) and names exactly + this handover; refused (``owner_key_rotation``) otherwise.""" + payload = verified_payload(envelope, previous, OWNER_KEY_PAYLOAD_TYPE) + if payload is None: + raise Rejected("owner_key_rotation", "a rotation is signed by the key the ledger pins now; this one does not verify under it") + try: + rotation = json.loads(payload) + except ValueError: + raise Rejected("owner_key_rotation", "the rotation payload is not JSON") from None + if (not isinstance(rotation, dict) or rotation.get("protocol") != OWNER_KEY_PROTOCOL + or rotation.get("previous") != previous.hex() or rotation.get("next") != next_key.hex()): + raise Rejected("owner_key_rotation", "the rotation does not name this handover (previous and next key)") + return rotation def approval_payload(spec: dict, operation: str, approver: dict, *, verdict_ids: list[str] | None = None, spec_digest_value: str | None = None) -> dict: """What the owner signs: this spec (by id, version and digest), this operation, the verdicts a promotion - rests on, and who approves. The digest is the spec's as it is on disk before the operation.""" + rests on, and who approves. The digest is the spec's content digest (:func:`spec_digest`: the parsed + document without ``history``) before the operation, so a re-serialized file is the same spec and an + edit to the file's ``history`` is not covered; the ledger's ``spec_changed`` events are the history.""" if operation not in GATED: raise Rejected("spec_operation", f"an approval covers one of {sorted(GATED)}, not {operation!r}") if approver.get("kind") != "human": @@ -105,7 +171,7 @@ def verify_approval(envelope: dict, public: bytes, spec: dict, operation: str, * approver = approval.get("approver") if not isinstance(approver, dict) or approver.get("kind") != "human" or not _PRINCIPAL_ID.match(str(approver.get("id"))): raise Rejected("approval_actor", "the approval names no human approver") - return Approved({**approval, "keyid": public.hex()}) + return Approved({**approval, "keyid": public.hex()}, _token=_ISSUED) def resolve_verdicts(events: list[dict], spec: dict, verdict_ids: list[str], spec_digest_value: str | None = None) -> list[dict]: @@ -137,15 +203,23 @@ def resolve_verdicts(events: list[dict], spec: dict, verdict_ids: list[str], spe return resolved -def gate(spec: dict, operation: str, actor: dict, events: list[dict], envelope: dict, owner_public: bytes, *, +def gate(spec: dict, operation: str, actor: dict, events: list[dict], envelope: dict, *, verdict_ids: list[str] | None = None, spec_digest_value: str | None = None) -> tuple[Approved, list[dict]]: - """The goal gate in one call: the actor is human and is the approver, the approval verifies and covers this - spec and operation, and (on promote) every verdict resolves to an accepting review of this variant whose - proposers and reviewer are not the approver. Returns the approval and the resolved verdicts.""" + """The goal gate in one call: the actor is human and is the approver, the ledger pins an owner key and the + approval verifies under that key (no other) and covers this spec and operation, and (on promote) every + verdict resolves to an accepting review of this variant whose proposers and reviewer are not the + approver. The key is read from ``events`` (:func:`pinned_owner_key`), never taken from the caller. + Returns the approval and the resolved verdicts.""" if actor.get("kind") != "human": raise Rejected("spec_actor", f"{operation} is an owner act: the actor's kind is human, not {actor.get('kind')!r}") + pinned = pinned_owner_key(events) + if pinned is None: + raise Rejected("owner_key_unset", "the ledger pins no owner key; `factory owner --public KEY` (or the first `--owner-public`) sets it") + declared = [s.get("keyid") for s in (envelope.get("signatures") or []) if isinstance(s, dict)] if isinstance(envelope, dict) else [] + if declared and pinned not in declared: + raise Rejected("owner_key_mismatch", f"the approval is signed under key {str(declared[0])[:10]}, not the owner key the ledger pins ({pinned[:10]})") resolved = resolve_verdicts(events, spec, list(verdict_ids or []), spec_digest_value) if operation == "promote" else [] - approval = verify_approval(envelope, owner_public, spec, operation, verdict_ids=verdict_ids, spec_digest_value=spec_digest_value) + approval = verify_approval(envelope, bytes.fromhex(pinned), spec, operation, verdict_ids=verdict_ids, spec_digest_value=spec_digest_value) if approval["approver"]["id"] != actor.get("id"): raise Rejected("approval_actor", f"the approval was signed for {approval['approver']['id']!r}, not the actor {actor.get('id')!r}") for record in resolved: @@ -181,7 +255,8 @@ def new_spec(spec_id: str, capability: str, requirements: list[dict], footprint_ def spec_digest(spec: dict) -> str: - """The spec without its history, so two specs with the same content digest alike.""" + """The content digest: the parsed spec without its ``history``, so two files with the same content digest + alike however they are serialized. The ledger's events are the history; the file's copy is not covered.""" return digest({k: v for k, v in spec.items() if k != "history"}) @@ -200,7 +275,7 @@ def transition(spec: dict, operation: str, actor: dict, **detail) -> dict: if actor.get("kind") != "human": raise Rejected("spec_actor", f"{operation} is an owner act: the actor's kind is human, not {actor.get('kind')!r}") approval = detail.get("approval") - if not isinstance(approval, Approved): + if not _is_issued(approval): raise Rejected("spec_approval", f"{operation} needs the owner's verified approval (see `factory approve`); none given") if approval["operation"] != operation or approval["spec_id"] != spec["spec_id"] or approval["version"] != spec["version"]: raise Rejected("approval_mismatch", f"the approval covers {approval['operation']} of {approval['spec_id']} v{approval['version']}") diff --git a/tests/test_factory.py b/tests/test_factory.py index 4c9862a..aff25b8 100644 --- a/tests/test_factory.py +++ b/tests/test_factory.py @@ -283,6 +283,44 @@ def test_a_forging_candidate_is_refused_and_an_honest_one_passes(self): sealed.write_text("\n".join(lines) + "\n" + lines[-1][:20], encoding="utf-8") self.assertIn("torn", harness.verify_journal(sealed, "ab" * 32)) + def test_the_child_and_the_tests_runner_run_without_the_hosts_seed(self): + """M2 of the #164 verification: the candidate's process and the suite get the Build Thread's scrubbed + environment, never the host's whole one; the host's signing seed and a --seed-env variable are absent.""" + from unittest import mock + root = self.scratch / "probe" + root.mkdir() + (root / "envprobe.py").write_text( + "import os\n\ndef run(ctx, fixture):\n" + " return {'seed': len(os.environ.get('SYBERLABS_FACTORY_PROBE_SEED', ''))," + " 'default': len(os.environ.get('SYBERLABS_CERTIFICATE_SEED', ''))," + " 'path': bool(os.environ.get('PATH')), 'home': os.environ.get('HOME')}\n", encoding="utf-8") + home = ledger.Ledger(self.scratch / "ledger") + with mock.patch.dict(os.environ, {"SYBERLABS_FACTORY_PROBE_SEED": "a" * 64, "SYBERLABS_CERTIFICATE_SEED": "b" * 64}): + run_id = harness.new_run_id() + report = harness.record(root, home.run_path(run_id), "envprobe:run", run_id=run_id, revision="probe", + strip_env=("SYBERLABS_FACTORY_PROBE_SEED",)) + self.assertEqual(report["status"], "ok", report) + self.assertEqual((report["outcome"]["seed"], report["outcome"]["default"], report["outcome"]["path"]), (0, 0, True)) + self.assertNotEqual(report["outcome"]["home"], os.environ.get("HOME"), "HOME is the scratch home, not the host's") + probe = json.dumps([sys.executable, "-c", "import os, sys; sys.exit(len(os.environ.get('SYBERLABS_FACTORY_PROBE_SEED', ''))" + " + len(os.environ.get('SYBERLABS_CERTIFICATE_SEED', '')))"]) + tests = factory_cli._run_tests(root, probe, 60, strip_env=("SYBERLABS_FACTORY_PROBE_SEED",)) + self.assertEqual((tests["exit_code"], tests["full_suite"]), (0, True), tests["output_tail"]) + + def test_a_killed_run_delivers_no_journal(self): + """L1 of the #164 verification: a run stopped at its timeout has no end record and its journal does not + reach the ledger's runs/.""" + root = self.scratch / "sleeper" + root.mkdir() + (root / "sleep.py").write_text("import time\ntime.sleep(60)\n", encoding="utf-8") + home = ledger.Ledger(self.scratch / "ledger") + run_id = harness.new_run_id() + report = harness.record(root, home.run_path(run_id), str(root / "sleep.py"), run_id=run_id, revision="sleep", timeout=2) + self.assertEqual(report["status"], "killed", report) + self.assertIn("no end after", report["error"]) + self.assertFalse(home.run_path(run_id).exists(), "a killed run's journal is not delivered") + self.assertEqual(list((home.home / "runs").iterdir()), []) + def test_scrub(self): self.assertEqual(harness.scrub("ghp_abcdefghijklmnopqrstuvwxyz0123456789"), "") self.assertEqual(harness.scrub("GITHUB_TOKEN=whatever"), "GITHUB_TOKEN=") @@ -535,6 +573,7 @@ def test_verdicts_resolve_against_the_ledger(self): current = specmod.spec_digest(document) reviewer = {"kind": "model", "id": "gpt", "model": "gpt-5", "family": "openai"} events = [ + {"kind": "owner_key_set", "body": {"keyid": OWNER_PUBLIC.hex(), "previous": None, "rotation_digest": None}}, {"kind": "spec_changed", "body": {"spec_id": "order-path", "operation": "mutate", "variant_id": "var1", "actor": {"kind": "model", "id": "claude"}}}, {"kind": "spec_changed", "body": {"spec_id": "order-path", "operation": "review", "verdict_id": "ok1", @@ -554,17 +593,42 @@ def test_verdicts_resolve_against_the_ledger(self): with self.assertRaises(Rejected): specmod.resolve_verdicts(events, edited, ["ok1"]) envelope = specmod.sign_approval(specmod.approval_payload(document, "promote", ACTOR, verdict_ids=["ok1"]), OWNER_SEED) - approval, found = specmod.gate(document, "promote", ACTOR, events, envelope, OWNER_PUBLIC, verdict_ids=["ok1"]) + approval, found = specmod.gate(document, "promote", ACTOR, events, envelope, verdict_ids=["ok1"]) self.assertIsInstance(approval, specmod.Approved) self.assertEqual(found[0]["verdict_id"], "ok1") proposer_as_owner = {"kind": "human", "id": "claude"} own = specmod.sign_approval(specmod.approval_payload(document, "promote", proposer_as_owner, verdict_ids=["ok1"]), OWNER_SEED) with self.assertRaises(Rejected) as refused: - specmod.gate(document, "promote", proposer_as_owner, events, own, OWNER_PUBLIC, verdict_ids=["ok1"]) + specmod.gate(document, "promote", proposer_as_owner, events, own, verdict_ids=["ok1"]) self.assertEqual(refused.exception.code, "approval_not_independent") with self.assertRaises(Rejected) as refused: - specmod.gate(document, "promote", {"kind": "model", "id": "gpt"}, events, envelope, OWNER_PUBLIC, verdict_ids=["ok1"]) + specmod.gate(document, "promote", {"kind": "model", "id": "gpt"}, events, envelope, verdict_ids=["ok1"]) self.assertEqual(refused.exception.code, "spec_actor") + # The key is the ledger's, not the caller's: an approval under another keypair is refused however the gate + # is called, and a ledger that pins no key approves nothing. + other_seed, _ = generate() + under_another_key = specmod.sign_approval(specmod.approval_payload(document, "promote", ACTOR, verdict_ids=["ok1"]), other_seed) + with self.assertRaises(Rejected) as refused: + specmod.gate(document, "promote", ACTOR, events, under_another_key, verdict_ids=["ok1"]) + self.assertEqual(refused.exception.code, "owner_key_mismatch") + with self.assertRaises(Rejected) as refused: + specmod.gate(document, "promote", ACTOR, events[1:], envelope, verdict_ids=["ok1"]) + self.assertEqual(refused.exception.code, "owner_key_unset") + self.assertEqual(specmod.pinned_owner_key(events[1:]), None) + # ``Approved`` is a capability, not a marker: the constructor refuses without the module's token, and + # ``transition`` refuses a plain dictionary and an instance made around the constructor alike. + with self.assertRaises(Rejected) as refused: + specmod.Approved(dict(approval)) + self.assertEqual(refused.exception.code, "approval_forged") + candidate = json.loads(json.dumps(document)) + specmod.transition(candidate, "validate", ACTOR) + counterfeit = specmod.Approved.__new__(specmod.Approved) + dict.update(counterfeit, approval) + for forged in (dict(approval), counterfeit): + with self.assertRaises(Rejected) as refused: + specmod.transition(json.loads(json.dumps(candidate)), "promote", ACTOR, approval=forged, verdict_ids=["ok1"]) + self.assertEqual(refused.exception.code, "spec_approval") + self.assertEqual(json.loads(json.dumps(candidate))["state"], "candidate") def test_independence_is_by_provider_family(self): claude = {"kind": "model", "id": "a", "model": "claude-sonnet-4-5"} @@ -730,9 +794,14 @@ def test_end_to_end(self): code, out, err = self.run_cli("approve", "spec.json", "--verdict", "v1", "--actor", "human:tester", "--seed-env", "SYBERLABS_FACTORY_TEST_SEED", "--out", "approval.json", cwd=tree) self.assertEqual(code, 0, err) + code, out, err = self.run_cli("spec", "promote", "spec.json", "--verdict", "v1", "--actor", "human:tester", + "--approval", "approval.json", cwd=tree) + self.assertEqual(code, 2) + self.assertIn("owner_key_unset", err, "a ledger that pins no owner key promotes nothing") code, out, err = self.run_cli("spec", "promote", "spec.json", "--verdict", "v1", "--actor", "human:tester", "--approval", "approval.json", "--owner-public", "owner.pub", cwd=tree) self.assertEqual(code, 2) + self.assertIn("pinned (bootstrap", out, "the first --owner-public pins the key") self.assertIn("spec_verdict", err, "v1 is a string, not a review on the ledger") self.assertEqual(json.loads(spec_path.read_text(encoding="utf-8"))["state"], "candidate") run = lambda role: f"{sys.executable} {tree / 'proposers.py'} {role}" @@ -753,10 +822,9 @@ def test_end_to_end(self): code, out, err = self.run_cli("spec", "promote", candidate_spec, "--verdict", verdict_id, "--actor", "human:tester", "--approval", "approval.json", "--owner-public", "other.pub", cwd=tree) self.assertEqual(code, 2) - self.assertIn("approval_unverified", err, "an approval under another key is no approval") + self.assertIn("owner_key_mismatch", err, "the ledger pins the owner key; the caller cannot name another") code, out, err = self.run_cli("spec", "promote", candidate_spec, "--verdict", verdict_id, "--actor", "human:tester", - "--approval", "approval.json", "--owner-public", "owner.pub", - "--tickets", "tickets", "--baseline", run_a, "--owner", "tester", cwd=tree) + "--approval", "approval.json", "--tickets", "tickets", "--baseline", run_a, "--owner", "tester", cwd=tree) self.assertEqual(code, 0, err) self.assertIn("candidate -> promoted", out) self.assertIn("ticket ", out) @@ -770,7 +838,7 @@ def test_end_to_end(self): self.assertEqual(promotion["body"]["approval"]["event_hash"], approvals[0]["hash"], "the promotion cites the approval event") self.assertTrue(home.verify()) code, out, err = self.run_cli("spec", "promote", candidate_spec, "--verdict", verdict_id, "--actor", "human:tester", - "--approval", "approval.json", "--owner-public", "owner.pub", cwd=tree) + "--approval", "approval.json", cwd=tree) self.assertEqual(code, 2, "a promoted spec is not promoted twice") [auto] = list((tree / "tickets").glob("*.json")) auto_ticket = json.loads(auto.read_text(encoding="utf-8")) @@ -826,6 +894,75 @@ def test_end_to_end(self): self.assertEqual(code, 2) self.assertIn("run_id", err) + def test_the_owner_key_is_pinned_and_rotates_only_under_the_old_key(self): + """M1 of the #164 verification: the gate trusts the key the ledger pins, not the key the caller names. A + second keypair's approval is refused with and without --owner-public, a rotation needs the pinned key's + seed, and after a rotation the new key approves and the old one does not.""" + from unittest import mock + tree = self.scratch / "tree" + shutil.copytree(FIXTURE, tree) + (tree / "spec.json").write_text(json.dumps(specmod.new_spec("order-path", "ordering", [ + {"req_id": "R1", "text": "When quantity is positive, the system shall post one order."}], + ["ingest", "rules", "effects"], author=ACTOR)), encoding="utf-8") + code, _, err = self.run_cli("spec", "validate", "spec.json", cwd=tree) + self.assertEqual(code, 0, err) + owner_seed, owner_public = generate() + mine_seed, mine_public = generate() + (tree / "owner.pub").write_text(owner_public.hex(), encoding="utf-8") + (tree / "mine.pub").write_text(mine_public.hex(), encoding="utf-8") + with mock.patch.dict(os.environ, {"SYBERLABS_FACTORY_OWNER_SEED": owner_seed.hex(), "SYBERLABS_FACTORY_MINE_SEED": mine_seed.hex()}): + retire = lambda *extra: self.run_cli("spec", "retire", "spec.json", "--actor", "human:mateo", *extra, cwd=tree) + code, out, _ = self.run_cli("owner", cwd=tree) + self.assertEqual((code, "(unset)" in out), (1, True)) + code, _, err = self.run_cli("approve", "spec.json", "--operation", "retire", "--actor", "human:mateo", + "--seed-env", "SYBERLABS_FACTORY_OWNER_SEED", "--out", "owner.json", cwd=tree) + self.assertEqual(code, 0, err) + code, _, err = retire("--approval", "owner.json") + self.assertEqual((code, "owner_key_unset" in err), (2, True), err) + code, out, err = self.run_cli("owner", "--public", "owner.pub", cwd=tree) + self.assertEqual(code, 0, err) + self.assertIn("pinned (bootstrap)", out) + code, out, _ = self.run_cli("owner", "--public", "owner.pub", cwd=tree) + self.assertEqual((code, "already pinned" in out), (0, True)) + # The verifier's repro: my own keypair signs an approval, and I name my own key on argv. + code, _, err = self.run_cli("approve", "spec.json", "--operation", "retire", "--actor", "human:mateo", + "--seed-env", "SYBERLABS_FACTORY_MINE_SEED", "--out", "mine.json", cwd=tree) + self.assertEqual(code, 0, err) + for extra in (("--approval", "mine.json", "--owner-public", "mine.pub"), ("--approval", "mine.json")): + code, _, err = retire(*extra) + self.assertEqual(code, 2, err) + self.assertIn("owner_key_mismatch", err) + self.assertEqual(json.loads((tree / "spec.json").read_text(encoding="utf-8"))["state"], "candidate") + # Rotation without the pinned key's signature is refused; with it, the ledger moves to the new key. + code, _, err = self.run_cli("owner", "--public", "mine.pub", cwd=tree) + self.assertEqual((code, "owner_key_rotation" in err), (2, True), err) + code, _, err = self.run_cli("owner", "--public", "mine.pub", "--seed-env", "SYBERLABS_FACTORY_MINE_SEED", cwd=tree) + self.assertEqual((code, "owner_key_rotation" in err), (2, True), err) + code, out, err = self.run_cli("owner", "--public", "mine.pub", "--seed-env", "SYBERLABS_FACTORY_OWNER_SEED", cwd=tree) + self.assertEqual(code, 0, err) + self.assertIn("rotated from " + owner_public.hex()[:10], out) + code, out, _ = self.run_cli("owner", cwd=tree) + self.assertEqual((code, mine_public.hex() in out), (0, True)) + code, _, err = retire("--approval", "owner.json") + self.assertEqual((code, "owner_key_mismatch" in err), (2, True), "the key that was rotated out no longer approves") + code, out, err = retire("--approval", "mine.json") + self.assertEqual(code, 0, err) + self.assertIn("candidate -> retired", out) + home = ledger.Ledger(tree / ".syberlabs" / "factory") + pins = [e["body"] for e in home.events() if e["kind"] == "owner_key_set"] + self.assertEqual([(p["keyid"], p["previous"]) for p in pins], [(owner_public.hex(), None), (mine_public.hex(), owner_public.hex())]) + self.assertTrue(home.verify()) + rotation = home.home / "approvals" / f"{pins[1]['rotation_digest']}.json" + rotation.write_text(rotation.read_text(encoding="utf-8").replace(owner_public.hex(), mine_public.hex()), encoding="utf-8") + self.assertTrue(any("approvals/" in problem for problem in home.problems()), "an edited rotation is named by verify") + # In process, the same: ``set_owner_key`` is the only writer and refuses a seed that is not the pinned key's. + with self.assertRaises(Rejected) as refused: + home.set_owner_key(owner_public, seed=owner_seed) + self.assertEqual(refused.exception.code, "owner_key_rotation") + with self.assertRaises(Rejected) as refused: + home.set_owner_key(mine_public, seed=mine_seed) + self.assertEqual(refused.exception.code, "owner_key_pinned") + if __name__ == "__main__": unittest.main() From 9ff757349a30770ef34ca0e4116be58cada89c04 Mon Sep 17 00:00:00 2001 From: sykosyber Date: Mon, 2 Nov 2026 02:36:45 -0800 Subject: [PATCH 3/8] Factory goal gate, M3 of the #164 delta verification: read the pinned owner key through the ledger's verified lineage, not its newest owner_key_set; verify the ledger before the gate and again after the candidate's test suite; make set_owner_key one lock acquisition M3: `pinned_owner_key` took the newest `owner_key_set`, `problems()` checked a rotation file for existence and digest only, and `append` is public, so one appended line re-rooted the gate with `verify()` True. Now `spec.owner_key_lineage(events, load_rotation)` walks every `owner_key_set` in order: the first is the one bare bootstrap (`previous` None, no `rotation_digest`); every later one carries `previous` equal to the key pinned before it and a `rotation_digest` whose stored envelope `verify_rotation`s under that previous key; every keyid is 64-hex. Any violation is a named `owner_key_lineage` problem, `verify()` is False, and the lineage pins nothing: `pinned_owner_key`, `Ledger.owner_key`, `spec.gate`, `factory owner` and `set_owner_key` refuse with `owner_key_lineage` rather than falling back to the last or an earlier key, so a second bare bootstrap is a violation, not a re-pin. `Ledger.load_rotation` supplies the envelopes; `gate` takes it as `load_rotation`, and the key still comes from the events alone. `spec promote|canonize|retire` verify the ledger (`problems()`) before the gate reads it and refuse `ledger_corrupt`; `factory check` verifies it once more after `_run_tests` and before `record_attestation`, against the head its own run record left, and refuses `ledger_corrupt` if it moved or has problems. `set_owner_key` reads the pinned key and appends under one acquisition of the journal lock (`_append`). Tests: the verifier's four shapes (bare appended attacker pin; rotation signed by the new key; stale `previous`; malformed keyid last) each leave the chain intact and each give `verify()` False, an `owner_key_lineage` problem, an `owner_key_lineage` refusal from the gate for the forged and the honest approval alike, a refused rotation, and `spec retire` exit 2; the honest bootstrap -> rotation -> retire path still passes; a test suite that appends to the ledger refuses the check at `ledger_corrupt` with nothing attested. The M1 test's edited-rotation tail now expects the lineage break. `tests/test_factory.py` is 50 tests; `docs/FACTORY.md` states the lineage rule; GAPS 65 (1) says the pin is as strong as the verified lineage and the boundary that remains is (3), a rewrite of the whole chain, for the deferred tlog anchoring. Co-Authored-By: Claude Fable 5.1 --- docs/FACTORY.md | 25 +++++++- spec/GAPS.md | 2 +- syberlabs/factory/cli.py | 12 +++- syberlabs/factory/ledger.py | 93 ++++++++++++++++++--------- syberlabs/factory/spec.py | 89 +++++++++++++++++++------ tests/test_factory.py | 125 ++++++++++++++++++++++++++++++++++-- 6 files changed, 287 insertions(+), 59 deletions(-) diff --git a/docs/FACTORY.md b/docs/FACTORY.md index 6576649..35d8fe0 100644 --- a/docs/FACTORY.md +++ b/docs/FACTORY.md @@ -12,7 +12,7 @@ architecture conformance, spec-driven development, attestation, ledger storage) are in the architecture plan this slice was built from. This page is what the repository does today. Package: `syberlabs/factory/`. Standard library only. `syberlabs` still does not import `syberwork`. -Claim ceiling for this page: **implemented** and **tested** (`tests/test_factory.py`, 48 tests, and the +Claim ceiling for this page: **implemented** and **tested** (`tests/test_factory.py`, 50 tests, and the CLI run below). Nothing here is measured, deployed or externally validated. ## The v0 slice @@ -94,7 +94,28 @@ signature under `approvals/` and cites it from the new `owner_key_set`, and `ver artifact; a rotation the pinned key did not sign is refused (`owner_key_rotation`). The verifier's repro of #164 (generate a keypair, approve with it, promote with `--owner-public mine.pub`) is refused at `owner_key_mismatch`, and `tests/test_factory.py::CliTests::test_the_owner_key_is_pinned_and_rotates_only_under_the_old_key` -pins that. `Approved`, the record `transition` takes for a gated operation, is made by `verify_approval` only: +pins that. + +**The lineage rule.** The pinned key is read through the ledger's verified lineage, never from the newest +`owner_key_set` alone (`spec.owner_key_lineage`, `Ledger.owner_key_lineage`). Walking every `owner_key_set` in +order: the first is the one bare bootstrap (`previous` null, no `rotation_digest`); every later one is a +rotation whose `previous` is exactly the key pinned before it, whose `rotation_digest` names a stored envelope +under `approvals/`, and whose envelope verifies (`verify_rotation`) under that previous key; every keyid is a +64-hex public key. Any violation is named by `problems` as `owner_key_lineage`, `verify` is false, and the +ledger pins nothing: `spec.gate`, `factory owner` and `set_owner_key` refuse with `owner_key_lineage` rather +than falling back to the last or an earlier key, so a second bare bootstrap is a violation, not a re-pin. The +delta verification's four shapes (an `owner_key_set` appended through the public `append` with an attacker's +key; a rotation signed by the new key instead of the pinned one; a rotation whose `previous` is a key rotated +out earlier; a malformed keyid as the last event) each leave the hash chain intact and each are refused this +way, in `CliTests::test_the_owner_key_is_the_verified_lineage_not_the_newest_event`. `spec promote|canonize|retire` +verify the ledger before the gate reads it (`ledger_corrupt`), and `factory check` verifies it once more after +the candidate's test suite ran and before anything is attested, against the head its own run record left, so a +line a candidate manages to append during its suite refuses the check (`ledger_corrupt`; +`BuildThreadCheck::test_a_ledger_that_changes_under_the_test_suite_refuses_the_check`). `set_owner_key` reads +the pinned key and appends under one acquisition of the journal lock, so two bootstraps racing on an empty +ledger cannot both land. What the lineage does not cover is an attacker who rewrites the whole chain +consistently; that is the unanchored write boundary of `spec/GAPS.md` 65 (3), and anchoring the head in +`tlog`/`witness` is the deferred fix. `Approved`, the record `transition` takes for a gated operation, is made by `verify_approval` only: its constructor demands a module-private token, and `transition` checks the token, so neither a dictionary nor an instance made around the constructor passes the gate. diff --git a/spec/GAPS.md b/spec/GAPS.md index f545038..6585b97 100644 --- a/spec/GAPS.md +++ b/spec/GAPS.md @@ -126,4 +126,4 @@ The schemas describe SyberWork as it behaves. They are not enforced at runtime e 63. **The GitHits pilot's example pacing and license reading rest on GitHits' documentation, not on observed traffic.** (1) The host paces `example` calls to one per 40 s per host (`syberlabs/githits_pace.py`, called by the launcher entry); GitHits' limit is per organization, so two hosts, or an operator's own `syberlabs githits example` (not paced), share the organization's budget without seeing each other's slots. (2) A loopback base URL is not paced unless `SYBERLABS_GITHITS_PACE_SECONDS` asks: a loopback proxy that forwards to GitHits would go unpaced. (3) Calls queued behind several others wait one interval each, so a Bash tool timeout shorter than the queue ends a call before it is sent, and the host then flags it `githits_unrecorded`. (4) The time file is plain text a process of the same user can rewrite; it paces cooperating processes and is no security boundary. (5) The license reading admits an example's `References`/`Sources` links by their `(SPDX)` and passes an example with neither code (a fenced, indented or HTML block) nor a source; inline code in prose is not read as code, and the three documented shapes (`complete`, `degraded`, `no_example` in the pinned OpenAPI document) are the only evidence of what real responses look like until the first live example is recorded. (6) The engineering smoke pins Claude Code 2.1.312 exactly because the host and the pilot VM run it; that version's flags were not re-checked here. 64. **The GitHits launcher fails closed before the network, and the treatment runs on a hooked API lane; neither is verified live, and other lookups on a `--bare` lane are still caught only after the fact.** The live canary of 2026-10-30 (Claude Code 2.1.312 on a Freestyle Linux VM) settled 56 (2): a `--settings` `PreToolUse` hook does not run under `--bare`, so `propose --claude-code --bare --githits` let the model run the launcher with no guard, and the client sent the lookup (`sent: true`) before the host stopped the run `provider_guard_inactive`. Now the launcher's entry sends nothing without claiming the hook's MAC-verified decision for its exact argv (`query_guard.claim_launch`; refused calls are recorded `status: unguarded`, `sent: false`), and `--githits` refuses `--bare` and runs on `--lane api-hooked` (the API key without `--bare`, a fresh `CLAUDE_CONFIG_DIR` and home per call, `--disable-slash-commands`; `docs/CLAUDE_CODE.md`). Not solved: (1) a decision is bound to the launcher's arguments (their SHA-256) and claimed once, not to a tool use id, which the launcher cannot see; a process holding the per-call key (a stdio MCP server, a shell under `--allow-code-tools-with-mcp`) can still sign a decision for its own arguments, as it could before; (2) the hook's words and the launcher's argv agree for plain words and quoted strings under a POSIX shell; a shell or platform that hands over different bytes (Git Bash's argument conversion to a Windows process, a non-UTF-8 byte) refuses a legitimate lookup (fail closed), which no live run has exercised; (3) WebSearch, WebFetch and `--mcp-config` (`mcp__githits__*`) lookups on a `--bare` lane have no pre-send gate: the hook does not run, so they still leave and are flagged `unguarded` afterwards; only `--githits` refuses `--bare`, and `api-hooked` or a login lane is where those tools are guarded; (4) `api-hooked` has run only against the stand-in `claude`: whether 2.1.312 with an empty config directory and home starts headless on `ANTHROPIC_API_KEY` (`apiKeySource`) and runs the hook is for its first live call, and the flags were read from 2.1.309's `--help` because 2.1.312's was not on the building machine; managed (policy) settings still load, `--setting-sources` has no value meaning `--settings` alone, `USERPROFILE` moves only on Windows, and the worktree's memory files (`CLAUDE.md`) are read in both arms, so the lane needs `--trusted-tree`; (5) the example license parser now reads any ATX or bold heading that names a source or reference ("## Source code" included) as a sources section and a fenced or indented block inside a blockquote as code, both of which can only drop more examples (fail closed); how often that drops a usable GitHits example is not measured; (6) the default deny-list (`SyberLabs`, `sykosyber`, `pypi:syberwork`, `deepwiki.com`, `deepwiki.org`) detects a fork of a SyberLabs repository only by its name (`githits.FORK_NAMES`) in a result's URL or a target, so a renamed fork, a vendored copy, or SyberLabs code mirrored under another name and site still passes, and no mirror or front-end other than DeepWiki is listed. -65. **The factory's goal gate is an owner signature, not yet a kernel approval; the candidate's process still shares memory with its recorder; the behavior-change label is per contract.** `factory-goal-gate` (2026-11-02, on the factory slice of #154) closes the slice's verification findings: `spec promote`, `canonize` and `retire` need a human actor and an approval that verifies (`factory approve` signs it with the owner's seed through the certificate module's Ed25519 and DSSE; `spec promote` verifies it under the owner key the ledger pins (`owner_key_set`; `factory owner`), never a key the caller names, resolves every `--verdict` to a ledger `review` that accepted the very variant on disk, refuses an approver who proposed or reviewed it, stores the approval under `approvals/` and cites its `approval_recorded` hash from the `spec_changed`); every artifact load checks the file against the digest the ledger recorded and `verify` covers artifacts, so an edited golden journal refuses the check instead of becoming its baseline; the candidate runs under `python -I` in a host-owned scratch directory, is never told the ledger's path, writes a journal sealed per record under a per-run key the parent holds, reports over a nonce-bound private pipe, and the parent reads the `end` record itself and refuses a journal with no end, a planted line or a mismatching report; `verify` recomputes the policy from the evidence and `signed: true` needs a verifying signature; reviewer independence is the provider family the command declared, not the caller's name, and an unrecorded family refuses; subprocess argv, cwd, socket addresses and the tests tail are scrubbed of credential shapes; the viewer builds its DOM with `textContent` and carries no payloads; ledger appends use the kernel journal's lock, fsync and torn-tail repair, and the projection rebuilds when the log moved; the tests check honours the contract's timeout, `full_suite` means the suite ran to completion, and a timed-out suite or recording has its process tree stopped; after the independent verification of #164 (2026-11-02), the candidate's process and the test suite run under the Build Thread's scrubbed environment without the host's signing seed or the check's `--seed-env` variable, a killed run's journal is not delivered, and `Approved` is constructible by `verify_approval` only. What remains: (1) the approval is the owner's signature over the spec's content digest, not an `approved` event on a kernel goal case, because the factory has no case to hang one on; the trust model is exactly this: promotion is bound to the owner key the ledger pins, not to the caller of the host CLI; the pin's bootstrap (`factory owner --public KEY`, or the first `--owner-public` on a ledger that pins none) is the one unsigned act, done by the operator by hand, so whoever pins first on an empty ledger owns it (a Class C act), after which only the pinned key approves (`owner_key_mismatch` otherwise, `owner_key_unset` before any pin) and only the pinned key rotates (`owner_key_rotation` otherwise); the ledger event is the citation the consolidation's §1.2 asks for, the journal hash is not; (2) io observation runs in the candidate's process, so code there can reach `_factory_harness._CURRENT[-1]` and its key through `sys.modules` and write records the seal accepts, or call the recorder's own `__exit__`; the seal and the channel raise the cost of a forgery, they are not a sandbox, and the recommendation on the open owner question stands: evidence with a person in the path, not the auto class; (3) a candidate that learns the ledger's absolute path from the contract in its worktree can still write to it between the check's two verifications only by forging a consistent unkeyed chain and matching digests, which `verify` does not distinguish from an honest ledger across runs; anchoring the chain head in `tlog`/`witness` is the fix; (4) the behavior-change label is `--behavior-change` on the check's argv, per contract, not a field of the ticket; (5) `independence` reads the model the command declared, so a command that lies about its model passes as it does for `model_usage`; (6) `verify_journal` reads text, so a journal whose line endings were rewritten verifies by content while the ledger's byte digest refuses it, which is the intended division, and the approval likewise covers the spec's content digest (parsed, `history` excluded), so a re-serialized file is the same spec and an edit to the file's `history` after signing is not covered, the ledger's `spec_changed` events being the history of record; (7) before this packet the ledger had no cross-process lock (two commands on one home could fork the chain, detected by `append` but not prevented) and `docs/FACTORY.md` said 18 tests where the file defined 35; both are fixed here. The consolidation's other C1 items (`serves`, `mission_ref`, `done_when` on specs, mandatory `human_owner` on tickets, `promote` renamed `pass`, `tickets.py`, `codemap.py`) are not in this packet. +65. **The factory's goal gate is an owner signature, not yet a kernel approval; the candidate's process still shares memory with its recorder; the behavior-change label is per contract.** `factory-goal-gate` (2026-11-02, on the factory slice of #154) closes the slice's verification findings: `spec promote`, `canonize` and `retire` need a human actor and an approval that verifies (`factory approve` signs it with the owner's seed through the certificate module's Ed25519 and DSSE; `spec promote` verifies it under the owner key the ledger pins (`owner_key_set`; `factory owner`), never a key the caller names, resolves every `--verdict` to a ledger `review` that accepted the very variant on disk, refuses an approver who proposed or reviewed it, stores the approval under `approvals/` and cites its `approval_recorded` hash from the `spec_changed`); every artifact load checks the file against the digest the ledger recorded and `verify` covers artifacts, so an edited golden journal refuses the check instead of becoming its baseline; the candidate runs under `python -I` in a host-owned scratch directory, is never told the ledger's path, writes a journal sealed per record under a per-run key the parent holds, reports over a nonce-bound private pipe, and the parent reads the `end` record itself and refuses a journal with no end, a planted line or a mismatching report; `verify` recomputes the policy from the evidence and `signed: true` needs a verifying signature; reviewer independence is the provider family the command declared, not the caller's name, and an unrecorded family refuses; subprocess argv, cwd, socket addresses and the tests tail are scrubbed of credential shapes; the viewer builds its DOM with `textContent` and carries no payloads; ledger appends use the kernel journal's lock, fsync and torn-tail repair, and the projection rebuilds when the log moved; the tests check honours the contract's timeout, `full_suite` means the suite ran to completion, and a timed-out suite or recording has its process tree stopped; after the independent verification of #164 (2026-11-02), the candidate's process and the test suite run under the Build Thread's scrubbed environment without the host's signing seed or the check's `--seed-env` variable, a killed run's journal is not delivered, and `Approved` is constructible by `verify_approval` only. What remains: (1) the approval is the owner's signature over the spec's content digest, not an `approved` event on a kernel goal case, because the factory has no case to hang one on; the trust model is exactly this: promotion is bound to the owner key the ledger pins, not to the caller of the host CLI; the pin's bootstrap (`factory owner --public KEY`, or the first `--owner-public` on a ledger that pins none) is the one unsigned act, done by the operator by hand, so whoever pins first on an empty ledger owns it (a Class C act), after which only the pinned key approves (`owner_key_mismatch` otherwise, `owner_key_unset` before any pin) and only the pinned key rotates (`owner_key_rotation` otherwise); after the delta verification of the pin (2026-11-02, M3) the key is read through the ledger's verified lineage, not its newest `owner_key_set`: one bare bootstrap, then rotations whose `previous` is the key pinned before them and whose stored envelope verifies under it, so an appended pin, a rotation the pinned key did not sign, a stale `previous` or a malformed keyid fails `verify` and refuses the gate at `owner_key_lineage` with no fallback to an earlier key, `spec promote|canonize|retire` verify the ledger before the gate reads it, `factory check` verifies it again after the test suite and before attesting, and `set_owner_key` reads and appends under one lock; the pin is therefore as strong as the ledger's verified lineage, and the boundary that remains is (3), an attacker who can rewrite the whole chain consistently, which the deferred `tlog`/`witness` anchoring closes; the ledger event is the citation the consolidation's §1.2 asks for, the journal hash is not; (2) io observation runs in the candidate's process, so code there can reach `_factory_harness._CURRENT[-1]` and its key through `sys.modules` and write records the seal accepts, or call the recorder's own `__exit__`; the seal and the channel raise the cost of a forgery, they are not a sandbox, and the recommendation on the open owner question stands: evidence with a person in the path, not the auto class; (3) a candidate that learns the ledger's absolute path from the contract in its worktree can still write to it between the check's two verifications only by forging a consistent unkeyed chain and matching digests, which `verify` does not distinguish from an honest ledger across runs; anchoring the chain head in `tlog`/`witness` is the fix; (4) the behavior-change label is `--behavior-change` on the check's argv, per contract, not a field of the ticket; (5) `independence` reads the model the command declared, so a command that lies about its model passes as it does for `model_usage`; (6) `verify_journal` reads text, so a journal whose line endings were rewritten verifies by content while the ledger's byte digest refuses it, which is the intended division, and the approval likewise covers the spec's content digest (parsed, `history` excluded), so a re-serialized file is the same spec and an edit to the file's `history` after signing is not covered, the ledger's `spec_changed` events being the history of record; (7) before this packet the ledger had no cross-process lock (two commands on one home could fork the chain, detected by `append` but not prevented) and `docs/FACTORY.md` said 18 tests where the file defined 35; both are fixed here. The consolidation's other C1 items (`serves`, `mission_ref`, `done_when` on specs, mandatory `human_owner` on tickets, `promote` renamed `pass`, `tickets.py`, `codemap.py`) are not in this packet. diff --git a/syberlabs/factory/cli.py b/syberlabs/factory/cli.py index 6842868..f1cc515 100644 --- a/syberlabs/factory/cli.py +++ b/syberlabs/factory/cli.py @@ -527,6 +527,12 @@ def _check(args, home: ledger.Ledger) -> int: evidence["tests"] = _run_tests(root, args.tests_argv, args.tests_timeout, strip_env=strip_env) print(f"tests: {' '.join(harness.mask(a) for a in evidence['tests']['argv'])} -> exit {evidence['tests']['exit_code']}" f" in {evidence['tests']['seconds']}s") + # The test suite ran in the worktree too, so the ledger is verified once more, against the head the run's + # own record left it at, before anything is attested over it; a line that reached the log in the meantime + # (an owner_key_set, a note, anything) refuses the check instead of being attested around. + final = home.events() + if home.head(final) != run_event["hash"] or len(final) != len(before) + 1 or home.problems(final): + raise Rejected("ledger_corrupt", "the ledger changed or stopped verifying while the candidate's checks ran; refusing to attest") builder_text = args.builder or os.environ.get("SYBERLABS_CANDIDATE") or "operator" parts = builder_text.split(":") builder = {"agent": parts[0], "model": parts[1] if len(parts) > 1 else None, "session": parts[2] if len(parts) > 2 else None, @@ -905,6 +911,10 @@ def _spec(args, home: ledger.Ledger) -> int: if not args.approval: raise Rejected("spec_approval", f"{args.operation} is an owner act: pass --approval FILE (from `factory approve`)") envelope = _read_json(args.approval, "approval") + problems = home.problems() + if problems: + more = f" (and {len(problems) - 1} more)" if len(problems) > 1 else "" + raise Rejected("ledger_corrupt", f"the ledger does not verify, so no key on it is trusted: {problems[0]}{more}") if args.owner_public: # Bootstrap only: the first key a ledger sees is pinned. A pinned ledger takes the same key as a no-op # and refuses any other here; rotation is `factory owner --public NEW --seed-env OLD`, never this flag. @@ -917,7 +927,7 @@ def _spec(args, home: ledger.Ledger) -> int: raise Rejected("owner_key_mismatch", f"the ledger pins owner key {pinned[:10]}, not {public.hex()[:10]}; " "rotate with `factory owner --public NEW --seed-env OLD`") approval, resolved = specmod.gate(document, args.operation, actor, home.events(), envelope, - verdict_ids=args.verdict, spec_digest_value=before_digest) + verdict_ids=args.verdict, spec_digest_value=before_digest, load_rotation=home.load_rotation) detail["approval"] = approval detail["spec_digest"] = before_digest detail["resolved_verdicts"] = resolved diff --git a/syberlabs/factory/ledger.py b/syberlabs/factory/ledger.py index 7ffea3c..381fdc0 100644 --- a/syberlabs/factory/ledger.py +++ b/syberlabs/factory/ledger.py @@ -20,7 +20,11 @@ The owner's public key is pinned here (``owner_key_set``): the first such event is the ledger's trust root and every later one is a rotation signed by the key it replaces (``set_owner_key``), so the goal gate verifies -approvals under a key the ledger names rather than one the caller passes. +approvals under a key the ledger names rather than one the caller passes. The pin is read through its lineage +(``owner_key_lineage``, ``spec.owner_key_lineage``), not from the newest event: ``problems`` walks every +``owner_key_set`` in order, demands one bare bootstrap and then rotations whose ``previous`` is the key pinned +before them and whose stored envelope verifies under that key, so an ``owner_key_set`` appended around +``set_owner_key`` makes the ledger fail ``verify`` and pins nothing rather than re-rooting the gate. Appends go through the kernel journal's writer (``syberlabs.journal.Journal``): a cross-process lock (``flock`` or ``msvcrt.locking``), flush and fsync per record, and truncation of a torn final line before the next read. @@ -119,7 +123,7 @@ def problems(self, events: list[dict] | None = None) -> list[str]: events = self.events() if events is None else events if not _verify_chain(events): return ["the event chain does not verify"] - found = [] + found = [f"owner_key_lineage: {violation}" for violation in self.owner_key_lineage(events)[1]] for event in events: body, kind = event["body"], event["kind"] try: @@ -157,17 +161,21 @@ def verify(self, events: list[dict] | None = None) -> bool: return not self.problems(events) def append(self, kind: str, body: dict) -> dict: + with self._locked() as writer: + return self._append(writer, self._read(writer), kind, body) + + def _append(self, writer: kernel_journal.Journal, events: list[dict], kind: str, body: dict) -> dict: + """Append under a lock the caller holds, over the ``events`` it read under that same lock, so a + read-then-append (``set_owner_key``) is one acquisition and nothing slips in between.""" if kind not in KINDS: raise Rejected("ledger_kind", f"unknown event kind {kind!r}") - with self._locked() as writer: - events = self._read(writer) - if not _verify_chain(events): - raise Rejected("ledger_corrupt", "the hash chain does not verify; refusing to append to an edited ledger") - event = {"seq": len(events) + 1, "kind": kind, "body": body, "at": int(time.time() * 1_000_000), - "previous": events[-1]["hash"] if events else GENESIS} - event["hash"] = event_digest(event) - # The kernel journal's append: flushed, fsynced, and refused if another writer slipped in between. - writer._write(self.log, event) + if not _verify_chain(events): + raise Rejected("ledger_corrupt", "the hash chain does not verify; refusing to append to an edited ledger") + event = {"seq": len(events) + 1, "kind": kind, "body": body, "at": int(time.time() * 1_000_000), + "previous": events[-1]["hash"] if events else GENESIS} + event["hash"] = event_digest(event) + # The kernel journal's append: flushed, fsynced, and refused if another writer slipped in between. + writer._write(self.log, event) return event # -- artifacts ----------------------------------------------------------------------------------------------- @@ -302,34 +310,59 @@ def record_approval(self, envelope: dict, approval: dict) -> dict: # -- the owner key ------------------------------------------------------------------------------------------- + def load_rotation(self, sha: str) -> dict | None: + """The stored rotation envelope ``approvals/.json`` when it is there and digests to its name; + None when it is missing, unreadable or altered. The lineage walk decides what that means.""" + if not isinstance(sha, str) or not sha or any(c not in "0123456789abcdef" for c in sha): + return None + path = self.home / "approvals" / f"{sha}.json" + try: + envelope = json.loads(path.read_text(encoding="utf-8")) + except (OSError, ValueError): + return None + return envelope if isinstance(envelope, dict) and digest(envelope) == sha else None + + def owner_key_lineage(self, events: list[dict] | None = None) -> tuple[str | None, list[str]]: + """``(pinned key, violations)`` from :func:`spec.owner_key_lineage` over this ledger's events, its stored + rotations supplying the envelopes: the first ``owner_key_set`` is the one bare bootstrap, every later one + carries ``previous`` equal to the key pinned before it and a ``rotation_digest`` whose envelope verifies + under that previous key, and every keyid is well-formed hex. Any violation names the event and leaves + the ledger pinning nothing; ``problems`` reports each one as ``owner_key_lineage``.""" + return specmod.owner_key_lineage(self.events() if events is None else events, self.load_rotation) + def owner_key(self, events: list[dict] | None = None) -> str | None: - """The owner's public key (hex) this ledger pins, or None before the first ``owner_key_set``.""" - return specmod.pinned_owner_key(self.events() if events is None else events) + """The owner's public key (hex) this ledger pins through a verified lineage, None before the first + ``owner_key_set``; refused (``owner_key_lineage``) when the lineage does not verify.""" + return specmod.pinned_owner_key(self.events() if events is None else events, self.load_rotation) def set_owner_key(self, public: bytes, *, seed: bytes | None = None) -> dict: """Pin ``public`` as the owner key. On a ledger that pins none this is the bootstrap: one event, no signature, and from then on the goal gate trusts this key and no other. On a ledger that pins a key it is a rotation and needs ``seed``, the seed of the key pinned now: the handover is signed by that key (``spec.sign_rotation``), verified, stored under ``approvals/`` and cited by the event. Refused - when the seed is not the pinned key's (``owner_key_rotation``) or the key is already pinned - (``owner_key_pinned``). Returns the event.""" + when the seed is not the pinned key's (``owner_key_rotation``), the key is already pinned + (``owner_key_pinned``) or the lineage so far does not verify (``owner_key_lineage``). The read of the + pinned key and the append are one lock acquisition, so two bootstraps racing on an empty ledger + cannot both land. Returns the event.""" from syberlabs.ed25519 import public_from_seed keyid = public.hex() - current = self.owner_key() - if current is None: - return self.append("owner_key_set", {"keyid": keyid, "previous": None, "rotation_digest": None}) - if current == keyid: - raise Rejected("owner_key_pinned", f"the ledger already pins {keyid[:10]}") - if seed is None: - raise Rejected("owner_key_rotation", f"the ledger pins {current[:10]}; rotating to {keyid[:10]} needs that key's seed (--seed-env)") - if public_from_seed(seed).hex() != current: - raise Rejected("owner_key_rotation", f"the seed given is not the pinned owner key's ({current[:10]}); only the pinned key rotates") - envelope = specmod.sign_rotation(specmod.rotation_payload(bytes.fromhex(current), public), seed) - specmod.verify_rotation(envelope, bytes.fromhex(current), public) - sha = digest(envelope) - (self.home / "approvals" / f"{sha}.json").write_text(canonical(envelope), encoding="utf-8") - return self.append("owner_key_set", {"keyid": keyid, "previous": current, "rotation_digest": sha}) + with self._locked() as writer: + events = self._read(writer) + current = specmod.pinned_owner_key(events, self.load_rotation) + if current is None: + return self._append(writer, events, "owner_key_set", {"keyid": keyid, "previous": None, "rotation_digest": None}) + if current == keyid: + raise Rejected("owner_key_pinned", f"the ledger already pins {keyid[:10]}") + if seed is None: + raise Rejected("owner_key_rotation", f"the ledger pins {current[:10]}; rotating to {keyid[:10]} needs that key's seed (--seed-env)") + if public_from_seed(seed).hex() != current: + raise Rejected("owner_key_rotation", f"the seed given is not the pinned owner key's ({current[:10]}); only the pinned key rotates") + envelope = specmod.sign_rotation(specmod.rotation_payload(bytes.fromhex(current), public), seed) + specmod.verify_rotation(envelope, bytes.fromhex(current), public) + sha = digest(envelope) + (self.home / "approvals" / f"{sha}.json").write_text(canonical(envelope), encoding="utf-8") + return self._append(writer, events, "owner_key_set", {"keyid": keyid, "previous": current, "rotation_digest": sha}) # -- the projection ----------------------------------------------------------------------------------------- @@ -455,4 +488,4 @@ def describe(self) -> dict: "runs": sum(1 for e in events if e["kind"] in RUN_KINDS), "attestations": sum(1 for e in events if e["kind"] == "attested"), "approvals": sum(1 for e in events if e["kind"] == "approval_recorded"), - "owner_key": self.owner_key(events), "head": self.head(events)} + "owner_key": self.owner_key_lineage(events)[0], "head": self.head(events)} diff --git a/syberlabs/factory/spec.py b/syberlabs/factory/spec.py index 07c17cc..cc2b313 100644 --- a/syberlabs/factory/spec.py +++ b/syberlabs/factory/spec.py @@ -19,11 +19,15 @@ caller cannot hand it a dictionary of its own. The owner's public key is pinned on the ledger, not supplied by the caller: an ``owner_key_set`` event names -it (:func:`pinned_owner_key`), the first one is the trust root of that ledger (bootstrap, written once), and -a later one is a rotation the previous key signed (:func:`verify_rotation`). :func:`gate` verifies every -approval under the pinned key only; a ledger with no pinned key refuses (``owner_key_unset``) and an approval -under any other key refuses (``owner_key_mismatch``), whoever runs the host command. The signing seed never -enters this module. A kernel ``approved`` event on a goal case is the intended source of this approval once +it, the first one is the trust root of that ledger (bootstrap, written once), and a later one is a rotation +the previous key signed (:func:`verify_rotation`). The pin is read through its lineage, never from the last +event alone: :func:`owner_key_lineage` walks every ``owner_key_set`` in order and verifies each handover under +the key pinned before it, so an appended pin, a rotation the pinned key did not sign, a stale ``previous`` or +a malformed key invalidates the lineage instead of re-rooting the gate (``owner_key_lineage``). :func:`gate` +verifies every approval under the lineage's key only; a ledger with no pinned key refuses (``owner_key_unset``), +an invalid lineage refuses (``owner_key_lineage``, never falling back to an earlier key) and an approval under +any other key refuses (``owner_key_mismatch``), whoever runs the host command. The signing seed never enters +this module. A kernel ``approved`` event on a goal case is the intended source of this approval once the factory has a case to hang it on; until then the signature stands in, and ``spec/GAPS.md`` records the gap. @@ -93,15 +97,56 @@ def _is_issued(approval: object) -> bool: return isinstance(approval, Approved) and getattr(approval, "_issued", None) is _ISSUED -def pinned_owner_key(events: list[dict]) -> str | None: - """The owner's public key (hex) the ledger pins: the newest ``owner_key_set`` event's ``keyid``, or None - when the ledger has pinned none. The first such event is the ledger's trust root; every later one is a - rotation the previous key signed (``previous`` and ``rotation_digest`` on the event).""" - for event in reversed(events): - if event.get("kind") == "owner_key_set": - keyid = (event.get("body") or {}).get("keyid") - return keyid if isinstance(keyid, str) and _HEX_KEY.match(keyid) else None - return None +def owner_key_lineage(events: list[dict], load_rotation=None) -> tuple[str | None, list[str]]: + """Walk every ``owner_key_set`` in ``events`` in order and return ``(pinned key, violations)``: the key the + verified lineage ends on (None when the ledger pins none) and every way the lineage fails. The first event + is the one unsigned bootstrap: ``previous`` None, no ``rotation_digest``. Every later one is a rotation: + ``previous`` is the key pinned right before it, ``rotation_digest`` names a stored envelope + (``load_rotation(digest)``, the ledger's ``approvals/``; None when missing or altered) that + :func:`verify_rotation` accepts under that previous key, and every ``keyid`` is a 64-hex public key. A + second bare bootstrap, a rotation signed by the new key, a stale ``previous`` and a malformed key are each + a violation. With violations the lineage is invalid and the key returned is None: a broken lineage pins + nothing rather than its last or an earlier key. Without a ``load_rotation`` no rotation can be checked, so + a rotated ledger read that way is invalid, by design.""" + pinned, violations = None, [] + for event in events: + if not isinstance(event, dict) or event.get("kind") != "owner_key_set": + continue + where = f"owner_key_set at seq {event.get('seq', '?')}" + body = event.get("body") if isinstance(event.get("body"), dict) else {} + keyid, previous, rotation = body.get("keyid"), body.get("previous"), body.get("rotation_digest") + if not (isinstance(keyid, str) and _HEX_KEY.match(keyid)): + violations.append(f"{where}: keyid is not a 64-hex public key") + continue + if pinned is None: + if previous is not None or rotation is not None: + violations.append(f"{where}: the first pin is the bootstrap and carries no previous key or rotation") + else: + if previous != pinned: + violations.append(f"{where}: previous {str(previous)[:10]!r} is not the key pinned before it ({pinned[:10]})") + if not (isinstance(rotation, str) and _HEX_KEY.match(rotation)): # a sha256 digest has the key's shape + violations.append(f"{where}: a second pin is a rotation and names a rotation_digest; a bare pin does not re-root the ledger") + else: + envelope = load_rotation(rotation) if load_rotation is not None else None + if envelope is None: + violations.append(f"{where}: rotation {rotation[:12]} is missing, altered or unavailable") + else: + try: + verify_rotation(envelope, bytes.fromhex(pinned), bytes.fromhex(keyid)) + except Rejected as exc: + violations.append(f"{where}: {exc.detail}") + pinned = keyid + return (None if violations else pinned), violations + + +def pinned_owner_key(events: list[dict], load_rotation=None) -> str | None: + """The owner's public key (hex) the ledger pins, read through its verified lineage + (:func:`owner_key_lineage`): None when the ledger has pinned none, refused (``owner_key_lineage``) when the + lineage does not verify. Never the last event's key on its own, and never an earlier key as a fallback.""" + pinned, violations = owner_key_lineage(events, load_rotation) + if violations: + raise Rejected("owner_key_lineage", "the ledger's owner-key lineage does not verify: " + "; ".join(violations)) + return pinned def rotation_payload(previous: bytes, next_key: bytes) -> dict: @@ -204,15 +249,17 @@ def resolve_verdicts(events: list[dict], spec: dict, verdict_ids: list[str], spe def gate(spec: dict, operation: str, actor: dict, events: list[dict], envelope: dict, *, - verdict_ids: list[str] | None = None, spec_digest_value: str | None = None) -> tuple[Approved, list[dict]]: - """The goal gate in one call: the actor is human and is the approver, the ledger pins an owner key and the - approval verifies under that key (no other) and covers this spec and operation, and (on promote) every - verdict resolves to an accepting review of this variant whose proposers and reviewer are not the - approver. The key is read from ``events`` (:func:`pinned_owner_key`), never taken from the caller. - Returns the approval and the resolved verdicts.""" + verdict_ids: list[str] | None = None, spec_digest_value: str | None = None, load_rotation=None) -> tuple[Approved, list[dict]]: + """The goal gate in one call: the actor is human and is the approver, the ledger pins an owner key whose + lineage verifies and the approval verifies under that key (no other) and covers this spec and operation, + and (on promote) every verdict resolves to an accepting review of this variant whose proposers and + reviewer are not the approver. The key is read from ``events`` through :func:`pinned_owner_key`, never + taken from the caller; ``load_rotation`` (the ledger's ``approvals/`` reader) only supplies the stored + rotation envelopes, each of which must still verify under the key the chain pinned before it. An invalid + lineage refuses (``owner_key_lineage``). Returns the approval and the resolved verdicts.""" if actor.get("kind") != "human": raise Rejected("spec_actor", f"{operation} is an owner act: the actor's kind is human, not {actor.get('kind')!r}") - pinned = pinned_owner_key(events) + pinned = pinned_owner_key(events, load_rotation) if pinned is None: raise Rejected("owner_key_unset", "the ledger pins no owner key; `factory owner --public KEY` (or the first `--owner-public`) sets it") declared = [s.get("keyid") for s in (envelope.get("signatures") or []) if isinstance(s, dict)] if isinstance(envelope, dict) else [] diff --git a/tests/test_factory.py b/tests/test_factory.py index aff25b8..6635b5c 100644 --- a/tests/test_factory.py +++ b/tests/test_factory.py @@ -952,16 +952,111 @@ def test_the_owner_key_is_pinned_and_rotates_only_under_the_old_key(self): pins = [e["body"] for e in home.events() if e["kind"] == "owner_key_set"] self.assertEqual([(p["keyid"], p["previous"]) for p in pins], [(owner_public.hex(), None), (mine_public.hex(), owner_public.hex())]) self.assertTrue(home.verify()) - rotation = home.home / "approvals" / f"{pins[1]['rotation_digest']}.json" - rotation.write_text(rotation.read_text(encoding="utf-8").replace(owner_public.hex(), mine_public.hex()), encoding="utf-8") - self.assertTrue(any("approvals/" in problem for problem in home.problems()), "an edited rotation is named by verify") - # In process, the same: ``set_owner_key`` is the only writer and refuses a seed that is not the pinned key's. + # In process, the same: ``set_owner_key`` refuses a seed that is not the pinned key's and a re-pin of the same key. with self.assertRaises(Rejected) as refused: home.set_owner_key(owner_public, seed=owner_seed) self.assertEqual(refused.exception.code, "owner_key_rotation") with self.assertRaises(Rejected) as refused: home.set_owner_key(mine_public, seed=mine_seed) self.assertEqual(refused.exception.code, "owner_key_pinned") + # An edited rotation is named by verify as the artifact it is and as a break in the lineage; from then on + # the ledger pins nothing, so neither key approves and no rotation is accepted (M3 of the delta verification). + rotation = home.home / "approvals" / f"{pins[1]['rotation_digest']}.json" + rotation.write_text(rotation.read_text(encoding="utf-8").replace(owner_public.hex(), mine_public.hex()), encoding="utf-8") + problems = home.problems() + self.assertTrue(any("approvals/" in problem for problem in problems), problems) + self.assertTrue(any(problem.startswith("owner_key_lineage:") for problem in problems), problems) + for public, seed in ((owner_public, owner_seed), (mine_public, mine_seed)): + with self.assertRaises(Rejected) as refused: + home.set_owner_key(public, seed=seed) + self.assertEqual(refused.exception.code, "owner_key_lineage") + + def test_the_owner_key_is_the_verified_lineage_not_the_newest_event(self): + """M3 of the #164 delta verification: the pin is the ledger's verified lineage, not its newest + ``owner_key_set``. After an honest bootstrap and rotation, each of the verifier's four shapes, appended + through the public ``append`` with the chain intact (a bare attacker pin, a rotation signed by the new key, + a rotation with a stale ``previous``, a malformed keyid last), fails ``verify``, is named + ``owner_key_lineage`` by ``problems``, refuses the gate at ``owner_key_lineage`` for the attacker's and + the honest approval alike (no ``owner_key_unset``, no fallback to an earlier key), refuses a further + rotation, and exits `spec retire` with 2. The honest ledger still retires.""" + from syberlabs.canonical import canonical, digest + mateo = {"kind": "human", "id": "mateo"} + tree = self.scratch / "tree" + shutil.copytree(FIXTURE, tree) + (tree / "spec.json").write_text(json.dumps(specmod.new_spec("order-path", "ordering", [ + {"req_id": "R1", "text": "When quantity is positive, the system shall post one order."}], + ["ingest", "rules", "effects"], author=mateo)), encoding="utf-8") + code, _, err = self.run_cli("spec", "validate", "spec.json", "--actor", "human:mateo", cwd=tree) + self.assertEqual(code, 0, err) + first_seed, first_public = generate() + second_seed, second_public = generate() + attacker_seed, attacker_public = generate() + home = ledger.Ledger(tree / ".syberlabs" / "factory") + home.set_owner_key(first_public) + home.set_owner_key(second_public, seed=first_seed) + self.assertEqual(home.owner_key(), second_public.hex()) + self.assertEqual(home.owner_key_lineage()[1], []) + self.assertTrue(home.verify()) + document = json.loads((tree / "spec.json").read_text(encoding="utf-8")) + honest = specmod.sign_approval(specmod.approval_payload(document, "retire", mateo), second_seed) + forged = specmod.sign_approval(specmod.approval_payload(document, "retire", mateo), attacker_seed) + (tree / "honest.json").write_text(json.dumps(honest), encoding="utf-8") + (tree / "forged.json").write_text(json.dumps(forged), encoding="utf-8") + + def rotation(target, previous, next_key, signer_seed, claimed_previous=None): + """An ``owner_key_set`` body with its envelope stored where ``verify`` looks, signed by whoever.""" + envelope = specmod.sign_rotation(specmod.rotation_payload(previous, next_key), signer_seed) + sha = digest(envelope) + (target.home / "approvals" / f"{sha}.json").write_text(canonical(envelope), encoding="utf-8") + return {"keyid": next_key.hex(), "previous": (claimed_previous or previous).hex(), "rotation_digest": sha} + + shapes = [ + ("a bare appended pin", lambda t: {"keyid": attacker_public.hex(), "previous": None, "rotation_digest": None}), + ("a rotation signed by the new key", lambda t: rotation(t, second_public, attacker_public, attacker_seed)), + ("a rotation with a stale previous", lambda t: rotation(t, first_public, attacker_public, first_seed)), + ("a malformed keyid last", lambda t: {"keyid": "not-a-key", "previous": second_public.hex(), "rotation_digest": None}), + ] + for number, (shape, body) in enumerate(shapes): + copy = self.scratch / f"shape{number}" + shutil.copytree(tree, copy) + target = ledger.Ledger(copy / ".syberlabs" / "factory") + target.append("owner_key_set", body(target)) + events = target.events() + self.assertTrue(ledger._verify_chain(events), shape) + self.assertFalse(target.verify(), shape) + self.assertTrue(any(p.startswith("owner_key_lineage: owner_key_set at seq 4") for p in target.problems()), (shape, target.problems())) + self.assertEqual(target.owner_key_lineage(events)[0], None, shape) + with self.assertRaises(Rejected, msg=shape) as refused: + target.owner_key() + self.assertEqual(refused.exception.code, "owner_key_lineage", shape) + for envelope in (forged, honest): + with self.assertRaises(Rejected, msg=shape) as refused: + specmod.gate(document, "retire", mateo, events, envelope, load_rotation=target.load_rotation) + self.assertEqual(refused.exception.code, "owner_key_lineage", shape) + with self.assertRaises(Rejected, msg=shape) as refused: + target.set_owner_key(attacker_public, seed=second_seed) + self.assertEqual(refused.exception.code, "owner_key_lineage", shape) + for approval in ("forged.json", "honest.json"): + code, _, err = self.run_cli("spec", "retire", "spec.json", "--actor", "human:mateo", "--approval", approval, cwd=copy) + self.assertEqual(code, 2, (shape, err)) + self.assertIn("owner_key_lineage", err, shape) + code, _, err = self.run_cli("owner", cwd=copy) + self.assertEqual((code, "owner_key_lineage" in err), (2, True), shape) + self.assertEqual(json.loads((copy / "spec.json").read_text(encoding="utf-8"))["state"], "candidate", shape) + self.assertEqual([e for e in target.events() if e["kind"] == "spec_changed" and e["body"].get("operation") == "retire"], [], shape) + # In-memory events without a loader: a bootstrap alone pins; a rotation cannot be checked, so it is invalid. + self.assertEqual(specmod.pinned_owner_key(home.events()[:2]), first_public.hex()) + with self.assertRaises(Rejected) as refused: + specmod.pinned_owner_key(home.events()) + self.assertEqual(refused.exception.code, "owner_key_lineage") + # The honest ledger: the forged approval is a mismatch, the honest one retires, and the lineage still verifies. + code, _, err = self.run_cli("spec", "retire", "spec.json", "--actor", "human:mateo", "--approval", "forged.json", cwd=tree) + self.assertEqual((code, "owner_key_mismatch" in err), (2, True), err) + code, out, err = self.run_cli("spec", "retire", "spec.json", "--actor", "human:mateo", "--approval", "honest.json", cwd=tree) + self.assertEqual(code, 0, err) + self.assertIn("candidate -> retired", out) + self.assertTrue(home.verify()) + self.assertEqual(home.describe()["owner_key"], second_public.hex()) if __name__ == "__main__": @@ -1079,6 +1174,28 @@ def test_an_edited_golden_refuses_the_check(self): self.assertIn(f"runs/{golden}", verdict.checks[0].output_tail) self.assertEqual([e for e in home.events() if e["kind"] == "attested"], [], "nothing was attested over an edited baseline") + def test_a_ledger_that_changes_under_the_test_suite_refuses_the_check(self): + """M3's window: a candidate that learned the ledger's path appends a line while its test suite runs, after + the check's post-run verification. The check verifies the ledger again after the suite and before anything + is attested, and refuses; the line is on the ledger, nothing is attested over it.""" + import sys as _sys + home, _ = self.golden() + reaching = json.dumps([_sys.executable, "-c", + f"import sys; sys.path.insert(0, {str(ROOT)!r}); from syberlabs.factory import ledger; " + f"ledger.Ledger({str(self.ledger_home)!r}).append('note', {{'text': 'from the suite'}})"]) + kit = self.kit(extra_argv=["--tests-argv", reaching]) + thread = kit.start("Reach", paths=["fxapp/"]) + rules = (self.project / "fxapp" / "rules.py").read_text(encoding="utf-8") + [candidate] = thread.propose(changes={"fxapp/rules.py": rules + "\n"}) + verdict = thread.check(candidate.id) + self.assertFalse(verdict.acceptable, verdict.summary()) + self.assertEqual(verdict.reason, "candidate_check_failed:factory") + self.assertIn("ledger_corrupt", verdict.checks[0].output_tail) + events = home.events() + self.assertEqual(events[-1]["kind"], "note", "the suite's line did land, which is what the check saw") + self.assertEqual([e for e in events if e["kind"] == "attested"], [], "nothing was attested over it") + self.assertTrue(home.verify()) + def test_a_candidate_that_forges_its_report_is_refused(self): """S2 through the seam: the candidate rewrites the recorded entrypoint to print a clean report and exit. The check reads the journal's end record itself and takes the report only over the nonce-bound channel.""" From caee31490000da058356e5c2efc46a14dc50b881 Mon Sep 17 00:00:00 2001 From: sykosyber Date: Mon, 2 Nov 2026 00:45:07 -0800 Subject: [PATCH 4/8] Factory autonomy thin slice (AM1): an owner-approved feature map compiled to tickets on the ledger, each feature built by a Build Thread the runner drives, inside an envelope; nothing merges featuremap.py: feature-map.v1 over #154's spec object (sectioned Markdown -> spec; D2), mapcheck (schema, spec digest, coverage, acyclic DAG, declared scope conflicts, act class, size, hidden-check names, approval digest), the task graph (critical path, total work, work/critical ratio, Dilworth width, conflict graph), the risk plan (seven code-computed inputs, standardized scores, v_i = V * softmax(z_i / tau) above a floor that never moves) and one feature -> one ticket in ticket_from_spec's shape (D5). policy.py: FeaturePolicy with the five typed questions over closed option sets, OfflinePolicy (critical path first, cheapest tier that fits, retry then stronger arm then owner, park when spent, stop on the envelope) and ShadowPolicy (records what an injected second policy would answer; never acts on it). loop.py: refuses an unapproved or stale map and an unpromoted spec, writes one contract per feature, drives each attempt with `syberlabs run`'s Runner (D17), reserves and settles an envelope ledger shaped like the eval spend ledger (D13), and records every proposal, step and outcome as ledger events whose digests exclude thread ids, commits and times. autonomy_cli.py: `syberlabs factory autonomy check|approve|envelope|run|why`, hooked from one line at the end of cli.py. 17 tests on a three-feature fixture over factory_app with a stand-in proposer command: tickets on the ledger, F1 -> F3 -> F2 order, shadow disagreement recorded, envelope and kill switch stop the loop, await_merge leaves a dependent waiting, a failing or out-of-scope candidate is refused by the kernel and parked, same fixture gives the same event digests, no merge or network call in the modules. docs/FACTORY_AUTONOMY.md says what the slice does and does not do, the glossary, and the next packets (C5, C6, C9, C10). Co-Authored-By: Claude Fable 5.1 --- docs/FACTORY_AUTONOMY.md | 132 ++++ syberlabs/factory/autonomy_cli.py | 166 +++++ syberlabs/factory/cli.py | 6 + syberlabs/factory/featuremap.py | 639 ++++++++++++++++++++ syberlabs/factory/loop.py | 532 ++++++++++++++++ syberlabs/factory/policy.py | 187 ++++++ tests/fixtures/autonomy/hidden_checks.json | 6 + tests/fixtures/autonomy/map.json | 40 ++ tests/fixtures/autonomy/spec.md | 16 + tests/fixtures/autonomy/standin_proposer.py | 34 ++ tests/test_factory_autonomy.py | 451 ++++++++++++++ 11 files changed, 2209 insertions(+) create mode 100644 docs/FACTORY_AUTONOMY.md create mode 100644 syberlabs/factory/autonomy_cli.py create mode 100644 syberlabs/factory/featuremap.py create mode 100644 syberlabs/factory/loop.py create mode 100644 syberlabs/factory/policy.py create mode 100644 tests/fixtures/autonomy/hidden_checks.json create mode 100644 tests/fixtures/autonomy/map.json create mode 100644 tests/fixtures/autonomy/spec.md create mode 100644 tests/fixtures/autonomy/standin_proposer.py create mode 100644 tests/test_factory_autonomy.py diff --git a/docs/FACTORY_AUTONOMY.md b/docs/FACTORY_AUTONOMY.md new file mode 100644 index 0000000..a2ee44e --- /dev/null +++ b/docs/FACTORY_AUTONOMY.md @@ -0,0 +1,132 @@ +# The autonomy thin slice (AM1): an approved feature map, built to "ready for owner merge" + +Packet C4 of the consolidation plan (`reports/2026-11-01-syberfactory-consolidation.md`, section 5), built on the +factory of `docs/FACTORY.md`: the same ledger, the same spec object, the same tickets, the same Build Thread. It +realises the first slice of the autonomous typed mode (`2026-10-28-syberfactory-autonomous-typed-mode.md`) as +three modules under `syberlabs/factory/` and one CLI group, at $0, offline, with a stand-in command where a +model would be. + +Claim ceiling for this page: **implemented** and **tested** (`tests/test_factory_autonomy.py`, 17 tests, run on +Windows with Python 3.12 and in CI). Nothing here is measured on a real spec, deployed, or validated by anyone +outside the repository. + +## What it does + +```text +spec (promoted) ─► FeatureMap (typed DAG) ─► mapcheck ─► owner approval ─► tickets ─► one Build Thread per attempt ─► ready for owner merge + featuremap.py loop.compile loop.run (Runner from `syberlabs run`) + FeaturePolicy asks: next_feature, proposer_arm, budget_tier, after_failure, worth_continuing + envelope ledger: reserve before, settle after, stop on the line +``` + +| Module | What it holds | +| --- | --- | +| `featuremap.py` | `feature-map.v1`: features with id, objective, `req_ids` (the spec requirements they trace to), scope paths, shown criteria, hidden-check names (names only), `depends_on`, act class, size, risk inputs. `spec_from_markdown` turns a sectioned Markdown spec (`## R1: text`, `- given, when, then` bullets) into #154's spec object (owner decision 11, D2). `mapcheck` is the deterministic floor: schema, spec digest, coverage, acyclic DAG, scope conflicts (an intersection must be declared with an order that agrees with the DAG), act class, size ceilings, hidden-check names, approval digest. `taskgraph`: critical path, total work, work/critical ratio, Dilworth width with a maximum antichain, conflict graph. `risk_plan`: seven risk inputs computed by code, `r_i` as a weighted sum, standardized `z_i`, `v_i = V * softmax(z_i / tau)` as integer units above a floor that is listed beside every allocation and never moves. `compile_ticket`: one feature to one ticket in `ticket_from_spec`'s shape (D5). `degenerate_map`: the map `ticket_from_spec` implies, one feature per requirement. | +| `policy.py` | `Question` (closed options built by code; the state a policy reads is ids and numbers only), `Answer`, `validate` (an answer outside the options is `policy_invalid`), `OfflinePolicy` (critical path first, cheapest arm and tier, retry then stronger arm then owner, park when the cap is spent, stop on the envelope), `ShadowPolicy` (acts on one policy, records what an injected second one would have answered and whether it agrees; an invalid or failing shadow is recorded and changes nothing), `recorded_answers` (a shadow over a fixture). | +| `loop.py` | `Loop.compile`: refuses a map without a current owner approval (`map_unapproved`), a spec that is not promoted, or a map with findings; writes one contract per feature; logs `map_frozen` and `ticket_opened{source: map}`. `Loop.run`: kill switch, eligibility, three policy questions recorded as proposals, envelope reservation, one unattended Build Thread, one proposer call through `CommandProvider`, then `syberlabs run`'s `Runner` drives the thread (D17), the envelope settles from the journal, the outcome is recorded. `EnvelopeLedger`: the eval spend ledger's shape generalized to attempts (D13). `why`: ticket -> feature -> map (approval) -> spec, from the ledger. `event_digests`: one digest per autonomy event without its volatile `refs`. | +| `autonomy_cli.py` | `syberlabs factory autonomy check | approve | envelope | run | why`, registered from one hook line at the end of `factory/cli.py`. | + +### A run on the fixture + +`tests/fixtures/autonomy/` holds a three-feature fixture over the factory's own `factory_app`: `spec.md` (three +sections), `map.json` (F1 -> F2 a dependency chain, F3 independent and larger), `hidden_checks.json` (the host's +catalogue, name to argv) and `standin_proposer.py` (the process boundary a model adapter sits behind: it reads the +request, appends a delivery marker to the one file in scope, and answers one candidate; `--break` and `--outside` +make it fail the visible check or edit outside its scope). + +The end-to-end test's ledger, in order: + +```text +map_frozen ticket_opened ×3 +policy_proposal(next_feature=F1) policy_proposal(proposer_arm) policy_proposal(budget_tier) +envelope_reserved attempt_started thread_step(check acceptable) thread_step(accept succeeded) envelope_settled feature_ready +policy_proposal(next_feature=F3) ... feature_ready +policy_proposal(next_feature=F2) ... feature_ready +loop_stopped(nothing_eligible) +``` + +F1 goes first (bottom level 2: a dependent waits on it), then F3 (size M, bottom level 2), then F2. Each feature +ends as an accepted candidate on `syberlabs/`, with the thread id, commit and target ref in the +`feature_ready` event's `refs`. `main` never moves. Under `integration: stack` F2's thread starts from F1's accepted +commit; under `await_merge` F2 is recorded `feature_waiting` and the loop stops with F1 and F3 ready, because only +the owner's merge can release it. The same fixture run twice gives the same `event_digests` list: no timestamp, +thread id, commit or elapsed time enters a digest. + +### From a terminal + +```sh +python -m syberlabs.factory --home .syberlabs/factory spec validate spec.json # the spec, as in FACTORY.md +python -m syberlabs.factory --home .syberlabs/factory spec promote spec.json --verdict review-1 --actor human:mateo +python -m syberlabs.factory autonomy check --map map.json --spec spec.json # findings, graph, risk plan; exit 1 on findings +python -m syberlabs.factory autonomy approve --map map.json --by mateo # the owner's act; any edit leaves it stale +python -m syberlabs.factory autonomy envelope --map map.json --calls 6 --attempts 2 --out envelope.json +python -m syberlabs.factory --home .syberlabs/factory autonomy run --map map.json --spec spec.json --envelope envelope.json \ + --owner mateo --proposer "/abs/python standin.py ." --check "tests=/abs/python -m unittest -q" \ + --hidden "hidden.f1.marker=/abs/python -c ..." # exit 0 when a feature is ready +python -m syberlabs.factory --home .syberlabs/factory autonomy why TICKET +``` + +## What it does not do + +- **Publish or merge.** No action in the loop pushes, opens a pull request or merges; `loop.ACTIONS` is the closed + list `start_thread, propose, check, accept_to_thread_branch`, and a test asserts the three modules hold no merge + or network call. The terminal state is `ready_for_owner_merge`. The draft PR is C9. +- **Call Jev, or any model.** `ShadowPolicy` accepts an injected callable and records its answers; nothing imports + `jev_api` or opens a socket. Jev stays in shadow until E7 (owner decision 7). The adapter that reuses + `jev_api`'s request and validation code is a later packet; `recorded_answers` is its fixture-side stand-in. +- **Author the map.** The map is hand-written or produced elsewhere; `mapcheck` refuses what it cannot accept. + The variant loop as map author is C4's follow-up in `factory/variants.py` (D14), not this slice. +- **Grade with a replay.** The hidden checks run in the candidate's worktree as contract checks the host holds + (never in the repository), which is the Build Thread's own evidence. The independent replay grade (a fresh clone, + a fresh hidden copy, the SyberEval gate) is the `replay` arm, left for C9/C10 with the eval runner. +- **Run with concurrency.** `concurrency` is 1. The task graph's width and conflict graph are computed and logged + so the question of whether `c > 1` pays can be answered from the record; the scope lock is a check on declared + overlap order, not a scheduler. +- **Price anything.** Every proposer call here is a stand-in at $0. The envelope's dollar tiers are read and + reserved; a priced arm would settle from `search_finished.spend` exactly as the eval runner does. +- **Add an event kind.** `ledger.KINDS` belongs to `ledger.py` and to the goal-gate packet editing it. The slice + writes `note` events whose `body.note` names the autonomy event (`loop.EVENTS`) and `ticket_opened` with + `source: map`. When the vocabulary is extended, `loop.record` is the one place to change. + +## Glossary (per the consolidation report) + +- **Spec**: #154's spec object (`spec.py`). An L1 objective. Only an owner promotes it (C1 makes that code). +- **FeatureMap**: the typed task DAG of this page. L2 work. Frozen by the owner's approval digest. +- **Feature**: one node of the map; compiles to one ticket; built by one or more Build Threads (attempts). +- **Ticket**: `ticket_from_spec`'s shape with `map_ref`, scope as footprint, shown criteria, exit criteria naming + evidence kinds and hidden checks, `rubric_digest` over the hidden-check names, a mandatory `human_owner`. +- **Codemap**: #154's `features.py`, hashed vectors per symbol and component. An index the map author may query + and the `moved` sensor uses. It is never the feature map (D3; the rename to `codemap.py` is C1's). +- **Envelope**: the owner's grant of autonomy: dollars by tier, calls, seconds, attempts per feature, act classes, + arms, the closed action list, the kill switch. Its ledger reserves before and settles after every attempt. +- **Floor**: host checks, hidden checks, critic, safety gate. Every feature, every risk score. Extra verification + is only ever conjoined. +- **Promote**: an owner act on a spec. Not an attestation's verdict, not an accepted candidate (D4). +- **Shadow**: a policy whose answers are recorded beside the acting policy's and never acted on. + +## Next packets + +- **C5 `factory-check-real-checkout`**: `bootstrap` on a fresh SyberWork clone with `examples/factory_self_check.py` + as the golden; the published contract shape committed as an example; the four FACTORY.md candidates against the + real contract as a receipt. +- **C6 `independent-review`**: one `independence()` over the host-recorded served model's provider family (D8); + `review.independent` recorded but not blocking; `auto_merge_eligible` computed and journaled per feature; the + variant `judge` and the critic share it. The feature loop then records the composition of section 4 in shadow. +- **C9 `factory-publish` and the feature certificate**: the draft PR per ready feature with Feature, Map, Ticket, + Envelope and Grade fields from the record; a grep test that no merge call exists; `feature-delivered/v1` as a + third predicate referencing the child certificate and attestation digests (D6). Reads `settle` only. +- **C10 E8 `risk-allocation`**: planted defects in 2- to 4-feature maps; arms are allocation policies over one + budget V (uniform, softmax at tau = 1, argmax, water-filling); the metric is defects caught per unit and escapes + by risk decile. `risk_plan` here records the propensities that evaluation needs. + +## Limits of this slice + +- Stacking (`integration: stack`) starts a dependent from its last dependency's accepted commit by checking out a + branch `syberfactory//` in the working repository. A feature with two dependencies on separate + branches is not integrated here; the owner's merge order is. +- A hidden check runs as a contract check in the candidate's worktree, so it is as exposed to candidate code as any + check (register N4). The fixture's stand-in writes no code that runs; a model's would, and then the host decision + (C7) applies. +- The envelope ledger has no cross-process lock, as the factory ledger has none (D1 puts both on the journal's lock + in C1). +- The risk weights and tau are priors. Nothing has calibrated them; `risk_plan` logs what calibration would need. diff --git a/syberlabs/factory/autonomy_cli.py b/syberlabs/factory/autonomy_cli.py new file mode 100644 index 0000000..19b6701 --- /dev/null +++ b/syberlabs/factory/autonomy_cli.py @@ -0,0 +1,166 @@ +"""``syberlabs factory autonomy ...``: the thin slice from a terminal. + + syberlabs factory autonomy check --map map.json --spec spec.json # mapcheck, task graph, risk plan; exit 1 on findings + syberlabs factory autonomy approve --map map.json --by mateo # the owner's approval over the map's digest (G1) + syberlabs factory autonomy envelope --map map.json --calls 6 --out env.json + syberlabs factory autonomy run --map map.json --spec spec.json --envelope env.json --owner mateo \\ + --proposer "python standin.py ." --check "tests=python -m unittest -q" --hidden "hidden.f1.marker=python -c ..." + syberlabs factory autonomy why TICKET # ticket -> feature -> map -> spec, from the ledger + +Registered through ``extend`` from one hook line at the end of ``cli.py``, so that file takes no other edit for +this packet. ``--home`` is the factory ledger, ``--root`` the repository the features change. +""" + +from __future__ import annotations + +import argparse +import json +import sys +from pathlib import Path + +from syberlabs.errors import Rejected +from syberlabs.factory import featuremap, loop +from syberlabs.factory import policy as policymod +from syberlabs.providers import split_command + +COMMAND = "autonomy" + + +def extend(populate, run): + """Wrap ``cli.populate`` and ``cli.run`` so the factory parser gains ``autonomy`` and dispatches it here.""" + def populate_with_autonomy(factory): + populate(factory) + steps = next(a for a in factory._actions if isinstance(a, argparse._SubParsersAction)) + add_commands(steps) + + def run_with_autonomy(args): + if getattr(args, "factory_command", None) != COMMAND: + return run(args) + try: + return _run(args) + except Rejected as exc: + print(f"error: {exc.code}: {exc.detail}", file=sys.stderr) + return 2 + + return populate_with_autonomy, run_with_autonomy + + +def add_commands(steps) -> None: + auto = steps.add_parser(COMMAND, help="the autonomous typed mode's thin slice: approved feature map -> tickets -> " + "Build Threads -> ready for owner merge, inside an envelope (docs/FACTORY_AUTONOMY.md)") + sub = auto.add_subparsers(dest="autonomy_command", required=True) + check = sub.add_parser("check", help="mapcheck findings, the task graph and the risk plan") + check.add_argument("--map", required=True) + check.add_argument("--spec", required=True, help="the promoted spec JSON (syberlabs factory spec ...)") + check.add_argument("--tau", type=float, default=1.0) + check.add_argument("--units", type=int, default=None, help="extra verification units to allocate (default: one per feature)") + check.add_argument("--json", action="store_true") + approve = sub.add_parser("approve", help="record the owner's approval over the map's current digest (a human act)") + approve.add_argument("--map", required=True) + approve.add_argument("--by", required=True, help="the approving person's id") + env = sub.add_parser("envelope", help="write an envelope for a map: dollars, calls, seconds, attempts") + env.add_argument("--map", required=True) + env.add_argument("--dollars", type=float, default=0.0) + env.add_argument("--calls", type=int, required=True) + env.add_argument("--seconds", type=float, default=3600.0) + env.add_argument("--attempts", type=int, default=2) + env.add_argument("--kill-switch", help="absolute path; when the file exists the loop stops before its next decision") + env.add_argument("--out", required=True) + runp = sub.add_parser("run", help="compile the approved map to tickets and drive each feature through a Build Thread") + runp.add_argument("--map", required=True) + runp.add_argument("--spec", required=True) + runp.add_argument("--envelope", required=True) + runp.add_argument("--owner", required=True, help="the accountable human on every ticket") + runp.add_argument("--kit-home", default=".syberlabs", help="the Build Thread home under --root (default .syberlabs)") + runp.add_argument("--proposer", required=True, help="the proposer command (a stand-in or a model adapter), as one string") + runp.add_argument("--check", action="append", default=[], metavar="NAME=CMD", help="a visible check (repeatable)") + runp.add_argument("--hidden", action="append", default=[], metavar="NAME=CMD", + help="a hidden check the host holds under the name the map uses (repeatable; never in a worktree)") + runp.add_argument("--baseline", help="the golden run id to name on tickets") + runp.add_argument("--max-steps", type=int, default=50) + runp.add_argument("--shadow", help="recorded answers JSON for a shadow policy; recorded beside each decision, never acted on") + why = sub.add_parser("why", help="walk a ticket back to its feature, map, approval and spec") + why.add_argument("ticket") + + +def _parse_checks(items: list[str], what: str) -> dict: + out = {} + for item in items: + name, found, command = item.partition("=") + if not found or not name or not command.strip(): + raise Rejected("check_argument", f"{what} must be NAME=COMMAND, not {item!r}") + out[name] = split_command(command) + return out + + +def _run(args) -> int: + from syberlabs.factory import ledger as ledgermod + command = args.autonomy_command + if command == "check": + document = loop.load_json(args.map, "map") + spec = loop.load_json(args.spec, "spec") + findings = featuremap.mapcheck(document, spec) + if findings: + for finding in findings: + print(f"finding {finding}") + print(f"{len(findings)} finding(s); the map is not compiled") + return 1 + graph = featuremap.taskgraph(document) + plan = featuremap.risk_plan(document, graph, budget=args.units, tau=args.tau) + if args.json: + print(json.dumps({"graph": graph, "plan": plan, "approved": featuremap.approved(document)}, indent=2, sort_keys=True)) + return 0 + print(f"map {document['id']} {featuremap.map_digest(document)[:12]}: {graph['features']} features, {graph['edges']} edges; " + f"approved {featuremap.approved(document)}") + print(f"critical path {' -> '.join(graph['critical_path'])} (length {graph['critical_path_length']}); total work " + f"{graph['total_work']}; work/critical {graph['work_critical_ratio']}; width {graph['width']} {graph['max_antichain']}") + for conflict in graph["conflicts"]: + print(f"conflict {conflict['a']} {conflict['b']} on {conflict['paths']}" + (" (ordered by the DAG)" if conflict["ordered_by_dag"] else "")) + for fid in plan["r"]: + print(f"risk {fid:5} r {plan['r'][fid]:.3f} z {plan['z'][fid]:+.2f} share {plan['share'][fid]:.3f} " + f"units {plan['units'][fid]} buys {', '.join(plan['buys'][fid][len(featuremap.FLOOR):]) or '-'}") + print(f"floor {', '.join(plan['floor'])} (every feature, never loosened); tau {plan['tau']} on standardized scores") + return 0 + if command == "approve": + document = loop.load_json(args.map, "map") + approval = featuremap.approve(document, {"kind": "human", "id": args.by}) + Path(args.map).write_text(json.dumps(document, indent=2, sort_keys=True) + "\n", encoding="utf-8") + print(f"approved {document['id']} at {approval['digest'][:12]} by {args.by}; any edit of the map leaves this stale") + return 0 + if command == "envelope": + document = loop.load_json(args.map, "map") + envelope = loop.new_envelope(featuremap.map_digest(document), dollars_total=args.dollars, calls_total=args.calls, + seconds_total=args.seconds, attempts_per_feature=args.attempts, kill_switch=args.kill_switch) + Path(args.out).write_text(json.dumps(envelope, indent=2, sort_keys=True) + "\n", encoding="utf-8") + print(f"wrote {args.out}: envelope {loop.envelope_digest(envelope)[:12]} for map {document['id']}") + return 0 + if command == "run": + document = loop.load_json(args.map, "map") + spec = loop.load_json(args.spec, "spec") + envelope = loop.load_json(args.envelope, "envelope") + policy = policymod.OfflinePolicy() + if args.shadow: + policy = policymod.ShadowPolicy(policy, policymod.recorded_answers(loop.load_json(args.shadow, "shadow")), shadow_name="recorded") + checks = {name: {"argv": argv, "timeout_seconds": 300} for name, argv in _parse_checks(args.check, "--check").items()} + if not checks: + raise Rejected("check_argument", "name at least one visible check with --check NAME=COMMAND") + root = Path(args.root).resolve() + kit_home = Path(args.kit_home) + driver = loop.Loop(repo_root=root, kit_home=kit_home if kit_home.is_absolute() else root / kit_home, + ledger=ledgermod.Ledger(args.home), map=document, spec=spec, envelope=envelope, policy=policy, + proposer_argv=split_command(args.proposer), checks=checks, hidden_catalogue=_parse_checks(args.hidden, "--hidden"), + human_owner=args.owner, baseline_run=args.baseline, log=print) + tickets = driver.compile() + for ticket in tickets: + print(f"ticket {ticket['ticket_id']} {ticket['map_ref']['feature_id']} {ticket['title']}") + summary = driver.run(max_steps=args.max_steps) + for fid, row in summary["features"].items(): + print(f"feature {fid:5} {row['state']:22} attempts {row['attempts']}" + (f" {row['last_reason']}" if row["last_reason"] else "")) + totals = summary["envelope"] + print(f"stopped: {summary['stopped']}; envelope ${totals['dollars']:.4f}, {totals['calls']} calls, {totals['seconds']}s; " + f"ready for owner merge: {', '.join(summary['ready_for_owner_merge']) or 'none'}. Nothing was merged or pushed.") + return 0 if summary["ready_for_owner_merge"] else 1 + if command == "why": + print(json.dumps(loop.why(ledgermod.Ledger(args.home), args.ticket), indent=2, sort_keys=True)) + return 0 + raise Rejected("autonomy_command", f"unknown command {command!r}") diff --git a/syberlabs/factory/cli.py b/syberlabs/factory/cli.py index f1cc515..94d4f75 100644 --- a/syberlabs/factory/cli.py +++ b/syberlabs/factory/cli.py @@ -1027,3 +1027,9 @@ def main(argv: list[str] | None = None) -> int: formatter_class=argparse.RawDescriptionHelpFormatter) populate(parser) return run(parser.parse_args(argv)) + + +# The autonomy thin slice (docs/FACTORY_AUTONOMY.md) registers its subcommands from its own module; this hook is the +# only edit this file takes for it. ``main`` and ``syberlabs/cli.py`` look ``populate`` and ``run`` up at call time. +from syberlabs.factory import autonomy_cli as _autonomy_cli # noqa: E402 +populate, run = _autonomy_cli.extend(populate, run) diff --git a/syberlabs/factory/featuremap.py b/syberlabs/factory/featuremap.py new file mode 100644 index 0000000..3fab85e --- /dev/null +++ b/syberlabs/factory/featuremap.py @@ -0,0 +1,639 @@ +"""FeatureMap: the typed task DAG between a promoted spec and its tickets (``syberfactory/feature-map.v1``). + +A spec (``spec.py``, the one spec object, consolidation D2) is the objective. A feature map is the work: a DAG +of features, each with an objective a Build Thread can start from, a scope (the paths it may edit), the +acceptance criteria the builder is shown, the names of the hidden checks the host holds (names only; the +checks themselves never enter a worktree), the features it depends on, and the inputs of its risk score. +Every feature traces to at least one requirement of the spec (a requirement is a section, so coverage is +checkable), and every requirement is covered or listed as ``uncovered`` with a reason. + +This module is code, not a model. ``mapcheck`` is the deterministic floor the plan-to-one P3 gate needs: +schema, spec digest, coverage, DAG (acyclic), scope conflicts (an intersection of two scopes must be +declared with an order that agrees with the DAG), act class, size ceilings, hidden-check names, and the +owner-approval digest. ``taskgraph`` gives the four standard measures (critical path, total work, their +ratio, Dilworth width with a maximum antichain) and the conflict graph. ``risk_plan`` standardizes the risk +scores and allocates extra verification as ``v_i = V * softmax(z_i / tau)`` above a hard floor that never +moves: host checks, hidden checks, critic and gate apply to every feature whatever its score. + +Relation to the rest of the factory: + +- D2: the map is derived from #154's spec object. ``spec_ref`` pins ``spec_id``, ``version`` and + ``spec_digest``; feature ``req_ids`` are the spec's ``req_id``s. ``degenerate_map`` is the map + ``ticket_from_spec`` implies: one feature per requirement, no dependencies. +- D3: this is the FeatureMap. ``features.py`` (hashed vectors) is the codemap, an index; it is not imported here. +- D5: ``compile_ticket`` turns one feature into one ticket in ``ticket_from_spec``'s shape: scope is the + footprint, shown criteria are ``acceptance_criteria``, evidence kinds and hidden-check names are the exit + criteria, and ``rubric_digest`` is the digest of the hidden-check names. A ticket's ``map_ref`` carries the + map digest and feature id, so ``why`` can walk ticket -> map -> spec. + +Nothing here has an opinion: a map that fails a check is refused with the findings, never repaired. +""" + +from __future__ import annotations + +import math +import re + +from syberlabs.canonical import digest +from syberlabs.errors import Rejected +from syberlabs.factory import PROTOCOL +from syberlabs.factory import spec as specmod + +SCHEMA = "syberfactory/feature-map.v1" +ACT_CLASSES = ("R", "C", "P", "X") # syberlabs/build.py ACT_CLASSES; copied so the factory keeps its declared edges +SIZES = ("S", "M", "L") +DURATION = {"S": 1, "M": 2, "L": 4} # abstract work units per size tier +ACT_RANK = {"R": 0, "C": 1, "P": 2, "X": 3} +INTEGRATIONS = ("await_merge", "stack") +MIN_FEATURES, MAX_FEATURES = 1, 40 +MAX_CRITERIA = 8 +MAX_FILES_CEILING, MAX_DIFF_BYTES_CEILING = 12, 40_000 +FEATURE_FIELDS = frozenset({"id", "title", "objective", "req_ids", "depends_on", "scope", "overlaps", "act_class", + "criteria", "hidden_checks", "size", "risk_inputs"}) +MAP_FIELDS = frozenset({"schema", "id", "spec_ref", "base", "author", "features", "uncovered", "integration", "approval"}) +_FID = re.compile(r"^F[0-9]{1,3}$") +_CHECK = re.compile(r"^[a-z][a-z0-9_.-]{0,63}$") # a contract check name (build._NAME) +_SECTION = re.compile(r"^##\s+(?P[A-Za-z][A-Za-z0-9_-]*)\s*[:.]\s*(?P.+?)\s*$") + +# Risk: weights sum to 1 so r is in [0, 1]. From the theory report, section 4; unvalidated priors. +WEIGHTS = {"scope": 0.15, "act_class": 0.15, "new_deps": 0.10, "needs_lookup": 0.10, "disagreement": 0.20, + "centrality": 0.20, "uncovered": 0.10} +ACT_RISK = {"R": 0.0, "C": 0.5, "P": 0.75, "X": 1.0} +FLOOR = ("host_checks", "hidden_checks", "critic", "safety_gate") # every feature, every score; never loosened +LADDER = ("independent_replay_rerun", "extra_seeds_x2", "adversarial_review", "owner_blind_review") +TAU_MIN = 0.05 # keeps every propensity positive (the overlap condition for calibration) + + +# -- spec side: sectioned Markdown -> #154's spec object (owner decision 11, D2) ---------------------------------- + +def spec_from_markdown(text: str, spec_id: str, capability: str, footprint_hint: list[str], *, + author: dict | None = None, evidence_kinds: list[str] | None = None) -> dict: + """A sectioned Markdown spec (``## R1: requirement text`` then ``- given ... / when ... / then ...`` lines) + becomes a draft #154 spec with one requirement per section. Scenario bullets of the form + ``- given X, when Y, then Z`` become scenarios; other bullets are kept as free text scenarios.""" + requirements, current = [], None + for line in text.splitlines(): + found = _SECTION.match(line) + if found: + current = {"req_id": found.group("id"), "text": found.group("text"), "scenarios": [], + "evidence_kinds": list(evidence_kinds or ["tests"])} + requirements.append(current) + continue + stripped = line.strip() + if current is not None and stripped.startswith("- "): + current["scenarios"].append(_scenario(stripped[2:])) + if not requirements: + raise Rejected("spec_invalid", "no '## : ' section found") + return specmod.new_spec(spec_id, capability, requirements, footprint_hint, author=author) + + +def _scenario(text: str) -> dict: + parts = re.split(r",\s*(?=when\b|then\b)", text, flags=re.IGNORECASE) + if len(parts) == 3 and parts[0].lower().startswith("given"): + return {"given": parts[0][5:].strip(), "when": parts[1][4:].strip(), "then": parts[2][4:].strip()} + return {"text": text} + + +# -- the map ------------------------------------------------------------------------------------------------------- + +def new_map(map_id: str, spec: dict, features: list[dict], *, base: str | None, author: dict, + uncovered: list[dict] | None = None, integration: str = "await_merge") -> dict: + """A map over ``spec`` as it is now. Validation is ``mapcheck``; this only assembles.""" + return {"schema": SCHEMA, "id": map_id, + "spec_ref": {"spec_id": spec["spec_id"], "version": spec["version"], "spec_digest": specmod.spec_digest(spec)}, + "base": base, "author": dict(author), "features": [dict(f) for f in features], + "uncovered": list(uncovered or []), "integration": integration, "approval": None} + + +def feature(fid: str, title: str, objective: str, *, req_ids: list[str], paths: list[str], depends_on: list[str] = (), + criteria: list[dict] | None = None, hidden_checks: list[str] = (), act_class: str = "R", size: str = "S", + overlaps: list[dict] = (), exclude: list[str] = (), max_files: int = 6, max_diff_bytes: int = 20_000, + new_dependencies: int = 0, needs_lookup: bool = False, disagreement: float = 0.0) -> dict: + return {"id": fid, "title": title, "objective": objective, "req_ids": list(req_ids), "depends_on": list(depends_on), + "scope": {"paths": list(paths), "exclude": list(exclude), "max_files": max_files, "max_diff_bytes": max_diff_bytes}, + "overlaps": [dict(o) for o in overlaps], "act_class": act_class, + "criteria": [dict(c) for c in (criteria or [])], "hidden_checks": list(hidden_checks), "size": size, + "risk_inputs": {"new_dependencies": new_dependencies, "needs_lookup": needs_lookup, "disagreement": disagreement}} + + +def degenerate_map(spec: dict, *, base: str | None, author: dict) -> dict: + """The map ``ticket_from_spec`` implies (D5): one feature per requirement, no dependencies, the spec's + resolved footprint files as every feature's scope, scenarios as the shown criteria. Two requirements over + one footprint therefore overlap; the degenerate map declares each overlap in requirement order.""" + files = (spec.get("footprint") or {}).get("files") or [] + if not files: + raise Rejected("footprint_unresolved", "resolve the spec's footprint against a Space graph first") + features = [] + for number, requirement in enumerate(spec["requirements"], 1): + fid = f"F{number}" + criteria = [{"id": f"{fid}.c{i}", "text": _criterion_text(s), "kind": "test"} + for i, s in enumerate(requirement["scenarios"], 1)] or [{"id": f"{fid}.c1", "text": requirement["text"], "kind": "judgment"}] + overlaps = [{"with": f"F{other}", "paths": sorted(files), "order": f"F{min(number, other)}_first"} + for other in range(1, len(spec["requirements"]) + 1) if other != number] + features.append(feature(fid, requirement["text"][:80], requirement["text"], req_ids=[requirement["req_id"]], + paths=sorted(files), criteria=criteria, overlaps=overlaps, + max_files=min(MAX_FILES_CEILING, max(1, len(files))))) + return new_map(f"{spec['spec_id']}.degenerate", spec, features, base=base, author=author) + + +def _criterion_text(scenario: dict) -> str: + if "text" in scenario: + return scenario["text"] + return f"given {scenario.get('given', '')}, when {scenario.get('when', '')}, then {scenario.get('then', '')}" + + +def map_digest(document: dict) -> str: + """The map without its approval, so approval is over exactly this digest.""" + return digest({k: v for k, v in document.items() if k != "approval"}) + + +def approve(document: dict, actor: dict) -> dict: + """The owner's approval (G1): a human actor over the map's digest. Any later edit of the map leaves the + approval stale, and ``approved`` says so. This records; it does not decide that the map is good.""" + if not isinstance(actor, dict) or actor.get("kind") != "human" or not actor.get("id"): + raise Rejected("approval_actor", "a map is approved by a human actor {kind: human, id: ...}, never a model") + document["approval"] = {"digest": map_digest(document), "actor": {"kind": "human", "id": str(actor["id"])}} + return document["approval"] + + +def approved(document: dict) -> bool: + approval = document.get("approval") + return (isinstance(approval, dict) and approval.get("digest") == map_digest(document) + and isinstance(approval.get("actor"), dict) and approval["actor"].get("kind") == "human" + and bool(approval["actor"].get("id"))) + + +# -- mapcheck ------------------------------------------------------------------------------------------------------ + +def path_intersects(a: str, b: str) -> bool: + """Prefix intersection of two scope entries at directory boundaries. ``"."`` or empty is the whole tree.""" + a, b = a.strip().lstrip("./"), b.strip().lstrip("./") + if a in ("", ".") or b in ("", "."): + return True + ad, bd = a.rstrip("/"), b.rstrip("/") + return ad == bd or bd.startswith(ad + "/") or ad.startswith(bd + "/") + + +def scope_intersection(f: dict, g: dict) -> list[str]: + out = set() + for p in f["scope"]["paths"]: + for q in g["scope"]["paths"]: + if path_intersects(p, q): + out.add(p if len(p.rstrip("/")) >= len(q.rstrip("/")) else q) + return sorted(out) + + +def mapcheck(document: dict, spec: dict) -> list[str]: + """Every finding, as strings. Empty means the map may be compiled. Order: shape, then graph, then coverage, + then conflicts, then approval. A shape finding stops the deeper checks, which would only cascade.""" + findings: list[str] = [] + note = findings.append + if not isinstance(document, dict): + return ["map: not a JSON object"] + missing, extra = MAP_FIELDS - set(document), set(document) - MAP_FIELDS + if missing or extra: + return [f"map: missing {sorted(missing)} unknown {sorted(extra)}"] + if document["schema"] != SCHEMA: + note(f"map.schema must be {SCHEMA!r}") + if not isinstance(document["id"], str) or not document["id"].strip(): + note("map.id must be a non-empty string") + ref = document["spec_ref"] + if not (isinstance(ref, dict) and set(ref) == {"spec_id", "version", "spec_digest"}): + note("map.spec_ref must be {spec_id, version, spec_digest}") + else: + if ref["spec_id"] != spec["spec_id"] or ref["version"] != spec["version"]: + note(f"map.spec_ref names {ref['spec_id']} v{ref['version']}, the spec is {spec['spec_id']} v{spec['version']}") + if ref["spec_digest"] != specmod.spec_digest(spec): + note("map.spec_ref.spec_digest does not equal the spec's digest (the spec changed after the map was written)") + if document["base"] is not None and not (isinstance(document["base"], str) and document["base"]): + note("map.base must be a commit string or null") + author = document["author"] + if not (isinstance(author, dict) and author.get("kind") in ("human", "model", "command") and author.get("id")): + note("map.author must be {kind: human|model|command, id}") + if document["integration"] not in INTEGRATIONS: + note(f"map.integration must be one of {INTEGRATIONS}") + features = document["features"] + if not (isinstance(features, list) and MIN_FEATURES <= len(features) <= MAX_FEATURES): + note(f"features must be a list of {MIN_FEATURES}..{MAX_FEATURES}") + return findings + req_ids = [r["req_id"] for r in spec["requirements"]] + ids: list[str] = [] + check_names: dict[str, str] = {} + for index, item in enumerate(features): + where = f"feature[{index}]" + if not isinstance(item, dict): + note(f"{where}: not an object") + continue + missing, extra = FEATURE_FIELDS - set(item), set(item) - FEATURE_FIELDS + if missing or extra: + note(f"{where}: missing {sorted(missing)} unknown {sorted(extra)}") + continue + fid = item["id"] + if not (isinstance(fid, str) and _FID.match(fid)): + note(f"{where}: bad id {fid!r} (F1..F999)") + continue + if fid in ids: + note(f"{where}: duplicate id {fid}") + ids.append(fid) + where = fid + if not (isinstance(item["title"], str) and item["title"].strip() and isinstance(item["objective"], str) and item["objective"].strip()): + note(f"{where}: title and objective must be non-empty strings") + if not (isinstance(item["req_ids"], list) and item["req_ids"]): + note(f"{where}: req_ids must name at least one spec requirement (every feature traces to a section)") + else: + for rid in item["req_ids"]: + if rid not in req_ids: + note(f"{where}: req_ids names unknown requirement {rid!r}") + if not (isinstance(item["depends_on"], list) and all(isinstance(x, str) for x in item["depends_on"])): + note(f"{where}: depends_on must be a list of feature ids") + elif len(set(item["depends_on"])) != len(item["depends_on"]) or fid in item["depends_on"]: + note(f"{where}: depends_on repeats an id or names itself") + scope = item["scope"] + if not (isinstance(scope, dict) and set(scope) == {"paths", "exclude", "max_files", "max_diff_bytes"}): + note(f"{where}: scope must be exactly {{paths, exclude, max_files, max_diff_bytes}}") + else: + paths = scope["paths"] + if not (isinstance(paths, list) and paths and all(isinstance(p, str) and p.strip() for p in paths)): + note(f"{where}: scope.paths must be a non-empty list of strings") + elif any(p.startswith("/") or ".." in p.split("/") or p.strip() in (".", "./") for p in paths): + note(f"{where}: scope.paths must be repository-relative, without '..', and not the whole tree") + if not (isinstance(scope["exclude"], list) and all(isinstance(p, str) for p in scope["exclude"])): + note(f"{where}: scope.exclude must be a list of strings") + for key, ceiling in (("max_files", MAX_FILES_CEILING), ("max_diff_bytes", MAX_DIFF_BYTES_CEILING)): + value = scope[key] + if type(value) is not int or not 1 <= value <= ceiling: + note(f"{where}: scope.{key} must be an int 1..{ceiling} (size check)") + if not isinstance(item["overlaps"], list): + note(f"{where}: overlaps must be a list") + else: + for overlap in item["overlaps"]: + if not (isinstance(overlap, dict) and set(overlap) == {"with", "paths", "order"} and isinstance(overlap["with"], str) + and isinstance(overlap["paths"], list) and isinstance(overlap["order"], str)): + note(f"{where}: overlap entries must be exactly {{with, paths, order}}") + elif overlap["order"] not in (f"{fid}_first", f"{overlap['with']}_first"): + note(f"{where}: overlap with {overlap['with']} has order {overlap['order']!r}; it must be '{fid}_first' or '{overlap['with']}_first'") + if item["act_class"] not in ACT_CLASSES: + note(f"{where}: act_class must be one of {ACT_CLASSES}") + criteria = item["criteria"] + if not (isinstance(criteria, list) and 1 <= len(criteria) <= MAX_CRITERIA): + note(f"{where}: criteria must be a list of 1..{MAX_CRITERIA} (what the builder is shown)") + else: + seen = set() + for criterion in criteria: + if not (isinstance(criterion, dict) and set(criterion) == {"id", "text", "kind"}): + note(f"{where}: criterion fields must be exactly id, text, kind") + continue + if not (isinstance(criterion["id"], str) and re.match(rf"^{re.escape(fid)}\.c[0-9]+$", criterion["id"])) or criterion["id"] in seen: + note(f"{where}: bad or duplicate criterion id {criterion.get('id')!r}") + seen.add(criterion["id"]) + if not (isinstance(criterion["text"], str) and criterion["text"].strip()): + note(f"{where}: criterion {criterion['id']} has empty text") + if criterion["kind"] not in ("test", "judgment"): + note(f"{where}: criterion {criterion['id']} kind must be test or judgment") + hidden = item["hidden_checks"] + if not (isinstance(hidden, list) and all(isinstance(h, str) and _CHECK.match(h) for h in hidden)): + note(f"{where}: hidden_checks must be a list of check names (names only; the checks stay with the host)") + else: + for name in hidden: + if name in check_names and check_names[name] != fid: + note(f"{where}: hidden check {name!r} is also named by {check_names[name]}") + check_names.setdefault(name, fid) + if item["size"] not in SIZES: + note(f"{where}: size must be S, M or L") + risk = item["risk_inputs"] + if not (isinstance(risk, dict) and set(risk) == {"new_dependencies", "needs_lookup", "disagreement"} + and type(risk["new_dependencies"]) is int and risk["new_dependencies"] >= 0 + and isinstance(risk["needs_lookup"], bool) + and isinstance(risk["disagreement"], (int, float)) and not isinstance(risk["disagreement"], bool) + and math.isfinite(risk["disagreement"]) and 0 <= risk["disagreement"] <= 1): + note(f"{where}: risk_inputs must be {{new_dependencies: int >= 0, needs_lookup: bool, disagreement: 0..1}}") + if findings: + return findings + by_id = {f["id"]: f for f in features} + for item in features: + for dep in item["depends_on"]: + if dep not in by_id: + note(f"{item['id']}: depends_on names unknown feature {dep!r}") + for overlap in item["overlaps"]: + if overlap["with"] not in by_id or overlap["with"] == item["id"]: + note(f"{item['id']}: overlap names unknown feature {overlap['with']!r}") + if findings: + return findings + deps = {f["id"]: list(f["depends_on"]) for f in features} + cycle = find_cycle(deps) + if cycle: + note("depends_on has a cycle: " + " -> ".join(cycle)) + # coverage: every requirement is traced by a feature or listed as uncovered with a reason, never both + uncovered = document["uncovered"] + listed = set() + if not isinstance(uncovered, list): + note("uncovered must be a list") + else: + for entry in uncovered: + if not (isinstance(entry, dict) and set(entry) == {"req_id", "reason"} and entry["req_id"] in req_ids + and isinstance(entry["reason"], str) and entry["reason"].strip()): + note(f"uncovered entry {entry!r} must be {{req_id: , reason: }}") + else: + listed.add(entry["req_id"]) + covered = {rid: sorted(f["id"] for f in features if rid in f["req_ids"]) for rid in req_ids} + for rid in req_ids: + if not covered[rid] and rid not in listed: + note(f"requirement {rid} is covered by no feature and is not listed as uncovered") + if covered[rid] and rid in listed: + note(f"requirement {rid} is both covered ({covered[rid]}) and listed as uncovered") + # conflicts: an intersection must be declared, with one order that does not contradict the DAG + ancestors_ = ancestors(deps) if not cycle else {} + for i, a in enumerate(ids): + for b in ids[i + 1:]: + intersection = scope_intersection(by_id[a], by_id[b]) + declared = ([o for o in by_id[a]["overlaps"] if o["with"] == b] + [o for o in by_id[b]["overlaps"] if o["with"] == a]) + if intersection and not declared: + note(f"scope conflict: {a} and {b} both claim {intersection} and declare no overlap") + if declared and not intersection: + note(f"{a} and {b} declare an overlap but their scopes do not intersect") + orders = {o["order"] for o in declared} + if len(orders) > 1: + note(f"{a} and {b} declare contradictory overlap orders {sorted(orders)}") + elif orders and ancestors_: + first = next(iter(orders))[: -len("_first")] + second = b if first == a else a + if second in ancestors_.get(first, set()): + note(f"overlap order {first}_first contradicts depends_on ({first} depends on {second})") + approval = document["approval"] + if approval is not None and not approved(document): + note("approval is present but stale or not by a human: it does not cover this map's digest") + return findings + + +def find_cycle(deps: dict[str, list[str]]) -> list[str] | None: + white, grey, black = 0, 1, 2 + colour = {k: white for k in deps} + stack: list[str] = [] + + def visit(node): + colour[node] = grey + stack.append(node) + for other in deps.get(node, []): + if other not in colour: + continue + if colour[other] == grey: + return stack[stack.index(other):] + [other] + if colour[other] == white: + found = visit(other) + if found: + return found + stack.pop() + colour[node] = black + return None + + for node in deps: + if colour[node] == white: + found = visit(node) + if found: + return found + return None + + +def ancestors(deps: dict[str, list[str]]) -> dict[str, set[str]]: + """Transitive dependencies (what each feature waits for).""" + memo: dict[str, set[str]] = {} + + def go(node): + if node not in memo: + memo[node] = set() + for dep in deps.get(node, []): + memo[node] |= {dep} | go(dep) + return memo[node] + + for node in deps: + go(node) + return memo + + +# -- task graph ----------------------------------------------------------------------------------------------------- + +def taskgraph(document: dict) -> dict: + """Critical path (forward and backward pass over size durations), total work and the work/critical-path + ratio (the most concurrency that can pay), Dilworth width with one maximum antichain (bipartite matching + and Koenig's construction), topological levels, slack, and the conflict graph of scope intersections.""" + features = document["features"] + ids = [f["id"] for f in features] + order = {fid: i for i, fid in enumerate(ids)} + deps = {f["id"]: list(f["depends_on"]) for f in features} + if find_cycle(deps): + raise Rejected("map_cyclic", "the task graph has a cycle; run mapcheck first") + duration = {f["id"]: DURATION[f["size"]] for f in features} + anc = ancestors(deps) + children = {fid: [g for g in ids if fid in deps[g]] for fid in ids} + topo = _topological(ids, deps, children, order) + est, eft = {}, {} + for node in topo: + est[node] = max((eft[d] for d in deps[node]), default=0) + eft[node] = est[node] + duration[node] + length = max(eft.values()) if eft else 0 + bottom = {} + for node in reversed(topo): + bottom[node] = duration[node] + max((bottom[c] for c in children[node]), default=0) + slack = {node: length - (est[node] + bottom[node]) for node in ids} + path, current = [], None + heads = [n for n in ids if not deps[n] and slack[n] == 0] + current = min(heads, key=order.get) if heads else None + while current: + path.append(current) + nxt = [c for c in children[current] if slack[c] == 0 and est[c] == eft[current]] + current = min(nxt, key=order.get) if nxt else None + level = {} + for node in topo: + level[node] = 0 if not deps[node] else 1 + max(level[d] for d in deps[node]) + antichain = _max_antichain(ids, anc) + conflicts = [] + by_id = {f["id"]: f for f in features} + for i, a in enumerate(ids): + for b in ids[i + 1:]: + intersection = scope_intersection(by_id[a], by_id[b]) + if intersection: + conflicts.append({"a": a, "b": b, "paths": intersection, "ordered_by_dag": a in anc[b] or b in anc[a]}) + total = sum(duration.values()) + return {"features": len(ids), "edges": sum(len(v) for v in deps.values()), "durations": duration, + "topological_order": topo, "topo_level": level, "earliest_start": est, "bottom_level": bottom, "slack": slack, + "critical_path": path, "critical_path_length": length, "total_work": total, + "work_critical_ratio": round(total / length, 3) if length else 0.0, + "width": len(antichain), "max_antichain": antichain, "conflicts": conflicts, + "descendants": {fid: sum(1 for g in ids if fid in anc[g]) for fid in ids}} + + +def _topological(ids, deps, children, order) -> list[str]: + indegree = {n: len(deps[n]) for n in ids} + ready = sorted([n for n in ids if indegree[n] == 0], key=order.get) + out = [] + while ready: + node = ready.pop(0) + out.append(node) + for child in children[node]: + indegree[child] -= 1 + if indegree[child] == 0: + ready.append(child) + ready.sort(key=order.get) + return out + + +def _max_antichain(ids: list[str], anc: dict[str, set[str]]) -> list[str]: + """Dilworth: width = n - |maximum matching| over the strict order a < b; Koenig recovers an antichain.""" + adjacent = {a: [b for b in ids if a in anc[b]] for a in ids} + match_right: dict[str, str] = {} + + def augment(u, seen): + for v in adjacent[u]: + if v in seen: + continue + seen.add(v) + if v not in match_right or augment(match_right[v], seen): + match_right[v] = u + return True + return False + + for u in ids: + augment(u, set()) + match_left = {u: v for v, u in match_right.items()} + left_reach, right_reach = set(u for u in ids if u not in match_left), set() + stack = list(left_reach) + while stack: + u = stack.pop() + for v in adjacent[u]: + if v not in right_reach: + right_reach.add(v) + w = match_right.get(v) + if w is not None and w not in left_reach: + left_reach.add(w) + stack.append(w) + cover_left, cover_right = set(ids) - left_reach, right_reach + antichain = [x for x in ids if x not in cover_left and x not in cover_right] + if len(antichain) != len(ids) - len(match_right): + raise Rejected("taskgraph_internal", "Koenig construction mismatch") + return antichain + + +# -- risk and the verification plan --------------------------------------------------------------------------------- + +def risk_inputs(item: dict, graph: dict) -> dict: + """The seven standardized inputs in [0, 1], all computable by code from the map and the graph.""" + scope = item["scope"] + n = graph["features"] + criteria = item["criteria"] + mechanical = sum(1 for c in criteria if c["kind"] == "test") + return {"scope": round(0.5 * scope["max_files"] / MAX_FILES_CEILING + 0.5 * scope["max_diff_bytes"] / MAX_DIFF_BYTES_CEILING, 4), + "act_class": ACT_RISK[item["act_class"]], + "new_deps": min(1.0, item["risk_inputs"]["new_dependencies"] / 2), + "needs_lookup": 1.0 if item["risk_inputs"]["needs_lookup"] else 0.0, + "disagreement": float(item["risk_inputs"]["disagreement"]), + "centrality": round(graph["descendants"][item["id"]] / max(1, n - 1), 4), + "uncovered": round(1 - mechanical / len(criteria), 4) if criteria else 1.0} + + +def risk_score(inputs: dict, weights: dict = WEIGHTS) -> float: + return round(sum(weights[k] * inputs[k] for k in weights), 4) + + +def softmax(values: list[float], tau: float) -> list[float]: + top = max(values) + exps = [math.exp((v - top) / tau) for v in values] + total = sum(exps) + return [e / total for e in exps] + + +def integer_units(shares: list[float], budget: int) -> list[int]: + """Largest-remainder rounding of ``budget * shares`` to integers that sum to ``budget``.""" + raw = [budget * s for s in shares] + base = [math.floor(x) for x in raw] + remainder = budget - sum(base) + order = sorted(range(len(shares)), key=lambda i: (-(raw[i] - base[i]), i)) + for i in order[:remainder]: + base[i] += 1 + return base + + +def ladder(units: int) -> list[str]: + rungs = list(LADDER[: min(units, len(LADDER))]) + if units > len(LADDER): + rungs.append(f"extra_seeds_x{2 * (units - len(LADDER))}") + return rungs + + +def risk_plan(document: dict, graph: dict | None = None, *, budget: int | None = None, tau: float = 1.0, + weights: dict = WEIGHTS) -> dict: + """Standardized risk scores and the softmax allocation of ``budget`` extra verification units above the floor. + + ``z_i = (r_i - mean) / sd`` so tau is in standard deviations of this map's spread (a map whose raw scores + spread over 0.14 would otherwise be allocated uniformly at any stated tau); with one feature or zero + spread the allocation is uniform. ``share`` is the propensity each unit had of landing on a feature and is + recorded with the plan, so later calibration can reweight. The floor is listed beside every allocation and is + the same for every feature: it is what a low score can never buy its way out of.""" + graph = graph or taskgraph(document) + if tau < TAU_MIN: + raise Rejected("risk_tau", f"tau must be at least {TAU_MIN} so every feature keeps a positive propensity") + features = document["features"] + ids = [f["id"] for f in features] + budget = len(ids) if budget is None else budget + if type(budget) is not int or budget < 0: + raise Rejected("risk_budget", "the verification budget is a non-negative integer number of units") + inputs = {f["id"]: risk_inputs(f, graph) for f in features} + scores = [risk_score(inputs[fid], weights) for fid in ids] + mean = sum(scores) / len(scores) + spread = math.sqrt(sum((s - mean) ** 2 for s in scores) / len(scores)) + z = [((s - mean) / spread) if spread > 0 else 0.0 for s in scores] + shares = softmax(z, tau) + units = integer_units(shares, budget) + return {"schema": "syberfactory/verification-plan.v1", "map_digest": map_digest(document), "weights": dict(weights), + "tau": tau, "budget": budget, "standardized": spread > 0, + "inputs": inputs, "r": dict(zip(ids, scores)), "z": {fid: round(v, 4) for fid, v in zip(ids, z)}, + "share": {fid: round(s, 4) for fid, s in zip(ids, shares)}, "units": dict(zip(ids, units)), + "floor": list(FLOOR), "buys": {fid: list(FLOOR) + ladder(u) for fid, u in zip(ids, units)}} + + +# -- compile: one feature -> one ticket (D5) ------------------------------------------------------------------------- + +def compile_ticket(document: dict, item: dict, spec: dict, *, human_owner: str, baseline_run: str | None = None, + space: dict | None = None) -> dict: + """The work order of one feature in ``ticket_from_spec``'s shape. ``human_owner`` is mandatory: agents are + delegated to, a person stays accountable. ``rubric_digest`` covers the hidden-check names the host holds; + the checks' content is never in the ticket, which a builder may read. With a Space graph the footprint's + components are the owners of the scope's files; without one no component is claimed.""" + if not isinstance(human_owner, str) or not human_owner.strip(): + raise Rejected("ticket_owner", "a ticket names the accountable human; none given") + requirements = {r["req_id"]: r for r in spec["requirements"]} + kinds: list[str] = [] + for rid in item["req_ids"]: + for kind in requirements[rid]["evidence_kinds"]: + if kind not in kinds: + kinds.append(kind) + components = sorted({record["component"] for path, record in (space or {}).get("files", {}).items() + if record.get("component") and any(path_intersects(p, path) for p in item["scope"]["paths"])}) + sha = map_digest(document) + return { + "protocol": PROTOCOL, "kind": "ticket", + "ticket_id": digest({"map": sha, "feature": item["id"]})[:16], + "title": item["title"][:120], + "spec_ref": {"spec_id": spec["spec_id"], "version": spec["version"], "req_ids": list(item["req_ids"])}, + "map_ref": {"map_id": document["id"], "map_digest": sha, "feature_id": item["id"]}, + "objective": item["objective"], + "acceptance_criteria": [dict(c) for c in item["criteria"]], + "footprint": {"components": components, "files": sorted(item["scope"]["paths"]), + "revision": document["base"], "space_digest": None}, + "scope": {k: (list(v) if isinstance(v, list) else v) for k, v in item["scope"].items()}, + "depends_on": list(item["depends_on"]), "act_class": item["act_class"], "size": item["size"], + "repro": {"baseline_run": baseline_run}, + "exit_criteria": [f"evidence:{kind}" for kind in kinds] + [f"hidden:{name}" for name in item["hidden_checks"]], + "rubric_digest": digest(sorted(item["hidden_checks"])) if item["hidden_checks"] else None, + "delegate": None, "human_owner": human_owner.strip(), + "state": "open", "candidates": [], "verdicts": [], "evidence_links": [], + } + + +def compile_tickets(document: dict, spec: dict, *, human_owner: str, baseline_run: str | None = None, + space: dict | None = None) -> list[dict]: + """Every feature, in map order. Refuses a map that fails ``mapcheck``.""" + findings = mapcheck(document, spec) + if findings: + raise Rejected("map_invalid", "; ".join(findings)) + return [compile_ticket(document, item, spec, human_owner=human_owner, baseline_run=baseline_run, space=space) + for item in document["features"]] diff --git a/syberlabs/factory/loop.py b/syberlabs/factory/loop.py new file mode 100644 index 0000000..288f4fb --- /dev/null +++ b/syberlabs/factory/loop.py @@ -0,0 +1,532 @@ +"""The thin-slice driver (AM1): an approved feature map, compiled to tickets, built by Build Threads, stopped by an envelope. + + loop = Loop(repo_root=".", kit_home=".syberlabs", ledger=Ledger(".syberlabs/factory"), map=document, spec=spec, + envelope=envelope, policy=OfflinePolicy(), proposer_argv=[python, "standin.py", "."], + checks={"tests": {"argv": [python, "-m", "unittest", "-q"], "timeout_seconds": 300}}, + hidden_catalogue={"hidden.f1.marker": [python, "-c", "..."]}, human_owner="mateo") + loop.compile() # refuses a map without a current owner approval; tickets go on the ledger + summary = loop.run() # features end "ready for owner merge", parked, escalated or waiting; nothing merges + +What it does, in order, every step: reads the kill switch; computes the eligible features from the map and +the record (dependencies ready, declared overlap order respected, act class inside the envelope, attempts +left, room in the envelope); asks the policy ``next_feature``, ``proposer_arm`` and ``budget_tier`` (each +answer is recorded on the factory ledger as a proposal before anything happens); reserves the tier on the +envelope ledger; starts one unattended Build Thread on a contract compiled from the feature's ticket (its +scope is the feature's scope, its checks are the repository's visible checks plus the hidden checks the +host holds under the names the ticket lists); runs the proposer command once through ``CommandProvider``; +then drives the thread with ``syberlabs run``'s own ``Runner`` (consolidation D17: recover, check and +accept are the kernel's, never re-implemented here) until the pass is idle; settles the envelope from the +thread's journal; and records the outcome. A failed attempt asks ``worth_continuing`` and ``after_failure``. + +What it never does: merge, push, open a pull request, edit the map, the spec, the envelope or a contract +after compile, call a model or a network. The terminal state of a feature is ``ready_for_owner_merge``: an +accepted candidate on ``syberlabs/``, with the thread id and commit on the ledger for the owner. + +Events go on #154's ledger. Its event vocabulary is owned by ``ledger.py`` (and by the goal-gate packet +that is editing it), so this slice writes its events as ``note`` with ``body.note`` naming the autonomy +event and ``body.refs`` holding the values that differ between two runs of the same fixture (thread ids, +commits, seconds). ``event_digests`` digests every autonomy event without ``refs``, so two runs of one +fixture give one list of digests. Tickets use the existing ``ticket_opened`` kind with ``source: map``. + +The envelope ledger (D13) is the eval spend ledger's shape (one JSON object per line, appended before the +work and settled after it, read strictly) generalized to attempts: ``reserve`` before an attempt holds the +tier's dollars and one call, ``settle`` replaces the hold with what the journal recorded, ``stop`` closes +the run with a reason. Totals are the settled values plus unsettled holds, so a killed attempt stays counted. +""" + +from __future__ import annotations + +import json +import math +import time +from pathlib import Path + +from syberlabs.build import ACT_CLASSES, PROMOTE, Kit, Runner +from syberlabs.canonical import canonical, digest +from syberlabs.errors import Rejected +from syberlabs.factory import PROTOCOL, featuremap, policy as policymod +from syberlabs.providers import CommandProvider + +ENVELOPE_SCHEMA = "syberfactory/envelope.v1" +ENVELOPE_LINE_SCHEMA = "syberlabs.factory/envelope-ledger.v1" +ENVELOPE_FILE = "envelope.jsonl" +ACTIONS = ("start_thread", "propose", "check", "accept_to_thread_branch") # closed; no merge, push or publish +EVENTS = ("map_frozen", "policy_proposal", "envelope_reserved", "envelope_settled", "attempt_started", "thread_step", + "feature_ready", "feature_failed", "feature_parked", "feature_escalated", "feature_waiting", "loop_stopped") +STATES = ("open", "building", "ready_for_owner_merge", "parked", "escalated", "waiting_owner_merge") +MAX_PASSES = 8 # Runner passes per attempt: check, accept, idle; more only when evidence ages or recovery runs + + +# -- the envelope ---------------------------------------------------------------------------------------------------- + +def new_envelope(map_digest: str, *, dollars_total: float, calls_total: int, seconds_total: float, + attempts_per_feature: int = 2, tiers: dict | None = None, arms: list[dict] | None = None, + act_classes: tuple = ("R",), max_candidates: int = 3, kill_switch: str | None = None) -> dict: + """The owner's grant: what the loop may spend, which classes it may build, which arms it may run.""" + tiers = tiers or {"S": 0.0, "M": 0.0, "L": 0.0} + arms = arms or [{"id": "standin", "tier_rank": 0, "revision": "standin"}] + if set(tiers) != set(policymod.TIERS) or any(not isinstance(v, (int, float)) or v < 0 for v in tiers.values()): + raise Rejected("envelope_invalid", "tiers must price S, M and L with non-negative dollars") + if not arms or any(not isinstance(a, dict) or not a.get("id") for a in arms): + raise Rejected("envelope_invalid", "arms must be a non-empty list of {id, tier_rank, revision}") + if any(c not in ACT_CLASSES for c in act_classes): + raise Rejected("envelope_invalid", f"act_classes must be from {ACT_CLASSES}") + for name, value in (("dollars_total", dollars_total), ("seconds_total", seconds_total)): + if not isinstance(value, (int, float)) or isinstance(value, bool) or not math.isfinite(value) or value < 0: + raise Rejected("envelope_invalid", f"{name} must be a finite number of at least 0") + if type(calls_total) is not int or calls_total < 0 or type(attempts_per_feature) is not int or attempts_per_feature < 1: + raise Rejected("envelope_invalid", "calls_total is an int of at least 0 and attempts_per_feature an int of at least 1") + return {"schema": ENVELOPE_SCHEMA, "map_digest": map_digest, + "dollars": {"total": float(dollars_total), "tiers": {k: float(tiers[k]) for k in policymod.TIERS}}, + "calls": {"total": calls_total}, "seconds": {"total": float(seconds_total)}, + "attempts_per_feature": attempts_per_feature, "concurrency": 1, "act_classes": sorted(act_classes), + "arms": [dict(a) for a in arms], "actions": list(ACTIONS), "max_candidates": max_candidates, + "kill_switch": kill_switch} + + +def envelope_digest(envelope: dict) -> str: + return digest(envelope) + + +def _strict_loads(text: str): + def no_repeats(pairs): + out = {} + for key, value in pairs: + if key in out: + raise ValueError(f"repeated key {key!r}") + out[key] = value + return out + + def no_constant(name): + raise ValueError(f"non-finite number {name}") + + return json.loads(text, object_pairs_hook=no_repeats, parse_constant=no_constant) + + +class EnvelopeLedger: + """Append-only lines under the factory home. Reserve, settle, stop; totals from the lines.""" + + def __init__(self, path: str | Path, envelope: dict): + self.path, self.envelope = Path(path), envelope + self.path.parent.mkdir(parents=True, exist_ok=True) + + def lines(self) -> list[dict]: + if not self.path.is_file(): + return [] + out = [] + for number, raw in enumerate(self.path.read_text(encoding="utf-8").splitlines(), 1): + if not raw.strip(): + continue + try: + value = _strict_loads(raw) + except ValueError as exc: + raise Rejected("envelope_unreadable", f"{self.path}: line {number}: {exc}") from None + if not isinstance(value, dict) or value.get("schema") != ENVELOPE_LINE_SCHEMA: + raise Rejected("envelope_unreadable", f"{self.path}: line {number} is not an envelope ledger line") + out.append(value) + return out + + def _append(self, line: dict) -> dict: + line = {"schema": ENVELOPE_LINE_SCHEMA, "envelope_digest": envelope_digest(self.envelope), **line} + with self.path.open("a", encoding="utf-8", newline="\n") as handle: + handle.write(canonical(line) + "\n") + handle.flush() + return line + + def totals(self) -> dict: + reserved: dict[tuple, dict] = {} + settled: dict[tuple, dict] = {} + stopped = None + for line in self.lines(): + key = (line.get("feature"), line.get("attempt")) + if line["kind"] == "reserve": + reserved[key] = line + elif line["kind"] == "settle": + settled[key] = line + elif line["kind"] == "stop": + stopped = line["reason"] + dollars = calls = seconds = 0.0 + for key, hold in reserved.items(): + actual = settled.get(key, hold) + dollars += float(actual["dollars"]) + calls += int(actual["calls"]) + seconds += float(actual["seconds"]) + return {"dollars": round(dollars, 6), "calls": int(calls), "seconds": round(seconds, 3), "attempts": len(reserved), + "unsettled": len(set(reserved) - set(settled)), "stopped": stopped, + "dollars_left": round(self.envelope["dollars"]["total"] - dollars, 6), + "calls_left": self.envelope["calls"]["total"] - int(calls), + "seconds_left": round(self.envelope["seconds"]["total"] - seconds, 3)} + + def room(self, tier: str, calls: int = 1) -> bool: + totals = self.totals() + return (totals["stopped"] is None and totals["dollars_left"] >= self.envelope["dollars"]["tiers"][tier] + and totals["calls_left"] >= calls and totals["seconds_left"] > 0) + + def reserve(self, feature: str, attempt: int, tier: str, arm: str) -> dict: + if not self.room(tier): + raise Rejected("envelope_exhausted", f"no room for tier {tier} on {feature}: {self.totals()}") + return self._append({"kind": "reserve", "feature": feature, "attempt": attempt, "tier": tier, "arm": arm, + "dollars": self.envelope["dollars"]["tiers"][tier], "calls": 1, "seconds": 0.0}) + + def settle(self, feature: str, attempt: int, *, dollars: float, calls: int, seconds: float, unknown_models: list) -> dict: + if not isinstance(dollars, (int, float)) or not math.isfinite(dollars) or dollars < 0: + raise Rejected("envelope_unpriced", f"{feature} attempt {attempt}: dollars are not a finite number of at least 0") + return self._append({"kind": "settle", "feature": feature, "attempt": attempt, "dollars": float(dollars), "calls": int(calls), + "seconds": round(float(seconds), 3), "unknown_models": list(unknown_models)}) + + def stop(self, reason: str) -> dict: + return self._append({"kind": "stop", "reason": reason}) + + +# -- ledger events ----------------------------------------------------------------------------------------------------- + +def record(ledger, note: str, map_digest: str, body: dict, refs: dict | None = None) -> dict: + if note not in EVENTS: + raise Rejected("autonomy_event", f"unknown autonomy event {note!r}") + return ledger.append("note", {"note": note, "map_digest": map_digest, **body, "refs": dict(refs or {})}) + + +def autonomy_events(ledger, map_digest: str | None = None) -> list[dict]: + """The slice's events in ledger order: ``note`` events it wrote and ``ticket_opened`` with ``source: map``.""" + out = [] + for event in ledger.events(): + body = event["body"] + if event["kind"] == "note" and body.get("note") in EVENTS or event["kind"] == "ticket_opened" and body.get("source") == "map": + if map_digest is None or body.get("map_digest") == map_digest: + out.append(event) + return out + + +def event_digests(ledger, map_digest: str | None = None) -> list[str]: + """One digest per autonomy event over its kind and body without ``refs``: the same fixture gives the same list.""" + return [digest({"kind": e["kind"], "body": {k: v for k, v in e["body"].items() if k != "refs"}}) + for e in autonomy_events(ledger, map_digest)] + + +def why(ledger, ticket_id: str) -> dict: + """The §1.3 walk as far as the ledger goes: ticket -> feature -> map (its approval) -> spec reference.""" + opened = next((e for e in ledger.events() if e["kind"] == "ticket_opened" and e["body"].get("ticket_id") == ticket_id), None) + if opened is None: + raise Rejected("ticket_unknown", f"no ticket_opened event for {ticket_id}") + body = opened["body"] + frozen = next((e for e in ledger.events() if e["kind"] == "note" and e["body"].get("note") == "map_frozen" + and e["body"].get("map_digest") == body.get("map_digest")), None) + ready = next((e for e in ledger.events() if e["kind"] == "note" and e["body"].get("note") == "feature_ready" + and e["body"].get("ticket_id") == ticket_id), None) + return {"ticket": ticket_id, "feature": body.get("feature_id"), "requirements": body.get("req_ids"), + "map": {"digest": body.get("map_digest"), "frozen_seq": frozen["seq"] if frozen else None, + "approved_by": (frozen or {}).get("body", {}).get("approved_by")}, + "spec": {"spec_id": body.get("spec_id"), "version": body.get("version"), "digest": (frozen or {}).get("body", {}).get("spec_digest")}, + "ready_for_owner_merge": {"seq": ready["seq"], **ready["body"]["refs"]} if ready else None} + + +# -- contracts ----------------------------------------------------------------------------------------------------------- + +def feature_contract(ticket: dict, *, checks: dict, hidden_catalogue: dict, max_candidates: int) -> dict: + """One ``repo-change``-shaped contract per ticket: scope from the feature, the visible checks plus the hidden + checks the host holds under the ticket's names, every check required. The id carries the ticket id so a + changed map never collides with a published contract (contracts are immutable once installed).""" + found = {name: {"argv": list(c["argv"]), "timeout_seconds": int(c.get("timeout_seconds", 300))} for name, c in checks.items()} + for exit_criterion in ticket["exit_criteria"]: + if not exit_criterion.startswith("hidden:"): + continue + name = exit_criterion[len("hidden:"):] + argv = hidden_catalogue.get(name) + if not argv: + raise Rejected("hidden_check_unknown", f"ticket {ticket['ticket_id']} names hidden check {name!r} the host does not hold") + if name in found: + raise Rejected("hidden_check_collision", f"hidden check {name!r} has the name of a visible check") + found[name] = {"argv": list(argv), "timeout_seconds": 120} + if not found: + raise Rejected("contract_unchecked", "a feature contract needs at least one check") + return {"id": f"syberfactory-{ticket['ticket_id']}", "version": 1, "title": ticket["title"], + "inputs": {"objective": "string", "act_class": "string"}, + "actions": {PROMOTE: {}}, "acceptance": [{"id": "accepted", "kind": "effect", "action": PROMOTE}], + "evolution": {"scope": dict(ticket["scope"]), "operators": ["patch"], + "budget": {"max_candidates": max_candidates, "max_evaluations": 2 * max_candidates, "max_seconds": 900}, + "evaluation": {"checks": found, "required": sorted(found), "max_age_seconds": 3600}, + "promotion": {"action": PROMOTE, "roles": ["developer"]}}} + + +# -- the loop ------------------------------------------------------------------------------------------------------------- + +class Loop: + def __init__(self, *, repo_root: str | Path, kit_home: str | Path, ledger, map: dict, spec: dict, envelope: dict, + policy, proposer_argv: list[str], checks: dict, hidden_catalogue: dict | None = None, human_owner: str, + baseline_run: str | None = None, actor: str = "factory@syberlabs.host", log=None, max_passes: int = MAX_PASSES): + self.repo_root, self.kit_home, self.ledger = Path(repo_root), Path(kit_home), ledger + self.map, self.spec, self.envelope, self.policy = map, spec, envelope, policy + self.proposer_argv, self.checks, self.hidden = list(proposer_argv), dict(checks), dict(hidden_catalogue or {}) + self.human_owner, self.baseline_run, self.actor = human_owner, baseline_run, actor + self.log = log or (lambda line: None) + self.max_passes = max_passes + self.map_digest = featuremap.map_digest(map) + if envelope.get("map_digest") != self.map_digest: + raise Rejected("envelope_map", "the envelope names a different map digest") + self.spend = EnvelopeLedger(self.ledger.home / ENVELOPE_FILE, envelope) + self.graph = None + self.plan = None + self.tickets: dict[str, dict] = {} + self.features = {f["id"]: f for f in map["features"]} + self.state = {fid: {"state": "open", "attempts": 0, "dollars": 0.0, "thread": None, "commit": None, "last_reason": None} + for fid in self.features} + self.kit = None + self.order: list[str] = [] + + # -- compile ----------------------------------------------------------------------------------------------------------- + + def compile(self) -> list[dict]: + """Refuse a map without a current owner approval or with findings; write one contract per feature; log + ``map_frozen`` and one ``ticket_opened`` per feature. Idempotent for one map digest.""" + if not featuremap.approved(self.map): + raise Rejected("map_unapproved", "the loop runs only an owner-approved map whose approval covers its current digest") + if self.spec.get("state") not in ("promoted", "canonical"): + raise Rejected("spec_state", f"work opens under a promoted spec, not one in state {self.spec.get('state')!r}") + findings = featuremap.mapcheck(self.map, self.spec) + if findings: + raise Rejected("map_invalid", "; ".join(findings)) + self.graph = featuremap.taskgraph(self.map) + self.plan = featuremap.risk_plan(self.map, self.graph) + tickets = featuremap.compile_tickets(self.map, self.spec, human_owner=self.human_owner, baseline_run=self.baseline_run, + space=self.ledger.latest_space()) + contracts = self.kit_home / "contracts" + contracts.mkdir(parents=True, exist_ok=True) + for ticket in tickets: + contract = feature_contract(ticket, checks=self.checks, hidden_catalogue=self.hidden, + max_candidates=self.envelope["max_candidates"]) + path = contracts / f"{contract['id']}.v{contract['version']}.json" + if not path.exists(): + path.write_text(json.dumps(contract, indent=2, sort_keys=True) + "\n", encoding="utf-8") + self.tickets[ticket["map_ref"]["feature_id"]] = ticket + already = any(e["body"].get("note") == "map_frozen" and e["body"].get("map_digest") == self.map_digest + for e in self.ledger.events() if e["kind"] == "note") + if not already: + record(self.ledger, "map_frozen", self.map_digest, { + "map_id": self.map["id"], "spec_id": self.spec["spec_id"], "spec_version": self.spec["version"], + "spec_digest": self.map["spec_ref"]["spec_digest"], "approved_by": self.map["approval"]["actor"], + "envelope_digest": envelope_digest(self.envelope), "features": [f["id"] for f in self.map["features"]], + "critical_path": self.graph["critical_path"], "critical_path_length": self.graph["critical_path_length"], + "width": self.graph["width"], "work_critical_ratio": self.graph["work_critical_ratio"], + "risk": self.plan["r"], "verification_units": self.plan["units"], "tau": self.plan["tau"], "floor": self.plan["floor"]}) + for ticket in tickets: + self.ledger.append("ticket_opened", { + "ticket_id": ticket["ticket_id"], "spec_id": self.spec["spec_id"], "version": self.spec["version"], + "req_id": ticket["spec_ref"]["req_ids"][0], "req_ids": ticket["spec_ref"]["req_ids"], "source": "map", + "map_digest": self.map_digest, "feature_id": ticket["map_ref"]["feature_id"], + "footprint": ticket["footprint"]["components"], "files": ticket["footprint"]["files"], + "revision": self.map["base"], "rubric_digest": ticket["rubric_digest"], "human_owner": ticket["human_owner"]}) + return tickets + + # -- state and eligibility -------------------------------------------------------------------------------------------- + + def _ready(self, fid: str) -> bool: + return self.state[fid]["state"] == "ready_for_owner_merge" + + def eligible(self) -> list[str]: + out = [] + for fid, item in self.features.items(): + row = self.state[fid] + if row["state"] != "open": + continue + if item["act_class"] not in self.envelope["act_classes"]: + row["state"] = "escalated" + record(self.ledger, "feature_escalated", self.map_digest, {"feature": fid, "reason": f"act_class_{item['act_class']}_outside_envelope"}) + continue + if not all(self._ready(d) for d in item["depends_on"]): + continue + if item["depends_on"] and self.map["integration"] == "await_merge": + row["state"] = "waiting_owner_merge" + record(self.ledger, "feature_waiting", self.map_digest, {"feature": fid, "waits_for": list(item["depends_on"])}) + continue + if any(o["order"] == f"{o['with']}_first" and not self._ready(o["with"]) and self.state[o["with"]]["state"] == "open" + for o in item["overlaps"]): + continue # the declared order says the other feature's scope goes first + if row["attempts"] >= self.envelope["attempts_per_feature"]: + continue + out.append(fid) + return out + + def policy_state(self) -> dict: + """Ids and numbers only.""" + totals = self.spend.totals() + tiers = self.envelope["dollars"]["tiers"] + return {"features": {fid: {"bottom_level": self.graph["bottom_level"][fid], "slack": self.graph["slack"][fid], + "topo_level": self.graph["topo_level"][fid], "risk": self.plan["r"][fid], + "size_units": featuremap.DURATION[self.features[fid]["size"]], + "act_rank": featuremap.ACT_RANK[self.features[fid]["act_class"]], + "attempts": self.state[fid]["attempts"], + "attempts_left": self.envelope["attempts_per_feature"] - self.state[fid]["attempts"], + "dollars_used": self.state[fid]["dollars"], "map_order": self.order.index(fid), + "state": STATES.index(self.state[fid]["state"])} for fid in self.features}, + "envelope": {"dollars_left": totals["dollars_left"], "calls_left": totals["calls_left"], "seconds_left": totals["seconds_left"], + "smallest_tier_dollars": min(tiers.values()), "attempts_per_feature": self.envelope["attempts_per_feature"], + "arms": [{"id": a["id"], "tier_rank": a.get("tier_rank", 0)} for a in self.envelope["arms"]], + "tiers": dict(tiers)}} + + def ask(self, key: str, feature: str | None, options: list[str], numbers: dict | None = None) -> policymod.Answer: + question = policymod.Question(key, feature, tuple(options), dict(numbers or {})) + answer = policymod.ask(self.policy, self.policy_state(), question) + record(self.ledger, "policy_proposal", self.map_digest, {"question": key, "feature": feature, "options": list(options), + "answer": answer.record(), "policy": getattr(self.policy, "name", "policy")}) + self.log(f"policy {key} {feature or '-'} -> {answer.value} ({answer.source}, {answer.reason})" + + (f"; shadow {answer.shadow['policy']} would say {answer.shadow['value']}" if answer.shadow else "")) + return answer + + # -- run ---------------------------------------------------------------------------------------------------------------- + + def run(self, max_steps: int = 50) -> dict: + if not self.tickets: + self.compile() + self.order = [f["id"] for f in self.map["features"]] + kill = self.envelope.get("kill_switch") + stopped = None + self.kit = Kit.local(self.kit_home, self.repo_root, actor=self.actor) + try: + for _ in range(max_steps): + if kill and Path(kill).exists(): + stopped = "kill_switch" + break + if self.spend.totals()["stopped"]: + stopped = self.spend.totals()["stopped"] + break + eligible = self.eligible() + if not eligible: + stopped = "nothing_eligible" + break + tiers = [t for t in policymod.TIERS if self.spend.room(t)] + if not tiers: + stopped = "envelope_exhausted" + break + chosen = self.ask("next_feature", None, eligible).value + arms = [a["id"] for a in self.envelope["arms"]] + arm = self.ask("proposer_arm", chosen, arms).value + tier = self.ask("budget_tier", chosen, tiers).value + self._attempt(chosen, arm, tier) + else: + stopped = "max_steps" + finally: + self.kit.close() + self.spend.stop(stopped) + record(self.ledger, "loop_stopped", self.map_digest, {"reason": stopped, "states": {fid: row["state"] for fid, row in self.state.items()}, + "calls": self.spend.totals()["calls"], "dollars": self.spend.totals()["dollars"]}) + return self.summary(stopped) + + def summary(self, stopped: str | None = None) -> dict: + totals = self.spend.totals() + return {"stopped": stopped or totals["stopped"], "map_digest": self.map_digest, + "features": {fid: {"state": row["state"], "attempts": row["attempts"], "ticket": self.tickets.get(fid, {}).get("ticket_id"), + "thread": row["thread"], "commit": row["commit"], "last_reason": row["last_reason"]} + for fid, row in self.state.items()}, + "ready_for_owner_merge": [fid for fid, row in self.state.items() if row["state"] == "ready_for_owner_merge"], + "envelope": totals, "events": len(autonomy_events(self.ledger, self.map_digest))} + + def _attempt(self, fid: str, arm_id: str, tier: str) -> None: + item, ticket, row = self.features[fid], self.tickets[fid], self.state[fid] + row["attempts"] += 1 + attempt = row["attempts"] + self.spend.reserve(fid, attempt, tier, arm_id) + record(self.ledger, "envelope_reserved", self.map_digest, {"feature": fid, "attempt": attempt, "tier": tier, "arm": arm_id, + "dollars": self.envelope["dollars"]["tiers"][tier]}) + arm = next(a for a in self.envelope["arms"] if a["id"] == arm_id) + started = time.monotonic() + stacked = None + if item["depends_on"] and self.map["integration"] == "stack": + stacked = self.state[item["depends_on"][-1]]["commit"] # one branch: the last dependency's accepted commit + self.kit.repo.git("checkout", "-q", "-B", f"syberfactory/{self.map['id']}/{fid}", stacked) + objective = f"{fid}: {ticket['objective']}\nCriteria: " + "; ".join(f"{c['id']} {c['text']}" for c in ticket["acceptance_criteria"]) + contract = f"syberfactory-{ticket['ticket_id']}.v1" + thread = self.kit.start(objective, contract=contract, paths=item["scope"]["paths"], act_class=item["act_class"], unattended=True) + row["state"], row["thread"] = "building", thread.id + record(self.ledger, "attempt_started", self.map_digest, {"feature": fid, "attempt": attempt, "ticket_id": ticket["ticket_id"], + "arm": arm_id, "tier": tier, "contract": contract, "stacked": stacked is not None}, + refs={"thread": thread.id, "base": thread.base, "stacked_on": stacked}) + provider = CommandProvider(self.proposer_argv, name=_name(arm_id), revision=str(arm.get("revision", "1")), + timeout=int(arm.get("timeout_seconds", 300))) + outcome, reason = "failed", None + try: + candidates = thread.propose(provider) + if not candidates: + reason = "no_candidate" + else: + outcome, reason = self._drive(thread, fid, attempt) + except Rejected as exc: + reason = exc.code + seconds = time.monotonic() - started + dollars, unknown = _spend(thread.history()) + row["dollars"] = round(row["dollars"] + dollars, 6) + self.spend.settle(fid, attempt, dollars=dollars, calls=provider.calls, seconds=seconds, unknown_models=unknown) + record(self.ledger, "envelope_settled", self.map_digest, {"feature": fid, "attempt": attempt, "dollars": dollars, + "calls": provider.calls, "unknown_models": unknown}, + refs={"seconds": round(seconds, 3)}) + if outcome == "accepted": + accepted = next(v for v in thread._views() if v["authoritative"]) + row["state"], row["commit"], row["last_reason"] = "ready_for_owner_merge", accepted["commit"], None + record(self.ledger, "feature_ready", self.map_digest, {"feature": fid, "attempt": attempt, "ticket_id": ticket["ticket_id"], + "exit_criteria": ticket["exit_criteria"], "next": "owner merges; nothing here merges"}, + refs={"thread": thread.id, "commit": accepted["commit"], "target_ref": thread.target_ref}) + self.log(f"{fid} ready for owner merge: {thread.target_ref} at {accepted['commit'][:10]}") + return + row["last_reason"] = reason + record(self.ledger, "feature_failed", self.map_digest, {"feature": fid, "attempt": attempt, "reason": reason}, refs={"thread": thread.id}) + self._after_failure(fid) + + def _drive(self, thread, fid: str, attempt: int) -> tuple[str, str | None]: + """``syberlabs run``'s passes over this one thread until nothing is left: the kernel checks, accepts and + recovers; this records what each pass did.""" + runner = Runner(self.kit, thread=thread.id, log=self.log) + for number in range(1, self.max_passes + 1): + steps = runner.once() + for step in steps: + record(self.ledger, "thread_step", self.map_digest, {"feature": fid, "attempt": attempt, "pass": number, "step": step.step, + "outcome": step.outcome, "reason": step.reason}, refs={"thread": thread.id}) + if any(s.step == "accept" and s.outcome == "succeeded" for s in steps): + return "accepted", None + refused = [s for s in steps if s.refused] + if refused: + return "failed", refused[0].reason or refused[0].outcome + if all(s.step in ("idle", "skip") for s in steps): + idle = steps[-1] if steps else None + return "failed", (idle.reason if idle else "no_step") + return "failed", "passes_exhausted" + + def _after_failure(self, fid: str) -> None: + row, item = self.state[fid], self.features[fid] + left = self.envelope["attempts_per_feature"] - row["attempts"] + options = ["continue", "stop"] if left > 0 else ["stop"] + worth = self.ask("worth_continuing", fid, options).value + choices = [] + if worth == "continue" and left > 0: + choices.append("retry_same") + if len(self.envelope["arms"]) > 1: + choices.append("retry_escalate_arm") + choices += ["escalate_owner", "park"] + decision = self.ask("after_failure", fid, choices).value + if decision in ("retry_same", "retry_escalate_arm"): + row["state"] = "open" # eligible again; the next step may pick it or another feature + return + row["state"] = "escalated" if decision == "escalate_owner" else "parked" + record(self.ledger, "feature_escalated" if decision == "escalate_owner" else "feature_parked", self.map_digest, + {"feature": fid, "reason": row["last_reason"], "attempts": row["attempts"]}) + + +def _name(arm_id: str) -> str: + cleaned = "".join(c if c.isalnum() or c in "_.-" else "-" for c in arm_id.lower()) + return (cleaned if cleaned[:1].isalpha() else "arm-" + cleaned)[:64] + + +def _spend(history: list[dict]) -> tuple[float, list[str]]: + """Host-observed dollars from the thread's finished searches, and the models the host could not price.""" + dollars, unknown = 0.0, [] + for event in history: + if event["kind"] == "search_finished" and isinstance(event["body"].get("spend"), dict): + spend = event["body"]["spend"] + dollars += float(spend.get("dollars") or 0.0) + unknown += [m for m in spend.get("unknown_models", []) if m not in unknown] + return round(dollars, 6), unknown + + +def load_json(path: str | Path, what: str) -> dict: + try: + return _strict_loads(Path(path).read_text(encoding="utf-8")) + except (OSError, ValueError) as exc: + raise Rejected(f"{what}_unreadable", f"{path}: {type(exc).__name__}: {exc}") from None diff --git a/syberlabs/factory/policy.py b/syberlabs/factory/policy.py new file mode 100644 index 0000000..7179371 --- /dev/null +++ b/syberlabs/factory/policy.py @@ -0,0 +1,187 @@ +"""FeaturePolicy: the five typed questions a loop over a feature map asks, with closed answer sets. + +A policy decides nothing. It proposes: ``decide(state, question)`` returns an ``Answer`` whose value is one of +the options code built before the question was asked, and the loop records the answer on the factory ledger +as a proposal before it acts on it. An answer outside the options is refused (``policy_invalid``) and never +acted on. The state a policy reads is ids and numbers (owner decision 1): feature ids, graph positions, risk +scores, attempts, dollars and calls. No titles, criteria, diffs, check output or paths. + +The questions (autonomous design, section 4.2), each with the option set code builds: + +- ``next_feature`` (choice): the eligible features (dependencies satisfied, no conflicting scope running, act + class allowed, room in the envelope, attempts left). With no eligible feature the loop stops; no question. +- ``proposer_arm`` (choice): the envelope's arms that fit the remaining dollars. +- ``budget_tier`` (choice): the tiers whose ceiling fits the remaining dollars (``S``, ``M``, ``L``). +- ``after_failure`` (choice): ``retry_same``, ``retry_escalate_arm``, ``escalate_owner``, ``park``; an option is + removed when the caps forbid it (no attempts left removes the retries). +- ``worth_continuing`` (choice over ``continue`` and ``stop``): may only stop early, never extend a cap. + +``OfflinePolicy`` is the default (owner decision 7): critical path first (highest bottom level, then higher +risk, then map order) for ``next_feature``, the cheapest arm and tier that fit, retry then escalate the arm +then park after a failure, stop when the envelope has no room. ``ShadowPolicy`` wraps an acting policy and a +second one that only answers: what it would have said is recorded beside the acting answer and never acted +on (Jev stays in shadow until E7). The shadow is an injected callable; nothing here imports or calls a +network client. +""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from typing import Any, Callable, Protocol + +from syberlabs.errors import Rejected + +QUESTIONS = ("next_feature", "proposer_arm", "budget_tier", "after_failure", "worth_continuing") +TIERS = ("S", "M", "L") +AFTER_FAILURE = ("retry_same", "retry_escalate_arm", "escalate_owner", "park") +WORTH = ("continue", "stop") +SOURCES = ("offline", "shadow", "rule") + + +@dataclass(frozen=True) +class Question: + key: str + feature: str | None + options: tuple[str, ...] + numbers: dict = field(default_factory=dict) # ids and numbers only; what a remote policy would be sent + + def __post_init__(self): + if self.key not in QUESTIONS: + raise Rejected("policy_question", f"unknown question {self.key!r}; one of {QUESTIONS}") + if not self.options or len(set(self.options)) != len(self.options): + raise Rejected("policy_question", f"{self.key}: options must be a non-empty list without repeats") + closed = {"budget_tier": TIERS, "after_failure": AFTER_FAILURE, "worth_continuing": WORTH}.get(self.key) + if closed is not None and any(o not in closed for o in self.options): + raise Rejected("policy_question", f"{self.key}: options must come from {closed}") + + +@dataclass +class Answer: + key: str + value: str + source: str + reason: str + probabilities: dict | None = None + shadow: dict | None = None + + def record(self) -> dict: + return {"key": self.key, "value": self.value, "source": self.source, "reason": self.reason, + "probabilities": self.probabilities, "shadow": self.shadow} + + +class FeaturePolicy(Protocol): + name: str + + def decide(self, state: dict, question: Question) -> Answer: ... + + +def validate(question: Question, answer: Any, source: str) -> Answer: + """An answer is an ``Answer`` or a plain value; either way its value must be one of the options sent.""" + if isinstance(answer, Answer): + value, reason, probabilities = answer.value, answer.reason, answer.probabilities + elif isinstance(answer, dict): + value, reason, probabilities = answer.get("value"), answer.get("reason", "cleared"), answer.get("probabilities") + else: + value, reason, probabilities = answer, "cleared", None + if value not in question.options: + raise Rejected("policy_invalid", f"{source} answered {value!r} to {question.key}; the options were {list(question.options)}") + if probabilities is not None: + if not isinstance(probabilities, dict) or set(probabilities) != set(question.options): + raise Rejected("policy_invalid", f"{source}: probabilities must cover exactly the options sent") + for option, p in probabilities.items(): + if isinstance(p, bool) or not isinstance(p, (int, float)) or not 0 <= p <= 1 or p != p: + raise Rejected("policy_invalid", f"{source}: probability for {option!r} is not a number in [0, 1]") + if abs(sum(probabilities.values()) - 1) > 0.02: + raise Rejected("policy_invalid", f"{source}: probabilities sum to {sum(probabilities.values()):.3f}, not 1") + return Answer(question.key, value, source, str(reason), probabilities) + + +class OfflinePolicy: + """Deterministic rules over the state's numbers. The default.""" + name = "offline" + + def decide(self, state: dict, question: Question) -> Answer: + features = state["features"] + if question.key == "next_feature": + pick = max(question.options, key=lambda fid: (features[fid]["bottom_level"], features[fid]["risk"], -features[fid]["map_order"])) + return Answer(question.key, pick, self.name, "rule:critical_path_first") + if question.key == "proposer_arm": + arms = {arm["id"]: arm for arm in state["envelope"]["arms"]} + pick = min(question.options, key=lambda a: (arms[a].get("tier_rank", 0), question.options.index(a))) + return Answer(question.key, pick, self.name, "rule:cheapest_arm") + if question.key == "budget_tier": + attempts = features[question.feature]["attempts"] + wanted = TIERS[min(attempts, len(TIERS) - 1)] + pick = wanted if wanted in question.options else question.options[0] + return Answer(question.key, pick, self.name, "rule:cheapest_tier_that_fits") + if question.key == "after_failure": + # First failure: the same arm again. Later failures with attempts left: a stronger arm when the envelope + # has one, else the owner. No retry offered (the cap is spent): park; the ledger holds the reason. + attempts = features[question.feature]["attempts"] + retry = [o for o in question.options if o.startswith("retry_")] + if attempts <= 1 and "retry_same" in retry: + return Answer(question.key, "retry_same", self.name, "rule:first_failure_retry") + if "retry_escalate_arm" in retry: + return Answer(question.key, "retry_escalate_arm", self.name, "rule:escalate_arm") + if retry and "escalate_owner" in question.options: + return Answer(question.key, "escalate_owner", self.name, "rule:no_stronger_arm") + pick = "park" if "park" in question.options else question.options[-1] + return Answer(question.key, pick, self.name, "rule:attempts_spent") + if question.key == "worth_continuing": + envelope = state["envelope"] + room = envelope["dollars_left"] >= envelope["smallest_tier_dollars"] and envelope["calls_left"] > 0 + left = features[question.feature]["attempts_left"] > 0 + pick = "continue" if (room and left and "continue" in question.options) else "stop" + return Answer(question.key, pick, self.name, "rule:room_and_attempts" if pick == "continue" else "rule:stop_on_envelope") + raise Rejected("policy_question", f"offline policy has no rule for {question.key}") + + +class ShadowPolicy: + """Act on ``acting``; ask ``shadow`` the same question and record what it would have answered. + + ``shadow(state, question)`` is any callable, injected by the caller: a recorded-answer selector, a test + stub, or later an adapter that reuses ``jev_api``'s request and validation code. Its answer is validated + against the same options; an invalid or failing shadow is recorded as such (``shadow.reason``) and changes + nothing. The acting answer is returned unchanged, with ``shadow`` filled in.""" + name = "shadow" + + def __init__(self, acting: FeaturePolicy, shadow: Callable[[dict, Question], Any], *, shadow_name: str = "shadow"): + self.acting, self.shadow, self.shadow_name = acting, shadow, shadow_name + self.disagreements = 0 + + def decide(self, state: dict, question: Question) -> Answer: + answer = validate(question, self.acting.decide(state, question), self.acting.name) + try: + would = validate(question, self.shadow(state, question), self.shadow_name) + record = {"policy": self.shadow_name, "value": would.value, "probabilities": would.probabilities, + "agrees": would.value == answer.value, "reason": "recorded"} + except Rejected as exc: + record = {"policy": self.shadow_name, "value": None, "probabilities": None, "agrees": None, "reason": exc.code} + except Exception as exc: # a shadow that breaks never breaks the loop + record = {"policy": self.shadow_name, "value": None, "probabilities": None, "agrees": None, + "reason": f"shadow_error:{type(exc).__name__}"} + if record["agrees"] is False: + self.disagreements += 1 + answer.shadow = record + return answer + + +def recorded_answers(answers: dict[str, Any]) -> Callable[[dict, Question], Any]: + """A shadow over a fixture: ``answers`` maps ``""`` or ``":"`` to a value or + ``{"value", "probabilities"}``. A question with no recorded answer raises, which the shadow wrapper + records as ``shadow_unanswered``.""" + def shadow(state: dict, question: Question): + for key in (f"{question.key}:{question.feature}", question.key): + if key in answers: + return answers[key] + raise Rejected("shadow_unanswered", f"no recorded answer for {question.key}") + return shadow + + +def ask(policy: FeaturePolicy, state: dict, question: Question) -> Answer: + """One validated proposal. The caller records it before acting.""" + answer = policy.decide(state, question) + source = answer.source if isinstance(answer, Answer) else getattr(policy, "name", "policy") + checked = validate(question, answer, source) + checked.shadow = answer.shadow if isinstance(answer, Answer) else None + return checked diff --git a/tests/fixtures/autonomy/hidden_checks.json b/tests/fixtures/autonomy/hidden_checks.json new file mode 100644 index 0000000..b109720 --- /dev/null +++ b/tests/fixtures/autonomy/hidden_checks.json @@ -0,0 +1,6 @@ +{ + "_comment": "The host's hidden-check catalogue: name -> argv, run in the candidate's worktree. '{python}' is the interpreter. The map names these checks; the worktree never holds them.", + "hidden.f1.marker": ["{python}", "-c", "import sys, pathlib; sys.exit(0 if pathlib.Path('fxapp/rules.py').read_text().rstrip().endswith('# F1 delivered') else 1)"], + "hidden.f2.marker": ["{python}", "-c", "import sys, pathlib; t = pathlib.Path('fxapp/ingest.py').read_text(); r = pathlib.Path('fxapp/rules.py').read_text(); sys.exit(0 if t.rstrip().endswith('# F2 delivered') and '# F1 delivered' in r else 1)"], + "hidden.f3.marker": ["{python}", "-c", "import sys, pathlib; sys.exit(0 if pathlib.Path('fxapp/variants.py').read_text().rstrip().endswith('# F3 delivered') else 1)"] +} diff --git a/tests/fixtures/autonomy/map.json b/tests/fixtures/autonomy/map.json new file mode 100644 index 0000000..39acc75 --- /dev/null +++ b/tests/fixtures/autonomy/map.json @@ -0,0 +1,40 @@ +{ + "schema": "syberfactory/feature-map.v1", + "id": "order-markers.m1", + "spec_ref": {"spec_id": "order-markers", "version": 1, "spec_digest": ""}, + "base": null, + "author": {"kind": "human", "id": "fixture"}, + "features": [ + { + "id": "F1", "title": "Rules reviewed", "objective": "Append the F1 delivery marker to fxapp/rules.py", + "req_ids": ["R1"], "depends_on": [], + "scope": {"paths": ["fxapp/rules.py"], "exclude": [], "max_files": 1, "max_diff_bytes": 2000}, + "overlaps": [], "act_class": "R", + "criteria": [{"id": "F1.c1", "text": "fxapp/rules.py ends with the line '# F1 delivered'", "kind": "test"}], + "hidden_checks": ["hidden.f1.marker"], "size": "S", + "risk_inputs": {"new_dependencies": 0, "needs_lookup": false, "disagreement": 0.1} + }, + { + "id": "F2", "title": "Ingest reviewed after rules", "objective": "Append the F2 delivery marker to fxapp/ingest.py", + "req_ids": ["R2"], "depends_on": ["F1"], + "scope": {"paths": ["fxapp/ingest.py"], "exclude": [], "max_files": 1, "max_diff_bytes": 2000}, + "overlaps": [], "act_class": "R", + "criteria": [{"id": "F2.c1", "text": "fxapp/ingest.py ends with the line '# F2 delivered'", "kind": "test"}], + "hidden_checks": ["hidden.f2.marker"], "size": "S", + "risk_inputs": {"new_dependencies": 0, "needs_lookup": false, "disagreement": 0.0} + }, + { + "id": "F3", "title": "Variants reviewed", "objective": "Append the F3 delivery marker to fxapp/variants.py", + "req_ids": ["R3"], "depends_on": [], + "scope": {"paths": ["fxapp/variants.py"], "exclude": [], "max_files": 1, "max_diff_bytes": 2000}, + "overlaps": [], "act_class": "R", + "criteria": [{"id": "F3.c1", "text": "fxapp/variants.py ends with the line '# F3 delivered'", "kind": "test"}, + {"id": "F3.c2", "text": "the entrypoints keep their names", "kind": "judgment"}], + "hidden_checks": ["hidden.f3.marker"], "size": "M", + "risk_inputs": {"new_dependencies": 0, "needs_lookup": false, "disagreement": 0.0} + } + ], + "uncovered": [], + "integration": "stack", + "approval": null +} diff --git a/tests/fixtures/autonomy/spec.md b/tests/fixtures/autonomy/spec.md new file mode 100644 index 0000000..547b6ae --- /dev/null +++ b/tests/fixtures/autonomy/spec.md @@ -0,0 +1,16 @@ +# Order markers (fixture spec for the autonomy thin slice) + +Sectioned Markdown with ids (owner decision 11, 2026-10-28). Each `##` section is one requirement of #154's spec +object; the bullets are its scenarios. The three features of `map.json` trace to these sections. + +## R1: The rules module records that its decision thresholds were reviewed. + +- given fxapp/rules.py, when the feature is delivered, then the module ends with the delivery marker for F1 + +## R2: The ingest module records that its normalization was reviewed after the rules. + +- given fxapp/ingest.py, when the feature is delivered after F1, then the module ends with the delivery marker for F2 + +## R3: The variants module records that its entrypoints were reviewed. + +- given fxapp/variants.py, when the feature is delivered, then the module ends with the delivery marker for F3 diff --git a/tests/fixtures/autonomy/standin_proposer.py b/tests/fixtures/autonomy/standin_proposer.py new file mode 100644 index 0000000..c252be3 --- /dev/null +++ b/tests/fixtures/autonomy/standin_proposer.py @@ -0,0 +1,34 @@ +"""A stand-in proposer for the autonomy thin slice: the process boundary a model adapter would sit behind. + +Usage: ``standin_proposer.py REPO_ROOT [--break | --outside]``. It reads the search request on stdin (the +thread's objective, its scope and the file list), takes the first scope path, reads that file from REPO_ROOT's +working tree, and answers one candidate that appends the feature's delivery marker (``# F1 delivered``) to it. +``--break`` appends a line that is not Python instead, so the visible check fails; ``--outside`` edits a path +outside the scope, which the host refuses as out of scope. No model, no network, no cost. +""" + +import json +import sys +from pathlib import Path + + +def main(argv: list[str]) -> int: + root = Path(argv[0]) + mode = argv[1] if len(argv) > 1 else "" + request = json.load(sys.stdin) + feature = request["objective"].split(":", 1)[0].strip() + path = request["scope"][0] + text = (root / path).read_text(encoding="utf-8") + if mode == "--break": + changes = {path: text.rstrip("\n") + "\nthis line is not python\n"} + elif mode == "--outside": + changes = {"fxapp/main.py": "# edited outside the feature's scope\n"} + else: + changes = {path: text.rstrip("\n") + f"\n\n# {feature} delivered\n"} + json.dump({"candidates": [{"changes": changes, "message": f"{feature}: delivery marker", "signal": None}], + "recommended": [0]}, sys.stdout) + return 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) diff --git a/tests/test_factory_autonomy.py b/tests/test_factory_autonomy.py new file mode 100644 index 0000000..706f6c6 --- /dev/null +++ b/tests/test_factory_autonomy.py @@ -0,0 +1,451 @@ +"""The autonomy thin slice (AM1) on the fixture app: spec -> approved feature map -> tickets on the ledger -> Build +Threads driven by the runner with a stand-in proposer -> features ready for the owner's merge, inside an envelope. +Offline, no model, no network, no merge.""" + +import json +import os +import shutil +import subprocess +import sys +import tempfile +import unittest +from pathlib import Path + +from syberlabs.errors import Rejected +from syberlabs.factory import featuremap, ledger, loop, space +from syberlabs.factory import policy as policymod +from syberlabs.factory import spec as specmod + +ROOT = Path(__file__).resolve().parents[1] +APP = ROOT / "tests" / "fixtures" / "factory_app" +AUTONOMY = ROOT / "tests" / "fixtures" / "autonomy" +DECLARED = json.loads((APP / "architecture.json").read_text(encoding="utf-8")) +OWNER = {"kind": "human", "id": "tester"} +GIT_ENV = {"GIT_AUTHOR_NAME": "t", "GIT_AUTHOR_EMAIL": "t@example.test", "GIT_COMMITTER_NAME": "t", + "GIT_COMMITTER_EMAIL": "t@example.test", "GIT_AUTHOR_DATE": "2026-01-01T00:00:00Z", + "GIT_COMMITTER_DATE": "2026-01-01T00:00:00Z"} + + +def promoted_spec(project: Path) -> dict: + """The fixture spec as #154's object: from sectioned Markdown, footprint resolved against Space, validated, promoted.""" + document = featuremap.spec_from_markdown((AUTONOMY / "spec.md").read_text(encoding="utf-8"), "order-markers", + "delivery markers on the order path", ["rules", "ingest", "main"], author=OWNER) + graph = space.index(project, revision="base") + space.map_components(graph, DECLARED) + specmod.resolve_footprint(document, graph) + specmod.transition(document, "validate", OWNER, space=graph) + specmod.transition(document, "promote", OWNER, verdict_ids=["review-1"]) + return document + + +def fixture_map(document: dict, base: str, **overrides) -> dict: + mapping = json.loads((AUTONOMY / "map.json").read_text(encoding="utf-8")) + mapping["spec_ref"]["spec_digest"] = specmod.spec_digest(document) + mapping["base"] = base + mapping.update(overrides) + return mapping + + +def hidden_catalogue() -> dict: + raw = json.loads((AUTONOMY / "hidden_checks.json").read_text(encoding="utf-8")) + return {name: [arg.replace("{python}", sys.executable) for arg in argv] for name, argv in raw.items() if not name.startswith("_")} + + +class Scratch(unittest.TestCase): + def setUp(self): + self.scratch = Path(tempfile.mkdtemp(prefix="autonomy-")) + self.addCleanup(shutil.rmtree, self.scratch, True) + + def project(self, name="project") -> tuple[Path, str]: + """A copy of the fixture app as a Git repository with a deterministic base commit.""" + project = self.scratch / name + shutil.copytree(APP, project) + env = {**os.environ, **GIT_ENV} + git = lambda *a: subprocess.run(["git", "-C", str(project), *a], check=True, capture_output=True, text=True, env=env).stdout.strip() + git("init", "-q", "-b", "main") + git("add", ".") + git("-c", "commit.gpgsign=false", "commit", "-qm", "base") + return project, git("rev-parse", "HEAD") + + def make_loop(self, project: Path, mapping: dict, document: dict, *, calls_total=10, attempts=2, mode="", policy=None, + kill_switch=None, ledger_name="ledger") -> loop.Loop: + home = ledger.Ledger(self.scratch / ledger_name) + envelope = loop.new_envelope(featuremap.map_digest(mapping), dollars_total=0.0, calls_total=calls_total, seconds_total=600, + attempts_per_feature=attempts, kill_switch=kill_switch) + argv = [sys.executable, str(AUTONOMY / "standin_proposer.py"), str(project)] + ([mode] if mode else []) + checks = {"tests": {"argv": [sys.executable, "-c", "import fxapp.main, fxapp.variants"], "timeout_seconds": 60}} + return loop.Loop(repo_root=project, kit_home=project / ".syberlabs", ledger=home, map=mapping, spec=document, envelope=envelope, + policy=policy or policymod.OfflinePolicy(), proposer_argv=argv, checks=checks, hidden_catalogue=hidden_catalogue(), + human_owner="tester") + + +class SpecAndMap(Scratch): + def test_sectioned_markdown_becomes_the_spec_object(self): + document = featuremap.spec_from_markdown((AUTONOMY / "spec.md").read_text(encoding="utf-8"), "order-markers", "cap", ["rules"]) + self.assertEqual([r["req_id"] for r in document["requirements"]], ["R1", "R2", "R3"]) + self.assertEqual(document["requirements"][0]["scenarios"][0]["given"], "fxapp/rules.py") + self.assertEqual(document["requirements"][0]["scenarios"][0]["then"], "the module ends with the delivery marker for F1") + self.assertEqual(document["state"], "draft") + with self.assertRaises(Rejected): + featuremap.spec_from_markdown("no sections here", "x", "y", ["rules"]) + + def test_fixture_map_validates_and_the_task_graph_measures(self): + project, base = self.project() + document = promoted_spec(project) + mapping = fixture_map(document, base) + self.assertEqual(featuremap.mapcheck(mapping, document), []) + graph = featuremap.taskgraph(mapping) + self.assertEqual(graph["critical_path"], ["F1", "F2"]) + self.assertEqual(graph["critical_path_length"], 2) + self.assertEqual(graph["total_work"], 4, "S + S + M") + self.assertEqual(graph["work_critical_ratio"], 2.0) + self.assertEqual(graph["width"], 2) + self.assertIn(sorted(graph["max_antichain"]), (["F1", "F3"], ["F2", "F3"]), "either pair is a maximum antichain") + self.assertEqual(graph["bottom_level"], {"F1": 2, "F2": 1, "F3": 2}) + self.assertEqual(graph["conflicts"], []) + featuremap.approve(mapping, OWNER) + self.assertTrue(featuremap.approved(mapping)) + self.assertEqual(featuremap.mapcheck(mapping, document), []) + mapping["features"][0]["title"] = "edited after approval" + self.assertFalse(featuremap.approved(mapping)) + self.assertIn("approval is present but stale", featuremap.mapcheck(mapping, document)[0]) + with self.assertRaises(Rejected) as refused: + featuremap.approve(mapping, {"kind": "model", "id": "claude"}) + self.assertEqual(refused.exception.code, "approval_actor") + + def test_mapcheck_refuses_a_cycle_flags_a_scope_conflict_and_checks_coverage(self): + project, base = self.project() + document = promoted_spec(project) + cyclic = fixture_map(document, base) + cyclic["features"][0]["depends_on"] = ["F2"] + findings = featuremap.mapcheck(cyclic, document) + self.assertTrue(any("cycle" in f for f in findings), findings) + with self.assertRaises(Rejected) as refused: + featuremap.taskgraph(cyclic) + self.assertEqual(refused.exception.code, "map_cyclic") + conflict = fixture_map(document, base) + conflict["features"][2]["scope"]["paths"] = ["fxapp/"] + findings = featuremap.mapcheck(conflict, document) + self.assertTrue(any(f.startswith("scope conflict: F1 and F3") for f in findings), findings) + self.assertTrue(any(f.startswith("scope conflict: F2 and F3") for f in findings), findings) + declared = fixture_map(document, base) + declared["features"][2]["scope"]["paths"] = ["fxapp/"] + declared["features"][2]["overlaps"] = [{"with": "F1", "paths": ["fxapp/rules.py"], "order": "F1_first"}, + {"with": "F2", "paths": ["fxapp/ingest.py"], "order": "F2_first"}] + self.assertEqual(featuremap.mapcheck(declared, document), [], "a declared overlap with an order is not a finding") + declared["features"][2]["depends_on"] = ["F1"] + declared["features"][2]["overlaps"][0]["order"] = "F3_first" + self.assertTrue(any("contradicts depends_on" in f for f in featuremap.mapcheck(declared, document))) + uncovered = fixture_map(document, base) + uncovered["features"][2]["req_ids"] = ["R1"] + findings = featuremap.mapcheck(uncovered, document) + self.assertIn("requirement R3 is covered by no feature and is not listed as uncovered", findings) + uncovered["uncovered"] = [{"req_id": "R3", "reason": "deferred to the next map"}] + self.assertEqual(featuremap.mapcheck(uncovered, document), []) + unknown = fixture_map(document, base) + unknown["features"][0]["req_ids"] = ["R9"] + self.assertIn("F1: req_ids names unknown requirement 'R9'", featuremap.mapcheck(unknown, document)) + stale = fixture_map(document, base) + stale["spec_ref"]["spec_digest"] = "0" * 64 + self.assertTrue(any("spec changed after the map" in f for f in featuremap.mapcheck(stale, document))) + shared = fixture_map(document, base) + shared["features"][1]["hidden_checks"] = ["hidden.f1.marker"] + self.assertTrue(any("also named by F1" in f for f in featuremap.mapcheck(shared, document))) + + def test_risk_plan_keeps_the_floor_and_allocates_softmax_units(self): + project, base = self.project() + document = promoted_spec(project) + mapping = fixture_map(document, base) + plan = featuremap.risk_plan(mapping, budget=4, tau=1.0) + self.assertEqual(sum(plan["units"].values()), 4) + self.assertTrue(plan["standardized"]) + self.assertAlmostEqual(sum(plan["share"].values()), 1.0, places=3) + for fid, buys in plan["buys"].items(): + self.assertEqual(buys[: len(featuremap.FLOOR)], list(featuremap.FLOOR), f"{fid} keeps the floor") + self.assertGreater(plan["r"]["F1"], plan["r"]["F2"], "F1 has a dependent and disagreement; F2 has neither") + self.assertEqual(plan["inputs"]["F3"]["uncovered"], 0.5, "one of F3's two criteria has no mechanical check") + sharp = featuremap.risk_plan(mapping, budget=4, tau=0.1) + self.assertGreaterEqual(max(sharp["share"].values()), max(plan["share"].values()), "a lower tau concentrates") + with self.assertRaises(Rejected): + featuremap.risk_plan(mapping, tau=0.01) + flat = fixture_map(document, base) + for item in flat["features"]: + item["depends_on"], item["size"], item["criteria"] = [], "S", [{"id": f"{item['id']}.c1", "text": "x", "kind": "test"}] + item["risk_inputs"]["disagreement"] = 0.0 + plan = featuremap.risk_plan(flat, budget=3) + self.assertFalse(plan["standardized"]) + self.assertEqual(plan["units"], {"F1": 1, "F2": 1, "F3": 1}, "zero spread allocates uniformly") + + def test_a_feature_compiles_to_one_ticket_in_the_spec_ticket_shape(self): + project, base = self.project() + document = promoted_spec(project) + mapping = fixture_map(document, base) + featuremap.approve(mapping, OWNER) + graph = space.index(project, revision="base") + space.map_components(graph, DECLARED) + tickets = featuremap.compile_tickets(mapping, document, human_owner="tester", baseline_run=None, space=graph) + self.assertEqual(len(tickets), 3) + ticket = tickets[1] + reference = specmod.ticket_from_spec(document, "R2", human_owner="tester") + self.assertEqual(set(reference) - set(ticket), set(), "every key of ticket_from_spec's shape is present") + self.assertEqual(ticket["ticket_id"], featuremap.digest({"map": featuremap.map_digest(mapping), "feature": "F2"})[:16]) + self.assertEqual(ticket["footprint"]["files"], ["fxapp/ingest.py"]) + self.assertEqual(ticket["footprint"]["components"], ["ingest"], "the Space graph's owner of the scope's files") + bare = featuremap.compile_ticket(mapping, mapping["features"][1], document, human_owner="tester") + self.assertEqual(bare["footprint"]["components"], [], "no Space graph, no component claim") + self.assertEqual(ticket["exit_criteria"], ["evidence:tests", "hidden:hidden.f2.marker"]) + self.assertEqual(ticket["rubric_digest"], featuremap.digest(["hidden.f2.marker"])) + self.assertEqual(ticket["map_ref"], {"map_id": "order-markers.m1", "map_digest": featuremap.map_digest(mapping), "feature_id": "F2"}) + self.assertEqual(ticket["acceptance_criteria"], mapping["features"][1]["criteria"]) + self.assertEqual(ticket["depends_on"], ["F1"]) + with self.assertRaises(Rejected) as refused: + featuremap.compile_ticket(mapping, mapping["features"][0], document, human_owner="") + self.assertEqual(refused.exception.code, "ticket_owner") + degenerate = featuremap.degenerate_map(document, base=base, author=OWNER) + self.assertEqual(featuremap.mapcheck(degenerate, document), [], "one feature per requirement, overlaps declared") + self.assertEqual([f["req_ids"] for f in degenerate["features"]], [["R1"], ["R2"], ["R3"]]) + + +class Policies(unittest.TestCase): + STATE = {"features": {"F1": {"bottom_level": 2, "risk": 0.2, "map_order": 0, "attempts": 0, "attempts_left": 2}, + "F3": {"bottom_level": 2, "risk": 0.1, "map_order": 2, "attempts": 0, "attempts_left": 2}}, + "envelope": {"dollars_left": 0.0, "calls_left": 1, "seconds_left": 10, "smallest_tier_dollars": 0.0, + "arms": [{"id": "cheap", "tier_rank": 0}, {"id": "strong", "tier_rank": 1}], "tiers": {"S": 0, "M": 0, "L": 0}}} + + def test_offline_rules(self): + offline = policymod.OfflinePolicy() + answer = policymod.ask(offline, self.STATE, policymod.Question("next_feature", None, ("F1", "F3"))) + self.assertEqual((answer.value, answer.reason), ("F1", "rule:critical_path_first")) + self.assertEqual(policymod.ask(offline, self.STATE, policymod.Question("proposer_arm", "F1", ("strong", "cheap"))).value, "cheap") + self.assertEqual(policymod.ask(offline, self.STATE, policymod.Question("budget_tier", "F1", ("S", "M"))).value, "S") + self.assertEqual(policymod.ask(offline, self.STATE, policymod.Question("worth_continuing", "F1", ("continue", "stop"))).value, "continue") + state = json.loads(json.dumps(self.STATE)) + state["envelope"]["calls_left"] = 0 + self.assertEqual(policymod.ask(offline, state, policymod.Question("worth_continuing", "F1", ("continue", "stop"))).value, "stop") + state["features"]["F1"]["attempts"] = 1 + self.assertEqual(policymod.ask(offline, state, policymod.Question("after_failure", "F1", policymod.AFTER_FAILURE)).value, "retry_same") + state["features"]["F1"]["attempts"] = 2 + self.assertEqual(policymod.ask(offline, state, policymod.Question("after_failure", "F1", policymod.AFTER_FAILURE)).value, "retry_escalate_arm") + self.assertEqual(policymod.ask(offline, state, policymod.Question("after_failure", "F1", ("retry_same", "escalate_owner", "park"))).value, + "escalate_owner", "attempts left but no stronger arm: the owner decides") + self.assertEqual(policymod.ask(offline, state, policymod.Question("after_failure", "F1", ("escalate_owner", "park"))).value, "park", + "no retry offered: the cap is spent") + + def test_closed_option_sets_are_enforced(self): + with self.assertRaises(Rejected): + policymod.Question("budget_tier", "F1", ("XL",)) + with self.assertRaises(Rejected): + policymod.Question("replan", "F1", ("a",)) + question = policymod.Question("next_feature", None, ("F1", "F3")) + with self.assertRaises(Rejected) as refused: + policymod.validate(question, "F2", "test") + self.assertEqual(refused.exception.code, "policy_invalid") + with self.assertRaises(Rejected): + policymod.validate(question, {"value": "F1", "probabilities": {"F1": 0.9, "F3": 0.3}}, "test") + good = policymod.validate(question, {"value": "F1", "probabilities": {"F1": 0.7, "F3": 0.3}}, "test") + self.assertEqual(good.probabilities["F3"], 0.3) + + def test_shadow_records_disagreement_and_never_acts(self): + recorded = policymod.recorded_answers({"next_feature": {"value": "F3", "probabilities": {"F1": 0.4, "F3": 0.6}}, + "budget_tier:F1": "M", "after_failure": "F9"}) + shadow = policymod.ShadowPolicy(policymod.OfflinePolicy(), recorded, shadow_name="recorded-jev") + answer = policymod.ask(shadow, self.STATE, policymod.Question("next_feature", None, ("F1", "F3"))) + self.assertEqual(answer.value, "F1", "the acting policy's answer stands") + self.assertEqual(answer.shadow, {"policy": "recorded-jev", "value": "F3", "probabilities": {"F1": 0.4, "F3": 0.6}, + "agrees": False, "reason": "recorded"}) + self.assertEqual(shadow.disagreements, 1) + answer = policymod.ask(shadow, self.STATE, policymod.Question("budget_tier", "F1", ("S", "M"))) + self.assertEqual((answer.value, answer.shadow["value"], answer.shadow["agrees"]), ("S", "M", False)) + answer = policymod.ask(shadow, self.STATE, policymod.Question("proposer_arm", "F1", ("cheap",))) + self.assertEqual(answer.shadow["reason"], "shadow_unanswered") + self.assertIsNone(answer.shadow["agrees"]) + state = json.loads(json.dumps(self.STATE)) + state["features"]["F1"]["attempts"] = 1 + answer = policymod.ask(shadow, state, policymod.Question("after_failure", "F1", ("retry_same", "park"))) + self.assertEqual((answer.value, answer.shadow["reason"]), ("retry_same", "policy_invalid"), "an answer outside the options is recorded, not acted on") + self.assertEqual(shadow.disagreements, 2) + + +class EndToEnd(Scratch): + def test_the_thin_slice_builds_three_features_to_ready_for_owner_merge(self): + project, base = self.project() + document = promoted_spec(project) + mapping = fixture_map(document, base) + featuremap.approve(mapping, OWNER) + recorded = policymod.recorded_answers({"next_feature": "F3", "budget_tier": "S", "proposer_arm": "standin"}) + shadow = policymod.ShadowPolicy(policymod.OfflinePolicy(), recorded, shadow_name="recorded-jev") + run = self.make_loop(project, mapping, document, policy=shadow) + tickets = run.compile() + home = run.ledger + self.assertEqual([t["map_ref"]["feature_id"] for t in tickets], ["F1", "F2", "F3"]) + opened = [e for e in home.events() if e["kind"] == "ticket_opened"] + self.assertEqual([(e["body"]["feature_id"], e["body"]["source"], e["body"]["human_owner"]) for e in opened], + [("F1", "map", "tester"), ("F2", "map", "tester"), ("F3", "map", "tester")]) + frozen = [e for e in home.events() if e["kind"] == "note" and e["body"]["note"] == "map_frozen"] + self.assertEqual(len(frozen), 1) + self.assertEqual(frozen[0]["body"]["approved_by"], OWNER) + self.assertEqual(frozen[0]["body"]["critical_path"], ["F1", "F2"]) + contracts = sorted(p.name for p in (project / ".syberlabs" / "contracts").glob("*.json")) + self.assertEqual(contracts, sorted(f"syberfactory-{t['ticket_id']}.v1.json" for t in tickets)) + contract = json.loads((project / ".syberlabs" / "contracts" / contracts[0]).read_text(encoding="utf-8")) + self.assertEqual(contract["evolution"]["scope"]["paths"], [tickets[[f"syberfactory-{t['ticket_id']}.v1.json" for t in tickets].index(contracts[0])]["footprint"]["files"][0]]) + self.assertEqual(len(contract["evolution"]["evaluation"]["required"]), 2, "the visible check and the hidden check") + + summary = run.run() + self.assertEqual(summary["stopped"], "nothing_eligible") + self.assertEqual(summary["ready_for_owner_merge"], ["F1", "F2", "F3"], summary) + self.assertEqual(summary["envelope"]["calls"], 3) + self.assertEqual(summary["envelope"]["dollars"], 0.0) + self.assertEqual(summary["envelope"]["unsettled"], 0) + events = loop.autonomy_events(home) + kinds = [(e["kind"] if e["kind"] != "note" else e["body"]["note"]) for e in events] + picks = [e["body"]["answer"]["value"] for e in events if e["kind"] == "note" and e["body"]["note"] == "policy_proposal" + and e["body"]["question"] == "next_feature"] + self.assertEqual(picks, ["F1", "F3", "F2"], "critical path first: F1 (bottom level 2, a dependent), then F3 (M), then F2") + shadows = [e["body"]["answer"]["shadow"] for e in events if e["kind"] == "note" and e["body"]["note"] == "policy_proposal" + and e["body"]["question"] == "next_feature"] + self.assertEqual([s["agrees"] for s in shadows], [False, True, None], "the shadow disagreed on the first pick and was out of options on the last") + self.assertEqual(shadows[2]["reason"], "policy_invalid") + steps = [(e["body"]["feature"], e["body"]["step"], e["body"]["outcome"]) for e in events if e["kind"] == "note" and e["body"]["note"] == "thread_step"] + self.assertEqual(steps, [("F1", "check", "acceptable"), ("F1", "accept", "succeeded"), + ("F3", "check", "acceptable"), ("F3", "accept", "succeeded"), + ("F2", "check", "acceptable"), ("F2", "accept", "succeeded")]) + self.assertEqual(kinds[:4], ["map_frozen", "ticket_opened", "ticket_opened", "ticket_opened"]) + self.assertEqual(kinds[-1], "loop_stopped") + self.assertEqual(kinds.count("feature_ready"), 3) + self.assertEqual(kinds.count("feature_failed"), 0) + self.assertTrue(home.verify()) + ready = [e for e in events if e["kind"] == "note" and e["body"]["note"] == "feature_ready"] + for event in ready: + self.assertTrue(event["body"]["refs"]["target_ref"].startswith("refs/heads/syberlabs/")) + self.assertEqual(event["body"]["next"], "owner merges; nothing here merges") + main = subprocess.run(["git", "-C", str(project), "rev-parse", "main"], capture_output=True, text=True, check=True).stdout.strip() + self.assertEqual(main, base, "main never moved") + f2 = summary["features"]["F2"]["commit"] + shown = subprocess.run(["git", "-C", str(project), "show", f"{f2}:fxapp/rules.py"], capture_output=True, text=True, check=True).stdout + self.assertIn("# F1 delivered", shown, "F2 stacked on F1's accepted commit") + walk = loop.why(home, tickets[1]["ticket_id"]) + self.assertEqual((walk["feature"], walk["requirements"], walk["map"]["approved_by"]), ("F2", ["R2"], OWNER)) + self.assertEqual(walk["spec"]["digest"], specmod.spec_digest(document)) + self.assertEqual(walk["ready_for_owner_merge"]["commit"], f2) + self.assertEqual(run.spend.totals()["stopped"], "nothing_eligible") + # The same list, for the report: every autonomy event in order. + print("\nledger events:", " ".join(kinds)) + + def test_same_fixture_gives_the_same_event_digests(self): + digests = [] + for name in ("one", "two"): + project, base = self.project(name) + document = promoted_spec(project) + mapping = fixture_map(document, base) + featuremap.approve(mapping, OWNER) + run = self.make_loop(project, mapping, document, ledger_name=f"ledger-{name}") + run.run() + digests.append(loop.event_digests(run.ledger)) + self.assertEqual(len(digests[0]), len(digests[1])) + self.assertEqual(digests[0], digests[1], "no timestamp, thread id or commit enters an event digest") + self.assertGreater(len(digests[0]), 20) + + def test_a_map_without_owner_approval_is_refused(self): + project, base = self.project() + document = promoted_spec(project) + mapping = fixture_map(document, base) + run = self.make_loop(project, mapping, document) + with self.assertRaises(Rejected) as refused: + run.compile() + self.assertEqual(refused.exception.code, "map_unapproved") + self.assertEqual(run.ledger.events(), [], "nothing was logged") + featuremap.approve(mapping, OWNER) + mapping["features"][0]["depends_on"] = ["F2"] + run = self.make_loop(project, mapping, document, ledger_name="ledger2") + with self.assertRaises(Rejected) as refused: + run.compile() + self.assertEqual(refused.exception.code, "map_unapproved", "an edit after approval leaves the approval stale") + featuremap.approve(mapping, OWNER) + run = self.make_loop(project, mapping, document, ledger_name="ledger3") + with self.assertRaises(Rejected) as refused: + run.compile() + self.assertEqual(refused.exception.code, "map_invalid") + self.assertIn("cycle", refused.exception.detail) + + def test_the_envelope_stops_the_loop(self): + project, base = self.project() + document = promoted_spec(project) + mapping = fixture_map(document, base) + featuremap.approve(mapping, OWNER) + run = self.make_loop(project, mapping, document, calls_total=2) + summary = run.run() + self.assertEqual(summary["stopped"], "envelope_exhausted") + self.assertEqual(summary["ready_for_owner_merge"], ["F1", "F3"]) + self.assertEqual(summary["features"]["F2"]["state"], "open", "F2 was eligible and waits for a new envelope") + self.assertEqual(summary["envelope"]["calls_left"], 0) + self.assertEqual(run.spend.totals()["stopped"], "envelope_exhausted") + lines = run.spend.lines() + self.assertEqual([line["kind"] for line in lines], ["reserve", "settle", "reserve", "settle", "stop"]) + + def test_await_merge_leaves_a_dependent_waiting_for_the_owner(self): + project, base = self.project() + document = promoted_spec(project) + mapping = fixture_map(document, base, integration="await_merge") + featuremap.approve(mapping, OWNER) + summary = self.make_loop(project, mapping, document).run() + self.assertEqual(summary["ready_for_owner_merge"], ["F1", "F3"]) + self.assertEqual(summary["features"]["F2"]["state"], "waiting_owner_merge") + self.assertEqual(summary["stopped"], "nothing_eligible") + + def test_a_failing_candidate_is_refused_by_the_kernel_and_the_feature_is_parked(self): + project, base = self.project() + document = promoted_spec(project) + mapping = fixture_map(document, base) + featuremap.approve(mapping, OWNER) + run = self.make_loop(project, mapping, document, attempts=1, mode="--break") + summary = run.run() + self.assertEqual(summary["ready_for_owner_merge"], []) + self.assertEqual({row["state"] for row in summary["features"].values()} - {"open"}, {"parked"}) + self.assertTrue(summary["features"]["F1"]["last_reason"].startswith("candidate_check_failed:"), summary["features"]["F1"]) + self.assertIn(summary["features"]["F1"]["last_reason"].split(":")[1], ("tests", "hidden.f1.marker"), "both checks fail; one is named") + self.assertEqual(summary["features"]["F2"]["state"], "open", "F2 waits on F1 and never started") + events = loop.autonomy_events(run.ledger) + questions = [(e["body"]["question"], e["body"]["answer"]["value"]) for e in events + if e["kind"] == "note" and e["body"]["note"] == "policy_proposal" and e["body"]["feature"] == "F1"] + self.assertEqual(questions[-2:], [("worth_continuing", "stop"), ("after_failure", "park")]) + self.assertEqual(summary["envelope"]["calls"], 2, "one call per parked feature; the envelope counted both") + + def test_a_candidate_outside_its_scope_never_reaches_accept(self): + project, base = self.project() + document = promoted_spec(project) + mapping = fixture_map(document, base) + featuremap.approve(mapping, OWNER) + run = self.make_loop(project, mapping, document, attempts=2, mode="--outside") + summary = run.run() + self.assertEqual(summary["ready_for_owner_merge"], []) + self.assertEqual(summary["features"]["F1"]["last_reason"], "candidate_out_of_scope") + self.assertEqual(summary["features"]["F1"]["attempts"], 2, "retry_same once, then parked") + self.assertEqual(summary["features"]["F1"]["state"], "parked") + + def test_the_kill_switch_stops_before_the_next_decision(self): + project, base = self.project() + document = promoted_spec(project) + mapping = fixture_map(document, base) + featuremap.approve(mapping, OWNER) + switch = self.scratch / "stop-now" + switch.write_text("") + run = self.make_loop(project, mapping, document, kill_switch=str(switch)) + summary = run.run() + self.assertEqual(summary["stopped"], "kill_switch") + self.assertEqual(summary["ready_for_owner_merge"], []) + self.assertEqual(summary["envelope"]["calls"], 0) + + def test_the_slice_holds_no_merge_and_no_network(self): + for name in ("featuremap", "policy", "loop", "autonomy_cli"): + text = (ROOT / "syberlabs" / "factory" / f"{name}.py").read_text(encoding="utf-8") + for forbidden in ('"merge"', "merge_pull", "git_push", "github_pull_request", "urllib", "http.client", "socket", "requests"): + self.assertNotIn(forbidden, text, f"{name}.py holds {forbidden}") + with self.assertRaises(Rejected): + loop.record(ledger.Ledger(self.scratch / "l"), "merged", "x", {}) + self.assertNotIn("merge", loop.ACTIONS) + self.assertNotIn("publish", " ".join(loop.ACTIONS)) + + +if __name__ == "__main__": + unittest.main() From 20b3338846ddbe84d55342d4725fc248d17878d6 Mon Sep 17 00:00:00 2001 From: sykosyber Date: Mon, 2 Nov 2026 01:35:48 -0800 Subject: [PATCH 5/8] Autonomy thin slice on the goal gate: compile checks the ledger's promotion record through C1's seam (the promote event, the approval it cites, the stored envelope, re-verified under --owner-public), retry_escalate_arm offers only the stronger arms so the recorded decision is the one that runs, one envelope ledger file per envelope digest so two maps or two grants in one home never share spend or a stop, stacking restores the owner's HEAD and refuses a dirty tree, the envelope ledger refuses negative or non-finite amounts, a kindless line, a second reserve and an orphan settle, a Rejected inside run() still writes the stop line and loop_stopped, the kill-switch path leaves the digest, scope paths compare case-folded without ./, risk_plan validates its weights, and the docs list the known limits and the deviations from C4 (#163 verification findings 1-10, 13) Co-Authored-By: Claude Fable 5.1 --- docs/FACTORY_AUTONOMY.md | 86 ++++++- syberlabs/factory/autonomy_cli.py | 8 +- syberlabs/factory/featuremap.py | 23 +- syberlabs/factory/loop.py | 245 +++++++++++++++--- syberlabs/factory/policy.py | 3 +- tests/test_factory_autonomy.py | 404 ++++++++++++++++++++++++------ 6 files changed, 643 insertions(+), 126 deletions(-) diff --git a/docs/FACTORY_AUTONOMY.md b/docs/FACTORY_AUTONOMY.md index a2ee44e..f2aeabb 100644 --- a/docs/FACTORY_AUTONOMY.md +++ b/docs/FACTORY_AUTONOMY.md @@ -6,9 +6,11 @@ realises the first slice of the autonomous typed mode (`2026-10-28-syberfactory- three modules under `syberlabs/factory/` and one CLI group, at $0, offline, with a stand-in command where a model would be. -Claim ceiling for this page: **implemented** and **tested** (`tests/test_factory_autonomy.py`, 17 tests, run on +Claim ceiling for this page: **implemented** and **tested** (`tests/test_factory_autonomy.py`, 25 tests, run on Windows with Python 3.12 and in CI). Nothing here is measured on a real spec, deployed, or validated by anyone -outside the repository. +outside the repository. This slice sits on the goal-gate packet (C1, `syberlabs/factory-goal-gate`): the spec it +builds under is one the owner promoted through `factory approve` and `factory spec promote`, and the loop checks +that on the ledger, not in the spec file. ## What it does @@ -23,8 +25,8 @@ spec (promoted) ─► FeatureMap (typed DAG) ─► mapcheck ─► owner | --- | --- | | `featuremap.py` | `feature-map.v1`: features with id, objective, `req_ids` (the spec requirements they trace to), scope paths, shown criteria, hidden-check names (names only), `depends_on`, act class, size, risk inputs. `spec_from_markdown` turns a sectioned Markdown spec (`## R1: text`, `- given, when, then` bullets) into #154's spec object (owner decision 11, D2). `mapcheck` is the deterministic floor: schema, spec digest, coverage, acyclic DAG, scope conflicts (an intersection must be declared with an order that agrees with the DAG), act class, size ceilings, hidden-check names, approval digest. `taskgraph`: critical path, total work, work/critical ratio, Dilworth width with a maximum antichain, conflict graph. `risk_plan`: seven risk inputs computed by code, `r_i` as a weighted sum, standardized `z_i`, `v_i = V * softmax(z_i / tau)` as integer units above a floor that is listed beside every allocation and never moves. `compile_ticket`: one feature to one ticket in `ticket_from_spec`'s shape (D5). `degenerate_map`: the map `ticket_from_spec` implies, one feature per requirement. | | `policy.py` | `Question` (closed options built by code; the state a policy reads is ids and numbers only), `Answer`, `validate` (an answer outside the options is `policy_invalid`), `OfflinePolicy` (critical path first, cheapest arm and tier, retry then stronger arm then owner, park when the cap is spent, stop on the envelope), `ShadowPolicy` (acts on one policy, records what an injected second one would have answered and whether it agrees; an invalid or failing shadow is recorded and changes nothing), `recorded_answers` (a shadow over a fixture). | -| `loop.py` | `Loop.compile`: refuses a map without a current owner approval (`map_unapproved`), a spec that is not promoted, or a map with findings; writes one contract per feature; logs `map_frozen` and `ticket_opened{source: map}`. `Loop.run`: kill switch, eligibility, three policy questions recorded as proposals, envelope reservation, one unattended Build Thread, one proposer call through `CommandProvider`, then `syberlabs run`'s `Runner` drives the thread (D17), the envelope settles from the journal, the outcome is recorded. `EnvelopeLedger`: the eval spend ledger's shape generalized to attempts (D13). `why`: ticket -> feature -> map (approval) -> spec, from the ledger. `event_digests`: one digest per autonomy event without its volatile `refs`. | -| `autonomy_cli.py` | `syberlabs factory autonomy check | approve | envelope | run | why`, registered from one hook line at the end of `factory/cli.py`. | +| `loop.py` | `Loop.compile`: refuses a map without a current owner approval (`map_unapproved`), a spec the ledger did not promote (`spec_unpromoted`, see `promotion_record`), or a map with findings; writes one contract per feature; logs `map_frozen` (with `promoted_by`) and `ticket_opened{source: map}`. `Loop.run`: kill switch, eligibility, three policy questions recorded as proposals, envelope reservation, one unattended Build Thread, one proposer call through `CommandProvider`, then `syberlabs run`'s `Runner` drives the thread (D17), the envelope settles from the journal, the outcome is recorded; a `Rejected` while running still writes the envelope's `stop` and the ledger's `loop_stopped{reason: }` before it propagates. `promotion_record`: the goal gate's record on the ledger for exactly this spec (the `spec_changed` promote whose `spec_digest` is the file's, the `approval_recorded` it cites, the envelope under `approvals/`), re-verified under the owner's public key when one is given. `EnvelopeLedger`: the eval spend ledger's shape generalized to attempts (D13), one file per envelope digest under `envelopes/`, strict on every line. `why`: ticket -> feature -> map (approval) -> spec (promotion), from the ledger. `event_digests`: one digest per autonomy event without its volatile `refs`. | +| `autonomy_cli.py` | `syberlabs factory autonomy check | approve | envelope | run | why`, registered from one hook line at the end of `factory/cli.py`. `run --owner-public KEY` re-verifies the promotion's approval under the owner's key. | ### A run on the fixture @@ -47,25 +49,39 @@ loop_stopped(nothing_eligible) F1 goes first (bottom level 2: a dependent waits on it), then F3 (size M, bottom level 2), then F2. Each feature ends as an accepted candidate on `syberlabs/`, with the thread id, commit and target ref in the -`feature_ready` event's `refs`. `main` never moves. Under `integration: stack` F2's thread starts from F1's accepted +`feature_ready` event's `refs`. `main` never moves, and the owner's checkout is as it was: HEAD on the same branch +at the same commit, no scratch branch left. Under `integration: stack` F2's thread starts from F1's accepted commit; under `await_merge` F2 is recorded `feature_waiting` and the loop stops with F1 and F3 ready, because only the owner's merge can release it. The same fixture run twice gives the same `event_digests` list: no timestamp, -thread id, commit or elapsed time enters a digest. +thread id, commit, elapsed time, approval digest or kill-switch path enters a digest. + +After a failure, `retry_same` offers the next attempt every arm again; `retry_escalate_arm` (offered only when the +envelope holds an arm ranked above the one that failed) offers only the stronger arms, so the arm on +`attempt_started` is the arm the recorded decision named. The test runs `cheap, cheap, strong` then parks. ### From a terminal ```sh python -m syberlabs.factory --home .syberlabs/factory spec validate spec.json # the spec, as in FACTORY.md -python -m syberlabs.factory --home .syberlabs/factory spec promote spec.json --verdict review-1 --actor human:mateo +python -m syberlabs.factory --home .syberlabs/factory approve spec.json --verdict VERDICT --actor human:mateo \ + --seed-env SYBERLABS_FACTORY_OWNER_SEED --out approval.json # the goal gate (C1): the owner signs +python -m syberlabs.factory --home .syberlabs/factory spec promote spec.json --verdict VERDICT --actor human:mateo \ + --approval approval.json --owner-public owner.pub # verified, recorded, cited on the ledger python -m syberlabs.factory autonomy check --map map.json --spec spec.json # findings, graph, risk plan; exit 1 on findings python -m syberlabs.factory autonomy approve --map map.json --by mateo # the owner's act; any edit leaves it stale python -m syberlabs.factory autonomy envelope --map map.json --calls 6 --attempts 2 --out envelope.json python -m syberlabs.factory --home .syberlabs/factory autonomy run --map map.json --spec spec.json --envelope envelope.json \ - --owner mateo --proposer "/abs/python standin.py ." --check "tests=/abs/python -m unittest -q" \ + --owner mateo --owner-public owner.pub --proposer "/abs/python standin.py ." --check "tests=/abs/python -m unittest -q" \ --hidden "hidden.f1.marker=/abs/python -c ..." # exit 0 when a feature is ready python -m syberlabs.factory --home .syberlabs/factory autonomy why TICKET ``` +`run` reads the spec's promotion from the same `--home` the promote wrote to. An envelope is one grant: its +ledger lives at `envelopes/.jsonl`, a second map or a new envelope in the same home starts +clean, and a run over an envelope whose ledger already carries a `stop` is refused (`envelope_stopped`). On +Windows, `--check` and `--hidden` commands with nested quotes need a script file (`split_command` is non-POSIX +there; pre-existing in #154). + ## What it does not do - **Publish or merge.** No action in the loop pushes, opens a pull request or merges; `loop.ACTIONS` is the closed @@ -121,12 +137,56 @@ python -m syberlabs.factory --home .syberlabs/factory autonomy why TICKET ## Limits of this slice -- Stacking (`integration: stack`) starts a dependent from its last dependency's accepted commit by checking out a - branch `syberfactory//` in the working repository. A feature with two dependencies on separate - branches is not integrated here; the owner's merge order is. +- Stacking (`integration: stack`) starts a dependent from its last dependency's accepted commit. `Kit.start` starts + from HEAD, so the loop moves HEAD to that commit on a scratch branch `syberfactory//` for the start + only, then puts the owner's branch (or detached commit) back and deletes the scratch branch, whether or not the + start succeeded. A working tree with uncommitted tracked changes is refused first (`repository_dirty`), so nothing + is carried into a thread base or lost. A feature with two dependencies on separate branches is not integrated + here; the owner's merge order is. - A hidden check runs as a contract check in the candidate's worktree, so it is as exposed to candidate code as any check (register N4). The fixture's stand-in writes no code that runs; a model's would, and then the host decision (C7) applies. -- The envelope ledger has no cross-process lock, as the factory ledger has none (D1 puts both on the journal's lock - in C1). +- The envelope ledger has no cross-process lock. C1 put the factory ledger on the journal's lock; the envelope file + is still appended without one (two loops on one envelope in one home is not a supported run). - The risk weights and tau are priors. Nothing has calibrated them; `risk_plan` logs what calibration would need. + `risk_plan(weights=)` is validated (the known inputs, each in [0, 1], summing to 1) but not reachable from the CLI. +- **The map approval is a record, not a credential.** `featuremap.approve` writes `{digest, actor}` and + `approved()` checks the digest against the map, not the actor against a signature: swapping `approval.actor.id` + leaves the map approved. The spec's promotion is now bound to the owner's signed approval through C1's seam + (`promotion_record`, re-verified with `--owner-public`); the map's approval has no such seam yet. Binding it is a + signed `approval_payload` over the map digest, which is C1's shape applied to a second artifact; proposed for the + packet that gives the factory a kernel case to hang approvals on. +- **The floor is listed, not enforced, by this slice.** `FLOOR` names host checks, hidden checks, critic and safety + gate, and every `buys` list carries all four. Only the first two are contract-required here (`required` in the + compiled contract is the visible checks plus the hidden checks). No critic runs and no safety gate is computed + until C6 (`independent-review`) and C9 bring them; "every feature, never loosened" is true of the two that exist. + +## Deviations from C4 as written + +The consolidation report's C4 row (section 5) asked for more than this slice ships. Each deviation is deliberate, +and none of them is hidden in "Deliberately not in this slice" above: + +- **The envelope ledger is re-implemented, not imported from #150's spend ledger (D13 "build it once").** The eval + spend ledger lives in `syberlabs/eval/`; `docs/architecture.declared.json` declares no `factory -> eval` edge, and + the layering test (`test_repository_layering_has_no_drift`) refuses an undeclared import. `EnvelopeLedger` copies + the shape (one JSON object per line, reserve before, settle after, strict read, non-finite refused) rather than the + code. Proposed for C11: declare `syberlabs-factory -> syberlabs-eval` (or lift the spend ledger into a module both + can import) and delete this copy. +- **`RecordedJevPolicy` does not reuse `jev_api`'s validator (D11).** Same layering: `jev_api` is outside the + factory's declared edges. `policy.validate` is the closed-option check; `recorded_answers` is the fixture-side + shadow. The adapter that reuses `jev_api`'s request and validation code is the packet that declares that edge. +- **Decisions are factory-ledger `note` events, not kernel-journal `observed{policy_decision}`, and `propose` is + untagged.** The kernel's `Thread.propose` takes no origin field today (an `origin` is recorded only for migrated + candidates, through `migrate`), and the kernel's event vocabulary is not this packet's to extend. Every policy + answer is a `policy_proposal` note on the factory ledger before it is acted on. Proposed for C6: an + `observed{policy_decision}` on the case and `propose(origin="model")` once the kernel accepts an origin on a + proposal. +- **`factory autonomy why` takes a ticket id only**, not a PR or thread id: there is no PR until C9, and the thread + id is in the `feature_ready` event the ticket walk already returns. +- **The fixture is `tests/fixtures/autonomy/`, not `factory/fixtures/spec-slugify-pricing/`.** It reuses the + factory's own `factory_app`, so the Space graph, the ledger and the hidden checks are the ones the rest of the + factory tests already exercise. A separate product fixture adds a second app to maintain for no extra coverage in + this slice. +- **`OfflinePolicy` is critical-path-first, not risk-per-unit-of-work-first.** `next_feature` orders by bottom + level, then risk, then map order. Risk per unit of work needs a cost model per feature that `risk_plan` does not + yet have (its units are verification units, not build cost); deferred until C10's E8 gives risk a measured scale. diff --git a/syberlabs/factory/autonomy_cli.py b/syberlabs/factory/autonomy_cli.py index 19b6701..afcc018 100644 --- a/syberlabs/factory/autonomy_cli.py +++ b/syberlabs/factory/autonomy_cli.py @@ -18,6 +18,7 @@ import sys from pathlib import Path +from syberlabs import certificate from syberlabs.errors import Rejected from syberlabs.factory import featuremap, loop from syberlabs.factory import policy as policymod @@ -79,7 +80,9 @@ def add_commands(steps) -> None: runp.add_argument("--baseline", help="the golden run id to name on tickets") runp.add_argument("--max-steps", type=int, default=50) runp.add_argument("--shadow", help="recorded answers JSON for a shadow policy; recorded beside each decision, never acted on") - why = sub.add_parser("why", help="walk a ticket back to its feature, map, approval and spec") + runp.add_argument("--owner-public", metavar="KEY", help="the owner's .pub file: re-verify the spec's promotion approval under it " + "(without it the ledger's hash-chained record and stored envelope are checked)") + why = sub.add_parser("why", help="walk a ticket back to its feature, map, approval, spec and its promotion") why.add_argument("ticket") @@ -146,10 +149,11 @@ def _run(args) -> int: raise Rejected("check_argument", "name at least one visible check with --check NAME=COMMAND") root = Path(args.root).resolve() kit_home = Path(args.kit_home) + owner_public = certificate.read_public(args.owner_public) if args.owner_public else None driver = loop.Loop(repo_root=root, kit_home=kit_home if kit_home.is_absolute() else root / kit_home, ledger=ledgermod.Ledger(args.home), map=document, spec=spec, envelope=envelope, policy=policy, proposer_argv=split_command(args.proposer), checks=checks, hidden_catalogue=_parse_checks(args.hidden, "--hidden"), - human_owner=args.owner, baseline_run=args.baseline, log=print) + human_owner=args.owner, baseline_run=args.baseline, log=print, owner_public=owner_public) tickets = driver.compile() for ticket in tickets: print(f"ticket {ticket['ticket_id']} {ticket['map_ref']['feature_id']} {ticket['title']}") diff --git a/syberlabs/factory/featuremap.py b/syberlabs/factory/featuremap.py index 3fab85e..7b0f358 100644 --- a/syberlabs/factory/featuremap.py +++ b/syberlabs/factory/featuremap.py @@ -165,12 +165,21 @@ def approved(document: dict) -> bool: # -- mapcheck ------------------------------------------------------------------------------------------------------ +def normalize_path(path: str) -> str: + """A scope entry as compared: backslashes as slashes, leading ``./`` segments and the trailing slash + removed, case folded (the kernel's scope check runs on case-insensitive filesystems too).""" + text = path.strip().replace("\\", "/") + while text.startswith("./"): + text = text[2:] + return text.rstrip("/").casefold() + + def path_intersects(a: str, b: str) -> bool: - """Prefix intersection of two scope entries at directory boundaries. ``"."`` or empty is the whole tree.""" - a, b = a.strip().lstrip("./"), b.strip().lstrip("./") - if a in ("", ".") or b in ("", "."): + """Prefix intersection of two scope entries at directory boundaries, after :func:`normalize_path`. + ``"."`` or empty is the whole tree.""" + ad, bd = normalize_path(a), normalize_path(b) + if ad in ("", ".") or bd in ("", "."): return True - ad, bd = a.rstrip("/"), b.rstrip("/") return ad == bd or bd.startswith(ad + "/") or ad.startswith(bd + "/") @@ -571,6 +580,12 @@ def risk_plan(document: dict, graph: dict | None = None, *, budget: int | None = graph = graph or taskgraph(document) if tau < TAU_MIN: raise Rejected("risk_tau", f"tau must be at least {TAU_MIN} so every feature keeps a positive propensity") + if not isinstance(weights, dict) or set(weights) != set(WEIGHTS): + raise Rejected("risk_weights", f"weights must name exactly the inputs {sorted(WEIGHTS)}") + if any(isinstance(w, bool) or not isinstance(w, (int, float)) or not math.isfinite(w) or not 0 <= w <= 1 for w in weights.values()): + raise Rejected("risk_weights", "each weight is a finite number in [0, 1]") + if abs(sum(weights.values()) - 1.0) > 1e-6: + raise Rejected("risk_weights", f"weights sum to {sum(weights.values()):.4f}, not 1, so r would leave [0, 1]") features = document["features"] ids = [f["id"] for f in features] budget = len(ids) if budget is None else budget diff --git a/syberlabs/factory/loop.py b/syberlabs/factory/loop.py index 288f4fb..8942392 100644 --- a/syberlabs/factory/loop.py +++ b/syberlabs/factory/loop.py @@ -32,6 +32,13 @@ work and settled after it, read strictly) generalized to attempts: ``reserve`` before an attempt holds the tier's dollars and one call, ``settle`` replaces the hold with what the journal recorded, ``stop`` closes the run with a reason. Totals are the settled values plus unsettled holds, so a killed attempt stays counted. +One file per envelope (``envelopes/.jsonl`` under the factory home), and every line names +the envelope it belongs to, so two maps or two grants in one home never read each other's spend or stop. + +The spec is promoted when the ledger says so, not when the file says so: ``promotion_record`` finds the +``spec_changed`` that promoted exactly this spec (its digest), the ``approval_recorded`` it cites and the +owner's envelope under ``approvals/``, and with the owner's public key re-verifies the signature (the goal +gate's ``verify_approval``). ``compile`` refuses a spec the ledger did not promote (``spec_unpromoted``). """ from __future__ import annotations @@ -45,11 +52,13 @@ from syberlabs.canonical import canonical, digest from syberlabs.errors import Rejected from syberlabs.factory import PROTOCOL, featuremap, policy as policymod +from syberlabs.factory import spec as specmod from syberlabs.providers import CommandProvider ENVELOPE_SCHEMA = "syberfactory/envelope.v1" ENVELOPE_LINE_SCHEMA = "syberlabs.factory/envelope-ledger.v1" -ENVELOPE_FILE = "envelope.jsonl" +ENVELOPE_DIR = "envelopes" +ENVELOPE_LINE_KINDS = ("reserve", "settle", "stop") ACTIONS = ("start_thread", "propose", "check", "accept_to_thread_branch") # closed; no merge, push or publish EVENTS = ("map_frozen", "policy_proposal", "envelope_reserved", "envelope_settled", "attempt_started", "thread_step", "feature_ready", "feature_failed", "feature_parked", "feature_escalated", "feature_waiting", "loop_stopped") @@ -85,7 +94,22 @@ def new_envelope(map_digest: str, *, dollars_total: float, calls_total: int, sec def envelope_digest(envelope: dict) -> str: - return digest(envelope) + """The grant's digest. The kill switch is a path on this host, not a term of the grant, so it stays out: + two runs of one fixture with and without a switch give one ``map_frozen`` digest.""" + return digest({k: v for k, v in envelope.items() if k != "kill_switch"}) + + +def envelope_path(home: str | Path, envelope: dict) -> Path: + return Path(home) / ENVELOPE_DIR / f"{envelope_digest(envelope)}.jsonl" + + +def _amount(value, name: str, where: str, *, integer: bool = False) -> float: + """A finite, non-negative number (an int when ``integer``); anything else is refused, never summed.""" + if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or value < 0: + raise Rejected("envelope_unpriced", f"{where}: {name} must be a finite number of at least 0, not {value!r}") + if integer and type(value) is not int: + raise Rejected("envelope_unpriced", f"{where}: {name} must be an integer, not {value!r}") + return value def _strict_loads(text: str): @@ -104,12 +128,34 @@ def no_constant(name): class EnvelopeLedger: - """Append-only lines under the factory home. Reserve, settle, stop; totals from the lines.""" + """Append-only lines for one envelope under the factory home. Reserve, settle, stop; totals from the lines. + + Read strictly, as the eval spend ledger is: a torn line, a repeated key, a non-finite number, a line of + another schema or another envelope, a line without a kind, a negative or non-finite amount, a second + ``reserve`` for one attempt or a ``settle`` without its ``reserve`` each refuse the whole file rather than + change a total. The loop writes none of these; a hand-edited or corrupted file does.""" def __init__(self, path: str | Path, envelope: dict): self.path, self.envelope = Path(path), envelope + self.digest = envelope_digest(envelope) self.path.parent.mkdir(parents=True, exist_ok=True) + def _check(self, line: dict, where: str) -> None: + if line.get("envelope_digest") != self.digest: + raise Rejected("envelope_unreadable", f"{where} belongs to envelope {str(line.get('envelope_digest'))[:12]}, not {self.digest[:12]}") + kind = line.get("kind") + if kind not in ENVELOPE_LINE_KINDS: + raise Rejected("envelope_unreadable", f"{where}: kind must be one of {ENVELOPE_LINE_KINDS}, not {kind!r}") + if kind == "stop": + if not isinstance(line.get("reason"), str) or not line["reason"]: + raise Rejected("envelope_unreadable", f"{where}: a stop names its reason") + return + if not isinstance(line.get("feature"), str) or not line["feature"] or type(line.get("attempt")) is not int or line["attempt"] < 1: + raise Rejected("envelope_unreadable", f"{where}: a {kind} names a feature and an attempt number of at least 1") + _amount(line.get("dollars"), "dollars", where) + _amount(line.get("calls"), "calls", where, integer=True) + _amount(line.get("seconds"), "seconds", where) + def lines(self) -> list[dict]: if not self.path.is_file(): return [] @@ -117,34 +163,47 @@ def lines(self) -> list[dict]: for number, raw in enumerate(self.path.read_text(encoding="utf-8").splitlines(), 1): if not raw.strip(): continue + where = f"{self.path}: line {number}" try: value = _strict_loads(raw) except ValueError as exc: - raise Rejected("envelope_unreadable", f"{self.path}: line {number}: {exc}") from None + raise Rejected("envelope_unreadable", f"{where}: {exc}") from None if not isinstance(value, dict) or value.get("schema") != ENVELOPE_LINE_SCHEMA: - raise Rejected("envelope_unreadable", f"{self.path}: line {number} is not an envelope ledger line") + raise Rejected("envelope_unreadable", f"{where} is not an envelope ledger line") + self._check(value, where) out.append(value) return out def _append(self, line: dict) -> dict: - line = {"schema": ENVELOPE_LINE_SCHEMA, "envelope_digest": envelope_digest(self.envelope), **line} + line = {"schema": ENVELOPE_LINE_SCHEMA, "envelope_digest": self.digest, **line} + self._check(line, f"{self.path}: new {line.get('kind')} line") with self.path.open("a", encoding="utf-8", newline="\n") as handle: handle.write(canonical(line) + "\n") handle.flush() return line - def totals(self) -> dict: + def _fold(self) -> tuple[dict, dict, str | None]: reserved: dict[tuple, dict] = {} settled: dict[tuple, dict] = {} stopped = None - for line in self.lines(): + for number, line in enumerate(self.lines(), 1): key = (line.get("feature"), line.get("attempt")) if line["kind"] == "reserve": + if key in reserved: + raise Rejected("envelope_conflict", f"{self.path}: line {number} reserves {key[0]} attempt {key[1]} a second time") reserved[key] = line elif line["kind"] == "settle": + if key not in reserved: + raise Rejected("envelope_conflict", f"{self.path}: line {number} settles {key[0]} attempt {key[1]}, which was never reserved") + if key in settled: + raise Rejected("envelope_conflict", f"{self.path}: line {number} settles {key[0]} attempt {key[1]} a second time") settled[key] = line - elif line["kind"] == "stop": + else: stopped = line["reason"] + return reserved, settled, stopped + + def totals(self) -> dict: + reserved, settled, stopped = self._fold() dollars = calls = seconds = 0.0 for key, hold in reserved.items(): actual = settled.get(key, hold) @@ -163,15 +222,25 @@ def room(self, tier: str, calls: int = 1) -> bool: and totals["calls_left"] >= calls and totals["seconds_left"] > 0) def reserve(self, feature: str, attempt: int, tier: str, arm: str) -> dict: + reserved, _, _ = self._fold() + if (feature, attempt) in reserved: + raise Rejected("envelope_conflict", f"{feature} attempt {attempt} is already reserved") if not self.room(tier): raise Rejected("envelope_exhausted", f"no room for tier {tier} on {feature}: {self.totals()}") return self._append({"kind": "reserve", "feature": feature, "attempt": attempt, "tier": tier, "arm": arm, "dollars": self.envelope["dollars"]["tiers"][tier], "calls": 1, "seconds": 0.0}) def settle(self, feature: str, attempt: int, *, dollars: float, calls: int, seconds: float, unknown_models: list) -> dict: - if not isinstance(dollars, (int, float)) or not math.isfinite(dollars) or dollars < 0: - raise Rejected("envelope_unpriced", f"{feature} attempt {attempt}: dollars are not a finite number of at least 0") - return self._append({"kind": "settle", "feature": feature, "attempt": attempt, "dollars": float(dollars), "calls": int(calls), + where = f"{feature} attempt {attempt}" + _amount(dollars, "dollars", where) + _amount(calls, "calls", where, integer=True) + _amount(seconds, "seconds", where) + reserved, settled, _ = self._fold() + if (feature, attempt) not in reserved: + raise Rejected("envelope_conflict", f"{where} was never reserved; nothing to settle") + if (feature, attempt) in settled: + raise Rejected("envelope_conflict", f"{where} is already settled") + return self._append({"kind": "settle", "feature": feature, "attempt": attempt, "dollars": float(dollars), "calls": calls, "seconds": round(float(seconds), 3), "unknown_models": list(unknown_models)}) def stop(self, reason: str) -> dict: @@ -203,8 +272,58 @@ def event_digests(ledger, map_digest: str | None = None) -> list[str]: for e in autonomy_events(ledger, map_digest)] +def promotion_record(ledger, spec: dict, owner_public: bytes | None = None) -> dict: + """The ledger's record that the owner promoted exactly this spec, through the goal gate's own shape. + + The spec on disk must be the spec the ledger wrote after a ``promote`` (or a later ``canonize``): the + ``spec_changed`` whose ``spec_digest`` is this file's digest, with ``to`` promoted or canonical. The + promotion's ``approval`` must cite an ``approval_recorded`` event (by hash) for this spec and version by a + human approver, whose envelope is under ``approvals/`` at the recorded digest. With ``owner_public`` the + envelope is re-verified (``spec.verify_approval`` over the digest the owner signed), so the record becomes + a credential; without it the hash-chained ledger and the stored envelope are what is checked. The file's + ``state`` string decides nothing here.""" + events = ledger.events() + changes = [e for e in events if e["kind"] == "spec_changed" and e["body"].get("spec_id") == spec.get("spec_id")] + current = specmod.spec_digest(spec) + written = next((e for e in reversed(changes) if e["body"].get("spec_digest") == current), None) + if written is None or written["body"].get("to") not in ("promoted", "canonical"): + raise Rejected("spec_unpromoted", f"the ledger holds no promotion of spec {spec.get('spec_id')!r} at digest {current[:12]}; " + "the file was edited after promotion, or was never promoted through `factory spec promote`") + version = written["body"].get("version") + promotion = next((e for e in reversed(changes[: changes.index(written) + 1]) if e["body"].get("operation") == "promote" + and e["body"].get("to") == "promoted" and e["body"].get("version") == version), None) + if promotion is None: + raise Rejected("spec_unpromoted", f"spec {spec['spec_id']} v{version} has no promote event before its current record") + cited = promotion["body"].get("approval") + actor = promotion["body"].get("actor") + if not isinstance(actor, dict) or actor.get("kind") != "human" or not isinstance(cited, dict) or not cited.get("event_hash"): + raise Rejected("spec_unpromoted", f"the promotion of {spec['spec_id']} at seq {promotion['seq']} names no human actor or no approval event") + recorded = next((e for e in events if e["kind"] == "approval_recorded" and e["hash"] == cited["event_hash"]), None) + if recorded is None: + raise Rejected("spec_unpromoted", f"the promotion cites approval event {str(cited['event_hash'])[:12]}, which is not on the ledger") + body = recorded["body"] + approver = body.get("approver") or {} + if (body.get("operation") != "promote" or body.get("spec_id") != spec["spec_id"] or body.get("version") != version + or approver.get("kind") != "human" or not approver.get("id") or body.get("approval_digest") != cited.get("approval_digest") + or approver != actor): + raise Rejected("spec_unpromoted", f"approval event {recorded['seq']} does not cover the promotion of {spec['spec_id']} v{version} by {actor.get('id')!r}") + path = Path(ledger.home) / "approvals" / f"{body['approval_digest']}.json" + try: + envelope = _strict_loads(path.read_text(encoding="utf-8")) + except (OSError, ValueError) as exc: + raise Rejected("spec_unpromoted", f"the approval envelope {body['approval_digest'][:12]} is missing or unreadable: {type(exc).__name__}") from None + if digest(envelope) != body["approval_digest"]: + raise Rejected("spec_unpromoted", f"approvals/{body['approval_digest'][:12]} does not match its recorded digest") + if owner_public is not None: + specmod.verify_approval(envelope, owner_public, spec, "promote", verdict_ids=list(body.get("verdict_ids") or []), + spec_digest_value=body.get("spec_digest")) + return {"seq": promotion["seq"], "approval_seq": recorded["seq"], "approver": dict(approver), "keyid": body.get("keyid"), + "verdict_ids": list(body.get("verdict_ids") or []), "approval_digest": body["approval_digest"], + "signed_digest": body.get("spec_digest"), "verified": owner_public is not None} + + def why(ledger, ticket_id: str) -> dict: - """The §1.3 walk as far as the ledger goes: ticket -> feature -> map (its approval) -> spec reference.""" + """The §1.3 walk as far as the ledger goes: ticket -> feature -> map (its approval) -> spec (its promotion).""" opened = next((e for e in ledger.events() if e["kind"] == "ticket_opened" and e["body"].get("ticket_id") == ticket_id), None) if opened is None: raise Rejected("ticket_unknown", f"no ticket_opened event for {ticket_id}") @@ -213,10 +332,12 @@ def why(ledger, ticket_id: str) -> dict: and e["body"].get("map_digest") == body.get("map_digest")), None) ready = next((e for e in ledger.events() if e["kind"] == "note" and e["body"].get("note") == "feature_ready" and e["body"].get("ticket_id") == ticket_id), None) + frozen_body = (frozen or {}).get("body", {}) return {"ticket": ticket_id, "feature": body.get("feature_id"), "requirements": body.get("req_ids"), "map": {"digest": body.get("map_digest"), "frozen_seq": frozen["seq"] if frozen else None, - "approved_by": (frozen or {}).get("body", {}).get("approved_by")}, - "spec": {"spec_id": body.get("spec_id"), "version": body.get("version"), "digest": (frozen or {}).get("body", {}).get("spec_digest")}, + "approved_by": frozen_body.get("approved_by")}, + "spec": {"spec_id": body.get("spec_id"), "version": body.get("version"), "digest": frozen_body.get("spec_digest"), + "promoted_by": frozen_body.get("promoted_by"), "promotion": frozen_body.get("refs", {}).get("promotion")}, "ready_for_owner_merge": {"seq": ready["seq"], **ready["body"]["refs"]} if ready else None} @@ -253,22 +374,26 @@ def feature_contract(ticket: dict, *, checks: dict, hidden_catalogue: dict, max_ class Loop: def __init__(self, *, repo_root: str | Path, kit_home: str | Path, ledger, map: dict, spec: dict, envelope: dict, policy, proposer_argv: list[str], checks: dict, hidden_catalogue: dict | None = None, human_owner: str, - baseline_run: str | None = None, actor: str = "factory@syberlabs.host", log=None, max_passes: int = MAX_PASSES): + baseline_run: str | None = None, actor: str = "factory@syberlabs.host", log=None, max_passes: int = MAX_PASSES, + owner_public: bytes | None = None): self.repo_root, self.kit_home, self.ledger = Path(repo_root), Path(kit_home), ledger self.map, self.spec, self.envelope, self.policy = map, spec, envelope, policy self.proposer_argv, self.checks, self.hidden = list(proposer_argv), dict(checks), dict(hidden_catalogue or {}) self.human_owner, self.baseline_run, self.actor = human_owner, baseline_run, actor + self.owner_public = owner_public self.log = log or (lambda line: None) self.max_passes = max_passes self.map_digest = featuremap.map_digest(map) if envelope.get("map_digest") != self.map_digest: raise Rejected("envelope_map", "the envelope names a different map digest") - self.spend = EnvelopeLedger(self.ledger.home / ENVELOPE_FILE, envelope) + self.spend = EnvelopeLedger(envelope_path(self.ledger.home, envelope), envelope) self.graph = None self.plan = None + self.promotion = None self.tickets: dict[str, dict] = {} self.features = {f["id"]: f for f in map["features"]} - self.state = {fid: {"state": "open", "attempts": 0, "dollars": 0.0, "thread": None, "commit": None, "last_reason": None} + self.state = {fid: {"state": "open", "attempts": 0, "dollars": 0.0, "thread": None, "commit": None, "last_reason": None, + "last_arm": None, "arm_floor": 0} for fid in self.features} self.kit = None self.order: list[str] = [] @@ -276,12 +401,14 @@ def __init__(self, *, repo_root: str | Path, kit_home: str | Path, ledger, map: # -- compile ----------------------------------------------------------------------------------------------------------- def compile(self) -> list[dict]: - """Refuse a map without a current owner approval or with findings; write one contract per feature; log - ``map_frozen`` and one ``ticket_opened`` per feature. Idempotent for one map digest.""" + """Refuse a map without a current owner approval, a spec the ledger did not promote, or a map with + findings; write one contract per feature; log ``map_frozen`` and one ``ticket_opened`` per feature. + Idempotent for one map digest.""" if not featuremap.approved(self.map): raise Rejected("map_unapproved", "the loop runs only an owner-approved map whose approval covers its current digest") if self.spec.get("state") not in ("promoted", "canonical"): raise Rejected("spec_state", f"work opens under a promoted spec, not one in state {self.spec.get('state')!r}") + self.promotion = promotion_record(self.ledger, self.spec, self.owner_public) findings = featuremap.mapcheck(self.map, self.spec) if findings: raise Rejected("map_invalid", "; ".join(findings)) @@ -304,10 +431,12 @@ def compile(self) -> list[dict]: record(self.ledger, "map_frozen", self.map_digest, { "map_id": self.map["id"], "spec_id": self.spec["spec_id"], "spec_version": self.spec["version"], "spec_digest": self.map["spec_ref"]["spec_digest"], "approved_by": self.map["approval"]["actor"], + "promoted_by": self.promotion["approver"], "promotion_verified": self.promotion["verified"], "envelope_digest": envelope_digest(self.envelope), "features": [f["id"] for f in self.map["features"]], "critical_path": self.graph["critical_path"], "critical_path_length": self.graph["critical_path_length"], "width": self.graph["width"], "work_critical_ratio": self.graph["work_critical_ratio"], - "risk": self.plan["r"], "verification_units": self.plan["units"], "tau": self.plan["tau"], "floor": self.plan["floor"]}) + "risk": self.plan["r"], "verification_units": self.plan["units"], "tau": self.plan["tau"], "floor": self.plan["floor"]}, + refs={"promotion": {k: self.promotion[k] for k in ("seq", "approval_seq", "approval_digest", "keyid", "verdict_ids")}}) for ticket in tickets: self.ledger.append("ticket_opened", { "ticket_id": ticket["ticket_id"], "spec_id": self.spec["spec_id"], "version": self.spec["version"], @@ -375,13 +504,21 @@ def ask(self, key: str, feature: str | None, options: list[str], numbers: dict | # -- run ---------------------------------------------------------------------------------------------------------------- def run(self, max_steps: int = 50) -> dict: + """Steps until nothing is eligible, the envelope is spent, the kill switch is set or ``max_steps`` pass. + An envelope whose ledger already carries a ``stop`` is refused before anything starts: a grant is spent + once. A ``Rejected`` raised while running (an invalid policy answer, a refused reservation, a thread or + checkout the kernel refused) still ends the record: the envelope gets its ``stop`` line and the ledger + its ``loop_stopped`` with the refusal's code as the reason, and then the refusal propagates.""" if not self.tickets: self.compile() + previous = self.spend.totals()["stopped"] + if previous: + raise Rejected("envelope_stopped", f"this envelope's ledger already stopped ({previous}); issue a new envelope for a new run") self.order = [f["id"] for f in self.map["features"]] kill = self.envelope.get("kill_switch") - stopped = None - self.kit = Kit.local(self.kit_home, self.repo_root, actor=self.actor) + stopped, failure = None, None try: + self.kit = Kit.local(self.kit_home, self.repo_root, actor=self.actor) for _ in range(max_steps): if kill and Path(kill).exists(): stopped = "kill_switch" @@ -398,19 +535,36 @@ def run(self, max_steps: int = 50) -> dict: stopped = "envelope_exhausted" break chosen = self.ask("next_feature", None, eligible).value - arms = [a["id"] for a in self.envelope["arms"]] - arm = self.ask("proposer_arm", chosen, arms).value + arm = self.ask("proposer_arm", chosen, self._arms(chosen)).value tier = self.ask("budget_tier", chosen, tiers).value self._attempt(chosen, arm, tier) else: stopped = "max_steps" + except Rejected as exc: + stopped, failure = exc.code, exc finally: - self.kit.close() + if self.kit is not None: + self.kit.close() self.spend.stop(stopped) record(self.ledger, "loop_stopped", self.map_digest, {"reason": stopped, "states": {fid: row["state"] for fid, row in self.state.items()}, - "calls": self.spend.totals()["calls"], "dollars": self.spend.totals()["dollars"]}) + "calls": self.spend.totals()["calls"], "dollars": self.spend.totals()["dollars"]}, + refs={"detail": failure.detail} if failure else None) + if failure is not None: + raise failure return self.summary(stopped) + def _arm_rank(self, arm_id: str) -> int: + return int(next(a for a in self.envelope["arms"] if a["id"] == arm_id).get("tier_rank", 0)) + + def _arms(self, fid: str) -> list[str]: + """The arms this feature may run now: every arm of the envelope, or after ``retry_escalate_arm`` only the + arms ranked above the one that failed, so the recorded decision is the one that happens.""" + floor = self.state[fid]["arm_floor"] + offered = [a["id"] for a in self.envelope["arms"] if int(a.get("tier_rank", 0)) >= floor] + if not offered: + raise Rejected("arm_unavailable", f"{fid}: no arm of the envelope is ranked at or above {floor}") + return offered + def summary(self, stopped: str | None = None) -> dict: totals = self.spend.totals() return {"stopped": stopped or totals["stopped"], "map_digest": self.map_digest, @@ -428,14 +582,16 @@ def _attempt(self, fid: str, arm_id: str, tier: str) -> None: record(self.ledger, "envelope_reserved", self.map_digest, {"feature": fid, "attempt": attempt, "tier": tier, "arm": arm_id, "dollars": self.envelope["dollars"]["tiers"][tier]}) arm = next(a for a in self.envelope["arms"] if a["id"] == arm_id) + row["last_arm"] = arm_id started = time.monotonic() stacked = None - if item["depends_on"] and self.map["integration"] == "stack": - stacked = self.state[item["depends_on"][-1]]["commit"] # one branch: the last dependency's accepted commit - self.kit.repo.git("checkout", "-q", "-B", f"syberfactory/{self.map['id']}/{fid}", stacked) objective = f"{fid}: {ticket['objective']}\nCriteria: " + "; ".join(f"{c['id']} {c['text']}" for c in ticket["acceptance_criteria"]) contract = f"syberfactory-{ticket['ticket_id']}.v1" - thread = self.kit.start(objective, contract=contract, paths=item["scope"]["paths"], act_class=item["act_class"], unattended=True) + if item["depends_on"] and self.map["integration"] == "stack": + stacked = self.state[item["depends_on"][-1]]["commit"] # one branch: the last dependency's accepted commit + thread = self._start_stacked(fid, stacked, objective, contract, item) + else: + thread = self.kit.start(objective, contract=contract, paths=item["scope"]["paths"], act_class=item["act_class"], unattended=True) row["state"], row["thread"] = "building", thread.id record(self.ledger, "attempt_started", self.map_digest, {"feature": fid, "attempt": attempt, "ticket_id": ticket["ticket_id"], "arm": arm_id, "tier": tier, "contract": contract, "stacked": stacked is not None}, @@ -470,6 +626,27 @@ def _attempt(self, fid: str, arm_id: str, tier: str) -> None: record(self.ledger, "feature_failed", self.map_digest, {"feature": fid, "attempt": attempt, "reason": reason}, refs={"thread": thread.id}) self._after_failure(fid) + def _start_stacked(self, fid: str, commit: str, objective: str, contract: str, item: dict): + """Start a thread from a dependency's accepted commit. ``Kit.start`` starts from HEAD, so HEAD is moved + to that commit on a scratch branch for the start and put back afterwards (the branch or detached commit + the owner had), whether or not the start succeeded; the scratch branch is deleted. A working tree with + uncommitted tracked changes is refused first (``repository_dirty``): a checkout would carry or lose them.""" + repo = self.kit.repo + if repo.git("status", "--porcelain", "--untracked-files=no").strip(): + raise Rejected("repository_dirty", f"{repo.root} has uncommitted changes; commit or stash them before a stacked feature starts") + branch = repo.current_branch() + head = repo.rev("HEAD") + scratch = f"syberfactory/{self.map['id']}/{fid}" + repo.git("checkout", "-q", "-B", scratch, commit) + try: + return self.kit.start(objective, contract=contract, paths=item["scope"]["paths"], act_class=item["act_class"], unattended=True) + finally: + if branch: + repo.git("checkout", "-q", branch[len("refs/heads/"):] if branch.startswith("refs/heads/") else branch) + else: + repo.git("checkout", "-q", "--detach", head) + repo.git("branch", "-q", "-D", scratch, ok=(0, 1)) + def _drive(self, thread, fid: str, attempt: int) -> tuple[str, str | None]: """``syberlabs run``'s passes over this one thread until nothing is left: the kernel checks, accepts and recovers; this records what each pass did.""" @@ -495,13 +672,17 @@ def _after_failure(self, fid: str) -> None: options = ["continue", "stop"] if left > 0 else ["stop"] worth = self.ask("worth_continuing", fid, options).value choices = [] + last_rank = self._arm_rank(row["last_arm"]) if row["last_arm"] else 0 + stronger = [a["id"] for a in self.envelope["arms"] if int(a.get("tier_rank", 0)) > last_rank] if worth == "continue" and left > 0: choices.append("retry_same") - if len(self.envelope["arms"]) > 1: + if stronger: choices.append("retry_escalate_arm") choices += ["escalate_owner", "park"] decision = self.ask("after_failure", fid, choices).value if decision in ("retry_same", "retry_escalate_arm"): + if decision == "retry_escalate_arm": + row["arm_floor"] = last_rank + 1 # the next attempt's proposer_arm offers only the stronger arms row["state"] = "open" # eligible again; the next step may pick it or another feature return row["state"] = "escalated" if decision == "escalate_owner" else "parked" diff --git a/syberlabs/factory/policy.py b/syberlabs/factory/policy.py index 7179371..853b17b 100644 --- a/syberlabs/factory/policy.py +++ b/syberlabs/factory/policy.py @@ -10,7 +10,8 @@ - ``next_feature`` (choice): the eligible features (dependencies satisfied, no conflicting scope running, act class allowed, room in the envelope, attempts left). With no eligible feature the loop stops; no question. -- ``proposer_arm`` (choice): the envelope's arms that fit the remaining dollars. +- ``proposer_arm`` (choice): the envelope's arms; after ``retry_escalate_arm`` only the arms ranked above the one + that failed, so the cheapest answer is then the cheapest stronger arm. - ``budget_tier`` (choice): the tiers whose ceiling fits the remaining dollars (``S``, ``M``, ``L``). - ``after_failure`` (choice): ``retry_same``, ``retry_escalate_arm``, ``escalate_owner``, ``park``; an option is removed when the caps forbid it (no attempts left removes the retries). diff --git a/tests/test_factory_autonomy.py b/tests/test_factory_autonomy.py index 706f6c6..e037594 100644 --- a/tests/test_factory_autonomy.py +++ b/tests/test_factory_autonomy.py @@ -1,8 +1,10 @@ """The autonomy thin slice (AM1) on the fixture app: spec -> approved feature map -> tickets on the ledger -> Build Threads driven by the runner with a stand-in proposer -> features ready for the owner's merge, inside an envelope. -Offline, no model, no network, no merge.""" +Offline, no model, no network, no merge. The spec is promoted through the goal gate's real path: review and +validate events on the ledger, the owner's signed approval verified and recorded, the promotion citing it.""" import json +import math import os import shutil import subprocess @@ -11,6 +13,8 @@ import unittest from pathlib import Path +from syberlabs.canonical import canonical +from syberlabs.ed25519 import generate from syberlabs.errors import Rejected from syberlabs.factory import featuremap, ledger, loop, space from syberlabs.factory import policy as policymod @@ -21,20 +25,47 @@ AUTONOMY = ROOT / "tests" / "fixtures" / "autonomy" DECLARED = json.loads((APP / "architecture.json").read_text(encoding="utf-8")) OWNER = {"kind": "human", "id": "tester"} +OWNER_SEED, OWNER_PUBLIC = generate() +VERDICT = "review-1" GIT_ENV = {"GIT_AUTHOR_NAME": "t", "GIT_AUTHOR_EMAIL": "t@example.test", "GIT_COMMITTER_NAME": "t", "GIT_COMMITTER_EMAIL": "t@example.test", "GIT_AUTHOR_DATE": "2026-01-01T00:00:00Z", "GIT_COMMITTER_DATE": "2026-01-01T00:00:00Z"} -def promoted_spec(project: Path) -> dict: - """The fixture spec as #154's object: from sectioned Markdown, footprint resolved against Space, validated, promoted.""" +def candidate_spec(project: Path) -> dict: + """The fixture spec as #154's object: from sectioned Markdown, footprint resolved against Space, validated.""" document = featuremap.spec_from_markdown((AUTONOMY / "spec.md").read_text(encoding="utf-8"), "order-markers", "delivery markers on the order path", ["rules", "ingest", "main"], author=OWNER) graph = space.index(project, revision="base") space.map_components(graph, DECLARED) specmod.resolve_footprint(document, graph) specmod.transition(document, "validate", OWNER, space=graph) - specmod.transition(document, "promote", OWNER, verdict_ids=["review-1"]) + return document + + +def promoted_spec(project: Path, home: ledger.Ledger, *, seed: bytes = OWNER_SEED, public: bytes = OWNER_PUBLIC) -> dict: + """The candidate promoted the way `factory spec promote` does it (C1's goal gate): a model's variant, an + independent reviewer's accepting verdict and the validate that wrote the candidate are on the ledger; the + owner signs an approval over the spec's digest, `gate` resolves the verdict and verifies the approval, + `transition` promotes, the approval is recorded and the `spec_changed` cites it.""" + document = candidate_spec(project) + before = specmod.spec_digest(document) + reviewer = {"kind": "model", "id": "gpt", "model": "gpt-5", "family": "openai"} + home.append("spec_changed", {"spec_id": document["spec_id"], "version": document["version"], "operation": "mutate", + "variant_id": "var1", "actor": {"kind": "model", "id": "claude", "family": "anthropic"}}) + home.append("spec_changed", {"spec_id": document["spec_id"], "version": document["version"], "operation": "review", + "verdict_id": VERDICT, "variant_id": "var1", "decision": "accept", "actor": reviewer}) + home.append("spec_changed", {"spec_id": document["spec_id"], "version": document["version"], "operation": "validate", + "accepted_variant": "var1", "verdict_id": VERDICT, "spec_digest": before}) + envelope = specmod.sign_approval(specmod.approval_payload(document, "promote", OWNER, verdict_ids=[VERDICT]), seed) + approval, resolved = specmod.gate(document, "promote", OWNER, home.events(), envelope, public, verdict_ids=[VERDICT], + spec_digest_value=before) + record = specmod.transition(document, "promote", OWNER, verdict_ids=[VERDICT], approval=approval, spec_digest=before, + resolved_verdicts=resolved) + event = home.record_approval(envelope, approval) + record["approval"] = {**record["approval"], "event_hash": event["hash"], "approval_digest": event["body"]["approval_digest"]} + home.append("spec_changed", {"spec_id": document["spec_id"], "version": document["version"], **record, + "spec_digest": specmod.spec_digest(document), "footprint": document["footprint"]["components"]}) return document @@ -51,6 +82,11 @@ def hidden_catalogue() -> dict: return {name: [arg.replace("{python}", sys.executable) for arg in argv] for name, argv in raw.items() if not name.startswith("_")} +def git(project: Path, *args: str) -> str: + env = {**os.environ, **GIT_ENV} + return subprocess.run(["git", "-C", str(project), *args], check=True, capture_output=True, text=True, env=env).stdout.strip() + + class Scratch(unittest.TestCase): def setUp(self): self.scratch = Path(tempfile.mkdtemp(prefix="autonomy-")) @@ -60,23 +96,36 @@ def project(self, name="project") -> tuple[Path, str]: """A copy of the fixture app as a Git repository with a deterministic base commit.""" project = self.scratch / name shutil.copytree(APP, project) - env = {**os.environ, **GIT_ENV} - git = lambda *a: subprocess.run(["git", "-C", str(project), *a], check=True, capture_output=True, text=True, env=env).stdout.strip() - git("init", "-q", "-b", "main") - git("add", ".") - git("-c", "commit.gpgsign=false", "commit", "-qm", "base") - return project, git("rev-parse", "HEAD") - - def make_loop(self, project: Path, mapping: dict, document: dict, *, calls_total=10, attempts=2, mode="", policy=None, - kill_switch=None, ledger_name="ledger") -> loop.Loop: - home = ledger.Ledger(self.scratch / ledger_name) + git(project, "init", "-q", "-b", "main") + git(project, "add", ".") + git(project, "-c", "commit.gpgsign=false", "commit", "-qm", "base") + return project, git(project, "rev-parse", "HEAD") + + def home(self, name="ledger") -> ledger.Ledger: + return ledger.Ledger(self.scratch / name) + + def make_loop(self, project: Path, mapping: dict, document: dict, home: ledger.Ledger, *, calls_total=10, attempts=2, mode="", + policy=None, kill_switch=None, arms=None, owner_public=None) -> loop.Loop: envelope = loop.new_envelope(featuremap.map_digest(mapping), dollars_total=0.0, calls_total=calls_total, seconds_total=600, - attempts_per_feature=attempts, kill_switch=kill_switch) + attempts_per_feature=attempts, kill_switch=kill_switch, arms=arms) argv = [sys.executable, str(AUTONOMY / "standin_proposer.py"), str(project)] + ([mode] if mode else []) checks = {"tests": {"argv": [sys.executable, "-c", "import fxapp.main, fxapp.variants"], "timeout_seconds": 60}} return loop.Loop(repo_root=project, kit_home=project / ".syberlabs", ledger=home, map=mapping, spec=document, envelope=envelope, policy=policy or policymod.OfflinePolicy(), proposer_argv=argv, checks=checks, hidden_catalogue=hidden_catalogue(), - human_owner="tester") + human_owner="tester", owner_public=owner_public) + + def ready_loop(self, name="project", ledger_name="ledger", **overrides) -> tuple[loop.Loop, Path, str, dict]: + """A project, a promoted spec on a fresh ledger and an approved fixture map: the loop ready to compile.""" + project, base = self.project(name) + home = self.home(ledger_name) + document = promoted_spec(project, home) + mapping = fixture_map(document, base, **overrides.pop("map", {})) + featuremap.approve(mapping, OWNER) + return self.make_loop(project, mapping, document, home, **overrides), project, base, mapping + + +def notes(events, note): + return [e for e in events if e["kind"] == "note" and e["body"]["note"] == note] class SpecAndMap(Scratch): @@ -91,7 +140,7 @@ def test_sectioned_markdown_becomes_the_spec_object(self): def test_fixture_map_validates_and_the_task_graph_measures(self): project, base = self.project() - document = promoted_spec(project) + document = promoted_spec(project, self.home()) mapping = fixture_map(document, base) self.assertEqual(featuremap.mapcheck(mapping, document), []) graph = featuremap.taskgraph(mapping) @@ -115,7 +164,7 @@ def test_fixture_map_validates_and_the_task_graph_measures(self): def test_mapcheck_refuses_a_cycle_flags_a_scope_conflict_and_checks_coverage(self): project, base = self.project() - document = promoted_spec(project) + document = promoted_spec(project, self.home()) cyclic = fixture_map(document, base) cyclic["features"][0]["depends_on"] = ["F2"] findings = featuremap.mapcheck(cyclic, document) @@ -151,10 +200,18 @@ def test_mapcheck_refuses_a_cycle_flags_a_scope_conflict_and_checks_coverage(sel shared = fixture_map(document, base) shared["features"][1]["hidden_checks"] = ["hidden.f1.marker"] self.assertTrue(any("also named by F1" in f for f in featuremap.mapcheck(shared, document))) + # Scope entries are compared normalised: case, leading "./" segments, backslashes and a trailing slash. + cased = fixture_map(document, base) + cased["features"][2]["scope"]["paths"] = ["./FXAPP/Rules.py"] + self.assertTrue(any(f.startswith("scope conflict: F1 and F3") for f in featuremap.mapcheck(cased, document)), + "FXAPP/Rules.py is fxapp/rules.py on a case-insensitive filesystem") + self.assertTrue(featuremap.path_intersects("./fxapp\\rules.py", "FXAPP/")) + self.assertFalse(featuremap.path_intersects(".github/x", "github/x"), "a leading dot is part of a name, not a './' prefix") + self.assertFalse(featuremap.path_intersects("fxapp/rules.py", "fxapp/rules")) def test_risk_plan_keeps_the_floor_and_allocates_softmax_units(self): project, base = self.project() - document = promoted_spec(project) + document = promoted_spec(project, self.home()) mapping = fixture_map(document, base) plan = featuremap.risk_plan(mapping, budget=4, tau=1.0) self.assertEqual(sum(plan["units"].values()), 4) @@ -168,6 +225,13 @@ def test_risk_plan_keeps_the_floor_and_allocates_softmax_units(self): self.assertGreaterEqual(max(sharp["share"].values()), max(plan["share"].values()), "a lower tau concentrates") with self.assertRaises(Rejected): featuremap.risk_plan(mapping, tau=0.01) + # Weights are validated: exactly the known inputs, each in [0, 1], summing to 1, so r stays in [0, 1]. + for bad in ({**featuremap.WEIGHTS, "scope": 0.5}, {k: v for k, v in featuremap.WEIGHTS.items() if k != "scope"}, + {**featuremap.WEIGHTS, "extra": 0.0}, {**featuremap.WEIGHTS, "scope": -0.15, "act_class": 0.45}, + {**featuremap.WEIGHTS, "scope": float("nan")}): + with self.assertRaises(Rejected, msg=str(bad)) as refused: + featuremap.risk_plan(mapping, weights=bad) + self.assertEqual(refused.exception.code, "risk_weights") flat = fixture_map(document, base) for item in flat["features"]: item["depends_on"], item["size"], item["criteria"] = [], "S", [{"id": f"{item['id']}.c1", "text": "x", "kind": "test"}] @@ -178,7 +242,7 @@ def test_risk_plan_keeps_the_floor_and_allocates_softmax_units(self): def test_a_feature_compiles_to_one_ticket_in_the_spec_ticket_shape(self): project, base = self.project() - document = promoted_spec(project) + document = promoted_spec(project, self.home()) mapping = fixture_map(document, base) featuremap.approve(mapping, OWNER) graph = space.index(project, revision="base") @@ -266,24 +330,96 @@ def test_shadow_records_disagreement_and_never_acts(self): self.assertEqual(shadow.disagreements, 2) +class Envelope(unittest.TestCase): + def setUp(self): + self.scratch = Path(tempfile.mkdtemp(prefix="envelope-")) + self.addCleanup(shutil.rmtree, self.scratch, True) + self.envelope = loop.new_envelope("m" * 64, dollars_total=1.0, calls_total=3, seconds_total=10.0) + self.spend = loop.EnvelopeLedger(loop.envelope_path(self.scratch, self.envelope), self.envelope) + + def raw(self, **fields) -> None: + line = {"schema": loop.ENVELOPE_LINE_SCHEMA, "envelope_digest": self.spend.digest, **fields} + with self.spend.path.open("a", encoding="utf-8", newline="\n") as handle: + handle.write(canonical(line) + "\n") + + def refuses(self, code, call, *args, **kwargs): + with self.assertRaises(Rejected, msg=f"{args} {kwargs}") as refused: + call(*args, **kwargs) + self.assertEqual(refused.exception.code, code, refused.exception.detail) + + def test_the_kill_switch_path_stays_out_of_the_digest_and_the_file_is_keyed_by_it(self): + with_switch = loop.new_envelope("m" * 64, dollars_total=1.0, calls_total=3, seconds_total=10.0, kill_switch=str(self.scratch / "stop")) + self.assertEqual(loop.envelope_digest(with_switch), self.spend.digest, "a host path is not a term of the grant") + self.assertEqual(self.spend.path, self.scratch / loop.ENVELOPE_DIR / f"{self.spend.digest}.jsonl") + other = loop.new_envelope("m" * 64, dollars_total=1.0, calls_total=4, seconds_total=10.0) + self.assertNotEqual(loop.envelope_path(self.scratch, other), self.spend.path, "another grant, another file") + + def test_reserve_and_settle_are_strict(self): + self.refuses("envelope_conflict", self.spend.settle, "F1", 1, dollars=0.0, calls=1, seconds=1.0, unknown_models=[]) + self.spend.reserve("F1", 1, "S", "standin") + self.refuses("envelope_conflict", self.spend.reserve, "F1", 1, "S", "standin") + for bad in ({"calls": -1}, {"calls": 1.0}, {"seconds": -0.5}, {"seconds": float("nan")}, {"dollars": float("inf")}, + {"dollars": -0.01}, {"calls": True}): + fields = {"dollars": 0.0, "calls": 1, "seconds": 1.0, **bad} + self.refuses("envelope_unpriced", self.spend.settle, "F1", 1, unknown_models=[], **fields) + self.assertEqual([line["kind"] for line in self.spend.lines()], ["reserve"], "a refused settle wrote nothing") + self.spend.settle("F1", 1, dollars=0.25, calls=1, seconds=2.0, unknown_models=[]) + self.refuses("envelope_conflict", self.spend.settle, "F1", 1, dollars=0.0, calls=1, seconds=1.0, unknown_models=[]) + totals = self.spend.totals() + self.assertEqual((totals["calls"], totals["dollars"], totals["seconds"], totals["unsettled"]), (1, 0.25, 2.0, 0)) + self.assertEqual((totals["calls_left"], totals["dollars_left"]), (2, 0.75)) + + def test_a_file_line_that_is_not_a_priced_envelope_line_refuses_the_file(self): + self.spend.reserve("F1", 1, "S", "standin") + cases = [ + ("envelope_unreadable", {"feature": "F1", "attempt": 1, "dollars": 0.0, "calls": 1, "seconds": 0.0}), # no kind: not a KeyError + ("envelope_unreadable", {"kind": "refund", "feature": "F1", "attempt": 1, "dollars": 0.0, "calls": 1, "seconds": 0.0}), + ("envelope_unpriced", {"kind": "settle", "feature": "F1", "attempt": 1, "dollars": -1.0, "calls": 1, "seconds": 0.0}), + ("envelope_unpriced", {"kind": "settle", "feature": "F1", "attempt": 1, "dollars": 0.0, "calls": -2, "seconds": 0.0}), + ("envelope_unpriced", {"kind": "settle", "feature": "F1", "attempt": 1, "dollars": 0.0, "calls": 1, "seconds": -3.0}), + ("envelope_unpriced", {"kind": "reserve", "feature": "F1", "attempt": 2, "dollars": 0.0, "calls": "1", "seconds": 0.0}), + ("envelope_unreadable", {"kind": "reserve", "attempt": 2, "dollars": 0.0, "calls": 1, "seconds": 0.0}), # no feature + ("envelope_unreadable", {"kind": "stop"}), # no reason + ("envelope_conflict", {"kind": "reserve", "feature": "F1", "attempt": 1, "dollars": 0.0, "calls": 1, "seconds": 0.0}), + ("envelope_conflict", {"kind": "settle", "feature": "F2", "attempt": 1, "dollars": 0.0, "calls": 1, "seconds": 0.0}), + ] + good = self.spend.path.read_text(encoding="utf-8") + for code, fields in cases: + self.raw(**fields) + self.refuses(code, self.spend.totals) + self.refuses(code, self.spend.room, "S") + self.spend.path.write_text(good, encoding="utf-8") + self.raw(kind="stop", reason="x", envelope_digest="0" * 64) + self.refuses("envelope_unreadable", self.spend.totals) + self.spend.path.write_text(good, encoding="utf-8") + self.raw(kind="settle", feature="F1", attempt=1, dollars=0.0, calls=1, seconds=0.0) + self.raw(kind="settle", feature="F1", attempt=1, dollars=0.0, calls=1, seconds=0.0) + self.refuses("envelope_conflict", self.spend.totals) + self.spend.path.write_text(good, encoding="utf-8") + self.assertEqual(self.spend.totals()["calls"], 1, "the hold counts until it settles") + + class EndToEnd(Scratch): def test_the_thin_slice_builds_three_features_to_ready_for_owner_merge(self): project, base = self.project() - document = promoted_spec(project) + home = self.home() + document = promoted_spec(project, home) mapping = fixture_map(document, base) featuremap.approve(mapping, OWNER) recorded = policymod.recorded_answers({"next_feature": "F3", "budget_tier": "S", "proposer_arm": "standin"}) shadow = policymod.ShadowPolicy(policymod.OfflinePolicy(), recorded, shadow_name="recorded-jev") - run = self.make_loop(project, mapping, document, policy=shadow) + run = self.make_loop(project, mapping, document, home, policy=shadow, owner_public=OWNER_PUBLIC) tickets = run.compile() - home = run.ledger self.assertEqual([t["map_ref"]["feature_id"] for t in tickets], ["F1", "F2", "F3"]) + self.assertTrue(run.promotion["verified"], "the owner's approval was re-verified under the owner's key") opened = [e for e in home.events() if e["kind"] == "ticket_opened"] self.assertEqual([(e["body"]["feature_id"], e["body"]["source"], e["body"]["human_owner"]) for e in opened], [("F1", "map", "tester"), ("F2", "map", "tester"), ("F3", "map", "tester")]) - frozen = [e for e in home.events() if e["kind"] == "note" and e["body"]["note"] == "map_frozen"] + frozen = notes(home.events(), "map_frozen") self.assertEqual(len(frozen), 1) self.assertEqual(frozen[0]["body"]["approved_by"], OWNER) + self.assertEqual(frozen[0]["body"]["promoted_by"], OWNER) + self.assertEqual(frozen[0]["body"]["refs"]["promotion"]["approval_digest"], run.promotion["approval_digest"]) self.assertEqual(frozen[0]["body"]["critical_path"], ["F1", "F2"]) contracts = sorted(p.name for p in (project / ".syberlabs" / "contracts").glob("*.json")) self.assertEqual(contracts, sorted(f"syberfactory-{t['ticket_id']}.v1.json" for t in tickets)) @@ -299,14 +435,12 @@ def test_the_thin_slice_builds_three_features_to_ready_for_owner_merge(self): self.assertEqual(summary["envelope"]["unsettled"], 0) events = loop.autonomy_events(home) kinds = [(e["kind"] if e["kind"] != "note" else e["body"]["note"]) for e in events] - picks = [e["body"]["answer"]["value"] for e in events if e["kind"] == "note" and e["body"]["note"] == "policy_proposal" - and e["body"]["question"] == "next_feature"] + picks = [e["body"]["answer"]["value"] for e in notes(events, "policy_proposal") if e["body"]["question"] == "next_feature"] self.assertEqual(picks, ["F1", "F3", "F2"], "critical path first: F1 (bottom level 2, a dependent), then F3 (M), then F2") - shadows = [e["body"]["answer"]["shadow"] for e in events if e["kind"] == "note" and e["body"]["note"] == "policy_proposal" - and e["body"]["question"] == "next_feature"] + shadows = [e["body"]["answer"]["shadow"] for e in notes(events, "policy_proposal") if e["body"]["question"] == "next_feature"] self.assertEqual([s["agrees"] for s in shadows], [False, True, None], "the shadow disagreed on the first pick and was out of options on the last") self.assertEqual(shadows[2]["reason"], "policy_invalid") - steps = [(e["body"]["feature"], e["body"]["step"], e["body"]["outcome"]) for e in events if e["kind"] == "note" and e["body"]["note"] == "thread_step"] + steps = [(e["body"]["feature"], e["body"]["step"], e["body"]["outcome"]) for e in notes(events, "thread_step")] self.assertEqual(steps, [("F1", "check", "acceptable"), ("F1", "accept", "succeeded"), ("F3", "check", "acceptable"), ("F3", "accept", "succeeded"), ("F2", "check", "acceptable"), ("F2", "accept", "succeeded")]) @@ -315,90 +449,158 @@ def test_the_thin_slice_builds_three_features_to_ready_for_owner_merge(self): self.assertEqual(kinds.count("feature_ready"), 3) self.assertEqual(kinds.count("feature_failed"), 0) self.assertTrue(home.verify()) - ready = [e for e in events if e["kind"] == "note" and e["body"]["note"] == "feature_ready"] - for event in ready: + for event in notes(events, "feature_ready"): self.assertTrue(event["body"]["refs"]["target_ref"].startswith("refs/heads/syberlabs/")) self.assertEqual(event["body"]["next"], "owner merges; nothing here merges") - main = subprocess.run(["git", "-C", str(project), "rev-parse", "main"], capture_output=True, text=True, check=True).stdout.strip() - self.assertEqual(main, base, "main never moved") + self.assertEqual(git(project, "rev-parse", "main"), base, "main never moved") + # The owner's checkout is as it was: HEAD on main at the base commit, a clean tree, no scratch branch left. + self.assertEqual(git(project, "symbolic-ref", "HEAD"), "refs/heads/main") + self.assertEqual(git(project, "rev-parse", "HEAD"), base) + self.assertEqual(git(project, "status", "--porcelain"), "") + self.assertEqual([b for b in git(project, "branch", "--list", "syberfactory/*").split() if b], []) f2 = summary["features"]["F2"]["commit"] - shown = subprocess.run(["git", "-C", str(project), "show", f"{f2}:fxapp/rules.py"], capture_output=True, text=True, check=True).stdout + shown = git(project, "show", f"{f2}:fxapp/rules.py") self.assertIn("# F1 delivered", shown, "F2 stacked on F1's accepted commit") walk = loop.why(home, tickets[1]["ticket_id"]) self.assertEqual((walk["feature"], walk["requirements"], walk["map"]["approved_by"]), ("F2", ["R2"], OWNER)) self.assertEqual(walk["spec"]["digest"], specmod.spec_digest(document)) + self.assertEqual(walk["spec"]["promoted_by"], OWNER) + self.assertEqual(walk["spec"]["promotion"]["seq"], run.promotion["seq"]) self.assertEqual(walk["ready_for_owner_merge"]["commit"], f2) self.assertEqual(run.spend.totals()["stopped"], "nothing_eligible") + self.assertEqual(run.spend.path.parent.name, loop.ENVELOPE_DIR) # The same list, for the report: every autonomy event in order. print("\nledger events:", " ".join(kinds)) def test_same_fixture_gives_the_same_event_digests(self): digests = [] for name in ("one", "two"): - project, base = self.project(name) - document = promoted_spec(project) - mapping = fixture_map(document, base) - featuremap.approve(mapping, OWNER) - run = self.make_loop(project, mapping, document, ledger_name=f"ledger-{name}") + run, _, _, _ = self.ready_loop(name, f"ledger-{name}") run.run() digests.append(loop.event_digests(run.ledger)) self.assertEqual(len(digests[0]), len(digests[1])) - self.assertEqual(digests[0], digests[1], "no timestamp, thread id or commit enters an event digest") + self.assertEqual(digests[0], digests[1], "no timestamp, thread id, commit or approval digest enters an event digest") self.assertGreater(len(digests[0]), 20) + def test_compile_needs_the_ledgers_promotion_record_not_the_files_state(self): + """The file's ``state`` decides nothing: the ledger must hold a promote of exactly this spec, citing a + recorded approval by a human, whose envelope is stored; with the owner's key it must verify.""" + project, base = self.project() + home = self.home() + in_memory = candidate_spec(project) + payload = specmod.approval_payload(in_memory, "promote", OWNER, verdict_ids=[VERDICT]) + approval = specmod.verify_approval(specmod.sign_approval(payload, OWNER_SEED), OWNER_PUBLIC, in_memory, "promote", verdict_ids=[VERDICT]) + specmod.transition(in_memory, "promote", OWNER, verdict_ids=[VERDICT], approval=approval) + self.assertEqual(in_memory["state"], "promoted", "the file says promoted") + mapping = fixture_map(in_memory, base) + featuremap.approve(mapping, OWNER) + run = self.make_loop(project, mapping, in_memory, home) + with self.assertRaises(Rejected) as refused: + run.compile() + self.assertEqual(refused.exception.code, "spec_unpromoted", "promoted in memory, never on the ledger") + self.assertEqual(loop.autonomy_events(home), [], "nothing was logged") + + document = promoted_spec(project, home) + edited = json.loads(json.dumps(document)) + edited["capability"] = "edited after promotion" + mapping = fixture_map(edited, base) + featuremap.approve(mapping, OWNER) + with self.assertRaises(Rejected) as refused: + self.make_loop(project, mapping, edited, home).compile() + self.assertEqual(refused.exception.code, "spec_unpromoted", "the file is not the spec the ledger promoted") + + mapping = fixture_map(document, base) + featuremap.approve(mapping, OWNER) + with self.assertRaises(Rejected) as refused: + self.make_loop(project, mapping, document, home, owner_public=generate()[1]).compile() + self.assertEqual(refused.exception.code, "approval_unverified", "another owner's key: the stored approval is no approval") + + approvals = next(p for p in (home.home / "approvals").glob("*.json")) + kept = approvals.read_text(encoding="utf-8") + approvals.write_text(kept.replace('"', "'", 1), encoding="utf-8") + with self.assertRaises(Rejected) as refused: + self.make_loop(project, mapping, document, home).compile() + self.assertEqual(refused.exception.code, "spec_unpromoted", "a damaged approval envelope refuses even without a key") + approvals.write_text(kept, encoding="utf-8") + + run = self.make_loop(project, mapping, document, home, owner_public=OWNER_PUBLIC) + run.compile() + self.assertEqual(run.promotion["approver"], OWNER) + self.assertEqual(run.promotion["verdict_ids"], [VERDICT]) + self.assertTrue(run.promotion["verified"]) + self.assertEqual(loop.promotion_record(home, document)["verified"], False, "without a key the record is checked, not the signature") + def test_a_map_without_owner_approval_is_refused(self): project, base = self.project() - document = promoted_spec(project) + home = self.home() + document = promoted_spec(project, home) mapping = fixture_map(document, base) - run = self.make_loop(project, mapping, document) + run = self.make_loop(project, mapping, document, home) with self.assertRaises(Rejected) as refused: run.compile() self.assertEqual(refused.exception.code, "map_unapproved") - self.assertEqual(run.ledger.events(), [], "nothing was logged") + self.assertEqual(loop.autonomy_events(home), [], "nothing was logged") featuremap.approve(mapping, OWNER) mapping["features"][0]["depends_on"] = ["F2"] - run = self.make_loop(project, mapping, document, ledger_name="ledger2") + run = self.make_loop(project, mapping, document, home) with self.assertRaises(Rejected) as refused: run.compile() self.assertEqual(refused.exception.code, "map_unapproved", "an edit after approval leaves the approval stale") featuremap.approve(mapping, OWNER) - run = self.make_loop(project, mapping, document, ledger_name="ledger3") + run = self.make_loop(project, mapping, document, home) with self.assertRaises(Rejected) as refused: run.compile() self.assertEqual(refused.exception.code, "map_invalid") self.assertIn("cycle", refused.exception.detail) def test_the_envelope_stops_the_loop(self): - project, base = self.project() - document = promoted_spec(project) - mapping = fixture_map(document, base) - featuremap.approve(mapping, OWNER) - run = self.make_loop(project, mapping, document, calls_total=2) + run, _, _, _ = self.ready_loop(calls_total=2) summary = run.run() self.assertEqual(summary["stopped"], "envelope_exhausted") self.assertEqual(summary["ready_for_owner_merge"], ["F1", "F3"]) self.assertEqual(summary["features"]["F2"]["state"], "open", "F2 was eligible and waits for a new envelope") self.assertEqual(summary["envelope"]["calls_left"], 0) self.assertEqual(run.spend.totals()["stopped"], "envelope_exhausted") - lines = run.spend.lines() - self.assertEqual([line["kind"] for line in lines], ["reserve", "settle", "reserve", "settle", "stop"]) + self.assertEqual([line["kind"] for line in run.spend.lines()], ["reserve", "settle", "reserve", "settle", "stop"]) + + def test_two_maps_in_one_home_keep_their_own_envelopes(self): + """One file per envelope digest: a second map (or a second grant) in the same factory home starts + with its own spend and no inherited stop; the same spent grant is refused, not silently re-run.""" + project_a, base = self.project("a") + home = self.home() + document = promoted_spec(project_a, home) + first = fixture_map(document, base) + featuremap.approve(first, OWNER) + run_a = self.make_loop(project_a, first, document, home) + self.assertEqual(run_a.run()["stopped"], "nothing_eligible") + project_b, base_b = self.project("b") + self.assertEqual(base_b, base, "the fixture's base commit is deterministic") + second = fixture_map(document, base, id="order-markers.m2") + featuremap.approve(second, OWNER) + run_b = self.make_loop(project_b, second, document, home) + self.assertNotEqual(run_b.spend.path, run_a.spend.path) + summary = run_b.run() + self.assertEqual(summary["stopped"], "nothing_eligible") + self.assertEqual(summary["ready_for_owner_merge"], ["F1", "F2", "F3"], "the second map built; it inherited no stop and no spend") + self.assertEqual(summary["envelope"]["calls"], 3) + self.assertEqual([line["kind"] for line in run_b.spend.lines()], ["reserve", "settle"] * 3 + ["stop"]) + self.assertEqual(len(notes(home.events(), "loop_stopped")), 2) + again = self.make_loop(project_a, first, document, home) + with self.assertRaises(Rejected) as refused: + again.run() + self.assertEqual(refused.exception.code, "envelope_stopped", "the first grant is spent; a new run needs a new envelope") + self.assertEqual(len(notes(home.events(), "loop_stopped")), 2, "a refused re-run writes nothing") + self.assertEqual([line["kind"] for line in run_a.spend.lines()].count("stop"), 1) def test_await_merge_leaves_a_dependent_waiting_for_the_owner(self): - project, base = self.project() - document = promoted_spec(project) - mapping = fixture_map(document, base, integration="await_merge") - featuremap.approve(mapping, OWNER) - summary = self.make_loop(project, mapping, document).run() + run, _, _, _ = self.ready_loop(map={"integration": "await_merge"}) + summary = run.run() self.assertEqual(summary["ready_for_owner_merge"], ["F1", "F3"]) self.assertEqual(summary["features"]["F2"]["state"], "waiting_owner_merge") self.assertEqual(summary["stopped"], "nothing_eligible") def test_a_failing_candidate_is_refused_by_the_kernel_and_the_feature_is_parked(self): - project, base = self.project() - document = promoted_spec(project) - mapping = fixture_map(document, base) - featuremap.approve(mapping, OWNER) - run = self.make_loop(project, mapping, document, attempts=1, mode="--break") + run, _, _, _ = self.ready_loop(attempts=1, mode="--break") summary = run.run() self.assertEqual(summary["ready_for_owner_merge"], []) self.assertEqual({row["state"] for row in summary["features"].values()} - {"open"}, {"parked"}) @@ -406,17 +608,33 @@ def test_a_failing_candidate_is_refused_by_the_kernel_and_the_feature_is_parked( self.assertIn(summary["features"]["F1"]["last_reason"].split(":")[1], ("tests", "hidden.f1.marker"), "both checks fail; one is named") self.assertEqual(summary["features"]["F2"]["state"], "open", "F2 waits on F1 and never started") events = loop.autonomy_events(run.ledger) - questions = [(e["body"]["question"], e["body"]["answer"]["value"]) for e in events - if e["kind"] == "note" and e["body"]["note"] == "policy_proposal" and e["body"]["feature"] == "F1"] + questions = [(e["body"]["question"], e["body"]["answer"]["value"]) for e in notes(events, "policy_proposal") if e["body"]["feature"] == "F1"] self.assertEqual(questions[-2:], [("worth_continuing", "stop"), ("after_failure", "park")]) self.assertEqual(summary["envelope"]["calls"], 2, "one call per parked feature; the envelope counted both") + def test_retry_escalate_arm_runs_the_stronger_arm_on_the_next_attempt(self): + """The recorded decision is the one that happens: after ``retry_escalate_arm`` the next ``proposer_arm`` + offers only the arms ranked above the one that failed, and the attempt runs on that arm.""" + arms = [{"id": "cheap", "tier_rank": 0, "revision": "1"}, {"id": "strong", "tier_rank": 1, "revision": "1"}] + run, _, _, _ = self.ready_loop(attempts=3, mode="--break", arms=arms) + summary = run.run() + self.assertEqual(summary["features"]["F1"]["state"], "parked") + self.assertEqual(summary["features"]["F1"]["attempts"], 3) + events = loop.autonomy_events(run.ledger) + f1 = lambda note: [e["body"] for e in notes(events, note) if e["body"].get("feature") == "F1"] + self.assertEqual([b["arm"] for b in f1("attempt_started")], ["cheap", "cheap", "strong"]) + self.assertEqual([b["arm"] for b in f1("envelope_reserved")], ["cheap", "cheap", "strong"]) + self.assertEqual([b["answer"]["value"] for b in f1("policy_proposal") if b["question"] == "after_failure"], + ["retry_same", "retry_escalate_arm", "park"]) + offered = [b["options"] for b in f1("policy_proposal") if b["question"] == "proposer_arm"] + self.assertEqual(offered, [["cheap", "strong"], ["cheap", "strong"], ["strong"]], "after the escalation only the stronger arm is an option") + choices = [b["options"] for b in f1("policy_proposal") if b["question"] == "after_failure"] + self.assertNotIn("retry_escalate_arm", choices[2], "on the strongest arm there is nothing to escalate to") + self.assertEqual([line["arm"] for line in run.spend.lines() if line["kind"] == "reserve" and line["feature"] == "F1"], + ["cheap", "cheap", "strong"]) + def test_a_candidate_outside_its_scope_never_reaches_accept(self): - project, base = self.project() - document = promoted_spec(project) - mapping = fixture_map(document, base) - featuremap.approve(mapping, OWNER) - run = self.make_loop(project, mapping, document, attempts=2, mode="--outside") + run, _, _, _ = self.ready_loop(attempts=2, mode="--outside") summary = run.run() self.assertEqual(summary["ready_for_owner_merge"], []) self.assertEqual(summary["features"]["F1"]["last_reason"], "candidate_out_of_scope") @@ -424,18 +642,56 @@ def test_a_candidate_outside_its_scope_never_reaches_accept(self): self.assertEqual(summary["features"]["F1"]["state"], "parked") def test_the_kill_switch_stops_before_the_next_decision(self): - project, base = self.project() - document = promoted_spec(project) - mapping = fixture_map(document, base) - featuremap.approve(mapping, OWNER) switch = self.scratch / "stop-now" switch.write_text("") - run = self.make_loop(project, mapping, document, kill_switch=str(switch)) + run, _, _, _ = self.ready_loop(kill_switch=str(switch)) summary = run.run() self.assertEqual(summary["stopped"], "kill_switch") self.assertEqual(summary["ready_for_owner_merge"], []) self.assertEqual(summary["envelope"]["calls"], 0) + def test_a_rejection_inside_run_still_ends_the_record(self): + """A ``Rejected`` while running (here an answer outside the options) propagates, but not before the + envelope has its ``stop`` line and the ledger its ``loop_stopped`` with the refusal's code.""" + class Rogue: + name = "rogue" + + def decide(self, state, question): + return policymod.Answer(question.key, "F9", self.name, "off the menu") + + run, _, _, _ = self.ready_loop(policy=Rogue()) + with self.assertRaises(Rejected) as refused: + run.run() + self.assertEqual(refused.exception.code, "policy_invalid") + events = loop.autonomy_events(run.ledger) + last = events[-1]["body"] + self.assertEqual((last["note"], last["reason"]), ("loop_stopped", "policy_invalid")) + self.assertIn("rogue answered 'F9'", last["refs"]["detail"]) + self.assertEqual([(line["kind"], line["reason"]) for line in run.spend.lines()], [("stop", "policy_invalid")]) + self.assertEqual(run.spend.totals()["stopped"], "policy_invalid") + self.assertTrue(run.ledger.verify()) + + def test_a_dirty_tree_refuses_the_stacked_start_and_leaves_the_owners_checkout_alone(self): + """Stacking moves HEAD only for the kernel's start and puts it back; a tree with uncommitted tracked + changes is refused before any checkout (``repository_dirty``), the hold stays counted, the record ends.""" + run, project, base, _ = self.ready_loop() + (project / "fxapp" / "main.py").write_text((project / "fxapp" / "main.py").read_text(encoding="utf-8") + "# owner's unsaved work\n", + encoding="utf-8") + with self.assertRaises(Rejected) as refused: + run.run() + self.assertEqual(refused.exception.code, "repository_dirty") + self.assertEqual([fid for fid, row in run.state.items() if row["state"] == "ready_for_owner_merge"], ["F1", "F3"], + "the two unstacked features built; F2's stacked start was refused") + self.assertEqual(git(project, "symbolic-ref", "HEAD"), "refs/heads/main") + self.assertEqual(git(project, "rev-parse", "HEAD"), base) + self.assertIn("# owner's unsaved work", (project / "fxapp" / "main.py").read_text(encoding="utf-8"), "nothing was lost") + self.assertEqual(git(project, "status", "--porcelain", "--untracked-files=no").split(), ["M", "fxapp/main.py"]) + totals = run.spend.totals() + self.assertEqual((totals["stopped"], totals["attempts"], totals["unsettled"]), ("repository_dirty", 3, 1), "the refused attempt's hold counts") + last = loop.autonomy_events(run.ledger)[-1]["body"] + self.assertEqual((last["note"], last["reason"], last["states"]["F2"]), ("loop_stopped", "repository_dirty", "open"), + "refused before its thread started, F2 is still open for a clean tree and a new envelope") + def test_the_slice_holds_no_merge_and_no_network(self): for name in ("featuremap", "policy", "loop", "autonomy_cli"): text = (ROOT / "syberlabs" / "factory" / f"{name}.py").read_text(encoding="utf-8") From 09050345bb64c5b2ae6c8d976541da12cfce8947 Mon Sep 17 00:00:00 2001 From: sykosyber Date: Mon, 2 Nov 2026 02:07:42 -0800 Subject: [PATCH 6/8] Autonomy on the pinned owner key (goal gate c78268a): promotion_record re-verifies the promotion's approval under the owner key the ledger pinned before the approval event (owner_key_unset and owner_key_mismatch refuse), autonomy run takes no --owner-public, the fixture bootstraps the key with set_owner_key and promotes through gate() as the CLI does, and the docs pin the key with factory owner Co-Authored-By: Claude Fable 5.1 --- docs/FACTORY_AUTONOMY.md | 14 ++++---- syberlabs/factory/autonomy_cli.py | 9 ++---- syberlabs/factory/loop.py | 40 +++++++++++++---------- tests/test_factory_autonomy.py | 54 ++++++++++++++++++++----------- 4 files changed, 70 insertions(+), 47 deletions(-) diff --git a/docs/FACTORY_AUTONOMY.md b/docs/FACTORY_AUTONOMY.md index f2aeabb..bb5f048 100644 --- a/docs/FACTORY_AUTONOMY.md +++ b/docs/FACTORY_AUTONOMY.md @@ -25,8 +25,8 @@ spec (promoted) ─► FeatureMap (typed DAG) ─► mapcheck ─► owner | --- | --- | | `featuremap.py` | `feature-map.v1`: features with id, objective, `req_ids` (the spec requirements they trace to), scope paths, shown criteria, hidden-check names (names only), `depends_on`, act class, size, risk inputs. `spec_from_markdown` turns a sectioned Markdown spec (`## R1: text`, `- given, when, then` bullets) into #154's spec object (owner decision 11, D2). `mapcheck` is the deterministic floor: schema, spec digest, coverage, acyclic DAG, scope conflicts (an intersection must be declared with an order that agrees with the DAG), act class, size ceilings, hidden-check names, approval digest. `taskgraph`: critical path, total work, work/critical ratio, Dilworth width with a maximum antichain, conflict graph. `risk_plan`: seven risk inputs computed by code, `r_i` as a weighted sum, standardized `z_i`, `v_i = V * softmax(z_i / tau)` as integer units above a floor that is listed beside every allocation and never moves. `compile_ticket`: one feature to one ticket in `ticket_from_spec`'s shape (D5). `degenerate_map`: the map `ticket_from_spec` implies, one feature per requirement. | | `policy.py` | `Question` (closed options built by code; the state a policy reads is ids and numbers only), `Answer`, `validate` (an answer outside the options is `policy_invalid`), `OfflinePolicy` (critical path first, cheapest arm and tier, retry then stronger arm then owner, park when the cap is spent, stop on the envelope), `ShadowPolicy` (acts on one policy, records what an injected second one would have answered and whether it agrees; an invalid or failing shadow is recorded and changes nothing), `recorded_answers` (a shadow over a fixture). | -| `loop.py` | `Loop.compile`: refuses a map without a current owner approval (`map_unapproved`), a spec the ledger did not promote (`spec_unpromoted`, see `promotion_record`), or a map with findings; writes one contract per feature; logs `map_frozen` (with `promoted_by`) and `ticket_opened{source: map}`. `Loop.run`: kill switch, eligibility, three policy questions recorded as proposals, envelope reservation, one unattended Build Thread, one proposer call through `CommandProvider`, then `syberlabs run`'s `Runner` drives the thread (D17), the envelope settles from the journal, the outcome is recorded; a `Rejected` while running still writes the envelope's `stop` and the ledger's `loop_stopped{reason: }` before it propagates. `promotion_record`: the goal gate's record on the ledger for exactly this spec (the `spec_changed` promote whose `spec_digest` is the file's, the `approval_recorded` it cites, the envelope under `approvals/`), re-verified under the owner's public key when one is given. `EnvelopeLedger`: the eval spend ledger's shape generalized to attempts (D13), one file per envelope digest under `envelopes/`, strict on every line. `why`: ticket -> feature -> map (approval) -> spec (promotion), from the ledger. `event_digests`: one digest per autonomy event without its volatile `refs`. | -| `autonomy_cli.py` | `syberlabs factory autonomy check | approve | envelope | run | why`, registered from one hook line at the end of `factory/cli.py`. `run --owner-public KEY` re-verifies the promotion's approval under the owner's key. | +| `loop.py` | `Loop.compile`: refuses a map without a current owner approval (`map_unapproved`), a spec the ledger did not promote (`spec_unpromoted`, see `promotion_record`), or a map with findings; writes one contract per feature; logs `map_frozen` (with `promoted_by`) and `ticket_opened{source: map}`. `Loop.run`: kill switch, eligibility, three policy questions recorded as proposals, envelope reservation, one unattended Build Thread, one proposer call through `CommandProvider`, then `syberlabs run`'s `Runner` drives the thread (D17), the envelope settles from the journal, the outcome is recorded; a `Rejected` while running still writes the envelope's `stop` and the ledger's `loop_stopped{reason: }` before it propagates. `promotion_record`: the goal gate's record on the ledger for exactly this spec (the `spec_changed` promote whose `spec_digest` is the file's, the `approval_recorded` it cites, the envelope under `approvals/`), re-verified under the owner key the ledger pinned at that point (`owner_key_set`); `owner_key_unset` and `owner_key_mismatch` refuse. `EnvelopeLedger`: the eval spend ledger's shape generalized to attempts (D13), one file per envelope digest under `envelopes/`, strict on every line. `why`: ticket -> feature -> map (approval) -> spec (promotion), from the ledger. `event_digests`: one digest per autonomy event without its volatile `refs`. | +| `autonomy_cli.py` | `syberlabs factory autonomy check | approve | envelope | run | why`, registered from one hook line at the end of `factory/cli.py`. | ### A run on the fixture @@ -62,21 +62,23 @@ envelope holds an arm ranked above the one that failed) offers only the stronger ### From a terminal ```sh +python -m syberlabs.factory --home .syberlabs/factory owner --public owner.pub # pin the owner key on the ledger (once) python -m syberlabs.factory --home .syberlabs/factory spec validate spec.json # the spec, as in FACTORY.md python -m syberlabs.factory --home .syberlabs/factory approve spec.json --verdict VERDICT --actor human:mateo \ --seed-env SYBERLABS_FACTORY_OWNER_SEED --out approval.json # the goal gate (C1): the owner signs python -m syberlabs.factory --home .syberlabs/factory spec promote spec.json --verdict VERDICT --actor human:mateo \ - --approval approval.json --owner-public owner.pub # verified, recorded, cited on the ledger + --approval approval.json # verified under the pinned key, recorded, cited python -m syberlabs.factory autonomy check --map map.json --spec spec.json # findings, graph, risk plan; exit 1 on findings python -m syberlabs.factory autonomy approve --map map.json --by mateo # the owner's act; any edit leaves it stale python -m syberlabs.factory autonomy envelope --map map.json --calls 6 --attempts 2 --out envelope.json python -m syberlabs.factory --home .syberlabs/factory autonomy run --map map.json --spec spec.json --envelope envelope.json \ - --owner mateo --owner-public owner.pub --proposer "/abs/python standin.py ." --check "tests=/abs/python -m unittest -q" \ + --owner mateo --proposer "/abs/python standin.py ." --check "tests=/abs/python -m unittest -q" \ --hidden "hidden.f1.marker=/abs/python -c ..." # exit 0 when a feature is ready python -m syberlabs.factory --home .syberlabs/factory autonomy why TICKET ``` -`run` reads the spec's promotion from the same `--home` the promote wrote to. An envelope is one grant: its +`run` reads the spec's promotion from the same `--home` the promote wrote to and re-verifies its approval under the +owner key that ledger pins; no key is passed on the command line. An envelope is one grant: its ledger lives at `envelopes/.jsonl`, a second map or a new envelope in the same home starts clean, and a run over an envelope whose ledger already carries a `stop` is refused (`envelope_stopped`). On Windows, `--check` and `--hidden` commands with nested quotes need a script file (`split_command` is non-POSIX @@ -153,7 +155,7 @@ there; pre-existing in #154). - **The map approval is a record, not a credential.** `featuremap.approve` writes `{digest, actor}` and `approved()` checks the digest against the map, not the actor against a signature: swapping `approval.actor.id` leaves the map approved. The spec's promotion is now bound to the owner's signed approval through C1's seam - (`promotion_record`, re-verified with `--owner-public`); the map's approval has no such seam yet. Binding it is a + (`promotion_record`, re-verified under the pinned owner key); the map's approval has no such seam yet. Binding it is a signed `approval_payload` over the map digest, which is C1's shape applied to a second artifact; proposed for the packet that gives the factory a kernel case to hang approvals on. - **The floor is listed, not enforced, by this slice.** `FLOOR` names host checks, hidden checks, critic and safety diff --git a/syberlabs/factory/autonomy_cli.py b/syberlabs/factory/autonomy_cli.py index afcc018..0d544fe 100644 --- a/syberlabs/factory/autonomy_cli.py +++ b/syberlabs/factory/autonomy_cli.py @@ -18,7 +18,6 @@ import sys from pathlib import Path -from syberlabs import certificate from syberlabs.errors import Rejected from syberlabs.factory import featuremap, loop from syberlabs.factory import policy as policymod @@ -69,7 +68,8 @@ def add_commands(steps) -> None: env.add_argument("--out", required=True) runp = sub.add_parser("run", help="compile the approved map to tickets and drive each feature through a Build Thread") runp.add_argument("--map", required=True) - runp.add_argument("--spec", required=True) + runp.add_argument("--spec", required=True, help="the promoted spec JSON; its promotion is read from --home and re-verified under " + "the owner key the ledger pins (factory owner)") runp.add_argument("--envelope", required=True) runp.add_argument("--owner", required=True, help="the accountable human on every ticket") runp.add_argument("--kit-home", default=".syberlabs", help="the Build Thread home under --root (default .syberlabs)") @@ -80,8 +80,6 @@ def add_commands(steps) -> None: runp.add_argument("--baseline", help="the golden run id to name on tickets") runp.add_argument("--max-steps", type=int, default=50) runp.add_argument("--shadow", help="recorded answers JSON for a shadow policy; recorded beside each decision, never acted on") - runp.add_argument("--owner-public", metavar="KEY", help="the owner's .pub file: re-verify the spec's promotion approval under it " - "(without it the ledger's hash-chained record and stored envelope are checked)") why = sub.add_parser("why", help="walk a ticket back to its feature, map, approval, spec and its promotion") why.add_argument("ticket") @@ -149,11 +147,10 @@ def _run(args) -> int: raise Rejected("check_argument", "name at least one visible check with --check NAME=COMMAND") root = Path(args.root).resolve() kit_home = Path(args.kit_home) - owner_public = certificate.read_public(args.owner_public) if args.owner_public else None driver = loop.Loop(repo_root=root, kit_home=kit_home if kit_home.is_absolute() else root / kit_home, ledger=ledgermod.Ledger(args.home), map=document, spec=spec, envelope=envelope, policy=policy, proposer_argv=split_command(args.proposer), checks=checks, hidden_catalogue=_parse_checks(args.hidden, "--hidden"), - human_owner=args.owner, baseline_run=args.baseline, log=print, owner_public=owner_public) + human_owner=args.owner, baseline_run=args.baseline, log=print) tickets = driver.compile() for ticket in tickets: print(f"ticket {ticket['ticket_id']} {ticket['map_ref']['feature_id']} {ticket['title']}") diff --git a/syberlabs/factory/loop.py b/syberlabs/factory/loop.py index 8942392..d320c70 100644 --- a/syberlabs/factory/loop.py +++ b/syberlabs/factory/loop.py @@ -37,8 +37,10 @@ The spec is promoted when the ledger says so, not when the file says so: ``promotion_record`` finds the ``spec_changed`` that promoted exactly this spec (its digest), the ``approval_recorded`` it cites and the -owner's envelope under ``approvals/``, and with the owner's public key re-verifies the signature (the goal -gate's ``verify_approval``). ``compile`` refuses a spec the ledger did not promote (``spec_unpromoted``). +owner's envelope under ``approvals/``, and re-verifies the signature under the owner key the ledger pinned +(``owner_key_set``; the goal gate's ``verify_approval``). ``compile`` refuses a spec the ledger did not +promote (``spec_unpromoted``), a ledger without a pinned key (``owner_key_unset``) and an approval under +another key (``owner_key_mismatch``). """ from __future__ import annotations @@ -272,16 +274,17 @@ def event_digests(ledger, map_digest: str | None = None) -> list[str]: for e in autonomy_events(ledger, map_digest)] -def promotion_record(ledger, spec: dict, owner_public: bytes | None = None) -> dict: +def promotion_record(ledger, spec: dict) -> dict: """The ledger's record that the owner promoted exactly this spec, through the goal gate's own shape. The spec on disk must be the spec the ledger wrote after a ``promote`` (or a later ``canonize``): the ``spec_changed`` whose ``spec_digest`` is this file's digest, with ``to`` promoted or canonical. The promotion's ``approval`` must cite an ``approval_recorded`` event (by hash) for this spec and version by a - human approver, whose envelope is under ``approvals/`` at the recorded digest. With ``owner_public`` the - envelope is re-verified (``spec.verify_approval`` over the digest the owner signed), so the record becomes - a credential; without it the hash-chained ledger and the stored envelope are what is checked. The file's - ``state`` string decides nothing here.""" + human approver, whose envelope is under ``approvals/`` at the recorded digest and was signed under the owner + key the ledger pinned at that point (``owner_key_set``, read with ``spec.pinned_owner_key``; a later + rotation does not unmake an earlier approval). The envelope is re-verified under that key + (``spec.verify_approval`` over the digest the owner signed), so the record is a credential, not a string. + The file's ``state`` string decides nothing here.""" events = ledger.events() changes = [e for e in events if e["kind"] == "spec_changed" and e["body"].get("spec_id") == spec.get("spec_id")] current = specmod.spec_digest(spec) @@ -314,12 +317,17 @@ def promotion_record(ledger, spec: dict, owner_public: bytes | None = None) -> d raise Rejected("spec_unpromoted", f"the approval envelope {body['approval_digest'][:12]} is missing or unreadable: {type(exc).__name__}") from None if digest(envelope) != body["approval_digest"]: raise Rejected("spec_unpromoted", f"approvals/{body['approval_digest'][:12]} does not match its recorded digest") - if owner_public is not None: - specmod.verify_approval(envelope, owner_public, spec, "promote", verdict_ids=list(body.get("verdict_ids") or []), - spec_digest_value=body.get("spec_digest")) - return {"seq": promotion["seq"], "approval_seq": recorded["seq"], "approver": dict(approver), "keyid": body.get("keyid"), + pinned = specmod.pinned_owner_key([e for e in events if e["seq"] < recorded["seq"]]) + if pinned is None: + raise Rejected("owner_key_unset", f"the ledger pinned no owner key before approval event {recorded['seq']}; the approval rests on no trust root") + if body.get("keyid") != pinned: + raise Rejected("owner_key_mismatch", f"approval event {recorded['seq']} is under key {str(body.get('keyid'))[:10]}, not the owner key " + f"the ledger pinned then ({pinned[:10]})") + specmod.verify_approval(envelope, bytes.fromhex(pinned), spec, "promote", verdict_ids=list(body.get("verdict_ids") or []), + spec_digest_value=body.get("spec_digest")) + return {"seq": promotion["seq"], "approval_seq": recorded["seq"], "approver": dict(approver), "keyid": pinned, "verdict_ids": list(body.get("verdict_ids") or []), "approval_digest": body["approval_digest"], - "signed_digest": body.get("spec_digest"), "verified": owner_public is not None} + "signed_digest": body.get("spec_digest")} def why(ledger, ticket_id: str) -> dict: @@ -374,13 +382,11 @@ def feature_contract(ticket: dict, *, checks: dict, hidden_catalogue: dict, max_ class Loop: def __init__(self, *, repo_root: str | Path, kit_home: str | Path, ledger, map: dict, spec: dict, envelope: dict, policy, proposer_argv: list[str], checks: dict, hidden_catalogue: dict | None = None, human_owner: str, - baseline_run: str | None = None, actor: str = "factory@syberlabs.host", log=None, max_passes: int = MAX_PASSES, - owner_public: bytes | None = None): + baseline_run: str | None = None, actor: str = "factory@syberlabs.host", log=None, max_passes: int = MAX_PASSES): self.repo_root, self.kit_home, self.ledger = Path(repo_root), Path(kit_home), ledger self.map, self.spec, self.envelope, self.policy = map, spec, envelope, policy self.proposer_argv, self.checks, self.hidden = list(proposer_argv), dict(checks), dict(hidden_catalogue or {}) self.human_owner, self.baseline_run, self.actor = human_owner, baseline_run, actor - self.owner_public = owner_public self.log = log or (lambda line: None) self.max_passes = max_passes self.map_digest = featuremap.map_digest(map) @@ -408,7 +414,7 @@ def compile(self) -> list[dict]: raise Rejected("map_unapproved", "the loop runs only an owner-approved map whose approval covers its current digest") if self.spec.get("state") not in ("promoted", "canonical"): raise Rejected("spec_state", f"work opens under a promoted spec, not one in state {self.spec.get('state')!r}") - self.promotion = promotion_record(self.ledger, self.spec, self.owner_public) + self.promotion = promotion_record(self.ledger, self.spec) findings = featuremap.mapcheck(self.map, self.spec) if findings: raise Rejected("map_invalid", "; ".join(findings)) @@ -431,7 +437,7 @@ def compile(self) -> list[dict]: record(self.ledger, "map_frozen", self.map_digest, { "map_id": self.map["id"], "spec_id": self.spec["spec_id"], "spec_version": self.spec["version"], "spec_digest": self.map["spec_ref"]["spec_digest"], "approved_by": self.map["approval"]["actor"], - "promoted_by": self.promotion["approver"], "promotion_verified": self.promotion["verified"], + "promoted_by": self.promotion["approver"], "envelope_digest": envelope_digest(self.envelope), "features": [f["id"] for f in self.map["features"]], "critical_path": self.graph["critical_path"], "critical_path_length": self.graph["critical_path_length"], "width": self.graph["width"], "work_critical_ratio": self.graph["work_critical_ratio"], diff --git a/tests/test_factory_autonomy.py b/tests/test_factory_autonomy.py index e037594..a5fe10e 100644 --- a/tests/test_factory_autonomy.py +++ b/tests/test_factory_autonomy.py @@ -44,11 +44,14 @@ def candidate_spec(project: Path) -> dict: def promoted_spec(project: Path, home: ledger.Ledger, *, seed: bytes = OWNER_SEED, public: bytes = OWNER_PUBLIC) -> dict: - """The candidate promoted the way `factory spec promote` does it (C1's goal gate): a model's variant, an - independent reviewer's accepting verdict and the validate that wrote the candidate are on the ledger; the - owner signs an approval over the spec's digest, `gate` resolves the verdict and verifies the approval, - `transition` promotes, the approval is recorded and the `spec_changed` cites it.""" + """The candidate promoted the way `factory spec promote` does it (C1's goal gate): the ledger pins the owner + key (bootstrap, once); a model's variant, an independent reviewer's accepting verdict and the validate that + wrote the candidate are on the ledger; the owner signs an approval over the spec's digest, `gate` resolves the + verdict and verifies the approval under the pinned key, `transition` promotes, the approval is recorded and + the `spec_changed` cites it.""" document = candidate_spec(project) + if home.owner_key() is None: + home.set_owner_key(public) before = specmod.spec_digest(document) reviewer = {"kind": "model", "id": "gpt", "model": "gpt-5", "family": "openai"} home.append("spec_changed", {"spec_id": document["spec_id"], "version": document["version"], "operation": "mutate", @@ -58,8 +61,7 @@ def promoted_spec(project: Path, home: ledger.Ledger, *, seed: bytes = OWNER_SEE home.append("spec_changed", {"spec_id": document["spec_id"], "version": document["version"], "operation": "validate", "accepted_variant": "var1", "verdict_id": VERDICT, "spec_digest": before}) envelope = specmod.sign_approval(specmod.approval_payload(document, "promote", OWNER, verdict_ids=[VERDICT]), seed) - approval, resolved = specmod.gate(document, "promote", OWNER, home.events(), envelope, public, verdict_ids=[VERDICT], - spec_digest_value=before) + approval, resolved = specmod.gate(document, "promote", OWNER, home.events(), envelope, verdict_ids=[VERDICT], spec_digest_value=before) record = specmod.transition(document, "promote", OWNER, verdict_ids=[VERDICT], approval=approval, spec_digest=before, resolved_verdicts=resolved) event = home.record_approval(envelope, approval) @@ -105,14 +107,14 @@ def home(self, name="ledger") -> ledger.Ledger: return ledger.Ledger(self.scratch / name) def make_loop(self, project: Path, mapping: dict, document: dict, home: ledger.Ledger, *, calls_total=10, attempts=2, mode="", - policy=None, kill_switch=None, arms=None, owner_public=None) -> loop.Loop: + policy=None, kill_switch=None, arms=None) -> loop.Loop: envelope = loop.new_envelope(featuremap.map_digest(mapping), dollars_total=0.0, calls_total=calls_total, seconds_total=600, attempts_per_feature=attempts, kill_switch=kill_switch, arms=arms) argv = [sys.executable, str(AUTONOMY / "standin_proposer.py"), str(project)] + ([mode] if mode else []) checks = {"tests": {"argv": [sys.executable, "-c", "import fxapp.main, fxapp.variants"], "timeout_seconds": 60}} return loop.Loop(repo_root=project, kit_home=project / ".syberlabs", ledger=home, map=mapping, spec=document, envelope=envelope, policy=policy or policymod.OfflinePolicy(), proposer_argv=argv, checks=checks, hidden_catalogue=hidden_catalogue(), - human_owner="tester", owner_public=owner_public) + human_owner="tester") def ready_loop(self, name="project", ledger_name="ledger", **overrides) -> tuple[loop.Loop, Path, str, dict]: """A project, a promoted spec on a fresh ledger and an approved fixture map: the loop ready to compile.""" @@ -408,10 +410,10 @@ def test_the_thin_slice_builds_three_features_to_ready_for_owner_merge(self): featuremap.approve(mapping, OWNER) recorded = policymod.recorded_answers({"next_feature": "F3", "budget_tier": "S", "proposer_arm": "standin"}) shadow = policymod.ShadowPolicy(policymod.OfflinePolicy(), recorded, shadow_name="recorded-jev") - run = self.make_loop(project, mapping, document, home, policy=shadow, owner_public=OWNER_PUBLIC) + run = self.make_loop(project, mapping, document, home, policy=shadow) tickets = run.compile() self.assertEqual([t["map_ref"]["feature_id"] for t in tickets], ["F1", "F2", "F3"]) - self.assertTrue(run.promotion["verified"], "the owner's approval was re-verified under the owner's key") + self.assertEqual(run.promotion["keyid"], OWNER_PUBLIC.hex(), "the approval was re-verified under the key the ledger pins") opened = [e for e in home.events() if e["kind"] == "ticket_opened"] self.assertEqual([(e["body"]["feature_id"], e["body"]["source"], e["body"]["human_owner"]) for e in opened], [("F1", "map", "tester"), ("F2", "map", "tester"), ("F3", "map", "tester")]) @@ -484,7 +486,7 @@ def test_same_fixture_gives_the_same_event_digests(self): def test_compile_needs_the_ledgers_promotion_record_not_the_files_state(self): """The file's ``state`` decides nothing: the ledger must hold a promote of exactly this spec, citing a - recorded approval by a human, whose envelope is stored; with the owner's key it must verify.""" + recorded approval by a human, whose envelope is stored and verifies under the owner key the ledger pinned.""" project, base = self.project() home = self.home() in_memory = candidate_spec(project) @@ -511,24 +513,40 @@ def test_compile_needs_the_ledgers_promotion_record_not_the_files_state(self): mapping = fixture_map(document, base) featuremap.approve(mapping, OWNER) - with self.assertRaises(Rejected) as refused: - self.make_loop(project, mapping, document, home, owner_public=generate()[1]).compile() - self.assertEqual(refused.exception.code, "approval_unverified", "another owner's key: the stored approval is no approval") + # A promotion whose approval was signed under a key the ledger never pinned, or on a ledger that pins no + # key, is a record without a trust root: refused whatever the file and the events say. + other_seed, other_public = generate() + for name, pin, code in (("unpinned", False, "owner_key_unset"), ("other-key", True, "owner_key_mismatch")): + forged_home = self.home(name) + if pin: + forged_home.set_owner_key(OWNER_PUBLIC) + forged = candidate_spec(project) + envelope = specmod.sign_approval(specmod.approval_payload(forged, "promote", OWNER, verdict_ids=[VERDICT]), other_seed) + approval = specmod.verify_approval(envelope, other_public, forged, "promote", verdict_ids=[VERDICT]) + record = specmod.transition(forged, "promote", OWNER, verdict_ids=[VERDICT], approval=approval) + event = forged_home.record_approval(envelope, approval) + record["approval"] = {**record["approval"], "event_hash": event["hash"], "approval_digest": event["body"]["approval_digest"]} + forged_home.append("spec_changed", {"spec_id": forged["spec_id"], "version": forged["version"], **record, + "spec_digest": specmod.spec_digest(forged), "footprint": forged["footprint"]["components"]}) + self.assertEqual(specmod.spec_digest(forged), specmod.spec_digest(document), "the same spec, differently approved") + with self.assertRaises(Rejected, msg=name) as refused: + self.make_loop(project, mapping, forged, forged_home).compile() + self.assertEqual(refused.exception.code, code, name) approvals = next(p for p in (home.home / "approvals").glob("*.json")) kept = approvals.read_text(encoding="utf-8") approvals.write_text(kept.replace('"', "'", 1), encoding="utf-8") with self.assertRaises(Rejected) as refused: self.make_loop(project, mapping, document, home).compile() - self.assertEqual(refused.exception.code, "spec_unpromoted", "a damaged approval envelope refuses even without a key") + self.assertEqual(refused.exception.code, "spec_unpromoted", "a damaged approval envelope refuses") approvals.write_text(kept, encoding="utf-8") - run = self.make_loop(project, mapping, document, home, owner_public=OWNER_PUBLIC) + run = self.make_loop(project, mapping, document, home) run.compile() self.assertEqual(run.promotion["approver"], OWNER) self.assertEqual(run.promotion["verdict_ids"], [VERDICT]) - self.assertTrue(run.promotion["verified"]) - self.assertEqual(loop.promotion_record(home, document)["verified"], False, "without a key the record is checked, not the signature") + self.assertEqual(run.promotion["keyid"], OWNER_PUBLIC.hex()) + self.assertEqual(loop.promotion_record(home, document)["seq"], run.promotion["seq"]) def test_a_map_without_owner_approval_is_refused(self): project, base = self.project() From ced03971ce63675d027493422e7cfa2e421b81ef Mon Sep 17 00:00:00 2001 From: sykosyber Date: Mon, 2 Nov 2026 03:10:39 -0800 Subject: [PATCH 7/8] Autonomy on the goal gate's owner-key lineage (goal gate 9ff7573, M3): promotion_record reads the pinned key through the ledger's verified lineage with its stored rotations, a lineage that does not verify refuses owner_key_lineage, the fixture gates with the ledger's loader, and the docs say map compilation honours the lineage Rebased onto syberlabs/factory-goal-gate at 9ff7573 (M3 of the #164 delta verification). The two branches touch disjoint files except the end-of-file hook in factory/cli.py; no conflicts. The adaptation #164's summary asked for: `loop.promotion_record` now calls `specmod.pinned_owner_key(prefix, ledger.load_rotation)` so a rotated ledger's envelopes can be checked, and `owner_key_lineage` propagates as the refusal instead of collapsing into `owner_key_unset`. The historical-prefix read (events with seq below the approval event's) still picks the key pinned at the time of the approval, so a later honest rotation does not unmake an earlier promotion. Because that prefix cannot see a pin appended after the approval, the whole ledger's lineage is verified first (`specmod.pinned_owner_key(events, ledger.load_rotation)`): a bare second `owner_key_set` appended with the hash chain intact leaves the ledger pinning nothing, and `Loop.compile` refuses `owner_key_lineage` rather than reading the earlier key. Tests (26, was 25): `EndToEnd::test_compile_reads_the_owner_key_through_the_ledgers_lineage` promotes a spec after an honest bootstrap -> rotation (approval signed by the second key) and compiles under the second key, shows the same lineage is unreadable without the loader, then appends the M3 repro (a bare `owner_key_set`) after an honest promotion on a second ledger: `compile` refuses `owner_key_lineage`, appends nothing, writes no contract. The fixture's `promoted_spec` passes `load_rotation=home.load_rotation` to `gate`, as the CLI does. Docs: FACTORY_AUTONOMY.md states that map compilation honours the ledger's owner-key lineage. Co-Authored-By: Claude Fable 5.1 --- docs/FACTORY_AUTONOMY.md | 9 ++++-- syberlabs/factory/loop.py | 16 +++++++---- tests/test_factory_autonomy.py | 50 ++++++++++++++++++++++++++++++++-- 3 files changed, 65 insertions(+), 10 deletions(-) diff --git a/docs/FACTORY_AUTONOMY.md b/docs/FACTORY_AUTONOMY.md index bb5f048..5e0a8d3 100644 --- a/docs/FACTORY_AUTONOMY.md +++ b/docs/FACTORY_AUTONOMY.md @@ -25,7 +25,7 @@ spec (promoted) ─► FeatureMap (typed DAG) ─► mapcheck ─► owner | --- | --- | | `featuremap.py` | `feature-map.v1`: features with id, objective, `req_ids` (the spec requirements they trace to), scope paths, shown criteria, hidden-check names (names only), `depends_on`, act class, size, risk inputs. `spec_from_markdown` turns a sectioned Markdown spec (`## R1: text`, `- given, when, then` bullets) into #154's spec object (owner decision 11, D2). `mapcheck` is the deterministic floor: schema, spec digest, coverage, acyclic DAG, scope conflicts (an intersection must be declared with an order that agrees with the DAG), act class, size ceilings, hidden-check names, approval digest. `taskgraph`: critical path, total work, work/critical ratio, Dilworth width with a maximum antichain, conflict graph. `risk_plan`: seven risk inputs computed by code, `r_i` as a weighted sum, standardized `z_i`, `v_i = V * softmax(z_i / tau)` as integer units above a floor that is listed beside every allocation and never moves. `compile_ticket`: one feature to one ticket in `ticket_from_spec`'s shape (D5). `degenerate_map`: the map `ticket_from_spec` implies, one feature per requirement. | | `policy.py` | `Question` (closed options built by code; the state a policy reads is ids and numbers only), `Answer`, `validate` (an answer outside the options is `policy_invalid`), `OfflinePolicy` (critical path first, cheapest arm and tier, retry then stronger arm then owner, park when the cap is spent, stop on the envelope), `ShadowPolicy` (acts on one policy, records what an injected second one would have answered and whether it agrees; an invalid or failing shadow is recorded and changes nothing), `recorded_answers` (a shadow over a fixture). | -| `loop.py` | `Loop.compile`: refuses a map without a current owner approval (`map_unapproved`), a spec the ledger did not promote (`spec_unpromoted`, see `promotion_record`), or a map with findings; writes one contract per feature; logs `map_frozen` (with `promoted_by`) and `ticket_opened{source: map}`. `Loop.run`: kill switch, eligibility, three policy questions recorded as proposals, envelope reservation, one unattended Build Thread, one proposer call through `CommandProvider`, then `syberlabs run`'s `Runner` drives the thread (D17), the envelope settles from the journal, the outcome is recorded; a `Rejected` while running still writes the envelope's `stop` and the ledger's `loop_stopped{reason: }` before it propagates. `promotion_record`: the goal gate's record on the ledger for exactly this spec (the `spec_changed` promote whose `spec_digest` is the file's, the `approval_recorded` it cites, the envelope under `approvals/`), re-verified under the owner key the ledger pinned at that point (`owner_key_set`); `owner_key_unset` and `owner_key_mismatch` refuse. `EnvelopeLedger`: the eval spend ledger's shape generalized to attempts (D13), one file per envelope digest under `envelopes/`, strict on every line. `why`: ticket -> feature -> map (approval) -> spec (promotion), from the ledger. `event_digests`: one digest per autonomy event without its volatile `refs`. | +| `loop.py` | `Loop.compile`: refuses a map without a current owner approval (`map_unapproved`), a spec the ledger did not promote (`spec_unpromoted`, see `promotion_record`), or a map with findings; writes one contract per feature; logs `map_frozen` (with `promoted_by`) and `ticket_opened{source: map}`. `Loop.run`: kill switch, eligibility, three policy questions recorded as proposals, envelope reservation, one unattended Build Thread, one proposer call through `CommandProvider`, then `syberlabs run`'s `Runner` drives the thread (D17), the envelope settles from the journal, the outcome is recorded; a `Rejected` while running still writes the envelope's `stop` and the ledger's `loop_stopped{reason: }` before it propagates. `promotion_record`: the goal gate's record on the ledger for exactly this spec (the `spec_changed` promote whose `spec_digest` is the file's, the `approval_recorded` it cites, the envelope under `approvals/`), re-verified under the owner key the ledger pinned at that point (`owner_key_set`, read through the ledger's verified owner-key lineage with its stored rotations, `Ledger.load_rotation`); a lineage that does not verify (a bare second pin, an unsigned or stale rotation, a malformed key) pins nothing and refuses `owner_key_lineage`; `owner_key_unset` and `owner_key_mismatch` refuse. `EnvelopeLedger`: the eval spend ledger's shape generalized to attempts (D13), one file per envelope digest under `envelopes/`, strict on every line. `why`: ticket -> feature -> map (approval) -> spec (promotion), from the ledger. `event_digests`: one digest per autonomy event without its volatile `refs`. | | `autonomy_cli.py` | `syberlabs factory autonomy check | approve | envelope | run | why`, registered from one hook line at the end of `factory/cli.py`. | ### A run on the fixture @@ -78,7 +78,10 @@ python -m syberlabs.factory --home .syberlabs/factory autonomy why TICKET ``` `run` reads the spec's promotion from the same `--home` the promote wrote to and re-verifies its approval under the -owner key that ledger pins; no key is passed on the command line. An envelope is one grant: its +owner key that ledger pins; no key is passed on the command line. Map compilation honours the ledger's owner-key +lineage (FACTORY.md): the key is the one the verified chain of `owner_key_set` events pinned before the approval, +each rotation checked against its stored envelope, and a ledger whose lineage does not verify compiles nothing +(`owner_key_lineage`), whatever its newest `owner_key_set` says. An envelope is one grant: its ledger lives at `envelopes/.jsonl`, a second map or a new envelope in the same home starts clean, and a run over an envelope whose ledger already carries a `stop` is refused (`envelope_stopped`). On Windows, `--check` and `--hidden` commands with nested quotes need a script file (`split_command` is non-POSIX @@ -155,7 +158,7 @@ there; pre-existing in #154). - **The map approval is a record, not a credential.** `featuremap.approve` writes `{digest, actor}` and `approved()` checks the digest against the map, not the actor against a signature: swapping `approval.actor.id` leaves the map approved. The spec's promotion is now bound to the owner's signed approval through C1's seam - (`promotion_record`, re-verified under the pinned owner key); the map's approval has no such seam yet. Binding it is a + (`promotion_record`, re-verified under the owner key the ledger's verified lineage pins); the map's approval has no such seam yet. Binding it is a signed `approval_payload` over the map digest, which is C1's shape applied to a second artifact; proposed for the packet that gives the factory a kernel case to hang approvals on. - **The floor is listed, not enforced, by this slice.** `FLOOR` names host checks, hidden checks, critic and safety diff --git a/syberlabs/factory/loop.py b/syberlabs/factory/loop.py index d320c70..b94379f 100644 --- a/syberlabs/factory/loop.py +++ b/syberlabs/factory/loop.py @@ -38,8 +38,10 @@ The spec is promoted when the ledger says so, not when the file says so: ``promotion_record`` finds the ``spec_changed`` that promoted exactly this spec (its digest), the ``approval_recorded`` it cites and the owner's envelope under ``approvals/``, and re-verifies the signature under the owner key the ledger pinned -(``owner_key_set``; the goal gate's ``verify_approval``). ``compile`` refuses a spec the ledger did not -promote (``spec_unpromoted``), a ledger without a pinned key (``owner_key_unset``) and an approval under +(``owner_key_set``, read through the ledger's verified lineage with its stored rotations; the goal gate's +``verify_approval``). ``compile`` refuses a spec the ledger did not promote (``spec_unpromoted``), a ledger +whose owner-key lineage does not verify (``owner_key_lineage``: a bare second pin, an unsigned or stale +rotation, a malformed key), a ledger without a pinned key (``owner_key_unset``) and an approval under another key (``owner_key_mismatch``). """ @@ -281,8 +283,11 @@ def promotion_record(ledger, spec: dict) -> dict: ``spec_changed`` whose ``spec_digest`` is this file's digest, with ``to`` promoted or canonical. The promotion's ``approval`` must cite an ``approval_recorded`` event (by hash) for this spec and version by a human approver, whose envelope is under ``approvals/`` at the recorded digest and was signed under the owner - key the ledger pinned at that point (``owner_key_set``, read with ``spec.pinned_owner_key``; a later - rotation does not unmake an earlier approval). The envelope is re-verified under that key + key the ledger pinned at that point (``owner_key_set``, read with ``spec.pinned_owner_key`` through the + ledger's verified lineage, its stored rotations supplied by ``ledger.load_rotation``; a later rotation does + not unmake an earlier approval). The whole ledger's lineage must verify first: a pin appended after the + approval that is not a signed rotation leaves the ledger pinning nothing (``owner_key_lineage`` refuses, + never ``owner_key_unset`` and never an earlier key). The envelope is re-verified under that key (``spec.verify_approval`` over the digest the owner signed), so the record is a credential, not a string. The file's ``state`` string decides nothing here.""" events = ledger.events() @@ -317,7 +322,8 @@ def promotion_record(ledger, spec: dict) -> dict: raise Rejected("spec_unpromoted", f"the approval envelope {body['approval_digest'][:12]} is missing or unreadable: {type(exc).__name__}") from None if digest(envelope) != body["approval_digest"]: raise Rejected("spec_unpromoted", f"approvals/{body['approval_digest'][:12]} does not match its recorded digest") - pinned = specmod.pinned_owner_key([e for e in events if e["seq"] < recorded["seq"]]) + specmod.pinned_owner_key(events, ledger.load_rotation) # the whole lineage verifies, or the ledger pins nothing + pinned = specmod.pinned_owner_key([e for e in events if e["seq"] < recorded["seq"]], ledger.load_rotation) if pinned is None: raise Rejected("owner_key_unset", f"the ledger pinned no owner key before approval event {recorded['seq']}; the approval rests on no trust root") if body.get("keyid") != pinned: diff --git a/tests/test_factory_autonomy.py b/tests/test_factory_autonomy.py index a5fe10e..da71cc2 100644 --- a/tests/test_factory_autonomy.py +++ b/tests/test_factory_autonomy.py @@ -47,7 +47,8 @@ def promoted_spec(project: Path, home: ledger.Ledger, *, seed: bytes = OWNER_SEE """The candidate promoted the way `factory spec promote` does it (C1's goal gate): the ledger pins the owner key (bootstrap, once); a model's variant, an independent reviewer's accepting verdict and the validate that wrote the candidate are on the ledger; the owner signs an approval over the spec's digest, `gate` resolves the - verdict and verifies the approval under the pinned key, `transition` promotes, the approval is recorded and + verdict and verifies the approval under the pinned key (read through the lineage with the ledger's stored + rotations), `transition` promotes, the approval is recorded and the `spec_changed` cites it.""" document = candidate_spec(project) if home.owner_key() is None: @@ -61,7 +62,8 @@ def promoted_spec(project: Path, home: ledger.Ledger, *, seed: bytes = OWNER_SEE home.append("spec_changed", {"spec_id": document["spec_id"], "version": document["version"], "operation": "validate", "accepted_variant": "var1", "verdict_id": VERDICT, "spec_digest": before}) envelope = specmod.sign_approval(specmod.approval_payload(document, "promote", OWNER, verdict_ids=[VERDICT]), seed) - approval, resolved = specmod.gate(document, "promote", OWNER, home.events(), envelope, verdict_ids=[VERDICT], spec_digest_value=before) + approval, resolved = specmod.gate(document, "promote", OWNER, home.events(), envelope, verdict_ids=[VERDICT], spec_digest_value=before, + load_rotation=home.load_rotation) record = specmod.transition(document, "promote", OWNER, verdict_ids=[VERDICT], approval=approval, spec_digest=before, resolved_verdicts=resolved) event = home.record_approval(envelope, approval) @@ -548,6 +550,50 @@ def test_compile_needs_the_ledgers_promotion_record_not_the_files_state(self): self.assertEqual(run.promotion["keyid"], OWNER_PUBLIC.hex()) self.assertEqual(loop.promotion_record(home, document)["seq"], run.promotion["seq"]) + def test_compile_reads_the_owner_key_through_the_ledgers_lineage(self): + """M3 of the #164 verification, on the autonomy side: the owner key is the ledger's verified lineage, read + with the ledger's stored rotations. A spec promoted after an honest rotation (bootstrap -> rotation signed + by the first key, the approval signed by the second) compiles under the second key; that lineage cannot be + read without the loader. A bare second ``owner_key_set`` appended through the public ``append`` after the + promotion (the hash chain intact) leaves the ledger pinning nothing: ``compile`` refuses + ``owner_key_lineage``, not ``owner_key_unset`` and not the earlier key, and writes nothing.""" + project, base = self.project() + home = self.home() + second_seed, second_public = generate() + home.set_owner_key(OWNER_PUBLIC) + home.set_owner_key(second_public, seed=OWNER_SEED) + self.assertEqual(home.owner_key(), second_public.hex()) + document = promoted_spec(project, home, seed=second_seed, public=second_public) + with self.assertRaises(Rejected) as refused: + specmod.pinned_owner_key(home.events()) + self.assertEqual(refused.exception.code, "owner_key_lineage", "a rotated ledger is unreadable without the loader") + mapping = fixture_map(document, base) + featuremap.approve(mapping, OWNER) + run = self.make_loop(project, mapping, document, home) + run.compile() + self.assertEqual(run.promotion["keyid"], second_public.hex(), "the key pinned before the approval, through the rotation") + self.assertTrue(home.verify()) + self.assertEqual(len(notes(home.events(), "map_frozen")), 1) + + # The M3 repro: an honest bootstrap and promotion, then a bare owner_key_set appended with the chain intact. + project, base = self.project("tampered") + tampered = self.home("tampered-ledger") + document = promoted_spec(project, tampered) + _, attacker_public = generate() + tampered.append("owner_key_set", {"keyid": attacker_public.hex(), "previous": None, "rotation_digest": None}) + self.assertTrue(ledger._verify_chain(tampered.events()), "the chain is intact; only the lineage is broken") + self.assertFalse(tampered.verify()) + mapping = fixture_map(document, base) + featuremap.approve(mapping, OWNER) + before = len(tampered.events()) + with self.assertRaises(Rejected) as refused: + self.make_loop(project, mapping, document, tampered).compile() + self.assertEqual(refused.exception.code, "owner_key_lineage") + self.assertIn("a bare pin does not re-root the ledger", refused.exception.detail) + self.assertEqual(loop.autonomy_events(tampered), [], "nothing was logged") + self.assertEqual(len(tampered.events()), before, "the ledger was not written") + self.assertFalse((project / ".syberlabs" / "contracts").exists(), "no contract was written") + def test_a_map_without_owner_approval_is_refused(self): project, base = self.project() home = self.home() From afccabc7e6c1d33d00f312b5c60505cde05a1867 Mon Sep 17 00:00:00 2001 From: sykosyber Date: Mon, 2 Nov 2026 03:14:57 -0800 Subject: [PATCH 8/8] Bind each owner-key rotation to its position on the chain and refuse a replayed envelope (M4) The rotation envelope (now owner-key/v1; v0 is refused) is signed over the seq of the owner_key_set it replaces and the ledger head at signing, the lineage walk checks both against the chain, and a rotation_digest cited twice is `rotation replayed`, so an honest A -> B handover cannot be appended again after the owner rotated B away, and an envelope signed for one position fails at any other. New CliTests case covers the replay, a moved envelope, a wrong replaces_seq and a v0 envelope end to end (verify, problems, gate, CLI); the M3 fixture signs over its position. FACTORY.md lineage rule and GAPS 65 (1)/(3) now say the remaining boundary is a consistent rewrite of the chain, not an append. Co-Authored-By: Claude Fable 5.1 --- docs/FACTORY.md | 22 +++++-- spec/GAPS.md | 2 +- syberlabs/factory/ledger.py | 23 +++++--- syberlabs/factory/spec.py | 69 ++++++++++++++++------ tests/test_factory.py | 115 +++++++++++++++++++++++++++++++++++- 5 files changed, 196 insertions(+), 35 deletions(-) diff --git a/docs/FACTORY.md b/docs/FACTORY.md index 35d8fe0..2a9be35 100644 --- a/docs/FACTORY.md +++ b/docs/FACTORY.md @@ -12,7 +12,7 @@ architecture conformance, spec-driven development, attestation, ledger storage) are in the architecture plan this slice was built from. This page is what the repository does today. Package: `syberlabs/factory/`. Standard library only. `syberlabs` still does not import `syberwork`. -Claim ceiling for this page: **implemented** and **tested** (`tests/test_factory.py`, 50 tests, and the +Claim ceiling for this page: **implemented** and **tested** (`tests/test_factory.py`, 51 tests, and the CLI run below). Nothing here is measured, deployed or externally validated. ## The v0 slice @@ -100,22 +100,32 @@ pins that. `owner_key_set` alone (`spec.owner_key_lineage`, `Ledger.owner_key_lineage`). Walking every `owner_key_set` in order: the first is the one bare bootstrap (`previous` null, no `rotation_digest`); every later one is a rotation whose `previous` is exactly the key pinned before it, whose `rotation_digest` names a stored envelope -under `approvals/`, and whose envelope verifies (`verify_rotation`) under that previous key; every keyid is a -64-hex public key. Any violation is named by `problems` as `owner_key_lineage`, `verify` is false, and the +under `approvals/` and is cited by no other `owner_key_set`, and whose envelope verifies (`verify_rotation`) +under that previous key for this very position; every keyid is a 64-hex public key. The envelope +(`syberlabs.space/factory/owner-key/v1`; a `v0` envelope, bound to nothing, is refused) is signed over +`previous`, `next`, `replaces_seq` (the `seq` of the `owner_key_set` it replaces) and `head` (the ledger head +when it was signed, which is the `previous` hash of the event it lands as), and the walk checks the last two +against the chain, so an honest handover cannot be appended a second time after the owner rotated that key +away (`rotation replayed`), and an envelope signed for one position, or signed and stored but never appended +there, fails at any other. Any violation is named by `problems` as `owner_key_lineage`, `verify` is false, and the ledger pins nothing: `spec.gate`, `factory owner` and `set_owner_key` refuse with `owner_key_lineage` rather than falling back to the last or an earlier key, so a second bare bootstrap is a violation, not a re-pin. The delta verification's four shapes (an `owner_key_set` appended through the public `append` with an attacker's key; a rotation signed by the new key instead of the pinned one; a rotation whose `previous` is a key rotated out earlier; a malformed keyid as the last event) each leave the hash chain intact and each are refused this -way, in `CliTests::test_the_owner_key_is_the_verified_lineage_not_the_newest_event`. `spec promote|canonize|retire` +way, in `CliTests::test_the_owner_key_is_the_verified_lineage_not_the_newest_event`; the replay of an honest +`A -> B` envelope after `B -> A` (the second verification's M4) and an envelope moved to another position are +refused the same way, in `CliTests::test_a_rotation_binds_to_its_position_and_a_replayed_envelope_is_refused`. +`spec promote|canonize|retire` verify the ledger before the gate reads it (`ledger_corrupt`), and `factory check` verifies it once more after the candidate's test suite ran and before anything is attested, against the head its own run record left, so a line a candidate manages to append during its suite refuses the check (`ledger_corrupt`; `BuildThreadCheck::test_a_ledger_that_changes_under_the_test_suite_refuses_the_check`). `set_owner_key` reads the pinned key and appends under one acquisition of the journal lock, so two bootstraps racing on an empty ledger cannot both land. What the lineage does not cover is an attacker who rewrites the whole chain -consistently; that is the unanchored write boundary of `spec/GAPS.md` 65 (3), and anchoring the head in -`tlog`/`witness` is the deferred fix. `Approved`, the record `transition` takes for a gated operation, is made by `verify_approval` only: +consistently from the rotation they want undone; an append, with any seed the owner ever held, buys nothing. +That is the unanchored write boundary of `spec/GAPS.md` 65 (3), and anchoring the head in `tlog`/`witness` is +the deferred fix. `Approved`, the record `transition` takes for a gated operation, is made by `verify_approval` only: its constructor demands a module-private token, and `transition` checks the token, so neither a dictionary nor an instance made around the constructor passes the gate. diff --git a/spec/GAPS.md b/spec/GAPS.md index 6585b97..24087a6 100644 --- a/spec/GAPS.md +++ b/spec/GAPS.md @@ -126,4 +126,4 @@ The schemas describe SyberWork as it behaves. They are not enforced at runtime e 63. **The GitHits pilot's example pacing and license reading rest on GitHits' documentation, not on observed traffic.** (1) The host paces `example` calls to one per 40 s per host (`syberlabs/githits_pace.py`, called by the launcher entry); GitHits' limit is per organization, so two hosts, or an operator's own `syberlabs githits example` (not paced), share the organization's budget without seeing each other's slots. (2) A loopback base URL is not paced unless `SYBERLABS_GITHITS_PACE_SECONDS` asks: a loopback proxy that forwards to GitHits would go unpaced. (3) Calls queued behind several others wait one interval each, so a Bash tool timeout shorter than the queue ends a call before it is sent, and the host then flags it `githits_unrecorded`. (4) The time file is plain text a process of the same user can rewrite; it paces cooperating processes and is no security boundary. (5) The license reading admits an example's `References`/`Sources` links by their `(SPDX)` and passes an example with neither code (a fenced, indented or HTML block) nor a source; inline code in prose is not read as code, and the three documented shapes (`complete`, `degraded`, `no_example` in the pinned OpenAPI document) are the only evidence of what real responses look like until the first live example is recorded. (6) The engineering smoke pins Claude Code 2.1.312 exactly because the host and the pilot VM run it; that version's flags were not re-checked here. 64. **The GitHits launcher fails closed before the network, and the treatment runs on a hooked API lane; neither is verified live, and other lookups on a `--bare` lane are still caught only after the fact.** The live canary of 2026-10-30 (Claude Code 2.1.312 on a Freestyle Linux VM) settled 56 (2): a `--settings` `PreToolUse` hook does not run under `--bare`, so `propose --claude-code --bare --githits` let the model run the launcher with no guard, and the client sent the lookup (`sent: true`) before the host stopped the run `provider_guard_inactive`. Now the launcher's entry sends nothing without claiming the hook's MAC-verified decision for its exact argv (`query_guard.claim_launch`; refused calls are recorded `status: unguarded`, `sent: false`), and `--githits` refuses `--bare` and runs on `--lane api-hooked` (the API key without `--bare`, a fresh `CLAUDE_CONFIG_DIR` and home per call, `--disable-slash-commands`; `docs/CLAUDE_CODE.md`). Not solved: (1) a decision is bound to the launcher's arguments (their SHA-256) and claimed once, not to a tool use id, which the launcher cannot see; a process holding the per-call key (a stdio MCP server, a shell under `--allow-code-tools-with-mcp`) can still sign a decision for its own arguments, as it could before; (2) the hook's words and the launcher's argv agree for plain words and quoted strings under a POSIX shell; a shell or platform that hands over different bytes (Git Bash's argument conversion to a Windows process, a non-UTF-8 byte) refuses a legitimate lookup (fail closed), which no live run has exercised; (3) WebSearch, WebFetch and `--mcp-config` (`mcp__githits__*`) lookups on a `--bare` lane have no pre-send gate: the hook does not run, so they still leave and are flagged `unguarded` afterwards; only `--githits` refuses `--bare`, and `api-hooked` or a login lane is where those tools are guarded; (4) `api-hooked` has run only against the stand-in `claude`: whether 2.1.312 with an empty config directory and home starts headless on `ANTHROPIC_API_KEY` (`apiKeySource`) and runs the hook is for its first live call, and the flags were read from 2.1.309's `--help` because 2.1.312's was not on the building machine; managed (policy) settings still load, `--setting-sources` has no value meaning `--settings` alone, `USERPROFILE` moves only on Windows, and the worktree's memory files (`CLAUDE.md`) are read in both arms, so the lane needs `--trusted-tree`; (5) the example license parser now reads any ATX or bold heading that names a source or reference ("## Source code" included) as a sources section and a fenced or indented block inside a blockquote as code, both of which can only drop more examples (fail closed); how often that drops a usable GitHits example is not measured; (6) the default deny-list (`SyberLabs`, `sykosyber`, `pypi:syberwork`, `deepwiki.com`, `deepwiki.org`) detects a fork of a SyberLabs repository only by its name (`githits.FORK_NAMES`) in a result's URL or a target, so a renamed fork, a vendored copy, or SyberLabs code mirrored under another name and site still passes, and no mirror or front-end other than DeepWiki is listed. -65. **The factory's goal gate is an owner signature, not yet a kernel approval; the candidate's process still shares memory with its recorder; the behavior-change label is per contract.** `factory-goal-gate` (2026-11-02, on the factory slice of #154) closes the slice's verification findings: `spec promote`, `canonize` and `retire` need a human actor and an approval that verifies (`factory approve` signs it with the owner's seed through the certificate module's Ed25519 and DSSE; `spec promote` verifies it under the owner key the ledger pins (`owner_key_set`; `factory owner`), never a key the caller names, resolves every `--verdict` to a ledger `review` that accepted the very variant on disk, refuses an approver who proposed or reviewed it, stores the approval under `approvals/` and cites its `approval_recorded` hash from the `spec_changed`); every artifact load checks the file against the digest the ledger recorded and `verify` covers artifacts, so an edited golden journal refuses the check instead of becoming its baseline; the candidate runs under `python -I` in a host-owned scratch directory, is never told the ledger's path, writes a journal sealed per record under a per-run key the parent holds, reports over a nonce-bound private pipe, and the parent reads the `end` record itself and refuses a journal with no end, a planted line or a mismatching report; `verify` recomputes the policy from the evidence and `signed: true` needs a verifying signature; reviewer independence is the provider family the command declared, not the caller's name, and an unrecorded family refuses; subprocess argv, cwd, socket addresses and the tests tail are scrubbed of credential shapes; the viewer builds its DOM with `textContent` and carries no payloads; ledger appends use the kernel journal's lock, fsync and torn-tail repair, and the projection rebuilds when the log moved; the tests check honours the contract's timeout, `full_suite` means the suite ran to completion, and a timed-out suite or recording has its process tree stopped; after the independent verification of #164 (2026-11-02), the candidate's process and the test suite run under the Build Thread's scrubbed environment without the host's signing seed or the check's `--seed-env` variable, a killed run's journal is not delivered, and `Approved` is constructible by `verify_approval` only. What remains: (1) the approval is the owner's signature over the spec's content digest, not an `approved` event on a kernel goal case, because the factory has no case to hang one on; the trust model is exactly this: promotion is bound to the owner key the ledger pins, not to the caller of the host CLI; the pin's bootstrap (`factory owner --public KEY`, or the first `--owner-public` on a ledger that pins none) is the one unsigned act, done by the operator by hand, so whoever pins first on an empty ledger owns it (a Class C act), after which only the pinned key approves (`owner_key_mismatch` otherwise, `owner_key_unset` before any pin) and only the pinned key rotates (`owner_key_rotation` otherwise); after the delta verification of the pin (2026-11-02, M3) the key is read through the ledger's verified lineage, not its newest `owner_key_set`: one bare bootstrap, then rotations whose `previous` is the key pinned before them and whose stored envelope verifies under it, so an appended pin, a rotation the pinned key did not sign, a stale `previous` or a malformed keyid fails `verify` and refuses the gate at `owner_key_lineage` with no fallback to an earlier key, `spec promote|canonize|retire` verify the ledger before the gate reads it, `factory check` verifies it again after the test suite and before attesting, and `set_owner_key` reads and appends under one lock; the pin is therefore as strong as the ledger's verified lineage, and the boundary that remains is (3), an attacker who can rewrite the whole chain consistently, which the deferred `tlog`/`witness` anchoring closes; the ledger event is the citation the consolidation's §1.2 asks for, the journal hash is not; (2) io observation runs in the candidate's process, so code there can reach `_factory_harness._CURRENT[-1]` and its key through `sys.modules` and write records the seal accepts, or call the recorder's own `__exit__`; the seal and the channel raise the cost of a forgery, they are not a sandbox, and the recommendation on the open owner question stands: evidence with a person in the path, not the auto class; (3) a candidate that learns the ledger's absolute path from the contract in its worktree can still write to it between the check's two verifications only by forging a consistent unkeyed chain and matching digests, which `verify` does not distinguish from an honest ledger across runs; anchoring the chain head in `tlog`/`witness` is the fix; (4) the behavior-change label is `--behavior-change` on the check's argv, per contract, not a field of the ticket; (5) `independence` reads the model the command declared, so a command that lies about its model passes as it does for `model_usage`; (6) `verify_journal` reads text, so a journal whose line endings were rewritten verifies by content while the ledger's byte digest refuses it, which is the intended division, and the approval likewise covers the spec's content digest (parsed, `history` excluded), so a re-serialized file is the same spec and an edit to the file's `history` after signing is not covered, the ledger's `spec_changed` events being the history of record; (7) before this packet the ledger had no cross-process lock (two commands on one home could fork the chain, detected by `append` but not prevented) and `docs/FACTORY.md` said 18 tests where the file defined 35; both are fixed here. The consolidation's other C1 items (`serves`, `mission_ref`, `done_when` on specs, mandatory `human_owner` on tickets, `promote` renamed `pass`, `tickets.py`, `codemap.py`) are not in this packet. +65. **The factory's goal gate is an owner signature, not yet a kernel approval; the candidate's process still shares memory with its recorder; the behavior-change label is per contract.** `factory-goal-gate` (2026-11-02, on the factory slice of #154) closes the slice's verification findings: `spec promote`, `canonize` and `retire` need a human actor and an approval that verifies (`factory approve` signs it with the owner's seed through the certificate module's Ed25519 and DSSE; `spec promote` verifies it under the owner key the ledger pins (`owner_key_set`; `factory owner`), never a key the caller names, resolves every `--verdict` to a ledger `review` that accepted the very variant on disk, refuses an approver who proposed or reviewed it, stores the approval under `approvals/` and cites its `approval_recorded` hash from the `spec_changed`); every artifact load checks the file against the digest the ledger recorded and `verify` covers artifacts, so an edited golden journal refuses the check instead of becoming its baseline; the candidate runs under `python -I` in a host-owned scratch directory, is never told the ledger's path, writes a journal sealed per record under a per-run key the parent holds, reports over a nonce-bound private pipe, and the parent reads the `end` record itself and refuses a journal with no end, a planted line or a mismatching report; `verify` recomputes the policy from the evidence and `signed: true` needs a verifying signature; reviewer independence is the provider family the command declared, not the caller's name, and an unrecorded family refuses; subprocess argv, cwd, socket addresses and the tests tail are scrubbed of credential shapes; the viewer builds its DOM with `textContent` and carries no payloads; ledger appends use the kernel journal's lock, fsync and torn-tail repair, and the projection rebuilds when the log moved; the tests check honours the contract's timeout, `full_suite` means the suite ran to completion, and a timed-out suite or recording has its process tree stopped; after the independent verification of #164 (2026-11-02), the candidate's process and the test suite run under the Build Thread's scrubbed environment without the host's signing seed or the check's `--seed-env` variable, a killed run's journal is not delivered, and `Approved` is constructible by `verify_approval` only. What remains: (1) the approval is the owner's signature over the spec's content digest, not an `approved` event on a kernel goal case, because the factory has no case to hang one on; the trust model is exactly this: promotion is bound to the owner key the ledger pins, not to the caller of the host CLI; the pin's bootstrap (`factory owner --public KEY`, or the first `--owner-public` on a ledger that pins none) is the one unsigned act, done by the operator by hand, so whoever pins first on an empty ledger owns it (a Class C act), after which only the pinned key approves (`owner_key_mismatch` otherwise, `owner_key_unset` before any pin) and only the pinned key rotates (`owner_key_rotation` otherwise); after the delta verification of the pin (2026-11-02, M3) the key is read through the ledger's verified lineage, not its newest `owner_key_set`: one bare bootstrap, then rotations whose `previous` is the key pinned before them and whose stored envelope verifies under it, so an appended pin, a rotation the pinned key did not sign, a stale `previous` or a malformed keyid fails `verify` and refuses the gate at `owner_key_lineage` with no fallback to an earlier key, `spec promote|canonize|retire` verify the ledger before the gate reads it, `factory check` verifies it again after the test suite and before attesting, and `set_owner_key` reads and appends under one lock; after the second delta verification (2026-11-02, M4: the rotation envelope named the two keys only, so an honest `A -> B` envelope replayed by an append after the owner rotated `B` away, given a ledger write and `B`'s seed) the envelope (`owner-key/v1`; a `v0` envelope is refused) is signed over the `seq` of the pin it replaces and the ledger head at signing, the walk checks both against the chain and refuses a `rotation_digest` cited twice (`owner_key_lineage: ... rotation replayed`), so an envelope verifies at the one position it was signed for and a seed the owner rotated away re-pins nothing by append; the pin is therefore as strong as the ledger's verified lineage, and the boundary that remains is (3), an attacker who rewrites the whole chain consistently from the rotation they want undone, which the deferred `tlog`/`witness` anchoring closes; the ledger event is the citation the consolidation's §1.2 asks for, the journal hash is not; (2) io observation runs in the candidate's process, so code there can reach `_factory_harness._CURRENT[-1]` and its key through `sys.modules` and write records the seal accepts, or call the recorder's own `__exit__`; the seal and the channel raise the cost of a forgery, they are not a sandbox, and the recommendation on the open owner question stands: evidence with a person in the path, not the auto class; (3) a candidate that learns the ledger's absolute path from the contract in its worktree can still write to it between the check's two verifications only by forging a consistent unkeyed chain and matching digests, which `verify` does not distinguish from an honest ledger across runs; the same rewrite is the only way left to re-pin a key the owner rotated away, since every rotation is bound to its position and none is accepted twice; anchoring the chain head in `tlog`/`witness` is the fix; (4) the behavior-change label is `--behavior-change` on the check's argv, per contract, not a field of the ticket; (5) `independence` reads the model the command declared, so a command that lies about its model passes as it does for `model_usage`; (6) `verify_journal` reads text, so a journal whose line endings were rewritten verifies by content while the ledger's byte digest refuses it, which is the intended division, and the approval likewise covers the spec's content digest (parsed, `history` excluded), so a re-serialized file is the same spec and an edit to the file's `history` after signing is not covered, the ledger's `spec_changed` events being the history of record; (7) before this packet the ledger had no cross-process lock (two commands on one home could fork the chain, detected by `append` but not prevented) and `docs/FACTORY.md` said 18 tests where the file defined 35; both are fixed here. The consolidation's other C1 items (`serves`, `mission_ref`, `done_when` on specs, mandatory `human_owner` on tickets, `promote` renamed `pass`, `tickets.py`, `codemap.py`) are not in this packet. diff --git a/syberlabs/factory/ledger.py b/syberlabs/factory/ledger.py index 381fdc0..572df35 100644 --- a/syberlabs/factory/ledger.py +++ b/syberlabs/factory/ledger.py @@ -23,8 +23,10 @@ approvals under a key the ledger names rather than one the caller passes. The pin is read through its lineage (``owner_key_lineage``, ``spec.owner_key_lineage``), not from the newest event: ``problems`` walks every ``owner_key_set`` in order, demands one bare bootstrap and then rotations whose ``previous`` is the key pinned -before them and whose stored envelope verifies under that key, so an ``owner_key_set`` appended around -``set_owner_key`` makes the ledger fail ``verify`` and pins nothing rather than re-rooting the gate. +before them and whose stored envelope verifies under that key for that very position (the envelope names +the ``seq`` of the pin it replaces and the head it was signed over, and a ``rotation_digest`` is cited once), +so an ``owner_key_set`` appended around ``set_owner_key``, a replayed handover included, makes the ledger +fail ``verify`` and pins nothing rather than re-rooting the gate. Appends go through the kernel journal's writer (``syberlabs.journal.Journal``): a cross-process lock (``flock`` or ``msvcrt.locking``), flush and fsync per record, and truncation of a torn final line before the next read. @@ -325,9 +327,10 @@ def load_rotation(self, sha: str) -> dict | None: def owner_key_lineage(self, events: list[dict] | None = None) -> tuple[str | None, list[str]]: """``(pinned key, violations)`` from :func:`spec.owner_key_lineage` over this ledger's events, its stored rotations supplying the envelopes: the first ``owner_key_set`` is the one bare bootstrap, every later one - carries ``previous`` equal to the key pinned before it and a ``rotation_digest`` whose envelope verifies - under that previous key, and every keyid is well-formed hex. Any violation names the event and leaves - the ledger pinning nothing; ``problems`` reports each one as ``owner_key_lineage``.""" + carries ``previous`` equal to the key pinned before it and a ``rotation_digest``, cited nowhere else, + whose envelope verifies under that previous key for this position (the seq it replaces, the head before + it), and every keyid is well-formed hex. Any violation names the event and leaves the ledger pinning + nothing; ``problems`` reports each one as ``owner_key_lineage``.""" return specmod.owner_key_lineage(self.events() if events is None else events, self.load_rotation) def owner_key(self, events: list[dict] | None = None) -> str | None: @@ -339,7 +342,8 @@ def set_owner_key(self, public: bytes, *, seed: bytes | None = None) -> dict: """Pin ``public`` as the owner key. On a ledger that pins none this is the bootstrap: one event, no signature, and from then on the goal gate trusts this key and no other. On a ledger that pins a key it is a rotation and needs ``seed``, the seed of the key pinned now: the handover is signed by that - key (``spec.sign_rotation``), verified, stored under ``approvals/`` and cited by the event. Refused + key (``spec.sign_rotation``) over the seq of the pin it replaces and the ledger head it lands on, so it + verifies at this position only, then verified, stored under ``approvals/`` and cited by the event. Refused when the seed is not the pinned key's (``owner_key_rotation``), the key is already pinned (``owner_key_pinned``) or the lineage so far does not verify (``owner_key_lineage``). The read of the pinned key and the append are one lock acquisition, so two bootstraps racing on an empty ledger @@ -358,8 +362,11 @@ def set_owner_key(self, public: bytes, *, seed: bytes | None = None) -> dict: raise Rejected("owner_key_rotation", f"the ledger pins {current[:10]}; rotating to {keyid[:10]} needs that key's seed (--seed-env)") if public_from_seed(seed).hex() != current: raise Rejected("owner_key_rotation", f"the seed given is not the pinned owner key's ({current[:10]}); only the pinned key rotates") - envelope = specmod.sign_rotation(specmod.rotation_payload(bytes.fromhex(current), public), seed) - specmod.verify_rotation(envelope, bytes.fromhex(current), public) + # The lineage verified, so the last owner_key_set is the pin of ``current``; the head is what the new + # event's ``previous`` will be, and the lock holds both still until the append. + replaces_seq, head = next(e["seq"] for e in reversed(events) if e["kind"] == "owner_key_set"), events[-1]["hash"] + envelope = specmod.sign_rotation(specmod.rotation_payload(bytes.fromhex(current), public, replaces_seq=replaces_seq, head=head), seed) + specmod.verify_rotation(envelope, bytes.fromhex(current), public, replaces_seq=replaces_seq, head=head) sha = digest(envelope) (self.home / "approvals" / f"{sha}.json").write_text(canonical(envelope), encoding="utf-8") return self._append(writer, events, "owner_key_set", {"keyid": keyid, "previous": current, "rotation_digest": sha}) diff --git a/syberlabs/factory/spec.py b/syberlabs/factory/spec.py index cc2b313..1c64528 100644 --- a/syberlabs/factory/spec.py +++ b/syberlabs/factory/spec.py @@ -23,7 +23,10 @@ the previous key signed (:func:`verify_rotation`). The pin is read through its lineage, never from the last event alone: :func:`owner_key_lineage` walks every ``owner_key_set`` in order and verifies each handover under the key pinned before it, so an appended pin, a rotation the pinned key did not sign, a stale ``previous`` or -a malformed key invalidates the lineage instead of re-rooting the gate (``owner_key_lineage``). :func:`gate` +a malformed key invalidates the lineage instead of re-rooting the gate (``owner_key_lineage``). A rotation +envelope is bound to its place on the chain: its payload names the ``seq`` of the pin it replaces and the +ledger head at signing, the walk checks both against the chain, and a ``rotation_digest`` cited twice is a +replay, so an honest handover cannot be appended again after the owner rotated that key away. :func:`gate` verifies every approval under the lineage's key only; a ledger with no pinned key refuses (``owner_key_unset``), an invalid lineage refuses (``owner_key_lineage``, never falling back to an earlier key) and an approval under any other key refuses (``owner_key_mismatch``), whoever runs the host command. The signing seed never enters @@ -61,7 +64,10 @@ ACTOR_KINDS = ("human", "model", "compiled") APPROVAL_PROTOCOL = "syberlabs.space/factory/approval/v0" APPROVAL_PAYLOAD_TYPE = "application/vnd.syberlabs.factory-approval+json" -OWNER_KEY_PROTOCOL = "syberlabs.space/factory/owner-key/v0" +OWNER_KEY_PROTOCOL = "syberlabs.space/factory/owner-key/v1" +# v0 envelopes named the two keys only and were bound to nothing on the chain, so one could be replayed (M4 of +# the #164 delta verification); no production ledger carries one, and the walk refuses them outright. +_RETIRED_OWNER_KEY_PROTOCOLS = frozenset({"syberlabs.space/factory/owner-key/v0"}) OWNER_KEY_PAYLOAD_TYPE = "application/vnd.syberlabs.factory-owner-key+json" _PRINCIPAL_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._@+-]{0,63}$") _HEX_KEY = re.compile(r"^[0-9a-f]{64}$") @@ -103,13 +109,17 @@ def owner_key_lineage(events: list[dict], load_rotation=None) -> tuple[str | Non is the one unsigned bootstrap: ``previous`` None, no ``rotation_digest``. Every later one is a rotation: ``previous`` is the key pinned right before it, ``rotation_digest`` names a stored envelope (``load_rotation(digest)``, the ledger's ``approvals/``; None when missing or altered) that - :func:`verify_rotation` accepts under that previous key, and every ``keyid`` is a 64-hex public key. A - second bare bootstrap, a rotation signed by the new key, a stale ``previous`` and a malformed key are each - a violation. With violations the lineage is invalid and the key returned is None: a broken lineage pins - nothing rather than its last or an earlier key. Without a ``load_rotation`` no rotation can be checked, so - a rotated ledger read that way is invalid, by design.""" - pinned, violations = None, [] - for event in events: + :func:`verify_rotation` accepts under that previous key for exactly this position (its payload's + ``replaces_seq`` is the ``seq`` of the pin it replaces and its ``head`` is the hash of the event right + before this one, the ledger head when it was signed), and every ``keyid`` is a 64-hex public key. A second + bare bootstrap, a rotation signed by the new key, a stale ``previous``, a malformed key, an envelope signed + for another position (or never appended where it was signed) and a ``rotation_digest`` cited a second time + (a replay of an honest handover after the owner rotated that key away) are each a violation. With + violations the lineage is invalid and the key returned is None: a broken lineage pins nothing rather than + its last or an earlier key. Without a ``load_rotation`` no rotation can be checked, so a rotated ledger + read that way is invalid, by design.""" + pinned, pinned_seq, cited, violations = None, None, {}, [] + for index, event in enumerate(events): if not isinstance(event, dict) or event.get("kind") != "owner_key_set": continue where = f"owner_key_set at seq {event.get('seq', '?')}" @@ -126,16 +136,22 @@ def owner_key_lineage(events: list[dict], load_rotation=None) -> tuple[str | Non violations.append(f"{where}: previous {str(previous)[:10]!r} is not the key pinned before it ({pinned[:10]})") if not (isinstance(rotation, str) and _HEX_KEY.match(rotation)): # a sha256 digest has the key's shape violations.append(f"{where}: a second pin is a rotation and names a rotation_digest; a bare pin does not re-root the ledger") + elif rotation in cited: + violations.append(f"{where}: rotation replayed; {rotation[:12]} was already cited at seq {cited[rotation]}") else: + cited[rotation] = event.get("seq", "?") + before = events[index - 1].get("hash") if index and isinstance(events[index - 1], dict) else None envelope = load_rotation(rotation) if load_rotation is not None else None if envelope is None: violations.append(f"{where}: rotation {rotation[:12]} is missing, altered or unavailable") + elif not (isinstance(pinned_seq, int) and isinstance(before, str)): + violations.append(f"{where}: the chain gives this rotation no position (seq and hash) to bind to") else: try: - verify_rotation(envelope, bytes.fromhex(pinned), bytes.fromhex(keyid)) + verify_rotation(envelope, bytes.fromhex(pinned), bytes.fromhex(keyid), replaces_seq=pinned_seq, head=before) except Rejected as exc: violations.append(f"{where}: {exc.detail}") - pinned = keyid + pinned, pinned_seq = keyid, event.get("seq") return (None if violations else pinned), violations @@ -149,19 +165,28 @@ def pinned_owner_key(events: list[dict], load_rotation=None) -> str | None: return pinned -def rotation_payload(previous: bytes, next_key: bytes) -> dict: - """What the current owner signs to hand the ledger to a new key: the key being replaced and the key that - replaces it. Signed by ``previous``; nothing else can rotate.""" - return {"protocol": OWNER_KEY_PROTOCOL, "previous": previous.hex(), "next": next_key.hex(), "at": int(time.time() * 1_000_000)} +def rotation_payload(previous: bytes, next_key: bytes, *, replaces_seq: int, head: str) -> dict: + """What the current owner signs to hand the ledger to a new key: the key being replaced, the key that + replaces it, and the place on the chain this handover is for (``replaces_seq``, the ``seq`` of the + ``owner_key_set`` that pinned ``previous``, and ``head``, the ledger head hash at signing, which is the + ``previous`` of the event the rotation lands as). Signed by ``previous``; nothing else can rotate, and the + envelope verifies at that one position only.""" + if not (isinstance(replaces_seq, int) and not isinstance(replaces_seq, bool) and replaces_seq >= 1): + raise Rejected("owner_key_rotation", "a rotation names the seq of the pin it replaces") + if not (isinstance(head, str) and _HEX_KEY.match(head)): # a chain hash has the key's shape + raise Rejected("owner_key_rotation", "a rotation names the ledger head it was signed over") + return {"protocol": OWNER_KEY_PROTOCOL, "previous": previous.hex(), "next": next_key.hex(), + "replaces_seq": replaces_seq, "head": head, "at": int(time.time() * 1_000_000)} def sign_rotation(payload: dict, seed: bytes) -> dict: return sign_dsse(OWNER_KEY_PAYLOAD_TYPE, canonical(payload).encode("utf-8"), seed) -def verify_rotation(envelope: dict, previous: bytes, next_key: bytes) -> dict: +def verify_rotation(envelope: dict, previous: bytes, next_key: bytes, *, replaces_seq: int, head: str) -> dict: """The rotation payload when ``envelope`` verifies under ``previous`` (the pinned key) and names exactly - this handover; refused (``owner_key_rotation``) otherwise.""" + this handover at exactly this position (``replaces_seq`` and ``head`` as :func:`rotation_payload` binds + them); refused (``owner_key_rotation``) otherwise, a retired ``owner-key/v0`` envelope included.""" payload = verified_payload(envelope, previous, OWNER_KEY_PAYLOAD_TYPE) if payload is None: raise Rejected("owner_key_rotation", "a rotation is signed by the key the ledger pins now; this one does not verify under it") @@ -169,9 +194,17 @@ def verify_rotation(envelope: dict, previous: bytes, next_key: bytes) -> dict: rotation = json.loads(payload) except ValueError: raise Rejected("owner_key_rotation", "the rotation payload is not JSON") from None - if (not isinstance(rotation, dict) or rotation.get("protocol") != OWNER_KEY_PROTOCOL + if not isinstance(rotation, dict): + raise Rejected("owner_key_rotation", "the rotation payload is not a factory rotation") + if rotation.get("protocol") in _RETIRED_OWNER_KEY_PROTOCOLS: + raise Rejected("owner_key_rotation", f"the rotation is {rotation['protocol']}, which binds to nothing on the chain and is refused; " + f"rotations are {OWNER_KEY_PROTOCOL}") + if (rotation.get("protocol") != OWNER_KEY_PROTOCOL or rotation.get("previous") != previous.hex() or rotation.get("next") != next_key.hex()): raise Rejected("owner_key_rotation", "the rotation does not name this handover (previous and next key)") + if rotation.get("replaces_seq") != replaces_seq or rotation.get("head") != head: + raise Rejected("owner_key_rotation", f"the rotation was signed for another position (replaces seq {rotation.get('replaces_seq')!r} " + f"over head {str(rotation.get('head'))[:12]}); here it replaces seq {replaces_seq} over head {head[:12]}") return rotation diff --git a/tests/test_factory.py b/tests/test_factory.py index 6635b5c..9de7976 100644 --- a/tests/test_factory.py +++ b/tests/test_factory.py @@ -1004,8 +1004,12 @@ def test_the_owner_key_is_the_verified_lineage_not_the_newest_event(self): (tree / "forged.json").write_text(json.dumps(forged), encoding="utf-8") def rotation(target, previous, next_key, signer_seed, claimed_previous=None): - """An ``owner_key_set`` body with its envelope stored where ``verify`` looks, signed by whoever.""" - envelope = specmod.sign_rotation(specmod.rotation_payload(previous, next_key), signer_seed) + """An ``owner_key_set`` body with its envelope stored where ``verify`` looks, signed by whoever over the + position it is appended at (the pin it replaces, the head it lands on), so only the signer is wrong.""" + events = target.events() + replaces_seq = next(e["seq"] for e in reversed(events) if e["kind"] == "owner_key_set") + payload = specmod.rotation_payload(previous, next_key, replaces_seq=replaces_seq, head=target.head(events)) + envelope = specmod.sign_rotation(payload, signer_seed) sha = digest(envelope) (target.home / "approvals" / f"{sha}.json").write_text(canonical(envelope), encoding="utf-8") return {"keyid": next_key.hex(), "previous": (claimed_previous or previous).hex(), "rotation_digest": sha} @@ -1057,6 +1061,113 @@ def rotation(target, previous, next_key, signer_seed, claimed_previous=None): self.assertIn("candidate -> retired", out) self.assertTrue(home.verify()) self.assertEqual(home.describe()["owner_key"], second_public.hex()) + def test_a_rotation_binds_to_its_position_and_a_replayed_envelope_is_refused(self): + """M4 of the #164 delta verification: a rotation envelope verifies at the one position it was signed for. + After an honest bootstrap A, rotation A -> B (envelope S1) and rotation back B -> A (the owner taking the + ledger back from a leaked key), an ``owner_key_set`` appended through the public ``append`` that cites S1 + again (``keyid`` B, ``previous`` A) fails ``verify``, is named ``rotation replayed`` by ``problems``, pins + nothing, refuses the gate at ``owner_key_lineage`` for an approval B signs (and one A signs) and exits + `spec retire` with 2. An envelope the pinned key honestly signed for this position but appended after + another event landed, one naming the wrong ``replaces_seq``, and a retired ``owner-key/v0`` envelope are + refused the same way. The honest ledger pins A, retires, and rotates to B again under a fresh envelope.""" + from syberlabs.canonical import canonical, digest + mateo = {"kind": "human", "id": "mateo"} + tree = self.scratch / "tree" + shutil.copytree(FIXTURE, tree) + (tree / "spec.json").write_text(json.dumps(specmod.new_spec("order-path", "ordering", [ + {"req_id": "R1", "text": "When quantity is positive, the system shall post one order."}], + ["ingest", "rules", "effects"], author=mateo)), encoding="utf-8") + code, _, err = self.run_cli("spec", "validate", "spec.json", "--actor", "human:mateo", cwd=tree) + self.assertEqual(code, 0, err) + a_seed, a_public = generate() + b_seed, b_public = generate() + home = ledger.Ledger(tree / ".syberlabs" / "factory") + bootstrap = home.set_owner_key(a_public) + handover = home.set_owner_key(b_public, seed=a_seed) + back = home.set_owner_key(a_public, seed=b_seed) + self.assertEqual((home.owner_key(), home.owner_key_lineage()[1], home.verify()), (a_public.hex(), [], True)) + # The honest envelope names its position: the bootstrap it replaced and the head it was signed over, which + # is the hash of the event right before it. At the position of the rotation back it does not verify. + s1 = handover["body"]["rotation_digest"] + before_handover = home.events()[handover["seq"] - 2]["hash"] + payload = specmod.verify_rotation(home.load_rotation(s1), a_public, b_public, replaces_seq=bootstrap["seq"], head=before_handover) + self.assertEqual((payload["protocol"], payload["replaces_seq"], payload["head"]), + ("syberlabs.space/factory/owner-key/v1", bootstrap["seq"], before_handover)) + with self.assertRaises(Rejected) as refused: + specmod.verify_rotation(home.load_rotation(s1), a_public, b_public, replaces_seq=back["seq"], head=back["hash"]) + self.assertEqual(refused.exception.code, "owner_key_rotation") + for bad in ({"replaces_seq": 0, "head": back["hash"]}, {"replaces_seq": True, "head": back["hash"]}, {"replaces_seq": 1, "head": "short"}): + with self.assertRaises(Rejected, msg=bad): + specmod.rotation_payload(a_public, b_public, **bad) + document = json.loads((tree / "spec.json").read_text(encoding="utf-8")) + under_b = specmod.sign_approval(specmod.approval_payload(document, "retire", mateo), b_seed) + under_a = specmod.sign_approval(specmod.approval_payload(document, "retire", mateo), a_seed) + (tree / "b.json").write_text(json.dumps(under_b), encoding="utf-8") + (tree / "a.json").write_text(json.dumps(under_a), encoding="utf-8") + + def stored(target, payload, signer_seed): + envelope = specmod.sign_rotation(payload, signer_seed) + sha = digest(envelope) + (target.home / "approvals" / f"{sha}.json").write_text(canonical(envelope), encoding="utf-8") + return sha + + def moved(target): + """Signed by the pinned key for exactly this position, then a line lands before it is appended.""" + sha = stored(target, specmod.rotation_payload(a_public, b_public, replaces_seq=back["seq"], head=target.head()), a_seed) + target.append("note", {"text": "lands between signing and appending"}) + return sha + + shapes = [ + ("the honest A -> B envelope replayed after B -> A", lambda t: s1, "rotation replayed"), + ("an envelope signed for this position, appended one event later", moved, "signed for another position"), + ("an envelope naming the bootstrap as the pin it replaces", + lambda t: stored(t, specmod.rotation_payload(a_public, b_public, replaces_seq=bootstrap["seq"], head=t.head()), a_seed), + "signed for another position"), + ("a retired owner-key/v0 envelope", + lambda t: stored(t, {"protocol": "syberlabs.space/factory/owner-key/v0", "previous": a_public.hex(), "next": b_public.hex(), "at": 0}, a_seed), + "owner-key/v0"), + ] + for number, (shape, cite, named) in enumerate(shapes): + copy = self.scratch / f"shape{number}" + shutil.copytree(tree, copy) + target = ledger.Ledger(copy / ".syberlabs" / "factory") + appended = target.append("owner_key_set", {"keyid": b_public.hex(), "previous": a_public.hex(), "rotation_digest": cite(target)}) + events = target.events() + self.assertTrue(ledger._verify_chain(events), shape) + self.assertFalse(target.verify(), shape) + where = f"owner_key_lineage: owner_key_set at seq {appended['seq']}" + self.assertTrue(any(p.startswith(where) and named in p for p in target.problems()), (shape, target.problems())) + self.assertEqual(target.owner_key_lineage(events)[0], None, shape) + with self.assertRaises(Rejected, msg=shape) as refused: + target.owner_key() + self.assertEqual(refused.exception.code, "owner_key_lineage", shape) + for envelope in (under_b, under_a): + with self.assertRaises(Rejected, msg=shape) as refused: + specmod.gate(document, "retire", mateo, events, envelope, load_rotation=target.load_rotation) + self.assertEqual(refused.exception.code, "owner_key_lineage", shape) + with self.assertRaises(Rejected, msg=shape) as refused: + target.set_owner_key(b_public, seed=a_seed) + self.assertEqual(refused.exception.code, "owner_key_lineage", shape) + for approval in ("b.json", "a.json"): + code, _, err = self.run_cli("spec", "retire", "spec.json", "--actor", "human:mateo", "--approval", approval, cwd=copy) + self.assertEqual((code, "owner_key_lineage" in err), (2, True), (shape, err)) + self.assertEqual(json.loads((copy / "spec.json").read_text(encoding="utf-8"))["state"], "candidate", shape) + # In memory, events with no seq or hash give a rotation nothing to bind to, so it is a violation, not a pin. + bare = [{"kind": "owner_key_set", "body": bootstrap["body"]}, {"kind": "owner_key_set", "body": handover["body"]}] + pinned, violations = specmod.owner_key_lineage(bare, home.load_rotation) + self.assertEqual(pinned, None) + self.assertTrue(any("no position" in v for v in violations), violations) + # The honest ledger: B's approval is a mismatch (B was rotated away), A's retires, and a fresh rotation to B + # is a new envelope at its own position, not S1 again. + code, _, err = self.run_cli("spec", "retire", "spec.json", "--actor", "human:mateo", "--approval", "b.json", cwd=tree) + self.assertEqual((code, "owner_key_mismatch" in err), (2, True), err) + code, out, err = self.run_cli("spec", "retire", "spec.json", "--actor", "human:mateo", "--approval", "a.json", cwd=tree) + self.assertEqual(code, 0, err) + self.assertIn("candidate -> retired", out) + again = home.set_owner_key(b_public, seed=a_seed) + self.assertNotEqual(again["body"]["rotation_digest"], s1) + self.assertEqual((home.owner_key(), home.owner_key_lineage()[1], home.verify()), (b_public.hex(), [], True)) + self.assertEqual(home.describe()["owner_key"], b_public.hex()) if __name__ == "__main__":