@stigmer/server 3.15.2 → 3.15.3-dev.20260914121148

package/dist/store/port-contract.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The port-contract runner — the scaffolding every domain store PORT's
+ * contract kit is built on (identity-account's store-contract.ts since
+ * 20260911.11 A11; IamPolicy's since 20260913.01 slice 2, when this was
+ * lifted out of the first kit so the second did not carry a copy).
+ *
+ * A port kit is a list of named cases a DRIVER's test iterates: open
+ * source runs them over its adapter on sqlite and Postgres, a composition
+ * runs the same list over the store it registers as a driver, so "the port
+ * holds" is one statement proven per driver, never restated per
+ * repository. This module owns the part every kit shares and no kit should
+ * restate: a FRESH fixture per case, the body run over it, cleanup after,
+ * and the rule that a failing body is the failure reported (a cleanup that
+ * fails after a failed body must not replace the assertion that matters
+ * with a teardown detail; a cleanup that fails after a passing body is a
+ * real failure).
+ *
+ * Shape. The package's precedent is store/__tests__/store-contract.ts —
+ * `describeStoreContract(makeFixture)` over the generic Store, a vitest
+ * `describe`. A port kit is consumed by ANOTHER package's tests through the
+ * published barrel, so it ships in dist/ and must not import vitest (a
+ * devDependency that would enter the root barrel's runtime import graph).
+ * It therefore returns cases instead of calling `describe`, asserts through
+ * node:assert/strict, and the consumer's framework does
+ * `for (const c of cases) it(c.name, c.run)`. Do not "fix" it back to the
+ * precedent's vitest shape.
+ *
+ * `disconnect` is the one escape hatch a port cannot express: a port has
+ * no lifecycle by design (a composition owns its store's), yet "an outage
+ * never reads as not-found" is the line that matters most, so a fixture
+ * cuts its store from the database and the kit asserts that the fault
+ * propagates. `cleanup` must tolerate a disconnected store.
+ */
+/** One fresh, isolated store per case, plus the one escape hatch the port cannot express. */
+export interface PortContractFixture<Port> {
+    readonly store: Port;
+    /**
+     * Cuts the store from its database so every later call is an
+     * infrastructure fault. `cleanup` still runs afterwards and must tolerate
+     * a disconnected store (both OSS drivers' `close` is idempotent; a pool
+     * fixture ends a per-case pool here and skips it in cleanup).
+     */
+    disconnect(): Promise<void>;
+    cleanup(): Promise<void>;
+}
+export interface PortContractCase {
+    /** The contract line, in the port's words; the framework prints it as the test name. */
+    readonly name: string;
+    /** Makes a FRESH fixture, runs the case, cleans up. A failing assertion wins over a failing cleanup. */
+    run(): Promise<void>;
+}
+/** A case body over a live fixture; the runner owns the fixture's lifecycle around it. */
+export type PortContractBody<Port> = (fixture: PortContractFixture<Port>) => Promise<void>;
+/** A kit's declaration: the contract line and the body that proves it. */
+export type PortContractDeclaration<Port> = readonly [
+    name: string,
+    body: PortContractBody<Port>
+];
+/** The kit's declarations as runnable cases over `makeFixture`, one fresh fixture per case, in declared order. */
+export declare function portContractCases<Port>(declarations: ReadonlyArray<PortContractDeclaration<Port>>, makeFixture: () => Promise<PortContractFixture<Port>>): ReadonlyArray<PortContractCase>;
+//# sourceMappingURL=port-contract.d.ts.map

package/dist/store/port-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-contract.d.ts","sourceRoot":"","sources":["../../src/store/port-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,6FAA6F;AAC7F,MAAM,WAAW,mBAAmB,CAAC,IAAI;IACvC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IACrB;;;;;OAKG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wGAAwG;IACxG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACtB;AAED,0FAA0F;AAC1F,MAAM,MAAM,gBAAgB,CAAC,IAAI,IAAI,CACnC,OAAO,EAAE,mBAAmB,CAAC,IAAI,CAAC,KAC/B,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB,0EAA0E;AAC1E,MAAM,MAAM,uBAAuB,CAAC,IAAI,IAAI,SAAS;IACnD,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,gBAAgB,CAAC,IAAI,CAAC;CAC7B,CAAC;AA6BF,kHAAkH;AAClH,wBAAgB,iBAAiB,CAAC,IAAI,EACpC,YAAY,EAAE,aAAa,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC,EAC1D,WAAW,EAAE,MAAM,OAAO,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,GACpD,aAAa,CAAC,gBAAgB,CAAC,CAKjC"}

package/dist/store/port-contract.js

@@ -0,0 +1,67 @@
+/**
+ * The port-contract runner — the scaffolding every domain store PORT's
+ * contract kit is built on (identity-account's store-contract.ts since
+ * 20260911.11 A11; IamPolicy's since 20260913.01 slice 2, when this was
+ * lifted out of the first kit so the second did not carry a copy).
+ *
+ * A port kit is a list of named cases a DRIVER's test iterates: open
+ * source runs them over its adapter on sqlite and Postgres, a composition
+ * runs the same list over the store it registers as a driver, so "the port
+ * holds" is one statement proven per driver, never restated per
+ * repository. This module owns the part every kit shares and no kit should
+ * restate: a FRESH fixture per case, the body run over it, cleanup after,
+ * and the rule that a failing body is the failure reported (a cleanup that
+ * fails after a failed body must not replace the assertion that matters
+ * with a teardown detail; a cleanup that fails after a passing body is a
+ * real failure).
+ *
+ * Shape. The package's precedent is store/__tests__/store-contract.ts —
+ * `describeStoreContract(makeFixture)` over the generic Store, a vitest
+ * `describe`. A port kit is consumed by ANOTHER package's tests through the
+ * published barrel, so it ships in dist/ and must not import vitest (a
+ * devDependency that would enter the root barrel's runtime import graph).
+ * It therefore returns cases instead of calling `describe`, asserts through
+ * node:assert/strict, and the consumer's framework does
+ * `for (const c of cases) it(c.name, c.run)`. Do not "fix" it back to the
+ * precedent's vitest shape.
+ *
+ * `disconnect` is the one escape hatch a port cannot express: a port has
+ * no lifecycle by design (a composition owns its store's), yet "an outage
+ * never reads as not-found" is the line that matters most, so a fixture
+ * cuts its store from the database and the kit asserts that the fault
+ * propagates. `cleanup` must tolerate a disconnected store.
+ */
+/**
+ * Runs `body` over a fresh fixture. The body's failure is the one reported:
+ * a cleanup failure after a failed body would otherwise replace the
+ * assertion that matters with a teardown detail.
+ */
+async function withFixture(makeFixture, body) {
+    const fixture = await makeFixture();
+    let failed = false;
+    try {
+        await body(fixture);
+    }
+    catch (error) {
+        failed = true;
+        throw error;
+    }
+    finally {
+        try {
+            await fixture.cleanup();
+        }
+        catch (cleanupError) {
+            if (!failed) {
+                throw cleanupError;
+            }
+        }
+    }
+}
+/** The kit's declarations as runnable cases over `makeFixture`, one fresh fixture per case, in declared order. */
+export function portContractCases(declarations, makeFixture) {
+    return declarations.map(([name, body]) => ({
+        name,
+        run: () => withFixture(makeFixture, body),
+    }));
+}
+//# sourceMappingURL=port-contract.js.map

package/dist/store/port-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-contract.js","sourceRoot":"","sources":["../../src/store/port-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAiCH;;;;GAIG;AACH,KAAK,UAAU,WAAW,CACxB,WAAqD,EACrD,IAA4B;IAE5B,MAAM,OAAO,GAAG,MAAM,WAAW,EAAE,CAAC;IACpC,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC;IACtB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,GAAG,IAAI,CAAC;QACd,MAAM,KAAK,CAAC;IACd,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YACH,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;QAC1B,CAAC;QAAC,OAAO,YAAY,EAAE,CAAC;YACtB,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,YAAY,CAAC;YACrB,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED,kHAAkH;AAClH,MAAM,UAAU,iBAAiB,CAC/B,YAA0D,EAC1D,WAAqD;IAErD,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;QACzC,IAAI;QACJ,GAAG,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,WAAW,EAAE,IAAI,CAAC;KAC1C,CAAC,CAAC,CAAC;AACN,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/server",
-  "version": "3.15.2",
+  "version": "3.15.3-dev.20260914121148",
   "description": "The Stigmer OSS control plane as a composable library: composeServer, the extension registry and the driver seams a composition builds on. The self-contained deployable of the same server is @stigmer/server-slim.",
   "license": "Apache-2.0",
   "type": "module",
@@ -62,9 +62,9 @@
     "@connectrpc/connect-node": "^2.0.0",
     "@kubernetes/client-node": "2.0.0",
     "@opentelemetry/api": "^1.9.0",
-    "@stigmer/protos": "3.15.2",
-    "@stigmer/temporal-codecs": "3.15.2",
-    "@stigmer/zip-structure": "3.15.2",
+    "@stigmer/protos": "3.15.3-dev.20260914121148",
+    "@stigmer/temporal-codecs": "3.15.3-dev.20260914121148",
+    "@stigmer/zip-structure": "3.15.3-dev.20260914121148",
     "@temporalio/activity": "1.16.2",
     "@temporalio/client": "1.16.2",
     "@temporalio/common": "1.16.2",

package/src/boot/compose.ts

@@ -72,6 +72,12 @@ import {
 import { ensureOperatorAccount } from "../domain/identityaccount/operator.js";
 import { newDirectAccountProvisioner } from "../domain/identityaccount/provisioning.js";
 import { newResourceIdentityAccountStore } from "../domain/identityaccount/resource-store.js";
+import { registerIamPolicyServices } from "../domain/iampolicy/controller.js";
+import { newIamPolicyGrantPath } from "../domain/iampolicy/grant-path.js";
+import { newOrganizationOnlyGrantScope } from "../domain/iampolicy/grant-scope.js";
+import { newMembershipRules } from "../domain/iampolicy/membership.js";
+import { newResourceIamPolicyStore } from "../domain/iampolicy/resource-store.js";
+import { newBuiltInRoleLifecycle } from "../domain/iampolicy/role-lifecycle.js";
 import { newIssuerDiscovery } from "../identity/oidc-discovery.js";
 import { newOidcUserInfoClient } from "../identity/oidc-userinfo.js";
 import { newApiKeyIdentityVerifier } from "../domain/apikey/verifier.js";
@@ -285,13 +291,13 @@ export async function composeServer(
   // position 1 of every chain calls it (O2).
   const authorizer =
     extensions.authorizer ?? newPermissiveSingleTeamAuthorizer();
-  // The C2 tuple-lifecycle driver (ruling Q2): undefined = the three
-  // shared tuple steps (CreateAuthorizationTuples / CleanupIamPolicies /
-  // UpdateVisibilityTuples) no-op — OSS behavior byte-identical. Handed
-  // to every resource controller as an explicit dependency, the same
-  // threading as the authorizer.
-  const authorizationLifecycle =
-    extensions.drivers.resourceAuthorizationLifecycle;
+  // The built-in authorization POSTURE (20260913.01, Q-OR-6), named once:
+  // no unit registered an Authorizer, so the roles open source records
+  // exist to feed the built-in one. Under it — and only under it — the
+  // identity-accounts stage below installs the built-in role lifecycle
+  // and the membership rules; a composition with its own Authorizer has
+  // its own onboarding and gets neither.
+  const builtInAuthorization = extensions.authorizer === undefined;
 
   // Stage: storage — the driver selection seam (DD-010): DATABASE_URL
   // present → Postgres (async connect + advisory-locked migrations), else
@@ -338,11 +344,67 @@ export async function composeServer(
   const identityAccounts =
     extensions.drivers.identityAccountStore ??
     newResourceIdentityAccountStore(store);
+  // The IamPolicy row half (20260913.01): the store PORT bound the same way
+  // (`drivers.iamPolicyStore`, Q-OR-10; open source's adapter over `store`
+  // when absent) and the domain's ONE grant and revoke path built over it.
+  // The grant path's lifecycle is the composed DRIVER — the cloud's tuple
+  // hooks — never the built-in lifecycle below, which sits ON TOP of the
+  // grant path; that direction keeps the two acyclic (S1 finding B). Both
+  // bindings are what the IamPolicy controller registers over (routes).
+  const iamPolicies =
+    extensions.drivers.iamPolicyStore ?? newResourceIamPolicyStore(store);
+  const iamPolicyGrantPath = newIamPolicyGrantPath({
+    policies: iamPolicies,
+    lifecycle: extensions.drivers.resourceAuthorizationLifecycle,
+    logger,
+  });
+  // The C2 tuple-lifecycle driver (ruling Q2): undefined = the three
+  // shared tuple steps (CreateAuthorizationTuples / CleanupIamPolicies /
+  // UpdateVisibilityTuples) no-op before any resolution work — OSS
+  // behavior byte-identical. Handed to every resource controller as an
+  // explicit dependency, the same threading as the authorizer.
+  const authorizationLifecycle =
+    extensions.drivers.resourceAuthorizationLifecycle;
+  // The lifecycle the ORGANIZATION and IDENTITY-ACCOUNT controllers get
+  // (20260913.01 slice 4, Q-S4-8): the composed driver when a unit
+  // registers one; otherwise, under the built-in posture, open source's
+  // role lifecycle — the organization creator's `owner` row, cleanup on
+  // organization and account deletes — the row half of the seam that
+  // records authorization at lifecycle points in every edition
+  // (extensions/resource-authorization.ts, corrected 2026-09-13). Those
+  // two kinds ONLY, because a lifecycle on a controller turns on the
+  // steps' full event RESOLUTION for that kind, and resolution fails a
+  // request whose configured parent id is missing (Java parity the
+  // cloud relies on) — a state open source admits by contract (a memory
+  // captured with no credential has no subject). The built-in object is
+  // a two-kind role recorder, so only two controllers see it; every other
+  // controller keeps the composed driver above and stays byte-identical.
+  const roleLifecycle =
+    authorizationLifecycle ??
+    (builtInAuthorization
+      ? newBuiltInRoleLifecycle({
+          grantPath: iamPolicyGrantPath,
+          accounts: identityAccounts,
+        })
+      : undefined);
+  // The operator seam is read once here for both its consumers below: the
+  // trusted-local account ensure and the membership rules' operator-email
+  // arm (which also applies under an authentication posture — the
+  // operator who signs in through OIDC is admin of what the laptop has).
+  const operatorIdentity = operatorIdentitySnapshot();
+  const membership = builtInAuthorization
+    ? newMembershipRules({
+        grantPath: iamPolicyGrantPath,
+        policies: iamPolicies,
+        store,
+        operatorEmail: operatorIdentity.email,
+      })
+    : undefined;
   const identityAccountPath = {
     accounts: identityAccounts,
     logger,
     authorizer,
-    authorizationLifecycle,
+    authorizationLifecycle: roleLifecycle,
   };
   const createIdentityAccount = newCreateAccountPath(
     identityAccountPath,
@@ -377,11 +439,22 @@ export async function composeServer(
   if (!requireAuthentication) {
     const operator = await ensureOperatorAccount(
       { accounts: identityAccounts, createAccount: createIdentityAccount },
-      operatorIdentitySnapshot(),
+      operatorIdentity,
     );
     logger.info("trusted-local operator account ensured", {
       accountId: operator.metadata?.id ?? "",
     });
+    // The laptop's one principal owns what the laptop has (Q-OR-6c):
+    // `owner` on every organization with no owner row, create-if-absent,
+    // so the Members page tells the truth from the first boot after roles
+    // exist. Under the built-in posture only — a unit with its own
+    // Authorizer and no authentication posture keeps its own rules.
+    if (membership !== undefined) {
+      await membership.ensureOperatorOwnership(operator);
+      logger.info("trusted-local operator ownership ensured", {
+        accountId: operator.metadata?.id ?? "",
+      });
+    }
   }
 
   // Stage: keys — the ratified fail-loud boot ASYMMETRY (D2 cross-domain
@@ -899,7 +972,9 @@ export async function composeServer(
       logger,
       authorizer,
       gateSteps: extensions.gateSteps,
-      authorizationLifecycle,
+      // The role lifecycle (the identity stage): the composed driver, or
+      // open source's owner-row writer under the built-in posture.
+      authorizationLifecycle: roleLifecycle,
       organizationDirectory: extensions.drivers.organizationDirectory,
     });
     // ApiKey is the first domain born AFTER the Go port (O3, 20260827.06 —
@@ -919,11 +994,33 @@ export async function composeServer(
     // composition adds what differs per edition through the registry —
     // the federation capability (the four federated RPC arms) and the
     // provision slot's gate steps (the cloud's personal organization).
+    // The membership rules are core, selected by posture (20260913.01).
     registerIdentityAccountServices(router, {
       ...identityAccountPath,
       provisioner: identityAccountProvisioner,
       federation: extensions.drivers.identityFederation,
       gateSteps: extensions.gateSteps,
+      membership,
+    });
+    // IamPolicy (20260913.01): the ROW half served once by open source in
+    // every edition over the store port and the grant path bound in the
+    // identity stage. A composition adds what differs per edition through
+    // the registry — a wider grant scope (`drivers.policyGrantScope`; the
+    // default is open source's organization-only scope, installed at this
+    // `??` site like the permissive Authorizer) and the tuple-half query
+    // engine (`drivers.authorizationQueries`; absent, those RPCs refuse
+    // UNIMPLEMENTED). The chains take no lifecycle: a policy is the
+    // authorization record, not a protected resource.
+    registerIamPolicyServices(router, {
+      grantPath: iamPolicyGrantPath,
+      policies: iamPolicies,
+      accounts: identityAccounts,
+      authorizer,
+      grantScope:
+        extensions.drivers.policyGrantScope ?? newOrganizationOnlyGrantScope(),
+      queries: extensions.drivers.authorizationQueries,
+      edition: extensions.edition,
+      logger,
     });
     registerEnvironmentServices(router, {
       store,

package/src/domain/iampolicy/__tests__/access-lists.test.ts

@@ -0,0 +1,238 @@
+/**
+ * Pins access-lists.ts (20260913.01 slice 5): the row-driven answer to
+ * "who has access, with which roles" — the hierarchy walk over scope
+ * tuples (child → parent through the resource's one structural link, at
+ * most five steps, `platform` terminal) and the grouping of assignable-
+ * role rows by principal in first-seen order, enriched where the display
+ * resolver answers and rendered as kind/id with the id as its name
+ * everywhere else (the Java PrincipalEnricher fallback). Moved from the
+ * cloud's iam/policy/access-lists.ts; the arms below are the Java
+ * contract read from that file.
+ */
+import { create } from "@bufbuild/protobuf";
+import { describe, expect, it } from "vitest";
+
+import { IamPolicySchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
+import { ApiResourceRefViewSchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/io_pb";
+import type { IamPolicySpec } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
+
+import { buildPrincipalAccessList, resolveHierarchy } from "../access-lists.js";
+import type { PrincipalDisplayResolver } from "../access-lists.js";
+import { policyIdFor } from "../constants.js";
+import { fakeIamPolicyStore, orgRole, triple } from "./support.js";
+
+function row(spec: IamPolicySpec) {
+  return create(IamPolicySchema, {
+    metadata: { id: policyIdFor(spec) },
+    spec,
+  });
+}
+
+/** `child` is scoped under `parent`: the structural link the walk follows. */
+function scopeLink(
+  child: { kind: string; id: string },
+  parent: { kind: string; id: string },
+): IamPolicySpec {
+  return triple(parent, parent.kind, child);
+}
+
+const nobody: PrincipalDisplayResolver = {
+  resolveIdentityAccounts: () => Promise.resolve(new Map()),
+};
+
+describe("resolveHierarchy", () => {
+  it("is the resource alone when inherited grants are not asked for", async () => {
+    const store = fakeIamPolicyStore();
+    await store.save(
+      row(
+        scopeLink(
+          { kind: "agent", id: "a1" },
+          { kind: "organization", id: "acme" },
+        ),
+      ),
+    );
+    expect(await resolveHierarchy(store, "agent", "a1", false)).toEqual([
+      { kind: "agent", id: "a1" },
+    ]);
+  });
+
+  it("climbs the scope links child-first and stops where no link exists", async () => {
+    const store = fakeIamPolicyStore();
+    await store.save(
+      row(
+        scopeLink(
+          { kind: "agent", id: "a1" },
+          { kind: "organization", id: "acme" },
+        ),
+      ),
+    );
+    expect(await resolveHierarchy(store, "agent", "a1", true)).toEqual([
+      { kind: "agent", id: "a1" },
+      { kind: "organization", id: "acme" },
+    ]);
+  });
+
+  it("stops at platform, the terminal kind, even when platform carries a link", async () => {
+    const store = fakeIamPolicyStore();
+    await store.save(
+      row(
+        scopeLink(
+          { kind: "organization", id: "acme" },
+          { kind: "platform", id: "stigmer" },
+        ),
+      ),
+    );
+    await store.save(
+      row(
+        scopeLink(
+          { kind: "platform", id: "stigmer" },
+          { kind: "organization", id: "loop" },
+        ),
+      ),
+    );
+    expect(await resolveHierarchy(store, "organization", "acme", true)).toEqual(
+      [
+        { kind: "organization", id: "acme" },
+        { kind: "platform", id: "stigmer" },
+      ],
+    );
+  });
+
+  it("walks at most five steps — a cycle cannot spin it", async () => {
+    const store = fakeIamPolicyStore();
+    await store.save(
+      row(scopeLink({ kind: "agent", id: "a" }, { kind: "agent", id: "b" })),
+    );
+    await store.save(
+      row(scopeLink({ kind: "agent", id: "b" }, { kind: "agent", id: "a" })),
+    );
+    const levels = await resolveHierarchy(store, "agent", "a", true);
+    expect(levels).toHaveLength(6);
+  });
+
+  it("ignores rows whose principal is a person or whose relation is owner/creator — those are grants, not links", async () => {
+    const store = fakeIamPolicyStore();
+    await store.save(row(orgRole("ida_alice", "owner", "acme")));
+    await store.save(
+      row(
+        triple({ kind: "organization", id: "parent" }, "owner", {
+          kind: "organization",
+          id: "acme",
+        }),
+      ),
+    );
+    expect(await resolveHierarchy(store, "organization", "acme", true)).toEqual(
+      [{ kind: "organization", id: "acme" }],
+    );
+  });
+});
+
+describe("buildPrincipalAccessList", () => {
+  it("answers nothing for a resource with no assignable-role rows — structural rows never show", async () => {
+    const store = fakeIamPolicyStore();
+    await store.save(
+      row(
+        scopeLink(
+          { kind: "agent", id: "a1" },
+          { kind: "organization", id: "acme" },
+        ),
+      ),
+    );
+    expect(
+      await buildPrincipalAccessList(store, nobody, [
+        { kind: "agent", id: "a1" },
+      ]),
+    ).toEqual([]);
+  });
+
+  it("groups by principal in first-seen order, one RoleGrant per row, direct grants without an owner resource", async () => {
+    const store = fakeIamPolicyStore();
+    await store.save(row(orgRole("ida_bob", "member", "acme")));
+    await store.save(row(orgRole("ida_alice", "owner", "acme")));
+    await store.save(row(orgRole("ida_bob", "viewer", "acme")));
+    const entries = await buildPrincipalAccessList(store, nobody, [
+      { kind: "organization", id: "acme" },
+    ]);
+    expect(entries.map((e) => e.principal?.id)).toEqual([
+      "ida_bob",
+      "ida_alice",
+    ]);
+    const bob = entries[0];
+    expect(bob?.roles.map((g) => g.role?.code)).toEqual(["member", "viewer"]);
+    expect(
+      bob?.roles.every((g) => !g.isInherited && g.ownerResource === undefined),
+    ).toBe(true);
+  });
+
+  it("marks grants from a parent level as inherited and names the owning level", async () => {
+    const store = fakeIamPolicyStore();
+    await store.save(row(orgRole("ida_alice", "admin", "acme")));
+    const entries = await buildPrincipalAccessList(store, nobody, [
+      { kind: "agent", id: "a1" },
+      { kind: "organization", id: "acme" },
+    ]);
+    expect(entries).toHaveLength(1);
+    const grant = entries[0]?.roles[0];
+    expect(grant?.isInherited).toBe(true);
+    expect(grant?.ownerResource?.kind).toBe("organization");
+    expect(grant?.ownerResource?.id).toBe("acme");
+    expect(grant?.role?.code).toBe("admin");
+  });
+
+  it("renders an unresolved principal of ANY kind as kind/id with the id as its name", async () => {
+    const store = fakeIamPolicyStore();
+    await store.save(row(orgRole("ida_ghost", "viewer", "acme")));
+    await store.save(
+      row(
+        triple({ kind: "team", id: "tm_1" }, "viewer", {
+          kind: "organization",
+          id: "acme",
+        }),
+      ),
+    );
+    const entries = await buildPrincipalAccessList(store, nobody, [
+      { kind: "organization", id: "acme" },
+    ]);
+    expect(
+      entries.map((e) => [
+        e.principal?.kind,
+        e.principal?.id,
+        e.principal?.name,
+      ]),
+    ).toEqual([
+      ["identity_account", "ida_ghost", "ida_ghost"],
+      ["team", "tm_1", "tm_1"],
+    ]);
+  });
+
+  it("asks the resolver once for the identity-account ids and uses its view where it answers", async () => {
+    const store = fakeIamPolicyStore();
+    await store.save(row(orgRole("ida_alice", "owner", "acme")));
+    await store.save(row(orgRole("ida_bob", "member", "acme")));
+    const asked: string[][] = [];
+    const resolver: PrincipalDisplayResolver = {
+      resolveIdentityAccounts: (ids) => {
+        asked.push([...ids]);
+        return Promise.resolve(
+          new Map([
+            [
+              "ida_alice",
+              create(ApiResourceRefViewSchema, {
+                kind: "identity_account",
+                id: "ida_alice",
+                name: "Alice",
+                email: "alice@example.com",
+              }),
+            ],
+          ]),
+        );
+      },
+    };
+    const entries = await buildPrincipalAccessList(store, resolver, [
+      { kind: "organization", id: "acme" },
+    ]);
+    expect(asked).toEqual([["ida_alice", "ida_bob"]]);
+    expect(entries.map((e) => e.principal?.name)).toEqual(["Alice", "ida_bob"]);
+    expect(entries[0]?.principal?.email).toBe("alice@example.com");
+  });
+});