@stigmer/server 3.38.3 → 3.39.1-dev.20260928194002

package/src/domain/organization/steps.ts

@@ -10,9 +10,11 @@
  * uniqueness guarantee, mirroring cloud's OrganizationCreateHandler
  * (CheckDuplicate + CopySlugToId) step-for-step.
  *
- * The same deviation shapes the delete: a freed slug is anyone's to take,
- * so newRevokeOrganizationPoliciesStep revokes the organization's policy
- * rows BEFORE its row is deleted, and fails the delete when it cannot.
+ * The same deviation shapes the delete. A slug is never taken twice
+ * (slug-ledger.ts), and newRevokeOrganizationPoliciesStep still revokes
+ * the organization's policy rows BEFORE its row is deleted, and fails the
+ * delete when it cannot, so nothing that grants on the organization
+ * outlives it.
  *
  * Proven by organization.conformance.test.ts (CONFORMANCE_TARGET=local),
  * __tests__/organization.test.ts and __tests__/organization-delete.test.ts.
@@ -28,6 +30,7 @@ import type { RequestContext } from "../../pipeline/request-context.js";
 import { EXISTING_RESOURCE_KEY } from "../../pipeline/steps/load-existing.js";
 import { metadataOf } from "../../pipeline/steps/shapes.js";
 import type { IamPolicyGrantPath } from "../iampolicy/grant-path.js";
+import { refusalForHeldSlug } from "./slug-ledger.js";
 
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { ApiResourceRefSchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
@@ -48,6 +51,13 @@ import { OrganizationSchema } from "@stigmer/protos/ai/stigmer/tenancy/organizat
  * organization. Checking existence by id (== the resolved slug) closes
  * that hole and mirrors cloud's OrganizationCreateHandler.CheckDuplicate.
  *
+ * A slug is taken for good (slug-ledger.ts), so the slug ledger is read
+ * first: a retired slug is refused with the reserved reason, a held one
+ * with the duplicate copy. The row is read after it for an organization no
+ * ledger entry records yet, one an older binary created during a rolling
+ * upgrade. This read is the early refusal, before any gate; the atomic
+ * guarantee is ClaimOrganizationSlug's, immediately before Persist.
+ *
  * Runs after ResolveSlug (slug is set) and before BuildNewState/
  * CopySlugToId (the id is not yet minted), so it keys on the slug value
  * that will become the id.
@@ -70,6 +80,16 @@ export function newCheckOrgDuplicateStep(
         throw internalError(new Error("organization slug is empty"), "duplicate check");
       }
 
+      let entry;
+      try {
+        entry = await store.organizationSlugs.find(metadata.slug);
+      } catch (error) {
+        throw internalError(error, "failed to check for duplicate organization");
+      }
+      if (entry !== undefined) {
+        throw refusalForHeldSlug(entry);
+      }
+
       try {
         await store.getResource(
           ctx.apiResourceKind,
@@ -120,9 +140,11 @@ export function newCopySlugToIdStep(): PipelineStep<typeof OrganizationSchema> {
  *
  * The generic delete chains clean up after the row and log a fault,
  * because a deleted resource's rows grant nothing once it is gone. An
- * organization is the exception: its id is its slug, the delete frees the
- * slug, and a row left behind would grant whoever creates the slug next.
- * So this step does not catch. A fault fails the delete with the
+ * organization is the exception: its rows are the grants on the tenancy
+ * root itself, and the scope link of every resource under it. The slug is
+ * never taken again (slug-ledger.ts), so they cannot pass to a new holder,
+ * but a row left behind would still be a grant nobody administers. So this
+ * step does not catch. A fault fails the delete with the
  * organization in place, and a retry resumes where the revocation stopped
  * (the grant path revokes the organization's owners last, so the owner
  * who retries still can). The grant path fires the composed driver's

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

@@ -0,0 +1,104 @@
+/**
+ * Pins the store-fault contract of the plugin's visibility-update load: a
+ * typed ResourceNotFoundError answers NotFound with the domain's pinned copy
+ * (`plugin 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 plugin 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 archive store and the member materializer are untouchable: a load that
+ * fails must stop the call before the plugin's level fans out to its members.
+ *
+ * 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 { PluginCommandController } from "@stigmer/protos/ai/stigmer/agentic/plugin/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 { registerPluginServices } from "../controller.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const PLUGIN_ID = "plg_storefault";
+
+const NOT_FOUND_COPY = `plugin not found: ${PLUGIN_ID}`;
+const LOAD_FAULT_COPY = "failed to load plugin";
+
+const MISSING = (): Error => new ResourceNotFoundError(`plugin/${PLUGIN_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 pluginCommand(store: Store): Client<typeof PluginCommandController> {
+  const transport = createRouterTransport(
+    (router) => {
+      registerPluginServices(router, {
+        store,
+        logger: silentLogger,
+        authorizer: newPermissiveSingleTeamAuthorizer(),
+        authorizationLifecycle: undefined,
+        artifactStorage: untouchable("artifactStorage"),
+        materializerProvider: untouchable("materializerProvider"),
+      });
+    },
+    {
+      router: {
+        interceptors: [
+          createVerifierChainInterceptor([], [], silentLogger),
+          createApiResourceInterceptor(),
+        ],
+      },
+    },
+  );
+  return createClient(PluginCommandController, transport);
+}
+
+describe("updateVisibility — LoadPluginForVisibilityUpdate", () => {
+  function surfaceError(store: Store): Promise<ConnectError> {
+    return errorOf(() =>
+      pluginCommand(store).updateVisibility({
+        resourceId: PLUGIN_ID,
+        visibility: ApiResourceVisibility.visibility_private,
+      }),
+    );
+  }
+
+  it("a missing plugin 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/plugin/controller.ts

@@ -16,8 +16,9 @@
  * in-process clients it rides exist only after the routes this controller
  * is registered in.
  *
- * Proven by __tests__/plugin.test.ts (composed-server round-trips) and
- * plugin.conformance.test.ts (CONFORMANCE_TARGET=local, local-postgres).
+ * Proven by __tests__/plugin.test.ts (composed-server round-trips),
+ * __tests__/store-faults.test.ts and plugin.conformance.test.ts
+ * (CONFORMANCE_TARGET=local, local-postgres).
  */
 import { create, fromBinary } from "@bufbuild/protobuf";
 import type { ConnectRouter, HandlerContext } from "@connectrpc/connect";
@@ -104,6 +105,7 @@ import {
 } from "../../pipeline/steps/authorize-resolved-target.js";
 import type { VersionHistoryBinding } from "../../pipeline/steps/version-history.js";
 import { metadataOf } from "../../pipeline/steps/shapes.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import type {
   ArchiveStaging,
@@ -386,7 +388,7 @@ async function updateVisibility(
   return reqCtx.get(UPDATE_VISIBILITY_PLUGIN_KEY) as Plugin;
 }
 
-/** Loads the plugin by resource_id; ANY load failure → NotFound. */
+/** Loads the plugin by resource_id; a missing one answers NotFound, a store fault Internal. */
 function newLoadPluginByIdStep(
   store: Store,
   key: string,
@@ -401,8 +403,11 @@ function newLoadPluginByIdStep(
           ctx.input.resourceId,
           PluginSchema,
         );
-      } catch {
-        throw notFoundError("plugin", ctx.input.resourceId);
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          throw notFoundError("plugin", ctx.input.resourceId);
+        }
+        throw internalError(error, "failed to load plugin");
       }
       ctx.set(key, plugin);
     },

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

@@ -0,0 +1,103 @@
+/**
+ * Pins the store-fault contract of the skill's visibility-update load: a
+ * typed ResourceNotFoundError answers NotFound with the domain's pinned copy
+ * (`skill 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 skill 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 artifact storage is 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 { SkillCommandController } from "@stigmer/protos/ai/stigmer/agentic/skill/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 { registerSkillServices } from "../controller.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const SKILL_ID = "skl_storefault";
+
+const NOT_FOUND_COPY = `skill not found: ${SKILL_ID}`;
+const LOAD_FAULT_COPY = "failed to load skill";
+
+const MISSING = (): Error => new ResourceNotFoundError(`skill/${SKILL_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 skillCommand(store: Store): Client<typeof SkillCommandController> {
+  const transport = createRouterTransport(
+    (router) => {
+      registerSkillServices(router, {
+        store,
+        logger: silentLogger,
+        authorizer: newPermissiveSingleTeamAuthorizer(),
+        authorizationLifecycle: undefined,
+        artifactStorage: untouchable("artifactStorage"),
+      });
+    },
+    {
+      router: {
+        interceptors: [
+          createVerifierChainInterceptor([], [], silentLogger),
+          createApiResourceInterceptor(),
+        ],
+      },
+    },
+  );
+  return createClient(SkillCommandController, transport);
+}
+
+describe("updateVisibility — LoadSkillForVisibilityUpdate", () => {
+  function surfaceError(store: Store): Promise<ConnectError> {
+    return errorOf(() =>
+      skillCommand(store).updateVisibility({
+        resourceId: SKILL_ID,
+        visibility: ApiResourceVisibility.visibility_private,
+      }),
+    );
+  }
+
+  it("a missing skill 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/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);
+  });
+});