@xml-auditfile/auditfile 0.0.0-stage → 0.0.2-alpha.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,184 @@
-# Temporary Holding Version
+# auditfile-js
 
-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.
+Streaming reader for Dutch tax audit files (XAF and related), following
+[auditfile-spec](https://github.com/XML-auditfile/auditfile-spec). The JavaScript counterpart of
+[auditfile-dotnet](https://github.com/XML-auditfile/auditfile-dotnet), with the same API in JavaScript style.
+
+> Status: draft (0.x).
+> Not affiliated with the Belastingdienst, SRA or any software vendor.
+
+```
+npm install @xml-auditfile/auditfile
+```
+
+The package ships TypeScript declarations, generated from the JSDoc. Every version is published from GitHub Actions with
+[provenance](https://docs.npmjs.com/generating-provenance-statements): `npm audit signatures` verifies that it was built
+from this repository.
+
+```js
+import { createReadStream } from 'node:fs';
+import { Auditfile, AuditfileSource, MemorySink } from '@xml-auditfile/auditfile';
+
+const sink = new MemorySink();
+const source = AuditfileSource.fromFactory(() => createReadStream('administratie.xaf'), 'administratie.xaf');
+const report = await Auditfile.read(source, sink);
+
+for (const diagnostic of report.diagnostics) {
+    console.log(String(diagnostic));
+}
+
+for (const line of sink.rows('tr_line')) {
+    console.log(`${line.getString('acc_id')} ${line.getDecimal('amnt')} ${line.getString('amnt_tp')}`);
+}
+```
+
+Rows have typed accessors (`getString`, `getDecimal`, `getInteger`, `getDate`, `getDateTime`, `getTime`, `getBoolean`) that check
+the column type and name the problem; `has()` tells whether a column exists in this version. `getDecimal` also reads an integer
+column, since a column can be integer in one version and decimal in another. In a loop over many rows, look the column up once
+(`table.findColumn('amnt')`) and pass it instead of the name.
+
+Values are read in XSD notation only: a date-time such as `03/01/2017 10:00:00` is refused (XAF-S004) rather than guessed.
+
+## What it does
+
+- **Determines the version**: forced in code, official namespace or alias from the registry, optionally
+  derived from the namespace (`useResolver`). Anything else stops with a clear diagnostic.
+- **Reads in two phases**: scan (validate against the built-in XSD, count rows per table) and load
+  (stream rows in batches to a sink). Verified mode loads only a valid file.
+- **Turns every repeating element into a table** following the manifest generated by auditfile-spec.
+  Rows know their id, parent, position and source part; values are typed.
+- **Checks** required and expected tables, keys, references and the XAF business rules
+  (balanced transactions, header counts and totals).
+- **Reads split audit files** (`audit.xaf`, `audit-2.xaf`, ...) as one file; you pass the parts in order.
+- **Reports** everything as diagnostics with stable codes, in Dutch or English.
+
+## Entry points
+
+| Call | Use |
+| ---- | --- |
+| `await Auditfile.read(source, sink, options)` | Read into a sink: `MemorySink` or your own sink |
+| `await Auditfile.validate(source, options)` | Validate without storing anything; `mode: 'unverified'` skips the XSD |
+| `await Auditfile.scan(source, options)` | Version, XSD validation and row counts only |
+| `(await Auditfile.open(source, options)).readRows()` | Stream rows yourself (`for await`); the rows can be iterated once |
+| `AuditfileVersion.Financial.V3_2` | Manifest, XSD, definitions, dialects and views of a version |
+| `schema.toJson()` / `AuditfileSchema.fromJson()` | Store and restore the schema of an import |
+
+Sources: the reader never opens files; you supply the streams. A stream is a Node `Readable`, a web
+`ReadableStream`, a `Blob`, a `Uint8Array`/`ArrayBuffer`, or any (async) iterable of `Uint8Array` chunks.
+
+| Call | Use |
+| ---- | --- |
+| `AuditfileSource.fromFactory(open, name)` | Fresh stream per call: can be read twice (scan, then load) |
+| `AuditfileSource.fromFactories([name, open], ...)` | Same, for the parts of a split audit file |
+| `AuditfileSource.fromStream(stream, name)` | Read once; validation then happens during loading. The stream is not destroyed |
+| `AuditfileSource.fromStreams([name, stream], ...)` | Same, for the parts of a split audit file |
+
+Options are a plain object: `version` (an `AuditfileVersion` or `"xaf/3.2"`), `mode` (`'verified'` or
+`'unverified'`), `useResolver`, `xsd`, `applyDialects`, `batchSize`, `language` (`'nl'` or `'en'`),
+`maxDiagnostics`, `maxDepth`, `maxCharactersInDocument`, `maxValueLength`, `onProgress` and `signal` (an `AbortSignal`,
+checked in the scan phase as well as the load phase). Unknown names and values out of range are refused.
+When a sink fails and its `abort` fails too, the read rejects with an `AggregateError` holding both errors.
+
+A sink is any object with `begin(context)`, `write(table, rows)`, `complete(report)` and `abort(report)`;
+each may return a promise. Set `capabilities = SinkCapabilities.NeedsRowCounts` to get row counts before the first row.
+
+## Values
+
+| Column type | JavaScript value |
+| ----------- | ---------------- |
+| `string` | `string` |
+| `decimal` | `Decimal`: exact, with the scale as written (`'100.00'`); never a floating-point number |
+| `integer` | `number`; values outside the safe integer range are reported (XAF-S004), never rounded |
+| `date` | `Date` at midnight UTC; a time zone in the file is ignored |
+| `datetime` | `Date`; a value without time zone is taken as UTC |
+| `time` | `string` `"HH:MM:SS"` |
+| `boolean` | `boolean` |
+
+## Security
+
+The reader is built for files from untrusted sources:
+
+- DTDs are refused, so there is no entity expansion and nothing is fetched (XXE, billion laughs).
+- XSD imports resolve only to the definitions embedded in the package; never to disk or network.
+- Nesting deeper than `maxDepth` (64) stops reading; the root element must appear within the first megabyte.
+- Memory grows with the number of keys (accounts, customers and suppliers, ...), not with the number of lines:
+  only open elements, key values, unresolved references (at most 100,000 per reference, XAF-R017 beyond that) and
+  the totals of transactions being read are kept, and the diagnostics list is capped at `maxDiagnostics`.
+- Text from the file is never interpreted: messages are filled without replacement patterns,
+  and lookups use `Map`, not plain objects.
+- A stream you pass with `fromStream` is never destroyed; streams from a factory are closed when reading stops.
+
+## Diagnostics
+
+Every finding is a diagnostic with a stable code from `diagnostics.json` of auditfile-spec. The report lists at most
+`maxDiagnostics` (default 1000), followed by XAF-X900 when more were found. A full list makes room for errors by
+leaving out infos and warnings, and fatal diagnostics are always included. `isValid`, `hasErrors`, `hasFatal` and
+`count(severity)` count every diagnostic, also the ones left out; `isTruncated` says whether some were.
+
+| Layer | Codes this reader reports |
+| ----- | ------------------------- |
+| XML | X001–X004 (X004 also for a part of a split file in another encoding than the first part), X900 |
+| Version | V001–V006 |
+| Structure | S001–S005, S008; S006 in unverified mode (in verified mode the XSD reports a missing field as D001) |
+| XSD | D001, D002 |
+| Rules | R001–R004, R017 |
+| Dialect | C001–C003, when a dialect applies |
+| Views | Q001, Q002 |
+
+Defined in the spec but not checked yet: S007 and S009 (in verified mode the XSD reports too many occurrences and
+values outside a code list as D001), R005–R016 (ascending numbers, periods, eleven test, IBAN, personal data),
+X005 (the XML parser reports an invalid character as X001) and E001–E004 (envelopes).
+
+## XSD validation
+
+Validation uses a streaming validator for the XSD subset that auditfile-spec uses: global and local elements,
+sequences with occurrence bounds, attributes, simple types with facets (enumeration, pattern, length, digits, ranges,
+white space) and `key`/`keyref`/`unique`. Every XSD of the registry compiles; a custom XSD (`xsd` option) that uses
+anything else (such as `xs:choice` or `xs:any`) is refused when it is compiled, never validated halfway.
+Like the .NET reader, identity constraints follow XPath 1.0: an unprefixed step selects elements without namespace.
+
+## Platforms
+
+Node 20 or later. The library itself uses no file system and no Node built-ins (SHA-256 uses Node's implementation
+when present, its own otherwise), so it also runs in the browser through a bundler. Its one dependency is
+[saxes](https://github.com/lddubeau/saxes), a strict, well-formedness-checking XML parser.
+
+## Layout
+
+| Path | Contents |
+| ---- | -------- |
+| `src/` | The reader; `src/memory/` holds `MemorySink` (also exported as `@xml-auditfile/auditfile/memory`) |
+| `src/xsd/` | The streaming XSD validator |
+| `test/` | Tests, using the XAF 3.2 sample in `test/data/xaf-3.2-sample.xaf` (two intended findings: XAF-R001, XAF-R003) |
+| `spec.lock.json` | The pinned auditfile-spec release |
+| `tools/` | `fetch-spec.ps1` (copies `generated/` of the pinned spec into `spec/generated/`) and `embed-spec.mjs` |
+
+Example programs live in [auditfile-js-samples](https://github.com/XML-auditfile/auditfile-js-samples).
+
+## Definitions
+
+Everything in `generated/` of a pinned auditfile-spec release (XSD, manifests, definitions, dialects, registry,
+diagnostics, views) is embedded in the package as `src/generated/spec.js`. The spec is not committed:
+`spec.lock.json` pins a commit, `tools/fetch-spec.ps1` copies only
+`generated/` of that commit into `spec/generated/` (git-ignored; a plain folder, not a git checkout), and
+`npm test` / `npm pack` embed it.
+
+```
+pwsh tools/fetch-spec.ps1        # after cloning and whenever spec.lock.json changes
+npm install
+npm test
+```
+
+To use a local spec checkout instead: `SPEC_ROOT=../auditfile-spec npm test`.
+
+## Workflows
+
+| Workflow | What it does |
+| -------- | ------------ |
+| `ci.yml` | Push to main and pull requests: fetch the pinned spec, install, test on Node 20, 22 and 24, pack (dry run), audit dependencies |
+| `release.yml` | Manual, with a version such as `1.0.1`. From `main` the version must be higher than every release; from `release/X.Y` (maintenance of an older line) it must be in line X.Y and higher than the latest release in that line. Then it fetches the pinned spec, tests, packs, creates the tag and GitHub release, and publishes to npm through Trusted Publishing when the `NPM_PUBLISH` variable is `true` (environment `npm`). Dist-tags: `latest` for the highest stable release, `next` for a pre-release, `release-X.Y` for maintenance |
+| `dependabot.yml` | Weekly updates of npm packages and GitHub Actions |
+
+## License
+
+Apache License 2.0.

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@xml-auditfile/auditfile",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2-alpha.1",
+  "description": "Streaming reader for Dutch tax audit files (XAF and related), following auditfile-spec.",
+  "keywords": [
+    "xaf",
+    "auditfile",
+    "auditfile-financieel",
+    "xml-auditfile",
+    "belastingdienst",
+    "audit",
+    "accounting",
+    "xml"
+  ],
+  "license": "Apache-2.0",
+  "author": "XML-auditfile",
+  "homepage": "https://github.com/XML-auditfile/auditfile-js#readme",
+  "bugs": {
+    "url": "https://github.com/XML-auditfile/auditfile-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/XML-auditfile/auditfile-js.git"
+  },
+  "type": "module",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./memory": {
+      "types": "./types/memory/memory-sink.d.ts",
+      "default": "./src/memory/memory-sink.js"
+    }
+  },
+  "files": [
+    "src/",
+    "types/",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "spec": "node tools/embed-spec.mjs",
+    "types": "tsc -p tsconfig.types.json",
+    "pretest": "node tools/embed-spec.mjs",
+    "test": "node --test",
+    "prepack": "node tools/embed-spec.mjs && tsc -p tsconfig.types.json"
+  },
+  "dependencies": {
+    "saxes": "6.0.0"
+  },
+  "devDependencies": {
+    "typescript": "7.0.2"
+  }
+}

package/src/auditfile.js

@@ -0,0 +1,186 @@
+import { normalizeOptions, ReadProgress } from './reading/read-options.js';
+import { ReadSession } from './reading/read-session.js';
+import { AuditfileSource } from './reading/source.js';
+import { checkSink, ImportContext, NULL_SINK, SinkCapabilities } from './sinks/sink.js';
+
+function checkSource(source) {
+    if (!(source instanceof AuditfileSource)) {
+        throw new TypeError('source must be an AuditfileSource.');
+    }
+
+    return source;
+}
+
+/**
+ * Entry point. Read an audit file into a sink, validate it, scan it, or stream its rows yourself.
+ * @example
+ * const sink = new MemorySink();
+ * const report = await Auditfile.read(AuditfileSource.fromFactory(() => fs.createReadStream('admin.xaf'), 'admin.xaf'), sink);
+ */
+export class Auditfile {
+    /**
+     * Reads an audit file into a sink. Verified mode (default) validates against the XSD first and loads only a valid file.
+     * @param {AuditfileSource} source
+     * @param {import('./sinks/sink.js').Sink} sink
+     * @param {import('./reading/read-options.js').ReadOptions} [options]
+     * @returns {Promise<import('./diagnostics/report.js').AuditfileReport>}
+     */
+    static async read(source, sink, options = undefined) {
+        checkSource(source);
+        checkSink(sink);
+        const settings = normalizeOptions(options);
+
+        const session = new ReadSession(source, settings);
+        if (!await session.prepare(((sink.capabilities ?? 0) & SinkCapabilities.NeedsRowCounts) !== 0)) {
+            await session.dispose();
+            return session.createReport(false);
+        }
+
+        const schema = session.schema;
+        const batches = new Map();
+        const total = schema.hasRowCounts ? schema.tables.reduce((sum, t) => sum + (t.rowCount ?? 0), 0) : null;
+        let rows = 0;
+
+        try {
+            settings.signal?.throwIfAborted();
+            await sink.begin(new ImportContext(schema, session.parts));
+            for await (const row of session.load()) {
+                let batch = batches.get(row.table);
+                if (batch === undefined) {
+                    batch = [];
+                    batches.set(row.table, batch);
+                }
+
+                batch.push(row);
+                rows++;
+                if (batch.length >= settings.batchSize) {
+                    settings.signal?.throwIfAborted();
+                    batches.set(row.table, []);
+                    await sink.write(row.table, batch);
+                    settings.onProgress?.(new ReadProgress(rows, total));
+                }
+            }
+
+            for (const [table, batch] of [...batches].sort(([a], [b]) => a.index - b.index)) {
+                if (batch.length > 0) {
+                    await sink.write(table, batch);
+                }
+            }
+
+            settings.onProgress?.(new ReadProgress(rows, total));
+        } catch (error) {
+            await session.dispose();
+            try {
+                await sink.abort(session.createReport(false));
+            } catch (abortError) {
+                // A failing rollback must not hide why the import failed: the caller gets both.
+                throw new AggregateError([error, abortError], 'The import failed, and aborting the sink failed too.');
+            }
+
+            throw error;
+        }
+
+        const failed = session.diagnostics.hasFatal || (session.validateDuringLoad && session.diagnostics.hasErrors);
+        const report = session.createReport(!failed);
+        if (failed) {
+            await sink.abort(report);
+        } else {
+            await sink.complete(report);
+        }
+
+        return report;
+    }
+
+    /**
+     * Validates an audit file (structure, keys, business rules) without storing anything.
+     * In verified mode (the default) the XSD is checked first and the rest only for a valid file;
+     * unverified mode skips the XSD and checks everything else, which is faster but reports fewer deviations
+     * (e.g. XAF-S004 instead of XAF-D001 for an invalid value).
+     * @param {AuditfileSource} source
+     * @param {import('./reading/read-options.js').ReadOptions} [options]
+     */
+    static validate(source, options = undefined) {
+        return Auditfile.read(source, NULL_SINK, options);
+    }
+
+    /**
+     * The scan phase only: determines the version, validates against the XSD in verified mode,
+     * and counts rows per table. The report's schema contains the row counts.
+     * @param {AuditfileSource} source
+     * @param {import('./reading/read-options.js').ReadOptions} [options]
+     */
+    static async scan(source, options = undefined) {
+        const session = new ReadSession(checkSource(source), normalizeOptions(options));
+        await session.prepare(true, true);
+        await session.dispose();
+        return session.createReport(false);
+    }
+
+    /**
+     * Opens an audit file for reading rows yourself, without a sink.
+     * @param {AuditfileSource} source
+     * @param {import('./reading/read-options.js').ReadOptions} [options]
+     */
+    static async open(source, options = undefined) {
+        const session = new ReadSession(checkSource(source), normalizeOptions(options));
+        const ready = await session.prepare(false);
+        if (!ready) {
+            await session.dispose();
+        }
+
+        return new AuditfileReader(session, ready);
+    }
+}
+
+/** Reads rows one by one. Check {@link AuditfileReader#schema} for null before reading: null means the file cannot be read. */
+export class AuditfileReader {
+    #session;
+    #ready;
+    #started = false;
+    #report = null;
+
+    /** @internal */
+    constructor(session, ready) {
+        this.#session = session;
+        this.#ready = ready;
+    }
+
+    /** @type {import('./schema/schema.js').AuditfileSchema | null} The import schema, or null when the file cannot be read (see {@link AuditfileReader#report}). */
+    get schema() {
+        return this.#ready ? this.#session.schema : null;
+    }
+
+    /**
+     * Rows in document order; a row is returned when its element closes. The rows are read while you iterate,
+     * and can be iterated only once: collect them in an array when you need them twice.
+     * @returns {AsyncGenerator<import('./reading/row.js').AuditfileRow>}
+     * @throws {Error} The rows are iterated a second time.
+     */
+    async *readRows() {
+        if (this.#started) {
+            throw new Error('The rows of an audit file can be iterated only once; collect them in an array to use them twice.');
+        }
+
+        this.#started = true;
+        if (this.#ready) {
+            yield* this.#session.load();
+        }
+    }
+
+    /**
+     * The report; complete after {@link AuditfileReader#readRows} has been iterated to the end. Until then every call gives
+     * the report so far; the complete report is made once and kept.
+     */
+    get report() {
+        if (this.#report !== null) {
+            return this.#report;
+        }
+
+        const report = this.#session.createReport(false);
+        if (!this.#ready || this.#session.loaded) {
+            this.#report = report;
+        }
+
+        return report;
+    }
+}