feat(spec): POST /api/v1/intents/{name}/run and form on patterns (0.67.0) #21

Merged

peterswimm merged 1 commit from feat/spec-intent-run into main

2026-10-09 17:43:30 +00:00

peterswimm commented

2026-10-09 17:40:16 +00:00

Owner

Part of ritual-engine#906 (toilville-design#177). This documents POST /api/v1/intents/{name}/run, which ritual-engine#907 serves over spel#1100's contract.

Scope

openapi.yaml 0.67.0:
- POST /api/v1/intents/{name}/run (runIntent, tag patterns), with {inputs?, run_id?, dry_run?}.
  - Idempotent on run_id.
  - dry_run validates and writes nothing.
  - The description gives the validation rules: a person acting for themselves; no reserved, unknown or malformed inputs; defaults filled.
  Outcome Status
  
  applied, duplicate, valid 200
  
  rejected 409, with reason and errors
  
  failed 500, with reason; the run is recorded
  
  no such intent 404
  
  malformed request 422
- form on PatternSchema: a nullable CommandForm naming the intent's generated command_form view. Its button's action_id is intent:run.
- validatePattern is marked deprecated for intents, in favour of runIntent with dry_run: true. It is still served.
- New schemas: IntentRunRequest and IntentRunResult.
CHANGELOG.md: Added and Deprecated entries under Unreleased.

Outcome	Status
`applied`, `duplicate`, `valid`	200
`rejected`	409, with `reason` and `errors`
`failed`	500, with `reason`; the run is recorded
no such intent	404
malformed request	422

Testing

openapi-spec-validator: the document is valid.
Result shapes from the spel#1100 rehearsal against IntentRunResult (Draft 2020-12, with format checks):
- applied, rejected (with the citation form's x-messages error), duplicate and a valid dry run all validate;
- a control with outcome running, which is internal to the contract and never returned by the route, is rejected.
PatternSchema validates with form both null and set.
tools/check_schema_registry.py reports the registry is consistent. pytest: 18 passed, 1 xfailed, as on main.

Impact Statement

Existing features: None changed. validatePattern is still documented and served, now marked deprecated.
Public APIs / contracts: documents one new endpoint, plus an additive form field on getPattern's response.
Schemas: adds two component schemas; PatternSchema gains form. No file under schemas/ changes.
Data / artifacts: None.
Integrations: generated clients gain runIntent. The Swift client's submitRitual moves to it in #906's step 4.
Mappings: an intent form's input action_ids are IntentRunRequest.inputs keys, and intent:run maps to runIntent.
Backward compatibility: additive, minor version bump.

Part of ritual-engine#906 (toilville-design#177). This documents `POST /api/v1/intents/{name}/run`, which ritual-engine#907 serves over spel#1100's contract. ## Scope - **`openapi.yaml` 0.67.0:** - **`POST /api/v1/intents/{name}/run`** (`runIntent`, tag `patterns`), with `{inputs?, run_id?, dry_run?}`. - Idempotent on `run_id`. - `dry_run` validates and writes nothing. - The description gives the validation rules: a person acting for themselves; no reserved, unknown or malformed inputs; defaults filled. | Outcome | Status | |---|---| | `applied`, `duplicate`, `valid` | 200 | | `rejected` | 409, with `reason` and `errors` | | `failed` | 500, with `reason`; the run is recorded | | no such intent | 404 | | malformed request | 422 | - **`form` on `PatternSchema`:** a nullable `CommandForm` naming the intent's generated `command_form` view. Its button's `action_id` is `intent:run`. - **`validatePattern` is marked deprecated** for intents, in favour of `runIntent` with `dry_run: true`. It is still served. - New schemas: `IntentRunRequest` and `IntentRunResult`. - **`CHANGELOG.md`:** Added and Deprecated entries under Unreleased. ## Testing - `openapi-spec-validator`: the document is valid. - **Result shapes from the spel#1100 rehearsal against `IntentRunResult`** (Draft 2020-12, with format checks): - `applied`, `rejected` (with the citation form's `x-messages` error), `duplicate` and a `valid` dry run all validate; - a control with outcome `running`, which is internal to the contract and never returned by the route, is rejected. - `PatternSchema` validates with `form` both null and set. - `tools/check_schema_registry.py` reports the registry is consistent. `pytest`: 18 passed, 1 xfailed, as on main. ## Impact Statement - **Existing features:** None changed. `validatePattern` is still documented and served, now marked deprecated. - **Public APIs / contracts:** documents one new endpoint, plus an additive `form` field on `getPattern`'s response. - **Schemas:** adds two component schemas; `PatternSchema` gains `form`. No file under `schemas/` changes. - **Data / artifacts:** None. - **Integrations:** generated clients gain `runIntent`. The Swift client's `submitRitual` moves to it in #906's step 4. - **Mappings:** an intent form's input `action_id`s are `IntentRunRequest.inputs` keys, and `intent:run` maps to `runIntent`. - **Backward compatibility:** additive, minor version bump.

peterswimm added 1 commit

2026-10-09 17:40:16 +00:00

feat(spec): POST /api/v1/intents/{name}/run and form on patterns (0.67.0)

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

Details

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

Details

ba199bb902

peterswimm merged commit f8ec7db607 into main

2026-10-09 17:43:30 +00:00

peterswimm deleted branch feat/spec-intent-run

2026-10-09 17:43:30 +00:00