generated from coulomb/repo-seed
Reorganize documentation into canonical repository layout
Adopt CoulombSocial/HelixForge/MarkiTect documentation structure: - research/260608-yawex-prior-art/ — yawex exploration and sources - demand/ — inbound NetKingdom integration requirements - spec/ — PRD, TSD, UseCaseCatalog, ArchitectureBlueprint scaffolds - docs/ — stakeholder documentation and repository-layout guide - wiki/, issues/, history/ — scaffolded directories Add SCOPE.md and AGENTS.md. Update workplan paths and README.
This commit is contained in:
149
spec/ArchitectureBlueprint.md
Normal file
149
spec/ArchitectureBlueprint.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# ArchitectureBlueprint — shard-wiki access & history model
|
||||
|
||||
Status: **draft for review** · Date: 2026-06-08 · Resolves pending decision
|
||||
"Scope of a minimal access model in shard-wiki core".
|
||||
|
||||
Part of `spec/`. Background on specification document types: InfoTechPrimers on
|
||||
coulomb.social.
|
||||
|
||||
This blueprint settles how shard-wiki handles access control and change history. It
|
||||
realizes the INTENT principles *Open by default, progressively governed*, *History as
|
||||
the safety net*, and *Authorization in core, authentication delegated*.
|
||||
|
||||
---
|
||||
|
||||
## 1. The core idea: one core, a ladder of modes
|
||||
|
||||
shard-wiki ships **one** authorization core. What changes between deployments is how much
|
||||
of it is switched on. No re-architecture is needed to climb the ladder — only
|
||||
configuration and the presence (or absence) of an external identity provider.
|
||||
|
||||
This mirrors the NetKingdom **capability-progression ladder** ("capability-driven, not
|
||||
scale-driven"): start lightweight, expand when the need appears.
|
||||
|
||||
| Mode | Identity provider | Who can read/write | External deps | Analogue |
|
||||
|------|------------------|--------------------|---------------|----------|
|
||||
| **L0 — Open (c2)** | none (everyone is `anonymous`) | everyone reads + writes | **none** | Ward Cunningham's original c2 wiki |
|
||||
| **L1 — Attributed** | local/optional | open writes, but edits are attributed when an identity is presented | none | classic "sign your edits" wiki |
|
||||
| **L2 — Authenticated** | user-engine (OIDC via net-kingdom lightweight) | authenticated principals; simple read-all / write-authenticated | user-engine + net-kingdom (OIDC/PKCE) | small team wiki |
|
||||
| **L3 — Role/Group** | user-engine memberships | per-shard/per-namespace roles (reader/author/maintainer) | user-engine groups | departmental wiki |
|
||||
| **L4 — Multi-tenant enterprise** | user-engine + net-kingdom expanded (Keycloak/SAML) | per-tenant isolation, per-page ACL, SSO/MFA, audit | full IAM stack | enterprise-grade |
|
||||
|
||||
**Invariant:** L0 must always be reachable with zero external dependencies. Access control
|
||||
is *additive*; removing the identity provider degrades gracefully back down the ladder, it
|
||||
never bricks the wiki.
|
||||
|
||||
---
|
||||
|
||||
## 2. Why history is the floor, not access control
|
||||
|
||||
In L0 the wiki trusts every writer. The protection against accidental loss, vandalism, or
|
||||
mistakes is therefore **not** gatekeeping but **complete, recoverable history**:
|
||||
|
||||
- Every write is a Git commit on the information space's coordination layer (per INTENT's
|
||||
Git-addressable coordination principle).
|
||||
- Any revision of any page is restorable; deletion is a commit, never destruction.
|
||||
- History exists identically in **all** modes — L4's access control *hardens* the wiki but
|
||||
the recoverability guarantee is the same one that makes L0 safe to run open.
|
||||
|
||||
This is the inversion of yawex, which gated with htpasswd and kept only a single `page~`
|
||||
backup. We keep the openness, replace the gate with history, and make the gate optional.
|
||||
|
||||
---
|
||||
|
||||
## 3. Component model
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ shard-wiki │
|
||||
request ───► │ ┌────────────┐ ┌──────────────────────┐ │
|
||||
(principal?) │ │ Policy │ │ Authorization core │ │
|
||||
│ │ Enforcement├──►│ (PDP): capability │ │
|
||||
│ │ Point (PEP)│ │ decisions per │ │
|
||||
│ └─────┬───────┘ │ page / shard / tenant│ │
|
||||
│ │ └──────────┬───────────┘ │
|
||||
│ ▼ │ │
|
||||
│ ┌────────────┐ ┌──────▼───────────┐ │
|
||||
│ │ Shard │ │ IdentityProvider │ │
|
||||
│ │ adapters │ │ (interface) │ │
|
||||
│ │ (+capability│ └──────┬───────────┘ │
|
||||
│ │ profile) │ │ │
|
||||
│ └─────┬───────┘ │ │
|
||||
│ ▼ │ │
|
||||
│ Git-backed coordination journal │ │
|
||||
└──────────────────────────────────┼─────────────┘
|
||||
│ (L2+ only)
|
||||
┌────────────────────────▼───────────────────┐
|
||||
│ user-engine (accounts, memberships, │
|
||||
│ profiles, audit, events) │
|
||||
│ backed by net-kingdom IAM │
|
||||
│ (OIDC/PKCE lightweight · Keycloak/SAML exp) │
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Owned by shard-wiki core:**
|
||||
- **Principal** — a resolved actor: `anonymous`, or an identity token + claims from the
|
||||
provider. Core never stores credentials.
|
||||
- **IdentityProvider interface** — a thin pluggable contract. The **null provider**
|
||||
(everyone = `anonymous`) is the L0 default and ships in-core.
|
||||
- **Authorization core (PDP)** — pure capability decisions: given (principal, action,
|
||||
target page/shard/tenant), return allow/deny. Actions: `read, write, patch, merge,
|
||||
administer`. Layered on each adapter's **capability profile** (a shard that can't write
|
||||
can't be written regardless of policy).
|
||||
- **Policy Enforcement Point (PEP)** — wraps every adapter operation; calls the PDP.
|
||||
- **Tenant boundary** — a *root entity* is the unit of multi-tenancy. Shards attach to a
|
||||
root; an L4 tenant maps to a root entity (or a set of them).
|
||||
- **Change history** — Git commits on the coordination journal; the recovery substrate.
|
||||
|
||||
**Delegated to the identity provider (L2+):**
|
||||
- Authentication (who you are) — net-kingdom IAM (OIDC/PKCE → Keycloak/SAML).
|
||||
- Identity lifecycle, user directory, credentials, secrets — net-kingdom / user-engine.
|
||||
- Memberships, groups, profiles, org structure, audit sink — user-engine.
|
||||
|
||||
---
|
||||
|
||||
## 4. Request flow (L4, fully governed)
|
||||
|
||||
1. Caller presents an OIDC token (issued by net-kingdom IAM) to shard-wiki.
|
||||
2. The configured **IdentityProvider** validates the token and resolves a **Principal**
|
||||
(subject + tenant + group/role claims), enriching via **user-engine** memberships.
|
||||
3. The **PEP** intercepts the requested action on a target page/shard.
|
||||
4. The **PDP** decides using: tenant isolation → shard role bindings → optional per-page
|
||||
ACL → adapter capability profile.
|
||||
5. On allow, the adapter performs the op; the write lands as a **Git commit** and an
|
||||
**audit event** is emitted to user-engine.
|
||||
6. On deny, the op is refused; nothing mutates.
|
||||
|
||||
**The same code path at L0:** step 1 is skipped, the null provider returns `anonymous`,
|
||||
the PDP's open policy allows read+write, the write still lands as a Git commit. History is
|
||||
identical; only the gate differs.
|
||||
|
||||
---
|
||||
|
||||
## 5. Design rules
|
||||
|
||||
- **Fail open only at L0, fail closed at L2+.** The mode is explicit configuration, never
|
||||
inferred from whether the provider happens to be reachable (a flaky IAM must not silently
|
||||
open an enterprise wiki). If an L2+ deployment loses its provider, it denies, it does not
|
||||
fall back to open.
|
||||
- **Authorization is pure and offline-capable.** Once a Principal is resolved, decisions
|
||||
need no network call — role/ACL data is carried on the Principal or cached, so a federated
|
||||
read of a projected page doesn't require a live IAM round-trip per page.
|
||||
- **Per-page ACL is opt-in (L4).** Default scoping is per-shard / per-namespace (L3). Per-page
|
||||
ACL is supported but off by default to avoid yawex's per-directory `AccessControl` sprawl.
|
||||
- **Provenance carries authorization context.** A federated page records not just its source
|
||||
shard and freshness but the authorization context under which it was read, so the union
|
||||
view never leaks content a principal couldn't see at source.
|
||||
|
||||
---
|
||||
|
||||
## 6. Open questions (carry into requirements)
|
||||
|
||||
1. Token format/claims contract with net-kingdom (OIDC scopes, tenant claim name).
|
||||
2. user-engine membership/role query shape and caching/TTL.
|
||||
3. Audit event schema shard-wiki emits to user-engine.
|
||||
4. How tenant ↔ root-entity mapping is configured and discovered.
|
||||
5. Whether L1 "attributed but open" is worth shipping or we jump L0 → L2.
|
||||
|
||||
See `demand/260608-netkingdom-integration-requirements.md` for the concrete asks
|
||||
these imply.
|
||||
54
spec/ProductRequirementsDocument.md
Normal file
54
spec/ProductRequirementsDocument.md
Normal file
@@ -0,0 +1,54 @@
|
||||
# ProductRequirementsDocument
|
||||
|
||||
Status: **draft scaffold** · Date: 2026-06-08
|
||||
|
||||
See InfoTechPrimers on coulomb.social for PRD conventions.
|
||||
|
||||
## 1. Product Name
|
||||
|
||||
**shard-wiki**
|
||||
|
||||
## 2. Product Intent
|
||||
|
||||
Git-based Markdown wiki **orchestrator and federation layer** — not a wiki
|
||||
engine. Joins heterogeneous wiki-shaped page stores (shards) into a coherent
|
||||
information space while preserving provenance, capabilities, and history.
|
||||
|
||||
Authoritative aspiration: `INTENT.md`.
|
||||
|
||||
## 3. Problem Statement
|
||||
|
||||
Wiki content lives in fragmented backends (Git repos, Gitea wikis, local
|
||||
folders, Obsidian vaults, WebDAV, application databases). Users and tools need a
|
||||
union of pages with versionable coordination, overlays for remote edits, and
|
||||
explicit provenance — without forcing a single storage format or engine.
|
||||
|
||||
## 4. Target Users
|
||||
|
||||
See `INTENT.md` § Intended Users.
|
||||
|
||||
## 5. Core Capabilities (maturity target)
|
||||
|
||||
- Attach multiple shards to a shared root entity.
|
||||
- Present union views of pages, links, metadata, and revisions.
|
||||
- Lazy projection and cache of remote shard content.
|
||||
- Overlay-before-mutation for capability-limited shards.
|
||||
- Git-backed coordination journal per information space.
|
||||
- Capability-aware shard adapter contract.
|
||||
- Pluggable authorization from open (L0) through multi-tenant enterprise (L4).
|
||||
- Complete recoverable history as the baseline safety net.
|
||||
|
||||
## 6. Non-Goals
|
||||
|
||||
See `INTENT.md` § Strategic Boundaries.
|
||||
|
||||
## 7. Research Inputs
|
||||
|
||||
- `research/260608-yawex-prior-art/findings.md` — federation design seeds from
|
||||
prior art.
|
||||
|
||||
## 8. Open Items
|
||||
|
||||
Pending completion of `SHARD-WP-0001` design tasks and ratification of access
|
||||
model INTENT amendments. Detailed requirements will be expanded as spec tasks
|
||||
complete.
|
||||
15
spec/README.md
Normal file
15
spec/README.md
Normal file
@@ -0,0 +1,15 @@
|
||||
# spec/
|
||||
|
||||
Specification files that guide and guardrail implementation.
|
||||
|
||||
Background on document types: InfoTechPrimers on coulomb.social.
|
||||
|
||||
| File | Status | Role |
|
||||
|------|--------|------|
|
||||
| `ProductRequirementsDocument.md` | draft scaffold | What the product must deliver |
|
||||
| `TechnicalSpecificationDocument.md` | draft scaffold | How the system is built |
|
||||
| `UseCaseCatalog.md` | draft scaffold | Observable usage scenarios |
|
||||
| `ArchitectureBlueprint.md` | draft | Access, history, and identity architecture |
|
||||
|
||||
Promote material from `research/` and reviewed items from `demand/` into spec
|
||||
before treating it as implementation authority.
|
||||
51
spec/TechnicalSpecificationDocument.md
Normal file
51
spec/TechnicalSpecificationDocument.md
Normal file
@@ -0,0 +1,51 @@
|
||||
# TechnicalSpecificationDocument
|
||||
|
||||
Status: **draft scaffold** · Date: 2026-06-08
|
||||
|
||||
See InfoTechPrimers on coulomb.social for TSD conventions.
|
||||
|
||||
## 1. System Overview
|
||||
|
||||
Python package (`src/shard_wiki/`) implementing a federation orchestration
|
||||
layer. Markdown-first, backend-neutral page model. Git-addressable coordination
|
||||
per information space.
|
||||
|
||||
## 2. Implementation Stack
|
||||
|
||||
| Concern | Choice |
|
||||
|---------|--------|
|
||||
| Language | Python ≥ 3.11 |
|
||||
| Layout | `src/` package, hatchling build |
|
||||
| Tests | pytest |
|
||||
| Lint/format | ruff |
|
||||
|
||||
## 3. Core Abstractions (to be specified)
|
||||
|
||||
| Abstraction | Description |
|
||||
|-------------|-------------|
|
||||
| Shard | Independently meaningful page store with sovereignty |
|
||||
| Root entity | Joined information space shards attach to |
|
||||
| Shard adapter contract | Versioned, capability-aware backend interface |
|
||||
| Wiki page model | Paths, links, metadata, revisions |
|
||||
| Projection | Lazy local view of remote content |
|
||||
| Overlay | Non-destructive edit before remote mutation |
|
||||
| Coordination journal | Git-backed change record |
|
||||
|
||||
## 4. Architecture References
|
||||
|
||||
- `spec/ArchitectureBlueprint.md` — access, history, identity delegation
|
||||
|
||||
## 5. Integration Boundaries
|
||||
|
||||
- Authentication delegated to external identity provider (reference:
|
||||
net-kingdom + user-engine). See `demand/260608-netkingdom-integration-requirements.md`.
|
||||
- No credential or secret storage in shard-wiki core.
|
||||
|
||||
## 6. Current Implementation
|
||||
|
||||
Package scaffold only (`__version__`, smoke tests). Domain model not yet coded.
|
||||
|
||||
## 7. Next Specification Work
|
||||
|
||||
Outputs from `SHARD-WP-0001` tasks (page resolution, namespaces, derived views,
|
||||
provenance, overlays, link semantics) will be incorporated here as they complete.
|
||||
47
spec/UseCaseCatalog.md
Normal file
47
spec/UseCaseCatalog.md
Normal file
@@ -0,0 +1,47 @@
|
||||
# UseCaseCatalog
|
||||
|
||||
Status: **draft scaffold** · Date: 2026-06-08
|
||||
|
||||
See InfoTechPrimers on coulomb.social for use-case catalog conventions.
|
||||
|
||||
## UC-01 — Standalone open wiki (L0)
|
||||
|
||||
**Actor:** Anonymous contributor
|
||||
**Goal:** Read and write wiki pages with full history and no external dependencies.
|
||||
**Notes:** Ward Cunningham / c2-style open mode. Recovery via Git history, not gatekeeping.
|
||||
|
||||
## UC-02 — Attach a Git repo shard
|
||||
|
||||
**Actor:** Maintainer
|
||||
**Goal:** Attach a repository or `wiki/` subdirectory as a shard of an information space.
|
||||
**Notes:** Preserve shard sovereignty and adapter capability profile.
|
||||
|
||||
## UC-03 — Project a remote shard page locally
|
||||
|
||||
**Actor:** Reader
|
||||
**Goal:** View a page from a remote or read-only shard as a local projection with provenance and freshness visible.
|
||||
**Notes:** Lazy projection; no silent mutation.
|
||||
|
||||
## UC-04 — Overlay edit on read-only shard
|
||||
|
||||
**Actor:** Author
|
||||
**Goal:** Propose changes to a remote/read-only page as overlay/draft/patch before destructive apply.
|
||||
**Notes:** Overlay-before-mutation principle.
|
||||
|
||||
## UC-05 — Union browse (BackLinks, RecentChanges)
|
||||
|
||||
**Actor:** Reader
|
||||
**Goal:** Navigate derived views across all attached shards.
|
||||
**Notes:** BackLinks over federated link graph is a strong core candidate (see research findings).
|
||||
|
||||
## UC-06 — Authenticated team wiki (L2+)
|
||||
|
||||
**Actor:** Authenticated principal
|
||||
**Goal:** Read/write under role-based authorization with identity from external provider.
|
||||
**Notes:** See `spec/ArchitectureBlueprint.md` capability ladder.
|
||||
|
||||
## UC-07 — Detect cross-shard divergence
|
||||
|
||||
**Actor:** Maintainer
|
||||
**Goal:** Identify when equivalent pages in different shards have diverged and reconcile.
|
||||
**Notes:** Union without erasure — conflicts visible, not hidden.
|
||||
Reference in New Issue
Block a user