feat: documents and session tokens

sql/README.md

@@ -0,0 +1,40 @@
+# SQL
+
+Table definitions for the database form of packages, a team's store, and the bundle.
+
+| File | Holds | Runs on |
+| --- | --- | --- |
+| `doc.sql` | Documents: works, documents, witnesses, nodes, pages, locations, references, citations, corrections, IDs, receipts, revocations, suspects and package files. | SQLite, Dolt, PostgreSQL |
+| `store.sql` | What a team adds: roster keys, projects, members, reading paths, layers, annotations, datasets, digitizations, views, policies, submissions and grades. Load `doc.sql` first. | SQLite, Dolt, PostgreSQL |
+| `bundle-sqlite.sql` | The bundle's extra tables: metadata, a full-text index (FTS5) and room for embeddings. Load both files above first. | SQLite |
+
+## Creating a database
+
+```sh
+sqlite3 lab.db < sql/doc.sql && sqlite3 lab.db < sql/store.sql
+psql -d lab -f sql/doc.sql && psql -d lab -f sql/store.sql
+dolt sql < sql/doc.sql && dolt sql < sql/store.sql
+```
+
+To load packages into SQLite with nothing installed, use `python3 tools/load.py --sqlite lab.db PACKAGE…`; [docs/examples.md](../docs/examples.md#load-packages-into-sqlite) has queries to try.
+
+## Conventions
+
+- No foreign keys: validators check references, so the same file runs everywhere.
+- Enumerations are `VARCHAR` with a `CHECK`; JSON values are canonical JSON in `TEXT`; booleans are `INTEGER` 0 or 1.
+- No table, column or index name is reserved in any of the three engines, so the formats' `key`, `index`, `at`, `by`, `before` and `after` become `doc_key`, `idx`, `made_at`, `signer`, `before_hash` and `after_hash`.
+- Each row keeps every property of its record, so a package loaded into the tables unloads back to the same bytes.
+- `citations`, `receipt_nodes` and `annotation_targets` are derived on load, for queries.
+
+## A first query
+
+Every sentence that cites a given reference, which is the citation's context:
+
+```sql
+SELECT c.sentence
+FROM citations c
+JOIN refs r ON r.doc_key = c.doc_key AND r.node = c.ref_node
+WHERE c.doc_key = 'hale2026harmonic' AND r.label = '2';
+```
+
+[Chapter 13](../spec/13-database.md) defines the mapping from files to tables.