@stigmer/server 3.26.0 → 3.27.1

package/src/domain/iampolicy/constants.ts

@@ -36,7 +36,9 @@
  * console and SDK show these sentences verbatim, so they are contract. The
  * new sentences are the two edition refusals (the federation shape), the
  * unknown permission, the unknown principal kind (the resource sentence's
- * shape) and the malformed triple.
+ * shape), the malformed triple, and the four principal refusals a team
+ * grantee brought (a person's qualifier, a team's qualifier, a kind no
+ * team may be granted, a role a team may not hold).
  */
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import type {
@@ -157,8 +159,8 @@ export const ROLES_RECONCILED_KEY = "membership_rules_reconciled";
 /**
  * The principal kinds a PERSON may grant a role to — the user `create`
  * lane's grantee vocabulary (2026-09-14, session 9 ruling Q-S9-2; the
- * security read's finding 41). A role names a person, so the one grantee
- * is the identity account. A row whose principal is a RESOURCE
+ * security read's finding 41): a person (the identity account) and a team
+ * of people. A row whose principal is a RESOURCE
  * (`organization:A#organization@platform_client:X`, `#managed_org`) is a
  * structural link, and structural links are `bootstrapPolicy`'s — the
  * platform's own lane, which skips role validation by design.
@@ -169,14 +171,27 @@ export const ROLES_RECONCILED_KEY = "membership_rules_reconciled";
  * two cannot drift), and the hierarchy walk follows it. Without the arm, a
  * person with `can_grant_access` on organization B could write
  * `organization:A#member@organization:B` and B's Members page, asked for
- * inherited access, would list A's people. The cloud's `create` had the
- * same gap; the store's exclusion also keeps the cloud's Java-era `team`,
- * which is not an ApiResourceKind and so no wire spec can name.
+ * inherited access, would list A's people.
+ *
+ * Each kind grants through its own list: a person the kind's
+ * `grantable_roles`, a team its `team_grantable_roles`, always as the
+ * team's members (`TEAM_MEMBERS_RELATION`). A kind that lists no team role
+ * — `organization` among them, so open source's organization-only scope —
+ * grants a team nothing.
  */
 export const USER_GRANT_PRINCIPAL_KINDS: ReadonlyArray<ApiResourceKind> = [
   ApiResourceKind.identity_account,
+  ApiResourceKind.team,
 ];
 
+/**
+ * The one relation a team principal names: the team's members. A grant to
+ * `team:<id>#member` is a grant to every member, and membership is bounded
+ * by organization membership in the model, so leaving the organization
+ * ends the grant with no cleanup.
+ */
+export const TEAM_MEMBERS_RELATION = "member";
+
 // ---------------------------------------------------------------------------
 // Byte-pinned copy (the cloud handlers' sentences, moved as-is).
 // ---------------------------------------------------------------------------
@@ -249,6 +264,35 @@ export function principalNotGrantableMessage(kind: string): string {
   return `Principal kind '${kind}' cannot be granted a role. Grantable principal kinds: [${grantable.join(", ")}]`;
 }
 
+/**
+ * A person principal carrying a relation qualifier (INVALID_ARGUMENT). A
+ * person is granted a role directly; `identity_account:<id>#<relation>`
+ * names no one, and OpenFGA would refuse the tuple after the row was
+ * written.
+ */
+export function personQualifierMessage(relation: string): string {
+  return `Principal kind 'identity_account' takes no relation; got '${relation}'`;
+}
+
+/** A team principal naming a relation other than its members (INVALID_ARGUMENT). */
+export function teamQualifierMessage(relation: string): string {
+  return `A team principal must name the relation '${TEAM_MEMBERS_RELATION}' (the team's members); got '${relation}'`;
+}
+
+/** A team grant on a kind that lists no team role (INVALID_ARGUMENT). */
+export function teamNotGrantableMessage(kind: string): string {
+  return `A team cannot be granted access to resource kind '${kind}'.`;
+}
+
+/** A team grant of a role the kind does not let a team hold (INVALID_ARGUMENT); the list in kind_meta order. */
+export function teamRoleNotGrantableMessage(
+  role: string,
+  kind: string,
+  grantable: ReadonlyArray<string>,
+): string {
+  return `Role '${role}' cannot be granted to a team on resource kind '${kind}'. Roles a team can hold: [${grantable.join(", ")}]`;
+}
+
 /** A triple field holding a canonical-text delimiter (INVALID_ARGUMENT; Q-S2-1). */
 export function malformedTripleMessage(field: string): string {
   return `policy ${field} must not contain ':', '#' or '@'`;

package/src/domain/iampolicy/controller.ts

@@ -31,9 +31,11 @@
  *     triple — strictly safer than the cloud's silent default instance.
  *   - `create` validates the role BEFORE it writes (the cloud's order): a
  *     held row under a role the kind does not grant is refused, never
- *     answered as a duplicate. It also grants to PEOPLE only (Q-S9-2,
- *     2026-09-14): a principal that is not an identity account is
- *     INVALID_ARGUMENT — a row naming a resource as its principal is the
+ *     answered as a duplicate. It also grants to PEOPLE and TEAMS only
+ *     (Q-S9-2, 2026-09-14): any other principal is INVALID_ARGUMENT, and a
+ *     team only on the roles its kind lets a team hold (steps.ts) and,
+ *     where an edition serves teams, only a team the create gate slot
+ *     admits — a row naming a resource as its principal is the
  *     structural link the hierarchy walk follows, `bootstrapPolicy`'s to
  *     write, and through this lane would have let a right on one
  *     organization list another's members. The cloud's create had the
@@ -136,9 +138,12 @@ import type { ServerEdition } from "@stigmer/protos/ai/stigmer/platform/v1/serve
 import type { Logger } from "../../boot/logger.js";
 import type { AuthorizationQueryEngine } from "../../extensions/authorization-queries.js";
 import type { Authorizer } from "../../extensions/authorizer.js";
+import { stepsForSlot } from "../../extensions/gate-slots.js";
+import type { ResolvedGateSteps } from "../../extensions/gate-slots.js";
 import { isPlatformPipelineCaller } from "../../extensions/identity.js";
 import type { CallerIdentity } from "../../extensions/identity.js";
 import type { PolicyGrantScope } from "../../extensions/policy-grant-scope.js";
+import type { PrincipalDisplay } from "../../extensions/principal-display.js";
 import {
   kindByEnumName,
   kindEnumName,
@@ -209,6 +214,10 @@ export interface IamPolicyControllerDeps {
   readonly grantScope: PolicyGrantScope;
   /** The composed query engine — undefined = the tuple-half RPCs refuse UNIMPLEMENTED. */
   readonly queries: AuthorizationQueryEngine | undefined;
+  /** The composed principal display — undefined = a non-person grantee renders in the id fallback shape. */
+  readonly principalDisplay: PrincipalDisplay | undefined;
+  /** The merged gate steps; `create` splices `iam-policy-create:pre-side-effect-gate`. */
+  readonly gateSteps: ResolvedGateSteps;
   /** The served edition — `checkMyPermission`'s first arm reads a kind's tier against it. */
   readonly edition: ServerEdition;
   readonly logger: Logger;
@@ -285,7 +294,10 @@ function guardSystemRpc(method: DescMethod, caller: CallerIdentity): void {
 // The command chains
 // ---------------------------------------------------------------------------
 
-/** `create`: the wire refusal, then Authorize → ValidateProto → ValidateGrantableRole → Grant. */
+/**
+ * `create`: the wire refusal, then Authorize → ValidateProto →
+ * ValidateGrantableRole → [iam-policy-create:pre-side-effect-gate] → Grant.
+ */
 function createPolicy(
   deps: IamPolicyControllerDeps,
   spec: IamPolicySpec,
@@ -303,8 +315,8 @@ function createPolicy(
 
 /**
  * The grant chain both `create` and `bootstrapPolicy` run; only the user
- * lane validates the role — bootstrap writes structural relations no
- * scope would admit.
+ * lane validates the role and runs the create gate slot — bootstrap writes
+ * structural relations no scope would admit and no edition gates.
  */
 async function grantThroughChain(
   deps: IamPolicyControllerDeps,
@@ -327,6 +339,12 @@ async function grantThroughChain(
     .addStep(newValidateProtoStep());
   if (validateRole) {
     pipeline.addStep(newValidateGrantableRoleStep(deps.grantScope));
+    for (const step of stepsForSlot<typeof IamPolicySpecSchema>(
+      deps.gateSteps,
+      "iam-policy-create:pre-side-effect-gate",
+    )) {
+      pipeline.addStep(step);
+    }
   }
   await pipeline.addStep(newGrantStep(deps.grantPath)).build().execute(reqCtx);
   return policyResultOf(reqCtx, method);
@@ -600,7 +618,12 @@ async function listResourceAccessByPrincipal(
       resource.id,
       input.includeInherited,
     );
-    return buildPrincipalAccessList(deps.policies, displayResolver, hierarchy);
+    return buildPrincipalAccessList(
+      deps.policies,
+      displayResolver,
+      deps.principalDisplay,
+      hierarchy,
+    );
   }, "failed to list resource access");
   return create(ResourceAccessByPrincipalListSchema, {
     entries: [...entries],

package/src/domain/iampolicy/resource-store.ts

@@ -54,13 +54,10 @@ const KIND = ApiResourceKind.iam_policy;
  * principal half is derived from the user lane's grantee vocabulary
  * (constants.ts USER_GRANT_PRINCIPAL_KINDS; Q-S9-2) so the writer's "who a
  * person may grant to" and the reader's "what is a person, not a parent"
- * are one definition; `team` stays for the cloud's Java-era rows (not an
- * ApiResourceKind, so no wire spec names it).
+ * are one definition: the identity account and the team.
  */
-const NON_STRUCTURAL_PRINCIPAL_KINDS: ReadonlyArray<string> = [
-  ...USER_GRANT_PRINCIPAL_KINDS.map((kind) => kindEnumName(kind)),
-  "team",
-];
+const NON_STRUCTURAL_PRINCIPAL_KINDS: ReadonlyArray<string> =
+  USER_GRANT_PRINCIPAL_KINDS.map((kind) => kindEnumName(kind));
 const NON_STRUCTURAL_RELATIONS: ReadonlyArray<string> = ["owner", "creator"];
 
 export function newResourceIamPolicyStore(store: Store): IamPolicyStore {

package/src/domain/iampolicy/steps.ts

@@ -30,17 +30,32 @@
  *      intersection — the cloud's second copy listing it. Intersecting is
  *      what keeps a scope from WIDENING the contract by accident;
  *   5. the PRINCIPAL (Q-S9-2, 2026-09-14; constants.ts
- *      USER_GRANT_PRINCIPAL_KINDS): a person grants roles to people — the
- *      identity account — and to nothing else. A row whose principal is a
+ *      USER_GRANT_PRINCIPAL_KINDS): a person grants roles to people and to
+ *      teams of people, and to nothing else. A row whose principal is a
  *      resource is a structural link (the hierarchy walk's parent edge),
  *      which is `bootstrapPolicy`'s to write; through this lane it would
  *      let a right on one organization read another's members. Last, so
  *      every answer the cloud's create gives today is unchanged and only
- *      the row it should never have written is refused.
+ *      the row it should never have written is refused. A person names no
+ *      relation qualifier: `identity_account:<id>#<anything>` names
+ *      nobody, and OpenFGA would refuse the tuple after the row was
+ *      written, a grant on paper that is denied in practice.
+ *
+ * A TEAM principal takes its own list in place of arm 4: the kind's
+ * `team_grantable_roles` ∩ scope, never the person list, because a team
+ * is granted only what its members could each be granted and never
+ * ownership. It must name the team's members (`TEAM_MEMBERS_RELATION`).
+ * A kind that lists no team role refuses a team whatever the role, so
+ * open source (organization-only scope, and `organization` lists none)
+ * grants a team nothing without a branch of its own. Whether the team
+ * exists and belongs to the resource's organization needs a read, which
+ * this synchronous step does not make: that is the
+ * `iam-policy-create:pre-side-effect-gate` slot's, spliced after it.
  */
 import { create } from "@bufbuild/protobuf";
 import { Code, ConnectError } from "@connectrpc/connect";
 
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { IamPolicySchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
 import type { RevokeOrgAccessInputSchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/io_pb";
 import type {
@@ -51,15 +66,23 @@ import type {
 import { IamRole } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
 
 import type { PolicyGrantScope } from "../../extensions/policy-grant-scope.js";
-import { grantableRolesFor } from "../../pipeline/apiresource-meta.js";
+import {
+  grantableRolesFor,
+  kindEnumName,
+  teamGrantableRolesFor,
+} from "../../pipeline/apiresource-meta.js";
 import type { PipelineStep } from "../../pipeline/pipeline.js";
 import type { RequestContext } from "../../pipeline/request-context.js";
 import {
   PER_RESOURCE_GRANTS_UNIMPLEMENTED_MESSAGE,
-  USER_GRANT_PRINCIPAL_KINDS,
+  TEAM_MEMBERS_RELATION,
   noGrantableRolesMessage,
+  personQualifierMessage,
   principalNotGrantableMessage,
   roleNotGrantableMessage,
+  teamNotGrantableMessage,
+  teamQualifierMessage,
+  teamRoleNotGrantableMessage,
 } from "./constants.js";
 import type { IamPolicyGrantPath } from "./grant-path.js";
 import {
@@ -94,6 +117,17 @@ export function newValidateGrantableRoleStep(
           Code.Unimplemented,
         );
       }
+      const principal = spec.principal;
+      if (principal?.kind === TEAM_KIND_NAME) {
+        requireTeamGrant(
+          spec.relation,
+          principal.relation,
+          kind,
+          kindName,
+          scoped,
+        );
+        return;
+      }
       const grantable = contract.filter((role) => scoped.has(role));
       if (!grantable.some((role) => IamRole[role] === spec.relation)) {
         throw new ConnectError(
@@ -105,18 +139,66 @@ export function newValidateGrantableRoleStep(
           Code.InvalidArgument,
         );
       }
-      const principalKindName = spec.principal?.kind ?? "";
+      const principalKindName = principal?.kind ?? "";
       const principalKind = requireKnownPrincipalKind(principalKindName);
-      if (!USER_GRANT_PRINCIPAL_KINDS.includes(principalKind)) {
+      if (principalKind !== ApiResourceKind.identity_account) {
         throw new ConnectError(
           principalNotGrantableMessage(principalKindName),
           Code.InvalidArgument,
         );
       }
+      const qualifier = principal?.relation ?? "";
+      if (qualifier !== "") {
+        throw new ConnectError(
+          personQualifierMessage(qualifier),
+          Code.InvalidArgument,
+        );
+      }
     },
   };
 }
 
+/** The wire name of the team kind, as an `ApiResourceRef.kind` carries it. */
+const TEAM_KIND_NAME = kindEnumName(ApiResourceKind.team);
+
+/**
+ * The team arm of ValidateGrantableRole (the module header): the role
+ * against the kind's team list narrowed by the scope, then the qualifier.
+ */
+function requireTeamGrant(
+  role: string,
+  qualifier: string,
+  kind: ApiResourceKind,
+  kindName: string,
+  scoped: ReadonlySet<IamRole>,
+): void {
+  const teamGrantable = teamGrantableRolesFor(kind).filter((r) =>
+    scoped.has(r),
+  );
+  if (teamGrantable.length === 0) {
+    throw new ConnectError(
+      teamNotGrantableMessage(kindName),
+      Code.InvalidArgument,
+    );
+  }
+  if (!teamGrantable.some((r) => IamRole[r] === role)) {
+    throw new ConnectError(
+      teamRoleNotGrantableMessage(
+        role,
+        kindName,
+        teamGrantable.map((r) => IamRole[r]),
+      ),
+      Code.InvalidArgument,
+    );
+  }
+  if (qualifier !== TEAM_MEMBERS_RELATION) {
+    throw new ConnectError(
+      teamQualifierMessage(qualifier),
+      Code.InvalidArgument,
+    );
+  }
+}
+
 /** Grant the spec as the chain's caller; the row (fresh or held) is the result. */
 export function newGrantStep(
   grantPath: IamPolicyGrantPath,

package/src/domain/workflow/registry/data/task-kind-registry.json

@@ -1498,6 +1498,7 @@
                     "identity_provider",
                     "oauth_app",
                     "platform_client",
+                    "team",
                     "organization",
                     "platform",
                     "agent",

package/src/extensions/__tests__/iam-policy-points.test.ts

@@ -15,6 +15,9 @@
  *     contextual checkMyPermission refuse UNIMPLEMENTED with the edition
  *     reason (the domain suite pins the refusal; this file pins the
  *     registry);
+ *   - `drivers.principalDisplay` — how an access list names a grantee
+ *     that is not a person (a team); single instance; absent = the id
+ *     fallback shape;
  *   - `ResourceAuthorizationLifecycle` gains the OPTIONAL `onPolicyGranted`
  *     and `onPolicyRevoked` (Q7 i): a unit's lifecycle that carries them
  *     resolves through the existing single-instance point with both hooks
@@ -26,6 +29,7 @@ import { describe, expect, it } from "vitest";
 import type { IamPolicyStore } from "../../domain/iampolicy/store.js";
 import type { AuthorizationQueryEngine } from "../authorization-queries.js";
 import type { PolicyGrantScope } from "../policy-grant-scope.js";
+import type { PrincipalDisplay } from "../principal-display.js";
 import { resolveExtensions } from "../registry.js";
 import type { ResourceAuthorizationLifecycle } from "../resource-authorization.js";
 
@@ -125,6 +129,32 @@ describe("the authorizationQueries capability point", () => {
   });
 });
 
+describe("the principalDisplay driver point", () => {
+  const display: PrincipalDisplay = { resolve: unimplemented };
+
+  it("is undefined with no extensions — a non-person grantee renders by its id", () => {
+    expect(resolveExtensions([]).drivers.principalDisplay).toBeUndefined();
+  });
+
+  it("carries the one registered instance through", () => {
+    const resolved = resolveExtensions([
+      { name: "cloud-iam", drivers: { principalDisplay: display } },
+    ]);
+    expect(resolved.drivers.principalDisplay).toBe(display);
+  });
+
+  it("throws on a second registration, naming both units", () => {
+    expect(() =>
+      resolveExtensions([
+        { name: "display-a", drivers: { principalDisplay: display } },
+        { name: "display-b", drivers: { principalDisplay: display } },
+      ]),
+    ).toThrowError(
+      /extension 'display-b' registers a PrincipalDisplay, but 'display-a' already did/,
+    );
+  });
+});
+
 describe("the widened ResourceAuthorizationLifecycle contract", () => {
   const resourceHooks = {
     onResourceCreated: unimplemented,

package/src/extensions/__tests__/registry.test.ts

@@ -480,6 +480,9 @@ describe("resolveExtensions — loud-fail throws (DD-006 §2b)", () => {
       "agent-execution-create:pre-side-effect-gate",
       "agent-execution-recover:pre-side-effect-gate",
       "agent-execution-submit-approval:gate",
+      // The eighth: the IamPolicy create chain before the write, where an
+      // edition that serves teams refuses a team it cannot admit.
+      "iam-policy-create:pre-side-effect-gate",
       // 20260911.11 Q-IA-9: the seventh ratified slot — after the account
       // persists inside provisionMyAccount, before the reply (the cloud's
       // personal-organization ensure and backfill ride it).

package/src/extensions/drivers.ts

@@ -31,6 +31,9 @@
  *     port, which kinds an edition grants on, and the tuple-half query
  *     engine only an authorization backend can answer) — landed with
  *     20260913.01, gate ruling Q-OR-10
+ *   - principal display (how an access list names a grantee that is not
+ *     a person: a team, in the editions that serve teams) — landed with
+ *     the Team kind
  *   - outbound egress (which addresses the control plane may dial when
  *     it reaches a URL a user supplied: the MCP endpoint it probes at save
  *     time and the login server it reaches on Sign in) — landed with the
@@ -70,6 +73,7 @@ import type { OutboundEgressPolicy } from "./outbound-egress.js";
 import type { ListReadScope } from "./list-read-scope.js";
 import type { OrganizationDirectory } from "./organization-directory.js";
 import type { PolicyGrantScope } from "./policy-grant-scope.js";
+import type { PrincipalDisplay } from "./principal-display.js";
 import type { ResourceAuthorizationLifecycle } from "./resource-authorization.js";
 import type { ScheduleFireCallerMint } from "./schedule-fire-caller.js";
 
@@ -233,6 +237,14 @@ export interface ExtensionDrivers {
    * with the edition reason — the identityFederation absent shape.
    */
   readonly authorizationQueries?: AuthorizationQueryEngine;
+  /**
+   * The principal display (single-instance point): how an access list
+   * names a grantee that is not a person — a team, in the editions that
+   * serve teams (extensions/principal-display.ts carries the contract).
+   * When absent, such a grantee renders by its id, the fallback shape
+   * every access list has always had.
+   */
+  readonly principalDisplay?: PrincipalDisplay;
   /**
    * The license-status provider (single-instance point): what license
    * this server holds, answered by PlatformQueryController.getLicenseStatus

package/src/extensions/gate-slots.ts

@@ -34,6 +34,15 @@
  * Non-transactional in the `org-create:post-persist` sense: a gate
  * failure fails the request, the row survives, the next call heals.
  *
+ * The eighth, `iam-policy-create:pre-side-effect-gate`: the IamPolicy
+ * `create` chain (the user grant lane), after ValidateGrantableRole and
+ * before Grant, so nothing is written when a gate refuses. It exists for
+ * the checks a grant needs that take a read, which the synchronous grant
+ * scope may not make: the Enterprise and Cloud editions refuse a team
+ * that does not exist, a team of another organization than the granted
+ * resource, and a team member who is not one of the organization's
+ * viewers. Never on `bootstrapPolicy`, the platform's structural lane.
+ *
  * Two enforcement layers, deliberately redundant, both derived from the
  * ONE literal tuple below (lockstep by construction):
  *   - GateSlotName (compile time): the union of declared slot literals.
@@ -71,6 +80,7 @@ export const GATE_SLOT_NAMES = [
   "org-create:post-persist",
   "sandbox-acquisition:gate",
   "identity-account-provision:post-persist",
+  "iam-policy-create:pre-side-effect-gate",
 ] as const;
 
 /** The declared slot-name union — a registration outside it fails tsc. */

package/src/extensions/principal-display.ts

@@ -0,0 +1,37 @@
+/**
+ * The principal-display driver point: how an access list names a grantee
+ * that is not a person. Single instance, registered as
+ * `drivers.principalDisplay`.
+ *
+ * An access list ("who has access to this agent, with which roles") names
+ * every grantee. People are resolved by the core from the identity-account
+ * port (domain/iampolicy/display-resolver.ts), the same in every edition.
+ * A grantee of another kind — a team, in the Enterprise and Cloud editions
+ * — lives in a store only that edition holds, so its name comes from this
+ * point. Absent (open source, which grants to no team), such a grantee
+ * renders in the fallback shape the access list has always used: its kind,
+ * with its id standing in as its name.
+ *
+ * The contract:
+ *   - It answers for the ids it knows and omits the rest; an omitted id
+ *     takes the fallback shape, never an error (a team deleted between
+ *     the grant read and this call is an omission, not a fault).
+ *   - It is never asked about the identity account; the core owns people.
+ *   - A fault it cannot answer through THROWS (the ListReadScope rule:
+ *     an empty answer is a real answer, never an outage in disguise), and
+ *     the list RPC fails with it.
+ */
+import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { ApiResourceRefView } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/io_pb";
+
+/** The principal-display contract (single-instance point, ExtensionDrivers.principalDisplay). */
+export interface PrincipalDisplay {
+  /**
+   * Display views for the principals of `kind` with these ids, keyed by
+   * id; ids it does not know are absent from the map.
+   */
+  resolve(
+    kind: ApiResourceKind,
+    ids: ReadonlyArray<string>,
+  ): Promise<ReadonlyMap<string, ApiResourceRefView>>;
+}

package/src/extensions/registry.ts

@@ -60,6 +60,7 @@ import type { LicenseStatusProvider } from "./license-status.js";
 import type { OutboundEgressPolicy } from "./outbound-egress.js";
 import type { ListReadScope } from "./list-read-scope.js";
 import type { PolicyGrantScope } from "./policy-grant-scope.js";
+import type { PrincipalDisplay } from "./principal-display.js";
 import type { ModelCatalogProvider } from "../domain/workflow/registry/model-catalog-provider.js";
 import type { VisitorErrorPolicy } from "../pipeline/interceptors/error-boundary.js";
 import type { PipelineStep } from "../pipeline/pipeline.js";
@@ -288,6 +289,11 @@ export interface ResolvedExtensionDrivers {
    * tuple-half RPC arms refuse UNIMPLEMENTED with the edition reason.
    */
   readonly authorizationQueries: AuthorizationQueryEngine | undefined;
+  /**
+   * The principal display — undefined = an access list names a grantee
+   * that is not a person by its id (the fallback shape).
+   */
+  readonly principalDisplay: PrincipalDisplay | undefined;
   /**
    * The license-status provider — undefined = compose.ts installs the
    * built-in `absent` answer, so every edition serves getLicenseStatus.
@@ -367,6 +373,8 @@ export function resolveExtensions(
   let policyGrantScopeDeclaredBy: string | undefined;
   let authorizationQueries: AuthorizationQueryEngine | undefined;
   let authorizationQueriesDeclaredBy: string | undefined;
+  let principalDisplay: PrincipalDisplay | undefined;
+  let principalDisplayDeclaredBy: string | undefined;
   let licenseStatus: LicenseStatusProvider | undefined;
   let licenseStatusDeclaredBy: string | undefined;
   let outboundEgress: OutboundEgressPolicy | undefined;
@@ -568,6 +576,16 @@ export function resolveExtensions(
       authorizationQueriesDeclaredBy = unit.name;
     }
 
+    if (unit.drivers?.principalDisplay !== undefined) {
+      if (principalDisplayDeclaredBy !== undefined) {
+        throw new Error(
+          `extension '${unit.name}' registers a PrincipalDisplay, but '${principalDisplayDeclaredBy}' already did — exactly one may be composed`,
+        );
+      }
+      principalDisplay = unit.drivers.principalDisplay;
+      principalDisplayDeclaredBy = unit.name;
+    }
+
     if (unit.drivers?.licenseStatus !== undefined) {
       if (licenseStatusDeclaredBy !== undefined) {
         throw new Error(
@@ -748,6 +766,7 @@ export function resolveExtensions(
       iamPolicyStore,
       policyGrantScope,
       authorizationQueries,
+      principalDisplay,
       licenseStatus,
       outboundEgress,
       platformClientStore,

package/src/index.ts

@@ -164,6 +164,9 @@ export type {
 export { iamPolicyStoreContract } from "./domain/iampolicy/store-contract.js";
 export type { PolicyGrantScope } from "./extensions/policy-grant-scope.js";
 export type { AuthorizationQueryEngine } from "./extensions/authorization-queries.js";
+// How an access list names a grantee that is not a person
+// (drivers.principalDisplay): a team, in the editions that serve teams.
+export type { PrincipalDisplay } from "./extensions/principal-display.js";
 export type { IdentityFederation } from "./extensions/identity-federation.js";
 export type { AccountsBySubject } from "./domain/identityaccount/resolve.js";
 export { identityIdForSubject } from "./domain/identityaccount/resolve.js";
@@ -288,8 +291,14 @@ export { ScheduleFireCallerRefusedError } from "./extensions/schedule-fire-calle
 // through the REAL boundary mechanism, never a re-derivation.
 export type { VisitorErrorPolicy } from "./pipeline/interceptors/error-boundary.js";
 export { createErrorBoundaryInterceptor } from "./pipeline/interceptors/error-boundary.js";
+// The tuple lifecycle's resolution, for a kind a composition serves outside
+// the generic chains (a cloud-served create): `resolveResourceCreatedEvent`
+// derives the creation event from the kind's `kind_meta` exactly as the
+// shared CreateAuthorizationTuples step does, so the driver sees one shape
+// whichever chain created the row.
 export {
   diffVisibilityShapes,
+  resolveResourceCreatedEvent,
   visibilityShapesFor,
 } from "./pipeline/steps/authorization-tuples.js";
 
@@ -376,6 +385,23 @@ export { newValidateProtoStep } from "./pipeline/steps/validation.js";
 // same name over its own repo.
 export { newBuildNewStateStep } from "./pipeline/steps/defaults.js";
 export { newResolveSlugStep } from "./pipeline/steps/slug.js";
+// The update and reference-read steps for the same kinds, on the same
+// terms. An update runs BuildUpdateState after the composition's own
+// loader has stashed the stored row under EXISTING_RESOURCE_KEY, so which
+// fields a client may change, how status carries over and how the audit
+// slots are stamped stay the OSS step's. A read by reference runs
+// AuthorizeResolvedTarget with `loadedTargetAsMethod(get)` after the
+// loader has stashed the row under TARGET_RESOURCE_KEY, so the kind's
+// `get` annotation owns the permission and the refusal copy for both
+// reads. The loaders stay the composition's for CheckDuplicate's reason:
+// they read its own table.
+export { newBuildUpdateStateStep } from "./pipeline/steps/build-update-state.js";
+export { EXISTING_RESOURCE_KEY } from "./pipeline/steps/load-existing.js";
+export {
+  loadedTargetAsMethod,
+  newAuthorizeResolvedTargetStep,
+} from "./pipeline/steps/authorize-resolved-target.js";
+export { TARGET_RESOURCE_KEY } from "./pipeline/steps/load-target.js";
 
 // The driver interfaces and the store-fault classes the ratified mapping
 // keys on (typed not-found → NotFound; anything else rethrows as an

package/src/pipeline/apiresource-meta.ts

@@ -200,6 +200,27 @@ export function grantableRolesFor(
   return getOption(valueDesc, kind_meta).authorization?.grantableRoles ?? [];
 }
 
+/**
+ * The roles a TEAM may be granted on a resource of `kind` according to the
+ * contract — `kind_meta.authorization.team_grantable_roles`, a subset of
+ * `grantableRolesFor(kind)` (the subset is pinned by a test, never assumed
+ * here). Empty for every kind a team cannot be granted access to, and for
+ * `organization`, so an edition that grants only on organizations grants
+ * nothing to a team. Total, never a throw, for the same reason as
+ * `grantableRolesFor`.
+ */
+export function teamGrantableRolesFor(
+  kind: ApiResourceKind,
+): ReadonlyArray<IamRole> {
+  const valueDesc = kindValueDescriptor(kind);
+  if (valueDesc === undefined || !hasOption(valueDesc, kind_meta)) {
+    return [];
+  }
+  return (
+    getOption(valueDesc, kind_meta).authorization?.teamGrantableRoles ?? []
+  );
+}
+
 /**
  * Whether an edition serves a tier: the tier names the MINIMUM edition,
  * the editions are ordered oss < enterprise < cloud (each composes the