Skip to content

contracts — a frozen contract version is changed only when oasdiff proves it compatible - #32

Merged
napkinstack-agent[bot] merged 1 commit into
mainfrom
contracts/compat-oasdiff
Sep 19, 2026
Merged

napkinstack-agent[bot] merged 1 commit into
mainfrom
contracts/compat-oasdiff

Conversation

@napkinstack-agent

Copy link
Copy Markdown
Contributor

contracts — a frozen contract version is changed only when oasdiff proves it compatible

Part of the validation log, #1 (NapkinStack M10h).


Module

contracts — its manifest only, its description (D24): no module changes beyond it.

  • This pull request touches a single module
  • ⚠️ Cross-module — the cross-module label is required, justification below

Deliverable

Not delivery work: the manifest and the tooling profile only — the line does not apply.

What it changes

catalog-api v1 is consumed by loans: it is frozen. Since v0.4.0, Module checks
refuses any change to it unless the command contracts declares under commands.compat,
as merged, proves the change compatible (nstack compat, V1). Until now nothing was
declared, so any change to v1 was refused. This declares the proof — in a pull request of its
own, because V1 reads it from the base.

  • The comparator: oasdiff 1.32.1, breaking --fail-on ERR, the OpenAPI field's breaking-
    change detector, pinned per platform by the SHA-256 the release's checksums.txt gives.
  • Why the command carries everything itself: V1 reads the command as merged, but runs it
    in the pull request's tree. A script of the module, or a binary installed there by
    bootstrap, would be files the very change it judges could rewrite. The command depends on
    nothing in that tree but the two documents it compares.
  • docs/tooling-profile.md: the Contract compatibility row.

Oracle

docs/os/05-workflow.md §3

  • The success criterion was written before the implementation — the plan's probes P4
    (v1 broken in place → V1 names the property) and P4b (an optional property added →
    proven compatible)
  • It was seen failing, for the right reason — before this change, any edit of v1
    is refused with "no merged compatibility command"
  • It passes now — replayed locally, below; on GitHub by P4 and P4b after the merge

Kind of oracle: fitness function (V1) · other: breaking-change detection


Review budget

  • Lines changed (excluding generated): 23
  • Files touched: 2
  • Within budget
  • ⚠️ Over budget — label required, justification: <generation, mechanical migration,
    mass rename…>

Contracts

  • No contract affected — catalog-api v1 is unchanged; its holder gains the proof that
    will judge its next change
  • Contract consumed — the version is declared in the manifest
  • Contract changed, additive — contract tests green, and nstack compat proving it
    once the version is consumed or stable
  • Contract changed, breaking — expand/contract step no. <1|2|3|4>, ADR linked,
    removal date set

Definition of Done

  • Oracle green
  • Lint, format, types — nothing to lint: YAML, checked by the hooks
  • Unit tests — none applicable
  • Build — nothing is built
  • Contract tests (when there is a contract) — compat replayed on three local branches
  • Fitness functions
  • Integration tests (per risk)
  • Security analysis — the archive's SHA-256 checked before it runs; hooks and gitleaks
  • Accessibility (when there is UI)
  • E2E on critical journeys (criticality high and above)
  • Observability added (criticality high and above)
  • Rollback verified (criticality critical)
  • Affected documentation updated
  • Diff self-reviewed line by line

Test sheet

Not required: the pull request changes no module beyond its description.


Summary

DONE

  • contracts declares commands.compat: oasdiff 1.32.1, fetched and checked per platform,
    comparing the version as merged with the version as changed.
  • The tooling profile names it.

VERIFIED

  • Locally, nstack compat contracts against this branch as the base, on three throwaway
    branches: unchanged → "No frozen contract version changed."; approximateLocation
    renamed in place (P4's shape) → FAIL [V1], oasdiff: "2 error — response-required-
    property-removed"
    on GET /tools and GET /tools/{toolId}; an optional instance added
    to Problem (P4b's shape) → "proven compatible"; a wrong SHA-256 in the merged command →
    the archive refused, FAIL [V1] — the proof fails closed.
  • nstack fitness, nstack pr-scope (0 modules touched, 23/400 lines), nstack pr-check
    (compliant, no sheet, no label); the project's hooks (yamllint on the block); gitleaks; one
    author, napkinstack-agent[bot], with its Agent-Session: trailer.

ASSUMED

  • GitHub keeps serving the v1.32.1 release archives; the pin refuses anything else.

NOT VERIFIED

  • On GitHub: V1 through Module checks — P4 and P4b, the probes that follow this merge.

RISKS

  • A changed frozen version downloads about 7 MB per run; nothing is downloaded otherwise.
  • When the proof cannot run (no network, a wrong pin), V1 reports "a breaking change":
    NapkinStack's message, not this command's — reported in the validation log.

Signals to report

  • I had to look at another module's implementation → a signal of a bad boundary
  • A kernel or playbook rule got in my way for no good reason — not a rule: V1 runs the
    merged command in the pull request's tree, so a proof that calls a file of the module can
    be rewritten by the change it judges. Reported in the validation log.
  • A quality gate blocked without improving quality
  • A rule applied by hand would be worth automating

🤖 Generated with Claude Code

…tible by oasdiff

catalog-api v1 is consumed by loans, so it is frozen (V1): a change to it must be proven
compatible by the command the holding module declares, as merged. Declared here in a pull
request of its own, since V1 reads the proof from the base.

The command depends on no file of the pull request's tree but the two documents: V1 runs it
in that tree, and a script or a binary installed by bootstrap there could be rewritten by
the very change it judges. oasdiff 1.32.1, fetched per platform, each archive checked
against the SHA-256 the release's checksums.txt gives.

Agent-Session: d9d08c03-d66a-408a-b9e2-39932ff3130a
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
@napkinstack-agent
napkinstack-agent Bot requested a review from a team as a code owner September 19, 2026 15:55
@napkinstack-agent napkinstack-agent Bot mentioned this pull request Sep 19, 2026
@napkinstack-agent
napkinstack-agent Bot merged commit 951b390 into main Sep 19, 2026
7 checks passed
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