@the_library/canonical-schemas 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,44 @@
+D-OPEN CODE SOVEREIGN LICENCE v1.0
+
+Copyright © 2026 DataPond Public Library Trust ("The Sanctuary")
+Technical Guardian: Pond Enterprise Pty Ltd ("The Shield")
+
+Full licence text, legal definitions, and governing terms:
+  https://registry.worldbibliotech.com/licence.html
+
+Source file: apps/registry/licence.html
+
+---
+
+SUMMARY OF KEY TERMS
+
+This software is a fundamental component of the DataPond Ecosystem, designed
+to build a decentralised, indestructible public library. Unlike standard
+open-source licences, the D-Open Code Sovereign Licence is a conditional
+grant of rights tied strictly to the ethical and technical preservation of
+the Public Domain.
+
+The Trust grants you a worldwide, royalty-free, non-exclusive licence to use,
+copy, modify, and distribute this software, subject to:
+
+  1. PUBLIC ACCESS — You may not restrict access to the underlying public data
+     via paywalls or mandatory registration.
+
+  2. D-SAFE INTEGRITY — Content served by this software must adhere to D-SAFE
+     Label standards.
+
+  3. TECHNICAL ANCHORS — You may not modify hard-coded Smart Contract addresses
+     to point to non-certified ledgers, and you may not fork this package to
+     redirect the DataPond canonical models to a private, centralised database.
+
+  4. OFFLINE RIGHTS — Deployment in fully offline environments (air-gapped
+     schools, remote field operations) is explicitly permitted under snapshot
+     terms.
+
+  5. BREACH — Violations trigger automatic termination with a 30-day cure
+     period before legal action.
+
+THE FULL LICENCE TEXT AT THE URL ABOVE GOVERNS. THIS SUMMARY IS FOR
+INFORMATIONAL PURPOSES ONLY AND DOES NOT CONSTITUTE LEGAL ADVICE.
+
+Governing law: South Australia.

package/README.md

@@ -1,3 +1,542 @@
-# Temporary Holding Version
+# `@the_library/canonical-schemas`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The governance artifact and TypeScript type library at the heart of the D-SAFE ecosystem. This package is the single source of truth for all canonical model definitions, international standard definitions, and their multilingual translations. Every D-SAFE application — from DataPond's own frontend to any third-party institution building on the sovereign library stack — installs this package as a dependency.
+
+> **No runtime code lives here.** `@the_library/canonical-schemas` ships JSON governance files and TypeScript interfaces only. Executable adapter logic lives in the companion package [`@the_library/standard-adapters`](#dependency-on-the_librarystandard-adapters).
+
+---
+
+## Licence
+
+This package is released under the **D-Open Code Sovereign Licence v1.0**.
+
+Full text: [registry.worldbibliotech.com/licence.html](https://registry.worldbibliotech.com/licence.html)
+
+See the [`LICENSE`](./LICENSE) file in this directory. [Read more about the licence below.](#the-d-open-code-sovereign-licence--source-code)
+
+---
+
+## Package layout
+
+```
+packages/canonical-schemas/
+  standards/               International standard definitions (StandardDefinition JSON)
+    isbn.json              ISO 2108:2017 — International Standard Book Number
+    issn.json              ISO 3297:2007 — International Standard Serial Number
+    isni.json              ISO 27729:2012 — International Standard Name Identifier
+    orcid.json             Open Researcher and Contributor ID
+    ddc.json               Dewey Decimal Classification (OCLC / Library of Congress)
+    lcc.json               Library of Congress Classification
+    udc.json               Universal Decimal Classification (UDC Consortium)
+    clc.json               Chinese Library Classification (National Library of China)
+    bbk.json               Library-Bibliographical Classification (Russian State Library)
+    tlc.json               Thai Library Classification (National Library of Thailand)
+    cc.json                Colon Classification (S.R. Ranganathan)
+
+  types/                   TypeScript interface definitions — zero runtime code
+    StandardAdapter.ts     StandardAdapter<TProps, TApis>, StandardApiAdapter, ValidationResult
+    StandardDefinition.ts  StandardDefinition, StandardProp, ExternalApiEntry, FieldMapping
+
+  definitions/
+    canonical/             ModelDefinition files for canonical entity types
+      Book.json            multipleInstances: true; instanceUidStrategy drives isbn codegen
+      Person.json          uidStrategy: ["isni", "orcid"]
+      Tag.json             uidStrategy: ["ddc"]
+      enums/
+        CopyrightStatus.json
+        QualityScore.json
+
+  schemas/
+    StandardDefinition.1.0.json   JSON Schema (meta-schema) for all standards/ files
+
+  governance/
+    GOVERNANCE.md          Rules for proposing changes to canonical definitions
+    changelog.md           Every decision: who approved what and when
+```
+
+---
+
+## Architecture: the two-tier definition hierarchy
+
+Schema definitions in the D-SAFE ecosystem are split into two tiers.
+
+```
+@the_library/canonical-schemas   ← governance package (DataPond publishes and controls)
+  definitions/canonical/
+    Book.json                    ← canonical: true
+    Person.json
+    Tag.json
+
+packages/db_schemas            ← compiler + codec (consumes canonical-schemas)
+  definitions/                   ← app-level definitions only
+    member.json                  ← canonical: false (DataPond-specific)
+```
+
+The canonical package is an **npm dependency** that every D-SAFE app installs. Third-party developers never edit it directly; they open a PR against the canonical repo to propose new models or translations. This design solves the **cross-app conflict problem**: without a shared authority, two apps that both define a `Book.title` prop could assign conflicting binary layouts, causing silent data corruption when records from different libraries are merged. With this package, canonical propIds are seeded first (IDs 0–511) and every app's compiler enforces the no-override invariant: a local definition may extend a canonical model but may never alter its prop names, types, bit widths, or enum references.
+
+---
+
+## Standards
+
+Each file in `standards/` is a `StandardDefinition` — a machine-readable description of one international identifier standard. It specifies:
+
+- The **props** the standard contributes to implementing models (name, wire type, normalization, display, check digit algorithm, regex pattern)
+- The **Mode S URI scheme** used for standards-first entity addressing (`sfcuid()`)
+- The **Linked Data URI template** for RDF/LOD output
+- **Discovery metadata** for external APIs, including field mappings and rate limits
+
+### Initial release: identifier standards
+
+| Standard | ID | Governing body | ISO ref | Check digit |
+|---|---|---|---|---|
+| ISBN-13 | `isbn` | International ISBN Agency | ISO 2108:2017 | isbn-13-luhn |
+| ISSN | `issn` | ISSN International Centre | ISO 3297:2007 | iso7064-mod11-2 |
+| ISNI | `isni` | ISNI International Agency | ISO 27729:2012 | iso7064-mod11-2 |
+| ORCID iD | `orcid` | ORCID Inc. | — | iso7064-mod11-2 |
+
+### Classification standards
+
+| Standard | ID | Governing body |
+|---|---|---|
+| Dewey Decimal Classification | `ddc` | OCLC (licensed from Library of Congress) |
+| Library of Congress Classification | `lcc` | Library of Congress |
+| Universal Decimal Classification | `udc` | UDC Consortium |
+| Chinese Library Classification | `clc` | National Library of China |
+| Library-Bibliographical Classification (ББК) | `bbk` | Russian State Library |
+| Thai Library Classification | `tlc` | National Library of Thailand |
+| Colon Classification | `cc` | S.R. Ranganathan (historical) |
+
+Classification standards (ddc and friends) have `externalApis: []` — the classifier assigns notations based on content; no external lookup is needed.
+
+### Normalization and display algorithms
+
+Each `props[]` entry declares `normalize` and `display` algorithm IDs. The `@the_library/db_schemas` compiler and `@the_library/standard-adapters` both implement these:
+
+| Algorithm | Used by | Normalized form |
+|---|---|---|
+| `compact-13` | ISBN | 13 compact digits; ISBN-10 converted to ISBN-13 |
+| `hyphenated-8` | ISSN | `NNNN-NNNX` |
+| `compact-16` | ISNI | 16 compact digits |
+| `hyphenated-4x4` | ORCID | `NNNN-NNNN-NNNN-NNNX` |
+| `ddc-notation` | DDC | Trim trailing zeros; normalize dots |
+
+The normalized form is always the standard's own authoritative storage format, not a universal compactness rule. ORCID retains hyphens because the ORCID spec mandates `NNNN-NNNN-NNNN-NNNX`; ISBN strips them because library convention does.
+
+---
+
+## ModelDefinition and `uidStrategy`
+
+`ModelDefinition` files in `definitions/canonical/` may declare a `uidStrategy` field that references standard IDs. This is what links a canonical model to its external identifiers.
+
+```json
+// definitions/canonical/Book.json (excerpt)
+{
+  "name": "Book",
+  "canonical": true,
+  "uidStrategy": "native-only",
+  "multipleInstances": true,
+  "instanceUidStrategy": ["isbn"]
+}
+```
+
+```json
+// definitions/canonical/Person.json (excerpt)
+{
+  "name": "Person",
+  "canonical": true,
+  "uidStrategy": ["isni", "orcid"]
+}
+```
+
+| `uidStrategy` value | Meaning |
+|---|---|
+| `"native-only"` | No universal external standard. Generated class uses Mode N UIDs only. |
+| `["isni", "orcid"]` | Implements two standards in priority order. `sfcuid()` returns Mode S from the first whose prop is non-null; falls back to Mode N. |
+| `["ddc"]` | Implements one classification standard. `sfcuid()` returns `ddc:{notation}` when non-null. |
+
+`instanceUidStrategy` applies the same logic to instance sub-objects of a `multipleInstances: true` model. `Book.instanceUidStrategy: ["isbn"]` injects the `isbn` prop onto `InstanceData`, generates `Book.LoadInstance("isbn:...")`, and registers an `isbnToInstance` crosswalk map in the Worker.
+
+The `@the_library/db_schemas` compiler enforces at build time that every standard ID in a `uidStrategy` array exists in this package's `standards/` directory, has a non-null `uriScheme`, and declares a `pk` prop.
+
+---
+
+## Multilingual ORM (`i18N`)
+
+Translations live inside the canonical definition files — not in app code. The French name for `Book.title` is `titre` as a canonical, governance-controlled fact, subject to the same review process as the prop itself. This ensures that any two French-locale apps built on D-SAFE use identical API surfaces, making cross-app interop structurally guaranteed rather than a coordination agreement.
+
+```json
+// definitions/canonical/Book.json (translations excerpt)
+{
+  "translations": {
+    "fr": {
+      "className": "Livre",
+      "staticMethods": { "Load": "Construit", "Query": "Chercher" },
+      "props": { "title": "titre", "description": "description" }
+    },
+    "de": { "className": "Buch", "props": { "title": "Titel" } }
+  }
+}
+```
+
+The `@the_library/public/models` schema generator's `--locale <lang>` flag emits thin TypeScript facade classes from these entries:
+
+```typescript
+// AUTO-GENERATED: Livre.ts (fr locale facade for Book)
+import { Book } from "./Book.ts";
+
+export class Livre extends Book {
+  get titre()  { return this.title;  }
+  set titre(v) { this.title = v; }
+  static Construit(id: number) { return Book.Load(id); }
+}
+```
+
+The canonical English class is always the structural base. The wire format, `binary.json` propIds, and all on-chain patches are untouched by locale. A French app's `Livre` is 100% binary-compatible with an English app's `Book` — they patch the same propIds.
+
+Standard-contributed props also carry translation entries. See the `translations` field in each `standards/*.json` file.
+
+---
+
+## EVM-compatible TypeScript classes
+
+The definitions governed by this package are the foundation of a full ORM whose generated output is **natively compatible with EVM smart contract storage**. The `@the_library/public/models` schema generator reads `ModelDefinition` files from `definitions/canonical/` and emits TypeScript classes whose state is binary-encoded into on-chain patches — not stored in a traditional database.
+
+### How the stack connects
+
+```
+@the_library/canonical-schemas          ← defines props, types, propIds
+        │
+        ▼  (consumed at build time)
+packages/db_schemas                   ← compiler: assigns binary propIds, builds binary.json
+        │
+        ▼  (code generation)
+packages/public/src/models → generated-src/    ← TypeScript classes with toPatch() / fromPatch()
+        │
+        ▼  (EVM calldata)
+contracts/ — Factory, BouncerStorage,   ← smart contracts receive binary-encoded patches
+             ScientistStorage, BackupStorage,    on SONIC mainnet (chain 146) and
+             AddressRegistry                     SONIC_BLAZE testnet (chain 14601)
+```
+
+### Binary encoding
+
+Every prop in `definitions/canonical/` maps to a globally stable numeric `propId` in `packages/db_schemas/dist/binary.json`. Canonical props occupy IDs **0–511**; app-level props start at **512**. This range split is what makes cross-institutional interoperability a structural property: any two apps built on the same canonical version agree on canonical propIds without any coordination — their on-chain patches are binary-compatible by construction.
+
+The generated class encodes its state into a compact binary patch:
+
+```typescript
+// AUTO-GENERATED (@the_library/public/models output)
+import { Book } from '@my-app/models';
+
+const book = new Book();
+book.title = "Thinking, Fast and Slow";
+book.copyrightStatus = CopyrightStatus.InCopyright;
+
+// Serialize to binary-encoded EVM calldata:
+const patch = book.toPatch();   // Uint8Array — propId + value pairs, packed per binary.json
+
+// Submit via the Factory contract (@the_library/public's EVM client):
+await factory.write.submitPatch([patch]);
+```
+
+The patch codec (`@the_library/db_schemas`'s `src/codec.ts`), `binary.json`, `versions.json`, and the EVM contracts are entirely unaffected by locale, translations, or which external APIs are configured. The ORM's i18N layer and the standard-adapter field-mapping layer both live **above** the wire format — the chain sees only propIds and values.
+
+### What the smart contracts store
+
+The four core contracts handle different write concerns:
+
+| Contract | Role |
+|---|---|
+| `BouncerStorage` | Access control — enforces member permissions before any write reaches storage |
+| `ScientistStorage` | Content metadata — stores canonical model patches (Book, Person, Tag records) |
+| `BackupStorage` | Arweave sidecar links — permanent-web content addresses anchored on-chain |
+| `Factory` | Write orchestration — routes patches to the correct storage contract |
+| `AddressRegistry` | Canonical address book — resolves contract addresses dynamically to survive hard-forks |
+
+Every model write goes through this pipeline: TypeScript ORM class → binary patch → `Factory.submitPatch()` → `BouncerStorage` (access check) → `ScientistStorage` (write). The canonical `propId` values from this package are what the contracts index and the crosswalk Worker queries.
+
+---
+
+## Dependency on `@the_library/standard-adapters`
+
+`@the_library/canonical-schemas` ships **only interfaces and JSON**. The companion package `@the_library/standard-adapters` ships the runtime implementations.
+
+```
+@the_library/canonical-schemas          ← no runtime imports; standalone
+  │  exports: standards/*.json
+  │  exports: types/StandardAdapter.ts   (interfaces only)
+  │  exports: types/StandardDefinition.ts
+  │
+  ▼  (implements the interfaces)
+@the_library/standard-adapters          ← runtime library; imports types from canonical-schemas
+  │  exports: ISBNAdapter, ISSNAdapter, ISNIAdapter, ORCIDAdapter, DDCAdapter, ...
+  │  exports: apiKeyDictionary
+  │
+  ▼  (consumes both)
+packages/db_schemas / apps/vue.datapond.earth / apps/book-manager
+```
+
+**Strict dependency rule:** `@the_library/canonical-schemas` must never import anything from `@the_library/standard-adapters`. This is enforced by the pnpm workspace dependency graph — `canonical-schemas/package.json` declares no dependency on `standard-adapters`. The `apiKeyDictionary` singleton that manages runtime API credentials lives entirely in `standard-adapters` and is unknown to this package.
+
+### `StandardAdapter` interface (defined here, implemented in `standard-adapters`)
+
+```typescript
+// types/StandardAdapter.ts
+
+export interface StandardAdapter<TProps, TApis> {
+  readonly standardId: string;
+  readonly uriScheme: string | null;
+  readonly apis: TApis;
+  normalize(value: string): string;
+  display(value: string): string;
+  validate(value: string | null | undefined): ValidationResult;
+  toLinkedDataUri(value: string): string;
+}
+```
+
+Each adapter in `standard-adapters` implements this interface. The `@the_library/db_schemas` compiler imports `standard-adapters` at build time and validates that every `externalApis[].id` in a standard's JSON definition has a matching key in the corresponding adapter's `apis` object. A missing key is a fatal compile error.
+
+### `externalApis` and field mapping
+
+The `externalApis[]` array in each standard definition describes the external APIs that support that standard and how their response fields map onto model props:
+
+```json
+{
+  "id": "openlibrary",
+  "kind": "lookup",
+  "rateLimit": { "requests": 100, "windowSeconds": 60 },
+  "fieldMapping": [
+    { "source": "title",       "target": "title",     "overwrite": "if-empty" },
+    { "source": "pageCount",   "target": "pageCount", "overwrite": "if-empty" },
+    { "source": "publishDate", "target": "pubYear",   "overwrite": "if-empty" }
+  ]
+}
+```
+
+- `"lookup"` — called with the standard's known pk value; populates or corrects model fields from an authoritative source.
+- `"search"` — called with partial information (a name, a keyword); returns candidates for operator selection.
+- `overwrite: "always"` — write unconditionally (use for pk fields and authoritative IDs).
+- `overwrite: "if-empty"` — write only if the target prop is currently null.
+- `overwrite: "never"` — fetch for UI comparison; do not auto-apply.
+
+The `@the_library/public/models` codegen uses these entries to generate `fetchFrom{ApiId}()` and `searchFrom{ApiId}()` methods on the model class, with return types inferred from the adapter's TypeScript `TApis` map.
+
+### `ApiKeyDictionary`
+
+Adapters that require an API key (marked `requiresApiKey: true` in `externalApis[]`) consume credentials through a global `apiKeyDictionary` singleton in `standard-adapters`. Consumer apps set keys once at startup:
+
+```typescript
+import { apiKeyDictionary } from '@the_library/standard-adapters';
+
+// Call before any adapter method that requires a key
+apiKeyDictionary.set('googlebooks', import.meta.env.VITE_GOOGLE_BOOKS_API_KEY);
+```
+
+If a key is missing when an adapter calls `apiKeyDictionary.require(apiId)`, it throws immediately with a clear error naming the missing key — fail fast at configuration time, not mid-request.
+
+---
+
+## Governance
+
+`@the_library/canonical-schemas` follows semantic versioning with strict rules:
+
+| Bump | Triggers |
+|---|---|
+| **Patch** | Typo fixes in labels or descriptions; translation additions; governance doc edits |
+| **Minor** | New standard definition file; new `externalApis[]` entry; new canonical model prop or enum value |
+| **Major** | Any change to a frozen field: `props[].name`, `props[].type`, `checkDigit.algorithm`, `uriScheme` variable names; removal of a standard; propId reassignment |
+
+**Frozen forever once published:** `id`, `props[].name`, `props[].type`, `props[].checkDigit.algorithm`, and `uriScheme` template variable names. These fields are embedded in binary-encoded on-chain patches for the life of the protocol.
+
+To propose a new standard or canonical model, open two coordinated PRs: one against this package (the JSON definition) and one against `@the_library/standard-adapters` (the TypeScript implementation). Both must be reviewed and merged together — a standard definition without a registered adapter is a fatal compile error in downstream apps.
+
+See [`governance/GOVERNANCE.md`](./governance/GOVERNANCE.md) and [`governance/changelog.md`](./governance/changelog.md).
+
+---
+
+## JSON Schema validation
+
+All files in `standards/` are validated against the meta-schema at `https://schemas.dsafe.us/StandardDefinition/1.0`. A local copy is bundled at [`schemas/StandardDefinition.1.0.json`](./schemas/StandardDefinition.1.0.json) and resolved via the package `exports` map for IDE tooling and CI validation before the remote endpoint is live.
+
+---
+
+## Licence Architecture
+
+The D-SAFE ecosystem operates under **two distinct licences** covering two distinct concerns. Understanding which licence applies to what is essential before building on this stack.
+
+```
+  SOURCE CODE                          CONTENT
+  (this package, smart contracts)      (books, works, knowledge artifacts)
+
+  D-Open Code Sovereign Licence   ──── governs ────►  D.I.C. + K  (Ꭰ-Licence)
+  └─ takes full liability               └─ Decentralized · Integral · Common
+  └─ non-modification clause            └─ + K certification overlay
+  └─ compatible with D.I.C.             └─ enforced on-chain by BouncerStorage
+  └─ fully D-SAFE by design             └─ anchored on Arweave permanently
+```
+
+They are designed to work together. The source code engine was built from the ground up to support D.I.C. natively: every architectural decision — immutable contracts, Arweave anchoring, the canonical schema, the BouncerStorage gate — exists to make D.I.C. compliance the path of least resistance for any application built on top.
+
+---
+
+## The D-Open Code Sovereign Licence  ·  Source Code
+
+This package, the EVM smart contracts, and the entire D-SAFE engine are published under the **D-Open Code Sovereign Licence v1.0**.
+
+Full text: [registry.worldbibliotech.com/licence.html](https://registry.worldbibliotech.com/licence.html)
+
+This is a licence for **source code** — the engine, the schema compiler, the ORM, the on-chain contracts. It is not a content licence. It governs what developers may do with the software itself.
+
+### What makes it different
+
+Unlike every conventional open-source licence, the D-Open Code Sovereign Licence **takes liability rather than disclaiming it**. It establishes a two-layer accountability structure:
+
+- **The Sanctuary** — DataPond Public Library Trust, a non-profit entity holding the assets. Provides the software and holds zero liability for damages, gas fees, or data loss.
+- **The Shield** — Pond Enterprise Pty Ltd, the technical guardian. Absorbs all claims regarding technical performance, patent infringement, and professional indemnity related to the core architecture.
+
+This is not a disclaimer. It is an **architecture of accountability** — named entities standing behind the technical warranty. For the first time, institutional partners, schools, and governments can deploy sovereign library infrastructure with a legal counterpart they can actually reach.
+
+### Core terms
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│           D-OPEN CODE SOVEREIGN LICENCE — SOURCE CODE            │
+├──────────────────────────────────────────────────────────────────┤
+│  PERMITTED                                                       │
+│                                                                  │
+│   ✔  Use, copy, and distribute the source code freely           │
+│   ✔  Build D-SAFE-compliant applications on top of it           │
+│   ✔  Deploy in fully offline / air-gapped environments          │
+│   ✔  Snapshot the codebase for long-term archive deployments     │
+│                                                                  │
+├──────────────────────────────────────────────────────────────────┤
+│  CONDITIONS                                                      │
+│                                                                  │
+│   ✘  No Modification of the certified source                    │
+│   ✘  No redirecting canonical models to private databases       │
+│   ✘  No use in applications with paywalls or mandatory login    │
+│   ✘  No deployment in jurisdictions where decentralised         │
+│      storage or uncensored public-domain data is illegal        │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+**On the No Modification clause:** the contracts are immutable once deployed on-chain. A modified contract cannot be recalled. A mis-deployed fork could permanently corrupt member records or redirect library assets with no possibility of reversal. The prohibition is therefore not a restriction of developer freedom — it is a protection of the permanence that makes the library indestructible.
+
+**On offline rights:** the licence explicitly grants snapshot and offline deployment rights. Hard-coded contract addresses in a D-SAFE certified snapshot are legally valid in air-gapped environments (schools, bunkers, remote field operations) where no connection to the canonical config or blockchain is possible. No other open-source licence has addressed this use case directly.
+
+**On interoperability as a legal condition:** the licence prohibits forking this package to redirect the DataPond canonical models to a private, centralised database. Any institution building on `@the_library/canonical-schemas` is making a legally binding commitment to the shared canonical schema — not just a technical one. This is what makes cross-institutional data compatibility durable.
+
+---
+
+## The Ꭰ-Licence  ·  Content (D.I.C. + K)
+
+The **Ꭰ-Licence** governs the **knowledge artifacts** — books, works, records — that flow through the certified infrastructure. It is composed of two layers: the D.I.C. base licence and the K certification overlay.
+
+> The Ꭰ character is Unicode `U+13A0`, the Cherokee letter A, visually identical to a Latin capital A. AI models, OCR engines, and search crawlers read it as A. Readers who know its meaning read it as D. The double-reading is intentional: open to machines, meaningful to those who built on it. It is a philosophical mark, not a security mechanism.
+
+### D.I.C. — the base licence
+
+D.I.C. stands for **Decentralized · Integral · Common**. Each letter is a non-negotiable pillar:
+
+```
+  D  ·  Decentralized
+         Content lives on Arweave — the Permaweb.
+         Guaranteed access for 250+ years.
+         No corporate kill-switch. No server a company can pull.
+         No database an operator can delete.
+
+  I  ·  Integral
+         Zero money flow. An absolute prohibition on any extraction
+         of commercial value from the distribution of knowledge:
+
+           ✘  No advertising or sponsorships
+           ✘  No paywalls or subscriptions
+           ✘  No social media integration or engagement loops
+           ✘  No news feeds or algorithmic amplification
+
+         A pure, unmonetised distribution of knowledge. Nothing else.
+
+  C  ·  Common
+         Based on Creative Commons CC BY-NC-ND 4.0:
+           · Attribution required in all reproductions
+           · Non-Commercial — the content itself cannot generate revenue
+           · No Derivatives — no modification of certified works
+```
+
+### K — the Knowledge certification overlay
+
+D.I.C. is a licence anyone can apply to their work. The **K layer** is what earns the work the **D-SAFE label** — and it cannot be self-issued.
+
+K certification requires:
+
+1. **Submission** — the work is submitted to the D-SAFE Registry with provenance documentation
+2. **Human review** — a manual audit against the zero-tolerance exclusion checklist
+3. **Authorship verification** — confirmation of human authorship
+4. **Audit record** — a cryptographic hash of the review published permanently to Arweave
+5. **Label issuance** — the D-SAFE label is granted and the work is published under the full Ꭰ-Licence
+
+**The K layer is deliberately not automated.** No algorithm decides whether a work carries the D-SAFE label. Human review is a hard prerequisite by design. This is what distinguishes the D-SAFE certification from content moderation filters — it is a human judgement, not a classifier output.
+
+A work can carry the D.I.C. licence without the D-SAFE label. It cannot carry the D-SAFE label without passing the K review.
+
+### The D-CODE Licence — formal name
+
+The complete content licence applied to all D-SAFE certified works is formally named the **D-CODE Licence** (Digital Constitution of Open and Decentralized Ecosystems). It is the legal instrument binding publishers to the D.I.C. + K obligations:
+
+- Content must be permanently and freely accessible to all
+- Content cannot be placed behind a paywall, subscription, or access control of any kind
+- Content cannot be removed or deleted by any party, including the original publisher
+- Attribution must be preserved in all reproductions and derivatives
+- Commercial use of the content itself is prohibited; the infrastructure hosting it may be commercial
+
+The D-CODE Licence is implemented on-chain via the `BouncerStorage` smart contract on Sonic Chain (Chain ID 146). The human-readable licence text is stored alongside every certified work on Arweave — it travels permanently with the content.
+
+### The D-SAFE K.nowledge label — inherited by the smart contracts
+
+Every piece of content accepted by the DataPond contracts is D-SAFE certified before it reaches storage. The `BouncerStorage` contract enforces D-SAFE compliance at the write boundary: a record without a valid D-SAFE label is rejected and never reaches `ScientistStorage`.
+
+Because all content flowing through these contracts already carries the K certification, **the contracts themselves inherit the D-SAFE K.nowledge label**. The engine is certified D-SAFE not by declaration, but by construction.
+
+```
+  ┌────────────────────────────────────────────────────────────────┐
+  │                                                                │
+  │   Ꭰ-SAFE  ·  K.nowledge Label                                 │
+  │                                                                │
+  │   All content certified free of:                               │
+  │     · Hate speech                                              │
+  │     · Explicit material                                        │
+  │     · Environmental harm promotion                             │
+  │     · Advertising, paywalls, and social media feeds            │
+  │     · AI-generated content (human authorship required)         │
+  │                                                                │
+  │   Verified by:    dsafe.us  ·  manual human review            │
+  │   Audit record:   Arweave   ·  permanent, immutable           │
+  │   Enforced by:    BouncerStorage  ·  Sonic Chain 146          │
+  │                                                                │
+  └────────────────────────────────────────────────────────────────┘
+```
+
+The certification chain is complete and unbroken:
+
+```
+  dsafe.us human review
+    → cryptographic audit hash published to Arweave
+      → BouncerStorage gate (on-chain enforcement)
+        → ScientistStorage write
+          → Arweave content anchor (permanent)
+```
+
+Any institution reading data from these contracts can trust not just the schema (governed by this package) but the content itself. The Ꭰ-SAFE label travels with the knowledge from the moment of certification to the moment of retrieval, permanently and verifiably.
+
+Full licence text: [registry.worldbibliotech.com/licence.html](https://registry.worldbibliotech.com/licence.html)
+
+---
+
+## Related packages
+
+| Package | Role |
+|---|---|
+| [`@the_library/standard-adapters`](../standard-adapters) | Runtime StandardAdapter implementations for all standards in this package |
+| [`@the_library/db_schemas`](../db_schemas) | ORM compiler and binary codec; consumes canonical definitions at build time |
+| [`@the_library/public`](../public) — `src/models/` | TypeScript class generator; emits model classes and locale facade classes |
+| [`@the_library/public`](../public) — `src/web3/` | EVM SDK: ABI files and deployed addresses for the on-chain registry |