Repository navigation
contracts — a frozen contract version is changed only when oasdiff proves it compatible - #32
Merged
Merged
Conversation
…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>
Open
napkinstack-admin
approved these changes
Sep 19, 2026
16 of 29 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.cross-modulelabel is required, justification belowDeliverable
Not delivery work: the manifest and the tooling profile only — the line does not apply.
What it changes
catalog-apiv1 is consumed byloans: it is frozen. Since v0.4.0,Module checksrefuses any change to it unless the command
contractsdeclares undercommands.compat,as merged, proves the change compatible (
nstack compat, V1). Until now nothing wasdeclared, 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.
breaking --fail-on ERR, the OpenAPI field's breaking-change detector, pinned per platform by the SHA-256 the release's
checksums.txtgives.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 onnothing in that tree but the two documents it compares.
docs/tooling-profile.md: theContract compatibilityrow.Oracle
(
v1broken in place → V1 names the property) and P4b (an optional property added →proven compatible)
v1is refused with "no merged compatibility command"
Kind of oracle: fitness function (V1) · other: breaking-change detection
Review budget
mass rename…>
Contracts
catalog-apiv1 is unchanged; its holder gains the proof thatwill judge its next change
nstack compatproving itonce the version is consumed or stable
removal date set
Definition of Done
compatreplayed on three local branchesTest sheet
Summary
DONE
contractsdeclarescommands.compat: oasdiff 1.32.1, fetched and checked per platform,comparing the version as merged with the version as changed.
VERIFIED
nstack compat contractsagainst this branch as the base, on three throwawaybranches: unchanged → "No frozen contract version changed.";
approximateLocationrenamed in place (P4's shape) →
FAIL [V1], oasdiff: "2 error — response-required-property-removed" on
GET /toolsandGET /tools/{toolId}; an optionalinstanceaddedto
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 itsAgent-Session:trailer.ASSUMED
NOT VERIFIED
Module checks— P4 and P4b, the probes that follow this merge.RISKS
NapkinStack's message, not this command's — reported in the validation log.
Signals to report
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.
🤖 Generated with Claude Code