@shapeshift-labs/frontier-lang-compiler 0.2.78 → 0.2.79

package/dist/declarations/semantic-history.d.ts

@@ -6,7 +6,7 @@ import type {
   SourceSpan
 } from '@shapeshift-labs/frontier-lang-kernel';
 import type { SemanticImportOwnershipRegion } from './semantic-sidecar.js';
-import type { CreateSemanticLineageEventInput, SemanticLineageEvent } from './semantic-lineage.js';
+import type { CreateSemanticLineageEventInput, SemanticAnchor, SemanticLineageEvent, SemanticLineageMap, SemanticLineageResolution } from './semantic-lineage.js';
 
 import type { SemanticHistoryAdmissionStatus, SemanticHistoryReviewerStatus, SemanticHistoryReplayLinkKind, SemanticHistoryOverlapKind, SemanticHistoryConflictReason, SemanticHistoryClaimKind, SemanticHistoryClaimStatus, SemanticHistoryProofAttemptStatus, SemanticHistoryMergeDecisionStatus, SemanticHistoryActorRef, SemanticHistoryRecordSourceRef, SemanticHistorySourceRef, SemanticHistoryOwnershipRegionRef, SemanticHistoryCandidateRef, SemanticHistoryClaimRecord, SemanticHistoryImportedParserEvidenceRecord, SemanticHistoryProofAttemptRecord, SemanticHistoryPatchAncestryRecord, SemanticHistoryMergeDecisionRecord, SemanticHistoryClaimInput, SemanticHistoryImportedParserEvidenceInput, SemanticHistoryProofAttemptInput, SemanticHistoryPatchAncestryInput, SemanticHistoryMergeDecisionInput, SemanticHistoryReviewerState, SemanticHistoryAdmissionState, SemanticHistoryReplayLink, SemanticHistoryRecordIndex } from './semantic-history-records.js';
 export type { SemanticHistoryAdmissionStatus, SemanticHistoryReviewerStatus, SemanticHistoryReplayLinkKind, SemanticHistoryOverlapKind, SemanticHistoryConflictReason, SemanticHistoryClaimKind, SemanticHistoryClaimStatus, SemanticHistoryProofAttemptStatus, SemanticHistoryMergeDecisionStatus, SemanticHistoryActorRef, SemanticHistoryRecordSourceRef, SemanticHistorySourceRef, SemanticHistoryOwnershipRegionRef, SemanticHistoryCandidateRef, SemanticHistoryClaimRecord, SemanticHistoryImportedParserEvidenceRecord, SemanticHistoryProofAttemptRecord, SemanticHistoryPatchAncestryRecord, SemanticHistoryMergeDecisionRecord, SemanticHistoryClaimInput, SemanticHistoryImportedParserEvidenceInput, SemanticHistoryProofAttemptInput, SemanticHistoryPatchAncestryInput, SemanticHistoryMergeDecisionInput, SemanticHistoryReviewerState, SemanticHistoryAdmissionState, SemanticHistoryReplayLink, SemanticHistoryRecordIndex } from './semantic-history-records.js';
@@ -138,6 +138,51 @@ export interface SemanticHistoryOverlapRecord {
   readonly reviewer: { readonly left?: SemanticHistoryReviewerStatus; readonly right?: SemanticHistoryReviewerStatus };
 }
 
+export type SemanticHistoryLineageAnchorSetKind = 'active' | 'candidate' | 'inactive' | 'deleted' | 'unresolved' | 'blocked';
+
+export interface SemanticHistoryLineageAnchorRecord extends Pick<SemanticAnchor, 'key' | 'id' | 'kind' | 'language' | 'sourcePath' | 'symbolId' | 'symbolName'> {
+  readonly status: string;
+  readonly resolutionId: string;
+  readonly reasonCodes: readonly string[];
+}
+
+export type SemanticHistoryLineageAnchorInventory = Readonly<Record<SemanticHistoryLineageAnchorSetKind, readonly SemanticHistoryLineageAnchorRecord[]>>;
+
+export interface SemanticHistoryRecordLineageResolution {
+  readonly kind: 'frontier.lang.semanticHistoryRecordLineageResolution';
+  readonly version: 1;
+  readonly id: string;
+  readonly stableId: string;
+  readonly hash: string;
+  readonly sourceRecordId?: string;
+  readonly sourceRecordStableId?: string;
+  readonly sourceRecordHash?: string;
+  readonly generatedAt: number | string;
+  readonly resolutions: readonly SemanticLineageResolution[];
+  readonly anchorInventory: SemanticHistoryLineageAnchorInventory;
+  readonly resolvedRecord: SemanticHistoryRecord;
+  readonly summary: Record<string, unknown> & {
+    readonly anchorCount: number;
+    readonly currentAnchorKeys: readonly string[];
+    readonly ownershipKeys: readonly string[];
+    readonly conflictKeys: readonly string[];
+    readonly activeAnchorKeys: readonly string[];
+    readonly candidateAnchorKeys: readonly string[];
+    readonly inactiveAnchorKeys: readonly string[];
+    readonly deletedAnchorKeys: readonly string[];
+    readonly unresolvedAnchorKeys: readonly string[];
+    readonly blockedAnchorKeys: readonly string[];
+    readonly reasonCodes: readonly string[];
+  };
+  readonly admission: {
+    readonly readiness: SemanticMergeReadiness | string;
+    readonly reviewRequired: boolean;
+    readonly autoMergeClaim: false;
+    readonly semanticEquivalenceClaim: false;
+  };
+  readonly metadata?: Record<string, unknown>;
+}
+
 export declare const SemanticHistoryAdmissionStatuses: readonly SemanticHistoryAdmissionStatus[];
 export declare const SemanticHistoryReviewerStatuses: readonly SemanticHistoryReviewerStatus[];
 export declare const SemanticHistoryOverlapKinds: readonly SemanticHistoryOverlapKind[];
@@ -146,3 +191,5 @@ export declare function createSemanticHistoryRecord(input?: CreateSemanticHistor
 export declare function querySemanticHistoryRecordOverlaps(records: SemanticHistoryRecord | readonly SemanticHistoryRecord[], options?: SemanticHistoryOverlapQueryOptions): readonly SemanticHistoryOverlapRecord[];
 export declare function semanticHistoryRecordsOverlap(left: SemanticHistoryRecord, right: SemanticHistoryRecord, options?: SemanticHistoryOverlapQueryOptions): boolean;
 export declare function semanticHistoryRecordsConflict(left: SemanticHistoryRecord, right: SemanticHistoryRecord, options?: SemanticHistoryOverlapQueryOptions): boolean;
+export declare function resolveSemanticHistoryRecordLineage(record: SemanticHistoryRecord, eventsOrMap?: SemanticLineageMap | readonly CreateSemanticLineageEventInput[], options?: { readonly id?: string; readonly generatedAt?: number | string; readonly maxDepth?: number; readonly keepDeletedAnchors?: boolean; readonly keepCandidateAnchors?: boolean; readonly keepBlockedAnchors?: boolean; readonly keepUnresolvedAnchors?: boolean; readonly metadata?: Record<string, unknown> }): SemanticHistoryRecordLineageResolution;
+export declare function resolveSemanticHistoryRecordsLineage(records: readonly SemanticHistoryRecord[] | SemanticHistoryRecord, eventsOrMap?: SemanticLineageMap | readonly CreateSemanticLineageEventInput[], options?: { readonly generatedAt?: number | string; readonly maxDepth?: number; readonly keepDeletedAnchors?: boolean; readonly keepCandidateAnchors?: boolean; readonly keepBlockedAnchors?: boolean; readonly keepUnresolvedAnchors?: boolean; readonly metadata?: Record<string, unknown> }): readonly SemanticHistoryRecordLineageResolution[];

package/dist/index.js

@@ -73,6 +73,7 @@ export { queryUniversalConversionPlan } from './internal/index-impl/queryUnivers
 export { createSemanticAnchor, createSemanticLineageEvent, createSemanticLineageMap, querySemanticLineageEvents, SemanticLineageEventKinds } from './internal/index-impl/semanticLineageRecords.js';
 export { resolveSemanticLineage, resolveSemanticLineageBatch, SemanticLineageResolutionStatuses } from './internal/index-impl/semanticLineageResolutionRecords.js';
 export { createSemanticHistoryRecord, querySemanticHistoryRecordOverlaps, SemanticHistoryAdmissionStatuses, SemanticHistoryConflictReasons, SemanticHistoryOverlapKinds, SemanticHistoryReviewerStatuses, semanticHistoryRecordsConflict, semanticHistoryRecordsOverlap } from './internal/index-impl/semanticHistoryRecords.js';
+export { resolveSemanticHistoryRecordLineage, resolveSemanticHistoryRecordsLineage } from './internal/index-impl/semanticHistoryLineageResolution.js';
 export { readSemanticSliceJson } from './internal/index-impl/readSemanticSliceJson.js';
 export { readUniversalAstJson } from './internal/index-impl/readUniversalAstJson.js';
 export { renderTargetAst } from './internal/index-impl/renderTargetAst.js';

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

@@ -0,0 +1,256 @@
+import { hashSemanticValue } from '@shapeshift-labs/frontier-lang-kernel';
+import { idFragment, uniqueStrings as uniqueRawStrings } from '../../native-import-utils.js';
+import { resolveSemanticLineage } from './semanticLineageResolutionRecords.js';
+
+export function resolveSemanticHistoryRecordLineage(record = {}, eventsOrMap = [], options = {}) {
+  const generatedAt = options.generatedAt ?? Date.now();
+  const sourceIndex = record.index ?? {};
+  const anchorKeys = uniqueStrings([
+    ...array(sourceIndex.semanticAnchorKeys),
+    ...array(sourceIndex.ownershipKeys),
+    ...array(sourceIndex.conflictKeys)
+  ]);
+  const resolutions = anchorKeys.map((anchorKey) => resolveSemanticLineage(eventsOrMap, {
+    anchorKey,
+    generatedAt
+  }, { maxDepth: options.maxDepth }));
+  const byAnchorKey = new Map(resolutions.map((resolution) => [resolution.query.anchorKey, resolution]));
+  const resolvedIndex = {
+    ...sourceIndex,
+    ownershipKeys: resolveIndexKeys(sourceIndex.ownershipKeys, byAnchorKey, options),
+    conflictKeys: resolveIndexKeys(sourceIndex.conflictKeys, byAnchorKey, options),
+    semanticAnchorKeys: resolveIndexKeys(sourceIndex.semanticAnchorKeys, byAnchorKey, options),
+    sourcePaths: uniqueStrings([
+      ...array(sourceIndex.sourcePaths),
+      ...resolutions.flatMap((resolution) => resolution.currentAnchors.map((anchor) => anchor.sourcePath))
+    ]),
+    lineageEventIds: uniqueStrings([
+      ...array(sourceIndex.lineageEventIds),
+      ...resolutions.flatMap((resolution) => resolution.traversedEventIds)
+    ]),
+    semanticLineageKinds: uniqueStrings([
+      ...array(sourceIndex.semanticLineageKinds),
+      ...resolutions.flatMap((resolution) => resolution.lineageEventKinds)
+    ]),
+    crdtOperationIds: uniqueStrings([
+      ...array(sourceIndex.crdtOperationIds),
+      ...resolutions.flatMap((resolution) => resolution.crdtOperationIds)
+    ]),
+    crdtHeads: uniqueStrings([
+      ...array(sourceIndex.crdtHeads),
+      ...resolutions.flatMap((resolution) => resolution.crdtHeads)
+    ]),
+    evidenceIds: uniqueStrings([
+      ...array(sourceIndex.evidenceIds),
+      ...resolutions.flatMap((resolution) => resolution.evidenceIds)
+    ]),
+    proofIds: uniqueStrings([
+      ...array(sourceIndex.proofIds),
+      ...resolutions.flatMap((resolution) => resolution.proofIds)
+    ])
+  };
+  const anchorInventory = createAnchorInventory(resolutions);
+  const summary = summarizeSemanticHistoryLineageResolutions(resolutions, resolvedIndex, anchorInventory);
+  const readiness = summary.cycle > 0 || summary.maxDepth > 0 ? 'blocked' : summary.resolved > 0 || summary.ambiguous > 0 || summary.deleted > 0 || summary.recreated > 0 ? 'needs-review' : 'ready';
+  const resolutionCore = {
+    kind: 'frontier.lang.semanticHistoryRecordLineageResolution',
+    version: 1,
+    sourceRecordId: record.id,
+    sourceRecordStableId: record.stableId,
+    sourceRecordHash: record.hash,
+    generatedAt,
+    resolutions,
+    anchorInventory,
+    summary,
+    admission: {
+      readiness,
+      reviewRequired: readiness !== 'ready',
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false
+    },
+    metadata: compactRecord(options.metadata)
+  };
+  const hash = hashSemanticValue(resolutionCore);
+  const id = options.id ?? `semantic_history_lineage_resolution_${idFragment(firstString(record.id, record.stableId, hash))}`;
+  const resolvedRecord = createResolvedHistoryRecord(record, resolvedIndex, { id, hash, generatedAt, summary, readiness });
+  return {
+    ...resolutionCore,
+    id,
+    stableId: `semantic_history_lineage_resolution_${idFragment(hash)}`,
+    hash,
+    resolvedRecord
+  };
+}
+
+export function resolveSemanticHistoryRecordsLineage(records = [], eventsOrMap = [], options = {}) {
+  return array(records).map((record) => resolveSemanticHistoryRecordLineage(record, eventsOrMap, options));
+}
+
+function createResolvedHistoryRecord(record, index, resolution) {
+  const core = {
+    ...record,
+    id: `${record.id ?? 'semantic_history'}#lineage-resolved`,
+    index,
+    metadata: {
+      ...(record.metadata ?? {}),
+      semanticHistoryLineageResolution: {
+        id: resolution.id,
+        sourceRecordId: record.id,
+        sourceRecordHash: record.hash,
+        readiness: resolution.readiness,
+        summary: resolution.summary,
+        anchorSummary: {
+          activeAnchorKeys: resolution.summary.activeAnchorKeys,
+          candidateAnchorKeys: resolution.summary.candidateAnchorKeys,
+          inactiveAnchorKeys: resolution.summary.inactiveAnchorKeys,
+          blockedAnchorKeys: resolution.summary.blockedAnchorKeys
+        },
+        autoMergeClaim: false,
+        semanticEquivalenceClaim: false
+      }
+    }
+  };
+  const stableCore = { ...core };
+  delete stableCore.hash;
+  delete stableCore.stableId;
+  const hash = hashSemanticValue(stableCore);
+  return {
+    ...core,
+    stableId: `semantic_history_${idFragment(hash)}`,
+    hash
+  };
+}
+
+function resolveIndexKeys(values, resolutions, options) {
+  return uniqueStrings(array(values).flatMap((value) => {
+    const key = String(value);
+    const resolution = resolutions.get(key);
+    if (!resolution) return [key];
+    if (resolution.status === 'deleted' && options.keepDeletedAnchors !== true) return [];
+    if (resolution.status === 'cycle' && options.keepBlockedAnchors !== true) return [];
+    if (resolution.status === 'max-depth' && options.keepBlockedAnchors !== true) return [];
+    if (resolution.status === 'not-found' && options.keepUnresolvedAnchors !== true) return [];
+    if (resolution.status === 'ambiguous' && options.keepCandidateAnchors === false) return [];
+    const current = resolution.currentAnchors.map((anchor) => anchor.key).filter(Boolean);
+    return current.length ? current : [key];
+  }));
+}
+
+function summarizeSemanticHistoryLineageResolutions(resolutions, index, anchorInventory) {
+  const byStatus = {};
+  for (const resolution of resolutions) byStatus[resolution.status] = (byStatus[resolution.status] ?? 0) + 1;
+  return {
+    anchorCount: resolutions.length,
+    unchanged: byStatus.unchanged ?? 0,
+    resolved: byStatus.resolved ?? 0,
+    ambiguous: byStatus.ambiguous ?? 0,
+    deleted: byStatus.deleted ?? 0,
+    recreated: byStatus.recreated ?? 0,
+    cycle: byStatus.cycle ?? 0,
+    maxDepth: byStatus['max-depth'] ?? 0,
+    notFound: byStatus['not-found'] ?? 0,
+    currentAnchorKeys: uniqueStrings(index.semanticAnchorKeys),
+    ownershipKeys: uniqueStrings(index.ownershipKeys),
+    conflictKeys: uniqueStrings(index.conflictKeys),
+    sourcePaths: uniqueStrings(index.sourcePaths),
+    activeAnchorKeys: uniqueStrings(anchorInventory.active.map((anchor) => anchor.key)),
+    candidateAnchorKeys: uniqueStrings(anchorInventory.candidate.map((anchor) => anchor.key)),
+    inactiveAnchorKeys: uniqueStrings(anchorInventory.inactive.map((anchor) => anchor.key)),
+    deletedAnchorKeys: uniqueStrings(anchorInventory.deleted.map((anchor) => anchor.key)),
+    unresolvedAnchorKeys: uniqueStrings(anchorInventory.unresolved.map((anchor) => anchor.key)),
+    blockedAnchorKeys: uniqueStrings(anchorInventory.blocked.map((anchor) => anchor.key)),
+    traversedEventIds: uniqueStrings(resolutions.flatMap((resolution) => resolution.traversedEventIds)),
+    terminalEventIds: uniqueStrings(resolutions.flatMap((resolution) => resolution.terminalEventIds)),
+    reasonCodes: uniqueStrings(resolutions.flatMap((resolution) => resolution.reasonCodes))
+  };
+}
+
+function createAnchorInventory(resolutions) {
+  const inventory = {
+    active: [],
+    candidate: [],
+    inactive: [],
+    deleted: [],
+    unresolved: [],
+    blocked: []
+  };
+  for (const resolution of resolutions) {
+    const start = anchorEntry(resolution.startAnchor ?? queryAnchor(resolution), resolution);
+    const current = resolution.currentAnchors.map((anchor) => anchorEntry(anchor, resolution));
+    if (resolution.status === 'ambiguous') {
+      inventory.candidate.push(...current);
+      if (start) inventory.inactive.push(start);
+      continue;
+    }
+    if (resolution.status === 'deleted') {
+      if (start) {
+        inventory.inactive.push(start);
+        inventory.deleted.push(start);
+      }
+      continue;
+    }
+    if (resolution.status === 'cycle' || resolution.status === 'max-depth') {
+      if (start) {
+        inventory.inactive.push(start);
+        inventory.blocked.push(start);
+      }
+      continue;
+    }
+    if (resolution.status === 'not-found') {
+      if (start) {
+        inventory.inactive.push(start);
+        inventory.unresolved.push(start);
+      }
+      continue;
+    }
+    inventory.active.push(...current);
+  }
+  return {
+    active: uniqueAnchorEntries(inventory.active),
+    candidate: uniqueAnchorEntries(inventory.candidate),
+    inactive: uniqueAnchorEntries(inventory.inactive),
+    deleted: uniqueAnchorEntries(inventory.deleted),
+    unresolved: uniqueAnchorEntries(inventory.unresolved),
+    blocked: uniqueAnchorEntries(inventory.blocked)
+  };
+}
+
+function anchorEntry(anchor, resolution) {
+  if (!anchor) return undefined;
+  return compactRecord({
+    key: anchor.key,
+    id: anchor.id,
+    kind: anchor.kind,
+    language: anchor.language,
+    sourcePath: anchor.sourcePath,
+    symbolId: anchor.symbolId,
+    symbolName: anchor.symbolName,
+    status: resolution.status,
+    resolutionId: resolution.id,
+    reasonCodes: uniqueStrings(resolution.reasonCodes)
+  });
+}
+
+function queryAnchor(resolution) {
+  return compactRecord({
+    key: resolution.query?.anchorKey,
+    id: resolution.query?.anchorId,
+    sourcePath: resolution.query?.sourcePath,
+    symbolName: resolution.query?.symbolName
+  });
+}
+
+function uniqueAnchorEntries(entries) {
+  const seen = new Set();
+  return entries.filter(Boolean).filter((entry) => {
+    const key = entry.key ?? entry.id ?? `${entry.sourcePath ?? ''}:${entry.symbolName ?? ''}`;
+    if (!key || seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function array(value) { return value === undefined || value === null ? [] : Array.isArray(value) ? value : [value]; }
+function uniqueStrings(values) { return uniqueRawStrings(array(values).map((value) => String(value ?? '')).filter(Boolean)); }
+function firstString(...values) { return values.map((value) => value === undefined || value === null ? '' : String(value)).find(Boolean); }
+function compactRecord(value) { return Object.fromEntries(Object.entries(value ?? {}).filter(([, entry]) => entry !== undefined)); }

package/package.json

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