Widget Contract Reconciliation¶

Status: living document · updated alongside each spec / engine / UI release Companion to: STORYTANGL_WIDGET_VOCAB.md v1.5 Companion to: bundles/<name>/EXTENSIONS.md (Tier P3 genre layers)

This document tracks implementation status across the three layers named in spec §0.7:

Layer	Document	Role
L1 — UI Vocabulary	`STORYTANGL_WIDGET_VOCAB.md` + `bundles/<name>/EXTENSIONS.md`	Target-truth. What data shapes the player-facing client needs. The spec evolves here; everything else chases.
L2 — API Transport	`API_SPEC.md` (forthcoming; derived from this doc)	REST endpoints (and other wire transport) routing L1 needs to L3 capabilities. Optional layer — CLI ports skip it.
L3 — Engine Capabilities	`ENGINE_CAPABILITIES.md` (forthcoming; derived from this doc)	Python callables that produce the data L1 wants. The current engine’s actual surface.

The spec is target-truth. This document is the honest reality check. The two are intentionally allowed to disagree during a settling phase — that’s how the inversion (UI-led design, backend chases) works.

How to read this doc¶

Each surface in the spec gets a row in one of the §-numbered tables below. The four status columns per row:

Column	What it tracks
Spec tier (L1)	`Tier S` / `Tier P1` / `Tier P2` / `Tier P3` per the vocab spec. The contract commitment.
Reference clients	What `apps/web/` and the reference CLI/Tk ports ship today. Values: `done`, `partial`, `not_started`, `n/a`.
Engine backend (L3)	What `engine/` ships today. Values: same as L2, plus `untyped` (works but with `dict[str, Any]` rather than typed Pydantic).
Plan	One-line forward direction. Empty when the row is settled across columns.

A row is settled when all three implementation columns match the spec’s tier commitment. A row with mismatched columns is in negotiation — that’s fine; the doc just makes the gap visible.

Sequence of work, per the inversion strategy. UI vocabulary leads (commit the target shape in the spec), the reference UI catches up next (against fixtures, even with dummy data), then the engine + API expose capabilities that match. The CLI port skips L2 entirely and consumes L3 directly via an in-process shim.

§A — Tier S surfaces (core contract)¶

These are the surfaces v1.5 marks Tier S — committed as stable target contract. Most are already shipping in the reference UI and engine; the negotiation is mostly about typed-shape graduations.

Surface	Spec tier	Reference UI	Engine backend	Plan
`ContentFragment` shape	S	done	done	—
`AttributedFragment` shape	S	done	done	—
`MediaFragment` shape	S	done	done	—
`GroupFragment` shape (`scene`, `dialog`, `overlay`, `status_sidecar`)	S	done	done	—
`KvFragment` shape	S	done (`KvRow[]`)	done (`list[KvRow]`)	tuple-row fixtures migrated in typed accepts / KvRow PR
`ChoiceFragment` shape (frame only)	S	done	done	—
`ControlFragment` (`update` / `delete`)	S	done	done	—
`UserEventFragment`	S	done	done	—
`ProjectedState.sections` with five `value_type`s	S	done	done	—
`metadata.info_affordances: list[InfoAffordance]`	S	done (web + CLI `?`/slash floor)	done (typed; gathered through service-info dispatch)	sandbox and credentials fixtures cover advertised channels
`InfoAffordance.query` optional dict (opaque descriptor)	S	done	done	bundles choose descriptor contents; clients hand it back
`metadata.info_state: InfoState` typed	S	done (nested type + dirty-kind cache hints)	partial (typed; v1 conservatively marks advertised kinds dirty)	add finer dirty tracking only when a client needs caching
`/story/info` accepts `kind`/`kinds` + `query` params	S	done client-side	done (same endpoint; singular/plural kind filters + query descriptor routing)	add bundle-specific providers as worlds need them
§1.6 Info channels	S	done (info pills + CLI floor)	done	keep rich renderers optional; `ProjectedState` fallback remains required
`PresentationHints` (style_name, style_tags, style_dict, icon)	S	partial (basic style/icon fields)	done	audit aliases and long-tail hints before treating complete
Bundle customization / presentation profiles	S target	partial (docs + older world `ui_config`)	not_started	keep advisory; requires world-info catalog before conformance
§5.1 Decision Legibility Contract	S	partial (JSON harness covers fixtures/sequences)	n/a (contract; not a capability)	expand field coverage as new decision surfaces promote
§5.2 Time Parity Rule (visual ritual skip, media advance)	S	partial (JSON harness covers readable fallbacks)	n/a	browser timing/skip E2E remains later
§5.3 Input Parity Rule (drag fallback, hotkey numbers)	S	partial (JSON harness covers fixture submit floors)	n/a	extend toward renderer-specific drag/keyboard fallbacks
§0.2 CLI Floor Rule	S	n/a	n/a (gating rule on PRs)	wire into CI for Tier S graduations

§B — Tier P1 surfaces (target for next engine epoch)¶

These are committed target contract but require additive engine work. Each row should land as a single PR-shaped change unless the surface is small enough to settle with its immediate neighbors.

Surface	Spec tier	Reference UI	Engine backend	Plan
Typed `PiecesAccepts` (was `tokens`)	P1	done (kind `pieces` + typed TS shape)	done (`Accepts` union)	expand conformance cases only as new widgets land
Typed `PickAccepts`, `TextAccepts`, `QuantityAccepts`, `RawCommandAccepts`	P1	done	done (`Accepts` union)	keep legacy web `payload_type` path as local UI compatibility until fixtures stop using it
Typed `PlaceAccepts` (including optional `edge_ref`)	P1	partial (`edge_ref` not rendered)	done (`Accepts` union)	add `edge_ref` fixture when route/network MVP lands
Typed `ComposeAccepts`	P1	partial (web nested renderer + CLI/Tk inspection fixture)	done (`Accepts` union)	harden layout and add broader part combinations as worlds emit them
Typed `UIHints`	P1	partial (documented + ad-hoc keys)	done (`UIHints`, extra-allow)	tighten named fields when more worlds use them
Typed `Blocker` (replaces dict blockers)	P1	done (typed + rendered)	untyped	engine PR
Typed `InterpretationFragment`	P1	done (renders `result` / `text` / `message`)	untyped	engine PR
`cost_previews: list[CostPreview]` (plural)	P1	done (choice display)	not_started	engine PR
`metadata.grammar` typed sub-key	P1	done	partial (string-keyed dict)	engine PR for `GrammarHint` Pydantic model
HTTP body field `edge_id`	P1	done	done	—
§1.5 Cursors and journal channels (per-channel envelopes)	P1	n/a (single cursor)	n/a (single cursor)	wait for MVP author needing multi-cursor (Discord-bot bundle, Lost Worlds gamebook)

Block on Tier P1 graduation to Tier S: the CLI reference port (engine/contrib/conformance/cli_reference_port.py) must implement each surface before its row can promote. Until then they stay P1.

§C — Tier P2 surfaces (interactive surface vocabulary)¶

These are committed target contract but larger, and several depend on the §7.4 predicate-registration protocol (an explicit open question in the spec).

Surface	Spec tier	Reference UI	Engine backend	Plan
`PieceFragment` (core shape)	P2	partial (basic web widget + carwars wireframes)	partial (untyped equivalent)	engine PR: typed `PieceFragment` with required `hints.label_text`
`PieceFragment.realized` + `cost` (offers)	P2	done in carwars catalog fixtures	not_started	engine PR for typed lifecycle; bundle MVP needed for shop semantics
`PieceFragment.owner`	P2 (proposal fixture)	not_started	not_started	wait for multi-cursor MVP
`PieceFragment.position`	P2 (proposal fixture)	not_started	not_started	wait for grid/hex bundle MVP (Patchwork, Carcassonne)
`PieceFragment.available` + `unavailable_reason`	P2	done	not_started	engine PR with `PieceFragment` graduation
`group_type="zone"` with `ZoneConstraints`	P2	partial (basic web widget + carwars wireframes)	not_started	engine PR: typed `GroupFragment.constraints`; bundle MVP for capacity
`ZoneLayoutHints` (orientation, fan, grid, hex, graph, floorplan)	P2	partial (orientation/grid/fan)	not_started	engine PR; render-port catches up as needed
`GraphLayout.edges` (first-class adjacencies with UIDs)	P2 (proposal fixture)	not_started	not_started	wait for network/route bundle MVP (Ticket-to-Ride-shaped)
`PlaceAccepts.edge_ref` fixture coverage	P2 pressure fixture	not_started	not_started	P1 typed field exists in the target; graph-route fixture remains gated on a route/network MVP
`RollFragment` (typed)	P2	partial (basic rendering in carwars)	not_started	engine PR; CLI reference port renders outcome word + narrative
`RitualHints` (skip_label, auto_skip_after_seen, allow_replay, duration_ms)	P2	partial	not_started	engine PR with `RollFragment` graduation
`predicate_ref` registration protocol	§7.4 OPEN	n/a	n/a	highest-leverage open question; awaiting MVP author
`visibility="hidden" \| "owner_only" \| "public"`	P2	partial	not_started	engine PR — single-cursor today, audience-list extension when multi-cursor lands
`visibility: list[ParticipantId]` (audience lists)	P2 (proposal fixture)	not_started	not_started	wait for team-game MVP

§D — Tier P3 genre extension surfaces¶

These are advisory genre conventions layered on top of v1.5. They do not create new core fragment types, accepts kinds, or value types. A generic client remains conforming when it renders the underlying v1.5 surfaces and ignores these enrichments.

Surface	Spec tier	Reference UI	Engine backend	Plan
`bundles/carwars/EXTENSIONS.md`	P3	docs + v1.5 wireframe	n/a	keep drag optional; no garage-specific core widgets
`bundles/credentials/EXTENSIONS.md`	P3	docs + v1.5 wireframe	n/a	packet / finding / disposition treatments remain genre enrichments
`bundles/training/EXTENSIONS.md`	P3	docs + v1.5 wireframe	n/a	study previews, stat checks, and inventory unlocks remain genre enrichments
`bundles/elefant_hunt/EXTENSIONS.md`	P3	docs + v1.5 wireframe	n/a	journal-as-story transcript proof; no new surface beyond graph zones / rolls
`ui_hints.stat_check`	P3	docs + v1.5 wireframe	bundle-specific	optional badge or CLI suffix; backend remains authoritative
`ui_hints.validity_check`	P3	docs + v1.5 wireframe	bundle-specific	optional preview over mediation choices; fallback to ordinary choice text
`ui_hints.encounter_check`	P3	docs + v1.5 wireframe	bundle-specific	optional risk badge / suffix; fallback to `ui_hints.emphasis` + prose
`ui_hints.drag`	P3	docs + v1.5 wireframe	n/a	optional enrichment; click-pick fallback remains required by §5.3
Genre transcript examples	P3 diagnostic	v1.5 wireframe samples	n/a	add executable transcripts when demo worlds stabilize; diagnostic, not gating
`_common/EXTENSIONS.md`	deferred	n/a	n/a	do not create until a fourth cross-genre pattern is not already covered by core v1.5

§E — API transport (Layer 2)¶

The API surface is intentionally underspecified at the contract level — the spec commits to the data shapes (L1), and the API chooses how to route them. This table is what the engine team implements.

Endpoint	Method	Spec target	Current engine	Plan
`/story/do`	POST	accepts `ChoiceRequest{edge_id, payload}`; returns `RuntimeEnvelope`	accepts `{edge_id, payload}`	type response
`/story/update`	GET	returns `RuntimeEnvelope` typed	partial	type response
`/story/info`	GET	accepts `kind?`, `kinds?`, and `query?` params (JSON-encoded descriptor); returns `ProjectedState`	done	add bundle-specific providers
`/system/info`	GET	public; rate-limited	done	—
`/auth/whoami`	GET	returns current `Principal`	not_started	see auth thread
`/auth/keys` (CRUD)	various	API key lifecycle	not_started	see auth thread
`/auth/revoke`	POST	revoke a key	not_started	see auth thread

CLI port and L2. The CLI port does not call any of these endpoints. It consumes engine/’s Python surface directly via an in-process shim — typically a thin wrapper around ServiceManager.do_action() / get_envelope() / get_projected_state(). The L2 column is therefore not blocking for CLI conformance.

§F — Conformance harness¶

These tests verify spec contracts against the reference implementations. They serve as the gating mechanism for tier graduations and as the regression suite for cross-port parity.

Harness	What it checks	Status	Plan
`engine/contrib/conformance/cli_reference_port.py`	Tier S CLI rendering for every fragment / value_type	partial (Tier S + current P1 widgets)	extend coverage as Tier P1 → S graduations happen
`engine/contrib/conformance/legibility.py`	§5.1 — referenced UIDs are rendered	initial	covers fixture and sequence choices; expand as new P1/P2 fields promote
`engine/contrib/conformance/parity.py`	§5.3 input parity	initial	covers fixture and sequence submit floors; time parity remains next harness
`engine/contrib/conformance/time_parity.py`	§5.2 time parity	initial	covers JSON-readable media/roll fallbacks; browser skip timing remains later
`engine/contrib/conformance/test_conformance.py`	pytest harness binding fixtures + ports	not_started	wire into CI
`engine/contrib/conformance/fixtures/*.json`	canonical envelopes per surface	partial (Tier S + current P1 fixtures)	keep promoting proposal fixtures as implementation lands
`engine/contrib/conformance/proposals/*.json`	forward-compatible proposal envelopes	partial	current set covers carwars garage, piece realization, place accepts, record KvRow, roll fragment, and one UUID-shaped v1.5 wireframe interpretation sample; CLI/Tk can inspect them without promotion
webapp Vitest conformance suite	webapp DOM matches expected for each fixture	not_started	written from fixtures; webapp regression mechanism

§G — Recent reconciliation events¶

A short log of what changed across recent spec / UI / engine releases. Each entry names which layer moved and what the consequence is for the others.

2026-05 — spec v1.5 (L1 update only)¶

Adopted the v1.4 genre-audit additions: journal-as-narrative, per-cursor projection of shared state, and the genre extension index. Impact: no new top-level vocabulary surfaces; improves authoring discipline and cross-demo traceability.
Reconciled v1.4 language with repo-current implementation status. Impact: typed Accepts and UIHints are described as implemented; Blocker, InterpretationFragment, typed info metadata, and Tier P2 widgets remain pending or partial.
Updated the fixture inventory to match the current repository, including compose_payload.json and the existing proposal fixture set.
Imported and vetted Tier P3 extension docs for CarWars, credentials, training, and elefant_hunt, plus GENRE_AUDIT_NOTES.md. Impact: genre enrichments are advisory over core v1.5; no _common/EXTENSIONS.md until a repeated cross-genre pattern is not already covered by the core vocabulary.
Archived the v1.5 wireframe package under docs/src/design/story/wireframes/v1_5/. Impact: visual coverage now matches the reconciled v1.5 vocabulary and Tier P3 extension docs; most wireframe fixtures remain design fixtures until their symbolic ids are translated for engine conformance.
Translated one v1.5 wireframe interpretation sample into engine/contrib/conformance/proposals/ with UUID-shaped ids. Impact: future ports have a concrete command-feedback fixture without promoting the whole wireframe bundle to gating conformance.

2026-05 — spec v1.3 (L1 update only)¶

Reverted accepts.kind="select" rename → pieces. Impact: L2/L3 may continue using pieces; no migration needed.
Demoted §1.5 cursors and §1.6 info channels to Tier P1. Impact: none on L2/L3 directly; clarifies that current single-cursor behavior is settled, multi-cursor is target.
Replaced GET /story/info/{kind} with query-descriptor model. Impact: L2 evolves the /story/info endpoint; no L1 break since the v1.2 URL form was never shipped.
Added §0.7 three-layer architecture. Impact: this document exists.
EXTENSIONS.md swept tokens → pieces. Impact: carwars Tier P3 conventions now consistent with main spec.

2026-05 — webapp v1.3 reference UI update¶

Reference webapp uses accepts.kind="pieces" throughout (15+ call sites).
Reference webapp implements InfoAffordance.query as an opaque JSON descriptor on /story/info?kind=...&query=....
Reference webapp accepts nested metadata.info_state. This row is superseded by the v1.5 update, where dirty_kinds became an implemented cache hint in the reference client.
Reference webapp ships place accepts kind without edge_ref (proposal fixture not yet exercised).

2026-05 — webapp v1.5 reference UI reconciliation¶

Reference webapp renders InterpretationFragment with the spec’s result, text, message, blocked_reason, hint, and candidates fields. Impact: command-resolution feedback no longer falls through to the unknown-fragment fallback.
Reference webapp renders typed blockers[] and plural cost_previews[] as choice decision details. Impact: locked choices expose more of the decision-legibility contract in the current shell.
Reference webapp posts edge_id to /story/do. Impact: client and endpoint server now use the same choice-edge identifier name.
Reference webapp treats metadata.info_state.dirty_kinds as cache hints for /story/info. Impact: the sidebar keeps old refresh behavior when no hint is provided, but skips clean side-channel refreshes when the backend sends explicit dirty-kind metadata. The tests cover both default status and selected affordance kinds.
Reference CLI/Tk ports render or inspect blockers, cost previews, typed accepts prompts, and v1.5 interpretation fields. Impact: new client ports can compare against portable JSON fixtures and proposal fixtures instead of copying the Vue shell.

2026-05 — engine current (L3 baseline)¶

Engine emits typed Accepts and UIHints models from tangl.journal.intent; blockers remain dictionary-shaped pending the next intent pass.
Engine HTTP body uses edge_id.
Engine KvFragment.content, projected kv_list values, web fixtures, and conformance fixtures use the unified KvRow record shape.
Engine has no /story/info/{kind} (consistent with v1.5 spec).

§H — How to use this doc¶

Spec authors. When you commit a vocabulary change, update the appropriate row’s “Spec tier” column and add a one-paragraph entry to §G. The implementation columns lag deliberately.
Reference UI authors. When the webapp implements a surface, update the “Reference UI” column to done or partial. If you’re implementing against a fixture (not against a live engine), use partial and note the fixture in the Plan column.
Engine authors. When the engine ships a typed shape or endpoint, update the “Engine backend” column. If you’re shipping the engine capability but not the API endpoint, that’s still progress — the capabilities table in ENGINE_CAPABILITIES.md (forthcoming) tracks Python surface separately.
CLI port authors. Watch §A and §B; you don’t care about §E. Your conformance is against cli_reference_port.py and the §F harness.

A row becomes a candidate for the §G log when any column moves. A surface becomes a candidate for Tier S graduation when all three implementation columns read done and the CLI reference port renders it.

§I — Forward-looking sequence¶

This is the inversion plan the project committed to: UI leads, API + engine chase. Each step’s deliverable is a single PR-shaped change to the named layer.

Phase 1 — Stabilize spec (current).

✅ Spec v1.5 with the v1.4 genre-audit additions reconciled to repo state.
✅ EXTENSIONS.md swept to pieces.
✅ Tier P3 extension docs imported and vetted for current demo genres.
✅ This reconciliation doc as the three-layer spine.

Phase 2 — Reference UI catches up. Wireframes and webapp align to v1.5.

✅ Wireframes resync: v1.5 bundle is archived under docs/src/design/story/wireframes/v1_5/, with v1.2/v1.3 treated as visual precedent rather than contract truth.
✅ The v1.5 wireframe annotates core vocabulary separately from Tier P3 enrichments (stat_check, drag, validity_check, encounter_check), keeping contract conformance and genre flavor separable.
Webapp PR sequence:
1. ✅ compose accepts rendering as nested ChoiceInputView.
2. ✅ InterpretationFragment renderer with the spec’s result / text field names.
3. ✅ metadata.info_state behavior pass: use nested dirty_kinds / available_kinds as cache hints once the backend emits them.
4. Keep info_affordances opaque; clients pass query descriptors through rather than parsing bundle-specific fields.

Phase 3 — Engine + API catch up. Backend declares capabilities, API maps them.

Engine PR sequence:
1. Typed Blocker model in tangl/journal/intent.py.
2. Typed InterpretationFragment with result / text fields.
3. Typed metadata.grammar model.
4. HTTP API: type responses on /story/do / /story/update.
5. Conformance harness: ✅ initial legibility.py; ✅ initial input-parity parity.py; ✅ initial time_parity.py; ✅ CLI-floor info-channel reachability; next add browser timing E2E only after promoted surfaces stabilize.

Phase 4 — Tier P1 → S graduation. Surfaces in §B promote one at a time, gated on the CLI reference port and the conformance harness having coverage for each.

Phase 5 — Tier P2 surfaces gate on bundle MVPs. Each Tier P2 surface (multi-cursor, pieces with position, edge_ref, predicate registration) waits for a real bundle author who needs it. We do not pre-build these.

End of v0.2.