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.
This commit is contained in:
1 parent
288e6e94ac
commit
c1175d389f
699 files changed
+110197
-4117
No files matched your search
@@ -0,0 +1,104 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user