studiograph 1.1.2 → 1.2.0-beta.1

package/dist/services/sync/context-index.js

@@ -0,0 +1,280 @@
+/**
+ * ContextIndex
+ *
+ * Cross-source context index for enrichment. Scans all repos for entity
+ * references using schema relationship fields and wikilinks.
+ *
+ * Ranks references by recency, enforces a max_tokens budget, and truncates
+ * excess context before the LLM call.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { join, basename } from 'path';
+// basename is still used for repoName extraction from repoDir
+import { ENTITY_SCHEMAS } from '../../core/validation.js';
+import { MarkdownService } from '../../services/markdown.js';
+const DEFAULT_MAX_TOKENS = 4000;
+const APPROX_CHARS_PER_TOKEN = 4;
+export class ContextIndex {
+    workspacePath;
+    schemaRegistry;
+    markdownService;
+    references = new Map();
+    built = false;
+    constructor(workspacePath, schemaRegistry) {
+        this.workspacePath = workspacePath;
+        this.schemaRegistry = schemaRegistry;
+        this.markdownService = new MarkdownService();
+    }
+    /**
+     * Scan all repos for entity references.
+     */
+    build() {
+        this.references.clear();
+        const repoDirs = this.findRepoDirs();
+        for (const repoDir of repoDirs) {
+            const repoName = basename(repoDir);
+            this.scanRepo(repoDir, repoName);
+        }
+        this.built = true;
+    }
+    /**
+     * Get all context references for one entity.
+     */
+    getReferences(entityId) {
+        if (!this.built)
+            this.build();
+        return this.references.get(entityId) ?? [];
+    }
+    /**
+     * Calculate field completeness (0–1) for an entity.
+     */
+    getCompleteness(entityType, frontmatter) {
+        const schema = ENTITY_SCHEMAS[entityType];
+        if (!schema)
+            return 1;
+        const shape = schema._def?.shape?.() ?? schema.shape ?? {};
+        const fields = Object.keys(shape).filter(k => !['entity_type', 'entity_id', 'created_at', 'updated_at', 'created_by', 'updated_by', 'visibility'].includes(k));
+        if (fields.length === 0)
+            return 1;
+        let filled = 0;
+        for (const field of fields) {
+            const value = frontmatter[field];
+            if (value !== undefined && value !== null && value !== '' && !(Array.isArray(value) && value.length === 0)) {
+                filled++;
+            }
+        }
+        return filled / fields.length;
+    }
+    /**
+     * Filter to entities worth enriching (low completeness + high context).
+     */
+    getEnrichable(minRefs = 2, maxCompleteness = 0.6) {
+        if (!this.built)
+            this.build();
+        const enrichable = [];
+        const repoDirs = this.findRepoDirs();
+        for (const repoDir of repoDirs) {
+            const repoName = basename(repoDir);
+            const subdirs = this.listSubDirs(repoDir);
+            for (const entityId of subdirs) {
+                const mainPath = join(repoDir, entityId, 'main.md');
+                if (!existsSync(mainPath))
+                    continue;
+                const refs = this.getReferences(entityId);
+                if (refs.length < minRefs)
+                    continue;
+                try {
+                    const doc = this.markdownService.parseFile(mainPath);
+                    const entityType = doc.frontmatter.entity_type ?? repoName;
+                    const completeness = this.getCompleteness(entityType, doc.frontmatter);
+                    if (completeness > maxCompleteness)
+                        continue;
+                    enrichable.push({
+                        entity_id: entityId,
+                        entity_type: entityType,
+                        repo: repoName,
+                        path: mainPath,
+                        frontmatter: doc.frontmatter,
+                        completeness,
+                        refCount: refs.length,
+                    });
+                }
+                catch {
+                    // skip unparseable files
+                }
+            }
+        }
+        // Sort by most references (richest context first)
+        return enrichable.sort((a, b) => b.refCount - a.refCount);
+    }
+    /**
+     * Assemble LLM context bundle for one entity.
+     * Ranks references by recency, enforces max_tokens budget.
+     */
+    assembleContextBundle(entityId, entityName, maxTokens = DEFAULT_MAX_TOKENS) {
+        const refs = this.getReferences(entityId);
+        if (refs.length === 0)
+            return '';
+        // Sort by date (most recent first), then by snippet length
+        const sorted = [...refs].sort((a, b) => {
+            if (a.date && b.date)
+                return b.date.localeCompare(a.date);
+            if (a.date)
+                return -1;
+            if (b.date)
+                return 1;
+            return 0;
+        });
+        const maxChars = maxTokens * APPROX_CHARS_PER_TOKEN;
+        const lines = [];
+        let totalChars = 0;
+        lines.push(`Context for "${entityName}" (${entityId}):\n`);
+        totalChars += lines[0].length;
+        for (const ref of sorted) {
+            const line = `- [${ref.entity_type}/${ref.entity_id}] (${ref.field}${ref.date ? ', ' + ref.date : ''}): ${ref.snippet}`;
+            if (totalChars + line.length > maxChars) {
+                lines.push(`\n... and ${sorted.length - lines.length + 1} more references (truncated)`);
+                break;
+            }
+            lines.push(line);
+            totalChars += line.length;
+        }
+        return lines.join('\n');
+    }
+    // ── Private ────────────────────────────────────────────────────────────────
+    scanRepo(repoDir, repoName) {
+        const subdirs = this.listSubDirs(repoDir);
+        for (const entityId of subdirs) {
+            const mainPath = join(repoDir, entityId, 'main.md');
+            if (!existsSync(mainPath))
+                continue;
+            try {
+                const doc = this.markdownService.parseFile(mainPath);
+                const entityType = doc.frontmatter.entity_type ?? repoName;
+                const relFields = this.getRelationshipFields(entityType);
+                // Scan relationship fields
+                for (const field of relFields) {
+                    const value = doc.frontmatter[field];
+                    if (!value)
+                        continue;
+                    const refs = Array.isArray(value) ? value : [value];
+                    for (const ref of refs) {
+                        const targetId = this.extractEntityId(String(ref));
+                        if (!targetId)
+                            continue;
+                        this.addReference(targetId, {
+                            entity_id: entityId,
+                            entity_type: entityType,
+                            field,
+                            repo: repoName,
+                            date: doc.frontmatter.date ?? doc.frontmatter.created_at,
+                            snippet: this.makeSnippet(doc.frontmatter, entityType),
+                        });
+                    }
+                }
+                // Scan wikilinks in content
+                for (const link of doc.wikilinks) {
+                    const targetId = this.extractEntityId(link);
+                    if (!targetId || targetId === entityId)
+                        continue;
+                    this.addReference(targetId, {
+                        entity_id: entityId,
+                        entity_type: entityType,
+                        field: 'content',
+                        repo: repoName,
+                        date: doc.frontmatter.date ?? doc.frontmatter.created_at,
+                        snippet: this.makeSnippet(doc.frontmatter, entityType),
+                    });
+                }
+            }
+            catch {
+                // skip unparseable files
+            }
+        }
+    }
+    addReference(entityId, ref) {
+        if (!this.references.has(entityId)) {
+            this.references.set(entityId, []);
+        }
+        this.references.get(entityId).push(ref);
+    }
+    /**
+     * Get relationship fields for an entity type by inspecting schema descriptions.
+     */
+    getRelationshipFields(entityType) {
+        const schema = ENTITY_SCHEMAS[entityType];
+        if (!schema)
+            return [];
+        const shape = schema._def?.shape?.() ?? schema.shape ?? {};
+        const fields = [];
+        for (const [name, zodType] of Object.entries(shape)) {
+            const desc = this.getDescription(zodType);
+            if (desc && (desc.includes('wikilink') || desc.includes('Wikilink'))) {
+                fields.push(name);
+            }
+        }
+        return fields;
+    }
+    getDescription(zodType) {
+        const def = zodType?._def;
+        if (!def)
+            return undefined;
+        if (def.description)
+            return def.description;
+        // Unwrap optional/default
+        if (def.innerType)
+            return this.getDescription(def.innerType);
+        return undefined;
+    }
+    extractEntityId(value) {
+        // [[entity-id]] or [[entity-id|Display Name]]
+        const match = value.match(/\[\[([^\]|]+)/);
+        if (match)
+            return match[1];
+        // Plain kebab-case
+        if (/^[a-z0-9_-]+$/.test(value))
+            return value;
+        return null;
+    }
+    makeSnippet(frontmatter, entityType) {
+        const name = frontmatter.name ?? frontmatter.title ?? '';
+        const date = frontmatter.date ?? '';
+        return `${entityType}: ${name}${date ? ' (' + date + ')' : ''}`;
+    }
+    findRepoDirs() {
+        // Look for workspace config to find repos
+        const configPath = join(this.workspacePath, '.studiograph', 'workspace.json');
+        if (existsSync(configPath)) {
+            try {
+                const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+                if (config.repos && Array.isArray(config.repos)) {
+                    return config.repos
+                        .map((r) => join(this.workspacePath, r.path))
+                        .filter((p) => existsSync(p));
+                }
+            }
+            catch {
+                // fall through to directory scan
+            }
+        }
+        // Fallback: scan top-level directories
+        return this.listSubDirs(this.workspacePath)
+            .map(d => join(this.workspacePath, d))
+            .filter(d => !d.includes('.studiograph') && !d.includes('node_modules') && !d.includes('.git'));
+    }
+    listSubDirs(dir) {
+        if (!existsSync(dir))
+            return [];
+        return readdirSync(dir).filter(f => {
+            if (f.startsWith('.'))
+                return false;
+            try {
+                return statSync(join(dir, f)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+}
+//# sourceMappingURL=context-index.js.map

package/dist/services/sync/context-index.js.map

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

package/dist/services/sync/derive.d.ts

@@ -0,0 +1,34 @@
+/**
+ * DerivationEngine
+ *
+ * Derives secondary entities (e.g. person, client) from primary extracted
+ * records by inspecting schema relationship fields.
+ *
+ * If a mapping references entity type X via relationship fields but no mapping
+ * directly provides X, then X needs derivation.
+ */
+import type { SchemaRegistry } from '../../core/schema-registry.js';
+import type { EntityMapping, ExtractedRecord, DerivationRule } from './types.js';
+export declare class DerivationEngine {
+    private schemaRegistry;
+    constructor(schemaRegistry: SchemaRegistry);
+    /**
+     * Detect which entity types need derivation.
+     *
+     * Logic: if a mapping references entity type X via relationship fields,
+     * but no mapping directly provides X, then X needs derivation.
+     */
+    detectDerivationNeeds(mappings: EntityMapping[]): DerivationRule[];
+    /**
+     * Derive secondary entities from primary extracted records.
+     */
+    derive(records: ExtractedRecord[], rules: DerivationRule[]): ExtractedRecord[];
+    /**
+     * Get relationship fields and their referenced entity types for a given entity type.
+     */
+    private getReferencedTypes;
+    /**
+     * Extract values from a frontmatter field (handles arrays and single values).
+     */
+    private extractValues;
+}

package/dist/services/sync/derive.js

@@ -0,0 +1,164 @@
+/**
+ * DerivationEngine
+ *
+ * Derives secondary entities (e.g. person, client) from primary extracted
+ * records by inspecting schema relationship fields.
+ *
+ * If a mapping references entity type X via relationship fields but no mapping
+ * directly provides X, then X needs derivation.
+ */
+import { ENTITY_SCHEMAS } from '../../core/validation.js';
+import { slugify } from './structured-extractor.js';
+/**
+ * Known relationship fields and the entity types they reference.
+ * Derived from schema .describe() annotations containing "wikilink".
+ */
+const RELATIONSHIP_FIELDS = {
+    attendees: 'person',
+    contacts: 'person',
+    team: 'person',
+    decision_makers: 'person',
+    stakeholders: 'person',
+    assignee: 'person',
+    person_name: 'person',
+    primary_contact: 'person',
+    reports_to: 'person',
+    client: 'client',
+    organization: 'client',
+    related_projects: 'project',
+    related_organizations: 'client',
+    deal: 'deal',
+    project: 'project',
+    proposals: 'proposal',
+    related_client: 'client',
+};
+/**
+ * Default repos for derived entity types.
+ */
+const DEFAULT_REPOS = {
+    person: 'people',
+    client: 'clients',
+    project: 'projects',
+    deal: 'deals',
+    proposal: 'proposals',
+};
+export class DerivationEngine {
+    schemaRegistry;
+    constructor(schemaRegistry) {
+        this.schemaRegistry = schemaRegistry;
+    }
+    /**
+     * Detect which entity types need derivation.
+     *
+     * Logic: if a mapping references entity type X via relationship fields,
+     * but no mapping directly provides X, then X needs derivation.
+     */
+    detectDerivationNeeds(mappings) {
+        const providedTypes = new Set(mappings.map(m => m.entity_type));
+        const rules = [];
+        const seen = new Set();
+        for (const mapping of mappings) {
+            // Inspect the entity type schema for relationship fields
+            const referencedTypes = this.getReferencedTypes(mapping.entity_type);
+            for (const [field, referencedType] of Object.entries(referencedTypes)) {
+                // Skip if already provided by a mapping
+                if (providedTypes.has(referencedType))
+                    continue;
+                if (seen.has(referencedType)) {
+                    // Add to existing rule's source fields
+                    const existing = rules.find(r => r.entity_type === referencedType);
+                    if (existing && !existing.source_fields.includes(field)) {
+                        existing.source_fields.push(field);
+                        if (!existing.from_entity_types.includes(mapping.entity_type)) {
+                            existing.from_entity_types.push(mapping.entity_type);
+                        }
+                    }
+                    continue;
+                }
+                seen.add(referencedType);
+                rules.push({
+                    entity_type: referencedType,
+                    source_fields: [field],
+                    from_entity_types: [mapping.entity_type],
+                    target_repo: DEFAULT_REPOS[referencedType] ?? `${referencedType}s`,
+                });
+            }
+        }
+        return rules;
+    }
+    /**
+     * Derive secondary entities from primary extracted records.
+     */
+    derive(records, rules) {
+        const derived = [];
+        const seenIds = new Set();
+        for (const rule of rules) {
+            // Filter records to those from entity types that feed this derivation
+            const sourceRecords = records.filter(r => rule.from_entity_types.includes(r.entity_type));
+            for (const record of sourceRecords) {
+                for (const field of rule.source_fields) {
+                    const values = this.extractValues(record.frontmatter, field);
+                    for (const value of values) {
+                        const entityId = slugify(cleanWikilink(value));
+                        if (!entityId || seenIds.has(entityId))
+                            continue;
+                        seenIds.add(entityId);
+                        const name = cleanWikilink(value);
+                        const frontmatter = {
+                            entity_type: rule.entity_type,
+                            entity_id: entityId,
+                            name,
+                        };
+                        derived.push({
+                            entity_type: rule.entity_type,
+                            entity_id: entityId,
+                            target_repo: rule.target_repo,
+                            frontmatter,
+                            content: '',
+                            source_name: record.source_name,
+                            source_ref: `${record.source_name}:#${rule.entity_type}/${entityId}`,
+                            confidence: 0.5,
+                        });
+                    }
+                }
+            }
+        }
+        return derived;
+    }
+    /**
+     * Get relationship fields and their referenced entity types for a given entity type.
+     */
+    getReferencedTypes(entityType) {
+        const result = {};
+        // Check known relationship fields against the schema
+        const schema = ENTITY_SCHEMAS[entityType];
+        if (!schema)
+            return result;
+        const shape = schema._def?.shape?.() ?? schema.shape ?? {};
+        for (const [fieldName, refType] of Object.entries(RELATIONSHIP_FIELDS)) {
+            if (fieldName in shape) {
+                result[fieldName] = refType;
+            }
+        }
+        return result;
+    }
+    /**
+     * Extract values from a frontmatter field (handles arrays and single values).
+     */
+    extractValues(frontmatter, field) {
+        const value = frontmatter[field];
+        if (!value)
+            return [];
+        if (Array.isArray(value))
+            return value.map(String).filter(Boolean);
+        return [String(value)];
+    }
+}
+/**
+ * Strip wikilink brackets: "[[john-doe]]" → "john-doe", "[[john|John Doe]]" → "john"
+ */
+function cleanWikilink(value) {
+    const match = value.match(/^\[\[([^\]|]+)(?:\|[^\]]+)?\]\]$/);
+    return match ? match[1] : value;
+}
+//# sourceMappingURL=derive.js.map

package/dist/services/sync/derive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.js","sourceRoot":"","sources":["../../../src/services/sync/derive.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAIpD;;;GAGG;AACH,MAAM,mBAAmB,GAA2B;IAClD,SAAS,EAAE,QAAQ;IACnB,QAAQ,EAAE,QAAQ;IAClB,IAAI,EAAE,QAAQ;IACd,eAAe,EAAE,QAAQ;IACzB,YAAY,EAAE,QAAQ;IACtB,QAAQ,EAAE,QAAQ;IAClB,WAAW,EAAE,QAAQ;IACrB,eAAe,EAAE,QAAQ;IACzB,UAAU,EAAE,QAAQ;IACpB,MAAM,EAAE,QAAQ;IAChB,YAAY,EAAE,QAAQ;IACtB,gBAAgB,EAAE,SAAS;IAC3B,qBAAqB,EAAE,QAAQ;IAC/B,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;IAClB,SAAS,EAAE,UAAU;IACrB,cAAc,EAAE,QAAQ;CACzB,CAAC;AAEF;;GAEG;AACH,MAAM,aAAa,GAA2B;IAC5C,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,SAAS;IACjB,OAAO,EAAE,UAAU;IACnB,IAAI,EAAE,OAAO;IACb,QAAQ,EAAE,WAAW;CACtB,CAAC;AAEF,MAAM,OAAO,gBAAgB;IACnB,cAAc,CAAiB;IAEvC,YAAY,cAA8B;QACxC,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;IACvC,CAAC;IAED;;;;;OAKG;IACH,qBAAqB,CAAC,QAAyB;QAC7C,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;QAChE,MAAM,KAAK,GAAqB,EAAE,CAAC;QACnC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAE/B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,yDAAyD;YACzD,MAAM,eAAe,GAAG,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;YAErE,KAAK,MAAM,CAAC,KAAK,EAAE,cAAc,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,CAAC;gBACtE,wCAAwC;gBACxC,IAAI,aAAa,CAAC,GAAG,CAAC,cAAc,CAAC;oBAAE,SAAS;gBAChD,IAAI,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,CAAC;oBAC7B,uCAAuC;oBACvC,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,KAAK,cAAc,CAAC,CAAC;oBACnE,IAAI,QAAQ,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;wBACxD,QAAQ,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;wBACnC,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;4BAC9D,QAAQ,CAAC,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;wBACvD,CAAC;oBACH,CAAC;oBACD,SAAS;gBACX,CAAC;gBAED,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;gBACzB,KAAK,CAAC,IAAI,CAAC;oBACT,WAAW,EAAE,cAAc;oBAC3B,aAAa,EAAE,CAAC,KAAK,CAAC;oBACtB,iBAAiB,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC;oBACxC,WAAW,EAAE,aAAa,CAAC,cAAc,CAAC,IAAI,GAAG,cAAc,GAAG;iBACnE,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,OAA0B,EAAE,KAAuB;QACxD,MAAM,OAAO,GAAsB,EAAE,CAAC;QACtC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;QAElC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,sEAAsE;YACtE,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;YAE1F,KAAK,MAAM,MAAM,IAAI,aAAa,EAAE,CAAC;gBACnC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;oBACvC,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;oBAE7D,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;wBAC3B,MAAM,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;wBAC/C,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;4BAAE,SAAS;wBACjD,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;wBAEtB,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;wBAClC,MAAM,WAAW,GAAwB;4BACvC,WAAW,EAAE,IAAI,CAAC,WAAW;4BAC7B,SAAS,EAAE,QAAQ;4BACnB,IAAI;yBACL,CAAC;wBAEF,OAAO,CAAC,IAAI,CAAC;4BACX,WAAW,EAAE,IAAI,CAAC,WAAW;4BAC7B,SAAS,EAAE,QAAQ;4BACnB,WAAW,EAAE,IAAI,CAAC,WAAW;4BAC7B,WAAW;4BACX,OAAO,EAAE,EAAE;4BACX,WAAW,EAAE,MAAM,CAAC,WAAW;4BAC/B,UAAU,EAAE,GAAG,MAAM,CAAC,WAAW,KAAK,IAAI,CAAC,WAAW,IAAI,QAAQ,EAAE;4BACpE,UAAU,EAAE,GAAG;yBAChB,CAAC,CAAC;oBACL,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACK,kBAAkB,CAAC,UAAkB;QAC3C,MAAM,MAAM,GAA2B,EAAE,CAAC;QAE1C,qDAAqD;QACrD,MAAM,MAAM,GAAG,cAAc,CAAC,UAAyC,CAAC,CAAC;QACzE,IAAI,CAAC,MAAM;YAAE,OAAO,MAAM,CAAC;QAE3B,MAAM,KAAK,GAAI,MAAc,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,IAAK,MAAc,CAAC,KAAK,IAAI,EAAE,CAAC;QAE7E,KAAK,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,CAAC;YACvE,IAAI,SAAS,IAAI,KAAK,EAAE,CAAC;gBACvB,MAAM,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC;YAC9B,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACK,aAAa,CAAC,WAAgC,EAAE,KAAa;QACnE,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,CAAC;QACtB,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACnE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACzB,CAAC;CACF;AAED;;GAEG;AACH,SAAS,aAAa,CAAC,KAAa;IAClC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAC9D,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AAClC,CAAC"}

package/dist/services/sync/enrichment-state.d.ts

@@ -0,0 +1,31 @@
+/**
+ * EnrichmentState
+ *
+ * Tracks context hashes per entity to avoid redundant LLM calls.
+ * Stored at .studiograph/enrichment-state.json.
+ *
+ * Before enriching, we hash the assembled context bundle. If the hash
+ * matches the stored value, we skip — the entity has already been
+ * enriched with identical context. When new references appear, the
+ * hash changes and the entity is re-enriched.
+ */
+export interface EnrichmentStateData {
+    /** entity_id → SHA-256 hex of the context bundle used for last enrichment */
+    entities: Record<string, string>;
+}
+export declare class EnrichmentState {
+    private filePath;
+    private data;
+    constructor(workspacePath: string);
+    private load;
+    save(): void;
+    /**
+     * Check whether the context bundle has changed since last enrichment.
+     * Returns true if the entity should be enriched (new or changed context).
+     */
+    hasChanged(entityId: string, contextBundle: string): boolean;
+    /**
+     * Record the context hash after successful enrichment.
+     */
+    record(entityId: string, contextBundle: string): void;
+}

package/dist/services/sync/enrichment-state.js

@@ -0,0 +1,63 @@
+/**
+ * EnrichmentState
+ *
+ * Tracks context hashes per entity to avoid redundant LLM calls.
+ * Stored at .studiograph/enrichment-state.json.
+ *
+ * Before enriching, we hash the assembled context bundle. If the hash
+ * matches the stored value, we skip — the entity has already been
+ * enriched with identical context. When new references appear, the
+ * hash changes and the entity is re-enriched.
+ */
+import { createHash } from 'crypto';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+export class EnrichmentState {
+    filePath;
+    data = null;
+    constructor(workspacePath) {
+        this.filePath = join(workspacePath, '.studiograph', 'enrichment-state.json');
+    }
+    load() {
+        if (this.data)
+            return this.data;
+        if (existsSync(this.filePath)) {
+            try {
+                this.data = JSON.parse(readFileSync(this.filePath, 'utf-8'));
+            }
+            catch {
+                this.data = { entities: {} };
+            }
+        }
+        else {
+            this.data = { entities: {} };
+        }
+        return this.data;
+    }
+    save() {
+        const dir = dirname(this.filePath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        writeFileSync(this.filePath, JSON.stringify(this.load(), null, 2) + '\n', 'utf-8');
+    }
+    /**
+     * Check whether the context bundle has changed since last enrichment.
+     * Returns true if the entity should be enriched (new or changed context).
+     */
+    hasChanged(entityId, contextBundle) {
+        const hash = hashContext(contextBundle);
+        const stored = this.load().entities[entityId];
+        return stored !== hash;
+    }
+    /**
+     * Record the context hash after successful enrichment.
+     */
+    record(entityId, contextBundle) {
+        this.load().entities[entityId] = hashContext(contextBundle);
+    }
+}
+function hashContext(contextBundle) {
+    return createHash('sha256').update(contextBundle).digest('hex');
+}
+//# sourceMappingURL=enrichment-state.js.map

package/dist/services/sync/enrichment-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrichment-state.js","sourceRoot":"","sources":["../../../src/services/sync/enrichment-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACxE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAOrC,MAAM,OAAO,eAAe;IAClB,QAAQ,CAAS;IACjB,IAAI,GAA+B,IAAI,CAAC;IAEhD,YAAY,aAAqB;QAC/B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,aAAa,EAAE,cAAc,EAAE,uBAAuB,CAAC,CAAC;IAC/E,CAAC;IAEO,IAAI;QACV,IAAI,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC;QAEhC,IAAI,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC;gBACH,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAwB,CAAC;YACtF,CAAC;YAAC,MAAM,CAAC;gBACP,IAAI,CAAC,IAAI,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;YAC/B,CAAC;QACH,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;QAC/B,CAAC;QAED,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,IAAI;QACF,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACnC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACrB,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACtC,CAAC;QACD,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;IACrF,CAAC;IAED;;;OAGG;IACH,UAAU,CAAC,QAAgB,EAAE,aAAqB;QAChD,MAAM,IAAI,GAAG,WAAW,CAAC,aAAa,CAAC,CAAC;QACxC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC9C,OAAO,MAAM,KAAK,IAAI,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,QAAgB,EAAE,aAAqB;QAC5C,IAAI,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,WAAW,CAAC,aAAa,CAAC,CAAC;IAC9D,CAAC;CACF;AAED,SAAS,WAAW,CAAC,aAAqB;IACxC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAClE,CAAC"}

package/dist/services/sync/enrichment.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Enrichment runner
+ *
+ * Enriches existing entities with cross-source context via LLM.
+ * Writes enriched files directly to repos (overwrite, no commit).
+ * User reviews via git diff, then commits or aborts.
+ */
+export interface EnrichOptions {
+    workspacePath: string;
+    entityTypes?: string[];
+    dryRun?: boolean;
+    minRefs?: number;
+    maxCompleteness?: number;
+    concurrency?: number;
+    schemaExtensions?: Record<string, any>;
+}
+export interface EnrichResult {
+    enriched: number;
+    skipped: number;
+    errors: {
+        entityId: string;
+        error: string;
+    }[];
+}
+export declare function runEnrichment(options: EnrichOptions, onProgress?: (msg: string) => void): Promise<EnrichResult>;