@wildo-ai/saas-models 1.1.5 → 1.1.6

package/dist/esm/compliance/privacy/legal-holds.shared.schemas.js

@@ -0,0 +1,331 @@
+/**
+ * Legal holds — a recorded decision that suspends DELETION of a defined scope until it is released (#1634).
+ *
+ * ## Why it exists
+ *
+ * Once data is deleted on a schedule (#1613's retention-class sweep), a firm under litigation, a
+ * regulator's investigation or a client dispute must be able to stop that for a defined scope, and
+ * keep proof that it did. A hold is that stop. It is a decision about a CASE, which is why it is not a
+ * retention class: a statutory period is a property of a class of data (#1635); a hold names a scope
+ * and a ground, and ends only when somebody releases it.
+ *
+ * ## What a hold suspends
+ *
+ * Every door that destroys data consults ONE predicate before destroying anything
+ * ({@link matchLegalHoldsToRows}, evaluated over the active holds the backend reads in one query):
+ *
+ * | door | what a held row gets |
+ * |---|---|
+ * | the retention-class sweep | skipped and counted, never thrown |
+ * | a subject erasure | left exactly as it is (neither deleted nor scrubbed), reported per row |
+ * | the tenant purge | the whole tenant is skipped while ANY hold on it is active |
+ * | a DELETE / DELETE_MANY, and an `onParentDelete` cascade | refused, 409 {@link LegalHoldErrorCode.LEGAL_HOLD_ACTIVE} |
+ * | file bytes in object storage | not hard-deleted while the owning row is held |
+ * | RAG chunk removal | chunks of a held row are kept |
+ *
+ * Impersonalization counts as destruction: a scrub removes exactly what a hold exists to preserve.
+ *
+ * ## What it does NOT do
+ *
+ * It does not restrict PROCESSING (reads, updates). A hold is a preservation duty, and a row that must
+ * be preserved may still be corrected; restricting processing of kept data is #1635's statutory
+ * restriction, a different obligation with a different trigger.
+ *
+ * assurance-control: WILDO.PRIVACY.STORAGE_LIMITATION — deletion suspended under a recorded legal hold.
+ */
+import { z } from 'zod';
+import { PersonalDataCategory } from './personal-data-category.shared.schemas.js';
+/** @wildo_source:part:start saas.models.privacy.legal-holds facet:layer:shared facet:audience:app-developer */
+/**
+ * WHAT a hold covers.
+ *
+ * - `ORGANIZATION` — every row the tenant owns, and the tenant itself (it is not purged).
+ * - `RESOURCE_ROWS` — the rows of ONE resource type in the tenant: the listed `rowIds`, or every row of
+ *   that type when none are listed. An explicit id list, not a query: a hold is evidence, and "which rows
+ *   were held" must be answerable from the hold alone, without re-running a filter against data that
+ *   has since changed.
+ * - `DATA_SUBJECT` — every row the subject-export graph attributes to one user. What a claim concerning
+ *   ONE person needs. See {@link LegalHoldSubjectAttributionKind} for how a row is attributed.
+ */
+export var LegalHoldScopeKind;
+(function (LegalHoldScopeKind) {
+    LegalHoldScopeKind["ORGANIZATION"] = "organization";
+    LegalHoldScopeKind["RESOURCE_ROWS"] = "resource_rows";
+    LegalHoldScopeKind["DATA_SUBJECT"] = "data_subject";
+})(LegalHoldScopeKind || (LegalHoldScopeKind = {}));
+/**
+ * WHY the data is held. Travels into every refusal and erasure report, because the ground is what a
+ * data subject is owed when their erasure is not completed.
+ *
+ * GDPR Art. 17(3)(e) (establishment, exercise or defence of legal claims) and Art. 17(3)(b) (compliance
+ * with a legal obligation) are the grounds under which a hold may also block an erasure.
+ * spec-cite: Regulation (EU) 2016/679, Art. 17(3)(b) and (e). Not legal advice.
+ */
+export var LegalHoldGround;
+(function (LegalHoldGround) {
+    /** Litigation, a dispute or a claim that is reasonably anticipated — Art. 17(3)(e). */
+    LegalHoldGround["LEGAL_CLAIMS"] = "legal_claims";
+    /** A regulator's or authority's investigation that requires the data to be preserved. */
+    LegalHoldGround["REGULATORY_INVESTIGATION"] = "regulatory_investigation";
+    /** A legal obligation to keep the data, other than a statutory retention period of a class — Art. 17(3)(b). */
+    LegalHoldGround["LEGAL_OBLIGATION"] = "legal_obligation";
+})(LegalHoldGround || (LegalHoldGround = {}));
+/**
+ * A hold's lifecycle. Two states and one direction: a released hold is kept as evidence and never
+ * reactivated — a new hold is a new row. There is no expiry state, deliberately: litigation ends by
+ * decision, not by clock, and a hold that lapses on its own is exactly the failure it exists to prevent.
+ */
+export var LegalHoldStatus;
+(function (LegalHoldStatus) {
+    LegalHoldStatus["ACTIVE"] = "active";
+    LegalHoldStatus["RELEASED"] = "released";
+})(LegalHoldStatus || (LegalHoldStatus = {}));
+/**
+ * WHO placed the hold, and therefore who may release it.
+ *
+ * A hold is released by the tier that placed it, and only by that tier. A tenant must not be able to
+ * lift a preservation duty the operator placed on it (an investigation OF the tenant), and the operator
+ * must not lift a tenant's own litigation hold on the tenant's behalf. Both tiers SEE every hold on the
+ * tenant: the tenant is owed knowing why its data is not being deleted.
+ */
+export var LegalHoldPlacementTier;
+(function (LegalHoldPlacementTier) {
+    /** Placed by the tenant's own owner, for its own data. */
+    LegalHoldPlacementTier["ORGANIZATION"] = "organization";
+    /** Placed by an application super-administrator, crossing into the tenant through the declared door. */
+    LegalHoldPlacementTier["PLATFORM"] = "platform";
+})(LegalHoldPlacementTier || (LegalHoldPlacementTier = {}));
+/**
+ * Client-branchable codes carried as `context.code` on a refusal (allow-listed by the error sanitizer).
+ */
+export var LegalHoldErrorCode;
+(function (LegalHoldErrorCode) {
+    /** A row the delete addresses is under an active legal hold. The caller is authorized; the state forbids it. */
+    LegalHoldErrorCode["LEGAL_HOLD_ACTIVE"] = "legal_hold_active";
+    /** The active holds could not be read, so whether the rows are held is unknown. Deletion is refused (fail closed). */
+    LegalHoldErrorCode["LEGAL_HOLD_STATE_UNVERIFIABLE"] = "legal_hold_state_unverifiable";
+})(LegalHoldErrorCode || (LegalHoldErrorCode = {}));
+/** The custom verbs. No generic CREATE / UPDATE / DELETE is exposed to any client. */
+export var LegalHolds_Operations;
+(function (LegalHolds_Operations) {
+    LegalHolds_Operations["PLACE"] = "place";
+    LegalHolds_Operations["RELEASE"] = "release";
+})(LegalHolds_Operations || (LegalHolds_Operations = {}));
+/** The largest explicit row list one `RESOURCE_ROWS` hold may name. A larger set is several holds, or the whole resource type. */
+export const LEGAL_HOLD_MAXIMUM_ROW_IDS = 1000;
+export const LegalHoldSchema = z.object({
+    _id: z.string().min(1).isPrimaryKey().isSummaryField(),
+    /** The held tenant. The primary scope anchor: the tenant sees every hold on its data. */
+    organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate().isAuditEvidence(),
+    scopeKind: z.enum(LegalHoldScopeKind)
+        .systemEnum('LegalHoldScopeKind')
+        .isDBIndexed()
+        .isSummaryField()
+        .excludeFromUpdate()
+        .isAuditEvidence(),
+    /** `RESOURCE_ROWS` only: the held resource type. */
+    resourceType: z.string().min(1).max(200).optional().excludeFromUpdate().isAuditEvidence(),
+    /** `RESOURCE_ROWS` only: the held rows. Absent means every row of {@link resourceType} in the tenant. */
+    rowIds: z.array(z.string().min(1)).max(LEGAL_HOLD_MAXIMUM_ROW_IDS).optional().excludeFromUpdate().isAuditEvidence(),
+    /** `DATA_SUBJECT` only: the person whose attributed rows are held. */
+    subjectUserId: z.string().min(1).optional().isDBIndexed().isForeignKey().excludeFromUpdate().isAuditEvidence(),
+    legalGround: z.enum(LegalHoldGround)
+        .systemEnum('LegalHoldGround')
+        .isSummaryField()
+        .excludeFromUpdate()
+        .isAuditEvidence(),
+    /**
+     * Why, in the placer's words: the matter, the case reference. REQUIRED.
+     *
+     * Not scrubbed on erasure, and that is a decision: a hold is the operator's defence evidence
+     * (Art. 17(3)(e)), and the matter it names is what the hold preserves. Not exported to SIEM by default
+     * either — free text is the surface most likely to name a third party.
+     */
+    justification: z.string().min(1).max(2000).excludeFromUpdate().dataCategories(PersonalDataCategory.USER_CONTENT),
+    placementTier: z.enum(LegalHoldPlacementTier)
+        .systemEnum('LegalHoldPlacementTier')
+        .isSummaryField()
+        .excludeFromCreate()
+        .excludeFromUpdate()
+        .isAuditEvidence(),
+    status: z.enum(LegalHoldStatus)
+        .systemEnum('LegalHoldStatus')
+        .default(LegalHoldStatus.ACTIVE)
+        .isDBIndexed()
+        .isSummaryField()
+        .excludeFromCreate()
+        .excludeFromUpdate()
+        .isAuditEvidence(),
+    placedByUserId: z.string().min(1).isForeignKey().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    placedAt: z.date().isSummaryField().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    releasedByUserId: z.string().min(1).optional().isForeignKey().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    /**
+     * The retention clock's closure field: a released hold is kept as `AUDIT_LOGS`-class evidence from this
+     * instant. Null while ACTIVE, so an active hold never expires. Server-owned — a caller-writable clock
+     * would be a caller-ordered delete of the evidence.
+     */
+    releasedAt: z.date().optional().isDBIndexed().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    releaseReason: z.string().max(2000).optional().excludeFromCreate().excludeFromUpdate().dataCategories(PersonalDataCategory.USER_CONTENT),
+    createdAt: z.date().optional(),
+    updatedAt: z.date().optional(),
+});
+/** The `place` request. Coherence between `scopeKind` and the three optional selectors is checked server-side. */
+export const LegalHoldPlaceRequestSchema = z.object({
+    scopeKind: z.enum(LegalHoldScopeKind).describe('What the hold covers: the whole organization, rows of one resource, or one person\'s data.'),
+    resourceType: z.string().min(1).max(200).optional().describe('For a resource-rows hold: the resource type whose rows are held.'),
+    rowIds: z.array(z.string().min(1)).min(1).max(LEGAL_HOLD_MAXIMUM_ROW_IDS).optional()
+        .describe('For a resource-rows hold: the rows held. Omit to hold every row of the resource type in the organization.'),
+    subjectUserId: z.string().min(1).optional().describe('For a data-subject hold: the user whose data is held.'),
+    legalGround: z.enum(LegalHoldGround).describe('Why the data must be preserved.'),
+    justification: z.string().min(1).max(2000).describe('The matter or case the hold preserves data for.'),
+});
+/** @wildo_source:part:end saas.models.privacy.legal-holds */
+export const LegalHoldReleaseRequestSchema = z.object({
+    releaseReason: z.string().min(1).max(2000).describe('Why the preservation duty has ended.'),
+});
+/**
+ * The scope-coherence rule for a `place` request, as one pure function the server and any client share.
+ * Returns the problems; empty means coherent.
+ */
+export function validateLegalHoldPlaceRequest(request) {
+    const problems = [];
+    switch (request.scopeKind) {
+        case LegalHoldScopeKind.ORGANIZATION:
+            if (request.resourceType !== undefined || request.rowIds !== undefined || request.subjectUserId !== undefined) {
+                problems.push('An organization hold covers the whole organization and takes no resourceType, rowIds or subjectUserId.');
+            }
+            break;
+        case LegalHoldScopeKind.RESOURCE_ROWS:
+            if (!request.resourceType)
+                problems.push('A resource-rows hold names the resourceType it holds.');
+            if (request.subjectUserId !== undefined)
+                problems.push('A resource-rows hold takes no subjectUserId.');
+            break;
+        case LegalHoldScopeKind.DATA_SUBJECT:
+            if (!request.subjectUserId)
+                problems.push('A data-subject hold names the subjectUserId whose data it holds.');
+            if (request.resourceType !== undefined || request.rowIds !== undefined)
+                problems.push('A data-subject hold takes no resourceType or rowIds.');
+            break;
+        default: {
+            const unknownKind = request.scopeKind;
+            problems.push(`Unknown legal hold scope kind '${String(unknownKind)}'.`);
+        }
+    }
+    return problems;
+}
+/**
+ * How ONE resource type's rows are attributed to a data subject, for `DATA_SUBJECT` holds.
+ *
+ * Derived from the subject-export graph of `USERS` (Art. 15 access purpose), so "the rows a hold on a
+ * person covers" and "the rows an access request about that person discloses" are the same set by
+ * construction. Where a row cannot be attributed from its own fields, the answer is UNRESOLVABLE and the
+ * row is HELD: over-preserving delays a deletion until release, under-preserving destroys evidence.
+ */
+export var LegalHoldSubjectAttributionKind;
+(function (LegalHoldSubjectAttributionKind) {
+    /** The row IS the person (`USERS`): attributed when its id is the subject. */
+    LegalHoldSubjectAttributionKind["SUBJECT_ROW"] = "subject_row";
+    /** The row carries a foreign key to `USERS` on an export edge: attributed when any of those fields names the subject. */
+    LegalHoldSubjectAttributionKind["FOREIGN_KEY"] = "foreign_key";
+    /**
+     * The resource is in the subject's export graph, but a row's attribution needs other rows (an owned
+     * descendant, or a key held on the `USERS` side). Any foreign-key field it carries still attributes it; beyond
+     * that, a row in the held tenant is held (conservative), a row outside any tenant is the person's only when its
+     * `userId` names them, and inside ANOTHER person's erasure it is that person's, not the held subject's.
+     */
+    LegalHoldSubjectAttributionKind["UNRESOLVABLE"] = "unresolvable";
+    /** Not in the subject's export graph (unrelated, or declared `exportSubject: FORBIDDEN`). A data-subject hold never covers it. */
+    LegalHoldSubjectAttributionKind["NOT_ATTRIBUTED"] = "not_attributed";
+})(LegalHoldSubjectAttributionKind || (LegalHoldSubjectAttributionKind = {}));
+/**
+ * THE hold predicate — which of `rows` are under which of `holds`. Pure; the backend reads the active
+ * holds once per call and hands them in.
+ *
+ * `erasureSubjectUserIds` is set only by a subject erasure: every row that erasure reaches in a resource
+ * of the subject's export graph IS attributed to the person being erased, so a `DATA_SUBJECT` hold on that
+ * person covers it whatever its own fields say.
+ *
+ * The ORGANIZATIONS row's tenant is its own id, so an `ORGANIZATION` hold also holds the tenant row.
+ */
+export function matchLegalHoldsToRows(input) {
+    const held = new Map();
+    if (input.holds.length === 0)
+        return held;
+    for (const candidate of input.rows) {
+        const rowOrganizationId = input.resourceType === input.organizationsResourceType
+            ? candidate.id
+            : candidate.organizationId;
+        for (const hold of input.holds) {
+            if (!legalHoldCoversRow(hold, candidate, rowOrganizationId, input))
+                continue;
+            const matches = held.get(candidate.id) ?? [];
+            matches.push({ holdId: hold._id, scopeKind: hold.scopeKind, legalGround: hold.legalGround });
+            held.set(candidate.id, matches);
+        }
+    }
+    return held;
+}
+function legalHoldCoversRow(hold, candidate, rowOrganizationId, input) {
+    switch (hold.scopeKind) {
+        case LegalHoldScopeKind.ORGANIZATION:
+            return rowOrganizationId === hold.organizationId;
+        case LegalHoldScopeKind.RESOURCE_ROWS:
+            return rowOrganizationId === hold.organizationId
+                && hold.resourceType === input.resourceType
+                && (hold.rowIds === undefined || hold.rowIds.includes(candidate.id));
+        case LegalHoldScopeKind.DATA_SUBJECT: {
+            // A person's rows outside any tenant (their user-scoped profile, preferences) are theirs wherever the
+            // claim arises, so a hold placed in one tenant covers them too. Rows of ANOTHER tenant are not this one's.
+            if (rowOrganizationId !== undefined && rowOrganizationId !== hold.organizationId)
+                return false;
+            const subject = hold.subjectUserId;
+            if (!subject)
+                return true; // incoherent hold: fail closed
+            const attribution = input.subjectAttribution;
+            if (attribution.kind === LegalHoldSubjectAttributionKind.NOT_ATTRIBUTED)
+                return false;
+            if (input.erasureSubjectUserIds?.includes(subject))
+                return true;
+            switch (attribution.kind) {
+                case LegalHoldSubjectAttributionKind.SUBJECT_ROW:
+                    return candidate.id === subject;
+                case LegalHoldSubjectAttributionKind.FOREIGN_KEY:
+                    return (attribution.foreignKeyFields ?? []).some((field) => String(candidate.row?.[field] ?? '') === subject);
+                case LegalHoldSubjectAttributionKind.UNRESOLVABLE: {
+                    // A foreign key on the row itself still names the person, when there is one.
+                    if ((attribution.foreignKeyFields ?? []).some((field) => String(candidate.row?.[field] ?? '') === subject))
+                        return true;
+                    // Inside the erasure of SOMEONE ELSE, the walk has already attributed the row: it is the erased person's,
+                    // not this subject's. Holding it would refuse their erasure on a ground belonging to another matter.
+                    if (input.erasureSubjectUserIds !== undefined)
+                        return false;
+                    // Outside any tenant, a row's owner is its `userId` (a USER_SELF row's primary scope), so a hold on one person
+                    // never reaches every other person's rows across the application.
+                    if (rowOrganizationId === undefined)
+                        return String(candidate.row?.userId ?? '') === subject;
+                    // Inside the held tenant, the row's owner cannot be read from its own fields: held, the conservative direction.
+                    return true;
+                }
+                default: {
+                    const unknownKind = attribution.kind;
+                    throw new Error(`Unknown legal hold subject attribution '${String(unknownKind)}'`);
+                }
+            }
+        }
+        default: {
+            // An unknown scope is not a reason to delete: fail closed.
+            const unknownKind = hold.scopeKind;
+            void unknownKind;
+            return true;
+        }
+    }
+}
+/**
+ * The grounds of a set of matches, de-duplicated in vocabulary order — what a refusal or a report shows.
+ */
+export function legalHoldGroundsOf(matches) {
+    const present = new Set(matches.map((match) => match.legalGround));
+    return Object.values(LegalHoldGround).filter((ground) => present.has(ground));
+}
+//# sourceMappingURL=legal-holds.shared.schemas.js.map

package/dist/esm/compliance/privacy/legal-holds.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legal-holds.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/compliance/privacy/legal-holds.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Legal holds — a recorded decision that suspends DELETION of a defined scope until it is released (#1634).\n *\n * ## Why it exists\n *\n * Once data is deleted on a schedule (#1613's retention-class sweep), a firm under litigation, a\n * regulator's investigation or a client dispute must be able to stop that for a defined scope, and\n * keep proof that it did. A hold is that stop. It is a decision about a CASE, which is why it is not a\n * retention class: a statutory period is a property of a class of data (#1635); a hold names a scope\n * and a ground, and ends only when somebody releases it.\n *\n * ## What a hold suspends\n *\n * Every door that destroys data consults ONE predicate before destroying anything\n * ({@link matchLegalHoldsToRows}, evaluated over the active holds the backend reads in one query):\n *\n * | door | what a held row gets |\n * |---|---|\n * | the retention-class sweep | skipped and counted, never thrown |\n * | a subject erasure | left exactly as it is (neither deleted nor scrubbed), reported per row |\n * | the tenant purge | the whole tenant is skipped while ANY hold on it is active |\n * | a DELETE / DELETE_MANY, and an `onParentDelete` cascade | refused, 409 {@link LegalHoldErrorCode.LEGAL_HOLD_ACTIVE} |\n * | file bytes in object storage | not hard-deleted while the owning row is held |\n * | RAG chunk removal | chunks of a held row are kept |\n *\n * Impersonalization counts as destruction: a scrub removes exactly what a hold exists to preserve.\n *\n * ## What it does NOT do\n *\n * It does not restrict PROCESSING (reads, updates). A hold is a preservation duty, and a row that must\n * be preserved may still be corrected; restricting processing of kept data is #1635's statutory\n * restriction, a different obligation with a different trigger.\n *\n * assurance-control: WILDO.PRIVACY.STORAGE_LIMITATION — deletion suspended under a recorded legal hold.\n */\n\nimport { z } from 'zod';\nimport { PersonalDataCategory } from './personal-data-category.shared.schemas';\n\n/** @wildo_source:part:start saas.models.privacy.legal-holds facet:layer:shared facet:audience:app-developer */\n/**\n * WHAT a hold covers.\n *\n * - `ORGANIZATION` — every row the tenant owns, and the tenant itself (it is not purged).\n * - `RESOURCE_ROWS` — the rows of ONE resource type in the tenant: the listed `rowIds`, or every row of\n *   that type when none are listed. An explicit id list, not a query: a hold is evidence, and \"which rows\n *   were held\" must be answerable from the hold alone, without re-running a filter against data that\n *   has since changed.\n * - `DATA_SUBJECT` — every row the subject-export graph attributes to one user. What a claim concerning\n *   ONE person needs. See {@link LegalHoldSubjectAttributionKind} for how a row is attributed.\n */\nexport enum LegalHoldScopeKind {\n  ORGANIZATION = 'organization',\n  RESOURCE_ROWS = 'resource_rows',\n  DATA_SUBJECT = 'data_subject',\n}\n\n/**\n * WHY the data is held. Travels into every refusal and erasure report, because the ground is what a\n * data subject is owed when their erasure is not completed.\n *\n * GDPR Art. 17(3)(e) (establishment, exercise or defence of legal claims) and Art. 17(3)(b) (compliance\n * with a legal obligation) are the grounds under which a hold may also block an erasure.\n * spec-cite: Regulation (EU) 2016/679, Art. 17(3)(b) and (e). Not legal advice.\n */\nexport enum LegalHoldGround {\n  /** Litigation, a dispute or a claim that is reasonably anticipated — Art. 17(3)(e). */\n  LEGAL_CLAIMS = 'legal_claims',\n  /** A regulator's or authority's investigation that requires the data to be preserved. */\n  REGULATORY_INVESTIGATION = 'regulatory_investigation',\n  /** A legal obligation to keep the data, other than a statutory retention period of a class — Art. 17(3)(b). */\n  LEGAL_OBLIGATION = 'legal_obligation',\n}\n\n/**\n * A hold's lifecycle. Two states and one direction: a released hold is kept as evidence and never\n * reactivated — a new hold is a new row. There is no expiry state, deliberately: litigation ends by\n * decision, not by clock, and a hold that lapses on its own is exactly the failure it exists to prevent.\n */\nexport enum LegalHoldStatus {\n  ACTIVE = 'active',\n  RELEASED = 'released',\n}\n\n/**\n * WHO placed the hold, and therefore who may release it.\n *\n * A hold is released by the tier that placed it, and only by that tier. A tenant must not be able to\n * lift a preservation duty the operator placed on it (an investigation OF the tenant), and the operator\n * must not lift a tenant's own litigation hold on the tenant's behalf. Both tiers SEE every hold on the\n * tenant: the tenant is owed knowing why its data is not being deleted.\n */\nexport enum LegalHoldPlacementTier {\n  /** Placed by the tenant's own owner, for its own data. */\n  ORGANIZATION = 'organization',\n  /** Placed by an application super-administrator, crossing into the tenant through the declared door. */\n  PLATFORM = 'platform',\n}\n\n/**\n * Client-branchable codes carried as `context.code` on a refusal (allow-listed by the error sanitizer).\n */\nexport enum LegalHoldErrorCode {\n  /** A row the delete addresses is under an active legal hold. The caller is authorized; the state forbids it. */\n  LEGAL_HOLD_ACTIVE = 'legal_hold_active',\n  /** The active holds could not be read, so whether the rows are held is unknown. Deletion is refused (fail closed). */\n  LEGAL_HOLD_STATE_UNVERIFIABLE = 'legal_hold_state_unverifiable',\n}\n\n/** The custom verbs. No generic CREATE / UPDATE / DELETE is exposed to any client. */\nexport enum LegalHolds_Operations {\n  PLACE = 'place',\n  RELEASE = 'release',\n}\n\n/** The largest explicit row list one `RESOURCE_ROWS` hold may name. A larger set is several holds, or the whole resource type. */\nexport const LEGAL_HOLD_MAXIMUM_ROW_IDS = 1000;\n\nexport const LegalHoldSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n\n  /** The held tenant. The primary scope anchor: the tenant sees every hold on its data. */\n  organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate().isAuditEvidence(),\n\n  scopeKind: z.enum(LegalHoldScopeKind)\n    .systemEnum('LegalHoldScopeKind')\n    .isDBIndexed()\n    .isSummaryField()\n    .excludeFromUpdate()\n    .isAuditEvidence(),\n\n  /** `RESOURCE_ROWS` only: the held resource type. */\n  resourceType: z.string().min(1).max(200).optional().excludeFromUpdate().isAuditEvidence(),\n\n  /** `RESOURCE_ROWS` only: the held rows. Absent means every row of {@link resourceType} in the tenant. */\n  rowIds: z.array(z.string().min(1)).max(LEGAL_HOLD_MAXIMUM_ROW_IDS).optional().excludeFromUpdate().isAuditEvidence(),\n\n  /** `DATA_SUBJECT` only: the person whose attributed rows are held. */\n  subjectUserId: z.string().min(1).optional().isDBIndexed().isForeignKey().excludeFromUpdate().isAuditEvidence(),\n\n  legalGround: z.enum(LegalHoldGround)\n    .systemEnum('LegalHoldGround')\n    .isSummaryField()\n    .excludeFromUpdate()\n    .isAuditEvidence(),\n\n  /**\n   * Why, in the placer's words: the matter, the case reference. REQUIRED.\n   *\n   * Not scrubbed on erasure, and that is a decision: a hold is the operator's defence evidence\n   * (Art. 17(3)(e)), and the matter it names is what the hold preserves. Not exported to SIEM by default\n   * either — free text is the surface most likely to name a third party.\n   */\n  justification: z.string().min(1).max(2000).excludeFromUpdate().dataCategories(PersonalDataCategory.USER_CONTENT),\n\n  placementTier: z.enum(LegalHoldPlacementTier)\n    .systemEnum('LegalHoldPlacementTier')\n    .isSummaryField()\n    .excludeFromCreate()\n    .excludeFromUpdate()\n    .isAuditEvidence(),\n\n  status: z.enum(LegalHoldStatus)\n    .systemEnum('LegalHoldStatus')\n    .default(LegalHoldStatus.ACTIVE)\n    .isDBIndexed()\n    .isSummaryField()\n    .excludeFromCreate()\n    .excludeFromUpdate()\n    .isAuditEvidence(),\n\n  placedByUserId: z.string().min(1).isForeignKey().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),\n  placedAt: z.date().isSummaryField().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),\n\n  releasedByUserId: z.string().min(1).optional().isForeignKey().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),\n  /**\n   * The retention clock's closure field: a released hold is kept as `AUDIT_LOGS`-class evidence from this\n   * instant. Null while ACTIVE, so an active hold never expires. Server-owned — a caller-writable clock\n   * would be a caller-ordered delete of the evidence.\n   */\n  releasedAt: z.date().optional().isDBIndexed().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),\n  releaseReason: z.string().max(2000).optional().excludeFromCreate().excludeFromUpdate().dataCategories(PersonalDataCategory.USER_CONTENT),\n\n  createdAt: z.date().optional(),\n  updatedAt: z.date().optional(),\n});\n\nexport type LegalHold = z.infer<typeof LegalHoldSchema>;\n\n/** The `place` request. Coherence between `scopeKind` and the three optional selectors is checked server-side. */\nexport const LegalHoldPlaceRequestSchema = z.object({\n  scopeKind: z.enum(LegalHoldScopeKind).describe('What the hold covers: the whole organization, rows of one resource, or one person\\'s data.'),\n  resourceType: z.string().min(1).max(200).optional().describe('For a resource-rows hold: the resource type whose rows are held.'),\n  rowIds: z.array(z.string().min(1)).min(1).max(LEGAL_HOLD_MAXIMUM_ROW_IDS).optional()\n    .describe('For a resource-rows hold: the rows held. Omit to hold every row of the resource type in the organization.'),\n  subjectUserId: z.string().min(1).optional().describe('For a data-subject hold: the user whose data is held.'),\n  legalGround: z.enum(LegalHoldGround).describe('Why the data must be preserved.'),\n  justification: z.string().min(1).max(2000).describe('The matter or case the hold preserves data for.'),\n});\nexport type LegalHoldPlaceRequest = z.infer<typeof LegalHoldPlaceRequestSchema>;\n/** @wildo_source:part:end saas.models.privacy.legal-holds */\n\nexport const LegalHoldReleaseRequestSchema = z.object({\n  releaseReason: z.string().min(1).max(2000).describe('Why the preservation duty has ended.'),\n});\n\n/**\n * The scope-coherence rule for a `place` request, as one pure function the server and any client share.\n * Returns the problems; empty means coherent.\n */\nexport function validateLegalHoldPlaceRequest(request: LegalHoldPlaceRequest): string[] {\n  const problems: string[] = [];\n  switch (request.scopeKind) {\n    case LegalHoldScopeKind.ORGANIZATION:\n      if (request.resourceType !== undefined || request.rowIds !== undefined || request.subjectUserId !== undefined) {\n        problems.push('An organization hold covers the whole organization and takes no resourceType, rowIds or subjectUserId.');\n      }\n      break;\n    case LegalHoldScopeKind.RESOURCE_ROWS:\n      if (!request.resourceType) problems.push('A resource-rows hold names the resourceType it holds.');\n      if (request.subjectUserId !== undefined) problems.push('A resource-rows hold takes no subjectUserId.');\n      break;\n    case LegalHoldScopeKind.DATA_SUBJECT:\n      if (!request.subjectUserId) problems.push('A data-subject hold names the subjectUserId whose data it holds.');\n      if (request.resourceType !== undefined || request.rowIds !== undefined) problems.push('A data-subject hold takes no resourceType or rowIds.');\n      break;\n    default: {\n      const unknownKind: never = request.scopeKind;\n      problems.push(`Unknown legal hold scope kind '${String(unknownKind)}'.`);\n    }\n  }\n  return problems;\n}\n\n/**\n * How ONE resource type's rows are attributed to a data subject, for `DATA_SUBJECT` holds.\n *\n * Derived from the subject-export graph of `USERS` (Art. 15 access purpose), so \"the rows a hold on a\n * person covers\" and \"the rows an access request about that person discloses\" are the same set by\n * construction. Where a row cannot be attributed from its own fields, the answer is UNRESOLVABLE and the\n * row is HELD: over-preserving delays a deletion until release, under-preserving destroys evidence.\n */\nexport enum LegalHoldSubjectAttributionKind {\n  /** The row IS the person (`USERS`): attributed when its id is the subject. */\n  SUBJECT_ROW = 'subject_row',\n  /** The row carries a foreign key to `USERS` on an export edge: attributed when any of those fields names the subject. */\n  FOREIGN_KEY = 'foreign_key',\n  /**\n   * The resource is in the subject's export graph, but a row's attribution needs other rows (an owned\n   * descendant, or a key held on the `USERS` side). Any foreign-key field it carries still attributes it; beyond\n   * that, a row in the held tenant is held (conservative), a row outside any tenant is the person's only when its\n   * `userId` names them, and inside ANOTHER person's erasure it is that person's, not the held subject's.\n   */\n  UNRESOLVABLE = 'unresolvable',\n  /** Not in the subject's export graph (unrelated, or declared `exportSubject: FORBIDDEN`). A data-subject hold never covers it. */\n  NOT_ATTRIBUTED = 'not_attributed',\n}\n\nexport interface LegalHoldSubjectAttribution {\n  readonly kind: LegalHoldSubjectAttributionKind;\n  /** The row fields naming a user — the whole answer for FOREIGN_KEY, a first answer for UNRESOLVABLE. */\n  readonly foreignKeyFields?: readonly string[];\n}\n\n/** An active hold, as the predicate needs it. */\nexport type ActiveLegalHold = Pick<LegalHold, '_id' | 'organizationId' | 'scopeKind' | 'resourceType' | 'rowIds' | 'subjectUserId' | 'legalGround'>;\n\n/** One row a deletion path is about to destroy. */\nexport interface LegalHoldCandidateRow {\n  readonly id: string;\n  /** The tenant the row belongs to; absent for a row with no organization scope. */\n  readonly organizationId?: string;\n  /** The row's fields, for foreign-key attribution. */\n  readonly row?: Record<string, unknown>;\n}\n\n/** Why a row is held: the hold and its ground. */\nexport interface LegalHoldMatch {\n  readonly holdId: string;\n  readonly scopeKind: LegalHoldScopeKind;\n  readonly legalGround: LegalHoldGround;\n}\n\n/**\n * THE hold predicate — which of `rows` are under which of `holds`. Pure; the backend reads the active\n * holds once per call and hands them in.\n *\n * `erasureSubjectUserIds` is set only by a subject erasure: every row that erasure reaches in a resource\n * of the subject's export graph IS attributed to the person being erased, so a `DATA_SUBJECT` hold on that\n * person covers it whatever its own fields say.\n *\n * The ORGANIZATIONS row's tenant is its own id, so an `ORGANIZATION` hold also holds the tenant row.\n */\nexport function matchLegalHoldsToRows(input: {\n  readonly holds: readonly ActiveLegalHold[];\n  readonly resourceType: string;\n  readonly rows: readonly LegalHoldCandidateRow[];\n  readonly organizationsResourceType: string;\n  readonly subjectAttribution: LegalHoldSubjectAttribution;\n  readonly erasureSubjectUserIds?: readonly string[];\n}): Map<string, LegalHoldMatch[]> {\n  const held = new Map<string, LegalHoldMatch[]>();\n  if (input.holds.length === 0) return held;\n  for (const candidate of input.rows) {\n    const rowOrganizationId = input.resourceType === input.organizationsResourceType\n      ? candidate.id\n      : candidate.organizationId;\n    for (const hold of input.holds) {\n      if (!legalHoldCoversRow(hold, candidate, rowOrganizationId, input)) continue;\n      const matches = held.get(candidate.id) ?? [];\n      matches.push({ holdId: hold._id, scopeKind: hold.scopeKind, legalGround: hold.legalGround });\n      held.set(candidate.id, matches);\n    }\n  }\n  return held;\n}\n\nfunction legalHoldCoversRow(\n  hold: ActiveLegalHold,\n  candidate: LegalHoldCandidateRow,\n  rowOrganizationId: string | undefined,\n  input: Parameters<typeof matchLegalHoldsToRows>[0],\n): boolean {\n  switch (hold.scopeKind) {\n    case LegalHoldScopeKind.ORGANIZATION:\n      return rowOrganizationId === hold.organizationId;\n    case LegalHoldScopeKind.RESOURCE_ROWS:\n      return rowOrganizationId === hold.organizationId\n        && hold.resourceType === input.resourceType\n        && (hold.rowIds === undefined || hold.rowIds.includes(candidate.id));\n    case LegalHoldScopeKind.DATA_SUBJECT: {\n      // A person's rows outside any tenant (their user-scoped profile, preferences) are theirs wherever the\n      // claim arises, so a hold placed in one tenant covers them too. Rows of ANOTHER tenant are not this one's.\n      if (rowOrganizationId !== undefined && rowOrganizationId !== hold.organizationId) return false;\n      const subject = hold.subjectUserId;\n      if (!subject) return true; // incoherent hold: fail closed\n      const attribution = input.subjectAttribution;\n      if (attribution.kind === LegalHoldSubjectAttributionKind.NOT_ATTRIBUTED) return false;\n      if (input.erasureSubjectUserIds?.includes(subject)) return true;\n      switch (attribution.kind) {\n        case LegalHoldSubjectAttributionKind.SUBJECT_ROW:\n          return candidate.id === subject;\n        case LegalHoldSubjectAttributionKind.FOREIGN_KEY:\n          return (attribution.foreignKeyFields ?? []).some((field) => String(candidate.row?.[field] ?? '') === subject);\n        case LegalHoldSubjectAttributionKind.UNRESOLVABLE: {\n          // A foreign key on the row itself still names the person, when there is one.\n          if ((attribution.foreignKeyFields ?? []).some((field) => String(candidate.row?.[field] ?? '') === subject)) return true;\n          // Inside the erasure of SOMEONE ELSE, the walk has already attributed the row: it is the erased person's,\n          // not this subject's. Holding it would refuse their erasure on a ground belonging to another matter.\n          if (input.erasureSubjectUserIds !== undefined) return false;\n          // Outside any tenant, a row's owner is its `userId` (a USER_SELF row's primary scope), so a hold on one person\n          // never reaches every other person's rows across the application.\n          if (rowOrganizationId === undefined) return String(candidate.row?.userId ?? '') === subject;\n          // Inside the held tenant, the row's owner cannot be read from its own fields: held, the conservative direction.\n          return true;\n        }\n        default: {\n          const unknownKind: never = attribution.kind;\n          throw new Error(`Unknown legal hold subject attribution '${String(unknownKind)}'`);\n        }\n      }\n    }\n    default: {\n      // An unknown scope is not a reason to delete: fail closed.\n      const unknownKind: never = hold.scopeKind;\n      void unknownKind;\n      return true;\n    }\n  }\n}\n\n/** One row a subject erasure left untouched because a legal hold covers it (#1634). */\nexport interface SubjectErasureLegalHoldRetention {\n  resourceType: string;\n  rowId: string;\n  /** The grounds of every hold covering the row — what the data subject is told. */\n  legalGrounds: LegalHoldGround[];\n  holdIds: string[];\n}\n\n/**\n * The grounds of a set of matches, de-duplicated in vocabulary order — what a refusal or a report shows.\n */\nexport function legalHoldGroundsOf(matches: readonly LegalHoldMatch[]): LegalHoldGround[] {\n  const present = new Set(matches.map((match) => match.legalGround));\n  return Object.values(LegalHoldGround).filter((ground) => present.has(ground));\n}\n"]}

package/dist/esm/compliance/privacy/operator-compliance-identity.shared.schemas.d.ts

@@ -46,14 +46,21 @@ export declare enum OperatorProcessingRole {
  * A B2B SaaS is typically a PROCESSOR for the records its customers put in, and a CONTROLLER for the
  * account and billing data of the people who administer them — simultaneously, in one product.
  *
- * `dataScope` is prose the operator writes, deliberately. Nothing structured exists to key it to: the
- * processing purposes a notice states are derived from the application's vision and requirements as
- * PROSE, so a ref here would point at nothing.
+ * `dataScope` is prose the operator writes, deliberately: it names a POPULATION of data ("customer records in a
+ * workspace"), not a processing purpose, so a lawful basis's `purposeRef` (#1709) is not what it would key to. No
+ * structured population vocabulary exists yet, and a ref to nothing would be worse than prose.
  */
 export declare const OperatorRoleAllocationSchema: z.ZodObject<{
     /** Which data this role covers, in the operator's own words — "customer records in a workspace". */
     dataScope: z.ZodString;
     role: z.ZodEnum<typeof OperatorProcessingRole>;
+    /**
+     * The resource types this role covers — the TYPED half of `dataScope` (#1710), so a running erasure or export can
+     * say who owes the Art. 19 communication for the subject in front of it. Optional: an allocation in prose only is
+     * still a valid statement for a notice, and a subject whose resource type no allocation names is reported as
+     * ROLE UNDECLARED, never guessed. `dataScope` stays the words a notice uses.
+     */
+    resourceTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 export type OperatorRoleAllocation = z.infer<typeof OperatorRoleAllocationSchema>;
 /**
@@ -64,6 +71,16 @@ export type OperatorRoleAllocation = z.infer<typeof OperatorRoleAllocationSchema
 export declare const OperatorLawfulBasisSchema: z.ZodObject<{
     /** The purpose, in the operator's own words. Matches how the notice states purposes: prose, not a ref. */
     purpose: z.ZodString;
+    /**
+     * A STABLE id for this purpose, which a provider's or a system of record's compliance choice names
+     * (`providerComplianceChoices.<ref>.purposeRefs`) to say which purpose sending it data serves (#1709).
+     *
+     * Separate from `purpose` because the prose is the notice's wording and changes when the operator rewords it, while
+     * a link to it must survive the rewording. OPTIONAL, like every other part of this identity (#225): a basis with no
+     * ref is still a basis, and a recipient cannot link to it — which the recipients report names as a purpose not
+     * linked, never as a recipient with no purpose.
+     */
+    purposeRef: z.ZodOptional<z.ZodString>;
     basis: z.ZodEnum<typeof LawfulBasis>;
     /**
      * The assessment behind the basis. REQUIRED for `LEGITIMATE_INTERESTS`, which is the only basis
@@ -220,6 +237,13 @@ export declare const ApplicationOperatorComplianceIdentitySchema: z.ZodObject<{
         /** Which data this role covers, in the operator's own words — "customer records in a workspace". */
         dataScope: z.ZodString;
         role: z.ZodEnum<typeof OperatorProcessingRole>;
+        /**
+         * The resource types this role covers — the TYPED half of `dataScope` (#1710), so a running erasure or export can
+         * say who owes the Art. 19 communication for the subject in front of it. Optional: an allocation in prose only is
+         * still a valid statement for a notice, and a subject whose resource type no allocation names is reported as
+         * ROLE UNDECLARED, never guessed. `dataScope` stays the words a notice uses.
+         */
+        resourceTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>>;
     /**
      * The lawful basis relied on, per processing purpose. At least one.
@@ -231,6 +255,16 @@ export declare const ApplicationOperatorComplianceIdentitySchema: z.ZodObject<{
     lawfulBases: z.ZodOptional<z.ZodArray<z.ZodObject<{
         /** The purpose, in the operator's own words. Matches how the notice states purposes: prose, not a ref. */
         purpose: z.ZodString;
+        /**
+         * A STABLE id for this purpose, which a provider's or a system of record's compliance choice names
+         * (`providerComplianceChoices.<ref>.purposeRefs`) to say which purpose sending it data serves (#1709).
+         *
+         * Separate from `purpose` because the prose is the notice's wording and changes when the operator rewords it, while
+         * a link to it must survive the rewording. OPTIONAL, like every other part of this identity (#225): a basis with no
+         * ref is still a basis, and a recipient cannot link to it — which the recipients report names as a purpose not
+         * linked, never as a recipient with no purpose.
+         */
+        purposeRef: z.ZodOptional<z.ZodString>;
         basis: z.ZodEnum<typeof LawfulBasis>;
         /**
          * The assessment behind the basis. REQUIRED for `LEGITIMATE_INTERESTS`, which is the only basis

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

@@ -1 +1 @@
-{"version":3,"file":"operator-compliance-identity.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/compliance/privacy/operator-compliance-identity.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE3D;;;;;;;;;;GAUG;AACH,oBAAY,WAAW;IACrB,gGAAgG;IAChG,OAAO,YAAY;IACnB,iGAAiG;IACjG,QAAQ,aAAa;IACrB,+FAA+F;IAC/F,gBAAgB,qBAAqB;IACrC,4FAA4F;IAC5F,eAAe,oBAAoB;IACnC,wFAAwF;IACxF,WAAW,gBAAgB;IAC3B;;;;OAIG;IACH,oBAAoB,yBAAyB;CAC9C;AAED,6GAA6G;AAC7G,oBAAY,sBAAsB;IAChC,sDAAsD;IACtD,UAAU,eAAe;IACzB,mHAAmH;IACnH,SAAS,cAAc;IACvB,oHAAoH;IACpH,gBAAgB,qBAAqB;CACtC;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,4BAA4B;IACvC,oGAAoG;;;kBAGpG,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;IACpC,0GAA0G;;;IAG1G;;;OAGG;;kBAgBH,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,eAAO,MAAM,+BAA+B;IAC1C;;;;;;;;;OASG;;IAEH;;;;;;OAMG;;kBA2BH,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,2CAA2C;IACtD,2HAA2H;;IAE3H,qGAAqG;;IAErG;;;;;OAKG;;IAEH;;;;;;OAMG;;;;;IAKH;;;;OAIG;;QA9MH,oGAAoG;;;;IAgNpG;;;;;;OAMG;;QA1MH,0GAA0G;;;QAG1G;;;WAGG;;;IAsMH;;;;;;OAMG;;QAvIH;;;;;;;;;WASG;;QAEH;;;;;;WAMG;;;IAwHH;;;;;;;;;OASG;;kBAsBH,CAAC;AACH,MAAM,MAAM,qCAAqC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2CAA2C,CAAC,CAAC;AAGhH;;;;;;;;;;;;GAYG;AACH,oBAAY,8BAA8B;IACxC,iBAAiB,oBAAoB;IACrC,kBAAkB,sBAAsB;IACxC,eAAe,mBAAmB;IAClC,gBAAgB,oBAAoB;IACpC,YAAY,gBAAgB;IAC5B,qCAAqC,uCAAuC;CAC7E;AAED;;;;;;;GAOG;AACH,wBAAgB,0CAA0C,CACxD,QAAQ,EAAE,qCAAqC,GAAG,SAAS,GAC1D,SAAS,8BAA8B,EAAE,CAS3C;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,qCAAqC,GAAG,SAAS,WAAW,EAAE,GAAG,SAAS,CAKvH;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CAAC,QAAQ,EAAE,qCAAqC,GAAG,OAAO,GAAG,SAAS,CAGxH"}
+{"version":3,"file":"operator-compliance-identity.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/compliance/privacy/operator-compliance-identity.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAG3D;;;;;;;;;;GAUG;AACH,oBAAY,WAAW;IACrB,gGAAgG;IAChG,OAAO,YAAY;IACnB,iGAAiG;IACjG,QAAQ,aAAa;IACrB,+FAA+F;IAC/F,gBAAgB,qBAAqB;IACrC,4FAA4F;IAC5F,eAAe,oBAAoB;IACnC,wFAAwF;IACxF,WAAW,gBAAgB;IAC3B;;;;OAIG;IACH,oBAAoB,yBAAyB;CAC9C;AAED,6GAA6G;AAC7G,oBAAY,sBAAsB;IAChC,sDAAsD;IACtD,UAAU,eAAe;IACzB,mHAAmH;IACnH,SAAS,cAAc;IACvB,oHAAoH;IACpH,gBAAgB,qBAAqB;CACtC;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,4BAA4B;IACvC,oGAAoG;;;IAGpG;;;;;OAKG;;kBAEH,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;IACpC,0GAA0G;;IAE1G;;;;;;;;OAQG;;;IAGH;;;OAGG;;kBAgBH,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,eAAO,MAAM,+BAA+B;IAC1C;;;;;;;;;OASG;;IAEH;;;;;;OAMG;;kBA2BH,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,2CAA2C;IACtD,2HAA2H;;IAE3H,qGAAqG;;IAErG;;;;;OAKG;;IAEH;;;;;;OAMG;;;;;IAKH;;;;OAIG;;QA/NH,oGAAoG;;;QAGpG;;;;;WAKG;;;IAyNH;;;;;;OAMG;;QApNH,0GAA0G;;QAE1G;;;;;;;;WAQG;;;QAGH;;;WAGG;;;IAgNH;;;;;;OAMG;;QAjJH;;;;;;;;;WASG;;QAEH;;;;;;WAMG;;;IAkIH;;;;;;;;;OASG;;kBAsBH,CAAC;AACH,MAAM,MAAM,qCAAqC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2CAA2C,CAAC,CAAC;AAGhH;;;;;;;;;;;;GAYG;AACH,oBAAY,8BAA8B;IACxC,iBAAiB,oBAAoB;IACrC,kBAAkB,sBAAsB;IACxC,eAAe,mBAAmB;IAClC,gBAAgB,oBAAoB;IACpC,YAAY,gBAAgB;IAC5B,qCAAqC,uCAAuC;CAC7E;AAED;;;;;;;GAOG;AACH,wBAAgB,0CAA0C,CACxD,QAAQ,EAAE,qCAAqC,GAAG,SAAS,GAC1D,SAAS,8BAA8B,EAAE,CAS3C;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,qCAAqC,GAAG,SAAS,WAAW,EAAE,GAAG,SAAS,CAKvH;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CAAC,QAAQ,EAAE,qCAAqC,GAAG,OAAO,GAAG,SAAS,CAGxH"}

package/dist/esm/compliance/privacy/operator-compliance-identity.shared.schemas.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { ConsentPurpose } from './consent-purposes.shared.js';
+import { LawfulBasisPurposeRefSchema } from './purpose-ref.shared.schemas.js';
 /**
  * GDPR Art. 6(1) — the six lawful bases, closed by the article.
  *
@@ -48,14 +49,21 @@ export var OperatorProcessingRole;
  * A B2B SaaS is typically a PROCESSOR for the records its customers put in, and a CONTROLLER for the
  * account and billing data of the people who administer them — simultaneously, in one product.
  *
- * `dataScope` is prose the operator writes, deliberately. Nothing structured exists to key it to: the
- * processing purposes a notice states are derived from the application's vision and requirements as
- * PROSE, so a ref here would point at nothing.
+ * `dataScope` is prose the operator writes, deliberately: it names a POPULATION of data ("customer records in a
+ * workspace"), not a processing purpose, so a lawful basis's `purposeRef` (#1709) is not what it would key to. No
+ * structured population vocabulary exists yet, and a ref to nothing would be worse than prose.
  */
 export const OperatorRoleAllocationSchema = z.strictObject({
     /** Which data this role covers, in the operator's own words — "customer records in a workspace". */
     dataScope: z.string().trim().min(1),
     role: z.enum(OperatorProcessingRole),
+    /**
+     * The resource types this role covers — the TYPED half of `dataScope` (#1710), so a running erasure or export can
+     * say who owes the Art. 19 communication for the subject in front of it. Optional: an allocation in prose only is
+     * still a valid statement for a notice, and a subject whose resource type no allocation names is reported as
+     * ROLE UNDECLARED, never guessed. `dataScope` stays the words a notice uses.
+     */
+    resourceTypes: z.array(z.string().trim().min(1)).min(1).optional(),
 });
 /**
  * One processing purpose and the basis the operator relies on for it.
@@ -65,6 +73,16 @@ export const OperatorRoleAllocationSchema = z.strictObject({
 export const OperatorLawfulBasisSchema = z.strictObject({
     /** The purpose, in the operator's own words. Matches how the notice states purposes: prose, not a ref. */
     purpose: z.string().trim().min(1),
+    /**
+     * A STABLE id for this purpose, which a provider's or a system of record's compliance choice names
+     * (`providerComplianceChoices.<ref>.purposeRefs`) to say which purpose sending it data serves (#1709).
+     *
+     * Separate from `purpose` because the prose is the notice's wording and changes when the operator rewords it, while
+     * a link to it must survive the rewording. OPTIONAL, like every other part of this identity (#225): a basis with no
+     * ref is still a basis, and a recipient cannot link to it — which the recipients report names as a purpose not
+     * linked, never as a recipient with no purpose.
+     */
+    purposeRef: LawfulBasisPurposeRefSchema.optional(),
     basis: z.enum(LawfulBasis),
     /**
      * The assessment behind the basis. REQUIRED for `LEGITIMATE_INTERESTS`, which is the only basis
@@ -262,7 +280,18 @@ export const ApplicationOperatorComplianceIdentitySchema = z.strictObject({
      * declaring no basis at all is a refusal wearing a declaration's clothes, and it would land as a
      * complete answer.
      */
-    lawfulBases: z.array(OperatorLawfulBasisSchema).min(1).optional(),
+    lawfulBases: z.array(OperatorLawfulBasisSchema).min(1).superRefine((bases, context) => {
+        // A purpose ref names ONE purpose, or a recipient linking to it would be linked to two (#1709).
+        const seen = new Set();
+        bases.forEach((entry, index) => {
+            if (entry.purposeRef === undefined)
+                return;
+            if (seen.has(entry.purposeRef)) {
+                context.addIssue({ code: 'custom', path: [index, 'purposeRef'], message: `purpose ref "${entry.purposeRef}" names more than one purpose` });
+            }
+            seen.add(entry.purposeRef);
+        });
+    }).optional(),
     /**
      * What a person must consent to in order to use the service at all (issue #139).
      *