@@ -0,0 +1,95 @@
+# 2026-08-12 — the isolation gradient (D-042) + FlexIR trust knobs as floors (D-043)
+
+Ratified by maintainer decisions D-042 and D-043 (dspy decision log,
+`MaximeRivest-dspy/roadmap/05-decisions.md`, both 2026-08-12; design
+source: `roadmap/linux-isolation-notes.md` Q9–Q16 and spec
+`§e0-isolation`). Spec + schema + law commit; no fixtures change in this
+commit (L8) — the fixture families for the new refusal codes and the
+gradient corpus follow as their own wave.
+
+What changed in this commit:
+
+1. **`spec/placement.md`** — the isolation-gradient section (RATIFIED):
+   the ordered closed vocabulary v1.0
+   (`none < namespace < fork < fork_cgroup < fork_ratchet < sandbox <
+   remote`), comparable by position, stamped `versions.isolation`;
+   floors-bake/envelopes-bind; binding-level floors with
+   max-composition (node-set byte shape deferred to the next node-set
+   wave — the leaf object's optional `isolation_floor`);
+   floor-lowering-as-artifact-edit with `floor_lowered_by`; run/score
+   envelope provenance (View-2/View-3); grants orthogonal to level;
+   invariance + identity-boundary rules; the sealed-memfd/JSON data
+   plane; the broker egress rule (credential injection — supersedes
+   env-passed values for below-full-trust leaves); the unified leaf
+   substrate summary. Placement sketch gains `isolation_floor`.
+2. **`spec/invariants.md`** — new law family, append-only:
+   - **PIR-015** — ordered/versioned gradient; floors bake, envelopes
+     bind; under-floor refuses.
+   - **PIR-016** — binding-level floors compose by max (tighten only).
+   - **PIR-017** — floor-lowering is an artifact edit with
+     `floor_lowered_by` provenance, never an engine flag.
+   - **PIR-018** — envelope provenance in runs (View-2) and scores
+     (View-3); grants orthogonal to level, unsupplied grants refuse at
+     load.
+   - **PIR-019** — isolation invariance; profile-unsatisfying runtimes
+     are D-033 identity deviations, never isolation levels; divergence
+     across levels is a candidate refusal class in optimization.
+   - **PIR-020** — one data-plane contract, two transports
+     (sealed-memfd Arrow local / JSON-typed wire remote); resolves the
+     D-027 `vars`-marshaling open surface.
+   - **PIR-021** — the unified leaf substrate: shared tool/interpreter
+     record, closed invocation discriminant (`call`|`session`), grants
+     as a closed static effect row, fork-scoped sessions at
+     `fork_ratchet`+, nested cost attribution.
+3. **`spec/errors.md`** — the VERIFY family gains `-004` (envelope
+   under-runs the effective floor, names leaf + floor + envelope) and
+   `-005` (declared grant unsupplied, names grant + leaf). Additive.
+4. **`spec/versions.md`** — the `isolation` vocabulary entry under the
+   extra-entry rule (same pattern as `interpreter_profile`): artifacts
+   using the gradient stamp `versions.isolation = "1.0"`.
+5. **`spec/manifest.md`** — the structural-profile `isolation_floor`
+   bullet cites the vocabulary; the canonical `vars_marshaling`
+   resolution paragraph (PIR-020); the new unified-leaf-substrate
+   section (D-043) with its additive byte shapes.
+6. **`spec/trust.md`** (PROPOSED status unchanged) — the `hardened`
+   example's `isolation ≥ os_sandbox` updated to the D-042 vocabulary
+   (`fork_ratchet`); ratification ask 5 marked satisfied by
+   D-042/D-043.
+7. **`schema/manifest.schema.json`** — `$defs/isolation_level` (the
+   closed ordered enum), `$defs/floor_provenance`, `$defs/grant`;
+   `placement.isolation` closes to the enum (+ null); placement gains
+   optional `isolation_floor` and `floor_lowered_by`; tool entries gain
+   optional `kind` (`call`|`session`) and `grants[]`; structural
+   interpreter entries type `isolation_floor` by the enum and gain
+   optional `kind_invocation` and `grants[]` (`kind_invocation`, not
+   `kind`, because bare `kind` is the legacy fused-profile
+   discriminator and would break the entry `oneOf`). All existing
+   fixtures validate unchanged (`isolation`/`isolation_floor` observed
+   values are all `"none"`).
+8. **`schema/README.md`** — placement-block bullet updated.
+
+Deliberately NOT in this commit:
+
+- The node-set leaf object's optional `isolation_floor` (the
+  binding-level floor's byte shape) — a node-set surface change, so it
+  rides the next node-set version wave with reference + corpus + port
+  catch-up, per the D-034/D-037/D-041 precedent. The law (PIR-016)
+  binds now at the manifest level.
+- Fixture families for `PIR-E-VERIFY-004`/`-005`, the gradient corpus,
+  and the View-2/View-3 envelope record shapes — follow-on waves.
+- Sidecar wire contract text (the data plane names transports, not
+  frames) — still out of 1.0 scope.
+
+Evidence: dspy decision log D-042 (isolation gradient: ordered
+vocabulary, revocable-vs-ratchet split, sealed-memfd data plane,
+floors/envelopes, invariance, identity boundary) and D-043 (FlexIR
+trust knobs are floor declarations, not enforcement: `code_trust` →
+floor aliases, enforcement at the materialize seam only, kernel-backed
+`lm_calls` cheapness, broker egress with credential injection,
+per-candidate scoring envelopes, the unified leaf substrate). Design
+notes: `MaximeRivest-dspy/roadmap/linux-isolation-notes.md`
+(conversation record, 2026-08-12).
+
+Affects: `spec/placement.md`, `spec/invariants.md`, `spec/errors.md`,
+`spec/versions.md`, `spec/manifest.md`, `spec/trust.md`,
+`schema/manifest.schema.json`, `schema/README.md`.
@@ -65,8 +65,15 @@ the other.
   (strategies, codecs, literal_table, transforms, parsers) are the
   **adapter-ir contract's** to pin, not this repo's.
 - **Placement blocks**: `{rung, contract, endpoint_ref, default_endpoint,
-  isolation, credential_ref}` (`spec/placement.md`); `rung` is an open
-  string (the ladder vocabulary is not ratified as closed).
+  isolation, isolation_floor?, floor_lowered_by?, credential_ref}`
+  (`spec/placement.md`); `rung` is an open string (the ladder vocabulary
+  is not ratified as closed). `isolation`/`isolation_floor` draw from the
+  D-042 ordered closed vocabulary v1.0 (`none < namespace < fork <
+  fork_cgroup < fork_ratchet < sandbox < remote`), stamped
+  `versions.isolation`; `floor_lowered_by` is the PIR-017 lowering
+  provenance. Tool entries and structural interpreter entries gain the
+  optional D-043 unified-leaf fields (`kind`/`kind_invocation`,
+  `grants[]`).
 - **Credentials**: `{name, scope}` and nothing else — a `value` key is a
   schema violation, making PIR-005 structural.
 - **Languages**: `packaged`/`authored` code identities require `language`
 
@@ -110,8 +110,16 @@
           "description": "Advisory default URL for endpoint_ref, spec/placement.md placement block."
         },
         "isolation": {
-          "type": ["string", "null"],
-          "description": "Isolation level, spec/placement.md placement block. Observed: 'none'. No closed vocabulary ratified."
+          "enum": ["none", "namespace", "fork", "fork_cgroup", "fork_ratchet", "sandbox", "remote", null],
+          "description": "The receiver's isolation envelope, spec/placement.md isolation gradient (D-042, ratified 2026-08-12): the ordered closed vocabulary v1.0, comparable by position (PIR-015). Artifacts using the gradient stamp versions.isolation = '1.0' (spec/versions.md). Null reads as unset (receiver default)."
+        },
+        "isolation_floor": {
+          "$ref": "#/$defs/isolation_level",
+          "description": "Optional baked minimum isolation demand on this placement (D-042; PIR-015): the receiver's envelope may exceed the floor, never under-run it -- under-floor is a loud load refusal (PIR-E-VERIFY-004). Mirrors the interpreter structural profile's required isolation_floor."
+        },
+        "floor_lowered_by": {
+          "$ref": "#/$defs/floor_provenance",
+          "description": "Provenance of a floor-lowering edit (D-042; PIR-017): lowering a floor is an artifact edit producing a new artifact version, never an engine flag. Absent when the floor was never lowered."
         },
         "credential_ref": {
           "type": ["string", "null"],
@@ -121,6 +129,53 @@
       "required": ["rung", "contract"],
       "additionalProperties": false
     },
+    "isolation_level": {
+      "enum": ["none", "namespace", "fork", "fork_cgroup", "fork_ratchet", "sandbox", "remote"],
+      "description": "The ordered isolation vocabulary v1.0 (D-042, spec/placement.md): none < namespace < fork < fork_cgroup < fork_ratchet < sandbox < remote. Ordering is normative -- 'floor' is defined by position comparison (PIR-015). Closed; extension is a versioned act (versions.isolation)."
+    },
+    "floor_provenance": {
+      "type": "object",
+      "description": "The floor-lowering provenance record (D-042 point 7; PIR-017): who lowered the floor, when, from what to what. Rides the placement block of the edited entry.",
+      "properties": {
+        "by": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Who signed for the lowered floor (PIR-014 provenance discipline)."
+        },
+        "date": {
+          "type": "string",
+          "minLength": 1,
+          "description": "When the floor was lowered."
+        },
+        "old": {
+          "$ref": "#/$defs/isolation_level",
+          "description": "The floor before the edit."
+        },
+        "new": {
+          "$ref": "#/$defs/isolation_level",
+          "description": "The floor after the edit (strictly lower than old -- raising needs no edit; it is a binding)."
+        }
+      },
+      "required": ["by", "date", "old", "new"],
+      "additionalProperties": false
+    },
+    "grant": {
+      "type": "object",
+      "description": "One entry of the closed static effect row (D-043 unified leaf substrate; PIR-021): a capability the parent explicitly hands the leaf. Grants are orthogonal to the isolation level -- every envelope must supply every declared grant or load refuses (PIR-E-VERIFY-005; PIR-018).",
+      "properties": {
+        "kind": {
+          "enum": ["fd", "broker_route"],
+          "description": "Closed grant kind: 'fd' -- a passed/inherited file descriptor (sealed-memfd data plane, listening sockets); 'broker_route' -- a hostname route through the parent-owned broker proxy (D-043: credential injection, per-request log)."
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The grant's name: the FD's declared role, or the broker route's hostname pattern."
+        }
+      },
+      "required": ["kind", "name"],
+      "additionalProperties": false
+    },
     "code_identity": {
       "type": "object",
       "description": "A declared code identity for packaged/authored entries (PIR-003 declare-don't-discover; PIR-014 provenance). Used by LM entries' `class`.",
@@ -457,7 +512,16 @@
         },
         "authored_by": {
           "type": "string",
-          "description": "PIR-014 provenance for machine-written tool code."
+          "description": "PIR-014 provenance for machine-written tool code. Under D-043, 'optimizer' defaults the leaf's binding-level isolation floor through the receiver's trust profile (spec/trust.md)."
+        },
+        "kind": {
+          "enum": ["call", "session"],
+          "description": "Optional unified-leaf-substrate invocation discriminant (D-043; PIR-021): 'call' -- one request/response (the default when absent); 'session' -- a held stateful context, fork-scoped (lifetime = leaf span) at fork_ratchet and above."
+        },
+        "grants": {
+          "type": "array",
+          "items": {"$ref": "#/$defs/grant"},
+          "description": "The closed static effect row (D-043; PIR-021): every capability this leaf may be handed, readable from the manifest without executing anything. Absent means no grants."
         }
       },
       "required": ["return_schema", "source", "deps", "language", "placement"],
@@ -533,13 +597,21 @@
           "description": "Declared resource limits; empty means no limits are claimed."
         },
         "isolation_floor": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Least isolation this identity permits; placement may move outward, never inward."
+          "$ref": "#/$defs/isolation_level",
+          "description": "Least isolation this identity permits, drawn from the ordered vocabulary (D-042, spec/placement.md; PIR-015); placement may move outward, never inward."
         },
         "placement": {
           "$ref": "#/$defs/placement",
           "description": "Receiver-controlled execution placement."
+        },
+        "kind_invocation": {
+          "enum": ["call", "session"],
+          "description": "Optional unified-leaf-substrate invocation discriminant (D-043; PIR-021); interpreters default to 'session'. Named kind_invocation here because 'kind' is the legacy fused-profile discriminator."
+        },
+        "grants": {
+          "type": "array",
+          "items": {"$ref": "#/$defs/grant"},
+          "description": "The closed static effect row (D-043; PIR-021). Absent means no grants."
         }
       },
       "required": [
 
@@ -14,7 +14,7 @@ Python type names).
 | `MANIFEST` | parse/schema/malformed | `-001` unreadable JSON · `-002` schema violation naming path · `-003` missing versions block |
 | `VERSION` | versions block mismatches | `-001` unknown major, names entry + both versions |
 | `LINK` | dangling refs | `-001` binding names absent pool entry · `-002` delta without entry |
-| `VERIFY` | declared-tier verification | `-001` credential unresolved (names name+scope) · `-002` endpoint serves wrong identity · `-003` system dep missing |
+| `VERIFY` | declared-tier verification | `-001` credential unresolved (names name+scope) · `-002` endpoint serves wrong identity · `-003` system dep missing · `-004` envelope under-runs the effective isolation floor (names leaf + floor + envelope; D-042, PIR-015/016) · `-005` declared grant unsupplied by the envelope (names grant + leaf; D-042/D-043, PIR-018) |
 | `NODE` | node-set compile refusal | `-001` un-whitelisted node (names node kind + location) · `-002` unresolved call (names target + location) · `-003` record-splat key refused — splat/kwarg collision or callee-unaccepted key (names key + location; D-041) · `-004` write to the read-only input record (names record + location; D-041) |
 | `LANG` | cross-language / rung-walk | `-001` no satisfiable rung (names component + language + rungs tried). Adapter-layer code never enters the walk (D-026) — its refusal is `PROFILE`, not `LANG` |
 | `PROFILE` | profile predicate | `-001` clause violated (names clause id) · `-002` authored-origin adapter code present (the D-026 refusal) |
 
@@ -86,6 +86,73 @@ design-intent style with ratification date.
   shipped score and the baked metric re-warrants. WHY (dspy L11;
   IR-program-spec §e0-binding).
 
+## Isolation discipline (D-042/D-043, ratified 2026-08-12)
+
+- **PIR-015 — The isolation gradient is ordered and versioned; floors
+  bake, envelopes bind.** `isolation` values come from the closed ordered
+  vocabulary `none < namespace < fork < fork_cgroup < fork_ratchet <
+  sandbox < remote` (v1.0, stamped `versions.isolation`); comparison is by
+  position. The artifact bakes a *floor* (`isolation_floor` on the
+  interpreter structural profile and on tool placement); the receiver's
+  actual envelope is a *binding* that may exceed the floor, never
+  under-run it — under-floor is a loud load refusal
+  (`PIR-E-VERIFY-004`). The gradient is an axis orthogonal to the rung.
+  WHY (D-042, 2026-08-12): the 3-value enum could not express the real
+  continuum from one-RAM/one-process to full lockdown, and had no floor
+  semantics for optimizer-authored code.
+- **PIR-016 — Binding-level floors compose by max.** A leaf's binding may
+  carry an `isolation_floor` override; the effective floor at a leaf =
+  max(entry floor, binding floor). Floors tighten per binding, never
+  loosen. WHY (D-042 point 6): per-leaf trust distinctions (author's
+  helper vs optimizer-generated body on the same runtime entry) must
+  never force a floor-fork of a byte-identical pool entry — sharing an
+  entry is a stated fact about identity.
+- **PIR-017 — Lowering a floor is an artifact edit, never an engine
+  flag.** Lowering produces a new artifact version with
+  `floor_lowered_by {by, date, old, new}` in provenance; raising the
+  envelope stays a binding. WHY (D-042 point 7): a runtime override flag
+  would make the artifact lie about how it runs; an edit is visible in a
+  diff, auditable, and scoped to one copy.
+- **PIR-018 — Envelope provenance; grants are orthogonal to level.**
+  Every run records the actual envelope used per leaf (View-2); every
+  score carries the envelope it was measured under (View-3). A leaf's
+  declared grants must be supplied by the envelope at *any* level or load
+  refuses (`PIR-E-VERIFY-005`) — "stopped working under stricter
+  isolation" is never a silent runtime surprise. WHY (D-042 point 7,
+  D-043 point 5): the record is what makes the invariance law a checkable
+  claim; optimizer trajectories carry the same per-candidate envelope.
+- **PIR-019 — Isolation invariance; the identity boundary.** A leaf must
+  behave identically at every isolation level; a level change that
+  changes behavior indicts the leaf (undeclared side channels), never the
+  level. Every level runs the leaf's declared interpreter profile (D-033)
+  unchanged; a runtime that cannot satisfy the profile is an *identity
+  deviation* under D-033 (refusal, or a recorded deviation that detaches
+  scores), never a higher isolation level — `remote` means the same
+  profile satisfied elsewhere. In optimization, a divergence across
+  levels is a candidate refusal class (D-043 point 5). WHY (D-042 points
+  5 and 8): this is what keeps the gradient a binding rather than an
+  identity axis, so scores stay warranted across isolation re-placement.
+- **PIR-020 — One data-plane contract, two transports.** Local-rung leaf
+  inputs/outputs travel as sealed shared memory (memfd + write-seal,
+  Arrow IPC), the FD passed as the capability grant; remote rungs use the
+  JSON-typed wire form. The leaf's typed contract is identical over both.
+  This is the resolution of the D-027 open `vars`-marshaling surface.
+  WHY (D-042 point 4): sealing makes inputs immutable to hostile bodies;
+  an FD crosses every wall on the gradient, so data sharing costs nothing
+  in isolation strength.
+- **PIR-021 — The unified leaf substrate.** Tools and interpreters share
+  one leaf record shape: a closed invocation discriminant (`call` — one
+  request/response — | `session` — a held stateful context) and grants as
+  a closed static effect row (`fd` | `broker_route`), readable from the
+  manifest without executing anything. Session leaves at `fork_ratchet`+
+  are fork-scoped: lifetime = leaf span. Nested cost attribution: an LM
+  call made through a grant bridge attributes to both the session leaf
+  that made it and the underlying predictor it reached, transitively.
+  WHY (D-043 point 6): interpreter and tool were always two spellings of
+  "a leaf that executes a body under a profile"; every knob (floor,
+  grants, placement, authorship) lands on both, and static grant rows
+  keep the trust surface auditable without simulation.
+
 ---
 
 Status: DRAFT, unratified. Numbering starts here; append only.