@stigmer/server 3.39.0 → 3.39.1-dev.20260928194002

package/src/domain/skill/controller.ts

@@ -99,6 +99,7 @@ import { newGuardReservedLabelsStep } from "../../pipeline/steps/guard-reserved-
 import { newValidateProtoStep } from "../../pipeline/steps/validation.js";
 import { newValidateVisibilityUpdateStep } from "../../pipeline/steps/validate-visibility.js";
 import { newDeleteVersionArchivesStep } from "../../pipeline/steps/version-archive.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import { MAX_ZIP_SIZE, TRANSFER_LANE_NOT_CONFIGURED } from "./constants.js";
 import {
@@ -463,7 +464,7 @@ async function updateVisibility(
   return reqCtx.get(UPDATE_VISIBILITY_SKILL_KEY) as Skill;
 }
 
-/** Loads the skill by resource_id; ANY load failure → NotFound. */
+/** Loads the skill by resource_id; a missing one answers NotFound, a store fault Internal. */
 function newLoadSkillForVisibilityUpdateStep(
   store: Store,
 ): PipelineStep<UpdateVisibilityDesc> {
@@ -478,8 +479,11 @@ function newLoadSkillForVisibilityUpdateStep(
           input.resourceId,
           SkillSchema,
         );
-      } catch {
-        throw notFoundError("skill", input.resourceId);
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          throw notFoundError("skill", input.resourceId);
+        }
+        throw internalError(error, "failed to load skill");
       }
       ctx.set(UPDATE_VISIBILITY_SKILL_KEY, skill);
     },

package/src/domain/workflow/__tests__/store-faults.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Pins the store-fault contract of the workflow's visibility-update load: a
+ * typed ResourceNotFoundError answers NotFound with the domain's pinned copy
+ * (`workflow not found: <id>`), and any other store failure is an
+ * infrastructure fault answered as a sanitized Internal, never a NotFound that
+ * tells a client the workflow does not exist (stigmer/stigmer#1345).
+ *
+ * The surface is updateVisibility, reached through the registered handler on
+ * an in-process router. The composed suites reach only a real store, which
+ * cannot fail selectively, so it runs here against a store whose read throws.
+ * The validator and the default-instance creator are untouchable: a load that
+ * fails must stop the call before anything past it runs.
+ *
+ * Out of scope: the NotFound copy itself (wire contract).
+ */
+import type { Client, ConnectError } from "@connectrpc/connect";
+import { Code, createClient, createRouterTransport } from "@connectrpc/connect";
+import { describe, expect, it } from "vitest";
+
+import { WorkflowCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/command_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+
+import { createLogger } from "../../../boot/logger.js";
+import { createApiResourceInterceptor } from "../../../pipeline/interceptors/apiresource.js";
+import { createVerifierChainInterceptor } from "../../../pipeline/interceptors/auth.js";
+import {
+  errorOf,
+  failingStore,
+  untouchable,
+} from "../../../pipeline/__tests__/support.js";
+import { newPermissiveSingleTeamAuthorizer } from "../../../pipeline/steps/authorize.js";
+import { ResourceNotFoundError } from "../../../store/interface.js";
+import type { Store } from "../../../store/interface.js";
+
+import { registerWorkflowServices } from "../controller.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const WORKFLOW_ID = "wfl_storefault";
+
+const NOT_FOUND_COPY = `workflow not found: ${WORKFLOW_ID}`;
+const LOAD_FAULT_COPY = "failed to load workflow";
+
+const MISSING = (): Error =>
+  new ResourceNotFoundError(`workflow/${WORKFLOW_ID}`);
+const LOCKED = (): Error => new Error("SQLITE_BUSY: database is locked");
+
+/**
+ * The registered handlers on an in-process router: the verifier chain stamps
+ * the trusted-local caller and the apiresource interceptor the kind, then
+ * Authorize and ValidateProto run and the load is the first step that reads
+ * the store.
+ */
+function workflowCommand(
+  store: Store,
+): Client<typeof WorkflowCommandController> {
+  const transport = createRouterTransport(
+    (router) => {
+      registerWorkflowServices(router, {
+        store,
+        logger: silentLogger,
+        authorizer: newPermissiveSingleTeamAuthorizer(),
+        authorizationLifecycle: undefined,
+        validator: untouchable("validator"),
+        workflowInstanceCreator: untouchable("workflowInstanceCreator"),
+      });
+    },
+    {
+      router: {
+        interceptors: [
+          createVerifierChainInterceptor([], [], silentLogger),
+          createApiResourceInterceptor(),
+        ],
+      },
+    },
+  );
+  return createClient(WorkflowCommandController, transport);
+}
+
+describe("updateVisibility — LoadWorkflowForVisibilityUpdate", () => {
+  function surfaceError(store: Store): Promise<ConnectError> {
+    return errorOf(() =>
+      workflowCommand(store).updateVisibility({
+        resourceId: WORKFLOW_ID,
+        visibility: ApiResourceVisibility.visibility_private,
+      }),
+    );
+  }
+
+  it("a missing workflow answers NotFound with the domain's copy", async () => {
+    const error = await surfaceError(failingStore(MISSING()));
+
+    expect(error.code).toBe(Code.NotFound);
+    expect(error.rawMessage).toBe(NOT_FOUND_COPY);
+  });
+
+  it("any other store failure answers a sanitized Internal", async () => {
+    const error = await surfaceError(failingStore(LOCKED()));
+
+    expect(error.code).toBe(Code.Internal);
+    expect(error.rawMessage).toBe(LOAD_FAULT_COPY);
+  });
+});

package/src/domain/workflow/controller.ts

@@ -492,7 +492,7 @@ async function updateVisibility(
   return reqCtx.get(UPDATE_VISIBILITY_WORKFLOW_KEY) as Workflow;
 }
 
-/** Loads the workflow by resource_id; ANY load failure → NotFound. */
+/** Loads the workflow by resource_id; a missing one answers NotFound, a store fault Internal. */
 function newLoadWorkflowForVisibilityUpdateStep(
   store: Store,
 ): PipelineStep<UpdateVisibilityDesc> {
@@ -507,8 +507,11 @@ function newLoadWorkflowForVisibilityUpdateStep(
           input.resourceId,
           WorkflowSchema,
         );
-      } catch {
-        throw notFoundError("workflow", input.resourceId);
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          throw notFoundError("workflow", input.resourceId);
+        }
+        throw internalError(error, "failed to load workflow");
       }
       ctx.set(UPDATE_VISIBILITY_WORKFLOW_KEY, workflow);
     },

package/src/domain/workflowinstance/__tests__/store-faults.test.ts

@@ -0,0 +1,172 @@
+/**
+ * Pins the store-fault contract of the workflow instance's loads. The shared
+ * targeted-update load (updateVisibility and updateExecutionVisibility): a
+ * typed ResourceNotFoundError answers NotFound with the domain's pinned copy
+ * (`workflow instance not found: <id>`), and any other store failure is an
+ * infrastructure fault answered as a sanitized Internal, never a NotFound that
+ * tells a client the instance does not exist (stigmer/stigmer#1345). Create's
+ * parent-workflow load reads the workflow through the in-process query
+ * client, so the store's typed miss arrives as a Connect NotFound: that
+ * answers the pinned `Workflow not found: <id>`, and any other failure an
+ * Internal, never a missing parent (stigmer/stigmer#1351).
+ *
+ * Every surface is reached through the registered handler on an in-process
+ * router. The composed suites reach only a real store, which cannot fail
+ * selectively, so the updates run against a store whose read throws and
+ * create against a parent loader whose read throws. Whatever the surface does
+ * not need is untouchable: a load that fails must stop the call before
+ * anything past it runs.
+ *
+ * Out of scope: the NotFound copies themselves (wire contract).
+ */
+import type { Client } from "@connectrpc/connect";
+import {
+  Code,
+  ConnectError,
+  createClient,
+  createRouterTransport,
+} from "@connectrpc/connect";
+import { describe, expect, it } from "vitest";
+
+import { WorkflowInstanceCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/command_pb";
+import { WorkflowExecutionVisibility } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/spec_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+
+import { createLogger } from "../../../boot/logger.js";
+import { createApiResourceInterceptor } from "../../../pipeline/interceptors/apiresource.js";
+import { createVerifierChainInterceptor } from "../../../pipeline/interceptors/auth.js";
+import {
+  errorOf,
+  failingStore,
+  untouchable,
+} from "../../../pipeline/__tests__/support.js";
+import { INTERNAL_FALLBACK_MESSAGE } from "../../../pipeline/pipeline.js";
+import { newPermissiveSingleTeamAuthorizer } from "../../../pipeline/steps/authorize.js";
+import { ResourceNotFoundError } from "../../../store/interface.js";
+import type { Store } from "../../../store/interface.js";
+
+import { registerWorkflowInstanceServices } from "../controller.js";
+import type { ParentWorkflowLoaderProvider } from "../steps.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const INSTANCE_ID = "win_storefault";
+const WORKFLOW_ID = "wfl_storefault";
+
+const NOT_FOUND_COPY = `workflow instance not found: ${INSTANCE_ID}`;
+const LOAD_FAULT_COPY = "failed to load workflow instance";
+const PARENT_NOT_FOUND_COPY = `Workflow not found: ${WORKFLOW_ID}`;
+const PARENT_LOAD_FAULT_COPY = "failed to load parent workflow";
+
+const MISSING = (): Error =>
+  new ResourceNotFoundError(`workflow_instance/${INSTANCE_ID}`);
+const LOCKED = (): Error => new Error("SQLITE_BUSY: database is locked");
+
+/** What the workflow query's `get` answers for a missing and a faulted workflow. */
+const PARENT_MISSING = (): Error =>
+  new ConnectError(`Workflow not found: ${WORKFLOW_ID}`, Code.NotFound);
+const PARENT_FAULTED = (): Error =>
+  new ConnectError(INTERNAL_FALLBACK_MESSAGE, Code.Internal);
+
+/**
+ * The registered handlers on an in-process router: the verifier chain stamps
+ * the trusted-local caller and the apiresource interceptor the kind, then
+ * Authorize and ValidateProto run and the load is the first step that reads
+ * the store or the parent.
+ */
+function instanceCommand(
+  store: Store,
+  parentWorkflowLoader: ParentWorkflowLoaderProvider = untouchable(
+    "parentWorkflowLoader",
+  ),
+): Client<typeof WorkflowInstanceCommandController> {
+  const transport = createRouterTransport(
+    (router) => {
+      registerWorkflowInstanceServices(router, {
+        store,
+        logger: silentLogger,
+        authorizer: newPermissiveSingleTeamAuthorizer(),
+        authorizationLifecycle: undefined,
+        parentWorkflowLoader,
+        listReadScope: undefined,
+      });
+    },
+    {
+      router: {
+        interceptors: [
+          createVerifierChainInterceptor([], [], silentLogger),
+          createApiResourceInterceptor(),
+        ],
+      },
+    },
+  );
+  return createClient(WorkflowInstanceCommandController, transport);
+}
+
+describe.each([
+  {
+    surface: "updateVisibility — LoadInstanceForVisibilityUpdate",
+    call: (store: Store) =>
+      instanceCommand(store).updateVisibility({
+        resourceId: INSTANCE_ID,
+        visibility: ApiResourceVisibility.visibility_private,
+      }),
+  },
+  {
+    surface:
+      "updateExecutionVisibility — LoadInstanceForExecutionVisibilityUpdate",
+    call: (store: Store) =>
+      instanceCommand(store).updateExecutionVisibility({
+        resourceId: INSTANCE_ID,
+        executionVisibility: WorkflowExecutionVisibility.private,
+      }),
+  },
+])("$surface", ({ call }) => {
+  it("a missing workflow instance answers NotFound with the domain's copy", async () => {
+    const error = await errorOf(() => call(failingStore(MISSING())));
+
+    expect(error.code).toBe(Code.NotFound);
+    expect(error.rawMessage).toBe(NOT_FOUND_COPY);
+  });
+
+  it("any other store failure answers a sanitized Internal", async () => {
+    const error = await errorOf(() => call(failingStore(LOCKED())));
+
+    expect(error.code).toBe(Code.Internal);
+    expect(error.rawMessage).toBe(LOAD_FAULT_COPY);
+  });
+});
+
+describe("create — LoadParentWorkflow", () => {
+  function surfaceError(parentError: Error): Promise<ConnectError> {
+    const failingParent: ParentWorkflowLoaderProvider = () => ({
+      get: () => Promise.reject(parentError),
+    });
+    return errorOf(() =>
+      instanceCommand(untouchable("store"), failingParent).create({
+        apiVersion: "agentic.stigmer.ai/v1",
+        kind: "WorkflowInstance",
+        metadata: { name: "Store Fault Instance", org: "org_storefault" },
+        spec: { workflowId: WORKFLOW_ID },
+      }),
+    );
+  }
+
+  it("a missing parent workflow answers NotFound with the pinned copy", async () => {
+    const error = await surfaceError(PARENT_MISSING());
+
+    expect(error.code).toBe(Code.NotFound);
+    expect(error.rawMessage).toBe(PARENT_NOT_FOUND_COPY);
+  });
+
+  it("any other parent-load failure answers a sanitized Internal", async () => {
+    const error = await surfaceError(PARENT_FAULTED());
+
+    expect(error.code).toBe(Code.Internal);
+    expect(error.rawMessage).toBe(PARENT_LOAD_FAULT_COPY);
+  });
+});

package/src/domain/workflowinstance/controller.ts

@@ -13,8 +13,8 @@
  *
  * Pipeline per RPC mirrors the Go step chains character-for-character.
  * Proven by workflowinstance.conformance.test.ts
- * (CONFORMANCE_TARGET=local) and the family test
- * ../workflow/__tests__/workflow.test.ts (the mutual edge makes the two
+ * (CONFORMANCE_TARGET=local), __tests__/store-faults.test.ts and the family
+ * test ../workflow/__tests__/workflow.test.ts (the mutual edge makes the two
  * domains one testable unit).
  */
 import type { ConnectRouter, HandlerContext } from "@connectrpc/connect";
@@ -104,6 +104,7 @@ import {
   newValidateVisibilityStep,
   newValidateVisibilityUpdateStep,
 } from "../../pipeline/steps/validate-visibility.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import { workflowInstanceSearchExtractor } from "./search-extractor.js";
 import {
@@ -573,9 +574,10 @@ function newSetInstanceExecutionVisibilityStep(): PipelineStep<UpdateExecutionVi
 // ---------------------------------------------------------------------------
 
 /**
- * Loads the instance by resource_id; ANY load failure → NotFound. The
- * accessor keeps the input shape compiler-checked (both targeted-update
- * inputs carry resource_id, but the compiler should prove it, not a cast).
+ * Loads the instance by resource_id; a missing one answers NotFound, a store
+ * fault Internal. The accessor keeps the input shape compiler-checked (both
+ * targeted-update inputs carry resource_id, but the compiler should prove it,
+ * not a cast).
  */
 function newLoadInstanceStep<Desc extends DescMessage>(
   store: Store,
@@ -594,8 +596,11 @@ function newLoadInstanceStep<Desc extends DescMessage>(
           resourceId,
           WorkflowInstanceSchema,
         );
-      } catch {
-        throw notFoundError("workflow instance", resourceId);
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          throw notFoundError("workflow instance", resourceId);
+        }
+        throw internalError(error, "failed to load workflow instance");
       }
       ctx.set(instanceKey, instance);
     },

package/src/domain/workflowinstance/steps.ts

@@ -8,7 +8,7 @@
  * the family test ../workflow/__tests__/workflow.test.ts (the mutual edge
  * makes the two domains one testable unit).
  */
-import { ConnectError } from "@connectrpc/connect";
+import { Code, ConnectError } from "@connectrpc/connect";
 import type { DescMessage } from "@bufbuild/protobuf";
 
 import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
@@ -55,9 +55,11 @@ export type ParentWorkflowLoaderProvider = () => ParentWorkflowLoader;
 
 /**
  * LoadParentWorkflow — create.go: loads the workflow the instance
- * materializes and stashes it for the same-org rule. ANY load failure maps
- * to NotFound("Workflow", id) — Go folds every client error into that arm
- * (capital-W copy is the wire contract).
+ * materializes and stashes it for the same-org rule. The workflow is read
+ * through the in-process query client, so a missing one arrives as a Connect
+ * NotFound and answers NotFound("Workflow", id) (the capital-W copy is the
+ * wire contract); any other failure is a fault answered as Internal, never a
+ * missing parent.
  */
 export function newLoadParentWorkflowStep(
   loaderProvider: ParentWorkflowLoaderProvider,
@@ -74,12 +76,14 @@ export function newLoadParentWorkflowStep(
       try {
         parent = await loaderProvider().get(workflowId);
       } catch (error) {
-        logger.warn("Parent workflow not found", {
-          error:
-            error instanceof ConnectError ? error.rawMessage : String(error),
-          workflowId,
-        });
-        throw notFoundError("Workflow", workflowId);
+        if (error instanceof ConnectError && error.code === Code.NotFound) {
+          logger.warn("Parent workflow not found", {
+            error: error.rawMessage,
+            workflowId,
+          });
+          throw notFoundError("Workflow", workflowId);
+        }
+        throw internalError(error, "failed to load parent workflow");
       }
 
       ctx.set(PARENT_WORKFLOW_KEY, parent);

package/src/pipeline/__tests__/blind-not-found.test.ts

@@ -20,9 +20,8 @@
  *
  * The scan parses each module with the TypeScript compiler API rather than a
  * regular expression, because a catch block's extent (nested braces, a log
- * line before the throw) is a syntax question. `PENDING` is the list of known
- * blind sites still to be fixed; the scan must equal it exactly, so a new
- * blind site fails here, and so does a fixed site still listed.
+ * line before the throw) is a syntax question. The scan must find no blind
+ * site at all, so a new one fails here with its module and line.
  */
 import { readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
@@ -34,19 +33,6 @@ import { describe, expect, it } from "vitest";
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const SRC = path.resolve(HERE, "../..");
 
-/** Known blind sites by module (relative to `src`), with their count. */
-const PENDING: ReadonlyMap<string, number> = new Map([
-  // Store loads, stigmer/stigmer#1345 (fixed domain by domain).
-  ["domain/plugin/controller.ts", 1],
-  ["domain/skill/controller.ts", 1],
-  ["domain/workflow/controller.ts", 1],
-  ["domain/workflowinstance/controller.ts", 1],
-  // Parent loads through the in-process chain that fold every RPC error,
-  // validation included, stigmer/stigmer#1351.
-  ["domain/agentinstance/steps.ts", 1],
-  ["domain/workflowinstance/steps.ts", 1],
-]);
-
 interface BlindSite {
   readonly module: string;
   readonly line: number;
@@ -258,7 +244,7 @@ describe("the blind-NotFound rule", () => {
 });
 
 describe("the server source", () => {
-  it("has no blind NotFound beyond the pending list, and the list names only live sites", () => {
+  it("has no blind NotFound", () => {
     const sources = serverSources();
     const constructors = notFoundConstructors(sources);
     const found = new Map<string, number[]>();
@@ -278,8 +264,6 @@ describe("the server source", () => {
     const where = [...found]
       .flatMap(([module, lines]) => lines.map((line) => `${module}:${line}`))
       .join("\n");
-    expect(counts, `blind NotFound sites found:\n${where}`).toEqual(
-      Object.fromEntries(PENDING),
-    );
+    expect(counts, `blind NotFound sites found:\n${where}`).toEqual({});
   });
 });