Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming. Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
3.0 KiB
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
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
- Validate the Page UUID.
- Canonicalize the language tag; empty becomes
und. - Hash the canonical payload with SHA-256.
- Persist the immutable Document if absent.
- Generate a new Revision UUID.
- Insert Revision metadata referencing the Document hash.
- 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:
- Explicit non-canonical language override
Accept-Languagetags in quality order- Base tag for each regional tag
- Owning Campus default
- System default
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:
{
"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
undworking projection may be returned by the Editor, while Viewer returns the existing not-found behavior.