Task 5: OpenAPI vendoring and contract check (spike with decision) (#5) #38

Merged
charles merged 2 commits from task/5-openapi-vendor-contract into foundation 2026-11-11 09:07:51 +00:00
Owner

What this builds

  • cargo xtask vendor-spec --from <path-or-url> (xtask/src/vendor_spec.rs): copies the fork's generated openapi.json byte for byte into crates/fluxer-proto/spec/openapi.json and writes spec/SOURCE (fork commit <sha>, -dirty if the file differs from that commit; url <url> <date>; file <path> <date> outside a checkout). Refuses anything that is not an OpenAPI 3 document with components.schemas.
  • cargo xtask spec-check (xtask/src/spec_check.rs): runs the contract test.
  • The vendored document: OpenAPI 3.1.0, 1,853,768 bytes, 715 schemas, 347 paths, from the local fork checkout at ba98441b (the file is tracked in the fork, so the generator was not run).
  • crates/fluxer-proto/tests/spec_contract.rs::hand_written_models_match_spec_schemas for UserPartial, Guild, Channel, Message, Role, GuildMember: every model field is a schema property; every required property is a model field; a required non-nullable property is not an Option; a required nullable one is accepted as null. Plus vendored_spec_records_its_source.
  • Spike decision: models stay hand-written, typify is not adopted (recorded with the measurements in crates/fluxer-proto/README.md). typify 0.8.0 over all of components.schemas emits ~35,700 lines that do not compile (166 errors; seven schemas defined twice or infinitely recursive). Cut by hand to the 50 schemas the four key types reach it compiles, but every struct is deny_unknown_fields, integer enums reject unknown values, and referenced_message loses absent-vs-null — all against the Global Constraints.

How it was tested

  • Contract test written first and seen failing (no spec vendored), then passing after vendoring. No model changes were needed: the Task 3 models already agree with the document.
  • Mutation check (not committed): edited the document and the allowlists to add a required property, remove a property, require an Option field and add a stale allowlist entry; each was reported.
  • Unit tests in vendor_spec.rs (validation, verbatim copy, SOURCE, a rejected document is not written); xtask/tests/ci_smoke.rs updated (the two subcommands are no longer "not implemented"; vendor-spec without --from is a usage error).
  • cargo xtask ci green locally on Linux.

Deviations from the plan

  • Schema name: the document has MessageResponseSchema, not MessageResponse (the plan said to adjust).
  • The plan's "every required property is a non-Option field" cannot hold literally: GuildResponse requires twelve properties Foundation does not model, and several required properties are nullable. The test keeps the intent with two exact allowlists (not_modelled: those twelve; not_in_spec: Guild::joined_at and Guild::unavailable, gateway-only state) whose stale entries fail, and it checks nullable required properties accept null instead of demanding non-Option.
  • URL download shells out to curl instead of adding reqwest (blocking) to xtask: no HTTP/TLS stack in a crate every CI run builds, and no clash with Task 6, which introduces reqwest to the workspace.
  • Files touched outside the task's list, all needed to wire the subcommands: xtask/src/main.rs (dispatch, --from), xtask/Cargo.toml + Cargo.lock (serde_json, time, both already workspace dependencies), xtask/tests/ci_smoke.rs, xtask/README.md, crates/fluxer-proto/README.md.

For the reviewer

  • SOURCE names the fork checkout's HEAD; the document itself last changed in fork commit bcfed66b (2026-10-30). One later fork commit touched schema sources the same day, so the tracked document may lag the schemas slightly; regenerating means running pnpm openapi:generate inside the fork, which this task must not modify.
  • fixtures/rest/guild.json omits four properties GuildResponse requires and user_me.json omits many UserPrivateResponse ones. The fixtures are deliberately trimmed, so this is not treated as a bug; the contract test does not validate fixtures against the document.

Closes #5

🤖 Generated with Claude Code

## What this builds - `cargo xtask vendor-spec --from <path-or-url>` (`xtask/src/vendor_spec.rs`): copies the fork's generated `openapi.json` byte for byte into `crates/fluxer-proto/spec/openapi.json` and writes `spec/SOURCE` (`fork commit <sha>`, `-dirty` if the file differs from that commit; `url <url> <date>`; `file <path> <date>` outside a checkout). Refuses anything that is not an OpenAPI 3 document with `components.schemas`. - `cargo xtask spec-check` (`xtask/src/spec_check.rs`): runs the contract test. - The vendored document: OpenAPI 3.1.0, 1,853,768 bytes, 715 schemas, 347 paths, from the local fork checkout at `ba98441b` (the file is tracked in the fork, so the generator was not run). - `crates/fluxer-proto/tests/spec_contract.rs::hand_written_models_match_spec_schemas` for `UserPartial`, `Guild`, `Channel`, `Message`, `Role`, `GuildMember`: every model field is a schema property; every `required` property is a model field; a required non-nullable property is not an `Option`; a required nullable one is accepted as `null`. Plus `vendored_spec_records_its_source`. - **Spike decision: models stay hand-written, `typify` is not adopted** (recorded with the measurements in `crates/fluxer-proto/README.md`). `typify` 0.8.0 over all of `components.schemas` emits ~35,700 lines that do not compile (166 errors; seven schemas defined twice or infinitely recursive). Cut by hand to the 50 schemas the four key types reach it compiles, but every struct is `deny_unknown_fields`, integer enums reject unknown values, and `referenced_message` loses absent-vs-null — all against the Global Constraints. ## How it was tested - Contract test written first and seen failing (no spec vendored), then passing after vendoring. No model changes were needed: the Task 3 models already agree with the document. - Mutation check (not committed): edited the document and the allowlists to add a required property, remove a property, require an `Option` field and add a stale allowlist entry; each was reported. - Unit tests in `vendor_spec.rs` (validation, verbatim copy, SOURCE, a rejected document is not written); `xtask/tests/ci_smoke.rs` updated (the two subcommands are no longer "not implemented"; `vendor-spec` without `--from` is a usage error). - `cargo xtask ci` green locally on Linux. ## Deviations from the plan - Schema name: the document has `MessageResponseSchema`, not `MessageResponse` (the plan said to adjust). - The plan's "every required property is a non-Option field" cannot hold literally: `GuildResponse` requires twelve properties Foundation does not model, and several required properties are nullable. The test keeps the intent with two exact allowlists (`not_modelled`: those twelve; `not_in_spec`: `Guild::joined_at` and `Guild::unavailable`, gateway-only state) whose stale entries fail, and it checks nullable required properties accept `null` instead of demanding non-`Option`. - URL download shells out to `curl` instead of adding `reqwest` (blocking) to xtask: no HTTP/TLS stack in a crate every CI run builds, and no clash with Task 6, which introduces `reqwest` to the workspace. - Files touched outside the task's list, all needed to wire the subcommands: `xtask/src/main.rs` (dispatch, `--from`), `xtask/Cargo.toml` + `Cargo.lock` (`serde_json`, `time`, both already workspace dependencies), `xtask/tests/ci_smoke.rs`, `xtask/README.md`, `crates/fluxer-proto/README.md`. ## For the reviewer - `SOURCE` names the fork checkout's HEAD; the document itself last changed in fork commit `bcfed66b` (2026-10-30). One later fork commit touched schema sources the same day, so the tracked document may lag the schemas slightly; regenerating means running `pnpm openapi:generate` inside the fork, which this task must not modify. - `fixtures/rest/guild.json` omits four properties `GuildResponse` requires and `user_me.json` omits many `UserPrivateResponse` ones. The fixtures are deliberately trimmed, so this is not treated as a bug; the contract test does not validate fixtures against the document. Closes #5 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Refs #5

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
feat(proto): vendor OpenAPI spec and contract-check models
All checks were successful
ci / Windows (x64) (push) Successful in 21s
ci / Windows (x64) (pull_request) Successful in 17s
ci / Linux (x86_64) (push) Successful in 44s
ci / Linux (x86_64) (pull_request) Successful in 52s
ec454914c8
Vendor the fork's generated OpenAPI 3.1 document into crates/fluxer-proto/spec
with cargo xtask vendor-spec --from <path-or-url> (SOURCE records the fork
commit), and make cargo xtask spec-check run the contract test of the
hand-written models against it. Spike decision, recorded in the fluxer-proto
README: typify output is not adopted; the models stay hand-written.

Refs #5

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Author
Owner

Independent review — Task 5 (reviewed at ec45491)

Verdict: APPROVE — 0 blocking, 4 minor. Local cargo xtask ci green (all steps passed, exit 0; remote runners not checked).

What I verified

  • Plan test hand_written_models_match_spec_schemas exists and covers the six-model map. Schema names checked against the vendored file: five match the plan; MessageResponse does not exist, MessageResponseSchema does (the plan allows adjusting names).
  • The test has teeth (mutations in the review worktree, reverted): Role.name made Option -> fails; bogus field on GuildMember -> fails; removing a not_modelled entry -> fails; a stale not_in_spec entry -> fails.
  • Interfaces: cargo xtask vendor-spec --from <path-or-url> and cargo xtask spec-check exist as written. Re-vendoring from the fork checkout leaves the tree clean; spec/openapi.json is byte-identical to the fork's file (OpenAPI 3.1.0, 715 schemas, 347 paths, 1,853,768 bytes); SOURCE = fork HEAD ba98441b, clean.
  • URL path (not exercised by the implementer): tested against a local python -m http.server — success writes url <url> <date> and the contract test still passes; a 404 and a refused connection exit 1 with curl's message and write nothing.
  • Invariants: no change to fluxer-core/fluxer-ui; xtask gains only serde_json and time (already workspace deps, no HTTP/TLS stack); no token-shaped strings in the vendored document; no model changes, so unknown-field/unknown-enum tolerance is untouched. Commits carry Refs #5 and the co-author line; PR title/body follow the contract.
  • Spike decision is recorded in crates/fluxer-proto/README.md with reasons. I did not re-run typify; the stated reasons (deny_unknown_fields, closed enums, lost absent-vs-null) are consistent with the document, where every checked schema has additionalProperties: false.
  • No Review Focus item belongs to this task.

Findings

  1. minor — CLAUDE.md (crate rules) still says "REST types are generated from the vendored OpenAPI document". The spike decided the opposite; the agent contract should be updated so later tasks do not try to generate.
  2. minor — xtask/src/vendor_spec.rs file_source/git_commit: any git checkout yields fork commit <sha>, including this repo or an unrelated one, and the sha is the checkout's HEAD rather than the commit that produced the file. A gitignored source file also reports clean (git status --porcelain prints nothing for ignored files), so the -dirty marker can be missed.
  3. minor — SOURCE is parsed by whitespace in tests/spec_contract.rs::vendored_spec_records_its_source and in the xtask unit test vendoring_a_file_copies_it_verbatim_and_writes_source. A file <path> <date> line whose path contains a space fails both; the unit test would fail on a Windows runner whose temp dir has a space in it.
  4. minor — The contract deviates from the plan's literal rule, in a documented way: 12 required GuildResponse properties sit in not_modelled, and the "non-Option" check goes through serde, so fields using null_to_default (e.g. features, flags, Role.color) accept a null the document forbids. That is lenient in the direction the "never panic" rule wants; noting it so nobody reads the test as strict validation.

Suggest a follow-up issue for 1-3 before or after merge; none of them blocks.

## Independent review — Task 5 (reviewed at ec45491) **Verdict: APPROVE — 0 blocking, 4 minor. Local `cargo xtask ci` green (all steps passed, exit 0; remote runners not checked).** ### What I verified - **Plan test** `hand_written_models_match_spec_schemas` exists and covers the six-model map. Schema names checked against the vendored file: five match the plan; `MessageResponse` does not exist, `MessageResponseSchema` does (the plan allows adjusting names). - **The test has teeth** (mutations in the review worktree, reverted): `Role.name` made `Option` -> fails; bogus field on `GuildMember` -> fails; removing a `not_modelled` entry -> fails; a stale `not_in_spec` entry -> fails. - **Interfaces**: `cargo xtask vendor-spec --from <path-or-url>` and `cargo xtask spec-check` exist as written. Re-vendoring from the fork checkout leaves the tree clean; `spec/openapi.json` is byte-identical to the fork's file (OpenAPI 3.1.0, 715 schemas, 347 paths, 1,853,768 bytes); `SOURCE` = fork HEAD `ba98441b`, clean. - **URL path** (not exercised by the implementer): tested against a local `python -m http.server` — success writes `url <url> <date>` and the contract test still passes; a 404 and a refused connection exit 1 with curl's message and write nothing. - **Invariants**: no change to `fluxer-core`/`fluxer-ui`; xtask gains only `serde_json` and `time` (already workspace deps, no HTTP/TLS stack); no token-shaped strings in the vendored document; no model changes, so unknown-field/unknown-enum tolerance is untouched. Commits carry `Refs #5` and the co-author line; PR title/body follow the contract. - **Spike decision** is recorded in `crates/fluxer-proto/README.md` with reasons. I did not re-run typify; the stated reasons (`deny_unknown_fields`, closed enums, lost absent-vs-null) are consistent with the document, where every checked schema has `additionalProperties: false`. - No Review Focus item belongs to this task. ### Findings 1. **minor** — `CLAUDE.md` (crate rules) still says "REST types are generated from the vendored OpenAPI document". The spike decided the opposite; the agent contract should be updated so later tasks do not try to generate. 2. **minor** — `xtask/src/vendor_spec.rs` `file_source`/`git_commit`: any git checkout yields `fork commit <sha>`, including this repo or an unrelated one, and the sha is the checkout's HEAD rather than the commit that produced the file. A gitignored source file also reports clean (`git status --porcelain` prints nothing for ignored files), so the `-dirty` marker can be missed. 3. **minor** — `SOURCE` is parsed by whitespace in `tests/spec_contract.rs::vendored_spec_records_its_source` and in the xtask unit test `vendoring_a_file_copies_it_verbatim_and_writes_source`. A `file <path> <date>` line whose path contains a space fails both; the unit test would fail on a Windows runner whose temp dir has a space in it. 4. **minor** — The contract deviates from the plan's literal rule, in a documented way: 12 required `GuildResponse` properties sit in `not_modelled`, and the "non-Option" check goes through serde, so fields using `null_to_default` (e.g. `features`, `flags`, `Role.color`) accept a `null` the document forbids. That is lenient in the direction the "never panic" rule wants; noting it so nobody reads the test as strict validation. Suggest a `follow-up` issue for 1-3 before or after merge; none of them blocks.
charles force-pushed task/5-openapi-vendor-contract from ec454914c8
All checks were successful
ci / Windows (x64) (push) Successful in 21s
ci / Windows (x64) (pull_request) Successful in 17s
ci / Linux (x86_64) (push) Successful in 44s
ci / Linux (x86_64) (pull_request) Successful in 52s
to d5a8323f23
All checks were successful
ci / Windows (x64) (push) Successful in 33s
ci / Windows (x64) (pull_request) Successful in 30s
ci / Linux (x86_64) (push) Successful in 1m1s
ci / Linux (x86_64) (pull_request) Successful in 1m0s
2026-11-11 09:04:35 +00:00
Compare
charles merged commit e0861b301c into foundation 2026-11-11 09:07:51 +00:00
Sign in to join this conversation.
No description provided.