pi-fold 2.0.0 → 3.0.0

package/extensions/lib/policy.ts

@@ -5,8 +5,8 @@ export const DEFAULT_ACTIVE_CONTEXT_ENTRY_TYPE_PREFIX = "pi-fold-active-context"
 export const DEFAULT_ACTIVE_CONTEXT_TOOL_LABEL = "pi-fold Active Context";
 export const DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN = "pi-fold";
 export const DEFAULT_ACTIVE_CONTEXT_COMMAND_NAMES = Object.freeze({
-  status: "pi-fold-context",
-  fold: "fold-context",
+  status: "fold-status",
+  fold: "fold",
 });
 
 export function entryTypeNamespace(entryTypePrefix: string): string {
@@ -33,10 +33,64 @@ const DEFAULT_ENTRY_NAMESPACE = entryTypeNamespace(DEFAULT_ACTIVE_CONTEXT_ENTRY_
 export const ACTIVE_CONTEXT_STATE_ENTRY = `${DEFAULT_ACTIVE_CONTEXT_ENTRY_TYPE_PREFIX}-state`;
 export const ACTIVE_CONTEXT_FOLD_RECORD_ENTRY = `${DEFAULT_ACTIVE_CONTEXT_ENTRY_TYPE_PREFIX}-fold-record`;
 export const PROVIDER_CONTEXT_MEASUREMENT_ENTRY = `${DEFAULT_ENTRY_NAMESPACE}-provider-context-measurement`;
+/**
+ * How many unbriefed pending folds stand before the runtime says so.
+ *
+ * A CONSTANT, not a threshold the deployment can turn (Shane's KISS rule): it is a
+ * batching size, and the only thing a knob here would buy is a deployment that never
+ * speaks. Three is the smallest batch that reads as a batch rather than as a running
+ * commentary on every cut.
+ */
+export const UNBRIEFED_FOLDS_BEFORE_NOTICE = 3;
+
+/**
+ * How many spans the frontier cuts on one projection pass.
+ *
+ * A CONSTANT, and a cost bound rather than a policy. Each cut rescans the window for the
+ * next stalest span, so an unbounded loop is quadratic in the number of spans a window
+ * holds: on a 300-turn fixture it took a gate from 2.5 seconds to 152. A frontier does not
+ * need to catch up in one pass, because a pass costs nothing to repeat and the material it
+ * has not reached yet is still raw and still in front of the agent, which is where the
+ * design wants it. Eight is comfortably ahead of any real arrival rate.
+ */
+export const MAX_FRONTIER_CUTS_PER_PASS = 8;
+
 export const ACTIVE_CONTEXT_TOOL_ACTIONS = Object.freeze([
-  "status", "peek", "fold", "expand", "refold", "protect", "unprotect",
-  "rebrief", "reboundary", "unmark",
+  "status", "peek", "brief", "expand", "refold", "pin", "unpin",
+  "reboundary", "unmark",
 ] as const);
+/**
+ * FOLD IS DELETED AS AN AGENT VERB (Shane, 2026-08-23), and `brief` is what replaced it.
+ *
+ * The agent used to choose spans from nothing. Measured against real compaction
+ * boundaries on 2026-08-23, that produced a projection byte-identical to the same arm
+ * with no agent at all: six marks, 9,450 characters of briefs, same visible count, same
+ * fold count, same aborts. It marks what the ladder would have taken anyway, because at
+ * the moment it is asked the only information available is staleness and the runtime
+ * already has that.
+ *
+ * So the runtime cuts at the frontier and the agent annotates what it cut, while the
+ * material is still in front of it. `brief` attaches or replaces the brief on a PENDING
+ * fold and refuses on a standing one, which is the rebrief deletion above read from the
+ * other side: a pending mark is not in the window, so writing its brief moves no bytes
+ * and costs no cache, and a standing fold's placeholder is in the window, so writing that
+ * one costs the whole prefix from there on. The name `fold` stays spent.
+ */
+/**
+ * REBRIEF IS DELETED (Shane, 2026-08-21). Every rebrief rewrites the projection at its
+ * fold's placeholder, which breaks the prefix cache from that point on: sol-20260820
+ * rep 7's first rebrief hit a front-of-projection fold, identical_share collapsed to
+ * 0.0007, and nine ~185K-token requests ran cacheRead 0 for $8.36 in one burst. The
+ * end block read 10 of 10 in every pifold rep with or without rebriefs, because
+ * lossless peek already carries recall, so the action was paying a full cache break
+ * for something the runtime did not need. The name stays spent.
+ */
+export const RETIRED_TOOL_ACTIONS: Readonly<Record<string, string>> = Object.freeze({
+  rebrief: "rebrief is deleted: rewriting a standing fold's brief rewrites the projection " +
+    "at that fold's placeholder and breaks the prefix cache from there on, for recall that " +
+    "peek already carries losslessly. Write the brief you want when you mark the span, or " +
+    "use reboundary to re-cut it.",
+});
 export type ActiveContextToolAction = typeof ACTIVE_CONTEXT_TOOL_ACTIONS[number];
 export const USER_RESCUE_MAX_SOURCE_CHARS = 512_000;
 export const DEFAULT_CONTEXT_WINDOW = 272_000;
@@ -45,38 +99,86 @@ export const MAX_EXPAND_LEASES = 64;
 
 export const COMMIT_RECLAIM_FLOOR_SHARE = 0.02;
 
+/**
+ * How far below the commit trigger the agent is told a commit is coming (Shane,
+ * 2026-08-22: "around 10% from the commit threshold"). A share of the serving budget
+ * rather than a token count, because a token count means a different fraction of every
+ * deployment's window. The advisory takes the wider of this and one worst recent inflow
+ * step, so a single large result cannot step over the whole band unasked.
+ */
 export const MAX_PINNED_SHARE = 0.25;
 
 export interface ActiveContextThresholds {
   maxTarget: number;
   minTarget: number;
-  freshTail: number;
   consolidateAfter: number;
+  minFoldChars: number;
 }
 
+/**
+ * The floor a fold has to clear to be worth making, in CHARACTERS (Shane, 2026-08-21).
+ *
+ * Characters rather than tokens because characters are provider-agnostic: a token count
+ * means a different amount of text on every wire, and this number exists so a person can
+ * reason about it. It replaces two constants nobody could tell apart, minToolChars at
+ * 2,000 and minChapterChars at 4,000, and it is not specific to tool results or to
+ * chapters: everything in the window costs tokens, so everything counts toward the floor.
+ *
+ * It is a floor, not a cut. The automatic span accumulates whole messages and stops at
+ * the first one that carries it OVER the floor, so a fold is always at least this big
+ * and never cuts a message in half to hit the number exactly. The same floor is what a
+ * gap between two folds has to clear to survive: anything smaller is absorbed by the
+ * fold beside it rather than left as a raw sliver, because a sliver costs its bytes and
+ * buys nothing.
+ *
+ * 8,000 was chosen against the sealed corpus. Rep 1 of sol-20260814-traps folded 89
+ * spans at a median of 57,808 source chars, but nine of them came in under 8,000 and
+ * TWO were net negative, 2,726 chars of source replaced by 5,341 of placeholder (196
+ * percent) and 6,384 replaced by 10,531 (165 percent). A fold that grows the window is
+ * not a fold. The floor sits above every observed inversion with room to spare.
+ */
+export const MINIMUM_FOLD_CHARS_FLOOR = 2_000;
+
 export const DEFAULT_THRESHOLDS: Readonly<ActiveContextThresholds> = Object.freeze({
   maxTarget: 0.80,
-  // 0.20, down from 0.35 (Shane 2026-08-14). The cut depth is what sets the epoch
-  // cadence: every commit rewrites the prefix from the earliest folded byte, so the
-  // cost of an epoch is nearly flat in how deep it cuts, while the relief it buys is
-  // the whole distance to the trigger. sol-20260814-traps rep 1 ran six commits, each
-  // freeing to 0.35 and refilling in two to three stages; at 0.20 the same run shape
-  // owes roughly a quarter fewer epochs, which is a quarter fewer full-prefix
-  // rewrites, the dominant self-inflicted cache break. The floor is a target the
-  // class law outranks, not a guarantee: a session pinned to the 0.25 ceiling
-  // beside the 0.02 fresh tail legally holds 0.27 and lands above this number,
-  // and the epoch receipt reports targetBudgetShare beside actualFreedBudgetShare
-  // so the shortfall is a readable fact per epoch rather than a silent miss. The
-  // validation laws below bind exactly as before.
-  minTarget: 0.20,
-  freshTail: 0.02,
+  // 0.40, up from 0.20 (Shane 2026-08-23: "we change the thresholds to what hits that
+  // 100k/250k or so"). This is the only threshold that moved, because the corpus says
+  // the top of the band was already where he wants it and only the floor was wrong.
+  //
+  // Read against the 19 mature sealed pifold runs that share a 251,520-token budget,
+  // where the trigger sat at 0.80 of it, 201,216 tokens. Peak occupancy per run came in
+  // at a median 237,399, a 0.944 share, p90 247,551, max 257,117: a session runs roughly
+  // 36,000 tokens PAST its own trigger before the commit it fired takes effect, because
+  // the trigger fires at a measurement and inflow continues while the epoch is computed.
+  // So 0.80 already delivers a 250k top, and raising it toward 250k directly would put
+  // the median peak over the budget and into the fence.
+  //
+  // The floor was the miss. Across 206 commit landings the session came to rest at a
+  // median 79,034 tokens, and 153 of the 206 landed below 100,000. Landings sit ABOVE
+  // the aim rather than at it, since the class law and the available material both
+  // outrank it, so moving the aim to 0.40 sets a floor near where it lands rather than
+  // far under it: 102,246 tokens against a default 272,000-token descriptor, 100,608
+  // against the harness budget.
+  //
+  // 0.40 also makes the aim reachable for the first time. MAX_PINNED_SHARE is 0.25, so a
+  // fully pinned session legally holds more than a 0.20 aim asks for and the target was
+  // a number the class law outranked by construction. The epoch receipt still reports
+  // targetBudgetShare beside actualFreedBudgetShare, so any remaining shortfall stays a
+  // readable fact per epoch rather than a silent miss.
+  //
+  // The cost is paid in cadence and it is the 2026-08-14 argument running backwards: a
+  // shallower cut buys less runway for nearly the same commit, so the refill distance
+  // goes from the observed 0.314 -> 0.80 to 0.40 -> 0.80 and the same session shape owes
+  // about a fifth more epochs, which is a fifth more full-prefix rewrites. Shane bought
+  // that deliberately: 100k of raw context held across the whole cycle is what he is
+  // paying for. The validation laws below bind exactly as before.
+  minTarget: 0.40,
   consolidateAfter: 10,
+  minFoldChars: 8_000,
 });
 
 export const MINIMUM_SUPPORTED_BUDGET_TOKENS = 10_000;
 
-export const MINIMUM_FRESH_TAIL_TOKENS = 500;
-
 export class ThresholdPolicyError extends Error {
   readonly invariant: string;
   constructor(invariant: string, message: string) {
@@ -99,7 +201,7 @@ export function resolveThresholds(value: unknown): ActiveContextThresholds {
     throw new ThresholdPolicyError("shape", "thresholds must be an object with all four fields");
   }
   const supplied = value as Record<string, unknown>;
-  const fields = ["maxTarget", "minTarget", "freshTail", "consolidateAfter"] as const;
+  const fields = ["maxTarget", "minTarget", "consolidateAfter", "minFoldChars"] as const;
   for (const key of Object.keys(supplied)) {
     if (!(fields as readonly string[]).includes(key)) {
       throw new ThresholdPolicyError("shape", `thresholds has no ${key} field`);
@@ -112,46 +214,31 @@ export function resolveThresholds(value: unknown): ActiveContextThresholds {
   }
   const maxTarget = thresholdProportion(supplied.maxTarget, "maxTarget");
   const minTarget = thresholdProportion(supplied.minTarget, "minTarget");
-  const freshTail = thresholdProportion(supplied.freshTail, "freshTail");
   const consolidateAfter = supplied.consolidateAfter;
   if (typeof consolidateAfter !== "number" || !Number.isInteger(consolidateAfter) || consolidateAfter < 1) {
     throw new ThresholdPolicyError("consolidateAfter", "thresholds.consolidateAfter must be a positive integer count");
   }
+  const minFoldChars = supplied.minFoldChars;
+  if (typeof minFoldChars !== "number" || !Number.isInteger(minFoldChars) ||
+      minFoldChars < MINIMUM_FOLD_CHARS_FLOOR) {
+    throw new ThresholdPolicyError("minFoldChars",
+      "thresholds.minFoldChars must be an integer character count of at least " +
+      `${MINIMUM_FOLD_CHARS_FLOOR}; below that a fold can cost more placeholder than the ` +
+      "source it replaces");
+  }
   if (!(minTarget < maxTarget)) {
     throw new ThresholdPolicyError("minTarget<maxTarget",
       "thresholds.minTarget must sit below thresholds.maxTarget, or a commit has no depth to reach");
   }
-  if (!(freshTail < maxTarget)) {
-    throw new ThresholdPolicyError("freshTail<maxTarget",
-      "thresholds.freshTail must sit below thresholds.maxTarget, or the trigger fires on protected mass alone");
-  }
-  if (!(maxTarget - minTarget >= freshTail)) {
-    throw new ThresholdPolicyError("gap>=freshTail",
-      "the hysteresis gap (maxTarget - minTarget) must be at least thresholds.freshTail, " +
-      "or refilling the protected tail alone re-fires the trigger");
-  }
-  const pinned = Math.ceil(MAX_PINNED_SHARE * MINIMUM_SUPPORTED_BUDGET_TOKENS);
-  const fresh = Math.ceil(freshTail * MINIMUM_SUPPORTED_BUDGET_TOKENS);
-  if (!(pinned + fresh < Math.floor(maxTarget * MINIMUM_SUPPORTED_BUDGET_TOKENS))) {
-    throw new ThresholdPolicyError("pinnedPlusFreshTail<maxTarget",
-      `the pin ceiling (${MAX_PINNED_SHARE}) plus thresholds.freshTail must stay below ` +
-      `thresholds.maxTarget at the ${MINIMUM_SUPPORTED_BUDGET_TOKENS}-token minimum supported budget`);
-  }
-  return { maxTarget, minTarget, freshTail, consolidateAfter };
+  return { maxTarget, minTarget, consolidateAfter, minFoldChars };
 }
 
-export function assertThresholdsServable(thresholds: ActiveContextThresholds, budgetTokens: number): void {
+export function assertThresholdsServable(_thresholds: ActiveContextThresholds, budgetTokens: number): void {
   if (!Number.isFinite(budgetTokens) || budgetTokens < MINIMUM_SUPPORTED_BUDGET_TOKENS) {
     throw new ThresholdPolicyError("minimumBudget",
       `a ${Math.floor(budgetTokens)}-token serving budget is below the ` +
       `${MINIMUM_SUPPORTED_BUDGET_TOKENS}-token minimum this package supports`);
   }
-  const freshTokens = Math.floor(thresholds.freshTail * budgetTokens);
-  if (freshTokens < MINIMUM_FRESH_TAIL_TOKENS) {
-    throw new ThresholdPolicyError("freshTailTokens",
-      `thresholds.freshTail is ${freshTokens} tokens of a ${Math.floor(budgetTokens)}-token serving budget, ` +
-      `below the ${MINIMUM_FRESH_TAIL_TOKENS}-token minimum one foldable unit needs`);
-  }
 }
 
 export function zoneBytes(share: number, budgetTokens: number): number {
@@ -172,54 +259,51 @@ export const PEEK_MIN_SLICE_BYTES = 1_024;
 
 export const STATUS_DIET_INDEX_ROWS = 5;
 
-export interface ActiveContextGuidance {
-  actionResponses: boolean;
-}
-
-export const DEFAULT_GUIDANCE: ActiveContextGuidance = Object.freeze({
-  actionResponses: true,
-});
-
-const GUIDANCE_KEYS: readonly (keyof ActiveContextGuidance)[] = Object.freeze([
-  "actionResponses",
-]);
-
-export function resolveGuidance(value: unknown): ActiveContextGuidance {
-  if (value === undefined) return DEFAULT_GUIDANCE;
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error("guidance must be an object of { actionResponses } booleans");
-  }
-  for (const key of Object.keys(value)) {
-    if (!GUIDANCE_KEYS.includes(key as keyof ActiveContextGuidance)) {
-      throw new Error(`guidance has no ${key} setting: the only keys are ` +
-        `${GUIDANCE_KEYS.join(", ")}, and they are booleans`);
-    }
-  }
-  const resolved = { ...DEFAULT_GUIDANCE } as ActiveContextGuidance;
-  for (const key of GUIDANCE_KEYS) {
-    if (!Object.hasOwn(value, key)) continue;
-    const setting = (value as Record<string, unknown>)[key];
-    if (typeof setting !== "boolean") throw new Error(`guidance.${key} must be a boolean`);
-    resolved[key] = setting;
-  }
-  return Object.freeze(resolved);
-}
-
 export const MAX_CONTEXT_RECEIPTS = 3;
 export const CONTEXT_RECEIPT_BLOCK_BYTES = 900;
 
-export const CONTEXT_MARK_RESPONSE_BYTES = 900;
+/**
+ * The post-fold notice's bound, and its own rather than the receipt block's.
+ *
+ * It is larger because it carries a variable-length list the receipt does not: three
+ * fixed sentences of instruction plus one entry per unbriefed fold, and the pending set
+ * grows past MAX_FRONTIER_CUTS_PER_PASS whenever the frontier stages faster than the
+ * agent answers. 1,200 seats the instruction and roughly eight folds; past that the list
+ * gives way and states how many it could not name.
+ */
+export const FOLD_NOTICE_BYTES = 1_200;
 export const CONTEXT_STATUS_RESPONSE_BYTES = 24_000;
 export const MAX_UNMARKED_CANDIDATES = 3;
 
 export const MAX_FOLD_SPAN_CHARS = 16_000;
-export const MAX_WEDGE_ABSORB_TOKENS = 256;
 export const PEEK_DEFAULT_MAX_BYTES = 16_000;
 export const PEEK_HEAD_SHARE = 0.6;
 
+/**
+ * A PEEK IS EPHEMERAL UNLESS THE AGENT SAYS OTHERWISE (Shane, 2026-08-22).
+ *
+ * The default follows the measured choice rather than the cautious one. On sealed run
+ * rep 7, six of seven peeks asked for ephemeral at first organic exposure, and the one
+ * durable read was the stage-64 probe, exactly where the bytes were wanted standing.
+ * The economics agree: a peek is a pure append and costs the cache nothing, while the
+ * withdrawal is a tail operation at the withdrawn result's own index, so the cheap read
+ * should be the one you get without asking.
+ *
+ * Only an explicit false is durable. A missing value, and anything the validator has
+ * already rejected, reads as ephemeral, so a host or model that never learned the
+ * argument still gets the cheap behaviour and can still recover the bytes by peeking
+ * again, which is lossless.
+ */
+export function peekIsEphemeral(params: Record<string, unknown> | undefined | null): boolean {
+  return params?.ephemeral !== false;
+}
+
 export const PEEK_READ_ONLY_CONTEXT_ACTIONS: ReadonlySet<string> = new Set(["status", "peek"]);
 
-export type MarkOrigin = "agent" | "ladder";
+/** "user" is a mark laid down by the human through /fold-editor; it stages and
+ *  commits through the same validated path as an agent mark and counts toward the
+ *  commit's coverage the same way. */
+export type MarkOrigin = "agent" | "ladder" | "user";
 
 export interface PendingFoldMark {
   mark: "fold";
@@ -245,12 +329,11 @@ export const ACTIVE_CONTEXT_POLICY = Object.freeze({
   refoldRatio: 0.85,
   prepareRatio: 0.90,
   responseReserve: 16_384,
-  minToolChars: 2_000,
-  minChapterChars: 4_000,
-  maxChapterChars: 128_000,
-  maxChapterTurns: 4,
+  // The most exact source bytes ONE read may put back in the window, whichever verb
+  // asks: an expand collapses its biggest children until the render fits, and a peek
+  // clamps its `bytes` to it. Was two numbers until 2026-08-22, when the peek ceiling
+  // was `maxChapterChars` 128,000 and that constant also claimed to cap a chapter.
   maxSourceChars: 200_000,
-  maxFoldSourceRefs: 256,
   maxBriefChars: 2_000,
   orientationMessages: 2,
   maxOrientationChars: 12_000,
@@ -414,7 +497,6 @@ export interface ActiveContextSnapshot {
   thresholds: ActiveContextThresholds;
   budgetTokens: number;
   protectedIndices: Set<number>;
-  toolProtectedIndices: Set<number>;
   policy: typeof ACTIVE_CONTEXT_POLICY;
   toolName: string;
   brandNoun: string;