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

package/dist/internal/index-impl/semanticEditTypeSyntaxReasons.js

@@ -0,0 +1,134 @@
+import { uniqueStrings } from '../../native-import-utils.js';
+import { nativeImportSourceText } from './nativeImportSourceText.js';
+import { sourceTextForSpan } from './sourceTextForSpan.js';
+
+export function typeSyntaxEditClassification(input) {
+  const reasonCodes = typeSyntaxEditReasonCodes(input);
+  if (!reasonCodes.length) return undefined;
+  const evidenceIds = typeSyntaxEvidenceIds(input);
+  if (evidenceIds.length) {
+    return {
+      status: 'portable',
+      reasonCodes: uniqueStrings([...reasonCodes, 'type-syntax-edit-backed-by-typechecker-or-declaration-evidence']),
+      evidenceIds
+    };
+  }
+  return {
+    status: 'blocked',
+    reasonCodes: uniqueStrings([...reasonCodes, 'type-syntax-edit-requires-typechecker-or-declaration-evidence']),
+    evidenceIds: []
+  };
+}
+
+export function typeSyntaxEditReasonCodes(input) {
+  if (!isJsTsLanguage(input) || input.region?.regionKind === 'import') return [];
+  if (!['modified', 'removed', 'added'].includes(input.region?.changeKind)) return [];
+  const baseText = typeSyntaxSourceText(input.context.base, input.baseSymbol, input.region, 'before');
+  const workerText = typeSyntaxSourceText(input.context.worker, input.workerSymbol, input.region, 'after');
+  if (typeof baseText !== 'string' || typeof workerText !== 'string' || baseText === workerText) return [];
+  const allowAngleAssertion = !isJsxLikeLanguage(input);
+  const base = typeSyntaxSignals(baseText, allowAngleAssertion);
+  const worker = typeSyntaxSignals(workerText, allowAngleAssertion);
+  const reasons = [];
+  if (base.satisfies || worker.satisfies) reasons.push('satisfies-expression-edit-requires-typechecker-evidence');
+  if (base.asConst || worker.asConst) reasons.push('as-const-assertion-edit-requires-declaration-evidence');
+  if (base.typeAssertion || worker.typeAssertion) reasons.push('type-assertion-edit-requires-typechecker-evidence');
+  if (base.constTypeParameters !== worker.constTypeParameters) reasons.push('const-type-parameter-edit-requires-declaration-evidence');
+  if (base.constraints !== worker.constraints) reasons.push('generic-constraint-edit-requires-typechecker-evidence');
+  if (base.generics !== worker.generics) reasons.push('generic-type-parameter-edit-requires-typechecker-evidence');
+  if (base.conditionalTypes !== worker.conditionalTypes) reasons.push('conditional-type-edit-requires-declaration-evidence');
+  return uniqueStrings(reasons);
+}
+
+function typeSyntaxSignals(text, allowAngleAssertion) {
+  const normalized = String(text ?? '').replace(/\s+/g, ' ').trim();
+  const genericClauses = typeParameterClauses(normalized);
+  return {
+    satisfies: /\bsatisfies\b/.test(normalized),
+    asConst: /\bas\s+const\b/.test(normalized),
+    typeAssertion: hasTypeAssertionSyntax(normalized, allowAngleAssertion),
+    generics: genericClauses.join('|'),
+    constraints: genericClauses.filter((clause) => /\bextends\b/.test(clause)).join('|'),
+    constTypeParameters: genericClauses.filter((clause) => /<[^>]*\bconst\s+[A-Za-z_$]/.test(clause)).join('|'),
+    conditionalTypes: conditionalTypeClauses(normalized).join('|')
+  };
+}
+
+function typeSyntaxSourceText(imported, symbol, region, projectionSide) {
+  const sourceText = nativeImportSourceText(imported);
+  const projection = region?.metadata?.changedRegionProjection;
+  const span = symbol?.sourceSpan ?? projection?.[projectionSide]?.sourceSpan ?? region?.sourceSpan;
+  const exact = sourceTextForSpan(sourceText, span);
+  const lineText = sourceLineTextForSpan(sourceText, span);
+  return typeof lineText === 'string' && hasTypeSyntaxCue(lineText) ? lineText : exact;
+}
+
+function hasTypeSyntaxCue(text) {
+  return /\b(?:satisfies|extends|infer|as\s+const|as\s+(?:unknown|any|never|string|number|boolean|symbol|bigint))\b|<\s*const\s+[A-Za-z_$]|\btype\s+[A-Za-z_$][\w$]*(?:\s*<[^>\n]+>)?\s*=/.test(String(text ?? ''));
+}
+
+function sourceLineTextForSpan(sourceText, span) {
+  if (typeof sourceText !== 'string' || typeof span?.startLine !== 'number') return undefined;
+  const lines = sourceText.split('\n');
+  const startLine = Math.max(1, span.startLine);
+  const endLine = Math.max(startLine, typeof span.endLine === 'number' ? span.endLine : startLine);
+  return lines.slice(startLine - 1, endLine).join('\n');
+}
+
+function typeParameterClauses(text) {
+  const clauses = [];
+  const pattern = /\b(?:export\s+)?(?:declare\s+)?(?:async\s+)?(?:function|class|interface|type)\s+[A-Za-z_$][\w$]*\s*(<[^>\n]+>)/g;
+  for (const match of text.matchAll(pattern)) clauses.push(match[1].replace(/\s+/g, ' '));
+  return clauses;
+}
+
+function conditionalTypeClauses(text) {
+  const clauses = [];
+  const pattern = /\btype\s+[A-Za-z_$][\w$]*(?:\s*<[^>\n]+>)?\s*=\s*([^;\n]*\bextends\b[^;\n]*\?[^;\n]*:[^;\n]*)/g;
+  for (const match of text.matchAll(pattern)) clauses.push(match[1].replace(/\s+/g, ' '));
+  return clauses;
+}
+
+function hasTypeAssertionSyntax(text, allowAngleAssertion) {
+  if (/\bas\s+const\b/.test(text)) return true;
+  const asAssertion = /\bas\s+(?:unknown|any|never|string|number|boolean|symbol|bigint|readonly|[A-Z_$][\w$]*|\{|\[)/;
+  const angleAssertion = /(?:\b(?:return|throw)\b|[=([,])\s*<\s*[A-Za-z_$][^>\n]*>\s*(?:[A-Za-z_$"'[(])/;
+  return asAssertion.test(text) || (allowAngleAssertion && angleAssertion.test(text));
+}
+
+function typeSyntaxEvidenceIds(input) {
+  return uniqueStrings(typeSyntaxEvidenceRecords(input)
+    .filter(typeSyntaxEvidencePassed).map((record) => String(record.id ?? record.evidenceId ?? record.hash ?? record.kind)));
+}
+
+function typeSyntaxEvidenceRecords(input) {
+  return [
+    input.scriptInput?.typeSyntaxEvidence,
+    input.scriptInput?.typeCheckerEvidence,
+    input.scriptInput?.typescriptEvidence,
+    input.scriptInput?.diagnosticsEvidence,
+    input.scriptInput?.declarationEvidence,
+    input.scriptInput?.evidence,
+    input.context?.typeSyntaxEvidence
+  ].flatMap((entry) => Array.isArray(entry) ? entry : [entry]).filter((entry) => entry && typeof entry === 'object');
+}
+
+function typeSyntaxEvidencePassed(record) {
+  const status = String(record.status ?? record.result ?? '').toLowerCase();
+  if (status && !['passed', 'pass', 'ok', 'clean', 'accepted-clean'].includes(status)) return false;
+  const text = [
+    record.kind, record.type, record.source, record.gateId, record.summary, record.metadata?.kind,
+    record.metadata?.source, record.metadata?.diagnosticSource, record.metadata?.declarationSource
+  ].filter(Boolean).join(' ').toLowerCase();
+  return /\b(typechecker|type-checker|typescript|diagnostic|diagnostics|declaration|declarations|d\.ts|type-syntax)\b/.test(text);
+}
+
+function isJsTsLanguage(input) {
+  const language = String(input.region?.language ?? input.context?.workerChangeSet?.language ?? input.context?.base?.language ?? '').toLowerCase();
+  return ['javascript', 'typescript', 'jsx', 'tsx'].includes(language);
+}
+
+function isJsxLikeLanguage(input) {
+  const language = String(input.region?.language ?? input.context?.workerChangeSet?.language ?? input.context?.base?.language ?? '').toLowerCase();
+  return ['jsx', 'tsx'].includes(language);
+}

package/dist/internal/index-impl/semanticIndexFromNativeDeclarations.js

@@ -1,4 +1,5 @@
 import{idFragment,caseSensitiveIdFragment}from'../../native-import-utils.js';import{semanticOwnershipRegionForDeclaration}from'../../semantic-import-regions.js';import{createSemanticIndexRecord,hashSemanticValue}from'@shapeshift-labs/frontier-lang-kernel';
+import{dynamicImportExpressionEdgeFields}from'./dynamicImportExpressionMetadata.js';import{hostDependencyEdgeFields}from'./importMetaUrlDependencyMetadata.js';import{moduleImportAttributeEdgeFields}from'./moduleImportAttributeMetadata.js';
 import{relationPredicateForDeclaration}from'./relationPredicateForDeclaration.js';
 export function semanticIndexFromNativeDeclarations(declarations, input, options) {
   const documentId = `doc_${idFragment(input.sourcePath ?? input.language)}_${idFragment(input.sourceHash)}`;
@@ -94,7 +95,7 @@ export function semanticIndexFromNativeDeclarations(declarations, input, options
         granularity: ownershipRegion.granularity,
         key: ownershipRegion.key
       }
-    }, ...projectSymbolGraphFacts({ moduleEdge, publicContractRegion, reExportIdentity, relationId, symbolId, evidenceId }));
+    }, ...projectSymbolGraphFacts({ moduleEdge, publicContractRegion, reExportIdentity, relationId, symbolId, evidenceId, compilerSymbol: declaration.metadata?.compilerSymbol, compilerSymbolIdentityHash: declaration.metadata?.compilerSymbolIdentityHash, compilerType: declaration.metadata?.compilerType, compilerTypeIdentityHash: declaration.metadata?.compilerTypeIdentityHash }));
     mappings.push({
       id: `map_${idFragment(declaration.nativeNode.id)}_${idFragment(symbolId)}`,
       nativeAstNodeId: declaration.nativeNode.id,
@@ -124,7 +125,8 @@ export function semanticIndexFromNativeDeclarations(declarations, input, options
           fileHashes: input.sourceHash ? 1 : 0,
           moduleEdges: facts.filter((fact) => fact.predicate === 'moduleEdge').length,
           reExportIdentities: facts.filter((fact) => fact.predicate === 'reExportIdentity').length,
-          publicContractRegions: facts.filter((fact) => fact.predicate === 'publicContractRegion').length
+          publicContractRegions: facts.filter((fact) => fact.predicate === 'publicContractRegion').length,
+          compilerSymbols: facts.filter((fact) => fact.predicate === 'compilerSymbol').length, compilerTypes: facts.filter((fact) => fact.predicate === 'compilerType').length
         }
       }
   }];
@@ -199,6 +201,8 @@ function moduleEdgeForDeclaration(declaration, input, documentId, relationId, ow
     namespace: declaration.namespace ?? declaration.metadata?.namespace,
     isTypeOnly: declaration.isTypeOnly ?? declaration.metadata?.isTypeOnly ?? declaration.metadata?.typeOnly,
     exportStar: declaration.exportStar ?? declaration.metadata?.exportStar,
+    ...dynamicImportExpressionEdgeFields(declaration.metadata), ...hostDependencyEdgeFields(declaration.metadata),
+    ...moduleImportAttributeEdgeFields(declaration.metadata),
     isReExport: edgeKind === 're-export',
     publicContract: publicContractForDeclaration(declaration, edgeKind)
   });
@@ -256,16 +260,18 @@ function reExportIdentityForDeclaration(declaration, input, documentId, relation
     localName: declaration.localName ?? declaration.metadata?.localName, namespace: declaration.namespace ?? declaration.metadata?.namespace,
     isTypeOnly: declaration.isTypeOnly ?? declaration.metadata?.isTypeOnly ?? declaration.metadata?.typeOnly, exportStar: declaration.exportStar ?? declaration.metadata?.exportStar,
     symbolId: declaration.symbolId, relationId, ownershipRegionId: ownershipRegion.id, ownershipRegionKey: ownershipRegion.key,
-    publicContract: true
+    publicContract: true, hasImportAttributes: moduleEdge?.hasImportAttributes, importAttributeCount: moduleEdge?.importAttributeCount, importAttributeKeys: moduleEdge?.importAttributeKeys, importAttributeHash: moduleEdge?.importAttributeHash, importAttributes: moduleEdge?.importAttributes
   });
 }
 
-function projectSymbolGraphFacts({ moduleEdge, publicContractRegion, reExportIdentity, relationId, symbolId, evidenceId }) {
+function projectSymbolGraphFacts({ moduleEdge, publicContractRegion, reExportIdentity, relationId, symbolId, evidenceId, compilerSymbol, compilerSymbolIdentityHash, compilerType, compilerTypeIdentityHash }) {
   return [
+    compilerSymbol ? { id: graphFactId(relationId, symbolId, 'compiler_symbol'), predicate: 'compilerSymbol', subjectId: symbolId, value: { ...compilerSymbol, identityHash: compilerSymbolIdentityHash }, evidenceIds: [evidenceId] } : undefined,
+    compilerType ? { id: graphFactId(relationId, symbolId, 'compiler_type'), predicate: 'compilerType', subjectId: symbolId, value: { ...compilerType, identityHash: compilerTypeIdentityHash }, evidenceIds: [evidenceId] } : undefined,
     moduleEdge ? {
       id: graphFactId(relationId, symbolId, 'module_edge'),
       predicate: 'moduleEdge',
-      subjectId: relationId,
+      subjectId: symbolId,
       objectId: symbolId,
       value: moduleEdge,
       evidenceIds: [evidenceId]

package/dist/internal/index-impl/semanticPatchBundleComposition.js

@@ -0,0 +1,166 @@
+import { hashSemanticValue } from '@shapeshift-labs/frontier-lang-kernel';
+import { idFragment, uniqueStrings } from '../../native-import-utils.js';
+import { compareSemanticPatchBundleRecords } from './semanticPatchBundleOverlaps.js';
+import { replaySemanticEditProjection } from './replaySemanticEditProjection.js';
+
+function composeSemanticPatchBundleProjections(input = {}) {
+  const id = String(input.id ?? 'semantic_patch_bundle_composition');
+  const currentSourceText = input.currentSourceText ?? input.headSourceText;
+  const projections = array(input.projections ?? input.semanticEditProjections);
+  const bundles = array(input.bundles ?? input.semanticPatchBundles);
+  const sourcePath = input.sourcePath ?? projections.find((projection) => projection?.sourcePath)?.sourcePath;
+  const language = input.language ?? projections.find((projection) => projection?.language)?.language;
+  const reasonCodes = baseReasonCodes({ currentSourceText, projections, bundles });
+  const overlapRecords = bundleOverlapRecords(bundles, input.overlapOptions);
+  reasonCodes.push(...overlapRecords.flatMap((record) => record.admission.status === 'independent'
+    ? []
+    : [`bundle-overlap:${record.admission.status}`]));
+  const replays = reasonCodes.length ? [] : projections.map((projection, index) => replaySemanticEditProjection({
+    id: `${id}_replay_${index + 1}`,
+    projection,
+    currentSourceText,
+    currentSourcePath: sourcePath ?? projection.sourcePath,
+    language: language ?? projection.language,
+    parser: input.parser
+  }));
+  reasonCodes.push(...replayReasonCodes(replays));
+  const edits = reasonCodes.length ? [] : appliedReplayEdits(replays);
+  reasonCodes.push(...sourceEditOverlapReasons(edits));
+  const outputSourceText = reasonCodes.length ? undefined : applyReplayEdits(currentSourceText, edits);
+  const verificationReplays = outputSourceText === undefined ? [] : projections.map((projection, index) => replaySemanticEditProjection({
+    id: `${id}_already_applied_${index + 1}`,
+    projection,
+    currentSourceText: outputSourceText,
+    currentSourcePath: sourcePath ?? projection.sourcePath,
+    language: language ?? projection.language,
+    parser: input.parser
+  }));
+  reasonCodes.push(...verificationReasonCodes(verificationReplays));
+  const status = reasonCodes.length ? 'blocked' : 'verified';
+  const core = {
+    kind: 'frontier.lang.semanticPatchBundleComposition',
+    version: 1,
+    schema: 'frontier.lang.semanticPatchBundleComposition.v1',
+    id,
+    status,
+    sourcePath,
+    language,
+    bundleIds: bundles.map((bundle) => bundle?.id).filter(Boolean),
+    projectionIds: projections.map((projection) => projection?.id).filter(Boolean),
+    currentHash: typeof currentSourceText === 'string' ? hashSemanticValue(currentSourceText) : undefined,
+    outputHash: outputSourceText === undefined ? undefined : hashSemanticValue(outputSourceText),
+    outputSourceText,
+    replays,
+    verificationReplays,
+    overlapRecords,
+    admission: {
+      status: status === 'verified' ? 'auto-merge-candidate' : 'blocked',
+      action: status === 'verified' ? 'apply' : 'human-review',
+      reviewRequired: status !== 'verified',
+      autoApplyCandidate: status === 'verified',
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false,
+      reasonCodes: uniqueStrings(reasonCodes)
+    },
+    summary: {
+      bundles: bundles.length,
+      projections: projections.length,
+      replays: replays.length,
+      verificationReplays: verificationReplays.length,
+      appliedEdits: edits.length,
+      overlapRecords: overlapRecords.length,
+      blockedOverlaps: overlapRecords.filter((record) => record.admission.status !== 'independent').length
+    },
+    evidence: [{
+      id: `evidence_${idFragment(id)}_semantic_patch_bundle_composition`,
+      kind: 'semantic-patch-bundle-composition',
+      status: status === 'verified' ? 'passed' : 'needs-review',
+      path: sourcePath,
+      summary: status === 'verified'
+        ? `Composed ${edits.length} replayed semantic edit(s) from ${projections.length} projection(s).`
+        : `Semantic patch bundle composition blocked: ${uniqueStrings(reasonCodes).join(', ')}.`,
+      metadata: {
+        bundleIds: bundles.map((bundle) => bundle?.id).filter(Boolean),
+        projectionIds: projections.map((projection) => projection?.id).filter(Boolean),
+        autoMergeClaim: false,
+        semanticEquivalenceClaim: false
+      }
+    }]
+  };
+  return { ...core, hash: hashSemanticValue(core) };
+}
+
+function baseReasonCodes(input) {
+  return uniqueStrings([
+    typeof input.currentSourceText === 'string' ? undefined : 'missing-current-source-text',
+    input.projections.length ? undefined : 'missing-semantic-edit-projections',
+    input.bundles.length && input.bundles.length !== input.projections.length ? 'bundle-projection-count-mismatch' : undefined,
+    ...input.projections.map((projection, index) => projection?.status === 'projected' ? undefined : `projection-not-projected:${index + 1}`)
+  ].filter(Boolean));
+}
+
+function bundleOverlapRecords(bundles, options = {}) {
+  const records = [];
+  for (let left = 0; left < bundles.length; left += 1) {
+    for (let right = left + 1; right < bundles.length; right += 1) {
+      records.push(compareSemanticPatchBundleRecords(bundles[left], bundles[right], options));
+    }
+  }
+  return records;
+}
+
+function replayReasonCodes(replays) {
+  return uniqueStrings(replays.flatMap((replay, index) => {
+    if (replay.status === 'accepted-clean' || replay.status === 'already-applied') return [];
+    return [`replay-not-clean:${index + 1}:${replay.status}`, ...(replay.admission?.reasonCodes ?? replay.summary?.reasonCodes ?? [])];
+  }));
+}
+
+function appliedReplayEdits(replays) {
+  return replays.flatMap((replay, replayIndex) => (replay.edits ?? [])
+    .filter((edit) => edit.status === 'applied')
+    .map((edit, editIndex) => ({
+      replayIndex,
+      editIndex,
+      operationId: edit.operationId,
+      start: edit.start,
+      end: edit.end,
+      replacementText: edit.replacementText
+    })));
+}
+
+function sourceEditOverlapReasons(edits) {
+  const reasons = [];
+  const ordered = edits.slice().sort((left, right) => left.start - right.start || left.end - right.end);
+  for (let index = 1; index < ordered.length; index += 1) {
+    const previous = ordered[index - 1];
+    const current = ordered[index];
+    if (sourceEditsOverlap(previous, current)) reasons.push(`composed-source-edit-overlap:${previous.operationId}:${current.operationId}`);
+  }
+  return uniqueStrings(reasons);
+}
+
+function applyReplayEdits(sourceText, edits) {
+  return edits.slice().sort((left, right) => right.start - left.start || right.end - left.end)
+    .reduce((text, edit) => text.slice(0, edit.start) + edit.replacementText + text.slice(edit.end), sourceText);
+}
+
+function verificationReasonCodes(replays) {
+  return uniqueStrings(replays.flatMap((replay, index) => {
+    if (replay.status === 'already-applied') return [];
+    return [`verification-replay-not-already-applied:${index + 1}:${replay.status}`, ...(replay.admission?.reasonCodes ?? [])];
+  }));
+}
+
+function sourceEditsOverlap(left, right) {
+  if (left.start === left.end) return right.start < left.start && left.start < right.end;
+  if (right.start === right.end) return left.start < right.start && right.start < left.end;
+  return left.start < right.end && right.start < left.end;
+}
+
+function array(value) {
+  if (value === undefined || value === null) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+export { composeSemanticPatchBundleProjections };

package/dist/internal/index-impl/semanticStructuralDiffRecords.js

@@ -0,0 +1,150 @@
+import { hashSemanticValue } from '@shapeshift-labs/frontier-lang-kernel';
+import { idFragment, uniqueStrings } from '../../native-import-utils.js';
+
+function semanticStructuralEdit(input) {
+  const actions = structuralEditActions(input);
+  const structuralKind = structuralEditKind(actions);
+  const record = compactRecord({
+    id: `semantic_structural_edit_${idFragment(input.operationId)}`,
+    kind: 'frontier.lang.semanticStructuralEdit',
+    version: 1,
+    algorithm: 'frontier.semantic-edit-structural-diff.v1',
+    runtimeNeutral: true,
+    operationId: input.operationId,
+    structuralKind,
+    actions,
+    operationKind: input.kind,
+    changeKind: input.changeKind,
+    anchorKey: input.anchor?.key,
+    conflictKey: input.anchor?.conflictKey,
+    regionKind: input.anchor?.regionKind,
+    sourcePath: input.anchor?.sourcePath,
+    symbolName: input.anchor?.symbolName,
+    symbolKind: input.anchor?.symbolKind,
+    from: structuralSpanLocation(input.spans?.base),
+    to: structuralSpanLocation(input.spans?.worker),
+    head: structuralSpanLocation(input.spans?.head),
+    baseTextHash: input.hashes?.baseTextHash,
+    workerTextHash: input.hashes?.workerTextHash,
+    headTextHash: input.hashes?.headTextHash,
+    beforeSignatureHash: input.hashes?.beforeSignatureHash,
+    afterSignatureHash: input.hashes?.afterSignatureHash,
+    status: input.status,
+    reviewRequired: true,
+    confidence: input.confidence,
+    reasonCodes: uniqueStrings([
+      ...(input.reasonCodes ?? []),
+      'structural-diff-review-required',
+      'replay-required-for-safety'
+    ]),
+    reanchor: input.reanchor,
+    metadata: {
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false
+    }
+  });
+  return { ...record, hash: hashSemanticValue(record) };
+}
+
+function semanticStructuralDiff(input) {
+  const edits = (input.operations ?? []).map((operation) => operation.structuralEdit).filter(Boolean);
+  const summary = summarizeStructuralEdits(edits);
+  const core = {
+    kind: 'frontier.lang.semanticStructuralDiff',
+    version: 1,
+    schema: 'frontier.lang.semanticStructuralDiff.v1',
+    id: input.input.structuralDiffId ?? `semantic_structural_diff_${idFragment(input.input.id ?? input.sourcePath ?? 'semantic_edit')}`,
+    algorithm: 'frontier.semantic-edit-structural-diff.v1',
+    runtimeNeutral: true,
+    language: input.language,
+    sourcePath: input.sourcePath,
+    workerChangeSetId: input.workerChangeSet.id,
+    headChangeSetId: input.headChangeSet?.id,
+    edits,
+    summary,
+    admission: {
+      status: 'review-required',
+      action: 'run-replay-and-diagnostics',
+      reviewRequired: true,
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false,
+      reasonCodes: ['structural-diff-review-required', 'replay-required-for-safety']
+    },
+    metadata: {
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false,
+      note: 'Structural edit records classify AST/CST-neutral anchor movement and content changes; source replay diagnostics still decide safety.'
+    }
+  };
+  return { ...core, hash: hashSemanticValue(core) };
+}
+
+function structuralEditActions(input) {
+  if (input.changeKind === 'added') return ['insert'];
+  if (input.changeKind === 'removed') return ['delete'];
+  const actions = [];
+  if (structuralSpanMoved(input.spans?.base, input.spans?.worker) || input.reanchor?.toAnchorKey) actions.push('move');
+  if (structuralContentChanged(input.hashes)) actions.push('update');
+  return actions.length ? actions : ['update'];
+}
+
+function structuralEditKind(actions) {
+  if (actions.includes('move') && actions.includes('update')) return 'move-update';
+  return actions[0] ?? 'update';
+}
+
+function structuralContentChanged(hashes) {
+  return Boolean(
+    hashes?.baseTextHash && hashes?.workerTextHash && hashes.baseTextHash !== hashes.workerTextHash
+    || hashes?.beforeSignatureHash && hashes?.afterSignatureHash && hashes.beforeSignatureHash !== hashes.afterSignatureHash
+  );
+}
+
+function structuralSpanMoved(left, right) {
+  if (!left || !right) return false;
+  return (left.path && right.path && left.path !== right.path)
+    || left.startLine !== right.startLine
+    || left.startColumn !== right.startColumn
+    || left.endLine !== right.endLine
+    || left.endColumn !== right.endColumn;
+}
+
+function structuralSpanLocation(span) {
+  return span ? compactRecord({
+    path: span.path,
+    startLine: span.startLine,
+    startColumn: span.startColumn,
+    endLine: span.endLine,
+    endColumn: span.endColumn
+  }) : undefined;
+}
+
+function summarizeStructuralEdits(edits) {
+  const byKind = countBy(edits.map((edit) => edit.structuralKind));
+  const byAction = countBy(edits.flatMap((edit) => edit.actions ?? []));
+  return {
+    edits: edits.length,
+    byKind,
+    byAction,
+    moves: byAction.move ?? 0,
+    updates: byAction.update ?? 0,
+    inserts: byAction.insert ?? 0,
+    deletes: byAction.delete ?? 0,
+    moveUpdates: byKind['move-update'] ?? 0,
+    reviewRequired: edits.length > 0,
+    autoMergeClaim: false,
+    semanticEquivalenceClaim: false
+  };
+}
+
+function countBy(values) {
+  const result = {};
+  for (const value of values.filter(Boolean)) result[value] = (result[value] ?? 0) + 1;
+  return result;
+}
+
+function compactRecord(value) {
+  return Object.fromEntries(Object.entries(value ?? {}).filter(([, entry]) => entry !== undefined && (!Array.isArray(entry) || entry.length > 0)));
+}
+
+export { semanticStructuralDiff, semanticStructuralEdit };