pi-fold 0.1.0 → 1.0.0

package/extensions/lib/persistence.ts

@@ -22,6 +22,8 @@ import {
   EXPAND_LEASE_GENERATIONS,
   MAX_ADVISORY_DELIVERIES_PER_MILESTONE,
   MAX_EXPAND_LEASES,
+  MAX_PENDING_MARKS,
+  SURFACING_MAX_LOG_RECORDS,
 } from "./policy.ts";
 import type {
   ActiveContextCheckpointV2,
@@ -35,7 +37,10 @@ import type {
   FoldPart,
   FoldRecordEntry,
   FoldRecordRef,
+  MarkOrigin,
+  PendingMark,
   PreparedFold,
+  SurfacingRecord,
 } from "./policy.ts";
 
 export const ACTIVE_FOLD_KEYS = [
@@ -49,6 +54,13 @@ export const PREPARED_FOLD_KEYS = [
 export const ACTIVE_STATE_KEYS = ["version", "sessionId", "revision", "folds", "expanded", "protected"] as const;
 export const FOLD_RECORD_REF_KEYS = ["id", "sha256"] as const;
 export const FOLD_RECORD_ENTRY_KEYS = ["version", "sessionId", "foldId", "recordSha256", "fold"] as const;
+export const SURFACING_RECORD_KEYS = ["source", "id", "score", "ordinal", "outcome"] as const;
+export const SURFACING_OUTCOMES = Object.freeze(["shown", "accept", "reject"] as const);
+export const PENDING_FOLD_MARK_KEYS = [
+  "mark", "id", "kind", "parts", "brief", "briefProvenance", "origin", "ordinal",
+] as const;
+export const PENDING_REFOLD_MARK_KEYS = ["mark", "id", "origin", "ordinal"] as const;
+export const MARK_ORIGINS = Object.freeze(["agent", "ladder"] as const);
 export const STATE_CHECKPOINT_V2_KEYS = [
   "version", "kind", "sessionId", "revision", "foldRefs", "expanded", "protected", "prepared", "stateSha256",
 ] as const;
@@ -67,6 +79,85 @@ export function validTokensSinceToolFold(value: unknown): value is number {
   return Number.isSafeInteger(value) && Number(value) >= 0;
 }
 
+export function validSurfacingRecord(value: unknown): value is SurfacingRecord {
+  if (!exactRecord(value, SURFACING_RECORD_KEYS)) return false;
+  const score = ownValue(value, "score");
+  return typeof ownValue(value, "source") === "string" && Boolean(ownValue(value, "source")) &&
+    typeof ownValue(value, "id") === "string" && Boolean(ownValue(value, "id")) &&
+    typeof score === "number" && Number.isFinite(score) && Number(score) >= 0 && Number(score) <= 1 &&
+    Number.isSafeInteger(ownValue(value, "ordinal")) && Number(ownValue(value, "ordinal")) >= 0 &&
+    SURFACING_OUTCOMES.includes(ownValue(value, "outcome") as SurfacingRecord["outcome"]);
+}
+
+export function parseSurfacingLog(value: unknown): SurfacingRecord[] {
+  const records = denseOwnArrayValues(value);
+  if (!records || records.length > SURFACING_MAX_LOG_RECORDS || !records.every(validSurfacingRecord)) {
+    throw new Error("Invalid active-context surfacing log");
+  }
+  return clone(records) as SurfacingRecord[];
+}
+
+/** Stable identity of one pending mark: its phase plus the fold it names. */
+export function pendingMarkKey(mark: Pick<PendingMark, "mark" | "id">): string {
+  return `${mark.mark}:${mark.id}`;
+}
+
+export function validPendingMark(value: unknown): value is PendingMark {
+  const id = ownValue(value, "id");
+  const ordinal = ownValue(value, "ordinal");
+  if (typeof id !== "string" || !id ||
+      !MARK_ORIGINS.includes(ownValue(value, "origin") as MarkOrigin) ||
+      !Number.isSafeInteger(ordinal) || Number(ordinal) < 0) return false;
+  const mark = ownValue(value, "mark");
+  if (mark === "refold") return exactRecord(value, PENDING_REFOLD_MARK_KEYS);
+  if (mark !== "fold" || !exactRecord(value, PENDING_FOLD_MARK_KEYS)) return false;
+  const kind = ownValue(value, "kind");
+  const parts = denseOwnArrayValues(ownValue(value, "parts"));
+  return (kind === "tool-result" || kind === "chapter" || kind === "consolidation") &&
+    Boolean(parts?.length) && parts!.length <= ACTIVE_CONTEXT_POLICY.maxFoldSourceRefs &&
+    parts!.every(validFoldPart) && structurallyValidBrief(ownValue(value, "brief")) &&
+    validProvenance(ownValue(value, "briefProvenance")) &&
+    id === foldIdFor(kind as FoldKind, parts as FoldPart[]);
+}
+
+/**
+ * Agent-corrected fold briefs, keyed by fold id. Bounded by the same brief cap a
+ * supplied brief obeys, and refused for a fold that is not in the forest, exactly
+ * like a pin or a refold mark naming a missing fold.
+ */
+export function parseBriefOverrides(
+  value: unknown,
+  ids?: ReadonlySet<string>,
+): Record<string, string> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Invalid active-context brief overrides");
+  }
+  const entries = Object.entries(value as Record<string, unknown>);
+  if (entries.length > MAX_ACTIVE_FOLD_RECORDS ||
+      entries.some(([id, brief]) => !id || typeof brief !== "string" || !brief.trim() ||
+        brief.length > ACTIVE_CONTEXT_POLICY.maxBriefChars || (ids && !ids.has(id)))) {
+    throw new Error("Invalid active-context brief overrides");
+  }
+  return Object.fromEntries(entries.sort(([left], [right]) => left.localeCompare(right))) as Record<string, string>;
+}
+
+/** The brief a fold PRESENTS: the agent's correction when it made one, else the record's. */
+export function foldBrief(
+  fold: Pick<ActiveFold, "id" | "brief">,
+  state: Pick<ActiveContextState, "briefs">,
+): string {
+  return state.briefs?.[fold.id] ?? fold.brief;
+}
+
+export function parsePendingMarks(value: unknown): PendingMark[] {
+  const marks = denseOwnArrayValues(value);
+  if (!marks || marks.length > MAX_PENDING_MARKS || !marks.every(validPendingMark) ||
+      new Set((marks as PendingMark[]).map(pendingMarkKey)).size !== marks.length) {
+    throw new Error("Invalid active-context pending marks");
+  }
+  return clone(marks) as PendingMark[];
+}
+
 export function parseLeases(value: unknown, foldIds?: ReadonlySet<string>): Record<string, number> {
   if (!isPlainRecord(value)) throw new Error("Invalid active-context expand leases");
   const entries = Object.entries(value);
@@ -235,11 +326,23 @@ export function parseActiveContextState(
   const hasTokensSinceToolFold = recordLike &&
     Object.prototype.hasOwnProperty.call(value, "tokensSinceToolFold");
   const hasLeases = recordLike && Object.prototype.hasOwnProperty.call(value, "leases");
+  const hasSurfacing = recordLike && Object.prototype.hasOwnProperty.call(value, "surfacing");
+  const hasPendingMarks = recordLike && Object.prototype.hasOwnProperty.call(value, "pendingMarks");
+  // Accepted, never read, never written. `pinnedPeeks` pinned a peek result against
+  // per-projection reclamation, which was deleted after rep 22 measured it rewriting
+  // the prefix mid-window. State written before that cut still carries the key, and
+  // rejecting it here would suspend automatic management on upgrade.
+  const hasPinnedPeeks = recordLike && Object.prototype.hasOwnProperty.call(value, "pinnedPeeks");
+  const hasBriefs = recordLike && Object.prototype.hasOwnProperty.call(value, "briefs");
   const extraKeys = [
     ...(hasPrepared ? ["prepared"] : []),
     ...(hasAdvisory ? ["advisory"] : []),
     ...(hasTokensSinceToolFold ? ["tokensSinceToolFold"] : []),
     ...(hasLeases ? ["leases"] : []),
+    ...(hasSurfacing ? ["surfacing"] : []),
+    ...(hasPendingMarks ? ["pendingMarks"] : []),
+    ...(hasPinnedPeeks ? ["pinnedPeeks"] : []),
+    ...(hasBriefs ? ["briefs"] : []),
   ];
   if (!exactRecord(value, [...ACTIVE_STATE_KEYS, ...extraKeys])) throw new Error("Invalid active-context state keys");
   const folds = denseOwnArrayValues(ownValue(value, "folds"));
@@ -265,8 +368,14 @@ export function parseActiveContextState(
     throw new Error("Invalid active-context tool-fold cadence");
   }
   const leases = hasLeases ? parseLeases(ownValue(value, "leases"), ids) : {};
+  const surfacing = hasSurfacing ? parseSurfacingLog(ownValue(value, "surfacing")) : [];
+  const marks = hasPendingMarks ? parsePendingMarks(ownValue(value, "pendingMarks")) : [];
+  if (marks.some((mark) => mark.mark === "refold" && !ids.has(mark.id))) {
+    throw new Error("Invalid active-context pending marks");
+  }
+  const briefs = hasBriefs ? parseBriefOverrides(ownValue(value, "briefs"), ids) : {};
   const source = clone(value) as unknown as ActiveContextState;
-  // Provenance normalization is presentation-only — never mutate a durable
+  // Provenance normalization is presentation-only; never mutate a durable
   // content-addressed fold record: changing its bytes causes the next re-persist
   // to report a conflicting durable fold and suspend automatic management.
   return {
@@ -280,6 +389,11 @@ export function parseActiveContextState(
       ? Number(ownValue(value, "tokensSinceToolFold"))
       : 0,
     leases,
+    // Omitted when empty so every state written before surfacing existed keeps its
+    // exact digest; the replay digest is order- and presence-sensitive by design.
+    ...(surfacing.length ? { surfacing } : {}),
+    ...(marks.length ? { pendingMarks: marks } : {}),
+    ...(Object.keys(briefs).length ? { briefs } : {}),
     ...(hasAdvisory
       ? { advisory: clone(source.advisory!) }
       : defaultAdvisory ? { advisory: { highWater: 0, delivered: {} } } : {}),
@@ -355,6 +469,9 @@ export function sameStateProjection(left: ActiveContextState, right: ActiveConte
     const normalizedState = { ...clone(value), revision: 0 } as Partial<ActiveContextState>;
     if (normalizedState.tokensSinceToolFold === 0) delete normalizedState.tokensSinceToolFold;
     if (normalizedState.leases && Object.keys(normalizedState.leases).length === 0) delete normalizedState.leases;
+    if (normalizedState.surfacing && normalizedState.surfacing.length === 0) delete normalizedState.surfacing;
+    if (normalizedState.pendingMarks && normalizedState.pendingMarks.length === 0) delete normalizedState.pendingMarks;
+    if (normalizedState.briefs && !Object.keys(normalizedState.briefs).length) delete normalizedState.briefs;
     return normalizedState;
   };
   return stableStringify(normalized(left)) === stableStringify(normalized(right));
@@ -395,6 +512,9 @@ export function validateV2ProjectionFields(
   advisoryValue: unknown,
   tokensSinceToolFoldValue: unknown,
   leasesValue: unknown,
+  surfacingValue?: unknown,
+  pendingMarksValue?: unknown,
+  briefsValue?: unknown,
 ): {
   expanded: string[];
   protected: EvidenceRef[];
@@ -402,6 +522,9 @@ export function validateV2ProjectionFields(
   advisory?: NonNullable<ActiveContextState["advisory"]>;
   tokensSinceToolFold: number;
   leases: Record<string, number>;
+  surfacing: SurfacingRecord[];
+  pendingMarks: PendingMark[];
+  briefs: Record<string, string>;
 } {
   const expanded = denseOwnArrayValues(expandedValue);
   const protectedRefs = denseOwnArrayValues(protectedValue);
@@ -419,6 +542,9 @@ export function validateV2ProjectionFields(
     throw new Error("Invalid active-context v2 tool-fold cadence");
   }
   const leases = leasesValue === undefined ? {} : parseLeases(leasesValue);
+  const surfacing = surfacingValue === undefined ? [] : parseSurfacingLog(surfacingValue);
+  const pendingMarks = pendingMarksValue === undefined ? [] : parsePendingMarks(pendingMarksValue);
+  const briefs = briefsValue === undefined ? {} : parseBriefOverrides(briefsValue);
   return {
     expanded: clone(expanded) as string[],
     protected: clone(protectedRefs) as EvidenceRef[],
@@ -428,6 +554,9 @@ export function validateV2ProjectionFields(
     }),
     tokensSinceToolFold: tokensSinceToolFoldValue === undefined ? 0 : Number(tokensSinceToolFoldValue),
     leases,
+    surfacing,
+    pendingMarks,
+    briefs,
   };
 }
 
@@ -439,10 +568,26 @@ export function parseActiveContextStateV2(value: unknown, sessionId: string): Ac
     Object.prototype.hasOwnProperty.call(value, "tokensSinceToolFold"));
   const hasLeases = Boolean(value && typeof value === "object" &&
     Object.prototype.hasOwnProperty.call(value, "leases"));
+  const hasSurfacing = Boolean(value && typeof value === "object" &&
+    Object.prototype.hasOwnProperty.call(value, "surfacing"));
+  const hasPendingMarks = Boolean(value && typeof value === "object" &&
+    Object.prototype.hasOwnProperty.call(value, "pendingMarks"));
+  // Accepted, never read, never written. `pinnedPeeks` pinned a peek result against
+  // per-projection reclamation, which was deleted after rep 22 measured it rewriting
+  // the prefix mid-window. State written before that cut still carries the key, and
+  // rejecting it here would suspend automatic management on upgrade.
+  const hasPinnedPeeks = Boolean(value && typeof value === "object" &&
+    Object.prototype.hasOwnProperty.call(value, "pinnedPeeks"));
+  const hasBriefs = Boolean(value && typeof value === "object" &&
+    Object.prototype.hasOwnProperty.call(value, "briefs"));
   const optionalKeys = [
     ...(hasAdvisory ? ["advisory"] : []),
     ...(hasTokensSinceToolFold ? ["tokensSinceToolFold"] : []),
     ...(hasLeases ? ["leases"] : []),
+    ...(hasSurfacing ? ["surfacing"] : []),
+    ...(hasPendingMarks ? ["pendingMarks"] : []),
+    ...(hasPinnedPeeks ? ["pinnedPeeks"] : []),
+    ...(hasBriefs ? ["briefs"] : []),
   ];
   const checkpoint = kind === "checkpoint" &&
     exactRecord(value, [...STATE_CHECKPOINT_V2_KEYS, ...optionalKeys]);
@@ -457,6 +602,7 @@ export function parseActiveContextStateV2(value: unknown, sessionId: string): Ac
   validateV2ProjectionFields(
     ownValue(value, "expanded"), ownValue(value, "protected"), ownValue(value, "prepared"),
     ownValue(value, "advisory"), ownValue(value, "tokensSinceToolFold"), ownValue(value, "leases"),
+    ownValue(value, "surfacing"), ownValue(value, "pendingMarks"), ownValue(value, "briefs"),
   );
   if (checkpoint) {
     const refs = denseOwnArrayValues(ownValue(value, "foldRefs"));
@@ -521,7 +667,7 @@ export function stateFromFoldRefs(
   wire: Pick<
     ActiveContextCheckpointV2,
     "sessionId" | "revision" | "expanded" | "protected" | "prepared" | "advisory" |
-      "tokensSinceToolFold" | "leases"
+      "tokensSinceToolFold" | "leases" | "surfacing" | "pendingMarks" | "briefs"
   >,
   refs: FoldRecordRef[],
   records: Map<string, FoldRecordEntry>,
@@ -541,6 +687,9 @@ export function stateFromFoldRefs(
     protected: clone(wire.protected),
     tokensSinceToolFold: wire.tokensSinceToolFold ?? 0,
     leases: clone(wire.leases ?? {}),
+    ...(wire.surfacing?.length ? { surfacing: clone(wire.surfacing) } : {}),
+    ...(wire.pendingMarks?.length ? { pendingMarks: clone(wire.pendingMarks) } : {}),
+    ...(wire.briefs && Object.keys(wire.briefs).length ? { briefs: clone(wire.briefs) } : {}),
     ...(wire.advisory === undefined ? {} : { advisory: clone(wire.advisory) }),
     ...(wire.prepared === null || wire.prepared === undefined ? {} : { prepared: clone(wire.prepared) }),
   };
@@ -690,6 +839,9 @@ export function makeStateCheckpoint(state: ActiveContextState): ActiveContextChe
     prepared: state.prepared ? clone(state.prepared) : null,
     tokensSinceToolFold: state.tokensSinceToolFold,
     leases: clone(state.leases),
+    ...(state.surfacing?.length ? { surfacing: clone(state.surfacing) } : {}),
+    ...(state.pendingMarks?.length ? { pendingMarks: clone(state.pendingMarks) } : {}),
+    ...(state.briefs && Object.keys(state.briefs).length ? { briefs: clone(state.briefs) } : {}),
     ...(state.advisory ? { advisory: clone(state.advisory) } : {}),
     stateSha256: semanticStateSha256(state),
   }, state.sessionId) as ActiveContextCheckpointV2;
@@ -724,6 +876,9 @@ export function makeStateDelta(previous: ActiveContextState, next: ActiveContext
     prepared: next.prepared ? clone(next.prepared) : null,
     tokensSinceToolFold: next.tokensSinceToolFold,
     leases: clone(next.leases),
+    ...(next.surfacing?.length ? { surfacing: clone(next.surfacing) } : {}),
+    ...(next.pendingMarks?.length ? { pendingMarks: clone(next.pendingMarks) } : {}),
+    ...(next.briefs && Object.keys(next.briefs).length ? { briefs: clone(next.briefs) } : {}),
     ...(next.advisory ? { advisory: clone(next.advisory) } : {}),
     stateSha256: semanticStateSha256(next),
   }, next.sessionId) as ActiveContextDeltaV2;
@@ -738,6 +893,7 @@ export function protectionSha256(state: Pick<ActiveContextState, "protected">):
 }
 
 export const ADVISORY_BUDGETS: Readonly<Record<AdvisoryMilestone, number>> = Object.freeze({
+  orientation: 1,
   notice: 2,
   tools: 2,
   chapters: 2,