@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/compliance/privacy/retention-schedule.shared.schemas.js

@@ -0,0 +1,107 @@
+import { z } from "zod";
+/**
+ * **The four data classes an application declares a retention period for.**
+ *
+ * ## Why four, and not one per resource
+ *
+ * `retentionPolicy.mode` on a resource says WHAT erasure does to a row. Nothing said HOW LONG a row
+ * is kept, and a privacy notice cannot be written without that number: a confident paragraph about
+ * impersonalization READS to a reader as an answer about retention, so the derivable half made the
+ * missing half harder to see rather than easier (issue #89).
+ *
+ * The first design put a duration on every resource. It was rejected as false precision: an operator
+ * decides "customer data three years, logs ninety days, audit seven years", not twelve numbers, and
+ * twelve numbers are twelve things to keep true. What an operator actually decides is a schedule over
+ * DATA CLASSES — and those classes are the ones that already differ in law, in storage and in who
+ * asks for them.
+ *
+ * ## The classes are the STORES, and that is deliberate
+ *
+ * Each member maps to a distinct backing service, so one declaration answers two questions that have
+ * always been asked separately: what a privacy notice must state, and what a backup-and-restore
+ * inventory must protect and for how long (issue #8, which today has no inventory of any kind).
+ *
+ * | class | where it lives |
+ * |---|---|
+ * | {@link RESOURCE_DATA} | MongoDB / PostgreSQL |
+ * | {@link FILES} | MinIO / S3 |
+ * | {@link AUDIT_LOGS} | immudb — the tamper-evident ledger |
+ * | {@link OPERATIONAL_LOGS} | the logging pipeline |
+ *
+ * Splitting further is available later and is not free: every additional class is another period an
+ * operator must decide and defend, and an undecided period is worse than a coarse one.
+ */
+export var DataRetentionClass;
+(function (DataRetentionClass) {
+    /**
+     * The application's own records — every resource row in its primary datastore.
+     *
+     * The class a privacy notice's retention paragraph is mostly about, because it is where the data a
+     * customer gave the application lives.
+     */
+    DataRetentionClass["RESOURCE_DATA"] = "RESOURCE_DATA";
+    /** Uploaded file BYTES in object storage. Separate because their lawful window rarely matches the row that references them, and because losing them is a different incident from losing a row. */
+    DataRetentionClass["FILES"] = "FILES";
+    /**
+     * The audit trail.
+     *
+     * Kept longest, and for a reason no other class shares: it is the record an operator needs to
+     * DEFEND itself, which is exactly the GDPR Art. 17(3) ground on which erasure may lawfully be
+     * refused. Never fold this into {@link RESOURCE_DATA} — doing so would let a shorter customer-data
+     * period silently shorten the evidence an operator may need years later.
+     */
+    DataRetentionClass["AUDIT_LOGS"] = "AUDIT_LOGS";
+    /** Operational and diagnostic logs. Usually the shortest period, and the one most often left undeclared because nobody thinks of it as personal data — it routinely carries IP addresses and user identifiers. */
+    DataRetentionClass["OPERATIONAL_LOGS"] = "OPERATIONAL_LOGS";
+})(DataRetentionClass || (DataRetentionClass = {}));
+/**
+ * One declared retention period.
+ *
+ * `retentionDays` is REQUIRED when a class is declared at all: the whole point is the number. A class
+ * an application has not decided is OMITTED from the schedule, which is a different answer and stays
+ * a different answer — see {@link ApplicationRetentionScheduleSchema}.
+ */
+export const DataRetentionPeriodSchema = z.strictObject({
+    /**
+     * How long a record of this class is kept, counted from the point the application stops needing it
+     * for the purpose it was collected for.
+     *
+     * Days rather than a duration string because it is the unit every downstream consumer needs — a
+     * notice renders it, a backup schedule compares it, and a sweep would subtract it. A free-text
+     * period ("as long as necessary") is the placeholder this field exists to make impossible.
+     */
+    retentionDays: z.number().int().positive(),
+    /**
+     * WHY this period, in the operator's words — the lawful basis, the contractual term, the statutory
+     * minimum.
+     *
+     * Required, and it is the field that keeps the number honest: a period with no stated reason is a
+     * guess that will be published as a commitment. A notice may render it; a reviewer certainly reads it.
+     */
+    rationale: z.string().trim().min(1),
+});
+/**
+ * The application's declared retention schedule — a period per {@link DataRetentionClass}.
+ *
+ * ## Partial ON PURPOSE, and absence is never read as "kept forever"
+ *
+ * Every class is optional, and an omitted class means *the operator has not decided this yet* — not
+ * that nothing is kept, and not that it is kept indefinitely. Both of those would be a statement, and
+ * neither is one anybody made.
+ *
+ * That is what makes this safe to ship before an operator has answered: a compliance document states
+ * the classes that ARE declared and marks the rest as needing a decision, naming who supplies it. The
+ * alternative — requiring all four — would block a document on a number nobody has yet, which is
+ * exactly the gate this whole capability exists to remove. **Never default a period.**
+ */
+export const ApplicationRetentionScheduleSchema = z.partialRecord(z.enum(DataRetentionClass), DataRetentionPeriodSchema);
+/**
+ * The classes an application has NOT declared a period for — what a document must mark as owed.
+ *
+ * Derived rather than stored, and total over the enum, so a class added to the vocabulary tomorrow is
+ * reported as undeclared by every existing application rather than silently omitted from the answer.
+ */
+export function undeclaredRetentionClasses(schedule) {
+    return Object.values(DataRetentionClass).filter((dataClass) => schedule?.[dataClass] === undefined);
+}
+//# sourceMappingURL=retention-schedule.shared.schemas.js.map

package/dist/esm/compliance/privacy/retention-schedule.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention-schedule.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/compliance/privacy/retention-schedule.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAN,IAAY,kBAqBX;AArBD,WAAY,kBAAkB;IAC5B;;;;;OAKG;IACH,qDAA+B,CAAA;IAC/B,kMAAkM;IAClM,qCAAe,CAAA;IACf;;;;;;;OAOG;IACH,+CAAyB,CAAA;IACzB,kNAAkN;IAClN,2DAAqC,CAAA;AACvC,CAAC,EArBW,kBAAkB,KAAlB,kBAAkB,QAqB7B;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,YAAY,CAAC;IACtD;;;;;;;OAOG;IACH,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IAC1C;;;;;;OAMG;IACH,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACpC,CAAC,CAAC;AAGH;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,CAAC,CAAC,aAAa,CAC/D,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,EAC1B,yBAAyB,CAC1B,CAAC;AAGF;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CACxC,QAAkD;IAElD,OAAO,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,QAAQ,EAAE,CAAC,SAAS,CAAC,KAAK,SAAS,CAAC,CAAC;AACtG,CAAC","sourcesContent":["import { z } from \"zod\";\n\n/**\n * **The four data classes an application declares a retention period for.**\n *\n * ## Why four, and not one per resource\n *\n * `retentionPolicy.mode` on a resource says WHAT erasure does to a row. Nothing said HOW LONG a row\n * is kept, and a privacy notice cannot be written without that number: a confident paragraph about\n * impersonalization READS to a reader as an answer about retention, so the derivable half made the\n * missing half harder to see rather than easier (issue #89).\n *\n * The first design put a duration on every resource. It was rejected as false precision: an operator\n * decides \"customer data three years, logs ninety days, audit seven years\", not twelve numbers, and\n * twelve numbers are twelve things to keep true. What an operator actually decides is a schedule over\n * DATA CLASSES — and those classes are the ones that already differ in law, in storage and in who\n * asks for them.\n *\n * ## The classes are the STORES, and that is deliberate\n *\n * Each member maps to a distinct backing service, so one declaration answers two questions that have\n * always been asked separately: what a privacy notice must state, and what a backup-and-restore\n * inventory must protect and for how long (issue #8, which today has no inventory of any kind).\n *\n * | class | where it lives |\n * |---|---|\n * | {@link RESOURCE_DATA} | MongoDB / PostgreSQL |\n * | {@link FILES} | MinIO / S3 |\n * | {@link AUDIT_LOGS} | immudb — the tamper-evident ledger |\n * | {@link OPERATIONAL_LOGS} | the logging pipeline |\n *\n * Splitting further is available later and is not free: every additional class is another period an\n * operator must decide and defend, and an undecided period is worse than a coarse one.\n */\nexport enum DataRetentionClass {\n  /**\n   * The application's own records — every resource row in its primary datastore.\n   *\n   * The class a privacy notice's retention paragraph is mostly about, because it is where the data a\n   * customer gave the application lives.\n   */\n  RESOURCE_DATA = \"RESOURCE_DATA\",\n  /** Uploaded file BYTES in object storage. Separate because their lawful window rarely matches the row that references them, and because losing them is a different incident from losing a row. */\n  FILES = \"FILES\",\n  /**\n   * The audit trail.\n   *\n   * Kept longest, and for a reason no other class shares: it is the record an operator needs to\n   * DEFEND itself, which is exactly the GDPR Art. 17(3) ground on which erasure may lawfully be\n   * refused. Never fold this into {@link RESOURCE_DATA} — doing so would let a shorter customer-data\n   * period silently shorten the evidence an operator may need years later.\n   */\n  AUDIT_LOGS = \"AUDIT_LOGS\",\n  /** Operational and diagnostic logs. Usually the shortest period, and the one most often left undeclared because nobody thinks of it as personal data — it routinely carries IP addresses and user identifiers. */\n  OPERATIONAL_LOGS = \"OPERATIONAL_LOGS\",\n}\n\n/**\n * One declared retention period.\n *\n * `retentionDays` is REQUIRED when a class is declared at all: the whole point is the number. A class\n * an application has not decided is OMITTED from the schedule, which is a different answer and stays\n * a different answer — see {@link ApplicationRetentionScheduleSchema}.\n */\nexport const DataRetentionPeriodSchema = z.strictObject({\n  /**\n   * How long a record of this class is kept, counted from the point the application stops needing it\n   * for the purpose it was collected for.\n   *\n   * Days rather than a duration string because it is the unit every downstream consumer needs — a\n   * notice renders it, a backup schedule compares it, and a sweep would subtract it. A free-text\n   * period (\"as long as necessary\") is the placeholder this field exists to make impossible.\n   */\n  retentionDays: z.number().int().positive(),\n  /**\n   * WHY this period, in the operator's words — the lawful basis, the contractual term, the statutory\n   * minimum.\n   *\n   * Required, and it is the field that keeps the number honest: a period with no stated reason is a\n   * guess that will be published as a commitment. A notice may render it; a reviewer certainly reads it.\n   */\n  rationale: z.string().trim().min(1),\n});\nexport type DataRetentionPeriod = z.infer<typeof DataRetentionPeriodSchema>;\n\n/**\n * The application's declared retention schedule — a period per {@link DataRetentionClass}.\n *\n * ## Partial ON PURPOSE, and absence is never read as \"kept forever\"\n *\n * Every class is optional, and an omitted class means *the operator has not decided this yet* — not\n * that nothing is kept, and not that it is kept indefinitely. Both of those would be a statement, and\n * neither is one anybody made.\n *\n * That is what makes this safe to ship before an operator has answered: a compliance document states\n * the classes that ARE declared and marks the rest as needing a decision, naming who supplies it. The\n * alternative — requiring all four — would block a document on a number nobody has yet, which is\n * exactly the gate this whole capability exists to remove. **Never default a period.**\n */\nexport const ApplicationRetentionScheduleSchema = z.partialRecord(\n  z.enum(DataRetentionClass),\n  DataRetentionPeriodSchema,\n);\nexport type ApplicationRetentionSchedule = z.infer<typeof ApplicationRetentionScheduleSchema>;\n\n/**\n * The classes an application has NOT declared a period for — what a document must mark as owed.\n *\n * Derived rather than stored, and total over the enum, so a class added to the vocabulary tomorrow is\n * reported as undeclared by every existing application rather than silently omitted from the answer.\n */\nexport function undeclaredRetentionClasses(\n  schedule: ApplicationRetentionSchedule | undefined,\n): readonly DataRetentionClass[] {\n  return Object.values(DataRetentionClass).filter((dataClass) => schedule?.[dataClass] === undefined);\n}\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"sharing.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/compliance/privacy/sharing.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC"}
+{"version":3,"file":"sharing.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/compliance/privacy/sharing.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC"}

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

@@ -1 +1 @@
-//# sourceMappingURL=sharing.shared.schemas.js.map
+//# sourceMappingURL=sharing.shared.schemas.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"sharing.shared.schemas.js","sourceRoot":"","sources":["../../../../src/compliance/privacy/sharing.shared.schemas.ts"],"names":[],"mappings":""}
+{"version":3,"file":"sharing.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/compliance/privacy/sharing.shared.schemas.ts"],"names":[],"mappings":"","sourcesContent":["export {};"]}

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

@@ -0,0 +1,279 @@
+import { type ResourceRelationship } from '../../resources/resources.shared.schemas';
+import type { ResourceType } from '../../resources/resources.shared.core.definitions';
+/**
+ * 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 declare enum 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.
+     */
+    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.
+     */
+    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.
+     */
+    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).
+     */
+    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.
+     */
+    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.
+     */
+    UNSUPPORTED_DEFERRED = "unsupported_deferred"
+}
+/** The classification of ONE child-direction edge of an erasure subject. */
+export interface SubjectErasureEdgeClassification {
+    /** The dependent resource on the far side of the edge. */
+    childResourceType: ResourceType;
+    /** What the erasure will do with that dependent's rows. */
+    disposition: SubjectErasureDisposition;
+    /**
+     * Human-readable justification, quoting the configuration that produced it. Surfaced in the
+     * erasure report and in the fail-loud error, so an operator never has to re-derive WHY a row was
+     * deleted, retained, or refused.
+     */
+    reason: string;
+}
+/**
+ * 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 declare function isBlockingSubjectErasureDisposition(disposition: SubjectErasureDisposition): boolean;
+/**
+ * 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 declare function classifySubjectErasureDisposition(relationship: ResourceRelationship): SubjectErasureEdgeClassification;
+/** Per-edge outcome of an executed erasure — the classification plus what actually happened. */
+export interface SubjectErasureEdgeOutcome extends SubjectErasureEdgeClassification {
+    /**
+     * `true` when the erasure ran a teardown for this edge.
+     *
+     * Reports that the teardown RAN, not that rows existed — discovery finding no dependents is a
+     * teardown that ran with nothing to do, and is `true`.
+     *
+     * **Read it together with `disposition`, because `false` has two very different meanings:**
+     *
+     * - a NON-executing disposition (`RETAINED_BY_DECLARATION`, `NOT_OWNED`) ⇒ the erasure deliberately
+     *   left the rows alone, and `false` is the expected, correct answer;
+     * - an EXECUTING disposition (`DELETE`, `IMPERSONALIZE_AND_RETAIN`) ⇒ the cascade DECLINED the edge
+     *   (the child had no registered service or repository, or the depth budget was spent). The
+     *   subject's data is partly still live. This pairing should never appear in a healthy system; it is
+     *   logged at ERROR when it happens, with the missing registration named.
+     *
+     * ⚠️ This flag was set unconditionally until 2026-08-11 — it meant "the dispatcher returned without
+     * throwing" and reported a skipped edge as torn down. Anything persisted before that date overstates
+     * what was erased. Treat this field as evidence only for reports produced after the fix.
+     */
+    executed: boolean;
+}
+/**
+ * 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 declare enum SubjectErasureExternalEffectStatus {
+    /** Every step of the effect completed against the external system. */
+    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.
+     */
+    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.
+     */
+    PARTIAL = "partial",
+    /** The effect could not run at all (provider unreachable, not configured). Nothing was changed. */
+    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.
+     */
+    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).
+     */
+    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`).
+     */
+    ACKNOWLEDGED_NON_ERASURE = "acknowledged-non-erasure"
+}
+/** Whether an external-effect status leaves personal data potentially live at a third party. */
+export declare function isIncompleteSubjectErasureExternalEffect(status: SubjectErasureExternalEffectStatus): boolean;
+export interface SubjectErasureExternalEffectOutcome {
+    /** Stable identifier of the effect, e.g. `'billing-provider'`. */
+    effectRef: string;
+    status: SubjectErasureExternalEffectStatus;
+    /**
+     * Human-readable account of what ran, for the compliance artifact. On `PARTIAL` / `FAILED` this
+     * must name what did NOT happen — the report is the only place that survives the request.
+     */
+    detail: string;
+    /**
+     * Per-step results, so a partial outcome is actionable rather than merely alarming (which step
+     * against which external id). Never carries personal data — ids and step names only.
+     */
+    steps?: Array<{
+        step: string;
+        targetRef?: string;
+        succeeded: boolean;
+        error?: string;
+    }>;
+}
+/**
+ * What one subject erasure did — the compliance artifact of a "delete my account" request.
+ *
+ * Returned to the caller (rather than only logged) so the flow that fronts the request can record
+ * or surface it: every edge of the subject appears exactly once with the disposition applied and
+ * the configuration that justified it, which is the evidence a data-protection response needs.
+ */
+export interface SubjectErasureReport {
+    /** The erased subject's resource type. */
+    subjectResourceType: ResourceType;
+    /** The erased subject rows. */
+    subjectIds: string[];
+    /** Every child-direction edge of the subject, classified, in registry order. */
+    edges: SubjectErasureEdgeOutcome[];
+    /**
+     * `true` once the subject rows themselves were scrubbed and flipped to `RETAINED`. Always `true`
+     * on a successful erasure — an erasure that could not retain its subject throws rather than
+     * returning a report.
+     */
+    subjectImpersonalized: boolean;
+    /**
+     * Outcomes of the external, non-transactional effects the erasure triggered — every SYSTEM WE
+     * DO NOT OWN that the subject's personal data reached: registered effect handlers (a billing
+     * provider), and each HTTP_API-bound resource linked to the subject (one entry per resource,
+     * `effectRef: 'http-api:<resourceType>'`, carrying its declared D6 erasure stance's outcome).
+     *
+     * Empty when no effect was registered for the subject's resource type. These run AFTER the local
+     * scrub has committed, so a failure here cannot roll the erasure back — the local data is
+     * already gone and re-running the whole erasure would be wrong. That asymmetry is precisely why
+     * the outcome is reported rather than thrown: the local part genuinely succeeded, and the caller
+     * needs to know that a third party still holds something.
+     *
+     * Check {@link isIncompleteSubjectErasureExternalEffect} over these before treating a report as a
+     * complete erasure.
+     */
+    /**
+     * Whose sessions this erasure ended, and whether resolving them failed.
+     *
+     * A LOCAL fact, not an external effect: the revocation is a write to our own session fence, applied
+     * at the scrub chokepoint so it covers every path that scrubs a person's row. It is recorded here
+     * because "the erased person can no longer be logged in" is exactly what a data-protection response
+     * has to be able to evidence.
+     *
+     * `lookupFailed` is kept distinct from an empty `principalUserIds`: no principals is a legitimate
+     * outcome (the resource declared `NO_PRINCIPAL`), whereas a failed lookup means the person may
+     * still hold a live session — and the two must never look alike in a compliance artifact.
+     */
+    sessionRevocation?: {
+        principalUserIds: string[];
+        lookupFailed: boolean;
+    };
+    externalEffects: SubjectErasureExternalEffectOutcome[];
+}
+//# sourceMappingURL=subject-erasure.shared.schemas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"subject-erasure.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/compliance/privacy/subject-erasure.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,0CAA0C,CAAC;AAMlD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mDAAmD,CAAC;AAEtF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,oBAAY,yBAAyB;IACnC;;;;;OAKG;IACH,MAAM,WAAW;IAEjB;;;;OAIG;IACH,wBAAwB,6BAA6B;IAErD;;;;;;;;OAQG;IACH,uBAAuB,4BAA4B;IAEnD;;;;;OAKG;IACH,SAAS,cAAc;IAEvB;;;;;OAKG;IACH,YAAY,iBAAiB;IAE7B;;;;;OAKG;IACH,oBAAoB,yBAAyB;CAC9C;AAED,4EAA4E;AAC5E,MAAM,WAAW,gCAAgC;IAC/C,0DAA0D;IAC1D,iBAAiB,EAAE,YAAY,CAAC;IAChC,2DAA2D;IAC3D,WAAW,EAAE,yBAAyB,CAAC;IACvC;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAQD;;;;;;GAMG;AACH,wBAAgB,mCAAmC,CACjD,WAAW,EAAE,yBAAyB,GACrC,OAAO,CAET;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,iCAAiC,CAC/C,YAAY,EAAE,oBAAoB,GACjC,gCAAgC,CA0FlC;AAED,gGAAgG;AAChG,MAAM,WAAW,yBAA0B,SAAQ,gCAAgC;IACjF;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,oBAAY,kCAAkC;IAC5C,sEAAsE;IACtE,SAAS,cAAc;IACvB;;;;OAIG;IACH,gBAAgB,qBAAqB;IACrC;;;;OAIG;IACH,OAAO,YAAY;IACnB,mGAAmG;IACnG,MAAM,WAAW;IACjB;;;OAGG;IACH,cAAc,mBAAmB;IAEjC;;;;;;;OAOG;IACH,wBAAwB,6BAA6B;IAErD;;;;;;;;;OASG;IACH,wBAAwB,6BAA6B;CACtD;AAED,gGAAgG;AAChG,wBAAgB,wCAAwC,CACtD,MAAM,EAAE,kCAAkC,GACzC,OAAO,CAOT;AAED,MAAM,WAAW,mCAAmC;IAClD,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,kCAAkC,CAAC;IAC3C;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACzF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,0CAA0C;IAC1C,mBAAmB,EAAE,YAAY,CAAC;IAClC,+BAA+B;IAC/B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,gFAAgF;IAChF,KAAK,EAAE,yBAAyB,EAAE,CAAC;IACnC;;;;OAIG;IACH,qBAAqB,EAAE,OAAO,CAAC;IAC/B;;;;;;;;;;;;;;OAcG;IACH;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,EAAE;QAClB,gBAAgB,EAAE,MAAM,EAAE,CAAC;QAC3B,YAAY,EAAE,OAAO,CAAC;KACvB,CAAC;IACF,eAAe,EAAE,mCAAmC,EAAE,CAAC;CACxD"}