@neetru/sdk 3.0.1 → 3.0.2

package/dist/catalog.d.cts

@@ -1,5 +1,5 @@
-import { I as ResolvedConfig, C as CatalogListOptions, b as CatalogListResponse, P as Product } from './types-Lfd3LiAF.cjs';
-import './collection-ref-DqAAhuhX.cjs';
+import { I as ResolvedConfig, C as CatalogListOptions, b as CatalogListResponse, P as Product } from './types-Dc4bjrrt.cjs';
+import './collection-ref-BDdfD87k.cjs';
 import 'drizzle-orm/node-postgres';
 import './errors.cjs';
 

package/dist/catalog.d.ts

@@ -1,5 +1,5 @@
-import { I as ResolvedConfig, C as CatalogListOptions, b as CatalogListResponse, P as Product } from './types-DALIhcbq.js';
-import './collection-ref-DqAAhuhX.js';
+import { I as ResolvedConfig, C as CatalogListOptions, b as CatalogListResponse, P as Product } from './types-D7zVkO3n.js';
+import './collection-ref-BDdfD87k.js';
 import 'drizzle-orm/node-postgres';
 import './errors.js';
 

package/dist/checkout.d.cts

@@ -1,4 +1,4 @@
-export { c as CheckoutIntentInfo, d as CheckoutIntentStatus, e as CheckoutNamespace, f as CheckoutStartInput, g as CheckoutStartResult, h as CheckoutTenantType, M as MockCheckout, a6 as createCheckoutNamespace } from './types-Lfd3LiAF.cjs';
-import './collection-ref-DqAAhuhX.cjs';
+export { c as CheckoutIntentInfo, d as CheckoutIntentStatus, e as CheckoutNamespace, f as CheckoutStartInput, g as CheckoutStartResult, h as CheckoutTenantType, M as MockCheckout, a6 as createCheckoutNamespace } from './types-Dc4bjrrt.cjs';
+import './collection-ref-BDdfD87k.cjs';
 import 'drizzle-orm/node-postgres';
 import './errors.cjs';

package/dist/checkout.d.ts

@@ -1,4 +1,4 @@
-export { c as CheckoutIntentInfo, d as CheckoutIntentStatus, e as CheckoutNamespace, f as CheckoutStartInput, g as CheckoutStartResult, h as CheckoutTenantType, M as MockCheckout, a6 as createCheckoutNamespace } from './types-DALIhcbq.js';
-import './collection-ref-DqAAhuhX.js';
+export { c as CheckoutIntentInfo, d as CheckoutIntentStatus, e as CheckoutNamespace, f as CheckoutStartInput, g as CheckoutStartResult, h as CheckoutTenantType, M as MockCheckout, a6 as createCheckoutNamespace } from './types-D7zVkO3n.js';
+import './collection-ref-BDdfD87k.js';
 import 'drizzle-orm/node-postgres';
 import './errors.js';

package/dist/{collection-ref-DqAAhuhX.d.cts → collection-ref-BDdfD87k.d.cts}

@@ -228,6 +228,98 @@ interface SyncTransport {
     }>, needsResync: boolean) => void) => () => void;
 }
 
+/**
+ * field-value.ts — Sentinels de escrita server-side para o Mundo Documentos.
+ *
+ * Resolve duas lacunas confirmadas (bug_05aedb8b) da superfície `client.db`:
+ *
+ *  1. **Timestamp resolvido no servidor** — antes deste módulo, o produto que
+ *     quisesse `createdAt`/`updatedAt` confiáveis tinha que usar `Date.now()`
+ *     no CLIENTE, que é spoofável e sofre clock-skew. Agora:
+ *
+ *         await orders.add({ total: 99, createdAt: serverTimestamp() });
+ *
+ *     O marcador atravessa o transporte REST como um objeto JSON namespaceado
+ *     e o Core o substitui por `FieldValue.serverTimestamp()` no momento da
+ *     escrita — relógio do SERVIDOR, não do cliente.
+ *
+ *  2. **Increment atômico** — antes, `update(id, { n: x+1 })` era read-modify-write
+ *     no cliente, sujeito a lost-update sob concorrência. Agora:
+ *
+ *         await counters.update('global', { hits: increment(1) });
+ *
+ *     O Core aplica `FieldValue.increment(1)` atomicamente no documento.
+ *
+ * ## Contrato de fio (wire format)
+ *
+ * Os sentinels são objetos JSON simples — sobrevivem `JSON.stringify` no
+ * transporte REST e ao `IndexedDB structured clone` da camada offline:
+ *
+ *   serverTimestamp()  → `{ "__neetru__": "serverTimestamp" }`
+ *   increment(n)       → `{ "__neetru__": "increment", "operand": n }`
+ *
+ * A chave-âncora `__neetru__` é deliberadamente improvável de colidir com
+ * dados de produto. O Core valida e resolve esses marcadores; qualquer objeto
+ * com `__neetru__` desconhecido é rejeitado server-side (fail-closed).
+ *
+ * ## Aplicação otimista (offline-first)
+ *
+ * A camada offline aplica uma APROXIMAÇÃO local imediata (para a UI não piscar):
+ *   - `serverTimestamp()` → `Date.now()` local (substituído pelo valor real no sync).
+ *   - `increment(n)`      → soma `n` ao valor numérico atual do campo (0 se ausente).
+ * O valor canônico vem sempre do servidor no pull/confirm subsequente.
+ *
+ * @module
+ */
+/** Chave-âncora dos marcadores de sentinel no wire format. */
+declare const NEETRU_SENTINEL_KEY: "__neetru__";
+/** Marcador de timestamp resolvido pelo servidor. */
+interface ServerTimestampSentinel {
+    readonly __neetru__: 'serverTimestamp';
+}
+/** Marcador de incremento atômico aplicado pelo servidor. */
+interface IncrementSentinel {
+    readonly __neetru__: 'increment';
+    /** Delta a somar (pode ser negativo para decremento). */
+    readonly operand: number;
+}
+/**
+ * União de todos os sentinels de campo. Use `serverTimestamp()` / `increment()`
+ * para construir — nunca monte o objeto à mão.
+ */
+type FieldSentinel = ServerTimestampSentinel | IncrementSentinel;
+/**
+ * Sentinel que instrui o servidor a gravar o timestamp do MOMENTO da escrita
+ * usando o relógio do servidor (não do cliente).
+ *
+ * @example
+ * ```ts
+ * import { serverTimestamp } from '@neetru/sdk/db';
+ * await orders.add({ total: 99, createdAt: serverTimestamp() });
+ * ```
+ */
+declare function serverTimestamp(): ServerTimestampSentinel;
+/**
+ * Sentinel que instrui o servidor a incrementar atomicamente o campo numérico
+ * por `n` (negativo decrementa). Se o campo não existir/não for numérico, o
+ * servidor o trata como `0` antes de somar (semântica `FieldValue.increment`).
+ *
+ * @param n — delta inteiro ou fracionário a somar.
+ * @example
+ * ```ts
+ * import { increment } from '@neetru/sdk/db';
+ * await counters.update('global', { hits: increment(1) });
+ * await wallet.update(uid, { balance: increment(-50) });
+ * ```
+ */
+declare function increment(n: number): IncrementSentinel;
+/** `true` se `v` é qualquer sentinel de campo Neetru. */
+declare function isFieldSentinel(v: unknown): v is FieldSentinel;
+/** `true` se `v` é o sentinel `serverTimestamp()`. */
+declare function isServerTimestampSentinel(v: unknown): v is ServerTimestampSentinel;
+/** `true` se `v` é o sentinel `increment(n)` com `operand` numérico válido. */
+declare function isIncrementSentinel(v: unknown): v is IncrementSentinel;
+
 /**
  * DbCollectionRef — superfície de Documentos offline-first do @neetru/sdk (M2).
  *
@@ -251,6 +343,23 @@ interface SyncTransport {
  * sem alterar a superfície pública.
  */
 
+/**
+ * Permite que cada campo de `T` aceite, além do seu tipo declarado, um sentinel
+ * de escrita server-side (`serverTimestamp()` / `increment()`).
+ *
+ * Sem isso, um produto que tipa `createdAt: number` veria erro de tipo ao passar
+ * `serverTimestamp()`. Esta projeção mantém o autocomplete dos campos do produto
+ * e ainda autoriza os sentinels onde fizer sentido.
+ *
+ * @example
+ * ```ts
+ * interface Order { total: number; createdAt: number; hits: number }
+ * orders.add({ total: 10, createdAt: serverTimestamp(), hits: increment(1) });
+ * ```
+ */
+type WithFieldSentinels<T> = {
+    [K in keyof T]: T[K] | FieldSentinel;
+};
 interface DbWhereFilter {
     field: string;
     op: '==' | '!=' | '<' | '<=' | '>' | '>=' | 'array-contains' | 'in' | 'not-in';
@@ -317,15 +426,15 @@ type DbChangeType = 'added' | 'modified' | 'removed';
  */
 type DbBatchOp<T = Record<string, unknown>> = {
     kind: 'add';
-    data: Omit<T, 'id'>;
+    data: WithFieldSentinels<Omit<T, 'id'>>;
 } | {
     kind: 'set';
     id: string;
-    data: Omit<T, 'id'>;
+    data: WithFieldSentinels<Omit<T, 'id'>>;
 } | {
     kind: 'update';
     id: string;
-    data: Partial<Omit<T, 'id'>>;
+    data: Partial<WithFieldSentinels<Omit<T, 'id'>>>;
 } | {
     kind: 'remove';
     id: string;
@@ -365,10 +474,10 @@ interface DbDocRef<T = Record<string, unknown>> {
     /** Nome da coleção parent. */
     readonly collection: string;
     get(): Promise<DbGetResult<T> | null>;
-    set(data: Omit<T, 'id'>): Promise<{
+    set(data: WithFieldSentinels<Omit<T, 'id'>>): Promise<{
         ok: true;
     }>;
-    update(data: Partial<Omit<T, 'id'>>): Promise<{
+    update(data: Partial<WithFieldSentinels<Omit<T, 'id'>>>): Promise<{
         ok: true;
     }>;
     remove(): Promise<{
@@ -387,16 +496,16 @@ interface DbCollectionRef<T = Record<string, unknown>> {
     /** Lista documentos com query opcional. */
     list(q?: DbQuery): Promise<DbListResult<T>>;
     /** Adiciona doc com id gerado pelo cliente (UUID v4). Durável localmente. */
-    add(data: Omit<T, 'id'>): Promise<{
+    add(data: WithFieldSentinels<Omit<T, 'id'>>): Promise<{
         ok: true;
         id: string;
     }>;
     /** Cria ou sobrescreve um doc pelo id. Durável localmente. */
-    set(id: string, data: Omit<T, 'id'>): Promise<{
+    set(id: string, data: WithFieldSentinels<Omit<T, 'id'>>): Promise<{
         ok: true;
     }>;
     /** Atualiza campos de um doc (merge). Durável localmente. */
-    update(id: string, data: Partial<Omit<T, 'id'>>): Promise<{
+    update(id: string, data: Partial<WithFieldSentinels<Omit<T, 'id'>>>): Promise<{
         ok: true;
     }>;
     /** Remove um doc (tombstone local). Durável localmente. */
@@ -469,4 +578,4 @@ interface CreateOfflineDocumentsOptions {
     periodicSyncIntervalMs?: number;
 }
 
-export type { ConflictRecord as C, DbBatchOp as D, NeetruDbDocuments as N, RealtimeTransport as R, SyncState as S, Unsubscribe as U, CreateOfflineDocumentsOptions as a, DbChangeType as b, DbCollectionRef as c, DbDoc as d, DbDocRef as e, DbGetResult as f, DbListResult as g, DbQuery as h, DbWhereFilter as i };
+export { type ConflictRecord as C, type DbBatchOp as D, type FieldSentinel as F, type IncrementSentinel as I, NEETRU_SENTINEL_KEY as N, type RealtimeTransport as R, type ServerTimestampSentinel as S, type Unsubscribe as U, type WithFieldSentinels as W, type CreateOfflineDocumentsOptions as a, type DbChangeType as b, type DbCollectionRef as c, type DbDoc as d, type DbDocRef as e, type DbGetResult as f, type DbListResult as g, type DbQuery as h, type DbWhereFilter as i, type NeetruDbDocuments as j, type SyncState as k, increment as l, isFieldSentinel as m, isIncrementSentinel as n, isServerTimestampSentinel as o, serverTimestamp as s };

package/dist/{collection-ref-DqAAhuhX.d.ts → collection-ref-BDdfD87k.d.ts}

@@ -228,6 +228,98 @@ interface SyncTransport {
     }>, needsResync: boolean) => void) => () => void;
 }
 
+/**
+ * field-value.ts — Sentinels de escrita server-side para o Mundo Documentos.
+ *
+ * Resolve duas lacunas confirmadas (bug_05aedb8b) da superfície `client.db`:
+ *
+ *  1. **Timestamp resolvido no servidor** — antes deste módulo, o produto que
+ *     quisesse `createdAt`/`updatedAt` confiáveis tinha que usar `Date.now()`
+ *     no CLIENTE, que é spoofável e sofre clock-skew. Agora:
+ *
+ *         await orders.add({ total: 99, createdAt: serverTimestamp() });
+ *
+ *     O marcador atravessa o transporte REST como um objeto JSON namespaceado
+ *     e o Core o substitui por `FieldValue.serverTimestamp()` no momento da
+ *     escrita — relógio do SERVIDOR, não do cliente.
+ *
+ *  2. **Increment atômico** — antes, `update(id, { n: x+1 })` era read-modify-write
+ *     no cliente, sujeito a lost-update sob concorrência. Agora:
+ *
+ *         await counters.update('global', { hits: increment(1) });
+ *
+ *     O Core aplica `FieldValue.increment(1)` atomicamente no documento.
+ *
+ * ## Contrato de fio (wire format)
+ *
+ * Os sentinels são objetos JSON simples — sobrevivem `JSON.stringify` no
+ * transporte REST e ao `IndexedDB structured clone` da camada offline:
+ *
+ *   serverTimestamp()  → `{ "__neetru__": "serverTimestamp" }`
+ *   increment(n)       → `{ "__neetru__": "increment", "operand": n }`
+ *
+ * A chave-âncora `__neetru__` é deliberadamente improvável de colidir com
+ * dados de produto. O Core valida e resolve esses marcadores; qualquer objeto
+ * com `__neetru__` desconhecido é rejeitado server-side (fail-closed).
+ *
+ * ## Aplicação otimista (offline-first)
+ *
+ * A camada offline aplica uma APROXIMAÇÃO local imediata (para a UI não piscar):
+ *   - `serverTimestamp()` → `Date.now()` local (substituído pelo valor real no sync).
+ *   - `increment(n)`      → soma `n` ao valor numérico atual do campo (0 se ausente).
+ * O valor canônico vem sempre do servidor no pull/confirm subsequente.
+ *
+ * @module
+ */
+/** Chave-âncora dos marcadores de sentinel no wire format. */
+declare const NEETRU_SENTINEL_KEY: "__neetru__";
+/** Marcador de timestamp resolvido pelo servidor. */
+interface ServerTimestampSentinel {
+    readonly __neetru__: 'serverTimestamp';
+}
+/** Marcador de incremento atômico aplicado pelo servidor. */
+interface IncrementSentinel {
+    readonly __neetru__: 'increment';
+    /** Delta a somar (pode ser negativo para decremento). */
+    readonly operand: number;
+}
+/**
+ * União de todos os sentinels de campo. Use `serverTimestamp()` / `increment()`
+ * para construir — nunca monte o objeto à mão.
+ */
+type FieldSentinel = ServerTimestampSentinel | IncrementSentinel;
+/**
+ * Sentinel que instrui o servidor a gravar o timestamp do MOMENTO da escrita
+ * usando o relógio do servidor (não do cliente).
+ *
+ * @example
+ * ```ts
+ * import { serverTimestamp } from '@neetru/sdk/db';
+ * await orders.add({ total: 99, createdAt: serverTimestamp() });
+ * ```
+ */
+declare function serverTimestamp(): ServerTimestampSentinel;
+/**
+ * Sentinel que instrui o servidor a incrementar atomicamente o campo numérico
+ * por `n` (negativo decrementa). Se o campo não existir/não for numérico, o
+ * servidor o trata como `0` antes de somar (semântica `FieldValue.increment`).
+ *
+ * @param n — delta inteiro ou fracionário a somar.
+ * @example
+ * ```ts
+ * import { increment } from '@neetru/sdk/db';
+ * await counters.update('global', { hits: increment(1) });
+ * await wallet.update(uid, { balance: increment(-50) });
+ * ```
+ */
+declare function increment(n: number): IncrementSentinel;
+/** `true` se `v` é qualquer sentinel de campo Neetru. */
+declare function isFieldSentinel(v: unknown): v is FieldSentinel;
+/** `true` se `v` é o sentinel `serverTimestamp()`. */
+declare function isServerTimestampSentinel(v: unknown): v is ServerTimestampSentinel;
+/** `true` se `v` é o sentinel `increment(n)` com `operand` numérico válido. */
+declare function isIncrementSentinel(v: unknown): v is IncrementSentinel;
+
 /**
  * DbCollectionRef — superfície de Documentos offline-first do @neetru/sdk (M2).
  *
@@ -251,6 +343,23 @@ interface SyncTransport {
  * sem alterar a superfície pública.
  */
 
+/**
+ * Permite que cada campo de `T` aceite, além do seu tipo declarado, um sentinel
+ * de escrita server-side (`serverTimestamp()` / `increment()`).
+ *
+ * Sem isso, um produto que tipa `createdAt: number` veria erro de tipo ao passar
+ * `serverTimestamp()`. Esta projeção mantém o autocomplete dos campos do produto
+ * e ainda autoriza os sentinels onde fizer sentido.
+ *
+ * @example
+ * ```ts
+ * interface Order { total: number; createdAt: number; hits: number }
+ * orders.add({ total: 10, createdAt: serverTimestamp(), hits: increment(1) });
+ * ```
+ */
+type WithFieldSentinels<T> = {
+    [K in keyof T]: T[K] | FieldSentinel;
+};
 interface DbWhereFilter {
     field: string;
     op: '==' | '!=' | '<' | '<=' | '>' | '>=' | 'array-contains' | 'in' | 'not-in';
@@ -317,15 +426,15 @@ type DbChangeType = 'added' | 'modified' | 'removed';
  */
 type DbBatchOp<T = Record<string, unknown>> = {
     kind: 'add';
-    data: Omit<T, 'id'>;
+    data: WithFieldSentinels<Omit<T, 'id'>>;
 } | {
     kind: 'set';
     id: string;
-    data: Omit<T, 'id'>;
+    data: WithFieldSentinels<Omit<T, 'id'>>;
 } | {
     kind: 'update';
     id: string;
-    data: Partial<Omit<T, 'id'>>;
+    data: Partial<WithFieldSentinels<Omit<T, 'id'>>>;
 } | {
     kind: 'remove';
     id: string;
@@ -365,10 +474,10 @@ interface DbDocRef<T = Record<string, unknown>> {
     /** Nome da coleção parent. */
     readonly collection: string;
     get(): Promise<DbGetResult<T> | null>;
-    set(data: Omit<T, 'id'>): Promise<{
+    set(data: WithFieldSentinels<Omit<T, 'id'>>): Promise<{
         ok: true;
     }>;
-    update(data: Partial<Omit<T, 'id'>>): Promise<{
+    update(data: Partial<WithFieldSentinels<Omit<T, 'id'>>>): Promise<{
         ok: true;
     }>;
     remove(): Promise<{
@@ -387,16 +496,16 @@ interface DbCollectionRef<T = Record<string, unknown>> {
     /** Lista documentos com query opcional. */
     list(q?: DbQuery): Promise<DbListResult<T>>;
     /** Adiciona doc com id gerado pelo cliente (UUID v4). Durável localmente. */
-    add(data: Omit<T, 'id'>): Promise<{
+    add(data: WithFieldSentinels<Omit<T, 'id'>>): Promise<{
         ok: true;
         id: string;
     }>;
     /** Cria ou sobrescreve um doc pelo id. Durável localmente. */
-    set(id: string, data: Omit<T, 'id'>): Promise<{
+    set(id: string, data: WithFieldSentinels<Omit<T, 'id'>>): Promise<{
         ok: true;
     }>;
     /** Atualiza campos de um doc (merge). Durável localmente. */
-    update(id: string, data: Partial<Omit<T, 'id'>>): Promise<{
+    update(id: string, data: Partial<WithFieldSentinels<Omit<T, 'id'>>>): Promise<{
         ok: true;
     }>;
     /** Remove um doc (tombstone local). Durável localmente. */
@@ -469,4 +578,4 @@ interface CreateOfflineDocumentsOptions {
     periodicSyncIntervalMs?: number;
 }
 
-export type { ConflictRecord as C, DbBatchOp as D, NeetruDbDocuments as N, RealtimeTransport as R, SyncState as S, Unsubscribe as U, CreateOfflineDocumentsOptions as a, DbChangeType as b, DbCollectionRef as c, DbDoc as d, DbDocRef as e, DbGetResult as f, DbListResult as g, DbQuery as h, DbWhereFilter as i };
+export { type ConflictRecord as C, type DbBatchOp as D, type FieldSentinel as F, type IncrementSentinel as I, NEETRU_SENTINEL_KEY as N, type RealtimeTransport as R, type ServerTimestampSentinel as S, type Unsubscribe as U, type WithFieldSentinels as W, type CreateOfflineDocumentsOptions as a, type DbChangeType as b, type DbCollectionRef as c, type DbDoc as d, type DbDocRef as e, type DbGetResult as f, type DbListResult as g, type DbQuery as h, type DbWhereFilter as i, type NeetruDbDocuments as j, type SyncState as k, increment as l, isFieldSentinel as m, isIncrementSentinel as n, isServerTimestampSentinel as o, serverTimestamp as s };

package/dist/db-react.d.cts

@@ -1,4 +1,4 @@
-import { S as SyncState, U as Unsubscribe, d as DbDoc, c as DbCollectionRef, h as DbQuery } from './collection-ref-DqAAhuhX.cjs';
+import { k as SyncState, U as Unsubscribe, d as DbDoc, c as DbCollectionRef, h as DbQuery } from './collection-ref-BDdfD87k.cjs';
 
 /**
  * Resultado de `useDocument`.

package/dist/db-react.d.ts

@@ -1,4 +1,4 @@
-import { S as SyncState, U as Unsubscribe, d as DbDoc, c as DbCollectionRef, h as DbQuery } from './collection-ref-DqAAhuhX.js';
+import { k as SyncState, U as Unsubscribe, d as DbDoc, c as DbCollectionRef, h as DbQuery } from './collection-ref-BDdfD87k.js';
 
 /**
  * Resultado de `useDocument`.

package/dist/db.cjs

@@ -1540,7 +1540,7 @@ var SyncEngine = class {
     return true;
   }
   /** Atualiza o cache após confirmação de escrita (outcome=confirmed). */
-  async _applySyncedDoc(collection, docId, serverVersion, serverTimestamp, mut, busChanges) {
+  async _applySyncedDoc(collection, docId, serverVersion, serverTimestamp2, mut, busChanges) {
     const existing = await this._store.getDoc(collection, docId);
     if (mut.op === "remove") {
       if (existing) {
@@ -1549,7 +1549,7 @@ var SyncEngine = class {
           meta: {
             ...existing.meta,
             serverVersion,
-            updatedAtServer: serverTimestamp,
+            updatedAtServer: serverTimestamp2,
             updatedAtLocal: Date.now(),
             state: "synced",
             deleted: true,
@@ -1567,7 +1567,7 @@ var SyncEngine = class {
       data: mut.op === "update" ? { ...existing?.data ?? {}, ...newData } : newData,
       meta: {
         serverVersion,
-        updatedAtServer: serverTimestamp,
+        updatedAtServer: serverTimestamp2,
         updatedAtLocal: Date.now(),
         state: "synced",
         pendingMutationIds: [],
@@ -2646,6 +2646,54 @@ var TabCoordinator = class {
 
 // src/db/collection-ref.ts
 init_db_errors();
+
+// src/db/field-value.ts
+var NEETRU_SENTINEL_KEY = "__neetru__";
+function serverTimestamp() {
+  return { __neetru__: "serverTimestamp" };
+}
+function increment(n) {
+  if (typeof n !== "number" || !Number.isFinite(n)) {
+    throw new TypeError(
+      `increment(n): n deve ser um n\xFAmero finito (recebido: ${String(n)}).`
+    );
+  }
+  return { __neetru__: "increment", operand: n };
+}
+function isFieldSentinel(v) {
+  return typeof v === "object" && v !== null && NEETRU_SENTINEL_KEY in v && typeof v[NEETRU_SENTINEL_KEY] === "string";
+}
+function isServerTimestampSentinel(v) {
+  return isFieldSentinel(v) && v.__neetru__ === "serverTimestamp";
+}
+function isIncrementSentinel(v) {
+  return isFieldSentinel(v) && v.__neetru__ === "increment" && typeof v.operand === "number" && Number.isFinite(v.operand);
+}
+function resolveSentinelLocally(value, baseValue) {
+  if (isServerTimestampSentinel(value)) {
+    return Date.now();
+  }
+  if (isIncrementSentinel(value)) {
+    const base = typeof baseValue === "number" && Number.isFinite(baseValue) ? baseValue : 0;
+    return base + value.operand;
+  }
+  return value;
+}
+function resolveSentinelsLocally(data, existing) {
+  let touched = false;
+  const out = {};
+  for (const [k, v] of Object.entries(data)) {
+    if (isFieldSentinel(v)) {
+      touched = true;
+      out[k] = resolveSentinelLocally(v, existing?.[k]);
+    } else {
+      out[k] = v;
+    }
+  }
+  return touched ? out : data;
+}
+
+// src/db/collection-ref.ts
 function isIndexedDBUnavailable() {
   return typeof indexedDB === "undefined" || typeof window === "undefined";
 }
@@ -2774,10 +2822,12 @@ var DbCollectionRefImpl = class {
     return this._buildListResult(q);
   }
   async add(data) {
+    const rawData = data;
+    const localData = resolveSentinelsLocally(rawData, void 0);
     const mutation = await this._queue.enqueue({
       collection: this._collection,
       op: "add",
-      payload: data,
+      payload: rawData,
       baseVersion: null,
       batchId: null
     });
@@ -2785,7 +2835,7 @@ var DbCollectionRefImpl = class {
     await this._store.putDoc({
       collection: this._collection,
       id: docId,
-      data,
+      data: localData,
       meta: {
         serverVersion: null,
         updatedAtServer: null,
@@ -2799,25 +2849,27 @@ var DbCollectionRefImpl = class {
     this._bus.emit([{
       type: "added",
       collection: this._collection,
-      doc: { id: docId, data }
+      doc: { id: docId, data: localData }
     }]);
     return { ok: true, id: docId };
   }
   async set(id, data) {
     assertValidId(id);
     const existing = await this._store.getDoc(this._collection, id);
+    const rawData = data;
+    const localData = resolveSentinelsLocally(rawData, void 0);
     const mutation = await this._queue.enqueue({
       collection: this._collection,
       docId: id,
       op: "set",
-      payload: data,
+      payload: rawData,
       baseVersion: existing?.meta.serverVersion ?? null,
       batchId: null
     });
     await this._store.putDoc({
       collection: this._collection,
       id,
-      data,
+      data: localData,
       meta: {
         serverVersion: existing?.meta.serverVersion ?? null,
         updatedAtServer: existing?.meta.updatedAtServer ?? null,
@@ -2831,19 +2883,22 @@ var DbCollectionRefImpl = class {
     this._bus.emit([{
       type: existing && !existing.meta.deleted ? "modified" : "added",
       collection: this._collection,
-      doc: { id, data }
+      doc: { id, data: localData }
     }]);
     return { ok: true };
   }
   async update(id, data) {
     assertValidId(id);
     const existing = await this._store.getDoc(this._collection, id);
-    const mergedData = existing?.meta.deleted ? { ...data } : { ...existing?.data ?? {}, ...data };
+    const rawData = data;
+    const existingBase = existing?.meta.deleted ? void 0 : existing?.data;
+    const localData = resolveSentinelsLocally(rawData, existingBase);
+    const mergedData = existing?.meta.deleted ? { ...localData } : { ...existing?.data ?? {}, ...localData };
     const mutation = await this._queue.enqueue({
       collection: this._collection,
       docId: id,
       op: "update",
-      payload: data,
+      payload: rawData,
       baseVersion: existing?.meta.serverVersion ?? null,
       batchId: null
     });
@@ -2900,6 +2955,7 @@ var DbCollectionRefImpl = class {
       const collection = this._collection;
       if (op.kind === "add") {
         const data = op.data;
+        const localData = resolveSentinelsLocally(data, void 0);
         const mutation = await this._queue.enqueue({
           collection,
           op: "add",
@@ -2911,7 +2967,7 @@ var DbCollectionRefImpl = class {
         await this._store.putDoc({
           collection,
           id: docId,
-          data,
+          data: localData,
           meta: {
             serverVersion: null,
             updatedAtServer: null,
@@ -2922,11 +2978,12 @@ var DbCollectionRefImpl = class {
             ownerId: null
           }
         });
-        busChanges.push({ type: "added", collection, doc: { id: docId, data } });
+        busChanges.push({ type: "added", collection, doc: { id: docId, data: localData } });
       } else if (op.kind === "set") {
         const id = op.id;
         const data = op.data;
         const existing = await this._store.getDoc(collection, id);
+        const localData = resolveSentinelsLocally(data, void 0);
         const mutation = await this._queue.enqueue({
           collection,
           docId: id,
@@ -2938,7 +2995,7 @@ var DbCollectionRefImpl = class {
         await this._store.putDoc({
           collection,
           id,
-          data,
+          data: localData,
           meta: {
             serverVersion: existing?.meta.serverVersion ?? null,
             updatedAtServer: existing?.meta.updatedAtServer ?? null,
@@ -2952,13 +3009,15 @@ var DbCollectionRefImpl = class {
         busChanges.push({
           type: existing && !existing.meta.deleted ? "modified" : "added",
           collection,
-          doc: { id, data }
+          doc: { id, data: localData }
         });
       } else if (op.kind === "update") {
         const id = op.id;
         const data = op.data;
         const existing = await this._store.getDoc(collection, id);
-        const merged = { ...existing?.data ?? {}, ...data };
+        const existingBase = existing?.meta.deleted ? void 0 : existing?.data;
+        const localData = resolveSentinelsLocally(data, existingBase);
+        const merged = { ...existing?.data ?? {}, ...localData };
         const mutation = await this._queue.enqueue({
           collection,
           docId: id,
@@ -3990,8 +4049,14 @@ function createLazyCollectionRef(name, getDocsPromise) {
   };
 }
 
+exports.NEETRU_SENTINEL_KEY = NEETRU_SENTINEL_KEY;
 exports.createNeetruDb = createNeetruDb;
 exports.createRestSyncTransport = createRestSyncTransport;
 exports.getWebSocketRealtimeClient = getWebSocketRealtimeClient;
+exports.increment = increment;
+exports.isFieldSentinel = isFieldSentinel;
+exports.isIncrementSentinel = isIncrementSentinel;
+exports.isServerTimestampSentinel = isServerTimestampSentinel;
+exports.serverTimestamp = serverTimestamp;
 //# sourceMappingURL=db.cjs.map
 //# sourceMappingURL=db.cjs.map