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

package/src/pipeline/steps/__tests__/guard-memory-capture.test.ts

@@ -179,9 +179,7 @@ describe("GuardMemoryCapture with the capability composed", () => {
 
 describe("GuardMemoryCapture without the capability (the pre-seam gate)", () => {
   it("admits trusted-local and OIDC callers", () => {
-    const step = newGuardMemoryCaptureStep<typeof MemorySchema>(
-      providerWith(),
-    );
+    const step = newGuardMemoryCaptureStep<typeof MemorySchema>(providerWith());
     step.execute(memoryCtx(LOCAL_USER));
     step.execute(
       memoryCtx({
@@ -194,9 +192,7 @@ describe("GuardMemoryCapture without the capability (the pre-seam gate)", () =>
   });
 
   it("refuses machine callers and platform_client_id carriers", () => {
-    const step = newGuardMemoryCaptureStep<typeof MemorySchema>(
-      providerWith(),
-    );
+    const step = newGuardMemoryCaptureStep<typeof MemorySchema>(providerWith());
     expect(() =>
       step.execute(memoryCtx({ ...LOCAL_USER, callerClass: "machine" })),
     ).toThrowError(MEMORY_CAPTURE_CALLER_MESSAGE);
@@ -214,9 +210,7 @@ describe("GuardMemoryCapture without the capability (the pre-seam gate)", () =>
     // With no capability composed the gate cannot classify runner
     // credentials — the single-user OSS posture admits them (the #564
     // narrowing is CLOUD policy, shipped in the cloud capability).
-    const step = newGuardMemoryCaptureStep<typeof MemorySchema>(
-      providerWith(),
-    );
+    const step = newGuardMemoryCaptureStep<typeof MemorySchema>(providerWith());
     step.execute(memoryCtx(SANDBOX_CALLER));
   });
 });

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/authorization-tuples.ts

@@ -78,7 +78,7 @@ import type { PipelineStep } from "../pipeline.js";
 import type { RequestContext } from "../request-context.js";
 import { EXISTING_RESOURCE_KEY } from "./load-existing.js";
 import type { HasMetadataShape } from "./shapes.js";
-import { metadataOf } from "./shapes.js";
+import { metadataOf, parentIdOf } from "./shapes.js";
 
 // ---------------------------------------------------------------------------
 // Visibility shape policy — the reconciler's level→shape mapping, ported
@@ -156,40 +156,19 @@ export function diffVisibilityShapes(
 }
 
 // ---------------------------------------------------------------------------
-// Parent-id resolution — the ParentIdExtractorRegistry port. Zero
-// hardcoded kind knowledge: the proto config names the spec field, this
-// module reads it structurally (protobuf-es spec messages are plain
-// objects whose properties are the camelCase proto field names).
+// Parent-id resolution — the ParentIdExtractorRegistry port. The spec-field
+// read itself is shapes.ts's `parentIdOf`, shared with the list read scope
+// (20260913.04 T04) so the id a tuple is written with and the id the scope
+// asks about are one read. This module adds the create-time rule: a
+// missing parent fails the request.
 // ---------------------------------------------------------------------------
 
-/** proto snake_case field name → the generated property name. */
-function camelCaseFieldName(specField: string): string {
-  return specField.replace(/_([a-z0-9])/g, (_, ch: string) => ch.toUpperCase());
-}
-
-/**
- * Extracts the parent id named by the config from the resource's spec.
- * Returns "" for every miss (no spec, no field, non-string value) — the
- * caller decides whether that is fatal, exactly as Java's registry
- * returns null and the service throws.
- */
-function extractParentId(resource: Message, specField: string): string {
-  // Structural access is the shapes.ts idiom: spec messages are plain
-  // objects; the property name is the camelCase form of the proto field.
-  const spec = (resource as unknown as { spec?: Record<string, unknown> }).spec;
-  if (spec === undefined) {
-    return "";
-  }
-  const value = spec[camelCaseFieldName(specField)];
-  return typeof value === "string" ? value : "";
-}
-
 function resolveParentLink(
   kind: ApiResourceKind,
   resource: Message,
   parentConfig: ParentRelationConfig,
 ): ResolvedParentLink {
-  const parentId = extractParentId(resource, parentConfig.specField);
+  const parentId = parentIdOf(resource, parentConfig.specField);
   if (parentId === "") {
     // Java: "Parent ID required for X but not found" → the request fails.
     throw internalError(

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;