Files
pages/docs/design/revision-language-model.md
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

105 lines
3.0 KiB
Markdown

# 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.