@endora-commerce/mod-organizations 0.100.0

package/dist/backend/services/organization-tax-id-validation-service.d.ts

@@ -0,0 +1,59 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { AuditPort } from '@endora-commerce/platform/kernel';
+import { OrganizationTaxIdValidation, type ReturnedAddress } from '../entities/organization-tax-id-validation.entity.js';
+import type { VatValidator } from './vat-validator-port.js';
+/**
+ * Owns the tax-ID validation flow (feature 026 US7).
+ *
+ * Inputs:
+ *  - `providerHint`: `'auto' | 'vies' | 'mf_pl' | 'format_only'`
+ *      `auto` → routes Polish NIPs (PL-prefixed or 10-digit) to MF;
+ *      anything that parses as a EU country code prefix → VIES; otherwise
+ *      degrades to `format_only`.
+ *  - `applyAutoFill`: when the result is `validated` AND the provider
+ *    returned a legalName / address, the Organization's `legalName` is
+ *    updated and `version` bumps. The address payload is only used for
+ *    display in the panel today (no Address-entity writes here — the
+ *    existing addresses module owns those).
+ *
+ * Output:
+ *  - Always persists one `OrganizationTaxIdValidation` row, regardless of
+ *    outcome. Provider outages produce `deferred` rows that the admin
+ *    can retry. The Organization itself NEVER fails its save because of
+ *    a validation outage.
+ */
+export interface TriggerValidationInput {
+    providerHint?: 'auto' | 'vies' | 'mf_pl' | 'format_only';
+    applyAutoFill?: boolean;
+    actorAdminUserId?: string | null;
+}
+export interface TriggerValidationResult {
+    record: OrganizationTaxIdValidation;
+    /** Reflects the org's post-update state when `applyAutoFill` was true. */
+    organization: {
+        id: string;
+        legalName: string | null;
+        version: number;
+    } | null;
+}
+export interface OrganizationTaxIdValidationServiceDeps {
+    emFactory: () => EntityManager;
+    /** VIES adapter — production wires `new ViesClient()`; tests inject a stub. */
+    vies?: VatValidator;
+    /** Ministerstwo Finansów adapter — production wires `new MinisterstwoFinansowClient()`. */
+    mfPl?: VatValidator;
+    /** Feature 054 — audits the validation write co-transactionally when provided. */
+    auditLog?: AuditPort;
+}
+export declare class OrganizationTaxIdValidationService {
+    private readonly deps;
+    constructor(deps: OrganizationTaxIdValidationServiceDeps);
+    listForOrganization(organizationId: string, options?: {
+        limit?: number;
+    }): Promise<OrganizationTaxIdValidation[]>;
+    trigger(organizationId: string, input?: TriggerValidationInput): Promise<TriggerValidationResult>;
+    private pickProvider;
+    private runProvider;
+}
+export type { ReturnedAddress };
+//# sourceMappingURL=organization-tax-id-validation-service.d.ts.map

package/dist/backend/services/organization-tax-id-validation-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"organization-tax-id-validation-service.d.ts","sourceRoot":"","sources":["../../../src/backend/services/organization-tax-id-validation-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EACL,2BAA2B,EAC3B,KAAK,eAAe,EACrB,MAAM,sDAAsD,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,yBAAyB,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,sBAAsB;IACrC,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,aAAa,CAAC;IACzD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,2BAA2B,CAAC;IACpC,0EAA0E;IAC1E,YAAY,EAAE;QACZ,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,OAAO,EAAE,MAAM,CAAC;KACjB,GAAG,IAAI,CAAC;CACV;AAED,MAAM,WAAW,sCAAsC;IACrD,SAAS,EAAE,MAAM,aAAa,CAAC;IAC/B,+EAA+E;IAC/E,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,2FAA2F;IAC3F,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,qBAAa,kCAAkC;IACjC,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,sCAAsC;IAEnE,mBAAmB,CACvB,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAC/B,OAAO,CAAC,2BAA2B,EAAE,CAAC;IASnC,OAAO,CACX,cAAc,EAAE,MAAM,EACtB,KAAK,GAAE,sBAA2B,GACjC,OAAO,CAAC,uBAAuB,CAAC;IA0DnC,OAAO,CAAC,YAAY;YAkBN,WAAW;CAmC1B;AAGD,YAAY,EAAE,eAAe,EAAE,CAAC"}

package/dist/backend/services/organization-tax-id-validation-service.js

@@ -0,0 +1,115 @@
+import { Organization } from '../entities/organization.entity.js';
+import { recordAuditFromContext } from '@endora-commerce/platform/commands';
+import { OrganizationTaxIdValidation, } from '../entities/organization-tax-id-validation.entity.js';
+export class OrganizationTaxIdValidationService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async listForOrganization(organizationId, options = {}) {
+        const em = this.deps.emFactory();
+        return em.find(OrganizationTaxIdValidation, { organizationId }, { orderBy: { createdAt: 'desc' }, limit: Math.min(options.limit ?? 25, 100) });
+    }
+    async trigger(organizationId, input = {}) {
+        const em = this.deps.emFactory();
+        const org = await em.findOneOrFail(Organization, {
+            id: organizationId,
+            deletedAt: null,
+        });
+        const providerKind = this.pickProvider(org.taxId, input.providerHint ?? 'auto');
+        const result = await this.runProvider(providerKind, org.taxId);
+        const record = em.create(OrganizationTaxIdValidation, {
+            organizationId,
+            provider: providerKind,
+            outcome: result.outcome,
+            taxIdValue: org.taxId,
+            legalNameReturned: result.legalName,
+            addressReturned: result.address,
+            errorKind: result.errorKind,
+            requestedByAdminUserId: input.actorAdminUserId ?? null,
+        });
+        await em.persistAndFlush(record);
+        // Stamp the org's "last validation" summary fields regardless of
+        // outcome — the admin panel reads `vatValidatedAt`, `vatValidationProvider`,
+        // and `vatValidationOutcome` directly off the Organization.
+        org.vatValidatedAt = new Date();
+        org.vatValidationProvider = providerKind;
+        org.vatValidationOutcome = result.outcome;
+        let appliedOrg = null;
+        if (input.applyAutoFill && result.outcome === 'validated' && result.legalName) {
+            org.legalName = result.legalName;
+        }
+        if (this.deps.auditLog) {
+            recordAuditFromContext(this.deps.auditLog, em, {
+                action: 'organization.tax_id_validation',
+                objectType: 'organization',
+                objectId: org.id,
+                stateBefore: null,
+                stateAfter: {
+                    provider: providerKind,
+                    outcome: result.outcome,
+                    appliedAutoFill: input.applyAutoFill && result.outcome === 'validated' && !!result.legalName,
+                },
+            });
+        }
+        await em.flush();
+        if (input.applyAutoFill && result.outcome === 'validated' && result.legalName) {
+            appliedOrg = {
+                id: org.id,
+                legalName: org.legalName ?? null,
+                version: org.version,
+            };
+        }
+        return { record, organization: appliedOrg };
+    }
+    pickProvider(taxId, hint) {
+        if (hint === 'vies')
+            return 'vies';
+        if (hint === 'mf_pl')
+            return 'mf_pl';
+        if (hint === 'format_only')
+            return 'format_only';
+        // auto-pick
+        const cleaned = taxId.replace(/[\s-]+/g, '').toUpperCase();
+        if (/^PL[0-9]{10}$/.test(cleaned) || /^[0-9]{10}$/.test(cleaned)) {
+            return 'mf_pl';
+        }
+        if (/^[A-Z]{2}.+$/.test(cleaned)) {
+            return 'vies';
+        }
+        return 'format_only';
+    }
+    async runProvider(provider, taxId) {
+        if (provider === 'format_only') {
+            const cleaned = taxId.replace(/[\s-]+/g, '');
+            const looksLikeId = /^[A-Z0-9]{6,32}$/i.test(cleaned);
+            return {
+                outcome: looksLikeId ? 'unverified' : 'failed',
+                legalName: null,
+                address: null,
+                errorKind: looksLikeId ? null : 'invalid_format',
+            };
+        }
+        if (provider === 'vies') {
+            if (!this.deps.vies) {
+                return {
+                    outcome: 'deferred',
+                    legalName: null,
+                    address: null,
+                    errorKind: 'provider_not_wired',
+                };
+            }
+            return this.deps.vies.validate({ taxId });
+        }
+        if (!this.deps.mfPl) {
+            return {
+                outcome: 'deferred',
+                legalName: null,
+                address: null,
+                errorKind: 'provider_not_wired',
+            };
+        }
+        return this.deps.mfPl.validate({ taxId });
+    }
+}
+//# sourceMappingURL=organization-tax-id-validation-service.js.map

package/dist/backend/services/organization-tax-id-validation-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"organization-tax-id-validation-service.js","sourceRoot":"","sources":["../../../src/backend/services/organization-tax-id-validation-service.ts"],"names":[],"mappings":"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"}

package/dist/backend/services/organization-tree-service.d.ts

@@ -0,0 +1,102 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import { type OrganizationTreeNode } from '@endora-commerce/contracts';
+import { HttpError } from '@endora-commerce/platform/http';
+import type { Organization } from '../entities/organization.entity.js';
+/**
+ * OrganizationTreeService (feature 056 US1) — the organizations-owned tree
+ * mechanism over the materialized `path` column (`'/<rootId>/…/<thisId>/'`).
+ *
+ * All traversal is single-query / index-backed (a `text_pattern_ops` prefix
+ * scan on `path`), never a per-node walk (FR-012 / SC-002). Mutations
+ * (assign/move) go through the Command Bus; this service supplies the pure
+ * cycle/depth checks and the single-UPDATE subtree path rewrite the Commands
+ * drive (Principle XIII).
+ *
+ * Flat behavior is preserved byte-for-byte: a root has `parent_id = NULL` and
+ * `path = '/<id>/'`, so `subtreeIds(root) = {root}` and `ancestorIds(root) = []`.
+ */
+/** Maximum number of path segments (tree levels) — depth bound (research §R3). */
+export declare const MAX_TREE_DEPTH_SEGMENTS = 10;
+/**
+ * The three refusals this module's tree rules produce, as pure functions —
+ * D-129's remaining sweep, MR 7.
+ *
+ * Extracted for the reason `admin_roles`' `roleInUseRefusal` was (issue #168):
+ * `check:error-translations` verifies that a code has a sentence and can see
+ * neither the token the raise writes nor a `{placeholder}` nothing fills, and
+ * the envelope's own `hasUnfilledPlaceholder` fall-back then hides the miss
+ * behind the written English. Only a test that builds a **real** refusal and
+ * renders the bundle's sentence from its `details` sees all three agree, and a
+ * refusal it can build without an `EntityManager` is what makes that test a unit
+ * test — `test/unit/organizations/error-code-sentences.test.ts`.
+ *
+ * Every one of them is tokened, which is the whole shape here: the base key
+ * `errors.<CODE>` renders for nobody, because `localizeErrorEnvelope` composes
+ * `errors.<CODE>.<token>` whenever `details.code` is present and never re-asks.
+ * The base sentences are carried anyway, and this module's manifest records
+ * D-190's measurement of why.
+ */
+export declare function cycleRefusal(): HttpError;
+/**
+ * The depth refusal, carrying the bound it refused against.
+ *
+ * `maxDepth` and never a second `code`: `details.code` is the refusal token, so
+ * a value written there would re-key the sentence lookup instead of filling the
+ * sentence. Before MR 7 this raise interpolated the bound into its English
+ * message and passed the token alone, so the translated sentence — which
+ * replaces the message wholesale — had no way to say how deep is too deep
+ * (!1181's finding).
+ */
+export declare function maxDepthRefusal(maxDepth?: number): HttpError;
+/**
+ * Deleting an organization that still has sub-organizations (FR-010), backed by
+ * the database's own `parent_id ON DELETE RESTRICT`.
+ *
+ * It lives beside the two above because it is the same rule read from the other
+ * end — a child is an edge of this tree — and because the admin route that
+ * raises it already imports this service.
+ */
+export declare function hasChildrenRefusal(): HttpError;
+export declare class OrganizationTreeService {
+    #private;
+    private readonly emFactory;
+    constructor(emFactory: () => EntityManager);
+    /**
+     * `{orgId} ∪ descendants`, pre-order (by `path`). One indexed prefix scan.
+     * Empty when the org does not exist.
+     */
+    subtreeIds(orgId: string): Promise<string[]>;
+    /** Descendants of `orgId` (excludes self), pre-order. */
+    descendantIds(orgId: string): Promise<string[]>;
+    /** Ancestor ids of `orgId`, nearest-first (parent → … → root). Excludes self. */
+    ancestorIds(orgId: string): Promise<string[]>;
+    /** Subtree as tree nodes (id, name, parentId, depth, status), pre-order. */
+    subtreeNodes(orgId: string): Promise<OrganizationTreeNode[]>;
+    /** Ancestor chain as tree nodes, nearest-first. */
+    ancestorNodes(orgId: string): Promise<OrganizationTreeNode[]>;
+    /**
+     * Rejects assigning `node`'s parent to `newParent` when that would create a
+     * cycle: `newParent` is `node` itself or lives inside `node`'s own subtree.
+     * One path-prefix comparison — no walk (FR-002).
+     */
+    assertNoCycle(node: Organization, newParent: Organization | null): void;
+    /**
+     * Rejects a re-parent whose resulting deepest subtree node would exceed the
+     * depth bound (`MAX_TREE_DEPTH_SEGMENTS` path segments — research §R3).
+     */
+    assertMaxDepth(em: EntityManager, node: Organization, newParent: Organization | null): Promise<void>;
+    /**
+     * Sets `node.parent_id` and rewrites the moved subtree's `path` prefixes in a
+     * single UPDATE (`path = :newPath || substring(path from len(oldPath)+1)`).
+     * Runs on the transactional `em`. The caller must have already validated the
+     * cycle + depth invariants. Returns the affected rows' prior `path` values
+     * (for reversible-command capture).
+     */
+    applyReparentPaths(em: EntityManager, node: Organization, newParent: Organization | null): Promise<{
+        affected: Array<{
+            id: string;
+            oldPath: string;
+        }>;
+    }>;
+}
+//# sourceMappingURL=organization-tree-service.d.ts.map

package/dist/backend/services/organization-tree-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"organization-tree-service.d.ts","sourceRoot":"","sources":["../../../src/backend/services/organization-tree-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAe,KAAK,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACpF,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAsB,MAAM,oCAAoC,CAAC;AAE3F;;;;;;;;;;;;GAYG;AAEH,kFAAkF;AAClF,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAO1C;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAOxC;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,QAAQ,GAAE,MAAgC,GAAG,SAAS,CAOrF;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,IAAI,SAAS,CAO9C;AAED,qBAAa,uBAAuB;;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,EAAE,MAAM,aAAa;IAE3D;;;OAGG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAYlD,yDAAyD;IACnD,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAKrD,iFAAiF;IAC3E,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAanD,4EAA4E;IACtE,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAYlE,mDAAmD;IAC7C,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAcnE;;;;OAIG;IACH,aAAa,CAAC,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI;IAOvE;;;OAGG;IACG,cAAc,CAClB,EAAE,EAAE,aAAa,EACjB,IAAI,EAAE,YAAY,EAClB,SAAS,EAAE,YAAY,GAAG,IAAI,GAC7B,OAAO,CAAC,IAAI,CAAC;IAoBhB;;;;;;OAMG;IACG,kBAAkB,CACtB,EAAE,EAAE,aAAa,EACjB,IAAI,EAAE,YAAY,EAClB,SAAS,EAAE,YAAY,GAAG,IAAI,GAC7B,OAAO,CAAC;QAAE,QAAQ,EAAE,KAAK,CAAC;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC;CAgDjE"}

package/dist/backend/services/organization-tree-service.js

@@ -0,0 +1,184 @@
+import { ERROR_CODES } from '@endora-commerce/contracts';
+import { HttpError } from '@endora-commerce/platform/http';
+/**
+ * OrganizationTreeService (feature 056 US1) — the organizations-owned tree
+ * mechanism over the materialized `path` column (`'/<rootId>/…/<thisId>/'`).
+ *
+ * All traversal is single-query / index-backed (a `text_pattern_ops` prefix
+ * scan on `path`), never a per-node walk (FR-012 / SC-002). Mutations
+ * (assign/move) go through the Command Bus; this service supplies the pure
+ * cycle/depth checks and the single-UPDATE subtree path rewrite the Commands
+ * drive (Principle XIII).
+ *
+ * Flat behavior is preserved byte-for-byte: a root has `parent_id = NULL` and
+ * `path = '/<id>/'`, so `subtreeIds(root) = {root}` and `ancestorIds(root) = []`.
+ */
+/** Maximum number of path segments (tree levels) — depth bound (research §R3). */
+export const MAX_TREE_DEPTH_SEGMENTS = 10;
+/** Split a materialized path `'/a/b/c/'` into its ordered id segments `[a, b, c]`. */
+function pathSegments(path) {
+    return path.split('/').filter((s) => s.length > 0);
+}
+/**
+ * The three refusals this module's tree rules produce, as pure functions —
+ * D-129's remaining sweep, MR 7.
+ *
+ * Extracted for the reason `admin_roles`' `roleInUseRefusal` was (issue #168):
+ * `check:error-translations` verifies that a code has a sentence and can see
+ * neither the token the raise writes nor a `{placeholder}` nothing fills, and
+ * the envelope's own `hasUnfilledPlaceholder` fall-back then hides the miss
+ * behind the written English. Only a test that builds a **real** refusal and
+ * renders the bundle's sentence from its `details` sees all three agree, and a
+ * refusal it can build without an `EntityManager` is what makes that test a unit
+ * test — `test/unit/organizations/error-code-sentences.test.ts`.
+ *
+ * Every one of them is tokened, which is the whole shape here: the base key
+ * `errors.<CODE>` renders for nobody, because `localizeErrorEnvelope` composes
+ * `errors.<CODE>.<token>` whenever `details.code` is present and never re-asks.
+ * The base sentences are carried anyway, and this module's manifest records
+ * D-190's measurement of why.
+ */
+export function cycleRefusal() {
+    return new HttpError(422, ERROR_CODES.ORGANIZATION_TREE_INVALID, 'Cannot set a parent that would create a cycle (the target is inside this organization\'s own subtree).', { code: 'cycle' });
+}
+/**
+ * The depth refusal, carrying the bound it refused against.
+ *
+ * `maxDepth` and never a second `code`: `details.code` is the refusal token, so
+ * a value written there would re-key the sentence lookup instead of filling the
+ * sentence. Before MR 7 this raise interpolated the bound into its English
+ * message and passed the token alone, so the translated sentence — which
+ * replaces the message wholesale — had no way to say how deep is too deep
+ * (!1181's finding).
+ */
+export function maxDepthRefusal(maxDepth = MAX_TREE_DEPTH_SEGMENTS) {
+    return new HttpError(422, ERROR_CODES.ORGANIZATION_TREE_INVALID, `Re-parent would exceed the maximum organization tree depth (${maxDepth} levels).`, { code: 'max_depth_exceeded', maxDepth });
+}
+/**
+ * Deleting an organization that still has sub-organizations (FR-010), backed by
+ * the database's own `parent_id ON DELETE RESTRICT`.
+ *
+ * It lives beside the two above because it is the same rule read from the other
+ * end — a child is an edge of this tree — and because the admin route that
+ * raises it already imports this service.
+ */
+export function hasChildrenRefusal() {
+    return new HttpError(409, ERROR_CODES.ORGANIZATION_HAS_CHILDREN, 'This organization has sub-organizations. Reassign or remove the children first.', { code: 'has_children' });
+}
+export class OrganizationTreeService {
+    emFactory;
+    constructor(emFactory) {
+        this.emFactory = emFactory;
+    }
+    /**
+     * `{orgId} ∪ descendants`, pre-order (by `path`). One indexed prefix scan.
+     * Empty when the org does not exist.
+     */
+    async subtreeIds(orgId) {
+        const em = this.emFactory();
+        const rows = (await em.getConnection().execute(`select "id" from "organizations"
+         where "path" like (select "path" from "organizations" where "id" = ?) || '%'
+           and "deleted_at" is null
+         order by "path"`, [orgId]));
+        return rows.map((r) => r.id);
+    }
+    /** Descendants of `orgId` (excludes self), pre-order. */
+    async descendantIds(orgId) {
+        const subtree = await this.subtreeIds(orgId);
+        return subtree.filter((id) => id !== orgId);
+    }
+    /** Ancestor ids of `orgId`, nearest-first (parent → … → root). Excludes self. */
+    async ancestorIds(orgId) {
+        const em = this.emFactory();
+        const rows = (await em.getConnection().execute(`select "path" from "organizations" where "id" = ?`, [orgId]));
+        const path = rows[0]?.path;
+        if (!path)
+            return [];
+        const segs = pathSegments(path);
+        segs.pop(); // drop self (final segment)
+        return segs.reverse(); // nearest-first
+    }
+    /** Subtree as tree nodes (id, name, parentId, depth, status), pre-order. */
+    async subtreeNodes(orgId) {
+        const em = this.emFactory();
+        const rows = (await em.getConnection().execute(`select "id", "name", "parent_id", "status", "path" from "organizations"
+         where "path" like (select "path" from "organizations" where "id" = ?) || '%'
+           and "deleted_at" is null
+         order by "path"`, [orgId]));
+        return rows.map((r) => this.#toNode(r));
+    }
+    /** Ancestor chain as tree nodes, nearest-first. */
+    async ancestorNodes(orgId) {
+        const ids = await this.ancestorIds(orgId);
+        if (ids.length === 0)
+            return [];
+        const em = this.emFactory();
+        const rows = (await em.getConnection().execute(`select "id", "name", "parent_id", "status", "path" from "organizations"
+         where "id" in (${ids.map(() => '?').join(', ')})`, ids));
+        const byId = new Map(rows.map((r) => [r.id, this.#toNode(r)]));
+        // Preserve nearest-first order from `ids`.
+        return ids.map((id) => byId.get(id)).filter((n) => n !== undefined);
+    }
+    /**
+     * Rejects assigning `node`'s parent to `newParent` when that would create a
+     * cycle: `newParent` is `node` itself or lives inside `node`'s own subtree.
+     * One path-prefix comparison — no walk (FR-002).
+     */
+    assertNoCycle(node, newParent) {
+        if (!newParent)
+            return; // detach → root, never a cycle
+        if (newParent.id === node.id || newParent.path.startsWith(node.path)) {
+            throw cycleRefusal();
+        }
+    }
+    /**
+     * Rejects a re-parent whose resulting deepest subtree node would exceed the
+     * depth bound (`MAX_TREE_DEPTH_SEGMENTS` path segments — research §R3).
+     */
+    async assertMaxDepth(em, node, newParent) {
+        const rows = (await em.getConnection().execute(`select "path" from "organizations" where "path" like ? and "deleted_at" is null`, [`${node.path}%`], 'all', em.getTransactionContext()));
+        const nodeSegs = pathSegments(node.path).length;
+        const maxSubtreeSegs = rows.reduce((max, r) => Math.max(max, pathSegments(r.path).length), nodeSegs);
+        const relativeMax = maxSubtreeSegs - nodeSegs; // 0 when node is a leaf
+        const newNodeSegs = newParent ? pathSegments(newParent.path).length + 1 : 1;
+        const newDeepestSegs = newNodeSegs + relativeMax;
+        if (newDeepestSegs > MAX_TREE_DEPTH_SEGMENTS) {
+            throw maxDepthRefusal();
+        }
+    }
+    /**
+     * Sets `node.parent_id` and rewrites the moved subtree's `path` prefixes in a
+     * single UPDATE (`path = :newPath || substring(path from len(oldPath)+1)`).
+     * Runs on the transactional `em`. The caller must have already validated the
+     * cycle + depth invariants. Returns the affected rows' prior `path` values
+     * (for reversible-command capture).
+     */
+    async applyReparentPaths(em, node, newParent) {
+        const oldPath = node.path;
+        const newPath = `${newParent ? newParent.path : '/'}${node.id}/`;
+        // Capture the moved subtree's prior paths (reversibility, R3).
+        const before = (await em.getConnection().execute(`select "id", "path" from "organizations" where "path" like ?`, [`${oldPath}%`], 'all', em.getTransactionContext()));
+        const affected = before.map((r) => ({ id: r.id, oldPath: r.path }));
+        if (newPath !== oldPath) {
+            // Rewrite every subtree row's path prefix in one statement.
+            await em.getConnection().execute(`update "organizations"
+           set "path" = ? || substring("path" from ?)
+         where "path" like ?`, [newPath, oldPath.length + 1, `${oldPath}%`], 'run', em.getTransactionContext());
+        }
+        // Reflect the change on the managed node entity so the transaction flush
+        // persists the new parent_id (+ version bump) consistently with the DB.
+        node.parentId = newParent ? newParent.id : null;
+        node.path = newPath;
+        return { affected };
+    }
+    #toNode(r) {
+        return {
+            id: r.id,
+            name: r.name,
+            parentId: r.parent_id,
+            depth: pathSegments(r.path).length - 1, // root = 0
+            status: r.status,
+        };
+    }
+}
+//# sourceMappingURL=organization-tree-service.js.map

package/dist/backend/services/organization-tree-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"organization-tree-service.js","sourceRoot":"","sources":["../../../src/backend/services/organization-tree-service.ts"],"names":[],"mappings":"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"}

package/dist/backend/services/personal-organization-service.d.ts

@@ -0,0 +1,130 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import { type CustomerAccountMemberWritePort, type CustomerAccountReadPort, type CustomerAccountRecord } from '@endora-commerce/contracts';
+import type { AuditPort } from '@endora-commerce/platform/kernel';
+import { Organization } from '../entities/organization.entity.js';
+/**
+ * `customer_accounts`' own read and write of the row this service binds to an
+ * Organization (feature 075, Phase C). The three sites they replace were
+ * `em.findOne`, `em.count` and a field assignment on that module's entity.
+ *
+ * With `customer_accounts` off both fail closed, which is the only coherent
+ * answer: provisioning a personal Organization for an account the platform
+ * cannot see would create a tenant with no member.
+ */
+export interface PersonalOrganizationAccountPorts {
+    read: CustomerAccountReadPort;
+    write: CustomerAccountMemberWritePort;
+}
+/**
+ * The name a scrubbed personal organisation is renamed to. It matches the one
+ * `customer_accounts` writes over the member's own first and last name,
+ * because a personal organisation's name *is* that person's name.
+ */
+export declare const ANONYMIZED_ORGANIZATION_NAME = "Deleted customer";
+/**
+ * Feature 051 — provisions and guards single-member Personal Organizations for
+ * B2C (individual) customers. One provisioning rule, reused by live registration
+ * and the backfill migration's mental model (the migration duplicates the SQL).
+ */
+export declare class PersonalOrganizationService {
+    #private;
+    private readonly emFactory;
+    /**
+     * Required since `customers`' Phase-C cut: the `ensureFor` overload that
+     * needed neither port — it took the caller's managed `CustomerAccount` and
+     * its `EntityManager` — went with that cut, and every method left reads
+     * this module's neighbour through its ports.
+     */
+    private readonly accounts;
+    /**
+     * Feature 075 — `anonymizeIfOrphaned` records the scrub. It used to be
+     * written by `customers`' deletion sweep, on a row that module does not
+     * own; the write and its one audit row moved here together.
+     */
+    private readonly auditLog?;
+    constructor(emFactory: () => EntityManager, 
+    /**
+     * Required since `customers`' Phase-C cut: the `ensureFor` overload that
+     * needed neither port — it took the caller's managed `CustomerAccount` and
+     * its `EntityManager` — went with that cut, and every method left reads
+     * this module's neighbour through its ports.
+     */
+    accounts: PersonalOrganizationAccountPorts, 
+    /**
+     * Feature 075 — `anonymizeIfOrphaned` records the scrub. It used to be
+     * written by `customers`' deletion sweep, on a row that module does not
+     * own; the write and its one audit row moved here together.
+     */
+    auditLog?: AuditPort | undefined);
+    /** Name an individual's organization from their profile, falling back to the email local-part. */
+    static personalName(account: Pick<CustomerAccountRecord, 'firstName' | 'lastName' | 'email'>): string;
+    /**
+     * The provisioning itself — find-or-create the personal organisation for an
+     * account, on the `EntityManager` the caller hands in.
+     *
+     * D-178 made this the one place the row is written, and gave it a caller that
+     * has no account row yet: `customer_accounts` inserts the account and its
+     * organisation in one transaction, so it passes the id it is *about* to write
+     * and the name components it already holds. Nothing here reads
+     * `customer_accounts` and nothing here writes it.
+     *
+     * Idempotent by `taxId`, which is derived from the account id — a retry after
+     * a rolled-back attempt re-finds the row rather than creating a second one.
+     *
+     * command-coverage-ignore: idempotent auto-provisioning of a customer's
+     * personal (B2C) organization — a system invariant the constitution mandates
+     * (Principle XI), not an operator-initiated write. Its caller's own write is
+     * the audited event.
+     */
+    provisionFor(em: EntityManager, input: {
+        customerAccountId: string;
+        email: string;
+        firstName?: string | null;
+        lastName?: string | null;
+    }): Promise<Organization>;
+    /**
+     * Return the customer's organization, provisioning a personal one iff none is
+     * linked. Idempotent by customer — a customer that already has an organization
+     * is returned as-is (never a second personal org).
+     *
+     * **Since D-178 this repairs rather than provisions.** Every write path now
+     * creates the account and its organisation in one transaction, so a live
+     * account always has one and this method's provisioning arm is reached only by
+     * a caller holding an account written before that ruling. It is kept because
+     * it is idempotent and because `ensureForCustomerAccount` is a published port.
+     */
+    ensureForCustomerAccountId(customerAccountId: string): Promise<Organization>;
+    /**
+     * D-178 — the account's **own** personal organisation, whatever it currently
+     * belongs to, provisioned if it has never existed.
+     *
+     * `unassign` on the admin customer screen is what wants it: an operator
+     * detaching a member from a company used to write `organization_id = NULL`,
+     * and the account it produced could never transact. The operation is now the
+     * move it always meant, and this is the destination. The **binding** is not
+     * written here — `customers` writes it through
+     * `CustomerAccountLifecycleWritePort.detachToPersonalOrganization` once its
+     * own authority and org-administrator-depletion guards have passed.
+     */
+    provisionPersonalOrganizationFor(customerAccountId: string): Promise<Organization>;
+    /**
+     * Feature 051, the other end of the same rule — the retention sweep's
+     * cascade, moved here with `customers`' Phase-C cut.
+     *
+     * That module ran it by loading this module's `Organization`, renaming it,
+     * blanking its registered address and stamping `deletedAt` — three writes on
+     * a row it does not own, plus the audit entry describing them. The decision
+     * is this module's: a personal organisation whose single member has been
+     * anonymised has nobody in it and carries that person's name.
+     *
+     * Writes nothing and answers `null` whenever the cascade does not apply, so a
+     * caller cannot get it wrong by asking too often.
+     */
+    anonymizeIfOrphaned(customerAccountId: string): Promise<Organization | null>;
+    /**
+     * Guard: a personal organization is single-member and MUST never gain a second
+     * customer. Call before attaching a customer to an organization.
+     */
+    assertMembershipAllowed(organizationId: string, em?: EntityManager<import("@mikro-orm/postgresql").AbstractSqlDriver<import("@mikro-orm/postgresql").AbstractSqlConnection, import("@mikro-orm/postgresql").AbstractSqlPlatform>>): Promise<void>;
+}
+//# sourceMappingURL=personal-organization-service.d.ts.map

package/dist/backend/services/personal-organization-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"personal-organization-service.d.ts","sourceRoot":"","sources":["../../../src/backend/services/personal-organization-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAEL,KAAK,8BAA8B,EACnC,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC3B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAElE;;;;;;;;GAQG;AACH,MAAM,WAAW,gCAAgC;IAC/C,IAAI,EAAE,uBAAuB,CAAC;IAC9B,KAAK,EAAE,8BAA8B,CAAC;CACvC;AAED;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,qBAAqB,CAAC;AAE/D;;;;GAIG;AACH,qBAAa,2BAA2B;;IAEpC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBAbT,SAAS,EAAE,MAAM,aAAa;IAC/C;;;;;OAKG;IACc,QAAQ,EAAE,gCAAgC;IAC3D;;;;OAIG;IACc,QAAQ,CAAC,EAAE,SAAS,YAAA;IAGvC,kGAAkG;IAClG,MAAM,CAAC,YAAY,CACjB,OAAO,EAAE,IAAI,CAAC,qBAAqB,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC,GACvE,MAAM;IAKT;;;;;;;;;;;;;;;;;OAiBG;IACG,YAAY,CAChB,EAAE,EAAE,aAAa,EACjB,KAAK,EAAE;QACL,iBAAiB,EAAE,MAAM,CAAC;QAC1B,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC1B,GACA,OAAO,CAAC,YAAY,CAAC;IAwBxB;;;;;;;;;;OAUG;IACG,0BAA0B,CAAC,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAoBlF;;;;;;;;;;;OAWG;IACG,gCAAgC,CAAC,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAYxF;;;;;;;;;;;;OAYG;IACG,mBAAmB,CAAC,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAsClF;;;OAGG;IACG,uBAAuB,CAAC,cAAc,EAAE,MAAM,EAAE,EAAE,+KAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;CAkB5F"}