@byline/core 6.12.0 → 6.13.0

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

@@ -0,0 +1,194 @@
+/**
+ * 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 { validateExtractionArtifact } from './artifact.js';
+const HASH = 'a'.repeat(64);
+const CONFIG_HASH = 'b'.repeat(64);
+function validArtifact() {
+    return {
+        schemaVersion: 1,
+        contentHash: HASH,
+        sourceVerified: true,
+        provider: 'tika',
+        providerVersion: '3.0.0',
+        producerConfigHash: CONFIG_HASH,
+        plainText: 'alpha',
+        metadata: {},
+        signals: { totalChars: 5 },
+        producedAt: '2026-11-04T00:00:00.000Z',
+    };
+}
+function codes(value, options) {
+    const result = validateExtractionArtifact(value, options);
+    return result.ok ? [] : result.issues.map((issue) => issue.code);
+}
+describe('validateExtractionArtifact', () => {
+    it('accepts a complete artifact', () => {
+        expect(validateExtractionArtifact(validArtifact())).toEqual({ ok: true });
+    });
+    it('accepts the optional members', () => {
+        expect(validateExtractionArtifact({
+            ...validArtifact(),
+            providerVersion: null,
+            markdown: '# alpha',
+            structure: { any: ['json'] },
+            pageCount: 1,
+            pageMap: {
+                version: 1,
+                assembly: { pageSeparator: '' },
+                pages: [{ index: 1, charStart: 0, charEnd: 5 }],
+            },
+        })).toEqual({ ok: true });
+    });
+    it.each([
+        ['null', null],
+        ['an array', []],
+        ['a string', 'artifact'],
+    ])('rejects %s', (_label, value) => {
+        expect(codes(value)).toContain('invalid-shape');
+    });
+    it('reports an unknown schema version as unsupported', () => {
+        expect(codes({ ...validArtifact(), schemaVersion: 2 })).toEqual(['unsupported-schema-version']);
+    });
+    it.each([
+        ['a short content hash', { contentHash: 'abc' }, 'invalid-content-hash'],
+        ['an upper-case content hash', { contentHash: 'A'.repeat(64) }, 'invalid-content-hash'],
+        ['an empty content hash', { contentHash: '' }, 'invalid-content-hash'],
+        ['a malformed configuration hash', { producerConfigHash: 'x' }, 'invalid-producer-config-hash'],
+        ['an empty provider', { provider: '' }, 'invalid-provider'],
+        ['a numeric provider version', { providerVersion: 3 }, 'invalid-provider-version'],
+        ['absent plain text', { plainText: undefined }, 'invalid-plain-text'],
+        ['non-string markdown', { markdown: 1 }, 'invalid-markdown'],
+        ['a negative page count', { pageCount: -1 }, 'invalid-page-count'],
+        ['a fractional page count', { pageCount: 1.5 }, 'invalid-page-count'],
+        ['absent metadata', { metadata: undefined }, 'invalid-metadata'],
+        ['absent signals', { signals: undefined }, 'invalid-signals'],
+        ['a negative total', { signals: { totalChars: -1 } }, 'invalid-signals'],
+        ['a date without a time', { producedAt: '2026-11-04' }, 'invalid-produced-at'],
+        ['an unparseable date', { producedAt: 'yesterday' }, 'invalid-produced-at'],
+        ['a non-boolean verified flag', { sourceVerified: 'yes' }, 'source-verified-mismatch'],
+    ])('rejects %s', (_label, change, code) => {
+        expect(codes({ ...validArtifact(), ...change })).toContain(code);
+    });
+    it('requires sourceVerified to agree with contentHash', () => {
+        expect(codes({ ...validArtifact(), sourceVerified: false })).toContain('source-verified-mismatch');
+        expect(codes({ ...validArtifact(), contentHash: null })).toContain('source-verified-mismatch');
+    });
+    it('accepts a legacy import with no source identity', () => {
+        expect(validateExtractionArtifact({ ...validArtifact(), contentHash: null, sourceVerified: false })).toEqual({ ok: true });
+    });
+    it('reports page map issues against the artifact text and page count', () => {
+        const artifact = {
+            ...validArtifact(),
+            pageCount: 2,
+            pageMap: {
+                version: 1,
+                assembly: { pageSeparator: '' },
+                pages: [{ index: 1, charStart: 0, charEnd: 5 }],
+            },
+        };
+        expect(codes(artifact)).toContain('invalid-page-map');
+    });
+    describe('structure', () => {
+        it('accepts any JSON value, because it is opaque to Byline', () => {
+            for (const structure of [null, 1, 'text', true, [1, { a: [] }], { a: { b: null } }]) {
+                expect(validateExtractionArtifact({ ...validArtifact(), structure })).toEqual({ ok: true });
+            }
+        });
+        const cycle = {};
+        cycle.self = cycle;
+        it.each([
+            ['a bigint', 1n],
+            ['a nested function', { a: () => 1 }],
+            ['NaN', [Number.NaN]],
+            ['a Date', new Date(0)],
+            ['a sparse array', new Array(1)],
+            ['an undefined member', { value: undefined }],
+            ['a nested undefined member', { section: { value: undefined } }],
+            ['an undefined member inside an array', [{ value: undefined }]],
+            ['a cycle', cycle],
+        ])('rejects %s', (_label, structure) => {
+            expect(codes({ ...validArtifact(), structure })).toContain('invalid-structure');
+        });
+    });
+    describe('metadata members', () => {
+        it('accepts recognised members and ignores unknown ones', () => {
+            expect(validateExtractionArtifact({
+                ...validArtifact(),
+                metadata: {
+                    contentType: 'application/pdf',
+                    pages: 3,
+                    title: 'T',
+                    authors: ['A', 'B'],
+                    language: 'en',
+                    createdAt: '2026-01-01T00:00:00Z',
+                    producer: 'P',
+                    somethingElse: { any: 1 },
+                },
+            })).toEqual({ ok: true });
+        });
+        it.each([
+            ['non-string authors', { authors: 42 }],
+            ['an author that is not a string', { authors: ['A', 1] }],
+            ['a hole in authors', { authors: new Array(1) }],
+            ['non-numeric pages', { pages: 'bad' }],
+            ['negative pages', { pages: -1 }],
+            ['a non-string title', { title: 1 }],
+            ['a non-string content type', { contentType: 1 }],
+            ['a non-string language', { language: 1 }],
+            ['a non-string creation date', { createdAt: 1 }],
+            ['a creation date that is not ISO 8601', { createdAt: 'not-a-date' }],
+            ['a raw PDF creation date', { createdAt: "D:20260101000000+07'00'" }],
+            ['a non-string producer', { producer: 1 }],
+        ])('rejects %s', (_label, metadata) => {
+            expect(codes({ ...validArtifact(), metadata })).toContain('invalid-metadata');
+        });
+    });
+    describe('signals members', () => {
+        it('accepts recognised members and ignores unknown ones', () => {
+            expect(validateExtractionArtifact({
+                ...validArtifact(),
+                signals: {
+                    totalChars: 5,
+                    charsPerPage: [2, 3],
+                    ocrCandidatePages: 0,
+                    textLayerCoverage: 1,
+                    somethingElse: true,
+                },
+            })).toEqual({ ok: true });
+        });
+        it.each([
+            ['non-array charsPerPage', { charsPerPage: 'bad' }],
+            ['a negative page count in charsPerPage', { charsPerPage: [-1] }],
+            ['a hole in charsPerPage', { charsPerPage: new Array(1) }],
+            ['a fractional OCR candidate count', { ocrCandidatePages: 1.5 }],
+            ['coverage above one', { textLayerCoverage: 2 }],
+            ['coverage below zero', { textLayerCoverage: -0.1 }],
+            ['non-numeric coverage', { textLayerCoverage: '1' }],
+        ])('rejects %s', (_label, change) => {
+            expect(codes({ ...validArtifact(), signals: { totalChars: 5, ...change } })).toContain('invalid-signals');
+        });
+    });
+    describe('an unrecorded producer configuration', () => {
+        const historical = { ...validArtifact(), providerVersion: null, producerConfigHash: null };
+        it('is rejected by default, so a new extraction cannot record null', () => {
+            expect(codes(historical)).toEqual(['unrecorded-producer']);
+        });
+        it('is rejected when the option is false', () => {
+            expect(codes(historical, { allowUnrecordedProducer: false })).toEqual(['unrecorded-producer']);
+        });
+        it('is accepted when reading a historical record', () => {
+            expect(validateExtractionArtifact(historical, { allowUnrecordedProducer: true })).toEqual({
+                ok: true,
+            });
+        });
+        it('does not relax a malformed configuration hash', () => {
+            expect(codes({ ...validArtifact(), producerConfigHash: 'x' }, { allowUnrecordedProducer: true })).toContain('invalid-producer-config-hash');
+        });
+    });
+});

package/dist/extraction/errors.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 { ExtractionFailureScope } from '../@types/extraction-types.js';
+/**
+ * A typed provider failure.
+ *
+ * - `file`: the input caused it (corrupt, encrypted, unsupported format).
+ *   Orchestration may record a per-file failure for this source and producer.
+ * - `infrastructure`: the service failed (timeout, unavailable, bad credentials).
+ *   Orchestration must not record the file as bad and must preserve existing
+ *   artifacts.
+ *
+ * `retryable` is independent policy: bad credentials are `infrastructure` but not
+ * usefully retryable until repaired.
+ *
+ * @provisional
+ */
+export declare class ExtractionProviderError extends Error {
+    readonly code = "ERR_EXTRACTION_PROVIDER";
+    readonly failureScope: ExtractionFailureScope;
+    readonly retryable: boolean;
+    constructor(message: string, options: {
+        failureScope: ExtractionFailureScope;
+        retryable: boolean;
+        cause?: unknown;
+    });
+}
+/**
+ * Whether a value is a typed provider failure. It checks the `code` brand rather
+ * than `instanceof`, so an error thrown by a second copy of `@byline/core` still
+ * classifies.
+ *
+ * @provisional
+ */
+export declare function isExtractionProviderError(error: unknown): error is ExtractionProviderError;
+/**
+ * Whether a value is a typed `file` failure. An untyped error or an abort is never
+ * evidence that the file is bad.
+ *
+ * @provisional
+ */
+export declare function isFileExtractionFailure(error: unknown): error is ExtractionProviderError;

package/dist/extraction/errors.js

@@ -0,0 +1,57 @@
+/**
+ * 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
+ */
+const ERROR_CODE = 'ERR_EXTRACTION_PROVIDER';
+/**
+ * A typed provider failure.
+ *
+ * - `file`: the input caused it (corrupt, encrypted, unsupported format).
+ *   Orchestration may record a per-file failure for this source and producer.
+ * - `infrastructure`: the service failed (timeout, unavailable, bad credentials).
+ *   Orchestration must not record the file as bad and must preserve existing
+ *   artifacts.
+ *
+ * `retryable` is independent policy: bad credentials are `infrastructure` but not
+ * usefully retryable until repaired.
+ *
+ * @provisional
+ */
+export class ExtractionProviderError extends Error {
+    code = ERROR_CODE;
+    failureScope;
+    retryable;
+    constructor(message, options) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'ExtractionProviderError';
+        this.failureScope = options.failureScope;
+        this.retryable = options.retryable;
+    }
+}
+/**
+ * Whether a value is a typed provider failure. It checks the `code` brand rather
+ * than `instanceof`, so an error thrown by a second copy of `@byline/core` still
+ * classifies.
+ *
+ * @provisional
+ */
+export function isExtractionProviderError(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const candidate = error;
+    return (candidate.code === ERROR_CODE &&
+        (candidate.failureScope === 'file' || candidate.failureScope === 'infrastructure') &&
+        typeof candidate.retryable === 'boolean');
+}
+/**
+ * Whether a value is a typed `file` failure. An untyped error or an abort is never
+ * evidence that the file is bad.
+ *
+ * @provisional
+ */
+export function isFileExtractionFailure(error) {
+    return isExtractionProviderError(error) && error.failureScope === 'file';
+}

package/dist/extraction/errors.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/errors.test.node.js

@@ -0,0 +1,68 @@
+/**
+ * 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 { ExtractionProviderError, isExtractionProviderError, isFileExtractionFailure, } from './errors.js';
+function fromAnotherCopy(failureScope) {
+    // Stands in for an error thrown by a second installed copy of @byline/core:
+    // the same shape and brand, but a different class, so `instanceof` is false.
+    class OtherExtractionProviderError extends Error {
+        code = 'ERR_EXTRACTION_PROVIDER';
+        failureScope = failureScope;
+        retryable = false;
+    }
+    return new OtherExtractionProviderError('from another copy');
+}
+describe('ExtractionProviderError', () => {
+    it('carries its brand, scope, retry policy and cause', () => {
+        const cause = new Error('socket closed');
+        const error = new ExtractionProviderError('service failed', {
+            failureScope: 'infrastructure',
+            retryable: true,
+            cause,
+        });
+        expect(error).toBeInstanceOf(Error);
+        expect(error.name).toBe('ExtractionProviderError');
+        expect(error.code).toBe('ERR_EXTRACTION_PROVIDER');
+        expect(error.failureScope).toBe('infrastructure');
+        expect(error.retryable).toBe(true);
+        expect(error.cause).toBe(cause);
+    });
+});
+describe('isExtractionProviderError', () => {
+    it('accepts a typed error from this copy and from another copy', () => {
+        const typed = new ExtractionProviderError('bad', { failureScope: 'file', retryable: false });
+        expect(isExtractionProviderError(typed)).toBe(true);
+        expect(isExtractionProviderError(fromAnotherCopy('file'))).toBe(true);
+    });
+    it.each([
+        ['an untyped error', new Error('boom')],
+        ['an abort', new DOMException('aborted', 'AbortError')],
+        ['a brand with an unknown scope', fromAnotherCopy('network')],
+        ['a plain value', 'ERR_EXTRACTION_PROVIDER'],
+        ['null', null],
+    ])('rejects %s', (_label, value) => {
+        expect(isExtractionProviderError(value)).toBe(false);
+    });
+});
+describe('isFileExtractionFailure', () => {
+    it('is true only for a typed file failure', () => {
+        expect(isFileExtractionFailure(new ExtractionProviderError('corrupt', { failureScope: 'file', retryable: false }))).toBe(true);
+        expect(isFileExtractionFailure(fromAnotherCopy('file'))).toBe(true);
+    });
+    it.each([
+        [
+            'an infrastructure failure',
+            new ExtractionProviderError('down', { failureScope: 'infrastructure', retryable: true }),
+        ],
+        ['an infrastructure failure from another copy', fromAnotherCopy('infrastructure')],
+        ['an untyped error', new Error('corrupt')],
+        ['an abort', new DOMException('aborted', 'AbortError')],
+    ])('is false for %s', (_label, value) => {
+        expect(isFileExtractionFailure(value)).toBe(false);
+    });
+});

package/dist/extraction/evidence.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 { SourceVerificationEvidence } from '../@types/extraction-types.js';
+/**
+ * Whether a stored record is valid verification evidence, optionally for a given
+ * hash. Unknown extra members are ignored, so a later minor can add members without
+ * invalidating stored evidence.
+ *
+ * Records written before `readBasis` existed stay valid, with or without a fallback
+ * reason. The presence of a JSON key is not evidence, and a hash copied from the
+ * saved file value does not make a record valid.
+ *
+ * @provisional
+ */
+export declare function isSourceVerificationEvidence(value: unknown, options?: {
+    expectedHash?: string;
+}): value is SourceVerificationEvidence;

package/dist/extraction/evidence.js

@@ -0,0 +1,54 @@
+/**
+ * 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 { CONTENT_HASH_PATTERN, STORAGE_VALIDATOR_LIMITS } from '../storage/content-hash.js';
+import { isIsoDateTime, isPlainObject } from './internal.js';
+const isBoundedString = (value, limit) => typeof value === 'string' && value.length > 0 && value.length <= limit;
+const FALLBACK_REASONS = ['changed', 'unsupported-kind', 'unestablishable'];
+const READ_BASES = ['expected', 'unconditional', 'fallback'];
+/**
+ * Whether a stored record is valid verification evidence, optionally for a given
+ * hash. Unknown extra members are ignored, so a later minor can add members without
+ * invalidating stored evidence.
+ *
+ * Records written before `readBasis` existed stay valid, with or without a fallback
+ * reason. The presence of a JSON key is not evidence, and a hash copied from the
+ * saved file value does not make a record valid.
+ *
+ * @provisional
+ */
+export function isSourceVerificationEvidence(value, options) {
+    if (!isPlainObject(value))
+        return false;
+    const { expectedHash, contentHash, validator, verifiedAt, size, readBasis, preconditionFallback, } = value;
+    if (typeof contentHash !== 'string' || !CONTENT_HASH_PATTERN.test(contentHash))
+        return false;
+    if (expectedHash !== contentHash)
+        return false;
+    if (options?.expectedHash !== undefined && expectedHash !== options.expectedHash)
+        return false;
+    if (!isPlainObject(validator) ||
+        !isBoundedString(validator.kind, STORAGE_VALIDATOR_LIMITS.kind) ||
+        !isBoundedString(validator.value, STORAGE_VALIDATOR_LIMITS.value)) {
+        return false;
+    }
+    if (!isIsoDateTime(verifiedAt))
+        return false;
+    if (size !== undefined && (!Number.isSafeInteger(size) || size < 0))
+        return false;
+    if (readBasis !== undefined && !READ_BASES.includes(readBasis))
+        return false;
+    if (preconditionFallback !== undefined && !FALLBACK_REASONS.includes(preconditionFallback)) {
+        return false;
+    }
+    // A legacy record has no readBasis, and any fallback reason is valid on it.
+    if (readBasis === undefined)
+        return true;
+    return readBasis === 'fallback'
+        ? preconditionFallback !== undefined
+        : preconditionFallback === undefined;
+}

package/dist/extraction/evidence.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/evidence.test.node.js

@@ -0,0 +1,138 @@
+/**
+ * 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 { isSourceVerificationEvidence } from './evidence.js';
+const HASH = 'a'.repeat(64);
+/** The record a downstream library wrote before `size` and `readBasis` existed. */
+function legacyRecord() {
+    return {
+        expectedHash: HASH,
+        contentHash: HASH,
+        validator: { kind: 's3-etag', value: '"abc"' },
+        verifiedAt: '2026-10-31T06:00:00.000Z',
+    };
+}
+describe('isSourceVerificationEvidence', () => {
+    describe('rule 1: plain objects', () => {
+        it.each([
+            ['null', null],
+            ['undefined', undefined],
+            ['an array', []],
+            ['a string', 'evidence'],
+            ['a class instance', new (class Evidence {
+                })()],
+        ])('rejects %s', (_label, value) => {
+            expect(isSourceVerificationEvidence(value)).toBe(false);
+        });
+        it('ignores unknown extra members, so a later minor can add some', () => {
+            expect(isSourceVerificationEvidence({ ...legacyRecord(), futureMember: 1 })).toBe(true);
+        });
+    });
+    describe('rule 2: hashes', () => {
+        it('accepts an existing record unchanged', () => {
+            expect(isSourceVerificationEvidence(legacyRecord())).toBe(true);
+        });
+        it.each([
+            ['a malformed expected hash', { expectedHash: 'abc', contentHash: 'abc' }],
+            ['an upper-case hash', { expectedHash: 'A'.repeat(64), contentHash: 'A'.repeat(64) }],
+            ['an empty hash', { expectedHash: '', contentHash: '' }],
+            ['hashes that differ', { contentHash: 'b'.repeat(64) }],
+            ['a missing content hash', { contentHash: undefined }],
+        ])('rejects %s', (_label, change) => {
+            expect(isSourceVerificationEvidence({ ...legacyRecord(), ...change })).toBe(false);
+        });
+        it('rejects a copied-only record with nothing measured', () => {
+            expect(isSourceVerificationEvidence({ expectedHash: HASH })).toBe(false);
+        });
+        it('checks the hash the caller expects', () => {
+            expect(isSourceVerificationEvidence(legacyRecord(), { expectedHash: HASH })).toBe(true);
+            expect(isSourceVerificationEvidence(legacyRecord(), { expectedHash: 'b'.repeat(64) })).toBe(false);
+        });
+    });
+    describe('rule 3: validator', () => {
+        it.each([
+            ['a missing validator', undefined],
+            ['a string validator', 'etag'],
+            ['a missing kind', { value: 'x' }],
+            ['a missing value', { kind: 'x' }],
+            ['an empty kind', { kind: '', value: 'x' }],
+            ['an empty value', { kind: 'x', value: '' }],
+            ['a kind over the limit', { kind: 'k'.repeat(33), value: 'x' }],
+            ['a value over the limit', { kind: 'x', value: 'v'.repeat(1025) }],
+        ])('rejects %s', (_label, validator) => {
+            expect(isSourceVerificationEvidence({ ...legacyRecord(), validator })).toBe(false);
+        });
+        it('accepts values at the limit', () => {
+            expect(isSourceVerificationEvidence({
+                ...legacyRecord(),
+                validator: { kind: 'k'.repeat(32), value: 'v'.repeat(1024) },
+            })).toBe(true);
+        });
+    });
+    describe('rule 4: verifiedAt', () => {
+        it.each([
+            ['a missing value', undefined],
+            ['a number', 1_790_000_000],
+            ['a date without a time', '2026-10-31'],
+            ['text', 'yesterday'],
+            ['an impossible date', '2026-13-45T00:00:00.000Z'],
+        ])('rejects %s', (_label, verifiedAt) => {
+            expect(isSourceVerificationEvidence({ ...legacyRecord(), verifiedAt })).toBe(false);
+        });
+        it('accepts an offset', () => {
+            expect(isSourceVerificationEvidence({
+                ...legacyRecord(),
+                verifiedAt: '2026-10-31T13:00:00+07:00',
+            })).toBe(true);
+        });
+    });
+    describe('rule 5: size', () => {
+        it.each([
+            ['negative', -1],
+            ['fractional', 1.5],
+            ['a string', '10'],
+            ['unsafe', Number.MAX_SAFE_INTEGER + 1],
+        ])('rejects a size that is %s', (_label, size) => {
+            expect(isSourceVerificationEvidence({ ...legacyRecord(), size })).toBe(false);
+        });
+        it('accepts zero', () => {
+            expect(isSourceVerificationEvidence({ ...legacyRecord(), size: 0 })).toBe(true);
+        });
+    });
+    describe('rules 6 and 7: known values', () => {
+        it('rejects an unknown readBasis', () => {
+            expect(isSourceVerificationEvidence({ ...legacyRecord(), readBasis: 'guess' })).toBe(false);
+        });
+        it('rejects an unknown fallback reason', () => {
+            expect(isSourceVerificationEvidence({ ...legacyRecord(), preconditionFallback: 'other' })).toBe(false);
+        });
+    });
+    describe('rule 8: readBasis and preconditionFallback', () => {
+        it.each([
+            // Legacy records written before readBasis existed.
+            [undefined, undefined, true],
+            [undefined, 'changed', true],
+            [undefined, 'unsupported-kind', true],
+            [undefined, 'unestablishable', true],
+            ['fallback', 'changed', true],
+            ['fallback', 'unsupported-kind', true],
+            ['fallback', 'unestablishable', true],
+            ['fallback', undefined, false],
+            ['expected', undefined, true],
+            ['unconditional', undefined, true],
+            ['expected', 'changed', false],
+            ['unconditional', 'unestablishable', false],
+        ])('readBasis %s with fallback %s is %s', (readBasis, preconditionFallback, valid) => {
+            expect(isSourceVerificationEvidence({
+                ...legacyRecord(),
+                ...(readBasis != null && { readBasis }),
+                ...(preconditionFallback != null && { preconditionFallback }),
+            })).toBe(valid);
+        });
+    });
+});

package/dist/extraction/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 { type ExtractionArtifactIssue, type ExtractionArtifactIssueCode, validateExtractionArtifact, } from './artifact.js';
+export { ExtractionProviderError, isExtractionProviderError, isFileExtractionFailure, } from './errors.js';
+export { isSourceVerificationEvidence } from './evidence.js';
+export { exclusionState } from './outcomes.js';
+export { type PageMapIssue, type PageMapIssueCode, validatePageMap } from './page-map.js';
+export { buildExtractionProducer, type ExtractionProducerIdentity, producerConfigHash, } from './producer.js';
+export { decideExtractionWork, type ExistingExtraction } from './work.js';

package/dist/extraction/index.js

@@ -0,0 +1,17 @@
+/**
+ * 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-safe, provisional extraction contract helpers. The contract types live in
+// `@types/extraction-types.ts`. The verified source read is server-only and lives in
+// `@byline/core/stored-files`.
+export { validateExtractionArtifact, } from './artifact.js';
+export { ExtractionProviderError, isExtractionProviderError, isFileExtractionFailure, } from './errors.js';
+export { isSourceVerificationEvidence } from './evidence.js';
+export { exclusionState } from './outcomes.js';
+export { validatePageMap } from './page-map.js';
+export { buildExtractionProducer, producerConfigHash, } from './producer.js';
+export { decideExtractionWork } from './work.js';

package/dist/extraction/internal.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** A string that both has the form of an ISO 8601 date-time and parses as one. */
+export declare function isIsoDateTime(value: unknown): boolean;
+export declare const isCount: (value: unknown) => boolean;
+/**
+ * Whether every slot of an array passes a check. It reads slots by index because
+ * `every` skips holes, and it stops at the first failure, so a very long sparse array
+ * cannot stall it.
+ */
+export declare function everySlot(value: unknown, check: (slot: unknown) => boolean): boolean;
+/**
+ * Sorted keys and no insignificant whitespace, for hashing a configuration. `undefined`
+ * object members are dropped, so an unset option hashes like an absent one. Any other
+ * value JSON cannot represent exactly is rejected with a `TypeError` rather than coerced,
+ * because two different values must never canonicalise the same. That includes array
+ * holes and symbol keys.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * Whether a value is a strict `JsonValue`. Unlike `canonicalJson`, it rejects an
+ * `undefined` object member, which would be lost on persistence.
+ */
+export declare function isJsonValue(value: unknown): boolean;