chainlesschain 0.163.6 → 0.163.7

package/src/harness/jsonl-session-store.js

@@ -32,9 +32,7 @@ import {
 } from "../lib/secure-file-identity.js";
 import {
   computeEventHash,
-  latestChainHash,
   TRANSCRIPT_CHAIN_STATUS,
-  verifyTranscriptText,
 } from "./transcript-integrity.js";
 import { withFileLock } from "../lib/with-file-lock.js";
 import {
@@ -47,8 +45,10 @@ import {
   SESSION_FORK_AUTHORITY_FIELD,
 } from "../lib/session-message-provenance.js";
 import {
-  iterateFileLinesSync,
-  iterateFileLinesReverseSync,
+  assertFileLineByteLength,
+  DEFAULT_MAX_FILE_LINE_BYTES,
+  iterateFileLinesSync as iterateRawFileLinesSync,
+  iterateFileLinesReverseSync as iterateRawFileLinesReverseSync,
 } from "../lib/file-lines.js";
 import {
   emptySessionMeta,
@@ -69,6 +69,7 @@ import {
 } from "./session-list-index.js";
 import { createSessionPersistenceFailure } from "../lib/session-persistence-failure.js";
 import { withSessionHostWriteAuthority } from "../lib/session-host-lease.js";
+import { createSessionTranscriptStructureProjection } from "../lib/session-transcript-structure.js";
 import {
   listSessionAntiRollbackIds,
   publishSessionAntiRollbackAnchor,
@@ -89,6 +90,7 @@ export const _sessionScaleFaultHooks = Object.seal({
   beforeTranscriptDirectoryFsync: null,
   afterTranscriptDirectoryFsync: null,
   afterTranscriptAppend: null,
+  beforeVerifiedProjectionRepair: null,
   afterForkCopy: null,
   afterForkLineage: null,
   afterForkPublish: null,
@@ -99,6 +101,9 @@ export const WS_TURN_EVENT = "ws_turn";
 export const WS_TURN_CLAIM_EVENT = "ws_turn_claim";
 export const WS_TURN_SCHEMA_VERSION = 1;
 export const WS_TURN_REQUEST_ID_MAX_BYTES = 128;
+export const CANONICAL_JSONL_RECORD_MAX_BYTES = DEFAULT_MAX_FILE_LINE_BYTES;
+export const CANONICAL_JSONL_RECORD_TOO_LARGE_CODE =
+  "CC_SESSION_JSONL_RECORD_TOO_LARGE";
 const WS_TURN_CONTENT_MAX_BYTES = 4 * 1024 * 1024;
 const WS_TURN_REQUEST_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:@-]*$/;
 const WS_TURN_INPUT_DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
@@ -110,6 +115,91 @@ export {
   SESSION_GENERATION_AUTHORITY_SCHEMA,
 };
 
+function canonicalJsonlSizeOptions(maxRecordBytes) {
+  return {
+    maxLineBytes: resolveCanonicalJsonlRecordMaxBytes(maxRecordBytes),
+    code: CANONICAL_JSONL_RECORD_TOO_LARGE_CODE,
+    label: "Canonical session JSONL record",
+  };
+}
+
+export function resolveCanonicalJsonlRecordMaxBytes(
+  maxRecordBytes = CANONICAL_JSONL_RECORD_MAX_BYTES,
+) {
+  const parsed = Number(maxRecordBytes);
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    throw new TypeError("maxRecordBytes must be a positive safe integer");
+  }
+  // Optional limits are test seams / caller-side tightening only. No caller
+  // may raise the canonical on-disk hard cap.
+  return Math.min(parsed, CANONICAL_JSONL_RECORD_MAX_BYTES);
+}
+
+export function assertCanonicalJsonlRecordByteLength(
+  byteLength,
+  maxRecordBytes = CANONICAL_JSONL_RECORD_MAX_BYTES,
+) {
+  assertFileLineByteLength(
+    byteLength,
+    canonicalJsonlSizeOptions(maxRecordBytes),
+  );
+  return byteLength;
+}
+
+export function assertCanonicalJsonlRecordSize(
+  serialized,
+  maxRecordBytes = CANONICAL_JSONL_RECORD_MAX_BYTES,
+) {
+  if (typeof serialized !== "string") {
+    throw new TypeError("Canonical session JSONL record must be a string");
+  }
+  return assertCanonicalJsonlRecordByteLength(
+    Buffer.byteLength(serialized, "utf8"),
+    maxRecordBytes,
+  );
+}
+
+export function serializeCanonicalJsonlRecord(
+  event,
+  maxRecordBytes = CANONICAL_JSONL_RECORD_MAX_BYTES,
+) {
+  const serialized = JSON.stringify(event);
+  assertCanonicalJsonlRecordSize(serialized, maxRecordBytes);
+  return serialized;
+}
+
+export function parseCanonicalJsonlRecord(
+  line,
+  maxRecordBytes = CANONICAL_JSONL_RECORD_MAX_BYTES,
+) {
+  assertCanonicalJsonlRecordSize(line, maxRecordBytes);
+  return JSON.parse(line);
+}
+
+function rethrowCanonicalJsonlRecordLimit(error) {
+  if (error?.code === CANONICAL_JSONL_RECORD_TOO_LARGE_CODE) throw error;
+}
+
+function canonicalLineOptions(options = {}) {
+  return {
+    ...options,
+    maxLineBytes: CANONICAL_JSONL_RECORD_MAX_BYTES,
+    lineTooLargeCode: CANONICAL_JSONL_RECORD_TOO_LARGE_CODE,
+    lineLabel: "Canonical session JSONL record",
+  };
+}
+
+function iterateCanonicalJsonlLinesSync(filePath, options = {}) {
+  return iterateRawFileLinesSync(filePath, canonicalLineOptions(options));
+}
+
+function iterateCanonicalJsonlLinesReverseSync(filePath, options = {}) {
+  return iterateRawFileLinesReverseSync(
+    filePath,
+    canonicalLineOptions(options),
+  );
+}
+
 function wsTurnError(message, code) {
   const error = new Error(message);
   error.code = code;
@@ -674,17 +764,23 @@ function inspectPhysicalTail(filePath, { dryRun = false } = {}) {
             found = true;
           }
         }
-        const tail = Buffer.allocUnsafe(size - tailStart);
+        const tailBytes = size - tailStart;
+        assertFileLineByteLength(
+          tailBytes,
+          canonicalJsonlSizeOptions(CANONICAL_JSONL_RECORD_MAX_BYTES),
+        );
+        const tail = Buffer.allocUnsafe(tailBytes);
         if (tail.length > 0) readSync(fd, tail, 0, tail.length, tailStart);
         try {
           const text = new TextDecoder("utf-8", { fatal: true }).decode(tail);
-          JSON.parse(text);
+          parseCanonicalJsonlRecord(text);
           // A valid legacy/manual last record merely lacks its newline; retain
           // it and normalize before appending the next chained event.
           result.action = "normalize-newline";
           result.changed = true;
           normalizeNewline = !dryRun;
-        } catch {
+        } catch (error) {
+          rethrowCanonicalJsonlRecordLimit(error);
           // Crash tail: discard only the one incomplete physical record.
           result.action = "discard-partial-record";
           result.changed = true;
@@ -714,19 +810,20 @@ function _resolveChainTail(filePath) {
   // Fast path: almost every append follows a newline-terminated record. Read
   // that tail once and avoid opening the file a second time just to inspect its
   // last byte. The slow repair path runs only for an unterminated crash tail.
-  const initial = iterateFileLinesReverseSync(filePath);
+  const initial = iterateCanonicalJsonlLinesReverseSync(filePath);
   const first = initial.next();
   if (!first.done && first.value.terminated) {
     try {
       let current = first;
       while (!current.done) {
         try {
-          const event = JSON.parse(current.value.line);
+          const event = parseCanonicalJsonlRecord(current.value.line);
           return {
             prevHash: typeof event?.hash === "string" ? event.hash : null,
             recovery: null,
           };
-        } catch {
+        } catch (error) {
+          rethrowCanonicalJsonlRecordLimit(error);
           current = initial.next();
         }
       }
@@ -738,14 +835,15 @@ function _resolveChainTail(filePath) {
   initial.return?.();
 
   const recovery = inspectPhysicalTail(filePath);
-  for (const { line } of iterateFileLinesReverseSync(filePath)) {
+  for (const { line } of iterateCanonicalJsonlLinesReverseSync(filePath)) {
     try {
-      const event = JSON.parse(line);
+      const event = parseCanonicalJsonlRecord(line);
       return {
         prevHash: typeof event?.hash === "string" ? event.hash : null,
         recovery: recovery.changed ? recovery : null,
       };
-    } catch {
+    } catch (error) {
+      rethrowCanonicalJsonlRecordLimit(error);
       // A malformed historical line is verified separately; keep searching so
       // this append never chains from arbitrary bytes.
     }
@@ -934,6 +1032,10 @@ function appendTranscriptEventAtPath({
   expectedState,
   parentDevice,
 }) {
+  // Bound the complete persisted envelope (including hash/prevHash) before
+  // opening or writing the canonical transcript.
+  const serializedEvent = serializeCanonicalJsonlRecord(event);
+  const bytes = Buffer.from(`${serializedEvent}\n`, "utf8");
   let fd = null;
   let wroteBytes = false;
   let appendCompleted = false;
@@ -975,7 +1077,6 @@ function appendTranscriptEventAtPath({
         }
       }
     }
-    const bytes = Buffer.from(`${JSON.stringify(event)}\n`, "utf8");
     let offset = 0;
     while (offset < bytes.length) {
       const written = writeSync(fd, bytes, offset, bytes.length - offset);
@@ -1201,11 +1302,12 @@ function antiRollbackAnchorMatchesCandidate(anchor, candidate) {
 function transcriptHashAtEventCount(filePath, eventCount) {
   if (eventCount === 0) return null;
   let count = 0;
-  for (const { line } of iterateFileLinesSync(filePath)) {
+  for (const { line } of iterateCanonicalJsonlLinesSync(filePath)) {
     let event;
     try {
-      event = JSON.parse(line);
-    } catch {
+      event = parseCanonicalJsonlRecord(line);
+    } catch (error) {
+      rethrowCanonicalJsonlRecordLimit(error);
       continue;
     }
     if (typeof event?.hash !== "string") continue;
@@ -1580,79 +1682,188 @@ export function appendAuthorityEventWithVerifiedProjection(
     );
   }
   const filePath = sessionPath(sessionId);
-  return withSessionHostWriterLock(
-    sessionId,
-    filePath,
-    () => {
-      const projection = createProjection();
-      if (
-        !projection ||
-        typeof projection.accept !== "function" ||
-        typeof projection.finish !== "function"
-      ) {
-        throw new TypeError(
-          "Authority projection must provide accept() and finish()",
-        );
-      }
-      if (!existsSync(filePath)) {
-        throw unverifiedTranscriptError(sessionId, {
-          status: "missing",
-          reason: "authority transcript does not exist",
-          lastHash: null,
-          chainedEvents: 0,
-        });
-      }
-      _resolveChainTail(filePath);
-      const verification = verifyTranscriptFile(filePath, {
-        onVerifiedEvent: (event) => {
-          const accepted = projection.accept(event);
-          if (accepted && typeof accepted.then === "function") {
-            throw new TypeError(
-              "Authority projection accept() must be synchronous",
-            );
-          }
-        },
-      });
-      assertVerifiedTranscriptAnchor(sessionId, verification);
-      const authority = Object.freeze({
-        headHash: verification.lastHash,
-        eventCount: verification.chainedEvents,
-        readMessages: () => rebuildVerifiedMessagesFromFile(filePath),
-      });
-      const projected = projection.finish(authority);
-      if (projected && typeof projected.then === "function") {
-        throw new TypeError(
-          "Authority projection finish() must be synchronous",
-        );
-      }
-      const validation = validateProjection(projected, authority);
-      if (validation && typeof validation.then === "function") {
-        throw new TypeError(
-          "Authority projection validation must be synchronous",
-        );
-      }
-      if (validation === false) {
-        throw new Error("Authority projection validation rejected the append");
+  let intendedAppend = null;
+  try {
+    return runClassifiedAppend(
+      sessionId,
+      "verified-projection-authority-append",
+      () =>
+        withSessionHostWriterLock(
+          sessionId,
+          filePath,
+          () => {
+            const projection = createProjection();
+            if (
+              !projection ||
+              typeof projection.accept !== "function" ||
+              typeof projection.finish !== "function"
+            ) {
+              throw new TypeError(
+                "Authority projection must provide accept() and finish()",
+              );
+            }
+            if (!existsSync(filePath)) {
+              throw unverifiedTranscriptError(sessionId, {
+                status: "missing",
+                reason: "authority transcript does not exist",
+                lastHash: null,
+                chainedEvents: 0,
+              });
+            }
+            _resolveChainTail(filePath);
+            const verification = verifyTranscriptFile(filePath, {
+              onVerifiedEvent: (event) => {
+                const accepted = projection.accept(event);
+                if (accepted && typeof accepted.then === "function") {
+                  throw new TypeError(
+                    "Authority projection accept() must be synchronous",
+                  );
+                }
+              },
+            });
+            assertVerifiedTranscriptAnchor(sessionId, verification);
+            const authority = Object.freeze({
+              headHash: verification.lastHash,
+              eventCount: verification.chainedEvents,
+              readMessages: () => rebuildVerifiedMessagesFromFile(filePath),
+            });
+            const projected = projection.finish(authority);
+            if (projected && typeof projected.then === "function") {
+              throw new TypeError(
+                "Authority projection finish() must be synchronous",
+              );
+            }
+            const validation = validateProjection(projected, authority);
+            if (validation && typeof validation.then === "function") {
+              throw new TypeError(
+                "Authority projection validation must be synchronous",
+              );
+            }
+            if (validation === false) {
+              throw new Error(
+                "Authority projection validation rejected the append",
+              );
+            }
+            const persistedData = encodeEventMessageProvenance(type, data);
+            let appended;
+            try {
+              appended = appendVerifiedWsAuthorityEventLocked(
+                sessionId,
+                filePath,
+                type,
+                persistedData,
+                authority.headHash,
+              );
+            } catch (error) {
+              // The transcript append can succeed before its metadata/anti-rollback
+              // anchor reports an ambiguous settlement. Perform an exact locked
+              // readback before releasing the writer authority: if the intended
+              // event is now the verified physical head, repair the rebuildable
+              // sidecar and publish a fresh anti-rollback witness. Callers may then
+              // safely treat the authority mutation as committed exactly once.
+              if (error?.commitState !== "unknown") throw error;
+              let intended = null;
+              const verification = verifyTranscriptFile(filePath, {
+                onVerifiedEvent: (event) => {
+                  intended = event;
+                },
+              });
+              const exactPhysicalCommit =
+                verification.status === TRANSCRIPT_CHAIN_STATUS.VERIFIED &&
+                verification.malformedLines === 0 &&
+                !verification.truncatedTail &&
+                intended?.prevHash === authority.headHash &&
+                intended?.type === type &&
+                JSON.stringify(intended?.data) ===
+                  JSON.stringify(persistedData);
+              if (!exactPhysicalCommit) throw error;
+              intendedAppend = Object.freeze({
+                previousHeadHash: authority.headHash,
+                type,
+                data: persistedData,
+                hash: intended.hash,
+              });
+              try {
+                runSessionScaleFaultHook("beforeVerifiedProjectionRepair", {
+                  sessionId,
+                  type,
+                  hash: intended.hash,
+                });
+                const repairedMeta = rebuildSessionMetaUnlocked(
+                  getSessionsDir(),
+                  sessionId,
+                  filePath,
+                );
+                publishSessionAntiRollbackWitness(
+                  sessionId,
+                  repairedMeta,
+                  filePath,
+                  "live",
+                );
+                assertVerifiedTranscriptAnchor(sessionId, verification);
+              } catch (cause) {
+                const repairError = new Error(
+                  `Session authority repair failed after exact physical commit: ${sessionId}`,
+                  { cause },
+                );
+                repairError.code = "SESSION_INDEX_ANCHOR_FAILED";
+                repairError.sessionId = sessionId;
+                repairError.commitState = "unknown";
+                throw repairError;
+              }
+              appended = Object.freeze({
+                hash: intended.hash,
+                event: intended,
+                commitState: "committed-after-readback",
+              });
+            }
+            if (intendedAppend === null) {
+              intendedAppend = Object.freeze({
+                previousHeadHash: authority.headHash,
+                type,
+                data: persistedData,
+                hash: appended.hash,
+              });
+            }
+            return Object.freeze({ hash: appended.hash });
+          },
+          {
+            failIfUnavailable: true,
+            timeoutMs: 30_000,
+            retryMs: 1,
+            maxRetryMs: 8,
+            retryJitterMs: 4,
+            yieldAfterReleaseMs: 2,
+          },
+        ),
+    );
+  } catch (error) {
+    // A strict lock-release failure happens after the callback returned. The
+    // append is already settled at that point, but runClassifiedAppend must
+    // conservatively label the operation unknown. Adjudicate only an exact
+    // verified head match; otherwise preserve the unknown outcome.
+    if (intendedAppend) {
+      try {
+        const events = readVerifiedEvents(sessionId);
+        const head = events.at(-1);
+        if (
+          head?.hash === intendedAppend.hash &&
+          head?.prevHash === intendedAppend.previousHeadHash &&
+          head?.type === intendedAppend.type &&
+          JSON.stringify(head?.data) === JSON.stringify(intendedAppend.data)
+        ) {
+          return Object.freeze({
+            hash: head.hash,
+            commitState: "committed-after-lock-release-readback",
+          });
+        }
+      } catch {
+        // Preserve the original classified persistence error.
       }
-      const persistedData = encodeEventMessageProvenance(type, data);
-      const appended = appendVerifiedWsAuthorityEventLocked(
-        sessionId,
-        filePath,
-        type,
-        persistedData,
-        authority.headHash,
-      );
-      return Object.freeze({ hash: appended.hash });
-    },
-    {
-      failIfUnavailable: true,
-      timeoutMs: 30_000,
-      retryMs: 1,
-      maxRetryMs: 8,
-      retryJitterMs: 4,
-      yieldAfterReleaseMs: 2,
-    },
-  );
+    }
+    if (intendedAppend && !error?.commitState) error.commitState = "unknown";
+    throw error;
+  }
 }
 
 /**
@@ -1885,13 +2096,15 @@ function verifyTranscriptFile(filePath, options = {}) {
     reason,
   });
 
-  for (const { line, lineNo, terminated } of iterateFileLinesSync(filePath, {
-    ioMetrics,
-  })) {
+  for (const { line, lineNo, terminated } of iterateCanonicalJsonlLinesSync(
+    filePath,
+    { ioMetrics },
+  )) {
     let event;
     try {
-      event = JSON.parse(line);
-    } catch {
+      event = parseCanonicalJsonlRecord(line);
+    } catch (error) {
+      rethrowCanonicalJsonlRecordLimit(error);
       result.malformedLines += 1;
       if (!terminated) {
         result.truncatedTail = true;
@@ -2242,11 +2455,98 @@ export function startSession(sessionId, meta = {}) {
     title: meta.title || "Untitled",
     provider: meta.provider || "",
     model: meta.model || "",
+    ...(meta.observabilityScope != null
+      ? {
+          observabilityScope: normalizeObservabilityScope(
+            meta.observabilityScope,
+          ),
+          usageTelemetryProtocol: "call-ledger",
+          usageTelemetryVersion: 1,
+        }
+      : {}),
   });
 
   return id;
 }
 
+/** Return the anchored transcript revision used by delivery causality bindings. */
+export function getVerifiedSessionObservabilityAuthority(sessionId) {
+  return readVerifiedProjection(sessionId, () => {
+    let sessionStartSeen = false;
+    let hasObservabilityScope = false;
+    let observabilityScope = null;
+    return {
+      accept(event) {
+        if (event?.type === "session_start" && !sessionStartSeen) {
+          sessionStartSeen = true;
+          if (Object.hasOwn(event.data || {}, "observabilityScope")) {
+            hasObservabilityScope = true;
+            observabilityScope = event.data.observabilityScope;
+          }
+        }
+      },
+      finish(authority) {
+        if (!authority.headHash || authority.eventCount <= 0) {
+          throw unverifiedTranscriptError(sessionId, {
+            status: "empty",
+            reason: "session has no anchored transcript events",
+          });
+        }
+        if (!hasObservabilityScope) {
+          const error = new Error(
+            `session ${sessionId} has no observabilityScope authority`,
+          );
+          error.code = "SESSION_OBSERVABILITY_SCOPE_MISSING";
+          throw error;
+        }
+        const normalizedScope = normalizeObservabilityScope(observabilityScope);
+        return Object.freeze({
+          sessionId,
+          headHash: authority.headHash,
+          eventCount: authority.eventCount,
+          observabilityScope: Object.freeze(normalizedScope),
+        });
+      },
+    };
+  });
+}
+
+function hasAsciiControlCharacter(value) {
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index);
+    if (code <= 0x1f || code === 0x7f) return true;
+  }
+  return false;
+}
+
+function normalizeObservabilityScope(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError("observabilityScope must be an object");
+  }
+  const normalize = (input, field) => {
+    if (input == null) return null;
+    if (typeof input !== "string") {
+      throw new TypeError(`observabilityScope.${field} must be a string`);
+    }
+    const output = input.trim();
+    if (!output || output.length > 256 || hasAsciiControlCharacter(output)) {
+      throw new TypeError(`observabilityScope.${field} is invalid`);
+    }
+    return output;
+  };
+  const normalized = {
+    workspaceId: normalize(value.workspaceId, "workspaceId"),
+    teamId: normalize(value.teamId, "teamId"),
+    policyId: normalize(value.policyId, "policyId"),
+  };
+  if (!Object.values(normalized).some((scopeId) => scopeId != null)) {
+    throw new TypeError(
+      "observabilityScope requires at least one non-null dimension",
+    );
+  }
+  return normalized;
+}
+
 export function appendUserMessage(sessionId, content) {
   return appendEvent(sessionId, "user_message", {
     role: "user",
@@ -2502,10 +2802,23 @@ export function appendToolCall(sessionId, toolName, args) {
  */
 export function appendToolCallCompact(
   sessionId,
-  { tool, isError, skill, plugin, pluginVersion, durationMs } = {},
+  { id, tool, isError, skill, plugin, pluginVersion, durationMs } = {},
 ) {
+  const cleanId =
+    id === undefined
+      ? null
+      : typeof id === "string" &&
+          id.trim() &&
+          id.length <= 128 &&
+          !/\p{Cc}/u.test(id)
+        ? id.trim()
+        : null;
+  if (id !== undefined && !cleanId) {
+    throw new TypeError("compact tool call id must be a bounded string");
+  }
   const duration = normalizeCompactDuration(durationMs);
   appendEvent(sessionId, "tool_call", {
+    ...(cleanId ? { id: cleanId } : {}),
     tool: tool || "?",
     is_error: Boolean(isError),
     ...(skill ? { skill: String(skill) } : {}),
@@ -2631,10 +2944,11 @@ export function readEvents(sessionId) {
   if (!existsSync(filePath)) return [];
 
   const events = [];
-  for (const { line } of iterateFileLinesSync(filePath)) {
+  for (const { line } of iterateCanonicalJsonlLinesSync(filePath)) {
     try {
-      events.push(JSON.parse(line));
-    } catch {
+      events.push(parseCanonicalJsonlRecord(line));
+    } catch (error) {
+      rethrowCanonicalJsonlRecordLimit(error);
       // Skip malformed lines
     }
   }
@@ -2823,11 +3137,16 @@ export function readVerifiedProjection(
           }),
         );
       }
+      const structure = createSessionTranscriptStructureProjection(sessionId);
       const verification = verifyTranscriptFile(filePath, {
         ioMetrics: options.ioMetrics,
-        onVerifiedEvent: (event) => projection.accept(event),
+        onVerifiedEvent: (event) => {
+          structure.accept(event);
+          projection.accept(event);
+        },
       });
       assertVerifiedTranscriptAnchor(sessionId, verification);
+      structure.finish({ assertValid: true });
       return projection.finish(
         Object.freeze({
           headHash: verification.lastHash,
@@ -2945,6 +3264,10 @@ function readVerifiedTranscriptBytesAtPath(sessionId, filePath, parentDevice) {
         "the read descriptor does not match the canonical path",
       );
     }
+    // Verify with the bounded line iterator before materializing the requested
+    // full transcript. A single attacker-controlled record can therefore never
+    // force readFileSync/JSON parsing to allocate an unbounded line first.
+    const verification = verifyTranscriptFile(filePath);
     const text = readFileSync(fd, "utf8");
     const afterStats = fstatSync(fd, { bigint: true });
     const after = physicalTranscriptStateFromStats(afterStats);
@@ -2964,10 +3287,6 @@ function readVerifiedTranscriptBytesAtPath(sessionId, filePath, parentDevice) {
         "the transcript changed while verified bytes were read",
       );
     }
-    const verification = {
-      ...verifyTranscriptText(text),
-      lastHash: latestChainHash(text),
-    };
     assertVerifiedTranscriptAnchor(sessionId, verification, published);
     return text;
   } finally {
@@ -3077,11 +3396,14 @@ function rebuildMessagesFromFile(
   // replay state, but the file itself is still never loaded as one giant string.
   const suffix = [];
   let checkpoint = [];
-  for (const { line } of iterateFileLinesReverseSync(filePath, { ioMetrics })) {
+  for (const { line } of iterateCanonicalJsonlLinesReverseSync(filePath, {
+    ioMetrics,
+  })) {
     let event;
     try {
-      event = JSON.parse(line);
-    } catch {
+      event = parseCanonicalJsonlRecord(line);
+    } catch (error) {
+      rethrowCanonicalJsonlRecordLimit(error);
       continue;
     }
     if (
@@ -3155,11 +3477,12 @@ export function toIsoSafe(ts) {
 
 function rebuildSessionMetaUnlocked(dir, sessionId, filePath) {
   let meta = emptySessionMeta(sessionId);
-  for (const { line } of iterateFileLinesSync(filePath)) {
+  for (const { line } of iterateCanonicalJsonlLinesSync(filePath)) {
     try {
-      const event = JSON.parse(line);
+      const event = parseCanonicalJsonlRecord(line);
       meta = applyEventToSessionMeta(meta, event, event?.hash);
-    } catch {
+    } catch (error) {
+      rethrowCanonicalJsonlRecordLimit(error);
       // The validator/repair path reports malformed records. The index remains
       // a best-effort projection over all intact events.
     }
@@ -3742,17 +4065,19 @@ export function forkSession(sourceId, options = {}) {
               },
             };
             const hash = computeEventHash(prevHash, core);
-            appendFileSync(
-              workingPath,
-              `${JSON.stringify({ ...core, prevHash, hash })}\n`,
-              { encoding: "utf8", mode: 0o600 },
-            );
+            const lineageEvent = { ...core, prevHash, hash };
+            const serializedLineage =
+              serializeCanonicalJsonlRecord(lineageEvent);
+            appendFileSync(workingPath, `${serializedLineage}\n`, {
+              encoding: "utf8",
+              mode: 0o600,
+            });
             ensurePrivateFile(workingPath);
             runSessionScaleFaultHook("afterForkLineage", {
               sourceId,
               sessionId: newId,
               filePath: workingPath,
-              event: { ...core, prevHash, hash },
+              event: lineageEvent,
             });
             target = inspectTarget();
             targetMeta = readSessionMeta(sessionsDir, newId);
@@ -4426,16 +4751,14 @@ export function validateJsonlSession(sessionId) {
   }
 
   let malformedLines = 0;
-  let eventCount = 0;
   let messageCount = 0;
   let invalidWsTurns = 0;
   let invalidWsClaims = 0;
-  let hasStartEvent = false;
-  for (const { line } of iterateFileLinesSync(filePath)) {
+  const structure = createSessionTranscriptStructureProjection(sessionId);
+  for (const { line } of iterateCanonicalJsonlLinesSync(filePath)) {
     try {
-      const event = JSON.parse(line);
-      eventCount += 1;
-      if (event?.type === "session_start") hasStartEvent = true;
+      const event = parseCanonicalJsonlRecord(line);
+      structure.accept(event);
       if (
         event?.type === "user_message" ||
         event?.type === "assistant_message"
@@ -4451,24 +4774,39 @@ export function validateJsonlSession(sessionId) {
       ) {
         invalidWsClaims += 1;
       }
-    } catch {
+    } catch (error) {
+      rethrowCanonicalJsonlRecordLimit(error);
       malformedLines++;
     }
   }
 
+  const structural = structure.finish();
+  const reason =
+    malformedLines > 0
+      ? "session contains malformed JSONL records"
+      : invalidWsTurns > 0
+        ? "session contains invalid WebSocket turn settlements"
+        : invalidWsClaims > 0
+          ? "session contains invalid WebSocket turn claims"
+          : structural.reason;
+
   return {
     sessionId,
     valid:
       malformedLines === 0 &&
       invalidWsTurns === 0 &&
       invalidWsClaims === 0 &&
-      hasStartEvent,
+      structural.valid,
+    reason,
     malformedLines,
     invalidWsTurns,
     invalidWsClaims,
-    eventCount,
+    eventCount: structural.eventCount,
     messageCount,
-    hasStartEvent,
+    hasStartEvent: structural.hasStartEvent,
+    sessionStartCount: structural.sessionStartCount,
+    sessionStartIndex: structural.sessionStartIndex,
+    sessionStartIsFirst: structural.sessionStartIsFirst,
   };
 }