Files
pages/docs/design/address-model.md
T
Anya Tokugawa c1175d389f 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.
2026-09-27 14:44:43 +09:00

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