# 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/` 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 ```