dsh-ptc-plus 0.5.1 → 0.5.3

package/internal/bounded-literal.js

@@ -0,0 +1,85 @@
+/**
+ * Compile-time evidence that a declaration's initializer is a bounded object
+ * literal.
+ *
+ * Recovery records a binding's value at settlement so it can be installed
+ * without re-executing the cell. Recording an arbitrary object is unsafe: the
+ * value codec enumerates an object's own keys before it can apply any budget,
+ * and enumerating a graph with millions of keys exhausts the worker heap before
+ * a cap can reject it (a four-million-key object aborts a 128 MiB worker).
+ *
+ * This module decides the question where it is cheap — on the syntax tree of the
+ * initializer — and returns the proven shape only for literals whose size is
+ * fixed by their source: an object literal with a bounded number of plain,
+ * non-computed properties whose values are primitives, array literals, or other
+ * such literals up to a fixed depth. Everything else (an identifier, a call, a
+ * class instance) yields no evidence, and its binding stays unrecorded and is
+ * named by recovery instead of being captured.
+ */
+
+/** Maximum number of own properties a recordable literal may declare. */
+export const RECORDED_LITERAL_MAX_PROPERTIES = 32
+
+/** Maximum nesting depth of recordable literals, counting the outer object. */
+export const RECORDED_LITERAL_MAX_DEPTH = 3
+
+/** Maximum number of array elements a recordable array literal may declare. */
+export const RECORDED_LITERAL_MAX_ELEMENTS = 64
+
+const OBJECT_PROPERTY_TYPES = new Set(['ObjectProperty', 'Property'])
+const LITERAL_KEY_TYPES = new Set(['StringLiteral', 'NumericLiteral', 'Literal', 'Identifier'])
+const PRIMITIVE_LITERAL_TYPES = new Set(['StringLiteral', 'NumericLiteral', 'BooleanLiteral', 'NullLiteral',
+  'BigIntLiteral', 'RegExpLiteral'])
+
+function isRecordableValue(node, depth) {
+  if (node === null || node === undefined) return false
+  // ESTree parsers emit `Literal`; Babel emits the typed variants above.
+  if (node.type === 'Literal') {
+    const value = node.value
+    return value === null || ['number', 'string', 'boolean', 'bigint'].includes(typeof value)
+      || node.regex !== undefined
+  }
+  if (PRIMITIVE_LITERAL_TYPES.has(node.type)) return true
+  if (node.type === 'TemplateLiteral') return node.expressions.length === 0
+  if (node.type === 'UnaryExpression') {
+    return ['-', '+', '!', 'void'].includes(node.operator) && isRecordableValue(node.argument, depth)
+  }
+  if (node.type === 'ObjectExpression') return boundedLiteralEvidence(node, depth) !== undefined
+  if (node.type === 'ArrayExpression') {
+    return node.elements.length <= RECORDED_LITERAL_MAX_ELEMENTS
+      && node.elements.every(element => isRecordableValue(element, depth))
+  }
+  return false
+}
+
+/**
+ * Evidence for one object literal, or `undefined` when the literal's size is
+ * not fixed by its source.
+ *
+ * @param {object} node an ESTree/Babel `ObjectExpression`
+ * @param {number} [depth] nest level of this literal, 1 for the top object
+ * @returns {{ properties: number, depth: number } | undefined}
+ */
+export function boundedLiteralEvidence(node, depth = 1) {
+  if (node?.type !== 'ObjectExpression') return undefined
+  if (depth > RECORDED_LITERAL_MAX_DEPTH) return undefined
+  if (node.properties.length > RECORDED_LITERAL_MAX_PROPERTIES) return undefined
+  let proven = 0
+  for (const property of node.properties) {
+    // `kind` is 'init' on most Babel versions and absent on some parses; an
+    // accessor or method arrives as `ObjectMethod`, which this branch rejects
+    // through the `type` check above.
+    if (!OBJECT_PROPERTY_TYPES.has(property.type) || property.computed === true
+      || (property.kind !== undefined && property.kind !== 'init') || property.method === true) return undefined
+    const key = property.key
+    if (!LITERAL_KEY_TYPES.has(key.type)) return undefined
+    const valueNode = property.value
+    if (valueNode.type === 'ObjectExpression') {
+      if (boundedLiteralEvidence(valueNode, depth + 1) === undefined) return undefined
+    } else if (!isRecordableValue(valueNode, depth)) {
+      return undefined
+    }
+    proven += 1
+  }
+  return { properties: proven, depth }
+}

package/internal/capability-command-receipt.js

@@ -1,4 +1,6 @@
 /** Structured command outcome for locale-owned Client receipts; text remains a CLI fallback. */
+import { capabilityProofText, normalizeCapabilityProof } from './capability-delivery-proof.js'
+
 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',
@@ -11,13 +13,25 @@ const FALLBACKS = Object.freeze({
 })
 const STATES = new Set(['recorded', 'pending', 'unavailable', 'usage', 'saved-only', 'paused', 'off'])
 
-export function capabilityCommandReceipt(state, sessionId, error, proposal) {
+export function capabilityCommandReceipt(state, sessionId, error, proposal, proof) {
   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')
-  return `${FALLBACKS[state]} ${sessionId}.${error ? ` ${error}` : ''}` + PREFIX
-    + JSON.stringify({ schema: 'ptc-capability-command/v1', state, sessionId, ...(error === undefined ? {} : { error }), ...(proposal === undefined ? {} : { proposal }) })
+  // 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)
+  return `${FALLBACKS[state]} ${sessionId}.${error ? ` ${error}` : ''}`
+    + (layers === undefined ? '' : ` ${capabilityProofText(layers)}`)
+    + PREFIX
+    + JSON.stringify({
+      schema: 'ptc-capability-command/v1', state, sessionId,
+      ...(error === undefined ? {} : { error }),
+      ...(proposal === undefined ? {} : { proposal }),
+      ...(layers === undefined ? {} : { proof: layers }),
+    })
 }
 
 export function readCapabilityCommandReceipt(text) {
@@ -26,6 +40,6 @@ export function readCapabilityCommandReceipt(text) {
     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) === text ? receipt : undefined
+      && capabilityCommandReceipt(receipt.state, receipt.sessionId, receipt.error, receipt.proposal, receipt.proof) === text ? receipt : undefined
   } catch { return undefined }
 }

package/internal/capability-delivery-proof.js

@@ -0,0 +1,70 @@
+/**
+ * One capability, three separate facts.
+ *
+ * Saving a global choice changes supply: the configuration now records a
+ * decision. It does not prove the model ever received that decision, and it does
+ * not prove a cell can reach the capability. Those are different questions with
+ * different owners:
+ *
+ * - **saved**: the global configuration records a choice for this capability.
+ * - **delivered**: the model-visible capability catalog published it at an
+ *   accepted step, rather than waiting for the next one or never listing it.
+ * - **usable**: a completed execution in this session actually reached it.
+ *
+ * Usability is only ever proved by an execution result. Nothing else in the
+ * product can claim it: a saved switch, a published catalog entry and an
+ * installed tool schema are all statements about intent, not about a value a
+ * cell obtained. Reporting "saved, delivered, usability unproven" is therefore
+ * the honest answer to "did that save take effect", and it is what a layer that
+ * cannot prove more must say instead of claiming effect.
+ */
+export const CAPABILITY_PROOF_SCHEMA = 'ptc-capability-proof/v1'
+export const CAPABILITY_DELIVERY_STATES = new Set(['delivered', 'pending', 'absent'])
+export const CAPABILITY_USABILITY_STATES = new Set(['proven', 'unproven'])
+
+const CAPABILITY_ID = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$/
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+export function normalizeCapabilityProof(value) {
+  if (!isRecord(value) || Reflect.ownKeys(value).length !== 5
+    || !Object.hasOwn(value, 'schema') || !Object.hasOwn(value, 'id') || !Object.hasOwn(value, 'saved')
+    || !Object.hasOwn(value, 'delivery') || !Object.hasOwn(value, 'usability')) {
+    throw new TypeError('invalid capability proof')
+  }
+  if (value.schema !== CAPABILITY_PROOF_SCHEMA) throw new TypeError('invalid capability proof schema')
+  if (typeof value.id !== 'string' || !CAPABILITY_ID.test(value.id)) throw new TypeError('invalid capability proof id')
+  if (typeof value.saved !== 'boolean') throw new TypeError('invalid capability proof saved fact')
+  if (!CAPABILITY_DELIVERY_STATES.has(value.delivery)) throw new TypeError('invalid capability proof delivery state')
+  if (!CAPABILITY_USABILITY_STATES.has(value.usability)) throw new TypeError('invalid capability proof usability state')
+  return Object.freeze({
+    schema: CAPABILITY_PROOF_SCHEMA,
+    id: value.id,
+    saved: value.saved,
+    delivery: value.delivery,
+    usability: value.usability,
+  })
+}
+
+/**
+ * The model-visible sentence for one proof. Each layer states its own result, so
+ * a reader can tell which layer failed instead of reading one blanket "applied".
+ */
+export function capabilityProofText(proof) {
+  const normalized = normalizeCapabilityProof(proof)
+  const id = normalized.id
+  const saved = normalized.saved
+    ? `Saved: yes. The global configuration records a choice for ${id}.`
+    : `Saved: no. The global configuration records no choice for ${id}, so this save did not happen; the session choice below is the only change.`
+  const delivery = {
+    delivered: `Delivered: yes. The model-visible capability catalog published ${id} at an accepted step.`,
+    pending: `Delivered: not yet. The saved configuration reaches the model-visible catalog at the next accepted step, so ${id} is not in it now.`,
+    absent: `Delivered: no. The published capability catalog does not list ${id}, so the model never received it.`,
+  }[normalized.delivery]
+  const usability = normalized.usability === 'proven'
+    ? `Usable: proven. A completed execution in this session reached ${id}.`
+    : `Usable: unproven. No completed execution in this session reached ${id}; only such a result would prove it, and a saved or published entry does not.`
+  return `${saved} ${delivery} ${usability}`
+}

package/internal/capability-environment.js

@@ -1,7 +1,7 @@
 import { capabilityRule, capabilityPolicyForConfig, changeCapabilityRule, effectiveCapabilitySettings, CAPABILITY_DISCLOSURES, CAPABILITY_INVENTORY_CATEGORIES } from './capability-policy.js'
 /** One session-owned capability view for presentation, discovery and preparation. */
 import { createHash } from 'node:crypto'
-import { jsonSchemaToTs, renderToolsSdk, ToolNotFoundError } from '@deepseek-ai/dsh-tools'
+import { jsonSchemaToTs, renderToolsSdk, ToolNotFoundError } from './host-tool-sdk.js'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { isModelInvocable, isUserInvocable } from '@deepseek-ai/dsh-skill'
 import { createScope } from '@deepseek-ai/dsh-scope'
@@ -9,11 +9,14 @@ import { Context } from '@deepseek-ai/cordis'
 import * as spillPolicy from '@deepseek-ai/dsh-spill-policy'
 import { readSessionLog } from './session-events.js'
 import { readCapabilityCommandReceipt } from './capability-command-receipt.js'
+import { normalizeCapabilityProof } from './capability-delivery-proof.js'
 import { createCapabilityPlan } from './capability-plan.js'
 import { PTC_MESSAGE_SOURCE_KIND } from './message-sources.js'
 import { deepFreeze } from './record-utils.js'
 import { capabilityProfileConfiguration } from './runtime-config.js'
 import { readRuntimeAvailability } from './runtime-messages.js'
+import { PLAN_CATEGORY_LINES, PLAN_NAVIGATION, PLAN_OVERAGE, PLAN_OVERAGE_HOLE,
+  PROMPT_SLOT_IDS, planCategorySlotId, resolvePromptText, resolvePromptTextConfig } from './prompt-text.js'
 
 export const CAPABILITY_PLAN_FORM = 'capability-plan'
 export const CAPABILITY_EVIDENCE_KEY = 'dshPtcPlusCapabilities'
@@ -25,6 +28,54 @@ const LEGACY_NAVIGATION = 'Use capabilities.search({query}) to retrieve complete
 const NAVIGATION = 'Use capabilities.search({query}) to retrieve complete tool, Skill and MCP contracts. Unlisted capabilities remain discoverable. Skill descriptions are summaries; follow each Skill\'s declared invocation eligibility to load its body before following it.'
 const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex')
 const messageText = message => message?.content?.filter(block => block.type === 'text').map(block => block.text).join('\n') ?? ''
+const byteLength = value => Buffer.byteLength(value, 'utf8')
+
+/**
+ * Delivered plan-channel text, resolved from the prompt-text document.
+ *
+ * The planner must receive the same words the panel shows, so the navigation
+ * sentence, the five category lines and the overage template are read once here
+ * rather than defaulting inside the planner. `isDefault` decides whether the
+ * snapshot can keep a historical generation: only an edited channel needs the v5
+ * record, so an untouched configuration stays byte-identical to before.
+ */
+function planChannelText(config) {
+  const prompt = resolvePromptTextConfig(config)
+  const navigationSentence = prompt.text(PROMPT_SLOT_IDS.planNavigationSentence)
+  const overageSentence = prompt.text(PROMPT_SLOT_IDS.planOverageSentence)
+  const categoryLines = Object.keys(PLAN_CATEGORY_LINES)
+    .map(category => [category, prompt.text(planCategorySlotId(category))])
+  const isDefault = navigationSentence === PLAN_NAVIGATION
+    && overageSentence === PLAN_OVERAGE
+    && categoryLines.every(([category, line]) => line === PLAN_CATEGORY_LINES[category])
+  return { navigationSentence, overageSentence, categoryLines, isDefault }
+}
+
+/**
+ * Directory budget for the delivered guidance.
+ *
+ * Editing a navigation sentence changes how many bytes the directory spends before
+ * any capability entry, so the budget moves with the text: an unchanged document
+ * therefore keeps today's budget exactly, and a longer sentence does not silently
+ * shrink the catalog.
+ */
+const planDirectoryBudget = (configured, navigationSentence) => (
+  configured + byteLength(navigationSentence) - byteLength(PLAN_NAVIGATION))
+
+/**
+ * Recorded plan text; a v5 snapshot carries the words and the budget it was
+ * composed from.
+ *
+ * The budget belongs in the record because it depends on the navigation sentence:
+ * replaying it from the current default literal would let a later edit of that
+ * literal silently change what an old snapshot replays to.
+ */
+const planPromptText = (channel, directoryBudgetBytes) => ({ promptText: {
+  navigationSentence: channel.navigationSentence,
+  categoryLines: channel.categoryLines.map(([category, line]) => [category, line]),
+  overageSentence: channel.overageSentence,
+  directoryBudgetBytes,
+} })
 
 /** Saved inputs and explicit session choices are distinct; automatic cancels a saved override. */
 export function sessionCapabilitySettings(sourceSettings, sessionOverrides = {}) {
@@ -85,9 +136,19 @@ function sourcePlan(message, id) {
   const source = message?.source
   if (source?.kind !== PTC_MESSAGE_SOURCE_KIND || source.form !== CAPABILITY_PLAN_FORM || source.sessionId !== id) return undefined
   const snapshot = source.snapshot
-  const generation = ['ptc-capability-environment/v1', 'ptc-capability-environment/v2', 'ptc-capability-environment/v3', 'ptc-capability-environment/v4'].indexOf(snapshot?.schema)
+  const generation = ['ptc-capability-environment/v1', 'ptc-capability-environment/v2', 'ptc-capability-environment/v3',
+    'ptc-capability-environment/v4', 'ptc-capability-environment/v5'].indexOf(snapshot?.schema)
+  // Historical generations each had one planner generation for a given settings
+  // shape, so their plan schema is part of the record's identity. Generation 5
+  // records the plan words instead, and its plan schema follows from the recorded
+  // settings: the recomputation below proves the whole plan, which makes a separate
+  // schema guess both unnecessary and wrong (a v5 snapshot may carry context
+  // settings and therefore a v3 plan, or a closed plan and therefore a v2 one).
+  const expectedPlanSchema = generation === 2 ? 'ptc-capability-plan/v2'
+    : generation >= 3 && snapshot.settings.policy !== undefined ? 'ptc-capability-plan/v3' : 'ptc-capability-plan/v1'
   if (source.digest !== digest(snapshot) || generation < 0
-    || !Array.isArray(snapshot.capabilities) || snapshot.plan?.schema !== (generation === 3 ? 'ptc-capability-plan/v3' : generation === 2 ? 'ptc-capability-plan/v2' : 'ptc-capability-plan/v1')) {
+    || !Array.isArray(snapshot.capabilities)
+    || (generation < 4 && snapshot.plan?.schema !== expectedPlanSchema)) {
     throw new Error('damaged session capability plan')
   }
   if (generation >= 1) {
@@ -100,30 +161,74 @@ function sourcePlan(message, id) {
     }
     if (JSON.stringify(merged) !== JSON.stringify(snapshot.settings)) throw new Error('inconsistent session capability choices')
   }
-  if (generation === 3 ? typeof snapshot.settings.contextEnabled !== 'boolean' : snapshot.settings.contextEnabled !== undefined) {
+  // v4 implies a context generation; v5 only says the plan words were edited, so it
+  // may or may not carry context settings.
+  const contextGeneration = generation === 3 ? typeof snapshot.settings.contextEnabled === 'boolean'
+    : generation === 4 ? true : snapshot.settings.contextEnabled === undefined
+  if (!contextGeneration) {
     throw new Error('inconsistent capability context generation')
   }
-  if (generation === 2 || generation === 3 && snapshot.settings.policy !== undefined) {
+  if (generation === 2 || generation >= 3 && snapshot.settings.policy !== undefined) {
     if (!snapshot.settings.policy || typeof snapshot.settings.recoveryEnabled !== 'boolean'
       || typeof snapshot.settings.previewEnabled !== 'boolean') throw new Error('damaged capability policy settings')
   } else if (snapshot.settings.policy !== undefined) throw new Error('inconsistent historical capability generation')
-  if (snapshot.navigationText !== undefined && snapshot.navigationText !== NAVIGATION) throw new Error('unknown capability navigation contract')
+  // A v5 snapshot carries the plan words it was composed from; a historical
+  // generation may only claim the registry defaults it was delivered with.
+  const recorded = generation === 4 ? planRecord(snapshot) : undefined
+  if (recorded === undefined) {
+    if (snapshot.promptText !== undefined) throw new Error('inconsistent capability plan text generation')
+    if (snapshot.navigationText !== undefined && snapshot.navigationText !== NAVIGATION) throw new Error('unknown capability navigation contract')
+  } else if (snapshot.navigationText !== recorded.navigationSentence) {
+    throw new Error('damaged capability plan text')
+  }
   const expected = createCapabilityPlan({ ...snapshot.settings, capabilities: snapshot.capabilities,
     coverage: snapshot.coverage, navigationText: snapshot.navigationText ?? LEGACY_NAVIGATION,
+    ...(recorded === undefined ? {} : {
+      categories: recorded.categoryLines,
+      directoryBudgetBytes: recorded.directoryBudgetBytes,
+    }),
     configurationRevision: digest(snapshot.settings) })
-  if (JSON.stringify(expected) !== JSON.stringify(snapshot.plan)
+  if ((generation >= 4 && snapshot.plan?.schema !== expected.schema)
+    || JSON.stringify(expected) !== JSON.stringify(snapshot.plan)
     || messageText(message) !== messageText(planMessage(snapshot, id, source.refresh === true))) {
     throw new Error('inconsistent session capability plan')
   }
   return deepFreeze(structuredClone(snapshot))
 }
 
+/**
+ * Validated plan words of a v5 snapshot.
+ *
+ * Returns `undefined` only when the snapshot carries no record at all; a record that
+ * exists but cannot be replayed throws, because a half-recorded plan text would let
+ * a later replay silently deliver different words than the ones recorded here.
+ */
+function planRecord(snapshot) {
+  const record = snapshot.promptText
+  if (record === undefined || record === null) return undefined
+  const categories = record.categoryLines
+  const known = Object.keys(PLAN_CATEGORY_LINES)
+  if (typeof record.navigationSentence !== 'string' || record.navigationSentence.length === 0
+    || typeof record.overageSentence !== 'string' || record.overageSentence.split(PLAN_OVERAGE_HOLE).length !== 2
+    || !Number.isSafeInteger(record.directoryBudgetBytes) || record.directoryBudgetBytes < 0
+    || !Array.isArray(categories) || categories.length !== known.length
+    || categories.some(pair => !Array.isArray(pair) || pair.length !== 2
+      || !known.includes(pair[0]) || typeof pair[1] !== 'string' || pair[1].length === 0)
+    || new Set(categories.map(pair => pair[0])).size !== categories.length) {
+    throw new Error('damaged capability plan text')
+  }
+  return { navigationSentence: record.navigationSentence, overageSentence: record.overageSentence,
+    directoryBudgetBytes: record.directoryBudgetBytes,
+    categoryLines: categories.map(([category, line]) => [category, line]) }
+}
+
 function planMessage(snapshot, id, refresh = false) {
   const plan = snapshot.plan
+  const overage = snapshot.promptText?.overageSentence ?? PLAN_OVERAGE
   const text = plan.enabled
     ? ['PTC Plus session capability environment' + (refresh ? ' refreshed; replaces the preceding capability plan.' : ':'),
       plan.directoryText, plan.catalogText,
-      ...(plan.budgets.overageBytes ? [`Explicit full contracts exceed the configured budget by ${plan.budgets.overageBytes} UTF-8 bytes.`] : [])]
+      ...(plan.budgets.overageBytes ? [overage.replace(PLAN_OVERAGE_HOLE, String(plan.budgets.overageBytes))] : [])]
       .filter(Boolean).join('\n\n')
     : snapshot.settings.contextEnabled === false
       ? 'PTC Plus capability and context settings are paused for this session. Use the host-provided capability contracts and result presentation.'
@@ -132,6 +237,43 @@ function planMessage(snapshot, id, refresh = false) {
     sessionId: id, refresh, digest: digest(snapshot), snapshot }, content: [{ type: 'text', text }] })
 }
 
+/**
+ * Delivered plan text for a snapshot, without the message envelope.
+ *
+ * Replay and the surface gate both need the bytes the model reads; keeping the
+ * composition private to this module means a caller cannot assemble a different
+ * plan and call it the delivered one.
+ */
+export function capabilityPlanText(snapshot, id, refresh = false) {
+  return planMessage(snapshot, id, refresh).content[0].text
+}
+
+/**
+ * Delivered plan message for a snapshot, envelope included.
+ *
+ * What this composition can claim is consistency, not provenance: the settings merge
+ * is a fixed point of the recorded settings, the recorded plan deep-equals a
+ * recomputation from them, the delivered text equals a recomposition of that plan and
+ * the snapshots it reads are deeply frozen. It recomputes the digest, so it cannot
+ * attest that these bytes are the ones a session log once carried.
+ */
+export function capabilityPlanMessage(snapshot, id, refresh = false) {
+  return planMessage(snapshot, id, refresh)
+}
+
+/**
+ * Delivered plan text of a plan message, after the replay contract accepted it.
+ *
+ * The reader above stays a recognizer and hands out no composition state; a caller
+ * that needs the bytes the model read asks this projection instead. An unreplayable
+ * message throws, so a lane that compares bytes cannot pass by receiving `undefined`.
+ */
+export function capabilityPlanTextFromMessage(message, sessionId) {
+  if (message?.source?.form !== CAPABILITY_PLAN_FORM) return undefined
+  sourcePlan(message, sessionId)
+  return message.content[0].text
+}
+
 /** Recognize capability-owned presentation for bounded offline context accounting. */
 export function readCapabilityContextMessage(message, sessionId) {
   const source = message?.source
@@ -702,11 +844,22 @@ export function createCapabilityEnvironment({ ctx, config, toolSchemasForAgent,
       const capabilities = requiresCapabilityInventory(settings) ? await inventory(agent, sections ?? [], settings, signal) : []
       const effective = effectiveCapabilitySettings(settings)
       const coverage = (effective.policy ? effective.enabled && effective.policy.allocation.statistics : effective.statistics?.enabled === true) ? await store?.coverage(agent, capabilities, settings.statistics) : undefined
+      const planChannel = planChannelText(currentConfig)
+      const directoryBudgetBytes = planDirectoryBudget(settings.directoryBudgetBytes, planChannel.navigationSentence)
       const plan = createCapabilityPlan({ ...settings, configurationRevision: digest(settings),
-        capabilities, coverage, navigationText: NAVIGATION })
+        capabilities, coverage, navigationText: planChannel.navigationSentence,
+        categories: planChannel.categoryLines,
+        directoryBudgetBytes })
       const hasChoices = settings.contextEnabled !== undefined || settings.policy !== undefined || choice !== undefined || previous?.schema === 'ptc-capability-environment/v2'
-      const snapshot = deepFreeze({ schema: settings.contextEnabled !== undefined ? 'ptc-capability-environment/v4' : settings.policy ? 'ptc-capability-environment/v3' : hasChoices ? 'ptc-capability-environment/v2' : 'ptc-capability-environment/v1',
-        ...(hasChoices ? { sourceSettings, sessionOverrides } : {}), navigationText: NAVIGATION, settings, capabilities, ...(coverage === undefined ? {} : { coverage }), plan })
+      // An edited plan channel needs the v5 record, and that generation requires the
+      // saved inputs and session choices it was composed from.
+      const recordsText = !planChannel.isDefault
+      const snapshot = deepFreeze({ schema: recordsText ? 'ptc-capability-environment/v5'
+        : settings.contextEnabled !== undefined ? 'ptc-capability-environment/v4' : settings.policy ? 'ptc-capability-environment/v3'
+          : hasChoices ? 'ptc-capability-environment/v2' : 'ptc-capability-environment/v1',
+        ...(hasChoices || recordsText ? { sourceSettings, sessionOverrides } : {}),
+        ...(recordsText ? planPromptText(planChannel, directoryBudgetBytes) : {}),
+        navigationText: planChannel.navigationSentence, settings, capabilities, ...(coverage === undefined ? {} : { coverage }), plan })
       const initialized = sessionEvents(agent.session).some(event => event.type === 'system/message')
       const message = planMessage(snapshot, id, force && initialized)
       agent.signal?.throwIfAborted?.()
@@ -1154,6 +1307,42 @@ export function createCapabilityEnvironment({ ctx, config, toolSchemasForAgent,
           member === agent ? status : member.status))
       }
     },
+    /**
+     * The saved, delivered and usable facts of one capability. A caller that
+     * only has "the save succeeded" must not report more than this returns.
+     */
+    describeCapabilityProof(agent, id) {
+      if (typeof id !== 'string' || id.length === 0) throw new TypeError('ptc-plus: capability proof requires a capability id')
+      const state = stateFor(agent)
+      const sourceSettings = state?.snapshot.sourceSettings ?? state?.snapshot.settings
+        ?? capabilityConfiguration(currentConfig)
+      // A global choice is recorded either as a legacy override or as a rule in the
+      // policy this owner writes for `/capabilities set global`, so both spellings
+      // prove the same save.
+      const capability = state?.snapshot.capabilities.find(item => item.id === id)
+      const recorded = capability === undefined || sourceSettings.policy === undefined
+        ? undefined : capabilityRule(sourceSettings.policy, capability)
+      const saved = Object.hasOwn(sourceSettings.manual?.overrides ?? {}, id)
+        || recorded?.availabilitySource === `item:${id}`
+        || recorded?.disclosureSource === `item:${id}`
+      // Delivery is a statement about the model-visible catalog. A plan that holds an
+      // entry whose choice is closed describes an entry the catalog does not list, so
+      // holding it proves nothing was delivered.
+      const entry = state?.snapshot.plan.entries.find(item => item.id === id)
+      const listed = entry !== undefined && entry.selection !== 'closed'
+      const delivery = !listed ? 'absent'
+        : state.message === undefined || planCommitted(agent, state.message) ? 'delivered' : 'pending'
+      return normalizeCapabilityProof({
+        schema: 'ptc-capability-proof/v1',
+        id,
+        saved,
+        delivery,
+        // Only a completed execution in this session proves usability; the
+        // worker's installed schemas and the published catalog prove nothing
+        // about what a cell actually obtained.
+        usability: state?.used?.has(id) === true ? 'proven' : 'unproven',
+      })
+    },
     describe(agent) {
       const state = stateFor(agent)
       return state === undefined ? { configured: capabilityConfiguration(currentConfig), effective: null }

package/internal/capability-plan.js

@@ -1,16 +1,12 @@
 import { capabilityRule, validateCapabilityPolicy, effectiveCapabilitySettings } from './capability-policy.js'
 import { Buffer } from 'node:buffer'
+import { PLAN_CATEGORY_LINES } from './prompt-text.js'
 
 const MANAGED_CATEGORIES = new Set(['tool', 'skill', 'resource', 'resource-template', 'task'])
 const EXCLUDED_CATEGORIES = new Set(['language', 'node', 'repl', 'ptc-plus', 'global-binding'])
 const SELECTIONS = new Set(['full', 'on-demand', 'closed'])
-const CATEGORY_NAVIGATION = new Map([
-  ['tool', 'Tools: search by task or tools.<name> for parameters and results.'],
-  ['skill', 'Skills: search by task or skills.<name> for when to use and how to load instructions.'],
-  ['resource', 'MCP resources: search by server or resource purpose.'],
-  ['resource-template', 'MCP templates: search by server or resource purpose.'],
-  ['task', 'Tasks: search by the operation you need.'],
-])
+/** Category guidance defaults; the registry owns the delivered literals. */
+const CATEGORY_NAVIGATION = new Map(Object.entries(PLAN_CATEGORY_LINES))
 
 function isRecord(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) }
 
@@ -121,6 +117,13 @@ function createLegacyCapabilityPlan(input) {
   const budgetBytes = integer(options.budgetBytes, 'contract budget bytes')
   const directoryBudgetBytes = integer(options.directoryBudgetBytes, 'directory budget bytes')
   const navigationText = text(options.navigationText, 'bounded discovery guidance')
+  const categoryNavigation = options.categories === undefined
+    ? CATEGORY_NAVIGATION
+    : new Map(options.categories.map(pair => {
+      if (!Array.isArray(pair) || pair.length !== 2) throw new TypeError('ptc-plus: capability categories must be [category, guidance] pairs')
+      const category = text(pair[0], `capability category ${pair[0]}`)
+      return [category, text(pair[1], `capability guidance for ${category}`)]
+    }))
   if (bytes(navigationText) > directoryBudgetBytes) throw new RangeError('ptc-plus: discovery guidance exceeds directory byte budget')
   const manual = record(options.manual ?? {}, 'manual capability settings')
   const overrides = record(manual.overrides ?? {}, 'capability overrides')
@@ -220,7 +223,7 @@ function createLegacyCapabilityPlan(input) {
   const directoryCategories = []
   const availableCategories = new Set(capabilities.filter(capability => selections.get(capability.id).selection !== 'closed')
     .map(capability => capability.category))
-  for (const [category, guidance] of CATEGORY_NAVIGATION) {
+  for (const [category, guidance] of categoryNavigation) {
     if (!availableCategories.has(category)) continue
     const proposed = `${directoryText}\n${guidance}`
     if (bytes(proposed) <= directoryBudgetBytes) {

package/internal/cell-error.js

@@ -5,3 +5,16 @@ export class ModuleRewriteError extends SyntaxError {
     if (cellPosition !== undefined) this.cellPosition = cellPosition
   }
 }
+
+/**
+ * The kernel refuses to admit a cell because a previous helper was not reclaimed.
+ *
+ * This is a fact about the kernel's own lifecycle, not about the recorded history
+ * or the submitted source, so consumers must not contract a frontier or blame a
+ * cell for it.
+ */
+export class CellAdmissionBlocked extends AggregateError {
+  constructor(failures) {
+    super(failures, 'previous computation helper reclamation failed; dispose the session before continuing')
+  }
+}