ARCH-01 Foundation Slice A — Atomic platform installation and authority kernel #822

New Issue

2026-07-22T19:40:54-05:00

jcwalker3 commented

2026-07-22 19:40:54 -05:00

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

Parents: #820, #821. First implementation leaf. SQLite-first. PostgreSQL parity is a separate issue.

1. Summary / objective

Implement the smallest executable ARCH-01 foundation: a connection-bound authenticated actor context, an immutable authority lattice, the principal-equivalence root, and a single-transaction platform installation that seeds the initial platform.bootstrap grant and an immutable installed marker. Everything else (evidence, bindings, workspaces) is out of scope.

2. Security/correctness problem

Without an authenticated caller bound to each mutation, any writer can assert another principal's authority. Without an atomic install with an immutable finalized marker, a partial/replayed install can seed a forged authority root. This slice establishes the trust root all later authority checks depend on.

3. Threat model / failure modes

Caller naming a foreign principal in an actor column; missing/stale/replaced connection context; raw-write bypass of triggers; two concurrent installs; revocation racing to zero active grants; post-install mutation of bootstrap artifacts; a principal with no equivalence class.

4. In-scope behavior

Connection-registered scalar actor functions: cp_actor_principal(), cp_actor_kind(), cp_operation_mode(), cp_service_session(), cp_context_epoch(). SQL may read but cannot set them. [TRUSTED-SERVICE] authenticity.
Trigger actor protocol on every mutating trigger: read cp_context_epoch(), read fields, re-read epoch, abort unless equal+non-null+bound to the active request/transaction; abort if any field absent/malformed/expired/unauthorized. [SCHEMA] (fail-closed abort).
operation_mode ∈ {normal,install,merge,internal_service} closed enum; actor_kind ∈ {operator,supervisor,service,installer}.
principal_equivalence_classes created before its initial principal; principals.current_class_id NOT NULL FK. [SCHEMA].
authority_dominance immutable lattice, exact seeded tuple set: (platform.bootstrap,platform.bootstrap), (platform.bootstrap,project.admin), (platform.bootstrap,supervisor.root.establish), (supervisor.root,supervisor.register), (supervisor.root,supervisor.verify), (supervisor.root,supervisor.recover). [SCHEMA].
authoritative_issuers with UNIQUE(issuer_kind,issuer_id); installer bootstrap: insert installer principal with temporary NULL issuer (gated to install mode, installer only) → insert distinguished operator-key issuer → update installer to reference it. [SCHEMA] + [TRUSTED-SERVICE] mode gate.
Single atomic install transaction: SQLite BEGIN IMMEDIATE; check no install marker; class → installer principal → issuer → installer update → dominance tuples → platform_bootstrap_seed → initial platform_bootstrap_grants(granted_by NULL, active) → platform_active_invariant(1,1) → install_state('installed') last.
install_state BEFORE INSERT trigger validates each required dominance tuple individually (reject missing/additional/malformed), the seed↔installer link, exactly one active NULL-grantor grant for the installer, installer issuer non-NULL, no extra principal created under the exception. [SCHEMA].
Immutability triggers on: install_state, platform_bootstrap_seed, distinguished issuer identity, installer registration fields, initial-grant identity, authority_dominance. Reject UPDATE/DELETE. [SCHEMA].
require_installed on every privileged table: abort when no marker and mode≠install. [SCHEMA].
Serialized grant/revoke on the singleton platform_active_invariant row; revoke rejected if it would drop active_count below 1. [SCHEMA] + [TRUSTED-SERVICE] serialization via BEGIN IMMEDIATE.
Audit rows for install, grant, revoke; audit_records append-only (reject UPDATE/DELETE). [SCHEMA].

5. Exclusions

No evidence stores/attestations, no repository bindings, no transports beyond what the distinguished issuer needs, no workspaces, no PostgreSQL, no ARCH-02/04, no principal merge operation body (only the class root + NOT NULL FK; full merge is a separate issue).

6. Schema/operation contracts

Tables: principals, principal_equivalence_classes, authoritative_issuers, authority_dominance, platform_bootstrap_seed, platform_bootstrap_grants, platform_active_invariant, install_state, audit_records, plus connection actor functions. Operations: install_platform, grant_platform_bootstrap, revoke_platform_bootstrap, register_principal (class+principal atomic). (Full candidate DDL exists in the design baseline but is unexecuted and contains defects; implement the intended semantics and correct on execution.)

7. SQLite behavior

BEGIN IMMEDIATE before the install-state check serializes concurrent installs; the loser rechecks and returns ALREADY_INSTALLED. Self-FK (registered_by = own id) resolves at statement end. Missing actor function ⇒ no such function ⇒ abort.

8. PostgreSQL behavior

Out of scope here; tracked in the PostgreSQL service-boundary issue. Do not claim parity.

9. Concurrency / transaction requirements

One atomic install transaction; no durable installing phase; no resume path — crash before commit leaves nothing. Grant succession serialized on the invariant row (full succession semantics deferred to its own issue; this slice implements only last-grant protection + basic grant/revoke).

10. Structured results

INSTALLED, ALREADY_INSTALLED, INVALID_ACTOR_CONTEXT, INVALID_BOOTSTRAP_STATE, DOMINANCE_SET_MISMATCH, AUTHORIZATION_DENIED, CONCURRENT_INSTALLATION_LOST.

11. Enforcement classification

Context authenticity [TRUSTED-SERVICE]; fail-closed aborts, dominance/immutability/NOT-NULL-class/last-grant [SCHEMA]; no [RUNTIME-ADAPTER] in this slice.

12. Acceptance criteria (numbered)

Clean install succeeds → INSTALLED, marker present.
Second install → ALREADY_INSTALLED, no mutation.
Failure at any install stage rolls back the whole transaction (no partial rows).
Missing/additional/malformed dominance tuple → DOMINANCE_SET_MISMATCH, no marker.
No durable partial install after rollback.
A principal cannot exist without a current class (NOT NULL FK).
Temporary NULL issuer applies only to the installer during install; any other NULL-issuer principal is rejected.
Missing/stale/inconsistent actor context → INVALID_ACTOR_CONTEXT, fail closed.
Bootstrap artifacts cannot be updated/deleted post-install.
Two concurrent installs → one INSTALLED, one CONCURRENT_INSTALLATION_LOST/ALREADY_INSTALLED.
Two concurrent revocations cannot remove the final active grant.
Raw-write bypass attempts (direct INSERT/UPDATE/DELETE) fail.
Audit rows created for successful security-sensitive operations.
Audit rows cannot be altered/deleted.

13. Named tests

t_install_clean(+), t_install_twice(−), t_install_stage_rollback(rollback, one per stage), t_dominance_missing/t_dominance_extra/t_dominance_malformed(−), t_no_partial_after_rollback(rollback), t_principal_no_class(−), t_nonobstaller_null_issuer(−), t_context_missing/t_context_stale/t_context_epoch_shift(−), t_bootstrap_immutable_{update,delete}(raw-bypass), t_concurrent_install(concurrency), t_concurrent_last_grant_revoke(concurrency/write-skew), t_raw_write_bypass(raw-bypass), t_audit_created(+), t_audit_immutable(raw-bypass).

14. Required audit events / evidence

platform_installed, platform_grant_created, platform_grant_revoked, principal_registered. Migration must execute against a fresh SQLite DB; test run output is the durable evidence.

15. Dependencies / parent

Parents #820, #821. No dependency on other leaves.

16. Definition of done

Migration executes on a fresh SQLite DB; ACs 1–14 pass including negative/rollback/raw-write/concurrency; no known silent authorization bypass; subsystem disabled by default until readiness checks pass; docs distinguish implemented vs planned; bounded PR against current authoritative base; author does not self-review/merge; every deferred contract has a linked follow-up.

17. Known limitations / deferred

Full grant succession (expiry/suspension/replacement) → grant-succession issue. Full merge semantics → principal-equivalence issue. Evidence, bindings, workspaces, PostgreSQL → their own issues. Candidate DDL is unexecuted and defect-bearing; execution is authoritative.

**Candidate architecture requiring executable validation; not yet approved, production-ready, or certified.** Parents: #820, #821. **First implementation leaf.** SQLite-first. PostgreSQL parity is a separate issue. ## 1. Summary / objective Implement the smallest executable ARCH-01 foundation: a connection-bound authenticated actor context, an immutable authority lattice, the principal-equivalence root, and a single-transaction platform installation that seeds the initial `platform.bootstrap` grant and an immutable `installed` marker. Everything else (evidence, bindings, workspaces) is out of scope. ## 2. Security/correctness problem Without an authenticated caller bound to each mutation, any writer can assert another principal's authority. Without an atomic install with an immutable finalized marker, a partial/replayed install can seed a forged authority root. This slice establishes the trust root all later authority checks depend on. ## 3. Threat model / failure modes Caller naming a foreign principal in an actor column; missing/stale/replaced connection context; raw-write bypass of triggers; two concurrent installs; revocation racing to zero active grants; post-install mutation of bootstrap artifacts; a principal with no equivalence class. ## 4. In-scope behavior - Connection-registered scalar actor functions: `cp_actor_principal()`, `cp_actor_kind()`, `cp_operation_mode()`, `cp_service_session()`, `cp_context_epoch()`. SQL may read but cannot set them. `[TRUSTED-SERVICE]` authenticity. - Trigger actor protocol on every mutating trigger: read `cp_context_epoch()`, read fields, re-read epoch, abort unless equal+non-null+bound to the active request/transaction; abort if any field absent/malformed/expired/unauthorized. `[SCHEMA]` (fail-closed abort). - `operation_mode ∈ {normal,install,merge,internal_service}` closed enum; `actor_kind ∈ {operator,supervisor,service,installer}`. - `principal_equivalence_classes` created **before** its initial principal; `principals.current_class_id` NOT NULL FK. `[SCHEMA]`. - `authority_dominance` immutable lattice, exact seeded tuple set: `(platform.bootstrap,platform.bootstrap)`, `(platform.bootstrap,project.admin)`, `(platform.bootstrap,supervisor.root.establish)`, `(supervisor.root,supervisor.register)`, `(supervisor.root,supervisor.verify)`, `(supervisor.root,supervisor.recover)`. `[SCHEMA]`. - `authoritative_issuers` with `UNIQUE(issuer_kind,issuer_id)`; installer bootstrap: insert installer principal with temporary NULL issuer (gated to install mode, installer only) → insert distinguished operator-key issuer → update installer to reference it. `[SCHEMA]` + `[TRUSTED-SERVICE]` mode gate. - Single atomic install transaction: SQLite `BEGIN IMMEDIATE`; check no install marker; class → installer principal → issuer → installer update → dominance tuples → `platform_bootstrap_seed` → initial `platform_bootstrap_grants(granted_by NULL, active)` → `platform_active_invariant(1,1)` → `install_state('installed')` **last**. - `install_state` `BEFORE INSERT` trigger validates **each** required dominance tuple individually (reject missing/additional/malformed), the seed↔installer link, exactly one active NULL-grantor grant for the installer, installer issuer non-NULL, no extra principal created under the exception. `[SCHEMA]`. - Immutability triggers on: `install_state`, `platform_bootstrap_seed`, distinguished issuer identity, installer registration fields, initial-grant identity, `authority_dominance`. Reject UPDATE/DELETE. `[SCHEMA]`. - `require_installed` on every privileged table: abort when no marker and mode≠install. `[SCHEMA]`. - Serialized grant/revoke on the singleton `platform_active_invariant` row; revoke rejected if it would drop active_count below 1. `[SCHEMA]` + `[TRUSTED-SERVICE]` serialization via `BEGIN IMMEDIATE`. - Audit rows for install, grant, revoke; `audit_records` append-only (reject UPDATE/DELETE). `[SCHEMA]`. ## 5. Exclusions No evidence stores/attestations, no repository bindings, no transports beyond what the distinguished issuer needs, no workspaces, no PostgreSQL, no ARCH-02/04, no principal merge operation body (only the class root + NOT NULL FK; full merge is a separate issue). ## 6. Schema/operation contracts Tables: `principals`, `principal_equivalence_classes`, `authoritative_issuers`, `authority_dominance`, `platform_bootstrap_seed`, `platform_bootstrap_grants`, `platform_active_invariant`, `install_state`, `audit_records`, plus connection actor functions. Operations: `install_platform`, `grant_platform_bootstrap`, `revoke_platform_bootstrap`, `register_principal` (class+principal atomic). (Full candidate DDL exists in the design baseline but is unexecuted and contains defects; implement the intended semantics and correct on execution.) ## 7. SQLite behavior `BEGIN IMMEDIATE` before the install-state check serializes concurrent installs; the loser rechecks and returns `ALREADY_INSTALLED`. Self-FK (`registered_by = own id`) resolves at statement end. Missing actor function ⇒ `no such function` ⇒ abort. ## 8. PostgreSQL behavior Out of scope here; tracked in the PostgreSQL service-boundary issue. Do not claim parity. ## 9. Concurrency / transaction requirements One atomic install transaction; no durable `installing` phase; no resume path — crash before commit leaves nothing. Grant succession serialized on the invariant row (full succession semantics deferred to its own issue; this slice implements only last-grant protection + basic grant/revoke). ## 10. Structured results `INSTALLED`, `ALREADY_INSTALLED`, `INVALID_ACTOR_CONTEXT`, `INVALID_BOOTSTRAP_STATE`, `DOMINANCE_SET_MISMATCH`, `AUTHORIZATION_DENIED`, `CONCURRENT_INSTALLATION_LOST`. ## 11. Enforcement classification Context authenticity `[TRUSTED-SERVICE]`; fail-closed aborts, dominance/immutability/NOT-NULL-class/last-grant `[SCHEMA]`; no `[RUNTIME-ADAPTER]` in this slice. ## 12. Acceptance criteria (numbered) 1. Clean install succeeds → `INSTALLED`, marker present. 2. Second install → `ALREADY_INSTALLED`, no mutation. 3. Failure at any install stage rolls back the whole transaction (no partial rows). 4. Missing/additional/malformed dominance tuple → `DOMINANCE_SET_MISMATCH`, no marker. 5. No durable partial install after rollback. 6. A principal cannot exist without a current class (NOT NULL FK). 7. Temporary NULL issuer applies only to the installer during install; any other NULL-issuer principal is rejected. 8. Missing/stale/inconsistent actor context → `INVALID_ACTOR_CONTEXT`, fail closed. 9. Bootstrap artifacts cannot be updated/deleted post-install. 10. Two concurrent installs → one `INSTALLED`, one `CONCURRENT_INSTALLATION_LOST`/`ALREADY_INSTALLED`. 11. Two concurrent revocations cannot remove the final active grant. 12. Raw-write bypass attempts (direct INSERT/UPDATE/DELETE) fail. 13. Audit rows created for successful security-sensitive operations. 14. Audit rows cannot be altered/deleted. ## 13. Named tests `t_install_clean`(+), `t_install_twice`(−), `t_install_stage_rollback`(rollback, one per stage), `t_dominance_missing`/`t_dominance_extra`/`t_dominance_malformed`(−), `t_no_partial_after_rollback`(rollback), `t_principal_no_class`(−), `t_nonobstaller_null_issuer`(−), `t_context_missing`/`t_context_stale`/`t_context_epoch_shift`(−), `t_bootstrap_immutable_{update,delete}`(raw-bypass), `t_concurrent_install`(concurrency), `t_concurrent_last_grant_revoke`(concurrency/write-skew), `t_raw_write_bypass`(raw-bypass), `t_audit_created`(+), `t_audit_immutable`(raw-bypass). ## 14. Required audit events / evidence `platform_installed`, `platform_grant_created`, `platform_grant_revoked`, `principal_registered`. Migration must execute against a fresh SQLite DB; test run output is the durable evidence. ## 15. Dependencies / parent Parents #820, #821. No dependency on other leaves. ## 16. Definition of done Migration executes on a fresh SQLite DB; ACs 1–14 pass including negative/rollback/raw-write/concurrency; no known silent authorization bypass; subsystem disabled by default until readiness checks pass; docs distinguish implemented vs planned; bounded PR against current authoritative base; author does not self-review/merge; every deferred contract has a linked follow-up. ## 17. Known limitations / deferred Full grant succession (expiry/suspension/replacement) → grant-succession issue. Full merge semantics → principal-equivalence issue. Evidence, bindings, workspaces, PostgreSQL → their own issues. Candidate DDL is unexecuted and defect-bearing; execution is authoritative.

jcwalker3 referenced this issue

2026-07-22 19:41:36 -05:00

ARCH-01 — Concurrency-safe platform.bootstrap grant succession #823

jcwalker3 referenced this issue

2026-07-22 19:42:25 -05:00

ARCH-01 — Principal equivalence classes, conflict detection, and serialized merges #824

jcwalker3 referenced this issue

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

ARCH-01 — Evidence attestations, typed subjects, digest binding, and immutability #825

jcwalker3 referenced this issue

2026-07-22 19:44:38 -05:00

ARCH-01 — PostgreSQL actor context, roles, privileges, and connection-pool safety #827