seam: wire x-polaris-codes into `polaris openapi` #54

New issue

Closed

opened 2026-09-11 10:41:32 +00:00 by bart · 1 comment

bart commented

2026-09-11 10:41:32 +00:00

Collaborator

Why

PH1.4 (#12) builds polaris.contracts.codes.build_x_polaris_codes(), which returns the {findings, errors, notifications} structure that is meant to be attached to the OpenAPI spec under the x-polaris-codes extension key, so the frontend's Transloco key-parity CI check (docs/12-implementation-plan.md "Frontend decoupling rules") can diff against it.

PH1.4 owns only backend/src/polaris/contracts/**, backend/tests/fixtures/snapshots/** and backend/src/polaris/cli/replay_run.py (per its row in docs/12-implementation-plan.md and CLAUDE.md's "don't edit files you haven't edited before" rule). Wiring the extension into the emitted spec means editing backend/src/polaris/cli/openapi.py (currently just spec = create_app().openapi(); out_path.write_text(...)), which belongs to the sealed PH0.2 output, not to PH1.4 -- so per the ticket's own instructions ("if it turns out you'd need to edit a file outside your ownership ... stop and post it as a seam request") that file is left untouched and this ticket is filed instead.

What to change

In backend/src/polaris/cli/openapi.py::run, after building spec, merge in the extension before writing:

from polaris.contracts.codes import build_x_polaris_codes

spec = create_app().openapi()
spec["x-polaris-codes"] = build_x_polaris_codes()

That's the whole change -- build_x_polaris_codes() already exists, is fully unit tested (backend/tests/unit/contracts/test_codes.py), and needs no arguments. Regenerate backend/openapi.json (polaris openapi) in the same PR so the committed spec includes the extension.

Acceptance

backend/openapi.json's top-level object has an x-polaris-codes key with findings/errors/notifications arrays matching polaris.contracts.codes.build_x_polaris_codes().
Ticks the second acceptance-criteria box on #12 (left unchecked there pending this).

Blocks

#12 (acceptance criterion only -- the rest of #12 does not depend on this)

## Why PH1.4 (#12) builds `polaris.contracts.codes.build_x_polaris_codes()`, which returns the `{findings, errors, notifications}` structure that is meant to be attached to the OpenAPI spec under the `x-polaris-codes` extension key, so the frontend's Transloco key-parity CI check (`docs/12-implementation-plan.md` "Frontend decoupling rules") can diff against it. PH1.4 owns only `backend/src/polaris/contracts/**`, `backend/tests/fixtures/snapshots/**` and `backend/src/polaris/cli/replay_run.py` (per its row in `docs/12-implementation-plan.md` and `CLAUDE.md`'s "don't edit files you haven't edited before" rule). Wiring the extension into the emitted spec means editing `backend/src/polaris/cli/openapi.py` (currently just `spec = create_app().openapi(); out_path.write_text(...)`), which belongs to the sealed PH0.2 output, not to PH1.4 -- so per the ticket's own instructions ("if it turns out you'd need to edit a file outside your ownership ... stop and post it as a seam request") that file is left untouched and this ticket is filed instead. ## What to change In `backend/src/polaris/cli/openapi.py::run`, after building `spec`, merge in the extension before writing: ```python from polaris.contracts.codes import build_x_polaris_codes spec = create_app().openapi() spec["x-polaris-codes"] = build_x_polaris_codes() ``` That's the whole change -- `build_x_polaris_codes()` already exists, is fully unit tested (`backend/tests/unit/contracts/test_codes.py`), and needs no arguments. Regenerate `backend/openapi.json` (`polaris openapi`) in the same PR so the committed spec includes the extension. ## Acceptance - `backend/openapi.json`'s top-level object has an `x-polaris-codes` key with `findings`/`errors`/`notifications` arrays matching `polaris.contracts.codes.build_x_polaris_codes()`. - Ticks the second acceptance-criteria box on #12 (left unchecked there pending this). ## Blocks - #12 (acceptance criterion only -- the rest of #12 does not depend on this)

bart added the

ready-for-agent

label

2026-09-11 10:41:32 +00:00

bart referenced this issue

2026-09-11 10:42:19 +00:00

PH1.4 — Engine contracts: PlanningSnapshot, PlanResult, Finding, projector/scorer I/O, task payloads, code lists, fixtures #12

bart referenced this issue from a commit

2026-09-11 10:43:46 +00:00

feat(api): add polaris.contracts frozen models and closed code lists

bart referenced this issue

2026-09-11 10:45:15 +00:00

PH1.4 -- Engine contracts: PlanningSnapshot, PlanResult, Finding, projector/scorer I/O, task payloads, code lists, fixtures #55

bart commented

2026-09-11 10:46:19 +00:00

Author

Collaborator

Fix drafted on feature/openapi-code-catalogue (local, not pushed yet): exactly the two-line change above. Holding off on pushing/opening the PR and regenerating openapi.json — polaris.contracts does not exist on main yet (PR #55 is still open, not merged), so build_x_polaris_codes cannot be imported or verified. Will rebase, regenerate the spec, and open the PR once #55 merges.

Fix drafted on `feature/openapi-code-catalogue` (local, not pushed yet): exactly the two-line change above. Holding off on pushing/opening the PR and regenerating `openapi.json` — `polaris.contracts` does not exist on `main` yet (PR #55 is still open, not merged), so `build_x_polaris_codes` cannot be imported or verified. Will rebase, regenerate the spec, and open the PR once #55 merges.

bart referenced this issue from a pull request that will close it,

2026-09-11 11:23:06 +00:00

build: wire x-polaris-codes into polaris openapi #65

bart referenced this issue from a commit

2026-09-11 11:23:06 +00:00

feat(build): wire x-polaris-codes into polaris openapi

bart referenced this issue from a commit

2026-09-11 11:23:06 +00:00

feat(build): wire x-polaris-codes into polaris openapi

bart referenced this issue

2026-09-11 11:23:18 +00:00

PH1.4 — Engine contracts: PlanningSnapshot, PlanResult, Finding, projector/scorer I/O, task payloads, code lists, fixtures #12