@stigmer/server 3.14.0-dev.20260910084630

package/src/domain/workflowexecution/__tests__/list-read-scope-summaries.test.ts

@@ -0,0 +1,193 @@
+/**
+ * Pins the ListReadScope arm of BOTH getExecutionSummary handlers (C2
+ * Stage 4's ExecutionReadScope port, absorbed into the generalized seam
+ * by 20260830.01.sp.list-read-scoping):
+ *
+ *   - a composed scope narrows the aggregation to authorized ids ∩ the
+ *     requested org (the Java GetExecutionSummary baseline);
+ *   - an EMPTY authorized set answers the proto DEFAULT INSTANCE — the
+ *     conformance-pinned multi-tenant zero shape (workflow: success_rate
+ *     0 and NO cost summary — the exact opposite of the OSS -1 sentinel
+ *     and always-present zero cost) falls out of the scoping;
+ *   - NO scope composed = the full scan, org NOT consulted (the OSS
+ *     single-user semantics, byte-identity guarded here as well as by
+ *     the conformance rosters).
+ */
+import { create, toBinary } from "@bufbuild/protobuf";
+import { describe, expect, it } from "vitest";
+
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase as AgentExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { GetAgentExecutionSummaryRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import { GetExecutionSummaryRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { createLogger } from "../../../boot/logger.js";
+import type { ListReadScope } from "../../../extensions/list-read-scope.js";
+import { testCallerIdentity } from "../../../pipeline/__tests__/support.js";
+import { newPermissiveSingleTeamAuthorizer } from "../../../pipeline/steps/authorize.js";
+import type { Store } from "../../../store/interface.js";
+
+import { getExecutionSummary as getAgentSummary } from "../../agentexecution/usage.js";
+import { getExecutionSummary as getWorkflowSummary } from "../get-execution-summary.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const caller = testCallerIdentity();
+
+function scopeOf(ids: ReadonlyArray<string>): ListReadScope {
+  return {
+    authorizedResourceIds: () => Promise.resolve(new Set(ids)),
+    restrictListEntries: () => Promise.resolve(new Set<string>()),
+  };
+}
+
+/** A store whose listResources answers the given serialized rows. */
+function listOnlyStore(rows: Uint8Array[]): Store {
+  return { listResources: () => Promise.resolve(rows) } as unknown as Store;
+}
+
+function workflowExecRow(id: string, org: string, phase: ExecutionPhase) {
+  return toBinary(
+    WorkflowExecutionSchema,
+    create(WorkflowExecutionSchema, {
+      metadata: { id, name: id, slug: id, org },
+      status: { phase },
+    }),
+  );
+}
+
+function agentExecRow(id: string, org: string, phase: AgentExecutionPhase) {
+  return toBinary(
+    AgentExecutionSchema,
+    create(AgentExecutionSchema, {
+      metadata: { id, name: id, org },
+      status: { phase },
+    }),
+  );
+}
+
+describe("workflow getExecutionSummary read scope", () => {
+  const rows = [
+    workflowExecRow("wfe_mine_done", "acme", ExecutionPhase.EXECUTION_COMPLETED),
+    workflowExecRow("wfe_mine_run", "acme", ExecutionPhase.EXECUTION_IN_PROGRESS),
+    // Authorized but in ANOTHER org — the org intersection must drop it.
+    workflowExecRow("wfe_other_org", "rival", ExecutionPhase.EXECUTION_FAILED),
+    // In the org but NOT authorized — the id set must drop it.
+    workflowExecRow("wfe_not_mine", "acme", ExecutionPhase.EXECUTION_FAILED),
+  ];
+
+  function deps(scope: ListReadScope | undefined) {
+    return {
+      store: listOnlyStore(rows),
+      logger: silentLogger,
+      listReadScope: scope,
+    };
+  }
+
+  it("narrows to authorized ids ∩ the requested org", async () => {
+    const summary = await getWorkflowSummary(
+      deps(scopeOf(["wfe_mine_done", "wfe_mine_run", "wfe_other_org"])),
+      create(GetExecutionSummaryRequestSchema, { org: "acme" }),
+      caller,
+    );
+    expect(summary.totalCount).toBe(2);
+    expect(summary.activeCount).toBe(1);
+    // One terminal (completed) — a real 100%, not the -1 sentinel.
+    expect(summary.successRate).toBe(1);
+  });
+
+  it("an empty authorized set answers the default instance — the multi-tenant zero shape", async () => {
+    const summary = await getWorkflowSummary(
+      deps(scopeOf([])),
+      create(GetExecutionSummaryRequestSchema, { org: "acme" }),
+      caller,
+    );
+    expect(summary.successRate).toBe(0);
+    expect(summary.totalCost).toBeUndefined();
+    expect(summary.totalCount).toBe(0);
+    expect(summary.avgDuration).toBeUndefined();
+  });
+
+  it("no scope composed = the full scan; org is NOT consulted (OSS byte-identity)", async () => {
+    const summary = await getWorkflowSummary(
+      deps(undefined),
+      create(GetExecutionSummaryRequestSchema, { org: "acme" }),
+      caller,
+    );
+    // All four rows counted, the rival org's included; and the OSS zero
+    // pins hold: the -1 sentinel family and the ALWAYS-present cost
+    // summary.
+    expect(summary.totalCount).toBe(4);
+    expect(summary.totalCost).toBeDefined();
+  });
+});
+
+describe("agent getExecutionSummary read scope", () => {
+  const rows = [
+    agentExecRow("aexec_mine", "acme", AgentExecutionPhase.EXECUTION_IN_PROGRESS),
+    agentExecRow("aexec_other_org", "rival", AgentExecutionPhase.EXECUTION_IN_PROGRESS),
+    agentExecRow("aexec_not_mine", "acme", AgentExecutionPhase.EXECUTION_IN_PROGRESS),
+  ];
+
+  function deps(scope: ListReadScope | undefined) {
+    return {
+      store: listOnlyStore(rows),
+      logger: silentLogger,
+      authorizer: newPermissiveSingleTeamAuthorizer(),
+      listReadScope: scope,
+    };
+  }
+
+  it("narrows to authorized ids ∩ the requested org", async () => {
+    const summary = await getAgentSummary(
+      deps(scopeOf(["aexec_mine", "aexec_other_org"])),
+      create(GetAgentExecutionSummaryRequestSchema, { org: "acme" }),
+      caller,
+    );
+    expect(summary.activeCount).toBe(1);
+  });
+
+  it("an empty authorized set answers the default instance", async () => {
+    const summary = await getAgentSummary(
+      deps(scopeOf([])),
+      create(GetAgentExecutionSummaryRequestSchema, { org: "acme" }),
+      caller,
+    );
+    expect(summary.activeCount).toBe(0);
+    expect(summary.phaseCounts).toEqual({});
+    expect(summary.avgDuration).toBeUndefined();
+  });
+
+  it("no scope composed = the full scan across orgs (OSS byte-identity)", async () => {
+    const summary = await getAgentSummary(
+      deps(undefined),
+      create(GetAgentExecutionSummaryRequestSchema, { org: "acme" }),
+      caller,
+    );
+    expect(summary.activeCount).toBe(3);
+  });
+
+  it("the scope receives the kind it is scoping (agent_execution here)", async () => {
+    const kinds: ApiResourceKind[] = [];
+    const recordingScope: ListReadScope = {
+      authorizedResourceIds: (_caller, kind) => {
+        kinds.push(kind);
+        return Promise.resolve(new Set<string>());
+      },
+      restrictListEntries: () => Promise.resolve(new Set<string>()),
+    };
+    await getAgentSummary(
+      deps(recordingScope),
+      create(GetAgentExecutionSummaryRequestSchema, { org: "acme" }),
+      caller,
+    );
+    expect(kinds).toEqual([ApiResourceKind.agent_execution]);
+  });
+});

package/src/domain/workflowexecution/__tests__/read-authorization.test.ts

@@ -0,0 +1,166 @@
+/**
+ * Pins the C2 Stage-4 enforcement on this domain's three config-annotated
+ * direct read surfaces (subscribe, subscribeEvents, getEventLog): each
+ * evaluates its OWN annotation through authorizeDirect BEFORE any store
+ * or broker touch, and a denying authorizer answers PERMISSION_DENIED
+ * with the method's byte-pinned error_msg. The exact copy doubles as the
+ * descriptor-mismatch guard (a handler passing another method's
+ * descriptor would answer the wrong copy). The deny/not-found/unavailable
+ * mapping itself is pinned in pipeline/steps/__tests__/authorize.test.ts.
+ */
+import { create } from "@bufbuild/protobuf";
+import type { HandlerContext } from "@connectrpc/connect";
+import { Code, ConnectError, createContextValues } from "@connectrpc/connect";
+import { describe, expect, it } from "vitest";
+
+import {
+  GetEventLogRequestSchema,
+  SubscribeEventsRequestSchema,
+  SubscribeWorkflowExecutionRequestSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+
+import { createLogger } from "../../../boot/logger.js";
+import type { Authorizer } from "../../../extensions/authorizer.js";
+import { callerIdentityKey } from "../../../pipeline/interceptors/auth.js";
+import { testCallerIdentity } from "../../../pipeline/__tests__/support.js";
+import type { Store } from "../../../store/interface.js";
+
+import { getEventLog } from "../get-event-log.js";
+import type { StreamBroker } from "../stream-broker.js";
+import { subscribeEvents } from "../subscribe-events.js";
+import { subscribeExecution } from "../subscribe.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const denyingAuthorizer: Authorizer = {
+  authorize: () => Promise.resolve({ kind: "deny", reason: "" }),
+};
+
+/** A store that fails the test if the denied request ever reaches it. */
+const untouchableStore = new Proxy({} as Store, {
+  get(_target, prop) {
+    throw new Error(`store.${String(prop)} reached despite the denial`);
+  },
+});
+
+const untouchableBroker = new Proxy({} as StreamBroker, {
+  get(_target, prop) {
+    throw new Error(`broker.${String(prop)} reached despite the denial`);
+  },
+});
+
+function handlerContext(): HandlerContext {
+  const values = createContextValues();
+  values.set(callerIdentityKey, testCallerIdentity());
+  return { signal: new AbortController().signal, values } as HandlerContext;
+}
+
+async function expectDenied(run: () => Promise<unknown>, copy: string) {
+  const error = await run().catch((e: unknown) => e);
+  expect(error).toBeInstanceOf(ConnectError);
+  expect((error as ConnectError).code).toBe(Code.PermissionDenied);
+  expect((error as ConnectError).rawMessage).toBe(copy);
+}
+
+describe("read-surface authorization (C2 Stage 4)", () => {
+  it("subscribe denies with its annotation copy before touching store or broker", async () => {
+    await expectDenied(
+      () =>
+        subscribeExecution(
+          {
+            store: untouchableStore,
+            logger: silentLogger,
+            broker: untouchableBroker,
+            authorizer: denyingAuthorizer,
+          },
+          create(SubscribeWorkflowExecutionRequestSchema, {
+            executionId: "wfe_01denied",
+          }),
+          handlerContext(),
+        ).next(),
+      "unauthorized to get workflow execution stream",
+    );
+  });
+
+  it("subscribeEvents denies with its annotation copy before the existence check", async () => {
+    await expectDenied(
+      () =>
+        subscribeEvents(
+          {
+            store: untouchableStore,
+            logger: silentLogger,
+            authorizer: denyingAuthorizer,
+          },
+          create(SubscribeEventsRequestSchema, { executionId: "wfe_01denied" }),
+          handlerContext(),
+        ).next(),
+      "unauthorized to subscribe to workflow execution events",
+    );
+  });
+
+  it("getEventLog denies with its annotation copy before the store read", async () => {
+    await expectDenied(
+      () =>
+        getEventLog(
+          {
+            store: untouchableStore,
+            logger: silentLogger,
+            authorizer: denyingAuthorizer,
+          },
+          create(GetEventLogRequestSchema, { executionId: "wfe_01denied" }),
+          testCallerIdentity(),
+        ),
+      "unauthorized to get workflow execution event log",
+    );
+  });
+
+  it("the internal caller class skips the check on all three (in-process parity)", async () => {
+    // The denying authorizer must never be consulted; the handlers then
+    // proceed into their store reads — the throwing store proves BOTH.
+    const internal = testCallerIdentity({ callerClass: "internal" });
+    const values = createContextValues();
+    values.set(callerIdentityKey, internal);
+    const ctx = {
+      signal: new AbortController().signal,
+      values,
+    } as HandlerContext;
+
+    const subscribeError = await subscribeExecution(
+      {
+        store: untouchableStore,
+        logger: silentLogger,
+        broker: untouchableBroker,
+        authorizer: denyingAuthorizer,
+      },
+      create(SubscribeWorkflowExecutionRequestSchema, {
+        executionId: "wfe_01internal",
+      }),
+      ctx,
+    )
+      .next()
+      .catch((e: unknown) => e);
+    expect((subscribeError as Error).message).toContain(
+      "reached despite the denial",
+    );
+
+    // getEventLog wraps its store fault as the sanitized Internal — the
+    // wrapped copy (not a denial) is the store-was-reached proof.
+    const eventLogError = await getEventLog(
+      {
+        store: untouchableStore,
+        logger: silentLogger,
+        authorizer: denyingAuthorizer,
+      },
+      create(GetEventLogRequestSchema, { executionId: "wfe_01internal" }),
+      internal,
+    ).catch((e: unknown) => e);
+    expect((eventLogError as ConnectError).code).toBe(Code.Internal);
+    expect((eventLogError as ConnectError).rawMessage).toBe(
+      "failed to query execution events",
+    );
+  });
+});

package/src/domain/workflowexecution/__tests__/send-signal.test.ts

@@ -0,0 +1,327 @@
+/**
+ * Pins sendSignal against Go's send_signal_test.go and
+ * send_signal_dedupe_test.go case-for-case: the validation and phase
+ * arms, the relay-envelope construction on the byte-pinned relaySignal
+ * channel, and the two-phase dedupe contract (oss#442) — ALREADY_EXISTS
+ * on a DELIVERED duplicate, ABORTED on a live in-flight claim,
+ * release-after-failure enabling an immediate retry, empty-key and
+ * store-error skips, and org-scoped key isolation.
+ */
+import { newPermissiveSingleTeamAuthorizer } from "../../../pipeline/steps/authorize.js";
+import { testCallerIdentity } from "../../../pipeline/__tests__/support.js";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { create } from "@bufbuild/protobuf";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import { SendSignalInputSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import type { SendSignalInput } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { createLogger } from "../../../boot/logger.js";
+import { SqliteStore } from "../../../store/sqlite/store.js";
+
+import { WORKFLOW_CREATOR_UNAVAILABLE_MESSAGE } from "../constants.js";
+import { ENGINE_DISCONNECTED } from "../engine.js";
+import { sendSignal } from "../send-signal.js";
+import type { SendSignalDeps } from "../send-signal.js";
+import { stubConnectedEngine } from "./engine-stub.js";
+import type { EngineStub } from "./engine-stub.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+let dir: string;
+let store: SqliteStore;
+let counter = 0;
+
+beforeAll(() => {
+  dir = mkdtempSync(path.join(tmpdir(), "wfexec-signal-"));
+  store = SqliteStore.open(path.join(dir, "test.db"));
+});
+
+afterAll(async () => {
+  await store.close();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function deps(engineStub?: EngineStub): SendSignalDeps {
+  return {
+    store,
+    logger: silentLogger,
+    authorizer: newPermissiveSingleTeamAuthorizer(),
+    engineState: () => engineStub?.state ?? ENGINE_DISCONNECTED,
+  };
+}
+
+async function seed(phase: ExecutionPhase, org = "acme"): Promise<string> {
+  counter += 1;
+  const id = `wfx_sig_${counter}`;
+  await store.saveResource(
+    ApiResourceKind.workflow_execution,
+    id,
+    WorkflowExecutionSchema,
+    create(WorkflowExecutionSchema, {
+      metadata: { id, name: id, org },
+      spec: {
+        workflowId: `wf_${counter}`,
+        workflowInstanceId: `wfi_${counter}`,
+      },
+      status: { phase },
+    }),
+  );
+  return id;
+}
+
+function input(
+  executionId: string,
+  signalName = "user_event",
+  idempotencyKey = "",
+): SendSignalInput {
+  return create(SendSignalInputSchema, {
+    executionId,
+    signalName,
+    idempotencyKey,
+    payload: { hello: "world" },
+  });
+}
+
+async function expectCode(
+  fn: () => Promise<unknown>,
+  code: Code,
+): Promise<ConnectError> {
+  try {
+    await fn();
+  } catch (error) {
+    expect(error).toBeInstanceOf(ConnectError);
+    expect((error as ConnectError).code).toBe(code);
+    return error as ConnectError;
+  }
+  throw new Error(`expected ${Code[code]}, call succeeded`);
+}
+
+describe("sendSignal validation + phase arms (send_signal_test.go)", () => {
+  it("requires execution_id and signal_name", async () => {
+    const missing = await expectCode(
+      () => sendSignal(deps(), input("", "sig"), testCallerIdentity()),
+      Code.InvalidArgument,
+    );
+    expect(missing.rawMessage).toBe("execution_id is required");
+    const id = await seed(ExecutionPhase.EXECUTION_IN_PROGRESS);
+    const noName = await expectCode(
+      () => sendSignal(deps(), input(id, ""), testCallerIdentity()),
+      Code.InvalidArgument,
+    );
+    expect(noName.rawMessage).toBe("signal_name is required");
+  });
+
+  it("unknown execution answers NotFound", async () => {
+    const err = await expectCode(
+      () => sendSignal(deps(), input("wfx_missing"), testCallerIdentity()),
+      Code.NotFound,
+    );
+    expect(err.rawMessage).toBe("workflow_execution not found: wfx_missing");
+  });
+
+  it("terminal phases refuse FailedPrecondition with the pinned copy", async () => {
+    const completed = await seed(ExecutionPhase.EXECUTION_COMPLETED);
+    const err = await expectCode(
+      () => sendSignal(deps(), input(completed), testCallerIdentity()),
+      Code.FailedPrecondition,
+    );
+    expect(err.rawMessage).toBe(
+      "cannot send signal to execution in phase EXECUTION_COMPLETED; only PENDING or IN_PROGRESS executions can receive signals",
+    );
+  });
+
+  it("engineless send refuses FailedPrecondition with the creator copy", async () => {
+    const id = await seed(ExecutionPhase.EXECUTION_IN_PROGRESS);
+    const err = await expectCode(
+      () => sendSignal(deps(), input(id), testCallerIdentity()),
+      Code.FailedPrecondition,
+    );
+    expect(err.rawMessage).toBe(WORKFLOW_CREATOR_UNAVAILABLE_MESSAGE);
+  });
+
+  it("delivers the relay envelope on the relaySignal channel (PENDING is signalable)", async () => {
+    const engine = stubConnectedEngine();
+    const id = await seed(ExecutionPhase.EXECUTION_PENDING);
+    const result = await sendSignal(
+      deps(engine),
+      input(id, "order_arrived"),
+      testCallerIdentity(),
+    );
+    expect(result.metadata?.id).toBe(id);
+
+    expect(engine.calls).toHaveLength(1);
+    const [startInput, signalName, payload] = engine.calls[0].args as [
+      { executionId: string; recoveryMode: boolean },
+      string,
+      unknown,
+    ];
+    expect(startInput.executionId).toBe(id);
+    expect(signalName).toBe("relaySignal");
+    // The envelope's JSON shape is the runner's wire contract.
+    expect(payload).toEqual({
+      signalName: "order_arrived",
+      payload: { hello: "world" },
+    });
+  });
+
+  it("a nil payload rides as null in the envelope (Go interface{} nil)", async () => {
+    const engine = stubConnectedEngine();
+    const id = await seed(ExecutionPhase.EXECUTION_IN_PROGRESS);
+    await sendSignal(
+      deps(engine),
+      create(SendSignalInputSchema, { executionId: id, signalName: "ping" }),
+      testCallerIdentity(),
+    );
+    const [, , payload] = engine.calls[0].args as [unknown, string, unknown];
+    expect(payload).toEqual({ signalName: "ping", payload: null });
+  });
+});
+
+describe("sendSignal dedupe (send_signal_dedupe_test.go, oss#442)", () => {
+  it("a DELIVERED duplicate answers AlreadyExists with the pinned shape", async () => {
+    const engine = stubConnectedEngine();
+    const id = await seed(ExecutionPhase.EXECUTION_IN_PROGRESS);
+    await sendSignal(
+      deps(engine),
+      input(id, "sig", "key-delivered"),
+      testCallerIdentity(),
+    );
+
+    const err = await expectCode(
+      () =>
+        sendSignal(
+          deps(engine),
+          input(id, "sig", "key-delivered"),
+          testCallerIdentity(),
+        ),
+      Code.AlreadyExists,
+    );
+    expect(err.rawMessage).toBe(
+      "signal_with_idempotency_key already exists: key-delivered",
+    );
+    // The successful send delivered exactly once.
+    expect(
+      engine.calls.filter((call) => call.method === "signalWithStart"),
+    ).toHaveLength(1);
+  });
+
+  it("a live in-flight claim answers Aborted (retryable conflict)", async () => {
+    const engine = stubConnectedEngine();
+    const id = await seed(ExecutionPhase.EXECUTION_IN_PROGRESS);
+    // Claim the key directly (a concurrent request's live hold).
+    await store.signalDedupe.claim("acme", "key-inflight", id, "sig", 300_000);
+
+    const err = await expectCode(
+      () =>
+        sendSignal(
+          deps(engine),
+          input(id, "sig", "key-inflight"),
+          testCallerIdentity(),
+        ),
+      Code.Aborted,
+    );
+    expect(err.rawMessage).toBe(
+      'signal with idempotency_key "key-inflight" is currently being delivered; retry shortly',
+    );
+  });
+
+  it("a failed send releases the claim so the retry claims freshly", async () => {
+    const engine = stubConnectedEngine();
+    engine.failures.signalWithStart = new Error("temporal exploded");
+    const id = await seed(ExecutionPhase.EXECUTION_IN_PROGRESS);
+
+    const err = await expectCode(
+      () =>
+        sendSignal(
+          deps(engine),
+          input(id, "sig", "key-retry"),
+          testCallerIdentity(),
+        ),
+      Code.Internal,
+    );
+    expect(err.rawMessage).toBe("failed to send signal to workflow");
+
+    // The retry with the same key must claim freshly and deliver.
+    const healthy = stubConnectedEngine();
+    await sendSignal(
+      deps(healthy),
+      input(id, "sig", "key-retry"),
+      testCallerIdentity(),
+    );
+    expect(
+      healthy.calls.filter((call) => call.method === "signalWithStart"),
+    ).toHaveLength(1);
+  });
+
+  it("no idempotency key skips dedupe entirely (backward compatible)", async () => {
+    const engine = stubConnectedEngine();
+    const id = await seed(ExecutionPhase.EXECUTION_IN_PROGRESS);
+    await sendSignal(deps(engine), input(id, "sig", ""), testCallerIdentity());
+    await sendSignal(deps(engine), input(id, "sig", ""), testCallerIdentity());
+    expect(
+      engine.calls.filter((call) => call.method === "signalWithStart"),
+    ).toHaveLength(2);
+  });
+
+  it("distinct keys do not collide; keys are org-scoped", async () => {
+    const engine = stubConnectedEngine();
+    const id = await seed(ExecutionPhase.EXECUTION_IN_PROGRESS);
+    await sendSignal(
+      deps(engine),
+      input(id, "sig", "key-a"),
+      testCallerIdentity(),
+    );
+    await sendSignal(
+      deps(engine),
+      input(id, "sig", "key-b"),
+      testCallerIdentity(),
+    );
+
+    // The same key under ANOTHER org claims independently ({org}:{key}).
+    const otherOrg = await seed(ExecutionPhase.EXECUTION_IN_PROGRESS, "beta");
+    await sendSignal(
+      deps(engine),
+      input(otherOrg, "sig", "key-a"),
+      testCallerIdentity(),
+    );
+
+    expect(
+      engine.calls.filter((call) => call.method === "signalWithStart"),
+    ).toHaveLength(3);
+  });
+
+  it("engineless failure after a claim also releases it (the send step is the failure)", async () => {
+    const id = await seed(ExecutionPhase.EXECUTION_IN_PROGRESS);
+    await expectCode(
+      () =>
+        sendSignal(
+          deps(),
+          input(id, "sig", "key-engineless"),
+          testCallerIdentity(),
+        ),
+      Code.FailedPrecondition,
+    );
+    // The claim was released: a healthy retry delivers instead of Aborted.
+    const healthy = stubConnectedEngine();
+    await sendSignal(
+      deps(healthy),
+      input(id, "sig", "key-engineless"),
+      testCallerIdentity(),
+    );
+    expect(
+      healthy.calls.filter((call) => call.method === "signalWithStart"),
+    ).toHaveLength(1);
+  });
+});