pi-fold 1.0.3 → 2.0.0

package/extensions/lib/tool-surface.ts

@@ -34,35 +34,22 @@ export function buildActiveContextTool(input: {
   const correctionGuidance = input.allowedActions.includes("rebrief")
     ? " Curation is correctable: rebrief replaces a fold's brief, and reboundary with ids re-cuts a span into exactly one fold, which merges adjacent folds when the span covers several and splits one when the span sits inside it. Reboundary with a single id returns that fold's span to raw."
     : "";
-  // The pin. Protection predates this sentence; the sentence exists because a verb
-  // nobody can discover is a verb nobody uses.
   const pinGuidance = input.allowedActions.includes("protect")
     ? " Protect is the pin: protect with ids holds folds or entries against automatic folding, consolidation and refolding until unprotect releases them, so an expanded span you still need stays expanded. Protect reveals nothing on its own: a folded span stays folded, just held. Pinning moves no context bytes, and fold receipts report how much mass you have pinned."
     : "";
-  // Marking is yours, folding is the runtime's. The epoch guidance says how marks
-  // behave and stops there: there is no agent-callable commit verb to describe.
   const epochGuidance = input.allowedActions.includes("unmark")
     ? " Fold scheduling is epoch mode: fold records pending marks and moves no context bytes, and the runtime applies every pending mark in one rewrite when the fold event fires. Mark SEVERAL spans in one call: marks carries several {ids, brief} pairs, and one call answers with your whole picture, every span now held plus the unmarked remainder and what share of the non-fresh window it is. Between fold events nothing else in your context changes, so that result is where the picture lives. Mark freely as you work; when to fold is the runtime's to decide, and unmark withdraws a mark you no longer want."
     : "";
-  // The recovery norm. Every placeholder already states the exact expand call, and a
-  // full run answered questions about folded material from memory anyway, inventing
-  // plausible values instead of reopening the fold. The syntax was discoverable; the
-  // norm was not, so the norm is stated where the syntax lives.
   const recoveryGuidance = input.allowedActions.includes("expand")
     ? " A fold brief is an index entry, not the source: when a question or task depends on material that is folded, peek or expand that fold and answer from the exact bytes, never from memory of them. Recalling folded detail without reopening it is how specifics get misremembered."
     : "";
-  // The standing facts about how this runtime behaves. They belong HERE, in the tool
-  // surface, because the tool surface sits in the stable prefix: it is cached from the
-  // first request and costs nothing per request thereafter, forever. The same sentences
-  // delivered as in-window carriers cost a cache break on the pass that renders them
-  // and every pass that displaces them. Anything always true is said once, here.
   const standingGuidance = " Folding is automatic, lossless and recoverable: the runtime folds stale spans on its own when the window needs room, nothing is ever discarded, and every folded span keeps its exact source. You are never asked to make room and no fold is ever announced in advance. Work normally and let it happen.";
   return {
     name: input.name,
     label: input.label,
     description: input.fullSurface
-      ? `Page, peek, fold, expand, refold, protect, rebrief, or re-cut exact Pi active-context evidence.${peekGuidance}${correctionGuidance}${pinGuidance}${epochGuidance}${recoveryGuidance}${standingGuidance} Mutations persist immediately and affect the next model call inside the same continuing turn; no turn boundary is required. Supplied fold briefs have a hard 1200-character maximum.`
-      : `Use only the configured active-context actions: ${input.allowedActions.join(", ")}.${peekGuidance}${correctionGuidance}${pinGuidance}${epochGuidance}${recoveryGuidance}${standingGuidance} Call fold only by copying the exact eligibleChapter.action returned by status; if status has no eligibleChapter, continue the task without folding. Supplied fold briefs have a hard 1200-character maximum.`,
+      ? `Page, peek, fold, expand, refold, protect, rebrief, or re-cut exact Pi active-context evidence.${peekGuidance}${correctionGuidance}${pinGuidance}${epochGuidance}${recoveryGuidance}${standingGuidance} Mutations persist immediately and affect the next model call inside the same continuing turn; no turn boundary is required. Supplied fold briefs have a hard ${input.maxBriefChars}-character maximum.`
+      : `Use only the configured active-context actions: ${input.allowedActions.join(", ")}.${peekGuidance}${correctionGuidance}${pinGuidance}${epochGuidance}${recoveryGuidance}${standingGuidance} Call fold only by copying the exact eligibleChapter.action returned by status; if status has no eligibleChapter, continue the task without folding. Supplied fold briefs have a hard ${input.maxBriefChars}-character maximum.`,
     parameters: {
       type: "object",
       additionalProperties: false,
@@ -87,8 +74,8 @@ export function buildActiveContextTool(input: {
                 minLength: 1,
                 maxLength: input.maxBriefChars,
                 description: "Write one for every span you mark. You know why the span mattered and " +
-                  "what you will want back from it; a generator reading the span alone does not. " +
-                  "Leaving it out hands the brief to the summarizer rather than skipping it.",
+                  "what you will want back from it; the deterministic brief that fills the gap " +
+                  "reads the span alone and does not.",
               },
             },
           },
@@ -97,7 +84,7 @@ export function buildActiveContextTool(input: {
           type: "string",
           minLength: 1,
           maxLength: input.maxBriefChars,
-          description: "Factual fold brief; keep it at most 1000 characters to stay below the hard 1200-character limit.",
+          description: `Factual fold brief, at most ${input.maxBriefChars} characters.`,
         },
         offset: { type: "integer", minimum: 0 },
         bytes: {

package/extensions/lib/transcript.ts

@@ -55,12 +55,6 @@ export function completeTurns(messages: unknown[]): CompleteTurn[] {
   return turns;
 }
 
-/**
- * Native compaction may resume the assistant after a summary without replaying
- * the compacted user message. Once a later user message exists, that closed
- * assistant/tool prefix is stale evidence, not part of the fresh user tail.
- * Keep the native summary itself raw and require a terminal assistant boundary.
- */
 export function leadingCompactionContinuation(messages: unknown[]): CompleteTurn | null {
   if (messageRole(messages[0]) !== "compactionSummary") return null;
   let firstUser = -1;
@@ -74,24 +68,11 @@ export function leadingCompactionContinuation(messages: unknown[]): CompleteTurn
   return end > 1 && terminalAssistant(messages[end - 1]) ? { start: 1, end } : null;
 }
 
-/**
- * The exact argument surface each read-only active-context action may carry. A context
- * call outside this surface is not classified read-only, so its batch never folds
- * unmarked.
- */
 export const READ_ONLY_CONTEXT_ACTION_ARGUMENTS: Readonly<Record<string, readonly string[]>> = Object.freeze({
   status: Object.freeze(["action", "detail", "offset", "limit"]),
   peek: Object.freeze(["action", "id"]),
 });
 
-/**
- * May the ladder fold this completed call's batch without an agent mark?
- *
- * Yes for every tool, unless the deployment blacklisted it. The one carve-out is the
- * active-context tool itself: a mutating context call folding its own batch would be a
- * rewrite caused by a tool call, so only its read-only actions inside the exact argument
- * surface above are foldable.
- */
 export function isAutoFoldableToolCall(
   name: string,
   args?: unknown,
@@ -132,7 +113,6 @@ export interface ScannedToolBatches extends ValidatedToolBatch {
   unsafeIndices: Set<number>;
 }
 
-/** Validate each same-assistant tool batch inside one complete turn; results never cross a batch. */
 export function scanTurnToolBatches(
   messages: unknown[],
   turn: CompleteTurn,
@@ -220,7 +200,6 @@ export function scanTurnToolBatches(
   return { calls, unsafeIndices };
 }
 
-/** Validate a complete turn as wholly auto-foldable. Granular callers may still use its safe batches. */
 export function validateTurnToolBatch(
   messages: unknown[],
   turn: CompleteTurn,
@@ -240,12 +219,6 @@ export interface ChapterUnit {
   turnStart: number;
 }
 
-/**
- * Structural chapter segments are deliberately independent of terminal turns.
- * A long-running user turn is one segment even while the coordinator continues
- * issuing tools; a later user message closes the preceding segment without
- * making that boundary either necessary or sufficient for folding.
- */
 export function chapterSegments(messages: unknown[]): CompleteTurn[] {
   const starts: number[] = [];
   for (let index = 0; index < messages.length; index += 1) {
@@ -266,12 +239,6 @@ export function chapterSegments(messages: unknown[]): CompleteTurn[] {
   return segments;
 }
 
-/**
- * Build indivisible structurally closed units. Chapters may summarize completed
- * mutating and failed work, including an old prefix of the currently running
- * turn. Every tool-use assistant must own one complete, unique result batch;
- * any pending, unmatched, or unknown shape protects its entire segment.
- */
 export function structurallyClosedChapterUnits(messages: unknown[], segment: CompleteTurn): ChapterUnit[] {
   const units: ChapterUnit[] = [];
   const ownedCalls = new Set<string>();
@@ -344,26 +311,12 @@ export function unsafeChapterIndices(messages: unknown[]): Set<number> {
   }
   const unsafe = new Set<number>();
   for (let index = 0; index < messages.length; index += 1) if (!eligible.has(index)) unsafe.add(index);
-  // The initiating request of the still-running segment remains raw even after
-  // its older completed work has moved beyond the byte tail. It carries the
-  // live marathon objective; subsequent structurally closed batches may fold.
   const current = segments.length ? segments[segments.length - 1] : undefined;
   if (current?.end === messages.length && !terminalAssistant(messages[current.end - 1]) &&
       messageRole(messages[current.start]) === "user") unsafe.add(current.start);
   return unsafe;
 }
 
-/**
- * The newest end of the window, where nothing folds.
- *
- * Two things decide it, and only two. The STRUCTURAL invariant comes first: an
- * unfinished turn is never foldable at any share, because the excursion in progress is
- * still using the evidence it gathered. Then the freshTail share, walked back turn by
- * turn until the suffix carries its bytes. The old hybrid rule -- three complete turns
- * OR 24,000 bytes, capped at a quarter of a small window -- is gone: it was three
- * numbers in two units answering one question, and at small windows the turn leg and
- * the byte leg disagreed about which was the protection.
- */
 export function freshBoundary(messages: unknown[], turns: CompleteTurn[], freshBytes: number): number {
   if (!messages.length) return 0;
   let unfinishedUser = messages.length;
@@ -411,22 +364,37 @@ export function toolFreshIndices(
 type EntryEvidence = { message: unknown; ref: BranchObject["ref"] };
 
 /**
- * Evidence for ONE session entry, derived once and kept.
+ * ONE CANONICALIZATION PER MESSAGE OBJECT.
  *
- * A session is append-only, and `buildContextEntries` hands back the session manager's own
- * stored entry objects rather than copies, so an entry mapped once cannot change shape
- * underneath us. Keying on the entry OBJECT rather than its id means a replaced entry
- * misses and is recomputed instead of served stale: there is no invalidation rule here to
- * get wrong, and a branch switch is simply a different path over the same stable objects.
+ * Mapping the branch canonicalizes and hashes EVERY event message, then canonicalizes a
+ * branch candidate again on each digest match. That is roughly twice the session's bytes
+ * of stringify-and-sha per derivation, and a derivation runs many times per request: on
+ * sol-20260813-paired rep 2 a single one cost 18.5 seconds against a 16.7 MB session,
+ * where rep 1 cost 3.5 against 7.1 MB. The work was never the mapping, it was rebuilding
+ * the same strings for messages that had not changed since the last pass.
  *
- * What this removes is not loop overhead. It is a `stableStringify` and a `sha256` per
- * message over the WHOLE history on every call, while the window that history projects
- * into stays the same size. That is superlinear in total session bytes, and it spent 135
- * of the 258 minutes of the 2026-08-11 rep, more than the run spent waiting on the model.
- *
- * `branchIndex` is deliberately NOT cached. It is a position in the branch being mapped
- * now, and a different leaf yields a different path across the same entries.
+ * This is gate 121's rule at the layer above it, and it carries gate 121's tradeoff
+ * unchanged and on purpose: the memo is keyed on the message OBJECT, so a replaced object
+ * misses and recomputes rather than serving stale, and a message MUTATED IN PLACE keeps
+ * its first canonical form. The session is append-only, so nothing mutates a message that
+ * has already been mapped; the cost is stated rather than guarded against.
  */
+const MESSAGE_WIRE = new WeakMap<object, { wire: string; digest: string }>();
+
+function messageWire(message: unknown): { wire: string; digest: string } | null {
+  const key = message && typeof message === "object" ? message as object : null;
+  if (key) {
+    const cached = MESSAGE_WIRE.get(key);
+    if (cached) return cached;
+  }
+  let wire: string;
+  try { wire = stableStringify(evidenceValue(message)); }
+  catch { return null; }
+  const canonical = { wire, digest: sha256Text(wire) };
+  if (key) MESSAGE_WIRE.set(key, canonical);
+  return canonical;
+}
+
 const ENTRY_EVIDENCE = new WeakMap<object, {
   sessionId: string;
   projectEntry: (entry: Record<string, unknown>) => unknown[];
@@ -451,7 +419,6 @@ function entryEvidence(
       try {
         items.push({ message, ref: evidenceRef(sessionId, entryId, message) });
       } catch {
-        // Unknown persisted shapes stay unavailable rather than weakening exact refs.
       }
     }
   }
@@ -471,7 +438,6 @@ export function mapActiveContext(input: {
   blacklistAutoFoldTools?: ReadonlySet<string>;
   readOnlyContextActions?: ReadonlySet<string>;
   contextWindow?: number;
-  /** True when `contextWindow` is a declared serving budget rather than a raw window. */
   netBudget?: boolean;
   thresholds?: ActiveContextThresholds;
 }): ActiveContextSnapshot {
@@ -491,19 +457,16 @@ export function mapActiveContext(input: {
   let cursor = 0;
   for (let index = 0; index < input.eventMessages.length; index += 1) {
     const message = input.eventMessages[index];
-    let wire: string | null = null;
-    let digest: string | null = null;
-    try {
-      wire = stableStringify(evidenceValue(message));
-      digest = sha256Text(wire);
-    } catch {
+    const canonical = messageWire(message);
+    if (!canonical) {
       mapped.push({ index, message, ref: null });
       continue;
     }
+    const { wire, digest } = canonical;
     let match = -1;
     for (let branchIndex = cursor; branchIndex < branchObjects.length; branchIndex += 1) {
       const candidate = branchObjects[branchIndex];
-      if (candidate.ref.sha256 === digest && stableStringify(evidenceValue(candidate.message)) === wire) {
+      if (candidate.ref.sha256 === digest && messageWire(candidate.message)?.wire === wire) {
         match = branchIndex;
         break;
       }
@@ -519,12 +482,6 @@ export function mapActiveContext(input: {
     Number.isFinite(input.contextWindow) && input.contextWindow > 0
     ? input.contextWindow
     : null;
-  // One denominator: both zone widths are shares of the serving budget the declared
-  // window yields, so a smaller window narrows the tails in proportion instead of
-  // meeting a fixed byte floor that only a second constant could rescue.
-  // A deployment that declared `providerInputBudget` passes its window in ALREADY NET of
-  // the reservation it holds back, so the zone widths divide by it as given. Only the
-  // descriptor fallback estimates a reservation out of the raw window.
   const thresholds = input.thresholds ?? DEFAULT_THRESHOLDS;
   const budgetTokens = input.netBudget === true
     ? (reportedContextWindow ?? DEFAULT_CONTEXT_WINDOW)
@@ -532,30 +489,8 @@ export function mapActiveContext(input: {
   const freshBytes = zoneBytes(thresholds.freshTail, budgetTokens);
   const turns = completeTurns(input.eventMessages);
   const boundary = freshBoundary(input.eventMessages, turns, freshBytes);
-  // THERE IS NO POSITIONAL REACH HERE ANY MORE.
-  //
-  // This function used to compute a second boundary, a byte prefix of the window called
-  // the stale zone, and the selectors would take nothing above it. Two reps died of it.
-  // Rep 2 clamped it to the last CLOSED turn, so a marathon session that never closed
-  // one had a zero-width zone: the last call announced 19 unmarked spans worth 274,173
-  // tokens while the selector could propose nothing, no commit ever fired, and the
-  // window was rejected twice at 375,830 estimated tokens. Rep 3 unclamped it and walked
-  // raw bytes, so a folded prefix was charged for evidence it had already replaced: 17
-  // folded results cost 1,002,801 raw bytes of a 1,072,081-byte allowance, the reach
-  // froze at index 36 of 133, and the run died against the fence at 0.972 occupancy with
-  // 25 takeable batches sitting above the line.
-  //
-  // Shane's ruling (2026-08-10): stale is a CLASS, not a position. A span is
-  // automatically foldable because of what it IS -- a completed tool batch the deployment
-  // did not blacklist, or older material a chapter or consolidation can compose -- and
-  // never because of where it sits. What this function still produces is the protection
-  // that is genuinely positional: the fresh byte tail, set-shaped, in `protectedIndices`
-  // and `toolProtectedIndices`. The rest of the law is membership plus the agent's pins
-  // plus the guard-with-waiver adjudicated once at commit.
   const protectedIndices = unsafeChapterIndices(input.eventMessages);
   const toolProtectedIndices = toolFreshIndices(input.eventMessages, turns, freshBytes);
-  // Chapter protection is set-shaped: preserve the newest complete turns and
-  // raw byte tail, while allowing an older closed prefix of the current turn.
   for (const index of toolProtectedIndices) protectedIndices.add(index);
   for (let mappedIndex = 0; mappedIndex < mapped.length; mappedIndex += 1) {
     const item = mapped[mappedIndex];
@@ -586,16 +521,6 @@ export function mapActiveContext(input: {
   return snapshot;
 }
 
-/**
- * The evidence boundary of the CURRENT turn: the position of the last terminal
- * assistant message. Everything after it was gathered by the excursion still in
- * progress, which is exactly the evidence a commit must not fold.
- *
- * Measured 2026-08-06 (rep 8): nineteen folds landed between the last read result and
- * the agent's next reply, rewriting the projection from 938k to 487k chars, so the
- * agent answered from a window where its own just-gathered evidence had become
- * placeholders. Freshness in bytes did not catch it; the boundary is a TURN.
- */
 export function currentTurnBoundary(snapshot: Pick<ActiveContextSnapshot, "messages">): number {
   let boundary = -1;
   for (let index = 0; index < snapshot.messages.length; index += 1) {
@@ -604,7 +529,6 @@ export function currentTurnBoundary(snapshot: Pick<ActiveContextSnapshot, "messa
   return boundary;
 }
 
-/** Every tool-result evidence key produced since that boundary. */
 export function currentTurnRefKeys(snapshot: ActiveContextSnapshot): Set<string> {
   const boundary = currentTurnBoundary(snapshot);
   const keys = new Set<string>();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fold",
-  "version": "1.0.3",
+  "version": "2.0.0",
   "description": "Lossless, agent-governed context folding for the Pi coding agent: only the oldest context changes; the fresh window stays untouched.",
   "keywords": [
     "pi-package",