@objectstack/service-messaging 7.4.0

package/dist/index.cjs

@@ -0,0 +1,1826 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_LOCALE: () => DEFAULT_LOCALE,
+  DEFAULT_RETENTION_TARGETS: () => DEFAULT_RETENTION_TARGETS,
+  DELIVERY_OBJECT: () => DELIVERY_OBJECT,
+  EMAIL_USER_OBJECT: () => USER_OBJECT2,
+  INBOX_OBJECT: () => INBOX_OBJECT,
+  InboxMessage: () => InboxMessage,
+  MEMBER_OBJECT: () => MEMBER_OBJECT,
+  MemoryNotificationOutbox: () => MemoryNotificationOutbox,
+  MessagingService: () => MessagingService,
+  MessagingServicePlugin: () => MessagingServicePlugin,
+  NOTIFICATION_EVENT_OBJECT: () => NOTIFICATION_EVENT_OBJECT,
+  NotificationDelivery: () => NotificationDelivery,
+  NotificationDispatcher: () => NotificationDispatcher,
+  NotificationPreference: () => NotificationPreference,
+  NotificationReceipt: () => NotificationReceipt,
+  NotificationRetention: () => NotificationRetention,
+  NotificationSubscription: () => NotificationSubscription,
+  NotificationTemplate: () => NotificationTemplate,
+  NotificationTemplateStore: () => NotificationTemplateStore,
+  PREFERENCE_OBJECT: () => PREFERENCE_OBJECT,
+  PreferenceResolver: () => PreferenceResolver,
+  RECEIPT_OBJECT: () => RECEIPT_OBJECT,
+  RecipientResolver: () => RecipientResolver,
+  SqlNotificationOutbox: () => SqlNotificationOutbox,
+  TEAM_MEMBER_OBJECT: () => TEAM_MEMBER_OBJECT,
+  TEMPLATE_OBJECT: () => TEMPLATE_OBJECT,
+  USER_OBJECT: () => USER_OBJECT,
+  classifyDeliveryAttempt: () => classifyDeliveryAttempt,
+  createEmailChannel: () => createEmailChannel,
+  createInboxChannel: () => createInboxChannel,
+  hashPartition: () => hashPartition,
+  interpolate: () => interpolate,
+  nextRetryDelayMs: () => nextRetryDelayMs,
+  quietHoursDeferral: () => quietHoursDeferral,
+  renderNotification: () => renderNotification
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/messaging-service-plugin.ts
+var import_node_crypto2 = require("crypto");
+
+// src/recipient-resolver.ts
+function looksLikeEmail(s) {
+  if (!s || /\s/.test(s)) return false;
+  const at = s.indexOf("@");
+  if (at <= 0 || at !== s.lastIndexOf("@") || at === s.length - 1) return false;
+  const domain = s.slice(at + 1);
+  const dot = domain.indexOf(".");
+  return dot > 0 && dot < domain.length - 1;
+}
+var USER_OBJECT = "sys_user";
+var MEMBER_OBJECT = "sys_member";
+var TEAM_MEMBER_OBJECT = "sys_team_member";
+var DEFAULT_OWNER_FIELDS = ["owner_id", "assigned_to", "assignee_id", "owner", "assignee"];
+var RecipientResolver = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.userObject = opts.userObject ?? USER_OBJECT;
+    this.memberObject = opts.memberObject ?? MEMBER_OBJECT;
+    this.teamMemberObject = opts.teamMemberObject ?? TEAM_MEMBER_OBJECT;
+    this.ownerFields = opts.ownerFields ?? DEFAULT_OWNER_FIELDS;
+  }
+  /** Expand an audience to a de-duplicated list of recipient user ids. */
+  async resolve(audience, ctx = {}) {
+    const specs = Array.isArray(audience) ? audience : [audience];
+    const data = this.opts.getData();
+    const out = [];
+    for (const spec of specs) {
+      for (const id of await this.resolveOne(spec, data, ctx)) {
+        if (id) out.push(id);
+      }
+    }
+    return [...new Set(out)];
+  }
+  async resolveOne(spec, data, ctx) {
+    if (typeof spec !== "string") {
+      if (spec && typeof spec === "object" && "ownerOf" in spec) {
+        return this.resolveOwnerOf(spec.ownerOf.object, spec.ownerOf.id, data);
+      }
+      this.opts.logger.warn(`[recipients] unrecognized audience spec ${JSON.stringify(spec)}; skipped`);
+      return [];
+    }
+    const value = spec.trim();
+    if (!value) return [];
+    if (value.startsWith("user:")) return [value.slice(5)].filter(Boolean);
+    if (value.startsWith("role:")) return this.resolveRole(value.slice(5), data, ctx);
+    if (value.startsWith("team:")) return this.resolveTeam(value.slice(5), data);
+    if (value.startsWith("owner_of:")) {
+      const rest = value.slice("owner_of:".length);
+      const sep = rest.indexOf(":");
+      if (sep > 0) return this.resolveOwnerOf(rest.slice(0, sep), rest.slice(sep + 1), data);
+      this.opts.logger.warn(`[recipients] malformed owner_of spec '${value}'; skipped`);
+      return [];
+    }
+    if (looksLikeEmail(value)) return [await this.resolveEmail(value, data)];
+    return [value];
+  }
+  /** `role:` → `sys_member` rows with that role in the tenant. */
+  async resolveRole(role, data, ctx) {
+    if (!role || !data) return [];
+    const where = { role };
+    if (ctx.organizationId) where.organization_id = ctx.organizationId;
+    try {
+      const rows = await data.find(this.memberObject, { where, fields: ["user_id"], limit: 1e4 });
+      return userIds(rows);
+    } catch (err) {
+      this.opts.logger.warn(`[recipients] role '${role}' lookup failed (${msg(err)}); 0 recipients`);
+      return [];
+    }
+  }
+  /** `team:` → `sys_team_member` rows for that team. */
+  async resolveTeam(teamId, data) {
+    if (!teamId || !data) return [];
+    try {
+      const rows = await data.find(this.teamMemberObject, {
+        where: { team_id: teamId },
+        fields: ["user_id"],
+        limit: 1e4
+      });
+      return userIds(rows);
+    } catch (err) {
+      this.opts.logger.warn(`[recipients] team '${teamId}' lookup failed (${msg(err)}); 0 recipients`);
+      return [];
+    }
+  }
+  /** `owner_of:` → the owner/assignee field of the referenced record. */
+  async resolveOwnerOf(object, id, data) {
+    if (!object || !id || !data) return [];
+    try {
+      const rec = await data.findOne(object, { where: { id }, fields: ["id", ...this.ownerFields] });
+      if (!rec) return [];
+      for (const f of this.ownerFields) {
+        const v = rec[f];
+        if (typeof v === "string" && v.length > 0) return [v];
+      }
+      return [];
+    } catch (err) {
+      this.opts.logger.warn(`[recipients] owner_of '${object}:${id}' lookup failed (${msg(err)}); 0 recipients`);
+      return [];
+    }
+  }
+  /**
+   * Resolve an email-shaped recipient to its user id. Falls back to the email
+   * verbatim on no match or lookup error (a downstream channel may still key
+   * a row by it — never lose the recipient on a directory miss).
+   */
+  async resolveEmail(email, data) {
+    if (!data) return email;
+    try {
+      const user = await data.findOne(this.userObject, { where: { email }, fields: ["id"] });
+      const id = user?.id;
+      if (id != null && String(id).length > 0) return String(id);
+      this.opts.logger.warn(`[recipients] no '${this.userObject}' matched email '${email}'; keeping verbatim`);
+      return email;
+    } catch (err) {
+      this.opts.logger.warn(`[recipients] email '${email}' lookup failed (${msg(err)}); keeping verbatim`);
+      return email;
+    }
+  }
+};
+function userIds(rows) {
+  if (!Array.isArray(rows)) return [];
+  return [...new Set(rows.map((r) => String(r?.user_id ?? "")).filter(Boolean))];
+}
+function msg(err) {
+  return err?.message ?? String(err);
+}
+
+// src/preference-resolver.ts
+var PREFERENCE_OBJECT = "sys_notification_preference";
+var WILDCARD = "*";
+var PreferenceResolver = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.objectName = opts.objectName ?? PREFERENCE_OBJECT;
+    this.mandatory = opts.mandatoryTopics ?? [];
+  }
+  /** Whether a topic bypasses preferences (exact or `prefix.` match). */
+  isMandatory(topic) {
+    return this.mandatory.some(
+      (m) => m.endsWith(".") ? topic.startsWith(m) : topic === m
+    );
+  }
+  /**
+   * Filter `(recipient × channel)` by preference. Recipients left with no
+   * accepted channel are dropped from the result.
+   */
+  async filter(recipients, channels, ctx) {
+    const all = () => recipients.map((r) => ({ recipient: r, channels: [...channels] }));
+    if (recipients.length === 0 || channels.length === 0) return [];
+    if (this.isMandatory(ctx.topic)) return all();
+    const data = this.opts.getData();
+    if (!data) return all();
+    let rows;
+    try {
+      rows = await this.loadRows(data, ctx);
+    } catch (err) {
+      this.opts.logger.warn(
+        `[preferences] lookup for topic '${ctx.topic}' failed (${msg2(err)}); delivering all (fail-open)`
+      );
+      return all();
+    }
+    const recipientSet = new Set(recipients);
+    const index = /* @__PURE__ */ new Map();
+    for (const r of rows) {
+      const user = String(r.user_id ?? "");
+      if (user !== WILDCARD && !recipientSet.has(user)) continue;
+      const topic = String(r.topic ?? WILDCARD);
+      const channel = String(r.channel ?? WILDCARD);
+      index.set(`${user}|${topic}|${channel}`, {
+        enabled: asBool(r.enabled),
+        quietHours: parseQuietHours(r.quiet_hours)
+      });
+    }
+    const nowMs = ctx.now ?? Date.now();
+    const critical = ctx.severity === "critical";
+    const targets = [];
+    for (const recipient of recipients) {
+      const accepted = channels.filter(
+        (channel) => this.resolveRow(index, recipient, ctx.topic, channel)?.enabled ?? true
+      );
+      if (accepted.length === 0) continue;
+      let notBefore;
+      if (!critical) {
+        const qh = this.resolveQuietHours(index, recipient, ctx.topic);
+        notBefore = qh ? quietHoursDeferral(qh, nowMs) : void 0;
+      }
+      targets.push(notBefore != null ? { recipient, channels: accepted, notBefore } : { recipient, channels: accepted });
+    }
+    return targets;
+  }
+  /** Load the candidate rows (topic-specific + wildcard-topic), org-scoped. */
+  async loadRows(data, ctx) {
+    const base = {};
+    if (ctx.organizationId) base.organization_id = ctx.organizationId;
+    const [specific, wildcard] = await Promise.all([
+      data.find(this.objectName, { where: { ...base, topic: ctx.topic }, limit: 1e4 }),
+      data.find(this.objectName, { where: { ...base, topic: WILDCARD }, limit: 1e4 })
+    ]);
+    return [...specific ?? [], ...wildcard ?? []];
+  }
+  /**
+   * Most-specific-wins lookup for (user, topic, channel). User-specific beats
+   * the `*` user; topic/channel specific beats their wildcards.
+   */
+  resolveRow(index, user, topic, channel) {
+    for (const u of [user, WILDCARD]) {
+      for (const t of [topic, WILDCARD]) {
+        for (const c of [channel, WILDCARD]) {
+          const hit = index.get(`${u}|${t}|${c}`);
+          if (hit !== void 0) return hit;
+        }
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Resolve a recipient's quiet-hours window. Declared on a channel-wildcard
+   * row (`(user, *, *)` or `(user, topic, *)`) — quiet hours are a per-person,
+   * channel-agnostic setting. Most-specific user/topic wins.
+   */
+  resolveQuietHours(index, user, topic) {
+    for (const u of [user, WILDCARD]) {
+      for (const t of [topic, WILDCARD]) {
+        const hit = index.get(`${u}|${t}|${WILDCARD}`);
+        if (hit?.quietHours) return hit.quietHours;
+      }
+    }
+    return void 0;
+  }
+};
+function asBool(v) {
+  return v === true || v === 1 || v === "1" || v === "true";
+}
+function parseQuietHours(v) {
+  let o = v;
+  if (typeof o === "string") {
+    try {
+      o = JSON.parse(o);
+    } catch {
+      return void 0;
+    }
+  }
+  if (!o || typeof o !== "object") return void 0;
+  if (o.start == null || o.end == null) return void 0;
+  return { tz: o.tz, start: String(o.start), end: String(o.end) };
+}
+function quietHoursDeferral(quietHours, nowMs) {
+  const start = parseHHMM(quietHours.start);
+  const end = parseHHMM(quietHours.end);
+  if (start == null || end == null || start === end) return void 0;
+  const cur = minutesOfDayInTz(nowMs, quietHours.tz ?? "UTC");
+  let untilEnd;
+  if (start < end) {
+    if (cur >= start && cur < end) untilEnd = end - cur;
+  } else {
+    if (cur >= start) untilEnd = 1440 - cur + end;
+    else if (cur < end) untilEnd = end - cur;
+  }
+  return untilEnd == null ? void 0 : nowMs + untilEnd * 6e4;
+}
+function parseHHMM(s) {
+  if (!s) return void 0;
+  const m = /^(\d{1,2}):(\d{2})$/.exec(s.trim());
+  if (!m) return void 0;
+  const h = Number(m[1]);
+  const min = Number(m[2]);
+  if (h > 23 || min > 59) return void 0;
+  return h * 60 + min;
+}
+function minutesOfDayInTz(nowMs, tz) {
+  try {
+    const parts = new Intl.DateTimeFormat("en-US", {
+      hour12: false,
+      hour: "2-digit",
+      minute: "2-digit",
+      timeZone: tz
+    }).formatToParts(new Date(nowMs));
+    const hour = Number(parts.find((p) => p.type === "hour")?.value ?? "0") % 24;
+    const minute = Number(parts.find((p) => p.type === "minute")?.value ?? "0");
+    return hour * 60 + minute;
+  } catch {
+    const d = new Date(nowMs);
+    return d.getUTCHours() * 60 + d.getUTCMinutes();
+  }
+}
+function msg2(err) {
+  return err?.message ?? String(err);
+}
+
+// src/messaging-service.ts
+var NOTIFICATION_EVENT_OBJECT = "sys_notification";
+var MessagingService = class {
+  constructor(ctx) {
+    this.ctx = ctx;
+    this.channels = /* @__PURE__ */ new Map();
+    this.now = ctx.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+    this.resolver = ctx.recipientResolver ?? new RecipientResolver({ getData: () => ctx.getData?.(), logger: ctx.logger });
+    this.preferences = ctx.preferenceResolver ?? new PreferenceResolver({
+      getData: () => ctx.getData?.(),
+      logger: ctx.logger,
+      mandatoryTopics: ctx.mandatoryTopics
+    });
+    this.outbox = ctx.outbox;
+  }
+  /**
+   * Attach the durable delivery outbox after construction. The plugin wires
+   * this once the data engine is resolvable (kernel:ready), switching `emit()`
+   * from inline fan-out to the reliable enqueue → dispatcher path.
+   */
+  setOutbox(outbox) {
+    this.outbox = outbox;
+  }
+  /** Register a channel implementation. A duplicate id warns and replaces. */
+  registerChannel(channel) {
+    if (this.channels.has(channel.id)) {
+      this.ctx.logger.warn(`[messaging] channel '${channel.id}' already registered; replacing`);
+    }
+    this.channels.set(channel.id, channel);
+    this.ctx.logger.info(`[messaging] channel registered: ${channel.id}`);
+  }
+  /** Remove a channel. No-op when absent. */
+  unregisterChannel(id) {
+    this.channels.delete(id);
+  }
+  /** Look up a channel by id. */
+  getChannel(id) {
+    return this.channels.get(id);
+  }
+  /** All registered channel ids. */
+  getRegisteredChannels() {
+    return [...this.channels.keys()];
+  }
+  /**
+   * The single notification ingress. Writes the L2 event, resolves the
+   * audience, and fans the result out to its channels. An unregistered
+   * channel, or a channel that throws, is reported as a failed delivery — it
+   * never aborts the rest of the fan-out. A `dedupKey` that matches an
+   * existing event short-circuits: the event id is returned and no new
+   * deliveries are produced.
+   */
+  async emit(input) {
+    const data = this.ctx.getData?.();
+    if (input.dedupKey && data) {
+      const existing = await this.findEventByDedupKey(data, input.dedupKey);
+      if (existing) {
+        this.ctx.logger.info(
+          `[messaging] emit: dedupKey '${input.dedupKey}' already emitted (${existing}); skipping`
+        );
+        return { notificationId: existing, deduped: true, deliveries: [], delivered: 0, failed: 0 };
+      }
+    }
+    let notificationId;
+    try {
+      notificationId = await this.writeEvent(data, input);
+    } catch (err) {
+      if (input.dedupKey && data) {
+        const winner = await this.findEventByDedupKey(data, input.dedupKey);
+        if (winner) {
+          this.ctx.logger.info(
+            `[messaging] emit: dedupKey '${input.dedupKey}' raced; converged to ${winner}`
+          );
+          return { notificationId: winner, deduped: true, deliveries: [], delivered: 0, failed: 0 };
+        }
+      }
+      throw err;
+    }
+    const recipients = await this.resolver.resolve(input.audience, {
+      organizationId: input.organizationId
+    });
+    if (recipients.length === 0) {
+      this.ctx.logger.warn(`[messaging] emit: topic '${input.topic}' resolved to 0 recipients`);
+      return { notificationId, deduped: false, deliveries: [], delivered: 0, failed: 0 };
+    }
+    const payload = input.payload ?? {};
+    const channels = input.channels?.length ? input.channels : ["inbox"];
+    const targets = await this.preferences.filter(recipients, channels, {
+      topic: input.topic,
+      organizationId: input.organizationId,
+      severity: input.severity
+    });
+    if (targets.length === 0) {
+      this.ctx.logger.info(`[messaging] emit: topic '${input.topic}' suppressed for all recipients by preference`);
+      return { notificationId, deduped: false, deliveries: [], delivered: 0, failed: 0 };
+    }
+    if (this.outbox) {
+      const deliveries2 = await this.enqueueDeliveries(this.outbox, notificationId, targets, input, payload);
+      const delivered2 = deliveries2.filter((d) => d.ok).length;
+      return { notificationId, deduped: false, deliveries: deliveries2, delivered: delivered2, failed: deliveries2.length - delivered2 };
+    }
+    const notification = {
+      notificationId,
+      organizationId: input.organizationId,
+      topic: input.topic,
+      title: str(payload.title) ?? input.topic,
+      body: str(payload.body) ?? "",
+      severity: input.severity ?? "info",
+      recipients,
+      channels: input.channels,
+      actionUrl: actionUrlFor(input, payload),
+      payload: input.payload
+    };
+    const { deliveries, delivered, failed } = await this.fanOut(notification, targets);
+    return { notificationId, deduped: false, deliveries, delivered, failed };
+  }
+  /**
+   * Enqueue one `pending` delivery row per `(channel × recipient)`. The
+   * dispatcher does the actual send + retry; here `ok` means "accepted for
+   * delivery" (enqueued), not yet delivered — progress is observable on the
+   * `sys_notification_delivery` row.
+   */
+  async enqueueDeliveries(outbox, notificationId, targets, input, payload) {
+    const deliveryPayload = {
+      ...payload,
+      title: str(payload.title) ?? input.topic,
+      body: str(payload.body) ?? "",
+      severity: input.severity ?? "info",
+      actionUrl: actionUrlFor(input, payload)
+    };
+    const deliveries = [];
+    for (const { recipient, channels, notBefore } of targets) {
+      for (const channel of channels) {
+        try {
+          const id = await outbox.enqueue({
+            notificationId,
+            recipientId: recipient,
+            channel,
+            topic: input.topic,
+            payload: deliveryPayload,
+            organizationId: input.organizationId,
+            // Quiet-hours deferral (P3b): the dispatcher won't claim
+            // this row until `notBefore`. Absent ⇒ immediate.
+            notBefore
+          });
+          deliveries.push({ channel, recipient, ok: true, externalId: id });
+        } catch (err) {
+          deliveries.push({ channel, recipient, ok: false, error: err?.message ?? String(err) });
+        }
+      }
+    }
+    return deliveries;
+  }
+  /** Find an existing event id by its dedup key, tolerating lookup failure. */
+  async findEventByDedupKey(data, dedupKey) {
+    try {
+      const row = await data.findOne(NOTIFICATION_EVENT_OBJECT, {
+        where: { dedup_key: dedupKey },
+        fields: ["id"]
+      });
+      const id = row?.id;
+      return id != null && String(id).length > 0 ? String(id) : void 0;
+    } catch (err) {
+      this.ctx.logger.warn(`[messaging] dedup lookup failed (${err.message}); proceeding`);
+      return void 0;
+    }
+  }
+  /**
+   * Persist the L2 event and return its id. With no data layer (minimal/test
+   * stacks) we warn and synthesize an id so fan-out can still be exercised.
+   */
+  async writeEvent(data, input) {
+    if (!data) {
+      this.ctx.logger.warn("[messaging] no data engine registered; event not persisted");
+      return `evt_${Math.random().toString(36).slice(2)}`;
+    }
+    const row = {
+      topic: input.topic,
+      payload: input.payload ?? null,
+      severity: input.severity ?? "info",
+      dedup_key: input.dedupKey ?? null,
+      // Normalize empty strings to null so the (source_object, source_id)
+      // index keys on real ids, never '' (producers may pass a bare object
+      // with no id — e.g. a comment thread_id with no record part).
+      source_object: str(input.source?.object) ?? null,
+      source_id: str(input.source?.id) ?? null,
+      actor_id: input.actorId ?? null,
+      organization_id: input.organizationId ?? null,
+      created_at: this.now()
+    };
+    const created = await data.insert(NOTIFICATION_EVENT_OBJECT, row);
+    const id = Array.isArray(created) ? created[0]?.id : created?.id ?? created;
+    return id != null ? String(id) : `evt_${Math.random().toString(36).slice(2)}`;
+  }
+  /**
+   * Fan a notification out to each recipient's accepted channels. Each
+   * `(recipient, channel)` pair becomes one `send()` call. An unregistered
+   * channel, or a channel that throws, is reported as a failed delivery — it
+   * never aborts the rest of the fan-out.
+   */
+  async fanOut(notification, targets) {
+    const deliveries = [];
+    for (const { recipient, channels } of targets) {
+      for (const channelId of channels) {
+        const channel = this.channels.get(channelId);
+        if (!channel) {
+          deliveries.push({
+            channel: channelId,
+            recipient,
+            ok: false,
+            error: `channel '${channelId}' not registered`
+          });
+          this.ctx.logger.warn(`[messaging] emit: channel '${channelId}' not registered`);
+          continue;
+        }
+        try {
+          const result = await channel.send(this.ctx, { notification, channel: channelId, recipient });
+          deliveries.push({
+            channel: channelId,
+            recipient,
+            ok: result.ok,
+            externalId: result.externalId,
+            error: result.error
+          });
+        } catch (err) {
+          deliveries.push({
+            channel: channelId,
+            recipient,
+            ok: false,
+            error: err?.message ?? String(err)
+          });
+        }
+      }
+    }
+    const delivered = deliveries.filter((d) => d.ok).length;
+    return { deliveries, delivered, failed: deliveries.length - delivered };
+  }
+};
+function str(v) {
+  if (v == null) return void 0;
+  const s = String(v);
+  return s.length > 0 ? s : void 0;
+}
+function actionUrlFor(input, payload) {
+  const explicit = str(payload.url) ?? str(payload.actionUrl);
+  if (explicit) return explicit;
+  const obj = str(input.source?.object);
+  const id = str(input.source?.id);
+  return obj && id ? `/${obj}/${id}` : void 0;
+}
+
+// src/inbox-channel.ts
+var INBOX_OBJECT = "sys_inbox_message";
+var RECEIPT_OBJECT = "sys_notification_receipt";
+function createInboxChannel(opts) {
+  const objectName = opts.objectName ?? INBOX_OBJECT;
+  const receiptObject = opts.receiptObject ?? RECEIPT_OBJECT;
+  const now = opts.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+  async function writeDeliveredReceipt(ctx, data, r) {
+    if (!r.notificationId) return;
+    try {
+      await data.insert(receiptObject, {
+        notification_id: r.notificationId,
+        delivery_id: null,
+        user_id: r.userId,
+        channel: "inbox",
+        state: "delivered",
+        at: r.at,
+        organization_id: r.organizationId ?? null,
+        created_at: r.at
+      });
+    } catch (err) {
+      ctx.logger.warn(
+        `[inbox] delivered receipt write failed for '${r.userId}' (${err.message}); inbox row stands`
+      );
+    }
+  }
+  return {
+    id: "inbox",
+    async send(ctx, delivery) {
+      const data = opts.getData();
+      const n = delivery.notification;
+      if (!data) {
+        ctx.logger.warn(
+          `[inbox] no data engine registered; inbox row for '${delivery.recipient}' not persisted`
+        );
+        return { ok: true };
+      }
+      const userId = delivery.recipient;
+      const at = now();
+      const row = {
+        user_id: userId,
+        notification_id: n.notificationId ?? null,
+        topic: n.topic,
+        title: n.title,
+        body_md: n.body,
+        severity: n.severity ?? "info",
+        action_url: n.actionUrl,
+        organization_id: n.organizationId ?? null,
+        created_at: at
+      };
+      let inboxId;
+      try {
+        const created = await data.insert(objectName, row);
+        const id = Array.isArray(created) ? created[0]?.id : created?.id ?? created;
+        inboxId = id != null ? String(id) : void 0;
+      } catch (err) {
+        return { ok: false, error: `inbox insert failed: ${err.message}` };
+      }
+      await writeDeliveredReceipt(ctx, data, {
+        notificationId: n.notificationId,
+        userId,
+        organizationId: n.organizationId,
+        at
+      });
+      return { ok: true, externalId: inboxId };
+    },
+    classifyError(_err) {
+      return "retryable";
+    }
+  };
+}
+
+// src/sql-outbox.ts
+var import_node_crypto = require("crypto");
+
+// src/backoff.ts
+function hashPartition(key, count) {
+  if (count <= 0) throw new Error("partition count must be > 0");
+  let h = 2166136261;
+  for (let i = 0; i < key.length; i++) {
+    h ^= key.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return Math.abs(h | 0) % count;
+}
+function nextRetryDelayMs(attemptsSoFar, rng = Math.random) {
+  const SCHEDULE = [1e3, 1e4, 6e4, 6e5, 36e5];
+  if (attemptsSoFar < 1 || attemptsSoFar > SCHEDULE.length) return null;
+  const base = SCHEDULE[attemptsSoFar - 1];
+  const jitter = 0.8 + rng() * 0.4;
+  return Math.floor(base * jitter);
+}
+function classifyDeliveryAttempt(result, errorClass, attemptsSoFar, now = Date.now(), rng) {
+  if (result.ok) return { success: true };
+  if (errorClass === "invalid_recipient") {
+    return { success: false, error: result.error, suppressed: true };
+  }
+  if (errorClass === "permanent") {
+    return { success: false, error: result.error, dead: true };
+  }
+  const delay = nextRetryDelayMs(attemptsSoFar + 1, rng);
+  if (delay === null) {
+    return { success: false, error: result.error, dead: true };
+  }
+  return { success: false, error: result.error, nextAttemptAt: now + delay };
+}
+
+// src/sql-outbox.ts
+var DELIVERY_OBJECT = "sys_notification_delivery";
+var SqlNotificationOutbox = class {
+  constructor(engine, opts) {
+    this.engine = engine;
+    if (opts.partitionCount <= 0) throw new Error("SqlNotificationOutbox: partitionCount must be > 0");
+    this.objectName = opts.objectName ?? DELIVERY_OBJECT;
+    this.partitionCount = opts.partitionCount;
+  }
+  async enqueue(input) {
+    const dedup = {
+      notification_id: input.notificationId,
+      recipient_id: input.recipientId,
+      channel: input.channel
+    };
+    const existing = await this.engine.findOne(this.objectName, { where: dedup, fields: ["id"] });
+    if (existing?.id) return String(existing.id);
+    const id = (0, import_node_crypto.randomUUID)();
+    const now = Date.now();
+    const row = {
+      id,
+      notification_id: input.notificationId,
+      recipient_id: input.recipientId,
+      channel: input.channel,
+      topic: input.topic ?? null,
+      payload: input.payload ?? {},
+      organization_id: input.organizationId ?? null,
+      partition_key: hashPartition(input.notificationId, this.partitionCount),
+      status: "pending",
+      attempts: 0,
+      // Deferred dispatch (quiet-hours, P3): claim() skips pending rows
+      // whose next_attempt_at is in the future.
+      next_attempt_at: input.notBefore ?? null,
+      created_at: now,
+      updated_at: now
+    };
+    try {
+      await this.engine.insert(this.objectName, row);
+      return id;
+    } catch (err) {
+      const winner = await this.engine.findOne(this.objectName, { where: dedup, fields: ["id"] });
+      if (winner?.id) return String(winner.id);
+      throw err;
+    }
+  }
+  async claim(opts) {
+    const now = opts.now ?? Date.now();
+    await this.engine.update(
+      this.objectName,
+      { status: "pending", claimed_by: null, claimed_at: null, updated_at: now },
+      { where: { status: "in_flight", claimed_at: { $lt: now - opts.claimTtlMs } }, multi: true }
+    );
+    const partitionFilter = opts.partition ? { partition_key: opts.partition.index } : {};
+    const candidates = await this.engine.find(this.objectName, {
+      where: {
+        status: "pending",
+        ...partitionFilter,
+        $or: [{ next_attempt_at: null }, { next_attempt_at: { $lte: now } }]
+      },
+      fields: ["id"],
+      limit: opts.limit
+    });
+    if (!candidates.length) return [];
+    const ids = candidates.map((c) => c.id);
+    await this.engine.update(
+      this.objectName,
+      { status: "in_flight", claimed_by: opts.nodeId, claimed_at: now, updated_at: now },
+      { where: { id: { $in: ids }, status: "pending" }, multi: true }
+    );
+    const claimed = await this.engine.find(this.objectName, {
+      where: { id: { $in: ids }, claimed_by: opts.nodeId, claimed_at: now, status: "in_flight" }
+    });
+    return claimed.map((r) => this.toRecord(r));
+  }
+  async ack(id, result) {
+    const current = await this.engine.findOne(this.objectName, {
+      where: { id },
+      fields: ["attempts"]
+    });
+    if (!current) return;
+    const now = Date.now();
+    let status;
+    let nextAttemptAt = null;
+    let error = null;
+    if (result.success) {
+      status = "success";
+    } else if (result.suppressed) {
+      status = "suppressed";
+      error = result.error ?? null;
+    } else if (result.dead) {
+      status = "dead";
+      error = result.error ?? null;
+    } else {
+      status = "pending";
+      nextAttemptAt = result.nextAttemptAt ?? null;
+      error = result.error ?? null;
+    }
+    await this.engine.update(
+      this.objectName,
+      {
+        status,
+        attempts: (current.attempts ?? 0) + 1,
+        last_attempted_at: now,
+        claimed_by: null,
+        claimed_at: null,
+        next_attempt_at: nextAttemptAt,
+        error,
+        updated_at: now
+      },
+      { where: { id }, multi: false }
+    );
+  }
+  async list(filter) {
+    const where = {};
+    if (filter?.status) where.status = filter.status;
+    if (filter?.notificationId) where.notification_id = filter.notificationId;
+    const rows = await this.engine.find(this.objectName, { where });
+    return rows.map((r) => this.toRecord(r));
+  }
+  toRecord(r) {
+    let payload = r.payload ?? {};
+    if (typeof payload === "string") {
+      try {
+        payload = JSON.parse(payload);
+      } catch {
+        payload = {};
+      }
+    }
+    return {
+      id: r.id,
+      notificationId: r.notification_id,
+      recipientId: r.recipient_id,
+      channel: r.channel,
+      topic: r.topic ?? void 0,
+      payload,
+      organizationId: r.organization_id ?? void 0,
+      partitionKey: r.partition_key,
+      status: r.status,
+      attempts: r.attempts,
+      claimedBy: r.claimed_by ?? void 0,
+      claimedAt: r.claimed_at ?? void 0,
+      nextAttemptAt: r.next_attempt_at ?? void 0,
+      lastAttemptedAt: r.last_attempted_at ?? void 0,
+      error: r.error ?? void 0,
+      createdAt: r.created_at,
+      updatedAt: r.updated_at
+    };
+  }
+};
+
+// src/dispatcher.ts
+var SINGLE_NODE_CLUSTER = {
+  lock: {
+    async acquire() {
+      return { release() {
+      }, isHeld: () => true, renew() {
+      } };
+    }
+  }
+};
+var NotificationDispatcher = class {
+  constructor(options) {
+    this.running = false;
+    const intervalMs = options.intervalMs ?? 500;
+    const lockTtlMs = options.lockTtlMs ?? intervalMs * 5;
+    this.opts = {
+      nodeId: options.nodeId,
+      outbox: options.outbox,
+      channels: options.channels,
+      channelContext: options.channelContext,
+      cluster: options.cluster ?? SINGLE_NODE_CLUSTER,
+      partitionCount: options.partitionCount ?? 8,
+      batchSize: options.batchSize ?? 32,
+      intervalMs,
+      lockTtlMs,
+      claimTtlMs: options.claimTtlMs ?? lockTtlMs * 2,
+      rng: options.rng,
+      now: options.now,
+      logger: options.logger,
+      onAttempt: options.onAttempt
+    };
+  }
+  /** Begin the periodic loop. Idempotent. */
+  start() {
+    if (this.running) return;
+    this.running = true;
+    this.scheduleTick();
+    this.timer = setInterval(() => this.scheduleTick(), this.opts.intervalMs);
+    this.timer?.unref?.();
+  }
+  /** Stop the loop and drain the in-flight tick. */
+  async stop() {
+    if (!this.running) return;
+    this.running = false;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = void 0;
+    }
+    if (this.inflightTick) {
+      try {
+        await this.inflightTick;
+      } catch {
+      }
+    }
+  }
+  /** Run one full tick (all partitions). Exposed for deterministic tests. */
+  async tick() {
+    await this.runTick();
+  }
+  scheduleTick() {
+    if (this.inflightTick) return;
+    this.inflightTick = this.runTick().catch((err) => {
+      this.opts.logger?.warn?.("notification-dispatcher: tick failed", {
+        nodeId: this.opts.nodeId,
+        error: err?.message ?? String(err)
+      });
+    }).finally(() => {
+      this.inflightTick = void 0;
+    });
+  }
+  async runTick() {
+    const count = this.opts.partitionCount;
+    const offset = stableNodeOffset(this.opts.nodeId, count);
+    for (let step = 0; step < count; step++) {
+      await this.runPartition((offset + step) % count);
+    }
+  }
+  async runPartition(index) {
+    const handle = await this.opts.cluster.lock.acquire(`notify.dispatcher.partition.${index}`, {
+      ttlMs: this.opts.lockTtlMs,
+      waitMs: 0
+    });
+    if (!handle) return;
+    try {
+      const claimed = await this.opts.outbox.claim({
+        nodeId: this.opts.nodeId,
+        limit: this.opts.batchSize,
+        partition: { index, count: this.opts.partitionCount },
+        claimTtlMs: this.opts.claimTtlMs
+      });
+      if (claimed.length === 0) return;
+      await handle.renew?.(this.opts.lockTtlMs);
+      for (const row of claimed) {
+        if (handle.isHeld && !handle.isHeld()) break;
+        await this.processRow(row);
+      }
+    } finally {
+      await handle.release();
+    }
+  }
+  async processRow(row) {
+    const channel = this.opts.channels.getChannel(row.channel);
+    if (!channel) {
+      await this.opts.outbox.ack(row.id, {
+        success: false,
+        error: `channel '${row.channel}' not registered`,
+        dead: true
+      });
+      this.opts.onAttempt?.(row, false);
+      return;
+    }
+    const p = row.payload ?? {};
+    const notification = {
+      notificationId: row.notificationId,
+      organizationId: row.organizationId,
+      topic: row.topic,
+      title: typeof p.title === "string" ? p.title : row.topic ?? "",
+      body: typeof p.body === "string" ? p.body : "",
+      severity: p.severity ?? "info",
+      recipients: [row.recipientId],
+      channels: [row.channel],
+      actionUrl: typeof p.actionUrl === "string" ? p.actionUrl : void 0,
+      payload: p
+    };
+    let result;
+    try {
+      result = await channel.send(this.opts.channelContext, {
+        notification,
+        channel: row.channel,
+        recipient: row.recipientId
+      });
+    } catch (err) {
+      result = { ok: false, error: err?.message ?? String(err) };
+    }
+    const errorClass = !result.ok && channel.classifyError ? channel.classifyError(result.error) : void 0;
+    const now = this.opts.now?.() ?? Date.now();
+    const ack = classifyDeliveryAttempt(result, errorClass, row.attempts, now, this.opts.rng);
+    await this.opts.outbox.ack(row.id, ack);
+    this.opts.onAttempt?.(row, result.ok);
+  }
+};
+function stableNodeOffset(nodeId, partitionCount) {
+  let h = 0;
+  for (let i = 0; i < nodeId.length; i++) h = h * 31 + nodeId.charCodeAt(i) | 0;
+  return Math.abs(h) % partitionCount;
+}
+
+// src/retention.ts
+var DEFAULT_RETENTION_TARGETS = [
+  { object: RECEIPT_OBJECT, tsField: "created_at", format: "iso" },
+  { object: INBOX_OBJECT, tsField: "created_at", format: "iso" },
+  { object: DELIVERY_OBJECT, tsField: "created_at", format: "epoch" },
+  { object: NOTIFICATION_EVENT_OBJECT, tsField: "created_at", format: "iso" }
+];
+var NotificationRetention = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.now = opts.now ?? (() => Date.now());
+    this.targets = opts.targets ?? DEFAULT_RETENTION_TARGETS;
+  }
+  /**
+   * Delete pipeline rows older than `retentionDays`. Returns one outcome per
+   * swept object. No-op (empty result) when no data engine is available or
+   * `retentionDays` is not a positive number.
+   */
+  async prune(retentionDays) {
+    const data = this.opts.getData();
+    if (!data) {
+      this.opts.logger.warn("[messaging] retention: no data engine; prune skipped");
+      return [];
+    }
+    if (!(retentionDays > 0)) {
+      this.opts.logger.warn(`[messaging] retention: invalid retentionDays=${retentionDays}; prune skipped`);
+      return [];
+    }
+    const cutoffMs = this.now() - retentionDays * 864e5;
+    const cutoffIso = new Date(cutoffMs).toISOString();
+    const outcomes = [];
+    for (const t of this.targets) {
+      const cutoff = t.format === "epoch" ? cutoffMs : cutoffIso;
+      try {
+        const res = await data.delete(t.object, {
+          where: { [t.tsField]: { $lt: cutoff } },
+          multi: true,
+          // System context: retention is an operator policy that spans
+          // tenants, so it must not be scoped by the caller's RLS.
+          context: { isSystem: true }
+        });
+        const deleted = countDeleted(res);
+        outcomes.push({ object: t.object, deleted });
+        if (deleted === void 0 || deleted > 0) {
+          this.opts.logger.info(
+            `[messaging] retention: pruned ${deleted ?? "?"} ${t.object} rows older than ${cutoffIso}`
+          );
+        }
+      } catch (err) {
+        const msg3 = err?.message ?? String(err);
+        this.opts.logger.warn(`[messaging] retention: prune of ${t.object} failed (${msg3}); continuing`);
+        outcomes.push({ object: t.object, error: msg3 });
+      }
+    }
+    return outcomes;
+  }
+};
+function countDeleted(res) {
+  if (typeof res === "number") return res;
+  if (Array.isArray(res)) return res.length;
+  if (res && typeof res === "object") {
+    const r = res;
+    for (const k of ["deletedCount", "deleted", "count", "affected", "affectedRows"]) {
+      if (typeof r[k] === "number") return r[k];
+    }
+  }
+  return void 0;
+}
+
+// src/template-renderer.ts
+var TEMPLATE_OBJECT = "sys_notification_template";
+var DEFAULT_LOCALE = "en";
+var TOKEN = /\{\{\s*([\w.$]+)\s*\}\}/g;
+function interpolate(template, context) {
+  if (!template) return "";
+  return template.replace(TOKEN, (_m, path) => {
+    const v = lookup(context, path);
+    return v == null ? "" : String(v);
+  });
+}
+function lookup(ctx, path) {
+  let cur = ctx;
+  for (const key of path.split(".")) {
+    if (cur == null || typeof cur !== "object") return void 0;
+    cur = cur[key];
+  }
+  return cur;
+}
+function renderNotification(template, input) {
+  const ctx = {
+    ...input.payload,
+    payload: input.payload,
+    topic: input.topic,
+    title: input.title ?? input.payload.title,
+    body: input.body ?? input.payload.body
+  };
+  if (template && (template.subject || template.body)) {
+    const subject = interpolate(String(template.subject ?? ""), ctx) || String(ctx.title ?? input.topic);
+    const renderedBody = interpolate(String(template.body ?? ""), ctx);
+    const isHtml = template.format === "html" || template.format === "mjml";
+    return isHtml ? { subject, html: renderedBody } : { subject, text: renderedBody };
+  }
+  return {
+    subject: String(ctx.title ?? input.topic),
+    text: String(ctx.body ?? "")
+  };
+}
+var NotificationTemplateStore = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.objectName = opts.objectName ?? TEMPLATE_OBJECT;
+  }
+  async load(topic, channel, locale) {
+    const data = this.opts.getData();
+    if (!data) return null;
+    const candidates = localeCandidates(locale);
+    for (const loc of candidates) {
+      try {
+        const row = await data.findOne(this.objectName, {
+          where: { topic, channel, locale: loc, is_active: true },
+          fields: ["subject", "body", "format"]
+        });
+        if (row) return row;
+      } catch {
+        return null;
+      }
+    }
+    return null;
+  }
+};
+function localeCandidates(locale) {
+  const out = [];
+  const push = (l) => {
+    if (l && !out.includes(l)) out.push(l);
+  };
+  push(locale);
+  if (locale && locale.includes("-")) push(locale.split("-")[0]);
+  push(DEFAULT_LOCALE);
+  return out;
+}
+
+// src/email-channel.ts
+var USER_OBJECT2 = "sys_user";
+var EMAIL_SHAPE = (s) => {
+  if (!s || /\s/.test(s)) return false;
+  const at = s.indexOf("@");
+  if (at <= 0 || at !== s.lastIndexOf("@") || at === s.length - 1) return false;
+  const dot = s.slice(at + 1).indexOf(".");
+  return dot > 0 && dot < s.length - at - 2;
+};
+function createEmailChannel(opts) {
+  const userObject = opts.userObject ?? USER_OBJECT2;
+  const defaultLocale = opts.defaultLocale ?? DEFAULT_LOCALE;
+  async function resolveAddress(ctx, data, recipient) {
+    if (EMAIL_SHAPE(recipient)) return recipient;
+    if (!data) return void 0;
+    try {
+      const user = await data.findOne(userObject, { where: { id: recipient }, fields: ["email"] });
+      const email = user?.email;
+      return typeof email === "string" && EMAIL_SHAPE(email) ? email : void 0;
+    } catch (err) {
+      ctx.logger.warn(`[email] address lookup for '${recipient}' failed (${err.message})`);
+      return void 0;
+    }
+  }
+  return {
+    id: "email",
+    async send(ctx, delivery) {
+      const email = opts.getEmail();
+      if (!email) {
+        ctx.logger.warn(`[email] no email service registered; '${delivery.recipient}' not emailed`);
+        return { ok: true };
+      }
+      const n = delivery.notification;
+      const address = await resolveAddress(ctx, opts.getData(), delivery.recipient);
+      if (!address) {
+        return { ok: false, error: `no email address for recipient '${delivery.recipient}'` };
+      }
+      const payload = n.payload ?? {};
+      const locale = typeof payload.locale === "string" ? payload.locale : defaultLocale;
+      const template = await opts.store.load(n.topic ?? "", "email", locale);
+      const rendered = renderNotification(template, {
+        topic: n.topic ?? "",
+        payload,
+        title: n.title,
+        body: n.body
+      });
+      try {
+        const result = await email.send({
+          to: address,
+          subject: rendered.subject,
+          ...rendered.html !== void 0 ? { html: rendered.html } : {},
+          ...rendered.text !== void 0 ? { text: rendered.text } : {}
+        });
+        const id = result?.id;
+        return { ok: true, externalId: id != null ? String(id) : void 0 };
+      } catch (err) {
+        return { ok: false, error: `email send failed: ${err.message}` };
+      }
+    },
+    classifyError(_err) {
+      return "retryable";
+    }
+  };
+}
+
+// src/objects/inbox-message.object.ts
+var import_data = require("@objectstack/spec/data");
+var InboxMessage = import_data.ObjectSchema.create({
+  name: "sys_inbox_message",
+  label: "Inbox Message",
+  pluralLabel: "Inbox Messages",
+  icon: "inbox",
+  description: "User-facing in-app notification rows materialized by the inbox messaging channel.",
+  titleFormat: "{title}",
+  compactLayout: ["title", "user_id", "severity", "created_at"],
+  listViews: {
+    mine: {
+      type: "grid",
+      name: "mine",
+      label: "Notifications",
+      data: { provider: "object", object: "sys_inbox_message" },
+      columns: ["title", "topic", "severity", "created_at"],
+      filter: [{ field: "user_id", operator: "equals", value: "{current_user_id}" }],
+      sort: [{ field: "created_at", order: "desc" }],
+      pagination: { pageSize: 50 },
+      emptyState: { title: "Inbox zero", message: "No notifications." }
+    }
+  },
+  fields: {
+    id: import_data.Field.text({
+      label: "Inbox Message ID",
+      required: true,
+      readonly: true
+    }),
+    user_id: import_data.Field.text({
+      label: "Recipient User",
+      required: true,
+      searchable: true
+    }),
+    notification_id: import_data.Field.text({
+      label: "Notification Event",
+      searchable: true,
+      description: "FK \u2192 sys_notification (the L2 event this row materializes)"
+    }),
+    delivery_id: import_data.Field.text({
+      label: "Delivery",
+      description: "FK \u2192 sys_notification_delivery (outbox row); null until P1"
+    }),
+    topic: import_data.Field.text({
+      label: "Topic",
+      searchable: true
+    }),
+    title: import_data.Field.text({
+      label: "Title",
+      required: true
+    }),
+    body_md: import_data.Field.markdown({
+      label: "Body"
+    }),
+    severity: import_data.Field.select({
+      label: "Severity",
+      options: [
+        { label: "Info", value: "info" },
+        { label: "Warning", value: "warning" },
+        { label: "Critical", value: "critical" }
+      ]
+    }),
+    action_url: import_data.Field.text({
+      label: "Action URL"
+    }),
+    created_at: import_data.Field.datetime({
+      label: "Created At",
+      readonly: true
+    })
+  }
+});
+
+// src/objects/notification-receipt.object.ts
+var import_data2 = require("@objectstack/spec/data");
+var NotificationReceipt = import_data2.ObjectSchema.create({
+  name: "sys_notification_receipt",
+  label: "Notification Receipt",
+  pluralLabel: "Notification Receipts",
+  icon: "check-check",
+  isSystem: true,
+  managedBy: "system",
+  description: "Per-recipient \xD7 channel receipt; the source of truth for notification read-state.",
+  titleFormat: "{state}",
+  compactLayout: ["notification_id", "user_id", "channel", "state", "at"],
+  fields: {
+    id: import_data2.Field.text({
+      label: "Receipt ID",
+      required: true,
+      readonly: true
+    }),
+    notification_id: import_data2.Field.text({
+      label: "Notification Event",
+      required: true,
+      searchable: true,
+      description: "FK \u2192 sys_notification (L2 event)"
+    }),
+    delivery_id: import_data2.Field.text({
+      label: "Delivery",
+      required: false,
+      description: "FK \u2192 sys_notification_delivery (outbox row); null until P1"
+    }),
+    user_id: import_data2.Field.text({
+      label: "Recipient User",
+      required: true,
+      searchable: true
+    }),
+    channel: import_data2.Field.text({
+      label: "Channel",
+      required: true,
+      description: "Channel id this receipt is for (inbox / email / push / \u2026)"
+    }),
+    state: import_data2.Field.select(["delivered", "read", "clicked", "dismissed"], {
+      label: "State",
+      required: true,
+      defaultValue: "delivered"
+    }),
+    at: import_data2.Field.datetime({
+      label: "At",
+      required: false,
+      description: "When the receipt reached its current state"
+    }),
+    created_at: import_data2.Field.datetime({
+      label: "Created At",
+      readonly: true
+    })
+  },
+  indexes: [
+    { fields: ["notification_id", "user_id", "channel"], unique: true },
+    { fields: ["user_id", "state"] }
+  ]
+});
+
+// src/objects/notification-delivery.object.ts
+var import_data3 = require("@objectstack/spec/data");
+var NotificationDelivery = import_data3.ObjectSchema.create({
+  name: "sys_notification_delivery",
+  label: "Notification Delivery",
+  pluralLabel: "Notification Deliveries",
+  icon: "send",
+  isSystem: true,
+  managedBy: "system",
+  description: "Durable per-recipient \xD7 channel delivery outbox (ADR-0030 Layer 4).",
+  titleFormat: "{channel} \u2192 {recipient_id}",
+  compactLayout: ["notification_id", "recipient_id", "channel", "status", "attempts"],
+  fields: {
+    id: import_data3.Field.text({ label: "Delivery ID", required: true, readonly: true }),
+    notification_id: import_data3.Field.text({
+      label: "Notification Event",
+      required: true,
+      searchable: true,
+      description: "FK \u2192 sys_notification (L2 event)"
+    }),
+    recipient_id: import_data3.Field.text({ label: "Recipient User", required: true, searchable: true }),
+    channel: import_data3.Field.text({ label: "Channel", required: true }),
+    topic: import_data3.Field.text({ label: "Topic", searchable: true }),
+    payload: import_data3.Field.json({
+      label: "Payload",
+      description: "Snapshot of the rendered notification content for dispatch."
+    }),
+    status: import_data3.Field.select(["pending", "in_flight", "success", "failed", "dead", "suppressed"], {
+      label: "Status",
+      required: true,
+      defaultValue: "pending"
+    }),
+    attempts: import_data3.Field.number({ label: "Attempts", defaultValue: 0 }),
+    partition_key: import_data3.Field.number({ label: "Partition Key", defaultValue: 0 }),
+    claimed_by: import_data3.Field.text({ label: "Claimed By", description: "Node id while in_flight" }),
+    claimed_at: import_data3.Field.number({ label: "Claimed At (ms)" }),
+    next_attempt_at: import_data3.Field.number({ label: "Next Attempt At (ms)" }),
+    last_attempted_at: import_data3.Field.number({ label: "Last Attempted At (ms)" }),
+    error: import_data3.Field.textarea({ label: "Error" }),
+    created_at: import_data3.Field.number({ label: "Created At (ms)", readonly: true }),
+    updated_at: import_data3.Field.number({ label: "Updated At (ms)" })
+  },
+  indexes: [
+    // Dedup: one delivery per (event, recipient, channel).
+    { fields: ["notification_id", "recipient_id", "channel"], unique: true },
+    // The hot claim query.
+    { fields: ["status", "partition_key", "next_attempt_at"] },
+    // Stale-in_flight reaper.
+    { fields: ["status", "claimed_at"] },
+    { fields: ["notification_id"] }
+  ]
+});
+
+// src/objects/notification-preference.object.ts
+var import_data4 = require("@objectstack/spec/data");
+var NotificationPreference = import_data4.ObjectSchema.create({
+  name: "sys_notification_preference",
+  label: "Notification Preference",
+  pluralLabel: "Notification Preferences",
+  icon: "bell-ring",
+  isSystem: true,
+  managedBy: "system",
+  description: "Per-user \xD7 topic \xD7 channel notification toggle (mute/allow), with admin-global defaults.",
+  titleFormat: "{user_id} \xB7 {topic} \xB7 {channel}",
+  compactLayout: ["user_id", "topic", "channel", "enabled", "digest"],
+  fields: {
+    id: import_data4.Field.text({ label: "Preference ID", required: true, readonly: true }),
+    user_id: import_data4.Field.text({
+      label: "User",
+      required: true,
+      searchable: true,
+      description: "Recipient user id, or '*' for the admin-global default."
+    }),
+    topic: import_data4.Field.text({
+      label: "Topic",
+      required: true,
+      searchable: true,
+      defaultValue: "*",
+      description: "Notification topic, or '*' for all topics."
+    }),
+    channel: import_data4.Field.text({
+      label: "Channel",
+      required: true,
+      defaultValue: "*",
+      description: "Channel id (inbox/email/push/\u2026), or '*' for all channels."
+    }),
+    enabled: import_data4.Field.boolean({
+      label: "Enabled",
+      defaultValue: true,
+      description: "When false, this (user, topic, channel) is muted."
+    }),
+    digest: import_data4.Field.select(["none", "daily", "weekly"], {
+      label: "Digest",
+      required: false,
+      defaultValue: "none",
+      description: "Batch cadence (P3 digest middleware)."
+    }),
+    quiet_hours: import_data4.Field.json({
+      label: "Quiet Hours",
+      required: false,
+      description: "Optional { tz, start, end } window (P3 quiet-hours middleware)."
+    }),
+    created_at: import_data4.Field.datetime({ label: "Created At", readonly: true }),
+    updated_at: import_data4.Field.datetime({ label: "Updated At", required: false })
+  },
+  indexes: [
+    { fields: ["user_id", "topic", "channel"], unique: true },
+    { fields: ["topic"] }
+  ]
+});
+
+// src/objects/notification-subscription.object.ts
+var import_data5 = require("@objectstack/spec/data");
+var NotificationSubscription = import_data5.ObjectSchema.create({
+  name: "sys_notification_subscription",
+  label: "Notification Subscription",
+  pluralLabel: "Notification Subscriptions",
+  icon: "rss",
+  isSystem: true,
+  managedBy: "system",
+  description: "Standing subscription of a principal (role/team/user) to a notification topic.",
+  titleFormat: "{principal} \xB7 {topic}",
+  compactLayout: ["topic", "principal", "enabled", "created_at"],
+  fields: {
+    id: import_data5.Field.text({ label: "Subscription ID", required: true, readonly: true }),
+    topic: import_data5.Field.text({
+      label: "Topic",
+      required: true,
+      searchable: true,
+      description: "Notification topic this principal subscribes to."
+    }),
+    principal: import_data5.Field.text({
+      label: "Principal",
+      required: true,
+      searchable: true,
+      description: "Subscriber selector: 'role:x' | 'team:x' | 'user:id' | bare user id."
+    }),
+    enabled: import_data5.Field.boolean({
+      label: "Enabled",
+      defaultValue: true,
+      description: "When false, the subscription is inactive."
+    }),
+    created_at: import_data5.Field.datetime({ label: "Created At", readonly: true })
+  },
+  indexes: [
+    { fields: ["topic", "principal"], unique: true },
+    { fields: ["topic"] }
+  ]
+});
+
+// src/objects/notification-template.object.ts
+var import_data6 = require("@objectstack/spec/data");
+var NotificationTemplate = import_data6.ObjectSchema.create({
+  name: "sys_notification_template",
+  label: "Notification Template",
+  pluralLabel: "Notification Templates",
+  icon: "file-text",
+  isSystem: true,
+  managedBy: "system",
+  description: "Per (topic \xD7 channel \xD7 locale) render template for notifications.",
+  titleFormat: "{topic} \xB7 {channel} \xB7 {locale}",
+  compactLayout: ["topic", "channel", "locale", "is_active"],
+  fields: {
+    id: import_data6.Field.text({ label: "Template ID", required: true, readonly: true }),
+    topic: import_data6.Field.text({ label: "Topic", required: true, searchable: true }),
+    channel: import_data6.Field.text({
+      label: "Channel",
+      required: true,
+      defaultValue: "email",
+      description: "Channel id this template renders for (email/inbox/push/\u2026)."
+    }),
+    locale: import_data6.Field.text({
+      label: "Locale",
+      required: true,
+      defaultValue: "en",
+      description: "BCP-47 locale, e.g. 'en' / 'en-US' / 'zh-CN'."
+    }),
+    version: import_data6.Field.number({
+      label: "Version",
+      required: false,
+      defaultValue: 1
+    }),
+    subject: import_data6.Field.text({
+      label: "Subject / Title",
+      required: false,
+      description: "Rendered into the email subject / inbox title. Supports {{ payload.x }}."
+    }),
+    body: import_data6.Field.markdown({
+      label: "Body",
+      required: false,
+      description: "Template body. Supports {{ payload.x }}. Interpreted per `format`."
+    }),
+    format: import_data6.Field.select(["markdown", "html", "text", "mjml"], {
+      label: "Body Format",
+      required: false,
+      defaultValue: "markdown"
+    }),
+    is_active: import_data6.Field.boolean({
+      label: "Active",
+      defaultValue: true,
+      description: "Only active templates are selected at render time."
+    }),
+    created_at: import_data6.Field.datetime({ label: "Created At", readonly: true }),
+    updated_at: import_data6.Field.datetime({ label: "Updated At", required: false })
+  },
+  indexes: [
+    { fields: ["topic", "channel", "locale"] },
+    { fields: ["topic"] }
+  ]
+});
+
+// src/messaging-service-plugin.ts
+var MessagingServicePlugin = class {
+  constructor(options = {}) {
+    this.name = "com.objectstack.service.messaging";
+    this.version = "1.0.0";
+    this.type = "standard";
+    this.dependencies = ["com.objectstack.engine.objectql"];
+    this.options = {
+      registerInbox: true,
+      reliableDelivery: true,
+      partitionCount: 8,
+      dispatchIntervalMs: 500,
+      mandatoryTopics: [],
+      retentionDays: 0,
+      retentionSweepMs: 36e5,
+      ...options
+    };
+  }
+  async init(ctx) {
+    const getData = () => {
+      try {
+        return ctx.getService("data") ?? ctx.getService("objectql");
+      } catch {
+        return void 0;
+      }
+    };
+    const service = new MessagingService({
+      logger: ctx.logger,
+      getData,
+      mandatoryTopics: this.options.mandatoryTopics
+    });
+    if (this.options.registerInbox) {
+      service.registerChannel(createInboxChannel({ getData }));
+    }
+    ctx.registerService("messaging", service);
+    ctx.getService("manifest").register({
+      id: "com.objectstack.service.messaging",
+      name: "Messaging Service",
+      version: "1.0.0",
+      type: "plugin",
+      scope: "system",
+      objects: [
+        InboxMessage,
+        NotificationReceipt,
+        NotificationDelivery,
+        NotificationPreference,
+        NotificationSubscription,
+        NotificationTemplate
+      ],
+      navigationContributions: [
+        {
+          app: "setup",
+          group: "group_configuration",
+          priority: 120,
+          items: [
+            { id: "nav_notification_preferences", type: "object", label: "Notification Preferences", objectName: "sys_notification_preference", icon: "bell-ring", requiresObject: "sys_notification_preference" },
+            { id: "nav_notification_subscriptions", type: "object", label: "Notification Subscriptions", objectName: "sys_notification_subscription", icon: "rss", requiresObject: "sys_notification_subscription" },
+            { id: "nav_notification_templates", type: "object", label: "Notification Templates", objectName: "sys_notification_template", icon: "file-text", requiresObject: "sys_notification_template" }
+          ]
+        }
+      ]
+    });
+    if (typeof ctx.hook === "function") {
+      const templateStore = new NotificationTemplateStore({ getData });
+      const getEmail = () => {
+        try {
+          return ctx.getService("email");
+        } catch {
+          return void 0;
+        }
+      };
+      ctx.hook("kernel:ready", async () => {
+        if (getEmail()) {
+          service.registerChannel(createEmailChannel({ getEmail, getData, store: templateStore }));
+          ctx.logger.info("[messaging] email channel registered (renders sys_notification_template)");
+        }
+      });
+    }
+    if (this.options.reliableDelivery && typeof ctx.hook === "function") {
+      ctx.hook("kernel:ready", async () => {
+        const engine = getData();
+        if (!engine) {
+          ctx.logger.warn("[messaging] no data engine at kernel:ready \u2014 reliable delivery disabled (inline fan-out)");
+          return;
+        }
+        const outbox = new SqlNotificationOutbox(engine, { partitionCount: this.options.partitionCount });
+        service.setOutbox(outbox);
+        let cluster;
+        try {
+          cluster = ctx.getService("cluster");
+        } catch {
+          cluster = void 0;
+        }
+        this.dispatcher = new NotificationDispatcher({
+          nodeId: `notify-${process.pid}-${(0, import_node_crypto2.randomUUID)().slice(0, 8)}`,
+          outbox,
+          channels: service,
+          channelContext: { logger: ctx.logger },
+          cluster,
+          partitionCount: this.options.partitionCount,
+          intervalMs: this.options.dispatchIntervalMs,
+          logger: ctx.logger
+        });
+        this.dispatcher.start();
+        ctx.logger.info(
+          `[messaging] reliable delivery on (outbox + dispatcher, ${this.options.partitionCount} partitions${cluster ? ", clustered" : ", single-node"})`
+        );
+      });
+    }
+    if (this.options.retentionDays > 0 && typeof ctx.hook === "function") {
+      ctx.hook("kernel:ready", async () => {
+        const retention = new NotificationRetention({ getData, logger: ctx.logger });
+        const days = this.options.retentionDays;
+        const sweep = () => {
+          void retention.prune(days).catch(
+            (err) => ctx.logger.warn(`[messaging] retention sweep failed: ${err?.message ?? err}`)
+          );
+        };
+        sweep();
+        this.retentionTimer = setInterval(sweep, this.options.retentionSweepMs);
+        this.retentionTimer.unref?.();
+        ctx.logger.info(
+          `[messaging] retention on (prune > ${days}d every ${Math.round(this.options.retentionSweepMs / 1e3)}s)`
+        );
+      });
+    }
+    ctx.logger.info(
+      `[messaging] service registered with channels: ${service.getRegisteredChannels().join(", ") || "(none)"}`
+    );
+  }
+  /** Stop the dispatcher loop + retention sweep on shutdown. */
+  async stop() {
+    await this.dispatcher?.stop();
+    this.dispatcher = void 0;
+    if (this.retentionTimer) {
+      clearInterval(this.retentionTimer);
+      this.retentionTimer = void 0;
+    }
+  }
+};
+
+// src/memory-outbox.ts
+var import_node_crypto3 = require("crypto");
+var MemoryNotificationOutbox = class {
+  constructor(partitionCount = 8, clock = () => Date.now()) {
+    this.partitionCount = partitionCount;
+    this.clock = clock;
+    this.rows = /* @__PURE__ */ new Map();
+  }
+  async enqueue(input) {
+    for (const r of this.rows.values()) {
+      if (r.notificationId === input.notificationId && r.recipientId === input.recipientId && r.channel === input.channel) {
+        return r.id;
+      }
+    }
+    const id = (0, import_node_crypto3.randomUUID)();
+    const now = this.clock();
+    this.rows.set(id, {
+      id,
+      notificationId: input.notificationId,
+      recipientId: input.recipientId,
+      channel: input.channel,
+      topic: input.topic,
+      payload: input.payload ?? {},
+      organizationId: input.organizationId,
+      partitionKey: hashPartition(input.notificationId, this.partitionCount),
+      status: "pending",
+      attempts: 0,
+      // Deferred dispatch (quiet-hours, P3): claim() skips pending rows
+      // whose nextAttemptAt is still in the future.
+      nextAttemptAt: input.notBefore,
+      createdAt: now,
+      updatedAt: now
+    });
+    return id;
+  }
+  async claim(opts) {
+    const now = opts.now ?? this.clock();
+    for (const r of this.rows.values()) {
+      if (r.status === "in_flight" && (r.claimedAt ?? 0) < now - opts.claimTtlMs) {
+        r.status = "pending";
+        r.claimedBy = void 0;
+        r.claimedAt = void 0;
+        r.updatedAt = now;
+      }
+    }
+    const out = [];
+    for (const r of this.rows.values()) {
+      if (out.length >= opts.limit) break;
+      if (r.status !== "pending") continue;
+      if (opts.partition && r.partitionKey !== opts.partition.index) continue;
+      if (r.nextAttemptAt != null && r.nextAttemptAt > now) continue;
+      r.status = "in_flight";
+      r.claimedBy = opts.nodeId;
+      r.claimedAt = now;
+      r.updatedAt = now;
+      out.push({ ...r });
+    }
+    return out;
+  }
+  async ack(id, result) {
+    const r = this.rows.get(id);
+    if (!r) return;
+    const now = this.clock();
+    r.attempts += 1;
+    r.lastAttemptedAt = now;
+    r.claimedBy = void 0;
+    r.claimedAt = void 0;
+    r.updatedAt = now;
+    if (result.success) {
+      r.status = "success";
+      r.nextAttemptAt = void 0;
+      r.error = void 0;
+    } else if (result.suppressed) {
+      r.status = "suppressed";
+      r.error = result.error;
+    } else if (result.dead) {
+      r.status = "dead";
+      r.error = result.error;
+    } else {
+      r.status = "pending";
+      r.nextAttemptAt = result.nextAttemptAt;
+      r.error = result.error;
+    }
+  }
+  async list(filter) {
+    let rows = [...this.rows.values()];
+    if (filter?.status) rows = rows.filter((r) => r.status === filter.status);
+    if (filter?.notificationId) rows = rows.filter((r) => r.notificationId === filter.notificationId);
+    return rows.map((r) => ({ ...r }));
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_LOCALE,
+  DEFAULT_RETENTION_TARGETS,
+  DELIVERY_OBJECT,
+  EMAIL_USER_OBJECT,
+  INBOX_OBJECT,
+  InboxMessage,
+  MEMBER_OBJECT,
+  MemoryNotificationOutbox,
+  MessagingService,
+  MessagingServicePlugin,
+  NOTIFICATION_EVENT_OBJECT,
+  NotificationDelivery,
+  NotificationDispatcher,
+  NotificationPreference,
+  NotificationReceipt,
+  NotificationRetention,
+  NotificationSubscription,
+  NotificationTemplate,
+  NotificationTemplateStore,
+  PREFERENCE_OBJECT,
+  PreferenceResolver,
+  RECEIPT_OBJECT,
+  RecipientResolver,
+  SqlNotificationOutbox,
+  TEAM_MEMBER_OBJECT,
+  TEMPLATE_OBJECT,
+  USER_OBJECT,
+  classifyDeliveryAttempt,
+  createEmailChannel,
+  createInboxChannel,
+  hashPartition,
+  interpolate,
+  nextRetryDelayMs,
+  quietHoursDeferral,
+  renderNotification
+});
+//# sourceMappingURL=index.cjs.map