@stigmer/server 3.14.0 → 3.14.1

package/src/domain/session/__tests__/run-gate.test.ts

@@ -0,0 +1,219 @@
+/**
+ * Pins the run gate's SPLICE in session-create over the real router (P1
+ * sp.run-gate): the AuthorizeRunTarget step sits after
+ * ResolveDefaultAgentInstance and before Persist, so (1) a denied caller
+ * answers PERMISSION_DENIED with the domain's byte-pinned copy and leaves
+ * no session row; (2) the check names the instance the CHAIN resolved,
+ * not only the one the caller typed — the session-first shape (empty
+ * spec) is checked against the platform default agent's default instance;
+ * (3) an allowed caller creates the session exactly as before. The
+ * authorizer under test answers only run-gate checks (runGateOnlyAuthorizer),
+ * so every refusal here is the run gate's and nobody else's.
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import type { Client, Transport } from "@connectrpc/connect";
+import { Code, ConnectError, createClient } from "@connectrpc/connect";
+import { createGrpcTransport } from "@connectrpc/connect-node";
+
+import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/command_pb";
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentQueryController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/query_pb";
+import { SessionCommandController } from "@stigmer/protos/ai/stigmer/agentic/session/v1/command_pb";
+import { 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 { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+
+import { loadConfig } from "../../../boot/config.js";
+import { composeServer } from "../../../boot/compose.js";
+import type { ComposedServer } from "../../../boot/compose.js";
+import { createLogger } from "../../../boot/logger.js";
+import type { AuthzDecision } from "../../../extensions/authorizer.js";
+import { runGateOnlyAuthorizer } from "../../../pipeline/__tests__/support.js";
+import {
+  DEFAULT_AGENT_LABEL,
+  DEFAULT_AGENT_LABEL_VALUE,
+} from "../../agent/defaultagent.js";
+import { runAgentInstanceDeniedMessage } from "../constants.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const API_VERSION = "agentic.stigmer.ai/v1";
+const ORG = "acme";
+
+let dir: string;
+let server: ComposedServer;
+let decision: AuthzDecision = { kind: "allow" };
+const gate = runGateOnlyAuthorizer(() => decision);
+let agentCommand: Client<typeof AgentCommandController>;
+let agentQuery: Client<typeof AgentQueryController>;
+let sessionCommand: Client<typeof SessionCommandController>;
+
+beforeAll(async () => {
+  dir = mkdtempSync(path.join(tmpdir(), "session-run-gate-test-"));
+  server = await composeServer({
+    config: loadConfig({
+      STIGMER_MODEL_REGISTRY_REFRESH: "off",
+      TEMPORAL_HOST_PORT: "127.0.0.1:1",
+      DB_PATH: path.join(dir, "stigmer.db"),
+      STORAGE_PATH: path.join(dir, "storage"),
+      ARTIFACT_LOCAL_BASE_PATH: path.join(dir, "artifacts"),
+    }),
+    logger: silentLogger,
+    portOverride: 0,
+    host: "127.0.0.1",
+    extensions: [{ name: "run-gate-test", authorizer: gate.authorizer }],
+  });
+  const port = await server.start();
+  const transport: Transport = createGrpcTransport({
+    baseUrl: `http://127.0.0.1:${port}`,
+  });
+  agentCommand = createClient(AgentCommandController, transport);
+  agentQuery = createClient(AgentQueryController, transport);
+  sessionCommand = createClient(SessionCommandController, transport);
+});
+
+afterAll(async () => {
+  await server.shutdown();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+async function sessionCount(): Promise<number> {
+  return (await server.store.listResources(ApiResourceKind.session)).length;
+}
+
+async function createAgent(name: string): Promise<string> {
+  const agent = await agentCommand.create({
+    apiVersion: API_VERSION,
+    kind: "Agent",
+    metadata: { name, org: ORG },
+    spec: { instructions: "You are the agent the run-gate tests target." },
+  });
+  return agent.metadata!.id;
+}
+
+/** The default-agent label is operator-seeded state; stamp it on the row. */
+async function markDefaultAgent(agentId: string): Promise<void> {
+  const stored = await server.store.getResource(
+    ApiResourceKind.agent,
+    agentId,
+    AgentSchema,
+  );
+  stored.metadata!.labels[DEFAULT_AGENT_LABEL] = DEFAULT_AGENT_LABEL_VALUE;
+  stored.metadata!.visibility = ApiResourceVisibility.visibility_public;
+  await server.store.saveResource(
+    ApiResourceKind.agent,
+    agentId,
+    AgentSchema,
+    stored,
+  );
+}
+
+async function captureError(
+  run: () => Promise<unknown>,
+): Promise<ConnectError> {
+  try {
+    await run();
+  } catch (error) {
+    return ConnectError.from(error);
+  }
+  throw new Error("expected the create to reject");
+}
+
+describe("session-create run gate (composed server)", () => {
+  it("denies a caller-named instance with the pinned copy and persists nothing", async () => {
+    decision = { kind: "deny", reason: "" };
+    gate.runGateChecks.length = 0;
+    const before = await sessionCount();
+
+    const err = await captureError(() =>
+      sessionCommand.create({
+        apiVersion: API_VERSION,
+        kind: "Session",
+        metadata: { name: "Denied session", org: ORG },
+        spec: { agentInstanceId: "agi_01private" },
+      }),
+    );
+
+    expect(err.code).toBe(Code.PermissionDenied);
+    expect(err.rawMessage).toBe(runAgentInstanceDeniedMessage("agi_01private"));
+    expect(gate.runGateChecks).toEqual([
+      {
+        permission: IamPermission.can_execute,
+        resourceKind: ApiResourceKind.agent_instance,
+        resourceId: "agi_01private",
+      },
+    ]);
+    expect(await sessionCount(), "no row behind a denial").toBe(before);
+  });
+
+  it("checks the instance the chain RESOLVED for the session-first shape", async () => {
+    decision = { kind: "deny", reason: "" };
+    gate.runGateChecks.length = 0;
+    const agentId = await createAgent("Default agent for the run gate");
+    await markDefaultAgent(agentId);
+
+    const err = await captureError(() =>
+      sessionCommand.create({
+        apiVersion: API_VERSION,
+        kind: "Session",
+        metadata: { name: "Session-first", org: ORG },
+        spec: {},
+      }),
+    );
+
+    expect(err.code).toBe(Code.PermissionDenied);
+    // ResolveDefaultAgentInstance created (or found) the default agent's
+    // default instance BEFORE the gate — the inherited pre-gate side
+    // effect the slot table records — and the gate names exactly it.
+    const agent = await agentQuery.get({ value: agentId });
+    const resolvedInstanceId = agent.status?.defaultInstanceId ?? "";
+    expect(resolvedInstanceId).not.toBe("");
+    expect(gate.runGateChecks).toHaveLength(1);
+    expect(gate.runGateChecks[0].resourceId).toBe(resolvedInstanceId);
+    expect(err.rawMessage).toBe(
+      runAgentInstanceDeniedMessage(resolvedInstanceId),
+    );
+  });
+
+  it("not-found answers NOT_FOUND naming the instance (the stigmer#224 order)", async () => {
+    decision = { kind: "not-found" };
+    const err = await captureError(() =>
+      sessionCommand.create({
+        apiVersion: API_VERSION,
+        kind: "Session",
+        metadata: { name: "Missing instance", org: ORG },
+        spec: { agentInstanceId: "agi_01missing" },
+      }),
+    );
+    expect(err.code).toBe(Code.NotFound);
+    expect(err.rawMessage).toContain("agi_01missing");
+  });
+
+  it("an allowed caller creates the session exactly as before", async () => {
+    decision = { kind: "allow" };
+    gate.runGateChecks.length = 0;
+    const agentId = await createAgent("Allowed agent");
+    const agent = await agentQuery.get({ value: agentId });
+    const instanceId = agent.status?.defaultInstanceId ?? "";
+    expect(instanceId, "agent create seeds a default instance").not.toBe("");
+
+    const session = await sessionCommand.create({
+      apiVersion: API_VERSION,
+      kind: "Session",
+      metadata: { name: "Allowed session", org: ORG },
+      spec: { agentInstanceId: instanceId },
+    });
+
+    expect(session.metadata?.id).toMatch(/^ses_/);
+    expect(session.spec?.agentInstanceId).toBe(instanceId);
+    expect(gate.runGateChecks.map((c) => c.resourceId)).toEqual([instanceId]);
+  });
+});

package/src/domain/session/__tests__/run-target.test.ts

@@ -0,0 +1,43 @@
+/**
+ * Pins the session run-target resolver (P1 sp.run-gate): a session's run
+ * target is the agent instance it binds to — agent_instance#can_execute on
+ * spec.agent_instance_id, with the domain's byte-pinned deny copy — and a
+ * session with no instance yet has no target (ResolveDefaultAgentInstance
+ * guarantees one before the step runs; an empty id reaching the resolver
+ * is the guard's arm, not a check to make).
+ */
+import { describe, expect, it } from "vitest";
+import { create } from "@bufbuild/protobuf";
+
+import { SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/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";
+
+import { runAgentInstanceDeniedMessage } from "../constants.js";
+import { sessionRunTarget } from "../run-target.js";
+
+describe("sessionRunTarget", () => {
+  it("targets the bound agent instance with can_execute and the pinned copy", () => {
+    const target = sessionRunTarget(
+      create(SessionSchema, { spec: { agentInstanceId: "agi_01abc" } }),
+    );
+    expect(target).toEqual({
+      permission: IamPermission.can_execute,
+      resourceKind: ApiResourceKind.agent_instance,
+      resourceId: "agi_01abc",
+      deniedMessage: "unauthorized to run agent instance 'agi_01abc'",
+    });
+    expect(target?.deniedMessage).toBe(
+      runAgentInstanceDeniedMessage("agi_01abc"),
+    );
+  });
+
+  it("answers no target when the session names no instance", () => {
+    expect(sessionRunTarget(create(SessionSchema, {}))).toBeUndefined();
+    expect(
+      sessionRunTarget(
+        create(SessionSchema, { spec: { agentInstanceId: "" } }),
+      ),
+    ).toBeUndefined();
+  });
+});

package/src/domain/session/constants.ts

@@ -0,0 +1,17 @@
+/**
+ * Session byte-pinned wire copy — every string a client can observe from
+ * this domain that is not already a proto annotation's error_msg. Wire
+ * once merged: the conformance run-gate suite asserts these characters.
+ */
+
+/**
+ * The run gate's deny copy when a session names an agent instance the
+ * caller may not run (P1 sp.run-gate, ruling Q-RG-4). NEW copy quotes the
+ * handle single-quoted (the ratified 2026-08-26 quoting rule). Identical to
+ * the agent-execution domain's instance copy on purpose — one fact, one
+ * sentence — the ENGINE_UNAVAILABLE_MESSAGE precedent for cross-domain
+ * twins: each domain owns its constant, the twin is named here.
+ */
+export function runAgentInstanceDeniedMessage(agentInstanceId: string): string {
+  return `unauthorized to run agent instance '${agentInstanceId}'`;
+}

package/src/domain/session/controller.ts

@@ -55,6 +55,7 @@ import {
   authorizeDirect,
   newAuthorizeStep,
 } from "../../pipeline/steps/authorize.js";
+import { newAuthorizeRunTargetStep } from "../../pipeline/steps/authorize-run-target.js";
 import { newGuardReservedLabelsStep } from "../../pipeline/steps/guard-reserved-labels.js";
 import {
   newBuildNewStateStep,
@@ -97,6 +98,7 @@ import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import type { SandboxLane } from "../../sandbox/lane.js";
 import { deprovisionSessionSandboxBestEffort } from "../../sandbox/steps.js";
+import { sessionRunTarget } from "./run-target.js";
 import { sessionSearchExtractor } from "./search-extractor.js";
 import type { ListReadScope } from "../../extensions/list-read-scope.js";
 import {
@@ -179,6 +181,13 @@ function kindOf(ctx: HandlerContext): ApiResourceKind {
  * runs BEFORE ValidateProto: when agent_instance_id is omitted, the
  * resolution fills it in before validation sees the spec.
  *
+ * AuthorizeRunTarget (the run gate, P1 sp.run-gate) follows it directly:
+ * the first step after the instance the session binds to is known, so a
+ * caller who may not run that instance is refused before validation reads
+ * anything further and before any step the chain owns side-effects. The
+ * default-instance creation INSIDE the resolution step still precedes it —
+ * the inherited pre-gate side effect recorded below, unchanged here.
+ *
  * The pre-side-effect gate slot splices before Persist, after the last
  * pure step (O4 plan-gate ruling Q2, mirroring the Java baseline's
  * post-resolution gate position). The default-instance resolution above
@@ -212,6 +221,7 @@ async function createSession(
         deps.authorizationLifecycle,
       ),
     )
+    .addStep(newAuthorizeRunTargetStep(deps.authorizer, sessionRunTarget))
     .addStep(newValidateProtoStep())
     .addStep(newValidateVisibilityStep())
     .addStep(newResolveSlugStep())

package/src/domain/session/run-target.ts

@@ -0,0 +1,30 @@
+/**
+ * The session run-target resolver (P1 sp.run-gate): a session is a
+ * conversation bound to ONE agent instance, so its run target is that
+ * instance — agent_instance#can_execute on spec.agent_instance_id.
+ *
+ * Pure over the record being built. ResolveDefaultAgentInstance runs before
+ * the gate and guarantees the id (the caller's, or the platform default
+ * agent's default instance), so an empty id here is that step's own
+ * refusal already thrown, never a check to make. Read from newState, where
+ * the resolution writes — the same clone gotcha steps.ts records.
+ */
+import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+
+import {
+  RUN_GATE_CHECKS,
+  type RunTarget,
+} from "../../pipeline/steps/authorize-run-target.js";
+import { runAgentInstanceDeniedMessage } from "./constants.js";
+
+export function sessionRunTarget(session: Session): RunTarget | undefined {
+  const agentInstanceId = session.spec?.agentInstanceId ?? "";
+  if (agentInstanceId === "") {
+    return undefined;
+  }
+  return {
+    ...RUN_GATE_CHECKS.agentInstance,
+    resourceId: agentInstanceId,
+    deniedMessage: runAgentInstanceDeniedMessage(agentInstanceId),
+  };
+}

package/src/domain/workflowexecution/__tests__/run-gate.test.ts

@@ -0,0 +1,200 @@
+/**
+ * Pins the run gate's SPLICE in workflow-execution-create over the real
+ * router (P1 sp.run-gate): AuthorizeRunTarget sits after
+ * ValidateWorkflowOrInstance and BEFORE EnsureEngineAvailable and
+ * CreateDefaultInstanceIfNeeded (the chain's first side effect and its
+ * first store read). Pinned here: (1) each shape is checked against its
+ * own target with its own byte-pinned copy; (2) a denial leaves no
+ * execution row and reads nothing — a nonexistent workflow_id is DENIED,
+ * not NOT_FOUND, because the gate answers before the lookup; (3) the gate
+ * precedes the engine gate: an ALLOWED create on this engineless server
+ * answers the engine's UNAVAILABLE; (4) the shape-less request is still
+ * INVALID_ARGUMENT from ValidateWorkflowOrInstance, which runs first. The
+ * authorizer under test answers only run-gate checks.
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import type { Client, Transport } from "@connectrpc/connect";
+import { Code, ConnectError, createClient } from "@connectrpc/connect";
+import { createGrpcTransport } from "@connectrpc/connect-node";
+
+import { WorkflowExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/command_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";
+
+import { loadConfig } from "../../../boot/config.js";
+import { composeServer } from "../../../boot/compose.js";
+import type { ComposedServer } from "../../../boot/compose.js";
+import { createLogger } from "../../../boot/logger.js";
+import type { AuthzDecision } from "../../../extensions/authorizer.js";
+import { runGateOnlyAuthorizer } from "../../../pipeline/__tests__/support.js";
+import {
+  ENGINE_UNAVAILABLE_MESSAGE,
+  runWorkflowDeniedMessage,
+  runWorkflowInstanceDeniedMessage,
+} from "../constants.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const API_VERSION = "agentic.stigmer.ai/v1";
+const ORG = "acme";
+
+let dir: string;
+let server: ComposedServer;
+let decision: AuthzDecision = { kind: "allow" };
+const gate = runGateOnlyAuthorizer(() => decision);
+let command: Client<typeof WorkflowExecutionCommandController>;
+
+beforeAll(async () => {
+  dir = mkdtempSync(path.join(tmpdir(), "wfexec-run-gate-test-"));
+  vi.stubEnv("STIGMER_ENCRYPTION_KEY", Buffer.alloc(32, 7).toString("base64"));
+  vi.stubEnv(
+    "STIGMER_RUNNER_TOKEN_KEY",
+    Buffer.alloc(32, 8).toString("base64"),
+  );
+  server = await composeServer({
+    config: loadConfig({
+      STIGMER_MODEL_REGISTRY_REFRESH: "off",
+      TEMPORAL_HOST_PORT: "127.0.0.1:1",
+      DB_PATH: path.join(dir, "stigmer.db"),
+      ARTIFACT_LOCAL_BASE_PATH: path.join(dir, "artifacts"),
+    }),
+    logger: silentLogger,
+    portOverride: 0,
+    host: "127.0.0.1",
+    extensions: [{ name: "run-gate-test", authorizer: gate.authorizer }],
+  });
+  const port = await server.start();
+  const transport: Transport = createGrpcTransport({
+    baseUrl: `http://127.0.0.1:${port}`,
+  });
+  command = createClient(WorkflowExecutionCommandController, transport);
+});
+
+afterAll(async () => {
+  try {
+    await server?.shutdown();
+    rmSync(dir, { recursive: true, force: true });
+  } finally {
+    vi.unstubAllEnvs();
+  }
+});
+
+async function captureError(
+  run: () => Promise<unknown>,
+): Promise<ConnectError> {
+  try {
+    await run();
+  } catch (error) {
+    return ConnectError.from(error);
+  }
+  throw new Error("expected the create to reject");
+}
+
+function createInput(spec: {
+  workflowId?: string;
+  workflowInstanceId?: string;
+}) {
+  return {
+    apiVersion: API_VERSION,
+    kind: "WorkflowExecution",
+    metadata: { name: "run-gate-wf-exec", org: ORG },
+    spec,
+  };
+}
+
+describe("workflow-execution-create run gate (composed server)", () => {
+  it("workflow_id: denies with the workflow copy before any lookup, persists nothing", async () => {
+    decision = { kind: "deny", reason: "" };
+    gate.runGateChecks.length = 0;
+    const before = (
+      await server.store.listResources(ApiResourceKind.workflow_execution)
+    ).length;
+
+    // A workflow that does not exist: a lookup-first chain would answer
+    // NOT_FOUND; the gate answers first.
+    const err = await captureError(() =>
+      command.create(createInput({ workflowId: "wf_01private" })),
+    );
+
+    expect(err.code).toBe(Code.PermissionDenied);
+    expect(err.rawMessage).toBe(runWorkflowDeniedMessage("wf_01private"));
+    expect(gate.runGateChecks).toEqual([
+      {
+        permission: IamPermission.can_execute,
+        resourceKind: ApiResourceKind.workflow,
+        resourceId: "wf_01private",
+      },
+    ]);
+    expect(
+      (await server.store.listResources(ApiResourceKind.workflow_execution))
+        .length,
+      "no execution row behind a denial",
+    ).toBe(before);
+  });
+
+  it("workflow_instance_id: denies with the instance copy on workflow_instance#can_execute", async () => {
+    decision = { kind: "deny", reason: "" };
+    gate.runGateChecks.length = 0;
+
+    const err = await captureError(() =>
+      command.create(createInput({ workflowInstanceId: "wfi_01private" })),
+    );
+
+    expect(err.code).toBe(Code.PermissionDenied);
+    expect(err.rawMessage).toBe(
+      runWorkflowInstanceDeniedMessage("wfi_01private"),
+    );
+    expect(gate.runGateChecks).toEqual([
+      {
+        permission: IamPermission.can_execute,
+        resourceKind: ApiResourceKind.workflow_instance,
+        resourceId: "wfi_01private",
+      },
+    ]);
+  });
+
+  it("not-found answers NOT_FOUND naming the target (the stigmer#224 order)", async () => {
+    decision = { kind: "not-found" };
+    const err = await captureError(() =>
+      command.create(createInput({ workflowId: "wf_01missing" })),
+    );
+    expect(err.code).toBe(Code.NotFound);
+    expect(err.rawMessage).toContain("wf_01missing");
+  });
+
+  it("the gate precedes the engine gate: an ALLOWED create reaches EnsureEngineAvailable", async () => {
+    decision = { kind: "allow" };
+    gate.runGateChecks.length = 0;
+
+    const err = await captureError(() =>
+      command.create(createInput({ workflowId: "wf_01allowed" })),
+    );
+
+    expect(err.code).toBe(Code.Unavailable);
+    expect(err.rawMessage).toBe(ENGINE_UNAVAILABLE_MESSAGE);
+    expect(gate.runGateChecks.map((c) => c.resourceId)).toEqual([
+      "wf_01allowed",
+    ]);
+  });
+
+  it("the shape-less request is still ValidateWorkflowOrInstance's INVALID_ARGUMENT, and the gate makes no check", async () => {
+    decision = { kind: "deny", reason: "" };
+    gate.runGateChecks.length = 0;
+
+    const err = await captureError(() => command.create(createInput({})));
+
+    expect(err.code).toBe(Code.InvalidArgument);
+    expect(err.rawMessage).toBe(
+      "either workflow_id or workflow_instance_id must be provided",
+    );
+    expect(gate.runGateChecks).toEqual([]);
+  });
+});

package/src/domain/workflowexecution/__tests__/run-target.test.ts

@@ -0,0 +1,80 @@
+/**
+ * Pins the workflow-execution run-target resolver (P1 sp.run-gate): the
+ * chain's own precedence — an explicit workflow_instance_id fully names
+ * the target (CreateDefaultInstanceIfNeeded returns early on it), else
+ * workflow_id names the blueprint whose default instance the chain will
+ * resolve — each with its own byte-pinned deny copy. Neither set has no
+ * target (ValidateWorkflowOrInstance refuses that shape as INVALID_ARGUMENT
+ * before this step runs).
+ */
+import { describe, expect, it } from "vitest";
+import { create } from "@bufbuild/protobuf";
+
+import { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/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";
+
+import {
+  runWorkflowDeniedMessage,
+  runWorkflowInstanceDeniedMessage,
+} from "../constants.js";
+import { workflowExecutionRunTarget } from "../run-target.js";
+
+describe("workflowExecutionRunTarget", () => {
+  it("workflow_instance_id → workflow_instance#can_execute", () => {
+    expect(
+      workflowExecutionRunTarget(
+        create(WorkflowExecutionSchema, {
+          spec: { workflowInstanceId: "wfi_01abc" },
+        }),
+      ),
+    ).toEqual({
+      permission: IamPermission.can_execute,
+      resourceKind: ApiResourceKind.workflow_instance,
+      resourceId: "wfi_01abc",
+      deniedMessage: runWorkflowInstanceDeniedMessage("wfi_01abc"),
+    });
+    expect(runWorkflowInstanceDeniedMessage("wfi_01abc")).toBe(
+      "unauthorized to run workflow instance 'wfi_01abc'",
+    );
+  });
+
+  it("workflow_id → workflow#can_execute", () => {
+    expect(
+      workflowExecutionRunTarget(
+        create(WorkflowExecutionSchema, { spec: { workflowId: "wf_01abc" } }),
+      ),
+    ).toEqual({
+      permission: IamPermission.can_execute,
+      resourceKind: ApiResourceKind.workflow,
+      resourceId: "wf_01abc",
+      deniedMessage: runWorkflowDeniedMessage("wf_01abc"),
+    });
+    expect(runWorkflowDeniedMessage("wf_01abc")).toBe(
+      "unauthorized to run workflow 'wf_01abc'",
+    );
+  });
+
+  it("precedence is the chain's: the explicit instance wins over the blueprint", () => {
+    const target = workflowExecutionRunTarget(
+      create(WorkflowExecutionSchema, {
+        spec: { workflowId: "wf_01abc", workflowInstanceId: "wfi_01abc" },
+      }),
+    );
+    expect(target?.resourceKind).toBe(ApiResourceKind.workflow_instance);
+    expect(target?.resourceId).toBe("wfi_01abc");
+  });
+
+  it("answers no target when neither reference is set", () => {
+    expect(
+      workflowExecutionRunTarget(create(WorkflowExecutionSchema, {})),
+    ).toBeUndefined();
+    expect(
+      workflowExecutionRunTarget(
+        create(WorkflowExecutionSchema, {
+          spec: { workflowId: "", workflowInstanceId: "" },
+        }),
+      ),
+    ).toBeUndefined();
+  });
+});

package/src/domain/workflowexecution/constants.ts

@@ -16,6 +16,23 @@
 export const ENGINE_UNAVAILABLE_MESSAGE =
   "The execution engine is temporarily unavailable. Please try again shortly.";
 
+/**
+ * The run gate's deny copy per request shape (P1 sp.run-gate, ruling
+ * Q-RG-4; wire once merged, asserted by the conformance run-gate suite).
+ * NEW copy quotes the handle single-quoted (the ratified 2026-08-26 rule).
+ * The agent-execution domain's `runAgent*` functions are these copies'
+ * twins; each domain owns its own.
+ */
+export function runWorkflowDeniedMessage(workflowId: string): string {
+  return `unauthorized to run workflow '${workflowId}'`;
+}
+
+export function runWorkflowInstanceDeniedMessage(
+  workflowInstanceId: string,
+): string {
+  return `unauthorized to run workflow instance '${workflowInstanceId}'`;
+}
+
 /**
  * The lifecycle steps' engineless refusal (lifecycle_steps.go, five
  * sites: pause/resume/cancel/terminate signal steps and recover's