dsh-ptc-plus 0.5.2 → 0.5.3

package/internal/session-journal-recovery.js

@@ -9,6 +9,9 @@ import {
   RECOVERY_BOUNDARY_EVENT,
   DIAGNOSTIC_WORDING_KEY,
   DIAGNOSTIC_WORDING_FIELDS,
+  SETTLEMENT_PROOF_KEY,
+  SETTLEMENT_PROOF_FIELDS,
+  SETTLEMENT_PROOF_VERSION,
   LEGACY_JOURNAL_VERSION,
   REPL_TOOL_NAMES,
   REWRITES_KEY,
@@ -23,6 +26,7 @@ import {
   normalizeJournal,
   normalizeRecoveryBoundaries,
   reduceStateOperations,
+  settlementProofDigest,
   userBindingsForJournal,
   validatedRewrites,
 } from './session-journal.js'
@@ -104,14 +108,13 @@ function reachableFrom(nodes, head) {
 }
 
 /**
- * Binding names a node recorded.
+ * Binding names a settlement journal recorded.
  *
  * The recorded values are the only evidence that names a durable binding today;
  * `unrecordedBindings` names the ones the codec could not transfer, and a
  * `kind: "binding"` save names one explicitly. A checkpoint save never counts.
  */
-function recordedBindingNames(node) {
-  const journal = node?.journal
+function journalBindingNames(journal) {
   if (journal === undefined) return []
   return [...new Set([
     ...(journal.values ?? []).map(value => value.name),
@@ -120,6 +123,11 @@ function recordedBindingNames(node) {
   ].filter(name => typeof name === 'string'))]
 }
 
+/** Binding names an installed node recorded. */
+function recordedBindingNames(node) {
+  return journalBindingNames(node?.journal)
+}
+
 function applyOperations(state, operations, nodeIndex) {
   const previousHead = state.head
   const transition = reduceStateOperations(state, operations, nodeIndex)
@@ -145,6 +153,117 @@ function applyOperations(state, operations, nodeIndex) {
   }
 }
 
+/**
+ * Adopt the relation a record states about the cell it revised.
+ *
+ * The relation belongs to the fold, because only the fold knows the path that
+ * builds the environment. An accepted edit claims the revision *replaces* the cell
+ * it edited, so the revision takes that cell's place in the recorded order: it
+ * continues from the target's parent and every cell that followed the target
+ * continues from the revision. Appending the revision after those cells instead
+ * leaves them replaying an environment the edit already rewrote, with the
+ * declarations they read gone and the revision not yet in place.
+ *
+ * `installed` says whether this settlement puts a cell on the path. A contracted
+ * revision installs nothing, so the cells that followed the target bridge to the
+ * target's parent, and only a head that was the target itself has to move.
+ *
+ * The returned record of what changed is what lets a rejected settlement put the
+ * path back: nothing this adoption did survives a settlement the fold refuses.
+ */
+function adoptSupersession(state, record, { installed }) {
+  const superseded = state.editRewritesHistory && record.supersedes !== undefined
+    ? state.nodes.findIndex(node => node.callSeq === record.supersedes) : -1
+  const adoption = {
+    superseded,
+    previousHead: state.head,
+    supersededBindings: new Set(state.supersededBindings),
+    supersessions: state.supersessions.length,
+    children: [],
+    parent: state.head,
+    head: undefined,
+  }
+  if (superseded < 0) {
+    // No relation: the settlement appends to the head, as it always has.
+    adoption.head = installed ? undefined : state.head
+    return adoption
+  }
+  const parent = state.nodes[superseded].parent
+  adoption.parent = parent
+  for (let child = 0; child < state.nodes.length; child += 1) {
+    if (state.nodes[child].parent === superseded) adoption.children.push(child)
+  }
+  // The head is the last recorded cell. It keeps its place when the target is on
+  // its path behind other cells, because those cells now reach the same head
+  // through the revision; otherwise the revision is the newest cell and the head.
+  const targetOnPath = reachableFrom(state.nodes, state.head).has(superseded)
+  if (installed) adoption.head = targetOnPath && state.head !== superseded ? state.head : undefined
+  else adoption.head = state.head === superseded ? parent : state.head
+  return adoption
+}
+
+/**
+ * Record the relation as the fact the model is owed.
+ *
+ * Only names the record proves count. A durable declaration that the replay
+ * re-establishes is not evidence about the superseded cell, and claiming it
+ * would report a binding this fold cannot see. What the revision supplies is the
+ * caller's answer, because a settlement the fold refused to install supplies
+ * nothing; a cell the fold installs supplies the names its journal recorded.
+ */
+function recordSupersession(state, record, adoption, suppliedNames) {
+  if (adoption.superseded < 0) return
+  const supplied = new Set(suppliedNames)
+  for (const name of recordedBindingNames(state.nodes[adoption.superseded])) {
+    if (!supplied.has(name)) state.supersededBindings.add(name)
+  }
+  state.supersessions.push(Object.freeze({
+    supersededCallSeq: record.supersedes,
+    supersedingCallSeq: record.call.seq,
+  }))
+}
+
+/**
+ * Fold one accepted record as a settlement of the recorded path.
+ *
+ * `installed` is false for a settlement the fold contracts: it puts no cell on the
+ * path and supplies no name, while the relation it states is still the log's fact.
+ * Either way the relation is adopted first and the state operations are applied
+ * last, so a settlement that throws leaves the path, the children it re-parented
+ * and the relation it recorded exactly as it found them.
+ */
+function applyAdoptedRecord(state, record, { journal, installed = true, restoredFromRecord = false }) {
+  const adoption = adoptSupersession(state, record, { installed })
+  const index = installed
+    ? state.nodes.push(Object.freeze({
+      code: record.code,
+      journal,
+      callSeq: record.call.seq,
+      parent: adoption.parent,
+      ...(restoredFromRecord ? { restoredFromRecord: true } : {}),
+      ...(record.result.userBindings === undefined ? {} : { userBindings: record.result.userBindings }),
+    })) - 1
+    : undefined
+  const inherited = installed ? index : adoption.parent
+  for (const child of adoption.children) {
+    state.nodes[child] = Object.freeze({ ...state.nodes[child], parent: inherited })
+  }
+  state.head = adoption.head === undefined ? index : adoption.head
+  try {
+    recordSupersession(state, record, adoption, installed ? journalBindingNames(journal) : [])
+    applyOperations(state, journal.operations, index)
+  } catch (error) {
+    if (index !== undefined) state.nodes.pop()
+    state.head = adoption.previousHead
+    for (const child of adoption.children) {
+      state.nodes[child] = Object.freeze({ ...state.nodes[child], parent: adoption.superseded })
+    }
+    state.supersededBindings = adoption.supersededBindings
+    state.supersessions.length = adoption.supersessions
+    throw error
+  }
+}
+
 /**
  * Binding names a recorded journal operation list saves.
  *
@@ -212,17 +331,10 @@ function applyRecord(state, record, invalidCallSeqs) {
     // the owner that read `Date.now()` or `process.pid` is gone, and the next
     // environment inherits the durable computation, not the live cache.
     if (!state.liveOnlyLost && journal.values !== undefined && journal.values.length > 0) {
-      const node = Object.freeze({
-        code,
-        journal,
-        callSeq: call.seq,
-        parent: state.head,
-        restoredFromRecord: true,
-        ...(result.userBindings === undefined ? {} : { userBindings: result.userBindings }),
-      })
-      const index = state.nodes.push(node) - 1
-      state.head = index
-      applyOperations(state, journal.operations, index)
+      // The relation is adopted for this settlement too: an accepted revision that
+      // settled volatile is still the revision the record names, so it replaces its
+      // target on the path and installs its own recorded values.
+      applyAdoptedRecord(state, record, { journal, restoredFromRecord: true })
       return
     }
     // A released live environment is reported as a contracted cell: the model
@@ -236,29 +348,22 @@ function applyRecord(state, record, invalidCallSeqs) {
         : journal.volatileReason ?? 'volatile cell',
       ...(volatileBindings.length === 0 || state.liveOnlyLost === true ? {} : { bindings: volatileBindings }),
     })
-    applyOperations(state, journal.operations, undefined)
+    // A contracted revision still replaces the cell it edited. Leaving the target
+    // on the path would keep building an environment the accepted edit already
+    // ended, and the relation is what tells the model those names are withdrawn
+    // rather than lost. The settlement installs nothing, so it supplies no name:
+    // every name the target recorded is withdrawn by this record.
+    applyAdoptedRecord(state, record, { journal, installed: false })
     return
   }
   if (!state.trusted && !state.surfaceContracted) {
     state.trusted = true
     state.volatileSuffix.length = 0
   }
-  const node = Object.freeze({
-    code,
-    journal,
-    callSeq: call.seq,
-    parent: state.head,
-    ...(result.userBindings === undefined ? {} : { userBindings: result.userBindings }),
-  })
-  const index = state.nodes.push(node) - 1
-  state.head = index
-  try {
-    applyOperations(state, journal.operations, index)
-  } catch (error) {
-    state.nodes.pop()
-    state.head = node.parent
-    throw error
-  }
+  // A record may declare that it is the revision of an earlier cell. Adoption of
+  // that relation, its re-parented children and the node this record puts on the
+  // path are one settlement: a record the fold refuses leaves none of them behind.
+  applyAdoptedRecord(state, record, { journal })
 }
 
 function recordEventSeq(record) {
@@ -277,9 +382,15 @@ function foldRecords(records, invalidCallSeqs, options = {}) {
     volatileSuffix: [],
     provenBindings: new Set(),
     deletedBindings: new Set(),
+    // One recorded revision replaced the cell it edited. The relation, not a
+    // deletion, is what the log proves: the superseded cell stays in the record
+    // and off the path to the head.
+    supersessions: [],
+    supersededBindings: new Set(),
     trusted: true,
     surfaceContracted: options.surfaceContracted === true,
     liveOnlyLost: options.liveOnlyLost === true,
+    editRewritesHistory: options.editRewritesHistory === true,
   }
   for (const record of records) {
     applyRecord(state, record, invalidCallSeqs)
@@ -1459,6 +1570,12 @@ function normalizePostEditFact(facts, call, resultEvent, result, replayPostEdit,
   let derived
   try {
     derived = normalizeDeferredEditSettlement(post.meta, target?.callSeq)
+    // The derived metadata is a published settlement of its own, so it carries the
+    // same proof the root journal does. Comparing the two recorded journal copies
+    // proves only that they agree with each other; an edit that changed both and
+    // left this proof behind no longer reproduces the settlement it published, and
+    // its journal is then not evidence for the bindings the revision declares.
+    requireRecordedSettlementProof(post.meta, derived.journal)
   } catch (error) {
     return fail(error.message)
   }
@@ -1517,6 +1634,40 @@ function requireRecordedDiagnosticWording(meta, journal) {
   }
 }
 
+/**
+ * A published settlement proves its own facts, and the Host's copy of its outcome
+ * must still agree with them.
+ *
+ * Recovery reads a record as evidence for the bindings its cell declared, and the
+ * record is the only account of its cell: editing the status, the completion or a
+ * diagnostic leaves the record self-consistent, because the completion is rendered
+ * from the same diagnostic that was edited. The proof recorded at publication is
+ * one digest over exactly those facts, so an edited record no longer reproduces it.
+ * A record that carries no proof predates it and keeps the older evidence.
+ *
+ * The retained `isError` is the Host's copy of the same outcome and not a fact this
+ * plugin can recompute, so an edit that also rewrites the proof still has to agree
+ * with it. That relation is the one a deferred edit already proves before it is
+ * published.
+ */
+function requireRecordedSettlementProof(meta, journal, isError = undefined) {
+  if (isError !== undefined && isError !== (journal.status === 'discarded'
+    || journal.completion?.kind === 'throw')) {
+    throw new Error('journal settlement does not agree with the tool result it settled')
+  }
+  if (!isRecord(meta) || !Object.hasOwn(meta, SETTLEMENT_PROOF_KEY)) return
+  const recorded = meta[SETTLEMENT_PROOF_KEY]
+  if (!isRecord(recorded) || Reflect.ownKeys(recorded).length !== SETTLEMENT_PROOF_FIELDS.size
+    || Reflect.ownKeys(recorded).some(key => !SETTLEMENT_PROOF_FIELDS.has(key))
+    || recorded.version !== SETTLEMENT_PROOF_VERSION
+    || typeof recorded.recordedMessage !== 'string') {
+    throw new Error('invalid recorded settlement proof')
+  }
+  if (recorded.recordedMessage !== settlementProofDigest(journal)) {
+    throw new Error('journal facts do not match their recorded settlement proof')
+  }
+}
+
 function advanceTimelineEvent(previous, inputEvent, eventIndex, replayFact, retainedCalls) {
   const nested = inputEvent?.type === 'tool/ptc-dispatch-start'
     || inputEvent?.type === 'tool/ptc-dispatch'
@@ -1767,6 +1918,7 @@ function advanceTimelineEvent(previous, inputEvent, eventIndex, replayFact, reta
               ...(derived.userBindings === undefined ? {} : { userBindings: derived.userBindings }),
             }
             requireRecordedDiagnosticWording(meta, derived.journal)
+            requireRecordedSettlementProof(meta, derived.journal)
           } else if (call.data.name === 'run_code') {
             const rawJournal = meta[JOURNAL_KEY]
             const resolveLegacyConfirm = rawJournal?.version === LEGACY_JOURNAL_VERSION
@@ -1800,6 +1952,15 @@ function advanceTimelineEvent(previous, inputEvent, eventIndex, replayFact, reta
               ...(userBindings === undefined ? {} : { userBindings }),
             }
             requireRecordedDiagnosticWording(meta, journal)
+            // The Host states the outcome of the cell it settled; a record whose
+            // completion or status contradicts it was edited after publication. The
+            // Host records that outcome on the result message it appends, so the
+            // message is read first; a log that carries it on the event instead is
+            // read the same way.
+            const hostIsError = typeof event.data?.message?.isError === 'boolean'
+              ? event.data.message.isError
+              : typeof event.data?.isError === 'boolean' ? event.data.isError : undefined
+            requireRecordedSettlementProof(meta, journal, hostIsError)
             let postEdit
             try {
               postEdit = normalizePostEditFact(state.eventFacts, call, event, normalized, undefined, state.executableCalls)
@@ -2299,7 +2460,8 @@ export function recoverJournal(session, currentCallSeq, options = {}) {
   // A live environment that was released cannot lend its recorded live-only
   // values to the environment that replaces it. The flag belongs to the fold, so
   // every re-fold below carries it.
-  const foldOptions = { liveOnlyLost: options?.liveOnlyLost === true }
+  const foldOptions = { liveOnlyLost: options?.liveOnlyLost === true,
+    editRewritesHistory: options?.editRewritesHistory === true }
   let state = foldRecords(records, invalidCallSeqs, foldOptions)
   let boundaryIndex = 0
   const carrierCallSeqForBoundary = boundary => boundary.carrierCallSeq
@@ -2415,6 +2577,9 @@ export function recoverJournal(session, currentCallSeq, options = {}) {
           code: postEdit.derived.code,
           result: { eventSeq: result.eventSeq, journal: postEdit.derived.journal,
             derived: postEdit.derived, userBindings: postEdit.derived.userBindings },
+          // The revision names the cell it edits. Whether that relation replaces
+          // the target or appends to it is the fold's decision, not the log's.
+          supersedes: postEdit.targetCallSeq,
           hidden: visibleCalls instanceof Set && (!visibleCalls.has(call.seq)
             || !visibleCalls.has(postEdit.targetCallSeq)),
         })
@@ -2482,6 +2647,19 @@ export function recoverJournal(session, currentCallSeq, options = {}) {
     enumerable: false,
     configurable: true,
   })
+  // The supersession relation is recovery evidence of the same kind: which cell
+  // each revision replaced, and which proved names the path no longer supplies
+  // because of it. Both stay off the enumerable shape for the same reason.
+  Object.defineProperty(history, 'supersessions', {
+    value: [...state.supersessions],
+    enumerable: false,
+    configurable: true,
+  })
+  Object.defineProperty(history, 'supersededBindings', {
+    value: [...state.supersededBindings],
+    enumerable: false,
+    configurable: true,
+  })
   return history
 }
 

package/internal/session-journal-schema.js

@@ -12,6 +12,7 @@ export const POST_EDIT_KEY = 'dshPtcPlusPostEdit'
 export const REWRITES_KEY = 'dshPtcPlusRewrites'
 export const RECOVERY_BOUNDARY_KEY = 'dshPtcPlusRecoveryBoundaries'
 export const DIAGNOSTIC_WORDING_KEY = 'dshPtcPlusDiagnosticWording'
+export const SETTLEMENT_PROOF_KEY = 'dshPtcPlusSettlementProof'
 export const IMPORT_BOUNDARY_JOURNAL_VERSION = 7
 export const PER_NAME_USER_BINDINGS_JOURNAL_VERSION = 8
 export const LANGUAGE_SEMANTICS_JOURNAL_VERSION = 9
@@ -62,6 +63,8 @@ export const ERROR_FIELDS = new Set(['kind', 'message'])
 export const EDIT_TARGET_FIELDS = new Set(['targetCallSeq'])
 export const DERIVED_RUN_FIELDS = new Set(['code', 'codeDigest', 'codeBytes', 'description'])
 export const DIAGNOSTIC_WORDING_FIELDS = new Set(['digest'])
+export const SETTLEMENT_PROOF_VERSION = 1
+export const SETTLEMENT_PROOF_FIELDS = new Set(['version', 'recordedMessage'])
 
 export const JOURNAL_VERSIONS = new Set([LEGACY_JOURNAL_VERSION, INTERMEDIATE_JOURNAL_VERSION, PREVIOUS_JOURNAL_VERSION, USER_BINDING_RELATIONLESS_JOURNAL_VERSION, FINGERPRINT_REUSE_JOURNAL_VERSION, VERSIONED_BINDING_REUSE_JOURNAL_VERSION, IMPORT_BOUNDARY_JOURNAL_VERSION, PER_NAME_USER_BINDINGS_JOURNAL_VERSION, LANGUAGE_SEMANTICS_JOURNAL_VERSION, MODULE_TRANSFORM_JOURNAL_VERSION, JOURNAL_VERSION])
 export const USER_BINDINGS_REUSE_POLICIES = new Set([LEGACY_USER_BINDINGS_REUSE_POLICY, LIVE_USER_BINDINGS_REUSE_POLICY])

package/internal/session-journal.js

@@ -64,6 +64,9 @@ import {
   USER_BINDINGS_REUSE_POLICIES,
   RECOVERY_BOUNDARY_FIELDS,
   DIAGNOSTIC_WORDING_KEY,
+  SETTLEMENT_PROOF_KEY,
+  SETTLEMENT_PROOF_FIELDS,
+  SETTLEMENT_PROOF_VERSION,
   REPL_TOOL_NAMES,
   REWRITE_FIELDS,
   REWRITE_KINDS,
@@ -78,6 +81,9 @@ export {
   RECOVERY_BOUNDARY_KEY,
   DIAGNOSTIC_WORDING_KEY,
   DIAGNOSTIC_WORDING_FIELDS,
+  SETTLEMENT_PROOF_KEY,
+  SETTLEMENT_PROOF_FIELDS,
+  SETTLEMENT_PROOF_VERSION,
   JOURNAL_VERSION,
   LIVE_USER_BINDINGS_REUSE_POLICY,
   RECOVERY_BOUNDARY_EVENT,
@@ -129,15 +135,46 @@ export function diagnosticWordingDigest(journal) {
   return digestOf(diagnostics.map(diagnosticWordingFacts))
 }
 
-/** Attach the recorded wording digest beside a journal, or drop a stale one. */
-export function withDiagnosticWording(meta, journal) {
-  const digest = diagnosticWordingDigest(journal)
-  if (digest === undefined) {
-    if (!Object.hasOwn(meta, DIAGNOSTIC_WORDING_KEY)) return meta
-    const { [DIAGNOSTIC_WORDING_KEY]: _omitted, ...rest } = meta
-    return rest
+/**
+ * Digest of the one settlement a journal states: the status of its cell, its
+ * completion, and the wording of its diagnostics.
+ *
+ * A published record is the only account of its own cell, so a record edited
+ * afterwards stays self-consistent: the completion is checkable against a
+ * diagnostic, and the diagnostic against the wording digest, but all three are
+ * the same settlement. The proof is taken at publication, from the facts the
+ * settlement was published with, and every fact is represented here exactly once,
+ * so a record whose status, completion or diagnostic wording changed no longer
+ * reproduces it.
+ */
+export function settlementProofDigest(journal) {
+  const completion = journal?.completion
+  const completionFacts = completion === undefined ? null
+    : completion.kind === 'return'
+      ? [completion.kind, completion.hasValue,
+        completion.hasValue ? digestOf(completion.value) : null]
+      : [completion.kind, completion.error.kind, completion.error.message]
+  return digestOf([
+    journal?.status ?? null,
+    completionFacts,
+    diagnosticWordingDigest(journal) ?? null,
+  ])
+}
+
+/**
+ * Attach the published settlement's proof beside a journal.
+ *
+ * Every settlement states a status, so every publication carries one; a record
+ * that carries none predates this proof and keeps the older evidence.
+ */
+export function withSettlementProof(meta, journal) {
+  return {
+    ...meta,
+    [SETTLEMENT_PROOF_KEY]: {
+      version: SETTLEMENT_PROOF_VERSION,
+      recordedMessage: settlementProofDigest(journal),
+    },
   }
-  return { ...meta, [DIAGNOSTIC_WORDING_KEY]: { digest } }
 }
 
 function cloneJson(value) {
@@ -1272,7 +1309,7 @@ export function withJournal(meta, journal) {
   const base = isRecord(meta) ? { ...meta } : meta === undefined ? {} : { value: cloneJson(meta) }
   const normalized = normalizeJournal(journal)
   base[JOURNAL_KEY] = normalized
-  return withDiagnosticWording(base, normalized)
+  return withSettlementProof(base, normalized)
 }
 
 /** Validate and detach one rewrite record emitted by the runtime. */

package/internal/session-log-view.js

@@ -249,6 +249,24 @@ export function createSessionLogProjection(options = {}) {
   })
 }
 
+/**
+ * The disposer a session projection registration handed back.
+ *
+ * Two registration contracts are published: an earlier host returns a disposer and a
+ * newer one returns a `ProjectionHandle` (`stateOf`/`readerFor`/`dispose`, possibly
+ * async). Every projection this plugin registers goes through this reader, because a
+ * registration that only understands the earlier shape drops the projection — and
+ * with it the fact that the host accepted it — on the newer contract.
+ * @param {unknown} registration - what `sessionProjections.register` returned.
+ * @returns {(() => unknown)|undefined} the release call, or undefined when the answer
+ *   names neither contract.
+ */
+export function projectionRegistrationDisposer(registration) {
+  if (typeof registration === 'function') return () => registration()
+  if (typeof registration?.dispose === 'function') return () => registration.dispose()
+  return undefined
+}
+
 export function createSessionLogOwner(ctx) {
   const projection = createSessionLogProjection()
   let registeredService
@@ -256,8 +274,10 @@ export function createSessionLogOwner(ctx) {
     try {
       scope.effect(() => {
         const registry = scope.sessionProjections
-        const unregister = registry.register(projection)
-        if (typeof unregister !== 'function') throw new Error('ptc-plus: sessionProjections.register did not return a disposer')
+        const unregister = projectionRegistrationDisposer(registry.register(projection))
+        if (unregister === undefined) {
+          throw new Error('ptc-plus: sessionProjections.register returned neither a disposer nor a handle')
+        }
         registeredService = registry
         return async () => {
           await unregister()