dsh-ptc-plus 0.4.10 → 0.5.1

package/internal/session-runtime.js

@@ -10,12 +10,14 @@ import {
   reduceStateOperations,
 } from './session-journal.js'
 import {
+  foldSessionTimeline,
   pathToHead,
   recoveryBoundaryForHistory,
   recoverJournal,
   visibleExecutableCallSeqs,
 } from './session-journal-recovery.js'
 import { valueLimitsFromConfig } from './value-wire-schema.js'
+import { encodeValueAtBoundary, valueWiresEqual } from './value-wire.js'
 import { normalizeBindingDescriptors } from './binding-descriptors.js'
 import { resolveConfig } from './runtime-config.js'
 import { WorkerClient } from './worker-client.js'
@@ -26,6 +28,7 @@ import { executionPolicies } from './binding-update-policy.js'
 import {
   createReplMemorySnapshot,
   normalizeReplMemorySnapshot,
+  REPL_MEMORY_META_KEY,
   unavailableReplMemorySnapshot,
 } from './repl-memory-projection.js'
 
@@ -34,8 +37,12 @@ const UNAVAILABLE_SURFACE_GENERATION = Symbol('unavailableSurfaceGeneration')
 
 function surfaceGeneration(session, provenanceRequired = true) {
   try {
-    return session?.surface?.replaceGeneration
-      ?? (provenanceRequired ? UNAVAILABLE_SURFACE_GENERATION : undefined)
+    const surface = session?.surface
+    const generation = surface?.replaceGeneration
+    if (generation === undefined) return provenanceRequired ? UNAVAILABLE_SURFACE_GENERATION : undefined
+    return surface.contentGeneration === undefined
+      ? generation
+      : `${generation}:${surface.contentGeneration}`
   } catch {
     return provenanceRequired ? UNAVAILABLE_SURFACE_GENERATION : undefined
   }
@@ -96,6 +103,7 @@ class SessionKernel {
     this.recoveryNotice = history.volatileSuffix.length === 0
       ? undefined
       : recoveryDiagnostic(history.volatileSuffix.length)
+    this.recoveryNoticeShown = false
     this.active = undefined
     this.sequence = 0
     this.tail = Promise.resolve()
@@ -144,17 +152,25 @@ class SessionKernel {
     } catch (error) {
       record.failed = true
       record.reason = error
-      return
+      return Promise.resolve(record)
     }
     const attempt = Promise.resolve(reset).then(
-      () => { this.reclamationRecords.delete(sequence) },
+      () => { this.reclamationRecords.delete(sequence); return record },
       error => {
         record.failed = true
         record.reason = error
+        return record
       },
     )
     this.reclamationAttempts.add(attempt)
     attempt.then(() => { this.reclamationAttempts.delete(attempt) })
+    return attempt
+  }
+
+  async prepareWorker() {
+    await Promise.all([...this.reclamationAttempts])
+    const failures = [...this.reclamationRecords.values()].filter(record => record.failed).map(record => record.reason)
+    if (failures.length) throw new AggregateError(failures, 'previous computation helper reclamation failed; dispose the session before continuing')
   }
 
   valueLimits(config = this.config) {
@@ -333,14 +349,12 @@ class SessionKernel {
       }
       if (skipped > 0) this.recoveryNotice = recoveryDiagnostic(skipped)
     }
-    const leadingDiagnostics = this.recoveryNotice === undefined ? [] : [this.recoveryNotice]
+    const leadingDiagnostics = this.recoveryNotice === undefined || this.recoveryNoticeShown
+      ? [] : [this.recoveryNotice]
+    this.recoveryNoticeShown = this.recoveryNotice !== undefined
     this.recoveryNotice = undefined
     if (request.journal !== undefined) request.journal.diagnostics.push(...leadingDiagnostics)
     const result = await this.cellExecutor.executeCell(request, undefined, config)
-    if (leadingDiagnostics.length > 0) {
-      const rendered = leadingDiagnostics.map(item => renderDiagnostic(item, request.program))
-      result.logs = [...rendered, ...result.logs]
-    }
     if (result.error === undefined) {
       this.failures.reset()
     } else {
@@ -351,17 +365,29 @@ class SessionKernel {
         if (request.journal !== undefined) request.journal.diagnostics.push(hint)
       }
     }
+    if (leadingDiagnostics.length > 0) {
+      const rendered = leadingDiagnostics.map(item => renderDiagnostic(item, request.program))
+      if (result.error === undefined) result.logs = [...rendered, ...result.logs]
+      else result.error = { ...result.error, message: [result.error.message, ...rendered].join('\n') }
+    }
     return finishResult(result)
   }
 
   async replayHistory(request, config) {
     this.bindingCatalog = new BindingCatalog()
+    const limits = this.valueLimits(config)
+    const emptyArgsWire = encodeValueAtBoundary({}, limits, 'parameter')
     const path = pathToHead(this.history)
     for (const node of path) {
+      const bindings = replayBindingNamespaces(request.bindings, node.journal, limits, emptyArgsWire)
+      const bindingDescriptors = bindings === request.bindings
+        ? request.bindingDescriptors : normalizeBindingDescriptors(bindings)
       try {
         const result = await this.cellExecutor.executeCell(
           {
             ...request,
+            bindings: bindingDescriptors.namespaces,
+            bindingDescriptors,
             program: node.code,
             journal: undefined,
             ...(node.userBindings === undefined ? { userBindings: undefined } : { userBindings: node.userBindings }),
@@ -476,7 +502,17 @@ class SessionKernel {
       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)
+      void this.resetWorker(worker).then(record => {
+        if (record.failed) {
+          result = { ...result, error: { ...result.error,
+            message: `${result.error?.message ?? 'cell terminated'}; helper reclamation failed: ${String(record.reason?.message ?? record.reason)}` } }
+          if (journal !== undefined && replay === undefined) {
+            this.completeJournal(journal, 'discarded', result, journal.volatileReason, active.diagnostics)
+          }
+        }
+        active.finish(result)
+      })
+      return
     }
     if (!terminate && active.observing && replay === undefined) {
       // Computation and journal settlement are complete. Observation cannot change either.
@@ -621,11 +657,47 @@ function sessionOf(sessionContext) {
     session,
     callId: sessionContext.callId,
     persistedCallSeq: sessionContext.persistedCallSeq,
+    sourceCallSeq: sessionContext.sourceCallSeq,
     cwd: typeof session?.header?.cwd === 'string' ? session.header.cwd : undefined,
     surfaceProvenanceRequired: true,
   }
 }
 
+/**
+ * Recorded-value replay settles a host call from its journal entry without
+ * dispatching it. A member the Host no longer supplies must therefore stay
+ * visible to the replayed cell as a replay-only stub; otherwise a routine
+ * capability removal would make an otherwise provable cell unreconstructable
+ * and contract the durable frontier. Zero-argument calls keep their recorded
+ * empty-object form so the args wire still matches the journal.
+ */
+function replayBindingNamespaces(namespaces, journal, limits, emptyArgsWire) {
+  const calls = journal?.calls ?? []
+  let changed = false
+  const next = namespaces.map(namespace => {
+    const recorded = calls.filter(call => call.global === namespace.global)
+    const missing = [...new Set(recorded.map(call => call.member))]
+      .filter(member => !namespace.members.includes(member))
+    if (missing.length === 0) return namespace
+    changed = true
+    const functions = { ...namespace.functions }
+    const emptyObjectMembers = [...(namespace.emptyObjectMembers ?? [])]
+    for (const member of missing) {
+      // The replay executor settles or rejects every host-binding call from the
+      // recorded journal, so the placeholder keeps the member visible without
+      // ever running; the throw only guards a dispatch path that would bypass
+      // recorded-value interception.
+      /* c8 ignore next -- replay interception precedes invocation */
+      functions[member] = () => { throw new Error(`replay-only member ${namespace.global}.${member}`) }
+      if (recorded.some(call => call.member === member && valueWiresEqual(call.args, emptyArgsWire, limits))) {
+        emptyObjectMembers.push(member)
+      }
+    }
+    return { ...namespace, functions, emptyObjectMembers }
+  })
+  return changed ? next : namespaces
+}
+
 export class SessionRuntime {
   constructor(config = {}, options = {}) {
     this.config = resolvedRuntimeConfig(config)
@@ -642,6 +714,7 @@ export class SessionRuntime {
     this.withInitiator = typeof options.withInitiator === 'function' ? options.withInitiator : undefined
     this.observeSession = options.observeSession ?? (() => false)
     this.readSessionLog = options.readSessionLog ?? (async session => session)
+    this.sessionForId = options.sessionForId
     this.disposal = undefined
   }
 
@@ -686,10 +759,32 @@ export class SessionRuntime {
     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)
+    const kernel = this.kernels.get(sessionId)
+    const session = kernel?.session ?? this.sessionForId?.(sessionId)
+    if (session !== undefined && kernel?.surfaceProvenanceRequired !== false) {
+      const observed = await this.readSessionLog(session, signal)
+      signal?.throwIfAborted()
+      const visible = visibleExecutableCallSeqs(observed)
+      if (kernel !== undefined) {
+        if ([...kernel.liveCallSeqs].some(seq => !visible.has(seq))) return unavailableReplMemorySnapshot()
+        kernel.surfaceGeneration = surfaceGeneration(session)
+      } else {
+        const timeline = foldSessionTimeline(observed.events)
+        const history = recoverJournal(observed, undefined, { visibleCallSeqs: visible })
+        const head = history.nodes[history.head]
+        if (head === undefined) return unavailableReplMemorySnapshot()
+        // A cold inventory can describe a proved recorded frontier without
+        // instantiating a worker. It cannot describe a discarded suffix.
+        const resultSeq = timeline.results.get(head.callSeq)?.eventSeq
+        const result = observed.events.find(event => event.type === 'tool/result' && event.seq === resultSeq)
+        const recorded = result?.data?.meta?.[REPL_MEMORY_META_KEY]?.memory
+        if (!isDeepStrictEqual(recorded, memory)) return unavailableReplMemorySnapshot()
+      }
+    }
+    return kernel?.observe(expected, signal)
   }
 
-  async runTentative(sessionContext, request) {
+  async runTentative(sessionContext, request, { programCompletion = false } = {}) {
     const completed = result => Object.freeze({ result, settlement: undefined })
     if (this.disposed) return completed({ logs: [], error: { kind: 'abort', message: 'PTC runtime disposed' } })
     let bindingDescriptors
@@ -699,11 +794,15 @@ export class SessionRuntime {
       return completed({ logs: [], error: { kind: 'exception', message: messageOf(error) } })
     }
     request = { ...request, bindings: bindingDescriptors.namespaces, bindingDescriptors }
+    if (request.cwd !== undefined && (typeof request.cwd !== 'string' || !isAbsolute(request.cwd))) {
+      return completed({ logs: [], error: { kind: 'exception', message: 'PTC execution cwd must be an absolute path' } })
+    }
     const {
       id: sessionId,
       session,
       callId,
       persistedCallSeq,
+      sourceCallSeq: provedSourceCallSeq,
       cwd,
       surfaceProvenanceRequired,
     } = sessionOf(sessionContext)
@@ -726,11 +825,15 @@ export class SessionRuntime {
         && !isCanonicalSequence(persistedCallSeq)) {
         throw new Error('persisted tool call sequence must be a non-negative safe integer')
       }
+      if (provedSourceCallSeq !== undefined
+        && !isCanonicalSequence(provedSourceCallSeq)) {
+        throw new Error('source tool call sequence must be a non-negative safe integer')
+      }
       if (cellConfig.durableReplay) {
-        sourceCallSeq = liveToolCallSeq(sessionLog, callId, 'run_code')
+        sourceCallSeq = provedSourceCallSeq ?? liveToolCallSeq(sessionLog, callId, 'run_code')
         callSeq = persistedCallSeq ?? sourceCallSeq
       } else {
-        sourceCallSeq = persistedCallSeq
+        sourceCallSeq = provedSourceCallSeq ?? persistedCallSeq
         if (sourceCallSeq === undefined) {
           try {
             sourceCallSeq = liveToolCallSeq(sessionLog, callId, 'run_code')
@@ -779,11 +882,12 @@ export class SessionRuntime {
       policies.rewritesEnabled,
       policies.languageSemantics,
       policies.moduleTransform,
+      request.cwd ?? cwd ?? null,
     )
     const workerReservation = kernel.reserveWorkerConfiguration(cellConfig)
     let result
     try {
-      result = await kernel.run({ ...request, journal, callSeq, sourceCallSeq, sessionLog }, cellConfig)
+      result = await kernel.run({ ...request, journal, callSeq, sourceCallSeq, sessionLog, programCompletion }, cellConfig)
     } finally {
       kernel.releaseWorkerConfiguration(workerReservation)
     }

package/internal/settings-compat.js

@@ -36,12 +36,16 @@ export function hostOwnsSettingsDocument(settingsModule) {
  * @returns the Cordis schema field for that definition.
  */
 export function configFieldSchema({ Schema, field, settingsModule }) {
-  const base = field.type === 'boolean'
-    ? Schema.boolean().default(field.default)
+  const schema = field.type === 'boolean'
+    ? Schema.boolean()
+    : field.type === 'string'
+      ? Schema.string()
     : field.type === 'enum'
-      // Keep omission visible until resolveConfig migrates legacy policies.
       ? Schema.union(field.options.map(option => Schema.const(option)))
-      : Schema.number().step(1).min(field.min).max(field.max).default(field.default)
+      : Schema.number().step(1).min(field.min).max(field.max)
+  // Migration must distinguish omitted legacy inputs from explicit new choices.
+  // Runtime defaults belong to resolveConfig; the Host must preserve omission.
+  const base = field.preserveOmission || field.type === 'enum' ? schema : schema.default(field.default)
   const described = base.description(field.description)
   if (!hostOwnsSettingsDocument(settingsModule)) return described
   if (typeof described.volatile !== 'function') {
@@ -68,7 +72,10 @@ export function installSettingsSectionCompat({
     const writeNamespace = sectionInstalled ? namespace : (ownerFiber ?? ctx.fiber)?.entry?.options?.id
     const writer = typeof provider?.update === 'function'
       && typeof writeNamespace === 'string' && writeNamespace.length > 0
-      ? Object.freeze({ update: patch => provider.update(writeNamespace, patch) }) : undefined
+      ? Object.freeze({
+        update: (patch, expectedRevision) => provider.update(writeNamespace, patch, expectedRevision),
+        read: () => provider.describe?.().find(descriptor => descriptor.ns === writeNamespace),
+      }) : undefined
     const unbind = onProvider(provider, writer)
     if (typeof unbind === 'function') settingsContext.effect(() => unbind, 'ptc-plus settings writer')
     if (typeof provider?.installSection === 'function') {

package/internal/stateful-module-compiler.js

@@ -96,9 +96,9 @@ export function createUserModuleCompilationHooks({ transformForParent = () => un
       }
     }
   }
-  const recordResolution = (parentUrl, specifier, importAttributes, result) => {
+  const recordResolution = (parentUrl, specifier, importAttributes, result,
+    transform = mapGet(modules, parentUrl) ?? transformForParent(parentUrl)) => {
     recordStatefulModuleResolution(parentUrl, specifier, importAttributes, result.url)
-    const transform = mapGet(modules, parentUrl) ?? transformForParent(parentUrl)
     // Runtime links are outside the user compilation graph. Skipping only
     // their load would still propagate user transforms to their dependencies.
     if (transform !== undefined && !startsWith(result.url, 'node:')
@@ -106,6 +106,7 @@ export function createUserModuleCompilationHooks({ transformForParent = () => un
   }
   return {
     mark,
+    recordResolution,
     resolve(specifier, context, nextResolve) {
       const evidence = commonJsEvidence.resolve(specifier, context, recordResolution)
       if (evidence !== undefined) return evidence

package/internal/stateful-module-runtime.js

@@ -198,7 +198,7 @@ const nativeModuleRealm = {
   importModule: (source, options) => import(source, options),
 }
 
-export function managedModuleImport(parentUrl, specifier, options, realm = nativeModuleRealm) {
+export function managedModuleImport(parentUrl, specifier, options, realm = nativeModuleRealm, recordResolution) {
   return new realm.Promise((resolve, reject) => {
     // Template conversion follows native import's ToString (including Symbols).
     const source = realm.stringify(specifier)
@@ -216,6 +216,7 @@ export function managedModuleImport(parentUrl, specifier, options, realm = nativ
       if (request !== url) return nextResolve(request, context)
       const resolution = nextResolve(source, { ...context, parentURL: parentUrl })
       const attributes = resolution.importAttributes ?? context.importAttributes
+      recordResolution?.(parentUrl, source, attributes, resolution)
       return { url: resolveManagedModuleAdapter(resolution, attributes), format: 'module',
         importAttributes: attributes, shortCircuit: true }
     })
@@ -259,13 +260,16 @@ export function loadManagedModuleAdapter(url) {
 }
 
 /** Only PTC-provided require paths decode formally compiled ESM returns. */
-export function managedRequire(parentUrl, nativeRequire) {
+export function managedRequire(parentUrl, nativeRequire, recordResolution) {
   const acquire = (target, receiver, args) => {
     let url
     let value
     const dispose = registerModuleResolutionHook((source, context, nextResolve) => {
       const result = nextResolve(source, context)
-      if (source === args[0] && url === undefined) url = result.url
+      if (source === args[0] && url === undefined) {
+        url = result.url
+        recordResolution?.(parentUrl, source, context.importAttributes, result)
+      }
       return result
     })
     try {

package/internal/stateful-root-runtime.js

@@ -13,7 +13,7 @@ export function createStatefulRootRuntime({ readAmbient, typeofAmbient, writeAmb
   const entries = new Map()
   const intrinsics = captureCompilerIntrinsics(dynamicIntrinsics?.realmFunction)
   errors ??= intrinsics
-  const dynamicRuntime = createDynamicEnvironmentRuntime({ ...dynamicIntrinsics, importModule })
+  const defaultDynamicRuntime = createDynamicEnvironmentRuntime({ ...dynamicIntrinsics, importModule })
   const moduleRuntime = dynamicIntrinsics === undefined ? undefined : createDynamicEnvironmentRuntime()
   let commit
   const read = name => {
@@ -59,7 +59,11 @@ export function createStatefulRootRuntime({ readAmbient, typeofAmbient, writeAmb
     return value
   }
   const begin = ({ declared = [], known = [], readOnly = [], legacyImports = [], legacyWritable = [], legacyLexicals = [], legacyObjects = [],
-    declarationKinds = [], declaredKinds = [], callableSources = [], languageSemantics = 'stateful-v1', committed }) => {
+    declarationKinds = [], declaredKinds = [], callableSources = [], languageSemantics = 'stateful-v1', committed,
+    importModule: cellImportModule = importModule }) => {
+    // Each cell owns dynamic-source resolution; shared logical roots remain live.
+    const dynamicRuntime = createDynamicEnvironmentRuntime({ ...dynamicIntrinsics,
+      importModule: cellImportModule }).installIntrinsics()
     dynamicRuntime.registerSources(callableSources)
     commit = committed
     const kinds = new Map()
@@ -127,7 +131,7 @@ export function createStatefulRootRuntime({ readAmbient, typeofAmbient, writeAmb
     const result = {
       values,
       intrinsics,
-      importModule,
+      importModule: cellImportModule,
       dynamic({ realm = false } = {}) {
         const pendingKinds = new Map()
         for (let index = 0; index < declaredKinds.length; index++) mapSet(pendingKinds, declaredKinds[index][0], declaredKinds[index][1])
@@ -155,6 +159,7 @@ export function createStatefulRootRuntime({ readAmbient, typeofAmbient, writeAmb
         const varFrame = { has: name => variableKind(kindFor(name)), get: name => varFrame.has(name) ? descriptor(name, 'var') : undefined,
           set() {} }
         return dynamicRuntime.environment({
+          importModule: cellImportModule,
           varFrame, frames: [{ kind: 'lexical', bindings: lexicalFrame }],
           declareVars: realm ? (names, functionNames) => {
             const globals = []
@@ -288,7 +293,7 @@ export function createStatefulRootRuntime({ readAmbient, typeofAmbient, writeAmb
     // Only new-generation environments select intrinsic interfaces. Native
     // global/prototype properties and saved legacy identities remain intact.
     if (dynamicIntrinsics !== undefined) {
-      dynamicRuntime.installIntrinsics()
+      defaultDynamicRuntime.installIntrinsics()
       moduleRuntime.installIntrinsics()
     }
     return result

package/internal/user-binding-authoring.js

@@ -37,14 +37,9 @@ export const BINDING_SUBMISSION = deepFreeze({
 })
 
 export const BINDING_AUTHORING_SDK = `
-During /binding, submit a draft for user review from run_code using the supplied requestId. Submission does not save, enable or execute it.
+/binding only: copy its requestId; submission does not save, enable or run the draft.
 \`\`\`ts
-declare namespace code {
-  function submitBindingDraft(args: {
-    requestId: string;
-    entry: { id: string; name: string; scope: "namespace" | "top-level"; symbols?: string[]; purpose: string; source: string; modelContext?: { includeDeclaration?: boolean; instructions?: string } };
-  }): Promise<{ accepted: true; id: string; requestId: string }>;
-}
+declare namespace code { function submitBindingDraft(args: { requestId: string; entry: { id: string; name: string; scope: "namespace" | "top-level"; symbols?: string[]; purpose: string; source: string; modelContext?: { includeDeclaration?: boolean; instructions?: string } } }): Promise<{ accepted: true; id: string; requestId: string }> }
 \`\`\``
 
 export function bindingAuthoringInstructions(requestId, cwd) {

package/internal/user-bindings-owner.js

@@ -1,4 +1,5 @@
 import { PTC_MESSAGE_SOURCE_KIND } from './message-sources.js'
+import { bindingToggleMessage } from './binding-toggle-receipt.js'
 import { RPC_CONTRACTS } from './rpc-contract.js'
 import { randomUUID } from 'node:crypto'
 import { dirname } from 'node:path'
@@ -378,13 +379,29 @@ export function createUserBindingsOwner(ctx, options = {}) {
   }
   // Fixed endpoint tables grouped by domain; the dispatcher only looks up the
   // operation, rejects unknown endpoints and hands over the validated input.
+  const setEnabled = async (input, requested) => {
+    const next = await store.setEnabled(input.id, requested, input.expectedRevision)
+    const entry = next.entries.find(entry => entry.id === input.id)
+    if (entry === undefined) throw new Error('saved binding missing from confirmed catalog')
+    const sessions = new Set((ctx.agents?.list?.() ?? []).map(agent => agent.session).filter(Boolean))
+    for (const session of sessions) {
+      try {
+        // Before the first accepted step these are initial settings, not changes
+        // to an environment the model has received. The catalog owns first delivery.
+        if (session.deriveMessages()[0]?.role !== 'system') continue
+        const message = createUserMessage(bindingToggleMessage(entry, next.revision))
+        session.append('user/message', message, { surfaceOp: 'append' })
+      } catch (error) { reportContainedFailure('ptc-plus: binding configuration saved but its session receipt could not be appended', error) }
+    }
+    return next
+  }
   const storageEndpoints = Object.freeze({
     list: () => store.list(),
     load: input => store.entry(input.id),
     reload: () => store.reload(),
     save: saveEntry,
-    enable: input => store.setEnabled(input.id, true, input.expectedRevision),
-    disable: input => store.setEnabled(input.id, false, input.expectedRevision),
+    enable: input => setEnabled(input, true),
+    disable: input => setEnabled(input, false),
     remove: input => store.remove(input.id, input.expectedRevision),
     import: input => store.importFile(input.path, input.expectedRevision, input.options),
     validate: input => validateEntry(input.entry),

package/internal/validated-parse-repair.js

@@ -53,7 +53,7 @@ function renderInvocation(argumentsValue) {
   const json = JSON.stringify(argumentsValue)
     .replaceAll('\u2028', '\\u2028')
     .replaceAll('\u2029', '\\u2029')
-  return `edit_run_code(${json})`
+  return `await tools.edit_run_code(${json})`
 }
 
 /** Requires exactly one valid suffix across all one- and two-token EOF closures. */

package/internal/value-wire.js

@@ -1,3 +1,4 @@
+import { types } from 'node:util'
 import { assertFields, isRecord } from './record-utils.js'
 import { runtimeIntrinsics as internal } from './runtime-intrinsics.js'
 import {
@@ -23,6 +24,9 @@ const intrinsicFunctionToString = Function.prototype.toString
 const reflectApply = Reflect.apply
 const bufferByteLength = internal.bufferByteLength
 const jsonStringify = JSON.stringify
+const { isProxy, isDate, isMap, isSet, isRegExp, isAnyArrayBuffer, isTypedArray,
+  isDataView, isNativeError, isPromise, isWeakMap, isWeakSet } = types
+const encodingFailures = new WeakMap()
 
 function limitsOf(options = {}) {
   const limits = { ...DEFAULT_VALUE_LIMITS, ...options }
@@ -36,19 +40,16 @@ function limitsOf(options = {}) {
 }
 
 function hasIntrinsicConstructor(prototype, name) {
+  if (isProxy(prototype)) return false
   const constructor = Object.getOwnPropertyDescriptor(prototype, 'constructor')?.value
-  if (typeof constructor !== 'function') return false
-  try {
-    return constructor.name === name
-      && constructor.prototype === prototype
-      && reflectApply(intrinsicFunctionToString, constructor, []) === `function ${name}() { [native code] }`
-  } catch {
-    return false
-  }
+  if (typeof constructor !== 'function' || isProxy(constructor)) return false
+  return Object.getOwnPropertyDescriptor(constructor, 'name')?.value === name
+    && Object.getOwnPropertyDescriptor(constructor, 'prototype')?.value === prototype
+    && reflectApply(intrinsicFunctionToString, constructor, []) === `function ${name}() { [native code] }`
 }
 
 function isIntrinsicObjectPrototype(value) {
-  return Object.getPrototypeOf(value) === null && hasIntrinsicConstructor(value, 'Object')
+  return !isProxy(value) && Object.getPrototypeOf(value) === null && hasIntrinsicConstructor(value, 'Object')
 }
 
 function plainObjectPrototype(value) {
@@ -66,8 +67,53 @@ function hasPlainArrayPrototype(value) {
     && isIntrinsicObjectPrototype(objectPrototype)
 }
 
-function invalid(path, detail) {
-  throw new TypeError(`value at ${path} is not PTC Value V1: ${detail}`)
+function invalid(path, detail, kind = 'shape', legacyDetail = detail, legacyMessage = `value at ${path} is not PTC Value V1: ${legacyDetail}`) {
+  const error = new TypeError(`value at ${path} is not PTC Value V1: ${detail}`)
+  weakMapSet(encodingFailures, error, { kind, path, detail, legacyMessage })
+  throw error
+}
+
+/** Brand checks do not read constructor, toStringTag, getters, or Proxy traps. */
+function unsupportedObject(value) {
+  if (isProxy(value)) return 'Proxy'
+  if (isDate(value)) return 'Date'
+  if (isMap(value)) return 'Map'
+  if (isSet(value)) return 'Set'
+  if (isRegExp(value)) return 'RegExp'
+  if (isAnyArrayBuffer(value)) return 'ArrayBuffer/SharedArrayBuffer'
+  if (isTypedArray(value)) return 'TypedArray/Buffer'
+  if (isDataView(value)) return 'DataView'
+  if (isNativeError(value)) return 'Error'
+  if (isPromise(value)) return 'Promise'
+  if (isWeakMap(value)) return 'WeakMap'
+  if (isWeakSet(value)) return 'WeakSet'
+  return 'unknown prototype'
+}
+
+export function valueEncodingFailure(error) {
+  return weakMapGet(encodingFailures, error)
+}
+
+export function valueEncodingHelp(failure) {
+  return failure?.kind === 'budget'
+    ? 'reduce the transferred graph to fit the reported value budget'
+    : 'select needed data explicitly as supported primitives, plain objects or arrays; keep unsupported live values in bindings (Date: explicit ISO text or timestamp; Map/Set: explicit entries or values); do not JSON.stringify a graph containing BigInt'
+}
+
+/** Only codec-owned failures acquire boundary facts; owner exceptions remain untouched. */
+export function encodeValueAtBoundary(value, options, boundary) {
+  try {
+    return encodeValue(value, options)
+  } catch (error) {
+    const failure = valueEncodingFailure(error)
+    if (failure === undefined) throw error
+    const fact = boundary === 'parameter'
+      ? 'program binding parameter was not dispatched'
+      : 'program binding call completed, but its result could not be transferred; external effects may already have occurred; do not repeat the operation solely to obtain its result'
+    const wrapped = new TypeError(`${fact}: ${error.message}; ${valueEncodingHelp(failure)}`)
+    weakMapSet(encodingFailures, wrapped, failure)
+    throw wrapped
+  }
 }
 
 function stringBytes(value) {
@@ -86,7 +132,7 @@ export function encodeValue(value, options = {}) {
 
   const accountText = (text, path) => {
     textBytes += stringBytes(text)
-    if (textBytes > limits.maxStringBytes) invalid(path, `string budget exceeds ${limits.maxStringBytes} bytes`)
+    if (textBytes > limits.maxStringBytes) invalid(path, `string budget exceeds ${limits.maxStringBytes} bytes`, 'budget')
   }
 
   const atom = (current, path) => {
@@ -106,14 +152,14 @@ export function encodeValue(value, options = {}) {
     if (typeof current === 'bigint') {
       const text = toString(current)
       const digits = text[0] === '-' ? text.length - 1 : text.length
-      if (digits > limits.maxBigIntDigits) invalid(path, `BigInt exceeds ${limits.maxBigIntDigits} digits`)
+      if (digits > limits.maxBigIntDigits) invalid(path, `BigInt exceeds ${limits.maxBigIntDigits} digits`, 'budget')
       accountText(text, path)
       return { tag: 'bigint', value: text }
     }
-    if (typeof current !== 'object') invalid(path, typeof current)
+    if (typeof current !== 'object') invalid(path, typeof current, 'unsupported')
     const prior = weakMapGet(seen, current)
     if (prior !== undefined) return { tag: 'reference', index: prior }
-    if (nodes.length >= limits.maxNodes) invalid(path, `node budget exceeds ${limits.maxNodes}`)
+    if (nodes.length >= limits.maxNodes) invalid(path, `node budget exceeds ${limits.maxNodes}`, 'budget')
     const index = nodes.length
     weakMapSet(seen, current, index)
     appendArray(nodes, undefined)
@@ -127,10 +173,10 @@ export function encodeValue(value, options = {}) {
     const current = item.value
     if (isArray(current)) {
       if (!hasPlainArrayPrototype(current)) invalid(item.path, 'non-plain array')
-      if (current.length > limits.maxArrayLength) invalid(item.path, `array length exceeds ${limits.maxArrayLength}`)
+      if (current.length > limits.maxArrayLength) invalid(item.path, `array length exceeds ${limits.maxArrayLength}`, 'budget')
       arraySlotCount += current.length
       if (arraySlotCount > limits.maxArrayLength) {
-        invalid(item.path, `array slot budget exceeds ${limits.maxArrayLength}`)
+        invalid(item.path, `array slot budget exceeds ${limits.maxArrayLength}`, 'budget')
       }
       const entries = []
       const keys = Reflect.ownKeys(current)
@@ -147,7 +193,7 @@ export function encodeValue(value, options = {}) {
           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}`)
+        if (edgeCount > limits.maxEdges) invalid(item.path, `edge budget exceeds ${limits.maxEdges}`, 'budget')
         appendArray(entries, [index, atom(descriptor.value, `${item.path}[${key}]`)])
       }
       nodes[item.index] = { type: 'array', length: current.length, entries }
@@ -155,7 +201,7 @@ export function encodeValue(value, options = {}) {
     }
 
     const prototype = plainObjectPrototype(current)
-    if (prototype === undefined) invalid(item.path, 'non-plain object')
+    if (prototype === undefined) invalid(item.path, `non-plain object (${unsupportedObject(current)})`, 'unsupported', 'non-plain object')
     const entries = []
     const keys = Reflect.ownKeys(current)
     for (let keyIndex = 0; keyIndex < keys.length; keyIndex += 1) {
@@ -167,7 +213,7 @@ export function encodeValue(value, options = {}) {
       }
       accountText(key, `${item.path}.${key}`)
       edgeCount += 1
-      if (edgeCount > limits.maxEdges) invalid(item.path, `edge budget exceeds ${limits.maxEdges}`)
+      if (edgeCount > limits.maxEdges) invalid(item.path, `edge budget exceeds ${limits.maxEdges}`, 'budget')
       appendArray(entries, [key, atom(descriptor.value, `${item.path}.${key}`)])
     }
     nodes[item.index] = { type: 'object', prototype, entries }
@@ -442,7 +488,8 @@ function renderCanonicalValue(normalized, limits) {
   let bytes = 0
   const append = (text) => {
     bytes += stringBytes(text)
-    if (bytes > limits.maxStringBytes) throw new TypeError(`rendered PTC value exceeds ${limits.maxStringBytes} bytes`)
+    if (bytes > limits.maxStringBytes) invalid('$', `rendered PTC value exceeds ${limits.maxStringBytes} bytes`, 'budget', undefined,
+      `rendered PTC value exceeds ${limits.maxStringBytes} bytes`)
     appendArray(chunks, text)
   }
   const emitted = new Set()