@jungjaehoon/mama-core 2.4.1 → 4.1.0

package/dist/memory/bootstrap-builder.d.ts

@@ -1,3 +1,4 @@
+import type { DatabaseAdapter } from '../db-manager.js';
 import type { MemoryAgentBootstrap, MemoryScopeRef } from './types.js';
 interface BuildMemoryAgentBootstrapParams {
     scopes: MemoryScopeRef[];
@@ -5,6 +6,6 @@ interface BuildMemoryAgentBootstrapParams {
     currentGoal?: string;
     mainAgentState?: MemoryAgentBootstrap['main_agent_state'];
 }
-export declare function buildMemoryAgentBootstrap(params: BuildMemoryAgentBootstrapParams): Promise<MemoryAgentBootstrap>;
+export declare function buildMemoryAgentBootstrap(adapter: DatabaseAdapter, params: BuildMemoryAgentBootstrapParams): Promise<MemoryAgentBootstrap>;
 export {};
 //# sourceMappingURL=bootstrap-builder.d.ts.map

package/dist/memory/bootstrap-builder.js

@@ -6,16 +6,16 @@ const finding_store_js_1 = require("./finding-store.js");
 const profile_builder_js_1 = require("./profile-builder.js");
 const truth_store_js_1 = require("./truth-store.js");
 const channel_summary_store_js_1 = require("./channel-summary-store.js");
-async function buildMemoryAgentBootstrap(params) {
+async function buildMemoryAgentBootstrap(adapter, params) {
     const [truthRows, findings, recentEvents, channelSummary] = await Promise.all([
-        (0, truth_store_js_1.queryRelevantTruth)({
+        (0, truth_store_js_1.queryRelevantTruth)(adapter, {
             query: '',
             scopes: params.scopes,
             includeHistory: false,
         }),
-        (0, finding_store_js_1.listOpenAuditFindings)(),
-        (0, event_store_js_1.listRecentMemoryEvents)(10),
-        params.channelKey ? (0, channel_summary_store_js_1.getChannelSummary)(params.channelKey) : Promise.resolve(null),
+        (0, finding_store_js_1.listOpenAuditFindings)(adapter),
+        (0, event_store_js_1.listRecentMemoryEvents)(adapter, 10),
+        params.channelKey ? (0, channel_summary_store_js_1.getChannelSummary)(adapter, params.channelKey) : Promise.resolve(null),
     ]);
     const scopedTruth = truthRows.filter((row) => row.scope_refs.some((scopeRef) => params.scopes.some((scope) => scope.kind === scopeRef.kind && scope.id === scopeRef.id)));
     const profile = (0, profile_builder_js_1.classifyProfileEntries)(scopedTruth.map((row) => ({

package/dist/memory/channel-summary-state-store.d.ts

@@ -1,6 +1,7 @@
+import type { DatabaseAdapter } from '../db-manager.js';
 import type { ChannelSummaryStateRecord, MemoryAuditAck, MemoryScopeRef } from './types.js';
-export declare function getChannelSummaryState(channelKey: string): Promise<ChannelSummaryStateRecord | null>;
-export declare function recordChannelAudit(input: {
+export declare function getChannelSummaryState(adapter: DatabaseAdapter, channelKey: string): Promise<ChannelSummaryStateRecord | null>;
+export declare function recordChannelAudit(adapter: DatabaseAdapter, input: {
     channelKey: string;
     turnId: string;
     topic: string;

package/dist/memory/channel-summary-state-store.js

@@ -6,7 +6,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getChannelSummaryState = getChannelSummaryState;
 exports.recordChannelAudit = recordChannelAudit;
 const node_crypto_1 = __importDefault(require("node:crypto"));
-const db_manager_js_1 = require("../db-manager.js");
 const channel_summary_store_js_1 = require("./channel-summary-store.js");
 const event_store_js_1 = require("./event-store.js");
 const finding_store_js_1 = require("./finding-store.js");
@@ -143,9 +142,7 @@ function reduceState(previous, input) {
         state_hash: stateHash,
     };
 }
-async function getChannelSummaryState(channelKey) {
-    await (0, db_manager_js_1.initDB)();
-    const adapter = (0, db_manager_js_1.getAdapter)();
+async function getChannelSummaryState(adapter, channelKey) {
     const row = adapter
         .prepare(`
         SELECT channel_key, state_json, state_hash, updated_at
@@ -155,68 +152,73 @@ async function getChannelSummaryState(channelKey) {
         .get(channelKey);
     return row ? deserializeState(row) : null;
 }
-async function recordChannelAudit(input) {
-    await (0, db_manager_js_1.initDB)();
-    const adapter = (0, db_manager_js_1.getAdapter)();
+async function recordChannelAudit(adapter, input) {
     const timestamp = Date.now();
-    const legacySummary = await (0, channel_summary_store_js_1.getChannelSummary)(input.channelKey);
-    const previous = (await getChannelSummaryState(input.channelKey)) ??
+    const legacySummary = await (0, channel_summary_store_js_1.getChannelSummary)(adapter, input.channelKey);
+    const previous = (await getChannelSummaryState(adapter, input.channelKey)) ??
         (legacySummary
             ? createLegacySeedState(input.channelKey, legacySummary)
             : createEmptyState(input.channelKey));
-    const eventIds = [];
-    const findingIds = [];
     const eventType = input.ack.status === 'failed'
         ? 'audit_failed'
         : input.ack.action === 'no_op'
             ? 'no_op'
             : input.ack.action;
-    eventIds.push(await (0, event_store_js_1.appendMemoryEvent)({
-        event_type: eventType,
-        actor: 'memory_agent',
-        source_turn_id: input.turnId,
-        memory_id: input.savedMemories?.[0]?.id,
-        topic: input.topic,
-        scope_refs: input.scopeRefs,
-        reason: input.ack.reason,
-        created_at: timestamp,
-    }));
-    if (input.ack.status === 'failed') {
-        findingIds.push(await (0, finding_store_js_1.createAuditFinding)({
-            kind: 'unsupported_claim',
-            severity: 'high',
-            summary: input.ack.reason ?? `memory audit failed for ${input.topic}`,
-            evidence_refs: eventIds,
-            affected_memory_ids: input.savedMemories?.map((memory) => memory.id) ?? [],
-            recommended_action: 'consult_memory',
-        }));
-    }
     const state = reduceState(previous, {
         topic: input.topic,
         ack: input.ack,
         savedMemories: input.savedMemories,
         timestamp,
     });
-    adapter
-        .prepare(`
-        INSERT OR REPLACE INTO channel_summary_state (
-          channel_key,
-          state_json,
-          state_hash,
-          updated_at
-        )
-        VALUES (?, ?, ?, ?)
-      `)
-        .run(input.channelKey, JSON.stringify({
-        active_topic: state.active_topic,
-        active_decisions: state.active_decisions,
-        recent_milestones: state.recent_milestones,
-        recent_audit_outcomes: state.recent_audit_outcomes,
-    }), state.state_hash, timestamp);
-    await (0, channel_summary_store_js_1.upsertChannelSummary)({
-        channelKey: input.channelKey,
-        summaryMarkdown: renderChannelSummaryMarkdown(state),
-        deltaHash: state.state_hash,
+    // One audit produces an event, its finding, the reduced state and the legacy
+    // summary. Written separately, a failure after the first leaves an event whose
+    // finding never existed - a record asserting something with nothing behind it.
+    const { eventIds, findingIds } = adapter.transaction(() => {
+        const events = [];
+        const findings = [];
+        events.push((0, event_store_js_1.insertMemoryEventInTransaction)(adapter, {
+            event_type: eventType,
+            actor: 'memory_agent',
+            source_turn_id: input.turnId,
+            memory_id: input.savedMemories?.[0]?.id,
+            topic: input.topic,
+            scope_refs: input.scopeRefs,
+            reason: input.ack.reason,
+            created_at: timestamp,
+        }));
+        if (input.ack.status === 'failed') {
+            findings.push((0, finding_store_js_1.createAuditFinding)(adapter, {
+                kind: 'unsupported_claim',
+                severity: 'high',
+                summary: input.ack.reason ?? `memory audit failed for ${input.topic}`,
+                evidence_refs: events,
+                affected_memory_ids: input.savedMemories?.map((memory) => memory.id) ?? [],
+                recommended_action: 'consult_memory',
+            }));
+        }
+        adapter
+            .prepare(`
+          INSERT OR REPLACE INTO channel_summary_state (
+            channel_key,
+            state_json,
+            state_hash,
+            updated_at
+          )
+          VALUES (?, ?, ?, ?)
+        `)
+            .run(input.channelKey, JSON.stringify({
+            active_topic: state.active_topic,
+            active_decisions: state.active_decisions,
+            recent_milestones: state.recent_milestones,
+            recent_audit_outcomes: state.recent_audit_outcomes,
+        }), state.state_hash, timestamp);
+        (0, channel_summary_store_js_1.upsertChannelSummary)(adapter, {
+            channelKey: input.channelKey,
+            summaryMarkdown: renderChannelSummaryMarkdown(state),
+            deltaHash: state.state_hash,
+            updatedAt: timestamp,
+        });
+        return { eventIds: events, findingIds: findings };
     });
     return { eventIds, findingIds, state };
 }

package/dist/memory/channel-summary-store.d.ts

@@ -1,8 +1,10 @@
+import type { DatabaseAdapter } from '../db-manager.js';
 import type { ChannelSummaryRecord } from './types.js';
-export declare function upsertChannelSummary(input: {
+export declare function upsertChannelSummary(adapter: Pick<DatabaseAdapter, 'prepare'>, input: {
     channelKey: string;
     summaryMarkdown: string;
     deltaHash?: string;
-}): Promise<void>;
-export declare function getChannelSummary(channelKey: string): Promise<ChannelSummaryRecord | null>;
+    updatedAt?: number;
+}): void;
+export declare function getChannelSummary(adapter: DatabaseAdapter, channelKey: string): Promise<ChannelSummaryRecord | null>;
 //# sourceMappingURL=channel-summary-store.d.ts.map

package/dist/memory/channel-summary-store.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.upsertChannelSummary = upsertChannelSummary;
 exports.getChannelSummary = getChannelSummary;
-const db_manager_js_1 = require("../db-manager.js");
 function toChannelSummary(row) {
     return {
         channel_key: String(row.channel_key),
@@ -11,9 +10,7 @@ function toChannelSummary(row) {
         updated_at: Number(row.updated_at),
     };
 }
-async function upsertChannelSummary(input) {
-    await (0, db_manager_js_1.initDB)();
-    const adapter = (0, db_manager_js_1.getAdapter)();
+function upsertChannelSummary(adapter, input) {
     adapter
         .prepare(`
         INSERT OR REPLACE INTO channel_summaries (
@@ -24,11 +21,9 @@ async function upsertChannelSummary(input) {
         )
         VALUES (?, ?, ?, ?)
       `)
-        .run(input.channelKey, input.summaryMarkdown, input.deltaHash ?? null, Date.now());
+        .run(input.channelKey, input.summaryMarkdown, input.deltaHash ?? null, input.updatedAt ?? Date.now());
 }
-async function getChannelSummary(channelKey) {
-    await (0, db_manager_js_1.initDB)();
-    const adapter = (0, db_manager_js_1.getAdapter)();
+async function getChannelSummary(adapter, channelKey) {
     const row = adapter
         .prepare(`
         SELECT channel_key, summary_markdown, delta_hash, updated_at

package/dist/memory/dashboard-read.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Listings and rollups over the memory a caller may see.
+ *
+ * The dashboard asked these of the database directly: which decisions are
+ * active and going stale, what changed recently, which projects are busy, and
+ * what one project holds. They are reads, so they answer to the caller's
+ * scopes — the same join every other admitted read stands on. A principal that
+ * admits nothing gets empty lists rather than the whole file.
+ */
+import { type DatabaseAdapter } from '../db-manager.js';
+export interface DecisionListingRow {
+    id: string;
+    topic: string;
+    decision: string;
+    reasoning?: string | null;
+    status: string | null;
+    confidence?: number | null;
+    created_at: number;
+    updated_at: number;
+}
+export interface ProjectRollup {
+    project: string;
+    activeDecisions: number;
+    lastActivity: number;
+}
+export interface ReadScope {
+    kind: string;
+    id: string;
+}
+/**
+ * Recent or stale decisions under the admitted scopes.
+ *
+ * `order: 'stale'` puts the least recently touched first — what the dashboard
+ * calls an alert. `order: 'recent'` is the activity feed. `status` narrows to
+ * one lifecycle state when the caller names it.
+ */
+export declare function readDecisionListing(adapter: DatabaseAdapter, scopes: readonly ReadScope[], options?: {
+    status?: string;
+    order?: 'recent' | 'stale';
+    limit?: number;
+}): Promise<DecisionListingRow[]>;
+/** Per-project active-decision counts and last activity, over admitted scopes. */
+export declare function readProjectRollups(adapter: DatabaseAdapter, scopes: readonly ReadScope[]): Promise<ProjectRollup[]>;
+/** What one project holds, still bounded by what the caller admits. */
+export declare function readProjectDecisions(adapter: DatabaseAdapter, scopes: readonly ReadScope[], project: string, limit?: number): Promise<DecisionListingRow[]>;
+//# sourceMappingURL=dashboard-read.d.ts.map

package/dist/memory/dashboard-read.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readDecisionListing = readDecisionListing;
+exports.readProjectRollups = readProjectRollups;
+exports.readProjectDecisions = readProjectDecisions;
+/**
+ * Listings and rollups over the memory a caller may see.
+ *
+ * The dashboard asked these of the database directly: which decisions are
+ * active and going stale, what changed recently, which projects are busy, and
+ * what one project holds. They are reads, so they answer to the caller's
+ * scopes — the same join every other admitted read stands on. A principal that
+ * admits nothing gets empty lists rather than the whole file.
+ */
+const db_manager_js_1 = require("../db-manager.js");
+async function admittedScopeIds(adapter, scopes) {
+    return Promise.all(scopes.map((scope) => (0, db_manager_js_1.ensureMemoryScope)(adapter, scope.kind, scope.id)));
+}
+/**
+ * Recent or stale decisions under the admitted scopes.
+ *
+ * `order: 'stale'` puts the least recently touched first — what the dashboard
+ * calls an alert. `order: 'recent'` is the activity feed. `status` narrows to
+ * one lifecycle state when the caller names it.
+ */
+async function readDecisionListing(adapter, scopes, options = {}) {
+    if (scopes.length === 0) {
+        return [];
+    }
+    const scopeIds = await admittedScopeIds(adapter, scopes);
+    const placeholders = scopeIds.map(() => '?').join(', ');
+    const status = typeof options.status === 'string' ? options.status.trim() : '';
+    const direction = options.order === 'stale' ? 'ASC' : 'DESC';
+    const limit = Math.min(Math.max(Math.floor(options.limit ?? 50), 1), 200);
+    return (await adapter
+        .prepare(`SELECT DISTINCT d.id, d.topic, d.decision, d.reasoning, d.status, d.confidence,
+              d.created_at, d.updated_at
+       FROM decisions d
+       JOIN memory_scope_bindings msb ON msb.memory_id = d.id
+       WHERE msb.scope_id IN (${placeholders})
+       ${status ? 'AND d.status = ?' : ''}
+       ORDER BY d.updated_at ${direction}
+       LIMIT ?`)
+        .all(...scopeIds, ...(status ? [status] : []), limit));
+}
+/** Per-project active-decision counts and last activity, over admitted scopes. */
+async function readProjectRollups(adapter, scopes) {
+    if (scopes.length === 0) {
+        return [];
+    }
+    const scopeIds = await admittedScopeIds(adapter, scopes);
+    const placeholders = scopeIds.map(() => '?').join(', ');
+    return (await adapter
+        .prepare(`SELECT ms.external_id AS project,
+              COUNT(DISTINCT d.id) AS activeDecisions,
+              MAX(d.updated_at) AS lastActivity
+       FROM memory_scopes ms
+       JOIN memory_scope_bindings msb ON msb.scope_id = ms.id
+       JOIN decisions d ON d.id = msb.memory_id
+       WHERE ms.kind = 'project'
+         AND d.status = 'active'
+         AND EXISTS (
+               SELECT 1 FROM memory_scope_bindings admitted
+               WHERE admitted.memory_id = d.id AND admitted.scope_id IN (${placeholders})
+             )
+       GROUP BY ms.external_id
+       ORDER BY lastActivity DESC`)
+        .all(...scopeIds));
+}
+/** What one project holds, still bounded by what the caller admits. */
+async function readProjectDecisions(adapter, scopes, project, limit = 50) {
+    if (scopes.length === 0 || project.trim() === '') {
+        return [];
+    }
+    const scopeIds = await admittedScopeIds(adapter, scopes);
+    const placeholders = scopeIds.map(() => '?').join(', ');
+    const bounded = Math.min(Math.max(Math.floor(limit), 1), 200);
+    return (await adapter
+        .prepare(`SELECT DISTINCT d.id, d.topic, d.decision, d.reasoning, d.status, d.confidence,
+              d.created_at, d.updated_at
+       FROM decisions d
+       JOIN memory_scope_bindings msb ON msb.memory_id = d.id
+       JOIN memory_scopes ms ON ms.id = msb.scope_id
+       WHERE ms.kind = 'project'
+         AND ms.external_id = ?
+         AND EXISTS (
+               SELECT 1 FROM memory_scope_bindings admitted
+               WHERE admitted.memory_id = d.id AND admitted.scope_id IN (${placeholders})
+             )
+       ORDER BY d.updated_at DESC
+       LIMIT ?`)
+        .all(project, ...scopeIds, bounded));
+}
+//# sourceMappingURL=dashboard-read.js.map

package/dist/memory/event-store.d.ts

@@ -1,7 +1,7 @@
 import type { DatabaseAdapter } from '../db-manager.js';
 import type { MemoryEventRecord } from './types.js';
-export declare function appendMemoryEvent(input: Omit<MemoryEventRecord, 'event_id'>): Promise<string>;
+export declare function appendMemoryEvent(adapter: DatabaseAdapter, input: Omit<MemoryEventRecord, 'event_id'>): Promise<string>;
 export declare function insertMemoryEventInTransaction(adapter: Pick<DatabaseAdapter, 'prepare'>, input: Omit<MemoryEventRecord, 'event_id'>): string;
-export declare function listMemoryEventsForMemory(memoryId: string): Promise<MemoryEventRecord[]>;
-export declare function listRecentMemoryEvents(limit?: number): Promise<MemoryEventRecord[]>;
+export declare function listMemoryEventsForMemory(adapter: Pick<DatabaseAdapter, 'prepare'>, memoryId: string): Promise<MemoryEventRecord[]>;
+export declare function listRecentMemoryEvents(adapter: Pick<DatabaseAdapter, 'prepare'>, limit?: number): Promise<MemoryEventRecord[]>;
 //# sourceMappingURL=event-store.d.ts.map

package/dist/memory/event-store.js

@@ -8,7 +8,6 @@ exports.insertMemoryEventInTransaction = insertMemoryEventInTransaction;
 exports.listMemoryEventsForMemory = listMemoryEventsForMemory;
 exports.listRecentMemoryEvents = listRecentMemoryEvents;
 const node_crypto_1 = __importDefault(require("node:crypto"));
-const db_manager_js_1 = require("../db-manager.js");
 function deserializeEvent(row) {
     return {
         event_id: String(row.event_id),
@@ -27,9 +26,7 @@ function deserializeEvent(row) {
         created_at: Number(row.created_at),
     };
 }
-async function appendMemoryEvent(input) {
-    await (0, db_manager_js_1.initDB)();
-    const adapter = (0, db_manager_js_1.getAdapter)();
+async function appendMemoryEvent(adapter, input) {
     return insertMemoryEventInTransaction(adapter, input);
 }
 function insertMemoryEventInTransaction(adapter, input) {
@@ -45,9 +42,7 @@ function insertMemoryEventInTransaction(adapter, input) {
         .run(eventId, input.event_type, input.actor, input.source_turn_id ?? null, input.memory_id ?? null, input.topic ?? null, JSON.stringify(input.scope_refs), input.evidence_refs ? JSON.stringify(input.evidence_refs) : null, input.reason ?? null, input.created_at);
     return eventId;
 }
-async function listMemoryEventsForMemory(memoryId) {
-    await (0, db_manager_js_1.initDB)();
-    const adapter = (0, db_manager_js_1.getAdapter)();
+async function listMemoryEventsForMemory(adapter, memoryId) {
     const rows = adapter
         .prepare(`
         SELECT event_id, event_type, actor, source_turn_id, memory_id, topic,
@@ -59,9 +54,7 @@ async function listMemoryEventsForMemory(memoryId) {
         .all(memoryId);
     return rows.map(deserializeEvent);
 }
-async function listRecentMemoryEvents(limit = 10) {
-    await (0, db_manager_js_1.initDB)();
-    const adapter = (0, db_manager_js_1.getAdapter)();
+async function listRecentMemoryEvents(adapter, limit = 10) {
     const rows = adapter
         .prepare(`
         SELECT event_id, event_type, actor, source_turn_id, memory_id, topic,

package/dist/memory/finding-store.d.ts

@@ -1,4 +1,5 @@
+import type { DatabaseAdapter } from '../db-manager.js';
 import type { AuditFindingRecord } from './types.js';
-export declare function createAuditFinding(input: Omit<AuditFindingRecord, 'finding_id' | 'status' | 'created_at' | 'resolved_at'>): Promise<string>;
-export declare function listOpenAuditFindings(): Promise<AuditFindingRecord[]>;
+export declare function createAuditFinding(adapter: Pick<DatabaseAdapter, 'prepare'>, input: Omit<AuditFindingRecord, 'finding_id' | 'status' | 'created_at' | 'resolved_at'>): string;
+export declare function listOpenAuditFindings(adapter: DatabaseAdapter): Promise<AuditFindingRecord[]>;
 //# sourceMappingURL=finding-store.d.ts.map

package/dist/memory/finding-store.js

@@ -6,7 +6,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createAuditFinding = createAuditFinding;
 exports.listOpenAuditFindings = listOpenAuditFindings;
 const node_crypto_1 = __importDefault(require("node:crypto"));
-const db_manager_js_1 = require("../db-manager.js");
 function safeParseJsonArray(value) {
     try {
         return JSON.parse(String(value));
@@ -31,9 +30,7 @@ function deserializeFinding(row) {
             : Number(row.resolved_at),
     };
 }
-async function createAuditFinding(input) {
-    await (0, db_manager_js_1.initDB)();
-    const adapter = (0, db_manager_js_1.getAdapter)();
+function createAuditFinding(adapter, input) {
     const findingId = `finding_${node_crypto_1.default.randomUUID().replace(/-/g, '')}`;
     adapter
         .prepare(`
@@ -46,9 +43,7 @@ async function createAuditFinding(input) {
         .run(findingId, input.kind, input.severity, input.summary, JSON.stringify(input.evidence_refs), JSON.stringify(input.affected_memory_ids), input.recommended_action, Date.now());
     return findingId;
 }
-async function listOpenAuditFindings() {
-    await (0, db_manager_js_1.initDB)();
-    const adapter = (0, db_manager_js_1.getAdapter)();
+async function listOpenAuditFindings(adapter) {
     const rows = adapter
         .prepare(`
         SELECT finding_id, kind, severity, summary, evidence_refs, affected_memory_ids,

package/dist/memory/graph-read.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The decision graph, as a caller may see it.
+ *
+ * The viewer drew this by reading `decisions` and `decision_edges` directly and
+ * embedding fifty rows in the HTTP process. Those are reads, and a read answers
+ * to the caller's scopes: every node here is a memory the caller's grant admits,
+ * every edge joins two such nodes, and the totals count the same admitted set.
+ * A principal that admits nothing sees an empty graph rather than the file.
+ */
+import { type DatabaseAdapter } from '../db-manager.js';
+export interface GraphReadNode {
+    id: string;
+    topic: string;
+    decision: string;
+    reasoning?: string | null;
+    outcome: string | null;
+    confidence: number | null;
+    created_at: number;
+}
+export interface GraphReadEdge {
+    from: string;
+    to: string;
+    relationship: string;
+    reason: string | null;
+}
+export interface GraphSimilarityEdge extends GraphReadEdge {
+    similarity: number;
+}
+export interface GraphScope {
+    kind: string;
+    id: string;
+}
+export declare function readGraphNodes(adapter: DatabaseAdapter, scopes: readonly GraphScope[], options?: {
+    limit?: number | null;
+    ids?: readonly string[];
+}): Promise<GraphReadNode[]>;
+export declare function readGraphEdges(adapter: DatabaseAdapter, scopes: readonly GraphScope[]): Promise<GraphReadEdge[]>;
+export declare function countGraphNodes(adapter: DatabaseAdapter, scopes: readonly GraphScope[]): Promise<number>;
+/**
+ * Similarity edges over the admitted set.
+ *
+ * This embeds a bounded window of admitted nodes and asks the vector index what
+ * each is near. It lives here rather than in an HTTP handler because that is
+ * where the embedder is — a door that embeds is a door that has opinions about
+ * what memory means.
+ */
+export declare function readGraphSimilarityEdges(adapter: DatabaseAdapter, scopes: readonly GraphScope[], options?: {
+    window?: number;
+    neighbors?: number;
+    threshold?: number;
+}): Promise<GraphSimilarityEdge[]>;
+//# sourceMappingURL=graph-read.d.ts.map

package/dist/memory/graph-read.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readGraphNodes = readGraphNodes;
+exports.readGraphEdges = readGraphEdges;
+exports.countGraphNodes = countGraphNodes;
+exports.readGraphSimilarityEdges = readGraphSimilarityEdges;
+/**
+ * The decision graph, as a caller may see it.
+ *
+ * The viewer drew this by reading `decisions` and `decision_edges` directly and
+ * embedding fifty rows in the HTTP process. Those are reads, and a read answers
+ * to the caller's scopes: every node here is a memory the caller's grant admits,
+ * every edge joins two such nodes, and the totals count the same admitted set.
+ * A principal that admits nothing sees an empty graph rather than the file.
+ */
+const db_manager_js_1 = require("../db-manager.js");
+const embedder_js_1 = require("../embedding/embedder.js");
+const search_js_1 = require("../knowledge/search.js");
+/** The admitted-node clause both a node read and an edge read stand on. */
+async function admittedScopeIds(adapter, scopes) {
+    return Promise.all(scopes.map((scope) => (0, db_manager_js_1.ensureMemoryScope)(adapter, scope.kind, scope.id)));
+}
+async function readGraphNodes(adapter, scopes, options = {}) {
+    if (scopes.length === 0) {
+        return [];
+    }
+    const scopeIds = await admittedScopeIds(adapter, scopes);
+    const scopePlaceholders = scopeIds.map(() => '?').join(', ');
+    const ids = options.ids ?? [];
+    const idClause = ids.length > 0 ? `AND d.id IN (${ids.map(() => '?').join(', ')})` : '';
+    const limit = options.limit ?? null;
+    const rows = (await adapter
+        .prepare(`SELECT DISTINCT d.id, d.topic, d.decision, d.reasoning, d.outcome, d.confidence, d.created_at
+       FROM decisions d
+       JOIN memory_scope_bindings msb ON msb.memory_id = d.id
+       WHERE msb.scope_id IN (${scopePlaceholders})
+       ${idClause}
+       ORDER BY d.created_at DESC
+       ${limit === null ? '' : 'LIMIT ?'}`)
+        .all(...scopeIds, ...ids, ...(limit === null ? [] : [limit])));
+    return rows;
+}
+async function readGraphEdges(adapter, scopes) {
+    if (scopes.length === 0) {
+        return [];
+    }
+    const scopeIds = await admittedScopeIds(adapter, scopes);
+    const placeholders = scopeIds.map(() => '?').join(', ');
+    // Both ends must be admitted: an edge to a memory this caller cannot read
+    // would disclose that it exists, which is the read the join is here to bound.
+    const rows = (await adapter
+        .prepare(`SELECT e.from_id, e.to_id, e.relationship, e.reason
+       FROM decision_edges e
+       WHERE EXISTS (
+               SELECT 1 FROM memory_scope_bindings b
+               WHERE b.memory_id = e.from_id AND b.scope_id IN (${placeholders})
+             )
+         AND EXISTS (
+               SELECT 1 FROM memory_scope_bindings b
+               WHERE b.memory_id = e.to_id AND b.scope_id IN (${placeholders})
+             )`)
+        .all(...scopeIds, ...scopeIds));
+    return rows.map((row) => ({
+        from: row.from_id,
+        to: row.to_id,
+        relationship: row.relationship,
+        reason: row.reason,
+    }));
+}
+async function countGraphNodes(adapter, scopes) {
+    if (scopes.length === 0) {
+        return 0;
+    }
+    const scopeIds = await admittedScopeIds(adapter, scopes);
+    const placeholders = scopeIds.map(() => '?').join(', ');
+    const row = (await adapter
+        .prepare(`SELECT COUNT(DISTINCT d.id) as count FROM decisions d
+       JOIN memory_scope_bindings msb ON msb.memory_id = d.id
+       WHERE msb.scope_id IN (${placeholders})`)
+        .get(...scopeIds));
+    return row?.count ?? 0;
+}
+/**
+ * Similarity edges over the admitted set.
+ *
+ * This embeds a bounded window of admitted nodes and asks the vector index what
+ * each is near. It lives here rather than in an HTTP handler because that is
+ * where the embedder is — a door that embeds is a door that has opinions about
+ * what memory means.
+ */
+async function readGraphSimilarityEdges(adapter, scopes, options = {}) {
+    const window = options.window ?? 50;
+    const neighbors = options.neighbors ?? 3;
+    const threshold = options.threshold ?? 0.7;
+    const nodes = await readGraphNodes(adapter, scopes, { limit: Math.max(window * 2, window) });
+    if (nodes.length < 2) {
+        return [];
+    }
+    const admitted = new Set(nodes.map((node) => node.id));
+    const seen = new Set();
+    const edges = [];
+    for (const node of nodes.slice(0, window)) {
+        const embedding = await (0, embedder_js_1.generateEmbedding)(`${node.topic} ${node.decision}`, 'query');
+        const similar = (await (0, search_js_1.vectorSearch)(adapter, embedding, neighbors, threshold));
+        for (const match of similar) {
+            // A neighbour the caller may not read is not an edge it may see.
+            if (match.id === node.id || !admitted.has(match.id)) {
+                continue;
+            }
+            const similarity = match.similarity ?? threshold;
+            if (similarity <= threshold) {
+                continue;
+            }
+            const key = [node.id, match.id].sort().join('|');
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            edges.push({
+                from: node.id,
+                to: match.id,
+                relationship: 'similar',
+                reason: null,
+                similarity,
+            });
+        }
+    }
+    return edges;
+}
+//# sourceMappingURL=graph-read.js.map