cogmem 3.6.2

package/dist/temporal/TemporalMemoryService.d.ts

@@ -0,0 +1,62 @@
+import Database from 'bun:sqlite';
+export type TimelineEntryType = 'milestone' | 'decision' | 'correction' | 'belief_version';
+export interface TimelineEntryRecord {
+    entryId: string;
+    projectId?: string;
+    entryType: TimelineEntryType;
+    canonicalKey?: string;
+    entityId?: string;
+    beliefId?: string;
+    title: string;
+    summary?: string;
+    reason?: string;
+    occurredAt: number;
+    evidenceEventIds: string[];
+    createdAt: number;
+}
+export interface RecordTimelineEntryInput {
+    projectId?: string;
+    entryType: TimelineEntryType;
+    canonicalKey?: string;
+    entityId?: string;
+    beliefId?: string;
+    title: string;
+    summary?: string;
+    reason?: string;
+    occurredAt?: number;
+    evidenceEventIds: string[];
+}
+export interface TimelineListOptions {
+    projectId?: string;
+    canonicalKey?: string;
+    entityId?: string;
+    entryTypes?: TimelineEntryType[];
+    startTime?: number;
+    endTime?: number;
+    limit?: number;
+}
+export interface TemporalBeliefRecord {
+    beliefId: string;
+    projectId?: string;
+    canonicalKey: string;
+    statement: string;
+    status: string;
+    version: number;
+    validFrom: number;
+    validTo?: number;
+    supersedesBeliefId?: string;
+    supersededByBeliefId?: string;
+}
+export declare class TemporalMemoryService {
+    private readonly db;
+    constructor(db: Database);
+    record(input: RecordTimelineEntryInput): TimelineEntryRecord;
+    get(entryId: string): TimelineEntryRecord | null;
+    list(options?: TimelineListOptions): TimelineEntryRecord[];
+    getBeliefAt(projectId: string | undefined, canonicalKey: string, atTime: number): TemporalBeliefRecord | null;
+    getBeliefHistory(projectId: string | undefined, canonicalKey: string): TemporalBeliefRecord[];
+    private mapTimelineRow;
+    private mapBeliefRow;
+    private initializeSchema;
+}
+//# sourceMappingURL=TemporalMemoryService.d.ts.map

package/dist/temporal/TemporalMemoryService.js

@@ -0,0 +1,128 @@
+import { randomUUID } from 'node:crypto';
+export class TemporalMemoryService {
+    db;
+    constructor(db) {
+        this.db = db;
+        this.initializeSchema();
+    }
+    record(input) {
+        const title = input.title.trim();
+        if (!title)
+            throw new Error('timeline_title_required');
+        const now = Date.now();
+        const occurredAt = input.occurredAt ?? now;
+        const entryId = `timeline-${randomUUID()}`;
+        this.db.prepare(`
+      INSERT INTO memory_timeline_entries (
+        entry_id, project_id, entry_type, canonical_key, entity_id, belief_id,
+        title, summary, reason, occurred_at, evidence_event_ids_json, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(entryId, input.projectId ?? null, input.entryType, input.canonicalKey?.trim().toLowerCase() ?? null, input.entityId ?? null, input.beliefId ?? null, title, input.summary ?? null, input.reason ?? null, occurredAt, JSON.stringify([...new Set(input.evidenceEventIds)]), now);
+        return this.get(entryId);
+    }
+    get(entryId) {
+        const row = this.db.prepare(`SELECT * FROM memory_timeline_entries WHERE entry_id = ?`).get(entryId);
+        return row ? this.mapTimelineRow(row) : null;
+    }
+    list(options = {}) {
+        const conditions = [];
+        const params = [];
+        if (options.projectId) {
+            conditions.push('project_id = ?');
+            params.push(options.projectId);
+        }
+        if (options.canonicalKey) {
+            conditions.push('canonical_key = ?');
+            params.push(options.canonicalKey.trim().toLowerCase());
+        }
+        if (options.entityId) {
+            conditions.push('entity_id = ?');
+            params.push(options.entityId);
+        }
+        if (options.startTime !== undefined) {
+            conditions.push('occurred_at >= ?');
+            params.push(options.startTime);
+        }
+        if (options.endTime !== undefined) {
+            conditions.push('occurred_at < ?');
+            params.push(options.endTime);
+        }
+        if (options.entryTypes?.length) {
+            conditions.push(`entry_type IN (${options.entryTypes.map(() => '?').join(', ')})`);
+            params.push(...options.entryTypes);
+        }
+        const limit = Math.max(1, Math.min(500, options.limit ?? 100));
+        const rows = this.db.prepare(`
+      SELECT * FROM memory_timeline_entries
+      ${conditions.length ? `WHERE ${conditions.join(' AND ')}` : ''}
+      ORDER BY occurred_at DESC, created_at DESC
+      LIMIT ?
+    `).all(...params, limit);
+        return rows.map((row) => this.mapTimelineRow(row));
+    }
+    getBeliefAt(projectId, canonicalKey, atTime) {
+        const row = this.db.prepare(`
+      SELECT * FROM belief_graph_nodes
+      WHERE canonical_key = ?
+        AND ((? IS NULL AND project_id IS NULL) OR project_id = ?)
+        AND valid_from <= ? AND (valid_to IS NULL OR valid_to > ?)
+        AND status != 'rejected' AND status != 'possible_conflict'
+      ORDER BY valid_from DESC LIMIT 1
+    `).get(canonicalKey.trim().toLowerCase(), projectId ?? null, projectId ?? null, atTime, atTime);
+        return row ? this.mapBeliefRow(row) : null;
+    }
+    getBeliefHistory(projectId, canonicalKey) {
+        const rows = this.db.prepare(`
+      SELECT * FROM belief_graph_nodes
+      WHERE canonical_key = ? AND ((? IS NULL AND project_id IS NULL) OR project_id = ?)
+        AND status != 'rejected' AND status != 'possible_conflict'
+      ORDER BY valid_from ASC, created_at ASC
+    `).all(canonicalKey.trim().toLowerCase(), projectId ?? null, projectId ?? null);
+        return rows.map((row) => this.mapBeliefRow(row));
+    }
+    mapTimelineRow(row) {
+        return {
+            entryId: String(row.entry_id),
+            projectId: row.project_id == null ? undefined : String(row.project_id),
+            entryType: row.entry_type,
+            canonicalKey: row.canonical_key == null ? undefined : String(row.canonical_key),
+            entityId: row.entity_id == null ? undefined : String(row.entity_id),
+            beliefId: row.belief_id == null ? undefined : String(row.belief_id),
+            title: String(row.title),
+            summary: row.summary == null ? undefined : String(row.summary),
+            reason: row.reason == null ? undefined : String(row.reason),
+            occurredAt: Number(row.occurred_at),
+            evidenceEventIds: JSON.parse(String(row.evidence_event_ids_json)),
+            createdAt: Number(row.created_at),
+        };
+    }
+    mapBeliefRow(row) {
+        return {
+            beliefId: String(row.belief_id),
+            projectId: row.project_id == null ? undefined : String(row.project_id),
+            canonicalKey: String(row.canonical_key),
+            statement: String(row.statement),
+            status: String(row.status),
+            version: Number(row.version),
+            validFrom: Number(row.valid_from),
+            validTo: row.valid_to == null ? undefined : Number(row.valid_to),
+            supersedesBeliefId: row.supersedes_belief_id == null ? undefined : String(row.supersedes_belief_id),
+            supersededByBeliefId: row.superseded_by_belief_id == null ? undefined : String(row.superseded_by_belief_id),
+        };
+    }
+    initializeSchema() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS memory_timeline_entries (
+        entry_id TEXT PRIMARY KEY, project_id TEXT, entry_type TEXT NOT NULL, canonical_key TEXT,
+        entity_id TEXT, belief_id TEXT, title TEXT NOT NULL, summary TEXT, reason TEXT,
+        occurred_at INTEGER NOT NULL, evidence_event_ids_json TEXT NOT NULL, created_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_memory_timeline_project_time
+        ON memory_timeline_entries(project_id, occurred_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_memory_timeline_canonical_time
+        ON memory_timeline_entries(project_id, canonical_key, occurred_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_memory_timeline_entity_time
+        ON memory_timeline_entries(project_id, entity_id, occurred_at DESC);
+    `);
+    }
+}

package/dist/temporal/index.d.ts

@@ -0,0 +1,2 @@
+export * from './TemporalMemoryService.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/temporal/index.js

@@ -0,0 +1 @@
+export * from './TemporalMemoryService.js';

package/dist/topic/TopicAliasRegistry.d.ts

@@ -0,0 +1,21 @@
+import type Database from 'bun:sqlite';
+import type { TopicAliasRecord, TopicCreatedBy } from './TopicTypes.js';
+export declare class TopicAliasRegistry {
+    private readonly db;
+    constructor(db: Database);
+    add(input: {
+        projectId: string;
+        topicId: string;
+        alias: string;
+        createdBy: TopicCreatedBy;
+        confidence: number;
+        evidenceEventIds?: string[];
+        now?: number;
+    }): TopicAliasRecord;
+    resolve(projectId: string, alias: string): TopicAliasRecord | undefined;
+    matchText(projectId: string, text: string, limit?: number): TopicAliasRecord[];
+    archive(aliasId: string, projectId: string, now?: number): void;
+    get(aliasId: string): TopicAliasRecord | undefined;
+}
+export declare function normalizeTopicAlias(value: string): string;
+//# sourceMappingURL=TopicAliasRegistry.d.ts.map

package/dist/topic/TopicAliasRegistry.js

@@ -0,0 +1,67 @@
+import { randomUUID } from 'node:crypto';
+export class TopicAliasRegistry {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    add(input) {
+        const topic = this.db.prepare(`SELECT project_id FROM topic_nodes WHERE topic_id = ?`).get(input.topicId);
+        if (!topic)
+            throw new Error(`topic_not_found:${input.topicId}`);
+        if (topic.project_id !== input.projectId)
+            throw new Error(`topic_project_mismatch:${input.topicId}`);
+        const alias = input.alias.normalize('NFKC').trim();
+        const normalizedAlias = normalizeTopicAlias(alias);
+        if (!normalizedAlias)
+            throw new Error('topic_alias_required');
+        const collisions = this.db.prepare(`
+      SELECT DISTINCT topic_id FROM topic_aliases
+      WHERE project_id = ? AND normalized_alias = ? AND status IN ('active', 'needs_review') AND topic_id != ?
+    `).all(input.projectId, normalizedAlias, input.topicId);
+        const status = collisions.length
+            ? 'needs_review'
+            : input.createdBy === 'model_candidate' ? 'candidate' : 'active';
+        const aliasId = `topic-alias-${randomUUID()}`;
+        const now = input.now ?? Date.now();
+        this.db.prepare(`
+      INSERT INTO topic_aliases (alias_id, project_id, normalized_alias, alias, topic_id, status,
+        created_by, confidence, evidence_event_ids_json, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(aliasId, input.projectId, normalizedAlias, alias, input.topicId, status, input.createdBy, Math.max(0, Math.min(1, input.confidence)), JSON.stringify(input.evidenceEventIds || []), now, now);
+        return this.get(aliasId);
+    }
+    resolve(projectId, alias) {
+        const rows = this.db.prepare(`
+      SELECT * FROM topic_aliases WHERE project_id = ? AND normalized_alias = ? AND status IN ('active', 'needs_review')
+      ORDER BY CASE status WHEN 'active' THEN 0 ELSE 1 END, confidence DESC
+    `).all(projectId, normalizeTopicAlias(alias));
+        if (new Set(rows.map((row) => row.topic_id)).size !== 1 || rows.some((row) => row.status === 'needs_review'))
+            return undefined;
+        return rows[0] ? mapAlias(rows[0]) : undefined;
+    }
+    matchText(projectId, text, limit = 10) {
+        const normalized = normalizeTopicAlias(text);
+        if (!normalized)
+            return [];
+        const rows = this.db.prepare(`
+      SELECT * FROM topic_aliases WHERE project_id = ? AND status = 'active' ORDER BY LENGTH(normalized_alias) DESC
+    `).all(projectId);
+        return rows.filter((row) => row.normalized_alias.length >= 2 && normalized.includes(row.normalized_alias)).slice(0, limit).map(mapAlias);
+    }
+    archive(aliasId, projectId, now = Date.now()) {
+        this.db.prepare(`UPDATE topic_aliases SET status = 'archived', updated_at = ? WHERE alias_id = ? AND project_id = ?`)
+            .run(now, aliasId, projectId);
+    }
+    get(aliasId) {
+        const row = this.db.prepare(`SELECT * FROM topic_aliases WHERE alias_id = ?`).get(aliasId);
+        return row ? mapAlias(row) : undefined;
+    }
+}
+export function normalizeTopicAlias(value) {
+    return String(value || '').normalize('NFKC').trim().toLocaleLowerCase().replace(/[_-]+/g, ' ').replace(/\s+/g, ' ');
+}
+function mapAlias(row) {
+    return { aliasId: row.alias_id, projectId: row.project_id, topicId: row.topic_id, alias: row.alias,
+        normalizedAlias: row.normalized_alias, status: row.status, createdBy: row.created_by, confidence: row.confidence,
+        evidenceEventIds: JSON.parse(row.evidence_event_ids_json), createdAt: row.created_at, updatedAt: row.updated_at };
+}

package/dist/topic/TopicGovernance.d.ts

@@ -0,0 +1,21 @@
+import type Database from 'bun:sqlite';
+import type { TopicAliasRegistry } from './TopicAliasRegistry.js';
+import type { TopicPathRegistry } from './TopicPathRegistry.js';
+import type { TopicRelationGraph } from './TopicRelationGraph.js';
+import type { TopicOperationInput, TopicOperationRecord } from './TopicTypes.js';
+export declare class TopicGovernance {
+    private readonly db;
+    private readonly paths;
+    private readonly aliases;
+    private readonly relations;
+    constructor(db: Database, paths: TopicPathRegistry, aliases: TopicAliasRegistry, relations: TopicRelationGraph);
+    apply(input: TopicOperationInput): TopicOperationRecord;
+    rollback(operationId: string, projectId: string, now?: number): TopicOperationRecord;
+    listOperations(input: {
+        projectId: string;
+        limit?: number;
+    }): TopicOperationRecord[];
+    getOperation(operationId: string): TopicOperationRecord | undefined;
+    private deleteTopicGraph;
+}
+//# sourceMappingURL=TopicGovernance.d.ts.map

package/dist/topic/TopicGovernance.js

@@ -0,0 +1,173 @@
+import { randomUUID } from 'node:crypto';
+import { isMemoryOntologyClass } from '../ontology/MemoryOntology.js';
+const OPERATIONS = new Set([
+    'USER_DEFINED_TOPIC_CREATE', 'USER_DEFINED_TOPIC_RENAME', 'USER_DEFINED_TOPIC_ALIAS', 'USER_DEFINED_TOPIC_MOVE',
+    'USER_DEFINED_TOPIC_MERGE', 'USER_DEFINED_TOPIC_SPLIT', 'USER_DEFINED_TOPIC_REASSIGN',
+    'USER_DEFINED_TOPIC_RELATION_ADD', 'USER_DEFINED_TOPIC_RELATION_REMOVE', 'MODEL_PROPOSED_TOPIC',
+    'MODEL_PROPOSED_TOPIC_ALIAS', 'MODEL_PROPOSED_TOPIC_RELATION', 'SYSTEM_REPAIR_TOPIC',
+]);
+export class TopicGovernance {
+    db;
+    paths;
+    aliases;
+    relations;
+    constructor(db, paths, aliases, relations) {
+        this.db = db;
+        this.paths = paths;
+        this.aliases = aliases;
+        this.relations = relations;
+    }
+    apply(input) {
+        if (!OPERATIONS.has(input.operationType))
+            throw new Error(`invalid_topic_operation:${input.operationType}`);
+        const now = input.now ?? Date.now();
+        const operationId = `topic-operation-${randomUUID()}`;
+        let targetTopicId = input.targetTopicId;
+        let before;
+        let after;
+        let status = 'applied';
+        this.db.transaction(() => {
+            if (input.operationType === 'USER_DEFINED_TOPIC_CREATE' || input.operationType === 'MODEL_PROPOSED_TOPIC') {
+                const ontologyClass = input.payload.ontologyClass ?? 'Topic';
+                if (!isMemoryOntologyClass(ontologyClass))
+                    throw new Error(`invalid_ontology_class:${String(ontologyClass)}`);
+                const created = this.paths.create({
+                    projectId: input.projectId, topicPath: required(input.payload.topicPath, 'topicPath'),
+                    canonicalName: required(input.payload.canonicalName, 'canonicalName'), ontologyClass,
+                    parentTopicId: optional(input.payload.parentTopicId), createdBy: input.actor,
+                    evidenceEventIds: input.evidenceEventIds, now,
+                });
+                targetTopicId = created.topicId;
+                this.aliases.add({
+                    projectId: input.projectId, topicId: created.topicId, alias: created.canonicalName,
+                    createdBy: input.actor, confidence: input.actor === 'user_explicit' ? 1 : 0.6,
+                    evidenceEventIds: input.evidenceEventIds, now,
+                });
+                after = created;
+            }
+            else {
+                if (!targetTopicId)
+                    throw new Error('target_topic_required');
+                before = this.paths.assertProject(targetTopicId, input.projectId);
+                if (input.operationType === 'USER_DEFINED_TOPIC_RENAME') {
+                    after = this.paths.update(targetTopicId, input.projectId, { canonicalName: required(input.payload.canonicalName, 'canonicalName'), now });
+                }
+                else if (input.operationType === 'USER_DEFINED_TOPIC_MOVE' || input.operationType === 'USER_DEFINED_TOPIC_REASSIGN') {
+                    after = this.paths.update(targetTopicId, input.projectId, {
+                        topicPath: optional(input.payload.topicPath), parentTopicId: optional(input.payload.parentTopicId) ?? null, now,
+                    });
+                }
+                else if (input.operationType === 'USER_DEFINED_TOPIC_ALIAS' || input.operationType === 'MODEL_PROPOSED_TOPIC_ALIAS') {
+                    after = this.aliases.add({ projectId: input.projectId, topicId: targetTopicId,
+                        alias: required(input.payload.alias, 'alias'), createdBy: input.actor,
+                        confidence: input.actor === 'user_explicit' ? 1 : 0.6, evidenceEventIds: input.evidenceEventIds, now });
+                    status = after.status === 'needs_review' ? 'needs_review' : 'applied';
+                }
+                else if (input.operationType === 'USER_DEFINED_TOPIC_MERGE') {
+                    const destinationId = required(input.payload.destinationTopicId, 'destinationTopicId');
+                    this.paths.assertProject(destinationId, input.projectId);
+                    after = this.paths.update(targetTopicId, input.projectId, { status: 'merged', mergeCandidates: [destinationId], now });
+                }
+                else if (input.operationType === 'USER_DEFINED_TOPIC_SPLIT') {
+                    const created = this.paths.create({ projectId: input.projectId,
+                        topicPath: required(input.payload.topicPath, 'topicPath'), canonicalName: required(input.payload.canonicalName, 'canonicalName'),
+                        ontologyClass: 'Topic', parentTopicId: before ? before.parentTopicId : undefined,
+                        createdBy: input.actor, evidenceEventIds: input.evidenceEventIds, now });
+                    after = { source: before, splitTopic: created };
+                }
+                else if (input.operationType === 'USER_DEFINED_TOPIC_RELATION_ADD' || input.operationType === 'MODEL_PROPOSED_TOPIC_RELATION') {
+                    after = this.relations.add({ projectId: input.projectId, sourceTopicId: targetTopicId,
+                        relation: required(input.payload.relation, 'relation'), targetTopicId: required(input.payload.targetTopicId, 'targetTopicId'),
+                        createdBy: input.actor, evidenceEventIds: input.evidenceEventIds, now });
+                }
+                else if (input.operationType === 'USER_DEFINED_TOPIC_RELATION_REMOVE') {
+                    const relationId = required(input.payload.relationId, 'relationId');
+                    const relation = this.relations.get(relationId);
+                    if (!relation || relation.projectId !== input.projectId)
+                        throw new Error(`topic_relation_project_mismatch:${relationId}`);
+                    before = relation;
+                    this.relations.archive(relationId, input.projectId, now);
+                    after = { relationId: input.payload.relationId, status: 'archived' };
+                }
+                else {
+                    after = this.paths.update(targetTopicId, input.projectId, { status: 'needs_review', now });
+                    status = 'needs_review';
+                }
+            }
+            this.db.prepare(`
+        INSERT INTO topic_operations (operation_id, project_id, operation_type, actor, target_topic_id, payload_json,
+          before_json, after_json, inverse_operation_json, status, evidence_event_ids_json, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(operationId, input.projectId, input.operationType, input.actor, targetTopicId || null, JSON.stringify(input.payload), before === undefined ? null : JSON.stringify(before), after === undefined ? null : JSON.stringify(after), before === undefined ? null : JSON.stringify({ restoreTopic: before }), status, JSON.stringify(input.evidenceEventIds || []), now);
+        })();
+        return this.getOperation(operationId);
+    }
+    rollback(operationId, projectId, now = Date.now()) {
+        const operation = this.getOperation(operationId);
+        if (!operation)
+            throw new Error(`topic_operation_not_found:${operationId}`);
+        if (operation.projectId !== projectId)
+            throw new Error(`topic_operation_project_mismatch:${operationId}`);
+        if (operation.status === 'reverted')
+            return operation;
+        this.db.transaction(() => {
+            if (operation.operationType === 'USER_DEFINED_TOPIC_ALIAS' || operation.operationType === 'MODEL_PROPOSED_TOPIC_ALIAS') {
+                const aliasId = operation.after?.aliasId;
+                if (aliasId)
+                    this.aliases.archive(aliasId, projectId, now);
+            }
+            else if (operation.operationType === 'USER_DEFINED_TOPIC_RELATION_ADD' || operation.operationType === 'MODEL_PROPOSED_TOPIC_RELATION') {
+                const relationId = operation.after?.relationId;
+                if (relationId)
+                    this.relations.archive(relationId, projectId, now);
+            }
+            else if (operation.operationType === 'USER_DEFINED_TOPIC_RELATION_REMOVE') {
+                const relation = operation.before;
+                if (relation?.relationId && relation.status)
+                    this.relations.setStatus(relation.relationId, projectId, relation.status, now);
+            }
+            else if (operation.operationType === 'USER_DEFINED_TOPIC_SPLIT') {
+                const splitTopicId = operation.after?.splitTopic?.topicId;
+                if (splitTopicId)
+                    this.deleteTopicGraph(splitTopicId, projectId);
+            }
+            else if (operation.before && operation.targetTopicId) {
+                const before = operation.before;
+                this.paths.update(operation.targetTopicId, projectId, {
+                    canonicalName: before.canonicalName, topicPath: before.topicPath, parentTopicId: before.parentTopicId ?? null,
+                    status: before.status, mergeCandidates: before.mergeCandidates, now,
+                });
+            }
+            else if (operation.targetTopicId && (operation.operationType === 'USER_DEFINED_TOPIC_CREATE' || operation.operationType === 'MODEL_PROPOSED_TOPIC')) {
+                this.deleteTopicGraph(operation.targetTopicId, projectId);
+            }
+            this.db.prepare(`UPDATE topic_operations SET status = 'reverted', reverted_at = ? WHERE operation_id = ?`).run(now, operationId);
+        })();
+        return this.getOperation(operationId);
+    }
+    listOperations(input) {
+        return this.db.prepare(`SELECT * FROM topic_operations WHERE project_id = ? ORDER BY created_at LIMIT ?`)
+            .all(input.projectId, Math.max(1, Math.min(input.limit ?? 100, 1000))).map(mapOperation);
+    }
+    getOperation(operationId) {
+        const row = this.db.prepare(`SELECT * FROM topic_operations WHERE operation_id = ?`).get(operationId);
+        return row ? mapOperation(row) : undefined;
+    }
+    deleteTopicGraph(topicId, projectId) {
+        this.paths.assertProject(topicId, projectId);
+        this.db.prepare(`DELETE FROM topic_relations WHERE project_id = ? AND (source_topic_id = ? OR target_topic_id = ?)`)
+            .run(projectId, topicId, topicId);
+        this.db.prepare(`DELETE FROM topic_aliases WHERE project_id = ? AND topic_id = ?`).run(projectId, topicId);
+        this.paths.delete(topicId, projectId);
+    }
+}
+function mapOperation(row) {
+    return { operationId: row.operation_id, projectId: row.project_id, operationType: row.operation_type, actor: row.actor,
+        targetTopicId: row.target_topic_id || undefined, payload: JSON.parse(row.payload_json),
+        before: row.before_json ? JSON.parse(row.before_json) : undefined, after: row.after_json ? JSON.parse(row.after_json) : undefined,
+        status: row.status, evidenceEventIds: JSON.parse(row.evidence_event_ids_json), createdAt: row.created_at,
+        revertedAt: row.reverted_at ?? undefined };
+}
+function required(value, name) { if (typeof value !== 'string' || !value.trim())
+    throw new Error(`${name}_required`); return value.trim(); }
+function optional(value) { return typeof value === 'string' && value.trim() ? value.trim() : undefined; }

package/dist/topic/TopicPathRegistry.d.ts

@@ -0,0 +1,36 @@
+import type Database from 'bun:sqlite';
+import { type MemoryOntologyClass } from '../ontology/MemoryOntology.js';
+import type { TopicCreatedBy, TopicNode, TopicStatus } from './TopicTypes.js';
+export declare class TopicPathRegistry {
+    private readonly db;
+    constructor(db: Database);
+    create(input: {
+        projectId: string;
+        topicPath: string;
+        canonicalName: string;
+        parentTopicId?: string;
+        ontologyClass?: MemoryOntologyClass;
+        status?: TopicStatus;
+        createdBy: TopicCreatedBy;
+        confidence?: number;
+        evidenceEventIds?: string[];
+        evidenceEpisodeIds?: string[];
+        now?: number;
+    }): TopicNode;
+    get(topicId: string): TopicNode | undefined;
+    getByPath(projectId: string, topicPath: string): TopicNode | undefined;
+    list(projectId: string, statuses?: TopicStatus[]): TopicNode[];
+    update(topicId: string, projectId: string, patch: {
+        canonicalName?: string;
+        topicPath?: string;
+        parentTopicId?: string | null;
+        status?: TopicStatus;
+        mergeCandidates?: string[];
+        now?: number;
+    }): TopicNode;
+    delete(topicId: string, projectId: string): void;
+    assertProject(topicId: string, projectId: string): TopicNode;
+    private listAliases;
+}
+export declare function normalizeTopicPath(value: string): string;
+//# sourceMappingURL=TopicPathRegistry.d.ts.map

package/dist/topic/TopicPathRegistry.js

@@ -0,0 +1,105 @@
+import { randomUUID } from 'node:crypto';
+import { isMemoryOntologyClass } from '../ontology/MemoryOntology.js';
+export class TopicPathRegistry {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    create(input) {
+        const now = input.now ?? Date.now();
+        const topicPath = normalizeTopicPath(input.topicPath);
+        const ontologyClass = input.ontologyClass ?? 'Topic';
+        if (!input.projectId.trim())
+            throw new Error('topic_project_required');
+        if (!input.canonicalName.trim())
+            throw new Error('topic_name_required');
+        if (!isMemoryOntologyClass(ontologyClass))
+            throw new Error(`invalid_ontology_class:${ontologyClass}`);
+        if (input.parentTopicId)
+            this.assertProject(input.parentTopicId, input.projectId);
+        const topicId = `topic-${randomUUID()}`;
+        this.db.prepare(`
+      INSERT INTO topic_nodes (
+        topic_id, project_id, topic_path, canonical_name, parent_topic_id, ontology_class, status,
+        created_by, confidence, evidence_event_ids_json, evidence_episode_ids_json, last_used_at,
+        merge_candidates_json, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, '[]', ?, ?)
+    `).run(topicId, input.projectId, topicPath, input.canonicalName.trim(), input.parentTopicId || null, ontologyClass, input.status ?? (input.createdBy === 'model_candidate' ? 'candidate' : 'active'), input.createdBy, clamp(input.confidence ?? (input.createdBy === 'user_explicit' ? 1 : 0.6)), JSON.stringify(input.evidenceEventIds || []), JSON.stringify(input.evidenceEpisodeIds || []), now, now, now);
+        return this.get(topicId);
+    }
+    get(topicId) {
+        const row = this.db.prepare(`SELECT * FROM topic_nodes WHERE topic_id = ?`).get(topicId);
+        return row ? mapTopic(row, this.listAliases(row.project_id, row.topic_id)) : undefined;
+    }
+    getByPath(projectId, topicPath) {
+        const row = this.db.prepare(`SELECT * FROM topic_nodes WHERE project_id = ? AND topic_path = ?`)
+            .get(projectId, normalizeTopicPath(topicPath));
+        return row ? mapTopic(row, this.listAliases(row.project_id, row.topic_id)) : undefined;
+    }
+    list(projectId, statuses) {
+        const rows = statuses?.length
+            ? this.db.prepare(`SELECT * FROM topic_nodes WHERE project_id = ? AND status IN (${statuses.map(() => '?').join(',')}) ORDER BY topic_path`)
+                .all(projectId, ...statuses)
+            : this.db.prepare(`SELECT * FROM topic_nodes WHERE project_id = ? ORDER BY topic_path`).all(projectId);
+        return rows.map((row) => mapTopic(row, this.listAliases(projectId, row.topic_id)));
+    }
+    update(topicId, projectId, patch) {
+        const current = this.assertProject(topicId, projectId);
+        if (patch.parentTopicId)
+            this.assertProject(patch.parentTopicId, projectId);
+        const next = {
+            canonicalName: patch.canonicalName?.trim() || current.canonicalName,
+            topicPath: patch.topicPath ? normalizeTopicPath(patch.topicPath) : current.topicPath,
+            parentTopicId: patch.parentTopicId === undefined ? current.parentTopicId : patch.parentTopicId || undefined,
+            status: patch.status || current.status,
+            mergeCandidates: patch.mergeCandidates ?? current.mergeCandidates ?? [],
+        };
+        this.db.prepare(`
+      UPDATE topic_nodes SET canonical_name = ?, topic_path = ?, parent_topic_id = ?, status = ?,
+        merge_candidates_json = ?, updated_at = ? WHERE topic_id = ? AND project_id = ?
+    `).run(next.canonicalName, next.topicPath, next.parentTopicId || null, next.status, JSON.stringify(next.mergeCandidates), patch.now ?? Date.now(), topicId, projectId);
+        return this.get(topicId);
+    }
+    delete(topicId, projectId) {
+        this.assertProject(topicId, projectId);
+        this.db.prepare(`DELETE FROM topic_nodes WHERE topic_id = ? AND project_id = ?`).run(topicId, projectId);
+    }
+    assertProject(topicId, projectId) {
+        const topic = this.get(topicId);
+        if (!topic)
+            throw new Error(`topic_not_found:${topicId}`);
+        if (topic.projectId !== projectId)
+            throw new Error(`topic_project_mismatch:${topicId}`);
+        return topic;
+    }
+    listAliases(projectId, topicId) {
+        return this.db.prepare(`SELECT alias FROM topic_aliases WHERE project_id = ? AND topic_id = ? AND status = 'active' ORDER BY created_at`)
+            .all(projectId, topicId).map((row) => row.alias);
+    }
+}
+export function normalizeTopicPath(value) {
+    const path = String(value || '').normalize('NFKC').trim().toLowerCase()
+        .replace(/[^\p{L}\p{N}/_-]+/gu, '-').replace(/_+/g, '-').replace(/\/{2,}/g, '/')
+        .replace(/^[/\-]+|[/\-]+$/g, '');
+    if (!path)
+        throw new Error('topic_path_required');
+    if (path.split('/').some((segment) => !segment || segment === '.' || segment === '..'))
+        throw new Error('invalid_topic_path');
+    return path;
+}
+function mapTopic(row, aliases) {
+    return {
+        topicId: row.topic_id, projectId: row.project_id, topicPath: row.topic_path, canonicalName: row.canonical_name,
+        aliases, parentTopicId: row.parent_topic_id || undefined, ontologyClass: row.ontology_class, status: row.status,
+        createdBy: row.created_by, confidence: row.confidence, evidenceEventIds: parse(row.evidence_event_ids_json, []),
+        evidenceEpisodeIds: parse(row.evidence_episode_ids_json, []), lastUsedAt: row.last_used_at,
+        mergeCandidates: parse(row.merge_candidates_json, []), createdAt: row.created_at, updatedAt: row.updated_at,
+    };
+}
+function parse(value, fallback) { try {
+    return value ? JSON.parse(value) : fallback;
+}
+catch {
+    return fallback;
+} }
+function clamp(value) { return Math.max(0, Math.min(1, Number.isFinite(value) ? value : 0)); }

package/dist/topic/TopicRelationGraph.d.ts

@@ -0,0 +1,23 @@
+import type Database from 'bun:sqlite';
+import type { TopicCreatedBy, TopicRelationRecord } from './TopicTypes.js';
+export declare class TopicRelationGraph {
+    private readonly db;
+    constructor(db: Database);
+    add(input: {
+        projectId: string;
+        sourceTopicId: string;
+        relation: string;
+        targetTopicId: string;
+        createdBy: TopicCreatedBy;
+        confidence?: number;
+        evidenceEventIds?: string[];
+        evidenceEpisodeIds?: string[];
+        now?: number;
+    }): TopicRelationRecord;
+    get(relationId: string): TopicRelationRecord | undefined;
+    archive(relationId: string, projectId: string, now?: number): void;
+    setStatus(relationId: string, projectId: string, status: TopicRelationRecord['status'], now?: number): void;
+    list(projectId: string): TopicRelationRecord[];
+    private assertTopic;
+}
+//# sourceMappingURL=TopicRelationGraph.d.ts.map