@lunora/server 1.0.0-alpha.24 → 1.0.0-alpha.26

package/dist/index.d.mts

@@ -558,6 +558,7 @@ interface HttpRouteHandlerOptions<SearchParams extends ArgsValidator, Body exten
 * handler receives. There is no parsed `body` — streams are typically GET, and
 * the raw `request` is exposed if a handler needs to read the body itself.
 * `signal` is tripped when the client disconnects.
+* @experimental Part of the HTTP-SSE stream surface; reconnect/POST-body design questions are still open.
 */
 interface HttpStreamHandlerOptions<SearchParams extends ArgsValidator, Params extends ArgsValidator> {
   ctx: HttpActionCtx;
@@ -604,6 +605,7 @@ interface HttpRouteBuilder<SearchParams extends ArgsValidator, Body extends Args
   * throw, an `event: error` frame is written with `{code, message}` before
   * the stream closes. The chunks are JSON-encoded; `R` is inferred from the
   * handler's yielded type.
+  * @experimental Reconnect/POST-body/wire-fidelity design questions are still open, so the shape may change.
   */
   stream: <R>(handler: (options: HttpStreamHandlerOptions<SearchParams, Params>) => AsyncGenerator<R, void, void> | AsyncIterable<R>) => LunoraRouteHandler;
   /**
@@ -1141,10 +1143,26 @@ interface DefinePluginOptions<TExtension extends Record<string, TableDefinition>
   middleware?: Middleware<TContextIn, TContextOut>;
 }
 /**
+* Call signatures for {@link definePlugin}. When `extension` is supplied the
+* returned plugin's `extension` is typed as PRESENT (not `?`), so the
+* canonical install pattern `defineSchema(...).extend(plugin.extension)`
+* typechecks without a non-null assertion — the shape every scaffold template
+* ships. The bare-options signature keeps `extension` optional for plugins
+* that carry only middleware.
+*/
+interface DefinePluginFunction {
+  <TExtension extends Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn>(key: string, options: DefinePluginOptions<TExtension, TContextIn, TContextOut> & {
+    extension: SchemaExtension<TExtension>;
+  }): Plugin<TExtension, TContextIn, TContextOut> & {
+    readonly extension: SchemaExtension<TExtension>;
+  };
+  <TExtension extends Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn>(key: string, options: DefinePluginOptions<TExtension, TContextIn, TContextOut>): Plugin<TExtension, TContextIn, TContextOut>;
+}
+/**
 * Package a schema extension + middleware as a reusable plugin. Either
 * field is optional — `definePlugin("foo", {})` is valid but degenerate.
 */
-declare const definePlugin: <TExtension extends Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn>(key: string, options: DefinePluginOptions<TExtension, TContextIn, TContextOut>) => Plugin<TExtension, TContextIn, TContextOut>;
+declare const definePlugin: DefinePluginFunction;
 /**
 * Bundle of registered functions a {@link Component} ships. Keys are the
 * function's local name (e.g. `check`, `reset`); the registered function

package/dist/index.d.ts

@@ -558,6 +558,7 @@ interface HttpRouteHandlerOptions<SearchParams extends ArgsValidator, Body exten
 * handler receives. There is no parsed `body` — streams are typically GET, and
 * the raw `request` is exposed if a handler needs to read the body itself.
 * `signal` is tripped when the client disconnects.
+* @experimental Part of the HTTP-SSE stream surface; reconnect/POST-body design questions are still open.
 */
 interface HttpStreamHandlerOptions<SearchParams extends ArgsValidator, Params extends ArgsValidator> {
   ctx: HttpActionCtx;
@@ -604,6 +605,7 @@ interface HttpRouteBuilder<SearchParams extends ArgsValidator, Body extends Args
   * throw, an `event: error` frame is written with `{code, message}` before
   * the stream closes. The chunks are JSON-encoded; `R` is inferred from the
   * handler's yielded type.
+  * @experimental Reconnect/POST-body/wire-fidelity design questions are still open, so the shape may change.
   */
   stream: <R>(handler: (options: HttpStreamHandlerOptions<SearchParams, Params>) => AsyncGenerator<R, void, void> | AsyncIterable<R>) => LunoraRouteHandler;
   /**
@@ -1141,10 +1143,26 @@ interface DefinePluginOptions<TExtension extends Record<string, TableDefinition>
   middleware?: Middleware<TContextIn, TContextOut>;
 }
 /**
+* Call signatures for {@link definePlugin}. When `extension` is supplied the
+* returned plugin's `extension` is typed as PRESENT (not `?`), so the
+* canonical install pattern `defineSchema(...).extend(plugin.extension)`
+* typechecks without a non-null assertion — the shape every scaffold template
+* ships. The bare-options signature keeps `extension` optional for plugins
+* that carry only middleware.
+*/
+interface DefinePluginFunction {
+  <TExtension extends Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn>(key: string, options: DefinePluginOptions<TExtension, TContextIn, TContextOut> & {
+    extension: SchemaExtension<TExtension>;
+  }): Plugin<TExtension, TContextIn, TContextOut> & {
+    readonly extension: SchemaExtension<TExtension>;
+  };
+  <TExtension extends Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn>(key: string, options: DefinePluginOptions<TExtension, TContextIn, TContextOut>): Plugin<TExtension, TContextIn, TContextOut>;
+}
+/**
 * Package a schema extension + middleware as a reusable plugin. Either
 * field is optional — `definePlugin("foo", {})` is valid but degenerate.
 */
-declare const definePlugin: <TExtension extends Record<string, TableDefinition>, TContextIn = unknown, TContextOut = TContextIn>(key: string, options: DefinePluginOptions<TExtension, TContextIn, TContextOut>) => Plugin<TExtension, TContextIn, TContextOut>;
+declare const definePlugin: DefinePluginFunction;
 /**
 * Bundle of registered functions a {@link Component} ships. Keys are the
 * function's local name (e.g. `check`, `reset`); the registered function

package/dist/index.mjs

@@ -9,10 +9,10 @@ export { defineIdentity } from './packem_shared/defineIdentity-DiX4zM9x.mjs';
 export { onConnect, onDisconnect } from './packem_shared/onConnect-CIPXKPyw.mjs';
 export { defineMigration } from './packem_shared/defineMigration-Hx01yIht.mjs';
 export { defineMutator } from './packem_shared/defineMutator-EIXAWhs9.mjs';
-export { composePluginMiddleware, defineComponent, definePlugin, defineSchemaExtension, installPlugins, mergeSchemaExtension } from './packem_shared/composePluginMiddleware-CcTj1_v2.mjs';
-export { PRESENCE_DEFAULT_TTL_MS, PRESENCE_TABLE, definePresence, presenceExtension } from './packem_shared/PRESENCE_DEFAULT_TTL_MS-BAD0QPAg.mjs';
+export { composePluginMiddleware, defineComponent, definePlugin, defineSchemaExtension, installPlugins, mergeSchemaExtension } from './packem_shared/composePluginMiddleware-z62dttBo.mjs';
+export { PRESENCE_DEFAULT_TTL_MS, PRESENCE_TABLE, definePresence, presenceExtension } from './packem_shared/PRESENCE_DEFAULT_TTL_MS-Cv1UPaJj.mjs';
 export { protectPublic } from './packem_shared/protectPublic-BlcGpiRc.mjs';
-export { defineAggregateIndex, defineRankIndex, defineSchema, defineTable, defineVectorIndex } from './packem_shared/defineAggregateIndex-znq4ygKQ.mjs';
+export { defineAggregateIndex, defineRankIndex, defineSchema, defineTable, defineVectorIndex } from './packem_shared/defineAggregateIndex-DTULzh09.mjs';
 export { defineShape } from './packem_shared/defineShape-C5scNOrf.mjs';
 export { anyApi } from './types.mjs';
 export { cronJobs } from '@lunora/scheduler';

package/dist/packem_shared/{PRESENCE_DEFAULT_TTL_MS-BAD0QPAg.mjs → PRESENCE_DEFAULT_TTL_MS-Cv1UPaJj.mjs}

@@ -2,8 +2,8 @@ import { v } from '@lunora/values';
 import { initLunora } from './initLunora-CmMVk4i7.mjs';
 import { LunoraError } from './LunoraError-WbxmrpxR.mjs';
 import { onDisconnect } from './onConnect-CIPXKPyw.mjs';
-import { defineSchemaExtension, defineComponent } from './composePluginMiddleware-CcTj1_v2.mjs';
-import { defineTable } from './defineAggregateIndex-znq4ygKQ.mjs';
+import { defineSchemaExtension, defineComponent } from './composePluginMiddleware-z62dttBo.mjs';
+import { defineTable } from './defineAggregateIndex-DTULzh09.mjs';
 
 const DEFAULT_TTL_MS = 3e4;
 const MAX_DATA_BYTES = 4096;

package/dist/packem_shared/{composePluginMiddleware-CcTj1_v2.mjs → composePluginMiddleware-z62dttBo.mjs}

@@ -28,7 +28,7 @@ const defineSchemaExtension = (key, options) => {
     ...options.vectorIndexes ? { vectorIndexes: options.vectorIndexes } : {}
   };
 };
-const definePlugin = (key, options) => {
+const definePlugin = ((key, options) => {
   if (!key) {
     throw new LunoraError$1("INTERNAL", "definePlugin: `key` is required and must be a non-empty string");
   }
@@ -40,7 +40,7 @@ const definePlugin = (key, options) => {
     ...options.extension ? { extension: options.extension } : {},
     ...options.middleware ? { middleware: options.middleware } : {}
   };
-};
+});
 const defineComponent = (key, options) => {
   const plugin = definePlugin(key, {
     ...options.extension ? { extension: options.extension } : {},

package/dist/packem_shared/{defineAggregateIndex-znq4ygKQ.mjs → defineAggregateIndex-DTULzh09.mjs}

@@ -1,6 +1,6 @@
 import { LunoraError as LunoraError$1 } from '@lunora/errors';
 import { isOrWrapsFromValidator, v } from '@lunora/values';
-import { mergeSchemaExtension } from './composePluginMiddleware-CcTj1_v2.mjs';
+import { mergeSchemaExtension } from './composePluginMiddleware-z62dttBo.mjs';
 
 const relationBuilder = {
   many: (table, options) => {
@@ -259,6 +259,49 @@ const attachStandaloneIndexes = (tables, aggregateIndexes, rankIndexes) => {
     table.rankIndexes.push(index);
   }
 };
+const strayIncrementalKnob = (source) => {
+  if (source.cursor) {
+    return "cursor";
+  }
+  if (source.reconcileEveryMs !== void 0) {
+    return "reconcileEveryMs";
+  }
+  if (source.softDeleteColumn !== void 0) {
+    return "softDeleteColumn";
+  }
+  return void 0;
+};
+const validateExternalSourceMode = (name, source) => {
+  const isIncremental = source.mode === "incremental";
+  if (source.mode !== void 0 && source.mode !== "full-pull" && !isIncremental) {
+    throw new LunoraError$1(
+      "INTERNAL",
+      `defineSchema: table "${name}" uses \`mode: ${JSON.stringify(source.mode)}\` — supported modes are "full-pull" (default) and "incremental".`
+    );
+  }
+  if (!isIncremental) {
+    const strayKnob = strayIncrementalKnob(source);
+    if (strayKnob) {
+      throw new LunoraError$1(
+        "INTERNAL",
+        `defineSchema: table "${name}" sets \`${strayKnob}\` but is not \`mode: "incremental"\` — that knob only applies to incremental ingest. Set \`mode: "incremental"\` or remove \`${strayKnob}\`.`
+      );
+    }
+    return;
+  }
+  if (!source.cursor?.column || !source.cursor.query) {
+    throw new LunoraError$1(
+      "INTERNAL",
+      `defineSchema: table "${name}" is \`mode: "incremental"\` but has no \`cursor\` — add \`cursor: { column: "updated_at", query: "… WHERE … > $N" }\` binding the watermark as the trailing parameter.`
+    );
+  }
+  if (source.reconcileEveryMs === void 0 && source.softDeleteColumn === void 0) {
+    throw new LunoraError$1(
+      "INTERNAL",
+      `defineSchema: table "${name}" is \`mode: "incremental"\` with no delete-visibility path — an incremental pull never sees upstream deletes, so it would accumulate phantom rows. Add \`reconcileEveryMs\` (a periodic full-pull sweep) or \`softDeleteColumn\` (an upstream tombstone column).`
+    );
+  }
+};
 const validateExternalSources = (tables) => {
   for (const [name, table] of Object.entries(tables)) {
     const source = table.externalSource;
@@ -277,12 +320,7 @@ const validateExternalSources = (tables) => {
         `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 LunoraError$1(
-        "INTERNAL",
-        `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".`
-      );
-    }
+    validateExternalSourceMode(name, source);
   }
 };
 const defineSchema = (tables, vectorIndexes = {}, aggregateIndexes = {}, rankIndexes = {}) => {

package/dist/types.d.mts

@@ -28,13 +28,38 @@ 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.
+* Delete-detection mode for external-source ingest (plan 077 / 136).
+*
+* `"full-pull"` (the default) reads the **whole** tenant membership each tick and
+* diffs it, so it observes upstream deletes for free — but costs a full read per tick
+* (the Phase-0 bench put the ceiling at ~10k rows).
+*
+* `"incremental"` pulls **only rows past a durable watermark** (`cursor`), cheap for
+* large low-churn tables above the full-pull cap. Because an absent row then means
+* "unchanged", not "deleted", incremental requires a delete-visibility path: either a
+* `reconcileEveryMs` periodic full-pull sweep, or a `softDeleteColumn` whose
+* tombstones the pull returns. `defineSchema` throws (and the
+* `external_source_incremental_no_delete_path` advisor lint fails the build) when an
+* incremental source declares neither.
 */
 type ExternalSourceMode = "full-pull" | "incremental";
 /**
+* Incremental-ingest cursor (plan 136): the monotonic watermark column plus the
+* watermark-parameterized pull query. `column` names the field in the pulled rows
+* whose max becomes the next watermark (e.g. `"updated_at"`). `query` is a second
+* SQL that returns only rows changed since the watermark — the watermark binds as
+* the parameter AFTER `tenantBy`'s params (e.g. Postgres
+* `... WHERE tenant_id = $1 AND updated_at >= $2 ORDER BY updated_at`). Prefer `>=`
+* with the idempotent upsert apply so rows sharing the boundary timestamp are never
+* skipped (re-pulling them is a no-op).
+*/
+interface ExternalSourceCursor {
+  /** The monotonic watermark column in the pulled rows; its max advances the stored watermark. */
+  column: string;
+  /** The incremental pull SQL. `tenantBy`'s params bind first, then the watermark as the trailing param. */
+  query: string;
+}
+/**
 * 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
@@ -48,19 +73,33 @@ interface ExternalSourceDefinition {
   binding: string;
   /** Project the materialized rows to these columns (passed to the membership diff). Omit ⇒ the full mapped document. */
   columns?: ReadonlyArray<string>;
+  /** **Required for `mode: "incremental"`**: the watermark column + watermark-parameterized pull query (plan 136). Rejected on a `"full-pull"` source. */
+  cursor?: ExternalSourceCursor;
   /** 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"`. */
+  /** Delete-detection mode. `"full-pull"` (the default) diffs the whole membership; `"incremental"` pulls past a `cursor` watermark. */
   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. */
+  /**
+  * **Incremental delete-visibility (plan 136)**: run a full-pull sweep at most
+  * this often (millis) to GC upstream deletes an incremental slice can't see.
+  * One of `reconcileEveryMs` / `softDeleteColumn` is required for incremental;
+  * rejected on a `"full-pull"` source.
+  */
   reconcileEveryMs?: number;
   /** Poll cadence, or `"manual"`. Omit ⇒ the runtime's size-scaled default. */
   refresh?: ExternalSourceRefresh;
   /**
+  * **Incremental delete-visibility (plan 136)**: the upstream soft-delete
+  * tombstone column (e.g. `"deleted_at"`). When set, the incremental pull must
+  * return tombstoned rows and the ingest turns each into a local delete — an
+  * alternative to `reconcileEveryMs`. Rejected on a `"full-pull"` source.
+  */
+  softDeleteColumn?: string;
+  /**
   * **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
@@ -1293,4 +1332,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 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, type X402ProcedureConfig, anyApi };
+export { type ActionCtx, type AggregateIndexDefinition, type AggregateOp, type AnyApi, type ArgsValidator, type AuthState, type CachePurge, type DatabaseReader, type DatabaseWriter, type DurableObjectJurisdiction, type ExternalSourceCursor, 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, type X402ProcedureConfig, anyApi };

package/dist/types.d.ts

@@ -28,13 +28,38 @@ 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.
+* Delete-detection mode for external-source ingest (plan 077 / 136).
+*
+* `"full-pull"` (the default) reads the **whole** tenant membership each tick and
+* diffs it, so it observes upstream deletes for free — but costs a full read per tick
+* (the Phase-0 bench put the ceiling at ~10k rows).
+*
+* `"incremental"` pulls **only rows past a durable watermark** (`cursor`), cheap for
+* large low-churn tables above the full-pull cap. Because an absent row then means
+* "unchanged", not "deleted", incremental requires a delete-visibility path: either a
+* `reconcileEveryMs` periodic full-pull sweep, or a `softDeleteColumn` whose
+* tombstones the pull returns. `defineSchema` throws (and the
+* `external_source_incremental_no_delete_path` advisor lint fails the build) when an
+* incremental source declares neither.
 */
 type ExternalSourceMode = "full-pull" | "incremental";
 /**
+* Incremental-ingest cursor (plan 136): the monotonic watermark column plus the
+* watermark-parameterized pull query. `column` names the field in the pulled rows
+* whose max becomes the next watermark (e.g. `"updated_at"`). `query` is a second
+* SQL that returns only rows changed since the watermark — the watermark binds as
+* the parameter AFTER `tenantBy`'s params (e.g. Postgres
+* `... WHERE tenant_id = $1 AND updated_at >= $2 ORDER BY updated_at`). Prefer `>=`
+* with the idempotent upsert apply so rows sharing the boundary timestamp are never
+* skipped (re-pulling them is a no-op).
+*/
+interface ExternalSourceCursor {
+  /** The monotonic watermark column in the pulled rows; its max advances the stored watermark. */
+  column: string;
+  /** The incremental pull SQL. `tenantBy`'s params bind first, then the watermark as the trailing param. */
+  query: string;
+}
+/**
 * 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
@@ -48,19 +73,33 @@ interface ExternalSourceDefinition {
   binding: string;
   /** Project the materialized rows to these columns (passed to the membership diff). Omit ⇒ the full mapped document. */
   columns?: ReadonlyArray<string>;
+  /** **Required for `mode: "incremental"`**: the watermark column + watermark-parameterized pull query (plan 136). Rejected on a `"full-pull"` source. */
+  cursor?: ExternalSourceCursor;
   /** 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"`. */
+  /** Delete-detection mode. `"full-pull"` (the default) diffs the whole membership; `"incremental"` pulls past a `cursor` watermark. */
   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. */
+  /**
+  * **Incremental delete-visibility (plan 136)**: run a full-pull sweep at most
+  * this often (millis) to GC upstream deletes an incremental slice can't see.
+  * One of `reconcileEveryMs` / `softDeleteColumn` is required for incremental;
+  * rejected on a `"full-pull"` source.
+  */
   reconcileEveryMs?: number;
   /** Poll cadence, or `"manual"`. Omit ⇒ the runtime's size-scaled default. */
   refresh?: ExternalSourceRefresh;
   /**
+  * **Incremental delete-visibility (plan 136)**: the upstream soft-delete
+  * tombstone column (e.g. `"deleted_at"`). When set, the incremental pull must
+  * return tombstoned rows and the ingest turns each into a local delete — an
+  * alternative to `reconcileEveryMs`. Rejected on a `"full-pull"` source.
+  */
+  softDeleteColumn?: string;
+  /**
   * **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
@@ -1293,4 +1332,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 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, type X402ProcedureConfig, anyApi };
+export { type ActionCtx, type AggregateIndexDefinition, type AggregateOp, type AnyApi, type ArgsValidator, type AuthState, type CachePurge, type DatabaseReader, type DatabaseWriter, type DurableObjectJurisdiction, type ExternalSourceCursor, 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, type X402ProcedureConfig, anyApi };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/server",
-  "version": "1.0.0-alpha.24",
+  "version": "1.0.0-alpha.26",
   "description": "Server primitives for Lunora: defineSchema, defineTable, query, mutation, and action",
   "keywords": [
     "backend",
@@ -62,9 +62,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/errors": "1.0.0-alpha.4",
-    "@lunora/scheduler": "1.0.0-alpha.9",
-    "@lunora/values": "1.0.0-alpha.7",
+    "@lunora/errors": "1.0.0-alpha.5",
+    "@lunora/scheduler": "1.0.0-alpha.10",
+    "@lunora/values": "1.0.0-alpha.8",
     "drizzle-orm": "^0.45.2",
     "hono": "^4.12.28"
   },