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,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
|
||||
```
|
||||
Reference in new issue
Block a user