pi-fold 2.0.0 → 3.1.0

package/extensions/lib/persistence.ts

@@ -22,6 +22,9 @@ import {
   EXPAND_LEASE_GENERATIONS,
   MAX_EXPAND_LEASES,
   MAX_PENDING_MARKS,
+  MEMORY_BODY_CHARS,
+  MEMORY_KEY_CHARS,
+  MEMORY_KEYS_MAX,
 } from "./policy.ts";
 import type {
   ActiveContextCheckpointV2,
@@ -32,6 +35,8 @@ import type {
   AdvisoryMilestone,
   BriefOverride,
   BriefProvenance,
+  ToolClip,
+  WorkingMemoryEntry,
   FoldKind,
   FoldPart,
   FoldRecordEntry,
@@ -56,7 +61,7 @@ export const PENDING_FOLD_MARK_KEYS = [
   "mark", "id", "kind", "parts", "brief", "briefProvenance", "origin", "ordinal",
 ] as const;
 export const PENDING_REFOLD_MARK_KEYS = ["mark", "id", "origin", "ordinal"] as const;
-export const MARK_ORIGINS = Object.freeze(["agent", "ladder"] as const);
+export const MARK_ORIGINS = Object.freeze(["agent", "ladder", "user"] as const);
 export const STATE_CHECKPOINT_V2_KEYS = [
   "version", "kind", "sessionId", "revision", "foldRefs", "expanded", "protected", "prepared", "stateSha256",
 ] as const;
@@ -91,8 +96,7 @@ export function validPendingMark(value: unknown): value is PendingMark {
   const kind = ownValue(value, "kind");
   const parts = denseOwnArrayValues(ownValue(value, "parts"));
   return (kind === "tool-result" || kind === "chapter" || kind === "consolidation") &&
-    Boolean(parts?.length) && parts!.length <= ACTIVE_CONTEXT_POLICY.maxFoldSourceRefs &&
-    parts!.every(validFoldPart) && structurallyValidBrief(ownValue(value, "brief")) &&
+    Boolean(parts?.length) && parts!.every(validFoldPart) && structurallyValidBrief(ownValue(value, "brief")) &&
     validProvenance(ownValue(value, "briefProvenance")) &&
     id === foldIdFor(kind as FoldKind, parts as FoldPart[]);
 }
@@ -168,7 +172,8 @@ export function parseLeases(value: unknown, foldIds?: ReadonlySet<string>): Reco
 
 export function validProvenance(value: unknown): value is BriefProvenance {
   if (exactRecord(value, ["kind"]) &&
-      (ownValue(value, "kind") === "supplied" || ownValue(value, "kind") === "deterministic")) return true;
+      (ownValue(value, "kind") === "supplied" || ownValue(value, "kind") === "deterministic" ||
+       ownValue(value, "kind") === "augmented")) return true;
   const hasDigest = Boolean(value && typeof value === "object" &&
     Object.prototype.hasOwnProperty.call(value, "launchContractDigest"));
   if (!exactRecord(value, ["kind", "provider", "model", "effort", ...(hasDigest ? ["launchContractDigest"] : [])]) ||
@@ -210,7 +215,6 @@ export function validFoldShape(value: unknown): value is ActiveFold {
   return (kind === "tool-result" || kind === "chapter" || kind === "consolidation") &&
     typeof ownValue(value, "id") === "string" && Boolean(ownValue(value, "id")) &&
     (parentId === null || typeof parentId === "string") && Boolean(parts?.length) &&
-    parts!.length <= ACTIVE_CONTEXT_POLICY.maxFoldSourceRefs &&
     parts!.every(validFoldPart) && structurallyValidBrief(ownValue(value, "brief")) &&
     validProvenance(ownValue(value, "provenance")) && typeof sourceSha256 === "string" &&
     /^[a-f0-9]{64}$/.test(sourceSha256) && Number.isSafeInteger(ownValue(value, "sourceChars")) &&
@@ -325,7 +329,11 @@ export function parseActiveContextState(
   const hasPendingMarks = recordLike && Object.prototype.hasOwnProperty.call(value, "pendingMarks");
   const hasPinnedPeeks = recordLike && Object.prototype.hasOwnProperty.call(value, "pinnedPeeks");
   const hasBriefs = recordLike && Object.prototype.hasOwnProperty.call(value, "briefs");
-  const hasRider = recordLike && Object.prototype.hasOwnProperty.call(value, "rider");
+  const hasClips = recordLike && Object.prototype.hasOwnProperty.call(value, "clips");
+  const hasMemory = recordLike && Object.prototype.hasOwnProperty.call(value, "memory");
+  // Read and dropped, never stored: see legacyRiderStateSha256. A v1 state has no digest
+  // to reproduce, so here the tolerance is the whole of it.
+  const hasLegacyRider = recordLike && Object.prototype.hasOwnProperty.call(value, "rider");
   refuseRetiredStateFields(value);
   const extraKeys = [
     ...(hasPrepared ? ["prepared"] : []),
@@ -335,7 +343,9 @@ export function parseActiveContextState(
     ...(hasPendingMarks ? ["pendingMarks"] : []),
     ...(hasPinnedPeeks ? ["pinnedPeeks"] : []),
     ...(hasBriefs ? ["briefs"] : []),
-    ...(hasRider ? ["rider"] : []),
+    ...(hasClips ? ["clips"] : []),
+    ...(hasMemory ? ["memory"] : []),
+    ...(hasLegacyRider ? ["rider"] : []),
   ];
   if (!exactRecord(value, [...ACTIVE_STATE_KEYS, ...extraKeys])) throw new Error("Invalid active-context state keys");
   const folds = denseOwnArrayValues(ownValue(value, "folds"));
@@ -357,9 +367,6 @@ export function parseActiveContextState(
   if (hasAdvisory && !validAdvisoryState(ownValue(value, "advisory"))) {
     throw new Error("Invalid active-context advisory state");
   }
-  if (hasRider && !validRiderState(ownValue(value, "rider"))) {
-    throw new Error("Invalid active-context rider state");
-  }
   if (hasTokensSinceToolFold && !validTokensSinceToolFold(ownValue(value, "tokensSinceToolFold"))) {
     throw new Error("Invalid active-context tool-fold cadence");
   }
@@ -369,6 +376,8 @@ export function parseActiveContextState(
     throw new Error("Invalid active-context pending marks");
   }
   const briefs = hasBriefs ? parseBriefOverrides(ownValue(value, "briefs"), ids) : {};
+  const clips = hasClips ? parseToolClips(ownValue(value, "clips")) : [];
+  const memory = hasMemory ? parseWorkingMemory(ownValue(value, "memory")) : [];
   const source = clone(value) as unknown as ActiveContextState;
   return {
     version: 1,
@@ -383,14 +392,56 @@ export function parseActiveContextState(
     leases,
     ...(marks.length ? { pendingMarks: marks } : {}),
     ...(Object.keys(briefs).length ? { briefs } : {}),
+    ...(clips.length ? { clips } : {}),
+    ...(memory.length ? { memory } : {}),
     ...(hasAdvisory
       ? { advisory: clone(source.advisory!) }
       : defaultAdvisory ? { advisory: { highWater: 0, delivered: {} } } : {}),
-    ...(hasRider ? { rider: clone(source.rider!) } : {}),
     ...(hasPrepared ? { prepared: clone(source.prepared!) } : {}),
   };
 }
 
+function parseToolClips(value: unknown): ToolClip[] {
+  const entries = denseOwnArrayValues(value);
+  if (!entries) throw new Error("Invalid active-context clips");
+  const clips = entries.map((entry) => {
+    if (!exactRecord(entry, ["callId", "entryId"]) ||
+        typeof ownValue(entry, "callId") !== "string" || !ownValue(entry, "callId") ||
+        typeof ownValue(entry, "entryId") !== "string" || !ownValue(entry, "entryId")) {
+      throw new Error("Invalid active-context clip entry");
+    }
+    return { callId: String(ownValue(entry, "callId")), entryId: String(ownValue(entry, "entryId")) };
+  });
+  if (new Set(clips.map((clip) => clip.callId)).size !== clips.length) {
+    throw new Error("Invalid active-context clips: duplicate call id");
+  }
+  return clips;
+}
+
+function parseWorkingMemory(value: unknown): WorkingMemoryEntry[] {
+  const entries = denseOwnArrayValues(value);
+  if (!entries) throw new Error("Invalid active-context working memory");
+  const memory = entries.map((entry) => {
+    const key = ownValue(entry, "key");
+    const body = ownValue(entry, "body");
+    const ordinal = ownValue(entry, "ordinal");
+    if (!exactRecord(entry, ["key", "body", "ordinal"]) ||
+        typeof key !== "string" || !key || key.length > MEMORY_KEY_CHARS ||
+        typeof body !== "string" || !body || body.length > MEMORY_BODY_CHARS ||
+        !Number.isSafeInteger(ordinal) || Number(ordinal) < 0) {
+      throw new Error("Invalid active-context working-memory entry");
+    }
+    return { key, body, ordinal: Number(ordinal) };
+  });
+  if (memory.length > MEMORY_KEYS_MAX) {
+    throw new Error(`Invalid active-context working memory: over ${MEMORY_KEYS_MAX} entries`);
+  }
+  if (new Set(memory.map((entry) => entry.key)).size !== memory.length) {
+    throw new Error("Invalid active-context working memory: duplicate key");
+  }
+  return memory;
+}
+
 export function clearPrepared(state: ActiveContextState): ActiveContextState {
   const next = { ...state };
   delete next.prepared;
@@ -416,8 +467,24 @@ export function validatePreparedShape(value: unknown): asserts value is Prepared
   }
 }
 
+// THE SPREAD IS THE COPY (2026-08-28). Roughly six calls per fold per persist, and only
+// `deriveFoldParents` wants a record it can write to, where it writes the TOP-LEVEL
+// `parentId` that the spread already gives it a fresh slot for. Every other caller hashes
+// and discards: `foldRecordRef`, `sameFoldRecordIdentity`, and `makeFoldRecordEntry`, whose
+// `parseFoldRecordEntry` deep-clones twice on its own.
+//
+// The digest cannot move. `safeJson` emits in `Reflect.ownKeys` order, a spread preserves
+// insertion order, and overwriting an existing key keeps it in its original position, so
+// `{ ...fold, parentId: null }` serializes to the same bytes as the cloned form.
+//
+// THE COST, STATED BECAUSE IT IS NOW LOAD-BEARING: the returned record shares every nested
+// object with its input, so "no caller mutates a canonical record's nested fields" is a rule
+// this function relies on rather than enforces. It holds today (`validateFoldForest` clones
+// at :281, `parseFoldRecordEntry` twice at :567-568, the hashing callers never write), and a
+// future caller that writes through `record.parts` would corrupt the fold it was built from.
+// Write `{ ...record, field: value }` rather than assigning into a nested one.
 export function canonicalFoldRecord(fold: ActiveFold): ActiveFold {
-  return { ...clone(fold), parentId: null };
+  return { ...fold, parentId: null };
 }
 
 export function sameFoldRecordIdentity(left: ActiveFold, right: ActiveFold): boolean {
@@ -441,6 +508,29 @@ export function legacyCadenceOmittedStateSha256(state: ActiveContextState): stri
   return sha256Value(legacy);
 }
 
+/**
+ * THE DIGEST A RIDER-ERA BUILD WROTE, reproduced without the subsystem.
+ *
+ * `semanticStateSha256` hashes the materialized state object, and `stableStringify` walks
+ * own keys in INSERTION order, so a field that is gone changes the digest even though it
+ * changed nothing else. The rider sat immediately before `prepared` in the materialized
+ * literal, and last when there was no prepared, so that is where it goes back for the one
+ * moment it is needed. It joins the two legacy derivations already here, which exist for
+ * exactly this reason: a state stays verifiable across the build that stopped writing it.
+ *
+ * Consulted ONLY when the wire actually carried a rider, so a current state whose digest
+ * has genuinely drifted still fails rather than finding a second way to pass.
+ */
+export function legacyRiderStateSha256(state: ActiveContextState, rider: unknown): string {
+  const legacy: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(state)) {
+    if (key === "prepared") legacy.rider = rider;
+    legacy[key] = value;
+  }
+  if (!Object.prototype.hasOwnProperty.call(legacy, "rider")) legacy.rider = rider;
+  return sha256Value(legacy);
+}
+
 export function legacyReplayOrderStateSha256(state: ActiveContextState): string {
   return sha256Value({
     version: state.version,
@@ -456,11 +546,18 @@ export function legacyReplayOrderStateSha256(state: ActiveContextState): string
 
 export function sameStateProjection(left: ActiveContextState, right: ActiveContextState): boolean {
   const normalized = (value: ActiveContextState): Partial<ActiveContextState> => {
-    const normalizedState = { ...clone(value), revision: 0 } as Partial<ActiveContextState>;
+    // A SHALLOW COPY IS ENOUGH TO DELETE TOP-LEVEL KEYS (2026-08-28). `delete` on a shallow
+    // copy cannot reach the original, the normalized object never escapes this function, and
+    // the runtime already stableStringifies live un-cloned state (`semanticStateSha256`), so
+    // un-cloned state is already required to be serializer-safe. Measured 97.6ms to 82.6ms
+    // on the largest real state in the corpus, at about two calls per provider request.
+    const normalizedState = { ...value, revision: 0 } as Partial<ActiveContextState>;
     if (normalizedState.tokensSinceToolFold === 0) delete normalizedState.tokensSinceToolFold;
     if (normalizedState.leases && Object.keys(normalizedState.leases).length === 0) delete normalizedState.leases;
     if (normalizedState.pendingMarks && normalizedState.pendingMarks.length === 0) delete normalizedState.pendingMarks;
     if (normalizedState.briefs && !Object.keys(normalizedState.briefs).length) delete normalizedState.briefs;
+    if (normalizedState.clips && normalizedState.clips.length === 0) delete normalizedState.clips;
+    if (normalizedState.memory && normalizedState.memory.length === 0) delete normalizedState.memory;
     return normalizedState;
   };
   return stableStringify(normalized(left)) === stableStringify(normalized(right));
@@ -503,13 +600,11 @@ export function validateV2ProjectionFields(
   leasesValue: unknown,
   pendingMarksValue?: unknown,
   briefsValue?: unknown,
-  riderValue?: unknown,
 ): {
   expanded: string[];
   protected: EvidenceRef[];
   prepared?: PreparedFold;
   advisory?: NonNullable<ActiveContextState["advisory"]>;
-  rider?: NonNullable<ActiveContextState["rider"]>;
   tokensSinceToolFold: number;
   leases: Record<string, number>;
   pendingMarks: PendingMark[];
@@ -527,9 +622,6 @@ export function validateV2ProjectionFields(
   if (advisoryValue !== undefined && !validAdvisoryState(advisoryValue)) {
     throw new Error("Invalid active-context v2 advisory state");
   }
-  if (riderValue !== undefined && !validRiderState(riderValue)) {
-    throw new Error("Invalid active-context v2 rider state");
-  }
   if (tokensSinceToolFoldValue !== undefined && !validTokensSinceToolFold(tokensSinceToolFoldValue)) {
     throw new Error("Invalid active-context v2 tool-fold cadence");
   }
@@ -543,9 +635,6 @@ export function validateV2ProjectionFields(
     ...(advisoryValue === undefined ? {} : {
       advisory: clone(advisoryValue) as NonNullable<ActiveContextState["advisory"]>,
     }),
-    ...(riderValue === undefined ? {} : {
-      rider: clone(riderValue) as NonNullable<ActiveContextState["rider"]>,
-    }),
     tokensSinceToolFold: tokensSinceToolFoldValue === undefined ? 0 : Number(tokensSinceToolFoldValue),
     leases,
     pendingMarks,
@@ -575,7 +664,15 @@ export function parseActiveContextStateV2(value: unknown, sessionId: string): Ac
     Object.prototype.hasOwnProperty.call(value, "addBriefs"));
   const hasRemoveBriefIds = Boolean(value && typeof value === "object" &&
     Object.prototype.hasOwnProperty.call(value, "removeBriefIds"));
-  const hasRider = Boolean(value && typeof value === "object" &&
+  const hasWireClips = Boolean(value && typeof value === "object" &&
+    Object.prototype.hasOwnProperty.call(value, "clips"));
+  const hasClipBase = Boolean(value && typeof value === "object" &&
+    Object.prototype.hasOwnProperty.call(value, "clipBase"));
+  const hasAddClips = Boolean(value && typeof value === "object" &&
+    Object.prototype.hasOwnProperty.call(value, "addClips"));
+  const hasWireMemory = Boolean(value && typeof value === "object" &&
+    Object.prototype.hasOwnProperty.call(value, "memory"));
+  const hasLegacyRider = Boolean(value && typeof value === "object" &&
     Object.prototype.hasOwnProperty.call(value, "rider"));
   refuseRetiredStateFields(value);
   const optionalKeys = [
@@ -589,7 +686,13 @@ export function parseActiveContextStateV2(value: unknown, sessionId: string): Ac
     ...(hasBriefs ? ["briefs"] : []),
     ...(hasAddBriefs ? ["addBriefs"] : []),
     ...(hasRemoveBriefIds ? ["removeBriefIds"] : []),
-    ...(hasRider ? ["rider"] : []),
+    ...(hasWireClips ? ["clips"] : []),
+    ...(hasClipBase ? ["clipBase"] : []),
+    ...(hasAddClips ? ["addClips"] : []),
+    ...(hasWireMemory ? ["memory"] : []),
+    // Carried no further than the digest check in `materializeStatePersistence`, which is
+    // the only thing on a load that the rider's absence can change.
+    ...(hasLegacyRider ? ["rider"] : []),
   ];
   const checkpoint = kind === "checkpoint" &&
     exactRecord(value, [...STATE_CHECKPOINT_V2_KEYS, ...optionalKeys]);
@@ -605,8 +708,19 @@ export function parseActiveContextStateV2(value: unknown, sessionId: string): Ac
     ownValue(value, "expanded"), ownValue(value, "protected"), ownValue(value, "prepared"),
     ownValue(value, "advisory"), ownValue(value, "tokensSinceToolFold"), ownValue(value, "leases"),
     ownValue(value, "pendingMarks"), ownValue(value, "briefs"),
-    ownValue(value, "rider"),
   );
+  if (hasWireClips) parseToolClips(ownValue(value, "clips"));
+  if (hasAddClips) parseToolClips(ownValue(value, "addClips"));
+  if (hasWireMemory) parseWorkingMemory(ownValue(value, "memory"));
+  if (hasClipBase) {
+    const base = ownValue(value, "clipBase");
+    if (!Number.isSafeInteger(base) || Number(base) < 0) throw new Error("Invalid active-context clip base");
+  }
+  // A whole array and a change cannot both be the truth on one wire.
+  if (hasWireClips && (hasClipBase || hasAddClips)) {
+    throw new Error("Invalid active-context clips: whole array beside a change");
+  }
+  if (hasAddClips && !hasClipBase) throw new Error("Invalid active-context clips: change without a base");
   if (checkpoint) {
     const refs = denseOwnArrayValues(ownValue(value, "foldRefs"));
     if (!refs || refs.length > MAX_ACTIVE_FOLD_RECORDS) throw new Error("Invalid active-context checkpoint refs");
@@ -681,7 +795,25 @@ export function normalizeFoldsForPersistedRecords(
   return deriveFoldParents(normalized);
 }
 
-export function deriveFoldParents(records: ActiveFold[]): ActiveFold[] {
+/**
+ * Rebuild the parent links a fold forest's records do not carry.
+ *
+ * THIS DOES NOT VALIDATE THE FOREST, and the split is deliberate. `validateFoldForest` deep
+ * clones the forest, recomputes `foldIdFor` per fold, and calls `flattenFoldRefs` per fold,
+ * which rebuilds `foldMap` over every fold; two of the four callers handed the result
+ * straight to `parseActiveContextState`, whose FIRST act is to validate it again. So a
+ * persist validated the same forest three times. Roughly 12ms saved at 88 folds, 28 at 178,
+ * 55 at 267, plus about 1.6x on the session-start load path.
+ *
+ * The child-record check above stays here, because it is about the ASSIGNMENT rather than
+ * the forest: a child claimed twice, or claimed by a parent that does not hold it, is a
+ * contradiction this loop is the only thing positioned to see.
+ *
+ * Callers that do not parse immediately afterwards want `deriveFoldParents` below. Reaching
+ * for this one is a claim that the very next statement validates the same array; nothing
+ * else makes it safe, and it reads at review as removing validation, which it is not.
+ */
+export function assignFoldParents(records: ActiveFold[]): ActiveFold[] {
   const folds = records.map(canonicalFoldRecord);
   const byId = new Map(folds.map((fold) => [fold.id, fold]));
   const assigned = new Set<string>();
@@ -693,14 +825,19 @@ export function deriveFoldParents(records: ActiveFold[]): ActiveFold[] {
       assigned.add(childId);
     }
   }
-  return validateFoldForest(folds);
+  return folds;
+}
+
+/** Assign the parents and validate the forest, for callers that do not parse next. */
+export function deriveFoldParents(records: ActiveFold[]): ActiveFold[] {
+  return validateFoldForest(assignFoldParents(records));
 }
 
 export function stateFromFoldRefs(
   wire: Pick<
     ActiveContextCheckpointV2,
     "sessionId" | "revision" | "expanded" | "protected" | "prepared" | "advisory" |
-      "tokensSinceToolFold" | "leases" | "pendingMarks" | "briefs" | "rider"
+      "tokensSinceToolFold" | "leases" | "pendingMarks" | "briefs" | "clips" | "memory"
   >,
   refs: FoldRecordRef[],
   records: Map<string, FoldRecordEntry>,
@@ -715,15 +852,18 @@ export function stateFromFoldRefs(
     version: 1,
     sessionId: wire.sessionId,
     revision: wire.revision,
-    folds: deriveFoldParents(folds),
+    // `parseActiveContextState` at the end of this function validates the forest, so
+    // validating it here as well was the same walk twice on one persist.
+    folds: assignFoldParents(folds),
     expanded: clone(wire.expanded),
     protected: clone(wire.protected),
     tokensSinceToolFold: wire.tokensSinceToolFold ?? 0,
     leases: clone(wire.leases ?? {}),
     ...(wire.pendingMarks?.length ? { pendingMarks: clone(wire.pendingMarks) } : {}),
     ...(wire.briefs && Object.keys(wire.briefs).length ? { briefs: clone(wire.briefs) } : {}),
+    ...(wire.clips?.length ? { clips: clone(wire.clips) } : {}),
+    ...(wire.memory?.length ? { memory: clone(wire.memory) } : {}),
     ...(wire.advisory === undefined ? {} : { advisory: clone(wire.advisory) }),
-    ...(wire.rider === undefined ? {} : { rider: clone(wire.rider) }),
     ...(wire.prepared === null || wire.prepared === undefined ? {} : { prepared: clone(wire.prepared) }),
   };
   return parseActiveContextState(state, wire.sessionId, false);
@@ -793,6 +933,14 @@ export function materializeStatePersistence(
     },
   };
   let stateSha256 = semanticStateSha256(state);
+  // WHAT THE LAST ACCEPTED ENTRY ACTUALLY RECORDED, when that is not what this build
+  // would compute. A state accepted through one of the legacy derivations below was
+  // written by a build that hashed it differently, and the delta that follows it names
+  // its base by THAT digest, so a chain of them is unreadable unless the reading carries
+  // both: the modern digest for what this build writes next, and the written one for what
+  // the next entry will name. Null whenever they agree, which is every state this build
+  // wrote itself, so the chain check below is unchanged for them.
+  let writtenSha256: string | null = null;
   let stateStart = -1;
   let checkpointIndex = -1;
   let v2Seen = false;
@@ -845,11 +993,21 @@ export function materializeStatePersistence(
     if (wire.kind === "checkpoint") {
       state = stateFromFoldRefs(wire, wire.foldRefs, records);
     } else {
-      if (wireVersion === 0 || wire.baseRevision !== state.revision || wire.baseStateSha256 !== stateSha256 ||
+      if (wireVersion === 0 || wire.baseRevision !== state.revision ||
+          (wire.baseStateSha256 !== stateSha256 && wire.baseStateSha256 !== writtenSha256) ||
           wire.revision <= wire.baseRevision) {
         throw new Error("Broken active-context delta chain");
       }
-      const refs = state.folds.map(foldRecordRef);
+      // THE RECORD MAP ALREADY HOLDS THIS DIGEST (2026-08-28). `foldRecordRef` canonicalizes
+      // and hashes a whole fold, and this ran once per delta entry over every standing fold:
+      // 48,715 calls in ONE load of a real sealed session, 2.6 to 3.7s of a 24 to 33s load.
+      // `records` is built by the same replay and carries the same digest verbatim. The
+      // fallback is unreachable, because the pre-scan raises on a delta before a checkpoint;
+      // it is kept so the change is exactly behaviour-preserving rather than nearly so.
+      const refs = state.folds.map((fold) => {
+        const record = records.get(fold.id);
+        return record ? { id: fold.id, sha256: record.recordSha256 } : foldRecordRef(fold);
+      });
       const byId = new Map(refs.map((ref) => [ref.id, ref]));
       for (const id of wire.removeFoldIds) {
         if (!byId.delete(id)) throw new Error(`Unknown active-context delta removal ${id}`);
@@ -905,24 +1063,43 @@ export function materializeStatePersistence(
           return mark;
         });
       }
+      // The clips replay by the same discriminator rule as the briefs and the marks: the
+      // presence of the CHANGE is what says a wire carries one. A delta written before
+      // 2026-08-24 states the whole array when it has one and states nothing when it does
+      // not, so "no array" means "no clips" there, exactly as it does for the marks.
+      const clips = wire.clipBase === undefined
+        ? (wire.clips !== undefined ? clone(wire.clips) : [])
+        : [...(state.clips ?? []).slice(0, wire.clipBase), ...clone(wire.addClips ?? [])];
+      if (wire.clipBase !== undefined && wire.clipBase > (state.clips ?? []).length) {
+        throw new Error(`Unknown active-context clip base ${wire.clipBase}`);
+      }
+      if (new Set(clips.map((clip) => clip.callId)).size !== clips.length) {
+        throw new Error("Invalid active-context clips: duplicate call id");
+      }
       state = stateFromFoldRefs(
         {
           ...wire,
           briefs: Object.keys(briefs).length ? briefs : undefined,
           pendingMarks: marks.length ? marks : undefined,
+          clips: clips.length ? clips : undefined,
+          memory: wire.memory?.length ? clone(wire.memory) : undefined,
         },
         [...byId.values()],
         records,
       );
     }
     const calculated = semanticStateSha256(state);
+    const legacyRider = (wire as { rider?: unknown }).rider;
     if (calculated !== wire.stateSha256 &&
         legacyCadenceOmittedStateSha256(state) !== wire.stateSha256 &&
-        legacyReplayOrderStateSha256(state) !== wire.stateSha256) {
+        legacyReplayOrderStateSha256(state) !== wire.stateSha256 &&
+        (legacyRider === undefined ||
+          legacyRiderStateSha256(state, legacyRider) !== wire.stateSha256)) {
       throw new Error("Active-context v2 state digest drift");
     }
     wireVersion = 2;
     stateSha256 = calculated;
+    writtenSha256 = wire.stateSha256 === calculated ? null : wire.stateSha256;
     rememberProjection();
   }
   return { state, wireVersion, records, stateSha256, projectionFingerprints };
@@ -965,8 +1142,9 @@ export function makeStateCheckpoint(state: ActiveContextState): ActiveContextChe
     leases: clone(state.leases),
     ...(state.pendingMarks?.length ? { pendingMarks: clone(state.pendingMarks) } : {}),
     ...(state.briefs && Object.keys(state.briefs).length ? { briefs: clone(state.briefs) } : {}),
+    ...(state.clips?.length ? { clips: clone(state.clips) } : {}),
+    ...(state.memory?.length ? { memory: clone(state.memory) } : {}),
     ...(state.advisory ? { advisory: clone(state.advisory) } : {}),
-    ...(state.rider ? { rider: clone(state.rider) } : {}),
     stateSha256: semanticStateSha256(state),
   }, state.sessionId) as ActiveContextCheckpointV2;
 }
@@ -1013,6 +1191,23 @@ export function makeStateDelta(previous: ActiveContextState, next: ActiveContext
     return !held || sha256Value(held) !== sha256Value(mark);
   });
   const marksTravel = previousMarks.length > 0 || nextMarks.length > 0;
+  // THE CLIPS ARE THE SAME RULE A THIRD TIME (2026-08-24). They shipped whole on every
+  // delta, which was 50.1 percent of all state bytes on sol-20260823-live rep 11, 472,750
+  // of 942,902, for an array that never held more than 34 entries: the same defect the two
+  // comments above were written about, arriving with a feature that did not inherit their
+  // encoding. Clips are APPENDED and never edited, so the change is a count of what the
+  // base already holds plus the ones that are new, and a rollback that shortens the array
+  // states a lower count. The marks' order list would be worse than the bug here: a callId
+  // is about a hundred characters, so re-listing them all on every delta costs more than
+  // the array it replaces.
+  const previousClips = previous.clips ?? [];
+  const nextClips = next.clips ?? [];
+  let clipBase = 0;
+  while (clipBase < previousClips.length && clipBase < nextClips.length &&
+    previousClips[clipBase].callId === nextClips[clipBase].callId &&
+    previousClips[clipBase].entryId === nextClips[clipBase].entryId) clipBase += 1;
+  const addClips = nextClips.slice(clipBase);
+  const clipsTravel = previousClips.length > 0 || nextClips.length > 0;
   // The rest travel whole and stay that way. Measured on the same run, the two that were
   // worth a diff were 20.0 MB of the 21.6 MB ledger; what remained were bounded objects
   // with their own caps rather than collections that grow with the epoch (the largest,
@@ -1038,14 +1233,44 @@ export function makeStateDelta(previous: ActiveContextState, next: ActiveContext
     ...(addPendingMarks.length ? { addPendingMarks: clone(addPendingMarks) } : {}),
     ...(Object.keys(addBriefs).length ? { addBriefs } : {}),
     ...(removeBriefIds.length ? { removeBriefIds } : {}),
+    ...(clipsTravel ? { clipBase: clipBase, ...(addClips.length ? { addClips: clone(addClips) } : {}) } : {}),
+    // The memory travels whole when it exists: bounded at MEMORY_KEYS_MAX entries and
+    // edited in place, so the change encodings above have nothing to save here.
+    ...(next.memory?.length ? { memory: clone(next.memory) } : {}),
     ...(next.advisory ? { advisory: clone(next.advisory) } : {}),
-    ...(next.rider ? { rider: clone(next.rider) } : {}),
     stateSha256: semanticStateSha256(next),
   }, next.sessionId) as ActiveContextDeltaV2;
 }
 
+// THE FOREST IS HASHED ONCE PER STATE OBJECT (2026-08-28). Nine call-site pairs reach this,
+// and the one that scales is the per-mark loop in `commitPendingMarks`: `prepareFold` hashes
+// `state`, and the `commitPreparedFold` on the very next statement re-hashes the SAME object
+// through `preparedFoldError`. So every applied mark paid one avoidable whole-forest hash,
+// and `state` grows by a fold each iteration, making a commit epoch O(marks x folds).
+// Instrumented across the suite: 6,363 calls, 63.8 percent of them repeats on an object
+// already hashed, peaking at 198 in a single context event.
+//
+// It is gate 113's rule, gate 120's and gate 121's, at a fourth address: kept against the
+// state OBJECT rather than its contents, because state is REPLACED on every change rather
+// than mutated, so a replaced one misses and hashes again instead of serving something
+// stale. Every transition in the runtime is a spread; nothing writes `state.folds`,
+// `state.expanded` or a fold in place.
+//
+// The accepted cost, which is the same one gate 121 accepted: a state mutated in place keeps
+// its first digest, and this digest is persisted into `PreparedFold.topologySha256`.
+//
+// NOT memoized beside it: `protectionSha256`, measured at 0.037 to 0.061ms on real states
+// because `state.protected` is empty in every sealed run, so a memo there buys about 3
+// percent and adds a second retained map for nothing.
+const TOPOLOGY_SHA256 = new WeakMap<object, string>();
+
 export function topologySha256(state: Pick<ActiveContextState, "folds" | "expanded">): string {
-  return sha256Value({ folds: state.folds, expanded: [...state.expanded].sort() });
+  const key = state as unknown as object;
+  const memoized = TOPOLOGY_SHA256.get(key);
+  if (memoized !== undefined) return memoized;
+  const digest = sha256Value({ folds: state.folds, expanded: [...state.expanded].sort() });
+  TOPOLOGY_SHA256.set(key, digest);
+  return digest;
 }
 
 export function protectionSha256(state: Pick<ActiveContextState, "protected">): string {
@@ -1056,12 +1281,13 @@ export const ADVISORY_MILESTONES = Object.freeze(
   ["orientation", "notice", "tools", "chapters", "urgent"] as AdvisoryMilestone[],
 );
 
-export const MAX_RIDER_TEXT_BYTES = 4_096;
-
 /**
  * THE RETIRED STATE FIELDS, REFUSED BY NAME.
  *
- * `lastCall` and `notices` were the occupancy thermostat's two announcements. Nothing
+ * `lastCall` and `notices` were the occupancy thermostat's two announcements, and `rider`
+ * was the post-commit invitation to create marks, deleted 2026-08-23 with the curation
+ * redesign: the runtime cuts and the agent edits, so an invitation to create is a carrier
+ * with nothing left to invite. Nothing
  * writes them any more and nothing reads them, so a durable state that still carries one
  * was written by a build that had them, and the exact-record readers would reject it with
  * "Invalid active-context state keys" -- true, and useless to whoever has to act on it.
@@ -1071,6 +1297,15 @@ export const MAX_RIDER_TEXT_BYTES = 4_096;
  * that comes back is not the state that was written. Gate 17 already states the wire's
  * policy in the other direction -- an older exact-record reader rejects newer fields, and
  * a bump is explicit -- and this is that same policy read from the newer side.
+ *
+ * `rider` IS NOT ON THIS LIST, and the distinction is the whole point of the list. The
+ * refusal's own reason is "a state it cannot reproduce", so a field the build CAN
+ * reproduce is out of its scope: the rider was projection carrier text, it changed no
+ * fold, no ref and no brief, and the only thing it ever touched that survives a load is
+ * the state digest. So it is read, spent on the digest, and dropped, which is what
+ * `legacyRiderStateSha256` below is for. Retiring it by name instead made every state the
+ * sol-20260815-hidden campaign sealed unreadable and cost the hidden-mass result its 102
+ * attributed carriage rows, which is a high price for a field that carried no behaviour.
  */
 const RETIRED_STATE_FIELDS: readonly string[] = Object.freeze(["lastCall", "notices", "surfacing"]);
 
@@ -1086,14 +1321,6 @@ export function refuseRetiredStateFields(value: unknown): void {
   );
 }
 
-export function validRiderState(value: unknown): value is NonNullable<ActiveContextState["rider"]> {
-  if (!exactRecord(value, ["epoch", "text"])) return false;
-  const epoch = ownValue(value, "epoch");
-  const text = ownValue(value, "text");
-  return Number.isSafeInteger(epoch) && Number(epoch) >= 0 &&
-    typeof text === "string" && text.length > 0 && text.length <= MAX_RIDER_TEXT_BYTES;
-}
-
 export function validAdvisoryState(value: unknown): value is NonNullable<ActiveContextState["advisory"]> {
   const hasArmed = Boolean(value && typeof value === "object" &&
     Object.prototype.hasOwnProperty.call(value, "armed"));