feat(schema): code, diff and progress blocks, block semantics, and the lens contract (#15) #17

Merged

peterswimm merged 1 commit from feat/spec-blocks-views-forms into main

2026-10-06 15:19:52 +00:00

peterswimm commented

2026-10-06 15:14:40 +00:00

Owner

Scope

The second part of #15: the parts toilville-design#177 and #189 have decided that need no new endpoint.

schemas/forge_block.json 1.2 adds three block variants:
- code (design #186): one or more files.
- diff (#187): hunks of lines, a status (proposed, applied, rejected, no_change, conflict), base_version, and an apply with a granularity.
- progress (#185): a bar, a step list, or both.
Every block gains an optional semantics object ({intent, importance, variant}). There is no confirm variant: a confirmation is a CEREMONY/critical composition.
New schemas/lens.json 1.0: Personality controls plus per-view block placement, as ville decided in #189.
openapi.yaml 0.63.0 mirrors these.
CHANGELOG cuts 1.4.0. tools/check_schema_registry.py has failed on main since frame_wire 1.4 merged in #14, because the newest release was still 1.3.0. Cutting the release is what that check asks for, but it is a release decision, so change it if you'd rather number it differently.

Differs from #15 as written:

semantics is a nested object, not flat semantic_intent/importance fields, because the Flutter ForgeBlockSemantics and the macOS SemanticIntent.swift already parse "semantics": {"intent", "importance", "variant"}.
The lens has no accent. In #189 ville made accent a mode state signal that no lens can replace, and atmosphere can only be lowered.

Left out:

/views, intent forms, interaction submit and parlay commands: ritual-server serves none of them, and core.block_specs has no surface, actor or provenance columns to store a lens.
wish/parlay in the blocks entity_type enum: the live specs are wishes (plural), and none exist for parlays.
sealed_confirm: not served yet.

Testing

python3 tools/check_schema_registry.py: consistent, 6 files. It fails on main.
python3 -m pytest -q: 18 passed, 1 xfailed.
Validated with jsonschema (Draft 2020-12):
- accepted: a single snippet, a multi-file code block, a proposed and a no_change diff, a progress with steps, a CEREMONY/critical section, and an unknown future intent
- rejected: empty files, value 1.5, an unknown diff status, importance urgent, a lowercase intent, type: confirm, and language Rust
- lens.json rejects an accent, a raw token, a non-user provenance, a negative reduction and an unknown density
The 13 new definitions accept the same payloads in both documents; I compared them with descriptions stripped. That comparison caught an unquoted YAML description that had turned into a property, which is fixed.
Spectral was not run; CI doesn't run it either.

Impact Statement

Existing features: none change. Every new member is optional, and the three blocks are new variants.
Public APIs / contracts: additive. forge_block 1.1 → 1.2, OpenAPI 0.62.0 → 0.63.0, new lens 1.0. A client generated from 1.1 does not recognise the three new block types; both clients already fall back on unknown types.
Schemas: forge_block.json, index.json 1.6, and the new lens.json. No database schema change.
Data / artifacts: ritual-engine's crates/frame-wire-contract vendors this repository's schemas/ and openapi.yaml verbatim, so it should be re-vendored once this merges.
Integrations: none.
Mappings: SemanticIntent mirrors UDG's 11 names, and ImportanceLevel mirrors ImportanceLevel.
Backward compatibility: every payload valid under forge_block 1.1 is valid under 1.2.

Docs

CHANGELOG.md records the additions, the deliberate differences from #15 and what's left out. The schema descriptions carry the #189 limits: density steps, corner radii, the motion ceiling and atmosphere baselines.

## Scope The second part of #15: the parts toilville-design#177 and #189 have decided that need no new endpoint. - `schemas/forge_block.json` 1.2 adds three block variants: - `code` (design #186): one or more files. - `diff` (#187): hunks of lines, a status (proposed, applied, rejected, no_change, conflict), `base_version`, and an `apply` with a granularity. - `progress` (#185): a bar, a step list, or both. - Every block gains an optional `semantics` object (`{intent, importance, variant}`). There is no `confirm` variant: a confirmation is a CEREMONY/critical composition. - New `schemas/lens.json` 1.0: Personality controls plus per-view block placement, as ville decided in #189. - `openapi.yaml` 0.63.0 mirrors these. - `CHANGELOG` cuts **1.4.0**. `tools/check_schema_registry.py` has failed on `main` since `frame_wire` 1.4 merged in #14, because the newest release was still 1.3.0. Cutting the release is what that check asks for, but it is a release decision, so change it if you'd rather number it differently. **Differs from #15 as written:** - `semantics` is a nested object, not flat `semantic_intent`/`importance` fields, because the Flutter `ForgeBlockSemantics` and the macOS `SemanticIntent.swift` already parse `"semantics": {"intent", "importance", "variant"}`. - The lens has no accent. In #189 ville made accent a mode state signal that no lens can replace, and atmosphere can only be lowered. **Left out:** - `/views`, intent forms, interaction submit and parlay commands: `ritual-server` serves none of them, and `core.block_specs` has no surface, actor or provenance columns to store a lens. - `wish`/`parlay` in the blocks `entity_type` enum: the live specs are `wishes` (plural), and none exist for parlays. - `sealed_confirm`: not served yet. ## Testing - `python3 tools/check_schema_registry.py`: consistent, 6 files. It fails on `main`. - `python3 -m pytest -q`: 18 passed, 1 xfailed. - Validated with `jsonschema` (Draft 2020-12): - accepted: a single snippet, a multi-file `code` block, a proposed and a no_change `diff`, a `progress` with steps, a CEREMONY/critical `section`, and an unknown future intent - rejected: empty `files`, `value` 1.5, an unknown diff status, importance `urgent`, a lowercase intent, `type: confirm`, and language `Rust` - `lens.json` rejects an accent, a raw token, a non-user provenance, a negative reduction and an unknown density - The 13 new definitions accept the same payloads in both documents; I compared them with descriptions stripped. That comparison caught an unquoted YAML description that had turned into a property, which is fixed. - Spectral was not run; CI doesn't run it either. ## Impact Statement - Existing features: none change. Every new member is optional, and the three blocks are new variants. - Public APIs / contracts: additive. `forge_block` 1.1 → 1.2, OpenAPI 0.62.0 → 0.63.0, new `lens` 1.0. A client generated from 1.1 does not recognise the three new block types; both clients already fall back on unknown types. - Schemas: `forge_block.json`, `index.json` 1.6, and the new `lens.json`. No database schema change. - Data / artifacts: ritual-engine's `crates/frame-wire-contract` vendors this repository's `schemas/` and `openapi.yaml` verbatim, so it should be re-vendored once this merges. - Integrations: none. - Mappings: `SemanticIntent` mirrors UDG's 11 names, and `ImportanceLevel` mirrors `ImportanceLevel`. - Backward compatibility: every payload valid under forge_block 1.1 is valid under 1.2. ## Docs `CHANGELOG.md` records the additions, the deliberate differences from #15 and what's left out. The schema descriptions carry the #189 limits: density steps, corner radii, the motion ceiling and atmosphere baselines.

peterswimm added 1 commit

2026-10-06 15:14:40 +00:00

feat(schema): code, diff and progress blocks, block semantics, and the lens contract (#15 )

PR policy check / policy-gate (pull_request) Successful in 1s

Details

CI / schema-registry (pull_request) Successful in 10s

Details

4b415d0a1f

forge_block.json 1.2 adds the code, diff and progress variants decided in
toilville-design#177, and an optional semantics object {intent, importance,
variant} on every block, which is the shape the Flutter and macOS clients
already parse. There is no confirm variant: a confirmation is a CEREMONY /
critical composition.

lens.json 1.0 is new: Personality controls (density, corners, motion and an
atmosphere reduction that can only lower the mode's baseline) plus per-view
block placement, following ville's ownership model in toilville-design#189.
It holds no token values and no accent.

openapi.yaml 0.63.0 mirrors the new definitions. CHANGELOG cuts 1.4.0 so the
schema registry check, red on main since frame_wire 1.4, passes.

peterswimm merged commit 0223618c6d into main

2026-10-06 15:19:52 +00:00

peterswimm deleted branch feat/spec-blocks-views-forms

2026-10-06 15:19:52 +00:00

peterswimm referenced this pull request from a commit

2026-10-06 15:19:54 +00:00

Merge pull request 'feat(schema): code, diff and progress blocks, block semantics, and the lens contract (#15)' (#17) from feat/spec-blocks-views-forms into main

peterswimm commented

2026-10-06 22:36:57 +00:00

Author

Owner

Added GET /api/v1/views and GET/PUT/DELETE /api/v1/lens (6db049c), which describe ritual-engine#870. Because this repo only describes served endpoints, merge this after ritual-engine#870 and spel#1041. Checks: openapi-spec-validator passes; tools/check_schema_registry.py passes; pytest 18 passed, 1 xfailed; example ResolvedView and Lens instances validate, and the accent, reduction-3 and provenance: user cases are refused.

Added `GET /api/v1/views` and `GET/PUT/DELETE /api/v1/lens` (6db049c), which describe ritual-engine#870. Because this repo only describes served endpoints, **merge this after ritual-engine#870 and spel#1041**. Checks: openapi-spec-validator passes; `tools/check_schema_registry.py` passes; pytest 18 passed, 1 xfailed; example `ResolvedView` and `Lens` instances validate, and the accent, reduction-3 and `provenance: user` cases are refused.