generated from coulomb/repo-seed
workplan: SHARD-WP-0014 wiki-engine implementation (kernel + typed-extension runtime + activation)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
148
workplans/SHARD-WP-0014-engine-implementation.md
Normal file
148
workplans/SHARD-WP-0014-engine-implementation.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user