dsh-ptc-plus 0.3.2 → 0.4.2

package/internal/recovery-tips.js

@@ -1,3 +1,5 @@
+import { recoveryTipIdentity } from './runtime-messages.js'
+
 const PLATFORM_CAUSE_CODES = new Set(['EACCES', 'EINVAL', 'ENOTDIR', 'ENOENT', 'UNKNOWN'])
 const TIP_CONTEXT_PREFIX = 'tools:ptc-plus-tip/'
 const TIP_PREFIXES = Object.freeze({
@@ -10,16 +12,20 @@ function tipHistory(view) {
   const active = new Map()
   const seen = new Set()
   const history = []
-  for (const snapshot of view.systemPromptSnapshots) {
+  const snapshots = [
+    ...view.systemPromptSnapshots,
+    ...(view.ptcMessages ?? []).filter(record => record.form === 'notice').map(record => ({
+      ...record, sections: [{ name: record.name, text: record.text }],
+    })),
+  ].sort((left, right) => left.index - right.index)
+  for (const snapshot of snapshots) {
     const next = new Map(snapshot.sections.map(section => [section.name, section.text]))
     for (const [name] of next) {
       if (active.has(name) || seen.has(name)) continue
-      const match = /^tools:ptc-plus-tip\/(repeated-binding-failure|platform-command-failure)\/([1-9][0-9]*)$/.exec(name)
-      if (match === null) continue
-      const ordinal = Number(match[2])
-      if (!Number.isSafeInteger(ordinal)) continue
+      const identity = recoveryTipIdentity(name)
+      if (identity === undefined) continue
       seen.add(name)
-      history.push({ id: match[1], ordinal, index: snapshot.index, contextStep: snapshot.contextStep })
+      history.push({ ...identity, index: snapshot.index, contextStep: snapshot.contextStep })
     }
     active.clear()
     for (const entry of next) active.set(...entry)
@@ -36,7 +42,7 @@ function hasPlatformCommandDiagnostic(diagnostics) {
     const causeCode = typeof diagnostic.cause?.code === 'string' ? diagnostic.cause.code.toUpperCase() : undefined
     if (causeCode !== undefined && PLATFORM_CAUSE_CODES.has(causeCode)
       && /\b(?:spawn|exec(?:ute)?|command|executable|shell|path|file)\b/i.test(text)) return true
-    return /(?:spawn|exec(?:ute)?|child process)\b.*(?:failed|error|not found|cannot find)/i.test(text)
+    return /\b(?:spawn|exec(?:ute)?|child process)\b.*\b(?:ENOENT|ENOTDIR|EACCES|EINVAL)\b/i.test(text)
       || /command not found|no such file|not recognized as (?:an )?internal|cannot find (?:the )?(?:path|file)/i.test(text)
   })
 }
@@ -45,7 +51,10 @@ function tipCandidate(view) {
   const { args, journal } = view.latestRun ?? {}
   if (args === undefined || journal === undefined) return undefined
   const codes = new Set(journal.diagnostics.map(diagnostic => diagnostic.code))
-  if (codes.has('PTC-W001')) return { id: 'repeated-binding-failure' }
+  if (codes.has('PTC-W001')) return {
+    id: 'repeated-binding-failure',
+    capability: journal.diagnostics.some(item => item.code === 'PTC-W001' && item.cause?.code === 'PTC-CAPABILITY'),
+  }
   if (hasPlatformCommandDiagnostic(journal.diagnostics)) return { id: 'platform-command-failure' }
   return undefined
 }
@@ -56,6 +65,9 @@ function renderTip(id, detailed, candidate = {}) {
       ? `${TIP_PREFIXES[id]} Re-check the active execution world and the actual executable before retrying. Use direct argv for a normal executable; use a shell only when its syntax or resolution is required. Windows, WSL, POSIX, and package shims have different paths and launch rules.`
       : `${TIP_PREFIXES[id]} Inspect the executable or path in the current execution world and choose direct argv or a shell only when required; do not assume Windows, WSL, POSIX, or one shell.`
   }
+  if (!candidate.capability) {
+    return `${TIP_PREFIXES[id]} Inspect the visible cell source and results for the local name, scope, initialization, or declaration conflict. Correct that expression before continuing; capability discovery does not list session-local variables.${detailed ? ' Earlier statements may have run; use current expression evidence without assuming a failed declaration initialized its binding.' : ''}`
+  }
   return detailed
     ? `${TIP_PREFIXES[id]} Inspect the live request with \`capabilities.tree()\`, \`capabilities.find()\`, or \`capabilities.inspect()\`, then call the typed member through \`tools.*\`. Do not invent hidden bindings or repeat the same failing expression.`
     : `${TIP_PREFIXES[id]} Inspect the live request with \`capabilities.tree()\`, \`capabilities.find()\`, or \`capabilities.inspect()\`, then call the typed member through \`tools.*\`.`
@@ -65,14 +77,14 @@ export function latestRecoveryTip(view, config) {
   if (!config.enabled) return undefined
   const candidate = tipCandidate(view)
   if (candidate === undefined) return undefined
-  const history = tipHistory(view)
-  const lastTip = history.at(-1)
+  // Cooldown, escalation, and ordinal are per trigger kind: one kind's tip must
+  // not suppress a different kind.
+  const matching = tipHistory(view).filter(item => item.id === candidate.id)
+  const lastTip = matching.at(-1)
   if (lastTip !== undefined && view.contextStep - lastTip.contextStep < config.cooldownMessages) return undefined
-  const unresolved = history.filter(item => item.id === candidate.id && item.index > (view.lastSuccessfulRunIndex ?? -1))
-  const ordinal = history.reduce(
-    (highest, item) => item.id === candidate.id ? Math.max(highest, item.ordinal) : highest,
-    0,
-  ) + 1
+  const unresolved = matching.filter(item => item.index > (view.lastSuccessfulRunIndex ?? -1))
+  const ordinal = matching.reduce((highest, item) => Math.max(highest, item.ordinal), 0) + 1
+  if (!Number.isSafeInteger(ordinal)) return undefined
   return {
     name: `${TIP_CONTEXT_PREFIX}${candidate.id}/${ordinal}`,
     text: renderTip(candidate.id, unresolved.length >= config.escalationFailures, candidate),

package/internal/rejected-cell-editor.js

@@ -270,7 +270,7 @@ function editRunCodeParameterBranch(operation, operationSchema) {
 export function editRunCodeSchema() {
   return {
     name: 'edit_run_code',
-    description: 'Make a small exact or regular-expression change to the most recent eligible cell captured when this edit call is dispatched, then run the complete corrected cell. A successful edit becomes the next eligible cell. Use this only when replaying the whole cell is safe. If earlier code may already have caused an external effect, use a new run_code cell and its existing variables instead; this tool does not resume at the error location. Send exactly one atomic edits or regex_edits array, plus expected_target_call_seq only when a diagnostic supplies it to bind a validated repair to its rejected cell. Choose edits for a few unique literal fragments; choose regex_edits when one counted pattern covers repeated fragments. Every resolved range must be non-overlapping in the original cell.',
+    description: 'Edit the most recent eligible cell captured at dispatch and run the complete corrected cell. A successful edit becomes the next target. This reruns the entire cell, including prior effects; use it after pre-execution rejection or when repeating those effects is safe under the called API\'s retry rules. Otherwise continue in a new run_code cell using retained values. A diagnostic may supply a localized correction; use it when it matches your intent and preserve its expected_target_call_seq. Send exactly one edits or regex_edits array: edits replaces unique literal fragments; regex_edits replaces a counted set of pattern matches. All ranges must be non-overlapping in the original cell. Regex replacements use JavaScript $1/$<name> captures, not \\1.',
     parameters: {
       type: 'object',
       oneOf: [
@@ -288,13 +288,13 @@ export function editRunCodeSchema() {
         }),
         editRunCodeParameterBranch('regex_edits', {
           type: 'array', minItems: 1, maxItems: EDIT_LIMITS.regexEdits,
-          description: 'Atomic regular-expression replacements, all matched against the original target cell.',
+          description: 'Atomic regular-expression replacements, all matched against the original target cell with JavaScript pattern and replacement semantics; each replacement is a JavaScript template (see replacement).',
           items: {
             type: 'object', additionalProperties: false,
             properties: {
-              pattern: { type: 'string', minLength: 1, description: 'JavaScript regular-expression source. Zero-length matches are rejected.' },
+              pattern: { type: 'string', minLength: 1, description: 'JavaScript regular-expression source without delimiters or flags (for example \\d+px, not /\\d+px/). Zero-length matches are rejected.' },
               flags: { type: 'string', pattern: '^(?!.*(.).*\\1)[gimsu]*$', description: 'Unique JavaScript g, i, m, s, or u flags. Global matching is always applied.' },
-              replacement: { type: 'string', description: 'JavaScript replacement template, including capture references such as $1 or $<name>.' },
+              replacement: { type: 'string', description: 'JavaScript replacement template. Reference captures as $1, $2, ... or $<name> (for example "<$1>" inserts capture 1); backslash escapes such as \\1 are NOT capture references and stay literal text; write a literal dollar sign as $$.' },
               expected_matches: { type: 'integer', minimum: 1, maximum: EDIT_LIMITS.regexMatches, description: 'Exact match count required before any replacement is applied.' },
             },
             required: ['pattern', 'flags', 'replacement', 'expected_matches'],
@@ -310,11 +310,16 @@ export function editRejectedCell(value, source, timeoutMs = DEFAULT_REGEX_TIMEOU
     return rejection('edit_run_code expects an object with exactly one edits or regex_edits array')
   }
   const keys = Object.keys(value)
+  const unsupported = keys.find(key => !['edits', 'regex_edits', EXPECTED_TARGET_CALL_SEQ].includes(key))
+  if (unsupported !== undefined) {
+    return rejection(`edit_run_code does not accept field ${JSON.stringify(unsupported)}; remove it and retry the edit`)
+  }
   const operationKeys = keys.filter(key => key === 'edits' || key === 'regex_edits')
-  if (operationKeys.length !== 1 || keys.length > 2
-    || keys.some(key => !['edits', 'regex_edits', EXPECTED_TARGET_CALL_SEQ].includes(key))
-    || !Array.isArray(value[operationKeys[0]])) {
-    return rejection('edit_run_code expects exactly one edits or regex_edits array')
+  if (operationKeys.length !== 1) {
+    return rejection('edit_run_code expects exactly one of edits or regex_edits; supply one operation and omit the other')
+  }
+  if (!Array.isArray(value[operationKeys[0]])) {
+    return rejection(`edit_run_code ${operationKeys[0]} must be an array`)
   }
   if (Object.hasOwn(value, EXPECTED_TARGET_CALL_SEQ)
     && (!Number.isSafeInteger(value[EXPECTED_TARGET_CALL_SEQ])

package/internal/repl-convenience.js

@@ -1,289 +1,2 @@
-import { bindingNodes, createGeneratedNameAllocator } from './binding-pattern.js'
-import {
-  CLASS_REDECLARATION_REWRITE,
-  FUNCTION_REDECLARATION_REWRITE,
-  MIXED_REDECLARATION_REWRITE,
-  redeclarationCommitTarget,
-} from './repl-rewrite-contract.js'
-import { applySourceEdits, createMappedTextBuilder, identitySourceMap } from './source-position-map.js'
-import { SKIP_AST_CHILDREN, walkAst } from './ast-traversal.js'
-
-/**
- * Optional compatibility policy for a persistent REPL. The cell language does
- * not own this policy: callers may replace it when persistence uses separate
- * lexical frames instead of one shared REPL environment.
- */
-
-function containsTopLevelAwait(node) {
-  let found = false
-  walkAst(node, current => {
-    if (current.type === 'AwaitExpression') found = true
-    if (current.type === 'FunctionDeclaration' || current.type === 'FunctionExpression'
-      || current.type === 'ArrowFunctionExpression') return SKIP_AST_CHILDREN
-  })
-  return found
-}
-
-function mixedDeclaratorText(statement, declarator, bindings, code, offset, allocateName) {
-  const fresh = bindings.filter(binding => !binding.existing)
-  const existing = bindings.filter(binding => binding.existing)
-  const valueName = allocateName('mixed_value')
-  const commitName = allocateName('mixed_commit')
-  const valuesName = allocateName('mixed_values')
-  const positions = new Map(bindings.map((binding, index) => [binding.name, index]))
-  const asynchronous = containsTopLevelAwait(declarator.id)
-  const builder = createMappedTextBuilder(code, offset)
-  const appendBindingName = binding => builder.appendMapped(binding.name, binding.start, binding.end)
-  builder.append(statement.kind === 'var' ? 'var [' : 'let [')
-  fresh.forEach((binding, index) => {
-    if (index > 0) builder.append(', ')
-    appendBindingName(binding)
-  })
-  builder.append(`] = ${asynchronous ? 'await ' : ''}(`)
-  builder.append(`(${asynchronous ? 'async ' : ''}(${valueName}, ${commitName}) => { ${statement.kind} `)
-  builder.appendSource(declarator.id.start, declarator.id.end)
-  builder.append(` = ${valueName}; return ${commitName}([`)
-  bindings.forEach((binding, index) => {
-    if (index > 0) builder.append(', ')
-    appendBindingName(binding)
-  })
-  builder.append(`]); })((`)
-  if (declarator.init === null) builder.append('undefined')
-  else builder.appendSource(declarator.init.start, declarator.init.end)
-  builder.append(`), (${valuesName}) => { `)
-  existing.forEach((binding, index) => {
-    if (index > 0) builder.append(' ')
-    appendBindingName(binding)
-    builder.append(` = ${valuesName}[${positions.get(binding.name)}];`)
-  })
-  builder.append(' return [')
-  fresh.forEach((binding, index) => {
-    if (index > 0) builder.append(', ')
-    builder.append(valuesName)
-    builder.append(`[${positions.get(binding.name)}]`)
-  })
-  builder.append(']; }) );')
-  return builder.result()
-}
-
-function existingDeclaratorText(declarator, code, offset) {
-  const builder = createMappedTextBuilder(code, offset)
-  builder.append(';(')
-  builder.appendSource(declarator.id.start, declarator.id.end)
-  builder.append(' = ')
-  if (declarator.init === null) builder.append('undefined')
-  else builder.appendSource(declarator.init.start, declarator.init.end)
-  builder.append(');')
-  return builder.result()
-}
-
-function freshDeclaratorText(statement, declarator, code, offset) {
-  const builder = createMappedTextBuilder(code, offset)
-  builder.append(statement.kind === 'var' ? 'var ' : 'let ')
-  builder.appendSource(declarator.start, declarator.end)
-  builder.append(';')
-  return builder.result()
-}
-
-function bindingEntries(pattern, declarationSpan) {
-  return bindingNodes(pattern).map(node => ({
-    name: node.name,
-    start: node.start,
-    end: node.end,
-    span: declarationSpan(node),
-  }))
-}
-
-function existingFunctionText(statement, code, offset) {
-  const builder = createMappedTextBuilder(code, offset)
-  builder.append(';(')
-  builder.appendMapped(statement.id.name, statement.id.start, statement.id.end)
-  builder.append(' = ')
-  builder.appendSource(statement.start, statement.id.start)
-  builder.appendSource(statement.id.end, statement.end)
-  builder.append(');')
-  return builder.result()
-}
-
-function existingClassText(statement, code, offset) {
-  const builder = createMappedTextBuilder(code, offset)
-  builder.append(';(')
-  builder.appendMapped(statement.id.name, statement.id.start, statement.id.end)
-  builder.append(' = ')
-  builder.appendSource(statement.start, statement.end)
-  builder.append(');')
-  return builder.result()
-}
-
-export function rewriteReplRedeclarations({
-  code,
-  sourceMap = identitySourceMap(code.length),
-  body,
-  offset,
-  knownBindings,
-  variableRedeclarationBindings = knownBindings,
-  writableBindings,
-  declarations,
-  declarationSpan,
-  collisionFor,
-  bindingPolicy,
-  autoSplitRedeclarations,
-  commitSignal,
-}) {
-  const redeclared = []
-  const rewrites = []
-  if (body === undefined) {
-    return {
-      executableCode: code,
-      executableSourceMap: sourceMap,
-      collisions: declarations.filter(declaration => knownBindings.has(declaration.name)).map(collisionFor),
-      redeclared,
-      rewrites,
-    }
-  }
-  const replacements = []
-  const rejected = []
-  const allocateName = createGeneratedNameAllocator(body)
-  for (const statement of body) {
-    if (statement.type !== 'VariableDeclaration') {
-      if ((statement.type === 'FunctionDeclaration' || statement.type === 'ClassDeclaration')
-        && statement.id !== null && knownBindings.has(statement.id.name)) {
-        const kind = statement.type === 'ClassDeclaration' ? 'class' : 'function'
-        if (!writableBindings.has(statement.id.name)) {
-          rejected.push({
-            name: statement.id.name,
-            kind,
-            reason: 'binding-not-writable',
-            span: declarationSpan(statement.id),
-          })
-        } else if (!bindingPolicy.functionClassRedeclarations) {
-          rejected.push({
-            name: statement.id.name,
-            kind,
-            reason: 'function-class-redeclarations-disabled',
-            span: declarationSpan(statement.id),
-          })
-        } else {
-          const commitDependency = redeclarationCommitTarget(statement.id.name, statement.start)
-          const replacement = kind === 'class'
-            ? existingClassText(statement, code, offset)
-            : existingFunctionText(statement, code, offset)
-          replacement.text += ` void 0; this[${JSON.stringify(commitSignal)}](${JSON.stringify(commitDependency)});`
-          replacements.push({
-            start: statement.start - offset,
-            end: statement.end - offset,
-            text: replacement.text,
-            mappings: replacement.mappings,
-          })
-          redeclared.push(collisionFor({
-            name: statement.id.name,
-            kind,
-            commitDependency,
-            span: declarationSpan(statement.id),
-          }))
-          rewrites.push({
-            kind: 'redeclaration',
-            description: kind === 'class'
-              ? CLASS_REDECLARATION_REWRITE
-              : FUNCTION_REDECLARATION_REWRITE,
-            source: statement.id.name,
-          })
-        }
-      }
-      continue
-    }
-    const entries = []
-    let statementRejected = false
-    for (const declarator of statement.declarations) {
-      const bindings = bindingEntries(declarator.id, declarationSpan)
-      const existing = bindings.filter(binding => variableRedeclarationBindings.has(binding.name))
-      const immutable = existing.filter(binding => !writableBindings.has(binding.name))
-      if (immutable.length > 0) {
-        rejected.push(...immutable.map(binding => ({
-          ...binding,
-          reason: 'binding-not-writable',
-        })))
-        statementRejected = true
-        continue
-      }
-      if (existing.length > 0 && !bindingPolicy.variableRedeclarations) {
-        rejected.push(...existing.map(binding => ({
-          ...binding,
-          reason: 'variable-redeclarations-disabled',
-        })))
-        statementRejected = true
-        continue
-      }
-      if (existing.length > 0 && existing.length < bindings.length) {
-        if (autoSplitRedeclarations) entries.push({ declarator, bindings, existing })
-        else {
-          rejected.push(...existing)
-          statementRejected = true
-        }
-        continue
-      }
-      entries.push({ declarator, bindings, existing })
-    }
-    if (statementRejected) continue
-    if (!entries.some(entry => entry.existing.length > 0)) {
-      if (statement.kind === 'const' && bindingPolicy.variableRedeclarations) {
-        replacements.push({
-          start: statement.start - offset,
-          end: statement.start - offset + statement.kind.length,
-          text: 'let',
-        })
-      }
-      continue
-    }
-    let replacementText = ''
-    const replacementMappings = []
-    const appendPart = (part) => {
-      if (replacementText.length > 0) replacementText += '\n'
-      const partOffset = replacementText.length
-      replacementText += part.text
-      part.mappings.forEach(mapping => replacementMappings.push({
-        ...mapping,
-        generatedStart: mapping.generatedStart + partOffset,
-        generatedEnd: mapping.generatedEnd + partOffset,
-      }))
-    }
-    for (const { declarator, bindings, existing } of entries) {
-      if (existing.length > 0 && existing.length < bindings.length) {
-        appendPart(mixedDeclaratorText(
-          statement,
-          declarator,
-          bindings.map(binding => ({ ...binding, existing: existing.includes(binding) })),
-          code,
-          offset,
-          allocateName,
-        ))
-        redeclared.push(...existing.map(collisionFor))
-        rewrites.push({
-          kind: 'redeclaration',
-          description: MIXED_REDECLARATION_REWRITE,
-          source: existing.map(binding => binding.name).join(', '),
-        })
-      } else if (existing.length === bindings.length && bindings.length > 0) {
-        redeclared.push(...existing.map(collisionFor))
-        appendPart(existingDeclaratorText(declarator, code, offset))
-      } else {
-        appendPart(freshDeclaratorText(statement, declarator, code, offset))
-      }
-    }
-    replacements.push({
-      start: statement.start - offset,
-      end: statement.end - offset,
-      text: replacementText,
-      mappings: replacementMappings,
-    })
-  }
-  const collisions = rejected.map(collisionFor)
-  let executableCode = code
-  let executableSourceMap = sourceMap
-  if (collisions.length === 0) {
-    const applied = applySourceEdits(code, sourceMap, replacements)
-    executableCode = applied.code
-    executableSourceMap = applied.sourceMap
-  }
-  return { executableCode, executableSourceMap, collisions, redeclared, rewrites }
-}
+/** Historical declaration adapter; new cells use logical binding identities. */
+export { rewriteReplRedeclarations } from './legacy-repl-convenience.js'

package/internal/repl-memory-projection.js

@@ -1,4 +1,5 @@
 import { isRecord } from './record-utils.js'
+import { REPL_TOOL_NAMES } from './session-journal-schema.js'
 
 export const REPL_MEMORY_KEY = 'ptcPlusRepl'
 export const REPL_MEMORY_META_KEY = 'dshPtcPlusBindings'
@@ -12,13 +13,22 @@ const MAX_PENDING_REPL_CALLS = 256
 const MAX_CALL_ID_LENGTH = 512
 const MAX_GENERATION_LENGTH = 128
 const SNAPSHOT_FIELDS = new Set(['available', 'entries', 'total', 'omitted'])
+const COUNTED_SNAPSHOT_FIELDS = new Set([...SNAPSHOT_FIELDS, 'reuseTotal'])
+const OBSERVED_SNAPSHOT_FIELDS = new Set([...SNAPSHOT_FIELDS, 'observation'])
+const OBSERVED_COUNTED_SNAPSHOT_FIELDS = new Set([...COUNTED_SNAPSHOT_FIELDS, 'observation'])
+const OBSERVATION_FIELDS = new Set(['at', 'entries'])
+const PREVIEW_FIELDS = new Set(['name', 'status', 'text', 'truncated'])
 const ENTRY_FIELDS = new Set(['name', 'kind', 'definition'])
+const COUNTED_ENTRY_FIELDS = new Set([...ENTRY_FIELDS, 'reuseCount'])
 const DEFINITION_FIELDS = new Set(['source', 'line', 'column'])
 const MEMORY_META_FIELDS = new Set(['version', 'generation', 'memory'])
 const PROJECTION_STATE_FIELDS = new Set(['generation', 'memory', 'pendingReplCalls'])
 const PENDING_CALL_FIELDS = new Set(['callId', 'seq'])
-const REPL_TOOL_NAMES = new Set(['run_code', 'edit_run_code'])
-const REPL_MEMORY_META_VERSION = 3
+const REPL_MEMORY_META_VERSION = 5
+
+function isReuseCount(value) {
+  return Number.isSafeInteger(value) && value >= 0
+}
 
 function exactFields(value, fields) {
   if (!isRecord(value)) return false
@@ -34,6 +44,7 @@ const EMPTY_REPL_MEMORY = Object.freeze({
   entries: Object.freeze([]),
   total: 0,
   omitted: 0,
+  reuseTotal: 0,
 })
 
 export function unavailableReplMemorySnapshot() {
@@ -59,20 +70,43 @@ function normalizeDefinition(value) {
 }
 
 function normalizeBinding(value) {
-  if (!exactFields(value, ENTRY_FIELDS) || typeof value.name !== 'string'
+  const counted = exactFields(value, COUNTED_ENTRY_FIELDS)
+  if ((!counted && !exactFields(value, ENTRY_FIELDS)) || typeof value.name !== 'string'
     || value.name.length === 0 || value.name.length > MAX_BINDING_NAME_LENGTH
-    || !BINDING_KINDS.has(value.kind)) {
+    || !BINDING_KINDS.has(value.kind)
+    || (counted && !isReuseCount(value.reuseCount))) {
     throw new Error('invalid dsh-ptc-plus REPL memory binding')
   }
   return Object.freeze({
     name: value.name,
     kind: value.kind,
     definition: normalizeDefinition(value.definition),
+    reuseCount: counted ? value.reuseCount : 0,
+  })
+}
+
+export function normalizeReplObservation(value) {
+  if (!exactFields(value, OBSERVATION_FIELDS) || !Number.isSafeInteger(value.at) || value.at < 0
+    || !Array.isArray(value.entries) || value.entries.length > MAX_BINDINGS) {
+    throw new Error('invalid dsh-ptc-plus REPL observation')
+  }
+  const names = new Set()
+  const entries = value.entries.map(entry => {
+    if (!exactFields(entry, PREVIEW_FIELDS) || typeof entry.name !== 'string'
+      || entry.name.length === 0 || entry.name.length > MAX_BINDING_NAME_LENGTH || names.has(entry.name)
+      || !['readable', 'unreadable'].includes(entry.status)
+      || typeof entry.text !== 'string' || entry.text.length > 512 || typeof entry.truncated !== 'boolean'
+      || (entry.status === 'unreadable' && (entry.text !== '' || entry.truncated))) {
+      throw new Error('invalid dsh-ptc-plus REPL value preview')
+    }
+    names.add(entry.name)
+    return Object.freeze({ ...entry })
   })
+  return Object.freeze({ at: value.at, entries: Object.freeze(entries) })
 }
 
-/** Produce bounded, value-independent presentation metadata from the live binding catalog. */
-export function createReplMemorySnapshot(bindings) {
+/** Source inventory and optional observation are UI-only; neither is recovery evidence. */
+export function createReplMemorySnapshot(bindings, observation = undefined) {
   const all = Array.isArray(bindings) ? bindings : []
   const candidates = []
   const names = new Set()
@@ -92,28 +126,45 @@ export function createReplMemorySnapshot(bindings) {
     entries.push(binding)
     sourceLength += binding.definition.source.length
   }
+  let observed
+  if (observation !== undefined) {
+    try {
+      const normalized = normalizeReplObservation(observation)
+      const visibleNames = new Set(entries.map(entry => entry.name))
+      observed = Object.freeze({ ...normalized, entries: Object.freeze(normalized.entries.filter(entry => visibleNames.has(entry.name))) })
+    } catch {}
+  }
   return Object.freeze({
     available: true,
     entries: Object.freeze(entries),
     total: candidates.length,
     omitted: candidates.length - entries.length,
+    // Counts survive the presentation truncation: this total covers every valid
+    // identity, including entries omitted from the bounded list.
+    reuseTotal: candidates.reduce((sum, entry) => sum + entry.reuseCount, 0),
+    ...(observed === undefined ? {} : { observation: observed }),
   })
 }
 
 /** Validate one complete session-projection value without accepting unknown fields. */
 export function normalizeReplMemorySnapshot(value) {
-  if (!exactFields(value, SNAPSHOT_FIELDS) || typeof value.available !== 'boolean'
+  const counted = exactFields(value, COUNTED_SNAPSHOT_FIELDS) || exactFields(value, OBSERVED_COUNTED_SNAPSHOT_FIELDS)
+  const legacy = exactFields(value, SNAPSHOT_FIELDS) || exactFields(value, OBSERVED_SNAPSHOT_FIELDS)
+  if ((!counted && !legacy) || typeof value.available !== 'boolean'
     || !Array.isArray(value.entries) || value.entries.length > MAX_BINDINGS
     || !Number.isSafeInteger(value.total) || value.total < 0
     || !Number.isSafeInteger(value.omitted) || value.omitted < 0
-    || value.total !== value.entries.length + value.omitted) {
+    || value.total !== value.entries.length + value.omitted
+    || counted && !isReuseCount(value.reuseTotal)) {
     throw new Error('invalid dsh-ptc-plus REPL memory snapshot')
   }
-  if (!value.available && (value.total !== 0 || value.entries.length !== 0)) {
+  const reuseTotal = counted ? value.reuseTotal : 0
+  if (!value.available && (value.total !== 0 || value.entries.length !== 0 || reuseTotal !== 0)) {
     throw new Error('unavailable dsh-ptc-plus REPL memory snapshot must be empty')
   }
   const names = new Set()
   let sourceLength = 0
+  let entryReuseTotal = 0
   const entries = value.entries.map((entry) => {
     const normalized = normalizeBinding(entry)
     if (names.has(normalized.name)) {
@@ -124,18 +175,36 @@ export function normalizeReplMemorySnapshot(value) {
       throw new Error('dsh-ptc-plus REPL binding definitions exceed the presentation budget')
     }
     names.add(normalized.name)
+    entryReuseTotal += normalized.reuseCount
     return normalized
   })
+  if (reuseTotal < entryReuseTotal) {
+    throw new Error('dsh-ptc-plus REPL reuse total is smaller than its entries')
+  }
+  const observation = value.observation === undefined ? undefined : normalizeReplObservation(value.observation)
+  if (observation !== undefined && (!value.available || observation.entries.some(entry => !names.has(entry.name)))) {
+    throw new Error('REPL observation requires a matching available inventory')
+  }
   return Object.freeze({
     available: value.available,
     entries: Object.freeze(entries),
     total: value.total,
     omitted: value.omitted,
+    reuseTotal,
+    ...(observation === undefined ? {} : { observation }),
   })
 }
 
+/** Reuse fields are version 5 additions; an older metadata version cannot own them. */
+function countedMemory(memory) {
+  return memory?.reuseTotal !== undefined
+    || Array.isArray(memory?.entries) && memory.entries.some(entry => entry?.reuseCount !== undefined)
+}
+
 function normalizeReplMemoryMetadata(value) {
-  if (!exactFields(value, MEMORY_META_FIELDS) || value.version !== REPL_MEMORY_META_VERSION) {
+  if (!exactFields(value, MEMORY_META_FIELDS) || ![3, 4, REPL_MEMORY_META_VERSION].includes(value.version)
+    || (value.version === 3 && value.memory?.observation !== undefined)
+    || (value.version < REPL_MEMORY_META_VERSION && countedMemory(value.memory))) {
     throw new Error('invalid dsh-ptc-plus REPL memory metadata')
   }
   return Object.freeze({
@@ -253,12 +322,12 @@ export function withReplMemorySnapshot(meta, snapshot, generation) {
   return base
 }
 
-/** Build the current runtime owner's value-independent session projection. */
+/** Build the current runtime owner's model-invisible session projection. */
 export function createReplMemoryProjection(generation) {
   const currentGeneration = normalizeGeneration(generation)
   return Object.freeze({
     key: REPL_MEMORY_KEY,
-    stateVersion: 3,
+    stateVersion: 5,
     stateSchema: Object.freeze({
       parse: value => normalizeProjectionState(value, currentGeneration),
     }),