fix(client): a 304 confirms a payload rather than establishing one

[XieX]

Summary

Fixes a path in the FDv2 delivery transport that could report a store holding nothing as initialized, which authorizes write_skills("*") to prune every managed SKILL.md on disk. Raised by Bugbot on #87 (comment r4146430929); verified reachable, and traced to two claims that were wider than what happened.

A poll adopted the response ETag after any body that did not raise, and a 304 published a first payload unconditionally. Between them, a body this SDK could not apply — a future intentCode, or a payload-transferred with no recognized intent — lent its etag to the next request, and the 304 that answered it reported the empty committed set as current: initialized, healthy, and with nothing in a 304 to notice it on.

Three claims narrowed:

• payload-transferred reports a commit only when it applied a pending set. A none intent builds none, nor does an unrecognized intentCode, and a foreign payload's contents are declined — those transfers now report nothing, where they reported a commit. They no longer adopt the selector of a payload that was never applied either, which on its own left a store resuming from content it does not hold while every diagnostic read healthy.
• A poll adopts the response ETag only from a body that completed an exchange: a committed payload, or a none intent, which is the server saying the content held is what the etag describes. Gating on the commit alone would have broken the steady state — the none body's etag is how a poll goes from a tiny 200 every interval to a bodiless 304.
• A 304 no longer publishes a first payload. It confirms the payload the store holds; the exchange it stands in for, the none intent, does not publish one either.

Not a new rule: TESTING.md §3.25 already defines is_initialized() as true "once a payload has committed", and §3.21/§3.22 turn prune suppression on it. The spec gains the bullets that were missing for the poll path in launchdarkly/ai-sdks-monorepo#34, and js-ai-sdk carries the identical fix in launchdarkly/js-ai-sdk#104.

test_a_304_before_any_payload_still_releases_wait_for_skills justified the old behavior as "a reconnect with a cached basis", which this transport has no mechanism for — _basis and _etag both start as None with no injection point — so a 304 reaching a store that holds nothing takes a server answering a request that carried no etag at all. It now fails closed, and the test asserts that.

Test plan

• pytest — 2164 passed, 11 skipped
• ruff check / ruff format --check / mypy packages/*/src clean
• New: a body under an unrecognized intent leaves the next request carrying no If-None-Match, the store uninitialized, nothing held, and no selector adopted
• New: all four shapes that reach payload-transferred with no pending set report neither a commit nor an up-to-date answer, and still count the transfer
• Rewritten: a 304 answering a request that carried no etag leaves wait_for_skills false and is_initialized() false without recording a failure
• The over-cap poll test was leaning on the same path for its "delivery carries on" assertion; its retry now gets a real payload

🤖 Generated with Claude Code

---

Note

Overview
Tightens FDv2 poll/stream semantics so an empty or unapplied store cannot be treated as initialized and authorize write_skills("*") to prune every managed skill on disk.

payload-transferred now reports a commit (and adopts a resume basis) only when a pending set was actually applied. Transfers with none, unknown intent codes, foreign payloads, or no pending work return an empty outcome—still counted in diagnostics but not a commit or up-to-date signal.

Poll etag handling adopts the response ETag only after a body completed an exchange (committed payload or none on server-intent). Unapplied bodies no longer lend their etag to a follow-up 304.

HTTP 304 no longer calls _publish_first_payload or satisfies wait_for_skills; it only confirms content already held after a real commit.

Agent docs in agents.md spell out the three linked invariants. Tests were added/rewritten for 304-before-payload, unrecognized-intent etag chains, and non-committing transfers.

^{Reviewed by Cursor Bugbot for commit daaf208. Bugbot is set up for automated code reviews on this repo. Configure here.}