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

package/dist/js-ts-safe-merge.js

@@ -12,6 +12,9 @@ import { createJsTsSafeMergeSemanticArtifacts } from './js-ts-safe-merge-semanti
 
 export { JsTsSafeMergeConflictCodes, JsTsSafeMergeGateIds, JsTsSafeMergeStatuses };
 
+const mergedOutputSyntaxDiagnosticCode = 'merged-output-syntax-diagnostic';
+const mergedOutputSyntaxDiagnosticsUnavailableCode = 'merged-output-syntax-diagnostics-unavailable';
+
 export function safeMergeJsTsImportsAndDeclarations(input = {}) {
   const context = createMergeContext(input);
   const baseSourceText = input.baseSourceText;
@@ -60,6 +63,7 @@ export function safeMergeJsTsImportsAndDeclarations(input = {}) {
   const mergedSourceText = applySourceMergePlan(headSourceText, mergePlan);
   const merged = scanJsTsTopLevelLedger(mergedSourceText, 'merged', context);
   if (!context.conflicts.length) validateLedgerUniqueness(merged, context);
+  if (!context.conflicts.length) validateMergedOutputSyntaxGate(input, context);
   if (context.conflicts.length) return blockedResult(context, { base, worker, head, merged });
 
   const result = {
@@ -179,3 +183,135 @@ function hasLedgerSpan(entry) {
   const hasLines = Number.isFinite(span.startLine) && Number.isFinite(span.endLine);
   return hasOffsets || hasLines;
 }
+
+function validateMergedOutputSyntaxGate(input, context) {
+  const diagnostics = normalizeMergedOutputSyntaxDiagnostics(input, context.sourcePath);
+  if (!diagnostics) {
+    if (requiresMergedOutputSyntaxDiagnostics(input)) {
+      addConflict(context, {
+        code: mergedOutputSyntaxDiagnosticsUnavailableCode,
+        gateId: JsTsSafeMergeGateIds.parseLedger,
+        side: 'merged',
+        message: 'Merged JS/TS output syntax diagnostics are required but were not provided.',
+        details: { required: true, diagnosticSource: 'missing' }
+      });
+    }
+    return;
+  }
+  for (const diagnostic of diagnostics) {
+    if (diagnostic.severity !== 'error' || !isSyntaxDiagnostic(diagnostic)) continue;
+    addConflict(context, {
+      code: mergedOutputSyntaxDiagnosticCode,
+      gateId: JsTsSafeMergeGateIds.parseLedger,
+      side: 'merged',
+      message: `Merged JS/TS output syntax diagnostic ${diagnostic.code}: ${diagnostic.message}`,
+      details: { diagnostic }
+    });
+  }
+}
+
+function requiresMergedOutputSyntaxDiagnostics(input) {
+  return input.requireMergedOutputSyntaxDiagnostics === true
+    || input.requireOutputSyntaxDiagnostics === true
+    || input.requireOutputSyntaxGate === true
+    || input.requireSyntaxGate === true;
+}
+
+function normalizeMergedOutputSyntaxDiagnostics(input, sourcePath) {
+  const values = [
+    input.mergedOutputSyntaxDiagnostics,
+    input.outputSyntaxDiagnostics,
+    input.syntaxDiagnostics?.merged,
+    input.syntaxDiagnostics?.output,
+    input.outputDiagnostics
+  ];
+  if (!values.some((value) => value !== undefined)) return undefined;
+  const expectedPath = normalizeDiagnosticPath(sourcePath);
+  const diagnostics = values
+    .flatMap((value) => normalizeDiagnosticList(value))
+    .filter((diagnostic) => {
+      const diagnosticPath = normalizeDiagnosticPath(diagnostic.sourcePath);
+      return !expectedPath || !diagnosticPath || expectedPath === diagnosticPath;
+    });
+  return diagnostics;
+}
+
+function normalizeDiagnosticList(value) {
+  if (value === undefined) return [];
+  const values = Array.isArray(value) ? value : [value].filter(Boolean);
+  return values.map((diagnostic, index) => compactRecord({
+    id: diagnostic.id ?? `diagnostic_${index + 1}`,
+    source: diagnostic.source ?? diagnostic.tool ?? diagnostic.name,
+    code: String(diagnostic.code ?? diagnostic.diagnosticCode ?? diagnostic.name ?? 'syntax-diagnostic'),
+    severity: normalizeDiagnosticSeverity(diagnostic.severity ?? diagnostic.category),
+    message: String(diagnostic.message ?? diagnostic.messageText ?? ''),
+    sourcePath: normalizeDiagnosticPath(diagnostic.sourcePath ?? diagnostic.fileName ?? diagnostic.file?.fileName),
+    start: numberOrUndefined(diagnostic.start),
+    end: numberOrUndefined(diagnostic.end),
+    line: numberOrUndefined(diagnostic.line),
+    column: numberOrUndefined(diagnostic.column),
+    phase: normalizeDiagnosticPhase(diagnostic.phase ?? diagnostic.diagnosticPhase ?? diagnostic.kind ?? diagnostic.type),
+    syntax: diagnostic.syntax === true ? true : undefined
+  }));
+}
+
+function isSyntaxDiagnostic(diagnostic) {
+  if (diagnostic.syntax === true) return true;
+  const text = [
+    diagnostic.phase,
+    diagnostic.kind,
+    diagnostic.category,
+    diagnostic.type,
+    diagnostic.source,
+    diagnostic.ruleId,
+    diagnostic.name,
+    diagnostic.code
+  ].filter(Boolean).join(' ').toLowerCase();
+  return /\bsyntax\b|\bsyntactic\b|\bparse\b|\bparser\b/.test(text) || isTypeScriptSyntaxDiagnosticCode(diagnostic.code);
+}
+
+function isTypeScriptSyntaxDiagnosticCode(code) {
+  const match = /^TS(\d+)$/.exec(String(code ?? ''));
+  if (!match) return false;
+  const numeric = Number(match[1]);
+  return numeric >= 1000 && numeric < 2000;
+}
+
+function normalizeDiagnosticSeverity(value) {
+  if (typeof value === 'string') {
+    const lowered = value.toLowerCase();
+    if (lowered.includes('error')) return 'error';
+    if (lowered.includes('warn')) return 'warning';
+    if (lowered.includes('suggest')) return 'suggestion';
+    if (lowered.includes('message')) return 'message';
+  }
+  if (value === 1) return 'error';
+  if (value === 0) return 'warning';
+  if (value === 2) return 'suggestion';
+  if (value === 3) return 'message';
+  return 'error';
+}
+
+function normalizeDiagnosticPhase(value) {
+  if (typeof value !== 'string') return undefined;
+  const lowered = value.toLowerCase();
+  if (lowered.includes('syntax') || lowered.includes('syntactic') || lowered.includes('parse')) return 'syntax';
+  if (lowered.includes('semantic') || lowered.includes('type')) return 'semantic';
+  return value;
+}
+
+function normalizeDiagnosticPath(value) {
+  if (value === undefined || value === null) return undefined;
+  const raw = String(value).replace(/\\/g, '/').replace(/\/+/g, '/');
+  const parts = [];
+  for (const part of raw.split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..' && parts.length) parts.pop();
+    else if (part !== '..') parts.push(part);
+  }
+  return parts.join('/');
+}
+
+function numberOrUndefined(value) {
+  return Number.isFinite(value) ? value : undefined;
+}

package/dist/js-ts-safe-project-merge-admission-routes.js

@@ -0,0 +1,216 @@
+const exactAdmissionRouteSpecs = Object.freeze({
+  'js-ts-project-symbol-rename-admission': routeSpec('apply-cross-file-symbol-rename', 'cross-file-symbol-rename', 'apply-project-symbol-rename'),
+  'js-ts-project-symbol-move-admission': routeSpec('apply-symbol-move-between-files', 'symbol-move-between-files', 'apply-project-symbol-move'),
+  'js-ts-project-split-merge-admission': routeSpec('apply-project-split-merge', 'split-merge-modules-classes', 'apply-project-split-merge')
+});
+
+const classificationRouteSpecs = Object.freeze({
+  'cross-file-symbol-rename': routeSpec('review-cross-file-symbol-rename', 'cross-file-symbol-rename', 'supply-import-export-rewrite-diagnostics-and-declarations'),
+  'exported-symbol-move': routeSpec('review-symbol-move-between-files', 'symbol-move-between-files', 'supply-symbol-lineage-rewrite-diagnostics-and-declarations'),
+  'imported-symbol-move': routeSpec('review-symbol-move-between-files', 'symbol-move-between-files', 'supply-symbol-lineage-rewrite-diagnostics-and-declarations'),
+  'file-move-rename': routeSpec('review-file-move-rename', 'file-move-rename', 'supply-path-lineage-rewrite-diagnostics-and-declarations'),
+  'module-split': routeSpec('review-project-split-merge', 'split-merge-modules-classes', 'supply-structural-partition-diagnostics-and-declarations'),
+  'module-merge': routeSpec('review-project-split-merge', 'split-merge-modules-classes', 'supply-structural-partition-diagnostics-and-declarations'),
+  'class-split': routeSpec('review-project-split-merge', 'split-merge-modules-classes', 'supply-structural-partition-diagnostics-and-declarations'),
+  'class-merge': routeSpec('review-project-split-merge', 'split-merge-modules-classes', 'supply-structural-partition-diagnostics-and-declarations')
+});
+
+function createProjectAdmissionRoutes(input = {}) {
+  return uniqueProjectAdmissionRoutes([
+    ...(input.fileResults ?? []).flatMap(fileAdmissionRoutes),
+    ...(input.missingEvidence ?? []).map(projectAdmissionRouteFromMissingEvidence),
+    ...(input.conflicts ?? []).map(projectAdmissionRouteFromConflict)
+  ].filter(Boolean));
+}
+
+function projectAdmissionRouteSummary(routes = []) {
+  return compactRecord({
+    total: routes.length,
+    byKind: countField(routes, 'routeKind'),
+    byAction: countField(routes, 'action'),
+    byLane: countField(routes, 'routeLane'),
+    byStatus: countField(routes, 'status'),
+    byRoute: countField(routes, 'routeId'),
+    nextRoute: routes.find((route) => route.status !== 'passed') ?? routes[0]
+  });
+}
+
+function projectAdmissionRouteFromExactAdmission(admission, options = {}) {
+  const spec = exactAdmissionRouteSpecs[admission?.kind] ?? routeSpec(`apply-${safeToken(admission?.kind ?? 'project-admission')}`, 'project-admission', options.action ?? 'apply-project');
+  return routeRecord({
+    routeId: spec.routeId,
+    routeKind: 'apply',
+    routeLane: spec.routeLane,
+    routeNext: spec.routeNext,
+    action: 'apply',
+    status: 'passed',
+    source: 'file-admission',
+    subjectKind: admission?.kind,
+    branch: admission?.branch,
+    sourcePath: admission?.sourcePath,
+    sourcePaths: admission?.details?.sourcePaths,
+    evidenceId: admission?.id,
+    conflictKey: admission?.details?.conflictKey,
+    reasonCodes: admission?.details?.reasonCode ? [admission.details.reasonCode] : [],
+    requiredEvidence: admission?.details?.requiredEvidence,
+    presentEvidence: admission?.details?.presentRequiredEvidence,
+    details: admission?.details
+  });
+}
+
+function projectAdmissionRouteFromClassification(classification, options = {}) {
+  const details = classification?.details ?? {};
+  const spec = classificationRouteSpecs[classification?.kind] ?? routeSpec(`review-${safeToken(classification?.kind ?? classification?.code ?? 'project-admission')}`, 'project-admission', 'review-structural-admission-evidence');
+  const explicitRouteId = details.routeId ?? details.proofRouteId;
+  const staleRouteId = details.structuralProofRouteId;
+  const stale = details.staleStructuralEditProof === true || details.otherBranchChanged === true;
+  return routeRecord({
+    routeId: options.routeId ?? explicitRouteId ?? staleRouteId ?? spec.routeId,
+    routeKind: stale ? 'rebase' : 'review',
+    routeLane: stale ? 'split-merge-modules-classes' : details.routeLane ?? spec.routeLane,
+    routeNext: stale ? 'prove-current-branch-output-before-admission' : details.routeNext ?? spec.routeNext,
+    action: stale ? 'rebase' : 'review',
+    status: options.status ?? 'blocked',
+    source: options.source ?? 'classification',
+    subjectKind: classification?.kind,
+    branch: classification?.branch,
+    sourcePath: options.sourcePath,
+    sourcePaths: classification?.sourcePaths,
+    conflictKey: details.conflictKey,
+    reasonCodes: uniqueStrings([classification?.code, details.reasonCode, ...(details.missingRequiredEvidence ?? [])]),
+    requiredEvidence: details.requiredEvidence,
+    missingEvidence: details.missingRequiredEvidence,
+    details
+  });
+}
+
+function projectAdmissionRouteFromConflict(conflict) {
+  const details = conflict?.details ?? {};
+  const classification = {
+    kind: classificationKindFromConflict(conflict, details),
+    code: conflict?.code,
+    branch: details.branch,
+    sourcePaths: uniqueStrings([...(details.sourcePaths ?? []), details.fromSourcePath, details.toSourcePath, details.exportSourcePath, details.importSourcePath, conflict?.sourcePath]),
+    details: { ...details, reasonCode: details.reasonCode ?? conflict?.code }
+  };
+  const route = projectAdmissionRouteFromClassification(classification, {
+    source: 'conflict',
+    sourcePath: conflict?.sourcePath,
+    status: conflict?.severity === 'error' ? 'failed' : 'blocked'
+  });
+  return route?.subjectKind === 'project-admission' && !structuralConflictCode(conflict?.code) && !details.routeId ? undefined : route;
+}
+
+function projectAdmissionRouteFromMissingEvidence(item) {
+  const route = item?.route ?? {};
+  const routeId = item?.routeId ?? route.id;
+  if (!routeId) return undefined;
+  const action = normalizedRouteAction(item?.action);
+  return routeRecord({
+    routeId,
+    routeKind: action,
+    routeLane: item?.routeLane ?? route.lane,
+    routeNext: item?.routeNext ?? route.next,
+    action,
+    status: item?.status ?? 'missing',
+    source: 'missing-evidence',
+    subjectKind: item?.kind,
+    proofLevel: item?.proofLevel,
+    evidenceId: item?.evidenceId,
+    reasonCodes: uniqueStrings([item?.code, ...(item?.relatedSignals ?? [])]),
+    details: item
+  });
+}
+
+function fileAdmissionRoutes(file) {
+  return [
+    ...(file?.admission?.routes ?? []),
+    ...fileAdmissionEvidence(file).map((record) => record.admissionRoute)
+  ].filter(Boolean);
+}
+
+function fileAdmissionEvidence(file) {
+  const records = [file?.summary, file?.metadata].filter(isPlainObject);
+  return records.flatMap((record) => Object.entries(record)
+    .filter(([key, value]) => /Admission(?:Evidence|s)$/.test(key) && Array.isArray(value))
+    .flatMap(([, value]) => value));
+}
+
+function classificationKindFromConflict(conflict, details) {
+  if (details.symbolRenameKind) return 'cross-file-symbol-rename';
+  if (details.symbolMoveKind === 'exported') return 'exported-symbol-move';
+  if (details.symbolMoveKind === 'imported') return 'imported-symbol-move';
+  if (details.movementKind && String(conflict?.code).includes('file-move-rename')) return 'file-move-rename';
+  for (const kind of ['module-split', 'module-merge', 'class-split', 'class-merge']) {
+    if (String(conflict?.code).includes(kind)) return kind;
+  }
+  return structuralConflictCode(conflict?.code) ? 'project-admission' : undefined;
+}
+
+function structuralConflictCode(code) {
+  return /^project-(worker|head)-/.test(String(code ?? ''))
+    || ['project-typescript-refactor-evidence-missing', 'project-source-span-roundtrip-proof-failed'].includes(String(code ?? ''));
+}
+
+function routeRecord(input) {
+  if (!input.routeId) return undefined;
+  return compactRecord({
+    kind: 'frontier.lang.jsTsProjectMergeAdmissionRoute',
+    version: 1,
+    routeId: input.routeId,
+    routeKind: input.routeKind,
+    routeLane: input.routeLane,
+    routeNext: input.routeNext,
+    action: input.action,
+    status: input.status,
+    source: input.source,
+    subjectKind: input.subjectKind,
+    branch: input.branch,
+    sourcePath: input.sourcePath,
+    sourcePaths: input.sourcePaths?.length ? uniqueStrings(input.sourcePaths) : undefined,
+    proofLevel: input.proofLevel,
+    evidenceId: input.evidenceId,
+    conflictKey: input.conflictKey,
+    reasonCodes: input.reasonCodes?.length ? uniqueStrings(input.reasonCodes) : undefined,
+    requiredEvidence: input.requiredEvidence,
+    presentEvidence: input.presentEvidence,
+    missingEvidence: input.missingEvidence,
+    details: input.details,
+    autoMergeClaim: false,
+    semanticEquivalenceClaim: false
+  });
+}
+
+function uniqueProjectAdmissionRoutes(routes) {
+  const seen = new Set();
+  return routes.filter((route) => {
+    const key = [route.routeId, route.source, route.sourcePath, route.conflictKey, route.evidenceId, route.status].filter(Boolean).join('#');
+    if (!key || seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function normalizedRouteAction(action) {
+  if (action === 'rerun' || action === 'rerun-gate') return 'rerun';
+  if (action === 'reject-proof' || action === 'reject') return 'reject';
+  if (action === 'block') return 'block';
+  if (action === 'apply') return 'apply';
+  if (action === 'rebase') return 'rebase';
+  return 'review';
+}
+
+function routeSpec(routeId, routeLane, routeNext) { return Object.freeze({ routeId, routeLane, routeNext }); }
+function countField(values, field) { const result = {}; for (const value of values) if (value?.[field]) result[value[field]] = (result[value[field]] ?? 0) + 1; return result; }
+function uniqueStrings(values) { return [...new Set((values ?? []).filter((value) => typeof value === 'string' && value.length > 0))]; }
+function safeToken(value) { return String(value ?? 'project-admission').replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'project-admission'; }
+function isPlainObject(value) { return Boolean(value && typeof value === 'object' && !Array.isArray(value)); }
+function compactRecord(record) { return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined && (!Array.isArray(value) || value.length > 0))); }
+
+export {
+  createProjectAdmissionRoutes,
+  projectAdmissionRouteFromClassification,
+  projectAdmissionRouteFromExactAdmission,
+  projectAdmissionRouteFromMissingEvidence,
+  projectAdmissionRouteSummary
+};

package/dist/js-ts-safe-project-merge-admission.js

@@ -0,0 +1,161 @@
+import { hashSemanticValue } from '@shapeshift-labs/frontier-lang-kernel';
+import { compactRecord } from './js-ts-safe-merge-context.js';
+import { projectAdmissionRouteFromExactAdmission } from './js-ts-safe-project-merge-admission-routes.js';
+
+function createExactBranchProjectSemanticEditAdmissionFile(options) {
+  const {
+    fileResult,
+    file,
+    classifications = [],
+    admissionKind,
+    action,
+    operation,
+    summaryKey,
+    evidenceKey,
+    metadataKey,
+    requireOtherBranchUnchanged = true,
+    requireBaseForOtherBranchUnchanged = true,
+    allowDeletedBranchOutput = false,
+    allowExistingExactOutput = false,
+    classificationFilter = () => true,
+    admissionFields = () => ({}),
+    details = (classification) => classification.details
+  } = options;
+  if (!classifications.length || !classifications.every(classificationFilter)) return undefined;
+  const branches = uniqueStrings(classifications.map((classification) => classification.branch));
+  if (branches.length !== 1) return undefined;
+  const branch = branches[0];
+  const admissions = classifications
+    .map((classification) => exactBranchProjectSemanticEditAdmission({
+      fileResult,
+      file,
+      classification,
+      admissionKind,
+      requireOtherBranchUnchanged,
+      requireBaseForOtherBranchUnchanged,
+      allowDeletedBranchOutput,
+      allowExistingExactOutput,
+      admissionFields,
+      details
+    }))
+    .filter(Boolean);
+  if (admissions.length !== classifications.length) return undefined;
+  const branchText = branchSourceText(file, branch);
+  const outputHash = hashProjectSourceText(branchText);
+  return {
+    admissions,
+    fileResult: compactRecord({
+      ...fileResult,
+      status: 'merged',
+      operation: typeof operation === 'function' ? operation(fileResult) : operation,
+      outputSourceText: branchText,
+      outputHash,
+      baseHash: hashProjectSourceText(file.baseSourceText),
+      workerHash: hashProjectSourceText(branchSourceText(file, 'worker')),
+      headHash: hashProjectSourceText(branchSourceText(file, 'head')),
+      result: fileResult.status === 'merged' ? fileResult.result : undefined,
+      semanticArtifacts: fileResult.status === 'merged' ? fileResult.semanticArtifacts : undefined,
+      conflicts: [],
+      admission: exactBranchProjectSemanticEditFileAdmission(action),
+      summary: compactRecord({
+        ...(isPlainObject(fileResult.summary) ? fileResult.summary : {}),
+        conflicts: 0,
+        [summaryKey]: admissions.length,
+        [evidenceKey]: admissions
+      }),
+      metadata: metadataKey ? compactRecord({
+        ...(isPlainObject(fileResult.metadata) ? fileResult.metadata : {}),
+        [metadataKey]: admissions
+      }) : fileResult.metadata
+    })
+  };
+}
+
+function exactBranchProjectSemanticEditAdmission(options) {
+  const { fileResult, file, classification, admissionKind, requireOtherBranchUnchanged, requireBaseForOtherBranchUnchanged, allowDeletedBranchOutput, allowExistingExactOutput, admissionFields, details } = options;
+  const branchText = branchSourceText(file, classification.branch);
+  if (typeof branchText !== 'string' && !allowDeletedBranchOutput) return undefined;
+  const exactMergedOutput = fileResult.status === 'merged' && fileResult.outputSourceText === branchText;
+  if (!exactMergedOutput || !allowExistingExactOutput) {
+    if (requireOtherBranchUnchanged && !otherProjectBranchUnchanged(file, classification.branch, { requireBase: requireBaseForOtherBranchUnchanged })) return undefined;
+  }
+  const outputHash = hashProjectSourceText(branchText);
+  const admission = {
+    id: safeProjectEvidenceId(`${classification.details?.conflictKey ?? classification.code}_${file.sourcePath}`),
+    kind: admissionKind,
+    status: 'passed',
+    branch: classification.branch,
+    ...(admissionFields(classification) ?? {}),
+    sourcePath: file.sourcePath,
+    outputHash,
+    sourceHash: outputHash,
+    summary: `Project ${classification.branch} semantic edit output matched branch ${typeof branchText === 'string' ? 'source' : 'deletion'} for ${file.sourcePath}.`,
+    details: compactRecord({
+      ...(details(classification) ?? {}),
+      sourcePath: file.sourcePath,
+      outputHash,
+      exactBranchOutput: true,
+      deletedOutput: typeof branchText !== 'string' || undefined,
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false
+    })
+  };
+  return { ...admission, admissionRoute: projectAdmissionRouteFromExactAdmission(admission, { action: options.action }) };
+}
+
+function exactBranchProjectSemanticEditFileAdmission(action) {
+  return {
+    status: 'auto-merge-candidate',
+    action,
+    reviewRequired: false,
+    autoApplyCandidate: true,
+    autoMergeClaim: false,
+    semanticEquivalenceClaim: false,
+    reasonCodes: []
+  };
+}
+
+function summarizeProjectSemanticEditAdmissions(admissions = [], fields = {}) {
+  const unique = uniqueProjectSemanticEditAdmissions(admissions);
+  const summary = { [fields.totalKey ?? 'admissions']: unique.length };
+  for (const field of fields.byKind ?? []) {
+    summary[field.key] = unique.filter((admission) => admission[field.property] === field.value).length;
+  }
+  if (fields.evidenceIdsKey) summary[fields.evidenceIdsKey] = unique.map((admission) => admission.id);
+  return summary;
+}
+
+function uniqueProjectSemanticEditAdmissions(admissions) {
+  const seen = new Set();
+  return admissions.filter((admission) => {
+    const key = admission.details?.conflictKey ?? admission.id;
+    if (!key || seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function branchSourceText(file, branch) {
+  if (branch === 'worker') return file.workerDeleted ? undefined : file.workerSourceText ?? file.baseSourceText;
+  return file.headDeleted ? undefined : file.headSourceText ?? file.baseSourceText;
+}
+
+function otherProjectBranchUnchanged(file, branch, options = {}) {
+  const other = branch === 'worker' ? branchSourceText(file, 'head') : branchSourceText(file, 'worker');
+  return (options.requireBase === false || typeof file.baseSourceText === 'string') && other === file.baseSourceText;
+}
+
+function hashProjectSourceText(text) { return typeof text === 'string' ? hashSemanticValue(text) : undefined; }
+function uniqueStrings(values) { return [...new Set(values.filter((value) => typeof value === 'string' && value.length > 0))]; }
+function isPlainObject(value) { return Boolean(value && typeof value === 'object' && !Array.isArray(value)); }
+function safeProjectEvidenceId(value) { return String(value ?? 'unknown').replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'evidence'; }
+
+export {
+  branchSourceText,
+  createExactBranchProjectSemanticEditAdmissionFile,
+  hashProjectSourceText,
+  otherProjectBranchUnchanged,
+  safeProjectEvidenceId,
+  summarizeProjectSemanticEditAdmissions,
+  uniqueProjectSemanticEditAdmissions
+};

package/dist/js-ts-safe-project-merge-ambient.js

@@ -0,0 +1,110 @@
+import { hashSemanticValue } from '@shapeshift-labs/frontier-lang-kernel';
+import { compactRecord } from './js-ts-safe-merge-context.js';
+import { globalAugmentationCompatibilityAssessment } from './js-ts-safe-project-merge-global-augmentation-compatibility.js';
+
+const ambientRequiredEvidence = [
+  'typescript-program-symbol-evidence',
+  'declaration-output-gate',
+  'consumer-diagnostics-gate',
+  'global-augmentation-compatibility-evidence'
+];
+
+function maybeBlockAmbientProjectFile(file, context, input = {}) {
+  const changed = changedProjectTexts(file);
+  if (!changed.length) return undefined;
+  const sourceText = changed.map((entry) => entry.sourceText).join('\n');
+  const ambient = ambientReason(file.sourcePath, sourceText);
+  if (!ambient) return undefined;
+  const compatibility = ambient.surface === 'global-augmentation'
+    ? globalAugmentationCompatibilityAssessment({
+      sourcePath: file.sourcePath,
+      sourceHashes: uniqueStrings(changed.map((entry) => hashText(entry.sourceText))),
+      moduleName: 'global',
+      surfaceKind: 'global-augmentation'
+    }, input)
+    : undefined;
+  if (compatibility?.status === 'passed') return undefined;
+  return blockedAmbientFile(file, context, ambient, compatibility);
+}
+
+function changedProjectTexts(file) {
+  const entries = [];
+  if (typeof file.workerSourceText === 'string' && file.workerSourceText !== file.baseSourceText) {
+    entries.push({ branch: 'worker', sourceText: file.workerSourceText });
+  }
+  if (typeof file.headSourceText === 'string' && file.headSourceText !== file.baseSourceText) {
+    entries.push({ branch: 'head', sourceText: file.headSourceText });
+  }
+  if (file.workerDeleted || file.headDeleted) entries.push({ branch: file.workerDeleted ? 'worker' : 'head', sourceText: file.baseSourceText ?? '' });
+  return entries;
+}
+
+function ambientReason(sourcePath, sourceText) {
+  if (/\.d\.[cm]?ts$/i.test(String(sourcePath ?? ''))) {
+    return { code: 'project-ambient-declaration-merge-blocked', operation: 'blocked-ambient-declaration', surface: 'declaration-file' };
+  }
+  if (/\bdeclare\s+global\b|\bdeclare\s+module\s+['"]|\bglobalThis\b/.test(String(sourceText ?? ''))) {
+    return { code: 'project-global-augmentation-merge-blocked', operation: 'blocked-global-augmentation', surface: 'global-augmentation' };
+  }
+  return undefined;
+}
+
+function blockedAmbientFile(file, context, ambient, compatibility = undefined) {
+  const conflict = {
+    code: ambient.code,
+    gateId: 'project-ambient-declaration-classifier',
+    message: `Project ${ambient.surface} changes require TypeScript program, declaration, and consumer diagnostics evidence.`,
+    sourcePath: file.sourcePath,
+    details: compactRecord({
+      reasonCode: ambient.code,
+      conflictKey: `project-ambient#${ambient.surface}#${file.sourcePath}`,
+      sourcePath: file.sourcePath,
+      surface: ambient.surface,
+      baseHash: hashText(file.baseSourceText),
+      workerHash: hashText(file.workerSourceText),
+      headHash: hashText(file.headSourceText),
+      requiredEvidence: ambientRequiredEvidence,
+      routeId: compatibility?.routeId,
+      routeLane: compatibility?.routeLane,
+      routeNext: compatibility?.routeNext,
+      reasonCodes: compatibility?.reasonCodes,
+      globalAugmentationCompatibilityProof: compatibility?.record,
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false
+    })
+  };
+  return compactRecord({
+    kind: 'frontier.lang.jsTsProjectSafeMergeFile',
+    version: 1,
+    sourcePath: file.sourcePath,
+    language: context.language,
+    status: 'blocked',
+    operation: ambient.operation,
+    baseHash: hashText(file.baseSourceText),
+    workerHash: hashText(file.workerSourceText),
+    headHash: hashText(file.headSourceText),
+    conflicts: [conflict],
+    admission: {
+      status: 'blocked',
+      action: 'human-review',
+      reviewRequired: true,
+      autoApplyCandidate: false,
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false,
+      reasonCodes: [ambient.code],
+      conflictKeys: [conflict.details.conflictKey]
+    },
+    summary: { conflicts: 1, projectAmbientDeclarationClassification: true },
+    conflictKeys: [conflict.details.conflictKey]
+  });
+}
+
+function hashText(text) {
+  return typeof text === 'string' ? hashSemanticValue(text) : undefined;
+}
+
+function uniqueStrings(values) {
+  return [...new Set(values.filter((value) => typeof value === 'string' && value.length > 0))];
+}
+
+export { maybeBlockAmbientProjectFile };