events stream (#15) #16

Merged

peterswimm merged 1 commit from feat/wish-commands-events-spec into main

2026-10-05 23:12:17 +00:00

peterswimm commented

2026-10-05 23:08:33 +00:00

Owner

Scope

This is the first part of #15. It documents the three endpoints ritual-server now serves for toilville-design#177:

GET /api/v1/wishes/{wish_id}/commands (ritual-engine#847)
POST /api/v1/wishes/{wish_id}/commands, with the same command on Kafka as forge.cmd.wish (ritual-engine#847)
GET /api/v1/events, a resumable SSE stream of wish and parlay facts (ritual-engine#856, merged)

It adds eight component schemas and a streaming tag, and bumps openapi.yaml to 0.62.0.

Where it differs from #15 as written, deliberately. The spec follows the server:

Available commands come from their own endpoint, not from an available_commands[] field on GET /wishes/{id}.
POST is synchronous: 200 for applied/noop/duplicate, 409 with reason for rejected. It does not return 202 {command_id}, because a command form needs the outcome in the response. Producers that can't wait use forge.cmd.wish.
The idempotency key is command_id, the same id the command's fact carries on the stream.
command is a string, not an enum. core.wish_commands is the catalog, and the list endpoint serves it.

Left for later parts of #15: parlay commands, views and lenses (the lens dials are still open in toilville-design#189), intent forms, the code/diff/progress blocks, and semantic_intent/importance. The server serves none of these yet. #15 stays open.

Testing

pytest: 18 passed, 1 xfailed. tools/check_schema_registry.py passes.
spectral lint with spectral:oas reports the same 58 problems before and after (1 error, pre-existing, in JsonValue). The additions introduce no new findings.
Field names, outcomes, status codes and SSE event names were checked against the Rust source:
- ritual-core/src/forge_handlers/wish_command.rs
- ritual-server/src/wish_commands.rs
- ritual-server/src/events_gateway.rs
The command catalog was checked against live core.wish_commands (13 commands).
breaking_change_detector.py was not run. It compares database migrations, needs a database connection, and this change touches none.

Impact Statement

Existing features: none changed; this is purely additive.
Public APIs / contracts: two new paths, eight new schemas, and the forge.cmd.wish command as x-kafka-command.
Schemas: no change to schemas/*.json.
Data / artifacts: none.
Integrations: clients (the Rituals apps, the PWA) can generate against the new paths.
Mappings: LineageFact.payload is untyped. Per-topic payload schemas stay in core.kafka_topics.message_schema, and generating components from that registry is still to do (a #15 acceptance criterion).
Backward compatibility: compatible.

Docs

CHANGELOG.md has the additions, the deliberate differences from #15, and what's not included.

## Scope This is the first part of #15. It documents the three endpoints ritual-server now serves for toilville-design#177: - `GET /api/v1/wishes/{wish_id}/commands` (ritual-engine#847) - `POST /api/v1/wishes/{wish_id}/commands`, with the same command on Kafka as `forge.cmd.wish` (ritual-engine#847) - `GET /api/v1/events`, a resumable SSE stream of wish and parlay facts (ritual-engine#856, merged) It adds eight component schemas and a `streaming` tag, and bumps `openapi.yaml` to 0.62.0. **Where it differs from #15 as written, deliberately.** The spec follows the server: - Available commands come from their own endpoint, not from an `available_commands[]` field on `GET /wishes/{id}`. - POST is synchronous: 200 for `applied`/`noop`/`duplicate`, 409 with `reason` for `rejected`. It does not return `202 {command_id}`, because a command form needs the outcome in the response. Producers that can't wait use `forge.cmd.wish`. - The idempotency key is `command_id`, the same id the command's fact carries on the stream. - `command` is a string, not an enum. `core.wish_commands` is the catalog, and the list endpoint serves it. **Left for later parts of #15:** parlay commands, views and lenses (the lens dials are still open in toilville-design#189), intent forms, the `code`/`diff`/`progress` blocks, and `semantic_intent`/`importance`. The server serves none of these yet. #15 stays open. ## Testing - `pytest`: 18 passed, 1 xfailed. `tools/check_schema_registry.py` passes. - `spectral lint` with `spectral:oas` reports the same 58 problems before and after (1 error, pre-existing, in `JsonValue`). The additions introduce no new findings. - Field names, outcomes, status codes and SSE event names were checked against the Rust source: - `ritual-core/src/forge_handlers/wish_command.rs` - `ritual-server/src/wish_commands.rs` - `ritual-server/src/events_gateway.rs` - The command catalog was checked against live `core.wish_commands` (13 commands). - `breaking_change_detector.py` was not run. It compares database migrations, needs a database connection, and this change touches none. ## Impact Statement - Existing features: none changed; this is purely additive. - Public APIs / contracts: two new paths, eight new schemas, and the `forge.cmd.wish` command as `x-kafka-command`. - Schemas: no change to `schemas/*.json`. - Data / artifacts: none. - Integrations: clients (the Rituals apps, the PWA) can generate against the new paths. - Mappings: `LineageFact.payload` is untyped. Per-topic payload schemas stay in `core.kafka_topics.message_schema`, and generating components from that registry is still to do (a #15 acceptance criterion). - Backward compatibility: compatible. ## Docs `CHANGELOG.md` has the additions, the deliberate differences from #15, and what's not included.

peterswimm added 1 commit

2026-10-05 23:08:33 +00:00

feat(spec): wish command endpoints and the GET /api/v1/events stream (#15 )

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

Details

CI / schema-registry (pull_request) Failing after 5s

Details

a0983c9ade

peterswimm merged commit cee7ffef91 into main

2026-10-05 23:12:17 +00:00

peterswimm deleted branch feat/wish-commands-events-spec

2026-10-05 23:12:17 +00:00