pi-lens 4.3.0 → 4.4.1

package/docs/rfcs/3654-unified-io-bridge-v2.md

@@ -0,0 +1,316 @@
+# RFC 3654: Unified File I/O Lifecycle Bridge (v2 Specification)
+
+**Status:** Accepted by the maintainer on #4145 (2026-10-08)  
+**Tracking Issue:** [apmantza/pi-lens#3654](https://github.com/apmantza/pi-lens/issues/3654)  
+**Related Issues/PRs:** #3651 (multi-span batching), #3652 (0-line reads), #3650 (mutating-tool path), #3785 (read-guard evidence & FileTime), #2465 (no-read-guard split), #3620 (lineage fence)  
+**Authors:** Architecture Council (`lens-orchestrator`, `council-peer`)  
+
+---
+
+## 1. Executive Summary & Teleological Frame
+
+### Problem
+Pi coding-agent extensions interacting with the filesystem outside pi-lens's native tool hooks currently face severe friction and architectural fragmentation:
+1. **Dual Bridge Overhead**: Producers performing atomic edit + preview-diff turns must call two separate global symbol bridges: `Symbol.for("pi-lens:mutation-bridge")` then `Symbol.for("pi-lens:read-bridge")`.
+2. **Redundant Synchronous I/O (#3651)**: `ReadBridge.recordRead` executes two synchronous `fs.readFileSync` calls per read (one for `captureReadContentBinding` and one for `captureLineHashes`), even when the producer already holds file content in memory.
+3. **Absence of Delete Lifecycle**: Programmatic file deletion is unrepresented in existing bridges, leaving zombie records in `readGuard.reads`, `writtenThisSession`, and `knownPathIndex`.
+4. **Ordering & Freshness Hazards**: Concurrent writers and multi-window reads risk desynchronizing `FileTime` and read evidence if the mutation and read facets are not executed in strict atomic sequence.
+
+### Proposed Outcome
+A unified, cohesive File I/O Lifecycle Bridge mounted at `Symbol.for("pi-lens:io-bridge")` carrying `readonly version: 2`, consolidating file observation (`read`), partial modification (`edit`), whole-file authorship (`write`), and deletion (`delete`) into an atomic, synchronous, non-throwing contract. Existing v1 bridges are preserved as zero-overhead shims mounted in the same first-wins pass.
+
+---
+
+## 2. Non-Negotiable Architectural Decisions (D1–D13)
+
+| ID | Decision | Invariant & Enforcement |
+|---|---|---|
+| **D1** | **Symbol Key & Version** | `Symbol.for("pi-lens:io-bridge")` + `readonly version: 2`. Policy: `version` covers minors; breaking majors require a new symbol key (first-wins frozen per-process slot). In the same first-wins pass, mount v1 shims for `pi-lens:read-bridge` and `pi-lens:mutation-bridge` preserving v1 return types (`void` and `boolean`). |
+| **D2** | **Mutation Umbrella Name** | The mutation facet is named **`mutate`** (not `write`), because `delete` is an absence event, not a write. |
+| **D3** | **`delete` Primitive** | `delete` is a `kind` under `mutate` (`mutate: { kind: "delete" }`), wrapped by the enclosing `!getFlag("no-read-guard")` gate, followed by the 4 confirmed-delete gates in production order, shared with the native bash path through `judgeConfirmedDelete` (`clients/confirmed-delete.ts`): (1) `isExternalOrVendorFile`, (2) `isPathIgnoredByProject`, (3) `readGuard.hasKnownPath`, (4) `!existsSync` confirm. Action: `readGuard.forgetPath(filePath)` and, when `!getFlag("no-lsp")`, `notifyExternalFileChange(filePath, 3)`. `no-lsp` suppresses only the notification; the native bash path skips the whole delete under `no-lsp`. Bypasses `recordWritten` and `addModifiedRange`; emits no change-log receipt. |
+| **D4** | **`rename` Deferred** | Compose as `delete(old)` + `write(new)`. Dead fields like `renamedFrom` are omitted from v2 until an active consumer exists. |
+| **D5** | **Read Evidence Policy** | Default is **coverage-only** (`evidence: "caller"` with no content/hashes binds range without line hashes). `"disk"` is an explicit opt-in for bridge-initiated disk hashing. The bridge never synthesizes hash evidence unless `"disk"` is passed. |
+| **D6** | **`content` Semantics** | Delivered raw text starting at `ranges[0][0]` (span-relative). No caller-fabricated `contentBinding`; whole-file staleness checks stay disk-derived only. |
+| **D7** | **Span Constraints** | `lineHashes` is keyed by absolute 1-indexed line numbers and supports multi-span reads. `content` is valid **only** with a single contiguous range (`ranges.length === 1`). |
+| **D8** | **Hash Map Typing** | `lineHashes` is `Record<number, string>` (keys integers $\ge 1$), matching `ReadRecord.lineHashes`. |
+| **D9** | **Never Throws** | `record()` never throws. Malformed, out-of-scope, or ignored calls return `{ accepted: false, reason: RecordReason }`. Hash keys outside declared ranges are rejected with `"malformed"`. |
+| **D10** | **Independent Facet Outcomes** | Facets apply independently; `record()` returns `{ read?: RecordOutcome, mutate?: RecordOutcome }`. |
+| **D11** | **Accessor Idiom** | `getIOBridge()` returns `undefined` on version mismatch (mirroring v1). |
+| **D12** | **Public API Stability** | Add section to `docs/public-api-stability.md` designating `PiLensIOBridge` as public API from day one, linking `docs/io-bridge-v2-migration.md`, with changelog fragment audience `user`. |
+| **D13** | **TLA+ & Governance Plan** | PR implementation must add row in `formal/coverage-map.json` mapping `clients/io-bridge.ts` to `[session-lifecycle, read-guard]`; verify write-before-read and lineage fence invariants, or cite `TLA+ unaffected`. |
+| **D14** | **Backward-Compatible Refinement** | v1 behavior may be refined in v2, but v1's observable behavior MUST NOT break. v1 shims (`read-bridge`, `mutation-bridge`) are a frozen compatibility layer. Every input v1 accepted, v1 accepts; same return types; same effective guard/cache key; same display path. Detailed mappings live in `docs/io-bridge-v2-migration.md`. |
+
+---
+
+## 3. Normative TypeScript Interface
+
+```typescript
+/**
+ * Generic File I/O Lifecycle Bridge for pi-lens (v2).
+ * Mounts at globalThis[IO_BRIDGE_SYMBOL].
+ */
+
+export const IO_BRIDGE_SYMBOL = Symbol.for("pi-lens:io-bridge");
+export const IO_BRIDGE_VERSION = 2 as const;
+
+/** 1-indexed closed line interval: [start, end] where start <= end. */
+export type LineRange = [start: number, end: number];
+
+/** Map of 1-indexed line numbers to alphanumeric line-content hashes. */
+export type LineHashMap = Record<number, string>;
+
+export interface ReadFacet {
+  /**
+   * 1-indexed line ranges delivered to the model. REQUIRED.
+   * `[]` represents an explicit zero-line / 0-byte read (#3652).
+   * Full-file read is represented by `[[1, lineCount]]`.
+   */
+  ranges: LineRange[];
+
+  /**
+   * Delivered raw text starting at ranges[0][0].
+   * Valid ONLY when ranges.length === 1 (single contiguous span).
+   */
+  content?: string;
+
+  /**
+   * Precomputed alphanumeric line hashes keyed by absolute 1-indexed line numbers.
+   * Supports multi-span reads. All keys must fall within declared ranges.
+   */
+  lineHashes?: LineHashMap;
+
+  /**
+   * Evidence collection mode:
+   * - "caller" (default): Use content / lineHashes if provided. If neither is provided,
+   *   records coverage-only with NO hashes (no disk reads performed).
+   * - "disk": Bridge synchronously disk-reads and hashes the declared ranges.
+   */
+  evidence?: "caller" | "disk";
+}
+
+export type MutationFacet =
+  | {
+      /** Partial file modification (line replacement / splice). */
+      kind: "edit";
+      /** 1-indexed line ranges modified. Must be non-empty. */
+      ranges: LineRange[];
+      /**
+       * Whether to queue deferred autofix and formatting for agent_settled.
+       * Defaults to true. When true, publishes `pilens:format:queued` on `pi.events`
+       * for newly-queued files (resolving the v1 event drop in mutation-bridge).
+       * Set to false to suppress both queueing and event emission.
+       */
+      deferAutofix?: boolean;
+      importsChanged?: boolean;
+    }
+  | {
+      /** Whole-file authorship (creation or complete replacement). */
+      kind: "write";
+      // The authored bytes are not part of v2 yet: binding creation read
+      // evidence from them is #3524's design (G9), and the field had no
+      // consumer (#4145 review F4).
+      /**
+       * Whether to queue deferred autofix and formatting for agent_settled.
+       * Defaults to true. When true, publishes `pilens:format:queued` on `pi.events`
+       * for newly-queued files. Set to false to suppress both queueing and event emission.
+       */
+      deferAutofix?: boolean;
+      importsChanged?: boolean;
+    }
+  | {
+      /**
+       * Lifecycle deletion: removes file from read records, writtenThisSession,
+       * and knownPathIndex, and notifies LSP DidClose / FileChangeType.Deleted (3).
+       * Mutually exclusive with `read`. Never calls recordWritten and emits no change-log receipt.
+       * Requires file to no longer exist on disk at the moment of recording.
+       */
+      kind: "delete";
+    };
+
+export interface BridgeEntry {
+  /**
+   * Path to the file. Non-empty string.
+   * Preserves caller's raw display path verbatim (matching v1 read-bridge.ts:137-139
+   * and mutation-bridge.ts:322). Scope check runs deps.isRecordable(filePath) directly
+   * on the input string without pre-resolving; internal map keying is handled downstream
+   * via normalizeFilePath / normalizeEphemeralMapKey.
+   */
+  filePath: string;
+
+  /** Optional caller identity for logging and telemetry (e.g. "my-tool"). */
+  consumer?: string;
+
+  /** Mutation facet (at most one). */
+  mutate?: MutationFacet;
+
+  /** Read facet (at most one). Mutually exclusive with mutate.kind: "delete". */
+  read?: ReadFacet;
+}
+
+export type RecordReason =
+  | "malformed"
+  | "out-of-scope"
+  | "ignored"
+  | "no-read-guard"
+  | "stale-lineage"
+  | "bookkeeping-error";
+
+export type RecordOutcome =
+  | { accepted: true }
+  | { accepted: false; reason: RecordReason };
+
+export interface RecordResult {
+  read?: RecordOutcome;
+  mutate?: RecordOutcome;
+}
+
+export interface PiLensIOBridge {
+  readonly version: 2;
+  /**
+   * Synchronously records file I/O operations.
+   * Atomic: executes mutate before read.
+   * Evaluates per-facet scope and #2465 flag gates.
+   * Never throws.
+   */
+  record(entry: BridgeEntry): RecordResult;
+}
+
+/** Convenience accessor performing symbol lookup + version === 2 check. */
+export function getIOBridge(): PiLensIOBridge | undefined;
+```
+
+---
+
+## 4. Keel Architectural Review
+
+| Keel Dimension | Concern | Current Design / Trap | Defect / Risk | Proposed Normative Rule | Justification |
+|---|---|---|---|---|---|
+| **Authority** | Path Normalization (§3, F1) | Pre-resolving `filePath` against `deps.getProjectRoot()` at the bridge entry. | Clobbers the caller's raw display path and creates key divergence if resolution semantics drift from `ReadGuard.key()` / `normalizeFilePath`. Violates AGENTS Shape #1 and display-path preservation. | `filePath` MUST be a non-empty string (`typeof filePath === "string" && filePath.length > 0`). Evaluated via `deps.isRecordable(filePath)` directly. The bridge NEVER pre-resolves or clobbers `filePath`. Internal canonicalization and map keying remain strictly encapsulated in downstream owners (`ReadGuard.key()` via `normalizeFilePath` and `normalizeEphemeralMapKey`). | Preserves exact v1 shim parity (`read-bridge.ts:137-139`, `mutation-bridge.ts:322`), preserves original caller display paths, and prevents divergent path keys. |
+| **Negative Path** | Invariant Conflict (§5) | `mutate: { kind: "delete" }` combined with `read`. | Contradictory state: deleting a file while binding a read on it creates a zombie read record on an absent file. | Validation strictly rejects `mutate.kind === "delete" && read !== undefined` with `{ accepted: false, reason: "malformed" }` for both facets. | Preserves invariant closure: an absent file has no read coverage. |
+| **Negative Path** | Contiguous Span Bounds (§5) | `content` passed with `ranges.length !== 1`. | Unclear line mapping if multiple disjoint ranges are passed with one text buffer. | If `content !== undefined`, require `ranges.length === 1`. If `ranges.length === 0`, `content` must be omitted or `""`. Else reject with `"malformed"`. | Enforces D7 deterministically; eliminates semantic ambiguity. |
+| **Negative Path** | Disk Failure in "disk" mode (§5) | `evidence: "disk"` on unreadable or deleted file. | Synchronous `fs.readFileSync` could throw an uncaught exception, crashing the host. | Disk reads in `"disk"` mode wrapped in try/catch. On failure, return `read: { accepted: false, reason: "bookkeeping-error" }`. | Preserves D9 (never throws). |
+| **Negative Path** | Delete Confirmation & Seam (F3) | Fabricating a change-log receipt, omitting enclosing flag gates (!no-read-guard, !no-lsp), or misordering confirmation gates. | Emitting LSP notifications when no-lsp is active (regression against v1 tool-result), or leaving zombie records in readGuard.reads when files are deleted on disk. | Wrapped by the enclosing `!getFlag("no-read-guard")` gate, followed by the 4 confirmed-delete gates in production order, shared with the native bash path (`judgeConfirmedDelete`, `clients/confirmed-delete.ts`): (1) `isExternalOrVendorFile` -> `"out-of-scope"`; (2) `isPathIgnoredByProject` -> `"ignored"`; (3) `hasKnownPath`: an untracked path that is absent returns `{ accepted: true }` without notifying LSP, and one still on disk returns `bookkeeping-error`; (4) `existsSync` confirm: a tracked file still on disk returns `{ accepted: false, reason: "bookkeeping-error" }` (v2 refinement; the bash path skips it). Action: `forgetPath(filePath)` and, unless `no-lsp`, `notifyExternalFileChange(filePath, 3)`; `no-lsp` suppresses only the notification. Bypasses `recordWritten` and emits NO change-log receipt. | Aligns with tool-result delete lifecycle and flags; refines disk-still-exists into explicit bookkeeping-error; closes zombie-record leaks without fabricated receipts. |
+| **State & Timing** | Lineage / Branch Fence (§3, §5) | Delayed write arriving after session `/tree` or shutdown. | Stale write accepted across epoch boundary, corrupting branch turn state (#3620). | `mutate` validates `runtime.readGuard.currentBranchEpoch`. If branch changed or lineage retired, call `recordDroppedRead` (`clients/session-scope.ts:281-301`, emitting `session-scope-read-dropped` at `clients/session-scope.ts:297`) and return `mutate: { accepted: false, reason: "stale-lineage" }`. If epoch is malformed, call `recordDegradationOnce` (`clients/mutation-bridge.ts:264`, emitting `mutation-bridge-invalid-branch-epoch`). | Preserves TLA+ `session-lifecycle` model and degradation accounting. |
+| **Boundaries** | Flag & Scope Gating (§4) | Collapsing `isRecordable` into a single combined check. | If `no-read-guard` is set, a single gate drops mutation turn-state and change logs (#2465). | Gating is strictly per-facet: `read` gates on `!noReadGuard && isRecordable`; `mutate` gates on `isRecordable`; read-guard write stamp gates on `!noReadGuard`. | Preserves independent accountability of turn-state vs read-guard. |
+| **Retirement** | Legacy Shims & First-Wins (§8) | Old extensions calling `read-bridge` or `mutation-bridge`. | In fresh processes, mounts v1 shims delegating to `ioBridge.record()`. If a dirty process already mounted legacy v1, first-wins retains incumbent. | Mount shims for `Symbol.for("pi-lens:read-bridge")` and `Symbol.for("pi-lens:mutation-bridge")` delegating to `ioBridge.record()`. Document first-wins behavior. | Zero-friction backward compatibility. |
+| **Observability** | Pull-Only Observability (Shape #31, F5) | Unobservable drops or citing non-existent degradation IDs. | Blind spots in monitors and analyzers; silent drops violate Shape #31. | State exact sinks with literal citations: (1) Read log provenance: v1 shim sets `source: "bridge:<consumer>"` (`clients/read-bridge.ts:207`); v2 native sets `source: "io-bridge:<consumer>"` (`[NEW]` in `clients/io-bridge.ts:NEW`, matching `ReadRecord.source` type at `clients/read-guard.ts:55`), written to `read-guard.log`; (2) `turn-state.json` via `deps.getCacheManager().addModifiedRange` (`clients/mutation-bridge.ts:382`); (3) Change-log receipt via `runtime.recordProjectMutation` (`clients/mutation-bridge.ts:393`, edit/write only); (4) Stale lineage write: `session-scope-read-dropped` (`clients/session-scope.ts:297`); (5) Foreign epoch: `mutation-bridge-invalid-branch-epoch` (`clients/mutation-bridge.ts:264`); (6) [NEW] Bridge-level drop telemetry: declare NEW `DegradationKind` union members in `clients/degradation-ledger.ts:40+`: `"io-bridge-read-dropped"` and `"io-bridge-mutate-dropped"`. Caller-synchronous outcome is also immediately returned in `RecordResult`. | Total observability across existing and new streams; fully verifiable by automated tests. |
+| **Side Channels** | Event Bus Parity (`pi.events`) | `mutation-bridge.ts:431` calls `runtime.deferMutation` without calling `publishFormatQueued`. | Tools listening on `pi.events` for `pilens:format:queued` never receive notice when mutations are recorded through the bridge, causing unexpected formatting at `agent_settled` to invalidate in-process line leases and anchors mid-session (AGENTS Shape #5; refs Rianico/pi-better-edit#32). | When `mutate` queues deferred format/autofix (`deferAutofix !== false`), `io-bridge` MUST invoke `publishFormatQueued` (`clients/format-events-publish.ts:187`) for newly-queued files. Passing `deferAutofix: false` suppresses both queueing and bus emission. | Closes the side-channel drop between native tool results and bridge mutations; provides deterministic warning before `agent_settled` rewrites. |
+
+---
+
+## 5. AI Engineering & Usability Review
+
+### 1. One-Page Learnability
+The interface is compact, strongly typed, and self-documenting. The four operations (`read`, `edit`, `write`, `delete`) map directly to the developer's mental model.
+
+### 2. Ordered Producer Guide
+Producers follow a clean 3-step lifecycle:
+```typescript
+// 1. Discover
+const bridge = getIOBridge();
+if (!bridge) return; // Bridge absent or unsupported version
+
+// 2. Formulate Entry (e.g. Hashline Edit + Preview)
+const result = bridge.record({
+  filePath: "src/app.ts", // relative or absolute string preserved
+  consumer: "my-tool",
+  mutate: {
+    kind: "edit",
+    ranges: [[12, 15]],
+  },
+  read: {
+    ranges: [[8, 25]],
+    content: previewText, // raw lines 8-25
+  },
+});
+
+// 3. Inspect Result
+if (!result.mutate?.accepted) countDrop("mutate", result.mutate?.reason);
+if (!result.read?.accepted) countDrop("read", result.read?.reason);
+```
+
+### 3. D5 Evidence Disambiguation
+- **Coverage-Only (Default)**: Passing `read: { ranges: [[10, 20]] }` without `content` or `lineHashes` credits lines 10–20 in `ReadGuard` coverage math, but does **not** read disk or bind line hashes. If lines 10–20 are modified externally, `FileTime` flags staleness and blocks the next edit.
+- **In-Memory Hash Evidence**: Passing `content` (or `lineHashes`) hashes the text in memory via `deliveredLineEvidence(text, offset)` and populates `lineHashes`. If the file is modified externally but lines 10–20 remain intact, `canIgnoreStalenessByHashes` allows the next edit without blocking.
+- **Disk Evidence (`evidence: "disk"`)**: Explicitly requests pi-lens to read the file from disk and compute line hashes.
+
+### 4. Full-File Read vs Content Binding (F7 Clarification)
+For a whole-file read `ranges: [[1, lineCount]]`, passing `content` derives in-memory line hashes for lines $1 \dots lineCount$. It does **not** synthesize a whole-file `contentBinding` (which binds `mtime` and `sha256` from disk). In `evidence: "caller"` mode, `contentBinding` is omitted, cleanly avoiding the #3652 false-block hazard.
+
+### 5. Producer Footguns & Safeguards
+- **Footgun: 0-indexed line numbers**: Bridge requires 1-indexed line numbers (`[1, 10]`). Ranges with $start < 1$ or $start > end$ are deterministically rejected as `"malformed"`.
+- **Footgun: Diff markers in `content`**: If a tool passes diff output (`+const x = 1`) instead of raw file lines, line hashes will not match on-disk bytes. Docs prominently warn: *`content` must be raw file text, never diff hunks*.
+- **Footgun: Delete followed by edit**: Deleting a file clears read coverage. Re-creating a file must be submitted as `mutate: { kind: "write" }`.
+- **Footgun: Deleting a file that still exists on disk**: If a caller calls `mutate: { kind: "delete" }` before removing the file from the filesystem, `nodeFs.existsSync(filePath)` fails the confirm gate and returns `{ accepted: false, reason: "bookkeeping-error" }`. The on-disk deletion must precede or occur synchronously with the bridge call.
+
+---
+
+## 6. Verification Plan
+
+### A. Unit Tests (`tests/clients/io-bridge.test.ts`)
+- **Facet Validation Matrix**: Exhaustive testing of invalid inputs returning `"malformed"`:
+  - Empty path string `""`.
+  - Zero-indexed ranges (`[0, 10]`), inverted ranges (`[10, 5]`), non-integer ranges.
+  - Multi-range with `content` (`ranges: [[1, 5], [10, 15]]` + `content`).
+  - `delete` combined with `read`.
+  - `lineHashes` with out-of-range keys (e.g. key `30` when range is `[1, 10]`).
+- **Path Parity & Display Preservation Matrix (F1)**:
+  - Red-before-green witness: pass a relative path (`"src/app.ts"`) through:
+    1. v1 shim `recordRead`: verify `deps.isRecordable("src/app.ts")` called; verify `ReadRecord.filePath === "src/app.ts"`; verify `ReadGuard.key("src/app.ts")` normalization.
+    2. v1 shim `recordMutation`: verify `deps.isRecordable("src/app.ts")` called; verify `addModifiedRange` called with `"src/app.ts"`.
+    3. v2 bridge `record`: verify identical outcomes, with display path preserved verbatim and no clobbering.
+- **Scope & Flag Gating Matrix (#2465)**:
+  - Out-of-project paths return `{ accepted: false, reason: "out-of-scope" }`.
+  - `no-read-guard` flag active: `read` returns `{ accepted: false, reason: "no-read-guard" }`; `mutate` returns `{ accepted: true }` but skips `ReadGuard.recordWritten`.
+- **Delete Seam & Flag Gates Matrix (F3)**:
+  - Enclosing flag gates:
+    - `no-read-guard` active: skips read-guard eviction, returns `{ accepted: false, reason: "no-read-guard" }`.
+    - `no-lsp` active: eviction `readGuard.forgetPath` runs, but `notifyExternalFileChange(filePath, 3)` is suppressed.
+  - 4 inner gates in production order (`judgeConfirmedDelete`, `clients/confirmed-delete.ts`, shared with the native bash path):
+    1. External / vendor path (`isExternalOrVendorFile`): returns `{ accepted: false, reason: "out-of-scope" }`.
+    2. Ignored path (`isPathIgnoredByProject`): returns `{ accepted: false, reason: "ignored" }`.
+    3. Untracked path (`!hasKnownPath`): if file absent, returns `{ accepted: true }`; zero LSP notifications sent. If it is still on disk, returns `{ accepted: false, reason: "bookkeeping-error" }`.
+    4. Disk confirm (`nodeFs.existsSync`): if file still exists on disk, returns `{ accepted: false, reason: "bookkeeping-error" }`.
+  - Confirmed delete on tracked path: calls `forgetPath(filePath)` and `notifyExternalFileChange(filePath, 3)`. Asserts NO `recordProjectMutation` or `addModifiedRange` invoked.
+- **Observability & Degradation Ledger Matrix (F5)**:
+  - Telemetry witness: trigger bridge drop on read and mutate; flush `latency.log` (via `getGlobalPiLensLogDir()` sink) and read back records, asserting:
+    - `kind: "io-bridge-read-dropped"`, `subject: "${consumer}:${reason}"`.
+    - `kind: "io-bridge-mutate-dropped"`, `subject: "${consumer}:${reason}"`.
+  - Stale lineage write: asserts emission of `session-scope-read-dropped` (`clients/session-scope.ts:297`).
+  - Malformed branch epoch: asserts emission of `mutation-bridge-invalid-branch-epoch` (`clients/mutation-bridge.ts:264`).
+
+### B. Seam Integration Probes & Red-Before-Green Witnesses
+
+#### 1. Witness for Write-Before-Read Atomic Ordering
+- **Production Seam**: `ReadGuard.checkEdit` -> `ioBridge.record(...)` -> `ReadGuard.checkEdit`.
+- **Probe Scenario**: An edit occurs to a file that was previously read. The producer submits a compound entry:
+  ```typescript
+  ioBridge.record({
+    filePath,
+    mutate: { kind: "edit", ranges: [[10, 15]] },
+    read: { ranges: [[5, 25]], content: postMutationContext }
+  });
+  ```
+- **Red Witness (Order Inversion)**: The order does not change an immediate `checkEdit`: the #4145 probe found the same verdict for every order, and there is no `file_time_stale` reason. What it changes is `consumedReadFiles`. `recordWritten` marks a file's existing reads consumed, and `recordRead` makes them outstanding again. Read-then-mutate therefore leaves the preview read consumed, and a consumed read is evictable on idle and under the file cap: after the idle window the read is gone and the next edit blocks as never read.
+- **Green Witness**: With `mutate` running before `read`, the preview read is the last word and stays outstanding, so idle eviction cannot drop it. `tests/clients/io-bridge.test.ts` "keeps the compound call's preview read outstanding through idle eviction" pins this; swapping the facets reds it (`expected [] to have a length of 1`).
+
+#### 2. Witness for D5 Coverage-Only Default
+- **Production Seam**: `ioBridge.record` -> `readGuard.reads.get(filePath)`.
+- **Probe Scenario**: Record a read with `read: { ranges: [[1, 10]] }` without `content` or `lineHashes`.
+- **Red Witness (Unwanted Disk Hashing)**: If the bridge silently read disk, `storedRecord.lineHashes` would be populated.
+- **Green Witness**: `storedRecord.lineHashes` is strictly `undefined`. Zero disk reads occur.
+
+#### 3. Witness for Delete Lifecycle Eviction (F3)
+- **Production Seam**: `ioBridge.record` -> `readGuard.hasKnownPath` + `notifyExternalFileChange`.
+- **Probe Scenario**: A file with existing read records is deleted via `mutate: { kind: "delete" }` after on-disk removal.
+- **Witness**: `readGuard.hasKnownPath(filePath) === false`, `readGuard.reads.has(filePath) === false`, `writtenThisSession.has(filePath) === false`, and mock LSP receives FileChangeType 3. Asserts NO change log receipt was appended.
+
+---
+
+## 7. Issues & Status
+
+- **Open Defects / Ambiguities**: **None**.
+  - **F1 (Path Resolution & Display Parity)**: Fully resolved. `filePath` non-empty string preserved verbatim without re-resolving or clobbering at bridge layer; unit test matrix verifies v1 parity.
+  - **F3 (Delete Seam & Flag Gates)**: Fully resolved. The enclosing `!getFlag("no-read-guard")` gate, then the 4 confirmed-delete gates shared with the native bash path (`clients/confirmed-delete.ts`), followed by `forgetPath` and, unless `no-lsp`, `notifyExternalFileChange`. Dropped fabricated change-log receipt.
+  - **F5 (Observability & Exact Citations)**: Fully resolved. Read log provenance uses `bridge:<consumer>` for v1 shim (`clients/read-bridge.ts:207`) and `io-bridge:<consumer>` as `[NEW]` for v2 native (`ReadRecord.source` type at `clients/read-guard.ts:55`). Re-uses existing `session-scope-read-dropped` (`clients/session-scope.ts:297`) and `mutation-bridge-invalid-branch-epoch` (`clients/mutation-bridge.ts:264`); explicitly declares `[NEW]` `DegradationKind` union members `"io-bridge-read-dropped"` and `"io-bridge-mutate-dropped"` in `clients/degradation-ledger.ts:40+` with test reading `latency.log`.
+- **Maintainer Decisions**: the maintainer accepted this design on #4145 (2026-10-08): the D5/D6 evidence model, the public field set, relative paths out of scope, and a tracked `docs/rfcs/`.