@concavejs/core 0.0.1-alpha.7 → 0.0.1-alpha.9

package/dist/auth/auth-context.d.ts

@@ -1,22 +1,11 @@
 /**
- * Ambient Authentication Context using AsyncLocalStorage
+ * Ambient Authentication Context.
  *
- * This module provides ambient auth context that automatically propagates through
- * the entire UDF execution chain without explicit parameter threading.
- *
- * Benefits:
- * - No need to pass auth through every function call
- * - Works automatically with nested UDF calls
- * - Simplifies function signatures
- * - Prevents auth context from being accidentally lost
+ * Context storage automatically propagates through async call chains when
+ * AsyncLocalStorage is available (Node/Bun). In runtimes without ALS, the
+ * fallback behaves correctly for serialized execution.
  */
-import { AsyncLocalStorage } from "node:async_hooks";
 import type { UserIdentityAttributes } from "convex/server";
-/**
- * AsyncLocalStorage for authentication context.
- * This provides automatic context propagation through async call chains.
- */
-export declare const authContext: AsyncLocalStorage<UserIdentityAttributes | undefined>;
 /**
  * Get the current authentication context.
  * Returns undefined if no auth context is set (unauthenticated request).

package/dist/auth/auth-context.js

@@ -1,21 +1,12 @@
 /**
- * Ambient Authentication Context using AsyncLocalStorage
+ * Ambient Authentication Context.
  *
- * This module provides ambient auth context that automatically propagates through
- * the entire UDF execution chain without explicit parameter threading.
- *
- * Benefits:
- * - No need to pass auth through every function call
- * - Works automatically with nested UDF calls
- * - Simplifies function signatures
- * - Prevents auth context from being accidentally lost
- */
-import { AsyncLocalStorage } from "node:async_hooks";
-/**
- * AsyncLocalStorage for authentication context.
- * This provides automatic context propagation through async call chains.
+ * Context storage automatically propagates through async call chains when
+ * AsyncLocalStorage is available (Node/Bun). In runtimes without ALS, the
+ * fallback behaves correctly for serialized execution.
  */
-export const authContext = new AsyncLocalStorage();
+import { ContextStorage } from "../kernel/context-storage";
+const authContext = new ContextStorage();
 /**
  * Get the current authentication context.
  * Returns undefined if no auth context is set (unauthenticated request).

package/dist/docstore/index.d.ts

@@ -4,6 +4,7 @@
  * Platform-agnostic document storage interface
  */
 export * from "./interface";
+export * from "./search-interfaces";
 export * from "./sql/schema";
 export * from "./search-index-registration";
 export * from "./vector-index-registration";

package/dist/docstore/index.js

@@ -4,6 +4,7 @@
  * Platform-agnostic document storage interface
  */
 export * from "./interface";
+export * from "./search-interfaces";
 export * from "./sql/schema";
 export * from "./search-index-registration";
 export * from "./vector-index-registration";

package/dist/docstore/interface.d.ts

@@ -129,12 +129,20 @@ export interface DocStore {
         nextCursor: string | null;
         hasMore: boolean;
     }>;
+    /**
+     * @deprecated Prefer the `SearchCapable` interface from `./search-interfaces`.
+     * This method will be removed from `DocStore` in a future version.
+     */
     search(indexId: ArrayBufferHex, searchQuery: string, filters: Map<string, unknown>, options?: {
         limit?: number;
     }): Promise<{
         doc: LatestDocument;
         score: number;
     }[]>;
+    /**
+     * @deprecated Prefer the `VectorSearchCapable` interface from `./search-interfaces`.
+     * This method will be removed from `DocStore` in a future version.
+     */
     vectorSearch(indexId: ArrayBufferHex, vector: number[], limit: number, filters: Map<string, string>): Promise<{
         doc: LatestDocument;
         score: number;

package/dist/docstore/interface.js

@@ -18,6 +18,12 @@ export function parseDocumentIdKey(key) {
     const internalId = key.substring(colonIndex + 1);
     if (!table || !internalId)
         return null;
+    if (table.startsWith("#")) {
+        const tableNumber = Number.parseInt(table.slice(1), 10);
+        if (Number.isInteger(tableNumber) && tableNumber > 0) {
+            return { table, internalId, tableNumber };
+        }
+    }
     return { table, internalId };
 }
 /**

package/dist/docstore/search-interfaces.d.ts

@@ -0,0 +1,29 @@
+import type { ArrayBufferHex, LatestDocument, DocStore } from "./interface";
+/**
+ * Interface for DocStore implementations that support full-text search.
+ * Prefer checking for this capability via `isSearchCapable()` type guard
+ * rather than assuming all DocStore implementations support search.
+ */
+export interface SearchCapable {
+    search(indexId: ArrayBufferHex, searchQuery: string, filters: Map<string, unknown>, options?: {
+        limit?: number;
+    }): Promise<{
+        doc: LatestDocument;
+        score: number;
+    }[]>;
+}
+/**
+ * Interface for DocStore implementations that support vector similarity search.
+ * Prefer checking for this capability via `isVectorSearchCapable()` type guard
+ * rather than assuming all DocStore implementations support vector search.
+ */
+export interface VectorSearchCapable {
+    vectorSearch(indexId: ArrayBufferHex, vector: number[], limit: number, filters: Map<string, string>): Promise<{
+        doc: LatestDocument;
+        score: number;
+    }[]>;
+}
+/** Type guard for DocStore implementations that support full-text search */
+export declare function isSearchCapable(store: DocStore): store is DocStore & SearchCapable;
+/** Type guard for DocStore implementations that support vector similarity search */
+export declare function isVectorSearchCapable(store: DocStore): store is DocStore & VectorSearchCapable;

package/dist/docstore/search-interfaces.js

@@ -0,0 +1,8 @@
+/** Type guard for DocStore implementations that support full-text search */
+export function isSearchCapable(store) {
+    return typeof store.search === "function";
+}
+/** Type guard for DocStore implementations that support vector similarity search */
+export function isVectorSearchCapable(store) {
+    return typeof store.vectorSearch === "function";
+}

package/dist/http/http-handler.js

@@ -7,7 +7,7 @@
 import { loadConvexModule } from "../udf";
 import { createClientAdapter } from "../udf/execution-adapter";
 import { UdfKernel } from "../queryengine";
-import { applyCors, computeCorsHeaders, handleCoreHttpApiRequest, resolveAuthContext } from "./index";
+import { applyCors, computeCorsHeaders, handleCoreHttpApiRequest, resolveAuthContext } from "./api-router";
 import { writtenTablesFromRanges } from "../utils";
 import { AdminAuthError, identityFromToken, isAdminToken, isSystemToken, JWTValidationError, SystemAuthError, } from "../auth";
 const VERSIONED_API_PREFIX = /^\/api\/\d+\.\d+(?:\.\d+)?(?=\/|$)/;
@@ -115,7 +115,7 @@ export class HttpHandler {
             storage: this.docstore && this.blobstore
                 ? {
                     store: async (blob) => {
-                        const convex = new UdfKernel(this.docstore, undefined, this.blobstore);
+                        const convex = new UdfKernel({ docstore: this.docstore, storage: this.blobstore });
                         const storageId = await convex.jsSyscall("storage/storeBlob", { blob });
                         const writtenRanges = convex.getTrackedWriteRanges();
                         return {
@@ -125,7 +125,7 @@ export class HttpHandler {
                         };
                     },
                     get: async (storageId) => {
-                        const convex = new UdfKernel(this.docstore, undefined, this.blobstore);
+                        const convex = new UdfKernel({ docstore: this.docstore, storage: this.blobstore });
                         const blob = await convex.jsSyscall("storage/getBlob", { storageId });
                         return { blob: blob ?? null };
                     },
@@ -296,6 +296,12 @@ export class HttpHandler {
         if (url.pathname === "/health") {
             return apply(Response.json({ status: "ok", runtime: this.runtimeName }));
         }
+        // Fallback: forward any unmatched, non-reserved path to the HTTP router.
+        // In Convex, HTTP actions are accessible at any path on the deployment URL
+        // (e.g. path: "/" matches requests to the root), not just under /api/http/*.
+        if (!isReservedApiPath(url.pathname)) {
+            return forwardHttpRequest(request, "HTTP action");
+        }
         return apply(Response.json({ error: "Not found" }, { status: 404 }));
     }
 }

package/dist/id-codec/document-id.js

@@ -13,6 +13,7 @@
 import { base32Encode, base32Decode, isValidBase32 } from './base32';
 import { vintEncode, vintDecode, vintEncodedLength } from './vint';
 import { fletcher16, verifyFletcher16 } from './fletcher16';
+import { fillRandomValues } from '../utils/crypto';
 /** Internal ID is always 16 bytes (128 bits) */
 export const INTERNAL_ID_LENGTH = 16;
 /** Minimum encoded length: 1 (vint) + 16 (id) + 2 (checksum) = 19 bytes = 31 base32 chars */
@@ -98,11 +99,11 @@ export function isValidDocumentId(encoded) {
     }
 }
 // NOTE: Deterministic ID generation for retries is handled by the UDF runtime
-// via an injected generator. This helper remains cryptographically random.
-const cryptoGetRandomValues = crypto.getRandomValues.bind(crypto);
+// via an injected generator. This helper remains cryptographically random when
+// native crypto is available, and degrades gracefully in runtimes without it.
 function randomBytes(n) {
     const buf = new Uint8Array(n);
-    cryptoGetRandomValues(buf);
+    fillRandomValues(buf);
     return buf;
 }
 /**

package/dist/index.d.ts

@@ -10,12 +10,12 @@ export { type ArrayBufferHex, type InternalDocumentId, documentIdKey, parseDocum
 export * from "./docstore/sql/schema";
 export * from "./docstore/search-index-registration";
 export * from "./transactor";
-export { UdfKernel } from "./kernel/udf-kernel";
+export { UdfKernel, type UdfKernelConfig } from "./kernel/udf-kernel";
 export { snapshotContext, transactionContext } from "./kernel/contexts";
 export { QueryRuntime } from "./query/query-runtime";
 export { SchemaService } from "./kernel/schema-service";
 export { BlobStoreGateway } from "./kernel/blob-store-gateway";
-export { DocStoreGateway } from "./kernel/docstore-gateway";
+export { DocStoreGateway, createDocAccess, type DocAccess } from "./kernel/docstore-gateway";
 export { SchedulerGateway } from "./kernel/scheduler-gateway";
 export { UdfInvocationManager } from "./kernel/udf-invocation-manager";
 export * from "./queryengine/cursor";
@@ -40,6 +40,7 @@ export * from "./utils/timestamp";
 export * from "./utils/keyspace";
 export * from "./utils/serialization";
 export * from "./utils/written-ranges";
+export * from "./utils/base64";
 export type { TransactionHandle, CommitResult, OplogDelta, Transactor } from "./interfaces/transactor";
 export type { KeyRange as InterfaceKeyRange } from "./interfaces/transactor";
 export { type ChangeDelta, type ChangeStreamConsumer, } from "./interfaces/change-stream-consumer";

package/dist/index.js

@@ -15,7 +15,7 @@ export { snapshotContext, transactionContext } from "./kernel/contexts";
 export { QueryRuntime } from "./query/query-runtime";
 export { SchemaService } from "./kernel/schema-service";
 export { BlobStoreGateway } from "./kernel/blob-store-gateway";
-export { DocStoreGateway } from "./kernel/docstore-gateway";
+export { DocStoreGateway, createDocAccess } from "./kernel/docstore-gateway";
 export { SchedulerGateway } from "./kernel/scheduler-gateway";
 export { UdfInvocationManager } from "./kernel/udf-invocation-manager";
 export * from "./queryengine/cursor";
@@ -49,6 +49,7 @@ export * from "./utils/timestamp";
 export * from "./utils/keyspace";
 export * from "./utils/serialization";
 export * from "./utils/written-ranges";
+export * from "./utils/base64";
 export * from "./interfaces/shard-router";
 export * from "./interfaces/cache-strategy";
 export * from "./interfaces/execution-context";

package/dist/kernel/blob-store-gateway.js

@@ -93,11 +93,12 @@ export class BlobStoreGateway {
         if (!latest || latest.ts > this.context.snapshotTimestamp) {
             return;
         }
-        await storage.delete(docId.internalId);
+        const canonicalDocId = latest.value.id;
+        await storage.delete(canonicalDocId.internalId);
         const timestamp = this.docStore.allocateTimestamp();
-        const entry = { ts: timestamp, id: docId, value: null, prev_ts: latest.ts };
+        const entry = { ts: timestamp, id: canonicalDocId, value: null, prev_ts: latest.ts };
         await this.docStore.applyWrites([entry], new Set(), "Error");
-        this.context.recordLocalWrite(storageId, "_storage", null, docId);
+        this.context.recordLocalWrite(storageId, "_storage", null, canonicalDocId);
     }
     requireStorage() {
         if (!this.storage) {

package/dist/kernel/context-storage.d.ts

@@ -1,4 +1,5 @@
 type Callback<T> = () => Promise<T> | T;
+export declare function hasAsyncLocalStorageSupport(): boolean;
 export declare class ContextStorage<T> {
     private readonly als?;
     private readonly stack;

package/dist/kernel/context-storage.js

@@ -1,21 +1,39 @@
+function resolveFromRequire(req) {
+    for (const specifier of ["node:async_hooks", "async_hooks"]) {
+        try {
+            const mod = req(specifier);
+            if (mod?.AsyncLocalStorage) {
+                return mod.AsyncLocalStorage;
+            }
+        }
+        catch {
+            // Try the next candidate module specifier.
+        }
+    }
+    return undefined;
+}
 const resolveAsyncLocalStorage = () => {
-    if (typeof globalThis !== "undefined" && globalThis.AsyncLocalStorage) {
-        return globalThis.AsyncLocalStorage;
+    const globalCtor = globalThis?.AsyncLocalStorage;
+    if (globalCtor) {
+        return globalCtor;
     }
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-implied-eval
-        const req = Function("return typeof require !== 'undefined' ? require : undefined")();
-        if (!req) {
-            return undefined;
+    const runtimeRequire = typeof require === "function" ? require : undefined;
+    if (runtimeRequire) {
+        const ctor = resolveFromRequire(runtimeRequire);
+        if (ctor) {
+            return ctor;
         }
-        const mod = req("node:async_hooks");
-        return mod.AsyncLocalStorage;
     }
-    catch {
-        return undefined;
+    const globalRequire = globalThis?.require;
+    if (typeof globalRequire === "function") {
+        return resolveFromRequire(globalRequire);
     }
+    return undefined;
 };
 const AsyncLocalStorageCtor = resolveAsyncLocalStorage();
+export function hasAsyncLocalStorageSupport() {
+    return AsyncLocalStorageCtor !== undefined;
+}
 export class ContextStorage {
     als;
     stack = [];

package/dist/kernel/docstore-gateway.d.ts

@@ -5,15 +5,40 @@ type IndexEntries = Set<{
     ts: bigint;
     update: DatabaseIndexUpdate;
 }>;
-export declare class DocStoreGateway {
-    private readonly docstore;
-    private readonly mutationTransaction?;
-    private context?;
-    constructor(docstore: DocStore, mutationTransaction?: OccMutationTransaction | undefined);
+/**
+ * Polymorphic document access interface.
+ *
+ * Two implementations replace the previous `if (this.mutationTransaction)` branching:
+ * - `SnapshotDocAccess`       — wraps DocStore directly (queries, actions)
+ * - `TransactionalDocAccess`  — wraps OccMutationTransaction + DocStore (mutations)
+ */
+export interface DocAccess {
+    computeSnapshotTimestamp(snapshotOverride: bigint | null | undefined, inheritedSnapshot: bigint | null): bigint;
+    allocateTimestamp(): bigint;
+    fetchLatestDocument(id: InternalDocumentId, snapshotTimestamp: bigint): Promise<LatestDocument | null>;
+    fetchTable(tableId: string, snapshotTimestamp: bigint): Promise<LatestDocument[]>;
+    applyWrites(documents: DocumentLogEntry[], indexes: IndexEntries, conflictStrategy: "Error" | "Overwrite"): Promise<void>;
+    hasTransaction(): boolean;
+    getTransaction(): OccMutationTransaction | undefined;
+    getDocStore(): DocStore;
+    /** Attach the kernel context for read/write tracking (non-transactional path) */
+    attachContext(context: KernelContext): void;
+}
+/**
+ * Factory function that selects the appropriate DocAccess implementation
+ * based on whether a mutation transaction is active.
+ */
+export declare function createDocAccess(docstore: DocStore, transaction?: OccMutationTransaction): DocAccess;
+/**
+ * @deprecated Use `createDocAccess` factory instead.
+ * This class is kept as an alias for backwards compatibility.
+ */
+export declare class DocStoreGateway implements DocAccess {
+    private readonly delegate;
+    constructor(docstore: DocStore, transaction?: OccMutationTransaction);
     attachContext(context: KernelContext): void;
     getTransaction(): OccMutationTransaction | undefined;
     hasTransaction(): boolean;
-    private getTimestampOracle;
     computeSnapshotTimestamp(snapshotOverride: bigint | null | undefined, inheritedSnapshot: bigint | null): bigint;
     allocateTimestamp(): bigint;
     fetchLatestDocument(id: InternalDocumentId, snapshotTimestamp: bigint): Promise<LatestDocument | null>;

package/dist/kernel/docstore-gateway.js

@@ -1,63 +1,137 @@
-export class DocStoreGateway {
+// ---------------------------------------------------------------------------
+// Snapshot (non-transactional) path — queries, actions
+// ---------------------------------------------------------------------------
+class SnapshotDocAccess {
     docstore;
-    mutationTransaction;
     context;
-    constructor(docstore, mutationTransaction) {
+    oracle;
+    constructor(docstore) {
         this.docstore = docstore;
-        this.mutationTransaction = mutationTransaction;
+        this.oracle = docstore.timestampOracle;
     }
     attachContext(context) {
         this.context = context;
     }
-    getTransaction() {
-        return this.mutationTransaction;
-    }
-    hasTransaction() {
-        return !!this.mutationTransaction;
-    }
-    getTimestampOracle() {
-        return this.docstore.timestampOracle;
-    }
     computeSnapshotTimestamp(snapshotOverride, inheritedSnapshot) {
-        if (this.mutationTransaction) {
-            return this.mutationTransaction.getSnapshotTimestamp();
-        }
-        const oracle = this.getTimestampOracle();
-        const docstoreTs = oracle?.getCurrentTimestamp() ?? 0n;
+        const docstoreTs = this.oracle?.getCurrentTimestamp() ?? 0n;
         const wallClockTs = BigInt(Date.now());
         const maxTs = docstoreTs > wallClockTs ? docstoreTs : wallClockTs;
         return snapshotOverride ?? inheritedSnapshot ?? maxTs;
     }
     allocateTimestamp() {
-        const oracle = this.getTimestampOracle();
-        if (oracle) {
-            return oracle.allocateTimestamp();
+        if (this.oracle) {
+            return this.oracle.allocateTimestamp();
         }
         return BigInt(Date.now());
     }
     async fetchLatestDocument(id, snapshotTimestamp) {
-        if (this.mutationTransaction) {
-            return this.mutationTransaction.getLatest(id);
-        }
         return this.docstore.get(id, snapshotTimestamp);
     }
     async fetchTable(tableId, snapshotTimestamp) {
-        if (this.mutationTransaction) {
-            return this.mutationTransaction.scanTable(tableId);
-        }
         return this.docstore.scan(tableId, snapshotTimestamp);
     }
     async applyWrites(documents, indexes, conflictStrategy) {
-        if (this.mutationTransaction) {
-            this.mutationTransaction.stageWrite(documents, indexes, conflictStrategy);
-            return;
-        }
         for (const { update } of indexes) {
             this.context?.recordIndexWrite(update.index_id, update.key);
         }
         await this.docstore.write(documents, indexes, conflictStrategy);
     }
+    hasTransaction() {
+        return false;
+    }
+    getTransaction() {
+        return undefined;
+    }
     getDocStore() {
         return this.docstore;
     }
 }
+// ---------------------------------------------------------------------------
+// Transactional path — mutations
+// ---------------------------------------------------------------------------
+class TransactionalDocAccess {
+    docstore;
+    transaction;
+    oracle;
+    constructor(docstore, transaction) {
+        this.docstore = docstore;
+        this.transaction = transaction;
+        this.oracle = docstore.timestampOracle;
+    }
+    attachContext(_context) {
+        // Transaction path: context read/write tracking is handled by OccMutationTransaction
+    }
+    computeSnapshotTimestamp(_snapshotOverride, _inheritedSnapshot) {
+        return this.transaction.getSnapshotTimestamp();
+    }
+    allocateTimestamp() {
+        if (this.oracle) {
+            return this.oracle.allocateTimestamp();
+        }
+        return BigInt(Date.now());
+    }
+    async fetchLatestDocument(id, _snapshotTimestamp) {
+        return this.transaction.getLatest(id);
+    }
+    async fetchTable(tableId, _snapshotTimestamp) {
+        return this.transaction.scanTable(tableId);
+    }
+    async applyWrites(documents, indexes, conflictStrategy) {
+        this.transaction.stageWrite(documents, indexes, conflictStrategy);
+    }
+    hasTransaction() {
+        return true;
+    }
+    getTransaction() {
+        return this.transaction;
+    }
+    getDocStore() {
+        return this.docstore;
+    }
+}
+/**
+ * Factory function that selects the appropriate DocAccess implementation
+ * based on whether a mutation transaction is active.
+ */
+export function createDocAccess(docstore, transaction) {
+    return transaction
+        ? new TransactionalDocAccess(docstore, transaction)
+        : new SnapshotDocAccess(docstore);
+}
+/**
+ * @deprecated Use `createDocAccess` factory instead.
+ * This class is kept as an alias for backwards compatibility.
+ */
+export class DocStoreGateway {
+    delegate;
+    constructor(docstore, transaction) {
+        this.delegate = createDocAccess(docstore, transaction);
+    }
+    attachContext(context) {
+        this.delegate.attachContext(context);
+    }
+    getTransaction() {
+        return this.delegate.getTransaction();
+    }
+    hasTransaction() {
+        return this.delegate.hasTransaction();
+    }
+    computeSnapshotTimestamp(snapshotOverride, inheritedSnapshot) {
+        return this.delegate.computeSnapshotTimestamp(snapshotOverride, inheritedSnapshot);
+    }
+    allocateTimestamp() {
+        return this.delegate.allocateTimestamp();
+    }
+    async fetchLatestDocument(id, snapshotTimestamp) {
+        return this.delegate.fetchLatestDocument(id, snapshotTimestamp);
+    }
+    async fetchTable(tableId, snapshotTimestamp) {
+        return this.delegate.fetchTable(tableId, snapshotTimestamp);
+    }
+    async applyWrites(documents, indexes, conflictStrategy) {
+        return this.delegate.applyWrites(documents, indexes, conflictStrategy);
+    }
+    getDocStore() {
+        return this.delegate.getDocStore();
+    }
+}

package/dist/kernel/index.d.ts

@@ -7,13 +7,14 @@
  */
 export { UdfKernel } from "./udf-kernel";
 export { KernelContext } from "./kernel-context";
-export { ContextStorage } from "./context-storage";
+export { ContextStorage, hasAsyncLocalStorageSupport } from "./context-storage";
 export { snapshotContext, transactionContext } from "./contexts";
 export { AccessLog } from "./access-log";
 export { BlobStoreGateway } from "./blob-store-gateway";
-export { DocStoreGateway } from "./docstore-gateway";
+export { DocStoreGateway, createDocAccess, type DocAccess } from "./docstore-gateway";
 export { SchedulerGateway } from "./scheduler-gateway";
-export { SchemaService, isMissingSchemaModuleError } from "./schema-service";
+export { SchemaService } from "./schema-service";
+export { isMissingSchemaModuleError } from "./missing-schema-error";
 export type { DbIndexConfig, SearchIndexConfig, VectorIndexConfig } from "./schema-service";
 export { KernelSyscalls, SyscallRouter } from "./syscalls";
 export type { KernelAuthContext, KernelResources, LocalWrite } from "./types";

package/dist/kernel/index.js

@@ -7,12 +7,13 @@
  */
 export { UdfKernel } from "./udf-kernel";
 export { KernelContext } from "./kernel-context";
-export { ContextStorage } from "./context-storage";
+export { ContextStorage, hasAsyncLocalStorageSupport } from "./context-storage";
 export { snapshotContext, transactionContext } from "./contexts";
 export { AccessLog } from "./access-log";
 export { BlobStoreGateway } from "./blob-store-gateway";
-export { DocStoreGateway } from "./docstore-gateway";
+export { DocStoreGateway, createDocAccess } from "./docstore-gateway";
 export { SchedulerGateway } from "./scheduler-gateway";
-export { SchemaService, isMissingSchemaModuleError } from "./schema-service";
+export { SchemaService } from "./schema-service";
+export { isMissingSchemaModuleError } from "./missing-schema-error";
 export { KernelSyscalls, SyscallRouter } from "./syscalls";
 export { UdfInvocationManager } from "./udf-invocation-manager";

package/dist/kernel/kernel-context.js

@@ -1,7 +1,6 @@
 import { serializeKeyRange } from "../queryengine/indexing/read-write-set";
 import { AccessLog } from "./access-log";
-import { stringToHex } from "../utils/utils";
-import { decodeIndexId, indexKeyspaceId } from "../utils/keyspace";
+import { decodeIndexId } from "../utils/keyspace";
 import { parseDeveloperId } from "../queryengine/developer-id";
 import { getGlobalTableRegistry } from "../tables/memory-table-registry";
 /**
@@ -46,7 +45,8 @@ export class KernelContext {
     }
     recordTableRead(tableName) {
         if (this.mutationTransaction) {
-            this.mutationTransaction.recordTableScan(stringToHex(tableName), []);
+            // Transactional reads must be recorded with concrete documents by the
+            // transaction-aware read path (for example scanTable/index query handlers).
             return;
         }
         this.readLog.addTableScan(tableName);
@@ -59,8 +59,8 @@ export class KernelContext {
     }
     recordIndexRange(tableName, indexDescriptor, startKey, endKey) {
         if (this.mutationTransaction) {
-            const indexId = indexKeyspaceId(tableName, indexDescriptor);
-            this.mutationTransaction.recordIndexRangeScan(indexId, startKey, endKey, []);
+            // Transactional reads must be recorded with concrete documents by the
+            // transaction-aware query runtime path.
             return;
         }
         this.readLog.addIndexRange(tableName, indexDescriptor, startKey, endKey);

package/dist/kernel/missing-schema-error.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Check whether an error indicates a missing convex/schema module.
+ * Schema is optional in Convex, so this is a normal condition — not an error.
+ */
+export declare function isMissingSchemaModuleError(error: unknown): boolean;

package/dist/kernel/missing-schema-error.js

@@ -0,0 +1,25 @@
+/**
+ * Check whether an error indicates a missing convex/schema module.
+ * Schema is optional in Convex, so this is a normal condition — not an error.
+ */
+export function isMissingSchemaModuleError(error) {
+    if (!error)
+        return false;
+    // Convert error to string and check for known messages
+    const errorString = String(error);
+    const isMissing = errorString.includes('Unable to resolve module "schema"') ||
+        errorString.includes("Module not found: schema") ||
+        errorString.includes('Unable to resolve module "convex/schema"');
+    if (isMissing)
+        return true;
+    // Recursively check causes if present (common in ModuleRegistry errors)
+    const causes = error.causes;
+    if (Array.isArray(causes)) {
+        return causes.some(isMissingSchemaModuleError);
+    }
+    const cause = error.cause;
+    if (cause) {
+        return isMissingSchemaModuleError(cause);
+    }
+    return false;
+}