@oscharko-dev/keiko-server 0.2.0

package/dist/memory-conv-handlers.js

@@ -0,0 +1,369 @@
+// Issue #212 — Conversation Center memory BFF.
+//
+// Two routes that let the Conversation Center compose enterprise memory WITHOUT importing
+// any memory-domain package directly (ADR-0019 rule 8 keeps the browser/UI tier away from
+// the domain). Both routes go through the existing redactor (D9) before serialisation.
+//
+//   POST /api/memory/context
+//     Body: { projectPath, chatId, queryText?, types?, budgetTokens? }
+//     Returns the MemoryRetrievalResult envelope (contextBlock + included + omitted + budget).
+//     Wraps `retrieveMemoryContext` from keiko-memory-retrieval.
+//
+//   POST /api/memory/capture-from-conversation
+//     Body: { text, context: { projectPath, chatId } }
+//     Returns { outcomes: CaptureOutcome[] }. Calls keiko-memory-capture's
+//     `extractCandidatesFromUserText` and persists each `candidate` outcome as a `proposed`
+//     memory record via the shared `buildMemoryRecordFromProposal` builder so the existing
+//     /api/memory/proposals/:id/accept route from #211 can transition the proposal to accepted
+//     (issue #642).
+//
+// CSRF: enforced for POST methods by the server dispatch layer in server.ts. Handlers do
+// NOT re-check.
+//
+// File budget: keep under 400 LOC per coordinator quality rules.
+import { randomUUID } from "node:crypto";
+import { retrieveMemoryContext, } from "@oscharko-dev/keiko-memory-retrieval";
+import { extractCandidatesFromUserText, memoryTextEgressRejectionReason, } from "@oscharko-dev/keiko-memory-capture";
+import { MEMORY_TYPES } from "@oscharko-dev/keiko-contracts";
+import { errorBody } from "./routes.js";
+import { createMemoryTargetResolver } from "./memory-target-resolver.js";
+import { conversationMemoryScopes, resolveConversationMemoryContext, } from "./memory-conversation-context.js";
+import { recordMemoryAudit } from "./memory-audit-handler.js";
+import { buildMemoryRecordFromProposal } from "./memory-record-builders.js";
+import { enforcePersistableMemoryOutcome, isPersistableMemoryCandidate, memoryCapturePolicyForDeps, } from "./memory-capture-policy.js";
+import { buildConversationRetrievalSignals, conversationFusionMode, } from "./memory-retrieval-signals.js";
+// ─── Constants ────────────────────────────────────────────────────────────────
+const MAX_BODY_BYTES = 64_000;
+// ─── Body reading (mirrors memory-handlers.ts pattern) ────────────────────────
+class BodyTooLargeError extends Error {
+    constructor() {
+        super("request body too large");
+        this.name = "BodyTooLargeError";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        let capped = false;
+        req.on("data", (chunk) => {
+            total += chunk.length;
+            if (total > MAX_BODY_BYTES) {
+                if (!capped) {
+                    capped = true;
+                    chunks.length = 0;
+                    reject(new BodyTooLargeError());
+                    req.resume();
+                }
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => {
+            if (!capped)
+                resolve(Buffer.concat(chunks).toString("utf8"));
+        });
+        req.on("error", reject);
+    });
+}
+async function readJsonBody(req) {
+    let raw;
+    try {
+        raw = await readBody(req);
+    }
+    catch (err) {
+        if (err instanceof BodyTooLargeError) {
+            return { status: 413, body: errorBody("PAYLOAD_TOO_LARGE", "Request body too large.") };
+        }
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = raw.length === 0 ? {} : JSON.parse(raw);
+    }
+    catch {
+        return { status: 400, body: errorBody("BAD_REQUEST", "Request body is not valid JSON.") };
+    }
+    if (!isRecord(parsed)) {
+        return { status: 400, body: errorBody("BAD_REQUEST", "Request body must be a JSON object.") };
+    }
+    return parsed;
+}
+function isRouteResult(value) {
+    return isRecord(value) && typeof value.status === "number";
+}
+function resolveVault(deps) {
+    if (deps.memoryVault === undefined) {
+        return {
+            status: 503,
+            body: errorBody("MEMORY_UNAVAILABLE", "Memory vault is not configured."),
+        };
+    }
+    return deps.memoryVault;
+}
+// ─── /api/memory/context — request parsing ───────────────────────────────────
+function parseTypes(raw) {
+    if (raw === undefined)
+        return null;
+    if (!Array.isArray(raw))
+        return null;
+    const out = [];
+    for (const r of raw) {
+        if (typeof r !== "string" || !MEMORY_TYPES.includes(r)) {
+            return null;
+        }
+        out.push(r);
+    }
+    return out;
+}
+export function vaultAsQueryPort(vault) {
+    // Retrieval must see expired rows so it can omit them with a concrete suppression reason
+    // instead of having storage silently drop them. Archived/forgotten rows already come back
+    // from the vault by default and are suppressed later by the retrieval layer.
+    return {
+        listByScope: (scope, options) => {
+            const limit = options?.maxResults;
+            return vault.listMemoriesByScope(scope, {
+                includeExpired: true,
+                ...(limit === undefined ? {} : { limit }),
+            });
+        },
+        listOutgoingEdges: (memoryId) => vault.listOutgoingEdges(memoryId),
+        listIncomingEdges: (memoryId) => vault.listIncomingEdges(memoryId),
+    };
+}
+function parseRequiredString(raw, key) {
+    const value = raw[key];
+    if (typeof value === "string" && value.length > 0) {
+        return value;
+    }
+    return {
+        status: 400,
+        body: errorBody("BAD_REQUEST", `${key} must be a non-empty string.`),
+    };
+}
+function parseOptionalQueryText(raw) {
+    if (raw.queryText === undefined)
+        return undefined;
+    if (typeof raw.queryText !== "string") {
+        return {
+            status: 400,
+            body: errorBody("BAD_REQUEST", "queryText must be a string when provided."),
+        };
+    }
+    return raw.queryText;
+}
+function parseOptionalBudgetTokens(raw) {
+    if (raw.budgetTokens === undefined)
+        return undefined;
+    if (typeof raw.budgetTokens !== "number" ||
+        !Number.isFinite(raw.budgetTokens) ||
+        !Number.isInteger(raw.budgetTokens) ||
+        raw.budgetTokens < 0) {
+        return {
+            status: 400,
+            body: errorBody("BAD_REQUEST", "budgetTokens must be a non-negative integer."),
+        };
+    }
+    return raw.budgetTokens;
+}
+function parseContextInput(raw) {
+    const projectPath = parseRequiredString(raw, "projectPath");
+    if (isRouteResult(projectPath))
+        return projectPath;
+    const chatId = parseRequiredString(raw, "chatId");
+    if (isRouteResult(chatId))
+        return chatId;
+    const types = parseTypes(raw.types);
+    if (raw.types !== undefined && types === null) {
+        return {
+            status: 400,
+            body: errorBody("BAD_REQUEST", `types must be an array of: ${MEMORY_TYPES.join(", ")}.`),
+        };
+    }
+    const queryText = parseOptionalQueryText(raw);
+    if (isRouteResult(queryText))
+        return queryText;
+    const budgetTokens = parseOptionalBudgetTokens(raw);
+    if (isRouteResult(budgetTokens))
+        return budgetTokens;
+    return {
+        projectPath,
+        chatId,
+        queryText: queryText ?? undefined,
+        types: types ?? undefined,
+        budgetTokens: budgetTokens ?? undefined,
+    };
+}
+function buildRetrievalRequest(scopes, input, nowMs, signals, fusion) {
+    // exactOptionalPropertyTypes: omit undefined fields instead of assigning them.
+    const req = {
+        scopes,
+        nowMs,
+        fusion,
+    };
+    if (input.queryText !== undefined)
+        req.queryText = input.queryText;
+    if (input.types !== undefined)
+        req.types = input.types;
+    if (input.budgetTokens !== undefined)
+        req.budgetTokens = input.budgetTokens;
+    // Embedding-cosine (#204, O-F4), reinforcement (O-P1), and MMR-diversity (O-F3) signals, same as
+    // the chat path. Passed only when present so a vault with no embeddings / no access history ranks
+    // byte-identically.
+    if (signals.semanticById !== undefined)
+        req.semanticById = signals.semanticById;
+    if (signals.strengthById.size > 0)
+        req.strengthById = signals.strengthById;
+    if (signals.embeddingById.size > 0)
+        req.embeddingById = signals.embeddingById;
+    return req;
+}
+// Builds the embedding + reinforcement signals, runs scoped retrieval, and records the reinforcement
+// reflex — the same pipeline the chat path uses. Extracted so the route handler stays a thin
+// parse/dispatch/audit shell.
+async function retrieveConversationMemory(deps, vault, scopes, input) {
+    const port = vaultAsQueryPort(vault);
+    const nowMs = Date.now();
+    // Embedding egress gate (#204, O-F4): only send the query to the secondary embedding model when it
+    // is not secret-shaped — matching the chat path's safeForSecondaryModel guard.
+    const safeForSecondaryModel = input.queryText === undefined ||
+        memoryTextEgressRejectionReason(input.queryText, memoryCapturePolicyForDeps(deps)) === null;
+    const signals = await buildConversationRetrievalSignals(deps, vault, input.queryText, scopes, nowMs, safeForSecondaryModel);
+    const result = retrieveMemoryContext(buildRetrievalRequest(scopes, input, nowMs, signals, conversationFusionMode(deps)), port);
+    // Reinforcement reflex (#204, O-P1): every recall is an access, same as the chat path.
+    const accessedIds = result.included.map((item) => item.memoryId);
+    if (accessedIds.length > 0) {
+        vault.recordAccess(accessedIds, Date.now());
+    }
+    return result;
+}
+export async function handleMemoryRetrieveContext(ctx, deps) {
+    const vault = resolveVault(deps);
+    if (isRouteResult(vault))
+        return vault;
+    const body = await readJsonBody(ctx.req);
+    if (isRouteResult(body))
+        return body;
+    const input = parseContextInput(body);
+    if (isRouteResult(input))
+        return input;
+    const context = resolveConversationMemoryContext(deps, input.projectPath, input.chatId);
+    if (isRouteResult(context))
+        return context;
+    const scopes = conversationMemoryScopes(context);
+    const result = await retrieveConversationMemory(deps, vault, scopes, input);
+    if (result.included.length > 0) {
+        const event = {
+            schemaVersion: "1",
+            kind: "memory:retrieved",
+            eventId: randomUUID(),
+            occurredAt: Date.now(),
+            initiatorSurface: "conversation-center",
+            summary: result.included.length === 1
+                ? "Retrieved 1 memory for the conversation memory API."
+                : `Retrieved ${String(result.included.length)} memories for the conversation memory API.`,
+            scopes,
+            matchedMemoryIds: result.included.map((item) => item.memoryId),
+        };
+        recordMemoryAudit({ evidenceStore: deps.evidenceStore }, event);
+    }
+    // Redact the entire envelope (contextBlock.text, memory excerpts, inclusion reasons).
+    // We deliberately do NOT echo `result.request` back: it carries no fresh info beyond what
+    // the caller posted and bloats the wire payload.
+    return {
+        status: 200,
+        body: deps.redactor({
+            contextBlock: result.contextBlock,
+            included: result.included,
+            omitted: result.omitted,
+            budget: result.budget,
+        }),
+    };
+}
+function optionalId(raw, key) {
+    const value = raw[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function parseCaptureContext(raw) {
+    if (!isRecord(raw)) {
+        return {
+            status: 400,
+            body: errorBody("BAD_REQUEST", "context must be an object with projectPath and chatId."),
+        };
+    }
+    const projectPath = optionalId(raw, "projectPath");
+    const chatId = optionalId(raw, "chatId");
+    if (projectPath === undefined || chatId === undefined) {
+        return {
+            status: 400,
+            body: errorBody("BAD_REQUEST", "context.projectPath and context.chatId are required."),
+        };
+    }
+    return {
+        projectPath,
+        chatId,
+    };
+}
+function parseCaptureInput(raw) {
+    const text = typeof raw.text === "string" ? raw.text : "";
+    if (text.trim().length === 0) {
+        return { status: 400, body: errorBody("BAD_REQUEST", "text must be a non-empty string.") };
+    }
+    const context = parseCaptureContext(raw.context);
+    if (isRouteResult(context))
+        return context;
+    return {
+        text,
+        context,
+    };
+}
+function buildCaptureContext(input) {
+    // exactOptionalPropertyTypes — only set fields when present.
+    return {
+        userId: input.userId,
+        nowMs: Date.now(),
+        newMemoryId: () => randomUUID(),
+        newProposalId: () => randomUUID(),
+        workspaceId: input.workspaceId,
+        projectId: input.projectId,
+        conversationId: input.conversationId,
+    };
+}
+export async function handleMemoryCaptureFromConversation(ctx, deps) {
+    const vault = resolveVault(deps);
+    if (isRouteResult(vault))
+        return vault;
+    const body = await readJsonBody(ctx.req);
+    if (isRouteResult(body))
+        return body;
+    const input = parseCaptureInput(body);
+    if (isRouteResult(input))
+        return input;
+    const runtimeContext = resolveConversationMemoryContext(deps, input.context.projectPath, input.context.chatId);
+    if (isRouteResult(runtimeContext))
+        return runtimeContext;
+    const captureContext = buildCaptureContext(runtimeContext);
+    const outcomes = extractCandidatesFromUserText(input.text, captureContext, memoryCapturePolicyForDeps(deps, { resolver: createMemoryTargetResolver(vault) }));
+    // Issue #642: persist every candidate outcome as a `proposed` memory record so the
+    // /api/memory/proposals/:id/accept route can find it by the returned proposalId. Uses the
+    // shared `buildMemoryRecordFromProposal` builder for parity with chat-handlers.ts.
+    const persistableOutcomes = outcomes.map(enforcePersistableMemoryOutcome);
+    persistCandidateOutcomes(vault, persistableOutcomes);
+    // Redact every outcome (proposal bodies may carry user text that needs scrubbing).
+    return { status: 200, body: deps.redactor({ outcomes: persistableOutcomes }) };
+}
+function persistCandidateOutcomes(vault, outcomes) {
+    for (const outcome of outcomes) {
+        if (!isPersistableMemoryCandidate(outcome))
+            continue;
+        const proposalId = outcome.proposal.proposalId;
+        const record = buildMemoryRecordFromProposal(proposalId, outcome);
+        if (record !== null) {
+            vault.insertMemory(record);
+        }
+    }
+}

package/dist/memory-conversation-context.d.ts

@@ -0,0 +1,13 @@
+import type { ConversationId, MemoryScope, ProjectId, UserId, WorkspaceId } from "@oscharko-dev/keiko-contracts/memory";
+import type { UiHandlerDeps } from "./deps.js";
+import type { RouteResult } from "./routes.js";
+export declare const LOCAL_CONVERSATION_MEMORY_USER_ID: UserId;
+export interface ConversationMemoryRuntimeContext {
+    readonly userId: UserId;
+    readonly workspaceId: WorkspaceId;
+    readonly projectId: ProjectId;
+    readonly conversationId: ConversationId;
+}
+export declare function resolveConversationMemoryContext(deps: UiHandlerDeps, projectPath: string, chatId: string): ConversationMemoryRuntimeContext | RouteResult;
+export declare function conversationMemoryScopes(context: ConversationMemoryRuntimeContext): readonly MemoryScope[];
+//# sourceMappingURL=memory-conversation-context.d.ts.map

package/dist/memory-conversation-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-conversation-context.d.ts","sourceRoot":"","sources":["../src/memory-conversation-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EACX,SAAS,EACT,MAAM,EACN,WAAW,EACZ,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C,eAAO,MAAM,iCAAiC,EAAuB,MAAM,CAAC;AAE5E,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;CACzC;AAED,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,aAAa,EACnB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,gCAAgC,GAAG,WAAW,CAWhD;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,gCAAgC,GACxC,SAAS,WAAW,EAAE,CAOxB"}

package/dist/memory-conversation-context.js

@@ -0,0 +1,22 @@
+import { errorBody } from "./routes.js";
+export const LOCAL_CONVERSATION_MEMORY_USER_ID = "local-operator";
+export function resolveConversationMemoryContext(deps, projectPath, chatId) {
+    const chat = deps.store.listChats(projectPath).find((entry) => entry.id === chatId);
+    if (chat === undefined) {
+        return { status: 404, body: errorBody("NOT_FOUND", "Chat not found.") };
+    }
+    return {
+        userId: LOCAL_CONVERSATION_MEMORY_USER_ID,
+        workspaceId: projectPath,
+        projectId: projectPath,
+        conversationId: chat.id,
+    };
+}
+export function conversationMemoryScopes(context) {
+    return [
+        { kind: "workspace", workspaceId: context.workspaceId },
+        { kind: "project", projectId: context.projectId },
+        { kind: "user", userId: context.userId },
+        { kind: "global" },
+    ];
+}

package/dist/memory-diagnostics.d.ts

@@ -0,0 +1,29 @@
+import type { MemoryAuditEvent, MemoryScope, MemoryStatus } from "@oscharko-dev/keiko-contracts";
+import { MEMORY_STATUSES } from "@oscharko-dev/keiko-contracts";
+import type { EvidenceStore } from "@oscharko-dev/keiko-evidence";
+import type { MemoryVaultStore } from "@oscharko-dev/keiko-memory-vault";
+export interface MemoryScopeCount {
+    readonly scope: MemoryScope;
+    readonly count: number;
+}
+export type MemoryStatusHistogram = Readonly<Record<MemoryStatus, number>>;
+export interface MemoryDiagnostics {
+    readonly schemaVersion: "1";
+    readonly generatedAt: number;
+    readonly scopeCounts: readonly MemoryScopeCount[];
+    readonly statusHistogram: MemoryStatusHistogram;
+    readonly recentAuditEvents: readonly MemoryAuditEvent[];
+    readonly storagePath: string;
+}
+export interface ExportMemoryDiagnosticsOptions {
+    readonly vault: MemoryVaultStore;
+    readonly scopes: readonly MemoryScope[];
+    readonly evidenceStore: EvidenceStore;
+    readonly redactString: (input: string) => string;
+    readonly evidenceDir: string;
+    readonly lastNAuditEvents?: number;
+    readonly now?: () => number;
+}
+export declare function exportMemoryDiagnostics(options: ExportMemoryDiagnosticsOptions): MemoryDiagnostics;
+export { MEMORY_STATUSES };
+//# sourceMappingURL=memory-diagnostics.d.ts.map

package/dist/memory-diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-diagnostics.d.ts","sourceRoot":"","sources":["../src/memory-diagnostics.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AACjG,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAWzE,MAAM,WAAW,gBAAgB;IAG/B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;AAE3E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,aAAa,EAAE,GAAG,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAClD,QAAQ,CAAC,eAAe,EAAE,qBAAqB,CAAC;IAChD,QAAQ,CAAC,iBAAiB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAGjD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAEnC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAmFD,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,8BAA8B,GACtC,iBAAiB,CAkCnB;AAGD,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/memory-diagnostics.js

@@ -0,0 +1,122 @@
+// Memory diagnostics export (Epic #204, Issue #214).
+//
+// Builds a body-free snapshot of the local memory state suitable for support / debugging
+// without exfiltrating any user content. The snapshot carries:
+//
+//   - generatedAt           epoch ms when the snapshot was built
+//   - scopeCounts           total record count per requested scope (post-redaction key)
+//   - statusHistogram       record count per MemoryStatus across all scanned scopes
+//   - recentAuditEvents     last N audit events (already redacted at persist time)
+//   - storagePath           the configured evidence dir, run through redactString
+//
+// Hard invariants:
+//
+//   - The raw record body is NEVER serialised. There is no opt-in flag in this PR.
+//   - The raw payload is NEVER serialised either. The same rationale.
+//   - The storage path is run through the audit redactor in case a user-supplied path
+//     happens to contain a credential-shaped segment.
+//   - Audit event tail is sanitised again on export. Persist-time redaction remains the
+//     primary boundary, but diagnostics must stay non-leaking even if a local manifest is
+//     edited or produced by an older writer.
+//
+// This function does NOT mutate the vault. It only reads.
+import { MEMORY_STATUSES } from "@oscharko-dev/keiko-contracts";
+import { auditRunIdFor } from "./memory-audit-handler.js";
+import { auditEventTouchesScope, memoryScopeKey, sanitizeAuditEvent, sanitizeMemoryScope, } from "./memory-scope-sanitizer.js";
+// ─── Constants ────────────────────────────────────────────────────────────────
+const DEFAULT_AUDIT_EVENT_TAIL = 50;
+const MIN_AUDIT_EVENT_TAIL = 1;
+const MAX_AUDIT_EVENT_TAIL = 1000;
+// ─── Pure helpers ─────────────────────────────────────────────────────────────
+function emptyHistogram() {
+    const counts = {
+        proposed: 0,
+        accepted: 0,
+        rejected: 0,
+        superseded: 0,
+        archived: 0,
+        forgotten: 0,
+        conflicted: 0,
+        expired: 0,
+    };
+    return counts;
+}
+function clampTail(value) {
+    if (value === undefined || !Number.isFinite(value)) {
+        return DEFAULT_AUDIT_EVENT_TAIL;
+    }
+    const integer = Math.floor(value);
+    if (integer < MIN_AUDIT_EVENT_TAIL) {
+        return MIN_AUDIT_EVENT_TAIL;
+    }
+    if (integer > MAX_AUDIT_EVENT_TAIL) {
+        return MAX_AUDIT_EVENT_TAIL;
+    }
+    return integer;
+}
+// Pulls the most recent N audit events from today's manifest and (if today's is short)
+// continues into yesterday's manifest. Two-day window is deliberate: a longer window
+// would risk scanning the entire ledger; the diagnostics view exists for a "what just
+// happened?" support snapshot, not a full audit replay.
+function readRecentAuditEvents(store, nowMs, limit, allowedScopeKeys, redactString) {
+    const today = readAuditManifest(store, auditRunIdFor(nowMs))
+        .map((event) => sanitizeAuditEvent(event, redactString))
+        .filter((event) => auditEventTouchesScope(event, allowedScopeKeys));
+    if (today.length >= limit) {
+        return today.slice(today.length - limit);
+    }
+    const yesterday = readAuditManifest(store, auditRunIdFor(nowMs - 24 * 60 * 60 * 1000))
+        .map((event) => sanitizeAuditEvent(event, redactString))
+        .filter((event) => auditEventTouchesScope(event, allowedScopeKeys));
+    const combined = [...yesterday, ...today];
+    if (combined.length <= limit) {
+        return combined;
+    }
+    return combined.slice(combined.length - limit);
+}
+function readAuditManifest(store, runId) {
+    const json = store.get(runId);
+    if (json === undefined) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(json);
+        if (Array.isArray(parsed)) {
+            return parsed;
+        }
+        return [];
+    }
+    catch {
+        return [];
+    }
+}
+// ─── Public entry point ───────────────────────────────────────────────────────
+export function exportMemoryDiagnostics(options) {
+    const now = options.now ?? (() => Date.now());
+    const nowMs = now();
+    const histogram = emptyHistogram();
+    const sanitizedScopes = options.scopes.map((scope) => sanitizeMemoryScope(scope, options.redactString));
+    const allowedScopeKeys = new Set(sanitizedScopes.map((scope) => memoryScopeKey(scope)));
+    const scopeCounts = options.scopes.map((scope, index) => {
+        const records = options.vault.listMemoriesByScope(scope, { includeExpired: true });
+        for (const record of records) {
+            histogram[record.status] += 1;
+        }
+        return {
+            scope: sanitizedScopes[index] ?? sanitizeMemoryScope(scope, options.redactString),
+            count: records.length,
+        };
+    });
+    const tail = clampTail(options.lastNAuditEvents);
+    const recentAuditEvents = readRecentAuditEvents(options.evidenceStore, nowMs, tail, allowedScopeKeys, options.redactString);
+    return {
+        schemaVersion: "1",
+        generatedAt: nowMs,
+        scopeCounts,
+        statusHistogram: histogram,
+        recentAuditEvents,
+        storagePath: options.redactString(options.evidenceDir),
+    };
+}
+// Re-export the status list for callers that want to render a stable histogram order.
+export { MEMORY_STATUSES };

package/dist/memory-embedding.d.ts

@@ -0,0 +1,21 @@
+import { type GatewayConfig, type OpenAIEmbeddingOutcome, type OpenAIEmbeddingRequest } from "@oscharko-dev/keiko-model-gateway";
+import type { MemoryId, MemoryRecord } from "@oscharko-dev/keiko-contracts/memory";
+import type { MemoryEmbeddingInput, MemoryEmbeddingRow, MemoryVaultStore } from "@oscharko-dev/keiko-memory-vault";
+import { type UiHandlerDeps } from "./deps.js";
+export declare function selectMemoryEmbeddingModelId(config: GatewayConfig | undefined): string | undefined;
+export type MemoryEmbedder = (text: string) => Promise<MemoryEmbeddingInput | null>;
+export declare function createMemoryEmbedder(config: GatewayConfig | undefined, requestImpl: (request: OpenAIEmbeddingRequest) => Promise<OpenAIEmbeddingOutcome>): MemoryEmbedder | null;
+export declare function embedMemoryText(deps: UiHandlerDeps, text: string): Promise<MemoryEmbeddingInput | null>;
+export declare function embedAndStoreMemory(deps: UiHandlerDeps, vault: MemoryVaultStore, memoryId: MemoryId, text: string): Promise<void>;
+export declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+export declare const SEMANTIC_DEDUP_COSINE_THRESHOLD = 0.95;
+export declare function findSemanticDuplicate(candidate: MemoryEmbeddingInput | null, neighbors: ReadonlyMap<MemoryId, MemoryEmbeddingRow>, threshold?: number): MemoryId | null;
+export declare const RELATED_LINK_COSINE_THRESHOLD = 0.82;
+export declare const MAX_AUTO_LINKS = 3;
+export declare function findRelatedNeighbors(candidate: MemoryEmbeddingInput | null, neighbors: ReadonlyMap<MemoryId, MemoryEmbeddingRow>, lower?: number, upper?: number, maxLinks?: number): readonly MemoryId[];
+export interface NoveltyInsertResult {
+    readonly inserted: MemoryRecord | null;
+    readonly mergedInto: MemoryId | null;
+}
+export declare function insertSalienceMemoryWithNoveltyGate(deps: UiHandlerDeps, vault: MemoryVaultStore, record: MemoryRecord): Promise<NoveltyInsertResult>;
+//# sourceMappingURL=memory-embedding.d.ts.map

package/dist/memory-embedding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-embedding.d.ts","sourceRoot":"","sources":["../src/memory-embedding.ts"],"names":[],"mappings":"AAgBA,OAAO,EAEL,KAAK,aAAa,EAGlB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC5B,MAAM,mCAAmC,CAAC;AAE3C,OAAO,KAAK,EAEV,QAAQ,EACR,YAAY,EAEb,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAIrE,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,aAAa,GAAG,SAAS,GAChC,MAAM,GAAG,SAAS,CAEpB;AAyDD,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;AAKpF,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,WAAW,EAAE,CAAC,OAAO,EAAE,sBAAsB,KAAK,OAAO,CAAC,sBAAsB,CAAC,GAChF,cAAc,GAAG,IAAI,CAuBvB;AAKD,wBAAsB,eAAe,CACnC,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAItC;AAKD,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,gBAAgB,EACvB,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAQf;AAKD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,CAgBzE;AAiBD,eAAO,MAAM,+BAA+B,OAAO,CAAC;AAKpD,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,oBAAoB,GAAG,IAAI,EACtC,SAAS,EAAE,WAAW,CAAC,QAAQ,EAAE,kBAAkB,CAAC,EACpD,SAAS,GAAE,MAAwC,GAClD,QAAQ,GAAG,IAAI,CAYjB;AAeD,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAGlD,eAAO,MAAM,cAAc,IAAI,CAAC;AAMhC,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,oBAAoB,GAAG,IAAI,EACtC,SAAS,EAAE,WAAW,CAAC,QAAQ,EAAE,kBAAkB,CAAC,EACpD,KAAK,GAAE,MAAsC,EAC7C,KAAK,GAAE,MAAwC,EAC/C,QAAQ,GAAE,MAAuB,GAChC,SAAS,QAAQ,EAAE,CAWrB;AA+CD,MAAM,WAAW,mBAAmB;IAElC,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAEvC,QAAQ,CAAC,UAAU,EAAE,QAAQ,GAAG,IAAI,CAAC;CACtC;AAOD,wBAAsB,mCAAmC,CACvD,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,mBAAmB,CAAC,CAoB9B"}