dsh-ptc-plus 0.3.2 → 0.4.1

package/internal/session-runtime.js

@@ -1,21 +1,30 @@
+import { isAbsolute } from 'node:path'
+import { isDeepStrictEqual } from 'node:util'
 import { diagnostic, renderDiagnostic } from './diagnostic.js'
 import { createFailureTracker, messageOf } from './failure-reporting.js'
 import {
   createJournal,
   liveToolCallSeq,
   normalizeJournal,
-  pathToHead,
   reduceStateOperations,
+} from './session-journal.js'
+import {
+  pathToHead,
+  recoveryBoundaryForHistory,
   recoverJournal,
   visibleExecutableCallSeqs,
-} from './session-journal.js'
+} from './session-journal-recovery.js'
+import { valueLimitsFromConfig } from './value-wire-schema.js'
 import { normalizeBindingDescriptors } from './binding-descriptors.js'
 import { resolveConfig } from './runtime-config.js'
 import { WorkerClient } from './worker-client.js'
+import { compilerWorkerCache } from './compiler-service.js'
 import { BindingCatalog, durabilityState, transitionDurability } from './session-state.js'
 import { SessionCellExecutor } from './session-cell-executor.js'
+import { executionPolicies } from './binding-update-policy.js'
 import {
   createReplMemorySnapshot,
+  normalizeReplMemorySnapshot,
   unavailableReplMemorySnapshot,
 } from './repl-memory-projection.js'
 
@@ -34,21 +43,6 @@ function recoveryDiagnostic(count) {
   })
 }
 
-function rewritePolicy(config) {
-  return {
-    autoRewriteImports: config.autoRewriteImports,
-    autoStripExports: config.autoStripExports,
-    autoSplitRedeclarations: config.autoSplitRedeclarations,
-  }
-}
-
-function bindingPolicy(config) {
-  return {
-    variableRedeclarations: config.looseTopLevelRedeclarations,
-    functionClassRedeclarations: config.looseTopLevelFunctionClassRedeclarations,
-  }
-}
-
 function resolvedRuntimeConfig(config) {
   return Object.freeze(resolveConfig(config))
 }
@@ -72,15 +66,10 @@ class ReplayCancelled extends Error {
 }
 
 class SessionKernel {
-  constructor({ config, history, cwd, session, withInitiator }) {
+  constructor({ config, history, cwd, session, userBindingsCwd, withInitiator, observeValues }) {
     this.config = config
     this.history = history
-    this.initialRecoveryBoundary = history.available === false && history.volatileSuffix.length > 0
-      ? {
-          failedCallSeq: history.volatileSuffix[0].seq,
-          frontierCallSeq: history.head === undefined ? null : history.nodes[history.head]?.callSeq ?? null,
-        }
-      : undefined
+    this.initialRecoveryBoundary = recoveryBoundaryForHistory(history)
     this.surfaceGeneration = undefined
     try {
       this.surfaceGeneration = session?.surface?.replaceGeneration
@@ -88,6 +77,8 @@ class SessionKernel {
       this.surfaceGeneration = undefined
     }
     this.cwd = cwd
+    this.userBindingsCwd = userBindingsCwd
+    this.observeValues = observeValues
     this.session = session
     this.withInitiator = withInitiator
     this.durability = durabilityState()
@@ -101,28 +92,56 @@ class SessionKernel {
     this.sequence = 0
     this.tail = Promise.resolve()
     this.tentatives = new WeakMap()
+    this.unsettledCells = 0
+    this.pendingInspection = undefined
+    this.pendingObservation = undefined
+    this.workerObservation = undefined
     this.workerReservations = new Set()
     this.cellExecutor = new SessionCellExecutor(this)
     this.client = new WorkerClient({
       workerUrl: WORKER_URL,
       cwd,
+      compilerCache: compilerWorkerCache,
       onMessage: message => this.cellExecutor.onMessage(message),
-      onFailure: message => this.active?.resolve({
-        logs: [], error: { kind: 'worker-exit', message },
-      }, true),
+      onFailure: message => {
+        this.pendingInspection?.finish()
+        this.workerObservation = undefined
+        this.active?.resolve({ logs: [], error: { kind: 'worker-exit', message } }, true)
+      },
     })
     this.failures = createFailureTracker()
+    this.reclamationSequence = 0
+    this.reclamationRecords = new Map()
+    this.reclamationAttempts = new Set()
     this.disposed = false
+    this.disposal = undefined
   }
 
-  valueLimits(config = this.config) {
-    return {
-      maxNodes: config.maxValueNodes,
-      maxEdges: config.maxValueEdges,
-      maxArrayLength: config.maxValueArrayLength,
-      maxBigIntDigits: config.maxValueBigIntDigits,
-      maxStringBytes: config.maxOutputBytes,
+  resetWorker(worker) {
+    const sequence = ++this.reclamationSequence
+    const record = { failed: false, reason: undefined }
+    this.reclamationRecords.set(sequence, record)
+    let reset
+    try {
+      reset = this.client.reset(worker)
+    } catch (error) {
+      record.failed = true
+      record.reason = error
+      return
     }
+    const attempt = Promise.resolve(reset).then(
+      () => { this.reclamationRecords.delete(sequence) },
+      error => {
+        record.failed = true
+        record.reason = error
+      },
+    )
+    this.reclamationAttempts.add(attempt)
+    attempt.then(() => { this.reclamationAttempts.delete(attempt) })
+  }
+
+  valueLimits(config = this.config) {
+    return valueLimitsFromConfig(config)
   }
 
   assertReconfigurationAllowed(config) {
@@ -156,6 +175,57 @@ class SessionKernel {
     return result
   }
 
+  /** Observe only the existing, settled live worker; never recover or execute a cell for the UI. */
+  observe(expected, signal) {
+    if (this.pendingInspection !== undefined) return Promise.resolve(undefined)
+    const current = () => {
+      if (this.disposed || !this.config.replViewEnabled || signal?.aborted
+        || this.client.worker === undefined || this.unsettledCells > 0) return false
+      try {
+        return this.session?.surface?.replaceGeneration === this.surfaceGeneration
+          && isDeepStrictEqual(expected, createReplMemorySnapshot(this.bindingCatalog.snapshot()))
+      } catch { return false }
+    }
+    return new Promise(resolve => {
+      let finished = false
+      let releaseQueue
+      const id = ++this.sequence
+      const finish = observation => {
+        if (finished) return
+        finished = true
+        clearTimeout(timer)
+        signal?.removeEventListener('abort', onAbort)
+        if (this.pendingInspection?.id === id) this.pendingInspection = undefined
+        resolve(current() && observation !== undefined
+          ? createReplMemorySnapshot(this.bindingCatalog.snapshot(), observation) : undefined)
+        releaseQueue?.()
+      }
+      const onAbort = () => finish()
+      const timer = setTimeout(onAbort, 250)
+      signal?.addEventListener('abort', onAbort, { once: true })
+      const inspect = () => {
+        if (finished) return
+        if (!current()) { finish(); return }
+        return new Promise(done => {
+          releaseQueue = done
+          const worker = this.client.worker
+          let started = false
+          this.pendingInspection = { id, finish, start: () => {
+            if (started) return
+            started = true
+            if (!current() || this.client.worker !== worker) { finish(); return }
+            try {
+              this.client.post({ type: 'observe', id, names: expected.entries.map(entry => entry.name) })
+              this.workerObservation = { id, worker, started: false }
+            } catch { finish() }
+          } }
+          try { this.client.post({ type: 'prepare', id }) } catch { finish() }
+        })
+      }
+      this.tail = this.tail.then(inspect, inspect)
+    })
+  }
+
   async execute(request, config) {
     const recoveryBoundaries = this.initialRecoveryBoundary === undefined
       ? []
@@ -187,6 +257,8 @@ class SessionKernel {
               visibleCallSeqs,
             })
           } catch (error) {
+            const boundary = recoveryBoundaryForHistory(this.history, undefined, { reset: true })
+            if (boundary !== undefined) recoveryBoundaries.push(boundary)
             this.history = emptyHistory()
             this.recoveryNotice = recoveryDiagnostic(1)
             this.initialRecoveryBoundary = undefined
@@ -194,14 +266,7 @@ class SessionKernel {
           if (this.history.volatileSuffix.length > 0) {
             this.recoveryNotice = recoveryDiagnostic(this.history.volatileSuffix.length)
           }
-          this.initialRecoveryBoundary = this.history.available === false && this.history.volatileSuffix.length > 0
-            ? {
-                failedCallSeq: this.history.volatileSuffix[0].seq,
-                frontierCallSeq: this.history.head === undefined
-                  ? null
-                  : this.history.nodes[this.history.head]?.callSeq ?? null,
-              }
-            : undefined
+          this.initialRecoveryBoundary = recoveryBoundaryForHistory(this.history)
           if (this.initialRecoveryBoundary !== undefined) {
             recoveryBoundaries.push(this.initialRecoveryBoundary)
             this.initialRecoveryBoundary = undefined
@@ -226,45 +291,28 @@ class SessionKernel {
             this.completeJournal(request.journal, 'noop', error.result)
             return finishResult(error.result)
           }
-          if (!(error instanceof ReplayFailure)) {
-            const result = {
-              logs: [],
-              error: {
-                kind: 'recovery',
-                message: `cannot reconstruct REPL from session log: ${messageOf(error)}`,
-              },
-            }
-            this.completeJournal(request.journal, 'noop', result)
-            return finishResult(result)
-          }
-          const frontier = error.node.parent === undefined
-            ? undefined
-            : this.history.nodes[error.node.parent]
-          const previousPathLength = pathToHead(this.history).length
           try {
-            const boundary = {
-              failedCallSeq: error.node.callSeq,
-              frontierCallSeq: frontier?.callSeq ?? null,
-            }
+            if (!(error instanceof ReplayFailure)) throw error
+            const previousPathLength = pathToHead(this.history).length
+            const boundary = recoveryBoundaryForHistory(this.history, error.node)
             const recovered = recoverJournal(this.session, request.callSeq, {
               extraBoundaries: [boundary],
               visibleCallSeqs: visibleExecutableCallSeqs(this.session),
             })
+            const nextPathLength = pathToHead(recovered).length
+            if (nextPathLength >= previousPathLength) throw new Error('recovery did not contract the historical frontier')
             recoveryBoundaries.push(boundary)
             this.history = recovered
-          } catch (boundaryError) {
-            const result = {
-              logs: [],
-              error: {
-                kind: 'recovery',
-                message: `cannot apply REPL recovery boundary: ${messageOf(boundaryError)}`,
-              },
-            }
-            this.completeJournal(request.journal, 'noop', result)
-            return finishResult(result)
+            skipped += previousPathLength - nextPathLength
+          } catch {
+            // Unproved historical metadata cannot gate the current request.
+            // A failed or noncontracting recovery has no reusable frontier.
+            const boundary = recoveryBoundaryForHistory(this.history, undefined, { reset: true })
+            if (boundary !== undefined) recoveryBoundaries.push(boundary)
+            this.history = emptyHistory()
+            this.replayed = true
+            skipped++
           }
-          const nextPathLength = pathToHead(this.history).length
-          skipped += Math.max(1, previousPathLength - nextPathLength)
           this.durability = durabilityState()
         }
       }
@@ -281,7 +329,8 @@ class SessionKernel {
     if (result.error === undefined) {
       this.failures.reset()
     } else {
-      const hint = this.failures.hint(result.error)
+      const primary = request.journal?.diagnostics.find(item => item.severity === 'error')
+      const hint = this.failures.hint(result.error, primary?.stateEffect)
       if (hint !== undefined) {
         result.logs = [...result.logs, renderDiagnostic(hint, request.program)]
         if (request.journal !== undefined) request.journal.diagnostics.push(hint)
@@ -296,7 +345,12 @@ class SessionKernel {
     for (const node of path) {
       try {
         const result = await this.cellExecutor.executeCell(
-          { ...request, program: node.code, journal: undefined },
+          {
+            ...request,
+            program: node.code,
+            journal: undefined,
+            ...(node.userBindings === undefined ? { userBindings: undefined } : { userBindings: node.userBindings }),
+          },
           node.journal,
           config,
         )
@@ -338,12 +392,14 @@ class SessionKernel {
       journal.operations = journal.operations.filter(operation => operation.action !== 'save')
     }
     if (status === 'discarded' || status === 'noop') {
+      journal.userBindingNames = null
       journal.calls.length = 0
       journal.operations.length = 0
     }
   }
 
   rollbackToDurable() {
+    this.workerObservation = undefined
     this.durability = durabilityState()
     this.replayed = false
     this.bindingCatalog = new BindingCatalog()
@@ -353,7 +409,8 @@ class SessionKernel {
   settleCell(active, result, terminate = false) {
     /* c8 ignore next */
     if (this.active !== active) return
-    const { request, journal, replay, prepared, worker } = active
+    active.settled = true
+    const { request, journal, replay, worker } = active
     clearInterval(active.computeTimer)
     clearTimeout(active.wallTimer)
     request.signal?.removeEventListener('abort', active.onAbort)
@@ -361,6 +418,10 @@ class SessionKernel {
       result = { ...result, rewrites: active.rewrites }
     }
     if (journal !== undefined && replay === undefined) {
+      journal.userBindingsFingerprint = terminate
+        ? null
+        : active.userBindingSnapshot?.fingerprint ?? null
+      journal.userBindingNames = terminate ? null : active.userBindingNames ?? null
       if (terminate) {
         const volatileReason = active.pendingBindings.values().next().value ?? active.durability.reason
         this.completeJournal(journal, 'discarded', result, volatileReason, active.diagnostics)
@@ -379,28 +440,58 @@ class SessionKernel {
         this.tentatives.set(journal, {
           callSeq: request.callSeq,
           program: request.program,
-          bindingCatalog: active.appliedBindingCatalog
-            ?? active.priorBindingCatalog.advance(prepared, request.program),
+          bindingCatalog: active.appliedBindingCatalog,
+          userBindings: active.userBindingSnapshot,
           worker,
         })
+        this.unsettledCells++
       }
     }
-    if (replay !== undefined && !terminate) {
+    if (!terminate) {
       this.bindingCatalog = active.appliedBindingCatalog
-        ?? active.priorBindingCatalog.advance(prepared, request.program)
     }
     if (replay === undefined && !terminate) {
+      // A live cell establishes this worker's timeline even when historical
+      // replay was disabled. Only a reset may reopen its recovery boundary.
+      this.replayed = true
       this.liveCallSeqs.add(request.callSeq ?? request.sourceCallSeq)
     }
     this.active = undefined
-    if (terminate) void this.client.reset(worker)
-    active.finish(result)
+    if (terminate) {
+      this.workerObservation = undefined
+      // A refused reclamation stays recorded on this kernel instead of becoming
+      // an unhandled rejection; the kernel keeps the worker until dispose.
+      this.resetWorker(worker)
+    }
+    if (!terminate && active.observing && replay === undefined) {
+      // Computation and journal settlement are complete. Observation cannot change either.
+      // done with observing=true precedes synchronous observation in the same worker turn.
+      this.workerObservation = { id: active.id, worker, started: true }
+      const timer = setTimeout(() => this.finishObservation({ id: active.id }), 250)
+      this.pendingObservation = { id: active.id, timer, journal, finish: () => active.finish(result) }
+    } else active.finish(result)
+  }
+
+  finishObservation(message) {
+    const inspection = this.pendingInspection
+    if (inspection !== undefined && inspection.id === message.id) {
+      inspection.finish(message.observation)
+      return
+    }
+    const pending = this.pendingObservation
+    if (pending === undefined || pending.id !== message.id) return
+    this.pendingObservation = undefined
+    clearTimeout(pending.timer)
+    const tentative = this.tentatives.get(pending.journal)
+    if (tentative !== undefined) tentative.observation = message.observation
+    pending.finish()
   }
 
   finalizeJournal(journal, confirmed) {
     const tentative = this.tentatives.get(journal)
     if (tentative === undefined) return
     this.tentatives.delete(journal)
+    this.unsettledCells--
     if (!confirmed) {
       if (journal.status === 'durable' || journal.status === 'volatile') {
         const reason = journal.volatileReason ?? 'run_code journal was not preserved in the final tool result'
@@ -408,7 +499,6 @@ class SessionKernel {
           type: 'volatile',
           reason,
         })
-        this.bindingCatalog = tentative.bindingCatalog
       }
       return
     }
@@ -418,11 +508,11 @@ class SessionKernel {
         code: tentative.program,
         journal: normalized,
         ...(tentative.callSeq === undefined ? {} : { callSeq: tentative.callSeq }),
+        ...(tentative.userBindings === undefined ? {} : { userBindings: tentative.userBindings }),
         parent: this.history.head,
       })
       const index = this.history.nodes.push(node) - 1
       this.history.head = index
-      this.bindingCatalog = tentative.bindingCatalog
       this.finishStateOperations(journal.operations, index, tentative.worker)
       return
     }
@@ -431,7 +521,6 @@ class SessionKernel {
         type: 'volatile',
         reason: journal.volatileReason,
       })
-      this.bindingCatalog = tentative.bindingCatalog
       this.finishStateOperations(journal.operations, undefined, tentative.worker)
     }
   }
@@ -445,7 +534,11 @@ class SessionKernel {
     if (tentative === undefined) {
       return createReplMemorySnapshot(this.bindingCatalog.snapshot())
     }
-    return createReplMemorySnapshot(tentative.bindingCatalog.snapshot())
+    return createReplMemorySnapshot(tentative.bindingCatalog.snapshot(), tentative.observation)
+  }
+
+  userBindingsFor(journal) {
+    return this.tentatives.get(journal)?.userBindings
   }
 
   finishStateOperations(operations, index, worker) {
@@ -454,12 +547,26 @@ class SessionKernel {
     this.history.checkpoints = transition.checkpoints
     if (transition.restored) {
       this.rollbackToDurable()
-      void this.client.reset(worker)
+      this.resetWorker(worker)
     }
   }
 
-  async dispose() {
+  dispose() {
+    if (this.disposal !== undefined) return this.disposal
+    const operation = this.#dispose()
+    this.disposal = operation
+    operation.then(
+      () => { if (this.disposal === operation) this.disposal = undefined },
+      () => { if (this.disposal === operation) this.disposal = undefined },
+    )
+    return operation
+  }
+
+  async #dispose() {
     this.disposed = true
+    this.pendingInspection?.finish()
+    this.workerObservation = undefined
+    // Keep any refused reclamation observable through this kernel's dispose.
     const worker = this.client.worker
     if (worker !== undefined) {
       /* c8 ignore next */
@@ -467,6 +574,18 @@ class SessionKernel {
     }
     await this.client.dispose()
     await this.tail
+    await Promise.all([...this.reclamationAttempts])
+    // A successful client disposal proves its owner no longer retains the
+    // helpers. Report every earlier refusal once, then let a later terminal
+    // retry release this already reclaimed kernel.
+    const reclamationFailures = [...this.reclamationRecords.values()]
+      .filter(record => record.failed)
+      .map(record => record.reason)
+    this.reclamationRecords.clear()
+    if (reclamationFailures.length === 1) throw reclamationFailures[0]
+    if (reclamationFailures.length > 1) {
+      throw new AggregateError(reclamationFailures, 'ptc-plus session kernel reclamation failed')
+    }
   }
 }
 
@@ -497,7 +616,13 @@ export class SessionRuntime {
     this.pendingNoops = new Map()
     this.settlements = new WeakSet()
     this.disposed = false
+    this.userBindingsCwd = options.userBindingsCwd ?? process.cwd()
+    if (typeof this.userBindingsCwd !== 'string' || !isAbsolute(this.userBindingsCwd)) {
+      throw new TypeError('userBindingsCwd must be an absolute path')
+    }
     this.withInitiator = typeof options.withInitiator === 'function' ? options.withInitiator : undefined
+    this.observeSession = options.observeSession ?? (() => false)
+    this.disposal = undefined
   }
 
   async run(sessionContext, request) {
@@ -514,6 +639,13 @@ export class SessionRuntime {
     this.config = resolved
   }
 
+  async observe(sessionId, memory, signal) {
+    if (this.disposed || !this.config.replViewEnabled) return undefined
+    const { observation: _observation, ...expected } = normalizeReplMemorySnapshot(memory)
+    if (!expected.available || expected.entries.length === 0) return undefined
+    return this.kernels.get(sessionId)?.observe(expected, signal)
+  }
+
   async runTentative(sessionContext, request) {
     const completed = result => Object.freeze({ result, settlement: undefined })
     if (this.disposed) return completed({ logs: [], error: { kind: 'abort', message: 'PTC runtime disposed' } })
@@ -559,6 +691,8 @@ export class SessionRuntime {
           })
           : emptyHistory()
       } catch (error) {
+        // Malformed PTC metadata is contracted by the ordered recovery owner.
+        // Failure to read DSH's session source cannot prove a reset boundary.
         return completed({ logs: [], error: { kind: 'recovery', message: `cannot reconstruct REPL from session log: ${messageOf(error)}` } })
       }
       kernel = new SessionKernel({
@@ -566,15 +700,19 @@ export class SessionRuntime {
         history,
         cwd,
         session,
+        userBindingsCwd: this.userBindingsCwd,
         withInitiator: this.withInitiator,
+        observeValues: () => this.config.replViewEnabled && this.observeSession(sessionId),
       })
       this.kernels.set(sessionId, kernel)
     }
+    const policies = executionPolicies(cellConfig)
     const journal = createJournal(
       /* c8 ignore next */
       this.pendingNoops.get(sessionId) ?? [],
-      bindingPolicy(cellConfig),
-      rewritePolicy(cellConfig),
+      policies.bindingPolicy,
+      policies.rewritesEnabled,
+      policies.languageSemantics,
     )
     const workerReservation = kernel.reserveWorkerConfiguration(cellConfig)
     let result
@@ -588,6 +726,7 @@ export class SessionRuntime {
       kernel,
       sessionId,
       replMemory: kernel.replMemoryFor(journal),
+      userBindings: kernel.userBindingsFor(journal),
       ...(result.recoveryBoundaries === undefined
         ? {}
         : { recoveryBoundaries: result.recoveryBoundaries }),
@@ -632,14 +771,36 @@ export class SessionRuntime {
     const kernel = this.kernels.get(id)
     this.pendingNoops.delete(id)
     if (kernel === undefined) return
-    this.kernels.delete(id)
+    // The entry survives a failed dispose so a repeated dispose reports the same
+    // unreclaimed instance instead of appearing to succeed.
     await kernel.dispose()
+    this.kernels.delete(id)
+  }
+
+  dispose() {
+    if (this.disposal !== undefined) return this.disposal
+    const operation = this.#dispose()
+    this.disposal = operation
+    operation.then(
+      () => { if (this.disposal === operation) this.disposal = undefined },
+      () => { if (this.disposal === operation) this.disposal = undefined },
+    )
+    return operation
   }
 
-  async dispose() {
+  async #dispose() {
     this.disposed = true
-    const kernels = [...this.kernels.values()]
-    this.kernels.clear()
-    await Promise.all(kernels.map(kernel => kernel.dispose()))
+    const entries = [...this.kernels]
+    const results = await Promise.allSettled(entries.map(async ([id, kernel]) => {
+      await kernel.dispose()
+      this.kernels.delete(id)
+    }))
+    const failures = []
+    for (const result of results) {
+      if (result.status === 'rejected') failures.push(result.reason)
+    }
+    if (failures.length > 0) {
+      throw new AggregateError(failures, 'ptc-plus session runtime disposal failed')
+    }
   }
 }