@stigmer/server 3.15.3-dev.20260914121148 → 3.15.3-dev.20260916211208

package/src/pipeline/steps/__tests__/guard-plugin-managed.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Pins the plugin-managed write guard's two-fact decision: a stored
+ * resource labelled with an EXISTING plugin's id refuses a client write
+ * with FAILED_PRECONDITION naming the plugin; a label whose plugin is gone
+ * locks nothing; an unlabelled resource passes; in-process and internal
+ * callers pass by structure; the request's own labels are never consulted;
+ * and the step reads the context key the chain names.
+ */
+import { describe, expect, it } from "vitest";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { create } from "@bufbuild/protobuf";
+
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { PluginSchema } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import type { CallerIdentity } from "../../../extensions/identity.js";
+import { PLUGIN_LABEL } from "../../apiresource-labels.js";
+import { RequestContext } from "../../request-context.js";
+import { ResourceNotFoundError } from "../../../store/interface.js";
+import type { Store } from "../../../store/interface.js";
+import { newGuardPluginManagedStep } from "../guard-plugin-managed.js";
+import { EXISTING_RESOURCE_KEY } from "../load-existing.js";
+
+const USER: CallerIdentity = {
+  identityId: "ida_alice",
+  callerClass: "user",
+  issuer: "stigmer",
+  rawToken: "tok",
+};
+const IN_PROCESS: CallerIdentity = { ...USER, origin: "in-process" };
+const INTERNAL: CallerIdentity = { ...USER, callerClass: "internal" };
+
+/** A store that knows one plugin row; everything else is not found. */
+function storeWith(pluginId: string | undefined): Store {
+  return {
+    getResource: (kind: ApiResourceKind, id: string) => {
+      if (kind === ApiResourceKind.plugin && id === pluginId) {
+        return Promise.resolve(
+          create(PluginSchema, { metadata: { id, slug: "thermos" } }),
+        );
+      }
+      return Promise.reject(
+        new ResourceNotFoundError(`${ApiResourceKind[kind]}/${id}`),
+      );
+    },
+  } as unknown as Store;
+}
+
+function ctxWithStored(
+  labels: Record<string, string>,
+  caller: CallerIdentity,
+  key = EXISTING_RESOURCE_KEY,
+) {
+  const ctx = new RequestContext(
+    AgentSchema,
+    // The REQUEST carries no plugin label: the guard must not read it.
+    create(AgentSchema, { metadata: { name: "reviewer", labels: {} } }),
+    caller,
+    ApiResourceKind.agent,
+  );
+  ctx.set(
+    key,
+    create(AgentSchema, {
+      metadata: { name: "reviewer", slug: "reviewer", labels },
+    }),
+  );
+  return ctx;
+}
+
+async function outcome(
+  promise: Promise<void> | void,
+): Promise<ConnectError | undefined> {
+  try {
+    await promise;
+    return undefined;
+  } catch (error) {
+    return error as ConnectError;
+  }
+}
+
+describe("GuardPluginManaged", () => {
+  it("refuses a client write to a member whose plugin exists, naming the plugin", async () => {
+    const step = newGuardPluginManagedStep<typeof AgentSchema>(
+      storeWith("plg_1"),
+    );
+    const error = await outcome(
+      step.execute(ctxWithStored({ [PLUGIN_LABEL]: "plg_1" }, USER)),
+    );
+    expect(error).toBeInstanceOf(ConnectError);
+    expect(error?.code).toBe(Code.FailedPrecondition);
+    expect(error?.rawMessage).toBe(
+      "agent 'reviewer' is managed by plugin 'thermos'; change the plugin and push it again, or compose your own agent over it",
+    );
+  });
+
+  it("locks nothing when the labelled plugin is gone", async () => {
+    const step = newGuardPluginManagedStep<typeof AgentSchema>(
+      storeWith(undefined),
+    );
+    expect(
+      await outcome(
+        step.execute(ctxWithStored({ [PLUGIN_LABEL]: "plg_gone" }, USER)),
+      ),
+    ).toBeUndefined();
+  });
+
+  it("passes an unlabelled resource without touching the store", async () => {
+    const step = newGuardPluginManagedStep<typeof AgentSchema>({
+      getResource: () => Promise.reject(new Error("must not be called")),
+    } as unknown as Store);
+    expect(
+      await outcome(step.execute(ctxWithStored({ team: "x" }, USER))),
+    ).toBeUndefined();
+  });
+
+  it("passes in-process and internal callers by structure", async () => {
+    const step = newGuardPluginManagedStep<typeof AgentSchema>(
+      storeWith("plg_1"),
+    );
+    expect(
+      await outcome(
+        step.execute(ctxWithStored({ [PLUGIN_LABEL]: "plg_1" }, IN_PROCESS)),
+      ),
+    ).toBeUndefined();
+    expect(
+      await outcome(
+        step.execute(ctxWithStored({ [PLUGIN_LABEL]: "plg_1" }, INTERNAL)),
+      ),
+    ).toBeUndefined();
+  });
+
+  it("reads the stored resource from the key the chain names", async () => {
+    const step = newGuardPluginManagedStep<typeof AgentSchema>(
+      storeWith("plg_1"),
+      { existingKey: "customKey" },
+    );
+    const error = await outcome(
+      step.execute(
+        ctxWithStored({ [PLUGIN_LABEL]: "plg_1" }, USER, "customKey"),
+      ),
+    );
+    expect(error?.code).toBe(Code.FailedPrecondition);
+    // Under the default key nothing is loaded, so nothing is refused.
+    expect(
+      await outcome(
+        step.execute(ctxWithStored({ [PLUGIN_LABEL]: "plg_1" }, USER)),
+      ),
+    ).toBeUndefined();
+  });
+});

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

@@ -11,7 +11,9 @@ import { describe, expect, it } from "vitest";
 import { Code, ConnectError } from "@connectrpc/connect";
 import { create } from "@bufbuild/protobuf";
 
+import type { Message } from "@bufbuild/protobuf";
 import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { PushSkillRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
 import { EnvironmentSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
 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";
@@ -74,6 +76,75 @@ describe("reservedLabelMutations", () => {
   });
 });
 
+describe("GuardReservedLabels on a push-shaped chain (named positions)", () => {
+  // Skill push builds its resource from an artifact and rides SKILL_KEY /
+  // EXISTING_SKILL_KEY rather than newState / EXISTING_RESOURCE_KEY; the
+  // positions parameter points the guard at them. Pins that a reserved
+  // introduction on the BUILT resource is judged (the request itself has
+  // no metadata), that a stored echo under the named existing key passes,
+  // and that the in-process origin passes by structure.
+  const BUILT_KEY = "builtResource";
+  const STORED_KEY = "storedResource";
+  function pushCtx(
+    labels: Record<string, string>,
+    stored?: Record<string, string>,
+    caller: CallerIdentity = USER,
+  ) {
+    const ctx = new RequestContext(
+      PushSkillRequestSchema,
+      create(PushSkillRequestSchema, {
+        org: "acme",
+        artifact: new Uint8Array(1),
+        labels,
+      }),
+      caller,
+      ApiResourceKind.skill,
+    );
+    ctx.set(
+      BUILT_KEY,
+      create(AgentSchema, { metadata: { name: "s", labels } }),
+    );
+    if (stored !== undefined) {
+      ctx.set(
+        STORED_KEY,
+        create(AgentSchema, { metadata: { name: "s", labels: stored } }),
+      );
+    }
+    return ctx;
+  }
+  const positioned = (authorizer: Authorizer) =>
+    newGuardReservedLabelsStep<typeof PushSkillRequestSchema>(authorizer, {
+      stateOf: (ctx) => ctx.get(BUILT_KEY) as Message,
+      existingKey: STORED_KEY,
+    });
+
+  it("rejects a reserved introduction read from the named state", async () => {
+    const error = await positioned(denying())
+      .execute(pushCtx({ "stigmer.ai/plugin": "plg_1" }))
+      ?.catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(ConnectError);
+    expect((error as ConnectError).code).toBe(Code.InvalidArgument);
+  });
+
+  it("passes an echo of the label stored under the named existing key", async () => {
+    await positioned(denying()).execute(
+      pushCtx(
+        { "stigmer.ai/plugin": "plg_1" },
+        { "stigmer.ai/plugin": "plg_1" },
+      ),
+    );
+  });
+
+  it("passes the in-process origin by structure", async () => {
+    await positioned(denying()).execute(
+      pushCtx({ "stigmer.ai/plugin": "plg_1" }, undefined, {
+        ...USER,
+        origin: "in-process",
+      }),
+    );
+  });
+});
+
 describe("GuardReservedLabels", () => {
   it("rejects an introduction with the byte-pinned copy when denied", async () => {
     const step = newGuardReservedLabelsStep<typeof AgentSchema>(denying());
@@ -133,9 +204,8 @@ describe("GuardReservedLabels", () => {
   });
 
   it("the Environment personal-label client contract passes", async () => {
-    const step = newGuardReservedLabelsStep<typeof EnvironmentSchema>(
-      denying(),
-    );
+    const step =
+      newGuardReservedLabelsStep<typeof EnvironmentSchema>(denying());
     const ctx = new RequestContext(
       EnvironmentSchema,
       create(EnvironmentSchema, {
@@ -151,7 +221,12 @@ describe("GuardReservedLabels", () => {
     const step = newGuardReservedLabelsStep<typeof AgentSchema>(denying());
     const ctx = agentCtx(
       { "stigmer.ai/default-instance": "true" },
-      { identityId: "internal", callerClass: "internal", issuer: "", rawToken: "" },
+      {
+        identityId: "internal",
+        callerClass: "internal",
+        issuer: "",
+        rawToken: "",
+      },
     );
     await expect(Promise.resolve(step.execute(ctx))).resolves.toBeUndefined();
   });
@@ -166,7 +241,9 @@ describe("GuardReservedLabels", () => {
       vouched,
       "stigmer.ai/workflow-execution-id",
     );
-    await expect(Promise.resolve(step.execute(vouched))).resolves.toBeUndefined();
+    await expect(
+      Promise.resolve(step.execute(vouched)),
+    ).resolves.toBeUndefined();
 
     const smuggled = agentCtx({
       "stigmer.ai/workflow-execution-id": "wfe_1",
@@ -176,9 +253,7 @@ describe("GuardReservedLabels", () => {
       smuggled,
       "stigmer.ai/workflow-execution-id",
     );
-    const error = await step
-      .execute(smuggled)
-      ?.catch((e: unknown) => e);
+    const error = await step.execute(smuggled)?.catch((e: unknown) => e);
     expect(error).toBeInstanceOf(ConnectError);
     expect((error as ConnectError).rawMessage).toContain(
       "stigmer.ai/default-agent",

package/src/pipeline/steps/authorization-facts.ts

@@ -0,0 +1,131 @@
+/**
+ * The facts a stored row's authorization tuples derive from, read back
+ * from the row (`RowAuthorizationFacts`, extensions/resource-authorization.ts)
+ * — the read-time twin of the tuple lifecycle's create-time resolution in
+ * authorization-tuples.ts, and deliberately not that function: the
+ * create-time one throws when a row is missing its organization or its
+ * parent (a create must not half-succeed), while a row read back years
+ * later is a fact, missing pieces included — an empty organization
+ * resolves `admin from organization` to nobody, it does not fault a read.
+ * The two cannot drift unnoticed: src/authorization/__tests__/facts.test.ts
+ * pins that a well-formed row resolves to the same links through both.
+ *
+ * Two readers share this one resolver, which is the reason it is a leaf
+ * of its own: the list lanes' shared helper (extensions/list-read-scope.ts)
+ * builds every candidate's `ListEntryMeta` through it, and the built-in
+ * authorizer (src/authorization/facts.ts) derives a loaded row's tuples
+ * through it. It imports the two pure leaves it needs (apiresource-meta,
+ * shapes) and the protos, and nothing else, so the seam may import it by
+ * value without a cycle — the third such leaf, beside those two.
+ *
+ * Every read is structural (shapes.ts's own premise: protobuf-es messages
+ * are plain objects sharing the generated metadata and audit types), so
+ * the resolver needs no schema — a list lane holds decoded rows of a kind
+ * it names, not their descriptors.
+ */
+import { AuthorizationScopeType } 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 { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import type { ApiResourceAudit } from "@stigmer/protos/ai/stigmer/commons/apiresource/status_pb";
+
+import type {
+  ResolvedParentLink,
+  RowAuthorizationFacts,
+} from "../../extensions/resource-authorization.js";
+import { getKindEnum, getKindMeta } from "../apiresource-meta.js";
+import { parentIdOf } from "./shapes.js";
+import type { HasMetadataShape } from "./shapes.js";
+
+/** The one path every stored API resource keeps its audit under. */
+interface HasAuditShape {
+  status?: { audit?: ApiResourceAudit };
+}
+
+/** The row's facts, read structurally; every absence is the empty value, never a throw. */
+export function rowAuthorizationFactsOf(
+  kind: ApiResourceKind,
+  resource: object,
+): RowAuthorizationFacts {
+  const metadata = (resource as HasMetadataShape).metadata;
+  const org = metadata?.org ?? "";
+  return {
+    id: metadata?.id ?? "",
+    org,
+    visibility:
+      metadata?.visibility ??
+      ApiResourceVisibility.api_resource_visibility_unspecified,
+    createdBy: createdByOf(resource),
+    parentLinks: parentLinksOf(kind, resource, org),
+  };
+}
+
+/** `status.audit.spec_audit.created_by.id` as stamped — "" when any link is absent. */
+export function createdByOf(resource: object): string {
+  return (
+    (resource as HasAuditShape).status?.audit?.specAudit?.createdBy?.id ?? ""
+  );
+}
+
+/**
+ * The scope link and every configured additional parent the row names, in
+ * the tuple lifecycle's order. A parent the row does not name is left out.
+ */
+export function parentLinksOf(
+  kind: ApiResourceKind,
+  resource: object,
+  org: string,
+): ReadonlyArray<ResolvedParentLink> {
+  const config = getKindMeta(kind).authorization;
+  if (config === undefined) {
+    return [];
+  }
+  const links: ResolvedParentLink[] = [];
+  switch (config.scopeType) {
+    case AuthorizationScopeType.ORGANIZATION:
+      if (org !== "") {
+        links.push({
+          relation: "organization",
+          parentKind: getKindEnum("organization"),
+          parentId: org,
+        });
+      }
+      break;
+    case AuthorizationScopeType.PARENT:
+      if (config.parent !== undefined) {
+        pushLink(links, resource, config.parent);
+      }
+      break;
+    case AuthorizationScopeType.OWNER_ONLY:
+    case AuthorizationScopeType.PLATFORM:
+    case AuthorizationScopeType.NONE:
+    case AuthorizationScopeType.UNSPECIFIED:
+      // No scope link: OWNER_ONLY by design; PLATFORM is dead config in
+      // both editions (the lifecycle warns and writes none); NONE and
+      // UNSPECIFIED are kinds outside the model.
+      break;
+    default: {
+      const exhaustive: never = config.scopeType;
+      throw new Error(`unknown scope type: ${String(exhaustive)}`);
+    }
+  }
+  for (const parent of config.additionalParents) {
+    pushLink(links, resource, parent);
+  }
+  return links;
+}
+
+function pushLink(
+  links: ResolvedParentLink[],
+  resource: object,
+  parent: ParentRelationConfig,
+): void {
+  const parentId = parentIdOf(resource, parent.specField);
+  if (parentId !== "") {
+    links.push({
+      relation: parent.relation,
+      parentKind: getKindEnum(parent.kind),
+      parentId,
+    });
+  }
+}

package/src/pipeline/steps/delete.ts

@@ -15,7 +15,11 @@ 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 {
+  internalError,
+  invalidArgumentError,
+  notFoundError,
+} from "../errors.js";
 import type { PipelineStep } from "../pipeline.js";
 import type { RequestContext } from "../request-context.js";
 import { EXISTING_RESOURCE_KEY } from "./load-existing.js";
@@ -24,7 +28,9 @@ import { idValueOf } from "./shapes.js";
 /** Context key for the extracted id (Go ResourceIdKey). */
 export const RESOURCE_ID_KEY = "resourceId";
 
-export function newExtractResourceIdStep<Desc extends DescMessage>(): PipelineStep<Desc> {
+export function newExtractResourceIdStep<
+  Desc extends DescMessage,
+>(): PipelineStep<Desc> {
   return {
     name: "ExtractResourceId",
     execute(ctx: RequestContext<Desc>): void {
@@ -90,7 +96,9 @@ function requireResourceId<Desc extends DescMessage>(
   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)"),
+      new Error(
+        "resource id not found in context (ExtractResourceId must run first)",
+      ),
       "delete pipeline ordering",
     );
   }

package/src/pipeline/steps/duplicate.ts

@@ -24,10 +24,16 @@ export function newCheckDuplicateStep<Desc extends DescMessage>(
       const metadata = metadataOf(ctx.newState);
       if (metadata === undefined) {
         // Established by earlier steps — a server-side programming error.
-        throw internalError(new Error("resource metadata is nil"), "duplicate check");
+        throw internalError(
+          new Error("resource metadata is nil"),
+          "duplicate check",
+        );
       }
       if (metadata.slug === "") {
-        throw internalError(new Error("resource slug is empty"), "duplicate check");
+        throw internalError(
+          new Error("resource slug is empty"),
+          "duplicate check",
+        );
       }
 
       let existing;

package/src/pipeline/steps/guard-plugin-managed.ts

@@ -0,0 +1,133 @@
+/**
+ * GuardPluginManaged — the write boundary for resources a plugin
+ * materialised. A plugin's skills, MCP servers, agent and workflows are
+ * ordinary resources in the organization, labelled `stigmer.ai/plugin:
+ * <plugin id>` by the controller that installed them; the plugin owns
+ * their definition, so a client edit would be silently overwritten by the
+ * next upgrade and a client delete would leave the plugin claiming a
+ * member it no longer has. Customisation is composition: the user writes
+ * their own agent over the plugin's skills and servers, which stay readable
+ * and usable by everyone the visibility admits.
+ *
+ * Two facts decide, together (the apiresource-labels.ts doctrine: a label
+ * restricts only beside server-owned state):
+ *   - the STORED resource carries the plugin label — the request's labels
+ *     are never consulted, so a client cannot detach a child by omitting
+ *     the label on an update;
+ *   - AND the plugin row it names exists. A label whose plugin is gone (a
+ *     cascade that failed part-way; a label a self-hosted operator stamped
+ *     by hand under the permissive authorizer) leaves the resource editable
+ *     and deletable, so nothing can be locked forever.
+ *
+ * Server-composed writes pass by structure: the plugin controller is the
+ * one writer of these resources and rides the in-process lane as the
+ * installing caller (`origin: "in-process"`), exactly the arm
+ * GuardReservedLabels passes. Operational RPCs (connect, OAuth flows,
+ * instances, sessions, executions) never splice this step: they read or
+ * enrich a server, they do not redefine it.
+ *
+ * Placement: after the chain's load of the stored resource (LoadExisting,
+ * LoadExistingForDelete, a kind's visibility loader, skill push's
+ * FindExistingBySlug), before any state is built or persisted. The
+ * refusal is FAILED_PRECONDITION with the plugin named, so the user knows
+ * which door to use instead.
+ *
+ * Proven by __tests__/guard-plugin-managed.test.ts and the plugin
+ * conformance suite's managed-child arms.
+ */
+import { Code, ConnectError } from "@connectrpc/connect";
+import type { DescMessage, Message } from "@bufbuild/protobuf";
+
+import { PluginSchema } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { pluginIdOf } from "../apiresource-labels.js";
+import { internalError } from "../errors.js";
+import type { PipelineStep } from "../pipeline.js";
+import type { RequestContext } from "../request-context.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
+import type { Store } from "../../store/interface.js";
+import { EXISTING_RESOURCE_KEY } from "./load-existing.js";
+import { metadataOf } from "./shapes.js";
+
+/** The kinds a plugin materialises; the noun opens the refusal sentence. */
+const MANAGED_KIND_NOUNS: ReadonlyMap<ApiResourceKind, string> = new Map([
+  [ApiResourceKind.skill, "skill"],
+  [ApiResourceKind.mcp_server, "MCP server"],
+  [ApiResourceKind.agent, "agent"],
+  [ApiResourceKind.workflow, "workflow"],
+]);
+
+/** The one sentence a refused mutation carries; the CLI and console render it as is. */
+export function pluginManagedRefusal(
+  kind: ApiResourceKind,
+  slug: string,
+  pluginSlug: string,
+): string {
+  const noun =
+    MANAGED_KIND_NOUNS.get(kind) ?? ApiResourceKind[kind] ?? String(kind);
+  return (
+    `${noun} '${slug}' is managed by plugin '${pluginSlug}'; change the plugin and ` +
+    "push it again, or compose your own agent over it"
+  );
+}
+
+export interface GuardPluginManagedPositions {
+  /** The context key the stored resource rides; defaults to EXISTING_RESOURCE_KEY. */
+  readonly existingKey?: string;
+}
+
+export function newGuardPluginManagedStep<Desc extends DescMessage>(
+  store: Store,
+  positions: GuardPluginManagedPositions = {},
+): PipelineStep<Desc> {
+  const existingKey = positions.existingKey ?? EXISTING_RESOURCE_KEY;
+  return {
+    name: "GuardPluginManaged",
+    async execute(ctx: RequestContext<Desc>): Promise<void> {
+      if (
+        ctx.callerIdentity.callerClass === "internal" ||
+        ctx.callerIdentity.origin === "in-process"
+      ) {
+        // The plugin controller's own materialisation, upgrade and cascade
+        // writes; the same structural pass GuardReservedLabels takes.
+        return;
+      }
+      const existing = ctx.get(existingKey);
+      if (existing === undefined) {
+        return;
+      }
+      const metadata = metadataOf(existing as Message);
+      const pluginId = pluginIdOf(metadata);
+      if (pluginId === undefined) {
+        return;
+      }
+
+      let pluginSlug: string;
+      try {
+        const plugin = await store.getResource(
+          ApiResourceKind.plugin,
+          pluginId,
+          PluginSchema,
+        );
+        pluginSlug = plugin.metadata?.slug ?? pluginId;
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          // A dangling label locks nothing: the plugin that would own this
+          // resource is gone, so the resource is the user's again.
+          return;
+        }
+        throw internalError(error, "plugin ownership could not be checked");
+      }
+
+      throw new ConnectError(
+        pluginManagedRefusal(
+          ctx.apiResourceKind,
+          metadata?.slug ?? "",
+          pluginSlug,
+        ),
+        Code.FailedPrecondition,
+      );
+    },
+  };
+}

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

@@ -40,12 +40,15 @@
  *
  * 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
+ * labels for echo detection. A push-shaped chain (skill push, whose
+ * PushSkillRequest carries `labels`) places it after its populate step and
+ * names its own positions (GuardReservedLabelsPositions), since its
+ * resource rides a domain key, not newState. 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 type { DescMessage, Message } 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";
@@ -69,9 +72,7 @@ export const RESERVED_LABEL_PREFIX = "stigmer.ai/";
 const CLIENT_CONTRACT_ALLOWLIST: ReadonlyMap<
   ApiResourceKind,
   ReadonlySet<string>
-> = new Map([
-  [ApiResourceKind.environment, new Set(["stigmer.ai/personal"])],
-]);
+> = new Map([[ApiResourceKind.environment, new Set(["stigmer.ai/personal"])]]);
 
 /**
  * The reserved keys `requested` would introduce or change relative to
@@ -91,9 +92,27 @@ export function reservedLabelMutations(
   return mutations.sort();
 }
 
+/**
+ * Where the guard finds the state that will persist and the stored state
+ * it is judged against. The create and update chains carry both in the
+ * shared positions (`ctx.newState`, EXISTING_RESOURCE_KEY); a push-shaped
+ * chain builds its resource from an artifact and rides its own keys, so
+ * it names them here. Defaults are the shared positions.
+ */
+export interface GuardReservedLabelsPositions<Desc extends DescMessage> {
+  /** The resource about to persist; defaults to the chain's newState. */
+  readonly stateOf?: (ctx: RequestContext<Desc>) => Message | undefined;
+  /** The context key the stored resource rides; defaults to EXISTING_RESOURCE_KEY. */
+  readonly existingKey?: string;
+}
+
 export function newGuardReservedLabelsStep<Desc extends DescMessage>(
   authorizer: Authorizer,
+  positions: GuardReservedLabelsPositions<Desc> = {},
 ): PipelineStep<Desc> {
+  const stateOf =
+    positions.stateOf ?? ((ctx: RequestContext<Desc>) => ctx.newState);
+  const existingKey = positions.existingKey ?? EXISTING_RESOURCE_KEY;
   return {
     name: "GuardReservedLabels",
     async execute(ctx: RequestContext<Desc>): Promise<void> {
@@ -108,12 +127,14 @@ export function newGuardReservedLabelsStep<Desc extends DescMessage>(
         // identity for attribution (ruling R5).
         return;
       }
-      const requested = metadataOf(ctx.newState)?.labels ?? {};
-      const existing = ctx.get(EXISTING_RESOURCE_KEY);
+      const state = stateOf(ctx);
+      const requested =
+        state === undefined ? {} : (metadataOf(state)?.labels ?? {});
+      const existing = ctx.get(existingKey);
       const stored =
         existing === undefined
           ? {}
-          : (metadataOf(existing as typeof ctx.newState)?.labels ?? {});
+          : (metadataOf(existing as Message)?.labels ?? {});
 
       const allowlist =
         CLIENT_CONTRACT_ALLOWLIST.get(ctx.apiResourceKind) ?? new Set();