@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/compliance/privacy/subject-erasure.shared.schemas.js

@@ -0,0 +1,238 @@
+import { RelationshipLifecycleModel, } from '../../resources/resources.shared.schemas.js';
+import { Resources_SharedUtils } from '../../resources/resources.shared.utils.js';
+import { ChildLifecycleMode, ChildLifecycleStrategy, } from '../../resources/child-operations.shared.schemas.js';
+/**
+ * What a SUBJECT ERASURE does to one child-direction edge of the subject.
+ *
+ * ## Why this vocabulary exists at all
+ *
+ * "Erase this subject" (a `delete my account` request) is not "delete this row". The subject row
+ * SURVIVES — scrubbed and marked `RETAINED` — so that foreign keys from legally-retained financial
+ * rows keep resolving to an anonymized person. But the subject's OWN dependents must each be
+ * disposed of, and the disposition differs per edge: a profile holding a name and an avatar has to
+ * go, an invoice has to stay, an audit log was never the subject's to begin with.
+ *
+ * This enum is the closed set of answers, and it is deliberately WIDER than the two teardown
+ * strategies of {@link ChildLifecycleStrategy}: the delete cascade only ever asks about edges that
+ * opted IN (`onParentDelete.enabled === true`) and silently ignores the rest, whereas an erasure
+ * must account for EVERY edge — including the ones nobody opted in — because an edge nobody thought
+ * about is exactly where personal data survives an erasure unnoticed.
+ *
+ * Two members therefore have no runtime action and exist to make the erasure FAIL LOUD
+ * ({@link UNCLASSIFIED}, {@link UNSUPPORTED_DEFERRED}), and two describe leaving a row alone for
+ * two genuinely different reasons ({@link RETAINED_BY_DECLARATION} vs {@link NOT_OWNED}). Those two
+ * are not merged despite sharing a no-op: a data-protection reviewer asking "why is this row still
+ * here?" needs "because the author declared it retained" and "because it was never the subject's
+ * row" to be different answers, and only the first one is a compliance claim someone made.
+ */
+export var SubjectErasureDisposition;
+(function (SubjectErasureDisposition) {
+    /**
+     * Hard-delete the child rows. The author declared this dependent's data dies with the parent's
+     * ownership (`onParentDelete.enabled`, `strategy: DELETE`) — on an erasure the ownership ends in
+     * the only way that matters for personal data, so the rows go. This is the `USER_PROFILES` case:
+     * there is no legal obligation to retain a name, a bio or an avatar.
+     */
+    SubjectErasureDisposition["DELETE"] = "delete";
+    /**
+     * Scrub the child rows' personal fields in place and KEEP them, flipping `retentionStatus` to
+     * `RETAINED` (`onParentDelete.strategy = IMPERSONALIZE_AND_RETAIN`). For a dependent that must
+     * survive for a legal/audit obligation while holding personal data of its own.
+     */
+    SubjectErasureDisposition["IMPERSONALIZE_AND_RETAIN"] = "impersonalize_and_retain";
+    /**
+     * LEAVE THE ROWS EXACTLY AS THEY ARE — a dependent whose cascade the author explicitly DISABLED
+     * (`onParentDelete.enabled: false`). That declaration says "this row survives its parent's
+     * teardown", which is a positive compliance claim, not an omission.
+     *
+     * This is how the retained billing rows are expressed: subscriptions, invoice refs, usage records
+     * and credit pools each disable the cascade, keep their financial audit trail fully VISIBLE, and
+     * rely on the erased subject row still resolving their foreign keys.
+     */
+    SubjectErasureDisposition["RETAINED_BY_DECLARATION"] = "retained_by_declaration";
+    /**
+     * LEAVE THE ROWS ALONE — the edge is not an ownership edge at all
+     * (`lifecycleModelMode` is `INDEPENDENT` or `LINK_ONLY`, or the relationship is disabled). The
+     * related rows live independently of the subject, so their disposition is not the subject's
+     * erasure to decide (audit logs, job executions, membership links).
+     */
+    SubjectErasureDisposition["NOT_OWNED"] = "not_owned";
+    /**
+     * ⛔ NO ANSWER — a DEPENDENT child with NO `onParentDelete` declaration whatsoever. The author
+     * owns this dependent's lifecycle but never said what happens to it, and an erasure must not
+     * guess: deleting could destroy data a retention obligation required keeping, and leaving could
+     * strand personal data that the erasure claimed to have removed. The orchestrator throws.
+     */
+    SubjectErasureDisposition["UNCLASSIFIED"] = "unclassified";
+    /**
+     * ⛔ DECLARED BUT NOT EXECUTABLE AS PART OF AN ERASURE — the edge opted in with
+     * `mode: LAZY` (queue the teardown for later). Deferring is a legitimate performance choice for a
+     * parent delete, but it would let an erasure report success while the subject's personal data is
+     * still live in a queue nobody is watching. The orchestrator throws.
+     */
+    SubjectErasureDisposition["UNSUPPORTED_DEFERRED"] = "unsupported_deferred";
+})(SubjectErasureDisposition || (SubjectErasureDisposition = {}));
+/** Dispositions that ABORT the erasure rather than executing it. */
+const BLOCKING_DISPOSITIONS = new Set([
+    SubjectErasureDisposition.UNCLASSIFIED,
+    SubjectErasureDisposition.UNSUPPORTED_DEFERRED,
+]);
+/**
+ * True when a disposition must stop the erasure before any write lands.
+ *
+ * Exported (rather than inlined at the one call site) so a future boot-time guard — the erasure
+ * analogue of `validateCompositionCascadeDeletability` — reports exactly the edges the runtime
+ * would refuse, instead of re-deriving the rule and drifting from it.
+ */
+export function isBlockingSubjectErasureDisposition(disposition) {
+    return BLOCKING_DISPOSITIONS.has(disposition);
+}
+/**
+ * Classify what a subject erasure must do with ONE child-direction edge — the delete-vs-retain
+ * decision, DERIVED FROM CONFIGURATION rather than from a hardcoded list of resource types.
+ *
+ * ## Where the answer comes from
+ *
+ * Two declarations the author already makes, read through the SAME shared authority the runtime
+ * delete cascade reads (`resolveRelationshipLifecycleOnParentDeleteConfig`), so the erasure and the
+ * cascade can never disagree about what an edge says:
+ *
+ *  1. **`handling.lifecycleModelMode`** — does the subject own this dependent's lifecycle at all?
+ *     `INDEPENDENT` / `LINK_ONLY` answers "no", and the erasure leaves those rows alone.
+ *  2. **`childOperations.lifecycle.onParentDelete`** — for an owned dependent, what did the author
+ *     declare happens when the parent stops owning it: hard-delete, scrub-and-retain, or nothing.
+ *
+ * ## The semantic caveat, stated plainly
+ *
+ * `onParentDelete` literally answers "what happens when the parent row is DELETED", and an erasure
+ * does NOT delete the subject — it scrubs and keeps it. v1 deliberately treats the two questions as
+ * one because they have the same answer for every edge in the shipped registry, and because an
+ * author who declared "this dependent dies with its parent" has already said the thing that
+ * matters: the dependent's data has no life of its own once the subject's does not.
+ *
+ * They are NOT the same question though, and the day a resource needs to answer them differently
+ * (retain a dependent on erasure that it hard-deletes on parent-delete, or the reverse) the
+ * expressible extension is a sibling `onSubjectErasure` axis on the same edge, defaulting to this
+ * derivation. Adding that axis speculatively now would give app authors a second knob with no
+ * consumer and two ways to say the same thing.
+ *
+ * Pure and side-effect free — no registry lookups, no I/O — so it is equally usable from a runtime
+ * orchestrator and from a boot-time guard.
+ */
+export function classifySubjectErasureDisposition(relationship) {
+    const childResourceType = relationship.resourceType2;
+    const classify = (disposition, reason) => ({ childResourceType, disposition, reason });
+    // A disabled relationship is not part of the live graph — the runtime never traverses it, so an
+    // erasure must not refuse to run because of it (the alternative would be a permanently blocked
+    // erasure on a resource carrying a switched-off edge).
+    if (relationship.isDisabled === true) {
+        return classify(SubjectErasureDisposition.NOT_OWNED, 'the relationship is disabled (isDisabled: true), so it is not part of the live graph');
+    }
+    const semantics = Resources_SharedUtils.requireResolvedRelationshipSemantics(relationship);
+    const lifecycleModel = semantics.handling.lifecycleModelMode;
+    if (lifecycleModel !== RelationshipLifecycleModel.DEPENDENT) {
+        return classify(SubjectErasureDisposition.NOT_OWNED, `lifecycleModelMode is '${lifecycleModel}' (not DEPENDENT): the related rows live ` +
+            `independently of the subject, so their disposition is not this erasure's decision`);
+    }
+    // DEPENDENT from here on: the subject owns this dependent's lifecycle, so the erasure MUST have
+    // an answer for it.
+    const onParentDelete = Resources_SharedUtils.resolveRelationshipLifecycleOnParentDeleteConfig(relationship);
+    if (!onParentDelete) {
+        return classify(SubjectErasureDisposition.UNCLASSIFIED, `the subject owns this dependent (lifecycleModelMode: DEPENDENT) but the edge declares no ` +
+            `onParentDelete lifecycle, so nobody has said whether its rows survive an erasure. ` +
+            `Declare onParentDelete on the edge: 'enabled: true' with strategy DELETE (the rows hold ` +
+            `no retainable value) or IMPERSONALIZE_AND_RETAIN (they must survive scrubbed), or ` +
+            `'enabled: false' to state explicitly that they survive intact`);
+    }
+    if (onParentDelete.enabled !== true) {
+        return classify(SubjectErasureDisposition.RETAINED_BY_DECLARATION, 'onParentDelete.enabled is false: the author declared these rows survive their parent\'s ' +
+            'teardown, so the erasure leaves them intact');
+    }
+    const mode = onParentDelete.mode ?? ChildLifecycleMode.IMMEDIATE;
+    if (mode !== ChildLifecycleMode.IMMEDIATE) {
+        return classify(SubjectErasureDisposition.UNSUPPORTED_DEFERRED, `onParentDelete.mode is '${mode}': deferring the teardown to a queue would let the erasure ` +
+            `report success while the subject's personal data is still live. Set mode: IMMEDIATE on ` +
+            `this edge for it to participate in a subject erasure`);
+    }
+    const strategy = onParentDelete.strategy ?? ChildLifecycleStrategy.DELETE;
+    switch (strategy) {
+        case ChildLifecycleStrategy.DELETE:
+            return classify(SubjectErasureDisposition.DELETE, 'onParentDelete declares strategy DELETE: the dependent\'s data dies with the subject\'s ' +
+                'ownership, so the erasure removes the rows');
+        case ChildLifecycleStrategy.IMPERSONALIZE_AND_RETAIN:
+            return classify(SubjectErasureDisposition.IMPERSONALIZE_AND_RETAIN, 'onParentDelete declares strategy IMPERSONALIZE_AND_RETAIN: the rows survive the erasure ' +
+                'with their personal fields scrubbed and retentionStatus flipped to RETAINED');
+        default: {
+            // Compile-time exhaustiveness: a new ChildLifecycleStrategy member without an erasure arm is
+            // a TYPE error here, not a silent runtime discovery on someone's deletion request.
+            const _exhaustiveStrategyCheck = strategy;
+            return classify(SubjectErasureDisposition.UNCLASSIFIED, `onParentDelete declares an unknown teardown strategy ` +
+                `'${String(_exhaustiveStrategyCheck)}' that subject erasure has no arm for`);
+        }
+    }
+}
+/**
+ * Outcome of one EXTERNAL, non-transactional erasure effect (a third-party provider the subject's
+ * personal data also reached — a billing provider customer, say).
+ *
+ * A separate vocabulary from {@link SubjectErasureDisposition} on purpose. An edge disposition
+ * describes a decision derived from configuration BEFORE anything ran, and its teardown is part of
+ * the database transaction. An external effect is the opposite on both counts: it is discovered by
+ * calling out to a system Wildo does not own, and it CANNOT join the transaction. Collapsing the
+ * two would let a caller read "the erasure succeeded" from a value that only ever described the
+ * local rows.
+ */
+export var SubjectErasureExternalEffectStatus;
+(function (SubjectErasureExternalEffectStatus) {
+    /** Every step of the effect completed against the external system. */
+    SubjectErasureExternalEffectStatus["COMPLETED"] = "completed";
+    /**
+     * The subject had nothing at this external system — no provider customer, no linked record. A
+     * legitimate success, kept DISTINCT from `COMPLETED` so "there was nothing to erase" can never be
+     * mistaken for "we erased it", which is exactly the confusion a regulator would probe.
+     */
+    SubjectErasureExternalEffectStatus["NOTHING_TO_ERASE"] = "nothing-to-erase";
+    /**
+     * The effect ran and some steps succeeded while others failed — personal data may still be live
+     * at the external system. The loudest state in this enum: it demands follow-up, and it is why the
+     * status is not a boolean.
+     */
+    SubjectErasureExternalEffectStatus["PARTIAL"] = "partial";
+    /** The effect could not run at all (provider unreachable, not configured). Nothing was changed. */
+    SubjectErasureExternalEffectStatus["FAILED"] = "failed";
+    /**
+     * No handler was registered for this effect. Distinct from `NOTHING_TO_ERASE`: that means we
+     * looked and found nothing, this means nobody looked.
+     */
+    SubjectErasureExternalEffectStatus["NOT_REGISTERED"] = "not-registered";
+    /**
+     * The external system's binding DECLARES its rows hold no personal/subject data
+     * (`HttpApiErasureStance.NO_SUBJECT_DATA`, ETL D6 stance 6a) — nothing was erased because,
+     * by declaration, there is nothing an erasure could apply to. Distinct from
+     * {@link NOTHING_TO_ERASE}: that means we LOOKED and found no linked rows; this means the
+     * declaration made looking unnecessary. A complete outcome — the declaration's coherence is
+     * validated at boot (a 6a resource cannot participate in subject export).
+     */
+    SubjectErasureExternalEffectStatus["DECLARED_NO_SUBJECT_DATA"] = "declared-no-subject-data";
+    /**
+     * The rows live in an external system the platform cannot erase, and the CONTROLLER explicitly
+     * acknowledged completing the erasure anyway (`HttpApiErasureStance.
+     * CONTROLLER_ACKNOWLEDGED_NON_ERASURE`, ETL D6 stance 6c — the per-request
+     * `acknowledgeHttpApiNonErasure` option). Deliberately INCOMPLETE in
+     * {@link isIncompleteSubjectErasureExternalEffect}: the subject's data is still live at the
+     * third party, and a compliance artifact must say so however deliberate the decision was. The
+     * acknowledgement itself is additionally recorded as a CRITICAL audit event — the record is
+     * the control (`administrative-continuity-floors.md`).
+     */
+    SubjectErasureExternalEffectStatus["ACKNOWLEDGED_NON_ERASURE"] = "acknowledged-non-erasure";
+})(SubjectErasureExternalEffectStatus || (SubjectErasureExternalEffectStatus = {}));
+/** Whether an external-effect status leaves personal data potentially live at a third party. */
+export function isIncompleteSubjectErasureExternalEffect(status) {
+    return status === SubjectErasureExternalEffectStatus.PARTIAL
+        || status === SubjectErasureExternalEffectStatus.FAILED
+        || status === SubjectErasureExternalEffectStatus.NOT_REGISTERED
+        // An acknowledged non-erasure is a DELIBERATE hole, and still a hole: personal data remains
+        // live at the third party, so "is this erasure actually complete" must answer no.
+        || status === SubjectErasureExternalEffectStatus.ACKNOWLEDGED_NON_ERASURE;
+}
+//# sourceMappingURL=subject-erasure.shared.schemas.js.map

package/dist/esm/compliance/privacy/subject-erasure.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subject-erasure.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/compliance/privacy/subject-erasure.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  RelationshipLifecycleModel,\n  type ResourceRelationship,\n} from '../../resources/resources.shared.schemas';\nimport { Resources_SharedUtils } from '../../resources/resources.shared.utils';\nimport {\n  ChildLifecycleMode,\n  ChildLifecycleStrategy,\n} from '../../resources/child-operations.shared.schemas';\nimport type { ResourceType } from '../../resources/resources.shared.core.definitions';\n\n/**\n * What a SUBJECT ERASURE does to one child-direction edge of the subject.\n *\n * ## Why this vocabulary exists at all\n *\n * \"Erase this subject\" (a `delete my account` request) is not \"delete this row\". The subject row\n * SURVIVES — scrubbed and marked `RETAINED` — so that foreign keys from legally-retained financial\n * rows keep resolving to an anonymized person. But the subject's OWN dependents must each be\n * disposed of, and the disposition differs per edge: a profile holding a name and an avatar has to\n * go, an invoice has to stay, an audit log was never the subject's to begin with.\n *\n * This enum is the closed set of answers, and it is deliberately WIDER than the two teardown\n * strategies of {@link ChildLifecycleStrategy}: the delete cascade only ever asks about edges that\n * opted IN (`onParentDelete.enabled === true`) and silently ignores the rest, whereas an erasure\n * must account for EVERY edge — including the ones nobody opted in — because an edge nobody thought\n * about is exactly where personal data survives an erasure unnoticed.\n *\n * Two members therefore have no runtime action and exist to make the erasure FAIL LOUD\n * ({@link UNCLASSIFIED}, {@link UNSUPPORTED_DEFERRED}), and two describe leaving a row alone for\n * two genuinely different reasons ({@link RETAINED_BY_DECLARATION} vs {@link NOT_OWNED}). Those two\n * are not merged despite sharing a no-op: a data-protection reviewer asking \"why is this row still\n * here?\" needs \"because the author declared it retained\" and \"because it was never the subject's\n * row\" to be different answers, and only the first one is a compliance claim someone made.\n */\nexport enum SubjectErasureDisposition {\n  /**\n   * Hard-delete the child rows. The author declared this dependent's data dies with the parent's\n   * ownership (`onParentDelete.enabled`, `strategy: DELETE`) — on an erasure the ownership ends in\n   * the only way that matters for personal data, so the rows go. This is the `USER_PROFILES` case:\n   * there is no legal obligation to retain a name, a bio or an avatar.\n   */\n  DELETE = 'delete',\n\n  /**\n   * Scrub the child rows' personal fields in place and KEEP them, flipping `retentionStatus` to\n   * `RETAINED` (`onParentDelete.strategy = IMPERSONALIZE_AND_RETAIN`). For a dependent that must\n   * survive for a legal/audit obligation while holding personal data of its own.\n   */\n  IMPERSONALIZE_AND_RETAIN = 'impersonalize_and_retain',\n\n  /**\n   * LEAVE THE ROWS EXACTLY AS THEY ARE — a dependent whose cascade the author explicitly DISABLED\n   * (`onParentDelete.enabled: false`). That declaration says \"this row survives its parent's\n   * teardown\", which is a positive compliance claim, not an omission.\n   *\n   * This is how the retained billing rows are expressed: subscriptions, invoice refs, usage records\n   * and credit pools each disable the cascade, keep their financial audit trail fully VISIBLE, and\n   * rely on the erased subject row still resolving their foreign keys.\n   */\n  RETAINED_BY_DECLARATION = 'retained_by_declaration',\n\n  /**\n   * LEAVE THE ROWS ALONE — the edge is not an ownership edge at all\n   * (`lifecycleModelMode` is `INDEPENDENT` or `LINK_ONLY`, or the relationship is disabled). The\n   * related rows live independently of the subject, so their disposition is not the subject's\n   * erasure to decide (audit logs, job executions, membership links).\n   */\n  NOT_OWNED = 'not_owned',\n\n  /**\n   * ⛔ NO ANSWER — a DEPENDENT child with NO `onParentDelete` declaration whatsoever. The author\n   * owns this dependent's lifecycle but never said what happens to it, and an erasure must not\n   * guess: deleting could destroy data a retention obligation required keeping, and leaving could\n   * strand personal data that the erasure claimed to have removed. The orchestrator throws.\n   */\n  UNCLASSIFIED = 'unclassified',\n\n  /**\n   * ⛔ DECLARED BUT NOT EXECUTABLE AS PART OF AN ERASURE — the edge opted in with\n   * `mode: LAZY` (queue the teardown for later). Deferring is a legitimate performance choice for a\n   * parent delete, but it would let an erasure report success while the subject's personal data is\n   * still live in a queue nobody is watching. The orchestrator throws.\n   */\n  UNSUPPORTED_DEFERRED = 'unsupported_deferred',\n}\n\n/** The classification of ONE child-direction edge of an erasure subject. */\nexport interface SubjectErasureEdgeClassification {\n  /** The dependent resource on the far side of the edge. */\n  childResourceType: ResourceType;\n  /** What the erasure will do with that dependent's rows. */\n  disposition: SubjectErasureDisposition;\n  /**\n   * Human-readable justification, quoting the configuration that produced it. Surfaced in the\n   * erasure report and in the fail-loud error, so an operator never has to re-derive WHY a row was\n   * deleted, retained, or refused.\n   */\n  reason: string;\n}\n\n/** Dispositions that ABORT the erasure rather than executing it. */\nconst BLOCKING_DISPOSITIONS: ReadonlySet<SubjectErasureDisposition> = new Set([\n  SubjectErasureDisposition.UNCLASSIFIED,\n  SubjectErasureDisposition.UNSUPPORTED_DEFERRED,\n]);\n\n/**\n * True when a disposition must stop the erasure before any write lands.\n *\n * Exported (rather than inlined at the one call site) so a future boot-time guard — the erasure\n * analogue of `validateCompositionCascadeDeletability` — reports exactly the edges the runtime\n * would refuse, instead of re-deriving the rule and drifting from it.\n */\nexport function isBlockingSubjectErasureDisposition(\n  disposition: SubjectErasureDisposition,\n): boolean {\n  return BLOCKING_DISPOSITIONS.has(disposition);\n}\n\n/**\n * Classify what a subject erasure must do with ONE child-direction edge — the delete-vs-retain\n * decision, DERIVED FROM CONFIGURATION rather than from a hardcoded list of resource types.\n *\n * ## Where the answer comes from\n *\n * Two declarations the author already makes, read through the SAME shared authority the runtime\n * delete cascade reads (`resolveRelationshipLifecycleOnParentDeleteConfig`), so the erasure and the\n * cascade can never disagree about what an edge says:\n *\n *  1. **`handling.lifecycleModelMode`** — does the subject own this dependent's lifecycle at all?\n *     `INDEPENDENT` / `LINK_ONLY` answers \"no\", and the erasure leaves those rows alone.\n *  2. **`childOperations.lifecycle.onParentDelete`** — for an owned dependent, what did the author\n *     declare happens when the parent stops owning it: hard-delete, scrub-and-retain, or nothing.\n *\n * ## The semantic caveat, stated plainly\n *\n * `onParentDelete` literally answers \"what happens when the parent row is DELETED\", and an erasure\n * does NOT delete the subject — it scrubs and keeps it. v1 deliberately treats the two questions as\n * one because they have the same answer for every edge in the shipped registry, and because an\n * author who declared \"this dependent dies with its parent\" has already said the thing that\n * matters: the dependent's data has no life of its own once the subject's does not.\n *\n * They are NOT the same question though, and the day a resource needs to answer them differently\n * (retain a dependent on erasure that it hard-deletes on parent-delete, or the reverse) the\n * expressible extension is a sibling `onSubjectErasure` axis on the same edge, defaulting to this\n * derivation. Adding that axis speculatively now would give app authors a second knob with no\n * consumer and two ways to say the same thing.\n *\n * Pure and side-effect free — no registry lookups, no I/O — so it is equally usable from a runtime\n * orchestrator and from a boot-time guard.\n */\nexport function classifySubjectErasureDisposition(\n  relationship: ResourceRelationship,\n): SubjectErasureEdgeClassification {\n  const childResourceType = relationship.resourceType2 as ResourceType;\n  const classify = (\n    disposition: SubjectErasureDisposition,\n    reason: string,\n  ): SubjectErasureEdgeClassification => ({ childResourceType, disposition, reason });\n\n  // A disabled relationship is not part of the live graph — the runtime never traverses it, so an\n  // erasure must not refuse to run because of it (the alternative would be a permanently blocked\n  // erasure on a resource carrying a switched-off edge).\n  if (relationship.isDisabled === true) {\n    return classify(\n      SubjectErasureDisposition.NOT_OWNED,\n      'the relationship is disabled (isDisabled: true), so it is not part of the live graph',\n    );\n  }\n\n  const semantics = Resources_SharedUtils.requireResolvedRelationshipSemantics(relationship);\n  const lifecycleModel = semantics.handling.lifecycleModelMode;\n\n  if (lifecycleModel !== RelationshipLifecycleModel.DEPENDENT) {\n    return classify(\n      SubjectErasureDisposition.NOT_OWNED,\n      `lifecycleModelMode is '${lifecycleModel}' (not DEPENDENT): the related rows live ` +\n        `independently of the subject, so their disposition is not this erasure's decision`,\n    );\n  }\n\n  // DEPENDENT from here on: the subject owns this dependent's lifecycle, so the erasure MUST have\n  // an answer for it.\n  const onParentDelete = Resources_SharedUtils.resolveRelationshipLifecycleOnParentDeleteConfig(\n    relationship,\n  );\n\n  if (!onParentDelete) {\n    return classify(\n      SubjectErasureDisposition.UNCLASSIFIED,\n      `the subject owns this dependent (lifecycleModelMode: DEPENDENT) but the edge declares no ` +\n        `onParentDelete lifecycle, so nobody has said whether its rows survive an erasure. ` +\n        `Declare onParentDelete on the edge: 'enabled: true' with strategy DELETE (the rows hold ` +\n        `no retainable value) or IMPERSONALIZE_AND_RETAIN (they must survive scrubbed), or ` +\n        `'enabled: false' to state explicitly that they survive intact`,\n    );\n  }\n\n  if (onParentDelete.enabled !== true) {\n    return classify(\n      SubjectErasureDisposition.RETAINED_BY_DECLARATION,\n      'onParentDelete.enabled is false: the author declared these rows survive their parent\\'s ' +\n        'teardown, so the erasure leaves them intact',\n    );\n  }\n\n  const mode = onParentDelete.mode ?? ChildLifecycleMode.IMMEDIATE;\n  if (mode !== ChildLifecycleMode.IMMEDIATE) {\n    return classify(\n      SubjectErasureDisposition.UNSUPPORTED_DEFERRED,\n      `onParentDelete.mode is '${mode}': deferring the teardown to a queue would let the erasure ` +\n        `report success while the subject's personal data is still live. Set mode: IMMEDIATE on ` +\n        `this edge for it to participate in a subject erasure`,\n    );\n  }\n\n  const strategy = onParentDelete.strategy ?? ChildLifecycleStrategy.DELETE;\n  switch (strategy) {\n    case ChildLifecycleStrategy.DELETE:\n      return classify(\n        SubjectErasureDisposition.DELETE,\n        'onParentDelete declares strategy DELETE: the dependent\\'s data dies with the subject\\'s ' +\n          'ownership, so the erasure removes the rows',\n      );\n\n    case ChildLifecycleStrategy.IMPERSONALIZE_AND_RETAIN:\n      return classify(\n        SubjectErasureDisposition.IMPERSONALIZE_AND_RETAIN,\n        'onParentDelete declares strategy IMPERSONALIZE_AND_RETAIN: the rows survive the erasure ' +\n          'with their personal fields scrubbed and retentionStatus flipped to RETAINED',\n      );\n\n    default: {\n      // Compile-time exhaustiveness: a new ChildLifecycleStrategy member without an erasure arm is\n      // a TYPE error here, not a silent runtime discovery on someone's deletion request.\n      const _exhaustiveStrategyCheck: never = strategy;\n      return classify(\n        SubjectErasureDisposition.UNCLASSIFIED,\n        `onParentDelete declares an unknown teardown strategy ` +\n          `'${String(_exhaustiveStrategyCheck)}' that subject erasure has no arm for`,\n      );\n    }\n  }\n}\n\n/** Per-edge outcome of an executed erasure — the classification plus what actually happened. */\nexport interface SubjectErasureEdgeOutcome extends SubjectErasureEdgeClassification {\n  /**\n   * `true` when the erasure ran a teardown for this edge.\n   *\n   * Reports that the teardown RAN, not that rows existed — discovery finding no dependents is a\n   * teardown that ran with nothing to do, and is `true`.\n   *\n   * **Read it together with `disposition`, because `false` has two very different meanings:**\n   *\n   * - a NON-executing disposition (`RETAINED_BY_DECLARATION`, `NOT_OWNED`) ⇒ the erasure deliberately\n   *   left the rows alone, and `false` is the expected, correct answer;\n   * - an EXECUTING disposition (`DELETE`, `IMPERSONALIZE_AND_RETAIN`) ⇒ the cascade DECLINED the edge\n   *   (the child had no registered service or repository, or the depth budget was spent). The\n   *   subject's data is partly still live. This pairing should never appear in a healthy system; it is\n   *   logged at ERROR when it happens, with the missing registration named.\n   *\n   * ⚠️ This flag was set unconditionally until 2026-08-11 — it meant \"the dispatcher returned without\n   * throwing\" and reported a skipped edge as torn down. Anything persisted before that date overstates\n   * what was erased. Treat this field as evidence only for reports produced after the fix.\n   */\n  executed: boolean;\n}\n\n/**\n * Outcome of one EXTERNAL, non-transactional erasure effect (a third-party provider the subject's\n * personal data also reached — a billing provider customer, say).\n *\n * A separate vocabulary from {@link SubjectErasureDisposition} on purpose. An edge disposition\n * describes a decision derived from configuration BEFORE anything ran, and its teardown is part of\n * the database transaction. An external effect is the opposite on both counts: it is discovered by\n * calling out to a system Wildo does not own, and it CANNOT join the transaction. Collapsing the\n * two would let a caller read \"the erasure succeeded\" from a value that only ever described the\n * local rows.\n */\nexport enum SubjectErasureExternalEffectStatus {\n  /** Every step of the effect completed against the external system. */\n  COMPLETED = 'completed',\n  /**\n   * The subject had nothing at this external system — no provider customer, no linked record. A\n   * legitimate success, kept DISTINCT from `COMPLETED` so \"there was nothing to erase\" can never be\n   * mistaken for \"we erased it\", which is exactly the confusion a regulator would probe.\n   */\n  NOTHING_TO_ERASE = 'nothing-to-erase',\n  /**\n   * The effect ran and some steps succeeded while others failed — personal data may still be live\n   * at the external system. The loudest state in this enum: it demands follow-up, and it is why the\n   * status is not a boolean.\n   */\n  PARTIAL = 'partial',\n  /** The effect could not run at all (provider unreachable, not configured). Nothing was changed. */\n  FAILED = 'failed',\n  /**\n   * No handler was registered for this effect. Distinct from `NOTHING_TO_ERASE`: that means we\n   * looked and found nothing, this means nobody looked.\n   */\n  NOT_REGISTERED = 'not-registered',\n\n  /**\n   * The external system's binding DECLARES its rows hold no personal/subject data\n   * (`HttpApiErasureStance.NO_SUBJECT_DATA`, ETL D6 stance 6a) — nothing was erased because,\n   * by declaration, there is nothing an erasure could apply to. Distinct from\n   * {@link NOTHING_TO_ERASE}: that means we LOOKED and found no linked rows; this means the\n   * declaration made looking unnecessary. A complete outcome — the declaration's coherence is\n   * validated at boot (a 6a resource cannot participate in subject export).\n   */\n  DECLARED_NO_SUBJECT_DATA = 'declared-no-subject-data',\n\n  /**\n   * The rows live in an external system the platform cannot erase, and the CONTROLLER explicitly\n   * acknowledged completing the erasure anyway (`HttpApiErasureStance.\n   * CONTROLLER_ACKNOWLEDGED_NON_ERASURE`, ETL D6 stance 6c — the per-request\n   * `acknowledgeHttpApiNonErasure` option). Deliberately INCOMPLETE in\n   * {@link isIncompleteSubjectErasureExternalEffect}: the subject's data is still live at the\n   * third party, and a compliance artifact must say so however deliberate the decision was. The\n   * acknowledgement itself is additionally recorded as a CRITICAL audit event — the record is\n   * the control (`administrative-continuity-floors.md`).\n   */\n  ACKNOWLEDGED_NON_ERASURE = 'acknowledged-non-erasure',\n}\n\n/** Whether an external-effect status leaves personal data potentially live at a third party. */\nexport function isIncompleteSubjectErasureExternalEffect(\n  status: SubjectErasureExternalEffectStatus,\n): boolean {\n  return status === SubjectErasureExternalEffectStatus.PARTIAL\n    || status === SubjectErasureExternalEffectStatus.FAILED\n    || status === SubjectErasureExternalEffectStatus.NOT_REGISTERED\n    // An acknowledged non-erasure is a DELIBERATE hole, and still a hole: personal data remains\n    // live at the third party, so \"is this erasure actually complete\" must answer no.\n    || status === SubjectErasureExternalEffectStatus.ACKNOWLEDGED_NON_ERASURE;\n}\n\nexport interface SubjectErasureExternalEffectOutcome {\n  /** Stable identifier of the effect, e.g. `'billing-provider'`. */\n  effectRef: string;\n  status: SubjectErasureExternalEffectStatus;\n  /**\n   * Human-readable account of what ran, for the compliance artifact. On `PARTIAL` / `FAILED` this\n   * must name what did NOT happen — the report is the only place that survives the request.\n   */\n  detail: string;\n  /**\n   * Per-step results, so a partial outcome is actionable rather than merely alarming (which step\n   * against which external id). Never carries personal data — ids and step names only.\n   */\n  steps?: Array<{ step: string; targetRef?: string; succeeded: boolean; error?: string }>;\n}\n\n/**\n * What one subject erasure did — the compliance artifact of a \"delete my account\" request.\n *\n * Returned to the caller (rather than only logged) so the flow that fronts the request can record\n * or surface it: every edge of the subject appears exactly once with the disposition applied and\n * the configuration that justified it, which is the evidence a data-protection response needs.\n */\nexport interface SubjectErasureReport {\n  /** The erased subject's resource type. */\n  subjectResourceType: ResourceType;\n  /** The erased subject rows. */\n  subjectIds: string[];\n  /** Every child-direction edge of the subject, classified, in registry order. */\n  edges: SubjectErasureEdgeOutcome[];\n  /**\n   * `true` once the subject rows themselves were scrubbed and flipped to `RETAINED`. Always `true`\n   * on a successful erasure — an erasure that could not retain its subject throws rather than\n   * returning a report.\n   */\n  subjectImpersonalized: boolean;\n  /**\n   * Outcomes of the external, non-transactional effects the erasure triggered — every SYSTEM WE\n   * DO NOT OWN that the subject's personal data reached: registered effect handlers (a billing\n   * provider), and each HTTP_API-bound resource linked to the subject (one entry per resource,\n   * `effectRef: 'http-api:<resourceType>'`, carrying its declared D6 erasure stance's outcome).\n   *\n   * Empty when no effect was registered for the subject's resource type. These run AFTER the local\n   * scrub has committed, so a failure here cannot roll the erasure back — the local data is\n   * already gone and re-running the whole erasure would be wrong. That asymmetry is precisely why\n   * the outcome is reported rather than thrown: the local part genuinely succeeded, and the caller\n   * needs to know that a third party still holds something.\n   *\n   * Check {@link isIncompleteSubjectErasureExternalEffect} over these before treating a report as a\n   * complete erasure.\n   */\n  /**\n   * Whose sessions this erasure ended, and whether resolving them failed.\n   *\n   * A LOCAL fact, not an external effect: the revocation is a write to our own session fence, applied\n   * at the scrub chokepoint so it covers every path that scrubs a person's row. It is recorded here\n   * because \"the erased person can no longer be logged in\" is exactly what a data-protection response\n   * has to be able to evidence.\n   *\n   * `lookupFailed` is kept distinct from an empty `principalUserIds`: no principals is a legitimate\n   * outcome (the resource declared `NO_PRINCIPAL`), whereas a failed lookup means the person may\n   * still hold a live session — and the two must never look alike in a compliance artifact.\n   */\n  sessionRevocation?: {\n    principalUserIds: string[];\n    lookupFailed: boolean;\n  };\n  externalEffects: SubjectErasureExternalEffectOutcome[];\n}\n"]}

package/dist/esm/compliance/privacy/subject-export-render.shared.utils.d.ts

@@ -0,0 +1,74 @@
+import type { SubjectExportBundle } from './subject-export.shared.schemas';
+/**
+ * The wire format a subject export artifact is rendered into.
+ *
+ * GDPR Art. 20 requires a "structured, commonly used and machine-readable format", which is a
+ * property of the OUTPUT, not of the assembly — so it lives here rather than on the orchestrator.
+ * Art. 15 places no format obligation at all, but a subject who receives their access bundle as an
+ * unreadable blob has not meaningfully received it, so both rights render through the same path.
+ *
+ * A closed vocabulary: the four removed export operations declared `format: z.enum(['json','csv','pdf'])`
+ * inline with no renderer behind any of them. `pdf` is deliberately NOT reinstated — it is a
+ * presentation format, not a machine-readable one, and Art. 20 asks for the opposite of a PDF.
+ */
+export declare enum SubjectExportFormat {
+    /**
+     * Canonical and LOSSLESS. Preserves nested objects, arrays, types and nulls exactly as held, and
+     * carries the report alongside the data in one document. This is the format an Art. 20 request
+     * should receive by default — it is the only one a receiving system can re-import without
+     * guessing.
+     */
+    JSON = "json",
+    /**
+     * Tabular and LOSSY, one file per resource. Widely readable by spreadsheet tools, which is why it
+     * is offered at all, but nested values are JSON-encoded into cells and type information is gone.
+     * Never the default for portability.
+     */
+    CSV = "csv"
+}
+/** One file within a rendered export artifact. */
+export interface SubjectExportRenderedFile {
+    /** Filename, stable across renders of the same bundle. */
+    name: string;
+    /** IANA media type, for an HTTP `Content-Type` when the artifact is served. */
+    contentType: string;
+    content: string;
+}
+/**
+ * A rendered export artifact — what is actually handed to (or stored for) the data subject.
+ *
+ * Always a LIST of files, even for JSON which produces exactly one. A subject bundle is inherently
+ * multi-resource, and modelling the single-file case as a bare string would force the CSV path to
+ * either fabricate a join across unrelated tables or silently drop every resource but one.
+ */
+export interface SubjectExportRenderedArtifact {
+    format: SubjectExportFormat;
+    files: SubjectExportRenderedFile[];
+}
+/**
+ * Render an assembled bundle into the artifact the data subject receives.
+ *
+ * ## Why the report travels WITH the data
+ *
+ * It would be simpler to ship only the rows. But a subject handed "your data" with no statement of
+ * what was left out — and on what basis — has been given a bundle that misrepresents itself by
+ * omission. That is the same defect as the routed export operations this capability replaced: a
+ * response that looks complete and is not. The report names every edge that was excluded and every
+ * field narrowed away, so the artifact is self-describing and the subject can tell the difference
+ * between "we hold nothing else" and "the rest is outside this request".
+ *
+ * It also gives an Art. 20 recipient the one thing they cannot otherwise derive: which fields exist
+ * but were withheld as controller-derived, and are therefore obtainable through an Art. 15 request
+ * instead.
+ *
+ * ## Determinism
+ *
+ * The same bundle renders byte-identically every time — column order is first-seen rather than
+ * hash-ordered, and nothing is timestamped at render time. An artifact that changed on every render
+ * could not be content-hashed, checksummed, or compared against a stored copy, which is exactly what
+ * an integrity claim over a compliance artifact needs.
+ *
+ * Pure: no I/O, no clock, no registry. Storing the artifact is a separate concern.
+ */
+export declare function renderSubjectExportBundle(bundle: SubjectExportBundle, format: SubjectExportFormat): SubjectExportRenderedArtifact;
+//# sourceMappingURL=subject-export-render.shared.utils.d.ts.map

package/dist/esm/compliance/privacy/subject-export-render.shared.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subject-export-render.shared.utils.d.ts","sourceRoot":"","sources":["../../../../../src/compliance/privacy/subject-export-render.shared.utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,mBAAmB,EAGpB,MAAM,iCAAiC,CAAC;AAEzC;;;;;;;;;;;GAWG;AACH,oBAAY,mBAAmB;IAC7B;;;;;OAKG;IACH,IAAI,SAAS;IAEb;;;;OAIG;IACH,GAAG,QAAQ;CACZ;AAED,kDAAkD;AAClD,MAAM,WAAW,yBAAyB;IACxC,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,mBAAmB,CAAC;IAC5B,KAAK,EAAE,yBAAyB,EAAE,CAAC;CACpC;AAkED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,mBAAmB,GAC1B,6BAA6B,CAmC/B"}

package/dist/esm/compliance/privacy/subject-export-render.shared.utils.js

@@ -0,0 +1,137 @@
+import { resolveCsvColumnsFromRows, toCsvCell } from '../../exports/tabular-csv.shared.utils.js';
+/**
+ * The wire format a subject export artifact is rendered into.
+ *
+ * GDPR Art. 20 requires a "structured, commonly used and machine-readable format", which is a
+ * property of the OUTPUT, not of the assembly — so it lives here rather than on the orchestrator.
+ * Art. 15 places no format obligation at all, but a subject who receives their access bundle as an
+ * unreadable blob has not meaningfully received it, so both rights render through the same path.
+ *
+ * A closed vocabulary: the four removed export operations declared `format: z.enum(['json','csv','pdf'])`
+ * inline with no renderer behind any of them. `pdf` is deliberately NOT reinstated — it is a
+ * presentation format, not a machine-readable one, and Art. 20 asks for the opposite of a PDF.
+ */
+export var SubjectExportFormat;
+(function (SubjectExportFormat) {
+    /**
+     * Canonical and LOSSLESS. Preserves nested objects, arrays, types and nulls exactly as held, and
+     * carries the report alongside the data in one document. This is the format an Art. 20 request
+     * should receive by default — it is the only one a receiving system can re-import without
+     * guessing.
+     */
+    SubjectExportFormat["JSON"] = "json";
+    /**
+     * Tabular and LOSSY, one file per resource. Widely readable by spreadsheet tools, which is why it
+     * is offered at all, but nested values are JSON-encoded into cells and type information is gone.
+     * Never the default for portability.
+     */
+    SubjectExportFormat["CSV"] = "csv";
+})(SubjectExportFormat || (SubjectExportFormat = {}));
+function renderSliceAsCsv(slice) {
+    // The whole slice is in hand here (a subject bundle is assembled before it is rendered), so the
+    // row-union column resolution is sound. A STREAMING export cannot use it — see its docstring.
+    const columns = resolveCsvColumnsFromRows(slice.rows);
+    const lines = [
+        columns.map(toCsvCell).join(','),
+        ...slice.rows.map((row) => columns.map((column) => toCsvCell(row[column])).join(',')),
+    ];
+    return {
+        name: `${String(slice.resourceType)}.csv`,
+        contentType: 'text/csv',
+        // Trailing newline: POSIX text convention, and several spreadsheet importers drop the final row
+        // without it.
+        content: `${lines.join('\n')}\n`,
+    };
+}
+/**
+ * The report, rendered as prose for a human reading a CSV bundle.
+ *
+ * The JSON format carries the report as structured data; CSV has nowhere to put it, and shipping the
+ * data files alone would be the more serious omission — see {@link renderSubjectExportBundle} on why
+ * the report travels WITH the data.
+ */
+function renderReportAsText(report) {
+    const lines = [
+        'DATA SUBJECT EXPORT — SUMMARY',
+        '',
+        `Request type: ${report.purpose}`,
+        `Subject: ${String(report.subjectResourceType)} (${report.subjectIds.join(', ')})`,
+        `Total records: ${report.totalRecordCount}`,
+        '',
+        'INCLUDED',
+    ];
+    const collected = report.edges.filter((edge) => edge.collected);
+    lines.push(...(collected.length > 0
+        ? collected.map((edge) => `  - ${String(edge.relatedResourceType)}: ${edge.recordCount} record(s)`)
+        : ['  (no related records)']));
+    const omitted = report.edges.filter((edge) => !edge.collected);
+    if (omitted.length > 0) {
+        lines.push('', 'NOT INCLUDED, AND WHY');
+        lines.push(...omitted.map((edge) => `  - ${String(edge.relatedResourceType)}: ${edge.reason}`));
+    }
+    if (report.fieldsExcludedAsDerived.length > 0) {
+        lines.push('', 'FIELDS OUTSIDE THIS REQUEST (controller-derived; available under a right-of-access request)', ...report.fieldsExcludedAsDerived.map((field) => `  - ${field}`));
+    }
+    if (report.fieldsWithheldAsNonDisclosable.length > 0) {
+        lines.push('', 'FIELDS WITHHELD (security-sensitive; not disclosable under any request)', ...report.fieldsWithheldAsNonDisclosable.map((field) => `  - ${field}`));
+    }
+    return { name: 'SUMMARY.txt', contentType: 'text/plain', content: `${lines.join('\n')}\n` };
+}
+/**
+ * Render an assembled bundle into the artifact the data subject receives.
+ *
+ * ## Why the report travels WITH the data
+ *
+ * It would be simpler to ship only the rows. But a subject handed "your data" with no statement of
+ * what was left out — and on what basis — has been given a bundle that misrepresents itself by
+ * omission. That is the same defect as the routed export operations this capability replaced: a
+ * response that looks complete and is not. The report names every edge that was excluded and every
+ * field narrowed away, so the artifact is self-describing and the subject can tell the difference
+ * between "we hold nothing else" and "the rest is outside this request".
+ *
+ * It also gives an Art. 20 recipient the one thing they cannot otherwise derive: which fields exist
+ * but were withheld as controller-derived, and are therefore obtainable through an Art. 15 request
+ * instead.
+ *
+ * ## Determinism
+ *
+ * The same bundle renders byte-identically every time — column order is first-seen rather than
+ * hash-ordered, and nothing is timestamped at render time. An artifact that changed on every render
+ * could not be content-hashed, checksummed, or compared against a stored copy, which is exactly what
+ * an integrity claim over a compliance artifact needs.
+ *
+ * Pure: no I/O, no clock, no registry. Storing the artifact is a separate concern.
+ */
+export function renderSubjectExportBundle(bundle, format) {
+    switch (format) {
+        case SubjectExportFormat.JSON:
+            return {
+                format,
+                files: [{
+                        name: 'subject-export.json',
+                        contentType: 'application/json',
+                        // `report` first: a reader opening the file meets the account of what this bundle is and
+                        // what it omits before the rows themselves.
+                        content: `${JSON.stringify({ report: bundle.report, data: bundle.slices }, null, 2)}\n`,
+                    }],
+            };
+        case SubjectExportFormat.CSV:
+            return {
+                format,
+                files: [
+                    renderReportAsText(bundle.report),
+                    // A slice with no rows still produces its (header-only) file: "this resource was read and
+                    // held nothing for you" is a different statement from the file being absent, and the
+                    // report distinguishes them too.
+                    ...bundle.slices.map(renderSliceAsCsv),
+                ],
+            };
+        default: {
+            // Compile-time exhaustiveness: a new format without a renderer is a TYPE error here, not a
+            // subject receiving an empty artifact.
+            const _exhaustiveFormatCheck = format;
+            throw new Error(`renderSubjectExportBundle has no renderer for format '${String(_exhaustiveFormatCheck)}'`);
+        }
+    }
+}
+//# sourceMappingURL=subject-export-render.shared.utils.js.map

package/dist/esm/compliance/privacy/subject-export-render.shared.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subject-export-render.shared.utils.js","sourceRoot":"","sources":["../../../../../src/compliance/privacy/subject-export-render.shared.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import { resolveCsvColumnsFromRows, toCsvCell } from '../../exports/tabular-csv.shared.utils';\nimport type {\n  SubjectExportBundle,\n  SubjectExportReport,\n  SubjectExportResourceSlice,\n} from './subject-export.shared.schemas';\n\n/**\n * The wire format a subject export artifact is rendered into.\n *\n * GDPR Art. 20 requires a \"structured, commonly used and machine-readable format\", which is a\n * property of the OUTPUT, not of the assembly — so it lives here rather than on the orchestrator.\n * Art. 15 places no format obligation at all, but a subject who receives their access bundle as an\n * unreadable blob has not meaningfully received it, so both rights render through the same path.\n *\n * A closed vocabulary: the four removed export operations declared `format: z.enum(['json','csv','pdf'])`\n * inline with no renderer behind any of them. `pdf` is deliberately NOT reinstated — it is a\n * presentation format, not a machine-readable one, and Art. 20 asks for the opposite of a PDF.\n */\nexport enum SubjectExportFormat {\n  /**\n   * Canonical and LOSSLESS. Preserves nested objects, arrays, types and nulls exactly as held, and\n   * carries the report alongside the data in one document. This is the format an Art. 20 request\n   * should receive by default — it is the only one a receiving system can re-import without\n   * guessing.\n   */\n  JSON = 'json',\n\n  /**\n   * Tabular and LOSSY, one file per resource. Widely readable by spreadsheet tools, which is why it\n   * is offered at all, but nested values are JSON-encoded into cells and type information is gone.\n   * Never the default for portability.\n   */\n  CSV = 'csv',\n}\n\n/** One file within a rendered export artifact. */\nexport interface SubjectExportRenderedFile {\n  /** Filename, stable across renders of the same bundle. */\n  name: string;\n  /** IANA media type, for an HTTP `Content-Type` when the artifact is served. */\n  contentType: string;\n  content: string;\n}\n\n/**\n * A rendered export artifact — what is actually handed to (or stored for) the data subject.\n *\n * Always a LIST of files, even for JSON which produces exactly one. A subject bundle is inherently\n * multi-resource, and modelling the single-file case as a bare string would force the CSV path to\n * either fabricate a join across unrelated tables or silently drop every resource but one.\n */\nexport interface SubjectExportRenderedArtifact {\n  format: SubjectExportFormat;\n  files: SubjectExportRenderedFile[];\n}\n\nfunction renderSliceAsCsv(slice: SubjectExportResourceSlice): SubjectExportRenderedFile {\n  // The whole slice is in hand here (a subject bundle is assembled before it is rendered), so the\n  // row-union column resolution is sound. A STREAMING export cannot use it — see its docstring.\n  const columns = resolveCsvColumnsFromRows(slice.rows);\n  const lines = [\n    columns.map(toCsvCell).join(','),\n    ...slice.rows.map((row) => columns.map((column) => toCsvCell(row[column])).join(',')),\n  ];\n  return {\n    name: `${String(slice.resourceType)}.csv`,\n    contentType: 'text/csv',\n    // Trailing newline: POSIX text convention, and several spreadsheet importers drop the final row\n    // without it.\n    content: `${lines.join('\\n')}\\n`,\n  };\n}\n\n/**\n * The report, rendered as prose for a human reading a CSV bundle.\n *\n * The JSON format carries the report as structured data; CSV has nowhere to put it, and shipping the\n * data files alone would be the more serious omission — see {@link renderSubjectExportBundle} on why\n * the report travels WITH the data.\n */\nfunction renderReportAsText(report: SubjectExportReport): SubjectExportRenderedFile {\n  const lines: string[] = [\n    'DATA SUBJECT EXPORT — SUMMARY',\n    '',\n    `Request type: ${report.purpose}`,\n    `Subject: ${String(report.subjectResourceType)} (${report.subjectIds.join(', ')})`,\n    `Total records: ${report.totalRecordCount}`,\n    '',\n    'INCLUDED',\n  ];\n  const collected = report.edges.filter((edge) => edge.collected);\n  lines.push(\n    ...(collected.length > 0\n      ? collected.map((edge) => `  - ${String(edge.relatedResourceType)}: ${edge.recordCount} record(s)`)\n      : ['  (no related records)']),\n  );\n\n  const omitted = report.edges.filter((edge) => !edge.collected);\n  if (omitted.length > 0) {\n    lines.push('', 'NOT INCLUDED, AND WHY');\n    lines.push(...omitted.map((edge) => `  - ${String(edge.relatedResourceType)}: ${edge.reason}`));\n  }\n  if (report.fieldsExcludedAsDerived.length > 0) {\n    lines.push(\n      '',\n      'FIELDS OUTSIDE THIS REQUEST (controller-derived; available under a right-of-access request)',\n      ...report.fieldsExcludedAsDerived.map((field) => `  - ${field}`),\n    );\n  }\n  if (report.fieldsWithheldAsNonDisclosable.length > 0) {\n    lines.push(\n      '',\n      'FIELDS WITHHELD (security-sensitive; not disclosable under any request)',\n      ...report.fieldsWithheldAsNonDisclosable.map((field) => `  - ${field}`),\n    );\n  }\n\n  return { name: 'SUMMARY.txt', contentType: 'text/plain', content: `${lines.join('\\n')}\\n` };\n}\n\n/**\n * Render an assembled bundle into the artifact the data subject receives.\n *\n * ## Why the report travels WITH the data\n *\n * It would be simpler to ship only the rows. But a subject handed \"your data\" with no statement of\n * what was left out — and on what basis — has been given a bundle that misrepresents itself by\n * omission. That is the same defect as the routed export operations this capability replaced: a\n * response that looks complete and is not. The report names every edge that was excluded and every\n * field narrowed away, so the artifact is self-describing and the subject can tell the difference\n * between \"we hold nothing else\" and \"the rest is outside this request\".\n *\n * It also gives an Art. 20 recipient the one thing they cannot otherwise derive: which fields exist\n * but were withheld as controller-derived, and are therefore obtainable through an Art. 15 request\n * instead.\n *\n * ## Determinism\n *\n * The same bundle renders byte-identically every time — column order is first-seen rather than\n * hash-ordered, and nothing is timestamped at render time. An artifact that changed on every render\n * could not be content-hashed, checksummed, or compared against a stored copy, which is exactly what\n * an integrity claim over a compliance artifact needs.\n *\n * Pure: no I/O, no clock, no registry. Storing the artifact is a separate concern.\n */\nexport function renderSubjectExportBundle(\n  bundle: SubjectExportBundle,\n  format: SubjectExportFormat,\n): SubjectExportRenderedArtifact {\n  switch (format) {\n    case SubjectExportFormat.JSON:\n      return {\n        format,\n        files: [{\n          name: 'subject-export.json',\n          contentType: 'application/json',\n          // `report` first: a reader opening the file meets the account of what this bundle is and\n          // what it omits before the rows themselves.\n          content: `${JSON.stringify({ report: bundle.report, data: bundle.slices }, null, 2)}\\n`,\n        }],\n      };\n\n    case SubjectExportFormat.CSV:\n      return {\n        format,\n        files: [\n          renderReportAsText(bundle.report),\n          // A slice with no rows still produces its (header-only) file: \"this resource was read and\n          // held nothing for you\" is a different statement from the file being absent, and the\n          // report distinguishes them too.\n          ...bundle.slices.map(renderSliceAsCsv),\n        ],\n      };\n\n    default: {\n      // Compile-time exhaustiveness: a new format without a renderer is a TYPE error here, not a\n      // subject receiving an empty artifact.\n      const _exhaustiveFormatCheck: never = format;\n      throw new Error(\n        `renderSubjectExportBundle has no renderer for format '${String(_exhaustiveFormatCheck)}'`,\n      );\n    }\n  }\n}\n"]}