@nitpicker/archive 0.0.0-stage → 0.25.0

package/lib/populate-entity-tables/upsert-text-refs.js

@@ -0,0 +1,78 @@
+import { computeContentHash } from '../populate-ref-tables/compute-content-hash.js';
+/**
+ * Rows sent per `INSERT INTO text_refs ... VALUES (...)` statement. Each
+ * row binds 2 params (hash + text) so 500 rows = 1 000 params — well
+ * under the SQLite variable limit.
+ */
+const INSERT_CHUNK_SIZE = 500;
+/**
+ * Rows sent per `SELECT ... WHERE hash IN (?, ...)` chunk on the
+ * post-insert read-back. Same reasoning as {@link ./resolve-text-refs.ts}.
+ */
+const LOOKUP_CHUNK_SIZE = 800;
+/**
+ * Upserts a set of text strings into `text_refs` and returns their ids
+ * (issue #193).
+ *
+ * Unlike {@link ./resolve-text-refs.ts}, which only reads, this helper
+ * inserts every missing string first. It exists specifically for
+ * `dom_path` strings, which are synthesised by the image-items populate
+ * ({@link ./populate-image-items.ts}) and are not among the columns the
+ * `text_refs` populate scans
+ * ({@link ../populate-ref-tables/populate-text-refs.ts}) — the caller
+ * cannot rely on the dictionary already containing them.
+ *
+ * Strategy:
+ *
+ * 1. **Hash and INSERT OR IGNORE** every input string in bulk. New rows
+ *    materialise; conflicts are silently skipped.
+ * 2. **Read back** by hash + text (the `(hash, text)` UNIQUE composite)
+ *    to pick up both freshly-inserted and pre-existing ids.
+ *
+ * The read-back narrows on both hash and text (same defensive shape as
+ * {@link ../populate-ref-tables/populate-header-tables.ts}'s `resolveValueIds`) so
+ * an astronomically improbable hash collision cannot leak the wrong
+ * id back to the caller.
+ *
+ * Empty / null strings are ignored; duplicates in `texts` are deduped
+ * internally.
+ * @param trx - Knex instance or transaction connected to the archive DB.
+ * @param texts - Iterable of text strings to upsert.
+ * @returns Map keyed by the raw text string.
+ * @example
+ * const idMap = await upsertTextRefs(trx, [
+ *   'html/body[1]/img[1]',
+ *   'unknown/42',
+ * ]);
+ */
+export async function upsertTextRefs(trx, texts) {
+    const distinct = new Set();
+    for (const text of texts) {
+        if (typeof text === 'string' && text !== '') {
+            distinct.add(text);
+        }
+    }
+    if (distinct.size === 0) {
+        return new Map();
+    }
+    const values = [...distinct];
+    const hashes = values.map((text) => computeContentHash(text));
+    const inserts = values.map((text, index) => ({ hash: hashes[index], text }));
+    for (let index = 0; index < inserts.length; index += INSERT_CHUNK_SIZE) {
+        const chunk = inserts.slice(index, index + INSERT_CHUNK_SIZE);
+        await trx('text_refs').insert(chunk).onConflict(['hash', 'text']).ignore();
+    }
+    const result = new Map();
+    for (let index = 0; index < values.length; index += LOOKUP_CHUNK_SIZE) {
+        const chunkValues = values.slice(index, index + LOOKUP_CHUNK_SIZE);
+        const chunkHashes = hashes.slice(index, index + LOOKUP_CHUNK_SIZE);
+        const rows = await trx('text_refs')
+            .select('id', 'hash', 'text')
+            .whereIn('hash', chunkHashes)
+            .whereIn('text', chunkValues);
+        for (const row of rows) {
+            result.set(row.text, row.id);
+        }
+    }
+    return result;
+}

package/lib/populate-ref-tables/classify-content-type.d.ts

@@ -0,0 +1,16 @@
+import type { ContentTypeCategory } from './types.js';
+/**
+ * Classifies a raw HTTP `Content-Type` header value into the same coarse
+ * categories used by the viewer read-model. The rule table in
+ * `content-type-rules.ts` is evaluated in declared order and the first
+ * matching rule wins (so `application/xhtml+xml` → `html` and
+ * `image/svg+xml` → `image`).
+ *
+ * `null` / empty / whitespace-only inputs map to `'unknown'`; MIMEs that
+ * fail every rule map to `'other'`. Behaviour mirrors
+ * `@nitpicker/query`'s `classifyContentType`; see the type header of
+ * `content-type-rules.ts` for the drift-warning contract.
+ * @param contentType - The raw `Content-Type` header value, or `null`.
+ * @returns The canonical category label.
+ */
+export declare function classifyContentType(contentType: string | null): ContentTypeCategory;

package/lib/populate-ref-tables/classify-content-type.js

@@ -0,0 +1,52 @@
+import { CONTENT_TYPE_RULES } from './content-type-rules.js';
+/**
+ * Classifies a raw HTTP `Content-Type` header value into the same coarse
+ * categories used by the viewer read-model. The rule table in
+ * `content-type-rules.ts` is evaluated in declared order and the first
+ * matching rule wins (so `application/xhtml+xml` → `html` and
+ * `image/svg+xml` → `image`).
+ *
+ * `null` / empty / whitespace-only inputs map to `'unknown'`; MIMEs that
+ * fail every rule map to `'other'`. Behaviour mirrors
+ * `@nitpicker/query`'s `classifyContentType`; see the type header of
+ * `content-type-rules.ts` for the drift-warning contract.
+ * @param contentType - The raw `Content-Type` header value, or `null`.
+ * @returns The canonical category label.
+ */
+export function classifyContentType(contentType) {
+    if (contentType == null) {
+        return 'unknown';
+    }
+    const semi = contentType.indexOf(';');
+    const head = (semi === -1 ? contentType : contentType.slice(0, semi))
+        .trim()
+        .toLowerCase();
+    if (head === '') {
+        return 'unknown';
+    }
+    for (const rule of CONTENT_TYPE_RULES) {
+        for (const matcher of rule.matchers) {
+            switch (matcher.kind) {
+                case 'exact': {
+                    if (head === matcher.value) {
+                        return rule.category;
+                    }
+                    break;
+                }
+                case 'prefix': {
+                    if (head.startsWith(matcher.value)) {
+                        return rule.category;
+                    }
+                    break;
+                }
+                case 'suffix': {
+                    if (head.endsWith(matcher.value)) {
+                        return rule.category;
+                    }
+                    break;
+                }
+            }
+        }
+    }
+    return 'other';
+}

package/lib/populate-ref-tables/compute-content-hash.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Computes a 32-byte content hash for a UTF-8 string or raw byte buffer.
+ *
+ * The hash columns on `text_refs`, `json_refs`, `blob_refs`,
+ * `header_value_refs`, and `header_sets` use **SHA-256** rather than a
+ * faster candidate such as BLAKE3, for three reasons:
+ *
+ * 1. **No new dependency**. `@nitpicker/archive`'s dependency list is small
+ *    and CLAUDE.md's supply-chain rules discourage adding a hash-only lib.
+ * 2. **Consistency**. `page_html_blobs.hash` — the existing content-addressable
+ *    dictionary — is SHA-256 (see `Database.#writePageHtmlBlob`). Using the
+ *    same algorithm keeps every content-hash column in the archive on one
+ *    scheme.
+ * 3. **Column contract is length-only**. Every 0.13 hash column is typed
+ *    `BLOB` (32 bytes when populated). SHA-256 satisfies that contract.
+ *
+ * If BLAKE3 is later required for throughput, this single function is the only
+ * edit point — every callsite in 0.13 routes through here.
+ * @param value - Value to hash. `string` inputs are encoded as UTF-8.
+ * @returns 32-byte hash as a `Buffer`, ready to insert into a `BLOB` column.
+ */
+export declare function computeContentHash(value: string | Uint8Array): Buffer;

package/lib/populate-ref-tables/compute-content-hash.js

@@ -0,0 +1,26 @@
+import { createHash } from 'node:crypto';
+/**
+ * Computes a 32-byte content hash for a UTF-8 string or raw byte buffer.
+ *
+ * The hash columns on `text_refs`, `json_refs`, `blob_refs`,
+ * `header_value_refs`, and `header_sets` use **SHA-256** rather than a
+ * faster candidate such as BLAKE3, for three reasons:
+ *
+ * 1. **No new dependency**. `@nitpicker/archive`'s dependency list is small
+ *    and CLAUDE.md's supply-chain rules discourage adding a hash-only lib.
+ * 2. **Consistency**. `page_html_blobs.hash` — the existing content-addressable
+ *    dictionary — is SHA-256 (see `Database.#writePageHtmlBlob`). Using the
+ *    same algorithm keeps every content-hash column in the archive on one
+ *    scheme.
+ * 3. **Column contract is length-only**. Every 0.13 hash column is typed
+ *    `BLOB` (32 bytes when populated). SHA-256 satisfies that contract.
+ *
+ * If BLAKE3 is later required for throughput, this single function is the only
+ * edit point — every callsite in 0.13 routes through here.
+ * @param value - Value to hash. `string` inputs are encoded as UTF-8.
+ * @returns 32-byte hash as a `Buffer`, ready to insert into a `BLOB` column.
+ */
+export function computeContentHash(value) {
+    const bytes = typeof value === 'string' ? Buffer.from(value, 'utf8') : value;
+    return createHash('sha256').update(bytes).digest();
+}

package/lib/populate-ref-tables/compute-header-flags.d.ts

@@ -0,0 +1,16 @@
+import type { HeaderEntry, HeaderFlagsRow } from './types.js';
+/**
+ * Computes the {@link HeaderFlagsRow} for one decomposed header set.
+ *
+ * Each `has_*` boolean is a straight "is this name present" check on the
+ * decomposed entries — semantically equivalent to `checkHeaders` /
+ * `headerPresenceExpression` in `@nitpicker/query`, but expressed in JS
+ * over the already-normalized `HeaderEntry.name` (lower-cased) so no
+ * `LIKE` pattern is needed. This drops the JSON-key-shape false-positive
+ * risk that `headerPresenceExpression`'s SQL guard against (a value that
+ * happens to mention another header's name won't fire here because names
+ * come from the parsed JSON's KEYS, not from a substring scan).
+ * @param entries - Every decomposed entry for one `header_sets` row.
+ * @returns The row-shaped flags to insert into `header_flags`.
+ */
+export declare function computeHeaderFlags(entries: readonly HeaderEntry[]): HeaderFlagsRow;

package/lib/populate-ref-tables/compute-header-flags.js

@@ -0,0 +1,70 @@
+/**
+ * Computes the {@link HeaderFlagsRow} for one decomposed header set.
+ *
+ * Each `has_*` boolean is a straight "is this name present" check on the
+ * decomposed entries — semantically equivalent to `checkHeaders` /
+ * `headerPresenceExpression` in `@nitpicker/query`, but expressed in JS
+ * over the already-normalized `HeaderEntry.name` (lower-cased) so no
+ * `LIKE` pattern is needed. This drops the JSON-key-shape false-positive
+ * risk that `headerPresenceExpression`'s SQL guard against (a value that
+ * happens to mention another header's name won't fire here because names
+ * come from the parsed JSON's KEYS, not from a substring scan).
+ * @param entries - Every decomposed entry for one `header_sets` row.
+ * @returns The row-shaped flags to insert into `header_flags`.
+ */
+export function computeHeaderFlags(entries) {
+    const cachePolicies = [];
+    let hasCsp = false;
+    let hasXFrameOptions = false;
+    let hasXContentTypeOptions = false;
+    let hasHsts = false;
+    let hasReferrerPolicy = false;
+    let hasPermissionsPolicy = false;
+    let hasSetCookie = false;
+    for (const entry of entries) {
+        switch (entry.name) {
+            case 'content-security-policy': {
+                hasCsp = true;
+                break;
+            }
+            case 'x-frame-options': {
+                hasXFrameOptions = true;
+                break;
+            }
+            case 'x-content-type-options': {
+                hasXContentTypeOptions = true;
+                break;
+            }
+            case 'strict-transport-security': {
+                hasHsts = true;
+                break;
+            }
+            case 'referrer-policy': {
+                hasReferrerPolicy = true;
+                break;
+            }
+            case 'permissions-policy': {
+                hasPermissionsPolicy = true;
+                break;
+            }
+            case 'set-cookie': {
+                hasSetCookie = true;
+                break;
+            }
+            case 'cache-control': {
+                cachePolicies.push(entry.value);
+                break;
+            }
+        }
+    }
+    return {
+        has_csp: hasCsp ? 1 : 0,
+        has_x_frame_options: hasXFrameOptions ? 1 : 0,
+        has_x_content_type_options: hasXContentTypeOptions ? 1 : 0,
+        has_hsts: hasHsts ? 1 : 0,
+        has_referrer_policy: hasReferrerPolicy ? 1 : 0,
+        has_permissions_policy: hasPermissionsPolicy ? 1 : 0,
+        has_set_cookie: hasSetCookie ? 1 : 0,
+        cache_policy: cachePolicies.length === 0 ? null : cachePolicies.join(', '),
+    };
+}

package/lib/populate-ref-tables/content-type-rules.d.ts

@@ -0,0 +1,38 @@
+import type { ContentTypeCategory } from './types.js';
+/**
+ * Single matcher slot for a Content-Type rule. See `@nitpicker/query`'s
+ * `content-type-rules.ts` for the wider design discussion — this file only
+ * carries the subset required for JS-side classification (no SQL builders,
+ * which live in `@nitpicker/query`).
+ */
+type Matcher = {
+    readonly kind: 'exact';
+    readonly value: string;
+} | {
+    readonly kind: 'prefix';
+    readonly value: string;
+} | {
+    readonly kind: 'suffix';
+    readonly value: string;
+};
+/**
+ * One row of the classification table: attach a category to a set of
+ * matchers, all of which OR together.
+ */
+interface Rule {
+    readonly category: Exclude<ContentTypeCategory, 'other' | 'unknown'>;
+    readonly matchers: readonly Matcher[];
+}
+/**
+ * Content-Type classification rules, evaluated in array order — first match
+ * wins. Kept in lock-step with the source-of-truth table in
+ * `packages/@nitpicker/query/src/content-type-rules.ts`. Do not reorder
+ * without also editing the query-side copy (a drift would misroute
+ * `image/svg+xml` between `image` and `xml`, etc.).
+ *
+ * A future cleanup can lift the rule table into `@d-zero/shared` so both
+ * `@nitpicker/archive` and `@nitpicker/query` import a single source of
+ * truth; that migration is out of 0.13's scope.
+ */
+export declare const CONTENT_TYPE_RULES: readonly Rule[];
+export {};

package/lib/populate-ref-tables/content-type-rules.js

@@ -0,0 +1,133 @@
+/**
+ * Content-Type classification rules, evaluated in array order — first match
+ * wins. Kept in lock-step with the source-of-truth table in
+ * `packages/@nitpicker/query/src/content-type-rules.ts`. Do not reorder
+ * without also editing the query-side copy (a drift would misroute
+ * `image/svg+xml` between `image` and `xml`, etc.).
+ *
+ * A future cleanup can lift the rule table into `@d-zero/shared` so both
+ * `@nitpicker/archive` and `@nitpicker/query` import a single source of
+ * truth; that migration is out of 0.13's scope.
+ */
+export const CONTENT_TYPE_RULES = [
+    {
+        category: 'html',
+        matchers: [
+            { kind: 'exact', value: 'text/html' },
+            { kind: 'exact', value: 'application/xhtml+xml' },
+        ],
+    },
+    {
+        category: 'pdf',
+        matchers: [{ kind: 'exact', value: 'application/pdf' }],
+    },
+    {
+        category: 'csv',
+        matchers: [
+            { kind: 'exact', value: 'text/csv' },
+            { kind: 'exact', value: 'application/csv' },
+            { kind: 'exact', value: 'application/x-csv' },
+            { kind: 'exact', value: 'text/tab-separated-values' },
+            { kind: 'exact', value: 'text/tsv' },
+        ],
+    },
+    {
+        category: 'word',
+        matchers: [
+            { kind: 'exact', value: 'application/msword' },
+            {
+                kind: 'exact',
+                value: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+            },
+        ],
+    },
+    {
+        category: 'excel',
+        matchers: [
+            { kind: 'exact', value: 'application/vnd.ms-excel' },
+            {
+                kind: 'exact',
+                value: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+            },
+        ],
+    },
+    {
+        category: 'powerpoint',
+        matchers: [
+            { kind: 'exact', value: 'application/vnd.ms-powerpoint' },
+            {
+                kind: 'exact',
+                value: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+            },
+        ],
+    },
+    {
+        category: 'image',
+        matchers: [{ kind: 'prefix', value: 'image/' }],
+    },
+    {
+        category: 'audio',
+        matchers: [{ kind: 'prefix', value: 'audio/' }],
+    },
+    {
+        category: 'video',
+        matchers: [{ kind: 'prefix', value: 'video/' }],
+    },
+    {
+        category: 'font',
+        matchers: [
+            { kind: 'prefix', value: 'font/' },
+            { kind: 'prefix', value: 'application/font-' },
+            { kind: 'exact', value: 'application/vnd.ms-fontobject' },
+        ],
+    },
+    {
+        category: 'css',
+        matchers: [{ kind: 'exact', value: 'text/css' }],
+    },
+    {
+        category: 'javascript',
+        matchers: [
+            { kind: 'exact', value: 'text/javascript' },
+            { kind: 'exact', value: 'application/javascript' },
+            { kind: 'exact', value: 'application/x-javascript' },
+            { kind: 'exact', value: 'application/ecmascript' },
+        ],
+    },
+    {
+        category: 'json',
+        matchers: [
+            { kind: 'exact', value: 'application/json' },
+            { kind: 'exact', value: 'application/yaml' },
+            { kind: 'exact', value: 'application/x-yaml' },
+            { kind: 'exact', value: 'text/yaml' },
+            { kind: 'exact', value: 'text/x-yaml' },
+            { kind: 'suffix', value: '+json' },
+            { kind: 'suffix', value: '+yaml' },
+        ],
+    },
+    {
+        category: 'xml',
+        matchers: [
+            { kind: 'exact', value: 'application/xml' },
+            { kind: 'exact', value: 'text/xml' },
+            { kind: 'suffix', value: '+xml' },
+        ],
+    },
+    {
+        category: 'archive',
+        matchers: [
+            { kind: 'exact', value: 'application/zip' },
+            { kind: 'exact', value: 'application/gzip' },
+            { kind: 'exact', value: 'application/x-gzip' },
+            { kind: 'exact', value: 'application/x-tar' },
+            { kind: 'exact', value: 'application/x-7z-compressed' },
+            { kind: 'exact', value: 'application/x-rar-compressed' },
+            { kind: 'exact', value: 'application/octet-stream' },
+        ],
+    },
+    {
+        category: 'text',
+        matchers: [{ kind: 'prefix', value: 'text/' }],
+    },
+];

package/lib/populate-ref-tables/create-header-table-caches.d.ts

@@ -0,0 +1,25 @@
+import type { HeaderTableCaches } from './types.js';
+import type { Knex } from 'knex';
+/**
+ * Creates a {@link HeaderTableCaches} bundle warmed from the DB's current
+ * `header_name_refs` / `header_value_refs` / `header_sets` rows.
+ *
+ * Warming lets idempotent re-runs (and resumed / appended crawls against
+ * an archive that already holds header rows) reuse existing ids instead
+ * of re-issuing an upsert per entry. On a fresh archive all three tables
+ * are empty and the warm-up is three cheap SELECTs.
+ *
+ * The bundle is only valid for the connection (or transaction lineage)
+ * it was warmed against — ids observed here are stable because the
+ * header dictionaries are append-only, but a cache warmed on connection
+ * A does not see rows a concurrent writer B added. The crawler holds a
+ * single writer connection per archive, so this cannot occur in
+ * practice.
+ * @param trx - Knex instance or transaction connected to the archive DB.
+ * @returns Warmed cache bundle ready for
+ *   {@link ./upsert-one-header-set.ts}.
+ * @example
+ * const caches = await createHeaderTableCaches(knex);
+ * const setId = await upsertOneHeaderSet(knex, decomposed, caches);
+ */
+export declare function createHeaderTableCaches(trx: Knex): Promise<HeaderTableCaches>;

package/lib/populate-ref-tables/create-header-table-caches.js

@@ -0,0 +1,49 @@
+import { headerValueCacheKey } from './header-value-cache-key.js';
+/**
+ * Creates a {@link HeaderTableCaches} bundle warmed from the DB's current
+ * `header_name_refs` / `header_value_refs` / `header_sets` rows.
+ *
+ * Warming lets idempotent re-runs (and resumed / appended crawls against
+ * an archive that already holds header rows) reuse existing ids instead
+ * of re-issuing an upsert per entry. On a fresh archive all three tables
+ * are empty and the warm-up is three cheap SELECTs.
+ *
+ * The bundle is only valid for the connection (or transaction lineage)
+ * it was warmed against — ids observed here are stable because the
+ * header dictionaries are append-only, but a cache warmed on connection
+ * A does not see rows a concurrent writer B added. The crawler holds a
+ * single writer connection per archive, so this cannot occur in
+ * practice.
+ * @param trx - Knex instance or transaction connected to the archive DB.
+ * @returns Warmed cache bundle ready for
+ *   {@link ./upsert-one-header-set.ts}.
+ * @example
+ * const caches = await createHeaderTableCaches(knex);
+ * const setId = await upsertOneHeaderSet(knex, decomposed, caches);
+ */
+export async function createHeaderTableCaches(trx) {
+    const nameIdCache = new Map();
+    const nameRows = await trx('header_name_refs').select();
+    for (const row of nameRows) {
+        nameIdCache.set(row.name, row.id);
+    }
+    const valueIdCache = new Map();
+    const valueRows = await trx('header_value_refs').select();
+    for (const row of valueRows) {
+        valueIdCache.set(headerValueCacheKey(Buffer.from(row.hash), row.value), row.id);
+    }
+    const setIdByRawJsonHash = new Map();
+    const setIdByRawHash = new Map();
+    const setRows = await trx('header_sets').select('id', 'raw_json_hash', 'raw_hash');
+    for (const row of setRows) {
+        setIdByRawJsonHash.set(Buffer.from(row.raw_json_hash).toString('hex'), row.id);
+        setIdByRawHash.set(Buffer.from(row.raw_hash).toString('hex'), row.id);
+    }
+    return {
+        nameIdCache,
+        valueIdCache,
+        setIdByRawJsonHash,
+        setIdByRawHash,
+        setIdsProcessedThisRun: new Set(),
+    };
+}

package/lib/populate-ref-tables/data-uri-url-refs-limit.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Threshold above which a `data:` URI is treated as a `blob_refs` payload
+ * rather than a `url_refs` URL. Shared between {@link ./populate-url-refs.ts}
+ * (which excludes `> LIMIT` data URIs from `url_refs`) and
+ * {@link ./populate-blob-refs.ts} (which routes them to `blob_refs`).
+ *
+ * The two populators MUST agree on this constant — a mismatch creates a
+ * routing hole where URIs of the disputed length land in neither table.
+ * Keeping the value here as a single-file export makes drift impossible.
+ *
+ * 512 was chosen because well-formed http(s) URLs virtually never exceed
+ * 512 characters in practice, while the smallest observed data URIs are
+ * ~600 bytes.
+ */
+export declare const DATA_URI_URL_REFS_LIMIT = 512;

package/lib/populate-ref-tables/data-uri-url-refs-limit.js

@@ -0,0 +1,15 @@
+/**
+ * Threshold above which a `data:` URI is treated as a `blob_refs` payload
+ * rather than a `url_refs` URL. Shared between {@link ./populate-url-refs.ts}
+ * (which excludes `> LIMIT` data URIs from `url_refs`) and
+ * {@link ./populate-blob-refs.ts} (which routes them to `blob_refs`).
+ *
+ * The two populators MUST agree on this constant — a mismatch creates a
+ * routing hole where URIs of the disputed length land in neither table.
+ * Keeping the value here as a single-file export makes drift impossible.
+ *
+ * 512 was chosen because well-formed http(s) URLs virtually never exceed
+ * 512 characters in practice, while the smallest observed data URIs are
+ * ~600 bytes.
+ */
+export const DATA_URI_URL_REFS_LIMIT = 512;

package/lib/populate-ref-tables/decode-data-uri.d.ts

@@ -0,0 +1,21 @@
+import type { DecodedDataUri } from './types.js';
+/**
+ * Attempts to decode a `data:...` URI into its raw payload bytes.
+ *
+ * Supports the two encoding forms in RFC 2397:
+ *
+ * - `data:<mime>;base64,<base64-bytes>` — the base64 tail is decoded via
+ *   `Buffer.from(..., 'base64')`.
+ * - `data:<mime>,<percent-encoded-bytes>` — the tail is percent-decoded
+ *   via `decodeURIComponent(...)`, then re-encoded as UTF-8. This form is
+ *   commonly used for SVG data URIs.
+ *
+ * Returns `null` on any parse / decode failure so the caller can skip the
+ * value without aborting the whole `blob_refs` population step. A single
+ * malformed data URI in a 470 K-row archive should not halt the migration
+ * — the raw `url` string is still preserved in the source `images` row.
+ * @param value - Raw column value; may or may not start with `data:`.
+ * @returns Decoded bytes, or `null` when the value isn't a data URI or
+ *   can't be decoded.
+ */
+export declare function decodeDataUri(value: string): DecodedDataUri | null;