clivly 0.12.0 → 0.13.0

package/drizzle.cjs

@@ -164,6 +164,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.
@@ -198,3 +261,5 @@ exports.discoverFromDrizzle = require_drizzle.discoverFromDrizzle;
 exports.drizzleIntrospector = drizzleIntrospector;
 exports.fromDrizzle = fromDrizzle;
 exports.fromDrizzleProjection = fromDrizzleProjection;
+exports.insertAndPush = insertAndPush;
+exports.toColumnKeyedRow = toColumnKeyedRow;

package/drizzle.d.cts

@@ -1,6 +1,6 @@
 import { R as ProjectionMapping, z as ProjectionRef } from "./entity-config-ApnT5j3X.cjs";
 import { n as buildUniqueConstraints, r as discoverFromDrizzle } from "./drizzle-CiK37zJm.cjs";
-import { t as NamespaceIntrospector, v as SyncSource } from "./namespace-probe-C5RLl74M.cjs";
+import { t as NamespaceIntrospector, v as SyncSource } from "./namespace-probe-H7yWc0JV.cjs";
 import { Table } from "drizzle-orm";
 //#region ../sdk/src/drizzle-projection.d.ts
 /**
@@ -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/drizzle.d.mts

@@ -1,6 +1,6 @@
 import { R as ProjectionMapping, z as ProjectionRef } from "./entity-config-CKcj4-M_.mjs";
 import { n as buildUniqueConstraints, r as discoverFromDrizzle } from "./drizzle-ehVWLSrN.mjs";
-import { t as NamespaceIntrospector, v as SyncSource } from "./namespace-probe-CNQKSmxz.mjs";
+import { t as NamespaceIntrospector, v as SyncSource } from "./namespace-probe-DykR0kgh.mjs";
 import { Table } from "drizzle-orm";
 //#region ../sdk/src/drizzle-projection.d.ts
 /**
@@ -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/drizzle.mjs

@@ -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 = 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.
@@ -192,4 +255,4 @@ function drizzleIntrospector(db) {
 	};
 }
 //#endregion
-export { buildUniqueConstraints, discoverFromDrizzle, drizzleIntrospector, fromDrizzle, fromDrizzleProjection };
+export { buildUniqueConstraints, discoverFromDrizzle, drizzleIntrospector, fromDrizzle, fromDrizzleProjection, insertAndPush, toColumnKeyedRow };

package/index.cjs

@@ -3,7 +3,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_entity_config = require("./entity-config-BI4RYNKL.cjs");
 require("./mapping-score-CaB3F4Uu.cjs");
 const require_internal_entity_heuristics = require("./internal-entity-heuristics.cjs");
-const require_sdk = require("./sdk-BvGSxBQc.cjs");
+const require_sdk = require("./sdk-DKfKhJD_.cjs");
 let node_child_process = require("node:child_process");
 let node_fs = require("node:fs");
 let node_module = require("node:module");

package/index.mjs

@@ -2,7 +2,7 @@
 import { t as CANONICAL_FIELDS } from "./entity-config-Ccfb2IL9.mjs";
 import "./mapping-score-C68uAqGB.mjs";
 import { hasDefiningColumn, isFrameworkTable, matchesConcept, requiredFieldsFor, scoreFieldMap, scoreRelationships, suggestCursorField, toFieldMap } from "./internal-entity-heuristics.mjs";
-import { s as isPlaceholderUrl, t as createClivlySDK } from "./sdk-C-Pjxj2y.mjs";
+import { s as isPlaceholderUrl, t as createClivlySDK } from "./sdk-B-dp1tZN.mjs";
 import { createRequire } from "node:module";
 import { spawn } from "node:child_process";
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, watch, writeFileSync } from "node:fs";

package/{namespace-probe-CNQKSmxz.d.mts → namespace-probe-DykR0kgh.d.mts}

@@ -164,6 +164,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.
@@ -477,6 +494,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/{namespace-probe-C5RLl74M.d.cts → namespace-probe-H7yWc0JV.d.cts}

@@ -164,6 +164,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.
@@ -477,6 +494,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clivly",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "private": false,
   "type": "module",
   "description": "Clivly CLI — scaffold a CRM into your app (clivly init).",

package/{sdk-C-Pjxj2y.mjs → sdk-B-dp1tZN.mjs}

@@ -699,6 +699,20 @@ function detectHostEnvironment(env, configured) {
 	return fromNodeEnv(env.NODE_ENV?.trim());
 }
 //#endregion
+//#region ../sdk/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 ../sdk/src/presence-machine.ts
 const PRESENCE_BACKOFF_BASE_MS = 1e3;
 const PRESENCE_BACKOFF_MAX_MS = 3e4;
@@ -2090,6 +2104,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({
@@ -2445,7 +2481,8 @@ function createClivlySDK(config) {
 		runScheduled,
 		createClivlyHandler,
 		sync: runSync,
-		createAuthVerifyHandler
+		createAuthVerifyHandler,
+		pushOne
 	};
 }
 //#endregion

package/{sdk-BvGSxBQc.cjs → sdk-DKfKhJD_.cjs}

@@ -699,6 +699,20 @@ function detectHostEnvironment(env, configured) {
 	return fromNodeEnv(env.NODE_ENV?.trim());
 }
 //#endregion
+//#region ../sdk/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 ../sdk/src/presence-machine.ts
 const PRESENCE_BACKOFF_BASE_MS = 1e3;
 const PRESENCE_BACKOFF_MAX_MS = 3e4;
@@ -2090,6 +2104,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({
@@ -2445,7 +2481,8 @@ function createClivlySDK(config) {
 		runScheduled,
 		createClivlyHandler,
 		sync: runSync,
-		createAuthVerifyHandler
+		createAuthVerifyHandler,
+		pushOne
 	};
 }
 //#endregion

package/sdk.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_entity_config = require("./entity-config-BI4RYNKL.cjs");
-const require_sdk = require("./sdk-BvGSxBQc.cjs");
+const require_sdk = require("./sdk-DKfKhJD_.cjs");
 exports.ClivlyAuthError = require_sdk.ClivlyAuthError;
 exports.ClivlyError = require_sdk.ClivlyError;
 exports.ClivlyNetworkError = require_sdk.ClivlyNetworkError;

package/sdk.d.cts

@@ -1,5 +1,5 @@
 import { C as customObjectDeclarations, M as validateEntitiesConfig, a as ClivlyEntitiesConfig, f as CustomObjectDeclaration, l as ConfigValidationError, m as DiscoveredSchemaTable, u as ConfigValidationResult, w as defineClivlyConfig } from "./entity-config-ApnT5j3X.cjs";
-import { _ as RemoteProjectionsDescription, a as ClivlyConnectResult, c as ClivlyUser, d as DiscoveredTable, f as DoctorCheck, g as EnsuredObjectTypeResult, h as EnsuredMappingResult, i as ClivlyConnectReason, l as CreateChatSessionHandlerOptions, m as EnsureSchemaResult, n as ChatSessionRequestBody, o as ClivlySDK, p as DoctorReport, r as ChatWidgetVisitor, s as ClivlySDKConfig, u as CursorStore, y as SyncTriggerDescription } from "./namespace-probe-C5RLl74M.cjs";
+import { _ as RemoteProjectionsDescription, a as ClivlyConnectResult, c as ClivlyUser, d as DiscoveredTable, f as DoctorCheck, g as EnsuredObjectTypeResult, h as EnsuredMappingResult, i as ClivlyConnectReason, l as CreateChatSessionHandlerOptions, m as EnsureSchemaResult, n as ChatSessionRequestBody, o as ClivlySDK, p as DoctorReport, r as ChatWidgetVisitor, s as ClivlySDKConfig, u as CursorStore, y as SyncTriggerDescription } from "./namespace-probe-H7yWc0JV.cjs";
 //#region ../sdk/src/trigger-url.d.ts
 export declare function isPlaceholderUrl(value: string): boolean;
 //#endregion

package/sdk.d.mts

@@ -1,5 +1,5 @@
 import { C as customObjectDeclarations, M as validateEntitiesConfig, a as ClivlyEntitiesConfig, f as CustomObjectDeclaration, l as ConfigValidationError, m as DiscoveredSchemaTable, u as ConfigValidationResult, w as defineClivlyConfig } from "./entity-config-CKcj4-M_.mjs";
-import { _ as RemoteProjectionsDescription, a as ClivlyConnectResult, c as ClivlyUser, d as DiscoveredTable, f as DoctorCheck, g as EnsuredObjectTypeResult, h as EnsuredMappingResult, i as ClivlyConnectReason, l as CreateChatSessionHandlerOptions, m as EnsureSchemaResult, n as ChatSessionRequestBody, o as ClivlySDK, p as DoctorReport, r as ChatWidgetVisitor, s as ClivlySDKConfig, u as CursorStore, y as SyncTriggerDescription } from "./namespace-probe-CNQKSmxz.mjs";
+import { _ as RemoteProjectionsDescription, a as ClivlyConnectResult, c as ClivlyUser, d as DiscoveredTable, f as DoctorCheck, g as EnsuredObjectTypeResult, h as EnsuredMappingResult, i as ClivlyConnectReason, l as CreateChatSessionHandlerOptions, m as EnsureSchemaResult, n as ChatSessionRequestBody, o as ClivlySDK, p as DoctorReport, r as ChatWidgetVisitor, s as ClivlySDKConfig, u as CursorStore, y as SyncTriggerDescription } from "./namespace-probe-DykR0kgh.mjs";
 //#region ../sdk/src/trigger-url.d.ts
 export declare function isPlaceholderUrl(value: string): boolean;
 //#endregion

package/sdk.mjs

@@ -1,3 +1,3 @@
 import { c as defineClivlyConfig, g as validateEntitiesConfig, s as customObjectDeclarations } from "./entity-config-Ccfb2IL9.mjs";
-import { a as ClivlyRateLimitError, i as ClivlyNetworkError, n as ClivlyAuthError, o as createChatSessionHandler, r as ClivlyError, s as isPlaceholderUrl, t as createClivlySDK } from "./sdk-C-Pjxj2y.mjs";
+import { a as ClivlyRateLimitError, i as ClivlyNetworkError, n as ClivlyAuthError, o as createChatSessionHandler, r as ClivlyError, s as isPlaceholderUrl, t as createClivlySDK } from "./sdk-B-dp1tZN.mjs";
 export { ClivlyAuthError, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, createChatSessionHandler, createClivlySDK, customObjectDeclarations, defineClivlyConfig, isPlaceholderUrl, validateEntitiesConfig };

package/vite.d.cts

@@ -1,4 +1,4 @@
-import { o as ClivlySDK } from "./namespace-probe-C5RLl74M.cjs";
+import { o as ClivlySDK } from "./namespace-probe-H7yWc0JV.cjs";
 import { Plugin } from "vite";
 //#region ../sdk/src/vite.d.ts
 export interface ClivlyViteOptions {

package/vite.d.mts

@@ -1,4 +1,4 @@
-import { o as ClivlySDK } from "./namespace-probe-CNQKSmxz.mjs";
+import { o as ClivlySDK } from "./namespace-probe-DykR0kgh.mjs";
 import { Plugin } from "vite";
 //#region ../sdk/src/vite.d.ts
 export interface ClivlyViteOptions {