@clivly/sdk 0.12.0 → 0.14.1

package/README.md

@@ -272,10 +272,16 @@ production runtimes.
 // Cloudflare Workers
 export default {
   scheduled: () => clivly.runScheduled(), // cron: one heartbeat + one sync
-  fetch: clivly.createClivlyHandler(),    // or drive via an uptime ping
+  fetch: clivly.createClivlyHandler(),    // the route Clivly Cloud POSTs to
 };
 ```
 
+**Only `POST` triggers a sync.** `HEAD` answers `204` and does no work — that
+is the liveness probe. `GET` still syncs but logs a deprecation warning, and a
+future release will refuse it with `405`, so point any cron or uptime check at
+`POST`. Set `CLIVLY_TRIGGER_REQUIRE_POST=true` to adopt that now and confirm
+nothing in your setup depends on `GET`.
+
 `runScheduled()` throws if a sync push fails, so a cron run is marked failed.
 `createClivlyHandler()` returns `200` when the triggered run finishes
 successfully and `500` otherwise, with `{ ok, runId, durationMs }` or
@@ -350,7 +356,8 @@ it, dashboard-authored objects are fetched and then skipped; nothing errors, and
 | Nothing connects, no error | You imported the config but never called an entry point | Call `start()` / `runScheduled()`, or add `clivlyVite(sdk)` |
 | `reason: "invalid_api_key"` | `CLIVLY_SECRET_KEY` missing, wrong, or revoked by a regeneration | Re-run `npx clivly login` |
 | Sync works once on serverless, then stops | `start()`'s `setInterval` cannot persist | Use `runScheduled()` or `createClivlyHandler()` |
-| Every cold start re-reads everything | The default cursor store is in-memory | Pass a persistent [`cursorStore`](#persisting-the-delta-cursor) |
+| Every run re-reads everything | The default cursor store is in-memory, which serverless discards between invocations | Pass [`kvCursorStore`](#persisting-the-delta-cursor) |
+| A cron stopped triggering syncs | Only `POST` triggers a sync | Change the caller to `POST` |
 | `401` on the tick route | Trigger secret differs between your app and Clivly | Redeploy with the current `CLIVLY_SYNC_TRIGGER_SECRET` |
 | An entity syncs nothing, silently | `source` keyed by entity key instead of CRM concept | Key it `contacts` / `companies` / `deals` / `custom` |
 | Rows sync on insert but never on edit | `cursorField` does not change on edit | Add an `updated_at` column and use it. `doctor()` warns about this |
@@ -372,35 +379,92 @@ failed `connect()` result into a throwable.
 
 Delta sync tracks a per-entity cursor so each run only pages rows changed since
 the last one. By default that cursor lives in memory — fine for a long-lived
-process, but **lost on every serverless cold start**, so a fresh isolate would
-re-page the whole entity.
+process, but **discarded between invocations on serverless**. Every delta run
+then starts from nothing and re-reads your entire source tables: a full sync,
+on every run, reported as a success. The SDK warns at startup when it detects a
+serverless runtime with no `cursorStore`, and `clivly status` flags it.
+
+Use the store the SDK ships. It works with any key-value client that has `get`
+and `put` — Workers KV, Upstash, node-redis:
 
 ```ts
+import { createClivlySDK, kvCursorStore } from "@clivly/sdk";
+
 const clivly = createClivlySDK({
   apiKey: process.env.CLIVLY_SECRET_KEY!,
   entities,
   source: { /* … */ },
-  cursorStore: {
-    // `SyncCursor` is { id: string; time: Date } — serialize `time` yourself.
-    get: async (entity) => {
-      const raw = await kv.get(`clivly:cursor:${entity}`);
-      return raw ? { id: raw.id, time: new Date(raw.time) } : null;
-    },
-    set: (entity, cursor) =>
-      kv.put(
-        `clivly:cursor:${entity}`,
-        cursor && { id: cursor.id, time: cursor.time.toISOString() }
-      ),
-  },
+  cursorStore: kvCursorStore(env.CLIVLY_CURSORS),
 });
 ```
 
+Writing your own is fine too, but mind the one trap: **`SyncCursor.time` is a
+`Date`**. A JSON round-trip turns it into a string, and the sync path then
+calls `.toISOString()` on it and throws. Serialize to ISO on the way out and
+parse back to a `Date` on the way in — which is exactly what `kvCursorStore`
+does for you:
+
+```ts
+cursorStore: {
+  get: async (entity) => {
+    const raw = await kv.get(`clivly:cursor:${entity}`);
+    if (!raw) return null;
+    const { id, time } = JSON.parse(raw);
+    return { id, time: new Date(time) }; // back to a Date
+  },
+  set: (entity, cursor) =>
+    kv.put(
+      `clivly:cursor:${entity}`,
+      cursor ? JSON.stringify({ id: cursor.id, time: cursor.time.toISOString() }) : ""
+    ),
+}
+```
+
+Return `null` rather than throwing on a missing or malformed value: the cost is
+one full re-read, where throwing would stop sync entirely.
+
+`memoryCursorStore()` is also exported, for tests and for long-lived hosts that
+want the default named explicitly.
+
 Delta sync is **at-least-once**: after a cold start with no persisted cursor,
 rows since the last push may be re-sent (the server dedupes by id) — it never
 silently skips rows. Use `sync({ mode: "full" })` when you need the server to
 reconcile deletions (archive-on-leave); a delta cannot tell absence from
 "unchanged".
 
+### Pushing a row the moment it is written
+
+Scheduled syncs pick new rows up eventually. To push one immediately (a signup,
+say), opt in with `sync: { instant: true }` and wrap the insert with
+`insertAndPush`. You create it once per mapped table, and it inserts,
+translates the row and pushes it. Without the opt-in, both helpers do nothing
+and the row arrives on the next delta sync instead. The `entity` argument is
+the key from your `entities` config. A push never throws: a failed push only
+logs a warning, and the next delta sync still delivers the row.
+
+```ts
+import { insertAndPush } from "clivly/drizzle";
+
+const insertUser = insertAndPush(clivly, db, schema.users, { entity: "user" });
+
+// In the signup handler. Pass `waitUntil` on Workers so the push outlives the response.
+const created = await insertUser(newUserValues, c.executionCtx.waitUntil.bind(c.executionCtx));
+```
+
+When a library performs the insert itself (an auth library's lifecycle hook,
+for example) there is no call to wrap. Re-read the row and translate it with
+`toColumnKeyedRow`, then push it:
+
+```ts
+import { toColumnKeyedRow } from "clivly/drizzle";
+
+await clivly.pushOne("user", toColumnKeyedRow(schema.users, row));
+```
+
+The translation matters. A Drizzle row is keyed by property name (`fullName`),
+but mappings and the cloud address columns by their database name
+(`full_name`), so an untranslated row pushes empty fields without any error.
+
 ### Sync ordering
 
 `runSync` pushes **companies first**, then contacts, then deals, then custom
@@ -418,9 +482,17 @@ membership**, each row carrying the join table's foreign-key column.
 { id: "u1", full_name: "Ada", email: "ada@acme.test", org_id: "globex" }
 ```
 
-This mirrors what the embedded model produces with `LEFT JOIN <join table>`, and
-it is what lets Clivly keep one CRM row per membership instead of collapsing the
-person onto whichever company happened to come first.
+This mirrors what the embedded model produces with `LEFT JOIN <join table>`.
+Clivly keeps Ada as **one contact** (identity is her `id`, not `id` + company)
+with **two memberships**, one per organisation. The contact list shows her once,
+as `Acme +1`, and both organisations' contact counts include her. Her primary
+organisation is the lowest company ref for a new contact, and it stays put
+while she still belongs to it.
+
+When she leaves one organisation, a **full** sync ends that membership and
+keeps the contact and her other memberships live. A delta sync never ends a
+membership, because a missing row may just be on the next page of the push.
+She is archived only when she leaves the source entirely.
 
 A person with no membership may omit the column entirely or send it as `null` —
 both are accepted. But if **no** pushed row carries the column, the push is
@@ -450,13 +522,14 @@ is honoured. Other `4xx` responses return immediately.
 | `entities` | `ClivlyEntitiesConfig` | — | From `defineClivlyConfig({ entities })` |
 | `schema` | `DiscoveredTable[]` | — | Use `discoverFromDrizzle(schema)`. It reports keys, types, nullability and FK edges alongside column names; [derived objects](#derived-objects) cannot be authored without them, so prefer it over a hand-written array |
 | `source` | `{ contacts, companies?, deals?, custom? }` | — | Keyed by CRM concept. `contacts` is required when `source` is present |
-| `cursorStore` | `CursorStore` | in-memory | Persist on serverless |
+| `cursorStore` | `CursorStore` | in-memory | **Required on serverless** — `kvCursorStore(kv)` |
 | `heartbeatIntervalMs` | `number` | `60000` | HTTP presence cadence and default sync cadence; paused when opt-in WebSocket presence is ready |
 | `presence.transport` | `"http" \\| "websocket"` | `"http"` | WebSocket is for long-lived Node hosts; HTTP resumes during reconnect/fallback |
 | `presence.deploymentId` | `string` | platform-derived | Optional release identity for a WebSocket deployment |
 | `sync.onBoot` | `boolean` | `true` | Only affects `start()` |
 | `sync.intervalMs` | `number` | `heartbeatIntervalMs` | |
 | `sync.batchSize` | `number` | `500` | Rows per page |
+| `sync.instant` | `boolean` | `false` | Lets `pushOne()` / `insertAndPush()` push a single row immediately; see [Pushing a row the moment it is written](#pushing-a-row-the-moment-it-is-written) |
 | `retry.maxAttempts` / `retry.baseDelayMs` | `number` | `3` / `500` | |
 | `syncTrigger.path` / `.url` / `.secret` | `string` | — | See above |
 | `verifyToken` | `string` | — | For `createAuthVerifyHandler`. **Nothing calls that endpoint today** |
@@ -518,7 +591,7 @@ rejected key and a dead network all mean the question went unanswered.
 | From `clivly` | From `@clivly/sdk` | Contents |
 | --- | --- | --- |
 | `clivly/sdk` | `@clivly/sdk` | `createClivlySDK`, `defineClivlyConfig`, `createChatSessionHandler`, error classes, all types |
-| `clivly/drizzle` | `@clivly/sdk/drizzle` | `fromDrizzle`, `discoverFromDrizzle`, `drizzleIntrospector`, `buildUniqueConstraints` |
+| `clivly/drizzle` | `@clivly/sdk/drizzle` | `fromDrizzle`, `discoverFromDrizzle`, `drizzleIntrospector`, `buildUniqueConstraints`, `insertAndPush`, `toColumnKeyedRow` |
 | `clivly/vite` | `@clivly/sdk/vite` | `clivlyVite` |
 | — | `@clivly/sdk/chat-session` | `createChatSessionHandler` (also on the root) |
 

package/dist/chat-session.d.cts

@@ -1,4 +1,4 @@
-import { c as CreateChatSessionHandlerOptions } from "./types-CvhxV-IX.cjs";
+import { c as CreateChatSessionHandlerOptions } from "./types-DK8mqmkV.cjs";
 //#region src/chat-session.d.ts
 export declare function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl, fetchImpl, resolveUser }: CreateChatSessionHandlerOptions): (request: Request) => Promise<Response>;
 //#endregion

package/dist/chat-session.d.mts

@@ -1,4 +1,4 @@
-import { c as CreateChatSessionHandlerOptions } from "./types-CvhxV-IX.mjs";
+import { c as CreateChatSessionHandlerOptions } from "./types-DK8mqmkV.mjs";
 //#region src/chat-session.d.ts
 export declare function createChatSessionHandler({ allowedOrigins, apiKey, apiUrl, fetchImpl, resolveUser }: CreateChatSessionHandlerOptions): (request: Request) => Promise<Response>;
 //#endregion

package/dist/drizzle.cjs

@@ -163,6 +163,69 @@ function fromDrizzle(db, table, opts) {
 	return source;
 }
 /**
+* Insert a row into a mapped Drizzle table and push it to Clivly immediately
+* — the "one call does both" instant-push API (see
+* docs/reviews/2026-09-19-near-real-time-sync-plan.md, question 1). Returns
+* only after the write completes; the push itself is fire-and-forget (see
+* `pushOne`), so this resolves at the same time a plain `db.insert(...)`
+* would.
+*
+* Created once per mapped table, mirroring `fromDrizzle`'s own convention —
+* no per-call table-to-entity lookup, so a table two entities share (e.g.
+* `user` for both `user` and `organizationOwner`) is never ambiguous:
+* ```ts
+* const insertUser = insertAndPush(clivly, db, schema.user, { entity: "user" });
+* // in the signup handler:
+* const created = await insertUser(newUserValues, c.executionCtx);
+* ```
+*
+* `waitUntil`, when provided (Hono exposes it as `c.executionCtx.waitUntil`),
+* extends the request's lifetime past the response so the push survives on
+* Cloudflare Workers and similar runtimes, which otherwise kill background
+* work the instant a response is sent. Omit it on a long-lived process where
+* nothing tears the request down early.
+*
+* Table property keys are translated to real database column names before
+* the push — the same translation `fromDrizzle` performs on `fetchPage` rows
+* — because a raw `.returning()` result is keyed by Drizzle property name
+* (`fullName`), and every consumer downstream of a push (the fieldMap, the
+* cloud's ingest) addresses columns by their database name (`full_name`).
+* Skipping this would silently push empty fields with no error anywhere.
+*/
+/**
+* Translate a Drizzle-property-keyed row (e.g. a `.returning()` result, or a
+* plain unprojected `select()`) to real database column names — the same
+* translation `fromDrizzle` performs on `fetchPage` rows. Every consumer
+* downstream of a push (the fieldMap, the cloud's ingest) addresses columns
+* by their database name (`full_name`), not the property name (`fullName`);
+* skipping this would silently push empty fields with no error anywhere.
+*
+* Exported so a host can build the same translated row from a table it read
+* some other way — e.g. re-querying a row inside an auth library's own
+* lifecycle hook, where there is no `insertAndPush` call site to wrap
+* because the library performs the insert internally.
+*/
+function toColumnKeyedRow(table, row) {
+	const columns = (0, drizzle_orm.getTableColumns)(table);
+	const columnNameByPropertyKey = /* @__PURE__ */ new Map();
+	for (const [propertyKey, column] of Object.entries(columns)) columnNameByPropertyKey.set(propertyKey, column.name);
+	const out = {};
+	for (const [propertyKey, value] of Object.entries(row)) out[columnNameByPropertyKey.get(propertyKey) ?? propertyKey] = value;
+	return out;
+}
+function insertAndPush(clivly, db, table, opts) {
+	const insertableDb = db;
+	return async (values, waitUntil) => {
+		const [created] = await insertableDb.insert(table).values(values).returning();
+		if (!created) throw new Error(`insertAndPush: insert into "${(0, drizzle_orm.getTableName)(table)}" returned no row.`);
+		const row = toColumnKeyedRow(table, created);
+		const pushed = clivly.pushOne(opts.entity, row);
+		if (waitUntil) waitUntil(pushed);
+		else await pushed;
+		return created;
+	};
+}
+/**
 * Build a `NamespaceIntrospector` from any Drizzle client that exposes
 * `.execute()`. Reads `information_schema` in the connection's default schema
 * (`current_schema()`), so it reports exactly the tables the app can reach.
@@ -207,3 +270,5 @@ Object.defineProperty(exports, "discoverFromDrizzle", {
 exports.drizzleIntrospector = drizzleIntrospector;
 exports.fromDrizzle = fromDrizzle;
 exports.fromDrizzleProjection = fromDrizzleProjection;
+exports.insertAndPush = insertAndPush;
+exports.toColumnKeyedRow = toColumnKeyedRow;

package/dist/drizzle.d.cts

@@ -1,4 +1,4 @@
-import { _ as SyncSource, y as NamespaceIntrospector } from "./types-CvhxV-IX.cjs";
+import { _ as SyncSource, y as NamespaceIntrospector } from "./types-DK8mqmkV.cjs";
 import { ProjectionMapping, ProjectionRef } from "@clivly/core";
 import { Table } from "drizzle-orm";
 import { buildUniqueConstraints, discoverFromDrizzle } from "@clivly/core/drizzle";
@@ -115,6 +115,56 @@ export declare function fromDrizzle(db: DrizzleDb, table: Table, opts: FromDrizz
   objectType: string;
 };
 export declare function fromDrizzle(db: DrizzleDb, table: Table, opts: FromDrizzleOptions): SyncSource;
+interface PushOneCapable {
+  pushOne(entityKey: string, row: Record<string, unknown>): Promise<void>;
+}
+/**
+ * Insert a row into a mapped Drizzle table and push it to Clivly immediately
+ * — the "one call does both" instant-push API (see
+ * docs/reviews/2026-09-19-near-real-time-sync-plan.md, question 1). Returns
+ * only after the write completes; the push itself is fire-and-forget (see
+ * `pushOne`), so this resolves at the same time a plain `db.insert(...)`
+ * would.
+ *
+ * Created once per mapped table, mirroring `fromDrizzle`'s own convention —
+ * no per-call table-to-entity lookup, so a table two entities share (e.g.
+ * `user` for both `user` and `organizationOwner`) is never ambiguous:
+ * ```ts
+ * const insertUser = insertAndPush(clivly, db, schema.user, { entity: "user" });
+ * // in the signup handler:
+ * const created = await insertUser(newUserValues, c.executionCtx);
+ * ```
+ *
+ * `waitUntil`, when provided (Hono exposes it as `c.executionCtx.waitUntil`),
+ * extends the request's lifetime past the response so the push survives on
+ * Cloudflare Workers and similar runtimes, which otherwise kill background
+ * work the instant a response is sent. Omit it on a long-lived process where
+ * nothing tears the request down early.
+ *
+ * Table property keys are translated to real database column names before
+ * the push — the same translation `fromDrizzle` performs on `fetchPage` rows
+ * — because a raw `.returning()` result is keyed by Drizzle property name
+ * (`fullName`), and every consumer downstream of a push (the fieldMap, the
+ * cloud's ingest) addresses columns by their database name (`full_name`).
+ * Skipping this would silently push empty fields with no error anywhere.
+ */
+/**
+ * Translate a Drizzle-property-keyed row (e.g. a `.returning()` result, or a
+ * plain unprojected `select()`) to real database column names — the same
+ * translation `fromDrizzle` performs on `fetchPage` rows. Every consumer
+ * downstream of a push (the fieldMap, the cloud's ingest) addresses columns
+ * by their database name (`full_name`), not the property name (`fullName`);
+ * skipping this would silently push empty fields with no error anywhere.
+ *
+ * Exported so a host can build the same translated row from a table it read
+ * some other way — e.g. re-querying a row inside an auth library's own
+ * lifecycle hook, where there is no `insertAndPush` call site to wrap
+ * because the library performs the insert internally.
+ */
+export declare function toColumnKeyedRow(table: Table, row: Record<string, unknown>): Record<string, unknown>;
+export declare function insertAndPush(clivly: PushOneCapable, db: unknown, table: Table, opts: {
+  entity: string;
+}): (values: Record<string, unknown>, waitUntil?: (promise: Promise<unknown>) => void) => Promise<Record<string, unknown>>;
 /**
  * Build a `NamespaceIntrospector` from any Drizzle client that exposes
  * `.execute()`. Reads `information_schema` in the connection's default schema

package/dist/drizzle.d.mts

@@ -1,4 +1,4 @@
-import { _ as SyncSource, y as NamespaceIntrospector } from "./types-CvhxV-IX.mjs";
+import { _ as SyncSource, y as NamespaceIntrospector } from "./types-DK8mqmkV.mjs";
 import { ProjectionMapping, ProjectionRef } from "@clivly/core";
 import { buildUniqueConstraints, discoverFromDrizzle } from "@clivly/core/drizzle";
 import { Table } from "drizzle-orm";
@@ -115,6 +115,56 @@ export declare function fromDrizzle(db: DrizzleDb, table: Table, opts: FromDrizz
   objectType: string;
 };
 export declare function fromDrizzle(db: DrizzleDb, table: Table, opts: FromDrizzleOptions): SyncSource;
+interface PushOneCapable {
+  pushOne(entityKey: string, row: Record<string, unknown>): Promise<void>;
+}
+/**
+ * Insert a row into a mapped Drizzle table and push it to Clivly immediately
+ * — the "one call does both" instant-push API (see
+ * docs/reviews/2026-09-19-near-real-time-sync-plan.md, question 1). Returns
+ * only after the write completes; the push itself is fire-and-forget (see
+ * `pushOne`), so this resolves at the same time a plain `db.insert(...)`
+ * would.
+ *
+ * Created once per mapped table, mirroring `fromDrizzle`'s own convention —
+ * no per-call table-to-entity lookup, so a table two entities share (e.g.
+ * `user` for both `user` and `organizationOwner`) is never ambiguous:
+ * ```ts
+ * const insertUser = insertAndPush(clivly, db, schema.user, { entity: "user" });
+ * // in the signup handler:
+ * const created = await insertUser(newUserValues, c.executionCtx);
+ * ```
+ *
+ * `waitUntil`, when provided (Hono exposes it as `c.executionCtx.waitUntil`),
+ * extends the request's lifetime past the response so the push survives on
+ * Cloudflare Workers and similar runtimes, which otherwise kill background
+ * work the instant a response is sent. Omit it on a long-lived process where
+ * nothing tears the request down early.
+ *
+ * Table property keys are translated to real database column names before
+ * the push — the same translation `fromDrizzle` performs on `fetchPage` rows
+ * — because a raw `.returning()` result is keyed by Drizzle property name
+ * (`fullName`), and every consumer downstream of a push (the fieldMap, the
+ * cloud's ingest) addresses columns by their database name (`full_name`).
+ * Skipping this would silently push empty fields with no error anywhere.
+ */
+/**
+ * Translate a Drizzle-property-keyed row (e.g. a `.returning()` result, or a
+ * plain unprojected `select()`) to real database column names — the same
+ * translation `fromDrizzle` performs on `fetchPage` rows. Every consumer
+ * downstream of a push (the fieldMap, the cloud's ingest) addresses columns
+ * by their database name (`full_name`), not the property name (`fullName`);
+ * skipping this would silently push empty fields with no error anywhere.
+ *
+ * Exported so a host can build the same translated row from a table it read
+ * some other way — e.g. re-querying a row inside an auth library's own
+ * lifecycle hook, where there is no `insertAndPush` call site to wrap
+ * because the library performs the insert internally.
+ */
+export declare function toColumnKeyedRow(table: Table, row: Record<string, unknown>): Record<string, unknown>;
+export declare function insertAndPush(clivly: PushOneCapable, db: unknown, table: Table, opts: {
+  entity: string;
+}): (values: Record<string, unknown>, waitUntil?: (promise: Promise<unknown>) => void) => Promise<Record<string, unknown>>;
 /**
  * Build a `NamespaceIntrospector` from any Drizzle client that exposes
  * `.execute()`. Reads `information_schema` in the connection's default schema

package/dist/drizzle.mjs

@@ -162,6 +162,69 @@ function fromDrizzle(db, table, opts) {
 	return source;
 }
 /**
+* Insert a row into a mapped Drizzle table and push it to Clivly immediately
+* — the "one call does both" instant-push API (see
+* docs/reviews/2026-09-19-near-real-time-sync-plan.md, question 1). Returns
+* only after the write completes; the push itself is fire-and-forget (see
+* `pushOne`), so this resolves at the same time a plain `db.insert(...)`
+* would.
+*
+* Created once per mapped table, mirroring `fromDrizzle`'s own convention —
+* no per-call table-to-entity lookup, so a table two entities share (e.g.
+* `user` for both `user` and `organizationOwner`) is never ambiguous:
+* ```ts
+* const insertUser = insertAndPush(clivly, db, schema.user, { entity: "user" });
+* // in the signup handler:
+* const created = await insertUser(newUserValues, c.executionCtx);
+* ```
+*
+* `waitUntil`, when provided (Hono exposes it as `c.executionCtx.waitUntil`),
+* extends the request's lifetime past the response so the push survives on
+* Cloudflare Workers and similar runtimes, which otherwise kill background
+* work the instant a response is sent. Omit it on a long-lived process where
+* nothing tears the request down early.
+*
+* Table property keys are translated to real database column names before
+* the push — the same translation `fromDrizzle` performs on `fetchPage` rows
+* — because a raw `.returning()` result is keyed by Drizzle property name
+* (`fullName`), and every consumer downstream of a push (the fieldMap, the
+* cloud's ingest) addresses columns by their database name (`full_name`).
+* Skipping this would silently push empty fields with no error anywhere.
+*/
+/**
+* Translate a Drizzle-property-keyed row (e.g. a `.returning()` result, or a
+* plain unprojected `select()`) to real database column names — the same
+* translation `fromDrizzle` performs on `fetchPage` rows. Every consumer
+* downstream of a push (the fieldMap, the cloud's ingest) addresses columns
+* by their database name (`full_name`), not the property name (`fullName`);
+* skipping this would silently push empty fields with no error anywhere.
+*
+* Exported so a host can build the same translated row from a table it read
+* some other way — e.g. re-querying a row inside an auth library's own
+* lifecycle hook, where there is no `insertAndPush` call site to wrap
+* because the library performs the insert internally.
+*/
+function toColumnKeyedRow(table, row) {
+	const columns = getTableColumns(table);
+	const columnNameByPropertyKey = /* @__PURE__ */ new Map();
+	for (const [propertyKey, column] of Object.entries(columns)) columnNameByPropertyKey.set(propertyKey, column.name);
+	const out = {};
+	for (const [propertyKey, value] of Object.entries(row)) out[columnNameByPropertyKey.get(propertyKey) ?? propertyKey] = value;
+	return out;
+}
+function insertAndPush(clivly, db, table, opts) {
+	const insertableDb = db;
+	return async (values, waitUntil) => {
+		const [created] = await insertableDb.insert(table).values(values).returning();
+		if (!created) throw new Error(`insertAndPush: insert into "${getTableName(table)}" returned no row.`);
+		const row = toColumnKeyedRow(table, created);
+		const pushed = clivly.pushOne(opts.entity, row);
+		if (waitUntil) waitUntil(pushed);
+		else await pushed;
+		return created;
+	};
+}
+/**
 * Build a `NamespaceIntrospector` from any Drizzle client that exposes
 * `.execute()`. Reads `information_schema` in the connection's default schema
 * (`current_schema()`), so it reports exactly the tables the app can reach.
@@ -191,4 +254,4 @@ function drizzleIntrospector(db) {
 	};
 }
 //#endregion
-export { buildUniqueConstraints, discoverFromDrizzle, drizzleIntrospector, fromDrizzle, fromDrizzleProjection };
+export { buildUniqueConstraints, discoverFromDrizzle, drizzleIntrospector, fromDrizzle, fromDrizzleProjection, insertAndPush, toColumnKeyedRow };

package/dist/index.cjs

@@ -701,6 +701,20 @@ function detectHostEnvironment(env, configured) {
 	return fromNodeEnv(env.NODE_ENV?.trim());
 }
 //#endregion
+//#region src/instant-push-support.ts
+/**
+* The fast rollback switch for instant push (see
+* docs/reviews/2026-09-19-near-real-time-sync-plan.md, question 5).
+*
+* A host-side env var, not a Clivly-Cloud-side toggle: it must keep working
+* even when Clivly Cloud is the thing misbehaving (e.g. its ingest endpoint
+* is what instant push is flooding), and it must take effect without a
+* redeploy — just an env var change and the next cold start.
+*/
+function isInstantPushDisabled(env) {
+	return env.CLIVLY_INSTANT_PUSH_DISABLED === "true";
+}
+//#endregion
 //#region src/presence-machine.ts
 const PRESENCE_BACKOFF_BASE_MS = 1e3;
 const PRESENCE_BACKOFF_MAX_MS = 3e4;
@@ -1379,6 +1393,51 @@ async function fullSyncSource(args) {
 	};
 }
 //#endregion
+//#region src/trigger-method.ts
+/** Host-side override, mirroring `CLIVLY_INSTANT_PUSH_DISABLED`. */
+const REQUIRE_POST_ENV_VAR = "CLIVLY_TRIGGER_REQUIRE_POST";
+const NON_POST_DEPRECATION_WARNING = `Clivly: this sync trigger was called with GET. It still ran the sync, but a future release will refuse any method except POST with a 405. Change the caller — your cron job or uptime check — to POST. To adopt the new behaviour now, set ${REQUIRE_POST_ENV_VAR}=true.`;
+const METHOD_NOT_ALLOWED = 405;
+const NO_CONTENT = 204;
+const OK = 200;
+/**
+* Resolve the phase. Only the exact strings `"true"` and `"false"` count —
+* anything else (unset, empty, `"1"`, `"TRUE"`) falls through to the default
+* rather than guessing, so a typo can never silently disable a guard.
+*/
+function enforcementEnabled(input) {
+	const override = input.env[REQUIRE_POST_ENV_VAR];
+	if (override === "true") return true;
+	if (override === "false") return false;
+	return input.enforceDefault;
+}
+function resolveTriggerMethod(input) {
+	const method = input.method.toUpperCase();
+	if (method === "POST") return {
+		runSync: true,
+		status: OK
+	};
+	if (method === "HEAD") return {
+		runSync: false,
+		status: NO_CONTENT
+	};
+	const refuse = {
+		body: {
+			error: `Method ${method} is not allowed on the Clivly sync trigger. Use POST.`,
+			ok: false
+		},
+		runSync: false,
+		status: METHOD_NOT_ALLOWED
+	};
+	if (method !== "GET") return refuse;
+	if (enforcementEnabled(input)) return refuse;
+	return {
+		runSync: true,
+		status: OK,
+		warn: NON_POST_DEPRECATION_WARNING
+	};
+}
+//#endregion
 //#region src/trigger-url.ts
 const SCHEME_REGEX = /^https?:\/\//;
 const INVALID_HOST_CHARS_REGEX = /[/\\@?#\s]/;
@@ -1570,7 +1629,7 @@ function buildSchema(config) {
 	});
 }
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-function createMemoryCursorStore() {
+function memoryCursorStore() {
 	const cursors = /* @__PURE__ */ new Map();
 	return {
 		get: (entity) => cursors.get(entity) ?? null,
@@ -1579,6 +1638,56 @@ function createMemoryCursorStore() {
 		}
 	};
 }
+/** Default key prefix for {@link kvCursorStore}. */
+const CURSOR_KEY_PREFIX = "clivly:cursor:";
+/**
+* A persistent `CursorStore` backed by any key-value store.
+*
+* Serverless runtimes discard memory between invocations, so without a
+* persisted cursor every `delta` sync starts from `null` and re-reads the
+* whole source table. That is invisible — the run succeeds — and bills like a
+* full sync forever.
+*
+* This exists because the hand-written version has a trap in it:
+* `SyncCursor.time` is a `Date`, which a JSON round-trip turns into a string,
+* and `fromDrizzle` then calls `since.time.toISOString()` on it. The cursor is
+* stored as an ISO string and parsed back to a `Date` here so no caller has to
+* remember that.
+*
+* ```ts
+* cursorStore: kvCursorStore(env.CLIVLY_CURSORS) // Workers KV binding
+* ```
+*
+* A malformed or partial stored value resolves to `null` rather than throwing:
+* the worst case is one full re-read, where throwing would wedge sync entirely.
+*/
+function kvCursorStore(kv, options) {
+	const prefix = options?.prefix ?? "clivly:cursor:";
+	const keyFor = (entity) => `${prefix}${entity}`;
+	return {
+		get: async (entity) => {
+			const raw = await kv.get(keyFor(entity));
+			if (!raw) return null;
+			try {
+				const parsed = JSON.parse(raw);
+				if (typeof parsed.id !== "string" || typeof parsed.time !== "string") return null;
+				const time = new Date(parsed.time);
+				return Number.isNaN(time.getTime()) ? null : {
+					id: parsed.id,
+					time
+				};
+			} catch {
+				return null;
+			}
+		},
+		set: async (entity, cursor) => {
+			await kv.put(keyFor(entity), cursor === null ? "" : JSON.stringify({
+				id: cursor.id,
+				time: cursor.time.toISOString()
+			}));
+		}
+	};
+}
 function isLikelyServerless() {
 	const runtime = globalThis;
 	if (runtime.navigator?.userAgent === "Cloudflare-Workers") return true;
@@ -1808,9 +1917,11 @@ function createClivlySDK(config) {
 	let presenceClient = null;
 	let httpHeartbeatActive = true;
 	const batchSize = config.sync?.batchSize ?? DEFAULT_BATCH_SIZE;
-	const cursorStore = config.cursorStore ?? createMemoryCursorStore();
+	if (serverless && !config.cursorStore) console.warn("Clivly: no `cursorStore` is configured and this looks like a serverless/edge runtime, where memory does not survive between invocations. Every `delta` sync will start from scratch and re-read your entire source tables — a full sync, on every run, billed as such. Pass a persistent store: `cursorStore: kvCursorStore(env.MY_KV)` (exported from `@clivly/sdk`). See https://clivly.com/docs/concepts/sync#cursor-stores");
+	const cursorStore = config.cursorStore ?? memoryCursorStore();
 	const fetcher = createFetcher(config.retry);
 	let warnedUnsignedTrigger = false;
+	let warnedNonPostTrigger = false;
 	const remoteProjections = createRemoteProjectionFetcher({
 		apiKey: config.apiKey,
 		apiUrl,
@@ -1972,6 +2083,28 @@ function createClivlySDK(config) {
 		lastPushFailure = null;
 		if (!await syncOne(resolved.source, resolved.path, "delta", resolved.objectType, runId, SAMPLE_BATCH_SIZE, SAMPLE_BATCH_SIZE, false)) throw pushFailureError(describePushFailure([resolved.source.entity]));
 	};
+	const pushOne = async (entityKey, row) => {
+		if (config.sync?.instant !== true) return;
+		if (isInstantPushDisabled(config.env ?? process.env)) return;
+		const resolved = resolveEntitySource(config, entityKey);
+		if (!resolved) {
+			console.warn(`Clivly instant push: no source is configured for entity "${entityKey}" — this row was not pushed. It will still sync on the next delta run once \`entities\` declares it.`);
+			return;
+		}
+		const path = CONCEPT_PATHS[resolved.expectedKey];
+		if (!path) return;
+		const push = createPush();
+		try {
+			if (!await push(path, {
+				source: pushSourceOf(resolved.source),
+				rows: [row],
+				mode: "delta",
+				...resolved.expectedKey === "custom" ? { objectType: resolved.source.objectType } : {}
+			})) console.warn(`Clivly instant push failed for "${entityKey}". This row will still sync on the next delta run.`);
+		} catch (error) {
+			console.warn(`Clivly instant push failed for "${entityKey}": ${error instanceof Error ? error.message : String(error)}. This row will still sync on the next delta run.`);
+		}
+	};
 	const describeSyncTrigger = () => ({
 		configured: config.syncTrigger?.url,
 		resolved: resolveTriggerUrl({
@@ -2214,8 +2347,45 @@ function createClivlySDK(config) {
 			return {};
 		}
 	};
+	/**
+	* The response to send instead of running a sync, or null to proceed.
+	*
+	* Split out of the handler so the method decision reads as one thing rather
+	* than three branches ahead of the request plumbing — the same shape as
+	* `triggerRequestAllowed` below.
+	*/
+	const refuseDisallowedMethod = (req) => {
+		const decision = resolveTriggerMethod({
+			enforceDefault: false,
+			env: config.env ?? process.env,
+			method: req.method
+		});
+		if (decision.warn && !warnedNonPostTrigger) {
+			warnedNonPostTrigger = true;
+			console.warn(decision.warn);
+		}
+		if (decision.runSync) return null;
+		return decision.body ? jsonResponse(decision.body, decision.status) : new Response(null, { status: decision.status });
+	};
+	/**
+	* Serve a preview request, or null when this payload is a real sync.
+	*
+	* Preview (T10) is a signed, ZERO-WRITE dry run: it returns ≤5 RAW source
+	* rows, slimmed to only the columns the draft maps or filters on and coerced
+	* to JSON scalars, which the cloud then projects through the same path as a
+	* real sync. It never syncs, never pushes, never writes a cursor and never
+	* ingests. Callers keep it inside their `try` so a malformed body or a
+	* throwing `fetchPage` degrades to the same graceful 500 as the sync paths.
+	*/
+	const handleIfPreview = async (payload) => {
+		if (payload.preview) return await handlePreviewRequest(config, payload.preview);
+		if (payload.previewProjection) return await handleProjectionPreviewRequest(config, payload.previewProjection);
+		return null;
+	};
 	const createClivlyHandler = () => async (req) => {
 		observedUrl = observedTriggerUrl(req) ?? observedUrl;
+		const refusal = refuseDisallowedMethod(req);
+		if (refusal) return refusal;
 		const rawBody = await req.text().catch(() => "");
 		if (!await triggerRequestAllowed(req, rawBody)) return jsonResponse({
 			ok: false,
@@ -2225,8 +2395,8 @@ function createClivlySDK(config) {
 		const runId = payload.runId ?? null;
 		const startedAt = Date.now();
 		try {
-			if (payload.preview) return await handlePreviewRequest(config, payload.preview);
-			if (payload.previewProjection) return await handleProjectionPreviewRequest(config, payload.previewProjection);
+			const previewResponse = await handleIfPreview(payload);
+			if (previewResponse) return previewResponse;
 			if (payload.sample) await runSampleSync(payload.sample.entityKey, payload.runId);
 			else await runScheduled({
 				mode: payload.mode,
@@ -2327,10 +2497,12 @@ function createClivlySDK(config) {
 		runScheduled,
 		createClivlyHandler,
 		sync: runSync,
-		createAuthVerifyHandler
+		createAuthVerifyHandler,
+		pushOne
 	};
 }
 //#endregion
+exports.CURSOR_KEY_PREFIX = CURSOR_KEY_PREFIX;
 exports.ClivlyAuthError = ClivlyAuthError;
 exports.ClivlyError = ClivlyError;
 exports.ClivlyNetworkError = ClivlyNetworkError;
@@ -2350,6 +2522,8 @@ Object.defineProperty(exports, "defineClivlyConfig", {
 	}
 });
 exports.isPlaceholderUrl = isPlaceholderUrl;
+exports.kvCursorStore = kvCursorStore;
+exports.memoryCursorStore = memoryCursorStore;
 Object.defineProperty(exports, "validateEntitiesConfig", {
 	enumerable: true,
 	get: function() {

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { a as ClivlySDK, c as CreateChatSessionHandlerOptions, d as DoctorCheck, f as DoctorReport, g as RemoteProjectionsDescription, h as EnsuredObjectTypeResult, i as ClivlyConnectResult, l as CursorStore, m as EnsuredMappingResult, n as ChatWidgetVisitor, o as ClivlySDKConfig, p as EnsureSchemaResult, r as ClivlyConnectReason, s as ClivlyUser, t as ChatSessionRequestBody, u as DiscoveredTable, v as SyncTriggerDescription } from "./types-CvhxV-IX.cjs";
+import { a as ClivlySDK, c as CreateChatSessionHandlerOptions, d as DoctorCheck, f as DoctorReport, g as RemoteProjectionsDescription, h as EnsuredObjectTypeResult, i as ClivlyConnectResult, l as CursorStore, m as EnsuredMappingResult, n as ChatWidgetVisitor, o as ClivlySDKConfig, p as EnsureSchemaResult, r as ClivlyConnectReason, s as ClivlyUser, t as ChatSessionRequestBody, u as DiscoveredTable, v as SyncTriggerDescription } from "./types-DK8mqmkV.cjs";
 import { createChatSessionHandler } from "./chat-session.cjs";
 import { ClivlyEntitiesConfig, ConfigValidationError, ConfigValidationResult, CustomObjectDeclaration, DiscoveredSchemaTable, customObjectDeclarations, defineClivlyConfig, validateEntitiesConfig } from "@clivly/core/entity-config";
 //#region src/trigger-url.d.ts
@@ -26,6 +26,38 @@ export declare class ClivlyRateLimitError extends ClivlyError {}
 export declare class ClivlyNetworkError extends ClivlyError {}
 //#endregion
 //#region src/index.d.ts
+export declare function memoryCursorStore(): CursorStore;
+/** The shape every key-value client shares: Workers KV, Upstash, node-redis. */
+export interface CursorKV {
+  get(key: string): Promise<string | null> | string | null;
+  put(key: string, value: string): Promise<unknown> | unknown;
+}
+/** Default key prefix for {@link kvCursorStore}. */
+export declare const CURSOR_KEY_PREFIX = "clivly:cursor:";
+/**
+ * A persistent `CursorStore` backed by any key-value store.
+ *
+ * Serverless runtimes discard memory between invocations, so without a
+ * persisted cursor every `delta` sync starts from `null` and re-reads the
+ * whole source table. That is invisible — the run succeeds — and bills like a
+ * full sync forever.
+ *
+ * This exists because the hand-written version has a trap in it:
+ * `SyncCursor.time` is a `Date`, which a JSON round-trip turns into a string,
+ * and `fromDrizzle` then calls `since.time.toISOString()` on it. The cursor is
+ * stored as an ISO string and parsed back to a `Date` here so no caller has to
+ * remember that.
+ *
+ * ```ts
+ * cursorStore: kvCursorStore(env.CLIVLY_CURSORS) // Workers KV binding
+ * ```
+ *
+ * A malformed or partial stored value resolves to `null` rather than throwing:
+ * the worst case is one full re-read, where throwing would wedge sync entirely.
+ */
+export declare function kvCursorStore(kv: CursorKV, options?: {
+  prefix?: string;
+}): CursorStore;
 /**
  * Create the Clivly SDK. The implemented surface — heartbeat/discovery reporting
  * and the auth-verify handler — connects a developer's app to a running Clivly

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as ClivlySDK, c as CreateChatSessionHandlerOptions, d as DoctorCheck, f as DoctorReport, g as RemoteProjectionsDescription, h as EnsuredObjectTypeResult, i as ClivlyConnectResult, l as CursorStore, m as EnsuredMappingResult, n as ChatWidgetVisitor, o as ClivlySDKConfig, p as EnsureSchemaResult, r as ClivlyConnectReason, s as ClivlyUser, t as ChatSessionRequestBody, u as DiscoveredTable, v as SyncTriggerDescription } from "./types-CvhxV-IX.mjs";
+import { a as ClivlySDK, c as CreateChatSessionHandlerOptions, d as DoctorCheck, f as DoctorReport, g as RemoteProjectionsDescription, h as EnsuredObjectTypeResult, i as ClivlyConnectResult, l as CursorStore, m as EnsuredMappingResult, n as ChatWidgetVisitor, o as ClivlySDKConfig, p as EnsureSchemaResult, r as ClivlyConnectReason, s as ClivlyUser, t as ChatSessionRequestBody, u as DiscoveredTable, v as SyncTriggerDescription } from "./types-DK8mqmkV.mjs";
 import { createChatSessionHandler } from "./chat-session.mjs";
 import { ClivlyEntitiesConfig, ConfigValidationError, ConfigValidationResult, CustomObjectDeclaration, DiscoveredSchemaTable, customObjectDeclarations, defineClivlyConfig, validateEntitiesConfig } from "@clivly/core/entity-config";
 //#region src/trigger-url.d.ts
@@ -26,6 +26,38 @@ export declare class ClivlyRateLimitError extends ClivlyError {}
 export declare class ClivlyNetworkError extends ClivlyError {}
 //#endregion
 //#region src/index.d.ts
+export declare function memoryCursorStore(): CursorStore;
+/** The shape every key-value client shares: Workers KV, Upstash, node-redis. */
+export interface CursorKV {
+  get(key: string): Promise<string | null> | string | null;
+  put(key: string, value: string): Promise<unknown> | unknown;
+}
+/** Default key prefix for {@link kvCursorStore}. */
+export declare const CURSOR_KEY_PREFIX = "clivly:cursor:";
+/**
+ * A persistent `CursorStore` backed by any key-value store.
+ *
+ * Serverless runtimes discard memory between invocations, so without a
+ * persisted cursor every `delta` sync starts from `null` and re-reads the
+ * whole source table. That is invisible — the run succeeds — and bills like a
+ * full sync forever.
+ *
+ * This exists because the hand-written version has a trap in it:
+ * `SyncCursor.time` is a `Date`, which a JSON round-trip turns into a string,
+ * and `fromDrizzle` then calls `since.time.toISOString()` on it. The cursor is
+ * stored as an ISO string and parsed back to a `Date` here so no caller has to
+ * remember that.
+ *
+ * ```ts
+ * cursorStore: kvCursorStore(env.CLIVLY_CURSORS) // Workers KV binding
+ * ```
+ *
+ * A malformed or partial stored value resolves to `null` rather than throwing:
+ * the worst case is one full re-read, where throwing would wedge sync entirely.
+ */
+export declare function kvCursorStore(kv: CursorKV, options?: {
+  prefix?: string;
+}): CursorStore;
 /**
  * Create the Clivly SDK. The implemented surface — heartbeat/discovery reporting
  * and the auth-verify handler — connects a developer's app to a running Clivly

package/dist/index.mjs

@@ -700,6 +700,20 @@ function detectHostEnvironment(env, configured) {
 	return fromNodeEnv(env.NODE_ENV?.trim());
 }
 //#endregion
+//#region src/instant-push-support.ts
+/**
+* The fast rollback switch for instant push (see
+* docs/reviews/2026-09-19-near-real-time-sync-plan.md, question 5).
+*
+* A host-side env var, not a Clivly-Cloud-side toggle: it must keep working
+* even when Clivly Cloud is the thing misbehaving (e.g. its ingest endpoint
+* is what instant push is flooding), and it must take effect without a
+* redeploy — just an env var change and the next cold start.
+*/
+function isInstantPushDisabled(env) {
+	return env.CLIVLY_INSTANT_PUSH_DISABLED === "true";
+}
+//#endregion
 //#region src/presence-machine.ts
 const PRESENCE_BACKOFF_BASE_MS = 1e3;
 const PRESENCE_BACKOFF_MAX_MS = 3e4;
@@ -1378,6 +1392,51 @@ async function fullSyncSource(args) {
 	};
 }
 //#endregion
+//#region src/trigger-method.ts
+/** Host-side override, mirroring `CLIVLY_INSTANT_PUSH_DISABLED`. */
+const REQUIRE_POST_ENV_VAR = "CLIVLY_TRIGGER_REQUIRE_POST";
+const NON_POST_DEPRECATION_WARNING = `Clivly: this sync trigger was called with GET. It still ran the sync, but a future release will refuse any method except POST with a 405. Change the caller — your cron job or uptime check — to POST. To adopt the new behaviour now, set ${REQUIRE_POST_ENV_VAR}=true.`;
+const METHOD_NOT_ALLOWED = 405;
+const NO_CONTENT = 204;
+const OK = 200;
+/**
+* Resolve the phase. Only the exact strings `"true"` and `"false"` count —
+* anything else (unset, empty, `"1"`, `"TRUE"`) falls through to the default
+* rather than guessing, so a typo can never silently disable a guard.
+*/
+function enforcementEnabled(input) {
+	const override = input.env[REQUIRE_POST_ENV_VAR];
+	if (override === "true") return true;
+	if (override === "false") return false;
+	return input.enforceDefault;
+}
+function resolveTriggerMethod(input) {
+	const method = input.method.toUpperCase();
+	if (method === "POST") return {
+		runSync: true,
+		status: OK
+	};
+	if (method === "HEAD") return {
+		runSync: false,
+		status: NO_CONTENT
+	};
+	const refuse = {
+		body: {
+			error: `Method ${method} is not allowed on the Clivly sync trigger. Use POST.`,
+			ok: false
+		},
+		runSync: false,
+		status: METHOD_NOT_ALLOWED
+	};
+	if (method !== "GET") return refuse;
+	if (enforcementEnabled(input)) return refuse;
+	return {
+		runSync: true,
+		status: OK,
+		warn: NON_POST_DEPRECATION_WARNING
+	};
+}
+//#endregion
 //#region src/trigger-url.ts
 const SCHEME_REGEX = /^https?:\/\//;
 const INVALID_HOST_CHARS_REGEX = /[/\\@?#\s]/;
@@ -1569,7 +1628,7 @@ function buildSchema(config) {
 	});
 }
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-function createMemoryCursorStore() {
+function memoryCursorStore() {
 	const cursors = /* @__PURE__ */ new Map();
 	return {
 		get: (entity) => cursors.get(entity) ?? null,
@@ -1578,6 +1637,56 @@ function createMemoryCursorStore() {
 		}
 	};
 }
+/** Default key prefix for {@link kvCursorStore}. */
+const CURSOR_KEY_PREFIX = "clivly:cursor:";
+/**
+* A persistent `CursorStore` backed by any key-value store.
+*
+* Serverless runtimes discard memory between invocations, so without a
+* persisted cursor every `delta` sync starts from `null` and re-reads the
+* whole source table. That is invisible — the run succeeds — and bills like a
+* full sync forever.
+*
+* This exists because the hand-written version has a trap in it:
+* `SyncCursor.time` is a `Date`, which a JSON round-trip turns into a string,
+* and `fromDrizzle` then calls `since.time.toISOString()` on it. The cursor is
+* stored as an ISO string and parsed back to a `Date` here so no caller has to
+* remember that.
+*
+* ```ts
+* cursorStore: kvCursorStore(env.CLIVLY_CURSORS) // Workers KV binding
+* ```
+*
+* A malformed or partial stored value resolves to `null` rather than throwing:
+* the worst case is one full re-read, where throwing would wedge sync entirely.
+*/
+function kvCursorStore(kv, options) {
+	const prefix = options?.prefix ?? "clivly:cursor:";
+	const keyFor = (entity) => `${prefix}${entity}`;
+	return {
+		get: async (entity) => {
+			const raw = await kv.get(keyFor(entity));
+			if (!raw) return null;
+			try {
+				const parsed = JSON.parse(raw);
+				if (typeof parsed.id !== "string" || typeof parsed.time !== "string") return null;
+				const time = new Date(parsed.time);
+				return Number.isNaN(time.getTime()) ? null : {
+					id: parsed.id,
+					time
+				};
+			} catch {
+				return null;
+			}
+		},
+		set: async (entity, cursor) => {
+			await kv.put(keyFor(entity), cursor === null ? "" : JSON.stringify({
+				id: cursor.id,
+				time: cursor.time.toISOString()
+			}));
+		}
+	};
+}
 function isLikelyServerless() {
 	const runtime = globalThis;
 	if (runtime.navigator?.userAgent === "Cloudflare-Workers") return true;
@@ -1807,9 +1916,11 @@ function createClivlySDK(config) {
 	let presenceClient = null;
 	let httpHeartbeatActive = true;
 	const batchSize = config.sync?.batchSize ?? DEFAULT_BATCH_SIZE;
-	const cursorStore = config.cursorStore ?? createMemoryCursorStore();
+	if (serverless && !config.cursorStore) console.warn("Clivly: no `cursorStore` is configured and this looks like a serverless/edge runtime, where memory does not survive between invocations. Every `delta` sync will start from scratch and re-read your entire source tables — a full sync, on every run, billed as such. Pass a persistent store: `cursorStore: kvCursorStore(env.MY_KV)` (exported from `@clivly/sdk`). See https://clivly.com/docs/concepts/sync#cursor-stores");
+	const cursorStore = config.cursorStore ?? memoryCursorStore();
 	const fetcher = createFetcher(config.retry);
 	let warnedUnsignedTrigger = false;
+	let warnedNonPostTrigger = false;
 	const remoteProjections = createRemoteProjectionFetcher({
 		apiKey: config.apiKey,
 		apiUrl,
@@ -1971,6 +2082,28 @@ function createClivlySDK(config) {
 		lastPushFailure = null;
 		if (!await syncOne(resolved.source, resolved.path, "delta", resolved.objectType, runId, SAMPLE_BATCH_SIZE, SAMPLE_BATCH_SIZE, false)) throw pushFailureError(describePushFailure([resolved.source.entity]));
 	};
+	const pushOne = async (entityKey, row) => {
+		if (config.sync?.instant !== true) return;
+		if (isInstantPushDisabled(config.env ?? process.env)) return;
+		const resolved = resolveEntitySource(config, entityKey);
+		if (!resolved) {
+			console.warn(`Clivly instant push: no source is configured for entity "${entityKey}" — this row was not pushed. It will still sync on the next delta run once \`entities\` declares it.`);
+			return;
+		}
+		const path = CONCEPT_PATHS[resolved.expectedKey];
+		if (!path) return;
+		const push = createPush();
+		try {
+			if (!await push(path, {
+				source: pushSourceOf(resolved.source),
+				rows: [row],
+				mode: "delta",
+				...resolved.expectedKey === "custom" ? { objectType: resolved.source.objectType } : {}
+			})) console.warn(`Clivly instant push failed for "${entityKey}". This row will still sync on the next delta run.`);
+		} catch (error) {
+			console.warn(`Clivly instant push failed for "${entityKey}": ${error instanceof Error ? error.message : String(error)}. This row will still sync on the next delta run.`);
+		}
+	};
 	const describeSyncTrigger = () => ({
 		configured: config.syncTrigger?.url,
 		resolved: resolveTriggerUrl({
@@ -2213,8 +2346,45 @@ function createClivlySDK(config) {
 			return {};
 		}
 	};
+	/**
+	* The response to send instead of running a sync, or null to proceed.
+	*
+	* Split out of the handler so the method decision reads as one thing rather
+	* than three branches ahead of the request plumbing — the same shape as
+	* `triggerRequestAllowed` below.
+	*/
+	const refuseDisallowedMethod = (req) => {
+		const decision = resolveTriggerMethod({
+			enforceDefault: false,
+			env: config.env ?? process.env,
+			method: req.method
+		});
+		if (decision.warn && !warnedNonPostTrigger) {
+			warnedNonPostTrigger = true;
+			console.warn(decision.warn);
+		}
+		if (decision.runSync) return null;
+		return decision.body ? jsonResponse(decision.body, decision.status) : new Response(null, { status: decision.status });
+	};
+	/**
+	* Serve a preview request, or null when this payload is a real sync.
+	*
+	* Preview (T10) is a signed, ZERO-WRITE dry run: it returns ≤5 RAW source
+	* rows, slimmed to only the columns the draft maps or filters on and coerced
+	* to JSON scalars, which the cloud then projects through the same path as a
+	* real sync. It never syncs, never pushes, never writes a cursor and never
+	* ingests. Callers keep it inside their `try` so a malformed body or a
+	* throwing `fetchPage` degrades to the same graceful 500 as the sync paths.
+	*/
+	const handleIfPreview = async (payload) => {
+		if (payload.preview) return await handlePreviewRequest(config, payload.preview);
+		if (payload.previewProjection) return await handleProjectionPreviewRequest(config, payload.previewProjection);
+		return null;
+	};
 	const createClivlyHandler = () => async (req) => {
 		observedUrl = observedTriggerUrl(req) ?? observedUrl;
+		const refusal = refuseDisallowedMethod(req);
+		if (refusal) return refusal;
 		const rawBody = await req.text().catch(() => "");
 		if (!await triggerRequestAllowed(req, rawBody)) return jsonResponse({
 			ok: false,
@@ -2224,8 +2394,8 @@ function createClivlySDK(config) {
 		const runId = payload.runId ?? null;
 		const startedAt = Date.now();
 		try {
-			if (payload.preview) return await handlePreviewRequest(config, payload.preview);
-			if (payload.previewProjection) return await handleProjectionPreviewRequest(config, payload.previewProjection);
+			const previewResponse = await handleIfPreview(payload);
+			if (previewResponse) return previewResponse;
 			if (payload.sample) await runSampleSync(payload.sample.entityKey, payload.runId);
 			else await runScheduled({
 				mode: payload.mode,
@@ -2326,8 +2496,9 @@ function createClivlySDK(config) {
 		runScheduled,
 		createClivlyHandler,
 		sync: runSync,
-		createAuthVerifyHandler
+		createAuthVerifyHandler,
+		pushOne
 	};
 }
 //#endregion
-export { ClivlyAuthError, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, createChatSessionHandler, createClivlySDK, customObjectDeclarations, defineClivlyConfig, isPlaceholderUrl, validateEntitiesConfig };
+export { CURSOR_KEY_PREFIX, ClivlyAuthError, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, createChatSessionHandler, createClivlySDK, customObjectDeclarations, defineClivlyConfig, isPlaceholderUrl, kvCursorStore, memoryCursorStore, validateEntitiesConfig };

package/dist/{types-CvhxV-IX.d.cts → types-DK8mqmkV.d.cts}

@@ -208,6 +208,23 @@ interface ClivlySDKConfig {
      */
     intervalMs?: number;
     batchSize?: number;
+    /**
+     * Opt into `pushOne()`/`insertAndPush()` pushing a single changed row to
+     * Clivly immediately, instead of waiting for the next delta sync. Off by
+     * default: turning it on changes a write's async failure surface (a push
+     * can fail independently of the write that triggered it, swallowed and
+     * left for the next delta sync to catch), which an existing install
+     * upgrading to a newer `clivly` should opt into deliberately rather than
+     * inherit silently. Requires a real scheduled delta sync running
+     * underneath as the safety net for anything the instant push misses (a
+     * failed push, a raw SQL write, a bulk import) — see
+     * docs/reviews/2026-09-19-near-real-time-sync-plan.md.
+     *
+     * Can also be disabled at runtime without a redeploy via the
+     * `CLIVLY_INSTANT_PUSH_DISABLED=true` environment variable — the fast
+     * rollback switch if this misbehaves in production.
+     */
+    instant?: boolean;
   };
   /**
    * The remote sync trigger: how Clivly Cloud asks this app to run a sync.
@@ -521,6 +538,31 @@ interface ClivlySDK {
    * own state.
    */
   ping(): Promise<ClivlyConnectResult>;
+  /**
+   * Push one row to Clivly immediately, instead of waiting for the next delta
+   * sync — the "instant" half of near-real-time sync (see
+   * docs/reviews/2026-09-19-near-real-time-sync-plan.md). No-ops unless
+   * `sync.instant` is set and `CLIVLY_INSTANT_PUSH_DISABLED` is unset.
+   *
+   * `entityKey` is a key of `config.entities.entities` (the same key
+   * `clivly.config.ts` declares the entity under), not a table name — an
+   * unresolvable key logs a warning and returns without throwing, the same
+   * fail-safe as every other call site here: a config mismatch never syncs
+   * the wrong thing, it just doesn't sync this row instantly (the safety-net
+   * delta sync still will).
+   *
+   * `row` must be keyed by the source table's real database column names
+   * (`full_name`, not `fullName`) — the same contract `fetchPage` rows
+   * satisfy. `insertAndPush` (from `clivly/drizzle`) performs this
+   * translation for you from a Drizzle table; calling `pushOne` directly with
+   * a raw Drizzle `.returning()` row will silently push empty fields.
+   *
+   * Never throws and never advances the delta cursor. Fire-and-forget by
+   * design: on Cloudflare Workers and similar runtimes, wrap the call in
+   * `ctx.waitUntil(...)` so it survives past the response, since nothing
+   * here blocks or awaits the caller's own write.
+   */
+  pushOne(entityKey: string, row: Record<string, unknown>): Promise<void>;
   /**
    * One-shot heartbeat + a single sync, with no keep-alive timers. The correct
    * entry point on serverless/edge (Workers, Vercel, Lambda), where `start()`'s

package/dist/{types-CvhxV-IX.d.mts → types-DK8mqmkV.d.mts}

@@ -208,6 +208,23 @@ interface ClivlySDKConfig {
      */
     intervalMs?: number;
     batchSize?: number;
+    /**
+     * Opt into `pushOne()`/`insertAndPush()` pushing a single changed row to
+     * Clivly immediately, instead of waiting for the next delta sync. Off by
+     * default: turning it on changes a write's async failure surface (a push
+     * can fail independently of the write that triggered it, swallowed and
+     * left for the next delta sync to catch), which an existing install
+     * upgrading to a newer `clivly` should opt into deliberately rather than
+     * inherit silently. Requires a real scheduled delta sync running
+     * underneath as the safety net for anything the instant push misses (a
+     * failed push, a raw SQL write, a bulk import) — see
+     * docs/reviews/2026-09-19-near-real-time-sync-plan.md.
+     *
+     * Can also be disabled at runtime without a redeploy via the
+     * `CLIVLY_INSTANT_PUSH_DISABLED=true` environment variable — the fast
+     * rollback switch if this misbehaves in production.
+     */
+    instant?: boolean;
   };
   /**
    * The remote sync trigger: how Clivly Cloud asks this app to run a sync.
@@ -521,6 +538,31 @@ interface ClivlySDK {
    * own state.
    */
   ping(): Promise<ClivlyConnectResult>;
+  /**
+   * Push one row to Clivly immediately, instead of waiting for the next delta
+   * sync — the "instant" half of near-real-time sync (see
+   * docs/reviews/2026-09-19-near-real-time-sync-plan.md). No-ops unless
+   * `sync.instant` is set and `CLIVLY_INSTANT_PUSH_DISABLED` is unset.
+   *
+   * `entityKey` is a key of `config.entities.entities` (the same key
+   * `clivly.config.ts` declares the entity under), not a table name — an
+   * unresolvable key logs a warning and returns without throwing, the same
+   * fail-safe as every other call site here: a config mismatch never syncs
+   * the wrong thing, it just doesn't sync this row instantly (the safety-net
+   * delta sync still will).
+   *
+   * `row` must be keyed by the source table's real database column names
+   * (`full_name`, not `fullName`) — the same contract `fetchPage` rows
+   * satisfy. `insertAndPush` (from `clivly/drizzle`) performs this
+   * translation for you from a Drizzle table; calling `pushOne` directly with
+   * a raw Drizzle `.returning()` row will silently push empty fields.
+   *
+   * Never throws and never advances the delta cursor. Fire-and-forget by
+   * design: on Cloudflare Workers and similar runtimes, wrap the call in
+   * `ctx.waitUntil(...)` so it survives past the response, since nothing
+   * here blocks or awaits the caller's own write.
+   */
+  pushOne(entityKey: string, row: Record<string, unknown>): Promise<void>;
   /**
    * One-shot heartbeat + a single sync, with no keep-alive timers. The correct
    * entry point on serverless/edge (Workers, Vercel, Lambda), where `start()`'s

package/dist/vite.d.cts

@@ -1,4 +1,4 @@
-import { a as ClivlySDK } from "./types-CvhxV-IX.cjs";
+import { a as ClivlySDK } from "./types-DK8mqmkV.cjs";
 import { Plugin } from "vite";
 //#region src/vite.d.ts
 export interface ClivlyViteOptions {

package/dist/vite.d.mts

@@ -1,4 +1,4 @@
-import { a as ClivlySDK } from "./types-CvhxV-IX.mjs";
+import { a as ClivlySDK } from "./types-DK8mqmkV.mjs";
 import { Plugin } from "vite";
 //#region src/vite.d.ts
 export interface ClivlyViteOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/sdk",
-  "version": "0.12.0",
+  "version": "0.14.1",
   "private": false,
   "description": "Clivly SDK — connect your app to Clivly Cloud (heartbeat, discovery, auth bridge).",
   "license": "MIT",
@@ -53,7 +53,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@clivly/core": "0.12.0"
+    "@clivly/core": "0.14.1"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4",