@wildo-ai/saas-models 1.0.1 → 1.1.0

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

@@ -0,0 +1,230 @@
+import { z } from 'zod';
+import { DataProcessingConsent } from './privacy.shared.schemas';
+/**
+ * GDPR Art. 6(1) — the six lawful bases, closed by the article.
+ *
+ * Enumerated individually rather than carried as prose because each carries a different obligation:
+ * consent must be withdrawable, legitimate interests needs a balancing assessment, a legal obligation
+ * must name the law. "We have a lawful basis" is not a disclosure; a notice must say WHICH.
+ *
+ * spec-cite: GDPR Art. 6(1)(a)–(f).
+ */
+export declare enum LawfulBasis {
+    /** Art. 6(1)(a) — the subject consented to the processing for one or more specific purposes. */
+    CONSENT = "CONSENT",
+    /** Art. 6(1)(b) — necessary to perform a contract with the subject, or pre-contractual steps. */
+    CONTRACT = "CONTRACT",
+    /** Art. 6(1)(c) — necessary to comply with a legal obligation the controller is subject to. */
+    LEGAL_OBLIGATION = "LEGAL_OBLIGATION",
+    /** Art. 6(1)(d) — necessary to protect vital interests of the subject or another person. */
+    VITAL_INTERESTS = "VITAL_INTERESTS",
+    /** Art. 6(1)(e) — necessary for a task in the public interest or official authority. */
+    PUBLIC_TASK = "PUBLIC_TASK",
+    /**
+     * Art. 6(1)(f) — necessary for legitimate interests, except where overridden by the subject's
+     * rights. The only basis requiring a balancing assessment, which is why declaring it without one
+     * is refused below.
+     */
+    LEGITIMATE_INTERESTS = "LEGITIMATE_INTERESTS"
+}
+/** Whether the operator decides the purposes of a processing, carries them out for someone else, or both. */
+export declare enum OperatorProcessingRole {
+    /** The operator determines the purposes and means. */
+    CONTROLLER = "CONTROLLER",
+    /** The operator processes on a customer's documented instructions — the usual B2B posture for customer records. */
+    PROCESSOR = "PROCESSOR",
+    /** The operator and another party jointly determine purposes and means, and must have an arrangement saying how. */
+    JOINT_CONTROLLER = "JOINT_CONTROLLER"
+}
+/**
+ * ONE role, over ONE population of data.
+ *
+ * A single role field would be the wrong shape, and the produced notice said so before this existed:
+ * *"This notice therefore does not assign a single legal role to all data processed in a workspace."*
+ * 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.
+ */
+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>;
+}, z.core.$strict>;
+export type OperatorRoleAllocation = z.infer<typeof OperatorRoleAllocationSchema>;
+/** One processing purpose and the basis the operator relies on for it. */
+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;
+    basis: z.ZodEnum<typeof LawfulBasis>;
+    /**
+     * The assessment behind the basis. REQUIRED for `LEGITIMATE_INTERESTS`, which is the only basis
+     * that needs a balancing test — see the superRefine below.
+     */
+    assessmentNote: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type OperatorLawfulBasis = z.infer<typeof OperatorLawfulBasisSchema>;
+/**
+ * What a person must agree to in order to USE the service at all (issue #139).
+ *
+ * ## The near-miss this exists because of
+ *
+ * `analytics.requiredConsent` already exists and governs ANALYTICS alone. The compliance partial
+ * described it as "the minimum a person must give to use the service" until 2026-08-30 — a much
+ * larger claim about a much narrower field. A drafter following that wording would have published
+ * that a person must consent to analytics in order to use the product: false, and false about the one
+ * subject a reader is most likely to act on.
+ *
+ * Correcting it left a real hole, which a produced notice then reported in its own words:
+ * *"There is no declared surface for recording a service-wide consent requirement distinct from
+ * analytics consent."* This is that surface.
+ *
+ * ## Why the floor may be NONE, and usually should be
+ *
+ * Consent is ONE Art. 6(1) basis among six, and for most B2B SaaS the basis for core processing is
+ * CONTRACT — a person uses the product because their employer signed for it, not because they
+ * consented. A required level above `NONE` says the opposite, so declaring one is a claim about the
+ * lawful basis and not merely a UI gate.
+ *
+ * `NONE` is therefore both the default and the honest answer for most applications: *nothing is
+ * gated on consent; the lawful basis lives in {@link ApplicationOperatorComplianceIdentitySchema.lawfulBases}.*
+ * A field that pushed applications toward declaring consent would be worse than the gap it closes.
+ *
+ * ⚠️ Declaring a level here does NOT make consent the lawful basis for anything. It states a gate.
+ * The basis is declared per purpose, separately, and the two disagreeing is the shape a reviewer
+ * needs to see rather than one the schema should quietly reconcile.
+ */
+export declare const ServiceConsentRequirementSchema: z.ZodObject<{
+    /**
+     * The minimum consent a person must give to use the service.
+     *
+     * `NONE` means nothing is gated on consent — the common and usually correct answer. It is a
+     * DECLARATION, not an absence: an application that says `NONE` has answered the question, which is
+     * what separates it from one that has not been asked.
+     */
+    requiredLevel: z.ZodEnum<typeof DataProcessingConsent>;
+    /**
+     * What this gate actually controls, in the operator's own words.
+     *
+     * REQUIRED whenever the level is above `NONE`, because a gate nobody can describe is a gate nobody
+     * can honour — enforced below. A notice stating "consent is required" without saying what it
+     * governs tells a person they must agree to something unnamed.
+     */
+    gatedProcessing: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ServiceConsentRequirement = z.infer<typeof ServiceConsentRequirementSchema>;
+/**
+ * WHO is publishing this notice, under what legal role, on what basis — the operator's own compliance
+ * identity (issue #131).
+ *
+ * ## Why this exists, and why in configuration
+ *
+ * A produced compliance document asked three questions the application had nowhere to answer:
+ * who operates the service, in what role, and on what lawful basis. Measured 2026-08-30, the only
+ * `legalEntityName` anywhere in the compliance model was the PROCESSOR's, from the register in issue
+ * #88 — nothing described the operator.
+ *
+ * That is not merely an empty field. A landing REPLACES the produced document on every run, so an
+ * operator who answered by editing the document lost the answer on the next regeneration:
+ * `.claude/rules/one-source-of-truth.md`'s test failing in the direction that matters — delete and
+ * re-run, and you lose TRUTH rather than TIME.
+ *
+ * Configuration rather than a governed document, and identity and basis together rather than split.
+ * They are two halves of ONE clause a reader meets in the first paragraph, and separating them would
+ * put those halves in two places with two lifecycles for no benefit a reader can perceive. The
+ * ASSESSMENT behind a basis is reviewed work and lives in `assessmentNote`; the conclusion belongs
+ * with the identity that publishes it.
+ *
+ * ## What is deliberately NOT here
+ *
+ * A DPO appointment record, a processing-activities register (Art. 30), a retention schedule
+ * (`dataRetention`), a processor register (#88). This is the operator's identity and legal posture —
+ * the answers a notice needs in its opening sections — not a compliance programme.
+ */
+export declare const ApplicationOperatorComplianceIdentitySchema: z.ZodObject<{
+    /** The legal entity operating the service, as registered. */
+    legalEntityName: z.ZodString;
+    /** Its registered address, as a reader would need it to serve a request. */
+    registeredAddress: z.ZodString;
+    /**
+     * How a data subject reaches the operator about privacy — an address, an email, or a URL.
+     *
+     * Open string because all three are legitimate and the law names none: what matters is that a route
+     * exists and is stated, not what shape it takes.
+     */
+    privacyContact: z.ZodString;
+    /**
+     * An Art. 27 representative in the origin jurisdiction, where the operator is established outside it.
+     *
+     * Optional, because most operators are established where their subjects are and appointing one
+     * would be a fiction. Absent means "not required", never "not considered" — a notice states it only
+     * when declared.
+     */
+    representative: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        address: z.ZodString;
+    }, z.core.$strict>>;
+    /**
+     * The operator's role, per population of data. At least one.
+     *
+     * See {@link OperatorRoleAllocationSchema} for why this is a list rather than a field.
+     */
+    roleAllocations: z.ZodArray<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>;
+    }, z.core.$strict>>;
+    /**
+     * The lawful basis relied on, per processing purpose. At least one.
+     *
+     * `min(1)` at the schema for the same reason the placement plan requires one decision: an identity
+     * declaring no basis at all is a refusal wearing a declaration's clothes, and it would land as a
+     * complete answer.
+     */
+    lawfulBases: 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;
+        basis: z.ZodEnum<typeof LawfulBasis>;
+        /**
+         * The assessment behind the basis. REQUIRED for `LEGITIMATE_INTERESTS`, which is the only basis
+         * that needs a balancing test — see the superRefine below.
+         */
+        assessmentNote: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    /**
+     * What a person must consent to in order to use the service at all (issue #139).
+     *
+     * OPTIONAL, and absent means UNANSWERED rather than `NONE`. The distinction is the one this whole
+     * lane turns on: a declared `NONE` is the operator saying nothing is gated on consent, while
+     * absence is nobody having been asked, and a notice must not render the second as the first.
+     */
+    serviceConsentRequirement: z.ZodOptional<z.ZodObject<{
+        /**
+         * The minimum consent a person must give to use the service.
+         *
+         * `NONE` means nothing is gated on consent — the common and usually correct answer. It is a
+         * DECLARATION, not an absence: an application that says `NONE` has answered the question, which is
+         * what separates it from one that has not been asked.
+         */
+        requiredLevel: z.ZodEnum<typeof DataProcessingConsent>;
+        /**
+         * What this gate actually controls, in the operator's own words.
+         *
+         * REQUIRED whenever the level is above `NONE`, because a gate nobody can describe is a gate nobody
+         * can honour — enforced below. A notice stating "consent is required" without saying what it
+         * governs tells a person they must agree to something unnamed.
+         */
+        gatedProcessing: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ApplicationOperatorComplianceIdentity = z.infer<typeof ApplicationOperatorComplianceIdentitySchema>;
+/**
+ * The lawful bases an operator declares, deduplicated — what a notice enumerates when it says which
+ * bases the service relies on.
+ */
+export declare function declaredLawfulBases(identity: ApplicationOperatorComplianceIdentity): readonly LawfulBasis[];
+/** True when the operator declares more than one role, so a notice must not assign a single one. */
+export declare function operatorHoldsSeveralProcessingRoles(identity: ApplicationOperatorComplianceIdentity): boolean;
+//# sourceMappingURL=operator-compliance-identity.shared.schemas.d.ts.map

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

@@ -0,0 +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,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAEjE;;;;;;;;GAQG;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,0EAA0E;AAC1E,eAAO,MAAM,yBAAyB;IACpC,0GAA0G;;;IAG1G;;;OAGG;;kBAgBH,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,+BAA+B;IAC1C;;;;;;OAMG;;IAEH;;;;;;OAMG;;kBAgBH,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,2CAA2C;IACtD,6DAA6D;;IAE7D,4EAA4E;;IAE5E;;;;;OAKG;;IAEH;;;;;;OAMG;;;;;IAKH;;;;OAIG;;QAxJH,oGAAoG;;;;IA0JpG;;;;;;OAMG;;QAxJH,0GAA0G;;;QAG1G;;;WAGG;;;IAoJH;;;;;;OAMG;;QAxGH;;;;;;WAMG;;QAEH;;;;;;WAMG;;;kBA4FH,CAAC;AACH,MAAM,MAAM,qCAAqC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2CAA2C,CAAC,CAAC;AAGhH;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,qCAAqC,GAAG,SAAS,WAAW,EAAE,CAI3G;AAED,oGAAoG;AACpG,wBAAgB,mCAAmC,CAAC,QAAQ,EAAE,qCAAqC,GAAG,OAAO,CAE5G"}

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

@@ -0,0 +1,232 @@
+import { z } from 'zod';
+import { DataProcessingConsent } from './privacy.shared.schemas.js';
+/**
+ * GDPR Art. 6(1) — the six lawful bases, closed by the article.
+ *
+ * Enumerated individually rather than carried as prose because each carries a different obligation:
+ * consent must be withdrawable, legitimate interests needs a balancing assessment, a legal obligation
+ * must name the law. "We have a lawful basis" is not a disclosure; a notice must say WHICH.
+ *
+ * spec-cite: GDPR Art. 6(1)(a)–(f).
+ */
+export var LawfulBasis;
+(function (LawfulBasis) {
+    /** Art. 6(1)(a) — the subject consented to the processing for one or more specific purposes. */
+    LawfulBasis["CONSENT"] = "CONSENT";
+    /** Art. 6(1)(b) — necessary to perform a contract with the subject, or pre-contractual steps. */
+    LawfulBasis["CONTRACT"] = "CONTRACT";
+    /** Art. 6(1)(c) — necessary to comply with a legal obligation the controller is subject to. */
+    LawfulBasis["LEGAL_OBLIGATION"] = "LEGAL_OBLIGATION";
+    /** Art. 6(1)(d) — necessary to protect vital interests of the subject or another person. */
+    LawfulBasis["VITAL_INTERESTS"] = "VITAL_INTERESTS";
+    /** Art. 6(1)(e) — necessary for a task in the public interest or official authority. */
+    LawfulBasis["PUBLIC_TASK"] = "PUBLIC_TASK";
+    /**
+     * Art. 6(1)(f) — necessary for legitimate interests, except where overridden by the subject's
+     * rights. The only basis requiring a balancing assessment, which is why declaring it without one
+     * is refused below.
+     */
+    LawfulBasis["LEGITIMATE_INTERESTS"] = "LEGITIMATE_INTERESTS";
+})(LawfulBasis || (LawfulBasis = {}));
+/** Whether the operator decides the purposes of a processing, carries them out for someone else, or both. */
+export var OperatorProcessingRole;
+(function (OperatorProcessingRole) {
+    /** The operator determines the purposes and means. */
+    OperatorProcessingRole["CONTROLLER"] = "CONTROLLER";
+    /** The operator processes on a customer's documented instructions — the usual B2B posture for customer records. */
+    OperatorProcessingRole["PROCESSOR"] = "PROCESSOR";
+    /** The operator and another party jointly determine purposes and means, and must have an arrangement saying how. */
+    OperatorProcessingRole["JOINT_CONTROLLER"] = "JOINT_CONTROLLER";
+})(OperatorProcessingRole || (OperatorProcessingRole = {}));
+/**
+ * ONE role, over ONE population of data.
+ *
+ * A single role field would be the wrong shape, and the produced notice said so before this existed:
+ * *"This notice therefore does not assign a single legal role to all data processed in a workspace."*
+ * 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.
+ */
+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),
+});
+/** One processing purpose and the basis the operator relies on for it. */
+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),
+    basis: z.enum(LawfulBasis),
+    /**
+     * The assessment behind the basis. REQUIRED for `LEGITIMATE_INTERESTS`, which is the only basis
+     * that needs a balancing test — see the superRefine below.
+     */
+    assessmentNote: z.string().trim().min(1).optional(),
+}).superRefine((entry, context) => {
+    /*
+     * A legitimate-interests claim with no assessment is the shape that satisfies a field and discloses
+     * nothing — the same defect as a revision that records no superseded rationale. Art. 6(1)(f) is the
+     * only basis whose lawfulness depends on a balancing test, so a declaration without one asserts a
+     * conclusion nobody reached.
+     */
+    if (entry.basis === LawfulBasis.LEGITIMATE_INTERESTS && entry.assessmentNote === undefined) {
+        context.addIssue({
+            code: 'custom',
+            path: ['assessmentNote'],
+            message: `purpose "${entry.purpose}" relies on LEGITIMATE_INTERESTS and records no assessment — that basis is lawful only where the balancing test was actually done, so state it or choose the basis that applies`,
+        });
+    }
+});
+/**
+ * What a person must agree to in order to USE the service at all (issue #139).
+ *
+ * ## The near-miss this exists because of
+ *
+ * `analytics.requiredConsent` already exists and governs ANALYTICS alone. The compliance partial
+ * described it as "the minimum a person must give to use the service" until 2026-08-30 — a much
+ * larger claim about a much narrower field. A drafter following that wording would have published
+ * that a person must consent to analytics in order to use the product: false, and false about the one
+ * subject a reader is most likely to act on.
+ *
+ * Correcting it left a real hole, which a produced notice then reported in its own words:
+ * *"There is no declared surface for recording a service-wide consent requirement distinct from
+ * analytics consent."* This is that surface.
+ *
+ * ## Why the floor may be NONE, and usually should be
+ *
+ * Consent is ONE Art. 6(1) basis among six, and for most B2B SaaS the basis for core processing is
+ * CONTRACT — a person uses the product because their employer signed for it, not because they
+ * consented. A required level above `NONE` says the opposite, so declaring one is a claim about the
+ * lawful basis and not merely a UI gate.
+ *
+ * `NONE` is therefore both the default and the honest answer for most applications: *nothing is
+ * gated on consent; the lawful basis lives in {@link ApplicationOperatorComplianceIdentitySchema.lawfulBases}.*
+ * A field that pushed applications toward declaring consent would be worse than the gap it closes.
+ *
+ * ⚠️ Declaring a level here does NOT make consent the lawful basis for anything. It states a gate.
+ * The basis is declared per purpose, separately, and the two disagreeing is the shape a reviewer
+ * needs to see rather than one the schema should quietly reconcile.
+ */
+export const ServiceConsentRequirementSchema = z.strictObject({
+    /**
+     * The minimum consent a person must give to use the service.
+     *
+     * `NONE` means nothing is gated on consent — the common and usually correct answer. It is a
+     * DECLARATION, not an absence: an application that says `NONE` has answered the question, which is
+     * what separates it from one that has not been asked.
+     */
+    requiredLevel: z.enum(DataProcessingConsent),
+    /**
+     * What this gate actually controls, in the operator's own words.
+     *
+     * REQUIRED whenever the level is above `NONE`, because a gate nobody can describe is a gate nobody
+     * can honour — enforced below. A notice stating "consent is required" without saying what it
+     * governs tells a person they must agree to something unnamed.
+     */
+    gatedProcessing: z.string().trim().min(1).optional(),
+}).superRefine((requirement, context) => {
+    /*
+     * A required level above NONE with nothing described is the shape that satisfies the field and
+     * discloses nothing — the same defect as a revision recording no superseded rationale, and as a
+     * legitimate-interests basis with no assessment. Each time, the value is the easy half and the
+     * explanation is the half that makes it mean anything.
+     */
+    if (requirement.requiredLevel !== DataProcessingConsent.NONE && requirement.gatedProcessing === undefined) {
+        context.addIssue({
+            code: 'custom',
+            path: ['gatedProcessing'],
+            message: `a required consent level of ${requirement.requiredLevel} gates something — say what, or declare NONE. A notice stating that consent is required without naming what it governs tells a person they must agree to something unnamed`,
+        });
+    }
+});
+/**
+ * WHO is publishing this notice, under what legal role, on what basis — the operator's own compliance
+ * identity (issue #131).
+ *
+ * ## Why this exists, and why in configuration
+ *
+ * A produced compliance document asked three questions the application had nowhere to answer:
+ * who operates the service, in what role, and on what lawful basis. Measured 2026-08-30, the only
+ * `legalEntityName` anywhere in the compliance model was the PROCESSOR's, from the register in issue
+ * #88 — nothing described the operator.
+ *
+ * That is not merely an empty field. A landing REPLACES the produced document on every run, so an
+ * operator who answered by editing the document lost the answer on the next regeneration:
+ * `.claude/rules/one-source-of-truth.md`'s test failing in the direction that matters — delete and
+ * re-run, and you lose TRUTH rather than TIME.
+ *
+ * Configuration rather than a governed document, and identity and basis together rather than split.
+ * They are two halves of ONE clause a reader meets in the first paragraph, and separating them would
+ * put those halves in two places with two lifecycles for no benefit a reader can perceive. The
+ * ASSESSMENT behind a basis is reviewed work and lives in `assessmentNote`; the conclusion belongs
+ * with the identity that publishes it.
+ *
+ * ## What is deliberately NOT here
+ *
+ * A DPO appointment record, a processing-activities register (Art. 30), a retention schedule
+ * (`dataRetention`), a processor register (#88). This is the operator's identity and legal posture —
+ * the answers a notice needs in its opening sections — not a compliance programme.
+ */
+export const ApplicationOperatorComplianceIdentitySchema = z.strictObject({
+    /** The legal entity operating the service, as registered. */
+    legalEntityName: z.string().trim().min(1),
+    /** Its registered address, as a reader would need it to serve a request. */
+    registeredAddress: z.string().trim().min(1),
+    /**
+     * How a data subject reaches the operator about privacy — an address, an email, or a URL.
+     *
+     * Open string because all three are legitimate and the law names none: what matters is that a route
+     * exists and is stated, not what shape it takes.
+     */
+    privacyContact: z.string().trim().min(1),
+    /**
+     * An Art. 27 representative in the origin jurisdiction, where the operator is established outside it.
+     *
+     * Optional, because most operators are established where their subjects are and appointing one
+     * would be a fiction. Absent means "not required", never "not considered" — a notice states it only
+     * when declared.
+     */
+    representative: z.strictObject({
+        name: z.string().trim().min(1),
+        address: z.string().trim().min(1),
+    }).optional(),
+    /**
+     * The operator's role, per population of data. At least one.
+     *
+     * See {@link OperatorRoleAllocationSchema} for why this is a list rather than a field.
+     */
+    roleAllocations: z.array(OperatorRoleAllocationSchema).min(1),
+    /**
+     * The lawful basis relied on, per processing purpose. At least one.
+     *
+     * `min(1)` at the schema for the same reason the placement plan requires one decision: an identity
+     * 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),
+    /**
+     * What a person must consent to in order to use the service at all (issue #139).
+     *
+     * OPTIONAL, and absent means UNANSWERED rather than `NONE`. The distinction is the one this whole
+     * lane turns on: a declared `NONE` is the operator saying nothing is gated on consent, while
+     * absence is nobody having been asked, and a notice must not render the second as the first.
+     */
+    serviceConsentRequirement: ServiceConsentRequirementSchema.optional(),
+});
+/**
+ * The lawful bases an operator declares, deduplicated — what a notice enumerates when it says which
+ * bases the service relies on.
+ */
+export function declaredLawfulBases(identity) {
+    const order = Object.values(LawfulBasis);
+    return [...new Set(identity.lawfulBases.map((entry) => entry.basis))]
+        .sort((left, right) => order.indexOf(left) - order.indexOf(right));
+}
+/** True when the operator declares more than one role, so a notice must not assign a single one. */
+export function operatorHoldsSeveralProcessingRoles(identity) {
+    return new Set(identity.roleAllocations.map((allocation) => allocation.role)).size > 1;
+}
+//# sourceMappingURL=operator-compliance-identity.shared.schemas.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"operator-compliance-identity.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/compliance/privacy/operator-compliance-identity.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\n\nimport { DataProcessingConsent } from './privacy.shared.schemas';\n\n/**\n * GDPR Art. 6(1) — the six lawful bases, closed by the article.\n *\n * Enumerated individually rather than carried as prose because each carries a different obligation:\n * consent must be withdrawable, legitimate interests needs a balancing assessment, a legal obligation\n * must name the law. \"We have a lawful basis\" is not a disclosure; a notice must say WHICH.\n *\n * spec-cite: GDPR Art. 6(1)(a)–(f).\n */\nexport enum LawfulBasis {\n  /** Art. 6(1)(a) — the subject consented to the processing for one or more specific purposes. */\n  CONSENT = 'CONSENT',\n  /** Art. 6(1)(b) — necessary to perform a contract with the subject, or pre-contractual steps. */\n  CONTRACT = 'CONTRACT',\n  /** Art. 6(1)(c) — necessary to comply with a legal obligation the controller is subject to. */\n  LEGAL_OBLIGATION = 'LEGAL_OBLIGATION',\n  /** Art. 6(1)(d) — necessary to protect vital interests of the subject or another person. */\n  VITAL_INTERESTS = 'VITAL_INTERESTS',\n  /** Art. 6(1)(e) — necessary for a task in the public interest or official authority. */\n  PUBLIC_TASK = 'PUBLIC_TASK',\n  /**\n   * Art. 6(1)(f) — necessary for legitimate interests, except where overridden by the subject's\n   * rights. The only basis requiring a balancing assessment, which is why declaring it without one\n   * is refused below.\n   */\n  LEGITIMATE_INTERESTS = 'LEGITIMATE_INTERESTS',\n}\n\n/** Whether the operator decides the purposes of a processing, carries them out for someone else, or both. */\nexport enum OperatorProcessingRole {\n  /** The operator determines the purposes and means. */\n  CONTROLLER = 'CONTROLLER',\n  /** The operator processes on a customer's documented instructions — the usual B2B posture for customer records. */\n  PROCESSOR = 'PROCESSOR',\n  /** The operator and another party jointly determine purposes and means, and must have an arrangement saying how. */\n  JOINT_CONTROLLER = 'JOINT_CONTROLLER',\n}\n\n/**\n * ONE role, over ONE population of data.\n *\n * A single role field would be the wrong shape, and the produced notice said so before this existed:\n * *\"This notice therefore does not assign a single legal role to all data processed in a workspace.\"*\n * A B2B SaaS is typically a PROCESSOR for the records its customers put in, and a CONTROLLER for the\n * account and billing data of the people who administer them — simultaneously, in one product.\n *\n * `dataScope` is prose the operator writes, deliberately. Nothing structured exists to key it to: the\n * processing purposes a notice states are derived from the application's vision and requirements as\n * PROSE, so a ref here would point at nothing.\n */\nexport const OperatorRoleAllocationSchema = z.strictObject({\n  /** Which data this role covers, in the operator's own words — \"customer records in a workspace\". */\n  dataScope: z.string().trim().min(1),\n  role: z.enum(OperatorProcessingRole),\n});\nexport type OperatorRoleAllocation = z.infer<typeof OperatorRoleAllocationSchema>;\n\n/** One processing purpose and the basis the operator relies on for it. */\nexport const OperatorLawfulBasisSchema = z.strictObject({\n  /** The purpose, in the operator's own words. Matches how the notice states purposes: prose, not a ref. */\n  purpose: z.string().trim().min(1),\n  basis: z.enum(LawfulBasis),\n  /**\n   * The assessment behind the basis. REQUIRED for `LEGITIMATE_INTERESTS`, which is the only basis\n   * that needs a balancing test — see the superRefine below.\n   */\n  assessmentNote: z.string().trim().min(1).optional(),\n}).superRefine((entry, context) => {\n  /*\n   * A legitimate-interests claim with no assessment is the shape that satisfies a field and discloses\n   * nothing — the same defect as a revision that records no superseded rationale. Art. 6(1)(f) is the\n   * only basis whose lawfulness depends on a balancing test, so a declaration without one asserts a\n   * conclusion nobody reached.\n   */\n  if (entry.basis === LawfulBasis.LEGITIMATE_INTERESTS && entry.assessmentNote === undefined) {\n    context.addIssue({\n      code: 'custom',\n      path: ['assessmentNote'],\n      message: `purpose \"${entry.purpose}\" relies on LEGITIMATE_INTERESTS and records no assessment — that basis is lawful only where the balancing test was actually done, so state it or choose the basis that applies`,\n    });\n  }\n});\nexport type OperatorLawfulBasis = z.infer<typeof OperatorLawfulBasisSchema>;\n\n/**\n * What a person must agree to in order to USE the service at all (issue #139).\n *\n * ## The near-miss this exists because of\n *\n * `analytics.requiredConsent` already exists and governs ANALYTICS alone. The compliance partial\n * described it as \"the minimum a person must give to use the service\" until 2026-08-30 — a much\n * larger claim about a much narrower field. A drafter following that wording would have published\n * that a person must consent to analytics in order to use the product: false, and false about the one\n * subject a reader is most likely to act on.\n *\n * Correcting it left a real hole, which a produced notice then reported in its own words:\n * *\"There is no declared surface for recording a service-wide consent requirement distinct from\n * analytics consent.\"* This is that surface.\n *\n * ## Why the floor may be NONE, and usually should be\n *\n * Consent is ONE Art. 6(1) basis among six, and for most B2B SaaS the basis for core processing is\n * CONTRACT — a person uses the product because their employer signed for it, not because they\n * consented. A required level above `NONE` says the opposite, so declaring one is a claim about the\n * lawful basis and not merely a UI gate.\n *\n * `NONE` is therefore both the default and the honest answer for most applications: *nothing is\n * gated on consent; the lawful basis lives in {@link ApplicationOperatorComplianceIdentitySchema.lawfulBases}.*\n * A field that pushed applications toward declaring consent would be worse than the gap it closes.\n *\n * ⚠️ Declaring a level here does NOT make consent the lawful basis for anything. It states a gate.\n * The basis is declared per purpose, separately, and the two disagreeing is the shape a reviewer\n * needs to see rather than one the schema should quietly reconcile.\n */\nexport const ServiceConsentRequirementSchema = z.strictObject({\n  /**\n   * The minimum consent a person must give to use the service.\n   *\n   * `NONE` means nothing is gated on consent — the common and usually correct answer. It is a\n   * DECLARATION, not an absence: an application that says `NONE` has answered the question, which is\n   * what separates it from one that has not been asked.\n   */\n  requiredLevel: z.enum(DataProcessingConsent),\n  /**\n   * What this gate actually controls, in the operator's own words.\n   *\n   * REQUIRED whenever the level is above `NONE`, because a gate nobody can describe is a gate nobody\n   * can honour — enforced below. A notice stating \"consent is required\" without saying what it\n   * governs tells a person they must agree to something unnamed.\n   */\n  gatedProcessing: z.string().trim().min(1).optional(),\n}).superRefine((requirement, context) => {\n  /*\n   * A required level above NONE with nothing described is the shape that satisfies the field and\n   * discloses nothing — the same defect as a revision recording no superseded rationale, and as a\n   * legitimate-interests basis with no assessment. Each time, the value is the easy half and the\n   * explanation is the half that makes it mean anything.\n   */\n  if (requirement.requiredLevel !== DataProcessingConsent.NONE && requirement.gatedProcessing === undefined) {\n    context.addIssue({\n      code: 'custom',\n      path: ['gatedProcessing'],\n      message: `a required consent level of ${requirement.requiredLevel} gates something — say what, or declare NONE. A notice stating that consent is required without naming what it governs tells a person they must agree to something unnamed`,\n    });\n  }\n});\nexport type ServiceConsentRequirement = z.infer<typeof ServiceConsentRequirementSchema>;\n\n/**\n * WHO is publishing this notice, under what legal role, on what basis — the operator's own compliance\n * identity (issue #131).\n *\n * ## Why this exists, and why in configuration\n *\n * A produced compliance document asked three questions the application had nowhere to answer:\n * who operates the service, in what role, and on what lawful basis. Measured 2026-08-30, the only\n * `legalEntityName` anywhere in the compliance model was the PROCESSOR's, from the register in issue\n * #88 — nothing described the operator.\n *\n * That is not merely an empty field. A landing REPLACES the produced document on every run, so an\n * operator who answered by editing the document lost the answer on the next regeneration:\n * `.claude/rules/one-source-of-truth.md`'s test failing in the direction that matters — delete and\n * re-run, and you lose TRUTH rather than TIME.\n *\n * Configuration rather than a governed document, and identity and basis together rather than split.\n * They are two halves of ONE clause a reader meets in the first paragraph, and separating them would\n * put those halves in two places with two lifecycles for no benefit a reader can perceive. The\n * ASSESSMENT behind a basis is reviewed work and lives in `assessmentNote`; the conclusion belongs\n * with the identity that publishes it.\n *\n * ## What is deliberately NOT here\n *\n * A DPO appointment record, a processing-activities register (Art. 30), a retention schedule\n * (`dataRetention`), a processor register (#88). This is the operator's identity and legal posture —\n * the answers a notice needs in its opening sections — not a compliance programme.\n */\nexport const ApplicationOperatorComplianceIdentitySchema = z.strictObject({\n  /** The legal entity operating the service, as registered. */\n  legalEntityName: z.string().trim().min(1),\n  /** Its registered address, as a reader would need it to serve a request. */\n  registeredAddress: z.string().trim().min(1),\n  /**\n   * How a data subject reaches the operator about privacy — an address, an email, or a URL.\n   *\n   * Open string because all three are legitimate and the law names none: what matters is that a route\n   * exists and is stated, not what shape it takes.\n   */\n  privacyContact: z.string().trim().min(1),\n  /**\n   * An Art. 27 representative in the origin jurisdiction, where the operator is established outside it.\n   *\n   * Optional, because most operators are established where their subjects are and appointing one\n   * would be a fiction. Absent means \"not required\", never \"not considered\" — a notice states it only\n   * when declared.\n   */\n  representative: z.strictObject({\n    name: z.string().trim().min(1),\n    address: z.string().trim().min(1),\n  }).optional(),\n  /**\n   * The operator's role, per population of data. At least one.\n   *\n   * See {@link OperatorRoleAllocationSchema} for why this is a list rather than a field.\n   */\n  roleAllocations: z.array(OperatorRoleAllocationSchema).min(1),\n  /**\n   * The lawful basis relied on, per processing purpose. At least one.\n   *\n   * `min(1)` at the schema for the same reason the placement plan requires one decision: an identity\n   * declaring no basis at all is a refusal wearing a declaration's clothes, and it would land as a\n   * complete answer.\n   */\n  lawfulBases: z.array(OperatorLawfulBasisSchema).min(1),\n  /**\n   * What a person must consent to in order to use the service at all (issue #139).\n   *\n   * OPTIONAL, and absent means UNANSWERED rather than `NONE`. The distinction is the one this whole\n   * lane turns on: a declared `NONE` is the operator saying nothing is gated on consent, while\n   * absence is nobody having been asked, and a notice must not render the second as the first.\n   */\n  serviceConsentRequirement: ServiceConsentRequirementSchema.optional(),\n});\nexport type ApplicationOperatorComplianceIdentity = z.infer<typeof ApplicationOperatorComplianceIdentitySchema>;\n\n\n/**\n * The lawful bases an operator declares, deduplicated — what a notice enumerates when it says which\n * bases the service relies on.\n */\nexport function declaredLawfulBases(identity: ApplicationOperatorComplianceIdentity): readonly LawfulBasis[] {\n  const order = Object.values(LawfulBasis);\n  return [...new Set(identity.lawfulBases.map((entry) => entry.basis))]\n    .sort((left, right) => order.indexOf(left) - order.indexOf(right));\n}\n\n/** True when the operator declares more than one role, so a notice must not assign a single one. */\nexport function operatorHoldsSeveralProcessingRoles(identity: ApplicationOperatorComplianceIdentity): boolean {\n  return new Set(identity.roleAllocations.map((allocation) => allocation.role)).size > 1;\n}\n"]}