@astram/guard 0.23.0 → 0.24.0

package/dist/notifications/mariadb-notification-store.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `MariaDbNotificationStore` — the framework-default {@link NotificationStore} (notification-store
+ * SPEC §5A) over `<ns>_identity.user_notification` (identity migration 108), on guard's core pool
+ * (`<ns>_core`, DML on `<ns>_identity`). Database names are resolved at construction, never per
+ * request; every statement is parameterized.
+ *
+ * Tenant wall (core 50 #4, #7; Shield #4): every per-user statement filters `un_user_uuid = ?
+ * AND un_tenant_id = ?`, including the post-insert count. `purge` is the one statement that is
+ * not per-user: it is the retention sweep over the whole table, bounded by `LIMIT`.
+ *
+ * `insertMany` is ONE multi-row `INSERT … ON DUPLICATE KEY UPDATE un_dedupe_key = un_dedupe_key`:
+ * a repeated `(user, tenant, dedupe key)` is a no-op on `uq_un_dedupe`; never `INSERT IGNORE`
+ * (that would also hide FK and data errors). The inserted count is NOT read from `affectedRows`:
+ * the `mariadb` driver connects with `CLIENT_FOUND_ROWS` by default (`foundRows` defaults to true,
+ * `lib/config/connection-options.js`), so an ODKU row left unchanged reports 1, the same as an
+ * insert. Instead the store counts its own freshly generated `un_uuid`s right after the insert, on
+ * the same `query` (the caller's transaction when given, so it sees its own uncommitted rows).
+ */
+import type { Pool } from 'mariadb';
+import { type FrameworkSchemaNames } from '../config/framework-schema-names.js';
+import { type NotificationCategory, type NotificationInsert, type NotificationListQuery, type NotificationListResult, type NotificationRetentionPolicy, type NotificationStore, type NotificationUnreadCounts, type NotificationWriteOptions } from './ports.js';
+/** Rows per `insertMany` statement (the `post` recipient cap, SPEC §10). */
+export declare const NOTIFICATION_INSERT_MAX_ROWS = 1000;
+export declare class MariaDbNotificationStore implements NotificationStore {
+    private readonly pool;
+    /** `<identity>`.`user_notification`, resolved at construction. */
+    private readonly table;
+    constructor(pool: Pick<Pool, 'query'>, 
+    /** Framework database names; absent ⇒ resolved from `SHIELD_DB_NAMESPACE` here, once. */
+    schemas?: FrameworkSchemaNames);
+    list(userId: string, tenantId: string, query: NotificationListQuery): Promise<NotificationListResult>;
+    countUnread(userId: string, tenantId: string): Promise<NotificationUnreadCounts>;
+    markRead(userId: string, tenantId: string, uuid: string, nowMs: number): Promise<boolean>;
+    markAllRead(userId: string, tenantId: string, category: NotificationCategory | undefined, nowMs: number): Promise<number>;
+    insertMany(rows: readonly NotificationInsert[], opts?: NotificationWriteOptions): Promise<number>;
+    purge(nowMs: number, policy: NotificationRetentionPolicy, maxRows: number): Promise<number>;
+}
+//# sourceMappingURL=mariadb-notification-store.d.ts.map

package/dist/notifications/mariadb-notification-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mariadb-notification-store.d.ts","sourceRoot":"","sources":["../../src/notifications/mariadb-notification-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAE3B,KAAK,2BAA2B,EAEhC,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAC9B,MAAM,YAAY,CAAC;AAIpB,4EAA4E;AAC5E,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAgDjD,qBAAa,wBAAyB,YAAW,iBAAiB;IAK9D,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJvB,kEAAkE;IAClE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAGZ,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC;IAC1C,yFAAyF;IACzF,OAAO,CAAC,EAAE,oBAAoB;IAQ1B,IAAI,CACR,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,sBAAsB,CAAC;IA2B5B,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAchF,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBzF,WAAW,CACf,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,oBAAoB,GAAG,SAAS,EAC1C,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC;IAWZ,UAAU,CACd,IAAI,EAAE,SAAS,kBAAkB,EAAE,EACnC,IAAI,GAAE,wBAA6B,GAClC,OAAO,CAAC,MAAM,CAAC;IAuDZ,KAAK,CACT,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,2BAA2B,EACnC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC;CAiBnB"}

package/dist/notifications/mariadb-notification-store.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MariaDbNotificationStore = exports.NOTIFICATION_INSERT_MAX_ROWS = void 0;
+const framework_schema_names_js_1 = require("../config/framework-schema-names.js");
+const ports_js_1 = require("./ports.js");
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Rows per `insertMany` statement (the `post` recipient cap, SPEC §10). */
+exports.NOTIFICATION_INSERT_MAX_ROWS = 1000;
+const SELECT_COLUMNS = 'un_uuid, un_category, un_kind, un_title, un_body, un_link, un_created_at_ms, un_read_at_ms';
+function isCategory(v) {
+    return ports_js_1.NOTIFICATION_CATEGORIES.includes(v);
+}
+/** BIGINT columns may arrive as bigint; the epoch-ms range fits a safe integer. */
+const toRow = (r) => ({
+    uuid: String(r.un_uuid),
+    // The column carries a CHECK constraint; an unexpected value is still never passed on raw.
+    category: isCategory(r.un_category) ? r.un_category : 'personal',
+    kind: r.un_kind,
+    title: r.un_title,
+    body: r.un_body ?? null,
+    link: r.un_link ?? null,
+    createdAtMs: Number(r.un_created_at_ms),
+    readAtMs: r.un_read_at_ms == null ? null : Number(r.un_read_at_ms),
+});
+function affected(res) {
+    return Number(res?.affectedRows ?? 0);
+}
+function countOf(rows) {
+    const first = Array.isArray(rows) ? rows[0] : undefined;
+    return Number(first?.c ?? 0);
+}
+function assertPositiveInteger(name, v, max) {
+    if (!Number.isSafeInteger(v) || v < 1 || (max !== undefined && v > max)) {
+        throw new RangeError(`MariaDbNotificationStore: ${name} is out of range`);
+    }
+}
+class MariaDbNotificationStore {
+    pool;
+    /** `<identity>`.`user_notification`, resolved at construction. */
+    table;
+    constructor(pool, 
+    /** Framework database names; absent ⇒ resolved from `SHIELD_DB_NAMESPACE` here, once. */
+    schemas) {
+        this.pool = pool;
+        this.table = (0, framework_schema_names_js_1.qualifiedTableName)((0, framework_schema_names_js_1.schemaNamesAtConstruction)(schemas).identity, 'user_notification');
+    }
+    async list(userId, tenantId, query) {
+        assertPositiveInteger('page', query.page);
+        assertPositiveInteger('limit', query.limit, 100);
+        const where = ['un_user_uuid = ?', 'un_tenant_id = ?'];
+        const params = [userId, tenantId];
+        if (query.category !== undefined) {
+            where.push('un_category = ?');
+            params.push(query.category);
+        }
+        if (query.unreadOnly)
+            where.push('un_read_at_ms IS NULL');
+        const clause = where.join(' AND ');
+        const total = countOf(await this.pool.query(`SELECT COUNT(*) AS c FROM ${this.table} WHERE ${clause}`, params));
+        if (total === 0)
+            return { total: 0, rows: [] };
+        const offset = (query.page - 1) * query.limit;
+        if (!Number.isSafeInteger(offset)) {
+            throw new RangeError('MariaDbNotificationStore: page is out of range');
+        }
+        const rows = (await this.pool.query(`SELECT ${SELECT_COLUMNS} FROM ${this.table} WHERE ${clause}
+        ORDER BY un_created_at_ms DESC, un_uuid DESC LIMIT ? OFFSET ?`, [...params, query.limit, offset]));
+        return { total, rows: rows.map(toRow) };
+    }
+    async countUnread(userId, tenantId) {
+        const rows = (await this.pool.query(`SELECT un_category, COUNT(*) AS c FROM ${this.table}
+        WHERE un_user_uuid = ? AND un_tenant_id = ? AND un_read_at_ms IS NULL
+        GROUP BY un_category`, [userId, tenantId]));
+        const counts = { announcement: 0, personal: 0 };
+        for (const r of rows) {
+            if (isCategory(r.un_category))
+                counts[r.un_category] = Number(r.c);
+        }
+        return counts;
+    }
+    async markRead(userId, tenantId, uuid, nowMs) {
+        const res = await this.pool.query(`UPDATE ${this.table} SET un_read_at_ms = ?
+        WHERE un_uuid = ? AND un_user_uuid = ? AND un_tenant_id = ? AND un_read_at_ms IS NULL`, [nowMs, uuid, userId, tenantId]);
+        if (affected(res) > 0)
+            return true;
+        // Already read (the first read time is kept) or not this caller's notice in this tenant.
+        const rows = (await this.pool.query(`SELECT 1 AS found FROM ${this.table}
+        WHERE un_uuid = ? AND un_user_uuid = ? AND un_tenant_id = ? LIMIT 1`, [uuid, userId, tenantId]));
+        return rows.length > 0;
+    }
+    async markAllRead(userId, tenantId, category, nowMs) {
+        const params = [nowMs, userId, tenantId];
+        let sql = `UPDATE ${this.table} SET un_read_at_ms = ?
+        WHERE un_user_uuid = ? AND un_tenant_id = ? AND un_read_at_ms IS NULL`;
+        if (category !== undefined) {
+            sql += ' AND un_category = ?';
+            params.push(category);
+        }
+        return affected(await this.pool.query(sql, params));
+    }
+    async insertMany(rows, opts = {}) {
+        if (rows.length === 0)
+            return 0;
+        if (rows.length > exports.NOTIFICATION_INSERT_MAX_ROWS) {
+            throw new RangeError('MariaDbNotificationStore: too many rows for one insert');
+        }
+        const run = opts.query ?? ((sql, params) => this.pool.query(sql, params));
+        const params = [];
+        for (const r of rows) {
+            params.push(r.uuid, r.tenantId, r.userId, r.category, r.kind, r.title, r.body, r.link, r.dedupeKey, r.createdAtMs);
+        }
+        const values = rows.map(() => '(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL)').join(', ');
+        await run(`INSERT INTO ${this.table}
+         (un_uuid, un_tenant_id, un_user_uuid, un_category, un_kind, un_title, un_body, un_link,
+          un_dedupe_key, un_created_at_ms, un_read_at_ms)
+       VALUES ${values}
+       ON DUPLICATE KEY UPDATE un_dedupe_key = un_dedupe_key`, params);
+        // Count the rows that landed (see the file header: affectedRows cannot tell an ODKU no-op from
+        // an insert). Grouped by tenant so every statement stays tenant- and user-scoped.
+        const byTenant = new Map();
+        for (const r of rows) {
+            const group = byTenant.get(r.tenantId);
+            if (group)
+                group.push(r);
+            else
+                byTenant.set(r.tenantId, [r]);
+        }
+        let inserted = 0;
+        for (const [tenantId, group] of byTenant) {
+            const users = [...new Set(group.map((r) => r.userId))];
+            const marks = (n) => new Array(n).fill('?').join(', ');
+            inserted += countOf(await run(`SELECT COUNT(*) AS c FROM ${this.table}
+            WHERE un_tenant_id = ? AND un_user_uuid IN (${marks(users.length)})
+              AND un_uuid IN (${marks(group.length)})`, [tenantId, ...users, ...group.map((r) => r.uuid)]));
+        }
+        return inserted;
+    }
+    async purge(nowMs, policy, maxRows) {
+        assertPositiveInteger('maxRows', maxRows);
+        const readCutoff = nowMs - policy.readDays * DAY_MS;
+        const maxCutoff = nowMs - policy.maxDays * DAY_MS;
+        // `maxDays ≥ readDays` (loader rule) ⇒ maxCutoff ≤ readCutoff, so the leading range keeps the
+        // statement on `idx_un_created`: read notices older than the read retention, and every notice
+        // older than the max retention.
+        const lead = Math.max(readCutoff, maxCutoff);
+        return affected(await this.pool.query(`DELETE FROM ${this.table}
+          WHERE un_created_at_ms < ? AND (un_read_at_ms IS NOT NULL OR un_created_at_ms < ?)
+          ORDER BY un_created_at_ms LIMIT ?`, [lead, maxCutoff, maxRows]));
+    }
+}
+exports.MariaDbNotificationStore = MariaDbNotificationStore;

package/dist/notifications/notification-retention.job.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `NotificationRetentionJob` — deletes expired notices (notification-store SPEC §5E, §10, §11).
+ *
+ * Registered with `ShieldModule.forRoot({ auth: true })` beside the store, over guard's core pool
+ * `SHIELD_DB_POOL` (it does not own the pool: `ConnectionLifecycle` ends it in
+ * `onApplicationShutdown`, after this job stopped).
+ *
+ * - First pass {@link NOTIFICATION_RETENTION_FIRST_RUN_MS} after bootstrap, then one pass every
+ *   {@link NOTIFICATION_RETENTION_INTERVAL_MS} (hourly), scheduled only after the previous pass
+ *   settled, so passes never overlap.
+ * - One pass = one `purge` of at most {@link NOTIFICATION_RETENTION_BATCH} rows: read notices older
+ *   than `NOTIFICATION_READ_RETENTION_DAYS`, any notice older than `NOTIFICATION_MAX_RETENTION_DAYS`.
+ * - A failed pass is logged by error class only (never the driver message) and retried at the next
+ *   interval; nothing here throws into Nest, so it never blocks boot (a missing table, migration
+ *   108 not applied, is just a logged pass).
+ * - Every timer is `unref()`'d. `onModuleDestroy` (Nest `close()` step 1) clears the timer and
+ *   waits for a running pass. Off the request path (Shield #12).
+ */
+import { type OnApplicationBootstrap, type OnModuleDestroy } from '@nestjs/common';
+import type { NotificationRetentionPolicy, NotificationStore } from './ports.js';
+export declare const NOTIFICATION_RETENTION_FIRST_RUN_MS = 5000;
+export declare const NOTIFICATION_RETENTION_INTERVAL_MS: number;
+export declare const NOTIFICATION_RETENTION_BATCH = 5000;
+export interface NotificationRetentionLogger {
+    log(message: string): void;
+    error(message: string): void;
+}
+export interface NotificationRetentionJobOptions {
+    /** Default `Date.now`. */
+    readonly now?: () => number;
+    /** Default `new Logger('Shield')`. */
+    readonly logger?: NotificationRetentionLogger;
+}
+export declare class NotificationRetentionJob implements OnApplicationBootstrap, OnModuleDestroy {
+    private readonly store;
+    private readonly policy;
+    private readonly now;
+    private readonly logger;
+    private stopped;
+    private timer;
+    private inFlight;
+    constructor(store: Pick<NotificationStore, 'purge'>, policy: NotificationRetentionPolicy, options?: NotificationRetentionJobOptions);
+    onApplicationBootstrap(): void;
+    onModuleDestroy(): Promise<void>;
+    /**
+     * One retention pass; resolves to the deleted count, or `null` when the pass failed (logged).
+     * Exposed for tests and operators; the timer calls it hourly.
+     */
+    runOnce(): Promise<number | null>;
+    private schedule;
+}
+//# sourceMappingURL=notification-retention.job.d.ts.map

package/dist/notifications/notification-retention.job.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification-retention.job.d.ts","sourceRoot":"","sources":["../../src/notifications/notification-retention.job.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAGL,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,2BAA2B,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEjF,eAAO,MAAM,mCAAmC,OAAQ,CAAC;AACzD,eAAO,MAAM,kCAAkC,QAAiB,CAAC;AACjE,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAEjD,MAAM,WAAW,2BAA2B;IAC1C,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,+BAA+B;IAC9C,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,sCAAsC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,2BAA2B,CAAC;CAC/C;AAED,qBACa,wBAAyB,YAAW,sBAAsB,EAAE,eAAe;IAQpF,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IARzB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,QAAQ,CAA4B;gBAGzB,KAAK,EAAE,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC,EACvC,MAAM,EAAE,2BAA2B,EACpD,OAAO,GAAE,+BAAoC;IAM/C,sBAAsB,IAAI,IAAI;IAIxB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtC;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAavC,OAAO,CAAC,QAAQ;CAcjB"}

package/dist/notifications/notification-retention.job.js

@@ -0,0 +1,97 @@
+"use strict";
+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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotificationRetentionJob = exports.NOTIFICATION_RETENTION_BATCH = exports.NOTIFICATION_RETENTION_INTERVAL_MS = exports.NOTIFICATION_RETENTION_FIRST_RUN_MS = void 0;
+/**
+ * `NotificationRetentionJob` — deletes expired notices (notification-store SPEC §5E, §10, §11).
+ *
+ * Registered with `ShieldModule.forRoot({ auth: true })` beside the store, over guard's core pool
+ * `SHIELD_DB_POOL` (it does not own the pool: `ConnectionLifecycle` ends it in
+ * `onApplicationShutdown`, after this job stopped).
+ *
+ * - First pass {@link NOTIFICATION_RETENTION_FIRST_RUN_MS} after bootstrap, then one pass every
+ *   {@link NOTIFICATION_RETENTION_INTERVAL_MS} (hourly), scheduled only after the previous pass
+ *   settled, so passes never overlap.
+ * - One pass = one `purge` of at most {@link NOTIFICATION_RETENTION_BATCH} rows: read notices older
+ *   than `NOTIFICATION_READ_RETENTION_DAYS`, any notice older than `NOTIFICATION_MAX_RETENTION_DAYS`.
+ * - A failed pass is logged by error class only (never the driver message) and retried at the next
+ *   interval; nothing here throws into Nest, so it never blocks boot (a missing table, migration
+ *   108 not applied, is just a logged pass).
+ * - Every timer is `unref()`'d. `onModuleDestroy` (Nest `close()` step 1) clears the timer and
+ *   waits for a running pass. Off the request path (Shield #12).
+ */
+const common_1 = require("@nestjs/common");
+const audit_chain_sealer_js_1 = require("../audit/audit-chain-sealer.js");
+exports.NOTIFICATION_RETENTION_FIRST_RUN_MS = 5_000;
+exports.NOTIFICATION_RETENTION_INTERVAL_MS = 60 * 60 * 1000;
+exports.NOTIFICATION_RETENTION_BATCH = 5000;
+let NotificationRetentionJob = class NotificationRetentionJob {
+    store;
+    policy;
+    now;
+    logger;
+    stopped = false;
+    timer;
+    inFlight;
+    constructor(store, policy, options = {}) {
+        this.store = store;
+        this.policy = policy;
+        this.now = options.now ?? Date.now;
+        this.logger = options.logger ?? new common_1.Logger('Shield');
+    }
+    onApplicationBootstrap() {
+        this.schedule(exports.NOTIFICATION_RETENTION_FIRST_RUN_MS);
+    }
+    async onModuleDestroy() {
+        this.stopped = true;
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        await this.inFlight; // never rejects (runOnce catches)
+    }
+    /**
+     * One retention pass; resolves to the deleted count, or `null` when the pass failed (logged).
+     * Exposed for tests and operators; the timer calls it hourly.
+     */
+    async runOnce() {
+        try {
+            const deleted = await this.store.purge(this.now(), this.policy, exports.NOTIFICATION_RETENTION_BATCH);
+            if (deleted > 0)
+                this.logger.log(`[notifications] retention removed ${deleted} notices`);
+            return deleted;
+        }
+        catch (err) {
+            this.logger.error(`[notifications] retention pass failed (${(0, audit_chain_sealer_js_1.auditSealErrorClass)(err)}); retried next hour`);
+            return null;
+        }
+    }
+    schedule(delayMs) {
+        if (this.stopped || this.timer !== undefined)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            if (this.stopped)
+                return;
+            this.inFlight = this.runOnce()
+                .then(() => undefined)
+                .finally(() => {
+                this.inFlight = undefined;
+                this.schedule(exports.NOTIFICATION_RETENTION_INTERVAL_MS);
+            });
+        }, delayMs);
+        this.timer.unref();
+    }
+};
+exports.NotificationRetentionJob = NotificationRetentionJob;
+exports.NotificationRetentionJob = NotificationRetentionJob = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [Object, Object, Object])
+], NotificationRetentionJob);

package/dist/notifications/notification.service.d.ts

@@ -0,0 +1,68 @@
+import type { Pool } from 'mariadb';
+import { type FrameworkSchemaNames } from '../config/framework-schema-names.js';
+import { type NotificationCategory, type NotificationKindRegistration, type NotificationStore, type NotificationWriteOptions } from './ports.js';
+/** SPEC §10 limits. */
+export declare const NOTIFICATION_TITLE_MAX = 160;
+export declare const NOTIFICATION_BODY_MAX = 1000;
+export declare const NOTIFICATION_LINK_MAX = 512;
+export declare const NOTIFICATION_RECIPIENTS_MAX = 1000;
+/** The prefix reserved for the framework's own kinds. */
+export declare const FRAMEWORK_KIND_PREFIX = "shield.";
+/** The framework's own kinds. Step 2 registers none (step 3 adds `shield.access_changed`). */
+export declare const FRAMEWORK_NOTIFICATION_KINDS: readonly NotificationKindRegistration[];
+export interface NotificationPostInput {
+    /** The company the notice belongs to; recipients must be active members of it. */
+    readonly tenantId: string;
+    /** User uuids, 1–1000. Service accounts are not users and never receive notices. */
+    readonly recipients: readonly string[];
+    readonly kind: string;
+    readonly title: string;
+    readonly body?: string | null;
+    /** App-relative path only (`/…`, not `//`, no `\`, no control characters). */
+    readonly link?: string | null;
+    /** Idempotency key per recipient and tenant, 1–64 of `[A-Za-z0-9._:-]`. */
+    readonly dedupeKey?: string | null;
+}
+export interface NotificationPostResult {
+    readonly created: number;
+    readonly skipped: number;
+}
+/** Validated kind registry: kind ⇒ category. */
+export type NotificationKindRegistry = ReadonlyMap<string, NotificationCategory>;
+/**
+ * Build the kind registry from the app's `notificationKinds` (validated at boot, SPEC §5C) and the
+ * framework's own kinds. Refuses a malformed or over-long kind, an unknown category, a duplicate,
+ * and an app kind under the reserved `shield.` prefix; each error names the kind.
+ */
+export declare function resolveNotificationKinds(appKinds: readonly NotificationKindRegistration[] | undefined, frameworkKinds?: readonly NotificationKindRegistration[]): NotificationKindRegistry;
+/** Logs counts only (Nest `Logger` shape). */
+export interface NotificationServiceLogger {
+    debug(message: string): void;
+}
+export interface NotificationServiceOptions {
+    /** Default `Date.now`. */
+    readonly now?: () => number;
+    /** Default `new Logger('Shield')`. */
+    readonly logger?: NotificationServiceLogger;
+}
+export declare class NotificationService {
+    private readonly store;
+    /** Guard's core pool: the recipient filter runs here when no caller `query` is given. */
+    private readonly pool;
+    private readonly kinds;
+    private readonly usersTable;
+    private readonly membershipTable;
+    private readonly now;
+    private readonly logger;
+    constructor(store: NotificationStore, 
+    /** Guard's core pool: the recipient filter runs here when no caller `query` is given. */
+    pool: Pick<Pool, 'query'>, kinds: NotificationKindRegistry, 
+    /** Framework database names; absent ⇒ resolved from `SHIELD_DB_NAMESPACE` here, once. */
+    schemas?: FrameworkSchemaNames, options?: NotificationServiceOptions);
+    /** Whether `kind` is registered (framework or app). */
+    hasKind(kind: string): boolean;
+    post(input: NotificationPostInput, opts?: NotificationWriteOptions): Promise<NotificationPostResult>;
+    /** ONE parameterized SELECT: active users with an active membership in `tenantId`. */
+    private activeRecipients;
+}
+//# sourceMappingURL=notification.service.d.ts.map

package/dist/notifications/notification.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification.service.d.ts","sourceRoot":"","sources":["../../src/notifications/notification.service.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAOL,KAAK,oBAAoB,EAEzB,KAAK,4BAA4B,EAEjC,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC9B,MAAM,YAAY,CAAC;AAEpB,uBAAuB;AACvB,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAC1C,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAOhD,yDAAyD;AACzD,eAAO,MAAM,qBAAqB,YAAY,CAAC;AAE/C,8FAA8F;AAC9F,eAAO,MAAM,4BAA4B,EAAE,SAAS,4BAA4B,EAAO,CAAC;AAExF,MAAM,WAAW,qBAAqB;IACpC,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,gDAAgD;AAChD,MAAM,MAAM,wBAAwB,GAAG,WAAW,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AAWjF;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,4BAA4B,EAAE,GAAG,SAAS,EAC7D,cAAc,GAAE,SAAS,4BAA4B,EAAiC,GACrF,wBAAwB,CAqC1B;AAED,8CAA8C;AAC9C,MAAM,WAAW,yBAAyB;IACxC,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,0BAA0B;IACzC,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,sCAAsC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,yBAAyB,CAAC;CAC7C;AAED,qBAAa,mBAAmB;IAO5B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,yFAAyF;IACzF,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IATxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;gBAGhC,KAAK,EAAE,iBAAiB;IACzC,yFAAyF;IACxE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,EACzB,KAAK,EAAE,wBAAwB;IAChD,yFAAyF;IACzF,OAAO,CAAC,EAAE,oBAAoB,EAC9B,OAAO,GAAE,0BAA+B;IAS1C,uDAAuD;IACvD,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIxB,IAAI,CACR,KAAK,EAAE,qBAAqB,EAC5B,IAAI,GAAE,wBAA6B,GAClC,OAAO,CAAC,sBAAsB,CAAC;IA6ClC,sFAAsF;YACxE,gBAAgB;CAwB/B"}