@rasensio/aidlc 0.7.0 → 1.1.0

package/dist/knowledge/index/sqlite-index.js

@@ -0,0 +1,354 @@
+/**
+ * SQLite implementation of KnowledgeIndex using the Node standard library
+ * (`node:sqlite`, Node >= 22) — zero npm dependencies (design DD1).
+ *
+ * FTS5 powers full-text search; if the runtime's SQLite build lacks FTS5 the
+ * index falls back to LIKE matching with a one-time stderr warning. The
+ * database is a disposable cache at `.aidlc/knowledge/index.db`, gitignored
+ * and rebuildable from YAML at any time (KG Req 3.1–3.3).
+ *
+ * Requirements: KG 3.1–3.8, 10.1–10.3, 11.4
+ *
+ * @module
+ */
+import { DatabaseSync } from 'node:sqlite';
+import { join } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { KNOWLEDGE_SCHEMA_VERSION } from '../types.js';
+import { IndexOutdatedError } from './knowledge-index.js';
+/** Filename of the index database inside the knowledge directory. */
+export const INDEX_DB_FILE = 'index.db';
+export class SqliteIndex {
+    db;
+    ftsAvailable = true;
+    ftsWarned = false;
+    /**
+     * @param knowledgeDir - Directory holding YAML sources; index.db is created here.
+     * @param dbPathOverride - Test hook: use ':memory:' for an ephemeral index.
+     */
+    constructor(knowledgeDir, dbPathOverride) {
+        const dbPath = dbPathOverride ?? join(knowledgeDir, INDEX_DB_FILE);
+        if (!dbPathOverride)
+            mkdirSync(knowledgeDir, { recursive: true });
+        this.db = new DatabaseSync(dbPath);
+        this.db.exec('PRAGMA journal_mode = WAL');
+        this.ensureSchema();
+    }
+    // -------------------------------------------------------------------------
+    // Schema
+    // -------------------------------------------------------------------------
+    ensureSchema() {
+        const version = this.readSchemaVersion();
+        if (version === 0) {
+            this.createSchema();
+        }
+        else if (version < KNOWLEDGE_SCHEMA_VERSION) {
+            // Refuse to serve; migration is rebuild-from-YAML (KG Req 11.4)
+            throw new IndexOutdatedError(version, KNOWLEDGE_SCHEMA_VERSION);
+        }
+    }
+    readSchemaVersion() {
+        try {
+            const row = this.db
+                .prepare('SELECT version FROM _schema_version ORDER BY rowid DESC LIMIT 1')
+                .get();
+            return row?.version ?? 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    createSchema() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS _schema_version (
+        version INTEGER NOT NULL,
+        created_at TEXT NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS entities (
+        id TEXT PRIMARY KEY,
+        type TEXT NOT NULL,
+        name TEXT NOT NULL,
+        description TEXT NOT NULL,
+        confidence REAL NOT NULL DEFAULT 0.5,
+        source TEXT NOT NULL DEFAULT 'agent-inferred',
+        author TEXT NOT NULL DEFAULT 'unknown',
+        tags TEXT NOT NULL DEFAULT '[]',
+        last_verified TEXT NOT NULL,
+        metadata TEXT DEFAULT '{}',
+        source_file TEXT NOT NULL DEFAULT ''
+      );
+
+      CREATE TABLE IF NOT EXISTS relationships (
+        from_entity TEXT NOT NULL,
+        to_entity TEXT NOT NULL,
+        type TEXT NOT NULL,
+        metadata TEXT DEFAULT '{}',
+        last_verified TEXT NOT NULL,
+        UNIQUE(from_entity, to_entity, type)
+      );
+
+      CREATE TABLE IF NOT EXISTS file_mappings (
+        file_path TEXT NOT NULL,
+        entity_id TEXT NOT NULL,
+        PRIMARY KEY (file_path, entity_id)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_entities_type ON entities(type);
+      CREATE INDEX IF NOT EXISTS idx_entities_confidence ON entities(confidence);
+      CREATE INDEX IF NOT EXISTS idx_relationships_from ON relationships(from_entity);
+      CREATE INDEX IF NOT EXISTS idx_relationships_to ON relationships(to_entity);
+      CREATE INDEX IF NOT EXISTS idx_relationships_type ON relationships(type);
+    `);
+        try {
+            // search_text carries a tokenizer-friendly normalization of name+tags
+            // (camelCase/kebab-case split) so code identifiers match (design risk 3).
+            this.db.exec(`
+        CREATE VIRTUAL TABLE IF NOT EXISTS entities_fts USING fts5(
+          id UNINDEXED, name, description, tags, search_text
+        );
+      `);
+        }
+        catch {
+            this.ftsAvailable = false;
+        }
+        this.db
+            .prepare('INSERT INTO _schema_version (version, created_at) VALUES (?, ?)')
+            .run(KNOWLEDGE_SCHEMA_VERSION, new Date().toISOString());
+    }
+    // -------------------------------------------------------------------------
+    // Entities
+    // -------------------------------------------------------------------------
+    getEntity(id) {
+        const row = this.db.prepare('SELECT * FROM entities WHERE id = ?').get(id);
+        return row ? rowToEntity(row) : undefined;
+    }
+    upsertEntity(entity) {
+        this.db
+            .prepare(`INSERT OR REPLACE INTO entities
+         (id, type, name, description, confidence, source, author, tags, last_verified, metadata, source_file)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(entity.id, entity.type, entity.name, entity.description, entity.confidence, entity.source, entity.author, JSON.stringify(entity.tags), entity.lastVerified, JSON.stringify(entity.metadata ?? {}), entity.source);
+        this.syncFts(entity);
+        this.syncFileMapping(entity);
+    }
+    deleteEntity(id) {
+        if (this.ftsAvailable) {
+            this.db.prepare('DELETE FROM entities_fts WHERE id = ?').run(id);
+        }
+        this.db.prepare('DELETE FROM file_mappings WHERE entity_id = ?').run(id);
+        this.db.prepare('DELETE FROM entities WHERE id = ?').run(id);
+    }
+    fullTextSearch(term, options = {}) {
+        const limit = options.limit ?? 20;
+        const minConfidence = options.minConfidence ?? 0;
+        if (this.ftsAvailable) {
+            try {
+                return this.ftsSearch(term, options.type, minConfidence, limit);
+            }
+            catch {
+                // FTS5 query syntax error on user input — fall back to LIKE.
+            }
+        }
+        this.warnNoFts();
+        return this.likeSearch(term, options.type, minConfidence, limit);
+    }
+    ftsSearch(term, type, minConfidence, limit) {
+        // Tokenize the query the same way FTS5's default tokenizer splits text —
+        // on non-alphanumeric boundaries — so punctuation in the term can't glue
+        // tokens together and miss the indexed words.
+        const tokens = term.split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+        if (tokens.length === 0) {
+            return this.likeSearch(term, type, minConfidence, limit);
+        }
+        const ftsQuery = tokens.map((t) => `"${t}"`).join(' OR ');
+        let sql = `
+      SELECT e.* FROM entities e
+      JOIN entities_fts f ON e.id = f.id
+      WHERE entities_fts MATCH ?
+        AND e.confidence >= ?`;
+        const params = [ftsQuery, minConfidence];
+        if (type) {
+            sql += ' AND e.type = ?';
+            params.push(type);
+        }
+        sql += ' ORDER BY f.rank, e.confidence DESC LIMIT ?';
+        params.push(limit);
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(rowToEntity);
+    }
+    likeSearch(term, type, minConfidence, limit) {
+        const like = `%${term.toLowerCase()}%`;
+        let sql = `
+      SELECT * FROM entities
+      WHERE (lower(name) LIKE ? OR lower(description) LIKE ? OR lower(tags) LIKE ?)
+        AND confidence >= ?`;
+        const params = [like, like, like, minConfidence];
+        if (type) {
+            sql += ' AND type = ?';
+            params.push(type);
+        }
+        sql += ' ORDER BY confidence DESC LIMIT ?';
+        params.push(limit);
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(rowToEntity);
+    }
+    getAllEntities(filter = {}) {
+        let sql = 'SELECT * FROM entities';
+        const params = [];
+        if (filter.minConfidence !== undefined) {
+            sql += ' WHERE confidence >= ?';
+            params.push(filter.minConfidence);
+        }
+        sql += ' ORDER BY confidence DESC, last_verified DESC';
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(rowToEntity);
+    }
+    getEntitiesByTypes(types, filter = {}) {
+        if (types.length === 0)
+            return [];
+        const placeholders = types.map(() => '?').join(',');
+        let sql = `SELECT * FROM entities WHERE type IN (${placeholders})`;
+        const params = [...types];
+        if (filter.minConfidence !== undefined) {
+            sql += ' AND confidence >= ?';
+            params.push(filter.minConfidence);
+        }
+        sql += ' ORDER BY confidence DESC';
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(rowToEntity);
+    }
+    getEntitiesByFilePath(path) {
+        const rows = this.db
+            .prepare(`SELECT e.* FROM entities e
+         JOIN file_mappings m ON e.id = m.entity_id
+         WHERE m.file_path = ?`)
+            .all(path);
+        return rows.map(rowToEntity);
+    }
+    countEntitiesByType(type) {
+        const row = this.db
+            .prepare('SELECT COUNT(*) AS n FROM entities WHERE type = ?')
+            .get(type);
+        return row.n;
+    }
+    // -------------------------------------------------------------------------
+    // Relationships
+    // -------------------------------------------------------------------------
+    upsertRelationship(rel) {
+        this.db
+            .prepare(`INSERT OR REPLACE INTO relationships
+         (from_entity, to_entity, type, metadata, last_verified)
+         VALUES (?, ?, ?, ?, ?)`)
+            .run(rel.from, rel.to, rel.type, JSON.stringify(rel.metadata ?? {}), rel.lastVerified);
+    }
+    relationshipsFrom(id) {
+        const rows = this.db
+            .prepare('SELECT * FROM relationships WHERE from_entity = ?')
+            .all(id);
+        return rows.map(rowToRelationship);
+    }
+    relationshipsTo(id) {
+        const rows = this.db
+            .prepare('SELECT * FROM relationships WHERE to_entity = ?')
+            .all(id);
+        return rows.map(rowToRelationship);
+    }
+    relationshipsFor(ids) {
+        if (ids.length === 0)
+            return [];
+        const placeholders = ids.map(() => '?').join(',');
+        const rows = this.db
+            .prepare(`SELECT * FROM relationships
+         WHERE from_entity IN (${placeholders}) OR to_entity IN (${placeholders})`)
+            .all(...ids, ...ids);
+        return rows.map(rowToRelationship);
+    }
+    countRelationshipsByType(type) {
+        const row = this.db
+            .prepare('SELECT COUNT(*) AS n FROM relationships WHERE type = ?')
+            .get(type);
+        return row.n;
+    }
+    // -------------------------------------------------------------------------
+    // Rebuild
+    // -------------------------------------------------------------------------
+    rebuild(entities, relationships) {
+        this.db.exec('BEGIN');
+        try {
+            this.db.exec('DELETE FROM relationships');
+            this.db.exec('DELETE FROM file_mappings');
+            this.db.exec('DELETE FROM entities');
+            if (this.ftsAvailable)
+                this.db.exec('DELETE FROM entities_fts');
+            for (const entity of entities)
+                this.upsertEntity(entity);
+            for (const rel of relationships)
+                this.upsertRelationship(rel);
+            this.db.exec('COMMIT');
+        }
+        catch (err) {
+            this.db.exec('ROLLBACK');
+            throw err;
+        }
+    }
+    close() {
+        this.db.close();
+    }
+    // -------------------------------------------------------------------------
+    // Internals
+    // -------------------------------------------------------------------------
+    syncFts(entity) {
+        if (!this.ftsAvailable)
+            return;
+        this.db.prepare('DELETE FROM entities_fts WHERE id = ?').run(entity.id);
+        this.db
+            .prepare('INSERT INTO entities_fts (id, name, description, tags, search_text) VALUES (?, ?, ?, ?, ?)')
+            .run(entity.id, entity.name, entity.description, entity.tags.join(' '), normalizeSearchText(`${entity.id} ${entity.name} ${entity.tags.join(' ')}`));
+    }
+    syncFileMapping(entity) {
+        this.db.prepare('DELETE FROM file_mappings WHERE entity_id = ?').run(entity.id);
+        if (entity.source && entity.source !== 'agent-inferred') {
+            this.db
+                .prepare('INSERT OR REPLACE INTO file_mappings (file_path, entity_id) VALUES (?, ?)')
+                .run(entity.source, entity.id);
+        }
+    }
+    warnNoFts() {
+        if (this.ftsAvailable || this.ftsWarned)
+            return;
+        this.ftsWarned = true;
+        process.stderr.write('Warning: SQLite FTS5 unavailable in this Node build; using slower LIKE search.\n');
+    }
+}
+/** Split camelCase and kebab/snake-case identifiers into searchable words. */
+export function normalizeSearchText(text) {
+    return text
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[-_./]/g, ' ')
+        .toLowerCase();
+}
+function rowToEntity(row) {
+    return {
+        id: row.id,
+        type: row.type,
+        name: row.name,
+        description: row.description,
+        confidence: row.confidence,
+        source: row.source,
+        author: row.author,
+        tags: JSON.parse(row.tags),
+        lastVerified: row.last_verified,
+        metadata: JSON.parse(row.metadata || '{}'),
+    };
+}
+function rowToRelationship(row) {
+    return {
+        from: row.from_entity,
+        to: row.to_entity,
+        type: row.type,
+        metadata: JSON.parse(row.metadata || '{}'),
+        lastVerified: row.last_verified,
+    };
+}
+//# sourceMappingURL=sqlite-index.js.map

package/dist/knowledge/index/sqlite-index.js.map

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

package/dist/knowledge/merge-driver.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Custom git merge driver for `.aidlc/knowledge/*.yaml` — a pure 3-way merge
+ * over entity/relationship documents (design DD5).
+ *
+ * Resolution for same-id conflicts (KG Req 12.3): higher confidence wins,
+ * newer lastVerified supplies description and author, tags union-merge,
+ * metadata merges with the newer side taking precedence. No entity present
+ * in ours or theirs is ever lost (correctness property 10); deletions are
+ * handled by `compact`, not by merges.
+ *
+ * Requirements: KG 12.2, 12.3
+ *
+ * @module
+ */
+import type { Entity } from './types.js';
+export interface MergeConflict {
+    id: string;
+    ours: Entity;
+    theirs: Entity;
+    resolution: Entity;
+}
+export interface MergeResult {
+    /** Serialized merged YAML file content. */
+    content: string;
+    /** Same-id conflicts that were auto-resolved. */
+    conflicts: MergeConflict[];
+    warnings: string[];
+}
+/** Resolve a same-id conflict per KG Req 12.3. */
+export declare function resolveEntityConflict(ours: Entity, theirs: Entity): Entity;
+/**
+ * 3-way merge of one knowledge YAML file. Pure function of the three
+ * contents; git integration is handled by the CLI command wrapper.
+ */
+export declare function mergeKnowledgeFiles(base: string, ours: string, theirs: string): MergeResult;
+//# sourceMappingURL=merge-driver.d.ts.map

package/dist/knowledge/merge-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-driver.d.ts","sourceRoot":"","sources":["../../src/knowledge/merge-driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAgC,MAAM,YAAY,CAAC;AAEvE,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAkDD,kDAAkD;AAClD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAgB1E;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,CAiD3F"}

package/dist/knowledge/merge-driver.js

@@ -0,0 +1,130 @@
+/**
+ * Custom git merge driver for `.aidlc/knowledge/*.yaml` — a pure 3-way merge
+ * over entity/relationship documents (design DD5).
+ *
+ * Resolution for same-id conflicts (KG Req 12.3): higher confidence wins,
+ * newer lastVerified supplies description and author, tags union-merge,
+ * metadata merges with the newer side taking precedence. No entity present
+ * in ours or theirs is ever lost (correctness property 10); deletions are
+ * handled by `compact`, not by merges.
+ *
+ * Requirements: KG 12.2, 12.3
+ *
+ * @module
+ */
+import { parseAllDocuments, stringify } from 'yaml';
+/** Key uniquely identifying a relationship document. */
+function relationshipKey(rel) {
+    return `${rel.from}|${rel.type}|${rel.to}`;
+}
+function parseFile(content, label) {
+    const result = {
+        meta: null,
+        entities: new Map(),
+        relationships: new Map(),
+        warnings: [],
+    };
+    let docs;
+    try {
+        docs = parseAllDocuments(content);
+    }
+    catch (err) {
+        result.warnings.push(`${label}: unparseable YAML (${err.message})`);
+        return result;
+    }
+    for (const doc of docs) {
+        if (doc.errors.length > 0) {
+            result.warnings.push(`${label}: skipped corrupt document`);
+            continue;
+        }
+        const obj = doc.toJSON();
+        if (!obj || typeof obj !== 'object')
+            continue;
+        if ('_meta' in obj) {
+            result.meta = obj._meta;
+        }
+        else if (typeof obj.from === 'string' && typeof obj.to === 'string') {
+            const rel = obj;
+            result.relationships.set(relationshipKey(rel), rel);
+        }
+        else if (typeof obj.id === 'string') {
+            result.entities.set(obj.id, obj);
+        }
+    }
+    return result;
+}
+/** Resolve a same-id conflict per KG Req 12.3. */
+export function resolveEntityConflict(ours, theirs) {
+    const ourTime = ours.lastVerified ?? '';
+    const theirTime = theirs.lastVerified ?? '';
+    const newer = ourTime >= theirTime ? ours : theirs;
+    const older = ourTime >= theirTime ? theirs : ours;
+    return {
+        ...older,
+        ...newer,
+        confidence: Math.max(ours.confidence ?? 0, theirs.confidence ?? 0),
+        lastVerified: newer.lastVerified,
+        description: newer.description || older.description,
+        author: newer.author ?? older.author,
+        tags: [...new Set([...(ours.tags ?? []), ...(theirs.tags ?? [])])],
+        metadata: { ...older.metadata, ...newer.metadata },
+    };
+}
+/**
+ * 3-way merge of one knowledge YAML file. Pure function of the three
+ * contents; git integration is handled by the CLI command wrapper.
+ */
+export function mergeKnowledgeFiles(base, ours, theirs) {
+    const baseFile = parseFile(base, 'base');
+    const ourFile = parseFile(ours, 'ours');
+    const theirFile = parseFile(theirs, 'theirs');
+    const warnings = [...baseFile.warnings, ...ourFile.warnings, ...theirFile.warnings];
+    const conflicts = [];
+    // Entities: union of ours ∪ theirs (property 10: nothing is lost).
+    const merged = [];
+    const allIds = new Set([...ourFile.entities.keys(), ...theirFile.entities.keys()]);
+    for (const id of allIds) {
+        const ourEntity = ourFile.entities.get(id);
+        const theirEntity = theirFile.entities.get(id);
+        if (ourEntity && !theirEntity) {
+            merged.push(ourEntity);
+        }
+        else if (!ourEntity && theirEntity) {
+            merged.push(theirEntity);
+        }
+        else if (ourEntity && theirEntity) {
+            if (deepEqual(ourEntity, theirEntity)) {
+                merged.push(ourEntity);
+            }
+            else {
+                const resolution = resolveEntityConflict(ourEntity, theirEntity);
+                conflicts.push({ id, ours: ourEntity, theirs: theirEntity, resolution });
+                merged.push(resolution);
+            }
+        }
+    }
+    // Relationships: union by (from, type, to); newer lastVerified wins on clash.
+    const relationships = new Map();
+    for (const [key, rel] of theirFile.relationships)
+        relationships.set(key, rel);
+    for (const [key, rel] of ourFile.relationships) {
+        const existing = relationships.get(key);
+        if (!existing || (rel.lastVerified ?? '') >= (existing.lastVerified ?? '')) {
+            relationships.set(key, rel);
+        }
+    }
+    // Serialize: meta header (ours wins, else theirs/base), entities, relationships.
+    const meta = ourFile.meta ?? theirFile.meta ?? baseFile.meta;
+    const parts = [];
+    if (meta)
+        parts.push(stringify({ _meta: meta }));
+    for (const entity of merged)
+        parts.push(stringify(entity, { lineWidth: 100 }));
+    for (const rel of relationships.values())
+        parts.push(stringify(rel, { lineWidth: 100 }));
+    return { content: parts.join('---\n'), conflicts, warnings };
+}
+function deepEqual(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+//# sourceMappingURL=merge-driver.js.map

package/dist/knowledge/merge-driver.js.map

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

package/dist/knowledge/reader.d.ts

@@ -0,0 +1,32 @@
+/**
+ * KnowledgeReader — query interface over the index (KG Req 5.1–5.7).
+ *
+ * Reads never touch the YAML sources; everything is served from the
+ * KnowledgeIndex. Subgraph traversal is breadth-first in application code —
+ * adequate for the target scale of ≤1000 entities (design DD1).
+ *
+ * @module
+ */
+import type { Entity, Relationship, GraphQueryResult } from './types.js';
+import type { KnowledgeIndex } from './index/knowledge-index.js';
+export interface QueryOptions {
+    type?: string;
+    minConfidence?: number;
+    limit?: number;
+}
+export interface EntityDetail {
+    entity: Entity;
+    inbound: Relationship[];
+    outbound: Relationship[];
+}
+export declare class KnowledgeReader {
+    private readonly index;
+    constructor(index: KnowledgeIndex);
+    /** Full-text search with relationships for the matched set (KG Req 5.1). */
+    search(term: string, options?: QueryOptions): GraphQueryResult;
+    /** Single entity with inbound and outbound relationships (KG Req 5.2). */
+    get(entityId: string): EntityDetail | undefined;
+    /** Subgraph of all entities within `depth` hops (KG Req 5.3). */
+    subgraph(entityId: string, depth: number): GraphQueryResult;
+}
+//# sourceMappingURL=reader.d.ts.map

package/dist/knowledge/reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../src/knowledge/reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAEjE,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,cAAc;IAElD,4EAA4E;IAC5E,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,gBAAgB;IAWlE,0EAA0E;IAC1E,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAU/C,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,gBAAgB;CAqC5D"}

package/dist/knowledge/reader.js

@@ -0,0 +1,74 @@
+/**
+ * KnowledgeReader — query interface over the index (KG Req 5.1–5.7).
+ *
+ * Reads never touch the YAML sources; everything is served from the
+ * KnowledgeIndex. Subgraph traversal is breadth-first in application code —
+ * adequate for the target scale of ≤1000 entities (design DD1).
+ *
+ * @module
+ */
+export class KnowledgeReader {
+    index;
+    constructor(index) {
+        this.index = index;
+    }
+    /** Full-text search with relationships for the matched set (KG Req 5.1). */
+    search(term, options = {}) {
+        const searchOptions = {};
+        if (options.type !== undefined)
+            searchOptions.type = options.type;
+        if (options.minConfidence !== undefined)
+            searchOptions.minConfidence = options.minConfidence;
+        if (options.limit !== undefined)
+            searchOptions.limit = options.limit;
+        const entities = this.index.fullTextSearch(term, searchOptions);
+        const relationships = this.index.relationshipsFor(entities.map((e) => e.id));
+        return { entities, relationships, totalCount: entities.length };
+    }
+    /** Single entity with inbound and outbound relationships (KG Req 5.2). */
+    get(entityId) {
+        const entity = this.index.getEntity(entityId);
+        if (!entity)
+            return undefined;
+        return {
+            entity,
+            inbound: this.index.relationshipsTo(entityId),
+            outbound: this.index.relationshipsFrom(entityId),
+        };
+    }
+    /** Subgraph of all entities within `depth` hops (KG Req 5.3). */
+    subgraph(entityId, depth) {
+        const visited = new Set();
+        const entities = [];
+        const relationshipKeys = new Set();
+        const relationships = [];
+        const queue = [{ id: entityId, depth: 0 }];
+        while (queue.length > 0) {
+            const item = queue.shift();
+            if (visited.has(item.id) || item.depth > depth)
+                continue;
+            const entity = this.index.getEntity(item.id);
+            if (!entity)
+                continue;
+            visited.add(item.id);
+            entities.push(entity);
+            for (const rel of [...this.index.relationshipsFrom(item.id), ...this.index.relationshipsTo(item.id)]) {
+                const key = `${rel.from}|${rel.type}|${rel.to}`;
+                if (!relationshipKeys.has(key)) {
+                    relationshipKeys.add(key);
+                    relationships.push(rel);
+                }
+                const neighbor = rel.from === item.id ? rel.to : rel.from;
+                if (!visited.has(neighbor)) {
+                    queue.push({ id: neighbor, depth: item.depth + 1 });
+                }
+            }
+        }
+        // Keep only relationships whose endpoints are both in the subgraph, so the
+        // result is self-contained at every depth (subgraph monotonicity property).
+        const inGraph = new Set(entities.map((e) => e.id));
+        const contained = relationships.filter((r) => inGraph.has(r.from) && inGraph.has(r.to));
+        return { entities, relationships: contained, totalCount: entities.length };
+    }
+}
+//# sourceMappingURL=reader.js.map