@wildo-ai/saas-models 1.1.5 → 1.1.6

package/dist/esm/frontend-definitions/settings-destination-ref.definitions.d.ts

@@ -69,6 +69,15 @@ export declare enum EngineSettingsDestinationRef {
     BILLING = "billing",
     /** Organization API keys. Org owner/admin only. */
     API_KEYS = "api-keys",
+    /**
+     * OAuth clients the ORGANIZATION registers — the machine credentials it issues for itself, and the ones an
+     * autonomous agent runs as (#1611). Org owner/admin only.
+     *
+     * The sibling of {@link API_KEYS} for the reason {@link APPLICATION_OAUTH_CLIENTS} is the sibling of the
+     * application's keys: under client-credentials both authenticate the organization's machine principal, so they
+     * are two credential types for one identity. Until #1812 this had no screen, and binding an agent was REST only.
+     */
+    ORGANIZATION_OAUTH_CLIENTS = "organization-oauth-clients",
     /**
      * The tenant's OWN credentials toward third parties — its Slack workspace token, its CRM key.
      *
@@ -97,6 +106,22 @@ export declare enum EngineSettingsDestinationRef {
     SIEM = "siem",
     /** Outbound webhook endpoints and delivery log. */
     WEBHOOKS = "webhooks",
+    /**
+     * Messages other systems sent the application that belong to THIS organization (#1596): what
+     * arrived, whether the handler processed it, and REPLAY for one that died. Org owner/admin only.
+     */
+    INBOUND_DELIVERIES = "inbound-deliveries",
+    /**
+     * The outside firms working in THIS organization (#1597): each relationship with its scope and term,
+     * and the verbs that accept, confine, pause and end it. The client's register of third parties with
+     * access to its data. Placed only by an application whose organization types declare `servesAsProvider`.
+     */
+    SERVICE_PROVIDERS = "service-providers",
+    /**
+     * THIS organization's clients, when it is a service firm (#1597): its engagements, and which of its
+     * people serve which client. Placed only by an application whose organization types declare `servesAsProvider`.
+     */
+    SERVICE_CLIENTS = "service-clients",
     /** The organization's audit log. Org owner/admin only. */
     AUDIT_LOGS = "audit-logs",
     /**
@@ -115,6 +140,29 @@ export declare enum EngineSettingsDestinationRef {
     ORGANIZATION_ENTITLEMENTS = "organization-entitlements",
     /** Referral codes and their redemptions. Organization-scoped despite living in the billing domain. */
     ORGANIZATION_REFERRALS = "organization-referrals",
+    /**
+     * The organization's legal holds (#1634): what is held from deletion, on what ground, placed and released by
+     * whom. `ORG_OWNER`, matching the resource's own READ / LIST roles.
+     */
+    ORGANIZATION_LEGAL_HOLDS = "organization-legal-holds",
+    /**
+     * The domains THIS organization receives and sends mail on (#1600): claim one, publish its ownership TXT record
+     * and the provider's DNS records, verify, remove. Org owner/admin only, matching the resource's ORG_ADMIN verbs.
+     */
+    EMAIL_DOMAINS = "email-domains",
+    /**
+     * The addresses THIS organization — a service firm — keeps on its own verified domain for the clients it serves;
+     * each routes its mail into that client's organization (#1600). Org owner/admin only. Placed only by an application
+     * whose organization types declare `servesAsProvider`.
+     */
+    CLIENT_MAILBOXES = "client-mailboxes",
+    /**
+     * What THIS organization's experts decide about its agents' work (#1599): the override rate per agent, tool, case
+     * and reviewer; whether the content of their corrections is kept, why, and who else may read it; the authorisation
+     * to export them as evaluation data; and the ledger of every export. Org owner/admin only, matching the resources'
+     * ORG_ADMIN verbs and the override-rate route's organization-administrator check.
+     */
+    AGENT_WORK_REVIEW = "agent-work-review",
     /** The application's own descriptive record — name, description, the operator's identity. */
     APPLICATION_GENERAL = "application-general",
     /** Released versions of the application. */
@@ -166,6 +214,19 @@ export declare enum EngineSettingsDestinationRef {
     APPLICATION_SIEM = "application-siem",
     /** Application-wide outbound webhooks, and their delivery log. */
     APPLICATION_WEBHOOKS = "application-webhooks",
+    /**
+     * Messages other systems sent the application that resolved to NO organization — application-scope
+     * and unroutable inbound deliveries (#1596) — with REPLAY for a dead one. The inbound mirror of
+     * {@link APPLICATION_WEBHOOKS}'s delivery log, kept separate because it is a different direction,
+     * a different entitlement and a different operator task.
+     */
+    APPLICATION_INBOUND_DELIVERIES = "application-inbound-deliveries",
+    /**
+     * Whether each declared retention period is being enforced (#1636): one record per retention-sweep run and
+     * bound resource — what it deleted under which period, what a hold kept, and how the run ended. Read-only;
+     * the operator's view of the storage-limitation evidence.
+     */
+    APPLICATION_RETENTION_ENFORCEMENT = "application-retention-enforcement",
     /**
      * The billing CATALOGUE the application sells — products, their prices, and promotions.
      *

package/dist/esm/frontend-definitions/settings-destination-ref.definitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settings-destination-ref.definitions.d.ts","sourceRoot":"","sources":["../../../../src/frontend-definitions/settings-destination-ref.definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,oJAAoJ;AACpJ;;;;;;;;;;;;;;;GAeG;AACH,oBAAY,4BAA4B;IACtC,+CAA+C;IAC/C,OAAO,YAAY;IACnB,wDAAwD;IACxD,QAAQ,aAAa;IACrB,iEAAiE;IACjE,UAAU,eAAe;IACzB,kDAAkD;IAClD,WAAW,gBAAgB;IAC3B,8FAA8F;IAC9F,cAAc,mBAAmB;IACjC,mEAAmE;IACnE,oBAAoB,yBAAyB;IAC7C,kFAAkF;IAClF,OAAO,YAAY;IACnB;;;;;;;OAOG;IACH,kBAAkB,uBAAuB;IACzC,qGAAqG;IACrG,OAAO,YAAY;IACnB,mDAAmD;IACnD,QAAQ,aAAa;IACrB;;;;;;OAMG;IACH,oBAAoB,yBAAyB;IAC7C;;;;;;;;;;OAUG;IACH,uBAAuB,4BAA4B;IACnD,oDAAoD;IACpD,GAAG,QAAQ;IACX,4DAA4D;IAC5D,IAAI,SAAS;IACb,qEAAqE;IACrE,IAAI,SAAS;IACb,mDAAmD;IACnD,QAAQ,aAAa;IACrB,0DAA0D;IAC1D,UAAU,eAAe;IACzB;;;;;;;;;;;;OAYG;IACH,yBAAyB,8BAA8B;IACvD,sGAAsG;IACtG,sBAAsB,2BAA2B;IAejD,6FAA6F;IAC7F,mBAAmB,wBAAwB;IAC3C,4CAA4C;IAC5C,oBAAoB,yBAAyB;IAC7C;;;;;;;OAOG;IACH,yBAAyB,8BAA8B;IACvD;;;;;;;;OAQG;IACH,yBAAyB,8BAA8B;IACvD;;;;;;;OAOG;IACH,sBAAsB,2BAA2B;IACjD,oFAAoF;IACpF,wBAAwB,6BAA6B;IACrD,+FAA+F;IAC/F,oBAAoB,yBAAyB;IAC7C,yFAAyF;IACzF,eAAe,oBAAoB;IACnC;;;;;;;OAOG;IACH,gBAAgB,qBAAqB;IACrC,8EAA8E;IAC9E,gBAAgB,qBAAqB;IACrC,kEAAkE;IAClE,oBAAoB,yBAAyB;IAC7C;;;;;;OAMG;IACH,eAAe,oBAAoB;CACpC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,4EAA4E;AAE5E;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,gCAAgC,EAAE,WAAW,CAAC,MAAM,CAAgE,CAAC"}
+{"version":3,"file":"settings-destination-ref.definitions.d.ts","sourceRoot":"","sources":["../../../../src/frontend-definitions/settings-destination-ref.definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,oJAAoJ;AACpJ;;;;;;;;;;;;;;;GAeG;AACH,oBAAY,4BAA4B;IACtC,+CAA+C;IAC/C,OAAO,YAAY;IACnB,wDAAwD;IACxD,QAAQ,aAAa;IACrB,iEAAiE;IACjE,UAAU,eAAe;IACzB,kDAAkD;IAClD,WAAW,gBAAgB;IAC3B,8FAA8F;IAC9F,cAAc,mBAAmB;IACjC,mEAAmE;IACnE,oBAAoB,yBAAyB;IAC7C,kFAAkF;IAClF,OAAO,YAAY;IACnB;;;;;;;OAOG;IACH,kBAAkB,uBAAuB;IACzC,qGAAqG;IACrG,OAAO,YAAY;IACnB,mDAAmD;IACnD,QAAQ,aAAa;IACrB;;;;;;;OAOG;IACH,0BAA0B,+BAA+B;IACzD;;;;;;OAMG;IACH,oBAAoB,yBAAyB;IAC7C;;;;;;;;;;OAUG;IACH,uBAAuB,4BAA4B;IACnD,oDAAoD;IACpD,GAAG,QAAQ;IACX,4DAA4D;IAC5D,IAAI,SAAS;IACb,qEAAqE;IACrE,IAAI,SAAS;IACb,mDAAmD;IACnD,QAAQ,aAAa;IACrB;;;OAGG;IACH,kBAAkB,uBAAuB;IACzC;;;;OAIG;IACH,iBAAiB,sBAAsB;IACvC;;;OAGG;IACH,eAAe,oBAAoB;IACnC,0DAA0D;IAC1D,UAAU,eAAe;IACzB;;;;;;;;;;;;OAYG;IACH,yBAAyB,8BAA8B;IACvD,sGAAsG;IACtG,sBAAsB,2BAA2B;IACjD;;;OAGG;IACH,wBAAwB,6BAA6B;IACrD;;;OAGG;IACH,aAAa,kBAAkB;IAC/B;;;;OAIG;IACH,gBAAgB,qBAAqB;IACrC;;;;;OAKG;IACH,iBAAiB,sBAAsB;IAevC,6FAA6F;IAC7F,mBAAmB,wBAAwB;IAC3C,4CAA4C;IAC5C,oBAAoB,yBAAyB;IAC7C;;;;;;;OAOG;IACH,yBAAyB,8BAA8B;IACvD;;;;;;;;OAQG;IACH,yBAAyB,8BAA8B;IACvD;;;;;;;OAOG;IACH,sBAAsB,2BAA2B;IACjD,oFAAoF;IACpF,wBAAwB,6BAA6B;IACrD,+FAA+F;IAC/F,oBAAoB,yBAAyB;IAC7C,yFAAyF;IACzF,eAAe,oBAAoB;IACnC;;;;;;;OAOG;IACH,gBAAgB,qBAAqB;IACrC,8EAA8E;IAC9E,gBAAgB,qBAAqB;IACrC,kEAAkE;IAClE,oBAAoB,yBAAyB;IAC7C;;;;;OAKG;IACH,8BAA8B,mCAAmC;IACjE;;;;OAIG;IACH,iCAAiC,sCAAsC;IACvE;;;;;;OAMG;IACH,eAAe,oBAAoB;CACpC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,4EAA4E;AAE5E;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,gCAAgC,EAAE,WAAW,CAAC,MAAM,CAAgE,CAAC"}

package/dist/esm/frontend-definitions/settings-destination-ref.definitions.js

@@ -70,6 +70,15 @@ export var EngineSettingsDestinationRef;
     EngineSettingsDestinationRef["BILLING"] = "billing";
     /** Organization API keys. Org owner/admin only. */
     EngineSettingsDestinationRef["API_KEYS"] = "api-keys";
+    /**
+     * OAuth clients the ORGANIZATION registers — the machine credentials it issues for itself, and the ones an
+     * autonomous agent runs as (#1611). Org owner/admin only.
+     *
+     * The sibling of {@link API_KEYS} for the reason {@link APPLICATION_OAUTH_CLIENTS} is the sibling of the
+     * application's keys: under client-credentials both authenticate the organization's machine principal, so they
+     * are two credential types for one identity. Until #1812 this had no screen, and binding an agent was REST only.
+     */
+    EngineSettingsDestinationRef["ORGANIZATION_OAUTH_CLIENTS"] = "organization-oauth-clients";
     /**
      * The tenant's OWN credentials toward third parties — its Slack workspace token, its CRM key.
      *
@@ -98,6 +107,22 @@ export var EngineSettingsDestinationRef;
     EngineSettingsDestinationRef["SIEM"] = "siem";
     /** Outbound webhook endpoints and delivery log. */
     EngineSettingsDestinationRef["WEBHOOKS"] = "webhooks";
+    /**
+     * Messages other systems sent the application that belong to THIS organization (#1596): what
+     * arrived, whether the handler processed it, and REPLAY for one that died. Org owner/admin only.
+     */
+    EngineSettingsDestinationRef["INBOUND_DELIVERIES"] = "inbound-deliveries";
+    /**
+     * The outside firms working in THIS organization (#1597): each relationship with its scope and term,
+     * and the verbs that accept, confine, pause and end it. The client's register of third parties with
+     * access to its data. Placed only by an application whose organization types declare `servesAsProvider`.
+     */
+    EngineSettingsDestinationRef["SERVICE_PROVIDERS"] = "service-providers";
+    /**
+     * THIS organization's clients, when it is a service firm (#1597): its engagements, and which of its
+     * people serve which client. Placed only by an application whose organization types declare `servesAsProvider`.
+     */
+    EngineSettingsDestinationRef["SERVICE_CLIENTS"] = "service-clients";
     /** The organization's audit log. Org owner/admin only. */
     EngineSettingsDestinationRef["AUDIT_LOGS"] = "audit-logs";
     /**
@@ -116,6 +141,29 @@ export var EngineSettingsDestinationRef;
     EngineSettingsDestinationRef["ORGANIZATION_ENTITLEMENTS"] = "organization-entitlements";
     /** Referral codes and their redemptions. Organization-scoped despite living in the billing domain. */
     EngineSettingsDestinationRef["ORGANIZATION_REFERRALS"] = "organization-referrals";
+    /**
+     * The organization's legal holds (#1634): what is held from deletion, on what ground, placed and released by
+     * whom. `ORG_OWNER`, matching the resource's own READ / LIST roles.
+     */
+    EngineSettingsDestinationRef["ORGANIZATION_LEGAL_HOLDS"] = "organization-legal-holds";
+    /**
+     * The domains THIS organization receives and sends mail on (#1600): claim one, publish its ownership TXT record
+     * and the provider's DNS records, verify, remove. Org owner/admin only, matching the resource's ORG_ADMIN verbs.
+     */
+    EngineSettingsDestinationRef["EMAIL_DOMAINS"] = "email-domains";
+    /**
+     * The addresses THIS organization — a service firm — keeps on its own verified domain for the clients it serves;
+     * each routes its mail into that client's organization (#1600). Org owner/admin only. Placed only by an application
+     * whose organization types declare `servesAsProvider`.
+     */
+    EngineSettingsDestinationRef["CLIENT_MAILBOXES"] = "client-mailboxes";
+    /**
+     * What THIS organization's experts decide about its agents' work (#1599): the override rate per agent, tool, case
+     * and reviewer; whether the content of their corrections is kept, why, and who else may read it; the authorisation
+     * to export them as evaluation data; and the ledger of every export. Org owner/admin only, matching the resources'
+     * ORG_ADMIN verbs and the override-rate route's organization-administrator check.
+     */
+    EngineSettingsDestinationRef["AGENT_WORK_REVIEW"] = "agent-work-review";
     // ── Application administration ──────────────────────────────────────────────
     //
     // Everything below is `ResourcePrimaryScope.APPLICATION`: it configures the APPLICATION ITSELF
@@ -179,6 +227,19 @@ export var EngineSettingsDestinationRef;
     EngineSettingsDestinationRef["APPLICATION_SIEM"] = "application-siem";
     /** Application-wide outbound webhooks, and their delivery log. */
     EngineSettingsDestinationRef["APPLICATION_WEBHOOKS"] = "application-webhooks";
+    /**
+     * Messages other systems sent the application that resolved to NO organization — application-scope
+     * and unroutable inbound deliveries (#1596) — with REPLAY for a dead one. The inbound mirror of
+     * {@link APPLICATION_WEBHOOKS}'s delivery log, kept separate because it is a different direction,
+     * a different entitlement and a different operator task.
+     */
+    EngineSettingsDestinationRef["APPLICATION_INBOUND_DELIVERIES"] = "application-inbound-deliveries";
+    /**
+     * Whether each declared retention period is being enforced (#1636): one record per retention-sweep run and
+     * bound resource — what it deleted under which period, what a hold kept, and how the run ended. Read-only;
+     * the operator's view of the storage-limitation evidence.
+     */
+    EngineSettingsDestinationRef["APPLICATION_RETENTION_ENFORCEMENT"] = "application-retention-enforcement";
     /**
      * The billing CATALOGUE the application sells — products, their prices, and promotions.
      *

package/dist/esm/frontend-definitions/settings-destination-ref.definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"settings-destination-ref.definitions.js","sourceRoot":"","sources":["../../../../src/frontend-definitions/settings-destination-ref.definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,oJAAoJ;AACpJ;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAN,IAAY,4BAmJX;AAnJD,WAAY,4BAA4B;IACtC,+CAA+C;IAC/C,mDAAmB,CAAA;IACnB,wDAAwD;IACxD,qDAAqB,CAAA;IACrB,iEAAiE;IACjE,yDAAyB,CAAA;IACzB,kDAAkD;IAClD,2DAA2B,CAAA;IAC3B,8FAA8F;IAC9F,iEAAiC,CAAA;IACjC,mEAAmE;IACnE,6EAA6C,CAAA;IAC7C,kFAAkF;IAClF,mDAAmB,CAAA;IACnB;;;;;;;OAOG;IACH,yEAAyC,CAAA;IACzC,qGAAqG;IACrG,mDAAmB,CAAA;IACnB,mDAAmD;IACnD,qDAAqB,CAAA;IACrB;;;;;;OAMG;IACH,6EAA6C,CAAA;IAC7C;;;;;;;;;;OAUG;IACH,mFAAmD,CAAA;IACnD,oDAAoD;IACpD,2CAAW,CAAA;IACX,4DAA4D;IAC5D,6CAAa,CAAA;IACb,qEAAqE;IACrE,6CAAa,CAAA;IACb,mDAAmD;IACnD,qDAAqB,CAAA;IACrB,0DAA0D;IAC1D,yDAAyB,CAAA;IACzB;;;;;;;;;;;;OAYG;IACH,uFAAuD,CAAA;IACvD,sGAAsG;IACtG,iFAAiD,CAAA;IAEjD,+EAA+E;IAC/E,EAAE;IACF,+FAA+F;IAC/F,4FAA4F;IAC5F,2EAA2E;IAC3E,4FAA4F;IAC5F,4FAA4F;IAC5F,EAAE;IACF,wFAAwF;IACxF,gGAAgG;IAChG,+FAA+F;IAC/F,0EAA0E;IAE1E,6FAA6F;IAC7F,2EAA2C,CAAA;IAC3C,4CAA4C;IAC5C,6EAA6C,CAAA;IAC7C;;;;;;;OAOG;IACH,uFAAuD,CAAA;IACvD;;;;;;;;OAQG;IACH,uFAAuD,CAAA;IACvD;;;;;;;OAOG;IACH,iFAAiD,CAAA;IACjD,oFAAoF;IACpF,qFAAqD,CAAA;IACrD,+FAA+F;IAC/F,6EAA6C,CAAA;IAC7C,yFAAyF;IACzF,mEAAmC,CAAA;IACnC;;;;;;;OAOG;IACH,qEAAqC,CAAA;IACrC,8EAA8E;IAC9E,qEAAqC,CAAA;IACrC,kEAAkE;IAClE,6EAA6C,CAAA;IAC7C;;;;;;OAMG;IACH,mEAAmC,CAAA;AACrC,CAAC,EAnJW,4BAA4B,KAA5B,4BAA4B,QAmJvC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,4EAA4E;AAE5E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAwB,IAAI,GAAG,CAAS,MAAM,CAAC,MAAM,CAAC,4BAA4B,CAAC,CAAC,CAAC","sourcesContent":["/**\n * The IDENTITY half of the engine's settings-hub catalogue — the refs, and nothing else.\n *\n * ## Why the identity lives here and the catalogue does not\n *\n * A settings destination has two halves, and only one of them is a rendering concern:\n *\n * - **What a destination IS** — its `target` (a resource operation, a bespoke engine panel, a set\n *   of sub-tabs), its role gating, its runtime-capability gating. That half names components and\n *   panel refs, so it belongs to `@wildo-ai/saas-frontend-lib`, where `ENGINE_SETTINGS_DESTINATIONS`\n *   declares it.\n * - **WHICH destinations exist** — a closed set of ids. That half names nothing renderable. It is\n *   the vocabulary an application's `SettingsHubConfig` addresses by string, the vocabulary the\n *   app-creation placement plan names in a `PlacementSubject`, and the vocabulary engine code\n *   addresses by enum member. It is declared here.\n *\n * The split was made 2026-09-09 because the second half had a consumer the first half's package\n * could never serve. `validatePlacementPlan`'s `UNKNOWN_SUBJECT` finding is a HARD FLOOR — it\n * refuses a landing — and it can only fire when a caller supplies the universe of subjects that\n * exist. Its one production caller is the app-creation semantic authority, a backend-side package\n * that must not depend on `saas-frontend-lib`. So a declared refusal had no holder, for no reason\n * other than where a list of sixteen strings was written down.\n *\n * Nothing is re-exported across the boundary: `saas-frontend-lib` imports the enum from here and\n * declares only the catalogue.\n */\n\n/** @wildo_source:part:start saas.frontend.settings-hub.engine-destinations facet:layer:frontend facet:family:config facet:audience:app-developer */\n/**\n * Every settings destination the engine ships, as a named vocabulary.\n *\n * Imported from `@wildo-ai/saas-models`. Exists because these refs are a CLOSED\n * vocabulary that engine code addresses by name — the billing command-menu entry\n * opens `/settings/billing`, and any future engine launcher will do the same.\n * Before this enum, `'billing'` was a bare literal in `billing-launcher.ts` with\n * nothing tying it to the catalog entry it names: rename the destination and the\n * command silently resolves to the hub's DEFAULT section instead of failing, so a\n * menu item labelled \"Billing\" would open Profile.\n *\n * **Engine code must address a destination through this enum. Application\n * config addresses one by string**, deliberately: a placement is authored data,\n * an application should not import an engine enum to write its own rail, and a\n * typo there is caught at DEV startup by `verifySettingsHubContent`.\n */\nexport enum EngineSettingsDestinationRef {\n  /** The signed-in user's own profile record. */\n  PROFILE = 'profile',\n  /** Password, MFA, sessions — a bespoke engine panel. */\n  SECURITY = 'security',\n  /** Theme and appearance preferences — a bespoke engine panel. */\n  APPEARANCE = 'appearance',\n  /** The signed-in user's own preference record. */\n  PREFERENCES = 'preferences',\n  /** Invitations addressed TO the signed-in user, across organizations they have not joined. */\n  MY_INVITATIONS = 'my-invitations',\n  /** The current organization's own record. Org owner/admin only. */\n  ORGANIZATION_GENERAL = 'organization-general',\n  /** Organization membership list, including INVITED rows. Org owner/admin only. */\n  MEMBERS = 'members',\n  /**\n   * The organization's internal structure — teams, departments, the hierarchy under the tenant.\n   *\n   * Its own rail entry rather than a tab inside {@link ORGANIZATION_GENERAL}. The general pane is a\n   * record — a column of decisions about the tenant itself — and a unit hierarchy is a population\n   * you navigate, which is a different kind of surface and a different task. Nesting it there also\n   * put it behind a pane a reader had no other reason to open.\n   */\n  ORGANIZATION_UNITS = 'organization-units',\n  /** Billing home — subscription, plans, usage, invoices. Gated on the `billingEnabled` capability. */\n  BILLING = 'billing',\n  /** Organization API keys. Org owner/admin only. */\n  API_KEYS = 'api-keys',\n  /**\n   * The tenant's OWN credentials toward third parties — its Slack workspace token, its CRM key.\n   *\n   * The mirror image of {@link API_KEYS} and easy to confuse with it: an API key is a credential\n   * somebody uses to reach THIS application, and one of these is a credential this application uses\n   * to reach somebody else ON THIS TENANT'S BEHALF. Same administrator, opposite direction.\n   */\n  PROVIDER_CREDENTIALS = 'provider-credentials',\n  /**\n   * The signed-in person's OWN credentials toward third parties — their personal API key, the\n   * account they connected themselves.\n   *\n   * Distinct from {@link PROVIDER_CREDENTIALS} by OWNER, not by feature, and the two must never be\n   * merged into one screen. A tenant's credential is a shared integration an administrator\n   * configures for everyone; this one is an individual's own account, which nobody else may see,\n   * spend or remove. Putting them on one page would put a colleague's personal vendor token in an\n   * administrator's view — and the resource's authorization refuses that, so the screen would show\n   * an empty list nobody could explain.\n   */\n  MY_PROVIDER_CREDENTIALS = 'my-provider-credentials',\n  /** Single sign-on configuration and connections. */\n  SSO = 'sso',\n  /** SCIM directory provisioning configuration and tokens. */\n  SCIM = 'scim',\n  /** Audit-event streaming configuration and failed-delivery queue. */\n  SIEM = 'siem',\n  /** Outbound webhook endpoints and delivery log. */\n  WEBHOOKS = 'webhooks',\n  /** The organization's audit log. Org owner/admin only. */\n  AUDIT_LOGS = 'audit-logs',\n  /**\n   * What THIS organization is currently entitled to — its features, its numeric limits, and the\n   * application-administrator exceptions laid over them.\n   *\n   * Readable by any organization member (`organizationFeatures` READ is `ORG_MEMBER`), which is why\n   * it carries no `requiredRoles`: a member who is told a surface needs an upgrade should be able to\n   * see what their organization actually has. The operations that CHANGE it — enable, disable, reset\n   * — are `APP_ADMIN_SUPER_ADMIN` on the resource itself, so the same screen is a read-only summary\n   * for a member and the grant/withdraw console for a platform administrator.\n   *\n   * Until this existed there was no way to reach the entitlement state from anywhere in the product:\n   * the resource had a table, an admin UI behaviour and three custom operations, and no door.\n   */\n  ORGANIZATION_ENTITLEMENTS = 'organization-entitlements',\n  /** Referral codes and their redemptions. Organization-scoped despite living in the billing domain. */\n  ORGANIZATION_REFERRALS = 'organization-referrals',\n\n  // ── Application administration ──────────────────────────────────────────────\n  //\n  // Everything below is `ResourcePrimaryScope.APPLICATION`: it configures the APPLICATION ITSELF\n  // rather than one tenant inside it, and it is the operator's surface, not a customer's. The\n  // category an application places these in is what supplies that scope, and\n  // `useVisibleSettingsHubConfig` resolves the application id from `appIdentity` — the access\n  // token does not carry one, so a category scoped this way was unreachable until 2026-09-17.\n  //\n  // Each mirrors an organization-scope sibling above, and the pairs are NOT redundant: an\n  // application-wide SSO connection authenticates everybody who is not covered by a tenant's own,\n  // and an application-wide SIEM export carries the operator's own security events rather than a\n  // customer's. Same mechanism, different principal, different consequence.\n\n  /** The application's own descriptive record — name, description, the operator's identity. */\n  APPLICATION_GENERAL = 'application-general',\n  /** Released versions of the application. */\n  APPLICATION_VERSIONS = 'application-versions',\n  /**\n   * OAuth clients registered against the APPLICATION — the credential a machine presents for a\n   * client-credentials or authorization-code exchange.\n   *\n   * The sibling of {@link APPLICATION_API_KEYS} rather than a duplicate of it: under\n   * client-credentials both authenticate the same `APPLICATION_MACHINE` principal, so they are two\n   * credential TYPES for one identity and belong side by side.\n   */\n  APPLICATION_OAUTH_CLIENTS = 'application-oauth-clients',\n  /**\n   * The two-person rule, made reviewable — requested, signed, time-bound elevations over the\n   * application-wide reads.\n   *\n   * Placed because a control of this kind is justified by VISIBILITY rather than by prevention:\n   * it does not stop an operator reading across tenants, it makes a second administrator sign for\n   * it and leaves a record. An elevation nobody can read makes nothing visible, so the mechanism\n   * ran without its own justification until this had a door.\n   */\n  APPLICATION_ACCESS_GRANTS = 'application-access-grants',\n  /**\n   * The application-wide audit trail — every tenant's events plus the ones belonging to no tenant.\n   *\n   * Distinct from the organization {@link AUDIT_LOGS} by the question it answers, not by scope\n   * alone: the tenant door answers \"what happened in my organization\", this one answers \"what\n   * happened at all\", and only the second can support a deployment-level attestation. Every read\n   * through it is a declared crossing and emits one event into each tenant it reached.\n   */\n  APPLICATION_AUDIT_LOGS = 'application-audit-logs',\n  /** The application-scope feature and limit state, with administrator exceptions. */\n  APPLICATION_ENTITLEMENTS = 'application-entitlements',\n  /** API keys that authenticate a machine to the APPLICATION rather than to one organization. */\n  APPLICATION_API_KEYS = 'application-api-keys',\n  /** Application-wide single sign-on: the configuration, and the connections it admits. */\n  APPLICATION_SSO = 'application-sso',\n  /**\n   * Application-wide SCIM directory provisioning.\n   *\n   * One target rather than the organization sibling's two tabs, and that asymmetry is real rather\n   * than an omission: there is no `APPLICATION_SCIM_TOKENS` resource — only\n   * `ORGANIZATION_SCIM_TOKENS` exists — so the application scope has a provisioning configuration\n   * and nothing to tab to.\n   */\n  APPLICATION_SCIM = 'application-scim',\n  /** Application-wide audit-event streaming, and the deliveries that failed. */\n  APPLICATION_SIEM = 'application-siem',\n  /** Application-wide outbound webhooks, and their delivery log. */\n  APPLICATION_WEBHOOKS = 'application-webhooks',\n  /**\n   * The billing CATALOGUE the application sells — products, their prices, and promotions.\n   *\n   * Distinct from the organization `BILLING` destination, which is one tenant's subscription and\n   * invoices. This is the operator editing what is on sale; that is a customer reading what they\n   * bought.\n   */\n  BILLING_CATALOG = 'billing-catalog',\n}\n\n/**\n * ## Two administration surfaces that are DELIBERATELY absent, so neither is re-proposed\n *\n * **A tenant directory.** `organizations` LIST looks like one and is not: it is confined by\n * `assignScopeRootCollectionConfinementToFilter` to the tenants the caller holds an\n * organization-wide role entry for, so a platform super-administrator sees THEIR OWN organizations\n * and not every tenant. That confinement is deliberate — the resource's own banner says so, and\n * says explicitly that an operator who \"cannot find the tenant id\" should stop rather than widen\n * the operation, because widening it hands the full customer list to every platform administrator\n * as a standing privilege. A destination named \"Organizations\" under Administration would promise\n * the directory and deliver the memberships, which is worse than having no entry: the reader\n * cannot tell the difference, and the number looks authoritative.\n *\n * **A user directory.** Same shape one level down. The application-wide user read is gated on a\n * two-person `applicationAccessGrants` window precisely so that it is not a standing privilege, so\n * a permanently-placed rail entry would either sit there refusing or quietly bypass the control it\n * is supposed to pass through.\n *\n * Both become placeable when a governed cross-tenant read exists — an operation that requires the\n * grant and says so. Neither becomes placeable by widening the operation that is already there.\n */\n/** @wildo_source:part:end saas.frontend.settings-hub.engine-destinations */\n\n/**\n * Every destination ref the engine ships — the set an authored placement is validated against.\n *\n * **Derived from the enum, not from the catalogue, and that is the point.** It used to be\n * `ENGINE_SETTINGS_DESTINATIONS.map(d => d.ref)`, which made the set a statement about how many\n * catalogue entries had been written rather than about what the vocabulary contains: a member added\n * to the enum and not yet given a catalogue entry would have been silently absent from the universe\n * a hard floor is measured against, so a placement naming it would have been refused as UNKNOWN.\n * Deriving from the enum is TOTAL over the vocabulary — a member added tomorrow is in this set the\n * same day — and the reverse obligation (every ref has a catalogue entry) is pinned in\n * `saas-frontend-lib`, where the catalogue lives and where an omission is a rendering defect.\n *\n * Values are bare ids, the shape `placementSubjectLocalKey` publishes for\n * `ENGINE_SETTINGS_DESTINATION` subjects, so this set can be handed to `validatePlacementPlan`\n * without being re-spelled.\n */\nexport const ENGINE_SETTINGS_DESTINATION_REFS: ReadonlySet<string> = new Set<string>(Object.values(EngineSettingsDestinationRef));\n"]}
+{"version":3,"file":"settings-destination-ref.definitions.js","sourceRoot":"","sources":["../../../../src/frontend-definitions/settings-destination-ref.definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,oJAAoJ;AACpJ;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAN,IAAY,4BAgNX;AAhND,WAAY,4BAA4B;IACtC,+CAA+C;IAC/C,mDAAmB,CAAA;IACnB,wDAAwD;IACxD,qDAAqB,CAAA;IACrB,iEAAiE;IACjE,yDAAyB,CAAA;IACzB,kDAAkD;IAClD,2DAA2B,CAAA;IAC3B,8FAA8F;IAC9F,iEAAiC,CAAA;IACjC,mEAAmE;IACnE,6EAA6C,CAAA;IAC7C,kFAAkF;IAClF,mDAAmB,CAAA;IACnB;;;;;;;OAOG;IACH,yEAAyC,CAAA;IACzC,qGAAqG;IACrG,mDAAmB,CAAA;IACnB,mDAAmD;IACnD,qDAAqB,CAAA;IACrB;;;;;;;OAOG;IACH,yFAAyD,CAAA;IACzD;;;;;;OAMG;IACH,6EAA6C,CAAA;IAC7C;;;;;;;;;;OAUG;IACH,mFAAmD,CAAA;IACnD,oDAAoD;IACpD,2CAAW,CAAA;IACX,4DAA4D;IAC5D,6CAAa,CAAA;IACb,qEAAqE;IACrE,6CAAa,CAAA;IACb,mDAAmD;IACnD,qDAAqB,CAAA;IACrB;;;OAGG;IACH,yEAAyC,CAAA;IACzC;;;;OAIG;IACH,uEAAuC,CAAA;IACvC;;;OAGG;IACH,mEAAmC,CAAA;IACnC,0DAA0D;IAC1D,yDAAyB,CAAA;IACzB;;;;;;;;;;;;OAYG;IACH,uFAAuD,CAAA;IACvD,sGAAsG;IACtG,iFAAiD,CAAA;IACjD;;;OAGG;IACH,qFAAqD,CAAA;IACrD;;;OAGG;IACH,+DAA+B,CAAA;IAC/B;;;;OAIG;IACH,qEAAqC,CAAA;IACrC;;;;;OAKG;IACH,uEAAuC,CAAA;IAEvC,+EAA+E;IAC/E,EAAE;IACF,+FAA+F;IAC/F,4FAA4F;IAC5F,2EAA2E;IAC3E,4FAA4F;IAC5F,4FAA4F;IAC5F,EAAE;IACF,wFAAwF;IACxF,gGAAgG;IAChG,+FAA+F;IAC/F,0EAA0E;IAE1E,6FAA6F;IAC7F,2EAA2C,CAAA;IAC3C,4CAA4C;IAC5C,6EAA6C,CAAA;IAC7C;;;;;;;OAOG;IACH,uFAAuD,CAAA;IACvD;;;;;;;;OAQG;IACH,uFAAuD,CAAA;IACvD;;;;;;;OAOG;IACH,iFAAiD,CAAA;IACjD,oFAAoF;IACpF,qFAAqD,CAAA;IACrD,+FAA+F;IAC/F,6EAA6C,CAAA;IAC7C,yFAAyF;IACzF,mEAAmC,CAAA;IACnC;;;;;;;OAOG;IACH,qEAAqC,CAAA;IACrC,8EAA8E;IAC9E,qEAAqC,CAAA;IACrC,kEAAkE;IAClE,6EAA6C,CAAA;IAC7C;;;;;OAKG;IACH,iGAAiE,CAAA;IACjE;;;;OAIG;IACH,uGAAuE,CAAA;IACvE;;;;;;OAMG;IACH,mEAAmC,CAAA;AACrC,CAAC,EAhNW,4BAA4B,KAA5B,4BAA4B,QAgNvC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,4EAA4E;AAE5E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAwB,IAAI,GAAG,CAAS,MAAM,CAAC,MAAM,CAAC,4BAA4B,CAAC,CAAC,CAAC","sourcesContent":["/**\n * The IDENTITY half of the engine's settings-hub catalogue — the refs, and nothing else.\n *\n * ## Why the identity lives here and the catalogue does not\n *\n * A settings destination has two halves, and only one of them is a rendering concern:\n *\n * - **What a destination IS** — its `target` (a resource operation, a bespoke engine panel, a set\n *   of sub-tabs), its role gating, its runtime-capability gating. That half names components and\n *   panel refs, so it belongs to `@wildo-ai/saas-frontend-lib`, where `ENGINE_SETTINGS_DESTINATIONS`\n *   declares it.\n * - **WHICH destinations exist** — a closed set of ids. That half names nothing renderable. It is\n *   the vocabulary an application's `SettingsHubConfig` addresses by string, the vocabulary the\n *   app-creation placement plan names in a `PlacementSubject`, and the vocabulary engine code\n *   addresses by enum member. It is declared here.\n *\n * The split was made 2026-09-09 because the second half had a consumer the first half's package\n * could never serve. `validatePlacementPlan`'s `UNKNOWN_SUBJECT` finding is a HARD FLOOR — it\n * refuses a landing — and it can only fire when a caller supplies the universe of subjects that\n * exist. Its one production caller is the app-creation semantic authority, a backend-side package\n * that must not depend on `saas-frontend-lib`. So a declared refusal had no holder, for no reason\n * other than where a list of sixteen strings was written down.\n *\n * Nothing is re-exported across the boundary: `saas-frontend-lib` imports the enum from here and\n * declares only the catalogue.\n */\n\n/** @wildo_source:part:start saas.frontend.settings-hub.engine-destinations facet:layer:frontend facet:family:config facet:audience:app-developer */\n/**\n * Every settings destination the engine ships, as a named vocabulary.\n *\n * Imported from `@wildo-ai/saas-models`. Exists because these refs are a CLOSED\n * vocabulary that engine code addresses by name — the billing command-menu entry\n * opens `/settings/billing`, and any future engine launcher will do the same.\n * Before this enum, `'billing'` was a bare literal in `billing-launcher.ts` with\n * nothing tying it to the catalog entry it names: rename the destination and the\n * command silently resolves to the hub's DEFAULT section instead of failing, so a\n * menu item labelled \"Billing\" would open Profile.\n *\n * **Engine code must address a destination through this enum. Application\n * config addresses one by string**, deliberately: a placement is authored data,\n * an application should not import an engine enum to write its own rail, and a\n * typo there is caught at DEV startup by `verifySettingsHubContent`.\n */\nexport enum EngineSettingsDestinationRef {\n  /** The signed-in user's own profile record. */\n  PROFILE = 'profile',\n  /** Password, MFA, sessions — a bespoke engine panel. */\n  SECURITY = 'security',\n  /** Theme and appearance preferences — a bespoke engine panel. */\n  APPEARANCE = 'appearance',\n  /** The signed-in user's own preference record. */\n  PREFERENCES = 'preferences',\n  /** Invitations addressed TO the signed-in user, across organizations they have not joined. */\n  MY_INVITATIONS = 'my-invitations',\n  /** The current organization's own record. Org owner/admin only. */\n  ORGANIZATION_GENERAL = 'organization-general',\n  /** Organization membership list, including INVITED rows. Org owner/admin only. */\n  MEMBERS = 'members',\n  /**\n   * The organization's internal structure — teams, departments, the hierarchy under the tenant.\n   *\n   * Its own rail entry rather than a tab inside {@link ORGANIZATION_GENERAL}. The general pane is a\n   * record — a column of decisions about the tenant itself — and a unit hierarchy is a population\n   * you navigate, which is a different kind of surface and a different task. Nesting it there also\n   * put it behind a pane a reader had no other reason to open.\n   */\n  ORGANIZATION_UNITS = 'organization-units',\n  /** Billing home — subscription, plans, usage, invoices. Gated on the `billingEnabled` capability. */\n  BILLING = 'billing',\n  /** Organization API keys. Org owner/admin only. */\n  API_KEYS = 'api-keys',\n  /**\n   * OAuth clients the ORGANIZATION registers — the machine credentials it issues for itself, and the ones an\n   * autonomous agent runs as (#1611). Org owner/admin only.\n   *\n   * The sibling of {@link API_KEYS} for the reason {@link APPLICATION_OAUTH_CLIENTS} is the sibling of the\n   * application's keys: under client-credentials both authenticate the organization's machine principal, so they\n   * are two credential types for one identity. Until #1812 this had no screen, and binding an agent was REST only.\n   */\n  ORGANIZATION_OAUTH_CLIENTS = 'organization-oauth-clients',\n  /**\n   * The tenant's OWN credentials toward third parties — its Slack workspace token, its CRM key.\n   *\n   * The mirror image of {@link API_KEYS} and easy to confuse with it: an API key is a credential\n   * somebody uses to reach THIS application, and one of these is a credential this application uses\n   * to reach somebody else ON THIS TENANT'S BEHALF. Same administrator, opposite direction.\n   */\n  PROVIDER_CREDENTIALS = 'provider-credentials',\n  /**\n   * The signed-in person's OWN credentials toward third parties — their personal API key, the\n   * account they connected themselves.\n   *\n   * Distinct from {@link PROVIDER_CREDENTIALS} by OWNER, not by feature, and the two must never be\n   * merged into one screen. A tenant's credential is a shared integration an administrator\n   * configures for everyone; this one is an individual's own account, which nobody else may see,\n   * spend or remove. Putting them on one page would put a colleague's personal vendor token in an\n   * administrator's view — and the resource's authorization refuses that, so the screen would show\n   * an empty list nobody could explain.\n   */\n  MY_PROVIDER_CREDENTIALS = 'my-provider-credentials',\n  /** Single sign-on configuration and connections. */\n  SSO = 'sso',\n  /** SCIM directory provisioning configuration and tokens. */\n  SCIM = 'scim',\n  /** Audit-event streaming configuration and failed-delivery queue. */\n  SIEM = 'siem',\n  /** Outbound webhook endpoints and delivery log. */\n  WEBHOOKS = 'webhooks',\n  /**\n   * Messages other systems sent the application that belong to THIS organization (#1596): what\n   * arrived, whether the handler processed it, and REPLAY for one that died. Org owner/admin only.\n   */\n  INBOUND_DELIVERIES = 'inbound-deliveries',\n  /**\n   * The outside firms working in THIS organization (#1597): each relationship with its scope and term,\n   * and the verbs that accept, confine, pause and end it. The client's register of third parties with\n   * access to its data. Placed only by an application whose organization types declare `servesAsProvider`.\n   */\n  SERVICE_PROVIDERS = 'service-providers',\n  /**\n   * THIS organization's clients, when it is a service firm (#1597): its engagements, and which of its\n   * people serve which client. Placed only by an application whose organization types declare `servesAsProvider`.\n   */\n  SERVICE_CLIENTS = 'service-clients',\n  /** The organization's audit log. Org owner/admin only. */\n  AUDIT_LOGS = 'audit-logs',\n  /**\n   * What THIS organization is currently entitled to — its features, its numeric limits, and the\n   * application-administrator exceptions laid over them.\n   *\n   * Readable by any organization member (`organizationFeatures` READ is `ORG_MEMBER`), which is why\n   * it carries no `requiredRoles`: a member who is told a surface needs an upgrade should be able to\n   * see what their organization actually has. The operations that CHANGE it — enable, disable, reset\n   * — are `APP_ADMIN_SUPER_ADMIN` on the resource itself, so the same screen is a read-only summary\n   * for a member and the grant/withdraw console for a platform administrator.\n   *\n   * Until this existed there was no way to reach the entitlement state from anywhere in the product:\n   * the resource had a table, an admin UI behaviour and three custom operations, and no door.\n   */\n  ORGANIZATION_ENTITLEMENTS = 'organization-entitlements',\n  /** Referral codes and their redemptions. Organization-scoped despite living in the billing domain. */\n  ORGANIZATION_REFERRALS = 'organization-referrals',\n  /**\n   * The organization's legal holds (#1634): what is held from deletion, on what ground, placed and released by\n   * whom. `ORG_OWNER`, matching the resource's own READ / LIST roles.\n   */\n  ORGANIZATION_LEGAL_HOLDS = 'organization-legal-holds',\n  /**\n   * The domains THIS organization receives and sends mail on (#1600): claim one, publish its ownership TXT record\n   * and the provider's DNS records, verify, remove. Org owner/admin only, matching the resource's ORG_ADMIN verbs.\n   */\n  EMAIL_DOMAINS = 'email-domains',\n  /**\n   * The addresses THIS organization — a service firm — keeps on its own verified domain for the clients it serves;\n   * each routes its mail into that client's organization (#1600). Org owner/admin only. Placed only by an application\n   * whose organization types declare `servesAsProvider`.\n   */\n  CLIENT_MAILBOXES = 'client-mailboxes',\n  /**\n   * What THIS organization's experts decide about its agents' work (#1599): the override rate per agent, tool, case\n   * and reviewer; whether the content of their corrections is kept, why, and who else may read it; the authorisation\n   * to export them as evaluation data; and the ledger of every export. Org owner/admin only, matching the resources'\n   * ORG_ADMIN verbs and the override-rate route's organization-administrator check.\n   */\n  AGENT_WORK_REVIEW = 'agent-work-review',\n\n  // ── Application administration ──────────────────────────────────────────────\n  //\n  // Everything below is `ResourcePrimaryScope.APPLICATION`: it configures the APPLICATION ITSELF\n  // rather than one tenant inside it, and it is the operator's surface, not a customer's. The\n  // category an application places these in is what supplies that scope, and\n  // `useVisibleSettingsHubConfig` resolves the application id from `appIdentity` — the access\n  // token does not carry one, so a category scoped this way was unreachable until 2026-09-17.\n  //\n  // Each mirrors an organization-scope sibling above, and the pairs are NOT redundant: an\n  // application-wide SSO connection authenticates everybody who is not covered by a tenant's own,\n  // and an application-wide SIEM export carries the operator's own security events rather than a\n  // customer's. Same mechanism, different principal, different consequence.\n\n  /** The application's own descriptive record — name, description, the operator's identity. */\n  APPLICATION_GENERAL = 'application-general',\n  /** Released versions of the application. */\n  APPLICATION_VERSIONS = 'application-versions',\n  /**\n   * OAuth clients registered against the APPLICATION — the credential a machine presents for a\n   * client-credentials or authorization-code exchange.\n   *\n   * The sibling of {@link APPLICATION_API_KEYS} rather than a duplicate of it: under\n   * client-credentials both authenticate the same `APPLICATION_MACHINE` principal, so they are two\n   * credential TYPES for one identity and belong side by side.\n   */\n  APPLICATION_OAUTH_CLIENTS = 'application-oauth-clients',\n  /**\n   * The two-person rule, made reviewable — requested, signed, time-bound elevations over the\n   * application-wide reads.\n   *\n   * Placed because a control of this kind is justified by VISIBILITY rather than by prevention:\n   * it does not stop an operator reading across tenants, it makes a second administrator sign for\n   * it and leaves a record. An elevation nobody can read makes nothing visible, so the mechanism\n   * ran without its own justification until this had a door.\n   */\n  APPLICATION_ACCESS_GRANTS = 'application-access-grants',\n  /**\n   * The application-wide audit trail — every tenant's events plus the ones belonging to no tenant.\n   *\n   * Distinct from the organization {@link AUDIT_LOGS} by the question it answers, not by scope\n   * alone: the tenant door answers \"what happened in my organization\", this one answers \"what\n   * happened at all\", and only the second can support a deployment-level attestation. Every read\n   * through it is a declared crossing and emits one event into each tenant it reached.\n   */\n  APPLICATION_AUDIT_LOGS = 'application-audit-logs',\n  /** The application-scope feature and limit state, with administrator exceptions. */\n  APPLICATION_ENTITLEMENTS = 'application-entitlements',\n  /** API keys that authenticate a machine to the APPLICATION rather than to one organization. */\n  APPLICATION_API_KEYS = 'application-api-keys',\n  /** Application-wide single sign-on: the configuration, and the connections it admits. */\n  APPLICATION_SSO = 'application-sso',\n  /**\n   * Application-wide SCIM directory provisioning.\n   *\n   * One target rather than the organization sibling's two tabs, and that asymmetry is real rather\n   * than an omission: there is no `APPLICATION_SCIM_TOKENS` resource — only\n   * `ORGANIZATION_SCIM_TOKENS` exists — so the application scope has a provisioning configuration\n   * and nothing to tab to.\n   */\n  APPLICATION_SCIM = 'application-scim',\n  /** Application-wide audit-event streaming, and the deliveries that failed. */\n  APPLICATION_SIEM = 'application-siem',\n  /** Application-wide outbound webhooks, and their delivery log. */\n  APPLICATION_WEBHOOKS = 'application-webhooks',\n  /**\n   * Messages other systems sent the application that resolved to NO organization — application-scope\n   * and unroutable inbound deliveries (#1596) — with REPLAY for a dead one. The inbound mirror of\n   * {@link APPLICATION_WEBHOOKS}'s delivery log, kept separate because it is a different direction,\n   * a different entitlement and a different operator task.\n   */\n  APPLICATION_INBOUND_DELIVERIES = 'application-inbound-deliveries',\n  /**\n   * Whether each declared retention period is being enforced (#1636): one record per retention-sweep run and\n   * bound resource — what it deleted under which period, what a hold kept, and how the run ended. Read-only;\n   * the operator's view of the storage-limitation evidence.\n   */\n  APPLICATION_RETENTION_ENFORCEMENT = 'application-retention-enforcement',\n  /**\n   * The billing CATALOGUE the application sells — products, their prices, and promotions.\n   *\n   * Distinct from the organization `BILLING` destination, which is one tenant's subscription and\n   * invoices. This is the operator editing what is on sale; that is a customer reading what they\n   * bought.\n   */\n  BILLING_CATALOG = 'billing-catalog',\n}\n\n/**\n * ## Two administration surfaces that are DELIBERATELY absent, so neither is re-proposed\n *\n * **A tenant directory.** `organizations` LIST looks like one and is not: it is confined by\n * `assignScopeRootCollectionConfinementToFilter` to the tenants the caller holds an\n * organization-wide role entry for, so a platform super-administrator sees THEIR OWN organizations\n * and not every tenant. That confinement is deliberate — the resource's own banner says so, and\n * says explicitly that an operator who \"cannot find the tenant id\" should stop rather than widen\n * the operation, because widening it hands the full customer list to every platform administrator\n * as a standing privilege. A destination named \"Organizations\" under Administration would promise\n * the directory and deliver the memberships, which is worse than having no entry: the reader\n * cannot tell the difference, and the number looks authoritative.\n *\n * **A user directory.** Same shape one level down. The application-wide user read is gated on a\n * two-person `applicationAccessGrants` window precisely so that it is not a standing privilege, so\n * a permanently-placed rail entry would either sit there refusing or quietly bypass the control it\n * is supposed to pass through.\n *\n * Both become placeable when a governed cross-tenant read exists — an operation that requires the\n * grant and says so. Neither becomes placeable by widening the operation that is already there.\n */\n/** @wildo_source:part:end saas.frontend.settings-hub.engine-destinations */\n\n/**\n * Every destination ref the engine ships — the set an authored placement is validated against.\n *\n * **Derived from the enum, not from the catalogue, and that is the point.** It used to be\n * `ENGINE_SETTINGS_DESTINATIONS.map(d => d.ref)`, which made the set a statement about how many\n * catalogue entries had been written rather than about what the vocabulary contains: a member added\n * to the enum and not yet given a catalogue entry would have been silently absent from the universe\n * a hard floor is measured against, so a placement naming it would have been refused as UNKNOWN.\n * Deriving from the enum is TOTAL over the vocabulary — a member added tomorrow is in this set the\n * same day — and the reverse obligation (every ref has a catalogue entry) is pinned in\n * `saas-frontend-lib`, where the catalogue lives and where an omission is a rendering defect.\n *\n * Values are bare ids, the shape `placementSubjectLocalKey` publishes for\n * `ENGINE_SETTINGS_DESTINATION` subjects, so this set can be handed to `validatePlacementPlan`\n * without being re-spelled.\n */\nexport const ENGINE_SETTINGS_DESTINATION_REFS: ReadonlySet<string> = new Set<string>(Object.values(EngineSettingsDestinationRef));\n"]}

package/dist/esm/guidance/guidance-state.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guidance-state.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/guidance/guidance-state.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AAIhF;;oEAEoE;AAEpE,mCAAmC;AACnC,eAAO,MAAM,0BAA0B;;;;;iBASrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E;;oEAEoE;AAEpE,qBAAqB;AACrB,eAAO,MAAM,uBAAuB;;;;;;;;;;;;iBASlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;oEAEoE;AAEpE;;wDAEwD;AACxD,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;iBAa9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;iBAElC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;iBAE1C,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF,MAAM,MAAM,sBAAsB,GAAG,iBAAiB,GAAG,yBAAyB,CAAC"}
+{"version":3,"file":"guidance-state.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/guidance/guidance-state.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AAIhF;;oEAEoE;AAEpE,mCAAmC;AACnC,eAAO,MAAM,0BAA0B;;;;;iBAUrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E;;oEAEoE;AAEpE,qBAAqB;AACrB,eAAO,MAAM,uBAAuB;;;;;;;;;;;;iBASlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;oEAEoE;AAEpE;;wDAEwD;AACxD,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;iBAa9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;iBAElC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;iBAE1C,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF,MAAM,MAAM,sBAAsB,GAAG,iBAAiB,GAAG,yBAAyB,CAAC"}

package/dist/esm/guidance/guidance-state.shared.schemas.js

@@ -8,28 +8,29 @@ import { addImpersonalizeWith } from '@wildo-ai/zod-decorators';
  * ────────────────────────────────────────────────────────────── */
 /** Per-element completion state */
 export const GuidanceElementStateSchema = z.object({
-    status: z.enum(OnboardingStatus),
+    status: z.enum(OnboardingStatus).describe('Where this element stands. The guidance engine records an element when it is completed.'),
     /** Timestamp when this element was completed.
      *  Uses z.coerce.date() to handle string → Date coercion on parse (stored as ISO strings in DB). */
-    completedAt: z.coerce.date().optional(),
+    completedAt: z.coerce.date().optional().describe('When this element was completed.'),
     /** For surveys: submitted answers */
-    surveyAnswers: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.array(z.string())])).optional(),
+    surveyAnswers: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.array(z.string())])).optional()
+        .describe('For a survey element, the submitted answers, keyed by question id. Absent for other element types.'),
     /** For tours: last completed step index */
-    lastStepIndex: z.number().int().optional(),
+    lastStepIndex: z.number().int().optional().describe('For a tour element, the zero-based index of the step on which the tour was finished. Absent for other element types.'),
 });
 /** ──────────────────────────────────────────────────────────────
  * Guidance State — Per-Flow State
  * ────────────────────────────────────────────────────────────── */
 /** Per-flow state */
 export const GuidanceFlowStateSchema = z.object({
-    status: z.enum(OnboardingStatus),
-    startedAt: z.coerce.date().optional(),
-    completedAt: z.coerce.date().optional(),
-    dismissedAt: z.coerce.date().optional(),
+    status: z.enum(OnboardingStatus).describe('Where this flow stands. `completed`, `skipped` and `dismissed` are final: a flow in one of them is not shown again.'),
+    startedAt: z.coerce.date().optional().describe('When the flow was first shown.'),
+    completedAt: z.coerce.date().optional().describe('When the flow was completed.'),
+    dismissedAt: z.coerce.date().optional().describe('When the flow was dismissed. Absent unless it was.'),
     /** Element-level state keyed by element ref */
-    elements: z.record(z.string(), GuidanceElementStateSchema).default({}),
+    elements: z.record(z.string(), GuidanceElementStateSchema).default({}).describe('Progress on the flow\'s individual elements, keyed by element reference. Elements not yet completed are absent.'),
     /** How many times this flow has been triggered */
-    triggerCount: z.number().int().default(0),
+    triggerCount: z.number().int().default(0).describe('How many times the flow has been shown. A first-visit flow is shown only while this is 0.'),
 });
 /** ──────────────────────────────────────────────────────────────
  * Guidance State — Top-Level Document

package/dist/esm/guidance/guidance-state.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"guidance-state.shared.schemas.js","sourceRoot":"","sources":["../../../../src/guidance/guidance-state.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\nimport { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas';\nimport { OnboardingStatus } from '../config/frontend/onboarding.shared.schemas';\nimport { RedactionType } from '../compliance/privacy/redaction.shared.schemas';\nimport { addImpersonalizeWith } from '@wildo-ai/zod-decorators';\n\n/** ──────────────────────────────────────────────────────────────\n * Guidance State — Per-Element State\n * ────────────────────────────────────────────────────────────── */\n\n/** Per-element completion state */\nexport const GuidanceElementStateSchema = z.object({\n  status: z.enum(OnboardingStatus),\n  /** Timestamp when this element was completed.\n   *  Uses z.coerce.date() to handle string → Date coercion on parse (stored as ISO strings in DB). */\n  completedAt: z.coerce.date().optional(),\n  /** For surveys: submitted answers */\n  surveyAnswers: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.array(z.string())])).optional(),\n  /** For tours: last completed step index */\n  lastStepIndex: z.number().int().optional(),\n});\nexport type GuidanceElementState = z.infer<typeof GuidanceElementStateSchema>;\n\n/** ──────────────────────────────────────────────────────────────\n * Guidance State — Per-Flow State\n * ────────────────────────────────────────────────────────────── */\n\n/** Per-flow state */\nexport const GuidanceFlowStateSchema = z.object({\n  status: z.enum(OnboardingStatus),\n  startedAt: z.coerce.date().optional(),\n  completedAt: z.coerce.date().optional(),\n  dismissedAt: z.coerce.date().optional(),\n  /** Element-level state keyed by element ref */\n  elements: z.record(z.string(), GuidanceElementStateSchema).default({}),\n  /** How many times this flow has been triggered */\n  triggerCount: z.number().int().default(0),\n});\nexport type GuidanceFlowState = z.infer<typeof GuidanceFlowStateSchema>;\n\n/** ──────────────────────────────────────────────────────────────\n * Guidance State — Top-Level Document\n * ────────────────────────────────────────────────────────────── */\n\n/** Shared guidance state payload body.\n *  Scope-specific state resources extend this schema with their owning FK\n *  (`userId` / `organizationId`) before persistence. */\nexport const GuidanceStateSchema = z.object({\n  /** Map of flowRef → flow state */\n  // USAGE — which guidance flows this person has seen and how far through. A record of what they\n  // did in the product, held per user, so a notice must enumerate it.\n  // RESET on erasure — returns this field to its schema default. It holds the per-flow progress map — which guidance flows this person saw and how far through each,\n  // which the category above correctly declares as personal data. RESET rather than REMOVE or MASK\n  // because the field is non-nullable WITH a `.default()`: REMOVE needs a clearable field and MASK\n  // needs a string. The value comes from the schema, so there is no second copy to drift.\n  flows: addImpersonalizeWith(\n  z.record(z.string(), GuidanceFlowStateSchema).default({}).isSummaryField()\n      .dataCategories(PersonalDataCategory.USAGE),\n    RedactionType.RESET,\n  ),\n});\nexport type GuidanceState = z.infer<typeof GuidanceStateSchema>;\n\nexport const UserGuidanceStateSchema = GuidanceStateSchema.extend({\n  userId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n});\nexport type UserGuidanceState = z.infer<typeof UserGuidanceStateSchema>;\n\nexport const OrganizationGuidanceStateSchema = GuidanceStateSchema.extend({\n  organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n});\nexport type OrganizationGuidanceState = z.infer<typeof OrganizationGuidanceStateSchema>;\n\nexport type PersistedGuidanceState = UserGuidanceState | OrganizationGuidanceState;\n"]}
+{"version":3,"file":"guidance-state.shared.schemas.js","sourceRoot":"","sources":["../../../../src/guidance/guidance-state.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\nimport { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas';\nimport { OnboardingStatus } from '../config/frontend/onboarding.shared.schemas';\nimport { RedactionType } from '../compliance/privacy/redaction.shared.schemas';\nimport { addImpersonalizeWith } from '@wildo-ai/zod-decorators';\n\n/** ──────────────────────────────────────────────────────────────\n * Guidance State — Per-Element State\n * ────────────────────────────────────────────────────────────── */\n\n/** Per-element completion state */\nexport const GuidanceElementStateSchema = z.object({\n  status: z.enum(OnboardingStatus).describe('Where this element stands. The guidance engine records an element when it is completed.'),\n  /** Timestamp when this element was completed.\n   *  Uses z.coerce.date() to handle string → Date coercion on parse (stored as ISO strings in DB). */\n  completedAt: z.coerce.date().optional().describe('When this element was completed.'),\n  /** For surveys: submitted answers */\n  surveyAnswers: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.array(z.string())])).optional()\n    .describe('For a survey element, the submitted answers, keyed by question id. Absent for other element types.'),\n  /** For tours: last completed step index */\n  lastStepIndex: z.number().int().optional().describe('For a tour element, the zero-based index of the step on which the tour was finished. Absent for other element types.'),\n});\nexport type GuidanceElementState = z.infer<typeof GuidanceElementStateSchema>;\n\n/** ──────────────────────────────────────────────────────────────\n * Guidance State — Per-Flow State\n * ────────────────────────────────────────────────────────────── */\n\n/** Per-flow state */\nexport const GuidanceFlowStateSchema = z.object({\n  status: z.enum(OnboardingStatus).describe('Where this flow stands. `completed`, `skipped` and `dismissed` are final: a flow in one of them is not shown again.'),\n  startedAt: z.coerce.date().optional().describe('When the flow was first shown.'),\n  completedAt: z.coerce.date().optional().describe('When the flow was completed.'),\n  dismissedAt: z.coerce.date().optional().describe('When the flow was dismissed. Absent unless it was.'),\n  /** Element-level state keyed by element ref */\n  elements: z.record(z.string(), GuidanceElementStateSchema).default({}).describe('Progress on the flow\\'s individual elements, keyed by element reference. Elements not yet completed are absent.'),\n  /** How many times this flow has been triggered */\n  triggerCount: z.number().int().default(0).describe('How many times the flow has been shown. A first-visit flow is shown only while this is 0.'),\n});\nexport type GuidanceFlowState = z.infer<typeof GuidanceFlowStateSchema>;\n\n/** ──────────────────────────────────────────────────────────────\n * Guidance State — Top-Level Document\n * ────────────────────────────────────────────────────────────── */\n\n/** Shared guidance state payload body.\n *  Scope-specific state resources extend this schema with their owning FK\n *  (`userId` / `organizationId`) before persistence. */\nexport const GuidanceStateSchema = z.object({\n  /** Map of flowRef → flow state */\n  // USAGE — which guidance flows this person has seen and how far through. A record of what they\n  // did in the product, held per user, so a notice must enumerate it.\n  // RESET on erasure — returns this field to its schema default. It holds the per-flow progress map — which guidance flows this person saw and how far through each,\n  // which the category above correctly declares as personal data. RESET rather than REMOVE or MASK\n  // because the field is non-nullable WITH a `.default()`: REMOVE needs a clearable field and MASK\n  // needs a string. The value comes from the schema, so there is no second copy to drift.\n  flows: addImpersonalizeWith(\n  z.record(z.string(), GuidanceFlowStateSchema).default({}).isSummaryField()\n      .dataCategories(PersonalDataCategory.USAGE),\n    RedactionType.RESET,\n  ),\n});\nexport type GuidanceState = z.infer<typeof GuidanceStateSchema>;\n\nexport const UserGuidanceStateSchema = GuidanceStateSchema.extend({\n  userId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n});\nexport type UserGuidanceState = z.infer<typeof UserGuidanceStateSchema>;\n\nexport const OrganizationGuidanceStateSchema = GuidanceStateSchema.extend({\n  organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n});\nexport type OrganizationGuidanceState = z.infer<typeof OrganizationGuidanceStateSchema>;\n\nexport type PersistedGuidanceState = UserGuidanceState | OrganizationGuidanceState;\n"]}

package/dist/esm/guidance/lifecycle-state.shared.schemas.js

@@ -99,20 +99,20 @@ export function isValidLifecycleTransition(from, to) {
 /** Record of a single stage transition */
 export const LifecycleStageTransitionSchema = z.object({
     /** Stage that was entered */
-    stage: z.enum(LifecycleStage),
+    stage: z.enum(LifecycleStage).describe('The stage entered.'),
     /** When this stage was entered */
-    enteredAt: z.coerce.date(),
+    enteredAt: z.coerce.date().describe('When the stage was entered.'),
     /** When this stage was exited (undefined if current) */
-    exitedAt: z.coerce.date().optional(),
+    exitedAt: z.coerce.date().optional().describe('When the stage was left. Absent for the current stage, and occasionally for an earlier one when two transitions happened at once.'),
     /** What triggered this transition (milestone ref, cron, operation, etc.) */
-    trigger: z.string().optional(),
+    trigger: z.string().optional().describe('What caused the transition: `auto_create` for the initial stage, `operation:<operation>`, `milestone:<milestone>`, `guidance_completed`, `engagement_threshold`, `dormancy_cron` or `on_read_reactivation`.'),
 });
 /** Engagement metrics tracked while user is ACTIVATED */
 export const LifecycleEngagementSchema = z.object({
     /** Total operations since activation */
-    operationsSinceActivation: z.number().int().default(0),
+    operationsSinceActivation: z.number().int().default(0).describe('Operations performed while in the `activated` or `reactivated` stage. Reset to 0 on reactivation, and compared with the configured engagement threshold to move to `engaged`.'),
     /** Distinct active dates since activation (YYYY-MM-DD strings) */
-    activeDates: z.array(z.string()).default([]),
+    activeDates: z.array(z.string()).default([]).describe('Distinct UTC calendar days (`YYYY-MM-DD`) with at least one operation while in the `activated` or `reactivated` stage. Cleared on reactivation.'),
 });
 /** Shared lifecycle state payload body.
  *  Scope-specific state resources extend this schema with their owning FK

package/dist/esm/guidance/lifecycle-state.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle-state.shared.schemas.js","sourceRoot":"","sources":["../../../../src/guidance/lifecycle-state.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\nimport { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas';\nimport { CoreResourceType } from '../resources/resources.shared.core.definitions';\nimport { RedactionType } from '../compliance/privacy/redaction.shared.schemas';\nimport { addImpersonalizeWith } from '@wildo-ai/zod-decorators';\n\n/** ──────────────────────────────────────────────────────────────\n * Lifecycle Stage — Ordered Progression with Dormancy/Reactivation Branches\n * ────────────────────────────────────────────────────────────── */\n\n/** Lifecycle stages — ordered progression with dormancy/reactivation branches */\nexport enum LifecycleStage {\n  /** User has signed up but hasn't met activation criteria */\n  SIGNED_UP = 'signed_up',\n  /** User has met activation criteria (reached product value) */\n  ACTIVATED = 'activated',\n  /** User shows sustained engagement (optional — requires engagementThreshold config) */\n  ENGAGED = 'engaged',\n  /** User has been inactive past the dormancy threshold */\n  DORMANT = 'dormant',\n  /** Previously dormant user has returned */\n  REACTIVATED = 'reactivated',\n  /** User has churned (billing-triggered — deferred) */\n  CHURNED = 'churned',\n  /** User has been fully offboarded (deferred) */\n  OFFBOARDED = 'offboarded',\n}\n\n/** ──────────────────────────────────────────────────────────────\n * Lifecycle Scope — Bi-Scope (same as guidance/progression)\n * ────────────────────────────────────────────────────────────── */\n\n/** Lifecycle state scope — bi-scope (same as guidance/progression) */\nexport enum LifecycleScope {\n  USER = 'user',\n  ORGANIZATION = 'organization',\n}\n\n/** ──────────────────────────────────────────────────────────────\n * Const Maps — State Machine, Stage Sets, Scope Mappings\n * ────────────────────────────────────────────────────────────── */\n\n/** Valid state transitions — the lifecycle state machine.\n *  Key = source stage, Value = valid target stages. */\nexport const LIFECYCLE_VALID_TRANSITIONS: Readonly<Record<LifecycleStage, readonly LifecycleStage[]>> = {\n  [LifecycleStage.SIGNED_UP]: [LifecycleStage.ACTIVATED],\n  [LifecycleStage.ACTIVATED]: [LifecycleStage.ENGAGED, LifecycleStage.DORMANT],\n  [LifecycleStage.ENGAGED]: [LifecycleStage.DORMANT],\n  [LifecycleStage.DORMANT]: [LifecycleStage.REACTIVATED, LifecycleStage.CHURNED],\n  [LifecycleStage.REACTIVATED]: [LifecycleStage.ENGAGED, LifecycleStage.DORMANT],\n  [LifecycleStage.CHURNED]: [LifecycleStage.OFFBOARDED],\n  [LifecycleStage.OFFBOARDED]: [],\n} as const;\n\n/** Stages from which a user can become dormant (all active stages except SIGNED_UP) */\nexport const LIFECYCLE_DORMANCY_SOURCE_STAGES = [\n  LifecycleStage.ACTIVATED,\n  LifecycleStage.ENGAGED,\n  LifecycleStage.REACTIVATED,\n] as const;\n\n/** Stages eligible for engagement threshold evaluation (can transition to ENGAGED) */\nexport const LIFECYCLE_ENGAGEMENT_ELIGIBLE_STAGES = [\n  LifecycleStage.ACTIVATED,\n  LifecycleStage.REACTIVATED,\n] as const;\n\n/** Maps LifecycleScope → corresponding CoreResourceType for lifecycle state storage */\nexport const LIFECYCLE_SCOPE_TO_RESOURCE: Readonly<Record<LifecycleScope, CoreResourceType>> = {\n  [LifecycleScope.USER]: CoreResourceType.USER_LIFECYCLE_STATE,\n  [LifecycleScope.ORGANIZATION]: CoreResourceType.ORGANIZATION_LIFECYCLE_STATE,\n} as const;\n\n/** Maps LifecycleScope → corresponding Progression resource type (for activation criteria eval).\n *  Named to avoid collision with existing PROGRESSION_SCOPE_TO_RESOURCE in milestone-definition.shared.schemas.ts\n *  (which is keyed by ProgressionScope, not LifecycleScope). */\nexport const LIFECYCLE_TO_PROGRESSION_RESOURCE: Readonly<Record<LifecycleScope, CoreResourceType>> = {\n  [LifecycleScope.USER]: CoreResourceType.USER_PROGRESSION_STATE,\n  [LifecycleScope.ORGANIZATION]: CoreResourceType.ORGANIZATION_PROGRESSION_STATE,\n} as const;\n\n/** Maps LifecycleScope → corresponding Guidance state resource type (for GUIDANCE_COMPLETED activation criteria). */\nexport const LIFECYCLE_TO_GUIDANCE_RESOURCE: Readonly<Record<LifecycleScope, CoreResourceType>> = {\n  [LifecycleScope.USER]: CoreResourceType.USER_GUIDANCE_STATE,\n  [LifecycleScope.ORGANIZATION]: CoreResourceType.ORGANIZATION_GUIDANCE_STATE,\n} as const;\n\n/** All lifecycle resource types — for conditional exclusion when lifecycle disabled\n *  (same pattern as BILLING_RESOURCE_TYPES in resources.shared.core.definitions.ts) */\nexport const LIFECYCLE_RESOURCE_TYPES: ReadonlySet<CoreResourceType> = new Set([\n  CoreResourceType.USER_LIFECYCLE_STATE,\n  CoreResourceType.ORGANIZATION_LIFECYCLE_STATE,\n]);\n\n/** Guidance state resource types — used to detect guidance state updates for activation criteria */\nexport const GUIDANCE_STATE_RESOURCE_TYPES: ReadonlySet<CoreResourceType> = new Set([\n  CoreResourceType.USER_GUIDANCE_STATE,\n  CoreResourceType.ORGANIZATION_GUIDANCE_STATE,\n]);\n\n/** ──────────────────────────────────────────────────────────────\n * Utility Functions\n * ────────────────────────────────────────────────────────────── */\n\n/** Validate if a lifecycle transition is valid per the state machine. */\nexport function isValidLifecycleTransition(from: LifecycleStage, to: LifecycleStage): boolean {\n  return LIFECYCLE_VALID_TRANSITIONS[from]?.includes(to) ?? false;\n}\n\n/** ──────────────────────────────────────────────────────────────\n * Zod Schemas — Lifecycle State Document\n * ────────────────────────────────────────────────────────────── */\n\n/** Record of a single stage transition */\nexport const LifecycleStageTransitionSchema = z.object({\n  /** Stage that was entered */\n  stage: z.enum(LifecycleStage),\n  /** When this stage was entered */\n  enteredAt: z.coerce.date(),\n  /** When this stage was exited (undefined if current) */\n  exitedAt: z.coerce.date().optional(),\n  /** What triggered this transition (milestone ref, cron, operation, etc.) */\n  trigger: z.string().optional(),\n});\nexport type LifecycleStageTransition = z.infer<typeof LifecycleStageTransitionSchema>;\n\n/** Engagement metrics tracked while user is ACTIVATED */\nexport const LifecycleEngagementSchema = z.object({\n  /** Total operations since activation */\n  operationsSinceActivation: z.number().int().default(0),\n  /** Distinct active dates since activation (YYYY-MM-DD strings) */\n  activeDates: z.array(z.string()).default([]),\n});\nexport type LifecycleEngagement = z.infer<typeof LifecycleEngagementSchema>;\n\n/** Shared lifecycle state payload body.\n *  Scope-specific state resources extend this schema with their owning FK\n *  (`userId` / `organizationId`) before persistence. */\nexport const LifecycleStateSchema = z.object({\n  /** Current lifecycle stage */\n  // USAGE across the block below — a lifecycle stage, its history, and an engagement score are all\n  // observations the product made ABOUT this person's behaviour.\n  // RESET on erasure — returns this field to its schema default. It holds the lifecycle stage this person reached,\n  // which the category above correctly declares as personal data. RESET rather than REMOVE or MASK\n  // because the field is non-nullable WITH a `.default()`: REMOVE needs a clearable field and MASK\n  // needs a string. The value comes from the schema, so there is no second copy to drift.\n  currentStage: addImpersonalizeWith(\n  z.enum(LifecycleStage).default(LifecycleStage.SIGNED_UP).isSummaryField()\n      .dataCategories(PersonalDataCategory.USAGE),\n    RedactionType.RESET,\n  ),\n  /** When the current stage was entered. `.default(now)` so the row is\n   *  eager-seedable via onParentCreate (the evaluator still supplies it explicitly). */\n  stageEnteredAt: z.coerce.date().default(() => new Date()),\n  /** History of stage transitions (most recent first, capped at last 20) */\n  // RESET on erasure — returns this field to its schema default. It holds the transition history — when they moved between stages,\n  // which the category above correctly declares as personal data. RESET rather than REMOVE or MASK\n  // because the field is non-nullable WITH a `.default()`: REMOVE needs a clearable field and MASK\n  // needs a string. The value comes from the schema, so there is no second copy to drift.\n  stageHistory: addImpersonalizeWith(\n  z.array(LifecycleStageTransitionSchema).default([]).dataCategories(PersonalDataCategory.USAGE),\n    RedactionType.RESET,\n  ),\n  /** Deduplicated set of all stages ever visited (survives stageHistory cap).\n   *  Used by `hasReachedStage()` for reliable stage visitation checks. */\n  stagesVisited: z.array(z.enum(LifecycleStage)).default([]),\n  /** Last activity timestamp (updated on operations, debounced ~30 min).\n   *  `.default(now)` so the row is eager-seedable via onParentCreate. */\n  // NO treatment, deliberately — and this is a CHOICE the RESET guard forced rather than an omission.\n  //\n  // This field's default reads the clock (`.default(() => new Date())`, so a row is eager-seedable via\n  // onParentCreate). RESET would therefore write a value generated BY the erasure, recording the erased\n  // person as active at the moment they were erased — fabricating information rather than removing it.\n  // The guard refuses that outright.\n  //\n  // Of its two suggested remedies, neither is right here. A static `new Date(0)` default would change\n  // what every LIVE row means, not just erased ones — the lifecycle evaluator reads this to decide\n  // engagement, so a new member would read as inactive since 1970. Making it nullable + REMOVE pushes\n  // an `undefined` onto every consumer of a field that has always held a value.\n  //\n  // So the timestamp is RETAINED, and the notice can say so plainly. The mode is satisfied by\n  // `currentStage` and `stageHistory`, which carry the behavioural detail; a bare timestamp attached to\n  // a subject whose identity row has been scrubbed discloses very little on its own.\n  lastActiveAt: z.coerce.date().default(() => new Date()).dataCategories(PersonalDataCategory.USAGE),\n  /** Which activation criteria have been met (keyed by criterion ref) */\n  activationCriteriaMet: z.record(z.string(), z.boolean()).default({}),\n  /** Engagement metrics (tracked while ACTIVATED, used for ENGAGED transition) */\n  engagement: LifecycleEngagementSchema.default({\n    operationsSinceActivation: 0,\n    activeDates: [],\n  }),\n});\nexport type LifecycleState = z.infer<typeof LifecycleStateSchema>;\n\nexport const UserLifecycleStateSchema = LifecycleStateSchema.extend({\n  // `.isUnique()` = idempotency backstop for onParentCreate seeding (one row per user;\n  // the evaluator's read-then-create already tolerates the unique conflict).\n  userId: z.string().min(1).isDBIndexed().isUnique().isForeignKey().isSummaryField().excludeFromUpdate(),\n});\nexport type UserLifecycleState = z.infer<typeof UserLifecycleStateSchema>;\n\nexport const OrganizationLifecycleStateSchema = LifecycleStateSchema.extend({\n  // `.isUnique()` = idempotency backstop for onParentCreate seeding (one row per org).\n  organizationId: z.string().min(1).isDBIndexed().isUnique().isForeignKey().isSummaryField().excludeFromUpdate(),\n});\nexport type OrganizationLifecycleState = z.infer<typeof OrganizationLifecycleStateSchema>;\n\nexport type PersistedLifecycleState = UserLifecycleState | OrganizationLifecycleState;\n\n/** ──────────────────────────────────────────────────────────────\n * Stage History Utility\n * ────────────────────────────────────────────────────────────── */\n\n/** Check if the user has ACTUALLY visited a given stage (not a linear comparison).\n *  Uses `stagesVisited` for reliable lookups that survive the stageHistory cap.\n *  Falls back to `stageHistory` for documents created before `stagesVisited` was added. */\nexport function hasReachedStage(state: LifecycleState, targetStage: LifecycleStage): boolean {\n  if (state.currentStage === targetStage) return true;\n  if (state.stagesVisited?.length) {\n    return state.stagesVisited.includes(targetStage);\n  }\n  return state.stageHistory.some(entry => entry.stage === targetStage);\n}\n"]}
+{"version":3,"file":"lifecycle-state.shared.schemas.js","sourceRoot":"","sources":["../../../../src/guidance/lifecycle-state.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\nimport { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas';\nimport { CoreResourceType } from '../resources/resources.shared.core.definitions';\nimport { RedactionType } from '../compliance/privacy/redaction.shared.schemas';\nimport { addImpersonalizeWith } from '@wildo-ai/zod-decorators';\n\n/** ──────────────────────────────────────────────────────────────\n * Lifecycle Stage — Ordered Progression with Dormancy/Reactivation Branches\n * ────────────────────────────────────────────────────────────── */\n\n/** Lifecycle stages — ordered progression with dormancy/reactivation branches */\nexport enum LifecycleStage {\n  /** User has signed up but hasn't met activation criteria */\n  SIGNED_UP = 'signed_up',\n  /** User has met activation criteria (reached product value) */\n  ACTIVATED = 'activated',\n  /** User shows sustained engagement (optional — requires engagementThreshold config) */\n  ENGAGED = 'engaged',\n  /** User has been inactive past the dormancy threshold */\n  DORMANT = 'dormant',\n  /** Previously dormant user has returned */\n  REACTIVATED = 'reactivated',\n  /** User has churned (billing-triggered — deferred) */\n  CHURNED = 'churned',\n  /** User has been fully offboarded (deferred) */\n  OFFBOARDED = 'offboarded',\n}\n\n/** ──────────────────────────────────────────────────────────────\n * Lifecycle Scope — Bi-Scope (same as guidance/progression)\n * ────────────────────────────────────────────────────────────── */\n\n/** Lifecycle state scope — bi-scope (same as guidance/progression) */\nexport enum LifecycleScope {\n  USER = 'user',\n  ORGANIZATION = 'organization',\n}\n\n/** ──────────────────────────────────────────────────────────────\n * Const Maps — State Machine, Stage Sets, Scope Mappings\n * ────────────────────────────────────────────────────────────── */\n\n/** Valid state transitions — the lifecycle state machine.\n *  Key = source stage, Value = valid target stages. */\nexport const LIFECYCLE_VALID_TRANSITIONS: Readonly<Record<LifecycleStage, readonly LifecycleStage[]>> = {\n  [LifecycleStage.SIGNED_UP]: [LifecycleStage.ACTIVATED],\n  [LifecycleStage.ACTIVATED]: [LifecycleStage.ENGAGED, LifecycleStage.DORMANT],\n  [LifecycleStage.ENGAGED]: [LifecycleStage.DORMANT],\n  [LifecycleStage.DORMANT]: [LifecycleStage.REACTIVATED, LifecycleStage.CHURNED],\n  [LifecycleStage.REACTIVATED]: [LifecycleStage.ENGAGED, LifecycleStage.DORMANT],\n  [LifecycleStage.CHURNED]: [LifecycleStage.OFFBOARDED],\n  [LifecycleStage.OFFBOARDED]: [],\n} as const;\n\n/** Stages from which a user can become dormant (all active stages except SIGNED_UP) */\nexport const LIFECYCLE_DORMANCY_SOURCE_STAGES = [\n  LifecycleStage.ACTIVATED,\n  LifecycleStage.ENGAGED,\n  LifecycleStage.REACTIVATED,\n] as const;\n\n/** Stages eligible for engagement threshold evaluation (can transition to ENGAGED) */\nexport const LIFECYCLE_ENGAGEMENT_ELIGIBLE_STAGES = [\n  LifecycleStage.ACTIVATED,\n  LifecycleStage.REACTIVATED,\n] as const;\n\n/** Maps LifecycleScope → corresponding CoreResourceType for lifecycle state storage */\nexport const LIFECYCLE_SCOPE_TO_RESOURCE: Readonly<Record<LifecycleScope, CoreResourceType>> = {\n  [LifecycleScope.USER]: CoreResourceType.USER_LIFECYCLE_STATE,\n  [LifecycleScope.ORGANIZATION]: CoreResourceType.ORGANIZATION_LIFECYCLE_STATE,\n} as const;\n\n/** Maps LifecycleScope → corresponding Progression resource type (for activation criteria eval).\n *  Named to avoid collision with existing PROGRESSION_SCOPE_TO_RESOURCE in milestone-definition.shared.schemas.ts\n *  (which is keyed by ProgressionScope, not LifecycleScope). */\nexport const LIFECYCLE_TO_PROGRESSION_RESOURCE: Readonly<Record<LifecycleScope, CoreResourceType>> = {\n  [LifecycleScope.USER]: CoreResourceType.USER_PROGRESSION_STATE,\n  [LifecycleScope.ORGANIZATION]: CoreResourceType.ORGANIZATION_PROGRESSION_STATE,\n} as const;\n\n/** Maps LifecycleScope → corresponding Guidance state resource type (for GUIDANCE_COMPLETED activation criteria). */\nexport const LIFECYCLE_TO_GUIDANCE_RESOURCE: Readonly<Record<LifecycleScope, CoreResourceType>> = {\n  [LifecycleScope.USER]: CoreResourceType.USER_GUIDANCE_STATE,\n  [LifecycleScope.ORGANIZATION]: CoreResourceType.ORGANIZATION_GUIDANCE_STATE,\n} as const;\n\n/** All lifecycle resource types — for conditional exclusion when lifecycle disabled\n *  (same pattern as BILLING_RESOURCE_TYPES in resources.shared.core.definitions.ts) */\nexport const LIFECYCLE_RESOURCE_TYPES: ReadonlySet<CoreResourceType> = new Set([\n  CoreResourceType.USER_LIFECYCLE_STATE,\n  CoreResourceType.ORGANIZATION_LIFECYCLE_STATE,\n]);\n\n/** Guidance state resource types — used to detect guidance state updates for activation criteria */\nexport const GUIDANCE_STATE_RESOURCE_TYPES: ReadonlySet<CoreResourceType> = new Set([\n  CoreResourceType.USER_GUIDANCE_STATE,\n  CoreResourceType.ORGANIZATION_GUIDANCE_STATE,\n]);\n\n/** ──────────────────────────────────────────────────────────────\n * Utility Functions\n * ────────────────────────────────────────────────────────────── */\n\n/** Validate if a lifecycle transition is valid per the state machine. */\nexport function isValidLifecycleTransition(from: LifecycleStage, to: LifecycleStage): boolean {\n  return LIFECYCLE_VALID_TRANSITIONS[from]?.includes(to) ?? false;\n}\n\n/** ──────────────────────────────────────────────────────────────\n * Zod Schemas — Lifecycle State Document\n * ────────────────────────────────────────────────────────────── */\n\n/** Record of a single stage transition */\nexport const LifecycleStageTransitionSchema = z.object({\n  /** Stage that was entered */\n  stage: z.enum(LifecycleStage).describe('The stage entered.'),\n  /** When this stage was entered */\n  enteredAt: z.coerce.date().describe('When the stage was entered.'),\n  /** When this stage was exited (undefined if current) */\n  exitedAt: z.coerce.date().optional().describe('When the stage was left. Absent for the current stage, and occasionally for an earlier one when two transitions happened at once.'),\n  /** What triggered this transition (milestone ref, cron, operation, etc.) */\n  trigger: z.string().optional().describe('What caused the transition: `auto_create` for the initial stage, `operation:<operation>`, `milestone:<milestone>`, `guidance_completed`, `engagement_threshold`, `dormancy_cron` or `on_read_reactivation`.'),\n});\nexport type LifecycleStageTransition = z.infer<typeof LifecycleStageTransitionSchema>;\n\n/** Engagement metrics tracked while user is ACTIVATED */\nexport const LifecycleEngagementSchema = z.object({\n  /** Total operations since activation */\n  operationsSinceActivation: z.number().int().default(0).describe('Operations performed while in the `activated` or `reactivated` stage. Reset to 0 on reactivation, and compared with the configured engagement threshold to move to `engaged`.'),\n  /** Distinct active dates since activation (YYYY-MM-DD strings) */\n  activeDates: z.array(z.string()).default([]).describe('Distinct UTC calendar days (`YYYY-MM-DD`) with at least one operation while in the `activated` or `reactivated` stage. Cleared on reactivation.'),\n});\nexport type LifecycleEngagement = z.infer<typeof LifecycleEngagementSchema>;\n\n/** Shared lifecycle state payload body.\n *  Scope-specific state resources extend this schema with their owning FK\n *  (`userId` / `organizationId`) before persistence. */\nexport const LifecycleStateSchema = z.object({\n  /** Current lifecycle stage */\n  // USAGE across the block below — a lifecycle stage, its history, and an engagement score are all\n  // observations the product made ABOUT this person's behaviour.\n  // RESET on erasure — returns this field to its schema default. It holds the lifecycle stage this person reached,\n  // which the category above correctly declares as personal data. RESET rather than REMOVE or MASK\n  // because the field is non-nullable WITH a `.default()`: REMOVE needs a clearable field and MASK\n  // needs a string. The value comes from the schema, so there is no second copy to drift.\n  currentStage: addImpersonalizeWith(\n  z.enum(LifecycleStage).default(LifecycleStage.SIGNED_UP).isSummaryField()\n      .dataCategories(PersonalDataCategory.USAGE),\n    RedactionType.RESET,\n  ),\n  /** When the current stage was entered. `.default(now)` so the row is\n   *  eager-seedable via onParentCreate (the evaluator still supplies it explicitly). */\n  stageEnteredAt: z.coerce.date().default(() => new Date()),\n  /** History of stage transitions (most recent first, capped at last 20) */\n  // RESET on erasure — returns this field to its schema default. It holds the transition history — when they moved between stages,\n  // which the category above correctly declares as personal data. RESET rather than REMOVE or MASK\n  // because the field is non-nullable WITH a `.default()`: REMOVE needs a clearable field and MASK\n  // needs a string. The value comes from the schema, so there is no second copy to drift.\n  stageHistory: addImpersonalizeWith(\n  z.array(LifecycleStageTransitionSchema).default([]).dataCategories(PersonalDataCategory.USAGE),\n    RedactionType.RESET,\n  ),\n  /** Deduplicated set of all stages ever visited (survives stageHistory cap).\n   *  Used by `hasReachedStage()` for reliable stage visitation checks. */\n  stagesVisited: z.array(z.enum(LifecycleStage)).default([]),\n  /** Last activity timestamp (updated on operations, debounced ~30 min).\n   *  `.default(now)` so the row is eager-seedable via onParentCreate. */\n  // NO treatment, deliberately — and this is a CHOICE the RESET guard forced rather than an omission.\n  //\n  // This field's default reads the clock (`.default(() => new Date())`, so a row is eager-seedable via\n  // onParentCreate). RESET would therefore write a value generated BY the erasure, recording the erased\n  // person as active at the moment they were erased — fabricating information rather than removing it.\n  // The guard refuses that outright.\n  //\n  // Of its two suggested remedies, neither is right here. A static `new Date(0)` default would change\n  // what every LIVE row means, not just erased ones — the lifecycle evaluator reads this to decide\n  // engagement, so a new member would read as inactive since 1970. Making it nullable + REMOVE pushes\n  // an `undefined` onto every consumer of a field that has always held a value.\n  //\n  // So the timestamp is RETAINED, and the notice can say so plainly. The mode is satisfied by\n  // `currentStage` and `stageHistory`, which carry the behavioural detail; a bare timestamp attached to\n  // a subject whose identity row has been scrubbed discloses very little on its own.\n  lastActiveAt: z.coerce.date().default(() => new Date()).dataCategories(PersonalDataCategory.USAGE),\n  /** Which activation criteria have been met (keyed by criterion ref) */\n  activationCriteriaMet: z.record(z.string(), z.boolean()).default({}),\n  /** Engagement metrics (tracked while ACTIVATED, used for ENGAGED transition) */\n  engagement: LifecycleEngagementSchema.default({\n    operationsSinceActivation: 0,\n    activeDates: [],\n  }),\n});\nexport type LifecycleState = z.infer<typeof LifecycleStateSchema>;\n\nexport const UserLifecycleStateSchema = LifecycleStateSchema.extend({\n  // `.isUnique()` = idempotency backstop for onParentCreate seeding (one row per user;\n  // the evaluator's read-then-create already tolerates the unique conflict).\n  userId: z.string().min(1).isDBIndexed().isUnique().isForeignKey().isSummaryField().excludeFromUpdate(),\n});\nexport type UserLifecycleState = z.infer<typeof UserLifecycleStateSchema>;\n\nexport const OrganizationLifecycleStateSchema = LifecycleStateSchema.extend({\n  // `.isUnique()` = idempotency backstop for onParentCreate seeding (one row per org).\n  organizationId: z.string().min(1).isDBIndexed().isUnique().isForeignKey().isSummaryField().excludeFromUpdate(),\n});\nexport type OrganizationLifecycleState = z.infer<typeof OrganizationLifecycleStateSchema>;\n\nexport type PersistedLifecycleState = UserLifecycleState | OrganizationLifecycleState;\n\n/** ──────────────────────────────────────────────────────────────\n * Stage History Utility\n * ────────────────────────────────────────────────────────────── */\n\n/** Check if the user has ACTUALLY visited a given stage (not a linear comparison).\n *  Uses `stagesVisited` for reliable lookups that survive the stageHistory cap.\n *  Falls back to `stageHistory` for documents created before `stagesVisited` was added. */\nexport function hasReachedStage(state: LifecycleState, targetStage: LifecycleStage): boolean {\n  if (state.currentStage === targetStage) return true;\n  if (state.stagesVisited?.length) {\n    return state.stagesVisited.includes(targetStage);\n  }\n  return state.stageHistory.some(entry => entry.stage === targetStage);\n}\n"]}

package/dist/esm/guidance/progression-state.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"progression-state.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/guidance/progression-state.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;oEAEoE;AAEpE,+CAA+C;AAC/C,eAAO,MAAM,kCAAkC;;;iBAK7C,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAE9F;;oEAEoE;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,sBAAsB;;;;iBAcjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;oEAEoE;AAEpE,uCAAuC;AACvC,eAAO,MAAM,iCAAiC;;;iBAK5C,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAE5F;;oEAEoE;AAEpE;;wDAEwD;AACxD,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;iBA8CjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;iBAErC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;iBAE7C,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAE9F,MAAM,MAAM,yBAAyB,GAAG,oBAAoB,GAAG,4BAA4B,CAAC"}
+{"version":3,"file":"progression-state.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/guidance/progression-state.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;oEAEoE;AAEpE,+CAA+C;AAC/C,eAAO,MAAM,kCAAkC;;;iBAK7C,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAE9F;;oEAEoE;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,sBAAsB;;;;iBAejC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;oEAEoE;AAEpE,uCAAuC;AACvC,eAAO,MAAM,iCAAiC;;;iBAK5C,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAE5F;;oEAEoE;AAEpE;;wDAEwD;AACxD,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;iBA8CjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;iBAErC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;iBAE7C,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAE9F,MAAM,MAAM,yBAAyB,GAAG,oBAAoB,GAAG,4BAA4B,CAAC"}

package/dist/esm/guidance/progression-state.shared.schemas.js

@@ -8,9 +8,9 @@ import { addImpersonalizeWith } from '@wildo-ai/zod-decorators';
 /** Record of a single milestone achievement */
 export const ProgressionMilestoneAchievedSchema = z.object({
     /** When the milestone was achieved */
-    achievedAt: z.coerce.date(),
+    achievedAt: z.coerce.date().describe('When the milestone was achieved.'),
     /** How many times the triggering operation occurred (for COUNT_THRESHOLD context) */
-    count: z.number().int().default(0),
+    count: z.number().int().default(0).describe('How many times the milestone\'s triggering operation had been performed when the milestone was achieved.'),
 });
 /** ──────────────────────────────────────────────────────────────
  * Progression State — Value Moment Record
@@ -47,14 +47,15 @@ export const ValueMomentStateSchema = z.object({
      * on the first signal and never needs this, but it is recorded for both so a moment whose mode is
      * changed after the fact does not silently lose the progress it already had.
      */
-    signalsObserved: z.array(z.string()).default([]),
+    signalsObserved: z.array(z.string()).default([]).describe('Signals observed so far. A signal that must occur several times is added once it reaches that count. The moment fires when any signal, or every signal, has been observed, depending on its mode.'),
     /** Matching event occurrences per path-safe signal identity, accumulated per moment and scope.
      * Optional for existing state rows; absent counts mean zero. Ordinary moment counters share the
      * progression record's retention/erasure lifecycle. Anti-pattern counts remain instance-local.
      */
-    signalOccurrenceCounts: z.record(z.string(), z.number().int().nonnegative()).optional(),
+    signalOccurrenceCounts: z.record(z.string(), z.number().int().nonnegative()).optional()
+        .describe('Occurrences counted per signal, kept only for signals that must occur more than once before they count as observed. A missing count means zero.'),
     /** When the moment fired. Absent while it is still accumulating signals. */
-    achievedAt: z.coerce.date().optional(),
+    achievedAt: z.coerce.date().optional().describe('When the value moment fired. Absent while it is still collecting signals.'),
 });
 /** ──────────────────────────────────────────────────────────────
  * Progression State — Per-Category Aggregated Progress
@@ -62,9 +63,9 @@ export const ValueMomentStateSchema = z.object({
 /** Per-category aggregated progress */
 export const ProgressionCategoryProgressSchema = z.object({
     /** Number of milestones completed in this category */
-    completedCount: z.number().int().default(0),
+    completedCount: z.number().int().default(0).describe('Number of milestones achieved in this category.'),
     /** Total points earned in this category */
-    totalPoints: z.number().int().default(0),
+    totalPoints: z.number().int().default(0).describe('Points earned from the milestones achieved in this category.'),
 });
 /** ──────────────────────────────────────────────────────────────
  * Progression State — Top-Level Document