@jungjaehoon/mama-core 4.1.0 → 5.0.0

package/dist/knowledge/index.d.ts

@@ -1,3 +1,4 @@
+import { type LinkCommand, type LinkReceipt, type StoredLink } from './links.js';
 import type { DatabaseInstance } from '../db-manager.js';
 import { type JudgmentAccess, type JudgmentKnowledgeOptions } from './judgments.js';
 import type { CommitmentPage, CreateWorkCommand, ReviseWorkCommand, WithdrawWorkCommand, WorkRead, WorkWriteResult } from './commitments.js';
@@ -7,7 +8,8 @@ export type { JudgmentAccess } from './judgments.js';
 export { judgmentRecordId } from './judgments.js';
 export type { IdentityCorrection, IdentityCorrectionReceipt, JudgmentAmendment, JudgmentCommand, JudgmentEventMeta, JudgmentProjections, JudgmentReceipt, JudgmentRecordFields, JsonValue, OwnerWorkPatch, RecordLink, WorkGraphPage, WorkGraphQuery, WorkReclassifyDisposition, WorkReference, } from '../memory/judgment-types.js';
 export { WORK_RECLASSIFY_DISPOSITIONS } from '../memory/judgment-types.js';
-export { JudgmentError, appendJudgment, insertTwinEdge, getTwinEdge, listTwinEdgesForRefs, mapTwinEdgeRow, } from './judgments.js';
+export { JudgmentError, appendJudgment, getTwinEdge, listTwinEdgesForRefs, mapTwinEdgeRow, } from './judgments.js';
+export { appendLink, findLink, linkEdgeId, type LinkCommand, type LinkReceipt, type StoredLink, } from './links.js';
 export { assertTwinRefsVisible, channelGrantClause, isChannelGranted, listVisibleTwinEdgesForRefs, visibleTwinRefKeys, visibleTwinRefKeysRecursive, TwinRefNotVisibleError, } from './access.js';
 export type { ChannelGrant, ChannelGrantClause } from './access.js';
 export { TWIN_EDGE_SOURCES, TWIN_EDGE_TYPES, TWIN_REF_KINDS, type InsertTwinEdgeInput, type ListVisibleTwinEdgesOptions, type TwinEdgeInsert, type TwinEdgeRecord, type TwinEdgeSource, type TwinEdgeSubjectRef, type TwinEdgeType, type TwinProjectRef, type TwinRef, type TwinRefKind, type TwinScopeRef, type TwinVisibility, } from './twin-edge-types.js';
@@ -18,9 +20,8 @@ export { createWork, readWork, reviseWork, withdrawWork } from './commitments.js
 export { parseExactDueAt, assertIsoDate, assertWorkPatchValues, WORK_PATCH_DEADLINE_PATTERN, WORK_PATCH_DUE_AT_PATTERN, type ParsedExactDueAt, } from './work-dates.js';
 export type { CommitmentPage, CommitmentChainEntry, CommitmentRevision, CommitmentView, CreateWorkCommand, ReviseWorkCommand, WithdrawWorkCommand, WorkRead, WorkWriteResult, } from './commitments.js';
 export { vectorSearch, fts5Search } from './search.js';
-export { queryDecisionGraph, querySemanticEdges, getGraphNeighborhood, getGraphPaths, getGraphTimeline, queryGraph, AgentGraphValidationError, type AgentGraphAdapter, type AgentGraphEdgeFilters, type AgentGraphResult, type AgentGraphCurrentProjection, type AgentGraphPath, type AgentGraphTimelineEvent, type AgentGraphTimelineMemoryEvent, type AgentGraphTimelineCaseEvent, type AgentGraphTimelineRawEvent, type AgentGraphTimelineEdgeEvent, type GraphNeighborhoodInput, type GraphPathsInput, type GraphPathsResult, type GraphTimelineInput, type GraphTimelineResult, } from './graph-query.js';
+export { queryDecisionGraph, querySemanticEdges, STATED_DECISION_EDGES, getGraphNeighborhood, getGraphPaths, getGraphTimeline, queryGraph, AgentGraphValidationError, type AgentGraphAdapter, type AgentGraphEdgeFilters, type AgentGraphResult, type AgentGraphCurrentProjection, type AgentGraphPath, type AgentGraphTimelineEvent, type AgentGraphTimelineMemoryEvent, type AgentGraphTimelineCaseEvent, type AgentGraphTimelineRawEvent, type AgentGraphTimelineEdgeEvent, type GraphNeighborhoodInput, type GraphPathsInput, type GraphPathsResult, type GraphTimelineInput, type GraphTimelineResult, } from './graph-query.js';
 export type { SourceIngestCommand, SourceIngestReceipt } from './source-ingest.js';
-export { upsertDecisionEdge, proposeDecisionEdge, approveDecisionEdge, rejectDecisionEdge, deprecateAutoDecisionEdges, deleteDecisionEdgesWithAudit, type DecisionEdgeKey, type DecisionEdgeRow, type DecisionEdgeDeleteFailure, } from './decision-edges.js';
 export interface KnowledgeOptions extends JudgmentKnowledgeOptions {
     adapter: DatabaseInstance;
 }
@@ -42,6 +43,13 @@ export interface Knowledge {
      * paths, timelines, and hydrated details — all under the caller's authority.
      */
     queryGraph(query: WorkGraphQuery, access: JudgmentAccess): WorkGraphPage;
+    /**
+     * Append one edge between existing records, with its reason; nothing is edited. A link to an
+     * edge contradicts it.
+     */
+    appendLink(command: LinkCommand, access: JudgmentAccess): LinkReceipt;
+    /** The link this principal already wrote under a command id, if any. */
+    findLink(commandId: string, access: JudgmentAccess): StoredLink | null;
 }
 export declare function createKnowledge(options: KnowledgeOptions): Knowledge;
 //# sourceMappingURL=index.d.ts.map

package/dist/knowledge/index.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.deprecateAutoDecisionEdges = exports.rejectDecisionEdge = exports.approveDecisionEdge = exports.proposeDecisionEdge = exports.upsertDecisionEdge = exports.AgentGraphValidationError = exports.queryGraph = exports.getGraphTimeline = exports.getGraphPaths = exports.getGraphNeighborhood = exports.querySemanticEdges = exports.queryDecisionGraph = exports.fts5Search = exports.vectorSearch = exports.WORK_PATCH_DUE_AT_PATTERN = exports.WORK_PATCH_DEADLINE_PATTERN = exports.assertWorkPatchValues = exports.assertIsoDate = exports.parseExactDueAt = exports.withdrawWork = exports.reviseWork = exports.readWork = exports.createWork = exports.isObservationVisibilityRowVisible = exports.isObservationVersionVisible = exports.readObservationVersion = exports.searchOwnerObservationVersions = exports.getObservationVersion = exports.appendObservationVersion = exports.observationVersionId = exports.correctIdentity = exports.ingestSource = exports.TWIN_REF_KINDS = exports.TWIN_EDGE_TYPES = exports.TWIN_EDGE_SOURCES = exports.TwinRefNotVisibleError = exports.visibleTwinRefKeysRecursive = exports.visibleTwinRefKeys = exports.listVisibleTwinEdgesForRefs = exports.isChannelGranted = exports.channelGrantClause = exports.assertTwinRefsVisible = exports.mapTwinEdgeRow = exports.listTwinEdgesForRefs = exports.getTwinEdge = exports.insertTwinEdge = exports.appendJudgment = exports.JudgmentError = exports.WORK_RECLASSIFY_DISPOSITIONS = exports.judgmentRecordId = void 0;
-exports.deleteDecisionEdgesWithAudit = void 0;
+exports.AgentGraphValidationError = exports.queryGraph = exports.getGraphTimeline = exports.getGraphPaths = exports.getGraphNeighborhood = exports.STATED_DECISION_EDGES = exports.querySemanticEdges = exports.queryDecisionGraph = exports.fts5Search = exports.vectorSearch = exports.WORK_PATCH_DUE_AT_PATTERN = exports.WORK_PATCH_DEADLINE_PATTERN = exports.assertWorkPatchValues = exports.assertIsoDate = exports.parseExactDueAt = exports.withdrawWork = exports.reviseWork = exports.readWork = exports.createWork = exports.isObservationVisibilityRowVisible = exports.isObservationVersionVisible = exports.readObservationVersion = exports.searchOwnerObservationVersions = exports.getObservationVersion = exports.appendObservationVersion = exports.observationVersionId = exports.correctIdentity = exports.ingestSource = exports.TWIN_REF_KINDS = exports.TWIN_EDGE_TYPES = exports.TWIN_EDGE_SOURCES = exports.TwinRefNotVisibleError = exports.visibleTwinRefKeysRecursive = exports.visibleTwinRefKeys = exports.listVisibleTwinEdgesForRefs = exports.isChannelGranted = exports.channelGrantClause = exports.assertTwinRefsVisible = exports.linkEdgeId = exports.findLink = exports.appendLink = exports.mapTwinEdgeRow = exports.listTwinEdgesForRefs = exports.getTwinEdge = exports.appendJudgment = exports.JudgmentError = exports.WORK_RECLASSIFY_DISPOSITIONS = exports.judgmentRecordId = void 0;
 exports.createKnowledge = createKnowledge;
+const links_js_1 = require("./links.js");
 const judgments_js_1 = require("./judgments.js");
 const source_ingest_js_1 = require("./source-ingest.js");
 const commitments_js_1 = require("./commitments.js");
@@ -15,10 +15,13 @@ Object.defineProperty(exports, "WORK_RECLASSIFY_DISPOSITIONS", { enumerable: tru
 var judgments_js_3 = require("./judgments.js");
 Object.defineProperty(exports, "JudgmentError", { enumerable: true, get: function () { return judgments_js_3.JudgmentError; } });
 Object.defineProperty(exports, "appendJudgment", { enumerable: true, get: function () { return judgments_js_3.appendJudgment; } });
-Object.defineProperty(exports, "insertTwinEdge", { enumerable: true, get: function () { return judgments_js_3.insertTwinEdge; } });
 Object.defineProperty(exports, "getTwinEdge", { enumerable: true, get: function () { return judgments_js_3.getTwinEdge; } });
 Object.defineProperty(exports, "listTwinEdgesForRefs", { enumerable: true, get: function () { return judgments_js_3.listTwinEdgesForRefs; } });
 Object.defineProperty(exports, "mapTwinEdgeRow", { enumerable: true, get: function () { return judgments_js_3.mapTwinEdgeRow; } });
+var links_js_2 = require("./links.js");
+Object.defineProperty(exports, "appendLink", { enumerable: true, get: function () { return links_js_2.appendLink; } });
+Object.defineProperty(exports, "findLink", { enumerable: true, get: function () { return links_js_2.findLink; } });
+Object.defineProperty(exports, "linkEdgeId", { enumerable: true, get: function () { return links_js_2.linkEdgeId; } });
 var access_js_1 = require("./access.js");
 Object.defineProperty(exports, "assertTwinRefsVisible", { enumerable: true, get: function () { return access_js_1.assertTwinRefsVisible; } });
 Object.defineProperty(exports, "channelGrantClause", { enumerable: true, get: function () { return access_js_1.channelGrantClause; } });
@@ -62,18 +65,12 @@ Object.defineProperty(exports, "fts5Search", { enumerable: true, get: function (
 var graph_query_js_2 = require("./graph-query.js");
 Object.defineProperty(exports, "queryDecisionGraph", { enumerable: true, get: function () { return graph_query_js_2.queryDecisionGraph; } });
 Object.defineProperty(exports, "querySemanticEdges", { enumerable: true, get: function () { return graph_query_js_2.querySemanticEdges; } });
+Object.defineProperty(exports, "STATED_DECISION_EDGES", { enumerable: true, get: function () { return graph_query_js_2.STATED_DECISION_EDGES; } });
 Object.defineProperty(exports, "getGraphNeighborhood", { enumerable: true, get: function () { return graph_query_js_2.getGraphNeighborhood; } });
 Object.defineProperty(exports, "getGraphPaths", { enumerable: true, get: function () { return graph_query_js_2.getGraphPaths; } });
 Object.defineProperty(exports, "getGraphTimeline", { enumerable: true, get: function () { return graph_query_js_2.getGraphTimeline; } });
 Object.defineProperty(exports, "queryGraph", { enumerable: true, get: function () { return graph_query_js_2.queryGraph; } });
 Object.defineProperty(exports, "AgentGraphValidationError", { enumerable: true, get: function () { return graph_query_js_2.AgentGraphValidationError; } });
-var decision_edges_js_1 = require("./decision-edges.js");
-Object.defineProperty(exports, "upsertDecisionEdge", { enumerable: true, get: function () { return decision_edges_js_1.upsertDecisionEdge; } });
-Object.defineProperty(exports, "proposeDecisionEdge", { enumerable: true, get: function () { return decision_edges_js_1.proposeDecisionEdge; } });
-Object.defineProperty(exports, "approveDecisionEdge", { enumerable: true, get: function () { return decision_edges_js_1.approveDecisionEdge; } });
-Object.defineProperty(exports, "rejectDecisionEdge", { enumerable: true, get: function () { return decision_edges_js_1.rejectDecisionEdge; } });
-Object.defineProperty(exports, "deprecateAutoDecisionEdges", { enumerable: true, get: function () { return decision_edges_js_1.deprecateAutoDecisionEdges; } });
-Object.defineProperty(exports, "deleteDecisionEdgesWithAudit", { enumerable: true, get: function () { return decision_edges_js_1.deleteDecisionEdgesWithAudit; } });
 function createKnowledge(options) {
     const writer = (0, judgments_js_1.createJudgmentWriter)(options);
     return {
@@ -85,6 +82,8 @@ function createKnowledge(options) {
         withdrawWork: (command, access) => (0, commitments_js_1.withdrawWork)(command, access, options),
         readWork: (query, access) => (0, commitments_js_1.readWork)(options.adapter, query, access),
         queryGraph: (query, access) => (0, graph_query_js_1.queryGraph)(options.adapter, query, access),
+        appendLink: (command, access) => (0, links_js_1.appendLink)(options.adapter, command, access),
+        findLink: (commandId, access) => (0, links_js_1.findLink)(options.adapter, commandId, access),
     };
 }
 //# sourceMappingURL=index.js.map

package/dist/knowledge/judgments.d.ts

@@ -1,6 +1,6 @@
 import type { DatabaseAdapter, DatabaseInstance } from '../db-manager.js';
 import { type TwinEdgeInsert, type TwinEdgeRecord, type TwinEdgeSource, type TwinEdgeType, type TwinProjectRef, type TwinRef } from './twin-edge-types.js';
-import type { JudgmentCommand, JudgmentReceipt } from '../memory/judgment-types.js';
+import type { JudgmentCommand, JudgmentReceipt, WorkReference } from '../memory/judgment-types.js';
 import type { MemoryScopeRef } from '../memory/types.js';
 export interface JudgmentAccess {
     principalId: string;
@@ -88,6 +88,8 @@ export declare function admittedScopeIds(access: JudgmentAccess): string[];
 export declare function boundScopeIdsFor(access: JudgmentAccess, command: {
     scopes?: MemoryScopeRef[];
 }): string[];
+/** Whether a link may name this target under the caller's admitted write scopes. */
+export declare function referenceExists(adapter: Pick<DatabaseAdapter, 'prepare'>, reference: WorkReference, admittedScopeIds: readonly string[]): boolean;
 export declare function appendJudgment(command: JudgmentCommand, access: JudgmentAccess, options: JudgmentKnowledgeOptions): Promise<JudgmentReceipt>;
 export declare function createJudgmentWriter(options: JudgmentKnowledgeOptions): {
     appendJudgment: (command: JudgmentCommand, access: JudgmentAccess) => Promise<JudgmentReceipt>;

package/dist/knowledge/judgments.js

@@ -7,6 +7,7 @@ exports.JudgmentError = void 0;
 exports.judgmentRecordId = judgmentRecordId;
 exports.admittedScopeIds = admittedScopeIds;
 exports.boundScopeIdsFor = boundScopeIdsFor;
+exports.referenceExists = referenceExists;
 exports.appendJudgment = appendJudgment;
 exports.createJudgmentWriter = createJudgmentWriter;
 exports.mapTwinEdgeRow = mapTwinEdgeRow;
@@ -130,6 +131,12 @@ const AMEND_FIELDS = [
 /** Public-save parity fields carried by the command are validated up front so a
  * malformed command fails before any write or embedder call. */
 function validateCommandFields(command) {
+    // A replacement is a stated act: without its own reason the supersedes link would carry the
+    // whole record's reasoning instead.
+    for (const replacement of command.replaces ?? []) {
+        requireText(replacement.id, 'replaces id');
+        requireText(replacement.reason, 'replaces reason');
+    }
     if (command.confidence !== undefined &&
         (!Number.isFinite(command.confidence) || command.confidence < 0 || command.confidence > 1)) {
         throw new JudgmentError('INVALID_COMMAND', 'confidence must be a number between 0 and 1');
@@ -163,14 +170,8 @@ function validateCommandFields(command) {
             throw new JudgmentError('INVALID_COMMAND', 'amends requires at least one projection field to set');
         }
     }
-    for (const edge of command.projections?.decisionEdges ?? []) {
-        if (edge.fromId !== undefined) {
-            requireText(edge.fromId, 'projection edge source');
-        }
-        requireText(edge.targetId, 'projection edge target');
-        requireText(edge.relationship, 'projection edge relationship');
-    }
 }
+/** Whether a link may name this target under the caller's admitted write scopes. */
 function referenceExists(adapter, reference, admittedScopeIds) {
     if (reference.kind === 'memory') {
         const row = adapter
@@ -207,7 +208,13 @@ function referenceExists(adapter, reference, admittedScopeIds) {
             .get(reference.id) !== undefined);
     }
     if (reference.kind === 'edge') {
-        return (adapter.prepare('SELECT 1 FROM twin_edges WHERE edge_id = ?').get(reference.id) !== undefined);
+        // A correction reads the link it corrects, so both of that link's ends must be reachable.
+        const edge = adapter
+            .prepare('SELECT subject_kind, subject_id, object_kind, object_id FROM twin_edges WHERE edge_id = ?')
+            .get(reference.id);
+        return (edge !== undefined &&
+            referenceExists(adapter, { kind: edge.subject_kind, id: edge.subject_id }, admittedScopeIds) &&
+            referenceExists(adapter, { kind: edge.object_kind, id: edge.object_id }, admittedScopeIds));
     }
     return false;
 }
@@ -255,6 +262,26 @@ const AMEND_COLUMN_MAP = {
     supersedes: 'supersedes',
     supersededBy: 'superseded_by',
 };
+/** The column values an amendment or a replacement is about to overwrite, per target. */
+function priorValuesFor(adapter, command) {
+    const read = (id, columns) => adapter.prepare(`SELECT ${columns.join(', ')} FROM decisions WHERE id = ?`).get(id);
+    const replaced = (command.replaces ?? []).map((replacement) => {
+        const prior = read(replacement.id, ['status', 'superseded_by']);
+        return {
+            target: replacement.id,
+            values: { status: prior?.status ?? null, supersededBy: prior?.superseded_by ?? null },
+        };
+    });
+    const amended = (command.amends ?? []).map((amendment) => {
+        const fields = AMEND_FIELDS.filter((field) => field in amendment);
+        const prior = read(amendment.target.id, fields.map((field) => AMEND_COLUMN_MAP[field]));
+        return {
+            target: amendment.target.id,
+            values: Object.fromEntries(fields.map((field) => [field, prior?.[AMEND_COLUMN_MAP[field]] ?? null])),
+        };
+    });
+    return [...replaced, ...amended];
+}
 function applyAmendment(adapter, amendment, now) {
     const sets = ['updated_at = ?'];
     const params = [now];
@@ -268,7 +295,7 @@ function applyAmendment(adapter, amendment, now) {
         .prepare(`UPDATE decisions SET ${sets.join(', ')} WHERE id = ?`)
         .run(...params, amendment.target.id);
 }
-function applyProjections(adapter, command, recordId, effectiveScopes, now) {
+function applyProjections(adapter, command, recordId, effectiveScopes) {
     const projections = command.projections;
     if (!projections)
         return;
@@ -280,17 +307,6 @@ function applyProjections(adapter, command, recordId, effectiveScopes, now) {
             scopes: effectiveScopes,
         });
     }
-    for (const targetId of projections.supersedeTargets ?? []) {
-        adapter
-            .prepare("UPDATE decisions SET superseded_by = ?, status = 'superseded', updated_at = ? WHERE id = ?")
-            .run(recordId, now, targetId);
-    }
-    const edgeInsert = adapter.prepare(`INSERT INTO decision_edges
-     (from_id, to_id, relationship, reason, weight, created_at, created_by, approved_by_user)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
-    for (const edge of projections.decisionEdges ?? []) {
-        edgeInsert.run(edge.fromId ?? recordId, edge.targetId, edge.relationship, edge.reason ?? null, edge.weight ?? 1, now, edge.createdBy ?? 'user', edge.approvedByUser ?? 1);
-    }
 }
 function parseReceipt(value) {
     let parsed;
@@ -339,7 +355,6 @@ function insertLink(adapter, command, recordId, link, index, access, now) {
         agent_id: Object.hasOwn(command, 'agentId') ? (command.agentId ?? undefined) : access.agentId,
         model_run_id: command.modelRunId ?? undefined,
         reason_text: typeof link.attrs?.reason === 'string' ? link.attrs.reason : (command.reasoning ?? undefined),
-        evidence_refs: command.replaces?.length ? command.replaces : undefined,
         content_hash: contentHash,
         created_at: now,
     });
@@ -405,6 +420,9 @@ async function appendJudgmentOnAdapter(adapter, command, access, embedder) {
             }
             return;
         }
+        // What the amendments and replacements will overwrite, kept in this record: the target
+        // columns are a projection, and the appended records are the history.
+        const replacedValues = priorValuesFor(adapter, command);
         const decisionRowId = (0, db_manager_js_1.insertPreparedDecision)(adapter, {
             id: recordId,
             topic: command.topic,
@@ -443,7 +461,9 @@ async function appendJudgmentOnAdapter(adapter, command, access, embedder) {
              kind = COALESCE(?, kind), status = COALESCE(?, status),
              summary = COALESCE(?, summary), is_static = COALESCE(?, is_static)
          WHERE id = ?`)
-            .run(command.recordKind, (0, canonicalize_js_1.canonicalizeJSON)(command.payload ?? {}), command.appliesFrom ?? null, command.appliesUntil ?? null, command.record?.kind ?? null, command.record?.status ?? null, 
+            .run(command.recordKind, (0, canonicalize_js_1.canonicalizeJSON)(replacedValues.length > 0
+            ? { ...(command.payload ?? {}), replacedValues }
+            : (command.payload ?? {})), command.appliesFrom ?? null, command.appliesUntil ?? null, command.record?.kind ?? null, command.record?.status ?? null, 
         // Never leave summary NULL: legacy readers (evolution candidates,
         // recall) assume it is text. The command summary is the authored
         // summary when the record does not carry a distinct one.
@@ -477,7 +497,7 @@ async function appendJudgmentOnAdapter(adapter, command, access, embedder) {
             }
             applyAmendment(adapter, amendment, domainNow);
         }
-        applyProjections(adapter, command, recordId, effectiveScopes, domainNow);
+        applyProjections(adapter, command, recordId, effectiveScopes);
         // A commitment's own clock is domain time, like the record's: `updated_at`
         // is what the board sorts and filters on, so a caller that states when a
         // revision happened must see that time on the row, not the wall clock the
@@ -547,9 +567,9 @@ async function appendJudgmentOnAdapter(adapter, command, access, embedder) {
              (commitment_id, revision, record_id, operation, set_json, clear_json, applies_from, applies_until, created_at, agent_id, model_run_id)
              VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
                     .run(work.commitmentId, revision, recordId, work.operation, (0, canonicalize_js_1.canonicalizeJSON)(workPatch(work)), (0, canonicalize_js_1.canonicalizeJSON)(work.clear ?? []), command.eventDatetime ?? null, command.appliesUntil ?? null, domainNow, access.agentId, command.modelRunId ?? null);
-                edgeIds.push(insertLink(adapter, command, recordId, { relation: 'builds_on', target: { kind: 'memory', id: current.head_record_id } }, command.links?.length ?? 0, 
-                // The host links a revision to the record it revises; the agent did not judge it.
-                { ...access, edgeSource: 'code' }, now));
+                // No host edge to the previous revision: the order lives in commitment_assignments, and
+                // how a revision relates to an earlier record is the agent's link to state (owner,
+                // 2026-09-30).
                 adapter
                     .prepare('UPDATE commitments SET current_revision = ?, head_record_id = ?, withdrawn = ?, updated_at = ?, agent_id = ?, model_run_id = ? WHERE commitment_id = ?')
                     .run(revision, recordId, work.operation === 'withdraw' ? 1 : 0, domainNow, access.agentId, command.modelRunId ?? null, work.commitmentId);

package/dist/knowledge/links.d.ts

@@ -0,0 +1,50 @@
+import type { DatabaseAdapter } from '../db-manager.js';
+import type { RecordLink } from '../memory/judgment-types.js';
+import type { JudgmentAccess } from './judgments.js';
+import type { TwinRef } from './twin-edge-types.js';
+/**
+ * One edge the agent appends between records that already exist, with the sentence of why.
+ *
+ * Nothing is edited: a link is a new row, and a wrong link is answered by a newer one that
+ * contradicts it. The row is its own receipt, so no record or revision is written for it.
+ */
+export interface LinkCommand {
+    commandId: string;
+    /** The record the statement is made from; for a work item, its head revision. */
+    from: {
+        kind: 'memory';
+        id: string;
+    };
+    /** An edge target is a correction and takes `contradicts`. */
+    to: TwinRef;
+    relation: RecordLink['relation'];
+    reason: string;
+    /** Observations or records the reason rests on. */
+    evidenceRefs?: TwinRef[];
+    /** Extra relation attributes, such as a person's role. */
+    attrs?: Record<string, unknown>;
+    agentId?: string | null;
+    modelRunId?: string | null;
+}
+export interface LinkReceipt {
+    edgeId: string;
+    createdAt: number;
+    /** True when the command id was already written with this same link. */
+    replayed: boolean;
+}
+/** A stored link, found by the command id that wrote it. */
+export interface StoredLink extends LinkReceipt {
+    from: TwinRef;
+    to: TwinRef;
+    relation: string;
+    reason: string | null;
+}
+/** A link's id is fixed by who asked and under which command id, so a retry finds its row. */
+export declare function linkEdgeId(principalId: string, commandId: string): string;
+/**
+ * The link a principal already wrote under this command id, if any: a retry finds it here, with
+ * what it states, so the caller can tell a retry from another link under the same id.
+ */
+export declare function findLink(adapter: Pick<DatabaseAdapter, 'prepare'>, commandId: string, access: JudgmentAccess): StoredLink | null;
+export declare function appendLink(adapter: Pick<DatabaseAdapter, 'prepare' | 'transaction' | 'transactionImmediate'>, command: LinkCommand, access: JudgmentAccess): LinkReceipt;
+//# sourceMappingURL=links.d.ts.map

package/dist/knowledge/links.js

@@ -0,0 +1,152 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.linkEdgeId = linkEdgeId;
+exports.findLink = findLink;
+exports.appendLink = appendLink;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const canonicalize_js_1 = require("../canonicalize.js");
+const judgments_js_1 = require("./judgments.js");
+const TARGET_KINDS = new Set(['memory', 'registry', 'observation', 'edge']);
+const EVIDENCE_KINDS = new Set(['memory', 'observation']);
+/**
+ * Relations a link states. Replacing (supersedes) and amending change the target's state, so they
+ * are acts written with a record (`replaces`, an amendment), and a source citation (derived_from)
+ * is written with the record that rests on it.
+ */
+const RELATIONS = new Set([
+    'refines',
+    'contradicts',
+    'mentions',
+    'builds_on',
+    'debates',
+    'synthesizes',
+    'blocks',
+    'next_action_for',
+]);
+function nonblank(value, field) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new judgments_js_1.JudgmentError('INVALID_COMMAND', `${field} must be nonblank`);
+    }
+    return value;
+}
+/** A link's id is fixed by who asked and under which command id, so a retry finds its row. */
+function linkEdgeId(principalId, commandId) {
+    return `link_${node_crypto_1.default
+        .createHash('sha256')
+        .update((0, canonicalize_js_1.canonicalizeJSON)({ principalId, commandId }))
+        .digest('hex')
+        .slice(0, 24)}`;
+}
+function linkContentHash(edgeId, command) {
+    return node_crypto_1.default
+        .createHash('sha256')
+        .update((0, canonicalize_js_1.canonicalizeJSON)({
+        edgeId,
+        from: command.from,
+        to: command.to,
+        relation: command.relation,
+        reason: command.reason,
+        evidenceRefs: command.evidenceRefs ?? [],
+        attrs: command.attrs ?? {},
+    }))
+        .digest();
+}
+function assertReachable(adapter, refs, access) {
+    // The same rule a record's own links follow (judgments.ts): the ends sit in the caller's
+    // admitted scopes, and an edge target has both of its ends there.
+    const scopeIds = (0, judgments_js_1.admittedScopeIds)(access);
+    for (const ref of refs) {
+        if (!(0, judgments_js_1.referenceExists)(adapter, ref, scopeIds)) {
+            // Echo only the caller's own input: an unavailable id reads the same whether wrong or outside scope.
+            throw new judgments_js_1.JudgmentError('REFERENCE_NOT_FOUND', `A link end is unavailable: ${ref.kind} ${ref.id}`);
+        }
+    }
+}
+/**
+ * The link a principal already wrote under this command id, if any: a retry finds it here, with
+ * what it states, so the caller can tell a retry from another link under the same id.
+ */
+function findLink(adapter, commandId, access) {
+    const existing = (0, judgments_js_1.getTwinEdge)(adapter, linkEdgeId(access.principalId, commandId));
+    return existing
+        ? {
+            edgeId: existing.edge_id,
+            createdAt: existing.created_at,
+            replayed: true,
+            from: existing.subject_ref,
+            to: existing.object_ref,
+            relation: existing.edge_type,
+            reason: existing.reason_text,
+        }
+        : null;
+}
+function appendLink(adapter, command, access) {
+    nonblank(command.commandId, 'commandId');
+    nonblank(access.principalId, 'principalId');
+    const reason = nonblank(command.reason, 'reason').trim();
+    if (command.from?.kind !== 'memory') {
+        throw new judgments_js_1.JudgmentError('INVALID_COMMAND', 'A link starts from a memory record');
+    }
+    nonblank(command.from.id, 'from.id');
+    if (!command.to || !TARGET_KINDS.has(command.to.kind)) {
+        throw new judgments_js_1.JudgmentError('INVALID_COMMAND', 'A link targets a memory record, a registry node, an observation or an edge');
+    }
+    nonblank(command.to.id, 'to.id');
+    if (!RELATIONS.has(command.relation)) {
+        throw new judgments_js_1.JudgmentError('INVALID_COMMAND', `Unknown link relation: ${command.relation}`);
+    }
+    if (command.to.kind === 'edge' && command.relation !== 'contradicts') {
+        throw new judgments_js_1.JudgmentError('INVALID_COMMAND', 'A link to an edge is a correction and takes the relation contradicts');
+    }
+    for (const ref of command.evidenceRefs ?? []) {
+        if (!EVIDENCE_KINDS.has(ref.kind)) {
+            throw new judgments_js_1.JudgmentError('INVALID_COMMAND', 'Link evidence is an observation or a record');
+        }
+        nonblank(ref.id, 'evidence id');
+    }
+    const edgeId = linkEdgeId(access.principalId, command.commandId);
+    const contentHash = linkContentHash(edgeId, { ...command, reason });
+    const replay = () => {
+        const existing = (0, judgments_js_1.getTwinEdge)(adapter, edgeId);
+        if (!existing)
+            return null;
+        if (!existing.content_hash.equals(contentHash)) {
+            throw new judgments_js_1.JudgmentError('COMMAND_CONFLICT', 'The command id is already bound to another link');
+        }
+        return { edgeId, createdAt: existing.created_at, replayed: true };
+    };
+    assertReachable(adapter, [command.from, command.to, ...(command.evidenceRefs ?? [])], access);
+    const earlier = replay();
+    if (earlier)
+        return earlier;
+    const now = Date.now();
+    const transaction = adapter.transactionImmediate
+        ? adapter.transactionImmediate.bind(adapter)
+        : adapter.transaction.bind(adapter);
+    return transaction(() => {
+        const raced = replay();
+        if (raced)
+            return raced;
+        (0, judgments_js_1.insertTwinEdge)(adapter, {
+            edge_id: edgeId,
+            edge_type: command.relation,
+            subject_ref: command.from,
+            object_ref: command.to,
+            relation_attrs: { ...(command.attrs ?? {}), reason },
+            confidence: 1.0,
+            source: access.edgeSource ?? 'agent',
+            agent_id: Object.hasOwn(command, 'agentId') ? (command.agentId ?? undefined) : access.agentId,
+            model_run_id: command.modelRunId ?? undefined,
+            request_idempotency_key: command.commandId,
+            reason_text: reason,
+            evidence_refs: command.evidenceRefs?.length ? command.evidenceRefs : undefined,
+            content_hash: contentHash,
+            created_at: now,
+        });
+        return { edgeId, createdAt: now, replayed: false };
+    });
+}
+//# sourceMappingURL=links.js.map

package/dist/mama-api.d.ts

@@ -20,16 +20,16 @@
 import { type CheckpointRow, type ListDecisionsOptions, type SearchCandidate, type SuggestFunctionOptions, type UpdateOutcomeParams } from './memory/api.js';
 import { DecisionRecord, type DatabaseInstance } from './db-manager.js';
 import { SemanticEdges } from './decision-formatter.js';
-import { saveMemory as saveMemoryInAdapter, recallMemory as recallMemoryInAdapter, buildProfile as buildProfileInAdapter, ingestMemory as ingestMemoryInAdapter, ingestConversation as ingestConversationInAdapter, evolveMemory, buildMemoryBootstrap as buildMemoryBootstrapInAdapter, createAuditAck, recordMemoryAudit as recordMemoryAuditInAdapter, upsertChannelSummary as upsertChannelSummaryInAdapter, getChannelSummary as getChannelSummaryInAdapter } from './memory/api.js';
+import { saveMemory as saveMemoryInAdapter, recallMemory as recallMemoryInAdapter, buildProfile as buildProfileInAdapter, ingestMemory as ingestMemoryInAdapter, ingestConversation as ingestConversationInAdapter, buildMemoryBootstrap as buildMemoryBootstrapInAdapter, createAuditAck, recordMemoryAudit as recordMemoryAuditInAdapter, upsertChannelSummary as upsertChannelSummaryInAdapter, getChannelSummary as getChannelSummaryInAdapter } from './memory/api.js';
 import { createAuditFinding as createAuditFindingInAdapter, listOpenAuditFindings as listOpenAuditFindingsInAdapter } from './memory/finding-store.js';
 import { listMemoryEventsForMemory as listMemoryEventsForMemoryInAdapter, listRecentMemoryEvents as listRecentMemoryEventsInAdapter } from './memory/event-store.js';
 import { getMemoryProvenance as getMemoryProvenanceInAdapter, listMemoriesByEnvelopeHash as listMemoriesByEnvelopeHashInAdapter, listMemoriesByGatewayCallId as listMemoriesByGatewayCallIdInAdapter, listMemoriesByModelRunId as listMemoriesByModelRunIdInAdapter } from './memory/provenance-query.js';
 import { beginModelRun as beginModelRunInAdapter, commitModelRun as commitModelRunInAdapter, failModelRun as failModelRunInAdapter, getModelRun as getModelRunInAdapter, listModelRunNativeInputs as listModelRunNativeInputsInAdapter } from './runtime/model-run-store.js';
 import { appendToolTrace as appendToolTraceInAdapter, listToolTracesForRun as listToolTracesForRunInAdapter, listToolTraces as listToolTracesInAdapter, readToolTrace as readToolTraceInAdapter } from './runtime/tool-trace-store.js';
 import { type SearchHitDiagnostics } from './knowledge/search-quality.js';
-/**
- * Parameters for mama.save()
- */
+import type { RecordLink } from './memory/judgment-types.js';
+import { type DecisionLinkInput, type DecisionWithEdges } from './memory/decision-links.js';
+import type { LinkReceipt } from './knowledge/links.js';
 interface SaveParams {
     topic: string;
     decision: string;
@@ -52,6 +52,17 @@ interface SaveParams {
     }>;
     /** ISO 8601 date string for when the event actually occurred (e.g. "2023-01-15") */
     event_date?: string | null;
+    /** Decisions this one relates to, each with the relation and the reason the caller judged. */
+    links?: Array<{
+        id: string;
+        relation: RecordLink['relation'];
+        reason: string;
+    }>;
+    /** Decisions this one replaces, each with the reason. */
+    replaces?: Array<{
+        id: string;
+        reason: string;
+    }>;
 }
 /**
  * Similar decision result from search
@@ -294,6 +305,10 @@ declare function suggest(userQuestion: string, options?: SuggestFunctionOptions)
 declare function recall(topic: string, options?: RecallOptions): Promise<string | RecallGraphResult>;
 declare function expandWithGraph(candidates: SearchCandidate[]): Promise<SearchCandidate[]>;
 declare function updateOutcome(decisionId: string, outcome: UpdateOutcomeParams): Promise<void>;
+/** Link one decision to another, or correct a link, with the reason the caller judged. */
+declare function link(input: DecisionLinkInput): Promise<LinkReceipt>;
+/** One decision with every edge in and out, each with its reason and who wrote it. */
+declare function getDecision(id: string): Promise<DecisionWithEdges | null>;
 declare function listDecisions(options?: ListDecisionsOptions): Promise<DecisionRecord[] | string>;
 declare function saveCheckpoint(summary: string, openFiles?: string[], nextSteps?: string, recentConversation?: any[]): Promise<number | bigint>;
 declare function loadCheckpoint(): Promise<CheckpointRow | null>;
@@ -368,7 +383,6 @@ export declare function createMamaApi(adapter: DatabaseInstance): {
         id: string;
     }>;
     ingestConversation: (input: Parameters<typeof ingestConversationInAdapter>[1]) => Promise<import("./index.js").IngestConversationResult>;
-    evolveMemory: (input: Parameters<typeof evolveMemory>[0]) => Promise<import("./memory/evolution-engine.js").EvolutionResult>;
     buildMemoryBootstrap: (params: Parameters<typeof buildMemoryBootstrapInAdapter>[1]) => Promise<import("./memory/types.js").MemoryAgentBootstrap>;
     createAuditAck: (input: Parameters<typeof createAuditAck>[0]) => import("./memory/types.js").MemoryAuditAck;
     recordMemoryAudit: (input: Parameters<typeof recordMemoryAuditInAdapter>[1]) => Promise<{
@@ -408,6 +422,8 @@ export declare function createMamaApi(adapter: DatabaseInstance): {
 export type MamaApi = ReturnType<typeof createMamaApi>;
 declare const mama: {
     save: typeof save;
+    link: typeof link;
+    getDecision: typeof getDecision;
     suggest: typeof suggest;
     saveMemory: typeof saveMemory;
     recallMemory: typeof recallMemory;
@@ -417,7 +433,6 @@ declare const mama: {
     buildProfile: typeof buildProfile;
     ingestMemory: typeof ingestMemory;
     ingestConversation: typeof ingestConversation;
-    evolveMemory: typeof evolveMemory;
     buildMemoryBootstrap: typeof buildMemoryBootstrap;
     createAuditAck: typeof createAuditAck;
     recordMemoryAudit: typeof recordMemoryAudit;
@@ -445,6 +460,6 @@ declare const mama: {
     recall: typeof recall;
     expandWithGraph: typeof expandWithGraph;
 };
-export { save, suggest, saveMemory, recallMemory, listDecisions as list, listCheckpoints, updateOutcome, buildProfile, ingestMemory, ingestConversation, evolveMemory, buildMemoryBootstrap, createAuditAck, recordMemoryAudit, upsertChannelSummary, getChannelSummary, listOpenAuditFindings, createAuditFinding, getMemoryProvenance, listMemoriesByEnvelopeHash, listMemoriesByGatewayCallId, listMemoriesByModelRunId, listMemoryEventsForMemory, listRecentMemoryEvents, beginModelRun, commitModelRun, failModelRun, getModelRun, appendToolTrace, listToolTracesForRun, listToolTraces, readToolTrace, saveCheckpoint, loadCheckpoint, recall, expandWithGraph, };
+export { save, link, getDecision, suggest, saveMemory, recallMemory, listDecisions as list, listCheckpoints, updateOutcome, buildProfile, ingestMemory, ingestConversation, buildMemoryBootstrap, createAuditAck, recordMemoryAudit, upsertChannelSummary, getChannelSummary, listOpenAuditFindings, createAuditFinding, getMemoryProvenance, listMemoriesByEnvelopeHash, listMemoriesByGatewayCallId, listMemoriesByModelRunId, listMemoryEventsForMemory, listRecentMemoryEvents, beginModelRun, commitModelRun, failModelRun, getModelRun, appendToolTrace, listToolTracesForRun, listToolTraces, readToolTrace, saveCheckpoint, loadCheckpoint, recall, expandWithGraph, };
 export default mama;
 //# sourceMappingURL=mama-api.d.ts.map