@nodii/dsar 0.20.0 → 0.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/dist/bind-pattern-a.d.ts +127 -13
  2. package/dist/bind-pattern-a.d.ts.map +1 -1
  3. package/dist/bind-pattern-a.js +553 -32
  4. package/dist/bind-pattern-a.js.map +1 -1
  5. package/dist/bind-pattern-b.d.ts.map +1 -1
  6. package/dist/bind-pattern-b.js +58 -3
  7. package/dist/bind-pattern-b.js.map +1 -1
  8. package/dist/grpc/dsar-service.d.ts +29 -0
  9. package/dist/grpc/dsar-service.d.ts.map +1 -1
  10. package/dist/grpc/dsar-service.js +34 -0
  11. package/dist/grpc/dsar-service.js.map +1 -1
  12. package/dist/grpc/proto-path.d.ts +33 -0
  13. package/dist/grpc/proto-path.d.ts.map +1 -0
  14. package/dist/grpc/proto-path.js +87 -0
  15. package/dist/grpc/proto-path.js.map +1 -0
  16. package/dist/hold-failure-mode.d.ts +24 -0
  17. package/dist/hold-failure-mode.d.ts.map +1 -1
  18. package/dist/hold-failure-mode.js +24 -0
  19. package/dist/hold-failure-mode.js.map +1 -1
  20. package/dist/hold-gate-probe.d.ts +61 -0
  21. package/dist/hold-gate-probe.d.ts.map +1 -0
  22. package/dist/hold-gate-probe.js +146 -0
  23. package/dist/hold-gate-probe.js.map +1 -0
  24. package/dist/holds.d.ts +60 -1
  25. package/dist/holds.d.ts.map +1 -1
  26. package/dist/holds.js +60 -3
  27. package/dist/holds.js.map +1 -1
  28. package/dist/index.d.ts +16 -6
  29. package/dist/index.d.ts.map +1 -1
  30. package/dist/index.js +28 -5
  31. package/dist/index.js.map +1 -1
  32. package/dist/migrations/index.d.ts.map +1 -1
  33. package/dist/migrations/index.js +10 -0
  34. package/dist/migrations/index.js.map +1 -1
  35. package/dist/orchestrator.d.ts +48 -0
  36. package/dist/orchestrator.d.ts.map +1 -1
  37. package/dist/orchestrator.js +297 -20
  38. package/dist/orchestrator.js.map +1 -1
  39. package/dist/register.d.ts +35 -1
  40. package/dist/register.d.ts.map +1 -1
  41. package/dist/register.js +26 -0
  42. package/dist/register.js.map +1 -1
  43. package/dist/retention-sweeper.d.ts +252 -0
  44. package/dist/retention-sweeper.d.ts.map +1 -0
  45. package/dist/retention-sweeper.js +356 -0
  46. package/dist/retention-sweeper.js.map +1 -0
  47. package/dist/retention.d.ts +109 -1
  48. package/dist/retention.d.ts.map +1 -1
  49. package/dist/retention.js +216 -3
  50. package/dist/retention.js.map +1 -1
  51. package/dist/subject-kinds.d.ts +74 -0
  52. package/dist/subject-kinds.d.ts.map +1 -0
  53. package/dist/subject-kinds.js +141 -0
  54. package/dist/subject-kinds.js.map +1 -0
  55. package/dist/types.d.ts +423 -7
  56. package/dist/types.d.ts.map +1 -1
  57. package/dist/types.js +164 -0
  58. package/dist/types.js.map +1 -1
  59. package/package.json +7 -4
  60. package/proto/nodii/dsar/v1/dsar.proto +202 -0
  61. package/src/migrations/001-lifecycle-requests.sql +422 -0
@@ -1,10 +1,30 @@
1
- import type { SubjectKindStr } from "./types.js";
1
+ import { type PiiBucket, type SubjectKindStr } from "./types.js";
2
2
  type SqlClient = {
3
3
  unsafe: (sql: string, args?: unknown[]) => Promise<any>;
4
4
  };
5
5
  export interface DataClassRegistration {
6
6
  dataClass: string;
7
7
  subjectKind: SubjectKindStr;
8
+ /**
9
+ * D720 — which of the three retention buckets this class belongs to.
10
+ * Defaults to `operational` (the pre-D720 behaviour: keyed to the person,
11
+ * destroyed by an Art. 17 erase).
12
+ *
13
+ * ONE DECLARATION, TWO CONSUMERS. The same array a service hands
14
+ * `registerWithOrchestrator` is the array it hands
15
+ * `bindPatternA({ retention: { dataClasses } })`, so the buckets the
16
+ * orchestrator knows about and the buckets the erase leg partitions on cannot
17
+ * drift apart.
18
+ */
19
+ bucket?: PiiBucket;
20
+ /**
21
+ * D720 — the statute that mandates retention of a `statutory` class (e.g.
22
+ * `"CGST Act 2017 s.36"`). Surfaced verbatim in the erase response's
23
+ * `retained_classes[].statute_citation`, i.e. read by a data subject and
24
+ * potentially by a regulator — so it carries a CITATION, never an internal
25
+ * ticket id or an explanation.
26
+ */
27
+ statuteCitation?: string;
8
28
  }
9
29
  export interface RegisterWithOrchestratorOpts {
10
30
  serviceName: string;
@@ -30,6 +50,20 @@ export interface RegisterWithOrchestratorResult {
30
50
  * Idempotent: re-registering with the same data_classes returns
31
51
  * rows_inserted=0, rows_updated=0. Removing a data_class entry between boots
32
52
  * soft-deletes the row.
53
+ *
54
+ * D719 — every `subjectKind` is validated against the CLOSED vocabulary BEFORE
55
+ * any dispatch mode runs, and an unknown kind throws
56
+ * {@link UnknownSubjectKindError}. This call happens at service boot, so the
57
+ * rejection is boot-loud: the process fails to start rather than silently
58
+ * writing an unroutable `retention_policies` row.
59
+ *
60
+ * Why it must fail rather than warn: the orchestrator's fan-out is
61
+ * subject_kind-ONLY (D486 — `SELECT DISTINCT service_id FROM retention_policies
62
+ * WHERE subject_kind = $1`). A row registered under a typo, a retired kind
63
+ * (`platform_admin`), or an internal DEK key SCOPE (`TICKET_REQUESTER`, …) is
64
+ * never selected by any fan-out, so the service is silently skipped on every
65
+ * erase — an erase-completeness hole that looks exactly like a successful
66
+ * registration from the caller's side.
33
67
  */
34
68
  export declare function registerWithOrchestrator(opts: RegisterWithOrchestratorOpts): Promise<RegisterWithOrchestratorResult>;
35
69
  export {};
@@ -1 +1 @@
1
- {"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,KAAK,SAAS,GAAG;IAEf,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;CACzD,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,cAAc,CAAC;CAC7B;AAED,MAAM,WAAW,4BAA4B;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,qBAAqB,EAAE,CAAC;IACrC,iDAAiD;IACjD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,8BAA8B;IAC7C,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,4BAA4B,GACjC,OAAO,CAAC,8BAA8B,CAAC,CAUzC"}
1
+ {"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":"AAaA,OAAO,EAAe,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAE9E,KAAK,SAAS,GAAG;IAEf,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;CACzD,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,cAAc,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,4BAA4B;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,qBAAqB,EAAE,CAAC;IACrC,iDAAiD;IACjD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,8BAA8B;IAC7C,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,4BAA4B,GACjC,OAAO,CAAC,8BAA8B,CAAC,CA+BzC"}
package/dist/register.js CHANGED
@@ -9,14 +9,40 @@
9
9
  // orchestrator's RPC; CI tests against synthetic mini-microservices).
10
10
  // - `sqlClient` set → direct UPSERT into `retention_policies` (orchestrator-
11
11
  // internal mode; used by nodii-tenant-service itself).
12
+ import { assertSubjectKind } from "./subject-kinds.js";
13
+ import { isPiiBucket } from "./types.js";
12
14
  /**
13
15
  * Register this service's data-class set with the orchestrator. Spec § 5.11.5.
14
16
  *
15
17
  * Idempotent: re-registering with the same data_classes returns
16
18
  * rows_inserted=0, rows_updated=0. Removing a data_class entry between boots
17
19
  * soft-deletes the row.
20
+ *
21
+ * D719 — every `subjectKind` is validated against the CLOSED vocabulary BEFORE
22
+ * any dispatch mode runs, and an unknown kind throws
23
+ * {@link UnknownSubjectKindError}. This call happens at service boot, so the
24
+ * rejection is boot-loud: the process fails to start rather than silently
25
+ * writing an unroutable `retention_policies` row.
26
+ *
27
+ * Why it must fail rather than warn: the orchestrator's fan-out is
28
+ * subject_kind-ONLY (D486 — `SELECT DISTINCT service_id FROM retention_policies
29
+ * WHERE subject_kind = $1`). A row registered under a typo, a retired kind
30
+ * (`platform_admin`), or an internal DEK key SCOPE (`TICKET_REQUESTER`, …) is
31
+ * never selected by any fan-out, so the service is silently skipped on every
32
+ * erase — an erase-completeness hole that looks exactly like a successful
33
+ * registration from the caller's side.
18
34
  */
19
35
  export async function registerWithOrchestrator(opts) {
36
+ for (const dc of opts.dataClasses) {
37
+ assertSubjectKind(dc.subjectKind, `registerWithOrchestrator(serviceName=${JSON.stringify(opts.serviceName)}, dataClass=${JSON.stringify(dc.dataClass)})`);
38
+ // D720 — boot-loud on a typo'd bucket, for the same reason the subject-kind
39
+ // check above is boot-loud: this declaration decides whether an erase
40
+ // destroys the class or retains it, and a silently-defaulted typo picks
41
+ // "destroy".
42
+ if (dc.bucket !== undefined && !isPiiBucket(dc.bucket)) {
43
+ throw new Error(`registerWithOrchestrator(serviceName=${JSON.stringify(opts.serviceName)}, dataClass=${JSON.stringify(dc.dataClass)}): unknown retention bucket ${JSON.stringify(dc.bucket)} — expected one of statutory | operational | free_text (D720). The bucket decides whether a DSAR erase destroys this class or retains it under statute; an unrecognised value cannot be defaulted.`);
44
+ }
45
+ }
20
46
  if (opts.sqlClient) {
21
47
  return registerViaSql(opts);
22
48
  }
@@ -1 +1 @@
1
- {"version":3,"file":"register.js","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"register.js","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,252 @@
1
+ import type { HoldKind, RetentionAnchor, RetentionSchedule, SqlTransaction } from "./types.js";
2
+ type SqlClient = {
3
+ unsafe: (sql: string, args?: unknown[]) => Promise<any>;
4
+ /**
5
+ * Optional transaction runner (porsager `sql.begin`). When present, each
6
+ * record's HARD DELETE and its purge event commit or roll back TOGETHER — the
7
+ * same atomicity D239 gives the compliance events. When absent, the two run
8
+ * sequentially on the pool and a crash between them can drop the event for an
9
+ * already-deleted row; the sweeper says so rather than pretending otherwise.
10
+ */
11
+ begin?: <T>(cb: (tx: SqlTransaction) => Promise<T>) => Promise<T>;
12
+ };
13
+ /** Canonical sweeper job name, mirroring the reaper's metrics family. */
14
+ export declare const RETENTION_SWEEPER_JOB_NAME = "dsar.retention_sweeper";
15
+ /** Default sweep interval — 24h, same cadence as the lifecycle reaper. */
16
+ export declare const RETENTION_SWEEPER_INTERVAL_MS: number;
17
+ /** Default per-target row budget for one sweep. */
18
+ export declare const RETENTION_SWEEPER_BATCH_SIZE = 500;
19
+ /**
20
+ * D720 amendment to D593 — the per-record purge topic:
21
+ * `<serviceName>.retention.record_purged.v1`.
22
+ */
23
+ export declare function retentionPurgeTopic(serviceName: string): string;
24
+ /**
25
+ * One service table the sweeper scans, and how to read a retention window out
26
+ * of it. The consumer declares this because the LIBRARY CANNOT KNOW IT: which
27
+ * column holds "relationship_end" for a payslip, or which jurisdiction a given
28
+ * invoice was filed under, is service knowledge.
29
+ */
30
+ export interface RetentionSweepTarget {
31
+ /** The registered data class this table holds. Carried on the purge event. */
32
+ dataClass: string;
33
+ /** Table to scan. Validated as a bare SQL identifier. */
34
+ tableName: string;
35
+ /**
36
+ * The ANCHOR timestamp column — whichever of creation / last activity /
37
+ * relationship end / filing date the schedule counts from. MUST correspond to
38
+ * the matched schedule's `anchor`; a mismatch is caught at sweep time
39
+ * (`anchor` below).
40
+ */
41
+ anchorColumn: string;
42
+ /** Which anchor `anchorColumn` represents. Schedules with a different anchor are SKIPPED. */
43
+ anchor: RetentionAnchor;
44
+ /** Primary-key column. Defaults to `id`. */
45
+ idColumn?: string;
46
+ /** Tenant column. Defaults to `tenant_id`. */
47
+ tenantColumn?: string;
48
+ /** Subject column, when the table has one — narrows the hold consult. */
49
+ subjectColumn?: string;
50
+ /** Fixed jurisdiction for every row in this table. Mutually exclusive with `jurisdictionColumn`. */
51
+ jurisdiction?: string;
52
+ /** Per-row jurisdiction column (e.g. the tenant's filing country). */
53
+ jurisdictionColumn?: string;
54
+ /** Schedule `document_class`. Defaults to `dataClass`. */
55
+ documentClass?: string;
56
+ /** Schedule `entity_kind`. Defaults to `dataClass`. */
57
+ entityKind?: string;
58
+ }
59
+ /** One record the sweeper resolved as past its window. */
60
+ export interface RetentionPurgeRecord {
61
+ dataClass: string;
62
+ tableName: string;
63
+ recordId: string;
64
+ tenantId: string;
65
+ subjectId: string | null;
66
+ jurisdiction: string;
67
+ documentClass: string;
68
+ entityKind: string;
69
+ /** ISO-8601 — the record's anchor timestamp. */
70
+ anchoredAt: string;
71
+ /** ISO-8601 — when the window expired. */
72
+ retainedUntil: string;
73
+ /** The schedule that governed it. */
74
+ schedule: RetentionSchedule;
75
+ }
76
+ /** The `<svc>.retention.record_purged.v1` payload (D720 / D593 amendment). */
77
+ export interface RetentionPurgeEvent {
78
+ topic: string;
79
+ serviceName: string;
80
+ dataClass: string;
81
+ tableName: string;
82
+ recordId: string;
83
+ tenantId: string;
84
+ subjectId: string | null;
85
+ jurisdiction: string;
86
+ documentClass: string;
87
+ entityKind: string;
88
+ retentionPeriod: string;
89
+ anchor: RetentionAnchor;
90
+ anchoredAt: string;
91
+ retainedUntil: string;
92
+ statuteCitation?: string;
93
+ purgedAt: string;
94
+ }
95
+ /**
96
+ * The consumer's outbox adapter — same seam shape as `OutboxEmitter`, so a
97
+ * service wires the SAME `insertIntoOutbox` helper it already has. Called once
98
+ * per purged record.
99
+ */
100
+ export type RetentionPurgeOutboxEmitter = (tx: SqlTransaction, event: RetentionPurgeEvent) => Promise<void>;
101
+ export interface RetentionSweeperOpts {
102
+ /** Used to build the purge topic. The gRPC/wire service identity. */
103
+ serviceName: string;
104
+ /**
105
+ * OWNER-pool-backed SQL client. The sweep SELECTs the service's own tables
106
+ * and the purge DELETEs rows; both are owner-granted (BYPASSRLS) per the RLS
107
+ * doctrine, exactly like the lifecycle reaper's DELETE.
108
+ */
109
+ db: SqlClient;
110
+ /**
111
+ * The schedule registry. Either a static array or a loader called once per
112
+ * sweep (so a schedule amendment takes effect on the next tick without a
113
+ * redeploy — read `retention_schedules` here).
114
+ */
115
+ schedules: readonly RetentionSchedule[] | (() => Promise<readonly RetentionSchedule[]>);
116
+ /** The service's class→table mapping. */
117
+ targets: readonly RetentionSweepTarget[];
118
+ /**
119
+ * HARD-DELETE the record. MUST actually delete (or irreversibly destroy) the
120
+ * row — crypto-shred alone does not complete "put beyond use" (EDPB 02/2025
121
+ * §51), and this job exists precisely to finish what the shred cannot.
122
+ *
123
+ * `tx` is the transaction the purge event is written in (present only when
124
+ * the supplied `db` exposes `begin`). Run the DELETE on it and the row and
125
+ * its event commit together.
126
+ *
127
+ * A throw aborts THIS record only; the sweep continues and reports it in
128
+ * `errors`. The purge event is emitted only AFTER `onPurge` resolves, so a
129
+ * failed delete never announces a deletion that did not happen.
130
+ */
131
+ onPurge: (record: RetentionPurgeRecord, tx?: SqlTransaction) => Promise<void>;
132
+ /**
133
+ * Emits `<svc>.retention.record_purged.v1`, one row per purged record
134
+ * (D593 amendment). Omit and no events are produced.
135
+ */
136
+ outboxEmitter?: RetentionPurgeOutboxEmitter;
137
+ /** Defaults to `data_residency_holds`. */
138
+ holdsTableName?: string;
139
+ /**
140
+ * Hold kinds that BLOCK a purge. Defaults to
141
+ * {@link DEFAULT_ERASE_BLOCKING_HOLD_KINDS} — a preservation (litigation /
142
+ * regulator) hold is whole-record and blocks every bucket, so the same set
143
+ * that blocks an erase blocks a scheduled purge.
144
+ */
145
+ blockingHoldKinds?: readonly HoldKind[];
146
+ /**
147
+ * ACTIONABLE budget per target per sweep — how many rows the tick will act
148
+ * on (purge) or clear as in-window before it stops. Defaults to 500.
149
+ *
150
+ * Skipped rows (held, no resolvable schedule) do NOT consume this budget.
151
+ * That is deliberate and is the fix for head-of-line starvation: the scan is
152
+ * ordered by anchor ASC, so permanently-skipped rows are the OLDEST rows and
153
+ * sit at the head forever. Under a plain `LIMIT batchSize` with no cursor,
154
+ * once they numbered `>= batchSize` they re-filled every batch on every tick
155
+ * and nothing behind them was ever examined again — while the sweeper kept
156
+ * reporting success.
157
+ */
158
+ batchSize?: number;
159
+ /**
160
+ * Hard ceiling on rows READ per target per sweep, skipped ones included.
161
+ * Defaults to `10 × batchSize`.
162
+ *
163
+ * The cursor walks past skipped rows, so without a ceiling a corpus of a
164
+ * million held records would make every tick a full table scan. When this
165
+ * cap stops a tick, `exhausted` is false — the tick says so rather than
166
+ * looking complete.
167
+ */
168
+ maxScan?: number;
169
+ /** Override the 24h interval. */
170
+ intervalMs?: number;
171
+ /** Injectable clock (tests). */
172
+ now?: () => Date;
173
+ /** Optional hook after each sweep (metrics). */
174
+ onRun?: (result: RetentionSweepResult) => void | Promise<void>;
175
+ }
176
+ export interface RetentionSweepResult {
177
+ /** Records hard-deleted. */
178
+ purged: number;
179
+ /** Records inside their window — untouched. */
180
+ inWindow: number;
181
+ /** Records past their window but covered by an active hold. */
182
+ skippedHeld: number;
183
+ /** Records with no resolvable schedule — never purged (absence of a rule is not a licence). */
184
+ skippedNoSchedule: number;
185
+ /**
186
+ * Rows READ from the service's tables this tick, skipped ones included.
187
+ *
188
+ * The distinction between this and `purged + inWindow` is the whole point of
189
+ * the keyset cursor: a sweep that scanned 5000 rows to purge 3 is telling you
190
+ * something a purge count alone hides.
191
+ */
192
+ scanned: number;
193
+ /**
194
+ * True when every target was read to its end this tick. FALSE means the tick
195
+ * stopped early — the actionable budget filled, or `maxScan` capped it — so
196
+ * rows beyond the cursor were never examined. A saturated tick is visible
197
+ * rather than silent, which is what makes starvation diagnosable instead of
198
+ * merely absent-looking.
199
+ */
200
+ exhausted: boolean;
201
+ /** Per-record `onPurge` failures. The record survives to the next sweep. */
202
+ errors: Array<{
203
+ recordId: string;
204
+ tableName: string;
205
+ error: string;
206
+ }>;
207
+ /** ISO-8601 timestamp the run completed. */
208
+ ranAt: string;
209
+ }
210
+ export interface RetentionSweeperJobDefinition {
211
+ name: string;
212
+ intervalMs: number;
213
+ /** The SELECT + DELETE are owner-granted; the client MUST be owner-pool-backed. */
214
+ pool: "owner";
215
+ handler: () => Promise<RetentionSweepResult>;
216
+ }
217
+ /**
218
+ * Raised when the hold consult fails during a sweep.
219
+ *
220
+ * FAIL-CLOSED, and it aborts the WHOLE sweep rather than skipping one record.
221
+ * The operator ruling the hold posture rests on is "if holds is inaccessible we
222
+ * deny the write — fail CLOSED" (2026-07-30), and a purge is the most
223
+ * irreversible write in the system. Skipping quietly would also be
224
+ * indistinguishable, in the run result, from "nothing was due" — so the sweep
225
+ * raises, the scheduler logs, and the next tick retries once holds is readable.
226
+ */
227
+ export declare class RetentionSweepHoldConsultFailed extends Error {
228
+ readonly code = "RETENTION_SWEEP_HOLD_CONSULT_FAILED";
229
+ constructor(tableName: string, recordId: string, cause: unknown);
230
+ }
231
+ /**
232
+ * D720 — build the schedulable purpose-spent sweeper.
233
+ *
234
+ * Per sweep, per target:
235
+ * 1. SELECT the batch (id, tenant, subject?, jurisdiction?, anchor);
236
+ * 2. resolve the governing schedule via {@link applyRetentionSchedules} —
237
+ * no schedule ⇒ SKIP (absence of a rule is never a licence to delete);
238
+ * 3. still inside its window ⇒ SKIP;
239
+ * 4. `extended_by_proceeding` ⇒ SKIP unless a hold consult says otherwise
240
+ * (an open proceeding rides the hold mechanism per D720);
241
+ * 5. hold consult (FAIL-CLOSED — a consult error aborts the sweep);
242
+ * 6. `onPurge(record, tx)` — the consumer's hard delete;
243
+ * 7. emit `<svc>.retention.record_purged.v1`.
244
+ *
245
+ * Steps 6+7 run in ONE transaction when `db` exposes `begin`, so the delete and
246
+ * its event commit together. Without a transaction runner the event is emitted
247
+ * after the delete resolves — a dropped event is recoverable, an
248
+ * announced-but-undeleted row is not.
249
+ */
250
+ export declare function makeRetentionSweeperJob(opts: RetentionSweeperOpts): RetentionSweeperJobDefinition;
251
+ export {};
252
+ //# sourceMappingURL=retention-sweeper.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"retention-sweeper.d.ts","sourceRoot":"","sources":["../src/retention-sweeper.ts"],"names":[],"mappings":"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"}