dsh-ptc-plus 0.5.3 → 0.5.6

package/index.js

@@ -123,6 +123,47 @@ 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, readPromptText) {
   const presentationGeneration = randomUUID()
@@ -375,7 +416,10 @@ 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,
@@ -430,6 +474,10 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolS
     let unreadableTransportReported = false
     disposers.push(ctx.on('system-prompt/assemble', async (assembly, context, next) => {
       const projected = await directSurface.assemble(assembly, context, next)
+      // 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.
@@ -462,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) }
@@ -478,41 +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, proof) => capabilityCommandReceipt(state, String(agent.session.id), error,
-              state === 'pending' && capabilityEnvironment.pendingChoiceMessage(agent)
-                ? { commandId, rawInput, message: capabilityEnvironment.pendingChoiceMessage(agent) } : undefined,
-              proof)
+            // 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 save states what it changed and what it did not prove: the
-              // model-visible catalog and a cell that reached the capability are
-              // separate facts, reported by the layer that owns each one.
-              const proof = capabilityEnvironment.describeCapabilityProof(agent, decodeURIComponent(selection[2]))
+              // 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, proof) }
+                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.
@@ -684,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)
@@ -985,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

@@ -1,5 +1,5 @@
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
-import { isPtcMessageSource, PTC_MESSAGE_SOURCE_KIND } from './message-sources.js'
+import { isPtcMessageSource, PTC_MESSAGE_SOURCE_KIND, RETIRED_SURFACE_RECORD } from './message-sources.js'
 
 /**
  * Session binding adoption: which Global User Binding catalog entries this
@@ -23,13 +23,28 @@ import { isPtcMessageSource, PTC_MESSAGE_SOURCE_KIND } from './message-sources.j
  * `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 one PTC message in the session log, so it is
+ * 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.
+ * 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:'
@@ -65,6 +80,7 @@ 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({
@@ -92,24 +108,100 @@ export function readBindingAdoption(value) {
 }
 
 /**
- * The newest adoption this session recorded, or `undefined` while it recorded
- * none. The newest record replaces earlier ones, because stating a decision
- * again is how a session changes its mind.
+ * 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 latestBindingAdoption(records) {
-  if (!Array.isArray(records)) return undefined
+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 normalizeBindingAdoption({ schema: BINDING_ADOPTION_SCHEMA, declined: record.declined })
+      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 undefined
+      return Object.freeze({ state: 'unreadable' })
     }
   }
-  return undefined
+  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
 }
 
 /**

package/internal/capability-command-receipt.js

@@ -1,6 +1,14 @@
-/** Structured command outcome for locale-owned Client receipts; text remains a CLI fallback. */
-import { capabilityProofText, normalizeCapabilityProof } from './capability-delivery-proof.js'
-
+/**
+ * Structured command outcome for locale-owned Client receipts; text remains a CLI fallback.
+ *
+ * A receipt states the one write a command performed: which entry, which choice,
+ * and which owner now records it. Whether a cell later reached that entry is a
+ * different question with a different owner — a catalogue row's `evidence` field,
+ * where a marker means an accepted execution obtained it, and which the page does
+ * not state — so a receipt that restated
+ * a degree of proof would answer a question this command never asked and could
+ * not answer.
+ */
 const PREFIX = '\n\nPTC Plus capability refresh receipt:\n'
 const FALLBACKS = Object.freeze({
   'saved-only': 'Global choice saved, but the session update failed; inspect and retry session',
@@ -12,34 +20,110 @@ const FALLBACKS = Object.freeze({
   off: 'Capability management is off; the session stays with the Host capabilities for session',
 })
 const STATES = new Set(['recorded', 'pending', 'unavailable', 'usage', 'saved-only', 'paused', 'off'])
+const SCOPES = new Set(['session', 'global'])
+const DIMENSIONS = new Set(['availability', 'disclosure'])
+// Every choice `/capabilities set` accepts, so a receipt cannot name a write the
+// command would have refused.
+const SELECTIONS = new Set(['full', 'on-demand', 'closed', 'automatic', 'inherit', 'enabled', 'host', 'adaptive'])
+/**
+ * What the receipt's one-line sentence needs from an id: no whitespace, bounded length.
+ *
+ * Which ids a choice may name is the record vocabulary's question
+ * (`capability-selection.js`), answered once where the record is written. Asking it
+ * again here would be a second owner of the same vocabulary, and a stricter second
+ * owner refuses a record the session already holds: the write lands, the receipt cannot
+ * be composed, and the command reports a failure it did not have. This predicate is a
+ * strict superset of that vocabulary, so every record a writer accepts is reportable.
+ */
+const ENTRY_ID = /^\S{1,256}$/
+/**
+ * Releases up to 0.5.4 appended a saved/delivered/usable report to the same
+ * receipt. Such a receipt stays readable — the Client renders the outcome it
+ * recorded instead of falling back to its raw text — and the report is dropped
+ * before any consumer sees it. Its wording is frozen history this build does not
+ * reproduce, so its opening segment plus the stored facts are the whole check.
+ */
+const LEGACY_REPORT = ' Saved: '
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/** One written choice, closed over the vocabulary the writer accepts. */
+function commandRecord(value) {
+  if (!isRecord(value) || !SCOPES.has(value.scope) || typeof value.id !== 'string' || !ENTRY_ID.test(value.id)
+    || !SELECTIONS.has(value.selection)
+    || value.dimension !== undefined && !DIMENSIONS.has(value.dimension)
+    || Reflect.ownKeys(value).length !== (value.dimension === undefined ? 3 : 4)) {
+    throw new TypeError('invalid capability command record')
+  }
+  return Object.freeze({
+    scope: value.scope,
+    id: value.id,
+    ...(value.dimension === undefined ? {} : { dimension: value.dimension }),
+    selection: value.selection,
+  })
+}
+
+/** The sentence a non-Client reader gets; the Client states the same facts in its own words. */
+function recordFallback(record) {
+  const dimension = record.dimension === undefined ? '' : ` ${record.dimension}`
+  return `Recorded ${record.id}${dimension} = ${record.selection}`
+    + (record.scope === 'global' ? ' in the global configuration.' : ' for this session.')
+}
 
-export function capabilityCommandReceipt(state, sessionId, error, proposal, proof) {
+export function capabilityCommandReceipt(state, sessionId, error, proposal, record) {
   if (!STATES.has(state) || typeof sessionId !== 'string' || !sessionId) throw new TypeError('invalid capability command receipt')
   if (error !== undefined && (state !== 'saved-only' || typeof error !== 'string' || !error)) throw new TypeError('invalid capability command error')
   if (proposal !== undefined && (state !== 'pending' || !proposal || typeof proposal.commandId !== 'string'
     || typeof proposal.rawInput !== 'string' || !proposal.message)) throw new TypeError('invalid capability proposal receipt')
-  // A command that names one capability reports that capability's three layers
-  // beside the session outcome, so "saved" cannot be read as "delivered" or
-  // "usable". The schema stays v1 because the field is additive: receipts
-  // recorded before it existed still reproduce their own text.
-  const layers = proof === undefined ? undefined : normalizeCapabilityProof(proof)
+  // Only a receipt that says the write happened names one: a command whose session
+  // write failed reports that failure instead of naming a record it never appended.
+  if (record !== undefined && state !== 'recorded') throw new TypeError('invalid capability command record state')
+  const written = record === undefined ? undefined : commandRecord(record)
   return `${FALLBACKS[state]} ${sessionId}.${error ? ` ${error}` : ''}`
-    + (layers === undefined ? '' : ` ${capabilityProofText(layers)}`)
+    + (written === undefined ? '' : ` ${recordFallback(written)}`)
     + PREFIX
     + JSON.stringify({
       schema: 'ptc-capability-command/v1', state, sessionId,
       ...(error === undefined ? {} : { error }),
       ...(proposal === undefined ? {} : { proposal }),
-      ...(layers === undefined ? {} : { proof: layers }),
+      ...(written === undefined ? {} : { record: written }),
     })
 }
 
+/**
+ * The receipt a command text carries, or `undefined` for any other text.
+ *
+ * A receipt this build writes is read only when the whole text is exactly what
+ * the writer produces from the facts it stores. A 0.5.4 receipt carries the
+ * report described above instead, and its visible sentence cannot be reproduced
+ * without keeping that wording, so its stored facts decide: the outcome sentence,
+ * the field order and the record of what was written must all be the writer's.
+ */
 export function readCapabilityCommandReceipt(text) {
   if (typeof text !== 'string' || !text.includes(PREFIX)) return undefined
+  const cut = text.indexOf(PREFIX)
+  let stored
+  try { stored = JSON.parse(text.slice(cut + PREFIX.length)) } catch { return undefined }
+  if (stored?.schema !== 'ptc-capability-command/v1' || !STATES.has(stored.state)) return undefined
+  let current
   try {
-    const receipt = JSON.parse(text.slice(text.indexOf(PREFIX) + PREFIX.length))
-    return receipt?.schema === 'ptc-capability-command/v1' && STATES.has(receipt.state)
-      && typeof receipt.sessionId === 'string' && receipt.sessionId
-      && capabilityCommandReceipt(receipt.state, receipt.sessionId, receipt.error, receipt.proposal, receipt.proof) === text ? receipt : undefined
+    current = capabilityCommandReceipt(stored.state, stored.sessionId, stored.error, stored.proposal, stored.record)
   } catch { return undefined }
+  if (stored.proof === undefined) return current === text ? stored : undefined
+  const head = current.slice(0, current.indexOf(PREFIX))
+  if (!text.startsWith(head)) return undefined
+  const sentence = text.slice(head.length, cut)
+  // One report segment, one line, directly after the outcome sentence: the shape
+  // the 0.5.4 writer produced from these stored facts.
+  if (stored.record !== undefined || !sentence.startsWith(LEGACY_REPORT)
+    || sentence.includes('\n') || sentence.split(LEGACY_REPORT).length !== 2) return undefined
+  const fields = Object.keys(JSON.parse(current.slice(current.indexOf(PREFIX) + PREFIX.length)))
+  if (Object.keys(stored).join() !== [...fields, 'proof'].join()) return undefined
+  return {
+    schema: stored.schema, state: stored.state, sessionId: stored.sessionId,
+    ...(stored.error === undefined ? {} : { error: stored.error }),
+    ...(stored.proposal === undefined ? {} : { proposal: stored.proposal }),
+  }
 }