js-bao 0.5.1 → 0.5.2

package/dist/cloudflare.d.cts

@@ -563,6 +563,27 @@ declare class BaseModel implements StringSetChangeTracker {
      */
     static count(this: new (...args: any[]) => any, filter?: DocumentFilter, options?: Pick<QueryOptions, "documents">): Promise<number>;
     static findAll<T extends BaseModel>(this: new (...args: any[]) => T): Promise<T[]>;
+    /**
+     * Resolve a record by its unique-constraint field values via an engine query.
+     * Used as a fallback when the `_uniqueIdx_<model>_<constraint>` map has no
+     * entry for a key.
+     *
+     * The index map is a cache over the SQLite projection, not the source of
+     * truth: every record is loaded into the projection on `initializeForDocument`
+     * regardless of index presence, but a record written by a client predating
+     * index maintenance (legacy data) is missing from the index. Such a record
+     * silently escapes both `upsertByUnique` lookups and the `save()` uniqueness
+     * check. A query over the constraint fields finds it reliably.
+     *
+     * Contract: RESOLVE ONLY. Returns the owning record (with `_metaDocId` set to
+     * the document that holds it, via `queryOne`) or `null`. Callers decide
+     * whether to heal the missing index entry (write paths) and do their own
+     * logging — this method never mutates the index, so read paths stay
+     * read-only. Mirrors `buildUniqueKey`: a null/undefined value in any
+     * constraint field means the record does not participate in the constraint,
+     * so no query runs.
+     */
+    private static _resolveByUniqueFallback;
     static findByUnique<T extends BaseModel>(this: typeof BaseModel & (new (...args: any[]) => T), constraintName: string, value: any | any[]): Promise<T | null>;
     static upsertByUnique<T extends BaseModel>(this: typeof BaseModel & (new (...args: any[]) => T), constraintName: string, uniqueLookupValue: any | any[], dataToUpsert: Partial<Omit<InstanceType<new (...args: any[]) => T>, keyof BaseModel | "toJSON">> & {
         id?: string;
@@ -733,6 +754,18 @@ interface HookResult {
     allow: boolean;
     /** Reason for denial (returned to client as error message) */
     reason?: string;
+    /**
+     * Names of fields the hook wrote onto `ctx.data` that the DO should echo
+     * back to the caller in the write response's `appliedFields`. A `beforeSave`
+     * hook can compute and set fields on `ctx.data` (e.g. app-level triggers that
+     * derive a value from the submitted row); those values are persisted but are
+     * invisible to a caller that rebuilds a change event from its original
+     * submission inputs. Reporting the names here lets the DO read the final
+     * post-hook values back and thread them into `appliedFields` so the caller
+     * can propagate them (#1476). The hook contract stays generic — it names the
+     * fields it applied and does not need to know how the caller uses them.
+     */
+    serverAppliedFieldNames?: string[];
 }
 /** Result from beforeQuery hooks — can inject additional filters */
 interface BeforeQueryResult extends HookResult {
@@ -849,6 +882,20 @@ interface QueryResponse {
 interface SaveResponse {
     success: boolean;
     id: string;
+    /**
+     * Server-applied field values the DO wrote AFTER the caller's submission
+     * inputs were assembled, read back from the final post-hook `data`
+     * (#1476, consolidating the #1462 `stamps` channel). This is the single
+     * "server-applied fields" channel: it carries both the applied `autoStamps`
+     * timestamps and any fields a `beforeSave` hook reported via
+     * `serverAppliedFieldNames` (e.g. app-level trigger-computed values). Present
+     * only when at least one such field ended up with a value. Lets the Worker
+     * thread these values into the change-event `data` it broadcasts to
+     * subscribers — otherwise a `select`-listed stamped or trigger-computed field
+     * never reaches the frame, because the frame is rebuilt from the submission
+     * inputs (which predate the DO-side write).
+     */
+    appliedFields?: Record<string, any>;
 }
 interface DeleteResponse {
     success: boolean;
@@ -931,6 +978,8 @@ interface PatchRequest {
 interface PatchResponse {
     success: boolean;
     id: string;
+    /** Server-applied field values (#1476). See `SaveResponse.appliedFields`. */
+    appliedFields?: Record<string, any>;
 }
 interface BatchOperation {
     op: "save" | "patch" | "delete" | "increment" | "addToSet" | "removeFromSet";
@@ -958,12 +1007,46 @@ interface BatchOperation {
 }
 interface BatchRequest {
     operations: BatchOperation[];
+    /**
+     * All-or-nothing execution (#1478). When `true`, the FIRST operation that
+     * fails inside the transaction — hook denial, condition / `ifNotExists` /
+     * unique violation, record-not-found, or upsert validation error — aborts
+     * the whole batch: every write is rolled back and the handler returns an
+     * error naming the failed step with its natural HTTP status (see
+     * `BatchOperationResult.status`). When `false` or absent (the default), each
+     * operation's outcome is recorded independently and successful siblings
+     * commit — the partial-success behavior import-bulk and applyToQuery rely on.
+     */
+    atomic?: boolean;
 }
+/**
+ * Stable, machine-readable failure tag on a failed `BatchOperationResult`
+ * (#1478). Derived at each failure site — never inferred from the `error`
+ * string. `#1389` (conditional writes + fencing-token enforcement) surfaces its
+ * condition / stale-token rejections through this same channel.
+ */
+type BatchFailureCode = "NOT_FOUND" | "HOOK_DENIED" | "CONDITION_NOT_MET" | "ALREADY_EXISTS" | "UNIQUE_VIOLATION" | "VALIDATION_ERROR";
 interface BatchOperationResult {
     success: boolean;
     id: string;
     error?: string;
+    /**
+     * Structured failure metadata (#1478), present only on a failed result. Both
+     * are derived at the failure site, not parsed back out of `error`:
+     *  - `status` — the natural HTTP status for the cause (404 not found,
+     *    403 hook denial, 409 condition / `ifNotExists` / unique conflict,
+     *    400 upsert validation).
+     *  - `code` — a stable machine-readable tag (see `BatchFailureCode`).
+     *
+     * In atomic mode the handler reads the first failure's `status`/`code` to
+     * build the error response, so an increment-on-missing op keeps its 404 and a
+     * hook denial keeps its 403 instead of collapsing to a uniform 409.
+     */
+    status?: number;
+    code?: BatchFailureCode;
     values?: Record<string, number>;
+    /** Server-applied field values (#1476). See `SaveResponse.appliedFields`. */
+    appliedFields?: Record<string, any>;
 }
 interface BatchResponse {
     results: BatchOperationResult[];
@@ -1604,6 +1687,41 @@ interface LoadSchemaOptions {
  */
 declare function loadSchemaFromTomlString(tomlString: string, options?: LoadSchemaOptions): DefinedModelSchema[];
 
+/**
+ * Unique-constraint index helpers (shared CRDT contract).
+ *
+ * js-bao enforces unique constraints inside the Yjs document, not via a SQL
+ * `UNIQUE`. Each constraint has a `_uniqueIdx_<model>_<constraint>` map
+ * (uniqueKey -> surviving recordId) and a document observer that
+ * deterministically discards duplicate losers. Both the client write path and
+ * the server-direct write path (`mutateRecord` in js-bao-wss) must derive the
+ * key and the index map name the SAME way, or a server-written record would
+ * not be seen by the client-side resolver. These helpers are the single source
+ * of truth for that derivation so neither side keeps a parallel copy.
+ */
+
+/**
+ * Build the unique-constraint key for a record over the given fields.
+ *
+ * Mirrors the document-observer conflict resolver: a `null`/`undefined` value
+ * in any field means the record does not participate in the constraint (returns
+ * `null`); otherwise the per-field `String()` values joined by `"|"`. This is
+ * the key the `_uniqueIdx_*` map is read/written with during conflict
+ * resolution, so it is the key the resolver treats as authoritative.
+ */
+declare function buildUniqueKey(recordData: Y.Map<any> | Record<string, any>, fields: string[]): string | null;
+/**
+ * Name of the Yjs map that indexes a unique constraint within a document:
+ * `_uniqueIdx_<model>_<constraint>` mapping uniqueKey -> surviving recordId.
+ */
+declare function uniqueIndexMapName(modelName: string, constraintName: string): string;
+/**
+ * The constraint name js-bao assigns to a single-field `unique: true` field
+ * (see `resolveUniqueConstraints` in models/schema.ts). Compound constraints
+ * keep their author-given name instead.
+ */
+declare function fieldUniqueConstraintName(modelName: string, fieldName: string): string;
+
 /**
  * Meta Sync — writes _meta_* YMaps into a YDoc.
  *
@@ -1656,4 +1774,161 @@ declare function syncModelMeta(yDoc: Y.Doc, modelName: string, schema: ModelSche
  */
 declare function syncInferredMeta(yDoc: Y.Doc, modelName: string, recordData: Record<string, any>): void;
 
-export { type AfterQueryContext, type AfterQueryResult, type AggregateRequest, type AggregateResponse, type AggregationOperation, type AggregationOptions, type AggregationResult, type BatchOperation, type BatchOperationResult, type BatchRequest, type BatchResponse, type BeforeDeleteContext, type BeforeQueryContext, type BeforeQueryResult, type BeforeSaveContext, type ConnectDoDbOptions, type CountRequest, type CountResponse, DOClientEngine, type DOClientEngineConfig, type DatabaseDOHooks, type DeleteRequest, type DeleteResponse, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, type DoDb, type DocumentFilter, type DropIndexRequest, type DropIndexResponse, type DropUniqueConstraintRequest, type DropUniqueConstraintResponse, type ErrorResponse, type GroupByField, type HookContext, type HookResult, type IncrementRequest, type IncrementResponse, type IndexEntry, type IndexListResponse, type InitJsBaoDOOptions, type InitJsBaoDOResult, type ModelAccessor, type PaginatedResult, type PatchOptions, type PatchRequest, type PatchResponse, type ProjectionSpec, type QueryOptions, type QueryRequest, type QueryResponse, type RegisterIndexRequest, type RegisterIndexResponse, type RegisterUniqueConstraintRequest, type RegisterUniqueConstraintResponse, type SaveOptions, type SaveRequest, type SaveResponse, type SortSpec, type StringSetMembership, type StringSetUpdateRequest, type StringSetUpdateResponse, type SyncIndexesRequest, type SyncIndexesResponse, type UniqueConstraintEntry, type UniqueConstraintListResponse, type WriteCondition, clearMetaSyncCache, connectDoDb, discoverModelNames, discoverSchema, getActiveDOEngine, inferFieldType, initJsBaoDO, loadSchemaFromTomlString, registerFunctionDefault, resetJsBaoDO, schemaToToml, syncInferredMeta, syncModelMeta };
+/**
+ * Write lifecycle — shared, schema-keyed write behavior for both the js-bao
+ * client (`BaseModel.save()`) and the server-direct workflow write path
+ * (`mutateRecord` in js-bao-wss `src/yjs-room-v2.ts`).
+ *
+ * Background (#1246): the server re-implemented js-bao's client write behavior,
+ * so the two paths could drift and new js-bao field types were not picked up by
+ * workflow writes automatically. This module is the single source of truth for
+ * the *pure transform* (data + schema → Yjs structure), keyed only off schema
+ * metadata — no ORM concerns (reactivity, local-change tracking, document
+ * connection). Both paths call these helpers, so:
+ *
+ *   1. the stringset Yjs-shape primitives are written the same way on both sides;
+ *   2. schema `default`s and `autoStamp`s are applied the same way on both sides;
+ *   3. a new `FieldType` breaks `fieldWriteKind`'s exhaustive switch until it is
+ *      classified once — and the server, calling the same core, inherits it.
+ *
+ * The unique-index contract already lives in `../utils/uniqueIndex.ts`; this
+ * module is the same "neither side keeps a parallel copy" pattern generalized
+ * to the rest of the write lifecycle.
+ */
+
+/**
+ * Compile-time exhaustiveness guard. Passing a value whose type is not `never`
+ * is a TypeScript error, so an unhandled `case` in an exhaustive `switch` fails
+ * `tsc`. At runtime (reached only for a genuinely unknown value) it throws.
+ */
+declare function assertNever(x: never): never;
+/**
+ * How a field's declared type is written into the record Y.Map. Every member
+ * of the `FieldType` union must be classified here; adding a new field type to
+ * the union without a `case` below fails `pnpm typecheck` (via `assertNever`),
+ * which is what forces both write paths to handle it. (#1246, layer 2.)
+ */
+type FieldWriteKind = "scalar" | "stringset";
+declare function fieldWriteKind(type: FieldType): FieldWriteKind;
+/** True if `type` is a member of the `FieldType` union. */
+declare function isKnownFieldType(type: string): type is FieldType;
+/**
+ * Resolve (or migrate to) the canonical nested `Y.Map<boolean>` for a
+ * `stringset` field. A legacy plain-object value is carried over member by
+ * member; the nested map is never destroyed and rebuilt, so a concurrent
+ * client `.add()`/`.delete()` merges instead of being clobbered.
+ */
+declare function ensureStringSetYMap(rm: Y.Map<any>, fieldName: string): Y.Map<boolean>;
+interface StringSetDelta {
+    add?: Iterable<string>;
+    remove?: Iterable<string>;
+    clear?: boolean;
+}
+/**
+ * Apply a per-member DELTA to a stringset target map. `clear` empties the set
+ * first; then `remove` deletes, then `add` sets — so an `add` wins over a
+ * `remove` of the same member within one delta. Members not named are left
+ * untouched, so two concurrent `add`s of different members merge cleanly.
+ */
+declare function applyStringSetDelta(target: Y.Map<boolean>, delta: StringSetDelta): void;
+/**
+ * REPLACE a stringset field with exactly `members`, applied as a per-member
+ * CRDT diff (set members present, delete members no longer present) so a
+ * concurrent client edit merges instead of being clobbered by a
+ * destroy-and-rebuild.
+ */
+declare function replaceStringSet(rm: Y.Map<any>, fieldName: string, members: Iterable<unknown>): void;
+/**
+ * Apply the client save-diff stringset change shape (`{additions, removals}`)
+ * to the parent record's Y.Map. Thin wrapper over `applyStringSetDelta` so the
+ * js-bao client and the server write a stringset the exact same way.
+ */
+declare function applyStringSetChange(recordYMap: Y.Map<any>, fieldName: string, change: {
+    additions: Set<string>;
+    removals: Set<string>;
+}): void;
+interface ParsedStringSetOp {
+    add: string[];
+    remove: string[];
+    clear: boolean;
+}
+/**
+ * Recognize a `stringset` DELTA op-object inside a write payload:
+ * `{ $add?: string[], $remove?: string[], $clear?: true }`. Returns the
+ * normalized op, or `null` when `value` is not an op-object (a plain array
+ * keeps its REPLACE meaning; a scalar is a scalar). Throws on a malformed op
+ * (unknown `$key`, or `$add`/`$remove` not an array) so an author typo
+ * surfaces instead of silently writing nothing. (#1242, moved here in #1246.)
+ */
+declare function parseStringSetOp(value: unknown): ParsedStringSetOp | null;
+/**
+ * Write a single field's value into the record Y.Map according to the field's
+ * declared type. Scalars are `.set()` directly; a `stringset` takes an array
+ * (REPLACE) or a `{ $add/$remove/$clear }` op-object (DELTA). A collection
+ * value in a non-stringset slot, or a scalar in a stringset slot, is rejected
+ * (mirrors #1242 guardrails) rather than silently corrupting the record.
+ *
+ * `declaredType` is the resolved `_meta_` type (may be `undefined` when the doc
+ * has no `_meta_` for the model — first-writer / legacy). An unresolved or
+ * unknown type is treated as scalar for backward compatibility, but a
+ * collection value still requires a real `stringset` type.
+ */
+declare function writeField(rm: Y.Map<any>, declaredType: string | undefined, key: string, value: unknown, modelName: string): void;
+declare function registerFunctionDefaultGenerator(name: string, fn: () => any): void;
+declare function decodeFunctionDefault(name: string): (() => any) | undefined;
+interface SchemaFieldLike {
+    type?: string;
+    default?: any;
+    autoStamp?: "create" | "update" | "both";
+    required?: boolean;
+    unique?: boolean;
+}
+/**
+ * Resolve a field's declared default to a concrete value:
+ *  - a function → call it (client path holds real function refs);
+ *  - a `"$$literal"` string → an escaped literal; unescape the leading `$$` to
+ *    one `$` and use it verbatim (a literal default like `default: "$0.00"`,
+ *    which metaSync doubled on encode so it is not mistaken for a function ref);
+ *  - a `"$name"` string → decode via the registry and call it (server path,
+ *    where `_meta_` `$`-encodes function defaults);
+ *  - anything else → the literal value.
+ *
+ * An unknown `"$name"` throws (fail loud) rather than silently leaving the
+ * field unset or writing the literal `"$..."` string into the record — a
+ * missing server-populated field must not hide (#1246, Fork 3).
+ */
+declare function resolveDefaultValue(rawDefault: any, opts?: {
+    fieldName?: string;
+    modelName?: string;
+    decode?: (name: string) => (() => any) | undefined;
+}): any;
+/**
+ * Apply schema `default`s to a plain data object for a CREATE. A field with a
+ * declared default that the caller did not set (absent or `undefined`) is
+ * populated; an explicit caller value always wins. `id` is skipped — both
+ * paths assign the id separately. Pure: mutates and returns `data`.
+ */
+declare function applyDefaultsFromSchema(fields: Record<string, SchemaFieldLike>, data: Record<string, any>, opts?: {
+    modelName?: string;
+    decodeFunctionDefault?: (name: string) => (() => any) | undefined;
+}): Record<string, any>;
+/**
+ * Apply schema `autoStamp` timestamps to a plain data object. Pure transform,
+ * with `now` injected by the caller (server passes `Date.now()`; tests pass a
+ * fixed clock) so the result is deterministic and testable — no global clock.
+ *
+ * Semantics mirror the client `BaseModel.save()` stamp block:
+ *  - `'create'`  → stamp only when `isNew` and the caller did not set the field
+ *                  explicitly (a non-null value present in `data`);
+ *  - `'update'` / `'both'` → stamp on every save unless the caller set the
+ *                  field explicitly.
+ *
+ * An explicit caller value (present and non-null in `data`) always wins.
+ * Mutates and returns `data`.
+ */
+declare function applyAutoStampsFromSchema(fields: Record<string, SchemaFieldLike>, data: Record<string, any>, opts: {
+    isNew: boolean;
+    now: number;
+}): Record<string, any>;
+
+export { type AfterQueryContext, type AfterQueryResult, type AggregateRequest, type AggregateResponse, type AggregationOperation, type AggregationOptions, type AggregationResult, type BatchOperation, type BatchOperationResult, type BatchRequest, type BatchResponse, type BeforeDeleteContext, type BeforeQueryContext, type BeforeQueryResult, type BeforeSaveContext, type ConnectDoDbOptions, type CountRequest, type CountResponse, DOClientEngine, type DOClientEngineConfig, type DatabaseDOHooks, type DeleteRequest, type DeleteResponse, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, type DoDb, type DocumentFilter, type DropIndexRequest, type DropIndexResponse, type DropUniqueConstraintRequest, type DropUniqueConstraintResponse, type ErrorResponse, type FieldType, type FieldWriteKind, type GroupByField, type HookContext, type HookResult, type IncrementRequest, type IncrementResponse, type IndexEntry, type IndexListResponse, type InitJsBaoDOOptions, type InitJsBaoDOResult, type ModelAccessor, type PaginatedResult, type ParsedStringSetOp, type PatchOptions, type PatchRequest, type PatchResponse, type ProjectionSpec, type QueryOptions, type QueryRequest, type QueryResponse, type RegisterIndexRequest, type RegisterIndexResponse, type RegisterUniqueConstraintRequest, type RegisterUniqueConstraintResponse, type SaveOptions, type SaveRequest, type SaveResponse, type SchemaFieldLike, type SortSpec, type StringSetDelta, type StringSetMembership, type StringSetUpdateRequest, type StringSetUpdateResponse, type SyncIndexesRequest, type SyncIndexesResponse, type UniqueConstraintEntry, type UniqueConstraintListResponse, type WriteCondition, applyAutoStampsFromSchema, applyDefaultsFromSchema, applyStringSetChange, applyStringSetDelta, assertNever, buildUniqueKey, clearMetaSyncCache, connectDoDb, decodeFunctionDefault, discoverModelNames, discoverSchema, ensureStringSetYMap, fieldUniqueConstraintName, fieldWriteKind, getActiveDOEngine, inferFieldType, initJsBaoDO, isKnownFieldType, loadSchemaFromTomlString, parseStringSetOp, registerFunctionDefault, registerFunctionDefaultGenerator, replaceStringSet, resetJsBaoDO, resolveDefaultValue, schemaToToml, syncInferredMeta, syncModelMeta, uniqueIndexMapName, writeField };

package/dist/cloudflare.d.ts

@@ -563,6 +563,27 @@ declare class BaseModel implements StringSetChangeTracker {
      */
     static count(this: new (...args: any[]) => any, filter?: DocumentFilter, options?: Pick<QueryOptions, "documents">): Promise<number>;
     static findAll<T extends BaseModel>(this: new (...args: any[]) => T): Promise<T[]>;
+    /**
+     * Resolve a record by its unique-constraint field values via an engine query.
+     * Used as a fallback when the `_uniqueIdx_<model>_<constraint>` map has no
+     * entry for a key.
+     *
+     * The index map is a cache over the SQLite projection, not the source of
+     * truth: every record is loaded into the projection on `initializeForDocument`
+     * regardless of index presence, but a record written by a client predating
+     * index maintenance (legacy data) is missing from the index. Such a record
+     * silently escapes both `upsertByUnique` lookups and the `save()` uniqueness
+     * check. A query over the constraint fields finds it reliably.
+     *
+     * Contract: RESOLVE ONLY. Returns the owning record (with `_metaDocId` set to
+     * the document that holds it, via `queryOne`) or `null`. Callers decide
+     * whether to heal the missing index entry (write paths) and do their own
+     * logging — this method never mutates the index, so read paths stay
+     * read-only. Mirrors `buildUniqueKey`: a null/undefined value in any
+     * constraint field means the record does not participate in the constraint,
+     * so no query runs.
+     */
+    private static _resolveByUniqueFallback;
     static findByUnique<T extends BaseModel>(this: typeof BaseModel & (new (...args: any[]) => T), constraintName: string, value: any | any[]): Promise<T | null>;
     static upsertByUnique<T extends BaseModel>(this: typeof BaseModel & (new (...args: any[]) => T), constraintName: string, uniqueLookupValue: any | any[], dataToUpsert: Partial<Omit<InstanceType<new (...args: any[]) => T>, keyof BaseModel | "toJSON">> & {
         id?: string;
@@ -733,6 +754,18 @@ interface HookResult {
     allow: boolean;
     /** Reason for denial (returned to client as error message) */
     reason?: string;
+    /**
+     * Names of fields the hook wrote onto `ctx.data` that the DO should echo
+     * back to the caller in the write response's `appliedFields`. A `beforeSave`
+     * hook can compute and set fields on `ctx.data` (e.g. app-level triggers that
+     * derive a value from the submitted row); those values are persisted but are
+     * invisible to a caller that rebuilds a change event from its original
+     * submission inputs. Reporting the names here lets the DO read the final
+     * post-hook values back and thread them into `appliedFields` so the caller
+     * can propagate them (#1476). The hook contract stays generic — it names the
+     * fields it applied and does not need to know how the caller uses them.
+     */
+    serverAppliedFieldNames?: string[];
 }
 /** Result from beforeQuery hooks — can inject additional filters */
 interface BeforeQueryResult extends HookResult {
@@ -849,6 +882,20 @@ interface QueryResponse {
 interface SaveResponse {
     success: boolean;
     id: string;
+    /**
+     * Server-applied field values the DO wrote AFTER the caller's submission
+     * inputs were assembled, read back from the final post-hook `data`
+     * (#1476, consolidating the #1462 `stamps` channel). This is the single
+     * "server-applied fields" channel: it carries both the applied `autoStamps`
+     * timestamps and any fields a `beforeSave` hook reported via
+     * `serverAppliedFieldNames` (e.g. app-level trigger-computed values). Present
+     * only when at least one such field ended up with a value. Lets the Worker
+     * thread these values into the change-event `data` it broadcasts to
+     * subscribers — otherwise a `select`-listed stamped or trigger-computed field
+     * never reaches the frame, because the frame is rebuilt from the submission
+     * inputs (which predate the DO-side write).
+     */
+    appliedFields?: Record<string, any>;
 }
 interface DeleteResponse {
     success: boolean;
@@ -931,6 +978,8 @@ interface PatchRequest {
 interface PatchResponse {
     success: boolean;
     id: string;
+    /** Server-applied field values (#1476). See `SaveResponse.appliedFields`. */
+    appliedFields?: Record<string, any>;
 }
 interface BatchOperation {
     op: "save" | "patch" | "delete" | "increment" | "addToSet" | "removeFromSet";
@@ -958,12 +1007,46 @@ interface BatchOperation {
 }
 interface BatchRequest {
     operations: BatchOperation[];
+    /**
+     * All-or-nothing execution (#1478). When `true`, the FIRST operation that
+     * fails inside the transaction — hook denial, condition / `ifNotExists` /
+     * unique violation, record-not-found, or upsert validation error — aborts
+     * the whole batch: every write is rolled back and the handler returns an
+     * error naming the failed step with its natural HTTP status (see
+     * `BatchOperationResult.status`). When `false` or absent (the default), each
+     * operation's outcome is recorded independently and successful siblings
+     * commit — the partial-success behavior import-bulk and applyToQuery rely on.
+     */
+    atomic?: boolean;
 }
+/**
+ * Stable, machine-readable failure tag on a failed `BatchOperationResult`
+ * (#1478). Derived at each failure site — never inferred from the `error`
+ * string. `#1389` (conditional writes + fencing-token enforcement) surfaces its
+ * condition / stale-token rejections through this same channel.
+ */
+type BatchFailureCode = "NOT_FOUND" | "HOOK_DENIED" | "CONDITION_NOT_MET" | "ALREADY_EXISTS" | "UNIQUE_VIOLATION" | "VALIDATION_ERROR";
 interface BatchOperationResult {
     success: boolean;
     id: string;
     error?: string;
+    /**
+     * Structured failure metadata (#1478), present only on a failed result. Both
+     * are derived at the failure site, not parsed back out of `error`:
+     *  - `status` — the natural HTTP status for the cause (404 not found,
+     *    403 hook denial, 409 condition / `ifNotExists` / unique conflict,
+     *    400 upsert validation).
+     *  - `code` — a stable machine-readable tag (see `BatchFailureCode`).
+     *
+     * In atomic mode the handler reads the first failure's `status`/`code` to
+     * build the error response, so an increment-on-missing op keeps its 404 and a
+     * hook denial keeps its 403 instead of collapsing to a uniform 409.
+     */
+    status?: number;
+    code?: BatchFailureCode;
     values?: Record<string, number>;
+    /** Server-applied field values (#1476). See `SaveResponse.appliedFields`. */
+    appliedFields?: Record<string, any>;
 }
 interface BatchResponse {
     results: BatchOperationResult[];
@@ -1604,6 +1687,41 @@ interface LoadSchemaOptions {
  */
 declare function loadSchemaFromTomlString(tomlString: string, options?: LoadSchemaOptions): DefinedModelSchema[];
 
+/**
+ * Unique-constraint index helpers (shared CRDT contract).
+ *
+ * js-bao enforces unique constraints inside the Yjs document, not via a SQL
+ * `UNIQUE`. Each constraint has a `_uniqueIdx_<model>_<constraint>` map
+ * (uniqueKey -> surviving recordId) and a document observer that
+ * deterministically discards duplicate losers. Both the client write path and
+ * the server-direct write path (`mutateRecord` in js-bao-wss) must derive the
+ * key and the index map name the SAME way, or a server-written record would
+ * not be seen by the client-side resolver. These helpers are the single source
+ * of truth for that derivation so neither side keeps a parallel copy.
+ */
+
+/**
+ * Build the unique-constraint key for a record over the given fields.
+ *
+ * Mirrors the document-observer conflict resolver: a `null`/`undefined` value
+ * in any field means the record does not participate in the constraint (returns
+ * `null`); otherwise the per-field `String()` values joined by `"|"`. This is
+ * the key the `_uniqueIdx_*` map is read/written with during conflict
+ * resolution, so it is the key the resolver treats as authoritative.
+ */
+declare function buildUniqueKey(recordData: Y.Map<any> | Record<string, any>, fields: string[]): string | null;
+/**
+ * Name of the Yjs map that indexes a unique constraint within a document:
+ * `_uniqueIdx_<model>_<constraint>` mapping uniqueKey -> surviving recordId.
+ */
+declare function uniqueIndexMapName(modelName: string, constraintName: string): string;
+/**
+ * The constraint name js-bao assigns to a single-field `unique: true` field
+ * (see `resolveUniqueConstraints` in models/schema.ts). Compound constraints
+ * keep their author-given name instead.
+ */
+declare function fieldUniqueConstraintName(modelName: string, fieldName: string): string;
+
 /**
  * Meta Sync — writes _meta_* YMaps into a YDoc.
  *
@@ -1656,4 +1774,161 @@ declare function syncModelMeta(yDoc: Y.Doc, modelName: string, schema: ModelSche
  */
 declare function syncInferredMeta(yDoc: Y.Doc, modelName: string, recordData: Record<string, any>): void;
 
-export { type AfterQueryContext, type AfterQueryResult, type AggregateRequest, type AggregateResponse, type AggregationOperation, type AggregationOptions, type AggregationResult, type BatchOperation, type BatchOperationResult, type BatchRequest, type BatchResponse, type BeforeDeleteContext, type BeforeQueryContext, type BeforeQueryResult, type BeforeSaveContext, type ConnectDoDbOptions, type CountRequest, type CountResponse, DOClientEngine, type DOClientEngineConfig, type DatabaseDOHooks, type DeleteRequest, type DeleteResponse, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, type DoDb, type DocumentFilter, type DropIndexRequest, type DropIndexResponse, type DropUniqueConstraintRequest, type DropUniqueConstraintResponse, type ErrorResponse, type GroupByField, type HookContext, type HookResult, type IncrementRequest, type IncrementResponse, type IndexEntry, type IndexListResponse, type InitJsBaoDOOptions, type InitJsBaoDOResult, type ModelAccessor, type PaginatedResult, type PatchOptions, type PatchRequest, type PatchResponse, type ProjectionSpec, type QueryOptions, type QueryRequest, type QueryResponse, type RegisterIndexRequest, type RegisterIndexResponse, type RegisterUniqueConstraintRequest, type RegisterUniqueConstraintResponse, type SaveOptions, type SaveRequest, type SaveResponse, type SortSpec, type StringSetMembership, type StringSetUpdateRequest, type StringSetUpdateResponse, type SyncIndexesRequest, type SyncIndexesResponse, type UniqueConstraintEntry, type UniqueConstraintListResponse, type WriteCondition, clearMetaSyncCache, connectDoDb, discoverModelNames, discoverSchema, getActiveDOEngine, inferFieldType, initJsBaoDO, loadSchemaFromTomlString, registerFunctionDefault, resetJsBaoDO, schemaToToml, syncInferredMeta, syncModelMeta };
+/**
+ * Write lifecycle — shared, schema-keyed write behavior for both the js-bao
+ * client (`BaseModel.save()`) and the server-direct workflow write path
+ * (`mutateRecord` in js-bao-wss `src/yjs-room-v2.ts`).
+ *
+ * Background (#1246): the server re-implemented js-bao's client write behavior,
+ * so the two paths could drift and new js-bao field types were not picked up by
+ * workflow writes automatically. This module is the single source of truth for
+ * the *pure transform* (data + schema → Yjs structure), keyed only off schema
+ * metadata — no ORM concerns (reactivity, local-change tracking, document
+ * connection). Both paths call these helpers, so:
+ *
+ *   1. the stringset Yjs-shape primitives are written the same way on both sides;
+ *   2. schema `default`s and `autoStamp`s are applied the same way on both sides;
+ *   3. a new `FieldType` breaks `fieldWriteKind`'s exhaustive switch until it is
+ *      classified once — and the server, calling the same core, inherits it.
+ *
+ * The unique-index contract already lives in `../utils/uniqueIndex.ts`; this
+ * module is the same "neither side keeps a parallel copy" pattern generalized
+ * to the rest of the write lifecycle.
+ */
+
+/**
+ * Compile-time exhaustiveness guard. Passing a value whose type is not `never`
+ * is a TypeScript error, so an unhandled `case` in an exhaustive `switch` fails
+ * `tsc`. At runtime (reached only for a genuinely unknown value) it throws.
+ */
+declare function assertNever(x: never): never;
+/**
+ * How a field's declared type is written into the record Y.Map. Every member
+ * of the `FieldType` union must be classified here; adding a new field type to
+ * the union without a `case` below fails `pnpm typecheck` (via `assertNever`),
+ * which is what forces both write paths to handle it. (#1246, layer 2.)
+ */
+type FieldWriteKind = "scalar" | "stringset";
+declare function fieldWriteKind(type: FieldType): FieldWriteKind;
+/** True if `type` is a member of the `FieldType` union. */
+declare function isKnownFieldType(type: string): type is FieldType;
+/**
+ * Resolve (or migrate to) the canonical nested `Y.Map<boolean>` for a
+ * `stringset` field. A legacy plain-object value is carried over member by
+ * member; the nested map is never destroyed and rebuilt, so a concurrent
+ * client `.add()`/`.delete()` merges instead of being clobbered.
+ */
+declare function ensureStringSetYMap(rm: Y.Map<any>, fieldName: string): Y.Map<boolean>;
+interface StringSetDelta {
+    add?: Iterable<string>;
+    remove?: Iterable<string>;
+    clear?: boolean;
+}
+/**
+ * Apply a per-member DELTA to a stringset target map. `clear` empties the set
+ * first; then `remove` deletes, then `add` sets — so an `add` wins over a
+ * `remove` of the same member within one delta. Members not named are left
+ * untouched, so two concurrent `add`s of different members merge cleanly.
+ */
+declare function applyStringSetDelta(target: Y.Map<boolean>, delta: StringSetDelta): void;
+/**
+ * REPLACE a stringset field with exactly `members`, applied as a per-member
+ * CRDT diff (set members present, delete members no longer present) so a
+ * concurrent client edit merges instead of being clobbered by a
+ * destroy-and-rebuild.
+ */
+declare function replaceStringSet(rm: Y.Map<any>, fieldName: string, members: Iterable<unknown>): void;
+/**
+ * Apply the client save-diff stringset change shape (`{additions, removals}`)
+ * to the parent record's Y.Map. Thin wrapper over `applyStringSetDelta` so the
+ * js-bao client and the server write a stringset the exact same way.
+ */
+declare function applyStringSetChange(recordYMap: Y.Map<any>, fieldName: string, change: {
+    additions: Set<string>;
+    removals: Set<string>;
+}): void;
+interface ParsedStringSetOp {
+    add: string[];
+    remove: string[];
+    clear: boolean;
+}
+/**
+ * Recognize a `stringset` DELTA op-object inside a write payload:
+ * `{ $add?: string[], $remove?: string[], $clear?: true }`. Returns the
+ * normalized op, or `null` when `value` is not an op-object (a plain array
+ * keeps its REPLACE meaning; a scalar is a scalar). Throws on a malformed op
+ * (unknown `$key`, or `$add`/`$remove` not an array) so an author typo
+ * surfaces instead of silently writing nothing. (#1242, moved here in #1246.)
+ */
+declare function parseStringSetOp(value: unknown): ParsedStringSetOp | null;
+/**
+ * Write a single field's value into the record Y.Map according to the field's
+ * declared type. Scalars are `.set()` directly; a `stringset` takes an array
+ * (REPLACE) or a `{ $add/$remove/$clear }` op-object (DELTA). A collection
+ * value in a non-stringset slot, or a scalar in a stringset slot, is rejected
+ * (mirrors #1242 guardrails) rather than silently corrupting the record.
+ *
+ * `declaredType` is the resolved `_meta_` type (may be `undefined` when the doc
+ * has no `_meta_` for the model — first-writer / legacy). An unresolved or
+ * unknown type is treated as scalar for backward compatibility, but a
+ * collection value still requires a real `stringset` type.
+ */
+declare function writeField(rm: Y.Map<any>, declaredType: string | undefined, key: string, value: unknown, modelName: string): void;
+declare function registerFunctionDefaultGenerator(name: string, fn: () => any): void;
+declare function decodeFunctionDefault(name: string): (() => any) | undefined;
+interface SchemaFieldLike {
+    type?: string;
+    default?: any;
+    autoStamp?: "create" | "update" | "both";
+    required?: boolean;
+    unique?: boolean;
+}
+/**
+ * Resolve a field's declared default to a concrete value:
+ *  - a function → call it (client path holds real function refs);
+ *  - a `"$$literal"` string → an escaped literal; unescape the leading `$$` to
+ *    one `$` and use it verbatim (a literal default like `default: "$0.00"`,
+ *    which metaSync doubled on encode so it is not mistaken for a function ref);
+ *  - a `"$name"` string → decode via the registry and call it (server path,
+ *    where `_meta_` `$`-encodes function defaults);
+ *  - anything else → the literal value.
+ *
+ * An unknown `"$name"` throws (fail loud) rather than silently leaving the
+ * field unset or writing the literal `"$..."` string into the record — a
+ * missing server-populated field must not hide (#1246, Fork 3).
+ */
+declare function resolveDefaultValue(rawDefault: any, opts?: {
+    fieldName?: string;
+    modelName?: string;
+    decode?: (name: string) => (() => any) | undefined;
+}): any;
+/**
+ * Apply schema `default`s to a plain data object for a CREATE. A field with a
+ * declared default that the caller did not set (absent or `undefined`) is
+ * populated; an explicit caller value always wins. `id` is skipped — both
+ * paths assign the id separately. Pure: mutates and returns `data`.
+ */
+declare function applyDefaultsFromSchema(fields: Record<string, SchemaFieldLike>, data: Record<string, any>, opts?: {
+    modelName?: string;
+    decodeFunctionDefault?: (name: string) => (() => any) | undefined;
+}): Record<string, any>;
+/**
+ * Apply schema `autoStamp` timestamps to a plain data object. Pure transform,
+ * with `now` injected by the caller (server passes `Date.now()`; tests pass a
+ * fixed clock) so the result is deterministic and testable — no global clock.
+ *
+ * Semantics mirror the client `BaseModel.save()` stamp block:
+ *  - `'create'`  → stamp only when `isNew` and the caller did not set the field
+ *                  explicitly (a non-null value present in `data`);
+ *  - `'update'` / `'both'` → stamp on every save unless the caller set the
+ *                  field explicitly.
+ *
+ * An explicit caller value (present and non-null in `data`) always wins.
+ * Mutates and returns `data`.
+ */
+declare function applyAutoStampsFromSchema(fields: Record<string, SchemaFieldLike>, data: Record<string, any>, opts: {
+    isNew: boolean;
+    now: number;
+}): Record<string, any>;
+
+export { type AfterQueryContext, type AfterQueryResult, type AggregateRequest, type AggregateResponse, type AggregationOperation, type AggregationOptions, type AggregationResult, type BatchOperation, type BatchOperationResult, type BatchRequest, type BatchResponse, type BeforeDeleteContext, type BeforeQueryContext, type BeforeQueryResult, type BeforeSaveContext, type ConnectDoDbOptions, type CountRequest, type CountResponse, DOClientEngine, type DOClientEngineConfig, type DatabaseDOHooks, type DeleteRequest, type DeleteResponse, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, type DoDb, type DocumentFilter, type DropIndexRequest, type DropIndexResponse, type DropUniqueConstraintRequest, type DropUniqueConstraintResponse, type ErrorResponse, type FieldType, type FieldWriteKind, type GroupByField, type HookContext, type HookResult, type IncrementRequest, type IncrementResponse, type IndexEntry, type IndexListResponse, type InitJsBaoDOOptions, type InitJsBaoDOResult, type ModelAccessor, type PaginatedResult, type ParsedStringSetOp, type PatchOptions, type PatchRequest, type PatchResponse, type ProjectionSpec, type QueryOptions, type QueryRequest, type QueryResponse, type RegisterIndexRequest, type RegisterIndexResponse, type RegisterUniqueConstraintRequest, type RegisterUniqueConstraintResponse, type SaveOptions, type SaveRequest, type SaveResponse, type SchemaFieldLike, type SortSpec, type StringSetDelta, type StringSetMembership, type StringSetUpdateRequest, type StringSetUpdateResponse, type SyncIndexesRequest, type SyncIndexesResponse, type UniqueConstraintEntry, type UniqueConstraintListResponse, type WriteCondition, applyAutoStampsFromSchema, applyDefaultsFromSchema, applyStringSetChange, applyStringSetDelta, assertNever, buildUniqueKey, clearMetaSyncCache, connectDoDb, decodeFunctionDefault, discoverModelNames, discoverSchema, ensureStringSetYMap, fieldUniqueConstraintName, fieldWriteKind, getActiveDOEngine, inferFieldType, initJsBaoDO, isKnownFieldType, loadSchemaFromTomlString, parseStringSetOp, registerFunctionDefault, registerFunctionDefaultGenerator, replaceStringSet, resetJsBaoDO, resolveDefaultValue, schemaToToml, syncInferredMeta, syncModelMeta, uniqueIndexMapName, writeField };