@wildo-ai/saas-models 1.1.4 → 1.1.6

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

@@ -0,0 +1,226 @@
+/**
+ * One row per (retention-class sweep run × class-bound resource): what the run deleted for that resource,
+ * under which declared period, what it held back, and how it ended (#1636).
+ *
+ * ## Why a store, when the sweep already returns its outcome
+ *
+ * GDPR Art. 5(1)(e) (storage limitation) is a principle the operator must be able to DEMONSTRATE
+ * (Art. 5(2), accountability). The sweep's run output is transient: a successful run's result is kept only
+ * as long as the job execution that carried it, and a failed run survives only as an invocation status. So
+ * after #1613 the engine deleted by period and nothing durable said that it had. This row is that record,
+ * and it is the first producer of `AssuranceDocumentFactAuthorityKind.RUNTIME_EVIDENCE`: a privacy notice
+ * says a class's retention is ENFORCED only when these rows show it.
+ *
+ * ## Counts and instants only, by construction
+ *
+ * The evidence must outlive the rows it describes WITHOUT re-creating them. So no field names a deleted
+ * row, and none carries a field value: {@link projectRetentionEnforcementRecord} is the only producer and
+ * copies a closed list of counts, instants and vocabulary members. A row id or a value added here would
+ * turn deletion evidence into a copy of what was deleted — the key set is pinned by a test for that reason.
+ *
+ * ## Every run, including a failed one
+ *
+ * The sweep writes one row per bound resource per run in a `finally`, so a run that fails still leaves a
+ * `FAILED` row: a failed run is evidence too, and an operator whose sweep stopped working must be able to
+ * see WHEN it stopped. A resource the sweep skipped leaves a `SKIPPED` row naming why, because a skip that
+ * leaves nothing is indistinguishable from a sweep that never ran.
+ *
+ * ## Retention of the evidence itself
+ *
+ * Bound to `AUDIT_LOGS` from `CREATED` (see the resource configuration): this is the operator's defence
+ * evidence, so it is kept as long as the audit trail and outlives the data it describes.
+ *
+ * assurance-control: WILDO.PRIVACY.STORAGE_LIMITATION — records evidence that declared retention was enforced.
+ */
+import { z } from 'zod';
+import { DataRetentionClass, RetentionStartPoint } from './retention-schedule.shared.schemas.js';
+/** @wildo_source:part:start saas.models.privacy.retention-enforcement-record facet:layer:shared facet:audience:app-developer */
+/**
+ * How one sweep run ended for one class-bound resource. The three non-skip members are the three outcomes
+ * the sweep distinguishes; `SKIPPED` is a resource the sweep deliberately did not work on this run.
+ */
+export var RetentionEnforcementOutcome;
+(function (RetentionEnforcementOutcome) {
+    /** Every row past its period that the sweep listed was deleted; nothing was left for the next run. */
+    RetentionEnforcementOutcome["COMPLETED"] = "COMPLETED";
+    /**
+     * The run stopped at its per-run ceiling with expired rows still waiting, which the next run resumes.
+     * Normal operation after a period is shortened or a backlog builds up, and NOT a failure: the period is
+     * being enforced, bounded per run so a mistake cannot become one unbounded delete.
+     */
+    RetentionEnforcementOutcome["DEFERRED_BY_CEILING"] = "DEFERRED_BY_CEILING";
+    /** Listing or deleting failed, or the delete removed nothing. Retention was NOT enforced for this resource this run. */
+    RetentionEnforcementOutcome["FAILED"] = "FAILED";
+    /** The sweep did not work on this resource this run; `skipReason` says why. Neither enforcement nor failure. */
+    RetentionEnforcementOutcome["SKIPPED"] = "SKIPPED";
+})(RetentionEnforcementOutcome || (RetentionEnforcementOutcome = {}));
+/** Which step of a resource's sweep failed. Named so the log, the thrown message and the record say the same thing. */
+export var RetentionClassSweepFailureStage;
+(function (RetentionClassSweepFailureStage) {
+    /** Listing expired rows failed, so nothing more was deleted for that resource this run. */
+    RetentionClassSweepFailureStage["READ"] = "read";
+    /** A service-layer delete failed; earlier rows of the same resource may already be deleted. */
+    RetentionClassSweepFailureStage["DELETE"] = "delete";
+    /** The same rows were listed again after being deleted — the delete removed nothing, so the sweep stopped rather than loop. */
+    RetentionClassSweepFailureStage["NO_PROGRESS"] = "no-progress";
+    /**
+     * The active legal holds could not be read (#1634), so whether the listed rows are held is unknown. The
+     * sweep deletes nothing more for that resource this run — a read error never means "not held".
+     */
+    RetentionClassSweepFailureStage["LEGAL_HOLD_UNVERIFIABLE"] = "legal-hold-unverifiable";
+    /**
+     * The resource's sweep THREW instead of returning an outcome (every expected failure is caught and reported as
+     * one of the stages above). Deletions it made before throwing are not counted, so read `deletedCount: 0` on
+     * this stage as "unknown", not as "none".
+     */
+    RetentionClassSweepFailureStage["UNEXPECTED"] = "unexpected";
+})(RetentionClassSweepFailureStage || (RetentionClassSweepFailureStage = {}));
+/**
+ * Why a bound resource was not swept at all this run. A skip is REPORTED, never silent: a sweep that
+ * quietly skips a resource is indistinguishable from one that found nothing expired.
+ */
+export var RetentionClassSweepSkipReason;
+(function (RetentionClassSweepSkipReason) {
+    /** The bound class has no declared period. Undecided is never "delete now" — the gap is reported instead. */
+    RetentionClassSweepSkipReason["CLASS_UNDECLARED"] = "class-undeclared";
+    /** A SCOPE_DELETED binding whose rows die in the tenant purge cascade: the purge enforces it. */
+    RetentionClassSweepSkipReason["ENFORCED_BY_TENANT_PURGE"] = "enforced-by-tenant-purge";
+})(RetentionClassSweepSkipReason || (RetentionClassSweepSkipReason = {}));
+export const RetentionEnforcementRecordSchema = z.object({
+    /** Document id. `.isPrimaryKey()` is what makes the PostgreSQL planner emit the PRIMARY KEY constraint. */
+    _id: z.string().isPrimaryKey().isSummaryField(),
+    /**
+     * The application RECORD id, the APPLICATION scope's key, stamped from the canonical identity. Optional because
+     * the routed APPLICATION edge is OPTIONAL (the Mongo convertor requires the column's requiredness to match the
+     * edge), and because a run whose identity cannot be resolved still writes its evidence, without it.
+     */
+    applicationId: z.string().isDBIndexed().optional(),
+    /**
+     * The sweep run — one ATTEMPT — this row belongs to: `<jobId>/<attempt id>` when the queue ran it (the prefix is
+     * the `JobExecution` key; retries share it, so the attempt keeps them apart), otherwise an id the sweep minted.
+     * Every row of one attempt carries the same value, so a run's rows group.
+     */
+    runRef: z.string().min(1).isDBIndexed().isSummaryField(),
+    /** The instant the run computed its cutoffs from. The window the evidence door filters on. */
+    sweptAt: z.date().isDBIndexed().isSummaryField(),
+    retentionClass: z.enum(DataRetentionClass).systemEnum('DataRetentionClass').isDBIndexed().isSummaryField(),
+    /** The bound resource this row describes. A resource TYPE, never a row. */
+    resourceType: z.string().min(1).isDBIndexed().isSummaryField(),
+    startPoint: z.enum(RetentionStartPoint).systemEnum('RetentionStartPoint'),
+    /**
+     * The period read from the schedule for THIS run. Stored because a schedule change must be visible in
+     * the evidence: the same resource swept under 365 days and then under 30 leaves two rows that say so.
+     * Absent on a `SKIPPED` row whose class had no declared period.
+     */
+    retentionDaysApplied: z.number().int().min(0).optional(),
+    /** Rows whose retention start was strictly before this instant were due for deletion. Absent on a skip. */
+    cutoff: z.date().optional(),
+    deletedCount: z.number().int().min(0),
+    /** The retention start of the earliest and latest row deleted: the window actually deleted, not the one due. */
+    oldestDeletedStartedAt: z.date().optional(),
+    newestDeletedStartedAt: z.date().optional(),
+    /**
+     * Rows past their period the sweep did NOT delete because a legal hold covers them (#1634). ABSENT means
+     * no hold check ran for this resource this run — "not measured", which is not the same as zero.
+     */
+    heldSkippedCount: z.number().int().min(0).optional(),
+    /**
+     * Rows retained under a statutory restriction (#1635) that are still inside their period — a count only.
+     * ABSENT means nothing measured it this run.
+     */
+    statutoryRestrictedCount: z.number().int().min(0).optional(),
+    reachedRunCeiling: z.boolean(),
+    outcome: z.enum(RetentionEnforcementOutcome).systemEnum('RetentionEnforcementOutcome').isDBIndexed().isSummaryField(),
+    failureStage: z.enum(RetentionClassSweepFailureStage).systemEnum('RetentionClassSweepFailureStage').optional(),
+    skipReason: z.enum(RetentionClassSweepSkipReason).systemEnum('RetentionClassSweepSkipReason').optional(),
+    createdAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),
+});
+/** @wildo_source:part:end saas.models.privacy.retention-enforcement-record */
+/**
+ * How often the retention-class sweep runs: hourly (`RETENTION_CLASS_SWEEP_CRON`, `15 * * * *`, in the backend's
+ * batch manifests). A COPY, because the manifest lives in the backend and the reader deciding whether a record
+ * is recent — the document-fact derivation — cannot import it; a backend test pins the two together.
+ */
+export const RETENTION_CLASS_SWEEP_INTERVAL_MS = 60 * 60 * 1000;
+/**
+ * The outcome a resource's run ended in. ONE rule, so the record, the audit event and the log cannot
+ * disagree about whether a run failed: a failure stage wins over everything, then a skip, then the ceiling.
+ */
+export function retentionEnforcementOutcomeOf(source) {
+    if (source.failureStage !== undefined)
+        return RetentionEnforcementOutcome.FAILED;
+    if (source.skipReason !== undefined)
+        return RetentionEnforcementOutcome.SKIPPED;
+    if (source.reachedRunCeiling)
+        return RetentionEnforcementOutcome.DEFERRED_BY_CEILING;
+    return RetentionEnforcementOutcome.COMPLETED;
+}
+/**
+ * The ONLY way a retention-enforcement record is built: a closed projection of one resource's sweep outcome.
+ *
+ * Closed on purpose. It names every field it copies, so a row id or a field value added to the sweep's
+ * outcome later cannot reach the table by accident (see the file header).
+ */
+export function projectRetentionEnforcementRecord(source, run) {
+    return {
+        ...(run.applicationId !== undefined ? { applicationId: run.applicationId } : {}),
+        runRef: run.runRef,
+        sweptAt: run.sweptAt,
+        retentionClass: source.retentionClass,
+        resourceType: source.resourceType,
+        startPoint: source.startPoint,
+        ...(source.retentionDaysApplied !== undefined ? { retentionDaysApplied: source.retentionDaysApplied } : {}),
+        ...(source.cutoff !== undefined ? { cutoff: source.cutoff } : {}),
+        deletedCount: source.deletedCount,
+        ...(source.oldestDeletedStartedAt !== undefined ? { oldestDeletedStartedAt: source.oldestDeletedStartedAt } : {}),
+        ...(source.newestDeletedStartedAt !== undefined ? { newestDeletedStartedAt: source.newestDeletedStartedAt } : {}),
+        ...(source.heldSkippedCount !== undefined ? { heldSkippedCount: source.heldSkippedCount } : {}),
+        ...(source.statutoryRestrictedCount !== undefined ? { statutoryRestrictedCount: source.statutoryRestrictedCount } : {}),
+        reachedRunCeiling: source.reachedRunCeiling,
+        outcome: retentionEnforcementOutcomeOf(source),
+        ...(source.failureStage !== undefined ? { failureStage: source.failureStage } : {}),
+        ...(source.skipReason !== undefined ? { skipReason: source.skipReason } : {}),
+    };
+}
+/**
+ * # Retention enforcement, answered to an evidence reader
+ *
+ * assurance-control: WILDO.PRIVACY.STORAGE_LIMITATION — whether each declared period was enforced is
+ * answerable for any window.
+ *
+ * What `GET /assurance/retention-enforcement-evidence` returns: the enforcement records whose run fell in a
+ * closed window. The records ARE counts and instants (see the file header), so handing them over names no
+ * person and no deleted row; the door drops only the storage ids.
+ */
+export const RetentionEnforcementEvidenceRecordSchema = RetentionEnforcementRecordSchema.omit({ _id: true, applicationId: true, createdAt: true });
+export const RetentionEnforcementEvidenceSchema = z.object({
+    window: z.object({ from: z.string(), to: z.string() }),
+    /** Every record whose `sweptAt` falls in the window, oldest first. */
+    records: z.array(RetentionEnforcementEvidenceRecordSchema),
+    /** How many distinct sweep runs those records come from. */
+    runCount: z.number().int().min(0),
+});
+const RETENTION_ENFORCEMENT_RECORD_INSTANT_FIELDS = ['sweptAt', 'cutoff', 'oldestDeletedStartedAt', 'newestDeletedStartedAt'];
+/**
+ * Read an evidence answer that crossed a JSON boundary — the door's response, or the copy the assurance
+ * collector committed — back into {@link RetentionEnforcementEvidence}. ONE place revives the instants, which
+ * JSON carries as strings, so every reader of a committed answer reads it alike. `undefined` when the value is
+ * not an evidence answer: a reader treats that as "no evidence", never as "nothing enforced".
+ */
+export function parseRetentionEnforcementEvidenceJson(value) {
+    if (!value || typeof value !== 'object' || !Array.isArray(value.records))
+        return undefined;
+    const records = (value.records).map((record) => {
+        if (!record || typeof record !== 'object')
+            return record;
+        const revived = { ...record };
+        for (const field of RETENTION_ENFORCEMENT_RECORD_INSTANT_FIELDS) {
+            if (typeof revived[field] === 'string')
+                revived[field] = new Date(revived[field]);
+        }
+        return revived;
+    });
+    const parsed = RetentionEnforcementEvidenceSchema.safeParse({ ...value, records });
+    return parsed.success ? parsed.data : undefined;
+}
+//# sourceMappingURL=retention-enforcement-records.shared.schemas.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retention-enforcement-records.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/compliance/privacy/retention-enforcement-records.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * One row per (retention-class sweep run × class-bound resource): what the run deleted for that resource,\n * under which declared period, what it held back, and how it ended (#1636).\n *\n * ## Why a store, when the sweep already returns its outcome\n *\n * GDPR Art. 5(1)(e) (storage limitation) is a principle the operator must be able to DEMONSTRATE\n * (Art. 5(2), accountability). The sweep's run output is transient: a successful run's result is kept only\n * as long as the job execution that carried it, and a failed run survives only as an invocation status. So\n * after #1613 the engine deleted by period and nothing durable said that it had. This row is that record,\n * and it is the first producer of `AssuranceDocumentFactAuthorityKind.RUNTIME_EVIDENCE`: a privacy notice\n * says a class's retention is ENFORCED only when these rows show it.\n *\n * ## Counts and instants only, by construction\n *\n * The evidence must outlive the rows it describes WITHOUT re-creating them. So no field names a deleted\n * row, and none carries a field value: {@link projectRetentionEnforcementRecord} is the only producer and\n * copies a closed list of counts, instants and vocabulary members. A row id or a value added here would\n * turn deletion evidence into a copy of what was deleted — the key set is pinned by a test for that reason.\n *\n * ## Every run, including a failed one\n *\n * The sweep writes one row per bound resource per run in a `finally`, so a run that fails still leaves a\n * `FAILED` row: a failed run is evidence too, and an operator whose sweep stopped working must be able to\n * see WHEN it stopped. A resource the sweep skipped leaves a `SKIPPED` row naming why, because a skip that\n * leaves nothing is indistinguishable from a sweep that never ran.\n *\n * ## Retention of the evidence itself\n *\n * Bound to `AUDIT_LOGS` from `CREATED` (see the resource configuration): this is the operator's defence\n * evidence, so it is kept as long as the audit trail and outlives the data it describes.\n *\n * assurance-control: WILDO.PRIVACY.STORAGE_LIMITATION — records evidence that declared retention was enforced.\n */\nimport { z } from 'zod';\n\nimport { DataRetentionClass, RetentionStartPoint } from './retention-schedule.shared.schemas';\n\n/** @wildo_source:part:start saas.models.privacy.retention-enforcement-record facet:layer:shared facet:audience:app-developer */\n/**\n * How one sweep run ended for one class-bound resource. The three non-skip members are the three outcomes\n * the sweep distinguishes; `SKIPPED` is a resource the sweep deliberately did not work on this run.\n */\nexport enum RetentionEnforcementOutcome {\n  /** Every row past its period that the sweep listed was deleted; nothing was left for the next run. */\n  COMPLETED = 'COMPLETED',\n  /**\n   * The run stopped at its per-run ceiling with expired rows still waiting, which the next run resumes.\n   * Normal operation after a period is shortened or a backlog builds up, and NOT a failure: the period is\n   * being enforced, bounded per run so a mistake cannot become one unbounded delete.\n   */\n  DEFERRED_BY_CEILING = 'DEFERRED_BY_CEILING',\n  /** Listing or deleting failed, or the delete removed nothing. Retention was NOT enforced for this resource this run. */\n  FAILED = 'FAILED',\n  /** The sweep did not work on this resource this run; `skipReason` says why. Neither enforcement nor failure. */\n  SKIPPED = 'SKIPPED',\n}\n\n/** Which step of a resource's sweep failed. Named so the log, the thrown message and the record say the same thing. */\nexport enum RetentionClassSweepFailureStage {\n  /** Listing expired rows failed, so nothing more was deleted for that resource this run. */\n  READ = 'read',\n  /** A service-layer delete failed; earlier rows of the same resource may already be deleted. */\n  DELETE = 'delete',\n  /** The same rows were listed again after being deleted — the delete removed nothing, so the sweep stopped rather than loop. */\n  NO_PROGRESS = 'no-progress',\n  /**\n   * The active legal holds could not be read (#1634), so whether the listed rows are held is unknown. The\n   * sweep deletes nothing more for that resource this run — a read error never means \"not held\".\n   */\n  LEGAL_HOLD_UNVERIFIABLE = 'legal-hold-unverifiable',\n  /**\n   * The resource's sweep THREW instead of returning an outcome (every expected failure is caught and reported as\n   * one of the stages above). Deletions it made before throwing are not counted, so read `deletedCount: 0` on\n   * this stage as \"unknown\", not as \"none\".\n   */\n  UNEXPECTED = 'unexpected',\n}\n\n/**\n * Why a bound resource was not swept at all this run. A skip is REPORTED, never silent: a sweep that\n * quietly skips a resource is indistinguishable from one that found nothing expired.\n */\nexport enum RetentionClassSweepSkipReason {\n  /** The bound class has no declared period. Undecided is never \"delete now\" — the gap is reported instead. */\n  CLASS_UNDECLARED = 'class-undeclared',\n  /** A SCOPE_DELETED binding whose rows die in the tenant purge cascade: the purge enforces it. */\n  ENFORCED_BY_TENANT_PURGE = 'enforced-by-tenant-purge',\n}\n\nexport const RetentionEnforcementRecordSchema = z.object({\n  /** Document id. `.isPrimaryKey()` is what makes the PostgreSQL planner emit the PRIMARY KEY constraint. */\n  _id: z.string().isPrimaryKey().isSummaryField(),\n\n  /**\n   * The application RECORD id, the APPLICATION scope's key, stamped from the canonical identity. Optional because\n   * the routed APPLICATION edge is OPTIONAL (the Mongo convertor requires the column's requiredness to match the\n   * edge), and because a run whose identity cannot be resolved still writes its evidence, without it.\n   */\n  applicationId: z.string().isDBIndexed().optional(),\n\n  /**\n   * The sweep run — one ATTEMPT — this row belongs to: `<jobId>/<attempt id>` when the queue ran it (the prefix is\n   * the `JobExecution` key; retries share it, so the attempt keeps them apart), otherwise an id the sweep minted.\n   * Every row of one attempt carries the same value, so a run's rows group.\n   */\n  runRef: z.string().min(1).isDBIndexed().isSummaryField(),\n  /** The instant the run computed its cutoffs from. The window the evidence door filters on. */\n  sweptAt: z.date().isDBIndexed().isSummaryField(),\n\n  retentionClass: z.enum(DataRetentionClass).systemEnum('DataRetentionClass').isDBIndexed().isSummaryField(),\n  /** The bound resource this row describes. A resource TYPE, never a row. */\n  resourceType: z.string().min(1).isDBIndexed().isSummaryField(),\n  startPoint: z.enum(RetentionStartPoint).systemEnum('RetentionStartPoint'),\n\n  /**\n   * The period read from the schedule for THIS run. Stored because a schedule change must be visible in\n   * the evidence: the same resource swept under 365 days and then under 30 leaves two rows that say so.\n   * Absent on a `SKIPPED` row whose class had no declared period.\n   */\n  retentionDaysApplied: z.number().int().min(0).optional(),\n  /** Rows whose retention start was strictly before this instant were due for deletion. Absent on a skip. */\n  cutoff: z.date().optional(),\n\n  deletedCount: z.number().int().min(0),\n  /** The retention start of the earliest and latest row deleted: the window actually deleted, not the one due. */\n  oldestDeletedStartedAt: z.date().optional(),\n  newestDeletedStartedAt: z.date().optional(),\n  /**\n   * Rows past their period the sweep did NOT delete because a legal hold covers them (#1634). ABSENT means\n   * no hold check ran for this resource this run — \"not measured\", which is not the same as zero.\n   */\n  heldSkippedCount: z.number().int().min(0).optional(),\n  /**\n   * Rows retained under a statutory restriction (#1635) that are still inside their period — a count only.\n   * ABSENT means nothing measured it this run.\n   */\n  statutoryRestrictedCount: z.number().int().min(0).optional(),\n  reachedRunCeiling: z.boolean(),\n\n  outcome: z.enum(RetentionEnforcementOutcome).systemEnum('RetentionEnforcementOutcome').isDBIndexed().isSummaryField(),\n  failureStage: z.enum(RetentionClassSweepFailureStage).systemEnum('RetentionClassSweepFailureStage').optional(),\n  skipReason: z.enum(RetentionClassSweepSkipReason).systemEnum('RetentionClassSweepSkipReason').optional(),\n\n  createdAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n});\nexport type RetentionEnforcementRecord = z.infer<typeof RetentionEnforcementRecordSchema>;\n/** @wildo_source:part:end saas.models.privacy.retention-enforcement-record */\n\n/**\n * How often the retention-class sweep runs: hourly (`RETENTION_CLASS_SWEEP_CRON`, `15 * * * *`, in the backend's\n * batch manifests). A COPY, because the manifest lives in the backend and the reader deciding whether a record\n * is recent — the document-fact derivation — cannot import it; a backend test pins the two together.\n */\nexport const RETENTION_CLASS_SWEEP_INTERVAL_MS = 60 * 60 * 1000;\n\n/** What the sweep knows about one bound resource at the end of a run — the input {@link projectRetentionEnforcementRecord} reads. */\nexport interface RetentionEnforcementRecordSource {\n  readonly resourceType: string;\n  readonly retentionClass: DataRetentionClass;\n  readonly startPoint: RetentionStartPoint;\n  readonly retentionDaysApplied?: number;\n  readonly cutoff?: Date;\n  readonly deletedCount: number;\n  readonly oldestDeletedStartedAt?: Date;\n  readonly newestDeletedStartedAt?: Date;\n  readonly heldSkippedCount?: number;\n  readonly statutoryRestrictedCount?: number;\n  readonly reachedRunCeiling: boolean;\n  readonly failureStage?: RetentionClassSweepFailureStage;\n  readonly skipReason?: RetentionClassSweepSkipReason;\n}\n\n/**\n * The outcome a resource's run ended in. ONE rule, so the record, the audit event and the log cannot\n * disagree about whether a run failed: a failure stage wins over everything, then a skip, then the ceiling.\n */\nexport function retentionEnforcementOutcomeOf(source: Pick<RetentionEnforcementRecordSource, 'failureStage' | 'skipReason' | 'reachedRunCeiling'>): RetentionEnforcementOutcome {\n  if (source.failureStage !== undefined) return RetentionEnforcementOutcome.FAILED;\n  if (source.skipReason !== undefined) return RetentionEnforcementOutcome.SKIPPED;\n  if (source.reachedRunCeiling) return RetentionEnforcementOutcome.DEFERRED_BY_CEILING;\n  return RetentionEnforcementOutcome.COMPLETED;\n}\n\n/**\n * The ONLY way a retention-enforcement record is built: a closed projection of one resource's sweep outcome.\n *\n * Closed on purpose. It names every field it copies, so a row id or a field value added to the sweep's\n * outcome later cannot reach the table by accident (see the file header).\n */\nexport function projectRetentionEnforcementRecord(\n  source: RetentionEnforcementRecordSource,\n  run: { readonly applicationId?: string; readonly runRef: string; readonly sweptAt: Date },\n): Omit<RetentionEnforcementRecord, '_id' | 'createdAt'> {\n  return {\n    ...(run.applicationId !== undefined ? { applicationId: run.applicationId } : {}),\n    runRef: run.runRef,\n    sweptAt: run.sweptAt,\n    retentionClass: source.retentionClass,\n    resourceType: source.resourceType,\n    startPoint: source.startPoint,\n    ...(source.retentionDaysApplied !== undefined ? { retentionDaysApplied: source.retentionDaysApplied } : {}),\n    ...(source.cutoff !== undefined ? { cutoff: source.cutoff } : {}),\n    deletedCount: source.deletedCount,\n    ...(source.oldestDeletedStartedAt !== undefined ? { oldestDeletedStartedAt: source.oldestDeletedStartedAt } : {}),\n    ...(source.newestDeletedStartedAt !== undefined ? { newestDeletedStartedAt: source.newestDeletedStartedAt } : {}),\n    ...(source.heldSkippedCount !== undefined ? { heldSkippedCount: source.heldSkippedCount } : {}),\n    ...(source.statutoryRestrictedCount !== undefined ? { statutoryRestrictedCount: source.statutoryRestrictedCount } : {}),\n    reachedRunCeiling: source.reachedRunCeiling,\n    outcome: retentionEnforcementOutcomeOf(source),\n    ...(source.failureStage !== undefined ? { failureStage: source.failureStage } : {}),\n    ...(source.skipReason !== undefined ? { skipReason: source.skipReason } : {}),\n  };\n}\n\n/**\n * # Retention enforcement, answered to an evidence reader\n *\n * assurance-control: WILDO.PRIVACY.STORAGE_LIMITATION — whether each declared period was enforced is\n * answerable for any window.\n *\n * What `GET /assurance/retention-enforcement-evidence` returns: the enforcement records whose run fell in a\n * closed window. The records ARE counts and instants (see the file header), so handing them over names no\n * person and no deleted row; the door drops only the storage ids.\n */\nexport const RetentionEnforcementEvidenceRecordSchema = RetentionEnforcementRecordSchema.omit({ _id: true, applicationId: true, createdAt: true });\nexport type RetentionEnforcementEvidenceRecord = z.infer<typeof RetentionEnforcementEvidenceRecordSchema>;\n\nexport const RetentionEnforcementEvidenceSchema = z.object({\n  window: z.object({ from: z.string(), to: z.string() }),\n  /** Every record whose `sweptAt` falls in the window, oldest first. */\n  records: z.array(RetentionEnforcementEvidenceRecordSchema),\n  /** How many distinct sweep runs those records come from. */\n  runCount: z.number().int().min(0),\n});\nexport type RetentionEnforcementEvidence = z.infer<typeof RetentionEnforcementEvidenceSchema>;\n\nconst RETENTION_ENFORCEMENT_RECORD_INSTANT_FIELDS = ['sweptAt', 'cutoff', 'oldestDeletedStartedAt', 'newestDeletedStartedAt'] as const;\n\n/**\n * Read an evidence answer that crossed a JSON boundary — the door's response, or the copy the assurance\n * collector committed — back into {@link RetentionEnforcementEvidence}. ONE place revives the instants, which\n * JSON carries as strings, so every reader of a committed answer reads it alike. `undefined` when the value is\n * not an evidence answer: a reader treats that as \"no evidence\", never as \"nothing enforced\".\n */\nexport function parseRetentionEnforcementEvidenceJson(value: unknown): RetentionEnforcementEvidence | undefined {\n  if (!value || typeof value !== 'object' || !Array.isArray((value as { records?: unknown }).records)) return undefined;\n  const records = ((value as { records: unknown[] }).records).map((record) => {\n    if (!record || typeof record !== 'object') return record;\n    const revived: Record<string, unknown> = { ...(record as Record<string, unknown>) };\n    for (const field of RETENTION_ENFORCEMENT_RECORD_INSTANT_FIELDS) {\n      if (typeof revived[field] === 'string') revived[field] = new Date(revived[field] as string);\n    }\n    return revived;\n  });\n  const parsed = RetentionEnforcementEvidenceSchema.safeParse({ ...(value as Record<string, unknown>), records });\n  return parsed.success ? parsed.data : undefined;\n}\n"]}

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

@@ -1,8 +1,9 @@
 import { z } from "zod";
+/** @wildo_source:part:start saas.models.privacy.retention-schedule facet:layer:shared facet:audience:app-developer */
 /**
- * **The four data classes an application declares a retention period for.**
+ * **The data classes an application declares a retention period for.**
  *
- * ## Why four, and not one per resource
+ * ## Why a handful of classes, and not one period 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
@@ -27,9 +28,20 @@ import { z } from "zod";
  * | {@link FILES} | MinIO / S3 |
  * | {@link AUDIT_LOGS} | immudb — the tamper-evident ledger |
  * | {@link OPERATIONAL_LOGS} | the logging pipeline |
+ * | {@link BUSINESS_RECORDS} | MongoDB / PostgreSQL — the one class split by LAW rather than by store |
  *
  * 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.
+ * operator must decide and defend, and an undecided period is worse than a coarse one. The criterion
+ * for a new member is that its records differ in law, in storage or in who asks for them —
+ * {@link BUSINESS_RECORDS} is the first split made on the law alone (#1613).
+ *
+ * ## How a row is bound to a class
+ *
+ * A resource declares `retentionBinding: { retentionClass, startPoint }` in its resource
+ * configuration ({@link ResourceRetentionBindingSchema}). An engine sweep then deletes a bound row
+ * once `retentionDays` of its class have passed since the row's {@link RetentionStartPoint}. A
+ * resource with no binding is kept until it is erased, and is reported by
+ * `unboundRetentionResources` so the gap stays visible.
  */
 export declare enum DataRetentionClass {
     /**
@@ -51,8 +63,119 @@ export declare enum 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. */
-    OPERATIONAL_LOGS = "OPERATIONAL_LOGS"
+    OPERATIONAL_LOGS = "OPERATIONAL_LOGS",
+    /**
+     * Records whose MINIMUM retention is set by law: business correspondence, accounting documents and
+     * their supporting pieces.
+     *
+     * A separate class because its members differ in law from {@link RESOURCE_DATA}: the period is a
+     * statutory floor, not the operator's choice, and it usually outlives the customer relationship.
+     * Germany's HGB §257 and AO §147 require 6 years for business letters and 8 for booking vouchers,
+     * counted from the end of the calendar year; France's Code de commerce L123-22 requires 10 years
+     * for accounting documents; UK law-firm practice follows the 15-year long-stop of the Limitation
+     * Act 1980 s.14B. Folding these into {@link RESOURCE_DATA} would force one of two wrong answers:
+     * delete statutory records with the customer data, or keep all customer data for a decade.
+     *
+     * Carries NO default period, like every class: the number depends on the jurisdiction and the
+     * record, and a defaulted statutory period is a legal statement nobody made. A resource that binds
+     * it usually counts from {@link RetentionStartPoint.END_OF_CALENDAR_YEAR}. What an erasure does to a
+     * row still inside its period is the subject-erasure lane's (#1635), not this class's.
+     */
+    BUSINESS_RECORDS = "BUSINESS_RECORDS"
 }
+/** @wildo_source:part:end saas.models.privacy.retention-schedule */
+/** @wildo_source:part:start saas.models.privacy.retention-binding facet:layer:shared facet:audience:app-developer */
+/**
+ * **When a bound row's retention clock starts.**
+ *
+ * A schedule period is counted "from the point the application stops needing it for the purpose it
+ * was collected for" ({@link DataRetentionPeriodSchema}), so binding a live record to a class
+ * counted from its CREATION would delete it while it is still in use. Every binding therefore names
+ * its start point explicitly: there is no default, because every candidate default deletes somebody's
+ * live data for some resource (#1613 review F1).
+ *
+ * ## The instant is READ from what the framework already records — not stamped a second time
+ *
+ * Four of the five members read an instant the row already carries, so the retention clock is the
+ * same value every other surface shows, and no write path has to remember to maintain a copy:
+ *
+ * | member | the clock starts at | read from |
+ * |---|---|---|
+ * | {@link CREATED} | the insert | `createdAt` — infrastructure-owned on both adapters |
+ * | {@link LAST_UPDATED} | the most recent update | `updatedAt` — infrastructure-owned on both adapters |
+ * | {@link CLOSURE_EVENT} | the moment the declared closure date field is set | that field; null never expires |
+ * | {@link END_OF_CALENDAR_YEAR} | 31 December 23:59:59.999 UTC of the creation year | `createdAt` |
+ * | {@link SCOPE_DELETED} | the row's organization was marked for deletion | `retentionStartedAt`, stamped by the tenant purge |
+ *
+ * Rejected: persisting a `retentionStartedAt` on EVERY bound row. `createdAt` and `updatedAt` are
+ * already maintained by the persistence adapter on every write path (the Mongoose timestamps plugin;
+ * the PostgreSQL repository's timestamp stamping), and a second copy would have to be written at
+ * each of those paths too — the one-invariant-many-sites shape that has shipped half-applied
+ * repeatedly in this repository. Only {@link SCOPE_DELETED} has no instant on the row, so only it
+ * stores one.
+ *
+ * The EXPIRY is never stored, for any member: the sweep computes `start + retentionDays` from the
+ * CURRENT schedule at every run, so changing a period needs no backfill.
+ */
+export declare enum RetentionStartPoint {
+    /** At insert. For records whose purpose ends with their creation: a log line, a delivery attempt. */
+    CREATED = "CREATED",
+    /** At every update. For state kept only while it is still being touched: a draft, a session record. */
+    LAST_UPDATED = "LAST_UPDATED",
+    /**
+     * When the resource's declared `closureFieldName` date field is set — a ticket closed, a contract
+     * ended, a case archived. While that field is null the row never expires, which is what makes this
+     * the member for "kept while it is open, then N days".
+     */
+    CLOSURE_EVENT = "CLOSURE_EVENT",
+    /**
+     * 31 December 23:59:59.999 UTC of the year the row was created — how HGB §257(5) and AO §147(4)
+     * count commercial and tax retention.
+     */
+    END_OF_CALENDAR_YEAR = "END_OF_CALENDAR_YEAR",
+    /**
+     * When the row's organization is marked for deletion — "kept while the account exists, then N days".
+     *
+     * Two cases, decided at startup by the resource's `organizations → <resource>` teardown edge:
+     * - the edge DELETES the row in the tenant purge: the purge IS the enforcement, at
+     *   `tenantTeardown.retentionWindowDays`, which is single-sourced to {@link DataRetentionClass.RESOURCE_DATA}
+     *   — so only that class may be bound this way;
+     * - the row OUTLIVES its tenant (the edge is disabled, retains-and-impersonalizes, or is absent):
+     *   the purge stamps `retentionStartedAt` with the organization's `deletionRequestedAt`, and the
+     *   retention sweep deletes the row after its own class period.
+     */
+    SCOPE_DELETED = "SCOPE_DELETED"
+}
+/** The one field the framework stores for a retention clock: the {@link RetentionStartPoint.SCOPE_DELETED} instant. */
+export declare const RETENTION_STARTED_AT_FIELD_NAME = "retentionStartedAt";
+/**
+ * A resource's binding to a {@link DataRetentionClass}, declared as `retentionBinding` in its
+ * resource configuration.
+ *
+ * ⚠️ NOT `retentionPolicy`. That is the erasure TREATMENT (what an erasure does to a row: delete, or
+ * retain and scrub); this is the retention PERIOD (how long a row is kept at all). A resource may
+ * declare either, both or neither, and they answer different questions for different readers.
+ *
+ * Strict, so a misspelled key fails at configuration build instead of being ignored — an ignored
+ * binding would be a retention period the application states and nothing enforces.
+ */
+export declare const ResourceRetentionBindingSchema: z.ZodObject<{
+    /** The class whose declared period applies. The period itself lives in the application's `dataRetention` schedule, never here. */
+    retentionClass: z.ZodEnum<typeof DataRetentionClass>;
+    /** When the clock starts. Required, with no default — see {@link RetentionStartPoint}. */
+    startPoint: z.ZodEnum<typeof RetentionStartPoint>;
+    /**
+     * The date field whose value is the closure instant. Required for, and only allowed with,
+     * {@link RetentionStartPoint.CLOSURE_EVENT}; the resource factory refuses a field that is not a
+     * date, is not database-indexed (the sweep queries it on every run), or can be written by a
+     * client-routed create or update (a caller could backdate it into a delete). Make it server-owned:
+     * excluded from create and update, set by the owning handlers, declared in their `authoritativeFields`.
+     */
+    closureFieldName: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ResourceRetentionBinding = z.infer<typeof ResourceRetentionBindingSchema>;
+/** @wildo_source:part:end saas.models.privacy.retention-binding */
+/** @wildo_source:part:start saas.models.privacy.retention-schedule */
 /**
  * One declared retention period.
  *
@@ -91,7 +214,7 @@ export type DataRetentionPeriod = z.infer<typeof DataRetentionPeriodSchema>;
  *
  * 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
+ * alternative — requiring every class — 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 declare const ApplicationRetentionScheduleSchema: z.ZodRecord<z.ZodEnum<typeof DataRetentionClass> & z.core.$partial, z.ZodObject<{
@@ -114,6 +237,7 @@ export declare const ApplicationRetentionScheduleSchema: z.ZodRecord<z.ZodEnum<t
     rationale: z.ZodString;
 }, z.core.$strict>>;
 export type ApplicationRetentionSchedule = z.infer<typeof ApplicationRetentionScheduleSchema>;
+/** @wildo_source:part:end saas.models.privacy.retention-schedule */
 /**
  * The classes an application has NOT declared a period for — what a document must mark as owed.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"retention-schedule.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/compliance/privacy/retention-schedule.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,oBAAY,kBAAkB;IAC5B;;;;;OAKG;IACH,aAAa,kBAAkB;IAC/B,kMAAkM;IAClM,KAAK,UAAU;IACf;;;;;;;OAOG;IACH,UAAU,eAAe;IACzB,kNAAkN;IAClN,gBAAgB,qBAAqB;CACtC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB;IACpC;;;;;;;OAOG;;IAEH;;;;;;OAMG;;kBAEH,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kCAAkC;IAlC7C;;;;;;;OAOG;;IAEH;;;;;;OAMG;;mBAsBJ,CAAC;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAE9F;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,4BAA4B,GAAG,SAAS,GACjD,SAAS,kBAAkB,EAAE,CAE/B"}
+{"version":3,"file":"retention-schedule.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/compliance/privacy/retention-schedule.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,sHAAsH;AACtH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,oBAAY,kBAAkB;IAC5B;;;;;OAKG;IACH,aAAa,kBAAkB;IAC/B,kMAAkM;IAClM,KAAK,UAAU;IACf;;;;;;;OAOG;IACH,UAAU,eAAe;IACzB,kNAAkN;IAClN,gBAAgB,qBAAqB;IACrC;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,qBAAqB;CACtC;AACD,oEAAoE;AAEpE,qHAAqH;AACrH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,oBAAY,mBAAmB;IAC7B,qGAAqG;IACrG,OAAO,YAAY;IACnB,uGAAuG;IACvG,YAAY,iBAAiB;IAC7B;;;;OAIG;IACH,aAAa,kBAAkB;IAC/B;;;OAGG;IACH,oBAAoB,yBAAyB;IAC7C;;;;;;;;;;OAUG;IACH,aAAa,kBAAkB;CAChC;AAED,uHAAuH;AACvH,eAAO,MAAM,+BAA+B,uBAAuB,CAAC;AAEpE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,8BAA8B;IACzC,kIAAkI;;IAElI,0FAA0F;;IAE1F;;;;;;OAMG;;kBAEH,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AACtF,mEAAmE;AAEnE,sEAAsE;AACtE;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB;IACpC;;;;;;;OAOG;;IAEH;;;;;;OAMG;;kBAEH,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kCAAkC;IAlC7C;;;;;;;OAOG;;IAEH;;;;;;OAMG;;mBAsBJ,CAAC;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAC9F,oEAAoE;AAEpE;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,4BAA4B,GAAG,SAAS,GACjD,SAAS,kBAAkB,EAAE,CAE/B"}

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

@@ -1,8 +1,9 @@
 import { z } from "zod";
+/** @wildo_source:part:start saas.models.privacy.retention-schedule facet:layer:shared facet:audience:app-developer */
 /**
- * **The four data classes an application declares a retention period for.**
+ * **The data classes an application declares a retention period for.**
  *
- * ## Why four, and not one per resource
+ * ## Why a handful of classes, and not one period 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
@@ -27,9 +28,20 @@ import { z } from "zod";
  * | {@link FILES} | MinIO / S3 |
  * | {@link AUDIT_LOGS} | immudb — the tamper-evident ledger |
  * | {@link OPERATIONAL_LOGS} | the logging pipeline |
+ * | {@link BUSINESS_RECORDS} | MongoDB / PostgreSQL — the one class split by LAW rather than by store |
  *
  * 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.
+ * operator must decide and defend, and an undecided period is worse than a coarse one. The criterion
+ * for a new member is that its records differ in law, in storage or in who asks for them —
+ * {@link BUSINESS_RECORDS} is the first split made on the law alone (#1613).
+ *
+ * ## How a row is bound to a class
+ *
+ * A resource declares `retentionBinding: { retentionClass, startPoint }` in its resource
+ * configuration ({@link ResourceRetentionBindingSchema}). An engine sweep then deletes a bound row
+ * once `retentionDays` of its class have passed since the row's {@link RetentionStartPoint}. A
+ * resource with no binding is kept until it is erased, and is reported by
+ * `unboundRetentionResources` so the gap stays visible.
  */
 export var DataRetentionClass;
 (function (DataRetentionClass) {
@@ -53,7 +65,118 @@ export var DataRetentionClass;
     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";
+    /**
+     * Records whose MINIMUM retention is set by law: business correspondence, accounting documents and
+     * their supporting pieces.
+     *
+     * A separate class because its members differ in law from {@link RESOURCE_DATA}: the period is a
+     * statutory floor, not the operator's choice, and it usually outlives the customer relationship.
+     * Germany's HGB §257 and AO §147 require 6 years for business letters and 8 for booking vouchers,
+     * counted from the end of the calendar year; France's Code de commerce L123-22 requires 10 years
+     * for accounting documents; UK law-firm practice follows the 15-year long-stop of the Limitation
+     * Act 1980 s.14B. Folding these into {@link RESOURCE_DATA} would force one of two wrong answers:
+     * delete statutory records with the customer data, or keep all customer data for a decade.
+     *
+     * Carries NO default period, like every class: the number depends on the jurisdiction and the
+     * record, and a defaulted statutory period is a legal statement nobody made. A resource that binds
+     * it usually counts from {@link RetentionStartPoint.END_OF_CALENDAR_YEAR}. What an erasure does to a
+     * row still inside its period is the subject-erasure lane's (#1635), not this class's.
+     */
+    DataRetentionClass["BUSINESS_RECORDS"] = "BUSINESS_RECORDS";
 })(DataRetentionClass || (DataRetentionClass = {}));
+/** @wildo_source:part:end saas.models.privacy.retention-schedule */
+/** @wildo_source:part:start saas.models.privacy.retention-binding facet:layer:shared facet:audience:app-developer */
+/**
+ * **When a bound row's retention clock starts.**
+ *
+ * A schedule period is counted "from the point the application stops needing it for the purpose it
+ * was collected for" ({@link DataRetentionPeriodSchema}), so binding a live record to a class
+ * counted from its CREATION would delete it while it is still in use. Every binding therefore names
+ * its start point explicitly: there is no default, because every candidate default deletes somebody's
+ * live data for some resource (#1613 review F1).
+ *
+ * ## The instant is READ from what the framework already records — not stamped a second time
+ *
+ * Four of the five members read an instant the row already carries, so the retention clock is the
+ * same value every other surface shows, and no write path has to remember to maintain a copy:
+ *
+ * | member | the clock starts at | read from |
+ * |---|---|---|
+ * | {@link CREATED} | the insert | `createdAt` — infrastructure-owned on both adapters |
+ * | {@link LAST_UPDATED} | the most recent update | `updatedAt` — infrastructure-owned on both adapters |
+ * | {@link CLOSURE_EVENT} | the moment the declared closure date field is set | that field; null never expires |
+ * | {@link END_OF_CALENDAR_YEAR} | 31 December 23:59:59.999 UTC of the creation year | `createdAt` |
+ * | {@link SCOPE_DELETED} | the row's organization was marked for deletion | `retentionStartedAt`, stamped by the tenant purge |
+ *
+ * Rejected: persisting a `retentionStartedAt` on EVERY bound row. `createdAt` and `updatedAt` are
+ * already maintained by the persistence adapter on every write path (the Mongoose timestamps plugin;
+ * the PostgreSQL repository's timestamp stamping), and a second copy would have to be written at
+ * each of those paths too — the one-invariant-many-sites shape that has shipped half-applied
+ * repeatedly in this repository. Only {@link SCOPE_DELETED} has no instant on the row, so only it
+ * stores one.
+ *
+ * The EXPIRY is never stored, for any member: the sweep computes `start + retentionDays` from the
+ * CURRENT schedule at every run, so changing a period needs no backfill.
+ */
+export var RetentionStartPoint;
+(function (RetentionStartPoint) {
+    /** At insert. For records whose purpose ends with their creation: a log line, a delivery attempt. */
+    RetentionStartPoint["CREATED"] = "CREATED";
+    /** At every update. For state kept only while it is still being touched: a draft, a session record. */
+    RetentionStartPoint["LAST_UPDATED"] = "LAST_UPDATED";
+    /**
+     * When the resource's declared `closureFieldName` date field is set — a ticket closed, a contract
+     * ended, a case archived. While that field is null the row never expires, which is what makes this
+     * the member for "kept while it is open, then N days".
+     */
+    RetentionStartPoint["CLOSURE_EVENT"] = "CLOSURE_EVENT";
+    /**
+     * 31 December 23:59:59.999 UTC of the year the row was created — how HGB §257(5) and AO §147(4)
+     * count commercial and tax retention.
+     */
+    RetentionStartPoint["END_OF_CALENDAR_YEAR"] = "END_OF_CALENDAR_YEAR";
+    /**
+     * When the row's organization is marked for deletion — "kept while the account exists, then N days".
+     *
+     * Two cases, decided at startup by the resource's `organizations → <resource>` teardown edge:
+     * - the edge DELETES the row in the tenant purge: the purge IS the enforcement, at
+     *   `tenantTeardown.retentionWindowDays`, which is single-sourced to {@link DataRetentionClass.RESOURCE_DATA}
+     *   — so only that class may be bound this way;
+     * - the row OUTLIVES its tenant (the edge is disabled, retains-and-impersonalizes, or is absent):
+     *   the purge stamps `retentionStartedAt` with the organization's `deletionRequestedAt`, and the
+     *   retention sweep deletes the row after its own class period.
+     */
+    RetentionStartPoint["SCOPE_DELETED"] = "SCOPE_DELETED";
+})(RetentionStartPoint || (RetentionStartPoint = {}));
+/** The one field the framework stores for a retention clock: the {@link RetentionStartPoint.SCOPE_DELETED} instant. */
+export const RETENTION_STARTED_AT_FIELD_NAME = "retentionStartedAt";
+/**
+ * A resource's binding to a {@link DataRetentionClass}, declared as `retentionBinding` in its
+ * resource configuration.
+ *
+ * ⚠️ NOT `retentionPolicy`. That is the erasure TREATMENT (what an erasure does to a row: delete, or
+ * retain and scrub); this is the retention PERIOD (how long a row is kept at all). A resource may
+ * declare either, both or neither, and they answer different questions for different readers.
+ *
+ * Strict, so a misspelled key fails at configuration build instead of being ignored — an ignored
+ * binding would be a retention period the application states and nothing enforces.
+ */
+export const ResourceRetentionBindingSchema = z.strictObject({
+    /** The class whose declared period applies. The period itself lives in the application's `dataRetention` schedule, never here. */
+    retentionClass: z.enum(DataRetentionClass),
+    /** When the clock starts. Required, with no default — see {@link RetentionStartPoint}. */
+    startPoint: z.enum(RetentionStartPoint),
+    /**
+     * The date field whose value is the closure instant. Required for, and only allowed with,
+     * {@link RetentionStartPoint.CLOSURE_EVENT}; the resource factory refuses a field that is not a
+     * date, is not database-indexed (the sweep queries it on every run), or can be written by a
+     * client-routed create or update (a caller could backdate it into a delete). Make it server-owned:
+     * excluded from create and update, set by the owning handlers, declared in their `authoritativeFields`.
+     */
+    closureFieldName: z.string().trim().min(1).optional(),
+});
+/** @wildo_source:part:end saas.models.privacy.retention-binding */
+/** @wildo_source:part:start saas.models.privacy.retention-schedule */
 /**
  * One declared retention period.
  *
@@ -91,10 +214,11 @@ export const DataRetentionPeriodSchema = z.strictObject({
  *
  * 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
+ * alternative — requiring every class — 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);
+/** @wildo_source:part:end saas.models.privacy.retention-schedule */
 /**
  * The classes an application has NOT declared a period for — what a document must mark as owed.
  *