@wildo-ai/saas-models 1.1.2 → 1.1.4

package/dist/esm/notifications/notification-badges.schemas.js

@@ -3,16 +3,42 @@ import { initZodDecorators } from '@wildo-ai/zod-decorators';
 initZodDecorators(z);
 import { IndicatorVariant } from '@wildo-ai/presets-components-models';
 import { ResourcePrimaryScope } from "../resources/resources.shared.schemas.js";
+/**
+ * The one character that separates the parts of a badge KEY and a badge REFERENCE.
+ *
+ * Both formats are positional, so the separator may not appear inside a part or the parse is
+ * ambiguous. `NotificationBadgeIdentifierSchema` refuses it in an identifier for exactly that
+ * reason, and `collectNotificationBadgeDeclarationViolations` re-states the refusal at boot,
+ * because a declaration object is authored in TypeScript and never `.parse()`d.
+ */
+export const NOTIFICATION_BADGE_KEY_SEPARATOR = ':';
+/** Any string that does not contain {@link NOTIFICATION_BADGE_KEY_SEPARATOR}. */
+export const NOTIFICATION_BADGE_IDENTIFIER_PATTERN = /^[^:]+$/;
 /**
  * Notification badge identifier.
  *
- * No canonical (core) identifiers ship today — the two aspirational placeholders
- * (`new messages` / `unpaid invoices`) were removed because nothing produced them
- * (see `.claude/plans/badge-launcher-retract.md`). When the badge surfacing is
- * reintroduced with a real producer (Reintroduction Contract R1), core identifiers
- * come back as a `CoreNotificationBadgeIdentifiers` enum unioned in here.
+ * The identifier is an open string because no canonical (core) identifier ships: the two
+ * aspirational placeholders (`new messages` / `unpaid invoices`) were removed because nothing
+ * produced them.
+ *
+ * The SURFACING is not missing. A navigation item declares `notificationBadgeRef` and the sidebar
+ * renders it, and an application declares its own badges, so the open string is what an application
+ * uses today. What is still absent is a FRAMEWORK-shipped identifier with a framework producer
+ * behind it; when one lands, core identifiers come back as a `CoreNotificationBadgeIdentifiers`
+ * enum unioned in here.
+ *
+ * Open, but not unconstrained: an identifier may not contain
+ * {@link NOTIFICATION_BADGE_KEY_SEPARATOR}, because it is the LAST part of a badge key and of a
+ * badge reference and both are positional. A definition object is authored in TypeScript and never
+ * `.parse()`d, so this constraint is also re-stated as a boot check — see
+ * {@link collectNotificationBadgeDeclarationViolations}.
  */
-export const NotificationBadgeIdentifierSchema = z.string().min(1, { error: 'Notification badge identifier is required' });
+export const NotificationBadgeIdentifierSchema = z
+    .string()
+    .min(1, { error: 'Notification badge identifier is required' })
+    .regex(NOTIFICATION_BADGE_IDENTIFIER_PATTERN, {
+    error: `Notification badge identifier must not contain "${NOTIFICATION_BADGE_KEY_SEPARATOR}" — that character separates the parts of a badge key and reference`,
+});
 /**
  * Notification badge scope. Tightened to USER_SELF | ORGANIZATIONS only.
  *
@@ -32,6 +58,22 @@ export const NotificationScopeSchema = z.enum([
     ResourcePrimaryScope.USER_SELF,
     ResourcePrimaryScope.ORGANIZATIONS,
 ]);
+/**
+ * @wildo_source:part:start saas.models.notifications.badge-vocabularies facet:layer:shared facet:audience:app-developer
+ *
+ * The four vocabularies a badge definition picks from: how its count is CALCULATED, how it is
+ * PRESENTED, whether it draws attention, and — for a stored counter — what an operation does to it.
+ *
+ * ⚠️ **Choosing the source kind wrongly produces a number that DRIFTS.** Reach for `EVENT_COUNTER`
+ * only when the count is a fact the badge itself owns ("unread messages": arrive → increment, seen →
+ * reset). For any quantity derived from data an operation could change by another route — incomplete
+ * todos, unpaid invoices — use `DERIVED_QUERY`, which recomputes a live aggregate. A stored counter
+ * on a derived quantity is right on the day it is written and wrong thereafter.
+ *
+ * An `EVENT_COUNTER` badge additionally needs `notificationBadgeOperations` declared on the
+ * operations that move it; a `DERIVED_QUERY` badge needs none, because the recompute hangs off the
+ * source resource's own mutations.
+ */
 export var NotificationBadgeOperation;
 (function (NotificationBadgeOperation) {
     NotificationBadgeOperation["INCREMENT"] = "increment";
@@ -77,6 +119,7 @@ export var NotificationBadgePulse;
     /** Persistent — pulse while the count is > 0. */
     NotificationBadgePulse["WHILE_ACTIVE"] = "while_active";
 })(NotificationBadgePulse || (NotificationBadgePulse = {}));
+/** @wildo_source:part:end saas.models.notifications.badge-vocabularies */
 /** EVENT_COUNTER source — no extra config; the stored counter is the truth. */
 export const NotificationBadgeEventCounterSourceSchema = z.object({
     kind: z.literal(NotificationBadgeSourceKind.EVENT_COUNTER),
@@ -156,4 +199,146 @@ export const NotificationBadgeSchema = z.discriminatedUnion('scope', [
     NotificationBadgeOrganizationSchema,
     NotificationBadgeUserSelfSchema,
 ]);
+/** Build the DEFINITION-identity key from its parts. */
+export function buildNotificationBadgeKey(scope, identifier) {
+    return `${scope}${NOTIFICATION_BADGE_KEY_SEPARATOR}${identifier}`;
+}
+/**
+ * The key of a definition (or of anything else carrying a badge identity, such as a persisted row).
+ *
+ * Takes the identity fields rather than the whole definition so a `NotificationBadge` row and a
+ * `NotificationBadgeDefinition` resolve through the SAME function — a second copy for the row shape
+ * is how the two come to disagree.
+ */
+export function notificationBadgeIdentityKey(identity) {
+    return buildNotificationBadgeKey(identity.scope, identity.identifier);
+}
+/**
+ * Parse a key, returning `null` when it is not a well-formed key at a SUPPORTED scope.
+ *
+ * The scope check is not cosmetic: the APPLICATION variant was dropped in the polymorphism refactor
+ * and no resource type backs it, so `application:foo` must fail here rather than reach a dispatch
+ * that has no repository for it.
+ */
+export function parseNotificationBadgeKey(key) {
+    const parts = key.split(NOTIFICATION_BADGE_KEY_SEPARATOR);
+    if (parts.length !== 2)
+        return null;
+    const [scope, identifier] = parts;
+    if (!isSupportedNotificationBadgeScope(scope) || identifier.length === 0)
+        return null;
+    return { scope, identifier };
+}
+/** Build the INSTANCE address carried on the wire. */
+export function buildNotificationBadgeReference(scope, scopeId, identifier) {
+    return `${scope}${NOTIFICATION_BADGE_KEY_SEPARATOR}${scopeId}${NOTIFICATION_BADGE_KEY_SEPARATOR}${identifier}`;
+}
+/** Parse a wire reference, returning `null` for a malformed one or an unsupported scope. */
+export function parseNotificationBadgeReference(reference) {
+    const parts = reference.split(NOTIFICATION_BADGE_KEY_SEPARATOR);
+    if (parts.length !== 3)
+        return null;
+    const [scope, scopeId, identifier] = parts;
+    if (!isSupportedNotificationBadgeScope(scope) || scopeId.length === 0 || identifier.length === 0)
+        return null;
+    return { scope, scopeId, identifier };
+}
+/**
+ * Reduce a wire reference to the DEFINITION key it addresses — the one hop the browser badge store
+ * takes, so that what it keys on is what a navigation item resolves against.
+ */
+export function notificationBadgeKeyFromReference(reference) {
+    const parsed = parseNotificationBadgeReference(reference);
+    return parsed ? buildNotificationBadgeKey(parsed.scope, parsed.identifier) : null;
+}
+/** Whether a raw string names one of the two surviving badge scopes. */
+export function isSupportedNotificationBadgeScope(scope) {
+    return scope === ResourcePrimaryScope.USER_SELF || scope === ResourcePrimaryScope.ORGANIZATIONS;
+}
+// ════════════════════════════════════════════════════════════════
+// Declaration coherence — checked at CONFIGURATION time
+// ════════════════════════════════════════════════════════════════
+/**
+ * Why a badge declaration is refused. A closed vocabulary with a named runtime source, so a
+ * diagnostic can be branched on and each member can carry its own explanation.
+ */
+export var NotificationBadgeDeclarationViolationReason;
+(function (NotificationBadgeDeclarationViolationReason) {
+    /**
+     * Two definitions declare the same `(scope, identifier)`. Every lookup resolves the FIRST, so
+     * the second is unreachable while silently sharing the first's count — the shape that made
+     * identifier-only lookup unsafe in the first place. Two definitions at DIFFERENT scopes are
+     * fine and are exactly what the key makes reachable.
+     */
+    NotificationBadgeDeclarationViolationReason["DUPLICATE_DEFINITION_KEY"] = "duplicate_definition_key";
+    /**
+     * An identifier contains the key separator, which would make its key and every reference built
+     * from it parse into the wrong parts. Refused rather than escaped: a positional format with an
+     * escaping rule is a format two implementations will eventually disagree about.
+     */
+    NotificationBadgeDeclarationViolationReason["IDENTIFIER_CONTAINS_KEY_SEPARATOR"] = "identifier_contains_key_separator";
+    /** An operation declares a `badgeRef` that names no registered definition. */
+    NotificationBadgeDeclarationViolationReason["OPERATION_REF_UNRESOLVED"] = "operation_ref_unresolved";
+})(NotificationBadgeDeclarationViolationReason || (NotificationBadgeDeclarationViolationReason = {}));
+/**
+ * The whole declaration-coherence check, as a pure function over what an application declared.
+ *
+ * Pure and shared on purpose: the backend registry runs it as a fail-closed boot gate and the
+ * frontend launcher verifier reports it in development, and a second implementation is how the two
+ * come to disagree about what a valid declaration is.
+ *
+ * It answers the question `derive-before-you-ask.md` asks — who owes this, and what says so. The
+ * population is exactly the registered definitions plus every authored
+ * `notificationBadgeOperations` entry; nothing is inferred and nothing is sampled.
+ */
+export function collectNotificationBadgeDeclarationViolations(definitions, operationSites = []) {
+    const violations = [];
+    const seenKeys = new Set();
+    for (const definition of definitions) {
+        if (!NOTIFICATION_BADGE_IDENTIFIER_PATTERN.test(definition.identifier)) {
+            violations.push({
+                reason: NotificationBadgeDeclarationViolationReason.IDENTIFIER_CONTAINS_KEY_SEPARATOR,
+                badgeKey: notificationBadgeIdentityKey(definition),
+                identifier: definition.identifier,
+            });
+            // Still recorded below, so a malformed identifier declared twice is reported as both.
+        }
+        const key = notificationBadgeIdentityKey(definition);
+        if (seenKeys.has(key)) {
+            violations.push({
+                reason: NotificationBadgeDeclarationViolationReason.DUPLICATE_DEFINITION_KEY,
+                badgeKey: key,
+                identifier: definition.identifier,
+            });
+            continue;
+        }
+        seenKeys.add(key);
+    }
+    for (const site of operationSites) {
+        if (!seenKeys.has(site.badgeRef)) {
+            violations.push({
+                reason: NotificationBadgeDeclarationViolationReason.OPERATION_REF_UNRESOLVED,
+                badgeKey: site.badgeRef,
+                resourceType: site.resourceType,
+                operationIdentifier: site.operationIdentifier,
+            });
+        }
+    }
+    return violations;
+}
+/**
+ * Index the registered definitions by key, so a dispatch resolves in one lookup rather than a scan.
+ *
+ * Built from the SAME key function the boot check uses, so a definition the boot check accepted is
+ * a definition this map can serve.
+ */
+export function buildNotificationBadgeDefinitionIndex(definitions) {
+    const index = new Map();
+    for (const definition of definitions) {
+        const key = notificationBadgeIdentityKey(definition);
+        if (!index.has(key))
+            index.set(key, definition);
+    }
+    return index;
+}
 //# sourceMappingURL=notification-badges.schemas.js.map

package/dist/esm/notifications/notification-badges.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"notification-badges.schemas.js","sourceRoot":"","sources":["../../../../src/notifications/notification-badges.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\nimport { initZodDecorators } from '@wildo-ai/zod-decorators';\n\ninitZodDecorators(z);\n\nimport { IndicatorVariant } from '@wildo-ai/presets-components-models';\nimport { ResourcePrimaryScope } from \"../resources/resources.shared.schemas\";\n\n\n/**\n * Notification badge identifier.\n *\n * No canonical (core) identifiers ship today — the two aspirational placeholders\n * (`new messages` / `unpaid invoices`) were removed because nothing produced them\n * (see `.claude/plans/badge-launcher-retract.md`). When the badge surfacing is\n * reintroduced with a real producer (Reintroduction Contract R1), core identifiers\n * come back as a `CoreNotificationBadgeIdentifiers` enum unioned in here.\n */\nexport const NotificationBadgeIdentifierSchema = z.string().min(1, { error: 'Notification badge identifier is required' });\n\n/**\n * Notification badge scope. Tightened to USER_SELF | ORGANIZATIONS only.\n *\n * The APPLICATION variant was dropped in the polymorphism refactor\n * (`.cursor/plans/notification-badges-polymorphism-refactor.md`):\n *   - No canonical badges were ever declared at APPLICATION scope (see\n *     `notification-badges.core.definitions.ts`).\n *   - The two surviving variants (USER + ORG) each own their own resource type\n *     and MongoDB collection. Allowing APPLICATION here would let consumers\n *     write a payload that no resource configuration / collection accepts.\n *\n * `WS_BadgeUpdatePayload` semantics are unchanged — the dispatcher in\n * `NotificationBadgeBackendService.emitBadgeUpdate` still routes USER badges to\n * `sendToUser` and ORG badges to `sendToOrganization`.\n */\nexport const NotificationScopeSchema = z.enum([\n    ResourcePrimaryScope.USER_SELF,\n    ResourcePrimaryScope.ORGANIZATIONS,\n]);\n\nexport enum NotificationBadgeOperation {\n    INCREMENT = 'increment',\n    DECREMENT = 'decrement',\n    SET = 'set',\n    RESET = 'reset',\n}\n\n/**\n * How a badge's count is CALCULATED — the load-bearing distinction (R1).\n *\n * - `EVENT_COUNTER`: a stored counter mutated imperatively on domain events\n *   (arrive → increment, seen → reset). Correct for \"unread messages\" style\n *   badges. The count lives in the badge document.\n * - `DERIVED_QUERY`: the count is a LIVE aggregate over a resource collection\n *   (`count(resourceType where filter, scoped)`), recomputed on that resource's\n *   mutations. Correct for \"incomplete todos\" / \"unpaid invoices\" — quantities\n *   derived from data that would DRIFT if tracked with a stored counter.\n */\nexport enum NotificationBadgeSourceKind {\n    EVENT_COUNTER = 'event_counter',\n    DERIVED_QUERY = 'derived_query',\n}\n\n/** How the badge is presented. `NONE` = suppressed even when the count is > 0. */\nexport enum NotificationBadgeDisplayMode {\n    /** A colored signal dot (\"≥ 1\"), no number. */\n    DOT = 'dot',\n    /** The numeric count (truncated at the display cap). */\n    COUNT = 'count',\n    /** Rendered as nothing (count still computed/available). */\n    NONE = 'none',\n}\n\n/**\n * WHETHER / WHEN a badge draws attention. The LOOK of the pulse is theme-owned\n * (`UIBehaviorRecipe.motion.attention`), so a definition only declares intent.\n */\nexport enum NotificationBadgePulse {\n    NONE = 'none',\n    /** Transitional — pulse briefly when the count rises (recommended). */\n    ON_INCREASE = 'on_increase',\n    /** Persistent — pulse while the count is > 0. */\n    WHILE_ACTIVE = 'while_active',\n}\n\n/** EVENT_COUNTER source — no extra config; the stored counter is the truth. */\nexport const NotificationBadgeEventCounterSourceSchema = z.object({\n    kind: z.literal(NotificationBadgeSourceKind.EVENT_COUNTER),\n});\n\n/**\n * DERIVED_QUERY source — the count is `count(resourceType where filter)` with the\n * scope bound via `scopeField` (the FK field on the counted resource that equals\n * the badge's `scopeId`, e.g. `userId` for a USER_SELF badge). Recomputed by the\n * backend on any mutation of `resourceType` (see backend R5).\n */\nexport const NotificationBadgeDerivedQuerySourceSchema = z.object({\n    kind: z.literal(NotificationBadgeSourceKind.DERIVED_QUERY),\n    resourceType: z.string().min(1, { error: 'Derived-badge resourceType is required' }),\n    filter: z.record(z.string(), z.unknown()),\n    scopeField: z.string().min(1, { error: 'Derived-badge scopeField is required' }),\n});\n\n/** Discriminated union over the calculation kinds. */\nexport const NotificationBadgeSourceSchema = z.discriminatedUnion('kind', [\n    NotificationBadgeEventCounterSourceSchema,\n    NotificationBadgeDerivedQuerySourceSchema,\n]);\n\n/**\n * Presentation declaration. `tone` reuses the design-system `IndicatorVariant`\n * (single source — the `Badge` component maps the same enum). `pulse` is a\n * trigger only; the theme owns the animation.\n */\nexport const NotificationBadgeDisplaySchema = z.object({\n    mode: z.enum(NotificationBadgeDisplayMode).default(NotificationBadgeDisplayMode.COUNT),\n    tone: z.enum(IndicatorVariant).default(IndicatorVariant.NEUTRAL),\n    pulse: z.enum(NotificationBadgePulse).default(NotificationBadgePulse.NONE),\n});\n\n/**\n * Badge IDENTITY — the (identifier, scope) tuple shared by the declaration and\n * the persisted document. Kept separate so the stored badge doc does NOT absorb\n * declaration-only fields (`source` / `display`).\n */\nconst NotificationBadgeIdentitySchema = z.object({\n    identifier: NotificationBadgeIdentifierSchema,\n    scope: NotificationScopeSchema,\n});\n\n/**\n * Badge DEFINITION — the declaration app/framework authors register: identity +\n * how the count is calculated (`source`) + how it is presented (`display`).\n */\nexport const NotificationBadgeDefinitionSchema = NotificationBadgeIdentitySchema.extend({\n    source: NotificationBadgeSourceSchema,\n    display: NotificationBadgeDisplaySchema,\n});\n\nconst NotificationBadgeBaseSchema = NotificationBadgeIdentitySchema.extend({\n    // A compact badge without its application-defined identifier is not interpretable: callers\n    // could see a number but not what the number counts. Override the identity field here (rather\n    // than decorating NotificationBadgeIdentitySchema) so persisted API rows gain summary metadata\n    // while application-authored badge definitions remain a plain declaration schema.\n    identifier: NotificationBadgeIdentifierSchema.isSummaryField(),\n    // `isPrimaryKey` (composite: excludeFromCreate + isHidden + isUnique + isDBIndexed) —\n    // the server generates `_id`, so it must NOT be required on the create DTO. Using bare\n    // `.isDBIndexed()` here left `_id` create-required, which failed the dispatcher-driven\n    // badge materialization (`buildNewBadge` supplies no `_id`).\n    _id: z.string().min(1, { error: 'Notification badge ID is required' }).isPrimaryKey(),\n    count: z.number().min(0, { error: 'Notification badge count must be greater than or equal to 0' }).isSummaryField(),\n    createdAt: z.date().default(() => new Date()).isDBIndexed(),\n    updatedAt: z.date().default(() => new Date()).isDBIndexed().isSummaryField(),\n});\n\nexport const NotificationBadgeOrganizationSchema = NotificationBadgeBaseSchema.extend({\n    scope: z.literal(ResourcePrimaryScope.ORGANIZATIONS),\n    organizationId: z.string().min(1, { error: 'Organization ID is required' }).isDBIndexed().isForeignKey(),\n});\n\nexport const NotificationBadgeUserSelfSchema = NotificationBadgeBaseSchema.extend({\n    scope: z.literal(ResourcePrimaryScope.USER_SELF),\n    userId: z.string().min(1, { error: 'User ID is required' }).isDBIndexed().isForeignKey(),\n});\n\n/**\n * Discriminated union over the two surviving badge scopes (USER_SELF / ORGANIZATIONS).\n * The APPLICATION variant was dropped — see `NotificationScopeSchema` JSDoc above.\n */\nexport const NotificationBadgeSchema = z.discriminatedUnion('scope', [\n    NotificationBadgeOrganizationSchema,\n    NotificationBadgeUserSelfSchema,\n]);\n\nexport type NotificationBadgeDefinition = z.infer<typeof NotificationBadgeDefinitionSchema>;\nexport type NotificationBadgeIdentifier = z.infer<typeof NotificationBadgeIdentifierSchema>;\nexport type NotificationScope = z.infer<typeof NotificationScopeSchema>;\nexport type NotificationBadge = z.infer<typeof NotificationBadgeSchema>;\nexport type NotificationBadgeSource = z.infer<typeof NotificationBadgeSourceSchema>;\nexport type NotificationBadgeDerivedQuerySource = z.infer<typeof NotificationBadgeDerivedQuerySourceSchema>;\nexport type NotificationBadgeDisplay = z.infer<typeof NotificationBadgeDisplaySchema>;\n\n"]}
+{"version":3,"file":"notification-badges.schemas.js","sourceRoot":"","sources":["../../../src/notifications/notification-badges.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,iBAAiB,CAAC,CAAC,CAAC,CAAC;AAErB,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AACvE,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAG7E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,GAAG,CAAC;AAEpD,iFAAiF;AACjF,MAAM,CAAC,MAAM,qCAAqC,GAAG,SAAS,CAAC;AAE/D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAAC;KAC7C,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,2CAA2C,EAAE,CAAC;KAC9D,KAAK,CAAC,qCAAqC,EAAE;IAC1C,KAAK,EAAE,mDAAmD,gCAAgC,qEAAqE;CAClK,CAAC,CAAC;AAEP;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,IAAI,CAAC;IAC1C,oBAAoB,CAAC,SAAS;IAC9B,oBAAoB,CAAC,aAAa;CACrC,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAN,IAAY,0BAKX;AALD,WAAY,0BAA0B;IAClC,qDAAuB,CAAA;IACvB,qDAAuB,CAAA;IACvB,yCAAW,CAAA;IACX,6CAAe,CAAA;AACnB,CAAC,EALW,0BAA0B,KAA1B,0BAA0B,QAKrC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAN,IAAY,2BAGX;AAHD,WAAY,2BAA2B;IACnC,8DAA+B,CAAA;IAC/B,8DAA+B,CAAA;AACnC,CAAC,EAHW,2BAA2B,KAA3B,2BAA2B,QAGtC;AAED,kFAAkF;AAClF,MAAM,CAAN,IAAY,4BAOX;AAPD,WAAY,4BAA4B;IACpC,+CAA+C;IAC/C,2CAAW,CAAA;IACX,wDAAwD;IACxD,+CAAe,CAAA;IACf,4DAA4D;IAC5D,6CAAa,CAAA;AACjB,CAAC,EAPW,4BAA4B,KAA5B,4BAA4B,QAOvC;AAED;;;GAGG;AACH,MAAM,CAAN,IAAY,sBAMX;AAND,WAAY,sBAAsB;IAC9B,uCAAa,CAAA;IACb,uEAAuE;IACvE,qDAA2B,CAAA;IAC3B,iDAAiD;IACjD,uDAA6B,CAAA;AACjC,CAAC,EANW,sBAAsB,KAAtB,sBAAsB,QAMjC;AACD,0EAA0E;AAE1E,+EAA+E;AAC/E,MAAM,CAAC,MAAM,yCAAyC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9D,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,2BAA2B,CAAC,aAAa,CAAC;CAC7D,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yCAAyC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9D,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,2BAA2B,CAAC,aAAa,CAAC;IAC1D,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,wCAAwC,EAAE,CAAC;IACpF,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;IACzC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,sCAAsC,EAAE,CAAC;CACnF,CAAC,CAAC;AAEH,sDAAsD;AACtD,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IACtE,yCAAyC;IACzC,yCAAyC;CAC5C,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC,MAAM,CAAC;IACnD,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC,OAAO,CAAC,4BAA4B,CAAC,KAAK,CAAC;IACtF,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC;IAChE,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC,OAAO,CAAC,sBAAsB,CAAC,IAAI,CAAC;CAC7E,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,+BAA+B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,UAAU,EAAE,iCAAiC;IAC7C,KAAK,EAAE,uBAAuB;CACjC,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,+BAA+B,CAAC,MAAM,CAAC;IACpF,MAAM,EAAE,6BAA6B;IACrC,OAAO,EAAE,8BAA8B;CAC1C,CAAC,CAAC;AAEH,MAAM,2BAA2B,GAAG,+BAA+B,CAAC,MAAM,CAAC;IACvE,2FAA2F;IAC3F,8FAA8F;IAC9F,+FAA+F;IAC/F,kFAAkF;IAClF,UAAU,EAAE,iCAAiC,CAAC,cAAc,EAAE;IAC9D,sFAAsF;IACtF,uFAAuF;IACvF,uFAAuF;IACvF,6DAA6D;IAC7D,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,mCAAmC,EAAE,CAAC,CAAC,YAAY,EAAE;IACrF,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,6DAA6D,EAAE,CAAC,CAAC,cAAc,EAAE;IACnH,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE;IAC3D,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE;CAC/E,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,mCAAmC,GAAG,2BAA2B,CAAC,MAAM,CAAC;IAClF,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,oBAAoB,CAAC,aAAa,CAAC;IACpD,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,6BAA6B,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,YAAY,EAAE;CAC3G,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,+BAA+B,GAAG,2BAA2B,CAAC,MAAM,CAAC;IAC9E,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,oBAAoB,CAAC,SAAS,CAAC;IAChD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,YAAY,EAAE;CAC3F,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,kBAAkB,CAAC,OAAO,EAAE;IACjE,mCAAmC;IACnC,+BAA+B;CAClC,CAAC,CAAC;AA+CH,wDAAwD;AACxD,MAAM,UAAU,yBAAyB,CACrC,KAAwB,EACxB,UAAuC;IAEvC,OAAO,GAAG,KAAK,GAAG,gCAAgC,GAAG,UAAU,EAAE,CAAC;AACtE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,4BAA4B,CACxC,QAAmE;IAEnE,OAAO,yBAAyB,CAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CACrC,GAAW;IAEX,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;IAC1D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,GAAG,KAAK,CAAC;IAClC,IAAI,CAAC,iCAAiC,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtF,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AACjC,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,+BAA+B,CAC3C,KAAwB,EACxB,OAAe,EACf,UAAuC;IAEvC,OAAO,GAAG,KAAK,GAAG,gCAAgC,GAAG,OAAO,GAAG,gCAAgC,GAAG,UAAU,EAAE,CAAC;AACnH,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,+BAA+B,CAC3C,SAAiB;IAEjB,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;IAChE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,GAAG,KAAK,CAAC;IAC3C,IAAI,CAAC,iCAAiC,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9G,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;AAC1C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iCAAiC,CAAC,SAAiB;IAC/D,MAAM,MAAM,GAAG,+BAA+B,CAAC,SAAS,CAAC,CAAC;IAC1D,OAAO,MAAM,CAAC,CAAC,CAAC,yBAAyB,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACtF,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,iCAAiC,CAAC,KAAa;IAC3D,OAAO,KAAK,KAAK,oBAAoB,CAAC,SAAS,IAAI,KAAK,KAAK,oBAAoB,CAAC,aAAa,CAAC;AACpG,CAAC;AAED,mEAAmE;AACnE,wDAAwD;AACxD,mEAAmE;AAEnE;;;GAGG;AACH,MAAM,CAAN,IAAY,2CAgBX;AAhBD,WAAY,2CAA2C;IACnD;;;;;OAKG;IACH,oGAAqD,CAAA;IACrD;;;;OAIG;IACH,sHAAuE,CAAA;IACvE,8EAA8E;IAC9E,oGAAqD,CAAA;AACzD,CAAC,EAhBW,2CAA2C,KAA3C,2CAA2C,QAgBtD;AAsBD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,6CAA6C,CACzD,WAAmD,EACnD,iBAAuE,EAAE;IAEzE,MAAM,UAAU,GAA4C,EAAE,CAAC;IAC/D,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAwB,CAAC;IAEjD,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACnC,IAAI,CAAC,qCAAqC,CAAC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YACrE,UAAU,CAAC,IAAI,CAAC;gBACZ,MAAM,EAAE,2CAA2C,CAAC,iCAAiC;gBACrF,QAAQ,EAAE,4BAA4B,CAAC,UAAU,CAAC;gBAClD,UAAU,EAAE,UAAU,CAAC,UAAU;aACpC,CAAC,CAAC;YACH,sFAAsF;QAC1F,CAAC;QAED,MAAM,GAAG,GAAG,4BAA4B,CAAC,UAAU,CAAC,CAAC;QACrD,IAAI,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,UAAU,CAAC,IAAI,CAAC;gBACZ,MAAM,EAAE,2CAA2C,CAAC,wBAAwB;gBAC5E,QAAQ,EAAE,GAAG;gBACb,UAAU,EAAE,UAAU,CAAC,UAAU;aACpC,CAAC,CAAC;YACH,SAAS;QACb,CAAC;QACD,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACtB,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;QAChC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC/B,UAAU,CAAC,IAAI,CAAC;gBACZ,MAAM,EAAE,2CAA2C,CAAC,wBAAwB;gBAC5E,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,YAAY,EAAE,IAAI,CAAC,YAAY;gBAC/B,mBAAmB,EAAE,IAAI,CAAC,mBAAmB;aAChD,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IAED,OAAO,UAAU,CAAC;AACtB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qCAAqC,CACjD,WAAmD;IAEnD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAqD,CAAC;IAC3E,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACnC,MAAM,GAAG,GAAG,4BAA4B,CAAC,UAAU,CAAC,CAAC;QACrD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC","sourcesContent":["import { z } from \"zod\";\nimport { initZodDecorators } from '@wildo-ai/zod-decorators';\n\ninitZodDecorators(z);\n\nimport { IndicatorVariant } from '@wildo-ai/presets-components-models';\nimport { ResourcePrimaryScope } from \"../resources/resources.shared.schemas\";\n\n\n/**\n * The one character that separates the parts of a badge KEY and a badge REFERENCE.\n *\n * Both formats are positional, so the separator may not appear inside a part or the parse is\n * ambiguous. `NotificationBadgeIdentifierSchema` refuses it in an identifier for exactly that\n * reason, and `collectNotificationBadgeDeclarationViolations` re-states the refusal at boot,\n * because a declaration object is authored in TypeScript and never `.parse()`d.\n */\nexport const NOTIFICATION_BADGE_KEY_SEPARATOR = ':';\n\n/** Any string that does not contain {@link NOTIFICATION_BADGE_KEY_SEPARATOR}. */\nexport const NOTIFICATION_BADGE_IDENTIFIER_PATTERN = /^[^:]+$/;\n\n/**\n * Notification badge identifier.\n *\n * The identifier is an open string because no canonical (core) identifier ships: the two\n * aspirational placeholders (`new messages` / `unpaid invoices`) were removed because nothing\n * produced them.\n *\n * The SURFACING is not missing. A navigation item declares `notificationBadgeRef` and the sidebar\n * renders it, and an application declares its own badges, so the open string is what an application\n * uses today. What is still absent is a FRAMEWORK-shipped identifier with a framework producer\n * behind it; when one lands, core identifiers come back as a `CoreNotificationBadgeIdentifiers`\n * enum unioned in here.\n *\n * Open, but not unconstrained: an identifier may not contain\n * {@link NOTIFICATION_BADGE_KEY_SEPARATOR}, because it is the LAST part of a badge key and of a\n * badge reference and both are positional. A definition object is authored in TypeScript and never\n * `.parse()`d, so this constraint is also re-stated as a boot check — see\n * {@link collectNotificationBadgeDeclarationViolations}.\n */\nexport const NotificationBadgeIdentifierSchema = z\n    .string()\n    .min(1, { error: 'Notification badge identifier is required' })\n    .regex(NOTIFICATION_BADGE_IDENTIFIER_PATTERN, {\n        error: `Notification badge identifier must not contain \"${NOTIFICATION_BADGE_KEY_SEPARATOR}\" — that character separates the parts of a badge key and reference`,\n    });\n\n/**\n * Notification badge scope. Tightened to USER_SELF | ORGANIZATIONS only.\n *\n * The APPLICATION variant was dropped in the polymorphism refactor\n * (`.cursor/plans/notification-badges-polymorphism-refactor.md`):\n *   - No canonical badges were ever declared at APPLICATION scope (see\n *     `notification-badges.core.definitions.ts`).\n *   - The two surviving variants (USER + ORG) each own their own resource type\n *     and MongoDB collection. Allowing APPLICATION here would let consumers\n *     write a payload that no resource configuration / collection accepts.\n *\n * `WS_BadgeUpdatePayload` semantics are unchanged — the dispatcher in\n * `NotificationBadgeBackendService.emitBadgeUpdate` still routes USER badges to\n * `sendToUser` and ORG badges to `sendToOrganization`.\n */\nexport const NotificationScopeSchema = z.enum([\n    ResourcePrimaryScope.USER_SELF,\n    ResourcePrimaryScope.ORGANIZATIONS,\n]);\n\n/**\n * @wildo_source:part:start saas.models.notifications.badge-vocabularies facet:layer:shared facet:audience:app-developer\n *\n * The four vocabularies a badge definition picks from: how its count is CALCULATED, how it is\n * PRESENTED, whether it draws attention, and — for a stored counter — what an operation does to it.\n *\n * ⚠️ **Choosing the source kind wrongly produces a number that DRIFTS.** Reach for `EVENT_COUNTER`\n * only when the count is a fact the badge itself owns (\"unread messages\": arrive → increment, seen →\n * reset). For any quantity derived from data an operation could change by another route — incomplete\n * todos, unpaid invoices — use `DERIVED_QUERY`, which recomputes a live aggregate. A stored counter\n * on a derived quantity is right on the day it is written and wrong thereafter.\n *\n * An `EVENT_COUNTER` badge additionally needs `notificationBadgeOperations` declared on the\n * operations that move it; a `DERIVED_QUERY` badge needs none, because the recompute hangs off the\n * source resource's own mutations.\n */\nexport enum NotificationBadgeOperation {\n    INCREMENT = 'increment',\n    DECREMENT = 'decrement',\n    SET = 'set',\n    RESET = 'reset',\n}\n\n/**\n * How a badge's count is CALCULATED — the load-bearing distinction (R1).\n *\n * - `EVENT_COUNTER`: a stored counter mutated imperatively on domain events\n *   (arrive → increment, seen → reset). Correct for \"unread messages\" style\n *   badges. The count lives in the badge document.\n * - `DERIVED_QUERY`: the count is a LIVE aggregate over a resource collection\n *   (`count(resourceType where filter, scoped)`), recomputed on that resource's\n *   mutations. Correct for \"incomplete todos\" / \"unpaid invoices\" — quantities\n *   derived from data that would DRIFT if tracked with a stored counter.\n */\nexport enum NotificationBadgeSourceKind {\n    EVENT_COUNTER = 'event_counter',\n    DERIVED_QUERY = 'derived_query',\n}\n\n/** How the badge is presented. `NONE` = suppressed even when the count is > 0. */\nexport enum NotificationBadgeDisplayMode {\n    /** A colored signal dot (\"≥ 1\"), no number. */\n    DOT = 'dot',\n    /** The numeric count (truncated at the display cap). */\n    COUNT = 'count',\n    /** Rendered as nothing (count still computed/available). */\n    NONE = 'none',\n}\n\n/**\n * WHETHER / WHEN a badge draws attention. The LOOK of the pulse is theme-owned\n * (`UIBehaviorRecipe.motion.attention`), so a definition only declares intent.\n */\nexport enum NotificationBadgePulse {\n    NONE = 'none',\n    /** Transitional — pulse briefly when the count rises (recommended). */\n    ON_INCREASE = 'on_increase',\n    /** Persistent — pulse while the count is > 0. */\n    WHILE_ACTIVE = 'while_active',\n}\n/** @wildo_source:part:end saas.models.notifications.badge-vocabularies */\n\n/** EVENT_COUNTER source — no extra config; the stored counter is the truth. */\nexport const NotificationBadgeEventCounterSourceSchema = z.object({\n    kind: z.literal(NotificationBadgeSourceKind.EVENT_COUNTER),\n});\n\n/**\n * DERIVED_QUERY source — the count is `count(resourceType where filter)` with the\n * scope bound via `scopeField` (the FK field on the counted resource that equals\n * the badge's `scopeId`, e.g. `userId` for a USER_SELF badge). Recomputed by the\n * backend on any mutation of `resourceType` (see backend R5).\n */\nexport const NotificationBadgeDerivedQuerySourceSchema = z.object({\n    kind: z.literal(NotificationBadgeSourceKind.DERIVED_QUERY),\n    resourceType: z.string().min(1, { error: 'Derived-badge resourceType is required' }),\n    filter: z.record(z.string(), z.unknown()),\n    scopeField: z.string().min(1, { error: 'Derived-badge scopeField is required' }),\n});\n\n/** Discriminated union over the calculation kinds. */\nexport const NotificationBadgeSourceSchema = z.discriminatedUnion('kind', [\n    NotificationBadgeEventCounterSourceSchema,\n    NotificationBadgeDerivedQuerySourceSchema,\n]);\n\n/**\n * Presentation declaration. `tone` reuses the design-system `IndicatorVariant`\n * (single source — the `Badge` component maps the same enum). `pulse` is a\n * trigger only; the theme owns the animation.\n */\nexport const NotificationBadgeDisplaySchema = z.object({\n    mode: z.enum(NotificationBadgeDisplayMode).default(NotificationBadgeDisplayMode.COUNT),\n    tone: z.enum(IndicatorVariant).default(IndicatorVariant.NEUTRAL),\n    pulse: z.enum(NotificationBadgePulse).default(NotificationBadgePulse.NONE),\n});\n\n/**\n * Badge IDENTITY — the (identifier, scope) tuple shared by the declaration and\n * the persisted document. Kept separate so the stored badge doc does NOT absorb\n * declaration-only fields (`source` / `display`).\n */\nconst NotificationBadgeIdentitySchema = z.object({\n    identifier: NotificationBadgeIdentifierSchema,\n    scope: NotificationScopeSchema,\n});\n\n/**\n * Badge DEFINITION — the declaration app/framework authors register: identity +\n * how the count is calculated (`source`) + how it is presented (`display`).\n */\nexport const NotificationBadgeDefinitionSchema = NotificationBadgeIdentitySchema.extend({\n    source: NotificationBadgeSourceSchema,\n    display: NotificationBadgeDisplaySchema,\n});\n\nconst NotificationBadgeBaseSchema = NotificationBadgeIdentitySchema.extend({\n    // A compact badge without its application-defined identifier is not interpretable: callers\n    // could see a number but not what the number counts. Override the identity field here (rather\n    // than decorating NotificationBadgeIdentitySchema) so persisted API rows gain summary metadata\n    // while application-authored badge definitions remain a plain declaration schema.\n    identifier: NotificationBadgeIdentifierSchema.isSummaryField(),\n    // `isPrimaryKey` (composite: excludeFromCreate + isHidden + isUnique + isDBIndexed) —\n    // the server generates `_id`, so it must NOT be required on the create DTO. Using bare\n    // `.isDBIndexed()` here left `_id` create-required, which failed the dispatcher-driven\n    // badge materialization (`buildNewBadge` supplies no `_id`).\n    _id: z.string().min(1, { error: 'Notification badge ID is required' }).isPrimaryKey(),\n    count: z.number().min(0, { error: 'Notification badge count must be greater than or equal to 0' }).isSummaryField(),\n    createdAt: z.date().default(() => new Date()).isDBIndexed(),\n    updatedAt: z.date().default(() => new Date()).isDBIndexed().isSummaryField(),\n});\n\nexport const NotificationBadgeOrganizationSchema = NotificationBadgeBaseSchema.extend({\n    scope: z.literal(ResourcePrimaryScope.ORGANIZATIONS),\n    organizationId: z.string().min(1, { error: 'Organization ID is required' }).isDBIndexed().isForeignKey(),\n});\n\nexport const NotificationBadgeUserSelfSchema = NotificationBadgeBaseSchema.extend({\n    scope: z.literal(ResourcePrimaryScope.USER_SELF),\n    userId: z.string().min(1, { error: 'User ID is required' }).isDBIndexed().isForeignKey(),\n});\n\n/**\n * Discriminated union over the two surviving badge scopes (USER_SELF / ORGANIZATIONS).\n * The APPLICATION variant was dropped — see `NotificationScopeSchema` JSDoc above.\n */\nexport const NotificationBadgeSchema = z.discriminatedUnion('scope', [\n    NotificationBadgeOrganizationSchema,\n    NotificationBadgeUserSelfSchema,\n]);\n\nexport type NotificationBadgeDefinition = z.infer<typeof NotificationBadgeDefinitionSchema>;\nexport type NotificationBadgeIdentifier = z.infer<typeof NotificationBadgeIdentifierSchema>;\nexport type NotificationScope = z.infer<typeof NotificationScopeSchema>;\nexport type NotificationBadge = z.infer<typeof NotificationBadgeSchema>;\nexport type NotificationBadgeSource = z.infer<typeof NotificationBadgeSourceSchema>;\nexport type NotificationBadgeDerivedQuerySource = z.infer<typeof NotificationBadgeDerivedQuerySourceSchema>;\nexport type NotificationBadgeDisplay = z.infer<typeof NotificationBadgeDisplaySchema>;\n\n\n// ════════════════════════════════════════════════════════════════\n// Badge IDENTITY — the one place the key and reference formats live\n// ════════════════════════════════════════════════════════════════\n\n/**\n * A badge KEY: `<scope>:<identifier>` — the DEFINITION's identity, and the only thing that may be\n * used to look a definition up.\n *\n * ## Why the identifier alone is not an identity\n *\n * A definition is `(scope, identifier)`. Nothing ever stopped two definitions declaring the same\n * `identifier` at different scopes, and until this type existed every lookup matched on the\n * identifier alone — so the second definition was unreachable and silently shared the first's\n * count. The key makes both reachable and makes the collision that DOES matter (two definitions at\n * one scope and identifier) something a boot check can refuse.\n *\n * ## Why `scopeId` is NOT in the key\n *\n * `scopeId` says WHOSE badge — a user id, an organization id. It is per-viewer instance data that a\n * navigation declaration cannot possibly carry, and a browser session only ever receives pushes for\n * its own scope ids (the backend routes USER badges to that user's socket and ORG badges to that\n * organization's room). So the key is what a DECLARATION can name, and the reference below is what\n * an INSTANCE is addressed by.\n */\nexport type NotificationBadgeKey = string;\n\n/**\n * A badge REFERENCE: `<scope>:<scopeId>:<identifier>` — one badge ROW, on the wire.\n *\n * Carried by `WS_BadgeUpdatePayload.badgeReference` because emission needs the scopeId to route.\n * The browser reduces it to a {@link NotificationBadgeKey} on arrival via\n * {@link notificationBadgeKeyFromReference}, which is what makes the store's key and the navigation\n * item's lookup the same key rather than two conventions that agree by luck.\n */\nexport type NotificationBadgeReference = string;\n\n/** Build the DEFINITION-identity key from its parts. */\nexport function buildNotificationBadgeKey(\n    scope: NotificationScope,\n    identifier: NotificationBadgeIdentifier,\n): NotificationBadgeKey {\n    return `${scope}${NOTIFICATION_BADGE_KEY_SEPARATOR}${identifier}`;\n}\n\n/**\n * The key of a definition (or of anything else carrying a badge identity, such as a persisted row).\n *\n * Takes the identity fields rather than the whole definition so a `NotificationBadge` row and a\n * `NotificationBadgeDefinition` resolve through the SAME function — a second copy for the row shape\n * is how the two come to disagree.\n */\nexport function notificationBadgeIdentityKey(\n    identity: Pick<NotificationBadgeDefinition, 'scope' | 'identifier'>,\n): NotificationBadgeKey {\n    return buildNotificationBadgeKey(identity.scope, identity.identifier);\n}\n\n/**\n * Parse a key, returning `null` when it is not a well-formed key at a SUPPORTED scope.\n *\n * The scope check is not cosmetic: the APPLICATION variant was dropped in the polymorphism refactor\n * and no resource type backs it, so `application:foo` must fail here rather than reach a dispatch\n * that has no repository for it.\n */\nexport function parseNotificationBadgeKey(\n    key: string,\n): { scope: NotificationScope; identifier: NotificationBadgeIdentifier } | null {\n    const parts = key.split(NOTIFICATION_BADGE_KEY_SEPARATOR);\n    if (parts.length !== 2) return null;\n    const [scope, identifier] = parts;\n    if (!isSupportedNotificationBadgeScope(scope) || identifier.length === 0) return null;\n    return { scope, identifier };\n}\n\n/** Build the INSTANCE address carried on the wire. */\nexport function buildNotificationBadgeReference(\n    scope: NotificationScope,\n    scopeId: string,\n    identifier: NotificationBadgeIdentifier,\n): NotificationBadgeReference {\n    return `${scope}${NOTIFICATION_BADGE_KEY_SEPARATOR}${scopeId}${NOTIFICATION_BADGE_KEY_SEPARATOR}${identifier}`;\n}\n\n/** Parse a wire reference, returning `null` for a malformed one or an unsupported scope. */\nexport function parseNotificationBadgeReference(\n    reference: string,\n): { scope: NotificationScope; scopeId: string; identifier: NotificationBadgeIdentifier } | null {\n    const parts = reference.split(NOTIFICATION_BADGE_KEY_SEPARATOR);\n    if (parts.length !== 3) return null;\n    const [scope, scopeId, identifier] = parts;\n    if (!isSupportedNotificationBadgeScope(scope) || scopeId.length === 0 || identifier.length === 0) return null;\n    return { scope, scopeId, identifier };\n}\n\n/**\n * Reduce a wire reference to the DEFINITION key it addresses — the one hop the browser badge store\n * takes, so that what it keys on is what a navigation item resolves against.\n */\nexport function notificationBadgeKeyFromReference(reference: string): NotificationBadgeKey | null {\n    const parsed = parseNotificationBadgeReference(reference);\n    return parsed ? buildNotificationBadgeKey(parsed.scope, parsed.identifier) : null;\n}\n\n/** Whether a raw string names one of the two surviving badge scopes. */\nexport function isSupportedNotificationBadgeScope(scope: string): scope is NotificationScope {\n    return scope === ResourcePrimaryScope.USER_SELF || scope === ResourcePrimaryScope.ORGANIZATIONS;\n}\n\n// ════════════════════════════════════════════════════════════════\n// Declaration coherence — checked at CONFIGURATION time\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Why a badge declaration is refused. A closed vocabulary with a named runtime source, so a\n * diagnostic can be branched on and each member can carry its own explanation.\n */\nexport enum NotificationBadgeDeclarationViolationReason {\n    /**\n     * Two definitions declare the same `(scope, identifier)`. Every lookup resolves the FIRST, so\n     * the second is unreachable while silently sharing the first's count — the shape that made\n     * identifier-only lookup unsafe in the first place. Two definitions at DIFFERENT scopes are\n     * fine and are exactly what the key makes reachable.\n     */\n    DUPLICATE_DEFINITION_KEY = 'duplicate_definition_key',\n    /**\n     * An identifier contains the key separator, which would make its key and every reference built\n     * from it parse into the wrong parts. Refused rather than escaped: a positional format with an\n     * escaping rule is a format two implementations will eventually disagree about.\n     */\n    IDENTIFIER_CONTAINS_KEY_SEPARATOR = 'identifier_contains_key_separator',\n    /** An operation declares a `badgeRef` that names no registered definition. */\n    OPERATION_REF_UNRESOLVED = 'operation_ref_unresolved',\n}\n\n/** One refused declaration, carrying enough to name the author's own file without re-deriving it. */\nexport interface NotificationBadgeDeclarationViolation {\n    reason: NotificationBadgeDeclarationViolationReason;\n    /** The badge key at issue — the definition's, or the unresolved `badgeRef` as authored. */\n    badgeKey: string;\n    /** Present when the violation belongs to a definition rather than to an operation declaration. */\n    identifier?: NotificationBadgeIdentifier;\n    /** Present when the violation belongs to an operation declaration. */\n    resourceType?: string;\n    /** Present when the violation belongs to an operation declaration. */\n    operationIdentifier?: string;\n}\n\n/** Where an operation declared a badge reference — one row per authored `notificationBadgeOperations` entry. */\nexport interface NotificationBadgeOperationDeclarationSite {\n    resourceType: string;\n    operationIdentifier: string;\n    badgeRef: string;\n}\n\n/**\n * The whole declaration-coherence check, as a pure function over what an application declared.\n *\n * Pure and shared on purpose: the backend registry runs it as a fail-closed boot gate and the\n * frontend launcher verifier reports it in development, and a second implementation is how the two\n * come to disagree about what a valid declaration is.\n *\n * It answers the question `derive-before-you-ask.md` asks — who owes this, and what says so. The\n * population is exactly the registered definitions plus every authored\n * `notificationBadgeOperations` entry; nothing is inferred and nothing is sampled.\n */\nexport function collectNotificationBadgeDeclarationViolations(\n    definitions: readonly NotificationBadgeDefinition[],\n    operationSites: readonly NotificationBadgeOperationDeclarationSite[] = [],\n): NotificationBadgeDeclarationViolation[] {\n    const violations: NotificationBadgeDeclarationViolation[] = [];\n    const seenKeys = new Set<NotificationBadgeKey>();\n\n    for (const definition of definitions) {\n        if (!NOTIFICATION_BADGE_IDENTIFIER_PATTERN.test(definition.identifier)) {\n            violations.push({\n                reason: NotificationBadgeDeclarationViolationReason.IDENTIFIER_CONTAINS_KEY_SEPARATOR,\n                badgeKey: notificationBadgeIdentityKey(definition),\n                identifier: definition.identifier,\n            });\n            // Still recorded below, so a malformed identifier declared twice is reported as both.\n        }\n\n        const key = notificationBadgeIdentityKey(definition);\n        if (seenKeys.has(key)) {\n            violations.push({\n                reason: NotificationBadgeDeclarationViolationReason.DUPLICATE_DEFINITION_KEY,\n                badgeKey: key,\n                identifier: definition.identifier,\n            });\n            continue;\n        }\n        seenKeys.add(key);\n    }\n\n    for (const site of operationSites) {\n        if (!seenKeys.has(site.badgeRef)) {\n            violations.push({\n                reason: NotificationBadgeDeclarationViolationReason.OPERATION_REF_UNRESOLVED,\n                badgeKey: site.badgeRef,\n                resourceType: site.resourceType,\n                operationIdentifier: site.operationIdentifier,\n            });\n        }\n    }\n\n    return violations;\n}\n\n/**\n * Index the registered definitions by key, so a dispatch resolves in one lookup rather than a scan.\n *\n * Built from the SAME key function the boot check uses, so a definition the boot check accepted is\n * a definition this map can serve.\n */\nexport function buildNotificationBadgeDefinitionIndex(\n    definitions: readonly NotificationBadgeDefinition[],\n): ReadonlyMap<NotificationBadgeKey, NotificationBadgeDefinition> {\n    const index = new Map<NotificationBadgeKey, NotificationBadgeDefinition>();\n    for (const definition of definitions) {\n        const key = notificationBadgeIdentityKey(definition);\n        if (!index.has(key)) index.set(key, definition);\n    }\n    return index;\n}\n"]}

package/dist/esm/notifications/notification-badges.shared.resources-config.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notification-badges.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../../src/notifications/notification-badges.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EACL,+BAA+B,EAC/B,mCAAmC,EACpC,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EACL,qBAAqB,EAGtB,MAAM,gDAAgD,CAAC;AACxD,OAAO,EAGL,oBAAoB,EACrB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,qBAAqB,EAAE,MAAM,8CAA8C,CAAC;AAOrF,KAAK,oCAAoC,GACrC,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,WAAW,CAAC;AAEtC,eAAO,MAAM,iEAAiE,GAC5E,wBAAwB,oBAAoB,EAAE,KAC7C,qBAAqB,CACtB,SAAS,EACT,oCAAoC,EACpC,OAAO,+BAA+B,CA+HtC,CAAC;AAIH,KAAK,4CAA4C,GAC7C,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,CAAC;AAEjC,eAAO,MAAM,yEAAyE,GACpF,wBAAwB,oBAAoB,EAAE,KAC7C,qBAAqB,CACtB,SAAS,EACT,4CAA4C,EAC5C,OAAO,mCAAmC,CAoF1C,CAAC"}
+{"version":3,"file":"notification-badges.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../src/notifications/notification-badges.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EACL,+BAA+B,EAC/B,mCAAmC,EACpC,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EACL,qBAAqB,EAGtB,MAAM,gDAAgD,CAAC;AACxD,OAAO,EAGL,oBAAoB,EACrB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,qBAAqB,EAAE,MAAM,8CAA8C,CAAC;AAOrF,KAAK,oCAAoC,GACrC,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,WAAW,CAAC;AAEtC,eAAO,MAAM,iEAAiE,GAC5E,wBAAwB,oBAAoB,EAAE,KAC7C,qBAAqB,CACtB,SAAS,EACT,oCAAoC,EACpC,OAAO,+BAA+B,CA+HtC,CAAC;AAIH,KAAK,4CAA4C,GAC7C,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,CAAC;AAEjC,eAAO,MAAM,yEAAyE,GACpF,wBAAwB,oBAAoB,EAAE,KAC7C,qBAAqB,CACtB,SAAS,EACT,4CAA4C,EAC5C,OAAO,mCAAmC,CAoF1C,CAAC"}

package/dist/esm/notifications/notifications.shared.schemas.d.ts

@@ -14,6 +14,56 @@ export declare enum UserNotificationLevel {
     ERROR = "error"
 }
 export declare const UserNotificationChannelSchema: z.ZodUnion<readonly [z.ZodEnum<typeof CoreUserNotificationChannel>, z.ZodString]>;
+/** @wildo_source:part:start saas.models.notifications.targets facet:layer:shared facet:audience:app-developer */
+/**
+ * WHO a declared `userNotifications` entry reaches — and, on the EMAIL channel, whether the tenant
+ * gets to redirect or silence it.
+ *
+ * Imported from `@wildo-ai/saas-models`. The target is the single most consequential field of a
+ * notification declaration, because it decides three separate things at once:
+ *
+ * 1. **the recipients** — resolved per member below;
+ * 2. **whether the recipient's own channel preference can suppress it** — only `USER_SELF` and
+ *    `USERS_CUSTOM` are suppressible, because only they reach a person about their own affairs. Every
+ *    other target reaches somebody because of a ROLE they hold, and a personal switch must not
+ *    silently disable a tenant's administrative monitoring. See
+ *    {@link userNotificationTargetIsSuppressibleByRecipientPreference};
+ * 3. **whether `userRoles` is read at all** — see {@link userNotificationTargetReadsUserRoles}. On the
+ *    two tenant-wide targets the field is REFUSED rather than ignored, because "everyone in the
+ *    tenant" is not a set a role list may narrow.
+ *
+ * ## Who each target resolves to
+ *
+ * | target | recipients |
+ * |---|---|
+ * | `USER_SELF` | the initiator of the operation |
+ * | `USERS_CUSTOM` | whatever your `userIdsSelector` returns. Without that function the target resolves nobody |
+ * | `ORGANIZATION`, `ORGANIZATION_USERS` | every member of the initiator's tenant. `userRoles` is refused here |
+ * | `ORGANIZATION_BILLING`, `ORGANIZATION_SECURITY`, `ORGANIZATION_USER_MANAGEMENT`, `ORGANIZATION_ADMINISTRATIVE` | members of the tenant holding `ORG_OWNER` or `ORG_ADMIN`, unless `userRoles` names a different set |
+ * | `APPLICATION_BILLING` | holders of `APP_ADMIN_BILLING_MANAGER` or `APP_ADMIN_SUPER_ADMIN`, application-wide |
+ * | `APPLICATION_ADMIN_VIEWER` | holders of `APP_ADMIN_VIEWER` or `APP_ADMIN_SUPER_ADMIN` |
+ * | every other `APPLICATION_*` | holders of `APP_ADMIN_SUPER_ADMIN` |
+ * | `INBOUND_CONTACT` | nobody, deliberately. The recipient is not a user of your application, so this target is only usable with an EMAIL notification declaring `recipientEmailField` |
+ *
+ * A target the dispatcher has no rule for resolves nobody and logs a warning — so a custom target
+ * string (the schema accepts one) sends nothing on the email and websocket paths.
+ *
+ * ## The tenant can redirect or silence an ORGANIZATION-flavoured EMAIL, and you cannot override it
+ *
+ * Each tenant owns a notification-settings record with a per-category switch and a per-category
+ * address, and the category is DERIVED from the target — `ORGANIZATION_BILLING` to `billing`,
+ * `ORGANIZATION_SECURITY` to `security`, and so on. Two consequences to design around:
+ *
+ * - **a configured address REPLACES the member fan-out**, it does not add to it. A tenant routing
+ *   security mail to a monitoring address is saying where that mail goes, not asking for a copy;
+ * - **the category switch suppresses the notification entirely**, whether or not an address is
+ *   configured. A tenant that turns billing notifications off means it for the members too.
+ *
+ * `ORGANIZATION` and `ORGANIZATION_USERS` are tenant-wide and belong to no category, so no switch can
+ * silence them; a tenant-wide default address still redirects them.
+ *
+ * This applies to EMAIL only. The websocket and in-product paths always fan out to the members.
+ */
 export declare enum CoreUserNotificationTarget {
     APPLICATION_ADMINISTRATOR = "application_administrator",
     APPLICATION_BILLING = "application_billing",
@@ -32,6 +82,48 @@ export declare enum CoreUserNotificationTarget {
     USERS_CUSTOM = "users_custom",
     INBOUND_CONTACT = "inbound_contact"
 }
+/**
+ * Whether a notification aimed at this target may be SUPPRESSED by the recipient's own channel
+ * preference (`UserPreferences.notifications.email` / `.sms` / `.push` / `.inApp`).
+ *
+ * DERIVED from the target rather than declared per notification, because the target already carries
+ * the distinction and a second field would be one more thing to get wrong on 87 declarations.
+ *
+ * `USER_SELF` and `USERS_CUSTOM` reach a PERSON about their own affairs — those are the messages a
+ * person is choosing about when they turn a channel off, and honouring that choice is the whole
+ * point of the switch existing (#409).
+ *
+ * Every other target reaches somebody because of a ROLE they hold: an application administrator, an
+ * organization's security or billing contact. A personal channel preference must not silently
+ * disable a tenant's or an application's administrative monitoring — the recipient did not choose to
+ * receive those as a person and cannot switch them off as one. A tenant that wants role mail
+ * elsewhere routes it, which is what the organization notification-settings record is for.
+ *
+ * Nothing here reaches account RECOVERY. Password reset, magic link and email verification are sent
+ * directly through the email service and never pass through the notification dispatcher, so no
+ * channel preference can lock a person out of their own account. That measurement is what made
+ * suppression safe to implement at all.
+ */
+export declare function userNotificationTargetIsSuppressibleByRecipientPreference(target: string): boolean;
+/**
+ * The targets on which `userRoles` MEANS anything (#495).
+ *
+ * `userRoles` is not a recipient FILTER, which is how its name reads and how it has been authored. It
+ * is the role-SELECTION override for the eleven role-scoped targets: `mapOrganizationTargetToRoles`
+ * and `mapApplicationTargetToRoles` take it in place of their per-target default, and nothing else
+ * anywhere reads it.
+ *
+ * On every other target it is inert, and inert in three different ways that all looked the same to an
+ * author: `USER_SELF` addresses the initiator, `USERS_CUSTOM` goes straight to `userIdsSelector`, and
+ * `ORGANIZATION`/`ORGANIZATION_USERS` mean everyone in the tenant by definition. Declaring it there
+ * is a filter that silently does nothing, which is what the refinement below now refuses.
+ *
+ * Scoped as a POSITIVE list of targets that read it rather than a rule about one target, because the
+ * defect was never specific to `USERS_CUSTOM` — refusing it there alone would leave the other three
+ * free to mislead the next author in exactly the same way.
+ */
+export declare function userNotificationTargetReadsUserRoles(target: string): boolean;
+/** @wildo_source:part:end saas.models.notifications.targets */
 export declare const UserNotificationTargetSchema: z.ZodUnion<readonly [z.ZodEnum<typeof CoreUserNotificationTarget>, z.ZodString]>;
 /**
  * How the frontend renders a celebration after a successful operation.
@@ -73,6 +165,58 @@ export declare const FrontendDisplayHintsSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type FrontendDisplayHints = z.infer<typeof FrontendDisplayHintsSchema>;
 /**
+ * @wildo_source:part:start saas.models.notifications.user-notification-definition facet:layer:shared facet:audience:app-developer
+ *
+ * One notification an operation sends. Declared as `userNotifications` on a resource operation, in
+ * the resource config — an array, so one operation may send several.
+ *
+ * ```ts
+ * userNotifications: [
+ *   { target: CoreUserNotificationTarget.USER_SELF, channel: CoreUserNotificationChannel.EMAIL,
+ *     condition: ({ currentObject }) => currentObject.status === 'INVITED' },
+ *   { target: CoreUserNotificationTarget.ORGANIZATION_USERS, channel: CoreUserNotificationChannel.WEBSOCKET },
+ * ]
+ * ```
+ *
+ * ## What actually sends
+ *
+ * `EMAIL`, `WEBSOCKET` and `FRONT_END_SUCCESS` deliver. **`SMS` and `PUSH` are declaration vocabulary
+ * only** — the dispatcher's branch for them logs and returns without sending. The framework does have
+ * an SMS transport (authentication's one-time codes use it) and this dispatcher is not wired to it,
+ * so declaring an SMS notification is inert rather than pending.
+ *
+ * For an EMAIL, create the template directory the reference names. The startup validator resolves
+ * every declared reference through the configured locale chain before the application takes traffic,
+ * and prints the exact directory to create when one is missing.
+ *
+ * ## The recipient's preferences are honoured, and three things override them
+ *
+ * A recipient who has switched a channel off does not receive it. Three deliberate exceptions:
+ *
+ *  - a ROLE-addressed target — the recipient did not choose to receive it as a person;
+ *  - `alwaysDeliver: true` — declare it on a security notice a compromised account's owner must still
+ *    receive;
+ *  - a recipient with NO preferences row at all, because preferences are created lazily and a missing
+ *    record must never read as "everything off".
+ *
+ * The `inApp` switch governs the notification CENTRE on the frontend rather than the socket frame —
+ * suppressing the frame would also suppress the live UI updates that ride the same channel.
+ *
+ * ## `condition` gates the notification, not the operation
+ *
+ * The predicate goes on the notification. It decides only whether this one message is sent; refusing
+ * the CALL is a separate declaration on the operation variant, and the two are independent — a
+ * variant can be enabled while its notification is gated off, and the reverse. The form deliberately
+ * matches an operation variant's `enabledCondition` so both read the same way.
+ *
+ * ## Emailing somebody who is not a user
+ *
+ * `recipientEmailField` names a TOP-LEVEL field on the record holding the address. There is no
+ * recipient, so there are no recipient preferences and no recipient language: the message goes out in
+ * the application's default locale. A nested address cannot be named, nor a list — the path sends
+ * exactly one message per notification. Pair it with a `condition` when the same operation also
+ * serves rows whose address belongs to somebody who must not be written to.
+ *
  * Base fields shared by all user notification channel variants.
  */
 export declare const UserNotificationDefinition_BaseSchema: z.ZodObject<{
@@ -132,6 +276,7 @@ export declare const UserNotificationDefinition_BaseSchema: z.ZodObject<{
         };
     }) => boolean>>;
     customNotificationRef: z.ZodOptional<z.ZodString>;
+    alwaysDeliver: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 /** EMAIL channel — template-oriented (email-specific fields handled by email templates) */
 export declare const UserNotificationDefinition_EmailSchema: z.ZodObject<{
@@ -191,6 +336,7 @@ export declare const UserNotificationDefinition_EmailSchema: z.ZodObject<{
         };
     }) => boolean>>;
     customNotificationRef: z.ZodOptional<z.ZodString>;
+    alwaysDeliver: z.ZodOptional<z.ZodBoolean>;
     channel: z.ZodLiteral<CoreUserNotificationChannel.EMAIL>;
     recipientEmailField: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
@@ -252,6 +398,7 @@ export declare const UserNotificationDefinition_WebSocketSchema: z.ZodObject<{
         };
     }) => boolean>>;
     customNotificationRef: z.ZodOptional<z.ZodString>;
+    alwaysDeliver: z.ZodOptional<z.ZodBoolean>;
     channel: z.ZodLiteral<CoreUserNotificationChannel.WEBSOCKET>;
 }, z.core.$strip>;
 /**
@@ -329,6 +476,7 @@ export declare const UserNotificationDefinition_FrontEndSuccessSchema: z.ZodObje
         };
     }) => boolean>>;
     customNotificationRef: z.ZodOptional<z.ZodString>;
+    alwaysDeliver: z.ZodOptional<z.ZodBoolean>;
     channel: z.ZodLiteral<CoreUserNotificationChannel.FRONT_END_SUCCESS>;
     celebration: z.ZodOptional<z.ZodObject<{
         mode: z.ZodDefault<z.ZodEnum<typeof CelebrationDisplayMode>>;
@@ -396,6 +544,7 @@ export declare const UserNotificationDefinition_SMSSchema: z.ZodObject<{
         };
     }) => boolean>>;
     customNotificationRef: z.ZodOptional<z.ZodString>;
+    alwaysDeliver: z.ZodOptional<z.ZodBoolean>;
     channel: z.ZodLiteral<CoreUserNotificationChannel.SMS>;
 }, z.core.$strip>;
 /** PUSH channel — not yet implemented, plain base */
@@ -456,6 +605,7 @@ export declare const UserNotificationDefinition_PushSchema: z.ZodObject<{
         };
     }) => boolean>>;
     customNotificationRef: z.ZodOptional<z.ZodString>;
+    alwaysDeliver: z.ZodOptional<z.ZodBoolean>;
     channel: z.ZodLiteral<CoreUserNotificationChannel.PUSH>;
 }, z.core.$strip>;
 /** Catch-all for custom channels (any string not matching core channels) */
@@ -516,6 +666,7 @@ export declare const UserNotificationDefinition_CustomChannelSchema: z.ZodObject
         };
     }) => boolean>>;
     customNotificationRef: z.ZodOptional<z.ZodString>;
+    alwaysDeliver: z.ZodOptional<z.ZodBoolean>;
     channel: z.ZodString;
 }, z.core.$strip>;
 /**
@@ -581,6 +732,7 @@ export declare const UserNotificationDefinitionSchema: z.ZodUnion<readonly [z.Zo
         };
     }) => boolean>>;
     customNotificationRef: z.ZodOptional<z.ZodString>;
+    alwaysDeliver: z.ZodOptional<z.ZodBoolean>;
     channel: z.ZodLiteral<CoreUserNotificationChannel.EMAIL>;
     recipientEmailField: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
@@ -640,6 +792,7 @@ export declare const UserNotificationDefinitionSchema: z.ZodUnion<readonly [z.Zo
         };
     }) => boolean>>;
     customNotificationRef: z.ZodOptional<z.ZodString>;
+    alwaysDeliver: z.ZodOptional<z.ZodBoolean>;
     channel: z.ZodLiteral<CoreUserNotificationChannel.WEBSOCKET>;
 }, z.core.$strip>, z.ZodObject<{
     identifier: z.ZodString;
@@ -698,6 +851,7 @@ export declare const UserNotificationDefinitionSchema: z.ZodUnion<readonly [z.Zo
         };
     }) => boolean>>;
     customNotificationRef: z.ZodOptional<z.ZodString>;
+    alwaysDeliver: z.ZodOptional<z.ZodBoolean>;
     channel: z.ZodLiteral<CoreUserNotificationChannel.FRONT_END_SUCCESS>;
     celebration: z.ZodOptional<z.ZodObject<{
         mode: z.ZodDefault<z.ZodEnum<typeof CelebrationDisplayMode>>;
@@ -763,6 +917,7 @@ export declare const UserNotificationDefinitionSchema: z.ZodUnion<readonly [z.Zo
         };
     }) => boolean>>;
     customNotificationRef: z.ZodOptional<z.ZodString>;
+    alwaysDeliver: z.ZodOptional<z.ZodBoolean>;
     channel: z.ZodLiteral<CoreUserNotificationChannel.SMS>;
 }, z.core.$strip>, z.ZodObject<{
     identifier: z.ZodString;
@@ -821,6 +976,7 @@ export declare const UserNotificationDefinitionSchema: z.ZodUnion<readonly [z.Zo
         };
     }) => boolean>>;
     customNotificationRef: z.ZodOptional<z.ZodString>;
+    alwaysDeliver: z.ZodOptional<z.ZodBoolean>;
     channel: z.ZodLiteral<CoreUserNotificationChannel.PUSH>;
 }, z.core.$strip>, z.ZodObject<{
     identifier: z.ZodString;
@@ -879,9 +1035,11 @@ export declare const UserNotificationDefinitionSchema: z.ZodUnion<readonly [z.Zo
         };
     }) => boolean>>;
     customNotificationRef: z.ZodOptional<z.ZodString>;
+    alwaysDeliver: z.ZodOptional<z.ZodBoolean>;
     channel: z.ZodString;
 }, z.core.$strip>]>;
 export type UserNotificationDefinition = z.infer<typeof UserNotificationDefinitionSchema>;
+/** @wildo_source:part:end saas.models.notifications.user-notification-definition */
 /**
  * M2M Notification Channels
  */