dsh-ptc-plus 0.3.2 → 0.4.1

package/internal/dynamic-native-runtime.js

@@ -0,0 +1,248 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { createContext, runInContext } from 'node:vm'
+import { recordExceptionOrigin } from './failure-reporting.js'
+import { createCallableSourceRegistry } from './callable-source-catalog.js'
+import { captureCompilerIntrinsics, moduleRuntimeIntrinsics as internal } from './compiler-intrinsics.js'
+
+const realmStates = new internal.WeakMap()
+const exposedIntrinsics = new internal.WeakMap()
+// Source facts describe canonical values and emitted source, independent of
+// which owned realm's toString observes a callable crossing a module boundary.
+const sources = createCallableSourceRegistry()
+const callableSources = new internal.WeakMap()
+const callableSourceTargets = new internal.WeakMap()
+const sourceTarget = origin => typeof origin === 'string' ? origin : origin?.target
+const copyArguments = (source, start = 0, result = []) => internal.copyArray(source, start, source.length, result)
+const invocationScopes = new AsyncLocalStorage()
+const getScope = AsyncLocalStorage.prototype.getStore
+const enterScope = AsyncLocalStorage.prototype.enterWith
+const currentScope = () => internal.Reflect.apply(getScope, invocationScopes, [])
+const selectScope = value => internal.Reflect.apply(enterScope, invocationScopes, [value])
+// Node 22 installs promise hooks lazily through a host array iterator. Complete
+// that platform initialization before source can mutate the module realm.
+selectScope(undefined)
+// Native eval has no callable activation in the source caller chain. Its
+// private realm gives each invocation a native try/finally lifetime without
+// moving source parameters or declarations, or changing source realm globals.
+let pendingInvocation
+const invocationRealm = createContext({
+  take() {
+    const invocation = pendingInvocation
+    pendingInvocation = undefined
+    return invocation
+  },
+  enter(invocation) {
+    const previous = currentScope()
+    selectScope({ invoke: invocation.invoke, origin: invocation.origin,
+      interface: invocation.interface, parent: previous })
+    return previous
+  },
+  failed(invocation, error) { recordExceptionOrigin(error, sourceTarget(invocation.origin)) },
+  leave(previous) { selectScope(previous) },
+})
+// A distinct source identity keeps V8 eval-origin notes out of user frames.
+const nativeContinuation = runInContext(`eval.bind(undefined, ${JSON.stringify(`
+  const invocation = take();
+  const previous = enter(invocation);
+  try {
+    while (invocation.advance(invocation)) invocation.args = invocation.collect(invocation.arrayLike);
+    invocation.complete(invocation, invocation.dispatch())
+  }
+  catch (error) { failed(invocation, error); throw error }
+  finally { leave(previous) }
+  //# sourceURL=ptc-plus:native-invocation
+`)})`, invocationRealm)
+
+/** Native callable identities are classified once for their owning realm. */
+export function createNativeCallAdapter({ realmFunction, intrinsicEval, reflect, errors, evaluate, rootEnvironment, interfaceOwner }) {
+  reflect = { apply: reflect.apply, construct: reflect.construct }
+  const { getPrototypeOf, setPrototypeOf } = captureCompilerIntrinsics(realmFunction).Object
+  let state = internal.weakMapGet(realmStates, realmFunction)
+  if (state === undefined) {
+    const intrinsics = realmFunction('return {constructors:[Function,(async function(){}).constructor,(function*(){}).constructor,(async function*(){}).constructor],call:Function.prototype.call,apply:Function.prototype.apply,bind:Function.prototype.bind,toString:Function.prototype.toString,reflectApply:Reflect.apply,reflectConstruct:Reflect.construct}')()
+    const constructors = new internal.Set()
+    for (let index = 0; index < intrinsics.constructors.length; index++) internal.setAdd(constructors, intrinsics.constructors[index])
+    state = { ...intrinsics, realmFunction, intrinsicEval, constructors,
+      bound: new internal.WeakMap(), prepared: new internal.WeakMap(), sources, callableSources, callableSourceTargets,
+      exposed: new internal.Map(), interfaces: new internal.WeakMap(),
+      nativeApply: reflect.apply(intrinsics.bind, intrinsics.reflectApply, [undefined]),
+      nativeConstruct: reflect.apply(intrinsics.bind, intrinsics.reflectConstruct, [undefined]),
+      templateArguments: realmFunction('return Array.of')() }
+    internal.weakMapSet(realmStates, realmFunction, state)
+  }
+  let selected = interfaceOwner === undefined ? state : internal.weakMapGet(state.interfaces, interfaceOwner)
+  if (selected === undefined) {
+    selected = { exposed: new internal.Map() }
+    internal.weakMapSet(state.interfaces, interfaceOwner, selected)
+  }
+  // Realm owners share intrinsic classification and source facts. An explicit
+  // generation owner retains its own root through opaque and asynchronous calls.
+  const install = () => {
+    if (selected.installed) return
+    selected.installed = true
+    const expose = (target, constructable = false) => {
+      const dispatch = (receiver, args, newTarget) => {
+        const active = currentScope()
+        const owner = active?.interface === selected ? active : undefined
+        return (owner?.invoke ?? invoke)(target, receiver, args, owner?.origin, newTarget)
+      }
+      const wrapper = new internal.Proxy(target, {
+        apply: (_, receiver, args) => dispatch(receiver, args),
+        ...(constructable ? { construct: (_, args, newTarget) => dispatch(undefined, args, newTarget) } : {}),
+      })
+      internal.mapSet(selected.exposed, target, wrapper)
+      if (interfaceOwner === undefined) internal.weakMapSet(exposedIntrinsics, target, wrapper)
+      internal.weakMapSet(state.callableSources, wrapper, reflect.apply(state.toString, target, []))
+      return wrapper
+    }
+    // Source reads select interfaces without replacing native global or
+    // prototype properties, including in escaped asynchronous continuations.
+    expose(state.intrinsicEval)
+    expose(state.toString)
+    internal.setForEach(state.constructors, constructor => expose(constructor, true))
+    const exposedFunction = internal.mapGet(selected.exposed, state.realmFunction)
+    internal.weakMapSet(realmStates, exposedFunction, state)
+  }
+  const isNativeConstructor = target => {
+    while (internal.weakMapHas(state.bound, target)) target = internal.weakMapGet(state.bound, target).callee
+    return internal.setHas(state.constructors, target)
+  }
+  const adaptConstructed = (native, origin) => {
+    const source = reflect.apply(state.toString, native, [])
+    const compiled = evaluate(state.intrinsicEval, undefined, [`(${source})`], rootEnvironment(sourceTarget(origin)), { functionConstructor: true })
+    setPrototypeOf(compiled, getPrototypeOf(native))
+    internal.weakMapSet(state.callableSources, compiled, source)
+    return compiled
+  }
+  const exposedValue = value => internal.mapGet(selected.exposed, value) ?? internal.weakMapGet(exposedIntrinsics, value) ?? value
+  const propagate = (error, origin) => {
+    recordExceptionOrigin(error, sourceTarget(origin), { reset: true })
+    for (let scope = currentScope(); scope !== undefined; scope = scope.parent) {
+      recordExceptionOrigin(error, sourceTarget(scope.origin))
+    }
+    return error
+  }
+  const invoke = (callee, receiver, args, origin, newTarget) => {
+    // Exposed intrinsic proxies already selected their owning interface.
+    const plan = invocation(callee, receiver, origin, false, newTarget !== undefined, false)
+    plan.newTarget = newTarget
+    return beginInvocation(plan, args)()
+  }
+  const prepareCall = (callee, receiver, origin, optional = false) => {
+    const plan = invocation(callee, receiver, origin, optional)
+    return plan === undefined ? undefined : prepareTagInvocation(plan)
+  }
+  const invocation = (callee, receiver, origin, optional = false, construct = false, selectInterface = true) => {
+    if (optional && callee == null) return undefined
+    const reference = internal.weakMapGet(state.prepared, callee)
+    if (reference !== undefined && !construct) ({ callee, receiver } = reference)
+    return { callee: selectInterface ? exposedValue(callee) : callee, receiver, origin, construct }
+  }
+  const validateInvocation = ({ callee, origin, construct }) => {
+    if (!construct && typeof callee !== 'function' && typeof origin?.callee === 'string') {
+      const error = new errors.TypeError(`${origin.callee} is not a function`)
+      recordExceptionOrigin(error, origin.target, { sourceFailure: true })
+      throw error
+    }
+  }
+  const collectArguments = reflect.apply(state.bind, state.reflectApply, [undefined, state.templateArguments, undefined])
+  const intrinsicTarget = callee => {
+    while (internal.weakMapHas(state.bound, callee)) callee = internal.weakMapGet(state.bound, callee).callee
+    return internal.setHas(state.constructors, callee) || callee === state.intrinsicEval || callee === state.toString
+  }
+  // Native array-like conversion runs in the continuation, after target
+  // validation and before dispatch. User getters therefore retain their source
+  // caller, and nested call/apply aliases consume each argument list once.
+  const advanceInvocation = plan => {
+    while (true) {
+      const { callee, receiver, args, construct } = plan
+      const bound = internal.weakMapGet(state.bound, callee)
+      if (bound !== undefined && intrinsicTarget(callee)) {
+        plan.callee = bound.callee
+        if (!construct) plan.receiver = bound.receiver
+        if (plan.newTarget === callee) plan.newTarget = bound.callee
+        plan.args = copyArguments(args, 0, copyArguments(bound.args))
+        continue
+      }
+      if (!construct && callee === state.call) {
+        plan.callee = receiver
+        plan.receiver = args[0]
+        plan.args = copyArguments(args, 1)
+        continue
+      }
+      if (!construct && (callee === state.apply && typeof receiver === 'function'
+        || callee === state.reflectApply && typeof args[0] === 'function')) {
+        plan.callee = callee === state.apply ? receiver : args[0]
+        plan.receiver = callee === state.apply ? args[0] : args[1]
+        plan.arrayLike = callee === state.apply ? args[1] : args[2]
+        if (callee === state.apply && plan.arrayLike == null) { plan.args = []; continue }
+        return true
+      }
+      plan.adaptConstructed = internal.setHas(state.constructors, callee)
+        || !construct && callee === state.reflectConstruct && isNativeConstructor(args[0])
+      plan.dispatch = !construct && callee === state.intrinsicEval
+        ? () => evaluate(callee, receiver, args, rootEnvironment(sourceTarget(plan.origin)))
+        : reflect.apply(state.bind, construct ? state.nativeConstruct : state.nativeApply,
+          construct ? [undefined, callee, args, plan.newTarget] : [undefined, callee, receiver, args])
+      return false
+    }
+  }
+  const completeInvocation = (plan, value) => {
+    if (plan.adaptConstructed) return adaptConstructed(value, plan.origin)
+    if (!plan.construct && plan.callee === state.bind) internal.weakMapSet(state.bound, value,
+      { callee: plan.receiver, receiver: plan.args[0], args: copyArguments(plan.args, 1) })
+    if (!plan.construct && plan.callee === state.toString) {
+      let receiver = plan.receiver
+      while (!internal.weakMapHas(state.callableSources, receiver) && internal.weakMapHas(state.callableSourceTargets, receiver)) {
+        receiver = internal.weakMapGet(state.callableSourceTargets, receiver)
+        value = reflect.apply(state.toString, receiver, [])
+      }
+      return internal.weakMapGet(state.callableSources, receiver) ?? state.sources.get(value) ?? value
+    }
+    return exposedValue(value)
+  }
+  const beginInvocation = (plan, args) => {
+    validateInvocation(plan)
+    pendingInvocation = {
+      ...plan, args, invoke, interface: selected, complete: completeInvocation,
+      newTarget: plan.construct && plan.newTarget === undefined ? plan.callee : plan.newTarget,
+      advance: advanceInvocation, collect: collectArguments,
+    }
+    return nativeContinuation
+  }
+  const prepareTagInvocation = plan => {
+    const result = (...args) => invoke(plan.callee, plan.receiver, args, plan.origin)
+    internal.weakMapSet(state.prepared, result, plan)
+    return result
+  }
+  return {
+    install,
+    exposedValue,
+    isEval: callee => callee === state.intrinsicEval || internal.mapHas(selected.exposed, state.intrinsicEval) && callee === internal.mapGet(selected.exposed, state.intrinsicEval),
+    evaluate(compiled, environment) {
+      // Bootstrap originals never leave this owner. Direct eval must use the
+      // actual intrinsic identity inside its private explicit lexical frame.
+      const run = state.realmFunction(compiled.environmentName, 'eval', 'source', 'return eval(source)')
+      return reflect.apply(run, undefined, [environment, state.intrinsicEval, compiled.code])
+    },
+    declareGlobals(names) { if (names.length > 0) reflect.apply(state.intrinsicEval, undefined, [`var ${internal.join(names, ',')};`]) },
+    propagate,
+    prepareCall,
+    prepareInvocation: invocation,
+    releaseMemberReceiver(receiver) { return receiver },
+    prepareMemberInvocation(receiver, callee, origin, optional) { return invocation(callee, receiver, origin, optional) },
+    beginInvocation,
+    prepareTagInvocation,
+    templateArguments: state.templateArguments,
+    referenceCall(callee, receiver) {
+      if (callee == null) return callee
+      callee = exposedValue(callee)
+      const result = (...args) => invoke(callee, receiver, args)
+      internal.weakMapSet(state.prepared, result, { callee, receiver })
+      return result
+    },
+    registerCallableSourceTarget(adapter, target) { internal.weakMapSet(state.callableSourceTargets, adapter, target); return adapter },
+    registerSources(sources) { state.sources.register(sources) },
+    originalSource(source) { return state.sources.get(source) },
+  }
+}

package/internal/dynamic-scope-analysis.js

@@ -0,0 +1,90 @@
+import { visitSource } from './compiler-source-regions.js'
+
+/** A switch creates its case environment after evaluating the discriminant.
+ * Babel parents nested discriminant scopes to the switch, so filter that
+ * synthetic edge using the reference's actual source ancestry. */
+export function* sourceScopePath(path, origin = path) {
+  const excluded = new Set()
+  for (let child = origin; child.parentPath; child = child.parentPath) {
+    if (child.key === 'discriminant' && child.parentPath.isSwitchStatement()) excluded.add(child.parentPath.scope)
+  }
+  for (let scope = path.scope; scope; scope = scope.parent) {
+    if (!excluded.has(scope)) yield scope
+  }
+}
+
+export function sourceBinding(path, name) {
+  for (const scope of sourceScopePath(path)) {
+    const binding = scope.getOwnBinding(name)
+    if (binding !== undefined && sourceBindingVisible(path, binding)) return binding
+  }
+  return undefined
+}
+
+/** Lookup and dynamic descriptor capture share the same visibility test. */
+export function sourceBindingVisible(path, binding) {
+  return !sourceInParameters(path, binding.scope) || binding.kind === 'param'
+    || binding.kind === 'local' && binding.path.node === binding.scope.block
+}
+
+/** A parameter expression (including a closure inside it) cannot see its
+ * function's body declarations. Source ancestry owns this visibility edge. */
+export function sourceInParameters(path, scope) {
+  for (let child = path; child.parentPath; child = child.parentPath) {
+    if (child.parentPath.node === scope.block) return child.listKey === 'params'
+  }
+  return false
+}
+
+/** Source environments that can introduce a binding between a reference and
+ * its static owner. Strict closures still inherit outer sloppy activations. */
+export function createDynamicScopeAnalysis(tree) {
+  const evalActivations = new WeakSet()
+  const parameterEvalActivations = new WeakSet()
+  const directEvalSubtrees = new WeakSet()
+  visitSource(tree, { CallExpression(path) {
+    if (path.node.callee.type !== 'Identifier' || path.node.callee.name !== 'eval') return
+    // Parameter plans need syntactic eval containment, including strict and
+    // nested callables; shadow introduction separately follows real owners.
+    for (let current = path; current && !directEvalSubtrees.has(current.node); current = current.parentPath) {
+      directEvalSubtrees.add(current.node)
+    }
+    if (path.isInStrictMode()) return
+    let child = path
+    for (let parent = path.parentPath; parent; child = parent, parent = parent.parentPath) {
+      if (parent.isFunction()) {
+        if (child.key === 'body') { evalActivations.add(parent.node); return }
+        if (child.listKey === 'params') { parameterEvalActivations.add(parent.node); return }
+      }
+      if (parent.isProgram()) evalActivations.add(parent.node)
+    }
+  } })
+  return {
+    containsDirectEval(node) { return directEvalSubtrees.has(node) },
+    mayEvalShadow(path, ownerNode, self = false) {
+      let child = path
+      for (let parent = path.parentPath; parent; child = parent, parent = parent.parentPath) {
+        if (parent.node === ownerNode && !self) return false
+        if (evalActivations.has(parent.node) && (parent.isProgram() || child.key === 'body')) return true
+        if (parameterEvalActivations.has(parent.node) && (child.key === 'body' || child.listKey === 'params')) return true
+        if (parent.node === ownerNode) return false
+      }
+      return false
+    },
+  }
+}
+
+/** Var storage belongs to its variable scope, while initialization can select
+ * a simple catch binding or an intervening with object. Ordinary block lexical
+ * declarations retain their independent stateful identity. */
+export function varInitializerTarget(path, ownerNode, name, sourceName = node => node.name) {
+  const withNodes = []
+  let child = path
+  for (let parent = path.parentPath; parent && parent.node !== ownerNode;
+    child = parent, parent = parent.parentPath) {
+    if (parent.isWithStatement() && child.key === 'body') withNodes.push(parent.node)
+    if (parent.isCatchClause() && child.key === 'body' && parent.node.param?.type === 'Identifier'
+      && sourceName(parent.node.param) === name) return { catchNode: parent.node, withNodes }
+  }
+  return { withNodes }
+}

package/internal/edit-transport-owner.js

@@ -20,6 +20,14 @@ import {
 import { editTargetForCall, projectSessionLog } from './session-log-view.js'
 import { RUN_CODE } from './runtime-bridge-owner.js'
 import { isRecord } from './record-utils.js'
+import {
+  userBindingDraftCapabilityFromMeta,
+  withUserBindingDraftCapability,
+} from './user-binding-draft-projection.js'
+import {
+  userBindingsSnapshotFromMeta,
+  withUserBindingsSnapshot,
+} from './user-bindings.js'
 import {
   validatedReplMemorySnapshot,
   withReplMemorySnapshot,
@@ -96,9 +104,19 @@ export function createEditTransportOwner(ctx, {
     if (derived.recoveryBoundaries !== undefined) {
       meta[RECOVERY_BOUNDARY_KEY] = normalizeRecoveryBoundaries(derived.recoveryBoundaries)
     }
-    return derived.replMemory === undefined
+    const withBindings = derived.userBindings === undefined
       ? meta
-      : withReplMemorySnapshot(meta, derived.replMemory, presentationGeneration)
+      : withUserBindingsSnapshot(meta, derived.userBindings)
+    const withDraft = derived.draftCapability === undefined
+      ? withBindings
+      : withUserBindingDraftCapability(
+          withBindings,
+          derived.draftCapability,
+          presentationGeneration,
+        )
+    return derived.replMemory === undefined
+      ? withDraft
+      : withReplMemorySnapshot(withDraft, derived.replMemory, presentationGeneration)
   }
   definition.output = {
     schema: {
@@ -186,6 +204,11 @@ export function createEditTransportOwner(ctx, {
         ? normalizeRecoveryBoundaries(inner.meta[RECOVERY_BOUNDARY_KEY])
         : undefined
       const replMemory = validatedReplMemorySnapshot(inner?.meta, presentationGeneration)
+      const userBindings = userBindingsSnapshotFromMeta(inner?.meta)
+      const draftCapability = userBindingDraftCapabilityFromMeta(
+        inner?.meta,
+        presentationGeneration,
+      )
       const value = derivedEditResult(inner)
       const derived = {
         targetCallSeq: target.callSeq,
@@ -193,6 +216,8 @@ export function createEditTransportOwner(ctx, {
         rewrites,
         recoveryBoundaries,
         replMemory,
+        userBindings,
+        draftCapability,
         code: edited.code,
         description: edited.description,
       }

package/internal/execution-seam-compat.js

@@ -0,0 +1,193 @@
+/**
+ * Own how PTC Plus attaches to the host's program-execution seam.
+ *
+ * DSH registers one execution seam per generation. The current release
+ * registers `ctx.ptcRuntime` (`@deepseek-ai/dsh-ptc-runtime`); the preceding one
+ * registered `ctx.codeRuntime` (`@deepseek-ai/dsh-code-runtime`). Both run one
+ * model-written program against host async bindings. They differ in the service
+ * name, in the call shape (`resolve(request)` then `run(spec)` against a single
+ * `run(request)`), and in the capability descriptors a provider publishes.
+ * Which seam is live is decided by the registered service, never by a version
+ * string, so a deployment on either generation obtains the same behavior.
+ *
+ * PTC Plus replaces the execution of session cells with its own persistent
+ * REPL. The object DSH describes to the model is therefore the plugin's
+ * execution, not the wrapped provider's, so `takeOver()` answers the
+ * descriptors the plugin can honor and withholds the ones it cannot. The REPL
+ * runs every cell in one long-lived worker rather than a fresh process per
+ * call, applies the session's configured budgets rather than a per-call host
+ * deadline, and performs no file confinement. DSH gates `timeoutMs` on
+ * `timeout` and resolves or escalates file policy on `sandboxMode`, so
+ * withholding those descriptors keeps DSH's authority decisions with DSH
+ * instead of having this plugin accept an input it would then ignore.
+ *
+ * A seam-neutral request carries exactly `program`, `bindings`, and `signal`:
+ * the fields PTC Plus consumes. A resolved spec's directory, deadline, and
+ * authority describe the provider whose execution was replaced, and are neither
+ * forwarded to the session kernel nor re-derived here.
+ */
+
+/** Cordis service name registered by the current DSH generation. */
+export const EXECUTION_SEAM_SERVICE = 'ptcRuntime'
+
+/** Cordis service name registered by the preceding DSH generation. */
+export const LEGACY_EXECUTION_SEAM_SERVICE = 'codeRuntime'
+
+const SEAM_SERVICES = Object.freeze([EXECUTION_SEAM_SERVICE, LEGACY_EXECUTION_SEAM_SERVICE])
+
+/**
+ * Descriptors the plugin replaces with the capabilities of its own execution.
+ * `executionInstructions` describes the wrapped provider's program model, which
+ * no longer applies; `timeout` and `sandboxMode` gate host inputs the plugin
+ * cannot honor. Withdrawal is unconditional because the rule is a property of
+ * the plugin's execution, not of a generation: the preceding generation's
+ * contract defines none of these members and nothing in its install closure
+ * reads them, so withdrawing there is inert, while a provider that published
+ * them stays unable to outlive the takeover.
+ */
+const WITHHELD_DESCRIPTORS = Object.freeze(['executionInstructions', 'sandboxMode', 'timeout'])
+
+/** Read a registered service without declaring an injection requirement. */
+function readService(ctx, name) {
+  if (typeof ctx?.get === 'function') return ctx.get(name)
+  return ctx?.[name]
+}
+
+function descriptorsMatch(left, right) {
+  if (left === undefined || right === undefined) return left === right
+  return left.value === right.value
+    && left.get === right.get
+    && left.set === right.set
+    && left.writable === right.writable
+    && left.enumerable === right.enumerable
+    && left.configurable === right.configurable
+}
+
+/**
+ * Build the seam handle for one live execution service.
+ * @param {object} service - the registered `ctx.ptcRuntime` or `ctx.codeRuntime`.
+ * @param {string} serviceName - the service name it was registered under.
+ */
+export function createExecutionSeam(service, serviceName) {
+  if (service === null || typeof service !== 'object') {
+    throw new TypeError(`ptc-plus: ${serviceName} must be an execution service object`)
+  }
+  const current = serviceName === EXECUTION_SEAM_SERVICE
+  const upstreamRun = service.run
+  if (typeof upstreamRun !== 'function') {
+    throw new TypeError(`ptc-plus: ${serviceName}.run must be a function`)
+  }
+  const upstreamResolve = service.resolve
+  if (current && typeof upstreamResolve !== 'function') {
+    throw new TypeError('ptc-plus: ptcRuntime.resolve must be a function')
+  }
+  let installed
+  return Object.freeze({
+    serviceName,
+    language: service.language,
+    /**
+     * Run one program through the provider this plugin wraps. The current
+     * generation resolves the request before running it, exactly as its own
+     * consumer does; the preceding generation accepts the request directly.
+     */
+    invokeUpstream(request) {
+      return current
+        ? upstreamRun.call(service, upstreamResolve.call(service, request))
+        : upstreamRun.call(service, request)
+    },
+    /**
+     * Install the plugin's execution entry, and its capability descriptors, on
+     * the live service. Only one takeover is live at a time.
+     * @param {(request: object) => Promise<object>} execute - the plugin's entry.
+     * @returns {() => void} restores every descriptor this call replaced.
+     */
+    takeOver(execute) {
+      if (installed !== undefined) throw new Error('ptc-plus: execution seam already taken over')
+      const saved = new Map()
+      const written = new Map()
+      const define = (name, descriptor) => {
+        const previous = Object.getOwnPropertyDescriptor(service, name)
+        if (!saved.has(name)) saved.set(name, previous)
+        // Preserve the shadowed property's visibility so a consumer that
+        // enumerates the provider sees the same member set.
+        Object.defineProperty(service, name, { enumerable: previous?.enumerable ?? false, ...descriptor })
+        written.set(name, Object.getOwnPropertyDescriptor(service, name))
+      }
+      define('run', {
+        configurable: true,
+        writable: true,
+        value: current
+          ? spec => execute({
+              program: spec.program,
+              bindings: spec.bindings,
+              signal: spec.signal,
+            })
+          : request => execute(request),
+      })
+      for (const name of WITHHELD_DESCRIPTORS) {
+        define(name, { configurable: true, value: name === 'executionInstructions' ? '' : undefined })
+      }
+      const restore = () => {
+        if (installed !== restore) return
+        installed = undefined
+        for (const [name, descriptor] of saved) {
+          if (!descriptorsMatch(Object.getOwnPropertyDescriptor(service, name), written.get(name))) continue
+          if (descriptor === undefined) delete service[name]
+          else Object.defineProperty(service, name, descriptor)
+        }
+      }
+      installed = restore
+      return restore
+    },
+  })
+}
+
+/**
+ * Wait for the host's execution seam and attach the plugin to the live one.
+ *
+ * A deployment registers one generation, so the current service is preferred
+ * whenever both are live; the preceding generation attaches only when the
+ * current one is absent. The injected scope requires the plugin's own core
+ * services as well, so the callback receives a context the plugin can work in,
+ * and everything the plugin registers there belongs to the seam the host
+ * registered: unloading that service unloads the plugin, and registering it
+ * again attaches once more, which is how a host that reloads its runtime
+ * provider reloads this dependent.
+ *
+ * @param {object} ctx - the plugin context.
+ * @param {object} options - `services` are the plugin's own required services,
+ *   and `attach` is invoked with the injected scope and the seam handle.
+ * @returns {Promise<unknown>} settles with the attach result.
+ */
+export function installExecutionSeam(ctx, { services = [], attach }) {
+  let live
+  const select = (name, scope) => {
+    if (live !== undefined) return live.attached
+    if (name === LEGACY_EXECUTION_SEAM_SERVICE && readService(ctx, EXECUTION_SEAM_SERVICE) !== undefined) {
+      return undefined
+    }
+    const entry = { name }
+    live = entry
+    try {
+      entry.attached = attach(scope, createExecutionSeam(scope?.[name] ?? readService(ctx, name), name))
+    } catch (error) {
+      live = undefined
+      throw error
+    }
+    scope.effect?.(() => () => {
+      if (live === entry) live = undefined
+    }, 'ptc-plus execution seam lifecycle')
+    return entry.attached
+  }
+  const pending = SEAM_SERVICES.map(name => new Promise((resolve, reject) => {
+    ctx.inject([...services, name], scope => {
+      try {
+        resolve(select(name, scope))
+      } catch (error) {
+        reject(error)
+        throw error
+      }
+    })
+  }))
+  return Promise.race(pending)
+}