@gobing-ai/ts-llm-jsonl-importer 0.4.59 → 0.4.60

package/README.md

@@ -69,6 +69,32 @@ values, same `ImportResult`).
 When `readFileStream` is unavailable (e.g. Cloudflare Workers), the importer falls back to
 `readFile` + split transparently.
 
+## Cancellation
+
+Both entry points accept a cooperative `signal` (`AbortSignal`, feature A21 / ADR-112):
+
+```ts
+const controller = new AbortController();
+const resultPromise = runJsonlImport('codex', {
+    db,
+    roots: ['./agent-history'],
+    mode: 'incremental',
+    signal: controller.signal,
+});
+controller.abort(); // cancel from a watchdog, shutdown hook, or deadline
+```
+
+Cancellation is cooperative: the signal is checked at safe boundaries — before schema and
+checkpoint writes, before each source file, and between bounded batches — never inside a
+transaction. A batch already in flight settles first (its record, ledger, and checkpoint writes
+commit atomically), then the run rejects with `ImportCancelledError` (a `HistoryImportError`).
+No invocation-owned write happens after settlement, and incremental resume continues from the
+last committed checkpoint; a cancelled mid-file run never arms the file-identity short-circuit.
+`runOpenCodeImport` discards queued-but-unissued operations when cancelled, so the OpenCode
+store stays authoritative for the next run. A cancellation cannot interrupt a synchronous SQLite
+call mid-flight — the containing process remains the hard fallback for blocking work. Omitting
+`signal` preserves existing behavior.
+
 ## Import Specific Files
 
 ```ts

package/dist/cancellation.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Cooperative cancellation boundary (feature A21 / ADR-112). Call it only at safe
+ * boundaries — before starting further asynchronous work or writes — so any in-flight
+ * batch settles first and the public promise can never reject ahead of its own writes.
+ * Synchronous SQLite work cannot be interrupted here; the containing process remains
+ * the hard fallback for blocking work.
+ */
+export declare function throwIfImportAborted(signal: AbortSignal | undefined): void;
+//# sourceMappingURL=cancellation.d.ts.map

package/dist/cancellation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancellation.d.ts","sourceRoot":"","sources":["../src/cancellation.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,IAAI,CAI1E"}

package/dist/cancellation.js

@@ -0,0 +1,13 @@
+import { ImportCancelledError } from './errors.js';
+/**
+ * Cooperative cancellation boundary (feature A21 / ADR-112). Call it only at safe
+ * boundaries — before starting further asynchronous work or writes — so any in-flight
+ * batch settles first and the public promise can never reject ahead of its own writes.
+ * Synchronous SQLite work cannot be interrupted here; the containing process remains
+ * the hard fallback for blocking work.
+ */
+export function throwIfImportAborted(signal) {
+    if (signal?.aborted) {
+        throw new ImportCancelledError('Import cancelled by abort signal', signal.reason);
+    }
+}

package/dist/errors.d.ts

@@ -3,4 +3,14 @@ export declare class HistoryImportError extends Error {
     readonly details?: unknown | undefined;
     constructor(message: string, details?: unknown | undefined);
 }
+/**
+ * Error raised when a run is cancelled through its {@link ImportOptions.signal} abort signal
+ * (feature A21 / ADR-112). Thrown only after in-flight transaction and checkpoint work has
+ * settled, so catching it means "cancellation settled — no further writes from this
+ * invocation". Incremental resume continues from the last committed checkpoint.
+ */
+export declare class ImportCancelledError extends HistoryImportError {
+    readonly abortReason?: unknown | undefined;
+    constructor(message?: string, abortReason?: unknown | undefined);
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,qBAAa,kBAAmB,SAAQ,KAAK;IAGrC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO;gBAD1B,OAAO,EAAE,MAAM,EACN,OAAO,CAAC,EAAE,OAAO,YAAA;CAKjC"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,qBAAa,kBAAmB,SAAQ,KAAK;IAGrC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO;gBAD1B,OAAO,EAAE,MAAM,EACN,OAAO,CAAC,EAAE,OAAO,YAAA;CAKjC;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,kBAAkB;IAGpD,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO;gBAD9B,OAAO,SAAqC,EACnC,WAAW,CAAC,EAAE,OAAO,YAAA;CAKrC"}

package/dist/errors.js

@@ -7,3 +7,17 @@ export class HistoryImportError extends Error {
         this.name = 'HistoryImportError';
     }
 }
+/**
+ * Error raised when a run is cancelled through its {@link ImportOptions.signal} abort signal
+ * (feature A21 / ADR-112). Thrown only after in-flight transaction and checkpoint work has
+ * settled, so catching it means "cancellation settled — no further writes from this
+ * invocation". Incremental resume continues from the last committed checkpoint.
+ */
+export class ImportCancelledError extends HistoryImportError {
+    abortReason;
+    constructor(message = 'Import cancelled by abort signal', abortReason) {
+        super(message, abortReason);
+        this.abortReason = abortReason;
+        this.name = 'ImportCancelledError';
+    }
+}

package/dist/importer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"importer.d.ts","sourceRoot":"","sources":["../src/importer.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAER,aAAa,EACb,YAAY,EAGZ,gBAAgB,EAEnB,MAAM,SAAS,CAAC;AAoFjB;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CA2YrH"}
+{"version":3,"file":"importer.d.ts","sourceRoot":"","sources":["../src/importer.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAER,aAAa,EACb,YAAY,EAGZ,gBAAgB,EAEnB,MAAM,SAAS,CAAC;AAoFjB;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CA8ZrH"}

package/dist/importer.js

@@ -1,4 +1,5 @@
 import { ambientRuntimePaths, createNodeFileSystem, resolvePath, walkDir, } from '@gobing-ai/ts-runtime';
+import { throwIfImportAborted } from './cancellation.js';
 import { sha256 } from './hash.js';
 import { applyHistoryImportSchema, checkpointUpsertOp, codexUsageAttributionUpdateOp, ensureTargetTable, ledgerExistingHashes, ledgerInsertOp, loadSourceCheckpoints, reconcileFullImport, recordInsertOp, resetCheckpoints, targetTableFor, toolCallDurationUpdateOp, toolCallResultBytesUpdateOp, } from './jsonl-importer-dao.js';
 import { claudeToolResultTiming, ompToolResultTiming, timestampToEpochMs } from './mappers.js';
@@ -48,12 +49,18 @@ function attachableDuration(timing, messageTsMs) {
  * @param options - Importer options (database, roots/files, mode, etc.).
  */
 export async function runJsonlImport(source, options) {
+    // Cancellation boundary (feature A21): before ANY invocation-owned write, including the
+    // schema setup below. An already-aborted signal must leave the database untouched.
+    throwIfImportAborted(options.signal);
     const definition = resolveSourceDefinition(source);
     const resolvedSource = definition.source;
     const fileSystem = options.fileSystem ?? createNodeFileSystem();
     await applyHistoryImportSchema(options.db);
     const mode = options.mode ?? 'incremental';
     const files = await discoverFiles(definition, options.roots, options.files, fileSystem, options.paths);
+    // Cancellation boundary: file discovery can walk many roots; a signal firing during it
+    // must stop before the full-mode checkpoint reset (an invocation-owned write).
+    throwIfImportAborted(options.signal);
     if (mode === 'full' && !options.dryRun) {
         await resetCheckpoints(options.db, resolvedSource, files);
     }
@@ -80,6 +87,8 @@ export async function runJsonlImport(source, options) {
     // Only incremental mode consults checkpoints; full/force-file read everything.
     const checkpoints = mode === 'incremental' ? await loadSourceCheckpoints(options.db, resolvedSource) : undefined;
     for (const file of files) {
+        // Cancellation boundary: stop before starting another file's work.
+        throwIfImportAborted(options.signal);
         const entry = checkpoints?.get(file);
         const checkpoint = entry?.line ?? 0;
         if (checkpoints !== undefined && entry !== undefined && entry.size !== null && entry.mtimeMs !== null) {
@@ -93,6 +102,10 @@ export async function runJsonlImport(source, options) {
         }
         let lineNumber = 0;
         for await (const rawLine of readLines(fileSystem, file)) {
+            // Cancellation boundary between bounded per-line batches: a batch already in
+            // flight settled above (its record + ledger + checkpoint writes commit
+            // atomically), so rejecting here never leaves a partial line behind.
+            throwIfImportAborted(options.signal);
             lineNumber += 1;
             const line = rawLine.trim();
             if (line.length === 0 || lineNumber <= checkpoint)
@@ -310,31 +323,38 @@ export async function runJsonlImport(source, options) {
                     checkpointUpdates += 1;
                 }
             }
-            // 0675 R1/R4: stamp file identity once per READ file (never for skipped ones).
-            // This is also what self-heals legacy rows whose stored identity is NULL — without
-            // it a fully-imported database never arms the short-circuit. Skipped when nothing
-            // changed since the stored checkpoint to keep no-op runs write-free. Degraded
-            // entries (pre-migration database without identity columns, 0678 fail-open) keep
-            // the old line-only write shape via checkpointUpsertOp's optional identity.
-            if (!options.dryRun && mode === 'incremental') {
-                const statAfter = await safeStat(fileSystem, file);
-                // Degraded = a STORED entry without identity (pre-migration database, 0678
-                // fail-open). No stored entry means first-ever import: stamp normally.
-                const identityDegraded = entry !== undefined && entry.size === null && entry.mtimeMs === null;
-                const identityChanged = entry !== undefined &&
-                    (entry.size !== (statAfter?.size ?? null) || entry.mtimeMs !== (statAfter?.mtimeMs ?? null));
-                if (statAfter !== null && !identityDegraded && (entry === undefined || identityChanged)) {
-                    await options.db.batch([
-                        checkpointUpsertOp(resolvedSource, file, Math.max(lineNumber, checkpoint), options.now, {
-                            size: statAfter.size,
-                            mtimeMs: statAfter.mtimeMs,
-                        }),
-                    ]);
-                    checkpointUpdates += 1;
-                }
+        }
+        // 0675 R1/R4 (relocated from the per-line loop for feature A21): stamp file identity
+        // once per READ file, only after the file's line loop COMPLETED. A cancelled run
+        // throws at the per-line boundary above and must not arm the identity short-circuit:
+        // a mid-file checkpoint carrying full-file identity would make the next incremental
+        // run skip the whole file and silently lose the un-imported tail. "Once per read file
+        // (never for skipped ones)" is also what self-heals legacy rows whose stored identity
+        // is NULL — without a stamp a fully-imported database never arms the short-circuit.
+        // Skipped when nothing changed since the stored checkpoint to keep no-op runs
+        // write-free. Degraded entries (pre-migration database without identity columns,
+        // 0678 fail-open) keep the line-only write shape via checkpointUpsertOp's optional
+        // identity.
+        if (!options.dryRun && mode === 'incremental') {
+            const statAfter = await safeStat(fileSystem, file);
+            // Degraded = a STORED entry without identity (pre-migration database, 0678
+            // fail-open). No stored entry means first-ever import: stamp normally.
+            const identityDegraded = entry !== undefined && entry.size === null && entry.mtimeMs === null;
+            const identityChanged = entry !== undefined &&
+                (entry.size !== (statAfter?.size ?? null) || entry.mtimeMs !== (statAfter?.mtimeMs ?? null));
+            if (statAfter !== null && !identityDegraded && (entry === undefined || identityChanged)) {
+                await options.db.batch([
+                    checkpointUpsertOp(resolvedSource, file, Math.max(lineNumber, checkpoint), options.now, {
+                        size: statAfter.size,
+                        mtimeMs: statAfter.mtimeMs,
+                    }),
+                ]);
+                checkpointUpdates += 1;
             }
         }
     }
+    // Cancellation boundary: stop before the full-mode reconciliation deletes.
+    throwIfImportAborted(options.signal);
     let reconciliation;
     if (mode === 'full') {
         reconciliation = await reconcileFullImport(options.db, resolvedSource, desiredHashes, files, options.dryRun ?? false);

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { DERIVED_DURATION_CEILING_MS, type DeriveAssistantDurationsResult, DURATION_SOURCE_DERIVED, deriveAssistantDurations, } from './assistant-duration';
-export { HistoryImportError } from './errors';
+export { HistoryImportError, ImportCancelledError } from './errors';
 export { sha256, stableJson } from './hash';
 export { runJsonlImport } from './importer';
 export { applyHistoryImportSchema, normalizeSourceFilePaths, TYPED_HISTORY_TABLES } from './jsonl-importer-dao';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,2BAA2B,EAC3B,KAAK,8BAA8B,EACnC,uBAAuB,EACvB,wBAAwB,GAC3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAChH,OAAO,EACH,qBAAqB,EACrB,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,uBAAuB,EACvB,cAAc,GACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,KAAK,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,EAAE,uBAAuB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,yBAAyB,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AACxF,OAAO,EACH,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,wBAAwB,GAC3B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAC7E,YAAY,EACR,cAAc,EACd,WAAW,EACX,UAAU,EACV,aAAa,EACb,YAAY,EACZ,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,SAAS,EACT,oBAAoB,EACpB,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,gBAAgB,GACnB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,2BAA2B,EAC3B,KAAK,8BAA8B,EACnC,uBAAuB,EACvB,wBAAwB,GAC3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AACpE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAChH,OAAO,EACH,qBAAqB,EACrB,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,uBAAuB,EACvB,cAAc,GACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,KAAK,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,EAAE,uBAAuB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,yBAAyB,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AACxF,OAAO,EACH,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,wBAAwB,GAC3B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAC7E,YAAY,EACR,cAAc,EACd,WAAW,EACX,UAAU,EACV,aAAa,EACb,YAAY,EACZ,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,SAAS,EACT,oBAAoB,EACpB,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,gBAAgB,GACnB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -1,5 +1,5 @@
 export { DERIVED_DURATION_CEILING_MS, DURATION_SOURCE_DERIVED, deriveAssistantDurations, } from './assistant-duration.js';
-export { HistoryImportError } from './errors.js';
+export { HistoryImportError, ImportCancelledError } from './errors.js';
 export { sha256, stableJson } from './hash.js';
 export { runJsonlImport } from './importer.js';
 export { applyHistoryImportSchema, normalizeSourceFilePaths, TYPED_HISTORY_TABLES } from './jsonl-importer-dao.js';

package/dist/opencode-importer.d.ts

@@ -11,6 +11,14 @@ export interface OpenCodeImportOptions {
     dryRun?: boolean;
     redactionRules?: readonly RedactionRule[];
     now?: () => Date;
+    /**
+     * Cooperative cancellation signal (feature A21 / ADR-112). Checked before the schema
+     * write, between source pages, and before the single settlement batch. Work already
+     * queued but not yet issued is discarded (the OpenCode store stays authoritative and a
+     * later run re-reads it); a batch already in flight settles before the run rejects with
+     * {@link ImportCancelledError}. Omitting the signal preserves existing behavior.
+     */
+    signal?: AbortSignal;
 }
 /** Import OpenCode's current SQLite history store into the forensic contract tables. */
 export declare function runOpenCodeImport(options: OpenCodeImportOptions): Promise<ImportResult>;

package/dist/opencode-importer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"opencode-importer.d.ts","sourceRoot":"","sources":["../src/opencode-importer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,SAAS,EAAkB,MAAM,kBAAkB,CAAC;AACnF,OAAO,EAGH,KAAK,UAAU,EAEf,KAAK,YAAY,EACpB,MAAM,uBAAuB,CAAC;AAgB/B,OAAO,KAAK,EAAe,UAAU,EAAE,YAAY,EAAgC,aAAa,EAAE,MAAM,SAAS,CAAC;AAYlH,8EAA8E;AAC9E,MAAM,WAAW,qBAAqB;IAClC,EAAE,EAAE,SAAS,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,cAAc,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CACpB;AAED,wFAAwF;AACxF,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,YAAY,CAAC,CAsI7F"}
+{"version":3,"file":"opencode-importer.d.ts","sourceRoot":"","sources":["../src/opencode-importer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,SAAS,EAAkB,MAAM,kBAAkB,CAAC;AACnF,OAAO,EAGH,KAAK,UAAU,EAEf,KAAK,YAAY,EACpB,MAAM,uBAAuB,CAAC;AAiB/B,OAAO,KAAK,EAAe,UAAU,EAAE,YAAY,EAAgC,aAAa,EAAE,MAAM,SAAS,CAAC;AAYlH,8EAA8E;AAC9E,MAAM,WAAW,qBAAqB;IAClC,EAAE,EAAE,SAAS,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,cAAc,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,wFAAwF;AACxF,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,YAAY,CAAC,CAiJ7F"}

package/dist/opencode-importer.js

@@ -1,5 +1,6 @@
 import { createDbAdapter } from '@gobing-ai/ts-db';
 import { ambientRuntimePaths, createNodeFileSystem, joinPath, } from '@gobing-ai/ts-runtime';
+import { throwIfImportAborted } from './cancellation.js';
 import { sha256 } from './hash.js';
 import { applyHistoryImportSchema, deleteCheckpointOperation, openCodeBulkWriteOperations, openCodeDeleteOperations, readOpenCodeExistingEntries, readOpenCodeMessages, readOpenCodeParts, } from './jsonl-importer-dao.js';
 import { maybeArgsRaw } from './mappers.js';
@@ -8,6 +9,9 @@ const SOURCE = 'opencode';
 const PAGE_SIZE = 250;
 /** Import OpenCode's current SQLite history store into the forensic contract tables. */
 export async function runOpenCodeImport(options) {
+    // Cancellation boundary (feature A21): before ANY invocation-owned write, including the
+    // schema setup below. An already-aborted signal must leave both databases untouched.
+    throwIfImportAborted(options.signal);
     const paths = options.paths ?? ambientRuntimePaths();
     const sourceDatabase = options.sourceDatabase ?? joinPath(paths.home, '.local/share/opencode/opencode.db');
     const fileSystem = options.fileSystem ?? createNodeFileSystem();
@@ -41,6 +45,10 @@ export async function runOpenCodeImport(options) {
     let reconciliation;
     try {
         while (true) {
+            // Cancellation boundary between bounded pages: stop before reading/queueing
+            // further work. Operations queued but not yet issued are discarded below —
+            // nothing was written, so the OpenCode store stays authoritative for resume.
+            throwIfImportAborted(options.signal);
             const messages = await readOpenCodeMessages(sourceDb, lastTime, lastId, PAGE_SIZE);
             if (messages.length === 0)
                 break;
@@ -111,6 +119,10 @@ export async function runOpenCodeImport(options) {
             }
             reconciliation = { staleTargetRows, staleLedgerRows, staleCheckpointRows };
         }
+        // Cancellation boundary before the single settlement batch: everything queued above
+        // is discarded (never issued), so a cancelled run writes nothing and the checkpoint
+        // stays where the previous run left it.
+        throwIfImportAborted(options.signal);
         if (operations.length > 0)
             await options.db.batch(operations);
     }

package/dist/schema-sql.d.ts

@@ -4,7 +4,7 @@
  * Guaranteed to match the package version; a bump-or-fail test enforces that
  * any modification to HISTORY_IMPORT_SCHEMA_SQL must be accompanied by a version bump.
  */
-export declare const HISTORY_IMPORT_SCHEMA_VERSION = "0.4.59";
+export declare const HISTORY_IMPORT_SCHEMA_VERSION = "0.4.60";
 /**
  * DDL string that creates the history import checkpoint, ledger, and typed contract tables.
  *

package/dist/schema-sql.js

@@ -4,7 +4,7 @@
  * Guaranteed to match the package version; a bump-or-fail test enforces that
  * any modification to HISTORY_IMPORT_SCHEMA_SQL must be accompanied by a version bump.
  */
-export const HISTORY_IMPORT_SCHEMA_VERSION = '0.4.59';
+export const HISTORY_IMPORT_SCHEMA_VERSION = '0.4.60';
 /**
  * DDL string that creates the history import checkpoint, ledger, and typed contract tables.
  *

package/dist/types.d.ts

@@ -70,6 +70,17 @@ export interface ImportOptions {
     readonly dryRun?: boolean;
     readonly redactionRules?: readonly RedactionRule[];
     readonly now?: () => Date;
+    /**
+     * Cooperative cancellation signal (feature A21 / ADR-112). Checked at safe boundaries —
+     * before schema and checkpoint writes, before each source file, and between bounded
+     * per-line batches — never inside a transaction: a batch already in flight settles first
+     * (its record, ledger, and checkpoint writes commit atomically), then the run rejects
+     * with {@link ImportCancelledError}. No invocation-owned write happens after settlement,
+     * and incremental resume continues from the last committed checkpoint. A cancellation
+     * cannot interrupt a synchronous SQLite call mid-flight — the containing process remains
+     * the hard fallback for blocking work. Omitting the signal preserves existing behavior.
+     */
+    readonly signal?: AbortSignal;
     /**
      * Optional cwd/home anchor (ADR-023 A1 / task 0042). When set, registry `defaultRoots`
      * resolve against `paths.home` instead of the ambient working directory; explicit

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-llm-jsonl-importer",
-    "version": "0.4.59",
+    "version": "0.4.60",
     "description": "@gobing-ai/ts-llm-jsonl-importer — Generic JSONL importer for LLM agent history files.",
     "keywords": [
         "typescript",
@@ -47,9 +47,9 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-llm-jsonl-importer-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-db": "^0.4.59",
-        "@gobing-ai/ts-runtime": "^0.4.59",
-        "@gobing-ai/ts-utils": "^0.4.59",
+        "@gobing-ai/ts-db": "^0.4.60",
+        "@gobing-ai/ts-runtime": "^0.4.60",
+        "@gobing-ai/ts-utils": "^0.4.60",
         "zod": "^4.1.0"
     },
     "devDependencies": {

package/src/cancellation.ts

@@ -0,0 +1,14 @@
+import { ImportCancelledError } from './errors';
+
+/**
+ * Cooperative cancellation boundary (feature A21 / ADR-112). Call it only at safe
+ * boundaries — before starting further asynchronous work or writes — so any in-flight
+ * batch settles first and the public promise can never reject ahead of its own writes.
+ * Synchronous SQLite work cannot be interrupted here; the containing process remains
+ * the hard fallback for blocking work.
+ */
+export function throwIfImportAborted(signal: AbortSignal | undefined): void {
+    if (signal?.aborted) {
+        throw new ImportCancelledError('Import cancelled by abort signal', signal.reason);
+    }
+}

package/src/errors.ts

@@ -8,3 +8,19 @@ export class HistoryImportError extends Error {
         this.name = 'HistoryImportError';
     }
 }
+
+/**
+ * Error raised when a run is cancelled through its {@link ImportOptions.signal} abort signal
+ * (feature A21 / ADR-112). Thrown only after in-flight transaction and checkpoint work has
+ * settled, so catching it means "cancellation settled — no further writes from this
+ * invocation". Incremental resume continues from the last committed checkpoint.
+ */
+export class ImportCancelledError extends HistoryImportError {
+    constructor(
+        message = 'Import cancelled by abort signal',
+        readonly abortReason?: unknown,
+    ) {
+        super(message, abortReason);
+        this.name = 'ImportCancelledError';
+    }
+}

package/src/importer.ts

@@ -7,6 +7,7 @@ import {
     resolvePath,
     walkDir,
 } from '@gobing-ai/ts-runtime';
+import { throwIfImportAborted } from './cancellation';
 import { sha256 } from './hash';
 import {
     applyHistoryImportSchema,
@@ -127,6 +128,9 @@ function attachableDuration(
  * @param options - Importer options (database, roots/files, mode, etc.).
  */
 export async function runJsonlImport(source: string | SourceDefinition, options: ImportOptions): Promise<ImportResult> {
+    // Cancellation boundary (feature A21): before ANY invocation-owned write, including the
+    // schema setup below. An already-aborted signal must leave the database untouched.
+    throwIfImportAborted(options.signal);
     const definition = resolveSourceDefinition(source);
     const resolvedSource = definition.source;
     const fileSystem = options.fileSystem ?? createNodeFileSystem();
@@ -134,6 +138,9 @@ export async function runJsonlImport(source: string | SourceDefinition, options:
 
     const mode = options.mode ?? 'incremental';
     const files = await discoverFiles(definition, options.roots, options.files, fileSystem, options.paths);
+    // Cancellation boundary: file discovery can walk many roots; a signal firing during it
+    // must stop before the full-mode checkpoint reset (an invocation-owned write).
+    throwIfImportAborted(options.signal);
     if (mode === 'full' && !options.dryRun) {
         await resetCheckpoints(options.db, resolvedSource, files);
     }
@@ -165,6 +172,8 @@ export async function runJsonlImport(source: string | SourceDefinition, options:
     const checkpoints = mode === 'incremental' ? await loadSourceCheckpoints(options.db, resolvedSource) : undefined;
 
     for (const file of files) {
+        // Cancellation boundary: stop before starting another file's work.
+        throwIfImportAborted(options.signal);
         const entry = checkpoints?.get(file);
         const checkpoint = entry?.line ?? 0;
         if (checkpoints !== undefined && entry !== undefined && entry.size !== null && entry.mtimeMs !== null) {
@@ -178,6 +187,10 @@ export async function runJsonlImport(source: string | SourceDefinition, options:
         }
         let lineNumber = 0;
         for await (const rawLine of readLines(fileSystem, file)) {
+            // Cancellation boundary between bounded per-line batches: a batch already in
+            // flight settled above (its record + ledger + checkpoint writes commit
+            // atomically), so rejecting here never leaves a partial line behind.
+            throwIfImportAborted(options.signal);
             lineNumber += 1;
             const line = rawLine.trim();
             if (line.length === 0 || lineNumber <= checkpoint) continue;
@@ -469,32 +482,39 @@ export async function runJsonlImport(source: string | SourceDefinition, options:
                     checkpointUpdates += 1;
                 }
             }
-            // 0675 R1/R4: stamp file identity once per READ file (never for skipped ones).
-            // This is also what self-heals legacy rows whose stored identity is NULL — without
-            // it a fully-imported database never arms the short-circuit. Skipped when nothing
-            // changed since the stored checkpoint to keep no-op runs write-free. Degraded
-            // entries (pre-migration database without identity columns, 0678 fail-open) keep
-            // the old line-only write shape via checkpointUpsertOp's optional identity.
-            if (!options.dryRun && mode === 'incremental') {
-                const statAfter = await safeStat(fileSystem, file);
-                // Degraded = a STORED entry without identity (pre-migration database, 0678
-                // fail-open). No stored entry means first-ever import: stamp normally.
-                const identityDegraded = entry !== undefined && entry.size === null && entry.mtimeMs === null;
-                const identityChanged =
-                    entry !== undefined &&
-                    (entry.size !== (statAfter?.size ?? null) || entry.mtimeMs !== (statAfter?.mtimeMs ?? null));
-                if (statAfter !== null && !identityDegraded && (entry === undefined || identityChanged)) {
-                    await options.db.batch([
-                        checkpointUpsertOp(resolvedSource, file, Math.max(lineNumber, checkpoint), options.now, {
-                            size: statAfter.size,
-                            mtimeMs: statAfter.mtimeMs,
-                        }),
-                    ]);
-                    checkpointUpdates += 1;
-                }
+        }
+        // 0675 R1/R4 (relocated from the per-line loop for feature A21): stamp file identity
+        // once per READ file, only after the file's line loop COMPLETED. A cancelled run
+        // throws at the per-line boundary above and must not arm the identity short-circuit:
+        // a mid-file checkpoint carrying full-file identity would make the next incremental
+        // run skip the whole file and silently lose the un-imported tail. "Once per read file
+        // (never for skipped ones)" is also what self-heals legacy rows whose stored identity
+        // is NULL — without a stamp a fully-imported database never arms the short-circuit.
+        // Skipped when nothing changed since the stored checkpoint to keep no-op runs
+        // write-free. Degraded entries (pre-migration database without identity columns,
+        // 0678 fail-open) keep the line-only write shape via checkpointUpsertOp's optional
+        // identity.
+        if (!options.dryRun && mode === 'incremental') {
+            const statAfter = await safeStat(fileSystem, file);
+            // Degraded = a STORED entry without identity (pre-migration database, 0678
+            // fail-open). No stored entry means first-ever import: stamp normally.
+            const identityDegraded = entry !== undefined && entry.size === null && entry.mtimeMs === null;
+            const identityChanged =
+                entry !== undefined &&
+                (entry.size !== (statAfter?.size ?? null) || entry.mtimeMs !== (statAfter?.mtimeMs ?? null));
+            if (statAfter !== null && !identityDegraded && (entry === undefined || identityChanged)) {
+                await options.db.batch([
+                    checkpointUpsertOp(resolvedSource, file, Math.max(lineNumber, checkpoint), options.now, {
+                        size: statAfter.size,
+                        mtimeMs: statAfter.mtimeMs,
+                    }),
+                ]);
+                checkpointUpdates += 1;
             }
         }
     }
+    // Cancellation boundary: stop before the full-mode reconciliation deletes.
+    throwIfImportAborted(options.signal);
     let reconciliation: ReconcileSummary | undefined;
     if (mode === 'full') {
         reconciliation = await reconcileFullImport(

package/src/index.ts

@@ -4,7 +4,7 @@ export {
     DURATION_SOURCE_DERIVED,
     deriveAssistantDurations,
 } from './assistant-duration';
-export { HistoryImportError } from './errors';
+export { HistoryImportError, ImportCancelledError } from './errors';
 export { sha256, stableJson } from './hash';
 export { runJsonlImport } from './importer';
 export { applyHistoryImportSchema, normalizeSourceFilePaths, TYPED_HISTORY_TABLES } from './jsonl-importer-dao';

package/src/opencode-importer.ts

@@ -6,6 +6,7 @@ import {
     joinPath,
     type RuntimePaths,
 } from '@gobing-ai/ts-runtime';
+import { throwIfImportAborted } from './cancellation';
 import { sha256 } from './hash';
 import {
     applyHistoryImportSchema,
@@ -43,10 +44,21 @@ export interface OpenCodeImportOptions {
     dryRun?: boolean;
     redactionRules?: readonly RedactionRule[];
     now?: () => Date;
+    /**
+     * Cooperative cancellation signal (feature A21 / ADR-112). Checked before the schema
+     * write, between source pages, and before the single settlement batch. Work already
+     * queued but not yet issued is discarded (the OpenCode store stays authoritative and a
+     * later run re-reads it); a batch already in flight settles before the run rejects with
+     * {@link ImportCancelledError}. Omitting the signal preserves existing behavior.
+     */
+    signal?: AbortSignal;
 }
 
 /** Import OpenCode's current SQLite history store into the forensic contract tables. */
 export async function runOpenCodeImport(options: OpenCodeImportOptions): Promise<ImportResult> {
+    // Cancellation boundary (feature A21): before ANY invocation-owned write, including the
+    // schema setup below. An already-aborted signal must leave both databases untouched.
+    throwIfImportAborted(options.signal);
     const paths = options.paths ?? ambientRuntimePaths();
     const sourceDatabase = options.sourceDatabase ?? joinPath(paths.home, '.local/share/opencode/opencode.db');
     const fileSystem = options.fileSystem ?? createNodeFileSystem();
@@ -82,6 +94,10 @@ export async function runOpenCodeImport(options: OpenCodeImportOptions): Promise
 
     try {
         while (true) {
+            // Cancellation boundary between bounded pages: stop before reading/queueing
+            // further work. Operations queued but not yet issued are discarded below —
+            // nothing was written, so the OpenCode store stays authoritative for resume.
+            throwIfImportAborted(options.signal);
             const messages = await readOpenCodeMessages(sourceDb, lastTime, lastId, PAGE_SIZE);
             if (messages.length === 0) break;
 
@@ -160,6 +176,10 @@ export async function runOpenCodeImport(options: OpenCodeImportOptions): Promise
             }
             reconciliation = { staleTargetRows, staleLedgerRows, staleCheckpointRows };
         }
+        // Cancellation boundary before the single settlement batch: everything queued above
+        // is discarded (never issued), so a cancelled run writes nothing and the checkpoint
+        // stays where the previous run left it.
+        throwIfImportAborted(options.signal);
         if (operations.length > 0) await options.db.batch(operations);
     } finally {
         sourceDb.close();

package/src/schema-sql.ts

@@ -4,7 +4,7 @@
  * Guaranteed to match the package version; a bump-or-fail test enforces that
  * any modification to HISTORY_IMPORT_SCHEMA_SQL must be accompanied by a version bump.
  */
-export const HISTORY_IMPORT_SCHEMA_VERSION = '0.4.59';
+export const HISTORY_IMPORT_SCHEMA_VERSION = '0.4.60';
 
 /**
  * DDL string that creates the history import checkpoint, ledger, and typed contract tables.

package/src/types.ts

@@ -93,6 +93,17 @@ export interface ImportOptions {
     readonly dryRun?: boolean;
     readonly redactionRules?: readonly RedactionRule[];
     readonly now?: () => Date;
+    /**
+     * Cooperative cancellation signal (feature A21 / ADR-112). Checked at safe boundaries —
+     * before schema and checkpoint writes, before each source file, and between bounded
+     * per-line batches — never inside a transaction: a batch already in flight settles first
+     * (its record, ledger, and checkpoint writes commit atomically), then the run rejects
+     * with {@link ImportCancelledError}. No invocation-owned write happens after settlement,
+     * and incremental resume continues from the last committed checkpoint. A cancellation
+     * cannot interrupt a synchronous SQLite call mid-flight — the containing process remains
+     * the hard fallback for blocking work. Omitting the signal preserves existing behavior.
+     */
+    readonly signal?: AbortSignal;
     /**
      * Optional cwd/home anchor (ADR-023 A1 / task 0042). When set, registry `defaultRoots`
      * resolve against `paths.home` instead of the ambient working directory; explicit