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

New Issue

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

jcwalker3 commented

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

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

Parents: #820, #832. Depends on: #833 (domains/membership generation), #834 (config generations/current evidence).

1. Summary / objective

Define and implement the mutation-safety contract: an authoritative physical observation bound to the protected mutation, and a race-free probe/record protocol under the exclusion domain.

2. Security/correctness problem

DB checks of recorded generation/status/expiry cannot detect an external filesystem/mount/symlink change after a clean probe. If immediate ineligibility is required, an authoritative physical observation must occur at the mutation-sensitive use and be bound to that mutation. Two probes racing before the domain lock can both observe a clean pre-change state.

3. Threat model / failure modes

Drift between probe and use; probe/record race producing two clean records for overlapping workspaces; stale membership generation; probe timeout/crash mid-verify; cross-domain lock ordering deadlock.

4. In-scope behavior — explicit mutation-safety contract

Perform an authoritative physical observation at every mutation-sensitive use if immediate ineligibility is required; do not claim immediate invalidation from periodic expiry alone. Bind the observation to the protected mutation (observed-state fingerprint recorded with the mutation intent). [RUNTIME-ADAPTER] observation + [SCHEMA] binding.
Race-free protocol — one of: (a) lock the exclusion domain before physical observation and hold through recording + current selection; or (b) capture membership generation, lock during finalization, verify generation unchanged, retry probe if it changed. [SCHEMA] lock/generation + [TRUSTED-SERVICE] orchestration.
Observed-state fingerprint; lock ordering (deterministic across domains); cross-domain operations; probe timeout; crash behavior; retry/conflict results; domain split/merge/retirement interactions; parallelism between proven-isolated domains; evidence update + audit.

5. Exclusions

No global identity registration (→ #833), no verified-evidence schema (→ #834), no retirement fencing (→ lifecycle child).

6. Schema/operation contracts

domain_locks / membership-generation columns from #833; mutation_observation_fingerprints. Operations: probe_workspace, record_workspace_verification (extends #834 with the lock/generation protocol), bind_observation_to_mutation.

7. SQLite behavior

BEGIN IMMEDIATE + a domain-lock row; option (b) re-checks membership generation after acquiring the lock and retries the probe if changed.

8. PostgreSQL behavior

SELECT … FOR UPDATE on the exclusion-domain row; SERIALIZABLE retry; advisory lock for cross-domain ordering.

9. Concurrency / transaction requirements

Two probes of overlapping workspaces cannot both finalize clean: the second observes a changed membership generation (or is blocked by the domain lock) and retries; proven-isolated domains may proceed in parallel.

10. Structured results

OBSERVED_CLEAN, OBSERVED_DRIFT, PROBE_TIMEOUT, PROBE_CRASHED, DOMAIN_LOCK_CONFLICT, GENERATION_CHANGED_RETRY, MUTATION_BOUND.

11. Enforcement classification

Physical observation [RUNTIME-ADAPTER]; domain lock + membership generation + fingerprint binding [SCHEMA]; orchestration/timeout [TRUSTED-SERVICE].

12. Acceptance criteria

Mutation-sensitive use performs an authoritative observation bound to the mutation when immediate ineligibility is required.
Immediate invalidation is not claimed from expiry alone.
The probe/record race cannot produce two clean records for overlapping workspaces.
Domain lock/generation protocol is executable and deterministic.
Proven-isolated domains run in parallel.
Probe timeout/crash yields a structured result, not a stale clean record.

13. Named tests

t_action_time_drift(−), t_probe_record_race(concurrency), t_generation_changed_retry(concurrency), t_cross_domain_lock_order(concurrency), t_isolated_domain_parallel(+), t_probe_timeout(−), t_probe_crash(−), t_observation_bound_to_mutation(+).

14. Audit events / evidence

workspace_probed, observation_bound, probe_conflict. Test output evidence.

15. Dependencies / parent

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

16. Definition of done

Executable SQLite (+PG) with a real probe adapter (or a deterministic test double whose contract matches the adapter); ACs pass incl. race + drift; bounded PR; no self-review/merge.

17. Known limitations / deferred

Physical observation is [RUNTIME-ADAPTER]; a bounded staleness window is acceptable only if explicitly stated and never described as immediate. Retirement fencing → lifecycle child.

**Candidate architecture requiring executable validation; not yet approved, production-ready, or certified.** Parents: #820, #832. Depends on: #833 (domains/membership generation), #834 (config generations/current evidence). ## 1. Summary / objective Define and implement the mutation-safety contract: an authoritative physical observation bound to the protected mutation, and a race-free probe/record protocol under the exclusion domain. ## 2. Security/correctness problem DB checks of recorded generation/status/expiry cannot detect an external filesystem/mount/symlink change after a clean probe. If immediate ineligibility is required, an authoritative physical observation must occur at the mutation-sensitive use and be bound to that mutation. Two probes racing before the domain lock can both observe a clean pre-change state. ## 3. Threat model / failure modes Drift between probe and use; probe/record race producing two clean records for overlapping workspaces; stale membership generation; probe timeout/crash mid-verify; cross-domain lock ordering deadlock. ## 4. In-scope behavior — explicit mutation-safety contract - Perform an authoritative physical observation at **every mutation-sensitive use** if immediate ineligibility is required; do **not** claim immediate invalidation from periodic expiry alone. Bind the observation to the protected mutation (observed-state fingerprint recorded with the mutation intent). `[RUNTIME-ADAPTER]` observation + `[SCHEMA]` binding. - Race-free protocol — one of: (a) lock the exclusion domain **before** physical observation and hold through recording + current selection; or (b) capture membership generation, lock during finalization, verify generation unchanged, retry probe if it changed. `[SCHEMA]` lock/generation + `[TRUSTED-SERVICE]` orchestration. - Observed-state fingerprint; lock ordering (deterministic across domains); cross-domain operations; probe timeout; crash behavior; retry/conflict results; domain split/merge/retirement interactions; parallelism between proven-isolated domains; evidence update + audit. ## 5. Exclusions No global identity registration (→ #833), no verified-evidence schema (→ #834), no retirement fencing (→ lifecycle child). ## 6. Schema/operation contracts `domain_locks` / membership-generation columns from #833; `mutation_observation_fingerprints`. Operations: `probe_workspace`, `record_workspace_verification` (extends #834 with the lock/generation protocol), `bind_observation_to_mutation`. ## 7. SQLite behavior `BEGIN IMMEDIATE` + a domain-lock row; option (b) re-checks membership generation after acquiring the lock and retries the probe if changed. ## 8. PostgreSQL behavior `SELECT … FOR UPDATE` on the exclusion-domain row; `SERIALIZABLE` retry; advisory lock for cross-domain ordering. ## 9. Concurrency / transaction requirements Two probes of overlapping workspaces cannot both finalize clean: the second observes a changed membership generation (or is blocked by the domain lock) and retries; proven-isolated domains may proceed in parallel. ## 10. Structured results `OBSERVED_CLEAN`, `OBSERVED_DRIFT`, `PROBE_TIMEOUT`, `PROBE_CRASHED`, `DOMAIN_LOCK_CONFLICT`, `GENERATION_CHANGED_RETRY`, `MUTATION_BOUND`. ## 11. Enforcement classification Physical observation `[RUNTIME-ADAPTER]`; domain lock + membership generation + fingerprint binding `[SCHEMA]`; orchestration/timeout `[TRUSTED-SERVICE]`. ## 12. Acceptance criteria 1. Mutation-sensitive use performs an authoritative observation bound to the mutation when immediate ineligibility is required. 2. Immediate invalidation is not claimed from expiry alone. 3. The probe/record race cannot produce two clean records for overlapping workspaces. 4. Domain lock/generation protocol is executable and deterministic. 5. Proven-isolated domains run in parallel. 6. Probe timeout/crash yields a structured result, not a stale clean record. ## 13. Named tests `t_action_time_drift`(−), `t_probe_record_race`(concurrency), `t_generation_changed_retry`(concurrency), `t_cross_domain_lock_order`(concurrency), `t_isolated_domain_parallel`(+), `t_probe_timeout`(−), `t_probe_crash`(−), `t_observation_bound_to_mutation`(+). ## 14. Audit events / evidence `workspace_probed`, `observation_bound`, `probe_conflict`. Test output evidence. ## 15. Dependencies / parent Parents #820, #832; depends #833, #834. ## 16. Definition of done Executable SQLite (+PG) with a real probe adapter (or a deterministic test double whose contract matches the adapter); ACs pass incl. race + drift; bounded PR; no self-review/merge. ## 17. Known limitations / deferred Physical observation is `[RUNTIME-ADAPTER]`; a bounded staleness window is acceptable only if explicitly stated and never described as immediate. Retirement fencing → lifecycle child.

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

jcwalker3 referenced this issue

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

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