@wildo-ai/saas-models 1.1.4 → 1.1.5

package/dist/esm/compliance/privacy/ai-use-posture.shared.schemas.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { engineCapabilityReachesRuntimeService } from '../../external-providers/engine-capability-surface.shared.js';
 import { EngineCapability } from "../../external-providers/engine-capabilities.shared.schemas.js";
 /**
  * **Whether an AI use DECIDES something about a person, and who reviews it if so.**
@@ -106,7 +107,44 @@ export const AI_ENGINE_CAPABILITIES = Object.freeze([
     EngineCapability.AI_EMBEDDINGS,
     EngineCapability.AI_DOCUMENT_EXTRACTION,
     EngineCapability.AI_CODING_AGENT,
+    /*
+     * ADDED 2026-09-12, and its absence was a hole rather than a judgement.
+     *
+     * Generating an image from a person's prompt, or from their content, is AI processing by any
+     * reading a notice has to survive — and because this list is what a document ASKS about, omitting
+     * it meant an application offering image generation to its users was asked NOTHING about AI. The
+     * omission was silent in the direction that matters: the notice reads complete.
+     *
+     * It was noticed while adding the surface axis and deliberately not slipped into that change,
+     * because widening this vocabulary changes what an application must declare. Measured before
+     * landing: Wonder Todos enables the capability and its only provider offering it sits in the
+     * COMPANION scope (the brand/logo generator), so the scope resolution keeps it outside the
+     * contracted service and its notice is unchanged. An application that binds an image provider to
+     * a RUNTIME scope is now asked for a posture, which is the whole point.
+     */
+    EngineCapability.AI_IMAGE_GENERATION,
 ]);
+/**
+ * The AI capabilities a document about the CONTRACTED SERVICE must ask about.
+ *
+ * The set above, minus the capabilities that never run while the application serves a user. This is
+ * the set a privacy notice, a record of processing and an Article 22 automated-decision statement
+ * are about, and the distinction is not cosmetic: `AI_CODING_AGENT` is a build-time tool that writes
+ * the application's SOURCE. It decides nothing about a data subject and processes none of their
+ * data, so asking an operator to declare its "posture" toward people, or listing it as OUTSTANDING
+ * in a notice, invents an AI question the service does not raise.
+ *
+ * That is not hypothetical. Wonder CRM enables `AI_CODING_AGENT` and no other AI capability. Under
+ * the unfiltered set the drafter is pushed into the per-capability AI branch — the branch that asks
+ * "whether it DECIDES something about a person" — for an application whose contracted service
+ * performs no AI at all, and whose own declared fact says exactly that.
+ *
+ * DERIVED rather than listed, and total over the set above, so an AI capability added tomorrow lands
+ * on the right side of this line by its DECLARED SURFACE rather than by anyone remembering to add it
+ * here. The surface map is itself exhaustive over `EngineCapability`, so there is no default to fall
+ * through.
+ */
+export const AI_ENGINE_CAPABILITIES_IN_THE_CONTRACTED_SERVICE = Object.freeze(AI_ENGINE_CAPABILITIES.filter((capability) => engineCapabilityReachesRuntimeService(capability)));
 /**
  * Enabled AI capabilities with no declared posture — what a document must report as outstanding.
  *
@@ -115,6 +153,6 @@ export const AI_ENGINE_CAPABILITIES = Object.freeze([
  */
 export function undeclaredAiUseCapabilities(enabledCapabilities, posture) {
     const enabled = new Set(enabledCapabilities);
-    return AI_ENGINE_CAPABILITIES.filter((capability) => enabled.has(capability) && posture?.[capability] === undefined);
+    return AI_ENGINE_CAPABILITIES_IN_THE_CONTRACTED_SERVICE.filter((capability) => enabled.has(capability) && posture?.[capability] === undefined);
 }
 //# sourceMappingURL=ai-use-posture.shared.schemas.js.map

package/dist/esm/compliance/privacy/ai-use-posture.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"ai-use-posture.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/compliance/privacy/ai-use-posture.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,6DAA6D,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAN,IAAY,qBAoBX;AApBD,WAAY,qBAAqB;IAC/B;;;;;;OAMG;IACH,oDAA2B,CAAA;IAC3B;;;;;;;OAOG;IACH,0EAAiD,CAAA;IACjD,+FAA+F;IAC/F,sEAA6C,CAAA;AAC/C,CAAC,EApBW,qBAAqB,KAArB,qBAAqB,QAoBhC;AAED,4CAA4C;AAC5C,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC;KAChC,YAAY,CAAC;IACZ,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC;IAC1C;;;;;;OAMG;IACH,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC;;;;;;;OAOG;IACH,sBAAsB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CAC5D,CAAC;KACD,WAAW,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE;IAChC,IAAI,OAAO,CAAC,WAAW,KAAK,qBAAqB,CAAC,WAAW,EAAE,CAAC;QAC9D,IAAI,OAAO,CAAC,sBAAsB,KAAK,IAAI,EAAE,CAAC;YAC5C,OAAO,CAAC,QAAQ,CAAC;gBACf,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,CAAC,wBAAwB,CAAC;gBAChC,OAAO,EAAE,wEAAwE;aAClF,CAAC,CAAC;QACL,CAAC;QACD,OAAO;IACT,CAAC;IACD,IAAI,OAAO,CAAC,sBAAsB,KAAK,IAAI,EAAE,CAAC;QAC5C,OAAO,CAAC,QAAQ,CAAC;YACf,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,wBAAwB,CAAC;YAChC,OAAO,EAAE,KAAK,OAAO,CAAC,WAAW,0EAA0E;SAC5G,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC,CAAC;AAGL;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,EAAE,kBAAkB,CAAC,CAAC;AAG3G;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAgC,MAAM,CAAC,MAAM,CAAC;IAC/E,gBAAgB,CAAC,MAAM;IACvB,gBAAgB,CAAC,aAAa;IAC9B,gBAAgB,CAAC,sBAAsB;IACvC,gBAAgB,CAAC,eAAe;CACjC,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CACzC,mBAAsC,EACtC,OAA4C;IAE5C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAC7C,OAAO,sBAAsB,CAAC,MAAM,CAClC,CAAC,UAAU,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,OAAO,EAAE,CAAC,UAAU,CAAC,KAAK,SAAS,CAC/E,CAAC;AACJ,CAAC","sourcesContent":["import { z } from \"zod\";\n\nimport { EngineCapability } from \"../../external-providers/engine-capabilities.shared.schemas\";\n\n/**\n * **Whether an AI use DECIDES something about a person, and who reviews it if so.**\n *\n * ## What the capability already says, and what it cannot\n *\n * `AI_LLM`, `AI_EMBEDDINGS`, `AI_DOCUMENT_EXTRACTION` and `AI_CODING_AGENT` establish that AI is in use\n * and for what FUNCTION. They cannot establish the two things that carry legal weight (issue #92):\n * whether any of it produces a decision with a legal or similarly significant effect on a person, and\n * whether a human reviews such a decision.\n *\n * Neither is inferable from a capability being enabled — the same `AI_LLM` backs a summarisation\n * feature that decides nothing and a screening feature that decides a great deal.\n *\n * ## Why silence here is worse than silence elsewhere\n *\n * Automated decision-making with significant effects attracts specific obligations: information about\n * the logic involved, and a right to obtain human intervention. A notice that describes AI use and says\n * nothing about consequence does not read as \"unknown\" — it reads as \"nothing significant happens\n * here\", which **silently claims the exemption**. That is why the posture is declared rather than\n * defaulted, and why an undeclared capability is reported as undeclared rather than assumed harmless.\n */\nexport enum AiDecisionConsequence {\n  /**\n   * The AI produces no decision about a person — it summarises, drafts, classifies content, or assists\n   * a task whose outcome affects nobody's rights.\n   *\n   * A real and common answer, and the one that must be DECLARED rather than assumed: it is exactly the\n   * claim a silent notice makes for free.\n   */\n  NO_DECISION = \"NO_DECISION\",\n  /**\n   * The AI informs a decision a HUMAN takes. The human is the decision-maker and can disregard it.\n   *\n   * Distinct from {@link NO_DECISION} because a person is affected, and distinct from\n   * {@link DECIDES_AUTONOMOUSLY} because the obligation attaches to solely-automated decisions. Where\n   * the human merely rubber-stamps, this is the wrong answer — the review must be capable of changing\n   * the outcome.\n   */\n  ASSISTS_HUMAN_DECISION = \"ASSISTS_HUMAN_DECISION\",\n  /** The AI's output IS the decision, with no human able to change it before it takes effect. */\n  DECIDES_AUTONOMOUSLY = \"DECIDES_AUTONOMOUSLY\",\n}\n\n/** One AI capability's declared posture. */\nexport const AiUsePostureSchema = z\n  .strictObject({\n    consequence: z.enum(AiDecisionConsequence),\n    /**\n     * What the AI is used FOR, in the operator's words.\n     *\n     * Required, and it is what makes the posture checkable: \"summarising a contact's interaction\n     * history\" and \"scoring a lead's creditworthiness\" are the same capability and different postures,\n     * so a consequence with no stated use cannot be reviewed by anyone.\n     */\n    purpose: z.string().trim().min(1),\n    /**\n     * How a person obtains human intervention — REQUIRED unless the posture is\n     * {@link AiDecisionConsequence.NO_DECISION}.\n     *\n     * The pairing is enforced below rather than left to a reviewer: an application declaring that AI\n     * decides something about a person, and saying nothing about review, has described the obligation\n     * without answering it.\n     */\n    humanReviewArrangement: z.string().trim().min(1).nullable(),\n  })\n  .superRefine((posture, context) => {\n    if (posture.consequence === AiDecisionConsequence.NO_DECISION) {\n      if (posture.humanReviewArrangement !== null) {\n        context.addIssue({\n          code: \"custom\",\n          path: [\"humanReviewArrangement\"],\n          message: \"a use that decides nothing has no human-review arrangement to describe\",\n        });\n      }\n      return;\n    }\n    if (posture.humanReviewArrangement === null) {\n      context.addIssue({\n        code: \"custom\",\n        path: [\"humanReviewArrangement\"],\n        message: `a ${posture.consequence} use affects a person, so it must say how human intervention is obtained`,\n      });\n    }\n  });\nexport type AiUsePosture = z.infer<typeof AiUsePostureSchema>;\n\n/**\n * The application's declared AI postures, keyed by the capability they describe.\n *\n * Keyed by CAPABILITY rather than by feature, deliberately. The issue suggested \"an AI use\", and a\n * feature-level posture is more precise — and it is a granularity nobody maintains, the same trade\n * that settled the retention schedule and the processor register. A capability is the unit the\n * application already declares, there are at most four, and an operator whose single `AI_LLM` capability\n * backs two features with different consequences declares the STRONGER one, which is the safe direction.\n */\nexport const ApplicationAiUsePostureSchema = z.partialRecord(z.enum(EngineCapability), AiUsePostureSchema);\nexport type ApplicationAiUsePosture = z.infer<typeof ApplicationAiUsePostureSchema>;\n\n/**\n * The AI capabilities a document must ask about.\n *\n * Named here rather than derived from a prefix: `AI_` is a spelling, and a capability added tomorrow\n * whose name happens to start with it would silently join the set — while one that processes personal\n * data under a different name would silently stay out.\n */\nexport const AI_ENGINE_CAPABILITIES: readonly EngineCapability[] = Object.freeze([\n  EngineCapability.AI_LLM,\n  EngineCapability.AI_EMBEDDINGS,\n  EngineCapability.AI_DOCUMENT_EXTRACTION,\n  EngineCapability.AI_CODING_AGENT,\n]);\n\n/**\n * Enabled AI capabilities with no declared posture — what a document must report as outstanding.\n *\n * Takes the ENABLED set as an argument: a capability the application has not enabled raises no\n * question, and reporting it would fill a notice with AI the application does not use.\n */\nexport function undeclaredAiUseCapabilities(\n  enabledCapabilities: readonly string[],\n  posture: ApplicationAiUsePosture | undefined,\n): readonly EngineCapability[] {\n  const enabled = new Set(enabledCapabilities);\n  return AI_ENGINE_CAPABILITIES.filter(\n    (capability) => enabled.has(capability) && posture?.[capability] === undefined,\n  );\n}\n"]}
+{"version":3,"file":"ai-use-posture.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/compliance/privacy/ai-use-posture.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,qCAAqC,EAAE,MAAM,2DAA2D,CAAC;AAClH,OAAO,EAAE,gBAAgB,EAAE,MAAM,6DAA6D,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAN,IAAY,qBAoBX;AApBD,WAAY,qBAAqB;IAC/B;;;;;;OAMG;IACH,oDAA2B,CAAA;IAC3B;;;;;;;OAOG;IACH,0EAAiD,CAAA;IACjD,+FAA+F;IAC/F,sEAA6C,CAAA;AAC/C,CAAC,EApBW,qBAAqB,KAArB,qBAAqB,QAoBhC;AAED,4CAA4C;AAC5C,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC;KAChC,YAAY,CAAC;IACZ,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC;IAC1C;;;;;;OAMG;IACH,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC;;;;;;;OAOG;IACH,sBAAsB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CAC5D,CAAC;KACD,WAAW,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE;IAChC,IAAI,OAAO,CAAC,WAAW,KAAK,qBAAqB,CAAC,WAAW,EAAE,CAAC;QAC9D,IAAI,OAAO,CAAC,sBAAsB,KAAK,IAAI,EAAE,CAAC;YAC5C,OAAO,CAAC,QAAQ,CAAC;gBACf,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,CAAC,wBAAwB,CAAC;gBAChC,OAAO,EAAE,wEAAwE;aAClF,CAAC,CAAC;QACL,CAAC;QACD,OAAO;IACT,CAAC;IACD,IAAI,OAAO,CAAC,sBAAsB,KAAK,IAAI,EAAE,CAAC;QAC5C,OAAO,CAAC,QAAQ,CAAC;YACf,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,wBAAwB,CAAC;YAChC,OAAO,EAAE,KAAK,OAAO,CAAC,WAAW,0EAA0E;SAC5G,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC,CAAC;AAGL;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,EAAE,kBAAkB,CAAC,CAAC;AAG3G;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAgC,MAAM,CAAC,MAAM,CAAC;IAC/E,gBAAgB,CAAC,MAAM;IACvB,gBAAgB,CAAC,aAAa;IAC9B,gBAAgB,CAAC,sBAAsB;IACvC,gBAAgB,CAAC,eAAe;IAChC;;;;;;;;;;;;;;OAcG;IACH,gBAAgB,CAAC,mBAAmB;CACrC,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,gDAAgD,GAAgC,MAAM,CAAC,MAAM,CACxG,sBAAsB,CAAC,MAAM,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,qCAAqC,CAAC,UAAU,CAAC,CAAC,CACjG,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CACzC,mBAAsC,EACtC,OAA4C;IAE5C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAC7C,OAAO,gDAAgD,CAAC,MAAM,CAC5D,CAAC,UAAU,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,OAAO,EAAE,CAAC,UAAU,CAAC,KAAK,SAAS,CAC/E,CAAC;AACJ,CAAC","sourcesContent":["import { z } from \"zod\";\n\nimport { engineCapabilityReachesRuntimeService } from '../../external-providers/engine-capability-surface.shared';\nimport { EngineCapability } from \"../../external-providers/engine-capabilities.shared.schemas\";\n\n/**\n * **Whether an AI use DECIDES something about a person, and who reviews it if so.**\n *\n * ## What the capability already says, and what it cannot\n *\n * `AI_LLM`, `AI_EMBEDDINGS`, `AI_DOCUMENT_EXTRACTION` and `AI_CODING_AGENT` establish that AI is in use\n * and for what FUNCTION. They cannot establish the two things that carry legal weight (issue #92):\n * whether any of it produces a decision with a legal or similarly significant effect on a person, and\n * whether a human reviews such a decision.\n *\n * Neither is inferable from a capability being enabled — the same `AI_LLM` backs a summarisation\n * feature that decides nothing and a screening feature that decides a great deal.\n *\n * ## Why silence here is worse than silence elsewhere\n *\n * Automated decision-making with significant effects attracts specific obligations: information about\n * the logic involved, and a right to obtain human intervention. A notice that describes AI use and says\n * nothing about consequence does not read as \"unknown\" — it reads as \"nothing significant happens\n * here\", which **silently claims the exemption**. That is why the posture is declared rather than\n * defaulted, and why an undeclared capability is reported as undeclared rather than assumed harmless.\n */\nexport enum AiDecisionConsequence {\n  /**\n   * The AI produces no decision about a person — it summarises, drafts, classifies content, or assists\n   * a task whose outcome affects nobody's rights.\n   *\n   * A real and common answer, and the one that must be DECLARED rather than assumed: it is exactly the\n   * claim a silent notice makes for free.\n   */\n  NO_DECISION = \"NO_DECISION\",\n  /**\n   * The AI informs a decision a HUMAN takes. The human is the decision-maker and can disregard it.\n   *\n   * Distinct from {@link NO_DECISION} because a person is affected, and distinct from\n   * {@link DECIDES_AUTONOMOUSLY} because the obligation attaches to solely-automated decisions. Where\n   * the human merely rubber-stamps, this is the wrong answer — the review must be capable of changing\n   * the outcome.\n   */\n  ASSISTS_HUMAN_DECISION = \"ASSISTS_HUMAN_DECISION\",\n  /** The AI's output IS the decision, with no human able to change it before it takes effect. */\n  DECIDES_AUTONOMOUSLY = \"DECIDES_AUTONOMOUSLY\",\n}\n\n/** One AI capability's declared posture. */\nexport const AiUsePostureSchema = z\n  .strictObject({\n    consequence: z.enum(AiDecisionConsequence),\n    /**\n     * What the AI is used FOR, in the operator's words.\n     *\n     * Required, and it is what makes the posture checkable: \"summarising a contact's interaction\n     * history\" and \"scoring a lead's creditworthiness\" are the same capability and different postures,\n     * so a consequence with no stated use cannot be reviewed by anyone.\n     */\n    purpose: z.string().trim().min(1),\n    /**\n     * How a person obtains human intervention — REQUIRED unless the posture is\n     * {@link AiDecisionConsequence.NO_DECISION}.\n     *\n     * The pairing is enforced below rather than left to a reviewer: an application declaring that AI\n     * decides something about a person, and saying nothing about review, has described the obligation\n     * without answering it.\n     */\n    humanReviewArrangement: z.string().trim().min(1).nullable(),\n  })\n  .superRefine((posture, context) => {\n    if (posture.consequence === AiDecisionConsequence.NO_DECISION) {\n      if (posture.humanReviewArrangement !== null) {\n        context.addIssue({\n          code: \"custom\",\n          path: [\"humanReviewArrangement\"],\n          message: \"a use that decides nothing has no human-review arrangement to describe\",\n        });\n      }\n      return;\n    }\n    if (posture.humanReviewArrangement === null) {\n      context.addIssue({\n        code: \"custom\",\n        path: [\"humanReviewArrangement\"],\n        message: `a ${posture.consequence} use affects a person, so it must say how human intervention is obtained`,\n      });\n    }\n  });\nexport type AiUsePosture = z.infer<typeof AiUsePostureSchema>;\n\n/**\n * The application's declared AI postures, keyed by the capability they describe.\n *\n * Keyed by CAPABILITY rather than by feature, deliberately. The issue suggested \"an AI use\", and a\n * feature-level posture is more precise — and it is a granularity nobody maintains, the same trade\n * that settled the retention schedule and the processor register. A capability is the unit the\n * application already declares, there are at most four, and an operator whose single `AI_LLM` capability\n * backs two features with different consequences declares the STRONGER one, which is the safe direction.\n */\nexport const ApplicationAiUsePostureSchema = z.partialRecord(z.enum(EngineCapability), AiUsePostureSchema);\nexport type ApplicationAiUsePosture = z.infer<typeof ApplicationAiUsePostureSchema>;\n\n/**\n * The AI capabilities a document must ask about.\n *\n * Named here rather than derived from a prefix: `AI_` is a spelling, and a capability added tomorrow\n * whose name happens to start with it would silently join the set — while one that processes personal\n * data under a different name would silently stay out.\n */\nexport const AI_ENGINE_CAPABILITIES: readonly EngineCapability[] = Object.freeze([\n  EngineCapability.AI_LLM,\n  EngineCapability.AI_EMBEDDINGS,\n  EngineCapability.AI_DOCUMENT_EXTRACTION,\n  EngineCapability.AI_CODING_AGENT,\n  /*\n   * ADDED 2026-09-12, and its absence was a hole rather than a judgement.\n   *\n   * Generating an image from a person's prompt, or from their content, is AI processing by any\n   * reading a notice has to survive — and because this list is what a document ASKS about, omitting\n   * it meant an application offering image generation to its users was asked NOTHING about AI. The\n   * omission was silent in the direction that matters: the notice reads complete.\n   *\n   * It was noticed while adding the surface axis and deliberately not slipped into that change,\n   * because widening this vocabulary changes what an application must declare. Measured before\n   * landing: Wonder Todos enables the capability and its only provider offering it sits in the\n   * COMPANION scope (the brand/logo generator), so the scope resolution keeps it outside the\n   * contracted service and its notice is unchanged. An application that binds an image provider to\n   * a RUNTIME scope is now asked for a posture, which is the whole point.\n   */\n  EngineCapability.AI_IMAGE_GENERATION,\n]);\n\n/**\n * The AI capabilities a document about the CONTRACTED SERVICE must ask about.\n *\n * The set above, minus the capabilities that never run while the application serves a user. This is\n * the set a privacy notice, a record of processing and an Article 22 automated-decision statement\n * are about, and the distinction is not cosmetic: `AI_CODING_AGENT` is a build-time tool that writes\n * the application's SOURCE. It decides nothing about a data subject and processes none of their\n * data, so asking an operator to declare its \"posture\" toward people, or listing it as OUTSTANDING\n * in a notice, invents an AI question the service does not raise.\n *\n * That is not hypothetical. Wonder CRM enables `AI_CODING_AGENT` and no other AI capability. Under\n * the unfiltered set the drafter is pushed into the per-capability AI branch — the branch that asks\n * \"whether it DECIDES something about a person\" — for an application whose contracted service\n * performs no AI at all, and whose own declared fact says exactly that.\n *\n * DERIVED rather than listed, and total over the set above, so an AI capability added tomorrow lands\n * on the right side of this line by its DECLARED SURFACE rather than by anyone remembering to add it\n * here. The surface map is itself exhaustive over `EngineCapability`, so there is no default to fall\n * through.\n */\nexport const AI_ENGINE_CAPABILITIES_IN_THE_CONTRACTED_SERVICE: readonly EngineCapability[] = Object.freeze(\n  AI_ENGINE_CAPABILITIES.filter((capability) => engineCapabilityReachesRuntimeService(capability)),\n);\n\n/**\n * Enabled AI capabilities with no declared posture — what a document must report as outstanding.\n *\n * Takes the ENABLED set as an argument: a capability the application has not enabled raises no\n * question, and reporting it would fill a notice with AI the application does not use.\n */\nexport function undeclaredAiUseCapabilities(\n  enabledCapabilities: readonly string[],\n  posture: ApplicationAiUsePosture | undefined,\n): readonly EngineCapability[] {\n  const enabled = new Set(enabledCapabilities);\n  return AI_ENGINE_CAPABILITIES_IN_THE_CONTRACTED_SERVICE.filter(\n    (capability) => enabled.has(capability) && posture?.[capability] === undefined,\n  );\n}\n"]}

package/dist/esm/compliance/privacy/capability-consent-purposes.shared.utils.d.ts

@@ -0,0 +1,33 @@
+import { ConsentPurpose } from './consent-purposes.shared';
+import type { ResourceOperationConsentGateDeclaration } from './consent-gate-vocabulary.shared.schemas';
+/**
+ * The narrow slice of a resolved resource configuration this derivation reads: every operation, each
+ * possibly carrying a `consentGate`. Structural, so `ResourcesRegistry['resourceConfigurations']`
+ * values satisfy it without a cast at the call site — the operation record is a discriminated union
+ * with no shared `consentGate` member (mirroring how `assertServiceConsentRequirementMet` reads the
+ * same field off `executionContext.operation`), so each element is narrowed the same way here.
+ */
+export interface CapabilityConsentGateSubject {
+    readonly operations: readonly {
+        readonly consentGate?: ResourceOperationConsentGateDeclaration;
+    }[];
+}
+/**
+ * Every `ConsentPurpose` declared by at least one operation across every resource in the registry
+ * (#1462, following #1258 Step 3).
+ *
+ * Total over the REGISTRY, not over one application's own resources: an engine capability could
+ * declare a `consentGate` as validly as an app-authored one, and the person facing a refusal from
+ * either needs the same PROMPT surface to grant it from — there is no reader this derivation exists
+ * to protect from engine noise the way `collectApplicationResourcesWithNoPersonalDataDeclaration`
+ * protects a startup log from ~85 engine resources that never answer a question nobody asked them.
+ * This is a SET, not a per-resource report: only the union of what was declared is useful downstream.
+ *
+ * Pure and import-light on purpose, mirroring `applicationAskedConsentPurposes` in the same
+ * directory: the one call site that matters (`ResourcesRegistryBackendService.initialize()`) hands
+ * this the live registry and the result travels onward as plain data
+ * (`compliance.capabilityDeclaredConsentPurposes`), never as a reason to import registry types where
+ * they do not otherwise belong.
+ */
+export declare function collectCapabilityDeclaredConsentPurposes(resourceConfigurations: Readonly<Record<string, CapabilityConsentGateSubject>>): ConsentPurpose[];
+//# sourceMappingURL=capability-consent-purposes.shared.utils.d.ts.map

package/dist/esm/compliance/privacy/capability-consent-purposes.shared.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-consent-purposes.shared.utils.d.ts","sourceRoot":"","sources":["../../../../../src/compliance/privacy/capability-consent-purposes.shared.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC7E,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,0CAA0C,CAAC;AAExG;;;;;;GAMG;AACH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,UAAU,EAAE,SAAS;QAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,uCAAuC,CAAA;KAAE,EAAE,CAAC;CACpG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wCAAwC,CACtD,sBAAsB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,4BAA4B,CAAC,CAAC,GAC7E,cAAc,EAAE,CASlB"}

package/dist/esm/compliance/privacy/capability-consent-purposes.shared.utils.js

@@ -0,0 +1,30 @@
+import { CONSENT_PURPOSES } from './consent-purposes.shared.js';
+/**
+ * Every `ConsentPurpose` declared by at least one operation across every resource in the registry
+ * (#1462, following #1258 Step 3).
+ *
+ * Total over the REGISTRY, not over one application's own resources: an engine capability could
+ * declare a `consentGate` as validly as an app-authored one, and the person facing a refusal from
+ * either needs the same PROMPT surface to grant it from — there is no reader this derivation exists
+ * to protect from engine noise the way `collectApplicationResourcesWithNoPersonalDataDeclaration`
+ * protects a startup log from ~85 engine resources that never answer a question nobody asked them.
+ * This is a SET, not a per-resource report: only the union of what was declared is useful downstream.
+ *
+ * Pure and import-light on purpose, mirroring `applicationAskedConsentPurposes` in the same
+ * directory: the one call site that matters (`ResourcesRegistryBackendService.initialize()`) hands
+ * this the live registry and the result travels onward as plain data
+ * (`compliance.capabilityDeclaredConsentPurposes`), never as a reason to import registry types where
+ * they do not otherwise belong.
+ */
+export function collectCapabilityDeclaredConsentPurposes(resourceConfigurations) {
+    const declared = new Set();
+    for (const configuration of Object.values(resourceConfigurations)) {
+        for (const operation of configuration.operations) {
+            const purpose = operation.consentGate?.purpose;
+            if (purpose !== undefined)
+                declared.add(purpose);
+        }
+    }
+    return CONSENT_PURPOSES.filter((purpose) => declared.has(purpose));
+}
+//# sourceMappingURL=capability-consent-purposes.shared.utils.js.map

package/dist/esm/compliance/privacy/capability-consent-purposes.shared.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-consent-purposes.shared.utils.js","sourceRoot":"","sources":["../../../../../src/compliance/privacy/capability-consent-purposes.shared.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAkB,MAAM,2BAA2B,CAAC;AAc7E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,wCAAwC,CACtD,sBAA8E;IAE9E,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,KAAK,MAAM,aAAa,IAAI,MAAM,CAAC,MAAM,CAAC,sBAAsB,CAAC,EAAE,CAAC;QAClE,KAAK,MAAM,SAAS,IAAI,aAAa,CAAC,UAAU,EAAE,CAAC;YACjD,MAAM,OAAO,GAAG,SAAS,CAAC,WAAW,EAAE,OAAO,CAAC;YAC/C,IAAI,OAAO,KAAK,SAAS;gBAAE,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IACD,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;AACrE,CAAC","sourcesContent":["import { CONSENT_PURPOSES, ConsentPurpose } from './consent-purposes.shared';\nimport type { ResourceOperationConsentGateDeclaration } from './consent-gate-vocabulary.shared.schemas';\n\n/**\n * The narrow slice of a resolved resource configuration this derivation reads: every operation, each\n * possibly carrying a `consentGate`. Structural, so `ResourcesRegistry['resourceConfigurations']`\n * values satisfy it without a cast at the call site — the operation record is a discriminated union\n * with no shared `consentGate` member (mirroring how `assertServiceConsentRequirementMet` reads the\n * same field off `executionContext.operation`), so each element is narrowed the same way here.\n */\nexport interface CapabilityConsentGateSubject {\n  readonly operations: readonly { readonly consentGate?: ResourceOperationConsentGateDeclaration }[];\n}\n\n/**\n * Every `ConsentPurpose` declared by at least one operation across every resource in the registry\n * (#1462, following #1258 Step 3).\n *\n * Total over the REGISTRY, not over one application's own resources: an engine capability could\n * declare a `consentGate` as validly as an app-authored one, and the person facing a refusal from\n * either needs the same PROMPT surface to grant it from — there is no reader this derivation exists\n * to protect from engine noise the way `collectApplicationResourcesWithNoPersonalDataDeclaration`\n * protects a startup log from ~85 engine resources that never answer a question nobody asked them.\n * This is a SET, not a per-resource report: only the union of what was declared is useful downstream.\n *\n * Pure and import-light on purpose, mirroring `applicationAskedConsentPurposes` in the same\n * directory: the one call site that matters (`ResourcesRegistryBackendService.initialize()`) hands\n * this the live registry and the result travels onward as plain data\n * (`compliance.capabilityDeclaredConsentPurposes`), never as a reason to import registry types where\n * they do not otherwise belong.\n */\nexport function collectCapabilityDeclaredConsentPurposes(\n  resourceConfigurations: Readonly<Record<string, CapabilityConsentGateSubject>>,\n): ConsentPurpose[] {\n  const declared = new Set<ConsentPurpose>();\n  for (const configuration of Object.values(resourceConfigurations)) {\n    for (const operation of configuration.operations) {\n      const purpose = operation.consentGate?.purpose;\n      if (purpose !== undefined) declared.add(purpose);\n    }\n  }\n  return CONSENT_PURPOSES.filter((purpose) => declared.has(purpose));\n}\n"]}

package/dist/esm/compliance/privacy/client-storage.shared.schemas.d.ts

@@ -8,8 +8,8 @@ import { z } from "zod";
  * persists, and which are strictly necessary versus consent-gated. Nothing in the framework declared
  * any of it (issue #91).
  *
- * The consent POSTURE was already real and enforced — `DataProcessingConsent` plus the capability
- * flags make `ANALYTICS` a boundary the runtime honours rather than a stated intention, which is a
+ * The consent POSTURE was already real and enforced — `consentedPurposes` plus the capability
+ * flags make `ConsentPurpose.ANALYTICS` a boundary the runtime honours rather than a stated intention, which is a
  * stronger position than most cookie notices, which describe consent they do not enforce. What could
  * not be produced was the table.
  *
@@ -77,9 +77,10 @@ export type ClientStorageEntry = z.infer<typeof ClientStorageEntrySchema>;
 /**
  * The client storage the FRAMEWORK sets, which no application authored and every application inherits.
  *
- * Both are `STRICTLY_NECESSARY`: they carry session state for a service the visitor asked for, and
- * neither measures behaviour. Both are `httpOnly`, so no script — the application's or anyone else's —
- * can read them.
+ * All are `STRICTLY_NECESSARY`. The two cookies carry session state for a service the visitor asked for
+ * and are `httpOnly`, so no script can read them. The website consent record (#534) is web storage and
+ * is necessary for a different reason: remembering a refusal is what makes the refusal hold, and a
+ * consent record that itself needed consent could never be kept.
  *
  * Their lifetimes are the application's to configure, so they are described by their SOURCE. Their
  * `setWhen` is stated because neither is unconditional: an application whose visitors never sign in

package/dist/esm/compliance/privacy/client-storage.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client-storage.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/compliance/privacy/client-storage.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,sHAAsH;AACtH,oBAAY,sBAAsB;IAChC,MAAM,WAAW;IACjB,aAAa,kBAAkB;IAC/B,eAAe,oBAAoB;CACpC;AAED;;;;;;GAMG;AACH,oBAAY,sBAAsB;IAChC,sGAAsG;IACtG,kBAAkB,uBAAuB;IACzC,qGAAqG;IACrG,aAAa,kBAAkB;CAChC;AAED,qEAAqE;AACrE,eAAO,MAAM,wBAAwB;IACnC,kGAAkG;;;IAGlG,mGAAmG;;;IAGnG;;;;;;;OAOG;;IAEH;;;;;;OAMG;;kBAEH,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,kBAAkB,EAiBrE,CAAC;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,uCAAuC;IAnElD,kGAAkG;;;IAGlG,mGAAmG;;;IAGnG;;;;;;;OAOG;;IAEH;;;;;;OAMG;;oBAiDJ,CAAC;AACF,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uCAAuC,CAAC,CAAC;AAExG;;;;;;GAMG;AACH,wBAAgB,kCAAkC,CAChD,mBAAmB,EAAE,SAAS,MAAM,EAAE,EACtC,SAAS,EAAE,iCAAiC,GAAG,SAAS,GACvD,SAAS,MAAM,EAAE,CAEnB"}
+{"version":3,"file":"client-storage.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/compliance/privacy/client-storage.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,sHAAsH;AACtH,oBAAY,sBAAsB;IAChC,MAAM,WAAW;IACjB,aAAa,kBAAkB;IAC/B,eAAe,oBAAoB;CACpC;AAED;;;;;;GAMG;AACH,oBAAY,sBAAsB;IAChC,sGAAsG;IACtG,kBAAkB,uBAAuB;IACzC,qGAAqG;IACrG,aAAa,kBAAkB;CAChC;AAED,qEAAqE;AACrE,eAAO,MAAM,wBAAwB;IACnC,kGAAkG;;;IAGlG,mGAAmG;;;IAGnG;;;;;;;OAOG;;IAEH;;;;;;OAMG;;kBAEH,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,kBAAkB,EAyBrE,CAAC;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,uCAAuC;IA5ElD,kGAAkG;;;IAGlG,mGAAmG;;;IAGnG;;;;;;;OAOG;;IAEH;;;;;;OAMG;;oBA0DJ,CAAC;AACF,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uCAAuC,CAAC,CAAC;AAExG;;;;;;GAMG;AACH,wBAAgB,kCAAkC,CAChD,mBAAmB,EAAE,SAAS,MAAM,EAAE,EACtC,SAAS,EAAE,iCAAiC,GAAG,SAAS,GACvD,SAAS,MAAM,EAAE,CAEnB"}

package/dist/esm/compliance/privacy/client-storage.shared.schemas.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { WEBSITE_VISITOR_CONSENT_STORAGE_KEY } from "./consent-purposes.shared.js";
 /**
  * **What the application stores in a visitor's browser, and what gates it.**
  *
@@ -8,8 +9,8 @@ import { z } from "zod";
  * persists, and which are strictly necessary versus consent-gated. Nothing in the framework declared
  * any of it (issue #91).
  *
- * The consent POSTURE was already real and enforced — `DataProcessingConsent` plus the capability
- * flags make `ANALYTICS` a boundary the runtime honours rather than a stated intention, which is a
+ * The consent POSTURE was already real and enforced — `consentedPurposes` plus the capability
+ * flags make `ConsentPurpose.ANALYTICS` a boundary the runtime honours rather than a stated intention, which is a
  * stronger position than most cookie notices, which describe consent they do not enforce. What could
  * not be produced was the table.
  *
@@ -78,9 +79,10 @@ export const ClientStorageEntrySchema = z.strictObject({
 /**
  * The client storage the FRAMEWORK sets, which no application authored and every application inherits.
  *
- * Both are `STRICTLY_NECESSARY`: they carry session state for a service the visitor asked for, and
- * neither measures behaviour. Both are `httpOnly`, so no script — the application's or anyone else's —
- * can read them.
+ * All are `STRICTLY_NECESSARY`. The two cookies carry session state for a service the visitor asked for
+ * and are `httpOnly`, so no script can read them. The website consent record (#534) is web storage and
+ * is necessary for a different reason: remembering a refusal is what makes the refusal hold, and a
+ * consent record that itself needed consent could never be kept.
  *
  * Their lifetimes are the application's to configure, so they are described by their SOURCE. Their
  * `setWhen` is stated because neither is unconditional: an application whose visitors never sign in
@@ -104,6 +106,14 @@ export const ENGINE_CLIENT_STORAGE_ENTRIES = Object.freeze([
         lifetime: "The application's configured anonymous-session lifetime.",
         setWhen: "Set only where the application admits anonymous visitors.",
     }),
+    Object.freeze({
+        name: WEBSITE_VISITOR_CONSENT_STORAGE_KEY,
+        mechanism: ClientStorageMechanism.LOCAL_STORAGE,
+        purpose: "Remembers which optional purposes a website visitor agreed to, so they are not asked on every page and nothing optional starts without it.",
+        necessity: ClientStorageNecessity.STRICTLY_NECESSARY,
+        lifetime: "Until the visitor changes their choice or clears the site's storage.",
+        setWhen: "Set on the marketing website when a visitor makes a consent choice, and only where the site runs a consent-based provider.",
+    }),
 ]);
 /**
  * The application's own client storage, per FRONTEND SURFACE.

package/dist/esm/compliance/privacy/client-storage.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"client-storage.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/compliance/privacy/client-storage.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,sHAAsH;AACtH,MAAM,CAAN,IAAY,sBAIX;AAJD,WAAY,sBAAsB;IAChC,2CAAiB,CAAA;IACjB,yDAA+B,CAAA;IAC/B,6DAAmC,CAAA;AACrC,CAAC,EAJW,sBAAsB,KAAtB,sBAAsB,QAIjC;AAED;;;;;;GAMG;AACH,MAAM,CAAN,IAAY,sBAKX;AALD,WAAY,sBAAsB;IAChC,sGAAsG;IACtG,mEAAyC,CAAA;IACzC,qGAAqG;IACrG,yDAA+B,CAAA;AACjC,CAAC,EALW,sBAAsB,KAAtB,sBAAsB,QAKjC;AAED,qEAAqE;AACrE,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,YAAY,CAAC;IACrD,kGAAkG;IAClG,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC;IACzC,mGAAmG;IACnG,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC;IACzC;;;;;;;OAOG;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAClC;;;;;;OAMG;IACH,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CAC7C,CAAC,CAAC;AAGH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAkC,MAAM,CAAC,MAAM,CAAC;IACxF,MAAM,CAAC,MAAM,CAAC;QACZ,IAAI,EAAE,iBAAiB;QACvB,SAAS,EAAE,sBAAsB,CAAC,MAAM;QACxC,OAAO,EAAE,6FAA6F;QACtG,SAAS,EAAE,sBAAsB,CAAC,kBAAkB;QACpD,QAAQ,EAAE,oDAAoD;QAC9D,OAAO,EAAE,8DAA8D;KACxE,CAAC;IACF,MAAM,CAAC,MAAM,CAAC;QACZ,IAAI,EAAE,sBAAsB;QAC5B,SAAS,EAAE,sBAAsB,CAAC,MAAM;QACxC,OAAO,EAAE,uGAAuG;QAChH,SAAS,EAAE,sBAAsB,CAAC,kBAAkB;QACpD,QAAQ,EAAE,0DAA0D;QACpE,OAAO,EAAE,2DAA2D;KACrE,CAAC;CACH,CAAC,CAAC;AAEH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,uCAAuC,GAAG,CAAC,CAAC,MAAM,CAC7D,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EACxB,CAAC,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAClC,CAAC;AAGF;;;;;;GAMG;AACH,MAAM,UAAU,kCAAkC,CAChD,mBAAsC,EACtC,SAAwD;IAExD,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,SAAS,EAAE,CAAC,UAAU,CAAC,KAAK,SAAS,CAAC,CAAC;AAC3F,CAAC","sourcesContent":["import { z } from \"zod\";\n\n/**\n * **What the application stores in a visitor's browser, and what gates it.**\n *\n * ## What a cookie notice actually is\n *\n * An itemised table: which cookies and client-side storage keys are set, what each is for, how long it\n * persists, and which are strictly necessary versus consent-gated. Nothing in the framework declared\n * any of it (issue #91).\n *\n * The consent POSTURE was already real and enforced — `DataProcessingConsent` plus the capability\n * flags make `ANALYTICS` a boundary the runtime honours rather than a stated intention, which is a\n * stronger position than most cookie notices, which describe consent they do not enforce. What could\n * not be produced was the table.\n *\n * ## The engine sets cookies of its own, and that is why this has an ORIGIN split\n *\n * Every generated application sets at least one cookie it never declared, because the framework sets\n * it: {@link ENGINE_CLIENT_STORAGE_ENTRIES}. Asking only the application would produce a cookie table\n * that omits the session cookie — the same shape as the engine-versus-application finding in the\n * resource declarations, and the same remedy: report the two origins separately, and let the framework\n * answer for its own.\n *\n * ## Lifetimes the framework will not invent\n *\n * The engine's cookies take their `maxAge` from the application's session configuration, so the\n * framework declares the NAME, the purpose and the necessity, and describes the lifetime by where it\n * comes from. A fixed number here would be a published commitment nothing enforces — the same rule\n * that governs the retention schedule.\n */\n\n/** Where a value is stored in the browser. Cookies and web storage carry different expectations and different law. */\nexport enum ClientStorageMechanism {\n  COOKIE = \"COOKIE\",\n  LOCAL_STORAGE = \"LOCAL_STORAGE\",\n  SESSION_STORAGE = \"SESSION_STORAGE\",\n}\n\n/**\n * Whether the entry may be set before consent.\n *\n * The distinction a cookie banner exists to implement, and the one a notice is read for. Two values on\n * purpose: an entry is either required for a service the visitor asked for, or it is not and needs\n * consent. A middle category would be a place to put everything nobody wanted to decide.\n */\nexport enum ClientStorageNecessity {\n  /** Required to deliver a service the visitor explicitly requested — signing in, keeping a session. */\n  STRICTLY_NECESSARY = \"STRICTLY_NECESSARY\",\n  /** Set only after the visitor consents. Analytics, personalisation, anything measuring behaviour. */\n  CONSENT_GATED = \"CONSENT_GATED\",\n}\n\n/** One cookie or storage key, as a notice's table would print it. */\nexport const ClientStorageEntrySchema = z.strictObject({\n  /** The exact key or cookie name a visitor would see in their browser. Not a description of it. */\n  name: z.string().trim().min(1),\n  mechanism: z.enum(ClientStorageMechanism),\n  /** What it is FOR, in a sentence a visitor can read. \"Session management\", not \"auth token v2\". */\n  purpose: z.string().trim().min(1),\n  necessity: z.enum(ClientStorageNecessity),\n  /**\n   * How long it persists, as a notice would state it — \"the browser session\", \"30 days\", or where the\n   * value comes from when the application configures it.\n   *\n   * Free text rather than a duration, because the honest answer is often a reference rather than a\n   * number, and a number the application does not actually enforce is worse than a description of the\n   * mechanism that does.\n   */\n  lifetime: z.string().trim().min(1),\n  /**\n   * WHEN it is set, for an entry that is not set on every visit — `null` when it always is.\n   *\n   * Required-and-nullable rather than optional: \"set on every visit\" and \"nobody recorded when\" are\n   * different answers, and a cookie table that implies the first while meaning the second overstates\n   * what a visitor's browser holds.\n   */\n  setWhen: z.string().trim().min(1).nullable(),\n});\nexport type ClientStorageEntry = z.infer<typeof ClientStorageEntrySchema>;\n\n/**\n * The client storage the FRAMEWORK sets, which no application authored and every application inherits.\n *\n * Both are `STRICTLY_NECESSARY`: they carry session state for a service the visitor asked for, and\n * neither measures behaviour. Both are `httpOnly`, so no script — the application's or anyone else's —\n * can read them.\n *\n * Their lifetimes are the application's to configure, so they are described by their SOURCE. Their\n * `setWhen` is stated because neither is unconditional: an application whose visitors never sign in\n * sets no refresh cookie, and one that does not use anonymous sessions sets no anonymous cookie. A\n * table claiming both are always present would overstate what a visitor's browser holds.\n */\nexport const ENGINE_CLIENT_STORAGE_ENTRIES: readonly ClientStorageEntry[] = Object.freeze([\n  Object.freeze({\n    name: \"__wildo_refresh\",\n    mechanism: ClientStorageMechanism.COOKIE,\n    purpose: \"Keeps a signed-in session alive so a visitor is not asked to authenticate on every request.\",\n    necessity: ClientStorageNecessity.STRICTLY_NECESSARY,\n    lifetime: \"The application's configured refresh-token expiry.\",\n    setWhen: \"Set when a visitor signs in, and cleared when they sign out.\",\n  }),\n  Object.freeze({\n    name: \"__wildo_anon_session\",\n    mechanism: ClientStorageMechanism.COOKIE,\n    purpose: \"Gives a visitor who has not signed in a continuous session, so work in progress survives a page load.\",\n    necessity: ClientStorageNecessity.STRICTLY_NECESSARY,\n    lifetime: \"The application's configured anonymous-session lifetime.\",\n    setWhen: \"Set only where the application admits anonymous visitors.\",\n  }),\n]);\n\n/**\n * The application's own client storage, per FRONTEND SURFACE.\n *\n * Per surface rather than application-wide, and that is the issue's own point: a public marketing site\n * and the authenticated application set different things, and one merged list would be wrong for both —\n * it would show a visitor to the marketing site cookies only the app sets.\n *\n * Partial: a surface with no entry has not been inventoried, which the derivation reports. An empty\n * ARRAY is the different, positive answer — this surface sets nothing of its own beyond the engine's.\n */\nexport const ApplicationClientStorageInventorySchema = z.record(\n  z.string().trim().min(1),\n  z.array(ClientStorageEntrySchema),\n);\nexport type ApplicationClientStorageInventory = z.infer<typeof ApplicationClientStorageInventorySchema>;\n\n/**\n * Frontend surfaces with no inventory at all — the gap, per surface.\n *\n * Takes the surface list as an argument so the same function serves the companion (which reads the\n * declared services) and a test. Order follows the surfaces given, so the answer reads like the\n * application it describes.\n */\nexport function uninventoriedClientStorageSurfaces(\n  frontendSurfaceKeys: readonly string[],\n  inventory: ApplicationClientStorageInventory | undefined,\n): readonly string[] {\n  return frontendSurfaceKeys.filter((surfaceKey) => inventory?.[surfaceKey] === undefined);\n}\n"]}
+{"version":3,"file":"client-storage.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/compliance/privacy/client-storage.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,mCAAmC,EAAE,MAAM,2BAA2B,CAAC;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,sHAAsH;AACtH,MAAM,CAAN,IAAY,sBAIX;AAJD,WAAY,sBAAsB;IAChC,2CAAiB,CAAA;IACjB,yDAA+B,CAAA;IAC/B,6DAAmC,CAAA;AACrC,CAAC,EAJW,sBAAsB,KAAtB,sBAAsB,QAIjC;AAED;;;;;;GAMG;AACH,MAAM,CAAN,IAAY,sBAKX;AALD,WAAY,sBAAsB;IAChC,sGAAsG;IACtG,mEAAyC,CAAA;IACzC,qGAAqG;IACrG,yDAA+B,CAAA;AACjC,CAAC,EALW,sBAAsB,KAAtB,sBAAsB,QAKjC;AAED,qEAAqE;AACrE,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,YAAY,CAAC;IACrD,kGAAkG;IAClG,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC;IACzC,mGAAmG;IACnG,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC;IACzC;;;;;;;OAOG;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAClC;;;;;;OAMG;IACH,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CAC7C,CAAC,CAAC;AAGH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAkC,MAAM,CAAC,MAAM,CAAC;IACxF,MAAM,CAAC,MAAM,CAAC;QACZ,IAAI,EAAE,iBAAiB;QACvB,SAAS,EAAE,sBAAsB,CAAC,MAAM;QACxC,OAAO,EAAE,6FAA6F;QACtG,SAAS,EAAE,sBAAsB,CAAC,kBAAkB;QACpD,QAAQ,EAAE,oDAAoD;QAC9D,OAAO,EAAE,8DAA8D;KACxE,CAAC;IACF,MAAM,CAAC,MAAM,CAAC;QACZ,IAAI,EAAE,sBAAsB;QAC5B,SAAS,EAAE,sBAAsB,CAAC,MAAM;QACxC,OAAO,EAAE,uGAAuG;QAChH,SAAS,EAAE,sBAAsB,CAAC,kBAAkB;QACpD,QAAQ,EAAE,0DAA0D;QACpE,OAAO,EAAE,2DAA2D;KACrE,CAAC;IACF,MAAM,CAAC,MAAM,CAAC;QACZ,IAAI,EAAE,mCAAmC;QACzC,SAAS,EAAE,sBAAsB,CAAC,aAAa;QAC/C,OAAO,EAAE,4IAA4I;QACrJ,SAAS,EAAE,sBAAsB,CAAC,kBAAkB;QACpD,QAAQ,EAAE,sEAAsE;QAChF,OAAO,EAAE,4HAA4H;KACtI,CAAC;CACH,CAAC,CAAC;AAEH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,uCAAuC,GAAG,CAAC,CAAC,MAAM,CAC7D,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EACxB,CAAC,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAClC,CAAC;AAGF;;;;;;GAMG;AACH,MAAM,UAAU,kCAAkC,CAChD,mBAAsC,EACtC,SAAwD;IAExD,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,SAAS,EAAE,CAAC,UAAU,CAAC,KAAK,SAAS,CAAC,CAAC;AAC3F,CAAC","sourcesContent":["import { z } from \"zod\";\n\nimport { WEBSITE_VISITOR_CONSENT_STORAGE_KEY } from \"./consent-purposes.shared\";\n\n/**\n * **What the application stores in a visitor's browser, and what gates it.**\n *\n * ## What a cookie notice actually is\n *\n * An itemised table: which cookies and client-side storage keys are set, what each is for, how long it\n * persists, and which are strictly necessary versus consent-gated. Nothing in the framework declared\n * any of it (issue #91).\n *\n * The consent POSTURE was already real and enforced — `consentedPurposes` plus the capability\n * flags make `ConsentPurpose.ANALYTICS` a boundary the runtime honours rather than a stated intention, which is a\n * stronger position than most cookie notices, which describe consent they do not enforce. What could\n * not be produced was the table.\n *\n * ## The engine sets cookies of its own, and that is why this has an ORIGIN split\n *\n * Every generated application sets at least one cookie it never declared, because the framework sets\n * it: {@link ENGINE_CLIENT_STORAGE_ENTRIES}. Asking only the application would produce a cookie table\n * that omits the session cookie — the same shape as the engine-versus-application finding in the\n * resource declarations, and the same remedy: report the two origins separately, and let the framework\n * answer for its own.\n *\n * ## Lifetimes the framework will not invent\n *\n * The engine's cookies take their `maxAge` from the application's session configuration, so the\n * framework declares the NAME, the purpose and the necessity, and describes the lifetime by where it\n * comes from. A fixed number here would be a published commitment nothing enforces — the same rule\n * that governs the retention schedule.\n */\n\n/** Where a value is stored in the browser. Cookies and web storage carry different expectations and different law. */\nexport enum ClientStorageMechanism {\n  COOKIE = \"COOKIE\",\n  LOCAL_STORAGE = \"LOCAL_STORAGE\",\n  SESSION_STORAGE = \"SESSION_STORAGE\",\n}\n\n/**\n * Whether the entry may be set before consent.\n *\n * The distinction a cookie banner exists to implement, and the one a notice is read for. Two values on\n * purpose: an entry is either required for a service the visitor asked for, or it is not and needs\n * consent. A middle category would be a place to put everything nobody wanted to decide.\n */\nexport enum ClientStorageNecessity {\n  /** Required to deliver a service the visitor explicitly requested — signing in, keeping a session. */\n  STRICTLY_NECESSARY = \"STRICTLY_NECESSARY\",\n  /** Set only after the visitor consents. Analytics, personalisation, anything measuring behaviour. */\n  CONSENT_GATED = \"CONSENT_GATED\",\n}\n\n/** One cookie or storage key, as a notice's table would print it. */\nexport const ClientStorageEntrySchema = z.strictObject({\n  /** The exact key or cookie name a visitor would see in their browser. Not a description of it. */\n  name: z.string().trim().min(1),\n  mechanism: z.enum(ClientStorageMechanism),\n  /** What it is FOR, in a sentence a visitor can read. \"Session management\", not \"auth token v2\". */\n  purpose: z.string().trim().min(1),\n  necessity: z.enum(ClientStorageNecessity),\n  /**\n   * How long it persists, as a notice would state it — \"the browser session\", \"30 days\", or where the\n   * value comes from when the application configures it.\n   *\n   * Free text rather than a duration, because the honest answer is often a reference rather than a\n   * number, and a number the application does not actually enforce is worse than a description of the\n   * mechanism that does.\n   */\n  lifetime: z.string().trim().min(1),\n  /**\n   * WHEN it is set, for an entry that is not set on every visit — `null` when it always is.\n   *\n   * Required-and-nullable rather than optional: \"set on every visit\" and \"nobody recorded when\" are\n   * different answers, and a cookie table that implies the first while meaning the second overstates\n   * what a visitor's browser holds.\n   */\n  setWhen: z.string().trim().min(1).nullable(),\n});\nexport type ClientStorageEntry = z.infer<typeof ClientStorageEntrySchema>;\n\n/**\n * The client storage the FRAMEWORK sets, which no application authored and every application inherits.\n *\n * All are `STRICTLY_NECESSARY`. The two cookies carry session state for a service the visitor asked for\n * and are `httpOnly`, so no script can read them. The website consent record (#534) is web storage and\n * is necessary for a different reason: remembering a refusal is what makes the refusal hold, and a\n * consent record that itself needed consent could never be kept.\n *\n * Their lifetimes are the application's to configure, so they are described by their SOURCE. Their\n * `setWhen` is stated because neither is unconditional: an application whose visitors never sign in\n * sets no refresh cookie, and one that does not use anonymous sessions sets no anonymous cookie. A\n * table claiming both are always present would overstate what a visitor's browser holds.\n */\nexport const ENGINE_CLIENT_STORAGE_ENTRIES: readonly ClientStorageEntry[] = Object.freeze([\n  Object.freeze({\n    name: \"__wildo_refresh\",\n    mechanism: ClientStorageMechanism.COOKIE,\n    purpose: \"Keeps a signed-in session alive so a visitor is not asked to authenticate on every request.\",\n    necessity: ClientStorageNecessity.STRICTLY_NECESSARY,\n    lifetime: \"The application's configured refresh-token expiry.\",\n    setWhen: \"Set when a visitor signs in, and cleared when they sign out.\",\n  }),\n  Object.freeze({\n    name: \"__wildo_anon_session\",\n    mechanism: ClientStorageMechanism.COOKIE,\n    purpose: \"Gives a visitor who has not signed in a continuous session, so work in progress survives a page load.\",\n    necessity: ClientStorageNecessity.STRICTLY_NECESSARY,\n    lifetime: \"The application's configured anonymous-session lifetime.\",\n    setWhen: \"Set only where the application admits anonymous visitors.\",\n  }),\n  Object.freeze({\n    name: WEBSITE_VISITOR_CONSENT_STORAGE_KEY,\n    mechanism: ClientStorageMechanism.LOCAL_STORAGE,\n    purpose: \"Remembers which optional purposes a website visitor agreed to, so they are not asked on every page and nothing optional starts without it.\",\n    necessity: ClientStorageNecessity.STRICTLY_NECESSARY,\n    lifetime: \"Until the visitor changes their choice or clears the site's storage.\",\n    setWhen: \"Set on the marketing website when a visitor makes a consent choice, and only where the site runs a consent-based provider.\",\n  }),\n]);\n\n/**\n * The application's own client storage, per FRONTEND SURFACE.\n *\n * Per surface rather than application-wide, and that is the issue's own point: a public marketing site\n * and the authenticated application set different things, and one merged list would be wrong for both —\n * it would show a visitor to the marketing site cookies only the app sets.\n *\n * Partial: a surface with no entry has not been inventoried, which the derivation reports. An empty\n * ARRAY is the different, positive answer — this surface sets nothing of its own beyond the engine's.\n */\nexport const ApplicationClientStorageInventorySchema = z.record(\n  z.string().trim().min(1),\n  z.array(ClientStorageEntrySchema),\n);\nexport type ApplicationClientStorageInventory = z.infer<typeof ApplicationClientStorageInventorySchema>;\n\n/**\n * Frontend surfaces with no inventory at all — the gap, per surface.\n *\n * Takes the surface list as an argument so the same function serves the companion (which reads the\n * declared services) and a test. Order follows the surfaces given, so the answer reads like the\n * application it describes.\n */\nexport function uninventoriedClientStorageSurfaces(\n  frontendSurfaceKeys: readonly string[],\n  inventory: ApplicationClientStorageInventory | undefined,\n): readonly string[] {\n  return frontendSurfaceKeys.filter((surfaceKey) => inventory?.[surfaceKey] === undefined);\n}\n"]}

package/dist/esm/compliance/privacy/consent-gate-vocabulary.shared.schemas.d.ts

@@ -0,0 +1,127 @@
+import { ConsentPurpose } from './consent-purposes.shared';
+/**
+ * WHEN a person is put the question of a consent-gated purpose (#1258 Step 3).
+ *
+ * `compliance.serviceConsentRequirement` collapsed this axis to one member — the check runs on
+ * every user-initiated operation, forever — and that is correct for exactly the case it exists for
+ * (the whole application rests on the purpose). Most declared purposes do not: an operation that
+ * merely USES a purpose when it is granted needs to ask once, not on every call.
+ *
+ * A closed vocabulary rather than a boolean or a duration, because each member is a different KIND
+ * of trigger — some are moments in a lifecycle, one is a standing check — and a single "how often"
+ * field could not tell a reader which.
+ */
+export declare enum ConsentGateTiming {
+    /** Before there is an account — the marketing website's own visitor prompt. Not backend-enforced: no request exists to refuse. */
+    VISITOR = "visitor",
+    /** At the moment an account is created, alongside document acceptance. Asked once. */
+    SIGNUP = "signup",
+    /** The first time a signed-in person's session reaches the application, via the guidance/onboarding engine (D7). Asked once per person, not per capability. */
+    FIRST_SESSION = "firstSession",
+    /** The first time THIS capability is reached, by the surface that declares it. Asked once per person per capability. */
+    ON_USE = "onUse",
+    /** Re-asked when the declaration this purpose rests on changes materially — mirrors governed-document re-acceptance (Step 2), never a silent re-prompt of everybody. */
+    ON_CHANGE = "onChange",
+    /** Checked on every user-initiated operation, application-wide. The ONLY member `serviceConsentRequirement` uses — see {@link SERVICE_CONSENT_REQUIREMENT_TIMING}. */
+    ALWAYS = "always"
+}
+/**
+ * WHAT a missing consent-gated purpose costs the person right now (#1258 Step 3).
+ *
+ * A closed vocabulary rather than a boolean "blocking", because a missing purpose has three
+ * genuinely different consequences and conflating any two of them either over-blocks (today's
+ * `serviceConsentRequirement`, applied per capability, would lock a person out of a to-do list over
+ * analytics) or under-informs (silently disabling a feature with no explanation).
+ */
+export declare enum ConsentGateRefusal {
+    /** Nothing is withheld. The purpose is surfaced to the person as a decision they have not made, and nothing more. */
+    INFORM = "inform",
+    /**
+     * The DECLARING operation refuses, with a typed error the caller can branch on, and nothing else.
+     * The default when a declaration names a purpose and no refusal (D2) — a declaration that only
+     * says WHAT is asked must not silently become a claim about the whole product.
+     */
+    WITHHOLD_CAPABILITY = "withholdCapability",
+    /**
+     * The whole application is withheld until the purpose is granted. Reserved for the application-wide
+     * requirement (`serviceConsentRequirement`) — see {@link SERVICE_CONSENT_REQUIREMENT_REFUSAL}. An
+     * operation-level declaration may not choose this member (its type excludes it): a single capability
+     * asking for the whole product to be withheld is exactly the collapse D2 exists to prevent, and the
+     * one place that genuinely means it already has its own field.
+     */
+    WITHHOLD_SERVICE = "withholdService"
+}
+/**
+ * `compliance.serviceConsentRequirement` is the ONE cell of the ⟨timing, refusal⟩ grid this framework
+ * enforces unconditionally (D1): {@link ConsentGateTiming.ALWAYS} × {@link ConsentGateRefusal.WITHHOLD_SERVICE},
+ * applied to the whole application rather than to one capability.
+ *
+ * It needs no `timing` / `refusal` field of its own — the cell is fixed by what the field IS — and
+ * these two constants exist only so the mapping is STATED rather than merely true: a reader who has
+ * just read {@link ConsentGateTiming} and {@link ConsentGateRefusal} can find, in one place, which
+ * cell the field they already know about occupies. The runtime behaviour is unchanged; see
+ * `assertServiceConsentRequirementMet` in `@wildo-ai/saas-backend-lib`, which evaluates BOTH this
+ * cell and any operation's own {@link ResourceOperationConsentGateDeclaration} through the same
+ * chokepoint, so the two axes cannot disagree about a purpose both name.
+ */
+export declare const SERVICE_CONSENT_REQUIREMENT_TIMING = ConsentGateTiming.ALWAYS;
+export declare const SERVICE_CONSENT_REQUIREMENT_REFUSAL = ConsentGateRefusal.WITHHOLD_SERVICE;
+/**
+ * What a resource OPERATION declares about the purpose its processing rests on (#1258 Step 3).
+ *
+ * "A capability declares the purpose it rests on — on the resource operation first": this is that
+ * declaration. It lives beside `recordsUsage` and `userNotifications` on the operation config — an
+ * authored consequence of the operation, expressed where the operation is expressed — and is read by
+ * the SAME evaluator `serviceConsentRequirement` goes through, so a purpose required at BOTH levels is
+ * governed once rather than twice (`consentGateCapabilityOwed`).
+ *
+ * `refusal` excludes {@link ConsentGateRefusal.WITHHOLD_SERVICE} by TYPE, not by convention — see that
+ * member's own doc for why. `timing` is advisory to the backend (which enforces regardless of when a
+ * frontend surface asked) and load-bearing for the frontend surface that decides WHEN to ask.
+ *
+ * **The prompt surface reads this field (#1462).** `applicationAskedConsentPurposes` unions
+ * `requiredPurposes`, `analytics.*` and `compliance.capabilityDeclaredConsentPurposes` — the set the
+ * engine derives, once at boot, from every operation's own `consentGate` across the whole registry
+ * (`collectCapabilityDeclaredConsentPurposes`, called by `ResourcesRegistryBackendService.initialize()`
+ * the moment the registry is built). So declaring one here is enough: no second declaration site, and
+ * the application-tier gate offers it the same way it already offers ANALYTICS.
+ *
+ * What this does NOT yet do: distinguish `timing`. `ON_USE` / `FIRST_SESSION` are declared members of
+ * {@link ConsentGateTiming} with no dedicated prompt surface to honour them — every declared purpose
+ * is offered by the one generic prompt that exists today, regardless of which timing member it names.
+ * That is a real, tracked gap (`#1462`'s two folded-in follow-ups), and it is strictly better than the
+ * alternative it replaced: refusing a capability with nowhere at all to grant what it asks for.
+ */
+export interface ResourceOperationConsentGateDeclaration {
+    /** The purpose this operation's processing rests on. */
+    readonly purpose: ConsentPurpose;
+    /** What a missing grant costs. Defaults to {@link ConsentGateRefusal.WITHHOLD_CAPABILITY} (D2). */
+    readonly refusal?: Exclude<ConsentGateRefusal, ConsentGateRefusal.WITHHOLD_SERVICE>;
+    /** When the person is asked. Defaults to {@link ConsentGateTiming.ON_USE}. */
+    readonly timing?: ConsentGateTiming;
+}
+/** One purpose this principal owes, and what it currently costs them, for ONE operation's declaration. */
+export interface ConsentGateCapabilityOwed {
+    readonly purpose: ConsentPurpose;
+    readonly refusal: ConsentGateRefusal;
+}
+/**
+ * What an operation's OWN {@link ResourceOperationConsentGateDeclaration} still owes, given what the
+ * person has granted and what the application already requires application-wide.
+ *
+ * Pure, so the merge rule between the two independent sources of a required purpose — the
+ * application-wide requirement and a capability's own declaration — is written once and pinned
+ * without a running backend. `undefined` in every case where nothing is owed:
+ *
+ * - the operation declares nothing;
+ * - the declared purpose is already granted;
+ * - the declared purpose is ALSO in the application-wide required set — that purpose is already
+ *   governed by `serviceConsentRequirement`'s WITHHOLD_SERVICE cell, so re-declaring it here would
+ *   evaluate the same fact twice and could, on a future edit, disagree with itself.
+ */
+export declare function consentGateCapabilityOwed(input: {
+    readonly granted: readonly ConsentPurpose[];
+    readonly declaration: ResourceOperationConsentGateDeclaration | undefined;
+    readonly serviceRequiredPurposes: readonly ConsentPurpose[];
+}): ConsentGateCapabilityOwed | undefined;
+//# sourceMappingURL=consent-gate-vocabulary.shared.schemas.d.ts.map

package/dist/esm/compliance/privacy/consent-gate-vocabulary.shared.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent-gate-vocabulary.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/compliance/privacy/consent-gate-vocabulary.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE3D;;;;;;;;;;;GAWG;AACH,oBAAY,iBAAiB;IAC3B,kIAAkI;IAClI,OAAO,YAAY;IACnB,sFAAsF;IACtF,MAAM,WAAW;IACjB,+JAA+J;IAC/J,aAAa,iBAAiB;IAC9B,wHAAwH;IACxH,MAAM,UAAU;IAChB,wKAAwK;IACxK,SAAS,aAAa;IACtB,sKAAsK;IACtK,MAAM,WAAW;CAClB;AAED;;;;;;;GAOG;AACH,oBAAY,kBAAkB;IAC5B,qHAAqH;IACrH,MAAM,WAAW;IACjB;;;;OAIG;IACH,mBAAmB,uBAAuB;IAC1C;;;;;;OAMG;IACH,gBAAgB,oBAAoB;CACrC;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kCAAkC,2BAA2B,CAAC;AAC3E,eAAO,MAAM,mCAAmC,sCAAsC,CAAC;AAEvF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,uCAAuC;IACtD,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,mGAAmG;IACnG,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,gBAAgB,CAAC,CAAC;IACpF,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;CACrC;AAED,0GAA0G;AAC1G,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;CACtC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IAC5C,QAAQ,CAAC,WAAW,EAAE,uCAAuC,GAAG,SAAS,CAAC;IAC1E,QAAQ,CAAC,uBAAuB,EAAE,SAAS,cAAc,EAAE,CAAC;CAC7D,GAAG,yBAAyB,GAAG,SAAS,CAMxC"}

package/dist/esm/compliance/privacy/consent-gate-vocabulary.shared.schemas.js

@@ -0,0 +1,94 @@
+/**
+ * WHEN a person is put the question of a consent-gated purpose (#1258 Step 3).
+ *
+ * `compliance.serviceConsentRequirement` collapsed this axis to one member — the check runs on
+ * every user-initiated operation, forever — and that is correct for exactly the case it exists for
+ * (the whole application rests on the purpose). Most declared purposes do not: an operation that
+ * merely USES a purpose when it is granted needs to ask once, not on every call.
+ *
+ * A closed vocabulary rather than a boolean or a duration, because each member is a different KIND
+ * of trigger — some are moments in a lifecycle, one is a standing check — and a single "how often"
+ * field could not tell a reader which.
+ */
+export var ConsentGateTiming;
+(function (ConsentGateTiming) {
+    /** Before there is an account — the marketing website's own visitor prompt. Not backend-enforced: no request exists to refuse. */
+    ConsentGateTiming["VISITOR"] = "visitor";
+    /** At the moment an account is created, alongside document acceptance. Asked once. */
+    ConsentGateTiming["SIGNUP"] = "signup";
+    /** The first time a signed-in person's session reaches the application, via the guidance/onboarding engine (D7). Asked once per person, not per capability. */
+    ConsentGateTiming["FIRST_SESSION"] = "firstSession";
+    /** The first time THIS capability is reached, by the surface that declares it. Asked once per person per capability. */
+    ConsentGateTiming["ON_USE"] = "onUse";
+    /** Re-asked when the declaration this purpose rests on changes materially — mirrors governed-document re-acceptance (Step 2), never a silent re-prompt of everybody. */
+    ConsentGateTiming["ON_CHANGE"] = "onChange";
+    /** Checked on every user-initiated operation, application-wide. The ONLY member `serviceConsentRequirement` uses — see {@link SERVICE_CONSENT_REQUIREMENT_TIMING}. */
+    ConsentGateTiming["ALWAYS"] = "always";
+})(ConsentGateTiming || (ConsentGateTiming = {}));
+/**
+ * WHAT a missing consent-gated purpose costs the person right now (#1258 Step 3).
+ *
+ * A closed vocabulary rather than a boolean "blocking", because a missing purpose has three
+ * genuinely different consequences and conflating any two of them either over-blocks (today's
+ * `serviceConsentRequirement`, applied per capability, would lock a person out of a to-do list over
+ * analytics) or under-informs (silently disabling a feature with no explanation).
+ */
+export var ConsentGateRefusal;
+(function (ConsentGateRefusal) {
+    /** Nothing is withheld. The purpose is surfaced to the person as a decision they have not made, and nothing more. */
+    ConsentGateRefusal["INFORM"] = "inform";
+    /**
+     * The DECLARING operation refuses, with a typed error the caller can branch on, and nothing else.
+     * The default when a declaration names a purpose and no refusal (D2) — a declaration that only
+     * says WHAT is asked must not silently become a claim about the whole product.
+     */
+    ConsentGateRefusal["WITHHOLD_CAPABILITY"] = "withholdCapability";
+    /**
+     * The whole application is withheld until the purpose is granted. Reserved for the application-wide
+     * requirement (`serviceConsentRequirement`) — see {@link SERVICE_CONSENT_REQUIREMENT_REFUSAL}. An
+     * operation-level declaration may not choose this member (its type excludes it): a single capability
+     * asking for the whole product to be withheld is exactly the collapse D2 exists to prevent, and the
+     * one place that genuinely means it already has its own field.
+     */
+    ConsentGateRefusal["WITHHOLD_SERVICE"] = "withholdService";
+})(ConsentGateRefusal || (ConsentGateRefusal = {}));
+/**
+ * `compliance.serviceConsentRequirement` is the ONE cell of the ⟨timing, refusal⟩ grid this framework
+ * enforces unconditionally (D1): {@link ConsentGateTiming.ALWAYS} × {@link ConsentGateRefusal.WITHHOLD_SERVICE},
+ * applied to the whole application rather than to one capability.
+ *
+ * It needs no `timing` / `refusal` field of its own — the cell is fixed by what the field IS — and
+ * these two constants exist only so the mapping is STATED rather than merely true: a reader who has
+ * just read {@link ConsentGateTiming} and {@link ConsentGateRefusal} can find, in one place, which
+ * cell the field they already know about occupies. The runtime behaviour is unchanged; see
+ * `assertServiceConsentRequirementMet` in `@wildo-ai/saas-backend-lib`, which evaluates BOTH this
+ * cell and any operation's own {@link ResourceOperationConsentGateDeclaration} through the same
+ * chokepoint, so the two axes cannot disagree about a purpose both name.
+ */
+export const SERVICE_CONSENT_REQUIREMENT_TIMING = ConsentGateTiming.ALWAYS;
+export const SERVICE_CONSENT_REQUIREMENT_REFUSAL = ConsentGateRefusal.WITHHOLD_SERVICE;
+/**
+ * What an operation's OWN {@link ResourceOperationConsentGateDeclaration} still owes, given what the
+ * person has granted and what the application already requires application-wide.
+ *
+ * Pure, so the merge rule between the two independent sources of a required purpose — the
+ * application-wide requirement and a capability's own declaration — is written once and pinned
+ * without a running backend. `undefined` in every case where nothing is owed:
+ *
+ * - the operation declares nothing;
+ * - the declared purpose is already granted;
+ * - the declared purpose is ALSO in the application-wide required set — that purpose is already
+ *   governed by `serviceConsentRequirement`'s WITHHOLD_SERVICE cell, so re-declaring it here would
+ *   evaluate the same fact twice and could, on a future edit, disagree with itself.
+ */
+export function consentGateCapabilityOwed(input) {
+    const { declaration } = input;
+    if (!declaration)
+        return undefined;
+    if (input.serviceRequiredPurposes.includes(declaration.purpose))
+        return undefined;
+    if (input.granted.includes(declaration.purpose))
+        return undefined;
+    return { purpose: declaration.purpose, refusal: declaration.refusal ?? ConsentGateRefusal.WITHHOLD_CAPABILITY };
+}
+//# sourceMappingURL=consent-gate-vocabulary.shared.schemas.js.map

package/dist/esm/compliance/privacy/consent-gate-vocabulary.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent-gate-vocabulary.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/compliance/privacy/consent-gate-vocabulary.shared.schemas.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,MAAM,CAAN,IAAY,iBAaX;AAbD,WAAY,iBAAiB;IAC3B,kIAAkI;IAClI,wCAAmB,CAAA;IACnB,sFAAsF;IACtF,sCAAiB,CAAA;IACjB,+JAA+J;IAC/J,mDAA8B,CAAA;IAC9B,wHAAwH;IACxH,qCAAgB,CAAA;IAChB,wKAAwK;IACxK,2CAAsB,CAAA;IACtB,sKAAsK;IACtK,sCAAiB,CAAA;AACnB,CAAC,EAbW,iBAAiB,KAAjB,iBAAiB,QAa5B;AAED;;;;;;;GAOG;AACH,MAAM,CAAN,IAAY,kBAiBX;AAjBD,WAAY,kBAAkB;IAC5B,qHAAqH;IACrH,uCAAiB,CAAA;IACjB;;;;OAIG;IACH,gEAA0C,CAAA;IAC1C;;;;;;OAMG;IACH,0DAAoC,CAAA;AACtC,CAAC,EAjBW,kBAAkB,KAAlB,kBAAkB,QAiB7B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,iBAAiB,CAAC,MAAM,CAAC;AAC3E,MAAM,CAAC,MAAM,mCAAmC,GAAG,kBAAkB,CAAC,gBAAgB,CAAC;AA2CvF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAIzC;IACC,MAAM,EAAE,WAAW,EAAE,GAAG,KAAK,CAAC;IAC9B,IAAI,CAAC,WAAW;QAAE,OAAO,SAAS,CAAC;IACnC,IAAI,KAAK,CAAC,uBAAuB,CAAC,QAAQ,CAAC,WAAW,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IAClF,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IAClE,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,OAAO,IAAI,kBAAkB,CAAC,mBAAmB,EAAE,CAAC;AAClH,CAAC","sourcesContent":["import { ConsentPurpose } from './consent-purposes.shared';\n\n/**\n * WHEN a person is put the question of a consent-gated purpose (#1258 Step 3).\n *\n * `compliance.serviceConsentRequirement` collapsed this axis to one member — the check runs on\n * every user-initiated operation, forever — and that is correct for exactly the case it exists for\n * (the whole application rests on the purpose). Most declared purposes do not: an operation that\n * merely USES a purpose when it is granted needs to ask once, not on every call.\n *\n * A closed vocabulary rather than a boolean or a duration, because each member is a different KIND\n * of trigger — some are moments in a lifecycle, one is a standing check — and a single \"how often\"\n * field could not tell a reader which.\n */\nexport enum ConsentGateTiming {\n  /** Before there is an account — the marketing website's own visitor prompt. Not backend-enforced: no request exists to refuse. */\n  VISITOR = 'visitor',\n  /** At the moment an account is created, alongside document acceptance. Asked once. */\n  SIGNUP = 'signup',\n  /** The first time a signed-in person's session reaches the application, via the guidance/onboarding engine (D7). Asked once per person, not per capability. */\n  FIRST_SESSION = 'firstSession',\n  /** The first time THIS capability is reached, by the surface that declares it. Asked once per person per capability. */\n  ON_USE = 'onUse',\n  /** Re-asked when the declaration this purpose rests on changes materially — mirrors governed-document re-acceptance (Step 2), never a silent re-prompt of everybody. */\n  ON_CHANGE = 'onChange',\n  /** Checked on every user-initiated operation, application-wide. The ONLY member `serviceConsentRequirement` uses — see {@link SERVICE_CONSENT_REQUIREMENT_TIMING}. */\n  ALWAYS = 'always',\n}\n\n/**\n * WHAT a missing consent-gated purpose costs the person right now (#1258 Step 3).\n *\n * A closed vocabulary rather than a boolean \"blocking\", because a missing purpose has three\n * genuinely different consequences and conflating any two of them either over-blocks (today's\n * `serviceConsentRequirement`, applied per capability, would lock a person out of a to-do list over\n * analytics) or under-informs (silently disabling a feature with no explanation).\n */\nexport enum ConsentGateRefusal {\n  /** Nothing is withheld. The purpose is surfaced to the person as a decision they have not made, and nothing more. */\n  INFORM = 'inform',\n  /**\n   * The DECLARING operation refuses, with a typed error the caller can branch on, and nothing else.\n   * The default when a declaration names a purpose and no refusal (D2) — a declaration that only\n   * says WHAT is asked must not silently become a claim about the whole product.\n   */\n  WITHHOLD_CAPABILITY = 'withholdCapability',\n  /**\n   * The whole application is withheld until the purpose is granted. Reserved for the application-wide\n   * requirement (`serviceConsentRequirement`) — see {@link SERVICE_CONSENT_REQUIREMENT_REFUSAL}. An\n   * operation-level declaration may not choose this member (its type excludes it): a single capability\n   * asking for the whole product to be withheld is exactly the collapse D2 exists to prevent, and the\n   * one place that genuinely means it already has its own field.\n   */\n  WITHHOLD_SERVICE = 'withholdService',\n}\n\n/**\n * `compliance.serviceConsentRequirement` is the ONE cell of the ⟨timing, refusal⟩ grid this framework\n * enforces unconditionally (D1): {@link ConsentGateTiming.ALWAYS} × {@link ConsentGateRefusal.WITHHOLD_SERVICE},\n * applied to the whole application rather than to one capability.\n *\n * It needs no `timing` / `refusal` field of its own — the cell is fixed by what the field IS — and\n * these two constants exist only so the mapping is STATED rather than merely true: a reader who has\n * just read {@link ConsentGateTiming} and {@link ConsentGateRefusal} can find, in one place, which\n * cell the field they already know about occupies. The runtime behaviour is unchanged; see\n * `assertServiceConsentRequirementMet` in `@wildo-ai/saas-backend-lib`, which evaluates BOTH this\n * cell and any operation's own {@link ResourceOperationConsentGateDeclaration} through the same\n * chokepoint, so the two axes cannot disagree about a purpose both name.\n */\nexport const SERVICE_CONSENT_REQUIREMENT_TIMING = ConsentGateTiming.ALWAYS;\nexport const SERVICE_CONSENT_REQUIREMENT_REFUSAL = ConsentGateRefusal.WITHHOLD_SERVICE;\n\n/**\n * What a resource OPERATION declares about the purpose its processing rests on (#1258 Step 3).\n *\n * \"A capability declares the purpose it rests on — on the resource operation first\": this is that\n * declaration. It lives beside `recordsUsage` and `userNotifications` on the operation config — an\n * authored consequence of the operation, expressed where the operation is expressed — and is read by\n * the SAME evaluator `serviceConsentRequirement` goes through, so a purpose required at BOTH levels is\n * governed once rather than twice (`consentGateCapabilityOwed`).\n *\n * `refusal` excludes {@link ConsentGateRefusal.WITHHOLD_SERVICE} by TYPE, not by convention — see that\n * member's own doc for why. `timing` is advisory to the backend (which enforces regardless of when a\n * frontend surface asked) and load-bearing for the frontend surface that decides WHEN to ask.\n *\n * **The prompt surface reads this field (#1462).** `applicationAskedConsentPurposes` unions\n * `requiredPurposes`, `analytics.*` and `compliance.capabilityDeclaredConsentPurposes` — the set the\n * engine derives, once at boot, from every operation's own `consentGate` across the whole registry\n * (`collectCapabilityDeclaredConsentPurposes`, called by `ResourcesRegistryBackendService.initialize()`\n * the moment the registry is built). So declaring one here is enough: no second declaration site, and\n * the application-tier gate offers it the same way it already offers ANALYTICS.\n *\n * What this does NOT yet do: distinguish `timing`. `ON_USE` / `FIRST_SESSION` are declared members of\n * {@link ConsentGateTiming} with no dedicated prompt surface to honour them — every declared purpose\n * is offered by the one generic prompt that exists today, regardless of which timing member it names.\n * That is a real, tracked gap (`#1462`'s two folded-in follow-ups), and it is strictly better than the\n * alternative it replaced: refusing a capability with nowhere at all to grant what it asks for.\n */\nexport interface ResourceOperationConsentGateDeclaration {\n  /** The purpose this operation's processing rests on. */\n  readonly purpose: ConsentPurpose;\n  /** What a missing grant costs. Defaults to {@link ConsentGateRefusal.WITHHOLD_CAPABILITY} (D2). */\n  readonly refusal?: Exclude<ConsentGateRefusal, ConsentGateRefusal.WITHHOLD_SERVICE>;\n  /** When the person is asked. Defaults to {@link ConsentGateTiming.ON_USE}. */\n  readonly timing?: ConsentGateTiming;\n}\n\n/** One purpose this principal owes, and what it currently costs them, for ONE operation's declaration. */\nexport interface ConsentGateCapabilityOwed {\n  readonly purpose: ConsentPurpose;\n  readonly refusal: ConsentGateRefusal;\n}\n\n/**\n * What an operation's OWN {@link ResourceOperationConsentGateDeclaration} still owes, given what the\n * person has granted and what the application already requires application-wide.\n *\n * Pure, so the merge rule between the two independent sources of a required purpose — the\n * application-wide requirement and a capability's own declaration — is written once and pinned\n * without a running backend. `undefined` in every case where nothing is owed:\n *\n * - the operation declares nothing;\n * - the declared purpose is already granted;\n * - the declared purpose is ALSO in the application-wide required set — that purpose is already\n *   governed by `serviceConsentRequirement`'s WITHHOLD_SERVICE cell, so re-declaring it here would\n *   evaluate the same fact twice and could, on a future edit, disagree with itself.\n */\nexport function consentGateCapabilityOwed(input: {\n  readonly granted: readonly ConsentPurpose[];\n  readonly declaration: ResourceOperationConsentGateDeclaration | undefined;\n  readonly serviceRequiredPurposes: readonly ConsentPurpose[];\n}): ConsentGateCapabilityOwed | undefined {\n  const { declaration } = input;\n  if (!declaration) return undefined;\n  if (input.serviceRequiredPurposes.includes(declaration.purpose)) return undefined;\n  if (input.granted.includes(declaration.purpose)) return undefined;\n  return { purpose: declaration.purpose, refusal: declaration.refusal ?? ConsentGateRefusal.WITHHOLD_CAPABILITY };\n}\n"]}