@stigmer/server 3.14.0-dev.20260910084630

package/src/pipeline/steps/guard-reserved-labels.ts

@@ -0,0 +1,171 @@
+/**
+ * GuardReservedLabels — the write-boundary guard for the platform-reserved
+ * `stigmer.ai/*` label namespace (the Java GuardReservedLabelsStep port,
+ * cloud#320/#386; C2 Stage 3, 20260827.10).
+ *
+ * Reserved labels carry platform semantics — the motivating one is
+ * `stigmer.ai/default-agent`, which the default-agent resolution reads
+ * GLOBALLY (label + visibility_public), so a tenant labeling its own
+ * public agent would enter every organization's default-agent candidate
+ * set. Only rejecting the write closes that.
+ *
+ * Behavior (the Java matrix verbatim):
+ *   - ECHOES pass — clients read-modify-write whole resources, so a
+ *     stored reserved label legitimately comes back on honest updates.
+ *   - REMOVALS pass — dropping a reserved label only shrinks what it
+ *     granted (de-escalation, and the operator cleanup path).
+ *   - INTRODUCTIONS and CHANGES reject with INVALID_ARGUMENT (the
+ *     cloud#229 boundary doctrine: server-reserved sentinels are not
+ *     accepted from clients) — unless the caller holds
+ *     `can_write_reserved_labels` on `platform:stigmer`, consulted
+ *     LAZILY through the one composed Authorizer, so normal writes pay
+ *     no authorization round-trip. The OSS permissive default allows —
+ *     the local posture keeps today's behavior byte-identically; the
+ *     cloud's FGA Authorizer supplies the operator gate.
+ *   - INTERNAL callers pass (the in-process chain's own composed
+ *     requests — default-instance factories, managed environments; the
+ *     TS rendering of Java's skipAuthorization + isInProcessCall arms).
+ *   - PER-KIND CLIENT CONTRACTS pass: `stigmer.ai/personal` on
+ *     Environment, which the console legitimately sends on create — the
+ *     one allowlist entry, kept here with the doctrine so widening it is
+ *     one reviewable diff.
+ *   - SERVER-STAMPED KEYS pass (server-stamped-reserved-labels.ts, the
+ *     Java ServerStampedReservedLabels arm, cloud#386): a step that made
+ *     the trust decision for specific keys on THIS request records
+ *     exactly those keys, and the guard exempts exactly them (the
+ *     agentexecution create chain's RecordRunnerLineageLabels is the
+ *     first recorder — parity entry 20260830.05).
+ *   - LABELS only, deliberately not annotations (annotations carry no
+ *     resolution or authorization semantics).
+ *
+ * Placement: after BuildNewState/BuildUpdateState — the step inspects the
+ * state that will persist, and update chains have LoadExisting's stored
+ * labels for echo detection. The infrastructure-failure arm answers a
+ * sanitized INTERNAL (the TS store-fault doctrine, #478) where Java
+ * echoes raw exception text — an unpinned outage-lane difference.
+ */
+import { Code, ConnectError } from "@connectrpc/connect";
+import type { DescMessage } from "@bufbuild/protobuf";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+
+import type { Authorizer } from "../../extensions/authorizer.js";
+import { internalError } from "../errors.js";
+import type { PipelineStep } from "../pipeline.js";
+import type { RequestContext } from "../request-context.js";
+import { EXISTING_RESOURCE_KEY } from "./load-existing.js";
+import { serverStampedReservedLabels } from "./server-stamped-reserved-labels.js";
+import { metadataOf } from "./shapes.js";
+
+/** The platform-reserved label key namespace (SystemManagedLabels). */
+export const RESERVED_LABEL_PREFIX = "stigmer.ai/";
+
+/**
+ * The reserved keys clients may legitimately write per kind — the one
+ * entry today is the personal-environment marker the console sends on
+ * create (the Java CLIENT_CONTRACT_ALLOWLIST verbatim).
+ */
+const CLIENT_CONTRACT_ALLOWLIST: ReadonlyMap<
+  ApiResourceKind,
+  ReadonlySet<string>
+> = new Map([
+  [ApiResourceKind.environment, new Set(["stigmer.ai/personal"])],
+]);
+
+/**
+ * The reserved keys `requested` would introduce or change relative to
+ * `stored` — the guard's predicate (SystemManagedLabels
+ * reservedLabelMutations). Removals and echoes are not mutations.
+ */
+export function reservedLabelMutations(
+  stored: Readonly<Record<string, string>>,
+  requested: Readonly<Record<string, string>>,
+): ReadonlyArray<string> {
+  const mutations: string[] = [];
+  for (const [key, value] of Object.entries(requested)) {
+    if (key.startsWith(RESERVED_LABEL_PREFIX) && stored[key] !== value) {
+      mutations.push(key);
+    }
+  }
+  return mutations.sort();
+}
+
+export function newGuardReservedLabelsStep<Desc extends DescMessage>(
+  authorizer: Authorizer,
+): PipelineStep<Desc> {
+  return {
+    name: "GuardReservedLabels",
+    async execute(ctx: RequestContext<Desc>): Promise<void> {
+      if (
+        ctx.callerIdentity.callerClass === "internal" ||
+        ctx.callerIdentity.origin === "in-process"
+      ) {
+        // Server-composed request (the Java isInProcessCall arm,
+        // cloud#386): the trust decision was made by the service code
+        // that built it — default-instance factories stamp reserved
+        // labels by design, even when the call propagates the user's
+        // identity for attribution (ruling R5).
+        return;
+      }
+      const requested = metadataOf(ctx.newState)?.labels ?? {};
+      const existing = ctx.get(EXISTING_RESOURCE_KEY);
+      const stored =
+        existing === undefined
+          ? {}
+          : (metadataOf(existing as typeof ctx.newState)?.labels ?? {});
+
+      const allowlist =
+        CLIENT_CONTRACT_ALLOWLIST.get(ctx.apiResourceKind) ?? new Set();
+      const stamped = serverStampedReservedLabels(ctx);
+      const mutations = reservedLabelMutations(stored, requested).filter(
+        (key) => !allowlist.has(key) && !stamped.has(key),
+      );
+      if (mutations.length === 0) {
+        return;
+      }
+
+      // Lazy operator check — only a request that actually mutates a
+      // reserved key ever reaches the Authorizer.
+      let decision;
+      try {
+        decision = await authorizer.authorize(ctx.callerIdentity, {
+          permission: IamPermission.can_write_reserved_labels,
+          resourceKind: ApiResourceKind.platform,
+          resourceId: "stigmer",
+        });
+      } catch (error) {
+        throw reservedLabelCheckFailure(error);
+      }
+      switch (decision.kind) {
+        case "allow":
+          return;
+        case "deny":
+        case "not-found":
+          throw new ConnectError(
+            `Labels in the reserved '${RESERVED_LABEL_PREFIX}' namespace ` +
+              "are platform-managed and cannot be set or changed by this " +
+              `request: ${mutations.join(", ")}. Stored reserved labels ` +
+              "may be echoed back unchanged or removed.",
+            Code.InvalidArgument,
+          );
+        case "unavailable":
+          throw reservedLabelCheckFailure(decision.cause);
+        default: {
+          const exhaustive: never = decision;
+          throw reservedLabelCheckFailure(
+            new Error(`unknown decision ${JSON.stringify(exhaustive)}`),
+          );
+        }
+      }
+    },
+  };
+}
+
+/** Authorization infrastructure failure: fail closed, sanitized (#478). */
+function reservedLabelCheckFailure(error: unknown): ConnectError {
+  return internalError(
+    error instanceof Error ? error : new Error(String(error)),
+    "reserved-label validation could not be completed",
+  );
+}

package/src/pipeline/steps/helpers.ts

@@ -0,0 +1,154 @@
+/**
+ * Shared lookup helpers — port steps/helpers.go. Full-scan slug and label
+ * lookups, exactly Go's semantics (indexability is guaranteed at the store
+ * interface, not here — D2 §3).
+ */
+import { fromBinary } from "@bufbuild/protobuf";
+import type { DescMessage, MessageShape } from "@bufbuild/protobuf";
+import type { Timestamp } from "@bufbuild/protobuf/wkt";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { AuthorizationScopeType } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/authorization_config_pb";
+
+import type { Store } from "../../store/interface.js";
+import { getKindMeta } from "../apiresource-meta.js";
+import { internalError, invalidArgumentError } from "../errors.js";
+import { metadataOf } from "./shapes.js";
+
+/**
+ * Finds one resource by slug, optionally narrowed to an org — Go
+ * FindResourceBySlug. Slugs are org-scoped identifiers: the same slug can
+ * exist in different orgs; an EMPTY org applies no filter (matches any
+ * org). Not-found is a normal outcome (undefined), never an error.
+ */
+export async function findResourceBySlug<Desc extends DescMessage>(
+  store: Store,
+  kind: ApiResourceKind,
+  schema: Desc,
+  slug: string,
+  org: string,
+): Promise<MessageShape<Desc> | undefined> {
+  const rows = await store.listResources(kind);
+  for (const data of rows) {
+    let resource: MessageShape<Desc>;
+    try {
+      resource = fromBinary(schema, data);
+    } catch {
+      continue; // skip malformed rows, as Go does
+    }
+    const metadata = metadataOf(resource);
+    if (metadata === undefined || metadata.slug !== slug) {
+      continue;
+    }
+    if (org !== "" && metadata.org !== org) {
+      continue;
+    }
+    return resource;
+  }
+  return undefined;
+}
+
+/**
+ * Finds one resource by (labelKey=labelValue, org) — Go
+ * FindResourceByLabelAndOrg. Org is matched EXACTLY here, unlike the slug
+ * helper: (label, org) together form the composite uniqueness key, and
+ * treating an empty org as a wildcard would make an empty-org resource
+ * collide with matching resources in EVERY org — the cross-tenant
+ * over-matching this helper exists to prevent (metadata.org is
+ * proto-unconstrained on create, so empty is a reachable input).
+ */
+export async function findResourceByLabelAndOrg<Desc extends DescMessage>(
+  store: Store,
+  kind: ApiResourceKind,
+  schema: Desc,
+  labelKey: string,
+  labelValue: string,
+  org: string,
+): Promise<MessageShape<Desc> | undefined> {
+  const rows = await store.listResources(kind);
+  for (const data of rows) {
+    let resource: MessageShape<Desc>;
+    try {
+      resource = fromBinary(schema, data);
+    } catch {
+      continue;
+    }
+    const metadata = metadataOf(resource);
+    if (metadata === undefined) {
+      continue;
+    }
+    if (metadata.labels[labelKey] === labelValue && metadata.org === org) {
+      return resource;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Rejects a getByReference lookup that omits org for an org-scoped kind —
+ * Go RequireOrgForReference. For AUTHORIZATION_SCOPE_TYPE_ORGANIZATION
+ * kinds a slug is unique only WITHIN an org; resolving an org-less
+ * reference globally would cross tenant boundaries. The message matches
+ * the cloud edition verbatim (cross-edition error contract).
+ *
+ * Belongs at the getByReference boundary only — the low-level slug finders
+ * are legitimately called with a relative (possibly empty) org by internal
+ * resolvers.
+ */
+export function requireOrgForReference(
+  kind: ApiResourceKind,
+  org: string,
+): void {
+  if (org !== "") {
+    return;
+  }
+  let scopeType: AuthorizationScopeType | undefined;
+  let kindName: string;
+  try {
+    const meta = getKindMeta(kind);
+    scopeType = meta.authorization?.scopeType;
+    kindName = meta.name;
+  } catch (error) {
+    throw internalError(error, "failed to resolve kind metadata for reference org check");
+  }
+  // protobuf-es strips the shared enum prefix: proto
+  // AUTHORIZATION_SCOPE_TYPE_ORGANIZATION generates as ORGANIZATION.
+  if (scopeType === AuthorizationScopeType.ORGANIZATION) {
+    throw invalidArgumentError(`org is required for ${kindName} lookup`);
+  }
+}
+
+// The two list-step helpers below are duplicated per package in Go (each
+// controller carries its own copy); the TS tree consolidates them here
+// because the shared-steps guideline promotes a helper on its second
+// consumer.
+
+/** Go's sort.Slice comparator: newest first; nil timestamps last. */
+export function compareCreatedAtDesc(
+  a: Timestamp | undefined,
+  b: Timestamp | undefined,
+): number {
+  if (a === undefined || b === undefined) {
+    if (a === undefined && b === undefined) {
+      return 0;
+    }
+    return a !== undefined ? -1 : 1;
+  }
+  if (a.seconds !== b.seconds) {
+    return a.seconds > b.seconds ? -1 : 1;
+  }
+  if (a.nanos !== b.nanos) {
+    return a.nanos > b.nanos ? -1 : 1;
+  }
+  return 0;
+}
+
+/** True when resourceLabels contains every filter entry (empty = all). */
+export function matchesAllLabels(
+  resourceLabels: Record<string, string>,
+  filterLabels: Record<string, string>,
+): boolean {
+  return Object.entries(filterLabels).every(
+    ([key, value]) => resourceLabels[key] === value,
+  );
+}

package/src/pipeline/steps/index-search.ts

@@ -0,0 +1,90 @@
+/**
+ * IndexSearch / DeleteSearchIndex — port steps/index_search.go. Search
+ * index maintenance is BEST-EFFORT by contract: the resource is already
+ * persisted (or deleted) when these run, and the index can be rebuilt from
+ * the resources table — a failure logs a warning and never fails the
+ * pipeline. IndexSearch runs AFTER Persist; DeleteSearchIndex AFTER
+ * DeleteResource.
+ */
+import type { DescMessage } from "@bufbuild/protobuf";
+import type { Message } from "@bufbuild/protobuf";
+
+import type { SearchIndexEntry, Store } from "../../store/interface.js";
+import type { Logger } from "../../boot/logger.js";
+import { apiResourceKindName } from "../../store/proto-fields.js";
+import type { PipelineStep } from "../pipeline.js";
+import type { RequestContext } from "../request-context.js";
+import { RESOURCE_ID_KEY } from "./delete.js";
+import { internalError } from "../errors.js";
+import { metadataOf } from "./shapes.js";
+
+/**
+ * Extracts the searchable fields from a resource — Go SearchIndexExtractor.
+ * Each indexed domain registers its own extractor (undefined entry = skip).
+ */
+export interface SearchIndexExtractor {
+  getSearchIndexEntry(resource: Message): SearchIndexEntry | undefined;
+}
+
+export function newIndexSearchStep<Desc extends DescMessage>(
+  store: Store,
+  extractor: SearchIndexExtractor,
+  logger: Logger,
+): PipelineStep<Desc> {
+  return {
+    name: "IndexSearch",
+    async execute(ctx: RequestContext<Desc>): Promise<void> {
+      const resource = ctx.newState;
+      const metadata = metadataOf(resource);
+      if (metadata === undefined || metadata.id === "") {
+        logger.warn("IndexSearch: resource has no metadata or ID, skipping indexing");
+        return;
+      }
+
+      const entry = extractor.getSearchIndexEntry(resource);
+      if (entry === undefined) {
+        logger.warn("IndexSearch: extractor returned no entry, skipping indexing", {
+          id: metadata.id,
+        });
+        return;
+      }
+
+      try {
+        await store.upsertSearchIndex(ctx.apiResourceKind, metadata.id, entry);
+      } catch (error) {
+        logger.warn("IndexSearch: failed to update search index (best-effort)", {
+          id: metadata.id,
+          kind: apiResourceKindName(ctx.apiResourceKind),
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    },
+  };
+}
+
+export function newDeleteSearchIndexStep<Desc extends DescMessage>(
+  store: Store,
+  logger: Logger,
+): PipelineStep<Desc> {
+  return {
+    name: "DeleteSearchIndex",
+    async execute(ctx: RequestContext<Desc>): Promise<void> {
+      const id = ctx.get(RESOURCE_ID_KEY);
+      if (typeof id !== "string" || id === "") {
+        throw internalError(
+          new Error("resource id not found in context (ExtractResourceId must run first)"),
+          "delete search index ordering",
+        );
+      }
+      try {
+        await store.deleteSearchIndex(ctx.apiResourceKind, id);
+      } catch (error) {
+        logger.warn("DeleteSearchIndex: failed to remove search index entry (best-effort)", {
+          id,
+          kind: apiResourceKindName(ctx.apiResourceKind),
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    },
+  };
+}

package/src/pipeline/steps/load-by-reference.ts

@@ -0,0 +1,56 @@
+/**
+ * LoadByReference — ports steps/load_by_reference.go. GetByReference's
+ * loader: validates the reference (kind mismatch → InvalidArgument;
+ * org-scoped kinds require an org — RequireOrgForReference), resolves by
+ * slug with optional org narrowing, stores under TargetResource.
+ */
+import type { DescMessage, MessageShape } from "@bufbuild/protobuf";
+
+import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import type { Store } from "../../store/interface.js";
+import { getKindName } from "../apiresource-meta.js";
+import { invalidArgumentError, notFoundError } from "../errors.js";
+import { apiResourceKindName } from "../../store/proto-fields.js";
+import type { PipelineStep } from "../pipeline.js";
+import type { RequestContext } from "../request-context.js";
+import { findResourceBySlug, requireOrgForReference } from "./helpers.js";
+import { TARGET_RESOURCE_KEY } from "./load-target.js";
+
+export function newLoadByReferenceStep<TargetDesc extends DescMessage>(
+  store: Store,
+  targetSchema: TargetDesc,
+): PipelineStep<typeof ApiResourceReferenceSchema> {
+  return {
+    name: "LoadByReference",
+    async execute(
+      ctx: RequestContext<typeof ApiResourceReferenceSchema>,
+    ): Promise<void> {
+      const ref = ctx.input;
+      if (ref.slug === "") {
+        throw invalidArgumentError("slug is required in reference");
+      }
+
+      const kind = ctx.apiResourceKind;
+      if (
+        ref.kind !== ApiResourceKind.api_resource_kind_unknown &&
+        ref.kind !== kind
+      ) {
+        throw invalidArgumentError(
+          `kind mismatch: expected ${apiResourceKindName(kind)}, got ${apiResourceKindName(ref.kind)}`,
+        );
+      }
+
+      requireOrgForReference(kind, ref.org);
+
+      const target: MessageShape<TargetDesc> | undefined =
+        await findResourceBySlug(store, kind, targetSchema, ref.slug, ref.org);
+      if (target === undefined) {
+        throw notFoundError(getKindName(kind), ref.slug);
+      }
+
+      ctx.set(TARGET_RESOURCE_KEY, target);
+    },
+  };
+}

package/src/pipeline/steps/load-existing.ts

@@ -0,0 +1,73 @@
+/**
+ * LoadExisting — ports steps/load_existing.go. Update/Delete's loader:
+ * by id when provided (direct lookup), else by org-scoped slug (the
+ * fallback populates the id back into metadata so merge/persist have it).
+ * NotFound FAILS here — apply's tolerant probe is LoadForApply.
+ *
+ * Deliberate divergence from the Go source (ratified 2026-08-26): Go
+ * mapped ANY store error to NotFound. Here only the typed
+ * ResourceNotFoundError is NotFound; other store failures rethrow to the
+ * executor's sanitized Internal (see pipeline.ts and load-target.ts —
+ * the same narrowing, applied at every store-read site).
+ */
+import type { DescMessage, MessageShape } from "@bufbuild/protobuf";
+
+import { ResourceNotFoundError } from "../../store/interface.js";
+import type { Store } from "../../store/interface.js";
+import { getKindName } from "../apiresource-meta.js";
+import { internalError, invalidArgumentError, notFoundError } from "../errors.js";
+import type { PipelineStep } from "../pipeline.js";
+import type { RequestContext } from "../request-context.js";
+import { findResourceBySlug } from "./helpers.js";
+import { metadataOf } from "./shapes.js";
+
+/** Context key for the loaded resource (Go ExistingResourceKey). */
+export const EXISTING_RESOURCE_KEY = "existingResource";
+
+export function newLoadExistingStep<Desc extends DescMessage>(
+  store: Store,
+): PipelineStep<Desc> {
+  return {
+    name: "LoadExisting",
+    async execute(ctx: RequestContext<Desc>): Promise<void> {
+      const metadata = metadataOf(ctx.newState);
+      if (metadata === undefined) {
+        throw internalError(new Error("resource metadata is nil"), "load existing");
+      }
+
+      let existing: MessageShape<Desc>;
+      if (metadata.id !== "") {
+        try {
+          existing = await store.getResource(
+            ctx.apiResourceKind,
+            metadata.id,
+            ctx.schema,
+          );
+        } catch (error) {
+          if (error instanceof ResourceNotFoundError) {
+            throw notFoundError(getKindName(ctx.apiResourceKind), metadata.id);
+          }
+          throw error;
+        }
+      } else if (metadata.slug !== "") {
+        const found = await findResourceBySlug(
+          store,
+          ctx.apiResourceKind,
+          ctx.schema,
+          metadata.slug,
+          metadata.org,
+        );
+        if (found === undefined) {
+          throw notFoundError(getKindName(ctx.apiResourceKind), metadata.slug);
+        }
+        existing = found;
+        // Populate the id so merge and persist have it.
+        metadata.id = metadataOf(existing)?.id ?? "";
+      } else {
+        throw invalidArgumentError("resource id or slug is required for update");
+      }
+
+      ctx.set(EXISTING_RESOURCE_KEY, existing);
+    },
+  };
+}

package/src/pipeline/steps/load-for-apply.ts

@@ -0,0 +1,82 @@
+/**
+ * LoadForApply — ports steps/load_for_apply.go. Apply's existence probe:
+ * NEVER fails on not-found — it sets the ShouldCreate/ExistsInDatabase
+ * flags the controller branches on (create vs update), and populates the
+ * id when the resource exists.
+ */
+import { clone } from "@bufbuild/protobuf";
+import type { DescMessage, MessageShape } from "@bufbuild/protobuf";
+
+import type { Store } from "../../store/interface.js";
+import type { PipelineStep } from "../pipeline.js";
+import type { RequestContext } from "../request-context.js";
+import { findResourceBySlug } from "./helpers.js";
+import { EXISTING_RESOURCE_KEY } from "./load-existing.js";
+import { metadataOf } from "./shapes.js";
+
+/** Context keys (Go ExistsInDatabaseKey / ShouldCreateKey). */
+export const EXISTS_IN_DATABASE_KEY = "existsInDatabase";
+export const SHOULD_CREATE_KEY = "shouldCreate";
+
+export function newLoadForApplyStep<Desc extends DescMessage>(
+  store: Store,
+): PipelineStep<Desc> {
+  return {
+    name: "LoadForApply",
+    async execute(ctx: RequestContext<Desc>): Promise<void> {
+      const metadata = metadataOf(ctx.newState);
+      // No metadata or no slug (ResolveSlug should have run) → create.
+      if (metadata === undefined || metadata.slug === "") {
+        ctx.set(EXISTS_IN_DATABASE_KEY, false);
+        ctx.set(SHOULD_CREATE_KEY, true);
+        return;
+      }
+
+      const existing = await findResourceBySlug(
+        store,
+        ctx.apiResourceKind,
+        ctx.schema,
+        metadata.slug,
+        metadata.org,
+      );
+
+      if (existing === undefined) {
+        ctx.set(EXISTS_IN_DATABASE_KEY, false);
+        ctx.set(SHOULD_CREATE_KEY, true);
+        return;
+      }
+
+      ctx.set(EXISTING_RESOURCE_KEY, existing);
+      ctx.set(EXISTS_IN_DATABASE_KEY, true);
+      ctx.set(SHOULD_CREATE_KEY, false);
+      if (metadata.id === "") {
+        metadata.id = metadataOf(existing)?.id ?? "";
+      }
+    },
+  };
+}
+
+/**
+ * The apply update-arm delegation message: the ORIGINAL request (the Go
+ * pin — never the pipeline's mutated clone) with ONLY the resolved id
+ * copied on. Apply requests identify by name+org, not id, so without
+ * this the delegated update chain's Authorize step checks an EMPTY
+ * resource id — the permissive OSS default never noticed, but a real
+ * Authorizer (the cloud edition) must check the true target, exactly as
+ * the Java edition's post-load authorize order does (C2, 20260827.10).
+ * OSS wire behavior is unchanged: the update chain re-resolves and
+ * loads by slug regardless, and the rosters pin the byte-identity.
+ */
+export function withResolvedApplyId<Desc extends DescMessage>(
+  schema: Desc,
+  original: MessageShape<Desc>,
+  resolved: RequestContext<Desc>,
+): MessageShape<Desc> {
+  const enriched = clone(schema, original);
+  const metadata = metadataOf(enriched);
+  const resolvedId = metadataOf(resolved.newState)?.id ?? "";
+  if (metadata !== undefined && metadata.id === "" && resolvedId !== "") {
+    metadata.id = resolvedId;
+  }
+  return enriched;
+}

package/src/pipeline/steps/load-target.ts

@@ -0,0 +1,56 @@
+/**
+ * LoadTarget — ports steps/load_target.go. Get's loader for ID-wrapper
+ * inputs (OrganizationId, AgentId, …): loads by id into the
+ * TargetResource context key; NotFound when absent.
+ *
+ * Deliberate divergence from the Go source (ratified 2026-08-26): Go
+ * mapped ANY store error to NotFound — a locked file or corrupted page
+ * presented as a missing resource, inviting clients to discard real
+ * state. Here only the store's typed ResourceNotFoundError is NotFound;
+ * anything else rethrows, and the pipeline executor answers a sanitized
+ * Internal (see pipeline.ts). The idiom applies at every store-read site
+ * (guidelines §Errors).
+ */
+import type { DescMessage, MessageShape } from "@bufbuild/protobuf";
+
+import { ResourceNotFoundError } from "../../store/interface.js";
+import type { Store } from "../../store/interface.js";
+import { getKindName } from "../apiresource-meta.js";
+import { invalidArgumentError, notFoundError } from "../errors.js";
+import type { PipelineStep } from "../pipeline.js";
+import type { RequestContext } from "../request-context.js";
+import { idValueOf } from "./shapes.js";
+
+/** Context key for the loaded target (Go TargetResourceKey). */
+export const TARGET_RESOURCE_KEY = "targetResource";
+
+export function newLoadTargetStep<
+  InputDesc extends DescMessage,
+  TargetDesc extends DescMessage,
+>(store: Store, targetSchema: TargetDesc): PipelineStep<InputDesc> {
+  return {
+    name: "LoadTarget",
+    async execute(ctx: RequestContext<InputDesc>): Promise<void> {
+      const resourceId = idValueOf(ctx.input);
+      if (resourceId === "") {
+        throw invalidArgumentError("resource id is required");
+      }
+
+      let target: MessageShape<TargetDesc>;
+      try {
+        target = await store.getResource(
+          ctx.apiResourceKind,
+          resourceId,
+          targetSchema,
+        );
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          throw notFoundError(getKindName(ctx.apiResourceKind), resourceId);
+        }
+        throw error;
+      }
+
+      ctx.set(TARGET_RESOURCE_KEY, target);
+    },
+  };
+}