@stigmer/server 3.14.0-dev.20260910084630

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

@@ -0,0 +1,128 @@
+/**
+ * Pins the C2 Stage-4 enforcement on this domain's three config-annotated
+ * direct read surfaces (subscribe, getArtifactDownloadUrl,
+ * getArtifactContent): each evaluates its OWN annotation through
+ * authorizeDirect, and a denying authorizer answers PERMISSION_DENIED
+ * with the method's byte-pinned error_msg — before any store, broker, or
+ * blob-storage touch. The exact copy doubles as the descriptor-mismatch
+ * guard. The decision 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 {
+  AgentExecutionIdSchema,
+  GetArtifactContentRequestSchema,
+  GetArtifactDownloadUrlRequestSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+
+import type { ArtifactStorage } from "../../../artifactstorage/artifact-storage.js";
+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 { getArtifactContent, getArtifactDownloadUrl } from "../artifacts.js";
+import type { StreamBroker } from "../stream-broker.js";
+import { subscribeExecution } from "../subscribe.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const denyingAuthorizer: Authorizer = {
+  authorize: () => Promise.resolve({ kind: "deny", reason: "" }),
+};
+
+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`);
+  },
+});
+
+const untouchableStorage = new Proxy({} as ArtifactStorage, {
+  get(_target, prop) {
+    throw new Error(`storage.${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);
+}
+
+const artifactDeps = {
+  store: untouchableStore,
+  logger: silentLogger,
+  artifactStorage: untouchableStorage,
+  authorizer: denyingAuthorizer,
+};
+
+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(AgentExecutionIdSchema, { value: "aexec_01denied" }),
+          handlerContext(),
+        ).next(),
+      "unauthorized to subscribe to agent execution",
+    );
+  });
+
+  it("getArtifactDownloadUrl denies with its annotation copy before the load", async () => {
+    await expectDenied(
+      () =>
+        getArtifactDownloadUrl(
+          artifactDeps,
+          create(GetArtifactDownloadUrlRequestSchema, {
+            executionId: "aexec_01denied",
+            storageKey: "artifacts/aexec_01denied/report.txt",
+          }),
+          testCallerIdentity(),
+        ),
+      "unauthorized to download artifact from agent execution",
+    );
+  });
+
+  it("getArtifactContent denies with its annotation copy before the ownership check", async () => {
+    await expectDenied(
+      () =>
+        getArtifactContent(
+          artifactDeps,
+          create(GetArtifactContentRequestSchema, {
+            executionId: "aexec_01denied",
+            storageKey: "artifacts/aexec_01denied/report.txt",
+          }),
+          testCallerIdentity(),
+        ),
+      "unauthorized to read artifact content from agent execution",
+    );
+  });
+});

package/src/domain/agentexecution/__tests__/record-runner-lineage-labels.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Pins the lineage-label vouching step (parity entry 20260830.05, the
+ * Java RecordRunnerLineageLabelsStep port): no lineage labels means no
+ * capability consult; the capability's true vouches exactly the present
+ * lineage keys (the guard then passes them while a smuggled sibling still
+ * refuses); false vouches nothing; a binding-violation throw propagates;
+ * and with no capability composed the step is a no-op — nothing vouched,
+ * today's OSS behavior.
+ */
+import { describe, expect, it } from "vitest";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { create } from "@bufbuild/protobuf";
+
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import type { CallerIdentity } from "../../../extensions/identity.js";
+import type { RunnerCredentialProvider } from "../../../runnerauth/runner-credential-provider.js";
+import { RequestContext } from "../../../pipeline/request-context.js";
+import { serverStampedReservedLabels } from "../../../pipeline/steps/server-stamped-reserved-labels.js";
+import {
+  newRecordRunnerLineageLabelsStep,
+  WORKFLOW_EXECUTION_ID_LABEL,
+  WORKFLOW_TASK_LABEL,
+} from "../record-runner-lineage-labels.js";
+
+/** A cloud-shaped runner caller (class = the token_type claim). */
+const RUNNER: CallerIdentity = {
+  identityId: "ida_runner",
+  callerClass: "workflow_sandbox",
+  issuer: "stigmer",
+  rawToken: "opaque-to-oss",
+};
+
+function executionCtx(
+  labels: Record<string, string>,
+): RequestContext<typeof AgentExecutionSchema> {
+  return new RequestContext(
+    AgentExecutionSchema,
+    create(AgentExecutionSchema, { metadata: { name: "e", labels } }),
+    RUNNER,
+    ApiResourceKind.agent_execution,
+  );
+}
+
+function providerWith(
+  vouch?: (caller: CallerIdentity, workflowExecutionId: string) => boolean,
+): RunnerCredentialProvider {
+  return {
+    isEnabled: () => false,
+    mint: () => {
+      throw new Error("not under test");
+    },
+    verify: () => {
+      throw new Error("not under test");
+    },
+    ...(vouch === undefined ? {} : { vouchRunnerLineageLabels: vouch }),
+  };
+}
+
+describe("RecordRunnerLineageLabels", () => {
+  it("consults nothing when the request carries no lineage labels", () => {
+    const step = newRecordRunnerLineageLabelsStep(
+      providerWith(() => {
+        throw new Error("must not be consulted");
+      }),
+    );
+    const ctx = executionCtx({ ordinary: "fine" });
+    step.execute(ctx);
+    expect(serverStampedReservedLabels(ctx).size).toBe(0);
+  });
+
+  it("vouches exactly the present lineage keys on true", () => {
+    const observed: string[] = [];
+    const step = newRecordRunnerLineageLabelsStep(
+      providerWith((_caller, workflowExecutionId) => {
+        observed.push(workflowExecutionId);
+        return true;
+      }),
+    );
+    const ctx = executionCtx({
+      [WORKFLOW_EXECUTION_ID_LABEL]: "wfe_1",
+      [WORKFLOW_TASK_LABEL]: "notify",
+      "stigmer.ai/default-agent": "true", // never vouched by this step
+    });
+    step.execute(ctx);
+    expect(observed).toEqual(["wfe_1"]);
+    const stamped = serverStampedReservedLabels(ctx);
+    expect(stamped.has(WORKFLOW_EXECUTION_ID_LABEL)).toBe(true);
+    expect(stamped.has(WORKFLOW_TASK_LABEL)).toBe(true);
+    expect(stamped.has("stigmer.ai/default-agent")).toBe(false);
+    expect(stamped.size).toBe(2);
+  });
+
+  it("vouches only the task key when the execution-id label is absent", () => {
+    const step = newRecordRunnerLineageLabelsStep(providerWith(() => true));
+    const ctx = executionCtx({ [WORKFLOW_TASK_LABEL]: "notify" });
+    step.execute(ctx);
+    const stamped = serverStampedReservedLabels(ctx);
+    expect(stamped.has(WORKFLOW_TASK_LABEL)).toBe(true);
+    expect(stamped.size).toBe(1);
+  });
+
+  it("vouches nothing for a non-runner credential (false)", () => {
+    const step = newRecordRunnerLineageLabelsStep(providerWith(() => false));
+    const ctx = executionCtx({ [WORKFLOW_EXECUTION_ID_LABEL]: "wfe_1" });
+    step.execute(ctx);
+    expect(serverStampedReservedLabels(ctx).size).toBe(0);
+  });
+
+  it("a binding-violation refusal propagates untouched", () => {
+    const refusal = new ConnectError(
+      "workflow lineage label names a workflow execution this runner credential is not bound to",
+      Code.InvalidArgument,
+    );
+    const step = newRecordRunnerLineageLabelsStep(
+      providerWith(() => {
+        throw refusal;
+      }),
+    );
+    let error: unknown;
+    try {
+      step.execute(executionCtx({ [WORKFLOW_EXECUTION_ID_LABEL]: "wfe_other" }));
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBe(refusal);
+  });
+
+  it("is a no-op with no capability composed — today's OSS behavior", () => {
+    const step = newRecordRunnerLineageLabelsStep(providerWith());
+    const ctx = executionCtx({ [WORKFLOW_EXECUTION_ID_LABEL]: "wfe_1" });
+    step.execute(ctx);
+    expect(serverStampedReservedLabels(ctx).size).toBe(0);
+  });
+});

package/src/domain/agentexecution/__tests__/status-observers.test.ts

@@ -0,0 +1,164 @@
+/**
+ * Pins the status-hook consumption contract (O4, 20260827.07; DD-006 §3):
+ * the Q4 firing rule (phase change only), observer ordering and isolation
+ * (a throwing/rejecting observer is logged and never fails the caller),
+ * and the decorator clone-commit posture (a throwing decorator degrades
+ * exactly ITS contribution — earlier contributions survive, the RPC never
+ * fails). The per-site wiring is pinned by the lifecycle/approval/
+ * composition suites; this file pins the shared notifier itself.
+ */
+import { create } from "@bufbuild/protobuf";
+import { describe, expect, it } from "vitest";
+
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import {
+  ExecutionControlSignal,
+  ExecutionPhase,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { UpdateStatusResponseSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+
+import type { Logger } from "../../../boot/logger.js";
+import type { AgentExecutionStatusTransition } from "../../../extensions/status-hooks.js";
+import {
+  applyResponseDecorators,
+  notifyStatusObservers,
+} from "../status-observers.js";
+
+function silentLoggerWithCapture(): { logger: Logger; warnings: string[] } {
+  const warnings: string[] = [];
+  const logger = {
+    debug: () => {},
+    info: () => {},
+    warn: (msg: string) => {
+      warnings.push(msg);
+    },
+    error: () => {},
+  } as unknown as Logger;
+  return { logger, warnings };
+}
+
+function execution(id: string) {
+  return create(AgentExecutionSchema, { metadata: { id, name: id } });
+}
+
+describe("notifyStatusObservers", () => {
+  it("fires only when the phase actually changed (ruling Q4)", async () => {
+    const seen: AgentExecutionStatusTransition[] = [];
+    const { logger } = silentLoggerWithCapture();
+    const deps = {
+      statusObservers: [
+        (t: AgentExecutionStatusTransition) => void seen.push(t),
+      ],
+      logger,
+    };
+
+    await notifyStatusObservers(
+      deps,
+      execution("aexec_same"),
+      ExecutionPhase.EXECUTION_IN_PROGRESS,
+      ExecutionPhase.EXECUTION_IN_PROGRESS,
+    );
+    expect(seen).toHaveLength(0);
+
+    await notifyStatusObservers(
+      deps,
+      execution("aexec_changed"),
+      ExecutionPhase.EXECUTION_IN_PROGRESS,
+      ExecutionPhase.EXECUTION_COMPLETED,
+    );
+    expect(seen).toHaveLength(1);
+    expect(seen[0]?.oldPhase).toBe(ExecutionPhase.EXECUTION_IN_PROGRESS);
+    expect(seen[0]?.newPhase).toBe(ExecutionPhase.EXECUTION_COMPLETED);
+    expect(seen[0]?.execution.metadata?.id).toBe("aexec_changed");
+  });
+
+  it("runs observers in registration order, awaiting each", async () => {
+    const order: string[] = [];
+    const { logger } = silentLoggerWithCapture();
+    await notifyStatusObservers(
+      {
+        statusObservers: [
+          async () => {
+            // A microtask delay: were observers not awaited in order, the
+            // second (synchronous) observer would record first.
+            await Promise.resolve();
+            order.push("first");
+          },
+          () => void order.push("second"),
+        ],
+        logger,
+      },
+      execution("aexec_order"),
+      ExecutionPhase.EXECUTION_IN_PROGRESS,
+      ExecutionPhase.EXECUTION_FAILED,
+    );
+    expect(order).toEqual(["first", "second"]);
+  });
+
+  it("logs a throwing or rejecting observer and keeps going — never a failed transition", async () => {
+    const seen: string[] = [];
+    const { logger, warnings } = silentLoggerWithCapture();
+    await expect(
+      notifyStatusObservers(
+        {
+          statusObservers: [
+            () => {
+              throw new Error("sync extension bug");
+            },
+            () => Promise.reject(new Error("async extension bug")),
+            () => void seen.push("healthy"),
+          ],
+          logger,
+        },
+        execution("aexec_faulty"),
+        ExecutionPhase.EXECUTION_IN_PROGRESS,
+        ExecutionPhase.EXECUTION_CANCELLED,
+      ),
+    ).resolves.toBeUndefined();
+    expect(seen).toEqual(["healthy"]);
+    expect(warnings).toHaveLength(2);
+  });
+});
+
+describe("applyResponseDecorators", () => {
+  it("commits each successful decorator's contribution to the reply", async () => {
+    const { logger } = silentLoggerWithCapture();
+    const decorated = await applyResponseDecorators(
+      [
+        (_execution, response) => {
+          response.signal = ExecutionControlSignal.STOP;
+        },
+      ],
+      logger,
+      execution("aexec_dec"),
+      create(UpdateStatusResponseSchema, {
+        signal: ExecutionControlSignal.UNSPECIFIED,
+      }),
+    );
+    expect(decorated.signal).toBe(ExecutionControlSignal.STOP);
+  });
+
+  it("degrades exactly the throwing decorator's contribution, keeping earlier ones", async () => {
+    const { logger, warnings } = silentLoggerWithCapture();
+    const decorated = await applyResponseDecorators(
+      [
+        (_execution, response) => {
+          response.signal = ExecutionControlSignal.STOP;
+        },
+        (_execution, response) => {
+          // Writes before throwing — the clone-commit posture must
+          // discard this partial write, not ship it.
+          response.signal = ExecutionControlSignal.UNSPECIFIED;
+          throw new Error("decorator bug");
+        },
+      ],
+      logger,
+      execution("aexec_partial"),
+      create(UpdateStatusResponseSchema, {
+        signal: ExecutionControlSignal.UNSPECIFIED,
+      }),
+    );
+    expect(decorated.signal).toBe(ExecutionControlSignal.STOP);
+    expect(warnings).toHaveLength(1);
+  });
+});

package/src/domain/agentexecution/__tests__/stream-broker.test.ts

@@ -0,0 +1,119 @@
+/**
+ * Pins the StreamBroker delivery semantics (stream_broker.go): bounded
+ * per-subscriber buffering with drop-on-full (never blocking a
+ * broadcast), notify-on-push, idempotent unsubscribe with close
+ * signaling, and per-execution isolation.
+ */
+import { create } from "@bufbuild/protobuf";
+import { describe, expect, it } from "vitest";
+
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+
+import { createLogger } from "../../../boot/logger.js";
+import {
+  StreamBroker,
+  SUBSCRIBER_BUFFER_CAPACITY,
+} from "../stream-broker.js";
+
+function capturingLogger() {
+  const lines: Array<{ level: string; message: string }> = [];
+  return {
+    lines,
+    logger: createLogger({
+      level: "debug",
+      pretty: false,
+      write: (line) =>
+        lines.push(JSON.parse(line) as { level: string; message: string }),
+    }),
+  };
+}
+
+function frame(id: string, error = "") {
+  return create(AgentExecutionSchema, {
+    metadata: { id },
+    status: { error },
+  });
+}
+
+describe("StreamBroker", () => {
+  it("delivers to every subscriber of the execution, none of another's", () => {
+    const { logger } = capturingLogger();
+    const broker = new StreamBroker(logger);
+    const a1 = broker.subscribe("aexec_a");
+    const a2 = broker.subscribe("aexec_a");
+    const b = broker.subscribe("aexec_b");
+
+    broker.broadcast(frame("aexec_a"));
+
+    expect(a1.queue).toHaveLength(1);
+    expect(a2.queue).toHaveLength(1);
+    expect(b.queue).toHaveLength(0);
+    expect(broker.getSubscriberCount("aexec_a")).toBe(2);
+  });
+
+  it("wakes a parked consumer exactly once per push", () => {
+    const { logger } = capturingLogger();
+    const broker = new StreamBroker(logger);
+    const sub = broker.subscribe("aexec_x");
+
+    let woken = 0;
+    sub.notify = () => {
+      woken += 1;
+    };
+    broker.broadcast(frame("aexec_x"));
+
+    expect(woken).toBe(1);
+    // The broker clears the hook after firing (one-shot, like the
+    // generator re-arms it per wait).
+    expect(sub.notify).toBeUndefined();
+  });
+
+  it("drops the frame for a full subscriber and warns (never blocks)", () => {
+    const { logger, lines } = capturingLogger();
+    const broker = new StreamBroker(logger);
+    const sub = broker.subscribe("aexec_full");
+
+    for (let i = 0; i < SUBSCRIBER_BUFFER_CAPACITY; i++) {
+      broker.broadcast(frame("aexec_full", `frame-${i}`));
+    }
+    expect(sub.queue).toHaveLength(SUBSCRIBER_BUFFER_CAPACITY);
+
+    broker.broadcast(frame("aexec_full", "overflow"));
+    expect(sub.queue).toHaveLength(SUBSCRIBER_BUFFER_CAPACITY);
+    expect(sub.queue.at(-1)?.status?.error).toBe(
+      `frame-${SUBSCRIBER_BUFFER_CAPACITY - 1}`,
+    );
+    expect(
+      lines.some((l) => l.message.includes("Subscriber channel full")),
+    ).toBe(true);
+  });
+
+  it("unsubscribe closes, wakes, cleans the map, and is idempotent", () => {
+    const { logger } = capturingLogger();
+    const broker = new StreamBroker(logger);
+    const sub = broker.subscribe("aexec_gone");
+
+    let woken = false;
+    sub.notify = () => {
+      woken = true;
+    };
+    broker.unsubscribe("aexec_gone", sub);
+
+    expect(sub.closed).toBe(true);
+    expect(woken, "a parked consumer observes the close").toBe(true);
+    expect(broker.getSubscriberCount("aexec_gone")).toBe(0);
+
+    // Idempotent; a post-close broadcast reaches nobody and throws nothing.
+    broker.unsubscribe("aexec_gone", sub);
+    broker.broadcast(frame("aexec_gone"));
+    expect(sub.queue).toHaveLength(0);
+  });
+
+  it("ignores frames without a metadata id (Go's nil guard)", () => {
+    const { logger } = capturingLogger();
+    const broker = new StreamBroker(logger);
+    const sub = broker.subscribe("");
+    broker.broadcast(create(AgentExecutionSchema, {}));
+    expect(sub.queue).toHaveLength(0);
+  });
+});