pi-fold 1.0.2 → 1.0.3

package/extensions/lib/instrumentation.ts

@@ -137,24 +137,44 @@ export type ContextEventKind =
   | "context.attempt"
   /** One auto-snap applied to a requested span, referencing its attempt. */
   | "context.correction"
+  /** One protect or unprotect: durable pin bookkeeping; no window bytes move. */
+  | "context.protect"
   /** The resolved serving budget, stated once at startup so a live run can prove it. */
   | "context.capacity"
-  /** One evaluation of the guided-curation last-call gate. */
-  | "context.gate"
-  /** One sparse occupancy reminder delivered into the window. */
-  | "context.reminder"
   /** One receipt delivered into the window. */
   | "context.receipt"
+  /** One post-commit rider composed and persisted: at most one per fold epoch. */
+  | "context.rider"
+  /** One pre-commit last-call exposure: the band-top prompt, with its telemetry. */
+  | "context.lastcall"
+  /** One gated round's outcome, attributed to the exposure it answers. */
+  | "context.response"
+  /** One surfacing suggestion issued: both channel scores, the divergence, the carrier. */
+  | "context.suggestion"
+  /** One surfacing suggestion graded: the acted/used/ignored join and its transition. */
+  | "context.outcome"
+  /** One append-once occupancy threshold notice delivered into the window. */
+  | "context.notice"
   /** One commit epoch: the single mutation an epoch pays for. */
   | "context.commit"
   /** One fold created, by the ladder or by the agent. */
   | "context.fold"
+  /**
+   * One generator call for a brief: what it read, what it wrote, and what it cost.
+   *
+   * The generator runs outside the session, so its spend appears in no provider ledger
+   * and its latency appears in no turn. Without this record a deployment cannot say what
+   * briefing costs it, which is the question the async lane exists to answer.
+   */
+  | "context.brief"
   /** One boundary sliver absorbed into its later neighbour. */
   | "context.absorb"
   /** One oversized span split into sequential bite-sized folds. */
   | "context.split"
   /** One overflow rollback and the recovery that followed it. */
   | "context.recovery"
+  /** One tree rollback: what left the branch, and whether the request replayed. */
+  | "context.rollback"
   /** One projection built, classified against the one before it. */
   | "context.projection"
   /** One provider response, which is where this stream joins provider usage. */

package/extensions/lib/measurement.ts

@@ -7,6 +7,7 @@ import {
   sha256Value,
 } from "../json.ts";
 import {
+  bytes,
   clone,
   exactRecord,
   messageRole,
@@ -22,8 +23,7 @@ import {
 import {
   ACTIVE_CONTEXT_POLICY,
   DEFAULT_CONTEXT_WINDOW,
-  TOOL_FOLD_CADENCE_MIN_TOKENS,
-  TOOL_FOLD_CADENCE_WINDOW_FRACTION,
+  servingBudgetTokens,
 } from "./policy.ts";
 import type {
   ActiveContextSnapshot,
@@ -35,7 +35,7 @@ import type {
 export { protectionSha256, topologySha256 } from "./persistence.ts";
 export { clone } from "./canonical.ts";
 export { sha256Value } from "../json.ts";
-export { ADVISORY_BUDGETS, validAdvisoryState } from "./persistence.ts";
+export { validAdvisoryState } from "./persistence.ts";
 
 export const MAPPED_BY_KEY = new WeakMap<ActiveContextSnapshot, Map<string, MappedMessage>>();
 
@@ -89,6 +89,32 @@ export function contextUsageRatio(value: unknown): number | null {
   return tokens / contextWindow;
 }
 
+/**
+ * A measured WINDOW ratio, restated as occupancy of the serving budget.
+ *
+ * The provider reports tokens against its total window and the thermostat is declared
+ * against the serving budget, so exactly one conversion stands between them and it is
+ * written here rather than inferred at each reader. Before this build the trigger
+ * divided by the budget while the freeing target and the backstop divided by the
+ * window, which at a 383,616-token budget behind a 400,000-token window is a 4.5-point
+ * disagreement, and 10 points at a 100,000-token fixture.
+ */
+export function budgetOccupancy(snapshot: ActiveContextSnapshot, windowRatio: number | null): number | null {
+  if (typeof windowRatio !== "number" || !Number.isFinite(windowRatio)) return null;
+  if (!(snapshot.budgetTokens > 0) || !(snapshot.contextWindow > 0)) return null;
+  return windowRatio * snapshot.contextWindow / snapshot.budgetTokens;
+}
+
+/**
+ * The fence, as a ratio of the window the measured ratio is denominated against.
+ *
+ * A measured ratio is tokens over `contextWindow`, so "the request reached its serving
+ * budget" is exactly `ratio >= budgetTokens / contextWindow`. When the snapshot carries
+ * a budget the runtime uses it verbatim: a deployment that DECLARED its input budget has
+ * already netted out its output reservation, and re-subtracting one here would fence it
+ * roughly four points early. Only the ctx fallback, where nothing but a raw provider
+ * window is known, still estimates the reservation.
+ */
 export function hardFenceRatio(value?: unknown, ctx?: any): number {
   const direct = ownValue(value, "contextWindow");
   const reported = ownValue(ctx?.getContextUsage?.(), "contextWindow");
@@ -97,6 +123,10 @@ export function hardFenceRatio(value?: unknown, ctx?: any): number {
     : typeof reported === "number" && Number.isFinite(reported) && reported > 0
       ? reported
       : DEFAULT_CONTEXT_WINDOW;
+  const budgetTokens = ownValue(value, "budgetTokens");
+  if (typeof budgetTokens === "number" && Number.isFinite(budgetTokens) && budgetTokens > 0) {
+    return Math.min(1, budgetTokens / contextWindow);
+  }
   const reserve = Math.min(
     ACTIVE_CONTEXT_POLICY.responseReserve,
     Math.floor(contextWindow * 0.1),
@@ -118,7 +148,7 @@ export function hardFenceRatio(value?: unknown, ctx?: any): number {
  * is how a 25 percent error survived four instrumented runs.
  */
 export interface CapacityAccounting {
-  /** "truthful" once the deployment declares its total serving window. */
+  /** "truthful" once the deployment declares its own serving budget. */
   mode: "descriptor" | "truthful";
   /** The denominator every pressure ratio and fence is computed against. */
   window: number;
@@ -131,6 +161,18 @@ export interface CapacityAccounting {
   descriptorWindow: number | null;
 }
 
+/**
+ * ONE denominator, and no guess in front of it.
+ *
+ * `truthful` means the deployment stated the budget it may actually fill, already net of
+ * whatever output reservation it holds back, so the value passes through untouched and
+ * the reservation this runtime reports is zero because it withheld nothing. Only the
+ * descriptor fallback still subtracts, because a per-request max-input descriptor is a
+ * total-window claim and the reservation inside it has to be estimated. That estimate was
+ * the defect the reshape removed: the runtime subtracted a fixed 16,384 tokens capped at
+ * a tenth of the window while the documentation claimed it subtracted the reservation
+ * actually in force.
+ */
 export function capacityAccounting(input: {
   window: number;
   truthful: boolean;
@@ -138,11 +180,8 @@ export function capacityAccounting(input: {
   usedTokens: number | null;
 }): CapacityAccounting {
   const window = Number.isFinite(input.window) && input.window > 0 ? input.window : DEFAULT_CONTEXT_WINDOW;
-  const outputReservation = Math.min(
-    ACTIVE_CONTEXT_POLICY.responseReserve,
-    Math.floor(window * 0.1),
-  );
-  const budgetTokens = window - outputReservation;
+  const budgetTokens = input.truthful ? window : servingBudgetTokens(window);
+  const outputReservation = window - budgetTokens;
   const usedTokens = typeof input.usedTokens === "number" && Number.isFinite(input.usedTokens) &&
     input.usedTokens >= 0 ? input.usedTokens : null;
   return {
@@ -270,13 +309,6 @@ export function contextWindowFor(ctx: any): number | null {
   return typeof modelWindow === "number" && Number.isFinite(modelWindow) && modelWindow > 0 ? modelWindow : null;
 }
 
-export function toolFoldCadence(contextWindow: number): number {
-  if (!Number.isFinite(contextWindow) || contextWindow <= 0) {
-    throw new Error("Tool-fold cadence requires a positive context window");
-  }
-  return Math.max(TOOL_FOLD_CADENCE_MIN_TOKENS, TOOL_FOLD_CADENCE_WINDOW_FRACTION * contextWindow);
-}
-
 export function rootFolds(state: ActiveContextState): ActiveFold[] {
   return state.folds.filter((fold) => fold.parentId === null);
 }
@@ -370,6 +402,50 @@ export function toolRefsProtected(
   });
 }
 
+/**
+ * Mass the agent's pins hold out of the ladder's reach: explicitly protected evidence
+ * outside the fresh tail. A pin's cost must be a number the agent sees on receipts,
+ * never a silent commit shortfall.
+ */
+export function protectedStaleMass(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+): { bytes: number; refs: number } {
+  const explicit = explicitProtectedKeys(state);
+  if (!explicit.size) return { bytes: 0, refs: 0 };
+  let total = 0;
+  let refs = 0;
+  for (const item of snapshot.mapped) {
+    if (!item.ref || !explicit.has(objectRefKey(item.ref))) continue;
+    if (snapshot.protectedIndices.has(item.index)) continue;
+    total += bytes(item.message);
+    refs += 1;
+  }
+  return { bytes: total, refs };
+}
+
+/**
+ * Every byte protect currently holds raw, fresh or stale: the mass the pinned-share
+ * cap is measured against. protectedStaleMass narrows to what a commit could not
+ * reclaim TODAY; the cap has to see the whole promise, because a pin inside the
+ * fresh tail outlives the tail.
+ */
+export function explicitProtectedMass(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+): { bytes: number; refs: number } {
+  const explicit = explicitProtectedKeys(state);
+  if (!explicit.size) return { bytes: 0, refs: 0 };
+  let total = 0;
+  let refs = 0;
+  for (const item of snapshot.mapped) {
+    if (!item.ref || !explicit.has(objectRefKey(item.ref))) continue;
+    total += bytes(item.message);
+    refs += 1;
+  }
+  return { bytes: total, refs };
+}
+
 export interface AdmissionVerdict {
   admitted: boolean;
   reason: "admitted" | "unmeasured" | "would-cross-fence";