From 98032f7d9593c496c95562aac4a1c7dd02791ceb Mon Sep 17 00:00:00 2001 From: "napkinstack-agent[bot]" <330339777+napkinstack-agent[bot]@users.noreply.github.com> Date: Sat, 19 Sep 2026 17:53:50 +0200 Subject: [PATCH] =?UTF-8?q?contracts=20=E2=80=94=20compat=20declared:=20a?= =?UTF-8?q?=20frozen=20version=20changed=20is=20proven=20compatible=20by?= =?UTF-8?q?=20oasdiff?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- contracts/MANIFEST.yaml | 21 ++++++++++++++++++++- docs/tooling-profile.md | 2 +- 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/contracts/MANIFEST.yaml b/contracts/MANIFEST.yaml index d3f68d7..9283cd3 100644 --- a/contracts/MANIFEST.yaml +++ b/contracts/MANIFEST.yaml @@ -28,7 +28,26 @@ commands: test: >- uvx --python 3.13 --from pytest==9.1.1 --with pyyaml==6.0.3 --with jsonschema==4.26.0 --with referencing==0.37.0 pytest tests -# compat: # exits 0 when $NSTACK_HEAD_PATH is compatible with $NSTACK_BASE_PATH + # A frozen version changed is proven compatible by oasdiff 1.32.1 (V1). V1 reads this command + # as merged and runs it in the pull request's tree, so it depends on no file of that tree but + # the two documents: a change cannot rewrite its own proof. Each archive is pinned by the + # SHA-256 of the release's checksums.txt. + compat: | + set -eu + case "$(uname -sm)" in + "Linux x86_64") asset=linux_amd64 sum=7c8939fc49b75ee11fec66a5b83b37a2fca6aee109fed85013b1ba2ac2a1ee7f ;; + "Linux aarch64") asset=linux_arm64 sum=32fff58a120f75a723d6c2422444691c37fa6813fed61d23f53dbcb604b30f6d ;; + Darwin*) asset=darwin_all sum=e4d74b7e2dfb9d4819e7fc720c905ec86547e4637ac270a2b0187c0f1fb7187e ;; + *) echo "compat: no pinned oasdiff for $(uname -sm)" >&2; exit 2 ;; + esac + tools="$(mktemp -d)" + trap 'rm -rf "$tools"' EXIT + curl -fsSL -o "$tools/oasdiff.tar.gz" \ + "https://github.com/oasdiff/oasdiff/releases/download/v1.32.1/oasdiff_1.32.1_$asset.tar.gz" + if command -v sha256sum >/dev/null; then hash=sha256sum; else hash="shasum -a 256"; fi + echo "$sum $tools/oasdiff.tar.gz" | $hash -c - >/dev/null + tar -xzf "$tools/oasdiff.tar.gz" -C "$tools" oasdiff + "$tools/oasdiff" breaking --fail-on ERR "$NSTACK_BASE_PATH/openapi.yaml" "$NSTACK_HEAD_PATH/openapi.yaml" docs: readme: README.md diff --git a/docs/tooling-profile.md b/docs/tooling-profile.md index d7c73e1..0336a74 100644 --- a/docs/tooling-profile.md +++ b/docs/tooling-profile.md @@ -21,7 +21,7 @@ | Format validation | Loadable YAML with no traps, conforming GitHub files | check-yaml, yamllint, check-jsonschema | NapkinStack foundation | | Architecture analysis | Support for the fitness functions | `nstack fitness` | NapkinStack foundation | | Contract documents | Each contract document valid in its format, each example what its schema declares | openapi-spec-validator (`check`); pytest and jsonschema (`test`) | The `contracts` module's verbs, with the update to v0.4.0 | -| Contract compatibility | Proving a change to a version someone relies on compatible | | | +| Contract compatibility | Proving a change to a version someone relies on compatible | oasdiff (`breaking --fail-on ERR`), each archive pinned by its SHA-256 | The `contracts` module's `compat`, run by `nstack compat` (V1) | | Framing and verification checks | The discovery, the charter, the cycles and the test sheet, checked | `nstack discover`, `nstack plan`, `nstack pr-check` | NapkinStack foundation | | Loading rules on demand | Playbooks triggered by context | Claude Code skills, generated by `nstack skills` | NapkinStack foundation | | Specialised agents | Independent review, isolated investigation | | |