docs(docs): V1-2.3 verification worker, M6, sandbox e2e and rehearsals

This commit is contained in:
bchanot committed 2026-11-01 17:38:07 +01:00
1 parent 5afb34ed0f
commit 7043d39ae0
7 files changed
+106 -10

No files matched your search

+13 -2
View File
@@ -926,6 +926,16 @@ own (§16.11), because a started DEV worker also processes the avatar upload
waiting since the V1-1 acceptance (AVATAR-01) and the due rows of the purge
queue.
Implemented in V1-2.3 (2026-11-01, migration `20261101100000_sheet_verification_jobs.sql`,
`crates/worker` mode `sheet-verify`, STORAGE.md §3.6): lease 10 minutes, attempt limit
five, verdict text at most 4 MiB; the completion also refuses an unknown verdict format
or code, a duplicated group key and a drawing whose result is not `ok`, and accepts a
failed verdict without groups or drawings; worker codes `verification.worker.unavailable`,
`.timeout`, `.resource_limit`, `.lease_expired` (a dead lease), `.verdict_refused` (a
completion answered `malformed`), a closed list in SQL (`private.sheet_worker_codes`).
These values and codes are the implementer's, for the owner's confirmation. The
service role executes these four RPCs besides the two upload ones (pgTAP 018).
Rejected: a verdict computed in browsers (contrary to the owner's rule), a
synchronous HTTP verification service (a public endpoint holding the service
key, a sandbox to rebuild; not in the MVP), an operator command-line
@@ -945,7 +955,7 @@ did not pass; the closed codes keep the categories apart.
| Timeout or resource limit | child over its wall-clock or memory limit | stays `verifying`, code recorded | yes, up to the limit | reduce the document or the drawing if it repeats |
| Interruption | worker crash, lease expired | claimable again; counts as an attempt | yes, up to the limit | automatic |
| Stale result | completion with an old token, after a withdrawal, or naming another revision | nothing written, logged | no | none needed |
| Definitive failure | attempt limit reached (five, proposal, tuned in V1-2.3) | `verification_failed`, outcome `unavailable`, last code | no | submit again later |
| Definitive failure | attempt limit reached (five; V1-2.3 implements five, for the owner's confirmation) | `verification_failed`, outcome `unavailable`, last code | no | submit again later |
| Core change | release that changes rules or reader | rounds withdrawn by the release migration | no | submit again |
- Withdrawal is always available: the submitter or any editor withdraws a
@@ -1695,7 +1705,7 @@ of the document's JSON text in one form, the same for every layer:
|---|---|---|---|
| M4 `sheet_access_hardening` | V1-2.1 | `anatomical_catalog_grants` and its RPCs; `has_mfa`, `grant_active`, `caller_has`; `can_read_official_catalog` and the reader row predicate; `can_edit_sheet` redefined (F14); AR-1 B on the platform role RPCs and the private write functions (F19, §5.7), F17, F18; F1, F2, F3 (fork closed), F5, F6, F8, F9, F12 (every catalogue table), F13, F15; asset-row immutability trigger (F16); historical-sheet protection trigger (§14.2); reader column grants narrowed; personal creation and visibility changes refused | no row changes |
| M5 `sheet_review_workflow` | V1-2.1 | version columns `revision`, `authors`, `source_version_id`, `published_review_id`, `document_fingerprint`; sheet column `working_copy_source_version_id`; revision, author and freeze triggers, the historical-sheet write rule; extended immutability guard (§6.8); rounds, comments, acknowledgments; `create_official_sheet`, `create_sheet_draft` adapted, `save_sheet_draft`, submit, withdraw, comment, acknowledge, decide, publish; `create_sheet_working_copy`; species RPCs; catalogue and version read RPCs; upload: `register_sheet_asset` extended, `confirm_sheet_asset_upload` with the storage check (F7), INSERT policy, bucket limit 2 MiB; mirror removal and status check (§12.2); superseded signatures dropped; the content-size CHECK replaced by the text measure (`octet_length(content::text)`, §12.2) | new columns take their defaults on the equine v1 row (`revision` 0, empty author set); its document, status, number and assets unchanged; the new size CHECK is validated against the existing rows when M5 is applied (the equine document measures 184 105 bytes as `content::text`, measured on the sandbox); bucket limit lowered; no round, no grant |
| M6 `sheet_verification_jobs` | V1-2.3 | worker RPCs (claim, input, complete with the verdict structure check, fail), service role only | none |
| M6 `sheet_verification_jobs` | V1-2.3 | worker RPCs (claim, input, complete with the verdict structure check, fail), service role only; written as `20261101100000_sheet_verification_jobs.sql`, pgTAP `021`, rehearsed on the sandbox from the state before M4 (M4 to M6 in one `migration up`) and from the state before M6 | none |
Each migration ships its pgTAP file (allowed and denied cases), regenerated
`database.types.ts`, a `db:sandbox up upgrade` run from the DEV state (with a
@@ -2154,6 +2164,7 @@ V1-2.7 on.
verification time at the caps within budget.
- Rollback: branch revert; the worker image exists on the sandbox only.
- Checkpoint: owner validates the server workflow (V1-2.1 to V1-2.3).
- State 2026-11-01: built and tested on the sandbox (RUST.md §13); DEV untouched.
### 16.5 V1-2.4 Wireframes (parallel to V1-2.1 to V1-2.3)