@lunora/runtime 1.0.0-alpha.22 → 1.0.0-alpha.24

package/dist/index.d.mts

@@ -1643,6 +1643,19 @@ interface FunctionRegistryEntry {
   */
   kind: "action" | "mutation" | "query" | "stream";
   visibility?: "internal" | "public";
+  /**
+  * x402 payment tag set by the `.x402({ price })` builder modifier. Present
+  * only on paid public procedures; the origin worker answers an unpaid RPC
+  * for such a function with a real `402` challenge (via the injected
+  * {@link WorkerOptions.x402Charge} gate) before dispatching, then verifies +
+  * settles at the origin boundary so the shard never sees payment state.
+  * Rides along on the registered function object's identity — codegen casts
+  * the real `fn` into `LUNORA_FUNCTIONS`, so reading it needs no change to the
+  * generated shape (same as `fn.rls`).
+  */
+  x402?: {
+    readonly price: number | string;
+  };
 }
 /**
 * The generated `LUNORA_FUNCTIONS` dispatch table, narrowed to what the
@@ -1650,6 +1663,25 @@ interface FunctionRegistryEntry {
 */
 type FunctionRegistryLike = Record<string, FunctionRegistryEntry>;
 /**
+* Injected x402 charge gate — the seam that paywalls a `.x402({ price })`-tagged
+* procedure at the origin worker without the runtime importing `@lunora/x402`
+* (which would pull viem/solana into every worker bundle). Build it with
+* `createProcedureChargeGate(config)` from `@lunora/x402/charge` and pass it as
+* {@link WorkerOptions.x402Charge}.
+*
+* Given the inbound `request`, the paid procedure's `spec` (its `functionPath` —
+* used as the x402 challenge `resource` — and USD `price`), and a `dispatch`
+* that runs the real shard forward, it returns a real `402` + `PAYMENT-REQUIRED`
+* challenge when the request is unpaid, or the dispatched response (with
+* `X-PAYMENT-RESPONSE` attached) once the client's `X-PAYMENT` is verified and
+* settled. `dispatch` runs only after payment is verified — an unpaid or
+* invalid request never reaches the shard.
+*/
+type X402ChargeGate = (request: Request, spec: {
+  functionPath: string;
+  price: number | string;
+}, dispatch: () => Promise<Response>) => Promise<Response>;
+/**
 * Lists objects in the storage bucket for the admin file browser. Structurally
 * compatible with `@lunora/storage`'s `Storage["list"]` — the runtime stays free
 * of a hard dependency on the storage package.
@@ -2313,6 +2345,18 @@ interface WorkerOptions {
   * reports "not configured" and the studio shows the credentials empty state.
   */
   workflowsClient?: (env: unknown) => undefined | WorkflowsRestClient;
+  /**
+  * Injected x402 charge gate for paid (`.x402({ price })`) procedures. Build
+  * it with `createProcedureChargeGate(config)` from `@lunora/x402/charge` and
+  * pass it here; the runtime stays free of a hard `@lunora/x402` dependency
+  * (and its viem/solana deps).
+  *
+  * **Required whenever any registered function is `.x402()`-tagged.** The
+  * origin worker refuses to dispatch a paid procedure with a config error
+  * (`500`) when this is absent, rather than serving it free — the paywall is
+  * fail-closed by construction. See {@link X402ChargeGate}.
+  */
+  x402Charge?: X402ChargeGate;
 }
 interface RpcContext {
   ctx: ExecutionContextLike;
@@ -2321,6 +2365,12 @@ interface RpcContext {
   shardKey: string;
 }
 /**
+* Ask the owner how many relays to spread new connections across for `shardKey`
+* (plan 075 Phase 2), cached per isolate so a promoted shard doesn't add a
+* round-trip to every WS upgrade. Fails closed to `0` (owner-served) on any error,
+* so a relay-probe hiccup can never break a connection.
+*/
+/**
 * The composed Lunora worker. `fetch` / `scheduled` are the standard Cloudflare
 * module-worker entrypoints (so the object can be re-exported directly as
 * `export default createWorker(...)`). `serverQuery` is the in-process fast-path

package/dist/index.d.ts

@@ -1643,6 +1643,19 @@ interface FunctionRegistryEntry {
   */
   kind: "action" | "mutation" | "query" | "stream";
   visibility?: "internal" | "public";
+  /**
+  * x402 payment tag set by the `.x402({ price })` builder modifier. Present
+  * only on paid public procedures; the origin worker answers an unpaid RPC
+  * for such a function with a real `402` challenge (via the injected
+  * {@link WorkerOptions.x402Charge} gate) before dispatching, then verifies +
+  * settles at the origin boundary so the shard never sees payment state.
+  * Rides along on the registered function object's identity — codegen casts
+  * the real `fn` into `LUNORA_FUNCTIONS`, so reading it needs no change to the
+  * generated shape (same as `fn.rls`).
+  */
+  x402?: {
+    readonly price: number | string;
+  };
 }
 /**
 * The generated `LUNORA_FUNCTIONS` dispatch table, narrowed to what the
@@ -1650,6 +1663,25 @@ interface FunctionRegistryEntry {
 */
 type FunctionRegistryLike = Record<string, FunctionRegistryEntry>;
 /**
+* Injected x402 charge gate — the seam that paywalls a `.x402({ price })`-tagged
+* procedure at the origin worker without the runtime importing `@lunora/x402`
+* (which would pull viem/solana into every worker bundle). Build it with
+* `createProcedureChargeGate(config)` from `@lunora/x402/charge` and pass it as
+* {@link WorkerOptions.x402Charge}.
+*
+* Given the inbound `request`, the paid procedure's `spec` (its `functionPath` —
+* used as the x402 challenge `resource` — and USD `price`), and a `dispatch`
+* that runs the real shard forward, it returns a real `402` + `PAYMENT-REQUIRED`
+* challenge when the request is unpaid, or the dispatched response (with
+* `X-PAYMENT-RESPONSE` attached) once the client's `X-PAYMENT` is verified and
+* settled. `dispatch` runs only after payment is verified — an unpaid or
+* invalid request never reaches the shard.
+*/
+type X402ChargeGate = (request: Request, spec: {
+  functionPath: string;
+  price: number | string;
+}, dispatch: () => Promise<Response>) => Promise<Response>;
+/**
 * Lists objects in the storage bucket for the admin file browser. Structurally
 * compatible with `@lunora/storage`'s `Storage["list"]` — the runtime stays free
 * of a hard dependency on the storage package.
@@ -2313,6 +2345,18 @@ interface WorkerOptions {
   * reports "not configured" and the studio shows the credentials empty state.
   */
   workflowsClient?: (env: unknown) => undefined | WorkflowsRestClient;
+  /**
+  * Injected x402 charge gate for paid (`.x402({ price })`) procedures. Build
+  * it with `createProcedureChargeGate(config)` from `@lunora/x402/charge` and
+  * pass it here; the runtime stays free of a hard `@lunora/x402` dependency
+  * (and its viem/solana deps).
+  *
+  * **Required whenever any registered function is `.x402()`-tagged.** The
+  * origin worker refuses to dispatch a paid procedure with a config error
+  * (`500`) when this is absent, rather than serving it free — the paywall is
+  * fail-closed by construction. See {@link X402ChargeGate}.
+  */
+  x402Charge?: X402ChargeGate;
 }
 interface RpcContext {
   ctx: ExecutionContextLike;
@@ -2321,6 +2365,12 @@ interface RpcContext {
   shardKey: string;
 }
 /**
+* Ask the owner how many relays to spread new connections across for `shardKey`
+* (plan 075 Phase 2), cached per isolate so a promoted shard doesn't add a
+* round-trip to every WS upgrade. Fails closed to `0` (owner-served) on any error,
+* so a relay-probe hiccup can never break a connection.
+*/
+/**
 * The composed Lunora worker. `fetch` / `scheduled` are the standard Cloudflare
 * module-worker entrypoints (so the object can be re-exported directly as
 * `export default createWorker(...)`). `serverQuery` is the in-process fast-path

package/dist/index.mjs

@@ -1,5 +1,5 @@
 export { toAirbyteMessages, toFivetranResponse } from './packem_shared/toAirbyteMessages-DrHdplb4.mjs';
-export { composeWorker, createLunoraHandler, createWorker, defineRpcEnvelope, resolveLunoraOptions, withFrameworkWorker } from './packem_shared/composeWorker-Dpw9d1s5.mjs';
+export { composeWorker, createLunoraHandler, createWorker, defineRpcEnvelope, resolveLunoraOptions, withFrameworkWorker } from './packem_shared/composeWorker-CxwkPZUl.mjs';
 export { createCrossShardRelationCapabilities } from './packem_shared/createCrossShardRelationCapabilities-CbcWjkAn.mjs';
 export { DEFAULT_REGISTRY_CACHE_TTL_MS, SHARD_REGISTRY_DO_NAME, createDynamicShardRegistry } from './packem_shared/DEFAULT_REGISTRY_CACHE_TTL_MS-B3pA7aXp.mjs';
 export { LunoraError, toErrorResponse } from './packem_shared/LunoraError-Bpb9EFJ3.mjs';
@@ -7,7 +7,7 @@ export { emitLogEvent, emitRpcEvent } from './packem_shared/emitLogEvent-pEdtqAK
 export { analyticsEngineSink, combineSinks, consoleSink, sentrySink, webhookSink } from './packem_shared/analyticsEngineSink-DqEvrQs0.mjs';
 export { createQueryCoordinator, createStaticShardRegistry, mergeStrategyForAggregate } from './packem_shared/createQueryCoordinator-DNCJzOZE.mjs';
 export { applyJurisdiction, resolveShard } from './packem_shared/applyJurisdiction-BkZtTkct.mjs';
-export { decorateResponse, enforceOrigin, handleCorsPreflight, resolveSecurity } from './packem_shared/decorateResponse-CsZc49QC.mjs';
+export { decorateResponse, enforceOrigin, handleCorsPreflight, resolveSecurity } from './packem_shared/decorateResponse-DRWQFNhF.mjs';
 export { NOOP_EXECUTION_CONTEXT } from './packem_shared/NOOP_EXECUTION_CONTEXT-CCTu0Bf1.mjs';
 export { composeIdentityResolvers, routeIdentityResolvers } from './packem_shared/composeIdentityResolvers-XGjO7V1J.mjs';
 

package/dist/packem_shared/{composeWorker-Dpw9d1s5.mjs → composeWorker-CxwkPZUl.mjs}

@@ -5,7 +5,17 @@ import { wrapResolverWithContract } from './composeIdentityResolvers-XGjO7V1J.mj
 export { composeIdentityResolvers, routeIdentityResolvers } from './composeIdentityResolvers-XGjO7V1J.mjs';
 import { emitRpcEvent } from './emitLogEvent-pEdtqAK8.mjs';
 import { resolveShard, applyJurisdiction } from './applyJurisdiction-BkZtTkct.mjs';
-import { resolveSecurity, handleCorsPreflight, enforceOrigin, decorateResponse, enforceWebSocketOrigin } from './decorateResponse-CsZc49QC.mjs';
+import { resolveSecurity, handleCorsPreflight, enforceOrigin, decorateResponse, enforceWebSocketOrigin } from './decorateResponse-DRWQFNhF.mjs';
+
+const evictOldestEntry = (map, capacity) => {
+  if (map.size < capacity) {
+    return;
+  }
+  const oldest = map.keys().next().value;
+  if (oldest !== void 0) {
+    map.delete(oldest);
+  }
+};
 
 const RELAY_NAME_INFIX = "::relay::";
 const relayName = (ownerKey, index) => `${ownerKey}${RELAY_NAME_INFIX}${String(index)}`;
@@ -477,6 +487,9 @@ const normalizeBatchCall = (raw, index, defaultShard) => {
   if (call.functionPath.startsWith("__lunora_relation__:") || call.functionPath.startsWith("__lunora_admin__")) {
     throw new LunoraError("reserved function path cannot be batched", { code: "FORBIDDEN", status: 403 });
   }
+  if (call.args !== void 0 && (typeof call.args !== "object" || call.args === null || Array.isArray(call.args))) {
+    throw new LunoraError("each batch call `args` must be an object", { code: "BAD_REQUEST", status: 400 });
+  }
   return {
     entry: {
       args: call.args === void 0 ? {} : call.args,
@@ -2028,6 +2041,22 @@ const logRpcDebug = (env, envelope) => {
   }
   console.warn(`[lunora:rpc] ${envelope.fanOut ? "fan-out" : `shard=${envelope.shardKey ?? "(root)"}`} ${envelope.functionPath}`);
 };
+const resolveX402Charge = (envelope, options) => {
+  const x402Tag = options.functions?.[envelope.functionPath]?.x402;
+  if (!x402Tag) {
+    return void 0;
+  }
+  if (envelope.fanOut) {
+    throw new LunoraError("a paid (`.x402`) function cannot be fanned out", { code: "BAD_REQUEST", status: 400 });
+  }
+  if (!options.x402Charge) {
+    throw new LunoraError(`function "${envelope.functionPath}" is marked paid (.x402) but no x402Charge gate is configured on the worker`, {
+      code: "MISCONFIGURED",
+      status: 500
+    });
+  }
+  return x402Tag;
+};
 const parseEnvelope = async (request) => {
   const text = await readBodyTextWithLimit(request);
   let body;
@@ -2069,12 +2098,16 @@ const forwardToShard = async (namespace, shardKey, request) => {
 };
 const relayProbeCache = /* @__PURE__ */ new Map();
 const RELAY_PROBE_TTL_MS = 5e3;
+const RELAY_PROBE_MAX_ENTRIES = 4096;
 const probeRelayCount = async (namespace, shardKey) => {
   const now = Date.now();
   const cached = relayProbeCache.get(shardKey);
   if (cached !== void 0 && cached.expiresMs > now) {
     return cached.relayCount;
   }
+  if (cached !== void 0) {
+    relayProbeCache.delete(shardKey);
+  }
   let relayCount = 0;
   try {
     const response = await resolveShard(namespace, shardKey).fetch(new Request("https://shard.internal/_lunora/route"));
@@ -2088,6 +2121,7 @@ const probeRelayCount = async (namespace, shardKey) => {
   } catch {
     relayCount = 0;
   }
+  evictOldestEntry(relayProbeCache, RELAY_PROBE_MAX_ENTRIES);
   relayProbeCache.set(shardKey, { expiresMs: now + RELAY_PROBE_TTL_MS, relayCount });
   return relayCount;
 };
@@ -2499,9 +2533,12 @@ const createWorker = (options) => {
       guardUnauthenticatedShardAccess("shard");
     }
     const upgradeHeaders = new Headers(request.headers);
-    upgradeHeaders.delete("x-lunora-userid");
-    upgradeHeaders.delete("x-lunora-identity");
-    upgradeHeaders.delete("x-lunora-identity-exp");
+    const clientHeaderNames = [...upgradeHeaders.keys()];
+    for (const name of clientHeaderNames) {
+      if (name.startsWith("x-lunora-")) {
+        upgradeHeaders.delete(name);
+      }
+    }
     const forwardedUserId = forwardedHeaders["x-lunora-userid"];
     const forwardedIdentity = forwardedHeaders["x-lunora-identity"];
     const forwardedExp = forwardedHeaders["x-lunora-identity-exp"];
@@ -2586,12 +2623,6 @@ const createWorker = (options) => {
         },
         sinkContext
       );
-      const responseBookmark = response.headers.get("x-d1-bookmark");
-      if (responseBookmark) {
-        const headers = new Headers(response.headers);
-        headers.set("x-d1-bookmark", responseBookmark);
-        return new Response(response.body, { headers, status: response.status });
-      }
       return response;
     } catch (error) {
       emitRpcEvent(observability, buildErrorEvent(functionPath, Date.now() - rpcStartedAt, error, { shardKey }), sinkContext);
@@ -2621,6 +2652,7 @@ const createWorker = (options) => {
     }
     const { headers: forwardedHeaders, identity } = await resolveForwardContext(request, env, publicResolveIdentity);
     await authorizeRpcEnvelope(envelope, identity);
+    const x402Tag = resolveX402Charge(envelope, options);
     {
       const rpcStartedAt = Date.now();
       const { observability } = options;
@@ -2672,7 +2704,11 @@ const createWorker = (options) => {
         }
       }
       const shardKey = envelope.shardKey ?? defaultShard;
-      return dispatchSingleShard(envelope.functionPath, envelope.args ?? {}, shardKey, forwardedHeaders, sinkContext);
+      const dispatch = () => dispatchSingleShard(envelope.functionPath, envelope.args ?? {}, shardKey, forwardedHeaders, sinkContext);
+      if (x402Tag && options.x402Charge) {
+        return options.x402Charge(request, { functionPath: envelope.functionPath, price: x402Tag.price }, dispatch);
+      }
+      return dispatch();
     }
   };
   const handleBatchRpc = async (request, env, context) => {
@@ -2693,8 +2729,21 @@ const createWorker = (options) => {
     if (!Array.isArray(calls)) {
       throw new LunoraError("RPC batch `calls` must be an array", { code: "BAD_REQUEST", status: 400 });
     }
-    const { headers: forwardedHeaders, identity } = await resolveForwardContext(request, env, options.resolveIdentity);
+    const { headers: forwardedHeaders, identity } = await resolveForwardContext(request, env, publicResolveIdentity);
     const groups = groupBatchCallsByShard(calls, defaultShard);
+    for (const entries of groups.values()) {
+      for (const entry of entries) {
+        if (options.functions?.[entry.functionPath]?.x402) {
+          throw new LunoraError(
+            `paid (\`.x402\`) function "${entry.functionPath}" cannot be called in a batch; dispatch it individually over ${RPC_PATH}`,
+            {
+              code: "BAD_REQUEST",
+              status: 400
+            }
+          );
+        }
+      }
+    }
     await Promise.all(
       [...groups.entries()].flatMap(
         ([shardKey, entries]) => entries.map((entry) => authorizeRpcEnvelope({ functionPath: entry.functionPath, shardKey }, identity))
@@ -2707,7 +2756,7 @@ const createWorker = (options) => {
       }
     } : void 0;
     const results = [];
-    let latestBookmark;
+    const bookmarks = [];
     const slotError = (entry, status, code, message) => {
       return { body: { error: { code, message } }, id: entry.id, status };
     };
@@ -2758,7 +2807,7 @@ const createWorker = (options) => {
         const durationMs = Date.now() - subStartedAt;
         const bookmark = response.headers.get("x-d1-bookmark");
         if (bookmark) {
-          latestBookmark = bookmark;
+          bookmarks.push(bookmark);
         }
         let parsed;
         try {
@@ -2789,8 +2838,9 @@ const createWorker = (options) => {
       })
     );
     const responseHeaders = { "content-type": "application/json" };
-    if (latestBookmark !== void 0) {
-      responseHeaders["x-d1-bookmark"] = latestBookmark;
+    const [onlyBookmark] = bookmarks;
+    if (bookmarks.length === 1 && onlyBookmark !== void 0) {
+      responseHeaders["x-d1-bookmark"] = onlyBookmark;
     }
     return Response.json({ results }, { headers: responseHeaders, status: 200 });
   };
@@ -2845,13 +2895,14 @@ const createWorker = (options) => {
     if (!coordinator) {
       throw new LunoraError("scheduled backup requires a `queryCoordinator` on the worker", { code: "BACKUP_NOT_CONFIGURED", status: 500 });
     }
-    if (!options.adminToken || options.adminToken.length === 0) {
-      throw new LunoraError("scheduled backup requires an `adminToken` to authenticate the per-shard export gate", {
+    const adminToken = effectiveAdminToken();
+    if (!adminToken || adminToken.length === 0) {
+      throw new LunoraError("scheduled backup requires an `adminToken` (or `env.LUNORA_ADMIN_TOKEN`) to authenticate the per-shard export gate", {
         code: "BACKUP_NOT_CONFIGURED",
         status: 500
       });
     }
-    const forwardedHeaders = { authorization: `Bearer ${options.adminToken}`, "content-type": "application/json" };
+    const forwardedHeaders = { authorization: `Bearer ${adminToken}`, "content-type": "application/json" };
     const tables = options.backupTables;
     let rows = 0;
     let bytes = 0;
@@ -2897,6 +2948,7 @@ const createWorker = (options) => {
     await pruneBackups(store, prefix);
   };
   const handleScheduled = async (controller, env, context) => {
+    resolveAdminTokenFromEnv(env);
     const errors = [];
     const toError = (error) => error instanceof Error ? error : new Error(String(error));
     const userHandler = options.crons?.[controller.cron];
@@ -3013,7 +3065,8 @@ const createWorker = (options) => {
     const url = new URL(request.url);
     if (request.method === "POST" || request.method === "PUT") {
       const contentLength = Number(request.headers.get("content-length") ?? "");
-      if (Number.isFinite(contentLength) && contentLength > MAX_BODY_BYTES) {
+      const maxBodyBytes = url.pathname === KV_VALUE_PATH ? KV_VALUE_MAX_BODY_BYTES : MAX_BODY_BYTES;
+      if (Number.isFinite(contentLength) && contentLength > maxBodyBytes) {
         throw new LunoraError("Body too large", { code: "PAYLOAD_TOO_LARGE", status: 413 });
       }
     }
@@ -3114,4 +3167,4 @@ const resolveLunoraOptions = (options, env) => {
 const createLunoraHandler = (options = {}) => (request, env, context) => createWorker(resolveLunoraOptions(options, env)).fetch(request, env, context ?? NOOP_EXECUTION_CONTEXT);
 const defineRpcEnvelope = (envelope) => envelope;
 
-export { NOOP_EXECUTION_CONTEXT, composeWorker, createLunoraHandler, createWorker, defineRpcEnvelope, resolveLunoraOptions, withFrameworkWorker };
+export { NOOP_EXECUTION_CONTEXT, composeWorker, createLunoraHandler, createWorker, defineRpcEnvelope, probeRelayCount, resolveLunoraOptions, withFrameworkWorker };

package/dist/packem_shared/{decorateResponse-CsZc49QC.mjs → decorateResponse-DRWQFNhF.mjs}

@@ -202,7 +202,14 @@ const handleCorsPreflight = (request, resolved) => {
   const headers = corsResponseHeaders(origin, resolved.cors);
   const requested = request.headers.get("access-control-request-headers");
   headers.set("access-control-allow-methods", resolved.cors.allowedMethods.join(", "));
-  headers.set("access-control-allow-headers", requested ?? resolved.cors.allowedHeaders.join(", "));
+  let allowedHeaders;
+  if (requested === null) {
+    allowedHeaders = resolved.cors.allowedHeaders.join(", ");
+  } else {
+    const permitted = new Set(resolved.cors.allowedHeaders.map((name) => name.toLowerCase()));
+    allowedHeaders = requested.split(",").map((name) => name.trim()).filter((name) => name.length > 0 && permitted.has(name.toLowerCase())).join(", ");
+  }
+  headers.set("access-control-allow-headers", allowedHeaders);
   headers.set("access-control-max-age", String(resolved.cors.maxAge));
   return new Response(null, { headers, status: 204 });
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/runtime",
-  "version": "1.0.0-alpha.22",
+  "version": "1.0.0-alpha.24",
   "description": "Lunora Worker runtime: the RPC router, shard resolver, and query coordinator",
   "keywords": [
     "cloudflare",
@@ -46,7 +46,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/errors": "1.0.0-alpha.3"
+    "@lunora/errors": "1.0.0-alpha.4"
   },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"