js-bao 0.5.0 → 0.5.2

package/dist/node.d.cts

@@ -31,8 +31,32 @@ interface FieldOptions {
     unique?: boolean;
     default?: any | (() => any);
     autoAssign?: boolean;
+    /**
+     * Auto-timestamp this field with `Date.now()` (milliseconds) on save.
+     *
+     * - `'create'` — stamp only on the first save (when `isNew === true`).
+     * - `'update'` — stamp on every save (create AND update).
+     * - `'both'`   — stamp on every save (create AND update).
+     *
+     * If the caller passes an explicit value for the field in `data`, the
+     * explicit value wins and the stamp is skipped. The stamp is applied
+     * in `beforeSave` BEFORE any user-defined hooks, so user hooks may
+     * still overwrite the value if they wish (last writer wins).
+     */
+    autoStamp?: "create" | "update" | "both";
     maxLength?: number;
     maxCount?: number;
+    /**
+     * Allowed-value set for a `string` field. When present, the codegen
+     * generators (database-type codegen + doc-model v2 codegen) emit a
+     * TypeScript string-literal union (`"a" | "b" | "c"`) instead of a bare
+     * `string` for this field.
+     *
+     * Advisory / codegen-only: this is a TS-emission hint. The runtime and the
+     * server do NOT enforce enum membership on write (see #843). Only valid on
+     * `string` fields, and must be a non-empty array of strings.
+     */
+    enum?: string[];
 }
 interface UniqueConstraintConfig {
     name: string;
@@ -495,6 +519,17 @@ declare class BaseModel implements StringSetChangeTracker {
     private ensureLocalChanges;
     private hasLocalChange;
     private getFromYjs;
+    /**
+     * Defensive normalization for the read/sync boundary (issue #625).
+     *
+     * Stringset fields are owned by getStringSetFromYjs (which expects the
+     * raw Y.Map / legacy plain-object shape — #561 / #601), so they pass
+     * through untouched. For any other field, a composite Yjs primitive
+     * (Y.Map / Y.Array / Y.Text) must never reach user code or the DB layer
+     * raw: normalize it to its plain-JS projection (toJSON / toString) and
+     * warn, rather than throwing. Scalars pass through unchanged.
+     */
+    private normalizeNonStringSetValue;
     private getValue;
     private setValue;
     get isDirty(): boolean;
@@ -629,6 +664,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;
@@ -951,6 +1007,7 @@ interface DiscoveredField {
     required?: boolean;
     default?: string | number | boolean;
     autoAssign?: boolean;
+    autoStamp?: "create" | "update" | "both";
     maxLength?: number;
     maxCount?: number;
 }
@@ -1044,6 +1101,11 @@ declare function loadSchemaFromToml(filePath: string, options?: LoadSchemaOption
 
 /**
  * Infer a _meta_ type string from a JS runtime value.
+ *
+ * Only an all-`true` Y.Map (the stringset wire shape) is tagged as
+ * `stringset` (issue #625) — a Y.Map carrying a composite payload, or a
+ * Y.Array / Y.Text, is not a stringset and stays untyped (`null`) rather
+ * than being mis-tagged.
  */
 declare function inferFieldType(value: unknown): "string" | "number" | "boolean" | "stringset" | null;
 /**
@@ -1075,6 +1137,163 @@ declare function syncModelMeta(yDoc: Y.Doc, modelName: string, schema: ModelSche
  */
 declare function syncInferredMeta(yDoc: Y.Doc, modelName: string, recordData: Record<string, any>): void;
 
+/**
+ * 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>;
+
 interface DumpOptions {
     includeIndexes?: boolean;
 }
@@ -1118,4 +1337,4 @@ declare function summarizePlainYDoc(dump: PlainYDoc): DumpSummary;
 
 declare function getRecommendedNodeEngine(): Promise<string>;
 
-export { type AddRelationMethod, type AggregationAliasDebugInfo, type AggregationOperation, type AggregationOptions, type AggregationResult, BaseModel, type DatabaseConfig, DatabaseEngine, type DatabaseEngineOptions, type DatabaseEngineType, NodeDatabaseFactory as DatabaseFactory, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, type DumpOptions, type DumpSummary, type DumpSummaryEntry, type FieldOptions, type FieldType, type GroupByField, type HasManyMethod, type HasManyThroughMethod, type InferAttrs, type InitJsBaoOptions, type InitJsBaoResult, LogLevel, Logger, type ModelConstructor, type ModelOptions, ModelRegistry, type NodeSqliteEngineOptions, type PaginatedResult, type PaginationOptions, type PlainYDoc, RecordNotFoundError, type RefersToMethod, type RegisteredModelInfo, type RemoveRelationMethod, type SQLJSEngineOptions, type Schema, SqljsEngine, type SqljsEngineOptions, StringSet, type StringSetMembership, type UniqueConstraintConfig, UniqueConstraintViolationError, attachAndRegisterModel, attachSchemaToClass, autoRegisterModel, clearMetaSyncCache, constants, createModelClass, defineModelSchema, detectEnvironment, discoverModelNames, discoverSchema, dumpYDocToPlain, features, generateULID, getRecommendedNodeEngine, inferFieldType, initJsBao, isBrowser, isNode, isNodeModuleAvailable, loadSchemaFromToml, loadSchemaFromTomlString, registerFunctionDefault, resetJsBao, schemaToToml, summarizePlainYDoc, syncInferredMeta, syncModelMeta };
+export { type AddRelationMethod, type AggregationAliasDebugInfo, type AggregationOperation, type AggregationOptions, type AggregationResult, BaseModel, type DatabaseConfig, DatabaseEngine, type DatabaseEngineOptions, type DatabaseEngineType, NodeDatabaseFactory as DatabaseFactory, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, type DumpOptions, type DumpSummary, type DumpSummaryEntry, type FieldOptions, type FieldType, type FieldWriteKind, type GroupByField, type HasManyMethod, type HasManyThroughMethod, type InferAttrs, type InitJsBaoOptions, type InitJsBaoResult, LogLevel, Logger, type ModelConstructor, type ModelOptions, ModelRegistry, type NodeSqliteEngineOptions, type PaginatedResult, type PaginationOptions, type ParsedStringSetOp, type PlainYDoc, RecordNotFoundError, type RefersToMethod, type RegisteredModelInfo, type RemoveRelationMethod, type SQLJSEngineOptions, type Schema, type SchemaFieldLike, SqljsEngine, type SqljsEngineOptions, StringSet, type StringSetDelta, type StringSetMembership, type UniqueConstraintConfig, UniqueConstraintViolationError, applyAutoStampsFromSchema, applyDefaultsFromSchema, applyStringSetChange, applyStringSetDelta, assertNever, attachAndRegisterModel, attachSchemaToClass, autoRegisterModel, clearMetaSyncCache, constants, createModelClass, decodeFunctionDefault, defineModelSchema, detectEnvironment, discoverModelNames, discoverSchema, dumpYDocToPlain, ensureStringSetYMap, features, fieldWriteKind, generateULID, getRecommendedNodeEngine, inferFieldType, initJsBao, isBrowser, isKnownFieldType, isNode, isNodeModuleAvailable, loadSchemaFromToml, loadSchemaFromTomlString, parseStringSetOp, registerFunctionDefault, registerFunctionDefaultGenerator, replaceStringSet, resetJsBao, resolveDefaultValue, schemaToToml, summarizePlainYDoc, syncInferredMeta, syncModelMeta, writeField };

package/dist/node.d.ts

@@ -31,8 +31,32 @@ interface FieldOptions {
     unique?: boolean;
     default?: any | (() => any);
     autoAssign?: boolean;
+    /**
+     * Auto-timestamp this field with `Date.now()` (milliseconds) on save.
+     *
+     * - `'create'` — stamp only on the first save (when `isNew === true`).
+     * - `'update'` — stamp on every save (create AND update).
+     * - `'both'`   — stamp on every save (create AND update).
+     *
+     * If the caller passes an explicit value for the field in `data`, the
+     * explicit value wins and the stamp is skipped. The stamp is applied
+     * in `beforeSave` BEFORE any user-defined hooks, so user hooks may
+     * still overwrite the value if they wish (last writer wins).
+     */
+    autoStamp?: "create" | "update" | "both";
     maxLength?: number;
     maxCount?: number;
+    /**
+     * Allowed-value set for a `string` field. When present, the codegen
+     * generators (database-type codegen + doc-model v2 codegen) emit a
+     * TypeScript string-literal union (`"a" | "b" | "c"`) instead of a bare
+     * `string` for this field.
+     *
+     * Advisory / codegen-only: this is a TS-emission hint. The runtime and the
+     * server do NOT enforce enum membership on write (see #843). Only valid on
+     * `string` fields, and must be a non-empty array of strings.
+     */
+    enum?: string[];
 }
 interface UniqueConstraintConfig {
     name: string;
@@ -495,6 +519,17 @@ declare class BaseModel implements StringSetChangeTracker {
     private ensureLocalChanges;
     private hasLocalChange;
     private getFromYjs;
+    /**
+     * Defensive normalization for the read/sync boundary (issue #625).
+     *
+     * Stringset fields are owned by getStringSetFromYjs (which expects the
+     * raw Y.Map / legacy plain-object shape — #561 / #601), so they pass
+     * through untouched. For any other field, a composite Yjs primitive
+     * (Y.Map / Y.Array / Y.Text) must never reach user code or the DB layer
+     * raw: normalize it to its plain-JS projection (toJSON / toString) and
+     * warn, rather than throwing. Scalars pass through unchanged.
+     */
+    private normalizeNonStringSetValue;
     private getValue;
     private setValue;
     get isDirty(): boolean;
@@ -629,6 +664,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;
@@ -951,6 +1007,7 @@ interface DiscoveredField {
     required?: boolean;
     default?: string | number | boolean;
     autoAssign?: boolean;
+    autoStamp?: "create" | "update" | "both";
     maxLength?: number;
     maxCount?: number;
 }
@@ -1044,6 +1101,11 @@ declare function loadSchemaFromToml(filePath: string, options?: LoadSchemaOption
 
 /**
  * Infer a _meta_ type string from a JS runtime value.
+ *
+ * Only an all-`true` Y.Map (the stringset wire shape) is tagged as
+ * `stringset` (issue #625) — a Y.Map carrying a composite payload, or a
+ * Y.Array / Y.Text, is not a stringset and stays untyped (`null`) rather
+ * than being mis-tagged.
  */
 declare function inferFieldType(value: unknown): "string" | "number" | "boolean" | "stringset" | null;
 /**
@@ -1075,6 +1137,163 @@ declare function syncModelMeta(yDoc: Y.Doc, modelName: string, schema: ModelSche
  */
 declare function syncInferredMeta(yDoc: Y.Doc, modelName: string, recordData: Record<string, any>): void;
 
+/**
+ * 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>;
+
 interface DumpOptions {
     includeIndexes?: boolean;
 }
@@ -1118,4 +1337,4 @@ declare function summarizePlainYDoc(dump: PlainYDoc): DumpSummary;
 
 declare function getRecommendedNodeEngine(): Promise<string>;
 
-export { type AddRelationMethod, type AggregationAliasDebugInfo, type AggregationOperation, type AggregationOptions, type AggregationResult, BaseModel, type DatabaseConfig, DatabaseEngine, type DatabaseEngineOptions, type DatabaseEngineType, NodeDatabaseFactory as DatabaseFactory, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, type DumpOptions, type DumpSummary, type DumpSummaryEntry, type FieldOptions, type FieldType, type GroupByField, type HasManyMethod, type HasManyThroughMethod, type InferAttrs, type InitJsBaoOptions, type InitJsBaoResult, LogLevel, Logger, type ModelConstructor, type ModelOptions, ModelRegistry, type NodeSqliteEngineOptions, type PaginatedResult, type PaginationOptions, type PlainYDoc, RecordNotFoundError, type RefersToMethod, type RegisteredModelInfo, type RemoveRelationMethod, type SQLJSEngineOptions, type Schema, SqljsEngine, type SqljsEngineOptions, StringSet, type StringSetMembership, type UniqueConstraintConfig, UniqueConstraintViolationError, attachAndRegisterModel, attachSchemaToClass, autoRegisterModel, clearMetaSyncCache, constants, createModelClass, defineModelSchema, detectEnvironment, discoverModelNames, discoverSchema, dumpYDocToPlain, features, generateULID, getRecommendedNodeEngine, inferFieldType, initJsBao, isBrowser, isNode, isNodeModuleAvailable, loadSchemaFromToml, loadSchemaFromTomlString, registerFunctionDefault, resetJsBao, schemaToToml, summarizePlainYDoc, syncInferredMeta, syncModelMeta };
+export { type AddRelationMethod, type AggregationAliasDebugInfo, type AggregationOperation, type AggregationOptions, type AggregationResult, BaseModel, type DatabaseConfig, DatabaseEngine, type DatabaseEngineOptions, type DatabaseEngineType, NodeDatabaseFactory as DatabaseFactory, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, type DumpOptions, type DumpSummary, type DumpSummaryEntry, type FieldOptions, type FieldType, type FieldWriteKind, type GroupByField, type HasManyMethod, type HasManyThroughMethod, type InferAttrs, type InitJsBaoOptions, type InitJsBaoResult, LogLevel, Logger, type ModelConstructor, type ModelOptions, ModelRegistry, type NodeSqliteEngineOptions, type PaginatedResult, type PaginationOptions, type ParsedStringSetOp, type PlainYDoc, RecordNotFoundError, type RefersToMethod, type RegisteredModelInfo, type RemoveRelationMethod, type SQLJSEngineOptions, type Schema, type SchemaFieldLike, SqljsEngine, type SqljsEngineOptions, StringSet, type StringSetDelta, type StringSetMembership, type UniqueConstraintConfig, UniqueConstraintViolationError, applyAutoStampsFromSchema, applyDefaultsFromSchema, applyStringSetChange, applyStringSetDelta, assertNever, attachAndRegisterModel, attachSchemaToClass, autoRegisterModel, clearMetaSyncCache, constants, createModelClass, decodeFunctionDefault, defineModelSchema, detectEnvironment, discoverModelNames, discoverSchema, dumpYDocToPlain, ensureStringSetYMap, features, fieldWriteKind, generateULID, getRecommendedNodeEngine, inferFieldType, initJsBao, isBrowser, isKnownFieldType, isNode, isNodeModuleAvailable, loadSchemaFromToml, loadSchemaFromTomlString, parseStringSetOp, registerFunctionDefault, registerFunctionDefaultGenerator, replaceStringSet, resetJsBao, resolveDefaultValue, schemaToToml, summarizePlainYDoc, syncInferredMeta, syncModelMeta, writeField };