ci(sdk): typecheck both typed SDKs, and catch a pin that drifted from its manifest

[macanderson]

Pull request

Summary

Two guards over sdk/: CI now typechecks the two SDKs that carry type
annotations, and a new offline check catches a version pin that has drifted
from the manifest it names.

Closes #94, Closes #98

What changed

Typechecking (#94)

• sdk (typescript) typechecks — npm ci && npx tsc --noEmit in
  sdk/typescript/, in a job that pulls no Rust toolchain. npm ci so the
  compiler comes from package-lock.json (typescript 5.9.3) rather than from
  whatever ^5.9.0 resolves to today.
• sdk (python) typechecks — mypy --strict --python-version 3.10 over
  contextgraph_sdk and examples, with mypy pinned for the same reason.

The Python half was not skipped, and here is the reasoning. The Python SDK
ships py.typed. That file is a promise to every downstream typechecker that
the package's annotations are meant to be believed, and nothing in this repo
had ever tested it. --strict because a py.typed package that leaks Any
across its own boundary keeps the promise to its callers and not to itself. It
is clean on this tree as written — no code changes were needed.

One correction to #94's premise, stated because the issue's framing is what
sized the work. "Nothing in CI appears to run tsc --noEmit" is right about
--noEmit and not quite right about typechecking: sdk (typescript) is a conformant implementation runs npm run build, which is tsc, and tsc
exits non-zero on a type error, so that job would have failed. The coverage was
incidental rather than absent. It is still worth its own job: it arrives only
after a full cargo build --workspace --bins that has nothing to do with the
question, and it holds only while the build script stays tsc. The new job
asks the question directly and in about a minute.

Version-pin drift (#98)

• .github/scripts/check-sdk-version-pins.py — stdlib only, offline, no
  registry call. Same shape as check-deploy-hygiene.py: a check(label, ok)
  ledger, PASS/FAIL per line, a remedy under each failure.
• sdk version pins name a version their manifest ships — the CI job that runs
  it, separate from the scaffold job for the reason the issue gives.
• docs/adr/0012-sdk-version-pins-share-a-major.md — the rule and why.

The decision the issue asked for: same major, not equality. The pins are
deliberately ranges and differently shaped ones — a caret for npm, a >= floor
for pip. Equality would make every SDK patch release an edit in the scaffolder
that nobody would remember to make, which defeats the range's whole purpose. A
major is the thing a scaffold cannot survive: majors are where the API changes,
and ADR 0011 is the worked example — FrameKind widened in 2.0.0, so a
project scaffolded against a 1.x pin generates code against the vocabulary
that release retired. Same major is the weakest rule that still catches every
break, which is what a guard should be; a stricter one fails on changes that
are correct.

Two things ride along with it, both because the pin rule leans on them:

• A floor may not run ahead of the manifest. ^2.1.0 against a shipped
  2.0.0 resolves to nothing at all — drift in the other direction, and the
  manifest version is the newest release that can exist, because these
  manifests are what publish-sdks.yml publishes.
• The SDKs and the crates share one major. The scaffolder's own comment and
  MIGRATION.md §5.4 both assert this, and ^2.0.0 protects a scaffold from
  ADR 0011 only while it holds. Its practical effect: a major bump is one
  commit across four files rather than four commits with a drift window in
  between.

The other manifests the issue named. sdk/go carries no package version —
a Go module is versioned by its git tag, not by a field in go.mod, and the
scaffolder emits no Go template, so there is no in-tree pin to compare against;
its ProtocolVersion is a protocol version, a different axis. The
"version": "1.0.0" strings in schema/reference-vectors.ndjson are provider
versions in fixtures and are untouched — rewriting them would change the bytes
the reference vectors pin. Both verdicts are recorded in the script's header
and in the ADR, so the next reader does not re-derive them.

Two drive-by fixes, both one line, both about a name a manifest does not
own:

• MIGRATION.md §5.4 called the TypeScript package @contextgraph/sdk. The
  published name is @contextgraphprotocol/typescript-sdk.
• CHANGELOG.md gains the two [Unreleased] entries.

Evidence

Every command below was run in this branch's worktree.

tsc --noEmit — clean, then deliberately broken, then reverted. The break
pushes a string that is not a KnownFrameKind into KNOWN_FRAME_KINDS, the
exact shape of type the PR #87 changes introduced:

### clean:
exit=0
### with a deliberate type error:
src/types.ts(40,3): error TS2322: Type '"definitely-not-a-known-kind"' is not assignable to type 'KnownFrameKind'.
exit=2
### reverted:
exit=0

mypy --strict --python-version 3.10 — same three states, the break being
a function annotated -> int that returns its str argument:

### clean:
Success: no issues found in 7 source files
exit=0
### with a deliberate annotation break:
contextgraph_sdk/budget.py:24: error: Incompatible return value type (got "str", expected "int")  [return-value]
Found 1 error in 1 file (checked 7 source files)
exit=1
### reverted:
Success: no issues found in 7 source files
exit=0

The version-pin guard on this tree — python3 .github/scripts/check-sdk-version-pins.py, exit=0:

the scaffolder's default pins agree with the SDK manifests they name
  PASS  DEFAULT_SDK is readable in the scaffolder
  PASS  the TypeScript template takes its SDK dependency from DEFAULT_SDK
  PASS  the Python template takes its SDK dependency from DEFAULT_SDK
  PASS  typescript pin shares the major sdk/typescript/package.json ships
  PASS  typescript pin does not name a version sdk/typescript/package.json has never shipped
  PASS  the Python pin names the package sdk/python publishes
  PASS  python pin shares the major sdk/python/pyproject.toml ships
  PASS  python pin does not name a version sdk/python/pyproject.toml has never shipped

the SDK majors move in lockstep with the crates
  PASS  every versioned manifest states an x.y.z version
  PASS  the SDKs and the crates share one major

OK — no version drift

The guard against the drift #98 actually recorded — DEFAULT_SDK.typescript
put back to ^0.1.0, exit=1:

  FAIL  typescript pin shares the major sdk/typescript/package.json ships
        pin '^0.1.0' names major 0; sdk/typescript/package.json ships 2.0.0
        remedy: move the pin in sdk/create-contextgraph-provider/index.js's DEFAULT_SDK onto 2.0.0,
        or explain the split in docs/adr/0012-sdk-version-pins-share-a-major.md.

Reverted, and green again — the last block above is the tree as pushed.

Six more drift shapes, each introduced, run, and reverted. Every one exits
1; the failing line is quoted:

Drift introduced	Failing check
Python pin >=1.0.0 against a 2.0.0 manifest	python pin shares the major sdk/python/pyproject.toml ships
TS pin ^2.1.0 when only 2.0.0 exists	typescript pin does not name a version sdk/typescript/package.json has never shipped
TS template hardcodes ^2.0.0 instead of {{SDK_SPEC}}	the TypeScript template takes its SDK dependency from DEFAULT_SDK
sdk/python alone bumped to 3.0.0	both python pin shares the major … and the SDKs and the crates share one major
TS pin <2.0.0 — a ceiling, not a floor	typescript pin is a floor this check can read
Python pin renamed to contextgraph>=2.0.0	the Python pin names the package sdk/python publishes

git status --porcelain after the last revert showed only the new files, and
the guard was green again.

Checklist

• One logical change per PR (smaller lands faster)
• Gate is green locally — fmt, clippy -D warnings, test
  — not run, and deliberately. This PR touches no Rust: the diff is one
  workflow, one Python script, and three markdown files. SCR-001 says build
  only what the change touches, and nothing here compiles. CI runs the Rust
  gate on the push.
• A witness test is included, or a reason there isn't one is stated below
  — the Evidence section is the witness for both guards: each is shown
  failing on the drift it exists for and passing once it is reverted. There
  is no #[test] because neither guard is Rust; the equivalent proof is the
  before/after run.
• Docs updated in the same PR if behavior or flags changed (README.md,
  docs/, doc comments, --help text) — ADR 0012, and the guard's own
  header carries the rationale the way check-deploy-hygiene.py does.
• All commits signed off (git commit -s, DCO)
• CHANGELOG.md updated under [Unreleased] if user-visible

Registry submission (only if adding a row to docs/registry.md)

• Not applicable — this PR does not add/change a conformance registry entry

Protocol-stability impact (if a spec/wire change)

• Not applicable — no wire or spec change

License

By submitting this pull request, I agree to dual-license this contribution
under MIT OR Apache-2.0, as certified by my DCO sign-off.

[sourcery-ai]

Sorry @macanderson, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 16 hours and 12 minutes by commenting @sourcery-ai review. Upgrade to get a review now.

[sourcery-ai]

Reviewer's Guide

The PR adds standalone CI jobs to typecheck the TypeScript and Python SDKs, plus an offline standard-library guard that verifies scaffolder pins, template indirection, SDK manifest compatibility, and SDK/crate major-version lockstep; accompanying ADR, changelog, and package-name documentation are updated.

Flow diagram for offline SDK version-pin validation

flowchart TD
    Start[Run check-sdk-version-pins.py] --> Parse[Read DEFAULT_SDK and SDK manifests]
    Parse --> Templates[Verify templates use SDK_SPEC]
    Templates --> Pins[Parse TypeScript and Python dependency floors]
    Pins --> Compatibility{Same major and not ahead?}
    Compatibility -->|No| Fail[Print FAIL and exit 1]
    Compatibility -->|Yes| Lockstep{SDK and crate majors match?}
    Lockstep -->|No| Fail
    Lockstep -->|Yes| Pass[Print OK and exit 0]

Loading

File-Level Changes

Change	Details	Files
Add direct CI typechecking for both annotated SDKs.	Run TypeScript npx tsc --noEmit in an isolated Node job. Run pinned mypy --strict --python-version 3.10 across the Python SDK and examples. Keep the checks independent of the Rust build and document the Python py.typed rationale.	.github/workflows/ci.yml CHANGELOG.md
Introduce an offline guard for SDK version-pin drift and enforce shared major versions.	Parse the scaffolder's DEFAULT_SDK, both SDK manifests, templates, and the Cargo workspace version using only the standard library. Require template dependencies to use {{SDK_SPEC}}, pins to match the published package and share its major, and floors not to exceed the manifest version. Require TypeScript, Python, and workspace crate manifests to use parseable versions with one shared major; emit per-check PASS/FAIL diagnostics and remedies. Run the guard in its own CI job and document the policy, rationale, and intentionally excluded version sources in ADR 0012.	.github/scripts/check-sdk-version-pins.py .github/workflows/ci.yml docs/adr/0012-sdk-version-pins-share-a-major.md
Correct SDK naming and record the new CI safeguards in project documentation.	Replace the outdated TypeScript package name with @contextgraphprotocol/typescript-sdk. Add unreleased changelog entries for SDK typechecking and version-pin drift detection.	MIGRATION.md CHANGELOG.md

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#94	Add an independent CI job that runs npx tsc --noEmit in sdk/typescript/, and verify that the SDK passes, fails on a deliberate type error, and passes again after reverting it.	✅
#94	Explicitly provide equivalent typechecking coverage for sdk/python/ and verify that it passes, fails on a deliberate annotation error, and passes again after reverting it.	✅
#94	Satisfy the CI/documentation requirements for the new jobs: pin or explain floating tool versions and record the jobs in CHANGELOG.md under [Unreleased].	❌	The changelog requirement is met, but the TypeScript job uses floating dependencies: actions/checkout@v5, actions/setup-node@v4, Node 22, and npm install without a pinned package-manager/dependency resolution. The Python job uses floating Python 3.12 and floating action versions. The PR explains the floating behavior for some choices, but not every version or tool dependency as required by the issue.
#98	Decide and document the version-drift rule for scaffolder SDK pins, including why same-major compatibility is used instead of exact equality and how the other named manifests are treated.	✅
#98	Add an offline guard under .github/scripts/ that checks DEFAULT_SDK against the TypeScript and Python SDK manifests, detects stale or ahead-of-manifest pins, provides actionable remediation output, and records the verdict for sdk/go and reference-vector versions.	✅
#98	Run the guard as a separate CI job rather than in the local-path scaffold job, ensure it passes on the current tree, demonstrate failure and recovery for the recorded TypeScript drift, and document the guard in the changelog.	✅

Possibly linked issues

• Nothing catches version drift between an SDK manifest and the scaffolder that pins it #98: The PR directly adds and runs the requested offline guard, documents the rule, checks exclusions, and records changelog updates.
• Typecheck the TypeScript SDK in CI #94: PR adds standalone tsc --noEmit and mypy jobs, validates deliberate failures, pins tools, and updates the changelog.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[macanderson]

Settling the one ❌ — "pin or explain every version the new jobs depend on" (#94)

Sourcery is half right, and the half it is right about is now fixed.

Fixed — the compiler was floating, and it should not have been. The
TypeScript job ran npm install, so it resolved typescript: "^5.9.0" to
whatever npm serves that day. That is exactly the hazard the comment beside the
mypy pin describes ("an unpinned strict typechecker turns each of its releases
into a possible red main on code nobody touched"), and I applied the reasoning
to one job and not the other. c11e8e6 switches it to npm ci, which resolves
sdk/typescript/package-lock.json exactly:

$ npm ci && npx tsc --version && npx tsc --noEmit
added 3 packages in 3s
Version 5.9.3
exit=0

The conformance jobs keep npm install on purpose. They ask whether the SDK
still behaves, not whether one compiler release still accepts it, so a resolved
patch is signal there rather than noise.

Answered — the action tags and runtime versions are the repository's
convention, not an omission in this PR. actions/checkout@v5,
actions/setup-node@v4, actions/setup-python@v5, node-version: "22" and
python-version: "3.12" are what every one of the twenty other jobs in
ci.yml already uses. Pinning these two jobs to SHAs or to patch versions
would make them the only jobs in the file that do, which trades a small
supply-chain gain for a convention that then holds nowhere else. Whether this
repository should pin actions by SHA is a real question and a repo-wide one —
it belongs in a PR that changes all twenty-two jobs together, not in two of
them.

The runtime version has a second, separate hole that this PR did not open and
does not close: python-version: "3.12" is pinned, and sdk/python's
requires-python says >=3.9, so the three oldest interpreters the package
claims are tested by nothing. That is filed as #107 with a reproduction and two
alternative fixes, and #108 covers the other residue found here.

[macanderson]

@sourcery-ai review

[sourcery-ai]

Sorry @macanderson, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 15 hours and 57 minutes by commenting @sourcery-ai review. Upgrade to get a review now.

[macanderson]

Sourcery's assessment table cannot be refreshed on this head: the re-review request came back you've used your own review budget of 250,000 diff characters for the last 7 days, available again in about 16 hours.

So the standing ❌ row is now stale in the part it is most specific about — it names npm install in the TypeScript job, and c11e8e6 replaced that with npm ci. The rest of the row (action major tags, Node 22, Python 3.12) is answered in the comment above: those are the convention every other job in ci.yml follows, and changing them is a repo-wide PR rather than two jobs going their own way.