@lunora/server 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/rls/testing.d.ts

@@ -1,4 +1,4 @@
-import { P as PolicyOperation, R as Role, a as Policy } from "../packem_shared/types.d-BDY0FYHK.js";
+import { P as PolicyOperation, R as Role, a as Policy } from "../packem_shared/types.d-Cxl6ndhm.js";
 import "../data-model.js";
 /**
 * The slice of a request identity a policy reads. Mirrors the

package/dist/rls/testing.mjs

@@ -1,4 +1,4 @@
-import { indexRolePermissions, computeReadBaseWhere, matchesWhere, evaluateWrite, permissionName } from '../packem_shared/rls-BDKRbMCA.mjs';
+import { indexRolePermissions, computeReadBaseWhere, matchesWhere, evaluateWrite, permissionName } from '../packem_shared/rls-B_ZWgslr.mjs';
 
 const expectPolicy = (policies, options = {}) => {
   const rolePermissions = indexRolePermissions(options.roles);

package/dist/types.d.mts

@@ -5,6 +5,14 @@ type ArgsValidator = ValidatorMap;
 type InferArgs<A extends ArgsValidator> = InferValidatorMap<A>;
 /** Storage backend for a `.global()` table: D1 (default) or a Postgres/MySQL database via Cloudflare Hyperdrive (PlanetScale, Neon, …). */
 type GlobalBackend = "d1" | "hyperdrive";
+/**
+* Cloudflare Durable Object data-residency jurisdiction declared via
+* `defineSchema(...).jurisdiction("…")`. Restricts where every DO the app
+* reaches runs and persists data (GDPR, FedRAMP, US data residency). Widening
+* union — Cloudflare adds values over time.
+* @see https://developers.cloudflare.com/durable-objects/reference/data-location/
+*/
+type DurableObjectJurisdiction = "eu" | "fedramp" | "us";
 /** How a table is routed at runtime. */
 type ShardMode = {
   backend?: GlobalBackend;
@@ -15,6 +23,51 @@ type ShardMode = {
 } | {
   kind: "root";
 };
+/** Poll cadence for a sourced table — `"manual"` (pull only on an explicit trigger) or a fixed interval. */
+type ExternalSourceRefresh = "manual" | {
+  everyMs: number;
+};
+/**
+* Delete-detection mode for external-source ingest. `"full-pull"` (default) reads
+* the whole tenant membership each tick and diffs it, so it observes upstream
+* deletes; `"incremental"` pulls only changed rows (cheap) and is blind to deletes
+* unless paired with a soft-delete column or a `reconcileEveryMs` full-pull sweep.
+*/
+type ExternalSourceMode = "full-pull" | "incremental";
+/**
+* Config for `.source(...)` (plan 077): declares a table as **materialized from an
+* external Postgres/MySQL behind Cloudflare Hyperdrive**, not written by user
+* mutations. A system-driven poll loop reads the tenant slice and lands it in the
+* DO's SQLite (via the validated CDC writer), after which `defineShape` carries it
+* to clients unchanged. Orthogonal to `shardMode` — a sourced table almost always
+* also `.shardBy()`s, in which case `tenantBy` is the mandatory tenant-isolation
+* boundary (enforced by the `external_source_unscoped` advisor lint).
+*/
+interface ExternalSourceDefinition {
+  /** The wrangler Hyperdrive binding name the poll loop reads from. */
+  binding: string;
+  /** Project the materialized rows to these columns (passed to the membership diff). Omit ⇒ the full mapped document. */
+  columns?: ReadonlyArray<string>;
+  /** Column whose value becomes the Lunora `_id`. Defaults to `"id"`. */
+  idColumn?: string;
+  /** Transform an external row into the stored document body. Omit ⇒ every selected column except `idColumn` is copied. */
+  map?: (row: Record<string, unknown>) => Record<string, unknown>;
+  /** Delete-detection mode. Defaults to `"full-pull"`. */
+  mode?: ExternalSourceMode;
+  /** The full tenant-membership query, with driver-native placeholders (`$1` / `?`). `tenantBy` binds its params. */
+  query: string;
+  /** `"incremental"` only: run a full-pull reconcile this often to garbage-collect tombstones the incremental path can't see. */
+  reconcileEveryMs?: number;
+  /** Poll cadence, or `"manual"`. Omit ⇒ the runtime's size-scaled default. */
+  refresh?: ExternalSourceRefresh;
+  /**
+  * **Mandatory under `.shardBy()`**: map this DO's shard key → the query's bound
+  * params, so a tenant DO can only ever pull its own rows. An unscoped sourced +
+  * sharded table replicates the whole multitenant table into every shard — the
+  * `external_source_unscoped` advisor lint fails the build when this is absent.
+  */
+  tenantBy?: (shardKey: string) => ReadonlyArray<unknown>;
+}
 interface IndexDefinition {
   fields: ReadonlyArray<string>;
   name: string;
@@ -130,6 +183,14 @@ interface TableDefinition<Shape extends Record<string, Validator> = Record<strin
   * without scanning the underlying table.
   */
   aggregateIndexes: ReadonlyArray<AggregateIndexDefinition>;
+  /**
+  * Set by `.source(...)` (named `externalSource`, not `source`, so the data
+  * field doesn't collide with the fluent `.source()` builder method — same
+  * convention as `shardBy()`/`shardMode`). When present, the table is
+  * materialized from an external Hyperdrive-backed database by a system poll
+  * loop rather than user mutations. Implies `isExternallyManaged`.
+  */
+  externalSource?: ExternalSourceDefinition;
   indexes: ReadonlyArray<IndexDefinition>;
   /**
   * `true` when `.externallyManaged()` was called — the table's rows are
@@ -165,6 +226,20 @@ interface TableDefinition<Shape extends Record<string, Validator> = Record<strin
   shape: Shape;
   shardMode: ShardMode;
   /**
+  * Set by `.softDelete()` (named `softDeleteMode`, not `softDelete`, so the
+  * data field doesn't collide with the fluent `.softDelete()` builder method —
+  * same convention as `shardBy()`/`shardMode`). When present, the table carries
+  * a nullable timestamp column (`field`, default `deletedAt`):
+  * `ctx.db.&lt;table>.delete()` flips it instead of physically removing the row,
+  * and **list reads** (`findMany`/`findFirst`/`query()`/`count`/`aggregate`/
+  * relation loads) hide rows whose `field` is set unless
+  * `includeDeleted: true` is passed. By-id `get`/`patch`/`replace` and
+  * `restore` are unaffected. Absent ⇒ deletes are physical, as before.
+  */
+  softDeleteMode?: {
+    field: string;
+  };
+  /**
   * Declared lifecycle triggers keyed by accessor name; empty unless
   * `.triggers()` was called. Named `triggerMap` (not `triggers`) so the
   * fluent `.triggers((t) => …)` builder method doesn't collide with this
@@ -443,6 +518,16 @@ interface BatchWriteOptions {
   /** Reject the call when the batch size exceeds this value (default 500). */
   limit?: number;
 }
+/** Options accepted by {@link DatabaseWriter.insertMany} and the per-table facade. */
+interface InsertManyOptions extends BatchWriteOptions {
+  /**
+  * When `true`, a UNIQUE-constraint breach for a row resolves to `null`
+  * instead of throwing — the rest of the batch is still inserted. Skipped rows
+  * keep their input-order slot with `null` in the returned array. Mirrors
+  * better-drizzle's `createMany({ skipDuplicates: true })`.
+  */
+  skipDuplicates?: boolean;
+}
 interface DatabaseWriter extends DatabaseReader {
   delete: <T extends string>(id: Id<T>) => Promise<void>;
   /**
@@ -460,6 +545,18 @@ interface DatabaseWriter extends DatabaseReader {
     deleted: number;
   }>;
   /**
+  * Delete every row matching `where` in one call. Matching rows are resolved
+  * first, then each row is deleted through the single-row delete pipeline
+  * (triggers, companion sync, CDC, broadcast) so reactive subscriptions and
+  * search/aggregate companions stay correct.
+  *
+  * **Atomic within a mutation:** the DO wraps a mutation's dispatch in a
+  * BEGIN/COMMIT span, so a mid-batch failure rolls back the whole mutation.
+  */
+  deleteWhere: (tableName: string, where: Record<string, unknown>, options?: BatchWriteOptions) => Promise<{
+    deleted: number;
+  }>;
+  /**
   * Insert a document, returning its server id.
   *
   * Pass `options.clientId` (a UUID) to key the row yourself — for an
@@ -476,12 +573,21 @@ interface DatabaseWriter extends DatabaseReader {
   * row gets defaults, validators, triggers, and a per-row RLS check — but the
   * caller pays one round-trip instead of N.
   *
+  * Pass `{ skipDuplicates: true }` to turn UNIQUE-constraint breaches into
+  * `null` results for that row instead of failing the whole batch; the rest of
+  * the batch is still inserted and order is preserved.
+  *
   * **Atomic within a mutation:** the DO wraps a mutation's dispatch in a
   * BEGIN/COMMIT span, so a mid-batch failure (an invalid or RLS-denied row)
   * rolls back the whole mutation. (In an action there is no transaction span,
   * so the prior inserts persist; the in-memory test harness mirrors the span.)
   */
-  insertMany: <T extends string>(tableName: T, documents: ReadonlyArray<Record<string, unknown>>, options?: BatchWriteOptions) => Promise<Id<T>[]>;
+  insertMany: {
+    <T extends string>(tableName: T, documents: ReadonlyArray<Record<string, unknown>>, options: BatchWriteOptions & {
+      skipDuplicates: true;
+    }): Promise<(Id<T> | null)[]>;
+    <T extends string>(tableName: T, documents: ReadonlyArray<Record<string, unknown>>, options?: InsertManyOptions): Promise<Id<T>[]>;
+  };
   /**
   * **Trusted** bulk insert: one multi-row `INSERT` that **skips per-row
   * `.check()` validators and before/after triggers** for throughput on data you
@@ -501,7 +607,8 @@ interface DatabaseWriter extends DatabaseReader {
   patch: <T extends string>(id: Id<T>, patch: Record<string, unknown>) => Promise<void>;
   /**
   * Patch many rows by id in one call. Each `{ id, patch }` is applied like a
-  * single `patch()` (per-row triggers + RLS).
+  * single `patch()` (per-row triggers + RLS). Returns the number of rows
+  * actually patched.
   *
   * **Atomic within a mutation:** the DO wraps a mutation's dispatch in a
   * BEGIN/COMMIT span, so a mid-batch failure rolls back the whole mutation.
@@ -511,7 +618,24 @@ interface DatabaseWriter extends DatabaseReader {
   patchMany: <T extends string>(patches: ReadonlyArray<{
     id: Id<T>;
     patch: Record<string, unknown>;
-  }>, options?: BatchWriteOptions) => Promise<void>;
+  }>, options?: BatchWriteOptions) => Promise<{
+    patched: number;
+  }>;
+  /**
+  * Patch every row matching `where` with the same `patch` in one call. The
+  * matching rows are resolved first, then each row is updated through the
+  * single-row patch pipeline (OCC, triggers, companion sync, CDC, broadcast)
+  * so reactive subscriptions and search/aggregate companions stay correct.
+  *
+  * **Atomic within a mutation:** the DO wraps a mutation's dispatch in a
+  * BEGIN/COMMIT span, so a mid-batch failure rolls back the whole mutation.
+  */
+  patchWhere: (tableName: string, args: {
+    patch: Record<string, unknown>;
+    where: Record<string, unknown>;
+  }, options?: BatchWriteOptions) => Promise<{
+    patched: number;
+  }>;
   replace: <T extends string>(id: Id<T>, document: Record<string, unknown>) => Promise<void>;
 }
 /** Authenticated identity surfaced into every context. */
@@ -614,6 +738,46 @@ interface Workflows {
   /** Resolve the handle for a declared workflow by export name. */
   get: <Params = Record<string, unknown>>(name: string) => WorkflowHandle<Params>;
 }
+/**
+* Programmatic cache purge surface exposed on {@link ActionCtx}. Actions run
+* in the Worker (not the DO), so they can reach the Worker's `ctx.cache.purge`.
+* Queries and mutations do not expose this — they run inside the Durable Object.
+*/
+interface CachePurge {
+  /**
+  * Purge cached responses matching the given tags, or everything when
+  * `purgeEverything` is true. Only available in action handlers.
+  */
+  purge: (options: {
+    purgeEverything?: boolean;
+    tags?: string[];
+  }) => Promise<unknown>;
+}
+/**
+* Structural projection of workers-types' `SecretsStoreSecret` binding — the
+* per-secret `secrets_store_secrets[]` binding whose `.get()` resolves the
+* secret value (or throws if it does not exist). Mirrored structurally so the
+* runtime resolves it without a workerd type dependency.
+*/
+interface SecretsStoreSecretLike {
+  get: () => Promise<string>;
+}
+/**
+* `ctx.secrets` — read account-level secrets bound via Cloudflare Secrets Store.
+* A core built-in (always present on every context, like `ctx.log`): a binding
+* named in wrangler's `secrets_store_secrets[]` is read by its binding name.
+*
+* ```ts
+* const apiKey = await ctx.secrets.get("STRIPE_KEY");
+* ```
+*
+* The lookup is async (the platform fetches and decrypts on first read);
+* reading an undeclared name throws a directed error naming the bound secrets.
+*/
+interface Secrets {
+  /** Resolve a Secrets Store secret by its wrangler binding name. */
+  get: (name: string) => Promise<string>;
+}
 /** Lifecycle phase relative to the SQL write. */
 type TriggerTiming = "after" | "before";
 /** The CRUD operation a trigger reacts to. `patch` and `replace` both map to `update`. */
@@ -899,7 +1063,7 @@ interface VectorRecord {
 }
 /**
 * Read-only vector surface exposed on {@link QueryCtx}. Mirrors the read half
-* of `@lunora/vectors`' `LunoraVectors` so the live adapter is assignable.
+* of `@lunora/bindings/vectors`' `LunoraVectors` so the live adapter is assignable.
 */
 interface VectorSearchReader {
   getByIds: (indexName: string, ids: ReadonlyArray<string>) => Promise<ReadonlyArray<VectorRecord>>;
@@ -944,6 +1108,14 @@ interface QueryCtx {
   readonly auth: AuthState;
   readonly db: DatabaseReader;
   /**
+  * The validated, typed environment. Populated only when the project declares
+  * a `defineEnv(...)` contract in `lunora/env.ts`; codegen then narrows this to
+  * the validated `InferEnv` shape so `ctx.env.STRIPE_KEY` is parsed and
+  * coercion-aware. Absent (optional) without a contract — declare
+  * `lunora/env.ts` to populate and type it.
+  */
+  readonly env?: Record<string, unknown>;
+  /**
   * The caller's IP for this request — Cloudflare's trusted `CF-Connecting-IP`,
   * forwarded server-side (never read from a client header). `undefined` when
   * unknown: a live-subscription re-run, a server-initiated dispatch, or
@@ -969,6 +1141,8 @@ interface QueryCtx {
   * Mirrors Convex's `ctx.runQuery`.
   */
   readonly runQuery: <A extends ArgsValidator, R>(reference: RegisteredQuery<A, R>, args: InferArgs<A>) => Promise<R>;
+  /** Read account-level secrets from Cloudflare Secrets Store; see {@link Secrets}. */
+  readonly secrets: Secrets;
   readonly storage: ReadOnlyStorage;
   readonly vectors: VectorSearchReader;
 }
@@ -976,6 +1150,14 @@ interface MutationCtx {
   readonly auth: AuthState;
   readonly db: DatabaseWriter;
   /**
+  * The validated, typed environment. Populated only when the project declares
+  * a `defineEnv(...)` contract in `lunora/env.ts`; codegen then narrows this to
+  * the validated `InferEnv` shape so `ctx.env.STRIPE_KEY` is parsed and
+  * coercion-aware. Absent (optional) without a contract — declare
+  * `lunora/env.ts` to populate and type it.
+  */
+  readonly env?: Record<string, unknown>;
+  /**
   * The caller's IP for this request — Cloudflare's trusted `CF-Connecting-IP`,
   * forwarded server-side (never read from a client header). `undefined` when
   * unknown: a live-subscription re-run, a server-initiated dispatch, or
@@ -1009,6 +1191,8 @@ interface MutationCtx {
   */
   readonly runQuery: <A extends ArgsValidator, R>(reference: RegisteredQuery<A, R>, args: InferArgs<A>) => Promise<R>;
   readonly scheduler: Scheduler;
+  /** Read account-level secrets from Cloudflare Secrets Store; see {@link Secrets}. */
+  readonly secrets: Secrets;
   readonly storage: ReadOnlyStorage;
   readonly vectors: VectorSearch;
   /** Start / resume / inspect durable workflows; see {@link Workflows}. */
@@ -1016,7 +1200,22 @@ interface MutationCtx {
 }
 interface ActionCtx {
   readonly auth: AuthState;
+  /**
+  * Programmatic Workers Cache purge; see {@link CachePurge}.
+  * **Action-only** — actions run in the Worker, which has a `cache` binding.
+  * Queries and mutations run inside the Durable Object and do not expose this.
+  * Optional at runtime because Workers Cache is only present when enabled.
+  */
+  readonly cache?: CachePurge;
   readonly db: DatabaseWriter;
+  /**
+  * The validated, typed environment. Populated only when the project declares
+  * a `defineEnv(...)` contract in `lunora/env.ts`; codegen then narrows this to
+  * the validated `InferEnv` shape so `ctx.env.STRIPE_KEY` is parsed and
+  * coercion-aware. Absent (optional) without a contract — declare
+  * `lunora/env.ts` to populate and type it.
+  */
+  readonly env?: Record<string, unknown>;
   readonly fetch: typeof globalThis.fetch;
   /**
   * The caller's IP for this request — Cloudflare's trusted `CF-Connecting-IP`,
@@ -1037,6 +1236,8 @@ interface ActionCtx {
   readonly runMutation: <A extends ArgsValidator, R>(reference: RegisteredMutation<A, R>, args: InferArgs<A>) => Promise<R>;
   readonly runQuery: <A extends ArgsValidator, R>(reference: RegisteredQuery<A, R>, args: InferArgs<A>) => Promise<R>;
   readonly scheduler: Scheduler;
+  /** Read account-level secrets from Cloudflare Secrets Store; see {@link Secrets}. */
+  readonly secrets: Secrets;
   readonly storage: Storage;
   readonly vectors: VectorSearch;
   /** Start / resume / inspect durable workflows; see {@link Workflows}. */
@@ -1048,4 +1249,4 @@ interface ActionCtx {
 */
 type AnyApi = Record<string, Record<string, RegisteredFunction<ArgsValidator, unknown, FunctionKind>>>;
 declare const anyApi: AnyApi;
-export { type ActionCtx, type AggregateIndexDefinition, type AggregateOp, type AnyApi, type ArgsValidator, type AuthState, type DatabaseReader, type DatabaseWriter, type FunctionKind, type FunctionVisibility, type GlobalBackend, type IndexDefinition, type IndexRangeBuilder, type InferArgs, type LifecycleEvent, type LifecycleEventKind, type LunoraLogger, type MutationCtx, type OnDeleteAction, type PaginationOptions, type PaginationResult, type QueryCtx, type RankIndexDefinition, type RankSortKey, type ReadOnlyStorage, type RegisteredAction, type RegisteredFunction, type RegisteredLifecycleHook, type RegisteredMutation, type RegisteredQuery, type RegisteredStream, type RelationDefinition, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type Schema, type SearchFilterBuilder, type SearchIndexDefinition, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableDefinition, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerBuilder, type TriggerCtx, type TriggerDatabase, type TriggerDefinition, type TriggerDeleteEvent, type TriggerEvent, type TriggerGroupByEntry, type TriggerGroupByOptions, type TriggerHandler, type TriggerInsertEvent, type TriggerOp, type TriggerQueryArgs, type TriggerQueryPage, type TriggerRankOptions, type TriggerRankPageOptions, type TriggerRankResult, type TriggerRow, type TriggerTiming, type TriggerUpdateEvent, type VectorEmbedder, type VectorIndexDefinition, type VectorMatch, type VectorMatches, type VectorMetric, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, anyApi };
+export { type ActionCtx, type AggregateIndexDefinition, type AggregateOp, type AnyApi, type ArgsValidator, type AuthState, type CachePurge, type DatabaseReader, type DatabaseWriter, type DurableObjectJurisdiction, type ExternalSourceDefinition, type ExternalSourceMode, type ExternalSourceRefresh, type FunctionKind, type FunctionVisibility, type GlobalBackend, type IndexDefinition, type IndexRangeBuilder, type InferArgs, type LifecycleEvent, type LifecycleEventKind, type LunoraLogger, type MutationCtx, type OnDeleteAction, type PaginationOptions, type PaginationResult, type QueryCtx, type RankIndexDefinition, type RankSortKey, type ReadOnlyStorage, type RegisteredAction, type RegisteredFunction, type RegisteredLifecycleHook, type RegisteredMutation, type RegisteredQuery, type RegisteredStream, type RelationDefinition, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type Schema, type SearchFilterBuilder, type SearchIndexDefinition, type Secrets, type SecretsStoreSecretLike, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableDefinition, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerBuilder, type TriggerCtx, type TriggerDatabase, type TriggerDefinition, type TriggerDeleteEvent, type TriggerEvent, type TriggerGroupByEntry, type TriggerGroupByOptions, type TriggerHandler, type TriggerInsertEvent, type TriggerOp, type TriggerQueryArgs, type TriggerQueryPage, type TriggerRankOptions, type TriggerRankPageOptions, type TriggerRankResult, type TriggerRow, type TriggerTiming, type TriggerUpdateEvent, type VectorEmbedder, type VectorIndexDefinition, type VectorMatch, type VectorMatches, type VectorMetric, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, anyApi };