@astram/identity 0.1.2 → 0.2.0

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

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * MembershipService — the membership layer's write/read logic, built ENTIRELY on the
+ * injected RecordsService facade (which supplies the request principal and runs each op
+ * through the engine pipe). It never touches a pool, query runner, or raw SQL — every op
+ * is one-or-more facade calls, so the permission gate + anti-forgery write-context +
+ * audit + cross-tenant isolation are applied automatically.
+ *
+ * A `company_membership` is the first-class `(user, company)` scope with `is_active`
+ * (exactly one active per user) + `status`. This service owns the ONE invariant the DB
+ * cannot express — one-active-per-user — because there is no partial-unique on
+ * `cm_is_active`; `setActive` is the guard.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MembershipService = void 0;
+const common_1 = require("@nestjs/common");
+const engine_1 = require("@astram/engine");
+const posting_version_bump_js_1 = require("./posting-version-bump.js");
+let MembershipService = class MembershipService {
+    records;
+    versionBump;
+    constructor(records, versionBump) {
+        this.records = records;
+        this.versionBump = versionBump;
+    }
+    /**
+     * Read a membership's tenant (its `companyUuid`) through the pipe, or `null` when
+     * unresolvable (→ no bump; fail-safe, never guesses a tenant). Used to target the
+     * permission-version bump at the company whose coarse grants a mutation changed.
+     */
+    async tenantOf(membershipUuid) {
+        try {
+            const m = await this.records.get('company_membership', membershipUuid);
+            const companyUuid = m?.fields?.companyUuid;
+            return typeof companyUuid === 'string' && companyUuid.length > 0 ? companyUuid : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Bump the permission version for each DISTINCT tenant in `tenantUuids` (best-effort +
+     * fail-safe): the mutation already succeeded, so a bump hiccup must NOT surface as an
+     * error that hides a successful membership change — the cache is invalidated by the next
+     * legit bump / the facts' natural TTL instead. No collaborator wired → no-op (prior
+     * behavior). `null`/empty entries are skipped (never bump a guessed tenant).
+     */
+    async bumpTenants(tenantUuids) {
+        const bump = this.versionBump;
+        if (!bump)
+            return;
+        for (const tenant of new Set(tenantUuids.filter((t) => !!t))) {
+            try {
+                await bump.bumpTenant(tenant);
+            }
+            catch {
+                // Fail-safe: never fail an applied membership change on a version-bump hiccup.
+            }
+        }
+    }
+    /**
+     * Add a membership card for `(userUuid, companyUuid)`. New memberships are created
+     * INACTIVE (`isActive:false`) — activation is an explicit `setActive` call so the
+     * one-active invariant is never violated by a fresh add. A duplicate `(user, company)`
+     * hits the DB's UNIQUE constraint and the engine's error surfaces to the caller (NOT
+     * swallowed here). `createdBy` is stamped server-side (actorId-trusted).
+     */
+    addMembership(userUuid, companyUuid) {
+        return this.records.create('company_membership', {
+            fields: { userUuid, companyUuid, isActive: false, status: 'active' },
+        });
+    }
+    /** List a user's membership cards (tenant-scoped by the pipe). */
+    async listMemberships(userUuid) {
+        const page = await this.records.list('company_membership', { where: { userUuid } });
+        return page.rows;
+    }
+    /**
+     * Flip which of the user's memberships is active — the ONE-ACTIVE invariant. The service
+     * is the guard because the DB has no partial-unique on `cm_is_active`.
+     *
+     * ⚠️ ORDER IS LOAD-BEARING (fail-safe against a LOGIN LOCKOUT). The engine's `list` has
+     * no ORDER BY (PKs are random uuids → arbitrary row order) and each `update` is its OWN
+     * transaction (no cross-call atomicity). So this MUST activate the TARGET FIRST, then
+     * deactivate the others:
+     *   - Worst case of a mid-loop failure is then a transient TWO-active window, which is
+     *     RECOVERABLE — the credential resolver reads `is_active=1 LIMIT 1`, so it still
+     *     resolves a tenant and login works.
+     *   - The forbidden alternative (deactivate-old-then-activate-target) can leave a
+     *     ZERO-active window on a mid-failure → the resolver returns null → the user is
+     *     LOCKED OUT of login until an admin re-activates. Never do that.
+     *
+     * Guard: if `membershipUuid` is NOT one of the user's memberships, throw — otherwise the
+     * loop would deactivate everything and activate nothing (also a zero-active lockout).
+     */
+    async setActive(membershipUuid, userUuid) {
+        const page = await this.records.list('company_membership', { where: { userUuid } });
+        const target = page.rows.find((m) => m.id === membershipUuid);
+        if (!target) {
+            // Not this user's membership → refuse rather than leave the user with ZERO active
+            // (a login lockout). Fail-closed.
+            throw new common_1.NotFoundException(`membership ${membershipUuid} does not belong to user ${userUuid}`);
+        }
+        // 1) TARGET FIRST — guarantees an active membership exists before any deactivation, so
+        //    a mid-failure below leaves TWO active (recoverable), never ZERO (lockout).
+        await this.records.update('company_membership', target.id, { fields: { isActive: true } });
+        // 2) Deactivate every OTHER membership (skip the target we just activated).
+        const deactivated = [];
+        for (const m of page.rows) {
+            if (m.id === membershipUuid)
+                continue;
+            await this.records.update('company_membership', m.id, { fields: { isActive: false } });
+            deactivated.push(m);
+        }
+        // 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.
+        // A user's memberships can span DIFFERENT companies, so setActive may affect MULTIPLE
+        // tenants: bump the target's tenant AND every deactivated membership's tenant. Read each
+        // tenant from the already-loaded rows (companyUuid is a field on the membership) — no
+        // extra pipe reads. bumpTenants de-dupes + is best-effort/fail-safe (the flip already
+        // succeeded; a bump hiccup must not error).
+        const asCompanyUuid = (m) => {
+            const c = m.fields?.companyUuid;
+            return typeof c === 'string' && c.length > 0 ? c : null;
+        };
+        await this.bumpTenants([asCompanyUuid(target), ...deactivated.map(asCompanyUuid)]);
+    }
+    /**
+     * Update a membership's mutable non-activity fields (currently `status`). Activity is
+     * flipped only via `setActive` to preserve the one-active invariant, so `isActive` is
+     * intentionally NOT a patch key here.
+     */
+    updateMembership(membershipUuid, patch) {
+        // NO version bump here (ADR-0011): this patches `status` ONLY — `isActive` is
+        // deliberately not a patch key (activity flips solely via `setActive`, which bumps),
+        // and the controller only ever passes `{ status }`. Coarse-grant resolution gates on
+        // `cm_is_active = 1`, NOT on `cm_status`, so a status change does NOT alter which roles
+        // resolve → the warm cache stays correct → no invalidation needed. If a future patch key
+        // is ever added here that CAN change which roles/postings resolve, it MUST bump the
+        // membership's tenant (mirror `setActive`).
+        return this.records.update('company_membership', membershipUuid, { fields: patch });
+    }
+    /** Remove a membership card (its postings cascade at the DB via FK ON DELETE CASCADE). */
+    async removeMembership(membershipUuid) {
+        // ADR-0011 STALENESS FIX: resolve the membership's tenant BEFORE the delete (it's
+        // unreadable afterwards). If the membership was active, deleting it (postings cascade)
+        // removes the user's role grants in that company — a coarse-grant change — so bump that
+        // tenant AFTER the delete succeeds. Best-effort/fail-safe (bumpTenants swallows). A
+        // membership belongs to exactly one company → one tenant bump.
+        const tenant = await this.tenantOf(membershipUuid);
+        await this.records.delete('company_membership', membershipUuid);
+        await this.bumpTenants([tenant]);
+    }
+};
+exports.MembershipService = MembershipService;
+exports.MembershipService = MembershipService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Optional)()),
+    __param(1, (0, common_1.Inject)(posting_version_bump_js_1.POSTING_VERSION_BUMP)),
+    __metadata("design:paramtypes", [engine_1.RecordsService, Object])
+], MembershipService);

package/dist/features/membership/posting-version-bump.d.ts

@@ -0,0 +1,10 @@
+/**
+ * PostingVersionBump — the seam the membership/posting services call after a change to bump the
+ * tenant's permission version (ADR-0011), so a role gain/loss lands in authorization WITHOUT
+ * re-login. Injected @Optional() — absent (unit tests) = no bump = prior behavior.
+ */
+export interface PostingVersionBump {
+    bumpTenant(tenantUuid: string): Promise<void>;
+}
+export declare const POSTING_VERSION_BUMP: unique symbol;
+//# sourceMappingURL=posting-version-bump.d.ts.map

package/dist/features/membership/posting-version-bump.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"posting-version-bump.d.ts","sourceRoot":"","sources":["../../../src/features/membership/posting-version-bump.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED,eAAO,MAAM,oBAAoB,eAAiC,CAAC"}

package/dist/features/membership/posting-version-bump.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POSTING_VERSION_BUMP = void 0;
+exports.POSTING_VERSION_BUMP = Symbol('POSTING_VERSION_BUMP');

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

@@ -0,0 +1,59 @@
+/**
+ * PostingService — the ATOMIC replace-set of a membership's postings (Phase 3, Task 4),
+ * built on the injected RecordsService facade (→ the engine pipe). A posting is a bundled, time-bounded assignment:
+ * a role (+ optional department + optional branch) with an optional effective window.
+ * The Assignments editor submits the FULL desired row set for a membership; this service
+ * diffs current-vs-desired and applies the minimal change — delete only what's removed,
+ * create only what's added, keep the rest untouched.
+ *
+ * ── Atomicity / mid-op safety (why delete-then-create is safe here) ──────────────────
+ * The engine's feature-facing surface (`RecordsService`) exposes NO cross-call transaction
+ * — each of its methods (create/update/delete/list/get) runs in its OWN transaction, and
+ * no `externalQueryRunner` seam is handed to features. So `replacePostings` cannot wrap
+ * the whole diff in a single DB transaction. Instead it is safe BY CONSTRUCTION:
+ *   - Deletes target ONLY rows absent from `desired` (the "removed" set). A KEPT posting
+ *     is never a delete target, so it is never removed.
+ *   - Creates target ONLY rows absent from `current` (the "added" set).
+ * Therefore the membership NEVER lands empty mid-op: even if a create fails after the
+ * delete phase, every kept posting is still present (never deleted). Ordering is
+ * delete-first, then create; a failure surfaces to the caller (fail-closed) with the
+ * kept set intact. (Covered by the mid-op-safety tests in posting.service.spec.ts.)
+ */
+import { RecordsService, type RecordView } from '@astram/engine';
+import { type PostingVersionBump } from './posting-version-bump.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
+ * type=date>`), an ISO datetime, an epoch-ms number, or `null` (open-ended). They are
+ * normalized to epoch-ms integers before the engine writes them (see `toEpochMs`).
+ */
+export interface PostingInput {
+    roleUuid: string;
+    departmentUuid?: string | null;
+    branchUuid?: string | null;
+    effectiveFrom?: string | number | null;
+    effectiveUntil?: string | number | null;
+}
+export declare class PostingService {
+    private readonly records;
+    private readonly versionBump?;
+    constructor(records: RecordsService, versionBump?: (PostingVersionBump | null) | undefined);
+    /** List a membership's postings (tenant-scoped by the pipe). */
+    listPostings(membershipUuid: string): Promise<readonly RecordView[]>;
+    /**
+     * Replace a membership's full posting set with `desired`, applying the minimal diff.
+     * Compares current vs desired by the natural key `roleUuid|departmentUuid|branchUuid`:
+     * deletes removed rows, creates added rows, leaves kept rows untouched. See the file
+     * header for the atomicity / mid-op-safety reasoning (delete-then-create is safe because
+     * kept postings are never delete targets, so the membership never lands empty).
+     */
+    replacePostings(membershipUuid: string, desired: readonly PostingInput[]): Promise<void>;
+    /**
+     * Resolve the tenant (company uuid) a membership belongs to — the tenant whose permission
+     * version a posting change must bump. Reads the parent `company_membership` through the
+     * pipe (tenant-scoped, no raw SQL), returning `companyUuid` or `null` if unresolvable
+     * (then no bump — fail-safe; never guesses a tenant).
+     */
+    private resolveMembershipTenant;
+}
+//# sourceMappingURL=posting.service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"posting.service.d.ts","sourceRoot":"","sources":["../../../src/features/membership/posting.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAAwB,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE1F;;;;;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;AA4DD,qBACa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAKxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;gBALZ,OAAO,EAAE,cAAc,EAKvB,WAAW,CAAC,GAAE,kBAAkB,GAAG,IAAI,aAAA;IAG1D,gEAAgE;IAC1D,YAAY,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC;IAK1E;;;;;;OAMG;IACG,eAAe,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA4D9F;;;;;OAKG;YACW,uBAAuB;CAStC"}

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

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * PostingService — the ATOMIC replace-set of a membership's postings (Phase 3, Task 4),
+ * built on the injected RecordsService facade (→ the engine pipe). A posting is a bundled, time-bounded assignment:
+ * a role (+ optional department + optional branch) with an optional effective window.
+ * The Assignments editor submits the FULL desired row set for a membership; this service
+ * diffs current-vs-desired and applies the minimal change — delete only what's removed,
+ * create only what's added, keep the rest untouched.
+ *
+ * ── Atomicity / mid-op safety (why delete-then-create is safe here) ──────────────────
+ * The engine's feature-facing surface (`RecordsService`) exposes NO cross-call transaction
+ * — each of its methods (create/update/delete/list/get) runs in its OWN transaction, and
+ * no `externalQueryRunner` seam is handed to features. So `replacePostings` cannot wrap
+ * the whole diff in a single DB transaction. Instead it is safe BY CONSTRUCTION:
+ *   - Deletes target ONLY rows absent from `desired` (the "removed" set). A KEPT posting
+ *     is never a delete target, so it is never removed.
+ *   - Creates target ONLY rows absent from `current` (the "added" set).
+ * Therefore the membership NEVER lands empty mid-op: even if a create fails after the
+ * delete phase, every kept posting is still present (never deleted). Ordering is
+ * delete-first, then create; a failure surfaces to the caller (fail-closed) with the
+ * kept set intact. (Covered by the mid-op-safety tests in posting.service.spec.ts.)
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostingService = void 0;
+const common_1 = require("@nestjs/common");
+const engine_1 = require("@astram/engine");
+const posting_version_bump_js_1 = require("./posting-version-bump.js");
+/** The field keys whose values are effective-window epoch-ms bounds (normalized on write). */
+const WINDOW_KEYS = new Set(['effectiveFrom', 'effectiveUntil']);
+/**
+ * Normalize an effective-window bound to epoch-ms (a `number`), or `null` if empty/unparseable.
+ * The membership_posting object declares these fields as `number` (BIGINT epoch-ms) so the
+ * engine binds an INTEGER, never a driver-serialized `Date` — the timezone-immune fix. A bare
+ * `YYYY-MM-DD` (the native date input) is parsed by `Date.parse` as UTC midnight (per the ES
+ * spec's date-only form), so the stored instant is timezone-stable regardless of host tz.
+ */
+function toEpochMs(value) {
+    if (value === null || value === undefined || value === '')
+        return null;
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === 'string') {
+        const ms = Date.parse(value);
+        return Number.isNaN(ms) ? null : ms;
+    }
+    return null;
+}
+/** The identity a human calls "the same posting": role + optional dept + optional branch. */
+function naturalKey(p) {
+    return `${p.roleUuid}|${p.departmentUuid ?? ''}|${p.branchUuid ?? ''}`;
+}
+/**
+ * Build the engine field map from a desired posting, dropping empty optionals and
+ * normalizing the effective-window bounds to epoch-ms integers.
+ *
+ * Two concerns:
+ *  1. Drop `undefined`/`null`/`''` optional keys. This is load-bearing: the editor submits
+ *     `departmentUuid`/`branchUuid`/`effectiveFrom`/`effectiveUntil` as `null`/`''` for an
+ *     empty (company-wide / open-ended) posting, but the engine's validate stage runs its
+ *     type-coercer on any PRESENT column and REJECTS `null`. Omitting the key entirely makes
+ *     the stage skip it (absent + optional → no coercion), so the column defaults to SQL NULL
+ *     — exactly what a company-wide / no-expiry posting means.
+ *  2. Convert the window bounds (`effectiveFrom`/`effectiveUntil`) from the client's date
+ *     string / ISO / number to epoch-ms via `toEpochMs`, because the object declares them as
+ *     `number` (BIGINT epoch-ms) — the timezone-immune storage. An unparseable/empty bound
+ *     is dropped (→ SQL NULL = open-ended), never coerced to a bogus number.
+ */
+function stripEmpty(input) {
+    const out = {};
+    for (const [k, v] of Object.entries(input)) {
+        if (WINDOW_KEYS.has(k)) {
+            const ms = toEpochMs(v);
+            if (ms !== null)
+                out[k] = ms; // else omit → SQL NULL (open-ended)
+            continue;
+        }
+        if (v !== undefined && v !== null && v !== '')
+            out[k] = v;
+    }
+    return out;
+}
+let PostingService = class PostingService {
+    records;
+    versionBump;
+    constructor(records, versionBump) {
+        this.records = records;
+        this.versionBump = versionBump;
+    }
+    /** List a membership's postings (tenant-scoped by the pipe). */
+    async listPostings(membershipUuid) {
+        const page = await this.records.list('membership_posting', { where: { membershipUuid } });
+        return page.rows;
+    }
+    /**
+     * Replace a membership's full posting set with `desired`, applying the minimal diff.
+     * Compares current vs desired by the natural key `roleUuid|departmentUuid|branchUuid`:
+     * deletes removed rows, creates added rows, leaves kept rows untouched. See the file
+     * header for the atomicity / mid-op-safety reasoning (delete-then-create is safe because
+     * kept postings are never delete targets, so the membership never lands empty).
+     */
+    async replacePostings(membershipUuid, desired) {
+        const current = (await this.records.list('membership_posting', { where: { membershipUuid } })).rows;
+        const desiredKeys = new Set(desired.map(naturalKey));
+        const currentKeys = new Set(current.map((r) => naturalKey(r.fields)));
+        // Track whether the diff actually changed anything — only a real add/remove of a role
+        // assignment need invalidate cached permission facts (a no-op replace must not bump).
+        let changed = false;
+        // Delete removed: rows in current whose key is not in desired. Kept rows are skipped.
+        for (const r of current) {
+            const key = naturalKey(r.fields);
+            if (!desiredKeys.has(key)) {
+                await this.records.delete('membership_posting', r.id);
+                changed = true;
+            }
+        }
+        // Create added: desired rows whose key is not already present. Only real fields are
+        // sent (undefined/null/empty optionals are dropped so the engine gets a clean field map).
+        for (const d of desired) {
+            if (!currentKeys.has(naturalKey(d))) {
+                await this.records.create('membership_posting', {
+                    fields: { membershipUuid, ...stripEmpty(d) },
+                });
+                changed = true;
+            }
+        }
+        // ADR-0011 STALENESS FIX: a posting add/remove changes the effective roles (→ coarse
+        // grants) of the membership's user in that company, so bump the tenant's permission
+        // version — every live session in that tenant then reloads its cached facts on the next
+        // request (a role gain/loss lands within the version bound). Only when something actually
+        // changed, and only when the bump collaborator is wired (absent in unit tests → no-op).
+        // Best-effort + fail-safe: the posting write already succeeded, so a bump failure must
+        // NOT surface as a 500 that hides a successful assignment change — the cache is instead
+        // invalidated by the next legit bump / the facts' natural TTL. We log-swallow it.
+        if (changed && this.versionBump) {
+            const tenantUuid = await this.resolveMembershipTenant(membershipUuid);
+            if (tenantUuid) {
+                try {
+                    await this.versionBump.bumpTenant(tenantUuid);
+                }
+                catch {
+                    // Fail-safe: never fail an applied posting change on a version-bump hiccup.
+                }
+            }
+        }
+    }
+    /**
+     * Resolve the tenant (company uuid) a membership belongs to — the tenant whose permission
+     * version a posting change must bump. Reads the parent `company_membership` through the
+     * pipe (tenant-scoped, no raw SQL), returning `companyUuid` or `null` if unresolvable
+     * (then no bump — fail-safe; never guesses a tenant).
+     */
+    async resolveMembershipTenant(membershipUuid) {
+        try {
+            const m = await this.records.get('company_membership', membershipUuid);
+            const companyUuid = m?.fields?.companyUuid;
+            return typeof companyUuid === 'string' && companyUuid.length > 0 ? companyUuid : null;
+        }
+        catch {
+            return null;
+        }
+    }
+};
+exports.PostingService = PostingService;
+exports.PostingService = PostingService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Optional)()),
+    __param(1, (0, common_1.Inject)(posting_version_bump_js_1.POSTING_VERSION_BUMP)),
+    __metadata("design:paramtypes", [engine_1.RecordsService, Object])
+], PostingService);

package/dist/features/org-structure/org-catalog.controller.d.ts

@@ -0,0 +1,14 @@
+import { OrgCatalogService } from './org-catalog.service.js';
+export declare class OrgCatalogController {
+    private readonly catalog;
+    constructor(catalog: OrgCatalogService);
+    /** A company's departments as `{ uuid, name }` options for the posting editor. */
+    listCompanyDepartments(companyUuid: string): Promise<{
+        rows: import("../shared/named-option.js").NamedOption[];
+    }>;
+    /** A company's branches as `{ uuid, name }` options for the posting editor. */
+    listCompanyBranches(companyUuid: string): Promise<{
+        rows: import("../shared/named-option.js").NamedOption[];
+    }>;
+}
+//# sourceMappingURL=org-catalog.controller.d.ts.map

package/dist/features/org-structure/org-catalog.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"org-catalog.controller.d.ts","sourceRoot":"","sources":["../../../src/features/org-structure/org-catalog.controller.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAU7D,qBACa,oBAAoB;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,iBAAiB;IAEvD,kFAAkF;IAG5E,sBAAsB,CAAuB,WAAW,EAAE,MAAM;;;IAKtE,+EAA+E;IAGzE,mBAAmB,CAAuB,WAAW,EAAE,MAAM;;;CAIpE"}

package/dist/features/org-structure/org-catalog.controller.js

@@ -0,0 +1,62 @@
+"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);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrgCatalogController = void 0;
+const common_1 = require("@nestjs/common");
+const guard_1 = require("@astram/guard");
+const org_catalog_service_js_1 = require("./org-catalog.service.js");
+// ── Company-scoped catalogs (dept/branch option lists for the posting editor) ──
+//
+// These back the Assignments editor's company-scoped Department/Branch dropdowns.
+// Each returns `{ rows: [{ uuid, name }] }` — the uuid is the option VALUE the client
+// stores, the name is the display LABEL. Read through the pipe (list the
+// company_department/company_branch junction → resolve each catalog uuid to a name in
+// the service), so no raw uuid is ever a label.
+let OrgCatalogController = class OrgCatalogController {
+    catalog;
+    constructor(catalog) {
+        this.catalog = catalog;
+    }
+    /** A company's departments as `{ uuid, name }` options for the posting editor. */
+    async listCompanyDepartments(companyUuid) {
+        const rows = await this.catalog.listCompanyDepartments(companyUuid);
+        return { rows };
+    }
+    /** A company's branches as `{ uuid, name }` options for the posting editor. */
+    async listCompanyBranches(companyUuid) {
+        const rows = await this.catalog.listCompanyBranches(companyUuid);
+        return { rows };
+    }
+};
+exports.OrgCatalogController = OrgCatalogController;
+__decorate([
+    (0, common_1.Get)('companies/:companyUuid/departments'),
+    (0, guard_1.Classified)({ typeKey: 'company_department', action: 'read' }),
+    __param(0, (0, common_1.Param)('companyUuid')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], OrgCatalogController.prototype, "listCompanyDepartments", null);
+__decorate([
+    (0, common_1.Get)('companies/:companyUuid/branches'),
+    (0, guard_1.Classified)({ typeKey: 'company_branch', action: 'read' }),
+    __param(0, (0, common_1.Param)('companyUuid')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], OrgCatalogController.prototype, "listCompanyBranches", null);
+exports.OrgCatalogController = OrgCatalogController = __decorate([
+    (0, common_1.Controller)('identity'),
+    __metadata("design:paramtypes", [org_catalog_service_js_1.OrgCatalogService])
+], OrgCatalogController);

package/dist/features/org-structure/org-catalog.service.d.ts

@@ -0,0 +1,19 @@
+/**
+ * OrgCatalogService — company-scoped Department/Branch OPTION lists for the Assignments
+ * editor dropdowns, via the RecordsService facade (no actor threading). Reads the
+ * company_department/company_branch junctions and resolves each catalog uuid → display
+ * name (never a raw uuid label). No raw SQL.
+ */
+import { RecordsService } from '@astram/engine';
+import { type NamedOption } from '../shared/named-option.js';
+export declare class OrgCatalogService {
+    private readonly records;
+    constructor(records: RecordsService);
+    /** A company's departments as `{ uuid, name }` options for the posting editor. */
+    listCompanyDepartments(companyUuid: string): Promise<NamedOption[]>;
+    /** A company's branches as `{ uuid, name }` options for the posting editor. */
+    listCompanyBranches(companyUuid: string): Promise<NamedOption[]>;
+    /** Shared reader for a company-scoped catalog junction; lists then name-resolves. */
+    private listCompanyCatalog;
+}
+//# sourceMappingURL=org-catalog.service.d.ts.map

package/dist/features/org-structure/org-catalog.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"org-catalog.service.d.ts","sourceRoot":"","sources":["../../../src/features/org-structure/org-catalog.service.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,qBACa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAEpD,kFAAkF;IAClF,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAInE,+EAA+E;IAC/E,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAIhE,qFAAqF;YACvE,kBAAkB;CAiBjC"}

package/dist/features/org-structure/org-catalog.service.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * OrgCatalogService — company-scoped Department/Branch OPTION lists for the Assignments
+ * editor dropdowns, via the RecordsService facade (no actor threading). Reads the
+ * company_department/company_branch junctions and resolves each catalog uuid → display
+ * name (never a raw uuid label). No raw SQL.
+ */
+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.OrgCatalogService = void 0;
+const common_1 = require("@nestjs/common");
+const engine_1 = require("@astram/engine");
+let OrgCatalogService = class OrgCatalogService {
+    records;
+    constructor(records) {
+        this.records = records;
+    }
+    /** A company's departments as `{ uuid, name }` options for the posting editor. */
+    listCompanyDepartments(companyUuid) {
+        return this.listCompanyCatalog('company_department', 'departmentUuid', 'department', companyUuid);
+    }
+    /** A company's branches as `{ uuid, name }` options for the posting editor. */
+    listCompanyBranches(companyUuid) {
+        return this.listCompanyCatalog('company_branch', 'branchUuid', 'branch', companyUuid);
+    }
+    /** Shared reader for a company-scoped catalog junction; lists then name-resolves. */
+    async listCompanyCatalog(junctionTypeKey, refFieldKey, catalogTypeKey, companyUuid) {
+        const page = await this.records.list(junctionTypeKey, { where: { companyUuid } });
+        const options = [];
+        for (const row of page.rows) {
+            const refUuid = row.fields[refFieldKey];
+            if (typeof refUuid !== 'string' || refUuid.length === 0)
+                continue;
+            const view = await this.records.get(catalogTypeKey, refUuid);
+            const name = view?.fields?.name;
+            options.push({ uuid: refUuid, name: typeof name === 'string' && name.length > 0 ? name : '(unknown)' });
+        }
+        return options;
+    }
+};
+exports.OrgCatalogService = OrgCatalogService;
+exports.OrgCatalogService = OrgCatalogService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [engine_1.RecordsService])
+], OrgCatalogService);

package/dist/features/role/role.controller.d.ts

@@ -0,0 +1,37 @@
+import { RoleService } from './role.service.js';
+import { type ListQueryDto } from '../shared/list-query.js';
+export declare class RoleController {
+    private readonly roles;
+    constructor(roles: RoleService);
+    /**
+     * List roles — gated on `identity:role:read` (see class doc). Server-side DataTable:
+     * `?page&limit&search&sortBy&sortOrder`. Returns `{ total, rows, page, limit }` —
+     * `total` reflects the FILTERED set so the client can page the true result count.
+     */
+    listRoles(query: ListQueryDto): Promise<{
+        total: number;
+        rows: readonly import("packages/engine/dist/types.js").RecordView[];
+        page: number;
+        limit: number;
+    }>;
+    /** Create a role — gated on `identity:role:create`. */
+    createRole(body: {
+        name?: string;
+    }): Promise<{
+        id: import("packages/engine/dist/types.js").RecordId;
+    }>;
+    /** Read one role — gated on `identity:role:read` (CONTROL-plane; root, the identity
+     *  administrator, may read roles). */
+    getRole(uuid: string): Promise<import("packages/engine/dist/types.js").RecordView | null>;
+    /** Update a role — gated on `identity:role:update`. */
+    updateRole(uuid: string, body: {
+        name?: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+    /** Delete a role — gated on `identity:role:delete`. */
+    deleteRole(uuid: string): Promise<{
+        success: boolean;
+    }>;
+}
+//# sourceMappingURL=role.controller.d.ts.map

package/dist/features/role/role.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role.controller.d.ts","sourceRoot":"","sources":["../../../src/features/role/role.controller.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAK5E,qBACa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,WAAW;IAE/C;;;;OAIG;IAGG,SAAS,CAAU,KAAK,EAAE,YAAY;;;;;;IAM5C,uDAAuD;IAGjD,UAAU,CAAS,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAKhD;0CACsC;IAGtC,OAAO,CAAgB,IAAI,EAAE,MAAM;IAInC,uDAAuD;IAGjD,UAAU,CAAgB,IAAI,EAAE,MAAM,EAAU,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAK7E,uDAAuD;IAGjD,UAAU,CAAgB,IAAI,EAAE,MAAM;;;CAI7C"}