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.
8.3 KiB
Address Model Draft
Goal
Separate:
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
Address != Meaning
Addresses are:
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
/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:
semantic navigation surfaces
NOT canonical object identities.
Resolution Flow
path
↓
uuid
↓
revision
↓
projection
2. uuid:
Purpose
Stable semantic object identity.
Example
uuid:550e8400-e29b-41d4-a716-446655440000
Properties
Property Value mutable no semantic no canonical identity yes stable yes
Important Principle
UUIDs are:
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
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:
immutable object references only
Forbidden
revision -> mutable asset HEAD
Allowed
revision -> sha256 immutable snapshot
4. sha256:
Purpose
Immutable content-addressed object identity.
Example
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:
historical truth
5. asset:
The normative lifecycle, freezing, authorization, and retention rules are in
asset-model.md.
Purpose
Mutable editable workspace object.
Example
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:
current editable HEAD
Save Flow
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:
semantic continuity of editing
NOT immutable historical truth.
6. alias:
Purpose
Semantic indirection pointer.
Example
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
share:abcdef
Typical Projection
/s/abcdef
Properties
Property Value temporary usually delegated yes capability-bound yes
Internal Model
Share addresses usually resolve to:
macaroon delegated capability
8. derived:
Purpose
Generated/transformed object identity.
Example
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
external:gdrive:file123
external:figma:abcd
external:slack:thread456
Properties
Property Value foreign ownership yes mutability external-defined projection-capable yes
Runtime Resolution Pipeline
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
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.
Raw Document Projection
Raw payload delivery is a projection, not another identity namespace. The HTTP form therefore carries an explicit internal address:
/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:
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:
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:
semantic knowledge routing
+
immutable object graph
+
projection-oriented rendering
+
capability-based reachability
rather than:
filesystem-oriented page hierarchy