@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/compliance/privacy/personal-data-category.shared.schemas.d.ts

@@ -0,0 +1,220 @@
+import { z } from 'zod';
+/**
+ * What KIND of personal data a field holds — the vocabulary a privacy notice enumerates when it
+ * answers "which categories of personal data do you process".
+ *
+ * ⚠️ NOT `Compliance_DataClassification`, and the near-miss is why this exists. That enum is a
+ * four-level SENSITIVITY ladder (public / internal / confidential / restricted) applied to
+ * flows-actors configuration: it answers "how protected must this be", not "what kind of personal
+ * data is this". Using it as a category vocabulary produces a notice describing protection levels
+ * where a reader expects data types.
+ *
+ * ⚠️ NOT a sensitivity, a retention class, a provenance, or a scrub treatment. A single field is
+ * routinely all five at once — `CONTACT_DETAILS`, retained for 30 days, subject-provided, masked on
+ * erasure. Each axis has its own declaration and they are deliberately not merged.
+ *
+ * **The ordinary members are coarse on purpose; the special ones are not.** Ordinary categories are
+ * a framework's judgement about a useful grouping, and a granularity nobody maintains produces an
+ * inventory that is precise and wrong. The special-category members are the LAW's own list, closed
+ * by GDPR Art. 9(1), and they are enumerated individually because "special category data" alone is
+ * not a disclosure — a reader is entitled to know it is health data rather than political opinion,
+ * and each carries its own Art. 9(2) condition.
+ *
+ * @example
+ * // The common case: one category, on the field that holds it.
+ * email: z.email().dataCategories(PersonalDataCategory.CONTACT_DETAILS)
+ * @example
+ * // A field that genuinely spans two. An array never forces the author to pick a lie.
+ * dietaryNotes: z.string().dataCategories([PersonalDataCategory.USER_CONTENT, PersonalDataCategory.SPECIAL_CATEGORY_HEALTH])
+ *
+ * @wildo_source:part:start zod.decorators.data-categories facet:layer:shared facet:family:decorator facet:kind:api facet:audience:app-developer
+ */
+export declare enum PersonalDataCategory {
+    /** Who the person is: name, username, display name, account identifier, avatar. */
+    IDENTITY = "identity",
+    /** How the person is reached: email address, telephone number, postal address. */
+    CONTACT_DETAILS = "contact-details",
+    /**
+     * What proves the person is who they claim: passwords, MFA secrets, API keys, session tokens.
+     *
+     * Rarely authored by hand — the fact producer DERIVES this category from `.isPassword()`,
+     * `.isOtp()` and `.isWriteOnlySecret()`, which are declarations the application already makes.
+     * Declare it explicitly only for a credential those markers do not cover.
+     */
+    CREDENTIALS = "credentials",
+    /** Money: payment-method references, invoices, billing details, transaction history. */
+    FINANCIAL = "financial",
+    /** What the person did in the product: activity records, timestamps, device and telemetry data. */
+    USAGE = "usage",
+    /** Where the person is or was: coordinates, derived region, IP-inferred location. */
+    LOCATION = "location",
+    /**
+     * What the person wrote or uploaded: free text, notes, attachments.
+     *
+     * ⚠️ Free text is the category that can silently contain any other one — a "notes" field may hold
+     * health information nobody declared. Declaring `USER_CONTENT` states what the field is FOR; it
+     * does not certify what it will contain, and no schema can. Where a free-text field is
+     * FORESEEABLY used for a special category, declare that member alongside.
+     */
+    USER_CONTENT = "user-content",
+    /** The person's working life: employer, job title, professional relationship to the operator. */
+    PROFESSIONAL = "professional",
+    /** Art. 9(1): racial or ethnic origin. */
+    SPECIAL_CATEGORY_RACIAL_OR_ETHNIC_ORIGIN = "special-category:racial-or-ethnic-origin",
+    /** Art. 9(1): political opinions. */
+    SPECIAL_CATEGORY_POLITICAL_OPINIONS = "special-category:political-opinions",
+    /** Art. 9(1): religious or philosophical beliefs. */
+    SPECIAL_CATEGORY_RELIGIOUS_OR_PHILOSOPHICAL_BELIEFS = "special-category:religious-or-philosophical-beliefs",
+    /** Art. 9(1): trade union membership. */
+    SPECIAL_CATEGORY_TRADE_UNION_MEMBERSHIP = "special-category:trade-union-membership",
+    /** Art. 9(1): genetic data. */
+    SPECIAL_CATEGORY_GENETIC = "special-category:genetic",
+    /**
+     * Art. 9(1): biometric data processed FOR THE PURPOSE OF uniquely identifying a natural person.
+     *
+     * The purpose qualifier is part of the law's definition, not a footnote: a photograph is ordinary
+     * `IDENTITY` data until it is put through facial recognition, at which point it becomes this.
+     */
+    SPECIAL_CATEGORY_BIOMETRIC = "special-category:biometric",
+    /** Art. 9(1): data concerning health. */
+    SPECIAL_CATEGORY_HEALTH = "special-category:health",
+    /** Art. 9(1): data concerning a natural person's sex life or sexual orientation. */
+    SPECIAL_CATEGORY_SEX_LIFE_OR_SEXUAL_ORIENTATION = "special-category:sex-life-or-sexual-orientation",
+    /**
+     * GDPR Art. 10: criminal convictions and offences.
+     *
+     * Deliberately NOT a member of {@link SPECIAL_CATEGORY_PERSONAL_DATA_CATEGORIES}. Art. 10 is a
+     * separate article with a different condition — processing requires official authority or a
+     * Member State law — so folding it into the Art. 9 set would attach the wrong legal test to it.
+     */
+    CRIMINAL_OFFENCE = "criminal-offence"
+}
+/**
+ * What the ENGINE deliberately does NOT declare, so its silence reads as a decision.
+ *
+ * Measured 2026-08-30: 48 of the 85 engine resource configurations declare at least one category. The rest are silent on
+ * purpose, in four groups:
+ *
+ * - **System machinery is not personal data, even when the row carries a `userId`.** A queue
+ *   execution, an entitlement limit, an unread counter, a token-budget counter — each exists so the
+ *   platform can do its work, and the person's identifier on it is the LINK, not the datum. This
+ *   group is the one that is easiest to get wrong, because such rows legitimately appear in a
+ *   subject export: `systemAccessPolicy.exportSubject` means *rows here relate to a subject and
+ *   belong in their bundle*, which is true by linkage alone. It does not mean the row holds a datum
+ *   about them, and reading it that way once put `jobExecutions` in this inventory.
+ *
+ * - **A legal person is not a data subject.** `organizations`, `organizationUnits`,
+ *   `organizationProfiles`, `organizationPreferences` and their siblings describe a COMPANY. GDPR
+ *   Recital 14 excludes the processing of data concerning legal persons, so declaring
+ *   `CONTACT_DETAILS` on an organization's switchboard number would make every notice claim the
+ *   operator holds an individual's contact details that it does not. A small company's number is
+ *   often a person's — that is a fact about the customer's data, not about this field's meaning.
+ * - **Configuration is not data about anyone.** SSO/SCIM/webhook configuration, API keys and OAuth
+ *   clients owned by an organization, products, prices, promotions, ETL cursors. An organization's
+ *   API key is a bearer secret whose subject is the organization; the person who minted it is not
+ *   recorded on the row.
+ * - **A foreign key is LINKAGE, not a category.** `userId` on a usage row is what makes that usage
+ *   personal; the category of the row's CONTENT is what a notice enumerates. Declaring `IDENTITY`
+ *   on every owner FK would put "identity data" against resources holding no name, and tell a
+ *   reader nothing the linkage does not already imply. The machinery group above is this same rule
+ *   applied one level up, at the row rather than the field.
+ *
+ * The line between the first group and a real answer is not always obvious, and one pair is worth
+ * keeping side by side: a metered USAGE RECORD is declared while a TOKEN-BUDGET counter is not.
+ * Both count something a person consumed. The usage record is a per-event history with a timestamp —
+ * a record of what they did, which an Art. 15 copy must contain. The budget counter is a single
+ * mutable number that exists so a limiter can refuse the next call; nothing about the person
+ * survives in it. Ask what the row is FOR, not what it counts.
+ *
+ * Recorded here because absence is invisible. A future reader finding `organizationProfiles`
+ * undeclared should be able to see that it was considered, not assume it was missed — the same
+ * discipline a justified `N/A` serves in a verification matrix.
+ */
+/** Zod form of {@link PersonalDataCategory}. */
+export declare const PersonalDataCategorySchema: z.ZodEnum<typeof PersonalDataCategory>;
+/**
+ * The GDPR Art. 9(1) members, as a set — the one place the Art. 9 line is drawn.
+ *
+ * Derived by PREFIX rather than hand-listed: every Art. 9 member's wire value begins
+ * `special-category:`, so a member added to the enum joins this set automatically. A hand-written
+ * list would be a second enumeration of a closed vocabulary, and the failure mode is silent — a new
+ * Art. 9 member omitted from it reads as ordinary personal data.
+ */
+export declare const SPECIAL_CATEGORY_PERSONAL_DATA_CATEGORIES: ReadonlySet<PersonalDataCategory>;
+/**
+ * Does this category carry the GDPR Art. 9 condition?
+ *
+ * `false` for {@link PersonalDataCategory.CRIMINAL_OFFENCE} — see that member's note. Callers that
+ * need "needs a condition beyond Art. 6" must test both.
+ */
+export declare function isSpecialCategoryPersonalData(category: PersonalDataCategory): boolean;
+/** @wildo_source:part:end zod.decorators.data-categories */
+/** Every declared value that is not a {@link PersonalDataCategory} member. */
+export declare function unknownPersonalDataCategories(declared: readonly string[]): readonly string[];
+/**
+ * Why the fact producer believes a field holds personal data, when the field itself declares no
+ * category. Each basis is a declaration the application ALREADY made for another purpose — never an
+ * inference from the field's name.
+ */
+export declare enum PersonalDataFieldBasis {
+    /** The field declares a category outright. */
+    DECLARED = "declared",
+    /** `.isPassword()` / `.isOtp()` / `.isWriteOnlySecret()` — a credential by the application's own marking. */
+    CREDENTIAL_MARKER = "credential-marker",
+    /** `.impersonalizeWith()` — the application declared this value must be scrubbed on erasure. */
+    ERASURE_SCRUB = "erasure-scrub",
+    /** `.portabilityProvenance()` — the application declared where this value about the subject came from. */
+    PORTABILITY_PROVENANCE = "portability-provenance"
+}
+/** One field's category answer within a resource. */
+export interface PersonalDataFieldCategories {
+    readonly fieldName: string;
+    readonly basis: PersonalDataFieldBasis;
+    /** Empty exactly when `basis` is not `DECLARED` and no category could be derived. */
+    readonly categories: readonly PersonalDataCategory[];
+}
+/** What one resource's main schema says about the categories of personal data it holds. */
+export interface ResourcePersonalDataCategoryProfile {
+    /** Fields carrying an explicit `.dataCategories()` declaration. */
+    readonly declaredFields: readonly PersonalDataFieldCategories[];
+    /**
+     * Fields the application has ALREADY declared to be personal — through a credential marker, an
+     * erasure scrub treatment, or a portability provenance — that carry no category.
+     *
+     * This is the actionable gap: the omission is provably an omission rather than a judgement that
+     * the field is not personal, because the application said it was personal by another door.
+     */
+    readonly uncategorizedPersonalFields: readonly PersonalDataFieldCategories[];
+    /** The union of every category the resource declares, derived credentials included. */
+    readonly categories: readonly PersonalDataCategory[];
+}
+/**
+ * Dedupe and order categories by the enum's own declaration order.
+ *
+ * Exported because every consumer that unions categories — across fields, across resources, across
+ * an application — needs the same order, and a document that reorders its own category list between
+ * runs reads as if the answer changed. One authority for the order, rather than each caller sorting
+ * alphabetically (which would interleave the Art. 9 members through the ordinary ones) or by first
+ * appearance (which depends on resource iteration order).
+ */
+export declare function sortPersonalDataCategories(categories: Iterable<PersonalDataCategory>): readonly PersonalDataCategory[];
+/**
+ * Read a resource's declared data categories off its main schema, and report the fields the
+ * application has already admitted are personal but has not categorized.
+ *
+ * **TOP-LEVEL fields only**, which is a real limit and is stated rather than hidden: the walk uses
+ * the same shape resolver the subject-export compiler uses, and that resolver merges union options
+ * without descending into a nested `ZodObject`. A category declared on `billingContact.email` is
+ * therefore invisible here — exactly as an `.impersonalizeWith()` declared there is invisible to
+ * the scrub writer, which is why the retention guard makes a nested treatment a BOOT ERROR. A
+ * nested category is not a boot error (it breaks nothing at runtime); it simply does not reach a
+ * notice, so declare categories at the top level.
+ *
+ * **Derivation is from DECLARATIONS, never from names.** `CREDENTIALS` is inferred from
+ * `.isPassword()` / `.isOtp()` / `.isWriteOnlySecret()` because those are markers the author wrote.
+ * Nothing here looks at a field being called `email`, `phone` or `dateOfBirth` — a category list
+ * assembled by pattern-matching identifiers is a guess presented as an inventory, and whatever the
+ * guess misses is simply not disclosed.
+ */
+export declare function resolveResourcePersonalDataCategories(mainSchema: unknown): ResourcePersonalDataCategoryProfile;
+//# sourceMappingURL=personal-data-category.shared.schemas.d.ts.map

package/dist/esm/compliance/privacy/personal-data-category.shared.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"personal-data-category.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/compliance/privacy/personal-data-category.shared.schemas.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,oBAAY,oBAAoB;IAC9B,mFAAmF;IACnF,QAAQ,aAAa;IACrB,kFAAkF;IAClF,eAAe,oBAAoB;IACnC;;;;;;OAMG;IACH,WAAW,gBAAgB;IAC3B,wFAAwF;IACxF,SAAS,cAAc;IACvB,mGAAmG;IACnG,KAAK,UAAU;IACf,qFAAqF;IACrF,QAAQ,aAAa;IACrB;;;;;;;OAOG;IACH,YAAY,iBAAiB;IAC7B,iGAAiG;IACjG,YAAY,iBAAiB;IAI7B,0CAA0C;IAC1C,wCAAwC,6CAA6C;IACrF,qCAAqC;IACrC,mCAAmC,wCAAwC;IAC3E,qDAAqD;IACrD,mDAAmD,wDAAwD;IAC3G,yCAAyC;IACzC,uCAAuC,4CAA4C;IACnF,+BAA+B;IAC/B,wBAAwB,6BAA6B;IACrD;;;;;OAKG;IACH,0BAA0B,+BAA+B;IACzD,yCAAyC;IACzC,uBAAuB,4BAA4B;IACnD,oFAAoF;IACpF,+CAA+C,oDAAoD;IAEnG;;;;;;OAMG;IACH,gBAAgB,qBAAqB;CACtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,gDAAgD;AAChD,eAAO,MAAM,0BAA0B,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,oBAAoB,CAAgC,CAAC;AAE/G;;;;;;;GAOG;AACH,eAAO,MAAM,yCAAyC,EAAE,WAAW,CAAC,oBAAoB,CAEvF,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAErF;AACD,4DAA4D;AAE5D,8EAA8E;AAC9E,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,CAG5F;AAED;;;;GAIG;AACH,oBAAY,sBAAsB;IAChC,8CAA8C;IAC9C,QAAQ,aAAa;IACrB,6GAA6G;IAC7G,iBAAiB,sBAAsB;IACvC,gGAAgG;IAChG,aAAa,kBAAkB;IAC/B,0GAA0G;IAC1G,sBAAsB,2BAA2B;CAClD;AAED,qDAAqD;AACrD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC;IACvC,qFAAqF;IACrF,QAAQ,CAAC,UAAU,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACtD;AAED,2FAA2F;AAC3F,MAAM,WAAW,mCAAmC;IAClD,mEAAmE;IACnE,QAAQ,CAAC,cAAc,EAAE,SAAS,2BAA2B,EAAE,CAAC;IAChE;;;;;;OAMG;IACH,QAAQ,CAAC,2BAA2B,EAAE,SAAS,2BAA2B,EAAE,CAAC;IAC7E,uFAAuF;IACvF,QAAQ,CAAC,UAAU,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACtD;AAID;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAAG,SAAS,oBAAoB,EAAE,CAEtH;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qCAAqC,CAAC,UAAU,EAAE,OAAO,GAAG,mCAAmC,CA6C9G"}

package/dist/esm/compliance/privacy/personal-data-category.shared.schemas.js

@@ -0,0 +1,252 @@
+import { getDataCategories, getImpersonalizeTreatment, getPortabilityProvenance, isOtpField, isPasswordField, isWriteOnlySecretField } from '@wildo-ai/zod-decorators';
+import { z } from 'zod';
+import { resolveSubjectExportObjectShapeThroughWrappers } from './subject-export.shared.schemas.js';
+/**
+ * What KIND of personal data a field holds — the vocabulary a privacy notice enumerates when it
+ * answers "which categories of personal data do you process".
+ *
+ * ⚠️ NOT `Compliance_DataClassification`, and the near-miss is why this exists. That enum is a
+ * four-level SENSITIVITY ladder (public / internal / confidential / restricted) applied to
+ * flows-actors configuration: it answers "how protected must this be", not "what kind of personal
+ * data is this". Using it as a category vocabulary produces a notice describing protection levels
+ * where a reader expects data types.
+ *
+ * ⚠️ NOT a sensitivity, a retention class, a provenance, or a scrub treatment. A single field is
+ * routinely all five at once — `CONTACT_DETAILS`, retained for 30 days, subject-provided, masked on
+ * erasure. Each axis has its own declaration and they are deliberately not merged.
+ *
+ * **The ordinary members are coarse on purpose; the special ones are not.** Ordinary categories are
+ * a framework's judgement about a useful grouping, and a granularity nobody maintains produces an
+ * inventory that is precise and wrong. The special-category members are the LAW's own list, closed
+ * by GDPR Art. 9(1), and they are enumerated individually because "special category data" alone is
+ * not a disclosure — a reader is entitled to know it is health data rather than political opinion,
+ * and each carries its own Art. 9(2) condition.
+ *
+ * @example
+ * // The common case: one category, on the field that holds it.
+ * email: z.email().dataCategories(PersonalDataCategory.CONTACT_DETAILS)
+ * @example
+ * // A field that genuinely spans two. An array never forces the author to pick a lie.
+ * dietaryNotes: z.string().dataCategories([PersonalDataCategory.USER_CONTENT, PersonalDataCategory.SPECIAL_CATEGORY_HEALTH])
+ *
+ * @wildo_source:part:start zod.decorators.data-categories facet:layer:shared facet:family:decorator facet:kind:api facet:audience:app-developer
+ */
+export var PersonalDataCategory;
+(function (PersonalDataCategory) {
+    /** Who the person is: name, username, display name, account identifier, avatar. */
+    PersonalDataCategory["IDENTITY"] = "identity";
+    /** How the person is reached: email address, telephone number, postal address. */
+    PersonalDataCategory["CONTACT_DETAILS"] = "contact-details";
+    /**
+     * What proves the person is who they claim: passwords, MFA secrets, API keys, session tokens.
+     *
+     * Rarely authored by hand — the fact producer DERIVES this category from `.isPassword()`,
+     * `.isOtp()` and `.isWriteOnlySecret()`, which are declarations the application already makes.
+     * Declare it explicitly only for a credential those markers do not cover.
+     */
+    PersonalDataCategory["CREDENTIALS"] = "credentials";
+    /** Money: payment-method references, invoices, billing details, transaction history. */
+    PersonalDataCategory["FINANCIAL"] = "financial";
+    /** What the person did in the product: activity records, timestamps, device and telemetry data. */
+    PersonalDataCategory["USAGE"] = "usage";
+    /** Where the person is or was: coordinates, derived region, IP-inferred location. */
+    PersonalDataCategory["LOCATION"] = "location";
+    /**
+     * What the person wrote or uploaded: free text, notes, attachments.
+     *
+     * ⚠️ Free text is the category that can silently contain any other one — a "notes" field may hold
+     * health information nobody declared. Declaring `USER_CONTENT` states what the field is FOR; it
+     * does not certify what it will contain, and no schema can. Where a free-text field is
+     * FORESEEABLY used for a special category, declare that member alongside.
+     */
+    PersonalDataCategory["USER_CONTENT"] = "user-content";
+    /** The person's working life: employer, job title, professional relationship to the operator. */
+    PersonalDataCategory["PROFESSIONAL"] = "professional";
+    // ── GDPR Art. 9(1), verbatim and closed. Processing needs an Art. 9(2) condition of its own,
+    //    over and above the Art. 6 lawful basis every other member already needs.
+    /** Art. 9(1): racial or ethnic origin. */
+    PersonalDataCategory["SPECIAL_CATEGORY_RACIAL_OR_ETHNIC_ORIGIN"] = "special-category:racial-or-ethnic-origin";
+    /** Art. 9(1): political opinions. */
+    PersonalDataCategory["SPECIAL_CATEGORY_POLITICAL_OPINIONS"] = "special-category:political-opinions";
+    /** Art. 9(1): religious or philosophical beliefs. */
+    PersonalDataCategory["SPECIAL_CATEGORY_RELIGIOUS_OR_PHILOSOPHICAL_BELIEFS"] = "special-category:religious-or-philosophical-beliefs";
+    /** Art. 9(1): trade union membership. */
+    PersonalDataCategory["SPECIAL_CATEGORY_TRADE_UNION_MEMBERSHIP"] = "special-category:trade-union-membership";
+    /** Art. 9(1): genetic data. */
+    PersonalDataCategory["SPECIAL_CATEGORY_GENETIC"] = "special-category:genetic";
+    /**
+     * Art. 9(1): biometric data processed FOR THE PURPOSE OF uniquely identifying a natural person.
+     *
+     * The purpose qualifier is part of the law's definition, not a footnote: a photograph is ordinary
+     * `IDENTITY` data until it is put through facial recognition, at which point it becomes this.
+     */
+    PersonalDataCategory["SPECIAL_CATEGORY_BIOMETRIC"] = "special-category:biometric";
+    /** Art. 9(1): data concerning health. */
+    PersonalDataCategory["SPECIAL_CATEGORY_HEALTH"] = "special-category:health";
+    /** Art. 9(1): data concerning a natural person's sex life or sexual orientation. */
+    PersonalDataCategory["SPECIAL_CATEGORY_SEX_LIFE_OR_SEXUAL_ORIENTATION"] = "special-category:sex-life-or-sexual-orientation";
+    /**
+     * GDPR Art. 10: criminal convictions and offences.
+     *
+     * Deliberately NOT a member of {@link SPECIAL_CATEGORY_PERSONAL_DATA_CATEGORIES}. Art. 10 is a
+     * separate article with a different condition — processing requires official authority or a
+     * Member State law — so folding it into the Art. 9 set would attach the wrong legal test to it.
+     */
+    PersonalDataCategory["CRIMINAL_OFFENCE"] = "criminal-offence";
+})(PersonalDataCategory || (PersonalDataCategory = {}));
+/**
+ * What the ENGINE deliberately does NOT declare, so its silence reads as a decision.
+ *
+ * Measured 2026-08-30: 48 of the 85 engine resource configurations declare at least one category. The rest are silent on
+ * purpose, in four groups:
+ *
+ * - **System machinery is not personal data, even when the row carries a `userId`.** A queue
+ *   execution, an entitlement limit, an unread counter, a token-budget counter — each exists so the
+ *   platform can do its work, and the person's identifier on it is the LINK, not the datum. This
+ *   group is the one that is easiest to get wrong, because such rows legitimately appear in a
+ *   subject export: `systemAccessPolicy.exportSubject` means *rows here relate to a subject and
+ *   belong in their bundle*, which is true by linkage alone. It does not mean the row holds a datum
+ *   about them, and reading it that way once put `jobExecutions` in this inventory.
+ *
+ * - **A legal person is not a data subject.** `organizations`, `organizationUnits`,
+ *   `organizationProfiles`, `organizationPreferences` and their siblings describe a COMPANY. GDPR
+ *   Recital 14 excludes the processing of data concerning legal persons, so declaring
+ *   `CONTACT_DETAILS` on an organization's switchboard number would make every notice claim the
+ *   operator holds an individual's contact details that it does not. A small company's number is
+ *   often a person's — that is a fact about the customer's data, not about this field's meaning.
+ * - **Configuration is not data about anyone.** SSO/SCIM/webhook configuration, API keys and OAuth
+ *   clients owned by an organization, products, prices, promotions, ETL cursors. An organization's
+ *   API key is a bearer secret whose subject is the organization; the person who minted it is not
+ *   recorded on the row.
+ * - **A foreign key is LINKAGE, not a category.** `userId` on a usage row is what makes that usage
+ *   personal; the category of the row's CONTENT is what a notice enumerates. Declaring `IDENTITY`
+ *   on every owner FK would put "identity data" against resources holding no name, and tell a
+ *   reader nothing the linkage does not already imply. The machinery group above is this same rule
+ *   applied one level up, at the row rather than the field.
+ *
+ * The line between the first group and a real answer is not always obvious, and one pair is worth
+ * keeping side by side: a metered USAGE RECORD is declared while a TOKEN-BUDGET counter is not.
+ * Both count something a person consumed. The usage record is a per-event history with a timestamp —
+ * a record of what they did, which an Art. 15 copy must contain. The budget counter is a single
+ * mutable number that exists so a limiter can refuse the next call; nothing about the person
+ * survives in it. Ask what the row is FOR, not what it counts.
+ *
+ * Recorded here because absence is invisible. A future reader finding `organizationProfiles`
+ * undeclared should be able to see that it was considered, not assume it was missed — the same
+ * discipline a justified `N/A` serves in a verification matrix.
+ */
+/** Zod form of {@link PersonalDataCategory}. */
+export const PersonalDataCategorySchema = z.enum(PersonalDataCategory);
+/**
+ * The GDPR Art. 9(1) members, as a set — the one place the Art. 9 line is drawn.
+ *
+ * Derived by PREFIX rather than hand-listed: every Art. 9 member's wire value begins
+ * `special-category:`, so a member added to the enum joins this set automatically. A hand-written
+ * list would be a second enumeration of a closed vocabulary, and the failure mode is silent — a new
+ * Art. 9 member omitted from it reads as ordinary personal data.
+ */
+export const SPECIAL_CATEGORY_PERSONAL_DATA_CATEGORIES = new Set(Object.values(PersonalDataCategory).filter((category) => category.startsWith('special-category:')));
+/**
+ * Does this category carry the GDPR Art. 9 condition?
+ *
+ * `false` for {@link PersonalDataCategory.CRIMINAL_OFFENCE} — see that member's note. Callers that
+ * need "needs a condition beyond Art. 6" must test both.
+ */
+export function isSpecialCategoryPersonalData(category) {
+    return SPECIAL_CATEGORY_PERSONAL_DATA_CATEGORIES.has(category);
+}
+/** @wildo_source:part:end zod.decorators.data-categories */
+/** Every declared value that is not a {@link PersonalDataCategory} member. */
+export function unknownPersonalDataCategories(declared) {
+    const members = new Set(Object.values(PersonalDataCategory));
+    return declared.filter((value) => !members.has(value));
+}
+/**
+ * Why the fact producer believes a field holds personal data, when the field itself declares no
+ * category. Each basis is a declaration the application ALREADY made for another purpose — never an
+ * inference from the field's name.
+ */
+export var PersonalDataFieldBasis;
+(function (PersonalDataFieldBasis) {
+    /** The field declares a category outright. */
+    PersonalDataFieldBasis["DECLARED"] = "declared";
+    /** `.isPassword()` / `.isOtp()` / `.isWriteOnlySecret()` — a credential by the application's own marking. */
+    PersonalDataFieldBasis["CREDENTIAL_MARKER"] = "credential-marker";
+    /** `.impersonalizeWith()` — the application declared this value must be scrubbed on erasure. */
+    PersonalDataFieldBasis["ERASURE_SCRUB"] = "erasure-scrub";
+    /** `.portabilityProvenance()` — the application declared where this value about the subject came from. */
+    PersonalDataFieldBasis["PORTABILITY_PROVENANCE"] = "portability-provenance";
+})(PersonalDataFieldBasis || (PersonalDataFieldBasis = {}));
+const CATEGORY_ORDER = Object.values(PersonalDataCategory);
+/**
+ * Dedupe and order categories by the enum's own declaration order.
+ *
+ * Exported because every consumer that unions categories — across fields, across resources, across
+ * an application — needs the same order, and a document that reorders its own category list between
+ * runs reads as if the answer changed. One authority for the order, rather than each caller sorting
+ * alphabetically (which would interleave the Art. 9 members through the ordinary ones) or by first
+ * appearance (which depends on resource iteration order).
+ */
+export function sortPersonalDataCategories(categories) {
+    return [...new Set(categories)].sort((left, right) => CATEGORY_ORDER.indexOf(left) - CATEGORY_ORDER.indexOf(right));
+}
+/**
+ * Read a resource's declared data categories off its main schema, and report the fields the
+ * application has already admitted are personal but has not categorized.
+ *
+ * **TOP-LEVEL fields only**, which is a real limit and is stated rather than hidden: the walk uses
+ * the same shape resolver the subject-export compiler uses, and that resolver merges union options
+ * without descending into a nested `ZodObject`. A category declared on `billingContact.email` is
+ * therefore invisible here — exactly as an `.impersonalizeWith()` declared there is invisible to
+ * the scrub writer, which is why the retention guard makes a nested treatment a BOOT ERROR. A
+ * nested category is not a boot error (it breaks nothing at runtime); it simply does not reach a
+ * notice, so declare categories at the top level.
+ *
+ * **Derivation is from DECLARATIONS, never from names.** `CREDENTIALS` is inferred from
+ * `.isPassword()` / `.isOtp()` / `.isWriteOnlySecret()` because those are markers the author wrote.
+ * Nothing here looks at a field being called `email`, `phone` or `dateOfBirth` — a category list
+ * assembled by pattern-matching identifiers is a guess presented as an inventory, and whatever the
+ * guess misses is simply not disclosed.
+ */
+export function resolveResourcePersonalDataCategories(mainSchema) {
+    const shape = resolveSubjectExportObjectShapeThroughWrappers(mainSchema);
+    const declaredFields = [];
+    const uncategorizedPersonalFields = [];
+    const union = new Set();
+    for (const [fieldName, rawFieldSchema] of Object.entries(shape ?? {})) {
+        const fieldSchema = rawFieldSchema;
+        const declared = getDataCategories(fieldSchema);
+        if (declared !== undefined && declared.length > 0) {
+            const categories = sortPersonalDataCategories(declared);
+            declaredFields.push({ fieldName, basis: PersonalDataFieldBasis.DECLARED, categories });
+            for (const category of categories)
+                union.add(category);
+            continue;
+        }
+        if (isPasswordField(fieldSchema) || isOtpField(fieldSchema) || isWriteOnlySecretField(fieldSchema)) {
+            // Derived, not guessed: the author marked this a credential. It is reported as a DECLARED-
+            // equivalent answer rather than a gap, because asking for `.dataCategories(CREDENTIALS)` on a
+            // field already marked `.isPassword()` is a second declaration of one fact.
+            declaredFields.push({
+                fieldName,
+                basis: PersonalDataFieldBasis.CREDENTIAL_MARKER,
+                categories: [PersonalDataCategory.CREDENTIALS],
+            });
+            union.add(PersonalDataCategory.CREDENTIALS);
+            continue;
+        }
+        if (getImpersonalizeTreatment(fieldSchema) !== undefined) {
+            uncategorizedPersonalFields.push({ fieldName, basis: PersonalDataFieldBasis.ERASURE_SCRUB, categories: [] });
+            continue;
+        }
+        if (getPortabilityProvenance(fieldSchema) !== undefined) {
+            uncategorizedPersonalFields.push({ fieldName, basis: PersonalDataFieldBasis.PORTABILITY_PROVENANCE, categories: [] });
+        }
+    }
+    return {
+        declaredFields,
+        uncategorizedPersonalFields,
+        categories: sortPersonalDataCategories(union),
+    };
+}
+//# sourceMappingURL=personal-data-category.shared.schemas.js.map

package/dist/esm/compliance/privacy/personal-data-category.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"personal-data-category.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/compliance/privacy/personal-data-category.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { getDataCategories, getImpersonalizeTreatment, getPortabilityProvenance, isOtpField, isPasswordField, isWriteOnlySecretField } from '@wildo-ai/zod-decorators';\nimport { z } from 'zod';\n\nimport { resolveSubjectExportObjectShapeThroughWrappers } from './subject-export.shared.schemas';\n\n/**\n * What KIND of personal data a field holds — the vocabulary a privacy notice enumerates when it\n * answers \"which categories of personal data do you process\".\n *\n * ⚠️ NOT `Compliance_DataClassification`, and the near-miss is why this exists. That enum is a\n * four-level SENSITIVITY ladder (public / internal / confidential / restricted) applied to\n * flows-actors configuration: it answers \"how protected must this be\", not \"what kind of personal\n * data is this\". Using it as a category vocabulary produces a notice describing protection levels\n * where a reader expects data types.\n *\n * ⚠️ NOT a sensitivity, a retention class, a provenance, or a scrub treatment. A single field is\n * routinely all five at once — `CONTACT_DETAILS`, retained for 30 days, subject-provided, masked on\n * erasure. Each axis has its own declaration and they are deliberately not merged.\n *\n * **The ordinary members are coarse on purpose; the special ones are not.** Ordinary categories are\n * a framework's judgement about a useful grouping, and a granularity nobody maintains produces an\n * inventory that is precise and wrong. The special-category members are the LAW's own list, closed\n * by GDPR Art. 9(1), and they are enumerated individually because \"special category data\" alone is\n * not a disclosure — a reader is entitled to know it is health data rather than political opinion,\n * and each carries its own Art. 9(2) condition.\n *\n * @example\n * // The common case: one category, on the field that holds it.\n * email: z.email().dataCategories(PersonalDataCategory.CONTACT_DETAILS)\n * @example\n * // A field that genuinely spans two. An array never forces the author to pick a lie.\n * dietaryNotes: z.string().dataCategories([PersonalDataCategory.USER_CONTENT, PersonalDataCategory.SPECIAL_CATEGORY_HEALTH])\n *\n * @wildo_source:part:start zod.decorators.data-categories facet:layer:shared facet:family:decorator facet:kind:api facet:audience:app-developer\n */\nexport enum PersonalDataCategory {\n  /** Who the person is: name, username, display name, account identifier, avatar. */\n  IDENTITY = 'identity',\n  /** How the person is reached: email address, telephone number, postal address. */\n  CONTACT_DETAILS = 'contact-details',\n  /**\n   * What proves the person is who they claim: passwords, MFA secrets, API keys, session tokens.\n   *\n   * Rarely authored by hand — the fact producer DERIVES this category from `.isPassword()`,\n   * `.isOtp()` and `.isWriteOnlySecret()`, which are declarations the application already makes.\n   * Declare it explicitly only for a credential those markers do not cover.\n   */\n  CREDENTIALS = 'credentials',\n  /** Money: payment-method references, invoices, billing details, transaction history. */\n  FINANCIAL = 'financial',\n  /** What the person did in the product: activity records, timestamps, device and telemetry data. */\n  USAGE = 'usage',\n  /** Where the person is or was: coordinates, derived region, IP-inferred location. */\n  LOCATION = 'location',\n  /**\n   * What the person wrote or uploaded: free text, notes, attachments.\n   *\n   * ⚠️ Free text is the category that can silently contain any other one — a \"notes\" field may hold\n   * health information nobody declared. Declaring `USER_CONTENT` states what the field is FOR; it\n   * does not certify what it will contain, and no schema can. Where a free-text field is\n   * FORESEEABLY used for a special category, declare that member alongside.\n   */\n  USER_CONTENT = 'user-content',\n  /** The person's working life: employer, job title, professional relationship to the operator. */\n  PROFESSIONAL = 'professional',\n\n  // ── GDPR Art. 9(1), verbatim and closed. Processing needs an Art. 9(2) condition of its own,\n  //    over and above the Art. 6 lawful basis every other member already needs.\n  /** Art. 9(1): racial or ethnic origin. */\n  SPECIAL_CATEGORY_RACIAL_OR_ETHNIC_ORIGIN = 'special-category:racial-or-ethnic-origin',\n  /** Art. 9(1): political opinions. */\n  SPECIAL_CATEGORY_POLITICAL_OPINIONS = 'special-category:political-opinions',\n  /** Art. 9(1): religious or philosophical beliefs. */\n  SPECIAL_CATEGORY_RELIGIOUS_OR_PHILOSOPHICAL_BELIEFS = 'special-category:religious-or-philosophical-beliefs',\n  /** Art. 9(1): trade union membership. */\n  SPECIAL_CATEGORY_TRADE_UNION_MEMBERSHIP = 'special-category:trade-union-membership',\n  /** Art. 9(1): genetic data. */\n  SPECIAL_CATEGORY_GENETIC = 'special-category:genetic',\n  /**\n   * Art. 9(1): biometric data processed FOR THE PURPOSE OF uniquely identifying a natural person.\n   *\n   * The purpose qualifier is part of the law's definition, not a footnote: a photograph is ordinary\n   * `IDENTITY` data until it is put through facial recognition, at which point it becomes this.\n   */\n  SPECIAL_CATEGORY_BIOMETRIC = 'special-category:biometric',\n  /** Art. 9(1): data concerning health. */\n  SPECIAL_CATEGORY_HEALTH = 'special-category:health',\n  /** Art. 9(1): data concerning a natural person's sex life or sexual orientation. */\n  SPECIAL_CATEGORY_SEX_LIFE_OR_SEXUAL_ORIENTATION = 'special-category:sex-life-or-sexual-orientation',\n\n  /**\n   * GDPR Art. 10: criminal convictions and offences.\n   *\n   * Deliberately NOT a member of {@link SPECIAL_CATEGORY_PERSONAL_DATA_CATEGORIES}. Art. 10 is a\n   * separate article with a different condition — processing requires official authority or a\n   * Member State law — so folding it into the Art. 9 set would attach the wrong legal test to it.\n   */\n  CRIMINAL_OFFENCE = 'criminal-offence',\n}\n\n/**\n * What the ENGINE deliberately does NOT declare, so its silence reads as a decision.\n *\n * Measured 2026-08-30: 48 of the 85 engine resource configurations declare at least one category. The rest are silent on\n * purpose, in four groups:\n *\n * - **System machinery is not personal data, even when the row carries a `userId`.** A queue\n *   execution, an entitlement limit, an unread counter, a token-budget counter — each exists so the\n *   platform can do its work, and the person's identifier on it is the LINK, not the datum. This\n *   group is the one that is easiest to get wrong, because such rows legitimately appear in a\n *   subject export: `systemAccessPolicy.exportSubject` means *rows here relate to a subject and\n *   belong in their bundle*, which is true by linkage alone. It does not mean the row holds a datum\n *   about them, and reading it that way once put `jobExecutions` in this inventory.\n *\n * - **A legal person is not a data subject.** `organizations`, `organizationUnits`,\n *   `organizationProfiles`, `organizationPreferences` and their siblings describe a COMPANY. GDPR\n *   Recital 14 excludes the processing of data concerning legal persons, so declaring\n *   `CONTACT_DETAILS` on an organization's switchboard number would make every notice claim the\n *   operator holds an individual's contact details that it does not. A small company's number is\n *   often a person's — that is a fact about the customer's data, not about this field's meaning.\n * - **Configuration is not data about anyone.** SSO/SCIM/webhook configuration, API keys and OAuth\n *   clients owned by an organization, products, prices, promotions, ETL cursors. An organization's\n *   API key is a bearer secret whose subject is the organization; the person who minted it is not\n *   recorded on the row.\n * - **A foreign key is LINKAGE, not a category.** `userId` on a usage row is what makes that usage\n *   personal; the category of the row's CONTENT is what a notice enumerates. Declaring `IDENTITY`\n *   on every owner FK would put \"identity data\" against resources holding no name, and tell a\n *   reader nothing the linkage does not already imply. The machinery group above is this same rule\n *   applied one level up, at the row rather than the field.\n *\n * The line between the first group and a real answer is not always obvious, and one pair is worth\n * keeping side by side: a metered USAGE RECORD is declared while a TOKEN-BUDGET counter is not.\n * Both count something a person consumed. The usage record is a per-event history with a timestamp —\n * a record of what they did, which an Art. 15 copy must contain. The budget counter is a single\n * mutable number that exists so a limiter can refuse the next call; nothing about the person\n * survives in it. Ask what the row is FOR, not what it counts.\n *\n * Recorded here because absence is invisible. A future reader finding `organizationProfiles`\n * undeclared should be able to see that it was considered, not assume it was missed — the same\n * discipline a justified `N/A` serves in a verification matrix.\n */\n\n/** Zod form of {@link PersonalDataCategory}. */\nexport const PersonalDataCategorySchema: z.ZodEnum<typeof PersonalDataCategory> = z.enum(PersonalDataCategory);\n\n/**\n * The GDPR Art. 9(1) members, as a set — the one place the Art. 9 line is drawn.\n *\n * Derived by PREFIX rather than hand-listed: every Art. 9 member's wire value begins\n * `special-category:`, so a member added to the enum joins this set automatically. A hand-written\n * list would be a second enumeration of a closed vocabulary, and the failure mode is silent — a new\n * Art. 9 member omitted from it reads as ordinary personal data.\n */\nexport const SPECIAL_CATEGORY_PERSONAL_DATA_CATEGORIES: ReadonlySet<PersonalDataCategory> = new Set(\n  Object.values(PersonalDataCategory).filter((category) => category.startsWith('special-category:')),\n);\n\n/**\n * Does this category carry the GDPR Art. 9 condition?\n *\n * `false` for {@link PersonalDataCategory.CRIMINAL_OFFENCE} — see that member's note. Callers that\n * need \"needs a condition beyond Art. 6\" must test both.\n */\nexport function isSpecialCategoryPersonalData(category: PersonalDataCategory): boolean {\n  return SPECIAL_CATEGORY_PERSONAL_DATA_CATEGORIES.has(category);\n}\n/** @wildo_source:part:end zod.decorators.data-categories */\n\n/** Every declared value that is not a {@link PersonalDataCategory} member. */\nexport function unknownPersonalDataCategories(declared: readonly string[]): readonly string[] {\n  const members = new Set<string>(Object.values(PersonalDataCategory));\n  return declared.filter((value) => !members.has(value));\n}\n\n/**\n * Why the fact producer believes a field holds personal data, when the field itself declares no\n * category. Each basis is a declaration the application ALREADY made for another purpose — never an\n * inference from the field's name.\n */\nexport enum PersonalDataFieldBasis {\n  /** The field declares a category outright. */\n  DECLARED = 'declared',\n  /** `.isPassword()` / `.isOtp()` / `.isWriteOnlySecret()` — a credential by the application's own marking. */\n  CREDENTIAL_MARKER = 'credential-marker',\n  /** `.impersonalizeWith()` — the application declared this value must be scrubbed on erasure. */\n  ERASURE_SCRUB = 'erasure-scrub',\n  /** `.portabilityProvenance()` — the application declared where this value about the subject came from. */\n  PORTABILITY_PROVENANCE = 'portability-provenance',\n}\n\n/** One field's category answer within a resource. */\nexport interface PersonalDataFieldCategories {\n  readonly fieldName: string;\n  readonly basis: PersonalDataFieldBasis;\n  /** Empty exactly when `basis` is not `DECLARED` and no category could be derived. */\n  readonly categories: readonly PersonalDataCategory[];\n}\n\n/** What one resource's main schema says about the categories of personal data it holds. */\nexport interface ResourcePersonalDataCategoryProfile {\n  /** Fields carrying an explicit `.dataCategories()` declaration. */\n  readonly declaredFields: readonly PersonalDataFieldCategories[];\n  /**\n   * Fields the application has ALREADY declared to be personal — through a credential marker, an\n   * erasure scrub treatment, or a portability provenance — that carry no category.\n   *\n   * This is the actionable gap: the omission is provably an omission rather than a judgement that\n   * the field is not personal, because the application said it was personal by another door.\n   */\n  readonly uncategorizedPersonalFields: readonly PersonalDataFieldCategories[];\n  /** The union of every category the resource declares, derived credentials included. */\n  readonly categories: readonly PersonalDataCategory[];\n}\n\nconst CATEGORY_ORDER: readonly PersonalDataCategory[] = Object.values(PersonalDataCategory);\n\n/**\n * Dedupe and order categories by the enum's own declaration order.\n *\n * Exported because every consumer that unions categories — across fields, across resources, across\n * an application — needs the same order, and a document that reorders its own category list between\n * runs reads as if the answer changed. One authority for the order, rather than each caller sorting\n * alphabetically (which would interleave the Art. 9 members through the ordinary ones) or by first\n * appearance (which depends on resource iteration order).\n */\nexport function sortPersonalDataCategories(categories: Iterable<PersonalDataCategory>): readonly PersonalDataCategory[] {\n  return [...new Set(categories)].sort((left, right) => CATEGORY_ORDER.indexOf(left) - CATEGORY_ORDER.indexOf(right));\n}\n\n/**\n * Read a resource's declared data categories off its main schema, and report the fields the\n * application has already admitted are personal but has not categorized.\n *\n * **TOP-LEVEL fields only**, which is a real limit and is stated rather than hidden: the walk uses\n * the same shape resolver the subject-export compiler uses, and that resolver merges union options\n * without descending into a nested `ZodObject`. A category declared on `billingContact.email` is\n * therefore invisible here — exactly as an `.impersonalizeWith()` declared there is invisible to\n * the scrub writer, which is why the retention guard makes a nested treatment a BOOT ERROR. A\n * nested category is not a boot error (it breaks nothing at runtime); it simply does not reach a\n * notice, so declare categories at the top level.\n *\n * **Derivation is from DECLARATIONS, never from names.** `CREDENTIALS` is inferred from\n * `.isPassword()` / `.isOtp()` / `.isWriteOnlySecret()` because those are markers the author wrote.\n * Nothing here looks at a field being called `email`, `phone` or `dateOfBirth` — a category list\n * assembled by pattern-matching identifiers is a guess presented as an inventory, and whatever the\n * guess misses is simply not disclosed.\n */\nexport function resolveResourcePersonalDataCategories(mainSchema: unknown): ResourcePersonalDataCategoryProfile {\n  const shape = resolveSubjectExportObjectShapeThroughWrappers(mainSchema);\n  const declaredFields: PersonalDataFieldCategories[] = [];\n  const uncategorizedPersonalFields: PersonalDataFieldCategories[] = [];\n  const union = new Set<PersonalDataCategory>();\n\n  for (const [fieldName, rawFieldSchema] of Object.entries(shape ?? {})) {\n    const fieldSchema = rawFieldSchema as z.ZodTypeAny;\n    const declared = getDataCategories(fieldSchema);\n\n    if (declared !== undefined && declared.length > 0) {\n      const categories = sortPersonalDataCategories(declared as readonly PersonalDataCategory[]);\n      declaredFields.push({ fieldName, basis: PersonalDataFieldBasis.DECLARED, categories });\n      for (const category of categories) union.add(category);\n      continue;\n    }\n\n    if (isPasswordField(fieldSchema) || isOtpField(fieldSchema) || isWriteOnlySecretField(fieldSchema)) {\n      // Derived, not guessed: the author marked this a credential. It is reported as a DECLARED-\n      // equivalent answer rather than a gap, because asking for `.dataCategories(CREDENTIALS)` on a\n      // field already marked `.isPassword()` is a second declaration of one fact.\n      declaredFields.push({\n        fieldName,\n        basis: PersonalDataFieldBasis.CREDENTIAL_MARKER,\n        categories: [PersonalDataCategory.CREDENTIALS],\n      });\n      union.add(PersonalDataCategory.CREDENTIALS);\n      continue;\n    }\n\n    if (getImpersonalizeTreatment(fieldSchema) !== undefined) {\n      uncategorizedPersonalFields.push({ fieldName, basis: PersonalDataFieldBasis.ERASURE_SCRUB, categories: [] });\n      continue;\n    }\n\n    if (getPortabilityProvenance(fieldSchema) !== undefined) {\n      uncategorizedPersonalFields.push({ fieldName, basis: PersonalDataFieldBasis.PORTABILITY_PROVENANCE, categories: [] });\n    }\n  }\n\n  return {\n    declaredFields,\n    uncategorizedPersonalFields,\n    categories: sortPersonalDataCategories(union),\n  };\n}\n"]}

package/dist/esm/compliance/privacy/personal-data-declaration.shared.utils.d.ts

@@ -0,0 +1,75 @@
+import type { ResourceDataSubjectPolicy, ResourceRetentionPolicy, ResourceSystemAccessPolicy } from '../../resources/resources-config.shared.schemas';
+/**
+ * Has this resource said ANYTHING about whether its rows are about people?
+ *
+ * ## The decision behind this, and what it is deliberately NOT
+ *
+ * Issue #93 asked whether a resource holding personal data should be REQUIRED to declare it, and the
+ * evidence for requiring it was strong: measured across two applications, a declaration gets made if
+ * and only if the framework refuses to start without it. `exportSubject` is fail-closed at
+ * registration and was declared on 10 of 12 resources; `retentionPolicy` and `.impersonalizeWith()`
+ * are not enforced and were declared on 1 and 0.
+ *
+ * **Paul decided against refusing.** A hard constraint on every application author, for every
+ * resource, forever, is too strict — and the framework's own directive says the system must work
+ * first, with protection arriving later as a judge-style guard rather than as a refusal wired into
+ * the mechanism (`.claude/rules/application-creation-directive.md`).
+ *
+ * So this is a REPORT, and the report exists to be read by a human at startup. It never refuses, it
+ * never throws, and nothing downstream branches on it. The other half of the decision — the half
+ * that actually produces declarations — is the framework knowledge that teaches an author to write
+ * one while they are authoring the resource, which is where a declaration is cheap.
+ *
+ * ## What counts as having answered
+ *
+ * ANY of four declarations, because they are four different questions and answering any one of them
+ * means the author considered the subject:
+ *
+ * | declaration | the question it answers |
+ * |---|---|
+ * | `retentionPolicy.mode` | does an erasure keep this row, and are its fields scrubbed? |
+ * | `dataSubjectPolicy.kind` | whose session does erasing this row end? |
+ * | `systemAccessPolicy.exportSubject` | do these rows belong in a subject's export bundle? |
+ * | a field carrying `.dataCategories()` | what KIND of personal data is held? |
+ *
+ * A resource declaring NONE of them has never been asked, and that is the only state this reports.
+ * It is emphatically NOT a claim that the resource holds personal data — most resources do not, and
+ * the report says "unanswered", never "undeclared personal data".
+ *
+ * ⚠️ `RETAIN_ONLY` counts as an ANSWER, and that is the point of admitting `retentionPolicy` at all:
+ * its documented meaning is "this resource holds no personal data of its own", enforced by the
+ * factory, which refuses a scrub treatment beside it. A resource that says so has answered the
+ * question in the negative, deliberately, and must never appear in a gap list.
+ */
+export interface PersonalDataDeclarationSubject {
+    readonly retentionPolicy?: ResourceRetentionPolicy;
+    readonly dataSubjectPolicy?: ResourceDataSubjectPolicy;
+    readonly systemAccessPolicy?: ResourceSystemAccessPolicy;
+    readonly mainSchema?: unknown;
+}
+/** True when the resource declares at least one of the four — see {@link PersonalDataDeclarationSubject}. */
+export declare function resourceAnsweredThePersonalDataQuestion(configuration: PersonalDataDeclarationSubject): boolean;
+/** One resource that has said nothing, with the size of what it holds so a reader can triage. */
+export interface UnansweredPersonalDataResource {
+    readonly resourceType: string;
+    /** Top-level field count, purely to help a reader judge which to look at first. */
+    readonly fieldCount: number;
+}
+/**
+ * The APPLICATION's own resources that have said nothing about personal data.
+ *
+ * `applicationResourceTypes` is supplied by the caller rather than derived here, and that is the
+ * whole reason this takes two arguments. The engine's ~85 resources declare their own posture and an
+ * app author cannot change them, so including them would put 26 permanent entries in front of every
+ * reader of a report about THEIR application — which is how a diagnostic channel stops being read.
+ * The backend registry already separates the two at composition time, so the split is made once,
+ * where the app and core factory maps are actually distinguishable, rather than re-derived here from
+ * a key set that would then be a second enumeration of the same population.
+ */
+export declare function collectApplicationResourcesWithNoPersonalDataDeclaration(params: {
+    readonly resourceConfigurations: Readonly<Record<string, PersonalDataDeclarationSubject>>;
+    readonly applicationResourceTypes: readonly string[];
+}): readonly UnansweredPersonalDataResource[];
+/** Narrow a materialized configuration to the fields this report reads. Structural, so any shape carrying them satisfies it. */
+export declare function asPersonalDataDeclarationSubject(configuration: PersonalDataDeclarationSubject): PersonalDataDeclarationSubject;
+//# sourceMappingURL=personal-data-declaration.shared.utils.d.ts.map

package/dist/esm/compliance/privacy/personal-data-declaration.shared.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"personal-data-declaration.shared.utils.d.ts","sourceRoot":"","sources":["../../../../../src/compliance/privacy/personal-data-declaration.shared.utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,MAAM,iDAAiD,CAAC;AAGtJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,eAAe,CAAC,EAAE,uBAAuB,CAAC;IACnD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,yBAAyB,CAAC;IACvD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,0BAA0B,CAAC;IACzD,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,6GAA6G;AAC7G,wBAAgB,uCAAuC,CAAC,aAAa,EAAE,8BAA8B,GAAG,OAAO,CAK9G;AAED,iGAAiG;AACjG,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wDAAwD,CAAC,MAAM,EAAE;IAC/E,QAAQ,CAAC,sBAAsB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,8BAA8B,CAAC,CAAC,CAAC;IAC1F,QAAQ,CAAC,wBAAwB,EAAE,SAAS,MAAM,EAAE,CAAC;CACtD,GAAG,SAAS,8BAA8B,EAAE,CAgB5C;AAED,gIAAgI;AAChI,wBAAgB,gCAAgC,CAAC,aAAa,EAAE,8BAA8B,GAAG,8BAA8B,CAE9H"}