@jungjaehoon/mama-core 4.1.1 → 5.1.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';
@@ -17,10 +19,9 @@ export { observationVersionId, appendObservationVersion, getObservationVersion,
 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 { vectorSearch, fts5Search, RECALL_EXCLUDED_STATUSES } from './search.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.RECALL_EXCLUDED_STATUSES = 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; } });
@@ -59,21 +62,16 @@ Object.defineProperty(exports, "WORK_PATCH_DUE_AT_PATTERN", { enumerable: true,
 var search_js_1 = require("./search.js");
 Object.defineProperty(exports, "vectorSearch", { enumerable: true, get: function () { return search_js_1.vectorSearch; } });
 Object.defineProperty(exports, "fts5Search", { enumerable: true, get: function () { return search_js_1.fts5Search; } });
+Object.defineProperty(exports, "RECALL_EXCLUDED_STATUSES", { enumerable: true, get: function () { return search_js_1.RECALL_EXCLUDED_STATUSES; } });
 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 +83,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/knowledge/search.d.ts

@@ -8,6 +8,8 @@
  */
 import type { DatabaseInstance, DecisionRecord } from '../db-manager.js';
 import type { MemoryKindFilter } from '../memory/types.js';
+/** Statuses default recall leaves out; history (`includeHistory`) shows them. */
+export declare const RECALL_EXCLUDED_STATUSES: readonly ["superseded", "contradicted", "stale"];
 /**
  * Brute-force cosine similarity search over stored embeddings.
  *
@@ -31,7 +33,10 @@ export declare function vectorSearch(adapter: DatabaseInstance, queryEmbedding:
  * @param limit - Max rows to return
  * @returns Matching decision IDs with BM25 rank scores
  */
-export declare function fts5Search(adapter: DatabaseInstance, query: string, limit?: number, kind?: MemoryKindFilter): Promise<{
+export declare function fts5Search(adapter: DatabaseInstance, query: string, limit?: number, kind?: MemoryKindFilter, exclude?: {
+    statuses?: readonly string[];
+    amendments?: boolean;
+}): Promise<{
     id: string;
     rank: number;
 }[]>;

package/dist/knowledge/search.js

@@ -8,8 +8,11 @@
  * @module knowledge/search
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.RECALL_EXCLUDED_STATUSES = void 0;
 exports.vectorSearch = vectorSearch;
 exports.fts5Search = fts5Search;
+/** Statuses default recall leaves out; history (`includeHistory`) shows them. */
+exports.RECALL_EXCLUDED_STATUSES = ['superseded', 'contradicted', 'stale'];
 /**
  * Brute-force cosine similarity search over stored embeddings.
  *
@@ -59,7 +62,7 @@ async function vectorSearch(adapter, queryEmbedding, limit = 5, threshold = 0.7,
  * @param limit - Max rows to return
  * @returns Matching decision IDs with BM25 rank scores
  */
-async function fts5Search(adapter, query, limit = 10, kind) {
+async function fts5Search(adapter, query, limit = 10, kind, exclude) {
     // An absent FTS table is a real answer - no rows. A failing adapter is not,
     // so this lookup is left unguarded and its errors reach the caller.
     const tableCheck = adapter
@@ -68,24 +71,27 @@ async function fts5Search(adapter, query, limit = 10, kind) {
     if (!tableCheck)
         return [];
     // Query execution - let errors propagate to the caller
-    const kindClause = Array.isArray(kind)
-        ? `AND d.kind IN (${kind.map(() => '?').join(', ')})`
-        : kind === undefined
-            ? ''
-            : 'AND d.kind = ?';
+    const kinds = Array.isArray(kind) ? kind : kind === undefined ? [] : [kind];
+    const kindClause = kinds.length === 0 ? '' : `AND d.kind IN (${kinds.map(() => '?').join(', ')})`;
+    // Excluded rows are left out before LIMIT, so they cannot fill the pool ahead of rows that stay.
+    const statuses = exclude?.statuses ?? [];
+    const statusClause = statuses.length === 0
+        ? ''
+        : `AND (d.status IS NULL OR d.status NOT IN (${statuses.map(() => '?').join(', ')}))`;
+    const amendmentClause = exclude?.amendments
+        ? "AND json_extract(d.payload_json, '$.amended') IS NULL"
+        : '';
     const stmt = adapter.prepare(`
     SELECT d.id, rank
     FROM decisions_fts
     JOIN decisions d ON decisions_fts.rowid = d.rowid
     WHERE decisions_fts MATCH ?
       ${kindClause}
+      ${statusClause}
+      ${amendmentClause}
     ORDER BY rank
     LIMIT ?
   `);
-    return (Array.isArray(kind)
-        ? stmt.all(query, ...kind, limit)
-        : kind === undefined
-            ? stmt.all(query, limit)
-            : stmt.all(query, kind, limit));
+    return stmt.all(query, ...kinds, ...statuses, limit);
 }
 //# sourceMappingURL=search.js.map