@astram/identity 0.19.0 → 0.21.0

package/dist/features/authz/access-change-notifier.d.ts

@@ -0,0 +1,109 @@
+import type { ModuleRegistry, Principal } from '@astram/core';
+import { type NotificationQuery, type NotificationPostInput, type NotificationPostResult } from '@astram/guard';
+import type { IdentitySchemaNames } from '../../schema.js';
+/** DI token: the module's one notifier (attached to `SHIELD_NOTIFICATIONS` when guard has it). */
+export declare const ACCESS_CHANGE_NOTIFIER: unique symbol;
+export declare const ACCESS_CHANGED_KIND = "shield.access_changed";
+export declare const ACCESS_CHANGED_TITLE = "Your access changed";
+export declare const ACCESS_NOTICE_SAVEPOINT = "shield_access_notice";
+/** SPEC §10 limits (mirror guard's `NOTIFICATION_BODY_MAX` / `NOTIFICATION_RECIPIENTS_MAX`). */
+export declare const ACCESS_NOTICE_LABELS_PER_LINE = 10;
+export declare const ACCESS_NOTICE_BODY_MAX = 1000;
+export declare const ACCESS_NOTICE_RECIPIENTS_MAX = 1000;
+/** The part of guard's `NotificationService` the notifier uses. */
+export interface AccessNoticePoster {
+    post(input: NotificationPostInput, opts?: {
+        query?: NotificationQuery;
+    }): Promise<NotificationPostResult>;
+}
+/** One user in one tenant (server-derived; never request input). */
+export interface AccessPair {
+    readonly userId: string;
+    readonly tenantId: string;
+}
+/** A pair's effective exact keys at snapshot time. */
+export interface AccessEntry extends AccessPair {
+    readonly keys: ReadonlySet<string>;
+}
+/** A successful snapshot, keyed by `pairKey(pair)`. */
+export interface AccessSnapshot {
+    readonly ok: true;
+    readonly entries: ReadonlyMap<string, AccessEntry>;
+}
+/** A holder or snapshot read failed: carries counts and the error class only. */
+export interface AccessReadFailure {
+    readonly ok: false;
+    /** Pairs the read was for (`null` when unknown, e.g. the holder read itself failed). */
+    readonly pairCount: number | null;
+    readonly errorClass: string;
+}
+export interface AccessNoticeResult {
+    readonly created: number;
+    readonly dropped: number;
+}
+export interface AccessChangeNotifierLogger {
+    warn(message: string): void;
+}
+/**
+ * The notice failed and its savepoint could not be rolled back: the caller's transaction is gone,
+ * so the caller fails and rolls back like any database error (SPEC v3 §5A). The message holds no
+ * value; the original error rides on `cause`.
+ */
+export declare class AccessNoticeTransactionLostError extends Error {
+    constructor(cause: unknown);
+}
+/** Locale-independent code-point order (JS `<` compares UTF-16 code units). */
+export declare function compareCodePoints(a: string, b: string): number;
+/**
+ * SPEC §10 body: sorted labels, ≤ 10 per line, then labels folded into the `and N more` tail
+ * (from the line showing more, ties from the longer line) while the body exceeds 1000 characters.
+ * `null` when nothing was gained or lost.
+ */
+export declare function accessNoticeBody(gained: readonly string[], lost: readonly string[]): string | null;
+/**
+ * The step-1 generated label of a key with no catalog label (G-027 step 1 SPEC §10), computed as
+ * guard's catalog reconciler does (`catalog-reconciler.ts` `generatedText`, not exported): engine
+ * `permissionTextOf` over a one-action declaration, type label from the registry descriptor when
+ * it differs from the typeKey. An unresolvable key gets `"<Type>: <action>"`, never the raw key.
+ */
+export declare function generatedPermissionLabel(registry: ModuleRegistry, key: string): string;
+export declare class AccessChangeNotifier {
+    private readonly registry;
+    /** Injectable clock (epoch-ms) for the posting window, bound as `?` integers. */
+    private readonly now;
+    private service;
+    private readonly logger;
+    private readonly app;
+    private readonly authz;
+    constructor(registry: ModuleRegistry, schemas: IdentitySchemaNames, logger?: AccessChangeNotifierLogger, 
+    /** Injectable clock (epoch-ms) for the posting window, bound as `?` integers. */
+    now?: () => number);
+    /** Bind guard's `NotificationService` (`null` ⇒ every method is a no-op). */
+    attach(service: AccessNoticePoster | null): void;
+    /** Whether a change by `actor` would be notified (service attached, not the org bootstrap). */
+    enabledFor(actor: Principal): boolean;
+    /**
+     * Users holding `roleUuid` through an in-effect posting of their active membership, with
+     * `u_status = 'active'` (the `readRoleIdsForTenant` predicates), per tenant. Never throws.
+     */
+    holdersOfRole(query: NotificationQuery, roleUuid: string): Promise<readonly AccessPair[] | AccessReadFailure>;
+    /**
+     * Effective keys per pair on the caller's open transaction (sees its uncommitted rows): one
+     * roles query for all pairs (chunked at 500), one `role_permission` query for all roles, then
+     * `expandGrantKeys`. A pair with no roles has an empty set. Never throws.
+     */
+    snapshot(query: NotificationQuery, pairs: readonly AccessPair[] | AccessReadFailure): Promise<AccessSnapshot | AccessReadFailure>;
+    /**
+     * Diff `before` and `after` per pair and post one notice to each changed user, under the
+     * `shield_access_notice` savepoint on `query`. Never throws. `dropped` = the pairs that would
+     * have been notified (on a snapshot failure: the pairs the failed read was for, when known).
+     */
+    notify(query: NotificationQuery, actor: Principal, before: AccessSnapshot | AccessReadFailure, after: AccessSnapshot | AccessReadFailure): Promise<AccessNoticeResult>;
+    /** One parameterized catalog read; a missing, blank or raw-key label ⇒ the generated label. */
+    private labelsOf;
+    private isBootstrap;
+    private warnDropped;
+    private rowsOf;
+    private pairsOf;
+}
+//# sourceMappingURL=access-change-notifier.d.ts.map

package/dist/features/authz/access-change-notifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-change-notifier.d.ts","sourceRoot":"","sources":["../../../src/features/authz/access-change-notifier.ts"],"names":[],"mappings":"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"}

package/dist/features/authz/access-change-notifier.js

@@ -0,0 +1,421 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccessChangeNotifier = exports.AccessNoticeTransactionLostError = exports.ACCESS_NOTICE_RECIPIENTS_MAX = exports.ACCESS_NOTICE_BODY_MAX = exports.ACCESS_NOTICE_LABELS_PER_LINE = exports.ACCESS_NOTICE_SAVEPOINT = exports.ACCESS_CHANGED_TITLE = exports.ACCESS_CHANGED_KIND = exports.ACCESS_CHANGE_NOTIFIER = void 0;
+exports.compareCodePoints = compareCodePoints;
+exports.accessNoticeBody = accessNoticeBody;
+exports.generatedPermissionLabel = generatedPermissionLabel;
+/**
+ * `AccessChangeNotifier` — G-027 step 3 (notifying-user SPEC §5A, §10, §11): one personal
+ * `shield.access_changed` notice to each user whose EFFECTIVE permission keys changed, posted on
+ * the change's own transaction `query` so a rolled-back change sends nothing.
+ *
+ * Effective keys follow `readRoleIdsForTenant` exactly (active membership `cm_is_active = 1`,
+ * `u_status = 'active'`, in-effect posting window bound as epoch-ms integers) → `role_permission`
+ * → `expandGrantKeys` against the registry's `listActions()`: a notice never claims access
+ * `decide()` would not give. Holders come from memberships only, so service accounts never appear.
+ *
+ * Failure model (SPEC v3 §5A): a notice failure never fails the change, with ONE exception.
+ * - `holdersOfRole` / `snapshot` never throw: they return an {@link AccessReadFailure} on a read
+ *   error; `snapshot` passes a failure through. `notify` given a failure on either side logs and drops.
+ * - `notify` runs under `SAVEPOINT shield_access_notice` (label read + every `post`): any error ⇒
+ *   `ROLLBACK TO SAVEPOINT`, one `[notifications] access-change notices dropped` warning with
+ *   counts and the error class only (never SQL, values or labels), `{ created: 0, dropped }`.
+ *   The caller's change continues and commits.
+ * - Exception: when that `ROLLBACK TO SAVEPOINT` itself fails, the database already ended the
+ *   caller's transaction (e.g. a deadlock on the notice insert), so `notify` throws
+ *   {@link AccessNoticeTransactionLostError} and the caller must fail and roll back: never catch it
+ *   to continue, or the audit row and later writes would autocommit without the change.
+ * - Without an attached `NotificationService` (guard `auth: false`) every method is a no-op with
+ *   no SQL; an actor bound to `shield:org-bootstrap` gets `notify` ⇒ `{ 0, 0 }` with no SQL
+ *   (`enabledFor(actor)` lets a caller skip its snapshots too).
+ *
+ * Text (SPEC §10): title `Your access changed`; `You can now: a, b.` / `You can no longer: c.`
+ * joined by `\n`; labels sorted by code point, at most 10 per line then `, and N more.`, folded
+ * further while the body would exceed 1000 characters. No actor, other user, role, company, raw
+ * key or uuid. Users of one tenant with the same text share one `post` (≤ 1000 recipients).
+ */
+const common_1 = require("@nestjs/common");
+const engine_1 = require("@astram/engine");
+const guard_1 = require("@astram/guard");
+const org_bootstrap_manifest_js_1 = require("../org-bootstrap/org-bootstrap.manifest.js");
+const db_permission_facts_adapter_js_1 = require("./db-permission-facts.adapter.js");
+/** DI token: the module's one notifier (attached to `SHIELD_NOTIFICATIONS` when guard has it). */
+exports.ACCESS_CHANGE_NOTIFIER = Symbol('IDENTITY_ACCESS_CHANGE_NOTIFIER');
+exports.ACCESS_CHANGED_KIND = 'shield.access_changed';
+exports.ACCESS_CHANGED_TITLE = 'Your access changed';
+exports.ACCESS_NOTICE_SAVEPOINT = 'shield_access_notice';
+/** SPEC §10 limits (mirror guard's `NOTIFICATION_BODY_MAX` / `NOTIFICATION_RECIPIENTS_MAX`). */
+exports.ACCESS_NOTICE_LABELS_PER_LINE = 10;
+exports.ACCESS_NOTICE_BODY_MAX = 1000;
+exports.ACCESS_NOTICE_RECIPIENTS_MAX = 1000;
+/** Pairs per batched roles query (2 placeholders each). */
+const PAIR_CHUNK = 500;
+/** Values per `IN (…)` list (roles, permission keys); review F-2. */
+const IN_CHUNK = 1000;
+/** `items` in slices of at most `size`. */
+function chunksOf(items, size) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size)
+        out.push(items.slice(i, i + size));
+    return out;
+}
+/**
+ * The notice failed and its savepoint could not be rolled back: the caller's transaction is gone,
+ * so the caller fails and rolls back like any database error (SPEC v3 §5A). The message holds no
+ * value; the original error rides on `cause`.
+ */
+class AccessNoticeTransactionLostError extends Error {
+    constructor(cause) {
+        super('access-change notice: transaction lost', { cause });
+        this.name = 'AccessNoticeTransactionLostError';
+    }
+}
+exports.AccessNoticeTransactionLostError = AccessNoticeTransactionLostError;
+/** The class name of an error, never its message (core 50 #10). */
+function errorClassOf(err) {
+    if (err instanceof Error)
+        return err.constructor?.name || 'Error';
+    return typeof err;
+}
+function pairKey(p) {
+    return `${p.tenantId}|${p.userId}`;
+}
+/** Locale-independent code-point order (JS `<` compares UTF-16 code units). */
+function compareCodePoints(a, b) {
+    const x = Array.from(a);
+    const y = Array.from(b);
+    const n = Math.min(x.length, y.length);
+    for (let i = 0; i < n; i++) {
+        const d = x[i].codePointAt(0) - y[i].codePointAt(0);
+        if (d !== 0)
+            return d;
+    }
+    return x.length - y.length;
+}
+function codePointLength(s) {
+    return Array.from(s).length;
+}
+// C0, DEL, C1 and the Unicode line/paragraph separators (review F-4): a label is one line of text.
+// Built from a string so no raw separator character sits in the source.
+const CONTROL_CHARS = new RegExp(`[\u0000-\u001f\u007f-\u009f${String.fromCharCode(0x2028, 0x2029)}]`, 'g');
+function line(prefix, labels, shown) {
+    const rest = labels.length - shown;
+    const head = labels.slice(0, shown).join(', ');
+    if (rest <= 0)
+        return `${prefix}: ${head}.`;
+    return shown === 0 ? `${prefix}: ${rest} more.` : `${prefix}: ${head}, and ${rest} more.`;
+}
+/**
+ * SPEC §10 body: sorted labels, ≤ 10 per line, then labels folded into the `and N more` tail
+ * (from the line showing more, ties from the longer line) while the body exceeds 1000 characters.
+ * `null` when nothing was gained or lost.
+ */
+function accessNoticeBody(gained, lost) {
+    const g = [...gained].sort(compareCodePoints);
+    const l = [...lost].sort(compareCodePoints);
+    if (g.length === 0 && l.length === 0)
+        return null;
+    let sg = Math.min(g.length, exports.ACCESS_NOTICE_LABELS_PER_LINE);
+    let sl = Math.min(l.length, exports.ACCESS_NOTICE_LABELS_PER_LINE);
+    const render = () => [
+        ...(g.length > 0 ? [line('You can now', g, sg)] : []),
+        ...(l.length > 0 ? [line('You can no longer', l, sl)] : []),
+    ].join('\n');
+    let body = render();
+    while (codePointLength(body) > exports.ACCESS_NOTICE_BODY_MAX && sg + sl > 0) {
+        const gl = g.length > 0 ? codePointLength(line('You can now', g, sg)) : 0;
+        const ll = l.length > 0 ? codePointLength(line('You can no longer', l, sl)) : 0;
+        if (sg > sl || (sg === sl && gl >= ll))
+            sg -= 1;
+        else
+            sl -= 1;
+        body = render();
+    }
+    return body;
+}
+function humanize(s) {
+    const spaced = s.replace(/_/g, ' ');
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+/**
+ * The step-1 generated label of a key with no catalog label (G-027 step 1 SPEC §10), computed as
+ * guard's catalog reconciler does (`catalog-reconciler.ts` `generatedText`, not exported): engine
+ * `permissionTextOf` over a one-action declaration, type label from the registry descriptor when
+ * it differs from the typeKey. An unresolvable key gets `"<Type>: <action>"`, never the raw key.
+ */
+function generatedPermissionLabel(registry, key) {
+    const registered = registry.resolveByPermissionKey(key);
+    const parts = key.split(':');
+    const typeKey = registered?.action.typeKey ?? parts[1] ?? 'permission';
+    const actionKey = registered?.action.actionKey ?? parts[2] ?? 'use';
+    if (registered !== undefined) {
+        const descriptorLabel = registry.resolveObjectType(typeKey)?.label;
+        const label = descriptorLabel && descriptorLabel !== typeKey ? descriptorLabel : undefined;
+        const isCrud = guard_1.IDENTITY_ACTIONS.includes(actionKey);
+        try {
+            const [t] = (0, engine_1.permissionTextOf)({
+                typeKey,
+                ...(label !== undefined ? { label } : {}),
+                ...(isCrud ? {} : { crudActions: false, actions: [actionKey] }),
+            }).filter((p) => p.action === actionKey);
+            if (t)
+                return t.label;
+        }
+        catch (err) {
+            if (!(err instanceof engine_1.RegistrationError))
+                throw err;
+        }
+    }
+    return `${humanize(typeKey)}: ${actionKey.replace(/_/g, ' ')}`;
+}
+class AccessChangeNotifier {
+    registry;
+    now;
+    service = null;
+    logger;
+    app;
+    authz;
+    constructor(registry, schemas, logger, 
+    /** Injectable clock (epoch-ms) for the posting window, bound as `?` integers. */
+    now = Date.now) {
+        this.registry = registry;
+        this.now = now;
+        this.logger = logger ?? new common_1.Logger('IdentityAccessChangeNotifier');
+        this.app = `\`${schemas.app}\``;
+        this.authz = `\`${schemas.authz}\``;
+    }
+    /** Bind guard's `NotificationService` (`null` ⇒ every method is a no-op). */
+    attach(service) {
+        this.service = service;
+    }
+    /** Whether a change by `actor` would be notified (service attached, not the org bootstrap). */
+    enabledFor(actor) {
+        return this.service !== null && !this.isBootstrap(actor);
+    }
+    /**
+     * Users holding `roleUuid` through an in-effect posting of their active membership, with
+     * `u_status = 'active'` (the `readRoleIdsForTenant` predicates), per tenant. Never throws.
+     */
+    async holdersOfRole(query, roleUuid) {
+        if (this.service === null)
+            return [];
+        try {
+            const nowMs = this.now();
+            const rows = await query(`SELECT DISTINCT cm.cm_user_uuid AS user_id, cm.cm_company_uuid AS tenant_id
+           FROM ${this.app}.\`company_membership\` cm
+           JOIN ${this.app}.\`users\` u ON u.u_uuid = cm.cm_user_uuid AND u.u_status = 'active'
+           JOIN ${this.app}.\`membership_posting\` mp ON mp.mp_membership_uuid = cm.cm_uuid
+          WHERE mp.mp_role_uuid = ? AND cm.cm_is_active = 1
+            AND (mp.mp_effective_from_ms IS NULL OR mp.mp_effective_from_ms <= ?)
+            AND (mp.mp_effective_until_ms IS NULL OR mp.mp_effective_until_ms > ?)`, [roleUuid, nowMs, nowMs]);
+            return this.pairsOf(rows);
+        }
+        catch (err) {
+            return { ok: false, pairCount: null, errorClass: errorClassOf(err) };
+        }
+    }
+    /**
+     * Effective keys per pair on the caller's open transaction (sees its uncommitted rows): one
+     * roles query for all pairs (chunked at 500), one `role_permission` query for all roles, then
+     * `expandGrantKeys`. A pair with no roles has an empty set. Never throws.
+     */
+    async snapshot(query, pairs) {
+        if (!Array.isArray(pairs))
+            return pairs;
+        const entries = new Map();
+        if (this.service === null)
+            return { ok: true, entries };
+        const wanted = new Map();
+        for (const p of pairs) {
+            const userId = (0, engine_1.canonicalUuid)(p.userId);
+            const tenantId = (0, engine_1.canonicalUuid)(p.tenantId);
+            if (userId === null || tenantId === null)
+                continue;
+            const pair = { userId, tenantId };
+            wanted.set(pairKey(pair), pair);
+        }
+        if (wanted.size === 0)
+            return { ok: true, entries };
+        try {
+            const nowMs = this.now();
+            const rolesByPair = new Map();
+            const all = [...wanted.values()];
+            for (let i = 0; i < all.length; i += PAIR_CHUNK) {
+                const chunk = all.slice(i, i + PAIR_CHUNK);
+                const where = chunk
+                    .map(() => '(cm.cm_user_uuid = ? AND cm.cm_company_uuid = ?)')
+                    .join(' OR ');
+                const rows = await query(`SELECT DISTINCT cm.cm_user_uuid AS user_id, cm.cm_company_uuid AS tenant_id,
+                  mp.mp_role_uuid AS role_uuid
+             FROM ${this.app}.\`company_membership\` cm
+             JOIN ${this.app}.\`users\` u ON u.u_uuid = cm.cm_user_uuid AND u.u_status = 'active'
+             JOIN ${this.app}.\`membership_posting\` mp ON mp.mp_membership_uuid = cm.cm_uuid
+            WHERE (${where}) AND cm.cm_is_active = 1
+              AND (mp.mp_effective_from_ms IS NULL OR mp.mp_effective_from_ms <= ?)
+              AND (mp.mp_effective_until_ms IS NULL OR mp.mp_effective_until_ms > ?)`, [...chunk.flatMap((p) => [p.userId, p.tenantId]), nowMs, nowMs]);
+                for (const r of this.rowsOf(rows)) {
+                    const userId = (0, engine_1.canonicalUuid)(r.user_id);
+                    const tenantId = (0, engine_1.canonicalUuid)(r.tenant_id);
+                    const role = (0, engine_1.canonicalUuid)(r.role_uuid);
+                    if (userId === null || tenantId === null || role === null)
+                        continue;
+                    const k = pairKey({ userId, tenantId });
+                    if (!wanted.has(k))
+                        continue;
+                    const set = rolesByPair.get(k) ?? new Set();
+                    set.add(role);
+                    rolesByPair.set(k, set);
+                }
+            }
+            const roles = [...new Set([...rolesByPair.values()].flatMap((s) => [...s]))];
+            const keysByRole = new Map();
+            for (const slice of chunksOf(roles, IN_CHUNK)) {
+                const rows = await query(`SELECT rp_role_uuid AS role_uuid, rp_perm_key FROM ${this.authz}.\`role_permission\`
+            WHERE rp_role_uuid IN (${slice.map(() => '?').join(', ')})`, slice);
+                for (const r of this.rowsOf(rows)) {
+                    const role = (0, engine_1.canonicalUuid)(r.role_uuid);
+                    if (role === null || typeof r.rp_perm_key !== 'string')
+                        continue;
+                    const list = keysByRole.get(role) ?? [];
+                    list.push(r.rp_perm_key);
+                    keysByRole.set(role, list);
+                }
+            }
+            const allKeys = this.registry.listActions().map((a) => a.permissionKey);
+            for (const [k, pair] of wanted) {
+                const raw = [...(rolesByPair.get(k) ?? [])].flatMap((role) => keysByRole.get(role) ?? []);
+                entries.set(k, { ...pair, keys: new Set((0, db_permission_facts_adapter_js_1.expandGrantKeys)(raw, allKeys)) });
+            }
+            return { ok: true, entries };
+        }
+        catch (err) {
+            return { ok: false, pairCount: wanted.size, errorClass: errorClassOf(err) };
+        }
+    }
+    /**
+     * Diff `before` and `after` per pair and post one notice to each changed user, under the
+     * `shield_access_notice` savepoint on `query`. Never throws. `dropped` = the pairs that would
+     * have been notified (on a snapshot failure: the pairs the failed read was for, when known).
+     */
+    async notify(query, actor, before, after) {
+        const service = this.service;
+        if (service === null || this.isBootstrap(actor))
+            return { created: 0, dropped: 0 };
+        if (!before.ok || !after.ok) {
+            const failure = (!before.ok ? before : after);
+            const known = [before, after].map((s) => (s.ok ? s.entries.size : (s.pairCount ?? 0)));
+            const dropped = Math.max(...known);
+            this.warnDropped(dropped, failure.errorClass);
+            return { created: 0, dropped };
+        }
+        const changes = [];
+        const keys = new Set([...before.entries.keys(), ...after.entries.keys()]);
+        for (const k of keys) {
+            const b = before.entries.get(k);
+            const a = after.entries.get(k);
+            const pair = (a ?? b);
+            const was = b?.keys ?? new Set();
+            const now = a?.keys ?? new Set();
+            const gained = [...now].filter((x) => !was.has(x));
+            const lost = [...was].filter((x) => !now.has(x));
+            if (gained.length > 0 || lost.length > 0) {
+                changes.push({ pair: { userId: pair.userId, tenantId: pair.tenantId }, gained, lost });
+            }
+        }
+        if (changes.length === 0)
+            return { created: 0, dropped: 0 };
+        try {
+            await query(`SAVEPOINT ${exports.ACCESS_NOTICE_SAVEPOINT}`);
+        }
+        catch (err) {
+            this.warnDropped(changes.length, errorClassOf(err));
+            return { created: 0, dropped: changes.length };
+        }
+        try {
+            const labels = await this.labelsOf(query, [
+                ...new Set(changes.flatMap((c) => [...c.gained, ...c.lost])),
+            ]);
+            // tenant + body ⇒ recipients (same text in the same tenant shares one post).
+            const groups = new Map();
+            for (const c of changes) {
+                const body = accessNoticeBody(c.gained.map((k) => labels.get(k)), c.lost.map((k) => labels.get(k)));
+                if (body === null)
+                    continue;
+                const g = `${c.pair.tenantId}\n${body}`;
+                const group = groups.get(g) ?? { tenantId: c.pair.tenantId, body, recipients: [] };
+                group.recipients.push(c.pair.userId);
+                groups.set(g, group);
+            }
+            let created = 0;
+            for (const group of groups.values()) {
+                for (let i = 0; i < group.recipients.length; i += exports.ACCESS_NOTICE_RECIPIENTS_MAX) {
+                    const res = await service.post({
+                        tenantId: group.tenantId,
+                        recipients: group.recipients.slice(i, i + exports.ACCESS_NOTICE_RECIPIENTS_MAX),
+                        kind: exports.ACCESS_CHANGED_KIND,
+                        title: exports.ACCESS_CHANGED_TITLE,
+                        body: group.body,
+                    }, { query });
+                    created += res.created;
+                }
+            }
+            await query(`RELEASE SAVEPOINT ${exports.ACCESS_NOTICE_SAVEPOINT}`);
+            return { created, dropped: 0 };
+        }
+        catch (err) {
+            try {
+                await query(`ROLLBACK TO SAVEPOINT ${exports.ACCESS_NOTICE_SAVEPOINT}`);
+            }
+            catch {
+                // The database already ended the caller's transaction (e.g. a deadlock rolled it back,
+                // savepoint included): its later writes would autocommit, so the change must fail (SPEC v3 §5A).
+                throw new AccessNoticeTransactionLostError(err);
+            }
+            this.warnDropped(changes.length, errorClassOf(err));
+            return { created: 0, dropped: changes.length };
+        }
+    }
+    /** One parameterized catalog read; a missing, blank or raw-key label ⇒ the generated label. */
+    async labelsOf(query, keys) {
+        const stored = new Map();
+        for (const slice of chunksOf(keys, IN_CHUNK)) {
+            const rows = await query(`SELECT perm_key, perm_label FROM ${this.authz}.\`permission\`
+          WHERE perm_key IN (${slice.map(() => '?').join(', ')})`, slice);
+            for (const r of this.rowsOf(rows)) {
+                if (typeof r.perm_key === 'string' && typeof r.perm_label === 'string') {
+                    stored.set(r.perm_key, r.perm_label);
+                }
+            }
+        }
+        const out = new Map();
+        for (const key of keys) {
+            const label = (stored.get(key) ?? '').replace(CONTROL_CHARS, ' ').trim();
+            out.set(key, label !== '' && label !== key ? label : generatedPermissionLabel(this.registry, key));
+        }
+        return out;
+    }
+    isBootstrap(actor) {
+        return (0, engine_1.operationOf)(actor)?.operationKey === org_bootstrap_manifest_js_1.ORG_BOOTSTRAP_OPERATION;
+    }
+    warnDropped(pairs, errorClass) {
+        this.logger.warn(`[notifications] access-change notices dropped: pairs=${pairs} cause=${errorClass}`);
+    }
+    rowsOf(rows) {
+        if (!Array.isArray(rows))
+            throw new TypeError('unexpected result');
+        return rows;
+    }
+    pairsOf(rows) {
+        const out = new Map();
+        for (const r of this.rowsOf(rows)) {
+            const userId = (0, engine_1.canonicalUuid)(r.user_id);
+            const tenantId = (0, engine_1.canonicalUuid)(r.tenant_id);
+            if (userId === null || tenantId === null)
+                continue;
+            const pair = { userId, tenantId };
+            out.set(pairKey(pair), pair);
+        }
+        return [...out.values()];
+    }
+}
+exports.AccessChangeNotifier = AccessChangeNotifier;

package/dist/features/authz/grant-admin.service.d.ts

@@ -4,6 +4,7 @@ import { type AuditPort } from '@astram/engine';
 import { PermissionVersionBumper } from './permission-version.bumper.js';
 import { AccessBundleStore } from './access-bundle-store.js';
 import { GrantCeiling } from './grant-ceiling.js';
+import type { AccessChangeNotifier } from './access-change-notifier.js';
 import { type IdentitySchemaNames } from '../../schema.js';
 /**
  * The caller's reachable subtree, threaded from `req.principal` (Task 4.2). It scopes the
@@ -65,6 +66,12 @@ export declare class GrantAdminService {
     private readonly ceiling?;
     private readonly audit?;
     private readonly schemas;
+    /**
+     * G-027 step 3 (notifying-user SPEC §5B, §5C): personal access-change notices on the grant's
+     * own transaction. OPTIONAL (absent ⇒ no notices, no extra reads); the identity module
+     * always wires it.
+     */
+    private readonly accessNotifier?;
     private readonly bundles;
     /**
      * @param ceiling  The ADR-0029 self-escalation ceiling ("only grant what you hold") plus the
@@ -76,7 +83,13 @@ export declare class GrantAdminService {
      *   connection, fail-closed. The identity module ALWAYS wires the engine `MariaDbAuditSink`.
      * @param schemas Resolved framework names (absent ⇒ resolved from the namespace, once, here).
      */
-    constructor(pool: Pool, bumper: PermissionVersionBumper, bundleStore?: AccessBundleStore, ceiling?: GrantCeiling | undefined, audit?: AuditPort | undefined, schemas?: IdentitySchemaNames);
+    constructor(pool: Pool, bumper: PermissionVersionBumper, bundleStore?: AccessBundleStore, ceiling?: GrantCeiling | undefined, audit?: AuditPort | undefined, schemas?: IdentitySchemaNames, 
+    /**
+     * G-027 step 3 (notifying-user SPEC §5B, §5C): personal access-change notices on the grant's
+     * own transaction. OPTIONAL (absent ⇒ no notices, no extra reads); the identity module
+     * always wires it.
+     */
+    accessNotifier?: AccessChangeNotifier | undefined);
     /** All grantable exact keys (from the catalog) + the computed wildcard set. */
     listCatalog(): Promise<{
         catalog: CatalogRow[];
@@ -108,6 +121,19 @@ export declare class GrantAdminService {
      * to AuthorizationUnavailableError (503).
      */
     private writeGrants;
+    /**
+     * G-027 step 3 (SPEC §5B, §5C): read the role's holders and their effective keys on the grant's
+     * own transaction `conn`, BEFORE the `role_permission` write. `null` (no reads at all) when no
+     * notifier is wired or it is disabled for this actor (guard `auth: false`, the org bootstrap).
+     * Never throws: a failed read is carried as an `AccessReadFailure`.
+     */
+    private beginAccessNotice;
+    /**
+     * After the write and the bump: the after-snapshot and the notices, on the same connection (a
+     * rollback removes them with the grant). Returns the audit detail addition: `noticesDropped: n`
+     * when n > 0, `'unknown'` when a holder or snapshot read failed, else nothing (byte-identical).
+     */
+    private finishAccessNotice;
     /**
      * Write the grant-administration audit row(s) on the transaction connection (D6). One row per
      * distinct tenant among the actor's tenant and every tenant the change bumped, so each affected

package/dist/features/authz/grant-admin.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grant-admin.service.d.ts","sourceRoot":"","sources":["../../../src/features/authz/grant-admin.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"grant-admin.service.d.ts","sourceRoot":"","sources":["../../../src/features/authz/grant-admin.service.ts"],"names":[],"mappings":"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"}

package/dist/features/authz/grant-admin.service.js

@@ -44,6 +44,7 @@ class GrantAdminService {
     ceiling;
     audit;
     schemas;
+    accessNotifier;
     bundles;
     /**
      * @param ceiling  The ADR-0029 self-escalation ceiling ("only grant what you hold") plus the
@@ -55,12 +56,19 @@ class GrantAdminService {
      *   connection, fail-closed. The identity module ALWAYS wires the engine `MariaDbAuditSink`.
      * @param schemas Resolved framework names (absent ⇒ resolved from the namespace, once, here).
      */
-    constructor(pool, bumper, bundleStore, ceiling, audit, schemas = (0, schema_js_1.frameworkSchemasFromEnv)()) {
+    constructor(pool, bumper, bundleStore, ceiling, audit, schemas = (0, schema_js_1.frameworkSchemasFromEnv)(), 
+    /**
+     * G-027 step 3 (notifying-user SPEC §5B, §5C): personal access-change notices on the grant's
+     * own transaction. OPTIONAL (absent ⇒ no notices, no extra reads); the identity module
+     * always wires it.
+     */
+    accessNotifier) {
         this.pool = pool;
         this.bumper = bumper;
         this.ceiling = ceiling;
         this.audit = audit;
         this.schemas = schemas;
+        this.accessNotifier = accessNotifier;
         this.bundles = bundleStore ?? new access_bundle_store_js_1.AccessBundleStore(pool, schemas);
     }
     /** All grantable exact keys (from the catalog) + the computed wildcard set. */
@@ -167,10 +175,17 @@ class GrantAdminService {
                     await this.ceiling.assertMayStripRoleFromServiceAccounts(actor, roleUuid, accounts.map((a) => a.sa_tenant_id), 'revoke');
                 }
             }
+            // G-027 step 3 (SPEC §5B): the holders' effective keys before the write, on this
+            // connection, after the lock and every refusal (a refused change never reaches a notice).
+            const notice = await this.beginAccessNotice(conn, roleUuid, actor);
             for (const key of keys)
                 await statement(conn, key);
             const bumped = await this.bumper.bumpForRole(roleUuid, conn);
-            await this.auditGrantChange(conn, action, roleUuid, keys, actor, bumped, extra);
+            const noticeDetail = await this.finishAccessNotice(notice, actor);
+            await this.auditGrantChange(conn, action, roleUuid, keys, actor, bumped, {
+                ...extra,
+                ...noticeDetail,
+            });
             await conn.commit();
             // ADR-0035: the committed versions reach Redis now (gate 5 reads them there).
             await this.bumper.publishCommitted(conn);
@@ -189,6 +204,36 @@ class GrantAdminService {
             await conn.release();
         }
     }
+    /**
+     * G-027 step 3 (SPEC §5B, §5C): read the role's holders and their effective keys on the grant's
+     * own transaction `conn`, BEFORE the `role_permission` write. `null` (no reads at all) when no
+     * notifier is wired or it is disabled for this actor (guard `auth: false`, the org bootstrap).
+     * Never throws: a failed read is carried as an `AccessReadFailure`.
+     */
+    async beginAccessNotice(conn, roleUuid, actor) {
+        const notifier = this.accessNotifier;
+        if (!notifier || !notifier.enabledFor(actor))
+            return null;
+        const query = (sql, params) => conn.query(sql, params);
+        const holders = await notifier.holdersOfRole(query, roleUuid);
+        const before = await notifier.snapshot(query, holders);
+        return { notifier, query, holders, before };
+    }
+    /**
+     * After the write and the bump: the after-snapshot and the notices, on the same connection (a
+     * rollback removes them with the grant). Returns the audit detail addition: `noticesDropped: n`
+     * when n > 0, `'unknown'` when a holder or snapshot read failed, else nothing (byte-identical).
+     */
+    async finishAccessNotice(run, actor) {
+        if (run === null)
+            return {};
+        const after = await run.notifier.snapshot(run.query, run.holders);
+        const { dropped } = await run.notifier.notify(run.query, actor, run.before, after);
+        const readFailed = !Array.isArray(run.holders) || !run.before.ok || !after.ok;
+        if (readFailed)
+            return { noticesDropped: 'unknown' };
+        return dropped > 0 ? { noticesDropped: dropped } : {};
+    }
     /**
      * Write the grant-administration audit row(s) on the transaction connection (D6). One row per
      * distinct tenant among the actor's tenant and every tenant the change bumped, so each affected
@@ -312,6 +357,9 @@ class GrantAdminService {
             if (this.ceiling && actor.isRoot !== true) {
                 await this.ceiling.assertMayStripRoleFromServiceAccounts(actor, roleUuid, accounts.map((a) => a.sa_tenant_id), 'delete');
             }
+            // G-027 step 3 (SPEC §5C): holders + their keys before the grants go. Holders come from
+            // committed postings (the caller's uncommitted role delete is not visible here).
+            const notice = await this.beginAccessNotice(conn, roleUuid, actor);
             const keys = (await conn.query(`SELECT rp_perm_key FROM \`${this.schemas.authz}\`.\`role_permission\` WHERE rp_role_uuid = ? ORDER BY rp_perm_key`, [roleUuid])).map((r) => r.rp_perm_key);
             const bumped = await this.bumper.bumpForRole(roleUuid, conn);
             await conn.query(`DELETE FROM \`${this.schemas.authz}\`.\`role_permission\` WHERE rp_role_uuid = ?`, [roleUuid]);
@@ -321,9 +369,11 @@ class GrantAdminService {
                 const previous = a.sa_updated_at_ms === null ? 0 : Number(a.sa_updated_at_ms);
                 await conn.query(`UPDATE \`${this.schemas.app}\`.\`service_account\` SET sa_role_ids = ?, sa_updated_at_ms = ? WHERE sa_id = ?`, [JSON.stringify(remaining), Math.max(nowMs, previous + 1), a.sa_id]);
             }
+            const noticeDetail = await this.finishAccessNotice(notice, actor);
             await this.auditGrantChange(conn, 'role.permission_revoked', roleUuid, keys, actor, bumped, {
                 roleDeleted: true,
                 serviceAccountsUpdated: accounts.length,
+                ...noticeDetail,
             });
             await conn.commit();
             await this.bumper.publishCommitted(conn);

package/dist/features/identity-feature.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"identity-feature.module.d.ts","sourceRoot":"","sources":["../../src/features/identity-feature.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,EAGL,KAAK,gBAAgB,EAEtB,MAAM,cAAc,CAAC;AACtB,OAAO,EAaL,KAAK,cAAc,EAGnB,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AA0DxB,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,yBAAyB,CAAC;AA0C/E,OAAO,EAAiB,KAAK,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAkElF;;;;;;GAMG;AACH,wBAAgB,0CAA0C,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAUnF;AAKD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GACzC,IAAI,CAwBN;AAKD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,gBAAgB,EAAE,MAAM,EACxB,WAAW,EAAE;IAAE,QAAQ,CAAC,EAAE,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAC/E,IAAI,CAQN;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,GAAG,SAAS,GAChE,gBAAgB,EAAE,CAapB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,gBAAgB,EACzB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,cAAc,CAyBhB;AA2BD,qBACa,qBAAqB;IAChC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,CAAC,OAAO,CAAC,EACb,OAAO,EACP,YAAiB,EACjB,OAAO,EAAE,YAAY,EACrB,MAAM,GACP,GAAE;QACD,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAC5B,YAAY,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;QAC1C,OAAO,CAAC,EAAE,gBAAgB,CAAC;QAC3B,MAAM,CAAC,EAAE,aAAa,CAAC;KACnB,GAAG,aAAa;CAgqBvB"}
+{"version":3,"file":"identity-feature.module.d.ts","sourceRoot":"","sources":["../../src/features/identity-feature.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,EAGL,KAAK,gBAAgB,EAEtB,MAAM,cAAc,CAAC;AACtB,OAAO,EAaL,KAAK,cAAc,EAGnB,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AA4DxB,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,yBAAyB,CAAC;AA2C/E,OAAO,EAAiB,KAAK,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAkElF;;;;;;GAMG;AACH,wBAAgB,0CAA0C,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAUnF;AAKD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GACzC,IAAI,CAwBN;AAKD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,gBAAgB,EAAE,MAAM,EACxB,WAAW,EAAE;IAAE,QAAQ,CAAC,EAAE,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAC/E,IAAI,CAQN;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,GAAG,SAAS,GAChE,gBAAgB,EAAE,CAapB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,gBAAgB,EACzB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,cAAc,CAyBhB;AA2BD,qBACa,qBAAqB;IAChC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,CAAC,OAAO,CAAC,EACb,OAAO,EACP,YAAiB,EACjB,OAAO,EAAE,YAAY,EACrB,MAAM,GACP,GAAE;QACD,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAC5B,YAAY,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;QAC1C,OAAO,CAAC,EAAE,gBAAgB,CAAC;QAC3B,MAAM,CAAC,EAAE,aAAa,CAAC;KACnB,GAAG,aAAa;CA+qBvB"}

package/dist/features/identity-feature.module.js

@@ -54,6 +54,7 @@ const access_bundle_store_js_1 = require("./authz/access-bundle-store.js");
 const grant_admin_service_js_1 = require("./authz/grant-admin.service.js");
 const grant_admin_controller_js_1 = require("./authz/grant-admin.controller.js");
 const grant_ceiling_js_1 = require("./authz/grant-ceiling.js");
+const access_change_notifier_js_1 = require("./authz/access-change-notifier.js");
 const policy_service_js_1 = require("./policy/policy.service.js");
 const security_policy_service_js_1 = require("./security-policy/security-policy.service.js");
 const security_policy_controller_js_1 = require("./security-policy/security-policy.controller.js");
@@ -301,6 +302,10 @@ let IdentityFeatureModule = IdentityFeatureModule_1 = class IdentityFeatureModul
         // registered for the cross-tenant writer and the policy author too.
         const recordAuthorization = (0, record_authorization_js_1.buildRecordAuthorizationInputs)(authzPool, extraObjects, schemas);
         const ceilingRegistry = recordAuthorization.registry;
+        // G-027 step 3: personal access-change notices, keys expanded against the SAME registry the
+        // request path grants from. Attached to guard's NotificationService by the provider below
+        // (absent with `auth: false` ⇒ a no-op notifier).
+        const accessChangeNotifier = new access_change_notifier_js_1.AccessChangeNotifier(ceilingRegistry, schemas);
         const bumper = new permission_version_bumper_js_1.PermissionVersionBumper(undefined, schemas);
         const postingVersionBump = {
             bumpTenant: (tenantUuid) => bumper.bumpForTenant(tenantUuid, authzPool),
@@ -331,7 +336,7 @@ let IdentityFeatureModule = IdentityFeatureModule_1 = class IdentityFeatureModul
         const auditSinkConfig = { schema: schemas.audit };
         // Grant administration is audited on the grant's own transaction (D6, fail-closed).
         const grantAdminAuditSink = new engine_1.MariaDbAuditSink(auditSinkConfig);
-        const grantAdminService = new grant_admin_service_js_1.GrantAdminService(authzPool, bumper, accessBundleStore, grantCeiling, grantAdminAuditSink, schemas);
+        const grantAdminService = new grant_admin_service_js_1.GrantAdminService(authzPool, bumper, accessBundleStore, grantCeiling, grantAdminAuditSink, schemas, accessChangeNotifier);
         // Scope closure (Task 1.2 of the scoped-hierarchy program): the reconciler + node
         // move/delete maintenance, over the SAME shared authzPool (it reaches BOTH shield_app —
         // companies — and shield_authz — scope_closure). Reuses the SAME `bumper` instance so a
@@ -671,6 +676,16 @@ let IdentityFeatureModule = IdentityFeatureModule_1 = class IdentityFeatureModul
                 org_catalog_service_js_1.OrgCatalogService,
                 record_resolver_js_1.RecordResolverService,
                 { provide: posting_version_bump_js_1.POSTING_VERSION_BUMP, useValue: postingVersionBump },
+                // G-027 step 3: the one access-change notifier (also held by GrantAdminService), attached
+                // here to guard's NotificationService when guard provides it (`auth: true`), else none.
+                {
+                    provide: access_change_notifier_js_1.ACCESS_CHANGE_NOTIFIER,
+                    useFactory: (service) => {
+                        accessChangeNotifier.attach(service ?? null);
+                        return accessChangeNotifier;
+                    },
+                    inject: [{ token: guard_1.SHIELD_NOTIFICATIONS, optional: true }],
+                },
                 // Mandatory-2FA policies (R2.6, R2.9): the service, and its permission-version bump over
                 // the ONE shared bumper (bumps on the write's transaction, published after the commit).
                 security_policy_service_js_1.SecurityPolicyService,

package/dist/features/membership/membership.service.d.ts

@@ -20,11 +20,22 @@ import { RecordsService, type RecordId, type RecordView } from '@astram/engine';
 import type { Principal } from '@astram/core';
 import { type PostingVersionBump } from './posting-version-bump.js';
 import { GrantCeiling } from '../authz/grant-ceiling.js';
+import { type AccessChangeNotifier } from '../authz/access-change-notifier.js';
 export declare class MembershipService {
     private readonly records;
     private readonly ceiling;
     private readonly versionBump?;
-    constructor(records: RecordsService, ceiling: GrantCeiling, versionBump?: (PostingVersionBump | null) | undefined);
+    private readonly accessNotifier?;
+    constructor(records: RecordsService, ceiling: GrantCeiling, versionBump?: (PostingVersionBump | null) | undefined, accessNotifier?: (AccessChangeNotifier | null) | undefined);
+    /**
+     * G-027 step 3 (SPEC §5E): the before-snapshot of `pairs` on the engine transaction's own
+     * connection (`transactionQueryOf`), so the after-snapshot sees the uncommitted membership
+     * writes and the notice commits or rolls back with them. `null` (no reads) when no notifier is
+     * wired or it is disabled for this actor (guard `auth: false`, the org bootstrap). Never throws.
+     */
+    private beginAccessNotice;
+    /** After the last write: after-snapshot + notify (a drop is logged by the notifier only). */
+    private finishAccessNotice;
     /**
      * Read a membership through the subtree wall (404 when out of reach) and, unless the actor is
      * acting on their OWN membership, require the actor to dominate its user (security review): a
@@ -48,7 +59,8 @@ export declare class MembershipService {
      */
     addMembership(actor: Principal, userUuid: string, companyUuid: string): Promise<RecordId>;
     /**
-     * Add an ACTIVE membership for `(userUuid, companyUuid)` in one create (G-009 R4): a brand-new
+     * Add an ACTIVE membership for `(userUuid, companyUuid)` in one create, inside one engine
+     * transaction with the user's access notice (G-009 R4; G-027 step 3): a brand-new
      * membership has no other active card to displace, so no create-then-activate pair. A
      * membership for that pair already existing is an `IdentityConflictError`, from the pre-check
      * and from the `(cm_user_uuid, cm_company_uuid)` unique index (the pre-check read is SQL-scoped
@@ -88,6 +100,11 @@ export declare class MembershipService {
     /**
      * Remove a membership card (its postings cascade at the DB via FK ON DELETE CASCADE). A peer's
      * membership needs dominance over the peer (security review); your own does not.
+     *
+     * Intentionally sends NO access-change notice (notifying-user SPEC §11): the user can no longer
+     * open that company's inbox, and the notice store's recipient filter would skip them anyway.
+     * `updateMembership` (status only, no key change), user status changes and `deleteUser` are
+     * likewise not hooked.
      */
     removeMembership(actor: Principal, membershipUuid: string): Promise<void>;
 }

package/dist/features/membership/membership.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"membership.service.d.ts","sourceRoot":"","sources":["../../../src/features/membership/membership.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAwB,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE1F,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAYzD,qBACa,iBAAiB;IAE1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAGxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAQxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;gBAXZ,OAAO,EAAE,cAAc,EAGvB,OAAO,EAAE,YAAY,EAQrB,WAAW,CAAC,GAAE,kBAAkB,GAAG,IAAI,aAAA;IAG1D;;;;OAIG;YACW,WAAW;IAQzB;;;;;;OAMG;YACW,WAAW;IAYzB;;;;;;OAMG;IACG,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAkB/F;;;;;;;OAOG;IACG,mBAAmB,CACvB,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,QAAQ,CAAC;IAwBpB,kEAAkE;IAC5D,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC;IAKvE;;;;;;;;;;;;;;;;;OAiBG;IACG,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0D1F;;;;OAIG;IACG,gBAAgB,CACpB,KAAK,EAAE,SAAS,EAChB,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACzB,OAAO,CAAC,IAAI,CAAC;IA4BhB;;;OAGG;IACG,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAYhF"}
+{"version":3,"file":"membership.service.d.ts","sourceRoot":"","sources":["../../../src/features/membership/membership.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEhF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAwB,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE1F,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAEL,KAAK,oBAAoB,EAI1B,MAAM,oCAAoC,CAAC;AAoB5C,qBACa,iBAAiB;IAE1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAGxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAQxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAK7B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;gBAhBf,OAAO,EAAE,cAAc,EAGvB,OAAO,EAAE,YAAY,EAQrB,WAAW,CAAC,GAAE,kBAAkB,GAAG,IAAI,aAAA,EAKvC,cAAc,CAAC,GAAE,oBAAoB,GAAG,IAAI,aAAA;IAG/D;;;;;OAKG;YACW,iBAAiB;IAY/B,6FAA6F;YAC/E,kBAAkB;IAShC;;;;OAIG;YACW,WAAW;IAQzB;;;;;;OAMG;YACW,WAAW;IAYzB;;;;;;OAMG;IACG,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAkB/F;;;;;;;;OAQG;IACG,mBAAmB,CACvB,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,QAAQ,CAAC;IAgCpB,kEAAkE;IAC5D,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC;IAKvE;;;;;;;;;;;;;;;;;OAiBG;IACG,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyE1F;;;;OAIG;IACG,gBAAgB,CACpB,KAAK,EAAE,SAAS,EAChB,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACzB,OAAO,CAAC,IAAI,CAAC;IA4BhB;;;;;;;;OAQG;IACG,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAYhF"}

package/dist/features/membership/membership.service.js

@@ -33,9 +33,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MembershipService = void 0;
 const common_1 = require("@nestjs/common");
 const engine_1 = require("@astram/engine");
+const internal_1 = require("@astram/engine/internal");
 const posting_version_bump_js_1 = require("./posting-version-bump.js");
 const identity_errors_js_1 = require("../shared/identity-errors.js");
 const grant_ceiling_js_1 = require("../authz/grant-ceiling.js");
+const access_change_notifier_js_1 = require("../authz/access-change-notifier.js");
 /** The only status the active membership may have (case-sensitive, as the readers' predicate). */
 const ACTIVE_STATUS = 'active';
 /** A driver duplicate-key error (errno 1062), recognised by errno/code only, never its message. */
@@ -49,13 +51,36 @@ let MembershipService = class MembershipService {
     records;
     ceiling;
     versionBump;
+    accessNotifier;
     constructor(records, 
     // Dominance over the member for destructive ops (security review): REQUIRED, so a missing
     // ceiling fails DI at boot instead of silently skipping the check.
-    ceiling, versionBump) {
+    ceiling, versionBump, accessNotifier) {
         this.records = records;
         this.ceiling = ceiling;
         this.versionBump = versionBump;
+        this.accessNotifier = accessNotifier;
+    }
+    /**
+     * G-027 step 3 (SPEC §5E): the before-snapshot of `pairs` on the engine transaction's own
+     * connection (`transactionQueryOf`), so the after-snapshot sees the uncommitted membership
+     * writes and the notice commits or rolls back with them. `null` (no reads) when no notifier is
+     * wired or it is disabled for this actor (guard `auth: false`, the org bootstrap). Never throws.
+     */
+    async beginAccessNotice(tx, actor, pairs) {
+        const notifier = this.accessNotifier;
+        if (!notifier || !notifier.enabledFor(actor))
+            return null;
+        const query = (0, internal_1.transactionQueryOf)(tx);
+        const before = await notifier.snapshot(query, pairs);
+        return { notifier, query, pairs, before };
+    }
+    /** After the last write: after-snapshot + notify (a drop is logged by the notifier only). */
+    async finishAccessNotice(run, actor) {
+        if (run === null)
+            return;
+        const after = await run.notifier.snapshot(run.query, run.pairs);
+        await run.notifier.notify(run.query, actor, run.before, after);
     }
     /**
      * Read a membership through the subtree wall (404 when out of reach) and, unless the actor is
@@ -117,7 +142,8 @@ let MembershipService = class MembershipService {
         });
     }
     /**
-     * Add an ACTIVE membership for `(userUuid, companyUuid)` in one create (G-009 R4): a brand-new
+     * Add an ACTIVE membership for `(userUuid, companyUuid)` in one create, inside one engine
+     * transaction with the user's access notice (G-009 R4; G-027 step 3): a brand-new
      * membership has no other active card to displace, so no create-then-activate pair. A
      * membership for that pair already existing is an `IdentityConflictError`, from the pre-check
      * and from the `(cm_user_uuid, cm_company_uuid)` unique index (the pre-check read is SQL-scoped
@@ -136,8 +162,16 @@ let MembershipService = class MembershipService {
         }
         let id;
         try {
-            id = await this.records.create('company_membership', {
-                fields: { userUuid, companyUuid, isActive: true, status: 'active' },
+            // G-027 step 3 (SPEC §5E): the create and the user's access notice in one transaction.
+            id = await this.records.transaction(async (tx) => {
+                const notice = await this.beginAccessNotice(tx, actor, [
+                    { userId: userUuid, tenantId: companyUuid },
+                ]);
+                const created = await tx.create('company_membership', {
+                    fields: { userUuid, companyUuid, isActive: true, status: 'active' },
+                });
+                await this.finishAccessNotice(notice, actor);
+                return created;
             });
         }
         catch (err) {
@@ -203,6 +237,16 @@ let MembershipService = class MembershipService {
             if (current.fields?.status !== ACTIVE_STATUS) {
                 throw new identity_errors_js_1.IdentityConflictError('Only a membership with status active can be made the active membership.');
             }
+            // G-027 step 3 (SPEC §5E): the user in every company of their memberships (the target's
+            // and each one this flip deactivates), before the first write. One notice per company
+            // whose key set changed.
+            const companies = new Set();
+            for (const m of rows) {
+                const c = m.fields?.companyUuid;
+                if (typeof c === 'string' && c.length > 0)
+                    companies.add(c);
+            }
+            const notice = await this.beginAccessNotice(tx, actor, [...companies].map((tenantId) => ({ userId: userUuid, tenantId })));
             // 1) TARGET FIRST (defence in depth, see the method comment).
             await tx.update('company_membership', target.id, { fields: { isActive: true } });
             // 2) Deactivate every OTHER membership (skip the target we just activated).
@@ -212,6 +256,7 @@ let MembershipService = class MembershipService {
                 await tx.update('company_membership', m.id, { fields: { isActive: false } });
                 deactivated.push(m);
             }
+            await this.finishAccessNotice(notice, actor);
         });
         // ADR-0011 STALENESS FIX: activation ADDS the target company's role grants and each
         // deactivation REMOVES that company's grants — a coarse-grant change in BOTH directions.
@@ -262,6 +307,11 @@ let MembershipService = class MembershipService {
     /**
      * Remove a membership card (its postings cascade at the DB via FK ON DELETE CASCADE). A peer's
      * membership needs dominance over the peer (security review); your own does not.
+     *
+     * Intentionally sends NO access-change notice (notifying-user SPEC §11): the user can no longer
+     * open that company's inbox, and the notice store's recipient filter would skip them anyway.
+     * `updateMembership` (status only, no key change), user status changes and `deleteUser` are
+     * likewise not hooked.
      */
     async removeMembership(actor, membershipUuid) {
         // ADR-0011 STALENESS FIX: resolve the membership's tenant BEFORE the delete (it's
@@ -281,6 +331,8 @@ exports.MembershipService = MembershipService = __decorate([
     (0, common_1.Injectable)(),
     __param(2, (0, common_1.Optional)()),
     __param(2, (0, common_1.Inject)(posting_version_bump_js_1.POSTING_VERSION_BUMP)),
+    __param(3, (0, common_1.Optional)()),
+    __param(3, (0, common_1.Inject)(access_change_notifier_js_1.ACCESS_CHANGE_NOTIFIER)),
     __metadata("design:paramtypes", [engine_1.RecordsService,
-        grant_ceiling_js_1.GrantCeiling, Object])
+        grant_ceiling_js_1.GrantCeiling, Object, Object])
 ], MembershipService);

package/dist/features/membership/posting.service.d.ts

@@ -27,6 +27,7 @@ import { RecordsService, type RecordView } from '@astram/engine';
 import type { Principal } from '@astram/core';
 import { type PostingVersionBump } from './posting-version-bump.js';
 import { GrantCeiling } from '../authz/grant-ceiling.js';
+import { type AccessChangeNotifier } from '../authz/access-change-notifier.js';
 /**
  * The shape of one desired posting row submitted by the editor. The effective-window
  * bounds arrive from the client as a bare `YYYY-MM-DD` date string (native `<input
@@ -44,7 +45,8 @@ export declare class PostingService {
     private readonly records;
     private readonly ceiling;
     private readonly versionBump?;
-    constructor(records: RecordsService, ceiling: GrantCeiling, versionBump?: (PostingVersionBump | null) | undefined);
+    private readonly accessNotifier?;
+    constructor(records: RecordsService, ceiling: GrantCeiling, versionBump?: (PostingVersionBump | null) | undefined, accessNotifier?: (AccessChangeNotifier | null) | undefined);
     /** List a membership's postings (tenant-scoped by the pipe). */
     listPostings(membershipUuid: string): Promise<readonly RecordView[]>;
     /**
@@ -64,6 +66,15 @@ export declare class PostingService {
     addPostings(actor: Principal, membershipUuid: string, toAdd: readonly PostingInput[], opts?: {
         operationRoleIds?: ReadonlySet<string> | readonly string[];
     }): Promise<void>;
+    /**
+     * G-027 step 3 (SPEC §5D): the before-snapshot of (member, company) on the engine transaction's
+     * own connection (`transactionQueryOf`), so the after-snapshot sees the uncommitted posting
+     * writes and the notice commits or rolls back with them. `null` (no reads) when no notifier is
+     * wired or it is disabled for this actor (guard `auth: false`, the org bootstrap). Never throws.
+     */
+    private beginAccessNotice;
+    /** After the last write: after-snapshot + notify (a drop is logged by the notifier only). */
+    private finishAccessNotice;
     private assertEveryRole;
     /** The membership through the subtree read wall (404 when out of reach) and its company. */
     private reachMembership;

package/dist/features/membership/posting.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"posting.service.d.ts","sourceRoot":"","sources":["../../../src/features/membership/posting.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAE,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAwB,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC1F,OAAO,EAAE,YAAY,EAA6B,MAAM,2BAA2B,CAAC;AAOpF;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACvC,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACzC;AA0ED,qBACa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAGxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAKxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;gBARZ,OAAO,EAAE,cAAc,EAGvB,OAAO,EAAE,YAAY,EAKrB,WAAW,CAAC,GAAE,kBAAkB,GAAG,IAAI,aAAA;IAG1D,gEAAgE;IAC1D,YAAY,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC;IAK1E;;;;;OAKG;IACG,eAAe,CACnB,KAAK,EAAE,SAAS,EAChB,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,SAAS,YAAY,EAAE,GAC/B,OAAO,CAAC,IAAI,CAAC;IA0EhB;;;;;;OAMG;IACG,WAAW,CACf,KAAK,EAAE,SAAS,EAChB,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,IAAI,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,MAAM,EAAE,CAAA;KAAE,GACpE,OAAO,CAAC,IAAI,CAAC;IA4ChB,OAAO,CAAC,eAAe;IAQvB,4FAA4F;YAC9E,eAAe;IAY7B,iGAAiG;YACnF,YAAY;IAuB1B;;;;OAIG;YACW,cAAc;IAa5B;;;;;;;;;;;;OAYG;YACW,YAAY;YA+BZ,UAAU;CAkBzB"}
+{"version":3,"file":"posting.service.d.ts","sourceRoot":"","sources":["../../../src/features/membership/posting.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAE,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAwB,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC1F,OAAO,EAAE,YAAY,EAA6B,MAAM,2BAA2B,CAAC;AACpF,OAAO,EAEL,KAAK,oBAAoB,EAI1B,MAAM,oCAAoC,CAAC;AAO5C;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACvC,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACzC;AAkFD,qBACa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAGxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAKxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAK7B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;gBAbf,OAAO,EAAE,cAAc,EAGvB,OAAO,EAAE,YAAY,EAKrB,WAAW,CAAC,GAAE,kBAAkB,GAAG,IAAI,aAAA,EAKvC,cAAc,CAAC,GAAE,oBAAoB,GAAG,IAAI,aAAA;IAG/D,gEAAgE;IAC1D,YAAY,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC;IAK1E;;;;;OAKG;IACG,eAAe,CACnB,KAAK,EAAE,SAAS,EAChB,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,SAAS,YAAY,EAAE,GAC/B,OAAO,CAAC,IAAI,CAAC;IA6EhB;;;;;;OAMG;IACG,WAAW,CACf,KAAK,EAAE,SAAS,EAChB,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,IAAI,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,MAAM,EAAE,CAAA;KAAE,GACpE,OAAO,CAAC,IAAI,CAAC;IAiDhB;;;;;OAKG;YACW,iBAAiB;IAiB/B,6FAA6F;YAC/E,kBAAkB;IAShC,OAAO,CAAC,eAAe;IAQvB,4FAA4F;YAC9E,eAAe;IAY7B,iGAAiG;YACnF,YAAY;IAuB1B;;;;OAIG;YACW,cAAc;IAa5B;;;;;;;;;;;;OAYG;YACW,YAAY;YA+BZ,UAAU;CAkBzB"}

package/dist/features/membership/posting.service.js

@@ -40,8 +40,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PostingService = void 0;
 const common_1 = require("@nestjs/common");
 const engine_1 = require("@astram/engine");
+const internal_1 = require("@astram/engine/internal");
 const posting_version_bump_js_1 = require("./posting-version-bump.js");
 const grant_ceiling_js_1 = require("../authz/grant-ceiling.js");
+const access_change_notifier_js_1 = require("../authz/access-change-notifier.js");
 const identity_errors_js_1 = require("../shared/identity-errors.js");
 /** The field keys whose values are effective-window epoch-ms bounds (normalized on write). */
 const WINDOW_KEYS = new Set(['effectiveFrom', 'effectiveUntil']);
@@ -115,13 +117,15 @@ let PostingService = class PostingService {
     records;
     ceiling;
     versionBump;
+    accessNotifier;
     constructor(records, 
     // The role-assignment ceiling + binding rule (security hardening #11). REQUIRED: a missing
     // ceiling must fail DI at boot, never silently skip the check.
-    ceiling, versionBump) {
+    ceiling, versionBump, accessNotifier) {
         this.records = records;
         this.ceiling = ceiling;
         this.versionBump = versionBump;
+        this.accessNotifier = accessNotifier;
     }
     /** List a membership's postings (tenant-scoped by the pipe). */
     async listPostings(membershipUuid) {
@@ -170,12 +174,15 @@ let PostingService = class PostingService {
             // delete, while we waited is refused before the INSERT (rolled back).
             await this.lockAndRecheck(tx, actor, tenantUuid, addedRoles, undefined);
             await this.lockOrgUnits(tx, tenantUuid, added);
+            // G-027 step 3 (SPEC §5D): the member's keys in this company before the first write.
+            const notice = await this.beginAccessNotice(tx, actor, memberUuid, tenantUuid);
             for (const d of added) {
                 await tx.create('membership_posting', { fields: { ...stripEmpty(d), membershipUuid } });
             }
             for (const r of removed) {
                 await tx.delete('membership_posting', r.id);
             }
+            await this.finishAccessNotice(notice, actor);
         });
         await this.bumpTenant(tenantUuid);
     }
@@ -209,15 +216,43 @@ let PostingService = class PostingService {
         if (added.length === 0)
             return; // nothing missing: no write, no bump
         const addedRoles = await this.assertMayAdd(actor, tenantUuid, added, ceilingOpts);
+        const memberUuid = typeof membership.fields?.userUuid === 'string' ? membership.fields.userUuid : '';
         await this.records.transaction(async (tx) => {
             await this.lockAndRecheck(tx, actor, tenantUuid, addedRoles, ceilingOpts);
             await this.lockOrgUnits(tx, tenantUuid, added);
+            // G-027 step 3 (SPEC §5D): the member's keys in this company before the first write.
+            const notice = await this.beginAccessNotice(tx, actor, memberUuid, tenantUuid);
             for (const d of added) {
                 await tx.create('membership_posting', { fields: { ...stripEmpty(d), membershipUuid } });
             }
+            await this.finishAccessNotice(notice, actor);
         });
         await this.bumpTenant(tenantUuid);
     }
+    /**
+     * G-027 step 3 (SPEC §5D): the before-snapshot of (member, company) on the engine transaction's
+     * own connection (`transactionQueryOf`), so the after-snapshot sees the uncommitted posting
+     * writes and the notice commits or rolls back with them. `null` (no reads) when no notifier is
+     * wired or it is disabled for this actor (guard `auth: false`, the org bootstrap). Never throws.
+     */
+    async beginAccessNotice(tx, actor, memberUuid, tenantUuid) {
+        const notifier = this.accessNotifier;
+        if (!notifier || !notifier.enabledFor(actor))
+            return null;
+        const query = (0, internal_1.transactionQueryOf)(tx);
+        const pairs = memberUuid !== '' && tenantUuid !== null
+            ? [{ userId: memberUuid, tenantId: tenantUuid }]
+            : [];
+        const before = await notifier.snapshot(query, pairs);
+        return { notifier, query, pairs, before };
+    }
+    /** After the last write: after-snapshot + notify (a drop is logged by the notifier only). */
+    async finishAccessNotice(run, actor) {
+        if (run === null)
+            return;
+        const after = await run.notifier.snapshot(run.query, run.pairs);
+        await run.notifier.notify(run.query, actor, run.before, after);
+    }
     assertEveryRole(postings) {
         for (const d of postings) {
             if (typeof d?.roleUuid !== 'string' || d.roleUuid.length === 0) {
@@ -327,6 +362,8 @@ exports.PostingService = PostingService = __decorate([
     (0, common_1.Injectable)(),
     __param(2, (0, common_1.Optional)()),
     __param(2, (0, common_1.Inject)(posting_version_bump_js_1.POSTING_VERSION_BUMP)),
+    __param(3, (0, common_1.Optional)()),
+    __param(3, (0, common_1.Inject)(access_change_notifier_js_1.ACCESS_CHANGE_NOTIFIER)),
     __metadata("design:paramtypes", [engine_1.RecordsService,
-        grant_ceiling_js_1.GrantCeiling, Object])
+        grant_ceiling_js_1.GrantCeiling, Object, Object])
 ], PostingService);

package/migrations/1710000000108-CreateUserNotification.cjs

@@ -0,0 +1,66 @@
+/**
+ * Framework identity migration — the per-user notification store (G-027 step 2, NAES G-034 R5;
+ * spec `docs/features/notification-store/SPEC.md` §4A).
+ *
+ * `<identity>.user_notification` — one row per notice to one user in one company. Written and read
+ * only by guard (`MariaDbNotificationStore`, through `NotificationService.post` and the
+ * `/account/notifications` routes); identity owns the DDL only, like `email_change_token`.
+ *   - un_tenant_id: the company the notice belongs to, stamped server-side; a user reads only the
+ *     notices of the session's active company. A deleted company takes its notices with it.
+ *   - un_user_uuid: the recipient; a deleted user takes their notices with it.
+ *   - un_category: 'announcement' | 'personal' (from the kind's registration, never the caller).
+ *   - un_title / un_body / un_link: plain text; the link is an app-relative path.
+ *   - un_dedupe_key: the poster's optional idempotency key; unique per user and company (NULL keys
+ *     never collide), so a retried post inserts nothing. Binary collation: keys compare exactly
+ *     (`A1` and `a1` are different keys).
+ *   - un_created_at_ms / un_read_at_ms: epoch milliseconds (BIGINT, no driver time-zone shift);
+ *     NULL read time = unread.
+ * Indexes serve the inbox list and counts, the dedupe key, the retention purge and the tenant FK.
+ *
+ * Idempotent (CREATE TABLE IF NOT EXISTS); `down` drops the table with IF EXISTS. No rows are
+ * written, no ids are hard-coded. Database names come from `ctx.schemas` (namespace or single
+ * layout, ADR-0037/ADR-0041); the table is listed in core `FRAMEWORK_TABLES`.
+ */
+
+const { frameworkSchemasForMigration } = require('@astram/core');
+
+async function up(ctx) {
+  const { query } = ctx;
+  const { app: APP, identity: IDENTITY } = frameworkSchemasForMigration(ctx, process.env);
+
+  await query(
+    `CREATE TABLE IF NOT EXISTS \`${IDENTITY}\`.\`user_notification\` (
+      un_uuid          VARCHAR(36)   NOT NULL,
+      un_tenant_id     VARCHAR(36)   NOT NULL,
+      un_user_uuid     VARCHAR(36)   NOT NULL,
+      un_category      VARCHAR(16)   NOT NULL,
+      un_kind          VARCHAR(64)   NOT NULL,
+      un_title         VARCHAR(160)  NOT NULL,
+      un_body          VARCHAR(1000) NULL,
+      un_link          VARCHAR(512)  NULL,
+      un_dedupe_key    VARCHAR(64)   CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NULL,
+      un_created_at_ms BIGINT        NOT NULL,
+      un_read_at_ms    BIGINT        NULL,
+      PRIMARY KEY (un_uuid),
+      INDEX idx_un_inbox (un_user_uuid, un_tenant_id, un_category, un_read_at_ms, un_created_at_ms),
+      UNIQUE KEY uq_un_dedupe (un_user_uuid, un_tenant_id, un_dedupe_key),
+      INDEX idx_un_created (un_created_at_ms),
+      INDEX idx_un_tenant (un_tenant_id),
+      CONSTRAINT ck_un_category CHECK (un_category IN ('announcement', 'personal')),
+      CONSTRAINT FK_user_notification_tenant
+        FOREIGN KEY (un_tenant_id) REFERENCES \`${APP}\`.\`companies\` (c_uuid)
+        ON DELETE CASCADE,
+      CONSTRAINT FK_user_notification_user
+        FOREIGN KEY (un_user_uuid) REFERENCES \`${APP}\`.\`users\` (u_uuid)
+        ON DELETE CASCADE
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`,
+  );
+}
+
+async function down(ctx) {
+  const { query } = ctx;
+  const { identity: IDENTITY } = frameworkSchemasForMigration(ctx, process.env);
+  await query(`DROP TABLE IF EXISTS \`${IDENTITY}\`.\`user_notification\``);
+}
+
+module.exports = { up, down };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/identity",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "license": "MIT",
   "description": "Astram framework — the framework-owned identity + tenancy model. Hosts the identity @ObjectType classes (user, company, membership, posting), framework-authored identity migrations, and the identity resolver. Top of the dependency graph: depends on @astram/engine (for @ObjectType/@Field decorators) + @astram/guard / @astram/core (for the auth ports).",
   "type": "commonjs",
@@ -36,9 +36,9 @@
   },
   "dependencies": {
     "mariadb": "^3.5.4",
-    "@astram/core": "1.12.0",
-    "@astram/guard": "0.23.0",
-    "@astram/engine": "0.16.0"
+    "@astram/core": "1.13.0",
+    "@astram/guard": "0.25.0",
+    "@astram/engine": "0.16.1"
   },
   "peerDependencies": {
     "@nestjs/common": "^11",