@rasensio/aidlc 0.6.0 → 1.1.0

package/dist/knowledge/types.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Data model for the local knowledge graph.
+ *
+ * Entities and relationships are stored as YAML source files in
+ * `.aidlc/knowledge/` (source of truth) and mirrored into a SQLite index
+ * (derived cache). Built-in types are closed sets; `custom:<name>` extends
+ * both without a schema change.
+ *
+ * Requirements: KG 1.1–1.5, 2.4, 11.1
+ *
+ * @module
+ */
+/** Built-in entity types (KG Req 1.1). */
+export declare const ENTITY_TYPES: readonly ["module", "service", "domain-entity", "convention", "decision", "debt", "dependency", "endpoint", "config"];
+export type BuiltInEntityType = (typeof ENTITY_TYPES)[number];
+export type EntityType = BuiltInEntityType | `custom:${string}`;
+/** Built-in relationship types (KG Req 1.4). */
+export declare const RELATIONSHIP_TYPES: readonly ["depends-on", "implements", "calls", "owns", "contains", "extends", "uses", "produces", "consumes", "conflicts-with"];
+export type BuiltInRelationshipType = (typeof RELATIONSHIP_TYPES)[number];
+export type RelationshipType = BuiltInRelationshipType | `custom:${string}`;
+/** Current schema version for YAML sources and the SQLite index (KG Req 11.1). */
+export declare const KNOWLEDGE_SCHEMA_VERSION = 1;
+/** Confidence assigned to facts inferred by static analysis (KG Req 8.3). */
+export declare const DISCOVERY_CONFIDENCE = 0.6;
+/** Default confidence for agent-asserted facts (KG Req 8.3). */
+export declare const AGENT_CONFIDENCE = 0.9;
+/** Entities below this confidence are excluded from context output (KG Req 7.5). */
+export declare const STALE_CONFIDENCE_FLOOR = 0.3;
+/** A node in the knowledge graph (KG Req 1.2, 12.1). */
+export interface Entity {
+    /** Unique lowercase slug, e.g. "payment-service". */
+    id: string;
+    type: EntityType;
+    /** Human-readable name. */
+    name: string;
+    /** Free-text explanation. */
+    description: string;
+    /** Certainty 0.0–1.0. */
+    confidence: number;
+    /** File path the fact derives from, or "agent-inferred". */
+    source: string;
+    /** Who asserted the fact: git user name, "auto-discovery", or AIDLC_AUTHOR. */
+    author: string;
+    tags: string[];
+    /** ISO 8601 timestamp of last confirmation. */
+    lastVerified: string;
+    metadata?: Record<string, unknown>;
+}
+/** A directed, typed edge between two entities (KG Req 1.3). */
+export interface Relationship {
+    /** Source entity id. */
+    from: string;
+    /** Target entity id. */
+    to: string;
+    type: RelationshipType;
+    metadata?: Record<string, unknown>;
+    lastVerified: string;
+}
+/** `_meta` header document present in every YAML source file (KG Req 2.4). */
+export interface SourceFileMeta {
+    schemaVersion: number;
+    lastIndexed: string;
+    entityType: string;
+}
+export interface GraphQueryResult {
+    entities: Entity[];
+    relationships: Relationship[];
+    totalCount: number;
+}
+export interface ContextOutput {
+    markdown: string;
+    tokenEstimate: number;
+    entityCount: number;
+    sections: string[];
+}
+/** Entity ids are lowercase slugs: letters, digits, hyphens. */
+export declare const ENTITY_ID_RE: RegExp;
+export declare function isValidEntityType(type: string): boolean;
+export declare function isValidRelationshipType(type: string): boolean;
+/**
+ * Map an entity type to its YAML source filename (KG Req 2.1).
+ * Custom types share a single `custom.yaml`.
+ */
+export declare function sourceFileForType(type: string): string;
+/** Relationships live in a dedicated cross-cutting file. */
+export declare const RELATIONSHIPS_FILE = "relationships.yaml";
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/knowledge/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,0CAA0C;AAC1C,eAAO,MAAM,YAAY,uHAUf,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAC9D,MAAM,MAAM,UAAU,GAAG,iBAAiB,GAAG,UAAU,MAAM,EAAE,CAAC;AAEhE,gDAAgD;AAChD,eAAO,MAAM,kBAAkB,iIAWrB,CAAC;AAEX,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC1E,MAAM,MAAM,gBAAgB,GAAG,uBAAuB,GAAG,UAAU,MAAM,EAAE,CAAC;AAE5E,kFAAkF;AAClF,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,gEAAgE;AAChE,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,oFAAoF;AACpF,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAM1C,wDAAwD;AACxD,MAAM,WAAW,MAAM;IACrB,qDAAqD;IACrD,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,+CAA+C;IAC/C,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAMD,gEAAgE;AAChE,eAAO,MAAM,YAAY,QAAyB,CAAC;AAEnD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAKvD;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAK7D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAatD;AAED,4DAA4D;AAC5D,eAAO,MAAM,kBAAkB,uBAAuB,CAAC"}

package/dist/knowledge/types.js

@@ -0,0 +1,82 @@
+/**
+ * Data model for the local knowledge graph.
+ *
+ * Entities and relationships are stored as YAML source files in
+ * `.aidlc/knowledge/` (source of truth) and mirrored into a SQLite index
+ * (derived cache). Built-in types are closed sets; `custom:<name>` extends
+ * both without a schema change.
+ *
+ * Requirements: KG 1.1–1.5, 2.4, 11.1
+ *
+ * @module
+ */
+// ---------------------------------------------------------------------------
+// Type constants
+// ---------------------------------------------------------------------------
+/** Built-in entity types (KG Req 1.1). */
+export const ENTITY_TYPES = [
+    'module',
+    'service',
+    'domain-entity',
+    'convention',
+    'decision',
+    'debt',
+    'dependency',
+    'endpoint',
+    'config',
+];
+/** Built-in relationship types (KG Req 1.4). */
+export const RELATIONSHIP_TYPES = [
+    'depends-on',
+    'implements',
+    'calls',
+    'owns',
+    'contains',
+    'extends',
+    'uses',
+    'produces',
+    'consumes',
+    'conflicts-with',
+];
+/** Current schema version for YAML sources and the SQLite index (KG Req 11.1). */
+export const KNOWLEDGE_SCHEMA_VERSION = 1;
+/** Confidence assigned to facts inferred by static analysis (KG Req 8.3). */
+export const DISCOVERY_CONFIDENCE = 0.6;
+/** Default confidence for agent-asserted facts (KG Req 8.3). */
+export const AGENT_CONFIDENCE = 0.9;
+/** Entities below this confidence are excluded from context output (KG Req 7.5). */
+export const STALE_CONFIDENCE_FLOOR = 0.3;
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+/** Entity ids are lowercase slugs: letters, digits, hyphens. */
+export const ENTITY_ID_RE = /^[a-z0-9][a-z0-9-]*$/;
+export function isValidEntityType(type) {
+    return (ENTITY_TYPES.includes(type) ||
+        (type.startsWith('custom:') && type.length > 'custom:'.length));
+}
+export function isValidRelationshipType(type) {
+    return (RELATIONSHIP_TYPES.includes(type) ||
+        (type.startsWith('custom:') && type.length > 'custom:'.length));
+}
+/**
+ * Map an entity type to its YAML source filename (KG Req 2.1).
+ * Custom types share a single `custom.yaml`.
+ */
+export function sourceFileForType(type) {
+    const map = {
+        module: 'modules.yaml',
+        service: 'services.yaml',
+        'domain-entity': 'domain-entities.yaml',
+        convention: 'conventions.yaml',
+        decision: 'decisions.yaml',
+        debt: 'debt.yaml',
+        dependency: 'dependencies.yaml',
+        endpoint: 'endpoints.yaml',
+        config: 'config-entities.yaml',
+    };
+    return map[type] ?? 'custom.yaml';
+}
+/** Relationships live in a dedicated cross-cutting file. */
+export const RELATIONSHIPS_FILE = 'relationships.yaml';
+//# sourceMappingURL=types.js.map

package/dist/knowledge/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/knowledge/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,0CAA0C;AAC1C,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ;IACR,SAAS;IACT,eAAe;IACf,YAAY;IACZ,UAAU;IACV,MAAM;IACN,YAAY;IACZ,UAAU;IACV,QAAQ;CACA,CAAC;AAKX,gDAAgD;AAChD,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,YAAY;IACZ,YAAY;IACZ,OAAO;IACP,MAAM;IACN,UAAU;IACV,SAAS;IACT,MAAM;IACN,UAAU;IACV,UAAU;IACV,gBAAgB;CACR,CAAC;AAKX,kFAAkF;AAClF,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAE1C,6EAA6E;AAC7E,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAExC,gEAAgE;AAChE,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAEpC,oFAAoF;AACpF,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AA8D1C,8EAA8E;AAC9E,qBAAqB;AACrB,8EAA8E;AAE9E,gEAAgE;AAChE,MAAM,CAAC,MAAM,YAAY,GAAG,sBAAsB,CAAC;AAEnD,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,CACJ,YAAkC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAClD,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAC/D,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,IAAY;IAClD,OAAO,CACJ,kBAAwC,CAAC,QAAQ,CAAC,IAAI,CAAC;QACxD,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAC/D,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,MAAM,GAAG,GAA2B;QAClC,MAAM,EAAE,cAAc;QACtB,OAAO,EAAE,eAAe;QACxB,eAAe,EAAE,sBAAsB;QACvC,UAAU,EAAE,kBAAkB;QAC9B,QAAQ,EAAE,gBAAgB;QAC1B,IAAI,EAAE,WAAW;QACjB,UAAU,EAAE,mBAAmB;QAC/B,QAAQ,EAAE,gBAAgB;QAC1B,MAAM,EAAE,sBAAsB;KAC/B,CAAC;IACF,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,aAAa,CAAC;AACpC,CAAC;AAED,4DAA4D;AAC5D,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAAoB,CAAC"}

package/dist/knowledge/writer.d.ts

@@ -0,0 +1,67 @@
+/**
+ * KnowledgeWriter — validated writes to the YAML sources plus index sync.
+ *
+ * Same-id adds merge instead of duplicating (KG Req 4.4): union tags, keep
+ * the higher confidence, prefer the incoming description, bump lastVerified.
+ * Descriptions and metadata are screened for common secret patterns with a
+ * warning — never store credentials in the graph (NFR N6).
+ *
+ * Requirements: KG 4.1–4.6, 12.1, 12.5
+ *
+ * @module
+ */
+import type { Entity, Relationship } from './types.js';
+import type { YamlSourceStore } from './yaml-source.js';
+import type { KnowledgeIndex } from './index/knowledge-index.js';
+export interface WriteResult {
+    entity: Entity;
+    merged: boolean;
+    warnings: string[];
+}
+export interface ImportResult {
+    added: number;
+    updated: number;
+    errors: string[];
+    warnings: string[];
+}
+/** Resolve the author for a write: AIDLC_AUTHOR → git user.name → "unknown" (KG Req 12.1). */
+export declare function resolveAuthor(cwd?: string): string;
+export declare class KnowledgeWriter {
+    private readonly source;
+    private readonly index;
+    constructor(source: YamlSourceStore, index: KnowledgeIndex);
+    /**
+     * Add an entity; if the id already exists, merge fields (KG Req 4.4).
+     * Fills defaults: confidence 0.9, author resolution, lastVerified now.
+     */
+    addEntity(input: Partial<Entity> & {
+        id: string;
+        type: string;
+        name: string;
+    }): WriteResult;
+    /** Create a relationship between two existing entities (KG Req 4.2). */
+    addRelationship(input: {
+        from: string;
+        to: string;
+        type: string;
+        metadata?: Record<string, unknown>;
+    }): Relationship;
+    /** Update fields on an existing entity (KG Req 4.3). */
+    updateEntity(id: string, updates: Partial<Pick<Entity, 'description' | 'confidence' | 'tags' | 'name' | 'source' | 'metadata'>>): WriteResult;
+    /** Bulk import entities then relationships; per-item errors don't abort (KG Req 4.6). */
+    importBatch(entities: Array<Partial<Entity> & {
+        id: string;
+        type: string;
+        name: string;
+    }>, relationships: Array<{
+        from: string;
+        to: string;
+        type: string;
+        metadata?: Record<string, unknown>;
+    }>): ImportResult;
+    private validateEntity;
+    private screenForSecrets;
+}
+/** Merge an incoming entity into an existing one (KG Req 4.4). */
+export declare function mergeEntities(existing: Entity, incoming: Entity): Entity;
+//# sourceMappingURL=writer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../src/knowledge/writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAWjE,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,8FAA8F;AAC9F,wBAAgB,aAAa,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAclD;AAED,qBAAa,eAAe;IAExB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADL,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,cAAc;IAGxC;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,WAAW;IA+B3F,wEAAwE;IACxE,eAAe,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,YAAY;IA0BpH,wDAAwD;IACxD,YAAY,CACV,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,aAAa,GAAG,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC,CAAC,GACrG,WAAW;IAoBd,yFAAyF;IACzF,WAAW,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE,aAAa,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,GAAG,YAAY;IA6B9M,OAAO,CAAC,cAAc;IAmBtB,OAAO,CAAC,gBAAgB;CAYzB;AAED,kEAAkE;AAClE,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUxE"}

package/dist/knowledge/writer.js

@@ -0,0 +1,189 @@
+/**
+ * KnowledgeWriter — validated writes to the YAML sources plus index sync.
+ *
+ * Same-id adds merge instead of duplicating (KG Req 4.4): union tags, keep
+ * the higher confidence, prefer the incoming description, bump lastVerified.
+ * Descriptions and metadata are screened for common secret patterns with a
+ * warning — never store credentials in the graph (NFR N6).
+ *
+ * Requirements: KG 4.1–4.6, 12.1, 12.5
+ *
+ * @module
+ */
+import { execSync } from 'node:child_process';
+import { ENTITY_ID_RE, isValidEntityType, isValidRelationshipType, AGENT_CONFIDENCE, } from './types.js';
+/** Patterns that suggest a credential is being written into the graph (NFR N6). */
+const SECRET_PATTERNS = [
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+    /\bAKIA[0-9A-Z]{16}\b/, // AWS access key id
+    /\bgh[pousr]_[A-Za-z0-9]{36,}\b/, // GitHub tokens
+    /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/, // Slack tokens
+    /\b(?:api[_-]?key|secret|password|token)\s*[:=]\s*['"][^'"]{8,}['"]/i,
+];
+/** Resolve the author for a write: AIDLC_AUTHOR → git user.name → "unknown" (KG Req 12.1). */
+export function resolveAuthor(cwd) {
+    const env = process.env.AIDLC_AUTHOR;
+    if (env && env.trim())
+        return env.trim();
+    try {
+        const name = execSync('git config user.name', {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        if (name)
+            return name;
+    }
+    catch {
+        // git absent or unconfigured
+    }
+    return 'unknown';
+}
+export class KnowledgeWriter {
+    source;
+    index;
+    constructor(source, index) {
+        this.source = source;
+        this.index = index;
+    }
+    /**
+     * Add an entity; if the id already exists, merge fields (KG Req 4.4).
+     * Fills defaults: confidence 0.9, author resolution, lastVerified now.
+     */
+    addEntity(input) {
+        const warnings = [];
+        const entity = {
+            id: input.id,
+            type: input.type,
+            name: input.name,
+            description: input.description ?? '',
+            confidence: input.confidence ?? AGENT_CONFIDENCE,
+            source: input.source ?? 'agent-inferred',
+            author: input.author ?? resolveAuthor(),
+            tags: input.tags ?? [],
+            lastVerified: input.lastVerified ?? new Date().toISOString(),
+            ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
+        };
+        this.validateEntity(entity);
+        this.screenForSecrets(entity, warnings);
+        const existing = this.index.getEntity(entity.id);
+        if (existing) {
+            const merged = mergeEntities(existing, entity);
+            this.source.updateEntity(merged);
+            this.index.upsertEntity(merged);
+            return { entity: merged, merged: true, warnings };
+        }
+        this.source.appendEntity(entity);
+        this.index.upsertEntity(entity);
+        return { entity, merged: false, warnings };
+    }
+    /** Create a relationship between two existing entities (KG Req 4.2). */
+    addRelationship(input) {
+        if (!isValidRelationshipType(input.type)) {
+            throw new Error(`Unknown relationship type '${input.type}'. Use one of the built-in types or 'custom:<name>'.`);
+        }
+        if (!this.index.getEntity(input.from)) {
+            throw new Error(`Entity not found: '${input.from}'. Add it first with 'aidlc knowledge add'.`);
+        }
+        if (!this.index.getEntity(input.to)) {
+            throw new Error(`Entity not found: '${input.to}'. Add it first with 'aidlc knowledge add'.`);
+        }
+        const rel = {
+            from: input.from,
+            to: input.to,
+            type: input.type,
+            ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
+            lastVerified: new Date().toISOString(),
+        };
+        this.source.appendRelationship(rel);
+        this.index.upsertRelationship(rel);
+        return rel;
+    }
+    /** Update fields on an existing entity (KG Req 4.3). */
+    updateEntity(id, updates) {
+        const existing = this.index.getEntity(id);
+        if (!existing) {
+            throw new Error(`Entity not found: '${id}'`);
+        }
+        const warnings = [];
+        const updated = {
+            ...existing,
+            ...stripUndefined(updates),
+            lastVerified: new Date().toISOString(),
+        };
+        this.validateEntity(updated);
+        this.screenForSecrets(updated, warnings);
+        this.source.updateEntity(updated);
+        this.index.upsertEntity(updated);
+        return { entity: updated, merged: false, warnings };
+    }
+    /** Bulk import entities then relationships; per-item errors don't abort (KG Req 4.6). */
+    importBatch(entities, relationships) {
+        const result = { added: 0, updated: 0, errors: [], warnings: [] };
+        for (const input of entities) {
+            try {
+                const write = this.addEntity(input);
+                if (write.merged)
+                    result.updated++;
+                else
+                    result.added++;
+                result.warnings.push(...write.warnings);
+            }
+            catch (err) {
+                result.errors.push(`${input.id ?? '<no id>'}: ${err.message}`);
+            }
+        }
+        for (const rel of relationships) {
+            try {
+                this.addRelationship(rel);
+            }
+            catch (err) {
+                result.errors.push(`${rel.from}->${rel.to}: ${err.message}`);
+            }
+        }
+        return result;
+    }
+    // -------------------------------------------------------------------------
+    // Validation
+    // -------------------------------------------------------------------------
+    validateEntity(entity) {
+        if (!entity.id || !ENTITY_ID_RE.test(entity.id)) {
+            throw new Error(`Invalid entity id '${entity.id}' (must be a lowercase slug: letters, digits, hyphens)`);
+        }
+        if (!isValidEntityType(entity.type)) {
+            throw new Error(`Unknown entity type '${entity.type}'. Use one of the built-in types or 'custom:<name>'.`);
+        }
+        if (typeof entity.confidence !== 'number' || entity.confidence < 0 || entity.confidence > 1) {
+            throw new Error(`Confidence must be between 0.0 and 1.0, got: ${entity.confidence}`);
+        }
+        if (!entity.name) {
+            throw new Error('Entity name is required');
+        }
+    }
+    screenForSecrets(entity, warnings) {
+        const text = `${entity.description} ${JSON.stringify(entity.metadata ?? {})}`;
+        for (const pattern of SECRET_PATTERNS) {
+            if (pattern.test(text)) {
+                warnings.push(`Entity '${entity.id}' may contain a credential (matched ${pattern.source.slice(0, 30)}…). ` +
+                    'Never store secrets in the knowledge graph.');
+                return;
+            }
+        }
+    }
+}
+/** Merge an incoming entity into an existing one (KG Req 4.4). */
+export function mergeEntities(existing, incoming) {
+    return {
+        ...existing,
+        name: incoming.name || existing.name,
+        description: incoming.description || existing.description,
+        confidence: Math.max(existing.confidence, incoming.confidence),
+        tags: [...new Set([...existing.tags, ...incoming.tags])],
+        lastVerified: new Date().toISOString(),
+        metadata: { ...existing.metadata, ...incoming.metadata },
+    };
+}
+function stripUndefined(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+}
+//# sourceMappingURL=writer.js.map

package/dist/knowledge/writer.js.map

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

package/dist/knowledge/yaml-source.d.ts

@@ -0,0 +1,48 @@
+/**
+ * YAML source layer — the knowledge graph's source of truth.
+ *
+ * One multi-document file per entity type plus `relationships.yaml`, each with
+ * a `_meta` header document. Writes are append-only by default (KG Req 2.5,
+ * 12.5): new entities go to the end of the file; only explicit updates rewrite
+ * an existing document. Only the affected file is ever touched (KG Req 2.3).
+ *
+ * Requirements: KG 2.1–2.5, 11.1, 12.5
+ *
+ * @module
+ */
+import type { Entity, Relationship } from './types.js';
+/** Result of loading all YAML sources. */
+export interface LoadedGraph {
+    entities: Entity[];
+    relationships: Relationship[];
+    /** Parse problems encountered (file → message); corrupted docs are skipped. */
+    warnings: string[];
+}
+export declare class YamlSourceStore {
+    private readonly knowledgeDir;
+    constructor(knowledgeDir: string);
+    /** Absolute path of the knowledge directory. */
+    get dir(): string;
+    /** True once any source file exists. */
+    exists(): boolean;
+    /** Append a new entity document to its type file (KG Req 2.5). */
+    appendEntity(entity: Entity): void;
+    /** Rewrite an existing entity document in place (explicit update path). */
+    updateEntity(entity: Entity): void;
+    /** Append a relationship document to relationships.yaml (KG Req 2.5). */
+    appendRelationship(rel: Relationship): void;
+    /**
+     * Rewrite a whole source file from scratch (used only by `compact`,
+     * the sanctioned exception to append-only — KG Req 12.6).
+     */
+    rewriteFile(filename: string, entityType: string, docs: Array<Entity | Relationship>): void;
+    /** Update the `_meta.lastIndexed` timestamp of every source file. */
+    touchLastIndexed(timestamp: string): void;
+    /** Parse every source file into entities and relationships (KG Req 3.2). */
+    loadAll(): LoadedGraph;
+    /** List YAML source files (basenames), excluding the index db. */
+    listSourceFiles(): string[];
+    private ensureFile;
+    private metaHeader;
+}
+//# sourceMappingURL=yaml-source.d.ts.map

package/dist/knowledge/yaml-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml-source.d.ts","sourceRoot":"","sources":["../../src/knowledge/yaml-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAWH,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAkB,MAAM,YAAY,CAAC;AAEvE,0CAA0C;AAC1C,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,YAAY;gBAAZ,YAAY,EAAE,MAAM;IAEjD,gDAAgD;IAChD,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED,wCAAwC;IACxC,MAAM,IAAI,OAAO;IASjB,kEAAkE;IAClE,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQlC,2EAA2E;IAC3E,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IA4BlC,yEAAyE;IACzE,kBAAkB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAQ3C;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,GAAG,YAAY,CAAC,GAAG,IAAI;IAO3F,qEAAqE;IACrE,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IA2BzC,4EAA4E;IAC5E,OAAO,IAAI,WAAW;IAkDtB,kEAAkE;IAClE,eAAe,IAAI,MAAM,EAAE;IAe3B,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,UAAU;CAQnB"}