@nodii/dsar 0.20.0 → 0.23.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.
- package/dist/bind-pattern-a.d.ts +127 -13
- package/dist/bind-pattern-a.d.ts.map +1 -1
- package/dist/bind-pattern-a.js +553 -32
- package/dist/bind-pattern-a.js.map +1 -1
- package/dist/bind-pattern-b.d.ts.map +1 -1
- package/dist/bind-pattern-b.js +58 -3
- package/dist/bind-pattern-b.js.map +1 -1
- package/dist/grpc/dsar-service.d.ts +29 -0
- package/dist/grpc/dsar-service.d.ts.map +1 -1
- package/dist/grpc/dsar-service.js +34 -0
- package/dist/grpc/dsar-service.js.map +1 -1
- package/dist/grpc/proto-path.d.ts +33 -0
- package/dist/grpc/proto-path.d.ts.map +1 -0
- package/dist/grpc/proto-path.js +87 -0
- package/dist/grpc/proto-path.js.map +1 -0
- package/dist/hold-failure-mode.d.ts +24 -0
- package/dist/hold-failure-mode.d.ts.map +1 -1
- package/dist/hold-failure-mode.js +24 -0
- package/dist/hold-failure-mode.js.map +1 -1
- package/dist/hold-gate-probe.d.ts +61 -0
- package/dist/hold-gate-probe.d.ts.map +1 -0
- package/dist/hold-gate-probe.js +146 -0
- package/dist/hold-gate-probe.js.map +1 -0
- package/dist/holds.d.ts +60 -1
- package/dist/holds.d.ts.map +1 -1
- package/dist/holds.js +60 -3
- package/dist/holds.js.map +1 -1
- package/dist/index.d.ts +16 -6
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +28 -5
- package/dist/index.js.map +1 -1
- package/dist/migrations/index.d.ts.map +1 -1
- package/dist/migrations/index.js +10 -0
- package/dist/migrations/index.js.map +1 -1
- package/dist/orchestrator.d.ts +48 -0
- package/dist/orchestrator.d.ts.map +1 -1
- package/dist/orchestrator.js +297 -20
- package/dist/orchestrator.js.map +1 -1
- package/dist/register.d.ts +35 -1
- package/dist/register.d.ts.map +1 -1
- package/dist/register.js +26 -0
- package/dist/register.js.map +1 -1
- package/dist/retention-sweeper.d.ts +252 -0
- package/dist/retention-sweeper.d.ts.map +1 -0
- package/dist/retention-sweeper.js +356 -0
- package/dist/retention-sweeper.js.map +1 -0
- package/dist/retention.d.ts +109 -1
- package/dist/retention.d.ts.map +1 -1
- package/dist/retention.js +216 -3
- package/dist/retention.js.map +1 -1
- package/dist/subject-kinds.d.ts +74 -0
- package/dist/subject-kinds.d.ts.map +1 -0
- package/dist/subject-kinds.js +141 -0
- package/dist/subject-kinds.js.map +1 -0
- package/dist/types.d.ts +423 -7
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +164 -0
- package/dist/types.js.map +1 -1
- package/package.json +7 -4
- package/proto/nodii/dsar/v1/dsar.proto +202 -0
- package/src/migrations/001-lifecycle-requests.sql +422 -0
package/dist/register.d.ts
CHANGED
|
@@ -1,10 +1,30 @@
|
|
|
1
|
-
import type
|
|
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 {};
|
package/dist/register.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":"
|
|
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
|
}
|
package/dist/register.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"register.js","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,EAAE;AACF,6EAA6E;AAC7E,qEAAqE;AACrE,wDAAwD;AACxD,EAAE;AACF,0BAA0B;AAC1B,uEAAuE;AACvE,0EAA0E;AAC1E,+EAA+E;AAC/E,2DAA2D;
|
|
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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"}
|