dsh-ptc-plus 0.5.1 → 0.5.3

package/internal/kernel-worker.js

@@ -42,7 +42,7 @@ import { installProgramAmbientResolver } from './dynamic-environment-runtime.js'
 const { Object, Map, Set, Proxy, Error,
   mapGet, mapSet, mapHas, mapDelete, mapClear, mapSize, mapForEach,
   setHas, setAdd, setDelete, setClear, setForEach,
-  everyArray, someArray, appendArray, copyArray, join, sliceString, endsWith,
+  everyArray, someArray, isArray, min, appendArray, copyArray, join, sliceString, endsWith,
   bufferConcat, bufferIsBuffer, bufferToString,
   Reflect: privateReflect, promiseResolve, promiseReject } = moduleRuntimeIntrinsics
 const PublicPromise = globalThis.Promise
@@ -114,6 +114,11 @@ const output = new PassThrough()
 output.resume()
 const evaluationScope = createPrivateAsyncLocalStorage()
 const sessionCwd = typeof workerData?.cwd === 'string' ? workerData.cwd : undefined
+/** Fallback bound for the startup conformance probe when the host config omits one. */
+const DEFAULT_STARTUP_PROBE_MS = 5000
+const startupProbeMs = Number.isSafeInteger(workerData?.startupProbeMs) && workerData.startupProbeMs > 0
+  ? workerData.startupProbeMs
+  : DEFAULT_STARTUP_PROBE_MS
 // The module source base is fixed when a cell starts; the operation directory
 // follows the Session's working directory while the cell runs, so a confirmed
 // `tools.working_directory` change rebases the rest of the cell exactly as the
@@ -232,6 +237,9 @@ const CONFORMANCE_CELL = `"use strict";
 }`
 let activeRun
 let activeExecution
+// Compile-time proof that a binding's initializer is a bounded object literal,
+// keyed by binding name for the running cell.
+let declaredBoundedLiterals = new Map()
 let suppressReplCwdObservation = false
 let nextCallId = 0
 let nextStaticAdapterId = 0
@@ -964,7 +972,13 @@ async function activatePerNameUserBindings(snapshot, shadowedNames, cwd, reusePo
     let evaluated
     const activation = { id: entry.id, called: false, failed: false }
     try {
-      if (entry.durability === 'volatile') markVolatile(`user binding ${jsonStringify(entry.id)}: ${entry.volatileReason ?? 'non-replayable source'}`)
+      if (entry.durability === 'volatile') {
+        // Name the binding and its first cause instead of the whole reason list:
+        // the model reads this to decide what it can no longer redo.
+        const reasons = String(entry.volatileReason ?? 'non-replayable source').split(', ')
+        const more = reasons.length > 1 ? ` (+${reasons.length - 1} more)` : ''
+        markVolatile(`user binding ${jsonStringify(entry.id)} depends on ${reasons[0]}${more}`)
+      }
       evaluated = await userBindingActivationScope.run(activation, () => evaluateUserBinding(entry, cwd, snapshot.transform))
       const namespace = evaluated.namespace
       for (let symbolIndex = 0; symbolIndex < entry.symbols.length; symbolIndex += 1) {
@@ -1297,6 +1311,131 @@ function observeBindings(names) {
   }) }
 }
 
+/**
+ * The logical binding a committed root target names.
+ *
+ * A root target is `root:<sourceStart>:<name>` with an optional position suffix
+ * the compiler appends for a repeated name. Only the logical name exists on the
+ * recovery side, and it is the name the model reads, so the record keeps that
+ * instead of the compiler's internal target.
+ */
+function logicalBindingName(target) {
+  const match = /^root:\d+:([^:]+)/u.exec(target)
+  return match === null ? target : match[1]
+}
+
+/** Cap one recorded binding: 64 KiB of encoded wire. */
+const RECORDED_BINDING_WIRE_LIMIT = 64 * 1024
+/** Cap one settlement's recorded bindings: 1 MiB of encoded wire in total. */
+/** Cap the graph a recording pass may walk before the value becomes unrecorded. */
+const RECORDED_VALUE_NODES = 2048
+const RECORDED_VALUE_EDGES = 4096
+
+const RECORDED_CELL_WIRE_LIMIT = 1024 * 1024
+
+/**
+ * Encode the values a settlement produced.
+ *
+ * Every settlement records what it declared, durable or volatile: a durable
+ * cell still needs its values when recovery cannot replay it (a rewind moved
+ * the head past it, or the log proves it but the path does not reach it), and a
+ * volatile cell cannot be replayed at all. The record keeps values as wire so
+ * recovery installs them without running the cell again. Two caps keep the
+ * journal bounded: 64 KiB per binding and 1 MiB per settlement. A value over a
+ * cap, or one the codec cannot transfer, is reported by name instead of
+ * silently disappearing from the record.
+ */
+/**
+ * Whether recording one binding can be attempted without walking an unbounded
+ * value. The codec enumerates the value's own keys before it can apply any
+ * budget, and enumerating a graph with millions of keys exhausts a worker heap
+ * before a cap could reject it. So only shapes that are cheap to size are
+ * recorded: primitives, and arrays whose length is already known. A plain
+ * object, function or class instance is reported by name as unrecorded — its
+ * binding still exists in the journal's operations, but its value is not
+ * captured.
+ */
+function recordingAffordable(value) {
+  if (value === null) return true
+  const kind = typeof value
+  if (kind === 'number' || kind === 'string' || kind === 'boolean' || kind === 'bigint' || kind === 'undefined') return true
+  if (isArray(value)) return value.length <= RECORDED_VALUE_NODES
+  return false
+}
+
+function collectBindingValues(names, limits = {}) {
+  const values = []
+  const unrecorded = []
+  const seen = new Set()
+  let recorded = 0
+  for (const name of names) {
+    const logical = logicalBindingName(name)
+    if (setHas(seen, logical)) continue
+    const local = statefulRoots.localValue(name) ?? statefulRoots.localValue(logical)
+    if (local === undefined) {
+      setAdd(seen, logical)
+      unrecorded.push(logical)
+      continue
+    }
+    setAdd(seen, logical)
+    try {
+      // A recording pass must stay cheap. The codec starts by enumerating the
+      // value's own keys, so a huge declaration (millions of keys) would exhaust
+      // the worker heap before any budget check could reject it. Walk the value
+      // cheaply first — array length, or a `for…in` that stops after the cap
+      // without materializing keys — and record the name as unrecorded instead.
+      if (!recordingAffordable(local.value)) {
+        unrecorded.push(logical)
+        continue
+      }
+      const wire = encodeValue(local.value, {
+        ...limits,
+        maxNodes: min(limits.maxNodes ?? RECORDED_VALUE_NODES, RECORDED_VALUE_NODES),
+        maxEdges: min(limits.maxEdges ?? RECORDED_VALUE_EDGES, RECORDED_VALUE_EDGES),
+        maxArrayLength: min(limits.maxArrayLength ?? RECORDED_VALUE_NODES, RECORDED_VALUE_NODES),
+        maxStringBytes: min(limits.maxStringBytes ?? RECORDED_BINDING_WIRE_LIMIT, RECORDED_BINDING_WIRE_LIMIT),
+      })
+      const size = jsonStringify(wire).length
+      if (size > RECORDED_BINDING_WIRE_LIMIT || recorded + size > RECORDED_CELL_WIRE_LIMIT) {
+        unrecorded.push(logical)
+        continue
+      }
+      recorded += size
+      values.push({ name: logical, wire })
+    } catch {
+      unrecorded.push(logical)
+    }
+  }
+  return { values, unrecorded }
+}
+
+/**
+ * Install the values recovery recorded for a volatile cell.
+ *
+ * The worker never runs the restoration cell's source: each binding is decoded
+ * and committed directly, so an ambient read, a timer or a child process
+ * reached by the original cell is not dispatched a second time. A value the
+ * codec cannot decode is reported by name so recovery can say which binding it
+ * could not bring back.
+ */
+function restoreRecordedValues(message) {
+  const limits = message.valueLimits
+  const restored = []
+  const failed = []
+  for (const entry of message.values ?? []) {
+    const name = entry?.name
+    if (typeof name !== 'string' || name === '') continue
+    try {
+      const value = decodeValue(entry.wire, limits)
+      if (statefulRoots.restoreValue(name, value)) restored.push(name)
+      else failed.push({ name, reason: 'the store cannot publish a session identity for this name' })
+    } catch (error) {
+      failed.push({ name, reason: error instanceof Error ? error.message : String(error) })
+    }
+  }
+  return { restored, failed }
+}
+
 function refreshLegacyPublication(name) {
   const publications = activeExecution?.nativePublications
   const publication = publications === undefined ? undefined : mapGet(publications, name)
@@ -1334,12 +1473,16 @@ async function sendCompletion(message, execution, userBindings, committedRedecla
   // after this point is background output and carries the attribution
   // diagnostic instead of being attached to a later cell.
   execution.open = false
+  const bindingValues = collectBindingValues(committedRedeclarations, execution.valueLimits)
   channel.postMessage({
     type: 'done',
     id: message.id,
     outputFence: message.outputFence,
     logs: execution.logs,
     ...completionDurability(execution),
+    ...(bindingValues.values.length === 0 && bindingValues.unrecorded.length === 0
+      ? {}
+      : { bindingValues }),
     committedRedeclarations: setValuesArray(committedRedeclarations),
     ...(message.rootBindings === undefined ? {} : { rootBindingFacts: statefulRoots.facts() }),
     ...(perName ? { userBindingNames: normalizeUserBindingNames(mapArray(mapEntriesArray(userBindingSources), entry => ({
@@ -1398,6 +1541,11 @@ async function runCell(message) {
     volatileReason: message.volatileReason,
   }
   activeExecution = execution
+  // Compile-time evidence that a declaration's initializer is a bounded object
+  // literal, keyed by binding name. Settlement uses it to decide whether a value
+  // can be recorded without walking an object the codec cannot size; nothing
+  // reads it yet, so this commit changes no recording behaviour.
+  declaredBoundedLiterals = mapFromArray(message.declarationEvidence ?? [], entry => entry)
   const cellGlobals = []
   const committedRedeclarations = new Set()
 
@@ -1543,6 +1691,13 @@ channel.on('message', (message) => {
     channel.postMessage({ type: 'ready', id: message.id })
     return
   }
+  if (message?.type === 'restore') {
+    // Recovery installs the values a volatile cell recorded. No cell code runs
+    // here: replaying the source would redispatch the ambient effects that made
+    // the cell volatile, which is exactly what the record exists to avoid.
+    channel.postMessage({ type: 'restored', id: message.id, ...restoreRecordedValues(message) })
+    return
+  }
   if (message?.type === 'observe') {
     channel.postMessage({ type: 'observation-started', id: message.id })
     channel.postMessage({ type: 'observation', id: message.id,
@@ -1585,7 +1740,16 @@ try {
   await Promise.race([
     verifyEvaluation(),
     new Promise((_, reject) => {
-      startupTimer = setTimeout(() => reject(new Error('REPL settlement probe timed out')), 5000)
+      /* c8 ignore start -- the probe settles in microtasks, so the timer cannot win */
+      // `verifyEvaluation` dispatches its fixed sources through this realm's own
+      // evaluator, and every await it takes settles in a microtask (`throw`,
+      // `await Promise.reject`, a syntax rejection). A `setTimeout` is a macrotask,
+      // so it cannot run before those microtasks drain: the rejection below is
+      // unreachable for any input, and a bound of 1 ms still starts the worker.
+      startupTimer = setTimeout(() => reject(new Error(
+        `REPL settlement probe timed out after ${startupProbeMs}ms`,
+      )), startupProbeMs)
+      /* c8 ignore stop */
     }),
   ])
   replModuleRealm = (await evaluate('({Promise,stringify:value=>`${value}`,importModule:(source,options)=>import(source,options)})')).value

package/internal/legacy-cell-analysis.js

@@ -1,4 +1,5 @@
 /** Historical legacy-v1 lowering, retained from c51616c8d6c8:cell-analysis.js. */
+import { boundedLiteralEvidence } from './bounded-literal.js'
 import { ModuleRewriteError, rewriteModuleImportsExports } from './legacy-cell-rewriter.js'
 import { parseExecutableCell } from './legacy-cell-parser.js'
 import {
@@ -74,6 +75,7 @@ function topLevelDeclarations(body, variableRedeclarations = false) {
     if (statement.type === 'VariableDeclaration') {
       const definitionSpan = declarationSpan(statement)
       for (const declaration of statement.declarations) {
+        const first = declarations.length
         addPatternDeclarations(
           declaration.id,
           declarations,
@@ -81,6 +83,14 @@ function topLevelDeclarations(body, variableRedeclarations = false) {
           definitionSpan,
           statement.kind !== 'const' || variableRedeclarations,
         )
+        // A plain `const name = { … }` initializer proves its own size from the
+        // source, so recovery may record the value without walking it. A
+        // destructuring pattern has no single initializer to prove.
+        const evidence = declaration.id.type === 'Identifier' && declaration.init !== null
+          ? boundedLiteralEvidence(declaration.init) : undefined
+        if (evidence !== undefined) {
+          for (const record of declarations.slice(first)) record.boundedLiteral = evidence
+        }
       }
     } else if ((statement.type === 'FunctionDeclaration' || statement.type === 'ClassDeclaration')
       && statement.id !== null) {
@@ -408,6 +418,7 @@ function normalizePreparationOptions({
   importNamespaces = new Set(),
   writableBindings,
   moduleSemantics = LIVE_MODULE_SEMANTICS,
+  rewriteDescriptions,
 }) {
   if (typeof bindingPolicy === 'boolean') {
     bindingPolicy = {
@@ -435,7 +446,7 @@ function normalizePreparationOptions({
     throw new TypeError('ptc-plus: module semantics must define supported default-export and import-expression rules')
   }
   return { knownBindings, bindingPolicy, reservedBindings, rewritesEnabled,
-    importBindings, importNamespaces, writableBindings, moduleSemantics }
+    importBindings, importNamespaces, writableBindings, moduleSemantics, rewriteDescriptions }
 }
 
 function parseMappedCell(moduleRewrite, program) {
@@ -522,7 +533,7 @@ function classifyPrepared({ code, sourceMap }, program, knownBindings, moduleRew
 export function prepareLegacyProgram(program, options = {}) {
   if (typeof program !== 'string') throw new TypeError('ptc-plus: program must be a string')
   const { knownBindings, bindingPolicy, reservedBindings, rewritesEnabled,
-    importBindings, importNamespaces, writableBindings, moduleSemantics } = normalizePreparationOptions(options)
+    importBindings, importNamespaces, writableBindings, moduleSemantics, rewriteDescriptions } = normalizePreparationOptions(options)
   const unavailableGeneratedNames = new Set([
     ...knownBindings, ...reservedBindings, ...importBindings.keys(), ...importNamespaces,
   ])
@@ -561,6 +572,7 @@ export function prepareLegacyProgram(program, options = {}) {
     bindingPolicy,
     autoSplitRedeclarations: rewritesEnabled.autoSplitRedeclarations,
     commitSignal,
+    rewriteDescriptions,
   })
   const { executableCode, executableSourceMap, collisions, redeclared, rewrites } = convenience
   const commitTargets = new Set(moduleRewrite.commitTargets)

package/internal/legacy-repl-convenience.js

@@ -9,6 +9,18 @@ import {
 import { applySourceEdits, createMappedTextBuilder, identitySourceMap } from './source-position-map.js'
 import { SKIP_AST_CHILDREN, walkAst } from './ast-traversal.js'
 
+/**
+ * Historical descriptions, used when a caller supplies no resolved document.
+ *
+ * They are presentation only: no recognizer compares a rewrite description, so a
+ * customized description changes what the model reads and nothing else.
+ */
+const DEFAULT_DESCRIPTIONS = Object.freeze({
+  mixed: MIXED_REDECLARATION_REWRITE,
+  function: FUNCTION_REDECLARATION_REWRITE,
+  class: CLASS_REDECLARATION_REWRITE,
+})
+
 /**
  * Optional compatibility policy for a persistent REPL. The cell language does
  * not own this policy: callers may replace it when persistence uses separate
@@ -129,6 +141,7 @@ export function rewriteReplRedeclarations({
   bindingPolicy,
   autoSplitRedeclarations,
   commitSignal,
+  rewriteDescriptions = DEFAULT_DESCRIPTIONS,
 }) {
   const redeclared = []
   const rewrites = []
@@ -184,8 +197,8 @@ export function rewriteReplRedeclarations({
           rewrites.push({
             kind: 'redeclaration',
             description: kind === 'class'
-              ? CLASS_REDECLARATION_REWRITE
-              : FUNCTION_REDECLARATION_REWRITE,
+              ? rewriteDescriptions.class
+              : rewriteDescriptions.function,
             source: statement.id.name,
           })
         }
@@ -262,7 +275,7 @@ export function rewriteReplRedeclarations({
         redeclared.push(...existing.map(collisionFor))
         rewrites.push({
           kind: 'redeclaration',
-          description: MIXED_REDECLARATION_REWRITE,
+          description: rewriteDescriptions.mixed,
           source: existing.map(binding => binding.name).join(', '),
         })
       } else if (existing.length === bindings.length && bindings.length > 0) {

package/internal/official-repl-priority.js

@@ -1,27 +1,48 @@
 /**
  * Official persistent-REPL priority.
  *
- * The official `persistent-in-memory` execution mode is a live provider
- * capability, not a release fact: a provider reports `programFormat` `'repl'`
- * exactly when it retains a REPL per state owner. While the user selects the
- * official REPL priority and that provider is live, the plugin yields PTC
- * session execution to the official implementation and installs no session
- * runtime: `run_code`, its descriptors and its guidance stay official. The
- * decision is re-evaluated on every configuration change and host source
- * change, so either side can take over without restarting the host.
+ * The question is not which source form the official provider evaluates; it is
+ * whether that provider keeps a program environment alive per state owner. A
+ * host declares that fact as `retainsState`, and the answer decides who owns PTC
+ * session execution: while the user selects the official REPL priority and the
+ * live provider retains state, the plugin yields execution to the official
+ * implementation and installs no session runtime — `run_code`, its descriptors
+ * and its guidance stay official. Neither the source form nor a release
+ * identifier can answer it: one host line retains state for `script` programs and
+ * another runs the same `script` in a fresh process, and an earlier line could
+ * only report the REPL form at all. The decision is re-evaluated on every
+ * configuration change and host source change, so either side can take over
+ * without restarting the host.
  */
 
+/**
+ * Whether a live provider retains a program environment per state owner.
+ *
+ * A provider that reports `retainsState` answers directly, whatever source form
+ * it evaluates. A provider that predates that declaration leaks the same fact
+ * through its source form: only `repl` was retained, so a `script` or function
+ * body from that host is a fresh environment.
+ * @param {object} provider - the provider surface registered for the seam.
+ * @returns {boolean} true when the provider keeps state across runs per owner.
+ */
+export function providerRetainsState(provider) {
+  const reported = provider?.retainsState
+  if (typeof reported === 'boolean') return reported
+  // Without the declaration the source form is the only published evidence.
+  return provider?.programFormat === 'repl'
+}
+
 /**
  * Decide whether this configuration yields PTC session execution to the
  * official provider.
  * @param {object} config - resolved plugin configuration.
  * @param {object} provider - the live provider surface registered for the seam.
- * @returns {boolean} true when the official persistent REPL owns execution.
+ * @returns {boolean} true when the official provider owns execution.
  */
 export function defersToOfficialRepl(config, provider) {
   if (config?.officialReplPriority !== true) return false
   try {
-    return provider?.programFormat === 'repl'
+    return providerRetainsState(provider)
   } catch {
     // An unreadable capability descriptor cannot prove official ownership;
     // the plugin keeps its execution responsibility instead of guessing.

package/internal/program-bindings.js

@@ -175,6 +175,17 @@ export function capabilityFind(metadata, query) {
     .map(candidate => candidate.value)
 }
 
+/**
+ * Inspection answers "how do I call this", so it hands back the declaration the
+ * model programs against. The JSON schema is how the plugin stores a signature,
+ * not how anyone reads one; keeping it in the payload made the model parse JSON
+ * to learn a call shape the source already states.
+ */
+function inspectableMember(member) {
+  const { schema, ...rest } = member
+  return rest
+}
+
 /** Batch, budgeted inspection; omitted items remain explicit to the caller. */
 export function capabilityInspect(metadata, symbols = undefined, budget = 50) {
   if (!Number.isSafeInteger(budget) || budget < 1) throw new TypeError('ptc-plus: capability inspection budget must be a positive integer')
@@ -190,7 +201,7 @@ export function capabilityInspect(metadata, symbols = undefined, budget = 50) {
   const selected = requested.slice(0, budget).flatMap((symbol) => {
     const key = text(symbol, 'capability symbol')
     const found = bySymbol.get(key)
-    return found === undefined ? [] : [found]
+    return found === undefined ? [] : [inspectableMember(found)]
   })
   return {
     symbols: selected,

package/internal/projection-retention.js

@@ -0,0 +1,238 @@
+import { createHash } from 'node:crypto'
+
+/**
+ * Retention window for the host-only session-log projection.
+ *
+ * The projection is a fold shortcut, not the session log. Keeping the payload of
+ * every call would make a checkpoint proportional to how many bytes the session
+ * wrote (issue #10: a 77 MB state that the host cloned and pretty-printed until
+ * it aborted). The window is therefore bounded by default: the newest clusters
+ * keep their argument text so tips and the current edit target stay synchronous,
+ * and every older cluster keeps its identity, its observations and its call
+ * record while its payload text becomes a digest. Only a cluster beyond
+ * `retentionClusters` is folded into the chained summary, and a cluster whose
+ * payload alone exceeds the byte budget keeps its identity with a digested
+ * payload — the bound wins over the convenience of the hot cell, and the edit
+ * path refolds that cell from the session log.
+ *
+ * `retentionPayloadBytes` bounds the retained payload (the settlement and
+ * executable copies). A checkpoint additionally carries the selected run's
+ * copies, so its serialized total can approach roughly twice the budget plus the
+ * per-cluster metadata; that is the shipped bound, stated in ADR 0032.
+ *
+ * The environment overrides may only *lower* the window for tests; a value that
+ * would disable the bound is ignored so a deployment cannot silently return to
+ * an unbounded checkpoint.
+ */
+export const RETENTION_BOUNDS = Object.freeze({
+  runs: Object.freeze({ min: 8, max: 512 }),
+  bytes: Object.freeze({ min: 1024 * 1024, max: 16 * 1024 * 1024 }),
+  // 0 is the only unlimited spelling; a cluster cap of 0 means the count window
+  // never folds anything and only the payload budget bounds the checkpoint.
+  clusters: Object.freeze({ min: 0, max: 50000 }),
+})
+
+export const DEFAULT_RETENTION_LIMITS = Object.freeze({
+  runs: 8,
+  bytes: 8 * 1024 * 1024,
+  // The count window defaults to the payload window: cells beyond it fold into the
+  // chained summary instead of keeping a per-cluster record, which is what keeps a
+  // long session from growing linearly. A larger value keeps more recovery evidence
+  // without a log refold at the cost of a bigger checkpoint.
+  clusters: 8,
+})
+
+/**
+ * The environment levers exist for tests and for a deployment that wants a
+ * *smaller* window. They fill a field only when configuration leaves it absent
+ * and are clamped to the configured or default value, so no environment can
+ * widen the bound beyond what the settings say.
+ */
+const ENVIRONMENT_KEYS = Object.freeze({
+  runs: 'DSH_PTC_RETENTION_RUNS',
+  bytes: 'DSH_PTC_RETENTION_BYTES',
+  clusters: 'DSH_PTC_RETENTION_CLUSTERS',
+})
+
+function normalizeLimit(kind, raw, fallback) {
+  if (raw === undefined || raw === null || raw === '') return fallback
+  const value = Number(raw)
+  const { min, max } = RETENTION_BOUNDS[kind]
+  if (!Number.isFinite(value) || !Number.isInteger(value) || value < min || value > max) return fallback
+  // 0 means unlimited for clusters; every other value is clamped to the fallback
+  // so an environment lever can never widen the window past the configuration.
+  return kind === 'clusters' && value === 0 ? 0 : Math.min(value, fallback)
+}
+
+/**
+ * A configured window is honoured as written: it is the user's setting, bounded by
+ * `RETENTION_BOUNDS` only. The clamp in `normalizeLimit` exists for the environment
+ * lever, which may tighten a configured window but never widen it.
+ */
+function normalizeConfigured(kind, raw) {
+  if (raw === undefined || raw === null || raw === '') return DEFAULT_RETENTION_LIMITS[kind]
+  const value = Number(raw)
+  const { min, max } = RETENTION_BOUNDS[kind]
+  if (!Number.isFinite(value) || !Number.isInteger(value) || value < min || value > max) {
+    return DEFAULT_RETENTION_LIMITS[kind]
+  }
+  return value
+}
+
+let activeLimits = resolveRetentionLimits({})
+
+/** The limits the current fold prunes against. */
+export function retentionLimits() {
+  return activeLimits
+}
+
+/**
+ * Resolve the effective limits from plugin configuration: configuration wins,
+ * the environment fills an absent field, and anything invalid falls back to the
+ * default rather than to an unbounded checkpoint.
+ */
+export function resolveRetentionLimits(config = {}) {
+  const configured = {
+    runs: config.retentionPayloadRuns,
+    bytes: config.retentionPayloadBytes,
+    clusters: config.retentionClusters,
+  }
+  const resolved = {}
+  // The cluster window follows the payload window unless it is configured: a user
+  // who raises the retained cells expects the same number of cells to keep their
+  // cluster records, not eight of them.
+  if (configured.clusters === undefined || configured.clusters === null || configured.clusters === '') {
+    configured.clusters = normalizeConfigured('runs', configured.runs)
+  }
+  for (const kind of ['runs', 'bytes', 'clusters']) {
+    const base = normalizeConfigured(kind, configured[kind])
+    // The environment may only tighten the configured bound, never widen it.
+    resolved[kind] = normalizeLimit(kind, process.env[ENVIRONMENT_KEYS[kind]], base)
+  }
+  return Object.freeze(resolved)
+}
+
+/** Install the limits for the folds that follow; returns the previous ones. */
+export function configureRetention(config = {}) {
+  const previous = activeLimits
+  activeLimits = resolveRetentionLimits(config)
+  return previous
+}
+
+/** The count of clusters kept when the configuration folds by count. */
+export function retainedClusterCount(limits = activeLimits) {
+  if (limits.clusters === 0) return Number.POSITIVE_INFINITY
+  return Math.min(limits.runs, limits.clusters)
+}
+
+/** Shout when the retention window cannot hold the payload a consumer needs. */
+export const PRUNED_EDIT = '该单元格超出保留窗口，已不可编辑'
+export const PRUNED_EDIT_EN = 'This cell is outside the retention window and can no longer be edited'
+
+/**
+ * The checkpoint's summary and the session log disagree about a dropped cluster.
+ * Neither side may be used: the edit must be refused rather than applied to a cell
+ * the log and the checkpoint describe differently.
+ */
+export const PRUNED_SUMMARY_MISMATCH = '保留摘要与被重折的结算不一致'
+export const PRUNED_SUMMARY_MISMATCH_EN = 'Retention summary disagrees with the refolded settlement'
+
+/** The newest cell alone exceeded the byte budget and was dropped from the checkpoint. */
+export const HOT_CELL_DROPPED = '最新单元格超出保留预算，已从检查点移除'
+export const HOT_CELL_DROPPED_EN = 'The newest cell exceeded the retention budget and was removed from the checkpoint'
+
+export function digestOf(value) {
+  return createHash('sha256').update(JSON.stringify(value ?? null, (_key, field) => (
+    isPlainRecord(field) ? Object.fromEntries(Object.keys(field).sort().map(key => [key, field[key]])) : field
+  ))).digest('hex')
+}
+
+function isPlainRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+export function byteLength(value) {
+  if (typeof value === 'string') return Buffer.byteLength(value, 'utf8')
+  if (value === undefined || value === null) return 0
+  return Buffer.byteLength(JSON.stringify(value), 'utf8')
+}
+
+/**
+ * Identity of one settlement for the retention summary.
+ *
+ * A dropped settlement keeps three facts: its result position, its call position
+ * and the digest of the argument text the log still holds. Those three are exactly
+ * what a fold of the session log can reproduce, so the chain over them can be
+ * recomputed from the log; the normalized digest is recorded for diagnostics but
+ * stays out of the chain, because a settlement that was compacted earlier recorded
+ * only its payload digest rather than the normalized object itself.
+ */
+export function summaryEntry(settlement, resultSeq) {
+  return {
+    resultSeq,
+    callSeq: settlement?.call?.seq,
+    argumentsDigest: settlement?.call?.data?.argumentsDigest ?? digestOf(settlement?.call?.data?.arguments ?? null),
+    normalizedDigest: settlement?.normalized?.payloadDigest ?? digestOf(settlement?.normalized ?? null),
+  }
+}
+
+/** The part of an entry the chain commits to: reproducible from the log alone. */
+function chainEntry(entry) {
+  return { callSeq: entry.callSeq, resultSeq: entry.resultSeq, argumentsDigest: entry.argumentsDigest }
+}
+
+const EMPTY_CHAIN = digestOf(null)
+
+/**
+ * Extend a chained retention summary with the settlements it just dropped.
+ *
+ * The summary keeps one compact record per dropped cluster rather than only a
+ * rolling digest. Admission receives no session log, so it cannot recompute the
+ * chain from the events; what it can do is prove the summary is internally
+ * consistent (count, ranges, chain over the stored records). The record itself is
+ * what makes the later guarantee possible: when a dropped settlement is refolded
+ * from the log, its digests are compared against the stored record and a mismatch
+ * is reported instead of being used.
+ */
+export function extendSummary(previous, entries) {
+  if (entries.length === 0) return previous
+  const records = [...(previous?.entries ?? [])]
+  let chain = previous?.chainDigest ?? EMPTY_CHAIN
+  let count = previous?.count ?? 0
+  let fromSeq = previous?.fromSeq
+  let toSeq = previous?.toSeq
+  for (const entry of entries) {
+    const record = chainEntry(entry)
+    records.push(record)
+    chain = digestOf({ chain, entry: record })
+    count += 1
+    fromSeq = fromSeq === undefined ? entry.resultSeq : Math.min(fromSeq, entry.resultSeq)
+    toSeq = toSeq === undefined ? entry.resultSeq : Math.max(toSeq, entry.resultSeq)
+  }
+  records.sort((left, right) => left.resultSeq - right.resultSeq)
+  return { fromSeq, toSeq, count, chainDigest: chain, entries: records }
+}
+
+/** Recompute the chain committed by a summary's own records. */
+export function chainOfEntries(records) {
+  let chain = EMPTY_CHAIN
+  for (const record of records) chain = digestOf({ chain, entry: { callSeq: record.callSeq, resultSeq: record.resultSeq, argumentsDigest: record.argumentsDigest } })
+  return chain
+}
+
+/** The record a dropped cluster must match when it is refolded from the log. */
+export function summaryRecordOf(summary, resultSeq) {
+  if (!isPlainRecord(summary) || !Array.isArray(summary.entries)) return undefined
+  return summary.entries.find(record => record?.resultSeq === resultSeq)
+}
+
+/** Payload bytes a settlement still retains, used to decide pruning. */
+export function settlementBytes(settlement) {
+  let bytes = 0
+  const args = settlement?.call?.data?.arguments
+  if (typeof args === 'string') bytes += byteLength(args)
+  const normalized = settlement?.normalized
+  if (normalized !== undefined) bytes += byteLength(normalized)
+  if (settlement?.publication !== undefined) bytes += byteLength(settlement.publication)
+  return bytes
+}