fix: README transport-error claims + Vercel example AI SDK v4 alignment#143
Merged
Conversation
Review finding (Low) on #135: the mapper now maps charged but the AUDIT parsed-keys table still listed only status, event_id, balances.
README documented CyclesTransportError as thrown on network failure; the SDK never constructs it - transport failures surface as CyclesProtocolError with status: -1 (HOF paths) or CyclesResponse with isTransportError (programmatic). Rewrote the table row, removed the dead instanceof branch from the example, added a "Transport failures (status -1)" subsection. examples/vercel-ai-sdk/app/api/chat/route.ts mixed AI SDK v4 and v5 APIs while package.json pins ai@^4 (compiled under neither): UIMessage -> Message, await convertToModelMessages -> convertToCoreMessages. Typecheck skipped due to a local npm-internal bug; verified by review and post-fix grep for v5 identifiers (zero matches). CHANGELOG + AUDIT.md updated. Surfaced by the cycles-docs integration audit (runcycles/cycles-docs#785).
Apply 4 / modify 0 / skip 0: - README exception table + transport subsection, CHANGELOG, and AUDIT now scope the status: -1 claim to reservation-time failures and document the differing commit-time behavior: withCycles retries in the background (commit retry engine); StreamReservation.commit() throws and resets finalized for caller retry/release (verified in src/streaming.ts and src/lifecycle.ts).
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
1 participant
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.
Summary
Two fixes surfaced by the cycles-docs integration audit (runcycles/cycles-docs#785):
README transport-error claims:
CyclesTransportErrorwas documented as thrown on network failure; the SDK never constructs it. The README now documents actual behavior — reservation-time transport failures throwCyclesProtocolErrorwithstatus: -1(withCycles/reserveForStream) or returnCyclesResponsewithisTransportError(programmatic); commit-time failures are retried in the background bywithCycles, whileStreamReservation.commit()throws and resetsfinalized. Deadinstanceof CyclesTransportErrorbranch removed from the example; class remains exported.examples/vercel-ai-sdkv4 alignment: the route mixed AI SDK v4 and v5 APIs whilepackage.jsonpinsai@^4(compiled under neither major):UIMessage→Message,await convertToModelMessages→convertToCoreMessages. Post-fix grep for v5 identifiers across the example: zero matches.runcyclesusage untouched.Maintainer question (out of scope): should a future minor actually raise
CyclesTransportError, or deprecate it? Python client shares the exported-but-never-raised state (see runcycles/cycles-client-python#77).Codex-reviewed: 2 rounds (REVISE-MINOR → applied; round 1 caught that the transport claim needed reserve-time scoping). Note: CHANGELOG 0.1.1 says the class was removed from exports, but
src/index.tscurrently exports it — documented current reality, exports untouched.Test plan
npm run typecheck+npm run lintpass (run during review)