@stigmer/server 3.15.2 → 3.15.3-dev.20260914121148

package/src/pipeline/__tests__/inherited-authorization-parent.test.ts

@@ -0,0 +1,51 @@
+/**
+ * Pins `inheritedAuthorizationParentOf` (pipeline/apiresource-meta.ts):
+ * the kind_meta question "is this kind's authorization its parent's
+ * whole?", answered by the PARENT-scope + INHERITED-owner pair and by
+ * nothing else (stigmer-cloud 20260913.04 T04, Q-LB-34).
+ *
+ * The table below is the WHOLE kind enum, on purpose. The list read scope
+ * carries `authorizationParent` for exactly the kinds this function names,
+ * and a composed driver asks its authorization backend about the parent
+ * in the child's place — so a second kind joining the set is a change in
+ * what that driver checks, and must arrive as a reviewed edit of this
+ * table, never as a silent consequence of a kind_meta edit. Kinds with
+ * additional parents whose inheritance is partial (workflow_execution's
+ * opt-in `execution_viewer from workflow_instance`, agent_instance's
+ * `viewer from default_of`) own themselves and are pinned as `undefined`.
+ */
+import { describe, expect, it } from "vitest";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { inheritedAuthorizationParentOf } from "../apiresource-meta.js";
+
+describe("inheritedAuthorizationParentOf — the parent a kind's authorization is", () => {
+  it("agent_execution's authorization is its session's: relation `session`, spec field `session_id`", () => {
+    const parent = inheritedAuthorizationParentOf(
+      ApiResourceKind.agent_execution,
+    );
+    expect(parent).toBeDefined();
+    expect(parent?.kind).toBe("session");
+    expect(parent?.relation).toBe("session");
+    expect(parent?.specField).toBe("session_id");
+  });
+
+  it("every other kind's authorization is its own (the whole enum, pinned)", () => {
+    const inherited = Object.values(ApiResourceKind)
+      .filter((value): value is ApiResourceKind => typeof value === "number")
+      .filter((kind) => kind !== ApiResourceKind.api_resource_kind_unknown)
+      .filter((kind) => inheritedAuthorizationParentOf(kind) !== undefined)
+      .map((kind) => ApiResourceKind[kind]);
+    expect(inherited).toEqual(["agent_execution"]);
+  });
+
+  it.each([
+    ApiResourceKind.workflow_execution,
+    ApiResourceKind.agent_instance,
+    ApiResourceKind.workflow_instance,
+    ApiResourceKind.memory,
+  ])("a kind with an additional, partial parent owns itself: %s", (kind) => {
+    expect(inheritedAuthorizationParentOf(kind)).toBeUndefined();
+  });
+});

package/src/pipeline/__tests__/kind-by-enum-name.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Pins `kindByEnumName` (pipeline/apiresource-meta.ts), the lookup for the
+ * SECOND kind vocabulary the contract carries. A resource's own `kind`
+ * field is the `kind_meta.name` ("McpServer"; `getKindEnum`, the #545
+ * lesson). An `ApiResourceRef.kind` — the IamPolicy spec's principal and
+ * resource, the FGA object type — is the enum MEMBER name ("mcp_server"),
+ * which is what every SDK call site sends and what the cloud's
+ * `kindFromSpecString` resolved before this entry (20260913.01, Q-OR-2).
+ *
+ * Two properties are load-bearing and pinned here rather than assumed:
+ *
+ *   - EXACT match, never canonicalised. The IamPolicy id is derived from
+ *     the spec's text (Q-OR-9), so a lenient matcher that admitted
+ *     "Organization" beside "organization" would mint two rows for one
+ *     grant, or force the domain to rewrite caller input before storing
+ *     it. The two spellings `getKindEnum` accepts are refused here on
+ *     purpose; the contrast arm keeps the two lookups from being merged.
+ *   - NEVER a throw. The Authorize step resolves `resource_kind_path`
+ *     through this function at position 1 of every chain, and resolution
+ *     never throws by doctrine (authorize.ts header): an unknown name is
+ *     the unknown kind, and the Authorizer owns the decision.
+ */
+import { describe, expect, it } from "vitest";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import {
+  getKindEnum,
+  kindByEnumName,
+  kindEnumName,
+} from "../apiresource-meta.js";
+
+describe("kindByEnumName — an ApiResourceRef.kind is the enum member name", () => {
+  it.each([
+    ["organization", ApiResourceKind.organization],
+    ["identity_account", ApiResourceKind.identity_account],
+    ["mcp_server", ApiResourceKind.mcp_server],
+    ["agent", ApiResourceKind.agent],
+    ["iam_policy", ApiResourceKind.iam_policy],
+  ])("%s resolves to its kind", (name, kind) => {
+    expect(kindByEnumName(name)).toBe(kind);
+  });
+
+  it.each([
+    ["Organization", "the kind_meta spelling, not a member name"],
+    ["McpServer", "the kind_meta spelling, not a member name"],
+    ["ORGANIZATION", "case differs"],
+    ["organization ", "trailing whitespace"],
+    ["", "empty"],
+    ["spaceship", "not a kind"],
+    ["5", "a number spelled as text is not a name"],
+    ["constructor", "a prototype key is not a name"],
+  ])("%s is the unknown kind (%s) — never a throw", (value) => {
+    expect(kindByEnumName(value)).toBe(
+      ApiResourceKind.api_resource_kind_unknown,
+    );
+  });
+
+  it("the zero value's own name is the unknown kind too", () => {
+    expect(kindByEnumName("api_resource_kind_unknown")).toBe(
+      ApiResourceKind.api_resource_kind_unknown,
+    );
+  });
+
+  it("is exact where getKindEnum is lenient — the two vocabularies stay two lookups", () => {
+    // A resource's `kind` field: canonical kind_meta.name matching,
+    // case-insensitive, underscores ignored, and a throw on unknown.
+    expect(getKindEnum("McpServer")).toBe(ApiResourceKind.mcp_server);
+    expect(getKindEnum("mcp_server")).toBe(ApiResourceKind.mcp_server);
+    expect(() => getKindEnum("spaceship")).toThrow();
+    // An ApiResourceRef.kind: the member name and nothing else.
+    expect(kindByEnumName("McpServer")).toBe(
+      ApiResourceKind.api_resource_kind_unknown,
+    );
+    expect(kindByEnumName("mcp_server")).toBe(ApiResourceKind.mcp_server);
+  });
+
+  it("every member of the enum round-trips through its own name", () => {
+    for (const [name, value] of Object.entries(ApiResourceKind)) {
+      if (typeof value !== "number") continue;
+      expect(kindByEnumName(name), name).toBe(value);
+    }
+  });
+});
+
+describe("kindEnumName — the inverse: a kind spelled as an ApiResourceRef.kind", () => {
+  it.each([
+    [ApiResourceKind.organization, "organization"],
+    [ApiResourceKind.identity_account, "identity_account"],
+    [ApiResourceKind.mcp_server, "mcp_server"],
+  ])("%s spells as %s", (kind, name) => {
+    expect(kindEnumName(kind)).toBe(name);
+  });
+
+  it("the unknown kind spells itself — never a throw", () => {
+    expect(kindEnumName(ApiResourceKind.api_resource_kind_unknown)).toBe(
+      "api_resource_kind_unknown",
+    );
+  });
+
+  it("round-trips with kindByEnumName over every member — the two are inverses", () => {
+    for (const value of Object.values(ApiResourceKind)) {
+      if (typeof value !== "number") continue;
+      expect(kindByEnumName(kindEnumName(value)), String(value)).toBe(value);
+    }
+  });
+});

package/src/pipeline/__tests__/kind-served-by-edition.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Pins `tierServedByEdition` and `kindServedByEdition`
+ * (pipeline/apiresource-meta.ts), the server's twin of the SDK's tier-rank
+ * functions (sdk/typescript/src/resource-availability.ts: editions
+ * oss < enterprise < cloud; a tier admits its own edition and every edition
+ * above it; the enum NUMBERS are wire identifiers, never ranks —
+ * `enterprise` sits at 3 in both enums and ranks second). T01_1_review.md
+ * Q-OR-8 and claim check C5: the two implementations must agree on the
+ * whole matrix, because the console reads the SDK's answer to decide what
+ * to SHOW and `checkMyPermission` reads the server's to decide what is
+ * HELD; a disagreement is a surface that appears and then fails, the
+ * Q-EC-2b class.
+ *
+ * The matrix is spelled out rather than computed, so a change on either
+ * side is a visible diff here and the SDK's own test remains the SDK's.
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+  ApiResourceKind,
+  ResourceTier,
+} from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ServerEdition } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+
+import {
+  kindServedByEdition,
+  tierServedByEdition,
+} from "../apiresource-meta.js";
+
+const EDITIONS = [
+  ServerEdition.oss,
+  ServerEdition.enterprise,
+  ServerEdition.cloud,
+] as const;
+
+/** tier → the editions that serve it, in the SDK's order. */
+const MATRIX: ReadonlyArray<readonly [ResourceTier, readonly boolean[]]> = [
+  [ResourceTier.open_source, [true, true, true]],
+  [ResourceTier.enterprise, [false, true, true]],
+  [ResourceTier.cloud_only, [false, false, true]],
+  // A kind whose proto forgot the field is treated as core, as the SDK
+  // treats it: hiding a kind is the worse failure for a client, and holding
+  // a permission on a kind every edition serves is the truthful answer.
+  [ResourceTier.resource_tier_unspecified, [true, true, true]],
+];
+
+describe("tierServedByEdition — the SDK's rank table, spelled out", () => {
+  for (const [tier, served] of MATRIX) {
+    it(`${ResourceTier[tier]} is served by [oss, enterprise, cloud] = [${served.join(", ")}]`, () => {
+      expect(
+        EDITIONS.map((edition) => tierServedByEdition(tier, edition)),
+      ).toEqual(served);
+    });
+  }
+
+  it("an edition the server does not know serves everything — an older server hides nothing, the SDK's own fallback", () => {
+    for (const [tier] of MATRIX) {
+      expect(
+        tierServedByEdition(tier, ServerEdition.server_edition_unspecified),
+      ).toBe(true);
+    }
+  });
+});
+
+describe("kindServedByEdition — the kind's tier through the same table", () => {
+  it("reads the tier from kind_meta: agent everywhere, invitation from enterprise up, api_resource_version on cloud only", () => {
+    expect(
+      EDITIONS.map((edition) =>
+        kindServedByEdition(ApiResourceKind.agent, edition),
+      ),
+    ).toEqual([true, true, true]);
+    expect(
+      EDITIONS.map((edition) =>
+        kindServedByEdition(ApiResourceKind.invitation, edition),
+      ),
+    ).toEqual([false, true, true]);
+    expect(
+      EDITIONS.map((edition) =>
+        kindServedByEdition(ApiResourceKind.api_resource_version, edition),
+      ),
+    ).toEqual([false, false, true]);
+  });
+
+  it("platform is enterprise-tiered, so the operator seat's permissions are never held on open source (the settings-navigation arm)", () => {
+    expect(
+      kindServedByEdition(ApiResourceKind.platform, ServerEdition.oss),
+    ).toBe(false);
+    expect(
+      kindServedByEdition(ApiResourceKind.platform, ServerEdition.enterprise),
+    ).toBe(true);
+  });
+
+  it("iam_policy is served by every edition once this entry flips it", () => {
+    expect(
+      kindServedByEdition(ApiResourceKind.iam_policy, ServerEdition.oss),
+    ).toBe(true);
+  });
+
+  it("the unknown kind is a programming error, not an answer", () => {
+    expect(() =>
+      kindServedByEdition(
+        ApiResourceKind.api_resource_kind_unknown,
+        ServerEdition.cloud,
+      ),
+    ).toThrow();
+  });
+});

package/src/pipeline/apiresource-meta.ts

@@ -8,6 +8,39 @@
  * Both editions resolve the same strings from the same proto metadata; the
  * visibility helpers mirror Cloud's VisibilityConfigResolver so the
  * cross-edition error contract is identical by construction.
+ *
+ * The contract carries TWO kind vocabularies, and this module holds one
+ * lookup for each so they are never merged:
+ *
+ *   - A resource's own `kind` field is the `kind_meta.name` ("McpServer").
+ *     `getKindEnum` reads it by canonical name (case-insensitive,
+ *     underscores ignored) and throws on an unknown value.
+ *   - An `ApiResourceRef.kind` — the IamPolicy spec's principal and
+ *     resource, the FGA object type — is the enum MEMBER name
+ *     ("mcp_server"). `kindByEnumName` reads it by the descriptor's exact
+ *     proto name and never throws (20260913.01, Q-OR-2). Exact, because the
+ *     IamPolicy id is derived from the spec's text (Q-OR-9): a lenient
+ *     match would let "Organization" and "organization" mint two rows for
+ *     one grant. Reading the descriptor's name is not deriving a spelling;
+ *     the #545 rule is about recovering kind_meta.name from an enum, which
+ *     neither lookup does. A reader asked about a kind that arrived
+ *     through this vocabulary follows its doctrine: `grantableRolesFor`
+ *     answers the empty list for the unknown kind instead of throwing,
+ *     because the kind it is asked about may have come off the wire.
+ *     `kindEnumName` is the inverse — how server code SPELLS a kind when
+ *     it builds an `ApiResourceRef` itself (the built-in role lifecycle's
+ *     cleanup refs; the organization-role specs) — so no caller reaches
+ *     for the enum's reverse index by hand.
+ *
+ * A kind's TIER meets the served EDITION in exactly one place on the
+ * server, `tierServedByEdition` / `kindServedByEdition` (20260913.01
+ * Q-OR-8; claim check C5) — the twin of the SDK's rank functions
+ * (sdk/typescript/src/resource-availability.ts), pinned equal on the whole
+ * matrix by __tests__/kind-served-by-edition.test.ts. The console reads
+ * the SDK's answer to decide what to SHOW; `checkMyPermission` reads the
+ * server's to decide what is HELD; a disagreement is a surface that
+ * appears and then fails. The enum NUMBERS are wire identifiers, never
+ * ranks (`enterprise` sits at 3 in both enums and ranks second).
  */
 import { getOption, hasOption } from "@bufbuild/protobuf";
 import type { DescEnumValue } from "@bufbuild/protobuf";
@@ -16,9 +49,17 @@ import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apires
 import {
   ApiResourceKind,
   ApiResourceKindSchema,
+  ResourceTier,
   kind_meta,
 } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import type { ApiResourceKindMeta } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import {
+  AuthorizationScopeType,
+  OwnerAttributionType,
+} from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/authorization_config_pb";
+import type { ParentRelationConfig } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/authorization_config_pb";
+import type { IamRole } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+import { ServerEdition } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
 
 /** Go GetKindMeta: the kind_meta extension of the enum value. */
 export function getKindMeta(kind: ApiResourceKind): ApiResourceKindMeta {
@@ -29,6 +70,38 @@ export function getKindMeta(kind: ApiResourceKind): ApiResourceKindMeta {
   return getOption(valueDesc, kind_meta);
 }
 
+/**
+ * The parent a kind's authorization IS — the `kind_meta` declaration that
+ * a kind's permissions are its parent's whole, not its own: PARENT scope
+ * (the one structural link is to that parent) AND INHERITED owner (no
+ * owner tuple of its own; `owner from <parent>` in the FGA model).
+ * Undefined for every other kind, including kinds with additional parents
+ * whose inheritance is partial (a workflow_execution's opt-in
+ * `execution_viewer from workflow_instance` sits beside its own owner).
+ *
+ * Today exactly one kind answers: agent_execution → session (its
+ * `can_view` is `viewer or can_view from session`, and `viewer` is the
+ * session's). The list read scope reads this to carry the parent on every
+ * candidate (`ListEntryMeta.authorizationParent`, 20260913.04 T04), so a
+ * composed driver may ask its authorization backend about the parent —
+ * direct tuples — instead of the child, whose resolution walks the
+ * parent's whole set. A second kind declaring the pair gets the behavior
+ * from this declaration alone; the table pin in __tests__ makes that a
+ * reviewed change.
+ */
+export function inheritedAuthorizationParentOf(
+  kind: ApiResourceKind,
+): ParentRelationConfig | undefined {
+  const config = getKindMeta(kind).authorization;
+  if (
+    config?.scopeType !== AuthorizationScopeType.PARENT ||
+    config.ownerType !== OwnerAttributionType.INHERITED
+  ) {
+    return undefined;
+  }
+  return config.parent;
+}
+
 /** Go GetIdPrefix: e.g. agent → "agt". */
 export function getIdPrefix(kind: ApiResourceKind): string {
   return getKindMeta(kind).idPrefix;
@@ -55,19 +128,143 @@ export function getKindEnum(kindValue: string): ApiResourceKind {
   return kind;
 }
 
+/**
+ * Resolves an `ApiResourceRef.kind` — a kind's enum MEMBER name, exactly
+ * as the proto spells it ("organization", "identity_account") — to the
+ * enum. Anything else, including the kind_meta spelling, a different case,
+ * the empty string and the zero value's own name, is
+ * `api_resource_kind_unknown`; never a throw, because the Authorize step
+ * resolves `resource_kind_path` through this at position 1 of every chain
+ * and resolution never fails a request (authorize.ts header). See the
+ * module header for why the match is exact.
+ */
+export function kindByEnumName(value: string): ApiResourceKind {
+  return (
+    kindsByEnumName().get(value) ?? ApiResourceKind.api_resource_kind_unknown
+  );
+}
+
+/**
+ * The inverse of `kindByEnumName`: a kind spelled as an `ApiResourceRef.kind`
+ * — the descriptor's exact proto name ("organization", "identity_account").
+ * Total over the enum: the unknown kind spells itself, so a ref built from
+ * it round-trips to the unknown kind and the gate that reads it refuses
+ * the way it refuses a wire caller's garbage; never a throw.
+ */
+export function kindEnumName(kind: ApiResourceKind): string {
+  // A number that is no member (a cast from outside the enum) spells as
+  // the unknown kind, which every descriptor carries as its zero value.
+  const value =
+    kindValueDescriptor(kind) ??
+    kindValueDescriptor(ApiResourceKind.api_resource_kind_unknown);
+  return value?.name ?? "";
+}
+
 /**
  * Go DefaultVisibilityFor: blueprint kinds flagged defaults_to_org_visibility
  * get visibility_org (blueprints are shared org assets — a private default
  * would silently hide new blueprints from teammates); all others get
  * visibility_private.
  */
-export function defaultVisibilityFor(kind: ApiResourceKind): ApiResourceVisibility {
+export function defaultVisibilityFor(
+  kind: ApiResourceKind,
+): ApiResourceVisibility {
   const config = getKindMeta(kind).authorization?.visibility;
   return config?.defaultsToOrgVisibility === true
     ? ApiResourceVisibility.visibility_org
     : ApiResourceVisibility.visibility_private;
 }
 
+/**
+ * The roles a user may be granted on a resource of `kind` according to the
+ * CONTRACT — `kind_meta.authorization.grantable_roles`, the one source of
+ * "what can be granted at all" (Java AuthorizationConfigResolver
+ * .getGrantableRoles; the cloud's iam/policy/roles.ts grantableRolesFor,
+ * which this replaces at the 20260913.01 re-point). A kind that lists none
+ * is system-managed in every edition (identity_account, api_key,
+ * iam_policy, invitation, agent_execution); an edition's PolicyGrantScope
+ * (extensions/policy-grant-scope.ts) only narrows this list.
+ *
+ * Total, never a throw: the kind is an `ApiResourceRef.kind` resolved by
+ * `kindByEnumName`, so the unknown kind — the one member without
+ * `kind_meta` — is a legitimate argument and answers the empty list
+ * (module header, the second vocabulary).
+ */
+export function grantableRolesFor(
+  kind: ApiResourceKind,
+): ReadonlyArray<IamRole> {
+  const valueDesc = kindValueDescriptor(kind);
+  if (valueDesc === undefined || !hasOption(valueDesc, kind_meta)) {
+    return [];
+  }
+  return getOption(valueDesc, kind_meta).authorization?.grantableRoles ?? [];
+}
+
+/**
+ * Whether an edition serves a tier: the tier names the MINIMUM edition,
+ * the editions are ordered oss < enterprise < cloud (each composes the
+ * previous one's units), so a tier admits its own edition and every one
+ * above. An edition the server does not know (`server_edition_unspecified`)
+ * serves everything — the SDK's own fallback: an older client against a
+ * newer server hides nothing. A tier the proto forgot is treated as core
+ * for the same reason the SDK does: hiding a served kind is the worse
+ * failure.
+ */
+export function tierServedByEdition(
+  tier: ResourceTier,
+  edition: ServerEdition,
+): boolean {
+  if (edition === ServerEdition.server_edition_unspecified) {
+    return true;
+  }
+  return editionRank(edition) >= tierRank(tier);
+}
+
+/**
+ * Whether this edition serves a kind: its `kind_meta.tier` through the
+ * table above. Throws for a kind without `kind_meta` (the unknown kind):
+ * a caller that reaches this with wire input has skipped the kind
+ * refusals, and "served" for it would hide that bug.
+ */
+export function kindServedByEdition(
+  kind: ApiResourceKind,
+  edition: ServerEdition,
+): boolean {
+  return tierServedByEdition(getKindMeta(kind).tier, edition);
+}
+
+function editionRank(edition: ServerEdition): number {
+  switch (edition) {
+    case ServerEdition.oss:
+      return 1;
+    case ServerEdition.enterprise:
+      return 2;
+    case ServerEdition.cloud:
+    case ServerEdition.server_edition_unspecified:
+      return 3;
+    default: {
+      const exhaustive: never = edition;
+      throw new Error(`unknown server edition: ${String(exhaustive)}`);
+    }
+  }
+}
+
+function tierRank(tier: ResourceTier): number {
+  switch (tier) {
+    case ResourceTier.open_source:
+    case ResourceTier.resource_tier_unspecified:
+      return 1;
+    case ResourceTier.enterprise:
+      return 2;
+    case ResourceTier.cloud_only:
+      return 3;
+    default: {
+      const exhaustive: never = tier;
+      throw new Error(`unknown resource tier: ${String(exhaustive)}`);
+    }
+  }
+}
+
 /**
  * Go SupportsVisibility: PRIVATE and UNSPECIFIED are always supported (no
  * visibility grant); every other level requires the matching supports_*
@@ -134,3 +331,23 @@ function kindsByCanonicalName(): Map<string, ApiResourceKind> {
   }
   return canonicalNameCache;
 }
+
+let enumNameCache: Map<string, ApiResourceKind> | undefined;
+
+/**
+ * Every member by its descriptor name, the zero value included (it maps to
+ * itself, which is the unknown kind either way). A Map rather than the TS
+ * enum's reverse mapping, so a prototype key or a number spelled as text
+ * cannot resolve to anything.
+ */
+function kindsByEnumName(): Map<string, ApiResourceKind> {
+  if (enumNameCache === undefined) {
+    enumNameCache = new Map(
+      ApiResourceKindSchema.values.map((value) => [
+        value.name,
+        value.number as ApiResourceKind,
+      ]),
+    );
+  }
+  return enumNameCache;
+}

package/src/pipeline/interceptors/auth.ts

@@ -175,6 +175,19 @@ export function trustedLocalIdentity(): CallerIdentity {
   return trustedLocalIdentityFor(operatorIdentitySnapshot());
 }
 
+/**
+ * The identityId of the UNCONFIGURED laptop's operator — no
+ * STIGMER_OPERATOR_EMAIL, so the trust domain's one principal has no
+ * email to be named by. It is what the interceptor stamps and therefore
+ * what every audit actor on such a laptop carries as `created_by.id`; the
+ * operator account derives its subject from it (`local|system`) and the
+ * membership rules read it as "not a person" when they classify creator
+ * stamps (domain/iampolicy/membership.ts). One home (20260913.01 slice 4,
+ * Q-S4-6): a second spelling anywhere would make a stamp and its reader
+ * disagree silently.
+ */
+export const SYSTEM_OPERATOR_IDENTITY_ID = "system";
+
 /**
  * The trusted-local identity for a given operator — the one construction
  * of that principal, shared by the per-request stamp above and by the
@@ -187,7 +200,7 @@ export function trustedLocalIdentityFor(operator: {
 }): CallerIdentity {
   if (operator.email === "") {
     return {
-      identityId: "system",
+      identityId: SYSTEM_OPERATOR_IDENTITY_ID,
       callerClass: "user",
       issuer: "",
       rawToken: "",

package/src/pipeline/steps/__tests__/authorize-annotation-completeness.test.ts

@@ -20,9 +20,32 @@
  * never reach the annotation's resolution (the skip lanes resolve their
  * target in the handler through `authorizeDirect`'s override). A config
  * that names NO kind (static or by path) is outside this invariant: the
- * check is then about the kind, not the id, and today no OSS-served method
- * is shaped that way (the IamPolicy RPCs that are belong to
- * `sp.oss-organization-roles`).
+ * check is then about the kind, not the id.
+ *
+ * The IamPolicy contract is the one place that shape exists, and it is
+ * pinned here by descriptor, not by served route, so the arm turns green
+ * when the ANNOTATIONS land (sp.oss-organization-roles slice 1) and not
+ * when the service is first served (slice 5). Of its nine `rpc.config`
+ * methods: six name their target — `create`, `delete`,
+ * `listResourceAccessByPrincipal`, `getPrincipalResourceRoles` by
+ * `resource_kind_path` (the spec's `resource.kind`, a STRING the resolver
+ * reads by enum name) + `field_path`; `revokeOrgAccess` and
+ * `getPrincipalsCount` statically. `get(IamPolicyId)` names no kind BY
+ * DESIGN: its target is inside the row it loads, so it is the one
+ * load-then-authorize lane (`authorizeDirect` with the override's
+ * resourceKind + resourceId, the getByEmail precedent). The two
+ * `listAuthorized*Ids` were the open question of S1 (finding 7): an
+ * annotation with a permission and no kind resolves to an EMPTY target,
+ * which the open-source permissive Authorizer allows and the cloud's
+ * OpenFGA Authorizer denies for every caller — the #1073 class this
+ * invariant cannot see. Ruled at slice 1 (2026-09-13, T01_1_review.md
+ * Q-OR-2): `listAuthorizedPrincipalIds` HAS a resource and names it (the
+ * same `can_view_access` target `listResourceAccessByPrincipal` enforces
+ * for the same question); `listAuthorizedResourceIds` has a principal and
+ * no resource, so it is an `is_skip_authorization` lane whose handler
+ * enforces `checkAuthorization`'s principal-trust rule (a user only for
+ * themselves; machine and internal for anyone) — a dead `can_view_access`
+ * config would have been exactly the kind-less shape this file guards.
  *
  * The mutation arms prove the check bites over the same function.
  */
@@ -41,6 +64,8 @@ import {
   is_public,
   is_skip_authorization,
 } from "@stigmer/protos/ai/stigmer/commons/rpc/method_options_pb";
+import { IamPolicyCommandController } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/command_pb";
+import { IamPolicyQueryController } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/query_pb";
 
 import { loadConfig } from "../../../boot/config.js";
 import { composeServer } from "../../../boot/compose.js";
@@ -151,6 +176,51 @@ describe("authorization annotations name where the resource id comes from", () =
   });
 });
 
+describe("the IamPolicy contract names its targets (sp.oss-organization-roles slice 1, read by descriptor)", () => {
+  const targets = annotationTargets([
+    IamPolicyCommandController,
+    IamPolicyQueryController,
+  ]);
+  const byName = new Map(
+    targets.map((t) => [t.method.split("/")[1] ?? t.method, t]),
+  );
+
+  it.each([
+    "create",
+    "delete",
+    "revokeOrgAccess",
+    "listResourceAccessByPrincipal",
+    "getPrincipalResourceRoles",
+    "getPrincipalsCount",
+    "listAuthorizedPrincipalIds",
+  ])("%s names a resource kind AND where its id comes from", (method) => {
+    const target = byName.get(method);
+    expect(target, `${method} carries rpc.config`).toBeDefined();
+    expect(target?.namesKind, `${method} names a kind`).toBe(true);
+    expect(target?.namesId, `${method} names its id`).toBe(true);
+  });
+
+  it("get names no kind — the one load-then-authorize lane, its target inside the row", () => {
+    const get = byName.get("get");
+    expect(get, "get carries rpc.config").toBeDefined();
+    expect(get?.namesKind).toBe(false);
+    expect(get?.skipsResolution).toBe(false);
+  });
+
+  it("listAuthorizedResourceIds carries NO rpc.config and skips — its trust rule is the handler's (finding 7)", () => {
+    // Read the descriptor directly: `annotationTargets` lists only
+    // config-carrying methods, and this one must have left that set.
+    const method = IamPolicyQueryController.method.listAuthorizedResourceIds;
+    expect(byName.has("listAuthorizedResourceIds")).toBe(false);
+    expect(hasOption(method, rpcAuthorizationConfig)).toBe(false);
+    expect(getOption(method, is_skip_authorization)).toBe(true);
+  });
+
+  it("the invariant reports none of them once slice 1 lands", () => {
+    expect(unresolvableTargets(targets)).toEqual([]);
+  });
+});
+
 describe("the check bites (mutation proofs over the same function)", () => {
   const shaped = (overrides: Partial<AnnotationTarget>): AnnotationTarget => ({
     method: "x.v1.Query/probe",