@gobing-ai/ts-llm-jsonl-importer 0.4.14 → 0.4.15

package/README.md

@@ -8,10 +8,13 @@ Generic JSONL import pipeline for AI-agent history-style files: discover files,
 
 | Export | Purpose |
 |--------|---------|
-| `runJsonlImport()` | Runs discovery, parsing, validation, redaction, dedupe, and persistence |
+| `runJsonlImport()` | Runs discovery, parsing, validation, redaction, dedupe, and persistence. Accepts a built-in source string **or** a custom `SourceDefinition`. |
 | `applyHistoryImportSchema()` | Installs importer-owned checkpoint, ledger, and ETL tables |
 | `SOURCE_DEFINITIONS` | Built-in source definitions |
-| `getSourceDefinition()` | Returns one source definition by key |
+| `getSourceDefinition()` | Returns one built-in definition by key (throws `HistoryImportError` for unknown keys) |
+| `resolveSourceDefinition()` | Resolves a `string \| SourceDefinition` into a validated definition |
+| `validateSourceDefinition()` | Validates a custom definition (target-table names, required fields) before pipeline entry |
+| `VALID_TABLE_NAME` | Regex governing every importer-owned ETL table name |
 | `redactRecord()` / `redactValue()` | Applies redaction rules before persistence |
 | `sha256()` / `stableJson()` | Stable hash helpers used by the ledger |
 | `HISTORY_IMPORT_SCHEMA_SQL` | SQL schema string for explicit migration flows |
@@ -138,6 +141,42 @@ const result = await runJsonlImport('pi', { db, files: ['session.jsonl'], mode:
 
 Downstream consumers should treat `source_file`, `source_line`, and `split_index` as the stable provenance tuple.
 
+## Custom Source Definitions
+
+Beyond the built-in source keys, `runJsonlImport()` accepts a fully-specified `SourceDefinition`
+for any custom agent history format. Unknown strings throw `HistoryImportError`; custom definitions
+are validated before any I/O (target-table names must match `VALID_TABLE_NAME` = `/^history_etl_[a-z_]+$/`,
+and required fields must be present).
+
+```ts
+import { z } from 'zod';
+import { createDbAdapter } from '@gobing-ai/ts-db';
+import { runJsonlImport, type SourceDefinition } from '@gobing-ai/ts-llm-jsonl-importer';
+
+const acme: SourceDefinition = {
+    source: 'acme',
+    displayName: 'Acme Assistant',
+    defaultRoots: ['.acme'],
+    filePatterns: ['*.jsonl'],
+    targetTable: 'history_etl_acme',
+    splitConfig: { mode: 'one-to-one' },
+    fieldMap: { id: 'source_record_id', timestamp: 'created_at', content: 'content' },
+    fieldTransforms: {},
+    schema: z.object({
+        source_record_id: z.string().min(1),
+        created_at: z.string().min(1),
+        content: z.string().min(1),
+    }),
+};
+
+const db = await createDbAdapter({ driver: 'bun-sqlite', url: './history.db' });
+const result = await runJsonlImport(acme, { db, roots: ['~/.acme'], mode: 'incremental' });
+```
+
+The custom `source` name flows through checkpoints, the ledger, and `ImportResult.source` exactly
+like a built-in key. The importer creates the target ETL table on demand if it does not exist
+(idempotent `CREATE TABLE IF NOT EXISTS`), so built-in tables are unaffected.
+
 ## Boundary Notes
 
 - This package imports JSONL files and writes importer-owned tables; it does not model conversations, turns, tool calls, or analytics semantics.

package/dist/importer.d.ts

@@ -1,6 +1,14 @@
-import type { ImportOptions, ImportResult, LlmJsonlSource } from './types';
+import type { ImportOptions, ImportResult, SourceDefinition } from './types';
 /** Apply importer-owned schema to the target database. */
 export declare function applyHistoryImportSchema(db: ImportOptions['db']): Promise<void>;
-/** Run the JSONL import pipeline for one source definition. */
-export declare function runJsonlImport(source: LlmJsonlSource, options: ImportOptions): Promise<ImportResult>;
+/**
+ * Run the JSONL import pipeline for one source.
+ *
+ * @param source - Either a built-in source identifier resolved from the
+ *   registry, or a fully-specified {@link SourceDefinition} for a custom
+ *   source. Unknown strings throw {@link HistoryImportError}; custom
+ *   definitions are validated before any I/O.
+ * @param options - Importer options (database, roots/files, mode, etc.).
+ */
+export declare function runJsonlImport(source: string | SourceDefinition, options: ImportOptions): Promise<ImportResult>;
 //# sourceMappingURL=importer.d.ts.map

package/dist/importer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"importer.d.ts","sourceRoot":"","sources":["../src/importer.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAER,aAAa,EACb,YAAY,EAEZ,cAAc,EAGjB,MAAM,SAAS,CAAC;AAajB,0DAA0D;AAC1D,wBAAsB,wBAAwB,CAAC,EAAE,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAOrF;AAED,+DAA+D;AAC/D,wBAAsB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CA4G1G"}
+{"version":3,"file":"importer.d.ts","sourceRoot":"","sources":["../src/importer.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAe,aAAa,EAAE,YAAY,EAAc,gBAAgB,EAAoB,MAAM,SAAS,CAAC;AAWxH,0DAA0D;AAC1D,wBAAsB,wBAAwB,CAAC,EAAE,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAOrF;AAiCD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CA8GrH"}

package/dist/importer.js

@@ -1,10 +1,9 @@
-import { createNodeFileSystem, resolvePath, walkDir } from '@gobing-ai/ts-runtime';
+import { ambientRuntimePaths, createNodeFileSystem, resolvePath, walkDir, } from '@gobing-ai/ts-runtime';
 import { HistoryImportError } from './errors.js';
 import { sha256 } from './hash.js';
 import { redactRecord } from './redaction.js';
 import { HISTORY_IMPORT_SCHEMA_SQL } from './schema-sql.js';
-import { getSourceDefinition } from './sources.js';
-const VALID_TABLE_NAME = /^history_etl_[a-z_]+$/;
+import { resolveSourceDefinition, VALID_TABLE_NAME } from './sources.js';
 /** Apply importer-owned schema to the target database. */
 export async function applyHistoryImportSchema(db) {
     for (const statement of HISTORY_IMPORT_SCHEMA_SQL.split(';')) {
@@ -14,15 +13,55 @@ export async function applyHistoryImportSchema(db) {
         }
     }
 }
-/** Run the JSONL import pipeline for one source definition. */
+/**
+ * Ensure the ETL table(s) for a source definition exist.
+ *
+ * WHY: the static {@link HISTORY_IMPORT_SCHEMA_SQL} only creates the built-in
+ * `history_etl_*` tables. Custom source definitions (and built-in definitions
+ * with a `splitConfig.targetTable` override) need their target table(s) created
+ * on demand. The table name is already gated by {@link VALID_TABLE_NAME} in
+ * {@link validateSourceDefinition} / {@link targetTableFor}, so it is safe to
+ * interpolate into DDL. `CREATE TABLE IF NOT EXISTS` makes this idempotent for
+ * built-in tables that the static schema already created.
+ */
+async function ensureTargetTables(db, definition) {
+    const tables = new Set([targetTableFor(definition.targetTable)]);
+    if (definition.splitConfig.mode !== 'one-to-one' && definition.splitConfig.targetTable !== undefined) {
+        tables.add(targetTableFor(definition.splitConfig.targetTable));
+    }
+    for (const table of tables) {
+        await db.exec(ETL_TABLE_DDL(table));
+    }
+}
+function ETL_TABLE_DDL(table) {
+    return `CREATE TABLE IF NOT EXISTS ${table} (
+    record_hash TEXT PRIMARY KEY,
+    source_file TEXT NOT NULL,
+    source_line INTEGER NOT NULL,
+    split_index INTEGER NOT NULL,
+    payload_json TEXT NOT NULL,
+    imported_at TEXT NOT NULL
+);`;
+}
+/**
+ * Run the JSONL import pipeline for one source.
+ *
+ * @param source - Either a built-in source identifier resolved from the
+ *   registry, or a fully-specified {@link SourceDefinition} for a custom
+ *   source. Unknown strings throw {@link HistoryImportError}; custom
+ *   definitions are validated before any I/O.
+ * @param options - Importer options (database, roots/files, mode, etc.).
+ */
 export async function runJsonlImport(source, options) {
-    const definition = getSourceDefinition(source);
+    const definition = resolveSourceDefinition(source);
+    const resolvedSource = definition.source;
     const fileSystem = options.fileSystem ?? createNodeFileSystem();
     await applyHistoryImportSchema(options.db);
+    await ensureTargetTables(options.db, definition);
     const mode = options.mode ?? 'incremental';
-    const files = await discoverFiles(definition, options.roots, options.files, fileSystem);
+    const files = await discoverFiles(definition, options.roots, options.files, fileSystem, options.paths);
     if (mode === 'full' && !options.dryRun) {
-        await resetCheckpoints(options.db, source, files);
+        await resetCheckpoints(options.db, resolvedSource, files);
     }
     const parseErrors = [];
     const validationErrors = [];
@@ -31,7 +70,7 @@ export async function runJsonlImport(source, options) {
     let skippedDuplicates = 0;
     let checkpointUpdates = 0;
     for (const file of files) {
-        const checkpoint = mode === 'incremental' ? await readCheckpoint(options.db, source, file) : 0;
+        const checkpoint = mode === 'incremental' ? await readCheckpoint(options.db, resolvedSource, file) : 0;
         let lineNumber = 0;
         for await (const rawLine of readLines(fileSystem, file)) {
             lineNumber += 1;
@@ -49,7 +88,7 @@ export async function runJsonlImport(source, options) {
                 if (split === undefined)
                     continue;
                 const normalized = normalizeRecord(definition, split.raw, {
-                    source,
+                    source: resolvedSource,
                     sourceFile: file,
                     sourceLine: lineNumber,
                     splitIndex,
@@ -66,7 +105,7 @@ export async function runJsonlImport(source, options) {
                 const redacted = redactRecord(parsed.data, options.redactionRules);
                 lineSucceeded = true;
                 const recordHash = sha256({
-                    source,
+                    source: resolvedSource,
                     sourceFile: file,
                     sourceLine: lineNumber,
                     splitIndex,
@@ -78,18 +117,18 @@ export async function runJsonlImport(source, options) {
                 }
                 if (!options.dryRun) {
                     await insertRecord(options.db, split.targetTable, recordHash, file, lineNumber, splitIndex, redacted, options.now);
-                    await insertLedger(options.db, recordHash, source, file, lineNumber, splitIndex, split.targetTable, options.now);
+                    await insertLedger(options.db, recordHash, resolvedSource, file, lineNumber, splitIndex, split.targetTable, options.now);
                 }
                 importedRecords += 1;
             }
             if (lineSucceeded && !options.dryRun) {
-                await writeCheckpoint(options.db, source, file, lineNumber, options.now);
+                await writeCheckpoint(options.db, resolvedSource, file, lineNumber, options.now);
                 checkpointUpdates += 1;
             }
         }
     }
     return {
-        source,
+        source: resolvedSource,
         mode,
         scannedFiles: files.length,
         processedLines,
@@ -153,11 +192,20 @@ function normalizeRecord(definition, raw, context) {
     normalized.split_index = context.splitIndex;
     return normalized;
 }
-async function discoverFiles(definition, roots, files, fileSystem) {
+async function discoverFiles(definition, roots, files, fileSystem, paths) {
     if (files !== undefined && files.length > 0) {
         return files.map((file) => resolvePath(file)).sort();
     }
-    const resolvedRoots = (roots ?? definition.defaultRoots).map((root) => resolvePath(root));
+    // Root resolution splits by provenance (ADR-023 A1 / task 0042):
+    //  - explicit caller-supplied `roots` → cwd semantics: resolve against `paths.cwd` when
+    //    injected, else ambient cwd (the pre-seam behaviour — R4 additive-only).
+    //  - registry `defaultRoots` → home-relative: resolve against `paths.home`.
+    //    Previously both kinds anchored to ambient cwd, so a cwd ≠ $HOME silently skipped every
+    //    registry source because the home-relative paths never existed relative to cwd.
+    const ambient = paths ?? ambientRuntimePaths();
+    const resolvedRoots = roots !== undefined
+        ? roots.map((root) => resolvePath(ambient.cwd, root))
+        : definition.defaultRoots.map((root) => resolvePath(ambient.home, root));
     const found = new Set();
     for (const root of resolvedRoots) {
         if (!(await fileSystem.exists(root)))

package/dist/index.d.ts

@@ -3,6 +3,6 @@ export { sha256, stableJson } from './hash';
 export { applyHistoryImportSchema, runJsonlImport } from './importer';
 export { DEFAULT_REDACTION_RULES, redactRecord, redactValue } from './redaction';
 export { HISTORY_IMPORT_SCHEMA_SQL } from './schema-sql';
-export { getSourceDefinition, SOURCE_DEFINITIONS } from './sources';
+export { getSourceDefinition, resolveSourceDefinition, SOURCE_DEFINITIONS, VALID_TABLE_NAME, validateSourceDefinition, } from './sources';
 export type { FieldTransform, ImportIssue, ImportMode, ImportOptions, ImportResult, JsonObject, LlmJsonlSource, RedactionRule, SourceDefinition, SplitConfig, TransformContext, } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,EAAE,wBAAwB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACpE,YAAY,EACR,cAAc,EACd,WAAW,EACX,UAAU,EACV,aAAa,EACb,YAAY,EACZ,UAAU,EACV,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,gBAAgB,GACnB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,EAAE,wBAAwB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EACH,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,wBAAwB,GAC3B,MAAM,WAAW,CAAC;AACnB,YAAY,EACR,cAAc,EACd,WAAW,EACX,UAAU,EACV,aAAa,EACb,YAAY,EACZ,UAAU,EACV,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,gBAAgB,GACnB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -3,4 +3,4 @@ export { sha256, stableJson } from './hash.js';
 export { applyHistoryImportSchema, runJsonlImport } from './importer.js';
 export { DEFAULT_REDACTION_RULES, redactRecord, redactValue } from './redaction.js';
 export { HISTORY_IMPORT_SCHEMA_SQL } from './schema-sql.js';
-export { getSourceDefinition, SOURCE_DEFINITIONS } from './sources.js';
+export { getSourceDefinition, resolveSourceDefinition, SOURCE_DEFINITIONS, VALID_TABLE_NAME, validateSourceDefinition, } from './sources.js';

package/dist/sources.d.ts

@@ -1,6 +1,36 @@
 import type { LlmJsonlSource, SourceDefinition } from './types';
+/**
+ * Pattern every importer-owned table must match.
+ *
+ * WHY: the table name is interpolated into generated SQL (it is not a bind
+ * parameter), so it must be a safe identifier. The `history_etl_` prefix also
+ * namespaces importer tables away from consumer schemas. Both built-in and
+ * custom source definitions are held to this rule.
+ */
+export declare const VALID_TABLE_NAME: RegExp;
 /** Built-in source definitions keyed by source identifier. */
 export declare const SOURCE_DEFINITIONS: Readonly<Record<LlmJsonlSource, SourceDefinition>>;
-/** Resolve a built-in source definition by identifier. */
+/**
+ * Resolve a built-in source definition by identifier.
+ *
+ * Throws {@link HistoryImportError} for unknown identifiers so misconfigured
+ * callers fail fast at the seam instead of producing empty imports.
+ */
 export declare function getSourceDefinition(source: LlmJsonlSource): SourceDefinition;
+/**
+ * Validate a caller-supplied source definition before it enters the pipeline.
+ *
+ * WHY: target table names are interpolated into SQL, so both the primary
+ * `targetTable` and any `splitConfig.targetTable` override must match
+ * {@link VALID_TABLE_NAME}. Required structural fields are checked here so the
+ * importer can assume they are present. Built-in definitions skip this — they
+ * are validated by construction.
+ */
+export declare function validateSourceDefinition(definition: SourceDefinition): SourceDefinition;
+/**
+ * Resolve a `string | SourceDefinition` source argument into a validated
+ * {@link SourceDefinition}. Strings resolve from {@link SOURCE_DEFINITIONS}
+ * (unknown strings throw); objects are validated via {@link validateSourceDefinition}.
+ */
+export declare function resolveSourceDefinition(input: string | SourceDefinition): SourceDefinition;
 //# sourceMappingURL=sources.d.ts.map

package/dist/sources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../src/sources.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAA8B,cAAc,EAAE,gBAAgB,EAAoB,MAAM,SAAS,CAAC;AA+F9G,8DAA8D;AAC9D,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAQjF,CAAC;AAEF,0DAA0D;AAC1D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG,gBAAgB,CAE5E"}
+{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../src/sources.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAA8B,cAAc,EAAE,gBAAgB,EAAoB,MAAM,SAAS,CAAC;AA8F9G;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,QAA0B,CAAC;AAExD,8DAA8D;AAC9D,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAQjF,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG,gBAAgB,CAM5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,gBAAgB,GAAG,gBAAgB,CA+BvF;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,gBAAgB,CAK1F"}

package/dist/sources.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { HistoryImportError } from './errors.js';
 const sourceRecordSchema = z
     .object({
     source_record_id: z.string().min(1),
@@ -71,6 +72,15 @@ function sourceDefinition(source, displayName, defaultRoots, filePatterns) {
         schema: sourceRecordSchema,
     };
 }
+/**
+ * Pattern every importer-owned table must match.
+ *
+ * WHY: the table name is interpolated into generated SQL (it is not a bind
+ * parameter), so it must be a safe identifier. The `history_etl_` prefix also
+ * namespaces importer tables away from consumer schemas. Both built-in and
+ * custom source definitions are held to this rule.
+ */
+export const VALID_TABLE_NAME = /^history_etl_[a-z_]+$/;
 /** Built-in source definitions keyed by source identifier. */
 export const SOURCE_DEFINITIONS = {
     pi: sourceDefinition('pi', 'Pi', ['.pi/history', '.pi'], ['*.jsonl', '*.json']),
@@ -81,7 +91,73 @@ export const SOURCE_DEFINITIONS = {
     antigravity: sourceDefinition('antigravity', 'Antigravity', ['.antigravity'], ['*.jsonl']),
     openclaw: sourceDefinition('openclaw', 'OpenClaw', ['.openclaw'], ['*.jsonl']),
 };
-/** Resolve a built-in source definition by identifier. */
+/**
+ * Resolve a built-in source definition by identifier.
+ *
+ * Throws {@link HistoryImportError} for unknown identifiers so misconfigured
+ * callers fail fast at the seam instead of producing empty imports.
+ */
 export function getSourceDefinition(source) {
-    return SOURCE_DEFINITIONS[source];
+    const definition = SOURCE_DEFINITIONS[source];
+    if (definition === undefined) {
+        throw new HistoryImportError(`Unknown LLM JSONL source: ${source}`, { source });
+    }
+    return definition;
+}
+/**
+ * Validate a caller-supplied source definition before it enters the pipeline.
+ *
+ * WHY: target table names are interpolated into SQL, so both the primary
+ * `targetTable` and any `splitConfig.targetTable` override must match
+ * {@link VALID_TABLE_NAME}. Required structural fields are checked here so the
+ * importer can assume they are present. Built-in definitions skip this — they
+ * are validated by construction.
+ */
+export function validateSourceDefinition(definition) {
+    const requiredFields = [
+        'source',
+        'displayName',
+        'defaultRoots',
+        'filePatterns',
+        'targetTable',
+        'splitConfig',
+        'fieldMap',
+        'fieldTransforms',
+        'schema',
+    ];
+    for (const field of requiredFields) {
+        if (definition[field] === undefined || definition[field] === null) {
+            throw new HistoryImportError(`Source definition is missing required field: ${String(field)}`, {
+                source: definition.source,
+                field: String(field),
+            });
+        }
+    }
+    if (definition.filePatterns.length === 0) {
+        throw new HistoryImportError('Source definition must declare at least one file pattern', {
+            source: definition.source,
+            field: 'filePatterns',
+        });
+    }
+    assertValidTable(definition.targetTable, definition.source);
+    if (definition.splitConfig.mode !== 'one-to-one' && definition.splitConfig.targetTable !== undefined) {
+        assertValidTable(definition.splitConfig.targetTable, definition.source);
+    }
+    return definition;
+}
+/**
+ * Resolve a `string | SourceDefinition` source argument into a validated
+ * {@link SourceDefinition}. Strings resolve from {@link SOURCE_DEFINITIONS}
+ * (unknown strings throw); objects are validated via {@link validateSourceDefinition}.
+ */
+export function resolveSourceDefinition(input) {
+    if (typeof input === 'string') {
+        return getSourceDefinition(input);
+    }
+    return validateSourceDefinition(input);
+}
+function assertValidTable(table, source) {
+    if (!VALID_TABLE_NAME.test(table)) {
+        throw new HistoryImportError(`Invalid history ETL target table for source "${source}": ${table}. Must match ${VALID_TABLE_NAME.source}.`, { source, table });
+    }
 }

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import type { DbAdapter } from '@gobing-ai/ts-db';
-import type { FileSystem } from '@gobing-ai/ts-runtime';
+import type { FileSystem, RuntimePaths } from '@gobing-ai/ts-runtime';
 import type { z } from 'zod';
 /** Built-in source identifiers supported by the importer. */
 export type LlmJsonlSource = 'pi' | 'claude' | 'codex' | 'gemini' | 'opencode' | 'antigravity' | 'openclaw';
@@ -23,14 +23,16 @@ export type JsonObject = Record<string, unknown>;
 export type FieldTransform = (value: unknown, raw: JsonObject, context: TransformContext) => unknown;
 /** Context available while normalizing a split record. */
 export interface TransformContext {
-    readonly source: LlmJsonlSource;
+    /** Source identifier — a built-in {@link LlmJsonlSource} or a custom definition's name. */
+    readonly source: string;
     readonly sourceFile: string;
     readonly sourceLine: number;
     readonly splitIndex: number;
 }
 /** Declarative importer configuration for one LLM history source. */
 export interface SourceDefinition<TRecord extends JsonObject = JsonObject> {
-    readonly source: LlmJsonlSource;
+    /** Source identifier — a built-in {@link LlmJsonlSource} or a custom name. Becomes the checkpoint/ledger key. */
+    readonly source: string;
     readonly displayName: string;
     readonly defaultRoots: readonly string[];
     readonly filePatterns: readonly string[];
@@ -56,6 +58,12 @@ export interface ImportOptions {
     readonly dryRun?: boolean;
     readonly redactionRules?: readonly RedactionRule[];
     readonly now?: () => Date;
+    /**
+     * Optional cwd/home anchor (ADR-023 A1 / task 0042). When set, registry `defaultRoots`
+     * resolve against `paths.home` instead of the ambient working directory; explicit
+     * {@link ImportOptions.roots} keep cwd semantics unchanged. Defaults to ambient cwd/home.
+     */
+    readonly paths?: RuntimePaths;
 }
 /** Structured importer error that can be reported without persisting raw input. */
 export interface ImportIssue {
@@ -65,7 +73,8 @@ export interface ImportIssue {
 }
 /** Summary produced by the importer control function. */
 export interface ImportResult {
-    readonly source: LlmJsonlSource;
+    /** Source identifier — the built-in name or custom definition name that produced this result. */
+    readonly source: string;
     readonly mode: ImportMode;
     readonly scannedFiles: number;
     readonly processedLines: number;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,6DAA6D;AAC7D,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,GAAG,aAAa,GAAG,UAAU,CAAC;AAE5G,mDAAmD;AACnD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,aAAa,GAAG,YAAY,CAAC;AAE/D,kFAAkF;AAClF,MAAM,MAAM,WAAW,GACjB;IACI,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;CAC/B,GACD;IACI,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CACjC,GACD;IACI,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,SAAS,UAAU,EAAE,CAAC;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CACjC,CAAC;AAER,4DAA4D;AAC5D,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,sDAAsD;AACtD,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC;AAErG,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC/B;AAED,qEAAqE;AACrE,MAAM,WAAW,gBAAgB,CAAC,OAAO,SAAS,UAAU,GAAG,UAAU;IACrE,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;IACnE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;CACvC;AAED,6DAA6D;AAC7D,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAChC;AAED,oCAAoC;AACpC,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IACnD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED,mFAAmF;AACnF,MAAM,WAAW,WAAW;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CAC3B;AAED,yDAAyD;AACzD,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,SAAS,WAAW,EAAE,CAAC;IAC7C,QAAQ,CAAC,gBAAgB,EAAE,SAAS,WAAW,EAAE,CAAC;IAClD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACtC"}
+{"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.14",
+    "version": "0.4.15",
     "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.14",
-        "@gobing-ai/ts-runtime": "^0.4.14",
-        "@gobing-ai/ts-utils": "^0.4.14",
+        "@gobing-ai/ts-db": "^0.4.15",
+        "@gobing-ai/ts-runtime": "^0.4.15",
+        "@gobing-ai/ts-utils": "^0.4.15",
         "zod": "^4.1.0"
     },
     "devDependencies": {

package/src/importer.ts

@@ -1,18 +1,17 @@
-import { createNodeFileSystem, type FileSystem, resolvePath, walkDir } from '@gobing-ai/ts-runtime';
+import {
+    ambientRuntimePaths,
+    createNodeFileSystem,
+    type FileSystem,
+    type RuntimePaths,
+    resolvePath,
+    walkDir,
+} from '@gobing-ai/ts-runtime';
 import { HistoryImportError } from './errors';
 import { sha256 } from './hash';
 import { redactRecord } from './redaction';
 import { HISTORY_IMPORT_SCHEMA_SQL } from './schema-sql';
-import { getSourceDefinition } from './sources';
-import type {
-    ImportIssue,
-    ImportOptions,
-    ImportResult,
-    JsonObject,
-    LlmJsonlSource,
-    SourceDefinition,
-    TransformContext,
-} from './types';
+import { resolveSourceDefinition, VALID_TABLE_NAME } from './sources';
+import type { ImportIssue, ImportOptions, ImportResult, JsonObject, SourceDefinition, TransformContext } from './types';
 
 interface SplitRecord {
     readonly targetTable: string;
@@ -23,8 +22,6 @@ interface CheckpointRow {
     readonly last_imported_line: number;
 }
 
-const VALID_TABLE_NAME = /^history_etl_[a-z_]+$/;
-
 /** Apply importer-owned schema to the target database. */
 export async function applyHistoryImportSchema(db: ImportOptions['db']): Promise<void> {
     for (const statement of HISTORY_IMPORT_SCHEMA_SQL.split(';')) {
@@ -35,16 +32,57 @@ export async function applyHistoryImportSchema(db: ImportOptions['db']): Promise
     }
 }
 
-/** Run the JSONL import pipeline for one source definition. */
-export async function runJsonlImport(source: LlmJsonlSource, options: ImportOptions): Promise<ImportResult> {
-    const definition = getSourceDefinition(source);
+/**
+ * Ensure the ETL table(s) for a source definition exist.
+ *
+ * WHY: the static {@link HISTORY_IMPORT_SCHEMA_SQL} only creates the built-in
+ * `history_etl_*` tables. Custom source definitions (and built-in definitions
+ * with a `splitConfig.targetTable` override) need their target table(s) created
+ * on demand. The table name is already gated by {@link VALID_TABLE_NAME} in
+ * {@link validateSourceDefinition} / {@link targetTableFor}, so it is safe to
+ * interpolate into DDL. `CREATE TABLE IF NOT EXISTS` makes this idempotent for
+ * built-in tables that the static schema already created.
+ */
+async function ensureTargetTables(db: ImportOptions['db'], definition: SourceDefinition): Promise<void> {
+    const tables = new Set<string>([targetTableFor(definition.targetTable)]);
+    if (definition.splitConfig.mode !== 'one-to-one' && definition.splitConfig.targetTable !== undefined) {
+        tables.add(targetTableFor(definition.splitConfig.targetTable));
+    }
+    for (const table of tables) {
+        await db.exec(ETL_TABLE_DDL(table));
+    }
+}
+
+function ETL_TABLE_DDL(table: string): string {
+    return `CREATE TABLE IF NOT EXISTS ${table} (
+    record_hash TEXT PRIMARY KEY,
+    source_file TEXT NOT NULL,
+    source_line INTEGER NOT NULL,
+    split_index INTEGER NOT NULL,
+    payload_json TEXT NOT NULL,
+    imported_at TEXT NOT NULL
+);`;
+}
+/**
+ * Run the JSONL import pipeline for one source.
+ *
+ * @param source - Either a built-in source identifier resolved from the
+ *   registry, or a fully-specified {@link SourceDefinition} for a custom
+ *   source. Unknown strings throw {@link HistoryImportError}; custom
+ *   definitions are validated before any I/O.
+ * @param options - Importer options (database, roots/files, mode, etc.).
+ */
+export async function runJsonlImport(source: string | SourceDefinition, options: ImportOptions): Promise<ImportResult> {
+    const definition = resolveSourceDefinition(source);
+    const resolvedSource = definition.source;
     const fileSystem = options.fileSystem ?? createNodeFileSystem();
     await applyHistoryImportSchema(options.db);
+    await ensureTargetTables(options.db, definition);
 
     const mode = options.mode ?? 'incremental';
-    const files = await discoverFiles(definition, options.roots, options.files, fileSystem);
+    const files = await discoverFiles(definition, options.roots, options.files, fileSystem, options.paths);
     if (mode === 'full' && !options.dryRun) {
-        await resetCheckpoints(options.db, source, files);
+        await resetCheckpoints(options.db, resolvedSource, files);
     }
 
     const parseErrors: ImportIssue[] = [];
@@ -55,7 +93,7 @@ export async function runJsonlImport(source: LlmJsonlSource, options: ImportOpti
     let checkpointUpdates = 0;
 
     for (const file of files) {
-        const checkpoint = mode === 'incremental' ? await readCheckpoint(options.db, source, file) : 0;
+        const checkpoint = mode === 'incremental' ? await readCheckpoint(options.db, resolvedSource, file) : 0;
         let lineNumber = 0;
         for await (const rawLine of readLines(fileSystem, file)) {
             lineNumber += 1;
@@ -73,7 +111,7 @@ export async function runJsonlImport(source: LlmJsonlSource, options: ImportOpti
                 const split = splitRecords[splitIndex];
                 if (split === undefined) continue;
                 const normalized = normalizeRecord(definition, split.raw, {
-                    source,
+                    source: resolvedSource,
                     sourceFile: file,
                     sourceLine: lineNumber,
                     splitIndex,
@@ -91,7 +129,7 @@ export async function runJsonlImport(source: LlmJsonlSource, options: ImportOpti
                 const redacted = redactRecord(parsed.data, options.redactionRules);
                 lineSucceeded = true;
                 const recordHash = sha256({
-                    source,
+                    source: resolvedSource,
                     sourceFile: file,
                     sourceLine: lineNumber,
                     splitIndex,
@@ -115,7 +153,7 @@ export async function runJsonlImport(source: LlmJsonlSource, options: ImportOpti
                     await insertLedger(
                         options.db,
                         recordHash,
-                        source,
+                        resolvedSource,
                         file,
                         lineNumber,
                         splitIndex,
@@ -127,14 +165,14 @@ export async function runJsonlImport(source: LlmJsonlSource, options: ImportOpti
             }
 
             if (lineSucceeded && !options.dryRun) {
-                await writeCheckpoint(options.db, source, file, lineNumber, options.now);
+                await writeCheckpoint(options.db, resolvedSource, file, lineNumber, options.now);
                 checkpointUpdates += 1;
             }
         }
     }
 
     return {
-        source,
+        source: resolvedSource,
         mode,
         scannedFiles: files.length,
         processedLines,
@@ -211,12 +249,23 @@ async function discoverFiles(
     roots: readonly string[] | undefined,
     files: readonly string[] | undefined,
     fileSystem: FileSystem,
+    paths: RuntimePaths | undefined,
 ): Promise<readonly string[]> {
     if (files !== undefined && files.length > 0) {
         return files.map((file) => resolvePath(file)).sort();
     }
 
-    const resolvedRoots = (roots ?? definition.defaultRoots).map((root) => resolvePath(root));
+    // Root resolution splits by provenance (ADR-023 A1 / task 0042):
+    //  - explicit caller-supplied `roots` → cwd semantics: resolve against `paths.cwd` when
+    //    injected, else ambient cwd (the pre-seam behaviour — R4 additive-only).
+    //  - registry `defaultRoots` → home-relative: resolve against `paths.home`.
+    //    Previously both kinds anchored to ambient cwd, so a cwd ≠ $HOME silently skipped every
+    //    registry source because the home-relative paths never existed relative to cwd.
+    const ambient = paths ?? ambientRuntimePaths();
+    const resolvedRoots =
+        roots !== undefined
+            ? roots.map((root) => resolvePath(ambient.cwd, root))
+            : definition.defaultRoots.map((root) => resolvePath(ambient.home, root));
     const found = new Set<string>();
     for (const root of resolvedRoots) {
         if (!(await fileSystem.exists(root))) continue;

package/src/index.ts

@@ -3,7 +3,13 @@ export { sha256, stableJson } from './hash';
 export { applyHistoryImportSchema, runJsonlImport } from './importer';
 export { DEFAULT_REDACTION_RULES, redactRecord, redactValue } from './redaction';
 export { HISTORY_IMPORT_SCHEMA_SQL } from './schema-sql';
-export { getSourceDefinition, SOURCE_DEFINITIONS } from './sources';
+export {
+    getSourceDefinition,
+    resolveSourceDefinition,
+    SOURCE_DEFINITIONS,
+    VALID_TABLE_NAME,
+    validateSourceDefinition,
+} from './sources';
 export type {
     FieldTransform,
     ImportIssue,

package/src/sources.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { HistoryImportError } from './errors';
 import type { FieldTransform, JsonObject, LlmJsonlSource, SourceDefinition, TransformContext } from './types';
 
 const sourceRecordSchema = z
@@ -93,6 +94,15 @@ function sourceDefinition(
         schema: sourceRecordSchema,
     };
 }
+/**
+ * Pattern every importer-owned table must match.
+ *
+ * WHY: the table name is interpolated into generated SQL (it is not a bind
+ * parameter), so it must be a safe identifier. The `history_etl_` prefix also
+ * namespaces importer tables away from consumer schemas. Both built-in and
+ * custom source definitions are held to this rule.
+ */
+export const VALID_TABLE_NAME = /^history_etl_[a-z_]+$/;
 
 /** Built-in source definitions keyed by source identifier. */
 export const SOURCE_DEFINITIONS: Readonly<Record<LlmJsonlSource, SourceDefinition>> = {
@@ -105,7 +115,79 @@ export const SOURCE_DEFINITIONS: Readonly<Record<LlmJsonlSource, SourceDefinitio
     openclaw: sourceDefinition('openclaw', 'OpenClaw', ['.openclaw'], ['*.jsonl']),
 };
 
-/** Resolve a built-in source definition by identifier. */
+/**
+ * Resolve a built-in source definition by identifier.
+ *
+ * Throws {@link HistoryImportError} for unknown identifiers so misconfigured
+ * callers fail fast at the seam instead of producing empty imports.
+ */
 export function getSourceDefinition(source: LlmJsonlSource): SourceDefinition {
-    return SOURCE_DEFINITIONS[source];
+    const definition = SOURCE_DEFINITIONS[source];
+    if (definition === undefined) {
+        throw new HistoryImportError(`Unknown LLM JSONL source: ${source}`, { source });
+    }
+    return definition;
+}
+
+/**
+ * Validate a caller-supplied source definition before it enters the pipeline.
+ *
+ * WHY: target table names are interpolated into SQL, so both the primary
+ * `targetTable` and any `splitConfig.targetTable` override must match
+ * {@link VALID_TABLE_NAME}. Required structural fields are checked here so the
+ * importer can assume they are present. Built-in definitions skip this — they
+ * are validated by construction.
+ */
+export function validateSourceDefinition(definition: SourceDefinition): SourceDefinition {
+    const requiredFields: ReadonlyArray<keyof SourceDefinition> = [
+        'source',
+        'displayName',
+        'defaultRoots',
+        'filePatterns',
+        'targetTable',
+        'splitConfig',
+        'fieldMap',
+        'fieldTransforms',
+        'schema',
+    ];
+    for (const field of requiredFields) {
+        if (definition[field] === undefined || definition[field] === null) {
+            throw new HistoryImportError(`Source definition is missing required field: ${String(field)}`, {
+                source: definition.source,
+                field: String(field),
+            });
+        }
+    }
+    if (definition.filePatterns.length === 0) {
+        throw new HistoryImportError('Source definition must declare at least one file pattern', {
+            source: definition.source,
+            field: 'filePatterns',
+        });
+    }
+    assertValidTable(definition.targetTable, definition.source);
+    if (definition.splitConfig.mode !== 'one-to-one' && definition.splitConfig.targetTable !== undefined) {
+        assertValidTable(definition.splitConfig.targetTable, definition.source);
+    }
+    return definition;
+}
+
+/**
+ * Resolve a `string | SourceDefinition` source argument into a validated
+ * {@link SourceDefinition}. Strings resolve from {@link SOURCE_DEFINITIONS}
+ * (unknown strings throw); objects are validated via {@link validateSourceDefinition}.
+ */
+export function resolveSourceDefinition(input: string | SourceDefinition): SourceDefinition {
+    if (typeof input === 'string') {
+        return getSourceDefinition(input as LlmJsonlSource);
+    }
+    return validateSourceDefinition(input);
+}
+
+function assertValidTable(table: string, source: string): void {
+    if (!VALID_TABLE_NAME.test(table)) {
+        throw new HistoryImportError(
+            `Invalid history ETL target table for source "${source}": ${table}. Must match ${VALID_TABLE_NAME.source}.`,
+            { source, table },
+        );
+    }
 }

package/src/types.ts

@@ -1,5 +1,5 @@
 import type { DbAdapter } from '@gobing-ai/ts-db';
-import type { FileSystem } from '@gobing-ai/ts-runtime';
+import type { FileSystem, RuntimePaths } from '@gobing-ai/ts-runtime';
 import type { z } from 'zod';
 
 /** Built-in source identifiers supported by the importer. */
@@ -32,7 +32,8 @@ export type FieldTransform = (value: unknown, raw: JsonObject, context: Transfor
 
 /** Context available while normalizing a split record. */
 export interface TransformContext {
-    readonly source: LlmJsonlSource;
+    /** Source identifier — a built-in {@link LlmJsonlSource} or a custom definition's name. */
+    readonly source: string;
     readonly sourceFile: string;
     readonly sourceLine: number;
     readonly splitIndex: number;
@@ -40,7 +41,8 @@ export interface TransformContext {
 
 /** Declarative importer configuration for one LLM history source. */
 export interface SourceDefinition<TRecord extends JsonObject = JsonObject> {
-    readonly source: LlmJsonlSource;
+    /** Source identifier — a built-in {@link LlmJsonlSource} or a custom name. Becomes the checkpoint/ledger key. */
+    readonly source: string;
     readonly displayName: string;
     readonly defaultRoots: readonly string[];
     readonly filePatterns: readonly string[];
@@ -68,6 +70,12 @@ export interface ImportOptions {
     readonly dryRun?: boolean;
     readonly redactionRules?: readonly RedactionRule[];
     readonly now?: () => Date;
+    /**
+     * Optional cwd/home anchor (ADR-023 A1 / task 0042). When set, registry `defaultRoots`
+     * resolve against `paths.home` instead of the ambient working directory; explicit
+     * {@link ImportOptions.roots} keep cwd semantics unchanged. Defaults to ambient cwd/home.
+     */
+    readonly paths?: RuntimePaths;
 }
 
 /** Structured importer error that can be reported without persisting raw input. */
@@ -79,7 +87,8 @@ export interface ImportIssue {
 
 /** Summary produced by the importer control function. */
 export interface ImportResult {
-    readonly source: LlmJsonlSource;
+    /** Source identifier — the built-in name or custom definition name that produced this result. */
+    readonly source: string;
     readonly mode: ImportMode;
     readonly scannedFiles: number;
     readonly processedLines: number;