From b147d3e8317a720dfaa2936737d0158ae978ae17 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 15 Jun 2026 23:51:12 +0200 Subject: [PATCH] workplan: SHARD-WP-0014 wiki-engine implementation (kernel + typed-extension runtime + activation) Co-Authored-By: Claude Opus 4.8 --- .../SHARD-WP-0014-engine-implementation.md | 148 ++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 workplans/SHARD-WP-0014-engine-implementation.md diff --git a/workplans/SHARD-WP-0014-engine-implementation.md b/workplans/SHARD-WP-0014-engine-implementation.md new file mode 100644 index 0000000..f7df2c4 --- /dev/null +++ b/workplans/SHARD-WP-0014-engine-implementation.md @@ -0,0 +1,148 @@ +--- +id: SHARD-WP-0014 +type: workplan +title: "wiki-engine implementation — kernel + typed-extension runtime + activation" +domain: whynot +repo: shard-wiki +status: active +owner: tegwick +topic_slug: whynot +created: "2026-06-15" +updated: "2026-06-15" +depends_on: + - SHARD-WP-0007 + - SHARD-WP-0013 +--- + +# SHARD-WP-0014 — Wiki-engine implementation + +## Goal + +Implement the native **headless wiki engine** specified in `spec/WikiEngineCoreArchitecture.md`: +a **small page-store kernel** + a **stringent typed-extension runtime**, with **per-shard +activation** (ADR-0001: via feature-control/OpenFeature, LocalProvider default), the engine's +**§A capability profile derived from active extensions** (E-5), and exposure as a +**canonical-mode shard** (`EngineShardAdapter`). Target capability: **stand up an engine shard, +activate a chosen extension set, and attach it to an `InformationSpace` — its declared +capability profile reflecting exactly what is active** — proven end-to-end with one real +built-in extension. + +**Non-goal (this slice):** the headless network API protocol; git-IS-store backing (kernel uses +the existing simple store now; git backing integrates with SHARD-WP-0009/0012 later); +computational extensions; the full feature-control control plane. Build the framework, prove it. + +## Guiding rules (from WikiEngineCoreArchitecture) + +- E-1 engine is **one shard**, not a federation layer. E-2 small kernel. E-3 everything-else is a + typed extension. E-4 per-shard activation. E-5 capability profile derived from active + extensions. E-8 reuse (feature-control activation; model/provenance/coordination/adapters). + E-9 extensions are typed + conformance-verified. +- Honour the §11 dependency rule: `engine/` consumes `model/`, `provenance/`, `coordination/`, + `adapters/`, `policy/`; it is consumed only via its `EngineShardAdapter`. No orchestrator-tier + (`union/`, `projection/`) import. Pure-stdlib core; OpenFeature is an optional engine extra. + +--- + +## Engine kernel skeleton + +```task +id: SHARD-WP-0014-T1 +status: todo +priority: high +``` + +`src/shard_wiki/engine/kernel.py`: the minimal kernel — a page store + lifecycle over existing +primitives (reuse `model.Page`/`Identity`/`provenance`; a simple in-memory/folder-backed store +now, git-IS-store later) and a recoverable history hook into the decision log. Kernel covers the +c2-minimum (create/read/edit-as-history; `[[wikilink]]`+red-link resolution can be a thin kernel +helper). No extensions yet. Tests: page CRUD-as-history; kernel-only shard works. + +## Typed-extension runtime + +```task +id: SHARD-WP-0014-T2 +status: todo +priority: high +``` + +`src/shard_wiki/engine/extension.py`: the `Extension` contract (id, provides, types, hooks, +depends_on, conflicts_with, config), a registry, a **typed hook dispatcher** (typed +inputs/outputs, declared deterministic order), a **type checker**, and **composition** that +builds the dependency closure and **rejects impossible profiles** (conflicts / unmet deps / +incompatible types) — the §6.5 discipline for extensions. Extensions ship a conformance check +(mirrors §6.6). Tests: register/compose; deterministic hook order; impossible profile rejected; +conformance catches a lying extension. + +## Per-shard activation (feature-control / OpenFeature) + +```task +id: SHARD-WP-0014-T3 +status: todo +priority: high +``` + +`src/shard_wiki/engine/activation.py` (ADR-0001): resolve a shard's **activation profile** +(`{extension id → config}`) through an OpenFeature-shaped client with a **static LocalProvider +default** (standalone, zero external dep); context = `{tenant_id: root, shard_id, …}`; OpenFeature/ +feature-control is an optional provider plugged in when present (degrade gracefully, mirror the +identity ladder). **Availability only — never authorization.** Tests: LocalProvider activates a +subset; absent-provider falls back to defaults; context scoping works. + +## Capability profile derived from active extensions (E-5) + +```task +id: SHARD-WP-0014-T4 +status: todo +priority: high +``` + +`src/shard_wiki/engine/profile.py`: fold the active extensions' `on_profile` contributions into a +§A `CapabilityProfile` (e.g. `ext.struct` active ⟹ structure spectrum rises + `structured-payload` +verb), then `validate()` + conformance. Tests: activating an extension changes the derived +profile; the derived profile is valid and conformance-passes. + +## EngineShardAdapter (engine as a canonical-mode shard) + +```task +id: SHARD-WP-0014-T5 +status: todo +priority: high +``` + +`src/shard_wiki/engine/adapter.py`: `EngineShardAdapter` implements `adapters.ShardAdapter`, +backed by the kernel + active extensions, declaring the derived profile (T4). Attach an engine +shard to an `InformationSpace` and read/resolve/edit through it like any shard. Tests + +integration: engine shard passes `assert_conformant`; attach → resolve → edit works. + +## First built-in extension (prove the framework end-to-end) + +```task +id: SHARD-WP-0014-T6 +status: todo +priority: medium +``` + +Implement one real extension end-to-end — **`ext.views` (BackLinks)** or **`ext.struct` +(typed records)** — binding kernel hooks, declaring types, contributing to the derived profile, +activatable per shard. Integration test: with the extension OFF the capability is absent (honest +profile); ON it works and the profile reflects it. Update SCOPE + spec/README; `pytest` + +pyflakes green. + +--- + +## Acceptance criteria + +- `pytest` green, pyflakes clean; engine core pure-stdlib (OpenFeature optional, behind the + LocalProvider default). +- The vertical slice works: stand up an engine shard, activate a chosen extension set, attach to + an `InformationSpace`; the engine's declared §A profile **matches the active extensions** and + passes conformance. +- Module boundaries honour §11 (engine consumed only via `EngineShardAdapter`; no union/projection + import); E-1…E-9 respected. +- Activation is availability-only (no authz); standalone path has no external dependency. +- Each task committed; state-hub synced. + +## Suggested task order + +T1 kernel → T2 extension runtime → T3 activation → T4 derived profile → T5 EngineShardAdapter → +T6 first extension + integration.