@wildo-ai/saas-models 1.1.3 → 1.1.5

package/dist/esm/compliance/risk-posture.shared.schemas.js

@@ -0,0 +1,166 @@
+import { z } from 'zod';
+/**
+ * The risk signals an APPLICATION may take a posture on (#300 Layer 2).
+ *
+ * ## Why only the application-evaluation signals
+ *
+ * `report-risk-signals.mjs` derives signals in two homes, and the split is load-bearing rather than
+ * organisational. FRAMEWORK_BUILD_TIME signals — marker density across the objective catalogue,
+ * objectives with no marker, objectives marked only outside production — are facts about the ENGINE
+ * and are identical for every application. An application cannot change them and does not choose
+ * them, so a declared posture about one would be an operator accepting somebody else's exposure.
+ * They inform; they are not accepted.
+ *
+ * APPLICATION_EVALUATION_TIME signals are facts about one application's own declarations, and every
+ * one of them is downstream of a choice its operator made. Those are the ones a posture is about.
+ *
+ * ## This enum is the SOURCE, and the derivation is held to it
+ *
+ * The refs were string literals inside the report. A second list here, free to drift from the one the
+ * script emits, is exactly the transcription defect the assurance anchoring rule exists to stop — so
+ * the report now parses this enum and refuses when the set it emits and the set declared here
+ * disagree, in EITHER direction. A signal added to the report with no member here fails; a member
+ * here that no signal emits fails too, because an application could otherwise declare a posture
+ * about an exposure nothing measures.
+ */
+export var ApplicationRiskSignalRef;
+(function (ApplicationRiskSignalRef) {
+    /** Which engine capabilities are enabled, and therefore which exposures are structurally absent. */
+    ApplicationRiskSignalRef["CAPABILITY_SURFACE"] = "application:capability-surface";
+    /** Whether every retention class the vocabulary carries has a declared period. */
+    ApplicationRiskSignalRef["RETENTION_DECLARATION"] = "application:retention-declaration";
+    /** How many configured providers are vendor-hosted, each a third-party processor. */
+    ApplicationRiskSignalRef["PROVIDER_HOSTING"] = "application:provider-hosting";
+    /** Which personal-data categories this application's own resources declare, and whether any is special category. */
+    ApplicationRiskSignalRef["PERSONAL_DATA_INVENTORY"] = "application:personal-data-inventory";
+    /** Resources that have not answered the personal-data question at all. */
+    ApplicationRiskSignalRef["PERSONAL_DATA_DECLARATION_GAP"] = "application:personal-data-declaration-gap";
+    /** Operations reachable by an external agent over MCP. */
+    ApplicationRiskSignalRef["EXTERNAL_EXPOSURE_MCP"] = "application:external-exposure-mcp";
+})(ApplicationRiskSignalRef || (ApplicationRiskSignalRef = {}));
+/**
+ * What an operator has DECIDED to do about an exposure.
+ *
+ * NIST SP 800-39 names the risk responses as accepting, avoiding, mitigating, sharing or
+ * transferring risk, and that set is what this enum takes — the options, not the spelling.
+ * spec-cite: NIST SP 800-39 / CSRC glossary, "risk response" — paraphrased from the published
+ * definition, not quoted.
+ *
+ * ## Only NIST is NAMED here, and that is a licensing line rather than a preference
+ *
+ * Other risk-management standards describe the same options and are LICENSED documents. Naming one
+ * in engine source would put a paid standard's identity into shipped code, which is why this
+ * repository's boundary rule keeps external framework names to rights-classified mapping and report
+ * surfaces. NIST publications are US government works, so citing one here costs nothing — and the
+ * practice is already settled: NIST is named in 34 engine and platform files.
+ *
+ * The options are borrowed either way. Being INSPIRED by a standard and NAMING it are different
+ * acts, and only the second carries a licence.
+ *
+ * ## No band, no score, no number — and that is inherited rather than chosen here
+ *
+ * Layer 1 emits signals carrying NO score, weight, level or severity, and asserts that prohibition
+ * structurally. A posture that arrived as a 1–5 appetite rating would put a number underneath a layer
+ * that refuses to produce one, and the number is what a reader trusts without checking. What an
+ * operator can honestly say about an exposure is which of these four they chose and why, so that is
+ * what the declaration carries.
+ *
+ * assurance-control: WILDO.RISK.TREATMENT_DECLARED — an operator's chosen treatment per exposure,
+ * with the reasoning, in a form a measurement can contradict.
+ *
+ * ## `AVOIDED` is the member that makes this layer worth having
+ *
+ * The other three are consistent with any measurement: an application that REDUCED, SHARED or
+ * ACCEPTED an exposure still has it, so the signal and the posture agree whatever the signal says.
+ * `AVOIDED` claims the exposure is not taken at all, which a Layer 1 signal can CONTRADICT — declare
+ * that vendor-hosted processing is avoided while two of three configured providers are vendor-hosted,
+ * and the two statements cannot both be true.
+ *
+ * That is the difference between this and a questionnaire answer. A free-text "describe your risk
+ * appetite" is unfalsifiable by construction; a typed posture beside a derived signal is a claim the
+ * product itself can disagree with.
+ */
+export var RiskTreatmentPosture;
+(function (RiskTreatmentPosture) {
+    /**
+     * The application does not take this exposure at all.
+     *
+     * The only FALSIFIABLE posture — a signal reporting the exposure present contradicts it directly.
+     */
+    RiskTreatmentPosture["AVOIDED"] = "AVOIDED";
+    /** Taken, with controls that lower its likelihood or its consequence. */
+    RiskTreatmentPosture["REDUCED"] = "REDUCED";
+    /**
+     * Taken, with the consequence placed on another party by CONTRACT — an Art. 28 processor agreement
+     * being the case this framework can actually evidence.
+     *
+     * Narrower than "share or transfer" on purpose. Insurance-style transfer is a legitimate treatment
+     * and nothing in the product can attest it, so modelling it here would add a member no derivation
+     * could ever check. Naming the contractual case precisely is a smaller claim and a true one.
+     */
+    RiskTreatmentPosture["SHARED_BY_CONTRACT"] = "SHARED_BY_CONTRACT";
+    /** Taken, and the exposure retained knowingly. */
+    RiskTreatmentPosture["ACCEPTED"] = "ACCEPTED";
+})(RiskTreatmentPosture || (RiskTreatmentPosture = {}));
+/**
+ * One signal's posture, and why.
+ *
+ * `rationale` is REQUIRED, for the same reason `dataRetention` requires one: a posture with no reason
+ * is a token, and the thing a reviewer needs is the sentence, not the enum member. "We accept it" is
+ * what the member already says.
+ *
+ * ## What is deliberately NOT here
+ *
+ * **No `decidedBy` and no `decidedAt`.** Acceptance is a COMMIT — `one-source-of-truth.md` rule 7 and
+ * D5 — so the author and the instant are already recorded, mergeably and by a history everyone
+ * audits. Fields restating them would be a second authority that can disagree with git, and they are
+ * exactly the shape that made an earlier compliance record unproducible without forging an identity.
+ *
+ * **No review date.** `derive-before-you-ask.md` settles this: a date is a PROXY for "an input may
+ * have changed", every input is in git and enumerable, so the trigger is computable and the date is
+ * an output rather than something to type.
+ */
+export const ApplicationRiskPostureEntrySchema = z.strictObject({
+    posture: z.enum(RiskTreatmentPosture).describe('What the operator decided to do about this exposure.'),
+    rationale: z
+        .string()
+        .trim()
+        .min(1)
+        .describe('Why this posture, in the operator\'s own words — the sentence a reviewer reads, not a restatement of the member.'),
+});
+/**
+ * An application's declared posture per risk signal — PARTIAL by construction.
+ *
+ * Every entry is optional and the whole declaration may be omitted. That is not laxity: a compliance
+ * workflow may never stand in front of the mechanism (`application-creation-directive.md`), and a
+ * required posture would make an application UNBUILDABLE until somebody decided something about
+ * every signal the framework happens to derive. The undeclared set is REPORTED instead, by
+ * {@link undeclaredRiskSignals}, which is the "mark it, do not block" shape that rule asks for.
+ *
+ * So absence is representable and means one thing — nobody has decided yet — and it is
+ * distinguishable from `ACCEPTED`, which means somebody decided to live with it. Collapsing those two
+ * is the failure this layer exists to avoid: silence is not acceptance.
+ */
+export const ApplicationRiskPostureSchema = z.record(z.enum(ApplicationRiskSignalRef), ApplicationRiskPostureEntrySchema);
+/**
+ * The signals an application has declared NO posture for — what a register must mark as owed.
+ *
+ * Derived rather than stored, and total over the enum, so a signal added to the vocabulary tomorrow
+ * is reported as undeclared by every existing application rather than silently omitted from the
+ * answer. Deliberately the same shape as `undeclaredRetentionClasses`, because it is the same
+ * question one layer over.
+ */
+export function undeclaredRiskSignals(posture) {
+    return Object.values(ApplicationRiskSignalRef).filter((signalRef) => posture?.[signalRef] === undefined);
+}
+/**
+ * Postures that CLAIM AN EXPOSURE IS NOT TAKEN — the ones a measurement can contradict.
+ *
+ * Exported rather than inlined at the one call site, so the report and any later consumer ask the
+ * same question. Today it is `AVOIDED` alone; if a future member is also falsifiable it joins here
+ * and every consumer follows, which is the whole reason this is a function and not a comparison.
+ */
+export function riskPostureClaimsExposureAbsent(entry) {
+    return entry?.posture === RiskTreatmentPosture.AVOIDED;
+}
+//# sourceMappingURL=risk-posture.shared.schemas.js.map

package/dist/esm/compliance/risk-posture.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk-posture.shared.schemas.js","sourceRoot":"","sources":["../../../../src/compliance/risk-posture.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAN,IAAY,wBAaX;AAbD,WAAY,wBAAwB;IAClC,oGAAoG;IACpG,iFAAqD,CAAA;IACrD,kFAAkF;IAClF,uFAA2D,CAAA;IAC3D,qFAAqF;IACrF,6EAAiD,CAAA;IACjD,oHAAoH;IACpH,2FAA+D,CAAA;IAC/D,0EAA0E;IAC1E,uGAA2E,CAAA;IAC3E,0DAA0D;IAC1D,uFAA2D,CAAA;AAC7D,CAAC,EAbW,wBAAwB,KAAxB,wBAAwB,QAanC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,CAAN,IAAY,oBAoBX;AApBD,WAAY,oBAAoB;IAC9B;;;;OAIG;IACH,2CAAmB,CAAA;IACnB,yEAAyE;IACzE,2CAAmB,CAAA;IACnB;;;;;;;OAOG;IACH,iEAAyC,CAAA;IACzC,kDAAkD;IAClD,6CAAqB,CAAA;AACvB,CAAC,EApBW,oBAAoB,KAApB,oBAAoB,QAoB/B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAAC,CAAC,YAAY,CAAC;IAC9D,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,QAAQ,CAAC,sDAAsD,CAAC;IACtG,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CAAC,kHAAkH,CAAC;CAChI,CAAC,CAAC;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAClD,CAAC,CAAC,IAAI,CAAC,wBAAwB,CAAC,EAChC,iCAAiC,CAClC,CAAC;AAIF;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAA2C;IAE3C,OAAO,MAAM,CAAC,MAAM,CAAC,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,SAAS,CAAC,KAAK,SAAS,CAAC,CAAC;AAC3G,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,+BAA+B,CAAC,KAA8C;IAC5F,OAAO,KAAK,EAAE,OAAO,KAAK,oBAAoB,CAAC,OAAO,CAAC;AACzD,CAAC","sourcesContent":["import { z } from 'zod';\n\n/**\n * The risk signals an APPLICATION may take a posture on (#300 Layer 2).\n *\n * ## Why only the application-evaluation signals\n *\n * `report-risk-signals.mjs` derives signals in two homes, and the split is load-bearing rather than\n * organisational. FRAMEWORK_BUILD_TIME signals — marker density across the objective catalogue,\n * objectives with no marker, objectives marked only outside production — are facts about the ENGINE\n * and are identical for every application. An application cannot change them and does not choose\n * them, so a declared posture about one would be an operator accepting somebody else's exposure.\n * They inform; they are not accepted.\n *\n * APPLICATION_EVALUATION_TIME signals are facts about one application's own declarations, and every\n * one of them is downstream of a choice its operator made. Those are the ones a posture is about.\n *\n * ## This enum is the SOURCE, and the derivation is held to it\n *\n * The refs were string literals inside the report. A second list here, free to drift from the one the\n * script emits, is exactly the transcription defect the assurance anchoring rule exists to stop — so\n * the report now parses this enum and refuses when the set it emits and the set declared here\n * disagree, in EITHER direction. A signal added to the report with no member here fails; a member\n * here that no signal emits fails too, because an application could otherwise declare a posture\n * about an exposure nothing measures.\n */\nexport enum ApplicationRiskSignalRef {\n  /** Which engine capabilities are enabled, and therefore which exposures are structurally absent. */\n  CAPABILITY_SURFACE = 'application:capability-surface',\n  /** Whether every retention class the vocabulary carries has a declared period. */\n  RETENTION_DECLARATION = 'application:retention-declaration',\n  /** How many configured providers are vendor-hosted, each a third-party processor. */\n  PROVIDER_HOSTING = 'application:provider-hosting',\n  /** Which personal-data categories this application's own resources declare, and whether any is special category. */\n  PERSONAL_DATA_INVENTORY = 'application:personal-data-inventory',\n  /** Resources that have not answered the personal-data question at all. */\n  PERSONAL_DATA_DECLARATION_GAP = 'application:personal-data-declaration-gap',\n  /** Operations reachable by an external agent over MCP. */\n  EXTERNAL_EXPOSURE_MCP = 'application:external-exposure-mcp',\n}\n\n/**\n * What an operator has DECIDED to do about an exposure.\n *\n * NIST SP 800-39 names the risk responses as accepting, avoiding, mitigating, sharing or\n * transferring risk, and that set is what this enum takes — the options, not the spelling.\n * spec-cite: NIST SP 800-39 / CSRC glossary, \"risk response\" — paraphrased from the published\n * definition, not quoted.\n *\n * ## Only NIST is NAMED here, and that is a licensing line rather than a preference\n *\n * Other risk-management standards describe the same options and are LICENSED documents. Naming one\n * in engine source would put a paid standard's identity into shipped code, which is why this\n * repository's boundary rule keeps external framework names to rights-classified mapping and report\n * surfaces. NIST publications are US government works, so citing one here costs nothing — and the\n * practice is already settled: NIST is named in 34 engine and platform files.\n *\n * The options are borrowed either way. Being INSPIRED by a standard and NAMING it are different\n * acts, and only the second carries a licence.\n *\n * ## No band, no score, no number — and that is inherited rather than chosen here\n *\n * Layer 1 emits signals carrying NO score, weight, level or severity, and asserts that prohibition\n * structurally. A posture that arrived as a 1–5 appetite rating would put a number underneath a layer\n * that refuses to produce one, and the number is what a reader trusts without checking. What an\n * operator can honestly say about an exposure is which of these four they chose and why, so that is\n * what the declaration carries.\n *\n * assurance-control: WILDO.RISK.TREATMENT_DECLARED — an operator's chosen treatment per exposure,\n * with the reasoning, in a form a measurement can contradict.\n *\n * ## `AVOIDED` is the member that makes this layer worth having\n *\n * The other three are consistent with any measurement: an application that REDUCED, SHARED or\n * ACCEPTED an exposure still has it, so the signal and the posture agree whatever the signal says.\n * `AVOIDED` claims the exposure is not taken at all, which a Layer 1 signal can CONTRADICT — declare\n * that vendor-hosted processing is avoided while two of three configured providers are vendor-hosted,\n * and the two statements cannot both be true.\n *\n * That is the difference between this and a questionnaire answer. A free-text \"describe your risk\n * appetite\" is unfalsifiable by construction; a typed posture beside a derived signal is a claim the\n * product itself can disagree with.\n */\nexport enum RiskTreatmentPosture {\n  /**\n   * The application does not take this exposure at all.\n   *\n   * The only FALSIFIABLE posture — a signal reporting the exposure present contradicts it directly.\n   */\n  AVOIDED = 'AVOIDED',\n  /** Taken, with controls that lower its likelihood or its consequence. */\n  REDUCED = 'REDUCED',\n  /**\n   * Taken, with the consequence placed on another party by CONTRACT — an Art. 28 processor agreement\n   * being the case this framework can actually evidence.\n   *\n   * Narrower than \"share or transfer\" on purpose. Insurance-style transfer is a legitimate treatment\n   * and nothing in the product can attest it, so modelling it here would add a member no derivation\n   * could ever check. Naming the contractual case precisely is a smaller claim and a true one.\n   */\n  SHARED_BY_CONTRACT = 'SHARED_BY_CONTRACT',\n  /** Taken, and the exposure retained knowingly. */\n  ACCEPTED = 'ACCEPTED',\n}\n\n/**\n * One signal's posture, and why.\n *\n * `rationale` is REQUIRED, for the same reason `dataRetention` requires one: a posture with no reason\n * is a token, and the thing a reviewer needs is the sentence, not the enum member. \"We accept it\" is\n * what the member already says.\n *\n * ## What is deliberately NOT here\n *\n * **No `decidedBy` and no `decidedAt`.** Acceptance is a COMMIT — `one-source-of-truth.md` rule 7 and\n * D5 — so the author and the instant are already recorded, mergeably and by a history everyone\n * audits. Fields restating them would be a second authority that can disagree with git, and they are\n * exactly the shape that made an earlier compliance record unproducible without forging an identity.\n *\n * **No review date.** `derive-before-you-ask.md` settles this: a date is a PROXY for \"an input may\n * have changed\", every input is in git and enumerable, so the trigger is computable and the date is\n * an output rather than something to type.\n */\nexport const ApplicationRiskPostureEntrySchema = z.strictObject({\n  posture: z.enum(RiskTreatmentPosture).describe('What the operator decided to do about this exposure.'),\n  rationale: z\n    .string()\n    .trim()\n    .min(1)\n    .describe('Why this posture, in the operator\\'s own words — the sentence a reviewer reads, not a restatement of the member.'),\n});\n\nexport type ApplicationRiskPostureEntry = z.infer<typeof ApplicationRiskPostureEntrySchema>;\n\n/**\n * An application's declared posture per risk signal — PARTIAL by construction.\n *\n * Every entry is optional and the whole declaration may be omitted. That is not laxity: a compliance\n * workflow may never stand in front of the mechanism (`application-creation-directive.md`), and a\n * required posture would make an application UNBUILDABLE until somebody decided something about\n * every signal the framework happens to derive. The undeclared set is REPORTED instead, by\n * {@link undeclaredRiskSignals}, which is the \"mark it, do not block\" shape that rule asks for.\n *\n * So absence is representable and means one thing — nobody has decided yet — and it is\n * distinguishable from `ACCEPTED`, which means somebody decided to live with it. Collapsing those two\n * is the failure this layer exists to avoid: silence is not acceptance.\n */\nexport const ApplicationRiskPostureSchema = z.record(\n  z.enum(ApplicationRiskSignalRef),\n  ApplicationRiskPostureEntrySchema,\n);\n\nexport type ApplicationRiskPosture = z.infer<typeof ApplicationRiskPostureSchema>;\n\n/**\n * The signals an application has declared NO posture for — what a register must mark as owed.\n *\n * Derived rather than stored, and total over the enum, so a signal added to the vocabulary tomorrow\n * is reported as undeclared by every existing application rather than silently omitted from the\n * answer. Deliberately the same shape as `undeclaredRetentionClasses`, because it is the same\n * question one layer over.\n */\nexport function undeclaredRiskSignals(\n  posture: ApplicationRiskPosture | undefined,\n): readonly ApplicationRiskSignalRef[] {\n  return Object.values(ApplicationRiskSignalRef).filter((signalRef) => posture?.[signalRef] === undefined);\n}\n\n/**\n * Postures that CLAIM AN EXPOSURE IS NOT TAKEN — the ones a measurement can contradict.\n *\n * Exported rather than inlined at the one call site, so the report and any later consumer ask the\n * same question. Today it is `AVOIDED` alone; if a future member is also falsifiable it joins here\n * and every consumer follows, which is the whole reason this is a function and not a comparison.\n */\nexport function riskPostureClaimsExposureAbsent(entry: ApplicationRiskPostureEntry | undefined): boolean {\n  return entry?.posture === RiskTreatmentPosture.AVOIDED;\n}\n"]}

package/dist/esm/config/analytics-value-moments.shared.schemas.d.ts

@@ -100,9 +100,10 @@ export type ValueSignal = z.infer<typeof ValueSignalSchema>;
  *
  * The `role` is the load-bearing field, because it changes three things at once — event naming,
  * whether the moment PERSISTS once achieved, and how the engine evaluates it. In particular
- * `ANTI_PATTERN` is deliberately NOT persisted and is the only role for which `cooldownMs` and
- * `beforeStage` mean anything: it is meant to re-fire while the behaviour continues and to stop
- * permanently once the person reaches the stage that makes it moot.
+ * `ANTI_PATTERN` is deliberately NOT persisted and uses `cooldownMs` to allow repeated notices
+ * while the behaviour continues. `beforeStage` is a general inverse prerequisite for every role:
+ * once any listed moment is achieved, evaluation is suppressed. It is especially useful for
+ * stopping an anti-pattern after the person reaches the stage that makes it moot.
  */
 export declare enum ValueMomentMode {
     /** ANY signal in the list triggers the moment (OR logic) */

package/dist/esm/config/analytics-value-moments.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analytics-value-moments.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/config/analytics-value-moments.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAcxB;;;GAGG;AACH,oBAAY,kBAAkB;IAC5B,SAAS,cAAc;IACvB,kBAAkB,uBAAuB;IACzC,KAAK,UAAU;IACf,UAAU,eAAe;IACzB,WAAW,gBAAgB;IAC3B,mBAAmB,wBAAwB;IAC3C,YAAY,iBAAiB;IAC7B,WAAW,gBAAgB;IAC3B,gBAAgB,qBAAqB;CACtC;AAED,mHAAmH;AACnH,eAAO,MAAM,yBAAyB,EAAG,cAAuB,CAAC;AAEjE,6DAA6D;AAC7D,eAAO,MAAM,iCAAiC,EAAG,eAAwB,CAAC;AAE1E,2DAA2D;AAC3D,oBAAY,sBAAsB;IAChC,QAAQ,aAAa;IACrB,OAAO,YAAY;CACpB;AAED,0DAA0D;AAC1D,oBAAY,kBAAkB;IAC5B,YAAY,iBAAiB;IAC7B,cAAc,mBAAmB;IACjC,aAAa,kBAAkB;IAC/B,cAAc,mBAAmB;IACjC,cAAc,mBAAmB;CAClC;AAED,sEAAsE;AACtE,eAAO,MAAM,qCAAqC,EAAG,2BAAoC,CAAC;AAI1F,oBAAY,eAAe;IACzB,kBAAkB,uBAAuB;IACzC,cAAc,mBAAmB;IACjC,UAAU,eAAe;IACzB,cAAc,mBAAmB;IACjC,YAAY,iBAAiB;CAC9B;AAID;;;GAGG;AACH,eAAO,MAAM,wBAAwB,oGAGpC,CAAC;AACF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAuD1E,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAM5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAI5D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,oBAAY,eAAe;IACzB,4DAA4D;IAC5D,GAAG,QAAQ;IACX,+CAA+C;IAC/C,GAAG,QAAQ;CACZ;AAED;;;GAGG;AACH,oBAAY,eAAe;IACzB,qFAAqF;IACrF,IAAI,SAAS;IACb,sDAAsD;IACtD,UAAU,eAAe;IACzB,+CAA+C;IAC/C,UAAU,eAAe;IACzB,uEAAuE;IACvE,YAAY,iBAAiB;CAC9B;AAED;;;GAGG;AACH,oBAAY,gBAAgB;IAC1B,sCAAsC;IACtC,IAAI,SAAS;IACb,oCAAoC;IACpC,YAAY,iBAAiB;CAC9B;AAID,eAAO,MAAM,yBAAyB;;;iBAWpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAI5E,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiD5B,CAAC;AACH,iEAAiE;AACjE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}
+{"version":3,"file":"analytics-value-moments.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/config/analytics-value-moments.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAcxB;;;GAGG;AACH,oBAAY,kBAAkB;IAC5B,SAAS,cAAc;IACvB,kBAAkB,uBAAuB;IACzC,KAAK,UAAU;IACf,UAAU,eAAe;IACzB,WAAW,gBAAgB;IAC3B,mBAAmB,wBAAwB;IAC3C,YAAY,iBAAiB;IAC7B,WAAW,gBAAgB;IAC3B,gBAAgB,qBAAqB;CACtC;AAED,mHAAmH;AACnH,eAAO,MAAM,yBAAyB,EAAG,cAAuB,CAAC;AAEjE,6DAA6D;AAC7D,eAAO,MAAM,iCAAiC,EAAG,eAAwB,CAAC;AAE1E,2DAA2D;AAC3D,oBAAY,sBAAsB;IAChC,QAAQ,aAAa;IACrB,OAAO,YAAY;CACpB;AAED,0DAA0D;AAC1D,oBAAY,kBAAkB;IAC5B,YAAY,iBAAiB;IAC7B,cAAc,mBAAmB;IACjC,aAAa,kBAAkB;IAC/B,cAAc,mBAAmB;IACjC,cAAc,mBAAmB;CAClC;AAED,sEAAsE;AACtE,eAAO,MAAM,qCAAqC,EAAG,2BAAoC,CAAC;AAI1F,oBAAY,eAAe;IACzB,kBAAkB,uBAAuB;IACzC,cAAc,mBAAmB;IACjC,UAAU,eAAe;IACzB,cAAc,mBAAmB;IACjC,YAAY,iBAAiB;CAC9B;AAID;;;GAGG;AACH,eAAO,MAAM,wBAAwB,oGAGpC,CAAC;AACF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAuD1E,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAM5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAI5D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,oBAAY,eAAe;IACzB,4DAA4D;IAC5D,GAAG,QAAQ;IACX,+CAA+C;IAC/C,GAAG,QAAQ;CACZ;AAED;;;GAGG;AACH,oBAAY,eAAe;IACzB,qFAAqF;IACrF,IAAI,SAAS;IACb,sDAAsD;IACtD,UAAU,eAAe;IACzB,+CAA+C;IAC/C,UAAU,eAAe;IACzB,uEAAuE;IACvE,YAAY,iBAAiB;CAC9B;AAED;;;GAGG;AACH,oBAAY,gBAAgB;IAC1B,sCAAsC;IACtC,IAAI,SAAS;IACb,oCAAoC;IACpC,YAAY,iBAAiB;CAC9B;AAID,eAAO,MAAM,yBAAyB;;;iBAWpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAI5E,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiD5B,CAAC;AACH,iEAAiE;AACjE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/esm/config/analytics-value-moments.shared.schemas.js

@@ -139,9 +139,10 @@ export const ValueSignalSchema = z.discriminatedUnion('signalType', [
  *
  * The `role` is the load-bearing field, because it changes three things at once — event naming,
  * whether the moment PERSISTS once achieved, and how the engine evaluates it. In particular
- * `ANTI_PATTERN` is deliberately NOT persisted and is the only role for which `cooldownMs` and
- * `beforeStage` mean anything: it is meant to re-fire while the behaviour continues and to stop
- * permanently once the person reaches the stage that makes it moot.
+ * `ANTI_PATTERN` is deliberately NOT persisted and uses `cooldownMs` to allow repeated notices
+ * while the behaviour continues. `beforeStage` is a general inverse prerequisite for every role:
+ * once any listed moment is achieved, evaluation is suppressed. It is especially useful for
+ * stopping an anti-pattern after the person reaches the stage that makes it moot.
  */
 export var ValueMomentMode;
 (function (ValueMomentMode) {

package/dist/esm/config/analytics-value-moments.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"analytics-value-moments.shared.schemas.js","sourceRoot":"","sources":["../../../../src/config/analytics-value-moments.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Analytics Value Moment Schemas\n * \n * Defines value signals and value moments for the analytics system.\n * Value moments represent meaningful milestones in a user's journey\n * (TTFV, aha moments, activation stages, anti-patterns).\n */\n\nimport { z } from 'zod';\n\n/** Navigation content type values for VIEW_VISIT signals. Inlined here — canonical enum lives in saas-frontend-lib (navigation-v3.schemas). */\nconst NAVIGATION_CONTENT_TYPES = [\n  'resource_operation',\n  'composite_view',\n  'chart_view',\n  'full_custom_view',\n  'flows_actors_view',\n  'custom',\n] as const;\n\n// ─── Analytics Event Names (auto-instrumentation) ───────────────\n\n/**\n * Built-in analytics track event names used by auto-instrumentation.\n * App-custom events use arbitrary strings via track(name, properties).\n */\nexport enum AnalyticsEventName {\n  PAGE_VIEW = 'page_view',\n  RESOURCE_OPERATION = 'resource_operation',\n  ERROR = 'error',\n  USER_LOGIN = 'user_login',\n  USER_LOGOUT = 'user_logout',\n  USER_STATUS_CHANGED = 'user_status_changed',\n  NOTIFICATION = 'notification',\n  HOTKEY_USED = 'hotkey_used',\n  FEATURE_ACCESSED = 'feature_accessed',\n}\n\n/** Event name prefix for value moments (TTFV, aha, activation). Anti-pattern uses ValueMomentRole.ANTI_PATTERN. */\nexport const VALUE_MOMENT_EVENT_PREFIX = 'value_moment' as const;\n\n/** Signal type value when ALL mode signals are completed. */\nexport const VALUE_MOMENT_SIGNAL_ALL_COMPLETED = 'all_completed' as const;\n\n/** Trigger source for ANALYTICS_MOMENT_ACHIEVED events. */\nexport enum AnalyticsTriggerSource {\n  FRONTEND = 'frontend',\n  BACKEND = 'backend',\n}\n\n/** Hotkey key values for HOTKEY_USED analytics events. */\nexport enum AnalyticsHotkeyKey {\n  COMMAND_MENU = 'command_menu',\n  SIDEBAR_TOGGLE = 'sidebar_toggle',\n  NOTIFICATIONS = 'notifications',\n  QUICK_SWITCHER = 'quick_switcher',\n  SHORTCUTS_HELP = 'shortcuts_help',\n}\n\n/** Storage key prefix for achieved moments (suffixed with userId). */\nexport const ANALYTICS_ACHIEVED_STORAGE_KEY_PREFIX = 'wildo_analytics_achieved_' as const;\n\n// ─── Signal Types ───────────────────────────────────────────────\n\nexport enum ValueSignalType {\n  RESOURCE_OPERATION = 'resource_operation',\n  RESOURCE_STATE = 'resource_state',\n  VIEW_VISIT = 'view_visit',\n  FEATURE_ACCESS = 'feature_access',\n  CUSTOM_EVENT = 'custom_event',\n}\n\n// ─── Primitive filter (shallow equality matching only) ──────────\n\n/**\n * Only primitive values supported — no nested objects or arrays.\n * The engine evaluates: Object.entries(filter).every(([k, v]) => resource[k] === v)\n */\nexport const ValueSignal_FilterSchema = z.record(\n  z.string(),\n  z.union([z.string(), z.number(), z.boolean(), z.null()])\n);\nexport type ValueSignal_Filter = z.infer<typeof ValueSignal_FilterSchema>;\n\n// ─── Signal variant schemas (discriminated union on `signalType` — avoids Mongoose reserved `type`) ─────\n\nconst ValueSignal_ResourceOperationSchema = z.object({\n  signalType: z.literal(ValueSignalType.RESOURCE_OPERATION),\n  /** Resource type identifier (e.g., 'PROJECTS', 'REPORTS') */\n  resourceType: z.string().min(1),\n  /** Operation identifier (e.g., CoreResourceOperation.CREATE) */\n  operation: z.string().min(1),\n  /**\n   * Optional resource field filter. Only operations on resources matching this\n   * filter count. Filter evaluation requires the NOTIFY_RESOURCE_SUCCESS event\n   * to carry a `resultSummary` field.\n   */\n  filter: ValueSignal_FilterSchema.optional(),\n  /**\n   * Minimum occurrence count required. When omitted (or 1), the first matching event fires.\n   * When > 1, the engine counts matching events and fires at the N-th occurrence.\n   */\n  threshold: z.number().min(1).optional(),\n});\n\nconst ValueSignal_ResourceStateSchema = z.object({\n  signalType: z.literal(ValueSignalType.RESOURCE_STATE),\n  /** Resource type to count */\n  resourceType: z.string().min(1),\n  /** Field filter for counting */\n  filter: ValueSignal_FilterSchema.optional(),\n  /** Minimum count required to satisfy this signal */\n  threshold: z.number().min(1),\n});\n\nconst ValueSignal_ViewVisitSchema = z.object({\n  signalType: z.literal(ValueSignalType.VIEW_VISIT),\n  /** Navigation content type (e.g., COMPOSITE_VIEW, CHART_VIEW) */\n  contentType: z.enum(NAVIGATION_CONTENT_TYPES),\n  /** Specific view reference. If omitted, any view of this contentType qualifies. */\n  viewRef: z.string().optional(),\n});\n\nconst ValueSignal_FeatureAccessSchema = z.object({\n  signalType: z.literal(ValueSignalType.FEATURE_ACCESS),\n  /** Feature identifier from FeatureDefinition */\n  featureId: z.string().min(1),\n});\n\nconst ValueSignal_CustomEventSchema = z.object({\n  signalType: z.literal(ValueSignalType.CUSTOM_EVENT),\n  /** Custom event name (tracked via useAnalytics().track() or backend emitSignal()) */\n  eventName: z.string().min(1),\n  /** Threshold: number of occurrences before the signal fires. Default: 1 */\n  threshold: z.number().min(1).optional(),\n});\n\nexport const ValueSignalSchema = z.discriminatedUnion('signalType', [\n  ValueSignal_ResourceOperationSchema,\n  ValueSignal_ResourceStateSchema,\n  ValueSignal_ViewVisitSchema,\n  ValueSignal_FeatureAccessSchema,\n  ValueSignal_CustomEventSchema,\n]);\nexport type ValueSignal = z.infer<typeof ValueSignalSchema>;\n\n// ─── Value Moment Enums ─────────────────────────────────────────\n\n/**\n * @wildo_source:part:start saas.models.analytics.value-moments facet:layer:shared facet:audience:app-developer\n *\n * A VALUE MOMENT is something meaningful happening in a person's journey — first value reached, an\n * aha moment, an activation stage, or an anti-pattern worth noticing. An application declares them\n * as `analytics.valueMoments`, and reads `achievedMoments` from the analytics context to drive an\n * onboarding surface.\n *\n * ⚠️ **They need the ANALYTICS capability enabled.** `analytics.enabled` is a master switch —\n * `false` means no analytics at all, whatever a user consented to — so a declared value moment with\n * analytics off is evaluated by nothing and the surface reading `achievedMoments` renders empty.\n * Enabling analytics with an EMPTY provider list is how an application gets the internal progression\n * plane without telemetry leaving it.\n *\n * The `role` is the load-bearing field, because it changes three things at once — event naming,\n * whether the moment PERSISTS once achieved, and how the engine evaluates it. In particular\n * `ANTI_PATTERN` is deliberately NOT persisted and is the only role for which `cooldownMs` and\n * `beforeStage` mean anything: it is meant to re-fire while the behaviour continues and to stop\n * permanently once the person reaches the stage that makes it moot.\n */\nexport enum ValueMomentMode {\n  /** ANY signal in the list triggers the moment (OR logic) */\n  ANY = 'ANY',\n  /** ALL signals must be achieved (AND logic) */\n  ALL = 'ALL',\n}\n\n/**\n * Semantic role of a value moment.\n * Determines event naming, persistence behavior, and how the system treats the moment.\n */\nexport enum ValueMomentRole {\n  /** Time to First Value — the primary metric. Exactly 0 or 1 per scope per config. */\n  TTFV = 'ttfv',\n  /** Aha moment — behavior correlated with retention */\n  AHA_MOMENT = 'aha_moment',\n  /** Activation stage — progression milestone */\n  ACTIVATION = 'activation',\n  /** Anti-pattern — negative signal correlated with churn/frustration */\n  ANTI_PATTERN = 'anti_pattern',\n}\n\n/**\n * Scope entity for the value moment.\n * Determines whose journey is being measured and where achieved state is persisted.\n */\nexport enum ValueMomentScope {\n  /** Per-user value moment (default) */\n  USER = 'user',\n  /** Per-organization value moment */\n  ORGANIZATION = 'organization',\n}\n\n// ─── Value Moment Callback ──────────────────────────────────────\n\nexport const ValueMomentCallbackSchema = z.object({\n  /**\n   * Frontend: when true, emits FrontendEvents.ANALYTICS_MOMENT_ACHIEVED on achievement.\n   * App-custom code subscribes and filters by momentIdentifier for custom reactions.\n   */\n  frontendEvent: z.boolean().default(false),\n  /**\n   * Backend: Registered handler identifier to invoke when achieved.\n   * Handler resolved from a registry (similar to resource custom service implementations).\n   */\n  backendHandler: z.string().optional(),\n});\nexport type ValueMomentCallback = z.infer<typeof ValueMomentCallbackSchema>;\n\n// ─── Value Moment Definition ────────────────────────────────────\n\nexport const ValueMomentSchema = z.object({\n  /** Unique identifier (used as analytics event name prefix + persistence key) */\n  identifier: z.string().min(1),\n\n  /**\n   * Semantic role. Determines:\n   * - Event naming: TTFV/AHA_MOMENT/ACTIVATION emit 'value_moment.{id}', ANTI_PATTERN emits 'anti_pattern.{id}'\n   * - Persistence: TTFV/AHA_MOMENT/ACTIVATION are persisted once achieved. ANTI_PATTERN is NOT persisted.\n   * - Engine behavior: ANTI_PATTERN uses cooldownMs + beforeStage.\n   */\n  role: z.enum(ValueMomentRole),\n\n  /**\n   * Scope entity. Determines whose journey is measured.\n   * USER: per-user (default). ORGANIZATION: per-org.\n   */\n  scope: z.enum(ValueMomentScope).default(ValueMomentScope.USER),\n\n  /** Signals that compose this value moment */\n  signals: z.array(ValueSignalSchema).min(1),\n\n  /** Composition mode: ANY = first signal wins, ALL = all signals required */\n  mode: z.enum(ValueMomentMode).default(ValueMomentMode.ANY),\n\n  /**\n   * Prerequisite moment identifiers. This moment only starts evaluating\n   * AFTER all prerequisite moments have been achieved.\n   */\n  requires: z.array(z.string()).optional(),\n\n  /**\n   * Inverse prerequisite: this moment only evaluates BEFORE the specified\n   * stage(s) have been achieved. Once any beforeStage moment is achieved,\n   * this moment is permanently suppressed. Primarily used for ANTI_PATTERN role.\n   */\n  beforeStage: z.array(z.string()).optional(),\n\n  /**\n   * Cooldown in milliseconds between re-firings (only meaningful for ANTI_PATTERN role).\n   * Default: 300_000 (5 minutes) for ANTI_PATTERN, ignored for other roles.\n   */\n  cooldownMs: z.number().min(0).optional(),\n\n  /**\n   * Callback hooks triggered when the moment is achieved.\n   * - frontendEvent: emits ANALYTICS_MOMENT_ACHIEVED on the EventBus\n   * - backendHandler: invokes a registered handler\n   */\n  onAchieved: ValueMomentCallbackSchema.optional(),\n});\n/** @wildo_source:part:end saas.models.analytics.value-moments */\nexport type ValueMoment = z.infer<typeof ValueMomentSchema>;\n"]}
+{"version":3,"file":"analytics-value-moments.shared.schemas.js","sourceRoot":"","sources":["../../../../src/config/analytics-value-moments.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,+IAA+I;AAC/I,MAAM,wBAAwB,GAAG;IAC/B,oBAAoB;IACpB,gBAAgB;IAChB,YAAY;IACZ,kBAAkB;IAClB,mBAAmB;IACnB,QAAQ;CACA,CAAC;AAEX,mEAAmE;AAEnE;;;GAGG;AACH,MAAM,CAAN,IAAY,kBAUX;AAVD,WAAY,kBAAkB;IAC5B,6CAAuB,CAAA;IACvB,+DAAyC,CAAA;IACzC,qCAAe,CAAA;IACf,+CAAyB,CAAA;IACzB,iDAA2B,CAAA;IAC3B,iEAA2C,CAAA;IAC3C,mDAA6B,CAAA;IAC7B,iDAA2B,CAAA;IAC3B,2DAAqC,CAAA;AACvC,CAAC,EAVW,kBAAkB,KAAlB,kBAAkB,QAU7B;AAED,mHAAmH;AACnH,MAAM,CAAC,MAAM,yBAAyB,GAAG,cAAuB,CAAC;AAEjE,6DAA6D;AAC7D,MAAM,CAAC,MAAM,iCAAiC,GAAG,eAAwB,CAAC;AAE1E,2DAA2D;AAC3D,MAAM,CAAN,IAAY,sBAGX;AAHD,WAAY,sBAAsB;IAChC,+CAAqB,CAAA;IACrB,6CAAmB,CAAA;AACrB,CAAC,EAHW,sBAAsB,KAAtB,sBAAsB,QAGjC;AAED,0DAA0D;AAC1D,MAAM,CAAN,IAAY,kBAMX;AAND,WAAY,kBAAkB;IAC5B,mDAA6B,CAAA;IAC7B,uDAAiC,CAAA;IACjC,qDAA+B,CAAA;IAC/B,uDAAiC,CAAA;IACjC,uDAAiC,CAAA;AACnC,CAAC,EANW,kBAAkB,KAAlB,kBAAkB,QAM7B;AAED,sEAAsE;AACtE,MAAM,CAAC,MAAM,qCAAqC,GAAG,2BAAoC,CAAC;AAE1F,mEAAmE;AAEnE,MAAM,CAAN,IAAY,eAMX;AAND,WAAY,eAAe;IACzB,4DAAyC,CAAA;IACzC,oDAAiC,CAAA;IACjC,4CAAyB,CAAA;IACzB,oDAAiC,CAAA;IACjC,gDAA6B,CAAA;AAC/B,CAAC,EANW,eAAe,KAAf,eAAe,QAM1B;AAED,mEAAmE;AAEnE;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAC9C,CAAC,CAAC,MAAM,EAAE,EACV,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CACzD,CAAC;AAGF,2GAA2G;AAE3G,MAAM,mCAAmC,GAAG,CAAC,CAAC,MAAM,CAAC;IACnD,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,kBAAkB,CAAC;IACzD,6DAA6D;IAC7D,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/B,gEAAgE;IAChE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B;;;;OAIG;IACH,MAAM,EAAE,wBAAwB,CAAC,QAAQ,EAAE;IAC3C;;;OAGG;IACH,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CACxC,CAAC,CAAC;AAEH,MAAM,+BAA+B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,cAAc,CAAC;IACrD,6BAA6B;IAC7B,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/B,gCAAgC;IAChC,MAAM,EAAE,wBAAwB,CAAC,QAAQ,EAAE;IAC3C,oDAAoD;IACpD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAC7B,CAAC,CAAC;AAEH,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,UAAU,CAAC;IACjD,iEAAiE;IACjE,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,wBAAwB,CAAC;IAC7C,mFAAmF;IACnF,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC/B,CAAC,CAAC;AAEH,MAAM,+BAA+B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,cAAc,CAAC;IACrD,gDAAgD;IAChD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAC7B,CAAC,CAAC;AAEH,MAAM,6BAA6B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,YAAY,CAAC;IACnD,qFAAqF;IACrF,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,2EAA2E;IAC3E,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CACxC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,kBAAkB,CAAC,YAAY,EAAE;IAClE,mCAAmC;IACnC,+BAA+B;IAC/B,2BAA2B;IAC3B,+BAA+B;IAC/B,6BAA6B;CAC9B,CAAC,CAAC;AAGH,mEAAmE;AAEnE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAN,IAAY,eAKX;AALD,WAAY,eAAe;IACzB,4DAA4D;IAC5D,8BAAW,CAAA;IACX,+CAA+C;IAC/C,8BAAW,CAAA;AACb,CAAC,EALW,eAAe,KAAf,eAAe,QAK1B;AAED;;;GAGG;AACH,MAAM,CAAN,IAAY,eASX;AATD,WAAY,eAAe;IACzB,qFAAqF;IACrF,gCAAa,CAAA;IACb,sDAAsD;IACtD,4CAAyB,CAAA;IACzB,+CAA+C;IAC/C,4CAAyB,CAAA;IACzB,uEAAuE;IACvE,gDAA6B,CAAA;AAC/B,CAAC,EATW,eAAe,KAAf,eAAe,QAS1B;AAED;;;GAGG;AACH,MAAM,CAAN,IAAY,gBAKX;AALD,WAAY,gBAAgB;IAC1B,sCAAsC;IACtC,iCAAa,CAAA;IACb,oCAAoC;IACpC,iDAA6B,CAAA;AAC/B,CAAC,EALW,gBAAgB,KAAhB,gBAAgB,QAK3B;AAED,mEAAmE;AAEnE,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD;;;OAGG;IACH,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACzC;;;OAGG;IACH,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACtC,CAAC,CAAC;AAGH,mEAAmE;AAEnE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,gFAAgF;IAChF,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAE7B;;;;;OAKG;IACH,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC;IAE7B;;;OAGG;IACH,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC,IAAI,CAAC;IAE9D,6CAA6C;IAC7C,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAE1C,4EAA4E;IAC5E,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,GAAG,CAAC;IAE1D;;;OAGG;IACH,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IAExC;;;;OAIG;IACH,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IAE3C;;;OAGG;IACH,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAExC;;;;OAIG;IACH,UAAU,EAAE,yBAAyB,CAAC,QAAQ,EAAE;CACjD,CAAC,CAAC","sourcesContent":["/**\n * Analytics Value Moment Schemas\n * \n * Defines value signals and value moments for the analytics system.\n * Value moments represent meaningful milestones in a user's journey\n * (TTFV, aha moments, activation stages, anti-patterns).\n */\n\nimport { z } from 'zod';\n\n/** Navigation content type values for VIEW_VISIT signals. Inlined here — canonical enum lives in saas-frontend-lib (navigation-v3.schemas). */\nconst NAVIGATION_CONTENT_TYPES = [\n  'resource_operation',\n  'composite_view',\n  'chart_view',\n  'full_custom_view',\n  'flows_actors_view',\n  'custom',\n] as const;\n\n// ─── Analytics Event Names (auto-instrumentation) ───────────────\n\n/**\n * Built-in analytics track event names used by auto-instrumentation.\n * App-custom events use arbitrary strings via track(name, properties).\n */\nexport enum AnalyticsEventName {\n  PAGE_VIEW = 'page_view',\n  RESOURCE_OPERATION = 'resource_operation',\n  ERROR = 'error',\n  USER_LOGIN = 'user_login',\n  USER_LOGOUT = 'user_logout',\n  USER_STATUS_CHANGED = 'user_status_changed',\n  NOTIFICATION = 'notification',\n  HOTKEY_USED = 'hotkey_used',\n  FEATURE_ACCESSED = 'feature_accessed',\n}\n\n/** Event name prefix for value moments (TTFV, aha, activation). Anti-pattern uses ValueMomentRole.ANTI_PATTERN. */\nexport const VALUE_MOMENT_EVENT_PREFIX = 'value_moment' as const;\n\n/** Signal type value when ALL mode signals are completed. */\nexport const VALUE_MOMENT_SIGNAL_ALL_COMPLETED = 'all_completed' as const;\n\n/** Trigger source for ANALYTICS_MOMENT_ACHIEVED events. */\nexport enum AnalyticsTriggerSource {\n  FRONTEND = 'frontend',\n  BACKEND = 'backend',\n}\n\n/** Hotkey key values for HOTKEY_USED analytics events. */\nexport enum AnalyticsHotkeyKey {\n  COMMAND_MENU = 'command_menu',\n  SIDEBAR_TOGGLE = 'sidebar_toggle',\n  NOTIFICATIONS = 'notifications',\n  QUICK_SWITCHER = 'quick_switcher',\n  SHORTCUTS_HELP = 'shortcuts_help',\n}\n\n/** Storage key prefix for achieved moments (suffixed with userId). */\nexport const ANALYTICS_ACHIEVED_STORAGE_KEY_PREFIX = 'wildo_analytics_achieved_' as const;\n\n// ─── Signal Types ───────────────────────────────────────────────\n\nexport enum ValueSignalType {\n  RESOURCE_OPERATION = 'resource_operation',\n  RESOURCE_STATE = 'resource_state',\n  VIEW_VISIT = 'view_visit',\n  FEATURE_ACCESS = 'feature_access',\n  CUSTOM_EVENT = 'custom_event',\n}\n\n// ─── Primitive filter (shallow equality matching only) ──────────\n\n/**\n * Only primitive values supported — no nested objects or arrays.\n * The engine evaluates: Object.entries(filter).every(([k, v]) => resource[k] === v)\n */\nexport const ValueSignal_FilterSchema = z.record(\n  z.string(),\n  z.union([z.string(), z.number(), z.boolean(), z.null()])\n);\nexport type ValueSignal_Filter = z.infer<typeof ValueSignal_FilterSchema>;\n\n// ─── Signal variant schemas (discriminated union on `signalType` — avoids Mongoose reserved `type`) ─────\n\nconst ValueSignal_ResourceOperationSchema = z.object({\n  signalType: z.literal(ValueSignalType.RESOURCE_OPERATION),\n  /** Resource type identifier (e.g., 'PROJECTS', 'REPORTS') */\n  resourceType: z.string().min(1),\n  /** Operation identifier (e.g., CoreResourceOperation.CREATE) */\n  operation: z.string().min(1),\n  /**\n   * Optional resource field filter. Only operations on resources matching this\n   * filter count. Filter evaluation requires the NOTIFY_RESOURCE_SUCCESS event\n   * to carry a `resultSummary` field.\n   */\n  filter: ValueSignal_FilterSchema.optional(),\n  /**\n   * Minimum occurrence count required. When omitted (or 1), the first matching event fires.\n   * When > 1, the engine counts matching events and fires at the N-th occurrence.\n   */\n  threshold: z.number().min(1).optional(),\n});\n\nconst ValueSignal_ResourceStateSchema = z.object({\n  signalType: z.literal(ValueSignalType.RESOURCE_STATE),\n  /** Resource type to count */\n  resourceType: z.string().min(1),\n  /** Field filter for counting */\n  filter: ValueSignal_FilterSchema.optional(),\n  /** Minimum count required to satisfy this signal */\n  threshold: z.number().min(1),\n});\n\nconst ValueSignal_ViewVisitSchema = z.object({\n  signalType: z.literal(ValueSignalType.VIEW_VISIT),\n  /** Navigation content type (e.g., COMPOSITE_VIEW, CHART_VIEW) */\n  contentType: z.enum(NAVIGATION_CONTENT_TYPES),\n  /** Specific view reference. If omitted, any view of this contentType qualifies. */\n  viewRef: z.string().optional(),\n});\n\nconst ValueSignal_FeatureAccessSchema = z.object({\n  signalType: z.literal(ValueSignalType.FEATURE_ACCESS),\n  /** Feature identifier from FeatureDefinition */\n  featureId: z.string().min(1),\n});\n\nconst ValueSignal_CustomEventSchema = z.object({\n  signalType: z.literal(ValueSignalType.CUSTOM_EVENT),\n  /** Custom event name (tracked via useAnalytics().track() or backend emitSignal()) */\n  eventName: z.string().min(1),\n  /** Threshold: number of occurrences before the signal fires. Default: 1 */\n  threshold: z.number().min(1).optional(),\n});\n\nexport const ValueSignalSchema = z.discriminatedUnion('signalType', [\n  ValueSignal_ResourceOperationSchema,\n  ValueSignal_ResourceStateSchema,\n  ValueSignal_ViewVisitSchema,\n  ValueSignal_FeatureAccessSchema,\n  ValueSignal_CustomEventSchema,\n]);\nexport type ValueSignal = z.infer<typeof ValueSignalSchema>;\n\n// ─── Value Moment Enums ─────────────────────────────────────────\n\n/**\n * @wildo_source:part:start saas.models.analytics.value-moments facet:layer:shared facet:audience:app-developer\n *\n * A VALUE MOMENT is something meaningful happening in a person's journey — first value reached, an\n * aha moment, an activation stage, or an anti-pattern worth noticing. An application declares them\n * as `analytics.valueMoments`, and reads `achievedMoments` from the analytics context to drive an\n * onboarding surface.\n *\n * ⚠️ **They need the ANALYTICS capability enabled.** `analytics.enabled` is a master switch —\n * `false` means no analytics at all, whatever a user consented to — so a declared value moment with\n * analytics off is evaluated by nothing and the surface reading `achievedMoments` renders empty.\n * Enabling analytics with an EMPTY provider list is how an application gets the internal progression\n * plane without telemetry leaving it.\n *\n * The `role` is the load-bearing field, because it changes three things at once — event naming,\n * whether the moment PERSISTS once achieved, and how the engine evaluates it. In particular\n * `ANTI_PATTERN` is deliberately NOT persisted and uses `cooldownMs` to allow repeated notices\n * while the behaviour continues. `beforeStage` is a general inverse prerequisite for every role:\n * once any listed moment is achieved, evaluation is suppressed. It is especially useful for\n * stopping an anti-pattern after the person reaches the stage that makes it moot.\n */\nexport enum ValueMomentMode {\n  /** ANY signal in the list triggers the moment (OR logic) */\n  ANY = 'ANY',\n  /** ALL signals must be achieved (AND logic) */\n  ALL = 'ALL',\n}\n\n/**\n * Semantic role of a value moment.\n * Determines event naming, persistence behavior, and how the system treats the moment.\n */\nexport enum ValueMomentRole {\n  /** Time to First Value — the primary metric. Exactly 0 or 1 per scope per config. */\n  TTFV = 'ttfv',\n  /** Aha moment — behavior correlated with retention */\n  AHA_MOMENT = 'aha_moment',\n  /** Activation stage — progression milestone */\n  ACTIVATION = 'activation',\n  /** Anti-pattern — negative signal correlated with churn/frustration */\n  ANTI_PATTERN = 'anti_pattern',\n}\n\n/**\n * Scope entity for the value moment.\n * Determines whose journey is being measured and where achieved state is persisted.\n */\nexport enum ValueMomentScope {\n  /** Per-user value moment (default) */\n  USER = 'user',\n  /** Per-organization value moment */\n  ORGANIZATION = 'organization',\n}\n\n// ─── Value Moment Callback ──────────────────────────────────────\n\nexport const ValueMomentCallbackSchema = z.object({\n  /**\n   * Frontend: when true, emits FrontendEvents.ANALYTICS_MOMENT_ACHIEVED on achievement.\n   * App-custom code subscribes and filters by momentIdentifier for custom reactions.\n   */\n  frontendEvent: z.boolean().default(false),\n  /**\n   * Backend: Registered handler identifier to invoke when achieved.\n   * Handler resolved from a registry (similar to resource custom service implementations).\n   */\n  backendHandler: z.string().optional(),\n});\nexport type ValueMomentCallback = z.infer<typeof ValueMomentCallbackSchema>;\n\n// ─── Value Moment Definition ────────────────────────────────────\n\nexport const ValueMomentSchema = z.object({\n  /** Unique identifier (used as analytics event name prefix + persistence key) */\n  identifier: z.string().min(1),\n\n  /**\n   * Semantic role. Determines:\n   * - Event naming: TTFV/AHA_MOMENT/ACTIVATION emit 'value_moment.{id}', ANTI_PATTERN emits 'anti_pattern.{id}'\n   * - Persistence: TTFV/AHA_MOMENT/ACTIVATION are persisted once achieved. ANTI_PATTERN is NOT persisted.\n   * - Engine behavior: ANTI_PATTERN uses cooldownMs + beforeStage.\n   */\n  role: z.enum(ValueMomentRole),\n\n  /**\n   * Scope entity. Determines whose journey is measured.\n   * USER: per-user (default). ORGANIZATION: per-org.\n   */\n  scope: z.enum(ValueMomentScope).default(ValueMomentScope.USER),\n\n  /** Signals that compose this value moment */\n  signals: z.array(ValueSignalSchema).min(1),\n\n  /** Composition mode: ANY = first signal wins, ALL = all signals required */\n  mode: z.enum(ValueMomentMode).default(ValueMomentMode.ANY),\n\n  /**\n   * Prerequisite moment identifiers. This moment only starts evaluating\n   * AFTER all prerequisite moments have been achieved.\n   */\n  requires: z.array(z.string()).optional(),\n\n  /**\n   * Inverse prerequisite: this moment only evaluates BEFORE the specified\n   * stage(s) have been achieved. Once any beforeStage moment is achieved,\n   * this moment is permanently suppressed. Primarily used for ANTI_PATTERN role.\n   */\n  beforeStage: z.array(z.string()).optional(),\n\n  /**\n   * Cooldown in milliseconds between re-firings (only meaningful for ANTI_PATTERN role).\n   * Default: 300_000 (5 minutes) for ANTI_PATTERN, ignored for other roles.\n   */\n  cooldownMs: z.number().min(0).optional(),\n\n  /**\n   * Callback hooks triggered when the moment is achieved.\n   * - frontendEvent: emits ANALYTICS_MOMENT_ACHIEVED on the EventBus\n   * - backendHandler: invokes a registered handler\n   */\n  onAchieved: ValueMomentCallbackSchema.optional(),\n});\n/** @wildo_source:part:end saas.models.analytics.value-moments */\nexport type ValueMoment = z.infer<typeof ValueMomentSchema>;\n"]}