@byline/core 6.12.1 → 6.13.0

package/dist/extraction/producer.test.node.js

@@ -0,0 +1,230 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { describe, expect, it } from 'vitest';
+import { CONTENT_HASH_PATTERN, sha256Hex } from '../storage/content-hash.js';
+import { buildExtractionProducer, producerConfigHash } from './producer.js';
+const encoder = new TextEncoder();
+describe('producerConfigHash', () => {
+    it('hashes the canonical JSON of its inputs as lower-case SHA-256', async () => {
+        const hash = await producerConfigHash({
+            provider: 'tika',
+            configuration: { ocr: true, dpi: 300 },
+            hints: { language: 'en', filename: 'a.pdf' },
+            outputAffectingHints: ['language'],
+            configurationVersion: 'v1',
+            deploymentIdentifier: 'image-a',
+        });
+        const expected = '{"configuration":{"dpi":300,"ocr":true},"configurationVersion":"v1",' +
+            '"deploymentIdentifier":"image-a","hints":{"language":"en"},"provider":"tika"}';
+        expect(hash).toBe(await sha256Hex(encoder.encode(expected)));
+        expect(hash).toMatch(CONTENT_HASH_PATTERN);
+    });
+    it('does not depend on key order at any depth', async () => {
+        const a = await producerConfigHash({
+            provider: 'p',
+            configuration: { b: 1, a: { d: [1, { y: 2, x: 1 }], c: null } },
+        });
+        const b = await producerConfigHash({
+            provider: 'p',
+            configuration: { a: { c: null, d: [1, { x: 1, y: 2 }] }, b: 1 },
+        });
+        expect(a).toBe(b);
+    });
+    it('keeps array order significant', async () => {
+        const a = await producerConfigHash({ provider: 'p', configuration: { langs: ['th', 'en'] } });
+        const b = await producerConfigHash({ provider: 'p', configuration: { langs: ['en', 'th'] } });
+        expect(a).not.toBe(b);
+    });
+    it('drops undefined object members', async () => {
+        const a = await producerConfigHash({
+            provider: 'p',
+            configuration: { a: 1, b: undefined },
+        });
+        const b = await producerConfigHash({ provider: 'p', configuration: { a: 1 } });
+        expect(a).toBe(b);
+    });
+    it('drops nested undefined members, unlike strict JSON validation of artifact structure', async () => {
+        const a = await producerConfigHash({
+            provider: 'p',
+            configuration: { section: { a: 1, b: undefined } },
+        });
+        const b = await producerConfigHash({ provider: 'p', configuration: { section: { a: 1 } } });
+        expect(a).toBe(b);
+    });
+    it('keeps only the output-affecting hints that were supplied', async () => {
+        const withFilename = await producerConfigHash({
+            provider: 'p',
+            hints: { language: 'en', filename: 'a.pdf' },
+            outputAffectingHints: ['language', 'ocrLanguages'],
+        });
+        const withoutFilename = await producerConfigHash({
+            provider: 'p',
+            hints: { language: 'en' },
+            outputAffectingHints: ['language', 'ocrLanguages'],
+        });
+        const otherLanguage = await producerConfigHash({
+            provider: 'p',
+            hints: { language: 'th' },
+            outputAffectingHints: ['language'],
+        });
+        expect(withFilename).toBe(withoutFilename);
+        expect(otherLanguage).not.toBe(withoutFilename);
+    });
+    it('ignores every hint when the provider declares none', async () => {
+        const a = await producerConfigHash({ provider: 'p', hints: { language: 'en' } });
+        const b = await producerConfigHash({ provider: 'p' });
+        expect(a).toBe(b);
+    });
+    it.each([
+        ['provider', { provider: 'q' }],
+        ['configuration', { provider: 'p', configuration: { a: 2 } }],
+        ['configuration version', { provider: 'p', configurationVersion: 'v2' }],
+        ['deployment identifier', { provider: 'p', deploymentIdentifier: 'image-b' }],
+    ])('changes with the %s', async (_label, change) => {
+        const inputs = {
+            provider: 'p',
+            configuration: { a: 1 },
+            configurationVersion: 'v1',
+            deploymentIdentifier: 'image-a',
+        };
+        const base = await producerConfigHash(inputs);
+        const changed = await producerConfigHash({ ...inputs, ...change });
+        expect(changed).not.toBe(base);
+    });
+    it('treats an absent and a null deployment identifier as the same', async () => {
+        const absent = await producerConfigHash({ provider: 'p' });
+        const nullIdentifier = await producerConfigHash({ provider: 'p', deploymentIdentifier: null });
+        expect(nullIdentifier).toBe(absent);
+    });
+    it.each([
+        ['empty', ''],
+        ['leading whitespace', ' image'],
+        ['trailing whitespace', 'image '],
+        ['only whitespace', '   '],
+        ['not a string', 7],
+    ])('rejects a deployment identifier that is %s', async (_label, deploymentIdentifier) => {
+        await expect(producerConfigHash({ provider: 'p', deploymentIdentifier: deploymentIdentifier })).rejects.toThrow(TypeError);
+    });
+    it.each([
+        ['a function', () => 1],
+        ['a symbol', Symbol('x')],
+        ['a bigint', 1n],
+        ['NaN', Number.NaN],
+        ['Infinity', Number.POSITIVE_INFINITY],
+        ['a Date', new Date(0)],
+        ['a class instance', new (class Thing {
+            })()],
+        ['undefined in an array', [undefined]],
+    ])('rejects %s as a non-JSON value', async (_label, value) => {
+        await expect(producerConfigHash({ provider: 'p', configuration: { value } })).rejects.toThrow(TypeError);
+    });
+    it.each([
+        ['one hole', () => new Array(1)],
+        ['several holes', () => new Array(3)],
+        [
+            'a hole beside values',
+            () => {
+                const items = [1];
+                items[2] = 2;
+                return items;
+            },
+        ],
+        ['a very long sparse array', () => new Array(2 ** 32 - 1)],
+    ])('rejects a sparse array with %s', async (_label, items) => {
+        await expect(producerConfigHash({ provider: 'p', configuration: { items: items() } })).rejects.toThrow(TypeError);
+    });
+    it('rejects a nested sparse array', async () => {
+        await expect(producerConfigHash({ provider: 'p', configuration: { a: { b: [new Array(1)] } } })).rejects.toThrow(TypeError);
+    });
+    it('rejects a sparse output-affecting hint array', async () => {
+        await expect(producerConfigHash({
+            provider: 'p',
+            hints: { ocrLanguages: new Array(1) },
+            outputAffectingHints: ['ocrLanguages'],
+        })).rejects.toThrow(TypeError);
+    });
+    it('rejects symbol keys, which JSON would silently drop', async () => {
+        await expect(producerConfigHash({ provider: 'p', configuration: { [Symbol('x')]: 1 } })).rejects.toThrow(TypeError);
+    });
+    it('rejects a cycle rather than overflowing the stack', async () => {
+        const cycle = {};
+        cycle.self = cycle;
+        await expect(producerConfigHash({ provider: 'p', configuration: cycle })).rejects.toThrow(TypeError);
+    });
+    it('accepts a shared object that is not a cycle', async () => {
+        const shared = { x: 1 };
+        await expect(producerConfigHash({ provider: 'p', configuration: { a: shared, b: shared } })).resolves.toMatch(CONTENT_HASH_PATTERN);
+    });
+});
+describe('buildExtractionProducer', () => {
+    const provider = {
+        name: 'tika',
+        capabilities: {
+            ocr: false,
+            markdown: false,
+            tables: false,
+            formulas: false,
+            charts: false,
+            coordinates: false,
+            pageMap: false,
+            structure: false,
+            formats: ['*/*'],
+        },
+        configuration: { ocr: false },
+        outputAffectingHints: ['language'],
+        extract: () => Promise.reject(new Error('not used')),
+    };
+    it('returns the identifier it hashed, with the same hash as a direct call', async () => {
+        const producer = await buildExtractionProducer({
+            provider,
+            providerVersion: '3.0.0',
+            hints: { language: 'th', filename: 'a.pdf' },
+            configurationVersion: 'v1',
+            deploymentIdentifier: 'image-a',
+        });
+        expect(producer).toEqual({
+            provider: 'tika',
+            providerVersion: '3.0.0',
+            deploymentIdentifier: 'image-a',
+            producerConfigHash: await producerConfigHash({
+                provider: 'tika',
+                configuration: { ocr: false },
+                hints: { language: 'th' },
+                outputAffectingHints: ['language'],
+                configurationVersion: 'v1',
+                deploymentIdentifier: 'image-a',
+            }),
+        });
+    });
+    it('gives a different hash for a different identifier', async () => {
+        const a = await buildExtractionProducer({
+            provider,
+            providerVersion: null,
+            deploymentIdentifier: 'image-a',
+        });
+        const b = await buildExtractionProducer({
+            provider,
+            providerVersion: null,
+            deploymentIdentifier: 'image-b',
+        });
+        expect(a.producerConfigHash).not.toBe(b.producerConfigHash);
+    });
+    it('normalises an absent identifier to null', async () => {
+        const producer = await buildExtractionProducer({ provider, providerVersion: null });
+        expect(producer.deploymentIdentifier).toBeNull();
+        expect(producer.providerVersion).toBeNull();
+    });
+    it('does not put the engine version in the hash', async () => {
+        const a = await buildExtractionProducer({ provider, providerVersion: '1.0.0' });
+        const b = await buildExtractionProducer({ provider, providerVersion: '2.0.0' });
+        expect(a.producerConfigHash).toBe(b.producerConfigHash);
+    });
+    it('rejects a malformed identifier', async () => {
+        await expect(buildExtractionProducer({ provider, providerVersion: null, deploymentIdentifier: ' a' })).rejects.toThrow(TypeError);
+    });
+});

package/dist/extraction/root-graph-guard.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/extraction/root-graph-guard.test.node.js

@@ -0,0 +1,293 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Browser-safety guard for the `@byline/core` root entry.
+ *
+ * The root entry reaches browser bundles, so its module graph must not gain a Node
+ * built-in. Host framework protections such as `.server.*` file rules do not cover
+ * a published package, so the package checks itself here, against built output.
+ *
+ * Exactly one exception exists: `lib/logger.js` attempts a dynamic
+ * `import('node:async_hooks')` inside `try`/`catch` and falls back to a no-op store.
+ * The exception names the file, the specifier and the dynamic form together. A
+ * dynamic import is not safe merely because it is dynamic, and a static import of
+ * the same module in the same file would remove the fallback.
+ *
+ * Build `@byline/core` before running this test: it reads `dist`, so only a fresh build
+ * makes its result current. It fails when `dist/index.js` is missing or when the graph
+ * does not reach the extraction modules, but it is not a general stale-build detector.
+ *
+ * Its limits: it is a text walk rather than a parser, so it cannot see a computed
+ * `import(name)` or a template literal with a substitution, and it stops at package
+ * boundaries. It errs towards reporting: text in a string that looks like an import
+ * counts as one.
+ */
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { builtinModules } from 'node:module';
+import { tmpdir } from 'node:os';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, describe, expect, it } from 'vitest';
+const STATIC_IMPORT = /(?:^|[\n;])\s*(?:import|export)\s+(?:[^'"`;]*?\sfrom\s*)?['"]([^'"]+)['"]/g;
+// The specifier may be any literal whose value is known statically: a quoted string, or
+// a template literal with no substitution. A second argument may follow it.
+const DYNAMIC_IMPORT = /\b(?:import|require)\(\s*(?:'([^']+)'|"([^"]+)"|`((?:[^`$]|\$(?!\{))+)`)\s*[,)]/g;
+const BUILTINS = new Set(builtinModules);
+function isNodeBuiltin(specifier) {
+    return specifier.startsWith('node:') || BUILTINS.has(specifier.split('/')[0] ?? specifier);
+}
+/**
+ * Removes comments, because built output keeps JSDoc whose examples can contain import
+ * expressions. It leaves string and template contents alone. A quoted string ends at
+ * its line break, so a quote inside a regular expression cannot hide later lines.
+ */
+function stripComments(source) {
+    let output = '';
+    let i = 0;
+    while (i < source.length) {
+        const char = source[i];
+        const next = source[i + 1];
+        if (char === '/' && next === '/') {
+            const end = source.indexOf('\n', i);
+            i = end === -1 ? source.length : end;
+        }
+        else if (char === '/' && next === '*') {
+            const end = source.indexOf('*/', i + 2);
+            i = end === -1 ? source.length : end + 2;
+        }
+        else if (char === "'" || char === '"' || char === '`') {
+            let end = i + 1;
+            while (end < source.length && source[end] !== char) {
+                if (char !== '`' && source[end] === '\n')
+                    break;
+                end += source[end] === '\\' ? 2 : 1;
+            }
+            output += source.slice(i, end + 1);
+            i = end + 1;
+        }
+        else {
+            output += char;
+            i += 1;
+        }
+    }
+    return output;
+}
+/** Walks every relative static and dynamic import reachable from an entry file. */
+function walkGraph(entry) {
+    const root = dirname(entry);
+    const seen = new Set();
+    const builtinImports = [];
+    const visit = (file) => {
+        if (seen.has(file))
+            return;
+        seen.add(file);
+        const source = stripComments(readFileSync(file, 'utf8'));
+        const name = relative(root, file).split(sep).join('/');
+        const scan = (pattern, form) => {
+            for (const match of source.matchAll(pattern)) {
+                const specifier = (match[1] ?? match[2] ?? match[3]);
+                if (specifier.startsWith('.')) {
+                    visit(resolve(dirname(file), specifier));
+                }
+                else if (isNodeBuiltin(specifier)) {
+                    builtinImports.push({ file: name, specifier, form });
+                }
+            }
+        };
+        scan(STATIC_IMPORT, 'static');
+        scan(DYNAMIC_IMPORT, 'dynamic');
+    };
+    visit(entry);
+    return {
+        files: [...seen].map((file) => relative(root, file).split(sep).join('/')),
+        builtinImports,
+    };
+}
+const ALLOWED = [
+    { file: 'lib/logger.js', specifier: 'node:async_hooks', form: 'dynamic' },
+];
+const sameImport = (a, b) => a.file === b.file && a.specifier === b.specifier && a.form === b.form;
+/** Every failure the guard reports for a graph. */
+function guardViolations(builtinImports, allowed = ALLOWED) {
+    const unexpected = builtinImports
+        .filter((found) => !allowed.some((entry) => sameImport(entry, found)))
+        .map((found) => `${found.file}: ${found.form} import of ${found.specifier}`);
+    const stale = allowed
+        .filter((entry) => !builtinImports.some((found) => sameImport(entry, found)))
+        .map((entry) => `stale allowlist entry: ${entry.file} ${entry.form} ${entry.specifier}`);
+    return [...unexpected, ...stale];
+}
+describe('root graph guard', () => {
+    const temporaryDirectories = [];
+    /** Writes a small built tree and returns the path of its `index.js`. */
+    function fixture(files) {
+        const directory = mkdtempSync(join(tmpdir(), 'byline-root-guard-'));
+        temporaryDirectories.push(directory);
+        for (const [name, source] of Object.entries(files)) {
+            const path = join(directory, name);
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, source);
+        }
+        return join(directory, 'index.js');
+    }
+    afterEach(() => {
+        for (const directory of temporaryDirectories.splice(0)) {
+            rmSync(directory, { recursive: true, force: true });
+        }
+    });
+    const LOGGER = "try { await import('node:async_hooks') } catch {}\n";
+    describe('self-test', () => {
+        it('passes a tree with only the allowlisted import', () => {
+            const { builtinImports } = walkGraph(fixture({ 'index.js': "export * from './lib/logger.js'\n", 'lib/logger.js': LOGGER }));
+            expect(guardViolations(builtinImports)).toEqual([]);
+        });
+        it('catches a planted static import', () => {
+            const { builtinImports } = walkGraph(fixture({
+                'index.js': "export * from './lib/logger.js'\nexport { x } from './a/b.js'\n",
+                'lib/logger.js': LOGGER,
+                'a/b.js': "import { readFile } from 'node:fs/promises'\nexport const x = readFile\n",
+            }));
+            expect(guardViolations(builtinImports)).toEqual(['a/b.js: static import of node:fs/promises']);
+        });
+        it('catches a planted dynamic import', () => {
+            const { builtinImports } = walkGraph(fixture({
+                'index.js': "export * from './lib/logger.js'\nimport './a.js'\n",
+                'lib/logger.js': LOGGER,
+                'a.js': "const fs = await import('node:fs')\nexport { fs }\n",
+            }));
+            expect(guardViolations(builtinImports)).toEqual(['a.js: dynamic import of node:fs']);
+        });
+        it('catches a static import of the allowlisted module in the allowlisted file', () => {
+            const { builtinImports } = walkGraph(fixture({
+                'index.js': "export * from './lib/logger.js'\n",
+                'lib/logger.js': "import { AsyncLocalStorage } from 'node:async_hooks'\n",
+            }));
+            expect(guardViolations(builtinImports)).toEqual([
+                'lib/logger.js: static import of node:async_hooks',
+                'stale allowlist entry: lib/logger.js dynamic node:async_hooks',
+            ]);
+        });
+        it('catches the allowlisted import in any other file', () => {
+            const { builtinImports } = walkGraph(fixture({
+                'index.js': "export * from './lib/logger.js'\nimport './other.js'\n",
+                'lib/logger.js': LOGGER,
+                'other.js': "await import('node:async_hooks')\n",
+            }));
+            expect(guardViolations(builtinImports)).toEqual([
+                'other.js: dynamic import of node:async_hooks',
+            ]);
+        });
+        it('catches a bare built-in with no node: prefix', () => {
+            const { builtinImports } = walkGraph(fixture({
+                'index.js': "export * from './lib/logger.js'\nimport fs from 'fs'\nexport { fs }\n",
+                'lib/logger.js': LOGGER,
+            }));
+            expect(guardViolations(builtinImports)).toEqual(['index.js: static import of fs']);
+        });
+        it('ignores imports written in comments', () => {
+            const { builtinImports } = walkGraph(fixture({
+                'index.js': [
+                    "/** Example: hooks: () => import('./missing.hooks.js') */",
+                    "// await import('node:fs')",
+                    "export * from './lib/logger.js'",
+                ].join('\n'),
+                'lib/logger.js': LOGGER,
+            }));
+            expect(guardViolations(builtinImports)).toEqual([]);
+        });
+        it('still sees a real import after a string that looks like a comment', () => {
+            const { builtinImports } = walkGraph(fixture({
+                'index.js': [
+                    "export * from './lib/logger.js'",
+                    "const url = 'https://example.com/*'",
+                    "const fs = await import('node:fs')",
+                    'export { fs, url }',
+                ].join('\n'),
+                'lib/logger.js': LOGGER,
+            }));
+            expect(guardViolations(builtinImports)).toEqual(['index.js: dynamic import of node:fs']);
+        });
+        it('fails on a relative import that does not resolve', () => {
+            expect(() => walkGraph(fixture({ 'index.js': "export * from './missing.js'\n" }))).toThrow(/ENOENT/);
+        });
+        it('catches a built-in named by a no-substitution template literal', () => {
+            const { builtinImports } = walkGraph(fixture({
+                'index.js': [
+                    "export * from './lib/logger.js'",
+                    'export const read = () => import(`node:fs`)',
+                ].join('\n'),
+                'lib/logger.js': LOGGER,
+            }));
+            expect(guardViolations(builtinImports)).toEqual(['index.js: dynamic import of node:fs']);
+        });
+        it('follows a relative template literal import to a built-in one hop away', () => {
+            const { builtinImports } = walkGraph(fixture({
+                'index.js': [
+                    "export * from './lib/logger.js'",
+                    'export const load = () => import(`./hidden.js`)',
+                ].join('\n'),
+                'lib/logger.js': LOGGER,
+                'hidden.js': "import fs from 'node:fs'\nexport { fs }\n",
+            }));
+            expect(guardViolations(builtinImports)).toEqual(['hidden.js: static import of node:fs']);
+        });
+        it('catches a dynamic import with an options argument', () => {
+            const { builtinImports } = walkGraph(fixture({
+                'index.js': [
+                    "export * from './lib/logger.js'",
+                    "export const load = () => import('node:fs', { with: {} })",
+                ].join('\n'),
+                'lib/logger.js': LOGGER,
+            }));
+            expect(guardViolations(builtinImports)).toEqual(['index.js: dynamic import of node:fs']);
+        });
+        it('does not treat a template literal with a substitution as a known specifier', () => {
+            const { builtinImports } = walkGraph(fixture({
+                'index.js': 'export const load = (name) => import(`./${name}.js`)\n',
+            }));
+            expect(builtinImports).toEqual([]);
+        });
+        it('errs towards reporting text in a string that looks like an import', () => {
+            const { builtinImports } = walkGraph(fixture({
+                'index.js': "export const help = 'write import(`node:fs`) in your own code'\n",
+            }));
+            expect(builtinImports.map((found) => found.specifier)).toEqual(['node:fs']);
+        });
+        it('reports an allowlist entry that no longer matches', () => {
+            const { builtinImports } = walkGraph(fixture({ 'index.js': 'export const x = 1\n' }));
+            expect(guardViolations(builtinImports)).toEqual([
+                'stale allowlist entry: lib/logger.js dynamic node:async_hooks',
+            ]);
+        });
+        it('does not treat a package with a built-in-like suffix as a built-in', () => {
+            const { builtinImports } = walkGraph(fixture({ 'index.js': "import x from 'fs-extra'\nexport { x }\n" }));
+            expect(builtinImports).toEqual([]);
+        });
+    });
+    describe('the built @byline/core root entry', () => {
+        const entry = fileURLToPath(new URL('../../dist/index.js', import.meta.url));
+        it('exists; build @byline/core before running this test', () => {
+            expect(existsSync(entry)).toBe(true);
+        });
+        it('reaches the extraction modules', () => {
+            const { files } = walkGraph(entry);
+            expect(files).toEqual(expect.arrayContaining([
+                'extraction/artifact.js',
+                'extraction/errors.js',
+                'extraction/evidence.js',
+                'extraction/outcomes.js',
+                'extraction/page-map.js',
+                'extraction/producer.js',
+                'extraction/work.js',
+            ]));
+        });
+        it('holds no Node built-in beyond the allowlisted dynamic import', () => {
+            expect(guardViolations(walkGraph(entry).builtinImports)).toEqual([]);
+        });
+    });
+});

package/dist/extraction/work.d.ts

@@ -0,0 +1,55 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { type ExtractionProducerIdentity } from './producer.js';
+import type { ExtractionArtifact, ExtractionWorkDecision } from '../@types/extraction-types.js';
+/**
+ * The output and evidence a reference currently holds. Pass only this reference's
+ * own record: reuse here means "keep what this reference has", not a cache lookup.
+ * An artifact with a `null` `producerConfigHash` must never be returned as a cache
+ * match for a fully identified producer or for another reference.
+ *
+ * @provisional
+ */
+export interface ExistingExtraction {
+    state: 'complete' | 'failed' | 'identity-problem';
+    artifact?: Pick<ExtractionArtifact, 'contentHash' | 'sourceVerified' | 'provider' | 'providerVersion' | 'producerConfigHash' | 'schemaVersion'>;
+    evidence?: unknown;
+}
+/**
+ * Decides whether a reference needs extraction, before any bytes are read.
+ *
+ * - A reference with no `fileHash` is an identity problem. `force` does not bypass it.
+ * - `force` always yields `work`. It bypasses reuse, never the verified read.
+ * - `reuse` needs a complete, verified artifact for the reference's hash, valid
+ *   evidence for that hash, the same provider and configuration, a version that
+ *   passes the version rules, and the current schema. Follow it with
+ *   `probeVerifiedSource`.
+ * - A `null` current engine version never yields a version reason, so an unknown
+ *   version cannot cause repeated work.
+ * - An artifact with a `null` `producerConfigHash` is historical output whose
+ *   configuration was never recorded. Only that hash and a `null` recorded version go
+ *   uncompared, and `reuse` then reports `producerUnchecked: true`. A provider
+ *   mismatch, two known versions that differ, and every other reason apply unchanged.
+ *
+ * The decision is synchronous and cannot recompute the hash, so it trusts that
+ * `producer.deploymentIdentifier` is the value hashed into `producerConfigHash`.
+ * `buildExtractionProducer` guarantees that. It checks the identifier's form and
+ * throws a `TypeError` when malformed.
+ *
+ * Hosts may add their own reasons and treat the union as the decision.
+ *
+ * @provisional
+ */
+export declare function decideExtractionWork(input: {
+    force?: boolean;
+    reference: {
+        fileHash?: string | null;
+    };
+    producer: ExtractionProducerIdentity;
+    existing?: ExistingExtraction | null;
+}): ExtractionWorkDecision;