Eve library

Eve SOTA triage contract — `eve.triage.v1`, record of 2026-10

Audit

Revision 7

On this page
  • Task: 2.4
  • Evaluated: 2026-10-04, from Git at 14107ad861c26e8c3aba553be6e4ef462754f584
  • Decision: typed-triage-enforced
  • ADR gate: typed-triage, ADR-0076 (Eve document b8c933b0-9f07-8e7f-be0c-76f85f3da110, revision 1)
  • Record digest: 38a12592647c5b65c317d5241e5a61b2310aad8c73e02522bb14bf3dff726713
  • Supersedes: docs/audits/eve-sota-triage-contract/2026-09-05.json (record digest 38b875b5190c2383ded2f7e986ecb5f3c453a9dfd0ba58cfb9bdebbf28cdc8c5), which is preserved unchanged and stays rejected

The rule#

A requeue out of a held status and a close both refuse without a triage record, and the refusal writes nothing. Every record names one of a closed set of classes and carries evidence. A standalone triage request is written through one operation that requires an idempotency key and, while the item is leased, the holder’s fencing token. A triage record also reaches the ledger with a transition, from the queue’s lease recovery, from a duplicate close and from the planning lifecycle; those paths have their own guards, set out below, and do not all require an idempotency key.

The classes#

Class Named by Means Retry disposition
ship-verify-gap task 2.4 The artifact-diff verifier observed the knowledge plane and the shipped claim did not hold. needs-human-decision
test-failure task 2.4 The agent's own checks failed; the work did not reach a reviewable state. retry-when-ready
conflict task 2.4 A repository, lease, or state conflict blocked the attempt; the work itself was not judged. retry-when-ready
ambiguous-requirement task 2.4 The brief could not be executed as written, so no amount of retrying it will help. needs-human-decision
budget-exhausted task 2.4 A spend, time, or attempt budget ended the attempt before the work was finished. needs-human-decision
agent-refusal task 2.4 The agent declined the work on policy, safety, or capability grounds and said so. needs-human-decision
lease-lapsed the runtime The acquisition ended without a report — an expired lease, a vanished holder, or a superseded hold. retry-when-ready
not-observed the runtime The item could not be read back after the attempt, so nothing is claimed about what happened to it. needs-human-decision
duplicate owner decision The item duplicates a board task it names; the work is tracked there, so this item closes. no-retry

The two exits that may never be silent#

Exit Requirement Guard Proved by
silent-requeue An attempt that leaves a held status for ready or parked must record why it ended; the refusal writes nothing to the append-only ledger. triageRequiredFor refuses a silent requeue and writes NOTHING
quiet-close A rejected item must record why it was refused, and a human is no more exempt than a machine. triageRequiredFor refuses a quiet close and writes NOTHING

What a standalone triage request must carry#

  • Idempotency key. A standalone triage request names itself with an idempotency key. The route refuses a request without one and writes nothing. The same key sent again with the same request replays the recorded outcome and appends no second event; a new triage needs a new key. This is the rule of the standalone request only: the other write paths below have their own. Required by the route: yes; at most 256 characters; a repeat replays: yes.
  • Lease fencing. While an item carries a live lease only the lease holder may send a standalone triage for it, and the request must present the lease’s fencing token; without a live lease a token is refused. The store decides this under its lock. Holder only: yes; fence checked: yes.

Each operation: exposed, what it sends, and what was seen written#

"Exposed" means the source declares the operation. "Seen written" means a retained run at the capture commit ended with the triage on the ledger; it is claimed only when every case that shows it passed.

Operation Exposed Idempotency key Fencing token Seen written to the ledger Scope of that evidence
POST /v1/workbench/items/:id/triage yes required required-while-leased yes The real route on a real listener, with the real store over PostgreSQL.
workbench_triage (tools/workbench-mcp/server.mjs) yes required-input optional-input yes The real MCP server process, driven by a real MCP client over stdio, calling the real route.
drainTriageRequest (tools/eve-fleet-drain-lib.mjs), sent by tools/eve-fleet-drain.mjs yes sent sent-when-its-own-agent-holds-the-lease yes The request the drain’s library builds, sent by the spec to the real route. The drain process itself was not run, and no live drain is claimed.

The request both callers used to send, with no idempotency key, is refused and writes nothing: seen in the retained run.

Every way a triage record reaches the ledger#

The standalone request is one of five write paths in the source at the capture commit. The key and fencing rules above are its rules. The others are read from the source; the retained run did not exercise them.

Path Written as Writer In the source Classes Idempotency key Lease guard Seen written in the retained run
standalone-request work-item.triaged appendTriage (intent-store.ts), behind the route, the MCP tool and the fleet drain yes any required holder-only-with-fencing-token yes
transition-coupled work-item.transitioned, with the triage record in its payload transitionWorkItem (intent-store.ts) yes any required-only-for-a-move-to-leased-or-shipped holder-presents-its-fencing-token-or-the-whole-lease-is-compared no
runtime-lease-recovery work-item.transitioned, with the triage record in its payload the work queue (work-queue.ts), through transitionWorkItem yes lease-lapsed not-sent the-observed-lease-is-compared-whole no
duplicate-close work-item.transitioned, with the triage record in its payload the store, when a duplicate suggestion is accepted (intent-store.ts) yes duplicate not-sent as-the-transition no
planning-lifecycle work-item.triaged, and work-item.transitioned to rejected the store itself (planningTriage in intent-store.ts) yes conflict, ship-verify-gap none-of-its-own none no
  • standalone-request. The record explains and does not move the item. This is the path the three operations above use.
  • transition-coupled. A move carries the triage record itself. The record is required on the two guarded exits (yes) and refused on any other move (yes). An idempotency key is required only for a move to leased or shipped, so a requeue or a close can be written without one; when a key is sent, a repeat replays (yes). A caller that holds the lease must present its fencing token unless it passes the lease it observed, which is compared whole, token included, inside the transaction; a caller that is not the holder is not fenced by this path.
  • runtime-lease-recovery. The orphan sweep and the takeover of an expired lease requeue an item as the system (2 call sites), with a lease-lapsed record. They send no idempotency key. When a lease was observed, the requeue is guarded by that exact lease, so a lease that changed meanwhile is not released.
  • duplicate-close. Accepting a duplicate suggestion rejects the item with a duplicate record, inside the transaction of that decision. The transition carries no idempotency key of its own.
  • planning-lifecycle. The planning lifecycle writes triage records as the store: when a registered proof returns anything but verified, and when a planning work item is cancelled or invalidated (3 triaged events in the source, and a rejection with a conflict record: yes). These records have no idempotency key of their own and present no fencing token; they are written inside the planning operation’s transaction.

The evidence#

One retained run (docs/audits/eve-sota-triage-contract/2026-10-04.integration-run.json, SHA-256 bdc09de43075c8b1a4b819bcd3b0149a0c2cafe77e6b9046514ea4166f06e174), a local-test-observation: started 2026-10-04T08:05:52Z, finished 2026-10-04T08:06:06Z, exit code 0, at commit 14107ad861c26e8c3aba553be6e4ef462754f584; 3 passed, 0 failed, 0 skipped of 3. Database: pgvector/pgvector:pg16 (sha256:00ba258a66dac104fd5171074a0084462a64a1369d8513f3d0a634e2f24d15bc), 81 migrations applied; a throwaway container published on 127.0.0.1:55451 only, database oshun_dev created empty, migrated with prisma migrate deploy from libs/oshun/persistence, stopped and removed after the run; no row of the spec was left in it.

Case Result
refuses the request both callers used to send: no idempotency key, nothing written passed
the fleet drain’s request reaches the ledger, with the lease’s fencing token, and replays on a repeat passed
the MCP tool workbench_triage reaches the ledger through the real server process, and replays on a repeat passed

The earlier probe (tools/eve-everywhere/probe-fleet-drain.mjs): The fleet drain probe starts its own HTTP server as the workbench and answers every triage with success. It shows that the drain sends a triage; it cannot show that the workbench accepts one.

What this record supersedes, and why#

The 2026-09-05 record, its schema, its renderer and its pinned readable revision are preserved unchanged. It is not regenerated and it is not repaired by this record.

  • Rendering mismatch. The record was refreshed after its readable record was written: as committed it does not render to the revision Eve holds at its pin. Both are preserved unchanged and the mismatch stays a rejection of that record. The record (SHA-256 095488dd883e074fb639ff7ef4d2ecc0396c04902154cb6e0cd43db315c80cdb, refreshed 2026-09-24 by d5f6a886f83daf49f6a92787d0ba6cb7a4b1d965) renders to SHA-256 68100ac41c224af3657f5629a0ecb4bffe1d6d586fd3a817f9374030210d3712; Eve document 0dcafc7e-4e5e-8a2f-837b-40168fe6a7ce revision 1 is 127c8e8815eb691ce49e93cc8b70fba9b6d29fe61ff371961d8ca90d354aaa58.
  • Reachability. It said "MCP tool: true", "Fleet drain records it: true" and "End-to-end probe asserts it: true". The record reads these as reachability. They say an operation is exposed and that a probe asserted it; the probe’s workbench is a double that answers success. From the introducing commit to the correcting one the route required an idempotency key that the MCP tool could not send and the fleet drain did not send, so the workbench refused every triage either recorded, and the drain presented no fencing token for the lease its own agent held. Introduced by 627f2c8c96c6903cf3f0dec9976db54b4384d5f2 (2026-09-14); corrected by 6eb53be50987a128cf9af0b8c2900695fc159777 (2026-10-04).

Honest limits#

  • The ledger writes are local test observations of one run on one host against a throwaway PostgreSQL database; nothing here is a staging or production verification.
  • The MCP caller is the real server process. The fleet drain is represented by the request its library builds; the drain process was not run and no live drain is claimed.
  • A write is claimed for an operation only when every retained case that shows it passed at the capture commit. A skipped case, or the presence of a test file, substantiates nothing.
  • The transition-coupled, lease-recovery, duplicate-close and planning paths are described from the source at the capture commit. The retained run exercises the standalone request only; no write through the other paths is claimed as seen.
  • The other tools of the MCP server declare the idempotency key optional although the workbench refuses a request without one; they can send it, and they are outside this record.
  • This record closes task 2.4 only, as the earlier one did; the operator read model, execution isolation and the orchestrator model are other tasks.
  • The 2026-09-05 record stays rejected for its rendering mismatch. It is a preserved defect of the superseded record, not something this record repairs.