coulomb/coulomb-social
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Record architecture decisions: thin git plane, live default, upgrades

Browse source 
D1 thin dir+git with shard-wiki then kontextual upgrade path; D2 defer
asset-store; D3 NetKingdom authz consolidation; D4 outline explode/implode
and live-by-default includes with pin as exception.
This commit is contained in:
tegwick 2026-08-13 00:48:33 +02:00
parent c27a50e6d3
commit d953aed4dd
5 changed files with 232 additions and 210 deletions
Download patch file Download diff file Expand all files Collapse all files

368
docs/architecture/ArchitectureBlueprint.md
View file

@ -2,31 +2,21 @@
| Field | Value |
|-------|--------|
| Status | **draft for discussion** (revised 2026-08-13) |
| Status | **draft — decisions recorded 2026-08-13** |
| Product | coulomb.social rebuild (`coulomb-social`) |
| Related | stage-1 cut, capability maps, substrate exploration, authoring, stale/derived |
| Non-goals | Final store vendor lock-in; full UI chrome; implementing markitect features in this doc |
| Related | stage-1 cut, capability maps, authoring, stale/derived, upgrade path |
| Non-goals | Implementing UI chrome here; full markitect feature build in this doc |
## 0. Review summary (2026-08-13)
## 0. Decision log (2026-08-13)
This revision folds in topics settled after the first draft:
| # | Topic | Decision |
|---|--------|----------|
| D1 | **Content plane** | **Start thin:** directory + markdown files, **secured in git**. Supported **upgrade path**: thin → **shard-wiki** (when wiki/federation matters) via markitect-shaped content; then → **kontextual** (structure, scale, rich media) as a **supported upgrade** of the information base. |
| D2 | **asset-store** | **Extract later.** Stage-1 may use local files next to markdown (and/or temporary blob helpers); do not block on a new repo. |
| D3 | **PolicyGateway / content authz ownership** | **Do not invent a parallel owner.** Prefer **NetKingdom consolidation** so identity *and* authorization decisioning for app resources become the obvious path (flex-auth / NK as one story). Until that lands, coulomb uses coarse product authz (session + SpaceMembership + tenant); content plane stays fail-closed when a PDP is wired. |
| D4 | **Structure UX** | Aspire to **outline-editor flexibility**: **explode** one markdown into smaller **connected** documents; **implode** selection(s) back into one file. **Default = live** (spreadsheet-like: includes/derived resolve to current inputs automatically). **Pin** only when the user freezes a snapshot. |
| Topic | Stance |
|-------|--------|
| Identity / tenants / groups | NetKingdom only |
| Deploy | Railiance |
| Content SoR | Markdown + assets; DB = cache |
| markitect | **tool** as structure lib; **not** “run on markitect”; **main** = legacy |
| Page vs chunk | **Page-first**; chunks = address / transclude / promote |
| Authoring | Top-down **and** bottom-up; no forced mode |
| Title / Abstractor / Visual | Real fields; may start **lazy**; then persist; **regenerate + lock** |
| Stale derived content | Badge → generate **alternative** → **replace or keep** |
| Includes | Live resolve **and** (proposed) pinned snapshots with same stale grammar |
| Content plane | Still open: thin store / shard-wiki / kontextual (spikes) |
| Assets | kontextual BlobStorage now; extract asset-store when 2nd consumer |
| Live Bubble | Mapped; S1 aligns with Title/Abstractor/Visual/spaces/pages/cards |
**Still open (decisions, not re-litigate principles):** content-plane pick (A/B/C), visual storage short-term, PolicyGateway owner, chunk migration strategy.
Earlier freezes (unchanged): NetKingdom identity, Railiance deploy, markdown SoR + DB cache, markitect-tool not host, page-first, dual authoring, lazy projections + lock, stage-1 cut.
---
@ -36,62 +26,66 @@ Deliver a co-creation product where:
1. **Identity** (users, groups, tenants) is **NetKingdom** — not reimplemented.
2. **Runtime** is **Railiance** — not reimplemented.
3. **User-owned content** is **markdown (+ assets)** exportable without the app database.
3. **User-owned content** is **markdown (+ assets)** in a **git-secured directory tree**, exportable without the app database.
4. The **database is a cache / projection** for cards, memberships, search speed.
5. **markitect-tool** makes markdown an efficient structured substrate (lib/CLI/API) — **not** the product host.
6. **coulomb** owns co-creation UI (cards, spaces, copy/transfer, authoring UX) and product verbs.
7. Knowledge work stays **fluent**: top-down and bottom-up authoring; structure and reuse appear when needed (transclusion, lazy projections), not as mandatory a priori chunk graphs.
5. **markitect-tool** makes markdown structured and operable (parse, include, explode/implode, later derived slots) — **not** the product host.
6. **coulomb** owns co-creation UI (cards, spaces, outline-oriented editing, copy/transfer).
7. Knowledge work stays **fluent**: top-down and bottom-up; **live** reuse by default; pin when freezing matters.
8. Growth does not strand data: **thin git base → shard-wiki → kontextual** are **supported upgrades**, not rewrites from a proprietary store.
## 2. Non-negotiable rules
| # | Rule |
|---|------|
| R1 | Markdown (frontmatter + body + backmatter) + assets are the **exportable SoR** for content. |
| R2 | App DB holds **projections and app linkage only** for content; disposable for bodies. |
| R1 | Markdown (frontmatter + body + backmatter) + assets under a **directory tree** are the **exportable SoR**. |
| R2 | App DB holds **projections and app linkage only**; disposable for content bodies. |
| R3 | Authn/IdP = **NetKingdom**; coulomb maps OIDC → Member; no password store. |
| R4 | Authz composes NetKingdom groups, app membership, content-plane ACLs — **no second user directory**. |
| R4 | Authz: prefer **NetKingdom-consolidated** decisioning; no second user directory; no permanent coulomb-specific PolicyGateway fiefdom. |
| R5 | **markitect-main** is legacy reference, not a runtime foundation. |
| R6 | **markitect-tool** is the markdown structure dependency (parse, validate, query, include, later derived slots). |
| R7 | Content plane (shard-wiki / kontextual / thin store) sits behind a **narrow PageOps** interface. |
| R6 | **markitect-tool** is the markdown structure dependency. |
| R7 | **Default content plane = thin dir+git.** PageOps hide the plane; upgrades swap adapters. |
| R8 | Stage-1 must: onboarding; spaces/pages with **Title / Abstractor / Visual**; page copy; page transfer. |
| R9 | **Pages first** — do not model documents as a priori chunk assemblies; use address/transclude/promote. |
| R10 | Derived content (projections, pinned includes, pipelines, AI) uses **stale badge → alternative → replace\|keep** and **lock**; no silent overwrite of locked/user content. |
| R9 | **Pages first** — address / live-transclude / explode-implode / promote; not a priori chunk storage. |
| R10 | **Live by default** for includes and other formula-like derived content; **pin** freezes a snapshot; pinned/stale use badge → alternative → **replace \| keep** + lock. |
| R11 | **Explode / implode** (outline-editor flexibility) are first-class structure operations (markitect primitives + coulomb UX). |
| R12 | **asset-store** extraction is **deferred**; assets may live beside markdown until then. |
## 3. System shape
```text
┌──────────────────────────┐
│ NetKingdom │
│ OIDC, groups, tenants │
│ OIDC · groups · tenants│
│ (authz consolidation →)│
└────────────┬─────────────┘
│ principal
▼
┌─────────────────────────────────────────────────────────────┐
│ coulomb.social (product) │
│ • Card UI, spaces chrome, dual authoring flows │
│ • Session / Member / SpaceMembership │
│ • PageOps + projection UX (lazy / stale / lock) │
│ • Cards, spaces, dual authoring, outline explode/implode │
│ • PageOps; live resolve; pin when asked │
│ • Railiance deploy │
└───────────────┬─────────────────────────────┬───────────────┘
│ projections │ content ops
│ cache │ PageOps
▼ ▼
┌───────────────┐ ┌───────────────────────────┐
│ App DB cache │ │ Content plane (adapter) │
│ (Postgres) │ │ A thin folder/git │
└───────────────┘ │ B shard-wiki (thin) │
│ C kontextual-engine │
│ Postgres │ │ Content plane │
│ projections │ │ ★ A thin dir + git │
└───────────────┘ │ (default / stage-1) │
│ ↗ B shard-wiki upgrade │
│ ↗ C kontextual upgrade │
└─────────────┬─────────────┘
│ structure
▼
┌───────────────────────────┐
│
┌─────────────▼─────────────┐
│ markitect-tool │
│ parse, FM, query, include │
│ derived/stale (proposed) │
│ structure · include LIVE │
│ explode/implode · query │
│ pin/derived (proposed) │
└─────────────┬─────────────┘
▼
┌───────────────────────────┐
│ Asset bytes (blobs) │
│ content-addressed │
│ Assets (files next to md) │
│ later: shared asset-store │
└───────────────────────────┘
```
@ -99,188 +93,210 @@ Deliver a co-creation product where:
| Op | Meaning |
|----|---------|
| `list_pages(space)` | Card projections |
| `get_page(id)` | Full markdown + resolved visual; optional include resolve |
| `put_page(...)` | Create/update attributes + body |
| `archive_page` | Soft-delete / lifecycle |
| `copy_page` | Independent duplicate (rewrite includes as needed) |
| `transfer_page` | Re-home to another space |
| `put_visual` / `get_asset` | Binary visual/attachment |
| `project_field` / `regenerate` / `lock` | Lazy & stale projection actions |
| `derived_refresh` | Stale include/pipeline: alternative → replace\|keep (when markitect supports) |
| `list_pages` / `get_page` / `put_page` / `archive_page` | CRUD |
| `copy_page` / `transfer_page` | Duplicate / re-home |
| `explode_page` / `implode_pages` | Outline-style split/join (markitect) |
| `resolve_view` | Live includes/derived for display (default) |
| `pin_slot` / `unpin` / `refresh_pinned` | Freeze snapshot; stale → alternative → replace\|keep |
| `project_field` / `regenerate` / `lock` | Title/abstractor/visual lifecycle |
| `put_visual` / `get_asset` | Binary next to tree (later asset-store) |
Coulomb templates/services do **not** call Forgejo/shard/kontextual APIs ad hoc — only PageOps.
### Upgrade path (supported)
```text
Stage now A dir + .md + assets (+ git)
│ markitect-tool always
│
When wiki / B same markdown becomes shard-wiki shard(s)
federation │ PageOps adapter swap; export tree still valid
│
When scale / C kontextual KnowledgeAsset + blobs
rich media / │ markdown remains portable representation
governance │ PageOps adapter swap; migration tooling required
```
**Requirement:** every upgrade **preserves user export** of markdown+assets; no dead-end proprietary body store.
## 4. Information model (product)
| Concept | Representation |
|---------|----------------|
| **Page** | Markdown: frontmatter (title, abstractor, visual, space, projections lifecycle, …) + body + backmatter |
| **Space** | Container; may be `type: space` page or container id in frontmatter |
| **Visual** | Asset ref → blob store |
| **Card** | UI only: visual + title + abstractor + actions (+ stale badges) |
| **Region / “chunk”** | Addressable unit of a page (heading, `mkt:region`, selector) — **not** a required storage type |
| **Transclusion** | Live `mkt:include` and/or pinned `mkt:derived` snapshot (proposed) |
| **Page** | One markdown file (or connected set after explode) |
| **Space** | Directory / container + metadata page |
| **Tree** | Git-secured directory layout |
| **Card** | UI projection (title, abstractor, visual, actions, stale) |
| **Outline** | Headings / exploded connected docs — **not** Bubble chunk rows |
| **Live include** | `mkt:include` resolves current source (default) |
| **Pinned derived** | Optional frozen snapshot; explicit refresh |
| **Member / tenant** | NetKingdom + app session |
### 4.1 Page-first vs Bubble chunks
### 4.1 Outline editor flexibility (explode / implode)
Live Bubble has `custom.chunk` graphs. Rebuild stance:
Aspire to outline-editor UX powered by markitect **explode / implode** (and related compose/include):
| Action | User intent | Markitect analogue |
|--------|-------------|-------------------|
| **Explode** | Split a large page into smaller **connected** documents (sections as pages or files) | `mkt explode` (+ connectivity via includes/refs) |
| **Implode** | Merge selected docs/sections **back into one** markdown file | `mkt implode` / compose |
| **Navigate outline** | Treat structure as editable hierarchy | Headings + connected pages view |
Connectivity after explode: prefer **live includes or content references** so the outline stays one logical document until the user pins or permanently severs links.
### 4.2 Live by default (spreadsheet metaphor)
| | Live (default) | Pinned (exception) |
|--|----------------|-------------------|
| Includes / formula-like derived | Resolve to **current** inputs on view/export | Stored snapshot until refresh |
| Body of a normal page | User text as written | n/a |
| Projections (title/abstractor/visual) | Lazy fill then **persist**; regenerate on demand | Lock freezes; stale offers alternative |
| Stale pinned / locked derived | — | Badge → generate alternative → **replace or keep** |
**Spreadsheet rule:** formulas stay live unless the user **pastes values** (pin).
Pinning is deliberate, not the default co-creation mode.
### 4.3 Dual authoring + lazy projections
Unchanged intent: top-down and bottom-up both natural; missing display fields lazy-fill then persist; regenerate + lock per field.
See `authoring-modes-and-lazy-projections.md`, `stale-derived-content.md`.
## 5. Content plane — decided start + upgrades
### 5.1 Default: A — thin directory + git
```text
Write fluently in a page
→ address regions when needed
→ transclude / extract / promote
→ materialize a new page only when reuse earns independence
spaces/<space-slug>/
pages/<page-slug>.md
assets/…
# entire tree in git (user- or service-mediated commits)
```
See `transclusion-and-chunks.md`. Migration may flatten Bubble chunks into sections/regions/pages+includes.
### 4.2 Dual authoring
| Mode | Flow |
|------|------|
| **Top-down** | Title → abstractor → outline (headings) → elaborate body → visual |
| **Bottom-up** | Body first; title/abstractor/visual/structure later |
No mandatory mode toggle. Empty body with metadata is valid; body-only is valid.
### 4.3 Lazy projections + lock + stale alternatives
For **title**, **abstractor**, **visual** (and similar display fields):
1. Missing on display need → **generate** (lazy) → **persist** as normal field values.
2. **Regenerate** and **lock** are per-field.
3. If inputs changed → **May be stale** → **Generate updated version** → compare Current \| Alternative → **Keep** or **Use alternative**.
Detail: `authoring-modes-and-lazy-projections.md`, `stale-derived-content.md`.
Same grammar for **pinned includes** and **pipeline/AI/rule** blocks (markitect proposal: `mkt:derived`).
## 5. Content-plane options (comparison)
### 5.1 Option A — Thin folder/git store + markitect-tool
| | |
|--|--|
| **Idea** | `.md` tree + assets; markitect validates; app indexes cards |
| **Pros** | Fastest S1; trivial export; low structure tax |
| **Cons** | Copy/transfer/versioning are app work; federation later costs more |
| **When** | Velocity first; plane maturity unclear |
| **Why** | Simplest SoR; user data is files; matches “secured in git” |
| **coulomb role** | PageOps over filesystem/git; DB indexes cards |
| **markitect role** | Parse, live include, explode/implode, validate |
### 5.2 Option B — shard-wiki (thin slice)
### 5.2 Upgrade B — shard-wiki
| | |
|--|--|
| **Idea** | Headless wiki orchestration; IdP external; coulomb = UI |
| **Pros** | Page union, git coordination, multi-shard later; INTENT names Coulomb |
| **Cons** | Structure tax if federation leaks into product; multi-tenant ops still maturing |
| **Thin-slice rule** | One InformationSpace / instance; one primary shard; hide federation from cards |
When multi-shard wiki behavior, overlays, or federation become product-relevant:
### 5.3 Option C — kontextual-engine
- Ingest the **same** markdown tree (or git repo) as a shard.
- PageOps adapter targets shard-wiki; UI unchanged.
- markitect-tool remains structure layer for resolve/explode.
| | |
|--|--|
| **Idea** | Knowledge ops: asset identity, representations, blobs, audit, workflows; markdown via markitect adapter |
| **Pros** | Blobs ready; lineage; multi-format future; PolicyGateway port |
| **Cons** | Heavier; NetKingdom not wired; must enforce markdown export as happy path |
| **Auth gap** | Map OIDC → Actor; PolicyGateway → flex-auth |
### 5.3 Upgrade C — kontextual-engine
### 5.4 Evolution (not exclusive forever)
When asset identity, scale, rich multi-format media, audit/lineage, or ECM-class governance dominate:
```text
PageOps → A or thin B/C now
→ folder/git shard can become shard-wiki
→ assets can move to kontextual / asset-store
→ markitect-tool always structure layer
```
- Supported **migration** of the information base into kontextual assets/blobs.
- Markdown remains the portable authoring/export form where applicable.
- **Not** required for stage-1.
**Working shortlist (unchanged):** spike **A** as control + **B thin** and **C** in parallel; pick after scorecard (`spike-checklist.md`).
### 5.4 What we do *not* do now
## 6. Asset management
- Do not build coulomb **on** markitect-main.
- Do not require kontextual or shard-wiki for first productive transfer.
- Do not extract **asset-store** before a second consumer (D2).
| Source | Role |
|--------|------|
| kontextual BlobStorage | Prefer for Visual/bytes now (fs/S3/memory, content-addressed) |
| markitect-main assets | Ideas only — do not runtime-depend |
| Extract `asset-store` | When **second** consumer needs same API; seed from kontextual port |
## 6. Assets (deferred extract)
Visual field stores a **ref** (path or `sha256:…`); bytes never live only in Postgres.
- Stage-1: files under `assets/` (or equivalent) in the content tree; optional simple content-addressing later.
- **asset-store** shared repo: **later** (seed from kontextual BlobStorage when extracted).
- Visual field stores a **ref** into that tree (or future store).
## 7. Identity & access control
```text
Browser → NetKingdom OIDC → coulomb session
├─ product authz: tenant_id, SpaceMembership
└─ content plane: Actor(external_ref=iss|sub, groups=…)
PolicyGateway → flex-auth (preferred)
├─ product: tenant_id, SpaceMembership (and future NK groups)
└─ long-term: NetKingdom-consolidated authz (flex-auth / NK)
so PolicyGateway ownership becomes trivial or unused
```
Fail closed on ambiguous access. Spike: OIDC → Actor → cross-tenant deny.
| Now | Target |
|-----|--------|
| Session + membership + tenant isolation | Same + NK-group claims |
| Content plane fail-closed if PDP present | PDP = consolidated NK story |
| No coulomb-owned IdP | Unchanged |
**D3:** Avoid multi-team thrash on “who owns PolicyGateway”; push consolidation in NetKingdom so apps only pass principal + resource attributes.
## 8. Deploy sketch (Railiance)
| Component | Deploy |
|-----------|--------|
| coulomb-social | Existing chart; `app.coulomb.social` |
| Content plane | In-process, sidecar, or platform service |
| Asset bytes | PVC and/or S3; secrets via env-secret pattern |
| Content tree | Volume or git-backed storage accessible to the app; **git** is SoR discipline |
| Assets | Beside markdown until asset-store |
| NetKingdom | Existing KeyCape / Authelia |
Apex DNS stays Bubble until stage-1 cut + transfer readiness.
## 9. Stage-1 product scope
## 9. Stage-1 product scope (capability cut)
**Must:**
**Must for productive transfer** (Bubble → reference-only):
- Onboarding (NetKingdom)
- Spaces/pages: Title, Abstractor, Visual, body
- Copy, transfer
- Cards; dual authoring; lazy projections
- Content as **dir+git** via PageOps
- Live includes when markitect is wired; pin optional
- Member onboarding (NetKingdom; public reg may lag via provisioned users)
- Spaces + pages with **Title, Abstractor, Visual** + markdown body
- Page **copy** and **transfer**
- Card presentation
- Dual authoring + lazy projections (at least title/abstractor); stale replace|keep preferred early
**Aspire early (structure UX):**
**Later:** social, ventures/invest, challenges marketplace, monetization, full chunk-stage machine, multi-shard personal vaults.
- Outline-oriented **explode / implode**
Live Bubble map: `docs/capability/existing-bubble-capability-map.md`.
**Later:** social, marketplace, monetization, shard-wiki/kontextual upgrades, asset-store extract.
## 10. ADR roadmap
| ADR | Topic |
|-----|--------|
| ADR-0001 | NetKingdom identity (**done**) |
| ADR-0002 | Forgejo binding — **demote** to one adapter/export shape |
| **ADR-0003** | Page-centric model + SoR + DB cache + page-first/transclusion |
| **ADR-0004** | Content-plane choice + PageOps |
| **ADR-0005** | Asset-store extraction (if/when) |
| **ADR-0006** | Authoring modes + projections + stale/derived (or fold into 0003) |
| ADR-0002 | Forgejo slice → **one optional git remote / export**, not unique SoR |
| **ADR-0003** | Page model + dir+git SoR + page-first + live default + authoring/stale |
| **ADR-0004** | PageOps + **thin plane** + **upgrade path** B/C |
| **ADR-0005** | asset-store extraction (**later**) |
| — | NetKingdom authz consolidation (NK work, not coulomb-owned forever) |
Markitect-tool: implement `proposed-stale-derived-and-include-pinning.md` as its own work.
Markitect-tool: live include (done), explode/implode (done), pin/derived proposal (`proposed-stale-derived-and-include-pinning.md`).
## 11. Spike checklist
## 11. Spikes (narrowed)
See **[spike-checklist.md](./spike-checklist.md)**.
Add when scheduling: dual-authoring smoke, stale projection compare UX, include pin (after markitect).
With D1–D4, prioritize:
## 12. Discussion prompts (remaining)
1. **Thin tree layout + git write path** (PageOps on files).
2. **markitect** parse + **live** include in get/view.
3. **Explode/implode** UX prototype on real pages.
4. **Lazy title/abstractor** + stale replace\|keep.
5. Export zip/tar of tree without DB.
1. Content plane for next 3–6 months: **A velocity**, **B federation path**, or **C governance/blobs**?
2. Visual: kontextual/local blob first, or block on asset-store extract?
3. PolicyGateway production owner?
4. Bubble **chunk** migration: sections/regions only, or keep a chunk list UX as a *view*?
5. Default include mode in product: **live** vs **pinned** for shared excerpts?
Defer deep shard-wiki/kontextual spikes except **export/import round-trip sketches** that prove upgrade feasibility.
## 13. Working recommendation (principles frozen; plane open)
Full list remains in `spike-checklist.md` (update scorecard: A = chosen start).
| Layer | Recommendation |
|-------|----------------|
| Product UI | coulomb cards + spaces + dual authoring |
| Markdown structure | markitect-tool (includes + future derived slots) |
| Identity / deploy | NetKingdom / Railiance |
| Content plane | Spike A+B+C; choose with export fidelity as hard constraint |
| SoR | Markdown export always works; engines add IDs/lineage without trapping content |
| Assets | kontextual blobs now; extract later if shared |
| Chunks | Transclusion/extract, not a priori graph |
| Derived/stale | Badge → alternative → replace\|keep + lock |
## 12. Closed discussion prompts
| Prompt | Resolution |
|--------|------------|
| A vs B vs C for start | **A**; B/C = supported upgrades |
| asset-store now? | **Later** |
| PolicyGateway owner | **Consolidate under NetKingdom**; don’t fork ownership |
| Chunk UX | **Outline editor + explode/implode**, not chunk tables |
| Live vs pin default | **Live**; pin is explicit |
---
## 13. Working recommendation (frozen)
| Layer | Decision |
|-------|----------|
| Product UI | coulomb cards, spaces, outline explode/implode, dual authoring |
| Markdown structure | markitect-tool; **live** includes by default |
| Identity / deploy | NetKingdom / Railiance; authz → NK consolidation |
| Content plane | **Thin dir + git** now |
| Upgrades | → shard-wiki → kontextual (supported, markdown-preserving) |
| Assets | Beside tree now; **asset-store later** |
| Derived/stale | Live default; pin + badge → alternative → replace\|keep |
| markitect-main | Avoid |
---
@ -301,7 +317,7 @@ Add when scheduling: dual-authoring smoke, stale projection compare UX, include
### fleet
- kontextual: architecture-blueprint, asset-registry, blob-storage, markitect reuse boundary
- shard-wiki: INTENT, SCOPE
- markitect-tool: transform-compose-include, content-references, cache-incremental, **proposed-stale-derived-and-include-pinning.md**
- markitect-main: successor-gap-assessment (legacy)
- markitect-tool: transform-compose-include, explode-implode, content-references, **proposed-stale-derived-and-include-pinning.md**
- shard-wiki: INTENT (Coulomb as consumer; upgrade target)
- kontextual: blob-storage, asset-registry (upgrade + later asset-store seed)
- markitect-main: successor-gap (legacy only)

35
docs/architecture/spike-checklist.md
View file

@ -150,32 +150,23 @@ Scoring legend for each spike: **Pass** / **Partial** / **Fail** / **Skip** with
---
## Spike 8 — Cross-option decision workshop
## Spike 8 — Decision workshop → **mostly closed 2026-08-13**
**Owner:** founder + implementers
**Depends on:** Spikes 1–6 results
**Recorded in ArchitectureBlueprint §0 (D1–D4):**
- [ ] Fill scorecard (below).
- [ ] Choose primary content plane for stage 1 + migration path.
- [ ] Choose asset strategy (in-kontextual vs extract vs folder-only).
- [ ] File ADR-0003 (page model + SoR) and ADR-0004 (content plane).
- [ ] Update `docs/capability/model-v0.yaml` feature wording if PageOps replaces Forgejo-centric features.
| Item | Decision |
|------|----------|
| Content plane start | **A** thin dir + git |
| Upgrades | → shard-wiki → kontextual (supported) |
| asset-store | **Later** |
| Authz ownership | **NetKingdom consolidation** (avoid parallel PolicyGateway fiefdom) |
| Structure UX | Outline **explode/implode**; **live** default; pin exception |
### Scorecard (1–5, higher better)
Remaining workshop work:
| Criterion | A thin store | B shard-wiki | C kontextual |
|-----------|:------------:|:------------:|:------------:|
| Markdown export fidelity | | | |
| Stage-1 speed | | | |
| Structure tax (inverse) | | | |
| Copy/transfer naturalness | | | |
| Visual/blob readiness | | | |
| NetKingdom/authz fit | | | |
| Multi-shard / federation later | | | |
| Multi-format / ECM later | | | |
| Railiance operability | | | |
| Aligns with fleet layers | | | |
| **Total** | | | |
- [ ] File ADR-0003 / ADR-0004 reflecting D1–D4.
- [ ] Sketch export/import round-trip notes for B and C upgrades (feasibility only).
- [ ] Explode/implode UX prototype on thin tree (Spike 2 + markitect).
---

16
docs/architecture/stale-derived-content.md
View file

@ -118,20 +118,22 @@ Same for abstractor and visual (visual compare: two images or image vs placehold
Two legitimate modes (both needed):
### A. Live resolve (dynamic)
### A. Live resolve (dynamic) — **product default**
```markdown
<!-- mkt:include path="src.md" selector="sections[heading=API]" -->
```
At render/export, markitect resolves from **current** `src.md`.
“Stale” is less about the marker and more about **viewer cache**.
Still useful: badge if **last rendered snapshot** ≠ current resolve hash
(for offline cards that show a cached excerpt).
At render/export, markitect resolves from **current** `src.md`
(**spreadsheet-like**: formula results stay up to date).
### B. Pinned / materialised include (snapshot in host page)
“Stale” for pure live includes is mostly **viewer/cache** (optional badge if
a cached card excerpt lags live resolve). No replace/keep needed unless the
host cached a display snapshot.
For “user owns a frozen copy but can refresh”:
### B. Pinned / materialised include (snapshot in host page) — **exception**
For “freeze this excerpt / paste values” (explicit pin):
```markdown
<!-- mkt:derived id="api-excerpt"

8
docs/architecture/transclusion-and-chunks.md
View file

@ -172,10 +172,12 @@ then pin/freeze excerpts when “my version vs live source” matters.
| Mode | Behavior |
|------|----------|
| Live `mkt:include` | Always resolve current source at render |
| Pinned `mkt:derived` (proposed) | Store snapshot; badge when source/inputs change; user generates alternative and chooses replace or keep |
| **Live** `mkt:include` (**default**) | Always resolve current source — spreadsheet-like |
| **Pinned** `mkt:derived` (proposed) | Explicit freeze; badge when inputs change; alternative → replace \| keep |
Both are valid; co-creation often wants **pin + explicit refresh**.
**Product default is live.** Pin only when the user freezes a value.
Outline flexibility uses **explode / implode** into connected docs with live
links, not a priori chunk tables.
---

15
docs/capability/model-v0.yaml
View file

@ -121,9 +121,20 @@ capabilities:
title: Stale badge with generate alternative then replace or keep
status: todo
notes: "docs/architecture/stale-derived-content.md; markitect derived slots"
- id: feat.derived-include-pin
title: Pinned include/pipeline snapshots with same stale/replace grammar
- id: feat.include-live-default
title: Live includes by default (spreadsheet-like up-to-date resolve)
status: todo
- id: feat.derived-include-pin
title: Optional pin; stale badge with generate alternative then replace or keep
status: todo
- id: feat.outline-explode-implode
title: Outline-editor explode into connected docs and implode back
status: todo
notes: "markitect explode/implode; ArchitectureBlueprint D4"
- id: feat.content-plane-thin-git
title: Content SoR as directory + markdown files in git
status: todo
notes: "Upgrades to shard-wiki then kontextual supported later"
- id: feat.content-fail-closed
title: Fail closed on missing binding/fetch
status: shipped