Files
pages/docs/design/revision-language-model.md
T
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
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.
2026-09-27 14:44:43 +09:00

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

  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:

{
  "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.