deepspace 0.6.1 → 0.7.0

package/dist/worker.d.ts

@@ -5,6 +5,7 @@ import * as zod from 'zod';
 import * as better_auth from 'better-auth';
 import { betterAuth } from 'better-auth';
 import * as better_auth_plugins from 'better-auth/plugins';
+import { Hono } from 'hono';
 
 /**
  * Wire protocol constants.
@@ -898,6 +899,8 @@ declare function encode<M extends BaseMessage<string, unknown>>(message: M): str
  * - Raw SQLite access via this.sql
  * - Broadcast helpers: broadcast(), sendTo()
  * - HTTP fetch handler with WebSocket upgrade detection
+ * - Internal control-plane endpoint: POST /internal/disconnect-sockets
+ *   (force every client to reconnect and resync after out-of-band writes)
  *
  * Subclasses implement lifecycle hooks:
  *   onConnect, onMessage, onBinaryMessage, onDisconnect, onRequest, onAlarm
@@ -917,6 +920,21 @@ declare abstract class BaseRoom<E = Record<string, unknown>> {
     protected sql: SqlStorage;
     constructor(state: DurableObjectState, env: unknown);
     fetch(request: Request): Promise<Response>;
+    /**
+     * Handle built-in `/internal/*` control-plane routes shared by every room
+     * type. Returns a `Response` if the request was an internal route, or `null`
+     * to let the caller continue normal dispatch.
+     *
+     * Currently:
+     * - `POST /internal/disconnect-sockets` — close every live WebSocket so
+     *   clients reconnect and resync. Optional JSON body `{ code?, reason? }`
+     *   overrides the defaults (1012 / 'state-refresh'). Responds with
+     *   `{ success: true, closed: <n> }`.
+     *
+     * See the security note on `fetch()`: this path is only reachable via DO
+     * stub fetch from the app worker, never from the public internet.
+     */
+    protected handleInternalRequest(request: Request, url: URL): Promise<Response | null>;
     private handleWebSocketUpgrade;
     webSocketMessage(ws: WebSocket, message: ArrayBuffer | string): Promise<void>;
     webSocketClose(ws: WebSocket, _code: number, _reason: string): Promise<void>;
@@ -955,6 +973,33 @@ declare abstract class BaseRoom<E = Record<string, unknown>> {
      * Get all connected WebSockets.
      */
     protected getWebSockets(): WebSocket[];
+    /**
+     * Force every connected client to reconnect and resync by closing all live
+     * WebSockets. Returns the number of sockets closed.
+     *
+     * Use this after an **out-of-band, server-side write** to the room's records
+     * — an admin import route, a migration script, a cron job, or a server
+     * action — that connected clients have no way to learn about. Without it, a
+     * browser tab holding stale in-memory state keeps operating on (and may
+     * autosave over) data that changed underneath it. Closing the socket makes
+     * the client SDK reconnect and pull fresh query results.
+     *
+     * The default close code is 1012 ("service restart") with reason
+     * 'state-refresh'. The DeepSpace client treats *any* close as a reconnect
+     * trigger (it does not special-case clean/1000 closes), so on reconnect it
+     * re-subscribes every active query and receives fresh `QUERY_RESULT`s —
+     * `useQuery` consumers see the new data without re-subscribing.
+     *
+     * Each close is guarded so one already-closing socket can't abort the sweep.
+     *
+     * @param options.code   WebSocket close code (default 1012).
+     * @param options.reason WebSocket close reason (default 'state-refresh').
+     * @returns the number of sockets that were closed.
+     */
+    disconnectAllSockets(options?: {
+        code?: number;
+        reason?: string;
+    }): number;
     /**
      * Get the user attachment for a WebSocket.
      */
@@ -1401,6 +1446,14 @@ declare class RecordRoom<E = Record<string, unknown>> extends BaseRoom<E> {
      * truthy value on the worker to opt in). Off by default.
      */
     private get perfLogEnabled();
+    /**
+     * The HTTP debug API (`/api/debug/*`) runs arbitrary SQL and role changes
+     * with no auth of its own, so it is gated here at the DO's single ingress.
+     * Off unless a deployment opts in with `ALLOW_DEBUG_ROUTES=true`
+     * (`deepspace dev`/`test` set it automatically). Deployments holding shared
+     * data override this to always return false.
+     */
+    protected get debugRoutesEnabled(): boolean;
     constructor(state: DurableObjectState, env: unknown, schemas?: CollectionSchema[], config?: RecordRoomConfig);
     private getPermissionContext;
     fetch(request: Request): Promise<Response>;
@@ -2955,7 +3008,7 @@ declare function createDeepSpaceAI(env: DeepSpaceAIEnv, provider: Provider, opti
  *   const jwt = c.req.header('Authorization')!.slice(7)
  *   const tools = await composioTools(c.env, { toolkit: 'gmail', authToken: jwt })
  *   const ai = createDeepSpaceAI(c.env, 'anthropic', { authToken: jwt })
- *   const result = streamText({ model: ai('claude-sonnet-4-6'), prompt, tools })
+ *   const result = streamText({ model: ai('claude-sonnet-5'), prompt, tools })
  *
  * Merge with your own tools: `tools: { ...buildTools(executor), ...composio }`.
  */
@@ -4446,4 +4499,148 @@ type DeepSpaceAuth = ReturnType<typeof createDeepSpaceAuth>;
 /** Collections that bypass schema checks (permissive access) */
 declare const SYSTEM_COLLECTIONS: Set<string>;
 
-export { AI_CHATS_SCHEMA, AI_MESSAGES_SCHEMA, ALLOWED_BINDING_TYPES, APP_NAME_RULES, AUTO_PROVISIONABLE_TYPES, AUTO_PROVISION_SENTINEL, type ActionContext, type ActionHandler, type ActionResult, type ActionTools, type ApiWorkerEnv, type AppNameResolution, type AppNameValidation, type AuthWorkerEnv, Awareness, type AwarenessState, type AwarenessStates, BASE_USERS_SCHEMA, BUILT_IN_TOOLS, type BaseMessage, BaseRoom, CHANNELS_SCHEMA, CHANNEL_INVITATIONS_SCHEMA, CHANNEL_MEMBERS_SCHEMA, CONVERSATION_SCHEMAS, COST_RATES, CanvasRoom, type CanvasShape, type ChatContextConfig, type ChatMessageRow, type ChatRow, type ChatTurn, type ClientMessage, type CollectionPermissionSummary, type CollectionSchema, type ColumnDefinition, type ColumnInterpretation, type ComposioToolsOptions, type ConnectionAttachment, type ConvMemberData, type ConvMessageData, type ConvReactionData, type ConvReadCursorData, type ConvVoteData, type ConversationStateData, type CronContext, type CronExecution, CronRoom, type CronRoomConfig, type CronTask, type CustomBinding, type CustomBindingManifest, DEFAULT_CONTEXT_CONFIG, DEFAULT_DO_MANIFEST, DEFAULT_QUERY_LIMIT, DIRECTORY_SCHEMAS, type DOBindings, type DOManifest, type DOManifestEntry, type DeepSpaceAIEnv, type DeepSpaceAIOptions, type DeepSpaceAuth, type DeepSpaceAuthConfig, type DirectoryCommunityData, type DirectoryConversationData, type DirectoryMembershipData, type DirectoryPostData, type DoMigrationDirective, type DoMigrationPlan, type ExistingDOBinding, GLOBAL_DO_TYPES, GLOBAL_DO_TYPE_NAMES, type GameInput, GameRoom, type GameRoomConfig, type GetActionData, type GlobalDOType, type HandlerContext, type Job, type JobContext, JobRoom, type JobRoomConfig, type JobStatus, type JwtClaims, type JwtVerifierConfig, MESSAGES_SCHEMA, MSG, MSG_AWARENESS, MSG_SYNC, MSG_SYNC_STEP1, MSG_SYNC_STEP2, MSG_SYNC_UPDATE, MSG_YJS_AWARENESS, MSG_YJS_SYNC, type MessageHandlers, type MsgType, type MutateActionData, type PermissionAnalysis, type PermissionContext, type PermissionLevel, type PermissionSource, type PlatformWorkerEnv, type Player, type PrefixResult, type PresencePeer, PresenceRoom, type ProtocolMessage, type QueryActionData, REACTIONS_SCHEMA, READ_RECEIPTS_SCHEMA, RESERVED_BINDING_NAMES, RESERVED_COLLECTION_NAMES, ROLE_ADMIN, ROLE_ANONYMOUS, ROLE_DEFAULT, RecordRoom, type RecordRoomConfig, type ResolvedColumn, type ResolvedPermission, type RolePermissions, type RunMigrationsResult, SYSTEM_COLLECTIONS, SYSTEM_MANAGED_COLUMNS, SchemaRegistry, type ScopeContext, type ScopedR2Auth, type ScopedR2Config, type ScopedR2Handler, type ScreenshotEnv, type ScreenshotOptions, type ScreenshotResult, type ServerMessage, type SharedConnection, type StoredRecord, type Summarizer, type SyncResult, TEST_ACCOUNT_EMAIL_SUFFIX, type TokenDebugInfo, type ToolResult, type ToolSchema, USERS_COLUMNS, type User, type UserAttachment, VOTING_SCHEMAS, type ValidationError, type VerifiedAuth, type VerifyOutcome, type VerifyResult, type Viewport, WORKSPACE_SCHEMAS, YjsRoom, analyzePermissions, apiWorkerFetch, appendMessage, applyAiToolDefaults, applySlidingWindow, authWorkerFetch, bindingManifestFromOutputConfig, buildCronContext, buildTableSelect, buildUiParts, canCreate, canDelete, canRead, canUpdate, capToolResultSize, captureScreenshot, checkFieldPermissions, clientBuild, coerceValue, collectionTableName, columnId, composioTools, computeDoMigration, computeHmacHex, createChat, createDecoder, createDeepSpaceAI, createDeepSpaceAuth, createEncoder, createScopedR2Handler, dataToColumnValues, decodeJwtPayload, deleteChatCascade, dispatch, encode, encodeAwarenessMessage, encodeSyncStep1, encodeSyncStep2, encodeUpdate, enqueueJob, getChat, getGlobalDOSchemas, getGlobalDOType, getMessageType, getRolePermissions, handleAwarenessMessage, handleSyncMessage, hasContent, isAutoProvision, isOwner, isTestAccountClaims, isTestAccountEmail, isTestAccountTier, lintSchema, loadMessages, makeDefaultSummarizer, meterAi, meterUsage, meterVectorize, noopPermissionContext, platformWorkerFetch, prepareMessagesWithCompaction, priceBindingUsageEvent, readVarUint, readVarUint8Array, resolveAppName, resolveColumn, rowToData, runMigrations, serverBuild, timingSafeEqualHex, timingSafeEqualStrings, toUint8Array, totalChars, truncateOldToolResults, turnsToCoreMessages, unwrapToolOutput, updateChat, validateAppName, validateBindingManifest, validateDoManifest, verifyJwt, workspaceAccountsSchema, workspaceContentSharesSchema, workspaceEmailHandlesSchema, workspaceFormResponsesSchema, workspacePeopleSchema, workspaceProjectsSchema, workspaceTagsSchema, workspaceTasksSchema, workspaceTeamMembersSchema, workspaceTeamsSchema, workspaceTransactionsSchema, writeVarUint, writeVarUint8Array };
+/**
+ * Client-error ingestion route (opt-in) — the Worker half of client-side
+ * error reporting.
+ *
+ * Mount it in your app Worker with a single line:
+ *
+ *   import { registerClientErrorRoute } from 'deepspace/worker'
+ *   registerClientErrorRoute(app)   // BEFORE the app.all('/_deepspace/*') proxy
+ *
+ * Then, in the browser, `installClientErrorReporter()` (from 'deepspace')
+ * forwards uncaught errors here. The handler runs in the app's OWN Worker, so
+ * the `console.error` it emits is tagged by Cloudflare with this app's id —
+ * meaning a browser can only ever write to its own app's log stream, never
+ * another tenant's or the platform's. Reports then surface in `deepspace logs`
+ * (and the dashboard) tagged `CLIENT`.
+ *
+ * Anonymous by design (logged-out visitors hit client errors too), so the
+ * defenses are size caps (normalizeClientErrorReport) + a best-effort
+ * per-isolate throttle. It never blocks the page: it returns 204 and swallows
+ * work quickly.
+ */
+
+/**
+ * Handle one client-error report. Framework-agnostic — pass a raw `Request`.
+ * Returns 204 on success, 400 on a malformed/empty body, 429 when throttled.
+ */
+declare function handleClientErrorReport(request: Request): Promise<Response>;
+/**
+ * Register `POST /_deepspace/client-errors` on your Hono app. Mount it BEFORE
+ * the `app.all('/_deepspace/*')` proxy so the specific route wins the match.
+ */
+declare function registerClientErrorRoute(app: Hono<any, any, any>): void;
+
+/**
+ * Client-side error reporting — shared contract.
+ *
+ * Browser JS errors never invoke the app's Worker, so they never reach
+ * Workers Logs and are invisible to `deepspace logs`. The opt-in reporter
+ * (`installClientErrorReporter`, client entry) forwards them to the app's own
+ * Worker via `registerClientErrorRoute` (worker entry), which `console.error`s
+ * a marker-prefixed envelope. The platform log reader recognises the marker
+ * and tags the event `source: 'client'`.
+ *
+ * This module is isomorphic — no DOM, no Hono — so both halves import the
+ * exact same marker, caps, and normaliser and can never drift.
+ */
+/**
+ * Prefix the Worker route prepends before JSON-stringifying a report into a
+ * single `console.error` line. The platform mapper
+ * (platform/deploy-worker/src/lib/workers-logs.ts) detects this prefix to set
+ * `source: 'client'`. Deliberately distinctive so an ordinary app log is
+ * vanishingly unlikely to collide. The marker is added SERVER-SIDE by the app
+ * Worker — a browser cannot forge it onto a genuine server log.
+ *
+ * The platform copy is kept in sync by a drift test; if you change this
+ * string, that test fails until the platform const matches.
+ */
+declare const CLIENT_LOG_MARKER = "[deepspace:client-error]";
+type ClientErrorKind = 'error' | 'unhandledrejection' | 'react';
+/** A sanitized, capped browser-error report — the wire + log-line payload. */
+interface ClientErrorReport {
+    kind: ClientErrorKind;
+    message: string;
+    name?: string;
+    stack?: string;
+    /** Page URL where it fired (href or the script filename). */
+    url?: string;
+    line?: number;
+    col?: number;
+}
+
+/**
+ * `deepspace logs` wire DTO — the single source of truth for the whitelisted
+ * shape the platform telemetry reader emits and every consumer reads.
+ *
+ * The producer is `platform/deploy-worker/src/lib/workers-logs.ts` (which
+ * rebuilds each event field-by-field from a raw Cloudflare row — see the
+ * security invariant there). The consumers are the CLI tail
+ * (`cli/commands/logs.ts`), the dashboard Logs panel
+ * (`apps/dashboard/src/lib/types.ts`), and the e2e whitelist assertion
+ * (`tests/e2e/tests/logs.spec.ts`). This module used to be hand-mirrored in
+ * all four places; `source` was added to three of them and missed in the
+ * e2e whitelist, so it now lives here once and they import it.
+ *
+ * Isomorphic — no DOM, no Hono, no platform types — so it re-exports cleanly
+ * from both `deepspace` (client) and `deepspace/worker` and is safe to import
+ * from the private deploy-worker.
+ */
+declare const LOG_LEVELS: readonly ["debug", "log", "info", "warn", "error"];
+type LogLevel = (typeof LOG_LEVELS)[number];
+/** One log / request / exception event, rebuilt field-by-field from a CF row. */
+interface AppLogEvent {
+    /** `$metadata.id` — unique per event; the client's dedupe key. */
+    id: string;
+    /** Unix ms. */
+    timestamp: number;
+    level: LogLevel;
+    eventType: 'log' | 'request' | 'exception' | 'other';
+    message: string;
+    /**
+     * Present (= `'client'`) only for a browser-forwarded error the app's own
+     * Worker re-logged via `registerClientErrorRoute`. Absent means the log was
+     * emitted server-side — there is no explicit `'server'` value, so consumers
+     * branch on `source === 'client'`, never on a truthy/other check.
+     */
+    source?: 'client';
+    /** Invocation outcome (`ok`, `exception`, `exceededCpu`, …) when present. */
+    outcome?: string;
+    request?: {
+        method: string;
+        path: string;
+        status?: number;
+    };
+    exception?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+}
+interface AppLogsResponse {
+    /** Ascending by timestamp (CF returns newest-first; the reader flips). */
+    events: AppLogEvent[];
+    /** Max event timestamp in ms — pass back as `since` to poll; null when empty. */
+    cursor: number | null;
+    /** True when the window returned `limit` events (older events were cut). */
+    truncated: boolean;
+    pollIntervalMs: number;
+}
+/**
+ * Runtime tuple of every key a whitelisted `AppLogEvent` may carry — the
+ * canonical whitelist the e2e suite mirrors when asserting no event leaks a key
+ * outside this set. The two type-level assertions below fail compilation if
+ * this tuple and the `AppLogEvent` interface disagree in either direction, so
+ * adding an interface field forces a matching key here.
+ *
+ * NOTE: the e2e spec keeps its OWN copy of this set (it can't import the SDK —
+ * `@deepspace/e2e` has no `deepspace` dependency), kept in step by a comment,
+ * not by these compile-time guards. So this tuple hardens the code copies
+ * (deploy-worker/CLI/dashboard, which import it), while the e2e mirror remains a
+ * knowingly-accepted duplicate.
+ */
+declare const APP_LOG_EVENT_KEYS: readonly ["id", "timestamp", "level", "eventType", "message", "source", "outcome", "request", "exception"];
+type AppLogEventKey = (typeof APP_LOG_EVENT_KEYS)[number];
+
+export { AI_CHATS_SCHEMA, AI_MESSAGES_SCHEMA, ALLOWED_BINDING_TYPES, APP_LOG_EVENT_KEYS, APP_NAME_RULES, AUTO_PROVISIONABLE_TYPES, AUTO_PROVISION_SENTINEL, type ActionContext, type ActionHandler, type ActionResult, type ActionTools, type ApiWorkerEnv, type AppLogEvent, type AppLogEventKey, type AppLogsResponse, type AppNameResolution, type AppNameValidation, type AuthWorkerEnv, Awareness, type AwarenessState, type AwarenessStates, BASE_USERS_SCHEMA, BUILT_IN_TOOLS, type BaseMessage, BaseRoom, CHANNELS_SCHEMA, CHANNEL_INVITATIONS_SCHEMA, CHANNEL_MEMBERS_SCHEMA, CLIENT_LOG_MARKER, CONVERSATION_SCHEMAS, COST_RATES, CanvasRoom, type CanvasShape, type ChatContextConfig, type ChatMessageRow, type ChatRow, type ChatTurn, type ClientErrorKind, type ClientErrorReport, type ClientMessage, type CollectionPermissionSummary, type CollectionSchema, type ColumnDefinition, type ColumnInterpretation, type ComposioToolsOptions, type ConnectionAttachment, type ConvMemberData, type ConvMessageData, type ConvReactionData, type ConvReadCursorData, type ConvVoteData, type ConversationStateData, type CronContext, type CronExecution, CronRoom, type CronRoomConfig, type CronTask, type CustomBinding, type CustomBindingManifest, DEFAULT_CONTEXT_CONFIG, DEFAULT_DO_MANIFEST, DEFAULT_QUERY_LIMIT, DIRECTORY_SCHEMAS, type DOBindings, type DOManifest, type DOManifestEntry, type DeepSpaceAIEnv, type DeepSpaceAIOptions, type DeepSpaceAuth, type DeepSpaceAuthConfig, type DirectoryCommunityData, type DirectoryConversationData, type DirectoryMembershipData, type DirectoryPostData, type DoMigrationDirective, type DoMigrationPlan, type ExistingDOBinding, GLOBAL_DO_TYPES, GLOBAL_DO_TYPE_NAMES, type GameInput, GameRoom, type GameRoomConfig, type GetActionData, type GlobalDOType, type HandlerContext, type Job, type JobContext, JobRoom, type JobRoomConfig, type JobStatus, type JwtClaims, type JwtVerifierConfig, LOG_LEVELS, type LogLevel, MESSAGES_SCHEMA, MSG, MSG_AWARENESS, MSG_SYNC, MSG_SYNC_STEP1, MSG_SYNC_STEP2, MSG_SYNC_UPDATE, MSG_YJS_AWARENESS, MSG_YJS_SYNC, type MessageHandlers, type MsgType, type MutateActionData, type PermissionAnalysis, type PermissionContext, type PermissionLevel, type PermissionSource, type PlatformWorkerEnv, type Player, type PrefixResult, type PresencePeer, PresenceRoom, type ProtocolMessage, type QueryActionData, REACTIONS_SCHEMA, READ_RECEIPTS_SCHEMA, RESERVED_BINDING_NAMES, RESERVED_COLLECTION_NAMES, ROLE_ADMIN, ROLE_ANONYMOUS, ROLE_DEFAULT, RecordRoom, type RecordRoomConfig, type ResolvedColumn, type ResolvedPermission, type RolePermissions, type RunMigrationsResult, SYSTEM_COLLECTIONS, SYSTEM_MANAGED_COLUMNS, SchemaRegistry, type ScopeContext, type ScopedR2Auth, type ScopedR2Config, type ScopedR2Handler, type ScreenshotEnv, type ScreenshotOptions, type ScreenshotResult, type ServerMessage, type SharedConnection, type StoredRecord, type Summarizer, type SyncResult, TEST_ACCOUNT_EMAIL_SUFFIX, type TokenDebugInfo, type ToolResult, type ToolSchema, USERS_COLUMNS, type User, type UserAttachment, VOTING_SCHEMAS, type ValidationError, type VerifiedAuth, type VerifyOutcome, type VerifyResult, type Viewport, WORKSPACE_SCHEMAS, YjsRoom, analyzePermissions, apiWorkerFetch, appendMessage, applyAiToolDefaults, applySlidingWindow, authWorkerFetch, bindingManifestFromOutputConfig, buildCronContext, buildTableSelect, buildUiParts, canCreate, canDelete, canRead, canUpdate, capToolResultSize, captureScreenshot, checkFieldPermissions, clientBuild, coerceValue, collectionTableName, columnId, composioTools, computeDoMigration, computeHmacHex, createChat, createDecoder, createDeepSpaceAI, createDeepSpaceAuth, createEncoder, createScopedR2Handler, dataToColumnValues, decodeJwtPayload, deleteChatCascade, dispatch, encode, encodeAwarenessMessage, encodeSyncStep1, encodeSyncStep2, encodeUpdate, enqueueJob, getChat, getGlobalDOSchemas, getGlobalDOType, getMessageType, getRolePermissions, handleAwarenessMessage, handleClientErrorReport, handleSyncMessage, hasContent, isAutoProvision, isOwner, isTestAccountClaims, isTestAccountEmail, isTestAccountTier, lintSchema, loadMessages, makeDefaultSummarizer, meterAi, meterUsage, meterVectorize, noopPermissionContext, platformWorkerFetch, prepareMessagesWithCompaction, priceBindingUsageEvent, readVarUint, readVarUint8Array, registerClientErrorRoute, resolveAppName, resolveColumn, rowToData, runMigrations, serverBuild, timingSafeEqualHex, timingSafeEqualStrings, toUint8Array, totalChars, truncateOldToolResults, turnsToCoreMessages, unwrapToolOutput, updateChat, validateAppName, validateBindingManifest, validateDoManifest, verifyJwt, workspaceAccountsSchema, workspaceContentSharesSchema, workspaceEmailHandlesSchema, workspaceFormResponsesSchema, workspacePeopleSchema, workspaceProjectsSchema, workspaceTagsSchema, workspaceTasksSchema, workspaceTeamMembersSchema, workspaceTeamsSchema, workspaceTransactionsSchema, writeVarUint, writeVarUint8Array };

package/dist/worker.js

@@ -16,6 +16,8 @@ var BaseRoom = class {
   // ==========================================================================
   async fetch(request) {
     const url = new URL(request.url);
+    const internal = await this.handleInternalRequest(request, url);
+    if (internal) return internal;
     if (request.headers.get("Upgrade") === "websocket") {
       return this.handleWebSocketUpgrade(request, url);
     }
@@ -25,6 +27,36 @@ var BaseRoom = class {
     return new Response("Not Found", { status: 404 });
   }
   // ==========================================================================
+  // Internal Control-Plane Endpoints
+  // ==========================================================================
+  /**
+   * Handle built-in `/internal/*` control-plane routes shared by every room
+   * type. Returns a `Response` if the request was an internal route, or `null`
+   * to let the caller continue normal dispatch.
+   *
+   * Currently:
+   * - `POST /internal/disconnect-sockets` — close every live WebSocket so
+   *   clients reconnect and resync. Optional JSON body `{ code?, reason? }`
+   *   overrides the defaults (1012 / 'state-refresh'). Responds with
+   *   `{ success: true, closed: <n> }`.
+   *
+   * See the security note on `fetch()`: this path is only reachable via DO
+   * stub fetch from the app worker, never from the public internet.
+   */
+  async handleInternalRequest(request, url) {
+    if (request.method === "POST" && url.pathname === "/internal/disconnect-sockets") {
+      let options;
+      try {
+        const text = await request.text();
+        if (text) options = JSON.parse(text);
+      } catch {
+      }
+      const closed = this.disconnectAllSockets(options);
+      return Response.json({ success: true, closed });
+    }
+    return null;
+  }
+  // ==========================================================================
   // WebSocket Connection
   // ==========================================================================
   async handleWebSocketUpgrade(request, url) {
@@ -111,6 +143,42 @@ var BaseRoom = class {
   getWebSockets() {
     return this.state.getWebSockets();
   }
+  /**
+   * Force every connected client to reconnect and resync by closing all live
+   * WebSockets. Returns the number of sockets closed.
+   *
+   * Use this after an **out-of-band, server-side write** to the room's records
+   * — an admin import route, a migration script, a cron job, or a server
+   * action — that connected clients have no way to learn about. Without it, a
+   * browser tab holding stale in-memory state keeps operating on (and may
+   * autosave over) data that changed underneath it. Closing the socket makes
+   * the client SDK reconnect and pull fresh query results.
+   *
+   * The default close code is 1012 ("service restart") with reason
+   * 'state-refresh'. The DeepSpace client treats *any* close as a reconnect
+   * trigger (it does not special-case clean/1000 closes), so on reconnect it
+   * re-subscribes every active query and receives fresh `QUERY_RESULT`s —
+   * `useQuery` consumers see the new data without re-subscribing.
+   *
+   * Each close is guarded so one already-closing socket can't abort the sweep.
+   *
+   * @param options.code   WebSocket close code (default 1012).
+   * @param options.reason WebSocket close reason (default 'state-refresh').
+   * @returns the number of sockets that were closed.
+   */
+  disconnectAllSockets(options) {
+    const code = options?.code ?? 1012;
+    const reason = options?.reason ?? "state-refresh";
+    let closed = 0;
+    for (const ws of this.state.getWebSockets()) {
+      try {
+        ws.close(code, reason);
+        closed++;
+      } catch {
+      }
+    }
+    return closed;
+  }
   /**
    * Get the user attachment for a WebSocket.
    */
@@ -2670,6 +2738,16 @@ var RecordRoom = class extends BaseRoom {
   get perfLogEnabled() {
     return !!this.env?.DEEPSPACE_DO_PERF;
   }
+  /**
+   * The HTTP debug API (`/api/debug/*`) runs arbitrary SQL and role changes
+   * with no auth of its own, so it is gated here at the DO's single ingress.
+   * Off unless a deployment opts in with `ALLOW_DEBUG_ROUTES=true`
+   * (`deepspace dev`/`test` set it automatically). Deployments holding shared
+   * data override this to always return false.
+   */
+  get debugRoutesEnabled() {
+    return this.env?.ALLOW_DEBUG_ROUTES === "true";
+  }
   constructor(state, env, schemas = [], config = {}) {
     super(state, env);
     this.schemaRegistry = new SchemaRegistry([
@@ -2705,14 +2783,21 @@ var RecordRoom = class extends BaseRoom {
   // HTTP Entry Point (overrides BaseRoom.fetch)
   // ============================================================================
   async fetch(request) {
+    const url = new URL(request.url);
+    if (url.pathname.startsWith("/internal/")) {
+      const internal = await this.handleInternalRequest(request, url);
+      if (internal) return internal;
+    }
     const fetchStart = Date.now();
     const isColdStart = this.freshConstruct;
     const needsInit = !this.initPromise;
     this.freshConstruct = false;
     await this.ensureInitialized();
     const initMs = Date.now() - fetchStart;
-    const url = new URL(request.url);
     if (url.pathname.startsWith("/api/")) {
+      if (url.pathname.startsWith("/api/debug/") && !this.debugRoutesEnabled) {
+        return new Response("Not Found", { status: 404 });
+      }
       return handleApiRequest(this.createHandlerContext(), request, url);
     }
     if (request.headers.get("Upgrade") === "websocket") {
@@ -7232,10 +7317,111 @@ async function generateAppleClientSecret(apple) {
   cachedAppleSecret = { keyId: apple.keyId, token, expiresAt };
   return token;
 }
+
+// src/shared/client-errors.ts
+var CLIENT_LOG_MARKER = "[deepspace:client-error]";
+var CLIENT_ERROR_PATH = "/_deepspace/client-errors";
+var CLIENT_ERROR_CAPS = {
+  message: 1024,
+  stack: 4096,
+  name: 256,
+  url: 512
+};
+function capText(value, max) {
+  if (typeof value !== "string") return void 0;
+  return value.length > max ? value.slice(0, max) : value;
+}
+function finiteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function normalizeClientErrorReport(raw) {
+  if (typeof raw !== "object" || raw === null) return null;
+  const o = raw;
+  const kind = o.kind === "unhandledrejection" || o.kind === "react" ? o.kind : "error";
+  const message = capText(o.message, CLIENT_ERROR_CAPS.message) ?? "";
+  const name = capText(o.name, CLIENT_ERROR_CAPS.name);
+  const stack = capText(o.stack, CLIENT_ERROR_CAPS.stack);
+  const url = capText(o.url, CLIENT_ERROR_CAPS.url);
+  const line = finiteNumber(o.line);
+  const col = finiteNumber(o.col);
+  if (!message && !stack) return null;
+  const report = { kind, message: message || (name ?? "Error") };
+  if (name) report.name = name;
+  if (stack) report.stack = stack;
+  if (url) report.url = url;
+  if (line !== void 0) report.line = line;
+  if (col !== void 0) report.col = col;
+  return report;
+}
+function clientErrorToLogLine(report) {
+  return `${CLIENT_LOG_MARKER} ${JSON.stringify(report)}`;
+}
+
+// src/server/client-errors.ts
+var THROTTLE_WINDOW_MS = 1e3;
+var THROTTLE_MAX = 20;
+var windowStart = 0;
+var windowCount = 0;
+var MAX_BODY_BYTES = 64 * 1024;
+function shouldThrottleClientError(now = Date.now()) {
+  if (now - windowStart >= THROTTLE_WINDOW_MS) {
+    windowStart = now;
+    windowCount = 0;
+  }
+  windowCount += 1;
+  return windowCount > THROTTLE_MAX;
+}
+function jsonResponse(body, status) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+async function handleClientErrorReport(request) {
+  const site = request.headers.get("sec-fetch-site");
+  if (site && site !== "same-origin" && site !== "none") {
+    return new Response(null, { status: 403 });
+  }
+  if (shouldThrottleClientError()) {
+    return new Response(null, { status: 429, headers: { "Retry-After": "1" } });
+  }
+  const declared = Number(request.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+    return jsonResponse({ error: "payload_too_large" }, 413);
+  }
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    return jsonResponse({ error: "invalid_json" }, 400);
+  }
+  const report = normalizeClientErrorReport(body);
+  if (!report) return jsonResponse({ error: "invalid_report" }, 400);
+  console.error(clientErrorToLogLine(report));
+  return new Response(null, { status: 204 });
+}
+function registerClientErrorRoute(app) {
+  app.post(CLIENT_ERROR_PATH, (c) => handleClientErrorReport(c.req.raw));
+}
+
+// src/shared/log-events.ts
+var LOG_LEVELS = ["debug", "log", "info", "warn", "error"];
+var APP_LOG_EVENT_KEYS = [
+  "id",
+  "timestamp",
+  "level",
+  "eventType",
+  "message",
+  "source",
+  "outcome",
+  "request",
+  "exception"
+];
 export {
   AI_CHATS_SCHEMA,
   AI_MESSAGES_SCHEMA,
   ALLOWED_BINDING_TYPES,
+  APP_LOG_EVENT_KEYS,
   APP_NAME_RULES,
   AUTO_PROVISIONABLE_TYPES,
   AUTO_PROVISION_SENTINEL,
@@ -7246,6 +7432,7 @@ export {
   CHANNELS_SCHEMA,
   CHANNEL_INVITATIONS_SCHEMA,
   CHANNEL_MEMBERS_SCHEMA,
+  CLIENT_LOG_MARKER,
   CONVERSATION_SCHEMAS,
   COST_RATES,
   CanvasRoom,
@@ -7258,6 +7445,7 @@ export {
   GLOBAL_DO_TYPE_NAMES,
   GameRoom,
   JobRoom,
+  LOG_LEVELS,
   MESSAGES_SCHEMA,
   MSG,
   MSG_AWARENESS,
@@ -7330,6 +7518,7 @@ export {
   getMessageType,
   getRolePermissions,
   handleAwarenessMessage,
+  handleClientErrorReport,
   handleSyncMessage,
   hasContent,
   isAutoProvision,
@@ -7349,6 +7538,7 @@ export {
   priceBindingUsageEvent,
   readVarUint,
   readVarUint8Array,
+  registerClientErrorRoute,
   resolveAppName,
   resolveColumn,
   rowToData,