dsh-ptc-plus 0.3.2 → 0.4.1

package/internal/module-compilation.js

@@ -0,0 +1,321 @@
+import { staticModuleLinkReference } from './compiler-module-links.js'
+import { parse } from '@babel/parser'
+import { types as t } from '@babel/core'
+import { CELL_PARSER_PLUGINS, normalizeStatefulScopes, normalizeTypeScriptValues, lowerNativeLanguageSource,
+  hasModuleResources } from './repl-scope-normalizer.js'
+import { bindingNodes, createGeneratedNameAllocator } from './binding-pattern.js'
+import { applySourceEdits, identitySourceMap, sourceOffsetAt } from './source-position-map.js'
+import { applyRegionEdits, indexSourceRegions, visitRegionSource, transformRegionSource, validateRegionSource, sourceRegionData } from './compiler-region-output.js'
+import { adaptDynamicCell } from './dynamic-environment-integration.js'
+import { adaptLegacyModuleReferences, adaptModuleOperations } from './managed-module-operations.js'
+import { markCallableSources, collectRegionCallableRanges, createRegionCallableCollector, emitRegionCallableSources, callableSourceCatalog } from './callable-source-facts.js'
+import { commonJsExportEvidence } from './commonjs-source-evidence.js'
+export { commonJsExportEvidence, linkCommonJsEvidenceSource } from './commonjs-source-evidence.js'
+import { COMMONJS_PARAMETERS } from './compiler-scope-facts.js'
+import {
+  LEGACY_USER_BINDING_TRANSFORM, USER_BINDING_TRANSFORM, PROTECTED_MODULE_TRANSFORM,
+  supportedUserBindingTransform, transformTypeScriptSource,
+} from './typescript-transform.js'
+
+const topLevelRegion = region => region.kind === 'program' || region.top === true
+
+/** Keep one native export mapping while executing every source occurrence. */
+function normalizeModuleExports(source, sourceMap) {
+  const tree = parse(source, { sourceType: 'module', errorRecovery: true,
+    plugins: CELL_PARSER_PLUGINS })
+  for (const error of tree.errors) if (error.reasonCode === 'ModuleExportUndefined') throw error
+  const allocate = createGeneratedNameAllocator(tree)
+  const exports = new Map()
+  const edits = []
+  const anonymousFunctions = []
+  const dependencyEdits = []
+  const exportName = node => node.type === 'Identifier' ? node.name : node.value
+  for (const statement of tree.program.body) {
+    if (statement.type === 'ExportDefaultDeclaration') {
+      const declaration = statement.declaration
+      const named = ['FunctionDeclaration', 'ClassDeclaration'].includes(declaration.type)
+      if (declaration.type === 'FunctionDeclaration' && declaration.id === null) {
+        // Its synthetic native binding is inaccessible to source writes. Keep
+        // instantiation-time identity and the native inferred name "default".
+        exports.set('default', { nativeFunction: statement })
+        anonymousFunctions.push(statement)
+        continue
+      }
+      const local = named && declaration.id !== null ? declaration.id.name : allocate('module_default')
+      exports.set('default', local)
+      if (named && declaration.id !== null) {
+        edits.push({ start: statement.start, end: declaration.start, text: '' })
+      } else {
+        const value = source.slice(declaration.start, declaration.end)
+        const anonymous = declaration.type === 'ClassDeclaration'
+          || ['FunctionExpression', 'ClassExpression', 'ArrowFunctionExpression'].includes(declaration.type) && declaration.id == null
+        edits.push({ start: statement.start, end: statement.end,
+          text: `let ${local} = (${anonymous ? `({default: (${value})}).default` : value});` })
+      }
+      continue
+    }
+    if (statement.type !== 'ExportNamedDeclaration') continue
+    const declaration = statement.declaration
+    if (declaration !== null && declaration !== undefined) {
+      const names = declaration.type === 'VariableDeclaration'
+        ? declaration.declarations.flatMap(item => bindingNodes(item.id)).map(item => item.name)
+        : declaration.id?.type === 'Identifier' ? [declaration.id.name] : []
+      for (const name of names) exports.set(name, name)
+      edits.push({ start: statement.start, end: declaration.start, text: '' })
+      continue
+    }
+    const dependencies = []
+    for (const specifier of statement.specifiers) {
+      if (specifier.exportKind === 'type') continue
+      const name = exportName(specifier.exported)
+      if (statement.source === null || statement.source === undefined) {
+        exports.set(name, exportName(specifier.local))
+      } else {
+        const local = allocate('module_export')
+        const binding = specifier.type === 'ExportNamespaceSpecifier'
+          ? `* as ${local}` : `{ ${JSON.stringify(exportName(specifier.local))} as ${local} }`
+        const dependency = `import ${binding} from ${source.slice(statement.source.start, statement.end)}`
+        const mapping = specifier.type === 'ExportNamespaceSpecifier' ? `* as ${JSON.stringify(name)}`
+          : `{ ${JSON.stringify(exportName(specifier.local))} as ${JSON.stringify(name)} }`
+        const selected = { native: `export ${mapping} from ${source.slice(statement.source.start, statement.end)}` }
+        exports.set(name, selected)
+        dependencies.push({ name, selected, dependency })
+      }
+    }
+    if (statement.source != null && statement.specifiers.length === 0) {
+      dependencies.push(`import ${source.slice(statement.source.start, statement.end)}`)
+    }
+    dependencyEdits.push({ start: statement.start, end: statement.end, dependencies })
+  }
+  for (const statement of anonymousFunctions) {
+    if (exports.get('default')?.nativeFunction !== statement) {
+      // An anonymous function declaration has no initializer effects or local
+      // source name once a later export mapping replaces its only exposure.
+      edits.push({ start: statement.start, end: statement.end, text: '' })
+    }
+  }
+  for (const { start, end, dependencies } of dependencyEdits) {
+    // A retained native re-export already owns linking. An extra named import
+    // can make Node reject an otherwise valid cyclic forwarding graph. Only
+    // replaced mappings need a separate import to retain their source effects
+    // and missing-export validation.
+    edits.push({ start, end, text: dependencies.filter(item => typeof item === 'string' || exports.get(item.name) !== item.selected)
+      .map(item => typeof item === 'string' ? item : item.dependency).join('\n') })
+  }
+  const locals = [...exports].filter(([, binding]) => typeof binding === 'string')
+  const native = [...exports.values()].filter(binding => binding.native !== undefined).map(binding => binding.native)
+  if (exports.size > 0) edits.push({ start: source.length, end: source.length,
+    text: `\n${locals.length > 0 ? `export { ${locals.map(([name, local]) => `${local} as ${JSON.stringify(name)}`).join(', ')} };\n` : ''}${native.join('\n')}\n` })
+  return applySourceEdits(source, sourceMap, edits)
+}
+
+function moduleLinkPlan(source) {
+  const tree = parse(source, { sourceType: 'module', errorRecovery: true,
+    allowUndeclaredExports: true, plugins: CELL_PARSER_PLUGINS })
+  const allocate = createGeneratedNameAllocator(tree)
+  const reader = allocate('module_import_read')
+  const nativeReader = allocate('module_native_read')
+  const internalBindings = [reader, nativeReader]
+  const exports = []
+  const stars = []
+  const exportName = node => node.name ?? node.value
+  for (const statement of tree.program.body) {
+    if (statement.type === 'ExportDefaultDeclaration') exports.push({ name: 'default', kind: 'native' })
+    if (!['ExportNamedDeclaration', 'ExportAllDeclaration'].includes(statement.type)) continue
+    const relation = statement.source ? { source: statement.source.value,
+      attributes: Object.fromEntries((statement.attributes ?? [])
+        .map(attribute => [exportName(attribute.key), attribute.value.value])) } : undefined
+    if (statement.type === 'ExportAllDeclaration') stars.push(relation)
+    else for (const item of statement.specifiers) {
+      const name = exportName(item.exported)
+      exports.push(relation === undefined ? { name, kind: 'accessor' }
+        : item.type === 'ExportNamespaceSpecifier' ? { name, kind: 'namespace', ...relation }
+          : { name, kind: 'forward', imported: exportName(item.local), ...relation })
+    }
+  }
+  const runtime = new URL('./stateful-module-runtime.js', import.meta.url).href
+  return { reader, internalBindings, moduleInterface: { exports, stars },
+    prefix: `import {readModuleImport as ${nativeReader}} from ${JSON.stringify(runtime)};\nfunction ${reader}(source,name,get,attributes){return ${nativeReader}(import.meta.url,source,name,get,attributes)}\n` }
+}
+
+function adaptStaticModuleLinks(normalized, staticLinks) {
+  const edits = []
+  visitRegionSource(normalized, { sourceType: 'module', plugins: CELL_PARSER_PLUGINS }, input => {
+    for (const node of input.selected.body) {
+      if (node.source == null || !['ImportDeclaration', 'ExportNamedDeclaration', 'ExportAllDeclaration'].includes(node.type)) continue
+      const source = node.source.value
+      const attributes = Object.fromEntries((node.attributes ?? []).map(item => [item.key.name ?? item.key.value, item.value.value]))
+      const reference = staticModuleLinkReference(source, attributes)
+      staticLinks.push({ source, reference })
+      edits.push({ start: sourceOffsetAt(input.sourceMap, node.source.start),
+        end: sourceOffsetAt(input.sourceMap, node.source.end - 1) + 1,
+        text: JSON.stringify(reference) })
+    }
+  }, topLevelRegion)
+  return applyRegionEdits(normalized, edits)
+}
+
+function commonJsBodyRange(source) {
+  const body = parse(source).program.body[0].body
+  return { start: body.start + 1, end: body.end - 1 }
+}
+
+/** Module activations share lexical updates while retaining the native linker. */
+export function compileStatefulModule(source, {
+  transform = USER_BINDING_TRANSFORM, target = 'module', url, nativeUsing,
+} = {}) {
+  if (transform !== PROTECTED_MODULE_TRANSFORM && !supportedUserBindingTransform(transform)) {
+    throw new TypeError('user binding snapshot cannot prove its historical TypeScript transform')
+  }
+  const staticLinks = []
+  const sourceType = target === 'commonjs' ? 'commonjs' : 'module'
+  const callableParserOptions = { sourceType, plugins: CELL_PARSER_PLUGINS,
+    ...(target === 'commonjs' ? { allowAwaitOutsideFunction: undefined, allowReturnOutsideFunction: undefined } : {}) }
+  let mapped = { code: source, sourceMap: identitySourceMap(source.length) }
+  let callableSources = []
+  let nativeJavaScript = false
+  if (source.startsWith('#!')) {
+    // Interpreter directives belong to the source's first line, never to the
+    // prefixed module or CommonJS wrapper. Retain its original line boundary.
+    const directive = source.match(/^#![^\n\r\u2028\u2029]*/u)
+    mapped = applySourceEdits(source, mapped.sourceMap, [{ start: 0,
+      end: directive[0].length, text: '' }])
+  }
+  if (transform !== LEGACY_USER_BINDING_TRANSFORM) {
+    const marked = markCallableSources(mapped.code, mapped.sourceMap, callableParserOptions,
+      { lowerNativeSource: lowerNativeLanguageSource, nativeUsing })
+    callableSources = marked.callableSources
+    nativeJavaScript = marked.nativeJavaScript
+    mapped = marked
+    if (!nativeJavaScript) mapped = normalizeTypeScriptValues(mapped.code, mapped.sourceMap, target)
+    if (target !== 'commonjs' && (transform === USER_BINDING_TRANSFORM
+      || transform === PROTECTED_MODULE_TRANSFORM && hasModuleResources(mapped.code))) {
+      mapped = normalizeModuleExports(mapped.code, mapped.sourceMap)
+    }
+  }
+  const commonJsSource = target === 'commonjs'
+    ? commonJsExportEvidence(mapped.code, { legacy: transform === LEGACY_USER_BINDING_TRANSFORM }) : undefined
+  const links = transform === USER_BINDING_TRANSFORM && target === 'module'
+    ? moduleLinkPlan(mapped.code) : undefined
+  let normalized = transform === LEGACY_USER_BINDING_TRANSFORM ? mapped
+    : normalizeStatefulScopes(mapped.code, mapped.sourceMap, { target, moduleImport: links?.reader, nativeJavaScript, nativeUsing,
+      mode: transform === PROTECTED_MODULE_TRANSFORM ? 'protected-v1' : 'stateful-v1' })
+  // Protected entries retain native declaration policy; adapters still need
+  // bounded source regions after TypeScript and decorator lowering.
+  if (transform === PROTECTED_MODULE_TRANSFORM && normalized.sourceRegions === undefined) normalized = { ...normalized,
+    sourceRegions: indexSourceRegions(normalized.code, callableParserOptions) }
+  let protectedInterface
+  if (transform === PROTECTED_MODULE_TRANSFORM && target === 'module') {
+    const lexicalExports = normalized.moduleLexicalExports
+    normalized = adaptLegacyModuleReferences(normalized)
+    protectedInterface = normalized.moduleInterface
+    if (lexicalExports !== undefined) protectedInterface = { ...protectedInterface,
+      exports: protectedInterface.exports.map(entry => lexicalExports.has(entry.name) ? { ...entry, kind: 'accessor' } : entry) }
+  }
+  if (links !== undefined) normalized = { ...applyRegionEdits(normalized,
+    [{ start: 0, end: 0, text: links.prefix }]),
+    internalBindings: new Set([...normalized.internalBindings ?? [], ...links.internalBindings]) }
+  const classificationCode = normalized.code
+  if (links !== undefined || protectedInterface !== undefined) normalized = adaptStaticModuleLinks(normalized, staticLinks)
+  if (transform !== LEGACY_USER_BINDING_TRANSFORM) normalized = adaptModuleOperations(normalized, { target, url })
+  if (transform !== LEGACY_USER_BINDING_TRANSFORM) normalized = { ...normalized, ...adaptDynamicCell(normalized.code, normalized.sourceMap, {
+    sourceRegions: normalized.sourceRegions,
+    callableCollector: createRegionCallableCollector(callableSources),
+    module: true, compactOutput: true, importOperation: normalized.importOperation, sourceType, originalSource: source,
+    bindings: normalized.dynamicBindings, privateBindings: normalized.privateBindings,
+    internalBindings: normalized.internalBindings, parserPlugins: CELL_PARSER_PLUGINS,
+  }) }
+  // The published legacy map ends at its maintained transform input.
+  const wrapper = target === 'commonjs' ? 'function __ptc_commonjs__(){\n' : ''
+  let input = normalized
+  if (transform === LEGACY_USER_BINDING_TRANSFORM && wrapper) {
+    input = applySourceEdits(input.code, input.sourceMap, [{ start: 0, end: 0, text: wrapper }])
+    input = applySourceEdits(input.code, input.sourceMap, [{ start: input.code.length, end: input.code.length, text: '\n}' }])
+  }
+  let transformed, nativeExtraction, emission, sources
+  let moduleInterface = links?.moduleInterface ?? protectedInterface
+  if (transform === LEGACY_USER_BINDING_TRANSFORM) {
+    // Preserve the historical TypeScript lowering before adapting native
+    // bindings. Its unexpanded output is the source indexed by shared regions.
+    transformed = transformTypeScriptSource(input.code)
+    let code = transformed.code
+    if (wrapper) {
+      nativeExtraction = commonJsBodyRange(code)
+      code = code.slice(nativeExtraction.start, nativeExtraction.end)
+    }
+    let entry = { code, sourceMap: identitySourceMap(code.length),
+      sourceRegions: indexSourceRegions(code, callableParserOptions) }
+    if (target === 'commonjs') entry = normalizeStatefulScopes(code, entry.sourceMap,
+      { mode: 'protected-v1', target, nativeJavaScript: true, deferDecorators: true, deferResources: true })
+    if (target === 'module') {
+      entry = adaptLegacyModuleReferences(entry)
+      moduleInterface = entry.moduleInterface
+      entry = adaptStaticModuleLinks(entry, staticLinks)
+    }
+    entry = adaptModuleOperations(entry, { target, url })
+    emission = adaptDynamicCell(entry.code, entry.sourceMap, { module: true,
+      sourceRegions: entry.sourceRegions,
+      importOperation: entry.importOperation, sourceType, originalSource: source,
+      bindings: entry.dynamicBindings, internalBindings: entry.internalBindings, parserPlugins: CELL_PARSER_PLUGINS,
+    })
+  } else {
+    const owners = normalized.callableRanges === undefined ? collectRegionCallableRanges(normalized, callableSources, callableParserOptions)
+      : new Map(normalized.callableRanges.map(range => [range.start, range]))
+    // Native JavaScript has no remaining TypeScript emission work. Retain the
+    // generator's exact source and owner facts instead of expanding it again.
+    const output = nativeJavaScript ? { ...normalized, callableRanges: [...owners.values()] }
+      : transformRegionSource(normalized, { ...callableParserOptions, wrapCommonJs: true }, region => {
+      const generated = transformTypeScriptSource(region.code, {
+        module: target === 'module' && !region.prefix, sourceMap: true,
+        // Type-only declarations and the complete module interface were
+        // resolved before partitioning; omitted bodies cannot erase imports.
+        transform: { tsEnumIsMutable: true, verbatimModuleSyntax: true,
+          noEmptyExport: target === 'commonjs' || !!region.prefix },
+      })
+      return emitRegionCallableSources(region, generated, owners, callableParserOptions)
+    })
+    emission = nativeJavaScript ? output : { ...output, ...applySourceEdits(normalized.code, normalized.sourceMap,
+      [{ start: 0, end: normalized.code.length, text: output.code, mappings: output.sourceMap }]) }
+    sources = callableSourceCatalog(emission.code, callableSources, output.callableRanges)
+  }
+  // Callable ownership collection validates native output's exact grammar
+  // regions. Only the later TypeScript/legacy emitter changes that code.
+  if (!nativeJavaScript) validateRegionSource(emission, { sourceType, plugins: ['importAttributes'] })
+  return { code: emission.code, classificationCode, transform, target, moduleInterface, commonJsSource,
+    staticLinks, callableSources: sources,
+    sourceRegions: sourceRegionData(emission.sourceRegions),
+    sourceMap: { normalization: input.sourceMap, typescript: transformed?.map, nativeExtraction,
+      ...(transform === LEGACY_USER_BINDING_TRANSFORM ? {} : { emission: emission.sourceMap }) },
+  }
+}
+
+export function detectModuleSourceFormat(source, { extension } = {}) {
+  // Synchronous CommonJS hooks may leave format undefined. For an untyped
+  // package Node detects module syntax, including lexical wrapper-name clashes.
+  // Parse without executing source, allowing the repetitions PTC owns.
+  if (extension === '.ts') source = normalizeTypeScriptValues(source, identitySourceMap(source.length)).code
+  const tree = parse(source, { sourceType: 'unambiguous', errorRecovery: true,
+    allowReturnOutsideFunction: true, allowNewTargetOutsideFunction: true, plugins: CELL_PARSER_PLUGINS })
+  const wrapperNames = new Set(COMMONJS_PARAMETERS)
+  const lexicalWrapperName = tree.program.body.some(node => node.type === 'VariableDeclaration' && node.kind !== 'var'
+    ? node.declarations.some(item => bindingNodes(item.id).some(binding => wrapperNames.has(binding.name)))
+    : node.type === 'ClassDeclaration' && wrapperNames.has(node.id.name))
+  return tree.program.sourceType === 'module' || lexicalWrapperName ? 'module' : 'commonjs'
+}
+
+export function attachModuleNamespace(source, attributes, reference, sourceRegions) {
+  const text = source
+  const names = new Set()
+  visitRegionSource({ code: text, sourceMap: identitySourceMap(text.length), sourceRegions }, { sourceType: 'module' }, input => {
+    t.traverseFast(input.tree, node => { if (t.isIdentifier(node)) names.add(node.name) })
+  })
+  const allocate = createGeneratedNameAllocator(undefined, names)
+  const namespace = allocate('module_native_namespace')
+  const register = allocate('module_register_namespace')
+  const runtime = new URL('./stateful-module-runtime.js', import.meta.url).href
+  // A namespace import adds no named-import validation and reads no exports.
+  // Register after successful evaluation, before native require can return.
+  const entries = Object.entries(attributes ?? {})
+  const suffix = entries.length === 0 ? '' : ` with {${entries.map(([key, value]) => `${JSON.stringify(key)}:${JSON.stringify(value)}`).join(',')}}`
+  return `${text}\nimport * as ${namespace} from ${JSON.stringify(reference)}${suffix};\nimport {recordStatefulModuleNamespace as ${register}} from ${JSON.stringify(runtime)};\n${register}(import.meta.url,${namespace});\n`
+}

package/internal/module-runtime-platform.js

@@ -0,0 +1,19 @@
+import { registerHooks } from 'node:module'
+import { compilerPlatformBridge } from './compiler-platform.js'
+
+const nativeRegisterHooks = registerHooks
+const apply = Reflect.apply
+// Acquire the public hook lifecycle before any owned source can replace Node
+// exports or the hook prototype. The empty bootstrap hook changes no edge.
+const bootstrapHook = nativeRegisterHooks({})
+const deregister = bootstrapHook.deregister
+apply(deregister, bootstrapHook, [])
+
+/** Each native resolution scope has one captured registration and disposer. */
+export function registerModuleResolutionHook(resolve) {
+  const hook = nativeRegisterHooks({ resolve })
+  return () => apply(deregister, hook, [])
+}
+
+export const fileURLToPath = compilerPlatformBridge.fileURLToPath
+export const pathToFileURL = compilerPlatformBridge.pathToFileURL

package/internal/module-transform-contract.js

@@ -0,0 +1,12 @@
+export const LEGACY_USER_BINDING_TRANSFORM = 'amaro@1.1.11'
+export const USER_BINDING_TRANSFORM = 'stateful-module-v1+amaro@1.1.11'
+export const PROTECTED_MODULE_TRANSFORM = 'protected-module-v1+amaro@1.1.11'
+
+export function moduleTransformForLanguage(languageSemantics) {
+  return languageSemantics === 'stateful-v1' ? USER_BINDING_TRANSFORM
+    : languageSemantics === 'protected-v1' ? PROTECTED_MODULE_TRANSFORM : LEGACY_USER_BINDING_TRANSFORM
+}
+
+export function supportedUserBindingTransform(transform) {
+  return transform === USER_BINDING_TRANSFORM || transform === LEGACY_USER_BINDING_TRANSFORM
+}

package/internal/native-await-declarations.js

@@ -0,0 +1,68 @@
+import traverseModule from '@babel/traverse'
+import { types as t } from '@babel/core'
+
+const traverse = traverseModule.default ?? traverseModule
+
+/** Native await owns persistent declaration instantiation; references own writes. */
+export function rewriteNativeAwaitDeclarations(tree, { hiddenBindings, nativePlaceholders, reference, initialize, namedValue, replaceIterationDeclaration }) {
+  const placeholders = []
+  const preserve = node => { nativePlaceholders.add(node); placeholders.push(node) }
+  const rootIdentifiers = node => {
+    if (t.isIdentifier(node)) return [node]
+    if (t.isObjectPattern(node)) return node.properties.flatMap(property => rootIdentifiers(property.value ?? property.argument))
+    if (t.isArrayPattern(node)) return node.elements.flatMap(element => rootIdentifiers(element))
+    // Native REPL await registers direct pattern identifiers. Default targets
+    // and array rest targets remain assignment references in that generation.
+    return []
+  }
+  const lexicalPlaceholder = name => preserve(t.variableDeclaration('let', [
+    t.variableDeclarator(t.identifier(name), t.identifier(name)),
+  ]))
+  const assignmentPattern = (node, path) => {
+    if (t.isIdentifier(node)) return reference(path, node.name)
+    if (t.isArrayPattern(node)) return t.arrayPattern(node.elements.map(element => element === null ? null : assignmentPattern(element, path)))
+    if (t.isObjectPattern(node)) return t.objectPattern(node.properties.map(property => t.isRestElement(property)
+      ? t.restElement(assignmentPattern(property.argument, path))
+      : t.objectProperty(property.key, assignmentPattern(property.value, path), property.computed, false)))
+    if (t.isAssignmentPattern(node)) return t.assignmentPattern(assignmentPattern(node.left, path),
+      t.isIdentifier(node.left) ? namedValue(node.left.name, node.right) : node.right)
+    return t.restElement(assignmentPattern(node.argument, path))
+  }
+  traverse(tree, {
+    VariableDeclaration(path) {
+      if (path.node.declarations.some(declaration => t.isIdentifier(declaration.id) && hiddenBindings.has(declaration.id.name))
+        || path.getFunctionParent() !== null || path.node.kind !== 'var' && !path.parentPath.isProgram()) return
+      const original = path.node
+      if (original.kind === 'var') {
+        const declaration = t.cloneNode(original, true)
+        for (const item of declaration.declarations) item.init = t.unaryExpression('void', t.numericLiteral(0))
+        preserve(t.ifStatement(t.booleanLiteral(false), t.blockStatement([declaration])))
+      } else for (const item of original.declarations) for (const name of rootIdentifiers(item.id)) lexicalPlaceholder(name.name)
+      const assignment = item => {
+        const value = item.init ?? t.unaryExpression('void', t.numericLiteral(0))
+        return t.isIdentifier(item.id) ? initialize(path, item.id.name, namedValue(item.id.name, value))
+          : t.assignmentExpression('=', assignmentPattern(item.id, path), value)
+      }
+      if (path.parentPath.isForOfStatement() || path.parentPath.isForInStatement()) {
+        replaceIterationDeclaration(path, assignmentPattern(original.declarations[0].id, path),
+          original.declarations.filter(item => item.init !== null).map(assignment))
+      } else {
+        const assignments = original.declarations.map(assignment)
+        const expression = t.inherits(assignments.length === 1 ? assignments[0] : t.sequenceExpression(assignments), original)
+        path.replaceWith(path.parentPath.isForStatement() ? expression : t.expressionStatement(t.unaryExpression('void', expression)))
+      }
+      path.skip()
+    },
+    ClassDeclaration(path) {
+      if (!path.parentPath.isProgram()) return
+      const name = path.node.id.name
+      lexicalPlaceholder(name)
+      const target = reference(path.parentPath, name)
+      path.node.type = 'ClassExpression'
+      const assignment = t.inherits(t.assignmentExpression('=', target, path.node), path.node)
+      path.replaceWith(t.expressionStatement(t.unaryExpression('void', assignment)))
+      path.skip()
+    },
+  })
+  tree.program.body.unshift(...placeholders)
+}

package/internal/native-root-compilation.js

@@ -0,0 +1,54 @@
+import { parse } from '@babel/parser'
+import { bindingNodes, createGeneratedNameAllocator } from './binding-pattern.js'
+import { markCallableSources, collectCallableSources } from './callable-source-facts.js'
+import { adaptDynamicCell } from './dynamic-environment-integration.js'
+import { CELL_PARSER_PLUGINS } from './repl-scope-normalizer.js'
+
+/** Native declarations remain frozen; dynamic entries retain their native root. */
+export function adaptNativeRootDynamic(prepared, options, originalSource) {
+  if (prepared.collisions.length !== 0) return { ...prepared, nativeLexicals: new Set() }
+  const parser = { sourceType: 'script', allowAwaitOutsideFunction: true,
+    allowReturnOutsideFunction: true, plugins: CELL_PARSER_PLUGINS }
+  const marked = markCallableSources(prepared.code, prepared.sourceMap, parser)
+  const tree = parse(marked.code, parser)
+  const nativeLexicals = new Set(tree.program.body.flatMap(statement =>
+    statement.type === 'VariableDeclaration' && statement.kind !== 'var'
+      ? statement.declarations.flatMap(declaration => bindingNodes(declaration.id).map(binding => binding.name))
+      : statement.type === 'ClassDeclaration' ? [statement.id.name] : []))
+  const nativeAwait = hasRootAwait(tree.program)
+  const reservedBindings = new Set([...prepared.importNamespaces,
+    ...options.knownBindings ?? [], ...options.reservedBindings ?? []])
+  const allocate = createGeneratedNameAllocator(parse(marked.code, parser), reservedBindings)
+  const global = allocate('native_environment_global')
+  const established = [...options.establishedRoots ?? []]
+  const logicalRoots = established.filter(([, source]) => source !== 'absent').map(([name]) => name)
+  const nativePublications = prepared.declarations.filter(declaration => options.establishedRoots?.has(declaration.name)
+    && !prepared.redeclared.some(redeclaration => redeclaration.name === declaration.name))
+    .map(declaration => ({ name: declaration.name, writable: declaration.writable,
+      nativeLexical: nativeLexicals.has(declaration.name),
+      import: prepared.imports.get(declaration.name) }))
+  const dynamic = adaptDynamicCell(marked.code, marked.sourceMap, { nativeRoot: true,
+    environmentGlobal: global, reservedBindings, internalBindings: prepared.importNamespaces,
+    originalSource, parserPlugins: CELL_PARSER_PLUGINS, nativeAwait, logicalRoots: logicalRoots.length > 0 })
+  const callableSources = collectCallableSources(dynamic.code, marked.callableSources, parser)
+  return { ...prepared, code: dynamic.code, sourceMap: dynamic.sourceMap, nativeLexicals,
+    ...(established.length === 0 ? {} : { rootBindingFacts: true, rootBindings: {
+      known: [...options.knownBindings ?? []], established, candidates: [...options.rootCandidates ?? []],
+      dynamicOrigins: options.dynamicOrigins ?? [], legacyImports: [...options.importBindings ?? []],
+    } }),
+    importNamespaces: new Set([...prepared.importNamespaces, dynamic.dynamicEnvironmentName]),
+    moduleLoads: [...prepared.moduleLoads, { operation: 'native-dynamic', global, callableSources, awaitRoot: nativeAwait,
+      nativeLexicals: [...options.nativeLexicalBindings ?? []],
+      logicalRoots, writableRoots: logicalRoots.filter(name => options.writableBindings?.has(name)), nativePublications }] }
+}
+
+function hasRootAwait(node) {
+  if (node === null || typeof node !== 'object') return false
+  if (node.type === 'AwaitExpression' || node.type === 'ForOfStatement' && node.await) return true
+  if (['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression'].includes(node.type)) return false
+  if (['ObjectMethod', 'ClassMethod', 'ClassPrivateMethod'].includes(node.type)) {
+    return node.computed && hasRootAwait(node.key)
+  }
+  return Object.entries(node).some(([key, value]) => !['loc', 'extra', 'start', 'end'].includes(key)
+    && (Array.isArray(value) ? value.some(hasRootAwait) : value?.type !== undefined && hasRootAwait(value)))
+}

package/internal/native-root-dynamic.js

@@ -0,0 +1,67 @@
+import { createDynamicEnvironmentRuntime } from './dynamic-environment-runtime.js'
+import { moduleRuntimeIntrinsics as internal } from './compiler-intrinsics.js'
+
+const { Map, Set, mapGet, mapSet, mapHas, mapDelete, setHas, setAdd, appendArray } = internal
+
+/** Native storage and catalog-proved logical roots share a captured legacy view. */
+export function createNativeRootDynamic({ intrinsics, importModule, read, write, typeOf, remove, logicalReference }) {
+  const interfaceOwner = {}
+  const runtime = createDynamicEnvironmentRuntime({ ...intrinsics, importModule, interfaceOwner }).installIntrinsics()
+  const descriptor = name => ({ kind: 'var', get: () => read(name),
+    set: (value, strict) => write(name, value, strict), delete: () => remove(name), typeof: () => typeOf(name) })
+  const environment = runtime.environment({
+    ambient(name, strict) {
+      return runtime.reference(name, descriptor(name), undefined, strict)
+    },
+    declareVars: runtime.declareGlobals,
+    createVar: descriptor,
+  })
+  runtime.setRootEnvironment(() => environment)
+  return {
+    environment(callableSources, awaitRoot = false, logicalRoots = [], writableRoots = []) {
+      if (logicalRoots.length === 0) {
+        runtime.registerSources(callableSources)
+        return awaitRoot ? environment.awaitActivation() : environment
+      }
+      // Each captured legacy environment keeps its own root view. Installing a
+      // later bridge must not change escaped eval/Function calls from old cells.
+      const bridgedRuntime = createDynamicEnvironmentRuntime({ ...intrinsics, importModule, interfaceOwner }).installIntrinsics()
+      const writable = new Set()
+      for (let index = 0; index < writableRoots.length; index++) setAdd(writable, writableRoots[index])
+      const bindings = new Map(), varFrame = new Map(), roots = new Map()
+      for (let index = 0; index < logicalRoots.length; index++) {
+        const name = logicalRoots[index], binding = logicalReference(name, setHas(writable, name))
+        mapSet(bindings, name, binding)
+        mapSet(roots, name, binding)
+        if (binding.kind === 'var') mapSet(varFrame, name, binding)
+        const remove = binding.delete
+        binding.delete = () => {
+          if (!remove()) return false
+          mapDelete(bindings, name)
+          mapDelete(varFrame, name)
+          return true
+        }
+      }
+      const bridged = bridgedRuntime.environment({ frames: [{ kind: 'lexical', bindings }], varFrame,
+        ambient: (name, strict) => bridgedRuntime.reference(name, descriptor(name), undefined, strict),
+        declareVars(names, functionNames) {
+          const globals = []
+          for (let index = 0; index < names.length; index++) {
+            if (!mapHas(roots, names[index])) appendArray(globals, names[index])
+          }
+          bridgedRuntime.declareGlobals(globals, functionNames)
+        },
+        createVar(name) {
+          const root = mapGet(roots, name)
+          if (root === undefined) return descriptor(name)
+          root.declare()
+          mapSet(bindings, name, root)
+          return root
+        },
+      })
+      bridgedRuntime.setRootEnvironment(() => bridged)
+      bridgedRuntime.registerSources(callableSources)
+      return awaitRoot ? bridged.awaitActivation() : bridged
+    },
+  }
+}

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