@jungjaehoon/mama-core 2.4.1 → 4.1.0

package/dist/knowledge/commitments.d.ts

@@ -0,0 +1,192 @@
+/**
+ * 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
+ */
+import type { DatabaseAdapter } from '../db-manager.js';
+import type { JudgmentAccess, JudgmentKnowledgeOptions } from './judgments.js';
+import type { JudgmentEventMeta, JudgmentReceipt, OwnerWorkPatch, RecordLink, WorkReference } from '../memory/judgment-types.js';
+import type { MemoryScopeRef } from '../memory/types.js';
+/** One revision of a commitment, as the assignment row recorded it. */
+export interface CommitmentRevision {
+    revision: number;
+    operation: 'create' | 'revise' | 'withdraw';
+    recordRef: WorkReference;
+    set: OwnerWorkPatch;
+    clear: Array<keyof OwnerWorkPatch>;
+    /** Source event time; null means this legacy revision had no event time. */
+    eventDatetime: number | null;
+    createdAt: number;
+}
+/** The compact lifecycle entry returned for a progress-oriented chain read. */
+export interface CommitmentChainEntry {
+    revision: number;
+    operation: CommitmentRevision['operation'];
+    eventDatetime: number | null;
+    status: string | null;
+    stage: string | null;
+    summary: string | null;
+}
+export interface CommitmentView {
+    commitmentId: string;
+    rowId: number;
+    revision: number;
+    latestJudgmentRef: WorkReference;
+    /** The fold of every assignment up to `revision`. */
+    values: OwnerWorkPatch;
+    withdrawn: boolean;
+    /** The judgment record each surviving revision was written by, oldest first. */
+    basis: WorkReference[];
+    createdAt: number;
+    updatedAt: number;
+    /** Present only when the caller asked for `history: 'all'`. */
+    history?: CommitmentRevision[];
+    /** Present only when the caller asked for the internal `history: 'chain'`. */
+    chain?: CommitmentChainEntry[];
+}
+export interface CommitmentPage {
+    items: CommitmentView[];
+    nextCursor: string | null;
+    coverage: {
+        returned: number;
+        total: number | null;
+        complete: boolean;
+        /**
+         * Why the page is not the whole answer. Empty when it is. A caller that
+         * cannot tell a complete page from a truncated one will read the first page
+         * as the board, which is the failure this field exists to prevent.
+         */
+        reasons: string[];
+    };
+}
+export interface WorkRead {
+    commitmentId?: string;
+    rowId?: number;
+    /** Only revisions effective at or before this epoch millisecond are folded. */
+    asOf?: number;
+    history?: 'current' | 'chain' | 'all';
+    limit?: number;
+    cursor?: string;
+}
+/**
+ * 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.
+ */
+export declare function readWork(adapter: DatabaseAdapter, query: WorkRead, access: JudgmentAccess): CommitmentPage;
+/**
+ * What the caller states when it commits owner work.
+ *
+ * `commandId` is the caller's idempotency key and `summary` is what the record
+ * says; both are required because a commitment is a judgment first. Everything
+ * else about the work lives in the patch, which is the only vocabulary this
+ * module knows - no product's task shape reaches here.
+ */
+export interface WorkCommand {
+    commandId: string;
+    /** Native run that authored this work, when it was written during a model turn. */
+    modelRunId?: string | null;
+    /** What the caller is committing to, in its own words. */
+    summary: string;
+    reasoning?: string;
+    scopes?: MemoryScopeRef[];
+    /** Carried onto the record so a commitment names what caused it. */
+    sourceRefs?: string[];
+    /**
+     * Relations this command records as edges in the same transaction as the
+     * work. A commitment is a judgment first: a revision that only states how
+     * this work relates to other records is still a revision.
+     */
+    links?: RecordLink[];
+    eventDatetime?: number | null;
+    /**
+     * When this command happened, if the caller keeps its own clock. It stamps
+     * the record and the commitment row alike, so a board that filters on
+     * `updatedAt` reads the time the caller states rather than the wall clock.
+     */
+    recordedAt?: number;
+    /**
+     * Provenance carried onto the record's memory_events row. An importer names
+     * itself here so an imported row's history says who wrote it - not the agent
+     * that merely ran the migration.
+     */
+    event?: JudgmentEventMeta;
+}
+export interface CreateWorkCommand extends WorkCommand {
+    /** What this new commitment is about; becomes the record topic. */
+    topic: string;
+    set: OwnerWorkPatch;
+    /**
+     * Import vocabulary: the identity this work already had in a predecessor
+     * store. A migration that brings existing owner rows into the commitment log
+     * names their task id and revision so the log keeps the row's number and CAS
+     * history instead of minting a new identity. Absent for work first stated
+     * through this command log.
+     */
+    imported?: {
+        rowId: number;
+        revision?: number;
+        createdAt?: number;
+    };
+}
+export interface ReviseWorkCommand extends WorkCommand {
+    commitmentId: string;
+    /** The revision record's topic; the work item's topic when omitted. */
+    topic?: string;
+    expectedRevision?: number;
+    set?: OwnerWorkPatch;
+    clear?: Array<keyof OwnerWorkPatch>;
+}
+export interface WithdrawWorkCommand extends WorkCommand {
+    commitmentId: string;
+    /** The withdrawal record's topic; the work item's topic when omitted. */
+    topic?: string;
+    expectedRevision: number;
+}
+export interface WorkWriteResult {
+    commitmentId: string;
+    revision: number;
+    recordRef: WorkReference;
+    receipt: JudgmentReceipt;
+}
+/**
+ * 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.
+ */
+export declare function createWork(command: CreateWorkCommand, access: JudgmentAccess, options: JudgmentKnowledgeOptions): Promise<WorkWriteResult>;
+/**
+ * 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.
+ */
+export declare function reviseWork(command: ReviseWorkCommand, access: JudgmentAccess, options: JudgmentKnowledgeOptions): Promise<WorkWriteResult>;
+/**
+ * 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.
+ */
+export declare function withdrawWork(command: WithdrawWorkCommand, access: JudgmentAccess, options: JudgmentKnowledgeOptions): Promise<WorkWriteResult>;
+//# sourceMappingURL=commitments.d.ts.map

package/dist/knowledge/commitments.js

@@ -0,0 +1,386 @@
+"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 topic = command.topic ?? workTopic(options.adapter, command.commitmentId);
+    const receipt = await (0, judgments_js_1.appendJudgment)({
+        ...recordFields({ ...command, topic }),
+        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 topic = command.topic ?? workTopic(options.adapter, command.commitmentId);
+    const receipt = await (0, judgments_js_1.appendJudgment)({
+        ...recordFields({ ...command, topic }),
+        work: {
+            operation: 'withdraw',
+            commitmentId: command.commitmentId,
+            expectedRevision: command.expectedRevision,
+        },
+    }, access, options);
+    return requireWorkReceipt(receipt);
+}
+function workTopic(adapter, commitmentId) {
+    const row = adapter
+        .prepare(`SELECT decision.topic
+       FROM commitment_assignments AS assignment
+       JOIN decisions AS decision ON decision.id = assignment.record_id
+       WHERE assignment.commitment_id = ? AND assignment.operation = 'create'
+       ORDER BY assignment.revision
+       LIMIT 1`)
+        .get(commitmentId);
+    if (!row) {
+        throw new judgments_js_1.JudgmentError('REFERENCE_NOT_FOUND', `Commitment is unavailable: ${commitmentId}`);
+    }
+    return row.topic;
+}
+//# 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