cotx-engine 0.1.0

package/dist/commands/write.js

@@ -0,0 +1,221 @@
+import { CotxStore } from '../store/store.js';
+import { rebuildDerivedIndex } from '../store/derived-index.js';
+import { CotxGraph } from '../query/graph-index.js';
+// ── Zone protection ─────────────────────────────────────────────────────────
+const DETERMINISTIC_FIELDS = new Set([
+    'id',
+    'files',
+    'struct_hash',
+    'canonical_entry',
+    'depends_on',
+    'depended_by',
+    'provider',
+    'consumer',
+    'interface',
+    'trigger',
+    'steps',
+    'states',
+    'transitions',
+    'aliases',
+    'appears_in',
+    'layer',
+    'type',
+    'owner_module',
+    'state_field',
+    'auto_description',
+]);
+const ENRICHED_FIELD_SHAPES = {
+    module: {
+        responsibility: 'string',
+        key_patterns: 'string',
+    },
+    concept: {
+        definition: 'string',
+        distinguished_from: 'distinguished_from',
+    },
+    contract: {
+        guarantees: 'string[]',
+        invariants: 'string[]',
+    },
+    flow: {
+        error_paths: 'error_paths',
+        guards: 'guards',
+        invariants: 'string[]',
+    },
+};
+function parseStructuredArray(content) {
+    const parsed = JSON.parse(content);
+    if (!Array.isArray(parsed)) {
+        throw new Error('expected a JSON array');
+    }
+    return parsed;
+}
+function parseEnrichedValue(layer, fieldName, content) {
+    const shape = ENRICHED_FIELD_SHAPES[layer]?.[fieldName] ?? 'string';
+    switch (shape) {
+        case 'string':
+            return content;
+        case 'string[]': {
+            const parsed = parseStructuredArray(content);
+            if (!parsed.every((item) => typeof item === 'string')) {
+                throw new Error('expected an array of strings');
+            }
+            return parsed;
+        }
+        case 'error_paths': {
+            const parsed = parseStructuredArray(content);
+            if (!parsed.every((item) => item &&
+                typeof item === 'object' &&
+                typeof item.condition === 'string' &&
+                typeof item.behavior === 'string')) {
+                throw new Error('expected [{condition, behavior}, ...]');
+            }
+            return parsed;
+        }
+        case 'guards': {
+            const parsed = parseStructuredArray(content);
+            if (!parsed.every((item) => item &&
+                typeof item === 'object' &&
+                typeof item.transition === 'string' &&
+                typeof item.condition === 'string')) {
+                throw new Error('expected [{transition, condition}, ...]');
+            }
+            return parsed;
+        }
+        case 'distinguished_from': {
+            const parsed = parseStructuredArray(content);
+            if (!parsed.every((item) => item &&
+                typeof item === 'object' &&
+                typeof item.term === 'string' &&
+                typeof item.difference === 'string')) {
+                throw new Error('expected [{term, difference}, ...]');
+            }
+            return parsed;
+        }
+    }
+}
+// ── Node lookup ──────────────────────────────────────────────────────────────
+function findNodeAcrossLayers(store, nodeId) {
+    if (store.listModules().includes(nodeId)) {
+        return { layer: 'module', data: store.readModule(nodeId) };
+    }
+    if (store.listConcepts().includes(nodeId)) {
+        return { layer: 'concept', data: store.readConcept(nodeId) };
+    }
+    if (store.listContracts().includes(nodeId)) {
+        return {
+            layer: 'contract',
+            data: store.readContract(nodeId),
+        };
+    }
+    if (store.listFlows().includes(nodeId)) {
+        return { layer: 'flow', data: store.readFlow(nodeId) };
+    }
+    return null;
+}
+// ── Write helpers ────────────────────────────────────────────────────────────
+function writeNodeToStore(store, layer, data) {
+    switch (layer) {
+        case 'module':
+            store.writeModule(data);
+            break;
+        case 'concept':
+            store.writeConcept(data);
+            break;
+        case 'contract':
+            store.writeContract(data);
+            break;
+        case 'flow':
+            store.writeFlow(data);
+            break;
+    }
+}
+function writeEnriched(store, node, fieldName, content) {
+    if (DETERMINISTIC_FIELDS.has(fieldName)) {
+        return {
+            success: false,
+            message: `Field "${fieldName}" is deterministic-only and cannot be written via enriched zone.`,
+        };
+    }
+    const data = node.data;
+    if (!data.enriched) {
+        data.enriched = { source_hash: data.struct_hash, enriched_at: new Date().toISOString() };
+    }
+    try {
+        data.enriched[fieldName] = parseEnrichedValue(node.layer, fieldName, content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            success: false,
+            message: `Invalid enriched.${fieldName}: ${message}`,
+        };
+    }
+    data.enriched['source_hash'] = data.struct_hash;
+    data.enriched['enriched_at'] = new Date().toISOString();
+    writeNodeToStore(store, node.layer, data);
+    rebuildDerivedIndex(store);
+    CotxGraph.invalidateCache();
+    return { success: true, message: `Updated ${node.layer}/${data.id} enriched.${fieldName}` };
+}
+function writeAnnotation(store, node, annotationType, content, options) {
+    const validTypes = ['constraint', 'intent', 'concern', 'question'];
+    if (!validTypes.includes(annotationType)) {
+        return {
+            success: false,
+            message: `Invalid annotation type: ${annotationType}. Use: ${validTypes.join(', ')}`,
+        };
+    }
+    const data = node.data;
+    if (!data.annotations)
+        data.annotations = [];
+    data.annotations.push({
+        author: options?.author ?? 'human',
+        type: annotationType,
+        content,
+        date: new Date().toISOString().split('T')[0],
+    });
+    writeNodeToStore(store, node.layer, data);
+    rebuildDerivedIndex(store);
+    CotxGraph.invalidateCache();
+    return {
+        success: true,
+        message: `Added ${annotationType} annotation to ${node.layer}/${data.id}`,
+    };
+}
+// ── Public API ───────────────────────────────────────────────────────────────
+export async function commandWrite(projectRoot, nodeId, field, content, options) {
+    const store = new CotxStore(projectRoot);
+    if (!store.exists()) {
+        return { success: false, message: 'No .cotx/ found. Run: cotx compile' };
+    }
+    const [zone, fieldName] = field.split('.', 2);
+    if (!zone || !fieldName) {
+        return {
+            success: false,
+            message: `Invalid field: ${field}. Use enriched.<field> or annotation.<type>`,
+        };
+    }
+    const node = findNodeAcrossLayers(store, nodeId);
+    if (!node) {
+        return { success: false, message: `Node "${nodeId}" not found` };
+    }
+    let result;
+    if (zone === 'enriched') {
+        result = writeEnriched(store, node, fieldName, content);
+    }
+    else if (zone === 'annotation') {
+        result = writeAnnotation(store, node, fieldName, content, options);
+    }
+    else {
+        return {
+            success: false,
+            message: `Unknown zone: ${zone}. Use enriched or annotation`,
+        };
+    }
+    if (result.success) {
+        store.appendLog({ operation: 'write', affected_nodes: [nodeId], summary: `${field} on ${nodeId}` });
+    }
+    return result;
+}
+//# sourceMappingURL=write.js.map

package/dist/commands/write.js.map

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

package/dist/compiler/auto-describe.d.ts

@@ -0,0 +1,13 @@
+import type { CotxStore } from '../store/store.js';
+import type { ModuleNode } from '../store/schema.js';
+import type { GraphNode } from '../core/export/json-exporter.js';
+/**
+ * Generate deterministic one-line descriptions for modules that lack
+ * enriched.responsibility. Uses function/type names to extract the
+ * top action verbs and domain nouns.
+ *
+ * Only writes auto_description (not enriched.responsibility) to avoid
+ * overwriting LLM-quality enrichments. The map display prefers
+ * enriched.responsibility when available, falls back to auto_description.
+ */
+export declare function autoDescribeModules(store: CotxStore, nodes: GraphNode[], modules: ModuleNode[]): void;

package/dist/compiler/auto-describe.js

@@ -0,0 +1,91 @@
+import { splitCompoundName } from '../lib/naming.js';
+import { eng as ENGLISH_STOPWORDS } from 'stopword';
+const SKIP_WORDS = new Set([
+    ...ENGLISH_STOPWORDS,
+    'get', 'set', 'new', 'create', 'handle', 'error', 'config', 'init',
+    'test', 'mock', 'base', 'default', 'internal', 'util', 'helper',
+    'func', 'run', 'load', 'save', 'read', 'write', 'parse',
+    'string', 'value', 'result', 'node', 'file', 'path', 'name',
+    'args', 'options', 'command', 'true', 'false', 'null',
+]);
+/**
+ * Generate deterministic one-line descriptions for modules that lack
+ * enriched.responsibility. Uses function/type names to extract the
+ * top action verbs and domain nouns.
+ *
+ * Only writes auto_description (not enriched.responsibility) to avoid
+ * overwriting LLM-quality enrichments. The map display prefers
+ * enriched.responsibility when available, falls back to auto_description.
+ */
+export function autoDescribeModules(store, nodes, modules) {
+    // Build: moduleId → list of exported function/type names
+    const moduleNames = new Map();
+    // Map file → moduleId
+    const fileToModule = new Map();
+    for (const mod of modules) {
+        for (const f of mod.files) {
+            fileToModule.set(f, mod.id);
+        }
+    }
+    for (const node of nodes) {
+        const fp = node.properties.filePath;
+        const name = node.properties.name;
+        const exported = node.properties.isExported;
+        if (!fp || !name || !exported)
+            continue;
+        const modId = fileToModule.get(fp);
+        if (!modId)
+            continue;
+        if (!moduleNames.has(modId))
+            moduleNames.set(modId, []);
+        moduleNames.get(modId).push(name);
+    }
+    for (const mod of modules) {
+        const existing = store.readModule(mod.id);
+        const names = moduleNames.get(mod.id) ?? [];
+        if (names.length === 0)
+            continue;
+        const desc = generateDescription(names, mod.canonical_entry);
+        if (!desc)
+            continue;
+        // Write as auto_description — a deterministic fallback.
+        // Never overwrites LLM-written responsibility.
+        const enriched = existing.enriched ?? {
+            source_hash: mod.struct_hash,
+            enriched_at: new Date().toISOString(),
+        };
+        enriched.auto_description = desc;
+        enriched.source_hash = mod.struct_hash;
+        enriched.enriched_at = new Date().toISOString();
+        store.writeModule({ ...existing, enriched });
+    }
+}
+function generateDescription(names, canonicalEntry) {
+    // Extract word roots from all exported names
+    const wordCounts = new Map();
+    for (const name of names) {
+        const words = splitCompoundName(name);
+        for (const w of words) {
+            if (w.length < 3 || SKIP_WORDS.has(w))
+                continue;
+            wordCounts.set(w, (wordCounts.get(w) ?? 0) + 1);
+        }
+    }
+    if (wordCounts.size === 0)
+        return null;
+    // Top 5 words by frequency, then alphabetically
+    const sorted = [...wordCounts.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .slice(0, 5);
+    const topWords = sorted.map(([w]) => w);
+    // Build: "Handles <top words> operations via <canonical entry>"
+    const wordsStr = topWords.join(', ');
+    if (canonicalEntry) {
+        return `${capitalize(topWords[0])} operations: ${wordsStr} (entry: ${canonicalEntry})`;
+    }
+    return `${capitalize(topWords[0])} operations: ${wordsStr}`;
+}
+function capitalize(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+//# sourceMappingURL=auto-describe.js.map

package/dist/compiler/auto-describe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-describe.js","sourceRoot":"","sources":["../../src/compiler/auto-describe.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,GAAG,IAAI,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAEpD,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC;IACzB,GAAG,iBAAiB;IACpB,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM;IAClE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ;IAC/D,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;IACvD,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAC3D,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CACtD,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAgB,EAChB,KAAkB,EAClB,OAAqB;IAErB,yDAAyD;IACzD,MAAM,WAAW,GAAG,IAAI,GAAG,EAAoB,CAAC;IAEhD,sBAAsB;IACtB,MAAM,YAAY,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC/C,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;YAC1B,YAAY,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,QAA8B,CAAC;QAC1D,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,IAA0B,CAAC;QACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,UAAiC,CAAC;QACnE,IAAI,CAAC,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ;YAAE,SAAS;QAExC,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnC,IAAI,CAAC,KAAK;YAAE,SAAS;QAErB,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACxD,WAAW,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1C,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;QAC5C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAEjC,MAAM,IAAI,GAAG,mBAAmB,CAAC,KAAK,EAAE,GAAG,CAAC,eAAe,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI;YAAE,SAAS;QAEpB,wDAAwD;QACxD,+CAA+C;QAC/C,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,IAAI;YACpC,WAAW,EAAE,GAAG,CAAC,WAAW;YAC5B,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACtC,CAAC;QACD,QAAoC,CAAC,gBAAgB,GAAG,IAAI,CAAC;QAC9D,QAAQ,CAAC,WAAW,GAAG,GAAG,CAAC,WAAW,CAAC;QACvC,QAAQ,CAAC,WAAW,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAEhD,KAAK,CAAC,WAAW,CAAC,EAAE,GAAG,QAAQ,EAAE,QAAQ,EAAgB,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAe,EAAE,cAAsB;IAClE,6CAA6C;IAC7C,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC7C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACtC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,SAAS;YAChD,UAAU,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAED,IAAI,UAAU,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvC,gDAAgD;IAChD,MAAM,MAAM,GAAG,CAAC,GAAG,UAAU,CAAC,OAAO,EAAE,CAAC;SACrC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SACvD,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAEf,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IAExC,gEAAgE;IAChE,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,cAAc,EAAE,CAAC;QACnB,OAAO,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,gBAAgB,QAAQ,YAAY,cAAc,GAAG,CAAC;IACzF,CAAC;IACD,OAAO,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,gBAAgB,QAAQ,EAAE,CAAC;AAC9D,CAAC;AAED,SAAS,UAAU,CAAC,CAAS;IAC3B,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC"}

package/dist/compiler/concept-compiler.d.ts

@@ -0,0 +1,21 @@
+import type { GraphNode } from '../core/export/json-exporter.js';
+import type { ModuleNode, ConceptNode } from '../store/schema.js';
+export interface ConceptCompilerOptions {
+    /** Minimum distinct symbols a word root must appear in. Default: 3 */
+    minSymbolCount?: number;
+}
+/**
+ * Compile exported symbols into ConceptNode[].
+ *
+ * Algorithm:
+ * 1. Collect candidate nodes: exported types + functions.
+ * 2. Split each symbol name into word roots via splitCompoundName().
+ * 3. Count how many distinct symbols each word root appears in.
+ * 4. Threshold filter: keep roots appearing in ≥ 3 distinct symbols.
+ * 5. Noise filter: remove generic programming words.
+ * 6. For each surviving root, collect all file paths where it appears.
+ * 7. Assign to the module where it appears most frequently (→ layer).
+ * 8. Compute struct_hash from { id, aliases, appears_in }.
+ * 9. Return ConceptNode[] sorted alphabetically by id.
+ */
+export declare function compileConcepts(nodes: GraphNode[], modules: ModuleNode[], options?: ConceptCompilerOptions): ConceptNode[];

package/dist/compiler/concept-compiler.js

@@ -0,0 +1,125 @@
+import { splitCompoundName, moduleIdForFile } from '../lib/naming.js';
+import { structHash } from '../lib/hash.js';
+import { eng as ENGLISH_STOPWORDS } from 'stopword';
+/** Minimum word length to be considered a concept. */
+const MIN_WORD_LENGTH = 3;
+/**
+ * Words too generic to carry domain meaning.
+ * Combines English stopwords + code-specific noise.
+ */
+const NOISE_WORDS = new Set([
+    // English stopwords (about, after, all, also, and, any, are, as, at, be, ...)
+    ...ENGLISH_STOPWORDS,
+    // Code-generic verbs/nouns
+    'get', 'set', 'new', 'create', 'handle', 'error', 'config', 'init',
+    'type', 'data', 'info', 'item', 'list', 'map', 'test', 'mock', 'base',
+    'default', 'internal', 'util', 'helper', 'manager', 'service', 'handler',
+    'processor', 'builder', 'factory', 'impl', 'abstract', 'interface',
+    // Common low-signal code words
+    'load', 'save', 'read', 'write', 'parse', 'string', 'value', 'result',
+    'node', 'file', 'path', 'name', 'func', 'call', 'args', 'options',
+    'command', 'input', 'output', 'check', 'find', 'make', 'return',
+    'run', 'start', 'stop', 'open', 'close', 'send', 'copy', 'move',
+    'true', 'false', 'null', 'none', 'empty', 'count', 'size', 'length',
+    'index', 'key', 'val', 'err', 'msg', 'log', 'flag', 'mode', 'kind',
+    'uses', 'used', 'using', 'with', 'from', 'into', 'when', 'then',
+    'each', 'next', 'prev', 'last', 'first', 'has', 'was', 'did', 'does',
+    'should', 'must', 'can', 'may', 'will', 'try', 'not', 'only',
+]);
+/** Node labels that are potential concept carriers. */
+const CONCEPT_LABELS = new Set(['Class', 'Interface', 'Struct', 'Enum', 'Type', 'Function']);
+/**
+ * Produce CamelCase, snake_case, and kebab-case variants of a word root.
+ */
+function buildAliases(word) {
+    const camel = word.charAt(0).toUpperCase() + word.slice(1);
+    const snake = word; // already lower-cased word root = snake_case atom
+    const kebab = word; // single word: same as snake
+    return [...new Set([camel, snake, kebab])];
+}
+/**
+ * Compile exported symbols into ConceptNode[].
+ *
+ * Algorithm:
+ * 1. Collect candidate nodes: exported types + functions.
+ * 2. Split each symbol name into word roots via splitCompoundName().
+ * 3. Count how many distinct symbols each word root appears in.
+ * 4. Threshold filter: keep roots appearing in ≥ 3 distinct symbols.
+ * 5. Noise filter: remove generic programming words.
+ * 6. For each surviving root, collect all file paths where it appears.
+ * 7. Assign to the module where it appears most frequently (→ layer).
+ * 8. Compute struct_hash from { id, aliases, appears_in }.
+ * 9. Return ConceptNode[] sorted alphabetically by id.
+ */
+export function compileConcepts(nodes, modules, options) {
+    const minSymbolCount = options?.minSymbolCount ?? 3;
+    // Step 1: filter to exported symbols (types + functions)
+    const candidates = nodes.filter((n) => CONCEPT_LABELS.has(n.label) &&
+        n.properties.isExported === true);
+    // Build a lookup: moduleId → Set<filePath> (for tie-breaking later, not strictly needed)
+    const moduleFileSet = new Map();
+    for (const mod of modules) {
+        moduleFileSet.set(mod.id, new Set(mod.files));
+    }
+    // Step 2 & 3: map word root → Set of symbol IDs that contain it
+    // Also track word root → Set of file paths where it appears
+    const rootToSymbols = new Map();
+    const rootToFiles = new Map();
+    for (const node of candidates) {
+        const name = node.properties.name;
+        if (!name)
+            continue;
+        const filePath = node.properties.filePath;
+        const words = splitCompoundName(name);
+        for (const word of words) {
+            if (word.length < MIN_WORD_LENGTH)
+                continue;
+            if (!rootToSymbols.has(word)) {
+                rootToSymbols.set(word, new Set());
+                rootToFiles.set(word, new Set());
+            }
+            rootToSymbols.get(word).add(node.id);
+            if (filePath) {
+                rootToFiles.get(word).add(filePath);
+            }
+        }
+    }
+    // Step 4 & 5: threshold ≥ 3 distinct symbols, remove noise
+    const concepts = [];
+    for (const [word, symbolIds] of rootToSymbols) {
+        if (symbolIds.size < minSymbolCount)
+            continue;
+        if (NOISE_WORDS.has(word))
+            continue;
+        // Step 6: file paths where this concept appears
+        const appearsIn = [...rootToFiles.get(word)].sort();
+        // Step 7: find module where this concept appears most
+        const moduleCount = new Map();
+        for (const filePath of appearsIn) {
+            const modId = moduleIdForFile(filePath);
+            moduleCount.set(modId, (moduleCount.get(modId) ?? 0) + 1);
+        }
+        let layer = '_root';
+        let maxCount = 0;
+        for (const [modId, count] of moduleCount) {
+            if (count > maxCount || (count === maxCount && modId < layer)) {
+                maxCount = count;
+                layer = modId;
+            }
+        }
+        // Step 8: struct_hash
+        const aliases = buildAliases(word);
+        const hash = structHash({ id: word, aliases, appears_in: appearsIn });
+        concepts.push({
+            id: word,
+            aliases,
+            appears_in: appearsIn,
+            layer,
+            struct_hash: hash,
+        });
+    }
+    // Step 9: sort alphabetically by id
+    concepts.sort((a, b) => a.id.localeCompare(b.id));
+    return concepts;
+}
+//# sourceMappingURL=concept-compiler.js.map

package/dist/compiler/concept-compiler.js.map

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

package/dist/compiler/contract-compiler.d.ts

@@ -0,0 +1,16 @@
+import type { GraphNode, GraphEdge } from '../core/export/json-exporter.js';
+import type { ModuleNode, ContractNode } from '../store/schema.js';
+/**
+ * Compile GraphNode + GraphEdge + ModuleNode data into ContractNode records.
+ *
+ * Algorithm:
+ * 1. Build file→module map from ModuleNode[].
+ * 2. Build nodeId→module map by looking up each GraphNode's filePath.
+ * 3. Find cross-module CALLS edges (source module ≠ target module).
+ * 4. Group by (provider, consumer): target's module = provider, source's module = consumer.
+ * 5. Collect unique target function names per (provider, consumer) pair as interface[].
+ * 6. Generate contract ID as `${consumer}--${provider}` (consumer < provider alphabetically).
+ * 7. Compute struct_hash from { id, provider, consumer, interface }.
+ * 8. Return ContractNode[] sorted alphabetically by id.
+ */
+export declare function compileContracts(nodes: GraphNode[], edges: GraphEdge[], modules: ModuleNode[]): ContractNode[];

package/dist/compiler/contract-compiler.js

@@ -0,0 +1,90 @@
+import { structHash } from '../lib/hash.js';
+/**
+ * Compile GraphNode + GraphEdge + ModuleNode data into ContractNode records.
+ *
+ * Algorithm:
+ * 1. Build file→module map from ModuleNode[].
+ * 2. Build nodeId→module map by looking up each GraphNode's filePath.
+ * 3. Find cross-module CALLS edges (source module ≠ target module).
+ * 4. Group by (provider, consumer): target's module = provider, source's module = consumer.
+ * 5. Collect unique target function names per (provider, consumer) pair as interface[].
+ * 6. Generate contract ID as `${consumer}--${provider}` (consumer < provider alphabetically).
+ * 7. Compute struct_hash from { id, provider, consumer, interface }.
+ * 8. Return ContractNode[] sorted alphabetically by id.
+ */
+export function compileContracts(nodes, edges, modules) {
+    // Step 1: build file→module map
+    const fileToModule = new Map();
+    for (const mod of modules) {
+        for (const file of mod.files) {
+            fileToModule.set(file, mod.id);
+        }
+    }
+    // Step 2: build nodeId→module map
+    const nodeToModule = new Map();
+    for (const node of nodes) {
+        const filePath = node.properties.filePath;
+        if (!filePath)
+            continue;
+        const modId = fileToModule.get(filePath);
+        if (modId !== undefined) {
+            nodeToModule.set(node.id, modId);
+        }
+    }
+    // Build nodeId→name map for looking up target function names
+    const nodeToName = new Map();
+    for (const node of nodes) {
+        const name = node.properties.name;
+        if (name !== undefined) {
+            nodeToName.set(node.id, name);
+        }
+    }
+    // Step 3 & 4: find cross-module CALLS and group by (provider, consumer)
+    // key: `${consumer}::${provider}`, value: Set of function names
+    const pairInterface = new Map();
+    for (const edge of edges) {
+        if (edge.type !== 'CALLS')
+            continue;
+        const srcMod = nodeToModule.get(edge.sourceId);
+        const tgtMod = nodeToModule.get(edge.targetId);
+        if (!srcMod || !tgtMod)
+            continue;
+        if (srcMod === tgtMod)
+            continue;
+        // source = consumer, target = provider
+        const consumer = srcMod;
+        const provider = tgtMod;
+        const pairKey = `${consumer}::${provider}`;
+        if (!pairInterface.has(pairKey)) {
+            pairInterface.set(pairKey, new Set());
+        }
+        const fnName = nodeToName.get(edge.targetId);
+        if (fnName !== undefined) {
+            pairInterface.get(pairKey).add(fnName);
+        }
+    }
+    // Step 5–8: assemble ContractNode records
+    const contracts = [];
+    for (const [pairKey, fnNames] of pairInterface) {
+        const colonIdx = pairKey.indexOf('::');
+        const consumer = pairKey.slice(0, colonIdx);
+        const provider = pairKey.slice(colonIdx + 2);
+        // Step 6: ID is always consumer--provider
+        const id = `${consumer}--${provider}`;
+        // Step 5: sorted, deduplicated interface list
+        const iface = [...fnNames].sort();
+        // Step 7: struct_hash
+        const hash = structHash({ id, provider, consumer, interface: iface });
+        contracts.push({
+            id,
+            provider,
+            consumer,
+            interface: iface,
+            struct_hash: hash,
+        });
+    }
+    // Step 8: sort alphabetically by id
+    contracts.sort((a, b) => a.id.localeCompare(b.id));
+    return contracts;
+}
+//# sourceMappingURL=contract-compiler.js.map

package/dist/compiler/contract-compiler.js.map

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

package/dist/compiler/delta-detector.d.ts

@@ -0,0 +1,8 @@
+import type { CotxStore } from '../store/store.js';
+export interface DeltaResult {
+    changedFiles: string[];
+    affectedModules: string[];
+    affectedContracts: string[];
+    affectedFlows: string[];
+}
+export declare function detectDelta(store: CotxStore, changedFiles: string[]): DeltaResult;