From ddfbea797b07cd3639b173bd33e3fd08c7e49b23 Mon Sep 17 00:00:00 2001 From: neal Date: Tue, 22 Sep 2026 20:51:17 -0400 Subject: [PATCH 1/2] docs(export-import): drop stale iii 180s timeout rationale from IMPORT_CHUNK_SIZE ADR 0001 says any remaining iii-derived ceiling is a defect. The constant stands on its own (per-chunk fan-out, ~20x wallclock); only the timeout sentence was stale. .env.example already matches the post-#45 defaults. Closes #51 Generated-By: Claude Fable 5.1 --- src/functions/export-import.ts | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index 8fc0e42797..a40d3ddc92 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -45,9 +45,8 @@ import { logger } from "../logger.js"; // Bounded-concurrency chunk size for the import delete/write loops. A // "replace" or "merge" of a large export (up to MAX_TOTAL_OBSERVATIONS, // ~500k) would otherwise issue hundreds of thousands of sequential state -// round-trips and blow the 180s function timeout, leaving partial state. -// 20 keeps per-chunk fan-out low enough not to overwhelm the state -// backend while collapsing wallclock by ~20x versus the serial path. +// round-trips. 20 keeps per-chunk fan-out low enough not to overwhelm the +// state backend while collapsing wallclock by ~20x versus the serial path. const IMPORT_CHUNK_SIZE = 20; // Run `fn` over `items` in fixed-size chunks, awaiting each chunk before From c6ece2e0fbcff359a49d97cb2d3b913f32594eb6 Mon Sep 17 00:00:00 2001 From: neal Date: Sat, 3 Oct 2026 15:21:45 -0400 Subject: [PATCH 2/2] docs(export-import): state only what IMPORT_CHUNK_SIZE bounds on the in-process Engine State is synchronous node:sqlite with no invocation timeout and no remote backend, so the fan-out and ~20x wallclock claims do not hold here. Generated-By: Claude Opus 5.5 (1M context) --- src/functions/export-import.ts | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index 75ee46c071..148a3f39da 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -41,11 +41,9 @@ import { deleteIndexed, indexRecords } from "./search.js"; import { resetLessonIndex } from "./lessons.js"; import { logger } from "../logger.js"; -// Bounded-concurrency chunk size for the import delete/write loops. A -// "replace" or "merge" of a large export (up to MAX_TOTAL_OBSERVATIONS, -// ~500k) would otherwise issue hundreds of thousands of sequential state -// round-trips. 20 keeps per-chunk fan-out low enough not to overwhelm the -// state backend while collapsing wallclock by ~20x versus the serial path. +// Chunk size for the import delete/write loops. An import can touch up to +// MAX_TOTAL_OBSERVATIONS (~500k) records; chunking caps how many State +// calls are in flight per step instead of creating one promise per record. const IMPORT_CHUNK_SIZE = 20; // Run `fn` over `items` in fixed-size chunks, awaiting each chunk before