@dialecte/core 0.6.4 → 0.8.0

package/dist/errors/codes.d.ts

@@ -2,150 +2,605 @@ export declare const ERROR_CATALOG: {
     readonly UNKNOWN: {
         readonly code: "D0001";
         readonly message: "An unknown error occurred";
+        readonly explanation: {
+            readonly when: "A transaction's callback threw something that is not a structured error (a plain `Error`, a value); the original is its `cause`.";
+            readonly fix: "Read `cause` and `detail`; raise your own failures with `throwDialecteError` or `invariant` so callers get a key.";
+            readonly docs: "https://dialecte.github.io/core/guide/development/state-and-errors#error-catalog";
+        };
     };
     readonly ASSERTION_FAILED: {
         readonly code: "D0002";
         readonly message: "Assertion failed";
+        readonly explanation: {
+            readonly when: "An `invariant` without its own key failed, or core met a state it never expects (a catalogue built wrong, an inconsistent export, an engine running an sqlite-wasm older than 3.54.1, which removes a project on a failed install).";
+            readonly fix: "Read `detail`: it names the condition. Give `invariant` a key of its own when the failure is one a caller should handle.";
+            readonly docs: "https://dialecte.github.io/core/guide/development/state-and-errors#error-catalog";
+        };
     };
     readonly STORE_CONNECTION_FAILED: {
         readonly code: "D1001";
         readonly message: "Failed to open database";
+        readonly explanation: {
+            readonly when: "The project's database could not be opened (the SQLite file or its worker did not start), or the origin's hub could not be joined: its SharedWorker failed to start or was blocked, or a child's port went unanswered past the welcome budget (its page unbound it).";
+            readonly fix: "Check the browser supports the store (OPFS, workers, SharedWorker for the hub) and that no other tab holds the project; reload, or open the project with another storage. A child view refused so is bound again by its page (`createHubPort`, then `adoptHubPort`).";
+            readonly docs: "https://dialecte.github.io/core/api/project#store-errors";
+        };
     };
     readonly STORE_COMMIT_FAILED: {
         readonly code: "D1002";
         readonly message: "Failed to commit changes";
+        readonly explanation: {
+            readonly when: "The database refused a transaction's write as it committed (the failure is the `cause`).";
+            readonly fix: "Read `cause`; a full disk or a lost connection are the usual reasons. Retry the transaction once the store is back.";
+            readonly docs: "https://dialecte.github.io/core/api/project#store-errors";
+        };
     };
     readonly STORE_RECORD_NOT_FOUND: {
         readonly code: "D1003";
         readonly message: "Record not found in database";
+        readonly explanation: {
+            readonly when: "A write updated or deleted a record the store does not hold in that document.";
+            readonly fix: "Read the record again before writing: it was deleted, or the ref names another document.";
+            readonly docs: "https://dialecte.github.io/core/api/project#store-errors";
+        };
     };
     readonly STORE_BULK_ADD_FAILED: {
         readonly code: "D1004";
         readonly message: "Failed to add records to database";
+        readonly explanation: {
+            readonly when: "The database refused to add a batch of records (import, commit); the failure is the `cause`.";
+            readonly fix: "Read `cause`; a full disk or a closed store are the usual reasons.";
+            readonly docs: "https://dialecte.github.io/core/api/project#store-errors";
+        };
     };
     readonly STORE_BULK_UPDATE_FAILED: {
         readonly code: "D1005";
         readonly message: "Failed to update records in database";
+        readonly explanation: {
+            readonly when: "The database refused to update a batch of records; the failure is the `cause`.";
+            readonly fix: "Read `cause`; a full disk or a closed store are the usual reasons.";
+            readonly docs: "https://dialecte.github.io/core/api/project#store-errors";
+        };
     };
     readonly STORE_DELETE_FAILED: {
         readonly code: "D1006";
         readonly message: "Failed to delete records from database";
+        readonly explanation: {
+            readonly when: "The database refused to delete records; the failure is the `cause`.";
+            readonly fix: "Read `cause`; a closed store is the usual reason.";
+            readonly docs: "https://dialecte.github.io/core/api/project#store-errors";
+        };
     };
     readonly STORE_NOT_WRITABLE: {
         readonly code: "D1007";
         readonly message: "Store is not writable";
+        readonly explanation: {
+            readonly when: "A write reached an in-memory store created read-only.";
+            readonly fix: "Create the project with `storage: { type: 'inMemory', writable: true }` when the script writes.";
+            readonly docs: "https://dialecte.github.io/core/api/project#in-memory-storage";
+        };
     };
     readonly STORE_BLOB_NOT_FOUND: {
         readonly code: "D1008";
         readonly message: "Blob not found";
+        readonly explanation: {
+            readonly when: "A blob operation named a blob id the store does not hold.";
+            readonly fix: "List the blobs (`project.getBlobsByDocument`) and use an id from there.";
+            readonly docs: "https://dialecte.github.io/core/api/project#blobs";
+        };
+    };
+    readonly STORE_DUPLICATE_ID: {
+        readonly code: "D1009";
+        readonly message: "An id is already taken in the store";
+        readonly explanation: {
+            readonly when: "A write would create a record (or register a document) with an id the store already holds; `meta.recordIds` lists them.";
+            readonly fix: "Let core mint ids (omit `id`), or pick ids no record of the document has; `deepClone` mints new ids itself.";
+            readonly docs: "https://dialecte.github.io/core/api/project#store-errors";
+        };
+    };
+    readonly STORE_CLOSED: {
+        readonly code: "D1010";
+        readonly message: "Store is closed";
+        readonly explanation: {
+            readonly when: "A store operation was still in flight when its store closed, or code holding the store itself (a custom store, a test context) called it after its `close()`. A project closed with `project.close()` answers `PROJECT_NOT_OPENED` instead.";
+            readonly fix: "Await every operation before closing the store or the project; open it again before using it.";
+            readonly docs: "https://dialecte.github.io/core/api/project#lifecycle";
+        };
+    };
+    readonly STORE_READ_FAILED: {
+        readonly code: "D1011";
+        readonly message: "Failed to read from database";
+        readonly explanation: {
+            readonly when: "The SQLite store's database failed under a read; the failure is the `cause`.";
+            readonly fix: "Read `cause`; reopen the project. A lasting failure means the file is damaged: import its documents again.";
+            readonly docs: "https://dialecte.github.io/core/api/project#store-errors";
+        };
+    };
+    readonly STORE_PROTOCOL_MISMATCH: {
+        readonly code: "D1012";
+        readonly message: "Another version of the library holds the shared store connection";
+        readonly explanation: {
+            readonly when: "Another version of the library already holds the shared store connection (another tab runs an older or newer build).";
+            readonly fix: "Close the other tabs of the app, or reload them all on the same version.";
+            readonly docs: "https://dialecte.github.io/core/api/project#store-errors";
+        };
+    };
+    readonly STORE_REALM_ID_TAKEN: {
+        readonly code: "D1013";
+        readonly message: "A view with this id is already connected to the shared store";
+        readonly explanation: {
+            readonly when: "A view joined the shared store with an id another connected view already uses.";
+            readonly fix: "Give each view its own id; reload the page that reused one.";
+            readonly docs: "https://dialecte.github.io/core/api/project#store-errors";
+        };
+    };
+    readonly STORE_REALM_UNKNOWN: {
+        readonly code: "D1014";
+        readonly message: "The shared store does not know this view";
+        readonly explanation: {
+            readonly when: "A view spoke to the shared store without having joined it, or after it left.";
+            readonly fix: "Join (open the project) before reading or writing; reload a view that was disconnected.";
+            readonly docs: "https://dialecte.github.io/core/api/project#store-errors";
+        };
+    };
+    readonly STORE_VALUE_NOT_JSON: {
+        readonly code: "D1015";
+        readonly message: "A value handed to the store is not JSON";
+        readonly explanation: {
+            readonly when: "A write handed the store a value that is not plain JSON (a function, a Map, undefined, a class instance) in a record or in document metadata.";
+            readonly fix: "Pass plain strings, numbers, booleans, arrays and objects; `detail` names the value and the field.";
+            readonly docs: "https://dialecte.github.io/core/io/#values-a-store-keeps";
+        };
+    };
+    readonly STORE_UNAVAILABLE: {
+        readonly code: "D1016";
+        readonly message: "This browser gives the page no storage for a project";
+        readonly explanation: {
+            readonly when: "The browser gives the page no private file system (a private window), or a worker no synchronous file access, so the SQLite project store cannot create, open or destroy the project; nothing is changed.";
+            readonly fix: "Open the app in a normal (not private) window of a browser that supports the origin private file system.";
+            readonly docs: "https://dialecte.github.io/core/api/project#store-errors";
+        };
+    };
+    readonly STORE_QUOTA_EXCEEDED: {
+        readonly code: "D1017";
+        readonly message: "Not enough storage left for the project";
+        readonly explanation: {
+            readonly when: "The origin has too little storage left: for a new project's files, for an import (eight times the file's size and at least 1 MiB, less the project's free pages), or the file system refused a write for want of space; nothing of the call applied. The SQLite project store answers it; the local (IndexedDB) store answers the failing write's own error (`STORE_COMMIT_FAILED`, `STORE_BULK_ADD_FAILED`, `STORE_BULK_UPDATE_FAILED`; an import `IMPORT_FAILED`) until it moves to SQLite; the in-memory store has no limit.";
+            readonly fix: "Free storage for the origin (delete projects no longer needed) or import a smaller file, then try again; `meta.needed` and `meta.available` give the sizes when known.";
+            readonly docs: "https://dialecte.github.io/core/api/project#store-errors";
+        };
+    };
+    readonly STORE_ENGINE_LOST: {
+        readonly code: "D1018";
+        readonly message: "The project engine stopped answering";
+        readonly explanation: {
+            readonly when: "A call to a project engine served from a worker lost that engine: it ended with what hosted it or gave no answer within its budget (`meta.reason` `'host-gone'`), it sent nothing for too long while the call waited (`'no-heartbeat'`, it may still finish), or the hub dropped this view with the page that bound it - frozen, gone, or unbinding it (`'realm-dropped'`: every call, `getWriteOutcome` too, is refused so until the view is bound again).";
+            readonly fix: "A Document's commit and a Project's import ask the outcome themselves, once: a commit that landed resolves; otherwise the refusal says `meta.outcome` - `not-applied` (make it again if wanted), `running` (a silent engine may still apply it: tell the user, read again later), `unknown` (it could not be asked), or `applied` for an import (its document is in the project; its diagnostics were lost). Elsewhere ask `getWriteOutcome({ writeId })` with `meta.writeId` before writing again; never retry a write blindly. For `'realm-dropped'`, every call is refused until the page binds the view again once it is back (`onRejoined`, then `createHubPort`, its port handed to the view's `adoptHubPort`).";
+            readonly docs: "https://dialecte.github.io/core/api/project#store-errors";
+        };
+    };
+    readonly STORE_HUB_SPAWNERS_FIXED: {
+        readonly code: "D1019";
+        readonly message: "The page's hub connection runs another version of this dialecte's engine";
+        readonly explanation: {
+            readonly when: "`connectHub({ spawners })` named a dialecte whose engine the page's connection already runs at another version, or a project was opened (or destroyed by name) on `sqlite` from a factory of such a version (the project offers its engine to the hub as it opens): a page runs one version of each dialecte's engine (two would split a project's views between two engines). A later call adds the engines of dialectes the page does not run yet. `meta.spawners` names the dialectes (id and version) refused; nothing of the call was added, nothing opened.";
+            readonly fix: "Ship one version of each dialecte in the app: register each dialecte's `factory.spawner` from the copy the app opens its projects with.";
+            readonly docs: "https://dialecte.github.io/core/api/project#store-errors";
+        };
     };
     readonly ELEMENT_NOT_FOUND: {
         readonly code: "D2001";
         readonly message: "Element not found";
+        readonly explanation: {
+            readonly when: "A ref names an element the document does not hold (deleted, never created, or from another document).";
+            readonly fix: "Read the ref from a query in the same document (`getRecord`, `findDescendants`) instead of keeping an old one.";
+            readonly docs: "https://dialecte.github.io/core/guide/development/state-and-errors#error-catalog";
+        };
     };
     readonly ROOT_NOT_FOUND: {
         readonly code: "D2002";
         readonly message: "Root element not found";
+        readonly explanation: {
+            readonly when: "The document holds no root element of the dialecte's root tag (an empty or foreign document).";
+            readonly fix: "Import a file whose root is the dialecte's root element, or create the document with `project.initEmptyDocument`.";
+            readonly docs: "https://dialecte.github.io/core/api/project#initemptydocument";
+        };
     };
     readonly DUPLICATE_ID: {
         readonly code: "D2003";
         readonly message: "Duplicate element ID";
+        readonly explanation: {
+            readonly when: "Not raised by core itself: a dialecte or app code raises it when two elements carry the same id.";
+            readonly fix: "Give each element its own id; let core mint them.";
+            readonly docs: "https://dialecte.github.io/core/guide/development/state-and-errors#error-catalog";
+        };
     };
     readonly ELEMENT_TAGNAME_MISMATCH: {
         readonly code: "D2004";
         readonly message: "Element tagName does not match the expected type";
+        readonly explanation: {
+            readonly when: "A ref's `tagName` is not the tag of the record its id names.";
+            readonly fix: "Build refs with `toRef(record)` from a record you read, never by hand with a guessed tag.";
+            readonly docs: "https://dialecte.github.io/core/api/transaction#reforrecord";
+        };
     };
     readonly INVALID_PARENT_CHILD: {
         readonly code: "D3001";
         readonly message: "Invalid parent-child relationship";
+        readonly explanation: {
+            readonly when: "Not raised by core itself: a dialecte or app code raises it when an element is placed under a parent the schema does not admit.";
+            readonly fix: "Read the parent's children in the definition (`query.getDefinition`) and add the element under an admitted parent.";
+            readonly docs: "https://dialecte.github.io/core/api/transaction#addchild";
+        };
     };
     readonly INVALID_ATTRIBUTE: {
         readonly code: "D3002";
         readonly message: "Invalid attribute for element";
+        readonly explanation: {
+            readonly when: "Not raised by core itself: a dialecte or app code raises it for an attribute the element does not declare.";
+            readonly fix: "Use an attribute the element's definition lists.";
+            readonly docs: "https://dialecte.github.io/core/guide/development/state-and-errors#error-catalog";
+        };
     };
     readonly PROTECTED_ROOT: {
         readonly code: "D3003";
         readonly message: "Root element cannot be deleted";
+        readonly explanation: {
+            readonly when: "A transaction tried to delete the document's root element.";
+            readonly fix: "Delete the root's children instead, or remove the whole document with `project.removeDocument`.";
+            readonly docs: "https://dialecte.github.io/core/api/transaction#delete";
+        };
     };
     readonly REQUIRED_ATTRIBUTE_MISSING: {
         readonly code: "D3004";
         readonly message: "Required attribute is missing";
+        readonly explanation: {
+            readonly when: "Not raised by core itself: a dialecte or app code raises it when a required attribute is absent.";
+            readonly fix: "Give the attribute a value when creating the element.";
+            readonly docs: "https://dialecte.github.io/core/guide/development/state-and-errors#error-catalog";
+        };
     };
     readonly UNIQUE_CONSTRAINT_VIOLATION: {
         readonly code: "D3005";
         readonly message: "Value is already used within its scope";
+        readonly explanation: {
+            readonly when: "Not raised by core itself: a dialecte raises it when a value is already used within the scope where it must be unique.";
+            readonly fix: "Pick another value, or let the dialecte's hook name the element.";
+            readonly docs: "https://dialecte.github.io/core/guide/development/state-and-errors#error-catalog";
+        };
     };
     readonly UNKNOWN_NAMESPACE_PREFIX: {
         readonly code: "D3006";
         readonly message: "Unknown namespace prefix on attribute — pass it explicitly as { name, namespace: { prefix, uri } }";
+        readonly explanation: {
+            readonly when: "An attribute was written with a namespace key or prefix the dialecte does not declare.";
+            readonly fix: "Use a namespace key of the dialecte's config, or pass the namespace in full: `{ name, namespace: { prefix, uri } }`.";
+            readonly docs: "https://dialecte.github.io/core/api/transaction#addchild";
+        };
     };
     readonly PREFIXED_ATTRIBUTE_NAME: {
         readonly code: "D3007";
         readonly message: "Authored attribute name must be a local name — pass the namespace separately as { name, namespace }, not a prefixed name";
+        readonly explanation: {
+            readonly when: "An attribute was written with a prefixed name (`ext:attr`) on create or update.";
+            readonly fix: "Pass the local name and the namespace apart: `{ name: 'attr', namespace }`.";
+            readonly docs: "https://dialecte.github.io/core/api/transaction#addchild";
+        };
     };
     readonly FIXED_VALUE_VIOLATION: {
         readonly code: "D3008";
         readonly message: "Attribute value differs from the schema-fixed value";
+        readonly explanation: {
+            readonly when: "A write gave an attribute another value than the one the schema fixes.";
+            readonly fix: "Leave the attribute out (core writes the fixed value) or give exactly the fixed value; `getAttributeRules` reads it.";
+            readonly docs: "https://dialecte.github.io/core/api/transaction#addchild";
+        };
     };
     readonly XSI_TYPE_REQUIRED: {
         readonly code: "D3009";
         readonly message: "The element is declared with an abstract type: name a type with xsi:type";
+        readonly explanation: {
+            readonly when: "An element declared with an abstract type was created without naming a concrete type in `xsi:type`.";
+            readonly fix: "Name one of the admitted types: `attributes: { 'xsi:type': '<Type>' }`; `admittedXsiTypes` lists them.";
+            readonly docs: "https://dialecte.github.io/core/api/transaction#addchild";
+        };
     };
     readonly XSI_TYPE_NOT_ADMITTED: {
         readonly code: "D3010";
         readonly message: "The element may not take the type named with xsi:type";
+        readonly explanation: {
+            readonly when: "A write named in `xsi:type` a type the element may not take.";
+            readonly fix: "Pick a type from `admittedXsiTypes` for that element.";
+            readonly docs: "https://dialecte.github.io/core/api/transaction#addchild";
+        };
     };
     readonly XSI_TYPE_CHANGE_LEAVES_CONTENT: {
         readonly code: "D3011";
         readonly message: "The new xsi:type does not admit content the element still holds";
+        readonly explanation: {
+            readonly when: "An update changed `xsi:type` to a type that does not admit attributes or children the element still holds.";
+            readonly fix: "Remove that content in the same transaction before changing the type, or pick a type that admits it.";
+            readonly docs: "https://dialecte.github.io/core/api/transaction#update";
+        };
+    };
+    readonly XML_CHARACTER_NOT_ALLOWED: {
+        readonly code: "D3012";
+        readonly message: "The text holds a character XML does not allow";
+        readonly explanation: {
+            readonly when: "A write, an import session's own writes or an export met a character XML does not allow (a control character below U+0020 but tab, line feed and carriage return, U+FFFE, U+FFFF) in a value, a name, a prefix, a namespace URI or an id; nothing was written, no file.";
+            readonly fix: "Remove or replace the character named in `meta.character` at `meta.part` of the record `meta.recordId` before writing or exporting it.";
+            readonly docs: "https://dialecte.github.io/core/io/#values-a-store-keeps";
+        };
     };
     readonly ALREADY_COMMITTED: {
         readonly code: "D4001";
         readonly message: "Transaction already committed";
+        readonly explanation: {
+            readonly when: "Not raised by core today: kept for a transaction used after its commit.";
+            readonly fix: "Start a new `doc.transaction` for further writes.";
+            readonly docs: "https://dialecte.github.io/core/guide/development/state-and-errors#error-catalog";
+        };
     };
     readonly ALREADY_FAILED: {
         readonly code: "D4002";
         readonly message: "Transaction already failed";
+        readonly explanation: {
+            readonly when: "Not raised by core today: kept for a transaction used after it failed.";
+            readonly fix: "Start a new `doc.transaction`; the failed one wrote nothing.";
+            readonly docs: "https://dialecte.github.io/core/guide/development/state-and-errors#error-catalog";
+        };
     };
     readonly DATABASE_COMMIT_ERROR: {
         readonly code: "D4003";
         readonly message: "An error occurred while committing changes to the database";
+        readonly explanation: {
+            readonly when: "Not raised by core today: store commit failures are `STORE_COMMIT_FAILED`.";
+            readonly fix: "Read `cause`; see `STORE_COMMIT_FAILED`.";
+            readonly docs: "https://dialecte.github.io/core/guide/development/state-and-errors#error-catalog";
+        };
     };
     readonly CONCURRENT_TRANSACTION: {
         readonly code: "D4004";
         readonly message: "A transaction is already in progress. Concurrent transactions are not supported yet — serialize them or implement a transaction queue.";
+        readonly explanation: {
+            readonly when: "A `doc.transaction` started on a Document while another transaction or `doc.prepare` was still running on it (a missing `await`, or a nested transaction).";
+            readonly fix: "Await each transaction before the next; inside a transaction, write through its `tx`, never through `doc.transaction` again.";
+            readonly docs: "https://dialecte.github.io/core/api/document";
+        };
     };
     readonly EXPORT_ROOT_NOT_FOUND: {
         readonly code: "D5001";
         readonly message: "Root element not found in records during export";
+        readonly explanation: {
+            readonly when: "The export found no root record in the document.";
+            readonly fix: "The document is empty or damaged: import it again, or create it with `project.initEmptyDocument`.";
+            readonly docs: "https://dialecte.github.io/core/api/project#export";
+        };
     };
     readonly EXPORT_ORPHAN_CHILD_REF: {
         readonly code: "D5002";
         readonly message: "Parent references non-existent child record";
+        readonly explanation: {
+            readonly when: "The export met a parent whose list of children names a record that does not exist.";
+            readonly fix: "A hook or a raw write left a dangling child ref: a hook that deletes must also return the parent's `updated` operation.";
+            readonly docs: "https://dialecte.github.io/core/api/project#export";
+        };
     };
     readonly PARSE_ERROR: {
         readonly code: "D5003";
         readonly message: "Failed to parse XML";
+        readonly explanation: {
+            readonly when: "The file given to import (or to `parseXmlDocument`) is not well-formed XML.";
+            readonly fix: "Fix the XML where `detail` points (line and column); check the file's encoding.";
+            readonly docs: "https://dialecte.github.io/core/api/project#import";
+        };
+    };
+    readonly IMPORT_FAILED: {
+        readonly code: "D5004";
+        readonly message: "Failed to import the file";
+        readonly explanation: {
+            readonly when: "Importing a file failed after it was parsed (a hook threw, the store refused the records); nothing of the file remains.";
+            readonly fix: "Read `cause` and `detail`; an import hook must not read the store or throw on data it can report as a diagnostic.";
+            readonly docs: "https://dialecte.github.io/core/api/project#import";
+        };
+    };
+    readonly IMPORT_ABORTED: {
+        readonly code: "D5005";
+        readonly message: "The import was aborted";
+        readonly explanation: {
+            readonly when: "The import's `signal` was aborted; nothing of the file remains.";
+            readonly fix: "Nothing to fix when the abort was wanted; import the file again otherwise.";
+            readonly docs: "https://dialecte.github.io/core/api/project#import";
+        };
+    };
+    readonly EXPORT_CONFLICT: {
+        readonly code: "D5006";
+        readonly message: "The document changed while it was exported";
+        readonly explanation: {
+            readonly when: "The document was written twice while it was being exported, so no consistent file could be read.";
+            readonly fix: "Export when no transaction or import is writing the document, or retry.";
+            readonly docs: "https://dialecte.github.io/core/api/project#export";
+        };
+    };
+    readonly EXPORT_ABORTED: {
+        readonly code: "D5007";
+        readonly message: "The export was aborted";
+        readonly explanation: {
+            readonly when: "The export's `signal` was aborted.";
+            readonly fix: "Nothing to fix when the abort was wanted; export again otherwise.";
+            readonly docs: "https://dialecte.github.io/core/api/project#export";
+        };
     };
     readonly EXTENSION_METHOD_COLLISION: {
         readonly code: "D6001";
         readonly message: "Extension method name collision detected";
+        readonly explanation: {
+            readonly when: "Two extension modules merged under one key define a method of the same name.";
+            readonly fix: "Rename your method, or put your module under a key of its own.";
+            readonly docs: "https://dialecte.github.io/core/guide/extensions/#registering-extensions";
+        };
     };
     readonly UNKNOWN_CONFIG_KEY: {
         readonly code: "D7001";
         readonly message: "Unknown config key";
+        readonly explanation: {
+            readonly when: "A document, a test or a declaration named a config key the dialecte does not declare.";
+            readonly fix: "Use a key of the dialecte's `configs` (its `defaultConfigKey` when in doubt).";
+            readonly docs: "https://dialecte.github.io/core/api/dialecte#definedialecte";
+        };
     };
     readonly DOCUMENT_NOT_REGISTERED: {
         readonly code: "D7002";
         readonly message: "Document not registered in project";
+        readonly explanation: {
+            readonly when: "A document id names no document of the open project (removed, or from another project).";
+            readonly fix: "Use an id from `project.getDocuments()` or from the import result.";
+            readonly docs: "https://dialecte.github.io/core/api/project#document-access";
+        };
     };
     readonly PROJECT_NOT_OPENED: {
         readonly code: "D7003";
         readonly message: "Project not opened";
+        readonly explanation: {
+            readonly when: "The project was used before `open(name)` resolved, or once `close()`, `destroy()` or another `open()` was called on it - a batch import's file whose turn came after that is refused the same.";
+            readonly fix: "Keep the instance and await its `open(name)` before using the project; open it again after `close()` or `destroy()`, and await an `open()` of another project before using the Project again.";
+            readonly docs: "https://dialecte.github.io/core/api/project#lifecycle";
+        };
     };
     readonly BLOB_NOT_FOUND: {
         readonly code: "D7004";
         readonly message: "Blob not found in store";
+        readonly explanation: {
+            readonly when: "`project.exportBlob` named a blob the project does not hold.";
+            readonly fix: "Use an id from `project.getBlobsByDocument` or `getStandaloneBlobs`.";
+            readonly docs: "https://dialecte.github.io/core/api/project#blobs";
+        };
+    };
+    readonly PROJECT_LAYOUT_OUTDATED: {
+        readonly code: "D7005";
+        readonly message: "Project stored by another version of the library";
+        readonly explanation: {
+            readonly when: "The project file was stored by another version of the library (another layout); nothing was written to it.";
+            readonly fix: "Delete the project and import its files again with this version.";
+            readonly docs: "https://dialecte.github.io/core/api/project#store-errors";
+        };
+    };
+    readonly PROJECT_ENGINE_UNAVAILABLE: {
+        readonly code: "D7006";
+        readonly message: "No view can start the project engine";
+        readonly explanation: {
+            readonly when: "The project's engine could not be started or reached: its worker failed to load or never answered its open within the open budget; through the origin's hub, no open view offers an engine for the project's dialecte, or the engine never said it opened; a destroy still running past the open budget, or one asked by a page suspended before the hub granted it.";
+            readonly fix: "Keep one tab of the app open and reload; check the dialecte's `engineUrl` points at its worker and that it loads (the console names a script that fails); a destroy refused so is asked again once the project is closed elsewhere.";
+            readonly docs: "https://dialecte.github.io/core/api/project#store-errors";
+        };
+    };
+    readonly PROJECT_ENGINE_BUSY: {
+        readonly code: "D7007";
+        readonly message: "The project is still held by another engine";
+        readonly explanation: {
+            readonly when: "Another engine still holds the project (another tab or a worker that did not stop).";
+            readonly fix: "Close the other tabs of the app, then open the project again.";
+            readonly docs: "https://dialecte.github.io/core/api/project#store-errors";
+        };
+    };
+    readonly PROJECT_DIALECTE_MISMATCH: {
+        readonly code: "D7008";
+        readonly message: "The project's engine or file is of another dialecte";
+        readonly explanation: {
+            readonly when: "A project file stored by another dialecte was opened (nothing of it written); or an engine was asked for a project of another dialecte than its own - the dialecte's `engineUrl` (its project factory's, or a hub spawner's) pointing at another dialecte's worker. Two dialectes' projects of one name are two projects: opening one never meets the other. `meta`: `project`, `projectDialecteId` (the engine's or the file's), `realmDialecteId` (the one asked).";
+            readonly fix: "Open the project with the dialecte it was created with; point the dialecte's `engineUrl` at its own worker.";
+            readonly docs: "https://dialecte.github.io/core/api/project#store-errors";
+        };
+    };
+    readonly PROJECT_DIALECTE_VERSION_MISMATCH: {
+        readonly code: "D7009";
+        readonly message: "The project engine runs another version of the dialecte";
+        readonly explanation: {
+            readonly when: "The project's engine runs another version of the dialecte than this view.";
+            readonly fix: "Reload every tab of the app so they run the same version.";
+            readonly docs: "https://dialecte.github.io/core/api/project#store-errors";
+        };
+    };
+    readonly PROJECT_DESTROY_FAILED: {
+        readonly code: "D7010";
+        readonly message: "The project could not be deleted";
+        readonly explanation: {
+            readonly when: "Destroying a project left its files in place: another tab or worker still holds one.";
+            readonly fix: "Close the other tabs or windows of the app that have the project open, then destroy it again.";
+            readonly docs: "https://dialecte.github.io/core/api/project#lifecycle";
+        };
+    };
+    readonly PROJECT_OPEN_ELSEWHERE: {
+        readonly code: "D7011";
+        readonly message: "The project is open in another tab, window or connection";
+        readonly explanation: {
+            readonly when: "Another tab or window has the project open and there is no shared connection between them; or a destroy was asked while another connection - a store or project of the name in this page, or another tab - has the project open (`meta.connections`, where the store counts them).";
+            readonly fix: "Close the project in the other tab, window or connection, then open or destroy it here again.";
+            readonly docs: "https://dialecte.github.io/core/api/project#lifecycle";
+        };
+    };
+    readonly PROJECT_DATABASE_LOST: {
+        readonly code: "D7012";
+        readonly message: "The project's database is gone";
+        readonly explanation: {
+            readonly when: "The project's files hold data but none of them is its database any more: the database file's header was damaged (by the disk, another program, or site data changed outside the app). Nothing is opened or changed: no empty database is made in its place. `meta.project` names the project.";
+            readonly fix: "The project's data cannot be read back. Offer the user a reset, never automatically: `destroy()` on the same Project instance whose `open` was refused (keep it: `const project = new Project(params)`, then `await project.open(name)`) removes what the refused store holds, without opening it; `open(name)` then makes it again, empty, and its documents can be imported again.";
+            readonly docs: "https://dialecte.github.io/core/api/project#lifecycle";
+        };
+    };
+    readonly PROJECT_DESTROYED_WHILE_AWAY: {
+        readonly code: "D7013";
+        readonly message: "The project was deleted while this view was away";
+        readonly explanation: {
+            readonly when: "A view's connection to a project came back - the page back from a freeze or the back/forward cache, its engine started again - and the project it had open was destroyed meanwhile by another tab (and maybe made again under its name): nothing is opened in its place and nothing of it is read. `meta.project` names the project.";
+            readonly fix: "Tell the user the project was deleted elsewhere; close it in this view (`project.close()`), then open it again by its name for what is there now, or choose another.";
+            readonly docs: "https://dialecte.github.io/core/api/project#lifecycle";
+        };
+    };
+    readonly PROJECT_NAME_INVALID: {
+        readonly code: "D7014";
+        readonly message: "The project's name cannot name its files";
+        readonly explanation: {
+            readonly when: "A project's name or its dialecte's id is empty, `.` or `..`: every store refuses it before it is built (a SQLite project's files sit in a directory named after both, which no directory can be); nothing was opened or written. `meta.project` and `meta.dialecteId` say which.";
+            readonly fix: "Give the project a name of its own (and the dialecte an id) other than an empty one, `.` or `..`.";
+            readonly docs: "https://dialecte.github.io/core/api/project#lifecycle";
+        };
+    };
+    readonly PROJECT_ENGINE_NOT_DECLARED: {
+        readonly code: "D7015";
+        readonly message: "This project has no engine to open it on SQLite";
+        readonly explanation: {
+            readonly when: "A project was opened on `storage: { type: 'sqlite' }` but made by no dialecte's project factory: its engine (the dialecte's id, its version and its engine worker's URL) is known to no one, so nothing can start it. Nothing was opened.";
+            readonly fix: "Make the project with the dialecte's project factory (`createProjectFactory({ dialecte, engineUrl })`, as a dialecte package exports it), or open it on another storage.";
+            readonly docs: "https://dialecte.github.io/core/api/project#sqlite-storage";
+        };
+    };
+    readonly PROJECT_SQLITE_NOT_IMPORTED: {
+        readonly code: "D7016";
+        readonly message: "SQLite storage needs `import '@dialecte/core/sqlite'`";
+        readonly explanation: {
+            readonly when: "A project was opened (or destroyed by name) on `storage: { type: 'sqlite' }`, or a test asked for the `sqlite` test store, but the app never imported `@dialecte/core/sqlite`: the SQLite storage kind lives behind that entry, so an app that never imports it neither emits nor downloads the SQLite engine, its wasm or the hub. Nothing was opened.";
+            readonly fix: "Add `import '@dialecte/core/sqlite'` once to the app's entry (for tests, to the test runner's setup file), before the first project is opened on SQLite; or open the project on another storage. Imported already? The import registers the kind for every copy of @dialecte/core of the same SQLite storage version in the realm: a copy of another one (a dialecte bringing its own core) does not see it - align the core versions.";
+            readonly docs: "https://dialecte.github.io/core/api/project#sqlite-storage";
+        };
+    };
+    readonly DOCUMENT_PATH_INVALID: {
+        readonly code: "D7030";
+        readonly message: "A document's path is not valid";
+        readonly explanation: {
+            readonly when: "A document's path breaks a rule (empty, `.` or `..` segment, backslash, invisible character, not NFC, too long), names another file than the document's, changes its extension, or was handed to `project.import` of several files; nothing was written. `detail` says which rule.";
+            readonly fix: "Write the path relative, joined by `/`, in NFC, ending with the document's file name; pass a path to `importFile`, not to `import`.";
+            readonly docs: "https://dialecte.github.io/core/api/project#a-document-s-path";
+        };
+    };
+    readonly DOCUMENT_PATH_TAKEN: {
+        readonly code: "D7031";
+        readonly message: "A document's path is another document's place";
+        readonly explanation: {
+            readonly when: "Another document already holds the place (`meta.takenBy`), a document still importing included: the same path, a path under another document's file, or a file at a folder another document's path uses.";
+            readonly fix: "Choose a path no other document holds, or move the other document first.";
+            readonly docs: "https://dialecte.github.io/core/api/project#a-document-s-path";
+        };
     };
 };
 //# sourceMappingURL=codes.d.ts.map

package/dist/errors/codes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codes.d.ts","sourceRoot":"","sources":["../../src/errors/codes.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuKhB,CAAA"}
+{"version":3,"file":"codes.d.ts","sourceRoot":"","sources":["../../src/errors/codes.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8mBhB,CAAA"}

package/dist/errors/errors.constants.d.ts

@@ -0,0 +1,3 @@
+/** Where core's published docs live: an explanation's `docs` page is under it. */
+export declare const CORE_DOCS_URL = "https://dialecte.github.io/core";
+//# sourceMappingURL=errors.constants.d.ts.map

package/dist/errors/errors.constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.constants.d.ts","sourceRoot":"","sources":["../../src/errors/errors.constants.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,eAAO,MAAM,aAAa,oCAAoC,CAAA"}