pi-fold 1.0.2 → 1.0.3

package/extensions/lib/policy.ts

@@ -1,16 +1,25 @@
 import type { EvidenceRef } from "../json.ts";
 
-export const DEFAULT_ACTIVE_CONTEXT_TOOL_NAME = "active_context";
+/**
+ * THE deployment identity. One package, one brand, no constructor options.
+ *
+ * These were five public knobs through 1.0.2, on the theory that the runtime was a
+ * generic framework a host would brand. It is not: it is a branded package with one
+ * deployment, and the knobs bought nothing but a namespace a consumer could strand its
+ * own durable state under. They are hardwired here and REFUSED by name at the package
+ * entry. An internal seam survives on `registerActiveContext`, because the neutrality
+ * gate has to register a synthetic brand to prove none of it leaks into these defaults,
+ * and the experiment harness registers this same identity explicitly so the sealed runs
+ * keep their entry types.
+ */
+export const DEFAULT_ACTIVE_CONTEXT_TOOL_NAME = "pi_fold_context";
 export const DEFAULT_ACTIVE_CONTEXT_ENTRY_TYPE_PREFIX = "pi-fold-active-context";
-export const DEFAULT_ACTIVE_CONTEXT_TOOL_LABEL = "Active Context";
-export const DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN = "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: "context",
+  status: "pi-fold-context",
   fold: "fold-context",
 });
-export const GUIDANCE_PROFILES = Object.freeze(["pressure", "curation", "minimal"] as const);
-export type GuidanceProfile = typeof GUIDANCE_PROFILES[number];
-export const DEFAULT_GUIDANCE_PROFILE: GuidanceProfile = "pressure";
 
 export function entryTypeNamespace(entryTypePrefix: string): string {
   const suffix = "-active-context";
@@ -39,16 +48,13 @@ export const NATIVE_COMPACTION_RECEIPT_ENTRY = `${DEFAULT_ENTRY_NAMESPACE}-nativ
 export const NATIVE_COMPACTION_DECISION_ENTRY = `${DEFAULT_ENTRY_NAMESPACE}-native-compaction-decision`;
 export const PROVIDER_CONTEXT_MEASUREMENT_ENTRY = `${DEFAULT_ENTRY_NAMESPACE}-provider-context-measurement`;
 export const ACTIVE_CONTEXT_STATUS_KEY = DEFAULT_ACTIVE_CONTEXT_ENTRY_TYPE_PREFIX;
-export const ACTIVE_CONTEXT_TOOL_ACTIONS = Object.freeze([
-  "status", "peek", "fold", "expand", "refold", "protect", "unprotect",
-  // The correction verbs. Curation the agent cannot fix afterwards is curation it
-  // will not risk making, so re-briefing a fold and dissolving a mis-cut boundary
-  // are part of the ordinary surface, not an epoch-only extra.
-  "rebrief", "reboundary",
-] as const);
 /**
- * The epoch surface: the immediate actions plus `unmark`. A mark is a standing decision
- * rather than a one-shot attempt, so withdrawing one needs a verb of its own.
+ * The action surface, whole. There was a second, narrower list while immediate
+ * scheduling existed; epoch is the only scheduler now, so marks always exist and
+ * `unmark` is an ordinary verb: a mark is a standing decision rather than a one-shot
+ * attempt, so withdrawing one needs a verb of its own. The correction verbs are here
+ * for the same reason: curation the agent cannot fix afterwards is curation it will
+ * not risk making.
  *
  * There is deliberately NO agent-callable commit verb. Marking is the agent's job and
  * folding is the runtime's, and a verb the runtime is entitled to overrule is surface
@@ -56,65 +62,74 @@ export const ACTIVE_CONTEXT_TOOL_ACTIONS = Object.freeze([
  * runtime correctly held it both times. The internal commit paths -- the epoch commit,
  * the gated commit, the fence and the recovery lane -- are unchanged and unexposed.
  */
-export const EPOCH_ACTIVE_CONTEXT_TOOL_ACTIONS = Object.freeze([
-  ...ACTIVE_CONTEXT_TOOL_ACTIONS, "unmark",
+export const ACTIVE_CONTEXT_TOOL_ACTIONS = Object.freeze([
+  "status", "peek", "fold", "expand", "refold", "protect", "unprotect",
+  "rebrief", "reboundary", "unmark",
 ] as const);
-export type ActiveContextToolAction = typeof EPOCH_ACTIVE_CONTEXT_TOOL_ACTIONS[number];
+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;
-export const TOOL_FOLD_CADENCE_MIN_TOKENS = 12_000;
-export const TOOL_FOLD_CADENCE_WINDOW_FRACTION = 0.06;
 export const EXPAND_LEASE_GENERATIONS = 8;
 export const MAX_EXPAND_LEASES = 64;
-export const CONSOLIDATION_WIDTH_THRESHOLD = 10;
 export const MAX_ADVISORY_DELIVERIES_PER_MILESTONE = 16;
 
-// Ephemeral surfacing structure. These stay INTERNAL constants rather than public
+// Surfacing SELECTOR structure. These stay INTERNAL constants rather than public
 // options: they are the knobs the surfacing experiment is meant to settle, and an
-// option surface fixed before the accept/reject data exists would freeze a guess.
-export const DEFAULT_SURFACING_ENABLED = true;
-export const SURFACING_TOP_K = 3;
-export const SURFACING_MIN_SCORE = 0.30;
-export const SURFACING_CHAR_BUDGET = 1_000;
-export const SURFACING_COOLDOWN_ORDINALS = 8;
+// option surface fixed before the acted/used/ignored data exists would freeze a guess.
+// The per-request ephemeral carrier that once rendered the slate is deleted, and its
+// enable flag with it; the slate rides the commit-boundary carriers and status only.
+
+/** BM25's canonical parameters, and memex's fold lane runs on exactly these. */
+export const SURFACING_BM25_K1 = 1.5;
+export const SURFACING_BM25_B = 0.75;
+/**
+ * The divergence trigger, as three numbers on one 0..1 scale.
+ *
+ * The scale is the share of the query's own saturation ceiling a document reaches, so
+ * 1.0 would be every query term saturated in one document and a strong real match lands
+ * in the third of the range these numbers sit in. CONTENT_HIT is the cry-wolf guard:
+ * below it the fold does not match the task at all and nothing else matters. BRIEF_HIT
+ * is the visibility line: at or above it the placeholder already says what the fold
+ * holds, so the agent can see it and a suggestion repeats the window back to itself.
+ * The MARGIN keeps the pair from meeting in the middle, where both readings are weak
+ * and neither says anything.
+ */
+export const SURFACING_CONTENT_HIT = 0.25;
+export const SURFACING_BRIEF_HIT = 0.15;
+export const SURFACING_DIVERGENCE_MARGIN = 0.10;
+/** Precision budget, not a rate limit: at most one suggestion per delivery point. */
+export const SURFACING_SLATE_SIZE = 1;
+/** One clock. It is the outcome window AND the cooldown: no re-offer before an answer. */
 export const SURFACING_OUTCOME_WINDOW_ORDINALS = 12;
-export const SURFACING_RECENT_TASK_SPANS = 6;
-export const SURFACING_MAX_TASK_CHARS = 12_000;
-export const SURFACING_MAX_LOG_RECORDS = 128;
-export const SURFACING_LEXICAL_WEIGHT = 0.80;
-export const SURFACING_RECENCY_WEIGHT = 0.14;
-export const SURFACING_DEPTH_WEIGHT = 0.06;
-export const SURFACING_MAX_DEPTH = 4;
-export const SURFACING_MAX_TEXT_CHARS = 220;
-export const SURFACING_SOURCE_ID = "fold-brief";
+/** Offered this many times and never taken, and the fold leaves the candidate set. */
+export const SURFACING_IGNORE_LIMIT = 2;
+/** Distinct content-only terms downstream that grade an acted suggestion as used. */
+export const SURFACING_PROVENANCE_TERMS = 3;
+export const SURFACING_INTENT_CHARS = 1_200;
+export const SURFACING_INTENT_ARGUMENT_CHARS = 120;
+export const SURFACING_INTENT_RECENCY_SHARE = 0.5;
+export const SURFACING_INTENT_ARGUMENT_KEYS: readonly string[] = Object.freeze([
+  "path", "file_path", "query", "pattern", "command", "brief", "id",
+]);
+export const SURFACING_MAX_CONTENT_CHARS = 20_000;
+export const SURFACING_MAX_LEDGER_RECORDS = 256;
+export const SURFACING_HOOK_CHARS = 160;
 
 // Conservative LOWER bound on UTF-8 bytes per provider token, used only to cap
 // the protected byte tail as a share of a small window; never to estimate usage.
 export const BYTES_PER_TOKEN_FLOOR = 2;
 
-// Two-phase fold scheduling. A provider prefix cache is positional: any mid-window
-// edit invalidates every byte after it, so the cost of folding is dominated by how
-// OFTEN the projection changes, not by how much it saves. In "epoch" mode a fold
-// decision becomes a free MARK and a later COMMIT applies every pending mark in one
-// rewrite. "immediate" is the default and is byte-identical to pre-0.1.2 behavior.
-export const FOLD_SCHEDULING_MODES = Object.freeze(["immediate", "epoch"] as const);
-export type FoldSchedulingMode = typeof FOLD_SCHEDULING_MODES[number];
-export const DEFAULT_FOLD_SCHEDULING: FoldSchedulingMode = "immediate";
+// Two-phase fold scheduling, and the only scheduler. A provider prefix cache is
+// positional: any mid-window edit invalidates every byte after it, so the cost of
+// folding is dominated by how OFTEN the projection changes, not by how much it saves.
+// A fold decision is therefore a free MARK, and a later COMMIT applies every pending
+// mark in one rewrite. The alternative shipped as an option through 1.0.2 and was
+// deleted once measured: applying each fold where it was made cost 54 prefix rewrites
+// and a 0.193 pooled cache share against epoch's 0.919 on the same task.
 
 // Epoch knobs stay INTERNAL constants for the same reason the surfacing knobs do:
 // they are what the round-2 cost measurement exists to settle, and an option surface
 // fixed before that data would freeze a guess.
-/**
- * An automatic commit tops up with stale tool batches until it would free this share
- * of the window. It is a FLOOR under an epoch's accumulated marks, not the driver of
- * one, so it is set where a commit is unambiguously worth its single rewrite.
- */
-export const EPOCH_COMMIT_TARGET_WINDOW_SHARE = 0.40;
-/**
- * Commit when the ELIGIBLE marked mass is worth its one rewrite. Window pressure stays
- * underneath as the safety backstop; this is the economic trigger above it.
- */
-export const EPOCH_ELIGIBLE_SHARE_COMMIT_THRESHOLD = 0.30;
 /**
  * The reclaim floor, and the single constant that decides whether a commit is worth
  * firing at all.
@@ -127,32 +142,239 @@ export const EPOCH_ELIGIBLE_SHARE_COMMIT_THRESHOLD = 0.30;
  * per-mutation penalty is the same on both.
  *
  * So a commit that would free less than this share of the truthful budget does not
- * fire: it defers and accumulates until it is worth a full prefix. Safety outranks
- * economics, so the hard fence and overflow recovery fire regardless.
+ * fire: it defers and accumulates until it is worth a full prefix. A request whose
+ * projection exceeds the provider input budget is rejected outright, so recovery must
+ * produce a window that fits; the hard fence and overflow recovery fire regardless.
  */
 export const COMMIT_RECLAIM_FLOOR_SHARE = 0.02;
 
 /**
- * The thermostat's lower line.
+ * The pin ceiling (Shane 2026-08-09): protect may hold at most this share of the
+ * truthful serving budget raw. Protect was a per-entry promise with no mass bound,
+ * so a protect-happy agent could pin the window solid and leave every commit
+ * nothing to reclaim; past the cap, protect refuses with the cap named and
+ * unprotect is the release valve. A constant, not a knob.
+ */
+export const MAX_PINNED_SHARE = 0.25;
+
+// ---------------------------------------------------------------------------
+// THE THERMOSTAT. One declared object, one denominator, four numbers.
+//
+// Occupancy used to be a cluster: a trigger share of the budget, a post-commit target
+// share of the budget, a freeing floor stated as a share of the WINDOW, a fresh tail
+// stated in turns and bytes with a small-window byte cap, and a consolidation count.
+// Three of those divided by a different denominator than the other two, so the same
+// English word meant two numbers five to ten points apart at large windows. They are
+// one decision, so they are one object, and every one of them is now a proportion of
+// `capacityAccounting.budgetTokens` -- the truthful serving budget, the same value the
+// fence, the estimator and the trigger already read.
+//
+// There was a fifth, `staleTail`, that declared how far back automation could reach as a
+// byte prefix of the window. It is deleted (Shane 2026-08-10): automatic foldability is a
+// CLASS a span belongs to, not a position it occupies, so there is no width to declare.
+//
+// User-set, never agent-set (Sol 2026-08-09): an agent that can widen freshTail or move
+// maxTarget to the fence neutralizes the governor without ever calling a verb it is not
+// entitled to. Agent authority stays where it already is -- mark, unmark, protect,
+// unprotect -- and status may REPORT these values.
+// ---------------------------------------------------------------------------
+
+/** The four numbers that decide when a commit fires, how deep it cuts, and what stays raw. */
+export interface ActiveContextThresholds {
+  /** Occupancy of the serving budget that fires an automatic commit. */
+  maxTarget: number;
+  /** Occupancy an automatic commit folds down toward. The hysteresis gap is maxTarget - minTarget. */
+  minTarget: number;
+  /** Newest share of the serving budget where nothing folds, marked or not. */
+  freshTail: number;
+  /** Unpinned member folds at or above which placeholders become span material. */
+  consolidateAfter: number;
+}
+
+/**
+ * The proven values, and the reason each one is the number it is.
+ *
+ * maxTarget 0.80: Shane's RULING after rep 15. Below this line the runtime is quiet --
+ * nothing folds automatically at all -- so the line is where the fold event should
+ * happen, and the remaining fifth of the budget is the runway the commit itself spends.
  *
- * The floor above says what is worth firing; this says how DEEP a firing goes. The
- * failure shape it removes is rep 13's crumb ratchet: a trigger that fires, frees a
- * little, and re-fires almost immediately, so the window climbs a staircase of
- * mutations. Firing at the trigger line and folding down to a target line makes the
- * spacing between events structural -- the next event cannot arrive until inflow has
- * refilled the gap -- so the window saws instead of climbing.
+ * minTarget 0.35: the thermostat's lower line, and the reason event spacing is
+ * structural rather than hoped for. Rep 13's crumb ratchet fired, freed a little and
+ * re-fired, so the window climbed a staircase of mutations; folding down to a lower
+ * line means the next event cannot arrive until inflow has refilled a 45-point gap.
+ * Rep 13's largest measured inflow step was 27,815 tokens against a 400,000 window,
+ * about 7 points, so six worst-case steps land between events.
+ *
+ * freshTail 0.02: today's protected tail, re-denominated. The proven tail was 24,000
+ * serialized bytes; at the estimator's 4 bytes per token that is 6,000 tokens, and
+ * against the reference serving budget of 383,616 tokens (a 400,000-token window minus
+ * the 16,384-token response reserve) that is 1.564%, rounded UP to 0.02 so the
+ * re-denomination never narrows protection at the reference deployment.
+ *
+ * consolidateAfter 10: the proven count (the retired width rung counted the same roots
+ * against the same line). Placeholder briefs are about 300 tokens, so ten siblings cost
+ * under 1% of budget, and ten keeps an overnight session within two hops of any
+ * verbatim byte. A count, not a proportion: table-of-contents readability does not
+ * scale with window size, and a proportion would add a second denominator to the one
+ * thing this object exists to make singular.
+ */
+export const DEFAULT_THRESHOLDS: Readonly<ActiveContextThresholds> = Object.freeze({
+  maxTarget: 0.80,
+  minTarget: 0.35,
+  freshTail: 0.02,
+  consolidateAfter: 10,
+});
+
+/**
+ * The smallest serving budget this package supports, in tokens.
+ *
+ * Derived from the package's own two largest bounded replies: one status payload
+ * (CONTEXT_STATUS_RESPONSE_BYTES, 24,000) plus one default peek
+ * (PEEK_DEFAULT_MAX_BYTES, 16,000) is 40,000 bytes, which at the estimator's 4 bytes
+ * per token is 10,000 tokens. A budget that cannot hold the largest pair of answers
+ * this package can emit back to back cannot serve the surface it ships, so registration
+ * refuses it by name rather than folding its way into an unservable session.
+ */
+export const MINIMUM_SUPPORTED_BUDGET_TOKENS = 10_000;
+
+/**
+ * The narrowest fresh tail that still protects anything, in tokens: one minimum tool
+ * result (`minToolChars` 2,000 bytes) at the estimator's 4 bytes per token. A tail
+ * thinner than the smallest thing automation will ever fold protects nothing.
+ */
+export const MINIMUM_FRESH_TAIL_TOKENS = 500;
+
+export class ThresholdPolicyError extends Error {
+  readonly invariant: string;
+  constructor(invariant: string, message: string) {
+    super(message);
+    this.name = "ThresholdPolicyError";
+    this.invariant = invariant;
+  }
+}
+
+function thresholdProportion(value: unknown, field: string): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0 || value >= 1) {
+    throw new ThresholdPolicyError(field, `thresholds.${field} must be a proportion above 0 and below 1`);
+  }
+  return value;
+}
+
+/**
+ * The whole object, validated atomically, or an error naming the invariant that failed.
+ *
+ * Atomic because these are four quarters of one decision: validating them one at a time
+ * is how a trigger moved from 0.50 to 0.80 while its target stayed at 0.35 and the
+ * docstring kept arguing a 15-point gap that had become 45. Never clamped: a policy that
+ * cannot be served is a registration error, not a value to quietly rewrite (Sol).
+ */
+export function resolveThresholds(value: unknown): ActiveContextThresholds {
+  if (value === undefined) return { ...DEFAULT_THRESHOLDS };
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    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;
+  for (const key of Object.keys(supplied)) {
+    if (!(fields as readonly string[]).includes(key)) {
+      throw new ThresholdPolicyError("shape", `thresholds has no ${key} field`);
+    }
+  }
+  for (const field of fields) {
+    if (!Object.prototype.hasOwnProperty.call(supplied, field)) {
+      throw new ThresholdPolicyError("shape", `thresholds must declare ${field}; the object is set whole or not at all`);
+    }
+  }
+  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");
+  }
+  // L < M: the thermostat needs a gap to fold down into.
+  if (!(minTarget < maxTarget)) {
+    throw new ThresholdPolicyError("minTarget<maxTarget",
+      "thresholds.minTarget must sit below thresholds.maxTarget, or a commit has no depth to reach");
+  }
+  // F < M: a fresh tail wider than the trigger is a window that triggers on protection.
+  if (!(freshTail < maxTarget)) {
+    throw new ThresholdPolicyError("freshTail<maxTarget",
+      "thresholds.freshTail must sit below thresholds.maxTarget, or the trigger fires on protected mass alone");
+  }
+  // G >= F: one refill of the protected tail must not re-arm the trigger by itself.
+  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");
+  }
+  // P + F < M, in TOKENS at the smallest supported budget, so rounding cannot slip past:
+  // the pin ceiling plus the structurally fresh tail is the floor a commit can never get
+  // under, and a trigger at or below that floor announces commits with nothing to reclaim.
+  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 };
+}
+
+/**
+ * The tiny-window refusal, evaluated once at registration against the declared budget.
+ * Reject, never clamp: a deployment whose window cannot carry the policy it asked for
+ * gets told so with both numbers rather than a silently different governor.
+ */
+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`);
+  }
+}
+
+/**
+ * THE serving budget, from one window, by one formula.
+ *
+ * The output reservation is what makes the budget differ from the window, so it is
+ * subtracted exactly once and everything downstream -- the fence, the estimator, the
+ * trigger, and every threshold proportion -- divides by the same number.
+ */
+/**
+ * A zone width in serialized BYTES, from a share of the serving budget.
  *
- * The gap here is 15 points of a truthful budget. Rep 13's largest measured inflow step
- * was 27,815 tokens against a 400,000 window, about 7 points, so at least two full
- * worst-case steps must land before the trigger can re-arm, and the agent keeps roughly
- * two thirds of its budget as working room after every event. Eligibility still binds:
- * if the eligible mass cannot reach the target, the commit takes what it may and
- * records the shortfall rather than loosening a protection to hit a number.
+ * The thresholds are proportions of one denominator and a transcript position is a byte
+ * count, so exactly one conversion stands between them: the estimator's bytes per token.
+ * It is stated here, once, so every share of the budget is cut by one ruler.
  */
-export const CURATION_TARGET_OCCUPANCY_SHARE = 0.35;
+export function zoneBytes(share: number, budgetTokens: number): number {
+  if (!Number.isFinite(share) || share <= 0 || !Number.isFinite(budgetTokens) || budgetTokens <= 0) return 0;
+  return Math.floor(share * budgetTokens * ESTIMATED_BYTES_PER_TOKEN);
+}
+
+export function servingBudgetTokens(window: number): number {
+  const resolved = Number.isFinite(window) && window > 0 ? window : DEFAULT_CONTEXT_WINDOW;
+  return resolved - Math.min(ACTIVE_CONTEXT_POLICY.responseReserve, Math.floor(resolved * 0.1));
+}
+
 export const MAX_PENDING_MARKS = 256;
 /** Enough batches to actually reach the floor on a wide window before the loop exits. */
 export const EPOCH_MAX_TOPUP_MARKS = 64;
+/**
+ * How many times one commit re-reads its own eligible-root count.
+ *
+ * A termination bound, not a cadence: a parent is excluded from the count that produced
+ * it, so each round divides the standing roots by `consolidateAfter` and the sequence
+ * closes in two rounds at any window a session can carry.
+ */
+export const EPOCH_CONSOLIDATION_ROUNDS = 4;
 /** Estimate only; provider token accounting always comes from a measured response. */
 export const ESTIMATED_BYTES_PER_TOKEN = 4;
 /** Rendered navigation/topology overhead assumed around a brief when estimating a placeholder. */
@@ -163,8 +385,10 @@ export const ESTIMATED_PLACEHOLDER_OVERHEAD_BYTES = 240;
 // through iterations 2 and 3 and was sealed ON by rep 14 (64/64), so it is now
 // simply how pi-fold works: the flags and their conditional twins are gone, and
 // git history is the lineage. What stays configurable is only what is genuinely a
-// deployment fact (`providerTotalWindow`) or an experiment condition (`guidance`,
-// `foldScheduling`, `foldPeekResults`, `guidedCuration`).
+// deployment fact (`providerTotalWindow`). The experiment conditions that used to sit
+// beside it (`foldScheduling`, `foldPeekResults`, `guidedCuration`) are gone too: epoch
+// scheduling, peek foldability and guided curation are simply how pi-fold works, and
+// the harness keeps reading the keys only so sealed runs still validate.
 //
 // Sealed unconditional: admission control, retained pending marks, the eligible-share
 // commit trigger, stage-identified briefs, the current-turn commit guard, the
@@ -198,53 +422,82 @@ export const STATUS_DIET_SUGGESTIONS = 5;
 export const MAX_PROJECTION_HASH_RECORDS = 64;
 
 // ---------------------------------------------------------------------------
-// Guided curation. The one iteration-4 experiment condition: the two-signal
-// curation trigger, its bounded last-call gate, and the reactive receipt block.
+// Guided curation: the two-signal curation trigger, its bounded last-call gate,
+// and the reactive receipt block. It shipped as the one iteration-4 experiment
+// condition and is unconditional now, so only the constants below remain.
 // ---------------------------------------------------------------------------
 
-export const DEFAULT_GUIDED_CURATION = false;
-
 /**
- * Signal one: measured occupancy of the truthful serving budget.
+ * The three occupancy waypoints, as shares of the truthful serving budget.
  *
- * Four fifths, not half (Shane RULING 2026-08-06, after rep 15): below this line the
- * runtime is QUIET -- nothing folds automatically at all -- so the threshold is where
- * the fold event should happen, and the remaining fifth of the budget is the runway the
- * gate rounds and the commit itself spend. An earlier line buys announcement room by
- * spending window the agent still wants for the task.
+ * Each one lands exactly once per upward crossing as an append-once notice that then
+ * persists in the window the way a tool result does: appended at the tail, closed over
+ * by the freeze, never re-rendered mid-cycle, so it can never move a prefix byte. A
+ * commit that drops occupancy back under a waypoint re-arms it; the next crossing is a
+ * new event and gets a new notice.
  */
-export const CURATION_OCCUPANCY_SHARE = 0.80;
-
+export const THRESHOLD_NOTICE_SHARES: readonly number[] = Object.freeze([0.25, 0.50, 0.75]);
+/** Delivered notices kept rendered in the window; the oldest leaves the carrier, never the stream. */
+export const MAX_THRESHOLD_NOTICES = 9;
 /**
- * The two sparse reminders, as shares of the truthful serving budget.
- *
- * Exactly two per window cycle, one line each, informatory: mark chapters as you go so
- * the folds are neat when the fold event triggers. They are the ONLY pre-gate guidance
- * in guided curation -- recurring pressure nags trained rep 15's agent to ignore the
- * one message that mattered -- and they re-arm after each commit cycle, so a window that
- * climbs twice is reminded twice.
+ * The two guidance surfaces, as ONE public option, both switches defaulting on.
+ * Shane's ruling: notices and action responses are optional, and the default is yes.
  */
-export const CURATION_REMINDER_SHARES: readonly number[] = Object.freeze([0.45, 0.65]);
+export interface ActiveContextGuidance {
+  /** Append-once occupancy waypoints at 25/50/75 percent of the serving budget. */
+  thresholdNotices: boolean;
+  /** Persistent acknowledgements for the agent's own context actions. */
+  actionResponses: boolean;
+}
+
+export const DEFAULT_GUIDANCE: ActiveContextGuidance = Object.freeze({
+  thresholdNotices: true,
+  actionResponses: true,
+});
+
+const GUIDANCE_KEYS: readonly (keyof ActiveContextGuidance)[] = Object.freeze([
+  "thresholdNotices", "actionResponses",
+]);
 
 /**
- * Signal two: tool-result mass OUTSIDE the fresh tail, as a share of the window.
- * Occupancy alone announces commits a commit cannot serve -- a window full of
- * conversation has nothing stale to fold. Rep 14 ran 138 tool results over ~4.2MB of
- * payload against a 400k window, so a fifth of the window (~80k tokens, ~320KB) is
- * roughly a dozen ordinary results: reached early in a tool-heavy run, and never
- * reached by a run whose window is not actually made of stale tool output. It is half
- * the commit's own top-up target, so the announcement always precedes a commit that
- * has at least half a target of real mass to work with.
+ * Validated whole, like the thresholds: an unknown key is a typo, not a silent no-op.
+ *
+ * Booleans and nothing else. The dosage families that used to parameterize guidance
+ * (profiles, reminder shares, milestone budgets) were deleted for measuring nothing
+ * across eleven runs, and shares or per-notice keys here would rebuild them by another
+ * name. An operator either wants the runtime to speak at the boundary or does not.
  */
-export const CURATION_STALE_TOOL_SHARE = 0.20;
-
+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 { thresholdNotices, 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 both 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);
+}
+/** The last-call is LITERAL persisted bytes; the bound is on the stored text itself. */
+export const MAX_LAST_CALL_TEXT_BYTES = 2_048;
+/** One notice is one waypoint line; a waypoint that becomes a paragraph is bloat. */
+export const MAX_THRESHOLD_NOTICE_TEXT_BYTES = 512;
 /**
- * The gate's hard round cap. Every context pass with the gate open consumes one round,
- * so the commit proceeds after at most this many passes NO MATTER WHAT the agent does;
- * a pass whose response was not a context-tool call proceeds immediately. Two is a
- * bounded conversation, not a negotiation, and it makes a stall non-constructible.
+ * The surfacing line's own bound, applied to the line and not to the carrier that
+ * carries it, so a carrier's total overhead is its own bound plus this one and stays a
+ * number a gate can pin. The 21.9% ephemeral-slate tax is what this is measured
+ * against: one bounded line landing inside a rewrite the commit already paid for.
  */
-export const CURATION_GATE_MAX_ROUNDS = 2;
+export const MAX_SURFACING_LINE_BYTES = 384;
 
 /** How many automatic-action receipts stay in the window; the oldest ages out. */
 export const MAX_CONTEXT_RECEIPTS = 3;
@@ -314,6 +567,44 @@ export const MAX_FOLD_SPAN_CHARS = 16_000;
  * every absorption is receipted, and a wrong grouping is one `reboundary` away.
  */
 export const MAX_WEDGE_ABSORB_TOKENS = 256;
+/**
+ * How many generator calls the upgrade lane may hold open at once.
+ *
+ * The lane has to write briefs at the rate the ladder makes folds, or the folds that
+ * carry a model brief are a shrinking fraction of the folds a long session holds. One
+ * call in flight, started once per ladder pass, is not that rate: the live pressure run
+ * of 2026-08-10 measured completions at 6.9s, 9.4s and 14.3s while passes came about
+ * half a minute apart, so the lane spent most of its time idle and produced exactly one
+ * brief per commit boundary while four folds sat waiting. Two in flight, with a finished
+ * call starting the next one itself, makes production a function of generator latency
+ * instead of pass cadence. Two rather than more because provider calls are real money
+ * and real concurrency: the ladder makes about one leaf fold per boundary, and a lane
+ * that outruns the ladder by a wider margin only buys idle capacity.
+ */
+export const MAX_BRIEF_UPGRADES_IN_FLIGHT = 2;
+/**
+ * How many folds may be waiting on a generator at once. The queue holds each fold's
+ * exact source, so it is a memory bound as much as a work bound, and a fold dropped for
+ * a full queue simply keeps the deterministic brief it committed with. With the queue
+ * capped here and calls capped above, the work a session can have outstanding is a
+ * constant, and so is the number of briefs any one boundary can be asked to carry.
+ */
+export const MAX_BRIEF_UPGRADE_QUEUE = 4;
+/**
+ * How many spans one generator call may brief at once.
+ *
+ * A commit folds its spans together, so they are briefed together: one call, one answer,
+ * one brief per span. Sending them one at a time is what left the 2026-08-11 rep with 14
+ * model briefs across 87 committed folds, because the ladder makes about a dozen folds per
+ * boundary and the lane could hold four.
+ *
+ * Ten because that is the ladder's own group width (`consolidateAfter`), so a batch is
+ * never asked for more briefs than a consolidation would produce, and the answer stays
+ * bounded at ten brief caps. The batch's SOURCE is bounded by `maxSourceChars`, the same
+ * budget a single span was always held to, so the queue's memory bound does not move: it
+ * is still MAX_BRIEF_UPGRADE_QUEUE requests of at most one source budget each.
+ */
+export const MAX_BRIEF_BATCH_SPANS = 10;
 /** What a peek returns without an explicit widening argument. */
 export const PEEK_DEFAULT_MAX_BYTES = 16_000;
 /** Head share of a truncated peek; the remainder is the tail, where conclusions live. */
@@ -336,13 +627,13 @@ export const PEEK_HEAD_SHARE = 0.6;
  */
 export const OVERFLOW_RECOVERY_MAX_ATTEMPTS = 2;
 
-/** Active-context tool actions that read without mutating, so their results may fold. */
-export const READ_ONLY_CONTEXT_ACTIONS_DEFAULT: ReadonlySet<string> = new Set(["status"]);
 /**
- * The classification that also lets a `peek` result be reclaimed by the tool-fold rung.
+ * Active-context tool actions that read without mutating, so their results may fold.
+ *
  * A peek copies a fold's own stored source back into the window, so leaving it raw is a
- * pure duplicate of evidence the runtime already holds; epoch scheduling adopts this set
- * unconditionally, and immediate scheduling reaches it through `foldPeekResults`.
+ * pure duplicate of evidence the runtime already holds and the tool-fold rung reclaims
+ * it. There was a narrower set while immediate scheduling existed, reached by opting
+ * out; epoch is the only scheduler now and this classification is unconditional.
  */
 export const PEEK_READ_ONLY_CONTEXT_ACTIONS: ReadonlySet<string> = new Set(["status", "peek"]);
 
@@ -372,25 +663,34 @@ export interface PendingRefoldMark {
 export type PendingMark = PendingFoldMark | PendingRefoldMark;
 
 export const ACTIVE_CONTEXT_POLICY = Object.freeze({
-  freshTurns: 3,
-  freshBytes: 24_000,
-  freshWindowShare: 0.25,
-  warningRatio: 0.65,
-  toolFoldRatio: 0.75,
   refoldRatio: 0.85,
   prepareRatio: 0.90,
   warmRatio: 0.55,
   responseReserve: 16_384,
-  consolidationRatio: 0.85,
-  consolidationChildren: 5,
-  maxConsolidationChildren: 8,
   minToolChars: 2_000,
   minChapterChars: 4_000,
   maxChapterChars: 128_000,
   maxChapterTurns: 4,
   maxSourceChars: 200_000,
   maxFoldSourceRefs: 256,
-  maxBriefChars: 1_200,
+  /**
+   * 2,000 (Shane 2026-08-11), raised from 1,200.
+   *
+   * The cap is a limit the generator is told and can be cured against, not a truncation
+   * point, so it should sit where a good brief stops rather than where a cheap one does.
+   * Measured against what a stop-the-world compaction hands forward: this harness's own
+   * native-arm summaries ran 8,000 to 20,000 characters for a whole session, and a folded
+   * window carries about ten briefs, so a per-fold budget of roughly a tenth of a handoff
+   * is 800 to 2,000. The ceiling of that range is the right end to sit at, because ten
+   * briefs at the cap is 20,000 characters against a serving budget measured in hundreds
+   * of thousands, and because the cost of a brief that is too short is a fold the agent
+   * cannot decide whether to expand.
+   *
+   * It binds rarely by design: the run before this one averaged well under 1,200 on the
+   * calls that were not being truncated by a token ceiling. `context.brief` records every
+   * cure so the next run says how often it binds at all.
+   */
+  maxBriefChars: 2_000,
   briefTimeoutMs: 120_000,
   orientationMessages: 2,
   maxOrientationChars: 12_000,
@@ -409,6 +709,12 @@ export type BriefProvenance =
       launchContractDigest?: string;
     };
 
+/**
+ * A brief written after its fold committed: the agent's bare correction, or a model
+ * brief carrying the generator that wrote it.
+ */
+export type BriefOverride = string | { brief: string; provenance: BriefProvenance };
+
 export interface ActiveFold {
   id: string;
   kind: FoldKind;
@@ -438,42 +744,55 @@ export interface PreparedFold {
   fold: ActiveFold;
 }
 
-export type SurfacingOutcome = "shown" | "accept" | "reject";
+/**
+ * The graded success labels. `shown` is the open offer; the other three are terminal.
+ * `acted` is a context verb on the surfaced fold inside the window, `used` is that plus
+ * the retrieved content showing up in what the agent went on to say or call, and
+ * `ignored` is a closed window with neither.
+ */
+export type SurfacingOutcome = "shown" | "acted" | "used" | "ignored";
 
-/** One durable surfacing observation: what was shown, how it scored, and what the agent did. */
+/**
+ * The durable SUPPRESSION ledger: one record per fold, not one per showing. The
+ * per-suggestion detail a bandit trains on is the event stream, which is durable and
+ * unbounded; this is only what the next selection pass must not forget.
+ */
 export interface SurfacingRecord {
-  source: string;
   id: string;
-  score: number;
+  surfaced: number;
+  taken: number;
+  /** Transcript ordinal of the last state change; the cooldown and the window read it. */
   ordinal: number;
   outcome: SurfacingOutcome;
 }
 
-/** One item a suggestion source offers for the shared carrier. */
+/** One suppression-state change, returned so the caller emits it rather than inferring it. */
+export interface SurfacingTransition {
+  id: string;
+  from: SurfacingOutcome;
+  to: SurfacingOutcome;
+  ordinal: number;
+}
+
+/** One collapsed fold, scored on both channels. */
 export interface SurfacingCandidate {
-  source: string;
   id: string;
-  text: string;
+  /** What the placeholder shows: the brief channel. */
+  brief: string;
+  /** What the fold stores, descendants included: the content channel. */
+  content: string;
   route: string;
-  alternateRoute?: string;
-  /** Transcript position used for recency; higher is more recent. Never a wall clock. */
-  position?: number;
-  depth?: number;
+  /** Transcript position of the fold's last entry; higher is more recent. Never a clock. */
+  position: number;
+  depth: number;
 }
 
 export interface SurfacingSuggestion extends SurfacingCandidate {
-  score: number;
-}
-
-export interface SuggestionSourceInput {
-  state: ActiveContextState;
-  snapshot: ActiveContextSnapshot;
-  toolName: string;
-}
-
-export interface SuggestionSource {
-  id: string;
-  candidates: (input: SuggestionSourceInput) => SurfacingCandidate[];
+  contentScore: number;
+  briefScore: number;
+  margin: number;
+  /** Slate position, from 0. One suggestion per delivery point, so today it is always 0. */
+  slot: number;
 }
 
 export interface ActiveContextState {
@@ -491,18 +810,38 @@ export interface ActiveContextState {
   /** Retired with peek reclamation; carried only so pre-cut state still parses. */
   pinnedPeeks?: never;
   /**
-   * Agent-corrected fold briefs, by fold id. A fold RECORD is content-addressed and
+   * Corrected and upgraded fold briefs, by fold id. A fold RECORD is content-addressed and
    * immutable -- rewriting its brief in place would report a conflicting durable fold
    * and suspend automatic management -- so a re-brief is durable state beside the
    * record rather than a mutation of it. Omitted when empty.
    */
-  briefs?: Record<string, string>;
+  briefs?: Record<string, BriefOverride>;
   prepared?: PreparedFold;
   advisory?: {
     highWater: number;
     delivered: Record<string, number>;
     armed?: { milestone: AdvisoryMilestone; threshold: number; scheduleKey: string };
   };
+  /**
+   * The one action-prompt carrier: computed at a fold commit, persisted as LITERAL
+   * bytes so every re-render of the same epoch is byte-identical, replaced only by
+   * the next epoch's rider. Omitted when absent so pre-rider state digests never move.
+   */
+  rider?: { epoch: number; text: string };
+  /**
+   * The armed pre-commit last-call: one exposure per band-top crossing, persisted as
+   * LITERAL bytes like the rider. `exposure` is the context.lastcall event's stream
+   * seq; `contextCalls` and `agentMarks` are the arming snapshot the response
+   * attribution is measured against. Cleared by the commit that consumes it. Omitted
+   * when absent so pre-last-call state digests never move.
+   */
+  lastCall?: { exposure: number; ordinal: number; contextCalls: number; agentMarks: number; text: string };
+  /**
+   * Threshold notices: `fired` is the waypoint shares spent this occupancy cycle
+   * (re-armed by a commit that drops back under them), `ring` the delivered notices
+   * still rendered in the window, literal bytes, oldest evicted. Omitted when absent.
+   */
+  notices?: { fired: number[]; ring: Array<{ share: number; ordinal: number; text: string }> };
 }
 
 export interface FoldRecordRef {
@@ -531,8 +870,11 @@ export interface ActiveContextCheckpointV2 {
   leases?: Record<string, number>;
   surfacing?: SurfacingRecord[];
   pendingMarks?: PendingMark[];
-  briefs?: Record<string, string>;
+  briefs?: Record<string, BriefOverride>;
   advisory?: NonNullable<ActiveContextState["advisory"]>;
+  rider?: NonNullable<ActiveContextState["rider"]>;
+  lastCall?: NonNullable<ActiveContextState["lastCall"]>;
+  notices?: NonNullable<ActiveContextState["notices"]>;
   stateSha256: string;
 }
 
@@ -552,8 +894,11 @@ export interface ActiveContextDeltaV2 {
   leases?: Record<string, number>;
   surfacing?: SurfacingRecord[];
   pendingMarks?: PendingMark[];
-  briefs?: Record<string, string>;
+  briefs?: Record<string, BriefOverride>;
   advisory?: NonNullable<ActiveContextState["advisory"]>;
+  rider?: NonNullable<ActiveContextState["rider"]>;
+  lastCall?: NonNullable<ActiveContextState["lastCall"]>;
+  notices?: NonNullable<ActiveContextState["notices"]>;
   stateSha256: string;
 }
 
@@ -583,13 +928,17 @@ export interface ActiveContextSnapshot {
   branchObjects: BranchObject[];
   completeTurns: CompleteTurn[];
   freshBoundary: number;
+  /** The four thermostat numbers in force for this session. */
+  thresholds: ActiveContextThresholds;
+  /** The serving budget the thresholds are proportions of. One denominator. */
+  budgetTokens: number;
   protectedIndices: Set<number>;
   toolProtectedIndices: Set<number>;
   policy: typeof ACTIVE_CONTEXT_POLICY;
   toolName: string;
   brandNoun: string;
   entryTypePrefix: string;
-  readOnlyTools: ReadonlySet<string>;
+  blacklistAutoFoldTools: ReadonlySet<string>;
   /** Active-context tool actions treated as read-only when classifying tool batches. */
   readOnlyContextActions: ReadonlySet<string>;
   contextWindow: number;
@@ -602,8 +951,15 @@ export interface FoldCandidate {
   sourceRefs: EvidenceRef[];
 }
 
-export const READ_ONLY_TOOLS_DEFAULT = new Set([
-  "read", "grep", "find", "ls",
-]);
+/**
+ * The auto-fold exception list, EMPTY by default: every completed tool batch is foldable
+ * by the ladder without an agent mark, and this names the tools whose results must stay
+ * raw. The list ran the other way until the 2026-08-10 surface, as an allow-list seeded
+ * with pi's four built-in readers, which meant a deployment's own tools were unfoldable
+ * until someone remembered to name them and the ladder starved on exactly the results
+ * that filled the window. Foldability was never the protection: pins, the fresh tail and
+ * the commit guard are, and they apply to a blacklisted tool and an ordinary one alike.
+ */
+export const AUTO_FOLD_BLACKLIST_DEFAULT: ReadonlySet<string> = new Set();
 
 export type AdvisoryMilestone = "orientation" | "notice" | "tools" | "chapters" | "urgent";