ARCH-04 — Workspace configuration generations, immutable history, and current-evidence integrity #834

New Issue

2026-07-22T19:49:27-05:00

jcwalker3 commented

2026-07-22 19:49:27 -05:00

Candidate architecture requiring executable validation; not yet approved, production-ready, or certified.

Parents: #820, #832. Depends on: #833 (global identities).

1. Summary / objective

Implement workspace configuration generations with immutable history and a valid current-evidence integrity model: status='verified' requires a same-binding, clean, current-generation, unexpired evidence row via a literal-free composite foreign key plus explicit predicates.

2. Security/correctness problem

A stale clean scan must not remain "current" after the workspace's storage/path/node/volume/domain changes. The prior candidate used an invalid FK containing a literal 1; it must use real child columns, and verified must require non-null evidence, clean flag, generation agreement, unexpired evidence, and live-object joins.

3. Threat model / failure modes

Old clean evidence reselected after a change; NULL child columns satisfying a composite FK; direct generation edits; unverified binding retaining a stale current pointer; evidence expiry ignored.

4. In-scope behavior

First valid generation = 1 (justify if an alternative is adopted). Initial binding + config-history row inserted atomically. [SCHEMA].
Immutable workspace_config_history (per generation: storage_identity, registered_path, node_id/shared_volume_id, node/volume incarnation, exclusion_domain_id, exclusion_domain_generation). Direct generation edits prevented. [SCHEMA].
Config-bump transaction: on change to any bound value → increment current_config_generation, append history, status='fenced', clear current-evidence pointer + clean flag; defined pointer-clearing/fencing order and rollback. [SCHEMA] trigger.
Evidence parent candidate key UNIQUE(workspace_binding_id, evidence_row_id, is_clean, workspace_config_generation) with is_clean a stored/generated column; current-evidence FK uses real child columns (current_verification_evidence_id, current_evidence_is_clean, current_config_generation) — never a literal. [SCHEMA].
status='verified' requires: non-null evidence id, current_evidence_is_clean=1, non-null current generation matching, unexpired eligible evidence, and required live-object joins (node/volume/domain/supervisor status). CHECK enforces the first three; the live joins + expiry are use-time [SCHEMA] joins (+ [RUNTIME-ADAPTER] physical reprobe from the probing child).
Unverified status clears current pointer fields (stale pointers never read as authority).
Evidence subject binds every security-relevant observed value incl. node/volume incarnation and exclusion-domain generation (subject schema from #825/#833).

5. Exclusions

No probe/record race protocol (→ probing child), no retirement fencing cascade (→ lifecycle child), no global identity registration (→ #833).

6. Schema/operation contracts

workspace_bindings, workspace_config_history, workspace_verification_evidence. Operations: register_workspace_binding, record_workspace_verification (supervisor.verify), bump_workspace_config, fence_binding.

7. SQLite behavior

Composite FK with real child columns; is_clean generated column; BEGIN IMMEDIATE for bump; CHECK for verified predicates.

8. PostgreSQL behavior

Same constraints; generated column; FOR UPDATE on the binding row during bump; parity tested.

9. Concurrency / transaction requirements

A verification concurrent with a config bump cannot leave a verified pointer at a superseded generation; bump fences and clears atomically.

10. Structured results

VERIFIED, FENCED, VERIFICATION_REQUIRES_CLEAN_CURRENT_EVIDENCE, GENERATION_MISMATCH, EVIDENCE_EXPIRED, STALE_POINTER_CLEARED.

11. Enforcement classification

Composite FK (identity+cleanliness+generation), verified predicates, immutable history, bump-fencing [SCHEMA]; expiry/live-object ineligibility partly [SCHEMA] join + [RUNTIME-ADAPTER] reprobe (probing child).

12. Acceptance criteria

First generation is 1; initial binding+history atomic.
Config history immutable; direct generation edits rejected.
Bump increments generation, appends history, fences, clears pointer — atomically.
Current-evidence FK uses real child columns (no literal) and matches a clean row at the current generation.
verified requires non-null evidence id, clean flag, matching generation, unexpired evidence, live-object joins.
Unverified status clears current pointer fields.
The FK proves row identity, cleanliness, and generation only — expiry/authority are separate joins (not overstated).

13. Named tests

t_initial_generation(+), t_config_history_immutable(raw-bypass), t_bump_fences_and_clears(+), t_current_evidence_fk_clean(−), t_verified_predicates(−), t_unverified_clears_pointer(+), t_stale_generation_pointer(−), t_expired_evidence(−).

14. Audit events / evidence

workspace_verified, workspace_config_bumped, workspace_fenced. Test output evidence.

15. Dependencies / parent

Parents #820, #832; depends #833; consumes evidence subjects from #825.

16. Definition of done

Executable SQLite (+PG); ACs pass incl. raw-bypass; bounded PR; no self-review/merge.

17. Known limitations / deferred

External drift with no DB change + probe/record race → probing child. Retirement fencing → lifecycle child.

**Candidate architecture requiring executable validation; not yet approved, production-ready, or certified.** Parents: #820, #832. Depends on: #833 (global identities). ## 1. Summary / objective Implement workspace configuration generations with immutable history and a valid current-evidence integrity model: `status='verified'` requires a same-binding, clean, current-generation, unexpired evidence row via a literal-free composite foreign key plus explicit predicates. ## 2. Security/correctness problem A stale clean scan must not remain "current" after the workspace's storage/path/node/volume/domain changes. The prior candidate used an invalid FK containing a literal `1`; it must use real child columns, and `verified` must require non-null evidence, clean flag, generation agreement, unexpired evidence, and live-object joins. ## 3. Threat model / failure modes Old clean evidence reselected after a change; NULL child columns satisfying a composite FK; direct generation edits; unverified binding retaining a stale current pointer; evidence expiry ignored. ## 4. In-scope behavior - First valid generation = **1** (justify if an alternative is adopted). Initial binding + config-history row inserted atomically. `[SCHEMA]`. - Immutable `workspace_config_history` (per generation: storage_identity, registered_path, node_id/shared_volume_id, node/volume incarnation, exclusion_domain_id, exclusion_domain_generation). Direct generation edits prevented. `[SCHEMA]`. - Config-bump transaction: on change to any bound value → increment `current_config_generation`, append history, `status='fenced'`, clear current-evidence pointer + clean flag; defined pointer-clearing/fencing order and rollback. `[SCHEMA]` trigger. - Evidence parent candidate key `UNIQUE(workspace_binding_id, evidence_row_id, is_clean, workspace_config_generation)` with `is_clean` a stored/generated column; current-evidence FK uses **real child columns** (`current_verification_evidence_id`, `current_evidence_is_clean`, `current_config_generation`) — never a literal. `[SCHEMA]`. - `status='verified'` requires: non-null evidence id, `current_evidence_is_clean=1`, non-null current generation matching, unexpired eligible evidence, and required live-object joins (node/volume/domain/supervisor status). CHECK enforces the first three; the live joins + expiry are use-time `[SCHEMA]` joins (+ `[RUNTIME-ADAPTER]` physical reprobe from the probing child). - Unverified status clears current pointer fields (stale pointers never read as authority). - Evidence subject binds every security-relevant observed value incl. node/volume incarnation and exclusion-domain generation (subject schema from #825/#833). ## 5. Exclusions No probe/record race protocol (→ probing child), no retirement fencing cascade (→ lifecycle child), no global identity registration (→ #833). ## 6. Schema/operation contracts `workspace_bindings`, `workspace_config_history`, `workspace_verification_evidence`. Operations: `register_workspace_binding`, `record_workspace_verification` (supervisor.verify), `bump_workspace_config`, `fence_binding`. ## 7. SQLite behavior Composite FK with real child columns; `is_clean` generated column; `BEGIN IMMEDIATE` for bump; CHECK for verified predicates. ## 8. PostgreSQL behavior Same constraints; generated column; `FOR UPDATE` on the binding row during bump; parity tested. ## 9. Concurrency / transaction requirements A verification concurrent with a config bump cannot leave a verified pointer at a superseded generation; bump fences and clears atomically. ## 10. Structured results `VERIFIED`, `FENCED`, `VERIFICATION_REQUIRES_CLEAN_CURRENT_EVIDENCE`, `GENERATION_MISMATCH`, `EVIDENCE_EXPIRED`, `STALE_POINTER_CLEARED`. ## 11. Enforcement classification Composite FK (identity+cleanliness+generation), verified predicates, immutable history, bump-fencing `[SCHEMA]`; expiry/live-object ineligibility partly `[SCHEMA]` join + `[RUNTIME-ADAPTER]` reprobe (probing child). ## 12. Acceptance criteria 1. First generation is 1; initial binding+history atomic. 2. Config history immutable; direct generation edits rejected. 3. Bump increments generation, appends history, fences, clears pointer — atomically. 4. Current-evidence FK uses real child columns (no literal) and matches a clean row at the current generation. 5. `verified` requires non-null evidence id, clean flag, matching generation, unexpired evidence, live-object joins. 6. Unverified status clears current pointer fields. 7. The FK proves row identity, cleanliness, and generation only — expiry/authority are separate joins (not overstated). ## 13. Named tests `t_initial_generation`(+), `t_config_history_immutable`(raw-bypass), `t_bump_fences_and_clears`(+), `t_current_evidence_fk_clean`(−), `t_verified_predicates`(−), `t_unverified_clears_pointer`(+), `t_stale_generation_pointer`(−), `t_expired_evidence`(−). ## 14. Audit events / evidence `workspace_verified`, `workspace_config_bumped`, `workspace_fenced`. Test output evidence. ## 15. Dependencies / parent Parents #820, #832; depends #833; consumes evidence subjects from #825. ## 16. Definition of done Executable SQLite (+PG); ACs pass incl. raw-bypass; bounded PR; no self-review/merge. ## 17. Known limitations / deferred External drift with no DB change + probe/record race → probing child. Retirement fencing → lifecycle child.

jcwalker3 referenced this issue

2026-07-22 19:50:06 -05:00

ARCH-04 — Atomic workspace probing, overlap exclusion, and action-time drift detection #835

jcwalker3 referenced this issue

2026-07-22 19:50:43 -05:00

ARCH-04 — Workspace, node, volume, and domain retirement with dependent-resource fencing #836

jcwalker3 referenced this issue

2026-07-22 19:51:24 -05:00

Architecture acceptance matrix — invariant, test, evidence, and backend traceability #837

jcwalker3 referenced this issue

2026-07-22 20:04:09 -05:00

Architecture program — role-delivery-reliability control plane #820