Skip to content

Hard-assert the live wire contract (#937 item 4) - #1248

Merged
neuromechanist merged 1 commit into
devfrom
fix/contract-live-hardfail
Sep 3, 2026
Merged

neuromechanist merged 1 commit into
devfrom
fix/contract-live-hardfail

Conversation

@neuromechanist

Copy link
Copy Markdown
Contributor

Summary

The last warn-only gap in the wire-contract enforcement chain (#938 shared contract, #1224 route-level validation, #1239 OpenAPI generation). Two checks flip to hard asserts, and one stays a warning for a documented reason.

latest_version on the catalog now hard-asserts the canonical vX.Y.Z form. It was warn-only because the deployed dev backend still served bare "1.0.0" while #899 was in flight, and a hard assert would have redded integration-dev during the very PR that shipped the fix. Measured against api-test.nemar.org on 2026-09-03: all 7 rows serve canonical tags, none bare. The warning had nothing left to report and was only costing us the next regression.

The data-plane metadata check was not merely warn-only, it was inert. It defaulted to nm099999, whose metadata.json is 404 on dev, and returned early on the 404, so it validated nothing at all and would have kept passing however far the served shape drifted. It now resolves a dataset that actually serves a data plane (explicit TEST_DATA_DATASET, else the first row the anonymous catalog returns, else the old default), throws rather than returning when there is nothing to validate, and hard-asserts the neuroschema envelope, which passes against every dataset dev serves.

Full JSON-Schema conformance stays warn-only, now for a measured reason rather than an assumed one: fixing the dataset selection surfaced three real drifts in the served data, filed as #1247 and named in the warning. One of them, ORCIDs served bare where neuroschema declares format: uri, is the same mismatch found independently from the website side in nemarOrg/website#294.

Closes #937 item 4. Items 1 and 3 stay open on #937.

Test plan

  • bun run lint, bun run typecheck: clean.
  • Against the live dev backend (TEST_API_URL=https://api-test.nemar.org): 6 pass, 0 fail, with the Data-plane metadata.json fails neuroschema conformance on three fields #1247 conformance warning emitted for xx099903.
  • Gates unchanged: skips with no TEST_API_URL, and skips against prod without TEST_ALLOW_PROD.
  • Both new asserts mutation-proved. Inverting the version filter so it collects canonical values fails the assert. TEST_DATA_DATASET=nm099999 now throws with a message naming the missing data plane, where it previously passed silently.

Closes the last warn-only gap in the wire-contract chain (#937 item 4).

The catalog latest_version check is now a hard assert: it was warn-only while #899 was in flight and the deployed backend still served bare 1.0.0, but that deploy landed long ago and all 7 rows on api-test.nemar.org now serve canonical vX.Y.Z, so the warning had nothing left to report.

The data-plane check was worse than warn-only, it was inert: it defaulted to nm099999, whose metadata.json is 404 on dev, and returned early on the 404, so it validated nothing and would have reported success however far the shape drifted. It now resolves a dataset that actually serves a data plane (TEST_DATA_DATASET, else the first anonymous catalog row, else the old default), throws instead of returning when there is nothing to validate, and hard-asserts the neuroschema envelope, which passes against every dataset dev serves.

Full JSON-Schema conformance stays warn-only because fixing the dataset selection surfaced three real drifts in the served data: publish_date is not RFC 3339 date-time, signal_defaults is not always an object, and ORCIDs are served bare where neuroschema declares format uri (the same mismatch found from the website side in nemarOrg/website#294). Filed as #1247; the warning names it.

Tested: bun run lint, bun run typecheck; the suite against api-test.nemar.org (6 pass, 0 fail, the #1247 warning emitted); skips correctly with no TEST_API_URL and against prod without TEST_ALLOW_PROD. Both new asserts mutation-proved: inverting the version filter fails the assert, and TEST_DATA_DATASET=nm099999 now throws where it used to pass silently.
@github-actions

github-actions Bot commented Sep 3, 2026

Copy link
Copy Markdown

📦 Package Preview

Your package is ready to test!

bun install -g nemar-cli@PR1248

Version: 0.9.16-PR1248.5a4bb7f
Commit: 5a4bb7f


🤖 Updated on each push.

@neuromechanist
neuromechanist merged commit 674a0d8 into dev Sep 3, 2026
12 checks passed
@neuromechanist
neuromechanist deleted the fix/contract-live-hardfail branch September 3, 2026 19:00

This branch was previously deployed

1 inactive deployment
npm — 5a4bb7f3 Deployed Sep 3, 2026 by neuromechanist via publish #2288
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant