@wildo-ai/saas-models 1.1.5 → 1.1.6

package/dist/esm/notifications/m2m/webhook-config.shared.schemas.js

@@ -105,8 +105,21 @@ export const M2M_WEBHOOK_SCOPE_VARIANTS = [
  * derived `applicationPublicKeyPem` field.
  */
 export const WebhookEndpointSchema = z.object({
-    /** Stable per-endpoint identifier (ULID). Used as the `endpointId` FK on every delivery log row. */
-    id: z.string().min(1),
+    /**
+     * Stable per-endpoint identifier. Used as the `endpointId` FK on every delivery log row, and the
+     * key the UPDATE path matches an incoming endpoint to its stored self by (#1801).
+     *
+     * ASSIGNED BY THE SERVER when an endpoint is saved without one — which is how a new endpoint
+     * arrives from the settings pane, whose array editor seeds a new item's string fields with `''`.
+     * That is why blank is admitted here rather than refused: `min(1)` made the settings pane unable
+     * to add an endpoint at all, and an id is not something an administrator should have to invent.
+     * A caller that supplies its own id keeps it. Duplicate ids are refused on `endpoints` below.
+     */
+    id: z
+        .string()
+        .max(128)
+        .isNotEditable()
+        .describe('Identifies the endpoint. Delivery-log entries and endpoint tests name the endpoint by this id. Assigned by the server when a new endpoint is saved without one; an existing endpoint keeps its id.'),
     /**
      * Destination URL receiving POST deliveries.
      *
@@ -128,14 +141,42 @@ export const WebhookEndpointSchema = z.object({
      * link-local address is refused regardless of scheme, because a signed POST to an instance-metadata
      * service is a read primitive rather than a delivery.
      */
-    url: z.url(),
+    url: z
+        .url()
+        .describe('Where deliveries are sent, as a signed POST. Use `https://`: over `http://` the signature token travels in the clear. A destination that resolves to a private or link-local address is refused when a delivery is sent (outside production, loopback is allowed).'),
     /** Free-form admin label (visible in the management UI). */
-    description: z.string().max(500).default(''),
+    description: z.string().max(500).default('').describe('A label for the endpoint, shown to administrators. At most 500 characters; empty by default.'),
     /** Per-endpoint master switch — disabled endpoints are skipped by the dispatcher. */
-    enabled: z.boolean().default(true),
-    createdAt: z.date().default(() => new Date()),
-    updatedAt: z.date().default(() => new Date()),
+    enabled: z.boolean().default(true).describe('When `false`, deliveries skip this endpoint. It can still be tested. Defaults to `true`.'),
+    /**
+     * When this endpoint was added. SERVER-STAMPED (#1801): the UPDATE path keeps the stored value for
+     * an endpoint it recognises by `id` and stamps the save instant for a new one, whatever the request
+     * carries — the array is written whole, so a client that omitted or edited this field would
+     * otherwise reset or rewrite it.
+     *
+     * Why not `.excludeFromCreate().excludeFromUpdate()`: those strip TOP-LEVEL request fields only
+     * (`applyUpdateOmissionsToSchema` does not descend into array items), so on an item they would
+     * read as protection and enforce nothing. `.isNotEditable()` is what the item editor honours; the
+     * server stamp is what makes the value true.
+     */
+    createdAt: z
+        .date()
+        .default(() => new Date())
+        .isNotEditable()
+        .describe('When the endpoint was added. Set by the server; a value sent by the client is ignored.'),
+    /** When any setting of this endpoint last changed. SERVER-STAMPED, see {@link createdAt}. */
+    updatedAt: z
+        .date()
+        .default(() => new Date())
+        .isNotEditable()
+        .describe('When the endpoint\'s URL, description or switch last changed. Set by the server; a value sent by the client is ignored. Saving other endpoints does not change it.'),
 });
+/**
+ * The endpoint fields a CLIENT authors — every field except the identity and the two server-stamped
+ * timestamps. The UPDATE path compares these to decide whether an endpoint changed, so a field added
+ * to {@link WebhookEndpointSchema} tomorrow counts as a change without anyone remembering to list it.
+ */
+export const WEBHOOK_ENDPOINT_SERVER_OWNED_FIELDS = ['id', 'createdAt', 'updatedAt'];
 /**
  * Whether a destination is reached over PLAINTEXT HTTP, so the signature JWT travels in the clear.
  *
@@ -147,9 +188,10 @@ export const WebhookEndpointSchema = z.object({
  * it. A refusal can live in one place because it stops the request; a TOLERATED condition is
  * observed by several, and those several must agree.
  *
- * Read by the write path (which warns and audits) and by the endpoint probe (which reports it to
- * the admin who pressed "test"). Both are listed here so the next reader can tell whether adding a
- * third is joining a mechanism or starting a second one.
+ * Read by the UPDATE path (which logs a warning naming the destination host when a plaintext endpoint
+ * is saved) and by the endpoint probe (which reports it to the admin who pressed "test"). Both are
+ * listed here so the next reader can tell whether adding a third is joining a mechanism or starting
+ * a second one.
  *
  * Scheme comparison, not a `startsWith`: `WHATWG` lowercases the scheme during parsing, so
  * `HTTP://example.test` and `http://example.test` are the same destination and a prefix test would
@@ -187,8 +229,31 @@ export const WebhookConfigBaseSchema = z.object({
     _id: z.string().min(1).isPrimaryKey().isSummaryField(),
     /** Master kill-switch — when `false`, the dispatcher short-circuits with no deliveries. */
     enabled: z.boolean().default(false).isSummaryField(),
-    /** Admin-managed list of destinations. Empty array = no deliveries even when `enabled: true`. */
-    endpoints: z.array(WebhookEndpointSchema).default([]),
+    /**
+     * Admin-managed list of destinations. Empty array = no deliveries even when `enabled: true`.
+     *
+     * Ids must be unique: the UPDATE path matches endpoints by id to carry their timestamps forward,
+     * delivery-log rows name their endpoint by id, and `testEndpoint` selects one by id — a duplicate
+     * would make all three pick an arbitrary one of the two. Blank ids are exempt, because the server
+     * assigns them on save (see `WebhookEndpointSchema.id`).
+     */
+    // The refinement sits on the ARRAY, before `.default([])`: the request-DTO builder rebuilds a
+    // default-wrapped field from its inner type, so a check on the wrapper never reached a request and a
+    // PUT with two `"same"` ids was accepted (#1801 review M1).
+    endpoints: z
+        .array(WebhookEndpointSchema)
+        .superRefine((endpoints, ctx) => {
+        const seen = new Set();
+        endpoints.forEach((endpoint, index) => {
+            if (!endpoint.id)
+                return;
+            if (seen.has(endpoint.id)) {
+                ctx.addIssue({ code: 'custom', path: [index, 'id'], message: `Two endpoints share the id "${endpoint.id}". Each endpoint needs its own id.` });
+            }
+            seen.add(endpoint.id);
+        });
+    })
+        .default([]),
     /**
      * Derived field — populated by `postfixCoreOperations[READ]` from
      * `appConfig.jwtConfig.config.publicKey[JwtPrivateKeys.APPLICATION_WEBHOOK]`.

package/dist/esm/notifications/m2m/webhook-config.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhook-config.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/notifications/m2m/webhook-config.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * M2M Webhook Config Schema (Shared) — Polymorphic dual-scope\n *\n * Configures outbound webhook delivery for M2M notifications fired by\n * resource operations carrying a `WEBHOOK_ORGANIZATION` or\n * `WEBHOOK_APPLICATION` channel in their spec. Holds:\n *   - a master `enabled` switch\n *   - an array of admin-managed endpoints (URL + description + per-endpoint enabled flag)\n *   - a derived `applicationPublicKeyPem` (READ-only, populated by a\n *     postfix hook from `JwtPrivateKeys.APPLICATION_WEBHOOK` so external\n *     consumers can verify our JWT-signed deliveries)\n *\n * Scope FK (`organizationId` / `applicationId`) is injected by the\n * polymorphism engine — NOT declared on the base schema.\n *\n * @see m2m-webhook-organization-delivery.md — Phase 2 / Step 3\n * @see security/authentications/siem/siem-export-config.shared.schemas.ts\n *   for the dual-scope polymorphic precedent this mirrors.\n */\n\nimport { z } from 'zod';\nimport {\n  CoreResourceType,\n  coreResourceShared_FieldIdentifier,\n} from '../../resources/resources.shared.core.definitions';\nimport {\n  declarePolymorphicSchemas,\n  type PolymorphicVariantDefinition,\n} from '../../resources/utils/resource-polymorphism.schemas';\n\n// =============================================================================\n// ENDPOINT PROBE VOCABULARY\n// =============================================================================\n\n/**\n * Verdict of a single synthetic delivery fired by `webhookConfig.testEndpoint`.\n * A probe that cannot fail is worse than no probe, so every terminal state an\n * outbound attempt can reach is named here rather than collapsed into a boolean.\n *\n * The transport verdict and the HTTP status are deliberately SEPARATE axes:\n * `REJECTED` still carries a response status, because \"the endpoint answered 403\"\n * and \"the endpoint never answered\" are different problems with different fixes.\n *\n * Declared in this light schema module (not alongside the operation DTO) so the\n * audit-event vocabulary can name the same enum without pulling the resource-config\n * factory graph into `auditable-events.shared.schema.ts`.\n */\nexport enum WebhookEndpointProbeOutcome {\n  /**\n   * The endpoint answered with 2xx. This is the only outcome that evidences\n   * consumer-side signature verification: the platform cannot observe the\n   * consumer's verification step directly, so a 2xx from an endpoint that\n   * verifies before responding is the available proof.\n   */\n  ACCEPTED = 'accepted',\n  /** The endpoint answered, but not with 2xx. Reachable; it refused or errored. */\n  REJECTED = 'rejected',\n  /** No HTTP response at all — DNS/TLS/connection failure, or the attempt timed out. */\n  UNREACHABLE = 'unreachable',\n  /**\n   * Nothing left the platform. The payload could not be signed, which is an\n   * operator-side key/configuration fault, not a statement about the endpoint.\n   * Reported distinctly so an admin never reads a local misconfiguration as a\n   * broken customer endpoint.\n   */\n  NOT_SENT = 'not_sent',\n}\n\n// =============================================================================\n// SHARED VARIANT DEFINITIONS\n// =============================================================================\n\n/**\n * The 2 M2M webhook scope variants — shared by `WebhookConfig` and\n * `M2MWebhookDeliveryLog`. Centralised here so both polymorphic\n * declarations stay in lock-step.\n *\n * Notes:\n * - We deliberately define a domain-local constant (mirroring\n *   `BILLING_SCOPE_VARIANTS` in the billing domain) instead of reusing\n *   `AUTH_SCOPE_VARIANTS` from `authentications/`. The variant *shape*\n *   is identical — `(ORGANIZATIONS, APPLICATION)` with `isPrimaryScope:\n *   true` — but the auth constant is documented as \"shared across all\n *   AUTH polymorphic resources\" and webhooks are notification resources,\n *   not auth resources. Keeping a domain-local constant prevents the\n *   semantic drift the framework-mindset rule warns about.\n * - Both variants are primary scopes: there is no \"child of an\n *   organization unit\" or \"child of a user\" variant — webhooks are a\n *   tenant-level concern, not an entity-attached one.\n */\nexport const M2M_WEBHOOK_SCOPE_VARIANTS: PolymorphicVariantDefinition[] = [\n  {\n    parentResourceType: CoreResourceType.ORGANIZATIONS,\n    parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.ORGANIZATIONS],\n    isPrimaryScope: true,\n  },\n  {\n    parentResourceType: CoreResourceType.APPLICATION,\n    parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.APPLICATION],\n    isPrimaryScope: true,\n  },\n];\n\n// =============================================================================\n// ENDPOINT SUB-SCHEMA\n// =============================================================================\n\n/**\n * A single admin-configured webhook destination.\n *\n * v1 deliberately keeps endpoint config minimal (URL + description +\n * enabled flag) — per user direction: \"as a first implementation, we\n * need just an url and a description, not more.\" Per-endpoint secrets\n * are NOT used: signing happens with a single per-application JWT\n * private key (`JwtPrivateKeys.APPLICATION_WEBHOOK`) and consumers\n * verify with the matching public key surfaced via the parent config's\n * derived `applicationPublicKeyPem` field.\n */\nexport const WebhookEndpointSchema = z.object({\n  /** Stable per-endpoint identifier (ULID). Used as the `endpointId` FK on every delivery log row. */\n  id: z.string().min(1),\n  /**\n   * Destination URL receiving POST deliveries.\n   *\n   * ## `http://` IS ACCEPTED, AND WHAT THAT COSTS YOU (#492, decided 2026-09-08)\n   *\n   * Every delivery carries a **signature JWT in the request**. That JWT is a credential: it is what\n   * proves to your endpoint that the delivery came from this application. Over plaintext it is\n   * readable by anyone on the network path between us and you, and replayable against your endpoint\n   * until it expires — so an observer of one delivery can forge the next one.\n   *\n   * **Use `https://`.** Plaintext is admitted because refusing it would break endpoints already\n   * configured under a framework that accepted them, not because it is safe. That is a commercial\n   * accommodation, deliberately taken, and it is not an assessment that `http://` is fine here.\n   *\n   * The sibling agent push-notification caller requires HTTPS unconditionally, and the same argument\n   * applies to this field; the two differ only in whether anyone has already authored against them.\n   *\n   * Note the URL is also SSRF-guarded at delivery time — a destination resolving to a private or\n   * link-local address is refused regardless of scheme, because a signed POST to an instance-metadata\n   * service is a read primitive rather than a delivery.\n   */\n  url: z.url(),\n  /** Free-form admin label (visible in the management UI). */\n  description: z.string().max(500).default(''),\n  /** Per-endpoint master switch — disabled endpoints are skipped by the dispatcher. */\n  enabled: z.boolean().default(true),\n  createdAt: z.date().default(() => new Date()),\n  updatedAt: z.date().default(() => new Date()),\n});\n\nexport type WebhookEndpoint = z.infer<typeof WebhookEndpointSchema>;\n\n/**\n * Whether a destination is reached over PLAINTEXT HTTP, so the signature JWT travels in the clear.\n *\n * ## One definition, because two would eventually disagree (#492)\n *\n * Plaintext is ADMITTED here — a deliberate commercial accommodation recorded on\n * {@link WebhookEndpointSchema.url} — which is exactly why the condition needs a single named home\n * rather than an inline `startsWith('http://')` at each surface that wants to say something about\n * it. A refusal can live in one place because it stops the request; a TOLERATED condition is\n * observed by several, and those several must agree.\n *\n * Read by the write path (which warns and audits) and by the endpoint probe (which reports it to\n * the admin who pressed \"test\"). Both are listed here so the next reader can tell whether adding a\n * third is joining a mechanism or starting a second one.\n *\n * Scheme comparison, not a `startsWith`: `WHATWG` lowercases the scheme during parsing, so\n * `HTTP://example.test` and `http://example.test` are the same destination and a prefix test would\n * disagree with the URL the delivery actually opens. An unparseable value answers `false` — it is\n * not a plaintext destination, it is not a destination at all, and `z.url()` refuses it upstream.\n */\nexport function webhookEndpointTransportIsPlaintext(url: string): boolean {\n  try {\n    return new URL(url).protocol === 'http:';\n  } catch {\n    return false;\n  }\n}\n\n/**\n * The host of a webhook destination, for an audit row or a log line — never the full URL.\n *\n * Mirrors `AuditableEvent_Webhook_EndpointTestDispatchedEventDataSchema.destinationHost` and the\n * reasoning recorded there: paths and query strings on customer endpoints routinely embed\n * per-tenant tokens, and these rows are replicated to the organisation's SIEM and to the immutable\n * store. The host answers \"which of my endpoints\" without carrying a credential into a log.\n */\nexport function webhookEndpointDestinationHost(url: string): string {\n  try {\n    return new URL(url).host;\n  } catch {\n    return 'unparseable';\n  }\n}\n\n// =============================================================================\n// BASE CONFIG SCHEMA (polymorphism injects the scope FK at variant time)\n// =============================================================================\n\nexport const WebhookConfigBaseSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n\n  /** Master kill-switch — when `false`, the dispatcher short-circuits with no deliveries. */\n  enabled: z.boolean().default(false).isSummaryField(),\n\n  /** Admin-managed list of destinations. Empty array = no deliveries even when `enabled: true`. */\n  endpoints: z.array(WebhookEndpointSchema).default([]),\n\n  /**\n   * Derived field — populated by `postfixCoreOperations[READ]` from\n   * `appConfig.jwtConfig.config.publicKey[JwtPrivateKeys.APPLICATION_WEBHOOK]`.\n   * Excluded from CREATE/UPDATE so clients cannot set it; the value is\n   * regenerated on every read from the canonical app config so key\n   * rotation is reflected immediately. Phase 3 wires the postfix hook\n   * (Step 9 of the plan).\n   */\n  applicationPublicKeyPem: z.string().optional().excludeFromCreate().excludeFromUpdate(),\n\n  createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n});\n\nexport type WebhookConfigBase = z.infer<typeof WebhookConfigBaseSchema>;\n\n// =============================================================================\n// POLYMORPHIC DECLARATION\n// =============================================================================\n\n/**\n * Yields two `CoreResourceType` variants:\n *   - `organizationWebhookConfig` (FK: `organizationId`)\n *   - `applicationWebhookConfig` (FK: `applicationId`)\n *\n * Both are singletons per scope (cardinality ONE) — wired in\n * `resources-registry.shared.core.definitions.ts` via\n * `createPolymorphicScopeRelationships(...)`.\n */\nexport const webhookConfigPolymorphicDeclaration = declarePolymorphicSchemas({\n  baseResourceType: 'webhookConfig',\n  baseFieldIdentifier: 'webhookConfigId',\n  baseEnumKey: 'WEBHOOK_CONFIG',\n  baseSchema: WebhookConfigBaseSchema,\n  variants: M2M_WEBHOOK_SCOPE_VARIANTS,\n});\n"]}
+{"version":3,"file":"webhook-config.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/notifications/m2m/webhook-config.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * M2M Webhook Config Schema (Shared) — Polymorphic dual-scope\n *\n * Configures outbound webhook delivery for M2M notifications fired by\n * resource operations carrying a `WEBHOOK_ORGANIZATION` or\n * `WEBHOOK_APPLICATION` channel in their spec. Holds:\n *   - a master `enabled` switch\n *   - an array of admin-managed endpoints (URL + description + per-endpoint enabled flag)\n *   - a derived `applicationPublicKeyPem` (READ-only, populated by a\n *     postfix hook from `JwtPrivateKeys.APPLICATION_WEBHOOK` so external\n *     consumers can verify our JWT-signed deliveries)\n *\n * Scope FK (`organizationId` / `applicationId`) is injected by the\n * polymorphism engine — NOT declared on the base schema.\n *\n * @see m2m-webhook-organization-delivery.md — Phase 2 / Step 3\n * @see security/authentications/siem/siem-export-config.shared.schemas.ts\n *   for the dual-scope polymorphic precedent this mirrors.\n */\n\nimport { z } from 'zod';\nimport {\n  CoreResourceType,\n  coreResourceShared_FieldIdentifier,\n} from '../../resources/resources.shared.core.definitions';\nimport {\n  declarePolymorphicSchemas,\n  type PolymorphicVariantDefinition,\n} from '../../resources/utils/resource-polymorphism.schemas';\n\n// =============================================================================\n// ENDPOINT PROBE VOCABULARY\n// =============================================================================\n\n/**\n * Verdict of a single synthetic delivery fired by `webhookConfig.testEndpoint`.\n * A probe that cannot fail is worse than no probe, so every terminal state an\n * outbound attempt can reach is named here rather than collapsed into a boolean.\n *\n * The transport verdict and the HTTP status are deliberately SEPARATE axes:\n * `REJECTED` still carries a response status, because \"the endpoint answered 403\"\n * and \"the endpoint never answered\" are different problems with different fixes.\n *\n * Declared in this light schema module (not alongside the operation DTO) so the\n * audit-event vocabulary can name the same enum without pulling the resource-config\n * factory graph into `auditable-events.shared.schema.ts`.\n */\nexport enum WebhookEndpointProbeOutcome {\n  /**\n   * The endpoint answered with 2xx. This is the only outcome that evidences\n   * consumer-side signature verification: the platform cannot observe the\n   * consumer's verification step directly, so a 2xx from an endpoint that\n   * verifies before responding is the available proof.\n   */\n  ACCEPTED = 'accepted',\n  /** The endpoint answered, but not with 2xx. Reachable; it refused or errored. */\n  REJECTED = 'rejected',\n  /** No HTTP response at all — DNS/TLS/connection failure, or the attempt timed out. */\n  UNREACHABLE = 'unreachable',\n  /**\n   * Nothing left the platform. The payload could not be signed, which is an\n   * operator-side key/configuration fault, not a statement about the endpoint.\n   * Reported distinctly so an admin never reads a local misconfiguration as a\n   * broken customer endpoint.\n   */\n  NOT_SENT = 'not_sent',\n}\n\n// =============================================================================\n// SHARED VARIANT DEFINITIONS\n// =============================================================================\n\n/**\n * The 2 M2M webhook scope variants — shared by `WebhookConfig` and\n * `M2MWebhookDeliveryLog`. Centralised here so both polymorphic\n * declarations stay in lock-step.\n *\n * Notes:\n * - We deliberately define a domain-local constant (mirroring\n *   `BILLING_SCOPE_VARIANTS` in the billing domain) instead of reusing\n *   `AUTH_SCOPE_VARIANTS` from `authentications/`. The variant *shape*\n *   is identical — `(ORGANIZATIONS, APPLICATION)` with `isPrimaryScope:\n *   true` — but the auth constant is documented as \"shared across all\n *   AUTH polymorphic resources\" and webhooks are notification resources,\n *   not auth resources. Keeping a domain-local constant prevents the\n *   semantic drift the framework-mindset rule warns about.\n * - Both variants are primary scopes: there is no \"child of an\n *   organization unit\" or \"child of a user\" variant — webhooks are a\n *   tenant-level concern, not an entity-attached one.\n */\nexport const M2M_WEBHOOK_SCOPE_VARIANTS: PolymorphicVariantDefinition[] = [\n  {\n    parentResourceType: CoreResourceType.ORGANIZATIONS,\n    parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.ORGANIZATIONS],\n    isPrimaryScope: true,\n  },\n  {\n    parentResourceType: CoreResourceType.APPLICATION,\n    parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.APPLICATION],\n    isPrimaryScope: true,\n  },\n];\n\n// =============================================================================\n// ENDPOINT SUB-SCHEMA\n// =============================================================================\n\n/**\n * A single admin-configured webhook destination.\n *\n * v1 deliberately keeps endpoint config minimal (URL + description +\n * enabled flag) — per user direction: \"as a first implementation, we\n * need just an url and a description, not more.\" Per-endpoint secrets\n * are NOT used: signing happens with a single per-application JWT\n * private key (`JwtPrivateKeys.APPLICATION_WEBHOOK`) and consumers\n * verify with the matching public key surfaced via the parent config's\n * derived `applicationPublicKeyPem` field.\n */\nexport const WebhookEndpointSchema = z.object({\n  /**\n   * Stable per-endpoint identifier. Used as the `endpointId` FK on every delivery log row, and the\n   * key the UPDATE path matches an incoming endpoint to its stored self by (#1801).\n   *\n   * ASSIGNED BY THE SERVER when an endpoint is saved without one — which is how a new endpoint\n   * arrives from the settings pane, whose array editor seeds a new item's string fields with `''`.\n   * That is why blank is admitted here rather than refused: `min(1)` made the settings pane unable\n   * to add an endpoint at all, and an id is not something an administrator should have to invent.\n   * A caller that supplies its own id keeps it. Duplicate ids are refused on `endpoints` below.\n   */\n  id: z\n    .string()\n    .max(128)\n    .isNotEditable()\n    .describe('Identifies the endpoint. Delivery-log entries and endpoint tests name the endpoint by this id. Assigned by the server when a new endpoint is saved without one; an existing endpoint keeps its id.'),\n  /**\n   * Destination URL receiving POST deliveries.\n   *\n   * ## `http://` IS ACCEPTED, AND WHAT THAT COSTS YOU (#492, decided 2026-09-08)\n   *\n   * Every delivery carries a **signature JWT in the request**. That JWT is a credential: it is what\n   * proves to your endpoint that the delivery came from this application. Over plaintext it is\n   * readable by anyone on the network path between us and you, and replayable against your endpoint\n   * until it expires — so an observer of one delivery can forge the next one.\n   *\n   * **Use `https://`.** Plaintext is admitted because refusing it would break endpoints already\n   * configured under a framework that accepted them, not because it is safe. That is a commercial\n   * accommodation, deliberately taken, and it is not an assessment that `http://` is fine here.\n   *\n   * The sibling agent push-notification caller requires HTTPS unconditionally, and the same argument\n   * applies to this field; the two differ only in whether anyone has already authored against them.\n   *\n   * Note the URL is also SSRF-guarded at delivery time — a destination resolving to a private or\n   * link-local address is refused regardless of scheme, because a signed POST to an instance-metadata\n   * service is a read primitive rather than a delivery.\n   */\n  url: z\n    .url()\n    .describe(\n      'Where deliveries are sent, as a signed POST. Use `https://`: over `http://` the signature token travels in the clear. A destination that resolves to a private or link-local address is refused when a delivery is sent (outside production, loopback is allowed).',\n    ),\n  /** Free-form admin label (visible in the management UI). */\n  description: z.string().max(500).default('').describe('A label for the endpoint, shown to administrators. At most 500 characters; empty by default.'),\n  /** Per-endpoint master switch — disabled endpoints are skipped by the dispatcher. */\n  enabled: z.boolean().default(true).describe('When `false`, deliveries skip this endpoint. It can still be tested. Defaults to `true`.'),\n  /**\n   * When this endpoint was added. SERVER-STAMPED (#1801): the UPDATE path keeps the stored value for\n   * an endpoint it recognises by `id` and stamps the save instant for a new one, whatever the request\n   * carries — the array is written whole, so a client that omitted or edited this field would\n   * otherwise reset or rewrite it.\n   *\n   * Why not `.excludeFromCreate().excludeFromUpdate()`: those strip TOP-LEVEL request fields only\n   * (`applyUpdateOmissionsToSchema` does not descend into array items), so on an item they would\n   * read as protection and enforce nothing. `.isNotEditable()` is what the item editor honours; the\n   * server stamp is what makes the value true.\n   */\n  createdAt: z\n    .date()\n    .default(() => new Date())\n    .isNotEditable()\n    .describe('When the endpoint was added. Set by the server; a value sent by the client is ignored.'),\n  /** When any setting of this endpoint last changed. SERVER-STAMPED, see {@link createdAt}. */\n  updatedAt: z\n    .date()\n    .default(() => new Date())\n    .isNotEditable()\n    .describe('When the endpoint\\'s URL, description or switch last changed. Set by the server; a value sent by the client is ignored. Saving other endpoints does not change it.'),\n});\n\n/**\n * The endpoint fields a CLIENT authors — every field except the identity and the two server-stamped\n * timestamps. The UPDATE path compares these to decide whether an endpoint changed, so a field added\n * to {@link WebhookEndpointSchema} tomorrow counts as a change without anyone remembering to list it.\n */\nexport const WEBHOOK_ENDPOINT_SERVER_OWNED_FIELDS = ['id', 'createdAt', 'updatedAt'] as const satisfies readonly (keyof z.infer<typeof WebhookEndpointSchema>)[];\n\nexport type WebhookEndpoint = z.infer<typeof WebhookEndpointSchema>;\n\n/**\n * Whether a destination is reached over PLAINTEXT HTTP, so the signature JWT travels in the clear.\n *\n * ## One definition, because two would eventually disagree (#492)\n *\n * Plaintext is ADMITTED here — a deliberate commercial accommodation recorded on\n * {@link WebhookEndpointSchema.url} — which is exactly why the condition needs a single named home\n * rather than an inline `startsWith('http://')` at each surface that wants to say something about\n * it. A refusal can live in one place because it stops the request; a TOLERATED condition is\n * observed by several, and those several must agree.\n *\n * Read by the UPDATE path (which logs a warning naming the destination host when a plaintext endpoint\n * is saved) and by the endpoint probe (which reports it to the admin who pressed \"test\"). Both are\n * listed here so the next reader can tell whether adding a third is joining a mechanism or starting\n * a second one.\n *\n * Scheme comparison, not a `startsWith`: `WHATWG` lowercases the scheme during parsing, so\n * `HTTP://example.test` and `http://example.test` are the same destination and a prefix test would\n * disagree with the URL the delivery actually opens. An unparseable value answers `false` — it is\n * not a plaintext destination, it is not a destination at all, and `z.url()` refuses it upstream.\n */\nexport function webhookEndpointTransportIsPlaintext(url: string): boolean {\n  try {\n    return new URL(url).protocol === 'http:';\n  } catch {\n    return false;\n  }\n}\n\n/**\n * The host of a webhook destination, for an audit row or a log line — never the full URL.\n *\n * Mirrors `AuditableEvent_Webhook_EndpointTestDispatchedEventDataSchema.destinationHost` and the\n * reasoning recorded there: paths and query strings on customer endpoints routinely embed\n * per-tenant tokens, and these rows are replicated to the organisation's SIEM and to the immutable\n * store. The host answers \"which of my endpoints\" without carrying a credential into a log.\n */\nexport function webhookEndpointDestinationHost(url: string): string {\n  try {\n    return new URL(url).host;\n  } catch {\n    return 'unparseable';\n  }\n}\n\n// =============================================================================\n// BASE CONFIG SCHEMA (polymorphism injects the scope FK at variant time)\n// =============================================================================\n\nexport const WebhookConfigBaseSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n\n  /** Master kill-switch — when `false`, the dispatcher short-circuits with no deliveries. */\n  enabled: z.boolean().default(false).isSummaryField(),\n\n  /**\n   * Admin-managed list of destinations. Empty array = no deliveries even when `enabled: true`.\n   *\n   * Ids must be unique: the UPDATE path matches endpoints by id to carry their timestamps forward,\n   * delivery-log rows name their endpoint by id, and `testEndpoint` selects one by id — a duplicate\n   * would make all three pick an arbitrary one of the two. Blank ids are exempt, because the server\n   * assigns them on save (see `WebhookEndpointSchema.id`).\n   */\n  // The refinement sits on the ARRAY, before `.default([])`: the request-DTO builder rebuilds a\n  // default-wrapped field from its inner type, so a check on the wrapper never reached a request and a\n  // PUT with two `\"same\"` ids was accepted (#1801 review M1).\n  endpoints: z\n    .array(WebhookEndpointSchema)\n    .superRefine((endpoints, ctx) => {\n      const seen = new Set<string>();\n      endpoints.forEach((endpoint, index) => {\n        if (!endpoint.id) return;\n        if (seen.has(endpoint.id)) {\n          ctx.addIssue({ code: 'custom', path: [index, 'id'], message: `Two endpoints share the id \"${endpoint.id}\". Each endpoint needs its own id.` });\n        }\n        seen.add(endpoint.id);\n      });\n    })\n    .default([]),\n\n  /**\n   * Derived field — populated by `postfixCoreOperations[READ]` from\n   * `appConfig.jwtConfig.config.publicKey[JwtPrivateKeys.APPLICATION_WEBHOOK]`.\n   * Excluded from CREATE/UPDATE so clients cannot set it; the value is\n   * regenerated on every read from the canonical app config so key\n   * rotation is reflected immediately. Phase 3 wires the postfix hook\n   * (Step 9 of the plan).\n   */\n  applicationPublicKeyPem: z.string().optional().excludeFromCreate().excludeFromUpdate(),\n\n  createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n});\n\nexport type WebhookConfigBase = z.infer<typeof WebhookConfigBaseSchema>;\n\n// =============================================================================\n// POLYMORPHIC DECLARATION\n// =============================================================================\n\n/**\n * Yields two `CoreResourceType` variants:\n *   - `organizationWebhookConfig` (FK: `organizationId`)\n *   - `applicationWebhookConfig` (FK: `applicationId`)\n *\n * Both are singletons per scope (cardinality ONE) — wired in\n * `resources-registry.shared.core.definitions.ts` via\n * `createPolymorphicScopeRelationships(...)`.\n */\nexport const webhookConfigPolymorphicDeclaration = declarePolymorphicSchemas({\n  baseResourceType: 'webhookConfig',\n  baseFieldIdentifier: 'webhookConfigId',\n  baseEnumKey: 'WEBHOOK_CONFIG',\n  baseSchema: WebhookConfigBaseSchema,\n  variants: M2M_WEBHOOK_SCOPE_VARIANTS,\n});\n"]}

package/dist/esm/notifications/notification-badges.schemas.d.ts

@@ -20,7 +20,7 @@ export declare const NOTIFICATION_BADGE_IDENTIFIER_PATTERN: RegExp;
  * 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
+ * and the menubar render 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.
@@ -66,6 +66,11 @@ export declare const NotificationScopeSchema: z.ZodEnum<{
  * 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.
+ *
+ * `FRONTEND_PRODUCED` is for a count the FRONTEND already holds and the backend cannot compute — a
+ * quantity derived from rows that are not a repository collection (a projection, a live read the
+ * browser keeps current). The surface that owns the data publishes it with
+ * `usePublishNotificationBadgeCount`; nothing is stored and nothing is recomputed server-side.
  */
 export declare enum NotificationBadgeOperation {
     INCREMENT = "increment",
@@ -83,10 +88,19 @@ export declare enum NotificationBadgeOperation {
  *   (`count(resourceType where filter, scoped)`), recomputed on that resource's
  *   mutations. Correct for "incomplete todos" / "unpaid invoices" — quantities
  *   derived from data that would DRIFT if tracked with a stored counter.
+ * - `FRONTEND_PRODUCED`: the count is PUBLISHED by the frontend surface that already holds the
+ *   data it counts (`usePublishNotificationBadgeCount`), onto the same badge store a backend push
+ *   feeds. The backend neither stores nor recomputes it and skips it when seeding a connection.
+ *   Correct only where the backend cannot run the count — the rows are a projection rather than a
+ *   repository collection — so a `DERIVED_QUERY` over repository rows is never replaced by this.
+ *   The producer must be mounted wherever the navigation showing the badge is: for a menubar or
+ *   sidebar badge, a shell companion (`ApplicationMainProviderOptions.shellCompanions`), which the
+ *   signed-in shell mounts on every page. A late-mounting badge reads the last published count.
  */
 export declare enum NotificationBadgeSourceKind {
     EVENT_COUNTER = "event_counter",
-    DERIVED_QUERY = "derived_query"
+    DERIVED_QUERY = "derived_query",
+    FRONTEND_PRODUCED = "frontend_produced"
 }
 /** How the badge is presented. `NONE` = suppressed even when the count is > 0. */
 export declare enum NotificationBadgeDisplayMode {
@@ -125,6 +139,13 @@ export declare const NotificationBadgeDerivedQuerySourceSchema: z.ZodObject<{
     filter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     scopeField: z.ZodString;
 }, z.core.$strip>;
+/**
+ * FRONTEND_PRODUCED source — no extra config: the publishing surface names the badge by its key and
+ * supplies the count, so there is nothing for a declaration to say about how it is computed.
+ */
+export declare const NotificationBadgeFrontendProducedSourceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<NotificationBadgeSourceKind.FRONTEND_PRODUCED>;
+}, z.core.$strip>;
 /** Discriminated union over the calculation kinds. */
 export declare const NotificationBadgeSourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<NotificationBadgeSourceKind.EVENT_COUNTER>;
@@ -133,6 +154,8 @@ export declare const NotificationBadgeSourceSchema: z.ZodDiscriminatedUnion<[z.Z
     resourceType: z.ZodString;
     filter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     scopeField: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<NotificationBadgeSourceKind.FRONTEND_PRODUCED>;
 }, z.core.$strip>], "kind">;
 /**
  * Presentation declaration. `tone` reuses the design-system `IndicatorVariant`
@@ -161,6 +184,8 @@ export declare const NotificationBadgeDefinitionSchema: z.ZodObject<{
         resourceType: z.ZodString;
         filter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         scopeField: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<NotificationBadgeSourceKind.FRONTEND_PRODUCED>;
     }, z.core.$strip>], "kind">;
     display: z.ZodObject<{
         mode: z.ZodDefault<z.ZodEnum<typeof NotificationBadgeDisplayMode>>;
@@ -299,7 +324,14 @@ export declare enum NotificationBadgeDeclarationViolationReason {
      */
     IDENTIFIER_CONTAINS_KEY_SEPARATOR = "identifier_contains_key_separator",
     /** An operation declares a `badgeRef` that names no registered definition. */
-    OPERATION_REF_UNRESOLVED = "operation_ref_unresolved"
+    OPERATION_REF_UNRESOLVED = "operation_ref_unresolved",
+    /**
+     * An operation declares a counter move (increment, reset, …) on a badge whose count is NOT a
+     * stored counter — a `DERIVED_QUERY` recomputes its own and a `FRONTEND_PRODUCED` is published by
+     * the browser. The move would write a stored row nothing renders, and a backend push of that row
+     * would overwrite the real count. Only an `EVENT_COUNTER` is moved by operations.
+     */
+    OPERATION_MOVES_UNSTORED_COUNT = "operation_moves_unstored_count"
 }
 /** One refused declaration, carrying enough to name the author's own file without re-deriving it. */
 export interface NotificationBadgeDeclarationViolation {

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

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

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

@@ -22,7 +22,7 @@ export const NOTIFICATION_BADGE_IDENTIFIER_PATTERN = /^[^:]+$/;
  * 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
+ * and the menubar render 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.
@@ -73,6 +73,11 @@ export const NotificationScopeSchema = z.enum([
  * 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.
+ *
+ * `FRONTEND_PRODUCED` is for a count the FRONTEND already holds and the backend cannot compute — a
+ * quantity derived from rows that are not a repository collection (a projection, a live read the
+ * browser keeps current). The surface that owns the data publishes it with
+ * `usePublishNotificationBadgeCount`; nothing is stored and nothing is recomputed server-side.
  */
 export var NotificationBadgeOperation;
 (function (NotificationBadgeOperation) {
@@ -91,11 +96,20 @@ export var NotificationBadgeOperation;
  *   (`count(resourceType where filter, scoped)`), recomputed on that resource's
  *   mutations. Correct for "incomplete todos" / "unpaid invoices" — quantities
  *   derived from data that would DRIFT if tracked with a stored counter.
+ * - `FRONTEND_PRODUCED`: the count is PUBLISHED by the frontend surface that already holds the
+ *   data it counts (`usePublishNotificationBadgeCount`), onto the same badge store a backend push
+ *   feeds. The backend neither stores nor recomputes it and skips it when seeding a connection.
+ *   Correct only where the backend cannot run the count — the rows are a projection rather than a
+ *   repository collection — so a `DERIVED_QUERY` over repository rows is never replaced by this.
+ *   The producer must be mounted wherever the navigation showing the badge is: for a menubar or
+ *   sidebar badge, a shell companion (`ApplicationMainProviderOptions.shellCompanions`), which the
+ *   signed-in shell mounts on every page. A late-mounting badge reads the last published count.
  */
 export var NotificationBadgeSourceKind;
 (function (NotificationBadgeSourceKind) {
     NotificationBadgeSourceKind["EVENT_COUNTER"] = "event_counter";
     NotificationBadgeSourceKind["DERIVED_QUERY"] = "derived_query";
+    NotificationBadgeSourceKind["FRONTEND_PRODUCED"] = "frontend_produced";
 })(NotificationBadgeSourceKind || (NotificationBadgeSourceKind = {}));
 /** How the badge is presented. `NONE` = suppressed even when the count is > 0. */
 export var NotificationBadgeDisplayMode;
@@ -136,10 +150,18 @@ export const NotificationBadgeDerivedQuerySourceSchema = z.object({
     filter: z.record(z.string(), z.unknown()),
     scopeField: z.string().min(1, { error: 'Derived-badge scopeField is required' }),
 });
+/**
+ * FRONTEND_PRODUCED source — no extra config: the publishing surface names the badge by its key and
+ * supplies the count, so there is nothing for a declaration to say about how it is computed.
+ */
+export const NotificationBadgeFrontendProducedSourceSchema = z.object({
+    kind: z.literal(NotificationBadgeSourceKind.FRONTEND_PRODUCED),
+});
 /** Discriminated union over the calculation kinds. */
 export const NotificationBadgeSourceSchema = z.discriminatedUnion('kind', [
     NotificationBadgeEventCounterSourceSchema,
     NotificationBadgeDerivedQuerySourceSchema,
+    NotificationBadgeFrontendProducedSourceSchema,
 ]);
 /**
  * Presentation declaration. `tone` reuses the design-system `IndicatorVariant`
@@ -184,11 +206,11 @@ const NotificationBadgeBaseSchema = NotificationBadgeIdentitySchema.extend({
     updatedAt: z.date().default(() => new Date()).isDBIndexed().isSummaryField(),
 });
 export const NotificationBadgeOrganizationSchema = NotificationBadgeBaseSchema.extend({
-    scope: z.literal(ResourcePrimaryScope.ORGANIZATIONS),
+    scope: z.literal(ResourcePrimaryScope.ORGANIZATIONS).describe('Always `organizations`: this count is shared by every member of the organization.'),
     organizationId: z.string().min(1, { error: 'Organization ID is required' }).isDBIndexed().isForeignKey(),
 });
 export const NotificationBadgeUserSelfSchema = NotificationBadgeBaseSchema.extend({
-    scope: z.literal(ResourcePrimaryScope.USER_SELF),
+    scope: z.literal(ResourcePrimaryScope.USER_SELF).describe('Always `user_self`: this count belongs to one user and only that user can read it.'),
     userId: z.string().min(1, { error: 'User ID is required' }).isDBIndexed().isForeignKey(),
 });
 /**
@@ -279,6 +301,13 @@ export var NotificationBadgeDeclarationViolationReason;
     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";
+    /**
+     * An operation declares a counter move (increment, reset, …) on a badge whose count is NOT a
+     * stored counter — a `DERIVED_QUERY` recomputes its own and a `FRONTEND_PRODUCED` is published by
+     * the browser. The move would write a stored row nothing renders, and a backend push of that row
+     * would overwrite the real count. Only an `EVENT_COUNTER` is moved by operations.
+     */
+    NotificationBadgeDeclarationViolationReason["OPERATION_MOVES_UNSTORED_COUNT"] = "operation_moves_unstored_count";
 })(NotificationBadgeDeclarationViolationReason || (NotificationBadgeDeclarationViolationReason = {}));
 /**
  * The whole declaration-coherence check, as a pure function over what an application declared.
@@ -294,6 +323,7 @@ export var NotificationBadgeDeclarationViolationReason;
 export function collectNotificationBadgeDeclarationViolations(definitions, operationSites = []) {
     const violations = [];
     const seenKeys = new Set();
+    const sourceKindByKey = new Map();
     for (const definition of definitions) {
         if (!NOTIFICATION_BADGE_IDENTIFIER_PATTERN.test(definition.identifier)) {
             violations.push({
@@ -313,6 +343,7 @@ export function collectNotificationBadgeDeclarationViolations(definitions, opera
             continue;
         }
         seenKeys.add(key);
+        sourceKindByKey.set(key, definition.source.kind);
     }
     for (const site of operationSites) {
         if (!seenKeys.has(site.badgeRef)) {
@@ -322,6 +353,15 @@ export function collectNotificationBadgeDeclarationViolations(definitions, opera
                 resourceType: site.resourceType,
                 operationIdentifier: site.operationIdentifier,
             });
+            continue;
+        }
+        if (sourceKindByKey.get(site.badgeRef) !== NotificationBadgeSourceKind.EVENT_COUNTER) {
+            violations.push({
+                reason: NotificationBadgeDeclarationViolationReason.OPERATION_MOVES_UNSTORED_COUNT,
+                badgeKey: site.badgeRef,
+                resourceType: site.resourceType,
+                operationIdentifier: site.operationIdentifier,
+            });
         }
     }
     return violations;

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 * 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"]}
+{"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;;;;;;;;;;;;;;;;;;;;GAoBG;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;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAN,IAAY,2BAIX;AAJD,WAAY,2BAA2B;IACnC,8DAA+B,CAAA;IAC/B,8DAA+B,CAAA;IAC/B,sEAAuC,CAAA;AAC3C,CAAC,EAJW,2BAA2B,KAA3B,2BAA2B,QAItC;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;;;GAGG;AACH,MAAM,CAAC,MAAM,6CAA6C,GAAG,CAAC,CAAC,MAAM,CAAC;IAClE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,2BAA2B,CAAC,iBAAiB,CAAC;CACjE,CAAC,CAAC;AAEH,sDAAsD;AACtD,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IACtE,yCAAyC;IACzC,yCAAyC;IACzC,6CAA6C;CAChD,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,CAAC,QAAQ,CAAC,mFAAmF,CAAC;IAClJ,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,CAAC,QAAQ,CAAC,oFAAoF,CAAC;IAC/I,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,2CAuBX;AAvBD,WAAY,2CAA2C;IACnD;;;;;OAKG;IACH,oGAAqD,CAAA;IACrD;;;;OAIG;IACH,sHAAuE,CAAA;IACvE,8EAA8E;IAC9E,oGAAqD,CAAA;IACrD;;;;;OAKG;IACH,gHAAiE,CAAA;AACrE,CAAC,EAvBW,2CAA2C,KAA3C,2CAA2C,QAuBtD;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;IACjD,MAAM,eAAe,GAAG,IAAI,GAAG,EAAqD,CAAC;IAErF,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;QAClB,eAAe,CAAC,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACrD,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;YACH,SAAS;QACb,CAAC;QACD,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,2BAA2B,CAAC,aAAa,EAAE,CAAC;YACnF,UAAU,CAAC,IAAI,CAAC;gBACZ,MAAM,EAAE,2CAA2C,CAAC,8BAA8B;gBAClF,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 * and the menubar render 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 *\n * `FRONTEND_PRODUCED` is for a count the FRONTEND already holds and the backend cannot compute — a\n * quantity derived from rows that are not a repository collection (a projection, a live read the\n * browser keeps current). The surface that owns the data publishes it with\n * `usePublishNotificationBadgeCount`; nothing is stored and nothing is recomputed server-side.\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 * - `FRONTEND_PRODUCED`: the count is PUBLISHED by the frontend surface that already holds the\n *   data it counts (`usePublishNotificationBadgeCount`), onto the same badge store a backend push\n *   feeds. The backend neither stores nor recomputes it and skips it when seeding a connection.\n *   Correct only where the backend cannot run the count — the rows are a projection rather than a\n *   repository collection — so a `DERIVED_QUERY` over repository rows is never replaced by this.\n *   The producer must be mounted wherever the navigation showing the badge is: for a menubar or\n *   sidebar badge, a shell companion (`ApplicationMainProviderOptions.shellCompanions`), which the\n *   signed-in shell mounts on every page. A late-mounting badge reads the last published count.\n */\nexport enum NotificationBadgeSourceKind {\n    EVENT_COUNTER = 'event_counter',\n    DERIVED_QUERY = 'derived_query',\n    FRONTEND_PRODUCED = 'frontend_produced',\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/**\n * FRONTEND_PRODUCED source — no extra config: the publishing surface names the badge by its key and\n * supplies the count, so there is nothing for a declaration to say about how it is computed.\n */\nexport const NotificationBadgeFrontendProducedSourceSchema = z.object({\n    kind: z.literal(NotificationBadgeSourceKind.FRONTEND_PRODUCED),\n});\n\n/** Discriminated union over the calculation kinds. */\nexport const NotificationBadgeSourceSchema = z.discriminatedUnion('kind', [\n    NotificationBadgeEventCounterSourceSchema,\n    NotificationBadgeDerivedQuerySourceSchema,\n    NotificationBadgeFrontendProducedSourceSchema,\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).describe('Always `organizations`: this count is shared by every member of the organization.'),\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).describe('Always `user_self`: this count belongs to one user and only that user can read it.'),\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     * An operation declares a counter move (increment, reset, …) on a badge whose count is NOT a\n     * stored counter — a `DERIVED_QUERY` recomputes its own and a `FRONTEND_PRODUCED` is published by\n     * the browser. The move would write a stored row nothing renders, and a backend push of that row\n     * would overwrite the real count. Only an `EVENT_COUNTER` is moved by operations.\n     */\n    OPERATION_MOVES_UNSTORED_COUNT = 'operation_moves_unstored_count',\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    const sourceKindByKey = new Map<NotificationBadgeKey, NotificationBadgeSourceKind>();\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        sourceKindByKey.set(key, definition.source.kind);\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            continue;\n        }\n        if (sourceKindByKey.get(site.badgeRef) !== NotificationBadgeSourceKind.EVENT_COUNTER) {\n            violations.push({\n                reason: NotificationBadgeDeclarationViolationReason.OPERATION_MOVES_UNSTORED_COUNT,\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"]}