@the_library/canonical-schemas 1.0.0 → 1.1.0

package/THIRD_PARTY_NOTICES

@@ -0,0 +1,3 @@
+THIRD-PARTY NOTICES — @the_library/canonical-schemas
+
+This package includes no third-party components.

package/definitions/canonical/Book.json

@@ -218,18 +218,25 @@
     }
   ],
   "translations": {
-    "fr": {
+    "fra": {
       "className": "Livre",
       "props": {
         "title": "titre",
         "description": "description"
       }
     },
-    "idn": {
-      "className": "Book",
+    "zho": {
+      "className": "书",
       "props": {
-        "title": "title",
-        "description": "description"
+        "title": "标题",
+        "description": "描述"
+      }
+    },
+    "tha": {
+      "className": "หนังสือ",
+      "props": {
+        "title": "ชื่อ",
+        "description": "คำอธิบาย"
       }
     }
   }

package/definitions/canonical/Person.json

@@ -28,7 +28,7 @@
     }
   ],
   "translations": {
-    "fr": {
+    "fra": {
       "className": "Personne"
     }
   }

package/governance/changelog.md

@@ -1,13 +1 @@
 # Changelog
-
-## v1.0.0 — 2026-06-20
-
-Initial release.
-
-**Standards included:** isbn (ISO 2108:2017), issn (ISO 3297:2007),
-isni (ISO 27729:2012), orcid, ddc.
-
-**Canonical models:** Book, Person, Tag, CopyrightStatus, QualityScore.
-
-**Approved by:** DataPond core team.
-**Deferred:** doi, lcnaf (see §8.2 of canonical_schemas_package_spec.md).

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@the_library/canonical-schemas",
-  "version": "1.0.0",
+  "version": "1.1.0",
+  "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "exports": {
     "./types/StandardAdapter": {
@@ -16,8 +17,16 @@
     "./schemas/StandardDefinition/1.0": "./schemas/StandardDefinition.1.0.json",
     "./package.json": "./package.json"
   },
-  "files": ["types", "standards", "definitions", "schemas", "governance"],
+  "files": [
+    "types",
+    "standards",
+    "definitions",
+    "schemas",
+    "governance",
+    "uid-documentation.md",
+    "THIRD_PARTY_NOTICES"
+  ],
   "devDependencies": {
     "typescript": "^6.0.3"
   }
-}
+}

package/types/StandardAdapter.ts

@@ -1,98 +1,7 @@
 /*
- * THE D-CODE SOVEREIGN LIABILITY SHIELD LICENCE (v3.0)
- * PROPRIETARY PUBLIC SOURCE | STRICTLY CONDITIONAL GRANT
- *
- * COPYRIGHT: © [Year] DATAPOND PUBLIC LIBRARY TRUST - Australia
- * TECHNICAL GUARDIAN: POND ENTERPRISE PTY LTD - Australia
- *
- * 1. PREAMBLE & DEFINITIONS
- *    a. "The Software": The source code, binaries, data models, and Web3 utilities
- *       provided herein.
- *    b. "Modification": Includes, but is not limited to, altering source files,
- *       runtime memory manipulation (monkey-patching), API proxying, network
- *       redirection, or any dynamic attempt to bypass hard-coded configurations.
- *    c. "The Trust": DataPond Public Library Trust.
- *    d. "The Guardian": Pond Enterprise Pty Ltd.
- *
- * 2. STIPULATION OF SYSTEMIC RISK & VALUATION
- *    You acknowledge that The Software is not a standalone application, but an
- *    inseparable interface to a shared Web3 data infrastructure and curated smart
- *    contract ecosystem. The parties unconditionally agree the fundamental value of
- *    this ecosystem is $50,000,000.00 USD. You explicitly acknowledge that:
- *    a. Liability Anchor: The Trust and The Guardian assume third-party liability
- *       based STRICTLY AND SOLELY upon the unaltered, hard-coded Smart Contract
- *       addresses and Canonical Config endpoints. Any Modification to these anchors
- *       fraudulently exposes the creators to catastrophic criminal and civil liability.
- *    b. Network Integrity: The Web3 data model utilizes a shared state. Any
- *       Modification of the data model or redirection to private, centralized
- *       databases (forking) threatens irreversible data corruption across the entire
- *       decentralized ecosystem, inherently destroying the $50,000,000.00 asset.
- *
- * 3. CONDITIONAL GRANT OF RIGHTS & OFFLINE RESILIENCE
- *    Subject to strict compliance with all terms herein, The Trust grants you a
- *    worldwide, royalty-free, non-exclusive license to view, copy, use, and
- *    distribute The Software. This includes the right to deploy certified static
- *    "Snapshots" in 100% offline environments.
- *
- * 4. STRICT TECHNICAL ANCHORS (ANTI-FORK / ANTI-PROXY)
- *    You are expressly PROHIBITED from executing any Modification (as defined in
- *    Section 1b) to The Software. The Software must utilize the exact Smart Contract
- *    addresses and Canonical Config endpoints as originally distributed.
- *
- * 5. D-SAFE INTEGRITY & CONTENT RULES
- *    Any implementation utilizing The Software must adhere to the D-SAFE Specification
- *    (strictly Decentralized, Integral [zero paywalls/ads], and Common [CC BY-NC-ND]).
- *    Furthermore, the network utilizing The Software must be entirely free from:
- *    (i) Ecological Harm; (ii) Explicit Content or Violence; (iii) IP Infringement;
- *    (iv) Political Campaigning; (v) Spiritual Proselytization; (vi) Historiographical
- *    Disputes; (vii) Medical Advice; (viii) Works of Fiction; (ix) Psychological
- *    Profiling.
- *    SOLE DISCRETION: The Trust and The Guardian reserve the sole, absolute, and
- *    unchallengeable discretion to determine whether any content or implementation
- *    violates the D-SAFE rules outlined in this Section 5.
- *
- * 6. THE "KUKRI" LIABILITY SHIELD & AUTOMATIC REVOCATION
- *    a. Trust Sanctuary: The Trust provides The Software "AS IS" and holds ZERO
- *       LIABILITY for any damages, gas fees, or data loss.
- *    b. Guardian Direction: Claims regarding technical performance or professional
- *       indemnity must be directed exclusively to The Guardian.
- *    c. User Indemnity: You agree to indemnify and hold harmless The Trust and The
- *       Guardian against any and all claims arising from your use of The Software.
- *    d. SHIELD REVOCATION: The liability protections of Section 6a and 6b are
- *       strictly contingent upon your absolute compliance with Section 5 (D-SAFE).
- *       If The Trust or The Guardian determines, in their sole discretion, that you
- *       have violated Section 5, ALL LIABILITY PROTECTIONS ARE IMMEDIATELY AND
- *       AUTOMATICALLY REVOKED. You shall assume full personal and corporate
- *       liability for your implementation.
- *
- * 7. BREACH, CURE PERIOD, AND LIQUIDATED DAMAGES
- *    a. Content Breach (Section 5): For violations of Section 5, your liability shield
- *       drops immediately. You will be provided thirty (30) days notice to cure the
- *       breach. Failure to cure results in permanent revocation of this License.
- *    b. Technical Breach (Section 4 - The $50M Trigger): Any violation of Section 4
- *       (Modification) is an uncurable, material breach. Due to the catastrophic
- *       systemic risks outlined in Section 2, actual damages are impossible to
- *       calculate. You explicitly agree that a Technical Breach shall immediately
- *       result in you paying The Trust Liquidated Damages (and not a penalty) in the
- *       amount of $50,000,000.00 USD, OR the total gross revenue generated by your
- *       unauthorized use (including revenue generated by parent companies, affiliates,
- *       and subsidiaries utilizing the modified implementation), whichever is greater.
- *
- * 8. GOVERNING LAW, ARBITRATION, AND INJUNCTIVE RELIEF
- *    This License shall be governed by the laws of the State of Victoria, Australia.
- *    Any dispute shall be finally resolved by arbitration under the ACICA Rules.
- *    The seat of arbitration shall be Melbourne, Australia. The prevailing party
- *    shall recover reasonable attorneys' fees. You acknowledge that a Technical
- *    Breach will cause irreparable harm, entitling The Trust to immediate injunctive
- *    relief in any competent court worldwide. You expressly waive any legal
- *    requirement for The Trust to secure or post any bond in connection with such
- *    injunctive relief.
- *
- * 9. SEVERABILITY
- *    If any provision of this License is held invalid by a tribunal of competent
- *    jurisdiction, such provision shall be reformed only to the extent necessary
- *    to make it enforceable, and the remaining provisions shall remain in full force.
- * ==============================================================================
+ * D-Open Code Sovereign Licence 1.1 · © 2026 Antoine LUCAS · SPDX-License-Identifier: LicenseRef-DOCSL-1.1
+ * Non-commercial use of unmodified copies only. By using this file you accept the Licence, incl. USD 50M liquidated damages (s 16.4).
+ * Full text: https://registry.worldbibliotech.com/licence and the LICENSE file · Contact: admin@pondenterprise.com
  */
 
 export interface ValidationResult {

package/types/StandardDefinition.ts

@@ -1,98 +1,7 @@
 /*
- * THE D-CODE SOVEREIGN LIABILITY SHIELD LICENCE (v3.0)
- * PROPRIETARY PUBLIC SOURCE | STRICTLY CONDITIONAL GRANT
- *
- * COPYRIGHT: © [Year] DATAPOND PUBLIC LIBRARY TRUST - Australia
- * TECHNICAL GUARDIAN: POND ENTERPRISE PTY LTD - Australia
- *
- * 1. PREAMBLE & DEFINITIONS
- *    a. "The Software": The source code, binaries, data models, and Web3 utilities
- *       provided herein.
- *    b. "Modification": Includes, but is not limited to, altering source files,
- *       runtime memory manipulation (monkey-patching), API proxying, network
- *       redirection, or any dynamic attempt to bypass hard-coded configurations.
- *    c. "The Trust": DataPond Public Library Trust.
- *    d. "The Guardian": Pond Enterprise Pty Ltd.
- *
- * 2. STIPULATION OF SYSTEMIC RISK & VALUATION
- *    You acknowledge that The Software is not a standalone application, but an
- *    inseparable interface to a shared Web3 data infrastructure and curated smart
- *    contract ecosystem. The parties unconditionally agree the fundamental value of
- *    this ecosystem is $50,000,000.00 USD. You explicitly acknowledge that:
- *    a. Liability Anchor: The Trust and The Guardian assume third-party liability
- *       based STRICTLY AND SOLELY upon the unaltered, hard-coded Smart Contract
- *       addresses and Canonical Config endpoints. Any Modification to these anchors
- *       fraudulently exposes the creators to catastrophic criminal and civil liability.
- *    b. Network Integrity: The Web3 data model utilizes a shared state. Any
- *       Modification of the data model or redirection to private, centralized
- *       databases (forking) threatens irreversible data corruption across the entire
- *       decentralized ecosystem, inherently destroying the $50,000,000.00 asset.
- *
- * 3. CONDITIONAL GRANT OF RIGHTS & OFFLINE RESILIENCE
- *    Subject to strict compliance with all terms herein, The Trust grants you a
- *    worldwide, royalty-free, non-exclusive license to view, copy, use, and
- *    distribute The Software. This includes the right to deploy certified static
- *    "Snapshots" in 100% offline environments.
- *
- * 4. STRICT TECHNICAL ANCHORS (ANTI-FORK / ANTI-PROXY)
- *    You are expressly PROHIBITED from executing any Modification (as defined in
- *    Section 1b) to The Software. The Software must utilize the exact Smart Contract
- *    addresses and Canonical Config endpoints as originally distributed.
- *
- * 5. D-SAFE INTEGRITY & CONTENT RULES
- *    Any implementation utilizing The Software must adhere to the D-SAFE Specification
- *    (strictly Decentralized, Integral [zero paywalls/ads], and Common [CC BY-NC-ND]).
- *    Furthermore, the network utilizing The Software must be entirely free from:
- *    (i) Ecological Harm; (ii) Explicit Content or Violence; (iii) IP Infringement;
- *    (iv) Political Campaigning; (v) Spiritual Proselytization; (vi) Historiographical
- *    Disputes; (vii) Medical Advice; (viii) Works of Fiction; (ix) Psychological
- *    Profiling.
- *    SOLE DISCRETION: The Trust and The Guardian reserve the sole, absolute, and
- *    unchallengeable discretion to determine whether any content or implementation
- *    violates the D-SAFE rules outlined in this Section 5.
- *
- * 6. THE "KUKRI" LIABILITY SHIELD & AUTOMATIC REVOCATION
- *    a. Trust Sanctuary: The Trust provides The Software "AS IS" and holds ZERO
- *       LIABILITY for any damages, gas fees, or data loss.
- *    b. Guardian Direction: Claims regarding technical performance or professional
- *       indemnity must be directed exclusively to The Guardian.
- *    c. User Indemnity: You agree to indemnify and hold harmless The Trust and The
- *       Guardian against any and all claims arising from your use of The Software.
- *    d. SHIELD REVOCATION: The liability protections of Section 6a and 6b are
- *       strictly contingent upon your absolute compliance with Section 5 (D-SAFE).
- *       If The Trust or The Guardian determines, in their sole discretion, that you
- *       have violated Section 5, ALL LIABILITY PROTECTIONS ARE IMMEDIATELY AND
- *       AUTOMATICALLY REVOKED. You shall assume full personal and corporate
- *       liability for your implementation.
- *
- * 7. BREACH, CURE PERIOD, AND LIQUIDATED DAMAGES
- *    a. Content Breach (Section 5): For violations of Section 5, your liability shield
- *       drops immediately. You will be provided thirty (30) days notice to cure the
- *       breach. Failure to cure results in permanent revocation of this License.
- *    b. Technical Breach (Section 4 - The $50M Trigger): Any violation of Section 4
- *       (Modification) is an uncurable, material breach. Due to the catastrophic
- *       systemic risks outlined in Section 2, actual damages are impossible to
- *       calculate. You explicitly agree that a Technical Breach shall immediately
- *       result in you paying The Trust Liquidated Damages (and not a penalty) in the
- *       amount of $50,000,000.00 USD, OR the total gross revenue generated by your
- *       unauthorized use (including revenue generated by parent companies, affiliates,
- *       and subsidiaries utilizing the modified implementation), whichever is greater.
- *
- * 8. GOVERNING LAW, ARBITRATION, AND INJUNCTIVE RELIEF
- *    This License shall be governed by the laws of the State of Victoria, Australia.
- *    Any dispute shall be finally resolved by arbitration under the ACICA Rules.
- *    The seat of arbitration shall be Melbourne, Australia. The prevailing party
- *    shall recover reasonable attorneys' fees. You acknowledge that a Technical
- *    Breach will cause irreparable harm, entitling The Trust to immediate injunctive
- *    relief in any competent court worldwide. You expressly waive any legal
- *    requirement for The Trust to secure or post any bond in connection with such
- *    injunctive relief.
- *
- * 9. SEVERABILITY
- *    If any provision of this License is held invalid by a tribunal of competent
- *    jurisdiction, such provision shall be reformed only to the extent necessary
- *    to make it enforceable, and the remaining provisions shall remain in full force.
- * ==============================================================================
+ * D-Open Code Sovereign Licence 1.1 · © 2026 Antoine LUCAS · SPDX-License-Identifier: LicenseRef-DOCSL-1.1
+ * Non-commercial use of unmodified copies only. By using this file you accept the Licence, incl. USD 50M liquidated damages (s 16.4).
+ * Full text: https://registry.worldbibliotech.com/licence and the LICENSE file · Contact: admin@pondenterprise.com
  */
 
 export interface StandardProp {

package/uid-documentation.md

@@ -0,0 +1,305 @@
+# D-Library UID System — Developer & Librarian Reference
+
+This document explains how every record in the D-Library is identified: what the numbers and letters in an ID mean, when each format is used, and why the system works the way it does.
+
+Every example ID below was generated by the model classes of `@the_library/public`.
+
+---
+
+## 1. Why there are multiple ID formats
+
+Every entity (Book, Person, Tag, …) in the D-Library has **three representations of the same underlying identity**. They all refer to the same record — they are not three different IDs, they are three views of one number.
+
+| Layer | Example | Stored? | Human-readable? |
+|---|---|---|---|
+| **wireId** | `4740` | Yes — inside binary data | No |
+| **base-34 body** | `000000000043E` | No — computed on demand | Partially |
+| **SFCUID** | `DL:C:BK:BK000000000043E1` | No — computed on demand | Yes |
+
+The wireId is the only thing stored on-chain and in Arweave sidecars. Everything else is derived from it when needed. This means IDs never take up permanent storage beyond the wireId integer itself.
+
+---
+
+## 2. The wireId — the permanent anchor
+
+The **wireId** is a 64-bit unsigned integer (a `bigint` in the SDK), assigned when the record is created. It never changes, never moves, and can never be reassigned.
+
+- **Canonical entities** (librarian-created): bit 63 is `0`.
+- **User-created entities**: bit 63 is `1` (`0x8000000000000000` and above).
+
+The wireId itself is never shown to users. It is only used internally in the binary codec, sidecar files, and on-chain records.
+
+---
+
+## 3. The base-34 encoding
+
+To convert a wireId into something human-readable, it is encoded in **base-34**.
+
+**Base-34 alphabet:** `0123456789ABCDEFGHJKLMNPQRSTUVWXYZ`
+
+That is digits 0–9, plus all uppercase letters A–Z, **except I and O** (removed to prevent confusion with 1 and 0 when handwritten or read aloud).
+
+The wireId is encoded as a **13-character base-34 string**, zero-padded on the left. 13 is the shortest width that fits every 64-bit value (34^13 ≈ 8.1 × 10^19 ≥ 2^64 ≈ 1.8 × 10^19).
+
+```
+wireId 4740  → 000000000043E
+wireId 847   → 00000000000QX
+wireId 812   → 00000000000PW
+wireId 510   → 00000000000F0
+wireId 1     → 0000000000001
+```
+
+**Legacy IDs.** PIDs minted before the 64-bit widening have a 7-character body (e.g. `000043E`). They still decode: the decoder accepts both lengths and checks the check character against the body as it was minted. New IDs are always written with 13 characters.
+
+---
+
+## 4. The three SFCUID modes
+
+**SFCUID** stands for *Standards-First Canonical UID*. Every entity has at least one SFCUID — it is the human-readable identifier used in links, exports, and display.
+
+There are three modes. Which mode is used depends on whether the entity maps to an external standard (like ISBN or ISNI).
+
+---
+
+### 4.1 Mode N — Native D-Library identifier
+
+Mode N is the **permanent anchor** identifier. Every entity with a type prefix gets one, regardless of whether it has an external standard. It is always available and always decodes to a wireId without any network call.
+
+**Format:**
+
+```
+DL : {scope} : {typePrefix} : {bare PID}
+
+bare PID = {typePrefix}{13-char base-34 body}{check character}
+```
+
+The type prefix appears twice: once as a readable segment, and once inside the bare PID, which is a self-contained ID on its own (§5).
+
+**Position-by-position breakdown:**
+
+```
+D L : C : B K : B K 0 0 0 0 0 0 0 0 0 4 3 E 1
+│ │   │   └─┘   └─┘ └───────────────────────┘ │
+│ │   │   type  type  13-char base-34 body     check
+│ │   │   prefix      (wireId in base-34)       character
+│ │   │
+│ │   scope:
+│ │     C = Canonical (librarian-assigned)
+│ │     U = User-created
+│ │
+│ └─ "L" — Library
+└─── "D" — DataPond namespace
+```
+
+**Examples:**
+
+```
+DL:C:BK:BK000000000043E1     — Canonical Book, wireId 4740
+DL:C:PR:PR00000000000PW6     — Canonical Person, wireId 812
+DL:C:TG:TG00000000000F0F     — Canonical Tag, wireId 510
+DL:C:PO:PO00000000000QXG     — Canonical Post, wireId 847
+DL:U:BK:BK3VDVL1X8K6VRTW     — User-created Book, wireId 0x8000000000000001
+```
+
+#### 4.1.1 The scope character (C vs U)
+
+| Scope | Meaning | wireId |
+|---|---|---|
+| `C` | **Canonical** — created by a librarian via the official pipeline | bit 63 = 0 |
+| `U` | **User-created** — created by an end user in their personal library | bit 63 = 1 |
+
+Both scopes use the same encoding and decoding rules.
+
+#### 4.1.2 Type prefix table
+
+The two-character type prefix comes from each model's `typePrefix` in `definitions/canonical/`:
+
+| Prefix | Entity | Description |
+|---|---|---|
+| `BK` | Book | A bibliographic Work. One Book may have many editions (its instances). |
+| `PR` | Person | An author, editor, illustrator, or other named contributor. |
+| `TG` | Tag | A subject classification, topic, or collection tag. |
+| `CS` | ClassificationSystem | A classification scheme a Tag belongs to. |
+| `PO` | Post | A discussion post. |
+
+A Book's editions (instances) have no prefix and no Mode N ID of their own: an edition is identified through Mode S (its ISBN) or Mode DERIVED (§4.3).
+
+#### 4.1.3 The check character
+
+The final character of the bare PID is a check character computed using **ISO 7064 MOD 37-2** over the type prefix plus the body. Its purpose is to catch transcription errors — if a single character is wrong or two adjacent characters are swapped, the check character will not validate.
+
+The check character is drawn from the 37-character set `0–9 A–Z *`, where `*` is output as `X`. Because the base-34 body excludes `I` and `O`, there is a disambiguation rule: if the computed check character is `I`, emit `J`; if it is `O`, emit `P`.
+
+---
+
+### 4.2 Mode S — Standard-backed identifier
+
+Mode S is used when an entity maps directly to an **external bibliographic standard** — a number like an ISBN, ISNI, ORCID, or a classification notation. Mode S is the **preferred display identity** for these entities.
+
+**Format:**
+
+```
+{standardId}:{normalizedValue}
+```
+
+The `standardId` is always **lowercase** (the `id` field from the standard's definition file), and the value is the standard adapter's normalized form.
+
+**Examples:**
+
+```
+isbn:9780262033848          — a Book edition identified by its ISBN-13
+isni:0000000121032683       — a Person identified by their ISNI
+orcid:0000-0002-1825-0097   — a Person identified by their ORCID
+ddc:510                     — a Tag carrying DDC class 510 (Mathematics)
+```
+
+**What "standards-backed" means in practice:**
+
+- For a **Book**, the ISBN identifies a specific edition, not the Work itself. The Work is always Mode N.
+- For a **Person**, ISNI is tried first, then ORCID.
+- For a **Tag**, the classification standards are tried in this order: `lcc`, `ddc`, `udc`, `clc`, `bbk`, `tlc`, `cc`. The first notation that is set is used; a Tag with none falls back to Mode N.
+
+**Important:** `isbn:` (lowercase) is the identifier form. The uppercase `ISBN:` prefix (as in each standard's `uriScheme`, `ISBN:{{isbn}}`) is the export form. These are two different contexts — do not mix them.
+
+---
+
+### 4.3 Mode DERIVED — Non-default instances
+
+Mode DERIVED is used for Book editions that were created from a standards-backed source but are not the original edition — for example, an AI translation or a specific scan of a book that already has an ISBN.
+
+**Format:**
+
+```
+DL:C:DERIVED:{sourceSFCUID}:{discriminatorValues}
+```
+
+**Examples:**
+
+```
+DL:C:DERIVED:isbn:9780262033848:gemini-eng   — Gemini English translation of that ISBN
+DL:C:DERIVED:isbn:9780262033848:claude-fra   — Claude French translation of that same book
+```
+
+The `discriminatorValues` are the values of the instance's `identityComponent` fields, in their declaration order, each URI-encoded and joined with `:`. In the Book model, `language` is the identity component.
+
+Resolving a Mode DERIVED ID needs the ExternalIdCrosswalk worker to be ready (§8.3).
+
+---
+
+## 5. The bare PID vs Mode N SFCUID vs Linked Data URI
+
+These three look similar but are used in different contexts:
+
+| Form | Example | Used for |
+|---|---|---|
+| **Bare PID** | `BK000000000043E1` | Compact storage reference, MARC field 001, internal cross-references |
+| **Mode N SFCUID** | `DL:C:BK:BK000000000043E1` | Display, sharing, links, the `toPID()` return value |
+| **Linked Data URI** (planned) | `https://datapond.earth/id/book/BK000000000043E1` | RDF/JSON-LD export, semantic web interoperability |
+
+The bare PID is the Mode N SFCUID without the `DL:{scope}:{typePrefix}:` prefix. The Linked Data URI wraps the bare PID in a dereferenceable HTTPS URL under `datapond.earth/id/`.
+
+The Linked Data URIs are **not served yet**. The planned content negotiation is:
+- `application/ld+json` → JSON-LD (schema.org + BIBO + D-Library vocabulary)
+- `text/turtle` → RDF/Turtle
+- `application/xml` → MARCXML
+- `text/html` → human-readable record page (default)
+
+---
+
+## 6. Which identifier is canonical for each entity
+
+| Entity | Strategy | Preferred form | Fallback |
+|---|---|---|---|
+| Book (Work) | `uidStrategy: "native-only"` | `DL:C:BK:BK{body}{check}` | — (Mode N always) |
+| Book edition (instance) | `instanceUidStrategy: ["isbn"]` | `isbn:9780262033848` | Mode DERIVED |
+| Person | `uidStrategy: ["isni", "orcid"]` | `isni:0000000121032683` | `DL:C:PR:PR{body}{check}` |
+| Tag | `uidStrategy: ["lcc", "ddc", "udc", "clc", "bbk", "tlc", "cc"]` | e.g. `ddc:510` | `DL:C:TG:TG{body}{check}` |
+| ClassificationSystem, Post | — / `"native-only"` | Mode N | — |
+
+A Book is always Mode N — ISBN identifies an *edition*, not the Work itself. A single Work can have many editions, each with its own ISBN.
+
+---
+
+## 7. For librarians: what this means in practice
+
+**When you see an identifier**, you can decode it immediately:
+
+- `DL:C:BK:BK000000000043E1` → a canonical Book, wireId 4740. The `BK` tells you it's a Book (Work); `C` tells you it was assigned by a librarian.
+- `isbn:9780262033848` → a specific edition identified by its ISBN. The system looks up which Book it belongs to automatically.
+- `isni:0000000121032683` → a Person whose ISNI is `0000000121032683`.
+- `ddc:510` → the Tag representing DDC class 510 (Mathematics).
+
+**In the World Library today**, the live library at [worldbibliotech.com](https://worldbibliotech.com) doesn't put PIDs or SFCUIDs in its links yet. Its pages address records by wireId, with hash routing:
+
+- `https://worldbibliotech.com/#/read/4740` — Book 4740
+- `https://worldbibliotech.com/#/topic/510` and `https://worldbibliotech.com/#/bookList/510` — Tag 510
+
+The identifiers in this document are what the model classes produce and resolve (`toPID()`, `fromPID()`, `Book.LoadInstance()`), for sharing, export and catalogue use.
+
+**When a book has no ISBN** (for example, a handwritten manuscript digitized without a commercial edition), its edition gets a Mode DERIVED ID based on the Book's native ID plus its language, such as `DL:C:DERIVED:DL:C:BK:BK000000000043E1:eng`.
+
+**Scope C vs U:** Records you create as a librarian through the official pipeline are Canonical (C). Records users create in their personal libraries are User-created (U). Both types share the same ID format — the only difference is the scope letter and the top bit of the wireId.
+
+**The check character** at the end of every PID is a built-in safeguard. If someone misreads a digit or transposes two characters, the system flags the ID as invalid rather than silently looking up the wrong record. Think of it like the check digit on an ISBN or a credit card number.
+
+---
+
+## 8. For developers: implementation notes
+
+### 8.1 `toPID()` vs `sfcuid()`
+
+Every generated model class (`@the_library/public/models/models`) has these identity methods:
+
+- **`toPID()` / `toNativePID()`** — always returns the Mode N SFCUID (`DL:C:BK:BK…`). Synchronous, no worker needed. Available on every entity regardless of `uidStrategy`.
+- **`static fromPID(pid)`** — the reverse: accepts a Mode N SFCUID or a bare PID (13-character or legacy 7-character body) and returns `{ wireId }`, or `null` if it doesn't match the model's prefix or its check character.
+- **`sfcuid()`** — returns Mode S when a standard prop is populated, otherwise falls back to Mode N. Only present on standards-first models (`uidStrategy: string[]`, e.g. Person and Tag). Not present on `native-only` models (Book at Work level, Post, ClassificationSystem).
+- **`BookInstance.sfcuid()`** — a Book edition's own identifier: `isbn:…` when the edition has an ISBN, otherwise a Mode DERIVED ID built from the parent Book's `toPID()` (§4.3).
+
+### 8.2 Priority for `sfcuid()`
+
+When a model declares multiple standards (e.g., `uidStrategy: ["isni", "orcid"]` on Person), `sfcuid()` tries them in declaration order and returns the first populated one:
+
+```typescript
+sfcuid(): string {
+  if (this.isniId)  return `isni:${ISNIAdapter.normalize(this.isniId)}`;
+  if (this.orcidId) return `orcid:${ORCIDAdapter.normalize(this.orcidId)}`;
+  return this.toNativePID();
+}
+```
+
+### 8.3 Resolving an identifier
+
+`Book.LoadInstance(id, lang)` resolves any of the three modes to a Book and, for editions, the index of the matching instance:
+
+| SFCUID mode | How it resolves | Waits for |
+|---|---|---|
+| Mode N (`DL:C:…`) | Decodes inline with `fromPID()`, then loads the Book | — |
+| Mode S (`isbn:…`) | Looks the value up in the ExternalIdCrosswalk worker | the crosswalk worker |
+| Mode DERIVED | Looks the instance up in the ExternalIdCrosswalk worker | the crosswalk worker |
+
+`LoadInstance` waits for the crosswalk worker before resolving any mode. Its Mode N branch reads canonical IDs (`DL:C:`); decode a user-created ID (`DL:U:`) with `fromPID()` and load it with `LoadAsync()`.
+
+### 8.4 Standard props are ORM artifacts, not annotations
+
+The `isbn` prop on a Book edition is **not** a plain string stored alongside other fields. It is injected by the compiler from the `isbn.json` StandardDefinition in `@the_library/canonical-schemas`. On the generated class it comes with:
+
+- A validation method (`validateIsbn()`)
+- A normalized getter (`isbnNormalized`)
+- A propId from the global, append-only property dictionary, like every other prop
+
+No model may declare its own `isbn` field: the compiler rejects a model prop that collides with a standard's prop. Only `instanceUidStrategy: ["isbn"]` appears in the model definition, and the compiler and the code generator handle the rest. Lookups against the standard's external APIs (Open Library, Google Books) are in `@the_library/standard-adapters` (`ISBNAdapter.apis`), not on the model.
+
+### 8.5 Encoding and decoding PIDs
+
+Use the model classes: `toPID()` to encode and `fromPID()` to decode. The low-level `encodePID()` / `decodePID()` functions are internal to the SDK and not exported. Do **not** hand-compute base-34 bodies or check characters — the ISO 7064 MOD 37-2 check algorithm includes the I/O disambiguation rule (computed `I` → `J`, `O` → `P`) that is easy to get wrong by hand.
+
+### 8.6 The `@the_library/canonical-schemas` package
+
+The canonical definitions used throughout this system live in `@the_library/canonical-schemas`. This package:
+- Exports TypeScript interfaces (`StandardAdapter`, `StandardDefinition`)
+- Contains JSON definition files for each standard (`standards/isbn.json`, `standards/isni.json`, etc.)
+- Contains model definition files (`definitions/canonical/Book.json`, `Person.json`, `Tag.json`, `ClassificationSystem.json`, `Post.json`)
+- Contains enum definitions (`definitions/canonical/enums/`)
+- Has **no runtime code** — it is types and definition data only
+
+The runtime adapter implementations (validation, normalization, external API calls) live in `@the_library/standard-adapters`, which depends on `canonical-schemas` but is never imported by it.