dsh-ptc-plus 0.5.3 → 0.5.4

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 }),
+  }
 }