Levandor

Connector ⇄ contracts — verification playbook (local patch + authoritative cargo output)

4 min read

How to build/test the connector against a contract change that PM has committed locally but not yet pushed, and how to read authoritative cargo pass/fail through the rtk shell hook. Reusable for any pmv2 service that pins pmv2-contracts by git rev.

For Agents

Two independent techniques, used together to gate connector work while co-developing pmv2-contracts:

  1. A workspace-root [patch] redirects the pmv2-contracts git source to a local checkout — compile/test against the new shape before the rev is pushed.
  2. Trust rtk proxy cargo … > log + grep, not the rtk hook’s inline summary, for pass/fail.

Technique 1 — verify against un-pushed pmv2-contracts via a local-path [patch]

Problem

The connector pins pmv2-contracts by git rev against a private GitHub repo:

# crates/telegram_connector/Cargo.toml
pmv2-contracts = { git = "https://github.com/wowjeeez/pmv2-contracts", rev = "9ce3975" }

When PM lands an additive contract change (new enum variant / new field) in the local checkout at /Users/levander/coding/pmv2-contracts but hasn’t pushed it yet, you’d normally be blocked: the rev doesn’t exist on the remote, so you can’t bump the pin, and fetching needs a git token. Waiting for the push serializes the two halves of the feature.

Fix — redirect the source to the local checkout

Add a [patch] to the workspace ROOT Cargo.toml (not the crate’s — cargo only honors [patch] from the root manifest of the workspace):

[patch."https://github.com/wowjeeez/pmv2-contracts"]
pmv2-contracts = { path = "/Users/levander/coding/pmv2-contracts" }

The patch key must match the pinned source URL exactly. Cargo now resolves pmv2-contracts to the local path instead of the git rev — so:

  • No network, no git token, no pushed rev needed.
  • The connector compiles/tests against the new contract shape immediately.
  • Connector work proceeds in parallel with the contracts push instead of waiting for it.

Lifecycle (the part that bites you if skipped)

The [patch] and the resulting Cargo.lock delta (the pmv2-contracts source flips to a path source) are temporary local-dev state — never commit them.

Once PM pushes and posts the published rev hash:

  1. Remove the [patch] block from the workspace-root Cargo.toml.
  2. Bump rev = "<published-hash>" in crates/telegram_connector/Cargo.toml.
  3. Re-resolve and rebuild so Cargo.lock points back at the git rev (cargo update -p pmv2-contracts, or just a clean build).
  4. Re-run the gate against the published rev — this is the real green, not the patched one. Only this counts as shippable.

Don't commit the patch or the lockfile delta

The patched Cargo.lock references a machine-local path (/Users/levander/coding/pmv2-contracts) that won’t exist in CI or on another machine. Committing it breaks every other build. Verify git diff Cargo.toml Cargo.lock is clean of the patch before committing.

Only valid for additive changes

This works because the change is additive — the connector’s existing code still compiles, and new code targets the new shape. If the contract change is breaking, you’ll see it here too, which is the point: you catch the integration mismatch before the rev is even published.

Technique 2 — get authoritative pass/fail from cargo through the rtk hook

The rtk shell hook garbles cargo test / cargo clippy output

The rtk Claude-Code shell hook rewrites and summarizes cargo output. During this session it once misreported clippy as “1 error” when the run was actually clean. Do not trust the inline summarized output for a build/test gate.

Authoritative recipe

Run the cargo command through rtk proxy (raw, unfiltered), redirect to a logfile, capture the process exit code, then grep the file:

rtk proxy cargo test > /tmp/cargo_test.log 2>&1; echo $?
rtk proxy cargo clippy --all-targets -- -D warnings > /tmp/cargo_clippy.log 2>&1; echo $?

Then read the truth from the log, not the summary:

  • tests: grep for test result: (e.g. test result: ok. N passed; 0 failed)
  • clippy / compile errors: grep for error[ and error:

Why this and not a pipe

Do not pipe straight into grep (rtk proxy cargo test | grep …). Through a pipe, $? / PIPESTATUS reflects grep’s exit status, not cargo’s — so a failing build with no matching line looks like success (and vice-versa). Redirect to a file, check echo $? from the cargo process directly, then grep the file as a separate step.

For Agents

Quick rule: for any go/no-go cargo gate under the rtk hook → rtk proxy cargo <cmd> > log 2>&1; echo $?, then grep the log. Never gate on the hook’s inline one-line summary.

Worked example

This playbook was used to ship the connector half of per-source spend caps (babylon #730): built/tested the connector against PM’s un-pushed pmv2-contracts change via the local [patch], gated with rtk proxy + logfile, then removed the patch and bumped the pin to the published rev 9ce3975 and re-ran the gate green. See per-source-spend-caps-730.

Graph View

Backlinks