chore: add CLAUDE.md guidance on test fixtures, SDK regen, and TS client layer

[NathanFlurry]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[NathanFlurry]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• fix(test): stabilize lifecycle, sleep, queue, and run edge cases #4660 : 2 dependent PRs (#4664 , #4665 )
• test(rivetkit): re-enable gateway URL and direct-registry coverage #4659
• fix(rivetkit): keep internal error exposure behavior consistent #4661
• fix(rivetkit): add lifecycle error retry and gateway HTTP routing #4666
• fix(rivetkit-core): remove legacy timeouts #4799
• chore: add CLAUDE.md guidance on test fixtures, SDK regen, and TS client layer #4796 👈 (View in Graphite)
• fix(inspector): stream patched state updates #4795
• fix(rivetkit): refresh stale actor handles #4794
• test(rivetkit-napi): move private tests to crate root #4793
• test(rivetkit-core): move private tests to crate root #4792
• test(runner-configs): assert envoy protocol version #4791
• fix(serverless): split metadata protocol errors #4789 : 1 other dependent PR (#4790 )
• chore(sqlite): add open close lifecycle for envoy actors #4788
• fix(rivetkit): share lifecycle shutdown grace #4810
• fix(pegboard): move sqlite v1 migration into actor workflow #4787 : 1 other dependent PR (#4797 )
• test(rivetkit): cover c.db access from onWake/onSleep/onDestroy #4786
• fix(rivetkit-napi): run onMigrate before createState/onCreate/createVars #4785
• refactor(rivetkit-core): merge ready+started into lifecycle_started, drop redundant napi calls #4784
• fix(rivetkit): drain native sleep side tasks reliably #4782 : 1 other dependent PR (#4783 )
• fix(rivetkit): route raw request fetches to actors #4781
• fix(pegboard): refresh runner config after envoy connect #4778 : 2 other dependent PRs (#4779 , #4798 )
• chore(kitchen-sink): configurable endpoint #4766 : 2 other dependent PRs (#4754 , #4777 )
• refactor(rivetkit-core): rename StopReason to ShutdownKind and kill enum fallthroughs #4765
• chore(envoy-client): log command and event payloads #4751
• fix(rivetkit): minor sleep-cleanup follow-ups #4761
• docs(rivetkit): clean up stale setPreventSleep references in docs and JSDoc #4760
• docs(rivetkit): document keepAwake/waitUntil counter-arm race and surface bridge errors #4759
• test(engine): force overdue branch in alarm-during-sleep test with negative offset #4758
• fix(rivetkit-core): return stopping not starting when sleep/destroy called mid-shutdown #4757
• test(rivetkit): remove sleepWithPreventSleep fixture and tests #4756
• test(engine): add regression test for alarm-during-sleep-transition race #4755
• test(rivetkit-core): cover sleep/destroy guards and prevent_sleep no-op #4750
• docs: add keepAwake vs waitUntil table and internal sleep-sequence invariants #4749
• feat(rivetkit): expose c.keepAwake(promise) through native path #4748
• refactor(rivetkit): deprecate setPreventSleep to no-op in TypeScript #4747
• fix(rivetkit-core): enumerate non-drained counters in grace deadline warn log #4746
• fix(rivetkit-core): abort graceful cleanup task when grace deadline elapses #4745
• fix(rivetkit-core): error on sleep/destroy before startup or already-requested #4743
• fix(rivetkit-core): cap SerializeState shutdown timeout at 15s #4742
• refactor(rivetkit-core): remove prevent_sleep field and deprecate set_prevent_sleep to no-op #4741
• fix(api-public): remove orphan import_export actors module #4764
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

PR #4796 Review — docs: add replay guidance notes

This PR makes four distinct changes: CLAUDE.md guidance additions, a variable rename in a test, a behavioral change in SQLite commit logic, and a simplification of frontend error rendering.

---

Overview

File	Change
CLAUDE.md	Adds new RivetKit Test Fixtures section + a utoipa/SDK note
engine/packages/pegboard/tests/actor_sqlite_migration.rs	Renames takeover → opened
engine/packages/sqlite-storage/src/commit.rs	Converts .expect() panic to silent if let Some
frontend/src/app/serverless-connection-check.tsx	Replaces exhaustive ts-pattern match with flat field access

---

Issues

🔴 commit.rs — Violates Fail-By-Default Runtime constraint

The most significant change converts a deliberate .expect() panic into two silent if let Some no-ops:

// Before: invariant-asserting
let mut entry = self.pending_stages.get_async(&stage_key).await
    .expect("pending stage entry should exist for the duration of commit_stage");

// After: silent no-op
if let Some(mut entry) = self.pending_stages.get_async(&stage_key).await {
    ...
}

This directly contradicts the CLAUDE.md Fail-By-Default Runtime constraint:

"Avoid silent no-ops for required runtime behavior. If a capability is required, validate it and throw an explicit error with actionable context instead of returning early."

The removed comment explicitly stated the invariant: commit_stage_begin inserts the entry and only commit_finalize removes it, so it must be present here. If that invariant is actually violated in practice (causing a panic), the fix should either:

1. Restore the invariant (fix the race/ordering bug that causes the entry to go missing), or
2. Return an explicit Err(...) with a meaningful message instead of silently skipping the state update

A missing entry means next_chunk_idx and saw_last_chunk are never updated and error_message is never recorded — silent data loss in the commit pipeline. The PR description gives no explanation for why this invariant no longer holds.

Additionally, two separate get_async calls (one in Ok, one in Err) replace a single pre-match acquisition. At minimum, the entry could be fetched once before the match and an explicit error returned if absent.

🟡 serverless-connection-check.tsx — Loss of exhaustive type safety

The exhaustive ts-pattern match is replaced with direct field access:

// Before: compile-time exhaustive
match(error.error).with({ nonSuccessStatus: P.any }, ...).exhaustive();

// After: flat access
const { message, details } = error.error;

The .exhaustive() call guaranteed a TypeScript compile error if a new error variant was added without handling it. The new code silently renders all errors identically. This is fine if the upstream error type was intentionally changed to a flat { message, details } shape, but that type change isn't visible in this diff. The PR should confirm:

• What the new error.error type is (discriminated union vs. flat object)
• That message is always present (non-optional) at runtime

If message can be undefined, the rendered text will include the literal string "undefined".

---

Positives

🟢 Variable rename in test (takeover -> opened)

Clean and accurate. The variable holds the result of engine.open(...), not a takeover, so opened is the right name.

🟢 RivetKit Test Fixtures section in CLAUDE.md

The four bullet points capture genuinely non-obvious testing constraints (inspector token lock contention, fast-test file selection, private-module access for moved tests, tracing subscriber scoping). These are valuable.

🟡 utoipa/SDK note placement in CLAUDE.md

The note about updating SDK unions when an OpenAPI enum grows a variant is good guidance, but it's appended as a freestanding bullet at the end of the Reference Docs section, which is otherwise only navigation links. It should live in a more appropriate section (e.g., Dependency Management or a new SDK Codegen section).

Also, the third RivetKit Test Fixtures bullet is slightly verbose for CLAUDE.md conventions; consider trimming to the essential constraint.

---

Summary

The commit.rs change is the main concern — it silently swallows a violated invariant instead of failing loudly, contrary to the project's stated design philosophy, and could mask real bugs in the commit pipeline. Please either restore the invariant, add an explicit Err return when the entry is missing, or explain why the entry can legitimately be absent at this point in commit_stage.

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4796

All packages published as 0.0.0-pr.4796.509af22 with tag pr-4796.

Engine binary is shipped via @rivetkit/engine-cli on linux-x64-musl, linux-arm64-musl, darwin-x64, and darwin-arm64. Windows users should use the release installer or set RIVET_ENGINE_BINARY.

Docker images:

docker pull rivetdev/engine:slim-509af22
docker pull rivetdev/engine:full-509af22

Individual packages

npm install rivetkit@pr-4796
npm install @rivetkit/react@pr-4796
npm install @rivetkit/rivetkit-napi@pr-4796
npm install @rivetkit/workflow-engine@pr-4796

[NathanFlurry]

Landed in main via stack-merge fast-forward push. Commits are in main; closing to match.