@wildo-ai/saas-models 1.1.2 → 1.1.3

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

@@ -107,7 +107,27 @@ export const M2M_WEBHOOK_SCOPE_VARIANTS = [
 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),
-    /** Destination URL receiving POST deliveries. */
+    /**
+     * Destination URL receiving POST deliveries.
+     *
+     * ## `http://` IS ACCEPTED, AND WHAT THAT COSTS YOU (#492, decided 2026-09-08)
+     *
+     * Every delivery carries a **signature JWT in the request**. That JWT is a credential: it is what
+     * proves to your endpoint that the delivery came from this application. Over plaintext it is
+     * readable by anyone on the network path between us and you, and replayable against your endpoint
+     * until it expires — so an observer of one delivery can forge the next one.
+     *
+     * **Use `https://`.** Plaintext is admitted because refusing it would break endpoints already
+     * configured under a framework that accepted them, not because it is safe. That is a commercial
+     * accommodation, deliberately taken, and it is not an assessment that `http://` is fine here.
+     *
+     * The sibling agent push-notification caller requires HTTPS unconditionally, and the same argument
+     * applies to this field; the two differ only in whether anyone has already authored against them.
+     *
+     * Note the URL is also SSRF-guarded at delivery time — a destination resolving to a private or
+     * 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(),
     /** Free-form admin label (visible in the management UI). */
     description: z.string().max(500).default(''),
@@ -116,6 +136,50 @@ export const WebhookEndpointSchema = z.object({
     createdAt: z.date().default(() => new Date()),
     updatedAt: z.date().default(() => new Date()),
 });
+/**
+ * Whether a destination is reached over PLAINTEXT HTTP, so the signature JWT travels in the clear.
+ *
+ * ## One definition, because two would eventually disagree (#492)
+ *
+ * Plaintext is ADMITTED here — a deliberate commercial accommodation recorded on
+ * {@link WebhookEndpointSchema.url} — which is exactly why the condition needs a single named home
+ * rather than an inline `startsWith('http://')` at each surface that wants to say something about
+ * 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.
+ *
+ * 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
+ * disagree with the URL the delivery actually opens. An unparseable value answers `false` — it is
+ * not a plaintext destination, it is not a destination at all, and `z.url()` refuses it upstream.
+ */
+export function webhookEndpointTransportIsPlaintext(url) {
+    try {
+        return new URL(url).protocol === 'http:';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The host of a webhook destination, for an audit row or a log line — never the full URL.
+ *
+ * Mirrors `AuditableEvent_Webhook_EndpointTestDispatchedEventDataSchema.destinationHost` and the
+ * reasoning recorded there: paths and query strings on customer endpoints routinely embed
+ * per-tenant tokens, and these rows are replicated to the organisation's SIEM and to the immutable
+ * store. The host answers "which of my endpoints" without carrying a credential into a log.
+ */
+export function webhookEndpointDestinationHost(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return 'unparseable';
+    }
+}
 // =============================================================================
 // BASE CONFIG SCHEMA (polymorphism injects the scope FK at variant time)
 // =============================================================================

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  /** Destination URL receiving POST deliveries. */\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// 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  /** 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"]}

package/dist/esm/notifications/notification-badges.core.definitions.d.ts

@@ -3,10 +3,12 @@ import { NotificationBadgeDefinition } from "./notification-badges.schemas";
  * Canonical (framework-shipped) notification badge definitions.
  *
  * Intentionally empty: the two aspirational placeholders (`new messages` /
- * `unpaid invoices`) were removed because nothing produced them and the launcher
- * surfacing was retracted (see `.claude/plans/badge-launcher-retract.md`). Real
- * definitions return with their producer per the Reintroduction Contract (R1),
- * carrying a typed `source` (EVENT_COUNTER | DERIVED_QUERY) + `display`.
+ * `unpaid invoices`) were removed because nothing produced them.
+ *
+ * This is a statement about FRAMEWORK-shipped definitions only. Badge surfacing itself works: a
+ * navigation item carries `notificationBadgeRef` and the sidebar renders the badge, and applications
+ * declare their own definitions. A framework definition returns here only once the framework also
+ * ships its producer, carrying a typed `source` (EVENT_COUNTER | DERIVED_QUERY) + `display`.
  */
 export declare const coreNotificationBadgeDefinitions: NotificationBadgeDefinition[];
 //# sourceMappingURL=notification-badges.core.definitions.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"notification-badges.core.definitions.d.ts","sourceRoot":"","sources":["../../../../src/notifications/notification-badges.core.definitions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAE5E;;;;;;;;GAQG;AACH,eAAO,MAAM,gCAAgC,EAAE,2BAA2B,EAAO,CAAC"}
+{"version":3,"file":"notification-badges.core.definitions.d.ts","sourceRoot":"","sources":["../../../../src/notifications/notification-badges.core.definitions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAE5E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gCAAgC,EAAE,2BAA2B,EAAO,CAAC"}

package/dist/esm/notifications/notification-badges.core.definitions.js

@@ -2,10 +2,12 @@
  * Canonical (framework-shipped) notification badge definitions.
  *
  * Intentionally empty: the two aspirational placeholders (`new messages` /
- * `unpaid invoices`) were removed because nothing produced them and the launcher
- * surfacing was retracted (see `.claude/plans/badge-launcher-retract.md`). Real
- * definitions return with their producer per the Reintroduction Contract (R1),
- * carrying a typed `source` (EVENT_COUNTER | DERIVED_QUERY) + `display`.
+ * `unpaid invoices`) were removed because nothing produced them.
+ *
+ * This is a statement about FRAMEWORK-shipped definitions only. Badge surfacing itself works: a
+ * navigation item carries `notificationBadgeRef` and the sidebar renders the badge, and applications
+ * declare their own definitions. A framework definition returns here only once the framework also
+ * ships its producer, carrying a typed `source` (EVENT_COUNTER | DERIVED_QUERY) + `display`.
  */
 export const coreNotificationBadgeDefinitions = [];
 //# sourceMappingURL=notification-badges.core.definitions.js.map

package/dist/esm/notifications/notification-badges.core.definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"notification-badges.core.definitions.js","sourceRoot":"","sources":["../../../../src/notifications/notification-badges.core.definitions.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAkC,EAAE,CAAC","sourcesContent":["import { NotificationBadgeDefinition } from \"./notification-badges.schemas\";\n\n/**\n * Canonical (framework-shipped) notification badge definitions.\n *\n * Intentionally empty: the two aspirational placeholders (`new messages` /\n * `unpaid invoices`) were removed because nothing produced them and the launcher\n * surfacing was retracted (see `.claude/plans/badge-launcher-retract.md`). Real\n * definitions return with their producer per the Reintroduction Contract (R1),\n * carrying a typed `source` (EVENT_COUNTER | DERIVED_QUERY) + `display`.\n */\nexport const coreNotificationBadgeDefinitions: NotificationBadgeDefinition[] = [];\n"]}
+{"version":3,"file":"notification-badges.core.definitions.js","sourceRoot":"","sources":["../../../../src/notifications/notification-badges.core.definitions.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAkC,EAAE,CAAC","sourcesContent":["import { NotificationBadgeDefinition } from \"./notification-badges.schemas\";\n\n/**\n * Canonical (framework-shipped) notification badge definitions.\n *\n * Intentionally empty: the two aspirational placeholders (`new messages` /\n * `unpaid invoices`) were removed because nothing produced them.\n *\n * This is a statement about FRAMEWORK-shipped definitions only. Badge surfacing itself works: a\n * navigation item carries `notificationBadgeRef` and the sidebar renders the badge, and applications\n * declare their own definitions. A framework definition returns here only once the framework also\n * ships its producer, carrying a typed `source` (EVENT_COUNTER | DERIVED_QUERY) + `display`.\n */\nexport const coreNotificationBadgeDefinitions: NotificationBadgeDefinition[] = [];\n"]}

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

@@ -1,14 +1,35 @@
 import { z } from "zod";
 import { IndicatorVariant } from '@wildo-ai/presets-components-models';
 import { ResourcePrimaryScope } from "../resources/resources.shared.schemas";
+/**
+ * The one character that separates the parts of a badge KEY and a badge REFERENCE.
+ *
+ * Both formats are positional, so the separator may not appear inside a part or the parse is
+ * ambiguous. `NotificationBadgeIdentifierSchema` refuses it in an identifier for exactly that
+ * reason, and `collectNotificationBadgeDeclarationViolations` re-states the refusal at boot,
+ * because a declaration object is authored in TypeScript and never `.parse()`d.
+ */
+export declare const NOTIFICATION_BADGE_KEY_SEPARATOR = ":";
+/** Any string that does not contain {@link NOTIFICATION_BADGE_KEY_SEPARATOR}. */
+export declare const NOTIFICATION_BADGE_IDENTIFIER_PATTERN: RegExp;
 /**
  * Notification badge identifier.
  *
- * No canonical (core) identifiers ship today — the two aspirational placeholders
- * (`new messages` / `unpaid invoices`) were removed because nothing produced them
- * (see `.claude/plans/badge-launcher-retract.md`). When the badge surfacing is
- * reintroduced with a real producer (Reintroduction Contract R1), core identifiers
- * come back as a `CoreNotificationBadgeIdentifiers` enum unioned in here.
+ * The identifier is an open string because no canonical (core) identifier ships: the two
+ * aspirational placeholders (`new messages` / `unpaid invoices`) were removed because nothing
+ * produced them.
+ *
+ * The SURFACING is not missing. A navigation item declares `notificationBadgeRef` and the sidebar
+ * renders it, and an application declares its own badges, so the open string is what an application
+ * uses today. What is still absent is a FRAMEWORK-shipped identifier with a framework producer
+ * behind it; when one lands, core identifiers come back as a `CoreNotificationBadgeIdentifiers`
+ * enum unioned in here.
+ *
+ * Open, but not unconstrained: an identifier may not contain
+ * {@link NOTIFICATION_BADGE_KEY_SEPARATOR}, because it is the LAST part of a badge key and of a
+ * badge reference and both are positional. A definition object is authored in TypeScript and never
+ * `.parse()`d, so this constraint is also re-stated as a boot check — see
+ * {@link collectNotificationBadgeDeclarationViolations}.
  */
 export declare const NotificationBadgeIdentifierSchema: z.ZodString;
 /**
@@ -30,6 +51,22 @@ export declare const NotificationScopeSchema: z.ZodEnum<{
     user_self: ResourcePrimaryScope.USER_SELF;
     organizations: ResourcePrimaryScope.ORGANIZATIONS;
 }>;
+/**
+ * @wildo_source:part:start saas.models.notifications.badge-vocabularies facet:layer:shared facet:audience:app-developer
+ *
+ * The four vocabularies a badge definition picks from: how its count is CALCULATED, how it is
+ * PRESENTED, whether it draws attention, and — for a stored counter — what an operation does to it.
+ *
+ * ⚠️ **Choosing the source kind wrongly produces a number that DRIFTS.** Reach for `EVENT_COUNTER`
+ * only when the count is a fact the badge itself owns ("unread messages": arrive → increment, seen →
+ * reset). For any quantity derived from data an operation could change by another route — incomplete
+ * todos, unpaid invoices — use `DERIVED_QUERY`, which recomputes a live aggregate. A stored counter
+ * on a derived quantity is right on the day it is written and wrong thereafter.
+ *
+ * An `EVENT_COUNTER` badge additionally needs `notificationBadgeOperations` declared on the
+ * operations that move it; a `DERIVED_QUERY` badge needs none, because the recompute hangs off the
+ * source resource's own mutations.
+ */
 export declare enum NotificationBadgeOperation {
     INCREMENT = "increment",
     DECREMENT = "decrement",
@@ -71,6 +108,7 @@ export declare enum NotificationBadgePulse {
     /** Persistent — pulse while the count is > 0. */
     WHILE_ACTIVE = "while_active"
 }
+/** @wildo_source:part:end saas.models.notifications.badge-vocabularies */
 /** EVENT_COUNTER source — no extra config; the stored counter is the truth. */
 export declare const NotificationBadgeEventCounterSourceSchema: z.ZodObject<{
     kind: z.ZodLiteral<NotificationBadgeSourceKind.EVENT_COUNTER>;
@@ -176,4 +214,128 @@ export type NotificationBadge = z.infer<typeof NotificationBadgeSchema>;
 export type NotificationBadgeSource = z.infer<typeof NotificationBadgeSourceSchema>;
 export type NotificationBadgeDerivedQuerySource = z.infer<typeof NotificationBadgeDerivedQuerySourceSchema>;
 export type NotificationBadgeDisplay = z.infer<typeof NotificationBadgeDisplaySchema>;
+/**
+ * A badge KEY: `<scope>:<identifier>` — the DEFINITION's identity, and the only thing that may be
+ * used to look a definition up.
+ *
+ * ## Why the identifier alone is not an identity
+ *
+ * A definition is `(scope, identifier)`. Nothing ever stopped two definitions declaring the same
+ * `identifier` at different scopes, and until this type existed every lookup matched on the
+ * identifier alone — so the second definition was unreachable and silently shared the first's
+ * count. The key makes both reachable and makes the collision that DOES matter (two definitions at
+ * one scope and identifier) something a boot check can refuse.
+ *
+ * ## Why `scopeId` is NOT in the key
+ *
+ * `scopeId` says WHOSE badge — a user id, an organization id. It is per-viewer instance data that a
+ * navigation declaration cannot possibly carry, and a browser session only ever receives pushes for
+ * its own scope ids (the backend routes USER badges to that user's socket and ORG badges to that
+ * organization's room). So the key is what a DECLARATION can name, and the reference below is what
+ * an INSTANCE is addressed by.
+ */
+export type NotificationBadgeKey = string;
+/**
+ * A badge REFERENCE: `<scope>:<scopeId>:<identifier>` — one badge ROW, on the wire.
+ *
+ * Carried by `WS_BadgeUpdatePayload.badgeReference` because emission needs the scopeId to route.
+ * The browser reduces it to a {@link NotificationBadgeKey} on arrival via
+ * {@link notificationBadgeKeyFromReference}, which is what makes the store's key and the navigation
+ * item's lookup the same key rather than two conventions that agree by luck.
+ */
+export type NotificationBadgeReference = string;
+/** Build the DEFINITION-identity key from its parts. */
+export declare function buildNotificationBadgeKey(scope: NotificationScope, identifier: NotificationBadgeIdentifier): NotificationBadgeKey;
+/**
+ * The key of a definition (or of anything else carrying a badge identity, such as a persisted row).
+ *
+ * Takes the identity fields rather than the whole definition so a `NotificationBadge` row and a
+ * `NotificationBadgeDefinition` resolve through the SAME function — a second copy for the row shape
+ * is how the two come to disagree.
+ */
+export declare function notificationBadgeIdentityKey(identity: Pick<NotificationBadgeDefinition, 'scope' | 'identifier'>): NotificationBadgeKey;
+/**
+ * Parse a key, returning `null` when it is not a well-formed key at a SUPPORTED scope.
+ *
+ * The scope check is not cosmetic: the APPLICATION variant was dropped in the polymorphism refactor
+ * and no resource type backs it, so `application:foo` must fail here rather than reach a dispatch
+ * that has no repository for it.
+ */
+export declare function parseNotificationBadgeKey(key: string): {
+    scope: NotificationScope;
+    identifier: NotificationBadgeIdentifier;
+} | null;
+/** Build the INSTANCE address carried on the wire. */
+export declare function buildNotificationBadgeReference(scope: NotificationScope, scopeId: string, identifier: NotificationBadgeIdentifier): NotificationBadgeReference;
+/** Parse a wire reference, returning `null` for a malformed one or an unsupported scope. */
+export declare function parseNotificationBadgeReference(reference: string): {
+    scope: NotificationScope;
+    scopeId: string;
+    identifier: NotificationBadgeIdentifier;
+} | null;
+/**
+ * Reduce a wire reference to the DEFINITION key it addresses — the one hop the browser badge store
+ * takes, so that what it keys on is what a navigation item resolves against.
+ */
+export declare function notificationBadgeKeyFromReference(reference: string): NotificationBadgeKey | null;
+/** Whether a raw string names one of the two surviving badge scopes. */
+export declare function isSupportedNotificationBadgeScope(scope: string): scope is NotificationScope;
+/**
+ * Why a badge declaration is refused. A closed vocabulary with a named runtime source, so a
+ * diagnostic can be branched on and each member can carry its own explanation.
+ */
+export declare enum NotificationBadgeDeclarationViolationReason {
+    /**
+     * Two definitions declare the same `(scope, identifier)`. Every lookup resolves the FIRST, so
+     * the second is unreachable while silently sharing the first's count — the shape that made
+     * identifier-only lookup unsafe in the first place. Two definitions at DIFFERENT scopes are
+     * fine and are exactly what the key makes reachable.
+     */
+    DUPLICATE_DEFINITION_KEY = "duplicate_definition_key",
+    /**
+     * An identifier contains the key separator, which would make its key and every reference built
+     * from it parse into the wrong parts. Refused rather than escaped: a positional format with an
+     * escaping rule is a format two implementations will eventually disagree about.
+     */
+    IDENTIFIER_CONTAINS_KEY_SEPARATOR = "identifier_contains_key_separator",
+    /** An operation declares a `badgeRef` that names no registered definition. */
+    OPERATION_REF_UNRESOLVED = "operation_ref_unresolved"
+}
+/** One refused declaration, carrying enough to name the author's own file without re-deriving it. */
+export interface NotificationBadgeDeclarationViolation {
+    reason: NotificationBadgeDeclarationViolationReason;
+    /** The badge key at issue — the definition's, or the unresolved `badgeRef` as authored. */
+    badgeKey: string;
+    /** Present when the violation belongs to a definition rather than to an operation declaration. */
+    identifier?: NotificationBadgeIdentifier;
+    /** Present when the violation belongs to an operation declaration. */
+    resourceType?: string;
+    /** Present when the violation belongs to an operation declaration. */
+    operationIdentifier?: string;
+}
+/** Where an operation declared a badge reference — one row per authored `notificationBadgeOperations` entry. */
+export interface NotificationBadgeOperationDeclarationSite {
+    resourceType: string;
+    operationIdentifier: string;
+    badgeRef: string;
+}
+/**
+ * The whole declaration-coherence check, as a pure function over what an application declared.
+ *
+ * Pure and shared on purpose: the backend registry runs it as a fail-closed boot gate and the
+ * frontend launcher verifier reports it in development, and a second implementation is how the two
+ * come to disagree about what a valid declaration is.
+ *
+ * It answers the question `derive-before-you-ask.md` asks — who owes this, and what says so. The
+ * population is exactly the registered definitions plus every authored
+ * `notificationBadgeOperations` entry; nothing is inferred and nothing is sampled.
+ */
+export declare function collectNotificationBadgeDeclarationViolations(definitions: readonly NotificationBadgeDefinition[], operationSites?: readonly NotificationBadgeOperationDeclarationSite[]): NotificationBadgeDeclarationViolation[];
+/**
+ * Index the registered definitions by key, so a dispatch resolves in one lookup rather than a scan.
+ *
+ * Built from the SAME key function the boot check uses, so a definition the boot check accepted is
+ * a definition this map can serve.
+ */
+export declare function buildNotificationBadgeDefinitionIndex(definitions: readonly NotificationBadgeDefinition[]): ReadonlyMap<NotificationBadgeKey, NotificationBadgeDefinition>;
 //# sourceMappingURL=notification-badges.schemas.d.ts.map

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":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AACvE,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAG7E;;;;;;;;GAQG;AACH,eAAO,MAAM,iCAAiC,aAA4E,CAAC;AAE3H;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,uBAAuB;;;EAGlC,CAAC;AAEH,oBAAY,0BAA0B;IAClC,SAAS,cAAc;IACvB,SAAS,cAAc;IACvB,GAAG,QAAQ;IACX,KAAK,UAAU;CAClB;AAED;;;;;;;;;;GAUG;AACH,oBAAY,2BAA2B;IACnC,aAAa,kBAAkB;IAC/B,aAAa,kBAAkB;CAClC;AAED,kFAAkF;AAClF,oBAAY,4BAA4B;IACpC,+CAA+C;IAC/C,GAAG,QAAQ;IACX,wDAAwD;IACxD,KAAK,UAAU;IACf,4DAA4D;IAC5D,IAAI,SAAS;CAChB;AAED;;;GAGG;AACH,oBAAY,sBAAsB;IAC9B,IAAI,SAAS;IACb,uEAAuE;IACvE,WAAW,gBAAgB;IAC3B,iDAAiD;IACjD,YAAY,iBAAiB;CAChC;AAED,+EAA+E;AAC/E,eAAO,MAAM,yCAAyC;;iBAEpD,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,yCAAyC;;;;;iBAKpD,CAAC;AAEH,sDAAsD;AACtD,eAAO,MAAM,6BAA6B;;;;;;;2BAGxC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,8BAA8B;;;;iBAIzC,CAAC;AAYH;;;GAGG;AACH,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;iBAG5C,CAAC;AAkBH,eAAO,MAAM,mCAAmC;;;;;;;;iBAG9C,CAAC;AAEH,eAAO,MAAM,+BAA+B;;;;;;;;iBAG1C,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;4BAGlC,CAAC;AAEH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAC5F,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAC5F,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACxE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACxE,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AACpF,MAAM,MAAM,mCAAmC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yCAAyC,CAAC,CAAC;AAC5G,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC"}
+{"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

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