@happyvertical/smrt-core 0.45.3 → 0.47.0

package/dist/decorators/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/decorators/index.ts"],"sourcesContent":["/**\n * Field decorators for SMRT objects\n *\n * Modern decorator-based API for defining SMRT object properties.\n * Properties are typed as primitives with decorator metadata.\n */\n\nimport { ObjectRegistry } from '../registry.js';\nimport type { FieldUIHints } from '../scanner/types.js';\nimport type { SQLDataType } from '../schema/types.js';\nimport {\n  type CompatiblePropertyDecorator,\n  type CompatiblePropertyDecoratorContext,\n  type LegacyPropertyDecoratorTarget,\n  registerCompatibleFieldDecorator,\n} from './compatibility.js';\n\nexport type { FieldUIHints } from '../scanner/types.js';\n\n/**\n * Meta type wrapper for STI (Single Table Inheritance) meta fields\n *\n * Fields typed as Meta<T> are stored in the _meta_data JSONB column\n * rather than as direct table columns. Used for child-specific fields\n * in STI hierarchies.\n *\n * @example\n * ```typescript\n * @smrt({ tableStrategy: 'sti' })\n * class Event extends SmrtObject {\n *   title: string = '';\n * }\n *\n * @smrt()\n * class Meeting extends Event {\n *   // Stored in _meta_data JSONB column\n *   roomNumber: Meta<string> = '';\n *   attendees: Meta<string[]> = [];\n * }\n * ```\n */\nexport type Meta<T> = T;\n\n/**\n * Base field options\n */\nexport type PrimitiveFieldType =\n  | 'text'\n  | 'integer'\n  | 'decimal'\n  | 'boolean'\n  | 'datetime'\n  | 'json';\n\nexport type FieldType =\n  | PrimitiveFieldType\n  | 'meta'\n  | 'foreignKey'\n  | 'crossPackageRef'\n  | 'oneToMany'\n  | 'manyToMany';\n\nexport interface FieldOptions {\n  /** Explicit field type for runtime-only registration paths */\n  type?: FieldType;\n  /** Explicit SQL storage type when runtime and persistence contracts differ */\n  sqlType?: SQLDataType;\n  /** Whether the field is required */\n  required?: boolean;\n  /** Default value for the field */\n  default?: unknown;\n  /** Whether the field is unique */\n  unique?: boolean;\n  /**\n   * When `true`, the schema emits a database index targeting this field.\n   *\n   * For regular (column-backed) fields the index is a plain column index.\n   * For `@meta()` fields stored inside `_meta_data` JSONB, the index targets\n   * the JSON path — `json_extract(_meta_data, '$.fieldName')` on SQLite,\n   * `(_meta_data->>'fieldName')` on Postgres.\n   *\n   * Note that `collection.list({ where })` cannot currently reach a JSON-path\n   * index: dot-notation keys such as `_meta_data.fieldName` are rejected,\n   * because nothing rewrites them into the matching extraction expression\n   * (#2276, tracked in #2282). The index is still emitted and still serves\n   * hand-written SQL that spells the expression out; it just has no\n   * collection-level query to accelerate yet.\n   */\n  indexed?: boolean;\n  /** Whether the field is nullable */\n  nullable?: boolean;\n  /** Whether the field should be excluded from database */\n  transient?: boolean;\n  /**\n   * Marks the field as sensitive (e.g. API secrets, credentials, tax IDs).\n   *\n   * Sensitive fields are still persisted to the database, but the framework:\n   * - excludes them from `toPublicJSON()` (the serializer used by generated\n   *   REST/MCP/SvelteKit routes), so they never appear in API responses; and\n   * - rejects them as `where`-clause filter keys, closing the\n   *   `?secret[like]=...` value-probing oracle.\n   *\n   * Use this for any column that holds a secret value that must never be\n   * read back over a generated network surface.\n   */\n  sensitive?: boolean;\n  /**\n   * Marks the field as read-only over generated write surfaces.\n   *\n   * Read-only fields are stripped from the request body before\n   * `create`/`update` in generated REST/MCP/SvelteKit routes, so callers\n   * cannot mass-assign them. Server-side code can still set them directly.\n   */\n  readonly?: boolean;\n  /**\n   * Permission slug required to include this field in public/read responses.\n   *\n   * Fields with a read permission are fail-closed: generated serializers omit\n   * them unless the caller's resolved permission set contains this slug.\n   * `sensitive: true` still wins and omits the field for every caller.\n   */\n  readPermission?: string;\n  /** Field description */\n  description?: string;\n  /**\n   * Static UI hints for the field-policy rail (#2046, epic #2045).\n   *\n   * A pure presentation seed — carried in the manifest under the field's\n   * `_meta.ui`, readable at runtime via `getAllFields()` at `field._meta.ui`,\n   * and emitted to the browser in generated web-collection definitions. Has no\n   * schema, persistence, or security effect; `sensitive`/`readPermission`\n   * remain the security rail.\n   */\n  ui?: FieldUIHints;\n  /**\n   * Controls whether the field is included in JSON exports.\n   * - `true`: Always exported (unless site explicitly excludes it)\n   * - `false`: Never exported (cannot be overridden by site config)\n   * - `undefined`: Uses site's fieldExportDefault setting\n   */\n  exported?: boolean;\n}\n\n/**\n * Options for text fields\n */\nexport interface TextFieldOptions extends FieldOptions {\n  /** Minimum length for text fields */\n  minLength?: number;\n  /** Maximum length for text fields */\n  maxLength?: number;\n  /** Regex pattern for validation */\n  pattern?: RegExp | string;\n}\n\n/**\n * Options for numeric fields\n */\nexport interface NumericFieldOptions extends FieldOptions {\n  /** Minimum value */\n  min?: number;\n  /** Maximum value */\n  max?: number;\n}\n\n/**\n * Options for relationship fields\n */\nexport interface RelationshipFieldOptions extends FieldOptions {\n  /** Related class name */\n  related?: string;\n  /** Foreign key field name */\n  foreignKey?: string;\n  /** Through table for many-to-many */\n  through?: string;\n  /** Relationship type */\n  type?: 'foreignKey' | 'crossPackageRef' | 'oneToMany' | 'manyToMany';\n  /**\n   * What happens to this row when the referenced object is deleted (#2371).\n   *\n   * Same-package references emit this DB-level action and `SmrtObject.delete()`\n   * enforces the same policy in the application layer:\n   *\n   * - `'CASCADE'` — this row is deleted with the target.\n   * - `'SET NULL'` — this column is set to `NULL`. The field must be nullable;\n   *   declaring it on a `required` field throws `ConfigurationError`.\n   * - `'RESTRICT'` — deleting the target throws `DatabaseError` while any row\n   *   still points at it.\n   *\n   * When omitted, a column that is part of this class's `conflictColumns`\n   * (junction and association rows, which are *identified* by the reference)\n   * defaults to `CASCADE`; every other same-package column defaults to\n   * immediate `NO ACTION`.\n   * `@tenantId()` fields are the one exception: `smrt-tenancy` leads a\n   * tenant-scoped class's default `conflictColumns` with the tenant column,\n   * but that column scopes ownership rather than identifying the row, so it\n   * is never defaulted to `CASCADE` — deleting a `Tenant` must not cascade\n   * through every tenant-scoped table.\n   *\n   * Cascaded rows are removed set-based: their `beforeDelete`/`afterDelete`\n   * hooks and interceptors do not run and no change-feed entry is written, the\n   * same as a database-level `ON DELETE CASCADE`.\n   */\n  onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';\n  /**\n   * Set to `false` only for an app-side relationship whose target identifier\n   * must deliberately survive without a database parent row (for example an\n   * immutable audit/event record retained after its parent is pruned).\n   *\n   * The field remains a typed `foreignKey` relationship for loading and\n   * indexes, but no physical DDL constraint, schema dependency, or app-side\n   * delete action is emitted. The stored identifier is deliberately preserved\n   * after the parent is deleted. Ordinary same-package relationships must leave\n   * this enabled (the default).\n   */\n  constraint?:\n    | boolean\n    | {\n        /**\n         * Database engines on which SMRT emits the physical constraint.\n         *\n         * Relationship loading, UUID storage, indexes, and application-side\n         * delete enforcement remain active on every engine. Use this narrow\n         * allowlist only when an engine cannot faithfully enforce a supported\n         * relationship shape (for example a DuckDB self-reference).\n         */\n        engines: Array<'postgres' | 'sqlite' | 'duckdb' | 'json'>;\n      };\n}\n\n/**\n * Options specific to cross-package references.\n */\nexport interface CrossPackageRefOptions\n  extends Omit<RelationshipFieldOptions, 'related' | 'type'> {\n  /**\n   * Storage type for the referenced target id. Defaults to 'uuid'.\n   *\n   * Use 'text' only when the external target model declares\n   * `@smrt({ idType: 'text' })`.\n   */\n  idType?: 'uuid' | 'text';\n\n  /**\n   * When `true`, the framework verifies the referenced object exists at save time.\n   * Validation uses the target package's manifest (loaded on demand via\n   * `ObjectRegistry.ensureManifestLoaded()`), so this requires the target manifest\n   * to be discoverable at runtime.\n   *\n   * Empty/null values are always allowed (treated as \"no reference set\").\n   *\n   * Defaults to `false` — same behavior as a plain string field today.\n   */\n  validate?: boolean;\n}\n\n/**\n * Resolve a relationship decorator's target argument to a class name.\n *\n * Accepted target forms:\n * - `'Target'` — class name string; resolves lazily, immune to import cycles.\n * - `Target` — class constructor.\n * - `() => Target` — thunk (inline or a named `const`), invoked here to read\n *   the name, so its target must already be initialized.\n *\n * A thunk's own `.name` is `''`, so reading `relatedClass.name` used to register\n * `related: ''` (issue #2379): the field kept `type: 'foreignKey'` but lost its\n * target, which silently dropped the relationship edge, `loadRelated()`, and any\n * FK-derived index. Thunks are therefore invoked at decoration time and an\n * unresolvable target throws with the string form as the remedy — an empty\n * `related` is never registered.\n *\n * Resolution runs inside the field-registration callback, which is the latest\n * point in the decorator lifecycle (after the class binding exists for legacy\n * decorators, and at `@smrt()` application time for standard decorators), so a\n * self-referential `() => Self` thunk resolves rather than hitting the TDZ.\n * A thunk pointing at a class declared LATER in the same module is still in\n * that class's temporal dead zone when the decorators of the earlier class run;\n * that now fails loudly, naming the string form, instead of silently\n * registering an empty target.\n */\nfunction resolveRelatedClassName(\n  decoratorName: 'foreignKey' | 'oneToMany' | 'manyToMany',\n  relatedClass: string | Function,\n  className: string,\n  propertyKey: string,\n): string {\n  const where = `@${decoratorName}() on ${className}.${propertyKey}`;\n  const remedy =\n    `Pass the target class name as a string instead — ` +\n    `\\`@${decoratorName}('Target')\\` resolves lazily and is immune to import cycles.`;\n\n  if (typeof relatedClass === 'string') {\n    const name = relatedClass.trim();\n    if (!name) {\n      throw new Error(\n        `${where}: target class name is empty. Pass a class, a class name, or a \\`() => Target\\` thunk.`,\n      );\n    }\n    return name;\n  }\n\n  if (typeof relatedClass !== 'function') {\n    throw new Error(\n      `${where}: expected a class, a class name, or a \\`() => Target\\` thunk, received ${relatedClass === null ? 'null' : typeof relatedClass}. ${remedy}`,\n    );\n  }\n\n  // Class/function reference — the common `@foreignKey(Target)` form. Arrow\n  // functions have no `prototype`, so a *named* thunk (`const lazyTarget = () =>\n  // Target`) is still routed to the thunk branch below instead of registering\n  // the variable name as the target class.\n  if (relatedClass.name && relatedClass.prototype !== undefined) {\n    return relatedClass.name;\n  }\n\n  // Thunk (`() => Target`, named or inline) — invoke it for the target.\n  let resolved: unknown;\n  try {\n    resolved = (relatedClass as () => unknown)();\n  } catch (error) {\n    throw new Error(\n      `${where}: the \\`() => Target\\` thunk threw while resolving its target (${\n        error instanceof Error ? error.message : String(error)\n      }). ${remedy}`,\n      { cause: error },\n    );\n  }\n\n  if (typeof resolved === 'function' && resolved.name) {\n    return resolved.name;\n  }\n  if (typeof resolved === 'string' && resolved.trim()) {\n    return resolved.trim();\n  }\n\n  throw new Error(\n    `${where}: the \\`() => Target\\` thunk resolved to ${\n      resolved === null ? 'null' : typeof resolved\n    } instead of a named class. ${remedy}`,\n  );\n}\n\n/**\n * Marks a class property with validation constraints and metadata options.\n *\n * Use `@field()` when you need options beyond what plain TypeScript initializers\n * express — required validation, numeric ranges, string length limits, uniqueness,\n * or transient (non-persisted) computed properties.\n *\n * For plain persisted fields with no constraints, no decorator is needed: just\n * declare the property with a TypeScript initializer and the framework will infer\n * the column type from the default value (`0` → INTEGER, `0.0` → DECIMAL, `''` → TEXT).\n *\n * @param options - Field configuration options\n * @param options.required - If `true`, `save()` throws `ValidationError` when empty/null\n * @param options.unique - Enforces a UNIQUE database constraint\n * @param options.nullable - If `true`, the column accepts NULL (default depends on type)\n * @param options.transient - If `true`, the property is not persisted to the database\n * @param options.default - Default value applied at the database level\n * @param options.description - Human-readable description used in generated API docs\n * @param options.exported - Controls JSON export visibility (see `FieldOptions`)\n * @returns A TypeScript property decorator\n *\n * @example\n * ```typescript\n * @smrt()\n * class Product extends SmrtObject {\n *   @field({ required: true, maxLength: 100 })\n *   name: string = '';\n *\n *   @field({ min: 0 })\n *   stock: number = 0;\n *\n *   @field({ transient: true })\n *   get displayPrice(): string { return `$${this.price.toFixed(2)}`; }\n * }\n * ```\n *\n * @see {@link meta} for STI child-specific fields stored in `_meta_data` JSON\n * @see {@link foreignKey} for typed relationship fields\n */\nexport function field(\n  options: FieldOptions | NumericFieldOptions | TextFieldOptions = {},\n) {\n  return ((\n    targetOrValue: LegacyPropertyDecoratorTarget | undefined,\n    propertyKeyOrContext: CompatiblePropertyDecoratorContext<unknown, unknown>,\n  ) => {\n    registerCompatibleFieldDecorator(\n      targetOrValue,\n      propertyKeyOrContext,\n      (className, propertyKey) => {\n        ObjectRegistry.registerFieldDecorator(className, propertyKey, options);\n      },\n    );\n  }) as CompatiblePropertyDecorator;\n}\n\n/**\n * Declares a many-to-one (foreign key) relationship to another `SmrtObject` class.\n *\n * The decorated property stores the UUID of the related object. At runtime, call\n * `instance.loadRelated('fieldName')` to lazy-load (and cache) the related object,\n * or pass `include: ['fieldName']` to `collection.list()` for batch eager loading.\n *\n * Cross-package rule: Use `@foreignKey()` only for same-package references.\n * Use `@crossPackageRef()` for cross-package relationships.\n *\n * A named database constraint is emitted on supported engines by default, and\n * the same action is enforced by `SmrtObject.delete()` before the engine sees\n * it. Exceptional archival/audit references that intentionally outlive their\n * parent may declare `{ constraint: false }`; they retain relationship loading\n * and indexing while deliberately preserving the identifier after parent\n * deletion and omitting physical DDL. The\n * decorator also enables `loadRelated()` and eager `include:` loading:\n *\n * ```typescript\n * @foreignKey(Order, { onDelete: 'CASCADE' })   // deleted with the order\n * orderId: string = '';\n *\n * @foreignKey(Customer, { onDelete: 'RESTRICT' }) // blocks the customer delete\n * customerId: string = '';\n * ```\n *\n * Without an `onDelete`, a column that is part of this class's\n * `conflictColumns` defaults to `CASCADE` (this is what cleans up junction\n * rows); any other column defaults to immediate `NO ACTION`.\n *\n * @param relatedClass - The target class constructor, its name as a string, or a\n *   `() => Target` thunk. A thunk is **invoked at decoration time**, so its\n *   target must already be initialized: a class from an already-evaluated module\n *   or the decorated class itself. Use the string form for a class declared\n *   later in the same module or reached through an import cycle — it is never\n *   evaluated, so it cannot hit the temporal dead zone.\n * @param options - Optional field constraints (required, nullable, etc.)\n * @returns A TypeScript property decorator\n * @throws Error when the target cannot be resolved to a class name (an empty\n *   string, a thunk that throws — including on an uninitialized target — or a\n *   thunk returning an anonymous value)\n *\n * @example\n * ```typescript\n * @smrt()\n * class Order extends SmrtObject {\n *   // Same-package FK — enables loadRelated() and eager loading\n *   @foreignKey(Customer)\n *   customerId: string = '';\n *\n *   // Self-reference: the class binding exists when its decorators run\n *   @foreignKey(() => Order)\n *   parentOrderId: string = '';\n *\n *   // Declared later in this module — name string, never evaluated\n *   @foreignKey('Invoice')\n *   invoiceId: string = '';\n *\n *   // Physical constraint only where the engine can enforce this shape;\n *   // relationship loading and app-side delete policy remain cross-engine.\n *   @foreignKey('Order', {\n *     constraint: { engines: ['postgres', 'sqlite'] },\n *   })\n *   hierarchyParentId: string | null = null;\n * }\n *\n * // Cross-package: runtime relationship, index, and loading; no physical FK\n * @smrt()\n * class Post extends SmrtObject {\n *   @crossPackageRef('@happyvertical/smrt-users:User')\n *   authorId: string = '';\n * }\n * ```\n *\n * @see {@link oneToMany} for the inverse (parent) side of the relationship\n * @see SmrtObject.loadRelated for lazy-loading the related object at runtime\n */\nexport function foreignKey(\n  relatedClass: string | Function,\n  options: Omit<RelationshipFieldOptions, 'related'> = {},\n) {\n  return ((\n    targetOrValue: LegacyPropertyDecoratorTarget | undefined,\n    propertyKeyOrContext: CompatiblePropertyDecoratorContext<unknown, unknown>,\n  ) => {\n    registerCompatibleFieldDecorator(\n      targetOrValue,\n      propertyKeyOrContext,\n      (className, propertyKey) => {\n        ObjectRegistry.registerFieldDecorator(className, propertyKey, {\n          ...options,\n          type: 'foreignKey',\n          related: resolveRelatedClassName(\n            'foreignKey',\n            relatedClass,\n            className,\n            propertyKey,\n          ),\n        });\n      },\n    );\n  }) as CompatiblePropertyDecorator;\n}\n\n/**\n * Declares a cross-package foreign key reference.\n *\n * Use this for relationships that point to a `SmrtObject` in a *different* package\n * (e.g. `Customer.profileId` pointing at `@happyvertical/smrt-profiles:Profile`).\n *\n * Unlike same-package `@foreignKey()`, this emits **no** DDL `FOREIGN KEY`\n * constraint, keeping package schemas independently installable. The property is a\n * `UUID` column on PostgreSQL/DuckDB and `TEXT` on SQLite, matching the target's\n * id type; pass `{ idType: 'text' }` when the target declares\n * `@smrt({ idType: 'text' })`.\n *\n * What you get over a plain string field:\n * - The relationship is registered with the `ObjectRegistry`, so `loadRelated()`\n *   and `Collection.list({ include })` can resolve it once the target package's\n *   manifest is loaded.\n * - No physical database constraint is emitted; package schemas remain\n *   independently installable.\n * - Optional save-time validation (`validate: true`) confirms the referenced\n *   object exists, catching typos and stale IDs before they hit the database.\n * - `onDelete` is honoured by `SmrtObject.delete()` when the target package's\n *   manifest is loaded in the same runtime.\n *\n * The `qualifiedName` is a fully-qualified class identifier in the form\n * `@package/scope:ClassName` — for example `@happyvertical/smrt-profiles:Profile`.\n *\n * @param qualifiedName - Qualified name of the target class\n * @param options - Optional field constraints and `validate` flag\n * @returns A TypeScript property decorator\n *\n * @example\n * ```typescript\n * @smrt()\n * class Customer extends SmrtObject {\n *   @crossPackageRef('@happyvertical/smrt-profiles:Profile')\n *   profileId: string = '';\n *\n *   // With save-time validation\n *   @crossPackageRef('@happyvertical/smrt-profiles:Profile', { validate: true })\n *   primaryContactId: string = '';\n * }\n * ```\n *\n * @see {@link foreignKey} for same-package relationships\n * @see SmrtObject.loadRelated for runtime resolution\n */\nexport function crossPackageRef(\n  qualifiedName: string,\n  options: CrossPackageRefOptions = {},\n) {\n  return ((\n    targetOrValue: LegacyPropertyDecoratorTarget | undefined,\n    propertyKeyOrContext: CompatiblePropertyDecoratorContext<unknown, unknown>,\n  ) => {\n    registerCompatibleFieldDecorator(\n      targetOrValue,\n      propertyKeyOrContext,\n      (className, propertyKey) => {\n        ObjectRegistry.registerFieldDecorator(className, propertyKey, {\n          ...options,\n          type: 'crossPackageRef',\n          related: qualifiedName,\n        });\n      },\n    );\n  }) as CompatiblePropertyDecorator;\n}\n\n/**\n * Declares a one-to-many relationship from this object to a collection of related objects.\n *\n * The decorated property is `transient` — it is not persisted as a database column.\n * At runtime, call `instance.loadRelatedMany('fieldName')` to load the related objects,\n * or pass `include: ['fieldName']` to `collection.list()` for batch eager loading (issues\n * a single batched query for all instances instead of N individual queries).\n *\n * The inverse side (`@foreignKey`) must exist on the `relatedClass` pointing back to this\n * class. The framework discovers it automatically via `ObjectRegistry.getInverseRelationships()`.\n *\n * **Generated accessor (R10):** registering the class installs a consistent\n * `get<FieldName>()` instance method (e.g. `items` → `order.getItems()`) that\n * delegates to `loadRelatedMany('items')`. Generation is additive — a\n * hand-rolled method of the same name is never overwritten.\n *\n * **Disambiguation:** when `relatedClass` declares more than one `@foreignKey`\n * back to this class, pass `{ foreignKey: '<inverseFieldName>' }` so both\n * `loadRelatedMany` and the generated accessor resolve the intended inverse\n * side. Without it the first matching foreign key is used.\n *\n * **Delete behaviour is declared on the child, not here.** `@oneToMany` is a\n * transient read-side accessor; to have children removed with their parent,\n * put `onDelete: 'CASCADE'` on the inverse `@foreignKey` (#2371):\n *\n * ```typescript\n * class OrderItem extends SmrtObject {\n *   @foreignKey(Order, { onDelete: 'CASCADE' })\n *   orderId: string = '';\n * }\n * ```\n *\n * @param relatedClass - The class constructor of the child/related objects\n * @param options - Optional relationship options. `foreignKey` selects the\n *   inverse foreign-key field on `relatedClass` when it has more than one.\n * @returns A TypeScript property decorator (sets `transient: true` automatically)\n *\n * @example\n * ```typescript\n * @smrt()\n * class Order extends SmrtObject {\n *   @oneToMany(OrderItem)\n *   items: OrderItem[] = [];\n * }\n *\n * @smrt()\n * class OrderItem extends SmrtObject {\n *   @foreignKey(Order)\n *   orderId: string = '';\n * }\n *\n * const order = await orders.get({ id });\n * const items = await order.getItems(); // generated; === loadRelatedMany('items')\n * ```\n *\n * @example\n * ```typescript\n * // Multiple inverse foreign keys → disambiguate explicitly.\n * @smrt()\n * class Profile extends SmrtObject {\n *   @oneToMany(ProfileRelationship, { foreignKey: 'fromProfileId' })\n *   relationshipsFrom: ProfileRelationship[] = [];\n *   @oneToMany(ProfileRelationship, { foreignKey: 'toProfileId' })\n *   relationshipsTo: ProfileRelationship[] = [];\n * }\n * ```\n *\n * @see {@link foreignKey} for the many-to-one (child) side of the relationship\n * @see SmrtObject.loadRelatedMany for lazy-loading at runtime\n */\nexport function oneToMany(\n  relatedClass: string | Function,\n  options: Omit<RelationshipFieldOptions, 'related'> = {},\n) {\n  return ((\n    targetOrValue: LegacyPropertyDecoratorTarget | undefined,\n    propertyKeyOrContext: CompatiblePropertyDecoratorContext<unknown, unknown>,\n  ) => {\n    registerCompatibleFieldDecorator(\n      targetOrValue,\n      propertyKeyOrContext,\n      (className, propertyKey) => {\n        ObjectRegistry.registerFieldDecorator(className, propertyKey, {\n          ...options,\n          type: 'oneToMany',\n          related: resolveRelatedClassName(\n            'oneToMany',\n            relatedClass,\n            className,\n            propertyKey,\n          ),\n          transient: true, // Relationship fields are not database columns\n        });\n      },\n    );\n  }) as CompatiblePropertyDecorator;\n}\n\n/**\n * Declares a many-to-many relationship between two `SmrtObject` classes via a join table.\n *\n * The decorated property is `transient` — it is not persisted as a database column.\n * The `through` option specifies the junction table name. The join table model must\n * be decorated with `@smrt({ conflictColumns: ['...', '...'] })` to use the natural\n * key columns for upsert operations.\n *\n * Runtime loading: call `instance.loadRelatedMany('field')` to lazy-load, or\n * pass `include: ['field']` to `collection.list()` for batched eager loading.\n *\n * @param relatedClass - The class constructor of the related objects\n * @param options - Relationship options; `through` specifies the junction table name\n * @returns A TypeScript property decorator (sets `transient: true` automatically)\n *\n * @example\n * ```typescript\n * @smrt()\n * class Product extends SmrtObject {\n *   @manyToMany(Tag, { through: 'product_tags' })\n *   tags: Tag[] = [];\n * }\n * ```\n *\n * @see {@link oneToMany} for one-to-many relationships\n */\nexport function manyToMany(\n  relatedClass: string | Function,\n  options: Omit<RelationshipFieldOptions, 'related'> = {},\n) {\n  return ((\n    targetOrValue: LegacyPropertyDecoratorTarget | undefined,\n    propertyKeyOrContext: CompatiblePropertyDecoratorContext<unknown, unknown>,\n  ) => {\n    registerCompatibleFieldDecorator(\n      targetOrValue,\n      propertyKeyOrContext,\n      (className, propertyKey) => {\n        ObjectRegistry.registerFieldDecorator(className, propertyKey, {\n          ...options,\n          type: 'manyToMany',\n          related: resolveRelatedClassName(\n            'manyToMany',\n            relatedClass,\n            className,\n            propertyKey,\n          ),\n          transient: true, // Relationship fields are not database columns\n        });\n      },\n    );\n  }) as CompatiblePropertyDecorator;\n}\n\n/**\n * Marks a field as a Single Table Inheritance (STI) meta field.\n *\n * Meta fields are stored in the `_meta_data` JSONB column on the shared STI\n * table rather than as dedicated table columns. Use this decorator for fields\n * that are specific to an STI child class and should not pollute the shared\n * table schema with child-specific columns.\n *\n * The `@smrt({ tableStrategy: 'sti' })` decorator must be set on the base class.\n * All child-specific fields should use `@meta()` (or the `Meta<T>` type alias).\n *\n * @param options - Standard field options (required, nullable, description, etc.)\n * @returns A TypeScript property decorator (registers field with `type: 'meta'`)\n *\n * @example\n * ```typescript\n * @smrt({ tableStrategy: 'sti' })\n * class Event extends SmrtObject {\n *   title: string = ''; // shared column on events table\n * }\n *\n * @smrt()\n * class Meeting extends Event {\n *   @meta()\n *   roomNumber: string = ''; // stored in _meta_data JSON, not a column\n *\n *   @meta({ required: true })\n *   durationMinutes: number = 60;\n * }\n * ```\n *\n * @see {@link Meta} for the equivalent type alias approach\n * @see {@link field} for regular (non-STI) field declarations\n */\nexport function meta(options: FieldOptions = {}) {\n  return ((\n    targetOrValue: LegacyPropertyDecoratorTarget | undefined,\n    propertyKeyOrContext: CompatiblePropertyDecoratorContext<unknown, unknown>,\n  ) => {\n    registerCompatibleFieldDecorator(\n      targetOrValue,\n      propertyKeyOrContext,\n      (className, propertyKey) => {\n        ObjectRegistry.registerFieldDecorator(className, propertyKey, {\n          ...options,\n          type: 'meta', // Mark this field as a meta field for STI\n        });\n      },\n    );\n  }) as CompatiblePropertyDecorator;\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/decorators/index.ts"],"sourcesContent":["/**\n * Field decorators for SMRT objects\n *\n * Modern decorator-based API for defining SMRT object properties.\n * Properties are typed as primitives with decorator metadata.\n */\n\nimport type {\n  CustomActionScope,\n  ToolEffect,\n} from '../generators/custom-action.js';\nimport type { ApiHttpMethod } from '../registry/types.js';\nimport { ObjectRegistry } from '../registry.js';\nimport type { FieldUIHints } from '../scanner/types.js';\nimport type { SQLDataType } from '../schema/types.js';\nimport {\n  type CompatibleMethodDecorator,\n  type CompatibleMethodDecoratorContext,\n  type CompatiblePropertyDecorator,\n  type CompatiblePropertyDecoratorContext,\n  type LegacyPropertyDecoratorTarget,\n  registerCompatibleFieldDecorator,\n  registerCompatibleMethodDecorator,\n} from './compatibility.js';\n\nexport type { FieldUIHints } from '../scanner/types.js';\n\n/**\n * Meta type wrapper for STI (Single Table Inheritance) meta fields\n *\n * Fields typed as Meta<T> are stored in the _meta_data JSONB column\n * rather than as direct table columns. Used for child-specific fields\n * in STI hierarchies.\n *\n * @example\n * ```typescript\n * @smrt({ tableStrategy: 'sti' })\n * class Event extends SmrtObject {\n *   title: string = '';\n * }\n *\n * @smrt()\n * class Meeting extends Event {\n *   // Stored in _meta_data JSONB column\n *   roomNumber: Meta<string> = '';\n *   attendees: Meta<string[]> = [];\n * }\n * ```\n */\nexport type Meta<T> = T;\n\n/**\n * Base field options\n */\nexport type PrimitiveFieldType =\n  | 'text'\n  | 'integer'\n  | 'decimal'\n  | 'boolean'\n  | 'datetime'\n  | 'json';\n\nexport type FieldType =\n  | PrimitiveFieldType\n  | 'meta'\n  | 'foreignKey'\n  | 'crossPackageRef'\n  | 'oneToMany'\n  | 'manyToMany';\n\nexport interface FieldOptions {\n  /** Explicit field type for runtime-only registration paths */\n  type?: FieldType;\n  /** Explicit SQL storage type when runtime and persistence contracts differ */\n  sqlType?: SQLDataType;\n  /** Whether the field is required */\n  required?: boolean;\n  /** Default value for the field */\n  default?: unknown;\n  /** Whether the field is unique */\n  unique?: boolean;\n  /**\n   * When `true`, the schema emits a database index targeting this field.\n   *\n   * For regular (column-backed) fields the index is a plain column index.\n   * For `@meta()` fields stored inside `_meta_data` JSONB, the index targets\n   * the JSON path — `json_extract(_meta_data, '$.fieldName')` on SQLite,\n   * `(_meta_data->>'fieldName')` on Postgres.\n   *\n   * Note that `collection.list({ where })` cannot currently reach a JSON-path\n   * index: dot-notation keys such as `_meta_data.fieldName` are rejected,\n   * because nothing rewrites them into the matching extraction expression\n   * (#2276, tracked in #2282). The index is still emitted and still serves\n   * hand-written SQL that spells the expression out; it just has no\n   * collection-level query to accelerate yet.\n   */\n  indexed?: boolean;\n  /** Whether the field is nullable */\n  nullable?: boolean;\n  /** Whether the field should be excluded from database */\n  transient?: boolean;\n  /**\n   * Marks the field as sensitive (e.g. API secrets, credentials, tax IDs).\n   *\n   * Sensitive fields are still persisted to the database, but the framework:\n   * - excludes them from `toPublicJSON()` (the serializer used by generated\n   *   REST/MCP/SvelteKit routes), so they never appear in API responses; and\n   * - rejects them as `where`-clause filter keys, closing the\n   *   `?secret[like]=...` value-probing oracle.\n   *\n   * Use this for any column that holds a secret value that must never be\n   * read back over a generated network surface.\n   */\n  sensitive?: boolean;\n  /**\n   * Marks the field as read-only over generated write surfaces.\n   *\n   * Read-only fields are stripped from the request body before\n   * `create`/`update` in generated REST/MCP/SvelteKit routes, so callers\n   * cannot mass-assign them. Server-side code can still set them directly.\n   */\n  readonly?: boolean;\n  /**\n   * Permission slug required to include this field in public/read responses.\n   *\n   * Fields with a read permission are fail-closed: generated serializers omit\n   * them unless the caller's resolved permission set contains this slug.\n   * `sensitive: true` still wins and omits the field for every caller.\n   */\n  readPermission?: string;\n  /** Field description */\n  description?: string;\n  /**\n   * Static UI hints for the field-policy rail (#2046, epic #2045).\n   *\n   * A pure presentation seed — carried in the manifest under the field's\n   * `_meta.ui`, readable at runtime via `getAllFields()` at `field._meta.ui`,\n   * and emitted to the browser in generated web-collection definitions. Has no\n   * schema, persistence, or security effect; `sensitive`/`readPermission`\n   * remain the security rail.\n   */\n  ui?: FieldUIHints;\n  /**\n   * Controls whether the field is included in JSON exports.\n   * - `true`: Always exported (unless site explicitly excludes it)\n   * - `false`: Never exported (cannot be overridden by site config)\n   * - `undefined`: Uses site's fieldExportDefault setting\n   */\n  exported?: boolean;\n}\n\n/**\n * Options for text fields\n */\nexport interface TextFieldOptions extends FieldOptions {\n  /** Minimum length for text fields */\n  minLength?: number;\n  /** Maximum length for text fields */\n  maxLength?: number;\n  /** Regex pattern for validation */\n  pattern?: RegExp | string;\n}\n\n/**\n * Options for numeric fields\n */\nexport interface NumericFieldOptions extends FieldOptions {\n  /** Minimum value */\n  min?: number;\n  /** Maximum value */\n  max?: number;\n}\n\n/**\n * Options for relationship fields\n */\nexport interface RelationshipFieldOptions extends FieldOptions {\n  /** Related class name */\n  related?: string;\n  /** Foreign key field name */\n  foreignKey?: string;\n  /** Through table for many-to-many */\n  through?: string;\n  /** Relationship type */\n  type?: 'foreignKey' | 'crossPackageRef' | 'oneToMany' | 'manyToMany';\n  /**\n   * What happens to this row when the referenced object is deleted (#2371).\n   *\n   * Same-package references emit this DB-level action and `SmrtObject.delete()`\n   * enforces the same policy in the application layer:\n   *\n   * - `'CASCADE'` — this row is deleted with the target.\n   * - `'SET NULL'` — this column is set to `NULL`. The field must be nullable;\n   *   declaring it on a `required` field throws `ConfigurationError`.\n   * - `'RESTRICT'` — deleting the target throws `DatabaseError` while any row\n   *   still points at it.\n   *\n   * When omitted, a column that is part of this class's `conflictColumns`\n   * (junction and association rows, which are *identified* by the reference)\n   * defaults to `CASCADE`; every other same-package column defaults to\n   * immediate `NO ACTION`.\n   * `@tenantId()` fields are the one exception: `smrt-tenancy` leads a\n   * tenant-scoped class's default `conflictColumns` with the tenant column,\n   * but that column scopes ownership rather than identifying the row, so it\n   * is never defaulted to `CASCADE` — deleting a `Tenant` must not cascade\n   * through every tenant-scoped table.\n   *\n   * Cascaded rows are removed set-based: their `beforeDelete`/`afterDelete`\n   * hooks and interceptors do not run and no change-feed entry is written, the\n   * same as a database-level `ON DELETE CASCADE`.\n   */\n  onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';\n  /**\n   * Set to `false` only for an app-side relationship whose target identifier\n   * must deliberately survive without a database parent row (for example an\n   * immutable audit/event record retained after its parent is pruned).\n   *\n   * The field remains a typed `foreignKey` relationship for loading and\n   * indexes, but no physical DDL constraint, schema dependency, or app-side\n   * delete action is emitted. The stored identifier is deliberately preserved\n   * after the parent is deleted. Ordinary same-package relationships must leave\n   * this enabled (the default).\n   */\n  constraint?:\n    | boolean\n    | {\n        /**\n         * Database engines on which SMRT emits the physical constraint.\n         *\n         * Relationship loading, UUID storage, indexes, and application-side\n         * delete enforcement remain active on every engine. Use this narrow\n         * allowlist only when an engine cannot faithfully enforce a supported\n         * relationship shape (for example a DuckDB self-reference).\n         */\n        engines: Array<'postgres' | 'sqlite' | 'duckdb' | 'json'>;\n      };\n}\n\n/**\n * Options specific to cross-package references.\n */\nexport interface CrossPackageRefOptions\n  extends Omit<RelationshipFieldOptions, 'related' | 'type'> {\n  /**\n   * Storage type for the referenced target id. Defaults to 'uuid'.\n   *\n   * Use 'text' only when the external target model declares\n   * `@smrt({ idType: 'text' })`.\n   */\n  idType?: 'uuid' | 'text';\n\n  /**\n   * When `true`, the framework verifies the referenced object exists at save time.\n   * Validation uses the target package's manifest (loaded on demand via\n   * `ObjectRegistry.ensureManifestLoaded()`), so this requires the target manifest\n   * to be discoverable at runtime.\n   *\n   * Empty/null values are always allowed (treated as \"no reference set\").\n   *\n   * Defaults to `false` — same behavior as a plain string field today.\n   */\n  validate?: boolean;\n}\n\n/**\n * Resolve a relationship decorator's target argument to a class name.\n *\n * Accepted target forms:\n * - `'Target'` — class name string; resolves lazily, immune to import cycles.\n * - `Target` — class constructor.\n * - `() => Target` — thunk (inline or a named `const`), invoked here to read\n *   the name, so its target must already be initialized.\n *\n * A thunk's own `.name` is `''`, so reading `relatedClass.name` used to register\n * `related: ''` (issue #2379): the field kept `type: 'foreignKey'` but lost its\n * target, which silently dropped the relationship edge, `loadRelated()`, and any\n * FK-derived index. Thunks are therefore invoked at decoration time and an\n * unresolvable target throws with the string form as the remedy — an empty\n * `related` is never registered.\n *\n * Resolution runs inside the field-registration callback, which is the latest\n * point in the decorator lifecycle (after the class binding exists for legacy\n * decorators, and at `@smrt()` application time for standard decorators), so a\n * self-referential `() => Self` thunk resolves rather than hitting the TDZ.\n * A thunk pointing at a class declared LATER in the same module is still in\n * that class's temporal dead zone when the decorators of the earlier class run;\n * that now fails loudly, naming the string form, instead of silently\n * registering an empty target.\n */\nfunction resolveRelatedClassName(\n  decoratorName: 'foreignKey' | 'oneToMany' | 'manyToMany',\n  relatedClass: string | Function,\n  className: string,\n  propertyKey: string,\n): string {\n  const where = `@${decoratorName}() on ${className}.${propertyKey}`;\n  const remedy =\n    `Pass the target class name as a string instead — ` +\n    `\\`@${decoratorName}('Target')\\` resolves lazily and is immune to import cycles.`;\n\n  if (typeof relatedClass === 'string') {\n    const name = relatedClass.trim();\n    if (!name) {\n      throw new Error(\n        `${where}: target class name is empty. Pass a class, a class name, or a \\`() => Target\\` thunk.`,\n      );\n    }\n    return name;\n  }\n\n  if (typeof relatedClass !== 'function') {\n    throw new Error(\n      `${where}: expected a class, a class name, or a \\`() => Target\\` thunk, received ${relatedClass === null ? 'null' : typeof relatedClass}. ${remedy}`,\n    );\n  }\n\n  // Class/function reference — the common `@foreignKey(Target)` form. Arrow\n  // functions have no `prototype`, so a *named* thunk (`const lazyTarget = () =>\n  // Target`) is still routed to the thunk branch below instead of registering\n  // the variable name as the target class.\n  if (relatedClass.name && relatedClass.prototype !== undefined) {\n    return relatedClass.name;\n  }\n\n  // Thunk (`() => Target`, named or inline) — invoke it for the target.\n  let resolved: unknown;\n  try {\n    resolved = (relatedClass as () => unknown)();\n  } catch (error) {\n    throw new Error(\n      `${where}: the \\`() => Target\\` thunk threw while resolving its target (${\n        error instanceof Error ? error.message : String(error)\n      }). ${remedy}`,\n      { cause: error },\n    );\n  }\n\n  if (typeof resolved === 'function' && resolved.name) {\n    return resolved.name;\n  }\n  if (typeof resolved === 'string' && resolved.trim()) {\n    return resolved.trim();\n  }\n\n  throw new Error(\n    `${where}: the \\`() => Target\\` thunk resolved to ${\n      resolved === null ? 'null' : typeof resolved\n    } instead of a named class. ${remedy}`,\n  );\n}\n\n/**\n * Marks a class property with validation constraints and metadata options.\n *\n * Use `@field()` when you need options beyond what plain TypeScript initializers\n * express — required validation, numeric ranges, string length limits, uniqueness,\n * or transient (non-persisted) computed properties.\n *\n * For plain persisted fields with no constraints, no decorator is needed: just\n * declare the property with a TypeScript initializer and the framework will infer\n * the column type from the default value (`0` → INTEGER, `0.0` → DECIMAL, `''` → TEXT).\n *\n * @param options - Field configuration options\n * @param options.required - If `true`, `save()` throws `ValidationError` when empty/null\n * @param options.unique - Enforces a UNIQUE database constraint\n * @param options.nullable - If `true`, the column accepts NULL (default depends on type)\n * @param options.transient - If `true`, the property is not persisted to the database\n * @param options.default - Default value applied at the database level\n * @param options.description - Human-readable description used in generated API docs\n * @param options.exported - Controls JSON export visibility (see `FieldOptions`)\n * @returns A TypeScript property decorator\n *\n * @example\n * ```typescript\n * @smrt()\n * class Product extends SmrtObject {\n *   @field({ required: true, maxLength: 100 })\n *   name: string = '';\n *\n *   @field({ min: 0 })\n *   stock: number = 0;\n *\n *   @field({ transient: true })\n *   get displayPrice(): string { return `$${this.price.toFixed(2)}`; }\n * }\n * ```\n *\n * @see {@link meta} for STI child-specific fields stored in `_meta_data` JSON\n * @see {@link foreignKey} for typed relationship fields\n */\nexport function field(\n  options: FieldOptions | NumericFieldOptions | TextFieldOptions = {},\n) {\n  return ((\n    targetOrValue: LegacyPropertyDecoratorTarget | undefined,\n    propertyKeyOrContext: CompatiblePropertyDecoratorContext<unknown, unknown>,\n  ) => {\n    registerCompatibleFieldDecorator(\n      targetOrValue,\n      propertyKeyOrContext,\n      (className, propertyKey) => {\n        ObjectRegistry.registerFieldDecorator(className, propertyKey, options);\n      },\n    );\n  }) as CompatiblePropertyDecorator;\n}\n\n/**\n * Declares a many-to-one (foreign key) relationship to another `SmrtObject` class.\n *\n * The decorated property stores the UUID of the related object. At runtime, call\n * `instance.loadRelated('fieldName')` to lazy-load (and cache) the related object,\n * or pass `include: ['fieldName']` to `collection.list()` for batch eager loading.\n *\n * Cross-package rule: Use `@foreignKey()` only for same-package references.\n * Use `@crossPackageRef()` for cross-package relationships.\n *\n * A named database constraint is emitted on supported engines by default, and\n * the same action is enforced by `SmrtObject.delete()` before the engine sees\n * it. Exceptional archival/audit references that intentionally outlive their\n * parent may declare `{ constraint: false }`; they retain relationship loading\n * and indexing while deliberately preserving the identifier after parent\n * deletion and omitting physical DDL. The\n * decorator also enables `loadRelated()` and eager `include:` loading:\n *\n * ```typescript\n * @foreignKey(Order, { onDelete: 'CASCADE' })   // deleted with the order\n * orderId: string = '';\n *\n * @foreignKey(Customer, { onDelete: 'RESTRICT' }) // blocks the customer delete\n * customerId: string = '';\n * ```\n *\n * Without an `onDelete`, a column that is part of this class's\n * `conflictColumns` defaults to `CASCADE` (this is what cleans up junction\n * rows); any other column defaults to immediate `NO ACTION`.\n *\n * @param relatedClass - The target class constructor, its name as a string, or a\n *   `() => Target` thunk. A thunk is **invoked at decoration time**, so its\n *   target must already be initialized: a class from an already-evaluated module\n *   or the decorated class itself. Use the string form for a class declared\n *   later in the same module or reached through an import cycle — it is never\n *   evaluated, so it cannot hit the temporal dead zone.\n * @param options - Optional field constraints (required, nullable, etc.)\n * @returns A TypeScript property decorator\n * @throws Error when the target cannot be resolved to a class name (an empty\n *   string, a thunk that throws — including on an uninitialized target — or a\n *   thunk returning an anonymous value)\n *\n * @example\n * ```typescript\n * @smrt()\n * class Order extends SmrtObject {\n *   // Same-package FK — enables loadRelated() and eager loading\n *   @foreignKey(Customer)\n *   customerId: string = '';\n *\n *   // Self-reference: the class binding exists when its decorators run\n *   @foreignKey(() => Order)\n *   parentOrderId: string = '';\n *\n *   // Declared later in this module — name string, never evaluated\n *   @foreignKey('Invoice')\n *   invoiceId: string = '';\n *\n *   // Physical constraint only where the engine can enforce this shape;\n *   // relationship loading and app-side delete policy remain cross-engine.\n *   @foreignKey('Order', {\n *     constraint: { engines: ['postgres', 'sqlite'] },\n *   })\n *   hierarchyParentId: string | null = null;\n * }\n *\n * // Cross-package: runtime relationship, index, and loading; no physical FK\n * @smrt()\n * class Post extends SmrtObject {\n *   @crossPackageRef('@happyvertical/smrt-users:User')\n *   authorId: string = '';\n * }\n * ```\n *\n * @see {@link oneToMany} for the inverse (parent) side of the relationship\n * @see SmrtObject.loadRelated for lazy-loading the related object at runtime\n */\nexport function foreignKey(\n  relatedClass: string | Function,\n  options: Omit<RelationshipFieldOptions, 'related'> = {},\n) {\n  return ((\n    targetOrValue: LegacyPropertyDecoratorTarget | undefined,\n    propertyKeyOrContext: CompatiblePropertyDecoratorContext<unknown, unknown>,\n  ) => {\n    registerCompatibleFieldDecorator(\n      targetOrValue,\n      propertyKeyOrContext,\n      (className, propertyKey) => {\n        ObjectRegistry.registerFieldDecorator(className, propertyKey, {\n          ...options,\n          type: 'foreignKey',\n          related: resolveRelatedClassName(\n            'foreignKey',\n            relatedClass,\n            className,\n            propertyKey,\n          ),\n        });\n      },\n    );\n  }) as CompatiblePropertyDecorator;\n}\n\n/**\n * Declares a cross-package foreign key reference.\n *\n * Use this for relationships that point to a `SmrtObject` in a *different* package\n * (e.g. `Customer.profileId` pointing at `@happyvertical/smrt-profiles:Profile`).\n *\n * Unlike same-package `@foreignKey()`, this emits **no** DDL `FOREIGN KEY`\n * constraint, keeping package schemas independently installable. The property is a\n * `UUID` column on PostgreSQL/DuckDB and `TEXT` on SQLite, matching the target's\n * id type; pass `{ idType: 'text' }` when the target declares\n * `@smrt({ idType: 'text' })`.\n *\n * What you get over a plain string field:\n * - The relationship is registered with the `ObjectRegistry`, so `loadRelated()`\n *   and `Collection.list({ include })` can resolve it once the target package's\n *   manifest is loaded.\n * - No physical database constraint is emitted; package schemas remain\n *   independently installable.\n * - Optional save-time validation (`validate: true`) confirms the referenced\n *   object exists, catching typos and stale IDs before they hit the database.\n * - `onDelete` is honoured by `SmrtObject.delete()` when the target package's\n *   manifest is loaded in the same runtime.\n *\n * The `qualifiedName` is a fully-qualified class identifier in the form\n * `@package/scope:ClassName` — for example `@happyvertical/smrt-profiles:Profile`.\n *\n * @param qualifiedName - Qualified name of the target class\n * @param options - Optional field constraints and `validate` flag\n * @returns A TypeScript property decorator\n *\n * @example\n * ```typescript\n * @smrt()\n * class Customer extends SmrtObject {\n *   @crossPackageRef('@happyvertical/smrt-profiles:Profile')\n *   profileId: string = '';\n *\n *   // With save-time validation\n *   @crossPackageRef('@happyvertical/smrt-profiles:Profile', { validate: true })\n *   primaryContactId: string = '';\n * }\n * ```\n *\n * @see {@link foreignKey} for same-package relationships\n * @see SmrtObject.loadRelated for runtime resolution\n */\nexport function crossPackageRef(\n  qualifiedName: string,\n  options: CrossPackageRefOptions = {},\n) {\n  return ((\n    targetOrValue: LegacyPropertyDecoratorTarget | undefined,\n    propertyKeyOrContext: CompatiblePropertyDecoratorContext<unknown, unknown>,\n  ) => {\n    registerCompatibleFieldDecorator(\n      targetOrValue,\n      propertyKeyOrContext,\n      (className, propertyKey) => {\n        ObjectRegistry.registerFieldDecorator(className, propertyKey, {\n          ...options,\n          type: 'crossPackageRef',\n          related: qualifiedName,\n        });\n      },\n    );\n  }) as CompatiblePropertyDecorator;\n}\n\n/**\n * Declares a one-to-many relationship from this object to a collection of related objects.\n *\n * The decorated property is `transient` — it is not persisted as a database column.\n * At runtime, call `instance.loadRelatedMany('fieldName')` to load the related objects,\n * or pass `include: ['fieldName']` to `collection.list()` for batch eager loading (issues\n * a single batched query for all instances instead of N individual queries).\n *\n * The inverse side (`@foreignKey`) must exist on the `relatedClass` pointing back to this\n * class. The framework discovers it automatically via `ObjectRegistry.getInverseRelationships()`.\n *\n * **Generated accessor (R10):** registering the class installs a consistent\n * `get<FieldName>()` instance method (e.g. `items` → `order.getItems()`) that\n * delegates to `loadRelatedMany('items')`. Generation is additive — a\n * hand-rolled method of the same name is never overwritten.\n *\n * **Disambiguation:** when `relatedClass` declares more than one `@foreignKey`\n * back to this class, pass `{ foreignKey: '<inverseFieldName>' }` so both\n * `loadRelatedMany` and the generated accessor resolve the intended inverse\n * side. Without it the first matching foreign key is used.\n *\n * **Delete behaviour is declared on the child, not here.** `@oneToMany` is a\n * transient read-side accessor; to have children removed with their parent,\n * put `onDelete: 'CASCADE'` on the inverse `@foreignKey` (#2371):\n *\n * ```typescript\n * class OrderItem extends SmrtObject {\n *   @foreignKey(Order, { onDelete: 'CASCADE' })\n *   orderId: string = '';\n * }\n * ```\n *\n * @param relatedClass - The class constructor of the child/related objects\n * @param options - Optional relationship options. `foreignKey` selects the\n *   inverse foreign-key field on `relatedClass` when it has more than one.\n * @returns A TypeScript property decorator (sets `transient: true` automatically)\n *\n * @example\n * ```typescript\n * @smrt()\n * class Order extends SmrtObject {\n *   @oneToMany(OrderItem)\n *   items: OrderItem[] = [];\n * }\n *\n * @smrt()\n * class OrderItem extends SmrtObject {\n *   @foreignKey(Order)\n *   orderId: string = '';\n * }\n *\n * const order = await orders.get({ id });\n * const items = await order.getItems(); // generated; === loadRelatedMany('items')\n * ```\n *\n * @example\n * ```typescript\n * // Multiple inverse foreign keys → disambiguate explicitly.\n * @smrt()\n * class Profile extends SmrtObject {\n *   @oneToMany(ProfileRelationship, { foreignKey: 'fromProfileId' })\n *   relationshipsFrom: ProfileRelationship[] = [];\n *   @oneToMany(ProfileRelationship, { foreignKey: 'toProfileId' })\n *   relationshipsTo: ProfileRelationship[] = [];\n * }\n * ```\n *\n * @see {@link foreignKey} for the many-to-one (child) side of the relationship\n * @see SmrtObject.loadRelatedMany for lazy-loading at runtime\n */\nexport function oneToMany(\n  relatedClass: string | Function,\n  options: Omit<RelationshipFieldOptions, 'related'> = {},\n) {\n  return ((\n    targetOrValue: LegacyPropertyDecoratorTarget | undefined,\n    propertyKeyOrContext: CompatiblePropertyDecoratorContext<unknown, unknown>,\n  ) => {\n    registerCompatibleFieldDecorator(\n      targetOrValue,\n      propertyKeyOrContext,\n      (className, propertyKey) => {\n        ObjectRegistry.registerFieldDecorator(className, propertyKey, {\n          ...options,\n          type: 'oneToMany',\n          related: resolveRelatedClassName(\n            'oneToMany',\n            relatedClass,\n            className,\n            propertyKey,\n          ),\n          transient: true, // Relationship fields are not database columns\n        });\n      },\n    );\n  }) as CompatiblePropertyDecorator;\n}\n\n/**\n * Declares a many-to-many relationship between two `SmrtObject` classes via a join table.\n *\n * The decorated property is `transient` — it is not persisted as a database column.\n * The `through` option specifies the junction table name. The join table model must\n * be decorated with `@smrt({ conflictColumns: ['...', '...'] })` to use the natural\n * key columns for upsert operations.\n *\n * Runtime loading: call `instance.loadRelatedMany('field')` to lazy-load, or\n * pass `include: ['field']` to `collection.list()` for batched eager loading.\n *\n * @param relatedClass - The class constructor of the related objects\n * @param options - Relationship options; `through` specifies the junction table name\n * @returns A TypeScript property decorator (sets `transient: true` automatically)\n *\n * @example\n * ```typescript\n * @smrt()\n * class Product extends SmrtObject {\n *   @manyToMany(Tag, { through: 'product_tags' })\n *   tags: Tag[] = [];\n * }\n * ```\n *\n * @see {@link oneToMany} for one-to-many relationships\n */\nexport function manyToMany(\n  relatedClass: string | Function,\n  options: Omit<RelationshipFieldOptions, 'related'> = {},\n) {\n  return ((\n    targetOrValue: LegacyPropertyDecoratorTarget | undefined,\n    propertyKeyOrContext: CompatiblePropertyDecoratorContext<unknown, unknown>,\n  ) => {\n    registerCompatibleFieldDecorator(\n      targetOrValue,\n      propertyKeyOrContext,\n      (className, propertyKey) => {\n        ObjectRegistry.registerFieldDecorator(className, propertyKey, {\n          ...options,\n          type: 'manyToMany',\n          related: resolveRelatedClassName(\n            'manyToMany',\n            relatedClass,\n            className,\n            propertyKey,\n          ),\n          transient: true, // Relationship fields are not database columns\n        });\n      },\n    );\n  }) as CompatiblePropertyDecorator;\n}\n\n/**\n * Marks a field as a Single Table Inheritance (STI) meta field.\n *\n * Meta fields are stored in the `_meta_data` JSONB column on the shared STI\n * table rather than as dedicated table columns. Use this decorator for fields\n * that are specific to an STI child class and should not pollute the shared\n * table schema with child-specific columns.\n *\n * The `@smrt({ tableStrategy: 'sti' })` decorator must be set on the base class.\n * All child-specific fields should use `@meta()` (or the `Meta<T>` type alias).\n *\n * @param options - Standard field options (required, nullable, description, etc.)\n * @returns A TypeScript property decorator (registers field with `type: 'meta'`)\n *\n * @example\n * ```typescript\n * @smrt({ tableStrategy: 'sti' })\n * class Event extends SmrtObject {\n *   title: string = ''; // shared column on events table\n * }\n *\n * @smrt()\n * class Meeting extends Event {\n *   @meta()\n *   roomNumber: string = ''; // stored in _meta_data JSON, not a column\n *\n *   @meta({ required: true })\n *   durationMinutes: number = 60;\n * }\n * ```\n *\n * @see {@link Meta} for the equivalent type alias approach\n * @see {@link field} for regular (non-STI) field declarations\n */\nexport function meta(options: FieldOptions = {}) {\n  return ((\n    targetOrValue: LegacyPropertyDecoratorTarget | undefined,\n    propertyKeyOrContext: CompatiblePropertyDecoratorContext<unknown, unknown>,\n  ) => {\n    registerCompatibleFieldDecorator(\n      targetOrValue,\n      propertyKeyOrContext,\n      (className, propertyKey) => {\n        ObjectRegistry.registerFieldDecorator(className, propertyKey, {\n          ...options,\n          type: 'meta', // Mark this field as a meta field for STI\n        });\n      },\n    );\n  }) as CompatiblePropertyDecorator;\n}\n\n/**\n * Options for {@link method}.\n *\n * Every option is optional, and an omitted one falls back to the class-level\n * `api.routes[methodName]` entry (or `ai.descriptions[methodName]` for\n * `description`) when one exists. The merge is FIELD BY FIELD, so adding\n * `@method({ description })` to a class that already declares a route verb and\n * path does not reset them (#2686).\n */\nexport interface MethodOptions {\n  /**\n   * Override the default routing decision.\n   *\n   * Public methods are routed by default when they are WIRE-ABLE: every\n   * parameter can be built from a JSON request body or query string. Set\n   * `false` to withhold a method the heuristic accepted, `true` to expose one\n   * it rejected.\n   *\n   * `true` bypasses the heuristic and NOTHING else. It cannot manufacture a\n   * receiver, undo `api: false`, cross an `include`/`exclude` boundary, reach a\n   * non-public method, claim a CRUD verb, or hydrate a value the transport\n   * cannot build — a model-instance parameter still arrives as whatever JSON\n   * the caller sent.\n   */\n  expose?: boolean;\n\n  /**\n   * Why the method is withheld. Recorded in the knowledge artifact so\n   * `smrt doctor` and agents read an explanation instead of silence.\n   */\n  reason?: string;\n\n  /**\n   * HTTP verb for the generated route. Defaults to `POST`.\n   *\n   * Named `httpMethod`, not `method`: RFC 9110 calls this the request\n   * \"method\", so the protocol word is exactly the one that collides with the\n   * decorator's own name, and `@method({ method: 'POST' })` stutters.\n   * `httpMethod` is also already this framework's name for it — `ApiHttpMethod`\n   * is carried across the whole discovery/invoke path.\n   *\n   * Migrates from `api.routes[methodName].method`.\n   */\n  httpMethod?: ApiHttpMethod;\n\n  /**\n   * Route path segment(s), used verbatim and split on `/`.\n   * Defaults to the method name. Migrates from `api.routes[methodName].path`.\n   */\n  path?: string;\n\n  /**\n   * Declared receiver scope. Migrates from `api.routes[methodName].scope`.\n   *\n   * A DECLARATION checked against the method's executable receiver, not a\n   * relocation: an instance method is item-scoped and a static (or\n   * collection-class) method is collection-scoped, and no config can change\n   * that. A contradicting value is reported at build time and ignored.\n   */\n  scope?: CustomActionScope;\n\n  /**\n   * Agent-visible effect classification. Omitted actions are treated as\n   * `destructive`, so missing metadata can never widen browser capability\n   * exposure. Migrates from `api.routes[methodName].effect`.\n   */\n  effect?: ToolEffect;\n\n  /** Whether repeating the action with the same arguments is safe. */\n  idempotent?: boolean;\n\n  /** Whether the action may interact outside the SMRT application. */\n  openWorld?: boolean;\n\n  /**\n   * Description used by AI/tool surfaces, overriding the method's JSDoc.\n   * Migrates from `ai.descriptions[methodName]`.\n   */\n  description?: string;\n}\n\n/**\n * Refines how a method is exposed on generated surfaces.\n *\n * The method counterpart of {@link field}, and symmetric with it: a manifest\n * records exactly two collections per object, `fields` and `methods`. Neither\n * decorator DECLARES its member — a property is a field because it is a\n * property, and a method is a candidate action because it is public — both\n * REFINE what the framework already inferred. `@field()` refines an inferred\n * column type and constraints; `@method()` refines inferred exposure, its\n * route shape, and its tool semantics.\n *\n * The name is `@method()` rather than `@action()` because of the negative\n * case: withholding a method has to read correctly, and\n * `@action({ expose: false })` contradicts itself — declaring something an\n * action in order to say it is not one. \"Action\" keeps its established meaning\n * in the generators (a non-CRUD method exposed on a surface); this decorator\n * is how a method BECOMES one.\n *\n * Metadata only: the decorated method is not wrapped and keeps its identity,\n * so it stays directly callable.\n *\n * @example Shape the generated route\n * ```typescript\n * @method({ httpMethod: 'POST', path: 'reviews', effect: 'write' })\n * async runReview(options?: RunContentReviewOptions) { … }\n * ```\n *\n * @example Withhold a method the heuristic would have routed\n * ```typescript\n * @method({ expose: false, reason: 'callback registration, not a wire operation' })\n * static registerValidator(validator: ValidatorFunction) { … }\n * ```\n *\n * @example Force a route the heuristic rejected\n * ```typescript\n * // `expose: true` bypasses the heuristic only — this method must still\n * // accept whatever JSON the caller sends for `asset`.\n * @method({ expose: true })\n * async addAsset(asset: Asset) { … }\n * ```\n *\n * @see {@link field} for the property-side refinement decorator\n */\nexport function method(options: MethodOptions = {}) {\n  return ((\n    targetOrValue: unknown,\n    propertyKeyOrContext: CompatibleMethodDecoratorContext<\n      unknown,\n      // biome-ignore lint/suspicious/noExplicitAny: mirrors the lib's own `ClassMethodDecoratorContext` constraint; see `AnyMethodOf` in `compatibility.ts`. S4 #1579.\n      (this: unknown, ...args: any) => any\n    >,\n  ) => {\n    registerCompatibleMethodDecorator(\n      targetOrValue as LegacyPropertyDecoratorTarget | undefined,\n      propertyKeyOrContext,\n      (ctor, methodName, isStatic) => {\n        ObjectRegistry.registerMethodDecorator(\n          ctor,\n          methodName,\n          options,\n          isStatic,\n        );\n      },\n    );\n  }) as CompatibleMethodDecorator;\n}\n"],"mappings":"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"}

package/dist/embedded-write-queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embedded-write-queue.d.ts","sourceRoot":"","sources":["../src/embedded-write-queue.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AA0C5D,UAAU,iBAAiB;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,iBAAiB,GAAG,OAAO,CAEjE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,iBAAiB,GAAG,OAAO,CAEjE;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,iBAAiB,GAAG,OAAO,CAG3E;AAMD;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,EAAE,EAAE,iBAAiB,EACrB,SAAS,EAAE,OAAO,EAClB,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,CAAC,CAAC,CAwBZ;AAED;;;;;GAKG;AACH,wBAAsB,4BAA4B,CAAC,CAAC,EAClD,EAAE,EAAE,iBAAiB,EACrB,SAAS,EAAE,OAAO,EAClB,SAAS,EAAE,CAAC,WAAW,EAAE,iBAAiB,KAAK,OAAO,CAAC,CAAC,CAAC,GACxD,OAAO,CAAC,CAAC,CAAC,CAeZ"}
+{"version":3,"file":"embedded-write-queue.d.ts","sourceRoot":"","sources":["../src/embedded-write-queue.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AA0C5D,UAAU,iBAAiB;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,iBAAiB,GAAG,OAAO,CAEjE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,iBAAiB,GAAG,OAAO,CAEjE;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,iBAAiB,GAAG,OAAO,CAG3E;AA0BD;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,EAAE,EAAE,iBAAiB,EACrB,SAAS,EAAE,OAAO,EAClB,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,CAAC,CAAC,CAwBZ;AAED;;;;;GAKG;AACH,wBAAsB,4BAA4B,CAAC,CAAC,EAClD,EAAE,EAAE,iBAAiB,EACrB,SAAS,EAAE,OAAO,EAClB,SAAS,EAAE,CAAC,WAAW,EAAE,iBAAiB,KAAK,OAAO,CAAC,CAAC,CAAC,GACxD,OAAO,CAAC,CAAC,CAAC,CAeZ"}

package/dist/embedded-write-queue.js

@@ -69,8 +69,27 @@ function usesEmbeddedRevisionFallback(db) {
 	const url = db?.url ?? "";
 	return isEmbeddedDatabase(db) && !/^(?:https?|libsql):\/\//iu.test(url);
 }
+/**
+* Whether `url` identifies a SQLite/DuckDB in-memory database that is
+* private to its own connection, as opposed to shared state.
+*
+* Bare `:memory:` and `file::memory:` (no query string) each mint a fresh,
+* connection-private database -- `resolveDuckDBUrl(':memory:')` returns it
+* unchanged, with no per-instance suffix -- so two independent handles that
+* both happen to carry this literal string are NOT the same database and
+* must not share a write-queue identity (#2707). A `cache=shared` query
+* parameter (e.g. `file::memory:?cache=shared`) is the opposite case: it is
+* SQLite's own mechanism for making an in-memory database genuinely shared
+* across connections in the process, so a URL carrying it must keep the
+* ordinary string-keyed (shared) behavior.
+*/
+function isPerConnectionMemoryUrl(url) {
+	if (url.includes("cache=shared")) return false;
+	return url === ":memory:" || url === "file::memory:";
+}
 function queueKey(db) {
-	return typeof db?.url === "string" && db.url.length > 0 ? db.url : db;
+	if (typeof db?.url !== "string" || db.url.length === 0) return db;
+	return isPerConnectionMemoryUrl(db.url) ? db : db.url;
 }
 /**
 * Run `operation` after every previously queued write on the same database

package/dist/embedded-write-queue.js.map

@@ -1 +1 @@
-{"version":3,"file":"embedded-write-queue.js","names":[],"sources":["../src/embedded-write-queue.ts"],"sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks';\nimport type { DatabaseInterface } from '@happyvertical/sql';\n\n/**\n * In-process write serialization for embedded database engines (#2360).\n *\n * File-backed SQLite (libsql) allows one writer at a time and the SDK opens a\n * NEW connection for every null-aware upsert attempt (`transaction(\"write\")`),\n * with no busy timeout on either connection. Any other write on the root\n * connection while such a transaction is open — most commonly the change-feed\n * append that follows every model save — collides as `SQLITE_BUSY`, and under\n * sustained concurrency (a `Promise.all` of creates) the two sides livelock\n * through every retry tier. Before the tenant-led conflict target (#2360) the\n * null-aware path was rare (custom conflict keys with NULL values, #1246);\n * with `tenant_id` leading every tenant-scoped default key, EVERY NULL-tenant\n * (global) create takes it, so the collision became the steady state.\n *\n * The queue makes the process a single writer per embedded database for:\n *\n * - a `save()` whose upsert conflict values contain NULL (the only shape the\n *   SDK routes through a second-connection transaction), and\n * - the change-feed append (a root-connection write that follows every save).\n * - every model save and delete, so the embedded revision-CAS compare/upsert\n *   fallback cannot race an ordinary save, natural-key create, or delete.\n * - a complete root `SmrtObject.withTransaction()` callback, with writes on\n *   its bound handle re-entering the same hold instead of self-deadlocking.\n *\n * Ordinary save/delete holds contain database calls only — never an\n * interceptor or hook. Explicit transaction callbacks are caller-controlled,\n * so their bound model writes re-enter the existing hold. PostgreSQL is never\n * serialized here:\n * its null-aware upsert already arbitrates through advisory locks\n * server-side, and cross-process writers exist that an in-process queue could\n * not order anyway (which is also why this queue is a mitigation for embedded\n * engines' in-process writers, not a cross-process guarantee — embedded\n * engines have no cross-process writers in supported deployments).\n */\n\n/** Queue tail per database identity (URL string, or the handle itself). */\nconst urlQueues = new Map<string, Promise<unknown>>();\nconst handleQueues = new WeakMap<object, Promise<unknown>>();\nconst activeQueueKeys = new AsyncLocalStorage<ReadonlySet<string | object>>();\n\ninterface QueueableDatabase {\n  url?: string;\n}\n\n/**\n * Whether `db` is an embedded engine (SQLite/DuckDB/JSON — anything that is\n * not PostgreSQL). Handles without a URL are treated as embedded: serializing\n * them is at worst a throughput cost, while not serializing an embedded\n * handle reintroduces the livelock.\n */\nexport function isEmbeddedDatabase(db: QueueableDatabase): boolean {\n  return !isPostgresDatabase(db);\n}\n\n/**\n * Whether `db` is a PostgreSQL handle.\n *\n * The revision compare-and-swap predicate is dialect-specific (#2620): only\n * PostgreSQL needs the millisecond-truncating, timezone-tolerant guard, and\n * only PostgreSQL can evaluate `date_trunc`.\n */\nexport function isPostgresDatabase(db: QueueableDatabase): boolean {\n  return /^postgres(?:ql)?:/iu.test(db?.url ?? '');\n}\n\n/**\n * Whether revision compare-and-swap needs the process-local read/upsert path.\n *\n * DuckDB/JSON cannot express the timestamp predicate through the generic\n * update API, and local SQLite has only the process's writers in supported\n * deployments. Remote LibSQL/Turso is different: other processes may write\n * the same database, so it must use one conditional UPDATE at the server.\n */\nexport function usesEmbeddedRevisionFallback(db: QueueableDatabase): boolean {\n  const url = db?.url ?? '';\n  return isEmbeddedDatabase(db) && !/^(?:https?|libsql):\\/\\//iu.test(url);\n}\n\nfunction queueKey(db: QueueableDatabase): string | object {\n  return typeof db?.url === 'string' && db.url.length > 0 ? db.url : db;\n}\n\n/**\n * Run `operation` after every previously queued write on the same database\n * has settled. When `serialize` is false the operation runs immediately.\n */\nexport async function withEmbeddedWriteQueue<T>(\n  db: QueueableDatabase,\n  serialize: boolean,\n  operation: () => Promise<T>,\n): Promise<T> {\n  if (!serialize) return operation();\n\n  const key = queueKey(db);\n  const active = activeQueueKeys.getStore();\n  if (active?.has(key)) return operation();\n  const previous =\n    (typeof key === 'string' ? urlQueues.get(key) : handleQueues.get(key)) ??\n    Promise.resolve();\n  const run = () =>\n    activeQueueKeys.run(new Set([...(active ?? []), key]), operation);\n  const next = previous.then(run, run);\n  // The stored tail must never reject, or one failed write would poison the\n  // queue for every later writer.\n  const tail = next.catch(() => undefined);\n  if (typeof key === 'string') {\n    urlQueues.set(key, tail);\n    void tail.finally(() => {\n      if (urlQueues.get(key) === tail) urlQueues.delete(key);\n    });\n  } else {\n    handleQueues.set(key, tail);\n  }\n  return next;\n}\n\n/**\n * Serialize a complete embedded root transaction with ordinary model writes.\n * The transaction handle is registered as a reentrant alias so saves and\n * change-feed appends inside the callback do not queue behind their own root\n * transaction.\n */\nexport async function withEmbeddedWriteTransaction<T>(\n  db: DatabaseInterface,\n  serialize: boolean,\n  operation: (transaction: DatabaseInterface) => Promise<T>,\n): Promise<T> {\n  const transaction = db.transaction?.bind(db);\n  if (!transaction) {\n    throw new Error('Database transaction support is required');\n  }\n  return withEmbeddedWriteQueue(db, serialize, () =>\n    transaction((bound) => {\n      if (!serialize) return operation(bound);\n      const active = activeQueueKeys.getStore();\n      return activeQueueKeys.run(\n        new Set([...(active ?? []), queueKey(bound)]),\n        () => operation(bound),\n      );\n    }),\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,IAAM,4BAAY,IAAI,IAA8B;AACpD,IAAM,+BAAe,IAAI,QAAkC;AAC3D,IAAM,kBAAkB,IAAI,kBAAgD;;;;;;;AAY5E,SAAgB,mBAAmB,IAAgC;CACjE,OAAO,CAAC,mBAAmB,EAAE;AAC/B;;;;;;;;AASA,SAAgB,mBAAmB,IAAgC;CACjE,OAAO,sBAAsB,KAAK,IAAI,OAAO,EAAE;AACjD;;;;;;;;;AAUA,SAAgB,6BAA6B,IAAgC;CAC3E,MAAM,MAAM,IAAI,OAAO;CACvB,OAAO,mBAAmB,EAAE,KAAK,CAAC,4BAA4B,KAAK,GAAG;AACxE;AAEA,SAAS,SAAS,IAAwC;CACxD,OAAO,OAAO,IAAI,QAAQ,YAAY,GAAG,IAAI,SAAS,IAAI,GAAG,MAAM;AACrE;;;;;AAMA,eAAsB,uBACpB,IACA,WACA,WACY;CACZ,IAAI,CAAC,WAAW,OAAO,UAAU;CAEjC,MAAM,MAAM,SAAS,EAAE;CACvB,MAAM,SAAS,gBAAgB,SAAS;CACxC,IAAI,QAAQ,IAAI,GAAG,GAAG,OAAO,UAAU;CACvC,MAAM,YACH,OAAO,QAAQ,WAAW,UAAU,IAAI,GAAG,IAAI,aAAa,IAAI,GAAG,MACpE,QAAQ,QAAQ;CAClB,MAAM,YACJ,gBAAgB,oBAAI,IAAI,IAAI,CAAC,GAAI,UAAU,CAAC,GAAI,GAAG,CAAC,GAAG,SAAS;CAClE,MAAM,OAAO,SAAS,KAAK,KAAK,GAAG;CAGnC,MAAM,OAAO,KAAK,YAAY,KAAA,CAAS;CACvC,IAAI,OAAO,QAAQ,UAAU;EAC3B,UAAU,IAAI,KAAK,IAAI;EACvB,KAAU,cAAc;GACtB,IAAI,UAAU,IAAI,GAAG,MAAM,MAAM,UAAU,OAAO,GAAG;EACvD,CAAC;CACH,OACE,aAAa,IAAI,KAAK,IAAI;CAE5B,OAAO;AACT;;;;;;;AAQA,eAAsB,6BACpB,IACA,WACA,WACY;CACZ,MAAM,cAAc,GAAG,aAAa,KAAK,EAAE;CAC3C,IAAI,CAAC,aACH,MAAM,IAAI,MAAM,0CAA0C;CAE5D,OAAO,uBAAuB,IAAI,iBAChC,aAAa,UAAU;EACrB,IAAI,CAAC,WAAW,OAAO,UAAU,KAAK;EACtC,MAAM,SAAS,gBAAgB,SAAS;EACxC,OAAO,gBAAgB,oBACrB,IAAI,IAAI,CAAC,GAAI,UAAU,CAAC,GAAI,SAAS,KAAK,CAAC,CAAC,SACtC,UAAU,KAAK,CACvB;CACF,CAAC,CACH;AACF"}
+{"version":3,"file":"embedded-write-queue.js","names":[],"sources":["../src/embedded-write-queue.ts"],"sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks';\nimport type { DatabaseInterface } from '@happyvertical/sql';\n\n/**\n * In-process write serialization for embedded database engines (#2360).\n *\n * File-backed SQLite (libsql) allows one writer at a time and the SDK opens a\n * NEW connection for every null-aware upsert attempt (`transaction(\"write\")`),\n * with no busy timeout on either connection. Any other write on the root\n * connection while such a transaction is open — most commonly the change-feed\n * append that follows every model save — collides as `SQLITE_BUSY`, and under\n * sustained concurrency (a `Promise.all` of creates) the two sides livelock\n * through every retry tier. Before the tenant-led conflict target (#2360) the\n * null-aware path was rare (custom conflict keys with NULL values, #1246);\n * with `tenant_id` leading every tenant-scoped default key, EVERY NULL-tenant\n * (global) create takes it, so the collision became the steady state.\n *\n * The queue makes the process a single writer per embedded database for:\n *\n * - a `save()` whose upsert conflict values contain NULL (the only shape the\n *   SDK routes through a second-connection transaction), and\n * - the change-feed append (a root-connection write that follows every save).\n * - every model save and delete, so the embedded revision-CAS compare/upsert\n *   fallback cannot race an ordinary save, natural-key create, or delete.\n * - a complete root `SmrtObject.withTransaction()` callback, with writes on\n *   its bound handle re-entering the same hold instead of self-deadlocking.\n *\n * Ordinary save/delete holds contain database calls only — never an\n * interceptor or hook. Explicit transaction callbacks are caller-controlled,\n * so their bound model writes re-enter the existing hold. PostgreSQL is never\n * serialized here:\n * its null-aware upsert already arbitrates through advisory locks\n * server-side, and cross-process writers exist that an in-process queue could\n * not order anyway (which is also why this queue is a mitigation for embedded\n * engines' in-process writers, not a cross-process guarantee — embedded\n * engines have no cross-process writers in supported deployments).\n */\n\n/** Queue tail per database identity (URL string, or the handle itself). */\nconst urlQueues = new Map<string, Promise<unknown>>();\nconst handleQueues = new WeakMap<object, Promise<unknown>>();\nconst activeQueueKeys = new AsyncLocalStorage<ReadonlySet<string | object>>();\n\ninterface QueueableDatabase {\n  url?: string;\n}\n\n/**\n * Whether `db` is an embedded engine (SQLite/DuckDB/JSON — anything that is\n * not PostgreSQL). Handles without a URL are treated as embedded: serializing\n * them is at worst a throughput cost, while not serializing an embedded\n * handle reintroduces the livelock.\n */\nexport function isEmbeddedDatabase(db: QueueableDatabase): boolean {\n  return !isPostgresDatabase(db);\n}\n\n/**\n * Whether `db` is a PostgreSQL handle.\n *\n * The revision compare-and-swap predicate is dialect-specific (#2620): only\n * PostgreSQL needs the millisecond-truncating, timezone-tolerant guard, and\n * only PostgreSQL can evaluate `date_trunc`.\n */\nexport function isPostgresDatabase(db: QueueableDatabase): boolean {\n  return /^postgres(?:ql)?:/iu.test(db?.url ?? '');\n}\n\n/**\n * Whether revision compare-and-swap needs the process-local read/upsert path.\n *\n * DuckDB/JSON cannot express the timestamp predicate through the generic\n * update API, and local SQLite has only the process's writers in supported\n * deployments. Remote LibSQL/Turso is different: other processes may write\n * the same database, so it must use one conditional UPDATE at the server.\n */\nexport function usesEmbeddedRevisionFallback(db: QueueableDatabase): boolean {\n  const url = db?.url ?? '';\n  return isEmbeddedDatabase(db) && !/^(?:https?|libsql):\\/\\//iu.test(url);\n}\n\n/**\n * Whether `url` identifies a SQLite/DuckDB in-memory database that is\n * private to its own connection, as opposed to shared state.\n *\n * Bare `:memory:` and `file::memory:` (no query string) each mint a fresh,\n * connection-private database -- `resolveDuckDBUrl(':memory:')` returns it\n * unchanged, with no per-instance suffix -- so two independent handles that\n * both happen to carry this literal string are NOT the same database and\n * must not share a write-queue identity (#2707). A `cache=shared` query\n * parameter (e.g. `file::memory:?cache=shared`) is the opposite case: it is\n * SQLite's own mechanism for making an in-memory database genuinely shared\n * across connections in the process, so a URL carrying it must keep the\n * ordinary string-keyed (shared) behavior.\n */\nfunction isPerConnectionMemoryUrl(url: string): boolean {\n  if (url.includes('cache=shared')) return false;\n  return url === ':memory:' || url === 'file::memory:';\n}\n\nfunction queueKey(db: QueueableDatabase): string | object {\n  if (typeof db?.url !== 'string' || db.url.length === 0) return db;\n  return isPerConnectionMemoryUrl(db.url) ? db : db.url;\n}\n\n/**\n * Run `operation` after every previously queued write on the same database\n * has settled. When `serialize` is false the operation runs immediately.\n */\nexport async function withEmbeddedWriteQueue<T>(\n  db: QueueableDatabase,\n  serialize: boolean,\n  operation: () => Promise<T>,\n): Promise<T> {\n  if (!serialize) return operation();\n\n  const key = queueKey(db);\n  const active = activeQueueKeys.getStore();\n  if (active?.has(key)) return operation();\n  const previous =\n    (typeof key === 'string' ? urlQueues.get(key) : handleQueues.get(key)) ??\n    Promise.resolve();\n  const run = () =>\n    activeQueueKeys.run(new Set([...(active ?? []), key]), operation);\n  const next = previous.then(run, run);\n  // The stored tail must never reject, or one failed write would poison the\n  // queue for every later writer.\n  const tail = next.catch(() => undefined);\n  if (typeof key === 'string') {\n    urlQueues.set(key, tail);\n    void tail.finally(() => {\n      if (urlQueues.get(key) === tail) urlQueues.delete(key);\n    });\n  } else {\n    handleQueues.set(key, tail);\n  }\n  return next;\n}\n\n/**\n * Serialize a complete embedded root transaction with ordinary model writes.\n * The transaction handle is registered as a reentrant alias so saves and\n * change-feed appends inside the callback do not queue behind their own root\n * transaction.\n */\nexport async function withEmbeddedWriteTransaction<T>(\n  db: DatabaseInterface,\n  serialize: boolean,\n  operation: (transaction: DatabaseInterface) => Promise<T>,\n): Promise<T> {\n  const transaction = db.transaction?.bind(db);\n  if (!transaction) {\n    throw new Error('Database transaction support is required');\n  }\n  return withEmbeddedWriteQueue(db, serialize, () =>\n    transaction((bound) => {\n      if (!serialize) return operation(bound);\n      const active = activeQueueKeys.getStore();\n      return activeQueueKeys.run(\n        new Set([...(active ?? []), queueKey(bound)]),\n        () => operation(bound),\n      );\n    }),\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,IAAM,4BAAY,IAAI,IAA8B;AACpD,IAAM,+BAAe,IAAI,QAAkC;AAC3D,IAAM,kBAAkB,IAAI,kBAAgD;;;;;;;AAY5E,SAAgB,mBAAmB,IAAgC;CACjE,OAAO,CAAC,mBAAmB,EAAE;AAC/B;;;;;;;;AASA,SAAgB,mBAAmB,IAAgC;CACjE,OAAO,sBAAsB,KAAK,IAAI,OAAO,EAAE;AACjD;;;;;;;;;AAUA,SAAgB,6BAA6B,IAAgC;CAC3E,MAAM,MAAM,IAAI,OAAO;CACvB,OAAO,mBAAmB,EAAE,KAAK,CAAC,4BAA4B,KAAK,GAAG;AACxE;;;;;;;;;;;;;;;AAgBA,SAAS,yBAAyB,KAAsB;CACtD,IAAI,IAAI,SAAS,cAAc,GAAG,OAAO;CACzC,OAAO,QAAQ,cAAc,QAAQ;AACvC;AAEA,SAAS,SAAS,IAAwC;CACxD,IAAI,OAAO,IAAI,QAAQ,YAAY,GAAG,IAAI,WAAW,GAAG,OAAO;CAC/D,OAAO,yBAAyB,GAAG,GAAG,IAAI,KAAK,GAAG;AACpD;;;;;AAMA,eAAsB,uBACpB,IACA,WACA,WACY;CACZ,IAAI,CAAC,WAAW,OAAO,UAAU;CAEjC,MAAM,MAAM,SAAS,EAAE;CACvB,MAAM,SAAS,gBAAgB,SAAS;CACxC,IAAI,QAAQ,IAAI,GAAG,GAAG,OAAO,UAAU;CACvC,MAAM,YACH,OAAO,QAAQ,WAAW,UAAU,IAAI,GAAG,IAAI,aAAa,IAAI,GAAG,MACpE,QAAQ,QAAQ;CAClB,MAAM,YACJ,gBAAgB,oBAAI,IAAI,IAAI,CAAC,GAAI,UAAU,CAAC,GAAI,GAAG,CAAC,GAAG,SAAS;CAClE,MAAM,OAAO,SAAS,KAAK,KAAK,GAAG;CAGnC,MAAM,OAAO,KAAK,YAAY,KAAA,CAAS;CACvC,IAAI,OAAO,QAAQ,UAAU;EAC3B,UAAU,IAAI,KAAK,IAAI;EACvB,KAAU,cAAc;GACtB,IAAI,UAAU,IAAI,GAAG,MAAM,MAAM,UAAU,OAAO,GAAG;EACvD,CAAC;CACH,OACE,aAAa,IAAI,KAAK,IAAI;CAE5B,OAAO;AACT;;;;;;;AAQA,eAAsB,6BACpB,IACA,WACA,WACY;CACZ,MAAM,cAAc,GAAG,aAAa,KAAK,EAAE;CAC3C,IAAI,CAAC,aACH,MAAM,IAAI,MAAM,0CAA0C;CAE5D,OAAO,uBAAuB,IAAI,iBAChC,aAAa,UAAU;EACrB,IAAI,CAAC,WAAW,OAAO,UAAU,KAAK;EACtC,MAAM,SAAS,gBAAgB,SAAS;EACxC,OAAO,gBAAgB,oBACrB,IAAI,IAAI,CAAC,GAAI,UAAU,CAAC,GAAI,SAAS,KAAK,CAAC,CAAC,SACtC,UAAU,KAAK,CACvB;CACF,CAAC,CACH;AACF"}