@happyvertical/smrt-core 0.30.0

package/dist/decorators/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","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 { SQLDataType } from '../schema/types.js';\nimport {\n  type CompatiblePropertyDecorator,\n  type CompatiblePropertyDecoratorContext,\n  type LegacyPropertyDecoratorTarget,\n  registerCompatibleFieldDecorator,\n} from './compatibility.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?: any;\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 — giving WHERE clauses on that\n   * meta key the same performance as a real column.\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  /** Field description */\n  description?: string;\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\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 * 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<any, any>,\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 * For cross-package foreign keys, use a plain `string` property instead to avoid\n * circular dependencies between packages.\n *\n * @param relatedClass - The target class constructor (or class name string)\n * @param options - Optional field constraints (required, nullable, etc.)\n * @returns A TypeScript property decorator\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 *\n * // Cross-package: use a plain string instead\n * @smrt()\n * class Post extends SmrtObject {\n *   authorId: string = ''; // plain string — no circular dep\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 | any,\n  options: Omit<RelationshipFieldOptions, 'related'> = {},\n) {\n  return ((\n    targetOrValue: LegacyPropertyDecoratorTarget | undefined,\n    propertyKeyOrContext: CompatiblePropertyDecoratorContext<any, any>,\n  ) => {\n    const relatedClassName =\n      typeof relatedClass === 'string' ? relatedClass : relatedClass.name;\n\n    registerCompatibleFieldDecorator(\n      targetOrValue,\n      propertyKeyOrContext,\n      (className, propertyKey) => {\n        ObjectRegistry.registerFieldDecorator(className, propertyKey, {\n          ...options,\n          type: 'foreignKey',\n          related: relatedClassName,\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 * Unlike `@foreignKey()`, this decorator does **not** emit a DDL `FOREIGN KEY`\n * constraint — cross-package classes are not visible at schema-generation time and\n * adding a constraint would force a circular package dependency. The decorated\n * property remains a plain `TEXT` column at the database level.\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 * - Optional save-time validation (`validate: true`) confirms the referenced\n *   object exists, catching typos and stale IDs before they hit the database.\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 (emits FK constraint)\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<any, any>,\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 * @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 | any,\n  options: Omit<RelationshipFieldOptions, 'related'> = {},\n) {\n  return ((\n    targetOrValue: LegacyPropertyDecoratorTarget | undefined,\n    propertyKeyOrContext: CompatiblePropertyDecoratorContext<any, any>,\n  ) => {\n    const relatedClassName =\n      typeof relatedClass === 'string' ? relatedClass : relatedClass.name;\n\n    registerCompatibleFieldDecorator(\n      targetOrValue,\n      propertyKeyOrContext,\n      (className, propertyKey) => {\n        ObjectRegistry.registerFieldDecorator(className, propertyKey, {\n          ...options,\n          type: 'oneToMany',\n          related: relatedClassName,\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 | any,\n  options: Omit<RelationshipFieldOptions, 'related'> = {},\n) {\n  return ((\n    targetOrValue: LegacyPropertyDecoratorTarget | undefined,\n    propertyKeyOrContext: CompatiblePropertyDecoratorContext<any, any>,\n  ) => {\n    const relatedClassName =\n      typeof relatedClass === 'string' ? relatedClass : relatedClass.name;\n\n    registerCompatibleFieldDecorator(\n      targetOrValue,\n      propertyKeyOrContext,\n      (className, propertyKey) => {\n        ObjectRegistry.registerFieldDecorator(className, propertyKey, {\n          ...options,\n          type: 'manyToMany',\n          related: relatedClassName,\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<any, any>,\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"],"names":[],"mappings":";;AAyNO,SAAS,MACd,UAAiE,IACjE;AACA,UAAQ,CACN,eACA,yBACG;AACH;AAAA,MACE;AAAA,MACA;AAAA,MACA,CAAC,WAAW,gBAAgB;AAC1B,uBAAe,uBAAuB,WAAW,aAAa,OAAO;AAAA,MACvE;AAAA,IAAA;AAAA,EAEJ;AACF;AAoCO,SAAS,WACd,cACA,UAAqD,IACrD;AACA,UAAQ,CACN,eACA,yBACG;AACH,UAAM,mBACJ,OAAO,iBAAiB,WAAW,eAAe,aAAa;AAEjE;AAAA,MACE;AAAA,MACA;AAAA,MACA,CAAC,WAAW,gBAAgB;AAC1B,uBAAe,uBAAuB,WAAW,aAAa;AAAA,UAC5D,GAAG;AAAA,UACH,MAAM;AAAA,UACN,SAAS;AAAA,QAAA,CACV;AAAA,MACH;AAAA,IAAA;AAAA,EAEJ;AACF;AA0CO,SAAS,gBACd,eACA,UAAkC,IAClC;AACA,UAAQ,CACN,eACA,yBACG;AACH;AAAA,MACE;AAAA,MACA;AAAA,MACA,CAAC,WAAW,gBAAgB;AAC1B,uBAAe,uBAAuB,WAAW,aAAa;AAAA,UAC5D,GAAG;AAAA,UACH,MAAM;AAAA,UACN,SAAS;AAAA,QAAA,CACV;AAAA,MACH;AAAA,IAAA;AAAA,EAEJ;AACF;AA6DO,SAAS,UACd,cACA,UAAqD,IACrD;AACA,UAAQ,CACN,eACA,yBACG;AACH,UAAM,mBACJ,OAAO,iBAAiB,WAAW,eAAe,aAAa;AAEjE;AAAA,MACE;AAAA,MACA;AAAA,MACA,CAAC,WAAW,gBAAgB;AAC1B,uBAAe,uBAAuB,WAAW,aAAa;AAAA,UAC5D,GAAG;AAAA,UACH,MAAM;AAAA,UACN,SAAS;AAAA,UACT,WAAW;AAAA;AAAA,QAAA,CACZ;AAAA,MACH;AAAA,IAAA;AAAA,EAEJ;AACF;AA4BO,SAAS,WACd,cACA,UAAqD,IACrD;AACA,UAAQ,CACN,eACA,yBACG;AACH,UAAM,mBACJ,OAAO,iBAAiB,WAAW,eAAe,aAAa;AAEjE;AAAA,MACE;AAAA,MACA;AAAA,MACA,CAAC,WAAW,gBAAgB;AAC1B,uBAAe,uBAAuB,WAAW,aAAa;AAAA,UAC5D,GAAG;AAAA,UACH,MAAM;AAAA,UACN,SAAS;AAAA,UACT,WAAW;AAAA;AAAA,QAAA,CACZ;AAAA,MACH;AAAA,IAAA;AAAA,EAEJ;AACF;AAoCO,SAAS,KAAK,UAAwB,IAAI;AAC/C,UAAQ,CACN,eACA,yBACG;AACH;AAAA,MACE;AAAA,MACA;AAAA,MACA,CAAC,WAAW,gBAAgB;AAC1B,uBAAe,uBAAuB,WAAW,aAAa;AAAA,UAC5D,GAAG;AAAA,UACH,MAAM;AAAA;AAAA,QAAA,CACP;AAAA,MACH;AAAA,IAAA;AAAA,EAEJ;AACF;"}

package/dist/dispatch/bus.d.ts

@@ -0,0 +1,306 @@
+import { DatabaseInterface } from '@happyvertical/sql';
+import { Dispatch } from './models/Dispatch.js';
+import { DispatchSubscription } from './models/DispatchSubscription.js';
+import { DispatchBusOptions, DispatchCleanupOptions, DispatchCleanupResult, DispatchEmitOptions, DispatchHandler, DispatchListOptions, DispatchProcessOptions, DispatchRetryOptions, DispatchSubscribeOptions } from './types.js';
+/**
+ * Central hub for inter-agent messaging with both in-memory and persistent delivery.
+ *
+ * The `DispatchBus` combines two complementary delivery models:
+ *
+ * - **In-memory handlers** (`on(pattern, handler)`) — called synchronously (fire-and-forget)
+ *   when a dispatch is emitted. Fast, but lost on process restart.
+ * - **Persistent subscriptions** (`subscribe({ signalType, subscriber })`) — stored in
+ *   `_smrt_dispatch_subscriptions` and processed later by calling `process(subscriber, handler)`.
+ *   Survive restarts; suitable for background workers and scheduled agents.
+ *
+ * Signal types support single-segment wildcards: `'campaign.*'` matches `'campaign.completed'`
+ * and `'campaign.failed'`, but not `'campaign.phase.two'`.
+ *
+ * Dispatch lifecycle: `pending → processing → completed` (or `failed` on handler error).
+ * Use `retry()` to reset failed dispatches back to `pending`.
+ *
+ * Create instances via `createDispatchBus()` — do not use `new DispatchBus()` directly
+ * in application code.
+ *
+ * @example
+ * ```typescript
+ * const bus = await createDispatchBus({ db: myDb });
+ *
+ * // In-memory: immediate, fire-and-forget
+ * bus.on('invoice.paid', async (payload) => {
+ *   console.log('Invoice paid:', payload.invoiceId);
+ * });
+ *
+ * // Persistent: processed by 'notifications' agent on next run
+ * await bus.subscribe({ signalType: 'invoice.*', subscriber: 'notifications' });
+ *
+ * // Emit (notifies in-memory handlers immediately, stores persistent dispatch)
+ * await bus.emit('invoice.paid', { invoiceId: 'inv-001' }, { source: 'billing' });
+ *
+ * // Later, in the notifications agent:
+ * await bus.process('notifications', async (payload) => {
+ *   await sendEmail(payload.invoiceId);
+ * });
+ * ```
+ */
+export declare class DispatchBus {
+    private db;
+    private handlers;
+    private initialized;
+    /**
+     * Reserved subscriber name used internally for in-memory `on()` handlers.
+     * Callers may not register persistent subscriptions under this name, nor
+     * assert it as an emit `source`, so they cannot impersonate the in-memory
+     * pseudo-subscriber (S5 #1398).
+     */
+    private static readonly RESERVED_SUBSCRIBER;
+    /** Maximum stored length of a caller-asserted dispatch source label. */
+    private static readonly MAX_SOURCE_LENGTH;
+    /**
+     * Normalize a caller-asserted `source` into untrusted metadata.
+     *
+     * `source` is a declared label, not an authenticated identity, so it must not
+     * be trusted for authorization. This caps its length and **rejects** the
+     * reserved internal sentinel (`_in_memory_`) by throwing — the contract is
+     * that the sentinel is not an accepted source, so a caller cannot quietly
+     * impersonate the in-memory subscriber pseudo-source (S5 #1398). Empty/missing
+     * values default to `'unknown'` (unchanged behavior).
+     *
+     * @throws Error if `source` is the reserved in-memory sentinel.
+     */
+    private static sanitizeSource;
+    /**
+     * Create a new DispatchBus (use createDispatchBus factory instead)
+     */
+    constructor(db: DatabaseInterface);
+    /**
+     * Initialize the dispatch tables
+     */
+    initialize(): Promise<void>;
+    /**
+     * Emits a dispatch message.
+     *
+     * Two things happen atomically (from the caller's perspective):
+     * 1. One or more `Dispatch` rows are inserted with `status: 'pending'` into `_smrt_dispatch`.
+     * 2. All matching in-memory handlers (registered via `on()`) are invoked
+     *    fire-and-forget (errors are caught and logged, not thrown back to the caller).
+     *
+     * Persistent subscriptions registered via `subscribe()` will see this dispatch
+     * the next time `process(subscriber, handler)` is called for their subscriber name.
+     *
+     * **Delivery modes** affect how dispatches are created:
+     * - `compete` subscribers share a single dispatch (`target_subscriber = NULL`).
+     *   First subscriber to `process()` claims it (at-most-once delivery).
+     * - `fanout` subscribers each get their own dispatch copy (`target_subscriber` set
+     *   to the subscriber name), so each processes independently.
+     *
+     * If no subscriptions exist, one dispatch is created for future processing.
+     *
+     * **Security (S5 #1398):**
+     * - `tenant_id` is derived **server-side** from the active tenant context and
+     *   is never read from caller options, so it cannot be spoofed. Subscribers in
+     *   a different tenant cannot see or claim this dispatch (see {@link process}).
+     *   When there is no active tenant context (system/global), `tenant_id` is
+     *   `NULL` and the dispatch is visible to all scopes — preserving pre-tenancy
+     *   behavior.
+     * - `options.source` is **caller-asserted, untrusted metadata** — it is a
+     *   declared label only and must not be relied on as an authenticated emitter
+     *   identity. It is length-capped and the reserved internal sentinel
+     *   (`_in_memory_`) is rejected so a caller cannot impersonate the in-memory
+     *   subscriber pseudo-source.
+     *
+     * @param type - Signal type string, e.g. `'campaign.completed'` or `'invoice.paid'`
+     * @param payload - Any JSON-serializable data to attach to the dispatch
+     * @param options.source - Declared (untrusted) name of the emitting agent/component (default `'unknown'`)
+     * @param options.sourceId - Optional ID of the specific emitting entity
+     * @param options.metadata - Optional additional JSON metadata for the dispatch record
+     * @returns A persisted `Dispatch` instance (the compete dispatch, or the first fanout copy if fanout-only)
+     *
+     * @example
+     * ```typescript
+     * const dispatch = await bus.emit(
+     *   'campaign.completed',
+     *   { campaignId: 'cmp-001', impressions: 10_000 },
+     *   { source: 'suasor', sourceId: agentId },
+     * );
+     * console.log(dispatch.id); // UUID of the created dispatch record
+     * ```
+     *
+     * @see {@link on} for in-memory handlers
+     * @see {@link subscribe} for persistent subscriptions
+     * @see {@link process} to consume pending dispatches
+     */
+    emit(type: string, payload: unknown, options?: DispatchEmitOptions): Promise<Dispatch>;
+    /**
+     * Registers an in-memory handler for a signal type pattern.
+     *
+     * In-memory handlers are called immediately (fire-and-forget) during `emit()`.
+     * They are stored only in memory and lost on process restart — use `subscribe()`
+     * for durable, restart-safe subscriptions.
+     *
+     * Pattern matching supports a single-segment wildcard `*`:
+     * - `'campaign.*'` matches `'campaign.completed'` and `'campaign.failed'`
+     * - `'campaign.*'` does **not** match `'campaign.phase.two'`
+     *
+     * Multiple handlers may be registered for the same pattern — all will be called.
+     *
+     * @param pattern - Signal type pattern, optionally with a trailing `.*` wildcard
+     * @param handler - Async or sync function to call with `(payload, metadata)`
+     *
+     * @example
+     * ```typescript
+     * bus.on('invoice.*', async (payload, metadata) => {
+     *   console.log(`Invoice event from ${metadata.source}:`, payload);
+     * });
+     * ```
+     *
+     * @see {@link off} to remove a handler
+     * @see {@link subscribe} for persistent (restart-safe) subscriptions
+     */
+    on(pattern: string, handler: DispatchHandler): void;
+    /**
+     * Remove an in-memory handler
+     *
+     * @param pattern - Signal type pattern
+     * @param handler - Handler function to remove
+     * @returns True if handler was found and removed
+     */
+    off(pattern: string, handler: DispatchHandler): boolean;
+    /**
+     * Creates or updates a persistent subscription in the database.
+     *
+     * Persistent subscriptions survive process restarts. When `process(subscriber, handler)`
+     * is called later, all pending dispatches matching this subscriber's signal patterns
+     * will be delivered.
+     *
+     * Calling `subscribe()` with the same `signalType`/`subscriber` pair is idempotent
+     * (upsert) — it is safe to call on every agent startup.
+     *
+     * Set `delivery: 'fanout'` to give each subscriber their own dispatch copy.
+     * Default is `'compete'` (at-most-once, first subscriber to process claims it).
+     *
+     * @param options.signalType - Signal type pattern to subscribe to (wildcards supported)
+     * @param options.subscriber - Name that identifies this subscriber (e.g. agent class name)
+     * @param options.handler - Optional method name on the subscriber to call (default `'handleDispatch'`)
+     * @param options.delivery - `'compete'` (default) for at-most-once, `'fanout'` for per-subscriber copies
+     * @param options.enabled - If `false`, subscription is created but disabled (default `true`)
+     *
+     * @example
+     * ```typescript
+     * // Subscribe on agent startup (idempotent)
+     * await bus.subscribe({ signalType: 'campaign.*', subscriber: 'FiscusAgent' });
+     *
+     * // Fan-out: each subscriber gets their own dispatch copy
+     * await bus.subscribe({
+     *   signalType: 'campaign.*',
+     *   subscriber: 'AuditorAgent',
+     *   delivery: 'fanout',
+     * });
+     *
+     * // Later, process matching pending dispatches
+     * await bus.process('FiscusAgent', async (payload, metadata) => { ... });
+     * ```
+     *
+     * @see {@link process} to consume pending dispatches for this subscriber
+     * @see {@link unsubscribe} to remove the subscription
+     * @see {@link on} for non-persistent in-memory handling
+     */
+    subscribe(options: DispatchSubscribeOptions): Promise<void>;
+    /**
+     * Remove a persistent subscription
+     *
+     * @param signalType - Signal type pattern
+     * @param subscriber - Subscriber name
+     */
+    unsubscribe(signalType: string, subscriber: string): Promise<void>;
+    /**
+     * Processes pending dispatches for a named subscriber.
+     *
+     * For each matching `pending` dispatch:
+     * 1. Sets status to `processing`
+     * 2. Calls `handler(payload, metadata)`
+     * 3. On success: sets status to `completed`
+     * 4. On error: sets status to `failed` (stores the error message)
+     *
+     * Uses a wildcard-aware query strategy: subscriptions with `*` patterns fetch
+     * all pending dispatches and filter in memory; exact-match subscriptions use
+     * a direct SQL `IN` query for efficiency.
+     *
+     * @param subscriber - The subscriber name (must match a `subscribe()` call)
+     * @param handler - Function to call for each pending dispatch
+     * @param options.limit - Maximum dispatches to process in one call (default 100)
+     * @param options.signalTypes - Optional filter to process only specific signal types
+     * @returns Number of dispatches successfully processed (excludes failed)
+     *
+     * @example
+     * ```typescript
+     * const count = await bus.process('FiscusAgent', async (payload, metadata) => {
+     *   if (metadata.signalType === 'campaign.completed') {
+     *     await generateInvoice(payload.campaignId);
+     *   }
+     * });
+     * console.log(`Processed ${count} dispatches`);
+     * ```
+     *
+     * @see {@link subscribe} to register the persistent subscription first
+     * @see {@link retry} to reset failed dispatches back to pending
+     */
+    process(subscriber: string, handler: DispatchHandler, options?: DispatchProcessOptions): Promise<number>;
+    /**
+     * Retry failed dispatches
+     *
+     * Resets failed dispatches to pending status so they can be processed again.
+     *
+     * @param options - Retry options
+     * @returns Number of dispatches reset
+     */
+    retry(options?: DispatchRetryOptions): Promise<number>;
+    /**
+     * Clean up old dispatches
+     *
+     * @param options - Cleanup options
+     * @returns Number of dispatches deleted
+     */
+    cleanup(options?: DispatchCleanupOptions): Promise<DispatchCleanupResult>;
+    /**
+     * Lists dispatches, scoped to the active tenant context (S5 #1398).
+     *
+     * The tenant scope is derived **server-side** from the active context and
+     * **overrides any caller-supplied scope** — callers cannot select another
+     * tenant or widen visibility to all tenants. Scoping rules:
+     *
+     * - tenancy off → no tenant filter (pre-tenancy behavior).
+     * - active tenant T → that tenant's dispatches plus global (NULL) dispatches.
+     * - tenancy on but no active tenant → global (NULL) dispatches only
+     *   (fail-closed; never all tenants).
+     *
+     * @param options - Non-tenant list filters (status/type/source/etc.). Any
+     *   `tenantScope` field is ignored and replaced with the server-derived one.
+     */
+    list(options?: DispatchListOptions): Promise<Dispatch[]>;
+    /**
+     * Gets a dispatch by ID, enforcing the active tenant scope (S5 #1398).
+     *
+     * Applies the same server-derived tenant predicate as {@link list}: a
+     * subscriber in tenant A cannot fetch tenant B's dispatch by id, and when
+     * tenancy is on with no active tenant only global (NULL) dispatches are
+     * returned. Returns `null` when the dispatch exists but is out of scope.
+     */
+    get(id: string): Promise<Dispatch | null>;
+    /**
+     * List all subscriptions
+     */
+    listSubscriptions(subscriber?: string): Promise<DispatchSubscription[]>;
+    /**
+     * Notify in-memory handlers (fire-and-forget)
+     */
+    private notifyHandlers;
+}
+/**
+ * Create a DispatchBus instance
+ *
+ * @param options - Bus configuration
+ * @returns Initialized DispatchBus
+ */
+export declare function createDispatchBus(options?: DispatchBusOptions): Promise<DispatchBus>;
+//# sourceMappingURL=bus.d.ts.map

package/dist/dispatch/bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus.d.ts","sourceRoot":"","sources":["../../src/dispatch/bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAY5D,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAKxE,OAAO,KAAK,EACV,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,mBAAmB,EAEnB,sBAAsB,EACtB,oBAAoB,EACpB,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAapB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,EAAE,CAAoB;IAC9B,OAAO,CAAC,QAAQ,CAA+C;IAC/D,OAAO,CAAC,WAAW,CAAkB;IAErC;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAiB;IAE5D,wEAAwE;IACxE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAO;IAEhD;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAa7B;;OAEG;gBACS,EAAE,EAAE,iBAAiB;IAIjC;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAkCjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoDG;IACG,IAAI,CACR,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,QAAQ,CAAC;IA0EpB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI;IAenD;;;;;;OAMG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO;IAcvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACG,SAAS,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmCjE;;;;;OAKG;IACG,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,OAAO,CACX,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,eAAe,EACxB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,MAAM,CAAC;IAyIlB;;;;;;;OAOG;IACG,KAAK,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,MAAM,CAAC;IAqBhE;;;;;OAKG;IACG,OAAO,CACX,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,qBAAqB,CAAC;IAYjC;;;;;;;;;;;;;;OAcG;IACG,IAAI,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAUlE;;;;;;;OAOG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAS/C;;OAEG;IACG,iBAAiB,CACrB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAkBlC;;OAEG;IACH,OAAO,CAAC,cAAc;CAqCvB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,WAAW,CAAC,CA6BtB"}