@digimuza/saas-core 0.0.2

package/dist/events/index.js

@@ -0,0 +1,58 @@
+/**
+ * Public events surface: `@digimuza/saas-core/events`. Server-only.
+ *
+ * One durable record of everything that happens, typed at compile time and
+ * validated at runtime. Events are the substrate the later phases build on:
+ * realtime delivery, RxJS streams, notifications, audit logs, outgoing webhooks
+ * and durable jobs all read from here rather than inventing their own channel.
+ *
+ * Applications declare their own events and merge them with the core catalogue:
+ *
+ * ```ts
+ * import { z } from "zod";
+ * import {
+ *   coreEvents, createEventsService, defineEvents, mergeEventRegistries,
+ * } from "@digimuza/saas-core/events";
+ * import { getDatabase } from "@digimuza/saas-core/db";
+ *
+ * const registry = mergeEventRegistries(
+ *   coreEvents,
+ *   defineEvents({ "project.created": z.object({ projectId: z.uuid() }) }),
+ * );
+ *
+ * export const events = createEventsService({ db: getDatabase(), registry });
+ *
+ * await events.publish({
+ *   type: "project.created",   // autocompleted
+ *   workspaceId: context.workspaceId,
+ *   actorId: user.id,
+ *   data: { projectId },       // narrowed to this event's schema
+ * });
+ * ```
+ *
+ * Subscribers registered with `on()` run **in process** and are not durable: a
+ * crash between the commit and the handler loses the reaction, not the event.
+ * That is deliberate — durable reactions belong in Trigger.dev, reading the
+ * persisted row. Never keep state that must survive a restart in a handler.
+ */
+import { getDatabase } from "../db/client.js";
+import { coreEvents } from "./core-events.js";
+import { createEventsService } from "./service.js";
+export { coreEvents } from "./core-events.js";
+export { defineEvents, mergeEventRegistries, } from "./registry.js";
+export { createEventsService, } from "./service.js";
+/**
+ * Default service over the core catalogue only.
+ *
+ * An application with its own events should build its own service from a merged
+ * registry — this one cannot publish types it does not know about. It exists so
+ * the core's own services have somewhere to emit without every consumer having
+ * to wire a registry first.
+ */
+export const events = createEventsService({
+    get db() {
+        return getDatabase();
+    },
+    registry: coreEvents,
+});
+//# sourceMappingURL=index.js.map

package/dist/events/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAyB,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,mBAAmB,EAAsB,MAAM,cAAc,CAAC;AAEvE,OAAO,EAAE,UAAU,EAAyB,MAAM,kBAAkB,CAAC;AACrE,OAAO,EACL,YAAY,EACZ,oBAAoB,GAWrB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,GAMpB,MAAM,cAAc,CAAC;AAEtB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,MAAM,GAAoC,mBAAmB,CAAC;IACzE,IAAI,EAAE;QACJ,OAAO,WAAW,EAAE,CAAC;IACvB,CAAC;IACD,QAAQ,EAAE,UAAU;CACrB,CAAC,CAAC"}

package/dist/events/publisher.d.ts

@@ -0,0 +1,46 @@
+import type { CoreDatabase } from "../db/types.ts";
+import type { CoreEventSchemas } from "./core-events.ts";
+import type { PublishInput } from "./registry.ts";
+import type { EventsService } from "./service.ts";
+/**
+ * The slice of the events service that core services need.
+ *
+ * Narrowed to publishing and dispatch so that `workspaces`, `authorization` and
+ * `billing` do not depend on the full generic service — and so an application
+ * can pass a service built from a *merged* registry, which is a supertype of the
+ * core catalogue, without any of them knowing about the extra event types.
+ */
+export type CoreEventPublisher = Pick<EventsService<CoreEventSchemas>, "record" | "dispatch">;
+/**
+ * Collects events written inside a transaction, to be fanned out after it
+ * commits.
+ *
+ * This is the transactional outbox pattern. Writing the event in the same
+ * transaction as the state change means the two can never disagree: no state
+ * change without its event, and no event for a change that rolled back.
+ * Dispatching is deferred because in-process handlers would otherwise observe
+ * uncommitted work.
+ */
+export declare class EventOutbox {
+    private readonly publisher;
+    private readonly pending;
+    constructor(publisher: CoreEventPublisher | undefined);
+    /** True when no publisher is configured, so callers can skip the work. */
+    get enabled(): boolean;
+    /**
+     * Record an event inside `tx`. No-op when events are not configured.
+     *
+     * Pass the transaction the state change is using, not the pooled handle — the
+     * whole point is that the two commit together.
+     */
+    record(input: PublishInput<CoreEventSchemas>, tx: CoreDatabase): Promise<void>;
+    /**
+     * Fan out everything recorded. Call only after the transaction has committed.
+     *
+     * Never throws: dispatch failures are reported through the events service's
+     * own error sink, because the state change and its event are already durable
+     * and a subscriber problem must not surface as a failed operation.
+     */
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=publisher.d.ts.map

package/dist/events/publisher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publisher.d.ts","sourceRoot":"","sources":["../../src/events/publisher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAa,MAAM,eAAe,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,aAAa,CAAC,gBAAgB,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC,CAAC;AAE9F;;;;;;;;;GASG;AACH,qBAAa,WAAW;IAGV,OAAO,CAAC,QAAQ,CAAC,SAAS;IAFtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAE7D,YAA6B,SAAS,EAAE,kBAAkB,GAAG,SAAS,EAAI;IAE1E,0EAA0E;IAC1E,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,YAAY,CAAC,gBAAgB,CAAC,EAAE,EAAE,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAWnF;IAED;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAS3B;CACF"}

package/dist/events/publisher.js

@@ -0,0 +1,54 @@
+/**
+ * Collects events written inside a transaction, to be fanned out after it
+ * commits.
+ *
+ * This is the transactional outbox pattern. Writing the event in the same
+ * transaction as the state change means the two can never disagree: no state
+ * change without its event, and no event for a change that rolled back.
+ * Dispatching is deferred because in-process handlers would otherwise observe
+ * uncommitted work.
+ */
+export class EventOutbox {
+    publisher;
+    pending = [];
+    constructor(publisher) {
+        this.publisher = publisher;
+    }
+    /** True when no publisher is configured, so callers can skip the work. */
+    get enabled() {
+        return this.publisher !== undefined;
+    }
+    /**
+     * Record an event inside `tx`. No-op when events are not configured.
+     *
+     * Pass the transaction the state change is using, not the pooled handle — the
+     * whole point is that the two commit together.
+     */
+    async record(input, tx) {
+        if (this.publisher === undefined) {
+            return;
+        }
+        const { event, created } = await this.publisher.record(input, tx);
+        // A deduplicated event was already dispatched when first recorded.
+        if (created) {
+            this.pending.push(event);
+        }
+    }
+    /**
+     * Fan out everything recorded. Call only after the transaction has committed.
+     *
+     * Never throws: dispatch failures are reported through the events service's
+     * own error sink, because the state change and its event are already durable
+     * and a subscriber problem must not surface as a failed operation.
+     */
+    async flush() {
+        if (this.publisher === undefined || this.pending.length === 0) {
+            return;
+        }
+        const events = this.pending.splice(0, this.pending.length);
+        for (const event of events) {
+            await this.publisher.dispatch(event);
+        }
+    }
+}
+//# sourceMappingURL=publisher.js.map

package/dist/events/publisher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publisher.js","sourceRoot":"","sources":["../../src/events/publisher.ts"],"names":[],"mappings":"AAeA;;;;;;;;;GASG;AACH,MAAM,OAAO,WAAW;IAGO,SAAS;IAFrB,OAAO,GAAkC,EAAE,CAAC;IAE7D,YAA6B,SAAyC;yBAAzC,SAAS;IAAmC,CAAC;IAE1E,0EAA0E;IAC1E,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC;IACtC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CAAC,KAAqC,EAAE,EAAgB;QAClE,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YACjC,OAAO;QACT,CAAC;QAED,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAElE,mEAAmE;QACnE,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9D,OAAO;QACT,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC3D,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;CACF"}

package/dist/events/registry.d.ts

@@ -0,0 +1,87 @@
+import type { z } from "zod";
+/**
+ * A typed event catalogue.
+ *
+ * Each event type is paired with a Zod schema, which does double duty: `z.infer`
+ * gives the compile-time payload type, and the same schema validates at runtime
+ * before anything is written. A generic `Record<string, unknown>` payload would
+ * give neither, and a hand-written TypeScript interface would give only the
+ * first — leaving the database to accept whatever a caller happened to pass.
+ */
+export type EventSchemaMap = Record<string, z.ZodType>;
+export interface EventRegistry<S extends EventSchemaMap = EventSchemaMap> {
+    readonly schemas: S;
+}
+/**
+ * Declare a set of event types.
+ *
+ * ```ts
+ * export const appEvents = defineEvents({
+ *   "project.created": z.object({ projectId: z.uuid() }),
+ *   "project.deleted": z.object({ projectId: z.uuid() }),
+ * });
+ * ```
+ *
+ * The `const` type parameter preserves the literal keys, which is what makes
+ * `publish({ type: "project.created", ... })` autocomplete and narrow `data`.
+ */
+export declare function defineEvents<const S extends EventSchemaMap>(schemas: S): EventRegistry<S>;
+/**
+ * Combine the core catalogue with an application's own.
+ *
+ * Duplicate keys throw rather than silently overriding. An application that
+ * redefined `workspace.member.created` with a different payload would make every
+ * core consumer of that event wrong, and the failure would surface far from the
+ * cause.
+ */
+export declare function mergeEventRegistries<A extends EventSchemaMap, B extends EventSchemaMap>(first: EventRegistry<A>, second: EventRegistry<B>): EventRegistry<A & B>;
+/** Every event type in a registry, as a string literal union. */
+export type EventTypeOf<S extends EventSchemaMap> = keyof S & string;
+/** The validated payload for one event type. */
+export type EventDataOf<S extends EventSchemaMap, K extends EventTypeOf<S>> = z.output<S[K]>;
+/**
+ * What a caller passes to `publish`.
+ *
+ * A union of one variant per event type rather than `{ type: string; data:
+ * unknown }`, so `data` is checked against the schema for the `type` given in
+ * the same object literal.
+ */
+export type PublishInput<S extends EventSchemaMap> = {
+    [K in EventTypeOf<S>]: {
+        readonly type: K;
+        readonly data: z.input<S[K]>;
+        /**
+         * Tenant the event belongs to.
+         *
+         * Must originate from a verified {@link WorkspaceContext}; prefer
+         * `events.scoped(context)`, which binds it for you.
+         */
+        readonly workspaceId?: string | null;
+        /** The acting user. Resolve from the session, never from a request body. */
+        readonly actorId?: string | null;
+        /** Deduplication key, scoped to this event type. */
+        readonly idempotencyKey?: string;
+        /** When it happened, if that differs from now. */
+        readonly occurredAt?: Date;
+    };
+}[EventTypeOf<S>];
+/** A persisted event, narrowed by `type`. */
+export type SaasEvent<S extends EventSchemaMap = EventSchemaMap> = {
+    [K in EventTypeOf<S>]: {
+        readonly id: string;
+        readonly type: K;
+        readonly data: z.output<S[K]>;
+        readonly workspaceId: string | null;
+        readonly actorId: string | null;
+        readonly occurredAt: Date;
+    };
+}[EventTypeOf<S>];
+/** A single event type's variant of {@link SaasEvent}. */
+export type SaasEventOf<S extends EventSchemaMap, K extends EventTypeOf<S>> = Extract<SaasEvent<S>, {
+    type: K;
+}>;
+export type EventHandler<S extends EventSchemaMap, K extends EventTypeOf<S>> = (event: SaasEventOf<S, K>) => void | Promise<void>;
+export type AnyEventHandler<S extends EventSchemaMap> = (event: SaasEvent<S>) => void | Promise<void>;
+/** Removes a subscription. Every `on`/`onAny` call returns one. */
+export type Unsubscribe = () => void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/events/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/events/registry.ts"],"names":[],"mappings":"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"}

package/dist/events/registry.js

@@ -0,0 +1,34 @@
+import { InvalidInputError } from "../errors.js";
+/**
+ * Declare a set of event types.
+ *
+ * ```ts
+ * export const appEvents = defineEvents({
+ *   "project.created": z.object({ projectId: z.uuid() }),
+ *   "project.deleted": z.object({ projectId: z.uuid() }),
+ * });
+ * ```
+ *
+ * The `const` type parameter preserves the literal keys, which is what makes
+ * `publish({ type: "project.created", ... })` autocomplete and narrow `data`.
+ */
+export function defineEvents(schemas) {
+    return { schemas };
+}
+/**
+ * Combine the core catalogue with an application's own.
+ *
+ * Duplicate keys throw rather than silently overriding. An application that
+ * redefined `workspace.member.created` with a different payload would make every
+ * core consumer of that event wrong, and the failure would surface far from the
+ * cause.
+ */
+export function mergeEventRegistries(first, second) {
+    const collisions = Object.keys(second.schemas).filter((key) => key in first.schemas);
+    if (collisions.length > 0) {
+        throw new InvalidInputError(`Event types already defined: ${collisions.join(", ")}. ` +
+            `Rename the application's events rather than redefining core ones.`);
+    }
+    return { schemas: { ...first.schemas, ...second.schemas } };
+}
+//# sourceMappingURL=registry.js.map

package/dist/events/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/events/registry.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAiBjD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAiC,OAAU;IACrE,OAAO,EAAE,OAAO,EAAE,CAAC;AACrB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAuB,EACvB,MAAwB;IAExB,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;IAErF,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,iBAAiB,CACzB,gCAAgC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YACvD,mEAAmE,CACtE,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;AAC9D,CAAC"}

package/dist/events/service.d.ts

@@ -0,0 +1,78 @@
+import { isUniqueViolation } from "../db/errors.ts";
+import type { CoreDatabase } from "../db/types.ts";
+import type { WorkspaceContext } from "../workspaces/context.ts";
+import type { AnyEventHandler, EventHandler, EventRegistry, EventSchemaMap, EventTypeOf, PublishInput, SaasEvent, Unsubscribe } from "./registry.ts";
+/** Outcome of persisting an event. */
+export interface RecordResult<S extends EventSchemaMap> {
+    readonly event: SaasEvent<S>;
+    /**
+     * False when an event with the same type and idempotency key already existed.
+     *
+     * Callers must not dispatch a non-created event: it was already fanned out
+     * when it was first recorded, and doing it again would make every handler run
+     * twice for one real occurrence.
+     */
+    readonly created: boolean;
+}
+export interface ListEventsOptions {
+    readonly types?: readonly string[];
+    readonly limit?: number;
+    /** Return events strictly older than this, for keyset pagination. */
+    readonly before?: Date;
+    readonly actorId?: string;
+}
+/** A publisher with the workspace already bound. */
+export interface ScopedPublisher<S extends EventSchemaMap> {
+    publish(input: Omit<PublishInput<S>, "workspaceId"> & {
+        readonly actorId?: string | null;
+    }): Promise<SaasEvent<S>>;
+    record(input: Omit<PublishInput<S>, "workspaceId"> & {
+        readonly actorId?: string | null;
+    }, tx?: CoreDatabase): Promise<RecordResult<S>>;
+}
+export interface EventsService<S extends EventSchemaMap> {
+    /**
+     * Validate, persist and fan out an event.
+     *
+     * The row is committed before handlers run, so an event is never lost because
+     * a subscriber failed. A deduplicated event is returned without being
+     * dispatched again.
+     */
+    publish(input: PublishInput<S>): Promise<SaasEvent<S>>;
+    /**
+     * Validate and persist without dispatching.
+     *
+     * Pass the transaction your state change is using, so the event and the change
+     * commit together — no state change without its event, and no event for a
+     * change that rolled back. Dispatch after the commit, and only when `created`
+     * is true.
+     */
+    record(input: PublishInput<S>, tx?: CoreDatabase): Promise<RecordResult<S>>;
+    /** Fan out an already-persisted event. Use after committing a transaction. */
+    dispatch(event: SaasEvent<S>): Promise<void>;
+    /** Subscribe to one event type. */
+    on<K extends EventTypeOf<S>>(type: K, handler: EventHandler<S, K>): Unsubscribe;
+    /** Subscribe to every event. */
+    onAny(handler: AnyEventHandler<S>): Unsubscribe;
+    /** Recent events for a workspace, newest first. */
+    list(context: WorkspaceContext, options?: ListEventsOptions): Promise<SaasEvent<S>[]>;
+    /** Bind a verified workspace so callers cannot pass a different one. */
+    scoped(context: WorkspaceContext): ScopedPublisher<S>;
+}
+export interface EventsServiceDeps<S extends EventSchemaMap> {
+    readonly db: CoreDatabase;
+    readonly registry: EventRegistry<S>;
+    /**
+     * Where subscriber failures go.
+     *
+     * Handlers must not be able to fail a publish: the event has happened and is
+     * committed, so a broken subscriber is a separate operational problem. Without
+     * a sink those failures would vanish, so one is provided by default that logs.
+     */
+    readonly onHandlerError?: (error: unknown, event: SaasEvent<S>) => void;
+    readonly now?: () => Date;
+}
+export declare function createEventsService<S extends EventSchemaMap>(deps: EventsServiceDeps<S>): EventsService<S>;
+/** Re-exported so callers can narrow a caught publish failure. */
+export { isUniqueViolation };
+//# sourceMappingURL=service.d.ts.map

package/dist/events/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/events/service.ts"],"names":[],"mappings":"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"}

package/dist/events/service.js

@@ -0,0 +1,182 @@
+import { and, desc, eq, inArray, isNotNull, lt } from "drizzle-orm";
+import { InvalidInputError } from "../errors.js";
+import { isUniqueViolation } from "../db/errors.js";
+import { getDefaultLogger } from "../logger/default.js";
+import { events as eventsTable } from "../db/schema/index.js";
+const DEFAULT_LIST_LIMIT = 50;
+const MAX_LIST_LIMIT = 500;
+export function createEventsService(deps) {
+    const now = deps.now ?? (() => new Date());
+    const typed = new Map();
+    const wildcard = new Set();
+    const reportHandlerError = deps.onHandlerError ??
+        ((error, event) => {
+            getDefaultLogger().error("event handler failed", {
+                eventType: event.type,
+                eventId: event.id,
+                workspaceId: event.workspaceId,
+                error,
+            });
+        });
+    function validate(input) {
+        const schema = deps.registry.schemas[input.type];
+        if (schema === undefined) {
+            /**
+             * Reachable only from untyped JavaScript, but worth catching: an unknown
+             * type would otherwise be persisted with an unvalidated payload and reach
+             * consumers that cannot interpret it.
+             */
+            throw new InvalidInputError(`Unknown event type "${String(input.type)}".`);
+        }
+        const parsed = schema.safeParse(input.data);
+        if (!parsed.success) {
+            const problems = parsed.error.issues
+                .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
+                .join("; ");
+            throw new InvalidInputError(`Invalid payload for event "${input.type}": ${problems}`);
+        }
+        return parsed.data;
+    }
+    const service = {
+        async publish(input) {
+            const { event, created } = await service.record(input);
+            /**
+             * Already recorded means already dispatched. Fanning out again would make
+             * every handler run twice for a single real occurrence.
+             */
+            if (created) {
+                await service.dispatch(event);
+            }
+            return event;
+        },
+        async record(input, tx) {
+            const data = validate(input);
+            const db = tx ?? deps.db;
+            const occurredAt = input.occurredAt ?? now();
+            const inserted = await db
+                .insert(eventsTable)
+                .values({
+                type: input.type,
+                workspaceId: input.workspaceId ?? null,
+                actorUserId: input.actorId ?? null,
+                data: data,
+                occurredAt,
+                idempotencyKey: input.idempotencyKey ?? null,
+            })
+                /**
+                 * A retried operation reuses its idempotency key. Returning nothing on
+                 * conflict lets us fetch and return the original event, so the caller
+                 * sees the same identity either way and no duplicate is dispatched.
+                 *
+                 * The `where` predicate is required, not decorative: `events_idempotency_idx` is
+                 * a *partial* unique index, and PostgreSQL refuses to infer a partial
+                 * index as the conflict arbiter unless the predicate matches. Without it
+                 * every insert fails with "no unique or exclusion constraint matching
+                 * the ON CONFLICT specification".
+                 */
+                .onConflictDoNothing({
+                target: [eventsTable.type, eventsTable.idempotencyKey],
+                where: isNotNull(eventsTable.idempotencyKey),
+            })
+                .returning();
+            let row = inserted[0];
+            if (row === undefined) {
+                if (input.idempotencyKey === undefined) {
+                    // No key means no conflict was possible; something else went wrong.
+                    throw new Error(`Failed to record event "${input.type}".`);
+                }
+                const existing = await db
+                    .select()
+                    .from(eventsTable)
+                    .where(and(eq(eventsTable.type, input.type), eq(eventsTable.idempotencyKey, input.idempotencyKey)))
+                    .limit(1);
+                row = existing[0];
+                if (row === undefined) {
+                    throw new Error(`Failed to record event "${input.type}".`);
+                }
+                return { event: toEvent(row), created: false };
+            }
+            return { event: toEvent(row), created: true };
+        },
+        async dispatch(event) {
+            const handlers = [...(typed.get(event.type) ?? []), ...wildcard];
+            if (handlers.length === 0) {
+                return;
+            }
+            /**
+             * Run concurrently and settle every handler. Sequential dispatch would let
+             * a slow subscriber delay the rest, and a rejection would skip those after
+             * it — so each failure is reported and the others still run.
+             */
+            const results = await Promise.allSettled(handlers.map(async (handler) => handler(event)));
+            for (const result of results) {
+                if (result.status === "rejected") {
+                    reportHandlerError(result.reason, event);
+                }
+            }
+        },
+        on(type, handler) {
+            let handlers = typed.get(type);
+            if (handlers === undefined) {
+                handlers = new Set();
+                typed.set(type, handlers);
+            }
+            const erased = handler;
+            handlers.add(erased);
+            return () => {
+                handlers.delete(erased);
+            };
+        },
+        onAny(handler) {
+            wildcard.add(handler);
+            return () => {
+                wildcard.delete(handler);
+            };
+        },
+        async list(context, options = {}) {
+            const limit = Math.min(options.limit ?? DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT);
+            const filters = [
+                // Always scoped to the verified workspace; an event feed is tenant data.
+                eq(eventsTable.workspaceId, context.workspaceId),
+            ];
+            if (options.types !== undefined && options.types.length > 0) {
+                filters.push(inArray(eventsTable.type, [...options.types]));
+            }
+            if (options.before !== undefined) {
+                filters.push(lt(eventsTable.occurredAt, options.before));
+            }
+            if (options.actorId !== undefined) {
+                filters.push(eq(eventsTable.actorUserId, options.actorId));
+            }
+            const rows = await deps.db
+                .select()
+                .from(eventsTable)
+                .where(and(...filters))
+                // Tie-break on id so keyset pagination cannot loop on equal timestamps.
+                .orderBy(desc(eventsTable.occurredAt), desc(eventsTable.id))
+                .limit(limit);
+            return rows.map((row) => toEvent(row));
+        },
+        scoped(context) {
+            const bind = (input) => ({ ...input, workspaceId: context.workspaceId });
+            return {
+                publish: (input) => service.publish(bind(input)),
+                record: (input, tx) => service.record(bind(input), tx),
+            };
+        },
+    };
+    return service;
+}
+function toEvent(row) {
+    return {
+        id: row.id,
+        type: row.type,
+        data: row.data,
+        workspaceId: row.workspaceId,
+        actorId: row.actorUserId,
+        occurredAt: row.occurredAt,
+    };
+}
+/** Re-exported so callers can narrow a caught publish failure. */
+export { isUniqueViolation };
+//# sourceMappingURL=service.js.map

package/dist/events/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/events/service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAEpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,MAAM,IAAI,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAgG9D,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAC9B,MAAM,cAAc,GAAG,GAAG,CAAC;AAE3B,MAAM,UAAU,mBAAmB,CACjC,IAA0B;IAE1B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IAE3C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAmC,CAAC;IACzD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAsB,CAAC;IAE/C,MAAM,kBAAkB,GACtB,IAAI,CAAC,cAAc;QACnB,CAAC,CAAC,KAAc,EAAE,KAAmB,EAAE,EAAE;YACvC,gBAAgB,EAAE,CAAC,KAAK,CAAC,sBAAsB,EAAE;gBAC/C,SAAS,EAAE,KAAK,CAAC,IAAI;gBACrB,OAAO,EAAE,KAAK,CAAC,EAAE;gBACjB,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,KAAK;aACN,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IAEL,SAAS,QAAQ,CAAC,KAAsB;QACtC,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAEjD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB;;;;eAIG;YACH,MAAM,IAAI,iBAAiB,CAAC,uBAAuB,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7E,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM;iBACjC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;iBACvE,IAAI,CAAC,IAAI,CAAC,CAAC;YACd,MAAM,IAAI,iBAAiB,CAAC,8BAA8B,KAAK,CAAC,IAAI,MAAM,QAAQ,EAAE,CAAC,CAAC;QACxF,CAAC;QAED,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;IAED,MAAM,OAAO,GAAqB;QAChC,KAAK,CAAC,OAAO,CAAC,KAAK;YACjB,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAEvD;;;eAGG;YACH,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YAChC,CAAC;YAED,OAAO,KAAK,CAAC;QACf,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE;YACpB,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;YAC7B,MAAM,EAAE,GAAG,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;YACzB,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,IAAI,GAAG,EAAE,CAAC;YAE7C,MAAM,QAAQ,GAAG,MAAM,EAAE;iBACtB,MAAM,CAAC,WAAW,CAAC;iBACnB,MAAM,CAAC;gBACN,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,IAAI;gBACtC,WAAW,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;gBAClC,IAAI,EAAE,IAAa;gBACnB,UAAU;gBACV,cAAc,EAAE,KAAK,CAAC,cAAc,IAAI,IAAI;aAC7C,CAAC;gBACF;;;;;;;;;;mBAUG;iBACF,mBAAmB,CAAC;gBACnB,MAAM,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,WAAW,CAAC,cAAc,CAAC;gBACtD,KAAK,EAAE,SAAS,CAAC,WAAW,CAAC,cAAc,CAAC;aAC7C,CAAC;iBACD,SAAS,EAAE,CAAC;YAEf,IAAI,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;YAEtB,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;gBACtB,IAAI,KAAK,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;oBACvC,oEAAoE;oBACpE,MAAM,IAAI,KAAK,CAAC,2BAA2B,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC;gBAC7D,CAAC;gBAED,MAAM,QAAQ,GAAG,MAAM,EAAE;qBACtB,MAAM,EAAE;qBACR,IAAI,CAAC,WAAW,CAAC;qBACjB,KAAK,CACJ,GAAG,CACD,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,EAChC,EAAE,CAAC,WAAW,CAAC,cAAc,EAAE,KAAK,CAAC,cAAc,CAAC,CACrD,CACF;qBACA,KAAK,CAAC,CAAC,CAAC,CAAC;gBAEZ,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;gBAClB,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;oBACtB,MAAM,IAAI,KAAK,CAAC,2BAA2B,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC;gBAC7D,CAAC;gBAED,OAAO,EAAE,KAAK,EAAE,OAAO,CAAI,GAAG,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;YACpD,CAAC;YAED,OAAO,EAAE,KAAK,EAAE,OAAO,CAAI,GAAG,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACnD,CAAC;QAED,KAAK,CAAC,QAAQ,CAAC,KAAK;YAClB,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,QAAQ,CAAC,CAAC;YACjE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC1B,OAAO;YACT,CAAC;YAED;;;;eAIG;YACH,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CACtC,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAChD,CAAC;YAEF,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;oBACjC,kBAAkB,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;gBAC3C,CAAC;YACH,CAAC;QACH,CAAC;QAED,EAAE,CAAC,IAAI,EAAE,OAAO;YACd,IAAI,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC/B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,QAAQ,GAAG,IAAI,GAAG,EAAE,CAAC;gBACrB,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YAC5B,CAAC;YAED,MAAM,MAAM,GAAG,OAAwC,CAAC;YACxD,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAErB,OAAO,GAAG,EAAE;gBACV,QAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC3B,CAAC,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,OAAO;YACX,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACtB,OAAO,GAAG,EAAE;gBACV,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAC3B,CAAC,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,EAAE;YAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,kBAAkB,EAAE,cAAc,CAAC,CAAC;YAE5E,MAAM,OAAO,GAAG;gBACd,yEAAyE;gBACzE,EAAE,CAAC,WAAW,CAAC,WAAW,EAAE,OAAO,CAAC,WAAW,CAAC;aACjD,CAAC;YAEF,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC5D,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAC9D,CAAC;YACD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBACjC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;YAC3D,CAAC;YACD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;gBAClC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,WAAW,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;YAC7D,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,EAAE;iBACvB,MAAM,EAAE;iBACR,IAAI,CAAC,WAAW,CAAC;iBACjB,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC;gBACvB,wEAAwE;iBACvE,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;iBAC3D,KAAK,CAAC,KAAK,CAAC,CAAC;YAEhB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAI,GAAG,CAAC,CAAC,CAAC;QAC5C,CAAC;QAED,MAAM,CAAC,OAAO;YACZ,MAAM,IAAI,GAAG,CAAC,KAAc,EAAmB,EAAE,CAC/C,CAAC,EAAE,GAAI,KAAgB,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAoB,CAAC;YAElF,OAAO;gBACL,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBAChD,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;aACvD,CAAC;QACJ,CAAC;KACF,CAAC;IAEF,OAAO,OAAO,CAAC;AACjB,CAAC;AAWD,SAAS,OAAO,CAA2B,GAAkB;IAC3D,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,OAAO,EAAE,GAAG,CAAC,WAAW;QACxB,UAAU,EAAE,GAAG,CAAC,UAAU;KACX,CAAC;AACpB,CAAC;AAED,kEAAkE;AAClE,OAAO,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/features/bucket.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Deterministic bucketing for percentage rollouts.
+ *
+ * A flag that flickered between requests would be worse than no flag — a user
+ * would see the new editor, reload, and lose their work. So the bucket is a pure
+ * function of the flag key and the subject: stable across requests, processes and
+ * deploys, with no state to store.
+ *
+ * Salted with the key so a subject in the first 10% of one flag is not
+ * automatically in the first 10% of every other — otherwise the same unlucky
+ * cohort would receive every experiment.
+ */
+export declare function bucketOf(key: string, subjectId: string): number;
+/**
+ * Whether a subject falls inside a rollout.
+ *
+ * With no subject there is nothing stable to hash, so anything short of 100 is
+ * off: guessing would make the flag flicker, which is the one behaviour worth
+ * ruling out.
+ */
+export declare function isInRollout(key: string, percentage: number, subjectId: string | undefined): boolean;
+//# sourceMappingURL=bucket.d.ts.map

package/dist/features/bucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket.d.ts","sourceRoot":"","sources":["../../src/features/bucket.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAS/D;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,OAAO,CAYT"}

package/dist/features/bucket.js

@@ -0,0 +1,42 @@
+import { createHash } from "node:crypto";
+/**
+ * Deterministic bucketing for percentage rollouts.
+ *
+ * A flag that flickered between requests would be worse than no flag — a user
+ * would see the new editor, reload, and lose their work. So the bucket is a pure
+ * function of the flag key and the subject: stable across requests, processes and
+ * deploys, with no state to store.
+ *
+ * Salted with the key so a subject in the first 10% of one flag is not
+ * automatically in the first 10% of every other — otherwise the same unlucky
+ * cohort would receive every experiment.
+ */
+export function bucketOf(key, subjectId) {
+    const digest = createHash("sha256").update(`${key}:${subjectId}`).digest();
+    /**
+     * 32 bits mapped onto 0-99. Modulo bias over 100 buckets from a 2^32 range is
+     * about one part in forty million — irrelevant next to the sample sizes any
+     * rollout actually involves.
+     */
+    return digest.readUInt32BE(0) % 100;
+}
+/**
+ * Whether a subject falls inside a rollout.
+ *
+ * With no subject there is nothing stable to hash, so anything short of 100 is
+ * off: guessing would make the flag flicker, which is the one behaviour worth
+ * ruling out.
+ */
+export function isInRollout(key, percentage, subjectId) {
+    if (percentage >= 100) {
+        return true;
+    }
+    if (percentage <= 0) {
+        return false;
+    }
+    if (subjectId === undefined) {
+        return false;
+    }
+    return bucketOf(key, subjectId) < percentage;
+}
+//# sourceMappingURL=bucket.js.map