diff --git a/CLAUDE.md b/CLAUDE.md index e8de79249d..5268a1043d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -237,6 +237,12 @@ Auto-forget and retention release a Memory's image reference after its indexed d A failed release is logged without blocking deletion bookkeeping; it may leave an unused image. Concurrent deletion locking is outside this contract. +### Replace import +`mem::import` validates section shapes, size limits and keyed fields used by import indexing +before any store mutation. Rows without string keys are dropped and counted in `invalid`, so +legacy keyless Session stubs do not prevent restoring the rest. Access logs and legacy Memory +session IDs retain their normal normalization. This preflight does not make replacement transactional. + ### Graph Eviction Every path that hard-deletes Observations or Memories (`mem::evict`, `mem::observe` session-cap eviction, `mem::auto-forget`, `mem::forget`, `mem::retention-evict`, `mem::governance-delete`, diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index a4e10f28dd..b1981f00f6 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -103,6 +103,113 @@ function nonEmpty(rows: T[] | undefined): T[] | undefined { return rows && rows.length > 0 ? rows : undefined; } +const MAX_ACCESS_LOGS = 50_000; + +const KEYED_SECTIONS = [ + ["sessions", "id"], + ["memories", "id"], + ["summaries", "sessionId"], + ["graphNodes", "id"], + ["graphEdges", "id"], + ["semanticMemories", "id"], + ["proceduralMemories", "id"], + ["profiles", "project"], + ["signals", "id"], + ["facets", "id"], + ["lessons", "id"], + ["insights", "id"], +] as const; + +function isKeyedRow(row: unknown, key: string): boolean { + return ( + typeof row === "object" && + row !== null && + typeof (row as Record)[key] === "string" + ); +} + +// A replace import deletes every store before it writes, so a malformed +// section must fail first, leaving the store untouched. +function invalidImportSection(importData: ExportData): string | null { + for (const [section] of KEYED_SECTIONS) { + const rows: unknown = importData[section]; + if (rows != null && !Array.isArray(rows)) return `${section} must be an array`; + } + const accessLogs: unknown = importData.accessLogs; + if (accessLogs != null && !Array.isArray(accessLogs)) return "accessLogs must be an array"; + if (Array.isArray(accessLogs) && accessLogs.length > MAX_ACCESS_LOGS) { + return `Too many access logs (max ${MAX_ACCESS_LOGS})`; + } + return null; +} + +// A row without its key cannot be written (SQLite refuses an undefined key), +// so it is dropped rather than failing the import part way through. +function dropUnkeyedRows(importData: ExportData): number { + let dropped = 0; + const keep = (rows: T[], key: string): T[] => { + const kept = rows.filter((row) => isKeyedRow(row, key)); + dropped += rows.length - kept.length; + return kept; + }; + const sections = importData as unknown as Record; + for (const [section, key] of KEYED_SECTIONS) { + const rows = sections[section]; + if (rows) sections[section] = keep(rows, key); + } + for (const [sessionId, rows] of Object.entries(importData.observations)) { + importData.observations[sessionId] = keep(rows, "id"); + } + if (importData.accessLogs) { + const kept = importData.accessLogs.filter((row) => typeof row === "object" && row !== null); + dropped += importData.accessLogs.length - kept.length; + importData.accessLogs = kept; + } + return dropped; +} + +function invalidImportRow(data: ExportData): string | null { + const strings = (value: unknown) => Array.isArray(value) && value.every((item) => typeof item === "string"); + const optionalString = (value: unknown) => value == null || typeof value === "string"; + const checkIndexFields = (row: Record, fields: string[]): boolean => + fields.every((field) => strings(row[field])); + + for (const memory of data.memories) { + if (!isKeyedRow(memory, "id")) continue; + if (Array.isArray(memory.sessionIds) && !strings(memory.sessionIds)) return "memories.sessionIds must contain strings"; + if (memory.isLatest === false || !memory.title || !memory.content) continue; + if (typeof memory.title !== "string" || typeof memory.content !== "string" || + !optionalString(memory.createdAt) || !checkIndexFields(memory as unknown as Record, ["concepts", "files"])) { + return "memories contain invalid indexing fields"; + } + } + for (const rows of Object.values(data.observations)) { + for (const obs of rows) { + if (!isKeyedRow(obs, "id") || !obs.title || !obs.narrative) continue; + if (typeof obs.title !== "string" || typeof obs.narrative !== "string" || + !optionalString(obs.sessionId) || !optionalString(obs.timestamp) || + !optionalString(obs.subtitle) || !optionalString(obs.userPrompt) || + !checkIndexFields(obs as unknown as Record, ["facts", "concepts", "files"])) { + return "observations contain invalid indexing fields"; + } + } + } + for (const node of data.graphNodes ?? []) { + if (!isKeyedRow(node, "id")) continue; + if (!optionalString(node.name) || (node.sourceObservationIds != null && !strings(node.sourceObservationIds))) { + return "graphNodes contain invalid indexing fields"; + } + } + for (const edge of data.graphEdges ?? []) { + if (!isKeyedRow(edge, "id")) continue; + if (!optionalString(edge.sourceNodeId) || !optionalString(edge.targetNodeId) || + (edge.sourceObservationIds != null && !strings(edge.sourceObservationIds))) { + return "graphEdges contain invalid indexing fields"; + } + } + return null; +} + function oversizedExport(bytes: number): OversizedPayload { return { success: false, @@ -235,7 +342,6 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { const MAX_SUMMARIES = 10_000; const MAX_OBS_PER_SESSION = 5_000; const MAX_TOTAL_OBSERVATIONS = 500_000; - const MAX_ACCESS_LOGS = 50_000; if (!Array.isArray(importData.sessions)) { return { success: false, error: "sessions must be an array" }; @@ -300,6 +406,11 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { error: `Too many total observations (max ${MAX_TOTAL_OBSERVATIONS})`, }; } + const invalidSection = invalidImportSection(importData); + if (invalidSection) return { success: false, error: invalidSection }; + const invalidRow = invalidImportRow(importData); + if (invalidRow) return { success: false, error: invalidRow }; + const invalid = dropUnkeyedRows(importData); const stats = { sessions: 0, @@ -307,6 +418,7 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { memories: 0, summaries: 0, skipped: 0, + invalid, }; if (strategy === "replace") { @@ -553,15 +665,6 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { }); } if (importData.accessLogs) { - if (!Array.isArray(importData.accessLogs)) { - return { success: false, error: "accessLogs must be an array" }; - } - if (importData.accessLogs.length > MAX_ACCESS_LOGS) { - return { - success: false, - error: `Too many access logs (max ${MAX_ACCESS_LOGS})`, - }; - } const memoryIds = new Set( importData.memories.map((m) => m.id), ); diff --git a/test/export-import.test.ts b/test/export-import.test.ts index 66adec727d..7f7e172857 100644 --- a/test/export-import.test.ts +++ b/test/export-import.test.ts @@ -412,4 +412,85 @@ describe("Export/Import Functions", () => { expect(result.success).toBe(false); expect(result.error).toContain("Unsupported export version"); }); + + describe("replace leaves the store untouched when the file is invalid (#436)", () => { + const base = (): ExportData => ({ + version: VERSION, + exportedAt: "2026-03-01T00:00:00Z", + sessions: [], + observations: {}, + memories: [], + summaries: [], + }); + + it.each([ + ["accessLogs is not an array", { accessLogs: {} }], + ["lessons is not an array", { lessons: {} }], + ["insights is not an array", { insights: "x" }], + ["accessLogs exceeds its limit", { accessLogs: Array(50_001).fill({}) }], + ["memory content is not text", { memories: [{ ...testMemory, content: 42 }] }], + ["memory concepts contain a non-string", { memories: [{ ...testMemory, concepts: [null] }] }], + ["memory sessionIds contain a non-string", { memories: [{ ...testMemory, sessionIds: [3] }] }], + ["observation facts are not an array", { observations: { ses_2: [{ ...testObs, facts: {} }] } }], + ["observation narrative is not text", { observations: { ses_2: [{ ...testObs, narrative: 42 }] } }], + ["graph node provenance is malformed", { graphNodes: [{ id: "node", name: "Node", sourceObservationIds: [3] }] }], + ["graph edge endpoint is malformed", { graphEdges: [{ id: "edge", sourceNodeId: {}, targetNodeId: "node" }] }], + ])("%s", async (_label, patch) => { + const result = (await sdk.trigger("mem::import", { + exportData: { ...base(), ...patch }, + strategy: "replace", + })) as { success: boolean; error?: string }; + + expect(result.success).toBe(false); + expect(await kv.get("mem:sessions", "ses_1")).toEqual(testSession); + expect(await kv.get("mem:obs:ses_1", "obs_1")).not.toBeNull(); + expect(await kv.get("mem:memories", "mem_1")).not.toBeNull(); + expect(await kv.get("mem:summaries", "ses_1")).toEqual(testSummary); + }); + + it.each(["merge", "skip"] as const)("validates before writes with %s", async (strategy) => { + const result = await sdk.trigger("mem::import", { + exportData: { ...base(), sessions: [{ ...testSession, id: "new" }], memories: [{ ...testMemory, files: 5 }] }, + strategy, + }); + expect(result).toMatchObject({ success: false }); + expect(await kv.get("mem:sessions", "new")).toBeNull(); + expect(await kv.get("mem:memories", "mem_1")).toEqual(testMemory); + }); + + it.each(["merge", "skip", "replace"] as const)("keeps legacy normalization with %s", async (strategy) => { + const result = await sdk.trigger("mem::import", { + exportData: { + ...base(), + sessions: [{ status: "completed" }], + memories: [{ ...testMemory, id: "legacy", sessionIds: "old" }], + accessLogs: [{ memoryId: "legacy", count: "old", recent: [1, "old"] }], + }, + strategy, + }); + expect(result).toMatchObject({ success: true, invalid: 1 }); + expect(await kv.get("mem:memories", "legacy")).toMatchObject({ sessionIds: [] }); + expect(await kv.get("mem:access", "legacy")).toMatchObject({ count: 1, recent: [1] }); + }); + + it("drops rows without their key and restores the rest", async () => { + const keyless = { endedAt: "2026-09-22T01:02:26.889Z", status: "completed" }; + const result = (await sdk.trigger("mem::import", { + exportData: { + ...base(), + sessions: [keyless, { ...testSession, id: "ses_2" }], + observations: { ses_2: ["oops", { ...testObs, id: "obs_2", sessionId: "ses_2" }] }, + memories: [null, { ...testMemory, id: "mem_2" }], + lessons: [{ content: "no id" }], + }, + strategy: "replace", + })) as { success: boolean; invalid: number; sessions: number }; + + expect(result).toMatchObject({ success: true, invalid: 4, sessions: 1 }); + expect(await kv.get("mem:sessions", "ses_1")).toBeNull(); + expect(await kv.get("mem:sessions", "ses_2")).not.toBeNull(); + expect(await kv.get("mem:obs:ses_2", "obs_2")).not.toBeNull(); + expect(await kv.get("mem:memories", "mem_2")).not.toBeNull(); + }); + }); });