pi-fold 0.0.1 → 0.1.1

package/extensions/json.ts

@@ -0,0 +1,228 @@
+import { createHash } from "node:crypto";
+import { types as utilTypes } from "node:util";
+
+export interface EvidenceRef {
+  sessionId: string;
+  entryId: string;
+  role: string;
+  sha256: string;
+}
+
+// Capture trust-boundary intrinsics before mutable prototypes can influence validation.
+const ArrayConstructor = Array;
+const arrayIsArray = Array.isArray;
+const arrayPrototype = Array.prototype;
+const defineProperty = Object.defineProperty;
+const freeze = Object.freeze;
+const getOwnPropertyDescriptor = Object.getOwnPropertyDescriptor;
+const getPrototypeOf = Object.getPrototypeOf;
+const jsonStringify = JSON.stringify;
+const number = Number;
+const numberIsFinite = Number.isFinite;
+const numberIsSafeInteger = Number.isSafeInteger;
+const objectIs = Object.is;
+const objectPrototype = Object.prototype;
+const ownKeys = Reflect.ownKeys;
+const regexpTest = RegExp.prototype.test;
+const reflectApply = Reflect.apply;
+const string = String;
+const isProxy = utilTypes.isProxy;
+const sha256Pattern = /^[a-f0-9]{64}$/;
+
+function appendArrayValue(values: unknown[], value: unknown): void {
+  defineProperty(values, string(values.length), {
+    value,
+    enumerable: true,
+    configurable: true,
+    writable: true,
+  });
+}
+
+function safeJson(value: unknown, ancestors: unknown[]): string | undefined {
+  if (value === null) return "null";
+  const kind = typeof value;
+  if (kind === "string" || kind === "boolean") return jsonStringify(value);
+  if (kind === "number") return numberIsFinite(value) ? jsonStringify(value) : "null";
+  if (kind === "undefined" || kind === "function" || kind === "symbol") return undefined;
+  if (kind === "bigint") throw new Error("Value is not JSON-serializable");
+  if (!value || kind !== "object" || isProxy(value)) throw new Error("Value is not JSON-serializable");
+  for (let index = 0; index < ancestors.length; index += 1) {
+    if (ancestors[index] === value) throw new Error("Value contains a cycle");
+  }
+  const depth = ancestors.length;
+  appendArrayValue(ancestors, value);
+  try {
+    if (arrayIsArray(value)) {
+      if (getPrototypeOf(value) !== arrayPrototype) throw new Error("Value is not a plain JSON array");
+      const lengthDescriptor = getOwnPropertyDescriptor(value, "length");
+      if (!lengthDescriptor || !("value" in lengthDescriptor) ||
+          !numberIsSafeInteger(lengthDescriptor.value) || lengthDescriptor.value < 0) {
+        throw new Error("Value is not a dense JSON array");
+      }
+      const length = number(lengthDescriptor.value);
+      let output = "[";
+      for (let index = 0; index < length; index += 1) {
+        if (index) output += ",";
+        const descriptor = getOwnPropertyDescriptor(value, string(index));
+        if (!descriptor) {
+          output += "null";
+          continue;
+        }
+        if (!("value" in descriptor) || !descriptor.enumerable) throw new Error("Value contains an array accessor");
+        output += safeJson(descriptor.value, ancestors) ?? "null";
+      }
+      return `${output}]`;
+    }
+    if (!isPlainRecord(value)) throw new Error("Value is not a plain JSON object");
+    const keys = ownKeys(value);
+    let output = "{";
+    let emitted = 0;
+    for (let index = 0; index < keys.length; index += 1) {
+      const key = keys[index];
+      if (typeof key !== "string") throw new Error("Value contains a symbol property");
+      const descriptor = getOwnPropertyDescriptor(value, key);
+      if (!descriptor || !("value" in descriptor)) throw new Error("Value contains an object accessor");
+      if (!descriptor.enumerable) continue;
+      const serialized = safeJson(descriptor.value, ancestors);
+      if (serialized === undefined) continue;
+      if (emitted) output += ",";
+      output += `${jsonStringify(key)}:${serialized}`;
+      emitted += 1;
+    }
+    return `${output}}`;
+  } finally {
+    defineProperty(ancestors, "length", { value: depth, writable: true });
+  }
+}
+
+/** Preserve JSON property order without invoking getters, toJSON, coercion, iterators, or mutable prototypes. */
+export function stableStringify(value: unknown): string {
+  const serialized = safeJson(value, new ArrayConstructor<unknown>());
+  if (typeof serialized !== "string") throw new Error("Value is not JSON-serializable");
+  return serialized;
+}
+
+export function sha256Text(value: string): string {
+  return createHash("sha256").update(value, "utf8").digest("hex");
+}
+
+export function sha256Value(value: unknown): string {
+  return sha256Text(stableStringify(value));
+}
+
+export function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || arrayIsArray(value) || isProxy(value)) return false;
+  const prototype = getPrototypeOf(value);
+  return prototype === objectPrototype || prototype === null;
+}
+
+export function ownDataProperty(value: unknown, key: PropertyKey): unknown {
+  if (!isPlainRecord(value)) return undefined;
+  const descriptor = getOwnPropertyDescriptor(value, key);
+  return descriptor && "value" in descriptor ? descriptor.value : undefined;
+}
+
+/** Copy a dense own-data array without invoking inherited accessors, iterators, or methods. */
+export function denseOwnArrayValues(value: unknown): unknown[] | null {
+  if (!arrayIsArray(value) || isProxy(value) || getPrototypeOf(value) !== arrayPrototype) return null;
+  const lengthDescriptor = getOwnPropertyDescriptor(value, "length");
+  if (!lengthDescriptor || !("value" in lengthDescriptor) ||
+      !numberIsSafeInteger(lengthDescriptor.value) || lengthDescriptor.value < 0) return null;
+  const length = number(lengthDescriptor.value);
+  const values = new ArrayConstructor<unknown>(length);
+  for (let index = 0; index < length; index += 1) {
+    const descriptor = getOwnPropertyDescriptor(value, string(index));
+    if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) return null;
+    defineProperty(values, string(index), {
+      value: descriptor.value,
+      enumerable: true,
+      configurable: false,
+      writable: false,
+    });
+  }
+  const keys = ownKeys(value);
+  let indexes = 0;
+  for (let index = 0; index < keys.length; index += 1) {
+    const key = keys[index];
+    if (key === "length") continue;
+    if (key === "toJSON") {
+      const descriptor = getOwnPropertyDescriptor(value, key);
+      if (!descriptor || !("value" in descriptor) || descriptor.value !== undefined || descriptor.enumerable ||
+          descriptor.configurable || descriptor.writable) return null;
+      continue;
+    }
+    if (typeof key !== "string") return null;
+    const numeric = number(key);
+    if (!numberIsSafeInteger(numeric) || numeric < 0 || numeric >= length || string(numeric) !== key) return null;
+    indexes += 1;
+  }
+  if (indexes !== length) return null;
+
+  const copiedLength = getOwnPropertyDescriptor(values, "length");
+  if (!copiedLength || !("value" in copiedLength) || copiedLength.value !== length) return null;
+  for (let index = 0; index < length; index += 1) {
+    const source = getOwnPropertyDescriptor(value, string(index));
+    const copied = getOwnPropertyDescriptor(values, string(index));
+    if (!source || !("value" in source) || !copied || !("value" in copied) ||
+        !objectIs(copied.value, source.value) || !copied.enumerable || copied.configurable || copied.writable) return null;
+  }
+  freeze(values);
+  return values;
+}
+
+export function isObjectRef(value: unknown): value is EvidenceRef {
+  if (!isPlainRecord(value)) return false;
+  const keys = ownKeys(value);
+  if (keys.length !== 4) return false;
+  let mask = 0;
+  for (let index = 0; index < keys.length; index += 1) {
+    const key = keys[index];
+    if (typeof key !== "string") return false;
+    if (key === "sessionId") mask |= 1;
+    else if (key === "entryId") mask |= 2;
+    else if (key === "role") mask |= 4;
+    else if (key === "sha256") mask |= 8;
+    else return false;
+    const descriptor = getOwnPropertyDescriptor(value, key);
+    if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) return false;
+  }
+  if (mask !== 15) return false;
+  const sessionId = ownDataProperty(value, "sessionId");
+  const entryId = ownDataProperty(value, "entryId");
+  const role = ownDataProperty(value, "role");
+  const sha256 = ownDataProperty(value, "sha256");
+  return typeof sessionId === "string" && sessionId.length > 0 &&
+    typeof entryId === "string" && entryId.length > 0 &&
+    typeof role === "string" && role.length > 0 &&
+    typeof sha256 === "string" && reflectApply(regexpTest, sha256Pattern, [sha256]);
+}
+
+export function objectRefKey(ref: EvidenceRef): string {
+  return stableStringify({ sessionId: ref.sessionId, entryId: ref.entryId, role: ref.role });
+}
+
+export function sameObjectIdentity(left: EvidenceRef, right: EvidenceRef): boolean {
+  return objectRefKey(left) === objectRefKey(right);
+}
+
+export function evidenceValue(message: unknown): unknown {
+  if (!isPlainRecord(message) || ownDataProperty(message, "role") !== "custom") return message;
+  return {
+    role: "custom",
+    customType: ownDataProperty(message, "customType"),
+    content: ownDataProperty(message, "content"),
+    display: ownDataProperty(message, "display"),
+    details: ownDataProperty(message, "details"),
+  };
+}
+
+export function evidenceSha256(message: unknown): string {
+  return sha256Value(evidenceValue(message));
+}
+
+export function evidenceRef(sessionId: string, entryId: string, message: unknown): EvidenceRef {
+  if (!sessionId || !entryId || !isPlainRecord(message)) throw new Error("Pi evidence lacks a stable session, entry, or message");
+  const role = ownDataProperty(message, "role");
+  if (typeof role !== "string" || !role) throw new Error(`Pi entry ${entryId} has no role discriminator`);
+  return { sessionId, entryId, role, sha256: evidenceSha256(message) };
+}

package/extensions/lib/advisory.ts

@@ -0,0 +1,238 @@
+import { sha256Value } from "../json.ts";
+import { clone } from "./canonical.ts";
+import {
+  boundReceiptText,
+  hardFenceRatio,
+} from "./measurement.ts";
+import { ADVISORY_BUDGETS, validAdvisoryState } from "./persistence.ts";
+import type {
+  ActiveContextSnapshot,
+  ActiveContextState,
+  AdvisoryMilestone,
+  GuidanceProfile,
+  SurfacingSuggestion,
+} from "./policy.ts";
+import {
+  contextBrand,
+  DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN,
+  DEFAULT_GUIDANCE_PROFILE,
+  GUIDANCE_PROFILES,
+} from "./policy.ts";
+
+export { ADVISORY_BUDGETS };
+
+export interface AdvisorySchedule {
+  key: string;
+  rungs: Array<{ milestone: AdvisoryMilestone; threshold: number; budget: number }>;
+}
+
+export function advisoryState(state: ActiveContextState): NonNullable<ActiveContextState["advisory"]> {
+  if (state.advisory === undefined) return { highWater: 0, delivered: {} };
+  if (!validAdvisoryState(state.advisory)) {
+    throw new Error("Corrupt in-memory advisory state (no silent fallback)");
+  }
+  return clone(state.advisory);
+}
+
+export function clearArmedAdvisory(state: ActiveContextState): ActiveContextState {
+  const current = advisoryState(state);
+  if (!current.armed) return state;
+  const advisory = { ...current };
+  delete advisory.armed;
+  return { ...state, advisory };
+}
+
+export function normalizeGuidanceProfile(guidance: unknown = DEFAULT_GUIDANCE_PROFILE): GuidanceProfile {
+  if (!GUIDANCE_PROFILES.includes(guidance as GuidanceProfile)) {
+    throw new Error('guidance must be "pressure", "curation", or "minimal"');
+  }
+  return guidance as GuidanceProfile;
+}
+
+function guidanceRungs(
+  snapshot: Pick<ActiveContextSnapshot, "policy" | "contextWindow">,
+  guidance: GuidanceProfile,
+): AdvisorySchedule["rungs"] {
+  const urgent = {
+    milestone: "urgent" as const,
+    threshold: hardFenceRatio(snapshot) - 0.03,
+    budget: ADVISORY_BUDGETS.urgent,
+  };
+  if (guidance === "minimal") return [urgent];
+  return [
+    ...(guidance === "curation"
+      ? [{ milestone: "orientation" as const, threshold: 0.25, budget: ADVISORY_BUDGETS.orientation }]
+      : []),
+    { milestone: "notice" as const, threshold: 0.50, budget: ADVISORY_BUDGETS.notice },
+    { milestone: "tools" as const, threshold: snapshot.policy.toolFoldRatio - 0.04,
+      budget: ADVISORY_BUDGETS.tools },
+    { milestone: "chapters" as const, threshold: snapshot.policy.prepareRatio - 0.05,
+      budget: ADVISORY_BUDGETS.chapters },
+    urgent,
+  ];
+}
+
+export function advisorySchedule(
+  snapshot: Pick<ActiveContextSnapshot, "policy" | "contextWindow">,
+  guidance: GuidanceProfile = DEFAULT_GUIDANCE_PROFILE,
+): AdvisorySchedule {
+  const rungs = guidanceRungs(snapshot, guidance);
+  for (let index = rungs.length - 2; index >= 0; index -= 1) {
+    rungs[index].threshold = Math.min(rungs[index].threshold, rungs[index + 1].threshold - 0.02);
+  }
+  for (const rung of rungs) rung.threshold = Math.max(0, Math.min(1, rung.threshold));
+  return {
+    key: sha256Value(rungs.map(({ milestone, threshold }) => ({ milestone, threshold }))),
+    rungs,
+  };
+}
+
+export function updateAdvisoryMilestone(
+  currentState: ActiveContextState,
+  ratio: number,
+  schedule: AdvisorySchedule,
+  scheduleChanged: boolean,
+  scheduleKey: string,
+): { state: ActiveContextState; milestone: AdvisoryMilestone | null } {
+  const current = advisoryState(currentState);
+  if (scheduleChanged) {
+    return {
+      state: { ...currentState, advisory: { ...current, highWater: Math.min(1, ratio) } },
+      milestone: null,
+    };
+  }
+  let highWater = current.highWater;
+  for (let index = schedule.rungs.length - 1; index >= 0; index -= 1) {
+    const rung = schedule.rungs[index];
+    if ((current.delivered[rung.milestone] ?? 0) > 0 && ratio < 0.85 * rung.threshold) {
+      highWater = Math.min(highWater, index > 0 ? schedule.rungs[index - 1].threshold : 0);
+    }
+  }
+  const crossed = schedule.rungs.filter((rung) =>
+    highWater < rung.threshold && ratio >= rung.threshold &&
+    (current.delivered[rung.milestone] ?? 0) < rung.budget);
+  const selected = crossed.at(-1) ?? null;
+  const delivered = { ...current.delivered };
+  if (selected) delivered[selected.milestone] = (delivered[selected.milestone] ?? 0) + 1;
+  const armed = selected
+    ? { milestone: selected.milestone, threshold: selected.threshold, scheduleKey }
+    : current.armed;
+  return {
+    state: {
+      ...currentState,
+      advisory: {
+        highWater: Math.min(1, Math.max(highWater, ratio)),
+        delivered,
+        ...(armed ? { armed } : {}),
+      },
+    },
+    milestone: selected?.milestone ?? null,
+  };
+}
+
+function curationText(milestone: AdvisoryMilestone, percent: number, toolName: string): string {
+  if (milestone === "orientation") {
+    return "Collapsed folds are a browsable index of the work behind you, and their briefs sit in the cached " +
+      `prefix of the window, so paging that index costs almost nothing. Page it with ${toolName} ` +
+      `{"action":"status"} and expand what the current task needs with ${toolName} ` +
+      '{"action":"expand","id":"<fold-id>"}.';
+  }
+  if (milestone === "notice") {
+    return `Context is ${percent}% full; curate it against the task you are on now. Fold the spans that task ` +
+      `no longer needs with ${toolName} ` +
+      '{"action":"fold","ids":["<start>","<end>"],"brief":"<factual brief>"}, and keep what must stay raw out ' +
+      `of every fold with ${toolName} {"action":"protect","ids":["<entry-id>"]}.`;
+  }
+  if (milestone === "tools") {
+    return "Completed read-only tool batches are the cheapest thing to fold, and their endpoint ids are in the " +
+      "live advisory. Fold the batches whose detail this task is finished with; each one expands back to the " +
+      `exact entries later with ${toolName} {"action":"expand","id":"<fold-id>"}.`;
+  }
+  return "Fold up: hand two or more adjacent folds of finished work to " +
+    `${toolName} {"action":"fold","ids":["<fold-id>","<fold-id>"],"brief":"<factual brief>"} so they nest in ` +
+    "one deeper fold, leaving the oldest material deepest and still exactly recoverable. A closed chapter " +
+    `folds first, from the eligibleChapter endpoints in ${toolName} {"action":"status"}.`;
+}
+
+export function milestoneText(
+  milestone: AdvisoryMilestone,
+  sessionId: string,
+  threshold: number,
+  toolName: string,
+  brandNoun = DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN,
+  guidance: GuidanceProfile = DEFAULT_GUIDANCE_PROFILE,
+): string {
+  const percent = Math.round(threshold * 100);
+  const prefix = `[${contextBrand(brandNoun)} milestone ${milestone}; session ${sessionId.slice(0, 16)}]`;
+  if (guidance === "curation" && milestone !== "urgent") {
+    return `${prefix} ${curationText(milestone, percent, toolName)}`;
+  }
+  if (milestone === "notice") {
+    return `${prefix} Context pressure has crossed ${percent}%. Automatic folding is available. ` +
+      `Inspect candidates exactly with ${toolName} {"action":"status"}.`;
+  }
+  if (milestone === "tools") {
+    return `${prefix} The read-only tool-fold rung begins at ${percent}%. ` +
+      "Eligible completed tool batches can be folded now; current endpoint ids are in the live advisory.";
+  }
+  if (milestone === "chapters") {
+    return `${prefix} The chapter preparation rung begins at ${percent}%. ` +
+      `Use eligibleChapter endpoints with ${toolName} ` +
+      '{"action":"fold","ids":["<start>","<end>"],"brief":"<factual brief>"}.';
+  }
+  return `${prefix} The hard context fence is near. The next automatic action is a committed chapter fold ` +
+    "or the provider request is aborted before transmission.";
+}
+
+/**
+ * The surfacing carrier. It rides the same ephemeral tail channel as the live
+ * advisory: appended after the stable prefix, never durable, never a mutation of
+ * the projection, and cleared whenever the next context event is built.
+ */
+export function surfacingText(input: {
+  suggestions: readonly SurfacingSuggestion[];
+  brandNoun?: string;
+}): string | null {
+  if (!input.suggestions.length) return null;
+  const brand = contextBrand(input.brandNoun ?? DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN);
+  const lines = input.suggestions.map((suggestion, index) => [
+    `${index + 1}. ${suggestion.id}${suggestion.depth ? ` (depth ${suggestion.depth})` : ""}: ${suggestion.text}`,
+    ...(suggestion.alternateRoute ? [`   peek (ephemeral read): ${suggestion.alternateRoute}`] : []),
+    `   expand (durable restore): ${suggestion.route}`,
+  ].join("\n"));
+  return boundReceiptText(
+    [
+      `[${brand} suggestions] ${input.suggestions.length} collapsed span(s) look relevant to the current ` +
+        "task. Peek reads one back ephemerally at any depth; expand restores it in place, outermost first. " +
+        "Ignoring them is a valid answer.",
+      ...lines,
+    ].join("\n"),
+    2_048,
+    `[${brand} suggestions] Relevant collapsed spans are unavailable this pass.`,
+  );
+}
+
+export function liveAdvisoryText(input: {
+  milestone: AdvisoryMilestone;
+  ratio: number;
+  toolEndpoints: string[];
+  chapterEndpoints: string[];
+  remediationCount: number;
+  brandNoun?: string;
+}): string {
+  const tools = input.toolEndpoints.length
+    ? input.toolEndpoints.slice(0, 3).join(", ")
+    : "none";
+  const chapter = input.chapterEndpoints.length
+    ? `${input.chapterEndpoints[0]}..${input.chapterEndpoints.at(-1)}`
+    : "none";
+  return boundReceiptText(
+    `[${contextBrand(input.brandNoun ?? DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN)} advisory] ` +
+      `pressure ${Math.round(input.ratio * 100)}%; milestone ${input.milestone}; ` +
+      `eligible read-only batch endpoints: ${tools}; eligibleChapter endpoints: ${chapter}; ` +
+      `session milestone count: ${input.remediationCount}.`,
+    2_048,
+    `[${contextBrand(input.brandNoun ?? DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN)} advisory] ` +
+      "Live pressure details are unavailable.",
+  );
+}

package/extensions/lib/canonical.ts

@@ -0,0 +1,171 @@
+import {
+  denseOwnArrayValues,
+  evidenceSha256,
+  isPlainRecord,
+  stableStringify,
+} from "../json.ts";
+import { ACTIVE_CONTEXT_POLICY, DEFAULT_ACTIVE_CONTEXT_TOOL_NAME } from "./policy.ts";
+import type { ActiveContextState } from "./policy.ts";
+
+export function clone<T>(value: T): T {
+  return structuredClone(value);
+}
+
+export function bytes(value: unknown): number {
+  return Buffer.byteLength(typeof value === "string" ? value : stableStringify(value), "utf8");
+}
+
+export function boundedUtf8(text: string, maximumBytes: number): string {
+  const buffer = Buffer.from(text, "utf8");
+  if (buffer.length <= maximumBytes) return text;
+  // A multi-byte sequence cut by the bound decodes to one trailing replacement
+  // character; dropping it keeps the slice an exact prefix of the source.
+  return buffer.subarray(0, maximumBytes).toString("utf8").replace(/\uFFFD$/, "");
+}
+
+export function ownValue(value: unknown, key: string): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const descriptor = Object.getOwnPropertyDescriptor(value, key);
+  return descriptor && "value" in descriptor ? descriptor.value : undefined;
+}
+
+export function exactRecord(value: unknown, keys: readonly string[]): value is Record<string, unknown> {
+  if (!isPlainRecord(value)) return false;
+  const expected = new Set(keys);
+  const ownKeys = Reflect.ownKeys(value);
+  if (ownKeys.length !== expected.size) return false;
+  for (let index = 0; index < ownKeys.length; index += 1) {
+    const key = ownKeys[index];
+    if (typeof key !== "string" || !expected.has(key)) return false;
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) return false;
+  }
+  return true;
+}
+
+export function messageRole(message: unknown): string | null {
+  const role = ownValue(message, "role");
+  return typeof role === "string" && role ? role : null;
+}
+
+export function contentText(message: unknown): string {
+  const content = ownValue(message, "content");
+  if (typeof content === "string") return content;
+  const parts = denseOwnArrayValues(content);
+  if (!parts) return "";
+  const text: string[] = [];
+  for (let index = 0; index < parts.length; index += 1) {
+    const part = parts[index];
+    if (part && typeof part === "object" && ownValue(part, "type") === "text") {
+      text.push(String(ownValue(part, "text") ?? ""));
+    }
+  }
+  return text.join("\n");
+}
+
+/** Pi's exact one-entry projection, kept local so this service has no second transcript owner. */
+export function sessionEntryMessages(entry: Record<string, unknown>): unknown[] {
+  if (entry.type === "message" && entry.message && typeof entry.message === "object") {
+    const message = entry.message as Record<string, unknown>;
+    if ((message.role === "user" || message.role === "assistant" || message.role === "toolResult") &&
+        message.content == null) {
+      return [{ ...message, content: [] }];
+    }
+    return [message];
+  }
+  const timestamp = new Date(String(entry.timestamp)).getTime();
+  if (entry.type === "custom_message") {
+    return [{
+      role: "custom",
+      customType: entry.customType,
+      content: entry.content ?? [],
+      display: entry.display,
+      details: entry.details,
+      timestamp,
+    }];
+  }
+  if (entry.type === "branch_summary" && entry.summary) {
+    return [{ role: "branchSummary", summary: entry.summary, fromId: entry.fromId, timestamp }];
+  }
+  if (entry.type === "compaction") {
+    return [{ role: "compactionSummary", summary: entry.summary, tokensBefore: entry.tokensBefore, timestamp }];
+  }
+  return [];
+}
+
+export type UniqueMessageAnchor = {
+  index: number;
+  entryId: string;
+  message: unknown;
+};
+
+export function uniqueMessageDigestAnchor(
+  entries: readonly unknown[],
+  messageSha256: string,
+): UniqueMessageAnchor | null {
+  let anchor: UniqueMessageAnchor | null = null;
+  let digestMatches = 0;
+  for (let index = 0; index < entries.length; index += 1) {
+    const entry = entries[index];
+    if (!entry || typeof entry !== "object") continue;
+    const entryId = ownValue(entry, "id");
+    if (typeof entryId !== "string" || !entryId) continue;
+    const messages = sessionEntryMessages(entry as Record<string, unknown>);
+    for (let messageIndex = 0; messageIndex < messages.length; messageIndex += 1) {
+      let digest = "";
+      try { digest = evidenceSha256(messages[messageIndex]); } catch { continue; }
+      if (digest !== messageSha256) continue;
+      digestMatches += 1;
+      anchor = { index, entryId, message: messages[messageIndex] };
+    }
+  }
+  if (digestMatches !== 1 || !anchor) return null;
+  let identityMatches = 0;
+  for (let index = 0; index < entries.length; index += 1) {
+    if (ownValue(entries[index], "id") === anchor.entryId) identityMatches += 1;
+  }
+  return identityMatches === 1 ? anchor : null;
+}
+
+export function emptyActiveContextState(sessionId: string): ActiveContextState {
+  if (!sessionId) throw new Error("Active context requires a Pi session ID");
+  return {
+    version: 1,
+    sessionId,
+    revision: 0,
+    folds: [],
+    expanded: [],
+    protected: [],
+    tokensSinceToolFold: 0,
+    leases: {},
+    advisory: { highWater: 0, delivered: {} },
+  };
+}
+
+export function usefulBrief(
+  value: unknown,
+  maximum = ACTIVE_CONTEXT_POLICY.maxBriefChars,
+  toolName = DEFAULT_ACTIVE_CONTEXT_TOOL_NAME,
+): value is string {
+  if (typeof value !== "string") return false;
+  const brief = value.trim();
+  if (!brief || brief.length > maximum) return false;
+  const factualLines: string[] = [];
+  const lines = brief.split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    const text = lines[index].trim();
+    if (!text || text.toLowerCase().includes(toolName.toLowerCase()) ||
+        /^\[[^\]]*(?:fold|active-context)[^\]]*\]$/i.test(text)) continue;
+    if (/^(?:topology\b|expand\b|refold\b|list(?:\/page)?\b|page\b|action\b|fold(?:ed)?\s+(?:placeholder|uid|id)\b|(?:this\s+)?fold\b.*\b(?:expand|refold|placeholder|topology|uid|id)\b|(?:parent|children?|previous|next|navigation)\s*[:=])/i.test(text)) continue;
+    factualLines.push(text);
+  }
+  const factual = factualLines.join(" ").trim();
+  return /[A-Za-z0-9]{3,}/.test(factual);
+}
+
+export function structurallyValidBrief(value: unknown, maximum = ACTIVE_CONTEXT_POLICY.maxBriefChars): value is string {
+  if (typeof value !== "string") return false;
+  const brief = value.trim();
+  return Boolean(brief) && brief.length <= maximum &&
+    (brief.match(/[A-Za-z0-9]/g)?.length ?? 0) >= 3;
+}