@wildo-ai/saas-models 1.1.2 → 1.1.3

package/dist/esm/compliance/privacy/operating-jurisdictions.shared.schemas.js

@@ -32,12 +32,107 @@ import { z } from 'zod';
  * consumes it. An application may always declare where it operates; Wildo says plainly where it has
  * nothing to offer.
  */
+const JURISDICTION_SLUG_SHAPE = /^[a-z]{2}(-[a-z0-9]{1,8})?$/u;
+const JURISDICTION_SLUG_SHAPE_MESSAGE = 'a jurisdiction slug is an ISO 3166-1 alpha-2 country code, a supranational code such as "eu", '
+    + 'optionally with a regime or subdivision suffix such as "us-ca" — lowercase, because a slug that '
+    + 'differs only by case is a second identifier for one place';
+/**
+ * The CANONICAL form of a region subtag, or `null` when the subtag is not well-formed.
+ *
+ * Shape alone cannot separate `gb` from `uk`: both are two lowercase letters, both name the same
+ * place, and only one is the ISO 3166-1 alpha-2 code. So the shape check is answered by the regex
+ * and IDENTITY is answered here, by the same authority the publication validator already uses for
+ * the locale half of a variant — `Intl.getCanonicalLocales`, which resolves the CLDR alias table.
+ *
+ * A data file was rejected. An enumerated country list is a legal fact with a review trigger (the
+ * one table this file does keep, {@link JURISDICTION_CONTAINMENT}, says so and is 27 rows), and a
+ * second one covering every country on earth would rot with nobody watching. `Intl` ships the table
+ * with the runtime and updates with it.
+ *
+ * What this deliberately does NOT catch: a well-formed but unassigned code (`qq`, `aa`) canonicalises
+ * to itself and passes. Those are not authoring mistakes anybody makes; `uk` demonstrably is — it is
+ * in this repository's own tests and prose.
+ */
+function canonicalRegionSubtag(subtag) {
+    const requested = `und-${subtag.toUpperCase()}`;
+    try {
+        const [canonical] = Intl.getCanonicalLocales(requested);
+        return canonical === undefined ? null : canonical.slice('und-'.length);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * What is wrong with `slug` as a jurisdiction slug, or `null` when nothing is.
+ *
+ * Exported as a FUNCTION rather than only as a schema because the consumers that matter do not parse
+ * — the governed-document publication validator and the `_core` compliance-document candidate
+ * validator both emit their own typed issue records, and routing them through a Zod error to recover
+ * a message is how two surfaces come to disagree about what a jurisdiction is. One rule, three
+ * readers.
+ */
+export function jurisdictionSlugProblem(slug) {
+    if (!JURISDICTION_SLUG_SHAPE.test(slug)) {
+        return `${JURISDICTION_SLUG_SHAPE_MESSAGE} — received "${slug}"`;
+    }
+    const [root] = slug.split('-');
+    const canonical = canonicalRegionSubtag(root);
+    if (canonical === null) {
+        return `"${root}" is not a well-formed region code`;
+    }
+    if (canonical.toLowerCase() !== root) {
+        return `"${root}" is an alias for "${canonical.toLowerCase()}" — use the canonical code, or two slugs are one place`;
+    }
+    return null;
+}
 export const JurisdictionSlugSchema = z
     .string()
     .trim()
-    .regex(/^[a-z]{2}(-[a-z0-9]{1,8})?$/u, 'a jurisdiction slug is an ISO 3166-1 alpha-2 country code, a supranational code such as "eu", '
-    + 'optionally with a subdivision suffix such as "us-ca" — lowercase, because a slug that differs '
-    + 'only by case is a second identifier for one place');
+    .superRefine((slug, context) => {
+    const problem = jurisdictionSlugProblem(slug);
+    if (problem !== null) {
+        context.addIssue({ code: 'custom', message: problem });
+    }
+});
+/**
+ * The namespace every jurisdiction REFERENCE carries.
+ *
+ * A ref is `jurisdiction:<slug>`, and both halves are checked, because checking only the namespace is
+ * what let `jurisdiction:united-kingdom` — a value {@link JurisdictionSlugSchema} would refuse
+ * outright — sit in a landed application specification beside that same application's configuration
+ * declaring `gb`.
+ */
+export const JURISDICTION_REF_NAMESPACE = 'jurisdiction:';
+/** Which half of a `jurisdiction:<slug>` ref is wrong. The two are separate failures with separate remedies. */
+export var JurisdictionRefProblemScope;
+(function (JurisdictionRefProblemScope) {
+    /** The ref is not in the `jurisdiction:` namespace, so it resolves against a different vocabulary entirely. */
+    JurisdictionRefProblemScope["NAMESPACE"] = "NAMESPACE";
+    /** The namespace is right and the slug is not a jurisdiction. */
+    JurisdictionRefProblemScope["SLUG"] = "SLUG";
+})(JurisdictionRefProblemScope || (JurisdictionRefProblemScope = {}));
+/** What is wrong with `ref` as a `jurisdiction:<slug>` reference, or `null` when nothing is. */
+export function jurisdictionRefProblem(ref) {
+    if (!ref.startsWith(JURISDICTION_REF_NAMESPACE)) {
+        return {
+            scope: JurisdictionRefProblemScope.NAMESPACE,
+            message: `jurisdiction ref ${ref} must use the ${JURISDICTION_REF_NAMESPACE} namespace`,
+        };
+    }
+    const problem = jurisdictionSlugProblem(ref.slice(JURISDICTION_REF_NAMESPACE.length));
+    return problem === null ? null : { scope: JurisdictionRefProblemScope.SLUG, message: `jurisdiction ref ${ref}: ${problem}` };
+}
+/** `jurisdiction:<slug>`, with the slug held to the same rule as a declared operating jurisdiction. */
+export const JurisdictionRefSchema = z
+    .string()
+    .trim()
+    .superRefine((ref, context) => {
+    const problem = jurisdictionRefProblem(ref);
+    if (problem !== null) {
+        context.addIssue({ code: 'custom', message: problem.message });
+    }
+});
 /**
  * One jurisdiction this application operates in, and why it reaches the product.
  *

package/dist/esm/compliance/privacy/operating-jurisdictions.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"operating-jurisdictions.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/compliance/privacy/operating-jurisdictions.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC;KACpC,MAAM,EAAE;KACR,IAAI,EAAE;KACN,KAAK,CACJ,8BAA8B,EAC9B,gGAAgG;MAC5F,gGAAgG;MAChG,mDAAmD,CACxD,CAAC;AAGJ;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,YAAY,CAAC;IACxD,gBAAgB,EAAE,sBAAsB;IACxC,+GAA+G;IAC/G,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAChC,CAAC,CAAC;AAGH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,uCAAuC,GAAG,CAAC;KACrD,YAAY,CAAC;IACZ,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CAC3D,CAAC;KACD,WAAW,CAAC,CAAC,WAAW,EAAE,OAAO,EAAE,EAAE;IACpC,MAAM,KAAK,GAAG,WAAW,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAC/E,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC;IAChF,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,OAAO,CAAC,QAAQ,CAAC;YACf,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,eAAe,CAAC;YACvB,OAAO,EACL,gBAAgB,CAAC,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,gCAAgC;kBAC5G,+FAA+F;SACpG,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC,CAAC;AAGL;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAgD,MAAM,CAAC,MAAM,CAAC;IACjG,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC;QAChB,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;QAClF,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;KAC7E,CAAC;CACH,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAa,EAAE,QAAgB;IACrE,IAAI,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACpC,mHAAmH;IACnH,IAAI,QAAQ,CAAC,UAAU,CAAC,GAAG,KAAK,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAClD,OAAO,CAAC,wBAAwB,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CACjD,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,QAAQ,IAAI,QAAQ,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,CAAC,CACrE,CAAC;AACJ,CAAC","sourcesContent":["import { z } from 'zod';\n\n/**\n * WHERE this application operates, as the one source every compliance surface reads (issue #229).\n *\n * ## The hole this closes\n *\n * Measured 2026-09-02: nothing in application configuration said which jurisdictions an application\n * reaches. `jurisdiction` appeared only as prose, as the Art. 27 origin of a representative, and as\n * `jurisdictionRefs` on a governed-document release. The assurance programme's `jurisdictionSlugs`\n * were free text supplied per run BY THE PRODUCING MODEL — which is the opposite of a source: it is\n * unverifiable, it can differ between two runs of the same application, and nothing downstream could\n * disagree with it.\n *\n * ## Why a sibling of `operatorComplianceIdentity` rather than a field inside it\n *\n * Both describe legal posture, so folding this in is tempting. It is the wrong shape for one reason\n * that outranks the tidiness: that schema is all-or-nothing inside, so a jurisdiction could not be\n * recorded until the lawful bases were settled with counsel. Where you sell is known long before why\n * you may process — and issue #228 exists precisely because filling the entity must never block.\n *\n * Keeping them siblings means each is answerable the day it is known.\n *\n * ## Why an open slug and not an enum\n *\n * A jurisdiction is a genuinely open identifier: an application may operate anywhere, and an enum\n * would have to be widened before an operator could state the truth about their own product. That is\n * the \"genuinely open app/provider/resource identifier\" exemption in the semantic-literal rule, not a\n * shortcut around it. The shape is constrained; the membership is not.\n *\n * The framework's ability to KNOW what a declared jurisdiction requires is a separate question, and\n * a deliberately visible one — see {@link JURISDICTION_CONTAINMENT} and the coverage report that\n * consumes it. An application may always declare where it operates; Wildo says plainly where it has\n * nothing to offer.\n */\nexport const JurisdictionSlugSchema = z\n  .string()\n  .trim()\n  .regex(\n    /^[a-z]{2}(-[a-z0-9]{1,8})?$/u,\n    'a jurisdiction slug is an ISO 3166-1 alpha-2 country code, a supranational code such as \"eu\", '\n      + 'optionally with a subdivision suffix such as \"us-ca\" — lowercase, because a slug that differs '\n      + 'only by case is a second identifier for one place',\n  );\nexport type JurisdictionSlug = z.infer<typeof JurisdictionSlugSchema>;\n\n/**\n * One jurisdiction this application operates in, and why it reaches the product.\n *\n * `basis` is REQUIRED, and it is the half that makes the declaration mean anything — the same\n * argument the sibling schemas make for `assessmentNote` on a legitimate-interests basis and for\n * `gatedProcessing` on a consent gate. \"eu\" alone does not say whether the operator is established\n * there, sells there, or merely holds data about people there, and those imply different obligations.\n *\n * It is free prose deliberately. Nothing structured exists to key it to, and inventing a closed\n * vocabulary of reasons would be a legal taxonomy nobody reviewed.\n */\nexport const OperatingJurisdictionSchema = z.strictObject({\n  jurisdictionSlug: JurisdictionSlugSchema,\n  /** Why this jurisdiction reaches the product — \"customers established here\", \"data subjects resident here\". */\n  basis: z.string().trim().min(1),\n});\nexport type OperatingJurisdiction = z.infer<typeof OperatingJurisdictionSchema>;\n\n/**\n * The jurisdictions this application operates in.\n *\n * ## Absent is UNDECLARED, and an empty list is not offered\n *\n * The sibling `clientStorage` inventory distinguishes absent (\"not inventoried\") from an empty array\n * (\"this surface sets nothing\"), because there both are meaningful. Here only one is: every product\n * operates somewhere, so an empty list would be a claim nobody could mean. `min(1)` therefore refuses\n * it, and the whole declaration stays optional at the configuration level — absence is the honest\n * \"nobody has answered\", and every consumer must render it as that rather than as \"nowhere\".\n */\nexport const ApplicationOperatingJurisdictionsSchema = z\n  .strictObject({\n    jurisdictions: z.array(OperatingJurisdictionSchema).min(1),\n  })\n  .superRefine((declaration, context) => {\n    const slugs = declaration.jurisdictions.map((entry) => entry.jurisdictionSlug);\n    const duplicates = slugs.filter((slug, index) => slugs.indexOf(slug) !== index);\n    if (duplicates.length > 0) {\n      context.addIssue({\n        code: 'custom',\n        path: ['jurisdictions'],\n        message:\n          `jurisdiction ${[...new Set(duplicates)].map((slug) => `\"${slug}\"`).join(', ')} is declared more than once — `\n          + 'one place has one basis, and two entries would let a document cite whichever suits the clause',\n      });\n    }\n  });\nexport type ApplicationOperatingJurisdictions = z.infer<typeof ApplicationOperatingJurisdictionsSchema>;\n\n/**\n * Which jurisdictions a broader one contains, so a source addressing the broader one answers for them.\n *\n * Without this, an application declaring `fr` would be reported as uncovered while the GDPR source\n * plainly reaches it — over-warning, which is the failure mode that trains a reader to skim past the\n * warnings that matter. Subdivisions need no table: `us-ca` is contained by `us` by construction, and\n * that rule is applied in code rather than enumerated here.\n *\n * ⚠️ EU membership is a legal fact with a review trigger, not a convenience list: it changes when a\n * state accedes or withdraws, and it has done both. Verified against the 27 members as of 2026-09-02.\n * Nothing derives it, so a change is a deliberate edit here.\n */\nexport const JURISDICTION_CONTAINMENT: Readonly<Record<string, readonly string[]>> = Object.freeze({\n  eu: Object.freeze([\n    'at', 'be', 'bg', 'cy', 'cz', 'de', 'dk', 'ee', 'es', 'fi', 'fr', 'gr', 'hr', 'hu',\n    'ie', 'it', 'lt', 'lu', 'lv', 'mt', 'nl', 'pl', 'pt', 'ro', 'se', 'si', 'sk',\n  ]),\n});\n\n/**\n * Does a source addressing `reach` answer for an application operating in `declared`?\n *\n * Three ways, and the order is deliberate — exact first, because it is the common case and the other\n * two are refinements of it.\n */\nexport function jurisdictionReachCovers(reach: string, declared: string): boolean {\n  if (reach === declared) return true;\n  // A source addressing the whole of `us` answers for `us-ca`; one addressing only `us-ca` does not answer for `us`.\n  if (declared.startsWith(`${reach}-`)) return true;\n  return (JURISDICTION_CONTAINMENT[reach] ?? []).some(\n    (member) => member === declared || declared.startsWith(`${member}-`),\n  );\n}\n"]}
+{"version":3,"file":"operating-jurisdictions.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/compliance/privacy/operating-jurisdictions.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\n\n/**\n * WHERE this application operates, as the one source every compliance surface reads (issue #229).\n *\n * ## The hole this closes\n *\n * Measured 2026-09-02: nothing in application configuration said which jurisdictions an application\n * reaches. `jurisdiction` appeared only as prose, as the Art. 27 origin of a representative, and as\n * `jurisdictionRefs` on a governed-document release. The assurance programme's `jurisdictionSlugs`\n * were free text supplied per run BY THE PRODUCING MODEL — which is the opposite of a source: it is\n * unverifiable, it can differ between two runs of the same application, and nothing downstream could\n * disagree with it.\n *\n * ## Why a sibling of `operatorComplianceIdentity` rather than a field inside it\n *\n * Both describe legal posture, so folding this in is tempting. It is the wrong shape for one reason\n * that outranks the tidiness: that schema is all-or-nothing inside, so a jurisdiction could not be\n * recorded until the lawful bases were settled with counsel. Where you sell is known long before why\n * you may process — and issue #228 exists precisely because filling the entity must never block.\n *\n * Keeping them siblings means each is answerable the day it is known.\n *\n * ## Why an open slug and not an enum\n *\n * A jurisdiction is a genuinely open identifier: an application may operate anywhere, and an enum\n * would have to be widened before an operator could state the truth about their own product. That is\n * the \"genuinely open app/provider/resource identifier\" exemption in the semantic-literal rule, not a\n * shortcut around it. The shape is constrained; the membership is not.\n *\n * The framework's ability to KNOW what a declared jurisdiction requires is a separate question, and\n * a deliberately visible one — see {@link JURISDICTION_CONTAINMENT} and the coverage report that\n * consumes it. An application may always declare where it operates; Wildo says plainly where it has\n * nothing to offer.\n */\nconst JURISDICTION_SLUG_SHAPE = /^[a-z]{2}(-[a-z0-9]{1,8})?$/u;\n\nconst JURISDICTION_SLUG_SHAPE_MESSAGE =\n  'a jurisdiction slug is an ISO 3166-1 alpha-2 country code, a supranational code such as \"eu\", '\n  + 'optionally with a regime or subdivision suffix such as \"us-ca\" — lowercase, because a slug that '\n  + 'differs only by case is a second identifier for one place';\n\n/**\n * The CANONICAL form of a region subtag, or `null` when the subtag is not well-formed.\n *\n * Shape alone cannot separate `gb` from `uk`: both are two lowercase letters, both name the same\n * place, and only one is the ISO 3166-1 alpha-2 code. So the shape check is answered by the regex\n * and IDENTITY is answered here, by the same authority the publication validator already uses for\n * the locale half of a variant — `Intl.getCanonicalLocales`, which resolves the CLDR alias table.\n *\n * A data file was rejected. An enumerated country list is a legal fact with a review trigger (the\n * one table this file does keep, {@link JURISDICTION_CONTAINMENT}, says so and is 27 rows), and a\n * second one covering every country on earth would rot with nobody watching. `Intl` ships the table\n * with the runtime and updates with it.\n *\n * What this deliberately does NOT catch: a well-formed but unassigned code (`qq`, `aa`) canonicalises\n * to itself and passes. Those are not authoring mistakes anybody makes; `uk` demonstrably is — it is\n * in this repository's own tests and prose.\n */\nfunction canonicalRegionSubtag(subtag: string): string | null {\n  const requested = `und-${subtag.toUpperCase()}`;\n  try {\n    const [canonical] = Intl.getCanonicalLocales(requested);\n    return canonical === undefined ? null : canonical.slice('und-'.length);\n  } catch {\n    return null;\n  }\n}\n\n/**\n * What is wrong with `slug` as a jurisdiction slug, or `null` when nothing is.\n *\n * Exported as a FUNCTION rather than only as a schema because the consumers that matter do not parse\n * — the governed-document publication validator and the `_core` compliance-document candidate\n * validator both emit their own typed issue records, and routing them through a Zod error to recover\n * a message is how two surfaces come to disagree about what a jurisdiction is. One rule, three\n * readers.\n */\nexport function jurisdictionSlugProblem(slug: string): string | null {\n  if (!JURISDICTION_SLUG_SHAPE.test(slug)) {\n    return `${JURISDICTION_SLUG_SHAPE_MESSAGE} — received \"${slug}\"`;\n  }\n  const [root] = slug.split('-');\n  const canonical = canonicalRegionSubtag(root!);\n  if (canonical === null) {\n    return `\"${root}\" is not a well-formed region code`;\n  }\n  if (canonical.toLowerCase() !== root) {\n    return `\"${root}\" is an alias for \"${canonical.toLowerCase()}\" — use the canonical code, or two slugs are one place`;\n  }\n  return null;\n}\n\nexport const JurisdictionSlugSchema = z\n  .string()\n  .trim()\n  .superRefine((slug, context) => {\n    const problem = jurisdictionSlugProblem(slug);\n    if (problem !== null) {\n      context.addIssue({ code: 'custom', message: problem });\n    }\n  });\nexport type JurisdictionSlug = z.infer<typeof JurisdictionSlugSchema>;\n\n/**\n * The namespace every jurisdiction REFERENCE carries.\n *\n * A ref is `jurisdiction:<slug>`, and both halves are checked, because checking only the namespace is\n * what let `jurisdiction:united-kingdom` — a value {@link JurisdictionSlugSchema} would refuse\n * outright — sit in a landed application specification beside that same application's configuration\n * declaring `gb`.\n */\nexport const JURISDICTION_REF_NAMESPACE = 'jurisdiction:';\n\n/** Which half of a `jurisdiction:<slug>` ref is wrong. The two are separate failures with separate remedies. */\nexport enum JurisdictionRefProblemScope {\n  /** The ref is not in the `jurisdiction:` namespace, so it resolves against a different vocabulary entirely. */\n  NAMESPACE = 'NAMESPACE',\n  /** The namespace is right and the slug is not a jurisdiction. */\n  SLUG = 'SLUG',\n}\n\nexport interface JurisdictionRefProblem {\n  readonly scope: JurisdictionRefProblemScope;\n  readonly message: string;\n}\n\n/** What is wrong with `ref` as a `jurisdiction:<slug>` reference, or `null` when nothing is. */\nexport function jurisdictionRefProblem(ref: string): JurisdictionRefProblem | null {\n  if (!ref.startsWith(JURISDICTION_REF_NAMESPACE)) {\n    return {\n      scope: JurisdictionRefProblemScope.NAMESPACE,\n      message: `jurisdiction ref ${ref} must use the ${JURISDICTION_REF_NAMESPACE} namespace`,\n    };\n  }\n  const problem = jurisdictionSlugProblem(ref.slice(JURISDICTION_REF_NAMESPACE.length));\n  return problem === null ? null : { scope: JurisdictionRefProblemScope.SLUG, message: `jurisdiction ref ${ref}: ${problem}` };\n}\n\n/** `jurisdiction:<slug>`, with the slug held to the same rule as a declared operating jurisdiction. */\nexport const JurisdictionRefSchema = z\n  .string()\n  .trim()\n  .superRefine((ref, context) => {\n    const problem = jurisdictionRefProblem(ref);\n    if (problem !== null) {\n      context.addIssue({ code: 'custom', message: problem.message });\n    }\n  });\n\n/**\n * One jurisdiction this application operates in, and why it reaches the product.\n *\n * `basis` is REQUIRED, and it is the half that makes the declaration mean anything — the same\n * argument the sibling schemas make for `assessmentNote` on a legitimate-interests basis and for\n * `gatedProcessing` on a consent gate. \"eu\" alone does not say whether the operator is established\n * there, sells there, or merely holds data about people there, and those imply different obligations.\n *\n * It is free prose deliberately. Nothing structured exists to key it to, and inventing a closed\n * vocabulary of reasons would be a legal taxonomy nobody reviewed.\n */\nexport const OperatingJurisdictionSchema = z.strictObject({\n  jurisdictionSlug: JurisdictionSlugSchema,\n  /** Why this jurisdiction reaches the product — \"customers established here\", \"data subjects resident here\". */\n  basis: z.string().trim().min(1),\n});\nexport type OperatingJurisdiction = z.infer<typeof OperatingJurisdictionSchema>;\n\n/**\n * The jurisdictions this application operates in.\n *\n * ## Absent is UNDECLARED, and an empty list is not offered\n *\n * The sibling `clientStorage` inventory distinguishes absent (\"not inventoried\") from an empty array\n * (\"this surface sets nothing\"), because there both are meaningful. Here only one is: every product\n * operates somewhere, so an empty list would be a claim nobody could mean. `min(1)` therefore refuses\n * it, and the whole declaration stays optional at the configuration level — absence is the honest\n * \"nobody has answered\", and every consumer must render it as that rather than as \"nowhere\".\n */\nexport const ApplicationOperatingJurisdictionsSchema = z\n  .strictObject({\n    jurisdictions: z.array(OperatingJurisdictionSchema).min(1),\n  })\n  .superRefine((declaration, context) => {\n    const slugs = declaration.jurisdictions.map((entry) => entry.jurisdictionSlug);\n    const duplicates = slugs.filter((slug, index) => slugs.indexOf(slug) !== index);\n    if (duplicates.length > 0) {\n      context.addIssue({\n        code: 'custom',\n        path: ['jurisdictions'],\n        message:\n          `jurisdiction ${[...new Set(duplicates)].map((slug) => `\"${slug}\"`).join(', ')} is declared more than once — `\n          + 'one place has one basis, and two entries would let a document cite whichever suits the clause',\n      });\n    }\n  });\nexport type ApplicationOperatingJurisdictions = z.infer<typeof ApplicationOperatingJurisdictionsSchema>;\n\n/**\n * Which jurisdictions a broader one contains, so a source addressing the broader one answers for them.\n *\n * Without this, an application declaring `fr` would be reported as uncovered while the GDPR source\n * plainly reaches it — over-warning, which is the failure mode that trains a reader to skim past the\n * warnings that matter. Subdivisions need no table: `us-ca` is contained by `us` by construction, and\n * that rule is applied in code rather than enumerated here.\n *\n * ⚠️ EU membership is a legal fact with a review trigger, not a convenience list: it changes when a\n * state accedes or withdraws, and it has done both. Verified against the 27 members as of 2026-09-02.\n * Nothing derives it, so a change is a deliberate edit here.\n */\nexport const JURISDICTION_CONTAINMENT: Readonly<Record<string, readonly string[]>> = Object.freeze({\n  eu: Object.freeze([\n    'at', 'be', 'bg', 'cy', 'cz', 'de', 'dk', 'ee', 'es', 'fi', 'fr', 'gr', 'hr', 'hu',\n    'ie', 'it', 'lt', 'lu', 'lv', 'mt', 'nl', 'pl', 'pt', 'ro', 'se', 'si', 'sk',\n  ]),\n});\n\n/**\n * Does a source addressing `reach` answer for an application operating in `declared`?\n *\n * Three ways, and the order is deliberate — exact first, because it is the common case and the other\n * two are refinements of it.\n */\nexport function jurisdictionReachCovers(reach: string, declared: string): boolean {\n  if (reach === declared) return true;\n  // A source addressing the whole of `us` answers for `us-ca`; one addressing only `us-ca` does not answer for `us`.\n  if (declared.startsWith(`${reach}-`)) return true;\n  return (JURISDICTION_CONTAINMENT[reach] ?? []).some(\n    (member) => member === declared || declared.startsWith(`${member}-`),\n  );\n}\n"]}

package/dist/esm/compliance/privacy/privacy.shared.schemas.d.ts

@@ -59,6 +59,22 @@ export declare enum PrivacyLevel {
  * Not legal advice. See `.claude/plans/traceability-correlation-id.md` (SD9) for the full analysis
  * and the compliance obligations that attach to each non-`DISABLED` member.
  */
+/**
+ * @wildo_source:part:start saas.models.privacy.client-instance-id-scope facet:layer:shared facet:audience:app-developer
+ *
+ * Whether the application identifies a browser INSTALL across visits, declared as
+ * `compliance.clientInstanceIdScope`.
+ *
+ * It lives on `compliance` rather than beside the observability settings because it is a PRIVACY
+ * decision, and on the SHARED config because both halves must obey one authored value: the frontend
+ * decides whether to mint, store and send the id, and the backend independently decides whether to
+ * ingest and record it. Two gates, one source — so an application that never opts in is protected
+ * even if some client sends the header anyway.
+ *
+ * **`DISABLED` is the default**, so the privacy-preserving posture is what you get by doing nothing.
+ * Choosing another member is choosing an obligation, not just a signal: start-up prints the
+ * obligations each opt-in creates.
+ */
 export declare enum ClientInstanceIdScope {
     /**
      * DEFAULT. No client-install identifier is minted, sent, stored, or recorded — and the backend
@@ -82,6 +98,7 @@ export declare enum ClientInstanceIdScope {
      */
     PERSISTENT = "persistent"
 }
+/** @wildo_source:part:end saas.models.privacy.client-instance-id-scope */
 export declare const AnonymousUserPrivacySchema: z.ZodObject<{
     dataProcessingConsent: z.ZodDefault<z.ZodEnum<typeof DataProcessingConsent>>;
 }, z.core.$strip>;

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

@@ -1 +1 @@
-{"version":3,"file":"privacy.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/compliance/privacy/privacy.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,oBAAY,qBAAqB;IAC/B,MAAM,WAAW,CAAE,sBAAsB;IACzC,oBAAoB,yBAAyB,CAAE,uDAAuD;IACtG,YAAY,iBAAiB,CAAE,mCAAmC;IAClE,OAAO,YAAY;CACpB;AAED,oBAAY,6BAA6B;IACvC,MAAM,WAAW,CAAE,sBAAsB;IACzC,oBAAoB,yBAAyB,CAAE,uDAAuD;IACtG,OAAO,YAAY;CACpB;AAED,oBAAY,qBAAqB;IAC/B,IAAI,SAAS;IACb,KAAK,UAAU;IACf,SAAS,cAAc;IACvB,SAAS,cAAc;IACvB,IAAI,SAAS;CACd;AAED,oBAAY,YAAY;IACtB,OAAO,YAAY,CAAE,0BAA0B;IAC/C,QAAQ,aAAa,CAAE,2BAA2B;IAClD,QAAQ,aAAa;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,oBAAY,qBAAqB;IAC/B;;;;;OAKG;IACH,QAAQ,aAAa;IACrB;;;;OAIG;IACH,OAAO,YAAY;IACnB;;;;;;OAMG;IACH,UAAU,eAAe;CAC1B;AAED,eAAO,MAAM,0BAA0B;;iBAErC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,eAAO,MAAM,2BAA2B;;iBAEtC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,iBAAiB;;;iBAiB5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}
+{"version":3,"file":"privacy.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/compliance/privacy/privacy.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,oBAAY,qBAAqB;IAC/B,MAAM,WAAW,CAAE,sBAAsB;IACzC,oBAAoB,yBAAyB,CAAE,uDAAuD;IACtG,YAAY,iBAAiB,CAAE,mCAAmC;IAClE,OAAO,YAAY;CACpB;AAED,oBAAY,6BAA6B;IACvC,MAAM,WAAW,CAAE,sBAAsB;IACzC,oBAAoB,yBAAyB,CAAE,uDAAuD;IACtG,OAAO,YAAY;CACpB;AAED,oBAAY,qBAAqB;IAC/B,IAAI,SAAS;IACb,KAAK,UAAU;IACf,SAAS,cAAc;IACvB,SAAS,cAAc;IACvB,IAAI,SAAS;CACd;AAED,oBAAY,YAAY;IACtB,OAAO,YAAY,CAAE,0BAA0B;IAC/C,QAAQ,aAAa,CAAE,2BAA2B;IAClD,QAAQ,aAAa;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;;;;;;;;;;;;;;;GAeG;AACH,oBAAY,qBAAqB;IAC/B;;;;;OAKG;IACH,QAAQ,aAAa;IACrB;;;;OAIG;IACH,OAAO,YAAY;IACnB;;;;;;OAMG;IACH,UAAU,eAAe;CAC1B;AACD,0EAA0E;AAE1E,eAAO,MAAM,0BAA0B;;iBAKrC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,eAAO,MAAM,2BAA2B;;iBAKtC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,iBAAiB;;;iBAuB5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/esm/compliance/privacy/privacy.shared.schemas.js

@@ -63,6 +63,22 @@ export var PrivacyLevel;
  * Not legal advice. See `.claude/plans/traceability-correlation-id.md` (SD9) for the full analysis
  * and the compliance obligations that attach to each non-`DISABLED` member.
  */
+/**
+ * @wildo_source:part:start saas.models.privacy.client-instance-id-scope facet:layer:shared facet:audience:app-developer
+ *
+ * Whether the application identifies a browser INSTALL across visits, declared as
+ * `compliance.clientInstanceIdScope`.
+ *
+ * It lives on `compliance` rather than beside the observability settings because it is a PRIVACY
+ * decision, and on the SHARED config because both halves must obey one authored value: the frontend
+ * decides whether to mint, store and send the id, and the backend independently decides whether to
+ * ingest and record it. Two gates, one source — so an application that never opts in is protected
+ * even if some client sends the header anyway.
+ *
+ * **`DISABLED` is the default**, so the privacy-preserving posture is what you get by doing nothing.
+ * Choosing another member is choosing an obligation, not just a signal: start-up prints the
+ * obligations each opt-in creates.
+ */
 export var ClientInstanceIdScope;
 (function (ClientInstanceIdScope) {
     /**
@@ -87,11 +103,14 @@ export var ClientInstanceIdScope;
      */
     ClientInstanceIdScope["PERSISTENT"] = "persistent";
 })(ClientInstanceIdScope || (ClientInstanceIdScope = {}));
+/** @wildo_source:part:end saas.models.privacy.client-instance-id-scope */
 export const AnonymousUserPrivacySchema = z.object({
-    dataProcessingConsent: z.enum(DataProcessingConsent).default(DataProcessingConsent.BASIC),
+    dataProcessingConsent: z.enum(DataProcessingConsent).default(DataProcessingConsent.BASIC)
+        .describe('The processing this anonymous visitor has agreed to. The application decides what each level permits — the framework stores the decision, it does not attach a fixed meaning to the levels.'),
 });
 export const InboundContactPrivacySchema = z.object({
-    dataProcessingConsent: z.enum(DataProcessingConsent).default(DataProcessingConsent.BASIC),
+    dataProcessingConsent: z.enum(DataProcessingConsent).default(DataProcessingConsent.BASIC)
+        .describe('The processing this lead has agreed to. The application decides what each level permits — the framework stores the decision, it does not attach a fixed meaning to the levels.'),
 });
 export const UserPrivacySchema = z.object({
     // `.isAuditEvidence()` on these two, and deliberately NOT on the block that contains them.
@@ -108,7 +127,11 @@ export const UserPrivacySchema = z.object({
     // decision and must leave a trail naming the previous and resulting value. Reached today by the
     // preferences RESET, the generic UPDATE, and `update_privacy`, all of which route through the
     // same emission point, so no verb can change consent without a record.
-    dataProcessingConsent: z.enum(DataProcessingConsent).default(DataProcessingConsent.BASIC).isAuditEvidence(),
-    privacyLevel: z.enum(PrivacyLevel).default(PrivacyLevel.STANDARD).isAuditEvidence(),
+    dataProcessingConsent: z.enum(DataProcessingConsent).default(DataProcessingConsent.BASIC)
+        .describe('The processing this person has agreed to. It is the subject\'s own decision and only they (or an administrator acting for them) change it. The application decides what each level permits — the framework stores the decision and records every change, it does not attach a fixed meaning to the levels.')
+        .isAuditEvidence(),
+    privacyLevel: z.enum(PrivacyLevel).default(PrivacyLevel.STANDARD)
+        .describe('How much this person has agreed the application may collect about them, alongside the processing consent. The application decides what each level permits.')
+        .isAuditEvidence(),
 });
 //# sourceMappingURL=privacy.shared.schemas.js.map

package/dist/esm/compliance/privacy/privacy.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"privacy.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/compliance/privacy/privacy.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,MAAM,CAAN,IAAY,qBAKX;AALD,WAAY,qBAAqB;IAC/B,0CAAiB,CAAA;IACjB,sEAA6C,CAAA;IAC7C,sDAA6B,CAAA;IAC7B,4CAAmB,CAAA;AACrB,CAAC,EALW,qBAAqB,KAArB,qBAAqB,QAKhC;AAED,MAAM,CAAN,IAAY,6BAIX;AAJD,WAAY,6BAA6B;IACvC,kDAAiB,CAAA;IACjB,8EAA6C,CAAA;IAC7C,oDAAmB,CAAA;AACrB,CAAC,EAJW,6BAA6B,KAA7B,6BAA6B,QAIxC;AAED,MAAM,CAAN,IAAY,qBAMX;AAND,WAAY,qBAAqB;IAC/B,sCAAa,CAAA;IACb,wCAAe,CAAA;IACf,gDAAuB,CAAA;IACvB,gDAAuB,CAAA;IACvB,sCAAa,CAAA;AACf,CAAC,EANW,qBAAqB,KAArB,qBAAqB,QAMhC;AAED,MAAM,CAAN,IAAY,YAIX;AAJD,WAAY,YAAY;IACtB,mCAAmB,CAAA;IACnB,qCAAqB,CAAA;IACrB,qCAAqB,CAAA;AACvB,CAAC,EAJW,YAAY,KAAZ,YAAY,QAIvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAN,IAAY,qBAsBX;AAtBD,WAAY,qBAAqB;IAC/B;;;;;OAKG;IACH,8CAAqB,CAAA;IACrB;;;;OAIG;IACH,4CAAmB,CAAA;IACnB;;;;;;OAMG;IACH,kDAAyB,CAAA;AAC3B,CAAC,EAtBW,qBAAqB,KAArB,qBAAqB,QAsBhC;AAED,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,qBAAqB,EAAE,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC,OAAO,CAAC,qBAAqB,CAAC,KAAK,CAAC;CAC1F,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,qBAAqB,EAAE,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC,OAAO,CAAC,qBAAqB,CAAC,KAAK,CAAC;CAC1F,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,2FAA2F;IAC3F,EAAE;IACF,yFAAyF;IACzF,4FAA4F;IAC5F,yFAAyF;IACzF,6EAA6E;IAC7E,EAAE;IACF,8FAA8F;IAC9F,mGAAmG;IACnG,EAAE;IACF,4FAA4F;IAC5F,gGAAgG;IAChG,8FAA8F;IAC9F,uEAAuE;IACvE,qBAAqB,EAAE,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC,OAAO,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC,eAAe,EAAE;IAC3G,YAAY,EAAE,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,eAAe,EAAE;CACpF,CAAC,CAAC","sourcesContent":["/**\n * Privacy Shared Schemas\n *\n * Privacy-related schemas and enums for user data management\n */\n\nimport { z } from \"zod\";\n\n/**\n * Profile Visibility Enum\n *\n * Controls who can see a user's profile information\n */\nexport enum UserProfileVisibility {\n  PUBLIC = \"public\", // Visible to everyone\n  APPLICATION_INTERNAL = \"application_internal\", // Visible within application, for connected users only\n  ORGANIZATION = \"organization\", // Visible within organization only\n  PRIVATE = \"private\", // Visible to user only\n}\n\nexport enum OrganizationProfileVisibility {\n  PUBLIC = \"public\", // Visible to everyone\n  APPLICATION_INTERNAL = \"application_internal\", // Visible within application, for connected users only\n  PRIVATE = \"private\", // Visible to user only\n}\n\nexport enum DataProcessingConsent {\n  NONE = \"none\",\n  BASIC = \"basic\",\n  ANALYTICS = \"analytics\",\n  MARKETING = \"marketing\",\n  FULL = \"full\",\n}\n\nexport enum PrivacyLevel {\n  MINIMAL = \"minimal\", // Minimum data collection\n  STANDARD = \"standard\", // Standard data collection\n  ENHANCED = \"enhanced\", // Enhanced features with more data\n}\n\n/**\n * Whether — and with what lifetime — this application identifies the CLIENT INSTALL\n * (`clientInstanceId`, sent as `x-client-instance-id` and recorded on the audit row).\n *\n * A `clientInstanceId` answers \"which browser/device install issued this request?\", which the\n * per-request `correlationId` (server-minted, never stored on the device) and `frontendServiceName`\n * (a static per-app build constant) deliberately cannot. It is what lets an investigator group a\n * hostile actor's requests across sessions and logins — genuine security value, and exactly why it\n * needs a policy rather than a default.\n *\n * **This is a closed vocabulary with the OFF state inside it, on purpose.** Modelling it as\n * `{ enabled: boolean; scope: … }` would admit the meaningless `enabled: false, scope: PERSISTENT`\n * state; one enum makes \"off\" and \"how long it lives\" a single, always-coherent decision.\n *\n * **Why the framework refuses to choose for you (Fork D / SD9).** Storing an identifier on the\n * user's terminal equipment engages ePrivacy Directive Art 5(3), whose \"strictly necessary\"\n * exemption the EDPB reads narrowly (Guidelines 2/2023) — and *duration* is itself a\n * misclassification signal, so a long-lived id is the hardest case. GDPR Recital 49 (network and\n * information security as a legitimate interest) is a lawful basis for the PROCESSING but does not\n * remove the ePrivacy STORAGE consent question. Meanwhile NIST SP 800-53 AU-3 / AU-6(3)\n * affirmatively want this correlation capability for audit review. Those pull in opposite\n * directions, and the resolution is jurisdiction- and DPA-specific — so Wildo ships the mechanism\n * OFF and each application decides, with counsel, which member it may lawfully select.\n *\n * Not legal advice. See `.claude/plans/traceability-correlation-id.md` (SD9) for the full analysis\n * and the compliance obligations that attach to each non-`DISABLED` member.\n */\nexport enum ClientInstanceIdScope {\n  /**\n   * DEFAULT. No client-install identifier is minted, sent, stored, or recorded — and the backend\n   * additionally REFUSES an inbound `x-client-instance-id` (fail-closed, so a rogue or misconfigured\n   * client cannot start populating a pseudonymous identifier in an application's retained audit\n   * trail without that application ever opting in).\n   */\n  DISABLED = \"disabled\",\n  /**\n   * Minted per browsing session (`sessionStorage`) — dies when the tab closes and does NOT survive a\n   * restart, so it cannot follow a user across visits. The proportionate choice when the goal is\n   * correlating one session's activity; the easiest to justify as strictly necessary.\n   */\n  SESSION = \"session\",\n  /**\n   * Minted once per browser install (`localStorage`) — survives tab close, restart, logout, and\n   * account switch. The strongest investigative signal (it links pre- and post-authentication\n   * activity, and two accounts used from one machine) and correspondingly the most likely to require\n   * consent. Select only with a recorded legitimate-interest assessment and, where required,\n   * consent-gating.\n   */\n  PERSISTENT = \"persistent\",\n}\n\nexport const AnonymousUserPrivacySchema = z.object({\n  dataProcessingConsent: z.enum(DataProcessingConsent).default(DataProcessingConsent.BASIC),\n});\n\nexport type AnonymousUserPrivacy = z.infer<typeof AnonymousUserPrivacySchema>;\n\nexport const InboundContactPrivacySchema = z.object({\n  dataProcessingConsent: z.enum(DataProcessingConsent).default(DataProcessingConsent.BASIC),\n});\n\nexport type InboundContactPrivacy = z.infer<typeof InboundContactPrivacySchema>;\n\nexport const UserPrivacySchema = z.object({\n  // `.isAuditEvidence()` on these two, and deliberately NOT on the block that contains them.\n  //\n  // Both are the subject's own privacy DECISIONS — the lawful basis for processing and the\n  // collection scope — held as closed vocabularies, so recording their before/after values on\n  // `resource_operation_performed` is exactly the \"mark what decides authority, never what\n  // identifies a person\" rule that governs the same decorator on `UserSchema`.\n  //\n  // Evidence is selected per leaf; the audit walker resolves the dotted path. Governed-document\n  // interactions are separate immutable release-bound records and are never embedded in preferences.\n  //\n  // assurance-control: WILDO.PRIVACY.CONSENT_RECORD — a consent change is a security-relevant\n  // decision and must leave a trail naming the previous and resulting value. Reached today by the\n  // preferences RESET, the generic UPDATE, and `update_privacy`, all of which route through the\n  // same emission point, so no verb can change consent without a record.\n  dataProcessingConsent: z.enum(DataProcessingConsent).default(DataProcessingConsent.BASIC).isAuditEvidence(),\n  privacyLevel: z.enum(PrivacyLevel).default(PrivacyLevel.STANDARD).isAuditEvidence(),\n});\n\nexport type UserPrivacy = z.infer<typeof UserPrivacySchema>;\n"]}
+{"version":3,"file":"privacy.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/compliance/privacy/privacy.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,MAAM,CAAN,IAAY,qBAKX;AALD,WAAY,qBAAqB;IAC/B,0CAAiB,CAAA;IACjB,sEAA6C,CAAA;IAC7C,sDAA6B,CAAA;IAC7B,4CAAmB,CAAA;AACrB,CAAC,EALW,qBAAqB,KAArB,qBAAqB,QAKhC;AAED,MAAM,CAAN,IAAY,6BAIX;AAJD,WAAY,6BAA6B;IACvC,kDAAiB,CAAA;IACjB,8EAA6C,CAAA;IAC7C,oDAAmB,CAAA;AACrB,CAAC,EAJW,6BAA6B,KAA7B,6BAA6B,QAIxC;AAED,MAAM,CAAN,IAAY,qBAMX;AAND,WAAY,qBAAqB;IAC/B,sCAAa,CAAA;IACb,wCAAe,CAAA;IACf,gDAAuB,CAAA;IACvB,gDAAuB,CAAA;IACvB,sCAAa,CAAA;AACf,CAAC,EANW,qBAAqB,KAArB,qBAAqB,QAMhC;AAED,MAAM,CAAN,IAAY,YAIX;AAJD,WAAY,YAAY;IACtB,mCAAmB,CAAA;IACnB,qCAAqB,CAAA;IACrB,qCAAqB,CAAA;AACvB,CAAC,EAJW,YAAY,KAAZ,YAAY,QAIvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAN,IAAY,qBAsBX;AAtBD,WAAY,qBAAqB;IAC/B;;;;;OAKG;IACH,8CAAqB,CAAA;IACrB;;;;OAIG;IACH,4CAAmB,CAAA;IACnB;;;;;;OAMG;IACH,kDAAyB,CAAA;AAC3B,CAAC,EAtBW,qBAAqB,KAArB,qBAAqB,QAsBhC;AACD,0EAA0E;AAE1E,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,qBAAqB,EAAE,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC,OAAO,CAAC,qBAAqB,CAAC,KAAK,CAAC;SACtF,QAAQ,CACP,6LAA6L,CAC9L;CACJ,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,qBAAqB,EAAE,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC,OAAO,CAAC,qBAAqB,CAAC,KAAK,CAAC;SACtF,QAAQ,CACP,gLAAgL,CACjL;CACJ,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,2FAA2F;IAC3F,EAAE;IACF,yFAAyF;IACzF,4FAA4F;IAC5F,yFAAyF;IACzF,6EAA6E;IAC7E,EAAE;IACF,8FAA8F;IAC9F,mGAAmG;IACnG,EAAE;IACF,4FAA4F;IAC5F,gGAAgG;IAChG,8FAA8F;IAC9F,uEAAuE;IACvE,qBAAqB,EAAE,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC,OAAO,CAAC,qBAAqB,CAAC,KAAK,CAAC;SACtF,QAAQ,CACP,4SAA4S,CAC7S;SACA,eAAe,EAAE;IACpB,YAAY,EAAE,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC;SAC9D,QAAQ,CAAC,4JAA4J,CAAC;SACtK,eAAe,EAAE;CACrB,CAAC,CAAC","sourcesContent":["/**\n * Privacy Shared Schemas\n *\n * Privacy-related schemas and enums for user data management\n */\n\nimport { z } from \"zod\";\n\n/**\n * Profile Visibility Enum\n *\n * Controls who can see a user's profile information\n */\nexport enum UserProfileVisibility {\n  PUBLIC = \"public\", // Visible to everyone\n  APPLICATION_INTERNAL = \"application_internal\", // Visible within application, for connected users only\n  ORGANIZATION = \"organization\", // Visible within organization only\n  PRIVATE = \"private\", // Visible to user only\n}\n\nexport enum OrganizationProfileVisibility {\n  PUBLIC = \"public\", // Visible to everyone\n  APPLICATION_INTERNAL = \"application_internal\", // Visible within application, for connected users only\n  PRIVATE = \"private\", // Visible to user only\n}\n\nexport enum DataProcessingConsent {\n  NONE = \"none\",\n  BASIC = \"basic\",\n  ANALYTICS = \"analytics\",\n  MARKETING = \"marketing\",\n  FULL = \"full\",\n}\n\nexport enum PrivacyLevel {\n  MINIMAL = \"minimal\", // Minimum data collection\n  STANDARD = \"standard\", // Standard data collection\n  ENHANCED = \"enhanced\", // Enhanced features with more data\n}\n\n/**\n * Whether — and with what lifetime — this application identifies the CLIENT INSTALL\n * (`clientInstanceId`, sent as `x-client-instance-id` and recorded on the audit row).\n *\n * A `clientInstanceId` answers \"which browser/device install issued this request?\", which the\n * per-request `correlationId` (server-minted, never stored on the device) and `frontendServiceName`\n * (a static per-app build constant) deliberately cannot. It is what lets an investigator group a\n * hostile actor's requests across sessions and logins — genuine security value, and exactly why it\n * needs a policy rather than a default.\n *\n * **This is a closed vocabulary with the OFF state inside it, on purpose.** Modelling it as\n * `{ enabled: boolean; scope: … }` would admit the meaningless `enabled: false, scope: PERSISTENT`\n * state; one enum makes \"off\" and \"how long it lives\" a single, always-coherent decision.\n *\n * **Why the framework refuses to choose for you (Fork D / SD9).** Storing an identifier on the\n * user's terminal equipment engages ePrivacy Directive Art 5(3), whose \"strictly necessary\"\n * exemption the EDPB reads narrowly (Guidelines 2/2023) — and *duration* is itself a\n * misclassification signal, so a long-lived id is the hardest case. GDPR Recital 49 (network and\n * information security as a legitimate interest) is a lawful basis for the PROCESSING but does not\n * remove the ePrivacy STORAGE consent question. Meanwhile NIST SP 800-53 AU-3 / AU-6(3)\n * affirmatively want this correlation capability for audit review. Those pull in opposite\n * directions, and the resolution is jurisdiction- and DPA-specific — so Wildo ships the mechanism\n * OFF and each application decides, with counsel, which member it may lawfully select.\n *\n * Not legal advice. See `.claude/plans/traceability-correlation-id.md` (SD9) for the full analysis\n * and the compliance obligations that attach to each non-`DISABLED` member.\n */\n/**\n * @wildo_source:part:start saas.models.privacy.client-instance-id-scope facet:layer:shared facet:audience:app-developer\n *\n * Whether the application identifies a browser INSTALL across visits, declared as\n * `compliance.clientInstanceIdScope`.\n *\n * It lives on `compliance` rather than beside the observability settings because it is a PRIVACY\n * decision, and on the SHARED config because both halves must obey one authored value: the frontend\n * decides whether to mint, store and send the id, and the backend independently decides whether to\n * ingest and record it. Two gates, one source — so an application that never opts in is protected\n * even if some client sends the header anyway.\n *\n * **`DISABLED` is the default**, so the privacy-preserving posture is what you get by doing nothing.\n * Choosing another member is choosing an obligation, not just a signal: start-up prints the\n * obligations each opt-in creates.\n */\nexport enum ClientInstanceIdScope {\n  /**\n   * DEFAULT. No client-install identifier is minted, sent, stored, or recorded — and the backend\n   * additionally REFUSES an inbound `x-client-instance-id` (fail-closed, so a rogue or misconfigured\n   * client cannot start populating a pseudonymous identifier in an application's retained audit\n   * trail without that application ever opting in).\n   */\n  DISABLED = \"disabled\",\n  /**\n   * Minted per browsing session (`sessionStorage`) — dies when the tab closes and does NOT survive a\n   * restart, so it cannot follow a user across visits. The proportionate choice when the goal is\n   * correlating one session's activity; the easiest to justify as strictly necessary.\n   */\n  SESSION = \"session\",\n  /**\n   * Minted once per browser install (`localStorage`) — survives tab close, restart, logout, and\n   * account switch. The strongest investigative signal (it links pre- and post-authentication\n   * activity, and two accounts used from one machine) and correspondingly the most likely to require\n   * consent. Select only with a recorded legitimate-interest assessment and, where required,\n   * consent-gating.\n   */\n  PERSISTENT = \"persistent\",\n}\n/** @wildo_source:part:end saas.models.privacy.client-instance-id-scope */\n\nexport const AnonymousUserPrivacySchema = z.object({\n  dataProcessingConsent: z.enum(DataProcessingConsent).default(DataProcessingConsent.BASIC)\n    .describe(\n      'The processing this anonymous visitor has agreed to. The application decides what each level permits — the framework stores the decision, it does not attach a fixed meaning to the levels.',\n    ),\n});\n\nexport type AnonymousUserPrivacy = z.infer<typeof AnonymousUserPrivacySchema>;\n\nexport const InboundContactPrivacySchema = z.object({\n  dataProcessingConsent: z.enum(DataProcessingConsent).default(DataProcessingConsent.BASIC)\n    .describe(\n      'The processing this lead has agreed to. The application decides what each level permits — the framework stores the decision, it does not attach a fixed meaning to the levels.',\n    ),\n});\n\nexport type InboundContactPrivacy = z.infer<typeof InboundContactPrivacySchema>;\n\nexport const UserPrivacySchema = z.object({\n  // `.isAuditEvidence()` on these two, and deliberately NOT on the block that contains them.\n  //\n  // Both are the subject's own privacy DECISIONS — the lawful basis for processing and the\n  // collection scope — held as closed vocabularies, so recording their before/after values on\n  // `resource_operation_performed` is exactly the \"mark what decides authority, never what\n  // identifies a person\" rule that governs the same decorator on `UserSchema`.\n  //\n  // Evidence is selected per leaf; the audit walker resolves the dotted path. Governed-document\n  // interactions are separate immutable release-bound records and are never embedded in preferences.\n  //\n  // assurance-control: WILDO.PRIVACY.CONSENT_RECORD — a consent change is a security-relevant\n  // decision and must leave a trail naming the previous and resulting value. Reached today by the\n  // preferences RESET, the generic UPDATE, and `update_privacy`, all of which route through the\n  // same emission point, so no verb can change consent without a record.\n  dataProcessingConsent: z.enum(DataProcessingConsent).default(DataProcessingConsent.BASIC)\n    .describe(\n      'The processing this person has agreed to. It is the subject\\'s own decision and only they (or an administrator acting for them) change it. The application decides what each level permits — the framework stores the decision and records every change, it does not attach a fixed meaning to the levels.',\n    )\n    .isAuditEvidence(),\n  privacyLevel: z.enum(PrivacyLevel).default(PrivacyLevel.STANDARD)\n    .describe('How much this person has agreed the application may collect about them, alongside the processing consent. The application decides what each level permits.')\n    .isAuditEvidence(),\n});\n\nexport type UserPrivacy = z.infer<typeof UserPrivacySchema>;\n"]}

package/dist/esm/compliance/privacy/redaction.shared.schemas.d.ts

@@ -1,48 +1,101 @@
 import { z } from "zod";
 /**
- * Field-treatment vocabulary, shared by two consumers (D9 — "one authority axis"):
- *  - flow-actors `redactionRules` (log / response redaction), and
- *  - the impersonalization `.impersonalizeWith()` per-field treatment (erasure scrub —
- *    scrub a person out of a record that must be retained).
- *
- * Adding members is additive for both consumers (no exhaustive switches read it).
- * `KEEP` is meaningful only for impersonalization (never scrub this field) — the
- * never-scrub scope-FK floor relies on it. Reversible tokenization is intentionally
- * NOT in v1 (D6 = irreversible); `ENCRYPT` remains the existing reversible option, and a
- * dedicated `TOKENIZE` member can be added additively if a vault-backed mode ships later.
+ * @wildo_source:part:start saas.models.privacy.redaction-treatments facet:layer:shared facet:audience:app-developer
+ *
+ * How one field's value is replaced when it is redacted or scrubbed.
+ *
+ * Imported from `@wildo-ai/saas-models`.
+ *
+ * ## Two consumers, and only one of them accepts every member
+ *
+ * | consumer | what it does | accepts |
+ * |---|---|---|
+ * | flow-actors `redactionRules` | hides a value in a LOG or an API RESPONSE; the stored row is untouched | every member |
+ * | `.impersonalizeWith(...)` on a schema field | ERASURE scrub: permanently rewrites the stored value when the person is erased and the row is retained | `REMOVE` · `MASK` · `RESET` · `KEEP` only |
+ *
+ * **`HASH` and `ENCRYPT` are accepted by the type and REFUSED at erasure time.** An erasure scrub is
+ * one static write shared by every row in the batch, so `HASH` — which would have to hash each row's
+ * own value — cannot be expressed and throws. `ENCRYPT` is reversible, and an erasure that can be
+ * undone is not an erasure, so it is forbidden here and stays a redaction-only option. Both throw
+ * when the erasure runs, not when you author the field, so choosing one leaves a resource that
+ * configures cleanly and fails the first time somebody is erased.
+ *
+ * ## Choosing a treatment for an erasure scrub
+ *
+ * | the field | treatment |
+ * |---|---|
+ * | nullable, or `.nullish()` | `REMOVE` — writes `null`. The default choice. |
+ * | a constrained string that cannot hold the default mask (`z.email()`, `z.uuid()`, `.min(n)`) | `MASK` with an explicit `maskValue` that satisfies the field's own schema |
+ * | NON-nullable and carries a `.default()` — a counter, a settings object, a stage history, an array | `RESET` — writes what the schema says the field is when nobody has set it |
+ * | the row's link to its tenant or its creator | nothing: the never-scrub floor already protects it |
+ *
+ * `RESET` is the one to reach for when the other two do not fit, and that case is common rather than
+ * exotic: `REMOVE` writes `null`, which fails the strict re-parse of the row the erasure just wrote,
+ * and `MASK` writes a string, which cannot express an array, a record, a number or a date.
+ *
+ * ⚠️ **`RESET` refuses a default that reads the clock.** `.default(() => new Date())` — or a literal
+ * `.default(new Date())` evaluated when the module loads — makes the erasure write its OWN timestamp,
+ * so a field such as `lastActiveAt` would record the erased person as active at the moment they were
+ * erased. That fabricates information rather than removing it. Give the field a static neutral
+ * default such as `new Date(0)`, which asserts "no recorded value", or make it nullable and use
+ * `REMOVE`, which asserts "unknown". Those are different claims about a person; choose deliberately.
+ *
+ * ## The never-scrub floor
+ *
+ * A row's link to the organization or application it belongs to, and its `createdByUserId`, are
+ * never scrubbed — even when a treatment is declared on them. They connect the retained row to the
+ * tenant that must keep it, and nulling them would orphan the record the retention exists to
+ * preserve. `KEEP` is the way to say the same thing explicitly about any other field.
+ *
+ * A field with NO `.impersonalizeWith()` is left untouched by an erasure. Declaring nothing is how a
+ * legally required value — an invoice line, an amount, a date — survives the erasure of the person
+ * the record names.
+ *
+ * @example Scrubbing a person out of a retained record
+ * ```ts
+ * import { RedactionType } from '@wildo-ai/saas-models';
+ *
+ * const contactSchema = z.object({
+ *   // nullable → REMOVE
+ *   phone: z.string().nullish().impersonalizeWith(RedactionType.REMOVE),
+ *   // constrained string → MASK with a value the field's own schema accepts
+ *   email: z.email().impersonalizeWith(RedactionType.MASK, { maskValue: 'erased@erased.invalid' }),
+ *   // non-nullable with a default → RESET
+ *   preferences: z.object({ digest: z.boolean() }).default({ digest: false })
+ *     .impersonalizeWith(RedactionType.RESET),
+ *   // no treatment → survives the erasure, deliberately
+ *   invoicedAmount: z.number(),
+ * });
+ * ```
  */
 export declare enum RedactionType {
-    /** Replace with a fixed mask (e.g. `••••••••`). */
+    /** Replace with a fixed mask. In an erasure scrub the value must satisfy the field's own schema — pass `maskValue` when the default mask does not. */
     MASK = "mask",
-    /** Remove / null the value. Impersonalization: the default scrub. */
+    /** Remove / null the value. The default erasure scrub; requires a field that can actually hold `null`. */
     REMOVE = "remove",
-    /** Replace with a one-way hash — irreversible. */
+    /** Replace with a one-way hash. Redaction only — **throws** if an erasure scrub reaches it, because a scrub is one static write and cannot hash per row. */
     HASH = "hash",
-    /** Replace with a reversible ciphertext (key-dependent). */
+    /** Replace with a reversible ciphertext. Redaction only — **forbidden** for an erasure scrub, because a reversible erasure is not an erasure. */
     ENCRYPT = "encrypt",
-    /** Impersonalization only: retain the field as-is (never scrub). The scope-FK KEEP-floor uses this. */
+    /** Erasure scrub only: keep this field exactly as it is. The explicit form of the never-scrub floor. */
     KEEP = "keep",
     /**
-     * Impersonalization only: reset the field to its OWN schema default.
+     * Erasure scrub only: reset the field to its OWN schema default.
      *
-     * The treatment for a field that is non-nullable and carries a `.default()` — where neither of the
-     * other two reaches. `REMOVE` writes null, which fails the strict re-parse of the row erasure just
-     * wrote; `MASK` cannot express the value, because `maskValue` is typed `string` while these fields
-     * are arrays, records, numbers, dates and objects.
+     * The treatment for a field that is non-nullable and carries a `.default()`, where neither of the
+     * others reaches: `REMOVE` writes `null`, which fails the strict re-parse of the row the erasure
+     * just wrote, and `MASK` writes a string, while these fields are arrays, records, numbers, dates
+     * and objects.
      *
-     * That is not a rare shape. Measured 2026-08-31 across the engine schemas still owed an erasure
-     * posture, ELEVEN categorized fields were of it and NONE was scrubbable — behavioural counters,
-     * stage histories, notification preferences, regional settings carrying LOCATION. Those resources
-     * could declare no honest posture at all: `RETAIN_AND_IMPERSONALIZE` is refused when nothing would
-     * be scrubbed, and `RETAIN_ONLY` would assert they hold no personal data, which is false.
+     * The value is read from the schema rather than authored a second time, so it cannot drift from
+     * the default the field already declares — and for a person's counters and settings, "what this is
+     * when nobody has set it" is exactly what an erasure should leave behind.
      *
-     * The value comes from the schema rather than from the author, deliberately. A second copy of every
-     * default would drift from the first, and "what this field is when nobody has set it" is a question
-     * the schema already answers — for a person's settings and counters that is exactly what erasure
-     * should leave behind.
+     * Refused when the field declares no `.default()`, and refused when that default reads the clock.
      */
     RESET = "reset"
 }
+/** @wildo_source:part:end saas.models.privacy.redaction-treatments */
 export declare const RedationRulesSchema: z.ZodObject<{
     fieldPath: z.ZodString;
     isRecursive: z.ZodDefault<z.ZodBoolean>;

package/dist/esm/compliance/privacy/redaction.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"redaction.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/compliance/privacy/redaction.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;GAWG;AACH,oBAAY,aAAa;IACvB,mDAAmD;IACnD,IAAI,SAAS;IACb,qEAAqE;IACrE,MAAM,WAAW;IACjB,kDAAkD;IAClD,IAAI,SAAS;IACb,4DAA4D;IAC5D,OAAO,YAAY;IACnB,uGAAuG;IACvG,IAAI,SAAS;IACb;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,UAAU;CAChB;AAGD,eAAO,MAAM,mBAAmB;;;;;iBAK9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}
+{"version":3,"file":"redaction.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/compliance/privacy/redaction.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiBxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,oBAAY,aAAa;IACvB,sJAAsJ;IACtJ,IAAI,SAAS;IACb,0GAA0G;IAC1G,MAAM,WAAW;IACjB,4JAA4J;IAC5J,IAAI,SAAS;IACb,iJAAiJ;IACjJ,OAAO,YAAY;IACnB,wGAAwG;IACxG,IAAI,SAAS;IACb;;;;;;;;;;;;;OAaG;IACH,KAAK,UAAU;CAChB;AACD,sEAAsE;AAGtE,eAAO,MAAM,mBAAmB;;;;;iBAK9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/esm/compliance/privacy/redaction.shared.schemas.js

@@ -1,50 +1,116 @@
 import { z } from "zod";
 import { RolesSchema } from "../../security/authorizations/roles.shared.schemas.js";
+/*
+ * MAINTAINER NOTE — not part of the anchored, application-facing block below.
+ *
+ * One authority axis (D9): this vocabulary is shared by flow-actors `redactionRules` and by the
+ * impersonalization `.impersonalizeWith()` treatment, deliberately, so the two cannot drift into two
+ * spellings of the same idea. Adding a member is additive for both consumers — no exhaustive switch
+ * reads it — EXCEPT `buildImpersonalizeScrubPatch`, whose `default` arm throws on purpose so a new
+ * member fails loud in an erasure rather than being silently skipped.
+ *
+ * Reversible tokenization is intentionally NOT in v1 (D6 = irreversible). `ENCRYPT` stays the
+ * existing reversible option for redaction, and a vault-backed `TOKENIZE` member can be added
+ * additively if such a mode ships.
+ */
 /**
- * Field-treatment vocabulary, shared by two consumers (D9 — "one authority axis"):
- *  - flow-actors `redactionRules` (log / response redaction), and
- *  - the impersonalization `.impersonalizeWith()` per-field treatment (erasure scrub —
- *    scrub a person out of a record that must be retained).
- *
- * Adding members is additive for both consumers (no exhaustive switches read it).
- * `KEEP` is meaningful only for impersonalization (never scrub this field) — the
- * never-scrub scope-FK floor relies on it. Reversible tokenization is intentionally
- * NOT in v1 (D6 = irreversible); `ENCRYPT` remains the existing reversible option, and a
- * dedicated `TOKENIZE` member can be added additively if a vault-backed mode ships later.
+ * @wildo_source:part:start saas.models.privacy.redaction-treatments facet:layer:shared facet:audience:app-developer
+ *
+ * How one field's value is replaced when it is redacted or scrubbed.
+ *
+ * Imported from `@wildo-ai/saas-models`.
+ *
+ * ## Two consumers, and only one of them accepts every member
+ *
+ * | consumer | what it does | accepts |
+ * |---|---|---|
+ * | flow-actors `redactionRules` | hides a value in a LOG or an API RESPONSE; the stored row is untouched | every member |
+ * | `.impersonalizeWith(...)` on a schema field | ERASURE scrub: permanently rewrites the stored value when the person is erased and the row is retained | `REMOVE` · `MASK` · `RESET` · `KEEP` only |
+ *
+ * **`HASH` and `ENCRYPT` are accepted by the type and REFUSED at erasure time.** An erasure scrub is
+ * one static write shared by every row in the batch, so `HASH` — which would have to hash each row's
+ * own value — cannot be expressed and throws. `ENCRYPT` is reversible, and an erasure that can be
+ * undone is not an erasure, so it is forbidden here and stays a redaction-only option. Both throw
+ * when the erasure runs, not when you author the field, so choosing one leaves a resource that
+ * configures cleanly and fails the first time somebody is erased.
+ *
+ * ## Choosing a treatment for an erasure scrub
+ *
+ * | the field | treatment |
+ * |---|---|
+ * | nullable, or `.nullish()` | `REMOVE` — writes `null`. The default choice. |
+ * | a constrained string that cannot hold the default mask (`z.email()`, `z.uuid()`, `.min(n)`) | `MASK` with an explicit `maskValue` that satisfies the field's own schema |
+ * | NON-nullable and carries a `.default()` — a counter, a settings object, a stage history, an array | `RESET` — writes what the schema says the field is when nobody has set it |
+ * | the row's link to its tenant or its creator | nothing: the never-scrub floor already protects it |
+ *
+ * `RESET` is the one to reach for when the other two do not fit, and that case is common rather than
+ * exotic: `REMOVE` writes `null`, which fails the strict re-parse of the row the erasure just wrote,
+ * and `MASK` writes a string, which cannot express an array, a record, a number or a date.
+ *
+ * ⚠️ **`RESET` refuses a default that reads the clock.** `.default(() => new Date())` — or a literal
+ * `.default(new Date())` evaluated when the module loads — makes the erasure write its OWN timestamp,
+ * so a field such as `lastActiveAt` would record the erased person as active at the moment they were
+ * erased. That fabricates information rather than removing it. Give the field a static neutral
+ * default such as `new Date(0)`, which asserts "no recorded value", or make it nullable and use
+ * `REMOVE`, which asserts "unknown". Those are different claims about a person; choose deliberately.
+ *
+ * ## The never-scrub floor
+ *
+ * A row's link to the organization or application it belongs to, and its `createdByUserId`, are
+ * never scrubbed — even when a treatment is declared on them. They connect the retained row to the
+ * tenant that must keep it, and nulling them would orphan the record the retention exists to
+ * preserve. `KEEP` is the way to say the same thing explicitly about any other field.
+ *
+ * A field with NO `.impersonalizeWith()` is left untouched by an erasure. Declaring nothing is how a
+ * legally required value — an invoice line, an amount, a date — survives the erasure of the person
+ * the record names.
+ *
+ * @example Scrubbing a person out of a retained record
+ * ```ts
+ * import { RedactionType } from '@wildo-ai/saas-models';
+ *
+ * const contactSchema = z.object({
+ *   // nullable → REMOVE
+ *   phone: z.string().nullish().impersonalizeWith(RedactionType.REMOVE),
+ *   // constrained string → MASK with a value the field's own schema accepts
+ *   email: z.email().impersonalizeWith(RedactionType.MASK, { maskValue: 'erased@erased.invalid' }),
+ *   // non-nullable with a default → RESET
+ *   preferences: z.object({ digest: z.boolean() }).default({ digest: false })
+ *     .impersonalizeWith(RedactionType.RESET),
+ *   // no treatment → survives the erasure, deliberately
+ *   invoicedAmount: z.number(),
+ * });
+ * ```
  */
 export var RedactionType;
 (function (RedactionType) {
-    /** Replace with a fixed mask (e.g. `••••••••`). */
+    /** Replace with a fixed mask. In an erasure scrub the value must satisfy the field's own schema — pass `maskValue` when the default mask does not. */
     RedactionType["MASK"] = "mask";
-    /** Remove / null the value. Impersonalization: the default scrub. */
+    /** Remove / null the value. The default erasure scrub; requires a field that can actually hold `null`. */
     RedactionType["REMOVE"] = "remove";
-    /** Replace with a one-way hash — irreversible. */
+    /** Replace with a one-way hash. Redaction only — **throws** if an erasure scrub reaches it, because a scrub is one static write and cannot hash per row. */
     RedactionType["HASH"] = "hash";
-    /** Replace with a reversible ciphertext (key-dependent). */
+    /** Replace with a reversible ciphertext. Redaction only — **forbidden** for an erasure scrub, because a reversible erasure is not an erasure. */
     RedactionType["ENCRYPT"] = "encrypt";
-    /** Impersonalization only: retain the field as-is (never scrub). The scope-FK KEEP-floor uses this. */
+    /** Erasure scrub only: keep this field exactly as it is. The explicit form of the never-scrub floor. */
     RedactionType["KEEP"] = "keep";
     /**
-     * Impersonalization only: reset the field to its OWN schema default.
+     * Erasure scrub only: reset the field to its OWN schema default.
      *
-     * The treatment for a field that is non-nullable and carries a `.default()` — where neither of the
-     * other two reaches. `REMOVE` writes null, which fails the strict re-parse of the row erasure just
-     * wrote; `MASK` cannot express the value, because `maskValue` is typed `string` while these fields
-     * are arrays, records, numbers, dates and objects.
+     * The treatment for a field that is non-nullable and carries a `.default()`, where neither of the
+     * others reaches: `REMOVE` writes `null`, which fails the strict re-parse of the row the erasure
+     * just wrote, and `MASK` writes a string, while these fields are arrays, records, numbers, dates
+     * and objects.
      *
-     * That is not a rare shape. Measured 2026-08-31 across the engine schemas still owed an erasure
-     * posture, ELEVEN categorized fields were of it and NONE was scrubbable — behavioural counters,
-     * stage histories, notification preferences, regional settings carrying LOCATION. Those resources
-     * could declare no honest posture at all: `RETAIN_AND_IMPERSONALIZE` is refused when nothing would
-     * be scrubbed, and `RETAIN_ONLY` would assert they hold no personal data, which is false.
+     * The value is read from the schema rather than authored a second time, so it cannot drift from
+     * the default the field already declares — and for a person's counters and settings, "what this is
+     * when nobody has set it" is exactly what an erasure should leave behind.
      *
-     * The value comes from the schema rather than from the author, deliberately. A second copy of every
-     * default would drift from the first, and "what this field is when nobody has set it" is a question
-     * the schema already answers — for a person's settings and counters that is exactly what erasure
-     * should leave behind.
+     * Refused when the field declares no `.default()`, and refused when that default reads the clock.
      */
     RedactionType["RESET"] = "reset";
 })(RedactionType || (RedactionType = {}));
+/** @wildo_source:part:end saas.models.privacy.redaction-treatments */
 export const RedationRulesSchema = z.object({
     fieldPath: z.string(),
     isRecursive: z.boolean().default(false), // default false - if true, will redaction all nested fields