@specferret/core 0.1.0

package/dist/extractor/validator.js

@@ -0,0 +1,141 @@
+// Pure function. No I/O. No side effects. Ever.
+// Validator layer — validates JSON Schema subset, classifies breaking/non-breaking/no-change.
+/**
+ * JSON Schema keywords that are explicitly NOT supported by Ferret.
+ * If any appear in a schema, a warning is emitted but the schema is still accepted.
+ * See: spec/CONTRACT-SCHEMA.md — Part 3
+ */
+const UNSUPPORTED_KEYWORDS = [
+    '$ref', 'allOf', 'anyOf', 'oneOf', 'not',
+    'if', 'then', 'else', '$defs', 'definitions',
+    'patternProperties', 'dependencies',
+];
+/**
+ * Validates a schema object against the Ferret JSON Schema subset.
+ * Always returns valid: true — unsupported keywords produce warnings, not errors.
+ */
+export function validateFerretSchema(shape, filePath) {
+    const warnings = [];
+    if (shape === null || typeof shape !== 'object') {
+        return { valid: true, warnings };
+    }
+    const serialised = JSON.stringify(shape);
+    for (const keyword of UNSUPPORTED_KEYWORDS) {
+        // Match the keyword as a JSON object key (surrounded by quotes)
+        if (serialised.includes(`"${keyword}"`)) {
+            warnings.push(`⚠ Unsupported JSON Schema keyword: ${keyword} in ${filePath}\n` +
+                `  Ferret supports a subset of JSON Schema.\n` +
+                `  See: spec/CONTRACT-SCHEMA.md — Part 3`);
+        }
+    }
+    return { valid: true, warnings };
+}
+/**
+ * Compares two schema objects and classifies the change.
+ *
+ * Breaking:     required field removed, field type changed, enum value removed,
+ *               response/array type changed, required field added
+ * Non-breaking: optional field added, enum value added
+ * No-change:    property order changed, whitespace, required array reordered
+ */
+export function compareSchemas(previous, current) {
+    // Normalise: work with plain objects only
+    const prev = (typeof previous === 'object' && previous !== null ? previous : {});
+    const curr = (typeof current === 'object' && current !== null ? current : {});
+    // 1. Check type change at this level
+    if (prev.type !== undefined && curr.type !== undefined && prev.type !== curr.type) {
+        return { classification: 'breaking', reason: `type changed from '${prev.type}' to '${curr.type}'` };
+    }
+    // 2. Check required fields
+    const prevRequired = normaliseRequired(prev.required);
+    const currRequired = normaliseRequired(curr.required);
+    const removedRequired = prevRequired.filter(f => !currRequired.includes(f));
+    if (removedRequired.length > 0) {
+        return { classification: 'breaking', reason: `required field(s) removed: ${removedRequired.join(', ')}` };
+    }
+    const addedRequired = currRequired.filter(f => !prevRequired.includes(f));
+    if (addedRequired.length > 0) {
+        return { classification: 'breaking', reason: `required field(s) added: ${addedRequired.join(', ')}` };
+    }
+    // 3. Check enum changes
+    const prevEnum = normaliseEnum(prev.enum);
+    const currEnum = normaliseEnum(curr.enum);
+    if (prevEnum !== null && currEnum !== null) {
+        const removedEnum = prevEnum.filter(v => !currEnum.includes(v));
+        if (removedEnum.length > 0) {
+            return { classification: 'breaking', reason: `enum value(s) removed: ${removedEnum.join(', ')}` };
+        }
+        const addedEnum = currEnum.filter(v => !prevEnum.includes(v));
+        if (addedEnum.length > 0) {
+            return { classification: 'non-breaking', reason: `enum value(s) added: ${addedEnum.join(', ')}` };
+        }
+    }
+    // 4. Check properties — look for type changes in existing properties, or optional additions
+    const prevProps = (prev.properties ?? {});
+    const currProps = (curr.properties ?? {});
+    for (const key of Object.keys(currProps)) {
+        if (!(key in prevProps)) {
+            // New property — only breaking if it's also in required (already caught above)
+            if (currRequired.includes(key)) {
+                return { classification: 'breaking', reason: `required field added: ${key}` };
+            }
+            // Not required — non-breaking addition
+            continue;
+        }
+        // Property exists in both — check for type change recursively
+        const nested = compareSchemas(prevProps[key], currProps[key]);
+        if (nested.classification === 'breaking') {
+            return { classification: 'breaking', reason: `property '${key}': ${nested.reason}` };
+        }
+        if (nested.classification === 'non-breaking') {
+            return { classification: 'non-breaking', reason: `property '${key}': ${nested.reason}` };
+        }
+    }
+    // 5. Check for property removals (any removal is breaking — even "optional" fields
+    //    that consumers may depend on)
+    for (const key of Object.keys(prevProps)) {
+        if (!(key in currProps)) {
+            return { classification: 'breaking', reason: `property '${key}' removed` };
+        }
+    }
+    // 6. Check request/response top-level wrappers (Ferret API extension)
+    for (const wrapper of ['request', 'response']) {
+        if (prev[wrapper] !== undefined || curr[wrapper] !== undefined) {
+            const nested = compareSchemas(prev[wrapper] ?? {}, curr[wrapper] ?? {});
+            if (nested.classification === 'breaking') {
+                return { classification: 'breaking', reason: `${wrapper}: ${nested.reason}` };
+            }
+            if (nested.classification === 'non-breaking') {
+                return { classification: 'non-breaking', reason: `${wrapper}: ${nested.reason}` };
+            }
+        }
+    }
+    // 7. Check array items type change
+    if (prev.items !== undefined && curr.items !== undefined) {
+        const nested = compareSchemas(prev.items, curr.items);
+        if (nested.classification === 'breaking') {
+            return { classification: 'breaking', reason: `array items: ${nested.reason}` };
+        }
+        if (nested.classification === 'non-breaking') {
+            return { classification: 'non-breaking', reason: `array items: ${nested.reason}` };
+        }
+    }
+    // 8. Check if a new optional property was added (non-breaking)
+    const newOptionalKeys = Object.keys(currProps).filter(k => !(k in prevProps) && !currRequired.includes(k));
+    if (newOptionalKeys.length > 0) {
+        return { classification: 'non-breaking', reason: `optional field(s) added: ${newOptionalKeys.join(', ')}` };
+    }
+    return { classification: 'no-change', reason: 'schemas are semantically identical' };
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function normaliseRequired(required) {
+    if (!Array.isArray(required))
+        return [];
+    return required.filter((v) => typeof v === 'string');
+}
+function normaliseEnum(enumVal) {
+    if (!Array.isArray(enumVal))
+        return null;
+    return enumVal.map(v => String(v));
+}
+//# sourceMappingURL=validator.js.map

package/dist/extractor/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../src/extractor/validator.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./extractor/frontmatter.js";
+export * from "./extractor/typescript.js";
+export * from "./extractor/validator.js";
+export * from "./extractor/hash.js";
+export * from "./context/index.js";
+export * from "./store/types.js";
+export * from "./store/sqlite.js";
+export * from "./store/factory.js";
+export * from "./reconciler/index.js";
+export * from "./reconciler/import-suggestions.js";
+export * from "./config.js";
+export * from "./utils/paths.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oCAAoC,CAAC;AACnD,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+// @specferret/core public API
+// Do not export llm-fallback — dynamic import only, never a default export.
+export * from "./extractor/frontmatter.js";
+export * from "./extractor/typescript.js";
+export * from "./extractor/validator.js";
+export * from "./extractor/hash.js";
+export * from "./context/index.js";
+export * from "./store/types.js";
+export * from "./store/sqlite.js";
+export * from "./store/factory.js";
+export * from "./reconciler/index.js";
+export * from "./reconciler/import-suggestions.js";
+export * from "./config.js";
+export * from "./utils/paths.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAC9B,4EAA4E;AAE5E,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oCAAoC,CAAC;AACnD,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC"}

package/dist/reconciler/import-suggestions.d.ts

@@ -0,0 +1,10 @@
+import { FerretContract, FerretDependency, FerretNode } from "../store/types.js";
+export interface ImportSuggestion {
+    sourceContractId: string;
+    sourceFilePath: string;
+    suggestedImportId: string;
+    confidence: "medium" | "high";
+    evidence: string;
+}
+export declare function suggestMissingImports(nodes: FerretNode[], contracts: FerretContract[], dependencies: FerretDependency[]): ImportSuggestion[];
+//# sourceMappingURL=import-suggestions.d.ts.map

package/dist/reconciler/import-suggestions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-suggestions.d.ts","sourceRoot":"","sources":["../../src/reconciler/import-suggestions.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,UAAU,EACX,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,UAAU,EAAE,EACnB,SAAS,EAAE,cAAc,EAAE,EAC3B,YAAY,EAAE,gBAAgB,EAAE,GAC/B,gBAAgB,EAAE,CAgGpB"}

package/dist/reconciler/import-suggestions.js

@@ -0,0 +1,110 @@
+export function suggestMissingImports(nodes, contracts, dependencies) {
+    const nodeById = new Map(nodes.map((node) => [node.id, node]));
+    const nodeImportMap = new Map();
+    for (const dependency of dependencies) {
+        const imports = nodeImportMap.get(dependency.source_node_id) ?? new Set();
+        imports.add(dependency.target_contract_id);
+        nodeImportMap.set(dependency.source_node_id, imports);
+    }
+    const schemaKeysByContract = new Map();
+    for (const contract of contracts) {
+        schemaKeysByContract.set(contract.id, extractSchemaKeys(parseSchema(contract.shape_schema)));
+    }
+    const suggestions = [];
+    const seen = new Set();
+    for (const source of contracts) {
+        const sourceKeys = schemaKeysByContract.get(source.id) ?? new Set();
+        if (sourceKeys.size === 0) {
+            continue;
+        }
+        const importedTargets = nodeImportMap.get(source.node_id) ?? new Set();
+        const sourceNode = nodeById.get(source.node_id);
+        if (!sourceNode) {
+            continue;
+        }
+        const rankedCandidates = contracts
+            .filter((target) => target.id !== source.id && !importedTargets.has(target.id))
+            .map((target) => {
+            const targetKeys = schemaKeysByContract.get(target.id) ?? new Set();
+            const sharedKeys = intersectSets(sourceKeys, targetKeys);
+            const overlap = sourceKeys.size === 0 ? 0 : sharedKeys.length / sourceKeys.size;
+            return {
+                target,
+                targetKeys,
+                sharedKeys,
+                overlap,
+            };
+        })
+            .filter((candidate) => candidate.sharedKeys.length >= 2 &&
+            candidate.overlap >= 0.67 &&
+            candidate.targetKeys.size >= sourceKeys.size)
+            .sort((left, right) => {
+            if (right.sharedKeys.length !== left.sharedKeys.length) {
+                return right.sharedKeys.length - left.sharedKeys.length;
+            }
+            if (right.overlap !== left.overlap) {
+                return right.overlap - left.overlap;
+            }
+            return left.target.id.localeCompare(right.target.id);
+        })
+            .slice(0, 3);
+        for (const candidate of rankedCandidates) {
+            const confidence = candidate.sharedKeys.length >= 3 || candidate.overlap >= 0.75
+                ? "high"
+                : "medium";
+            const key = `${source.id}->${candidate.target.id}`;
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            suggestions.push({
+                sourceContractId: source.id,
+                sourceFilePath: sourceNode.file_path,
+                suggestedImportId: candidate.target.id,
+                confidence,
+                evidence: `shared shape keys: ${candidate.sharedKeys.slice(0, 3).join(", ")}`,
+            });
+        }
+    }
+    return suggestions.sort((left, right) => {
+        if (left.sourceContractId !== right.sourceContractId) {
+            return left.sourceContractId.localeCompare(right.sourceContractId);
+        }
+        return left.suggestedImportId.localeCompare(right.suggestedImportId);
+    });
+}
+function parseSchema(shapeSchema) {
+    try {
+        return JSON.parse(shapeSchema);
+    }
+    catch {
+        return {};
+    }
+}
+function extractSchemaKeys(schema) {
+    const keys = new Set();
+    const walk = (value) => {
+        if (!value || typeof value !== "object") {
+            return;
+        }
+        const record = value;
+        const properties = record.properties;
+        if (properties && typeof properties === "object") {
+            for (const [key, child] of Object.entries(properties)) {
+                keys.add(key);
+                walk(child);
+            }
+        }
+        const items = record.items;
+        if (items) {
+            walk(items);
+        }
+    };
+    walk(schema);
+    return keys;
+}
+function intersectSets(left, right) {
+    const shared = [...left].filter((item) => right.has(item));
+    return shared.sort((a, b) => a.localeCompare(b));
+}
+//# sourceMappingURL=import-suggestions.js.map

package/dist/reconciler/import-suggestions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-suggestions.js","sourceRoot":"","sources":["../../src/reconciler/import-suggestions.ts"],"names":[],"mappings":"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"}

package/dist/reconciler/index.d.ts

@@ -0,0 +1,53 @@
+import { DBStore } from "../store/types.js";
+import { ImportSuggestion } from "./import-suggestions.js";
+export interface UnresolvedImportViolation {
+    contractId: string;
+    filePath: string;
+    importPath: string;
+}
+export interface SelfImportViolation {
+    contractId: string;
+    filePath: string;
+    importPath: string;
+}
+export interface CircularImportViolation {
+    contractId: string;
+    filePath: string;
+    importPath: string;
+    cycle: string[];
+}
+export interface ImportIntegrityReport {
+    unresolvedImports: UnresolvedImportViolation[];
+    selfImports: SelfImportViolation[];
+    circularImports: CircularImportViolation[];
+}
+export interface ReconcileReport {
+    consistent: boolean;
+    flagged: Array<{
+        nodeId: string;
+        filePath: string;
+        triggeredByContractId: string;
+        impact: "direct" | "transitive";
+        depth: number;
+    }>;
+    integrityViolations: ImportIntegrityReport;
+    importSuggestions: ImportSuggestion[];
+    timestamp: string;
+}
+/**
+ * The Reconciler engine (Phase 3).
+ * It calculates the downstream impact of graph shape changes. Since resolving recursive graphs
+ * can be heavily database dependent, we execute an Application-level Breadth-First Search (BFS)
+ * to maintain 100% parity across SQLite and PostgreSQL effortlessly and stay extremely fast.
+ */
+export declare class Reconciler {
+    private store;
+    constructor(store: DBStore);
+    /**
+     * Identifies completely unhandled ripples and propagates them up to 10 hops (S011)
+     */
+    reconcile(): Promise<ReconcileReport>;
+    private validateImportIntegrity;
+    private findCircularImports;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/reconciler/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/reconciler/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EAIR,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,gBAAgB,EAEjB,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC,iBAAiB,EAAE,yBAAyB,EAAE,CAAC;IAC/C,WAAW,EAAE,mBAAmB,EAAE,CAAC;IACnC,eAAe,EAAE,uBAAuB,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,KAAK,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,qBAAqB,EAAE,MAAM,CAAC;QAC9B,MAAM,EAAE,QAAQ,GAAG,YAAY,CAAC;QAChC,KAAK,EAAE,MAAM,CAAC;KACf,CAAC,CAAC;IACH,mBAAmB,EAAE,qBAAqB,CAAC;IAC3C,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IACtC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,qBAAa,UAAU;IACT,OAAO,CAAC,KAAK;gBAAL,KAAK,EAAE,OAAO;IAElC;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,eAAe,CAAC;IAgH3C,OAAO,CAAC,uBAAuB;IAwF/B,OAAO,CAAC,mBAAmB;CAsD5B"}

package/dist/reconciler/index.js

@@ -0,0 +1,214 @@
+import { suggestMissingImports, } from "./import-suggestions.js";
+/**
+ * The Reconciler engine (Phase 3).
+ * It calculates the downstream impact of graph shape changes. Since resolving recursive graphs
+ * can be heavily database dependent, we execute an Application-level Breadth-First Search (BFS)
+ * to maintain 100% parity across SQLite and PostgreSQL effortlessly and stay extremely fast.
+ */
+export class Reconciler {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    /**
+     * Identifies completely unhandled ripples and propagates them up to 10 hops (S011)
+     */
+    async reconcile() {
+        const nodes = await this.store.getNodes();
+        const contracts = await this.store.getContracts();
+        const dependencies = await this.store.getDependencies();
+        const integrityViolations = this.validateImportIntegrity(nodes, contracts, dependencies);
+        const hasIntegrityViolations = integrityViolations.unresolvedImports.length > 0 ||
+            integrityViolations.selfImports.length > 0 ||
+            integrityViolations.circularImports.length > 0;
+        if (hasIntegrityViolations) {
+            return {
+                consistent: false,
+                flagged: [],
+                integrityViolations,
+                importSuggestions: [],
+                timestamp: new Date().toISOString(),
+            };
+        }
+        const importSuggestions = suggestMissingImports(nodes, contracts, dependencies);
+        const nodeMap = new Map(nodes.map((n) => [n.id, n]));
+        const contractMap = new Map(contracts.map((c) => [c.id, c]));
+        // 1. Identify "changed/trigger" contracts.
+        // In our simplified engine approach, any contract attached to a Node that is "needs-review"
+        // acts as a signal for propagation, OR any specifically updated shapes.
+        // For this prototype implementation, we'll traverse starting from specifically flagged nodes.
+        const triggerContracts = contracts.filter((c) => {
+            const parentNode = nodeMap.get(c.node_id);
+            return parentNode && parentNode.status === "needs-review";
+        });
+        const flaggedNodes = [];
+        // BFS Queue: [contractId, depth]
+        // S011 explicitly mandates capping transitive impact at 10 hops.
+        const queue = triggerContracts.map((c) => [
+            c.id,
+            1,
+        ]);
+        const visitedContracts = new Set();
+        while (queue.length > 0) {
+            const [contractId, depth] = queue.shift();
+            if (visitedContracts.has(contractId) || depth > 10)
+                continue;
+            visitedContracts.add(contractId);
+            // Find nodes that import this contract
+            const dependentEdges = dependencies.filter((d) => d.target_contract_id === contractId);
+            for (const edge of dependentEdges) {
+                const dependentNodeId = edge.source_node_id;
+                const dependentNode = nodeMap.get(dependentNodeId);
+                if (!dependentNode)
+                    continue;
+                // Skip nodes that are already reviewing or roadmap, per S011 instructions.
+                if (dependentNode.status === "needs-review" ||
+                    dependentNode.status === "roadmap") {
+                    continue;
+                }
+                // Flag the node natively
+                await this.store.updateNodeStatus(dependentNode.id, "needs-review");
+                dependentNode.status = "needs-review"; // Update internal ref mapping
+                flaggedNodes.push({
+                    nodeId: dependentNode.id,
+                    filePath: dependentNode.file_path,
+                    triggeredByContractId: contractId,
+                    impact: depth === 1 ? "direct" : "transitive",
+                    depth,
+                });
+                // Enqueue cascading contracts exported by the now-flagged dependent node
+                const cascadingContracts = contracts.filter((c) => c.node_id === dependentNode.id);
+                for (const cContract of cascadingContracts) {
+                    queue.push([cContract.id, depth + 1]);
+                }
+            }
+        }
+        // S012: graph is consistent when no nodes need review and all nodes are stable or roadmap.
+        // Roadmap nodes are planned-but-not-yet-built and are an acceptable stable state.
+        return {
+            consistent: flaggedNodes.length === 0 &&
+                nodes.every((n) => n.status === "stable" || n.status === "roadmap"),
+            flagged: flaggedNodes,
+            integrityViolations,
+            importSuggestions,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    validateImportIntegrity(nodes, contracts, dependencies) {
+        const nodeById = new Map(nodes.map((node) => [node.id, node]));
+        const contractById = new Map(contracts.map((contract) => [contract.id, contract]));
+        const contractsByNodeId = new Map();
+        for (const contract of contracts) {
+            const existing = contractsByNodeId.get(contract.node_id) ?? [];
+            existing.push(contract);
+            contractsByNodeId.set(contract.node_id, existing);
+        }
+        const dependencyKeys = new Set();
+        const uniqueDependencies = dependencies.filter((dependency) => {
+            const key = `${dependency.source_node_id}->${dependency.target_contract_id}`;
+            if (dependencyKeys.has(key)) {
+                return false;
+            }
+            dependencyKeys.add(key);
+            return true;
+        });
+        const unresolvedImports = [];
+        const selfImports = [];
+        const adjacency = new Map();
+        for (const contract of contracts) {
+            adjacency.set(contract.id, new Set());
+        }
+        for (const dependency of uniqueDependencies) {
+            const sourceNode = nodeById.get(dependency.source_node_id);
+            const sourceContracts = contractsByNodeId.get(dependency.source_node_id) ?? [];
+            const targetContract = contractById.get(dependency.target_contract_id);
+            if (!sourceNode || sourceContracts.length === 0) {
+                continue;
+            }
+            if (!targetContract) {
+                for (const sourceContract of sourceContracts) {
+                    unresolvedImports.push({
+                        contractId: sourceContract.id,
+                        filePath: sourceNode.file_path,
+                        importPath: dependency.target_contract_id,
+                    });
+                }
+                continue;
+            }
+            const selfImportingContracts = sourceContracts.filter((sourceContract) => sourceContract.id === dependency.target_contract_id);
+            for (const sourceContract of selfImportingContracts) {
+                selfImports.push({
+                    contractId: sourceContract.id,
+                    filePath: sourceNode.file_path,
+                    importPath: dependency.target_contract_id,
+                });
+            }
+            for (const sourceContract of sourceContracts) {
+                if (sourceContract.id === dependency.target_contract_id) {
+                    continue;
+                }
+                adjacency.get(sourceContract.id)?.add(dependency.target_contract_id);
+            }
+        }
+        const circularImports = this.findCircularImports(adjacency, contractById, nodeById);
+        return {
+            unresolvedImports,
+            selfImports,
+            circularImports,
+        };
+    }
+    findCircularImports(adjacency, contractById, nodeById) {
+        const visited = new Set();
+        const path = [];
+        const cycleMap = new Map();
+        const contractIds = [...adjacency.keys()].sort();
+        const visit = (contractId) => {
+            visited.add(contractId);
+            path.push(contractId);
+            const neighbors = [...(adjacency.get(contractId) ?? [])].sort();
+            for (const neighborId of neighbors) {
+                const existingIndex = path.indexOf(neighborId);
+                if (existingIndex !== -1) {
+                    const cycle = [...path.slice(existingIndex), neighborId];
+                    const key = canonicalizeCycle(cycle);
+                    if (!cycleMap.has(key)) {
+                        const sourceContractId = cycle[0];
+                        const sourceContract = contractById.get(sourceContractId);
+                        const sourceNode = sourceContract
+                            ? nodeById.get(sourceContract.node_id)
+                            : undefined;
+                        cycleMap.set(key, {
+                            contractId: sourceContractId,
+                            filePath: sourceNode?.file_path ?? sourceContractId,
+                            importPath: cycle.join(" -> "),
+                            cycle,
+                        });
+                    }
+                    continue;
+                }
+                if (!visited.has(neighborId)) {
+                    visit(neighborId);
+                }
+            }
+            path.pop();
+        };
+        for (const contractId of contractIds) {
+            if (!visited.has(contractId)) {
+                visit(contractId);
+            }
+        }
+        return [...cycleMap.values()].sort((left, right) => left.importPath.localeCompare(right.importPath));
+    }
+}
+function canonicalizeCycle(cycle) {
+    const ring = cycle.slice(0, -1);
+    if (ring.length === 0) {
+        return "";
+    }
+    const rotations = ring.map((_, index) => {
+        const rotated = [...ring.slice(index), ...ring.slice(0, index)];
+        return `${rotated.join("->")}->${rotated[0]}`;
+    });
+    return rotations.sort()[0];
+}
+//# sourceMappingURL=index.js.map

package/dist/reconciler/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/reconciler/index.ts"],"names":[],"mappings":"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"}

package/dist/store/factory.d.ts

@@ -0,0 +1,7 @@
+import { DBStore } from "./types.js";
+/**
+ * Evaluates the current environment and configuration (handling overrides from the CI pipeline, S005)
+ * and returns the correct initialized database engine.
+ */
+export declare function getStore(): Promise<DBStore>;
+//# sourceMappingURL=factory.d.ts.map

package/dist/store/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/store/factory.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAMrC;;;GAGG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC,CAyCjD"}