@shapeshift-labs/frontier-lang-compiler 0.2.40 → 0.2.42

package/README.md

@@ -264,6 +264,71 @@ console.log(changeSet.mergeCandidate.readiness); // merge-admission classificati
 
 Use `diffNativeSourceImports` when the worker or runner already produced `importNativeSource` results. Changed regions include a `metadata.changedRegionProjection` envelope with before/after source hashes, source-map links, ownership keys, readiness, and `autoMergeClaim: false` so swarm admission tools can score or port patches without treating semantic metadata as proof. Body-only edits that the lightweight scanner cannot anchor to a symbol are still reported as file-level changed regions instead of being silently treated as safe.
 
+Bundle a native diff into a compact semantic patch record when a coordinator needs hashes, changed semantic regions, source-map links, proof/history/evidence IDs, and merge-admission status without loading whole source files:
+
+```js
+import {
+  createSemanticPatchBundleRecord,
+  diffNativeSources,
+  querySemanticPatchBundleRecords
+} from '@shapeshift-labs/frontier-lang-compiler';
+
+const changeSet = diffNativeSources({
+  language: 'javascript',
+  sourcePath: 'src/runtime.js',
+  beforeSourceText: 'export function step(frame) { return frame + 1; }\n',
+  afterSourceText: 'export function step(frame, delta) { return frame + delta; }\n'
+});
+
+const bundle = createSemanticPatchBundleRecord(changeSet, {
+  proofIds: ['proof_worker_replay'],
+  historyIds: ['history_worker_run'],
+  admission: { status: 'queued', readiness: changeSet.readiness }
+});
+
+console.log(bundle.changedRegions[0].key); // compact semantic region key
+console.log(bundle.sourceMapLinks[0].sourceMapMappingId); // source-map link, not source text
+console.log(bundle.admission.autoMergeClaim); // false
+console.log(querySemanticPatchBundleRecords([bundle], { sourcePath: 'src/runtime.js' }).length); // 1
+```
+
+Semantic patch bundle records keep compact refs and query indexes for base/target/source hashes, source paths, changed region keys, conflict keys, source-map IDs, evidence IDs, proof IDs, history IDs, readiness, and admission status. They intentionally omit `before`/`after` import payloads and source text; use the original diff result when a worker needs to re-read or re-project source.
+
+Store worker outputs as compact semantic history records when a coordinator needs to compare distributed changes without merging whole files:
+
+```js
+import {
+  createSemanticHistoryRecord,
+  querySemanticHistoryRecordOverlaps
+} from '@shapeshift-labs/frontier-lang-compiler';
+
+const left = createSemanticHistoryRecord({
+  id: 'worker_left',
+  baseHash: 'source_base_hash',
+  importId: 'import_left',
+  sourcePath: 'src/runtime.ts',
+  ownershipRegions: [{ key: 'source#src/runtime.ts#function#step', granularity: 'symbol' }],
+  semanticCandidates: [{ id: 'candidate_left', conflictKeys: ['source#src/runtime.ts#function#step'] }],
+  evidenceIds: ['evidence_left_test'],
+  proofIds: ['proof_left_replay'],
+  admission: { status: 'queued', readiness: 'needs-review' },
+  replayLinks: [{ id: 'replay_left', kind: 'patch', path: 'patches/left.json' }]
+});
+
+const right = createSemanticHistoryRecord({
+  id: 'worker_right',
+  baseHash: 'different_source_base_hash',
+  importId: 'import_right',
+  sourcePath: 'src/runtime.ts',
+  ownershipRegions: [{ key: 'source#src/runtime.ts#function#step', granularity: 'symbol' }],
+  semanticCandidates: [{ id: 'candidate_right', conflictKeys: ['source#src/runtime.ts#function#step'] }]
+});
+
+console.log(querySemanticHistoryRecordOverlaps([left, right])[0].conflict); // true
+```
+
+The record stores base/target hashes, source and import IDs, ownership-region keys, semantic candidate IDs and conflict keys, evidence/proof IDs, reviewer and admission status, plus replay links. Overlap queries compare those compact indexes directly, so centralized and distributed swarms can find shared regions, stale-base conflicts, and replay targets without loading source text.
+
 Extract a surgical semantic slice when a worker only needs one symbol, region, native AST node, or source path:
 
 ```js
@@ -331,6 +396,15 @@ console.log(rustCandidate.sourceMap.mappings[0]?.semanticSymbolId); // generated
 
 `compileNativeSource` returns the import result, projection, target loss matrix cell, combined losses, readiness, evidence, output hash, and generated-output source maps. Same-language preserved output uses exact source mappings when the hash matches; generated stubs use declaration-level spans; adapter output uses adapter-supplied maps when present and otherwise gets an estimated fallback. Admission queues should treat `ok` as "code was emitted", not as merge approval; `readiness`, `targetCoverage`, and source-map precision carry the merge signal.
 
+Native projections and compile results also carry a `frontier.lang.nativeRoundtripEvidence` record under `evidence[].metadata.roundtripEvidence` and `metadata.roundtripEvidence`. That payload records import readiness/loss counts, universal AST validation and source-map precision, projection mode/hash verification, target adapter identity, target coverage, output source-map precision, and blocking/review loss ids in one coordinator-sortable JSON shape:
+
+```js
+const roundtrip = rustCandidate.metadata.roundtripEvidence;
+console.log(roundtrip.status); // "blocked", "stub-only", "preserved-source", or "target-adapter"
+console.log(roundtrip.output.sourceMaps.precision); // "exact", "declaration", "estimated", or "none"
+console.log(roundtrip.losses.blockingLossIds);
+```
+
 Provide a target projection adapter when the host owns real native-to-target translation semantics:
 
 ```js
@@ -475,6 +549,8 @@ console.log(imported.adapter.coverage.capabilityEvidence.observed.sourceRanges);
 console.log(imported.adapter.coverage.capabilityEvidence.gaps);
 console.log(imported.adapter.coverage.semanticCoverage.level);
 console.log(project.metadata.sourcePreservationSummary.total);
+console.log(project.metadata.projectAdmission.mergeScore.value); // sortable readiness score
+console.log(project.metadata.projectAdmission.mergeScore.components.targetProjectionCoverage.score);
 ```
 
 The built-in adapter factories are dependency-light wrappers for caller-owned parsers or ASTs:
@@ -496,6 +572,30 @@ Adapter summaries include a structured `coverage` record so merge queues can dis
 
 Coverage records also keep declared, observed, and effective capability evidence separate. `coverage.capabilityEvidence.gaps` highlights missing exact AST, token/trivia, parser diagnostics, source range, generated range, reference, type, and control-flow evidence for the current adapter/import. `observedOnly` means the import produced evidence the adapter did not declare, while `declaredOnly` means the adapter declared support that this run did not exercise.
 
+Project import admission records include `mergeScore`, a `frontier.lang.semanticMergeScore.v1` object with a 0-100 sortable value where higher is more admission-ready. The component scores combine semantic evidence density, source preservation, stale source hashes, changed ownership regions, proof/readiness evidence, and target projection coverage, so coordinators can sort imports while still seeing the specific evidence behind a low score.
+
+Release trains and semantic merge planners can inspect adapter package contracts without importing the adapter packages themselves:
+
+```js
+import {
+  getLanguageAdapterPackageContract,
+  queryLanguageAdapterPackageContracts
+} from '@shapeshift-labs/frontier-lang-compiler';
+
+const rust = getLanguageAdapterPackageContract('@shapeshift-labs/frontier-lang-rust');
+console.log(rust.sourceParser.format); // "rust-syn"
+console.log(rust.targetProjection.targets); // ["rust"]
+console.log(rust.releaseReadiness.releaseReady); // true
+
+const platformImporters = queryLanguageAdapterPackageContracts({
+  packageClass: 'platform-importer',
+  importsAdapterPackage: false
+});
+console.log(platformImporters.map((entry) => entry.package.name));
+```
+
+Each static contract exposes package name/version, version source, source parser languages/formats, parser caveats, target projection support/caveats, semantic-index formats, proof/evidence requirements, release readiness signals, and `runtime.importsAdapterPackage: false`. Standalone source-language importer packages such as Java, Kotlin, Swift, C#, Go, and Clang remain structural placeholders with `packageVersion: "0.0.0"` and `releaseReadiness.releaseReady: false` until a release train pins standalone package versions and host parser/build evidence.
+
 ## Related Packages
 
 The published Frontier package family is generated from one shared package catalog so READMEs stay in sync across packages:

package/bench/compile-suite.mjs

@@ -0,0 +1,31 @@
+import { performance } from 'node:perf_hooks';
+import { compileFrontierSource } from '../dist/index.js';
+
+const source = `
+module Bench @id("mod_bench")
+type TodoInput @id("type_input") {
+  title: Text
+}
+entity Todo @id("ent_todo") {
+  title @id("field_title"): Text
+}
+action addTodo @id("action_add") {
+  input TodoInput
+  writes field_title
+  returns Patch
+}
+`;
+
+const targets = ['typescript', 'javascript', 'rust', 'python', 'c'];
+
+export function measureFrontierCompile() {
+  const start = performance.now();
+  let bytes = 0;
+  for (let index = 0; index < 250; index += 1) {
+    bytes += compileFrontierSource(source, { target: targets[index % targets.length] }).output.length;
+  }
+  return {
+    bytes,
+    compileDurationMs: performance.now() - start
+  };
+}

package/bench/native-adapters.mjs

@@ -0,0 +1,32 @@
+import {
+  createClangAstNativeImporterAdapter,
+  createCSharpRoslynNativeImporterAdapter,
+  createEstreeNativeImporterAdapter,
+  createGoAstNativeImporterAdapter,
+  createJavaAstNativeImporterAdapter,
+  createKotlinPsiNativeImporterAdapter,
+  createPythonAstNativeImporterAdapter,
+  createRustSynNativeImporterAdapter,
+  createSwiftSyntaxNativeImporterAdapter
+} from '../dist/index.js';
+
+export function createBenchNativeAdapters() {
+  return {
+    estreeAdapter: createEstreeNativeImporterAdapter(),
+    kotlinPsiAdapter: createKotlinPsiNativeImporterAdapter()
+  };
+}
+
+export function createBenchMatrixAdapters(adapters) {
+  return [
+    adapters.estreeAdapter,
+    createPythonAstNativeImporterAdapter(),
+    createRustSynNativeImporterAdapter(),
+    createClangAstNativeImporterAdapter(),
+    createGoAstNativeImporterAdapter(),
+    createJavaAstNativeImporterAdapter(),
+    adapters.kotlinPsiAdapter,
+    createCSharpRoslynNativeImporterAdapter(),
+    createSwiftSyntaxNativeImporterAdapter()
+  ];
+}

package/bench/native-import-suite.mjs

@@ -0,0 +1,79 @@
+import { performance } from 'node:perf_hooks';
+import { importNativeSource, runNativeImporterAdapter } from '../dist/index.js';
+import { createBenchNativeAdapters } from './native-adapters.mjs';
+
+export async function collectNativeImports() {
+  const importStart = performance.now();
+  const adapters = createBenchNativeAdapters();
+  let nativeSymbols = 0;
+  const nativeImportResults = [];
+
+  for (let index = 0; index < 150; index += 1) {
+    const imported = index % 2 === 0
+      ? importNativeSource({
+        language: 'javascript',
+        sourcePath: `src/bench-${index}.js`,
+        sourceText: `export function bench${index}() { return ${index}; }\n`
+      })
+      : await runNativeImporterAdapter(adapters.estreeAdapter, {
+        sourcePath: `src/bench-${index}.js`,
+        sourceText: `export function bench${index}() { return ${index}; }\n`,
+        adapterOptions: {
+          ast: {
+            type: 'Program',
+            loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 42 } },
+            body: [{
+              type: 'FunctionDeclaration',
+              id: { type: 'Identifier', name: `bench${index}` },
+              loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 42 } }
+            }]
+          }
+        }
+      });
+    nativeSymbols += imported.semanticIndex?.symbols?.length ?? 0;
+    nativeImportResults.push(imported);
+  }
+
+  for (let index = 0; index < 50; index += 1) {
+    const imported = await runNativeImporterAdapter(adapters.kotlinPsiAdapter, createKotlinBenchCase(index));
+    nativeSymbols += imported.semanticIndex?.symbols?.length ?? 0;
+    nativeImportResults.push(imported);
+  }
+
+  return {
+    adapters,
+    nativeImportResults,
+    nativeSymbols,
+    nativeImportDurationMs: performance.now() - importStart
+  };
+}
+
+function createKotlinBenchCase(index) {
+  return {
+    sourcePath: `src/bench-${index}.kt`,
+    sourceText: `package bench\nclass BenchKotlin${index}(val title: String) { fun render${index}() = title }\n`,
+    adapterOptions: {
+      ast: {
+        kind: 'KtFile',
+        packageDirective: { kind: 'KtPackageDirective', fqName: 'bench' },
+        declarations: [{
+          kind: 'KtClass',
+          name: `BenchKotlin${index}`,
+          declarations: [{
+            kind: 'KtPrimaryConstructor',
+            parameters: [{
+              kind: 'KtParameter',
+              name: 'title',
+              typeReference: { text: 'String' },
+              valOrVarKeyword: 'val'
+            }]
+          }, {
+            kind: 'KtNamedFunction',
+            name: `render${index}`,
+            bodyExpression: { kind: 'KtBlockExpression' }
+          }]
+        }]
+      }
+    }
+  };
+}

package/bench/native-matrix-suite.mjs

@@ -0,0 +1,64 @@
+import { performance } from 'node:perf_hooks';
+import {
+  createNativeImportCoverageMatrix,
+  createNativeParserAstFormatMatrix,
+  createNativeParserFeatureMatrix,
+  createProjectionTargetLossMatrix,
+  createUniversalCapabilityMatrix,
+  queryNativeParserFeatureMatrix
+} from '../dist/index.js';
+import { createBenchMatrixAdapters } from './native-adapters.mjs';
+
+const requiredFeatures = ['syntax', 'semantic', 'sourcePreservation'];
+
+export function measureNativeMatrices(nativeImportResults, adapters) {
+  const matrixStart = performance.now();
+  const coverageMatrix = createNativeImportCoverageMatrix({ imports: nativeImportResults });
+  const coverageMatrixDurationMs = performance.now() - matrixStart;
+
+  const parserFormatMatrixStart = performance.now();
+  const parserFormatMatrix = createNativeParserAstFormatMatrix({
+    imports: nativeImportResults,
+    adapters: createBenchMatrixAdapters(adapters)
+  });
+  const parserFormatMatrixDurationMs = performance.now() - parserFormatMatrixStart;
+
+  const parserFeatureMatrixStart = performance.now();
+  const parserFeatureMatrix = createNativeParserFeatureMatrix({
+    imports: nativeImportResults,
+    adapters: createBenchMatrixAdapters(adapters),
+    requiredFeatures
+  });
+  const parserFeatureQuery = queryNativeParserFeatureMatrix(parserFeatureMatrix, {
+    language: 'javascript',
+    parser: 'estree',
+    requiredFeatures
+  });
+  const parserFeatureMatrixDurationMs = performance.now() - parserFeatureMatrixStart;
+
+  const projectionMatrixStart = performance.now();
+  const projectionLossMatrix = createProjectionTargetLossMatrix({ imports: nativeImportResults });
+  const projectionMatrixDurationMs = performance.now() - projectionMatrixStart;
+
+  const universalMatrixStart = performance.now();
+  const universalCapabilityMatrix = createUniversalCapabilityMatrix({
+    imports: nativeImportResults,
+    adapters: createBenchMatrixAdapters(adapters),
+    requiredFeatures
+  });
+  const universalMatrixDurationMs = performance.now() - universalMatrixStart;
+
+  return {
+    coverageMatrix,
+    coverageMatrixDurationMs,
+    parserFormatMatrix,
+    parserFormatMatrixDurationMs,
+    parserFeatureMatrix,
+    parserFeatureQuery,
+    parserFeatureMatrixDurationMs,
+    projectionLossMatrix,
+    projectionMatrixDurationMs,
+    universalCapabilityMatrix,
+    universalMatrixDurationMs
+  };
+}

package/bench/native-transform-suite.mjs

@@ -0,0 +1,125 @@
+import { performance } from 'node:perf_hooks';
+import {
+  compileNativeSource,
+  createNativeSourcePreservation,
+  createSemanticImportSidecar,
+  createSemanticSlice,
+  projectNativeImportToSource,
+  summarizeNativeImportFeatureEvidence,
+  testSemanticSlice
+} from '../dist/index.js';
+
+export function measureNativeTransformations(nativeImportResults) {
+  const preservationStart = performance.now();
+  const preservationRecords = nativeImportResults.map((imported) => imported.metadata.sourcePreservation ?? createNativeSourcePreservation({
+    language: imported.language,
+    sourcePath: imported.sourcePath,
+    sourceText: imported.metadata.sourcePreservation?.sourceText ?? ''
+  }));
+  const sourcePreservationDurationMs = performance.now() - preservationStart;
+  const sourcePreservationTokens = preservationRecords.reduce((sum, record) => sum + record.tokens.length + record.trivia.length, 0);
+
+  const sidecarStart = performance.now();
+  const semanticSidecars = nativeImportResults.map((imported) => createSemanticImportSidecar(imported));
+  const sidecarDurationMs = performance.now() - sidecarStart;
+  const sidecarOwnershipRegions = semanticSidecars.reduce((sum, sidecar) => sum + sidecar.ownershipRegions.length, 0);
+
+  const sliceStart = performance.now();
+  const semanticSlices = nativeImportResults.slice(0, 100).map((imported, index) => {
+    const symbol = imported.semanticIndex?.symbols?.[0]?.name ?? imported.semanticIndex?.symbols?.[0]?.id;
+    return createSemanticSlice(imported, {
+      entryRefs: symbol ? [`symbol:${symbol}`] : [],
+      includeDependencies: index % 2 === 0,
+      focusedCommands: [`npm test -- semantic-slice-${index}`]
+    });
+  });
+  const sliceDurationMs = performance.now() - sliceStart;
+  const sliceSourceMapLinks = semanticSlices.reduce((sum, slice) => sum + slice.sourceMapLinks.length, 0);
+  const sliceConflictKeys = semanticSlices.reduce((sum, slice) => sum + slice.mergeAdmission.conflictKeys.length, 0);
+  const sliceGateStart = performance.now();
+  const semanticSliceGates = semanticSlices.map((slice) => testSemanticSlice(slice, { requireSourceMapLinks: false }));
+  const sliceGateDurationMs = performance.now() - sliceGateStart;
+  const sliceGateFailures = semanticSliceGates.filter((gate) => gate.status === 'failed').length;
+
+  const featureEvidenceStart = performance.now();
+  const featureEvidenceSummaries = nativeImportResults.map((imported) => summarizeNativeImportFeatureEvidence(imported.losses, {
+    evidence: imported.evidence
+  }));
+  const featureEvidenceDurationMs = performance.now() - featureEvidenceStart;
+  const featureEvidencePolicyMatches = featureEvidenceSummaries.reduce((sum, summary) => sum + summary.total, 0);
+
+  const projectionStart = performance.now();
+  const nativeProjections = nativeImportResults.map((imported) => projectNativeImportToSource(imported));
+  const projectionDurationMs = performance.now() - projectionStart;
+  const projectionBytes = nativeProjections.reduce((sum, projection) => sum + projection.sourceText.length, 0);
+
+  const compileMetrics = measureNativeCompiles(nativeImportResults);
+  const targetAdapterMetrics = measureNativeTargetAdapterCompiles(nativeImportResults);
+  return {
+    sourcePreservationRecords: preservationRecords.length,
+    sourcePreservationTokens,
+    sourcePreservationDurationMs,
+    semanticSidecars: semanticSidecars.length,
+    sidecarOwnershipRegions,
+    sidecarDurationMs,
+    semanticSlices: semanticSlices.length,
+    sliceDurationMs,
+    sliceGateDurationMs,
+    sliceSourceMapLinks,
+    sliceConflictKeys,
+    sliceGateFailures,
+    featureEvidencePolicyMatches,
+    featureEvidenceDurationMs,
+    nativeProjections: nativeProjections.length,
+    projectionBytes,
+    projectionDurationMs,
+    ...compileMetrics,
+    ...targetAdapterMetrics
+  };
+}
+
+function measureNativeCompiles(nativeImportResults) {
+  const nativeCompileStart = performance.now();
+  const nativeCompiles = nativeImportResults.map((imported, index) => compileNativeSource(imported, {
+    target: index % 2 === 0 ? 'javascript' : 'rust',
+    emitOnBlocked: true
+  }));
+  const nativeCompileDurationMs = performance.now() - nativeCompileStart;
+  return {
+    nativeCompiles: nativeCompiles.length,
+    nativeCompileBytes: nativeCompiles.reduce((sum, result) => sum + result.output.length, 0),
+    nativeCompileSourceMaps: nativeCompiles.reduce((sum, result) => sum + result.sourceMaps.length, 0),
+    nativeCompileSourceMapMappings: nativeCompiles.reduce((sum, result) => sum + result.sourceMaps.reduce((mapSum, sourceMap) => mapSum + sourceMap.mappings.length, 0), 0),
+    nativeCompileBlocked: nativeCompiles.filter((result) => result.readiness.readiness === 'blocked').length,
+    nativeCompileDurationMs
+  };
+}
+
+function measureNativeTargetAdapterCompiles(nativeImportResults) {
+  const nativeTargetAdapterStart = performance.now();
+  const nativeTargetAdapterCompiles = nativeImportResults.slice(0, 25).map((imported, index) => {
+    const target = index % 2 === 0 ? 'rust' : 'python';
+    return compileNativeSource(imported, {
+      target,
+      targetAdapters: [{
+        id: `bench-target-adapter-${index}`,
+        sourceLanguage: imported.language,
+        target,
+        coverage: {
+          readiness: 'needs-review',
+          handledLossKinds: ['dynamicRuntime', 'dynamicDispatch', 'typeInference', 'overloadResolution']
+        },
+        project() {
+          return { output: `// bench target adapter ${index}\n`, readiness: 'needs-review' };
+        }
+      }]
+    });
+  });
+  const nativeTargetAdapterDurationMs = performance.now() - nativeTargetAdapterStart;
+  return {
+    nativeTargetAdapterCompiles: nativeTargetAdapterCompiles.length,
+    nativeTargetAdapterBytes: nativeTargetAdapterCompiles.reduce((sum, result) => sum + result.output.length, 0),
+    nativeTargetAdapterSourceMaps: nativeTargetAdapterCompiles.reduce((sum, result) => sum + result.sourceMaps.length, 0),
+    nativeTargetAdapterDurationMs
+  };
+}