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:
Anya Tokugawa committed 2026-09-27 14:44:43 +09:00
1 parent 288e6e94ac
commit c1175d389f
699 files changed
+110197 -4117

No files matched your search

+644
View File
@@ -0,0 +1,644 @@
# Address Model Draft
## Goal
Separate:
```text
identity
reachability
semantic meaning
projection
mutability
```
into independent address layers.
The addressing model is designed to support:
- semantic navigation
- immutable revisions
- mutable editing workspaces
- object storage
- projection rendering
- delegated sharing
- graph-capable knowledge topology
## Core Principle
```text
Address != Meaning
```
Addresses are:
```text
reachable locators
```
NOT semantic meaning themselves.
* * *
# Address Layer Overview
| Scheme | Purpose | Mutable | Human-oriented |
| --- | --- | --- | --- |
| `path:` | Semantic navigation | yes | yes |
| `uuid:` | Stable Page/Object identity | no | partially |
| `rev:` | Immutable historical snapshot | no | no |
| `sha256:` | Immutable content identity | no | no |
| `asset:` | Mutable editable workspace | yes | partially |
| `alias:` | Semantic pointer | yes | yes |
| `share:` | Delegated capability projection | caveat-bound | yes |
| `derived:` | Generated object | preferably no | no |
| `external:` | Foreign mounted object | provider-defined | partially |
* * *
# 1. path:
## Purpose
Human semantic routing namespace.
* * *
# Example
```text
/research/network/bgp
/dev/api/auth
/hr/onboarding
```
* * *
# Properties
Property Value mutable yes human-readable yes semantic yes canonical identity no
* * *
# Important Principle
Paths are:
```text
semantic navigation surfaces
```
NOT canonical object identities.
* * *
# Resolution Flow
```text
path
↓
uuid
↓
revision
↓
projection
```
* * *
# 2. uuid:
## Purpose
Stable semantic object identity.
* * *
# Example
```text
uuid:550e8400-e29b-41d4-a716-446655440000
```
* * *
# Properties
Property Value mutable no semantic no canonical identity yes stable yes
* * *
# Important Principle
UUIDs are:
```text
opaque reachable locators
```
NOT semantic meaning.
* * *
# UUID Targets
UUID may identify:
- HTML document object
- PDF semantic object
- Spreadsheet object
- DrawIO semantic object
- Presentation object
- Embedded semantic object
* * *
# Important Principle
UUID does NOT imply rendering format.
Projection decides interpretation.
* * *
# 3. rev:
## Purpose
Immutable historical semantic snapshot.
* * *
# Example
```text
rev:018f6b5d...
```
* * *
# Properties
Property Value immutable yes historical yes reproducible yes
* * *
# Revision Responsibilities
A revision freezes:
- HTML structure
- embedded object references
- semantic state
- projection state
A Revision has its own UUID. Immutable payload identity is represented
separately by `sha256:`. A Revision record links a Page UUID, language tag,
Document hash, authoring metadata, and creation time.
* * *
# Important Principle
Revisions MUST reference:
```text
immutable object references only
```
* * *
# Forbidden
```text
revision -> mutable asset HEAD
```
* * *
# Allowed
```text
revision -> sha256 immutable snapshot
```
* * *
# 4. sha256:
## Purpose
Immutable content-addressed object identity.
* * *
# Example
```text
sha256:deadbeef...
```
* * *
# Properties
Property Value immutable yes content-addressed yes deduplicatable yes cacheable yes
* * *
# Typical Targets
- DrawIO payload
- Excalidraw payload
- PDF binary
- Image
- CSS snapshot
- JS snapshot
- PPTX binary
- XLSX binary
* * *
# Important Principle
sha256 objects are:
```text
historical truth
```
* * *
# 5. asset:
The normative lifecycle, freezing, authorization, and retention rules are in
[`asset-model.md`](asset-model.md).
## Purpose
Mutable editable workspace object.
* * *
# Example
```text
asset:drawio:network-core
asset:xlsx:q1-budget
asset:slide:roadmap
```
* * *
# Properties
Property Value mutable yes editable yes workspace-oriented yes
* * *
# Important Principle
Assets represent:
```text
current editable HEAD
```
* * *
# Save Flow
```text
asset mutable HEAD
↓
save
↓
snapshot
↓
sha256 immutable object
```
For HTML Revisions, supported embedding attributes containing an `asset:`
address are resolved at save time. Unresolved Asset HEADs reject the save.
* * *
# Important Principle
Asset identity represents:
```text
semantic continuity of editing
```
NOT immutable historical truth.
* * *
# 6. alias:
## Purpose
Semantic indirection pointer.
* * *
# Example
```text
alias:latest-network-design
```
* * *
# Properties
Property Value mutable yes semantic yes canonical no
* * *
# Typical Uses
- latest stable design
- current handbook
- canonical public URL
- migration pointer
* * *
# 7. share:
## Purpose
Delegated capability projection.
* * *
# Example
```text
share:abcdef
```
* * *
# Typical Projection
```text
/s/abcdef
```
* * *
# Properties
Property Value temporary usually delegated yes capability-bound yes
* * *
# Internal Model
Share addresses usually resolve to:
```text
macaroon delegated capability
```
* * *
# 8. derived:
## Purpose
Generated/transformed object identity.
* * *
# Example
```text
derived:thumbnail:sha256:abcd
derived:ocr:sha256:abcd
derived:preview-svg:sha256:abcd
```
* * *
# Properties
Property Value generated yes reproducible usually immutable preferred
* * *
# Typical Derived Objects
- thumbnails
- OCR text
- SVG previews
- rendered PDF pages
- AI summaries
- embeddings
* * *
# 9. external:
## Purpose
Mounted foreign object reference.
* * *
# Example
```text
external:gdrive:file123
external:figma:abcd
external:slack:thread456
```
* * *
# Properties
Property Value foreign ownership yes mutability external-defined projection-capable yes
* * *
# Runtime Resolution Pipeline
```text
path
↓
uuid
↓
revision
↓
projection
↓
embedded object resolution
↓
sha256 / asset / external
↓
renderer
```
* * *
# Projection Principle
## Address != Rendering
Rendering is determined by:
- mime type
- object class
- projection adapter
- user context
- runtime capability
* * *
# Example
```text
uuid:abcd
```
may render as:
- HTML article
- PDF viewer
- slide deck
- spreadsheet runtime
- whiteboard canvas
depending on projection adapter.
The adapter contract, bounded-delivery rules, and structured-format roadmap
are defined in [projection-adapters.md](projection-adapters.md).
* * *
## Raw Document Projection
Raw payload delivery is a projection, not another identity namespace. The
HTTP form therefore carries an explicit internal address:
```text
/v/raw/path:/manual/report
/v/raw/uuid:550e8400-e29b-41d4-a716-446655440000
/v/raw/rev:018f6b5d...
```
Viewer embeds `path:` when displaying the current semantic projection.
Immutable Revision Viewer embeds `rev:`. A bare `/raw/<semantic-path>` is
forbidden because it conflates projection, reachability, and identity.
## Path Rename
Rename changes reachability, not Page identity. It is committed atomically as:
```text
link(new-path, existing-page-uuid)
unlink(old-path, existing-page-uuid)
```
Recursive rename applies the same mapping to every descendant in one database
transaction. Destination collisions abort the entire operation. When the
basename of an extension-bearing file changes, the latest language projections
receive a new Revision carrying the new `filename`; older Revisions remain
immutable.
* * *
# Mutability Model
| Layer | Mutable |
| --- | --- |
| `path:` | yes |
| `alias:` | yes |
| `asset:` | yes |
| `uuid:` | no |
| `rev:` | no |
| `sha256:` | no |
| `derived:` | preferably no |
* * *
# Important Separation
## Workspace Plane
Mutable editing world.
Contains:
- asset:
- path:
- alias:
* * *
# Revision Plane
Immutable historical world.
Contains:
- rev:
- sha256:
- derived:
* * *
# Core Architectural Principle
Pages Wiki separates:
```text
semantic navigation
identity
content storage
projection
editing
history
```
into independent planes.
* * *
# Conceptual Summary
| Layer | Responsibility |
| --- | --- |
| `path:` | Semantic routing |
| `uuid:` | Stable Page/Object identity |
| `rev:` | Historical snapshot identity |
| `sha256:` | Immutable content reality |
| `asset:` | Mutable editing continuity |
| Projection | Runtime interpretation |
| Capability | Authorized reachability |
* * *
# Final Conceptual Direction
Pages Wiki evolves toward:
```text
semantic knowledge routing
+
immutable object graph
+
projection-oriented rendering
+
capability-based reachability
```
rather than:
```text
filesystem-oriented page hierarchy
```