@factoidal/core 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,387 @@
 # Changelog
 
+## 0.12.0 — 2026-10-22
+
+One error model for the whole package
+(https://github.com/danbri/factoidal/issues/882 item 4,
+https://github.com/danbri/factoidal/issues/901 KR 3.1). Every op error
+envelope of the engine carries a stable `code`, the input `position` where
+the input defines one, and the `spec` section where one applies; the engine
+decides all three (`formal/lean4/Wasm/Ops/ErrorModel.lean`). The package
+copies them into one class, `FactoidalError`. The README "Errors" table is
+generated from the engine's list.
+
+### Breaking changes
+
+- `DatasetHandle`, the name of `Dataset` before 0.10.0, is removed. Use
+  `Dataset`.
+
+- `ParseError` is removed. Every function rejects with `FactoidalError`
+  (`code`, `position`, `spec`, `cause`); a parse error has
+  `code: 'parse.syntax'` (or `parse.rdf12-required`, `term.invalid-iri`,
+  `term.invalid-langtag`) and `err.position.{line, column, offset}` in place
+  of `err.line`, `err.column`, `err.offset`. `position.byteOffset` is new.
+- Error messages are the engine's text, with no `<function>: l4factoidal:`
+  prefix. A parse with an inferred format no longer appends "(format inferred
+  as ...)" to the message; `err.formatInferred` and `err.format` say it.
+- An unknown option key, an unknown format name, an `entail`, `output`,
+  `version`, `owlClosure` mode, `rmlMap` source kind or `Dataset.closure`
+  regime outside the engine's tables, and options that cannot be combined
+  were a `TypeError`; each is now a `FactoidalError` (`option.unknown`,
+  `format.unknown`, `option.invalid-value`, `regime.refused`,
+  `option.conflict`) decided by the new engine op `apiCheck`. A `TypeError`
+  stays only for an argument of the wrong JavaScript type.
+- A method of a disposed `Dataset` was a `TypeError`; it is now the engine's
+  `FactoidalError` with code `handle.disposed`. A closed `Store` is the same.
+- `queryRaw` rejected with an `Error` whose message began "SPARQL query
+  failed:" and which had `stderr`; it now rejects with the engine's
+  `FactoidalError` (`query.syntax` with a position, or `query.failed`).
+- File-system and IndexedDB failures (`openStore`, the delta log) are
+  `FactoidalError` with code `host.io` and the original error as `cause`.
+- `@factoidal/core/fn` `entail()` with an `x-ikl-*` regime rejects with code
+  `regime.refused` and the message names `query`, the function that refuses.
+
+Linked Web Storage kept in files, stage 1 (https://github.com/danbri/factoidal/issues/918;
+design record `docs/designissues/2026-10-22-lws-storage-on-disk.md`), decided in
+Lean (`L4Factoidal/LWS/Journal.lean`, `FileLayout.lean`):
+
+- `factoidal lws-serve DIR --storage files` (config member `storage: "files"`,
+  `listen({ storage: 'files' })`; the default stays `snapshot`): DIR holds one
+  file per resource body under `bodies/`, a journal `lws-journal` with one
+  record per change, and a metadata file `lws-files.json` that the journal is
+  folded into when it passes max(1 MiB, the size of the metadata file). A
+  write no longer rewrites the whole storage: a PUT into a storage of 1,000,
+  2,000 and 4,000 resources took 2.70, 2.40 and 2.89 ms, against 42.6, 83.9 and
+  170.4 ms with the snapshot (`tests/lws/scaling.mjs`, rows "storage").
+- A journal record is valid only when it is complete and its SHA-256 matches;
+  a torn last record is ignored at start (theorem `decodeFrames_torn`).
+  Replaying the records of a sequence of steps gives the metadata of the store
+  after them (`replay_records`, `persist_replay`).
+- With `FACTOIDAL_LWS_KEY` every body file and journal record is sealed with
+  ChaCha20-Poly1305 (HACL*), the file's own name in the associated data, and
+  `lws-files.json` as the snapshot is.
+- An existing `lws-state.json` is migrated at the first start in files mode and
+  renamed to `lws-state.json.migrated`.
+- New ops `lwsLoad` and `lwsPersist` (byte-region entry only): the engine names
+  the files to read and gives every file operation and byte; the host
+  (`lws/persist.mjs`) performs them. `tools/lws-touchstone.sh --storage files`.
+- Stage 1 still holds the whole storage in memory; stage 2 (bodies read on GET,
+  the metadata in an on-disk index) is an expected failure in
+  `tests/lws/scaling.mjs` naming issue 918.
+
+Linked Web Storage Search and Type Index Services (`lws10-index`, w3c/lws-protocol
+`9a08ff65`; https://github.com/danbri/factoidal/issues/912), decided in Lean
+(`L4Factoidal/LWS/TypeIndex.lean`, `Search.lean`):
+
+- The storage description advertises a `TypeIndexService`
+  (`GET /.well-known/lws-type-index`, a paged `TypeIndex`) and a
+  `TypeSearchService` (`QUERY /.well-known/lws-type-search` with an
+  `application/lws-query+json` filter in conjunctive normal form over `type`
+  and indexed relations such as `describedby`; a paged ContainerPage).
+  Option `typeIndex: false` of `listen`/`openLwsStorage` turns both off.
+- Types come from the native class, from `Link: <T>; rel="type"` on POST and
+  on `Prefer: set-linkset` PUT and PATCH, and from `rdf:type` in Turtle
+  content up to 1 MiB. Such a `type` link was refused with 409 before; it is
+  now a declared type and appears in the linkset document. A `type` link
+  that names an LWS or LDP class is still refused with 409. A PUT or PATCH
+  that applies `Prefer: set-linkset` answers `Preference-Applied: set-linkset`.
+- The index is kept by the store on every write and rebuilt in one pass when
+  a snapshot is opened. Answers, `totalItems` and the type index hold only
+  what the requesting agent may read now. Theorems `ixSearch_eq_specSearch`
+  and `searchAnswer_authorized`.
+
+Linked Web Storage Access Requests and Grants (LWS core §Access Requests
+and Grants, w3c/lws-protocol `9a08ff65`;
+https://github.com/danbri/factoidal/issues/913), decided in Lean
+(`L4Factoidal/LWS/AccessPolicy.lean`, `AccessGrants.lean`):
+
+- The storage description advertises an `AccessRequestService`
+  (`/.well-known/lws-access-requests/`) and an `AccessGrantService`
+  (`/.well-known/lws-access-grants/`), each with `conformsTo`
+  `https://www.w3.org/ns/lws#AccessProfile`. Both endpoints are LWS
+  containers: GET lists (paged), POST of an `application/lws+json` document
+  answers 201 with `Location`, GET and DELETE act on one member. Option
+  `accessGrants: false` of `listen`/`openLwsStorage` turns both off.
+- Any authenticated agent creates an access request; only the storage
+  controller (`acl:Control` on the storage root) creates or revokes a grant.
+  A document without `type`, `storage` (this storage), `access`, a policy
+  `type` with `AccessPolicy`, `action` (`read`, `modify`, `create`,
+  `delete`), `assignee`, or with a bad `inbox`, `target` or constraint,
+  answers 400.
+- A grant is part of the access policy beside Web Access Control: it permits
+  exactly its actions on exactly its targets (a container grant does not
+  reach the members) to its assignee (`foaf:Agent` for the public), when
+  every constraint holds: `dateTime` (`eq`, `gt`, `gteq`, `lt`, `lteq`),
+  `format` and `type` of the resource, `client` (the token's `client_id`)
+  with `eq` or `isAnyOf`; `purpose` is accepted and no request satisfies it.
+  A move needs `delete` of the resource and `create` in the destination.
+  Notification subscriptions and deliveries, and the type index answers,
+  see the same access. Theorems `grantsPermit_sound`,
+  `policyPermits_excluded`, `recordPermits_expired`, `grantsPermit_revoke`,
+  `grantAllows_acl`.
+- A new grant is announced (one `Create` notification) to its `inbox` and
+  to the inbox of each access request naming one of its assignees. Grants
+  and requests are kept in the storage snapshot (member `access`).
+- The storage controller hears of a new access request
+  (https://github.com/danbri/factoidal/issues/920). Core §Access Requests and
+  Grants: "When a new access request is submitted, the storage controller
+  SHOULD be notified." The draft names no inbox for the controller, so this
+  server's is configuration: `listen({ controllerInbox: URL })` or
+  `factoidal lws-serve --controller-inbox URL`. When it is set, each new
+  access request gives one `Create` notification there (signed, retried, as
+  every delivery); when it is not set, nothing is sent. An inbox that is not
+  `http` or `https` stops the start.
+
+Linked Web Storage moves and notifications, three more rules
+(w3c/lws-protocol `9a08ff65`), decided in Lean:
+
+- 301 at the previous identifiers of a moved resource
+  (https://github.com/danbri/factoidal/issues/914;
+  `L4Factoidal/LWS/MoveRedirect.lean`). §Moving Resources: "Such a server
+  SHOULD respond to subsequent requests on the previous identifiers of the
+  resource and of its auxiliary resources with 301 Moved Permanently,
+  including a `Location` header field pointing at the new identifier." After
+  a move, a request to the old path of the resource, of each descendant of a
+  moved container, of its `.acl` and `.meta` and of its `?linkset` answers
+  301 with the new IRI, when the same request at the new path would be
+  authorized (§Privacy Considerations, "Redirects": "Servers SHOULD apply the
+  same access control to such responses as to the moved resource itself");
+  otherwise the old path answers as before. A chain of moves answers the
+  current path. The table holds at most `redirectsMax` pairs (default 256,
+  `lws-serve --redirects-max N`), is kept in the snapshot (member `moved`),
+  and loses a pair when a new resource is created at its old path or the
+  moved resource is deleted. Theorems `redirect_current`, `after_ok`,
+  `redirect_after_move`.
+- A webhook inbox that names this server under another host name, an IP
+  address or `localhost`, at its port, is refused with 400
+  (https://github.com/danbri/factoidal/issues/915;
+  `L4Factoidal/LWS/InboxGuard.lean`). The engine compares the inbox
+  authority with the base IRI, the bound address and the interface
+  addresses; for a host name it answers `lwsStep` with `resolve: {host}`, the
+  host resolves the name and steps the request again with `resolved`. The
+  host passes `listen: {address, port, addresses}` to `lwsOpen`.
+- A delivery rate limit per subscription (issue 915; the webhook suite:
+  "Rate limiting and endpoint verification are suggested to prevent abuse of
+  the subscription mechanism"): at most `deliveryLimit` deliveries (default
+  10) in a window of `deliveryWindow` seconds (default 60;
+  `lws-serve --delivery-limit N --delivery-window S`; `deliveryLimit: 0`
+  turns it off). The activities over the limit wait and go, when the window
+  ends, in one envelope with an `activity` array (core §Batching
+  Notifications). An answer may carry `wake: SECONDS`; the host then calls
+  the new op `lwsFlush`. Theorem `admits_le`: at most `deliveryLimit`
+  deliveries per subscription in one window. Endpoint verification: the
+  drafts define no procedure (no request, no challenge, no expected answer),
+  so there is no behaviour to implement.
+
+Linked Web Storage, three rules of the editor's draft (w3c/lws-protocol
+`9a08ff65`, 2026-10-19), all decided in Lean:
+
+- Container pagination (§LWS Media Type, Pagination;
+  https://github.com/danbri/factoidal/issues/887). A container with more
+  than `pageSize` members (option of `listen`/`openLwsStorage`, default 100,
+  0 turns it off) answers in pages: `Link` relations `first`, `last`, `next`
+  (not on the last page) and `prev` (not on the first page), page URIs
+  `CONTAINER?page=N`, `totalItems` over the full membership, one `ETag` per
+  page. Members are listed in increasing path order, each once (theorem
+  `pageItems_concat`).
+- Client-managed links (§Metadata, §Update Resource;
+  https://github.com/danbri/factoidal/issues/888): `Link` with
+  `Prefer: set-linkset` on PUT (replace) and PATCH (add), `Link` on POST, and
+  JSON Patch or PUT of `application/linkset+json` on `PATH?linkset`.
+  Server-managed relations (`linkset`, `type`, `format`, `size`, `modified`,
+  `up`, `items`, `lws#storage`) answer 409; a malformed link answers 400.
+  Client links are kept in the storage snapshot.
+- Notifications (§Notifications and the webhook notification suite
+  `lws10-notifications-webhook`;
+  https://github.com/danbri/factoidal/issues/890). The storage description
+  advertises a `NotificationService` (`subscriptionType`
+  `["WebhookSubscription"]`, endpoint `/.well-known/lws-subscriptions/`) and
+  an Ed25519 `JsonWebKey` verification method. An authenticated POST of a
+  `WebhookSubscription` (`topic`, `inbox`, optional `expires`) answers 201;
+  each topic must be readable by the agent (403 otherwise). Every successful
+  write gives Activity Streams 2.0 `Create` (with `target`), `Update` or
+  `Delete` (with `origin`) activities, sent only to subscribers who may read
+  the resource at that time, as an `application/lws+json` POST to the inbox,
+  signed with HTTP Message Signatures (RFC 9421) and `Content-Digest`
+  (RFC 9530). The endpoint lists the agent's subscriptions; GET and DELETE
+  manage one. A delivery answered 5xx, 408, 425, 429 or not at all is tried
+  up to three times; 410 or three failed deliveries deactivate the
+  subscription. Subscriptions and the signing key are kept in the storage
+  snapshot. The host makes the requests the engine names and reports each
+  status to the new op `lwsDelivered`; `listen`/`openLwsStorage` take
+  `notifications: false` to turn it off.
+- Moving resources (§Moving Resources;
+  https://github.com/danbri/factoidal/issues/914). The storage description
+  describes a `MoveResource` capability (`appliesTo` DataResource and
+  Container, `preservesIdentifier` false). A JSON Patch (or PUT) of a
+  resource's linkset that changes its `up` link moves it to that container,
+  with its descendants when it is a container, in one step: the answer is
+  200 with the new linkset and `Content-Location`, both containers get a new
+  ETag, and a subscriber hears one `Move` activity (`origin`, `target`). A
+  destination that is missing or not a container, a cycle, the storage
+  root, a name already taken, another storage or a removed `up` link is
+  409. The agent needs the delete of every moved resource and the create in
+  the destination. `listen`/`openLwsStorage` take `moves: false` to turn it
+  off. Theorem `move_tree`: a move keeps the containment hierarchy a tree.
+- Three server options, each off by default and decided in Lean
+  configuration, so that every Touchstone test that one of our
+  configurations can satisfy runs (`tools/lws-touchstone.sh --config all`):
+  `lws-serve --moves all|data|off` (`moves: "data"` describes `appliesTo`
+  `[DataResource]` and answers a change of a container's `up` link with 409;
+  `"off"` describes no `MoveResource`), `--no-linkset-put` (`linksetPut:
+  false`: a linkset's `Allow` leaves out PUT and a PUT answers 405 with
+  `Allow`, as lws10-core §Metadata requires when PUT is not advertised) and
+  `--paginate-always` (`paginateAlways: true`: a container listing that fits
+  on one page is still one paginated page, with `rel="first"` and
+  `rel="last"` and no `rel="next"` or `rel="prev"`). An unknown `moves`
+  value stops the start.
+- Fixed: on a paginated container, `If-Match` with the `ETag` of its first
+  page (which a GET of the container URI answers) failed with 412; the
+  first page's tags are now current tags of the container.
+
+Encryption at rest of the LWS and Solid storage snapshot, off by default
+(https://github.com/danbri/factoidal/issues/921; owner, 2026-10-21: "Yes env
+var please. Again off by default but good to show we can."):
+
+- When the environment variable `FACTOIDAL_LWS_KEY` holds a 32-byte key (64
+  hex digits or base64url), `lws-serve` and `solid-serve` write
+  `DIR/lws-state.json` as format `lws-snapshot-sealed-1`: format id, cipher
+  id `chacha20-poly1305`, key id (first 8 bytes of SHA-256 of the key), a
+  12-byte nonce new for every write, and the ChaCha20-Poly1305 (RFC 8439,
+  HACL*) ciphertext of the snapshot, with the header as associated data.
+  `listen`/`openLwsStorage`/`openSolidStorage` take `storageKey` (text, or
+  `null` to read no key).
+- At start the file is authenticated before use. A wrong key, a changed or
+  truncated file, a clear-text file with the variable set and a sealed file
+  without it each stop the start with a one-line message (exit 1). With the
+  variable unset, behaviour is unchanged.
+- It protects the file on disk only: not the memory of a running server, not
+  the key in its environment, not the answers to clients.
+- Decided in Lean (`L4Factoidal/LWS/SnapshotSeal.lean`), with theorems over
+  any AEAD with RFC 8439 correctness (`unsealDoc_sealDoc`,
+  `unsealDoc_authenticated`, `unsealDoc_wrongKey`, ...). `lwsSnapshot` and
+  `solidSnapshot` take an optional second argument `{"nonce":…}`.
+- Cost with a key (2026-10-21, about 1,050 resources): a write takes about
+  2.7 times as long (133 to 143 ms against 49 to 54 ms), the file is 1.33
+  times larger, a restart about 2.1 times as long.
+
+### Breaking changes
+
+- The storage description has a second service, `NotificationService`, and
+  `verificationMethod` and `authentication` members; its `ETag` is a digest
+  of the document.
+- A container listing is in increasing path order. Before, it was in the
+  order of the store (newest write first).
+- A container with more than 100 members returns only its first 100 members
+  unless `pageSize` is set; follow `rel="next"`.
+- PUT on a linkset resource replaces the client links. Before, it answered
+  405.
+
+### Unstable
+
+- ANTICIPATORY AND UNSTABLE, off by default: a type search results resource
+  (https://github.com/danbri/factoidal/issues/922). With
+  `listen({ searchResults: true })` or `factoidal lws-serve
+  --unstable-search-results`, a QUERY answer of the Type Search Service by an
+  authenticated agent carries `Content-Location` naming
+  `/.well-known/lws-type-search/results/<id>` (RFC 10008 section 2.3).
+  lws10-index defines no such resource; its path, lifetime, snapshot member
+  and behaviour are likely to change. A GET by the same agent and client lists
+  the QUERY's results that a new QUERY would still answer (paged, filtered by
+  current read access); anyone else gets 404; after `searchResultsTtl`
+  (600 s) 410. The storage description marks it with the extension member
+  `https://github.com/danbri/factoidal/issues/922#unstableResultsResource`.
+  `lwsStep` request documents may carry `random` (16 bytes, base64); the LWS
+  host sends it with every request. Decided in Lean
+  (`L4Factoidal/LWS/SearchResults.lean`).
+- Off by default: Merkle hashes of the LWS storage
+  (https://github.com/danbri/factoidal/issues/919; owner, 2026-10-21: "As an
+  optional, probably default off until we settle on stronger motivating
+  usecase but good to have the fundamentals there"). With
+  `listen({ merkle: true })` or `factoidal lws-serve --merkle`: a GET or HEAD
+  of a resource carries `Repr-Digest: sha-256=:<base64>:` (RFC 9530, SHA-256
+  of the stored bytes, HACL*); a container listing carries
+  `Factoidal-Merkle-Root` and the member
+  `https://github.com/danbri/factoidal/issues/919#merkleRoot` (a Merkle digest
+  over its members and their digests); the storage description carries
+  `https://github.com/danbri/factoidal/issues/919#storageMerkleRoot`. Under
+  authorization the roots go to the storage controller only. Entity tags do
+  not change. The hashes are kept by the store on every write, delete and
+  move (only the containers above the change are recomputed) and rebuilt when
+  a storage is opened; no hash is in the snapshot. Decided in Lean
+  (`L4Factoidal/LWS/Merkle.lean`, `MerkleHttp.lean`), with theorems
+  `MkState.dig_eq_recompute` (the kept digests equal a recomputation from the
+  store) and `change_reaches_ancestor` (a change reaches every container
+  above it, with collision-freedom of SHA-256 as a stated hypothesis).
+  Cost (2026-10-21, wasm in Node): a write into a container of 2,000 members
+  takes about 6.3 ms with the option on against 0.9 ms off (linear in the
+  members of each container above the write); a reopen of 2,000 resources
+  with the hashes rebuilt takes 246 ms.
+
+### Performance
+
+- LWS and Solid PUT and GET of a large body
+  (https://github.com/danbri/factoidal/issues/903): one 100,000-triple
+  N-Triples body (7.7 MB) took about 17 s to PUT and the GET stopped the
+  engine with out of memory; now the PUT takes 85 ms and the GET 40 ms
+  (`npm run test:costs`). The cause was the FNV-1a digest of the entity tag,
+  computed in `Nat`: on wasm32 each byte made heap numbers. It now runs in
+  `UInt32` (theorem `fnv1a32_eq_spec`: same value as the `Nat` definition).
+  Peak memory of the 100,000-triple PUT and GET fell from 2,640 MiB to
+  288 MiB. Scaling check: `node tests/lws/scaling.mjs`.
+
+### Fixed
+
+Seven defects of `lws-serve` that the Touchstone LWS conformance harness found
+(https://github.com/danbri/factoidal/issues/911; record:
+`docs/designissues/2026-10-21-lws-touchstone-run.md`). All are decided in
+Lean (`formal/lean4/L4Factoidal/LWS/`):
+
+- A POST or PUT with no content and no `Content-Type` is accepted
+  (`Operations.writeMediaType`). Before, it answered 400, so the draft's own
+  container-creation example (`POST`, `Content-Length: 0`, the
+  `lws#Container` type link) failed. An empty data resource made this way
+  has type `application/octet-stream`. Content without `Content-Type` still
+  answers 400.
+- The Turtle form of a container uses `http://schema.org/size`, as the
+  `application/lws+json` context and the core draft's examples do. Before,
+  it used `https://schema.org/size`, so the two forms were not RDF
+  isomorphic. The WG's `lws10-vocab/vocabulary.yml` declares
+  `https://schema.org/`; the conflict is recorded in `Binding.containerTurtle`.
+- A container's `ETag` carries the FNV-1a digest of its listing in the
+  negotiated media type (`Binding.containerTag`). Before, it was the
+  container's clock only, and a host with a real clock sets the clock to
+  the current second, so two changes in one second gave one strong tag.
+  `Last-Modified` is unchanged.
+- The `lws#storage` link of a 401 and the default token audience are the
+  storage description IRI `<base>.well-known/lws-storage`, the IRI every
+  other response links and the description's `id` (`Authorization.storageIri`).
+  Before, both were the storage root `<base>`.
+- `If-Unmodified-Since` is evaluated for every method (412 when the resource
+  changed after the date), and `If-Modified-Since` and `If-Unmodified-Since`
+  are compared as instants in all three HTTP-date formats of RFC 9110
+  §5.6.7 (`HttpDate.parseHttpDate`; theorem `unixOfCivil_civilOfUnix`).
+  Before, `If-Unmodified-Since` was ignored and `If-Modified-Since` matched
+  only the exact `Last-Modified` text.
+- A POST names its new resource with the first free name of the hint (or
+  `res<clock>`), `-1`, `-2`, ... (`Operations.childPathFor`, theorem
+  `childPathFor_fresh`). Before, a clash got the clock as its one suffix,
+  and under a real clock the third POST to one container in one second
+  REPLACED the second resource.
+- The Turtle form of a container gives a contained container no
+  `dcterms:modified`: the `application/lws+json` context defines
+  `modified` for a DataResource only, so the JSON item's `modified` of a
+  container is no triple, and the two forms must be RDF isomorphic.
+- `factoidal lws-serve --page-size N` passes `N` to the engine's
+  `pageSize`.
+- Result: Touchstone (221 tests) runs with no failure, open 70 pass, 0
+  fail, 151 inapplicable; with authorization 146 pass, 0 fail, 75
+  inapplicable.
+
+Breaking: an LWS access token must name the storage description IRI in
+`aud` (or the `--audience` given). A token for the storage root IRI is now
+refused with 401 `invalid_token`.
+
 ## 0.11.0 — 2026-10-21
 
 No RDF, SPARQL, datatype or IRI decision is made in JavaScript any more

package/README.md

@@ -70,6 +70,62 @@ Formats (generated from `formats()`):
 <!-- formats-table:end -->
 
 Missing writers (HDT, N3, RDFa): https://github.com/danbri/factoidal/issues/883.
+
+## Errors
+
+Every function rejects with one class, `FactoidalError`, except that an
+argument of the wrong JavaScript type is a `TypeError`. The engine decides
+three fields: `code` (below), `position` (`{line, column, offset,
+byteOffset}` where the input defines one: `offset` is a UTF-16 index into
+your string, `byteOffset` counts UTF-8 bytes) and `spec` (the specification
+section of the condition). `cause` holds the underlying error of `host.io`.
+
+```js
+import { parse, FactoidalError } from '@factoidal/core';
+try { await parse('<http://e/a> <http://e/p> .', 'turtle'); }
+catch (e) { if (e instanceof FactoidalError) console.log(e.code, e.position.line, e.spec); }
+```
+
+Codes (generated from `engineTables().errorCodes`):
+
+<!-- errors-table:start (generated by test/errors.test.mjs) -->
+| code | specification | meaning |
+|---|---|---|
+| `parse.syntax` | <https://www.w3.org/TR/rdf12-turtle/#sec-grammar> | The input text does not match the grammar of its RDF syntax. |
+| `parse.rdf12-required` | <https://www.w3.org/TR/rdf12-concepts/#section-triple-terms> | The text uses an RDF 1.2 form (triple term, reified triple, base direction) and was read as RDF 1.1. |
+| `term.invalid-iri` | <https://www.w3.org/TR/rdf12-concepts/#section-IRIs> | A term that must be an IRI is not one. |
+| `term.invalid-langtag` | <https://www.w3.org/TR/rdf12-concepts/#section-Graph-Literal> | A language tag is not well-formed (BCP 47). |
+| `term.invalid` | <https://www.w3.org/TR/sparql11-results-json/#select-encode-terms> | A term or quad given as JSON is not an RDF term or quad. |
+| `query.syntax` | <https://www.w3.org/TR/sparql11-query/#grammar> | The SPARQL query does not match the SPARQL grammar. |
+| `query.failed` | <https://www.w3.org/TR/sparql11-query/#sparqlDefinition> | The SPARQL query parsed but its evaluation was refused. |
+| `update.syntax` | <https://www.w3.org/TR/sparql11-update/#grammar> | The SPARQL update does not match the SPARQL Update grammar. |
+| `update.failed` | <https://www.w3.org/TR/sparql11-update/#updateLanguage> | The SPARQL update parsed but was refused. |
+| `format.unknown` | - | The format name is not one the engine reads or writes. |
+| `serialize.unsupported-rdf12` | <https://www.w3.org/TR/rdf12-concepts/#section-triple-terms> | The data holds an RDF 1.2 term and the requested RDF 1.1 output has no form for it. |
+| `serialize.failed` | - | The writer refused the data. |
+| `canon.unsupported-rdf12` | <https://www.w3.org/TR/rdf-canon/#canon-algorithm> | RDFC-1.0 defines no canonical labelling for RDF 1.2 triple terms or directional strings. |
+| `canon.failed` | <https://www.w3.org/TR/rdf-canon/#canon-algorithm> | Canonicalization was refused. |
+| `owl.unsupported-rdf12` | <https://www.w3.org/TR/owl2-mapping-to-rdf/#Mapping_from_RDF_Graphs_to_the_Structural_Specification> | OWL 2 Direct Semantics has no rule for RDF 1.2 triple terms or directional strings. |
+| `reason.failed` | - | A closure or entailment check was refused. |
+| `regime.refused` | <https://www.w3.org/TR/sparql11-entailment/> | The entailment regime is not implemented. |
+| `validate.failed` | - | A validation (SHACL, ShEx, JSON Schema, Schematron) could not run on its inputs. |
+| `xml.failed` | <https://www.w3.org/TR/xml/#sec-well-formed> | An XML, XPath, XSLT, MathML or XForms input was refused. |
+| `crypto.failed` | - | A cryptographic or Verifiable Credentials operation refused its inputs. |
+| `store.failed` | - | A persisted-store, pack or HDT operation was refused. |
+| `registry.failed` | <https://www.w3.org/TR/sparql11-query/#extensionFunctions> | An extension-function or SERVICE registration was refused. |
+| `handle.unknown` | - | The handle was never issued by this engine. |
+| `handle.disposed` | - | The handle was issued and then closed. |
+| `option.unknown` | - | The options object has a key the function does not take. |
+| `option.invalid-value` | - | An option or mode argument has a value outside its table. |
+| `option.conflict` | - | Two options were given that cannot be combined. |
+| `capacity.exceeded` | - | The input is above a fixed size limit of the engine. |
+| `call.arity` | - | The op was called with the wrong number of arguments. |
+| `call.arguments` | - | The arguments document is not a JSON array of strings. |
+| `op.unknown` | - | The loaded engine has no op of this name. |
+| `op.failed` | - | Any other refusal of an op. |
+| `host.io` | - | The host could not read or write a file, a store or a log (no engine decision). |
+<!-- errors-table:end -->
+
 Full API: [API.md](https://github.com/danbri/factoidal-core/blob/main/npm/factoidal/API.md).
 Changes: [CHANGELOG.md](CHANGELOG.md).
 
@@ -97,10 +153,11 @@ Official test suites, pass / fail / total, 2026-10-09 [B] unless marked.
 | SPARQL 1.1 Query, Update, Protocol | 631 / 0 / 631 |
 | SPARQL 1.2 | 254 / 0 / 254 |
 | SPARQL Protocol, Graph Store, Service Description against `serve` | 50 / 0 / 50 [P] |
+| Linked Web Storage 1.0, Touchstone (another implementer's harness), `lws-serve` | 215 / 0 / 221 (6 not applicable) [L] |
 | RDF 1.1 N-Triples, N-Quads, Turtle, TriG, RDF/XML | 992 / 0 / 992 |
 | RDF 1.2 syntax suites | all pass |
 | RDF 1.1 Semantics | 39 / 0 / 39 |
-| RDF 1.2 Semantics | 40 / 7 / 47 |
+| RDF 1.2 Semantics | 29 / 0 / 29 [S] |
 | JSON-LD 1.1 toRdf, expand, flatten | 910 / 0 / 910 |
 | JSON-LD 1.1 compact, fromRdf | 298 / 0 / 300 (2 not run) |
 | JSON-LD 1.1 Framing | 29 / 63 / 92 |
@@ -111,7 +168,7 @@ Official test suites, pass / fail / total, 2026-10-09 [B] unless marked.
 | SHACL 1.0 Core, SHACL-SPARQL | 120 / 0 / 120 |
 | SHACL 1.2 Core | 103 / 30 / 133 |
 | ShEx 2 validation, ShExC | 1624 / 0 / 1624 |
-| CSVW | 821 / 1 / 822 |
+| CSVW | 821 / 0 / 821 (1 defective W3C test excluded) [C] |
 | RIF Core | 43 / 0 / 46 (3 undecided) |
 | RML Core | 60 / 0 / 76 (16 not attempted) |
 | XML 1.0 (xmlconf) | 1861 / 0 (516 not run) |
@@ -124,10 +181,13 @@ Official test suites, pass / fail / total, 2026-10-09 [B] unless marked.
 [B] https://github.com/danbri/factoidal-core/blob/03e2e6deee8146ce7e6fdc3f8f34b8245af5ab54/docs/designissues/2026-10-09-lean-conformance-baseline.md
 [P] https://github.com/danbri/factoidal-core/blob/9a4045f1572a032b53ccb867f8395fe0c8d97bb9/docs/designissues/2026-10-10-store-serve.md
 [X] https://github.com/danbri/factoidal-core/blob/cb871c2de8354362ae6226eb57fb6c549624ea1a/docs/designissues/2026-10-10-xml-profile-widened.md
+[L] 2026-10-22, https://github.com/danbri/factoidal-core/blob/2b9d2e39af53be31ed92463b58d3e132e65c4fe4/docs/designissues/2026-10-21-lws-touchstone-run.md (with server options, 220 of 221 pass in at least one configuration)
+[S] 2026-10-21, the current W3C manifest (29 active tests), https://github.com/danbri/factoidal-core/blob/2b9d2e39af53be31ed92463b58d3e132e65c4fe4/docs/claude-rules/current-state.md
+[C] 2026-10-21, validation test308, https://github.com/danbri/factoidal/issues/700
 
 ## Limits
 
-- Size: 2.5 MB packed, 12.4 MB unpacked; one 11.7 MB wasm module.
+- Size: 2.9 MB packed, 14.0 MB unpacked; one 13.2 MB wasm module.
 - `factoidal update` and `compact` exit 3; updates work through `serve`
   (https://github.com/danbri/factoidal/issues/641).
 - Fuseki: read-only administration API, one dataset per process, no

package/api.d.ts

@@ -42,11 +42,10 @@ export function buildApi(driver: {
 export function entryFromEngine(engine: object): Record<string, unknown>;
 
 export const Dataset: typeof import('./index').Dataset;
-export const DatasetHandle: typeof import('./index').DatasetHandle;
 export const Store: typeof import('./index').Store;
 export const dataFactory: import('./index').DataFactory;
-/** Position-carrying parse failure; see index.d.ts's ParseError. */
-export const ParseError: typeof import('./index').ParseError;
+/** The one error class; see index.d.ts's FactoidalError. */
+export const FactoidalError: typeof import('./index').FactoidalError;
 /** Package version string, e.g. '0.9.0'. */
 export const version: string;
 

package/api.mjs

@@ -18,7 +18,7 @@
 //
 // openStore() here takes a reader function only: there is no file system.
 
-import { buildApi, ParseError, DatasetHandle, Store } from './lib/api.mjs';
+import { buildApi, FactoidalError, Store } from './lib/api.mjs';
 import { entryFromEngine } from './lib/lean-entry.mjs';
 import { dataFactory } from './rdfjs.mjs';
 import { Dataset } from './lib/dataset.mjs';
@@ -52,5 +52,5 @@ export function createApi(engine, options) {
   });
 }
 
-export { buildApi, entryFromEngine, ParseError, DatasetHandle, Store, Dataset, dataFactory, version };
+export { buildApi, entryFromEngine, FactoidalError, Store, Dataset, dataFactory, version };
 export default createApi;