dsh-ptc-plus 0.5.2 → 0.5.4

package/index.js

@@ -13,8 +13,9 @@ import { CapabilityStatisticsStore } from './internal/capability-statistics-stor
 import { createCapabilityEnvironment } from './internal/capability-environment.js'
 import { capabilityCommandReceipt } from './internal/capability-command-receipt.js'
 import { toolSdkSchemas } from './internal/program-bindings.js'
+import { hostTransportDefinition, hostTransportUnreadable } from './internal/host-tool-sdk.js'
 import { createRuntimeMessageOwner, handBackRuntimeSessions } from './internal/runtime-contexts.js'
-import { createSessionLogOwner } from './internal/session-log-view.js'
+import { createSessionLogOwner, projectionRegistrationDisposer } from './internal/session-log-view.js'
 import { PTC_DELIVERY_CONTEXT } from './internal/runtime-messages.js'
 import { createCordisToolsOwner } from './internal/cordis-tools-owner.js'
 import { createEditTransportOwner, EDIT_RUN_CODE } from './internal/edit-transport-owner.js'
@@ -32,6 +33,7 @@ import { valueLimitsFromConfig } from './internal/value-wire-schema.js'
 import { createReplMemoryProjection } from './internal/repl-memory-projection.js'
 import { createUserBindingDraftProjection } from './internal/user-binding-draft-projection.js'
 import { createUserBindingsOwner } from './internal/user-bindings-owner.js'
+import { latestBindingAdoption } from './internal/binding-adoption.js'
 import { createHostRpc } from './internal/host-rpc.js'
 import { RPC_CONTRACTS } from './internal/rpc-contract.js'
 import { createReplObservationInterest } from './internal/repl-observation-interest.js'
@@ -112,8 +114,58 @@ function replGuidance({ bindingPolicy, rewritesEnabled, languageSemantics, durab
   return paragraphs.filter(paragraph => paragraph.trim().length > 0).join('\n\n')
 }
 
+/**
+ * The reserved `run_code` transport definition, from whichever surface this
+ * host publishes it on. Session execution is available exactly when one of
+ * those surfaces answers.
+ */
+function runCodeDefinitionFor(tools, scope) {
+  return hostTransportDefinition(tools, scope, RUN_CODE)
+}
+
+/**
+ * One catalogue row in the shape `/capabilities list` publishes.
+ *
+ * The command states the panel's two columns, so an entry carries the same
+ * statement the panel's column carries: exactly the dimensions that row decides,
+ * each naming the answer its own source gave. A dimension this session recorded
+ * no choice for stays stated as `inherit`. The saved column states the words the
+ * configuration wrote for that object: its own entry, or `automatic` when it wrote
+ * none — a category, server or bottom layer that would answer at runtime is
+ * behaviour, so it reaches no cell (capability-surface §8.1c). A server row states
+ * `automatic` unless its own `mcpServers.<server>` rule writes availability. Compressing a
+ * row into one word would
+ * answer for the dimension it dropped — a record that decided disclosure but not
+ * availability would read as if the session had decided nothing. No column
+ * reports the composition: the panel states supply, record and the receipt, and
+ * this listing is the same read rather than a second one that could answer for
+ * what a runtime built.
+ */
+function capabilityListingEntry(row) {
+  // A server decides availability only: its members carry disclosure, so the panel
+  // states one value for such a row and this listing states the same one.
+  const statement = column => row.kind === 'server' ? { availability: column.availability }
+    : { availability: column.availability, disclosure: column.disclosure }
+  return { id: row.id, name: row.name, category: row.category, source: row.source,
+    ...(typeof row.description === 'string' ? { description: row.description } : {}),
+    saved: statement(row.saved), temporary: statement(row.session) }
+}
+
+/**
+ * The composition a pending capability command made, in the shape a receipt carries.
+ *
+ * A command that composed a plan before the Host accepted a step has to carry it in its
+ * receipt: the plan is not in the log yet, so a restart would otherwise have no way to know
+ * which composition the command made. `recordedPlan` reads it back by matching the command's
+ * own id and raw input, which is why the proposal states both.
+ */
+function pendingProposal(capabilityEnvironment, commandId, rawInput, agent) {
+  const message = capabilityEnvironment.pendingChoiceMessage(agent)
+  return message === undefined ? undefined : { commandId, rawInput, message }
+}
+
 /** Register the session-bound REPL runtime. */
-function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolSdkSchemasForAgent, sessionId, sessionLog, settingsForCommand) {
+function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolSdkSchemasForAgent, sessionId, sessionLog, settingsForCommand, readPromptText) {
   const presentationGeneration = randomUUID()
   const replMemoryProjection = createReplMemoryProjection(presentationGeneration)
   const userBindingDraftProjection = createUserBindingDraftProjection(presentationGeneration)
@@ -247,11 +299,17 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolS
   const cancelCordisActivation = () => pendingCordisActivation?.cancel()
   const registerProjection = (projection, label) => {
     try {
-      const unregister = projectionService?.register?.(projection)
-      if (typeof unregister !== 'function') {
-        throw new Error('ptc-plus: sessionProjections.register did not return a disposer')
+      // A newer host returns a ProjectionHandle (`stateOf`/`readerFor`/`dispose`,
+      // possibly async); earlier hosts returned a disposer. Accept either shape so
+      // the projection is not silently dropped on the newer contract.
+      const dispose = projectionRegistrationDisposer(projectionService?.register?.(projection))
+      if (dispose === undefined) {
+        throw new Error('ptc-plus: sessionProjections.register returned neither a disposer nor a handle')
       }
-      return unregister
+      // Unregistration failures belong to the caller that is suspending or
+      // reloading the projection: it retries and reports them. Swallowing one
+      // here would turn a failed disposal into a silent duplicate projection.
+      return () => dispose()
     } catch (error) {
       ctx.logger?.warn?.(`ptc-plus: ${label} projection unavailable`, error)
       return undefined
@@ -348,6 +406,9 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolS
       readSessionLog: sessionLog.read,
       enabled: activeConfig.userBindingsEnabled,
       draftProjectionAvailable,
+      // A session's adoption is its own recorded decision, so it is read from
+      // that session's log instead of a process-local map.
+      bindingAdoptionForAgent: agent => latestBindingAdoption(sessionLog.project(agent)?.ptcMessages ?? []),
       maxWallMs: activeConfig.maxWallMs,
       maxOutputBytes: activeConfig.maxOutputBytes,
       maxOldGenerationSizeMb: activeConfig.maxOldGenerationSizeMb,
@@ -355,11 +416,15 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolS
       valueLimits: valueLimitsFromConfig(activeConfig),
     })
     capabilityEnvironment = createCapabilityEnvironment({ ctx, config: activeConfig,
-      toolSchemasForAgent: toolSdkSchemasForAgent, modelSchemasForAgent: toolSchemasForAgent,
+      toolSchemasForAgent: toolSdkSchemasForAgent,
+      // The panel's binding rows report the same catalog `/binding` acts on, so the
+      // read borrows the bindings owner's `list()` instead of opening a second store.
+      readUserBindings: () => userBindings.list(),
       store: new CapabilityStatisticsStore({ ctx }) })
     runtimeBridge = createRuntimeBridgeOwner({
       ctx,
       seam,
+      readPromptText,
       observeSession: id => observationInterest.has(id),
       readSessionLog: sessionLog.read,
       sessionConfig: activeConfig,
@@ -392,7 +457,8 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolS
       sessionId,
       toolSchemasForAgent,
       capabilityEnvironment,
-      userBindingsForAgent: () => userBindings.snapshot(),
+      declaresRunCode: agent => runCodeDefinitionFor(ctx.tools, agent) !== undefined,
+      userBindingsForAgent: agent => userBindings.snapshotForAgent(agent),
       setAgentPresentation: (agent, presentation) => (
         userBindings.setAgentPresentation(agent, presentation)
       ),
@@ -401,25 +467,37 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolS
       name: 'tools:ptc-plus-repl',
       order: 98,
       text: context => {
-        if (ctx.tools.get(RUN_CODE, context?.scope) === undefined) return ''
+        if (runCodeDefinitionFor(ctx.tools, context?.scope) === undefined) return ''
         return replGuidance(guidancePolicies(activeConfig), resolvePromptTextConfig(activeConfig))
       },
     }))
+    let unreadableTransportReported = false
     disposers.push(ctx.on('system-prompt/assemble', async (assembly, context, next) => {
       const projected = await directSurface.assemble(assembly, context, next)
-      if (ctx.tools.get(RUN_CODE, context?.agent) !== undefined) runtimeBridge.prepareAgent(context?.agent)
+      // A capability observation states what the Host declares. It prepares no session,
+      // so it neither re-applies the model-facing slots nor reports a transport the
+      // operator can do nothing about from a read.
+      if (context?.ptcPlusCapabilityObservation === true) return projected
+      if (runCodeDefinitionFor(ctx.tools, context?.agent) !== undefined) runtimeBridge.prepareAgent(context?.agent)
+      else if (!unreadableTransportReported && hostTransportUnreadable(ctx.tools, context?.agent)) {
+        // The host declares the reserved transport and this plugin cannot read it.
+        // Every gate that needs execution answers "unavailable", so the operator is
+        // told which of the two facts holds instead of finding the features gone.
+        unreadableTransportReported = true
+        ctx.logger?.warn?.('ptc-plus: the host tool executor declares run_code but publishes no transport definition this plugin can read; session execution stays unavailable')
+      }
       return projected
     }))
     disposers.push(() => capabilityEnvironment.dispose())
     disposers.push(ctx.on('agent/pre-step', (payload, next) => capabilityEnvironment.preStep(payload, next), { prepend: true }))
     disposers.push(ctx.on('agent/created', ({ agent }) => {
-      if (ctx.tools.get(RUN_CODE, agent) !== undefined) {
+      if (runCodeDefinitionFor(ctx.tools, agent) !== undefined) {
         runtimeBridge.prepareAgent(agent)
         editTransport.ensureInstalled(agent)
       }
     }))
     for (const agent of ctx.agents?.list?.() ?? []) {
-      if (ctx.tools.get(RUN_CODE, agent) !== undefined) {
+      if (runCodeDefinitionFor(ctx.tools, agent) !== undefined) {
         runtimeBridge.prepareAgent(agent)
         editTransport.ensureInstalled(agent)
       }
@@ -432,7 +510,7 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolS
       const capabilitiesRpc = ctx.inject(['ptcPlusRpc'], scope => {
         scope.effect(() => scope.ptcPlusRpc.register(RPC_CONTRACTS.capabilities, async (operation, payload, signal) => {
           signal.throwIfAborted()
-          if (operation === 'catalog') return { ok: true, value: await capabilityEnvironment.describeCatalog(signal) }
+          if (operation === 'catalog') return { ok: true, value: await capabilityEnvironment.describeCatalog(payload, signal) }
           if (operation === 'targets') return { ok: true, value: capabilityEnvironment.describeTargets() }
           if (operation === 'session-catalog') return { ok: true, value: await capabilityEnvironment.describeSessionCatalog(payload, signal) }
           if (operation === 'allocation') return { ok: true, value: await capabilityEnvironment.observeAllocation(payload, signal) }
@@ -448,36 +526,58 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolS
           input: { hint: 'refresh | list [all|skills|tools|mcp|mcp_tools] [query] | set session|global <id> [availability|disclosure] <choice>' },
           handler: async ({ commandId, agent, rawInput, signal }) => {
             const input = rawInput.trim()
-            const receipt = (state, error) => capabilityCommandReceipt(state, String(agent.session.id), error,
-              state === 'pending' && capabilityEnvironment.pendingChoiceMessage(agent)
-                ? { commandId, rawInput, message: capabilityEnvironment.pendingChoiceMessage(agent) } : undefined)
+            // A composition the Host has not committed yet is not in the log, so a pending
+            // receipt carries it as the proposal it is: a restart reads that proposal back as
+            // the plan the command made. A record needs no proposal — it is in the log already.
+            const receipt = (state, error, record) => capabilityCommandReceipt(state, String(agent.session.id), error,
+              state === 'pending' ? pendingProposal(capabilityEnvironment, commandId, rawInput, agent) : undefined, record)
             const selection = /^set (session|global) (\S+) (?:(availability|disclosure) )?(full|on-demand|closed|automatic|inherit|enabled|host|adaptive)$/.exec(input)
             if (selection) {
-              if (!capabilityEnvironment.canRefresh(agent)) return { kind: 'error', text: receipt('unavailable') }
+              // The write is stated before it happens: the receipt names the record
+              // this command asked for, and whether that record exists is the answer
+              // the command itself returns.
+              const record = { scope: selection[1], id: decodeURIComponent(selection[2]),
+                ...(selection[3] === undefined ? {} : { dimension: selection[3] }), selection: selection[4] }
               const changed = await capabilityEnvironment.change(agent, {
-                scope: selection[1], id: decodeURIComponent(selection[2]), dimension: selection[3], selection: selection[4], commandId,
+                scope: record.scope, id: record.id, dimension: selection[3], selection: record.selection,
               }, signal, settingsForCommand?.())
+              // A receipt states what this command wrote — which entry, which choice
+              // and which session or global configuration now records it. What a cell
+              // later obtained is that row's own `evidence` field, not a sentence here.
+              // A session choice is a record of this session's log, so it is durable the
+              // moment the command returns and needs no waiting state.
+              const state = changed.sessionApplied ? 'recorded' : 'saved-only'
               return { kind: changed.sessionApplied ? 'success' : 'error',
-                text: receipt(changed.sessionApplied ? changed.publication === 'pending' ? 'pending' : 'recorded' : 'saved-only', changed.error) }
+                text: receipt(state, changed.error, state === 'recorded' ? record : undefined) }
             }
             const listing = /^list(?: (all|skills|tools|mcp|mcp_tools))?(?: (.*))?$/.exec(input)
             if (listing) {
-              const entries = await capabilityEnvironment.catalogFor(agent, signal)
+              // The listing is the panel's own read: one session catalogue, projected
+              // into the columns this command states. The session's scope supplies the
+              // declared face while the Host holds its agent, and the plan its log froze
+              // supplies it afterwards; the saved configuration states the saved column.
+              // Nothing about the PTC runtime enters it, so the two surfaces cannot
+              // disagree about which ids exist.
+              const catalog = await capabilityEnvironment.describeSessionCatalog({
+                sessionId: String(agent.session.id ?? agent.id),
+              }, signal)
               const query = (listing[2] ?? '').toLocaleLowerCase()
               const kind = listing[1] ?? 'all'
-              return { kind: 'success', text: JSON.stringify({ schema: 'ptc-capability-catalog/v1', entries: entries.filter(entry => (
-                kind === 'all' || kind === 'skills' && entry.category === 'skill'
-                || kind === 'tools' && entry.category === 'tool' && entry.source?.kind !== 'mcp'
-                || kind === 'mcp' && ['server', 'resource'].includes(entry.category)
-                || kind === 'mcp_tools' && entry.category === 'tool' && entry.source?.kind === 'mcp'
-              ) && (!query || `${entry.id} ${entry.description}`.toLocaleLowerCase().includes(query))) }) }
+              const entries = catalog.rows
+                .filter(row => row.kind !== 'binding')
+                .filter(row => kind === 'all' || kind === 'skills' && row.category === 'skill'
+                  || kind === 'tools' && row.category === 'tool' && row.source?.kind !== 'mcp'
+                  || kind === 'mcp' && ['server', 'resource'].includes(row.category)
+                  || kind === 'mcp_tools' && row.category === 'tool' && row.source?.kind === 'mcp')
+                .filter(row => !query || `${row.id} ${row.name ?? ''} ${row.description ?? ''}`.toLocaleLowerCase().includes(query))
+                .map(capabilityListingEntry)
+              return { kind: 'success', text: JSON.stringify({ schema: 'ptc-capability-catalog/v1', entries }) }
             }
             if (input !== '' && input !== 'refresh') return { kind: 'error', text: receipt('usage') }
             if (input === 'refresh') {
-              if (!capabilityEnvironment.canRefresh(agent)) {
-                return { kind: 'error', text: receipt('unavailable') }
-              }
-              await capabilityEnvironment.refresh(agent, undefined, signal, commandId)
+              // The command acts on the session it was invoked in; the agent is the
+              // argument that states which composition to replace.
+              await capabilityEnvironment.refresh(agent, undefined, signal)
               // A refresh always republishes the saved configuration; when that
               // configuration has capability management or context off, report
               // the off state instead of claiming an updated environment.
@@ -649,11 +749,16 @@ export const apply = (ctx, config = {}) => {
 function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatileConfig) {
   let settingsWriter
   const sessionLog = createSessionLogOwner(ctx)
-  const toolSchemasForAgent = agent => typeof ctx.tools.schemas === 'function'
-    ? ctx.tools.schemas(agent)
+  // The second argument is the step's admission. Naming it is how a caller states the set
+  // the Host actually delivers for that step; omitting it reads every definition
+  // registered at this scope, which is the only view a call outside a model step has.
+  const toolSchemasForAgent = (agent, toolSet = undefined) => typeof ctx.tools.schemas === 'function'
+    ? ctx.tools.schemas(agent, toolSet)
     : []
-  // SDK contracts include output schemas; model-facing schemas remain unchanged.
-  const toolSdkSchemasForAgent = agent => toolSdkSchemas(ctx.tools, agent)
+  // SDK contracts include output schemas; model-facing schemas remain unchanged. The
+  // admission is read through the same registry, so a contract describes the definition
+  // this step delivers rather than one the registry would resolve.
+  const toolSdkSchemasForAgent = (agent, toolSet = undefined) => toolSdkSchemas(ctx.tools, agent, toolSet)
   const sessionId = agent => {
     const id = agent?.session?.id ?? agent?.id
     return id === undefined ? undefined : String(id)
@@ -730,7 +835,9 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
   // Execution ownership is a per-attachment property: `owned` installs the
   // session runtime, `deferred` leaves run_code to the official provider.
   const executionShape = nextConfig => (
-    defersToOfficialRepl(nextConfig, seam.provider) ? 'deferred' : 'owned'
+    defersToOfficialRepl(nextConfig, {
+      get retainsState() { return seam.originalRetainsState },
+    }) ? 'deferred' : 'owned'
   )
   const startActivation = record => {
     if (record.cancelled || disposed || activating !== record) {
@@ -744,7 +851,7 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
     try {
       candidate = record.shape === 'deferred'
         ? createDeferredRuntime()
-        : installPtCRuntime(ctx, record.config, seam, toolSchemasForAgent, toolSdkSchemasForAgent, sessionId, sessionLog, () => settingsWriter)
+        : installPtCRuntime(ctx, record.config, seam, toolSchemasForAgent, toolSdkSchemasForAgent, sessionId, sessionLog, () => settingsWriter, currentPromptText)
       record.runtime = candidate
     } catch (error) {
       const failedRuntime = error?.[INSTALL_CLEANUP]
@@ -899,8 +1006,10 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
   const handbackOwners = Object.fromEntries(['sessions', 'sessionPersistence', 'sessionQuery'].map(name => [name, ctx.get(name)]))
   // One spelling of "the current document": the same resolved configuration the
   // reconciliation loop applies, so a delivered message and the assembled prompt can
-  // never read two different prompt-text documents. Read lazily: the settings section
-  // replaces `configSource` after activation.
+  // never read two different prompt-text documents. One holder per attachment, handed
+  // to the runtime it installs, so two attachments in one process keep their own
+  // document. Read lazily: the settings section replaces `configSource` after
+  // activation.
   const currentPromptText = () => resolvePromptTextConfig(configSource())
   const messageOwner = createRuntimeMessageOwner(context => (
     committed?.retiring ? [] : committed?.runtime.contextsForRequest(context) ?? []
@@ -918,8 +1027,17 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
   ctx.effect(() => ctx.on('agent/disposed', ({ agent }) => messageOwner.disposeAgent(agent)), 'ptc-plus message agent disposal')
   ctx.effect(() => () => messageOwner.dispose(), 'ptc-plus dynamic message lifecycle')
   ctx.effect(() => async () => {
-    await controller.dispose()
+    // The model-visible handback states a fact about execution, so it must not
+    // ride on whether every projection unregistered: a failed disposal is
+    // reported by the caller that retries it, and the runtime is gone either way.
+    let disposalFailure
+    try {
+      await controller.dispose()
+    } catch (error) {
+      disposalFailure = error
+    }
     await handBackRuntimeSessions(ctx, handbackOwners)
+    if (disposalFailure !== undefined) throw disposalFailure
   }, 'ptc-plus provider handback')
 
   // The settings section replaces this source after activation; the prompt-text
@@ -937,11 +1055,28 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
     try {
       if (settingsWriter?.update === undefined) return
       const previousConfig = controller.committedConfig()
+      // A policy this process synthesized is not a record the settings document holds: write it
+      // back and the next resolution reports it as saved, so the rollback removes the field with
+      // the service's own `unset` op when it offers one. The two switches derived beside it are
+      // restated to the committed values; a service without `unset` keeps the previous, narrower
+      // behaviour and the residual is stated in capability-surface §8.7.
+      const keepDerived = previousConfig?.capabilityPolicySaved === true
+      // Only a committed configuration that reports it saved no policy lets the rollback remove
+      // one: with no committed record this process does not know what the document holds, and
+      // deleting a policy it never wrote would erase rules the user saved.
+      const removable = previousConfig !== undefined && previousConfig.capabilityPolicySaved === false
+        && typeof settingsWriter.mutate === 'function'
       const patch = previousConfig === undefined
         ? { enabled: false }
-        : Object.fromEntries(CONFIG_FIELDS.map(field => [field.key, previousConfig[field.key]]))
+        : Object.fromEntries(CONFIG_FIELDS
+          // Only the policy is synthesized with the two switches; a writer without `mutate` cannot
+          // remove it, so it omits that one field and still restates everything else it derived.
+          .filter(field => keepDerived || field.key !== 'capabilityPolicy')
+          .map(field => [field.key, previousConfig[field.key]]))
       try {
-        await settingsWriter.update(patch)
+        if (removable && Object.keys(patch).length > 0) await settingsWriter.update(patch)
+        if (removable) await settingsWriter.mutate([{ op: 'unset', path: ['capabilityPolicy'] }])
+        else await settingsWriter.update(patch)
       } catch (rollbackError) {
         reportActivationFailure(new Error(
           `ptc-plus: failed to roll back runtime configuration: ${rollbackError.message}`,

package/internal/binding-adoption.js

@@ -0,0 +1,228 @@
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { isPtcMessageSource, PTC_MESSAGE_SOURCE_KIND, RETIRED_SURFACE_RECORD } from './message-sources.js'
+
+/**
+ * Session binding adoption: which Global User Binding catalog entries this
+ * session uses.
+ *
+ * The question is answered per session and per entry, and the answer is a
+ * decision of exactly two states: this session uses the entry, or it does not.
+ * An entry the session never named is used, because the global catalog already
+ * answered the supply question. That default is the absence of a decision, not
+ * a third state: "use" and "never mentioned" lead to the same environment, so
+ * they are one state rather than two.
+ *
+ * Adoption can only take an entry away from this session. It cannot supply one,
+ * enable one, or name a source: an entry the global configuration disabled is
+ * absent from the catalog, so "adoption revives a deleted entry" has no
+ * encoding here and needs no rule forbidding it. Naming an entry the catalog
+ * does not offer is rejected at the surface that states the decision, because
+ * the record would otherwise claim authority over supply.
+ *
+ * The neighbour this must not be confused with is the capability pane's
+ * `automatic`, which means "the host derives this value". A binding has no host
+ * derivation to defer to, so borrowing that word would misdescribe both.
+ *
+ * The decision is recorded as a plugin record in the session log, so it is
+ * reconstructed by replaying that log after a restart instead of being kept in
+ * process memory. The message form is the historical carrier that 0.5.4 and
+ * earlier wrote; it is still read (those sessions keep their decision, and a
+ * repaired statement answers through it), and no writer produces it.
+ */
+export const BINDING_ADOPTION_FORM = 'binding-adoption'
+export const BINDING_ADOPTION_SCHEMA = 'ptc-binding-adoption/v1'
+
+/**
+ * The log record this session's adoption is written as.
+ *
+ * Adoption is a decision about this session's own environment: the catalog the
+ * model reads already reflects it, so the decision needs no message of its own.
+ * Writing it as a record makes it durable and immediate — it is taken the moment
+ * the control is used, before any step, without entering the model-visible surface
+ * (a surface node ahead of the host's protected head would make the log
+ * unreadable to every reader). A host that publishes no plugin-record writer
+ * refuses the write instead of falling back to that surface node.
+ */
+export const BINDING_ADOPTION_RECORD = 'plugin:ptc-plus/binding-adoption'
+
+const MAX_DECLINED = 64
+const ENTRY_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/
+const PREFIX = 'PTC Plus session binding adoption. This session uses every entry the global catalog supplies except the declined ones. Adoption can only withdraw an entry from this session: it cannot supply, enable or revive one, and the global configuration decides which entries exist at all. Declined entry IDs:'
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function sortIds(ids) {
+  return [...ids].sort((left, right) => left < right ? -1 : left > right ? 1 : 0)
+}
+
+export function normalizeBindingAdoption(value) {
+  if (!isRecord(value) || Reflect.ownKeys(value).length !== 2
+    || !Object.hasOwn(value, 'schema') || !Object.hasOwn(value, 'declined')) {
+    throw new TypeError('invalid binding adoption')
+  }
+  if (value.schema !== BINDING_ADOPTION_SCHEMA) throw new TypeError('invalid binding adoption schema')
+  if (!Array.isArray(value.declined) || value.declined.length > MAX_DECLINED) {
+    throw new TypeError('invalid binding adoption declined entries')
+  }
+  const declined = []
+  for (const id of value.declined) {
+    if (typeof id !== 'string' || !ENTRY_ID.test(id)) throw new TypeError('invalid binding adoption entry id')
+    if (declined.includes(id)) throw new TypeError('duplicate binding adoption entry id')
+    declined.push(id)
+  }
+  return Object.freeze({ schema: BINDING_ADOPTION_SCHEMA, declined: Object.freeze(sortIds(declined)) })
+}
+
+/** The exact model-visible wording one adoption record carries. */
+export function bindingAdoptionText(adoption) {
+  return `${PREFIX}\n${JSON.stringify(normalizeBindingAdoption(adoption).declined)}`
+}
+
+/** The historical message this adoption was written as before the record carrier. */
+export function bindingAdoptionMessage(adoption) {
+  const text = bindingAdoptionText(adoption)
+  const message = createUserMessage({
+    source: { kind: PTC_MESSAGE_SOURCE_KIND, form: BINDING_ADOPTION_FORM },
+    content: [{ type: 'text', text }],
+  })
+  if (readBindingAdoption(message) === undefined) throw new TypeError('invalid binding adoption message')
+  return message
+}
+
+/** Read one adoption record back from a message, message projection or message fact. */
+export function readBindingAdoption(value) {
+  const source = value?.source
+  if (!isPtcMessageSource(source) || source.form !== BINDING_ADOPTION_FORM) return undefined
+  if (!Array.isArray(value.content) || value.content.length !== 1 || value.content[0]?.type !== 'text') return undefined
+  const text = value.content[0].text
+  if (typeof text !== 'string' || !text.startsWith(`${PREFIX}\n`)) return undefined
+  try {
+    const declined = JSON.parse(text.slice(PREFIX.length + 1))
+    const adoption = normalizeBindingAdoption({ schema: BINDING_ADOPTION_SCHEMA, declined })
+    return bindingAdoptionText(adoption) === text ? adoption : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * How this session's newest adoption statement reads.
+ *
+ * `none` is the absence of a decision, `decided` is a statement this build can
+ * read, and `unreadable` is a statement it cannot. The third state is not the
+ * first: an unreadable newest statement still supersedes every earlier record,
+ * so no consumer may answer from the older one in its place. `latestBindingAdoption`
+ * collapses the last two into `undefined`, which is why the panel asks this
+ * function instead: `undefined` there means "no decision to apply", not "the
+ * session declined nothing".
+ */
+export function classifyBindingAdoption(records) {
+  if (!Array.isArray(records)) return Object.freeze({ state: 'none' })
+  for (let index = records.length - 1; index >= 0; index -= 1) {
+    const record = records[index]
+    if (record?.form !== BINDING_ADOPTION_FORM) continue
+    try {
+      return Object.freeze({ state: 'decided',
+        adoption: normalizeBindingAdoption({ schema: BINDING_ADOPTION_SCHEMA, declined: record.declined }) })
+    } catch {
+      // A record that cannot be read is not evidence for an earlier record
+      // either: the newest statement is the current one, and it is unreadable.
+      return Object.freeze({ state: 'unreadable' })
+    }
+  }
+  return Object.freeze({ state: 'none' })
+}
+
+/** Read one committed plugin record back as this session's adoption, or nothing. */
+export function readBindingAdoptionRecord(event) {
+  if (event?.type !== BINDING_ADOPTION_RECORD || event.ignorable !== true) return undefined
+  try {
+    return normalizeBindingAdoption(event.data)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Whether one event states this session's adoption at all.
+ *
+ * The record type states it, and so does the historical message form. A repaired statement
+ * (`RETIRED_SURFACE_RECORD`) states it only when the payload it kept is this owner's own form:
+ * the repair retires every surface node ahead of the protected head, whichever owner wrote it,
+ * so the carrier alone says nothing about who the statement belongs to.
+ */
+function statesBindingAdoption(event) {
+  if (event?.type === BINDING_ADOPTION_RECORD) return true
+  const source = event?.data?.source
+  return isPtcMessageSource(source) && source.form === BINDING_ADOPTION_FORM
+}
+
+/**
+ * Read one adoption out of either carrier, so a reader never has to know which release wrote it —
+ * and a repaired statement answers for the owner whose form it carries.
+ */
+export function readBindingAdoptionStatement(event) {
+  if (event?.type === BINDING_ADOPTION_RECORD) return readBindingAdoptionRecord(event)
+  if (event?.type === RETIRED_SURFACE_RECORD) {
+    return event.ignorable === true && statesBindingAdoption(event) ? readBindingAdoption(event.data) : undefined
+  }
+  return event?.type === 'user/message' ? readBindingAdoption(event.data) : undefined
+}
+
+/**
+ * This session's newest adoption statement, read from its own log events.
+ *
+ * The log is the owner of the decision, so every adoption statement it carries — a record, the
+ * message form an older release wrote, or a repaired statement of the same form — is classified,
+ * including one this build cannot read. Extracting the statements and classifying them here keeps
+ * every reader on the same cut: a reader that filtered to the readable statements first would hand
+ * a superseded record the answer, and the panel and the `/binding` command would then disagree
+ * about which record governs this session.
+ */
+export function bindingAdoptionOf(events) {
+  const records = []
+  for (const event of Array.isArray(events) ? events : []) {
+    if (event?.type !== 'user/message' && event?.type !== BINDING_ADOPTION_RECORD
+      && event?.type !== RETIRED_SURFACE_RECORD) continue
+    // A repair retires every owner's surface node, so only a statement that kept this owner's
+    // form joins the ordering; another owner's retired node is not an adoption at all.
+    if (!statesBindingAdoption(event)) continue
+    records.push({ form: BINDING_ADOPTION_FORM, declined: readBindingAdoptionStatement(event)?.declined })
+  }
+  return classifyBindingAdoption(records)
+}
+
+/**
+ * The newest adoption this session recorded, or `undefined` while it recorded
+ * none this build can read. The newest record replaces earlier ones, because
+ * stating a decision again is how a session changes its mind.
+ */
+export function latestBindingAdoption(records) {
+  const statement = classifyBindingAdoption(records)
+  return statement.state === 'decided' ? statement.adoption : undefined
+}
+
+/**
+ * The declined entry IDs of one adoption, as a set the environment uses.
+ * An adoption that was never stated declines nothing.
+ */
+export function declinedBindingEntries(adoption) {
+  return new Set(adoption === undefined ? [] : normalizeBindingAdoption(adoption).declined)
+}
+
+/** State one entry as used (`adopt` true) or not used, leaving the rest alone. */
+export function withBindingAdoption(adoption, entryId, adopt) {
+  if (typeof entryId !== 'string' || !ENTRY_ID.test(entryId)) throw new TypeError('invalid binding adoption entry id')
+  if (typeof adopt !== 'boolean') throw new TypeError('binding adoption decision must be a boolean')
+  const declined = declinedBindingEntries(adoption)
+  if (adopt) declined.delete(entryId)
+  else declined.add(entryId)
+  return normalizeBindingAdoption({ schema: BINDING_ADOPTION_SCHEMA, declined: [...declined] })
+}
+
+/** Drop every declined entry: this session again uses the whole catalog. */
+export function clearedBindingAdoption() {
+  return normalizeBindingAdoption({ schema: BINDING_ADOPTION_SCHEMA, declined: [] })
+}