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

New Issue

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

jcwalker3 commented

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

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

Parents: #820, #832. Depends on: #833, #834, #835.

1. Summary / objective

Implement retirement/replacement of workspaces, node incarnations, volume incarnations, and exclusion domains, fencing dependent workspaces before authority changes become effective, and preserving historical evidence.

2. Security/correctness problem

If a global object is retired/replaced without first fencing dependents, a workspace verified against the old object could still authorize a mutation on storage that is gone or reassigned.

3. Threat model / failure modes

Mutation through a retired/replaced object; dependent workspace not fenced before authority change; concurrent lifecycle changes racing; historical evidence lost; stale-generation authority.

4. In-scope behavior

Workspace retirement/replacement; node-incarnation replacement; volume-incarnation replacement; domain split/merge/replacement/retirement. [SCHEMA] lifecycle.
Fence dependent workspaces before authority changes become effective: the retirement transaction sets dependents fenced and clears their current-verification pointers in the same transaction, then applies the authority change. [SCHEMA] trigger/order.
Preserve historical evidence (never deleted). Prevent mutations through retired/replaced objects (use-time joins). Serialize concurrent lifecycle changes. Supervisor authorization required.

5. Exclusions

No global registration (→ #833), no config-generation schema (→ #834), no probing (→ #835).

6. Schema/operation contracts

Extends #833/#834 with retirement operations. Operations: retire_workspace, replace_node_incarnation, replace_volume_incarnation, split_domain, merge_domain, retire_domain.

7. SQLite behavior

BEGIN IMMEDIATE; fence dependents then change authority; immutable-history preserved.

8. PostgreSQL behavior

FOR UPDATE on the object + dependents; SERIALIZABLE retry; parity tested.

9. Concurrency / transaction requirements

Concurrent lifecycle changes on one object serialize; a mutation attempted through a retiring object fences-first, so it never proceeds against stale authority.

10. Structured results

RETIRED, REPLACED, FENCED_DEPENDENTS, STALE_GENERATION, DEPENDENCY_CONFLICT, SERIALIZATION_RETRY, AUTHORITY_REQUIRED.

11. Enforcement classification

Fencing order, immutability, lifecycle keys [SCHEMA]; supervisor authority [SCHEMA] trigger; physical teardown [RUNTIME-ADAPTER] (out of scope for the DB guarantee).

12. Acceptance criteria

Retiring/replacing a global object fences dependent workspaces before the authority change effects.
Mutations through retired/replaced objects are rejected.
Historical evidence preserved.
Concurrent lifecycle changes serialize.
Supervisor authority required for every lifecycle op.
Structured fenced/retired/stale-generation/retry/dependency-conflict results returned.

13. Named tests

t_retire_fences_dependents(+), t_mutation_through_retired(−), t_history_preserved(+), t_concurrent_lifecycle(concurrency), t_lifecycle_authority(−), t_stale_generation_use(−).

14. Audit events / evidence

workspace_retired, incarnation_replaced, domain_retired, dependents_fenced. Test output evidence.

15. Dependencies / parent

Parents #820, #832; depends #833, #834, #835.

16. Definition of done

Executable SQLite (+PG); ACs pass incl. fencing-before-effect + concurrency; bounded PR; no self-review/merge.

17. Known limitations / deferred

Physical teardown of storage is out of the DB guarantee. Cross-node fencing depends on the single-node coordination constraint (program-level).

**Candidate architecture requiring executable validation; not yet approved, production-ready, or certified.** Parents: #820, #832. Depends on: #833, #834, #835. ## 1. Summary / objective Implement retirement/replacement of workspaces, node incarnations, volume incarnations, and exclusion domains, fencing dependent workspaces **before** authority changes become effective, and preserving historical evidence. ## 2. Security/correctness problem If a global object is retired/replaced without first fencing dependents, a workspace verified against the old object could still authorize a mutation on storage that is gone or reassigned. ## 3. Threat model / failure modes Mutation through a retired/replaced object; dependent workspace not fenced before authority change; concurrent lifecycle changes racing; historical evidence lost; stale-generation authority. ## 4. In-scope behavior - Workspace retirement/replacement; node-incarnation replacement; volume-incarnation replacement; domain split/merge/replacement/retirement. `[SCHEMA]` lifecycle. - **Fence dependent workspaces before authority changes become effective**: the retirement transaction sets dependents `fenced` and clears their current-verification pointers in the same transaction, then applies the authority change. `[SCHEMA]` trigger/order. - Preserve historical evidence (never deleted). Prevent mutations through retired/replaced objects (use-time joins). Serialize concurrent lifecycle changes. Supervisor authorization required. ## 5. Exclusions No global registration (→ #833), no config-generation schema (→ #834), no probing (→ #835). ## 6. Schema/operation contracts Extends #833/#834 with retirement operations. Operations: `retire_workspace`, `replace_node_incarnation`, `replace_volume_incarnation`, `split_domain`, `merge_domain`, `retire_domain`. ## 7. SQLite behavior `BEGIN IMMEDIATE`; fence dependents then change authority; immutable-history preserved. ## 8. PostgreSQL behavior `FOR UPDATE` on the object + dependents; `SERIALIZABLE` retry; parity tested. ## 9. Concurrency / transaction requirements Concurrent lifecycle changes on one object serialize; a mutation attempted through a retiring object fences-first, so it never proceeds against stale authority. ## 10. Structured results `RETIRED`, `REPLACED`, `FENCED_DEPENDENTS`, `STALE_GENERATION`, `DEPENDENCY_CONFLICT`, `SERIALIZATION_RETRY`, `AUTHORITY_REQUIRED`. ## 11. Enforcement classification Fencing order, immutability, lifecycle keys `[SCHEMA]`; supervisor authority `[SCHEMA]` trigger; physical teardown `[RUNTIME-ADAPTER]` (out of scope for the DB guarantee). ## 12. Acceptance criteria 1. Retiring/replacing a global object fences dependent workspaces before the authority change effects. 2. Mutations through retired/replaced objects are rejected. 3. Historical evidence preserved. 4. Concurrent lifecycle changes serialize. 5. Supervisor authority required for every lifecycle op. 6. Structured fenced/retired/stale-generation/retry/dependency-conflict results returned. ## 13. Named tests `t_retire_fences_dependents`(+), `t_mutation_through_retired`(−), `t_history_preserved`(+), `t_concurrent_lifecycle`(concurrency), `t_lifecycle_authority`(−), `t_stale_generation_use`(−). ## 14. Audit events / evidence `workspace_retired`, `incarnation_replaced`, `domain_retired`, `dependents_fenced`. Test output evidence. ## 15. Dependencies / parent Parents #820, #832; depends #833, #834, #835. ## 16. Definition of done Executable SQLite (+PG); ACs pass incl. fencing-before-effect + concurrency; bounded PR; no self-review/merge. ## 17. Known limitations / deferred Physical teardown of storage is out of the DB guarantee. Cross-node fencing depends on the single-node coordination constraint (program-level).

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

jcwalker3 referenced this issue

2026-07-22 20:12:52 -05:00

ARCH-04 — Workspace identity, verification, exclusion domains, and mutation safety #832