@nitpicker/archive 0.0.0 → 0.25.0

package/lib/transfer/remap-redirect-dest-ids.js

@@ -0,0 +1,51 @@
+import { TRANSFER_ACTION } from './transfer-action.js';
+import { TRANSFER_SOURCE_ALIAS } from './transfer-source-alias.js';
+/**
+ * Remaps `redirect_dest_id` for every `full`/`stub`/`replace`-action
+ * destination row this source just wrote, from the source's own id space
+ * into the destination's, via `temp.xfer_ci_plan` (which by this point
+ * maps EVERY source id to a destination id, not just the ones this source
+ * inserted — `skip`/`replace` rows already had `dest_id` set at plan
+ * time).
+ *
+ * `skip`-action rows are deliberately excluded from the `SET` target
+ * (via the `p.action IN (...)` filter) — a `skip` row's `content_items`
+ * row belongs to a PRIOR, better-ranked source, and this (losing) source
+ * has no business touching its `redirect_dest_id`.
+ *
+ * Must run AFTER both
+ * {@link import('./insert-content-items.js').insertContentItems} and
+ * {@link import('./replace-content-items.js').replaceContentItems} —
+ * every plan row needs a resolved `dest_id` (its own AND its redirect
+ * target's) before this can run. A source row whose `redirect_dest_id`
+ * points outside this source's own plan (should not happen — concat's
+ * plan covers every source row, and split's plan closure always pulls a
+ * kept row's redirect target in too, see `plan-content-items-for-split.ts`)
+ * silently leaves that destination row's `redirect_dest_id` at `NULL`
+ * rather than erroring — a dangling-but-absent redirect is a safe
+ * degrade, never a wrong one.
+ * @param trx - Transaction with the source ATTACHed as
+ *   {@link TRANSFER_SOURCE_ALIAS}.
+ * @example
+ * ```ts
+ * await insertContentItems(trx, { crawlOrderOffset: 0 });
+ * await remapRedirectDestIds(trx);
+ * ```
+ */
+export async function remapRedirectDestIds(trx) {
+    await trx.raw(`
+		UPDATE main.content_items
+		SET redirect_dest_id = x.redirect_dest_id
+		FROM (
+			SELECT p.dest_id AS id, p2.dest_id AS redirect_dest_id
+			FROM xfer_ci_plan p
+			JOIN ${TRANSFER_SOURCE_ALIAS}.content_items s ON s.id = p.src_id
+			JOIN xfer_ci_plan p2 ON p2.src_id = s.redirect_dest_id
+			WHERE s.redirect_dest_id IS NOT NULL
+				AND p.action IN (${TRANSFER_ACTION.full}, ${TRANSFER_ACTION.stub}, ${TRANSFER_ACTION.replace})
+				AND p2.dest_id IS NOT NULL
+		) x
+		WHERE main.content_items.id = x.id
+			AND x.redirect_dest_id != x.id
+	`);
+}

package/lib/transfer/replace-content-items.d.ts

@@ -0,0 +1,39 @@
+import type { Knex } from 'knex';
+/**
+ * Overwrites every `replace`-action destination `content_items` row
+ * (concat only — split never assigns `replace`) with this source's
+ * column values, using the same per-column remap rules
+ * {@link import('./insert-content-items.js').insertContentItems} applies
+ * (dictionary FKs through their `temp.xfer_map_*` table, `redirect_dest_id`/
+ * `alias_of_id`/`dedupe_cap_event_id` always `NULL`, `crawl_order` offset).
+ *
+ * `url_id` is deliberately excluded from the UPDATE — a `replace` row was
+ * matched by URL string in the first place (`plan-content-items-for-concat.ts`),
+ * so the destination's `url_id` already points at the correct `url_refs`
+ * row and must not change. `is_external`/`is_target` are never forced
+ * here (unlike `insertContentItems`'s `stub` case) — concat has no stub
+ * action, so the source's own observed values pass straight through the
+ * generic `default` branch.
+ *
+ * Must run BEFORE {@link import('./insert-content-items.js').insertContentItems}
+ * would otherwise be fine in either order relative to it (they touch
+ * disjoint plan actions), but MUST run before the page-scoped table
+ * copies (`copy-page-meta.ts` et al.) — and after
+ * {@link import('./clear-replaced-page-rows.js').clearReplacedPageRows}
+ * has deleted the old derived rows for these same destination ids, so the
+ * fresh page-scoped copy does not collide with stale data.
+ * @param trx - Transaction with the source ATTACHed as
+ *   {@link TRANSFER_SOURCE_ALIAS}.
+ * @param options - Options.
+ * @param options.crawlOrderOffset - See `insertContentItems`'s parameter
+ *   of the same name — the same value passed to that call for this source.
+ * @example
+ * ```ts
+ * await clearReplacedPageRows(trx);
+ * await replaceContentItems(trx, { crawlOrderOffset: 0 });
+ * await insertContentItems(trx, { crawlOrderOffset: 0 });
+ * ```
+ */
+export declare function replaceContentItems(trx: Knex, options: {
+    crawlOrderOffset: number;
+}): Promise<void>;

package/lib/transfer/replace-content-items.js

@@ -0,0 +1,83 @@
+import { listTransferColumns } from './list-transfer-columns.js';
+import { quoteTransferIdentifier } from './quote-transfer-identifier.js';
+import { TRANSFER_ACTION } from './transfer-action.js';
+import { TRANSFER_SOURCE_ALIAS } from './transfer-source-alias.js';
+const SRC = TRANSFER_SOURCE_ALIAS;
+/**
+ * Overwrites every `replace`-action destination `content_items` row
+ * (concat only — split never assigns `replace`) with this source's
+ * column values, using the same per-column remap rules
+ * {@link import('./insert-content-items.js').insertContentItems} applies
+ * (dictionary FKs through their `temp.xfer_map_*` table, `redirect_dest_id`/
+ * `alias_of_id`/`dedupe_cap_event_id` always `NULL`, `crawl_order` offset).
+ *
+ * `url_id` is deliberately excluded from the UPDATE — a `replace` row was
+ * matched by URL string in the first place (`plan-content-items-for-concat.ts`),
+ * so the destination's `url_id` already points at the correct `url_refs`
+ * row and must not change. `is_external`/`is_target` are never forced
+ * here (unlike `insertContentItems`'s `stub` case) — concat has no stub
+ * action, so the source's own observed values pass straight through the
+ * generic `default` branch.
+ *
+ * Must run BEFORE {@link import('./insert-content-items.js').insertContentItems}
+ * would otherwise be fine in either order relative to it (they touch
+ * disjoint plan actions), but MUST run before the page-scoped table
+ * copies (`copy-page-meta.ts` et al.) — and after
+ * {@link import('./clear-replaced-page-rows.js').clearReplacedPageRows}
+ * has deleted the old derived rows for these same destination ids, so the
+ * fresh page-scoped copy does not collide with stale data.
+ * @param trx - Transaction with the source ATTACHed as
+ *   {@link TRANSFER_SOURCE_ALIAS}.
+ * @param options - Options.
+ * @param options.crawlOrderOffset - See `insertContentItems`'s parameter
+ *   of the same name — the same value passed to that call for this source.
+ * @example
+ * ```ts
+ * await clearReplacedPageRows(trx);
+ * await replaceContentItems(trx, { crawlOrderOffset: 0 });
+ * await insertContentItems(trx, { crawlOrderOffset: 0 });
+ * ```
+ */
+export async function replaceContentItems(trx, options) {
+    const columns = await listTransferColumns(trx, SRC, 'content_items', ['id', 'url_id']);
+    const setList = columns
+        .map((col) => `${quoteTransferIdentifier(col)} = x.${quoteTransferIdentifier(col)}`)
+        .join(', ');
+    const selectList = columns
+        .map((col) => {
+        const quotedCol = quoteTransferIdentifier(col);
+        switch (col) {
+            case 'content_type_id': {
+                return `mct.dest_id AS ${quotedCol}`;
+            }
+            case 'header_set_id': {
+                return `mhs.dest_id AS ${quotedCol}`;
+            }
+            case 'redirect_dest_id':
+            case 'alias_of_id':
+            case 'dedupe_cap_event_id': {
+                return `NULL AS ${quotedCol}`;
+            }
+            case 'crawl_order': {
+                return `s.crawl_order + ${options.crawlOrderOffset} AS ${quotedCol}`;
+            }
+            default: {
+                return `s.${quotedCol} AS ${quotedCol}`;
+            }
+        }
+    })
+        .join(', ');
+    await trx.raw(`
+		UPDATE main.content_items
+		SET ${setList}
+		FROM (
+			SELECT p.dest_id AS dest_id, ${selectList}
+			FROM xfer_ci_plan p
+			JOIN ${SRC}.content_items s ON s.id = p.src_id
+			LEFT JOIN xfer_map_content_type_refs mct ON mct.src_id = s.content_type_id
+			LEFT JOIN xfer_map_header_sets mhs ON mhs.src_id = s.header_set_id
+			WHERE p.action = ${TRANSFER_ACTION.replace}
+		) x
+		WHERE main.content_items.id = x.dest_id
+	`);
+}

package/lib/transfer/simple-page-scoped-tables.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Every page-scoped table whose only FK column is its own page reference
+ * — no dictionary or cross-entity FK columns to remap, so every other
+ * column passes through unchanged. Covers the 9
+ * beholder-`MainContentsData` sub-entity tables, the technology-detection
+ * pair (always updated together, per ARCHITECTURE.md's pairing
+ * invariant — copying both in the same call keeps that true here too),
+ * `page_jsonld`, `page_errors`, `page_html_ref` (`hash` is the content-
+ * addressed identity of a `page_html_blobs` row, identical in every archive,
+ * so it passes through once `copy-page-html-blobs.ts` has copied the blob),
+ * and `page_templates` (`template_key` is a plain string column, not a
+ * dictionary FK — see `copy-page-template-clusters.ts` for its paired
+ * cluster-evidence table).
+ *
+ * Shared between {@link import('./copy-simple-page-scoped-tables.js').copySimplePageScopedTables}
+ * (what to copy verbatim) and
+ * {@link import('./clear-replaced-page-rows.js').clearReplacedPageRows}
+ * (a subset of what to delete for a `replace`d page) — a single list here
+ * means a future page-scoped table only needs adding in one place to stay
+ * consistent between the two operations.
+ */
+export declare const SIMPLE_PAGE_SCOPED_TABLES: readonly {
+    table: string;
+    pageColumn: string;
+}[];

package/lib/transfer/simple-page-scoped-tables.js

@@ -0,0 +1,38 @@
+/**
+ * Every page-scoped table whose only FK column is its own page reference
+ * — no dictionary or cross-entity FK columns to remap, so every other
+ * column passes through unchanged. Covers the 9
+ * beholder-`MainContentsData` sub-entity tables, the technology-detection
+ * pair (always updated together, per ARCHITECTURE.md's pairing
+ * invariant — copying both in the same call keeps that true here too),
+ * `page_jsonld`, `page_errors`, `page_html_ref` (`hash` is the content-
+ * addressed identity of a `page_html_blobs` row, identical in every archive,
+ * so it passes through once `copy-page-html-blobs.ts` has copied the blob),
+ * and `page_templates` (`template_key` is a plain string column, not a
+ * dictionary FK — see `copy-page-template-clusters.ts` for its paired
+ * cluster-evidence table).
+ *
+ * Shared between {@link import('./copy-simple-page-scoped-tables.js').copySimplePageScopedTables}
+ * (what to copy verbatim) and
+ * {@link import('./clear-replaced-page-rows.js').clearReplacedPageRows}
+ * (a subset of what to delete for a `replace`d page) — a single list here
+ * means a future page-scoped table only needs adding in one place to stay
+ * consistent between the two operations.
+ */
+export const SIMPLE_PAGE_SCOPED_TABLES = [
+    { table: 'page_main_content_headings', pageColumn: 'pageId' },
+    { table: 'page_main_content_images', pageColumn: 'pageId' },
+    { table: 'page_main_content_tables', pageColumn: 'pageId' },
+    { table: 'page_main_content_buttons', pageColumn: 'pageId' },
+    { table: 'page_main_content_iframes', pageColumn: 'pageId' },
+    { table: 'page_main_content_videos', pageColumn: 'pageId' },
+    { table: 'page_main_content_audios', pageColumn: 'pageId' },
+    { table: 'page_main_content_canvases', pageColumn: 'pageId' },
+    { table: 'page_main_content_custom_elements', pageColumn: 'pageId' },
+    { table: 'technology_signals', pageColumn: 'pageId' },
+    { table: 'page_technologies', pageColumn: 'pageId' },
+    { table: 'page_jsonld', pageColumn: 'pageId' },
+    { table: 'page_errors', pageColumn: 'pageId' },
+    { table: 'page_html_ref', pageColumn: 'page_id' },
+    { table: 'page_templates', pageColumn: 'page_id' },
+];

package/lib/transfer/split-archive.d.ts

@@ -0,0 +1,55 @@
+import type { ArchiveAccessor } from '../archive-accessor.js';
+import type Archive from '../archive.js';
+import type { SplitArchiveResult, TransferCallbacks } from './types.js';
+/**
+ * Extracts the subset of one read-only-opened source archive within the
+ * given scope URLs into an already `Archive.create`d, empty destination —
+ * the crawler-side half of the `split` CLI command. Does not open/close/
+ * write anything itself; see `concat-archives.ts`'s docs for the same
+ * lifecycle-ownership split (the CLI's `commands/split.ts` owns open →
+ * transfer → rebuild-read-model → write).
+ *
+ * Rejects a `fromList` source up front — see `build-split-config.ts`'s
+ * docs for why "roots = the given scope" has no coherent meaning for an
+ * archive whose `roots` is a URL list rather than a scope.
+ *
+ * `flattenRedirectChains` still runs even though a single, not-yet-merged
+ * source is already flat by construction — a cheap no-op, kept for the
+ * same reason `reclassifyResourceExternality` is written mode-agnostic
+ * rather than split having its own near-duplicate of each.
+ * @param options - See individual properties.
+ * @param options.source - The source, read-only opened
+ *   (`Archive.openCached`).
+ * @param options.source.path
+ * @param options.source.accessor
+ * @param options.scopeUrls - The scope URLs the operator gave (raw
+ *   strings; normalised to `withoutHash` form by
+ *   {@link import('./build-split-config.js').buildSplitConfig}).
+ * @param options.destination - The empty destination, already
+ *   `Archive.create`d by the caller.
+ * @param options.name - The output archive's `name` config field.
+ * @param options.callbacks - Progress callbacks; see `types.ts`.
+ * @returns The derived config and the transfer outcome.
+ * @throws {Error} If the source is a `fromList` archive, or `scopeUrls` is empty.
+ * @example
+ * ```ts
+ * const destination = await Archive.create({ filePath: outputPath, cwd });
+ * const accessor = await Archive.openCached(archivePath);
+ * const result = await splitArchive({
+ *   source: { path: archivePath, accessor },
+ *   scopeUrls: ['https://example.com/blog/'],
+ *   destination,
+ *   name: 'blog',
+ * });
+ * ```
+ */
+export declare function splitArchive(options: {
+    readonly source: {
+        readonly accessor: ArchiveAccessor;
+        readonly path: string;
+    };
+    readonly scopeUrls: readonly string[];
+    readonly destination: Archive;
+    readonly name: string;
+    readonly callbacks?: TransferCallbacks;
+}): Promise<SplitArchiveResult>;

package/lib/transfer/split-archive.js

@@ -0,0 +1,98 @@
+import path from 'node:path';
+import ArchiveDefault from '../archive.js';
+import { buildScopeMap } from '../scope/build-scope-map.js';
+import { buildSplitConfig } from './build-split-config.js';
+import { copyInventorySourceLists } from './copy-inventory-source-lists.js';
+import { countExternalPagesInScope } from './count-external-pages-in-scope.js';
+import { flattenRedirectChains } from './flatten-redirect-chains.js';
+import { reclassifyResourceExternality } from './reclassify-resource-externality.js';
+import { transferArchiveRows } from './transfer-archive-rows.js';
+/**
+ * Extracts the subset of one read-only-opened source archive within the
+ * given scope URLs into an already `Archive.create`d, empty destination —
+ * the crawler-side half of the `split` CLI command. Does not open/close/
+ * write anything itself; see `concat-archives.ts`'s docs for the same
+ * lifecycle-ownership split (the CLI's `commands/split.ts` owns open →
+ * transfer → rebuild-read-model → write).
+ *
+ * Rejects a `fromList` source up front — see `build-split-config.ts`'s
+ * docs for why "roots = the given scope" has no coherent meaning for an
+ * archive whose `roots` is a URL list rather than a scope.
+ *
+ * `flattenRedirectChains` still runs even though a single, not-yet-merged
+ * source is already flat by construction — a cheap no-op, kept for the
+ * same reason `reclassifyResourceExternality` is written mode-agnostic
+ * rather than split having its own near-duplicate of each.
+ * @param options - See individual properties.
+ * @param options.source - The source, read-only opened
+ *   (`Archive.openCached`).
+ * @param options.source.path
+ * @param options.source.accessor
+ * @param options.scopeUrls - The scope URLs the operator gave (raw
+ *   strings; normalised to `withoutHash` form by
+ *   {@link import('./build-split-config.js').buildSplitConfig}).
+ * @param options.destination - The empty destination, already
+ *   `Archive.create`d by the caller.
+ * @param options.name - The output archive's `name` config field.
+ * @param options.callbacks - Progress callbacks; see `types.ts`.
+ * @returns The derived config and the transfer outcome.
+ * @throws {Error} If the source is a `fromList` archive, or `scopeUrls` is empty.
+ * @example
+ * ```ts
+ * const destination = await Archive.create({ filePath: outputPath, cwd });
+ * const accessor = await Archive.openCached(archivePath);
+ * const result = await splitArchive({
+ *   source: { path: archivePath, accessor },
+ *   scopeUrls: ['https://example.com/blog/'],
+ *   destination,
+ *   name: 'blog',
+ * });
+ * ```
+ */
+export async function splitArchive(options) {
+    const { source, scopeUrls, destination, name, callbacks } = options;
+    const sourceConfig = await source.accessor.getConfig();
+    if (sourceConfig.fromList) {
+        throw new Error('split: cannot split a --list/--list-file archive — its roots are a URL list, ' +
+            'not a scope, so "roots = the given scope" has no coherent meaning for it.');
+    }
+    const config = buildSplitConfig(sourceConfig, scopeUrls, name);
+    await destination.setConfig(config);
+    const knex = destination.getKnex();
+    const scope = buildScopeMap(config.roots, config);
+    callbacks?.onSourceStart?.(0, source.path);
+    const sourceDbPath = path.join(source.accessor.tmpDir, ArchiveDefault.SQLITE_DB_FILE_NAME);
+    const result = await transferArchiveRows({
+        knex,
+        sourceDbPath,
+        mode: { kind: 'split', scopeMap: scope, parseOptions: config },
+        crawlOrderOffset: 0,
+        sourceIndex: 0,
+        callbacks,
+    });
+    if (result.inserted === 0) {
+        throw new Error('split: no page inside the given scope was found in the source archive — nothing to extract.');
+    }
+    callbacks?.onPhase?.(1, 'flatteningRedirects');
+    await flattenRedirectChains(knex);
+    callbacks?.onPhase?.(1, 'reclassifyingResources');
+    await reclassifyResourceExternality(knex, scope, config);
+    callbacks?.onPhase?.(1, 'countingExternalInScope');
+    // Not always 0: the operator's scope URLs are not required to be a
+    // SUBSET of the source's original roots. A split scope broader than (or
+    // merely different from) the original roots can bring a page that was
+    // only ever recorded as an external link (never crawled under the
+    // source's narrower original scope) inside the new scope — the same
+    // "still external, never fabricate a scrape" rule concat's own
+    // `externalInScopeCount` documents.
+    const externalInScopeCount = await countExternalPagesInScope(knex, scope, config);
+    const inventoryListsCopied = await copyInventorySourceLists(destination, [
+        source.accessor.tmpDir,
+    ]);
+    return {
+        config,
+        source: result,
+        externalInScopeCount,
+        inventoryListsCopied,
+    };
+}

package/lib/transfer/split-source-transfer-phases.d.ts

@@ -0,0 +1,11 @@
+import type { TransferPhase } from './types.js';
+/**
+ * Ordered phase sequence {@link import('./transfer-archive-rows.js').transferArchiveRows}
+ * announces via `onPhase` for split's single source — identical to
+ * {@link import('./concat-source-transfer-phases.js').CONCAT_SOURCE_TRANSFER_PHASES}
+ * (the phase sequence inside `transferArchiveRows` does not branch on
+ * mode, only what each phase DOES differs), kept as its own named export
+ * so a CLI caller building split's `TaskList` rows never has to reason
+ * about why it is importing something named "concat".
+ */
+export declare const SPLIT_SOURCE_TRANSFER_PHASES: readonly TransferPhase[];

package/lib/transfer/split-source-transfer-phases.js

@@ -0,0 +1,18 @@
+/**
+ * Ordered phase sequence {@link import('./transfer-archive-rows.js').transferArchiveRows}
+ * announces via `onPhase` for split's single source — identical to
+ * {@link import('./concat-source-transfer-phases.js').CONCAT_SOURCE_TRANSFER_PHASES}
+ * (the phase sequence inside `transferArchiveRows` does not branch on
+ * mode, only what each phase DOES differs), kept as its own named export
+ * so a CLI caller building split's `TaskList` rows never has to reason
+ * about why it is importing something named "concat".
+ */
+export const SPLIT_SOURCE_TRANSFER_PHASES = [
+    'planningContentItems',
+    'copyingDictionaries',
+    'copyingContentItems',
+    'copyingPageRows',
+    'copyingResources',
+    'copyingJournals',
+    'committing',
+];

package/lib/transfer/transfer-action.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The action a `content_items` transfer plan (`temp.xfer_ci_plan`) assigns
+ * to each source row, stored as a small integer so the plan table can be
+ * queried/joined without a TEXT comparison.
+ *
+ * - `full` — insert the source row (and its page-scoped data) as a
+ *   brand-new destination row. Used by both concat (no existing dest row
+ *   for this URL yet) and split (in-scope, kept in full).
+ * - `stub` — insert only the `content_items` row itself, forced to
+ *   `is_external = 1` / `is_target = 0`; no `page_meta` or any other
+ *   page-scoped row is copied. Split-only — an out-of-scope page that a
+ *   kept page still references (an anchor target or a redirect
+ *   destination).
+ * - `replace` — an existing destination row for this URL is overwritten
+ *   because this source's observation outranks it (see
+ *   `content-item-rank-sql.ts`). Concat-only.
+ * - `skip` — the source row is not copied at all; the destination already
+ *   holds an equal-or-better observation for this URL. Concat-only.
+ *
+ * `full` and `stub` are the only actions {@link
+ * import('./plan-content-items-for-split.js').planContentItemsForSplit}
+ * ever assigns; `full`, `replace`, and `skip` are the only actions {@link
+ * import('./plan-content-items-for-concat.js').planContentItemsForConcat}
+ * ever assigns — a row not present in the plan at all means "dropped"
+ * (split-only: out of scope and unreferenced by anything kept).
+ */
+export declare const TRANSFER_ACTION: {
+    readonly full: 1;
+    readonly stub: 2;
+    readonly replace: 3;
+    readonly skip: 4;
+};
+/** Union of {@link TRANSFER_ACTION}'s values. */
+export type TransferAction = (typeof TRANSFER_ACTION)[keyof typeof TRANSFER_ACTION];

package/lib/transfer/transfer-action.js

@@ -0,0 +1,32 @@
+/**
+ * The action a `content_items` transfer plan (`temp.xfer_ci_plan`) assigns
+ * to each source row, stored as a small integer so the plan table can be
+ * queried/joined without a TEXT comparison.
+ *
+ * - `full` — insert the source row (and its page-scoped data) as a
+ *   brand-new destination row. Used by both concat (no existing dest row
+ *   for this URL yet) and split (in-scope, kept in full).
+ * - `stub` — insert only the `content_items` row itself, forced to
+ *   `is_external = 1` / `is_target = 0`; no `page_meta` or any other
+ *   page-scoped row is copied. Split-only — an out-of-scope page that a
+ *   kept page still references (an anchor target or a redirect
+ *   destination).
+ * - `replace` — an existing destination row for this URL is overwritten
+ *   because this source's observation outranks it (see
+ *   `content-item-rank-sql.ts`). Concat-only.
+ * - `skip` — the source row is not copied at all; the destination already
+ *   holds an equal-or-better observation for this URL. Concat-only.
+ *
+ * `full` and `stub` are the only actions {@link
+ * import('./plan-content-items-for-split.js').planContentItemsForSplit}
+ * ever assigns; `full`, `replace`, and `skip` are the only actions {@link
+ * import('./plan-content-items-for-concat.js').planContentItemsForConcat}
+ * ever assigns — a row not present in the plan at all means "dropped"
+ * (split-only: out of scope and unreferenced by anything kept).
+ */
+export const TRANSFER_ACTION = {
+    full: 1,
+    stub: 2,
+    replace: 3,
+    skip: 4,
+};

package/lib/transfer/transfer-archive-rows.d.ts

@@ -0,0 +1,65 @@
+import type { TransferCallbacks, TransferSourceResult } from './types.js';
+import type { ExURL, ParseURLOptions } from '@d-zero/shared/parse-url';
+import type { Knex } from 'knex';
+/** One source's transfer mode and (for split) scope-check inputs. */
+export type TransferSourceMode = {
+    readonly kind: 'concat';
+} | {
+    readonly kind: 'split';
+    readonly scopeMap: ReadonlyMap<string, readonly ExURL[]>;
+    readonly parseOptions?: ParseURLOptions;
+};
+/**
+ * Transfers ONE source archive's rows into the destination — the shared
+ * engine {@link import('./concat-archives.js').concatArchives} and
+ * {@link import('./split-archive.js').splitArchive} both drive, once per
+ * source. Attaches the source, plans, copies every table in dependency
+ * order, and detaches — always, even on failure (`finally`).
+ *
+ * Order within the transaction (see each step's own docs for why this
+ * exact order, not a different one):
+ * 1. Plan `content_items` (mode-specific) and `resource_items`.
+ * 2. Copy every dictionary (mode-specific), then their `header_sets`
+ *    children and `page_html_blobs` (both depend on the dictionary maps
+ *    dictionaries step just built).
+ * 3. Concat only: clear the old page-scoped rows of every `replace`
+ *    destination, then overwrite its `content_items` row. Both modes:
+ *    insert every `full`/`stub` row, backfilling `dest_id`; remap
+ *    `redirect_dest_id` now that every row has one.
+ * 4. Copy every page-scoped table.
+ * 5. Copy `resource_items` (and its js-scan cache), then
+ *    `resource_ref_edges` (needs the resource plan's `dest_id`, just
+ *    resolved).
+ * 6. Copy the append-only journal tables.
+ * @param options - See individual properties.
+ * @param options.knex - Knex connected to the destination archive DB (the
+ *   connection ATTACH/temp-tables/transaction all operate against).
+ * @param options.sourceDbPath - Absolute path to the source's `db.sqlite`
+ *   (e.g. `path.join(accessor.tmpDir, Archive.SQLITE_DB_FILE_NAME)`).
+ * @param options.mode - `{ kind: 'concat' }`, or `{ kind: 'split',
+ *   scopeMap, parseOptions? }` for the narrower-scope pass.
+ * @param options.crawlOrderOffset - Forwarded to
+ *   `insertContentItems`/`replaceContentItems` — see their docs.
+ * @param options.sourceIndex - This source's 0-based position, forwarded
+ *   verbatim to `callbacks` — purely for display, not used in any query.
+ * @param options.callbacks - Progress callbacks; see `types.ts`.
+ * @returns Per-action row counts — see {@link TransferSourceResult}.
+ * @example
+ * ```ts
+ * const result = await transferArchiveRows({
+ *   knex: destination.getKnex(),
+ *   sourceDbPath: path.join(accessor.tmpDir, Archive.SQLITE_DB_FILE_NAME),
+ *   mode: { kind: 'concat' },
+ *   crawlOrderOffset: 0,
+ *   sourceIndex: 0,
+ * });
+ * ```
+ */
+export declare function transferArchiveRows(options: {
+    readonly knex: Knex;
+    readonly sourceDbPath: string;
+    readonly mode: TransferSourceMode;
+    readonly crawlOrderOffset: number;
+    readonly sourceIndex: number;
+    readonly callbacks?: TransferCallbacks;
+}): Promise<TransferSourceResult>;