dsh-ptc-plus 0.2.4 → 0.3.2

package/internal/rejected-cell-editor.js

@@ -252,15 +252,29 @@ function assemble(source, replacements) {
   return changed ? { code: chunks.join('') } : { error: 'edits must change at least one matched fragment' }
 }
 
+function editRunCodeParameterBranch(operation, operationSchema) {
+  return {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      [operation]: operationSchema,
+      [EXPECTED_TARGET_CALL_SEQ]: {
+        type: 'integer', minimum: 0,
+        description: 'Optional target precondition copied from a validated diagnostic. The edit is rejected if the captured cell has another call sequence.',
+      },
+    },
+    required: [operation],
+  }
+}
+
 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.',
     parameters: {
       type: 'object',
-      additionalProperties: false,
-      properties: {
-        edits: {
+      oneOf: [
+        editRunCodeParameterBranch('edits', {
           type: 'array', minItems: 1, maxItems: EDIT_LIMITS.exactEdits,
           description: 'Atomic exact replacements, all resolved against the original target cell.',
           items: {
@@ -271,8 +285,8 @@ export function editRunCodeSchema() {
             },
             required: ['old_string', 'new_string'],
           },
-        },
-        regex_edits: {
+        }),
+        editRunCodeParameterBranch('regex_edits', {
           type: 'array', minItems: 1, maxItems: EDIT_LIMITS.regexEdits,
           description: 'Atomic regular-expression replacements, all matched against the original target cell.',
           items: {
@@ -285,13 +299,8 @@ export function editRunCodeSchema() {
             },
             required: ['pattern', 'flags', 'replacement', 'expected_matches'],
           },
-        },
-        [EXPECTED_TARGET_CALL_SEQ]: {
-          type: 'integer', minimum: 0,
-          description: 'Optional target precondition copied from a validated diagnostic. The edit is rejected if the captured cell has another call sequence.',
-        },
-      },
-      oneOf: [{ required: ['edits'] }, { required: ['regex_edits'] }],
+        }),
+      ],
     },
   }
 }

package/internal/repl-convenience.js

@@ -1,4 +1,10 @@
 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'
 
@@ -88,16 +94,41 @@ function bindingEntries(pattern, declarationSpan) {
   }))
 }
 
-export function rewriteLooseRedeclarations({
+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 = []
@@ -117,7 +148,47 @@ export function rewriteLooseRedeclarations({
     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) })
+        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
     }
@@ -125,7 +196,24 @@ export function rewriteLooseRedeclarations({
     let statementRejected = false
     for (const declarator of statement.declarations) {
       const bindings = bindingEntries(declarator.id, declarationSpan)
-      const existing = bindings.filter(binding => knownBindings.has(binding.name))
+      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 {
@@ -138,7 +226,7 @@ export function rewriteLooseRedeclarations({
     }
     if (statementRejected) continue
     if (!entries.some(entry => entry.existing.length > 0)) {
-      if (statement.kind === 'const') {
+      if (statement.kind === 'const' && bindingPolicy.variableRedeclarations) {
         replacements.push({
           start: statement.start - offset,
           end: statement.start - offset + statement.kind.length,
@@ -164,7 +252,7 @@ export function rewriteLooseRedeclarations({
         appendPart(mixedDeclaratorText(
           statement,
           declarator,
-          bindings.map(binding => ({ ...binding, existing: knownBindings.has(binding.name) })),
+          bindings.map(binding => ({ ...binding, existing: existing.includes(binding) })),
           code,
           offset,
           allocateName,
@@ -172,7 +260,7 @@ export function rewriteLooseRedeclarations({
         redeclared.push(...existing.map(collisionFor))
         rewrites.push({
           kind: 'redeclaration',
-          description: 'split a mixed top-level declaration while preserving native pattern initialization',
+          description: MIXED_REDECLARATION_REWRITE,
           source: existing.map(binding => binding.name).join(', '),
         })
       } else if (existing.length === bindings.length && bindings.length > 0) {

package/internal/repl-memory-projection.js

@@ -0,0 +1,277 @@
+import { isRecord } from './record-utils.js'
+
+export const REPL_MEMORY_KEY = 'ptcPlusRepl'
+export const REPL_MEMORY_META_KEY = 'dshPtcPlusBindings'
+
+const BINDING_KINDS = new Set(['variable', 'function', 'class', 'import'])
+const MAX_BINDINGS = 128
+const MAX_BINDING_NAME_LENGTH = 128
+const MAX_DEFINITION_SOURCE_LENGTH = 1024
+const MAX_DEFINITION_SOURCE_TOTAL_LENGTH = 16 * 1024
+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 ENTRY_FIELDS = new Set(['name', 'kind', 'definition'])
+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
+
+function exactFields(value, fields) {
+  if (!isRecord(value)) return false
+  const keys = Reflect.ownKeys(value)
+  return keys.length === fields.size && keys.every(key => (
+    typeof key === 'string' && fields.has(key)
+    && Object.prototype.propertyIsEnumerable.call(value, key)
+  ))
+}
+
+const EMPTY_REPL_MEMORY = Object.freeze({
+  available: false,
+  entries: Object.freeze([]),
+  total: 0,
+  omitted: 0,
+})
+
+export function unavailableReplMemorySnapshot() {
+  return EMPTY_REPL_MEMORY
+}
+
+function normalizeGeneration(value) {
+  if (typeof value !== 'string' || value.length === 0 || value.length > MAX_GENERATION_LENGTH) {
+    throw new Error('invalid dsh-ptc-plus REPL memory generation')
+  }
+  return value
+}
+
+function normalizeDefinition(value) {
+  if (!exactFields(value, DEFINITION_FIELDS)
+    || typeof value.source !== 'string' || value.source.length === 0
+    || value.source.length > MAX_DEFINITION_SOURCE_LENGTH
+    || !Number.isSafeInteger(value.line) || value.line < 1
+    || !Number.isSafeInteger(value.column) || value.column < 1) {
+    throw new Error('invalid dsh-ptc-plus REPL binding definition')
+  }
+  return Object.freeze({ source: value.source, line: value.line, column: value.column })
+}
+
+function normalizeBinding(value) {
+  if (!exactFields(value, ENTRY_FIELDS) || typeof value.name !== 'string'
+    || value.name.length === 0 || value.name.length > MAX_BINDING_NAME_LENGTH
+    || !BINDING_KINDS.has(value.kind)) {
+    throw new Error('invalid dsh-ptc-plus REPL memory binding')
+  }
+  return Object.freeze({
+    name: value.name,
+    kind: value.kind,
+    definition: normalizeDefinition(value.definition),
+  })
+}
+
+/** Produce bounded, value-independent presentation metadata from the live binding catalog. */
+export function createReplMemorySnapshot(bindings) {
+  const all = Array.isArray(bindings) ? bindings : []
+  const candidates = []
+  const names = new Set()
+  for (const binding of all) {
+    try {
+      const normalized = normalizeBinding(binding)
+      if (names.has(normalized.name)) continue
+      names.add(normalized.name)
+      candidates.push(normalized)
+    } catch {}
+  }
+  const entries = []
+  let sourceLength = 0
+  for (const binding of candidates) {
+    if (entries.length >= MAX_BINDINGS) break
+    if (sourceLength + binding.definition.source.length > MAX_DEFINITION_SOURCE_TOTAL_LENGTH) continue
+    entries.push(binding)
+    sourceLength += binding.definition.source.length
+  }
+  return Object.freeze({
+    available: true,
+    entries: Object.freeze(entries),
+    total: candidates.length,
+    omitted: candidates.length - entries.length,
+  })
+}
+
+/** Validate one complete session-projection value without accepting unknown fields. */
+export function normalizeReplMemorySnapshot(value) {
+  if (!exactFields(value, SNAPSHOT_FIELDS) || 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) {
+    throw new Error('invalid dsh-ptc-plus REPL memory snapshot')
+  }
+  if (!value.available && (value.total !== 0 || value.entries.length !== 0)) {
+    throw new Error('unavailable dsh-ptc-plus REPL memory snapshot must be empty')
+  }
+  const names = new Set()
+  let sourceLength = 0
+  const entries = value.entries.map((entry) => {
+    const normalized = normalizeBinding(entry)
+    if (names.has(normalized.name)) {
+      throw new Error('invalid dsh-ptc-plus REPL memory binding')
+    }
+    sourceLength += normalized.definition.source.length
+    if (sourceLength > MAX_DEFINITION_SOURCE_TOTAL_LENGTH) {
+      throw new Error('dsh-ptc-plus REPL binding definitions exceed the presentation budget')
+    }
+    names.add(normalized.name)
+    return normalized
+  })
+  return Object.freeze({
+    available: value.available,
+    entries: Object.freeze(entries),
+    total: value.total,
+    omitted: value.omitted,
+  })
+}
+
+function normalizeReplMemoryMetadata(value) {
+  if (!exactFields(value, MEMORY_META_FIELDS) || value.version !== REPL_MEMORY_META_VERSION) {
+    throw new Error('invalid dsh-ptc-plus REPL memory metadata')
+  }
+  return Object.freeze({
+    version: REPL_MEMORY_META_VERSION,
+    generation: normalizeGeneration(value.generation),
+    memory: normalizeReplMemorySnapshot(value.memory),
+  })
+}
+
+/** Read current-owner presentation metadata without affecting tool settlement. */
+export function validatedReplMemorySnapshot(meta, generation) {
+  if (!isRecord(meta) || !Object.hasOwn(meta, REPL_MEMORY_META_KEY)) return undefined
+  try {
+    const normalized = normalizeReplMemoryMetadata(meta[REPL_MEMORY_META_KEY])
+    return normalized.generation === normalizeGeneration(generation)
+      ? normalized.memory
+      : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function projectionState(generation, memory, pendingReplCalls) {
+  return Object.freeze({
+    generation,
+    memory,
+    pendingReplCalls: pendingReplCalls === null
+      ? null
+      : Object.freeze(pendingReplCalls),
+  })
+}
+
+function emptyProjectionState(generation) {
+  return projectionState(normalizeGeneration(generation), EMPTY_REPL_MEMORY, [])
+}
+
+function normalizeProjectionState(value, generation) {
+  if (!exactFields(value, PROJECTION_STATE_FIELDS)) {
+    throw new Error('invalid dsh-ptc-plus REPL memory projection state')
+  }
+  const storedGeneration = normalizeGeneration(value.generation)
+  const currentGeneration = normalizeGeneration(generation)
+  if (storedGeneration !== currentGeneration) return emptyProjectionState(currentGeneration)
+  const memory = normalizeReplMemorySnapshot(value.memory)
+  if (value.pendingReplCalls === null) {
+    if (memory.available) {
+      throw new Error('untracked dsh-ptc-plus REPL calls require unavailable memory')
+    }
+    return projectionState(currentGeneration, memory, null)
+  }
+  if (!Array.isArray(value.pendingReplCalls)
+    || value.pendingReplCalls.length > MAX_PENDING_REPL_CALLS) {
+    throw new Error('invalid dsh-ptc-plus pending REPL calls')
+  }
+  let previousSeq
+  const callIds = new Set()
+  const pendingReplCalls = value.pendingReplCalls.map((pending) => {
+    if (!exactFields(pending, PENDING_CALL_FIELDS)
+      || typeof pending.callId !== 'string' || pending.callId.length === 0
+      || pending.callId.length > MAX_CALL_ID_LENGTH || callIds.has(pending.callId)
+      || !Number.isSafeInteger(pending.seq) || pending.seq < 0
+      || (previousSeq !== undefined && previousSeq >= pending.seq)) {
+      throw new Error('invalid dsh-ptc-plus pending REPL call')
+    }
+    callIds.add(pending.callId)
+    previousSeq = pending.seq
+    return Object.freeze({ callId: pending.callId, seq: pending.seq })
+  })
+  return projectionState(currentGeneration, memory, pendingReplCalls)
+}
+
+function eventCallId(value) {
+  return typeof value === 'string' && value.length > 0 && value.length <= MAX_CALL_ID_LENGTH
+    ? value
+    : undefined
+}
+
+function trackReplCall(state, event) {
+  if (!REPL_TOOL_NAMES.has(event.data?.name)) return state
+  const seq = event.seq
+  const callId = eventCallId(event.data?.callId)
+  if (!Number.isSafeInteger(seq) || seq < 0 || callId === undefined) return state
+  const pending = state.pendingReplCalls
+  if (pending === null || pending.some(call => call.callId === callId || call.seq === seq)) return state
+  if (pending.length >= MAX_PENDING_REPL_CALLS) {
+    return projectionState(state.generation, EMPTY_REPL_MEMORY, null)
+  }
+  return projectionState(state.generation, state.memory, [
+    ...pending,
+    Object.freeze({ callId, seq }),
+  ].sort((left, right) => left.seq - right.seq))
+}
+
+function settleReplCall(state, event, generation) {
+  if (event.surfaceOp !== undefined && event.surfaceOp !== 'append') return state
+  const pending = state.pendingReplCalls
+  if (pending === null) return state
+  const callId = eventCallId(event.data?.message?.source?.callId)
+  if (callId === undefined) return state
+  const index = pending.findIndex(call => call.callId === callId)
+  if (index < 0) return state
+  const remaining = pending.filter((_call, pendingIndex) => pendingIndex !== index)
+  const memory = validatedReplMemorySnapshot(event.data?.meta, generation) ?? state.memory
+  return projectionState(state.generation, memory, remaining)
+}
+
+/** Merge the binding snapshot into private, model-invisible result presentation metadata. */
+export function withReplMemorySnapshot(meta, snapshot, generation) {
+  const base = isRecord(meta) ? { ...meta } : meta === undefined ? {} : { value: meta }
+  base[REPL_MEMORY_META_KEY] = normalizeReplMemoryMetadata({
+    version: REPL_MEMORY_META_VERSION,
+    generation: normalizeGeneration(generation),
+    memory: snapshot,
+  })
+  return base
+}
+
+/** Build the current runtime owner's value-independent session projection. */
+export function createReplMemoryProjection(generation) {
+  const currentGeneration = normalizeGeneration(generation)
+  return Object.freeze({
+    key: REPL_MEMORY_KEY,
+    stateVersion: 3,
+    stateSchema: Object.freeze({
+      parse: value => normalizeProjectionState(value, currentGeneration),
+    }),
+    init: () => emptyProjectionState(currentGeneration),
+    apply(state, event) {
+      if (event?.type === 'session/end-seed') return emptyProjectionState(currentGeneration)
+      if (event?.type === 'tool/call') return trackReplCall(state, event)
+      if (event?.type === 'tool/result') return settleReplCall(state, event, currentGeneration)
+      return state
+    },
+    wire: Object.freeze({
+      viewSchema: Object.freeze({ parse: normalizeReplMemorySnapshot }),
+      view: state => state.memory,
+    }),
+  })
+}

package/internal/repl-rewrite-contract.js

@@ -0,0 +1,15 @@
+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 function redeclarationCommitTarget(name, statementStart) {
+  return `redeclaration:${statementStart}:${name}`
+}

package/internal/run-code-description.js

@@ -0,0 +1,34 @@
+const GENERATED_RUN_CODE_DESCRIPTION = 'Execute the next TypeScript cell in this session'
+export const GENERATED_RUN_CODE_DESCRIPTION_KEY = 'dshPtcPlusRunCodeDescription'
+
+// Keep presentation provenance outside the canonical JSON argument graph.
+const generatedArguments = new WeakSet()
+
+export function markGeneratedRunCodeArguments(argumentsValue) {
+  if (argumentsValue !== null
+    && (typeof argumentsValue === 'object' || typeof argumentsValue === 'function')) {
+    generatedArguments.add(argumentsValue)
+  }
+  return argumentsValue
+}
+
+export function generatedRunCodeExecutionArguments(argumentsValue) {
+  markGeneratedRunCodeArguments(argumentsValue)
+  return markGeneratedRunCodeArguments({
+    ...argumentsValue,
+    description: GENERATED_RUN_CODE_DESCRIPTION,
+  })
+}
+
+export function generatedRunCodeDescriptionMeta(argumentsValue, meta) {
+  if (!generatedArguments.has(argumentsValue)) return meta
+  const base = meta !== null && typeof meta === 'object' && !Array.isArray(meta)
+    ? meta
+    : meta === undefined ? {} : { value: meta }
+  return {
+    ...base,
+    [GENERATED_RUN_CODE_DESCRIPTION_KEY]: GENERATED_RUN_CODE_DESCRIPTION,
+  }
+}
+
+export { GENERATED_RUN_CODE_DESCRIPTION }