dynamodb-reactive 0.1.22 → 0.2.1

package/README.md

@@ -1,96 +1,112 @@
-# **dynamodb-reactive**
+# dynamodb-reactive
 
-**Tagline:** A Serverless, Reactive tRPC replacement for AWS - unified package.
+Type-safe DynamoDB query subscriptions with HTTP snapshots and versioned JSON Patch updates over WebSockets.
 
-## **1. Overview**
+The application server owns authentication, router execution, and mutations. A router-agnostic Lambda consumes DynamoDB Streams and replays validated query metadata; it does not bundle or invoke application resolvers.
 
-`dynamodb-reactive` provides type-safe, real-time DynamoDB subscriptions with automatic JSON Patch diffing over WebSockets.
-
-**Key Features:**
-
-* **Full TypeScript Support:** End-to-end type safety from schema definition to React hooks.
-
-## **2. Installation**
+## Requirements and installation
 
 ```bash
-npm install dynamodb-reactive zod
-# or
 pnpm add dynamodb-reactive zod
 ```
 
-**Peer Dependencies (install as needed):**
+Install optional peers for the entry points you use:
 
-| Dependency | Required For |
-| :--- | :--- |
-| `zod` | Schema definitions (required) |
-| `react` | React hooks |
-| `aws-cdk-lib` | Infrastructure |
-| `constructs` | Infrastructure |
+```bash
+# dynamodb-reactive/react
+pnpm add react
 
-## **3. Package Exports**
+# dynamodb-reactive/infra
+pnpm add aws-cdk-lib constructs esbuild
+```
 
-| Import Path | Purpose |
-| :--- | :--- |
-| `dynamodb-reactive` | Core exports (DynamoTable, schemas) |
-| `dynamodb-reactive/core` | Core table definitions |
-| `dynamodb-reactive/server` | Server runtime (Router, handlers) |
-| `dynamodb-reactive/client` | Frontend client |
-| `dynamodb-reactive/react` | React hooks |
-| `dynamodb-reactive/infra` | CDK constructs |
+`zod` is always required. `react` is required only by `dynamodb-reactive/react`. `aws-cdk-lib`, `constructs`, and `esbuild` are required only by `dynamodb-reactive/infra`.
 
-## **4. Quick Start**
+Every public entry point supplies ESM (`.js` and `.d.ts`) and CommonJS (`.cjs` and `.d.cts`) conditions, so both `import` and `require()` consumers are supported:
 
-### **Step 1: Define Your Schema**
+| Import | Contents |
+| --- | --- |
+| `dynamodb-reactive` | Core table and schema exports |
+| `dynamodb-reactive/core` | Same core API, explicitly named |
+| `dynamodb-reactive/server` | Routers, database context, and HTTP/stream handlers |
+| `dynamodb-reactive/client` | React-free client, WebSocket manager, and query-key helpers |
+| `dynamodb-reactive/react` | Provider and React hooks |
+| `dynamodb-reactive/infra` | `ReactiveEngine` and its configuration types |
 
-```typescript
-import { z } from 'zod';
+React code must import the provider and hooks from `dynamodb-reactive/react`. Importing `dynamodb-reactive/client` does not load React.
+
+## Define a table
+
+```ts
+// todo-table.ts
 import { DynamoTable } from 'dynamodb-reactive/core';
+import { z } from 'zod';
 
 export const TodoTable = new DynamoTable({
-  tableName: 'my-table',
+  // This is the physical DynamoDB table name, not a logical CDK ID.
+  tableName: 'acme-todos',
   schema: z.object({
-    PK: z.string(),
-    SK: z.string(),
+    pk: z.string(),
+    sk: z.string(),
+    ownerId: z.string(),
     id: z.string(),
     text: z.string(),
     completed: z.boolean(),
     createdAt: z.number(),
   }),
-  pk: 'PK',
-  sk: 'SK',
+  pk: 'pk',
+  sk: 'sk',
+  indexes: {
+    byOwner: { name: 'byOwner', pk: 'ownerId', sk: 'createdAt' },
+  },
 });
 ```
 
-### **Step 2: Create the Router**
+`DynamoTable` is a runtime/type descriptor used for validation and query planning. It does not create a DynamoDB table or GSI. Provision a physical table separately, with an explicit `tableName` exactly equal to `TodoTable.tableName` and indexes matching the descriptor.
+
+## Define the router
+
+```ts
+// router.ts
+import { randomUUID } from 'node:crypto';
 
-```typescript
-import { z } from 'zod';
 import { initReactive } from 'dynamodb-reactive/server';
-import { TodoTable } from './schema';
+import { z } from 'zod';
+
+import { TodoTable } from './todo-table.js';
+
+export interface AppContext {
+  principalId: string;
+}
 
-type AppContext = Record<string, unknown>;
 const t = initReactive<AppContext>();
 
 export const appRouter = t.router({
   todos: {
-    // Query procedure
     list: t.procedure
-      .input(z.object({}).optional())
-      .query(async ({ ctx }) => {
+      .input(z.object({ ownerId: z.string() }))
+      .query(({ ctx, input }) => {
+        if (input.ownerId !== ctx.principalId) {
+          throw new Error('Forbidden');
+        }
         return ctx.db
           .query(TodoTable)
-          .filter((q) => q.eq(TodoTable.field.PK, 'TODO'))
+          .useIndex('byOwner')
+          .filter((q) => q.eq(TodoTable.field.ownerId, input.ownerId))
+          .sortDescending()
+          .take(100)
           .execute();
       }),
 
-    // Mutation procedure
     create: t.procedure
-      .input(z.object({ text: z.string() }))
+      .input(z.object({ text: z.string().min(1) }))
       .mutation(async ({ ctx, input }) => {
+        const id = randomUUID();
         const item = {
-          PK: 'TODO',
-          SK: Date.now().toString(),
-          id: Date.now().toString(),
+          pk: `USER#${ctx.principalId}`,
+          sk: `TODO#${id}`,
+          ownerId: ctx.principalId,
+          id,
           text: input.text,
           completed: false,
           createdAt: Date.now(),
@@ -98,46 +114,206 @@ export const appRouter = t.router({
         await ctx.db.put(TodoTable, item);
         return item;
       }),
+
+    toggle: t.procedure
+      .input(z.object({ id: z.string(), completed: z.boolean() }))
+      .mutation(({ ctx, input }) =>
+        ctx.db.update(
+          TodoTable,
+          { pk: `USER#${ctx.principalId}`, sk: `TODO#${input.id}` },
+          { completed: input.completed },
+        ),
+      ),
+
+    delete: t.procedure
+      .input(z.object({ id: z.string() }))
+      .mutation(async ({ ctx, input }) => {
+        await ctx.db.delete(TodoTable, {
+          pk: `USER#${ctx.principalId}`,
+          sk: `TODO#${input.id}`,
+        });
+        return { id: input.id };
+      }),
   },
 });
 
 export type AppRouter = typeof appRouter;
 ```
 
-### **Step 3: Create API Handler**
+### Subscription query contract
+
+A query procedure used as a subscription must:
+
+- execute exactly one `ctx.db.query(...)`;
+- call `.execute()`;
+- return that array unchanged.
+
+Mapping, filtering, wrapping, or otherwise transforming the result is rejected. Multiple queries and `ctx.db.get()` are also rejected for subscriptions. Use `handler.query(...)` for one-time reads, transform data in client presentation code, or redesign the stored model/query when one replayable query cannot express the subscription. Mutations are separate procedures and may use `get`, `put`, `update`, and `delete`.
+
+The query builder supports `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `between`, `beginsWith`, `contains`, `and`, `or`, and `not`. Exact primitive equality and nonempty `beginsWith` prefixes up to 64 characters produce targeted dependencies when the complete filter is safely trackable. Unfiltered queries, ranges, `contains`, `not`, null equality, long prefixes, and other unsafe plans fall back to table-wide wildcard invalidation. This costs more replays but preserves correctness.
+
+Replay uses strongly consistent PartiQL reads against the base table. `useIndex()` records sparse-index membership with `attribute_exists` checks and selects that index's sort key; it does not replay against the eventually consistent GSI itself. Sorting requires the base table or selected index to have a sort key. A sorted query reads all pages, sorts by that key, and then applies `.take(limit)`; an unsorted limited query can stop once enough items have been read and has no stable order.
+
+## Provision AWS resources
+
+Create the application table yourself and bind it to `ReactiveEngine`:
+
+```ts
+// stack.ts
+import * as cdk from 'aws-cdk-lib';
+import * as authorizers from 'aws-cdk-lib/aws-apigatewayv2-authorizers';
+import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import * as lambda from 'aws-cdk-lib/aws-lambda';
+import { Construct } from 'constructs';
+import { ReactiveEngine } from 'dynamodb-reactive/infra';
+
+import { TodoTable } from './todo-table.js';
+
+export class AppStack extends cdk.Stack {
+  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
+
+    const table = new dynamodb.Table(this, 'Todos', {
+      tableName: TodoTable.tableName,
+      partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
+      sortKey: { name: 'sk', type: dynamodb.AttributeType.STRING },
+      stream: dynamodb.StreamViewType.NEW_AND_OLD_IMAGES,
+    });
+    table.addGlobalSecondaryIndex({
+      indexName: TodoTable.indexes.byOwner.name,
+      partitionKey: {
+        name: TodoTable.indexes.byOwner.pk,
+        type: dynamodb.AttributeType.STRING,
+      },
+      sortKey: {
+        name: TodoTable.indexes.byOwner.sk,
+        type: dynamodb.AttributeType.NUMBER,
+      },
+    });
+
+    const authorizerFunction = new lambda.Function(this, 'ConnectAuth', {
+      runtime: lambda.Runtime.NODEJS_24_X,
+      handler: 'index.handler',
+      code: lambda.Code.fromAsset('dist/connect-authorizer'),
+    });
+    const connectAuthorizer = new authorizers.WebSocketLambdaAuthorizer(
+      'ConnectAuthorizer',
+      authorizerFunction,
+      { identitySource: ['route.request.querystring.token'] },
+    );
+
+    const engine = new ReactiveEngine(this, 'Reactive', {
+      resourcePrefix: 'acme-prod',
+      tables: [{ definition: TodoTable, table }],
+      connectAuthorizer,
+    });
+
+    const appRole = new iam.Role(this, 'ApplicationRole', {
+      assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
+    });
+    engine.grantApplicationAccess(appRole);
+
+    new cdk.CfnOutput(this, 'ClientWebSocketUrl', {
+      value: engine.webSocketUrl,
+    });
+  }
+}
+```
+
+The authorizer must return an authorizer context containing the stable principal identifier that the HTTP handler will compare. `ReactiveEngine` requires a real `connectAuthorizer` by default. `allowUnauthenticatedConnections: true` is an explicit alternative intended only for local or disposable development.
+
+The application role running `createReactiveHandler` needs the system-table and application-table permissions installed by `engine.grantApplicationAccess(appRole)`. The engine's generated stream Lambda is router-agnostic and receives only the table access it needs.
+
+`dynamodb-reactive/infra` intentionally exposes only `ReactiveEngine`, `ReactiveEngineProps`, and `ReactiveTableBinding`. User tables are supplied through the constructor's `tables` bindings; stream mappings and system tables are managed by the engine rather than separate public helpers.
+
+System tables use `RemovalPolicy.RETAIN` by default. Removing or replacing a stack therefore leaves fixed-name tables behind; importing, manually deleting, or choosing `RemovalPolicy.DESTROY` for a disposable environment is necessary before recreating the same prefix. Run CDK synth/deploy from the application package root where both `dynamodb-reactive` and `esbuild` are resolvable: the construct writes its generated entry under `<process.cwd()>/cdk.out/.generated` and `NodejsFunction` bundles it from there. The construct emits a WebSocket URL output; the explicit output above gives it an application-specific name.
+
+Version 2 provisions `<prefix>-ReactiveConnectionsV2`, `<prefix>-ReactiveDependenciesV2`, and `<prefix>-ReactiveConnectionQueriesV2`. These are deliberately new tables: 0.1 subscription state is incompatible and is not read or migrated.
 
-```typescript
-import { createReactiveHandler } from 'dynamodb-reactive/server';
-import { appRouter } from './router';
+## Expose the HTTP handler
 
-export const handler = createReactiveHandler({
+The HTTP principal must own the WebSocket connection named in the request. The connect Lambda stores `requestContext.authorizer` on the connection record; `authorizeConnection` must compare it with independently authenticated HTTP context.
+
+```ts
+// reactive-api.ts
+import {
+  createReactiveHandler,
+  type ReactiveRequest,
+} from 'dynamodb-reactive/server';
+import { z } from 'zod';
+
+import { authenticateBearer } from './auth.js';
+import { appRouter, type AppContext } from './router.js';
+
+const RESOURCE_PREFIX = 'acme-prod';
+
+export const reactive = createReactiveHandler<AppContext, typeof appRouter.definition>({
   router: appRouter,
-  dbConfig: { region: 'us-east-1' },
-  getContext: async () => ({}),
+  tablePrefix: RESOURCE_PREFIX,
+  getContext: async ({ headers }) => ({
+    principalId: await authenticateBearer(headers?.authorization),
+  }),
+  authorizeConnection: ({ context, connection }) =>
+    typeof connection.context?.principalId === 'string' &&
+    connection.context.principalId === context.principalId,
 });
 
-// In Next.js API route:
-export async function POST(request: Request) {
-  const body = await request.json();
-  const response = await handler.handleRequest('client-id', body);
-  return Response.json(response);
+const requestSchema: z.ZodType<ReactiveRequest> = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('subscribe'),
+    connectionId: z.string(),
+    subscriptionId: z.string(),
+    generation: z.number().int().nonnegative(),
+    registrationId: z.string(),
+    path: z.string(),
+    input: z.unknown(),
+  }),
+  z.object({
+    type: z.literal('unsubscribe'),
+    connectionId: z.string(),
+    subscriptionId: z.string(),
+    generation: z.number().int().nonnegative(),
+    registrationId: z.string(),
+  }),
+  z.object({
+    type: z.literal('call'),
+    connectionId: z.string(),
+    path: z.string(),
+    input: z.unknown(),
+  }),
+]);
+
+export async function POST(request: Request): Promise<Response> {
+  const body = requestSchema.parse(await request.json());
+  const headers = Object.fromEntries(request.headers.entries());
+  const result = await reactive.handleRequest(body, headers);
+  return Response.json(result);
 }
 ```
 
-### **Step 4: Set Up React Provider**
+`getContext` and `authorizeConnection` are required. Validate untrusted JSON at the framework boundary before calling `handleRequest(body, headers)`. The server performs additional key and procedure validation, but its TypeScript type is not an HTTP parser. `tablePrefix` must exactly equal the CDK `resourcePrefix`, or the application and engine will use different system tables.
+
+`registerConnection` and `unregisterConnection` are exposed for custom/non-CDK transports that manage their own connection lifecycle. API Gateway resources created by `ReactiveEngine` already invoke connect/disconnect handlers, so application HTTP routes should not call them.
+
+## React
+
+The provider owns connection setup and teardown. Supply both the deployed WebSocket URL and the HTTP route:
 
-```typescript
-// app/layout.tsx or providers.tsx
+```tsx
+// providers.tsx
 'use client';
 
-import { ReactiveClientProvider } from 'dynamodb-reactive/client';
+import type { ReactNode } from 'react';
+import { ReactiveClientProvider } from 'dynamodb-reactive/react';
 
-export function Providers({ children }: { children: React.ReactNode }) {
+export function Providers({ children }: { children: ReactNode }) {
   return (
     <ReactiveClientProvider
       config={{
-        url: process.env.NEXT_PUBLIC_WS_URL!,
+        url: process.env.NEXT_PUBLIC_REACTIVE_WS_URL!,
         httpUrl: '/api/reactive',
+        auth: () => window.localStorage.getItem('access-token') ?? '',
       }}
     >
       {children}
@@ -146,119 +322,168 @@ export function Providers({ children }: { children: React.ReactNode }) {
 }
 ```
 
-### **Step 5: Use React Hooks**
+Use `useQuery` for a reactive query and `useMutation` for a mutation:
 
-```typescript
+```tsx
+// todos.tsx
 'use client';
 
-import type { Todo } from './types';
-import type { AppRouter } from './router';
-import { useClient, useConnectionState } from 'dynamodb-reactive/client';
-
-export function TodoList() {
-  const connectionState = useConnectionState();
-  const client = useClient<AppRouter>();
-
-  // Subscribe to todos - receives real-time updates via WebSocket
-  const { data: todos, loading, error } = client.todos.list.useQuery({});
-
-  // Mutations with automatic optimistic updates
-  const createMutation = client.todos.create.useMutation();
-  const toggleMutation = client.todos.toggle.useMutation();
-  const deleteMutation = client.todos.delete.useMutation();
+import { useClient, useConnectionState } from 'dynamodb-reactive/react';
 
-  const handleCreate = async (text: string) => {
-    await createMutation.mutate({ text });
-  };
+import type { AppRouter } from './router.js';
 
-  const handleToggle = async (id: string) => {
-    await toggleMutation.mutate({ id });
-  };
-
-  const handleDelete = async (id: string) => {
-    await deleteMutation.mutate({ id }); // Removes instantly from UI
-  };
+export function Todos({ ownerId }: { ownerId: string }) {
+  const client = useClient<AppRouter>();
+  const connection = useConnectionState();
+  const todos = client.todos.list.useQuery({ ownerId });
+  const target = { path: 'todos.list', input: { ownerId } };
+
+  const createTodo = client.todos.create.useMutation({
+    invalidates: target,
+    optimisticData: (input) => {
+      const id = `temporary-${Date.now()}`;
+      return {
+        pk: `USER#${ownerId}`,
+        sk: `TODO#${id}`,
+        ownerId,
+        id,
+        text: input.text,
+        completed: false,
+        createdAt: Date.now(),
+      };
+    },
+  });
+  const toggleTodo = client.todos.toggle.useMutation({
+    invalidates: target,
+    optimisticUpdate: 'merge',
+  });
+  const deleteTodo = client.todos.delete.useMutation({
+    invalidates: target,
+    optimisticUpdate: 'remove',
+  });
 
-  if (loading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error.message}</div>;
+  if (todos.loading && !todos.data) return <p>Loading...</p>;
+  if (todos.error) return <p>{todos.error.message}</p>;
 
   return (
-    <div>
-      <p>WebSocket: {connectionState}</p>
-      {todos?.map((todo) => (
+    <section aria-busy={todos.loading || todos.stale}>
+      <p>Connection: {connection}</p>
+      <button onClick={() => void createTodo.mutate({ text: 'New todo' })}>
+        Add
+      </button>
+      {todos.data?.map((todo) => (
         <div key={todo.id}>
-          <input
-            type="checkbox"
-            checked={todo.completed}
-            onChange={() => handleToggle(todo.id)}
-          />
+          <button
+            onClick={() =>
+              void toggleTodo.mutate({
+                id: todo.id,
+                completed: !todo.completed,
+              })
+            }
+          >
+            {todo.completed ? 'Undo' : 'Complete'}
+          </button>
           <span>{todo.text}</span>
-          <button onClick={() => handleDelete(todo.id)}>Delete</button>
+          <button onClick={() => void deleteTodo.mutate({ id: todo.id })}>
+            Delete
+          </button>
         </div>
       ))}
-    </div>
+    </section>
   );
 }
 ```
 
-## **5. Optimistic Updates**
+`useQuery` returns `data`, `loading`, `stale`, `error`, `disabled`, `refetch`, and `setData`. Existing data may remain visible while `stale` and `loading` are true during reconnect or resync. `useMutation` returns `mutate`, `data`, `loading`, `error`, `disabled`, and `reset`.
 
-All mutations apply **instant** optimistic updates (before HTTP request):
+Mutation targeting is explicit:
 
-| Update Type | Behavior | Example Input |
-| :--- | :--- | :--- |
-| `'merge'` | Find item by `input.id`, merge input fields | `{ id: '123', completed: true }` |
-| `'remove'` | Remove item by `input.id` | `{ id: '123' }` |
-| Custom function | Apply custom logic | `(data, input) => [...]` |
+- `invalidates: 'todos.list'` targets every active query with that path.
+- `invalidates: { path: 'todos.list', input: { ownerId } }` is a `QueryTarget` for exactly that canonical path/input pair.
+- `queryKey` targets one exact canonical query key, obtained from an imperative subscription's `.key` or `getQueryKey(path, input)` from `dynamodb-reactive/client`. It takes precedence over `invalidates`.
 
-**Convention:** `<namespace>.<action>` mutations auto-invalidate `<namespace>.list` subscriptions.
+`optimisticUpdate: 'merge'` merges input/result fields into array items with the same `id`; `'remove'` removes that `id`; a function can implement other array changes. `optimisticData` supplies a temporary create result. Optimistic layers are rolled back on failure and reconciled with a fresh authoritative snapshot after success.
 
-**Example - Instant Toggle:**
-```typescript
-// For instant optimistic updates, include the fields you want to change
-const handleToggle = async (todo: Todo) => {
-  await updateMutation.mutate({
-    id: todo.id,
-    completed: !todo.completed  // Include new value for instant UI update
-  });
-};
-```
+Equal `(path, input)` pairs share one canonical subscription and cache entry even when object keys were inserted in different orders. Leases are reference-counted, and the server registration is removed only after the final observer unsubscribes.
 
-**Custom options:**
-```typescript
-const mutation = client.todos.update.useMutation({
-  invalidates: 'todos.list',           // Override auto-detection
-  optimisticUpdate: 'merge',           // 'merge' | 'remove' | custom function
-});
+## React-free client
 
-// For creates (no id), provide optimisticData
-const createMutation = client.todos.create.useMutation({
-  optimisticData: (input) => ({
-    id: `temp-${Date.now()}`,
-    ...input,
-    completed: false,
-    createdAt: Date.now(),
-  }),
+The raw typed client uses imperative `useSubscription` and `mutate` methods. Connect it before operations and disconnect it when its owner is disposed:
+
+```ts
+import { createReactiveClient } from 'dynamodb-reactive/client';
+
+import type { AppRouter } from './router.js';
+
+const client = createReactiveClient<AppRouter>({
+  url: 'wss://example.execute-api.us-east-1.amazonaws.com/prod',
+  httpUrl: 'https://app.example.com/api/reactive',
+  auth: async () => 'short-lived-access-token',
 });
+
+await client.connect();
+const subscription = client.todos.list.useSubscription(
+  { ownerId: 'user-123' },
+  {
+    onData: (items) => {
+      document.body.dataset.todoCount = String(items.length);
+    },
+    onError: (error) => {
+      document.body.dataset.reactiveError = error.message;
+    },
+  },
+);
+
+try {
+  await client.todos.toggle.mutate(
+    { id: 'todo-123', completed: true },
+    {
+      queryKey: subscription.key,
+      optimisticUpdate: 'merge',
+    },
+  );
+} finally {
+  subscription.unsubscribe();
+  client.disconnect();
+}
 ```
 
-## **6. Database Context Methods**
+The returned subscription exposes live getters for `data`, `loading`, `stale`, and `error`, plus `key`, `unsubscribe()`, and `refetch()`.
+
+## Delivery model
 
-The `ctx.db` object provides these methods:
+1. The client establishes a WebSocket and receives its API Gateway connection ID.
+2. A subscribe request goes over HTTP. The application authenticates the HTTP caller, verifies connection ownership, runs the one allowed query to capture metadata, establishes a strong baseline replay, and returns a versioned HTTP snapshot.
+3. DynamoDB Streams emit `NEW_AND_OLD_IMAGES`. The generic Lambda finds exact/prefix dependencies plus wildcard subscriptions, replays validated metadata with strong base-table reads, persists the new result/version and a pending delivery, then sends a versioned WebSocket patch.
+4. The client buffers patches that arrive before their snapshot, applies contiguous versions, ignores duplicate message IDs/stale versions, and requests a new HTTP snapshot for gaps, invalid patches, or a server `resync` instruction.
 
-| Method | Description |
-| :--- | :--- |
-| `query(table).filter(...).execute()` | Query with filters |
-| `get(table, key)` | Get single item by key |
-| `put(table, item)` | Create/replace item |
-| `update(table, key, updates)` | Update item fields |
-| `delete(table, key)` | Delete item |
+Pending delivery is durable until a send completes, so retries are at least once. A send followed by a failed clear can produce a duplicate; clients must keep duplicate handling enabled. Patch messages larger than 30 KiB become a small `resync` instruction rather than a WebSocket payload. Serialized subscription state is limited to 300 KiB.
+
+Connection and subscription records receive three-hour TTLs. Each authorized HTTP operation refreshes the connection lease; registration and re-registration renew the query and dependency records. The browser sends a WebSocket heartbeat every five minutes, but API Gateway can still close idle or maximum-age connections; the client reconnects and re-registers active subscriptions. DynamoDB TTL removes expired records asynchronously and is cleanup, not an authorization or immediate-deletion mechanism. HTTP ownership checks explicitly enforce connection status and lease expiry.
+
+## Security
+
+- Authenticate `$connect`; unauthenticated mode is an explicit development choice.
+- Authenticate every HTTP request independently and compare its principal with the stored WebSocket authorizer principal in `authorizeConnection`.
+- The `auth` client option sends `Authorization: Bearer ...` over HTTP and appends `token=...` to the WebSocket URL because browser WebSockets cannot set arbitrary headers. Use TLS, short-lived tokens, and infrastructure/logging that redacts query strings, or use a secure cookie/custom transport where appropriate.
+- Do not log authorization headers, tokens, authorizer context, full request inputs, or sensitive DynamoDB items. Redact errors before forwarding them to untrusted clients where necessary.
+- The stream Lambda validates versioned query metadata and cannot invoke arbitrary router code. Keep procedures and application authorization in the HTTP runtime.
+- Use `grantApplicationAccess` for the application runtime and retain least-privilege roles; do not grant broad account-wide DynamoDB or API Gateway permissions.
+
+## Verification and release checks
+
+From the repository root:
+
+```bash
+pnpm verify
+pnpm package:check
+pnpm package:smoke
+```
 
-## **7. Requirements**
+`pnpm verify` runs lint, the workspace typecheck, dual-format build, unit/CDK tests, artifact checks, and package consumer smokes. `package:check` packs the public artifact and checks its contents, export conditions, `publint`, and Are The Types Wrong. `package:smoke` installs the tarball into runtime and TypeScript/React/CDK consumers and executes them.
 
-* Node.js >= 18.0.0
-* TypeScript >= 5.3.0
+Pull-request and release CI run source verification on Node 24. Release CI also verifies the tag/version and npm availability, packs one exact tarball, reruns artifact checks and clean-consumer smokes against that tarball, and publishes it with provenance. Generated AWS Lambda functions use the Node.js 24 runtime.
 
-## **8. License**
+## License
 
 MIT