@shapeshift-labs/frontier-lang-compiler 0.2.149 → 0.2.151

package/dist/js-ts-safe-project-merge-typed-property-rename-rebase.js

@@ -0,0 +1,317 @@
+import { hashSemanticValue } from '@shapeshift-labs/frontier-lang-kernel';
+import { compactRecord, createMergeContext, sameStatementText, uniqueStrings } from './js-ts-safe-merge-context.js';
+import { scanJsTsTopLevelLedger } from './js-ts-safe-merge-ledger.js';
+import { hashText } from './js-ts-safe-project-merge-core.js';
+import {
+  entriesByKey,
+  escapeRegExp,
+  membersByName,
+  normalizeTypeText,
+  rejected,
+  renameTypesEqual,
+  safeId,
+  stalePropertyAccessReasons,
+  typedPropertyRenameRebaseEvidence,
+  unsafePropertyAccessReasons
+} from './js-ts-safe-project-merge-typed-property-rename-rebase-utils.js';
+
+const positiveReasonCode = 'typed-property-rename-rebase-admitted';
+const diagnosticsRequiredReasonCode = 'typed-property-rename-rebase-requires-output-diagnostics';
+const gateId = 'project-typed-property-rename-rebase';
+
+function maybeMergeTypedPropertyRenameRebaseFile(file, context, blockedResult, input = {}) {
+  const analysis = analyzeTypedPropertyRenameRebase(file, input);
+  if (!analysis.ok) return undefined;
+  const outputSourceText = analysis.outputSourceText;
+  const evidence = typedPropertyRenameRebaseEvidence(file, analysis);
+  const reasonCodes = uniqueStrings([positiveReasonCode, diagnosticsRequiredReasonCode, ...analysis.reasonCodes]);
+  const core = {
+    kind: 'frontier.lang.jsTsProjectSafeMergeFile',
+    version: 1,
+    sourcePath: file.sourcePath,
+    language: context.language,
+    status: 'merged',
+    operation: 'merged-typed-property-rename-rebase',
+    outputSourceText,
+    outputHash: hashText(outputSourceText),
+    baseHash: hashText(file.baseSourceText),
+    workerHash: hashText(file.workerSourceText),
+    headHash: hashText(file.headSourceText),
+    result: blockedResult,
+    semanticArtifacts: blockedResult?.semanticArtifacts,
+    conflicts: [],
+    admission: {
+      status: 'auto-merge-candidate',
+      action: 'apply-typed-property-rename-rebase',
+      reviewRequired: false,
+      autoApplyCandidate: true,
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false,
+      reasonCodes,
+      conflictKeys: [`typed-property-rename-rebase#${file.sourcePath}#${analysis.ownerName}#${analysis.fromName}#${analysis.toName}`],
+      evidenceIds: [evidence.id]
+    },
+    summary: {
+      conflicts: 0,
+      typedPropertyRenameRebases: 1,
+      typedPropertyRenameRebaseAdmissionEvidence: [evidence],
+      changedExistingDeclarations: blockedResult?.summary?.changedExistingDeclarations,
+      semanticEditOperations: blockedResult?.summary?.semanticEditOperations,
+      semanticEditReplayStatus: blockedResult?.summary?.semanticEditReplayStatus
+    },
+    metadata: {
+      typedPropertyRenameRebaseAdmissions: [evidence],
+      typedPropertyRenameRebase: compactRecord({
+        ownerName: analysis.ownerName,
+        ownerKind: analysis.ownerKind,
+        fromName: analysis.fromName,
+        toName: analysis.toName,
+        typeText: analysis.typeText,
+        workerAddedMembers: analysis.workerAddedMembers.map((member) => member.name),
+        workerAddedDeclarations: analysis.workerAddedDeclarations.map((entry) => entry.names?.[0]).filter(Boolean),
+        rebasedDeclarations: analysis.rebasedDeclarations,
+        diagnosticsRequired: true,
+        autoMergeClaim: false,
+        semanticEquivalenceClaim: false
+      })
+    },
+    conflictKeys: [`source#${file.sourcePath}`]
+  };
+  return { ...core, hash: hashSemanticValue(core) };
+}
+
+function analyzeTypedPropertyRenameRebase(file, input = {}) {
+  const baseSourceText = file.baseSourceText;
+  const workerSourceText = file.workerSourceText ?? baseSourceText;
+  const headSourceText = file.headSourceText ?? baseSourceText;
+  if (!file.sourcePath || typeof baseSourceText !== 'string' || typeof workerSourceText !== 'string' || typeof headSourceText !== 'string') {
+    return rejected('typed-property-rename-rebase-missing-source-text');
+  }
+  const ledgers = projectLedgers(file, input, baseSourceText, workerSourceText, headSourceText);
+  if (!ledgers.ok) return rejected('typed-property-rename-rebase-ledger-unavailable', ledgers.reasonCodes);
+  const rename = findSinglePropertyRename(ledgers);
+  if (!rename.ok) return rename;
+  const assembled = assembleRebasedSource(ledgers, rename.value);
+  if (!assembled.ok) return assembled;
+  return {
+    ok: true,
+    reasonCodes: assembled.reasonCodes,
+    outputSourceText: assembled.outputSourceText,
+    ...rename.value,
+    workerAddedDeclarations: assembled.workerAddedDeclarations,
+    rebasedDeclarations: assembled.rebasedDeclarations
+  };
+}
+
+function projectLedgers(file, input, baseSourceText, workerSourceText, headSourceText) {
+  const context = createMergeContext({
+    id: `typed_property_rename_rebase_${safeId(file.sourcePath)}`,
+    sourcePath: file.sourcePath,
+    language: file.language ?? input.language ?? 'typescript'
+  });
+  const base = scanJsTsTopLevelLedger(baseSourceText, 'base', context);
+  const worker = scanJsTsTopLevelLedger(workerSourceText, 'worker', context);
+  const head = scanJsTsTopLevelLedger(headSourceText, 'head', context);
+  return context.conflicts.length
+    ? { ok: false, reasonCodes: context.conflicts.map((conflict) => conflict.code) }
+    : { ok: true, base, worker, head };
+}
+
+function findSinglePropertyRename(ledgers) {
+  const baseObjects = objectDeclarationsByName(ledgers.base);
+  const workerObjects = objectDeclarationsByName(ledgers.worker);
+  const headObjects = objectDeclarationsByName(ledgers.head);
+  const candidates = [];
+  for (const [name, baseObject] of baseObjects) {
+    const workerObject = workerObjects.get(name);
+    const headObject = headObjects.get(name);
+    if (!workerObject || !headObject) continue;
+    const candidate = propertyRenameCandidate(name, baseObject, workerObject, headObject);
+    if (candidate.ok) candidates.push(candidate.value);
+    else if (candidate.reasonCodes.some((reason) => reason !== 'typed-property-rename-rebase-no-rename')) return candidate;
+  }
+  if (candidates.length !== 1) return rejected(candidates.length ? 'typed-property-rename-rebase-ambiguous' : 'typed-property-rename-rebase-no-rename');
+  return { ok: true, value: candidates[0] };
+}
+
+function propertyRenameCandidate(ownerName, baseObject, workerObject, headObject) {
+  const baseMembers = membersByName(baseObject.members);
+  const workerMembers = membersByName(workerObject.members);
+  const headMembers = membersByName(headObject.members);
+  const removedFromHead = [...baseMembers.keys()].filter((name) => !headMembers.has(name));
+  const addedToHead = [...headMembers.keys()].filter((name) => !baseMembers.has(name));
+  if (removedFromHead.length === 0 && addedToHead.length === 0) return rejected('typed-property-rename-rebase-no-rename');
+  if (removedFromHead.length !== 1 || addedToHead.length !== 1) return rejected('typed-property-rename-rebase-not-single-property');
+  const fromName = removedFromHead[0];
+  const toName = addedToHead[0];
+  const baseMember = baseMembers.get(fromName);
+  const headMember = headMembers.get(toName);
+  if (!workerMembers.has(fromName) || workerMembers.has(toName)) return rejected('typed-property-rename-rebase-worker-shape-changed');
+  if (!renameTypesEqual(baseMember, headMember)) return rejected('typed-property-rename-rebase-type-changed');
+  const stableReasons = stableMemberReasons(baseMembers, workerMembers, headMembers, fromName, toName);
+  if (stableReasons.length) return rejected(stableReasons[0], stableReasons);
+  const workerAddedMembers = workerObject.members.filter((member) => !baseMembers.has(member.name));
+  const outputObjectText = renderObjectDeclaration(headObject, workerAddedMembers);
+  return {
+    ok: true,
+    value: {
+      ownerName,
+      ownerKind: baseObject.kind,
+      fromName,
+      toName,
+      typeText: normalizeTypeText(baseMember.typeText),
+      baseObject,
+      workerObject,
+      headObject,
+      workerAddedMembers,
+      outputObjectText
+    }
+  };
+}
+
+function assembleRebasedSource(ledgers, rename) {
+  const baseByKey = entriesByKey(ledgers.base.entries);
+  const headByKey = entriesByKey(ledgers.head.entries);
+  const outputEntries = [];
+  const workerAddedDeclarations = [];
+  const rebasedDeclarations = [];
+  const reasonCodes = [];
+  for (const workerEntry of ledgers.worker.entries) {
+    if (isTargetObjectEntry(workerEntry, rename)) {
+      outputEntries.push(rename.outputObjectText);
+      continue;
+    }
+    const baseEntry = baseByKey.get(workerEntry.key);
+    const headEntry = headByKey.get(workerEntry.key);
+    if (!baseEntry) {
+      const added = rebaseWorkerEntry(workerEntry, rename);
+      if (!added.ok) return added;
+      workerAddedDeclarations.push(workerEntry);
+      rebasedDeclarations.push(...added.rebasedDeclarations);
+      outputEntries.push(added.text);
+      continue;
+    }
+    if (!headEntry) return rejected('typed-property-rename-rebase-head-removed-declaration');
+    const merged = mergeExistingEntry(baseEntry, workerEntry, headEntry, rename);
+    if (!merged.ok) return merged;
+    rebasedDeclarations.push(...merged.rebasedDeclarations);
+    outputEntries.push(merged.text);
+  }
+  for (const headEntry of ledgers.head.entries) {
+    if (baseByKey.has(headEntry.key) || ledgers.worker.entries.some((entry) => entry.key === headEntry.key)) continue;
+    outputEntries.push(headEntry.text);
+  }
+  reasonCodes.push(`typed-property-rename-rebase-owner:${rename.ownerName}`);
+  return {
+    ok: true,
+    reasonCodes,
+    outputSourceText: `${outputEntries.join('\n')}\n`,
+    workerAddedDeclarations,
+    rebasedDeclarations: uniqueStrings(rebasedDeclarations)
+  };
+}
+
+function mergeExistingEntry(baseEntry, workerEntry, headEntry, rename) {
+  if (isTargetObjectEntry(baseEntry, rename)) return { ok: true, text: rename.outputObjectText, rebasedDeclarations: [] };
+  const headIsRenameOnly = sameStatementText(headEntry.text, rebasePropertyReads(baseEntry.text, rename));
+  if (sameStatementText(workerEntry.text, baseEntry.text)) return { ok: true, text: headEntry.text, rebasedDeclarations: [] };
+  if (sameStatementText(headEntry.text, baseEntry.text) || headIsRenameOnly) {
+    const rebased = rebaseWorkerEntry(workerEntry, rename);
+    if (!rebased.ok) return rebased;
+    return rebased;
+  }
+  return rejected('typed-property-rename-rebase-existing-declaration-conflict');
+}
+
+function rebaseWorkerEntry(entry, rename) {
+  const unsafe = unsafePropertyAccessReasons(entry.text, rename.fromName);
+  if (unsafe.length) return rejected(unsafe[0], unsafe);
+  const text = rebasePropertyReads(entry.text, rename);
+  const remains = stalePropertyAccessReasons(text, rename.fromName);
+  if (remains.length) return rejected(remains[0], remains);
+  return {
+    ok: true,
+    text,
+    rebasedDeclarations: sameStatementText(text, entry.text) ? [] : [entry.names?.[0] ?? entry.key]
+  };
+}
+
+function objectDeclarationsByName(ledger) {
+  const result = new Map();
+  for (const entry of ledger.entries) {
+    const info = entry.declarationInfo;
+    if (!info || !['interface', 'type'].includes(info.declarationKind) || info.names.length !== 1) continue;
+    const object = parseObjectDeclaration(entry);
+    if (object) result.set(info.names[0], object);
+  }
+  return result;
+}
+
+function parseObjectDeclaration(entry) {
+  const kind = entry.declarationInfo.declarationKind;
+  const text = entry.text;
+  const open = text.indexOf('{');
+  const close = text.lastIndexOf('}');
+  if (open < 0 || close <= open) return undefined;
+  if (kind === 'type' && !/=\s*\{/.test(text.slice(0, open + 1))) return undefined;
+  const body = text.slice(open + 1, close);
+  const members = parseObjectMembers(body);
+  if (!members.ok) return undefined;
+  return { entry, kind, name: entry.declarationInfo.names[0], text, open, close, body, members: members.members };
+}
+
+function parseObjectMembers(body) {
+  const members = [];
+  let offset = 0;
+  for (const line of body.split('\n')) {
+    const start = offset;
+    offset += line.length + 1;
+    if (!line.trim()) continue;
+    const match = line.match(/^(\s*)(?:readonly\s+)?([A-Za-z_$][\w$]*)(\?)?\s*:\s*([^;,]+)\s*[;,]?\s*$/);
+    if (!match) return { ok: false };
+    members.push({
+      name: match[2],
+      optional: Boolean(match[3]),
+      typeText: match[4].trim(),
+      text: line,
+      indent: match[1],
+      start,
+      end: start + line.length
+    });
+  }
+  return { ok: true, members };
+}
+
+function renderObjectDeclaration(object, addedMembers) {
+  if (!addedMembers.length) return object.entry.text;
+  const insert = addedMembers.map((member) => member.text).join('\n');
+  const beforeClose = object.text.slice(0, object.close);
+  const afterClose = object.text.slice(object.close);
+  const needsNewline = beforeClose.endsWith('\n') ? '' : '\n';
+  return `${beforeClose}${needsNewline}${insert}\n${afterClose}`;
+}
+
+function stableMemberReasons(baseMembers, workerMembers, headMembers, fromName, toName) {
+  const reasons = [];
+  for (const [name, baseMember] of baseMembers) {
+    if (name === fromName) continue;
+    const workerMember = workerMembers.get(name);
+    const headMember = headMembers.get(name);
+    if (!workerMember || !headMember) reasons.push('typed-property-rename-rebase-stable-member-missing');
+    else if (!renameTypesEqual(baseMember, workerMember) || !renameTypesEqual(baseMember, headMember)) {
+      reasons.push('typed-property-rename-rebase-stable-member-changed');
+    }
+  }
+  for (const [name] of headMembers) {
+    if (!baseMembers.has(name) && name !== toName) reasons.push('typed-property-rename-rebase-head-added-extra-property');
+  }
+  return uniqueStrings(reasons);
+}
+
+function rebasePropertyReads(text, rename) {
+  const property = escapeRegExp(rename.fromName);
+  return String(text ?? '').replace(new RegExp(`(\\?\\.|\\.)${property}\\b`, 'g'), `$1${rename.toName}`);
+}
+function isTargetObjectEntry(entry, rename) { return entry.key === rename.baseObject.entry.key; }
+
+export { maybeMergeTypedPropertyRenameRebaseFile };

package/dist/js-ts-safe-project-merge-unsupported-surfaces.js

@@ -0,0 +1,319 @@
+import { compactRecord } from './js-ts-safe-merge-context.js';
+import { maskNonCode } from './js-ts-semantic-scope-use-def-scan.js';
+
+const DecoratorRuntimeExecutionRoute = Object.freeze({
+  routeId: 'prove-decorator-runtime-execution-equivalence',
+  routeLane: 'decorator-runtime-boundaries',
+  routeNext: 'supply-decorator-runtime-execution-proof',
+  failClosed: true,
+  blocksSemanticEquivalence: true
+});
+const GeneratorRuntimeProtocolRoute = Object.freeze({
+  routeId: 'prove-generator-runtime-protocol-equivalence',
+  routeLane: 'generator-runtime-boundaries',
+  routeNext: 'supply-generator-runtime-protocol-proof',
+  failClosed: true,
+  blocksSemanticEquivalence: true
+});
+const AsyncGeneratorRuntimeProtocolRoute = Object.freeze({
+  routeId: 'prove-async-generator-runtime-protocol-equivalence',
+  routeLane: 'generator-runtime-boundaries',
+  routeNext: 'supply-async-generator-runtime-protocol-proof',
+  failClosed: true,
+  blocksSemanticEquivalence: true
+});
+const ClassPrivateAccessorRuntimeRoute = Object.freeze({ routeId: 'prove-class-private-accessor-runtime-equivalence', routeLane: 'class-private-accessor-runtime-boundaries', routeNext: 'supply-class-private-accessor-runtime-proof', failClosed: true, blocksSemanticEquivalence: true });
+
+const surfaceChecks = [
+  { kind: 'explicit-resource-management', pattern: /\b(?:await\s+)?using\s+[A-Za-z_$][\w$]*\s*=/g },
+  { kind: 'decorator', pattern: /^[ \t]*@[A-Za-z_$][\w$]*(?:[.(\s]|$)/gm, startOffset: (match) => match[0].indexOf('@') },
+  { kind: 'accessor-field', pattern: /\baccessor\s+#?[A-Za-z_$][\w$]*/g },
+  { kind: 'private-class-element', pattern: /#[A-Za-z_$][\w$]*/g },
+  { kind: 'class-static-block', pattern: /\bstatic\s*\{/g },
+  { kind: 'enum-declaration', pattern: /\b(?:const\s+)?enum\s+[A-Za-z_$][\w$]*\s*\{/g },
+  { kind: 'namespace-declaration', pattern: /\b(?:namespace|module)\s+[A-Za-z_$][\w$]*(?:\s*\.\s*[A-Za-z_$][\w$]*)*\s*\{/g },
+  { kind: 'ambient-module-declaration', pattern: /\bdeclare\s+module\s+(?:(?:['"][^'"\n]+['"]\s*)|(?:[A-Za-z_$][\w$]*\s*))?\{/g },
+  { kind: 'global-augmentation', pattern: /\bdeclare\s+global\s*\{/g },
+  { kind: 'export-assignment', pattern: /\bexport\s*=\s*[A-Za-z_$][\w$]*/g },
+  { kind: 'import-meta-expression', pattern: /\bimport\s*\.\s*meta\b/g },
+  { kind: 'satisfies-expression', pattern: /(?:[A-Za-z_$][\w$.)\]]|\})\s+satisfies\b/g },
+  { kind: 'as-const-assertion', pattern: /\bas\s+const\b/g },
+  { kind: 'const-type-parameter', pattern: /<\s*const\s+[A-Za-z_$][\w$]*/g },
+  { kind: 'async-generator-function', pattern: /\basync\s+function\s*\*\s*(?:[A-Za-z_$][\w$]*\s*)?\(/g },
+  { kind: 'generator-function', pattern: /(?<!async\s)\bfunction\s*\*\s*(?:[A-Za-z_$][\w$]*\s*)?\(/g }
+];
+
+const focusedSurfaceReviewEntries = [
+  ['explicit-resource-management', 'explicit-resource-management-acquisition-disposal-order-evidence', 'control-flow-effect-graph', 'using and await using acquisition plus reverse lexical disposal-order evidence can bound ordering.', 'resource-management-disposal-effect-equivalence-not-claimed', 'Disposal side effects and executable effect equivalence remain unproved.', { routeId: 'prove-resource-management-disposal-effect-equivalence', routeLane: 'control-flow-effect-graph-runtime-resource-management', routeNext: 'supply-resource-management-disposal-proof', failClosed: true, blocksSemanticEquivalence: true }],
+  ['decorator', 'typescript-decorator-static-metadata-evidence', 'type-public-api-graph', 'TypeScript compiler-backed decorator target and expression metadata can bound static shape.', 'decorator-execution-equivalence-not-claimed', 'Decorator execution, side effects, and runtime ordering remain unproved.', DecoratorRuntimeExecutionRoute],
+  ['accessor-field', 'typescript-accessor-field-static-shape-evidence', 'type-public-api-graph', 'TypeScript compiler-backed accessor-field static shape records and proof hashes can bound public shape.', 'accessor-field-runtime-equivalence-not-claimed', 'Accessor initialization and getter/setter runtime behavior remain unproved.', ClassPrivateAccessorRuntimeRoute],
+  ['private-class-element', 'typescript-private-class-member-static-shape-evidence', 'type-public-api-graph', 'TypeScript compiler-backed private class member static shape records and proof hashes can bound class shape.', 'private-class-member-runtime-equivalence-not-claimed', 'Private member initialization, access, and runtime behavior remain unproved.', ClassPrivateAccessorRuntimeRoute],
+  ['class-static-block', 'class-static-block-initialization-order-evidence', 'control-flow-effect-graph', 'Class static block initialization-order evidence can bound public runtime-region ordering.', 'class-static-block-executable-runtime-equivalence-not-claimed', 'Executable static initialization side effects and runtime equivalence remain unproved.'],
+  ['enum-declaration', 'typescript-enum-runtime-shape-evidence', 'type-public-api-graph', 'TypeScript compiler-backed enum runtime-shape, member-value, and source-bound computed-value proof evidence can bound emitted enum shape.', 'enum-runtime-evaluation-equivalence-not-claimed', 'Broad executable enum runtime evaluation remains unproved beyond source-bound computed-value traces.'],
+  ['namespace-declaration', 'typescript-namespace-static-module-shape-evidence', 'module-export-import-graph', 'Namespace static module-shape records and proof hashes can bound declaration shape.', 'namespace-runtime-evaluation-equivalence-not-claimed', 'Namespace runtime evaluation and merging semantics remain unproved.'],
+  ['ambient-module-declaration', 'typescript-ambient-module-static-shape-evidence', 'module-export-import-graph', 'Ambient module static shape records and proof hashes can bound declaration shape.', 'ambient-module-compatibility-equivalence-not-claimed', 'Ambient module compatibility across external consumers remains unproved.'],
+  ['global-augmentation', 'typescript-global-augmentation-static-shape-evidence', 'module-export-import-graph', 'Global augmentation static shape records can bound declared global surface changes.', 'global-augmentation-compatibility-equivalence-not-claimed', 'Global compatibility and host/runtime interaction remain unproved.', { routeId: 'prove-global-augmentation-compatibility', routeLane: 'module-runtime-global-augmentation', routeNext: 'supply-source-bound-global-augmentation-compatibility-proof', failClosed: true, blocksSemanticEquivalence: true }],
+  ['export-assignment', 'typescript-export-assignment-static-module-shape-evidence', 'module-export-import-graph', 'Export-assignment static module-shape records can bound CommonJS-style export shape.', 'export-assignment-runtime-interop-equivalence-not-claimed', 'CommonJS/ESM runtime interop behavior remains unproved.'],
+  ['import-meta-expression', 'import-meta-host-context-member-evidence', 'control-flow-effect-graph', 'Static import.meta member and host-context evidence can bound observed host-dependent reads.', 'import-meta-host-context-equivalence-not-claimed', 'Host runtime resolution and executable import.meta equivalence remain unproved.'],
+  ['satisfies-expression', 'typescript-satisfies-static-inference-syntax-evidence', 'type-public-api-graph', 'Static compiler-backed inference syntax evidence can bound satisfies-expression syntax participation.', 'satisfies-inference-semantics-equivalence-not-claimed', 'Broad inference semantics and executable behavior remain unproved.'],
+  ['as-const-assertion', 'typescript-as-const-static-inference-syntax-evidence', 'type-public-api-graph', 'Static compiler-backed inference syntax evidence can bound as const assertion participation.', 'as-const-inference-semantics-equivalence-not-claimed', 'Broad literal inference semantics and executable behavior remain unproved.'],
+  ['const-type-parameter', 'typescript-const-type-parameter-static-inference-syntax-evidence', 'type-public-api-graph', 'Static compiler-backed inference syntax evidence can bound const type-parameter participation.', 'const-type-parameter-inference-semantics-equivalence-not-claimed', 'Broad generic inference semantics and executable behavior remain unproved.'],
+  ['async-generator-function', 'async-generator-await-yield-order-evidence', 'control-flow-effect-graph', 'Async generator await/yield order evidence can bound suspension ordering.', 'async-generator-runtime-protocol-equivalence-not-claimed', 'Async iterator protocol behavior, cancellation, backpressure, and executable scheduling remain unproved.', AsyncGeneratorRuntimeProtocolRoute],
+  ['generator-function', 'generator-yield-order-evidence', 'control-flow-effect-graph', 'Generator yield order evidence can bound iterator suspension ordering.', 'generator-runtime-protocol-equivalence-not-claimed', 'Iterator protocol behavior, delegation, cancellation, and executable scheduling remain unproved.', GeneratorRuntimeProtocolRoute],
+  ['top-level-await', 'top-level-await-module-runtime-scope-evidence', 'control-flow-effect-graph', 'Module-scope top-level await runtime-scope evidence can bound await suspension-order participation.', 'top-level-await-executable-suspension-order-equivalence-not-claimed', 'Executable suspension order and host module-loading behavior remain unproved.']
+];
+
+const focusedSurfaceReviews = Object.freeze(Object.fromEntries(
+  focusedSurfaceReviewEntries.map(([kind, evidenceKind, evidenceScope, evidenceSummary, proofGapCode, proofGapSummary, proofGapRoute]) => [
+    kind,
+    focusedSurfaceReview(evidenceKind, evidenceScope, evidenceSummary, proofGapCode, proofGapSummary, proofGapRoute)
+  ])
+));
+
+const surfaceEvidenceLimit = 50;
+
+function unsupportedJsTsSurfaceEvidence(id, files = [], fileResults = []) {
+  const surfaces = unsupportedSurfaceRecords(files, fileResults);
+  return evidenceRecord({
+    id,
+    suffix: 'unsupported_js_ts_surface_review',
+    level: 'unsupported-js-ts-surface-review',
+    status: 'unknown',
+    scope: 'project',
+    claimKind: 'unsupported-surface-upper-bound',
+    summary: surfaces.length
+      ? `Observed ${surfaces.length} unsupported or focused-evidence-only JS/TS surface marker(s); remaining proof gaps must be closed before any broad semantic equivalence claim.`
+      : 'Unsupported or focused-evidence-only JS/TS semantic surfaces require explicit external evidence before any broad semantic equivalence claim.',
+    metadata: {
+      partialMatrixRowsRemain: true,
+      requiresHumanOrExternalProof: true,
+      missingSignal: 'unsupported-js-ts-surface-proof-not-available',
+      nextAction: 'Supply the remaining focused unsupported-surface proof gaps or keep semanticEquivalenceClaim false.',
+      executableSemanticEquivalence: 'not-claimed',
+      surfaceReviewClaim: 'bounded-evidence-only',
+      surfaceEvidenceStatus: surfaces.length ? 'observed' : 'not-observed-by-lightweight-scan',
+      observedUnsupportedSurfaces: uniqueStrings(surfaces.map((surface) => surface.observedSurfaceKind)),
+      surfaceFocusedEvidenceKinds: uniqueStrings(surfaces.map((surface) => surface.boundedEvidence?.kind)),
+      surfaceProofGapCodes: uniqueStrings(surfaces.map((surface) => surface.remainingProofGap?.code)),
+      surfaceProofGapRouteIds: nonEmptyArray(uniqueStrings(surfaces.map((surface) => surface.remainingProofGap?.routeId))),
+      surfaceProofGapRouteLanes: nonEmptyArray(uniqueStrings(surfaces.map((surface) => surface.remainingProofGap?.routeLane))),
+      surfaceReasonCodes: uniqueStrings(surfaces.map((surface) => surface.reasonCode)),
+      surfaceEvidenceCount: surfaces.length || undefined,
+      surfaceEvidenceLimit: surfaces.length ? surfaceEvidenceLimit : undefined,
+      surfaceEvidenceTruncated: surfaces.length > surfaceEvidenceLimit || undefined,
+      surfaceEvidence: surfaces.length ? surfaces.slice(0, surfaceEvidenceLimit) : undefined
+    }
+  });
+}
+
+function unsupportedSurfaceRecords(files, fileResults) {
+  const sources = [...sourceEntries(files), ...resultEntries(fileResults)];
+  const seen = new Set();
+  return sources.flatMap((entry) => unsupportedSurfaceRecordsForEntry(entry, seen));
+}
+
+function unsupportedSurfaceRecordsForEntry(entry, seen) {
+  const masked = maskNonCode(entry.sourceText).code;
+  const lineStarts = lineStartsFor(entry.sourceText);
+  return [
+    ...surfaceChecks.flatMap((check) => {
+      check.pattern.lastIndex = 0;
+      return [...masked.matchAll(check.pattern)].flatMap((match) => {
+        const start = match.index + Math.max(0, Number(check.startOffset?.(match) ?? 0));
+        const end = match.index + match[0].length;
+        const key = `${entry.sourcePath}\0${entry.stage}\0${check.kind}\0${start}\0${end}`;
+        if (seen.has(key)) return [];
+        seen.add(key);
+        const location = lineColumnAt(lineStarts, start);
+        return [compactRecord({
+          sourcePath: entry.sourcePath,
+          stage: entry.stage,
+          kind: check.kind,
+          ...focusedSurfaceRecordFields(check.kind),
+          start,
+          end,
+          line: location.line,
+          column: location.column,
+          excerpt: excerptFor(entry.sourceText, start, end)
+        })];
+      });
+    }),
+    ...topLevelAwaitSurfaceRecords(entry, masked, lineStarts, seen)
+  ];
+}
+
+function topLevelAwaitSurfaceRecords(entry, masked, lineStarts, seen) {
+  const records = [];
+  let offset = 0;
+  let braceDepth = 0;
+  for (const line of masked.split(/(?<=\n)/)) {
+    const depthBeforeLine = braceDepth;
+    if (depthBeforeLine === 0) {
+      const awaitMatch = topLevelAwaitMatch(line);
+      if (awaitMatch) {
+        const record = unsupportedSurfaceRecord(
+          entry,
+          seen,
+          lineStarts,
+          'top-level-await',
+          offset + awaitMatch.index,
+          offset + awaitMatch.index + awaitMatch.length
+        );
+        if (record) records.push(record);
+      }
+    }
+    braceDepth = nextBraceDepth(braceDepth, line);
+    offset += line.length;
+  }
+  return records;
+}
+
+function topLevelAwaitMatch(line) {
+  const match = /(?:^|[^\w$])await\b/.exec(line);
+  if (!match) return undefined;
+  const index = match.index + match[0].indexOf('await');
+  const before = line.slice(0, index).trim();
+  if (before.includes('=>')) return undefined;
+  if (!before || /^(?:export\s+)?(?:const|let|var)\s+[A-Za-z_$][\w$]*(?:\s*:\s*[^=]+)?\s*=$/.test(before) || /^export\s+default$/.test(before)) {
+    return { index, length: 'await'.length };
+  }
+  return undefined;
+}
+
+function nextBraceDepth(depth, line) {
+  let current = depth;
+  for (const char of line) {
+    if (char === '{') current += 1;
+    else if (char === '}') current = Math.max(0, current - 1);
+  }
+  return current;
+}
+
+function unsupportedSurfaceRecord(entry, seen, lineStarts, kind, start, end) {
+  const key = `${entry.sourcePath}\0${entry.stage}\0${kind}\0${start}\0${end}`;
+  if (seen.has(key)) return undefined;
+  seen.add(key);
+  const location = lineColumnAt(lineStarts, start);
+  return compactRecord({
+    sourcePath: entry.sourcePath,
+    stage: entry.stage,
+    kind,
+    ...focusedSurfaceRecordFields(kind),
+    start,
+    end,
+    line: location.line,
+    column: location.column,
+    excerpt: excerptFor(entry.sourceText, start, end)
+  });
+}
+
+function focusedSurfaceReview(evidenceKind, evidenceScope, evidenceSummary, proofGapCode, proofGapSummary, proofGapRoute = undefined) {
+  return {
+    boundedEvidence: {
+      kind: evidenceKind,
+      status: 'bounded-evidence-available',
+      scope: evidenceScope,
+      summary: evidenceSummary
+    },
+    remainingProofGap: compactRecord({
+      code: proofGapCode,
+      status: 'not-claimed',
+      summary: proofGapSummary,
+      ...(proofGapRoute ?? {})
+    })
+  };
+}
+
+function focusedSurfaceRecordFields(kind) {
+  const review = focusedSurfaceReviews[kind] ?? focusedSurfaceReview(
+    'unsupported-js-ts-surface-focused-evidence-unmapped',
+    'unsupported-js-ts-surface-review',
+    'No focused evidence descriptor is mapped for this observed surface.',
+    'unsupported-js-ts-surface-proof-gap-not-claimed',
+    'The remaining proof gap is unmapped and semantic equivalence remains unproved.'
+  );
+  return {
+    observedSurfaceKind: kind,
+    boundedEvidence: review.boundedEvidence,
+    remainingProofGap: {
+      ...review.remainingProofGap,
+      proofClaim: false,
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false
+    },
+    proofGapCode: review.remainingProofGap.code,
+    reasonCode: review.remainingProofGap.code
+  };
+}
+
+function sourceEntries(files = []) {
+  return files.flatMap((file) => [
+    sourceEntry(file, 'base', file.baseSourceText),
+    sourceEntry(file, 'worker', file.workerSourceText),
+    sourceEntry(file, 'head', file.headSourceText)
+  ].filter(Boolean));
+}
+
+function resultEntries(fileResults = []) {
+  return fileResults.map((file) => sourceEntry(file, 'output', file.outputSourceText)).filter(Boolean);
+}
+
+function sourceEntry(file, stage, sourceText) {
+  return typeof sourceText === 'string'
+    ? { sourcePath: file.sourcePath, stage, sourceText }
+    : undefined;
+}
+
+function lineStartsFor(sourceText) {
+  const starts = [0];
+  for (let index = 0; index < sourceText.length; index += 1) {
+    if (sourceText[index] === '\n') starts.push(index + 1);
+  }
+  return starts;
+}
+
+function lineColumnAt(lineStarts, offset) {
+  let low = 0;
+  let high = lineStarts.length - 1;
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2);
+    if (lineStarts[mid] <= offset) low = mid + 1;
+    else high = mid - 1;
+  }
+  const lineIndex = Math.max(0, high);
+  return { line: lineIndex + 1, column: offset - lineStarts[lineIndex] + 1 };
+}
+
+function excerptFor(sourceText, start, end) {
+  const text = sourceText.slice(start, Math.min(sourceText.length, Math.max(end, start + 80)));
+  return text.replace(/\s+/g, ' ').trim() || undefined;
+}
+
+function evidenceRecord(input) {
+  return {
+    id: `${input.id}_proof_${input.suffix}`,
+    kind: 'js-ts-project-merge-proof-evidence',
+    level: input.level,
+    status: input.status,
+    scope: input.scope,
+    claimKind: input.claimKind ?? 'evidence',
+    evidenceOnly: true,
+    proofClaim: false,
+    autoMergeClaim: false,
+    semanticEquivalenceClaim: false,
+    summary: input.summary,
+    metadata: compactRecord({
+      ...(input.metadata ?? {}),
+      proofClaim: false,
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false
+    })
+  };
+}
+
+function uniqueStrings(values) {
+  return [...new Set((values ?? []).filter((value) => typeof value === 'string' && value.length > 0))];
+}
+function nonEmptyArray(value) { return Array.isArray(value) && value.length ? value : undefined; }
+
+export { unsupportedJsTsSurfaceEvidence };