dsh-ptc-plus 0.5.0 → 0.5.2

package/internal/isolated-worker.js

@@ -5,14 +5,46 @@ import { PassThrough } from 'node:stream'
 import { pathToFileURL } from 'node:url'
 import { helperProcessEnvironment, isElectronHost } from './worker-environment.js'
 
+/**
+ * Bound on the wait for one on-demand utilization answer.
+ *
+ * The helper answers by reading the inner worker's counters synchronously, so
+ * this bound covers delivery rather than helper work. It is deliberately not
+ * the shutdown release grace below: how long a stopping helper may keep running
+ * must not decide how long a cell waits for its measurement.
+ */
+export const ISOLATED_SAMPLE_MS = 1000
+/**
+ * Sampling failure code for a sample whose answer this transport could not
+ * observe. The transport reports only that fact: whether the worker stays usable
+ * belongs to the caller, which alone knows how many consecutive measurements it
+ * may lose before the worker has to be replaced.
+ */
+export const UNANSWERED_SAMPLE_CODE = 'ptc-sample-unanswered'
+/**
+ * Helper messages one sample may read out before it gives up on the answer.
+ *
+ * Reading stops at the first event-loop turn that delivers nothing, so this
+ * bound only ends a backlog larger than the bound itself, where the answer
+ * cannot be reached by reading until the channel empties.
+ */
+const SAMPLE_DRAIN_TURNS = 4096
 /**
  * Fallback bound for a helper that answers the stop request and then keeps the
  * process alive with unrelated work of its own.
  */
 const ISOLATED_RELEASE_MS = 1000
-/** Absolute bound after which an unresponsive helper is killed. */
+/**
+ * Default bound for each close stage of one helper and the transport default.
+ *
+ * Exit confirmation and the output close that follows are each bounded by it;
+ * the fixed release grace is capped so the bound still leaves a confirmation
+ * window for the kill. A transport instance carries a configurable
+ * `reclaimBoundMs`, and the close path reads that instance bound instead of
+ * this default.
+ */
 const ISOLATED_STOP_MS = 5000
-/** Bound on the helper's output pipes really ending after its process exited. */
+/** Default bound on the helper's output pipes really ending after its process exited. */
 const ISOLATED_OUTPUT_MS = 5000
 
 export function isolatedWorkerEntry(entry) {
@@ -36,7 +68,7 @@ export function isolatedWorkerEntry(entry) {
  * so a kernel that never answers is reclaimed without ending the host.
  */
 export class IsolatedWorker extends EventEmitter {
-  constructor({ helper, entry, workerData, resourceLimits, env, protocol = 'kernel' }) {
+  constructor({ helper, entry, workerData, resourceLimits, env, protocol = 'kernel', reclaimBoundMs = ISOLATED_STOP_MS }) {
     super()
     // The entry follows the worker constructor's contract: a URL or a string
     // filename. Anything else fails here, before a helper process exists.
@@ -58,6 +90,29 @@ export class IsolatedWorker extends EventEmitter {
     this.utilization = { idle: 0, active: 0 }
     this.utilizationSequence = 0
     this.utilizationRequests = new Map()
+    /**
+     * Count of messages this helper has produced.
+     *
+     * Reading a sample uses it to tell one event-loop turn that delivered
+     * something from one that delivered nothing; the count says nothing about
+     * when the helper wrote a message.
+     */
+    this.helperMessages = 0
+    /**
+     * Bound this instance waits for one utilization answer.
+     *
+     * It is read per request, so a transport user may shorten or extend the wait
+     * for its own environment without changing the shutdown release grace.
+     */
+    this.sampleBoundMs = ISOLATED_SAMPLE_MS
+    /**
+     * Bound this instance's close path waits for the killed helper to be
+     * confirmed gone and for its output pipes to end.
+     *
+     * It is read when the close starts, so a transport user may widen the wait
+     * for its own platform without changing the release grace.
+     */
+    this.reclaimBoundMs = reclaimBoundMs
     this.pendingErrors = []
     this.performance = {
       /** Utilization reported by the helper, in the shape callers already use. */
@@ -124,6 +179,7 @@ export class IsolatedWorker extends EventEmitter {
       }
     })
     this.child.on('message', message => {
+      this.helperMessages += 1
       if (message?.type === 'child-error') {
         const error = new Error(message.message)
         if (message.name !== undefined) error.name = message.name
@@ -139,11 +195,14 @@ export class IsolatedWorker extends EventEmitter {
       }
       if (message?.type === 'inner-worker-exit') { this.emit('inner-worker-exit', message.code); return }
       if (message?.type === 'utilization-sample') {
+        // An answer for a request this transport already concluded is still the
+        // helper doing its work: keep the freshest value it reported.
+        this.utilization = message.utilization
         const pending = this.utilizationRequests.get(message.id)
         if (pending !== undefined) {
           this.utilizationRequests.delete(message.id)
           clearTimeout(pending.timer)
-          this.utilization = message.utilization
+          if (pending.decision !== undefined) clearImmediate(pending.decision)
           pending.resolve(message.utilization)
         }
         return
@@ -225,25 +284,81 @@ export class IsolatedWorker extends EventEmitter {
     }
     const id = ++this.utilizationSequence
     return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
-        this.utilizationRequests.delete(id)
-        reject(new Error('kernel helper did not answer utilization sampling before its deadline'))
-      }, ISOLATED_RELEASE_MS)
-      this.utilizationRequests.set(id, { resolve, reject, timer })
+      const pending = { resolve, reject, timer: undefined, decision: undefined }
+      pending.timer = setTimeout(() => {
+        // A blocked host runs its expired timers before it reads its IPC pipe, so
+        // the answer may be waiting unread here. Read the channel out first and
+        // only then conclude that no answer exists.
+        pending.decision = setImmediate(() => this.#readOutSample(id, pending))
+      }, this.sampleBoundMs)
+      this.utilizationRequests.set(id, pending)
       try {
         this.child.send({ type: 'sample-utilization', id })
       } catch (error) {
-        clearTimeout(timer)
+        clearTimeout(pending.timer)
         this.utilizationRequests.delete(id)
         reject(error)
       }
     })
   }
 
+  /**
+   * Read the helper's channel out before one unanswered sample is concluded.
+   *
+   * Node delivers one helper message per event-loop turn, and the answer this
+   * request waits for is written after everything the helper wrote before it, so
+   * it can sit behind queued messages. Each turn therefore either delivers the
+   * answer or another message the helper wrote; only a turn that delivers no
+   * message shows that the channel holds nothing more this read could observe.
+   *
+   * A message the parser still holds in parts is not delivered on any of those
+   * turns, so a partially received message ahead of the answer delays it past
+   * this read-out; the sample then reports no answer, which is all this
+   * transport can prove about it.
+   */
+  #readOutSample(id, pending) {
+    let delivered = this.helperMessages
+    let turns = 0
+    const turn = () => {
+      if (this.utilizationRequests.get(id) !== pending) return
+      if (turns >= SAMPLE_DRAIN_TURNS) {
+        this.utilizationRequests.delete(id)
+        pending.decision = undefined
+        pending.reject(this.#unansweredSample('backlog'))
+        return
+      }
+      if (this.helperMessages === delivered) {
+        this.utilizationRequests.delete(id)
+        pending.decision = undefined
+        pending.reject(this.#unansweredSample('silent-channel'))
+        return
+      }
+      delivered = this.helperMessages
+      turns += 1
+      pending.decision = setImmediate(turn)
+    }
+    pending.decision = setImmediate(turn)
+  }
+
+  /**
+   * Report one sample whose answer this transport could not observe.
+   *
+   * The transport states the observation only. Whether the caller keeps its
+   * worker is decided where the consecutive measurement failures are counted.
+   */
+  #unansweredSample(reason) {
+    const error = new Error(reason === 'backlog'
+      ? `kernel helper wrote at least ${SAMPLE_DRAIN_TURNS} messages ahead of this utilization sample, so its answer could not be reached before the read-out bound`
+      : 'kernel helper did not answer utilization sampling before its deadline')
+    error.code = UNANSWERED_SAMPLE_CODE
+    return error
+  }
+
   /** Fail every request that still needs the helper's utilization answer. */
   #rejectUtilizationRequests(error) {
     for (const pending of this.utilizationRequests.values()) {
       clearTimeout(pending.timer)
+      if (pending.decision !== undefined) clearImmediate(pending.decision)
       pending.reject(error)
     }
     this.utilizationRequests.clear()
@@ -268,12 +383,14 @@ export class IsolatedWorker extends EventEmitter {
 
   async #stop() {
     if (this.exited) return
-    // Both cutoffs are anchored at the moment the close starts: an acknowledgement
-    // never postpones the kill, and a kill still leaves a positive bounded window
-    // for the helper's real exit to arrive.
+    // The configured bound is this close's exit-confirmation deadline, anchored
+    // at the close start so an acknowledgement never postpones the kill. The
+    // fixed release grace is capped to leave a grace-sized confirmation window
+    // for the kill, so a bound at or just above the grace is never consumed
+    // before the kill; the output pipes then get the same bound from their exit.
     const started = Date.now()
-    const killAt = started + ISOLATED_RELEASE_MS
-    const confirmBy = started + ISOLATED_STOP_MS
+    const confirmBy = started + this.reclaimBoundMs
+    const releaseAt = started + Math.min(ISOLATED_RELEASE_MS, Math.max(0, this.reclaimBoundMs - ISOLATED_RELEASE_MS))
     const exited = this.exitedPromise
     const onReleased = message => {
       if (message?.type === 'worker-message' && message.value?.type === 'shutdown-released') this.released = true
@@ -287,7 +404,7 @@ export class IsolatedWorker extends EventEmitter {
       } catch {
         // The channel is closed; the kill path below owns the instance.
       }
-      if (!await leftWithin(this, remaining(killAt))) {
+      if (!await leftWithin(this, remaining(releaseAt))) {
         let killFailure
         if (!this.exited) {
           try {
@@ -410,7 +527,7 @@ export class IsolatedOwner {
     // synchronously finish or throw and clear the marker for a later retry.
     const settling = Promise.resolve().then(async () => {
       if (record.neverStarted !== true && record.transport !== undefined) {
-        const closed = await outputClosed(record.transport, ISOLATED_OUTPUT_MS)
+        const closed = await outputClosed(record.transport, record.transport?.reclaimBoundMs ?? ISOLATED_OUTPUT_MS)
         if (!closed) {
           // Output never drained: keep the instance and say so instead of
           // pretending the pipes ended naturally.

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

@@ -0,0 +1,51 @@
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+export function defersToOfficialRepl(config, provider) {
+  if (config?.officialReplPriority !== true) return false
+  try {
+    return provider?.programFormat === 'repl'
+  } catch {
+    // An unreadable capability descriptor cannot prove official ownership;
+    // the plugin keeps its execution responsibility instead of guessing.
+    return false
+  }
+}
+
+/**
+ * Runtime record for an attachment that yields execution to the official
+ * provider. It owns no execution resources: the official provider releases
+ * anything it retained through its own lifecycle, and the plugin's settings,
+ * storage and UI owners remain available so the user can switch back.
+ */
+export function createDeferredRuntime() {
+  return Object.freeze({
+    cancelCordisActivation() {
+      // No Cordis companion is installed while execution is deferred.
+    },
+    contextsForRequest: () => [],
+    async reconfigure() {
+      // This attachment has no owners to reconfigure.
+    },
+    async dispose() {
+      // Nothing is owned here; disposal returns immediately.
+    },
+  })
+}