@jungjaehoon/mama-core 4.1.0 → 5.0.0

package/README.md

@@ -4,7 +4,7 @@ The shared engine for storage, records and revisions, evidence links, memory, se
 runtime drivers. Consumers supply their own database, principals, source access and product
 vocabulary through public exports. Core does not require the MAMA OS daemon.
 
-Version **4.1.0**; Node.js 22.13+. This README describes the current rebuild checkout.
+Version **5.0.0**; Node.js 22.13+. This README describes the current rebuild checkout.
 See [architecture](../../docs/explanation/architecture.md) and
 [the shared-engine goal](../../INTENT.md).
 
@@ -13,15 +13,15 @@ See [architecture](../../docs/explanation/architecture.md) and
 [package.json](package.json) defines supported import paths; [src/index.ts](src/index.ts)
 defines root exports. Representative root exports:
 
-| Area      | Root exports                                                                                      |
-| --------- | ------------------------------------------------------------------------------------------------- |
-| Storage   | `createAdapter`, `SQLiteAdapter`, `initDB`, `getDB`, `getAdapter`, `closeDB`                      |
-| Records   | `createKnowledge`, `appendJudgment`, `ingestSource`                                               |
-| Memory    | `mama`, `createMamaApi`, `saveMemory`, `recallMemory`, `ingestConversation`, `MEMORY_KINDS`       |
-| Search    | `generateEmbedding`, `generateEnhancedEmbedding`, `cosineSimilarity`, `EmbeddingCache`            |
-| Evidence  | `getMemoryProvenance`, `resolveMemoryProvenance`, `insertTwinEdge`, `listVisibleTwinEdgesForRefs` |
-| Execution | `createCatalog`, `createDispatcher`, `createClient`, `startRuntime`, `createActionIpcServer`      |
-| Traces    | `beginModelRun`, `commitModelRun`, `appendToolTrace`, `listToolTracesForRun`                      |
+| Area      | Root exports                                                                                 |
+| --------- | -------------------------------------------------------------------------------------------- |
+| Storage   | `createAdapter`, `SQLiteAdapter`, `initDB`, `getDB`, `getAdapter`, `closeDB`                 |
+| Records   | `createKnowledge`, `appendJudgment`, `ingestSource`                                          |
+| Memory    | `mama`, `createMamaApi`, `saveMemory`, `recallMemory`, `ingestConversation`, `MEMORY_KINDS`  |
+| Search    | `generateEmbedding`, `generateEnhancedEmbedding`, `cosineSimilarity`, `EmbeddingCache`       |
+| Evidence  | `getMemoryProvenance`, `resolveMemoryProvenance`, `listVisibleTwinEdgesForRefs`              |
+| Execution | `createCatalog`, `createDispatcher`, `createClient`, `startRuntime`, `createActionIpcServer` |
+| Traces    | `beginModelRun`, `commitModelRun`, `appendToolTrace`, `listToolTracesForRun`                 |
 
 Every public subpath below is relative to `@jungjaehoon/mama-core`:
 

package/db/migrations/099-commitment-revision-graph.sql

@@ -1,2 +1,5 @@
+-- 099 once backfilled a host builds_on from each commitment revision to the one before it. The
+-- host no longer writes edges the agent did not state (owner, 2026-09-30); the order of revisions
+-- lives in commitment_assignments. The version is kept so databases that crossed it stay aligned.
 INSERT OR IGNORE INTO schema_version (version, description)
 VALUES (99, 'Commitment revision graph links');

package/dist/api/catalog.js

@@ -899,7 +899,7 @@ function coreActionRegistrations(knowledge, adapter, deps) {
         {
             contract: {
                 name: 'memory.search',
-                summary: 'Search or list memory records under the caller authority. Omitted scopes read the admitted corpus; explicit scopes must be a subset of it. With a query this is the semantic recall path (vector + lexical fusion, learned ranker when enabled); without one it is the exact topic-prefix ledger read.',
+                summary: 'Search or list memory records under the caller authority. Omitted scopes read the admitted corpus; explicit scopes must be a subset of it. With a query this is the semantic recall path (vector + lexical fusion, learned ranker when enabled), each hit lists the records its stated links reach (links: id, topic, relation, reason, corrected_by), and a result reached through a link names the hit it came from (related_to), the relation (graph_source), the reason (edge_reason) and any correction (edge_corrected_by); a hit that is one revision of a work item names it (work_item: commitment_id, revision, head_revision), and an earlier revision can rank above the head that corrected it, so open the head before answering from it; without one it is the exact topic-prefix ledger read.',
                 inputSchema: memorySearchSchema,
                 examples: [
                     {
@@ -1078,14 +1078,14 @@ function coreActionRegistrations(knowledge, adapter, deps) {
         {
             contract: {
                 name: 'memory.read:graph',
-                summary: 'The decision graph this caller may see: `view: graph` returns a bounded page of nodes with the edges joining admitted nodes and the admitted total; `nodes` returns the named ids; `detail` returns one record in full; `similarity` returns what the vector index says is near, over the admitted window. Every view is bounded by the admitted scopes.',
+                summary: 'The decision graph this caller may see: `view: graph` returns a bounded page of nodes with the edges joining admitted nodes and the admitted total; `nodes` returns the named ids; `detail` returns one record in full. Every view is bounded by the admitted scopes.',
                 inputSchema: {
                     type: 'object',
                     additionalProperties: false,
                     properties: {
                         view: {
                             type: 'string',
-                            enum: ['graph', 'nodes', 'detail', 'similarity'],
+                            enum: ['graph', 'nodes', 'detail'],
                             description: 'Memory graph view, e.g. "detail".',
                         },
                         id: { type: 'string', description: 'One memory id for detail, e.g. "mem_123".' },
@@ -1132,9 +1132,6 @@ function coreActionRegistrations(knowledge, adapter, deps) {
                     }
                     return { nodes: await (0, graph_read_js_1.readGraphNodes)(adapter, scopes, { ids, limit: null }) };
                 }
-                if (view === 'similarity') {
-                    return { edges: await (0, graph_read_js_1.readGraphSimilarityEdges)(adapter, scopes) };
-                }
                 const [nodes, edges, total] = await Promise.all([
                     (0, graph_read_js_1.readGraphNodes)(adapter, scopes, { limit }),
                     (0, graph_read_js_1.readGraphEdges)(adapter, scopes),

package/dist/api/dispatch.js

@@ -272,7 +272,11 @@ function validateInput(schema, value, path) {
     if (schema.oneOf !== undefined) {
         const matches = schema.oneOf.filter((sub) => validateInput(sub, value, path) === null).length;
         if (matches !== 1) {
-            return `${path} must match exactly one allowed shape (${matches} matched).`;
+            // A refusal names what is allowed: "(0 matched)" alone once left a caller dropping the
+            // field and the write with it.
+            const shapes = schema.oneOf.map(shapeName).join(', ');
+            const described = schema.description === undefined ? '' : ` ${schema.description}`;
+            return `${path} must match exactly one of: ${shapes} (${matches} matched).${described}`;
         }
     }
     if (typeof value === 'number') {
@@ -349,6 +353,13 @@ function validateInput(schema, value, path) {
     }
     return null;
 }
+function shapeName(schema) {
+    if (schema.const !== undefined)
+        return JSON.stringify(schema.const);
+    if (schema.enum !== undefined)
+        return schema.enum.map((value) => JSON.stringify(value)).join(' | ');
+    return schema.type ?? 'a described shape';
+}
 function typeMismatch(type, value) {
     switch (type) {
         case 'object':

package/dist/db-adapter/node-sqlite-adapter.d.ts

@@ -94,7 +94,11 @@ export declare class NodeSQLiteAdapter implements DatabaseInstance {
     private rebuildRegistry069;
     private rebuildRecordActors070;
     private applyRepairMigration;
-    private rebuildWorkflowMemoryKind098;
+    /**
+     * A migration that drops and recreates a referenced table: foreign keys go off outside the
+     * transaction (a PRAGMA inside it does nothing), so the drop cascades to no row.
+     */
+    private applyWithForeignKeysOff;
     private operatorMemoryCommitIntentTableSql;
     private hasOperatorMemoryCommitIntentClaimInvariant;
     private assertMigration040BaseComplete;

package/dist/db-adapter/node-sqlite-adapter.js

@@ -14,7 +14,6 @@ const fs_1 = __importDefault(require("fs"));
 const node_sqlite_statement_js_1 = require("./node-sqlite-statement.js");
 const debug_logger_js_1 = require("../debug-logger.js");
 const embedder_js_1 = require("../embedding/embedder.js");
-const commitment_revision_migration_js_1 = require("../knowledge/commitment-revision-migration.js");
 const SQLITE_IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 // Migration 071 origin invariant, kept in ONE place so the DDL the rebuild
 // writes and the shape verification that admits a table cannot drift. A row is
@@ -322,7 +321,7 @@ class NodeSQLiteAdapter {
     }
     // Re-read one decision's effective status into the cache. MUST be called after
     // any status transition that can move a row OUT of an excluded state (e.g.
-    // promoteMemoryStatus staging->active): the vectorSearch pre-filter drops
+    // a status amendment back to active): the vectorSearch pre-filter drops
     // excluded rowids before the api post-filter ever sees them, so a stale
     // excluded entry would make an active row unrecallable until restart.
     refreshDecisionStatusCache(rowid) {
@@ -675,22 +674,6 @@ class NodeSQLiteAdapter {
             if (version <= currentVersion) {
                 continue;
             }
-            if (isCore && version === 99) {
-                try {
-                    this.exec('BEGIN TRANSACTION');
-                    (0, commitment_revision_migration_js_1.backfillCommitmentRevisionGraph)(this);
-                    this.exec(fs_1.default.readFileSync(path_1.default.join(migrationsDir, file), 'utf8'));
-                    this.stampMigration(sourceName, version);
-                    this.exec('COMMIT');
-                    (0, debug_logger_js_1.info)(`[node-sqlite-adapter] Migration ${file} applied successfully`);
-                }
-                catch (err) {
-                    this.exec('ROLLBACK');
-                    const message = err instanceof Error ? err.message : String(err);
-                    throw new Error(`Migration ${file} failed: ${message}`);
-                }
-                continue;
-            }
             if (isCore && version === 98) {
                 const decisionColumns = this.tableColumns('decisions');
                 if (!this.tableExists('decisions_fts') ||
@@ -698,11 +681,27 @@ class NodeSQLiteAdapter {
                     (0, debug_logger_js_1.warn)(`[node-sqlite-adapter] Migration ${file} deferred: the full decisions projection is not present`);
                     continue;
                 }
-                this.rebuildWorkflowMemoryKind098(migrationsDir);
+                this.applyWithForeignKeysOff(migrationsDir, file);
                 this.stampMigration(sourceName, version);
                 (0, debug_logger_js_1.info)(`[node-sqlite-adapter] Migration ${file} reconciled successfully`);
                 continue;
             }
+            // 084 rebuilds memory_scopes. Its own PRAGMA foreign_keys = OFF is a no-op inside the
+            // migration transaction, so dropping the table cascaded to every memory scope binding
+            // (a development memory at schema 80 lost all 414 on the way to 099).
+            if (isCore && version === 84) {
+                if (!this.tableExists('memory_scopes')) {
+                    // As the plain path does for an ALTER TABLE on a missing table: a legacy database whose
+                    // scope tables come later from the structural repair.
+                    (0, debug_logger_js_1.warn)(`[node-sqlite-adapter] Migration ${file} skipped: memory_scopes does not exist`);
+                    this.stampMigration(sourceName, version);
+                    continue;
+                }
+                this.applyWithForeignKeysOff(migrationsDir, file);
+                this.stampMigration(sourceName, version);
+                (0, debug_logger_js_1.info)(`[node-sqlite-adapter] Migration ${file} applied successfully`);
+                continue;
+            }
             // Runtime MetricsStore may already own project_id/channel_id. Reconcile
             // this additive migration atomically instead of accepting a duplicate skip.
             if (isCore && version === 68) {
@@ -1347,15 +1346,19 @@ class NodeSQLiteAdapter {
             throw new Error(`Repair migration ${fileName} failed: ${message}`);
         }
     }
-    rebuildWorkflowMemoryKind098(migrationsDir) {
-        const migrationPath = path_1.default.join(migrationsDir, '098-workflow-memory-kind.sql');
+    /**
+     * A migration that drops and recreates a referenced table: foreign keys go off outside the
+     * transaction (a PRAGMA inside it does nothing), so the drop cascades to no row.
+     */
+    applyWithForeignKeysOff(migrationsDir, file) {
+        const migrationPath = path_1.default.join(migrationsDir, file);
         if (!fs_1.default.existsSync(migrationPath)) {
-            throw new Error('Migration 098 workflow-kind rebuild SQL is missing');
+            throw new Error(`Migration ${file} SQL is missing`);
         }
         const previousForeignKeys = this.readForeignKeysEnabled();
         this.exec('PRAGMA foreign_keys = OFF');
         if (this.readForeignKeysEnabled()) {
-            throw new Error('Migration 098 could not disable foreign_keys before rebuilding decisions');
+            throw new Error(`Migration ${file} could not disable foreign_keys before its rebuild`);
         }
         try {
             this.transaction(() => {
@@ -1363,7 +1366,7 @@ class NodeSQLiteAdapter {
             });
             const violations = this.prepare('PRAGMA foreign_key_check').all();
             if (violations.length > 0) {
-                throw new Error('Migration 098 left foreign key violations');
+                throw new Error(`Migration ${file} left foreign key violations`);
             }
         }
         finally {

package/dist/db-manager.d.ts

@@ -81,7 +81,6 @@ export interface DecisionRecord {
     refined_from?: string | string[] | null;
     created_at: number;
     updated_at?: number;
-    edges?: DecisionEdgeRow[];
     /** ISO 8601 date when the event actually occurred. Null if not set. */
     event_date?: string | null;
     /** Source event timestamp in milliseconds when known. Null if not set. */
@@ -94,19 +93,9 @@ export interface OutcomeData {
     duration_days?: number | null;
     confidence?: number | null;
 }
-export interface DecisionEdgeRow {
-    from_id: string;
-    to_id: string;
-    relationship: string;
-    reason?: string | null;
-    weight?: number;
-    created_at?: number;
-    created_by?: string;
-    approved_by_user?: number | null;
-    decision_id?: string | null;
-    evidence?: string | null;
-}
 export interface SemanticEdgeItem {
+    /** The link's id when it is a `twin_edges` row; null for a legacy `decision_edges` row. */
+    edge_id?: string | null;
     from_id: string;
     to_id: string;
     relationship: string;

package/dist/index.d.ts

@@ -14,7 +14,7 @@ import mama from './mama-api.js';
 export { mama };
 export { createMamaApi, type MamaApi } from './mama-api.js';
 export { MEMORY_SCOPE_KINDS, MEMORY_KINDS, MEMORY_STATUSES, MEMORY_EDGE_TYPES, createEmptyRecallBundle, type MemoryScopeKind, type MemoryKind, type MemoryKindFilter, type MemoryStatus, type MemoryEdgeType, type MemoryScopeRef, type MemorySourceRef, type MemoryRecord, type MemoryWriteProvenance, type MemoryProvenanceRecord, type PublicSaveMemoryInput, type PublicIngestMemoryInput, type PublicIngestConversationInput, type MemorySearchResultHit, type MemoryEdge, type ProfileSnapshot, type RecallBundle, type ConversationMessage, type IngestConversationInput, type ExtractedMemoryUnit, type IngestConversationResult, type AuditFindingRecord, canonicalizeContextScopes, } from './memory/types.js';
-export { saveMemory, saveJudgmentRecord, saveLegacyMemory, promoteMemoryStatus, readMemoryRecordById, readMemoryRecordsInScopes, retireMemoryRecord, recallMemory, buildProfile, ingestMemory, evolveMemory, buildMemoryBootstrap, createAuditAck, recordMemoryAudit, ingestConversation, upsertChannelSummary, getChannelSummary, type MemoryRetirementStatus, type ReadMemoryRecordsOptions, } from './memory/api.js';
+export { saveMemory, saveJudgmentRecord, saveLegacyMemory, readMemoryRecordById, readMemoryRecordsInScopes, retireMemoryRecord, recallMemory, buildProfile, ingestMemory, buildMemoryBootstrap, createAuditAck, recordMemoryAudit, ingestConversation, upsertChannelSummary, getChannelSummary, type MemoryRetirementStatus, type ReadMemoryRecordsOptions, } from './memory/api.js';
 export { createKnowledge, appendJudgment, ingestSource, JudgmentError, type Knowledge, type KnowledgeOptions, type JudgmentAccess, type SourceIngestCommand, type SourceIngestReceipt, type WorkGraphPage, type WorkGraphQuery, type WorkReference, } from './knowledge/index.js';
 export { queryRelevantTruth } from './memory/truth-store.js';
 export { createAuditFinding, listOpenAuditFindings } from './memory/finding-store.js';
@@ -30,7 +30,7 @@ export { MODEL_RUN_STATUSES, type ModelRunStatus, type BeginModelRunInput, type
 export { beginModelRun, commitModelRun, failModelRun, getModelRun, } from './runtime/model-run-store.js';
 export { appendToolTrace, appendOperationToolTrace, listToolTracesForRun, listToolTraces, readToolTrace, } from './runtime/tool-trace-store.js';
 export { TWIN_EDGE_SOURCES, TWIN_EDGE_TYPES, TWIN_REF_KINDS, type InsertTwinEdgeInput, type ListVisibleTwinEdgesOptions, type TwinEdgeInsert, type TwinEdgeRecord, type TwinEdgeSource, type TwinEdgeType, type TwinRef, type TwinRefKind, type TwinScopeRef, } from './knowledge/twin-edge-types.js';
-export { getTwinEdge, insertTwinEdge, listTwinEdgesForRefs, mapTwinEdgeRow, } from './knowledge/judgments.js';
+export { getTwinEdge, listTwinEdgesForRefs, mapTwinEdgeRow } from './knowledge/judgments.js';
 export { listVisibleTwinEdgesForRefs } from './knowledge/access.js';
 export type { ActionCall, ActionContract, ActionExample, ActionFailure, ActionFailureKind, ActionResult, ActionSchemaObject, ActionSessionFacts, } from './action-contracts.js';
 export { createCatalog, coreActionRegistrations, UnknownActionError, type ActionCatalog, type ActionContext, type ActionExec, type ActionRegistration, type MemoryReadAllowance, } from './api/catalog.js';

package/dist/index.js

@@ -25,9 +25,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.insertMemoryEventInTransaction = exports.appendMemoryEvent = exports.listOpenAuditFindings = exports.createAuditFinding = exports.queryRelevantTruth = exports.JudgmentError = exports.ingestSource = exports.appendJudgment = exports.createKnowledge = exports.getChannelSummary = exports.upsertChannelSummary = exports.ingestConversation = exports.recordMemoryAudit = exports.createAuditAck = exports.buildMemoryBootstrap = exports.evolveMemory = exports.ingestMemory = exports.buildProfile = exports.recallMemory = exports.retireMemoryRecord = exports.readMemoryRecordsInScopes = exports.readMemoryRecordById = exports.promoteMemoryStatus = exports.saveLegacyMemory = exports.saveJudgmentRecord = exports.saveMemory = exports.canonicalizeContextScopes = exports.createEmptyRecallBundle = exports.MEMORY_EDGE_TYPES = exports.MEMORY_STATUSES = exports.MEMORY_KINDS = exports.MEMORY_SCOPE_KINDS = exports.createMamaApi = exports.mama = exports.SQLiteAdapter = exports.createAdapter = exports.getDbPath = exports.updateDecisionOutcome = exports.closeDB = exports.getAdapter = exports.getDB = exports.initDB = exports.EmbeddingCache = exports.EMBEDDING_PREFIX_SCHEME = exports.MODEL_NAME = exports.EMBEDDING_DIM = exports.embeddingCache = exports.cosineSimilarity = exports.generateEnhancedEmbedding = exports.generateEmbedding = void 0;
-exports.newRequestId = exports.IpcTransportError = exports.encodeFrame = exports.createActionIpcServer = exports.startRuntime = exports.createClient = exports.withCallReceipt = exports.validateInput = exports.createDispatcher = exports.UnknownActionError = exports.coreActionRegistrations = exports.createCatalog = exports.listVisibleTwinEdgesForRefs = exports.mapTwinEdgeRow = exports.listTwinEdgesForRefs = exports.insertTwinEdge = exports.getTwinEdge = exports.TWIN_REF_KINDS = exports.TWIN_EDGE_TYPES = exports.TWIN_EDGE_SOURCES = exports.readToolTrace = exports.listToolTraces = exports.listToolTracesForRun = exports.appendOperationToolTrace = exports.appendToolTrace = exports.getModelRun = exports.failModelRun = exports.commitModelRun = exports.beginModelRun = exports.MODEL_RUN_STATUSES = exports.scanMemoryWriteInput = exports.scanForSecrets = exports.sanitizeRecallText = exports.sanitizeRecallBundle = exports.resolveMemoryProvenance = exports.toIndexedEvent = exports.resolveMemoryProvenanceLive = exports.parseSourceRef = exports.isMessageRefVisible = exports.isEventVisibleNow = exports.OBSERVATION_COLUMNS = exports.listMemoryProvenanceAudit = exports.getMemoryProvenanceAudit = exports.listMemoriesByModelRunId = exports.listMemoriesByGatewayCallId = exports.listMemoriesByEnvelopeHash = exports.getMemoryProvenance = exports.normalizeMemoryWriteProvenance = exports.listRecentMemoryEvents = exports.listMemoryEventsForMemory = void 0;
-exports.FALLBACK_MODEL = exports.DEFAULT_MODEL = exports.listModels = exports.isAvailable = exports.generate = exports.extractCodeExample = exports.extractQuickAnswer = exports.estimateTokens = exports.ensureTokenBudget = exports.formatTrustContext = exports.formatList = exports.formatRecall = exports.formatLegacyContext = exports.formatContext = exports.isMAMAError = exports.wrapError = exports.ErrorCodes = exports.TimeoutError = exports.RateLimitError = exports.LinkError = exports.ConfigurationError = exports.EmbeddingError = exports.DatabaseError = exports.ValidationError = exports.NotFoundError = exports.MAMAError = exports.DebugLogger = exports.error = exports.warn = exports.info = exports.debug = exports.logSearching = exports.logLoading = exports.logError = exports.logFailed = exports.logComplete = exports.logProgress = exports.formatTopNContext = exports.selectTopDecisions = exports.calculateRelevance = exports.CanonicalizeError = exports.targetRefHash = exports.canonicalizeJSON = exports.IPC_MAX_FRAME_BYTES = exports.sendIpcRequest = void 0;
+exports.listRecentMemoryEvents = exports.listMemoryEventsForMemory = exports.insertMemoryEventInTransaction = exports.appendMemoryEvent = exports.listOpenAuditFindings = exports.createAuditFinding = exports.queryRelevantTruth = exports.JudgmentError = exports.ingestSource = exports.appendJudgment = exports.createKnowledge = exports.getChannelSummary = exports.upsertChannelSummary = exports.ingestConversation = exports.recordMemoryAudit = exports.createAuditAck = exports.buildMemoryBootstrap = exports.ingestMemory = exports.buildProfile = exports.recallMemory = exports.retireMemoryRecord = exports.readMemoryRecordsInScopes = exports.readMemoryRecordById = exports.saveLegacyMemory = exports.saveJudgmentRecord = exports.saveMemory = exports.canonicalizeContextScopes = exports.createEmptyRecallBundle = exports.MEMORY_EDGE_TYPES = exports.MEMORY_STATUSES = exports.MEMORY_KINDS = exports.MEMORY_SCOPE_KINDS = exports.createMamaApi = exports.mama = exports.SQLiteAdapter = exports.createAdapter = exports.getDbPath = exports.updateDecisionOutcome = exports.closeDB = exports.getAdapter = exports.getDB = exports.initDB = exports.EmbeddingCache = exports.EMBEDDING_PREFIX_SCHEME = exports.MODEL_NAME = exports.EMBEDDING_DIM = exports.embeddingCache = exports.cosineSimilarity = exports.generateEnhancedEmbedding = exports.generateEmbedding = void 0;
+exports.canonicalizeJSON = exports.IPC_MAX_FRAME_BYTES = exports.sendIpcRequest = exports.newRequestId = exports.IpcTransportError = exports.encodeFrame = exports.createActionIpcServer = exports.startRuntime = exports.createClient = exports.withCallReceipt = exports.validateInput = exports.createDispatcher = exports.UnknownActionError = exports.coreActionRegistrations = exports.createCatalog = exports.listVisibleTwinEdgesForRefs = exports.mapTwinEdgeRow = exports.listTwinEdgesForRefs = exports.getTwinEdge = exports.TWIN_REF_KINDS = exports.TWIN_EDGE_TYPES = exports.TWIN_EDGE_SOURCES = exports.readToolTrace = exports.listToolTraces = exports.listToolTracesForRun = exports.appendOperationToolTrace = exports.appendToolTrace = exports.getModelRun = exports.failModelRun = exports.commitModelRun = exports.beginModelRun = exports.MODEL_RUN_STATUSES = exports.scanMemoryWriteInput = exports.scanForSecrets = exports.sanitizeRecallText = exports.sanitizeRecallBundle = exports.resolveMemoryProvenance = exports.toIndexedEvent = exports.resolveMemoryProvenanceLive = exports.parseSourceRef = exports.isMessageRefVisible = exports.isEventVisibleNow = exports.OBSERVATION_COLUMNS = exports.listMemoryProvenanceAudit = exports.getMemoryProvenanceAudit = exports.listMemoriesByModelRunId = exports.listMemoriesByGatewayCallId = exports.listMemoriesByEnvelopeHash = exports.getMemoryProvenance = exports.normalizeMemoryWriteProvenance = void 0;
+exports.FALLBACK_MODEL = exports.DEFAULT_MODEL = exports.listModels = exports.isAvailable = exports.generate = exports.extractCodeExample = exports.extractQuickAnswer = exports.estimateTokens = exports.ensureTokenBudget = exports.formatTrustContext = exports.formatList = exports.formatRecall = exports.formatLegacyContext = exports.formatContext = exports.isMAMAError = exports.wrapError = exports.ErrorCodes = exports.TimeoutError = exports.RateLimitError = exports.LinkError = exports.ConfigurationError = exports.EmbeddingError = exports.DatabaseError = exports.ValidationError = exports.NotFoundError = exports.MAMAError = exports.DebugLogger = exports.error = exports.warn = exports.info = exports.debug = exports.logSearching = exports.logLoading = exports.logError = exports.logFailed = exports.logComplete = exports.logProgress = exports.formatTopNContext = exports.selectTopDecisions = exports.calculateRelevance = exports.CanonicalizeError = exports.targetRefHash = void 0;
 var embedder_js_1 = require("./embedding/embedder.js");
 Object.defineProperty(exports, "generateEmbedding", { enumerable: true, get: function () { return embedder_js_1.generateEmbedding; } });
 Object.defineProperty(exports, "generateEnhancedEmbedding", { enumerable: true, get: function () { return embedder_js_1.generateEnhancedEmbedding; } });
@@ -63,14 +63,12 @@ var api_js_1 = require("./memory/api.js");
 Object.defineProperty(exports, "saveMemory", { enumerable: true, get: function () { return api_js_1.saveMemory; } });
 Object.defineProperty(exports, "saveJudgmentRecord", { enumerable: true, get: function () { return api_js_1.saveJudgmentRecord; } });
 Object.defineProperty(exports, "saveLegacyMemory", { enumerable: true, get: function () { return api_js_1.saveLegacyMemory; } });
-Object.defineProperty(exports, "promoteMemoryStatus", { enumerable: true, get: function () { return api_js_1.promoteMemoryStatus; } });
 Object.defineProperty(exports, "readMemoryRecordById", { enumerable: true, get: function () { return api_js_1.readMemoryRecordById; } });
 Object.defineProperty(exports, "readMemoryRecordsInScopes", { enumerable: true, get: function () { return api_js_1.readMemoryRecordsInScopes; } });
 Object.defineProperty(exports, "retireMemoryRecord", { enumerable: true, get: function () { return api_js_1.retireMemoryRecord; } });
 Object.defineProperty(exports, "recallMemory", { enumerable: true, get: function () { return api_js_1.recallMemory; } });
 Object.defineProperty(exports, "buildProfile", { enumerable: true, get: function () { return api_js_1.buildProfile; } });
 Object.defineProperty(exports, "ingestMemory", { enumerable: true, get: function () { return api_js_1.ingestMemory; } });
-Object.defineProperty(exports, "evolveMemory", { enumerable: true, get: function () { return api_js_1.evolveMemory; } });
 Object.defineProperty(exports, "buildMemoryBootstrap", { enumerable: true, get: function () { return api_js_1.buildMemoryBootstrap; } });
 Object.defineProperty(exports, "createAuditAck", { enumerable: true, get: function () { return api_js_1.createAuditAck; } });
 Object.defineProperty(exports, "recordMemoryAudit", { enumerable: true, get: function () { return api_js_1.recordMemoryAudit; } });
@@ -136,7 +134,6 @@ Object.defineProperty(exports, "TWIN_EDGE_TYPES", { enumerable: true, get: funct
 Object.defineProperty(exports, "TWIN_REF_KINDS", { enumerable: true, get: function () { return twin_edge_types_js_1.TWIN_REF_KINDS; } });
 var judgments_js_1 = require("./knowledge/judgments.js");
 Object.defineProperty(exports, "getTwinEdge", { enumerable: true, get: function () { return judgments_js_1.getTwinEdge; } });
-Object.defineProperty(exports, "insertTwinEdge", { enumerable: true, get: function () { return judgments_js_1.insertTwinEdge; } });
 Object.defineProperty(exports, "listTwinEdgesForRefs", { enumerable: true, get: function () { return judgments_js_1.listTwinEdgesForRefs; } });
 Object.defineProperty(exports, "mapTwinEdgeRow", { enumerable: true, get: function () { return judgments_js_1.mapTwinEdgeRow; } });
 var access_js_1 = require("./knowledge/access.js");

package/dist/knowledge/commitments.d.ts

@@ -36,6 +36,8 @@ export interface CommitmentChainEntry {
     revision: number;
     operation: CommitmentRevision['operation'];
     eventDatetime: number | null;
+    /** When the revision was written; the day of a revision with no event time. */
+    createdAt: number;
     status: string | null;
     stage: string | null;
     summary: string | null;

package/dist/knowledge/commitments.js

@@ -106,6 +106,7 @@ function buildChain(adapter, revisions, admitted) {
             revision: revision.revision,
             operation: revision.operation,
             eventDatetime: revision.eventDatetime,
+            createdAt: revision.createdAt,
             status: revision.operation === 'withdraw' ? 'cancelled' : stringField(values, 'status'),
             stage: stringField(values, 'stage'),
             summary: readJudgmentSummary(adapter, revision.recordRef.id, admitted),

package/dist/knowledge/graph-query.d.ts

@@ -13,13 +13,22 @@ import type { DatabaseAdapter, DecisionRecord, SemanticEdges } from '../db-manag
 import { type JudgmentAccess } from './judgments.js';
 import type { WorkGraphPage, WorkGraphQuery } from '../memory/judgment-types.js';
 import type { TwinEdgeRecord, TwinEdgeType, TwinProjectRef, TwinRef, TwinScopeRef } from '../knowledge/twin-edge-types.js';
+/** The reasons the host's evolution rules gave the legacy `decision_edges` rows they wrote. */
+export declare const HOST_EDGE_REASON_PREFIXES: readonly ["Semantically similar", "Updated fact", "Related but distinct"];
+/**
+ * The edges an agent stated between decisions, in the `decision_edges` columns plus `edge_id`:
+ * links in `twin_edges` between two memories that the host did not write, and the legacy
+ * `decision_edges` rows whose reason is not one the host gave. Search expansion follows these and
+ * no host edge (owner, 2026-09-30): a similarity is no ground that two records are the same case.
+ */
+export declare const STATED_DECISION_EDGES: string;
 /**
  * Walk a topic's supersedes chain with a recursive CTE.
  *
  * @param adapter - Database to read through
  * @param topic - Decision topic to query
  * @param anchorId - Start from this decision instead of the topic's current head
- * @returns Decisions ordered by recency, each carrying its approved edges
+ * @returns Decisions ordered by recency
  */
 export declare function queryDecisionGraph(adapter: DatabaseAdapter, topic: string, anchorId?: string): Promise<DecisionRecord[]>;
 /**

package/dist/knowledge/graph-query.js

@@ -11,7 +11,7 @@
  * @module knowledge/graph-query
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentGraphValidationError = void 0;
+exports.AgentGraphValidationError = exports.STATED_DECISION_EDGES = exports.HOST_EDGE_REASON_PREFIXES = void 0;
 exports.queryDecisionGraph = queryDecisionGraph;
 exports.querySemanticEdges = querySemanticEdges;
 exports.getGraphNeighborhood = getGraphNeighborhood;
@@ -44,13 +44,38 @@ function parseRefinedFrom(decision) {
         throw new Error(`decision ${decision.id} has unreadable refined_from: ${message}`);
     }
 }
+/** The reasons the host's evolution rules gave the legacy `decision_edges` rows they wrote. */
+exports.HOST_EDGE_REASON_PREFIXES = [
+    'Semantically similar',
+    'Updated fact',
+    'Related but distinct',
+];
+/**
+ * The edges an agent stated between decisions, in the `decision_edges` columns plus `edge_id`:
+ * links in `twin_edges` between two memories that the host did not write, and the legacy
+ * `decision_edges` rows whose reason is not one the host gave. Search expansion follows these and
+ * no host edge (owner, 2026-09-30): a similarity is no ground that two records are the same case.
+ */
+exports.STATED_DECISION_EDGES = `(
+  SELECT NULL AS edge_id, from_id, to_id, relationship, reason, weight, created_at, created_by,
+         approved_by_user, decision_id, evidence
+    FROM decision_edges
+   WHERE ${exports.HOST_EDGE_REASON_PREFIXES.map((prefix) => `COALESCE(reason, '') NOT LIKE '${prefix}%'`).join(' AND ')}
+  UNION ALL
+  SELECT edge_id, subject_id, object_id, edge_type,
+         COALESCE(json_extract(relation_attrs_json, '$.reason'), reason_text), confidence,
+         created_at, source, NULL, NULL, NULL
+    FROM twin_edges
+   WHERE subject_kind = 'memory' AND object_kind = 'memory' AND source <> 'code'
+     AND edge_type <> 'derived_from'
+)`;
 /**
  * Walk a topic's supersedes chain with a recursive CTE.
  *
  * @param adapter - Database to read through
  * @param topic - Decision topic to query
  * @param anchorId - Start from this decision instead of the topic's current head
- * @returns Decisions ordered by recency, each carrying its approved edges
+ * @returns Decisions ordered by recency
  */
 async function queryDecisionGraph(adapter, topic, anchorId) {
     try {
@@ -66,13 +91,7 @@ async function queryDecisionGraph(adapter, topic, anchorId) {
           SELECT * FROM decision_chain ORDER BY created_at DESC, id DESC
         `)
                 .all(topic);
-            const edgesStmt = adapter.prepare(`
-        SELECT * FROM decision_edges
-        WHERE from_id = ?
-          AND (approved_by_user = 1 OR approved_by_user IS NULL)
-      `);
             for (const decision of decisions) {
-                decision.edges = edgesStmt.all(decision.id);
                 decision.refined_from = parseRefinedFrom(decision);
             }
             return decisions;
@@ -96,15 +115,7 @@ async function queryDecisionGraph(adapter, topic, anchorId) {
       ORDER BY created_at DESC
     `);
         const decisions = stmt.all(anchorId);
-        // Join with decision_edges to include relationships
-        // Prepare statement once outside loop for performance
-        const edgesStmt = adapter.prepare(`
-      SELECT * FROM decision_edges
-      WHERE from_id = ?
-        AND (approved_by_user = 1 OR approved_by_user IS NULL)
-    `);
         for (const decision of decisions) {
-            decision.edges = edgesStmt.all(decision.id);
             decision.refined_from = parseRefinedFrom(decision);
         }
         return decisions;
@@ -146,7 +157,7 @@ async function querySemanticEdges(adapter, decisionIds) {
         // Query outgoing edges (from_id = decision)
         const outgoingStmt = adapter.prepare(`
       SELECT e.*, d.topic, d.decision, d.confidence, d.created_at
-      FROM decision_edges e
+      FROM ${exports.STATED_DECISION_EDGES} e
       JOIN decisions d ON e.to_id = d.id
       WHERE e.from_id IN (${placeholders})
         AND e.relationship IN (${edgeTypePlaceholders})
@@ -157,7 +168,7 @@ async function querySemanticEdges(adapter, decisionIds) {
         // Query incoming edges (to_id = decision)
         const incomingStmt = adapter.prepare(`
       SELECT e.*, d.topic, d.decision, d.confidence, d.created_at
-      FROM decision_edges e
+      FROM ${exports.STATED_DECISION_EDGES} e
       JOIN decisions d ON e.from_id = d.id
       WHERE e.to_id IN (${placeholders})
         AND e.relationship IN (${edgeTypePlaceholders})
@@ -547,6 +558,29 @@ function loadTimelineRecordEvent(adapter, ref) {
     }
     return null;
 }
+/**
+ * Edges as the reader may see them. Both ends being visible does not make a link's evidence
+ * visible, so evidence refs the reader cannot see are left out. Entries without a kind are the
+ * link entries ({id, reason}) an earlier version copied into a record's own edges; they repeat the
+ * edge's target and reason.
+ */
+function withVisibleEvidence(adapter, edges, visibility) {
+    const refsOf = (edge) => Array.isArray(edge.evidence_refs)
+        ? edge.evidence_refs.filter((ref) => typeof ref?.id === 'string' &&
+            twin_edge_types_js_1.TWIN_REF_KINDS.includes(ref.kind))
+        : [];
+    const visible = (0, access_js_1.visibleTwinRefKeysRecursive)(adapter, edges.flatMap(refsOf), visibility);
+    return edges.map((edge) => {
+        if (!Array.isArray(edge.evidence_refs))
+            return edge;
+        const evidence = refsOf(edge).filter((ref) => visible.has(`${ref.kind}\0${ref.id}`));
+        return {
+            ...edge,
+            evidence_refs: evidence.length > 0 ? evidence : null,
+            evidence_refs_json: evidence.length > 0 ? JSON.stringify(evidence) : null,
+        };
+    });
+}
 function getGraphNeighborhood(adapter, input) {
     const depth = normalizeDepth(input.depth, 1);
     const limit = normalizeLimit(input.limit, DEFAULT_GRAPH_LIMIT);
@@ -598,7 +632,11 @@ function getGraphNeighborhood(adapter, input) {
         }
         frontier = nextFrontier;
     }
-    return { nodes, edges, current_projection: projectCurrentEdges(adapter, edges, visibility) };
+    return {
+        nodes,
+        edges: withVisibleEvidence(adapter, edges, { ...visibility, asOfMs: input.as_of_ms }),
+        current_projection: projectCurrentEdges(adapter, edges, visibility),
+    };
 }
 function getGraphPaths(adapter, input) {
     const maxDepth = normalizeDepth(input.max_depth, 3);
@@ -665,8 +703,12 @@ function getGraphPaths(adapter, input) {
     const pathEdges = [
         ...new Map(paths.flatMap((path) => path.edges).map((edge) => [edge.edge_id, edge])).values(),
     ];
+    const shown = new Map(withVisibleEvidence(adapter, pathEdges, visibility).map((edge) => [edge.edge_id, edge]));
     return {
-        paths,
+        paths: paths.map((path) => ({
+            ...path,
+            edges: path.edges.map((edge) => shown.get(edge.edge_id)),
+        })),
         limit_reached: limitReached || paths.length >= limit,
         current_projection: projectCurrentEdges(adapter, pathEdges, visibility),
     };
@@ -698,11 +740,11 @@ function getGraphTimeline(adapter, input) {
     const limit = normalizeLimit(input.limit, DEFAULT_GRAPH_LIMIT);
     const window = timelineWindow(input);
     const seeds = timelineSeeds(adapter, input.ref, visibility);
-    const edges = listFilteredEdges(adapter, seeds, {
+    const edges = withVisibleEvidence(adapter, listFilteredEdges(adapter, seeds, {
         visibility,
         edge_filters: input.edge_filters,
         as_of_ms: input.as_of_ms,
-    }).filter((edge) => isInTimelineWindow(edge.created_at, window));
+    }).filter((edge) => isInTimelineWindow(edge.created_at, window)), { ...visibility, asOfMs: input.as_of_ms });
     const refs = [];
     const seenRefs = new Set();
     for (const seed of seeds) {
@@ -765,6 +807,50 @@ function graphAccessInput(access) {
         max_source_ms: access.maxSourceMs,
     };
 }
+/**
+ * Later links that contradict an edge, each with its reason, and the links that contradict those:
+ * the edge row is never edited, so a correction is read from the edges that point at it.
+ */
+function edgeCorrections(adapter, edgeIds, visibility, asOfMs) {
+    const byTarget = new Map();
+    const seen = new Set(edgeIds);
+    let frontier = [...edgeIds];
+    while (frontier.length > 0) {
+        const placeholders = frontier.map(() => '?').join(', ');
+        const rows = adapter
+            .prepare(`SELECT edge_id, subject_kind, subject_id, object_id, reason_text, created_at
+           FROM twin_edges
+          WHERE object_kind = 'edge' AND edge_type = 'contradicts'
+            AND object_id IN (${placeholders}) AND created_at <= ?
+          ORDER BY created_at, edge_id`)
+            .all(...frontier, asOfMs);
+        const subjects = rows.map((row) => ({ kind: row.subject_kind, id: row.subject_id }));
+        const visible = (0, access_js_1.visibleTwinRefKeysRecursive)(adapter, subjects, visibility);
+        frontier = [];
+        for (const row of rows) {
+            if (!visible.has(`${row.subject_kind}\0${row.subject_id}`))
+                continue;
+            const list = byTarget.get(row.object_id) ?? [];
+            list.push({ edgeId: row.edge_id, reason: row.reason_text, at: row.created_at });
+            byTarget.set(row.object_id, list);
+            if (!seen.has(row.edge_id)) {
+                seen.add(row.edge_id);
+                frontier.push(row.edge_id);
+            }
+        }
+    }
+    const nest = (edgeId) => byTarget.get(edgeId)?.map((correction) => {
+        const further = nest(correction.edgeId);
+        return further ? { ...correction, correctedBy: further } : correction;
+    });
+    const corrections = new Map();
+    for (const edgeId of edgeIds) {
+        const list = nest(edgeId);
+        if (list)
+            corrections.set(edgeId, list);
+    }
+    return corrections;
+}
 /**
  * Name-free entry: registry alias, decisions FTS, observation metadata. Search
  * seeds are candidates, not citations — refs the caller cannot see are dropped
@@ -1127,8 +1213,9 @@ function hydrateNode(adapter, ref, ctx, access) {
     }
     return hydrateRecordNode(adapter, ref);
 }
-function pageEdgeAttrs(edge) {
+function pageEdgeAttrs(edge, correctedBy) {
     return {
+        ...(correctedBy?.length ? { corrected_by: correctedBy } : {}),
         edge_type: edge.edge_type,
         relation_attrs: (edge.relation_attrs ?? null),
         confidence: edge.confidence,
@@ -1137,6 +1224,7 @@ function pageEdgeAttrs(edge) {
         model_run_id: edge.model_run_id,
         reason_classification: edge.reason_classification,
         reason_text: edge.reason_text,
+        evidence_refs: (edge.evidence_refs ?? null),
         created_at: edge.created_at,
         content_hash: edge.content_hash.toString('hex'),
     };
@@ -1556,7 +1644,12 @@ function queryGraph(adapter, query, access) {
         nodes.sort((left, right) => (nodeOrder.get(`${left.ref.kind}:${left.ref.id}`) ?? Number.MAX_SAFE_INTEGER) -
             (nodeOrder.get(`${right.ref.kind}:${right.ref.id}`) ?? Number.MAX_SAFE_INTEGER));
     }
-    const pageEdges = collectedEdges.map((edge) => {
+    const corrections = edgeCorrections(adapter, collectedEdges.map((edge) => edge.edge_id), ctx.visibility, asOf);
+    const shownEdges = withVisibleEvidence(adapter, collectedEdges, {
+        ...ctx.visibility,
+        asOfMs: asOf,
+    });
+    const pageEdges = shownEdges.map((edge) => {
         const fromProjection = projections.get(projectionKey(edge.edge_id, 'from'));
         const toProjection = projections.get(projectionKey(edge.edge_id, 'to'));
         return {
@@ -1566,7 +1659,7 @@ function queryGraph(adapter, query, access) {
             to: edge.object_ref,
             resolvedFrom: fromProjection?.current_ref ?? edge.subject_ref,
             resolvedTo: toProjection?.current_ref ?? edge.object_ref,
-            attrs: pageEdgeAttrs(edge),
+            attrs: pageEdgeAttrs(edge, corrections.get(edge.edge_id)),
         };
     });
     return {