@lunora/server 1.0.0-alpha.7 → 1.0.0-alpha.9

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { Validator, Infer, ValidatorMap, InferValidatorMap, v } from '@lunora/values';
 export { type ColumnValidator, type Id, type Infer, ValidationError, type Validator, type ValidatorKind, v } from '@lunora/values';
-import { ArgsValidator, InferArgs, RegisteredAction, ActionCtx, MutationCtx, RegisteredMutation, QueryCtx, RegisteredQuery, RegisteredStream, FunctionKind, Secrets, LifecycleEvent, RegisteredLifecycleHook, TableDefinition, RegisteredFunction, VectorIndexDefinition, Schema, AggregateOp, DurableObjectJurisdiction, RelationDefinition, GlobalBackend, OnDeleteAction, TriggerBuilder, TriggerDefinition, VectorEmbedder, VectorMetric, AggregateIndexDefinition, RankIndexDefinition } from "./types.mjs";
+import { ArgsValidator, InferArgs, RegisteredAction, ActionCtx, MutationCtx, RegisteredMutation, QueryCtx, RegisteredQuery, RegisteredStream, FunctionKind, Secrets, LifecycleEvent, RegisteredLifecycleHook, TableDefinition, RegisteredFunction, VectorIndexDefinition, Schema, AggregateOp, DurableObjectJurisdiction, RelationDefinition, GlobalBackend, OnDeleteAction, ExternalSourceDefinition, TriggerBuilder, TriggerDefinition, VectorEmbedder, VectorMetric, AggregateIndexDefinition, RankIndexDefinition } from "./types.mjs";
 export { type AnyApi, type AuthState, type DatabaseReader, type DatabaseWriter, type FunctionVisibility, type IndexDefinition, type IndexRangeBuilder, type LifecycleEventKind, type LunoraLogger, type PaginationOptions, type PaginationResult, type RankSortKey, type ReadOnlyStorage, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type SearchFilterBuilder, type SearchIndexDefinition, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerCtx, type TriggerDatabase, 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 VectorMatch, type VectorMatches, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, anyApi } from "./types.mjs";
 import { Context, Hono } from 'hono';
 import { b as Permission, R as Role, T as TypedDefinePolicyInput, a as Policy, D as DefinePolicyInput, W as WhereInput, c as RlsOptions } from "./packem_shared/types.d-DmvyEMD6.mjs";
@@ -283,7 +283,10 @@ declare const defineEnv: <S extends EnvShape>(shape: S) => EnvAccessor<S>;
 * The runtime's structural error mapper keys off `name === "LunoraError"` plus
 * the numeric `status`, so throwing one of these from a handler or middleware
 * yields the right RPC/HTTP status without any further wiring. `code` carries
-* the machine-readable reason for clients.
+* the machine-readable reason for clients; the optional `data` carries a
+* structured, JSON+wire-encodable payload propagated verbatim to the client
+* (e.g. `{ retryAfterMs }`). Only an explicit `LunoraError`'s `data` crosses the
+* wire — an unhandled throw is still redacted to a generic message server-side.
 */
 declare const CODE_STATUS: {
   readonly BAD_REQUEST: 400;
@@ -329,7 +332,9 @@ declare class LunoraError extends Error {
   override readonly name = "LunoraError";
   readonly code: LunoraErrorCode;
   readonly status: number;
-  constructor(code: LunoraErrorCode, message?: string);
+  /** Structured, JSON+wire-encodable payload surfaced to the client alongside `code`. */
+  readonly data?: unknown;
+  constructor(code: LunoraErrorCode, message?: string, data?: unknown);
 }
 /**
 * Minimal structural writer the facade binds over. Declared with **method**
@@ -1271,6 +1276,19 @@ interface TableBuilder<Shape extends Record<string, Validator> = Record<string,
   softDelete: (options?: {
     field?: string;
   }) => TableBuilder<Shape>;
+  /**
+  * Materialize this table from an external Postgres/MySQL behind Cloudflare
+  * Hyperdrive (plan 077). A system-driven poll loop reads the tenant slice
+  * (`query`, with params bound from `tenantBy`) and lands it in the DO's SQLite,
+  * after which `defineShape` carries it to clients unchanged. Implies
+  * `.externallyManaged()` (rows come from the ingest loop, not user mutations).
+  *
+  * Orthogonal to `.shardBy()` — combine them for per-tenant DOs. **Under
+  * `.shardBy()` `tenantBy` is mandatory** (the tenant-isolation boundary); the
+  * `external_source_unscoped` advisor lint fails the build when it is absent, and
+  * `external_source_on_global` rejects combining `.source()` with `.global()`.
+  */
+  source: (definition: ExternalSourceDefinition) => TableBuilder<Shape>;
   /** Declare named lifecycle triggers fired inline within the write path. */
   triggers: (build: (t: TriggerBuilder<Shape>) => Record<string, TriggerDefinition>) => TableBuilder<Shape>;
   /** Declare a vector index over a single text field on this table. */

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Validator, Infer, ValidatorMap, InferValidatorMap, v } from '@lunora/values';
 export { type ColumnValidator, type Id, type Infer, ValidationError, type Validator, type ValidatorKind, v } from '@lunora/values';
-import { ArgsValidator, InferArgs, RegisteredAction, ActionCtx, MutationCtx, RegisteredMutation, QueryCtx, RegisteredQuery, RegisteredStream, FunctionKind, Secrets, LifecycleEvent, RegisteredLifecycleHook, TableDefinition, RegisteredFunction, VectorIndexDefinition, Schema, AggregateOp, DurableObjectJurisdiction, RelationDefinition, GlobalBackend, OnDeleteAction, TriggerBuilder, TriggerDefinition, VectorEmbedder, VectorMetric, AggregateIndexDefinition, RankIndexDefinition } from "./types.js";
+import { ArgsValidator, InferArgs, RegisteredAction, ActionCtx, MutationCtx, RegisteredMutation, QueryCtx, RegisteredQuery, RegisteredStream, FunctionKind, Secrets, LifecycleEvent, RegisteredLifecycleHook, TableDefinition, RegisteredFunction, VectorIndexDefinition, Schema, AggregateOp, DurableObjectJurisdiction, RelationDefinition, GlobalBackend, OnDeleteAction, ExternalSourceDefinition, TriggerBuilder, TriggerDefinition, VectorEmbedder, VectorMetric, AggregateIndexDefinition, RankIndexDefinition } from "./types.js";
 export { type AnyApi, type AuthState, type DatabaseReader, type DatabaseWriter, type FunctionVisibility, type IndexDefinition, type IndexRangeBuilder, type LifecycleEventKind, type LunoraLogger, type PaginationOptions, type PaginationResult, type RankSortKey, type ReadOnlyStorage, type ScheduledFunctionDoc, type ScheduledJob, type Scheduler, type SearchFilterBuilder, type SearchIndexDefinition, type ShardMode, type Storage, type StorageMetadata, type SystemDatabaseReader, type SystemDoc, type SystemQuery, type SystemTableName, type TableReader, type TableVectorIndex, type TriggerAggregateOptions, type TriggerCtx, type TriggerDatabase, 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 VectorMatch, type VectorMatches, type VectorQueryInput, type VectorRecord, type VectorSearch, type VectorSearchReader, type VectorUpsertInput, type WorkflowCreateOptions, type WorkflowHandle, type WorkflowInstance, type WorkflowInstanceStatus, type WorkflowStatusResult, type Workflows, anyApi } from "./types.js";
 import { Context, Hono } from 'hono';
 import { b as Permission, R as Role, T as TypedDefinePolicyInput, a as Policy, D as DefinePolicyInput, W as WhereInput, c as RlsOptions } from "./packem_shared/types.d-BDY0FYHK.js";
@@ -283,7 +283,10 @@ declare const defineEnv: <S extends EnvShape>(shape: S) => EnvAccessor<S>;
 * The runtime's structural error mapper keys off `name === "LunoraError"` plus
 * the numeric `status`, so throwing one of these from a handler or middleware
 * yields the right RPC/HTTP status without any further wiring. `code` carries
-* the machine-readable reason for clients.
+* the machine-readable reason for clients; the optional `data` carries a
+* structured, JSON+wire-encodable payload propagated verbatim to the client
+* (e.g. `{ retryAfterMs }`). Only an explicit `LunoraError`'s `data` crosses the
+* wire — an unhandled throw is still redacted to a generic message server-side.
 */
 declare const CODE_STATUS: {
   readonly BAD_REQUEST: 400;
@@ -329,7 +332,9 @@ declare class LunoraError extends Error {
   override readonly name = "LunoraError";
   readonly code: LunoraErrorCode;
   readonly status: number;
-  constructor(code: LunoraErrorCode, message?: string);
+  /** Structured, JSON+wire-encodable payload surfaced to the client alongside `code`. */
+  readonly data?: unknown;
+  constructor(code: LunoraErrorCode, message?: string, data?: unknown);
 }
 /**
 * Minimal structural writer the facade binds over. Declared with **method**
@@ -1271,6 +1276,19 @@ interface TableBuilder<Shape extends Record<string, Validator> = Record<string,
   softDelete: (options?: {
     field?: string;
   }) => TableBuilder<Shape>;
+  /**
+  * Materialize this table from an external Postgres/MySQL behind Cloudflare
+  * Hyperdrive (plan 077). A system-driven poll loop reads the tenant slice
+  * (`query`, with params bound from `tenantBy`) and lands it in the DO's SQLite,
+  * after which `defineShape` carries it to clients unchanged. Implies
+  * `.externallyManaged()` (rows come from the ingest loop, not user mutations).
+  *
+  * Orthogonal to `.shardBy()` — combine them for per-tenant DOs. **Under
+  * `.shardBy()` `tenantBy` is mandatory** (the tenant-isolation boundary); the
+  * `external_source_unscoped` advisor lint fails the build when it is absent, and
+  * `external_source_on_global` rejects combining `.source()` with `.global()`.
+  */
+  source: (definition: ExternalSourceDefinition) => TableBuilder<Shape>;
   /** Declare named lifecycle triggers fired inline within the write path. */
   triggers: (build: (t: TriggerBuilder<Shape>) => Record<string, TriggerDefinition>) => TableBuilder<Shape>;
   /** Declare a vector index over a single text field on this table. */

package/dist/index.mjs

@@ -2,26 +2,26 @@ export { default as asBucketStorage } from './packem_shared/asBucketStorage-Cnxd
 export { initLunora } from './packem_shared/initLunora-lxwHTEV3.mjs';
 export { createSecrets } from './packem_shared/createSecrets-TsIP9lOa.mjs';
 export { LunoraEnvError, defineEnv, redactSecrets } from './packem_shared/LunoraEnvError-DjFkpkSP.mjs';
-export { LunoraError } from './packem_shared/LunoraError-DhggBJZF.mjs';
+export { LunoraError } from './packem_shared/LunoraError-DN7Zhhvu.mjs';
 export { bindOrm, bindTableFacade } from './packem_shared/bindOrm-Ce57S3N9.mjs';
-export { httpAction, httpRoute, httpRouter, serveStorageObject } from './packem_shared/httpAction-B7FYUEgr.mjs';
+export { httpAction, httpRoute, httpRouter, serveStorageObject } from './packem_shared/httpAction-FLwfsePg.mjs';
 export { onConnect, onDisconnect } from './packem_shared/onConnect-CIPXKPyw.mjs';
 export { defineMigration } from './packem_shared/defineMigration-CAJLr6fx.mjs';
 export { defineMutator } from './packem_shared/defineMutator-EIXAWhs9.mjs';
 export { composePluginMiddleware, defineComponent, definePlugin, defineSchemaExtension, installPlugins, mergeSchemaExtension } from './packem_shared/composePluginMiddleware-Ck5_TUO8.mjs';
-export { PRESENCE_DEFAULT_TTL_MS, PRESENCE_TABLE, definePresence, presenceExtension } from './packem_shared/PRESENCE_DEFAULT_TTL_MS-DH9zLyXa.mjs';
+export { PRESENCE_DEFAULT_TTL_MS, PRESENCE_TABLE, definePresence, presenceExtension } from './packem_shared/PRESENCE_DEFAULT_TTL_MS-D8viLY1S.mjs';
 export { protectPublic } from './packem_shared/protectPublic-BjFkQ_Or.mjs';
-export { defineAggregateIndex, defineRankIndex, defineSchema, defineTable, defineVectorIndex } from './packem_shared/defineAggregateIndex-C2gT1GzM.mjs';
+export { defineAggregateIndex, defineRankIndex, defineSchema, defineTable, defineVectorIndex } from './packem_shared/defineAggregateIndex-ZdyU78gh.mjs';
 export { defineShape } from './packem_shared/defineShape-CJ27Wx7o.mjs';
 export { anyApi } from './types.mjs';
 export { cronJobs } from '@lunora/scheduler';
 export { ValidationError, v } from '@lunora/values';
-export { buildRlsReadRegistry, composeShapeReadWhere } from './packem_shared/buildRlsReadRegistry-CkxuS69B.mjs';
+export { buildRlsReadRegistry, composeShapeReadWhere } from './packem_shared/buildRlsReadRegistry-1jexWrb3.mjs';
 export { createPolicyDsl, definePermission, definePolicies, definePolicy, defineRole } from './packem_shared/createPolicyDsl-De67zPDS.mjs';
 export { defineStorageRule, defineStorageRules } from './packem_shared/defineStorageRule-qu0mpilX.mjs';
-export { mask } from './packem_shared/mask-eCUYOwhd.mjs';
-export { rls } from './packem_shared/rls-ClmjkkxZ.mjs';
-export { storageRules } from './packem_shared/storageRules-4a30FSpI.mjs';
+export { mask } from './packem_shared/mask-BV_jNzsN.mjs';
+export { rls } from './packem_shared/rls-2Jhd0uev.mjs';
+export { storageRules } from './packem_shared/storageRules-Cje6Woea.mjs';
 
 const VERSION = "0.0.0";
 

package/dist/packem_shared/{LunoraError-DhggBJZF.mjs → LunoraError-DN7Zhhvu.mjs}

@@ -41,10 +41,13 @@ class LunoraError extends Error {
   name = "LunoraError";
   code;
   status;
-  constructor(code, message) {
+  /** Structured, JSON+wire-encodable payload surfaced to the client alongside `code`. */
+  data;
+  constructor(code, message, data) {
     super(message ?? code);
     this.code = code;
     this.status = CODE_STATUS[code];
+    this.data = data;
   }
 }
 

package/dist/packem_shared/{PRESENCE_DEFAULT_TTL_MS-DH9zLyXa.mjs → PRESENCE_DEFAULT_TTL_MS-D8viLY1S.mjs}

@@ -1,9 +1,9 @@
 import { v } from '@lunora/values';
 import { initLunora } from './initLunora-lxwHTEV3.mjs';
-import { LunoraError } from './LunoraError-DhggBJZF.mjs';
+import { LunoraError } from './LunoraError-DN7Zhhvu.mjs';
 import { onDisconnect } from './onConnect-CIPXKPyw.mjs';
 import { defineSchemaExtension, defineComponent } from './composePluginMiddleware-Ck5_TUO8.mjs';
-import { defineTable } from './defineAggregateIndex-C2gT1GzM.mjs';
+import { defineTable } from './defineAggregateIndex-ZdyU78gh.mjs';
 
 const DEFAULT_TTL_MS = 3e4;
 const MAX_DATA_BYTES = 4096;

package/dist/packem_shared/{buildRlsReadRegistry-CkxuS69B.mjs → buildRlsReadRegistry-1jexWrb3.mjs}

@@ -1,4 +1,4 @@
-import { indexRolePermissions, computeReadBaseWhere, permissionName } from './rls-ClmjkkxZ.mjs';
+import { indexRolePermissions, computeReadBaseWhere, permissionName } from './rls-2Jhd0uev.mjs';
 import { r as readRlsTag } from './policy-tag-DvpVH2tv.mjs';
 
 const FALSE_PREDICATE = { OR: [] };

package/dist/packem_shared/{defineAggregateIndex-C2gT1GzM.mjs → defineAggregateIndex-ZdyU78gh.mjs}

@@ -41,6 +41,7 @@ const defineTable = (inputShape) => {
   let isExternallyManaged = false;
   let isPublic = false;
   let softDelete;
+  let externalSource;
   const builder = {
     aggregateIndex(name, options) {
       const op = options?.op ?? "count";
@@ -63,6 +64,9 @@ const defineTable = (inputShape) => {
     get aggregateIndexes() {
       return aggregateIndexes;
     },
+    get externalSource() {
+      return externalSource;
+    },
     externallyManaged() {
       isExternallyManaged = true;
       return builder;
@@ -137,6 +141,17 @@ const defineTable = (inputShape) => {
     get softDeleteMode() {
       return softDelete;
     },
+    source(definition) {
+      if (!definition.binding) {
+        throw new Error("source: `binding` is required (the wrangler Hyperdrive binding name)");
+      }
+      if (!definition.query) {
+        throw new Error("source: `query` is required (the tenant-membership SQL)");
+      }
+      externalSource = definition;
+      isExternallyManaged = true;
+      return builder;
+    },
     softDelete(options) {
       const field = options?.field ?? "deletedAt";
       softDelete = { field };
@@ -243,9 +258,33 @@ const attachStandaloneIndexes = (tables, aggregateIndexes, rankIndexes) => {
     table.rankIndexes.push(index);
   }
 };
+const validateExternalSources = (tables) => {
+  for (const [name, table] of Object.entries(tables)) {
+    const source = table.externalSource;
+    if (!source) {
+      continue;
+    }
+    if (table.shardMode.kind === "global") {
+      throw new Error(
+        `defineSchema: table "${name}" cannot be both .source() and .global() — a sourced table materializes into a shard DO's SQLite, a global table lives in the external tier`
+      );
+    }
+    if (table.shardMode.kind === "shardBy" && !source.tenantBy) {
+      throw new Error(
+        `defineSchema: sourced + .shardBy() table "${name}" needs a \`tenantBy\` mapper — without it every tenant's DO would run the same unscoped query and replicate the whole multitenant table (a cross-tenant leak). Add \`tenantBy: (shardKey) => [shardKey]\` binding the shard key into the query's parameters.`
+      );
+    }
+    if (source.mode === "incremental") {
+      throw new Error(
+        `defineSchema: table "${name}" uses \`mode: "incremental"\`, which is not yet implemented — only "full-pull" (the default) is supported. Remove \`mode\` or set it to "full-pull".`
+      );
+    }
+  }
+};
 const defineSchema = (tables, vectorIndexes = {}, aggregateIndexes = {}, rankIndexes = {}) => {
   fillIndexTableNames(tables);
   attachStandaloneIndexes(tables, aggregateIndexes, rankIndexes);
+  validateExternalSources(tables);
   return withExtend({ tables, vectorIndexes });
 };
 

package/dist/packem_shared/{httpAction-B7FYUEgr.mjs → httpAction-FLwfsePg.mjs}

@@ -1,6 +1,6 @@
 import { parseValidatorMap, ValidationError } from '@lunora/values';
 import { Hono } from 'hono';
-import { LunoraError } from './LunoraError-DhggBJZF.mjs';
+import { LunoraError } from './LunoraError-DN7Zhhvu.mjs';
 
 const httpAction = (handler) => async (c) => handler(c.get("lunora"), c.req.raw);
 const httpRouter = () => {

package/dist/packem_shared/{mask-eCUYOwhd.mjs → mask-BV_jNzsN.mjs}

@@ -1,4 +1,4 @@
-import { LunoraError } from './LunoraError-DhggBJZF.mjs';
+import { LunoraError } from './LunoraError-DN7Zhhvu.mjs';
 import { bindTableFacade, bindOrm } from './bindOrm-Ce57S3N9.mjs';
 
 const permissionName = (permission) => typeof permission === "string" ? permission : permission.name;

package/dist/packem_shared/{rls-ClmjkkxZ.mjs → rls-2Jhd0uev.mjs}

@@ -1,4 +1,4 @@
-import { LunoraError } from './LunoraError-DhggBJZF.mjs';
+import { LunoraError } from './LunoraError-DN7Zhhvu.mjs';
 import { bindTableFacade, bindOrm } from './bindOrm-Ce57S3N9.mjs';
 import { t as tagRlsMiddleware } from './policy-tag-DvpVH2tv.mjs';
 

package/dist/packem_shared/{storageRules-4a30FSpI.mjs → storageRules-Cje6Woea.mjs}

@@ -1,4 +1,4 @@
-import { LunoraError } from './LunoraError-DhggBJZF.mjs';
+import { LunoraError } from './LunoraError-DN7Zhhvu.mjs';
 
 const permissionName = (permission) => typeof permission === "string" ? permission : permission.name;
 const indexRolePermissions = (roles = []) => {

package/dist/rls/testing.mjs

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

package/dist/types.d.mts

@@ -23,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;
@@ -138,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
@@ -1101,4 +1154,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 DurableObjectJurisdiction, 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 };
+export { type ActionCtx, type AggregateIndexDefinition, type AggregateOp, type AnyApi, type ArgsValidator, type AuthState, 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 };

package/dist/types.d.ts

@@ -23,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;
@@ -138,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
@@ -1101,4 +1154,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 DurableObjectJurisdiction, 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 };
+export { type ActionCtx, type AggregateIndexDefinition, type AggregateOp, type AnyApi, type ArgsValidator, type AuthState, 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/server",
-  "version": "1.0.0-alpha.7",
+  "version": "1.0.0-alpha.9",
   "description": "Server primitives for Lunora: defineSchema, defineTable, query, mutation, and action",
   "keywords": [
     "backend",