@jungjaehoon/mama-core 2.4.1 → 4.0.0

package/dist/knowledge/commitments.js

@@ -0,0 +1,370 @@
+"use strict";
+/**
+ * Reading owner work back out of the commitment log.
+ *
+ * `appendJudgment` has written `commitments` and `commitment_assignments` since
+ * migration 075: a commitment row carries identity, the current revision and the
+ * head record, and one assignment row per revision carries the patch that
+ * revision applied. Nothing read them back. The only SELECT against either table
+ * was the writer's own CAS check, so the substrate could be written and never
+ * answered from - the shape this refactor exists to close.
+ *
+ * Current values are a fold, not a column. Each assignment states `set` and
+ * `clear` for that revision only, and the view is those applied in revision
+ * order. That is what keeps a correction from erasing what it corrected: the
+ * revision that changed a title is still readable next to the one that set it,
+ * and `history: 'all'` returns them.
+ *
+ * @module knowledge/commitments
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readWork = readWork;
+exports.createWork = createWork;
+exports.reviseWork = reviseWork;
+exports.withdrawWork = withdrawWork;
+const judgments_js_1 = require("./judgments.js");
+const work_dates_js_1 = require("./work-dates.js");
+const DEFAULT_LIMIT = 25;
+const MAX_LIMIT = 100;
+function parseLimit(value) {
+    if (value === undefined)
+        return DEFAULT_LIMIT;
+    if (!Number.isSafeInteger(value) || value < 1 || value > MAX_LIMIT) {
+        throw new judgments_js_1.JudgmentError('INVALID_COMMAND', `limit must be an integer from 1 to ${MAX_LIMIT}`);
+    }
+    return value;
+}
+function parseCursor(value) {
+    if (value === undefined)
+        return 0;
+    const afterTaskId = Number(value);
+    if (!Number.isSafeInteger(afterTaskId) || afterTaskId < 0) {
+        throw new judgments_js_1.JudgmentError('INVALID_COMMAND', 'cursor is not a commitment page cursor');
+    }
+    return afterTaskId;
+}
+function parseAsOf(value) {
+    if (value === undefined)
+        return null;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new judgments_js_1.JudgmentError('INVALID_COMMAND', 'asOf must be an epoch millisecond integer');
+    }
+    return value;
+}
+function parsePatch(json, field) {
+    const parsed = JSON.parse(json);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new judgments_js_1.JudgmentError('INVALID_COMMAND', `${field} is not a work patch object`);
+    }
+    return parsed;
+}
+function parseClear(json) {
+    const parsed = JSON.parse(json);
+    if (!Array.isArray(parsed)) {
+        throw new judgments_js_1.JudgmentError('INVALID_COMMAND', 'clear_json is not a field list');
+    }
+    return parsed;
+}
+function applyRevision(values, revision) {
+    for (const [field, value] of Object.entries(revision.set)) {
+        values[field] = value;
+    }
+    for (const field of revision.clear) {
+        delete values[field];
+    }
+}
+/**
+ * Fold the assignments into the values they leave behind.
+ *
+ * `clear` is applied after `set` within one revision: a revision that sets and
+ * clears the same field is stating that the field ends the revision absent,
+ * which is what the writer's own ordering already means.
+ */
+function foldAssignments(revisions) {
+    const values = {};
+    for (const revision of revisions) {
+        applyRevision(values, revision);
+    }
+    return values;
+}
+function stringField(values, field) {
+    const value = values[field];
+    return typeof value === 'string' ? value : null;
+}
+/** A revision's summary, only when its record is visible to the caller. */
+function readJudgmentSummary(adapter, recordId, admitted) {
+    if (!recordVisible(adapter, recordId, admitted))
+        return null;
+    const row = adapter.prepare('SELECT summary FROM decisions WHERE id = ?').get(recordId);
+    return row && typeof row.summary === 'string' ? row.summary : null;
+}
+function buildChain(adapter, revisions, admitted) {
+    const values = {};
+    return revisions.map((revision) => {
+        applyRevision(values, revision);
+        return {
+            revision: revision.revision,
+            operation: revision.operation,
+            eventDatetime: revision.eventDatetime,
+            status: revision.operation === 'withdraw' ? 'cancelled' : stringField(values, 'status'),
+            stage: stringField(values, 'stage'),
+            summary: readJudgmentSummary(adapter, revision.recordRef.id, admitted),
+        };
+    });
+}
+/**
+ * Whether the caller may read this commitment.
+ *
+ * A commitment carries no scope of its own; its head record does, through the
+ * same `memory_scope_bindings` every judgment read uses. An unbound record has
+ * no partition boundary to violate and stays readable, exactly as
+ * `referenceExists` decides it for a memory ref.
+ */
+function recordVisible(adapter, recordId, admitted) {
+    const row = adapter
+        .prepare('SELECT COUNT(*) AS bindings FROM memory_scope_bindings WHERE memory_id = ?')
+        .get(recordId);
+    if (!row)
+        return false;
+    if (row.bindings === 0)
+        return true;
+    if (admitted.length === 0)
+        return false;
+    const placeholders = admitted.map(() => '?').join(', ');
+    return (adapter
+        .prepare(`SELECT 1 FROM memory_scope_bindings
+          WHERE memory_id = ? AND scope_id IN (${placeholders}) LIMIT 1`)
+        .get(recordId, ...admitted) !== undefined);
+}
+/**
+ * Read owner work: one commitment, or a bounded page of them.
+ *
+ * `asOf` folds revisions by their source event time when recorded, or by the
+ * commit clock for judgments without an event time. A backfill committed today
+ * can therefore answer what was current at a historical instant. A commitment
+ * whose first revision is later than `asOf` is absent, not empty.
+ */
+function readWork(adapter, query, access) {
+    const admitted = (0, judgments_js_1.admittedScopeIds)(access);
+    const limit = parseLimit(query.limit);
+    const afterTaskId = parseCursor(query.cursor);
+    const asOf = parseAsOf(query.asOf);
+    const wantsHistory = query.history === 'all';
+    const wantsChain = query.history === 'chain';
+    if (query.history !== undefined &&
+        query.history !== 'all' &&
+        query.history !== 'current' &&
+        query.history !== 'chain') {
+        throw new judgments_js_1.JudgmentError('INVALID_COMMAND', "history must be 'current', 'chain', or 'all'");
+    }
+    if (query.commitmentId !== undefined && query.rowId !== undefined) {
+        throw new judgments_js_1.JudgmentError('INVALID_COMMAND', 'Ask by commitmentId or rowId, not both');
+    }
+    const reasons = [];
+    let rows;
+    let total = null;
+    if (query.commitmentId !== undefined) {
+        rows = adapter
+            .prepare('SELECT * FROM commitments WHERE commitment_id = ?')
+            .all(query.commitmentId);
+    }
+    else if (query.rowId !== undefined) {
+        rows = adapter
+            .prepare('SELECT * FROM commitments WHERE row_id = ?')
+            .all(query.rowId);
+    }
+    else {
+        // One extra row decides whether another page exists without a second count.
+        rows = adapter
+            .prepare('SELECT * FROM commitments WHERE row_id > ? ORDER BY row_id ASC LIMIT ?')
+            .all(afterTaskId, limit + 1);
+        total = adapter.prepare('SELECT COUNT(*) AS n FROM commitments').get().n;
+    }
+    const hasMore = query.commitmentId === undefined && query.rowId === undefined ? rows.length > limit : false;
+    const pageRows = hasMore ? rows.slice(0, limit) : rows;
+    const items = [];
+    let scopeHidden = 0;
+    for (const row of pageRows) {
+        if (!recordVisible(adapter, row.head_record_id, admitted)) {
+            scopeHidden += 1;
+            continue;
+        }
+        const assignments = adapter
+            .prepare(asOf === null
+            ? `SELECT assignment.*, judgment.event_datetime AS judgment_event_datetime
+             FROM commitment_assignments assignment
+             JOIN decisions judgment ON judgment.id = assignment.record_id
+             WHERE assignment.commitment_id = ? ORDER BY assignment.revision ASC`
+            : `SELECT assignment.*, judgment.event_datetime AS judgment_event_datetime FROM commitment_assignments assignment
+              JOIN decisions judgment ON judgment.id = assignment.record_id
+              WHERE assignment.commitment_id = ?
+                AND COALESCE(assignment.applies_from, judgment.event_datetime, assignment.created_at) <= ?
+              ORDER BY assignment.revision ASC`)
+            .all(...(asOf === null ? [row.commitment_id] : [row.commitment_id, asOf]));
+        if (assignments.length === 0) {
+            // Bounded away entirely: the commitment had not been created at `asOf`.
+            continue;
+        }
+        const revisions = assignments.map((assignment) => ({
+            revision: assignment.revision,
+            operation: assignment.operation,
+            recordRef: { kind: 'memory', id: assignment.record_id },
+            set: parsePatch(assignment.set_json, 'set_json'),
+            clear: parseClear(assignment.clear_json),
+            eventDatetime: assignment.applies_from ?? assignment.judgment_event_datetime ?? null,
+            createdAt: assignment.created_at,
+        }));
+        const head = revisions[revisions.length - 1];
+        items.push({
+            commitmentId: row.commitment_id,
+            rowId: row.row_id,
+            revision: head.revision,
+            latestJudgmentRef: head.recordRef,
+            values: foldAssignments(revisions),
+            withdrawn: revisions.some((revision) => revision.operation === 'withdraw'),
+            basis: revisions.map((revision) => revision.recordRef),
+            createdAt: row.created_at,
+            updatedAt: asOf === null ? row.updated_at : (head.eventDatetime ?? head.createdAt),
+            ...(wantsHistory ? { history: revisions } : {}),
+            ...(wantsChain ? { chain: buildChain(adapter, revisions, admitted) } : {}),
+        });
+    }
+    if (hasMore) {
+        reasons.push('more commitments follow this page');
+    }
+    if (scopeHidden > 0) {
+        // Named, never silent: a page short by rows the caller cannot read is a
+        // different answer from a page that is short because there is no more work.
+        reasons.push(`${scopeHidden} commitment(s) outside the caller's scopes`);
+    }
+    if (asOf !== null) {
+        reasons.push(`bounded to revisions effective at or before ${asOf}`);
+    }
+    return {
+        items,
+        nextCursor: hasMore ? String(pageRows[pageRows.length - 1].row_id) : null,
+        coverage: {
+            returned: items.length,
+            total,
+            complete: !hasMore && scopeHidden === 0,
+            reasons,
+        },
+    };
+}
+/**
+ * The record half of a work command, with absent fields omitted rather than set
+ * to `undefined`.
+ *
+ * The command payload is canonicalized and hashed into `command_bindings`, and
+ * the canonicalizer rejects an explicit `undefined` - correctly, since a key
+ * present with no value and a key absent are different payloads and must not
+ * hash alike.
+ */
+function recordFields(command) {
+    return {
+        commandId: command.commandId,
+        ...(command.modelRunId === undefined ? {} : { modelRunId: command.modelRunId }),
+        topic: command.topic,
+        summary: command.summary,
+        recordKind: 'commitment',
+        ...(command.reasoning === undefined ? {} : { reasoning: command.reasoning }),
+        ...(command.scopes === undefined ? {} : { scopes: command.scopes }),
+        ...(command.sourceRefs === undefined ? {} : { sourceRefs: command.sourceRefs }),
+        ...(command.links === undefined ? {} : { links: command.links }),
+        ...(command.eventDatetime === undefined ? {} : { eventDatetime: command.eventDatetime }),
+        ...(command.recordedAt === undefined ? {} : { recordedAt: command.recordedAt }),
+        ...(command.event === undefined ? {} : { event: command.event }),
+    };
+}
+function requireWorkReceipt(receipt) {
+    if (!receipt.work) {
+        // appendJudgment writes the commitment inside the same transaction as the
+        // record, so a receipt without one means the command was not a commitment.
+        throw new judgments_js_1.JudgmentError('INVALID_COMMAND', 'The judgment carried no commitment receipt');
+    }
+    return {
+        commitmentId: receipt.work.commitmentId,
+        revision: receipt.work.revision,
+        recordRef: { kind: 'memory', id: receipt.recordId },
+        receipt,
+    };
+}
+/**
+ * Commit new owner work.
+ *
+ * The work and the record that states it commit together: `appendJudgment` owns
+ * the transaction, and this is the vocabulary in front of it. A caller that
+ * wrote a task row here and a record there is the split this replaces.
+ */
+async function createWork(command, access, options) {
+    (0, work_dates_js_1.assertWorkPatchValues)(command.set);
+    const receipt = await (0, judgments_js_1.appendJudgment)({
+        ...recordFields(command),
+        work: {
+            operation: 'create',
+            set: command.set,
+            ...(command.imported === undefined ? {} : { imported: command.imported }),
+        },
+    }, access, options);
+    return requireWorkReceipt(receipt);
+}
+/**
+ * Revise owner work at an expected revision.
+ *
+ * The revision is the caller's claim about what it read. A concurrent write
+ * moves it and this fails loudly rather than overwriting what the caller never
+ * saw - the same compare-and-set the ledger it replaces performed.
+ */
+async function reviseWork(command, access, options) {
+    const statesNothing = command.set === undefined &&
+        (command.clear === undefined || command.clear.length === 0) &&
+        (command.links === undefined || command.links.length === 0);
+    if (statesNothing) {
+        throw new judgments_js_1.JudgmentError('INVALID_COMMAND', 'A revision must set, clear, or link at least one field');
+    }
+    if (command.set !== undefined) {
+        (0, work_dates_js_1.assertWorkPatchValues)(command.set);
+    }
+    // A revision is the caller's claim about what it read; a commitment it cannot
+    // see is one it cannot name. The read gate answers 'unavailable' rather than
+    // 'denied' so an outside-scope id probes the same silence as a wrong one.
+    if (readWork(options.adapter, { commitmentId: command.commitmentId }, access).items.length === 0) {
+        throw new judgments_js_1.JudgmentError('REFERENCE_NOT_FOUND', `Commitment is unavailable: ${command.commitmentId}`);
+    }
+    const receipt = await (0, judgments_js_1.appendJudgment)({
+        ...recordFields(command),
+        work: {
+            operation: 'revise',
+            commitmentId: command.commitmentId,
+            ...(command.expectedRevision === undefined
+                ? {}
+                : { expectedRevision: command.expectedRevision }),
+            ...(command.set === undefined ? {} : { set: command.set }),
+            ...(command.clear === undefined ? {} : { clear: command.clear }),
+        },
+    }, access, options);
+    return requireWorkReceipt(receipt);
+}
+/**
+ * Withdraw owner work.
+ *
+ * Withdrawal is a revision like any other: the values stay readable and the
+ * commitment is marked. Nothing is deleted, so a withdrawn commitment can still
+ * answer what it held and who withdrew it.
+ */
+async function withdrawWork(command, access, options) {
+    // Same gate as a revision: withdrawal is a claim about what the caller read.
+    if (readWork(options.adapter, { commitmentId: command.commitmentId }, access).items.length === 0) {
+        throw new judgments_js_1.JudgmentError('REFERENCE_NOT_FOUND', `Commitment is unavailable: ${command.commitmentId}`);
+    }
+    const receipt = await (0, judgments_js_1.appendJudgment)({
+        ...recordFields(command),
+        work: {
+            operation: 'withdraw',
+            commitmentId: command.commitmentId,
+            expectedRevision: command.expectedRevision,
+        },
+    }, access, options);
+    return requireWorkReceipt(receipt);
+}
+//# sourceMappingURL=commitments.js.map

package/dist/knowledge/decision-edges.d.ts

@@ -0,0 +1,70 @@
+import type { DatabaseAdapter } from '../db-manager.js';
+/**
+ * decision_edges + link_audit_log write boundary.
+ *
+ * Every mutation of the decision-edge graph goes through this module, so
+ * `decision_edges` and `link_audit_log` each have exactly one writing module
+ * inside `knowledge/` (the sibling judgments.ts owns the judgment-command
+ * edge insert). Each function performs the edge change and its audit row
+ * inside ONE adapter transaction - a link write and its audit row commit or
+ * fail together.
+ */
+type EdgeWriter = Pick<DatabaseAdapter, 'prepare' | 'transaction'>;
+export interface DecisionEdgeKey {
+    fromId: string;
+    toId: string;
+    relationship: string;
+}
+export interface DecisionEdgeRow extends DecisionEdgeKey {
+    reason: string | null;
+    createdBy: string | null;
+    approvedByUser: number | null;
+    decisionId: string | null;
+    evidence: string | null;
+    createdAt: number | null;
+}
+export interface ProposedDecisionEdge extends DecisionEdgeKey {
+    reason: string;
+    decisionId: string | null;
+    evidence: string | null;
+}
+export interface DecisionEdgeDeleteFailure {
+    link: string;
+    error: string;
+}
+/**
+ * Insert-or-replace one decision edge row with explicit governance columns.
+ * Used by the public createEdge API (createdBy 'llm', approvedByUser 1) and by
+ * the backup-restore path (columns replayed from the backup file).
+ */
+export declare function upsertDecisionEdge(adapter: EdgeWriter, edge: DecisionEdgeRow): void;
+/**
+ * Record a proposed edge pending user approval, plus its 'proposed' audit row.
+ */
+export declare function proposeDecisionEdge(adapter: EdgeWriter, edge: ProposedDecisionEdge): void;
+/**
+ * Approve a pending edge, plus its 'approved' audit row.
+ */
+export declare function approveDecisionEdge(adapter: EdgeWriter, key: DecisionEdgeKey): void;
+/**
+ * Reject a proposed edge: the 'rejected' audit row is written before the edge
+ * is deleted, in the same transaction.
+ */
+export declare function rejectDecisionEdge(adapter: EdgeWriter, key: DecisionEdgeKey, reason: string): void;
+/**
+ * Remove the auto-generated edge population (created_by='user' with no
+ * proposal context) and record one 'deprecated' audit row per removed link.
+ * `links` is the already-scanned target set; it only feeds the audit rows.
+ */
+export declare function deprecateAutoDecisionEdges(adapter: EdgeWriter, links: readonly DecisionEdgeKey[], reason: string): void;
+/**
+ * Delete one batch of edges, writing a 'deprecated' audit row for each. A
+ * per-link failure is collected and the batch continues, matching the cleanup
+ * tool's accounting; a failure of the batch itself throws to the caller.
+ */
+export declare function deleteDecisionEdgesWithAudit(adapter: EdgeWriter, links: readonly DecisionEdgeKey[], reason: string): {
+    deleted: number;
+    failures: DecisionEdgeDeleteFailure[];
+};
+export {};
+//# sourceMappingURL=decision-edges.d.ts.map

package/dist/knowledge/decision-edges.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.upsertDecisionEdge = upsertDecisionEdge;
+exports.proposeDecisionEdge = proposeDecisionEdge;
+exports.approveDecisionEdge = approveDecisionEdge;
+exports.rejectDecisionEdge = rejectDecisionEdge;
+exports.deprecateAutoDecisionEdges = deprecateAutoDecisionEdges;
+exports.deleteDecisionEdgesWithAudit = deleteDecisionEdgesWithAudit;
+/**
+ * Insert-or-replace one decision edge row with explicit governance columns.
+ * Used by the public createEdge API (createdBy 'llm', approvedByUser 1) and by
+ * the backup-restore path (columns replayed from the backup file).
+ */
+function upsertDecisionEdge(adapter, edge) {
+    adapter
+        .prepare(`INSERT OR REPLACE INTO decision_edges
+       (from_id, to_id, relationship, reason, created_by, approved_by_user, decision_id, evidence, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(edge.fromId, edge.toId, edge.relationship, edge.reason, edge.createdBy, edge.approvedByUser, edge.decisionId, edge.evidence, edge.createdAt);
+}
+/**
+ * Record a proposed edge pending user approval, plus its 'proposed' audit row.
+ */
+function proposeDecisionEdge(adapter, edge) {
+    adapter.transaction(() => {
+        adapter
+            .prepare(`INSERT INTO decision_edges
+         (from_id, to_id, relationship, reason, created_by, approved_by_user, decision_id, evidence, created_at)
+         VALUES (?, ?, ?, ?, 'llm', 0, ?, ?, ?)`)
+            .run(edge.fromId, edge.toId, edge.relationship, edge.reason, edge.decisionId, edge.evidence, Date.now());
+        adapter
+            .prepare(`INSERT INTO link_audit_log (from_id, to_id, relationship, action, actor, reason, created_at)
+         VALUES (?, ?, ?, 'proposed', 'llm', ?, ?)`)
+            .run(edge.fromId, edge.toId, edge.relationship, edge.reason, Date.now());
+    });
+}
+/**
+ * Approve a pending edge, plus its 'approved' audit row.
+ */
+function approveDecisionEdge(adapter, key) {
+    adapter.transaction(() => {
+        adapter
+            .prepare(`UPDATE decision_edges
+         SET approved_by_user = 1, approved_at = ?
+         WHERE from_id = ? AND to_id = ? AND relationship = ?`)
+            .run(Date.now(), key.fromId, key.toId, key.relationship);
+        adapter
+            .prepare(`INSERT INTO link_audit_log (from_id, to_id, relationship, action, actor, created_at)
+         VALUES (?, ?, ?, 'approved', 'user', ?)`)
+            .run(key.fromId, key.toId, key.relationship, Date.now());
+    });
+}
+/**
+ * Reject a proposed edge: the 'rejected' audit row is written before the edge
+ * is deleted, in the same transaction.
+ */
+function rejectDecisionEdge(adapter, key, reason) {
+    adapter.transaction(() => {
+        adapter
+            .prepare(`INSERT INTO link_audit_log (from_id, to_id, relationship, action, actor, reason, created_at)
+         VALUES (?, ?, ?, 'rejected', 'user', ?, ?)`)
+            .run(key.fromId, key.toId, key.relationship, reason, Date.now());
+        adapter
+            .prepare(`DELETE FROM decision_edges
+         WHERE from_id = ? AND to_id = ? AND relationship = ?`)
+            .run(key.fromId, key.toId, key.relationship);
+    });
+}
+/**
+ * Remove the auto-generated edge population (created_by='user' with no
+ * proposal context) and record one 'deprecated' audit row per removed link.
+ * `links` is the already-scanned target set; it only feeds the audit rows.
+ */
+function deprecateAutoDecisionEdges(adapter, links, reason) {
+    adapter.transaction(() => {
+        adapter
+            .prepare(`DELETE FROM decision_edges WHERE created_by = 'user' AND decision_id IS NULL`)
+            .run();
+        const auditStmt = adapter.prepare(`INSERT INTO link_audit_log (from_id, to_id, relationship, action, actor, reason, created_at)
+       VALUES (?, ?, ?, 'deprecated', 'system', ?, ?)`);
+        const timestamp = Date.now();
+        for (const link of links) {
+            auditStmt.run(link.fromId, link.toId, link.relationship, reason, timestamp);
+        }
+    });
+}
+/**
+ * Delete one batch of edges, writing a 'deprecated' audit row for each. A
+ * per-link failure is collected and the batch continues, matching the cleanup
+ * tool's accounting; a failure of the batch itself throws to the caller.
+ */
+function deleteDecisionEdgesWithAudit(adapter, links, reason) {
+    const deleteStmt = adapter.prepare(`DELETE FROM decision_edges
+     WHERE from_id = ? AND to_id = ? AND relationship = ?`);
+    const auditStmt = adapter.prepare(`INSERT INTO link_audit_log (from_id, to_id, relationship, action, actor, reason, created_at)
+     VALUES (?, ?, ?, 'deprecated', 'system', ?, ?)`);
+    let deleted = 0;
+    const failures = [];
+    const processLinks = () => {
+        for (const link of links) {
+            try {
+                deleteStmt.run(link.fromId, link.toId, link.relationship);
+                auditStmt.run(link.fromId, link.toId, link.relationship, reason, Date.now());
+                deleted++;
+            }
+            catch (error) {
+                failures.push({
+                    link: `${link.fromId}->${link.toId}`,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    };
+    // Use transaction if available, otherwise run directly
+    if (adapter.transaction) {
+        adapter.transaction(processLinks);
+    }
+    else {
+        processLinks();
+    }
+    return { deleted, failures };
+}
+//# sourceMappingURL=decision-edges.js.map