dsh-ptc-plus 0.3.1 → 0.4.1

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,201 +1,2 @@
-import { bindingNodes, createGeneratedNameAllocator } from './binding-pattern.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),
-  }))
-}
-
-export function rewriteLooseRedeclarations({
-  code,
-  sourceMap = identitySourceMap(code.length),
-  body,
-  offset,
-  knownBindings,
-  declarations,
-  declarationSpan,
-  collisionFor,
-  autoSplitRedeclarations,
-}) {
-  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)) {
-        rejected.push({ name: statement.id.name, span: declarationSpan(statement.id) })
-      }
-      continue
-    }
-    const entries = []
-    let statementRejected = false
-    for (const declarator of statement.declarations) {
-      const bindings = bindingEntries(declarator.id, declarationSpan)
-      const existing = bindings.filter(binding => knownBindings.has(binding.name))
-      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') {
-        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: knownBindings.has(binding.name) })),
-          code,
-          offset,
-          allocateName,
-        ))
-        redeclared.push(...existing.map(collisionFor))
-        rewrites.push({
-          kind: 'redeclaration',
-          description: 'split a mixed top-level declaration while preserving native pattern initialization',
-          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),
     }),

package/internal/repl-observation-interest.js

@@ -0,0 +1,70 @@
+import { RPC_CONTRACTS } from './rpc-contract.js'
+
+export const REPL_OBSERVATION_RPC_CONTRACT = RPC_CONTRACTS.repl
+
+/** A visible Client holds a cancellable request; it never requests evaluation. */
+export function createReplObservationInterest(ctx, initiallyEnabled, observe = async () => undefined) {
+  let enabled = initiallyEnabled
+  const watchers = new Set()
+  const inspections = new Set()
+  const registrations = new Set()
+  const clear = () => {
+    for (const watcher of [...watchers]) watcher.release()
+    for (const controller of inspections) controller.abort()
+  }
+  const handler = async (endpoint, payload, signal) => {
+    if (!enabled || !['watch', 'observe'].includes(endpoint) || typeof payload?.sessionId !== 'string'
+      || payload.sessionId.length === 0 || payload.sessionId.length > 256
+      || signal === undefined || (endpoint === 'watch' && watchers.size >= 64)) return { ok: false, error: {
+      code: 'repl/watch-unavailable', message: 'REPL observation unavailable', details: {},
+    } }
+    if (endpoint === 'observe') {
+      if (inspections.size >= 64) return { ok: true, value: null }
+      const controller = new AbortController()
+      inspections.add(controller)
+      try {
+        const value = await observe(payload.sessionId, payload.memory, AbortSignal.any([signal, controller.signal]))
+        return { ok: true, value: value ?? null }
+      } catch {
+        return { ok: false, error: { code: 'repl/observation-unavailable', message: 'REPL observation unavailable', details: {} } }
+      } finally {
+        inspections.delete(controller)
+      }
+    }
+    return new Promise(resolve => {
+      const watcher = { sessionId: payload.sessionId, release() {
+        signal.removeEventListener('abort', watcher.release)
+        watchers.delete(watcher)
+        resolve({ ok: true, value: null })
+      } }
+      watchers.add(watcher)
+      signal.addEventListener('abort', watcher.release, { once: true })
+      if (signal.aborted) watcher.release()
+    })
+  }
+  const injection = ctx.inject?.(['ptcPlusRpc'], scope => {
+    if (typeof scope.ptcPlusRpc?.register !== 'function') return
+    const owner = typeof scope.effect === 'function' ? scope : ctx
+    owner.effect(() => {
+      const unregister = scope.ptcPlusRpc.register(REPL_OBSERVATION_RPC_CONTRACT, handler)
+      const release = async () => {
+        if (!registrations.delete(release)) return
+        clear()
+        await unregister()
+      }
+      registrations.add(release)
+      return release
+    }, 'ptc-plus: visible REPL observation')
+  })
+  return {
+    has(sessionId) { return enabled && [...watchers].some(watcher => watcher.sessionId === sessionId) },
+    reconfigure(value) { enabled = value; if (!enabled) clear() },
+    async dispose() {
+      enabled = false
+      clear()
+      for (const release of [...registrations]) await release()
+      if (typeof injection === 'function') await injection()
+      else await injection?.dispose?.()
+    },
+  }
+}

package/internal/repl-rewrite-contract.js

@@ -0,0 +1,21 @@
+export const MIXED_REDECLARATION_REWRITE =
+  'split a mixed top-level declaration while preserving native pattern initialization'
+
+export const FUNCTION_REDECLARATION_REWRITE =
+  'reassigned an existing top-level function declaration for REPL continuity'
+
+export const CLASS_REDECLARATION_REWRITE =
+  'reassigned an existing top-level class declaration for REPL continuity'
+
+export const LEGACY_DEFAULT_EXPORT_BINDING = 'legacy-variable'
+export const LIVE_DEFAULT_EXPORT_BINDING = 'live-readonly'
+export const LEGACY_IMPORT_EXPRESSION_BOUNDARY = 'legacy'
+export const LIVE_IMPORT_EXPRESSION_BOUNDARY = 'statement-safe'
+export const LIVE_MODULE_SEMANTICS = Object.freeze({
+  defaultExportBinding: LIVE_DEFAULT_EXPORT_BINDING,
+  importExpressionBoundary: LIVE_IMPORT_EXPRESSION_BOUNDARY,
+})
+
+export function redeclarationCommitTarget(name, statementStart) {
+  return `redeclaration:${statementStart}:${name}`
+}