@stigmer/server 3.15.3-dev.20260916211208 → 3.16.1-dev.20260917224426

package/src/domain/workflowexecution/__tests__/phases.test.ts

@@ -0,0 +1,58 @@
+/**
+ * Pins `isTerminalWorkflowExecutionPhase` (phases.ts) over every member
+ * of the workflow ExecutionPhase enum, so the set is stated by
+ * enumeration and a new phase added to the contract lands in exactly one
+ * arm here. The contrast with subscribe.ts's `isWorkflowTerminalPhase`
+ * (TERMINATED omitted on purpose) is pinned so the two are never merged.
+ */
+import { describe, expect, it } from "vitest";
+
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+
+import { isTerminalWorkflowExecutionPhase } from "../phases.js";
+import { isWorkflowTerminalPhase } from "../subscribe.js";
+
+const TERMINAL = [
+  ExecutionPhase.EXECUTION_COMPLETED,
+  ExecutionPhase.EXECUTION_FAILED,
+  ExecutionPhase.EXECUTION_CANCELLED,
+  ExecutionPhase.EXECUTION_TERMINATED,
+];
+
+describe("isTerminalWorkflowExecutionPhase", () => {
+  it.each(TERMINAL.map((phase) => [ExecutionPhase[phase], phase] as const))(
+    "%s will never run again",
+    (_name, phase) => {
+      expect(isTerminalWorkflowExecutionPhase(phase)).toBe(true);
+    },
+  );
+
+  it.each([
+    ["UNSPECIFIED", ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED],
+    ["PENDING", ExecutionPhase.EXECUTION_PENDING],
+    ["IN_PROGRESS", ExecutionPhase.EXECUTION_IN_PROGRESS],
+    ["PAUSED", ExecutionPhase.EXECUTION_PAUSED],
+  ])("%s may still run", (_name, phase) => {
+    expect(isTerminalWorkflowExecutionPhase(phase)).toBe(false);
+  });
+
+  it("covers every member of the enum — a new phase must be classified here", () => {
+    const members = Object.values(ExecutionPhase).filter(
+      (value): value is ExecutionPhase => typeof value === "number",
+    );
+    const classified = members.filter((phase) =>
+      isTerminalWorkflowExecutionPhase(phase),
+    );
+    expect(classified.sort()).toEqual([...TERMINAL].sort());
+    expect(members).toHaveLength(8);
+  });
+
+  it("differs from the subscribe stream's close set on TERMINATED alone — deliberate, not to be merged", () => {
+    expect(isWorkflowTerminalPhase(ExecutionPhase.EXECUTION_TERMINATED)).toBe(
+      false,
+    );
+    expect(
+      isTerminalWorkflowExecutionPhase(ExecutionPhase.EXECUTION_TERMINATED),
+    ).toBe(true);
+  });
+});

package/src/domain/workflowexecution/phases.ts

@@ -0,0 +1,33 @@
+/**
+ * The workflow execution's "will this run ever run again?" predicate —
+ * the twin of domain/agentexecution/phases.ts `isTerminalExecutionPhase`,
+ * stated once so every consumer names the same set: COMPLETED, FAILED,
+ * CANCELLED and TERMINATED. PAUSED is NOT terminal (lifecycle.ts:
+ * `applyLifecyclePhaseTransition` keeps `completed_at` as-is on a pause
+ * and clears it on the way back to IN_PROGRESS), and neither is PENDING.
+ *
+ * Deliberately distinct from `isWorkflowTerminalPhase` in subscribe.ts,
+ * which OMITS TERMINATED — the disclosed Go quirk the subscribe stream
+ * ports faithfully as its close set. Do not merge the two; that file's
+ * header carries the reason.
+ *
+ * The first consumer is the runner-credential lane (runnerauth/
+ * bound-execution.ts): a run credential is valid while its run may still
+ * run, so a terminated workflow's credential must die exactly as a
+ * completed one's does.
+ */
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+
+export function isTerminalWorkflowExecutionPhase(
+  phase: ExecutionPhase,
+): boolean {
+  switch (phase) {
+    case ExecutionPhase.EXECUTION_COMPLETED:
+    case ExecutionPhase.EXECUTION_FAILED:
+    case ExecutionPhase.EXECUTION_CANCELLED:
+    case ExecutionPhase.EXECUTION_TERMINATED:
+      return true;
+    default:
+      return false;
+  }
+}

package/src/extensions/__tests__/extension-composition.test.ts

@@ -544,7 +544,13 @@ describe("extension composition (require-authentication posture)", () => {
     };
     expect(parsed.posture).toBe("required");
     expect(parsed.source).toBe("extension 'fake-identity'");
-    expect(parsed.verifiers).toBe("apikey, fake-verifier");
+    // A unit that declares the posture and brings verifiers but NO
+    // Authorizer is the BUILT-IN authorization posture: open source
+    // composes its Authorizer, and with it the runner-subject verifier
+    // between the API-key lane and the unit's own (runnerauth/
+    // runner-subject-verifier.ts). A unit with its own Authorizer gets
+    // neither (runner-subject-composed.test.ts pins that chain).
+    expect(parsed.verifiers).toBe("apikey, runner, fake-verifier");
   });
 
   it("a declared posture whose unit registers no verifier of its own is a boot throw naming the unit — the API-key lane alone cannot bootstrap", async () => {

package/src/identity/__tests__/oidc-verifier.test.ts

@@ -218,6 +218,28 @@ describe("the byte-pinned classifyAuthError arms", () => {
     expect(ConnectError.from(error).code).toBe(Code.Unauthenticated);
     expect(ConnectError.from(error).rawMessage).toBe(INVALID_TOKEN_MESSAGE);
   });
+
+  it("a JWT whose algorithm the JWKS cannot serve (HS256 against RS256 keys) → 'invalid token', a CREDENTIAL rejection, never a plain error the chassis maps INTERNAL", async () => {
+    // The shape the server's own execution-scoped runner token has
+    // (runnerauth.ts). Whether this verifier should ever SEE it is the
+    // chain order's business (the runner verifier claims it first); that
+    // it must not answer INTERNAL when it does is this arm's. Until
+    // 2026-09-16 it threw jose's JOSENotSupported unclassified, and a
+    // self-host with sign-in on failed every agent execution with
+    // "internal server error" (stigmer#1137).
+    const segment = (value: unknown): string =>
+      Buffer.from(JSON.stringify(value)).toString("base64url");
+    const hs256 = `${segment({ alg: "HS256", typ: "JWT" })}.${segment({
+      token_type: "execution_scoped",
+      execution_id: "aex_1",
+      iat: 1,
+      exp: 4102444800,
+    })}.${segment("a-mac-this-verifier-cannot-check")}`;
+    const error = await rejectionOf(verifier().verify(hs256));
+    expect(error).toBeInstanceOf(ConnectError);
+    expect(ConnectError.from(error).code).toBe(Code.Unauthenticated);
+    expect(ConnectError.from(error).rawMessage).toBe(INVALID_TOKEN_MESSAGE);
+  });
 });
 
 describe("subject → account resolution (20260911.11 Q-IA-2, A1)", () => {

package/src/identity/oidc-verifier.ts

@@ -159,7 +159,14 @@ function classifyJoseError(error: unknown): unknown {
   }
   if (
     error instanceof joseErrors.JWTInvalid ||
-    error instanceof joseErrors.JWSInvalid
+    error instanceof joseErrors.JWSInvalid ||
+    // A JWT whose algorithm the issuer's key set cannot serve (an HS256
+    // token against an RS256 JWKS): a credential this verifier recognizes
+    // but cannot verify, so a credential rejection — never the
+    // infrastructure arm. Until 2026-09-16 it fell through to INTERNAL,
+    // and a self-host with sign-in on failed every agent execution on its
+    // own runner token (stigmer#1137).
+    error instanceof joseErrors.JOSENotSupported
   ) {
     return new ConnectError(INVALID_TOKEN_MESSAGE, Code.Unauthenticated);
   }

package/src/pipeline/__tests__/kind-by-id-prefix.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Pins `kindByIdPrefix` (pipeline/apiresource-meta.ts), the inverse of
+ * `getIdPrefix` over the ids the server mints (`<prefix>_<ulid>`,
+ * pipeline/steps/defaults.ts). The runner-credential lane reads it to
+ * learn which execution kind a token's binding names — an agent
+ * execution (`aex_`) or a workflow execution (`wex_`) — without a second
+ * claim on the token or a guess.
+ *
+ * Two properties are load-bearing:
+ *
+ *   - NEVER a throw. The id arrives inside a credential; the caller
+ *     refuses with its own sentence, so anything that is not a known
+ *     prefix followed by an underscore is the unknown kind.
+ *   - Every `id_prefix` in the contract is UNIQUE. The lookup is a Map
+ *     over the `kind_meta` table; a duplicate prefix would silently win
+ *     for one kind and lose for the other. The pin below turns a future
+ *     duplicate into a reviewed change.
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+  ApiResourceKind,
+  ApiResourceKindSchema,
+  kind_meta,
+} from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { getOption, hasOption } from "@bufbuild/protobuf";
+
+import { getIdPrefix, kindByIdPrefix } from "../apiresource-meta.js";
+
+describe("kindByIdPrefix — a minted id names its kind by prefix", () => {
+  it.each([
+    ["aex_01m2mp45efcjvq2z1e1yn4cyz7", ApiResourceKind.agent_execution],
+    ["wex_01m2mp45efcjvq2z1e1yn4cyz7", ApiResourceKind.workflow_execution],
+    ["ses_x", ApiResourceKind.session],
+    ["ida_carol", ApiResourceKind.identity_account],
+  ])("%s is %s", (id, kind) => {
+    expect(kindByIdPrefix(id)).toBe(kind);
+  });
+
+  it.each([
+    ["zzz_unknown_kind", "an unknown prefix"],
+    ["aex", "a prefix with no underscore"],
+    ["_aex", "a leading underscore names no prefix"],
+    ["", "empty"],
+    ["AEX_upper", "prefixes are lowercase in the contract"],
+    ["stk_notajwt", "an API key's prefix is not a kind"],
+  ])("%s is the unknown kind (%s) — never a throw", (id) => {
+    expect(kindByIdPrefix(id)).toBe(ApiResourceKind.api_resource_kind_unknown);
+  });
+
+  it("round-trips with getIdPrefix over every kind the contract declares", () => {
+    for (const value of ApiResourceKindSchema.values) {
+      if (!hasOption(value, kind_meta)) continue;
+      const kind = value.number as ApiResourceKind;
+      expect(kindByIdPrefix(`${getIdPrefix(kind)}_01anyulid`), value.name).toBe(
+        kind,
+      );
+    }
+  });
+
+  it("every id_prefix in the contract is unique — the table pin a duplicate must change", () => {
+    const seen = new Map<string, string>();
+    for (const value of ApiResourceKindSchema.values) {
+      if (!hasOption(value, kind_meta)) continue;
+      const prefix = getOption(value, kind_meta).idPrefix;
+      expect(prefix, `${value.name} declares no id_prefix`).not.toBe("");
+      const holder = seen.get(prefix);
+      expect(
+        holder,
+        `id_prefix '${prefix}' is declared by both ${holder} and ${value.name}`,
+      ).toBeUndefined();
+      seen.set(prefix, value.name);
+    }
+  });
+});

package/src/pipeline/apiresource-meta.ts

@@ -351,3 +351,44 @@ function kindsByEnumName(): Map<string, ApiResourceKind> {
   }
   return enumNameCache;
 }
+
+/**
+ * The kind a minted resource id belongs to, read off its prefix — the
+ * inverse of `getIdPrefix` over the ids `generateId` mints
+ * (`<prefix>_<ulid>`, pipeline/steps/defaults.ts). The one consumer today
+ * is the runner-credential lane, whose token binds an execution by id and
+ * must know whether that id names an agent execution or a workflow
+ * execution without a second claim or a guess. Anything that is not
+ * `<known prefix>_<rest>` — no underscore, an unknown prefix, the empty
+ * string — is `api_resource_kind_unknown`; never a throw, because the id
+ * arrived inside a credential and the caller refuses with its own
+ * sentence. Every `id_prefix` in the contract is unique; the table pin in
+ * __tests__ makes a future duplicate a reviewed change, since this lookup
+ * would otherwise resolve it silently to one of the two.
+ */
+export function kindByIdPrefix(id: string): ApiResourceKind {
+  const separator = id.indexOf("_");
+  if (separator <= 0) {
+    return ApiResourceKind.api_resource_kind_unknown;
+  }
+  return (
+    kindsByIdPrefix().get(id.slice(0, separator)) ??
+    ApiResourceKind.api_resource_kind_unknown
+  );
+}
+
+let idPrefixCache: Map<string, ApiResourceKind> | undefined;
+
+function kindsByIdPrefix(): Map<string, ApiResourceKind> {
+  if (idPrefixCache === undefined) {
+    idPrefixCache = new Map(
+      ApiResourceKindSchema.values
+        .filter((value) => hasOption(value, kind_meta))
+        .map((value) => [
+          getOption(value, kind_meta).idPrefix,
+          value.number as ApiResourceKind,
+        ]),
+    );
+  }
+  return idPrefixCache;
+}

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, {