@marinoscar/platform-api 0.1.0-next.3 → 0.1.0-next.5

package/dist/jobs/rate-limit.error.js

@@ -0,0 +1,338 @@
+"use strict";
+// =============================================================================
+// Rate-limit classification (issue #261, epic #254)
+// =============================================================================
+//
+// THE QUEUE HAS TWO GENUINELY DIFFERENT KINDS OF FAILURE, and this file is
+// how it tells them apart.
+//
+//   - A BUG (a null dereference, a malformed payload, a permission error)
+//     should burn through a small attempt budget quickly and land in `failed`
+//     where a human can see it. Retrying it is nearly free and nearly
+//     pointless; retrying it fifty times is spam.
+//   - A PROVIDER RATE LIMIT is not a failure of the work at all. Nothing is
+//     wrong with the job, the payload, or the code; we simply asked too often.
+//     It should back off for MINUTES, and it must NOT consume the attempt
+//     budget — otherwise a long backfill against a throttling provider
+//     exhausts three attempts in the first minute and fails permanently for a
+//     reason that was never its fault.
+//
+// The whole rest of the terminal path depends on getting that discrimination
+// right, so it lives in one testable place rather than inline in a `catch`.
+//
+// -----------------------------------------------------------------------------
+// TWO WAYS IN, ON PURPOSE
+// -----------------------------------------------------------------------------
+//
+// `RateLimitError` is for a handler that KNOWS: it read the provider's
+// response itself and can say so explicitly, with the exact `retryAfterMs`
+// the provider named. `classifyRateLimit` is for everything else — an error
+// object thrown by an SDK that has its own shape and no idea this queue
+// exists. Handlers should not have to wrap every SDK, and SDK errors should
+// not have to be pre-classified, so both work.
+//
+// -----------------------------------------------------------------------------
+// ERRORS THAT CLASSIFY THEMSELVES (issue #509)
+// -----------------------------------------------------------------------------
+//
+// The status/name heuristics below exist for errors that know nothing about
+// this queue. They are WRONG for this application's own typed, code-carrying
+// errors: `AiError` extends Nest's `HttpException`, so its `.status` is the
+// HTTP *response* status this platform chose for its code — 503 for
+// "object storage is not configured" — not an upstream capacity signal. Read
+// as a throttle, that 503 held an unrunnable job in rate-limit deferral for
+// up to `JOBS_RATELIMIT_MAX_HITS` backoffs of up to fifteen minutes each,
+// never charging an attempt, for a condition only an administrator can fix.
+//
+// So an error may answer for itself: a function at the well-known
+// `CLASSIFY_RATE_LIMIT` symbol is asked FIRST (after `RateLimitError`), and
+// its answer is FINAL — the heuristics are not consulted. A symbol rather
+// than an import keeps the layering one-way: `jobs/` is the lower layer and
+// never imports from a feature (`ai/`), while a feature's error class
+// implements the symbol from here. `Symbol.for` makes it survive duplicate
+// module instances (a test double, a second copy of this file in a bundle).
+//
+// A remote worker node is a THIRD way in and deliberately does NOT live here:
+// it cannot throw a typed error across HTTP, so it reports the same
+// conclusion as flags (`{ rateLimited: true, retryAfterMs }`) and
+// `JobTerminalService.completeFailed` gives those flags the identical
+// treatment. See that file for the classification ORDER.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLASSIFY_RATE_LIMIT = exports.RateLimitError = void 0;
+exports.parseRetryAfterMs = parseRetryAfterMs;
+exports.classifyRateLimit = classifyRateLimit;
+/**
+ * Thrown by a handler that has positively identified a provider rate limit.
+ *
+ * Carries the provider's own `Retry-After` when there was one; the deferral
+ * treats it as a FLOOR on the computed backoff, never as an override (see
+ * `backoff.util.ts`).
+  *
+  * @stability experimental
+ */
+class RateLimitError extends Error {
+    retryAfterMs;
+    constructor(message, 
+    /** The provider's own `Retry-After`, in milliseconds, when it sent one; a floor on the backoff. */
+    retryAfterMs) {
+        super(message);
+        this.retryAfterMs = retryAfterMs;
+        this.name = 'RateLimitError';
+        // ⚠ REQUIRED, NOT CEREMONIAL. Extending a built-in (`Error`) breaks
+        // `instanceof` when the class is downlevelled: the emitted constructor
+        // calls `Error.call(this)`, which returns a fresh `Error` and leaves
+        // `this`'s prototype chain pointing at `Error.prototype` rather than
+        // `RateLimitError.prototype`. The symptom is the worst possible one for
+        // this file — `err instanceof RateLimitError` quietly returns `false`,
+        // every provider throttle is classified as an ordinary bug, and long
+        // backfills fail permanently on a transient condition. Restoring the
+        // prototype explicitly makes the check work under every target.
+        Object.setPrototypeOf(this, RateLimitError.prototype);
+    }
+}
+exports.RateLimitError = RateLimitError;
+const NOT_RATE_LIMITED = { rateLimited: false, retryAfterMs: null };
+/**
+ * The well-known key an error implements to classify itself (issue #509).
+ * See "ERRORS THAT CLASSIFY THEMSELVES" in the file header.
+  *
+  * @stability experimental
+ */
+exports.CLASSIFY_RATE_LIMIT = Symbol.for('jobs.classifyRateLimit');
+/**
+ * Normalises whatever a self-classifying error returned: `rateLimited` must
+ * be literally `true`, and a delay must be a finite positive number — any
+ * other value is "no opinion" (`null`), never zero.
+ */
+function normalizeSelfClassification(result) {
+    if (result === null || typeof result !== 'object') {
+        return NOT_RATE_LIMITED;
+    }
+    const { rateLimited, retryAfterMs } = result;
+    if (rateLimited !== true) {
+        return NOT_RATE_LIMITED;
+    }
+    return {
+        rateLimited: true,
+        retryAfterMs: typeof retryAfterMs === 'number' && Number.isFinite(retryAfterMs) && retryAfterMs > 0
+            ? retryAfterMs
+            : null,
+    };
+}
+/**
+ * HTTP statuses that mean "you are being throttled".
+ *
+ *   429 — Too Many Requests. The unambiguous one.
+ *   503 — Service Unavailable. Overload. Retrying immediately makes it worse;
+ *         it is a capacity signal, not a defect in the request, so it belongs
+ *         on the back-off-and-do-not-charge-an-attempt path.
+ *   529 — a non-standard "overloaded" status several API providers return in
+ *         preference to 503. Same meaning, same treatment.
+ *
+ * DELIBERATELY NOT HERE: 500 and 502. They are genuine faults rather than
+ * capacity signals, and treating them as rate limits would let a permanently
+ * broken provider hold jobs in deferral against the (much larger) rate-limit
+ * budget instead of failing them where somebody notices.
+ */
+const RATE_LIMIT_STATUSES = new Set([429, 503, 529]);
+/**
+ * Provider error NAMES that mean throttling with no HTTP status attached.
+ *
+ * AWS SDK clients frequently surface a throttle as a named error whose status
+ * is 400 — so a status-only classifier reads "client error, this request is
+ * malformed, fail it permanently" for what is really "slow down". These names
+ * are the documented retryable-throttling set shared across AWS services;
+ * matching them is what keeps an S3 `SlowDown` or a DynamoDB
+ * `ProvisionedThroughputExceededException` on the deferral path.
+ *
+ * Compared case-insensitively, because SDKs are inconsistent about whether
+ * the name arrives on `name`, `code`, or `__type` (which is often
+ * fully-qualified, e.g. `com.amazonaws...#ThrottlingException`).
+ */
+const THROTTLE_ERROR_NAMES = new Set([
+    'ThrottlingException',
+    'Throttling',
+    'ThrottledException',
+    'RequestThrottled',
+    'RequestThrottledException',
+    'TooManyRequestsException',
+    'RequestLimitExceeded',
+    'SlowDown',
+    'PriorRequestNotComplete',
+    'EC2ThrottledException',
+    'TransactionInProgressException',
+    'ProvisionedThroughputExceededException',
+    'LimitExceededException',
+    'BandwidthLimitExceeded',
+].map((name) => name.toLowerCase()));
+/** Every place a status code is realistically found on a thrown provider error. */
+function readStatus(err) {
+    const response = err.response;
+    const metadata = err.$metadata;
+    const candidates = [
+        err.status,
+        err.statusCode,
+        response?.status,
+        response?.statusCode,
+        metadata?.httpStatusCode,
+    ];
+    for (const candidate of candidates) {
+        if (typeof candidate === 'number' && Number.isFinite(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/** Every place a throttle NAME is realistically found. */
+function readNames(err) {
+    const names = [];
+    for (const key of ['name', 'code', '__type', 'errorType']) {
+        const value = err[key];
+        if (typeof value === 'string' && value.length > 0) {
+            // `__type` is often `com.amazonaws.dynamodb#ThrottlingException`;
+            // take the last path-ish segment as well as the whole string.
+            const tail = value.split(/[#/.:]/).pop();
+            names.push(value.toLowerCase());
+            if (tail && tail !== value) {
+                names.push(tail.toLowerCase());
+            }
+        }
+    }
+    return names;
+}
+/** Reads `retry-after` out of whatever header container the SDK used. */
+function readRetryAfterHeader(err) {
+    const response = err.response;
+    const containers = [
+        err.headers,
+        response?.headers,
+        err.$response?.headers,
+    ];
+    for (const container of containers) {
+        if (!container) {
+            continue;
+        }
+        // A `fetch` Headers instance: case-insensitive `get`.
+        const getter = container.get;
+        if (typeof getter === 'function') {
+            const value = getter.call(container, 'retry-after');
+            if (typeof value === 'string') {
+                return value;
+            }
+            continue;
+        }
+        // A plain object. Node lowercases incoming header names; other clients do
+        // not, so match case-insensitively rather than guessing.
+        for (const [key, value] of Object.entries(container)) {
+            if (key.toLowerCase() === 'retry-after' && (typeof value === 'string' || typeof value === 'number')) {
+                return String(value);
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Parses an HTTP `Retry-After` header value into milliseconds.
+ *
+ * RFC 9110 allows exactly two forms and this accepts both, because providers
+ * genuinely use both:
+ *
+ *   - `Retry-After: 120`      — delta-seconds → 120000
+ *   - `Retry-After: Wed, 21 Oct 2015 07:28:00 GMT` — an HTTP-date, converted
+ *     to a delay RELATIVE TO `now` (which is a parameter so tests can pin it,
+ *     and so a caller that already has a clock does not disagree with this
+ *     function about what time it is).
+ *
+ * Returns `null` for absent, empty, unparseable, or nonsensical input —
+ * INCLUDING a date already in the past, which is not an error but does not
+ * describe a wait. `null` means "no opinion", and the caller falls back to
+ * pure backoff; it never means zero, because a provider that said nothing
+ * must not be read as a provider that said "retry immediately".
+ *
+ * A negative delta-seconds is also `null` for the same reason. A fractional
+ * value (`0.5`) is rejected too: the grammar is DIGIT-only, so a fractional
+ * value means the header is not what we think it is, and guessing at a
+ * malformed header is how a 500ms wait gets read as a 500-second one.
+  *
+  * @stability experimental
+ */
+function parseRetryAfterMs(header, now = Date.now()) {
+    if (header === null || header === undefined) {
+        return null;
+    }
+    const raw = String(header).trim();
+    if (raw.length === 0) {
+        return null;
+    }
+    // Form 1: delta-seconds. Anchored and digit-only, deliberately — `parseInt`
+    // would happily read `30 minutes` as 30 and `1e3` as 1.
+    if (/^\d+$/.test(raw)) {
+        const seconds = Number(raw);
+        return Number.isFinite(seconds) ? seconds * 1000 : null;
+    }
+    // Form 2: HTTP-date.
+    const timestamp = Date.parse(raw);
+    if (Number.isNaN(timestamp)) {
+        return null;
+    }
+    const delta = timestamp - now;
+    // A date at or before `now` describes no wait at all. See the doc comment:
+    // that is "no opinion", not "zero".
+    return delta > 0 ? delta : null;
+}
+/**
+ * Decides whether an arbitrary thrown value is a provider rate limit, and
+ * extracts any `Retry-After` it carried.
+ *
+ * TOTAL AND NEVER THROWS. It is called from inside a failure path, on a value
+ * that is `unknown` by construction (anything can be thrown in JavaScript),
+ * so anything it does not positively recognise — a string, `null`, a plain
+ * `Error`, an SDK shape nobody anticipated — is simply "not a rate limit".
+ * The cost of a false negative is one wasted attempt; the cost of throwing
+ * here would be losing the failure handling entirely.
+  *
+  * @stability experimental
+ */
+function classifyRateLimit(err, now = Date.now()) {
+    // The explicit signal always wins, and carries its own delay.
+    if (err instanceof RateLimitError) {
+        return { rateLimited: true, retryAfterMs: err.retryAfterMs ?? null };
+    }
+    if (err === null || (typeof err !== 'object' && typeof err !== 'function')) {
+        return NOT_RATE_LIMITED;
+    }
+    const candidate = err;
+    // ⚠ THE try/catch IS WHAT MAKES THE "NEVER THROWS" PROMISE TRUE, and it is
+    // not theoretical: every read below touches a property on an object that
+    // came from somewhere else, and a property can be a GETTER. Several SDKs
+    // and proxy/mock libraries define lazily-computed or deliberately
+    // exploding accessors, and an exception raised while classifying a failure
+    // would escape the failure handler itself — losing the retry, the
+    // deferral, and the `lastError` for a job whose only real problem was that
+    // something upstream threw an unusual object. Degrading to "not a rate
+    // limit" costs at most one attempt.
+    try {
+        // An error that classifies itself is believed, and ONLY it — see
+        // "ERRORS THAT CLASSIFY THEMSELVES" in the header (issue #509). A
+        // throwing classifier lands in the catch below: not a rate limit.
+        const selfClassify = candidate[exports.CLASSIFY_RATE_LIMIT];
+        if (typeof selfClassify === 'function') {
+            return normalizeSelfClassification(selfClassify.call(candidate));
+        }
+        const status = readStatus(candidate);
+        const byStatus = status !== null && RATE_LIMIT_STATUSES.has(status);
+        const byName = readNames(candidate).some((name) => THROTTLE_ERROR_NAMES.has(name));
+        if (!byStatus && !byName) {
+            return NOT_RATE_LIMITED;
+        }
+        return {
+            rateLimited: true,
+            retryAfterMs: parseRetryAfterMs(readRetryAfterHeader(candidate), now),
+        };
+    }
+    catch {
+        return NOT_RATE_LIMITED;
+    }
+}
+//# sourceMappingURL=rate-limit.error.js.map

package/dist/jobs/rate-limit.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.error.js","sourceRoot":"","sources":["../../src/jobs/rate-limit.error.ts"],"names":[],"mappings":"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"}

package/dist/jobs/retention/audit-events-purge.handler.d.ts

@@ -0,0 +1,75 @@
+import { OnModuleInit } from '@nestjs/common';
+import { SystemSettingsService } from '../../settings/index';
+import type { Job } from '../data/jobs-db';
+import type { JobExecutionProfile } from '../job-execution-profile';
+import type { JobHandler } from '../job-handler.interface';
+import { JobHandlerRegistry } from '../job-handler.registry';
+import { RetentionPurgeRegistry } from './retention-purge.registry';
+/**
+ * The job type. PERMANENT once rows of it exist.
+ *
+ * @stability experimental
+ */
+export declare const AUDIT_EVENTS_PURGE_TYPE = "audit.events.purge";
+/**
+ * The two `audit_events` calls the purge makes.
+ *
+ * @stability experimental
+ */
+export interface AuditEventsPurgeDelegate {
+    /** Prisma `findMany`: the ids to purge. */
+    findMany(args: any): Promise<AuditEventsPurgeIdRow[]>;
+    /** Prisma `deleteMany`: how many were removed. */
+    deleteMany(args: any): Promise<AuditEventsPurgeBatch>;
+}
+/**
+ * One row the purge reads.
+ *
+ * @stability experimental
+ */
+export interface AuditEventsPurgeIdRow {
+    /** The event's id. */
+    id: string;
+}
+/**
+ * What a bulk delete resolves to.
+ *
+ * @stability experimental
+ */
+export interface AuditEventsPurgeBatch {
+    /** Rows removed. */
+    count: number;
+}
+/**
+ * The part of the database client this purge uses: `audit_events`, two calls.
+ * Structural, so an app's generated client satisfies it unchanged.
+ *
+ * @stability experimental
+ */
+export interface AuditEventsPurgePrisma {
+    /** `audit_events`. */
+    auditEvent: AuditEventsPurgeDelegate;
+}
+/**
+ * Deletes `audit_events` past `retention.auditEvents.days`, in batches; a
+ * logged no-op while the policy is off (the default).
+ *
+ * @stability experimental
+ */
+export declare class AuditEventsPurgeHandler implements JobHandler, OnModuleInit {
+    private readonly registry;
+    private readonly prisma;
+    private readonly systemSettings;
+    private readonly retention;
+    private readonly logger;
+    readonly type = "audit.events.purge";
+    readonly label = "Audit log purge";
+    /** Deletes only; thirty minutes covers millions of rows. Retried like any housekeeping job. */
+    readonly profile: JobExecutionProfile;
+    constructor(registry: JobHandlerRegistry, prisma: AuditEventsPurgePrisma, systemSettings: SystemSettingsService, retention: RetentionPurgeRegistry);
+    /** Registers with the job registry and declares the `auditEvents` policy. */
+    onModuleInit(): void;
+    /** Throws to fail (a database error), so the queue's retry applies. */
+    process(job: Job): Promise<void>;
+}
+//# sourceMappingURL=audit-events-purge.handler.d.ts.map

package/dist/jobs/retention/audit-events-purge.handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-events-purge.handler.d.ts","sourceRoot":"","sources":["../../../src/jobs/retention/audit-events-purge.handler.ts"],"names":[],"mappings":"AAwBA,OAAO,EAA8B,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAEpE;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,uBAAuB,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAAC;IACtD,kDAAkD;IAClD,UAAU,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACvD;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,sBAAsB;IACtB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,sBAAsB;IACtB,UAAU,EAAE,wBAAwB,CAAC;CACtC;AAED;;;;;GAKG;AACH,qBACa,uBAAwB,YAAW,UAAU,EAAE,YAAY;IAWpE,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACA,OAAO,CAAC,QAAQ,CAAC,MAAM;IAChD,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAb5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4C;IAEnE,QAAQ,CAAC,IAAI,wBAA2B;IAExC,QAAQ,CAAC,KAAK,qBAAqB;IAEnC,+FAA+F;IAC/F,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAiD;gBAGnE,QAAQ,EAAE,kBAAkB,EACH,MAAM,EAAE,sBAAsB,EACvD,cAAc,EAAE,qBAAqB,EACrC,SAAS,EAAE,sBAAsB;IAGpD,6EAA6E;IAC7E,YAAY,IAAI,IAAI;IAKpB,uEAAuE;IACjE,OAAO,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;CAwBvC"}

package/dist/jobs/retention/audit-events-purge.handler.js

@@ -0,0 +1,109 @@
+"use strict";
+// =============================================================================
+// `audit.events.purge` job handler (#681, platform-packages PP-1.10; jobs slice since #898)
+// =============================================================================
+//
+// Deletes `audit_events` rows created before `retention.auditEvents.days` ago
+// (default 365), in bounded batches, using the existing `created_at` index.
+// Enqueued once a day by `RetentionPurgeTask`, which only enqueues.
+//
+// ⚠ OFF BY DEFAULT (`retention.auditEvents.enabled: false`). The audit trail
+// is a compliance record, so deleting any of it is an explicit operator
+// decision. While disabled this handler is a logged no-op — checked here as
+// well as in the task, so an admin rerun of an old row cannot delete history
+// an operator never agreed to delete; see `runRetentionPolicyPurge`.
+//
+// Provided by `JobsModule` rather than a feature module: many slices WRITE
+// audit events (identity, ai, notifications), and the table is the identity
+// slice's, but identity cannot import jobs (the dependency graph runs the other
+// way, `platform-slices.json`), so the purge lives with the retention engine
+// that schedules it. It sees the table through the two-method structural view
+// below, which any app's generated client satisfies as it is.
+//
+// SERVER-ONLY: no `nodeResultSchema`/`persistNodeResult`.
+// =============================================================================
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var AuditEventsPurgeHandler_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditEventsPurgeHandler = exports.AUDIT_EVENTS_PURGE_TYPE = void 0;
+const common_1 = require("@nestjs/common");
+const index_1 = require("../../core/index");
+const index_2 = require("../../settings/index");
+const job_handler_registry_1 = require("../job-handler.registry");
+const batched_purge_1 = require("./batched-purge");
+const retention_purge_registry_1 = require("./retention-purge.registry");
+/**
+ * The job type. PERMANENT once rows of it exist.
+ *
+ * @stability experimental
+ */
+exports.AUDIT_EVENTS_PURGE_TYPE = 'audit.events.purge';
+/**
+ * Deletes `audit_events` past `retention.auditEvents.days`, in batches; a
+ * logged no-op while the policy is off (the default).
+ *
+ * @stability experimental
+ */
+let AuditEventsPurgeHandler = AuditEventsPurgeHandler_1 = class AuditEventsPurgeHandler {
+    registry;
+    prisma;
+    systemSettings;
+    retention;
+    logger = new common_1.Logger(AuditEventsPurgeHandler_1.name);
+    type = exports.AUDIT_EVENTS_PURGE_TYPE;
+    label = 'Audit log purge';
+    /** Deletes only; thirty minutes covers millions of rows. Retried like any housekeeping job. */
+    profile = { maxRuntimeMs: 30 * 60_000, maxAttempts: 3 };
+    constructor(registry, prisma, systemSettings, retention) {
+        this.registry = registry;
+        this.prisma = prisma;
+        this.systemSettings = systemSettings;
+        this.retention = retention;
+    }
+    /** Registers with the job registry and declares the `auditEvents` policy. */
+    onModuleInit() {
+        this.registry.register(this);
+        this.retention.register({ policy: 'auditEvents', type: this.type, what: 'audit log purge' });
+    }
+    /** Throws to fail (a database error), so the queue's retry applies. */
+    async process(job) {
+        const { auditEvents: policy } = await this.systemSettings.getRetentionPolicy();
+        await (0, batched_purge_1.runRetentionPolicyPurge)({
+            job,
+            logger: this.logger,
+            policy,
+            setting: 'retention.auditEvents',
+            what: 'audit log purge',
+            rows: 'audit event(s)',
+            selectIds: async (cutoff, take) => {
+                const rows = await this.prisma.auditEvent.findMany({
+                    where: { createdAt: { lt: cutoff } },
+                    select: { id: true },
+                    orderBy: { createdAt: 'asc' },
+                    take,
+                });
+                return rows.map((row) => row.id);
+            },
+            deleteIds: async (ids) => (await this.prisma.auditEvent.deleteMany({ where: { id: { in: ids } } })).count,
+        });
+    }
+};
+exports.AuditEventsPurgeHandler = AuditEventsPurgeHandler;
+exports.AuditEventsPurgeHandler = AuditEventsPurgeHandler = AuditEventsPurgeHandler_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Inject)(index_1.PLATFORM_PRISMA)),
+    __metadata("design:paramtypes", [job_handler_registry_1.JobHandlerRegistry, Object, index_2.SystemSettingsService,
+        retention_purge_registry_1.RetentionPurgeRegistry])
+], AuditEventsPurgeHandler);
+//# sourceMappingURL=audit-events-purge.handler.js.map

package/dist/jobs/retention/audit-events-purge.handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-events-purge.handler.js","sourceRoot":"","sources":["../../../src/jobs/retention/audit-events-purge.handler.ts"],"names":[],"mappings":"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"}

package/dist/jobs/retention/batched-purge.d.ts

@@ -0,0 +1,112 @@
+import type { Logger } from '@nestjs/common';
+import type { RetentionPolicyValue } from '@marinoscar/platform-contract/jobs';
+import type { Job } from '../data/jobs-db';
+/**
+ * Ids per batch — a lock-duration bound, as in `ai-usage-purge.handler.ts`.
+ *
+ * @stability experimental
+ */
+export declare const RETENTION_PURGE_BATCH_SIZE = 5000;
+/**
+ * Safety stop on the batch loop (5 million rows a run); the next run continues from the same cutoff.
+ *
+ * @stability experimental
+ */
+export declare const RETENTION_PURGE_MAX_BATCHES = 1000;
+/**
+ * What one {@link purgeInBatches} run did.
+ *
+ * @stability experimental
+ */
+export interface BatchedPurgeResult {
+    /** Rows the deletes reported removed. */
+    deleted: number;
+    /** Batches that deleted something (an empty first read is zero batches). */
+    batches: number;
+    /** True when the loop stopped at `maxBatches` with rows possibly left. */
+    hitSafetyStop: boolean;
+}
+/**
+ * The loop's inputs: how to read a batch of ids and how to delete them.
+ *
+ * @stability experimental
+ */
+export interface BatchedPurgeOptions {
+    /** Reads at most `take` ids older than the cutoff, oldest first. */
+    selectIds: (take: number) => Promise<string[]>;
+    /** Deletes exactly these ids; returns the count. */
+    deleteIds: (ids: string[]) => Promise<number>;
+    /** Ids per batch (default {@link RETENTION_PURGE_BATCH_SIZE}). */
+    batchSize?: number;
+    /** Safety stop on the loop (default {@link RETENTION_PURGE_MAX_BATCHES}). */
+    maxBatches?: number;
+    /** Where the safety-stop warning goes. Optional so the loop stays usable on its own. */
+    logger?: Pick<Logger, 'warn'>;
+    /** A human phrase for the warning ("notification inbox purge"). */
+    what?: string;
+}
+/**
+ * Deletes in bounded batches until a batch comes back short or the safety stop
+ * is reached. Errors from `selectIds`/`deleteIds` propagate, so a queue job
+ * built on this fails and is retried.
+ *
+ * @param options - the reader, the deleter and the optional bounds.
+ * @returns what the loop deleted, in how many batches, and whether it stopped early.
+ * @throws RangeError when `batchSize` or `maxBatches` is not a positive integer.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function purgeInBatches(options: BatchedPurgeOptions): Promise<BatchedPurgeResult>;
+/**
+ * `now - days`, the instant before which a row is purged.
+ *
+ * @param days - the policy's retention in days.
+ * @param now - the clock, in epoch milliseconds (tests pin it).
+ * @returns the cutoff instant.
+ *
+ * @stability experimental
+ */
+export declare function retentionCutoff(days: number, now?: number): Date;
+/**
+ * What {@link runRetentionPolicyPurge} needs from a retention handler.
+ *
+ * @stability experimental
+ */
+export interface RetentionPolicyPurgeOptions {
+    /** The running job; only its id is logged. */
+    job: Pick<Job, 'id'>;
+    /** Where the summary and the disabled no-op line go. */
+    logger: Pick<Logger, 'log' | 'warn'>;
+    /** The policy as read at the start of this run — re-read per run, never cached. */
+    policy: RetentionPolicyValue;
+    /** The setting's path, for the log lines ("retention.aiRuns"). */
+    setting: string;
+    /** A human phrase for the log lines, lower case ("AI run purge"). */
+    what: string;
+    /** What a deleted row is, plural ("AI run(s)"). */
+    rows: string;
+    /** Reads at most `take` ids older than `cutoff` that this purge may delete, oldest first. */
+    selectIds: (cutoff: Date, take: number) => Promise<string[]>;
+    /** Deletes exactly these ids; returns the count. */
+    deleteIds: (ids: string[]) => Promise<number>;
+}
+/**
+ * The body of every retention handler: a logged no-op while the policy is
+ * disabled, otherwise `purgeInBatches` from `now - policy.days` and one summary
+ * line (deleted, cutoff, retention days, batches, job id).
+ *
+ * THE POLICY IS CHECKED HERE AS WELL AS IN THE SCHEDULING TASK, deliberately —
+ * the argument `job-history-purge.handler.ts` makes. The 01:00 task is not the
+ * only way a purge row appears: an admin rerun of a historical row, or a job
+ * queued just before the switch was flipped, would otherwise delete data an
+ * operator believes they stopped deleting.
+ *
+ * @param options - the job, logger, policy and the table's reader and deleter.
+ * @returns `null` for the disabled no-op, otherwise the loop's result.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function runRetentionPolicyPurge(options: RetentionPolicyPurgeOptions): Promise<BatchedPurgeResult | null>;
+//# sourceMappingURL=batched-purge.d.ts.map

package/dist/jobs/retention/batched-purge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batched-purge.d.ts","sourceRoot":"","sources":["../../../src/jobs/retention/batched-purge.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAE/E,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAIhD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/C,oDAAoD;IACpD,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9C,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA2C9F;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,IAAI,CAE5E;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,8CAA8C;IAC9C,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACrB,wDAAwD;IACxD,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC,CAAC;IACrC,mFAAmF;IACnF,MAAM,EAAE,oBAAoB,CAAC;IAC7B,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,SAAS,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7D,oDAAoD;IACpD,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAyBpC"}