Files
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

7.7 KiB

Access Model draft

Goal

Separate:

knowledge navigation
projection rendering
editing surfaces
object retrieval
native execution

into independent runtime layers.

The system treats:

content != rendering != editor != storage

as a core architectural principle.

Core Principle

Pages Wiki does NOT treat editors as canonical reality.

Editors are:

authoring projections

onto canonical semantic object structures.

Canonical storage is:

DOM/object graph centered

depending on object class.

High-Level Access Architecture

graph TD

KA[Knowledge Access]
PA[Projection Access]
EA[Editing Access]
OA[Object Access]
NA[Native Access]

KA --> PA
PA --> EA

PA --> OA
EA --> OA

PA --> NA
EA --> NA

1. Knowledge Access

Purpose

Semantic navigation for humans.

Example

/research/network/bgp
/dev/api/auth
/hr/onboarding

Responsibilities

  • semantic routing
  • hierarchy traversal
  • language negotiation
  • capability evaluation
  • object resolution

Output

Usually:

rendered semantic projection

Resolution Pipeline

path
 ↓
uuid
 ↓
revision
 ↓
projection

Important Principle

Knowledge access is:

human semantic navigation

NOT raw object retrieval.

2. Projection Access

Purpose

Interpret semantic objects into runtime surfaces.

Example

/_/view/flow/uuid:abcd
/_/view/slides/uuid:abcd
/_/view/sheet/uuid:abcd
/_/view/print/uuid:abcd
/_/view/canvas/uuid:abcd

Projection Examples

Projection Meaning
flow Flowing article
slides Staged presentation
print Printable layout
sheet Spreadsheet runtime
canvas Whiteboard/canvas
topology Graph topology
preview Lightweight rendering

Important Principle

Projection is:

runtime interpretation

NOT canonical storage.

Same Object, Multiple Projections

graph TD

OBJ[Semantic Object]

FLOW[Flow Projection]
SLIDE[Slides Projection]
PRINT[Print Projection]
SHEET[Sheet Projection]

OBJ --> FLOW
OBJ --> SLIDE
OBJ --> PRINT
OBJ --> SHEET

3. Editing Access

Purpose

Provide authoring surfaces.


Important Principle

Editors are:

projection-specific authoring surfaces

NOT canonical storage owners.


Editor Pipeline

graph TD

EDITOR[Editor]
AST[Semantic Object Graph]
REV[Revision Snapshot]

EDITOR --> AST
AST --> REV

Supported Editors

Editor Purpose
Markdown Lightweight flow editing
WYSIWYG Visual article editing
Raw HTML Direct DOM editing
Slide Editor Presentation authoring
Sheet Editor Spreadsheet runtime editing
Whiteboard Editor Canvas editing
DrawIO-like Editor Topology editing

Important Principle

All editors ultimately produce:

semantic object graph

or:

canonical DOM representation

depending on object class.


Editor Negotiation

Runtime selects editor based on:

  • object class
  • supported projection types
  • runtime capabilities
  • user preferences
  • available native integrations

Example

HTML article

Available editors:

  • Markdown
  • WYSIWYG
  • Raw HTML

Example

Presentation object

Available editors:

  • Slide editor
  • Raw DOM editor

Example

Spreadsheet object

Available editors:

  • Sheet runtime editor
  • Native Excel integration

4. Object Access

Purpose

Raw immutable object retrieval.


Example

/_/obj/sha256:abcd

Typical Objects

  • PDF
  • PPTX
  • XLSX
  • PNG
  • SVG
  • JS
  • CSS
  • DrawIO payload
  • Excalidraw payload

Important Principle

Object access is:

transport/storage retrieval

NOT semantic navigation.


Object Access Pipeline

graph TD

OBJREF[Object Reference]
FETCH[Object Fetch]
CACHE[Cache/CDN]
RETURN[Runtime Consumer]

OBJREF --> FETCH
FETCH --> CACHE
CACHE --> RETURN

Important Principle

Object retrieval supports:

  • deduplication
  • CDN caching
  • immutable references
  • snapshot reproducibility
  • derived object generation

5. Native Access

Purpose

Bridge semantic objects into local/native applications.

Implementation status: TODO. The current integration-adapter runtime only permits hosted HTTP(S) viewers and editors. Direct executable launch requires a separately designed local helper, temporary workspace, credential store, executable allowlist, conflict detection, and Revision write-back protocol.


Example

Semantic Link Native Projection
teams.office.com msteams://
mailto: Mail client
tel: Dialer
vscode:// VS Code
figma:// Figma
slack:// Slack

Native Resolution Pipeline

graph TD

LINK[Semantic Link]
RES[Resolver]
NATIVE[Native Handler]
WEB[Web Fallback]

LINK --> RES

RES --> NATIVE
RES --> WEB

Important Principle

Links represent:

semantic execution intent

NOT fixed transport mechanisms.


Runtime chooses:

  • native app
  • browser fallback
  • embedded projection
  • external mounted surface

depending on environment.


6. Workspace Plane vs Revision Plane

Workspace Plane

Mutable editing world.

Contains:

  • path
  • alias
  • asset
  • live editors

Revision Plane

Immutable historical world.

Contains:

  • revision
  • sha256 snapshots
  • derived projections

Important Principle

Editors operate on:

workspace objects

Revisions store:

immutable semantic snapshots

7. Canonical Storage Principle

Canonical storage depends on object class.


Flow Articles

Canonical form:

HTML DOM

Presentation Objects

Canonical form:

presentation object graph

Projected into:

  • SVG sections
  • HTML slides
  • print layouts

Spreadsheet Objects

Canonical form:

structured semantic table graph

Projected into:

  • HTML tables
  • spreadsheet runtime
  • CSV
  • print layouts

Canvas/Whiteboard Objects

Canonical form:

spatial object graph

Projected into:

  • SVG
  • interactive canvas
  • thumbnails

Important Principle

Projection-specific formats are:

runtime surfaces

NOT canonical storage truth.


8. Embedded Object Model

Embedded objects may be:

Type Meaning
Inline Embedded payload
Linked Immutable external object
Mounted Live external application
Derived Generated projection
Lazy Runtime-fetched object

Example

<embedded-object
  kind="drawio"
  immutable-ref="sha256:abcd"
></embedded-object>

Important Principle

Large payloads should generally use:

external immutable object references

instead of giant inline blobs.


9. Semantic Link Model

Semantic links may resolve into:

  • knowledge paths
  • projections
  • native applications
  • external services
  • embedded runtimes

Example

/research/network/bgp

may contain:

teams://
mailto:
vscode://
figma://
tel:

runtime-aware semantic links.


10. Final Architectural Direction

Pages Wiki evolves toward:

semantic knowledge runtime environment

rather than:

filesystem-oriented wiki

Conceptual Summary

Layer Responsibility
Knowledge Access Semantic navigation
Projection Access Runtime interpretation
Editing Access Authoring surfaces
Object Access Immutable retrieval
Native Access Local runtime execution

Final Principle

Pages Wiki separates:

meaning
identity
projection
editing
storage
runtime execution

into independent architectural planes.