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.
666 lines
7.7 KiB
Markdown
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.
|