@stigmer/server 3.15.2-dev.20260913223433 → 3.15.3-dev.20260914100347

package/src/domain/iampolicy/membership.ts

@@ -0,0 +1,298 @@
+/**
+ * The open-source membership rules (20260913.01, T01_0_plan.md §3a;
+ * T01_1_review.md Q-OR-6b, Q-OR-6c; slice 4 rulings Q-S4-2 to Q-S4-7):
+ * how organization roles come to exist on a self-host that has no
+ * administrator to grant them. Core code, installed only under the
+ * built-in authorization posture (boot/compose.ts `builtInAuthorization`:
+ * no unit registered an Authorizer); a composition with its own
+ * Authorizer has its own onboarding and never constructs this.
+ *
+ * Two moments:
+ *
+ *   onAccountCreated(account, caller) — a person's FIRST provisioning, and
+ *   only that (the identity-account domain's AccountCreatedHook, run by
+ *   provisionMyAccount on the call whose `created` is true). For every
+ *   organization the account holds no row on, in this order:
+ *     1. `owner`  — the organization's creator stamp is this account (its
+ *                   subject or its id): the founder, who founded it
+ *                   idp-shaped before any row existed;
+ *     2. `admin`  — this account created a blueprint in it (BLUEPRINT_KINDS,
+ *                   constants.ts: the kinds an admin authors; sessions and
+ *                   executions are personal and confer nothing, DD-002
+ *                   rule 2);
+ *     3. `admin`  — the account's email is the configured operator email
+ *                   (an empty configuration matches nobody);
+ *     4. `admin`  — the organization has ZERO role rows and no PERSON other
+ *                   than this account created it or any blueprint in it:
+ *                   the fresh install's first caller, and the
+ *                   trusted-local-turned-OIDC laptop whose stamps are all
+ *                   "system". "Zero rows", never "no admin now" — revoking
+ *                   every admin of a bootstrapped organization must not
+ *                   hand it to the next stranger (plan finding 2); and the
+ *                   founder's own stamp counts as a person (Q-S4-7), so a
+ *                   revoked founder's empty organization is not handed
+ *                   over either;
+ *     5. `member` — everyone else.
+ *   Arms 3 and 4 both answer `admin`; 3 is checked first because it is a
+ *   string compare and 4 reads the organization's rows. `user`-class
+ *   callers only (Q-OR-6b): a runner, a machine or the in-process class
+ *   never earns a role. Nothing on an organization the account already
+ *   holds a row on, so a run that faulted midway converges on the next.
+ *
+ *   ensureOperatorOwnership(operator) — the trusted-local boot ensure
+ *   (Q-OR-6c): the laptop's operator becomes `owner` of every organization
+ *   that has NO owner row. "No owner row", not "no row of this operator"
+ *   (Q-S4-3): a boot-time write never overrides a human grant recorded
+ *   under an earlier OIDC life of the same database, and the permissive
+ *   Authorizer admits the operator regardless. A second boot writes
+ *   nothing. The row is granted AS the operator — the trusted-local
+ *   identity shape (empty issuer and token) carrying the account's id,
+ *   email and name — so its audit actor reads like every other write on
+ *   that laptop.
+ *
+ * What a creator stamp is. The rules read `status.audit.spec_audit
+ * .created_by.id` off organizations and blueprints. That stamp is the
+ * caller's identityId at the time: a provisioned caller's ACCOUNT id, an
+ * unprovisioned caller's raw issuer SUBJECT, and — under the trusted-local
+ * posture — the operator's EMAIL or the "system" placeholder
+ * (pipeline/interceptors/auth.ts trustedLocalIdentityFor). So "mine" is
+ * "equals my subject or my id" (an email stamp is nobody's by this rule;
+ * the operator is covered by arm 3 and by ensureOperatorOwnership), and a
+ * stamp is a PERSON when it is non-empty and not the "system" placeholder
+ * (SYSTEM_OPERATOR_IDENTITY_ID, the one home of that word — Q-S4-6). The
+ * rules classify stamps by shape and consult no account store (Q-S4-5).
+ *
+ * Reads. Policy rows through the IamPolicyStore PORT (`policies`, the
+ * same instance the grant path writes through) — never around it
+ * (Q-S4-5). Organizations and blueprints through the generic Store,
+ * decoded with each kind's own schema (CREATOR_SCAN_SCHEMAS; Q-S4-2: the
+ * envelope shares its field numbers but each status carries its audit
+ * under its own, so no generic decode exists). Cost, measured in the
+ * entry's execution record: one scan of each of seven kinds and one row
+ * read per organization, once per account creation.
+ *
+ * The window this design accepts (Q-S4-4). A store fault after the
+ * account row persisted fails the request INTERNAL (the controller's
+ * mapping) with the account in place; later calls answer `created:
+ * false`, so the rules never run again for that person. The writes ride
+ * the idempotent grant path, so a partial run leaves only correct rows,
+ * and the recovery is an administrator's grant — or, on a fresh install,
+ * arm 3 at the operator's own sign-in. An account created through the
+ * `create` RPC (the platform's own pipelines, cloud#393) never reaches
+ * this hook either: the rules are about a person signing in.
+ */
+import type { DescMessage } from "@bufbuild/protobuf";
+import { fromBinary } from "@bufbuild/protobuf";
+
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { EnvironmentSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { ScheduleSchema } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/api_pb";
+import { SkillSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { IdentityAccount } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
+import { IamRole } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+import { OrganizationSchema } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
+
+import type { CallerIdentity } from "../../extensions/identity.js";
+import { kindEnumName } from "../../pipeline/apiresource-meta.js";
+import { SYSTEM_OPERATOR_IDENTITY_ID } from "../../pipeline/interceptors/auth.js";
+import { auditOf } from "../../pipeline/steps/defaults.js";
+import { metadataOf } from "../../pipeline/steps/shapes.js";
+import type { Store } from "../../store/interface.js";
+import type { AccountCreatedHook } from "../identityaccount/provisioning.js";
+import { BLUEPRINT_KINDS } from "./constants.js";
+import type { IamPolicyGrantPath } from "./grant-path.js";
+import { organizationRole, relationOf } from "./specs.js";
+import type { IamPolicyStore } from "./store.js";
+
+export interface MembershipRulesDeps {
+  readonly grantPath: IamPolicyGrantPath;
+  /** The port the grant path writes through — read here for "holds a row", "zero rows", "has an owner". */
+  readonly policies: IamPolicyStore;
+  readonly store: Store;
+  /** STIGMER_OPERATOR_EMAIL as the operator seam holds it; "" when unconfigured. */
+  readonly operatorEmail: string;
+}
+
+export interface MembershipRules extends AccountCreatedHook {
+  /** The trusted-local boot ensure: `owner` wherever no owner row exists. */
+  ensureOperatorOwnership(operator: IdentityAccount): Promise<void>;
+}
+
+/**
+ * The schemas the creator scan decodes with: the organization and every
+ * BLUEPRINT_KINDS member. Pinned equal to that set by the domain's tests,
+ * so a kind added to the constant without a schema fails loudly instead
+ * of being skipped.
+ */
+export const CREATOR_SCAN_SCHEMAS: ReadonlyMap<ApiResourceKind, DescMessage> =
+  new Map<ApiResourceKind, DescMessage>([
+    [ApiResourceKind.organization, OrganizationSchema],
+    [ApiResourceKind.agent, AgentSchema],
+    [ApiResourceKind.workflow, WorkflowSchema],
+    [ApiResourceKind.skill, SkillSchema],
+    [ApiResourceKind.mcp_server, McpServerSchema],
+    [ApiResourceKind.environment, EnvironmentSchema],
+    [ApiResourceKind.schedule, ScheduleSchema],
+  ]);
+
+const ORGANIZATION = kindEnumName(ApiResourceKind.organization);
+const IDENTITY_ACCOUNT = kindEnumName(ApiResourceKind.identity_account);
+
+/** What the scan keeps of a resource: its id, its organization (blueprints), its creator stamp. */
+interface ScannedResource {
+  readonly id: string;
+  readonly org: string;
+  readonly createdBy: string;
+}
+
+/** A creator stamp that names a person: non-empty and not the unconfigured laptop's placeholder. */
+function isPersonStamp(stamp: string): boolean {
+  return stamp !== "" && stamp !== SYSTEM_OPERATOR_IDENTITY_ID;
+}
+
+export function newMembershipRules(deps: MembershipRulesDeps): MembershipRules {
+  const { grantPath, policies, store, operatorEmail } = deps;
+
+  async function scan(kind: ApiResourceKind): Promise<ScannedResource[]> {
+    const schema = CREATOR_SCAN_SCHEMAS.get(kind);
+    if (schema === undefined) {
+      throw new Error(
+        `no schema to decode ${kindEnumName(kind)} rows for the creator scan`,
+      );
+    }
+    const rows = await store.listResources(kind);
+    return rows.map((bytes) => {
+      const resource = fromBinary(schema, bytes);
+      const metadata = metadataOf(resource);
+      return {
+        id: metadata?.id ?? "",
+        org: metadata?.org ?? "",
+        createdBy: auditOf(schema, resource)?.specAudit?.createdBy?.id ?? "",
+      };
+    });
+  }
+
+  async function scanBlueprints(): Promise<ScannedResource[]> {
+    const scanned: ScannedResource[] = [];
+    for (const kind of BLUEPRINT_KINDS) {
+      scanned.push(...(await scan(kind)));
+    }
+    return scanned;
+  }
+
+  /** The organizations `accountId` already holds any row on — the idempotency set. */
+  async function organizationsHeldBy(
+    accountId: string,
+  ): Promise<ReadonlySet<string>> {
+    const rows = await policies.findByPrincipal(IDENTITY_ACCOUNT, accountId);
+    return new Set(
+      rows
+        .filter((row) => row.spec?.resource?.kind === ORGANIZATION)
+        .map((row) => row.spec?.resource?.id ?? ""),
+    );
+  }
+
+  return {
+    async onAccountCreated(account, caller): Promise<void> {
+      if (caller.callerClass !== "user") {
+        return;
+      }
+      const accountId = account.metadata?.id ?? "";
+      if (accountId === "") {
+        throw new Error(
+          "membership rules: the provisioned account carries no id",
+        );
+      }
+      const organizations = await scan(ApiResourceKind.organization);
+      if (organizations.length === 0) {
+        return;
+      }
+      const subject = account.spec?.idpId ?? "";
+      const email = account.spec?.email ?? "";
+      const isMine = (stamp: string): boolean =>
+        stamp !== "" && (stamp === subject || stamp === accountId);
+      const held = await organizationsHeldBy(accountId);
+      const blueprints = await scanBlueprints();
+
+      for (const organization of organizations) {
+        if (held.has(organization.id)) {
+          continue;
+        }
+        const inOrganization = blueprints.filter(
+          (blueprint) => blueprint.org === organization.id,
+        );
+        let role: IamRole;
+        if (isMine(organization.createdBy)) {
+          role = IamRole.owner;
+        } else if (inOrganization.some((b) => isMine(b.createdBy))) {
+          role = IamRole.admin;
+        } else if (operatorEmail !== "" && email === operatorEmail) {
+          role = IamRole.admin;
+        } else if (
+          ![
+            organization.createdBy,
+            ...inOrganization.map((b) => b.createdBy),
+          ].some((stamp) => isPersonStamp(stamp) && !isMine(stamp)) &&
+          (await policies.findByResource(ORGANIZATION, organization.id))
+            .length === 0
+        ) {
+          role = IamRole.admin;
+        } else {
+          role = IamRole.member;
+        }
+        await grantPath.grant(
+          organizationRole(accountId, role, organization.id),
+          caller,
+        );
+      }
+    },
+
+    async ensureOperatorOwnership(operator): Promise<void> {
+      const accountId = operator.metadata?.id ?? "";
+      if (accountId === "") {
+        throw new Error("membership rules: the operator account carries no id");
+      }
+      const actor = operatorActor(operator, accountId);
+      for (const organization of await scan(ApiResourceKind.organization)) {
+        const owners = await policies.findByResourceWithRelations(
+          ORGANIZATION,
+          organization.id,
+          [relationOf(IamRole.owner)],
+        );
+        if (owners.length > 0) {
+          continue;
+        }
+        await grantPath.grant(
+          organizationRole(accountId, IamRole.owner, organization.id),
+          actor,
+        );
+      }
+    },
+  };
+}
+
+/**
+ * The operator acting as its account: the trusted-local identity shape
+ * (pipeline/interceptors/auth.ts trustedLocalIdentityFor — no issuer, no
+ * token; email and display name only when known) with the account id as
+ * the principal, so the row's audit actor is the account, named the way
+ * every other trusted-local write names it.
+ */
+function operatorActor(
+  operator: IdentityAccount,
+  accountId: string,
+): CallerIdentity {
+  const email = operator.spec?.email ?? "";
+  const displayName = operator.metadata?.name ?? "";
+  return {
+    identityId: accountId,
+    callerClass: "user",
+    issuer: "",
+    rawToken: "",
+    ...(email !== "" ? { email } : {}),
+    ...(displayName !== "" ? { displayName } : {}),
+  };
+}

package/src/domain/iampolicy/permissions.ts

@@ -0,0 +1,35 @@
+/**
+ * The permission vocabulary as the wire spells it (20260913.01 slice 5,
+ * Q-S5-3): `checkMyPermission` carries its `relation` as a string — the
+ * FGA relation name, which is the `IamPermission` member name — while the
+ * composed Authorizer's `AuthzCheck` carries the enum. This is the one
+ * read from the first spelling to the second. A relation that names no
+ * permission is the caller's mistake (INVALID_ARGUMENT in the controller),
+ * never a permission nobody holds: the console asks with the ten strings
+ * `IamPermission` lists (claim check C4) and a typo should be heard.
+ *
+ * A Map over the descriptor's values, never the TS enum's reverse index
+ * (the `kindsByEnumName` doctrine in pipeline/apiresource-meta.ts): a
+ * prototype key or a number spelled as text must resolve to nothing. The
+ * zero value `unspecified` is not a permission and is left out.
+ */
+import {
+  IamPermission,
+  IamPermissionSchema,
+} from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+
+let byName: Map<string, IamPermission> | undefined;
+
+/** The permission a wire relation names, or `undefined`. */
+export function permissionByEnumName(
+  relation: string,
+): IamPermission | undefined {
+  if (byName === undefined) {
+    byName = new Map(
+      IamPermissionSchema.values
+        .filter((value) => value.number !== IamPermission.unspecified)
+        .map((value) => [value.name, value.number as IamPermission]),
+    );
+  }
+  return byName.get(relation);
+}

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

@@ -0,0 +1,186 @@
+/**
+ * The open-source IamPolicyStore: the port (store.ts) over the generic
+ * Store, rows of the `resources` table by kind (20260913.01, T01_0_plan.md
+ * §3a, §4). The composition root installs it when no extension registers
+ * `drivers.iamPolicyStore`.
+ *
+ * Reads. `findById` is a PRIMARY-KEY read. Every other find decodes
+ * `listResources(iam_policy)` and filters in memory: the `resources` table
+ * has no secondary index and `findByField` is single-hit, so a scan is the
+ * honest shape, and the row count is members × organizations on a
+ * self-host — measured in the entry's execution record (§4), not assumed.
+ * The filters are the cloud store's WHERE clauses restated over the proto
+ * (store.ts names each), so a driver's test over either edition reads the
+ * same contract.
+ *
+ * Writes. `save` refuses a policy whose id is not its triple's derived id
+ * (constants.ts policyIdFor): open source has no legacy random ids, and a
+ * stray id would break the primary key's promise of one row per triple.
+ * It is then read-then-write refusing a held id with DuplicatePolicyError,
+ * because the generic Store's saveResource is an upsert with no
+ * create-only form — the 2a adapter's shape and its recorded residual
+ * window (two concurrent saves of one triple may both fulfil; the primary
+ * key still guarantees ONE row, which is the invariant that matters, and
+ * the grant path treats a same-triple winner as the duplicate arm either
+ * way). Conditional store writes are a platform-wide follow-up, not this
+ * adapter's to invent.
+ *
+ * Store faults follow the ratified mapping (domain/apikey/lookup.ts): a
+ * typed ResourceNotFoundError reads as `undefined`; anything else
+ * propagates — an outage must never read as "no grant".
+ *
+ * The port's contract is proven by store-contract.ts, run over this
+ * adapter on both drivers in __tests__/resource-store.test.ts, which also
+ * pins the derived-id refusal that is this adapter's own.
+ */
+import { fromBinary } from "@bufbuild/protobuf";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { IamPolicy } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
+import { IamPolicySchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
+
+import { kindEnumName } from "../../pipeline/apiresource-meta.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
+import type { Store } from "../../store/interface.js";
+import { USER_GRANT_PRINCIPAL_KINDS, policyIdFor } from "./constants.js";
+import { DuplicatePolicyError } from "./store.js";
+import type { IamPolicyStore } from "./store.js";
+
+const KIND = ApiResourceKind.iam_policy;
+
+/**
+ * The cloud SQL's scope-tuple exclusions (store.ts): a scope tuple is a
+ * row whose principal is a RESOURCE and whose relation is structural. The
+ * 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).
+ */
+const NON_STRUCTURAL_PRINCIPAL_KINDS: ReadonlyArray<string> = [
+  ...USER_GRANT_PRINCIPAL_KINDS.map((kind) => kindEnumName(kind)),
+  "team",
+];
+const NON_STRUCTURAL_RELATIONS: ReadonlyArray<string> = ["owner", "creator"];
+
+export function newResourceIamPolicyStore(store: Store): IamPolicyStore {
+  async function readById(id: string): Promise<IamPolicy | undefined> {
+    try {
+      return await store.getResource(KIND, id, IamPolicySchema);
+    } catch (error) {
+      if (error instanceof ResourceNotFoundError) {
+        return undefined;
+      }
+      throw error;
+    }
+  }
+
+  /** Every row of the kind, decoded — the scan behind every non-id read. */
+  async function all(): Promise<ReadonlyArray<IamPolicy>> {
+    const rows = await store.listResources(KIND);
+    return rows.map((bytes) => fromBinary(IamPolicySchema, bytes));
+  }
+
+  async function where(
+    predicate: (policy: IamPolicy) => boolean,
+  ): Promise<ReadonlyArray<IamPolicy>> {
+    return (await all()).filter(predicate);
+  }
+
+  return {
+    async save(policy): Promise<void> {
+      const id = policy.metadata?.id ?? "";
+      if (policy.spec === undefined || id !== policyIdFor(policy.spec)) {
+        throw new Error("policy id must be derived from its triple");
+      }
+      if ((await readById(id)) !== undefined) {
+        throw new DuplicatePolicyError(`IAM policy '${id}' already exists`);
+      }
+      await store.saveResource(KIND, id, IamPolicySchema, policy);
+    },
+
+    async deleteById(id): Promise<void> {
+      await store.deleteResource(KIND, id);
+    },
+
+    findById: readById,
+
+    findByPrincipal(principalKind, principalId) {
+      return where((policy) => onPrincipal(policy, principalKind, principalId));
+    },
+
+    findByResource(resourceKind, resourceId) {
+      return where((policy) => onResource(policy, resourceKind, resourceId));
+    },
+
+    findByPrincipalAndResource(
+      principalKind,
+      principalId,
+      resourceKind,
+      resourceId,
+    ) {
+      return where(
+        (policy) =>
+          onPrincipal(policy, principalKind, principalId) &&
+          onResource(policy, resourceKind, resourceId),
+      );
+    },
+
+    findByResourceWithRelations(resourceKind, resourceId, relations) {
+      return where(
+        (policy) =>
+          onResource(policy, resourceKind, resourceId) &&
+          relations.includes(relationOf(policy)),
+      );
+    },
+
+    async countDistinctPrincipalsByResource(
+      resourceKind,
+      resourceId,
+      principalKind,
+      relations,
+    ): Promise<number> {
+      const principals = new Set<string>();
+      for (const policy of await all()) {
+        if (
+          onResource(policy, resourceKind, resourceId) &&
+          relations.includes(relationOf(policy)) &&
+          (principalKind === undefined ||
+            policy.spec?.principal?.kind === principalKind)
+        ) {
+          principals.add(
+            `${policy.spec?.principal?.kind ?? ""}:${policy.spec?.principal?.id ?? ""}`,
+          );
+        }
+      }
+      return principals.size;
+    },
+
+    async findScopeTuple(resourceKind, resourceId) {
+      return (await all()).find(
+        (policy) =>
+          onResource(policy, resourceKind, resourceId) &&
+          !NON_STRUCTURAL_PRINCIPAL_KINDS.includes(
+            policy.spec?.principal?.kind ?? "",
+          ) &&
+          !NON_STRUCTURAL_RELATIONS.includes(relationOf(policy)),
+      );
+    },
+  };
+}
+
+function onPrincipal(policy: IamPolicy, kind: string, id: string): boolean {
+  return (
+    policy.spec?.principal?.kind === kind && policy.spec?.principal?.id === id
+  );
+}
+
+function onResource(policy: IamPolicy, kind: string, id: string): boolean {
+  return (
+    policy.spec?.resource?.kind === kind && policy.spec?.resource?.id === id
+  );
+}
+
+function relationOf(policy: IamPolicy): string {
+  return policy.spec?.relation ?? "";
+}

package/src/domain/iampolicy/role-lifecycle.ts

@@ -0,0 +1,132 @@
+/**
+ * The built-in role lifecycle (20260913.01, T01_0_plan.md §3a; T01_1_review.md
+ * Q-OR-6a): the ResourceAuthorizationLifecycle open source installs when
+ * no unit registers one, under the built-in authorization posture
+ * (boot/compose.ts `builtInAuthorization`). It is the ROW writer of that
+ * posture at the resource lifecycle points — the one arm that makes an
+ * organization's creator its owner without an administrator — and nothing
+ * more. The cloud's tuple driver plays the same part for tuples; a
+ * composition that registers one never sees this object.
+ *
+ * It is handed to the ORGANIZATION and IDENTITY-ACCOUNT controllers only
+ * (slice 4 ruling Q-S4-8), the two kinds whose events it reads. A
+ * lifecycle on a controller turns on the tuple steps' full event
+ * resolution for that kind, and resolution fails a request whose
+ * configured parent id is missing — Java parity the cloud relies on, and
+ * a state open source admits by contract for other kinds (a memory
+ * captured with no credential has no subject). Every other controller
+ * keeps the composed driver (undefined in open source) and its steps
+ * no-op before any resolution, byte-identical to before this entry.
+ *
+ * What it writes:
+ *   - `organization` created with DIRECT attribution (the kind's
+ *     owner_type in kind_meta — the event says so; the driver follows it
+ *     exactly as the cloud's does) by a `user`-class caller that RESOLVES
+ *     to an account: one `owner` row for that account. Only `organization`,
+ *     because that row is what the Members page and entry 3's admin rule
+ *     read; an owner row on an agent would be the per-resource grant the
+ *     grant scope keeps Enterprise (Q-OR-3).
+ *   - `organization` and `identity_account` deleted: every row naming the
+ *     resource on either side goes, through the grant path's bidirectional
+ *     cleanup — the delete chains' CleanupIamPolicies step calls this, so
+ *     the rows die with the resource.
+ *
+ * Who the row is FOR, and who it says wrote it. The event's caller is the
+ * position-1 identity, which is an account id only when a verifier
+ * resolved it: under the trusted-local posture it is the operator's
+ * EMAIL (or "system"), and a composition verifier may stamp a raw
+ * subject. `accountForCaller` (domain/identityaccount/resolve.ts) is the
+ * domain's one statement of "the caller's account" — the two reads
+ * whoAmI makes — so this object and whoAmI cannot disagree (Q-S4-1). The
+ * row is then granted AS the account (`identityId` re-stamped, the
+ * `provisionMyAccount` idiom), so every policy row's `created_by.id` is
+ * an account id — never an email, never an idp subject. A caller that
+ * resolves to no account (an idp-shaped subject before provisioning)
+ * writes nothing: the membership rules heal a real person's ownership at
+ * first provisioning through the organization's creator stamp
+ * (membership.ts, Q-OR-6b), so the guard loses nobody. Non-`user` classes
+ * (`internal`, `runner`, a composition's own) write nothing by rule — the
+ * roles are people's (Q-OR-6b), and under trusted-local a daemon-origin
+ * caller carries the operator's fields and would otherwise resolve.
+ *
+ * Acyclic by construction: this object sits ON TOP of the grant path and
+ * defines neither policy hook. The grant path's own lifecycle is the
+ * composed driver (undefined in open source), never this object (S1
+ * finding B); the test pins both facts.
+ *
+ * Faults propagate. The create arm's throw fails the organization create
+ * (the step maps it INTERNAL; the row survives, a retry converges through
+ * the grant path's duplicate arm); the delete arm's throw is logged and
+ * the delete succeeds (the step's best-effort contract).
+ */
+import { create } from "@bufbuild/protobuf";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { OwnerAttributionType } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/authorization_config_pb";
+import { ApiResourceRefSchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
+import { IamRole } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+
+import type {
+  ResourceAuthorizationLifecycle,
+  ResourceCreatedEvent,
+  ResourceDeletedEvent,
+} from "../../extensions/resource-authorization.js";
+import { kindEnumName } from "../../pipeline/apiresource-meta.js";
+import { accountForCaller } from "../identityaccount/resolve.js";
+import type { AccountsByCaller } from "../identityaccount/resolve.js";
+import type { IamPolicyGrantPath } from "./grant-path.js";
+import { organizationRole } from "./specs.js";
+
+export interface BuiltInRoleLifecycleDeps {
+  readonly grantPath: IamPolicyGrantPath;
+  readonly accounts: AccountsByCaller;
+}
+
+/** The kinds whose rows die with the resource — the two sides an organization role names. */
+const CLEANUP_KINDS: ReadonlySet<ApiResourceKind> = new Set([
+  ApiResourceKind.organization,
+  ApiResourceKind.identity_account,
+]);
+
+export function newBuiltInRoleLifecycle(
+  deps: BuiltInRoleLifecycleDeps,
+): ResourceAuthorizationLifecycle {
+  const { grantPath, accounts } = deps;
+  return {
+    async onResourceCreated(event: ResourceCreatedEvent): Promise<void> {
+      if (
+        event.kind !== ApiResourceKind.organization ||
+        event.ownerAttribution !== OwnerAttributionType.DIRECT ||
+        event.caller.callerClass !== "user"
+      ) {
+        return;
+      }
+      const account = await accountForCaller(accounts, event.caller);
+      const accountId = account?.metadata?.id ?? "";
+      if (accountId === "") {
+        return;
+      }
+      await grantPath.grant(
+        organizationRole(accountId, IamRole.owner, event.resourceId),
+        { ...event.caller, identityId: accountId },
+      );
+    },
+
+    async onResourceDeleted(event: ResourceDeletedEvent): Promise<void> {
+      if (!CLEANUP_KINDS.has(event.kind)) {
+        return;
+      }
+      await grantPath.cleanupResource(
+        create(ApiResourceRefSchema, {
+          kind: kindEnumName(event.kind),
+          id: event.resourceId,
+        }),
+      );
+    },
+
+    async onVisibilityChanged(): Promise<void> {
+      // Visibility is a tuple concern (org-viewer, public-viewer shapes);
+      // open source's rows record roles, not visibility.
+    },
+  };
+}