@stigmer/server 3.15.3-dev.20260916211208 → 3.16.0

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

@@ -60,7 +60,10 @@ function memoryCtx(
 
 /** A provider whose only relevant surface is the capture capability. */
 function providerWith(
-  decide?: (caller: CallerIdentity, org: string) => MemoryCaptureDecision,
+  decide?: (
+    caller: CallerIdentity,
+    org: string,
+  ) => MemoryCaptureDecision | Promise<MemoryCaptureDecision>,
 ): RunnerCredentialProvider {
   return {
     isEnabled: () => false,
@@ -79,8 +82,34 @@ function jwtWith(payload: Record<string, unknown>): string {
   return `header.${body}.signature`;
 }
 
+async function rejectionOf(run: void | Promise<void>): Promise<unknown> {
+  return Promise.resolve(run).then(
+    () => {
+      throw new Error("expected the step to refuse");
+    },
+    (error: unknown) => error,
+  );
+}
+
 describe("GuardMemoryCapture with the capability composed", () => {
-  it("admit stashes the proved claims for ResolveMemoryDefaults", () => {
+  it("a capability that answers with a promise is awaited — the built-in provider reads the run's row for the session", async () => {
+    const step = newGuardMemoryCaptureStep<typeof MemorySchema>(
+      providerWith(() =>
+        Promise.resolve({
+          verdict: "admit" as const,
+          subjectIdentityAccountId: "ida_human",
+          provedSessionId: "ses_from_row",
+        }),
+      ),
+    );
+    const ctx = memoryCtx(SANDBOX_CALLER);
+    await step.execute(ctx);
+    expect(memoryCaptureCredentialOf(ctx)?.provedSessionId).toBe(
+      "ses_from_row",
+    );
+  });
+
+  it("admit stashes the proved claims for ResolveMemoryDefaults", async () => {
     const step = newGuardMemoryCaptureStep<typeof MemorySchema>(
       providerWith(() => ({
         verdict: "admit",
@@ -89,23 +118,18 @@ describe("GuardMemoryCapture with the capability composed", () => {
       })),
     );
     const ctx = memoryCtx(SANDBOX_CALLER);
-    step.execute(ctx);
+    await step.execute(ctx);
     expect(memoryCaptureCredentialOf(ctx)).toEqual({
       subjectIdentityAccountId: "ida_human",
       provedSessionId: "ses_proved",
     });
   });
 
-  it("refuse answers the byte-pinned PERMISSION_DENIED copy", () => {
+  it("refuse answers the byte-pinned PERMISSION_DENIED copy", async () => {
     const step = newGuardMemoryCaptureStep<typeof MemorySchema>(
       providerWith(() => ({ verdict: "refuse" })),
     );
-    let error: unknown;
-    try {
-      step.execute(memoryCtx(SANDBOX_CALLER));
-    } catch (e) {
-      error = e;
-    }
+    const error = await rejectionOf(step.execute(memoryCtx(SANDBOX_CALLER)));
     expect(error).toBeInstanceOf(ConnectError);
     expect((error as ConnectError).code).toBe(Code.PermissionDenied);
     expect((error as ConnectError).rawMessage).toBe(
@@ -113,7 +137,7 @@ describe("GuardMemoryCapture with the capability composed", () => {
     );
   });
 
-  it("hands the capability the caller and the capture org", () => {
+  it("hands the capability the caller and the capture org", async () => {
     const observed: Array<{ caller: CallerIdentity; org: string }> = [];
     const step = newGuardMemoryCaptureStep<typeof MemorySchema>(
       providerWith((caller, org) => {
@@ -121,11 +145,11 @@ describe("GuardMemoryCapture with the capability composed", () => {
         return { verdict: "no-opinion" };
       }),
     );
-    step.execute(memoryCtx(SANDBOX_CALLER, "org_zeta"));
+    await step.execute(memoryCtx(SANDBOX_CALLER, "org_zeta"));
     expect(observed).toEqual([{ caller: SANDBOX_CALLER, org: "org_zeta" }]);
   });
 
-  it("an org-mismatch throw from the capability propagates untouched", () => {
+  it("an org-mismatch throw from the capability propagates untouched", async () => {
     const mismatch = new ConnectError(
       "memory capture is scoped to the session's organization",
       Code.PermissionDenied,
@@ -135,16 +159,12 @@ describe("GuardMemoryCapture with the capability composed", () => {
         throw mismatch;
       }),
     );
-    let error: unknown;
-    try {
-      step.execute(memoryCtx(SANDBOX_CALLER, "org_other"));
-    } catch (e) {
-      error = e;
-    }
-    expect(error).toBe(mismatch);
+    expect(
+      await rejectionOf(step.execute(memoryCtx(SANDBOX_CALLER, "org_other"))),
+    ).toBe(mismatch);
   });
 
-  it("no-opinion falls through: platform_client_id carriers still refuse", () => {
+  it("no-opinion falls through: platform_client_id carriers still refuse", async () => {
     const step = newGuardMemoryCaptureStep<typeof MemorySchema>(
       providerWith(() => ({ verdict: "no-opinion" })),
     );
@@ -154,18 +174,18 @@ describe("GuardMemoryCapture with the capability composed", () => {
       issuer: "stigmer",
       rawToken: jwtWith({ platform_client_id: "pc_1" }),
     };
-    expect(() => step.execute(memoryCtx(minted))).toThrowError(
+    await expect(step.execute(memoryCtx(minted))).rejects.toThrowError(
       MEMORY_CAPTURE_CALLER_MESSAGE,
     );
   });
 
-  it("internal and in-process callers never consult the capability", () => {
+  it("internal and in-process callers never consult the capability", async () => {
     const step = newGuardMemoryCaptureStep<typeof MemorySchema>(
       providerWith(() => {
         throw new Error("must not be consulted");
       }),
     );
-    step.execute(
+    await step.execute(
       memoryCtx({
         identityId: "internal",
         callerClass: "internal",
@@ -173,15 +193,15 @@ describe("GuardMemoryCapture with the capability composed", () => {
         rawToken: "",
       }),
     );
-    step.execute(memoryCtx({ ...LOCAL_USER, origin: "in-process" }));
+    await step.execute(memoryCtx({ ...LOCAL_USER, origin: "in-process" }));
   });
 });
 
 describe("GuardMemoryCapture without the capability (the pre-seam gate)", () => {
-  it("admits trusted-local and OIDC callers", () => {
+  it("admits trusted-local and OIDC callers", async () => {
     const step = newGuardMemoryCaptureStep<typeof MemorySchema>(providerWith());
-    step.execute(memoryCtx(LOCAL_USER));
-    step.execute(
+    await step.execute(memoryCtx(LOCAL_USER));
+    await step.execute(
       memoryCtx({
         identityId: "ida_oidc",
         callerClass: "user",
@@ -191,26 +211,26 @@ describe("GuardMemoryCapture without the capability (the pre-seam gate)", () =>
     );
   });
 
-  it("refuses machine callers and platform_client_id carriers", () => {
+  it("refuses machine callers and platform_client_id carriers", async () => {
     const step = newGuardMemoryCaptureStep<typeof MemorySchema>(providerWith());
-    expect(() =>
+    await expect(
       step.execute(memoryCtx({ ...LOCAL_USER, callerClass: "machine" })),
-    ).toThrowError(MEMORY_CAPTURE_CALLER_MESSAGE);
-    expect(() =>
+    ).rejects.toThrowError(MEMORY_CAPTURE_CALLER_MESSAGE);
+    await expect(
       step.execute(
         memoryCtx({
           ...LOCAL_USER,
           rawToken: jwtWith({ platform_client_id: "pc_1" }),
         }),
       ),
-    ).toThrowError(MEMORY_CAPTURE_CALLER_MESSAGE);
+    ).rejects.toThrowError(MEMORY_CAPTURE_CALLER_MESSAGE);
   });
 
-  it("admits a runner-shaped caller — the recorded pre-fix posture", () => {
+  it("admits a runner-shaped caller — the recorded pre-fix posture", async () => {
     // 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());
-    step.execute(memoryCtx(SANDBOX_CALLER));
+    await step.execute(memoryCtx(SANDBOX_CALLER));
   });
 });

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

@@ -59,7 +59,7 @@ export function newGuardMemoryCaptureStep<Desc extends DescMessage>(
 ): PipelineStep<Desc> {
   return {
     name: "GuardMemoryCapture",
-    execute(ctx: RequestContext<Desc>): void {
+    async execute(ctx: RequestContext<Desc>): Promise<void> {
       const caller = ctx.callerIdentity;
       if (caller.callerClass === "internal" || caller.origin === "in-process") {
         // Server-composed traversals are not capture requests from a
@@ -72,9 +72,11 @@ export function newGuardMemoryCaptureStep<Desc extends DescMessage>(
         // arm checks it against the token's own claim (and throws its
         // byte-pinned refusal itself). Empty when the request carries
         // none; Java requires metadata.org before its org-match arm, so
-        // an empty value can only ever narrow.
+        // an empty value can only ever narrow. Awaited because the
+        // built-in provider reads the bound execution's row for the
+        // session and org the cloud's token carries as claims.
         const org = metadataOf(ctx.newState)?.org ?? "";
-        const decision = decide.call(provider, caller, org);
+        const decision = await decide.call(provider, caller, org);
         switch (decision.verdict) {
           case "admit":
             ctx.set(MEMORY_CAPTURE_CREDENTIAL_KEY, {

package/src/runnerauth/__tests__/bound-execution.test.ts

@@ -0,0 +1,334 @@
+/**
+ * Pins the bound-execution reader (bound-execution.ts) in isolation, with
+ * the clock injected, so the liveness rule every lane shares is stated
+ * by enumeration here and the verifier's and the decrypt lane's tests can
+ * assert behavior rather than restate it:
+ *
+ *   - the kind is read off the id alone: the two execution kinds by the
+ *     contract's prefix table, the connect binding by its own predicate;
+ *     anything else is `undefined` with no store read;
+ *   - a connect binding resolves through the connect's ExecutionContext
+ *     row (by `spec.executionId`), is live while that row exists, and is
+ *     not a run (`bindsARun`) — the shape both no-`exp` lanes refuse;
+ *   - live is "not terminal" for each kind's OWN terminal set (the agent
+ *     side's TERMINATED and WAITING_FOR_APPROVAL, the workflow side's
+ *     TERMINATED and PAUSED are the arms that differ from a naive set);
+ *   - a terminal row is live within the grace of its `completed_at`, dead
+ *     at the boundary and beyond, and dead at once with no timestamp or an
+ *     unparsable one (fail closed);
+ *   - a missing row is `undefined`; any other store failure propagates as
+ *     the same error object.
+ */
+import { create } from "@bufbuild/protobuf";
+import type { DescMessage, MessageShape } from "@bufbuild/protobuf";
+import { describe, expect, it, vi } from "vitest";
+
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase as AgentPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ExecutionContextSchema } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/api_pb";
+import { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { ExecutionPhase as WorkflowPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { newConnectExecutionId } from "../../domain/mcpserver/connect-execution-id.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
+import {
+  bindsARun,
+  boundExecutionKindOf,
+  loadBoundExecution,
+} from "../bound-execution.js";
+import type { BoundExecutionStore } from "../bound-execution.js";
+import { RUN_CREDENTIAL_GRACE_AFTER_TERMINAL_MS } from "../constants.js";
+
+const NOW = Date.parse("2026-09-16T12:00:00Z");
+const iso = (offsetMs: number): string =>
+  new Date(NOW + offsetMs).toISOString();
+
+/**
+ * A store of rows by id, plus the connect ECs by the execution id they
+ * were created for (`findByField` on `spec.executionId`). `reads` records
+ * every lookup key, so an arm can assert "no store read" and which read.
+ */
+function storeOf(
+  rows: Record<string, unknown>,
+  executionContexts: Record<string, unknown> = {},
+): BoundExecutionStore & {
+  reads: string[];
+} {
+  const reads: string[] = [];
+  return {
+    reads,
+    getResource<Desc extends DescMessage>(
+      kind: ApiResourceKind,
+      id: string,
+      _schema: Desc,
+    ): Promise<MessageShape<Desc>> {
+      reads.push(id);
+      const row = rows[id];
+      return row === undefined
+        ? Promise.reject(new ResourceNotFoundError(`${kind}/${id}`))
+        : Promise.resolve(row as MessageShape<Desc>);
+    },
+    findByField<Desc extends DescMessage>(
+      kind: ApiResourceKind,
+      fieldPath: string,
+      value: string,
+      _schema: Desc,
+    ): Promise<MessageShape<Desc>> {
+      reads.push(`${fieldPath}=${value}`);
+      const row =
+        kind === ApiResourceKind.execution_context &&
+        fieldPath === "spec.executionId"
+          ? executionContexts[value]
+          : undefined;
+      return row === undefined
+        ? Promise.reject(new ResourceNotFoundError(`${kind}/${value}`))
+        : Promise.resolve(row as MessageShape<Desc>);
+    },
+  };
+}
+
+function connectContext(executionId: string, createdBy: string, org = "acme") {
+  return create(ExecutionContextSchema, {
+    metadata: { id: "ectx_1", name: `exec-ctx-${executionId}`, org },
+    spec: { executionId },
+    status: { audit: { specAudit: { createdBy: { id: createdBy } } } },
+  });
+}
+
+function agentRun(
+  id: string,
+  phase: AgentPhase,
+  completedAt = "",
+  extra: { createdBy?: string; sessionId?: string; org?: string } = {},
+) {
+  return create(AgentExecutionSchema, {
+    metadata: { id, name: id, org: extra.org ?? "acme" },
+    spec: { sessionId: extra.sessionId ?? "" },
+    status: {
+      phase,
+      completedAt,
+      audit: { specAudit: { createdBy: { id: extra.createdBy ?? "" } } },
+    },
+  });
+}
+
+function workflowRun(id: string, phase: WorkflowPhase, completedAt = "") {
+  return create(WorkflowExecutionSchema, {
+    metadata: { id, name: id, org: "acme" },
+    status: { phase, completedAt },
+  });
+}
+
+describe("boundExecutionKindOf", () => {
+  it.each([
+    ["aex_1", "agent-execution"],
+    ["wex_1", "workflow-execution"],
+    [newConnectExecutionId("mcps_1"), "mcp-connect"],
+  ])("%s binds %s", (id, kind) => {
+    expect(boundExecutionKindOf(id)).toBe(kind);
+  });
+
+  it.each([["ses_1"], ["agt_1"], ["zzz_1"], [""], ["aex"], ["connect"]])(
+    "%s binds nothing",
+    (id) => {
+      expect(boundExecutionKindOf(id)).toBeUndefined();
+    },
+  );
+});
+
+describe("bindsARun — what a no-`exp` credential may name", () => {
+  it.each([
+    ["agent-execution", true],
+    ["workflow-execution", true],
+    ["mcp-connect", false],
+  ] as const)("%s → %s", (kind, expected) => {
+    expect(bindsARun(kind)).toBe(expected);
+  });
+});
+
+describe("loadBoundExecution", () => {
+  it("reads the row's facts the lane needs and nothing else", async () => {
+    const store = storeOf({
+      aex_1: agentRun("aex_1", AgentPhase.EXECUTION_IN_PROGRESS, "", {
+        createdBy: "ida_carol",
+        sessionId: "ses_carol",
+        org: "acme",
+      }),
+    });
+    expect(await loadBoundExecution(store, "aex_1", NOW)).toEqual({
+      kind: "agent-execution",
+      executionId: "aex_1",
+      org: "acme",
+      createdBy: "ida_carol",
+      sessionId: "ses_carol",
+      live: true,
+    });
+  });
+
+  it("an id that binds no kind is undefined with NO store read", async () => {
+    const store = storeOf({});
+    expect(await loadBoundExecution(store, "ses_1", NOW)).toBeUndefined();
+    expect(store.reads).toEqual([]);
+  });
+
+  describe("the connect binding — the ExecutionContext row by its execution id", () => {
+    const connectId = newConnectExecutionId("mcps_1");
+
+    it("resolves to the row's creator and org, no session, live while the row exists", async () => {
+      const store = storeOf(
+        {},
+        { [connectId]: connectContext(connectId, "ida_member", "acme") },
+      );
+      expect(await loadBoundExecution(store, connectId, NOW)).toEqual({
+        kind: "mcp-connect",
+        executionId: connectId,
+        org: "acme",
+        createdBy: "ida_member",
+        sessionId: "",
+        live: true,
+      });
+      // The read getByExecutionId already makes, and no primary-key read.
+      expect(store.reads).toEqual([`spec.executionId=${connectId}`]);
+    });
+
+    it("a connect whose row is gone (the connect settled) is undefined — the credential names no row", async () => {
+      expect(
+        await loadBoundExecution(storeOf({}), connectId, NOW),
+      ).toBeUndefined();
+    });
+
+    it("a store fault on the EC read propagates as the same error object", async () => {
+      const fault = new Error("connection reset");
+      const store: BoundExecutionStore = {
+        getResource: vi.fn(() => Promise.reject(new Error("unreachable"))),
+        findByField: vi.fn(() => Promise.reject(fault)),
+      };
+      await expect(loadBoundExecution(store, connectId, NOW)).rejects.toBe(
+        fault,
+      );
+    });
+  });
+
+  it("a missing row is undefined — the typed not-found, and only that, is absorbed", async () => {
+    expect(
+      await loadBoundExecution(storeOf({}), "aex_missing", NOW),
+    ).toBeUndefined();
+  });
+
+  it("any other store failure propagates as the same error object", async () => {
+    const fault = new Error("connection reset");
+    const store: BoundExecutionStore = {
+      getResource: vi.fn(() => Promise.reject(fault)),
+      findByField: vi.fn(() => Promise.reject(new Error("unreachable"))),
+    };
+    await expect(loadBoundExecution(store, "aex_1", NOW)).rejects.toBe(fault);
+  });
+
+  describe("liveness — the agent execution's own terminal set", () => {
+    it.each([
+      ["PENDING", AgentPhase.EXECUTION_PENDING],
+      ["IN_PROGRESS", AgentPhase.EXECUTION_IN_PROGRESS],
+      ["WAITING_FOR_APPROVAL", AgentPhase.EXECUTION_WAITING_FOR_APPROVAL],
+      ["PAUSED", AgentPhase.EXECUTION_PAUSED],
+    ])("%s is live", async (_name, phase) => {
+      const store = storeOf({ aex_1: agentRun("aex_1", phase) });
+      expect((await loadBoundExecution(store, "aex_1", NOW))?.live).toBe(true);
+    });
+
+    it.each([
+      ["COMPLETED", AgentPhase.EXECUTION_COMPLETED],
+      ["FAILED", AgentPhase.EXECUTION_FAILED],
+      ["CANCELLED", AgentPhase.EXECUTION_CANCELLED],
+      ["TERMINATED", AgentPhase.EXECUTION_TERMINATED],
+    ])(
+      "%s with no completed_at is dead at once — no grace without a timestamp",
+      async (_name, phase) => {
+        const store = storeOf({ aex_1: agentRun("aex_1", phase) });
+        expect((await loadBoundExecution(store, "aex_1", NOW))?.live).toBe(
+          false,
+        );
+      },
+    );
+
+    it("a row with no status has not started, which is live", async () => {
+      const store = storeOf({
+        aex_1: create(AgentExecutionSchema, { metadata: { id: "aex_1" } }),
+      });
+      expect((await loadBoundExecution(store, "aex_1", NOW))?.live).toBe(true);
+    });
+  });
+
+  describe("liveness — the workflow execution's own terminal set", () => {
+    it.each([
+      ["PENDING", WorkflowPhase.EXECUTION_PENDING],
+      ["IN_PROGRESS", WorkflowPhase.EXECUTION_IN_PROGRESS],
+      ["PAUSED", WorkflowPhase.EXECUTION_PAUSED],
+    ])("%s is live", async (_name, phase) => {
+      const store = storeOf({ wex_1: workflowRun("wex_1", phase) });
+      expect((await loadBoundExecution(store, "wex_1", NOW))?.live).toBe(true);
+    });
+
+    it.each([
+      ["COMPLETED", WorkflowPhase.EXECUTION_COMPLETED],
+      ["FAILED", WorkflowPhase.EXECUTION_FAILED],
+      ["CANCELLED", WorkflowPhase.EXECUTION_CANCELLED],
+      ["TERMINATED", WorkflowPhase.EXECUTION_TERMINATED],
+    ])("%s with no completed_at is dead at once", async (_name, phase) => {
+      const store = storeOf({ wex_1: workflowRun("wex_1", phase) });
+      expect((await loadBoundExecution(store, "wex_1", NOW))?.live).toBe(false);
+    });
+
+    it("a workflow execution has no session — the field is empty, never a guess", async () => {
+      const store = storeOf({
+        wex_1: workflowRun("wex_1", WorkflowPhase.EXECUTION_IN_PROGRESS),
+      });
+      expect((await loadBoundExecution(store, "wex_1", NOW))?.sessionId).toBe(
+        "",
+      );
+    });
+  });
+
+  describe("the grace after terminal, measured from completed_at", () => {
+    const G = RUN_CREDENTIAL_GRACE_AFTER_TERMINAL_MS;
+
+    it.each([
+      ["the moment it ended", 0, true],
+      ["one millisecond before the grace ends", -(G - 1), true],
+      ["exactly at the grace boundary", -G, false],
+      ["long after", -(G * 10), false],
+    ])("a run that ended %s → live=%s", async (_label, offset, live) => {
+      const store = storeOf({
+        aex_1: agentRun("aex_1", AgentPhase.EXECUTION_COMPLETED, iso(offset)),
+      });
+      expect((await loadBoundExecution(store, "aex_1", NOW))?.live).toBe(live);
+    });
+
+    it("a completed_at in the future (a skewed writer's clock) is inside the grace, not an error", async () => {
+      const store = storeOf({
+        aex_1: agentRun("aex_1", AgentPhase.EXECUTION_COMPLETED, iso(60_000)),
+      });
+      expect((await loadBoundExecution(store, "aex_1", NOW))?.live).toBe(true);
+    });
+
+    it("an unparsable completed_at gets no grace — fail closed", async () => {
+      const store = storeOf({
+        aex_1: agentRun(
+          "aex_1",
+          AgentPhase.EXECUTION_COMPLETED,
+          "yesterday-ish",
+        ),
+      });
+      expect((await loadBoundExecution(store, "aex_1", NOW))?.live).toBe(false);
+    });
+
+    it("the same rule applies to a workflow execution", async () => {
+      const store = storeOf({
+        wex_1: workflowRun("wex_1", WorkflowPhase.EXECUTION_FAILED, iso(-1000)),
+        wex_2: workflowRun("wex_2", WorkflowPhase.EXECUTION_FAILED, iso(-G)),
+      });
+      expect((await loadBoundExecution(store, "wex_1", NOW))?.live).toBe(true);
+      expect((await loadBoundExecution(store, "wex_2", NOW))?.live).toBe(false);
+    });
+  });
+});