@astram/identity 0.16.0 → 0.17.1

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

@@ -1,32 +1,113 @@
 /**
- * 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.
+ * OrgCatalogService — a company's own departments and branches (G-012, spec §5.A), through the
+ * RecordsService facade (the engine pipe: gate, wall, validate, write, audit).
+ *
+ * Ownership (R1): every department/branch row belongs to exactly one company (`companyUuid`,
+ * immutable), stamped here from the reached company, never from a request body; its one junction
+ * row (`company_department` / `company_branch`) is written in the same transaction (R4).
+ *
+ * Wall (R2): every route reaches the company or the row through the engine's subtree `readScope`
+ * first; out of reach ⇒ {@link IdentityNotFoundError} (404, never a 403 that reveals existence).
+ *
+ * Races (R3): create/rename/delete lock first (`lockForUpdate`), then re-read through the wall and
+ * check under the lock; the per-company unique index is the backstop (a driver 1062 ⇒ the same 409).
+ *
+ * The one raw statement (R7) is the delete's fixed, parameterised, read-only in-use `COUNT(*)` on
+ * the engine transaction's own connection: complete (no record policy can narrow it), after the row
+ * lock, so a concurrent posting add (which locks the same row, `PostingService`) is either counted
+ * or refused.
  */
 import { RecordsService } from '@astram/engine';
-import { type NamedOption } from '../shared/named-option.js';
+import type { FrameworkSchemas } from '@astram/core';
+import { type ListQueryDto } from '../shared/list-query.js';
+/** Most departments (and, separately, branches) one company may hold (spec §10). */
+export declare const ORG_UNIT_CAP = 1000;
+/** One department/branch option: `uuid` is the option value, `name` the label (never a uuid). */
+export interface OrgUnitOption {
+    uuid: string;
+    name: string;
+    /** Postings the caller can see that reference this row; omitted when it cannot read postings. */
+    usedBy?: number;
+}
+/** A company's departments or branches: one page, or every row (up to the cap). */
+export interface OrgUnitList {
+    rows: OrgUnitOption[];
+    total: number;
+    page: number;
+    limit: number;
+}
 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[]>;
+    private readonly schemas?;
+    constructor(records: RecordsService, schemas?: (FrameworkSchemas | null) | undefined);
+    /** A company's own departments (404 when the company is out of reach). */
+    listCompanyDepartments(companyUuid: string, query?: ListQueryDto): Promise<OrgUnitList>;
+    /** A company's own branches (404 when the company is out of reach). */
+    listCompanyBranches(companyUuid: string, query?: ListQueryDto): Promise<OrgUnitList>;
+    createDepartment(companyUuid: string, name: unknown): Promise<{
+        uuid: string;
+        name: string;
+    }>;
+    createBranch(companyUuid: string, name: unknown): Promise<{
+        uuid: string;
+        name: string;
+    }>;
+    renameDepartment(uuid: string, name: unknown): Promise<void>;
+    renameBranch(uuid: string, name: unknown): Promise<void>;
+    deleteDepartment(uuid: string): Promise<void>;
+    deleteBranch(uuid: string): Promise<void>;
     /**
-     * The id of the catalog row named `name`, creating it when none exists (G-009 R5). The catalog
-     * is global, so the lookup is by name; the create runs through the engine pipe like any write.
+     * The id of `companyUuid`'s department named `name` (normalised, spec §10), creating it with its
+     * owner and junction row when absent (org bootstrap, G-009 R5). A found row gets its junction
+     * row back if it lacks one (idempotent re-runs). Reads no company (the bootstrap's org-units step
+     * holds no company key), so the company is not walled here: the engine's create wall is.
      */
-    ensureDepartment(name: string): Promise<string>;
-    /** The id of the branch named `name`, creating it when none exists. */
-    ensureBranch(name: string): Promise<string>;
+    ensureDepartment(companyUuid: string, name: string): Promise<string>;
+    /** The id of `companyUuid`'s branch named `name`, creating it when absent. */
+    ensureBranch(companyUuid: string, name: string): Promise<string>;
     /** Link a department to a company (the junction row); idempotent. */
     attachDepartment(companyUuid: string, departmentUuid: string): Promise<void>;
     /** Link a branch to a company (the junction row); idempotent. */
     attachBranch(companyUuid: string, branchUuid: string): Promise<void>;
-    private ensureCatalogRow;
+    private validName;
+    private listUnits;
+    /**
+     * `usedBy` (NAES review #3/A): ONE engine aggregate over `membership_posting`, grouped by the
+     * unit, over exactly the returned ids. Gated as a posting read: a caller who cannot read postings
+     * gets the rows without `usedBy` (only `AuthorizationDeniedError` is caught); any other failure
+     * (`EngineUnavailableError` ⇒ 503) fails the request, never silently drops the counts.
+     */
+    private withUsedBy;
+    private createUnit;
+    private renameUnit;
+    private deleteUnit;
+    /**
+     * Lock the row FIRST, then re-read it through the wall (404 when out of reach or gone). A legacy
+     * row with no owner is root-only (the wall already hides it from a non-root; checked again here).
+     */
+    private lockAndReach;
+    /** Duplicate check, cap, then the row and its junction row, on the caller's transaction. */
+    private insertUnit;
+    /**
+     * Refuse a name another row of the same company already holds. The engine's equality runs under
+     * the column collation (`utf8mb4_unicode_ci`: case, accents and width fold), so "Qualite" finds
+     * "Qualité"; the 409 names the STORED clashing row.
+     */
+    private assertNameFree;
+    private findByName;
+    private duplicate;
+    /**
+     * Run a create/rename; a driver duplicate key (the per-company unique index, the backstop for a
+     * concurrent write) becomes the same 409 naming the stored row. Errno only: the driver's message
+     * holds the value and is never echoed (KI #87).
+     */
+    private mappingDuplicates;
+    /**
+     * The complete in-use count (spec §5.A, NAES third pass): one fixed framework statement on the
+     * engine transaction's own connection, after the row lock. Any failure ⇒ 503, nothing deleted.
+     */
+    private countPostings;
+    private ensureUnit;
     private attachJunction;
-    /** 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

@@ -1 +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,EAAiB,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAQ7D,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;IASnE,+EAA+E;IAC/E,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAIhE;;;OAGG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI/C,uEAAuE;IACvE,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI3C,qEAAqE;IACrE,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5E,iEAAiE;IACjE,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAItD,gBAAgB;YAOhB,cAAc;IAa5B,qFAAqF;YACvE,kBAAkB;CAoBjC"}
+{"version":3,"file":"org-catalog.service.d.ts","sourceRoot":"","sources":["../../../src/features/org-structure/org-catalog.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAEL,cAAc,EAMf,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAS5E,oFAAoF;AACpF,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,iGAAiG;AACjG,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,iGAAiG;IACjG,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,aAAa,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AA8DD,qBACa,iBAAiB;IAE1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAKxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;gBALR,OAAO,EAAE,cAAc,EAKvB,OAAO,CAAC,GAAE,gBAAgB,GAAG,IAAI,aAAA;IAKpD,0EAA0E;IAC1E,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAIvF,uEAAuE;IACvE,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAMpF,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAI7F,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAIzF,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5D,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxD,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMzC;;;;;OAKG;IACH,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIpE,8EAA8E;IAC9E,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIhE,qEAAqE;IACrE,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5E,iEAAiE;IACjE,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpE,OAAO,CAAC,SAAS;YAMH,SAAS;IAsCvB;;;;;OAKG;YACW,UAAU;YAwBV,UAAU;YAyBV,UAAU;YAkBV,UAAU;IAWxB;;;OAGG;YACW,YAAY;IAW1B,4FAA4F;YAC9E,UAAU;IAoBxB;;;;OAIG;YACW,cAAc;YAWd,UAAU;IAaxB,OAAO,CAAC,SAAS;IAMjB;;;;OAIG;YACW,iBAAiB;IAqB/B;;;OAGG;YACW,aAAa;YAiBb,UAAU;YAgBV,cAAc;CAc7B"}

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

@@ -1,9 +1,22 @@
 "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.
+ * OrgCatalogService — a company's own departments and branches (G-012, spec §5.A), through the
+ * RecordsService facade (the engine pipe: gate, wall, validate, write, audit).
+ *
+ * Ownership (R1): every department/branch row belongs to exactly one company (`companyUuid`,
+ * immutable), stamped here from the reached company, never from a request body; its one junction
+ * row (`company_department` / `company_branch`) is written in the same transaction (R4).
+ *
+ * Wall (R2): every route reaches the company or the row through the engine's subtree `readScope`
+ * first; out of reach ⇒ {@link IdentityNotFoundError} (404, never a 403 that reveals existence).
+ *
+ * Races (R3): create/rename/delete lock first (`lockForUpdate`), then re-read through the wall and
+ * check under the lock; the per-company unique index is the backstop (a driver 1062 ⇒ the same 409).
+ *
+ * The one raw statement (R7) is the delete's fixed, parameterised, read-only in-use `COUNT(*)` on
+ * the engine transaction's own connection: complete (no record policy can narrow it), after the row
+ * lock, so a concurrent posting add (which locks the same row, `PostingService`) is either counted
+ * or refused.
  */
 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;
@@ -14,83 +27,346 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 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.OrgCatalogService = void 0;
+exports.OrgCatalogService = exports.ORG_UNIT_CAP = void 0;
 const common_1 = require("@nestjs/common");
 const engine_1 = require("@astram/engine");
+const internal_1 = require("@astram/engine/internal");
+const framework_schemas_token_js_1 = require("../framework-schemas.token.js");
+const list_query_js_1 = require("../shared/list-query.js");
+const identity_errors_js_1 = require("../shared/identity-errors.js");
+const org_unit_name_js_1 = require("./org-unit-name.js");
+/** Most departments (and, separately, branches) one company may hold (spec §10). */
+exports.ORG_UNIT_CAP = 1000;
+const DEPARTMENT = {
+    kind: 'department',
+    typeKey: 'department',
+    junctionTypeKey: 'company_department',
+    refFieldKey: 'departmentUuid',
+    postingColumn: 'mp_department_uuid',
+    plural: 'departments',
+};
+const BRANCH = {
+    kind: 'branch',
+    typeKey: 'branch',
+    junctionTypeKey: 'company_branch',
+    refFieldKey: 'branchUuid',
+    postingColumn: 'mp_branch_uuid',
+    plural: 'branches',
+};
+const IN_USE = 'Still used by one or more assignments; move them first.';
+const COUNT_UNAVAILABLE = 'Could not check whether it is still in use; nothing was deleted. Try again.';
 /** Department/branch rows have a single uuid key; a composite id here is a wiring defect. */
 function catalogId(id) {
     if (typeof id !== 'string')
         throw new TypeError('catalog row id is not a single uuid');
     return id;
 }
+/** A driver duplicate-key error, by errno/code only (its message names the value: never echoed). */
+function isDuplicateKey(err) {
+    if (typeof err !== 'object' || err === null)
+        return false;
+    const e = err;
+    return e.errno === 1062 || e.code === 'ER_DUP_ENTRY';
+}
+const present = (v) => typeof v === 'string' && v.trim().length > 0;
+function nameOf(view) {
+    const name = view.fields?.name;
+    return typeof name === 'string' && name.length > 0 ? name : '(unknown)';
+}
+function ownerOf(view) {
+    const owner = view.fields?.companyUuid;
+    return typeof owner === 'string' && owner.length > 0 ? owner : null;
+}
 let OrgCatalogService = class OrgCatalogService {
     records;
-    constructor(records) {
+    schemas;
+    constructor(records, schemas) {
         this.records = records;
+        this.schemas = schemas;
+    }
+    // ------------------------------------------------------------------------------- lists
+    /** A company's own departments (404 when the company is out of reach). */
+    listCompanyDepartments(companyUuid, query) {
+        return this.listUnits(DEPARTMENT, companyUuid, query);
     }
-    /** 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 own branches (404 when the company is out of reach). */
+    listCompanyBranches(companyUuid, query) {
+        return this.listUnits(BRANCH, companyUuid, query);
     }
-    /** A company's branches as `{ uuid, name }` options for the posting editor. */
-    listCompanyBranches(companyUuid) {
-        return this.listCompanyCatalog('company_branch', 'branchUuid', 'branch', companyUuid);
+    // ------------------------------------------------------------------------------- writes
+    createDepartment(companyUuid, name) {
+        return this.createUnit(DEPARTMENT, companyUuid, name);
     }
+    createBranch(companyUuid, name) {
+        return this.createUnit(BRANCH, companyUuid, name);
+    }
+    renameDepartment(uuid, name) {
+        return this.renameUnit(DEPARTMENT, uuid, name);
+    }
+    renameBranch(uuid, name) {
+        return this.renameUnit(BRANCH, uuid, name);
+    }
+    deleteDepartment(uuid) {
+        return this.deleteUnit(DEPARTMENT, uuid);
+    }
+    deleteBranch(uuid) {
+        return this.deleteUnit(BRANCH, uuid);
+    }
+    // ------------------------------------------------------------------------------- bootstrap
     /**
-     * The id of the catalog row named `name`, creating it when none exists (G-009 R5). The catalog
-     * is global, so the lookup is by name; the create runs through the engine pipe like any write.
+     * The id of `companyUuid`'s department named `name` (normalised, spec §10), creating it with its
+     * owner and junction row when absent (org bootstrap, G-009 R5). A found row gets its junction
+     * row back if it lacks one (idempotent re-runs). Reads no company (the bootstrap's org-units step
+     * holds no company key), so the company is not walled here: the engine's create wall is.
      */
-    ensureDepartment(name) {
-        return this.ensureCatalogRow('department', name);
+    ensureDepartment(companyUuid, name) {
+        return this.ensureUnit(DEPARTMENT, companyUuid, name);
     }
-    /** The id of the branch named `name`, creating it when none exists. */
-    ensureBranch(name) {
-        return this.ensureCatalogRow('branch', name);
+    /** The id of `companyUuid`'s branch named `name`, creating it when absent. */
+    ensureBranch(companyUuid, name) {
+        return this.ensureUnit(BRANCH, companyUuid, name);
     }
     /** Link a department to a company (the junction row); idempotent. */
     attachDepartment(companyUuid, departmentUuid) {
-        return this.attachJunction('company_department', 'departmentUuid', companyUuid, departmentUuid);
+        return this.attachJunction(DEPARTMENT, companyUuid, departmentUuid);
     }
     /** Link a branch to a company (the junction row); idempotent. */
     attachBranch(companyUuid, branchUuid) {
-        return this.attachJunction('company_branch', 'branchUuid', companyUuid, branchUuid);
-    }
-    async ensureCatalogRow(typeKey, name) {
-        const page = await this.records.list(typeKey, { where: { name } });
-        const existing = page.rows[0];
-        if (existing !== undefined)
-            return catalogId(existing.id);
-        return catalogId(await this.records.create(typeKey, { fields: { name } }));
-    }
-    async attachJunction(junctionTypeKey, refFieldKey, companyUuid, refUuid) {
-        const page = await this.records.list(junctionTypeKey, { where: { companyUuid } });
-        if (page.rows.some((r) => r.fields[refFieldKey] === refUuid))
-            return;
-        await this.records.create(junctionTypeKey, {
-            fields: { companyUuid, [refFieldKey]: refUuid },
+        return this.attachJunction(BRANCH, companyUuid, branchUuid);
+    }
+    // ------------------------------------------------------------------------------- internals
+    validName(spec, raw) {
+        const result = (0, org_unit_name_js_1.normaliseOrgUnitName)(raw);
+        if (!result.ok)
+            throw new identity_errors_js_1.IdentityBadRequestError((0, org_unit_name_js_1.orgUnitNameMessage)(spec.kind, result.reason));
+        return result.value;
+    }
+    async listUnits(spec, companyUuid, query) {
+        // Reach the company through the subtree wall first (NAES review B): 404 when out of reach.
+        const company = await this.records.get('company', companyUuid);
+        if (company === null)
+            throw new identity_errors_js_1.IdentityNotFoundError('Company not found.');
+        const owner = catalogId(company.id);
+        const paged = present(query?.page) || present(query?.limit) || present(query?.search);
+        let page = 1;
+        let limit = exports.ORG_UNIT_CAP;
+        const listQuery = {
+            where: { companyUuid: owner },
+            sortBy: 'name',
+            sortOrder: 'asc',
+            limit: exports.ORG_UNIT_CAP,
+            offset: 0,
+        };
+        if (paged) {
+            const parsed = (0, list_query_js_1.parseListQuery)(query);
+            page = parsed.page;
+            limit = parsed.limit;
+            listQuery.limit = parsed.limit;
+            listQuery.offset = parsed.params.offset ?? 0;
+            if (parsed.params.search !== undefined) {
+                listQuery.search = { fields: ['name'], term: parsed.params.search };
+            }
+        }
+        const result = await this.records.list(spec.typeKey, listQuery);
+        const rows = result.rows.map((r) => ({
+            uuid: catalogId(r.id),
+            name: nameOf(r),
+        }));
+        return { rows: await this.withUsedBy(spec, rows), total: result.total, page, limit };
+    }
+    /**
+     * `usedBy` (NAES review #3/A): ONE engine aggregate over `membership_posting`, grouped by the
+     * unit, over exactly the returned ids. Gated as a posting read: a caller who cannot read postings
+     * gets the rows without `usedBy` (only `AuthorizationDeniedError` is caught); any other failure
+     * (`EngineUnavailableError` ⇒ 503) fails the request, never silently drops the counts.
+     */
+    async withUsedBy(spec, rows) {
+        if (rows.length === 0)
+            return rows;
+        let groups;
+        try {
+            groups = (await this.records.aggregate('membership_posting', {
+                where: { [spec.refFieldKey]: { in: rows.map((r) => r.uuid) } },
+                groupBy: [spec.refFieldKey],
+                measures: [{ fn: 'count', as: 'used_by' }],
+                limit: rows.length,
+            })).groups;
+        }
+        catch (err) {
+            if (err instanceof engine_1.AuthorizationDeniedError)
+                return rows;
+            throw err;
+        }
+        const counts = new Map();
+        for (const g of groups) {
+            const key = g.key[spec.refFieldKey];
+            if (typeof key === 'string')
+                counts.set(key.toLowerCase(), Number(g.values.used_by ?? 0));
+        }
+        return rows.map((r) => ({ ...r, usedBy: counts.get(r.uuid.toLowerCase()) ?? 0 }));
+    }
+    async createUnit(spec, companyUuid, rawName) {
+        const name = this.validName(spec, rawName);
+        let owner = companyUuid;
+        const uuid = await this.mappingDuplicates(spec, () => owner, name, () => this.records.transaction(async (tx) => {
+            // Lock the company FIRST (the snapshot of the reads below is taken after it), then reach
+            // it through the wall: out of reach or gone ⇒ 404.
+            await tx.lockForUpdate('company', companyUuid);
+            const company = await tx.get('company', companyUuid);
+            if (company === null)
+                throw new identity_errors_js_1.IdentityNotFoundError('Company not found.');
+            owner = catalogId(company.id);
+            return this.insertUnit(tx, spec, owner, name);
+        }));
+        return { uuid, name };
+    }
+    async renameUnit(spec, uuid, rawName) {
+        const name = this.validName(spec, rawName);
+        let owner = null;
+        await this.mappingDuplicates(spec, () => owner, name, () => this.records.transaction(async (tx) => {
+            const row = await this.lockAndReach(tx, spec, uuid);
+            owner = ownerOf(row);
+            if (row.fields?.name === name)
+                return; // same name: no write
+            await this.assertNameFree(tx, spec, owner, name, catalogId(row.id));
+            await tx.update(spec.typeKey, row.id, { fields: { name } });
+        }));
+    }
+    async deleteUnit(spec, uuid) {
+        await this.records.transaction(async (tx) => {
+            const row = await this.lockAndReach(tx, spec, uuid);
+            // R5: complete count under the row lock; any posting (visible or not) ⇒ 409, no number.
+            if ((await this.countPostings(tx, spec, catalogId(row.id))) > 0) {
+                throw new identity_errors_js_1.IdentityConflictError(IN_USE);
+            }
+            await tx.delete(spec.typeKey, row.id); // the junction row cascades
+        });
+    }
+    /**
+     * Lock the row FIRST, then re-read it through the wall (404 when out of reach or gone). A legacy
+     * row with no owner is root-only (the wall already hides it from a non-root; checked again here).
+     */
+    async lockAndReach(tx, spec, uuid) {
+        const label = spec.kind === 'department' ? 'Department' : 'Branch';
+        await tx.lockForUpdate(spec.typeKey, uuid);
+        const row = await tx.get(spec.typeKey, uuid);
+        if (row === null)
+            throw new identity_errors_js_1.IdentityNotFoundError(`${label} not found.`);
+        if (ownerOf(row) === null && this.records.requestPrincipal().isRoot !== true) {
+            throw new identity_errors_js_1.IdentityNotFoundError(`${label} not found.`);
+        }
+        return row;
+    }
+    /** Duplicate check, cap, then the row and its junction row, on the caller's transaction. */
+    async insertUnit(tx, spec, owner, name) {
+        await this.assertNameFree(tx, spec, owner, name, undefined);
+        const held = (await tx.list(spec.typeKey, { where: { companyUuid: owner }, limit: 1 })).total;
+        if (held >= exports.ORG_UNIT_CAP) {
+            throw new identity_errors_js_1.IdentityConflictError(`This company already has the maximum of ${exports.ORG_UNIT_CAP} ${spec.plural}.`);
+        }
+        const id = catalogId(await tx.create(spec.typeKey, { fields: { name, companyUuid: owner } }));
+        await tx.create(spec.junctionTypeKey, {
+            fields: { companyUuid: owner, [spec.refFieldKey]: id },
         });
+        return id;
+    }
+    /**
+     * Refuse a name another row of the same company already holds. The engine's equality runs under
+     * the column collation (`utf8mb4_unicode_ci`: case, accents and width fold), so "Qualite" finds
+     * "Qualité"; the 409 names the STORED clashing row.
+     */
+    async assertNameFree(tx, spec, owner, name, self) {
+        const clash = await this.findByName(tx, spec, owner, name, self);
+        if (clash !== undefined)
+            throw this.duplicate(spec, nameOf(clash));
+    }
+    async findByName(reader, spec, owner, name, self) {
+        const rows = (await reader.list(spec.typeKey, { where: { companyUuid: owner, name }, limit: 2 })).rows;
+        return rows.find((r) => self === undefined || catalogId(r.id) !== self);
+    }
+    duplicate(spec, storedName) {
+        return new identity_errors_js_1.IdentityConflictError(`A ${spec.kind} named "${storedName}" already exists in this company.`);
+    }
+    /**
+     * Run a create/rename; a driver duplicate key (the per-company unique index, the backstop for a
+     * concurrent write) becomes the same 409 naming the stored row. Errno only: the driver's message
+     * holds the value and is never echoed (KI #87).
+     */
+    async mappingDuplicates(spec, owner, name, write) {
+        try {
+            return await write();
+        }
+        catch (err) {
+            if (!isDuplicateKey(err))
+                throw err;
+            let stored = name;
+            try {
+                const clash = await this.findByName(this.records, spec, owner(), name);
+                if (clash !== undefined)
+                    stored = nameOf(clash);
+            }
+            catch {
+                // The 409 stands; the submitted name names the clash.
+            }
+            throw this.duplicate(spec, stored);
+        }
     }
-    /** 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)',
-            });
+    /**
+     * The complete in-use count (spec §5.A, NAES third pass): one fixed framework statement on the
+     * engine transaction's own connection, after the row lock. Any failure ⇒ 503, nothing deleted.
+     */
+    async countPostings(tx, spec, id) {
+        const schemas = this.schemas;
+        if (!schemas)
+            throw new identity_errors_js_1.IdentityUnavailableError(COUNT_UNAVAILABLE);
+        let n;
+        try {
+            const rows = (await (0, internal_1.transactionQueryOf)(tx)(`SELECT COUNT(*) AS n FROM \`${schemas.app}\`.\`membership_posting\` WHERE ${spec.postingColumn} = ?`, [id]));
+            n = Number(rows[0]?.n);
+        }
+        catch {
+            throw new identity_errors_js_1.IdentityUnavailableError(COUNT_UNAVAILABLE);
         }
-        return options;
+        if (!Number.isFinite(n))
+            throw new identity_errors_js_1.IdentityUnavailableError(COUNT_UNAVAILABLE);
+        return n;
+    }
+    async ensureUnit(spec, companyUuid, rawName) {
+        const name = this.validName(spec, rawName);
+        const found = await this.findByName(this.records, spec, companyUuid, name);
+        if (found !== undefined) {
+            const id = catalogId(found.id);
+            await this.attachJunction(spec, companyUuid, id);
+            return id;
+        }
+        return this.records.transaction(async (tx) => {
+            await tx.lockForUpdate('company', companyUuid);
+            const now = await this.findByName(tx, spec, companyUuid, name);
+            if (now !== undefined)
+                return catalogId(now.id);
+            return this.insertUnit(tx, spec, companyUuid, name);
+        });
+    }
+    async attachJunction(spec, companyUuid, refUuid) {
+        const page = await this.records.list(spec.junctionTypeKey, {
+            where: { companyUuid, [spec.refFieldKey]: refUuid },
+            limit: 1,
+        });
+        if (page.rows.length > 0)
+            return;
+        await this.records.create(spec.junctionTypeKey, {
+            fields: { companyUuid, [spec.refFieldKey]: refUuid },
+        });
     }
 };
 exports.OrgCatalogService = OrgCatalogService;
 exports.OrgCatalogService = OrgCatalogService = __decorate([
     (0, common_1.Injectable)(),
-    __metadata("design:paramtypes", [engine_1.RecordsService])
+    __param(1, (0, common_1.Optional)()),
+    __param(1, (0, common_1.Inject)(framework_schemas_token_js_1.IDENTITY_FRAMEWORK_SCHEMAS)),
+    __metadata("design:paramtypes", [engine_1.RecordsService, Object])
 ], OrgCatalogService);

package/dist/features/org-structure/org-unit-name.d.ts

@@ -0,0 +1,31 @@
+/**
+ * G-012 (spec §10): the ONE name rule for departments and branches, shared by the create and rename
+ * routes, `OrgCatalogService.ensure*` and the org bootstrap planner, so "Quality  Assurance" in a
+ * bootstrap file and "Quality Assurance" typed in the UI are the same name.
+ *
+ * Order (spec §10, as written): Unicode NFC; trim and collapse every whitespace run (JS `\s`, so
+ * tab, CR and LF too) to one space; refuse any control character left (U+0000–U+001F,
+ * U+007F–U+009F, e.g. NUL or NEL); refuse an empty result or one longer than
+ * {@link ORG_UNIT_NAME_MAX} characters (code points, the column width). The template's
+ * `validateName` (`pages/org-structure/orgStructure.js`) applies the same order, so the client
+ * never accepts a name the server refuses.
+ *
+ * Case, accents and width are NOT folded here: the stored name keeps what the user typed; the
+ * column collation (`utf8mb4_unicode_ci`) decides uniqueness, and the bootstrap planner compares
+ * with `nameKey` on top of this.
+ */
+/** The column width of `d_name` / `b_name` (VARCHAR(150), counted in characters). */
+export declare const ORG_UNIT_NAME_MAX = 150;
+export type OrgUnitNameRefusal = 'not_text' | 'empty' | 'control_character' | 'too_long';
+export type OrgUnitNameResult = {
+    readonly ok: true;
+    readonly value: string;
+} | {
+    readonly ok: false;
+    readonly reason: OrgUnitNameRefusal;
+};
+/** Normalise a department or branch name, or say why it is refused. Pure. */
+export declare function normaliseOrgUnitName(raw: unknown): OrgUnitNameResult;
+/** The fixed, user-facing 400 text for a refusal (`kind` is "department" or "branch"). */
+export declare function orgUnitNameMessage(kind: 'department' | 'branch', reason: OrgUnitNameRefusal): string;
+//# sourceMappingURL=org-unit-name.d.ts.map

package/dist/features/org-structure/org-unit-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"org-unit-name.d.ts","sourceRoot":"","sources":["../../../src/features/org-structure/org-unit-name.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,OAAO,GAAG,mBAAmB,GAAG,UAAU,CAAC;AAEzF,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC7C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAKhE,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,iBAAiB,CAQpE;AAED,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,YAAY,GAAG,QAAQ,EAC7B,MAAM,EAAE,kBAAkB,GACzB,MAAM,CASR"}