@jungjaehoon/mama-core 2.4.1 → 4.1.0

package/dist/registry/store.js

@@ -0,0 +1,395 @@
+"use strict";
+/**
+ * Registry store: work items, people and clients as nodes with the names they go by.
+ *
+ * Identity used to live in strings such as task titles and decision topics, so alternate
+ * spellings could not join without an explicit durable identity.
+ *
+ * A node here is cheap: an id, a kind, a display name, and the aliases it answers to.
+ * What it buys is that a record can point at identity instead of spelling it.
+ *
+ * Two decisions this module refuses to make on its own:
+ * - It never merges by similarity. `mergeNodes` happens because a caller decided, and the
+ *   reason is stored with it.
+ * - It never reassigns a contested alias. Claiming an alias another node holds raises, so
+ *   the caller resolves it (merge, or pick a different alias) rather than the store
+ *   silently moving identity from under existing records.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RegistryError = exports.REGISTRY_KINDS = void 0;
+exports.currentIdentityRevision = currentIdentityRevision;
+exports.rebuildRegistryProjections = rebuildRegistryProjections;
+exports.normalizeAlias = normalizeAlias;
+exports.createNode = createNode;
+exports.addAliases = addAliases;
+exports.upsertNode = upsertNode;
+exports.addAlias = addAlias;
+exports.resolveNodeById = resolveNodeById;
+exports.resolveAlias = resolveAlias;
+exports.resolveAliasCandidates = resolveAliasCandidates;
+exports.listNodes = listNodes;
+exports.mergeNodes = mergeNodes;
+exports.splitNode = splitNode;
+const node_crypto_1 = require("node:crypto");
+const types_js_1 = require("./types.js");
+Object.defineProperty(exports, "REGISTRY_KINDS", { enumerable: true, get: function () { return types_js_1.REGISTRY_KINDS; } });
+class RegistryError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'RegistryError';
+    }
+}
+exports.RegistryError = RegistryError;
+function currentIdentityRevision(adapter) {
+    const row = adapter
+        .prepare('SELECT revision FROM registry_identity_state WHERE singleton = 1')
+        .get();
+    if (!row || !Number.isSafeInteger(row.revision) || row.revision < 0) {
+        throw new Error('registry_identity_state is missing or malformed');
+    }
+    return row.revision;
+}
+function rebuildRegistryProjections(adapter) {
+    const revision = currentIdentityRevision(adapter);
+    const row = adapter
+        .prepare('SELECT MAX(committed_revision) AS revision FROM registry_corrections')
+        .get();
+    if ((row.revision ?? 0) !== revision) {
+        throw new Error('Registry correction projection revision is inconsistent');
+    }
+}
+/**
+ * The lookup key for an alias: case-folded, inner runs of whitespace collapsed, trimmed.
+ *
+ * Deliberately conservative - it folds the differences that are the same string typed
+ * twice, and nothing else. Hyphens, underscores and script differences stay significant,
+ * because "a-0001" and "a_0001" being the same thing is a judgement about the work, not
+ * about text, and belongs in an alias row someone added.
+ */
+function normalizeAlias(value) {
+    return value.trim().replace(/\s+/g, ' ').toLowerCase();
+}
+function toNode(row) {
+    return {
+        id: row.id,
+        kind: row.kind,
+        name: row.name,
+        parentId: row.parent_id,
+        mergedInto: row.merged_into,
+        note: row.note,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+function requireKind(kind) {
+    if (!types_js_1.REGISTRY_KINDS.includes(kind)) {
+        throw new RegistryError('invalid_kind', `Unknown registry kind: ${kind}`);
+    }
+    return kind;
+}
+function readNode(adapter, id) {
+    const row = adapter.prepare('SELECT * FROM registry_nodes WHERE id = ?').get(id);
+    return row ? toNode(row) : null;
+}
+function isNodeVisible(adapter, id, scopes) {
+    const bindings = adapter
+        .prepare('SELECT scope_kind AS kind, scope_id AS id FROM registry_scope_bindings WHERE node_id = ?')
+        .all(id);
+    if (bindings.length === 0) {
+        return true;
+    }
+    if (!scopes || scopes.length === 0) {
+        return false;
+    }
+    return scopes.some((scope) => bindings.some((binding) => binding.kind === scope.kind && binding.id === scope.id));
+}
+/**
+ * Follow `merged_into` to the node that now holds this identity.
+ *
+ * Bounded: a cycle written by a bad merge would otherwise hang every lookup, so the walk
+ * stops and reports rather than spinning.
+ */
+function followMerges(adapter, id) {
+    let current = readNode(adapter, id);
+    for (let hops = 0; current?.mergedInto && hops < 8; hops += 1) {
+        current = readNode(adapter, current.mergedInto);
+    }
+    if (current?.mergedInto) {
+        throw new RegistryError('merge_chain_too_long', `Merge chain from ${id} does not settle`);
+    }
+    return current;
+}
+/** Write one alias row, or raise when another node already answers to it. */
+function aliasScopes(scopes) {
+    return scopes && scopes.length > 0 ? scopes : [{ kind: 'global', id: '*' }];
+}
+function insertAlias(adapter, nodeId, kind, alias, now, scopes) {
+    const normalized = normalizeAlias(alias);
+    if (!normalized) {
+        throw new RegistryError('empty_alias', 'An alias must contain at least one character');
+    }
+    for (const scope of aliasScopes(scopes)) {
+        const existing = adapter
+            .prepare(`SELECT node_id FROM registry_aliases
+         WHERE kind = ? AND alias = ? AND scope_kind = ? AND scope_id = ?`)
+            .get(kind, normalized, scope.kind, scope.id);
+        if (existing) {
+            if (existing.node_id === nodeId) {
+                continue;
+            }
+            throw new RegistryError('alias_taken', `Alias "${alias}" is already registered in this scope.`);
+        }
+        adapter
+            .prepare(`INSERT INTO registry_aliases
+         (node_id, kind, alias, alias_display, scope_kind, scope_id, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`)
+            .run(nodeId, kind, normalized, alias.trim(), scope.kind, scope.id, now);
+    }
+}
+function createNode(adapter, input) {
+    const write = () => {
+        const kind = requireKind(input.kind);
+        const name = input.name.trim();
+        if (!name) {
+            throw new RegistryError('empty_name', 'A registry node needs a name');
+        }
+        const id = `reg_${(0, node_crypto_1.randomUUID)().replace(/-/g, '').slice(0, 20)}`;
+        const now = Date.now();
+        adapter
+            .prepare(`INSERT INTO registry_nodes (id, kind, name, parent_id, merged_into, merge_reason, note, created_at, updated_at)
+       VALUES (?, ?, ?, ?, NULL, NULL, ?, ?, ?)`)
+            .run(id, kind, name, input.parentId ?? null, input.note ?? null, now, now);
+        // The name is an alias too: asking for a node by the name it displays must work.
+        insertAlias(adapter, id, kind, name, now, input.scopes);
+        for (const alias of input.aliases ?? []) {
+            insertAlias(adapter, id, kind, alias, now, input.scopes);
+        }
+        for (const scope of input.scopes ?? []) {
+            if (!scope.id.trim()) {
+                throw new RegistryError('invalid_scope', 'Registry scope id must be nonblank');
+            }
+            adapter
+                .prepare(`INSERT INTO registry_scope_bindings (node_id, scope_kind, scope_id)
+           VALUES (?, ?, ?)`)
+                .run(id, scope.kind, scope.id);
+        }
+        return id;
+    };
+    return adapter.transaction(write);
+}
+function addAliases(adapter, nodeId, aliases, scopes) {
+    const write = () => {
+        if (scopes === undefined) {
+            for (const alias of aliases) {
+                addAlias(adapter, nodeId, alias);
+            }
+            return;
+        }
+        const node = readNode(adapter, nodeId);
+        if (!node || node.mergedInto) {
+            throw new RegistryError('unknown_node', 'Registry node unavailable');
+        }
+        for (const alias of aliases) {
+            insertAlias(adapter, nodeId, node.kind, alias, Date.now(), scopes);
+        }
+    };
+    adapter.transaction(write);
+}
+function upsertNode(adapter, input) {
+    const write = () => {
+        const existing = resolveAlias(adapter, input.name, input.kind, input.scopes);
+        if (existing) {
+            if (input.children && input.children.length > 0) {
+                throw new RegistryError('existing_children_unsupported', 'Adding children to an existing node requires an explicit correction.');
+            }
+            addAliases(adapter, existing.id, input.aliases ?? [], input.scopes);
+            return { id: existing.id, created: false, children: [] };
+        }
+        const id = createNode(adapter, input);
+        const children = input.children && input.children.length > 0
+            ? splitNode(adapter, {
+                parent: id,
+                children: input.children,
+                reason: input.note?.trim() || 'explicit parent declaration',
+            })
+            : [];
+        return { id, created: true, children };
+    };
+    return adapter.transaction(write);
+}
+function addAlias(adapter, nodeId, alias) {
+    const node = readNode(adapter, nodeId);
+    if (!node) {
+        throw new RegistryError('unknown_node', `No registry node ${nodeId}`);
+    }
+    if (node.mergedInto) {
+        throw new RegistryError('node_merged', `Node ${nodeId} was merged into ${node.mergedInto}; add the alias there`);
+    }
+    const scopes = adapter
+        .prepare('SELECT scope_kind AS kind, scope_id AS id FROM registry_scope_bindings WHERE node_id = ?')
+        .all(nodeId);
+    insertAlias(adapter, nodeId, node.kind, alias, Date.now(), scopes);
+}
+/** The live node behind an id, following merges. Null when the id is unknown. */
+function resolveNodeById(adapter, id) {
+    return followMerges(adapter, id);
+}
+/** The node an alias names, following merges. `kind` narrows when the same word is both. */
+function resolveAlias(adapter, alias, kind, scopes) {
+    const candidates = resolveAliasCandidates(adapter, alias, { kind, scopes });
+    if (candidates.length > 1) {
+        throw new RegistryError('alias_ambiguous', 'Alias resolves to multiple visible nodes.');
+    }
+    return candidates[0] ?? null;
+}
+function resolveAliasCandidates(adapter, alias, options) {
+    const normalized = normalizeAlias(alias);
+    if (!normalized) {
+        return [];
+    }
+    const admitted = options?.scopes && options.scopes.length > 0
+        ? options.scopes
+        : [{ kind: 'global', id: '*' }];
+    const whereKind = options?.kind ? 'kind = ? AND' : '';
+    const rows = adapter
+        .prepare(`SELECT node_id, alias_display FROM registry_aliases
+       WHERE ${whereKind} alias = ?
+         AND ((scope_kind = 'global' AND scope_id = '*')
+           OR (scope_kind || ':' || scope_id) IN (${admitted.map(() => '?').join(', ')}))
+       ORDER BY created_at, rowid`)
+        .all(...(options?.kind ? [requireKind(options.kind)] : []), normalized, ...admitted.map((scope) => `${scope.kind}:${scope.id}`));
+    const visible = rows
+        .map((row) => {
+        const node = followMerges(adapter, row.node_id);
+        if (!node || !isNodeVisible(adapter, node.id, admitted)) {
+            return null;
+        }
+        const canonicalVisible = adapter
+            .prepare(`SELECT 1 FROM registry_aliases
+           WHERE node_id = ? AND alias = ?
+             AND ((scope_kind = 'global' AND scope_id = '*')
+               OR (scope_kind || ':' || scope_id) IN (${admitted.map(() => '?').join(', ')}))
+           LIMIT 1`)
+            .get(node.id, normalizeAlias(node.name), ...admitted.map((scope) => `${scope.kind}:${scope.id}`));
+        return { ...node, name: canonicalVisible ? node.name : row.alias_display };
+    })
+        .filter((node) => node !== null);
+    const unique = [...new Map(visible.map((node) => [node.id, node])).values()];
+    return unique;
+}
+function listNodes(adapter, filter) {
+    const where = [];
+    const params = [];
+    if (filter?.kind) {
+        where.push('kind = ?');
+        params.push(requireKind(filter.kind));
+    }
+    if (filter?.parentId !== undefined) {
+        if (filter.parentId === null) {
+            where.push('parent_id IS NULL');
+        }
+        else {
+            where.push('parent_id = ?');
+            params.push(filter.parentId);
+        }
+    }
+    if (filter?.includeMerged !== true) {
+        where.push('merged_into IS NULL');
+    }
+    if (filter?.scopes && filter.scopes.length > 0) {
+        where.push(`(NOT EXISTS (SELECT 1 FROM registry_scope_bindings rs WHERE rs.node_id = registry_nodes.id)
+        OR EXISTS (
+          SELECT 1 FROM registry_scope_bindings rs
+           WHERE rs.node_id = registry_nodes.id
+             AND (rs.scope_kind || ':' || rs.scope_id) IN (${filter.scopes.map(() => '?').join(', ')})
+        ))`);
+        params.push(...filter.scopes.map((scope) => `${scope.kind}:${scope.id}`));
+    }
+    // rowid, not id: a split writes its children inside one millisecond, so `created_at`
+    // alone would order them by random uuid and report the parts in the wrong order.
+    const sql = `SELECT * FROM registry_nodes${where.length ? ` WHERE ${where.join(' AND ')}` : ''} ORDER BY created_at, rowid`;
+    return adapter.prepare(sql).all(...params).map(toNode);
+}
+/**
+ * Point one node's identity at another. The loser keeps its row as a tombstone so records
+ * that still reference it resolve forward instead of dangling.
+ */
+function mergeNodes(adapter, input) {
+    if (input.loser === input.survivor) {
+        throw new RegistryError('merge_self', 'A node cannot merge into itself');
+    }
+    const loser = readNode(adapter, input.loser);
+    const survivor = readNode(adapter, input.survivor);
+    if (!loser) {
+        throw new RegistryError('unknown_node', `No registry node ${input.loser}`);
+    }
+    if (loser.mergedInto) {
+        throw new RegistryError('loser_merged', `Node ${input.loser} was already merged`);
+    }
+    if (!survivor) {
+        throw new RegistryError('unknown_node', `No registry node ${input.survivor}`);
+    }
+    if (survivor.mergedInto) {
+        throw new RegistryError('survivor_merged', `Node ${input.survivor} was itself merged into ${survivor.mergedInto}`);
+    }
+    if (loser.kind !== survivor.kind) {
+        throw new RegistryError('kind_mismatch', `Cannot merge ${loser.kind} into ${survivor.kind}`);
+    }
+    const reason = input.reason.trim();
+    if (!reason) {
+        throw new RegistryError('missing_reason', 'A merge must record why');
+    }
+    const now = Date.now();
+    // Aliases move rather than duplicate: (kind, alias) is unique, and the loser's rows are
+    // exactly the spellings that must now reach the survivor.
+    adapter.transaction(() => {
+        adapter
+            .prepare(`INSERT OR IGNORE INTO registry_scope_bindings (node_id, scope_kind, scope_id)
+       SELECT ?, scope_kind, scope_id FROM registry_scope_bindings WHERE node_id = ?`)
+            .run(input.survivor, input.loser);
+        adapter
+            .prepare('UPDATE registry_aliases SET node_id = ? WHERE node_id = ?')
+            .run(input.survivor, input.loser);
+        adapter
+            .prepare('UPDATE registry_nodes SET merged_into = ?, merge_reason = ?, updated_at = ? WHERE id = ?')
+            .run(input.survivor, reason, now, input.loser);
+    });
+}
+/**
+ * Split one item into the children it really covers, keeping the parent as the umbrella.
+ *
+ * Nothing is deleted: the parent stays resolvable by its own aliases, and existing records
+ * keep pointing at it until someone decides which child they belong to.
+ */
+function splitNode(adapter, input) {
+    const write = () => {
+        const parent = readNode(adapter, input.parent);
+        if (!parent) {
+            throw new RegistryError('unknown_node', `No registry node ${input.parent}`);
+        }
+        if (parent.mergedInto) {
+            throw new RegistryError('node_merged', `Node ${input.parent} was merged away`);
+        }
+        if (input.children.length < 2) {
+            throw new RegistryError('split_too_small', 'A split needs at least two children');
+        }
+        if (!input.reason.trim()) {
+            throw new RegistryError('missing_reason', 'A split must record why');
+        }
+        const parentScopes = adapter
+            .prepare('SELECT scope_kind AS kind, scope_id AS id FROM registry_scope_bindings WHERE node_id = ?')
+            .all(parent.id);
+        return input.children.map((child) => createNode(adapter, {
+            kind: parent.kind,
+            name: child.name,
+            aliases: child.aliases,
+            parentId: parent.id,
+            note: input.reason.trim(),
+            scopes: parentScopes,
+        }));
+    };
+    return adapter.transaction(write);
+}
+//# sourceMappingURL=store.js.map

package/dist/registry/types.d.ts

@@ -0,0 +1,28 @@
+export declare const REGISTRY_KINDS: readonly ["item", "person", "client"];
+export type RegistryKind = (typeof REGISTRY_KINDS)[number];
+export interface RegistryNode {
+    id: string;
+    kind: RegistryKind;
+    name: string;
+    parentId: string | null;
+    mergedInto: string | null;
+    note: string | null;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface RecordActor {
+    personId: string;
+    role: string;
+}
+export interface RecordIdentity {
+    itemId: string | null;
+}
+export interface RegistryScopeRef {
+    /**
+     * The consumer's word for what kind of scope this is. The core matches it; it
+     * does not read it. Closed lists of kinds used to live here, in three copies.
+     */
+    kind: string;
+    id: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/registry/types.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REGISTRY_KINDS = void 0;
+exports.REGISTRY_KINDS = ['item', 'person', 'client'];
+//# sourceMappingURL=types.js.map

package/dist/relevance-scorer.js

@@ -14,7 +14,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.calculateRelevance = calculateRelevance;
 exports.selectTopDecisions = selectTopDecisions;
 exports.formatTopNContext = formatTopNContext;
-const embeddings_js_1 = require("./embeddings.js");
+const embedder_js_1 = require("./embedding/embedder.js");
 /**
  * Outcome weights for importance scoring
  */
@@ -70,7 +70,7 @@ function calculateRelevance(decision, queryContext) {
     let semanticScore = 0;
     if (decision.embedding && queryContext.embedding) {
         // Task 1.3: Use cosine similarity function
-        semanticScore = (0, embeddings_js_1.cosineSimilarity)(decision.embedding, queryContext.embedding);
+        semanticScore = (0, embedder_js_1.cosineSimilarity)(decision.embedding, queryContext.embedding);
     }
     else {
         // Fallback: no semantic match if embeddings missing

package/dist/runtime/agent-event-bus.d.ts

@@ -0,0 +1,50 @@
+export interface AgentNotice {
+    agent: string;
+    action: string;
+    target: string;
+    timestamp: number;
+}
+export type AgentEvent = {
+    type: 'memory:saved';
+    topic: string;
+    project?: string;
+} | {
+    type: 'extraction:completed';
+    projects: string[];
+} | {
+    type: 'memory:promoted';
+    saved: number;
+} | {
+    type: 'wiki:compiled';
+    pages: string[];
+} | {
+    type: 'dashboard:refresh';
+} | {
+    type: 'agent:action';
+    agent: string;
+    action: string;
+    target: string;
+};
+export type AgentEventType = AgentEvent['type'];
+type EventHandler = (event: AgentEvent) => void | Promise<void>;
+export declare class AgentEventBus {
+    static readonly MAX_NOTICES = 50;
+    private listeners;
+    private debounceTimers;
+    private listenerDebounceTimers;
+    private notices;
+    on(type: AgentEventType, handler: EventHandler): void;
+    off(type: AgentEventType, handler: EventHandler): void;
+    emit(event: AgentEvent): void;
+    emitDebounced(event: AgentEvent, delayMs: number): void;
+    /**
+     * Register a handler whose invocation is trailing-edge debounced: rapid
+     * successive events collapse into one call with the LAST event after
+     * delayMs of quiet. Pending invocations are cancelled by destroy().
+     */
+    onDebounced(type: AgentEventType, handler: EventHandler, delayMs: number): void;
+    getRecentNotices(limit: number): AgentNotice[];
+    destroy(): void;
+}
+export {};
+//# sourceMappingURL=agent-event-bus.d.ts.map

package/dist/runtime/agent-event-bus.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentEventBus = void 0;
+class AgentEventBus {
+    static MAX_NOTICES = 50;
+    listeners = new Map();
+    debounceTimers = new Map();
+    listenerDebounceTimers = new Set();
+    notices = [];
+    on(type, handler) {
+        if (!this.listeners.has(type)) {
+            this.listeners.set(type, new Set());
+        }
+        this.listeners.get(type).add(handler);
+    }
+    off(type, handler) {
+        this.listeners.get(type)?.delete(handler);
+    }
+    emit(event) {
+        const handlers = this.listeners.get(event.type);
+        if (handlers) {
+            for (const handler of handlers) {
+                try {
+                    const result = handler(event);
+                    if (result && typeof result.catch === 'function') {
+                        result.catch((err) => console.error(`[EventBus] Handler error for ${event.type}:`, err));
+                    }
+                }
+                catch (err) {
+                    console.error(`[EventBus] Sync handler error for ${event.type}:`, err);
+                }
+            }
+        }
+        if (event.type === 'agent:action') {
+            this.notices.unshift({
+                agent: event.agent,
+                action: event.action,
+                target: event.target,
+                timestamp: Date.now(),
+            });
+            if (this.notices.length > AgentEventBus.MAX_NOTICES) {
+                this.notices.length = AgentEventBus.MAX_NOTICES;
+            }
+        }
+    }
+    emitDebounced(event, delayMs) {
+        const existing = this.debounceTimers.get(event.type);
+        if (existing)
+            clearTimeout(existing);
+        this.debounceTimers.set(event.type, setTimeout(() => {
+            this.debounceTimers.delete(event.type);
+            this.emit(event);
+        }, delayMs));
+    }
+    /**
+     * Register a handler whose invocation is trailing-edge debounced: rapid
+     * successive events collapse into one call with the LAST event after
+     * delayMs of quiet. Pending invocations are cancelled by destroy().
+     */
+    onDebounced(type, handler, delayMs) {
+        let timer = null;
+        this.on(type, (event) => {
+            if (timer) {
+                clearTimeout(timer);
+                this.listenerDebounceTimers.delete(timer);
+            }
+            const scheduled = setTimeout(() => {
+                this.listenerDebounceTimers.delete(scheduled);
+                timer = null;
+                try {
+                    const result = handler(event);
+                    if (result && typeof result.catch === 'function') {
+                        result.catch((err) => console.error(`[EventBus] Debounced handler error for ${type}:`, err));
+                    }
+                }
+                catch (err) {
+                    console.error(`[EventBus] Debounced handler error for ${type}:`, err);
+                }
+            }, delayMs);
+            timer = scheduled;
+            this.listenerDebounceTimers.add(scheduled);
+        });
+    }
+    getRecentNotices(limit) {
+        return this.notices.slice(0, limit);
+    }
+    destroy() {
+        for (const timer of this.debounceTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.debounceTimers.clear();
+        for (const timer of this.listenerDebounceTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.listenerDebounceTimers.clear();
+        this.listeners.clear();
+        this.notices.length = 0;
+    }
+}
+exports.AgentEventBus = AgentEventBus;
+//# sourceMappingURL=agent-event-bus.js.map