mixdog 1.2.5 → 1.3.0

package/src/runtime/agent/orchestrator/session/store-agent-worker-rows.mjs

@@ -16,10 +16,17 @@
  * field name and row key is a consumed contract and is used verbatim.
  */
 import { readFileSync } from 'node:fs';
+import { readFile, stat } from 'node:fs/promises';
 import { join } from 'node:path';
-import { probePath, PROBE_PRESENT } from './store/fs-probe.mjs';
+import {
+  isSettledSessionStamp,
+  sameSessionStamp,
+  sessionStampOf,
+  statSessionStamp,
+} from './store/canonical-reader.mjs';
 import { readJsonProjection } from '../../../shared/pending-json-projection.mjs';
 import { listStoredAgentWorkers as assembleStoredAgentWorkers } from './store-agent-worker-pool.mjs';
+import { readTopLevelFields } from './store-agent-worker-header.mjs';
 import {
   TAG_TOMBSTONE_TTL_MS,
   agentPaneVisible,
@@ -166,16 +173,83 @@ function cancelStage(cancel, declaredStage) {
   return /^cancel/i.test(declaredStage) || CANCELLED_AGENT_STATUS.test(declaredStage) ? declaredStage : cancel.status;
 }
 
-function storedAgentWorkerIndex() {
-  const path = storedAgentWorkerIndexPath();
+// The worker indexes were re-parsed in full on every pool listing and ancestry
+// lookup, changed or not. Each keeps its last parse beside the bytes it came
+// from: the file is still read every time (a few hundred KB), but an
+// unchanged one — byte for byte, so no timestamp collision can serve a stale
+// document — reuses that parse.
+// Before the read, the full file stamp is checked under the same canonical
+// policy the session headers use: a file that still has the exact settled
+// { dev, ino, size, mtimeNs, ctimeNs } its bytes were proven to come from is
+// not read again (each pool listing re-read the whole index synchronously).
+const workerIndexCache = new Map(); // path -> { bytes, doc, stamp|null }
+// The index documents an asynchronous listing read before its (synchronous)
+// assembly; live only during that assembly.
+let passIndexes = null; // path -> doc | null
+
+function readWorkerIndexFile(path) {
+  if (passIndexes?.has(path)) return passIndexes.get(path);
   // This process's own queued (not yet persisted) writes win over the file.
   const projected = readJsonProjection(path);
   if (projected) return projected;
+  const before = observeStamp(path);
+  const cached = workerIndexCache.get(path);
+  if (before && cached?.stamp && sameSessionStamp(cached.stamp, before)) return cached.doc;
+  let bytes;
   try {
-    return JSON.parse(readFileSync(path, 'utf8'));
+    bytes = readFileSync(path);
   } catch {
+    workerIndexCache.delete(path);
     return null;
   }
+  const stamp = before && isSettledSessionStamp(before) && sameSessionStamp(before, observeStamp(path)) ? before : null;
+  if (cached?.bytes.equals(bytes)) {
+    cached.stamp = stamp;
+    return cached.doc;
+  }
+  let doc = null;
+  try {
+    doc = JSON.parse(bytes.toString('utf8'));
+  } catch {
+    /* malformed: no rows */
+  }
+  workerIndexCache.set(path, { bytes, doc, stamp });
+  return doc;
+}
+
+/** readWorkerIndexFile with every stat and read awaited, under the same
+ *  stamp and byte-equality cache. */
+async function readWorkerIndexFileAsync(path) {
+  const projected = readJsonProjection(path);
+  if (projected) return projected;
+  const before = await observeStampAsync(path);
+  const cached = workerIndexCache.get(path);
+  if (before && cached?.stamp && sameSessionStamp(cached.stamp, before)) return cached.doc;
+  let bytes;
+  try {
+    bytes = await readFile(path);
+  } catch {
+    workerIndexCache.delete(path);
+    return null;
+  }
+  const settled = before && isSettledSessionStamp(before);
+  const stamp = settled && sameSessionStamp(before, await observeStampAsync(path)) ? before : null;
+  if (cached?.bytes.equals(bytes)) {
+    cached.stamp = stamp;
+    return cached.doc;
+  }
+  let doc = null;
+  try {
+    doc = JSON.parse(bytes.toString('utf8'));
+  } catch {
+    /* malformed: no rows */
+  }
+  workerIndexCache.set(path, { bytes, doc, stamp });
+  return doc;
+}
+
+function storedAgentWorkerIndex() {
+  return readWorkerIndexFile(storedAgentWorkerIndexPath());
 }
 
 function storedAgentWorkerIndexRows() {
@@ -211,7 +285,8 @@ export function listStoredAgentWorkerLinks() {
 
 // The agent pool only reads top-level session fields, yet each refresh used to
 // JSON.parse every active worker's whole transcript (megabytes per worker,
-// every catalog publish). Cache the header per file fingerprint instead.
+// every catalog publish). Cache the header per full file stamp instead (see
+// probeWorkerSessionHeader).
 // The cache holds exactly the headers the latest pool assembly read: a fixed
 // LRU cap below the index size (263 headers against 256 slots) evicted every
 // entry just before its reuse, so each refresh re-parsed every worker
@@ -250,30 +325,120 @@ const WORKER_HEADER_FIELDS = [
   ...SESSION_CANCEL_FIELDS,
 ];
 
+// One assembly reads a session's header up to three times (reap check, row
+// projection, orphan prune); each read used to stat the file again. Within an
+// assembly the first answer stands, absent or unreadable included.
+let passHeaders = null; // path -> header | null, live only during an assembly
+
+function workerSessionHeaderPath(sessionId) {
+  return join(dataDir(), 'sessions', `${sessionId}.json`);
+}
+
 function readWorkerSessionHeader(sessionId) {
-  const path = join(dataDir(), 'sessions', `${sessionId}.json`);
-  const probe = probePath(path);
-  if (probe.state !== PROBE_PRESENT) return null;
+  const path = workerSessionHeaderPath(sessionId);
+  if (passHeaders?.has(path)) return passHeaders.get(path);
+  const header = probeWorkerSessionHeader(path);
+  passHeaders?.set(path, header);
+  return header;
+}
+
+let workerHeaderReads = 0;
+
+function observeStamp(path) {
+  try {
+    return statSessionStamp(path);
+  } catch {
+    return null;
+  }
+}
+
+// A header is reused only under the canonical full-stamp policy: the file
+// still has the exact { dev, ino, size, mtimeNs, ctimeNs } its bytes were
+// proven to come from (stat → read → stat), and that stamp was past the racy
+// window when read. Size + mtime alone let an equal-length rewrite that kept
+// its mtime serve stale ownership, status and cancel fields.
+function probeWorkerSessionHeader(path) {
+  // Absent and unreadable alike: no header.
+  const before = observeStamp(path);
+  if (!before) return null;
   const cached = workerSessionHeaderCache.get(path);
-  if (cached && cached.mtimeMs === probe.mtimeMs && cached.size === probe.size) {
+  if (cached && sameSessionStamp(cached.stamp, before)) {
     cached.pass = headerPass;
     return cached.header;
   }
-  let session = null;
+  workerSessionHeaderCache.delete(path);
+  // A rewrite re-reads only this record, and only its top-level fields are
+  // decoded: the transcript bytes are validated, never materialized.
+  let header = null;
+  try {
+    header = readTopLevelFields(readFileSync(path), WORKER_HEADER_FIELDS);
+  } catch {
+    return null;
+  }
+  if (!header) return null;
+  workerHeaderReads += 1;
+  if (isSettledSessionStamp(before) && sameSessionStamp(before, observeStamp(path))) {
+    workerSessionHeaderCache.set(path, { stamp: before, header, pass: headerPass });
+  }
+  return header;
+}
+
+async function observeStampAsync(path) {
+  try {
+    return sessionStampOf(await stat(path, { bigint: true }));
+  } catch {
+    return null;
+  }
+}
+
+/** probeWorkerSessionHeader with every stat and read awaited, under the
+ *  same full-stamp cache policy. */
+async function probeWorkerSessionHeaderAsync(path) {
+  const before = await observeStampAsync(path);
+  if (!before) return null;
+  const cached = workerSessionHeaderCache.get(path);
+  if (cached && sameSessionStamp(cached.stamp, before)) return cached.header;
+  workerSessionHeaderCache.delete(path);
+  let header = null;
   try {
-    session = JSON.parse(readFileSync(path, 'utf8'));
+    header = readTopLevelFields(await readFile(path), WORKER_HEADER_FIELDS);
   } catch {
     return null;
   }
-  if (!session || typeof session !== 'object') return null;
-  const header = {};
-  for (const field of WORKER_HEADER_FIELDS) {
-    if (Object.hasOwn(session, field)) header[field] = session[field];
+  if (!header) return null;
+  workerHeaderReads += 1;
+  if (isSettledSessionStamp(before) && sameSessionStamp(before, await observeStampAsync(path))) {
+    workerSessionHeaderCache.set(path, { stamp: before, header, pass: headerPass });
   }
-  workerSessionHeaderCache.set(path, { mtimeMs: probe.mtimeMs, size: probe.size, header, pass: headerPass });
   return header;
 }
 
+// Header reads in flight at once: each is a stat (and a read only when the
+// file changed) on the shared libuv pool, which other file I/O also needs.
+const HEADER_READ_CONCURRENCY = 4;
+
+async function prefetchWorkerHeaders(sessionIds, headers) {
+  const paths = [...new Set([...sessionIds].map(workerSessionHeaderPath))].filter((path) => !headers.has(path));
+  let next = 0;
+  const drain = async () => {
+    while (next < paths.length) {
+      const path = paths[next++];
+      headers.set(path, await probeWorkerSessionHeaderAsync(path));
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(HEADER_READ_CONCURRENCY, paths.length) }, drain));
+}
+
+/** Test/diagnostic seam: cached headers and the records this process read. */
+export function storedAgentWorkerHeaderStats() {
+  return {
+    entries: workerSessionHeaderCache.size,
+    reads: workerHeaderReads,
+    stickyIdle: stickyIdleSince.size,
+    indexes: workerIndexCache.size,
+  };
+}
+
 /** Owner record of a child row that is a Lead CONVERSATION. Only such an owner
  *  lets a missing pool row mean "the Lead's lease expired"; an Agent-owned or
  *  unreadable owner keeps its child rows visible exactly as before. */
@@ -377,16 +542,8 @@ function projectChildWorkerRow(row, context) {
 }
 
 function storedLeadWorkerRows() {
-  const path = storedLeadWorkerIndexPath();
-  let parsed = readJsonProjection(path);
-  if (!parsed) {
-    try {
-      parsed = JSON.parse(readFileSync(path, 'utf8'));
-    } catch {
-      /* no resident Lead pool */
-    }
-  }
-  return workerRows(parsed);
+  // Absent or unreadable: no resident Lead pool.
+  return workerRows(readWorkerIndexFile(storedLeadWorkerIndexPath()));
 }
 
 /** A Lead-index row whose durable session turned out to be an agent's.
@@ -464,6 +621,72 @@ function pruneOrphanChildRows(bySessionId, { liveLeadSessionIds }) {
  * never projected into either pool. `runningSessionIds` is the daemon's set of
  * sessions whose turn is in flight; omitted, no row is shown as running. */
 export function listStoredAgentWorkers({ runningSessionIds = null } = {}) {
+  headerPass += 1;
+  passHeaders = new Map();
+  try {
+    return assembleListedWorkers(runningSessionIds);
+  } finally {
+    passHeaders = null;
+    forgetUnreadHeaders();
+  }
+}
+
+// Keep what the latest assembly read, whatever the index size; forget the rest.
+function forgetUnreadHeaders() {
+  for (const [path, entry] of workerSessionHeaderCache) {
+    if (entry.pass !== headerPass) workerSessionHeaderCache.delete(path);
+  }
+}
+
+/** listStoredAgentWorkers without blocking the event loop on the store: both
+ *  indexes and every header the assembly can consult (each row's session,
+ *  each Lead row's, and each child's owner) are read first with awaited
+ *  stats and reads; the assembly then runs over what was read, with no file
+ *  access left in it (any header it still asks for falls back to a read).
+ *  `runningSessionIds` may be a function, asked once the reads are done. */
+export async function listStoredAgentWorkersAsync({ runningSessionIds = null } = {}) {
+  const agentIndexPath = storedAgentWorkerIndexPath();
+  const leadIndexPath = storedLeadWorkerIndexPath();
+  const [agentIndex, leadIndex] = await Promise.all([
+    readWorkerIndexFileAsync(agentIndexPath),
+    readWorkerIndexFileAsync(leadIndexPath),
+  ]);
+  const headers = new Map();
+  const childRows = workerRows(agentIndex);
+  const sessionIds = new Set(childRows.map((row) => cleanValue(row?.sessionId)));
+  for (const row of workerRows(leadIndex)) {
+    const sessionId = cleanValue(row?.sessionId);
+    if (sessionId && isStoredSessionId(sessionId)) sessionIds.add(sessionId);
+  }
+  await prefetchWorkerHeaders(sessionIds, headers);
+  const owners = new Set();
+  for (const row of childRows) {
+    const header = headers.get(workerSessionHeaderPath(cleanValue(row?.sessionId)));
+    const owner = row && typeof row === 'object' ? workerOwnerSessionId(row, header) : null;
+    if (owner) owners.add(owner);
+  }
+  await prefetchWorkerHeaders(owners, headers);
+  const running = typeof runningSessionIds === 'function' ? runningSessionIds() : runningSessionIds;
+  headerPass += 1;
+  for (const path of headers.keys()) {
+    const entry = workerSessionHeaderCache.get(path);
+    if (entry) entry.pass = headerPass;
+  }
+  passHeaders = headers;
+  passIndexes = new Map([
+    [agentIndexPath, agentIndex],
+    [leadIndexPath, leadIndex],
+  ]);
+  try {
+    return assembleListedWorkers(running);
+  } finally {
+    passHeaders = null;
+    passIndexes = null;
+    forgetUnreadHeaders();
+  }
+}
+
+function assembleListedWorkers(runningSessionIds) {
   const now = Date.now();
   const index = storedAgentWorkerIndex();
   const rows = workerRows(index);
@@ -487,21 +710,13 @@ export function listStoredAgentWorkers({ runningSessionIds = null } = {}) {
     };
     return tombstoneBlocksWork(work, findTagTombstone(work, tombstones));
   };
-  headerPass += 1;
-  try {
-    return assembleStoredAgentWorkers({
-      now,
-      runningSessionIds,
-      storedAgentWorkerIndexRows: () => rows.filter((row) => !isReaped(cleanValue(row.sessionId))),
-      projectChildWorkerRow,
-      storedLeadWorkerRows,
-      projectLeadWorkerRow,
-      pruneOrphanChildRows,
-    });
-  } finally {
-    // Keep what this assembly read, whatever the index size; forget the rest.
-    for (const [path, entry] of workerSessionHeaderCache) {
-      if (entry.pass !== headerPass) workerSessionHeaderCache.delete(path);
-    }
-  }
+  return assembleStoredAgentWorkers({
+    now,
+    runningSessionIds,
+    storedAgentWorkerIndexRows: () => rows.filter((row) => !isReaped(cleanValue(row.sessionId))),
+    projectChildWorkerRow,
+    storedLeadWorkerRows,
+    projectLeadWorkerRow,
+    pruneOrphanChildRows,
+  });
 }

package/src/runtime/agent/orchestrator/session/store-record-strict-scan.mjs

@@ -0,0 +1,325 @@
+/**
+ * Strict session-record read that decodes only what its caller needs.
+ *
+ * `readTopLevelLifecycleRecord` (lifecycle-scan.mjs) is the authority: a full
+ * `JSON.parse`, then a top-level duplicate-key walk. On a transcript that
+ * materializes every message object — about 2.5 ms per MB, most of it for
+ * tool output nobody reads. This reader reaches the SAME verdict and the same
+ * values while decoding only:
+ *   - top-level values whose key is not in `skip`;
+ *   - of `messages` (when it is an array): each element whose `role` is in
+ *     `fullMessageRoles` in full; every other object element as `{ role }`
+ *     (or `{}` without one); non-object elements in full.
+ * Everything else is validated, never decoded.
+ *
+ * The fast path accepts a document only when it has PROVEN it valid:
+ *   - no raw byte below 0x20 anywhere (one native regex test; JSON forbids
+ *     them inside strings, so a document with whitespace other than spaces,
+ *     i.e. a pretty-printed one, simply takes the authoritative path);
+ *   - no invalid escape anywhere (one native regex test; a backslash outside
+ *     a string fails the grammar walk below);
+ *   - the complete grammar, walked over every byte outside strings: values,
+ *     separators, exact number and literal spellings, nesting, and nothing
+ *     but whitespace after the root object;
+ *   - a root object without any repeated top-level key.
+ * Anything it cannot prove — malformed, ambiguous, or merely unusual — is
+ * handed to `readTopLevelLifecycleRecord` itself, so every rejection is the
+ * authority's own. Decoded values are `JSON.parse` of their exact UTF-8
+ * slices, which equal the full parse's sub-values (slices start and end at
+ * ASCII delimiters, so UTF-8 decoding agrees too).
+ */
+import { lifecycleRecordOf, readTopLevelLifecycleRecord } from './lifecycle-scan.mjs';
+
+const QUOTE = 0x22;
+const BACKSLASH = 0x5c;
+const SPACE = 0x20;
+const COMMA = 0x2c;
+const COLON = 0x3a;
+const OPEN_OBJECT = 0x7b;
+const CLOSE_OBJECT = 0x7d;
+const OPEN_ARRAY = 0x5b;
+const CLOSE_ARRAY = 0x5d;
+const MINUS = 0x2d;
+const PLUS = 0x2b;
+const DOT = 0x2e;
+const ZERO = 0x30;
+const NINE = 0x39;
+const EMPTY = new Set();
+
+// String-content faults, one native pass each (an alternation of the two is
+// slower than both). Any raw control byte: inside a string JSON.parse rejects
+// it; outside one only \t \n \r are whitespace, and those documents take the
+// full path.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: control bytes are exactly what this detects.
+const CONTROL_BYTE = /[\x00-\x1f]/;
+// An escape that is not one of \" \\ \/ \b \f \n \r \t \uXXXX. The run before
+// it starts after a non-backslash, so escapes pair from the run's start.
+const INVALID_ESCAPE = /(?<!\\)(?:\\\\)*\\(?:[^"\\/bfnrtu]|u(?![0-9a-fA-F]{4}))/;
+
+const isDigit = (code) => code >= ZERO && code <= NINE;
+
+// Only spaces can remain: CONTROL_BYTE already sent every \t \n \r away.
+function skipSpaces(text, at) {
+  let i = at;
+  while (text.charCodeAt(i) === SPACE) i++;
+  return i;
+}
+
+/** Index after the string opening at `at`, or -1. */
+function stringEnd(text, at) {
+  let quote = at;
+  for (;;) {
+    quote = text.indexOf('"', quote + 1);
+    if (quote === -1) return -1;
+    let run = 0;
+    for (let k = quote - 1; text.charCodeAt(k) === BACKSLASH; k--) run++;
+    if ((run & 1) === 0) return quote + 1;
+  }
+}
+
+/** Index after the JSON number at `at`, or -1. */
+function numberEnd(text, at) {
+  let i = at;
+  if (text.charCodeAt(i) === MINUS) i++;
+  if (text.charCodeAt(i) === ZERO) i++;
+  else if (isDigit(text.charCodeAt(i))) {
+    while (isDigit(text.charCodeAt(i))) i++;
+  } else return -1;
+  if (text.charCodeAt(i) === DOT) {
+    i++;
+    if (!isDigit(text.charCodeAt(i))) return -1;
+    while (isDigit(text.charCodeAt(i))) i++;
+  }
+  const exponent = text.charCodeAt(i);
+  if (exponent === 0x65 || exponent === 0x45) {
+    i++;
+    if (text.charCodeAt(i) === PLUS || text.charCodeAt(i) === MINUS) i++;
+    if (!isDigit(text.charCodeAt(i))) return -1;
+    while (isDigit(text.charCodeAt(i))) i++;
+  }
+  return i;
+}
+
+/** Index after `"key" :` starting at `at`, or -1. */
+function memberValueStart(text, at) {
+  if (text.charCodeAt(at) !== QUOTE) return -1;
+  const end = stringEnd(text, at);
+  if (end === -1) return -1;
+  const colon = skipSpaces(text, end);
+  return text.charCodeAt(colon) === COLON ? colon + 1 : -1;
+}
+
+/** Index after one valid JSON value starting at or after `at`, or -1.
+ *  Iterative, so nesting depth costs no stack. */
+function valueEnd(text, at) {
+  const closers = [];
+  let i = at;
+  for (;;) {
+    i = skipSpaces(text, i);
+    const code = text.charCodeAt(i);
+    if (code === QUOTE) i = stringEnd(text, i);
+    else if (code === OPEN_OBJECT || code === OPEN_ARRAY) {
+      const closer = code === OPEN_OBJECT ? CLOSE_OBJECT : CLOSE_ARRAY;
+      i = skipSpaces(text, i + 1);
+      if (text.charCodeAt(i) === closer) i++;
+      else {
+        closers.push(closer);
+        if (closer === CLOSE_OBJECT) {
+          i = memberValueStart(text, i);
+          if (i === -1) return -1;
+        }
+        continue;
+      }
+    } else if (code === 0x74) i = text.startsWith('true', i) ? i + 4 : -1;
+    else if (code === 0x66) i = text.startsWith('false', i) ? i + 5 : -1;
+    else if (code === 0x6e) i = text.startsWith('null', i) ? i + 4 : -1;
+    else i = numberEnd(text, i);
+    if (i === -1) return -1;
+    // After a value: close containers or move to the next member/element.
+    for (;;) {
+      if (closers.length === 0) return i;
+      i = skipSpaces(text, i);
+      const next = text.charCodeAt(i);
+      const closer = closers[closers.length - 1];
+      if (next === closer) {
+        closers.pop();
+        i++;
+        continue;
+      }
+      if (next !== COMMA) return -1;
+      i = skipSpaces(text, i + 1);
+      if (closer === CLOSE_OBJECT) {
+        i = memberValueStart(text, i);
+        if (i === -1) return -1;
+      }
+      break;
+    }
+  }
+}
+
+const decodeSlice = (bytes, start, end) => JSON.parse(bytes.toString('utf8', start, end));
+
+/** The key of the string token [start, end): its own bytes unless escaped. */
+function decodeKey(bytes, text, start, end) {
+  for (let k = start + 1; k < end - 1; k++) {
+    if (text.charCodeAt(k) === BACKSLASH) return decodeSlice(bytes, start, end);
+  }
+  return bytes.toString('utf8', start + 1, end - 1);
+}
+
+function defineMember(target, key, value) {
+  // JSON.parse creates own data properties, `__proto__` included.
+  Object.defineProperty(target, key, { value, writable: true, enumerable: true, configurable: true });
+}
+
+// "role" spelled with escapes is at most 6 escapes of 6 chars plus quotes.
+const MAX_ESCAPED_ROLE_KEY = 26;
+
+/** One `messages` element [start, ...): `{ end, item }`, or null. */
+function messageElement(bytes, text, start, fullRoles) {
+  if (text.charCodeAt(start) !== OPEN_OBJECT) {
+    const end = valueEnd(text, start);
+    return end === -1 ? null : { end, item: decodeSlice(bytes, start, end) };
+  }
+  let i = skipSpaces(text, start + 1);
+  let role;
+  let hasRole = false;
+  if (text.charCodeAt(i) === CLOSE_OBJECT) return { end: i + 1, item: {} };
+  for (;;) {
+    if (text.charCodeAt(i) !== QUOTE) return null;
+    const keyEnd = stringEnd(text, i);
+    if (keyEnd === -1) return null;
+    const isRole =
+      (keyEnd - i === 6 && text.startsWith('"role"', i)) ||
+      (keyEnd - i <= MAX_ESCAPED_ROLE_KEY && keyEnd - i > 6 && decodeKey(bytes, text, i, keyEnd) === 'role');
+    const colon = skipSpaces(text, keyEnd);
+    if (text.charCodeAt(colon) !== COLON) return null;
+    const valueStart = skipSpaces(text, colon + 1);
+    const end = valueEnd(text, valueStart);
+    if (end === -1) return null;
+    if (isRole) {
+      // Duplicate members resolve last-wins, as in the full parse.
+      role = decodeSlice(bytes, valueStart, end);
+      hasRole = true;
+    }
+    i = skipSpaces(text, end);
+    if (text.charCodeAt(i) === COMMA) {
+      i = skipSpaces(text, i + 1);
+      continue;
+    }
+    if (text.charCodeAt(i) !== CLOSE_OBJECT) return null;
+    const elementEnd = i + 1;
+    let item = {};
+    if (hasRole && fullRoles.has(role)) item = decodeSlice(bytes, start, elementEnd);
+    else if (hasRole) defineMember(item, 'role', role);
+    return { end: elementEnd, item };
+  }
+}
+
+/** Decode `messages` from the end in full, newest first, until `tailUntil`
+ *  accepts one; `spans` holds each element's [start, end). */
+function decodeTail(bytes, messages, spans, fullRoles, tailUntil) {
+  for (let k = messages.length - 1; k >= 0; k--) {
+    let item = messages[k];
+    if (item && typeof item === 'object' && !Array.isArray(item) && !fullRoles.has(item.role)) {
+      item = decodeSlice(bytes, spans[2 * k], spans[2 * k + 1]);
+      messages[k] = item;
+    }
+    if (tailUntil(item)) return;
+  }
+}
+
+/** The `messages` array [start, ...): `{ end, messages }`, or null. */
+function messagesValue(bytes, text, start, fullRoles, tailUntil) {
+  const messages = [];
+  const spans = tailUntil ? [] : null;
+  let i = skipSpaces(text, start + 1);
+  if (text.charCodeAt(i) === CLOSE_ARRAY) return { end: i + 1, messages };
+  for (;;) {
+    const element = messageElement(bytes, text, i, fullRoles);
+    if (!element) return null;
+    messages.push(element.item);
+    spans?.push(i, element.end);
+    i = skipSpaces(text, element.end);
+    if (text.charCodeAt(i) === COMMA) {
+      i = skipSpaces(text, i + 1);
+      continue;
+    }
+    if (text.charCodeAt(i) !== CLOSE_ARRAY) return null;
+    if (tailUntil) decodeTail(bytes, messages, spans, fullRoles, tailUntil);
+    return { end: i + 1, messages };
+  }
+}
+
+/**
+ * The proven-valid, duplicate-free root object of `bytes`, or null when
+ * validity could not be proven (or the document is not such an object). Of
+ * it only the members `decode(key)` accepts are decoded — `messages`, when an
+ * array, as described in the module comment with `fullMessageRoles`; every
+ * other member is validated and left out. With `fullTailUntil`, `messages`
+ * is also decoded in full from its end, newest first, through the first
+ * element the predicate accepts.
+ */
+export function provenTopLevelObject(bytes, decode, fullMessageRoles = EMPTY, fullTailUntil = null) {
+  try {
+    return provenDocument(bytes, decode, fullMessageRoles, fullTailUntil);
+  } catch {
+    return null;
+  }
+}
+
+function provenDocument(bytes, decode, fullRoles, tailUntil) {
+  const text = bytes.toString('latin1');
+  if (CONTROL_BYTE.test(text) || INVALID_ESCAPE.test(text)) return null;
+  let i = skipSpaces(text, 0);
+  if (text.charCodeAt(i) !== OPEN_OBJECT) return null;
+  const doc = {};
+  const seen = new Set();
+  i = skipSpaces(text, i + 1);
+  if (text.charCodeAt(i) === CLOSE_OBJECT) i++;
+  else {
+    for (;;) {
+      if (text.charCodeAt(i) !== QUOTE) return null;
+      const keyEnd = stringEnd(text, i);
+      if (keyEnd === -1) return null;
+      const key = decodeKey(bytes, text, i, keyEnd);
+      if (seen.has(key)) return null;
+      seen.add(key);
+      const colon = skipSpaces(text, keyEnd);
+      if (text.charCodeAt(colon) !== COLON) return null;
+      const start = skipSpaces(text, colon + 1);
+      const wanted = decode(key);
+      let end;
+      if (wanted && key === 'messages' && text.charCodeAt(start) === OPEN_ARRAY) {
+        const value = messagesValue(bytes, text, start, fullRoles, tailUntil);
+        if (!value) return null;
+        end = value.end;
+        defineMember(doc, key, value.messages);
+      } else {
+        end = valueEnd(text, start);
+        if (end === -1) return null;
+        if (wanted) defineMember(doc, key, decodeSlice(bytes, start, end));
+      }
+      i = skipSpaces(text, end);
+      if (text.charCodeAt(i) === COMMA) {
+        i = skipSpaces(text, i + 1);
+        continue;
+      }
+      if (text.charCodeAt(i) !== CLOSE_OBJECT) return null;
+      i++;
+      break;
+    }
+  }
+  return skipSpaces(text, i) === text.length ? doc : null;
+}
+
+/**
+ * `readTopLevelLifecycleRecord` of the UTF-8 document in `bytes`, with `doc`
+ * decoded as described above — only for a proven document; a record from the
+ * authoritative fallback carries the complete document. Consumers must read
+ * nothing but non-skipped fields and, of non-full messages, `role`.
+ */
+export function readStrictRecordFields(bytes, { skip = EMPTY, fullMessageRoles = EMPTY, fullTailUntil = null } = {}) {
+  const doc = provenTopLevelObject(bytes, (key) => !skip.has(key), fullMessageRoles, fullTailUntil);
+  return doc ? lifecycleRecordOf(doc) : readTopLevelLifecycleRecord(bytes.toString('utf8'));
+}