feat(log): log authority is the fleet default — adopt-at-open, oracle-gated; plus the power-cut throw-site cures and the loud torn-record contract

THE DEFAULT FLIP (ruled on proven evidence — at-ack survived 301/301
acked-writes-through-power-cut in block-layer fault injection; deferred
tree authority demonstrably loses flush-covered acks): a brain with NO
stored authority artifact now ADOPTS LOG AUTHORITY AT OPEN. The oracle
gates the flip exactly as the guarded adoption path always did — curable
divergences baseline-backfilled, the flip lands ONLY on a green verdict —
and a brain that cannot verify STAYS tree-authoritative loudly, with the
refusal recorded on the switch artifact so subsequent opens are cheap.
config logAuthority: 'defer' is the explicit documented opt-out (no
automatic adoption; declared flush-window loss; adoptLogAuthority() flips
later). A stored artifact always wins. RELEASES.md carries the posture.

Two standing .fails debt pins FLIP TO HOLDING under the default: the
at-ack crash-survival gap and the ack-at-log durability target — both now
permanent asserted truths, not aspirations.

POWER-CUT THROW SITES (fault-injection findings, brainy-alone config):
- A manifest-listed-but-unloadable column segment QUARANTINES at
  discovery (loud once, counted always, quarantinedSegments() exposed for
  the heal) and the field serves its remaining segments DEGRADED — never
  a raw throw killing every query on the field. Real storage faults still
  propagate untouched.
- Torn generation artifacts (NaN/garbage in manifest or counter) DISCARD
  with narration at the store's open and recovery re-derives — plus a
  defensive finite-integer guard at the init consumer. Never a RangeError
  killing an open.

THE LOUD TORN-RECORD CONTRACT: an existing-but-unparseable stored record
now surfaces as a typed, counted TornRecordError on every entity-read
surface (including fifteen previously-blind per-item batch catches);
ENOENT stays clean-absent; artifact readers with designed absent-recovery
keep null-tolerance behind the loud floor. Disk corruption can no longer
read as silent data invisibility.

Suite migration: the default's pins inverted deliberately, generation
baselines made relative, quarantine-contract pins rewritten to the ruled
behavior.

Gates: tsc 0 · unit 2065/2065 (159 files) · integration 826 (93 files) ·
conformance 31/31 · kill-matrix 15/15 · torn-open guards 2/2.

src/storage/tornRecordError.ts

@@ -0,0 +1,132 @@
+/**
+ * @module storage/tornRecordError
+ * @description Typed surface for TORN records — files that EXIST in storage but
+ * cannot be decoded (invalid JSON, truncated/garbled gzip). A torn record is
+ * disk corruption, not absence: reading it as `null` ("not found") makes the
+ * consumer unable to distinguish "never existed" from "exists but unreadable",
+ * so nothing ever heals it. Mandate: loud errors, never quiet losses.
+ *
+ * Contract implemented across the storage layer:
+ * - Genuine absence (ENOENT) still reads as clean `null` — no error, no noise.
+ * - A torn record ALWAYS registers here (error log + per-process gauge), then:
+ *   - entity read paths (get/getBatch/pagination/enumeration hydration) throw
+ *     {@link TornRecordError} to the caller — a row is never silently dropped;
+ *   - system-artifact read paths whose machinery is designed for
+ *     absent-artifact degradation (manifests with recovery paths, markers
+ *     whose verdict is "rescan", rebuildable statistics) map torn → their
+ *     existing degrade AFTER the encounter is logged and counted.
+ */
+
+import { prodLog } from '../utils/logger.js'
+
+/**
+ * @description Thrown when a stored object EXISTS but cannot be decoded —
+ * corrupt/torn bytes on disk (invalid JSON, undecodable gzip). Deliberately
+ * distinct from absence: `readObjectFromPath` returns `null` only for ENOENT.
+ * Catchable by type (`instanceof`), by `name === 'TornRecordError'`, or by
+ * `code === 'TORN_RECORD'` (cross-realm safe; never matches `isAbsentError`).
+ */
+export class TornRecordError extends Error {
+  /** Stable machine-checkable discriminator (errno-style). */
+  public readonly code = 'TORN_RECORD'
+  /** Storage-root-relative path of the torn object. */
+  public readonly path: string
+  /** The underlying decode failure (SyntaxError, zlib error, …). */
+  public override readonly cause: unknown
+
+  /**
+   * @param path - Storage-root-relative path of the torn object.
+   * @param cause - The underlying decode failure.
+   */
+  constructor(path: string, cause: unknown) {
+    const causeMessage =
+      cause instanceof Error ? cause.message : String(cause)
+    super(
+      `Torn record at '${path}': file exists but cannot be decoded (${causeMessage}). ` +
+        `This is storage corruption, not absence — the record was not silently skipped.`
+    )
+    this.name = 'TornRecordError'
+    this.path = path
+    this.cause = cause
+  }
+}
+
+/**
+ * @description True IFF `e` is a torn-record error — matches by `instanceof`
+ * first, then by `name`/`code` so errors crossing module-duplication or realm
+ * boundaries are still recognized.
+ * @param e - The caught value.
+ * @returns Whether `e` denotes an existing-but-undecodable stored object.
+ */
+export function isTornRecordError(e: unknown): e is TornRecordError {
+  if (e instanceof TornRecordError) return true
+  if (e === null || typeof e !== 'object') return false
+  const { name, code } = e as { name?: unknown; code?: unknown }
+  return name === 'TornRecordError' || code === 'TORN_RECORD'
+}
+
+/**
+ * @description True IFF `e` is a payload-decode failure — the file's BYTES were
+ * read fine but could not be turned back into an object: `SyntaxError` from
+ * `JSON.parse`, or a zlib error (`Z_DATA_ERROR`, `Z_BUF_ERROR`, …) from gunzip.
+ * Distinguishes "torn record" from real I/O faults (EIO/EACCES/…), which must
+ * propagate as themselves.
+ * @param e - The caught value.
+ * @returns Whether the error means "bytes present, content undecodable".
+ */
+export function isUnparseablePayloadError(e: unknown): boolean {
+  if (e === null || typeof e !== 'object') return false
+  if (e instanceof SyntaxError) return true
+  const { name, code } = e as { name?: unknown; code?: unknown }
+  if (name === 'SyntaxError') return true
+  return typeof code === 'string' && code.startsWith('Z_')
+}
+
+/** Per-process torn-record gauge state (module-scoped; see the accessors). */
+let tornRecordCount = 0
+let lastTornRecordPath: string | null = null
+
+/**
+ * @description Register a torn-record encounter: logs a production ERROR
+ * naming the path, increments the per-process gauge, and returns the typed
+ * error for the caller to throw (or to map into a documented loud degrade).
+ * EVERY torn encounter goes through here, whatever the caller decides —
+ * the floor is: never silent.
+ * @param path - Storage-root-relative path of the torn object.
+ * @param cause - The underlying decode failure.
+ * @returns The constructed {@link TornRecordError}.
+ */
+export function registerTornRecordEncounter(
+  path: string,
+  cause: unknown
+): TornRecordError {
+  tornRecordCount++
+  lastTornRecordPath = path
+  const error = new TornRecordError(path, cause)
+  prodLog.error(
+    `[Storage] TORN RECORD #${tornRecordCount}: '${path}' exists but cannot be decoded — ` +
+      `corrupt or partially written bytes. Cause: ${
+        cause instanceof Error ? `${cause.name}: ${cause.message}` : String(cause)
+      }`
+  )
+  return error
+}
+
+/**
+ * @description Read the per-process torn-record gauge: how many torn records
+ * this process has encountered and the most recent path. Observability seam —
+ * lets operators and tests confirm that corruption was seen, not swallowed.
+ * @returns The current gauge snapshot.
+ */
+export function getTornRecordGauge(): { count: number; lastPath: string | null } {
+  return { count: tornRecordCount, lastPath: lastTornRecordPath }
+}
+
+/**
+ * @description Reset the per-process torn-record gauge to zero. Test seam only
+ * (the gauge is process-lifetime state); production code never resets it.
+ */
+export function resetTornRecordGauge(): void {
+  tornRecordCount = 0
+  lastTornRecordPath = null
+}