From 27ba9206f769af10f915c4cc53f86bc8921eac92 Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 12 Aug 2026 18:29:29 +0200 Subject: [PATCH] Document content substrate: markdown SoR, markitect-tool, shard-wiki Capture preferred layering (NetKingdom, Railiance, coulomb UI, markitect-tool as markdown lib, DB as cache). Treat markitect-main as legacy; evaluate shard-wiki as thin-slice content plane candidate. --- INTENT.md | 1 + ...026-08-12-content-substrate-exploration.md | 165 ++++++++++++++++++ docs/capability/stage-1-cutover.md | 7 +- 3 files changed, 170 insertions(+), 3 deletions(-) create mode 100644 docs/architecture/2026-08-12-content-substrate-exploration.md diff --git a/INTENT.md b/INTENT.md index ee47835..f4ee860 100644 --- a/INTENT.md +++ b/INTENT.md @@ -82,6 +82,7 @@ The rebuild is deliberately **product-faithful first**: UI and content parity ma - `docs/resource-evidence/` — workload demand forecasts, observations, labor - `docs/capability/` — product capability/feature model; stage-1 cutover must set - `docs/decisions/2026-08-12-feature-cut-stage-1.md` — partial rebuild for productive transfer +- `docs/architecture/2026-08-12-content-substrate-exploration.md` — markdown SoR, markitect-tool, shard-wiki eval - `the-custodian/docs/coulomb-social-rebuild-seed.md` — original workplan seed (CUST-WP-0058-T08) - `the-custodian/canon/standards/business-app-service-contract_v0.1.md` - NetKingdom: IAM Profile, user-engine boundary, KeyCape/Keycloak modes diff --git a/docs/architecture/2026-08-12-content-substrate-exploration.md b/docs/architecture/2026-08-12-content-substrate-exploration.md new file mode 100644 index 0000000..3e389bf --- /dev/null +++ b/docs/architecture/2026-08-12-content-substrate-exploration.md @@ -0,0 +1,165 @@ +# Content substrate exploration — coulomb.social + +| Field | Value | +|-------|--------| +| Date | 2026-08-12 | +| Status | exploration (direction preferred; not full ADR yet) | +| Related | stage-1 cut, ADR-0002, markitect-tool, shard-wiki, NetKingdom | + +## Constraints (agreed) + +1. **Users, groups, tenants** → **NetKingdom** (OIDC, user-engine, later groups/roles). Coulomb does not reimplement identity directory. +2. **Deploy / operate** → **Railiance** (images, Helm, railiance01). +3. **User data is the user’s** — exportable in a **reuse-friendly** form. Prefer **markdown chunks** as **source of truth**. +4. **Database is a cache** for speed (lists, cards, search projections), not the SoR for page bodies/attributes that users care about owning. +5. **Not “running on markitect.”** markitect-tool is a **lib/service for markdown-as-efficient-datastore tooling**, not the product host. +6. **ADR-0002 Forgejo binding** is a useful vertical slice, not the definition of the product information model. + +## Product information model (working) + +| Concept | Role | +|---------|------| +| **Page** | Universal information object: frontmatter + body + backmatter (markdown) | +| **Space** | Grouping / context of pages (may itself be page-like later) | +| **Card UI** | Presentation of page projections (visual + title + abstract + actions) | +| **Member / group / tenant** | Identity plane — NetKingdom + app session, not page store | + +## Layering (preferred) + +```text +┌─────────────────────────────────────────────────────────────┐ +│ coulomb.social product UI (cards, spaces chrome, flows) │ +│ + session, membership UX, stage-1 product verbs │ +├─────────────────────────────────────────────────────────────┤ +│ Product application service (Django or equivalent) │ +│ — authz against NetKingdom principal │ +│ — page ops API: CRUD, copy, transfer │ +│ — projection cache (Postgres): card lists, memberships │ +├──────────────────────┬──────────────────────────────────────┤ +│ markitect-tool │ content store / wiki orchestration │ +│ parse, validate, │ markdown chunks on disk/git/… │ +│ front/back matter, │ (adapter: folder, git, shard-wiki, │ +│ transform, query │ Forgejo, …) │ +├──────────────────────┴──────────────────────────────────────┤ +│ NetKingdom identity │ Railiance runtime │ +└─────────────────────────────────────────────────────────────┘ +``` + +**SoR rule:** anything a user would take with them on export lives in **markdown (and assets)**. DB holds **derived** indexes and app-only linkage (e.g. Member UUID ↔ NetKingdom subject) that is not “content.” + +--- + +## Decision: markitect-main vs markitect-tool + +| | **markitect-tool** | **markitect-main** | +|--|--------------------|--------------------| +| Role | Syntax-layer **successor**: markdown as protocol | Older **monolithic** platform (parse + infospace + spaces + assets + UI experiments + ops glue) | +| Intent | Library + `mkt` CLI; no accounts/hosting | Full document platform; being **retired / split** | +| For coulomb | **Use** as dependency for structured markdown | **Avoid as runtime foundation** | +| Evidence | `markitect-tool/docs/markitect-main-scope-assessment.md`: tool is clean contract, not a trimmed copy of main; main’s infospace/spaces/DB/graphql out of tool scope | `markitect-main/docs/successor-gap-assessment.md`: main → tool + kontextual-engine + infospace-bench + filter + quarkdown | + +**Decision (this exploration):** + +- Treat **markitect-main as legacy reference / mine for ideas**, not as coulomb’s foundation. +- Integrate **markitect-tool** (and its contracts) for document structure operations. +- Persistence/orchestration of multi-backend wiki shape → evaluate **shard-wiki** / engine, not markitect-main `spaces/`. + +--- + +## Decision direction: shard-wiki as backend + +### What shard-wiki is + +From `shard-wiki` INTENT/SCOPE: + +- **Git-based markdown wiki orchestrator and federation layer** +- Joins **shards** (folder, git, native engine, future adapters) into a **union of pages** +- **Headless, API-first**; UI is a consumer concern (fits coulomb UI) +- **Does not implement** authn / identity store — **delegates to external IdP** (NetKingdom / user-engine) — matches coulomb +- Explicitly lists **“Systems such as Coulomb spaces”** as intended consumers +- Early-stage but substantial foundation (adapters, union, overlays, git coordination log, native engine shard) — not vapor intent only + +### Fit to coulomb constraints + +| Need | shard-wiki fit | +|------|----------------| +| Markdown as SoR | Strong — pages are wiki-shaped markdown content | +| Export / user-owned data | Strong — shards can be folder/git; take the files | +| DB as cache | Compatible — coulomb projects cards into Postgres; shard-wiki not required to be the card DB | +| NetKingdom identity | Compatible — IdP external; shard-wiki owns authz model for pages/shards | +| Avoid reimplementing wiki federation | Strong | +| Risk: “too much structure” | Real — namespaces, overlays, federation, capability profiles, multi-shard resolution are more than a single-tenant space CRUD MVP | + +### “Too much structure?” + +shard-wiki’s structure is **mechanism** (resolution, overlays, provenance, multi-shard), not a fixed **product ontology** (it refuses a universal knowledge ontology). Risk for coulomb is **operational and API surface**: + +- If coulomb calls the full federation graph on day one, stage-1 product work drowns in coordination concepts. +- If coulomb uses a **thin slice**: one InformationSpace per tenant (or per product instance), **one primary shard** (folder or git or native engine) for space pages, overlays only when needed — structure stays **under the hood**. + +**Evaluation stance:** + +| Approach | When | +|----------|------| +| **A. shard-wiki as content plane** | Prefer if we want federation (personal + space shards, export shards, git sync) and headless page ops soon | +| **B. coulomb thin page store + markitect-tool** | Prefer if stage-1 ships faster with a single folder/git layout; adopt shard-wiki when multi-shard or federation is real demand | +| **C. kontextual-engine** | Broader knowledge ops; evaluate if page-only wiki is too narrow long-term — heavier product fit analysis | + +**Preferred exploration order:** prove stage-1 page ops against a **minimal shard-wiki deployment** (or adapter conformance test) **in parallel** with a **simple folder/git adapter design**. Choose A if integration cost is acceptable and API stays stable; else B with a migration path **to** shard-wiki (adapter contract is designed for that). + +Do **not** pick markitect-main as the store. + +--- + +## NetKingdom / Railiance (unchanged ownership) + +| Concern | Owner | +|---------|--------| +| User accounts, login, MFA, groups/roles claims | NetKingdom | +| Application Member link (issuer, subject) | coulomb (JIT) | +| Tenant model | instance-per-client + `tenant_id` (DR-1 C); platform claims when ready | +| Images, deploy, probes, secrets mount | Railiance / railiance-apps | +| Content markdown + page authz | coulomb product + content plane (shard-wiki or thin store) | + +--- + +## Data ownership sketch + +```text +Export package (user or space): + pages/**/*.md # frontmatter + body + backmatter + assets/** # visuals, attachments + MANIFEST.json # optional: ids, space map, hashes +``` + +Rebuild / reimport should not require coulomb’s Postgres. Cache tables are disposable. + +--- + +## Implications for ADR-0002 and stage 1 + +- **ADR-0002:** keep as “Forgejo may host a git shard / export”; demote “one repo per space is the only SoR” when ADR-0003 (page substrate) lands. +- **Stage-1 features** (CRUD, visual, title, abstract, copy, transfer) become **page operations** on the content plane + **card projections** in coulomb UI. +- **markitect-tool** validates/normalizes frontmatter fields; does not host multi-user sessions. + +--- + +## Open evaluation tasks (if we continue) + +1. Spike: coulomb → markitect-tool parse/serialize of a stage-1 page document. +2. Spike: shard-wiki single-space InformationSpace + FolderAdapter or native engine; implement copy/transfer as engine ops or app-level compose. +3. Compare authz model: shard-wiki page ACLs vs coulomb SpaceMembership vs NetKingdom groups. +4. Decide cache invalidation: write to markdown first, then reindex cards. +5. Promote winners into **ADR-0003** (information model + substrate) and revise capability model feature wording. + +## Summary decisions from this note + +| Topic | Decision | +|-------|----------| +| markitect-main | **Avoid** as foundation; legacy reference only | +| markitect-tool | **Adopt** as markdown structure lib/service | +| “Run on markitect” | **Reject** framing | +| Markdown SoR + DB cache | **Adopt** | +| Identity / deploy | **NetKingdom / Railiance** (no reimplementation) | +| shard-wiki | **Serious candidate** for content plane; use **thin slice** to avoid over-structure; spike before hard commit | +| Next write-up | ADR-0003 after spikes or founder pick A vs B | diff --git a/docs/capability/stage-1-cutover.md b/docs/capability/stage-1-cutover.md index 016c0b6..5236123 100644 --- a/docs/capability/stage-1-cutover.md +++ b/docs/capability/stage-1-cutover.md @@ -119,8 +119,9 @@ capabilities but does not redefine the must set. ## Open product questions -1. **Visual** — cover image only, or gallery? Max size? Forgejo `assets/` vs object store? +1. **Visual** — cover image only, or gallery? Max size? assets next to markdown vs object store? 2. **Abstract** — rename `Space.description` → abstract in UI only, or schema rename? -3. **Page body editing** — stage 1 keeps edit-in-Forgejo for body, app forms for Title/Abstract/Visual only? Or in-app markdown editor? +3. **Page body editing** — stage 1: product forms for Title/Abstract/Visual + markdown body path; exact editor TBD. 4. **Delete** — hard delete vs archive (`is_active`)? -5. **Transfer cohort** — require public self-registration, or LLDAP bulk invite for stage 1? +5. **Transfer cohort** — require public self-registration, or LLDAP bulk invite for stage 1? +6. **Content substrate** — see `docs/architecture/2026-08-12-content-substrate-exploration.md` (markitect-tool + markdown SoR; evaluate shard-wiki thin slice vs folder/git store).