dsh-ptc-plus 0.3.2 → 0.4.2

package/internal/session-cell-executor.js

@@ -2,12 +2,15 @@ import {
   decodeValue,
   encodeValue,
   normalizeValueWire,
-  projectValueWire,
+  prepareValueWire,
   valueWiresEqual,
 } from './value-wire.js'
 import { diagnostic, renderDiagnostic } from './diagnostic.js'
+import { normalizeBindingDescriptors } from './binding-descriptors.js'
 import {
   firstLine,
+  cellPosition,
+  exceptionOriginPosition,
   limitLogs,
   LONG_CELL_CODE_UNITS,
   markBindingFailure,
@@ -16,15 +19,22 @@ import {
   oneLineMessage,
   safeProperty,
 } from './failure-reporting.js'
-import { assertStateName } from './session-journal.js'
-import { PreflightError, prepareProgram } from './cell-analysis.js'
-import { LIVE_DEFAULT_EXPORT_BINDING } from './repl-rewrite-contract.js'
-import { ModuleRewriteError } from './cell-rewriter.js'
+import { assertStateName, LIVE_USER_BINDINGS_REUSE_POLICY } from './session-journal.js'
+import { LIVE_USER_BINDINGS_SHADOW_POLICY, normalizeUserBindingNames } from './session-journal-schema.js'
+import { PreflightError, prepareProgram } from './compiler-service.js'
+import { executionPolicies } from './binding-update-policy.js'
+import { createReplMemorySnapshot } from './repl-memory-projection.js'
+import { ModuleRewriteError } from './cell-error.js'
 import { mapSourcePosition } from './source-position-map.js'
 import { durabilityState, transitionDurability } from './session-state.js'
+import { dynamicBindingOrigin } from './dynamic-binding-evidence.js'
 import { validatedEofClosureRepair } from './validated-parse-repair.js'
+import {
+  normalizeUserBindingsSnapshot,
+  selectUserBindingsSnapshot,
+} from './user-bindings.js'
 
-const OUTPUT_LIMIT_MESSAGE = bytes => `output exceeded ${bytes} bytes; reduce the returned value or keep it in a REPL binding`
+const OUTPUT_LIMIT_MESSAGE = bytes => `output exceeded ${bytes} bytes; this cell was discarded and the worker reset. Only bindings in the verified recovery frontier can be restored. External effects may already have occurred and are not undone. For future cells, bound console output and return a smaller value; do not assume this cell's values remain available.`
 
 function earlyResult(kind, message) {
   return { logs: [], error: { kind, message } }
@@ -52,16 +62,15 @@ function isBindingReferenceError(error) {
       || /Cannot access ['"][^'"]+['"] before initialization/.test(error.message))
 }
 
+/**
+ * Parse failures carry original cell coordinates in ModuleRewriteError.cellPosition; the rewriter
+ * owns any generated-source mapping, so the executor never re-applies wrapper offsets.
+ */
 function parseCellPosition(error) {
   const cellPosition = error instanceof ModuleRewriteError ? error.cellPosition : undefined
-  const line = Number.isSafeInteger(cellPosition?.line)
-    ? cellPosition.line
-    : Number.isSafeInteger(error?.loc?.line) ? error.loc.line - 1 : undefined
-  const column = Number.isSafeInteger(cellPosition?.column)
-    ? cellPosition.column
-    : Number.isSafeInteger(error?.loc?.column) ? error.loc.column + 1 : undefined
-  return line !== undefined && line >= 1 && column !== undefined
-    ? { line, column }
+  return Number.isSafeInteger(cellPosition?.line) && cellPosition.line >= 1
+    && Number.isSafeInteger(cellPosition?.column) && cellPosition.column >= 1
+    ? { line: cellPosition.line, column: cellPosition.column }
     : undefined
 }
 
@@ -81,7 +90,7 @@ function parseDiagnostic(error, source, position, repair) {
         : ['this cell was not executed; correct the reported syntax and retry only this cell with run_code']
       : [
           `this cell was not executed; validated syntax repair: append ${JSON.stringify(repair.delimiter)} at the end of this cell`,
-          `when edit_run_code is declared for the current request, call ${repair.invocation} to apply this correction and rerun the cell; otherwise retry only this cell with the corrected source in run_code`,
+          `when this correction matches your intent and edit_run_code is declared, prefer the direct tool call ${repair.invocation} with its target guard to run the complete corrected cell; validation proves syntax/preflight acceptance, not intended behavior; otherwise submit corrected source in run_code`,
         ],
   })
 }
@@ -121,6 +130,106 @@ function committedRedeclarationSet(message, prepared) {
   return committed
 }
 
+/** Accept value-free worker facts only for this compilation's logical root. */
+function completedRootBindingFacts(message, prepared, committed) {
+  if (prepared.rootRuntimeName === undefined && prepared.rootBindingFacts !== true) return undefined
+  if (!Array.isArray(message.rootBindingFacts)) throw new TypeError('kernel returned invalid root binding facts')
+  const established = new Map(prepared.rootBindings.established)
+  const initialized = new Set(prepared.declarations.filter(declaration => committed.has(declaration.commitDependency)
+    && (prepared.languageSemantics !== 'legacy-v1' || established.has(declaration.name)))
+    .map(declaration => declaration.name))
+  const candidates = new Map(prepared.rootBindings.candidates)
+  const dynamicOrigins = new Set(prepared.rootBindings.dynamicOrigins)
+  const available = new Set([...prepared.rootBindings.known, ...established.keys(), ...initialized])
+  const allowed = new Set([...available, ...candidates.values()])
+  const required = new Set([...established.keys(), ...initialized])
+  const imports = new Set([...prepared.rootBindings.legacyImports.map(([name]) => name),
+    ...[...established].filter(([, source]) => source === 'import').map(([name]) => name),
+    ...prepared.declarations.filter(declaration => declaration.kind === 'import' && committed.has(declaration.commitDependency))
+      .map(declaration => declaration.name)])
+  const seen = new Set()
+  const facts = message.rootBindingFacts.map(fact => {
+    const dynamicOrigin = dynamicBindingOrigin(fact?.write, fact?.name, dynamicOrigins)
+    if (fact === null || typeof fact !== 'object' || Array.isArray(fact)
+      || Object.keys(fact).length !== (Object.hasOwn(fact, 'write') ? 3 : 2)
+      || !Object.hasOwn(fact, 'name') || !Object.hasOwn(fact, 'source')
+      || typeof fact.name !== 'string' || !allowed.has(fact.name) && dynamicOrigin === undefined || seen.has(fact.name)
+      || !['local', 'import', 'absent'].includes(fact.source)
+      || Object.hasOwn(fact, 'write') && (typeof fact.write !== 'string'
+        || candidates.get(fact.write) !== fact.name && dynamicOrigin === undefined || fact.source === 'import')
+      || !available.has(fact.name) && !Object.hasOwn(fact, 'write')
+      || fact.source === 'import' && !imports.has(fact.name)
+      || fact.source === 'absent' && initialized.has(fact.name)) throw new TypeError('kernel returned invalid root binding facts')
+    seen.add(fact.name)
+    required.delete(fact.name)
+    return { name: fact.name, source: fact.source, ...(Object.hasOwn(fact, 'write') ? { write: fact.write } : {}) }
+  })
+  if (required.size !== 0) throw new TypeError('kernel returned incomplete root binding facts')
+  return facts
+}
+
+function completedUserBindingNames(active, message, snapshot) {
+  const facts = normalizeUserBindingNames(message.userBindingNames)
+  const required = active.userBindingBaseCatalog.userBindingNameSet(snapshot)
+  const allowed = active.userBindingBaseCatalog.userBindingNameSet(snapshot, true)
+  const providers = new Map((snapshot?.entries ?? []).flatMap(entry => (
+    (entry.scope === 'namespace' ? [entry.name] : entry.symbols).map(name => [name, entry.id])
+  )))
+  for (const fact of facts) {
+    if (!allowed.has(fact.name) || (fact.state === 'provider'
+      && (providers.get(fact.name) !== fact.entryId || active.request.bindingDescriptors.reservedNames.has(fact.name)))) {
+      throw new TypeError('kernel returned user binding name evidence with invalid ownership')
+    }
+    required.delete(fact.name)
+  }
+  if (required.size !== 0) throw new TypeError('kernel returned incomplete user binding name evidence')
+  if (active.replay !== undefined && JSON.stringify(facts) !== JSON.stringify(active.replay.userBindingNames)) {
+    throw new TypeError('cell replay produced different user binding name evidence')
+  }
+  return facts
+}
+
+function validateUserBindingActivation(active, message, ids) {
+  if (!Array.isArray(message.userBindingFailures)) throw new TypeError('kernel returned invalid user binding failures')
+  const expected = new Set(active.userBindings.entries.map(entry => entry.id))
+  for (const id of ids) expected.delete(id)
+  for (const failure of message.userBindingFailures) {
+    if (failure === null || typeof failure !== 'object' || Object.keys(failure).length !== 2
+      || typeof failure.error !== 'string' || !expected.delete(failure.id)) {
+      throw new TypeError('kernel returned invalid user binding failures')
+    }
+  }
+  if (expected.size !== 0) throw new TypeError('kernel omitted user binding activation outcomes')
+  if ([...ids].some(id => active.userBindingFailures.some(failure => failure.id === id))) {
+    throw new TypeError('kernel activated a request-owned user binding name')
+  }
+}
+
+/** A reserved program binding (`tools` and the injected error classes) is not shadowable at the
+ * session root, so a collision on it is not a repeated declaration. The collision producer records
+ * that reason, and rendering the recorded reason keeps "top-level bindings already exist" from
+ * implying the cell redeclared a name the session never created. */
+const RESERVED_BINDING_REASON = 'reserved-program-binding-not-shadowable'
+/** Reasons whose only remaining guidance is to reuse the binding already in session state. */
+const REUSE_BINDING_REASONS = new Set([
+  'variable-redeclarations-disabled', 'redeclaration-splitting-disabled', 'protected-root-redeclaration',
+  'import-binding-redeclaration', RESERVED_BINDING_REASON,
+])
+
+function reservedBindingNote(collisions) {
+  const reserved = [...new Set(collisions.filter(collision => collision.reason === RESERVED_BINDING_REASON)
+    .map(collision => collision.name))]
+  return reserved.length === 0
+    ? ''
+    : ` ${reserved.join(', ')} cannot be redeclared or overwritten because reserved program bindings are not shadowable.`
+}
+
+/** The model-visible structured form of every recorded collision, reduced to public fields. */
+function collisionRecords(collisions) {
+  return collisions.map(collision => ({ name: collision.name, kind: collision.kind,
+    reason: collision.reason, start: collision.start, end: collision.end }))
+}
+
 function collisionDiagnostic(collisions) {
   const names = [...new Set(collisions.map(item => item.name))]
   const reasons = new Set(collisions.map(item => item.reason).filter(Boolean))
@@ -136,7 +245,7 @@ function collisionDiagnostic(collisions) {
         : disabledKinds.has('class')
           ? ['assign a class expression to the existing writable binding']
           : []),
-    ...((reasons.size === 0 || reasons.has('variable-redeclarations-disabled'))
+    ...((reasons.size === 0 || [...reasons].some(reason => REUSE_BINDING_REASONS.has(reason)))
       ? ['reuse the existing bindings']
       : []),
   ]
@@ -147,14 +256,16 @@ function collisionDiagnostic(collisions) {
     ...(alternatives.length === 0 ? [] : [alternatives.join('; ')]),
     'place one-off declarations inside a block',
   ]
+  const reservedNote = reservedBindingNote(collisions)
   return diagnostic({
     code: 'PTC-N001',
     severity: 'error',
     phase: 'preflight',
-    message: `top-level bindings already exist: ${names.join(', ')}. This cell was not executed; the REPL state is unchanged.`,
+    message: `top-level bindings already exist: ${names.join(', ')}.${reservedNote} This cell was not executed; the REPL state is unchanged.`,
     stateEffect: 'unchanged',
     source: { cell: 'current', start: first.start, end: first.end },
     help,
+    collisions: collisionRecords(collisions),
   })
 }
 
@@ -164,6 +275,8 @@ function exceptionDiagnostic({
   position,
   declared,
   longCellFailure = false,
+  failureOrigin,
+  languageSemantics = 'legacy-v1',
 }) {
   const missingPath = error.name === 'ToolCallError' ? missingDescriptionPath(error) : undefined
   const missingDescription = missingPath !== undefined
@@ -188,20 +301,24 @@ function exceptionDiagnostic({
     ...(cause === undefined ? {} : { cause }),
     ...(source === undefined ? {} : { source }),
     help: [
-      ...(missingDescription
-        ? ['add a string `description` property to the nested native-tool argument object']
-        : ['inspect existing bindings and retry only the failing expression']),
+      'earlier statements or the failing operation may have caused effects; choose continuation using the operation owner\'s retry/idempotence contract and available execution facts; a thrown call or recorded-value replay does not prove a live retry is safe',
+      ...(failureOrigin === 'lease'
+        ? ['this REPL-captured capability reference belongs to an ended cell; obtain the member from the current program namespace, and have retained helpers resolve it at invocation']
+        : failureOrigin === 'capability'
+          ? ['inspect the current capability with capabilities.tree(), capabilities.find(), or capabilities.inspect(); availability may have changed']
+          : missingDescription
+            ? ['add a string `description` property to the nested native-tool argument object']
+            : []),
       ...(error.name === 'ToolCallError'
         && typeof error.toolName === 'string'
         && error.toolName.startsWith('cordis_')
         ? ['bindings assigned before this Cordis failure remain live; reuse them instead of resending large source']
-        : []),
-      ...(longCellFailure
-        ? ['execution may have occurred; inspect live state in a new short `run_code` cell before deciding whether a correction is safe']
-        : []),
-      ...(declared.size === 0 || longCellFailure
-        ? []
-        : ['use fresh names for one-off top-level bindings after partial execution; later declarations may be uninitialized']),
+        : longCellFailure
+          ? ['inspect relevant live state in a new short `run_code` cell; edit_run_code executes the complete corrected cell, not only the failing expression']
+          : languageSemantics !== 'legacy-v1'
+            ? ['completed declarations and actual assignments remain available; correct the failed initializer and continue with the same binding names']
+          : declared.size === 0 ? []
+            : ['use fresh names for one-off top-level bindings after partial execution; later declarations may be uninitialized']),
     ],
   })
 }
@@ -214,12 +331,18 @@ function invalidOutputDiagnostic(detail) {
     message: `cell result could not cross the PTC Value V1 boundary: ${firstLine(detail, 'unknown output encoding failure')}`,
     stateEffect: 'partially-applied',
     help: [
-      'return a PTC Value V1 value or keep the live value in a REPL binding',
+      'the worker remains live; inspect a retained binding in a later cell without rerunning the failed cell',
       'reduce the returned graph when it exceeds the configured value budget',
     ],
   })
 }
 
+/** Retain validated recorded wording while still comparing the actual failure. */
+function replayFailureDiagnostic(actual, replay) {
+  const recorded = replay?.diagnostics?.find(item => item.code === actual.code)
+  return recorded?.message === actual.message ? recorded : actual
+}
+
 function stateArguments(value) {
   if (value === null || typeof value !== 'object' || Array.isArray(value)) {
     throw new TypeError('repl.state expects an object')
@@ -253,30 +376,61 @@ export class SessionCellExecutor {
       return result
     }
 
-    const catalog = kernel.bindingCatalog.inputs()
-    const bindingPolicy = replayRecord === undefined ? {
-      variableRedeclarations: config.looseTopLevelRedeclarations,
-      functionClassRedeclarations: config.looseTopLevelFunctionClassRedeclarations,
-    } : replayRecord.bindingPolicy
-    const rewritesEnabled = replayRecord === undefined ? {
-      autoRewriteImports: config.autoRewriteImports,
-      autoStripExports: config.autoStripExports,
-      autoSplitRedeclarations: config.autoSplitRedeclarations,
-    } : replayRecord.rewritePolicy
-    const moduleSemantics = replayRecord === undefined ? {
-      defaultExportBinding: LIVE_DEFAULT_EXPORT_BINDING,
-    } : replayRecord.moduleSemantics
-    const prepareCell = program => prepareProgram(
-      program,
-      catalog.knownBindings,
+    let userBindings
+    const userBindingsShadowPolicy = replayRecord?.userBindingsShadowPolicy ?? LIVE_USER_BINDINGS_SHADOW_POLICY
+    const perNameUserBindings = userBindingsShadowPolicy === LIVE_USER_BINDINGS_SHADOW_POLICY
+    let userBindingBaseCatalog = kernel.bindingCatalog
+    let userBindingPlan
+    let userBindingFailures = []
+    try {
+      userBindings = request.userBindings === undefined
+        ? undefined
+        : normalizeUserBindingsSnapshot(request.userBindings)
+      if (userBindings === undefined) {
+        const catalog = kernel.bindingCatalog.withoutUserBindings()
+        userBindingPlan = perNameUserBindings ? kernel.bindingCatalog.userBindings(undefined, undefined, userBindingsShadowPolicy) : {
+          catalog,
+          shadowedNames: catalog.inputs().knownBindings,
+        }
+      } else {
+        const activeEntryIds = new Set()
+        for (const entry of userBindings.entries) {
+          const names = entry.scope === 'namespace' ? [entry.name] : entry.symbols
+          const conflict = names.find(name => request.bindingDescriptors.reservedNames.has(name))
+          if (conflict === undefined) activeEntryIds.add(entry.id)
+          else {
+            userBindingFailures.push(Object.freeze({
+              id: entry.id,
+              error: `conflicts with request-owned program binding ${JSON.stringify(conflict)}`,
+            }))
+          }
+        }
+        userBindingPlan = kernel.bindingCatalog.userBindings(userBindings, activeEntryIds, userBindingsShadowPolicy)
+      }
+    } catch (error) {
+      const result = earlyResult('exception', `invalid user binding snapshot: ${messageOf(error)}`)
+      kernel.completeJournal(request.journal, 'noop', result)
+      return result
+    }
+    const priorBindingCatalog = userBindingPlan.catalog
+    const catalog = priorBindingCatalog.inputs()
+    const { bindingPolicy, rewritesEnabled, moduleSemantics, languageSemantics, moduleTransform } = executionPolicies(config, replayRecord)
+    const prepareCell = program => prepareProgram(program, {
+      knownBindings: catalog.knownBindings,
       bindingPolicy,
-      request.bindingDescriptors.reservedNames,
+      languageSemantics,
+      reservedBindings: request.bindingDescriptors.reservedNames,
       rewritesEnabled,
-      catalog.importBindings,
-      catalog.importNamespaces,
-      catalog.writableBindings,
+      importBindings: catalog.importBindings,
+      importNamespaces: catalog.importNamespaces,
+      writableBindings: catalog.writableBindings,
+      nativeBindings: catalog.nativeBindings,
+      nativeLexicalBindings: catalog.nativeLexicalBindings,
+      rootCandidates: catalog.rootCandidates,
+      dynamicOrigins: catalog.dynamicOrigins,
+      establishedRoots: catalog.establishedRoots,
       moduleSemantics,
-    )
+    })
     let prepared
     try {
       prepared = prepareCell(request.program)
@@ -322,7 +476,9 @@ export class SessionCellExecutor {
       const result = earlyResult('abort', String(request.signal.reason))
       kernel.completeJournal(request.journal, 'discarded', result)
       kernel.rollbackToDurable()
-      void kernel.client.reset(worker)
+      // A refused reclamation stays recorded on the kernel so disposal remains
+      // observable instead of becoming an unhandled rejection after this abort.
+      kernel.resetWorker(worker)
       return result
     }
 
@@ -332,9 +488,9 @@ export class SessionCellExecutor {
     const bindings = this.withControlBinding(request.bindingDescriptors, journal, replayRecord)
     const id = ++kernel.sequence
     return new Promise((resolve) => {
-      const started = worker.performance.eventLoopUtilization()
       const active = {
         id,
+        started: false,
         request: { ...request, bindings: bindings.namespaces },
         finish: resolve,
         computeTimer: undefined,
@@ -363,41 +519,112 @@ export class SessionCellExecutor {
         control: { names: new Set(kernel.history.checkpoints.keys()) },
         rewrites: prepared.rewrites,
         prepared,
-        priorBindingCatalog: kernel.bindingCatalog,
+        priorBindingCatalog,
+        userBindingBaseCatalog,
+        userBindings,
+        userBindingsShadowPolicy,
+        userBindingFailures,
+        userBindingSnapshot: userBindings,
         worker,
+        settled: false,
       }
       active.resolve = (result, terminate = false) => kernel.settleCell(active, result, terminate)
       active.onAbort = () => active.resolve(
         earlyResult('abort', String(request.signal?.reason)),
         true,
       )
-      active.computeTimer = setInterval(() => {
-        if (worker.performance.eventLoopUtilization(started).active > config.computeMs) {
-          active.resolve(earlyResult('timeout', `compute budget exhausted (${config.computeMs}ms busy); split the work into smaller cells`), true)
+      active.budgetsStarted = false
+      active.startBudgets = () => {
+        if (active.budgetsStarted) return active.budgetsReady
+        active.budgetsStarted = true
+        // The wall bound starts at the request, while the compute baseline is
+        // sampled from the worker instead of reusing the helper's last periodic
+        // cache. Work that completed before this request must not be charged to
+        // the new cell, and work after the sample must remain counted.
+        active.wallTimer = setTimeout(() => {
+          active.resolve(earlyResult('timeout', `wall-clock ceiling reached (${config.maxWallMs}ms); split long-running work into smaller cells`), true)
+        }, config.maxWallMs)
+        active.budgetsReady = (async () => {
+          let started
+          try {
+            started = await worker.sampleUtilization()
+          } catch (error) {
+            // No fresh baseline means this request cannot be measured. Use the
+            // existing worker-exit route instead of pretending the last cache
+            // sample is this request's starting point.
+            active.resolve(earlyResult('worker-exit', messageOf(error)), true)
+            return
+          }
+          if (active.settled) return
+          active.computeTimer = setInterval(() => {
+            if (active.settled) return
+            if (worker.performance.eventLoopUtilization(started).active > config.computeMs) {
+              active.resolve(earlyResult('timeout', `compute budget exhausted (${config.computeMs}ms event-loop active, including synchronous blocking); this measure does not establish CPU use or the specific cause. Use asynchronous waiting for long waits, or a DSH-owned managed job if available. This cell was discarded and the worker reset; external effects or processes may continue.`), true)
+            }
+          }, Math.min(100, config.computeMs))
+        })()
+        return active.budgetsReady
+      }
+      active.start = async () => {
+        if (active.started) return
+        active.started = true
+        kernel.workerObservation = undefined
+        await active.startBudgets()
+        if (active.settled) return
+        try {
+          kernel.client.post({
+            type: 'run', id, program: prepared.code, namespaces: bindings.workerDescriptors,
+            moduleLoads: prepared.moduleLoads,
+            languageSemantics,
+            moduleTransform,
+            rootRuntimeName: prepared.rootRuntimeName,
+            rootBindings: prepared.rootBindings,
+            importBindingNamespaces: new Map([...catalog.importBindings].map(([name, binding]) => [name, binding.namespace])),
+            preparedImportBindingNamespaces: new Map([...prepared.imports].map(([name, binding]) => [name, binding.namespace])),
+            returnSignal: prepared.returnSignal,
+            asyncCompletion: prepared.asyncCompletion,
+            commitSignal: prepared.commitSignal,
+            maxOutputBytes: config.maxOutputBytes,
+            valueLimits,
+            durability,
+            observeNames: replayRecord === undefined && kernel.observeValues()
+              ? createReplMemorySnapshot(
+                  priorBindingCatalog.advance(prepared, request.program).snapshot(),
+                ).entries.map(entry => entry.name)
+              : [],
+            userBindings,
+            userBindingsShadowPolicy,
+            userBindingsReusePolicy: replayRecord === undefined
+              ? LIVE_USER_BINDINGS_REUSE_POLICY
+              : replayRecord.userBindingsReusePolicy,
+            ...(userBindings === undefined ? {} : { userBindingsCwd: kernel.userBindingsCwd }),
+            userBindingFailures,
+            shadowedUserBindingNames: [...new Set([
+              ...userBindingPlan.shadowedNames,
+              ...request.bindingDescriptors.reservedNames,
+            ])],
+          })
+        } catch (error) {
+          active.resolve(earlyResult('worker-exit', messageOf(error)), true)
         }
-      }, Math.min(100, config.computeMs))
-      active.wallTimer = setTimeout(() => {
-        active.resolve(earlyResult('timeout', `wall-clock ceiling reached (${config.maxWallMs}ms); split long-running work into smaller cells`), true)
-      }, config.maxWallMs)
+      }
       kernel.active = active
       request.signal?.addEventListener('abort', active.onAbort, { once: true })
       if (request.signal?.aborted) {
         active.onAbort()
         return
       }
-      try {
-        kernel.client.post({
-          type: 'run', id, program: prepared.code, namespaces: bindings.workerDescriptors,
-          moduleLoads: prepared.moduleLoads,
-          returnSignal: prepared.returnSignal,
-          commitSignal: prepared.commitSignal,
-          maxOutputBytes: config.maxOutputBytes,
-          valueLimits,
-          durability,
-        })
-      } catch (error) {
-        active.resolve(earlyResult('worker-exit', messageOf(error)), true)
-      }
+      void (async () => {
+        try {
+          // Only worker-confirmed observation may defer these budgets; never restart them.
+          if (kernel.workerObservation?.worker !== worker
+            || kernel.workerObservation.started !== true) await active.startBudgets()
+          if (active.settled) return
+          kernel.client.post({ type: 'prepare', id })
+        } catch (error) {
+          active.resolve(earlyResult('worker-exit', messageOf(error)), true)
+        }
+      })()
     })
   }
 
@@ -418,7 +645,7 @@ export class SessionCellExecutor {
       reservedNames: bindingDescriptors.reservedNames,
       workerDescriptors: Object.freeze([
         ...bindingDescriptors.workerDescriptors,
-        Object.freeze({ global: 'repl', members: namespace.members }),
+        ...normalizeBindingDescriptors([namespace]).workerDescriptors,
       ]),
     })
   }
@@ -456,6 +683,30 @@ export class SessionCellExecutor {
   }
 
   onMessage(message) {
+    if (message?.type === 'observation-started') {
+      const kernel = this.kernel
+      const observation = kernel.workerObservation
+      if (observation !== undefined && observation.id === message.id
+        && observation.worker === kernel.client.worker) observation.started = true
+      return
+    }
+    if (message?.type === 'ready') {
+      const inspection = this.kernel.pendingInspection
+      if (inspection !== undefined && inspection.id === message.id) inspection.start()
+      const active = this.kernel.active
+      if (active !== undefined && active.id === message.id) void active.start()
+      return
+    }
+    if (message?.type === 'observation') {
+      const kernel = this.kernel
+      const observation = kernel.workerObservation
+      if (observation !== undefined && observation.id === message.id) {
+        kernel.workerObservation = undefined
+        if (kernel.active?.worker === observation.worker) kernel.active.startBudgets()
+      }
+      kernel.finishObservation(message)
+      return
+    }
     if (message === null || typeof message !== 'object') return
     const handler = {
       volatile: this.handleVolatile,
@@ -515,6 +766,53 @@ export class SessionCellExecutor {
       active.resolve({ logs, error: { kind: 'recovery', message: 'session log replay consumed a different host-call transcript' } }, true)
       return
     }
+    let activatedUserBindings
+    const perNameUserBindings = active.userBindingsShadowPolicy === LIVE_USER_BINDINGS_SHADOW_POLICY
+    try {
+      if (active.userBindings === undefined) {
+        active.userBindingSnapshot = undefined
+        active.priorBindingCatalog = active.userBindingBaseCatalog.withoutUserBindings()
+      } else {
+        const ids = Array.isArray(message.activatedUserBindings)
+          && message.activatedUserBindings.every(id => typeof id === 'string')
+          ? new Set(message.activatedUserBindings)
+          : undefined
+        if (ids === undefined || ids.size !== message.activatedUserBindings.length) {
+          throw new TypeError('kernel returned an invalid activated user binding set')
+        }
+        const expected = new Set(active.userBindings.entries.map(entry => entry.id))
+        if ([...ids].some(id => !expected.has(id))) {
+          throw new TypeError('kernel activated an unknown user binding entry')
+        }
+        if (perNameUserBindings) validateUserBindingActivation(active, message, ids)
+        activatedUserBindings = selectUserBindingsSnapshot(active.userBindings, ids)
+        active.userBindingSnapshot = activatedUserBindings
+        active.priorBindingCatalog = active.userBindingBaseCatalog.userBindings(active.userBindings, ids, active.userBindingsShadowPolicy).catalog
+        if (!perNameUserBindings) {
+          const shadowed = Array.isArray(message.shadowedUserBindings)
+            && message.shadowedUserBindings.every(name => typeof name === 'string')
+            ? new Set(message.shadowedUserBindings)
+            : undefined
+          const activeNames = new Set(activatedUserBindings.entries.flatMap(entry => (
+            entry.scope === 'namespace' ? [entry.name] : entry.symbols
+          )))
+          if (shadowed === undefined || shadowed.size !== message.shadowedUserBindings.length
+            || [...shadowed].some(name => !activeNames.has(name))) {
+            throw new TypeError('kernel returned an invalid shadowed user binding set')
+          }
+          active.priorBindingCatalog = active.priorBindingCatalog.shadowUserBindings(shadowed)
+        }
+        if (active.replay !== undefined
+          && activatedUserBindings.fingerprint !== active.userBindings.fingerprint) {
+          active.resolve({ logs, error: { kind: 'recovery', message: 'recorded user bindings could not be reactivated' } }, true)
+          return
+        }
+      }
+      if (perNameUserBindings) active.userBindingNames = completedUserBindingNames(active, message, activatedUserBindings)
+    } catch (error) {
+      active.resolve(earlyResult('worker-exit', messageOf(error)), true)
+      return
+    }
     const bytes = Buffer.byteLength(JSON.stringify({ logs, value: message.value }), 'utf8')
     if (bytes > active.config.maxOutputBytes) {
       active.resolve({
@@ -524,8 +822,10 @@ export class SessionCellExecutor {
       return
     }
     let committed
+    let rootBindingFacts
     try {
       committed = committedRedeclarationSet(message, active.prepared)
+      rootBindingFacts = completedRootBindingFacts(message, active.prepared, committed)
     } catch (error) {
       active.resolve(earlyResult('worker-exit', messageOf(error)), true)
       return
@@ -536,7 +836,14 @@ export class SessionCellExecutor {
           active.prepared,
           active.request.program,
           committed,
+          rootBindingFacts,
         )
+    if (perNameUserBindings) {
+      active.appliedBindingCatalog = active.appliedBindingCatalog.reconcileUserBindingNames(
+        activatedUserBindings, active.userBindingNames, active.request.program,
+      )
+    }
+    active.observing = message.observing === true
     if (typeof message.error === 'string') {
       const rawError = {
         kind: 'exception',
@@ -547,30 +854,38 @@ export class SessionCellExecutor {
       const actualFailure = exceptionDiagnostic({
         error: rawError,
         cause: message.cause,
+        // A diagnostic caret must exist in the submitted cell. A native frame
+        // is mapped first; an unmappable frame falls back to the recorded
+        // source origin rather than attaching an out-of-range position.
         position: message.moduleLoadFailed === true
-          ? message.position
-          : mapSourcePosition(
-              message.position,
-              active.prepared.code,
+          ? cellPosition(message.position, active.request.program)
+          : cellPosition(
+              mapSourcePosition(
+                message.position,
+                active.prepared.code,
+                active.request.program,
+                active.prepared.sourceMap,
+              ),
               active.request.program,
-              active.prepared.sourceMap,
-            ),
+            ) ?? exceptionOriginPosition(message.exceptionOrigins, active.request.program),
         declared: message.moduleLoadFailed === true ? new Set() : active.prepared.declared,
+        languageSemantics: active.prepared.languageSemantics,
         longCellFailure: active.request.program.length >= LONG_CELL_CODE_UNITS,
+        failureOrigin: message.failureOrigin,
       })
-      const recordedFailure = active.replay?.diagnostics?.find(item => item.code === 'PTC-X001')
-      const failure = recordedFailure?.message === actualFailure.message ? recordedFailure : actualFailure
+      const failure = replayFailureDiagnostic(actualFailure, active.replay)
       const error = {
         kind: 'exception',
         message: renderDiagnostic(failure, active.request.program),
       }
       if (isBindingReferenceError(rawError)) markBindingFailure(error)
+      else if (message.failureOrigin === 'capability') markBindingFailure(error, 'capability')
       active.diagnostics.push(failure)
       active.resolve({ logs, error })
       return
     }
     if (typeof message.invalidOutput === 'string') {
-      const failure = invalidOutputDiagnostic(message.invalidOutput)
+      const failure = replayFailureDiagnostic(invalidOutputDiagnostic(message.invalidOutput), active.replay)
       const error = { kind: 'invalid-output', message: renderDiagnostic(failure, active.request.program) }
       active.diagnostics.push(failure)
       active.resolve({ logs, error })
@@ -581,23 +896,23 @@ export class SessionCellExecutor {
         || (message.hasValue ? message.value === undefined : message.value !== undefined)) {
         throw new TypeError('invalid PTC completion envelope')
       }
-      const value = message.hasValue ? normalizeValueWire(message.value, active.valueLimits) : undefined
+      const completion = message.hasValue ? prepareValueWire(message.value, active.valueLimits) : undefined
       active.completion = {
         hasValue: message.hasValue,
-        ...(message.hasValue ? { value } : {}),
+        ...(message.hasValue ? { value: completion.wire } : {}),
       }
       if (active.replay?.completion?.kind === 'return'
         && (active.replay.completion.hasValue !== message.hasValue
-          || (message.hasValue && !valueWiresEqual(active.replay.completion.value, value, active.valueLimits)))) {
+          || (message.hasValue && !valueWiresEqual(active.replay.completion.value, completion.wire, active.valueLimits)))) {
         active.resolve({ logs, error: { kind: 'recovery', message: 'cell replay produced a different completion value' } }, true)
         return
       }
       active.resolve({
         logs,
-        ...(message.hasValue ? { value: projectValueWire(value, active.valueLimits) } : {}),
+        ...(message.hasValue ? { value: completion.projectedValue } : {}),
       })
     } catch (error) {
-      const failure = invalidOutputDiagnostic(messageOf(error))
+      const failure = replayFailureDiagnostic(invalidOutputDiagnostic(messageOf(error)), active.replay)
       const invalid = { kind: 'invalid-output', message: renderDiagnostic(failure, active.request.program) }
       active.diagnostics.push(failure)
       active.resolve({ logs, error: invalid })