@stigmer/server 3.15.2 → 3.15.3-dev.20260914121148

package/src/extensions/drivers.ts

@@ -26,6 +26,11 @@
  *   - identity-account store + identity federation (the first domain
  *     whose persistence is a PORT, and the four federated RPC arms only
  *     one edition serves) — landed with 20260911.11, gate ruling Q-IA-9
+ *   - IamPolicy store + policy grant scope + authorization queries (the
+ *     IamPolicy domain's row half served in every edition; the store
+ *     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
  *
  * Merge rules (enforced by resolveExtensions, DD-006 §2b): the two
  * provider kinds are single-instance points — a second declaring unit is
@@ -40,14 +45,17 @@
 import type { ArtifactStorageDriverFactory } from "../artifactstorage/artifact-storage.js";
 import type { ChannelRuntime } from "../domain/agentchannel/channel-runtime.js";
 import type { IdentityAccountStore } from "../domain/identityaccount/store.js";
+import type { IamPolicyStore } from "../domain/iampolicy/store.js";
 import type { SecretCodec } from "../encryption/codec.js";
 import type { ModelCatalogProvider } from "../domain/workflow/registry/model-catalog-provider.js";
 import type { VisitorErrorPolicy } from "../pipeline/interceptors/error-boundary.js";
 import type { RunnerCredentialProvider } from "../runnerauth/runner-credential-provider.js";
 import type { SandboxProvisionerFactory } from "../sandbox/provisioner.js";
+import type { AuthorizationQueryEngine } from "./authorization-queries.js";
 import type { IdentityFederation } from "./identity-federation.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 { ResourceAuthorizationLifecycle } from "./resource-authorization.js";
 import type { ScheduleFireCallerMint } from "./schedule-fire-caller.js";
 
@@ -90,8 +98,13 @@ export interface ExtensionDrivers {
    * The resource-authorization lifecycle seam (C2, ruling Q2;
    * single-instance point). When composed, the three shared tuple steps
    * (CreateAuthorizationTuples / CleanupIamPolicies /
-   * UpdateVisibilityTuples) deliver resolved events to it; when absent,
-   * those steps no-op — OSS behavior byte-identical.
+   * UpdateVisibilityTuples) deliver resolved events to it, and the
+   * IamPolicy grant path delivers the two policy hooks. Corrected
+   * 2026-09-13 (20260913.01 Q-OR-6): when absent, the steps no-op, but
+   * open source is no longer record-less — the composition root installs
+   * the built-in role lifecycle (domain/iampolicy/role-lifecycle.ts, the
+   * entry's slice 4), which writes IamPolicy rows, whenever no extension
+   * registers an Authorizer (resource-authorization.ts header).
    */
   readonly resourceAuthorizationLifecycle?: ResourceAuthorizationLifecycle;
   /**
@@ -169,4 +182,38 @@ export interface ExtensionDrivers {
    * edition reason — the organizationDirectory absent-method shape.
    */
   readonly identityFederation?: IdentityFederation;
+  /**
+   * The IamPolicy store driver (20260913.01, Q-OR-10; single-instance
+   * point). The IamPolicy domain's persistence is a PORT like the
+   * identity-account domain's: when composed, every row the one grant
+   * path writes, deletes or reads — user grants, the structural
+   * bootstrap lanes, the access lists and counts — goes through this
+   * driver (the cloud serves the domain over its own `cloud.iam_policy`
+   * table this way, legacy random ids included). When absent, the OSS
+   * adapter over the generic Store installs at the compose.ts
+   * consumption site — OSS behavior byte-identical.
+   */
+  readonly iamPolicyStore?: IamPolicyStore;
+  /**
+   * The policy grant scope (20260913.01, Q-OR-3; single-instance point):
+   * which kinds a user may grant a role on in this edition, with which
+   * roles. Narrows the proto's `grantable_roles`, total over the enum,
+   * synchronous (policy-grant-scope.ts carries the reasons). When
+   * composed, ValidateGrantableRole and checkMyPermission's
+   * `can_grant_access` arm read it; when absent, open source's
+   * organization-only default installs at the compose.ts consumption
+   * site — the organization grants its four proto roles, nothing else
+   * grants anything.
+   */
+  readonly policyGrantScope?: PolicyGrantScope;
+  /**
+   * The authorization-query engine (20260913.01, Q-OR-8; single-instance
+   * point): the tuple-half questions — checkAuthorization, the two
+   * listAuthorized*Ids, a checkMyPermission with contextual policies —
+   * only an authorization backend can answer over its own graph. When
+   * composed, the IamPolicy query controller dispatches to it after its
+   * own trust checks; when absent, those RPC arms refuse UNIMPLEMENTED
+   * with the edition reason — the identityFederation absent shape.
+   */
+  readonly authorizationQueries?: AuthorizationQueryEngine;
 }

package/src/extensions/identity.ts

@@ -97,3 +97,24 @@ export interface IdentityVerifier {
    */
   verify(token: string): Promise<CallerIdentity | null>;
 }
+
+/**
+ * Whether `caller` is one of the platform's own pipelines — the admission
+ * rule of the RPCs a person must never reach directly, stated ONCE
+ * (20260911.11 A7 for the identity-account `create` RPC; 20260913.01
+ * Q-OR-7 and Q-S5-10 for the three IamPolicy system RPCs): a `machine`
+ * account (the platform's service accounts), the `internal` class (the
+ * server acting as itself over the in-process transport) or ANY identity
+ * that entered through that transport (a propagated user the server is
+ * composing a request for). A wire `user`, a `runner` and a composition's
+ * own classes are refused by the RPC that reads this — under the
+ * permissive Authorizer the annotation alone would admit anyone, so the
+ * rule is load-bearing in open source.
+ */
+export function isPlatformPipelineCaller(caller: CallerIdentity): boolean {
+  return (
+    caller.callerClass === "machine" ||
+    caller.callerClass === "internal" ||
+    caller.origin === "in-process"
+  );
+}

package/src/extensions/list-read-scope.ts

@@ -71,21 +71,61 @@
  *     untouched with the org unconsulted (the first line above). Two lanes
  *     have no org on the wire (`session.list`, `apiKey.findAll`) and offer
  *     the kind until P1 entry 12 pages them.
+ *   - A KIND WHOSE AUTHORIZATION IS ITS PARENT'S CARRIES THAT PARENT ON
+ *     EVERY CANDIDATE (stigmer-cloud 20260913.04 T04, Q-LB-33..36). When
+ *     `kind_meta` declares PARENT scope with INHERITED owner
+ *     (`inheritedAuthorizationParentOf`; today agent_execution → session),
+ *     the helper fills `ListEntryMeta.authorizationParent` from the row's
+ *     spec through the same read the tuple lifecycle wrote the parent link
+ *     with. A driver MAY answer the parent's question in place of the
+ *     child's: by the model's construction the two answers are identical
+ *     (the child's `owner`, `viewer` and `can_view` are all `from` the
+ *     parent), and the parent's resolution is direct tuples where the
+ *     child's walks the parent's whole set (OpenFGA's learned `weight2`
+ *     strategy read the founder's 423 sessions per execution; that is what
+ *     rolled back twice on 2026-09-14). A driver that ignores the field is
+ *     still correct. The one observable difference is stated, not hidden:
+ *     a row whose parent tuple never landed (the create chain's "row
+ *     survives, tuple write failed" state, healed by retry) is hidden by
+ *     the child's check and shown by the parent's — the row's truth, read
+ *     from the field the tuple was derived from, and no widening: nobody
+ *     reaches a parent through it who could not create the row in it.
  */
 import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 
+// The first VALUE imports from extensions/ into pipeline/ (every other
+// crossing is a type): two pure leaf modules that import nothing but
+// protos, so there is no cycle. Deliberate — one resolver for the tuple
+// writer and the list reader beats a copy in the seam.
+import {
+  getKindEnum,
+  inheritedAuthorizationParentOf,
+} from "../pipeline/apiresource-meta.js";
+import { parentIdOf } from "../pipeline/steps/shapes.js";
+
 import type { CallerIdentity } from "./identity.js";
+import type { ResolvedParentLink } from "./resource-authorization.js";
 
 /**
  * The candidate metadata a post-scan lane offers the scope — the three
  * fields the cloud driver's rules key on (id for the FGA intersection,
  * labels for the guest cookie rule; org rides along for symmetry with
- * the consumer-owned intersection, so a driver can log or assert on it).
+ * the consumer-owned intersection, so a driver can log or assert on it),
+ * plus the parent for kinds whose authorization is their parent's.
  */
 export interface ListEntryMeta {
   readonly id: string;
   readonly org: string;
   readonly labels: Readonly<Record<string, string>>;
+  /**
+   * OPTIONAL (added 20260913.04 T04): the parent this row's authorization
+   * IS — present only for a kind whose `kind_meta` is PARENT scope with
+   * INHERITED owner (the header's last contract line), the same
+   * `ResolvedParentLink` the tuple lifecycle wrote for the row. Absent for
+   * every other kind, and absent when the row's spec does not name its
+   * parent — a driver then asks about the row itself, never drops it.
+   */
+  readonly authorizationParent?: ResolvedParentLink;
 }
 
 /** The scope contract (single-instance point, ExtensionDrivers.listReadScope). */
@@ -117,7 +157,10 @@ export interface ListReadScope {
 
 /**
  * The shape every stored API resource message presents to the shared
- * helper — the metadata fields the scope's candidates are built from.
+ * helper — the metadata fields the scope's candidates are built from, and
+ * the spec the parent is read from (structurally, by `kind_meta`'s
+ * `spec_field`; typed loosely because the field differs per kind and the
+ * read is `parentIdOf`'s).
  */
 export interface ScopedListResource {
   metadata?: {
@@ -125,6 +168,7 @@ export interface ScopedListResource {
     org?: string;
     labels?: Record<string, string>;
   };
+  spec?: object;
 }
 
 /**
@@ -141,8 +185,11 @@ export interface ScopedListResource {
  *     permission-bounded across orgs, verified per lane in the entry's
  *     census — lanes Java does not org-narrow pass ""), then to the kept
  *     ids. The same set either way (both are per-row predicates); the
- *     order is the header's last contract line: the scope sees the org's
- *     rows, not the kind's.
+ *     order is the header's second-to-last contract line: the scope sees
+ *     the org's rows, not the kind's;
+ *   - the candidates of a kind whose authorization is its parent's carry
+ *     `authorizationParent` (the header's last line), resolved once per
+ *     call from `kind_meta` and once per row from the spec.
  */
 export async function restrictListByReadScope<T extends ScopedListResource>(
   scope: ListReadScope | undefined,
@@ -158,11 +205,42 @@ export async function restrictListByReadScope<T extends ScopedListResource>(
     requestOrg === ""
       ? resources
       : resources.filter((resource) => resource.metadata?.org === requestOrg);
-  const entries: ListEntryMeta[] = offered.map((resource) => ({
-    id: resource.metadata?.id ?? "",
-    org: resource.metadata?.org ?? "",
-    labels: resource.metadata?.labels ?? {},
-  }));
+  const parentOf = authorizationParentReader(kind);
+  const entries: ListEntryMeta[] = offered.map((resource) => {
+    const entry: ListEntryMeta = {
+      id: resource.metadata?.id ?? "",
+      org: resource.metadata?.org ?? "",
+      labels: resource.metadata?.labels ?? {},
+    };
+    const authorizationParent = parentOf(resource);
+    return authorizationParent === undefined
+      ? entry
+      : { ...entry, authorizationParent };
+  });
   const keptIds = await scope.restrictListEntries(caller, kind, entries);
   return offered.filter((resource) => keptIds.has(resource.metadata?.id ?? ""));
 }
+
+/**
+ * The per-row parent reader for `kind`: a constant `undefined` for the 27
+ * kinds whose authorization is their own, and for the kind whose
+ * authorization is its parent's, the `ResolvedParentLink` the tuple
+ * lifecycle wrote — or undefined for a row whose spec does not name it
+ * (never a throw: a list is not a create). `kind_meta` is consulted once
+ * per call, not once per row.
+ */
+function authorizationParentReader(
+  kind: ApiResourceKind,
+): (resource: ScopedListResource) => ResolvedParentLink | undefined {
+  const parent = inheritedAuthorizationParentOf(kind);
+  if (parent === undefined) {
+    return () => undefined;
+  }
+  const parentKind = getKindEnum(parent.kind);
+  return (resource) => {
+    const parentId = parentIdOf(resource, parent.specField);
+    return parentId === ""
+      ? undefined
+      : { relation: parent.relation, parentKind, parentId };
+  };
+}

package/src/extensions/policy-grant-scope.ts

@@ -0,0 +1,50 @@
+/**
+ * The policy-grant-scope driver point (20260913.01; the P1 gate's Q7 iii,
+ * T01_1_review.md Q-OR-3): WHICH kinds a user may grant a role on in this
+ * edition, and with which roles. Single instance, registered as
+ * `drivers.policyGrantScope` (the identityFederation shape: a driver point
+ * whose absence is open source's own behaviour). Absent, the composition
+ * root installs `newOrganizationOnlyGrantScope()`
+ * (domain/iampolicy/grant-scope.ts): the organization grants the roles its
+ * `kind_meta` lists — owner, admin, member, viewer (Q-OR-4) — and no other
+ * kind grants anything. Per-resource grants (a viewer on one agent) are
+ * what the Enterprise and Cloud editions add by registering a wider scope;
+ * the cloud registers every kind's `kind_meta` roles.
+ *
+ * Who reads it: the IamPolicy command controller's ValidateGrantableRole on
+ * `create` — AFTER the proto (`grantableRolesFor` in
+ * pipeline/apiresource-meta.ts, the source of "what can be granted at
+ * all"; a kind that lists no roles is system-managed in every edition and
+ * refused before the scope is asked) and never on `bootstrapPolicy`, the
+ * structural lane — and `checkMyPermission`'s second arm, which answers
+ * `can_grant_access` false for a kind outside the scope so the console's
+ * existing PermissionGate hides grant controls without a new SDK surface
+ * (Q-OR-5).
+ *
+ * The contract every scope is held to (Q-S3-3, 2026-09-13):
+ *
+ *   - It NARROWS the proto, never widens it. A scope's answer for a kind is
+ *     read as a subset of `kind_meta.authorization.grantable_roles`;
+ *     ValidateGrantableRole intersects the two, so a driver cannot admit a
+ *     role the contract does not list by accident.
+ *   - It is TOTAL over ApiResourceKind, the unknown kind included: a kind
+ *     it does not admit answers the empty list, never a throw.
+ *     checkMyPermission asks about a kind that came off the wire and was
+ *     resolved by `kindByEnumName`, which yields the unknown kind rather
+ *     than failing (apiresource-meta.ts header).
+ *   - It is SYNCHRONOUS: an edition's grant scope is a fact about the
+ *     edition, a proto read at most, never I/O. A scope that would need a
+ *     network to answer is a different seam.
+ */
+import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { IamRole } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+
+/** The grant-scope contract (single-instance point, ExtensionDrivers.policyGrantScope). */
+export interface PolicyGrantScope {
+  /**
+   * The roles a user may grant on a resource of `kind` in this edition — a
+   * subset of the kind's proto `grantable_roles`; empty when the edition
+   * grants nothing on the kind (or the kind is unknown). Never throws.
+   */
+  grantableRoles(kind: ApiResourceKind): ReadonlyArray<IamRole>;
+}

package/src/extensions/registry.ts

@@ -34,7 +34,10 @@
  * points (20260911.11) at the identity-accounts stage (the store driver,
  * ahead of the boot-time operator ensure) and the routes stage (the
  * federation capability and the provision slot's steps, into the
- * identity-account controller).
+ * identity-account controller); the IamPolicy points (20260913.01) at
+ * the same two stages — the store driver where the grant path is built,
+ * beside the identity-account store, and the grant scope and the query
+ * engine into the IamPolicy controller at the routes stage.
  */
 import type { DescMessage } from "@bufbuild/protobuf";
 import type { ConnectRouter } from "@connectrpc/connect";
@@ -45,10 +48,13 @@ import type { ArtifactStorageDriverFactory } from "../artifactstorage/artifact-s
 import { BUILT_IN_STORAGE_TYPES } from "../artifactstorage/artifact-storage.js";
 import type { ChannelRuntime } from "../domain/agentchannel/channel-runtime.js";
 import type { IdentityAccountStore } from "../domain/identityaccount/store.js";
+import type { IamPolicyStore } from "../domain/iampolicy/store.js";
 import type { SecretCodec } from "../encryption/codec.js";
 import { V1_VERSION } from "../encryption/v1-codec.js";
+import type { AuthorizationQueryEngine } from "./authorization-queries.js";
 import type { IdentityFederation } from "./identity-federation.js";
 import type { ListReadScope } from "./list-read-scope.js";
+import type { PolicyGrantScope } from "./policy-grant-scope.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";
@@ -250,6 +256,22 @@ export interface ResolvedExtensionDrivers {
    * four federated RPCs refuse UNIMPLEMENTED with the edition reason.
    */
   readonly identityFederation: IdentityFederation | undefined;
+  /**
+   * The 20260913.01 IamPolicy store driver — undefined = the compose.ts
+   * stage that builds the grant path installs the OSS adapter over the
+   * generic Store, OSS behavior byte-identical.
+   */
+  readonly iamPolicyStore: IamPolicyStore | undefined;
+  /**
+   * The 20260913.01 policy grant scope — undefined = compose.ts installs
+   * open source's organization-only default.
+   */
+  readonly policyGrantScope: PolicyGrantScope | undefined;
+  /**
+   * The 20260913.01 authorization-query engine — undefined = the
+   * tuple-half RPC arms refuse UNIMPLEMENTED with the edition reason.
+   */
+  readonly authorizationQueries: AuthorizationQueryEngine | undefined;
 }
 
 /**
@@ -297,6 +319,12 @@ export function resolveExtensions(
   let identityAccountStoreDeclaredBy: string | undefined;
   let identityFederation: IdentityFederation | undefined;
   let identityFederationDeclaredBy: string | undefined;
+  let iamPolicyStore: IamPolicyStore | undefined;
+  let iamPolicyStoreDeclaredBy: string | undefined;
+  let policyGrantScope: PolicyGrantScope | undefined;
+  let policyGrantScopeDeclaredBy: string | undefined;
+  let authorizationQueries: AuthorizationQueryEngine | undefined;
+  let authorizationQueriesDeclaredBy: string | undefined;
   const artifactStorageDrivers = new Map<
     string,
     ArtifactStorageDriverFactory
@@ -458,6 +486,36 @@ export function resolveExtensions(
       identityFederationDeclaredBy = unit.name;
     }
 
+    if (unit.drivers?.iamPolicyStore !== undefined) {
+      if (iamPolicyStoreDeclaredBy !== undefined) {
+        throw new Error(
+          `extension '${unit.name}' registers an IamPolicyStore, but '${iamPolicyStoreDeclaredBy}' already did — exactly one may be composed`,
+        );
+      }
+      iamPolicyStore = unit.drivers.iamPolicyStore;
+      iamPolicyStoreDeclaredBy = unit.name;
+    }
+
+    if (unit.drivers?.policyGrantScope !== undefined) {
+      if (policyGrantScopeDeclaredBy !== undefined) {
+        throw new Error(
+          `extension '${unit.name}' registers a PolicyGrantScope, but '${policyGrantScopeDeclaredBy}' already did — exactly one may be composed`,
+        );
+      }
+      policyGrantScope = unit.drivers.policyGrantScope;
+      policyGrantScopeDeclaredBy = unit.name;
+    }
+
+    if (unit.drivers?.authorizationQueries !== undefined) {
+      if (authorizationQueriesDeclaredBy !== undefined) {
+        throw new Error(
+          `extension '${unit.name}' registers an AuthorizationQueryEngine, but '${authorizationQueriesDeclaredBy}' already did — exactly one may be composed`,
+        );
+      }
+      authorizationQueries = unit.drivers.authorizationQueries;
+      authorizationQueriesDeclaredBy = unit.name;
+    }
+
     if (unit.drivers?.artifactStorageDrivers !== undefined) {
       for (const [name, factory] of unit.drivers.artifactStorageDrivers) {
         if ((BUILT_IN_STORAGE_TYPES as ReadonlyArray<string>).includes(name)) {
@@ -580,6 +638,9 @@ export function resolveExtensions(
       scheduleFireCaller,
       identityAccountStore,
       identityFederation,
+      iamPolicyStore,
+      policyGrantScope,
+      authorizationQueries,
     },
     services,
     workers,

package/src/extensions/resource-authorization.ts

@@ -26,9 +26,37 @@
  *   - onVisibilityChanged: SYNCHRONOUS, post-persist; a throw fails the
  *     request (metadata may be persisted with tuples lagging — retrying
  *     the same transition converges, the set-diff is idempotent).
+ *
+ * Corrected 2026-09-13 (20260913.01, T01_1_review.md Q-OR-6, Q-OR-10):
+ * "no driver composed = OSS behavior byte-identical" described the seam
+ * while the only writer of authorization records was the cloud's tuple
+ * driver. The seam now records authorization at lifecycle points in EVERY
+ * edition: open source's built-in role lifecycle
+ * (domain/iampolicy/role-lifecycle.ts, the entry's slice 4) writes
+ * IamPolicy rows (the organization creator's `owner` row; cleanup on
+ * delete), and a composed driver writes tuples too. The two POLICY hooks below are the
+ * other direction of the same seam — the IamPolicy domain's one grant and
+ * revoke path (domain/iampolicy/grant-path.ts) telling the driver that a
+ * row was written or is about to be deleted, so a composition can mirror
+ * the row as a tuple. Their order is the cloud#425 invariant, fixed by the
+ * path and stated on each event:
+ *   - onPolicyGranted: SYNCHRONOUS, AFTER the row is persisted; fires on
+ *     the duplicate arm too (the inline heal for a row whose tuple never
+ *     landed). A throw fails the request with the row in place — the
+ *     caller's retry or a boot backfill heals it.
+ *   - onPolicyRevoked: SYNCHRONOUS, BEFORE the row is deleted. A throw
+ *     leaves row and tuple, so a retry converges; the reverse order was
+ *     the fail-open incident class ("revoke" silently becoming "keep").
+ *     On the absent arm (no row for the spec) it fires with the spec and
+ *     no policy, so a composition can still delete a bare tuple written
+ *     before the row mirror existed.
+ * Absent method = no mirror is written (the OSS posture: rows are the
+ * record).
  */
 import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import type { OwnerAttributionType } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/authorization_config_pb";
+import type { IamPolicy } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
+import type { IamPolicySpec } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
 
 import type { CallerIdentity } from "./identity.js";
 
@@ -125,6 +153,31 @@ export interface DefaultInstanceLinkedEvent {
   readonly blueprintId: string;
 }
 
+/**
+ * Fired synchronously AFTER an IamPolicy row is persisted by the domain's
+ * grant path — and on the duplicate arm, when the triple was already held
+ * and no row was written, so a composition heals a row whose tuple never
+ * landed (cloud#425's inline heal). `policy` is the row as stored: on the
+ * duplicate arm the FIRST writer's row, whose id may be a legacy random
+ * one on a composition that predates derived ids.
+ */
+export interface PolicyGrantedEvent {
+  readonly policy: IamPolicy;
+  /** True when the triple was already held and this grant wrote nothing. */
+  readonly duplicate: boolean;
+}
+
+/**
+ * Fired synchronously BEFORE an IamPolicy row is deleted by the domain's
+ * grant path. `spec` is always the triple being revoked; `policy` is the
+ * row found for it, or `undefined` on the absent arm — the spec alone is
+ * enough to name the tuple a composition still deletes then.
+ */
+export interface PolicyRevokedEvent {
+  readonly spec: IamPolicySpec;
+  readonly policy: IamPolicy | undefined;
+}
+
 /**
  * The driver interface (single-instance point, registered via
  * ExtensionDrivers.resourceAuthorizationLifecycle). Implementations must
@@ -142,4 +195,16 @@ export interface ResourceAuthorizationLifecycle {
    * (the OSS posture: local access control needs none).
    */
   onDefaultInstanceLinked?(event: DefaultInstanceLinkedEvent): Promise<void>;
+  /**
+   * OPTIONAL (added 20260913.01 slice 2): synchronous, AFTER the row
+   * persist, on the duplicate arm too; a throw fails the grant with the
+   * row in place. Absent method = rows are the record (the OSS posture).
+   */
+  onPolicyGranted?(event: PolicyGrantedEvent): Promise<void>;
+  /**
+   * OPTIONAL (added 20260913.01 slice 2): synchronous, BEFORE the row
+   * delete; a throw leaves row and tuple for the retry. Absent method =
+   * rows are the record (the OSS posture).
+   */
+  onPolicyRevoked?(event: PolicyRevokedEvent): Promise<void>;
 }

package/src/index.ts

@@ -100,6 +100,8 @@ export type { ResolvedExtensionDrivers } from "./extensions/registry.js";
 // tests pin against.
 export type {
   DefaultInstanceLinkedEvent,
+  PolicyGrantedEvent,
+  PolicyRevokedEvent,
   ResourceAuthorizationLifecycle,
   ResourceCreatedEvent,
   ResourceDeletedEvent,
@@ -125,6 +127,24 @@ export type {
   IdentityAccountStoreContractFixture,
 } from "./domain/identityaccount/store-contract.js";
 export { identityAccountStoreContract } from "./domain/identityaccount/store-contract.js";
+// The 20260913.01 IamPolicy seams (Q-OR-1, Q-OR-10): the store PORT a
+// composition drives the domain's grant path through (drivers.iamPolicyStore;
+// a driver throws DuplicatePolicyError for a held id) and its vitest-free
+// contract kit; the grant scope (drivers.policyGrantScope — which kinds an
+// edition grants on, with which roles; open source's default is the
+// organization alone); and the tuple-half query engine
+// (drivers.authorizationQueries — the three graph questions only an
+// authorization backend answers). The grant path itself is NOT exported: a
+// composition reaches it as in-process RPCs, the doctrine.
+export type { IamPolicyStore } from "./domain/iampolicy/store.js";
+export { DuplicatePolicyError } from "./domain/iampolicy/store.js";
+export type {
+  IamPolicyStoreContractCase,
+  IamPolicyStoreContractFixture,
+} from "./domain/iampolicy/store-contract.js";
+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";
 export type { IdentityFederation } from "./extensions/identity-federation.js";
 export type { AccountsBySubject } from "./domain/identityaccount/resolve.js";
 export { identityIdForSubject } from "./domain/identityaccount/resolve.js";

package/src/pipeline/__tests__/grantable-roles-for.test.ts

@@ -0,0 +1,87 @@
+/**
+ * Pins `grantableRolesFor` (pipeline/apiresource-meta.ts), the one read of
+ * a kind's `kind_meta.authorization.grantable_roles` — what the IamPolicy
+ * domain's ValidateGrantableRole consults FIRST (20260913.01, Q-OR-3 as
+ * refined: the proto says what can be granted at all; the composed
+ * PolicyGrantScope only narrows by edition) and what open source's
+ * organization-only scope reads for the organization.
+ *
+ * Three properties are load-bearing and pinned here rather than assumed:
+ *
+ *   - The ORGANIZATION lists exactly owner, admin, member, viewer, in the
+ *     proto's order. This is the Q-OR-4 ruling made a test: the four roles
+ *     every edition grants on an organization are the proto's, not a list
+ *     in code, so a change to `api_resource_kind.proto` fails here and
+ *     someone reads the ruling before the console shows a fifth word.
+ *   - The five system-managed kinds list NO roles. ValidateGrantableRole's
+ *     first arm refuses a grant on them with the cloud's byte-pinned
+ *     INVALID_ARGUMENT in every edition; this is the data that arm reads.
+ *   - TOTAL, never a throw. The reader is asked about the SECOND kind
+ *     vocabulary — an `ApiResourceRef.kind` resolved through
+ *     `kindByEnumName`, which yields the unknown kind for anything it does
+ *     not recognise and never throws (the module header). The unknown kind
+ *     is the one enum member without `kind_meta`; it answers the empty
+ *     list, as the cloud's `grantableRolesFor` (iam/policy/roles.ts) did.
+ */
+import { getOption, hasOption } from "@bufbuild/protobuf";
+import { describe, expect, it } from "vitest";
+
+import {
+  ApiResourceKind,
+  ApiResourceKindSchema,
+  kind_meta,
+} from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { IamRole } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+
+import { grantableRolesFor } from "../apiresource-meta.js";
+
+describe("grantableRolesFor — the proto's grantable roles per kind", () => {
+  it("the organization grants exactly owner, admin, member, viewer, in proto order (Q-OR-4)", () => {
+    expect(grantableRolesFor(ApiResourceKind.organization)).toEqual([
+      IamRole.owner,
+      IamRole.admin,
+      IamRole.member,
+      IamRole.viewer,
+    ]);
+  });
+
+  it("a blueprint kind answers the descriptor's own list, not a copy", () => {
+    const agentValue = ApiResourceKindSchema.values.find(
+      (value) => value.number === ApiResourceKind.agent,
+    );
+    expect(agentValue).toBeDefined();
+    const fromDescriptor =
+      getOption(agentValue!, kind_meta).authorization?.grantableRoles ?? [];
+    expect(fromDescriptor.length).toBeGreaterThan(0);
+    expect(grantableRolesFor(ApiResourceKind.agent)).toEqual(fromDescriptor);
+  });
+
+  it.each([
+    ["identity_account", ApiResourceKind.identity_account],
+    ["api_key", ApiResourceKind.api_key],
+    ["iam_policy", ApiResourceKind.iam_policy],
+    ["invitation", ApiResourceKind.invitation],
+    ["agent_execution", ApiResourceKind.agent_execution],
+  ])(
+    "%s is system-managed: no grantable roles (Q-OR-3 arm 1)",
+    (_name, kind) => {
+      expect(grantableRolesFor(kind)).toEqual([]);
+    },
+  );
+
+  it("the unknown kind answers the empty list and never throws (the second vocabulary's doctrine)", () => {
+    expect(
+      grantableRolesFor(ApiResourceKind.api_resource_kind_unknown),
+    ).toEqual([]);
+  });
+
+  it("is total over the descriptor: every member answers an array", () => {
+    for (const value of ApiResourceKindSchema.values) {
+      const roles = grantableRolesFor(value.number as ApiResourceKind);
+      expect(Array.isArray(roles), value.name).toBe(true);
+      if (!hasOption(value, kind_meta)) {
+        expect(roles, `${value.name} carries no kind_meta`).toEqual([]);
+      }
+    }
+  });
+});