# Revision and Language Projection Detailed Design ## Status Implemented. SQLite `body` remains a transitional compatibility cache while the canonical payload is read from `documents/sha256/`. ## Invariants ```text Semantic Path != Page UUID Page UUID != Revision UUID Revision UUID != Document SHA-256 Language != Semantic Path ``` - A Page is language-neutral. - A Revision is immutable and belongs to exactly one Page. - A Revision references exactly one immutable Document payload. - The same Document hash may be referenced by many Pages, languages, or Revisions. - Saving identical content may create a new Revision event without duplicating the Document payload. ## Metadata schema ### `revisions` | Column | Constraint | Meaning | | --- | --- | --- | | `uuid` | primary key | Revision UUID | | `object_uuid` | required | Parent Page UUID | | `document_hash` | required | Lowercase SHA-256 payload hash | | `lang` | required, default `und` | Canonical BCP 47 tag | | `body` | transitional | Compatibility copy until filesystem migration | | `message` | optional | Commit message | | `created_at_ms` | required | Ordering timestamp | | `created_at` | transitional | Legacy seconds timestamp | `object_uuid` is retained during the broader Object-to-Page vocabulary migration. New code treats it as Page identity. ## Save transaction 1. Validate the Page UUID. 2. Canonicalize the language tag; empty becomes `und`. 3. Hash the canonical payload with SHA-256. 4. Persist the immutable Document if absent. 5. Generate a new Revision UUID. 6. Insert Revision metadata referencing the Document hash. 7. Commit metadata only after Document persistence succeeds. During the compatibility phase, step 4 also stores `body` in SQLite. The content-addressed file under `documents/sha256/` is canonical; removing the compatibility column is a later schema cleanup and does not change Revision UUIDs or hashes. ## Language selection Candidate order: 1. Explicit non-canonical language override 2. `Accept-Language` tags in quality order 3. Base tag for each regional tag 4. Owning Campus default 5. System default 6. `und` Candidates are canonical BCP 47 tags, deduplicated in order. Selection returns the newest Revision for the first candidate that exists. ## Compatibility migration For every legacy Revision: - preserve its existing `uuid`; - set `document_hash = sha256(body)`; - set `lang = und`; - set `created_at_ms = created_at * 1000`. New Revision UUIDs are random UUIDs. Legacy hash-shaped Revision identifiers remain resolvable indefinitely. ## API Revision save accepts: ```json { "object_uuid": "page UUID", "body": "canonical payload", "message": "manual-save", "lang": "ja-JP" } ``` Responses include both the Revision UUID and Document hash. ## Failure behavior - Invalid language tags return a client error. - Unknown Page UUIDs are rejected. - Missing requested languages fall through; they are not errors. - If no candidate exists, an empty `und` working projection may be returned by the Editor, while Viewer returns the existing not-found behavior.