@concavejs/core 0.0.1-alpha.6 → 0.0.1-alpha.8

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/auth/jwt.d.ts

@@ -36,6 +36,11 @@ export type JWTValidationConfig = {
     secret?: string;
     skipVerification?: boolean;
     clockTolerance?: number;
+    /**
+     * Optional TTL (in milliseconds) for cached remote JWKS resolvers.
+     * Defaults to 5 minutes when omitted.
+     */
+    jwksCacheTtlMs?: number;
 };
 export type JWTValidationErrorCode = "MISSING_CONFIG" | "INVALID_SIGNATURE" | "TOKEN_EXPIRED" | "TOKEN_NOT_ACTIVE" | "CLAIM_VALIDATION_FAILED" | "MISSING_SUBJECT" | "MISSING_ISSUER" | "INVALID_TOKEN";
 export declare class JWTValidationError extends Error {

package/dist/auth/jwt.js

@@ -123,12 +123,17 @@ export const WELL_KNOWN_JWKS_URLS = {
     firebase: () => "https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com",
 };
 const DEFAULT_CLOCK_TOLERANCE_SECONDS = 60;
+const DEFAULT_JWKS_CACHE_TTL_MS = 5 * 60 * 1000;
+const MAX_JWKS_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
 const JWKS_CACHE = new Map();
 let defaultValidationConfig;
 let adminAuthConfig;
 let systemAuthConfig;
 export function setJwtValidationConfig(config) {
     defaultValidationConfig = config;
+    // Config updates can change issuer/audience/JWKS source semantics.
+    // Clearing resolver cache avoids stale long-lived entries across reconfiguration.
+    JWKS_CACHE.clear();
 }
 export function getJwtValidationConfig() {
     return defaultValidationConfig;
@@ -268,7 +273,15 @@ export function resolveJwtValidationConfigFromEnv(env) {
         parseBoolean(getEnvValue("CONCAVE_JWT_SKIP_VERIFICATION", env));
     const clockTolerance = parseNumber(getEnvValue("AUTH_CLOCK_TOLERANCE", env)) ??
         parseNumber(getEnvValue("CONCAVE_JWT_CLOCK_TOLERANCE", env));
-    if (!jwksUrl && !issuer && !audience && !secret && skipVerification === undefined && clockTolerance === undefined) {
+    const jwksCacheTtlMs = parseNumber(getEnvValue("AUTH_JWKS_CACHE_TTL_MS", env)) ??
+        parseNumber(getEnvValue("CONCAVE_JWT_JWKS_CACHE_TTL_MS", env));
+    if (!jwksUrl &&
+        !issuer &&
+        !audience &&
+        !secret &&
+        skipVerification === undefined &&
+        clockTolerance === undefined &&
+        jwksCacheTtlMs === undefined) {
         return undefined;
     }
     return {
@@ -278,6 +291,7 @@ export function resolveJwtValidationConfigFromEnv(env) {
         secret,
         skipVerification,
         clockTolerance,
+        jwksCacheTtlMs,
     };
 }
 function normalizeList(value) {
@@ -324,15 +338,33 @@ function validateClaims(claims, config) {
         throw new JWTValidationError("CLAIM_VALIDATION_FAILED", "JWT claim validation failed: aud");
     }
 }
-function getRemoteJwks(jwksUrl) {
+function getRemoteJwks(jwksUrl, config) {
+    const now = Date.now();
     const cached = JWKS_CACHE.get(jwksUrl);
+    if (cached && cached.expiresAtMs > now) {
+        return cached.resolver;
+    }
     if (cached) {
-        return cached;
+        JWKS_CACHE.delete(jwksUrl);
     }
     const jwks = createRemoteJWKSet(new URL(jwksUrl));
-    JWKS_CACHE.set(jwksUrl, jwks);
+    const configuredTtl = config?.jwksCacheTtlMs ?? defaultValidationConfig?.jwksCacheTtlMs;
+    const ttlMs = resolveJwksCacheTtlMs(configuredTtl);
+    JWKS_CACHE.set(jwksUrl, {
+        resolver: jwks,
+        expiresAtMs: now + ttlMs,
+    });
     return jwks;
 }
+function resolveJwksCacheTtlMs(configuredTtl) {
+    if (configuredTtl === undefined) {
+        return DEFAULT_JWKS_CACHE_TTL_MS;
+    }
+    if (!Number.isFinite(configuredTtl)) {
+        return DEFAULT_JWKS_CACHE_TTL_MS;
+    }
+    return Math.max(0, Math.min(MAX_JWKS_CACHE_TTL_MS, Math.floor(configuredTtl)));
+}
 export function decodeJwtUnsafe(token) {
     if (!token)
         return null;
@@ -366,7 +398,7 @@ export async function verifyJwt(token, config) {
             ({ payload } = await jwtVerify(token, key, options));
         }
         else {
-            ({ payload } = await jwtVerify(token, getRemoteJwks(effectiveConfig.jwksUrl), options));
+            ({ payload } = await jwtVerify(token, getRemoteJwks(effectiveConfig.jwksUrl, effectiveConfig), options));
         }
         const claims = payload;
         validateClaims(claims, effectiveConfig);

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/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/api-router.d.ts

@@ -7,6 +7,7 @@ export interface FunctionExecutionParams {
     args: Record<string, any>;
     auth?: AuthContext | UserIdentityAttributes;
     componentPath?: string;
+    snapshotTimestamp?: bigint;
     request: Request;
 }
 export interface FunctionExecutionResult {
@@ -36,6 +37,7 @@ export interface CoreHttpApiOptions {
     notifyWrites?: (writtenRanges?: SerializedKeyRange[], writtenTables?: string[], commitTimestamp?: bigint) => Promise<void> | void;
     storage?: StorageAdapter;
     corsHeaders?: Record<string, string>;
+    getSnapshotTimestamp?: (request: Request) => Promise<bigint> | bigint;
 }
 export interface CoreHttpApiResult {
     handled: boolean;

package/dist/http/api-router.js

@@ -81,6 +81,40 @@ export async function resolveAuthContext(bodyAuth, headerToken, headerIdentity)
     }
     return bodyAuth;
 }
+function parseTimestampInput(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value === "bigint") {
+        return value >= 0n ? value : undefined;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+            return undefined;
+        }
+        return BigInt(value);
+    }
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (!/^\d+$/.test(trimmed)) {
+            return undefined;
+        }
+        try {
+            return BigInt(trimmed);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+async function resolveSnapshotTimestamp(options, request) {
+    const fromCallback = options.getSnapshotTimestamp ? await options.getSnapshotTimestamp(request) : undefined;
+    if (typeof fromCallback === "bigint") {
+        return fromCallback;
+    }
+    return BigInt(Date.now());
+}
 export async function handleCoreHttpApiRequest(request, options) {
     const url = new URL(request.url);
     const segments = url.pathname.split("/").filter(Boolean);
@@ -124,6 +158,19 @@ export async function handleCoreHttpApiRequest(request, options) {
         throw error;
     }
     const route = routeSegments[0];
+    if (route === "query_ts") {
+        if (request.method !== "POST") {
+            return {
+                handled: true,
+                response: apply(Response.json({ error: "Method not allowed" }, { status: 405 })),
+            };
+        }
+        const snapshotTimestamp = await resolveSnapshotTimestamp(options, request);
+        return {
+            handled: true,
+            response: apply(Response.json({ ts: snapshotTimestamp.toString() })),
+        };
+    }
     if (route === "storage") {
         if (!options.storage) {
             return {
@@ -183,7 +230,7 @@ export async function handleCoreHttpApiRequest(request, options) {
             }
         }
     }
-    if (route === "query" || route === "mutation" || route === "action") {
+    if (route === "query" || route === "mutation" || route === "action" || route === "query_at_ts") {
         if (request.method !== "POST") {
             return {
                 handled: true,
@@ -207,7 +254,7 @@ export async function handleCoreHttpApiRequest(request, options) {
                     response: apply(Response.json({ error: "Invalid request body" }, { status: 400 })),
                 };
             }
-            const { path, args, format, auth: bodyAuth, componentPath } = body;
+            const { path, args, format, auth: bodyAuth, componentPath, ts } = body;
             if (!path || typeof path !== "string") {
                 return {
                     handled: true,
@@ -236,6 +283,14 @@ export async function handleCoreHttpApiRequest(request, options) {
                 };
             }
             const jsonArgs = rawArgs ?? {};
+            const executionType = route === "query_at_ts" ? "query" : route;
+            const snapshotTimestamp = route === "query_at_ts" ? parseTimestampInput(ts) : undefined;
+            if (route === "query_at_ts" && snapshotTimestamp === undefined) {
+                return {
+                    handled: true,
+                    response: apply(Response.json({ error: "Invalid or missing ts" }, { status: 400 })),
+                };
+            }
             let authForExecution;
             try {
                 authForExecution = await resolveAuthContext(bodyAuth, headerToken, headerIdentity);
@@ -252,11 +307,12 @@ export async function handleCoreHttpApiRequest(request, options) {
                 throw error;
             }
             const executionParams = {
-                type: route,
+                type: executionType,
                 path,
                 args: jsonArgs,
                 auth: authForExecution,
                 componentPath,
+                snapshotTimestamp,
                 request,
             };
             try {
@@ -273,7 +329,7 @@ export async function handleCoreHttpApiRequest(request, options) {
             }
             const result = await options.executeFunction(executionParams);
             if (options.notifyWrites &&
-                (route === "mutation" || route === "action") &&
+                (executionType === "mutation" || executionType === "action") &&
                 (result.writtenRanges?.length || result.writtenTables?.length)) {
                 await options.notifyWrites(result.writtenRanges, result.writtenTables ?? writtenTablesFromRanges(result.writtenRanges));
             }

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+)?(?=\/|$)/;
@@ -20,6 +20,8 @@ function isReservedApiPath(pathname) {
         normalizedPath === "/api/sync" ||
         normalizedPath === "/api/reset-test-state" ||
         normalizedPath === "/api/query" ||
+        normalizedPath === "/api/query_ts" ||
+        normalizedPath === "/api/query_at_ts" ||
         normalizedPath === "/api/mutation" ||
         normalizedPath === "/api/action") {
         return true;
@@ -108,12 +110,12 @@ export class HttpHandler {
             }
         };
         const coreResult = await handleCoreHttpApiRequest(request, {
-            executeFunction: async ({ type, path, args, auth, componentPath }) => this.adapter.executeUdf(path, args, type, auth, componentPath),
+            executeFunction: async ({ type, path, args, auth, componentPath, snapshotTimestamp }) => this.adapter.executeUdf(path, args, type, auth, componentPath, undefined, snapshotTimestamp),
             notifyWrites,
             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 {
@@ -123,13 +125,26 @@ 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 };
                     },
                 }
                 : undefined,
             corsHeaders,
+            getSnapshotTimestamp: () => {
+                const oracle = this.docstore?.timestampOracle;
+                const oracleTimestamp = typeof oracle?.beginSnapshot === "function"
+                    ? oracle.beginSnapshot()
+                    : typeof oracle?.getCurrentTimestamp === "function"
+                        ? oracle.getCurrentTimestamp()
+                        : undefined;
+                const wallClock = BigInt(Date.now());
+                if (typeof oracleTimestamp === "bigint" && oracleTimestamp > wallClock) {
+                    return oracleTimestamp;
+                }
+                return wallClock;
+            },
         });
         if (coreResult?.handled) {
             return coreResult.response;

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/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>;