@shapeshift-labs/frontier-lang-compiler 0.2.21 → 0.2.22

package/README.md

@@ -64,6 +64,25 @@ console.log(readiness.readiness);
 
 The loss taxonomy separates broad scanner limits from specific round-trip risks such as conditional compilation, reflection, overload/type-inference gaps, comments/trivia preservation, source-map approximation, parser diagnostics, and target projection loss. These records are evidence labels for merge admission; they are not claims that the lightweight scanner expanded macros, evaluated inactive branches, resolved overloads, or ran a type checker.
 
+High-risk native features also have explicit evidence policies. These policies are advisory in this package: they tell a swarm or admission queue what evidence is missing without silently changing the existing readiness classification.
+
+```js
+import {
+  getNativeImportFeatureEvidencePolicy,
+  summarizeNativeImportFeatureEvidence
+} from '@shapeshift-labs/frontier-lang-compiler';
+
+const policy = getNativeImportFeatureEvidencePolicy('preprocessor');
+console.log(policy.requiredEvidenceKeys); // ["preprocessedOutputHash", "definesHash"]
+
+const featureEvidence = summarizeNativeImportFeatureEvidence(imported.losses, {
+  evidence: imported.evidence
+});
+
+console.log(featureEvidence.highestRisk);
+console.log(featureEvidence.missingRequiredEvidence);
+```
+
 Ask the compiler what is actually covered before sending native imports into a merge queue:
 
 ```js

package/bench/smoke.mjs

@@ -9,7 +9,8 @@ import {
   createSemanticImportSidecar,
   importNativeSource,
   projectNativeImportToSource,
-  runNativeImporterAdapter
+  runNativeImporterAdapter,
+  summarizeNativeImportFeatureEvidence
 } from '../dist/index.js';
 
 const source = `
@@ -88,6 +89,13 @@ const semanticSidecars = nativeImportResults.map((imported) => createSemanticImp
 const sidecarDurationMs = performance.now() - sidecarStart;
 const sidecarOwnershipRegions = semanticSidecars.reduce((sum, sidecar) => sum + sidecar.ownershipRegions.length, 0);
 
+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;
@@ -150,6 +158,8 @@ console.log(JSON.stringify({
   semanticSidecars: semanticSidecars.length,
   sidecarOwnershipRegions,
   sidecarDurationMs: Number(sidecarDurationMs.toFixed(2)),
+  featureEvidencePolicyMatches,
+  featureEvidenceDurationMs: Number(featureEvidenceDurationMs.toFixed(2)),
   nativeProjections: nativeProjections.length,
   projectionBytes,
   projectionDurationMs: Number(projectionDurationMs.toFixed(2)),

package/dist/index.d.ts

@@ -151,6 +151,49 @@ export interface NativeImportLossSummaryOptions {
   readonly semanticStatus?: string;
 }
 
+export type NativeImportFeatureEvidenceRisk = 'low' | 'medium' | 'high' | 'critical' | string;
+
+export interface NativeImportFeatureEvidencePolicy {
+  readonly kind: NativeImportKnownLossKind;
+  readonly category: NativeImportTaxonomyKind;
+  readonly risk: NativeImportFeatureEvidenceRisk;
+  readonly minimumReadiness: SemanticMergeReadiness;
+  readonly missingEvidenceReadiness: SemanticMergeReadiness;
+  readonly requiredEvidenceKeys: readonly string[];
+  readonly recommendedEvidenceKeys: readonly string[];
+  readonly notes: readonly string[];
+}
+
+export interface NativeImportFeatureEvidenceIssue {
+  readonly lossId: string;
+  readonly kind: NativeImportKnownLossKind;
+  readonly policyKind: NativeImportKnownLossKind;
+  readonly risk: NativeImportFeatureEvidenceRisk;
+  readonly category: NativeImportTaxonomyKind;
+  readonly readiness: SemanticMergeReadiness;
+  readonly missingRequiredEvidence: readonly string[];
+  readonly presentRequiredEvidence: readonly string[];
+  readonly presentRecommendedEvidence: readonly string[];
+  readonly evidenceIds: readonly string[];
+}
+
+export interface NativeImportFeatureEvidenceSummary {
+  readonly total: number;
+  readonly policyKinds: readonly NativeImportKnownLossKind[];
+  readonly byKind: Readonly<Record<string, number>>;
+  readonly byRisk: Readonly<Record<string, number>>;
+  readonly highestRisk: NativeImportFeatureEvidenceRisk;
+  readonly semanticMergeReadiness: SemanticMergeReadiness;
+  readonly missingRequiredEvidence: readonly {
+    readonly lossId: string;
+    readonly kind: NativeImportKnownLossKind;
+    readonly policyKind: NativeImportKnownLossKind;
+    readonly evidenceKey: string;
+  }[];
+  readonly issues: readonly NativeImportFeatureEvidenceIssue[];
+  readonly reasons: readonly string[];
+}
+
 export interface NativeImportLossSummary {
   readonly total: number;
   readonly hasLosses: boolean;
@@ -165,6 +208,7 @@ export interface NativeImportLossSummary {
   readonly reviewLossIds: readonly string[];
   readonly informationalLossIds: readonly string[];
   readonly failedEvidenceIds: readonly string[];
+  readonly featureEvidence: NativeImportFeatureEvidenceSummary;
   readonly parser?: string;
   readonly scanKind?: string;
   readonly semanticStatus?: string;
@@ -1428,6 +1472,7 @@ export declare const NativeImportLossKinds: readonly NativeImportKnownLossKind[]
 export declare const NativeImportRegionTaxonomyKinds: readonly NativeImportRegionTaxonomyKind[];
 export declare const ProjectionTargetLossClasses: readonly ProjectionTargetLossClass[];
 export declare const NativeImportReadinessBySeverity: Readonly<Record<NativeImportLossSummary['highestSeverity'], SemanticMergeReadiness>>;
+export declare const NativeImportFeatureEvidencePolicies: Readonly<Record<string, NativeImportFeatureEvidencePolicy>>;
 export declare const NativeImportLanguageProfiles: readonly NativeImportLanguageProfile[];
 export declare function normalizeCompileTarget(target?: string): FrontierCompileTarget;
 export declare function compileFrontierSource(source: string, options?: FrontierCompileOptions): FrontierCompileResult;
@@ -1438,6 +1483,8 @@ export declare function renderTargetAst(ast: FrontierTargetAst, target?: Frontie
 export declare function renderTargetAstWithSourceMap(ast: FrontierTargetAst, target?: FrontierCompileOptions['target'], options?: FrontierCompileEmitOptions): FrontierTargetSourceMapResult;
 export declare function emitForTargetWithSourceMap(document: FrontierLangDocument, target?: FrontierCompileOptions['target'], options?: FrontierCompileEmitOptions): FrontierTargetDocumentSourceMapResult;
 export declare function resolveCapabilityAdapters(document: FrontierLangDocument, target?: FrontierCompileOptions['target'], options?: { readonly platform?: string }): readonly CapabilityResolution[];
+export declare function getNativeImportFeatureEvidencePolicy(kind: NativeImportKnownLossKind | string): NativeImportFeatureEvidencePolicy | undefined;
+export declare function summarizeNativeImportFeatureEvidence(losses?: readonly NativeAstLossRecord[], options?: NativeImportLossSummaryOptions): NativeImportFeatureEvidenceSummary;
 export declare function summarizeNativeImportLosses(losses?: readonly NativeAstLossRecord[], options?: NativeImportLossSummaryOptions): NativeImportLossSummary;
 export declare function classifyNativeImportReadiness(losses?: readonly NativeAstLossRecord[], options?: NativeImportLossSummaryOptions): NativeImportReadinessClassification;
 export declare function classifyNativeImportRoundtripReadiness(importResult: NativeSourceImportResult | NativeProjectImportResult, options?: NativeImportRoundtripReadinessOptions): NativeImportRoundtripReadinessClassification;

package/dist/index.js

@@ -76,6 +76,13 @@ const semanticMergeReadinessRank = Object.freeze({
   blocked: 3
 });
 
+const nativeFeatureEvidenceRiskRank = Object.freeze({
+  low: 0,
+  medium: 1,
+  high: 2,
+  critical: 3
+});
+
 export const NativeImportRoundtripReadinessStatuses = Object.freeze([
   'exact',
   'preserved-source',
@@ -136,6 +143,117 @@ export const NativeImportReadinessBySeverity = Object.freeze({
   error: 'blocked'
 });
 
+export const NativeImportFeatureEvidencePolicies = Object.freeze({
+  macroExpansion: nativeImportFeatureEvidencePolicy('macroExpansion', {
+    category: 'macroExpansion',
+    risk: 'high',
+    minimumReadiness: 'needs-review',
+    requiredEvidenceKeys: ['macroDefinitionsHash', 'expandedSourceHash'],
+    recommendedEvidenceKeys: ['expansionMapId', 'sourceMapId', 'macroCallSites'],
+    notes: ['Macro-expanded code must retain a link from generated output back to macro call sites before semantic merges can be trusted.']
+  }),
+  macroHygiene: nativeImportFeatureEvidencePolicy('macroHygiene', {
+    category: 'macroExpansion',
+    risk: 'critical',
+    minimumReadiness: 'needs-review',
+    missingEvidenceReadiness: 'blocked',
+    requiredEvidenceKeys: ['hygieneContextHash', 'bindingMapId'],
+    recommendedEvidenceKeys: ['expansionMapId', 'captureSetHash'],
+    notes: ['Hygiene-sensitive macros can change binding identity even when emitted text looks equivalent.']
+  }),
+  preprocessor: nativeImportFeatureEvidencePolicy('preprocessor', {
+    category: 'preprocessor',
+    risk: 'high',
+    minimumReadiness: 'needs-review',
+    requiredEvidenceKeys: ['preprocessedOutputHash', 'definesHash'],
+    recommendedEvidenceKeys: ['includeGraphHash', 'conditionalBranches', 'sourceMapId'],
+    notes: ['Preprocessor imports need the active defines/includes and preprocessed output hash to make replayable claims.']
+  }),
+  conditionalCompilation: nativeImportFeatureEvidencePolicy('conditionalCompilation', {
+    category: 'conditionalCompilation',
+    risk: 'high',
+    minimumReadiness: 'needs-review',
+    requiredEvidenceKeys: ['activeBranches', 'inactiveBranchesHash'],
+    recommendedEvidenceKeys: ['compileTarget', 'featureFlags', 'preprocessedOutputHash'],
+    notes: ['Conditional branches that were not active still affect portability and conflict review.']
+  }),
+  metaprogramming: nativeImportFeatureEvidencePolicy('metaprogramming', {
+    category: 'metaprogramming',
+    risk: 'critical',
+    minimumReadiness: 'needs-review',
+    missingEvidenceReadiness: 'blocked',
+    requiredEvidenceKeys: ['generatedArtifactHash', 'generatorIdentity'],
+    recommendedEvidenceKeys: ['generatorInputsHash', 'generatedRanges', 'replayCommand'],
+    notes: ['Generated or metaprogrammed declarations need replayable generator identity and input evidence.']
+  }),
+  reflection: nativeImportFeatureEvidencePolicy('reflection', {
+    category: 'reflection',
+    risk: 'high',
+    minimumReadiness: 'needs-review',
+    requiredEvidenceKeys: ['reflectionSurface', 'runtimeContract'],
+    recommendedEvidenceKeys: ['observedMembers', 'fixtureIds', 'runtimeVersion'],
+    notes: ['Reflection-heavy code needs a declared runtime contract because static AST evidence is incomplete.']
+  }),
+  dynamicRuntime: nativeImportFeatureEvidencePolicy('dynamicRuntime', {
+    category: 'reflection',
+    risk: 'high',
+    minimumReadiness: 'needs-review',
+    requiredEvidenceKeys: ['runtimeContract'],
+    recommendedEvidenceKeys: ['fixtureIds', 'observedEffects', 'runtimeVersion'],
+    notes: ['Dynamic runtime behavior should stay review-required until fixtures or traces describe the observed contract.']
+  }),
+  dynamicDispatch: nativeImportFeatureEvidencePolicy('dynamicDispatch', {
+    category: 'overloadTypeInference',
+    risk: 'medium',
+    minimumReadiness: 'needs-review',
+    requiredEvidenceKeys: ['dispatchTargets'],
+    recommendedEvidenceKeys: ['callGraphId', 'typeEvidenceId', 'fixtureIds'],
+    notes: ['Dynamic dispatch needs candidate target evidence before call graph or porting claims are merge-ready.']
+  }),
+  generatedCode: nativeImportFeatureEvidencePolicy('generatedCode', {
+    category: 'generatedCode',
+    risk: 'high',
+    minimumReadiness: 'needs-review',
+    requiredEvidenceKeys: ['generatedArtifactHash', 'generatedRanges'],
+    recommendedEvidenceKeys: ['generatorIdentity', 'generatorInputsHash', 'sourceMapId'],
+    notes: ['Generated code must preserve generated ranges and artifact hashes so workers can avoid editing derived output blindly.']
+  }),
+  overloadResolution: nativeImportFeatureEvidencePolicy('overloadResolution', {
+    category: 'overloadTypeInference',
+    risk: 'medium',
+    minimumReadiness: 'needs-review',
+    requiredEvidenceKeys: ['resolvedOverloads'],
+    recommendedEvidenceKeys: ['typeEvidenceId', 'compilerVersion', 'callSiteSpans'],
+    notes: ['Overload-sensitive imports should record compiler/type evidence for each call site.']
+  }),
+  typeInference: nativeImportFeatureEvidencePolicy('typeInference', {
+    category: 'overloadTypeInference',
+    risk: 'medium',
+    minimumReadiness: 'needs-review',
+    requiredEvidenceKeys: ['inferredTypesHash'],
+    recommendedEvidenceKeys: ['typeEvidenceId', 'compilerVersion', 'symbolTableHash'],
+    notes: ['Inferred types need a stable type-evidence hash before cross-language projection can claim fidelity.']
+  }),
+  unsupportedSyntax: nativeImportFeatureEvidencePolicy('unsupportedSyntax', {
+    category: 'unsupportedSyntax',
+    risk: 'high',
+    minimumReadiness: 'needs-review',
+    missingEvidenceReadiness: 'blocked',
+    requiredEvidenceKeys: ['unsupportedSyntaxKind', 'sourceSpan'],
+    recommendedEvidenceKeys: ['parserDiagnosticId', 'nativeAstNodeId', 'sourceSnippetHash'],
+    notes: ['Unsupported syntax must remain anchored to source spans and parser diagnostics for later adapter work.']
+  }),
+  unsupportedSemantic: nativeImportFeatureEvidencePolicy('unsupportedSemantic', {
+    category: 'unsupportedSyntax',
+    risk: 'high',
+    minimumReadiness: 'needs-review',
+    missingEvidenceReadiness: 'blocked',
+    requiredEvidenceKeys: ['unsupportedSemanticKind', 'semanticSymbolId'],
+    recommendedEvidenceKeys: ['semanticIndexId', 'sourceMapId', 'reason'],
+    notes: ['Unsupported semantics should name the affected symbol so merge tools can isolate the unsafe region.']
+  })
+});
+
 export const NativeImportRegionTaxonomyKinds = Object.freeze([
   'symbol',
   'declaration',
@@ -473,6 +591,70 @@ export function resolveCapabilityAdapters(document, target = 'typescript', optio
     });
 }
 
+export function getNativeImportFeatureEvidencePolicy(kind) {
+  const normalized = normalizeNativeLossKind({ kind }, 'warning');
+  return NativeImportFeatureEvidencePolicies[normalized] ?? NativeImportFeatureEvidencePolicies[String(kind ?? '')];
+}
+
+export function summarizeNativeImportFeatureEvidence(losses = [], options = {}) {
+  const normalizedLosses = normalizeNativeLossRecords(losses);
+  const evidence = options.evidence ?? [];
+  const issues = [];
+  const byKind = {};
+  const byRisk = {};
+  const policyKinds = [];
+  let highestRisk = 'low';
+  let semanticMergeReadiness = 'ready';
+
+  for (const loss of normalizedLosses) {
+    const policy = getNativeImportFeatureEvidencePolicy(loss.kind);
+    if (!policy) continue;
+    byKind[policy.kind] = (byKind[policy.kind] ?? 0) + 1;
+    byRisk[policy.risk] = (byRisk[policy.risk] ?? 0) + 1;
+    if ((nativeFeatureEvidenceRiskRank[policy.risk] ?? 0) > (nativeFeatureEvidenceRiskRank[highestRisk] ?? 0)) {
+      highestRisk = policy.risk;
+    }
+    policyKinds.push(policy.kind);
+    semanticMergeReadiness = maxSemanticMergeReadiness(semanticMergeReadiness, policy.minimumReadiness);
+    const missingRequiredEvidence = policy.requiredEvidenceKeys.filter((key) => !nativeImportFeatureEvidenceHasKey(loss, evidence, key));
+    const presentRequiredEvidence = policy.requiredEvidenceKeys.filter((key) => !missingRequiredEvidence.includes(key));
+    const presentRecommendedEvidence = policy.recommendedEvidenceKeys.filter((key) => nativeImportFeatureEvidenceHasKey(loss, evidence, key));
+    if (missingRequiredEvidence.length) {
+      semanticMergeReadiness = maxSemanticMergeReadiness(semanticMergeReadiness, policy.missingEvidenceReadiness);
+    }
+    issues.push({
+      lossId: loss.id,
+      kind: loss.kind,
+      policyKind: policy.kind,
+      risk: policy.risk,
+      category: policy.category,
+      readiness: missingRequiredEvidence.length ? policy.missingEvidenceReadiness : policy.minimumReadiness,
+      missingRequiredEvidence,
+      presentRequiredEvidence,
+      presentRecommendedEvidence,
+      evidenceIds: nativeImportFeatureEvidenceIds(loss, evidence, policy)
+    });
+  }
+
+  const missingRequiredEvidence = issues.flatMap((issue) => issue.missingRequiredEvidence.map((key) => ({
+    lossId: issue.lossId,
+    kind: issue.kind,
+    policyKind: issue.policyKind,
+    evidenceKey: key
+  })));
+  return {
+    total: issues.length,
+    policyKinds: uniqueStrings(policyKinds),
+    byKind,
+    byRisk,
+    highestRisk: issues.length ? highestRisk : 'low',
+    semanticMergeReadiness,
+    missingRequiredEvidence,
+    issues,
+    reasons: nativeImportFeatureEvidenceReasons(issues)
+  };
+}
+
 export function summarizeNativeImportLosses(losses = [], options = {}) {
   const normalizedLosses = normalizeNativeLossRecords(losses);
   const bySeverity = { info: 0, warning: 0, error: 0 };
@@ -512,6 +694,9 @@ export function summarizeNativeImportLosses(losses = [], options = {}) {
     reviewLossIds,
     informationalLossIds
   });
+  const featureEvidence = summarizeNativeImportFeatureEvidence(normalizedLosses, {
+    evidence: options.evidence
+  });
 
   return {
     total: normalizedLosses.length,
@@ -527,6 +712,7 @@ export function summarizeNativeImportLosses(losses = [], options = {}) {
     reviewLossIds,
     informationalLossIds,
     failedEvidenceIds,
+    featureEvidence,
     parser: options.parser,
     scanKind: options.scanKind,
     semanticStatus: options.semanticStatus
@@ -4112,6 +4298,61 @@ function nativeImportCategoryForLossKind(kind) {
   return String(kind ?? 'opaqueNative');
 }
 
+function nativeImportFeatureEvidencePolicy(kind, input = {}) {
+  return Object.freeze({
+    kind,
+    category: input.category ?? nativeImportCategoryForLossKind(kind),
+    risk: input.risk ?? 'medium',
+    minimumReadiness: normalizeSemanticMergeReadiness(input.minimumReadiness) ?? 'needs-review',
+    missingEvidenceReadiness: normalizeSemanticMergeReadiness(input.missingEvidenceReadiness) ?? 'needs-review',
+    requiredEvidenceKeys: Object.freeze(uniqueStrings(input.requiredEvidenceKeys ?? [])),
+    recommendedEvidenceKeys: Object.freeze(uniqueStrings(input.recommendedEvidenceKeys ?? [])),
+    notes: Object.freeze(uniqueStrings(input.notes ?? []))
+  });
+}
+
+function nativeImportFeatureEvidenceHasKey(loss, evidence, key) {
+  return nativeImportFeatureEvidenceValuePresent(nativeImportFeatureEvidenceValue(loss, key))
+    || (evidence ?? []).some((record) => nativeImportFeatureEvidenceValuePresent(nativeImportFeatureEvidenceValue(record, key)));
+}
+
+function nativeImportFeatureEvidenceValue(record, key) {
+  if (!record || !key) return undefined;
+  const candidates = [record, record.metadata].filter(Boolean);
+  for (const candidate of candidates) {
+    const direct = candidate[key];
+    if (direct !== undefined) return direct;
+    const dotted = String(key).split('.').reduce((current, part) => current?.[part], candidate);
+    if (dotted !== undefined) return dotted;
+  }
+  return undefined;
+}
+
+function nativeImportFeatureEvidenceValuePresent(value) {
+  if (value === undefined || value === null) return false;
+  if (typeof value === 'string') return value.trim().length > 0;
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === 'object') return Object.keys(value).length > 0;
+  return true;
+}
+
+function nativeImportFeatureEvidenceIds(loss, evidence, policy) {
+  const keys = [...policy.requiredEvidenceKeys, ...policy.recommendedEvidenceKeys];
+  return uniqueStrings((evidence ?? [])
+    .filter((record) => keys.some((key) => nativeImportFeatureEvidenceValuePresent(nativeImportFeatureEvidenceValue(record, key))))
+    .map((record) => record.id)
+    .filter(Boolean)
+    .concat(loss.evidenceIds ?? []));
+}
+
+function nativeImportFeatureEvidenceReasons(issues) {
+  return uniqueStrings((issues ?? []).flatMap((issue) => {
+    const missing = issue.missingRequiredEvidence ?? [];
+    if (!missing.length) return [];
+    return [`${issue.kind} loss ${issue.lossId} is missing required evidence: ${missing.join(', ')}.`];
+  }));
+}
+
 function normalizeProjectionMatrixTargets(targets) {
   return uniqueStrings((Array.isArray(targets) ? targets : [targets])
     .map((target) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshift-labs/frontier-lang-compiler",
-  "version": "0.2.21",
+  "version": "0.2.22",
   "description": "Compiler facade for Frontier Lang source documents and language projection adapters.",
   "type": "module",
   "main": "./dist/index.js",