@byline/extraction-conformance 0.0.0-stage → 6.13.1

package/LICENSE

@@ -0,0 +1,373 @@
+Mozilla Public License Version 2.0
+==================================
+
+1. Definitions
+--------------
+
+1.1. "Contributor"
+    means each individual or legal entity that creates, contributes to
+    the creation of, or owns Covered Software.
+
+1.2. "Contributor Version"
+    means the combination of the Contributions of others (if any) used
+    by a Contributor and that particular Contributor's Contribution.
+
+1.3. "Contribution"
+    means Covered Software of a particular Contributor.
+
+1.4. "Covered Software"
+    means Source Code Form to which the initial Contributor has attached
+    the notice in Exhibit A, the Executable Form of such Source Code
+    Form, and Modifications of such Source Code Form, in each case
+    including portions thereof.
+
+1.5. "Incompatible With Secondary Licenses"
+    means
+
+    (a) that the initial Contributor has attached the notice described
+        in Exhibit B to the Covered Software; or
+
+    (b) that the Covered Software was made available under the terms of
+        version 1.1 or earlier of the License, but not also under the
+        terms of a Secondary License.
+
+1.6. "Executable Form"
+    means any form of the work other than Source Code Form.
+
+1.7. "Larger Work"
+    means a work that combines Covered Software with other material, in
+    a separate file or files, that is not Covered Software.
+
+1.8. "License"
+    means this document.
+
+1.9. "Licensable"
+    means having the right to grant, to the maximum extent possible,
+    whether at the time of the initial grant or subsequently, any and
+    all of the rights conveyed by this License.
+
+1.10. "Modifications"
+    means any of the following:
+
+    (a) any file in Source Code Form that results from an addition to,
+        deletion from, or modification of the contents of Covered
+        Software; or
+
+    (b) any new file in Source Code Form that contains any Covered
+        Software.
+
+1.11. "Patent Claims" of a Contributor
+    means any patent claim(s), including without limitation, method,
+    process, and apparatus claims, in any patent Licensable by such
+    Contributor that would be infringed, but for the grant of the
+    License, by the making, using, selling, offering for sale, having
+    made, import, or transfer of either its Contributions or its
+    Contributor Version.
+
+1.12. "Secondary License"
+    means either the GNU General Public License, Version 2.0, the GNU
+    Lesser General Public License, Version 2.1, the GNU Affero General
+    Public License, Version 3.0, or any later versions of those
+    licenses.
+
+1.13. "Source Code Form"
+    means the form of the work preferred for making modifications.
+
+1.14. "You" (or "Your")
+    means an individual or a legal entity exercising rights under this
+    License. For legal entities, "You" includes any entity that
+    controls, is controlled by, or is under common control with You. For
+    purposes of this definition, "control" means (a) the power, direct
+    or indirect, to cause the direction or management of such entity,
+    whether by contract or otherwise, or (b) ownership of more than
+    fifty percent (50%) of the outstanding shares or beneficial
+    ownership of such entity.
+
+2. License Grants and Conditions
+--------------------------------
+
+2.1. Grants
+
+Each Contributor hereby grants You a world-wide, royalty-free,
+non-exclusive license:
+
+(a) under intellectual property rights (other than patent or trademark)
+    Licensable by such Contributor to use, reproduce, make available,
+    modify, display, perform, distribute, and otherwise exploit its
+    Contributions, either on an unmodified basis, with Modifications, or
+    as part of a Larger Work; and
+
+(b) under Patent Claims of such Contributor to make, use, sell, offer
+    for sale, have made, import, and otherwise transfer either its
+    Contributions or its Contributor Version.
+
+2.2. Effective Date
+
+The licenses granted in Section 2.1 with respect to any Contribution
+become effective for each Contribution on the date the Contributor first
+distributes such Contribution.
+
+2.3. Limitations on Grant Scope
+
+The licenses granted in this Section 2 are the only rights granted under
+this License. No additional rights or licenses will be implied from the
+distribution or licensing of Covered Software under this License.
+Notwithstanding Section 2.1(b) above, no patent license is granted by a
+Contributor:
+
+(a) for any code that a Contributor has removed from Covered Software;
+    or
+
+(b) for infringements caused by: (i) Your and any other third party's
+    modifications of Covered Software, or (ii) the combination of its
+    Contributions with other software (except as part of its Contributor
+    Version); or
+
+(c) under Patent Claims infringed by Covered Software in the absence of
+    its Contributions.
+
+This License does not grant any rights in the trademarks, service marks,
+or logos of any Contributor (except as may be necessary to comply with
+the notice requirements in Section 3.4).
+
+2.4. Subsequent Licenses
+
+No Contributor makes additional grants as a result of Your choice to
+distribute the Covered Software under a subsequent version of this
+License (see Section 10.2) or under the terms of a Secondary License (if
+permitted under the terms of Section 3.3).
+
+2.5. Representation
+
+Each Contributor represents that the Contributor believes its
+Contributions are its original creation(s) or it has sufficient rights
+to grant the rights to its Contributions conveyed by this License.
+
+2.6. Fair Use
+
+This License is not intended to limit any rights You have under
+applicable copyright doctrines of fair use, fair dealing, or other
+equivalents.
+
+2.7. Conditions
+
+Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
+in Section 2.1.
+
+3. Responsibilities
+-------------------
+
+3.1. Distribution of Source Form
+
+All distribution of Covered Software in Source Code Form, including any
+Modifications that You create or to which You contribute, must be under
+the terms of this License. You must inform recipients that the Source
+Code Form of the Covered Software is governed by the terms of this
+License, and how they can obtain a copy of this License. You may not
+attempt to alter or restrict the recipients' rights in the Source Code
+Form.
+
+3.2. Distribution of Executable Form
+
+If You distribute Covered Software in Executable Form then:
+
+(a) such Covered Software must also be made available in Source Code
+    Form, as described in Section 3.1, and You must inform recipients of
+    the Executable Form how they can obtain a copy of such Source Code
+    Form by reasonable means in a timely manner, at a charge no more
+    than the cost of distribution to the recipient; and
+
+(b) You may distribute such Executable Form under the terms of this
+    License, or sublicense it under different terms, provided that the
+    license for the Executable Form does not attempt to limit or alter
+    the recipients' rights in the Source Code Form under this License.
+
+3.3. Distribution of a Larger Work
+
+You may create and distribute a Larger Work under terms of Your choice,
+provided that You also comply with the requirements of this License for
+the Covered Software. If the Larger Work is a combination of Covered
+Software with a work governed by one or more Secondary Licenses, and the
+Covered Software is not Incompatible With Secondary Licenses, this
+License permits You to additionally distribute such Covered Software
+under the terms of such Secondary License(s), so that the recipient of
+the Larger Work may, at their option, further distribute the Covered
+Software under the terms of either this License or such Secondary
+License(s).
+
+3.4. Notices
+
+You may not remove or alter the substance of any license notices
+(including copyright notices, patent notices, disclaimers of warranty,
+or limitations of liability) contained within the Source Code Form of
+the Covered Software, except that You may alter any license notices to
+the extent required to remedy known factual inaccuracies.
+
+3.5. Application of Additional Terms
+
+You may choose to offer, and to charge a fee for, warranty, support,
+indemnity or liability obligations to one or more recipients of Covered
+Software. However, You may do so only on Your own behalf, and not on
+behalf of any Contributor. You must make it absolutely clear that any
+such warranty, support, indemnity, or liability obligation is offered by
+You alone, and You hereby agree to indemnify every Contributor for any
+liability incurred by such Contributor as a result of warranty, support,
+indemnity or liability terms You offer. You may include additional
+disclaimers of warranty and limitations of liability specific to any
+jurisdiction.
+
+4. Inability to Comply Due to Statute or Regulation
+---------------------------------------------------
+
+If it is impossible for You to comply with any of the terms of this
+License with respect to some or all of the Covered Software due to
+statute, judicial order, or regulation then You must: (a) comply with
+the terms of this License to the maximum extent possible; and (b)
+describe the limitations and the code they affect. Such description must
+be placed in a text file included with all distributions of the Covered
+Software under this License. Except to the extent prohibited by statute
+or regulation, such description must be sufficiently detailed for a
+recipient of ordinary skill to be able to understand it.
+
+5. Termination
+--------------
+
+5.1. The rights granted under this License will terminate automatically
+if You fail to comply with any of its terms. However, if You become
+compliant, then the rights granted under this License from a particular
+Contributor are reinstated (a) provisionally, unless and until such
+Contributor explicitly and finally terminates Your grants, and (b) on an
+ongoing basis, if such Contributor fails to notify You of the
+non-compliance by some reasonable means prior to 60 days after You have
+come back into compliance. Moreover, Your grants from a particular
+Contributor are reinstated on an ongoing basis if such Contributor
+notifies You of the non-compliance by some reasonable means, this is the
+first time You have received notice of non-compliance with this License
+from such Contributor, and You become compliant prior to 30 days after
+Your receipt of the notice.
+
+5.2. If You initiate litigation against any entity by asserting a patent
+infringement claim (excluding declaratory judgment actions,
+counter-claims, and cross-claims) alleging that a Contributor Version
+directly or indirectly infringes any patent, then the rights granted to
+You by any and all Contributors for the Covered Software under Section
+2.1 of this License shall terminate.
+
+5.3. In the event of termination under Sections 5.1 or 5.2 above, all
+end user license agreements (excluding distributors and resellers) which
+have been validly granted by You or Your distributors under this License
+prior to termination shall survive termination.
+
+************************************************************************
+*                                                                      *
+*  6. Disclaimer of Warranty                                           *
+*  -------------------------                                           *
+*                                                                      *
+*  Covered Software is provided under this License on an "as is"       *
+*  basis, without warranty of any kind, either expressed, implied, or  *
+*  statutory, including, without limitation, warranties that the       *
+*  Covered Software is free of defects, merchantable, fit for a        *
+*  particular purpose or non-infringing. The entire risk as to the     *
+*  quality and performance of the Covered Software is with You.        *
+*  Should any Covered Software prove defective in any respect, You     *
+*  (not any Contributor) assume the cost of any necessary servicing,   *
+*  repair, or correction. This disclaimer of warranty constitutes an   *
+*  essential part of this License. No use of any Covered Software is   *
+*  authorized under this License except under this disclaimer.         *
+*                                                                      *
+************************************************************************
+
+************************************************************************
+*                                                                      *
+*  7. Limitation of Liability                                          *
+*  --------------------------                                          *
+*                                                                      *
+*  Under no circumstances and under no legal theory, whether tort      *
+*  (including negligence), contract, or otherwise, shall any           *
+*  Contributor, or anyone who distributes Covered Software as          *
+*  permitted above, be liable to You for any direct, indirect,         *
+*  special, incidental, or consequential damages of any character      *
+*  including, without limitation, damages for lost profits, loss of    *
+*  goodwill, work stoppage, computer failure or malfunction, or any    *
+*  and all other commercial damages or losses, even if such party      *
+*  shall have been informed of the possibility of such damages. This   *
+*  limitation of liability shall not apply to liability for death or   *
+*  personal injury resulting from such party's negligence to the       *
+*  extent applicable law prohibits such limitation. Some               *
+*  jurisdictions do not allow the exclusion or limitation of           *
+*  incidental or consequential damages, so this exclusion and          *
+*  limitation may not apply to You.                                    *
+*                                                                      *
+************************************************************************
+
+8. Litigation
+-------------
+
+Any litigation relating to this License may be brought only in the
+courts of a jurisdiction where the defendant maintains its principal
+place of business and such litigation shall be governed by laws of that
+jurisdiction, without reference to its conflict-of-law provisions.
+Nothing in this Section shall prevent a party's ability to bring
+cross-claims or counter-claims.
+
+9. Miscellaneous
+----------------
+
+This License represents the complete agreement concerning the subject
+matter hereof. If any provision of this License is held to be
+unenforceable, such provision shall be reformed only to the extent
+necessary to make it enforceable. Any law or regulation which provides
+that the language of a contract shall be construed against the drafter
+shall not be used to construe this License against a Contributor.
+
+10. Versions of the License
+---------------------------
+
+10.1. New Versions
+
+Mozilla Foundation is the license steward. Except as provided in Section
+10.3, no one other than the license steward has the right to modify or
+publish new versions of this License. Each version will be given a
+distinguishing version number.
+
+10.2. Effect of New Versions
+
+You may distribute the Covered Software under the terms of the version
+of the License under which You originally received the Covered Software,
+or under the terms of any subsequent version published by the license
+steward.
+
+10.3. Modified Versions
+
+If you create software not governed by this License, and you want to
+create a new license for such software, you may create and use a
+modified version of this License if you rename the license and remove
+any references to the name of the license steward (except to note that
+such modified license differs from this License).
+
+10.4. Distributing Source Code Form that is Incompatible With Secondary
+Licenses
+
+If You choose to distribute Source Code Form that is Incompatible With
+Secondary Licenses under the terms of this version of the License, the
+notice described in Exhibit B of this License must be attached.
+
+Exhibit A - Source Code Form License Notice
+-------------------------------------------
+
+  This Source Code Form 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 https://mozilla.org/MPL/2.0/.
+
+If it is not possible or desirable to put the notice in a particular
+file, then You may include the notice in a location (such as a LICENSE
+file in a relevant directory) where a recipient would be likely to look
+for such a notice.
+
+You may add additional accurate notices of copyright ownership.
+
+Exhibit B - "Incompatible With Secondary Licenses" Notice
+---------------------------------------------------------
+
+  This Source Code Form is "Incompatible With Secondary Licenses", as
+  defined by the Mozilla Public License, v. 2.0.

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# @byline/extraction-conformance
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Vitest kit that tests whether a Byline extraction provider honours the provider
+contract. Use it when you are writing or changing a driver for an extractor such as
+Apache Tika, Docling, an OCR service, or a hosted vision model.
+
+The contract and this kit are **provisional**. Until the contract is declared stable,
+a minor release may change them, and the changelog will say so.
+
+## Install
+
+The kit needs Vitest as a peer dependency, and it uses the same version of
+`@byline/core` as the rest of your Byline packages.
+
+```sh
+pnpm add -D @byline/extraction-conformance vitest
+```
+
+## Run the kit against a driver
+
+Call `defineExtractionProviderConformance` at the top level of a test file.
+
+```ts
+import { defineExtractionProviderConformance } from '@byline/extraction-conformance'
+
+import { createMyDriver } from './my-driver.js'
+
+defineExtractionProviderConformance({
+  name: 'my-driver',
+  createProvider: () => createMyDriver({ url: process.env.DRIVER_URL ?? '' }),
+  createUnavailableProvider: () => createMyDriver({ url: 'http://127.0.0.1:9' }),
+})
+```
+
+| Hook | Required | Purpose |
+|---|---|---|
+| `name` | Yes | Shown in the suite name |
+| `createProvider` | Yes | A provider connected to a working engine |
+| `createUnavailableProvider` | No | A provider whose service cannot be reached. Without it, case 6 is skipped |
+| `timeoutMs` | No | The timeout per case. The default is 60 seconds, for remote engines |
+
+Run it against a real engine. A fake that imitates your engine shows only that the
+fake passes. A case is skipped rather than passed when it does not apply, for example
+the page map case for a driver that declares `capabilities.pageMap` as `false`.
+
+## What the kit checks
+
+The nine cases cover capability honesty, result shape, sentinel text, page map
+sentinels, typed file failures, typed infrastructure failures, abort, input forms, and
+version consistency. The [extraction provider contract](https://github.com/Byline-CMS/bylinecms.dev/blob/develop/docs/06-search/10-extraction-provider-contract.md#conformance-kit)
+describes each one.
+
+- **Only the page map sentinel case makes a provenance claim.** A map can pass
+  `validatePageMap` with its pages in the wrong order. That case confirms that each
+  sentinel lies in the page it came from.
+- **A truncated PDF may resolve.** A parser that recovers a damaged file has not
+  failed, so the kit accepts either a typed `file` failure or a valid result. A corrupt
+  file must reject with a typed `file` failure.
+- **OCR, tables, formulas, and charts are not verified.** Those capabilities are
+  declared by the author.
+
+## Fixtures
+
+| File | Contents |
+|---|---|
+| `fixtures/sentinel.pdf` | Three born-digital pages, with one unique sentinel per page (`BYLINE-SENTINEL-PAGE-1` and so on) |
+| `fixtures/truncated.pdf` | The first half of `sentinel.pdf`, with no cross-reference table |
+| `fixtures/corrupt.pdf` | A PDF header followed by bytes with no PDF structure to recover |
+
+The fixtures are hand-written PDF syntax, with no dependencies. To regenerate them from
+the script shipped with the package:
+
+```sh
+node node_modules/@byline/extraction-conformance/scripts/generate-fixtures.mjs ./out
+```
+
+An engine's result for these fixtures describes that engine only. If a legitimate
+engine recovers the corrupt fixture, please report it rather than treating the driver
+as defective.
+
+## Use the cases without Vitest's wrapper
+
+Each case is a plain async function in `extractionProviderConformanceCases`. A case
+resolves when the provider passes, resolves with `{ skipped }` when it does not apply,
+and rejects with `ConformanceFailure` otherwise. Pass it your hooks and the result of
+`loadFixtures()`. The package root still imports Vitest, so Vitest must be installed.
+
+## License
+
+MPL-2.0.

package/dist/cases.d.ts

@@ -0,0 +1,73 @@
+/**
+ * This Source Code Form 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 https://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { ExtractionProvider } from '@byline/core';
+/**
+ * The sentinel on each physical page of `sentinel.pdf`, in page order.
+ *
+ * @provisional
+ */
+export declare const SENTINELS: readonly ['BYLINE-SENTINEL-PAGE-1', 'BYLINE-SENTINEL-PAGE-2', 'BYLINE-SENTINEL-PAGE-3'];
+/**
+ * The hooks a driver author supplies.
+ *
+ * @provisional
+ */
+export interface ConformanceHooks {
+    /** Shown in suite names, for example `'tika'`. */
+    name: string;
+    createProvider(): ExtractionProvider | Promise<ExtractionProvider>;
+    /** A provider whose service cannot be reached. Enables case 6. */
+    createUnavailableProvider?(): ExtractionProvider | Promise<ExtractionProvider>;
+    /** Per-case timeout in milliseconds. Default 60 seconds, for remote engines. */
+    timeoutMs?: number;
+}
+/**
+ * The fixture files, as bytes.
+ *
+ * @provisional
+ */
+export interface ConformanceFixtures {
+    sentinel: Buffer;
+    truncated: Buffer;
+    corrupt: Buffer;
+}
+/**
+ * Reads the fixtures shipped with this package.
+ *
+ * @provisional
+ */
+export declare function loadFixtures(): ConformanceFixtures;
+/**
+ * A provider broke a conformance rule.
+ *
+ * @provisional
+ */
+export declare class ConformanceFailure extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * One conformance case. It resolves when the provider passes, resolves with `skipped`
+ * when the case does not apply, and rejects with `ConformanceFailure` otherwise.
+ *
+ * @provisional
+ */
+export interface ExtractionProviderConformanceCase {
+    id: number;
+    name: string;
+    run(hooks: ConformanceHooks, fixtures: ConformanceFixtures): Promise<undefined | {
+        skipped: string;
+    }>;
+}
+/**
+ * Every case, in specification order.
+ *
+ * @provisional
+ */
+export declare const extractionProviderConformanceCases: readonly ExtractionProviderConformanceCase[];

package/dist/cases.js

@@ -0,0 +1,329 @@
+/**
+ * This Source Code Form 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 https://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+// The conformance cases are plain async functions. They have no test-runner dependency,
+// and `defineExtractionProviderConformance` registers them with Vitest.
+import { readFileSync } from 'node:fs';
+import { isExtractionProviderError, isFileExtractionFailure, validateExtractionArtifact, validatePageMap, } from '@byline/core';
+/**
+ * The sentinel on each physical page of `sentinel.pdf`, in page order.
+ *
+ * @provisional
+ */
+export const SENTINELS = [
+    'BYLINE-SENTINEL-PAGE-1',
+    'BYLINE-SENTINEL-PAGE-2',
+    'BYLINE-SENTINEL-PAGE-3',
+];
+const PDF = 'application/pdf';
+// Outside any `type/*` wildcard a provider might plausibly list.
+const UNSUPPORTED_TYPE = 'x-byline-conformance/unsupported';
+/**
+ * Reads the fixtures shipped with this package.
+ *
+ * @provisional
+ */
+export function loadFixtures() {
+    const read = (name) => readFileSync(new URL(`../fixtures/${name}`, import.meta.url));
+    return {
+        sentinel: read('sentinel.pdf'),
+        truncated: read('truncated.pdf'),
+        corrupt: read('corrupt.pdf'),
+    };
+}
+/**
+ * A provider broke a conformance rule.
+ *
+ * @provisional
+ */
+export class ConformanceFailure extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'ConformanceFailure';
+    }
+}
+const fail = (message, cause) => {
+    throw new ConformanceFailure(message, cause === undefined ? undefined : { cause });
+};
+const describeError = (error) => error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+function acceptsPdf(capabilities) {
+    return (Array.isArray(capabilities.formats) &&
+        capabilities.formats.some((format) => format === '*/*' || format === 'application/*' || format === PDF));
+}
+/** A type the provider accepts, for cases that are not about formats. */
+function declaredType(capabilities) {
+    if (acceptsPdf(capabilities))
+        return PDF;
+    const first = capabilities.formats?.[0] ?? PDF;
+    return first.replace(/\*$/, 'plain');
+}
+const PDF_SKIP = {
+    skipped: `This case uses a PDF fixture, and the provider does not accept ${PDF}.`,
+};
+/** Extracts the given bytes, passing a copy so a provider cannot change a fixture. */
+function extract(provider, bytes, mimeType = PDF, filename = 'fixture.pdf') {
+    return provider.extract({ data: new Uint8Array(bytes), filename, mimeType });
+}
+/** Extracts the sentinel fixture, which every accepting provider must handle. */
+async function extractSentinel(provider, fixtures) {
+    try {
+        return await extract(provider, fixtures.sentinel);
+    }
+    catch (error) {
+        return fail(`Extracting the sentinel fixture rejected: ${describeError(error)}`, error);
+    }
+}
+/**
+ * Every rule of a result's structural shape, including its page map against its own
+ * `pageCount`. Whether the map's pages are the physical pages is case 4's question alone.
+ */
+function shapeProblems(provider, result) {
+    const problems = [];
+    if (typeof result !== 'object' || result === null)
+        return ['the result is not an object'];
+    if (result.provider !== provider.name) {
+        problems.push(`result.provider is ${String(result.provider)}, not ${provider.name}`);
+    }
+    if (result.providerVersion !== undefined &&
+        (typeof result.providerVersion !== 'string' || result.providerVersion === '')) {
+        problems.push('providerVersion must be a non-empty string when present');
+    }
+    const shape = validateExtractionArtifact({
+        ...result,
+        schemaVersion: 1,
+        contentHash: null,
+        sourceVerified: false,
+        providerVersion: null,
+        producerConfigHash: null,
+        producedAt: '2026-01-01T00:00:00.000Z',
+    }, { allowUnrecordedProducer: true });
+    if (!shape.ok)
+        problems.push(...shape.issues.map((issue) => issue.message));
+    return problems;
+}
+const CAPABILITY_FLAGS = [
+    'ocr',
+    'markdown',
+    'tables',
+    'formulas',
+    'charts',
+    'coordinates',
+    'pageMap',
+    'structure',
+];
+const FORMAT = /^(\*\/\*|[a-z0-9.+-]+\/(\*|[a-z0-9.+-]+))$/i;
+/** Reads by index because `every` skips holes, and stops at the first bad slot. */
+function isDenseFormatList(formats) {
+    for (let i = 0; i < formats.length; i += 1) {
+        const format = formats[i];
+        if (typeof format !== 'string' || !FORMAT.test(format))
+            return false;
+    }
+    return true;
+}
+async function capabilityHonesty(hooks, fixtures) {
+    const provider = await hooks.createProvider();
+    const { capabilities } = provider;
+    for (const flag of CAPABILITY_FLAGS) {
+        if (typeof capabilities?.[flag] !== 'boolean')
+            fail(`capabilities.${flag} must be a boolean`);
+    }
+    if (!Array.isArray(capabilities.formats) ||
+        capabilities.formats.length === 0 ||
+        !isDenseFormatList(capabilities.formats)) {
+        fail('capabilities.formats must be a non-empty list of MIME types or wildcards');
+    }
+    if (!acceptsPdf(capabilities))
+        return undefined;
+    const result = await extractSentinel(provider, fixtures);
+    for (const member of ['markdown', 'structure', 'pageMap']) {
+        const present = result[member] !== undefined;
+        if (present !== capabilities[member]) {
+            fail(`capabilities.${member} is ${capabilities[member]}, ` +
+                `but the result ${present ? 'has' : 'does not have'} that member`);
+        }
+    }
+    return undefined;
+}
+async function resultShape(hooks, fixtures) {
+    const provider = await hooks.createProvider();
+    if (!acceptsPdf(provider.capabilities))
+        return PDF_SKIP;
+    const problems = shapeProblems(provider, await extractSentinel(provider, fixtures));
+    if (problems.length > 0)
+        fail(problems.join('; '));
+    return undefined;
+}
+async function sentinelText(hooks, fixtures) {
+    const provider = await hooks.createProvider();
+    if (!acceptsPdf(provider.capabilities))
+        return PDF_SKIP;
+    const { plainText } = await extractSentinel(provider, fixtures);
+    for (const sentinel of SENTINELS) {
+        if (!plainText.includes(sentinel))
+            fail(`plainText does not contain ${sentinel}`);
+    }
+    return undefined;
+}
+/** The only provenance check in the kit. Structural validity alone proves nothing. */
+async function pageMapSentinels(hooks, fixtures) {
+    const provider = await hooks.createProvider();
+    if (!provider.capabilities.pageMap) {
+        return { skipped: 'The provider declares capabilities.pageMap as false.' };
+    }
+    if (!acceptsPdf(provider.capabilities))
+        return PDF_SKIP;
+    const { plainText, pageMap } = await extractSentinel(provider, fixtures);
+    if (pageMap === undefined)
+        return fail('capabilities.pageMap is true, but there is no pageMap');
+    const structure = validatePageMap(plainText, pageMap, { pageCount: SENTINELS.length });
+    if (!structure.ok) {
+        fail(`validatePageMap: ${structure.issues.map((issue) => issue.code).join(', ')}`);
+    }
+    SENTINELS.forEach((sentinel, i) => {
+        const pageNumber = i + 1;
+        const page = pageMap.pages.find((candidate) => candidate.index === pageNumber);
+        let found = false;
+        for (let at = plainText.indexOf(sentinel); at !== -1; at = plainText.indexOf(sentinel, at + 1)) {
+            const inPage = page !== undefined && at >= page.charStart && at + sentinel.length <= page.charEnd;
+            if (!inPage)
+                fail(`${sentinel} at offset ${at} lies outside page ${pageNumber}`);
+            found = true;
+        }
+        if (!found)
+            fail(`${sentinel} does not appear in page ${pageNumber}`);
+    });
+    return undefined;
+}
+async function typedFileFailure(hooks, fixtures) {
+    const provider = await hooks.createProvider();
+    const { capabilities } = provider;
+    if (acceptsPdf(capabilities)) {
+        // Recovering a damaged file is legitimate. Misreporting one is not.
+        const truncated = await extract(provider, fixtures.truncated).then((result) => ({ result }), (error) => ({ error }));
+        if ('error' in truncated) {
+            if (!isFileExtractionFailure(truncated.error)) {
+                fail('A truncated PDF must resolve or reject with a typed file failure, ' +
+                    `not ${describeError(truncated.error)}`, truncated.error);
+            }
+        }
+        else {
+            const problems = shapeProblems(provider, truncated.result);
+            if (problems.length > 0)
+                fail(`The truncated file's result: ${problems.join('; ')}`);
+        }
+        const corrupt = await extract(provider, fixtures.corrupt).then(() => null, (error) => ({ error }));
+        if (corrupt === null)
+            fail('A corrupt PDF must reject with a typed file failure, but resolved');
+        else if (!isFileExtractionFailure(corrupt.error)) {
+            fail(`A corrupt PDF must reject with a typed file failure, not ${describeError(corrupt.error)}`, corrupt.error);
+        }
+    }
+    if (!capabilities.formats.includes('*/*')) {
+        const unsupported = await extract(provider, fixtures.sentinel, UNSUPPORTED_TYPE, 'fixture.bin').then(() => null, (error) => ({ error }));
+        if (unsupported === null) {
+            fail(`A type outside capabilities.formats must reject, but ${UNSUPPORTED_TYPE} resolved`);
+        }
+        else if (!isFileExtractionFailure(unsupported.error)) {
+            fail('A type outside capabilities.formats must reject with a typed file failure, ' +
+                `not ${describeError(unsupported.error)}`, unsupported.error);
+        }
+    }
+    return undefined;
+}
+async function typedInfrastructureFailure(hooks, fixtures) {
+    if (hooks.createUnavailableProvider === undefined) {
+        return { skipped: 'No createUnavailableProvider hook was given.' };
+    }
+    const provider = await hooks.createUnavailableProvider();
+    const rejection = await extract(provider, fixtures.sentinel, declaredType(provider.capabilities)).then(() => null, (error) => ({ error }));
+    if (rejection === null ||
+        !isExtractionProviderError(rejection.error) ||
+        rejection.error.failureScope !== 'infrastructure') {
+        fail('An unavailable service must reject with a typed infrastructure failure, not ' +
+            (rejection === null ? 'a result' : describeError(rejection.error)), rejection?.error);
+    }
+    if (provider.ping !== undefined) {
+        const pinged = await provider.ping().then(() => true, () => false);
+        if (pinged)
+            fail('ping must reject when the service is unavailable, but it resolved');
+    }
+    return undefined;
+}
+async function abort(hooks, fixtures) {
+    const provider = await hooks.createProvider();
+    const controller = new AbortController();
+    controller.abort();
+    const rejection = await provider
+        .extract({
+        data: new Uint8Array(fixtures.sentinel),
+        filename: 'fixture.pdf',
+        mimeType: declaredType(provider.capabilities),
+        signal: controller.signal,
+    })
+        .then(() => null, (error) => ({ error }));
+    if (rejection === null)
+        fail('An aborted signal must reject, but the extraction resolved');
+    else if (isFileExtractionFailure(rejection.error)) {
+        fail('An abort must not be reported as a file failure', rejection.error);
+    }
+    return undefined;
+}
+async function inputForms(hooks, fixtures) {
+    const provider = await hooks.createProvider();
+    if (!acceptsPdf(provider.capabilities))
+        return PDF_SKIP;
+    const fromBytes = await extractSentinel(provider, fixtures);
+    const copy = new Uint8Array(fixtures.sentinel);
+    const stream = new ReadableStream({
+        start(controller) {
+            controller.enqueue(copy);
+            controller.close();
+        },
+    });
+    const fromStream = await provider
+        .extract({ data: stream, filename: 'fixture.pdf', mimeType: PDF })
+        .catch((error) => fail(`Extracting from a stream rejected: ${describeError(error)}`, error));
+    if (fromStream.plainText !== fromBytes.plainText) {
+        fail('Stream input and byte-array input gave different plainText');
+    }
+    return undefined;
+}
+/** Assumes the engine does not change during the test run. */
+async function versionConsistency(hooks, fixtures) {
+    const provider = await hooks.createProvider();
+    if (provider.resolveVersion === undefined) {
+        return { skipped: 'The provider does not implement resolveVersion.' };
+    }
+    const version = await provider.resolveVersion();
+    if (typeof version !== 'string' || version === '') {
+        fail('resolveVersion must resolve a non-empty string');
+    }
+    if (!acceptsPdf(provider.capabilities))
+        return PDF_SKIP;
+    const { providerVersion } = await extractSentinel(provider, fixtures);
+    if (providerVersion !== version) {
+        fail(`resolveVersion gave ${version}, but the result's providerVersion is ${providerVersion}`);
+    }
+    return undefined;
+}
+/**
+ * Every case, in specification order.
+ *
+ * @provisional
+ */
+export const extractionProviderConformanceCases = [
+    { id: 1, name: 'capability honesty', run: capabilityHonesty },
+    { id: 2, name: 'result shape', run: resultShape },
+    { id: 3, name: 'sentinel text', run: sentinelText },
+    { id: 4, name: 'page map sentinel verification', run: pageMapSentinels },
+    { id: 5, name: 'typed file failure', run: typedFileFailure },
+    { id: 6, name: 'typed infrastructure failure', run: typedInfrastructureFailure },
+    { id: 7, name: 'abort', run: abort },
+    { id: 8, name: 'input forms', run: inputForms },
+    { id: 9, name: 'version consistency', run: versionConsistency },
+];

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * This Source Code Form 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 https://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { type ConformanceHooks } from './cases.js';
+export { ConformanceFailure, type ConformanceFixtures, type ConformanceHooks, type ExtractionProviderConformanceCase, extractionProviderConformanceCases, loadFixtures, SENTINELS, } from './cases.js';
+/**
+ * Registers the extraction provider conformance cases with Vitest. Call it at the top
+ * level of a test file.
+ *
+ * OCR, tables, formulas and charts are declared by the author and are not verified. The
+ * page map sentinel case is the only provenance claim the kit makes.
+ *
+ * @provisional
+ */
+export declare function defineExtractionProviderConformance(hooks: ConformanceHooks): void;

package/dist/index.js

@@ -0,0 +1,32 @@
+/**
+ * This Source Code Form 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 https://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { describe, it } from 'vitest';
+import { extractionProviderConformanceCases, loadFixtures } from './cases.js';
+export { ConformanceFailure, extractionProviderConformanceCases, loadFixtures, SENTINELS, } from './cases.js';
+const DEFAULT_TIMEOUT_MS = 60_000;
+/**
+ * Registers the extraction provider conformance cases with Vitest. Call it at the top
+ * level of a test file.
+ *
+ * OCR, tables, formulas and charts are declared by the author and are not verified. The
+ * page map sentinel case is the only provenance claim the kit makes.
+ *
+ * @provisional
+ */
+export function defineExtractionProviderConformance(hooks) {
+    describe(`${hooks.name} extraction provider conformance`, () => {
+        const fixtures = loadFixtures();
+        for (const { id, name, run } of extractionProviderConformanceCases) {
+            it(`case ${id}: ${name}`, async (context) => {
+                const outcome = await run(hooks, fixtures);
+                if (outcome !== undefined)
+                    context.skip(outcome.skipped);
+            }, hooks.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        }
+    });
+}

package/fixtures/corrupt.pdf

@@ -0,0 +1,6 @@
+%PDF-1.4
+��`D�ɜ�"
+d>1hg��=�.��������7(�SLC���!��8q2���Ic����K�i�X�j����\�Wu0-?z�F�BZU޷a^~�3��׮�J�/��`D�ɜ�"
+d>1hg��=�.��������7(�SLC���!��8q2���Ic����K�i�X�j����\�Wu0-?z�F�BZU޷a^~�3��׮�J�/��`D�ɜ�"
+d>1hg��=�.��������7(�SLC���!��8q2���Ic����K�i�X�j����\�Wu0-?z�F�BZU޷a^~�3��׮�J�/��`D�ɜ�"
+d>1hg��=�.��������7(�SLC���!��8q2���Ic����K�i�X�j����\�Wu0-?z�F�BZU޷a^~�3��׮�J�/��`D�ɜ�"

package/fixtures/sentinel.pdf

@@ -0,0 +1,54 @@
+%PDF-1.4
+1 0 obj
+<< /Type /Catalog /Pages 2 0 R >>
+endobj
+2 0 obj
+<< /Type /Pages /Kids [4 0 R 6 0 R 8 0 R] /Count 3 >>
+endobj
+3 0 obj
+<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>
+endobj
+4 0 obj
+<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Resources << /Font << /F1 3 0 R >> >> /Contents 5 0 R >>
+endobj
+5 0 obj
+<< /Length 53 >>
+stream
+BT /F1 12 Tf 72 720 Td (BYLINE-SENTINEL-PAGE-1) Tj ET
+endstream
+endobj
+6 0 obj
+<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Resources << /Font << /F1 3 0 R >> >> /Contents 7 0 R >>
+endobj
+7 0 obj
+<< /Length 53 >>
+stream
+BT /F1 12 Tf 72 720 Td (BYLINE-SENTINEL-PAGE-2) Tj ET
+endstream
+endobj
+8 0 obj
+<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Resources << /Font << /F1 3 0 R >> >> /Contents 9 0 R >>
+endobj
+9 0 obj
+<< /Length 53 >>
+stream
+BT /F1 12 Tf 72 720 Td (BYLINE-SENTINEL-PAGE-3) Tj ET
+endstream
+endobj
+xref
+0 10
+0000000000 65535 f 
+0000000009 00000 n 
+0000000058 00000 n 
+0000000127 00000 n 
+0000000197 00000 n 
+0000000323 00000 n 
+0000000426 00000 n 
+0000000552 00000 n 
+0000000655 00000 n 
+0000000781 00000 n 
+trailer
+<< /Size 10 /Root 1 0 R >>
+startxref
+884
+%%EOF

package/fixtures/truncated.pdf

@@ -0,0 +1,24 @@
+%PDF-1.4
+1 0 obj
+<< /Type /Catalog /Pages 2 0 R >>
+endobj
+2 0 obj
+<< /Type /Pages /Kids [4 0 R 6 0 R 8 0 R] /Count 3 >>
+endobj
+3 0 obj
+<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>
+endobj
+4 0 obj
+<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Resources << /Font << /F1 3 0 R >> >> /Contents 5 0 R >>
+endobj
+5 0 obj
+<< /Length 53 >>
+stream
+BT /F1 12 Tf 72 720 Td (BYLINE-SENTINEL-PAGE-1) Tj ET
+endstream
+endobj
+6 0 obj
+<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Resources << /Font << /F1 3 0 R >> >> /Contents 7 0 R >>
+endobj
+7 0 obj
+<< /Length 53 

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@byline/extraction-conformance",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "private": false,
+  "license": "MPL-2.0",
+  "version": "6.13.1",
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "description": "Behavioural conformance kit for Byline CMS extraction providers",
+  "keywords": [
+    "cms",
+    "headless cms",
+    "extraction",
+    "conformance",
+    "testing"
+  ],
+  "homepage": "https://github.com/Byline-CMS/bylinecms.dev",
+  "bugs": {
+    "url": "https://github.com/Byline-CMS/bylinecms.dev/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Byline-CMS/bylinecms.dev.git",
+    "directory": "packages/extraction-conformance"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "index": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "fixtures",
+    "scripts/generate-fixtures.mjs",
+    "!dist/**/*.test.node.*"
+  ],
+  "dependencies": {
+    "@byline/core": "6.13.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.6.4",
+    "@types/node": "^26.6.6",
+    "chokidar": "^6.0.0",
+    "chokidar-cli": "^3.0.0",
+    "npm-run-all": "^4.1.5",
+    "tsc-alias": "^1.9.10",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "peerDependencies": {
+    "vitest": "^5.0.5"
+  },
+  "scripts": {
+    "dev": "chokidar 'src/**/*' -c 'npm-run-all build'",
+    "build": "tsc -p tsconfig.json && tsc-alias",
+    "clean": "node scripts/clean.js node_modules dist build .turbo",
+    "lint": "biome check --write --unsafe --diagnostic-level=error",
+    "test": "vitest run --mode=node",
+    "test:watch": "vitest --mode=node",
+    "typecheck": "tsc --noEmit",
+    "generate:fixtures": "node scripts/generate-fixtures.mjs"
+  }
 }

package/scripts/generate-fixtures.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * This Source Code Form 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 https://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+// Writes the conformance fixtures, using hand-written PDF syntax and no dependencies.
+// The output is committed, and a test asserts that it matches this script.
+//
+//   sentinel.pdf   three born-digital pages, with one unique sentinel per page
+//   truncated.pdf  the first half of sentinel.pdf, with no cross-reference table
+//   corrupt.pdf    a PDF header followed by bytes with no PDF structure to recover
+//
+// Usage: node scripts/generate-fixtures.mjs [output-directory]
+
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PAGE_COUNT = 3
+
+function buildSentinelPdf() {
+  const firstPageObject = 4
+  const pageObject = (page) => firstPageObject + (page - 1) * 2
+  const kids = Array.from({ length: PAGE_COUNT }, (_, i) => `${pageObject(i + 1)} 0 R`).join(' ')
+
+  const objects = new Map([
+    [1, '<< /Type /Catalog /Pages 2 0 R >>'],
+    [2, `<< /Type /Pages /Kids [${kids}] /Count ${PAGE_COUNT} >>`],
+    [3, '<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>'],
+  ])
+  for (let page = 1; page <= PAGE_COUNT; page += 1) {
+    const content = `BT /F1 12 Tf 72 720 Td (BYLINE-SENTINEL-PAGE-${page}) Tj ET`
+    objects.set(
+      pageObject(page),
+      '<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] ' +
+        `/Resources << /Font << /F1 3 0 R >> >> /Contents ${pageObject(page) + 1} 0 R >>`
+    )
+    objects.set(
+      pageObject(page) + 1,
+      `<< /Length ${content.length} >>\nstream\n${content}\nendstream`
+    )
+  }
+
+  let pdf = '%PDF-1.4\n'
+  const offsets = []
+  const ids = [...objects.keys()].sort((a, b) => a - b)
+  for (const id of ids) {
+    offsets[id] = pdf.length
+    pdf += `${id} 0 obj\n${objects.get(id)}\nendobj\n`
+  }
+  const xref = pdf.length
+  pdf += `xref\n0 ${ids.length + 1}\n0000000000 65535 f \n`
+  for (const id of ids) pdf += `${String(offsets[id]).padStart(10, '0')} 00000 n \n`
+  pdf += `trailer\n<< /Size ${ids.length + 1} /Root 1 0 R >>\nstartxref\n${xref}\n%%EOF\n`
+  return Buffer.from(pdf, 'latin1')
+}
+
+function buildCorruptPdf() {
+  const header = Buffer.from('%PDF-1.4\n', 'latin1')
+  const noise = Buffer.alloc(512)
+  // A fixed sequence, so the file is reproducible. It holds no PDF objects.
+  let state = 0x2f
+  for (let i = 0; i < noise.length; i += 1) {
+    state = (state * 73 + 41) % 251
+    noise[i] = state
+  }
+  return Buffer.concat([header, noise])
+}
+
+export function buildFixtures() {
+  const sentinel = buildSentinelPdf()
+  return {
+    'sentinel.pdf': sentinel,
+    'truncated.pdf': sentinel.subarray(0, Math.floor(sentinel.length / 2)),
+    'corrupt.pdf': buildCorruptPdf(),
+  }
+}
+
+const script = fileURLToPath(import.meta.url)
+if (process.argv[1] !== undefined && resolve(process.argv[1]) === script) {
+  const output = process.argv[2] ?? join(dirname(script), '..', 'fixtures')
+  mkdirSync(output, { recursive: true })
+  for (const [name, bytes] of Object.entries(buildFixtures())) {
+    writeFileSync(join(output, name), bytes)
+  }
+}