dsh-ptc-plus 0.2.1

package/internal/value-wire.js

@@ -0,0 +1,421 @@
+import { assertFields, isRecord } from './record-utils.js'
+
+export const VALUE_CODEC = 'ptc-value-graph/v1'
+
+export const DEFAULT_VALUE_LIMITS = Object.freeze({
+  maxNodes: 100_000,
+  maxEdges: 1_000_000,
+  maxArrayLength: 1_000_000,
+  maxBigIntDigits: 100_000,
+  maxStringBytes: 64 * 1024 * 1024,
+})
+
+const ENVELOPE_FIELDS = new Set(['codec', 'root', 'nodes'])
+const OBJECT_NODE_FIELDS = new Set(['type', 'prototype', 'entries'])
+const ARRAY_NODE_FIELDS = new Set(['type', 'length', 'entries'])
+const UNDEFINED_FIELDS = new Set(['tag'])
+const NUMBER_FIELDS = new Set(['tag', 'value'])
+const BIGINT_FIELDS = new Set(['tag', 'value'])
+const REFERENCE_FIELDS = new Set(['tag', 'index'])
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+
+function limitsOf(options = {}) {
+  const limits = { ...DEFAULT_VALUE_LIMITS, ...options }
+  for (const [name, value] of Object.entries(limits)) {
+    if (!Number.isSafeInteger(value) || value < 1) throw new TypeError(`invalid PTC value limit ${name}`)
+  }
+  return limits
+}
+
+function hasIntrinsicConstructor(prototype, name) {
+  const constructor = Object.getOwnPropertyDescriptor(prototype, 'constructor')?.value
+  if (typeof constructor !== 'function') return false
+  try {
+    return constructor.name === name
+      && constructor.prototype === prototype
+      && Function.prototype.toString.call(constructor) === `function ${name}() { [native code] }`
+  } catch {
+    return false
+  }
+}
+
+function isIntrinsicObjectPrototype(value) {
+  return Object.getPrototypeOf(value) === null && hasIntrinsicConstructor(value, 'Object')
+}
+
+function plainObjectPrototype(value) {
+  const prototype = Object.getPrototypeOf(value)
+  if (prototype === null) return 'null'
+  if (typeof prototype === 'object' && isIntrinsicObjectPrototype(prototype)) return 'object'
+  return undefined
+}
+
+function hasPlainArrayPrototype(value) {
+  const prototype = Object.getPrototypeOf(value)
+  if (!Array.isArray(prototype) || !hasIntrinsicConstructor(prototype, 'Array')) return false
+  const objectPrototype = Object.getPrototypeOf(prototype)
+  return objectPrototype !== null && typeof objectPrototype === 'object'
+    && isIntrinsicObjectPrototype(objectPrototype)
+}
+
+function invalid(path, detail) {
+  throw new TypeError(`value at ${path} is not PTC Value V1: ${detail}`)
+}
+
+function stringBytes(value) {
+  return Buffer.byteLength(value, 'utf8')
+}
+
+/** Encode one supported JavaScript graph into the project-owned JSON-safe wire. */
+export function encodeValue(value, options = {}) {
+  const limits = limitsOf(options)
+  const seen = new WeakMap()
+  const pending = []
+  const nodes = []
+  let edgeCount = 0
+  let textBytes = 0
+
+  const accountText = (text, path) => {
+    textBytes += stringBytes(text)
+    if (textBytes > limits.maxStringBytes) invalid(path, `string budget exceeds ${limits.maxStringBytes} bytes`)
+  }
+
+  const atom = (current, path) => {
+    if (current === null || typeof current === 'boolean') return current
+    if (typeof current === 'string') {
+      accountText(current, path)
+      return current
+    }
+    if (typeof current === 'number') {
+      if (Number.isNaN(current)) return { tag: 'number', value: 'nan' }
+      if (current === Infinity) return { tag: 'number', value: 'infinity' }
+      if (current === -Infinity) return { tag: 'number', value: '-infinity' }
+      if (Object.is(current, -0)) return { tag: 'number', value: '-0' }
+      return current
+    }
+    if (current === undefined) return { tag: 'undefined' }
+    if (typeof current === 'bigint') {
+      const text = String(current)
+      const digits = text[0] === '-' ? text.length - 1 : text.length
+      if (digits > limits.maxBigIntDigits) invalid(path, `BigInt exceeds ${limits.maxBigIntDigits} digits`)
+      accountText(text, path)
+      return { tag: 'bigint', value: text }
+    }
+    if (typeof current !== 'object') invalid(path, typeof current)
+    const prior = seen.get(current)
+    if (prior !== undefined) return { tag: 'reference', index: prior }
+    if (nodes.length >= limits.maxNodes) invalid(path, `node budget exceeds ${limits.maxNodes}`)
+    const index = nodes.length
+    seen.set(current, index)
+    nodes.push(undefined)
+    pending.push({ value: current, index, path })
+    return { tag: 'reference', index }
+  }
+
+  const root = atom(value, '$')
+  for (let cursor = 0; cursor < pending.length; cursor += 1) {
+    const item = pending[cursor]
+    const current = item.value
+    if (Array.isArray(current)) {
+      if (!hasPlainArrayPrototype(current)) invalid(item.path, 'non-plain array')
+      if (current.length > limits.maxArrayLength) invalid(item.path, `array length exceeds ${limits.maxArrayLength}`)
+      const entries = []
+      for (const key of Reflect.ownKeys(current)) {
+        if (key === 'length') continue
+        if (typeof key !== 'string' || !/^(0|[1-9][0-9]*)$/.test(key)) {
+          invalid(item.path, 'array has a symbol or non-index property')
+        }
+        const index = Number(key)
+        if (!Number.isSafeInteger(index) || index >= current.length) invalid(`${item.path}[${key}]`, 'invalid array index')
+        const descriptor = Object.getOwnPropertyDescriptor(current, key)
+        if (descriptor === undefined || !Object.hasOwn(descriptor, 'value') || descriptor.enumerable !== true) {
+          invalid(`${item.path}[${key}]`, 'array index must be an enumerable data property')
+        }
+        edgeCount += 1
+        if (edgeCount > limits.maxEdges) invalid(item.path, `edge budget exceeds ${limits.maxEdges}`)
+        entries.push([index, atom(descriptor.value, `${item.path}[${key}]`)])
+      }
+      nodes[item.index] = { type: 'array', length: current.length, entries }
+      continue
+    }
+
+    const prototype = plainObjectPrototype(current)
+    if (prototype === undefined) invalid(item.path, 'non-plain object')
+    const entries = []
+    for (const key of Reflect.ownKeys(current)) {
+      if (typeof key !== 'string') invalid(item.path, 'object has a symbol key')
+      const descriptor = Object.getOwnPropertyDescriptor(current, key)
+      if (descriptor === undefined || !Object.hasOwn(descriptor, 'value') || descriptor.enumerable !== true) {
+        invalid(`${item.path}.${key}`, 'object property must be an enumerable data property')
+      }
+      accountText(key, `${item.path}.${key}`)
+      edgeCount += 1
+      if (edgeCount > limits.maxEdges) invalid(item.path, `edge budget exceeds ${limits.maxEdges}`)
+      entries.push([key, atom(descriptor.value, `${item.path}.${key}`)])
+    }
+    nodes[item.index] = { type: 'object', prototype, entries }
+  }
+  return { codec: VALUE_CODEC, root, nodes }
+}
+
+function decodeAtom(atom, nodes, limits, budget, path) {
+  if (atom === null || typeof atom === 'boolean') return atom
+  if (typeof atom === 'string') {
+    budget.textBytes += stringBytes(atom)
+    if (budget.textBytes > limits.maxStringBytes) throw new TypeError('PTC value string budget exceeded')
+    return atom
+  }
+  if (typeof atom === 'number') {
+    if (!Number.isFinite(atom) || Object.is(atom, -0)) throw new TypeError(`invalid PTC value number at ${path}`)
+    return atom
+  }
+  if (!isRecord(atom) || typeof atom.tag !== 'string') throw new TypeError(`invalid PTC value atom at ${path}`)
+  if (atom.tag === 'undefined') {
+    assertFields(atom, UNDEFINED_FIELDS, 'PTC undefined atom')
+    return undefined
+  }
+  if (atom.tag === 'number') {
+    assertFields(atom, NUMBER_FIELDS, 'PTC number atom')
+    if (atom.value === 'nan') return NaN
+    if (atom.value === 'infinity') return Infinity
+    if (atom.value === '-infinity') return -Infinity
+    if (atom.value === '-0') return -0
+    throw new TypeError('invalid PTC special number')
+  }
+  if (atom.tag === 'bigint') {
+    assertFields(atom, BIGINT_FIELDS, 'PTC BigInt atom')
+    if (typeof atom.value !== 'string' || !/^(0|-[1-9][0-9]*|[1-9][0-9]*)$/.test(atom.value)) {
+      throw new TypeError('invalid PTC BigInt')
+    }
+    const digits = atom.value[0] === '-' ? atom.value.length - 1 : atom.value.length
+    if (digits > limits.maxBigIntDigits) throw new TypeError('PTC BigInt digit budget exceeded')
+    budget.textBytes += stringBytes(atom.value)
+    if (budget.textBytes > limits.maxStringBytes) throw new TypeError('PTC value string budget exceeded')
+    return BigInt(atom.value)
+  }
+  if (atom.tag === 'reference') {
+    assertFields(atom, REFERENCE_FIELDS, 'PTC reference atom')
+    if (!Number.isSafeInteger(atom.index) || atom.index < 0 || atom.index >= nodes.length) {
+      throw new TypeError('dangling PTC value reference')
+    }
+    budget.reachable.add(atom.index)
+    return nodes[atom.index]
+  }
+  throw new TypeError(`unknown PTC value atom tag ${JSON.stringify(atom.tag)}`)
+}
+
+/** Validate, hydrate, and own one canonical PTC value envelope without recursive stack growth. */
+function decodeCanonicalValue(wire, options = {}) {
+  const limits = limitsOf(options)
+  assertFields(wire, ENVELOPE_FIELDS, 'PTC value envelope')
+  if (wire.codec !== VALUE_CODEC || !Array.isArray(wire.nodes)) throw new TypeError('invalid PTC value codec')
+  if (wire.nodes.length > limits.maxNodes) throw new TypeError('PTC value node budget exceeded')
+  const targets = new Array(wire.nodes.length)
+  for (let index = 0; index < wire.nodes.length; index += 1) {
+    const node = wire.nodes[index]
+    if (!isRecord(node)) throw new TypeError(`invalid PTC value node ${index}`)
+    if (node.type === 'array') {
+      assertFields(node, ARRAY_NODE_FIELDS, `PTC array node ${index}`)
+      if (!Number.isSafeInteger(node.length) || node.length < 0 || node.length > limits.maxArrayLength) {
+        throw new TypeError(`invalid PTC array length at node ${index}`)
+      }
+      if (!Array.isArray(node.entries)) throw new TypeError(`invalid PTC array entries at node ${index}`)
+      targets[index] = new Array(node.length)
+    } else if (node.type === 'object') {
+      assertFields(node, OBJECT_NODE_FIELDS, `PTC object node ${index}`)
+      if (!['object', 'null'].includes(node.prototype) || !Array.isArray(node.entries)) {
+        throw new TypeError(`invalid PTC object node ${index}`)
+      }
+      targets[index] = node.prototype === 'null' ? Object.create(null) : {}
+    } else {
+      throw new TypeError(`unknown PTC value node type at ${index}`)
+    }
+  }
+
+  const budget = { edges: 0, textBytes: 0, reachable: new Set() }
+  const root = decodeAtom(wire.root, targets, limits, budget, '$')
+  for (let nodeIndex = 0; nodeIndex < wire.nodes.length; nodeIndex += 1) {
+    const node = wire.nodes[nodeIndex]
+    const target = targets[nodeIndex]
+    if (node.type === 'array') {
+      let previous = -1
+      for (const entry of node.entries) {
+        if (!Array.isArray(entry) || entry.length !== 2 || !Number.isSafeInteger(entry[0])
+          || entry[0] <= previous || entry[0] < 0 || entry[0] >= node.length) {
+          throw new TypeError(`invalid PTC array entry at node ${nodeIndex}`)
+        }
+        previous = entry[0]
+        budget.edges += 1
+        if (budget.edges > limits.maxEdges) throw new TypeError('PTC value edge budget exceeded')
+        Object.defineProperty(target, entry[0], {
+          value: decodeAtom(entry[1], targets, limits, budget, `$nodes[${nodeIndex}][${entry[0]}]`),
+          enumerable: true, configurable: true, writable: true,
+        })
+      }
+      continue
+    }
+    const keys = new Set()
+    for (const entry of node.entries) {
+      if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== 'string' || keys.has(entry[0])) {
+        throw new TypeError(`invalid PTC object entry at node ${nodeIndex}`)
+      }
+      keys.add(entry[0])
+      budget.textBytes += stringBytes(entry[0])
+      if (budget.textBytes > limits.maxStringBytes) throw new TypeError('PTC value string budget exceeded')
+      budget.edges += 1
+      if (budget.edges > limits.maxEdges) throw new TypeError('PTC value edge budget exceeded')
+      Object.defineProperty(target, entry[0], {
+        value: decodeAtom(entry[1], targets, limits, budget, `$nodes[${nodeIndex}].${entry[0]}`),
+        enumerable: true, configurable: true, writable: true,
+      })
+    }
+  }
+  if (budget.reachable.size !== wire.nodes.length) throw new TypeError('PTC value envelope contains unreachable nodes')
+  const canonical = encodeValue(root, limits)
+  const serialization = JSON.stringify(canonical)
+  if (serialization !== JSON.stringify(wire)) throw new TypeError('non-canonical PTC value envelope')
+  return { value: root, wire: canonical, serialization }
+}
+
+/** Validate and hydrate one canonical PTC value envelope without recursive stack growth. */
+export function decodeValue(wire, options = {}) {
+  return decodeCanonicalValue(wire, options).value
+}
+
+export function normalizeValueWire(wire, options = {}) {
+  return decodeCanonicalValue(wire, options).wire
+}
+
+export function valueWiresEqual(left, right, options = {}) {
+  try {
+    return decodeCanonicalValue(left, options).serialization
+      === decodeCanonicalValue(right, options).serialization
+  } catch {
+    return false
+  }
+}
+
+/** True only when the outer structured-result projection preserves the complete value semantics. */
+export function isPlainJsonTree(value) {
+  const pending = [value]
+  const seen = new WeakSet()
+  while (pending.length > 0) {
+    const current = pending.pop()
+    if (current === null || typeof current === 'string' || typeof current === 'boolean') continue
+    if (typeof current === 'number' && Number.isFinite(current) && !Object.is(current, -0)) continue
+    if (typeof current !== 'object') return false
+    if (seen.has(current)) return false
+    seen.add(current)
+    if (Array.isArray(current)) {
+      for (let index = 0; index < current.length; index += 1) {
+        if (!Object.hasOwn(current, index)) return false
+        pending.push(current[index])
+      }
+    } else {
+      for (const key of Object.keys(current)) pending.push(current[key])
+    }
+  }
+  return true
+}
+
+function renderKey(key) {
+  return IDENTIFIER.test(key) ? key : JSON.stringify(key)
+}
+
+function atomText(atom) {
+  if (atom === null || typeof atom === 'boolean' || typeof atom === 'number') return String(atom)
+  if (typeof atom === 'string') return JSON.stringify(atom)
+  if (atom.tag === 'undefined') return 'undefined'
+  if (atom.tag === 'number') {
+    return atom.value === 'nan' ? 'NaN'
+      : atom.value === 'infinity' ? 'Infinity'
+        : atom.value === '-infinity' ? '-Infinity' : '-0'
+  }
+  if (atom.tag === 'bigint') return `${atom.value}n`
+  return undefined
+}
+
+/** Deterministic bounded TS-like presentation. It is never a decode format. */
+export function renderValueWire(wire, options = {}) {
+  const limits = limitsOf(options)
+  const normalized = normalizeValueWire(wire, limits)
+  const references = new Array(normalized.nodes.length).fill(0)
+  const count = (atom) => {
+    if (isRecord(atom) && atom.tag === 'reference') references[atom.index] += 1
+  }
+  count(normalized.root)
+  for (const node of normalized.nodes) for (const entry of node.entries) count(entry[1])
+  const labels = new Map()
+  let nextLabel = 0
+  for (let index = 0; index < references.length; index += 1) {
+    if (references[index] > 1) labels.set(index, ++nextLabel)
+  }
+
+  const chunks = []
+  let bytes = 0
+  const append = (text) => {
+    bytes += stringBytes(text)
+    if (bytes > limits.maxStringBytes) throw new TypeError(`rendered PTC value exceeds ${limits.maxStringBytes} bytes`)
+    chunks.push(text)
+  }
+  const emitted = new Set()
+  const active = new Set()
+  const tasks = [{ kind: 'atom', atom: normalized.root }]
+  while (tasks.length > 0) {
+    const task = tasks.pop()
+    if (task.kind === 'text') {
+      append(task.text)
+      continue
+    }
+    if (task.kind === 'leave') {
+      active.delete(task.index)
+      continue
+    }
+    const primitive = atomText(task.atom)
+    if (primitive !== undefined) {
+      append(primitive)
+      continue
+    }
+    const index = task.atom.index
+    const label = labels.get(index)
+    if (emitted.has(index)) {
+      append(active.has(index) ? `[Circular *${label}]` : `[Reference *${label}]`)
+      continue
+    }
+    emitted.add(index)
+    active.add(index)
+    if (label !== undefined) append(`<ref *${label}> `)
+    const node = normalized.nodes[index]
+    tasks.push({ kind: 'leave', index })
+    if (node.type === 'array') {
+      append('[')
+      tasks.push({ kind: 'text', text: ']' })
+      const entries = new Map(node.entries)
+      if (node.length > 0 && !entries.has(node.length - 1)) tasks.push({ kind: 'text', text: ',' })
+      for (let item = node.length - 1; item >= 0; item -= 1) {
+        if (item < node.length - 1) tasks.push({ kind: 'text', text: ', ' })
+        const value = entries.get(item)
+        if (value !== undefined) tasks.push({ kind: 'atom', atom: value })
+      }
+      continue
+    }
+    append('{')
+    tasks.push({ kind: 'text', text: '}' })
+    for (let entryIndex = node.entries.length - 1; entryIndex >= 0; entryIndex -= 1) {
+      const [key, value] = node.entries[entryIndex]
+      if (entryIndex < node.entries.length - 1) tasks.push({ kind: 'text', text: ', ' })
+      tasks.push({ kind: 'atom', atom: value })
+      tasks.push({ kind: 'text', text: `${renderKey(key)}: ` })
+    }
+  }
+  return chunks.join('')
+}
+
+/**
+ * Return a lossless outer value: plain JSON values stay structured; richer values become rendered
+ * text. The untagged ranges overlap because a plain JSON root may itself be a string.
+ */
+export function projectValueWire(wire, options = {}) {
+  const value = decodeValue(wire, options)
+  return isPlainJsonTree(value) ? value : renderValueWire(wire, options)
+}

package/internal/worker-client.js

@@ -0,0 +1,218 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { isAbsolute, join } from 'node:path'
+import { Worker } from 'node:worker_threads'
+import { messageOf } from './failure-reporting.js'
+
+const WINDOWS_ENVIRONMENT_NAMES = new Map([
+  ['appdata', 'APPDATA'],
+  ['comspec', 'ComSpec'],
+  ['home', 'HOME'],
+  ['homedrive', 'HOMEDRIVE'],
+  ['homepath', 'HOMEPATH'],
+  ['localappdata', 'LOCALAPPDATA'],
+  ['path', 'PATH'],
+  ['pathext', 'PATHEXT'],
+  ['programdata', 'ProgramData'],
+  ['programfiles', 'ProgramFiles'],
+  ['programfiles(x86)', 'ProgramFiles(x86)'],
+  ['systemdrive', 'SystemDrive'],
+  ['systemroot', 'SystemRoot'],
+  ['temp', 'TEMP'],
+  ['tmp', 'TMP'],
+  ['userprofile', 'USERPROFILE'],
+  ['windir', 'windir'],
+])
+const HOST_ONLY_ENVIRONMENT_NAMES = new Set(['node_test_context', 'node_v8_coverage'])
+
+/** Project the host environment once without losing Windows case variants. */
+export function normalizeWorkerEnvironment(source, platform = process.platform) {
+  if (platform !== 'win32') {
+    return Object.fromEntries(Object.entries(source).filter(([name, value]) => (
+      value !== undefined && !HOST_ONLY_ENVIRONMENT_NAMES.has(name.toLowerCase())
+    )))
+  }
+  const normalized = new Map()
+  for (const [name, value] of Object.entries(source)) {
+    if (value === undefined) continue
+    const key = name.toLowerCase()
+    if (HOST_ONLY_ENVIRONMENT_NAMES.has(key)) continue
+    const canonicalName = WINDOWS_ENVIRONMENT_NAMES.get(key) ?? name
+    const current = normalized.get(key)
+    if (current === undefined || name === canonicalName) {
+      normalized.set(key, [canonicalName, value])
+    }
+  }
+  return Object.fromEntries(normalized.values())
+}
+
+/** Owns one session kernel's worker process, private port, and scratch directory. */
+export class WorkerClient {
+  constructor({ workerUrl, cwd, onMessage, onFailure }) {
+    this.workerUrl = workerUrl
+    this.cwd = cwd
+    this.onMessage = onMessage
+    this.onFailure = onFailure
+    this.worker = undefined
+    this.workerLimit = undefined
+    this.workerReady = undefined
+    this.port = undefined
+    this.scratchReady = undefined
+    this.stderrTails = new WeakMap()
+    this.terminations = new Set()
+    this.disposed = false
+  }
+
+  /** Last non-empty stderr line of a failed worker, capped for diagnostics. */
+  stderrDetail(worker) {
+    const tail = this.stderrTails.get(worker)?.join('').trim()
+    if (tail === undefined || tail.length === 0) return undefined
+    const lastLine = tail.split(/\r?\n/).map(line => line.trim()).filter(line => line.length > 0).slice(-1)[0]
+    return lastLine === undefined ? undefined : lastLine.slice(0, 300)
+  }
+
+  async ensure(maxOldGenerationSizeMb) {
+    if (this.workerLimit !== undefined && this.workerLimit !== maxOldGenerationSizeMb) {
+      throw new Error('ptc-plus: session worker memory limit differs from the submitted cell configuration')
+    }
+    if (this.worker !== undefined) return this.workerReady
+    if (this.scratchReady === undefined) {
+      const scratchRoot = tmpdir()
+      if (!isAbsolute(scratchRoot)) {
+        throw new Error(`ptc-plus: host temporary directory must be absolute, got ${JSON.stringify(scratchRoot)}`)
+      }
+      this.scratchReady = mkdtemp(join(scratchRoot, 'dsh-ptc-plus-'))
+    }
+    this.workerLimit = maxOldGenerationSizeMb
+    let scratchDirectory
+    try {
+      scratchDirectory = await this.scratchReady
+    } catch (error) {
+      if (this.worker === undefined) this.workerLimit = undefined
+      throw error
+    }
+    /* c8 ignore next */
+    if (this.disposed) {
+      this.workerLimit = undefined
+      throw new Error('session kernel disposed')
+    }
+    /* c8 ignore next */
+    if (this.worker !== undefined) return this.workerReady
+    const environment = normalizeWorkerEnvironment(process.env)
+    let worker
+    try {
+      worker = new Worker(this.workerUrl, {
+        env: {
+          ...environment,
+          TEMP: scratchDirectory,
+          TMP: scratchDirectory,
+          TMPDIR: scratchDirectory,
+        },
+        execArgv: [],
+        workerData: this.cwd === undefined ? {} : { cwd: this.cwd },
+        resourceLimits: { maxOldGenerationSizeMb: this.workerLimit },
+        stdout: true,
+        stderr: true,
+      })
+    } catch (error) {
+      this.workerLimit = undefined
+      throw error
+    }
+    worker.stdout.resume()
+    worker.stderr.resume()
+    const stderrTail = []
+    worker.stderr.on?.('data', (chunk) => {
+      const text = typeof chunk === 'string' ? chunk : String(chunk ?? '')
+      stderrTail.push(text)
+      const bounded = Buffer.from(stderrTail.join('')).subarray(-2048).toString('utf8')
+      stderrTail.splice(0, stderrTail.length, bounded)
+    })
+    this.stderrTails.set(worker, stderrTail)
+    worker.on('error', error => this.fail(worker, `worker error: ${messageOf(error)}`))
+    worker.on('exit', code => this.fail(worker, `worker exited with code ${code}`))
+    this.worker = worker
+    this.workerReady = new Promise((resolve, reject) => {
+      const onError = error => reject(error)
+      const onExit = (code) => {
+        const detail = this.stderrDetail(worker)
+        reject(new Error(detail === undefined
+          ? `worker exited with code ${code} before opening its private channel`
+          : `worker exited with code ${code} before opening its private channel; last stderr: ${detail}`))
+      }
+      worker.once('error', onError)
+      worker.once('exit', onExit)
+      worker.once('message', (message) => {
+        worker.removeListener('error', onError)
+        worker.removeListener('exit', onExit)
+        if (message?.type === 'startup-error' && typeof message.error === 'string') {
+          reject(new Error(message.error))
+          void this.reset(worker)
+          return
+        }
+        if (message?.type !== 'ready' || typeof message.port?.postMessage !== 'function') {
+          reject(new Error('kernel worker returned an invalid private channel'))
+          void this.reset(worker)
+          return
+        }
+        this.port = message.port
+        this.port.on('message', (value) => {
+          if (worker === this.worker) this.onMessage(value)
+        })
+        resolve(worker)
+      })
+    })
+    return this.workerReady
+  }
+
+  post(message) {
+    this.port.postMessage(message)
+  }
+
+  /** Best-effort reply for a request whose lease may outlive a worker reset. */
+  postIfAlive(message) {
+    this.port?.postMessage(message)
+  }
+
+  fail(worker, message) {
+    if (worker !== this.worker) return
+    this.worker = undefined
+    this.workerLimit = undefined
+    this.workerReady = undefined
+    this.port?.close()
+    this.port = undefined
+    const detail = this.stderrDetail(worker)
+    this.onFailure(detail === undefined ? message : `${message}; last stderr: ${detail}`)
+  }
+
+  async reset(worker) {
+    if (this.worker === worker) {
+      this.worker = undefined
+      this.workerLimit = undefined
+      this.workerReady = undefined
+      this.port?.close()
+      this.port = undefined
+    }
+    const termination = worker.terminate()
+    this.terminations.add(termination)
+    try {
+      await termination
+    } finally {
+      this.terminations.delete(termination)
+    }
+  }
+
+  async dispose() {
+    this.disposed = true
+    const worker = this.worker
+    if (worker !== undefined) await this.reset(worker)
+    await Promise.all([...this.terminations])
+    if (this.scratchReady !== undefined) {
+      try {
+        const scratchDirectory = await this.scratchReady
+        await rm(scratchDirectory, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 })
+      } catch {
+        // Scratch cleanup is best-effort after all worker handles are closed.
+      }
+    }
+  }
+}