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

666 lines
7.7 KiB
Markdown

# Access Model draft
## Goal
Separate:
```text
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:
```text
authoring projections
```
onto canonical semantic object structures.
Canonical storage is:
```text
DOM/object graph centered
```
depending on object class.
# High-Level Access Architecture
```mermaid
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
```text
/research/network/bgp
/dev/api/auth
/hr/onboarding
```
# Responsibilities
- semantic routing
- hierarchy traversal
- language negotiation
- capability evaluation
- object resolution
# Output
Usually:
```text
rendered semantic projection
```
# Resolution Pipeline
```text
path
↓
uuid
↓
revision
↓
projection
```
# Important Principle
Knowledge access is:
```text
human semantic navigation
```
NOT raw object retrieval.
# 2. Projection Access
## Purpose
Interpret semantic objects into runtime surfaces.
# Example
```text
/_/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:
```text
runtime interpretation
```
NOT canonical storage.
# Same Object, Multiple Projections
```mermaid
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:
```text
projection-specific authoring surfaces
```
NOT canonical storage owners.
* * *
# Editor Pipeline
```mermaid
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:
```text
semantic object graph
```
or:
```text
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
```text
HTML article
```
Available editors:
- Markdown
- WYSIWYG
- Raw HTML
* * *
# Example
```text
Presentation object
```
Available editors:
- Slide editor
- Raw DOM editor
* * *
# Example
```text
Spreadsheet object
```
Available editors:
- Sheet runtime editor
- Native Excel integration
* * *
# 4. Object Access
## Purpose
Raw immutable object retrieval.
* * *
# Example
```text
/_/obj/sha256:abcd
```
* * *
# Typical Objects
- PDF
- PPTX
- XLSX
- PNG
- SVG
- JS
- CSS
- DrawIO payload
- Excalidraw payload
* * *
# Important Principle
Object access is:
```text
transport/storage retrieval
```
NOT semantic navigation.
* * *
# Object Access Pipeline
```mermaid
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
```mermaid
graph TD
LINK[Semantic Link]
RES[Resolver]
NATIVE[Native Handler]
WEB[Web Fallback]
LINK --> RES
RES --> NATIVE
RES --> WEB
```
* * *
# Important Principle
Links represent:
```text
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:
```text
workspace objects
```
Revisions store:
```text
immutable semantic snapshots
```
* * *
# 7. Canonical Storage Principle
Canonical storage depends on object class.
* * *
# Flow Articles
Canonical form:
```text
HTML DOM
```
* * *
# Presentation Objects
Canonical form:
```text
presentation object graph
```
Projected into:
- SVG sections
- HTML slides
- print layouts
* * *
# Spreadsheet Objects
Canonical form:
```text
structured semantic table graph
```
Projected into:
- HTML tables
- spreadsheet runtime
- CSV
- print layouts
* * *
# Canvas/Whiteboard Objects
Canonical form:
```text
spatial object graph
```
Projected into:
- SVG
- interactive canvas
- thumbnails
* * *
# Important Principle
Projection-specific formats are:
```text
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
```html
<embedded-object
kind="drawio"
immutable-ref="sha256:abcd"
></embedded-object>
```
* * *
# Important Principle
Large payloads should generally use:
```text
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
```text
/research/network/bgp
```
may contain:
```text
teams://
mailto:
vscode://
figma://
tel:
```
runtime-aware semantic links.
* * *
# 10. Final Architectural Direction
Pages Wiki evolves toward:
```text
semantic knowledge runtime environment
```
rather than:
```text
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:
```text
meaning
identity
projection
editing
storage
runtime execution
```
into independent architectural planes.