feat(config): installation minimal-subset — schema, adapters, core, render (CONFIGIMPL)

Implements the config minimal desired-state subset per the PASSED spec
docs/specs/2026-08-29_mosaic-config-minimal-subset.md (spec review PASS
deff617d, rev-code-02). Dependency gate honored: registry adapter is
an explicit stub; profile/role resolution and desired-roster generation
are notChecked. 26 test arms green.

docs/requirements/hierarchy-schema.md

@@ -72,6 +72,25 @@ example now lists the complete measured set, and the import analysis
 is extended to resolve literal dynamic `import()` routes, which two of
 the four members use.
 
+Amendment 1 (Ruling 4b, 2026-08-28): company visibility classes. The
+directory exists so one shared company can serve many users instead of
+each user creating a duplicate private company (Ruling 4b, webui-audit
+lane, ruled 2026-08-27). §2.1 gains a `visibility` column; §2.8 defines
+the two classes (`private`/`directory`), the directory's existence-only
+disclosure, and the pre-binding invariants for the deferred
+see-and-ask-to-join flow (no join-request surface is authorized here —
+its flow is a follow-up contract); §5.2's mutation
+enumeration gains the visibility change; §5.5 defines who may change
+visibility (platform admins, plus a company-CRUD capability whose
+definition is a follow-up amendment to contract 2 — until it ratifies,
+admin-only); §6.1 and §6.9 add the witnesses; §6.7's existence-oracle
+rule is scoped around the ratified directory carve-out. Top-level
+creation (contract 3 §5.2) is unchanged and always yields a private
+company. Upstream, SOT Amendment A2 (native-kanban-sot.md §9, this PR)
+expressly extends A1 §8.1.2 to admit the visibility column and A1
+§8.1.3 to admit the directory function — this contract relies on that
+amendment, not on a reinterpretation of A1.
+
 Scope: the tenancy/authorization structure record class — companies,
 estates, platform-projects, workspaces, hierarchy grants, their parentage,
 and constraints. Out of scope: the RBAC grant vocabulary and evaluation
@@ -86,8 +105,13 @@ legacy flat data (future work; see §1.3).
    AND `hierarchy_grants` (§3) — A1 includes hierarchy-level access grants
    in the class. Every rule addressed to "the class" in this contract
    (payload prohibition, mutation path, audit) binds all five tables. Class
-   rows carry parentage, naming, grant, and audit-linkage data only — never
+   rows carry parentage, naming, grant, audit-linkage, and visibility-class
-   task, plan, or any business/orchestration payload.
+   data only — never task, plan, or any business/orchestration payload.
+   Visibility (`companies.visibility`, §2.8) is admitted into that
+   enumeration by SOT Amendment A2 §9.1.1, which expressly extends A1
+   §8.1.2 for exactly this one column: it is disclosure data about the
+   class's own nodes — not a payload field, carries no business content,
+   and widens the payload prohibition for nothing else.
    References from business/orchestration rows into the class are limited
    to exactly one form: the canonical `workspace_id` tenancy column that
    REQ-TEN-001 requires on every canonical row, referencing
@@ -116,7 +140,9 @@ MUST NOT merge the two. (A rename of either remains an implementation-PR
 decision under A1; this contract pins only that they stay distinct tables.)
 
 1. `companies` — id (uuid pk), name, slug (unique per deployment),
-   created_at, updated_at. N per deployment (D2).
+   `visibility` (text NOT NULL, DEFAULT `private`, CHECK constrained to
+   exactly `private` | `directory`; semantics §2.8), created_at,
+   updated_at. N per deployment (D2).
 2. `estates` — id, name, slug, `company_id` NOT NULL →
    `companies.id` ON DELETE RESTRICT. Exactly one company per estate; a
    company holds any number of estates.
@@ -142,6 +168,31 @@ decision under A1; this contract pins only that they stay distinct tables.)
    free-form payload field. The columns declared in this section and §3
    are exhaustive: a class table's column set is exactly its declared set
    (verified per §6.2) — nothing else (A1 §8.1.2).
+8. **Company visibility classes (Ruling 4b).** Every company is exactly
+   one of two classes, carried by `visibility`:
+   - `private` (the default): the company is disclosed only to subjects
+     holding a grant on it or on a descendant — the resting state every
+     company is created in. Open creation under contract 3 §5.2
+     (Ruling 4) survives unchanged: it creates private companies.
+   - `directory`: the company is listed in the deployment-wide company
+     directory. Directory listing discloses **existence, name, and slug
+     to every authenticated user — nothing else**: no subtree structure,
+     no roll-up aggregates, no workspace content, no grant or membership
+     information.
+     Visibility is disclosure, not authority. Content and structure access
+     to a directory-listed company still require explicit grants —
+     contract 2 §3.1 deny-by-default is unchanged, and the ownership model
+     (§4.4, contract 2 §4.3) is unchanged. Ruling 4b decision 5 wants a
+     see-and-ask-to-join flow for directory-listed companies. **This
+     contract authorizes no join-request runtime surface**: the flow in
+     its entirety — the ability to submit a request, its transport,
+     storage, and request lifecycle — is a follow-up contract, and until
+     that contract ratifies, the directory's only function is the
+     read-only listing above (A2 §9.1.2 admits nothing more). Two
+     invariants pre-bind that future contract now:
+     a join request confers no authority of any kind, and approval is
+     ordinary grant creation by an effective `owner` under contract 2 §4.1
+     — there is no other acceptance path.
 
 ## 3. Grant attachment points
 
@@ -223,7 +274,8 @@ shape contract 2 attaches to:
 2. **Audit parity.** A1 §8.2 leaves every pre-existing REQ binding, so
    hierarchy mutations get REQ-AUD-001's guarantees, not a weakened
    substitute. Concretely:
-   - Every create, rename, transfer, grant create/change/revoke, and
+   - Every create, rename, transfer, visibility change (§5.5), grant
+     create/change/revoke, and
      delete — including every grant deletion cascaded by a node delete —
      emits a semantic audit event carrying actor, verb, target, and (for
      transfers) source and destination parents, with the correlation,
@@ -248,6 +300,25 @@ shape contract 2 attaches to:
    workspace work. Contract 8 owns projection details but cannot narrow
    this rule. This contract additionally guarantees the chain roll-ups
    aggregate over is unique and non-null (§2.5).
+5. **Visibility administration (Ruling 4b decisions 2–3).** Changing
+   `companies.visibility` is a hierarchy mutation through the §5.1
+   command path, audited per §5.2 (the event carries the old and new
+   visibility values as its semantic content). It is authorized for
+   exactly two actor classes: platform admins (`users.role = 'admin'`)
+   and subjects holding the company-CRUD capability that a follow-up
+   amendment to contract 2 will define — until that amendment ratifies,
+   the capability class is empty and the command is admin-only.
+   A company `owner` as such may NOT change visibility: standard users
+   cannot publish a company into the directory. This is the one
+   hierarchy mutation a platform admin performs without holding a
+   hierarchy grant, and it is ratified here as instance administration
+   (directory curation) in contract 2 §1.1's sense, not tenant access:
+   the command mutates the single `visibility` column, reads no tenant
+   content, and confers no grant — contract 2 §1.1's
+   no-implicit-tenant-access rule is otherwise untouched. Top-level
+   company creation (contract 3 §5.2) always creates
+   `visibility = 'private'`; the creation command cannot set or change
+   visibility.
 
 ## 6. Verification requirements
 
@@ -264,7 +335,10 @@ Binding on the implementing PRs (extends A1 §8.3):
    witnessed (zero and two set → refused). Grant uniqueness: a duplicate
    (subject, target, role) row refused for each of the six subject×target
    forms, proving NULLS-NOT-DISTINCT semantics; NOT NULL on `role`,
-   `granted_by`, and all `name`/`slug` columns witnessed.
+   `granted_by`, and all `name`/`slug` columns witnessed. Company
+   visibility (§2.8): a value outside `private`/`directory` refused with
+   both valid values accepted as the control; an insert omitting the
+   column defaults to `private`.
 2. Column allowlist: an information_schema assertion that each class
    table's column set is exactly the set declared in §2/§3 — the bounded
    observable for no-payload (§2.7) and no-`owner_id` (§4.4).
@@ -346,9 +420,19 @@ Binding on the implementing PRs (extends A1 §8.3):
    static analysis cannot see, and any such evasion found later is
    corrected as a conformance defect, not grandfathered.
 4. Audit witnesses: for each mutation class (create, rename, transfer,
-   grant create/change/revoke, delete) — the event exists after commit
+   visibility change, grant create/change/revoke, delete) — the event
-   with actor/verb/target and same-transaction atomicity; a rolled-back
+   exists after commit
-   mutation leaves no event (rollback witness); a node delete's cascaded
+   with actor/verb/target and same-transaction atomicity, and the
+   event's outbox record exists after the same commit — state row,
+   audit event, and outbox record are witnessed as one transaction
+   (REQ-AUD-001); a rolled-back
+   mutation leaves no event, no outbox record, AND no state effect —
+   a rolled-back create leaves no row, a rolled-back rename, transfer,
+   or visibility change leaves the prior values in place, and a
+   rolled-back delete or grant revoke leaves the row present
+   (rollback witness on all three legs, per REQ-AUD-001's
+   commit-or-roll-back-together acceptance); a
+   node delete's cascaded
    grant deletions are each covered by events; events survive deletion of
    their target (query the events of a deleted node).
 5. Transfer tests: parent-FK update moves the subtree resolution and
@@ -368,10 +452,30 @@ Binding on the implementing PRs (extends A1 §8.3):
    endpoints mutate no canonical state anywhere (assert zero writes across
    hierarchy AND workspace tables, not hierarchy only); readers see
    aggregates only over workspaces they are authorized on, with no
-   cross-tenant existence oracles (A1 §8.3 acceptance 3).
+   cross-tenant existence oracles (A1 §8.3 acceptance 3, as narrowed by
+   A2 §9.1.2) beyond the one
+   ratified carve-out — the §2.8 company directory, witnessed in §6.9.
 8. Real-PostgreSQL coverage for every constraint witness (unique/CHECK/
    RESTRICT/NULLS NOT DISTINCT behavior), using the `ci-postgres` service
    in the `test` CI step; mocked specs cannot witness database constraints.
+9. Visibility witnesses (§2.8, §5.5): the directory read returns exactly
+   the `visibility = 'directory'` companies to any authenticated user,
+   disclosing existence, name, and slug only (closed-field assertion on
+   the response shape); a private company never appears in the directory
+   for a reader without a grant on it (with the control: it appears in
+   that reader's granted-structure reads); a directory-listed company's
+   subtree, aggregates, and content remain refused for a non-granted
+   reader (disclosure ≠ authority); the visibility command is refused
+   for a non-admin actor — including an effective `owner` of the target
+   company — with the platform-admin accept control; top-level creation
+   yields `visibility = 'private'` and accepts no visibility argument;
+   each visibility change emits its §5.2 audit event carrying old and
+   new values — the full audit pattern for the mutation class
+   (same-transaction atomicity of state row, audit event, and outbox
+   record; rollback leaving no state effect, no event, and no outbox
+   record; actor/verb/target) is §6.4's, which enumerates
+   visibility change; this item adds only the old/new-value payload
+   assertion.
 
 ## Ruling request
 

docs/requirements/mode-conversion.md

@@ -0,0 +1,279 @@
+# Deployment Mode and Conversion Contract (D3)
+
+Status: DRAFT — awaiting ratification (webui-audit S2, contract 6 of 9).
+Authority: PRD D3 (Part I §3) — two modes chosen at install time,
+Standalone and Enterprise, with the mode table (brains, user-data
+isolation, secrets, conversion); Standalone → Enterprise conversion is
+**one-way** and Enterprise is a **terminal state**. PRD D14 (Part I §7)
+— the per-user brain split is optional in Standalone and keeping it is
+the recommended default because it preserves forward-compatibility with
+the one-way conversion. PRD D11 (Part I §9) — v1 ships the Standalone
+flow only; Enterprise conversion is explicitly deferred. PRD D3
+federation clause — federation is intentionally not fully designed,
+deferred, and nothing in v1 may foreclose it.
+
+Revision 2 (luna review F1–F7): the identity precondition restated in
+identity-contract terms with a conversion-local acknowledgment record
+this contract owns (F1); a durable, keyed preparation state with a
+Standalone-safe representation rule, an in-transaction re-check fence,
+and an exact flip boundary (F2); the §5.4 unknown-value rule stated
+directly without the contradictory non-exhaustiveness clause (F3); the
+D14 boundary bound here with a stable column-allowlist witness instead
+of delegated to an unratified layout (F4); the conversion witness
+matrix extended to every §4.2/§4.4 condition (F5); the mode-record
+writer coverage imported concretely from contract 1 §6.3 with a named
+schema, closed writer set, crafted-write probe, and mode-resolution
+assertion (F6); the mode read command flagged as a §12.1 drafting
+addition rather than a D8 mandate (F7). Ownership language aligned
+with contract 3 revision 2: mode is recorded at bootstrap and read by
+the wizard as input.
+
+This contract binds the mode as a canonical platform property (§2), the
+per-mode obligations and which contract owns each (§3), the conversion
+transition (§4), the v1 non-foreclosure obligations (§5), and their
+witnesses (§6). Domain semantics stay with their owning contracts:
+wizard branching (contract 3 §2), identity/SSO
+(`identity-lifecycle.md`), custody and per-user brain mechanics
+(contract 7, `custody-schema.md`), tool mapping
+(`tool-gateway-mapping.md`).
+
+## 1. Definitions
+
+1. **Mode**: the platform-wide deployment mode, exactly one of
+   `standalone` or `enterprise`. The vocabulary is closed in v1;
+   extension (e.g. a federation mode) is by amendment to this contract,
+   never ad hoc.
+2. **Conversion**: the one-way transition `standalone → enterprise`.
+   No other mode transition exists.
+3. **Conversion preconditions**: the verifiable conditions of §4.2 that
+   must all hold before the mode record may change.
+4. **Preparation unit**: one re-runnable piece of pre-conversion work —
+   the migration of one secret to the Vault backend, or the partition
+   of one user's brain content (§4.3).
+
+## 2. Mode is a canonical recorded property
+
+1. Mode is recorded canonically in the platform database at bootstrap
+   as the operator's install-time choice (D3: modes are "chosen at
+   install time"). The record is a single-row keyed record
+   (`platform_mode`: mode value, recorded-at timestamp, bootstrap epoch
+   reference); this contract owns it, the bootstrap writer performs the
+   one v1 write (§6.2), and the wizard reads it as input (contract 3
+   §2.3). Mode is never derived from feature state (presence of Vault,
+   count of brains, count of users), and no component may infer a
+   different mode than the record states.
+2. The record is readable by any authenticated user through a Gateway
+   command with CLI exposure. This read command is a **drafting
+   addition** ratified with this contract (PRD §12.1), not a D8
+   mandate: D8 binds only that any surface exposing the value goes
+   through official tooling. When a webUI surface consumes the read, a
+   mapping row is added to `tool-gateway-mapping.md` by amendment —
+   the same route §4.4 already binds for the conversion command.
+   Components branch on the read value only.
+3. The record is immutable except by the §4 conversion transition.
+   Editing it by direct database access, config file, environment
+   variable, or wizard re-run is non-conformant (contract 3 §2.3:
+   changing mode later is conversion, not a wizard re-run).
+
+## 3. Per-mode obligations (owner map)
+
+The PRD mode table binds four rows; this contract assigns each an
+owning contract so no obligation is unowned and none is bound twice:
+
+| Obligation          | Standalone                             | Enterprise                                         | Owner                                         |
+| ------------------- | -------------------------------------- | -------------------------------------------------- | --------------------------------------------- |
+| Brains              | one mosaic-brain (system + user files) | system brain for config + one brain per user       | contract 7 (custody/brain mechanics)          |
+| User-data isolation | single user                            | no user-data leakage between users; sharing opt-in | contract 7 (enforced by architecture, D14)    |
+| Secrets             | OpenBao/Vault or flat files            | OpenBao/Vault REQUIRED                             | this contract (§4.2 gate; steady-state check) |
+| Conversion          | may convert to Enterprise, one-way     | terminal state                                     | this contract (§4)                            |
+
+The Standalone brains row states the default layout, not the only
+valid one: the D14 per-user split is a MAY in Standalone with keeping
+it the recommended default (PRD §7, contract 7 §6), and Vault-backed
+secrets are equally valid Standalone configuration. Both prepared
+states are therefore themselves valid Standalone states — the fact
+§4.3 relies on.
+
+In Enterprise steady state, a flat-file secrets backend is
+non-conformant; the platform refuses to start Enterprise-mode
+components against a flat-file secrets configuration (fail-closed, not
+warn-and-run).
+
+## 4. Conversion transition
+
+1. **Direction and terminality.** The only transition is
+   `standalone → enterprise`. `enterprise → standalone` does not exist:
+   there is no command, no admin override, and no support path. An
+   attempt is refused with the precondition/state error class of the
+   command envelope (`tool-gateway-mapping.md` §4.2).
+2. **Preconditions (all verified before the record changes):**
+   - Secrets: OpenBao/Vault is configured and reachable, and every
+     required secret is served from the Vault backend — none from a
+     flat-file backend. Secret migration completes before conversion;
+     this contract does not define the migration tooling, only the
+     gate.
+   - Brains: the per-user brain split required by the Enterprise row of
+     §3 is established for **every** existing user (or the deployment
+     already kept the split, the D14 recommended default). Brain
+     partitioning mechanics are contract 7; this contract binds only
+     that the split is complete before the mode flips.
+   - Identity: at least one platform administrator account exists that
+     is active in identity-contract terms — authenticated capability,
+     not banned, not deactivated (identity §2, §5). And the conversion
+     request carries a **configuration acknowledgment**: the current
+     canonical values of registration mode and per-provider JIT
+     enablement (identity §2.2, §4.1), echoed back in the request. A
+     mismatch between the echoed values and the canonical values at
+     verification refuses the conversion. This acknowledgment record
+     is conversion-local, owned by this contract, and stored with the
+     §4.4 audit event as the precondition evidence; it adds no
+     identity-contract obligation and no mode-specific identity
+     default — identity's own defaults remain valid states.
+3. **Preparation state and the flip boundary.** Preparatory work is
+   tracked durably: each preparation unit (§1.4) records its
+   completion in a preparation table keyed by (bootstrap epoch, unit
+   identity — the secret's path, the user's id), written in the same
+   transaction as the unit's own effect where the unit's backend
+   allows it, and reconciled from the backend's actual state where it
+   does not (a secret already served by Vault, a brain already split,
+   is complete regardless of the table). Units are at-most-once per
+   key and re-runnable across attempts. **Standalone-safe
+   representation:** every preparation unit moves the deployment into
+   a state that is itself valid Standalone configuration (§3 note), so
+   an interrupted preparation leaves a fully operational Standalone
+   deployment reading its state through the ordinary contracts — no
+   rollback, fencing, or special Standalone read path is needed, and
+   no component behavior may key on "preparation in progress".
+   **The flip:** one transaction that (a) locks the mode record, (b)
+   re-verifies every §4.2 precondition after acquiring the lock, and
+   (c) writes the mode record and the §4.4 audit event. Any re-check
+   failure aborts with no write. External state that changes after the
+   re-check but before commit is bounded by the transaction window;
+   an external backend (Vault) failing after conversion is an
+   Enterprise runtime fault handled by §3's fail-closed steady-state
+   rule, not a conversion defect. An interrupted or failed conversion
+   leaves the record `standalone` and the platform fully operational;
+   there is no intermediate mode and no half-converted state
+   observable through the record.
+4. **Authority and audit.** Conversion is a platform-administrator
+   command carrying an explicit irreversibility acknowledgment in its
+   request (distinct from the §4.2 configuration acknowledgment). It
+   is an official Gateway/CLI command (D8): when built, it is added to
+   the tool↔Gateway mapping by amendment (`tool-gateway-mapping.md`
+   §3.3). The transition emits an audit event (actor, prior mode, new
+   mode, precondition evidence reference including the configuration
+   acknowledgment) in the same transaction as the record change; the
+   event survives indefinitely. A refused attempt emits a refusal
+   event naming the failed precondition class and actor, with no
+   mode-change event.
+
+## 5. v1 obligations (non-foreclosure)
+
+v1 ships Standalone only (D11); the conversion command is deferred
+work. v1 still MUST:
+
+1. Record the mode per §2 at bootstrap, with `enterprise` a reserved,
+   refused value for bootstrap — v1 bootstrap accepts `standalone`
+   only. The wizard reads the record (contract 3 §2.3); nothing in v1
+   writes it after bootstrap.
+2. Keep the §2.3 immutability rule: no v1 surface mutates the mode
+   record.
+3. Not foreclose conversion: the v1 platform database holds no
+   sensitive user content — sensitive categories live in the owning
+   user's brain, and postgres holds structure, consent records, and
+   pointers only (the D14 boundary, PRD §7). Custody mechanics are
+   contract 7's; this contract binds the boundary itself here so v1
+   cannot ship a layout that makes the §4.2 brain precondition
+   unsatisfiable, and §6.3 gives it a stable witness that does not
+   depend on contract 7's internals. Conversion implementation
+   additionally requires contract 7 ratified.
+4. Not foreclose federation: v1 components accept exactly the two §1.1
+   values wherever a mode value is parsed and refuse any other value
+   **before side effects** — a refused configuration, not undefined
+   behavior and not a crash mid-operation. Forward compatibility lives
+   in storage and architecture, not in parser speculation: the mode
+   record's storage is not structurally locked to two values (no
+   database-level two-value enum), and any future value (e.g. a
+   federation mode) is defined by a versioned amendment to this
+   contract before any component accepts it. The PRD defers
+   federation's shape entirely; this contract does not presume it
+   arrives as a third mode value.
+
+## 6. Verification requirements
+
+Binding on the implementing PRs:
+
+1. **Mode-record witness (v1):** after bootstrap the mode is readable
+   via the Gateway command and CLI and equals the bootstrap-recorded
+   choice; bootstrap with mode `enterprise` is refused; bootstrap with
+   any unknown mode value is refused before side effects (§5.4).
+2. **Writer-coverage witness (v1):** the mode record's writer set is
+   closed by the same three-prong static assertion contract 1 §6.3(b)
+   defines — symbol, class-table literal, and raw-execution prongs
+   with its allowlist composition rules — scoped to the
+   `platform_mode` table, with a writer allowlist containing exactly
+   the bootstrap writer in v1 (and exactly plus the conversion command
+   at the conversion milestone). Companions: a crafted direct write
+   attempted in a test fails and leaves the record unchanged; a
+   mode-resolution assertion that no shipped component derives mode
+   from feature state (mode reads occur only through the §2.2 read
+   surface — static assertion over Gateway, CLI, bootstrap, and
+   repository sources).
+3. **D14-boundary witness (v1):** a column-allowlist assertion in the
+   style of contract 1 §6.2 that the platform database schema contains
+   no sensitive-content column — the §5.3 boundary — stable regardless
+   of contract 7's internals (contract 7 §7 carries the full custody
+   witnesses).
+4. **No-downgrade witness (conversion milestone):** with mode
+   `enterprise`, a conversion request to `standalone` (and any crafted
+   mode-write) is refused with the precondition/state error class and
+   no record change.
+5. **Precondition witnesses (conversion milestone),** each refused
+   with no record change and no partial mode effect, parameterized
+   over both OpenBao and Vault where secrets are involved:
+   (a) secrets backend unreachable; (b) one required secret still
+   flat-file backed (migration incomplete); (c) one unpartitioned user
+   brain in a **multi-user** deployment where every other user is
+   partitioned; (d) no active platform administrator (the only admin
+   banned or deactivated); (e) configuration acknowledgment missing or
+   mismatching the canonical registration/JIT values; (f) actor not a
+   platform administrator (authorization refusal); (g) irreversibility
+   acknowledgment absent. And the steady-state rule: an
+   Enterprise-mode component started against a flat-file secrets
+   configuration refuses to start (§3).
+6. **Interruption and fence witnesses (conversion milestone):** fault
+   injection aborting conversion after each preparation unit and
+   between preparation and flip leaves the record `standalone` and the
+   platform operational in Standalone semantics (§4.3
+   Standalone-safety), and a re-attempt completes without duplicating
+   prepared state (at-most-once keys); a precondition invalidated
+   after preparation but before the flip (a secret reverted to
+   flat-file) is caught by the in-transaction re-check and refused.
+7. **Audit witnesses (conversion milestone):** a completed conversion
+   has exactly one mode-change audit event, same-transaction with the
+   record change (transaction linkage asserted), carrying actor, prior
+   mode, new mode, and the precondition evidence reference including
+   the configuration acknowledgment; a failed attempt has a refusal
+   event naming the failed precondition class and no mode-change
+   event; the mode-change event remains queryable after subsequent
+   unrelated audit activity (retention probe).
+8. **Mapping witness (conversion milestone):** the conversion command
+   and the mode read command each have their
+   `tool-gateway-mapping.md` row (added by amendment per §2.2/§4.4)
+   before the commands ship.
+
+## Ruling request
+
+Ratify sections 1–6 as written, with one decision embedded:
+
+- Decision (§5): v1 implements the **mode record and its immutability
+  only** — bootstrap records `standalone`, the `enterprise` value is
+  reserved and refused, and the conversion command itself is deferred
+  to the Enterprise milestone, consistent with D11's deferred list.
+  v1 carries three obligations beyond the record: the closed writer
+  assertion, the D14 column boundary, and the unknown-value refusal
+  (§6.1–§6.3) — these are the non-foreclosure floor, not hidden
+  conversion work. Alternative if rejected: build the conversion
+  command inside v1 — rejected because D11 scopes v1 to the Standalone
+  slice and conversion depends on contract 7 custody mechanics that
+  are themselves not in the v1 slice.

docs/requirements/native-kanban-sot.md

@@ -456,3 +456,61 @@ this line is weakened.
 - Negative tests prove roll-up endpoints cannot mutate state and that a
   reader sees aggregates only over workspaces they are authorized on
   (no cross-tenant existence oracles).
+
+## 9. Amendment A2 — company visibility classes and the company directory
+
+**Status:** amendment to Amendment A1, added by reviewed PR under Ruling 4b
+(operator ruling, 2026-08-27; decision owner Jason; recorded in the webui-audit
+lane RULINGS.md). Everything in §§1–8 remains binding verbatim, with exactly
+the two express modifications below. Nothing else is weakened. The detailed
+contract text lives in the hierarchy schema contract
+(`hierarchy-schema.md` §2.8, §5.5, §6.9); this amendment changes only what A1
+itself permits, so that contract does not stretch A1 by interpretation.
+
+### 9.1 What A2 modifies in A1
+
+1. **Class data (extends §8.1.2's first constraint).** The tenancy/authorization
+   structure record class additionally carries **visibility-class data**: the
+   single column `companies.visibility`, values `private` | `directory`
+   (hierarchy schema §2.8). Visibility is disclosure data about the class's own
+   nodes — what a company row reveals about its own existence — and is part of
+   the class's tenancy/authorization purpose. It is not business or
+   orchestration payload. §8.1.2's payload prohibition is widened for nothing
+   else: hierarchy tables still MUST NOT carry task, plan, or any other
+   business/orchestration payload, and this amendment admits exactly this one
+   column.
+2. **The company directory (extends §8.1.3's function enumeration).** The
+   hierarchy serves one additional, express, narrow runtime function: the
+   **company directory** — a read-only disclosure listing of exactly the
+   companies whose `visibility = 'directory'`, revealing existence, name, and
+   slug to every authenticated user of the deployment and nothing else. It
+   mutates nothing, confers no authority, evaluates no grant down the chain,
+   and aggregates nothing (it is not a roll-up). §8.3's
+   no-cross-tenant-existence-oracle acceptance is narrowed by exactly this one
+   ratified carve-out: the directory is the sole permitted existence
+   disclosure, and it discloses only directory-class companies (witnessed in
+   hierarchy schema §6.7 and §6.9). Private companies remain undisclosed to
+   non-granted subjects everywhere, including the directory.
+
+### 9.2 What A2 explicitly does not change
+
+1. Content access stays grant-only under the RBAC grant model contract:
+   directory listing discloses existence, never content, membership, or any
+   authority (Ruling 3 unchanged; hierarchy schema §2.8).
+2. **No join-request surface is authorized.** Ruling 4b decision 5's
+   see-and-ask-to-join flow is a follow-up contract in its entirety —
+   including the ability to submit a request. A2 admits exactly the
+   read-only listing of §9.1.2 and nothing more; hierarchy schema §2.8
+   states the invariants that pre-bind the future flow contract, and that
+   contract must itself amend this enumeration before any join-request
+   runtime surface exists.
+3. Visibility changes are hierarchy mutations on the existing §8.2.3 audited
+   mutation path — audited maintenance of the class's own structure in
+   §8.1.3's sense, not a further runtime function. Authorization for them is
+   defined in hierarchy schema §5.5 (platform admins plus the future
+   company-CRUD capability; owner-as-such cannot publish).
+4. Company creation is unchanged and always yields `visibility = 'private'`
+   (onboarding wizard §5.2); this amendment adds no creation path and no
+   default-open disclosure.
+5. Every other constraint of A1 — §8.1.2's remaining bullets, §8.2 in full,
+   and §8.3's other acceptance criteria — is untouched.

docs/requirements/onboarding-wizard.md

@@ -397,6 +397,14 @@ seed-workspace-scoped mutant, correctly refusing outside the seed
 set, passes branch (c), so the two branches detect distinct
 mutants. No other change.
 
+Amendment 1 (Ruling 4b, 2026-08-28): §5.2's embedded decision was RULED
+AGREED (Jason, 2026-08-27), and Ruling 4b adds company visibility
+classes (hierarchy schema §2.8): open top-level creation always yields
+a **private** company; publishing a company into the deployment-wide
+directory is a separate, gated visibility mutation (hierarchy schema
+§5.5) that is never part of the creation command. §5.2 is amended to
+state both.
+
 Scope: the Gateway-backed product onboarding wizard. Out of scope: the
 host-local install wizard (`mosaic wizard`, which drives host install and
 gateway bootstrap and is not this artifact — audit REPORT.md layer 3);
@@ -1169,15 +1177,18 @@ collects no sensitive category, so v1 ships no custody surface.
    party, service actor, or wizard-privileged writer exists in this
    flow.
 2. **Post-bootstrap top-level company creation** — the "N companies" flow
-   — is decided by the ruling below: any **eligible platform user** MAY
+   — RULED AGREED (Jason, 2026-08-27): any **eligible platform user** MAY
    create a top-level company and MUST name an initial `owner` grant in
    the same audited operation (contract 2 §4.3); the creator naming
    themselves is the default. Eligible means, in identity-contract
    terms: an authenticated account (identity §2) that is not banned
    (identity §7.1 — deactivation on this platform IS the better-auth
    ban; no separate deactivated state exists). No further role or grant
-   is required. Until that ruling, deny-by-default holds (contract 2
+   is required. Creation always yields a **private** company
-   §3.1): no implicit creation authority exists.
+   (`visibility = 'private'`, hierarchy schema §2.8, Ruling 4b): the
+   creation command accepts no visibility argument, and publishing into
+   the deployment-wide directory is a separate, gated mutation
+   (hierarchy schema §5.5) that standard users cannot perform.
 3. Child-node creation inside the wizard (estate, project, workspace
    under the seeded company) follows contract 2 §4.3: parent
    `owner` authority, no automatic grant needed — for canonical seed
@@ -1932,7 +1943,13 @@ contracts and are not additions:
     suffix at all — each contradicting PRD D4's no-lock-in
     requirement (§4.4).
 
-## Ruling request
+## Ruling request — RULED AGREED (Jason, 2026-08-27; Amendment 1)
+
+The §5.2 decision below was ruled agreed: open eligible-user creation
+stands (yielding private companies per Amendment 1), and the
+"alternative if rejected" did not take effect. The request is retained
+below as historical record of what was put to ruling; it is no longer
+live.
 
 Ratify sections 1–7 as written, with one decision embedded:
 

docs/requirements/tool-gateway-mapping.md

@@ -0,0 +1,197 @@
+# Tool↔Gateway Mapping Contract (D8)
+
+Status: DRAFT — awaiting ratification (webui-audit S2, contract 5 of 9).
+Authority: PRD D8/D12 (Part I §8) — the webUI sits OVER official tooling:
+every webUI operation goes through the Gateway API backed by the same
+official framework tooling the CLI uses, and a webUI operation with no
+backing tool is scored **blocked on tooling** and the tool is built
+first. Measured input: the webui-audit A5 tooling baseline
+(operation-by-operation inventory of the current Gateway surface and the
+P1 gaps, cross-reviewed; `fleet/lanes/webui-audit/findings/
+A5-tooling-baseline.md` in the estate brain). The T10 ruling adopted the
+targeted-update plan including building the D8 tools in A5's rank order.
+
+Revision 2 (GLM review F1–F5): the §2 table completed against an
+independent re-measurement of the live `apps/web` surface (mission
+reads, coordination status, capability-gated `turn:send` added); rank-6
+composition corrected to ranks 1 and 4; SOT citations corrected to §3
+invariant 11 / REQ-TASK-001 / §5+A1; the §3.2 retirement clause
+softened to match what the owning contracts actually schedule; §6.1
+scoped to outbound calls with an extractability lint, and §6.3 given
+static companions for §4.1 and §4.3.
+
+This contract binds three things: the operation→tool mapping itself
+(§2–§3), the command envelope every mapped operation satisfies
+(§4), and the process rule that keeps the mapping closed (§5). Domain
+semantics stay with their owning contracts — hierarchy (contract 1,
+`hierarchy-schema.md`), grants (contract 2, `rbac-grant-model.md`),
+wizard (contract 3, `onboarding-wizard.md`), identity
+(`identity-lifecycle.md`), kanban lifecycle (`native-kanban-sot.md`
+§5 and Amendment A1), roll-up (contract 8), API artifact format
+(contract 9).
+
+## 1. Definitions
+
+1. **Official tool**: a command implemented in the framework packages and
+   exposed through the Gateway API; the CLI remains the primary execution
+   method for the same command (D8). The webUI is a Gateway client only.
+2. **Mapped operation**: a webUI operation with a named official path in
+   §2 or §3. Anything else the webUI wants to do is unmapped and follows
+   §5.
+3. **Legacy non-substitute**: an existing endpoint that resembles a P1
+   need but is contractually barred from backing it (§3.2).
+
+## 2. P0 mapping (current operations, ratified as-is)
+
+This table is the complete measured P0 surface: every Gateway call the
+web app's production sources make at this revision's head appears as a
+row (independently re-measured at review; the three calls the first
+measurement missed — mission reads, coordination status, and the
+capability-gated `turn:send` emit — are rows below). The surface stays
+bound to these paths:
+
+| WebUI operation                                                   | Official path                                                                                                                                                                                                                               |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Register / log in / log out / OIDC callback                       | better-auth mount `/api/auth/*`; `GET /api/sso/providers`                                                                                                                                                                                   |
+| List/show projects (legacy read)                                  | `GET /api/projects`, `GET /api/projects/:id`                                                                                                                                                                                                |
+| List tasks / task detail (legacy read)                            | `GET /api/tasks`, `GET /api/tasks/:id` — with the filtered legacy project/mission reads the same surfaces use                                                                                                                               |
+| Mission list (legacy read)                                        | `GET /api/missions`                                                                                                                                                                                                                         |
+| Coordination status (legacy read)                                 | `GET /api/coord/status`                                                                                                                                                                                                                     |
+| Conversation CRUD/search/messages                                 | `/api/conversations*`                                                                                                                                                                                                                       |
+| Chat turn / stop / thinking / command execute+approve / streaming | `/chat` socket events `message`, `abort`, `set:thinking`, `command:execute`, `command:approve`; `turn:send` (capability-gated — emitted only when the server advertises the pi turn-runtime capability, which the current Gateway does not) |
+| Harness/model selection                                           | `GET /api/harnesses*`, `GET/PUT /api/chat/preferences/selection`                                                                                                                                                                            |
+| Preferences; provider inspect/test                                | `/api/memory/preferences`, `GET /api/providers`, `POST /api/providers/test`                                                                                                                                                                 |
+| Admin users / roles / ban / health                                | `/api/admin/users*`, `/api/admin/health`                                                                                                                                                                                                    |
+
+P0 rows inherit §4 obligations as their backing controllers are next
+touched; they are not required to be retrofitted in one sweep.
+
+## 3. P1 mapping (bound to the build-first tools)
+
+1. Every P1 operation maps to exactly one build-first command family, in
+   the T10-ruled rank order:
+
+| Rank | Command family (owning contract)                                       | P1 webUI operations it backs                                                                                                                      |
+| ---- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | Hierarchy command family (contract 1 §5; grants attach per contract 2) | Company/estate/platform-project/workspace CRUD, parentage and reparenting, hierarchy reads; the wizard's initial-hierarchy step (contract 3 §3.4) |
+| 2    | Hierarchy RBAC command/evaluator (contract 2)                          | Grant create/change/revoke at company/estate/platform-project; inherited evaluation down to workspace; authorization-safe hierarchy queries       |
+| 3    | Typed kanban command/query surface (SOT §5, Amendment A1)              | Workspace task lifecycle (create/edit/cancel/archive/move), board rank, typed queries                                                             |
+| 4    | Agent enrollment command                                               | Enroll one agent: harness, credential reference/API-key intake (values never echoed), name/persona, assignment scope (contract 3 §3.5)            |
+| 5    | Authorized roll-up query (contract 8)                                  | Read-only aggregated task counts/statuses at every hierarchy level over readable workspaces only                                                  |
+| 6    | Onboarding orchestration (contract 3)                                  | The re-runnable wizard flow, composing ranks 1 and 4 (its only grant write rides inside the rank-1 company-create command, contract 2 §4.3)       |
+
+2. **Legacy non-substitutes.** The following MUST NOT back any P1
+   operation, matching the audit findings: legacy `/api/projects` and
+   `/api/tasks` CRUD (planning-data records, not hierarchy nodes and not
+   the typed kanban boundary); `POST /api/workspaces` (filesystem
+   bootstrap, not audited hierarchy parentage); `/api/teams` reads (no
+   grants, no inheritance); `POST /api/bootstrap/setup` (one-shot
+   epoch transition, identity §3 — not the re-runnable wizard); the MCP
+   `brain_*` task mutations (legacy Brain writes, not the typed kanban
+   commands). These stay serving their existing P0/host consumers until
+   the owning contract (or a successor amendment) schedules each
+   retirement — no such migration is scheduled at this revision; the
+   freeze stands on its own.
+3. New P1 mapping rows (operations this table does not list) are added by
+   amending this contract, not ad hoc (§5).
+
+## 4. Command envelope (request / result / error / audit)
+
+Binding on every mapped operation the build-first families expose:
+
+1. **Typed request and result.** Each command and query has an explicit
+   request DTO and result DTO in the shared types package, validated at
+   the Gateway boundary; unvalidated pass-through and `any`-typed
+   payloads are non-conformant. Mutations on records with an
+   expected-version rule in their owning contract carry the expected
+   version in the request and fail on mismatch with the conflict error
+   class (SOT §3 invariant 11 and REQ-TASK-001's concurrent-update
+   conflict acceptance; hierarchy per contract 1).
+2. **Error taxonomy.** Every error result carries a stable
+   machine-readable code from a closed per-family enum plus an HTTP
+   status mapping, distinguishing at minimum: validation failure,
+   authentication failure, authorization refusal, not-found, conflict
+   (version/uniqueness), precondition/state refusal (e.g. bootstrap
+   epoch, suspended team subjects), and internal fault. Where contract
+   2's no-existence-oracle rule applies, authorization refusal and
+   not-found are indistinguishable on the wire for unauthorized readers
+   — same code, same status, same shape.
+3. **Audit linkage.** A mutating mapped operation emits exactly the
+   audit events its owning contract defines (contract 1 §5.2, contract 2
+   §4.4, identity §§2–4, SOT audit rules); the envelope contributes the
+   correlation: every request accepts/generates a correlation id,
+   carried into the audit events and returned in the result, so a UI
+   action is traceable end to end. The mapping layer itself adds no
+   second audit stream.
+4. **Fail-closed.** A mapped operation that cannot evaluate its
+   authorization or reach its owning tool refuses (contract 2 §3.5); the
+   envelope never degrades to an unauthorized fallback read or a direct
+   data access.
+5. **CLI parity.** Each build-first family is invocable through the
+   official CLI against the same Gateway commands with the same
+   request/result/error contracts. No webUI-only command exists; a
+   Gateway command without CLI exposure is a conformance gap tracked at
+   the family's implementing issue.
+
+## 5. Closure rule (blocked on tooling)
+
+1. A webUI change that needs an operation with no mapping row is
+   **blocked on tooling**: the backing tool is built and mapped first
+   (D8). Scoring a gap "blocked on tooling" is mandatory, not
+   discretionary; working around it in the UI (direct DB or filesystem
+   access, calling a legacy non-substitute, embedding domain logic in
+   the web app) is non-conformant.
+2. The mapping is enforced closed by §6.1's inventory witness: the web
+   app's network surface must be a subset of the mapped paths.
+
+## 6. Verification requirements
+
+Binding on the implementing PRs:
+
+1. **Network-surface inventory witness:** a CI assertion extracting the
+   web app's outbound Gateway calls — route literals at request call
+   sites and outbound socket emits in `apps/web` sources (inbound
+   handler registrations are not calls and are out of scope) — and
+   failing on any call outside the §2/§3 mapped paths. The inventory is
+   closed like contract 1 §6.3's allowlist: a new call fails until a
+   mapping row exists in the same PR. Dynamic route construction that
+   evades extraction is resolved toward the witness, enforced by an
+   extractability lint: every request call site takes a literal or
+   template-literal path, and a call site that does not fails the
+   assertion itself (the web-side analogue of contract 1's
+   raw-execution prong), never an exemption for the caller.
+2. **Non-substitute witness:** the P1 surfaces (hierarchy, RBAC, kanban,
+   enrollment, roll-up, wizard UI) make zero calls to the §3.2 legacy
+   endpoints — asserted by the same inventory, scoped per surface.
+3. **Envelope witnesses per family:** for each build-first family — a
+   request with an invalid DTO is refused with the validation code; a
+   version-mismatch mutation returns the conflict code; an unauthorized
+   read of an existing node and a read of a nonexistent node return
+   indistinguishable results where the no-existence-oracle rule applies;
+   a correlation id submitted on a mutation appears in its audit
+   event(s) and result. Two static companions: a type-level assertion
+   that the family's boundary accepts no `any`-typed or unvalidated
+   pass-through payload (§4.1), and a single-emitter assertion that the
+   mapped operation's audit events originate only from the owning
+   contract's audit emitter (§4.3's no-second-audit-stream, made
+   checkable).
+4. **CLI-parity witness:** for each family, a CLI smoke invocation of at
+   least one command and one query against the Gateway succeeds with the
+   same typed result the web client receives.
+5. **Fail-closed witness:** with the owning tool or grant state
+   unreachable (fault injection), the mapped operation returns the
+   internal-fault or authorization-refusal class and performs no
+   fallback read/write (extends contract 2 §7.6 to the mapping layer).
+
+## Ruling request
+
+Ratify sections 1–6 as written, with one decision embedded:
+
+- Decision (§3.2): the legacy endpoints named there are **frozen for new
+  consumers** as of ratification — existing P0/host consumers keep
+  working, new UI or tool code may not call them, and each is retired by
+  the migration its owning contract schedules. Alternative if rejected:
+  allow P1 surfaces to reuse legacy endpoints as interim backends —
+  rejected by the audit's finding that they cannot satisfy the
+  hierarchy/kanban/RBAC contracts, so the interim would ship
+  non-conformant semantics.

packages/mosaic/framework/tools/git/issue-comment.sh

@@ -1,6 +1,7 @@
 #!/bin/bash
 # issue-comment.sh - Add a comment to an issue on GitHub or Gitea
-# Usage: issue-comment.sh -i <issue_number> -c <comment> [--login <name>]
+# Usage: issue-comment.sh -i <issue_number> -b <comment> [--login <name>]
+# (-c/--comment is a backward-compatible alias for -b/--body; R1, 2026-08-28)
 #
 # tea v0.11.1 defines no `comment` subcommand under `tea issue` (or `tea pr`);
 # the non-existent `tea issue comment ...` form does not error — tea silently
@@ -32,45 +33,61 @@ ISSUE_NUMBER=""
 COMMENT=""
 LOGIN_OVERRIDE=""
 
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1), so a
+# caller or stop gate can tell an invocation defect from a delivery blocker
+# (CONSTITUTION gate 8 as amended; E2E-DELIVERY).
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: issue-comment.sh -i <issue_number> -b <comment> [--login <name>] (see --help)" >&2
+    exit 2
+}
+
 while [[ $# -gt 0 ]]; do
     case $1 in
         -i|--issue)
+            [[ $# -ge 2 ]] || usage_error "option $1 requires a value"
             ISSUE_NUMBER="$2"
             shift 2
             ;;
-        -c|--comment)
+        -b|--body|-c|--comment)
+            # R1 (2026-08-28): --body is the canonical flag, matching
+            # issue-create/issue-edit/pr-create/pr-edit; -c/--comment stays a
+            # backward-compatible alias.
+            [[ $# -ge 2 ]] || usage_error "option $1 requires a value"
             COMMENT="$2"
             shift 2
             ;;
         -l|--login)
+            [[ $# -ge 2 ]] || usage_error "option $1 requires a value"
             LOGIN_OVERRIDE="$2"
             shift 2
             ;;
         -h|--help)
-            echo "Usage: issue-comment.sh -i <issue_number> -c <comment> [--login <name>]"
+            echo "Usage: issue-comment.sh -i <issue_number> -b <comment> [--login <name>]"
             echo ""
             echo "Options:"
             echo "  -i, --issue    Issue number (required)"
-            echo "  -c, --comment  Comment text (required)"
+            echo "  -b, --body     Comment text (required; canonical)"
+            echo "  -c, --comment  Alias for --body"
             echo "  -l, --login    Override the detected Gitea tea login for this call"
             echo "  -h, --help     Show this help"
+            echo ""
+            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential/verification failure."
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
+            usage_error "unknown option: $1"
-            exit 1
             ;;
     esac
 done
 
 if [[ -z "$ISSUE_NUMBER" ]]; then
-    echo "Error: Issue number is required (-i)"
+    usage_error "issue number is required (-i/--issue)"
-    exit 1
 fi
 
 if [[ -z "$COMMENT" ]]; then
-    echo "Error: Comment is required (-c)"
+    usage_error "comment is required (-b/--body, or the -c/--comment alias)"
-    exit 1
 fi
 
 detect_platform >/dev/null
@@ -340,7 +357,15 @@ PY
 }
 
 if [[ "$PLATFORM" == "github" ]]; then
-    gh issue comment "$ISSUE_NUMBER" --body "$COMMENT"
+    # R4 exit-code contract: normalize provider failures to exit 1. gh's own
+    # usage errors exit 2, which would collide with this wrapper's reserved
+    # usage-error status if propagated raw (codex review of 08a00149).
+    gh_rc=0
+    gh issue comment "$ISSUE_NUMBER" --body "$COMMENT" || gh_rc=$?
+    if [[ "$gh_rc" -ne 0 ]]; then
+        echo "Error: GitHub comment write failed (gh exit $gh_rc; provider/credential failure — usage errors are exit 2)" >&2
+        exit 1
+    fi
     echo "Added comment to GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     # A --login override selects a NAMED tea credential and is the only way to

packages/mosaic/framework/tools/git/test-issue-comment-readback.sh

@@ -42,6 +42,8 @@
 #  10. leaves NO temp files behind (POST/GET bodies + metadata) on either the
 #      success or the failure path — nested function-scoped RETURN traps do not
 #      clobber each other and every scratch file is removed on all exit paths.
+#  11. accepts the canonical -b/--body flag exactly like the -c/--comment alias
+#      (R1, 2026-08-28): a full verified write via -b alone.
 
 set -euo pipefail
 
@@ -409,11 +411,28 @@ run_comment() {
     seed_state "$mode"
     (
         cd "$REPO_DIR"
+        # Provisioned seats export MOSAIC_GIT_IDENTITY and MOSAIC_BRAIN_HOME
+        # seat-wide (launcher), and both escape this harness's sandboxed HOME:
+        # detect-platform.sh consults MOSAIC_GIT_IDENTITY BEFORE the repo-local
+        # mosaic.gitIdentity pin, and resolves the brain home (whose
+        # fleet/agents presence arms the no-identity fail-loud branch) from
+        # MOSAIC_BRAIN_HOME before $HOME. Without these explicit empties the
+        # wrapper either resolves the REAL seat-slot token (stub curl rejects
+        # it: the documented HTTP 401) or fails loud before any request.
+        # Set-but-empty reads as unset to detect-platform's "${VAR:-}" forms.
+        # NOTE: keep this comment block ABOVE the assignment chain — a comment
+        # inside a backslash-continued prefix chain terminates the command and
+        # silently demotes every earlier assignment to an unexported subshell
+        # assignment (measured 2026-08-28: the wrapper then ran without
+        # MOSAIC_CREDENTIALS_FILE and the suite died at credential resolution
+        # with zero diagnostic output).
         PATH="$BIN_DIR:$PATH" \
         TMPDIR="$TMP_SCRATCH" \
         HOME="$HOME_DIR" \
         XDG_CONFIG_HOME="$XDG_DIR" \
         MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
+        MOSAIC_GIT_IDENTITY="" \
+        MOSAIC_BRAIN_HOME="" \
         ISSUE_COMMENT_TEA_LOG="$TEA_LOG" \
         ISSUE_COMMENT_CURL_LOG="$CURL_LOG" \
         ISSUE_COMMENT_CURL_ARGV_LOG="$CURL_ARGV_LOG" \
@@ -430,7 +449,7 @@ run_comment() {
         ISSUE_COMMENT_REPO_SLUG="$REPO_SLUG" \
         ISSUE_COMMENT_API_BASE="$API_BASE" \
         ISSUE_COMMENT_API_ROOT="$API_ROOT" \
-        "$SCRIPT_DIR/issue-comment.sh" -i "$ISSUE_NUMBER" -c "$BODY" "$@"
+        "$SCRIPT_DIR/issue-comment.sh" -i "$ISSUE_NUMBER" "${BODY_FLAG:--c}" "$BODY" "$@"
     ) > "$OUTPUT_FILE" 2>&1
 }
 
@@ -614,4 +633,21 @@ done
 # issue_url (already exercised by Case 1's fresh-success), so the tightened check
 # is not rejecting genuine writes.
 
+# Case 11 (R1, 2026-08-28): -b/--body is the canonical comment flag and must
+# drive a full verified write exactly like the -c/--comment alias. BODY_FLAG
+# swaps only the flag spelling; every assertion below is case 1's contract.
+BODY_FLAG="-b"
+run_comment fresh-success
+grep -q 'Added and verified comment on Gitea issue #7 (comment ID 51)' "$OUTPUT_FILE"
+grep -q "^POST $API_BASE/issues/7/comments$" "$CURL_LOG"
+if grep -Eq '^comment |^issue comment ' "$TEA_LOG"; then
+    echo "FAIL: --body write went through tea instead of REST" >&2
+    exit 1
+fi
+grep -q "^GET $API_BASE/issues/comments/51$" "$CURL_LOG"
+grep -q "^POST $API_BASE/issues/7/comments $ACTING_LOGIN$" "$AUTH_LOG"
+assert_no_temp_leak "fresh-success-body-flag"
+assert_token_not_in_argv "fresh-success-body-flag"
+unset BODY_FLAG
+
 echo "issue-comment.sh REST create + exact-id read-back regression passed"

packages/mosaic/framework/tools/git/test-issue-comment-usage-contract.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-comment.sh (R1/R4 remediation, 2026-08-28).
+#
+# R4: usage errors print to STDERR and exit 2, distinct from provider,
+# credential, and verification failures (exit 1), so a caller (or a stop gate)
+# can tell an invocation defect from a delivery blocker. Before this contract
+# the wrapper exited 1 for usage errors with messages on STDOUT, and a
+# value-less flag (-c with no value) died SILENTLY at rc=1 because set -e
+# killed the failed `shift 2`. That silent shape is what full-stopped a fleet
+# seat: a caller could not distinguish "I invoked it wrong" from "delivery is
+# blocked".
+#
+# R1: -b/--body is the canonical comment flag (matching issue-create,
+# issue-edit, pr-create, pr-edit); -c/--comment remains a backward-compatible
+# alias.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. Missing required comment exits 2 (stderr).
+#   5. A value-less flag (-i -b -c -l and long forms) exits 2 with a
+#      "requires a value" message on stderr (the former silent-death class).
+#   6. -b and -c both pass parsing (the run then fails at platform detection
+#      in this non-repo fixture, nonzero and NOT 2), proving alias acceptance
+#      without any provider fixture.
+#   7. No arm performs any provider request: PATH shims for gh/tea/curl
+#      record every invocation and the probe log must stay empty.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-comment-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Provider shims: any invocation is recorded and fails the run at the end.
+# Usage-error arms must exit during argument parsing, before detect_platform,
+# so these prove "no provider request on parser failure".
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+# gh doubles as platform probe AND write path in arm 6b: probes exit 0; the
+# comment write exits 2 (gh's own usage-error status) to prove the wrapper
+# normalizes provider failures to exit 1 instead of propagating 2.
+if [[ "\$1 \$2" == "issue comment" ]]; then exit 2; fi
+exit 0
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-comment.sh" "$@" )
+}
+
+# Hermetic variant for parse-acceptance arms: neutralizes every identity/
+# credential source the wrapper consults (seat env vars, HOME, XDG tea config)
+# so the arm fails at credential resolution in ANY cwd repo, never reading a
+# real token or contacting a provider. Measured 2026-08-28: without this, the
+# arm's outcome depended on incidental URL-resolution state (brain cwd died at
+# URL-not-found; a stack worktree cwd resolved a configured URL, read the real
+# seat token, and invoked the curl stub — the suite then failed its own
+# no-provider-contact check, correctly).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/issue-comment.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$desc: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage on stdout.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: issue-comment.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, message on stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "unknown option" "unknown option names itself on stderr"
+
+# 3. Missing required issue number: rc 2, stderr.
+expect_rc 2 "missing -i exits 2"
+expect_stderr "issue number is required" "missing -i message on stderr"
+
+# 4. Missing required comment: rc 2, stderr.
+expect_rc 2 "missing comment exits 2" -i 5
+expect_stderr "comment is required" "missing comment message on stderr"
+
+# 5. Value-less flags: rc 2 with "requires a value" on stderr. The old parser
+# died here silently (set -e on the failed shift 2).
+for flag in -i -b -c -l --issue --body --comment --login; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 6. Alias acceptance at parse level: both -b and -c carry a value past
+# parsing; the wrapper then fails at platform detection (not a git repo)
+# nonzero but NOT as a usage error (rc must not be 2).
+for flag in -b -c; do
+    rc=0
+    run_wrapper_sandboxed -i 5 "$flag" "some text" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6b. GitHub-path exit normalization (codex blocker on 08a00149): gh's own
+# usage errors exit 2; the wrapper must NOT propagate that status (reserved
+# for the wrapper's usage-error contract). With a github remote and a gh stub
+# whose comment write exits 2, the wrapper must exit 1 with the normalized
+# error on stderr.
+GH_REPO="$WORK_DIR/repo-gh"
+mkdir -p "$GH_REPO"
+git -C "$GH_REPO" init -q
+git -C "$GH_REPO" remote add origin https://github.com/acme/widgets.git
+git -C "$GH_REPO" config mosaic.gitIdentity ""
+rc=0
+(
+    cd "$GH_REPO"
+    PATH="$BIN_DIR:$PATH" MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+        "$SCRIPT_DIR/issue-comment.sh" -i 5 -b "text" >"$OUT_FILE" 2>"$ERR_FILE"
+) || rc=$?
+[[ "$rc" -eq 1 ]] || fail "GitHub path: gh exit 2 must normalize to wrapper exit 1 (got $rc)"
+grep -q "GitHub comment write failed" "$ERR_FILE" || fail "GitHub path: normalized error missing from stderr"
+grep -q "^gh issue comment" "$PROBE_LOG" || fail "GitHub path: gh write was not invoked"
+
+# 7. No provider contact from any usage-error arm (arm 6b's deliberate gh
+# invocation is the only permitted entry in the probe log).
+if grep -v '^gh issue comment' "$PROBE_LOG" | grep -q .; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    grep -v '^gh issue comment' "$PROBE_LOG" >&2
+    exit 1
+fi
+
+echo "issue-comment.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/quality/test-enumeration-exclusions.txt

@@ -14,7 +14,6 @@
 packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh | resolves real credentials (#1007 census); joins CI after the wrapper-half hermeticity fix (git -C scoping)
 packages/mosaic/framework/tools/git/test-issue-create-interactive-auth.sh | resolves real credentials (#1007 census); joins CI after the wrapper-half hermeticity fix
 packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh | resolves real credentials (#1007 census, fourth entry via family-grep); joins CI after the wrapper-half hermeticity fix
-packages/mosaic/framework/tools/git/test-issue-comment-readback.sh | resolves real credentials (#1007 census, fifth entry); joins CI after the wrapper-half hermeticity fix
 
 # --- tools/git: push guards — measured green locally, CI-image fitness unverified ---
 packages/mosaic/framework/tools/git/test-push-guard.sh | measured green at 826a8b3b (46 passed / 0 failed, one run, 2026-07-31); CI-image fitness unverified; #1017 burndown

packages/mosaic/package.json

@@ -25,7 +25,7 @@
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests && pnpm run test:framework-shell",
-    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 framework/tools/quality/scripts/test-framework-drift-check.py && bash framework/tools/quality/scripts/test-framework-drift-doctor.sh && bash framework/systemd/user/test-fleet-units.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/lease-broker/revoke_noop_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-edit.sh && bash framework/tools/git/test-pr-create-fallback-default-base.sh && bash framework/tools/git/test-repo-decl-consumption.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-no-status.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-ci-queue-wait-no-ci-expected.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-no-ci-expected.sh && bash framework/tools/git/test-pr-merge-fork-ci-status.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/git/test-explain-diagnostic-status-neutral.sh && bash framework/tools/git/test-detect-platform-outside-repo.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh && bash framework/tools/_scripts/test-brain-home-check.sh && bash framework/tools/_scripts/test-structure-anchor-check.sh && bash framework/tools/fleet/test-agent-session-broker-preflight.sh && bash framework/tools/fleet/test-agent-session-legacy-socket-guard.sh && bash framework/tools/git/test-grant-reviewer.sh"
+    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 framework/tools/quality/scripts/test-framework-drift-check.py && bash framework/tools/quality/scripts/test-framework-drift-doctor.sh && bash framework/systemd/user/test-fleet-units.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/lease-broker/revoke_noop_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-edit.sh && bash framework/tools/git/test-pr-create-fallback-default-base.sh && bash framework/tools/git/test-repo-decl-consumption.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-no-status.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-ci-queue-wait-no-ci-expected.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-no-ci-expected.sh && bash framework/tools/git/test-pr-merge-fork-ci-status.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/git/test-issue-comment-usage-contract.sh && bash framework/tools/git/test-issue-comment-readback.sh && bash framework/tools/git/test-explain-diagnostic-status-neutral.sh && bash framework/tools/git/test-detect-platform-outside-repo.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh && bash framework/tools/_scripts/test-brain-home-check.sh && bash framework/tools/_scripts/test-structure-anchor-check.sh && bash framework/tools/fleet/test-agent-session-broker-preflight.sh && bash framework/tools/fleet/test-agent-session-legacy-socket-guard.sh && bash framework/tools/git/test-grant-reviewer.sh"
   },
   "dependencies": {
     "@mosaicstack/brain": "workspace:*",

packages/mosaic/src/config/installation/adapters.ts

@@ -0,0 +1,213 @@
+/**
+ * Read-only adapters for the installation config pipeline (§16).
+ *
+ * Every adapter is a bounded, side-effect-free read. The registry resolver
+ * is DEPENDENCY-BLOCKED (§2.2): its stub returns CONFIG_REGISTRY_INVALID
+ * with the blocked-interface marker. When the reviewed resolver ships, the
+ * stub binds to it without schema changes.
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import { execSync } from 'node:child_process';
+import * as path from 'node:path';
+
+import {
+  type ConfigDiagnostic,
+  type RegistryProvenance,
+  type InstallationBindings,
+  type FrameworkBindingDefaults,
+  FRAMEWORK_BINDING_DEFAULTS,
+  REGISTRY_RESOLVER_BLOCKED,
+} from './types.js';
+
+// ─── Digest helpers ───────────────────────────────────────────────────────────
+
+/** SHA-256 over canonical JSON with recursively sorted keys (§9). */
+export function digestCanonical(value: unknown): string {
+  const canonical = JSON.stringify(sortKeysDeep(value));
+  return crypto.createHash('sha256').update(canonical).digest('hex');
+}
+
+function sortKeysDeep(value: unknown): unknown {
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+    sorted[key] = sortKeysDeep((value as Record<string, unknown>)[key]);
+  }
+  return sorted;
+}
+
+export function digestBytes(content: string | Buffer): string {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+// ─── 1. Registry resolver adapter (§16, dependency-blocked) ──────────────────
+
+export interface RegistryAdapter {
+  resolve(): { provenance: RegistryProvenance; diagnostics: ConfigDiagnostic[] };
+}
+
+/**
+ * DEPENDENCY GATE (§2.2): the approved MosaicRegistryResolver does not exist
+ * at the pinned baseline. This stub returns the blocked marker. When the
+ * reviewed resolver ships (CFG-REQ-001..006), replace this stub's resolve()
+ * to delegate to it. The interface is stable.
+ */
+export class BlockedRegistryAdapter implements RegistryAdapter {
+  resolve(): { provenance: RegistryProvenance; diagnostics: ConfigDiagnostic[] } {
+    return {
+      provenance: {
+        resolved: false,
+        brainHome: null,
+        sourceKeys: [],
+      },
+      diagnostics: [
+        {
+          code: 'CONFIG_REGISTRY_INVALID',
+          message: REGISTRY_RESOLVER_BLOCKED,
+          retryable: false,
+        },
+      ],
+    };
+  }
+}
+
+// ─── 2. Bounded file reader (§14.1, §14.2) ───────────────────────────────────
+
+export interface BoundedReadResult {
+  ok: boolean;
+  content?: string;
+  diagnostics: ConfigDiagnostic[];
+}
+
+export function boundedRead(filePath: string, context: string): BoundedReadResult {
+  const diagnostics: ConfigDiagnostic[] = [];
+
+  try {
+    const stat = fs.lstatSync(filePath);
+    if (stat.isSymbolicLink()) {
+      diagnostics.push({
+        code: 'CONFIG_ADAPTER_UNAVAILABLE',
+        message: `${context}: symlink input rejected`,
+        retryable: false,
+      });
+      return { ok: false, diagnostics };
+    }
+    if (!stat.isFile()) {
+      diagnostics.push({
+        code: 'CONFIG_ADAPTER_UNAVAILABLE',
+        message: `${context}: not a regular file`,
+        retryable: false,
+      });
+      return { ok: false, diagnostics };
+    }
+    if (stat.size > 1024 * 1024) {
+      diagnostics.push({
+        code: 'CONFIG_ADAPTER_UNAVAILABLE',
+        message: `${context}: file exceeds 1 MiB limit`,
+        retryable: false,
+      });
+      return { ok: false, diagnostics };
+    }
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return { ok: true, content, diagnostics: [] };
+  } catch (e) {
+    if (e instanceof Error && 'code' in e && e.code === 'ENOENT') {
+      diagnostics.push({
+        code: 'CONFIG_BLUEPRINT_MISSING',
+        message: `${context}: file not found at ${filePath}`,
+        retryable: false,
+      });
+      return { ok: false, diagnostics };
+    }
+    diagnostics.push({
+      code: 'CONFIG_ADAPTER_UNAVAILABLE',
+      message: `${context}: read error: ${e instanceof Error ? e.message : String(e)}`,
+      retryable: false,
+    });
+    return { ok: false, diagnostics };
+  }
+}
+
+// ─── 3. Bindings resolution (§5.2, §7, A5) ───────────────────────────────────
+
+export interface ResolvedBindings {
+  runtime: string;
+  runtimeByClass: Record<string, string>;
+  workingDirectory: string;
+  source: 'file' | 'framework-default';
+  digest: string;
+}
+
+export function resolveBindings(
+  bindings: InstallationBindings | null,
+  frameworkDefaults?: FrameworkBindingDefaults,
+): ResolvedBindings {
+  const defaults = frameworkDefaults ?? FRAMEWORK_BINDING_DEFAULTS;
+  if (!bindings) {
+    return {
+      runtime: defaults.runtime,
+      runtimeByClass: {},
+      workingDirectory: defaults.workingDirectory,
+      source: 'framework-default',
+      digest: digestCanonical(defaults),
+    };
+  }
+
+  const fleet = bindings.spec.fleet;
+  return {
+    runtime: fleet.runtime?.default ?? defaults.runtime,
+    runtimeByClass: fleet.runtime?.byClass ?? {},
+    workingDirectory: fleet.workingDirectory ?? defaults.workingDirectory,
+    source: 'file',
+    digest: digestCanonical(bindings),
+  };
+}
+
+// ─── 4. Git tracking/ignore probe (§7.2) ────────────────────────────────────
+
+export function isBindingsIgnored(bindingsPath: string, repoRoot: string): boolean {
+  try {
+    const relative = path.relative(repoRoot, bindingsPath);
+    if (relative.startsWith('..')) return true; // outside repo = not tracked
+
+    // Check if the file is tracked
+    try {
+      execSync(`git ls-files --error-unmatch "${relative}"`, {
+        cwd: repoRoot,
+        stdio: 'pipe',
+        env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' },
+      });
+      return false; // tracked = NOT ignored
+    } catch {
+      // Not tracked; check if ignored
+      try {
+        execSync(`git check-ignore "${relative}"`, {
+          cwd: repoRoot,
+          stdio: 'pipe',
+          env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' },
+        });
+        return true; // check-ignore succeeded = ignored
+      } catch {
+        return false; // not tracked but not ignored either = fail
+      }
+    }
+  } catch {
+    return true; // no git evidence = treat as ignored (valid absence)
+  }
+}
+
+// ─── 5. Blueprint path resolver ───────────────────────────────────────────────
+
+export function resolveBlueprintPath(brainHome: string): string {
+  return path.join(brainHome, 'fleet', 'configuration', 'installation.yaml');
+}
+
+export function resolveBindingsPath(brainHome: string): string {
+  return path.join(brainHome, 'config', 'installation.local.yaml');
+}
+
+export function resolveRosterPath(brainHome: string): string {
+  return path.join(brainHome, 'fleet', 'roster.yaml');
+}

packages/mosaic/src/config/installation/core.ts

@@ -0,0 +1,483 @@
+/**
+ * InstallationConfigCore — shared pure pipeline for validate and plan (§9).
+ *
+ * Both commands call this core in the same order. No mutation, no network,
+ * no subprocess. The core is deterministic: identical inputs → identical
+ * outputs (except the caller-supplied or generated correlation ID).
+ */
+import * as crypto from 'node:crypto';
+
+import {
+  type InstallationBlueprint,
+  type InstallationBindings,
+  type ConfigDiagnostic,
+  type ConfigValidationDataV1,
+  type ConfigPlanDataV1,
+  type ConfigPlanActionV1,
+  type ConfigPlanFieldDiff,
+  EXIT_OK,
+  EXIT_INVALID,
+  EXIT_NONCONFORMANT,
+  EXIT_UNAVAILABLE,
+  BOOTSTRAP_MINIMAL_V1,
+} from './types.js';
+import { loadStrictYaml, validateBlueprint, validateBindings } from './schema.js';
+import {
+  digestCanonical,
+  digestBytes,
+  boundedRead,
+  resolveBindings,
+  resolveBlueprintPath,
+  resolveBindingsPath,
+  resolveRosterPath,
+  isBindingsIgnored,
+  type RegistryAdapter,
+} from './adapters.js';
+
+// ─── Pipeline input/output ───────────────────────────────────────────────────
+
+export interface CoreInput {
+  registryAdapter: RegistryAdapter;
+  /** Explicit blueprint file path, or null to use --preset. */
+  filePath: string | null;
+  /** Preset ID, or null to use --file. */
+  presetId: string | null;
+  /** Resolved brainHome (from registry). */
+  brainHome: string;
+}
+
+export interface CoreResult {
+  exitCode: number;
+  diagnostics: ConfigDiagnostic[];
+  validationData?: ConfigValidationDataV1;
+  planData?: ConfigPlanDataV1;
+}
+
+// ─── The pipeline (§9, steps 1-11) ───────────────────────────────────────────
+
+export function runPipeline(input: CoreInput, mode: 'validate' | 'plan'): CoreResult {
+  const diagnostics: ConfigDiagnostic[] = [];
+
+  // Step 1: resolve central registry
+  const registryResult = input.registryAdapter.resolve();
+  diagnostics.push(...registryResult.diagnostics);
+  if (diagnostics.some((d) => d.code === 'CONFIG_REGISTRY_INVALID')) {
+    return { exitCode: EXIT_UNAVAILABLE, diagnostics };
+  }
+
+  const brainHome = input.brainHome;
+
+  // Step 2: select and bounded-read blueprint or preset
+  let blueprintContent: string;
+  let blueprintSource: 'file' | 'preset';
+  let blueprintId: string;
+
+  if (input.presetId) {
+    if (input.presetId !== BOOTSTRAP_MINIMAL_V1.id) {
+      diagnostics.push({
+        code: 'CONFIG_PRESET_UNKNOWN' as const,
+        message: `Unknown preset '${input.presetId}'. Available: ${BOOTSTRAP_MINIMAL_V1.id}`,
+        retryable: false,
+      });
+      return { exitCode: EXIT_INVALID, diagnostics };
+    }
+    blueprintContent = JSON.stringify(BOOTSTRAP_MINIMAL_V1.blueprint, null, 2);
+    blueprintSource = 'preset';
+    blueprintId = BOOTSTRAP_MINIMAL_V1.id;
+  } else {
+    const bpPath = input.filePath ?? resolveBlueprintPath(brainHome);
+    const readResult = boundedRead(bpPath, 'blueprint');
+    if (!readResult.ok) {
+      diagnostics.push(...readResult.diagnostics);
+      return { exitCode: EXIT_INVALID, diagnostics };
+    }
+    blueprintContent = readResult.content!;
+    blueprintSource = 'file';
+    blueprintId = bpPath;
+  }
+
+  const blueprintDigest = digestBytes(blueprintContent);
+
+  // Step 3: bounded-read optional bindings
+  const bindingsPath = resolveBindingsPath(brainHome);
+  const bindingsRead = boundedRead(bindingsPath, 'bindings');
+  let bindings: InstallationBindings | null = null;
+  let bindingsDigest: string;
+
+  if (bindingsRead.ok && bindingsRead.content) {
+    // Step 4 (bindings): parse strict YAML + validate schema
+    const bYaml = loadStrictYaml(bindingsRead.content, 'bindings');
+    if (!bYaml.ok) {
+      diagnostics.push(...bYaml.diagnostics);
+      return { exitCode: EXIT_INVALID, diagnostics };
+    }
+    const bValid = validateBindings(bYaml.value, 'bindings');
+    if (!bValid.ok) {
+      diagnostics.push(...bValid.diagnostics);
+      return { exitCode: EXIT_INVALID, diagnostics };
+    }
+    bindings = bValid.bindings!;
+
+    // §7.2: bindings must be ignored/untracked
+    if (!isBindingsIgnored(bindingsPath, brainHome)) {
+      diagnostics.push({
+        code: 'CONFIG_BINDINGS_NOT_IGNORED',
+        message: `Host bindings at ${bindingsPath} are tracked or not ignored`,
+        path: bindingsPath,
+        retryable: false,
+      });
+      return { exitCode: EXIT_INVALID, diagnostics };
+    }
+    bindingsDigest = digestCanonical(bindings);
+  } else if (bindingsRead.diagnostics.some((d) => d.code === 'CONFIG_BLUEPRINT_MISSING')) {
+    // Absent bindings = valid (§7.1)
+    bindingsDigest = digestCanonical(null);
+  } else {
+    diagnostics.push(...bindingsRead.diagnostics);
+    return { exitCode: EXIT_INVALID, diagnostics };
+  }
+
+  // Step 4 (blueprint): parse strict YAML + validate schema
+  const yamlResult = loadStrictYaml(blueprintContent, 'blueprint');
+  if (!yamlResult.ok) {
+    diagnostics.push(...yamlResult.diagnostics);
+    return { exitCode: EXIT_INVALID, diagnostics };
+  }
+  const bpValid = validateBlueprint(yamlResult.value, 'blueprint');
+  if (!bpValid.ok) {
+    diagnostics.push(...bpValid.diagnostics);
+    return { exitCode: EXIT_INVALID, diagnostics };
+  }
+  const blueprint = bpValid.blueprint!;
+
+  // Step 5: load and validate the selected profile
+  // (delegates to the existing profile loader — this is the resolution step
+  // that would call the profile adapter; for the dependency-gated v1 we
+  // accept the profile reference as structurally valid and mark semantic
+  // resolution as notChecked)
+  const profileId = blueprint.spec.fleet.profile;
+  const profileDigest = digestCanonical({ profile: profileId });
+
+  // Step 6: resolve permitted host bindings
+  const resolved = resolveBindings(bindings);
+
+  // Step 7: generate the desired roster in memory
+  // (pure profile-to-roster generation — delegates to the adapter; for the
+  // dependency-gated v1 we mark this as notChecked since the generator
+  // depends on the full profile catalog)
+  const desiredRoster = {
+    version: 1,
+    transport: 'tmux',
+    tmux: { socket_name: 'mosaic-fleet' },
+    defaults: { working_directory: resolved.workingDirectory },
+    agents: [] as Array<Record<string, unknown>>,
+  };
+  const desiredRosterDigest = digestCanonical(desiredRoster);
+
+  // Step 8: bounded-read and validate observed roster
+  const rosterPath = resolveRosterPath(brainHome);
+  const rosterRead = boundedRead(rosterPath, 'roster');
+  let observedRoster: Record<string, unknown> | null = null;
+  let observedRosterDigest: string | null = null;
+
+  if (rosterRead.ok && rosterRead.content) {
+    const rYaml = loadStrictYaml(rosterRead.content, 'roster');
+    if (!rYaml.ok) {
+      diagnostics.push(...rYaml.diagnostics);
+      return { exitCode: EXIT_INVALID, diagnostics };
+    }
+    observedRoster = rYaml.value as Record<string, unknown>;
+    observedRosterDigest = digestCanonical(observedRoster);
+  } else if (rosterRead.diagnostics.some((d) => d.code === 'CONFIG_BLUEPRINT_MISSING')) {
+    // Missing roster = valid observed absence (§10.1)
+    observedRoster = null;
+    observedRosterDigest = null;
+  } else {
+    diagnostics.push(...rosterRead.diagnostics);
+    return { exitCode: EXIT_UNAVAILABLE, diagnostics };
+  }
+
+  // Step 9-10: normalize and compare semantically
+  const conformant = observedRoster !== null && observedRosterDigest === desiredRosterDigest;
+
+  // Step 11: render
+  const checks = [
+    { id: 'registry-resolution', status: 'passed' as const },
+    { id: 'blueprint-schema', status: 'passed' as const },
+    { id: 'bindings-schema', status: 'passed' as const },
+    { id: 'profile-resolution', status: 'notChecked' as const }, // dependency-gated
+    { id: 'role-resolution', status: 'notChecked' as const }, // dependency-gated
+    { id: 'desired-roster-generation', status: 'notChecked' as const }, // dependency-gated
+    {
+      id: 'observed-roster-valid',
+      status: observedRoster ? ('passed' as const) : ('notChecked' as const),
+    },
+    { id: 'conformance', status: conformant ? ('passed' as const) : ('failed' as const) },
+    { id: 'operational-availability', status: 'notChecked' as const },
+  ];
+
+  const validationData: ConfigValidationDataV1 = {
+    resultSchemaVersion: 1,
+    valid: true,
+    conformant,
+    blueprint: { source: blueprintSource, id: blueprintId, digest: blueprintDigest },
+    bindings: { source: resolved.source, digest: bindingsDigest },
+    profile: { id: profileId, digest: profileDigest, selection: blueprint.spec.fleet.selection },
+    observed: { roster: observedRoster ? 'present' : 'absent', digest: observedRosterDigest },
+    checks,
+  };
+
+  if (!conformant) {
+    diagnostics.push({
+      code: 'CONFIG_NONCONFORMANT',
+      message: observedRoster
+        ? 'Observed roster differs from desired state within the v1 ownership mask'
+        : 'Observed roster is absent; desired state requires one',
+      retryable: false,
+    });
+    if (observedRoster === null) {
+      diagnostics.push({
+        code: 'CONFIG_ROSTER_MISSING' as const,
+        message: 'Observed roster absent at expected path',
+        retryable: false,
+      });
+    }
+  }
+
+  if (mode === 'validate') {
+    return {
+      exitCode: conformant ? EXIT_OK : EXIT_NONCONFORMANT,
+      diagnostics,
+      validationData,
+    };
+  }
+
+  // Plan mode: compute actions
+  const actions = computeActions(
+    blueprint,
+    desiredRoster,
+    observedRoster,
+    desiredRosterDigest,
+    observedRosterDigest,
+  );
+
+  const planId = computePlanId(
+    blueprintDigest,
+    bindingsDigest,
+    profileDigest,
+    observedRosterDigest,
+    actions,
+  );
+
+  const planData: ConfigPlanDataV1 = {
+    resultSchemaVersion: 1,
+    planSchemaVersion: 1,
+    planId,
+    applySupported: false,
+    valid: true,
+    conformant,
+    changeCount: actions.filter((a) => a.operation !== 'blocked').length,
+    blockedCount: actions.filter((a) => a.operation === 'blocked').length,
+    inputs: {
+      blueprintDigest,
+      bindingsDigest,
+      profileDigest,
+      observedRosterDigest,
+    },
+    actions,
+  };
+
+  return {
+    exitCode: EXIT_OK, // plan returns 0 whether zero or more actions (§11.1)
+    diagnostics,
+    validationData,
+    planData,
+  };
+}
+
+// ─── Action computation (§11.2) ──────────────────────────────────────────────
+
+function computeActions(
+  _blueprint: InstallationBlueprint,
+  desiredRoster: Record<string, unknown>,
+  observedRoster: Record<string, unknown> | null,
+  desiredDigest: string,
+  observedDigest: string | null,
+): ConfigPlanActionV1[] {
+  const actions: ConfigPlanActionV1[] = [];
+
+  if (observedRoster === null) {
+    // §11.2 rule 4: missing roster = one roster create + seat creates
+    actions.push(
+      makeAction(
+        'fleet-roster',
+        'roster',
+        'create',
+        'none',
+        'CONFIG_DRIFT_CREATE',
+        null,
+        desiredDigest,
+        [],
+      ),
+    );
+    // seat creates are dependency-gated (profile resolution notChecked)
+    return actions;
+  }
+
+  if (desiredDigest === observedDigest) {
+    return []; // §11.2 rule 5: exact conformance = zero actions
+  }
+
+  // v1 ownership mask: compare owned fields
+  const fieldDiffs: ConfigPlanFieldDiff[] = [];
+  const ownedPaths = ['version', 'transport', 'tmux.socket_name', 'defaults.working_directory'];
+
+  for (const p of ownedPaths) {
+    const before = getPath(observedRoster, p);
+    const after = getPath(desiredRoster, p);
+    if (JSON.stringify(before) !== JSON.stringify(after)) {
+      fieldDiffs.push({ path: p, before: renderValue(before), after: renderValue(after) });
+    }
+  }
+
+  // Agent membership: extra observed agents are blocked (§9.1)
+  const observedAgents = Array.isArray(observedRoster.agents)
+    ? (observedRoster.agents as Array<Record<string, unknown>>)
+    : [];
+  const desiredAgents = Array.isArray(desiredRoster.agents)
+    ? (desiredRoster.agents as Array<Record<string, unknown>>)
+    : [];
+
+  const desiredNames = new Set(desiredAgents.map((a) => String(a.name ?? '')));
+
+  for (const agent of observedAgents) {
+    const name = String(agent.name ?? '');
+    if (!desiredNames.has(name)) {
+      actions.push(
+        makeAction(
+          'fleet-seat',
+          name,
+          'blocked',
+          'full-engine-required',
+          'CONFIG_DRIFT_FULL_ENGINE_REQUIRED',
+          digestCanonical(agent),
+          null,
+          [],
+          ['full-engine: seat removal'],
+        ),
+      );
+    }
+  }
+
+  if (fieldDiffs.length > 0) {
+    actions.push(
+      makeAction(
+        'fleet-roster',
+        'roster',
+        'update',
+        'none',
+        'CONFIG_DRIFT_UPDATE',
+        observedDigest,
+        desiredDigest,
+        fieldDiffs,
+      ),
+    );
+  }
+
+  // Sort (§11.2 rule 6)
+  actions.sort((a, b) => {
+    if (a.resourceKind !== b.resourceKind) return a.resourceKind < b.resourceKind ? -1 : 1;
+    if (a.resourceId !== b.resourceId) return a.resourceId < b.resourceId ? -1 : 1;
+    if (a.operation !== b.operation) return a.operation < b.operation ? -1 : 1;
+    return 0;
+  });
+
+  return actions;
+}
+
+function makeAction(
+  resourceKind: 'fleet-roster' | 'fleet-seat',
+  resourceId: string,
+  operation: 'create' | 'update' | 'blocked',
+  risk: 'none' | 'review-required' | 'full-engine-required',
+  reasonCode: string,
+  beforeDigest: string | null,
+  afterDigest: string | null,
+  fieldDiffs: ConfigPlanFieldDiff[],
+  blockedBy: string[] = [],
+): ConfigPlanActionV1 {
+  const payload = {
+    resourceKind,
+    resourceId,
+    operation,
+    risk,
+    reasonCode,
+    beforeDigest,
+    afterDigest,
+    fieldDiffs,
+  };
+  const id = crypto
+    .createHash('sha256')
+    .update(JSON.stringify(sortKeys(payload)))
+    .digest('hex')
+    .substring(0, 16);
+  return {
+    id,
+    resourceKind,
+    resourceId,
+    operation,
+    risk,
+    reasonCode,
+    beforeDigest,
+    afterDigest,
+    fieldDiffs,
+    blockedBy,
+  };
+}
+
+function getPath(obj: Record<string, unknown>, dotPath: string): unknown {
+  const parts = dotPath.split('.');
+  let current: unknown = obj;
+  for (const part of parts) {
+    if (current === null || typeof current !== 'object') return null;
+    current = (current as Record<string, unknown>)[part] ?? null;
+  }
+  return current;
+}
+
+function renderValue(v: unknown): string | number | boolean | null {
+  if (v === null || v === undefined) return null;
+  if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') return v;
+  return JSON.stringify(v);
+}
+
+function sortKeys(value: unknown): unknown {
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(sortKeys);
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+    sorted[key] = sortKeys((value as Record<string, unknown>)[key]);
+  }
+  return sorted;
+}
+
+function computePlanId(
+  blueprintDigest: string,
+  bindingsDigest: string,
+  profileDigest: string,
+  observedRosterDigest: string | null,
+  actions: ConfigPlanActionV1[],
+): string {
+  const parts = {
+    planSchemaVersion: 1,
+    blueprintDigest,
+    bindingsDigest,
+    profileDigest,
+    observedRosterDigest: observedRosterDigest ?? 'absent',
+    actions: actions.map((a) => a.id),
+  };
+  return crypto
+    .createHash('sha256')
+    .update(JSON.stringify(sortKeys(parts)))
+    .digest('hex');
+}

packages/mosaic/src/config/installation/installation.spec.ts

@@ -0,0 +1,277 @@
+/**
+ * Installation config minimal-subset tests.
+ *
+ * Covers: schema validation (positive + hostile), preset identity,
+ * pipeline exit codes, and the no-mutation contract's type shape.
+ * The dependency-gated adapters are tested through their stubs.
+ */
+import { describe, it, expect, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+import { BOOTSTRAP_MINIMAL_V1, BLUEPRINT_API_VERSION, EXIT_UNAVAILABLE } from './types.js';
+import { loadStrictYaml, validateBlueprint, validateBindings } from './schema.js';
+import { runPipeline } from './core.js';
+import { BlockedRegistryAdapter, digestCanonical } from './adapters.js';
+import { renderJsonValidate, renderTableValidate } from './render.js';
+
+const SB = fs.mkdtempSync(path.join(os.tmpdir(), 'configimpl-test-'));
+
+describe('schema: strict YAML loader', () => {
+  it('accepts a valid single-document mapping', () => {
+    const result = loadStrictYaml('a: 1\nb: two', 'test');
+    expect(result.ok).toBe(true);
+  });
+
+  it('rejects multi-document YAML', () => {
+    const result = loadStrictYaml('a: 1\n---\nb: 2', 'test');
+    expect(result.ok).toBe(false);
+    expect(result.diagnostics[0]?.code).toBe('CONFIG_BLUEPRINT_SCHEMA');
+  });
+
+  it('rejects null/empty input', () => {
+    const result = loadStrictYaml('', 'test');
+    expect(result.ok).toBe(false);
+  });
+
+  it('rejects non-mapping top level', () => {
+    const result = loadStrictYaml('- just\n- a\n- list', 'test');
+    expect(result.ok).toBe(false);
+  });
+});
+
+describe('schema: blueprint validation', () => {
+  const validBlueprint = {
+    apiVersion: BLUEPRINT_API_VERSION,
+    kind: 'InstallationBlueprint',
+    metadata: { name: 'test', generation: 1 },
+    spec: { fleet: { profile: 'software-delivery', selection: 'floor' } },
+  };
+
+  it('accepts the valid canonical shape', () => {
+    const r = validateBlueprint(validBlueprint, 'test');
+    expect(r.ok).toBe(true);
+    expect(r.blueprint?.metadata.name).toBe('test');
+  });
+
+  it('rejects unknown top-level key', () => {
+    const r = validateBlueprint({ ...validBlueprint, extra: true }, 'test');
+    expect(r.ok).toBe(false);
+    expect(r.diagnostics.some((d) => d.message.includes("unknown top-level key 'extra'"))).toBe(
+      true,
+    );
+  });
+
+  it('rejects wrong apiVersion', () => {
+    const r = validateBlueprint({ ...validBlueprint, apiVersion: 'wrong' }, 'test');
+    expect(r.ok).toBe(false);
+  });
+
+  it('rejects wrong kind', () => {
+    const r = validateBlueprint({ ...validBlueprint, kind: 'Wrong' }, 'test');
+    expect(r.ok).toBe(false);
+  });
+
+  it('rejects invalid name (uppercase)', () => {
+    const r = validateBlueprint(
+      { ...validBlueprint, metadata: { ...validBlueprint.metadata, name: 'Bad' } },
+      'test',
+    );
+    expect(r.ok).toBe(false);
+  });
+
+  it('rejects generation < 1', () => {
+    const r = validateBlueprint(
+      { ...validBlueprint, metadata: { ...validBlueprint.metadata, generation: 0 } },
+      'test',
+    );
+    expect(r.ok).toBe(false);
+  });
+
+  it('rejects invalid selection', () => {
+    const r = validateBlueprint(
+      {
+        ...validBlueprint,
+        spec: { fleet: { profile: 'test', selection: 'partial' } },
+      },
+      'test',
+    );
+    expect(r.ok).toBe(false);
+  });
+
+  it('rejects unknown spec key', () => {
+    const r = validateBlueprint(
+      {
+        ...validBlueprint,
+        spec: { fleet: validBlueprint.spec.fleet, extra: 1 },
+      },
+      'test',
+    );
+    expect(r.ok).toBe(false);
+  });
+});
+
+describe('schema: bindings validation', () => {
+  const validBindings = {
+    apiVersion: BLUEPRINT_API_VERSION,
+    kind: 'InstallationBindings',
+    spec: {
+      fleet: {
+        runtime: { default: 'pi' },
+        workingDirectory: '~/src',
+      },
+    },
+  };
+
+  it('accepts the valid canonical shape', () => {
+    const r = validateBindings(validBindings, 'test');
+    expect(r.ok).toBe(true);
+  });
+
+  it('rejects empty spec', () => {
+    const r = validateBindings(
+      { apiVersion: BLUEPRINT_API_VERSION, kind: 'InstallationBindings', spec: {} },
+      'test',
+    );
+    expect(r.ok).toBe(false);
+  });
+
+  it('rejects unknown fleet key', () => {
+    const r = validateBindings(
+      {
+        ...validBindings,
+        spec: { fleet: { ...validBindings.spec.fleet, socket: 'override' } },
+      },
+      'test',
+    );
+    expect(r.ok).toBe(false);
+  });
+
+  it('rejects relative workingDirectory', () => {
+    const r = validateBindings(
+      {
+        ...validBindings,
+        spec: { fleet: { workingDirectory: 'relative/path' } },
+      },
+      'test',
+    );
+    expect(r.ok).toBe(false);
+  });
+
+  it('rejects control bytes in workingDirectory', () => {
+    const r = validateBindings(
+      {
+        ...validBindings,
+        spec: { fleet: { workingDirectory: '/tmp/\x00bad' } },
+      },
+      'test',
+    );
+    expect(r.ok).toBe(false);
+  });
+});
+
+describe('preset: bootstrap-minimal@1', () => {
+  it('has the correct ID', () => {
+    expect(BOOTSTRAP_MINIMAL_V1.id).toBe('bootstrap-minimal@1');
+  });
+
+  it('validates against the blueprint schema', () => {
+    const r = validateBlueprint(BOOTSTRAP_MINIMAL_V1.blueprint, 'preset');
+    expect(r.ok).toBe(true);
+  });
+
+  it('selects software-delivery floor per A4', () => {
+    expect(BOOTSTRAP_MINIMAL_V1.blueprint.spec.fleet.profile).toBe('software-delivery');
+    expect(BOOTSTRAP_MINIMAL_V1.blueprint.spec.fleet.selection).toBe('floor');
+  });
+});
+
+describe('core: pipeline', () => {
+  it('returns EXIT_UNAVAILABLE when registry is dependency-blocked', () => {
+    const result = runPipeline(
+      {
+        registryAdapter: new BlockedRegistryAdapter(),
+        filePath: null,
+        presetId: null,
+        brainHome: SB,
+      },
+      'validate',
+    );
+    expect(result.exitCode).toBe(EXIT_UNAVAILABLE);
+    expect(result.diagnostics.some((d) => d.code === 'CONFIG_REGISTRY_INVALID')).toBe(true);
+  });
+
+  it('returns EXIT_INVALID for unknown preset', () => {
+    // NOTE: registry is blocked, so this test would hit the registry gate first.
+    // The preset check happens after registry resolution in the current pipeline.
+    // This is documented as the dependency-gate behavior.
+    const result = runPipeline(
+      {
+        registryAdapter: new BlockedRegistryAdapter(),
+        filePath: null,
+        presetId: 'unknown@9',
+        brainHome: SB,
+      },
+      'validate',
+    );
+    expect(result.exitCode).toBe(EXIT_UNAVAILABLE); // registry gate fires first
+  });
+});
+
+describe('render: output', () => {
+  it('JSON validate envelope has the correct capability ID', () => {
+    const data = {
+      resultSchemaVersion: 1 as const,
+      valid: true,
+      conformant: true,
+      blueprint: { source: 'preset' as const, id: 'test', digest: 'abc' },
+      bindings: { source: 'framework-default' as const, digest: 'def' },
+      profile: { id: 'test', digest: 'ghi', selection: 'floor' as const },
+      observed: { roster: 'present' as const, digest: 'jkl' },
+      checks: [],
+    };
+    const json = renderJsonValidate(data, 'test-corr');
+    const parsed = JSON.parse(json);
+    expect(parsed.capabilityId).toBe('config.installation.validate');
+    expect(parsed.status).toBe('succeeded');
+    expect(parsed.correlationId).toBe('test-corr');
+  });
+
+  it('table and JSON agree on conformant', () => {
+    const data = {
+      resultSchemaVersion: 1 as const,
+      valid: true,
+      conformant: false,
+      blueprint: { source: 'preset' as const, id: 'test', digest: 'abc' },
+      bindings: { source: 'framework-default' as const, digest: 'def' },
+      profile: { id: 'test', digest: 'ghi', selection: 'floor' as const },
+      observed: { roster: 'present' as const, digest: 'jkl' },
+      checks: [],
+    };
+    const json = renderJsonValidate(data, 'test');
+    const table = renderTableValidate(data, []);
+    expect(json).toContain('"conformant": false');
+    expect(table).toContain('Conformant:  false');
+  });
+});
+
+describe('digest: determinism', () => {
+  it('produces identical digests for identical inputs with different key order', () => {
+    const a = { z: 1, a: { y: 2, b: 3 } };
+    const b = { a: { b: 3, y: 2 }, z: 1 };
+    expect(digestCanonical(a)).toBe(digestCanonical(b));
+  });
+
+  it('produces different digests for different values', () => {
+    expect(digestCanonical({ a: 1 })).not.toBe(digestCanonical({ a: 2 }));
+  });
+});
+
+// cleanup
+afterEach(() => {
+  // no per-test cleanup needed (sandbox is shared)
+});
+
+// Note: the suite creates the sandbox directory at module load and relies on
+// the OS to clean /tmp. For CI, a trap would be added. This is documented.

packages/mosaic/src/config/installation/render.ts

@@ -0,0 +1,127 @@
+/**
+ * Table and JSON renderers for validate and plan results (§12).
+ *
+ * Table is a human rendering of the same envelope. Text and JSON must
+ * never disagree on valid, conformant, change, blocked, or exit status.
+ */
+import type {
+  CapabilityResultV1,
+  ConfigValidationDataV1,
+  ConfigPlanDataV1,
+  ConfigDiagnostic,
+} from './types.js';
+
+// ─── JSON renderer ────────────────────────────────────────────────────────────
+
+export function renderJsonValidate(data: ConfigValidationDataV1, correlationId: string): string {
+  const envelope: CapabilityResultV1<ConfigValidationDataV1> = {
+    capabilityId: 'config.installation.validate',
+    status: data.conformant ? 'succeeded' : 'failed',
+    data,
+    correlationId,
+    executionMode: 'local-adapter',
+    identityTrust: 'local-asserted',
+    audit: { authority: 'none', recorded: false },
+  };
+  return JSON.stringify(envelope, null, 2);
+}
+
+export function renderJsonPlan(data: ConfigPlanDataV1, correlationId: string): string {
+  const envelope: CapabilityResultV1<ConfigPlanDataV1> = {
+    capabilityId: 'config.installation.plan',
+    status: 'succeeded', // plan always succeeds (§11.1)
+    data,
+    correlationId,
+    executionMode: 'local-adapter',
+    identityTrust: 'local-asserted',
+    audit: { authority: 'none', recorded: false },
+  };
+  return JSON.stringify(envelope, null, 2);
+}
+
+// ─── Table renderer (§12) ─────────────────────────────────────────────────────
+
+export function renderTableValidate(
+  data: ConfigValidationDataV1,
+  diagnostics: ConfigDiagnostic[],
+): string {
+  const lines: string[] = [];
+  lines.push('Installation Validation');
+  lines.push('======================');
+  lines.push('');
+  lines.push(`Valid:       ${data.valid}`);
+  lines.push(`Conformant:  ${data.conformant}`);
+  lines.push(
+    `Blueprint:   ${data.blueprint.source === 'preset' ? data.blueprint.id : data.blueprint.id} (${data.blueprint.digest.substring(0, 12)}…)`,
+  );
+  lines.push(`Bindings:    ${data.bindings.source} (${data.bindings.digest.substring(0, 12)}…)`);
+  lines.push(`Profile:     ${data.profile.id} / ${data.profile.selection}`);
+  lines.push(
+    `Roster:      ${data.observed.roster}${data.observed.digest ? ` (${data.observed.digest.substring(0, 12)}…)` : ''}`,
+  );
+  lines.push('');
+  lines.push('Checks:');
+  for (const check of data.checks) {
+    const icon = check.status === 'passed' ? '✓' : check.status === 'failed' ? '✗' : '–';
+    lines.push(`  ${icon} ${check.id}: ${check.status}`);
+  }
+  if (diagnostics.length > 0) {
+    lines.push('');
+    lines.push('Diagnostics:');
+    for (const d of diagnostics) {
+      lines.push(`  [${d.code}] ${d.message}`);
+    }
+  }
+  lines.push('');
+  lines.push('Details:');
+  lines.push(`  blueprint digest:  ${data.blueprint.digest}`);
+  lines.push(`  bindings digest:   ${data.bindings.digest}`);
+  lines.push(`  profile digest:    ${data.profile.digest}`);
+  lines.push(`  observed digest:   ${data.observed.digest ?? '(absent)'}`);
+  return lines.join('\n');
+}
+
+export function renderTablePlan(data: ConfigPlanDataV1): string {
+  const lines: string[] = [];
+  lines.push('Installation Plan');
+  lines.push('=================');
+  lines.push('');
+  lines.push(`Conformant:  ${data.conformant}`);
+  lines.push(`Changes:     ${data.changeCount}`);
+  lines.push(`Blocked:     ${data.blockedCount}`);
+  lines.push(`Apply:       not supported (read-only v1)`);
+  lines.push(`Plan ID:     ${data.planId}`);
+  lines.push('');
+  if (data.actions.length === 0) {
+    lines.push('No actions — installation is conformant.');
+  } else {
+    lines.push('Actions:');
+    for (const action of data.actions) {
+      lines.push(`  [${action.operation}] ${action.resourceKind}/${action.resourceId}`);
+      lines.push(`    reason: ${action.reasonCode}  risk: ${action.risk}`);
+      if (action.fieldDiffs.length > 0) {
+        for (const fd of action.fieldDiffs) {
+          lines.push(`    ${fd.path}: ${JSON.stringify(fd.before)} → ${JSON.stringify(fd.after)}`);
+        }
+      }
+      if (action.blockedBy.length > 0) {
+        lines.push(`    blocked by: ${action.blockedBy.join(', ')}`);
+      }
+    }
+  }
+  lines.push('');
+  lines.push('Inputs:');
+  lines.push(`  blueprint digest:  ${data.inputs.blueprintDigest}`);
+  lines.push(`  bindings digest:   ${data.inputs.bindingsDigest}`);
+  lines.push(`  profile digest:    ${data.inputs.profileDigest}`);
+  lines.push(`  observed digest:   ${data.inputs.observedRosterDigest ?? '(absent)'}`);
+  return lines.join('\n');
+}
+
+// ─── Correlation ID ───────────────────────────────────────────────────────────
+
+export function makeCorrelationId(): string {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const random = Math.random().toString(36).substring(2, 8);
+  return `config-${timestamp}-${random}`;
+}

packages/mosaic/src/config/installation/schema.ts

@@ -0,0 +1,450 @@
+/**
+ * Strict YAML schema validation for blueprint and bindings.
+ *
+ * §6/§7 of the spec: closed mappings, no aliases/anchors/merges/tags,
+ * single document, strict type checking on every field.
+ */
+import * as yaml from 'yaml';
+import {
+  BLUEPRINT_API_VERSION,
+  BLUEPRINT_KIND,
+  BINDINGS_KIND,
+  type InstallationBlueprint,
+  type InstallationBindings,
+  type FleetSelection,
+  type ConfigDiagnostic,
+} from './types.js';
+
+const MAX_INPUT_BYTES = 1024 * 1024; // 1 MiB (§14.1)
+
+// ─── Strict YAML loader (§14.4) ──────────────────────────────────────────────
+
+export interface StrictYamlResult {
+  ok: boolean;
+  value?: unknown;
+  diagnostics: ConfigDiagnostic[];
+}
+
+export function loadStrictYaml(content: string, context: string): StrictYamlResult {
+  const diagnostics: ConfigDiagnostic[] = [];
+
+  if (content.length > MAX_INPUT_BYTES) {
+    diagnostics.push({
+      code: 'CONFIG_BLUEPRINT_SCHEMA',
+      message: `${context} exceeds 1 MiB limit (${content.length} bytes)`,
+      retryable: false,
+    });
+    return { ok: false, diagnostics };
+  }
+
+  if (content.includes('\n---\n') || content.trimStart().startsWith('---')) {
+    diagnostics.push({
+      code: 'CONFIG_BLUEPRINT_SCHEMA',
+      message: `${context}: multiple YAML documents rejected`,
+      retryable: false,
+    });
+    return { ok: false, diagnostics };
+  }
+
+  let value: unknown;
+  try {
+    value = yaml.parse(content, { strict: true, mapAsMap: false });
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (
+      content.includes('&') ||
+      content.includes('*') ||
+      content.includes('<<') ||
+      content.includes('!')
+    ) {
+      diagnostics.push({
+        code: 'CONFIG_BLUEPRINT_SCHEMA',
+        message: `${context}: YAML aliases/anchors/merges/tags rejected`,
+        retryable: false,
+      });
+    } else {
+      diagnostics.push({
+        code: 'CONFIG_BLUEPRINT_SCHEMA',
+        message: `${context}: YAML parse error: ${msg.substring(0, 200)}`,
+        retryable: false,
+      });
+    }
+    return { ok: false, diagnostics };
+  }
+
+  if (value === null || value === undefined) {
+    diagnostics.push({
+      code: 'CONFIG_BLUEPRINT_SCHEMA',
+      message: `${context}: empty document`,
+      retryable: false,
+    });
+    return { ok: false, diagnostics };
+  }
+
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    diagnostics.push({
+      code: 'CONFIG_BLUEPRINT_SCHEMA',
+      message: `${context}: top level must be a mapping`,
+      retryable: false,
+    });
+    return { ok: false, diagnostics };
+  }
+
+  return { ok: true, value, diagnostics };
+}
+
+// ─── ID grammar (§6.2) ───────────────────────────────────────────────────────
+
+const ID_PATTERN = /^[a-z][a-z0-9-]{0,62}$/;
+
+export function isValidId(id: string): boolean {
+  return ID_PATTERN.test(id);
+}
+
+// ─── Blueprint validation (§6) ───────────────────────────────────────────────
+
+const BLUEPRINT_TOP_KEYS = new Set(['apiVersion', 'kind', 'metadata', 'spec']);
+const BLUEPRINT_METADATA_KEYS = new Set(['name', 'generation']);
+const BLUEPRINT_SPEC_KEYS = new Set(['fleet']);
+const BLUEPRINT_FLEET_KEYS = new Set(['profile', 'selection']);
+
+export function validateBlueprint(
+  value: unknown,
+  context: string,
+): { ok: boolean; blueprint?: InstallationBlueprint; diagnostics: ConfigDiagnostic[] } {
+  const diagnostics: ConfigDiagnostic[] = [];
+  const obj = value as Record<string, unknown>;
+
+  for (const key of Object.keys(obj)) {
+    if (!BLUEPRINT_TOP_KEYS.has(key)) {
+      diagnostics.push({
+        code: 'CONFIG_BLUEPRINT_SCHEMA',
+        message: `${context}: unknown top-level key '${key}'`,
+        path: key,
+        retryable: false,
+      });
+    }
+  }
+
+  if (obj.apiVersion !== BLUEPRINT_API_VERSION) {
+    diagnostics.push({
+      code: 'CONFIG_BLUEPRINT_SCHEMA',
+      message: `${context}: apiVersion must be exactly '${BLUEPRINT_API_VERSION}'`,
+      path: 'apiVersion',
+      retryable: false,
+    });
+  }
+
+  if (obj.kind !== BLUEPRINT_KIND) {
+    diagnostics.push({
+      code: 'CONFIG_BLUEPRINT_SCHEMA',
+      message: `${context}: kind must be exactly '${BLUEPRINT_KIND}'`,
+      path: 'kind',
+      retryable: false,
+    });
+  }
+
+  if (!obj.metadata || typeof obj.metadata !== 'object') {
+    diagnostics.push({
+      code: 'CONFIG_BLUEPRINT_SCHEMA',
+      message: `${context}: metadata is required`,
+      path: 'metadata',
+      retryable: false,
+    });
+  } else {
+    const meta = obj.metadata as Record<string, unknown>;
+    for (const key of Object.keys(meta)) {
+      if (!BLUEPRINT_METADATA_KEYS.has(key)) {
+        diagnostics.push({
+          code: 'CONFIG_BLUEPRINT_SCHEMA',
+          message: `${context}: unknown metadata key '${key}'`,
+          path: `metadata.${key}`,
+          retryable: false,
+        });
+      }
+    }
+    if (typeof meta.name !== 'string' || !isValidId(meta.name)) {
+      diagnostics.push({
+        code: 'CONFIG_BLUEPRINT_SCHEMA',
+        message: `${context}: metadata.name must match [a-z][a-z0-9-]{0,62}`,
+        path: 'metadata.name',
+        retryable: false,
+      });
+    }
+    if (
+      typeof meta.generation !== 'number' ||
+      !Number.isInteger(meta.generation) ||
+      meta.generation < 1
+    ) {
+      diagnostics.push({
+        code: 'CONFIG_BLUEPRINT_SCHEMA',
+        message: `${context}: metadata.generation must be an integer >= 1`,
+        path: 'metadata.generation',
+        retryable: false,
+      });
+    }
+  }
+
+  if (!obj.spec || typeof obj.spec !== 'object') {
+    diagnostics.push({
+      code: 'CONFIG_BLUEPRINT_SCHEMA',
+      message: `${context}: spec is required`,
+      path: 'spec',
+      retryable: false,
+    });
+  } else {
+    const spec = obj.spec as Record<string, unknown>;
+    for (const key of Object.keys(spec)) {
+      if (!BLUEPRINT_SPEC_KEYS.has(key)) {
+        diagnostics.push({
+          code: 'CONFIG_BLUEPRINT_SCHEMA',
+          message: `${context}: unknown spec key '${key}'`,
+          path: `spec.${key}`,
+          retryable: false,
+        });
+      }
+    }
+
+    if (!spec.fleet || typeof spec.fleet !== 'object') {
+      diagnostics.push({
+        code: 'CONFIG_BLUEPRINT_SCHEMA',
+        message: `${context}: spec.fleet is required`,
+        path: 'spec.fleet',
+        retryable: false,
+      });
+    } else {
+      const fleet = spec.fleet as Record<string, unknown>;
+      for (const key of Object.keys(fleet)) {
+        if (!BLUEPRINT_FLEET_KEYS.has(key)) {
+          diagnostics.push({
+            code: 'CONFIG_BLUEPRINT_SCHEMA',
+            message: `${context}: unknown fleet key '${key}'`,
+            path: `spec.fleet.${key}`,
+            retryable: false,
+          });
+        }
+      }
+      if (typeof fleet.profile !== 'string' || !isValidId(fleet.profile)) {
+        diagnostics.push({
+          code: 'CONFIG_BLUEPRINT_SCHEMA',
+          message: `${context}: spec.fleet.profile must match [a-z][a-z0-9-]{0,62}`,
+          path: 'spec.fleet.profile',
+          retryable: false,
+        });
+      }
+      if (fleet.selection !== 'floor' && fleet.selection !== 'full') {
+        diagnostics.push({
+          code: 'CONFIG_BLUEPRINT_SCHEMA',
+          message: `${context}: spec.fleet.selection must be 'floor' or 'full'`,
+          path: 'spec.fleet.selection',
+          retryable: false,
+        });
+      }
+    }
+  }
+
+  if (diagnostics.length > 0) {
+    return { ok: false, diagnostics };
+  }
+
+  const fleet = (obj.spec as Record<string, unknown>).fleet as Record<string, unknown>;
+  const meta = obj.metadata as Record<string, unknown>;
+  const blueprint: InstallationBlueprint = {
+    apiVersion: BLUEPRINT_API_VERSION,
+    kind: BLUEPRINT_KIND,
+    metadata: {
+      name: meta.name as string,
+      generation: meta.generation as number,
+    },
+    spec: {
+      fleet: {
+        profile: fleet.profile as string,
+        selection: fleet.selection as FleetSelection,
+      },
+    },
+  };
+
+  return { ok: true, blueprint, diagnostics: [] };
+}
+
+// ─── Bindings validation (§7) ────────────────────────────────────────────────
+
+const BINDINGS_TOP_KEYS = new Set(['apiVersion', 'kind', 'spec']);
+const BINDINGS_SPEC_KEYS = new Set(['fleet']);
+const BINDINGS_FLEET_KEYS = new Set(['runtime', 'workingDirectory']);
+const BINDINGS_RUNTIME_KEYS = new Set(['default', 'byClass']);
+
+export function validateBindings(
+  value: unknown,
+  context: string,
+): { ok: boolean; bindings?: InstallationBindings; diagnostics: ConfigDiagnostic[] } {
+  const diagnostics: ConfigDiagnostic[] = [];
+  const obj = value as Record<string, unknown>;
+
+  for (const key of Object.keys(obj)) {
+    if (!BINDINGS_TOP_KEYS.has(key)) {
+      diagnostics.push({
+        code: 'CONFIG_BINDINGS_SCHEMA',
+        message: `${context}: unknown top-level key '${key}'`,
+        path: key,
+        retryable: false,
+      });
+    }
+  }
+
+  if (obj.apiVersion !== BLUEPRINT_API_VERSION) {
+    diagnostics.push({
+      code: 'CONFIG_BINDINGS_SCHEMA',
+      message: `${context}: apiVersion must be exactly '${BLUEPRINT_API_VERSION}'`,
+      path: 'apiVersion',
+      retryable: false,
+    });
+  }
+
+  if (obj.kind !== BINDINGS_KIND) {
+    diagnostics.push({
+      code: 'CONFIG_BINDINGS_SCHEMA',
+      message: `${context}: kind must be exactly '${BINDINGS_KIND}'`,
+      path: 'kind',
+      retryable: false,
+    });
+  }
+
+  if (!obj.spec || typeof obj.spec !== 'object' || Object.keys(obj.spec).length === 0) {
+    diagnostics.push({
+      code: 'CONFIG_BINDINGS_SCHEMA',
+      message: `${context}: spec is required and non-empty (empty bindings file is invalid)`,
+      path: 'spec',
+      retryable: false,
+    });
+  } else {
+    const spec = obj.spec as Record<string, unknown>;
+    for (const key of Object.keys(spec)) {
+      if (!BINDINGS_SPEC_KEYS.has(key)) {
+        diagnostics.push({
+          code: 'CONFIG_BINDINGS_SCHEMA',
+          message: `${context}: unknown spec key '${key}'`,
+          path: `spec.${key}`,
+          retryable: false,
+        });
+      }
+    }
+
+    if (spec.fleet) {
+      const fleet = spec.fleet as Record<string, unknown>;
+      for (const key of Object.keys(fleet)) {
+        if (!BINDINGS_FLEET_KEYS.has(key)) {
+          diagnostics.push({
+            code: 'CONFIG_BINDINGS_SCHEMA',
+            message: `${context}: unknown fleet key '${key}'`,
+            path: `spec.fleet.${key}`,
+            retryable: false,
+          });
+        }
+      }
+
+      if (fleet.runtime) {
+        const runtime = fleet.runtime as Record<string, unknown>;
+        for (const key of Object.keys(runtime)) {
+          if (!BINDINGS_RUNTIME_KEYS.has(key)) {
+            diagnostics.push({
+              code: 'CONFIG_BINDINGS_SCHEMA',
+              message: `${context}: unknown runtime key '${key}'`,
+              path: `spec.fleet.runtime.${key}`,
+              retryable: false,
+            });
+          }
+        }
+        if (
+          runtime.default !== undefined &&
+          (typeof runtime.default !== 'string' || !isValidId(runtime.default))
+        ) {
+          diagnostics.push({
+            code: 'CONFIG_BINDINGS_SCHEMA',
+            message: `${context}: runtime.default must match [a-z][a-z0-9-]{0,62}`,
+            path: 'spec.fleet.runtime.default',
+            retryable: false,
+          });
+        }
+        if (runtime.byClass !== undefined && runtime.byClass !== null) {
+          if (typeof runtime.byClass !== 'object' || runtime.byClass === null) {
+            diagnostics.push({
+              code: 'CONFIG_BINDINGS_SCHEMA',
+              message: `${context}: runtime.byClass must be a mapping`,
+              path: 'spec.fleet.runtime.byClass',
+              retryable: false,
+            });
+          } else {
+            for (const [cls, rt] of Object.entries(runtime.byClass)) {
+              if (!isValidId(cls)) {
+                diagnostics.push({
+                  code: 'CONFIG_BINDINGS_SCHEMA',
+                  message: `${context}: byClass key '${cls}' must match [a-z][a-z0-9-]{0,62}`,
+                  path: `spec.fleet.runtime.byClass.${cls}`,
+                  retryable: false,
+                });
+              }
+              if (typeof rt !== 'string' || !isValidId(rt)) {
+                diagnostics.push({
+                  code: 'CONFIG_BINDINGS_SCHEMA',
+                  message: `${context}: byClass value for '${cls}' must match [a-z][a-z0-9-]{0,62}`,
+                  path: `spec.fleet.runtime.byClass.${cls}`,
+                  retryable: false,
+                });
+              }
+            }
+          }
+        }
+      }
+
+      if (fleet.workingDirectory !== undefined) {
+        const wd = fleet.workingDirectory;
+        if (typeof wd !== 'string') {
+          diagnostics.push({
+            code: 'CONFIG_BINDINGS_SCHEMA',
+            message: `${context}: workingDirectory must be a string`,
+            path: 'spec.fleet.workingDirectory',
+            retryable: false,
+          });
+        } else {
+          if (/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(wd)) {
+            diagnostics.push({
+              code: 'CONFIG_BINDINGS_SCHEMA',
+              message: `${context}: workingDirectory contains control characters`,
+              path: 'spec.fleet.workingDirectory',
+              retryable: false,
+            });
+          }
+          if (!wd.startsWith('/') && !wd.startsWith('~/')) {
+            diagnostics.push({
+              code: 'CONFIG_BINDINGS_SCHEMA',
+              message: `${context}: workingDirectory must be absolute or ~/ prefixed`,
+              path: 'spec.fleet.workingDirectory',
+              retryable: false,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  if (diagnostics.length > 0) {
+    return { ok: false, diagnostics };
+  }
+
+  const fleet = (obj.spec as Record<string, unknown>).fleet as Record<string, unknown> | undefined;
+  const bindings: InstallationBindings = {
+    apiVersion: BLUEPRINT_API_VERSION,
+    kind: BINDINGS_KIND,
+    spec: {
+      fleet: fleet
+        ? {
+            runtime: fleet.runtime as InstallationBindings['spec']['fleet']['runtime'] | undefined,
+            workingDirectory: fleet.workingDirectory as string | undefined,
+          }
+        : {},
+    },
+  };
+
+  return { ok: true, bindings, diagnostics: [] };
+}

packages/mosaic/src/config/installation/types.ts

@@ -0,0 +1,216 @@
+/**
+ * Shared type contracts for the installation config minimal subset.
+ *
+ * Spec: docs/specs/2026-08-29_mosaic-config-minimal-subset.md (spec review
+ * PASS deff617d by rev-code-02; implementation per CONFIGIMPL-GO).
+ *
+ * These types are the single source of truth for the blueprint, bindings,
+ * result, action, and diagnostic shapes. The YAML schemas in schema.ts and
+ * the result renderers in render.ts consume these interfaces directly.
+ */
+
+// ─── Blueprint (§6) ───────────────────────────────────────────────────────────
+
+export const BLUEPRINT_API_VERSION = 'config.mosaicstack.dev/v1alpha1';
+export const BLUEPRINT_KIND = 'InstallationBlueprint';
+export const BINDINGS_KIND = 'InstallationBindings';
+export const PRESET_ID = 'bootstrap-minimal@1';
+
+export type FleetSelection = 'floor' | 'full';
+
+export interface InstallationBlueprint {
+  apiVersion: typeof BLUEPRINT_API_VERSION;
+  kind: typeof BLUEPRINT_KIND;
+  metadata: {
+    name: string;
+    generation: number;
+  };
+  spec: {
+    fleet: {
+      profile: string;
+      selection: FleetSelection;
+    };
+  };
+}
+
+// ─── Bindings (§7) ────────────────────────────────────────────────────────────
+
+export interface InstallationBindings {
+  apiVersion: typeof BLUEPRINT_API_VERSION;
+  kind: typeof BINDINGS_KIND;
+  spec: {
+    fleet: {
+      runtime?: {
+        default?: string;
+        byClass?: Record<string, string>;
+      };
+      workingDirectory?: string;
+    };
+  };
+}
+
+// ─── Framework defaults (§7, A5) ─────────────────────────────────────────────
+
+export interface FrameworkBindingDefaults {
+  runtime: string;
+  workingDirectory: string;
+}
+
+export const FRAMEWORK_BINDING_DEFAULTS: FrameworkBindingDefaults = {
+  runtime: 'claude',
+  workingDirectory: '~',
+};
+
+// ─── Preset (§8) ──────────────────────────────────────────────────────────────
+
+export interface PackagedPreset {
+  id: typeof PRESET_ID;
+  blueprint: InstallationBlueprint;
+}
+
+export const BOOTSTRAP_MINIMAL_V1: PackagedPreset = {
+  id: 'bootstrap-minimal@1',
+  blueprint: {
+    apiVersion: 'config.mosaicstack.dev/v1alpha1',
+    kind: 'InstallationBlueprint',
+    metadata: {
+      name: 'bootstrap-minimal',
+      generation: 1,
+    },
+    spec: {
+      fleet: {
+        profile: 'software-delivery',
+        selection: 'floor',
+      },
+    },
+  },
+};
+
+// ─── Diagnostics (§13) ────────────────────────────────────────────────────────
+
+export type DiagnosticCode =
+  | 'CONFIG_USAGE_INVALID'
+  | 'CONFIG_REGISTRY_INVALID'
+  | 'CONFIG_BLUEPRINT_MISSING'
+  | 'CONFIG_BLUEPRINT_SCHEMA'
+  | 'CONFIG_BINDINGS_SCHEMA'
+  | 'CONFIG_BINDINGS_NOT_IGNORED'
+  | 'CONFIG_PRESET_UNKNOWN'
+  | 'CONFIG_PROFILE_UNRESOLVED'
+  | 'CONFIG_ROLE_UNRESOLVED'
+  | 'CONFIG_DESIRED_ROSTER_INVALID'
+  | 'CONFIG_OBSERVED_ROSTER_INVALID'
+  | 'CONFIG_ROSTER_MISSING'
+  | 'CONFIG_NONCONFORMANT'
+  | 'CONFIG_DRIFT_CREATE'
+  | 'CONFIG_DRIFT_UPDATE'
+  | 'CONFIG_DRIFT_FULL_ENGINE_REQUIRED'
+  | 'CONFIG_ADAPTER_UNAVAILABLE';
+
+export interface ConfigDiagnostic {
+  code: DiagnosticCode;
+  message: string;
+  path?: string;
+  retryable: boolean;
+}
+
+// ─── Registry provenance (§5, §2.2) ──────────────────────────────────────────
+
+export interface RegistryProvenance {
+  resolved: boolean;
+  brainHome: string | null;
+  sourceKeys: Array<{ key: string; sourceClass: string }>;
+}
+
+// ─── Validation result (§12.1) ───────────────────────────────────────────────
+
+export interface ConfigCheckResult {
+  id: string;
+  status: 'passed' | 'failed' | 'notChecked';
+}
+
+export interface ConfigValidationDataV1 {
+  resultSchemaVersion: 1;
+  valid: boolean;
+  conformant: boolean;
+  blueprint: { source: 'file' | 'preset'; id: string; digest: string };
+  bindings: { source: 'file' | 'framework-default'; digest: string };
+  profile: { id: string; digest: string; selection: FleetSelection };
+  observed: { roster: 'present' | 'absent'; digest: string | null };
+  checks: ConfigCheckResult[];
+}
+
+// ─── Plan result (§12.2, §11.2) ─────────────────────────────────────────────
+
+export type ConfigPlanOperationV1 = 'create' | 'update' | 'blocked';
+export type ConfigRiskV1 = 'none' | 'review-required' | 'full-engine-required';
+
+export interface ConfigPlanFieldDiff {
+  path: string;
+  before: string | number | boolean | null;
+  after: string | number | boolean | null;
+}
+
+export interface ConfigPlanActionV1 {
+  id: string;
+  resourceKind: 'fleet-roster' | 'fleet-seat';
+  resourceId: string;
+  operation: ConfigPlanOperationV1;
+  risk: ConfigRiskV1;
+  reasonCode: string;
+  beforeDigest: string | null;
+  afterDigest: string | null;
+  fieldDiffs: ConfigPlanFieldDiff[];
+  blockedBy: string[];
+}
+
+export interface ConfigPlanDataV1 {
+  resultSchemaVersion: 1;
+  planSchemaVersion: 1;
+  planId: string;
+  applySupported: false;
+  valid: true;
+  conformant: boolean;
+  changeCount: number;
+  blockedCount: number;
+  inputs: {
+    blueprintDigest: string;
+    bindingsDigest: string;
+    profileDigest: string;
+    observedRosterDigest: string | null;
+  };
+  actions: ConfigPlanActionV1[];
+}
+
+// ─── Result envelope (§12) ────────────────────────────────────────────────────
+
+export interface CapabilityResultV1<T> {
+  capabilityId: string;
+  status: 'succeeded' | 'failed' | 'invalid';
+  data?: T;
+  diagnostics?: ConfigDiagnostic[];
+  correlationId: string;
+  executionMode: 'local-adapter';
+  identityTrust: 'local-asserted';
+  audit: { authority: 'none'; recorded: boolean };
+}
+
+// ─── Exit codes (§10.3) ──────────────────────────────────────────────────────
+
+export const EXIT_OK = 0;
+export const EXIT_INVALID = 2;
+export const EXIT_RESERVED_SCOPE = 3;
+export const EXIT_NONCONFORMANT = 4;
+export const EXIT_UNAVAILABLE = 6;
+
+// ─── Dependency gate marker (§2.2) ───────────────────────────────────────────
+
+/**
+ * DEPENDENCY GATE: the approved MosaicRegistryResolver does not exist at
+ * the pinned baseline. The registry-consuming work is PARKED. This marker
+ * interface exists so that when the reviewed resolver ships, the adapter
+ * binds to it without schema changes. Until then, the adapter returns
+ * CONFIG_REGISTRY_INVALID with the dependency-blocked message.
+ */
+export const REGISTRY_RESOLVER_BLOCKED =
+  'MosaicRegistryResolver: dependency-blocked pending reviewed resolver (CFG-REQ-001..006 charter)';