chore(rivetkit): impl follow up review

Author: NathanFlurry

.agent/notes/driver-test-progress.md

@@ -0,0 +1,9 @@
+# DT-021 package exports audit
+
+- `./driver-helpers`: keep removed. The old entrypoint re-exported actor-instance, runtime-router, and gateway-resolution internals that are not a stable public surface anymore.
+- `./driver-helpers/websocket`: keep removed. It was an internal lazy `WebSocket` loader wrapper, and the supported path is the public client/connection API rather than importing transport helpers directly.
+- `./test`: restore. Examples and docs on this branch still import `rivetkit/test`, and the helper still makes sense as a thin native-envoy test bootstrap.
+- `./inspector`: restore. The package still ships live inspector runtime code (`ActorInspector`) plus workflow-history transport helpers.
+- `./topologies/*`: keep removed. The source modules are gone and `tests/package-surface.test.ts` already treats those subpaths as intentionally deleted.
+- `./dynamic`: keep removed permanently. This branch no longer ships a supported dynamic actor package entrypoint.
+- `./sandbox/*`: keep removed permanently. This branch no longer ships sandbox helpers from `rivetkit`.

.agent/notes/dt-021-package-exports-audit.md

@@ -4,6 +4,11 @@ Date: 2026-04-22
 
 Scope: `rivetkit-typescript/packages/rivetkit`, static registry, bare encoding.
 
+## Current Status
+
+- The isolated `wait send returns completion response` path was fixed by DT-012 and is no longer the active bug for this area.
+- Remaining queue flake tracking is the high-fan-out child-actor path under fast static/http/bare verification. See DT-051 and DT-056 in `scripts/ralph/prd.json`.
+
 ## Repro Commands
 
 ```bash

.agent/notes/flake-conn-websocket.md

@@ -0,0 +1,73 @@
+# Changelog
+
+## Unreleased
+
+- `rivetkit` no longer exposes `ctx.sql` on actor contexts. Migrate raw SQLite calls to `ctx.db` from `rivetkit/db`, and keep Drizzle setup on the `rivetkit/db/drizzle` subpath.
+
+  Migration example:
+
+  ```ts
+  import { db } from "rivetkit/db";
+
+  const myActor = actor({
+    db: db(),
+    actions: {
+      listTodos: async (ctx) => {
+        return await ctx.db.execute("SELECT * FROM todos ORDER BY created_at DESC");
+      },
+    },
+  });
+  ```
+
+- `rivetkit` no longer exports the old concrete typed error classes from `rivetkit/actor/errors` such as `QueueFull`, `ActorNotFound`, and `ActionTimedOut`. The native runtime now standardizes on `RivetError` plus `group` and `code` so the same error shape survives HTTP, WebSocket, and bridge boundaries instead of depending on `instanceof` across runtimes.
+
+  Migration example:
+
+  ```ts
+  try {
+    await actor.someAction();
+  } catch (e) {
+    if (e instanceof QueueFull) {
+      // old path
+    }
+
+    if (isRivetErrorCode(e, "queue", "full")) {
+      // new path
+    }
+  }
+  ```
+
+  Common replacements:
+
+  | Removed class                     | Use now                                           |
+  | --------------------------------- | ------------------------------------------------- |
+  | `QueueFull`                       | `isRivetErrorCode(e, "queue", "full")`            |
+  | `QueueMessageTooLarge`            | `isRivetErrorCode(e, "queue", "message_too_large")` |
+  | `QueueMessageInvalid`             | `isRivetErrorCode(e, "queue", "message_invalid")` |
+  | `QueuePayloadInvalid`             | `isRivetErrorCode(e, "queue", "invalid_payload")` |
+  | `QueueCompletionPayloadInvalid`   | `isRivetErrorCode(e, "queue", "invalid_completion_payload")` |
+  | `QueueAlreadyCompleted`           | `isRivetErrorCode(e, "queue", "already_completed")` |
+  | `ActionTimedOut`                  | `isRivetErrorCode(e, "action", "timed_out")`      |
+  | `ActionNotFound`                  | `isRivetErrorCode(e, "action", "not_found")`      |
+  | `ActorNotFound`                   | `isRivetErrorCode(e, "actor", "not_found")`       |
+  | `ActorStopping`                   | `isRivetErrorCode(e, "actor", "stopping")`        |
+  | `ActorAborted`                    | `isRivetErrorCode(e, "actor", "aborted")`         |
+  | `IncomingMessageTooLong`          | `isRivetErrorCode(e, "message", "incoming_too_long")` |
+  | `OutgoingMessageTooLong`          | `isRivetErrorCode(e, "message", "outgoing_too_long")` |
+  | `InvalidEncoding`                 | `isRivetErrorCode(e, "encoding", "invalid")`      |
+  | `InvalidRequest`                  | `isRivetErrorCode(e, "request", "invalid")`       |
+  | `InvalidQueryJSON`                | `isRivetErrorCode(e, "request", "invalid_query_json")` |
+  | `RequestHandlerNotDefined`        | `isRivetErrorCode(e, "handler", "request_not_defined")` |
+  | `WebSocketHandlerNotDefined`      | `isRivetErrorCode(e, "handler", "websocket_not_defined")` |
+  | `FeatureNotImplemented`           | `isRivetErrorCode(e, "feature", "not_implemented")` |
+  | `Unsupported`                     | `isRivetErrorCode(e, "feature", "unsupported")`   |
+
+  Keep catching `UserError` when you intentionally throw user-facing application errors yourself. The removal only affects the built-in typed subclasses that used to wrap framework/runtime failures.
+
+- Restored `Registry.handler(request)` and `Registry.serve()` for the native serverless runner endpoint described in `.agent/specs/serverless-restoration.md`. The route surface is `/api/rivet`, `/api/rivet/health`, `/api/rivet/metadata`, and `/api/rivet/start`; user traffic still goes through the Rivet Engine gateway.
+- `Registry.start()` now starts the native envoy path only. Built-in `staticDir` serving is not wired through the native engine subprocess yet and remains a follow-up.
+- Restored the supported `rivetkit/test`, `rivetkit/inspector`, and `rivetkit/inspector/client` entrypoints. `rivetkit/test` now waits for the native envoy metadata endpoint instead of the removed TypeScript in-memory runtime.
+- Restored the zero-runtime `*ContextOf` helper types on the root `rivetkit` export so patterns like `ActionContextOf<typeof myActor>` work again. `PATH_CONNECT`, `PATH_WEBSOCKET_PREFIX`, `KV_KEYS`, `ActorKv`, `ActorInstance`, `ActorRouter`, `createActorRouter`, and `routeWebSocket` stay removed.
+- `rivetkit/driver-helpers` and `rivetkit/driver-helpers/websocket` stay removed. They only exposed internal runtime/router helpers; migrate to the public `rivetkit`, `rivetkit/client`, and engine-client APIs instead of importing package internals.
+- `rivetkit/topologies/*` stays removed. The topology helpers are deleted on this branch; keep custom coordinate/partition logic in app code if you still need it.
+- `rivetkit/dynamic` and `rivetkit/sandbox/*` stay permanently removed on this branch. There is no in-package replacement, so move those integrations out of `rivetkit` imports instead of waiting for a hidden subpath to come back.

.agent/notes/flake-inspector-replay.md

@@ -343,18 +343,6 @@ When the user asks to track something in a note, store it in `.agent/notes/` by
 - If an external dependency's struct requires `std::sync::Mutex`, keep it at the construction boundary with an explicit forced-std-sync comment.
 - Prefer async locks because sync guards can be silently held across `.await`, poisoning creates `.expect("lock poisoned")` boilerplate, and the tiny uncontended-lock win is dwarfed by actor I/O latency.
 
-## TypeScript Concurrency
-
-- Use `antiox` for TypeScript concurrency primitives instead of ad hoc Promise queues, custom channel wrappers, or event-emitter based coordination.
-- Prefer the Tokio-shaped APIs from `antiox`. For example, use `antiox/sync/mpsc` for `tx` and `rx` channels, `antiox/task` for spawning tasks, and the matching sync and time modules as needed.
-- Treat `antiox` as the default choice for any TypeScript concurrency work because it mirrors Rust and Tokio APIs used elsewhere in the codebase.
-
-## TLS / HTTP clients
-
-- Always use rustls. Never enable `native-tls` / `default-tls` on `reqwest` or anything else on Linux. Consumers, especially `.node` addons published via npm, must have no runtime `libssl.so` dependency.
-- `reqwest` workspace dep must set `default-features = false` and enable `rustls-tls-native-roots` + `rustls-tls-webpki-roots`. Per-crate overrides must keep the same.
-- Never vendor openssl as a workaround. If `openssl-sys` shows up in `cargo tree`, trace the transitive dep, usually `reqwest` default features, and switch it to rustls.
-
 ## Error Handling
 
 - Custom error system at `packages/common/error/` using `#[derive(RivetError)]` on struct definitions. For the full derive example and conventions, see `.claude/reference/error-system.md`.
@@ -374,6 +362,9 @@ When the user asks to track something in a note, store it in `.agent/notes/` by
 
 - **Never use `vi.mock`, `jest.mock`, or module-level mocking.** Write tests against real infrastructure (Docker containers, real databases, real filesystems). For LLM calls, use `@copilotkit/llmock` to run a mock LLM server. For protocol-level test doubles (e.g., ACP adapters), write hand-written scripts that run as real processes. `vi.fn()` for simple callback tracking is acceptable.
 - Driver tests that wait for actor sleep must not poll actor actions while waiting; each action counts as activity and can reset the sleep deadline.
+- **Never paper over flakes with retry loops or bumped waits.** When a test flakes, (1) root-cause the race, (2) write a deterministic repro using `vi.useFakeTimers()` or event-ordered `Promise` resolution, (3) fix the underlying ordering in core/napi/typescript, (4) delete any flake-workaround note. `vi.waitFor` is acceptable for legitimate "wait for an async event" coordination but never as a retry-until-success masking layer. Every `vi.waitFor` call must have a one-line comment explaining why polling rather than direct awaiting is necessary.
+- In `rivetkit-typescript/packages/rivetkit/tests/`, put the `vi.waitFor(...)` justification on the immediately preceding `//` line. `pnpm run check:wait-for-comments` enforces the adjacent comment.
+- **Rust tests live under `tests/`, not inline `#[cfg(test)] mod tests` in `src/`.** Move every inline test module in Rust crates to the crate's `tests/` directory. Exceptions must be justified (e.g., testing a private internal that can't be reached from an integration test).
 - For running RivetKit tests, Vitest filter gotchas, the driver-test parity workflow, and Rust test layout rules, see `.claude/reference/testing.md`.
 
 ## Traces Package

.agent/notes/flake-queue-waitsend.md

@@ -29,6 +29,7 @@ When changing a versioned VBARE schema, follow the existing migration pattern.
      - `engine/packages/runner-protocol/src/lib.rs` `PROTOCOL_MK2_VERSION`
      - `rivetkit-typescript/packages/engine-runner/src/mod.ts` `PROTOCOL_VERSION`
    - Update the Rust latest re-export in `engine/packages/runner-protocol/src/lib.rs` to the new generated module.
+5. For any Rust VBARE protocol crate, bump the protocol constant together with the matching latest generated/schema wiring (`generated::vN`, latest re-exports, `protocol.rs`/`versioned.rs` if present, and the corresponding `engine/sdks/schemas/.../vN.bare` file).
 
 ## Epoxy durable keys
 
@@ -54,6 +55,7 @@ Use `test-snapshot-gen` to generate and load RocksDB snapshots of the full UDB K
 - `sqlite-storage` LTX decoders should validate the varint page index against the actual page-frame layout instead of trusting footer offsets alone.
 - `sqlite-storage` `get_pages(...)` should keep META, cold PIDX loads, and DELTA/SHARD blob fetches inside one `db.run(...)` transaction, then decode each unique blob once and evict stale cached PIDX rows that now need SHARD fallback.
 - `sqlite-storage` fast-path commits should update an already-cached PIDX in memory after the store write, but must not load PIDX from store just to mutate it or the one-RTT path is gone.
+- `sqlite-storage` shrink writes must delete above-EOF PIDX rows and fully-above-EOF SHARD blobs inside the same commit/takeover transaction; compaction only cleans partial shards by filtering pages at or below `head.db_size_pages`.
 - `sqlite-storage` fast-path cutoffs should use raw dirty-page bytes, and slow-path finalize must accept larger encoded DELTA blobs because UniversalDB chunks logical values internally.
 - `sqlite-storage` compaction should choose shard passes from the live PIDX scan, then delete DELTA blobs by comparing all existing delta keys against the remaining global PIDX references so multi-shard and overwritten deltas only disappear when every page ref is gone.
 - `sqlite-storage` compaction must re-read META inside its write transaction and fence on `generation` plus `head_txid` before updating `materialized_txid` or quota fields, so takeover and commits cannot rewind the head.