@clivly/sdk 0.11.0 → 0.13.0

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

@@ -141,6 +141,7 @@ function fromDrizzle(db, table, opts) {
 	const idColumnName = idColumn.name;
 	const source = {
 		entity: opts.entity,
+		...opts.pushSource === void 0 ? {} : { pushSource: opts.pushSource },
 		cursorField: cursorColumnName,
 		idField: idColumnName,
 		fetchPage: ({ since, limit }) => drizzleDb.select(projection).from(table).where(since ? drizzle_orm.sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy((0, drizzle_orm.asc)(cursorColumn), (0, drizzle_orm.asc)(idColumn)).limit(limit),
@@ -162,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.
@@ -206,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";
@@ -82,6 +82,21 @@ interface FromDrizzleOptions {
    * check and a false explanation.
    */
   objectType?: string;
+  /**
+   * The label this source's pushes carry, when it differs from `entity`.
+   *
+   * `entity` is the CURSOR KEY — two sources sharing it share a cursor, so the
+   * first to run advances it and the second silently pushes nothing. The push
+   * LABEL is matched against a mapping's `sourceTable`, which is the host
+   * table name. Those two requirements conflict whenever one table feeds two
+   * concepts: an `organization` table mapped as both a company and a
+   * subscription deal needs distinct cursors but the same table name on the
+   * wire.
+   *
+   * `fromDrizzleProjection` stamps this itself for the projection case. This
+   * is the same escape hatch for a plain single-table source.
+   */
+  pushSource?: string;
 }
 /**
  * Build a `SyncSource` from a Drizzle table, generating the keyset-paginated
@@ -100,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";
@@ -82,6 +82,21 @@ interface FromDrizzleOptions {
    * check and a false explanation.
    */
   objectType?: string;
+  /**
+   * The label this source's pushes carry, when it differs from `entity`.
+   *
+   * `entity` is the CURSOR KEY — two sources sharing it share a cursor, so the
+   * first to run advances it and the second silently pushes nothing. The push
+   * LABEL is matched against a mapping's `sourceTable`, which is the host
+   * table name. Those two requirements conflict whenever one table feeds two
+   * concepts: an `organization` table mapped as both a company and a
+   * subscription deal needs distinct cursors but the same table name on the
+   * wire.
+   *
+   * `fromDrizzleProjection` stamps this itself for the projection case. This
+   * is the same escape hatch for a plain single-table source.
+   */
+  pushSource?: string;
 }
 /**
  * Build a `SyncSource` from a Drizzle table, generating the keyset-paginated
@@ -100,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

@@ -140,6 +140,7 @@ function fromDrizzle(db, table, opts) {
 	const idColumnName = idColumn.name;
 	const source = {
 		entity: opts.entity,
+		...opts.pushSource === void 0 ? {} : { pushSource: opts.pushSource },
 		cursorField: cursorColumnName,
 		idField: idColumnName,
 		fetchPage: ({ since, limit }) => drizzleDb.select(projection).from(table).where(since ? sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy(asc(cursorColumn), asc(idColumn)).limit(limit),
@@ -161,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.
@@ -190,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;
@@ -1972,6 +1986,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({
@@ -2327,7 +2363,8 @@ function createClivlySDK(config) {
 		runScheduled,
 		createClivlyHandler,
 		sync: runSync,
-		createAuthVerifyHandler
+		createAuthVerifyHandler,
+		pushOne
 	};
 }
 //#endregion

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

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

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;
@@ -1971,6 +1985,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({
@@ -2326,7 +2362,8 @@ function createClivlySDK(config) {
 		runScheduled,
 		createClivlyHandler,
 		sync: runSync,
-		createAuthVerifyHandler
+		createAuthVerifyHandler,
+		pushOne
 	};
 }
 //#endregion

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.11.0",
+  "version": "0.13.0",
   "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.11.0"
+    "@clivly/core": "0.13.0"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4",