fix(customer-master): preserve entities when visible hierarchy contains cycles (#906)

docs/storybook-inventory.md

@@ -24,6 +24,7 @@ operator-facing control you can click before changing product CSS.
 | `Workspace/WorkspaceCalendar` | Read observed Naruon events, or open a commitment to land on that post. Fail-closed copy stays `이 범위의 일정을 아직 받을 수 없습니다`. | `--color-chip-border`, `WorkspaceCalendar`, `EvidenceStatusMark` |
 | `Ask Agent/Public claim verification` | Compare supported, refuted, and not-enough-information states; open only the external evidence link, then review the separate internal citation before changing governed graph state. | `--space-panel-block`, `--space-control-gap`, `--color-border`, `--size-control-min`, `PublicClaimVerification` |
 | `Ask Agent/Knowledge cutoff` | Exercise partial historical grounding, retained-revision provenance, later-live-change disclosure, and the narrow viewport before relying on a historical answer. | Native `datetime-local`, `--space-panel-block`, `--space-control-gap`, `--color-border`, `--size-control-min` |
+| `Customers/EntityTreeRow` | Read every visible customer entity exactly once; `PureCycle`, `SelfParent`, and `UnlistedParent` prove a cycled, self-parented, or unlisted parent renders as top level with an explicit ancestry note instead of disappearing. | `CustomerEntityTreeRow`, `customerEntityTree` |
 
 Repeated web objects must use `frontend/src/styles/tokens.css` and a module
 under `frontend/src/components/`. Do not add a second Node package manager;

frontend/src/App.tsx

@@ -1,5 +1,6 @@
 import { focusedGraphMustReset } from "./focusedGraphSelection";
 import { canAuthorVoice, postPrimaryVoiceLabel } from "./voicePerspective";
+import { buildCustomerEntityTree, type CustomerEntityTreeNode } from "./customerEntityTree";
 
 import { Component, lazy, Suspense, useCallback, useEffect, useEffectEvent, useRef, useState, type ReactNode } from "react";
 import { useAuth } from "react-oidc-context";
@@ -59,7 +60,6 @@ import {
   type ChatAnswer,
   type ChatExchange,
   type CorporateEntityRef,
-  type CustomerMasterEntity,
   type CustomerMasterResponse,
   type Counterparty,
   type EvaluationResponse,
@@ -4610,42 +4610,9 @@ function PostList({
   );
 }
 
-interface CustomerEntityTreeNode {
-  entity: CustomerMasterEntity;
-  children: CustomerEntityTreeNode[];
-}
-
-// Live bug (2026-08-19): Customer Master's own entity list rendered every
-// corporate_entity as an independent top-level row, even though the API
-// already carries parent_entity_id and the codebase already knows how to
-// build a real forest from it (lineageweave/affiliate_tree.py, used for
-// the post-detail popup's Affiliate tree) -- a group holding company and
-// its subsidiaries showed up as an unrelated flat list with no visual
-// hierarchy at all. A parent not present in this account's own visible
-// entity list (a real possibility -- ABAC can authorize a child entity
-// without its parent) is not dropped; that entity becomes a root here
-// instead of disappearing.
-function buildCustomerEntityTree(entities: CustomerMasterEntity[]): CustomerEntityTreeNode[] {
-  const byId = new Map(entities.map((entity) => [entity.corporate_entity_id, entity]));
-  const childrenByParent = new Map<string, CustomerMasterEntity[]>();
-  const roots: CustomerMasterEntity[] = [];
-  for (const entity of entities) {
-    if (entity.parent_entity_id && byId.has(entity.parent_entity_id)) {
-      const siblings = childrenByParent.get(entity.parent_entity_id) ?? [];
-      siblings.push(entity);
-      childrenByParent.set(entity.parent_entity_id, siblings);
-    } else {
-      roots.push(entity);
-    }
-  }
-  const toNode = (entity: CustomerMasterEntity): CustomerEntityTreeNode => ({
-    entity,
-    children: (childrenByParent.get(entity.corporate_entity_id) ?? []).map(toNode),
-  });
-  return roots.map(toNode);
-}
+// Customer forest builder lives in ./customerEntityTree (cycle-safe, #906).
 
-function CustomerEntityTreeRow({
+export function CustomerEntityTreeRow({
   node,
   depth,
   expandedEntityId,
@@ -4676,6 +4643,15 @@ function CustomerEntityTreeRow({
       >
         <strong>{entity.entity_name}</strong>
         <span>{entity.corporate_entity_code} · {entity.entity_level_label}</span>
+        {node.ancestryNote ? (
+          <span className="customer-ancestry-note">
+            {node.ancestryNote === "cycle-broken"
+              ? t("Shown as top level: listed parent forms a cycle.")
+              : node.ancestryNote === "self-parent"
+                ? t("Shown as top level: entity lists itself as parent.")
+                : t("Shown as top level: listed parent is not visible.")}
+          </span>
+        ) : null}
       </button>
       {expandedEntityId === entity.corporate_entity_id ? (
         <div className="customer-related-posts">

frontend/src/CustomerEntityTreeRow.stories.tsx

@@ -0,0 +1,97 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import { CustomerEntityTreeRow } from "./App";
+import { buildCustomerEntityTree } from "./customerEntityTree";
+import type { CustomerMasterEntity } from "./api";
+
+function entity(
+  id: string,
+  parent: string | null,
+  name = id,
+): CustomerMasterEntity {
+  return {
+    corporate_entity_id: id,
+    entity_name: name,
+    corporate_entity_code: id,
+    entity_level_code: "L",
+    entity_level_label: "Level",
+    parent_entity_id: parent,
+  };
+}
+
+const callbacks = {
+  onToggle: () => undefined,
+  onOpenPost: () => undefined,
+};
+
+const meta = {
+  title: "Customers/EntityTreeRow",
+  component: CustomerEntityTreeRow,
+} satisfies Meta<typeof CustomerEntityTreeRow>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+function ForestList({ nodes }: { nodes: ReturnType<typeof buildCustomerEntityTree> }) {
+  return (
+    <ul>
+      {nodes.map((node) => (
+        <CustomerEntityTreeRow
+          key={node.entity.corporate_entity_id}
+          node={node}
+          depth={0}
+          expandedEntityId={null}
+          relatedByEntity={{}}
+          relatedLoading={null}
+          {...callbacks}
+        />
+      ))}
+    </ul>
+  );
+}
+
+export const PureCycle: Story = {
+  render: () => (
+    <ForestList
+      nodes={buildCustomerEntityTree([
+        entity("A", "B", "Alpha"),
+        entity("B", "A", "Beta"),
+      ])}
+    />
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText("Alpha")).toBeInTheDocument();
+    await expect(canvas.getByText("Beta")).toBeInTheDocument();
+    await expect(
+      canvas.getByText("Shown as top level: listed parent forms a cycle."),
+    ).toBeInTheDocument();
+  },
+};
+
+export const SelfParent: Story = {
+  render: () => (
+    <ForestList nodes={buildCustomerEntityTree([entity("S", "S", "Solo")])} />
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText("Solo")).toBeInTheDocument();
+    await expect(
+      canvas.getByText("Shown as top level: entity lists itself as parent."),
+    ).toBeInTheDocument();
+  },
+};
+
+export const UnlistedParent: Story = {
+  render: () => (
+    <ForestList
+      nodes={buildCustomerEntityTree([entity("child", "ghost", "Orphan")])}
+    />
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText("Orphan")).toBeDefined();
+    await expect(
+      canvas.getByText("Shown as top level: listed parent is not visible."),
+    ).toBeInTheDocument();
+  },
+};

frontend/src/customerEntityTree.test.tsx

@@ -0,0 +1,109 @@
+import { render, screen } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { CustomerEntityTreeRow } from "./App";
+import { buildCustomerEntityTree } from "./customerEntityTree";
+import type { CustomerMasterEntity } from "./api";
+import { setLocale } from "./i18n";
+
+vi.mock("react-oidc-context", () => ({
+  useAuth: () => ({
+    isLoading: false,
+    isAuthenticated: false,
+    error: undefined,
+    user: undefined,
+    signinRedirect: vi.fn(),
+    signoutRedirect: vi.fn(),
+  }),
+}));
+
+beforeEach(() => {
+  setLocale("en");
+});
+
+function entity(
+  id: string,
+  parent: string | null,
+  name = id,
+): CustomerMasterEntity {
+  return {
+    corporate_entity_id: id,
+    entity_name: name,
+    corporate_entity_code: id,
+    entity_level_code: "L",
+    entity_level_label: "Level",
+    parent_entity_id: parent,
+  };
+}
+
+function flattenIds(
+  nodes: ReturnType<typeof buildCustomerEntityTree>,
+): string[] {
+  const out: string[] = [];
+  const walk = (
+    list: ReturnType<typeof buildCustomerEntityTree>,
+  ): void => {
+    for (const node of list) {
+      out.push(node.entity.corporate_entity_id);
+      walk(node.children);
+    }
+  };
+  walk(nodes);
+  return out;
+}
+
+describe("#906 cycle-safe customer forest", () => {
+  it("emits every entity exactly once for a pure two-entity cycle", () => {
+    const tree = buildCustomerEntityTree([
+      entity("A", "B"),
+      entity("B", "A"),
+    ]);
+    expect(flattenIds(tree).sort()).toEqual(["A", "B"]);
+    expect(tree).toHaveLength(1);
+    expect(tree[0].ancestryNote).toBe("cycle-broken");
+  });
+
+  it("emits a self-parent entity once instead of dropping it", () => {
+    const tree = buildCustomerEntityTree([entity("S", "S")]);
+    expect(flattenIds(tree)).toEqual(["S"]);
+    expect(tree[0].ancestryNote).toBe("self-parent");
+  });
+
+  it("preserves missing-parent-as-root and ordinary order", () => {
+    const tree = buildCustomerEntityTree([
+      entity("child", "ghost"),
+      entity("root", null),
+      entity("kid", "root"),
+    ]);
+    expect(flattenIds(tree)).toEqual(["child", "root", "kid"]);
+    expect(tree[0].ancestryNote).toBe("unlisted-parent");
+    expect(tree[1].ancestryNote).toBeUndefined();
+  });
+
+  it("renders both cycle members with an explicit ancestry note", () => {
+    const tree = buildCustomerEntityTree([
+      entity("A", "B", "Alpha"),
+      entity("B", "A", "Beta"),
+    ]);
+    render(
+      <ul>
+        {tree.map((node) => (
+          <CustomerEntityTreeRow
+            key={node.entity.corporate_entity_id}
+            node={node}
+            depth={0}
+            expandedEntityId={null}
+            relatedByEntity={{}}
+            relatedLoading={null}
+            onToggle={() => undefined}
+            onOpenPost={() => undefined}
+          />
+        ))}
+      </ul>,
+    );
+    expect(screen.getByText("Alpha")).toBeDefined();
+    expect(screen.getByText("Beta")).toBeDefined();
+    expect(
+      screen.getByText("Shown as top level: listed parent forms a cycle."),
+    ).toBeDefined();
+  });
+});

frontend/src/customerEntityTree.ts

@@ -0,0 +1,73 @@
+import type { CustomerMasterEntity } from "./api";
+
+export interface CustomerEntityTreeNode {
+  entity: CustomerMasterEntity;
+  children: CustomerEntityTreeNode[];
+  // Presentation-only ancestry flag. The entity DTO is never mutated:
+  // a broken presentation edge still renders the entity exactly once.
+  ancestryNote?: "cycle-broken" | "self-parent" | "unlisted-parent";
+}
+
+// Customer Master's visible entities form a forest, but ABAC can authorize
+// a child without its parent and stored parents can cycle (or self-point),
+// so the drawable forest must be derived defensively: every input entity is
+// emitted exactly once, ordinary order is preserved, and only the
+// presentation edge needed to establish a root is broken (#906).
+export function buildCustomerEntityTree(entities: CustomerMasterEntity[]): CustomerEntityTreeNode[] {
+  const byId = new Map(entities.map((entity) => [entity.corporate_entity_id, entity]));
+  // Tentative presentation parents: visible and non-self only.
+  const parentOf = new Map<string, string | null>();
+  const noteOf = new Map<string, NonNullable<CustomerEntityTreeNode["ancestryNote"]>>();
+  for (const entity of entities) {
+    const id = entity.corporate_entity_id;
+    const parent = entity.parent_entity_id;
+    if (!parent || !byId.has(parent)) {
+      parentOf.set(id, null);
+      if (parent) {
+        noteOf.set(id, "unlisted-parent");
+      }
+    } else if (parent === id) {
+      parentOf.set(id, null);
+      noteOf.set(id, "self-parent");
+    } else {
+      parentOf.set(id, parent);
+    }
+  }
+  // Break presentation cycles deterministically: walking from each entity
+  // in input order, the edge closing a revisited ancestor is cut so its
+  // predecessor becomes a root. Earlier members keep their edges, so the
+  // result is stable for a given input order and always acyclic.
+  for (const entity of entities) {
+    const path: string[] = [];
+    let cursor: string | null = entity.corporate_entity_id;
+    while (cursor !== null && !path.includes(cursor)) {
+      path.push(cursor);
+      cursor = parentOf.get(cursor) ?? null;
+    }
+    if (cursor !== null) {
+      const predecessor = path[path.length - 1];
+      parentOf.set(predecessor, null);
+      noteOf.set(predecessor, "cycle-broken");
+    }
+  }
+  const childrenByParent = new Map<string, CustomerMasterEntity[]>();
+  const roots: CustomerMasterEntity[] = [];
+  for (const entity of entities) {
+    const parent = parentOf.get(entity.corporate_entity_id);
+    if (parent) {
+      const siblings = childrenByParent.get(parent) ?? [];
+      siblings.push(entity);
+      childrenByParent.set(parent, siblings);
+    } else {
+      roots.push(entity);
+    }
+  }
+  const toNode = (entity: CustomerMasterEntity): CustomerEntityTreeNode => ({
+    entity,
+    children: (childrenByParent.get(entity.corporate_entity_id) ?? []).map(toNode),
+    ...(noteOf.has(entity.corporate_entity_id)
+      ? { ancestryNote: noteOf.get(entity.corporate_entity_id) }
+      : {}),
+  });
+  return roots.map(toNode);
+}