@stigmer/server 3.38.2 → 3.39.0

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

@@ -0,0 +1,110 @@
+/**
+ * Pins the store-fault contract of the agent instance's visibility-update
+ * load: a typed ResourceNotFoundError answers NotFound with the domain's
+ * pinned copy (`agent 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).
+ *
+ * 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 parent-agent loader is untouchable: a load that fails must stop the
+ * call before anything past it runs.
+ *
+ * Out of scope: the NotFound copy itself (wire contract) and create's
+ * parent-agent load, which folds every RPC error into NotFound
+ * (stigmer/stigmer#1351).
+ */
+import type { Client, ConnectError } from "@connectrpc/connect";
+import { Code, createClient, createRouterTransport } from "@connectrpc/connect";
+import { describe, expect, it } from "vitest";
+
+import { AgentInstanceCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/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 { registerAgentInstanceServices } from "../controller.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const INSTANCE_ID = "ain_storefault";
+
+const NOT_FOUND_COPY = `agent instance not found: ${INSTANCE_ID}`;
+const LOAD_FAULT_COPY = "failed to load agent instance";
+
+const MISSING = (): Error =>
+  new ResourceNotFoundError(`agent_instance/${INSTANCE_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 instanceCommand(
+  store: Store,
+): Client<typeof AgentInstanceCommandController> {
+  const transport = createRouterTransport(
+    (router) => {
+      registerAgentInstanceServices(router, {
+        store,
+        logger: silentLogger,
+        authorizer: newPermissiveSingleTeamAuthorizer(),
+        authorizationLifecycle: undefined,
+        parentAgentLoader: untouchable("parentAgentLoader"),
+        listReadScope: undefined,
+      });
+    },
+    {
+      router: {
+        interceptors: [
+          createVerifierChainInterceptor([], [], silentLogger),
+          createApiResourceInterceptor(),
+        ],
+      },
+    },
+  );
+  return createClient(AgentInstanceCommandController, transport);
+}
+
+describe("updateVisibility — LoadInstanceForVisibilityUpdate", () => {
+  function surfaceError(store: Store): Promise<ConnectError> {
+    return errorOf(() =>
+      instanceCommand(store).updateVisibility({
+        resourceId: INSTANCE_ID,
+        visibility: ApiResourceVisibility.visibility_private,
+      }),
+    );
+  }
+
+  it("a missing agent instance 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/agentinstance/controller.ts

@@ -7,8 +7,8 @@
  * refuses default instances outright (stigmer/stigmer#556).
  *
  * Pipeline per RPC mirrors the Go step chains character-for-character.
- * Proven by agentinstance.conformance.test.ts (CONFORMANCE_TARGET=local)
- * and __tests__/agentinstance.test.ts.
+ * Proven by agentinstance.conformance.test.ts (CONFORMANCE_TARGET=local),
+ * __tests__/agentinstance.test.ts and __tests__/store-faults.test.ts.
  *
  * Versus Stigmer Cloud, OSS excludes the CreateIamPolicies and Publish
  * steps. Deliberately NO same-org rule on create, unlike WorkflowInstance:
@@ -98,6 +98,7 @@ import {
   newValidateVisibilityStep,
   newValidateVisibilityUpdateStep,
 } from "../../pipeline/steps/validate-visibility.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import { agentInstanceSearchExtractor } from "./search-extractor.js";
 import {
@@ -398,7 +399,7 @@ async function updateVisibility(
   return reqCtx.get(UPDATE_VISIBILITY_INSTANCE_KEY) as AgentInstance;
 }
 
-/** Loads the agent instance by resource_id; ANY load failure → NotFound. */
+/** Loads the agent instance by resource_id; a missing one answers NotFound, a store fault Internal. */
 function newLoadInstanceForVisibilityUpdateStep(
   store: Store,
 ): PipelineStep<UpdateVisibilityDesc> {
@@ -413,8 +414,11 @@ function newLoadInstanceForVisibilityUpdateStep(
           input.resourceId,
           AgentInstanceSchema,
         );
-      } catch {
-        throw notFoundError("agent instance", input.resourceId);
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          throw notFoundError("agent instance", input.resourceId);
+        }
+        throw internalError(error, "failed to load agent instance");
       }
       ctx.set(UPDATE_VISIBILITY_INSTANCE_KEY, instance);
     },

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

@@ -0,0 +1,101 @@
+/**
+ * Pins the store-fault contract of the share's link-rotation load: a typed
+ * ResourceNotFoundError answers NotFound with the domain's pinned copy
+ * (`AgentShare 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 share does not exist (stigmer/stigmer#1345).
+ * Rotation is how an owner kills a leaked link, so a fault that reads as a
+ * missing share would leave the link live behind a false answer.
+ *
+ * The surface is rotateShareLink, 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.
+ *
+ * Out of scope: the NotFound copy itself (wire contract, pinned by the
+ * agentshare conformance suite), the anonymous profile lanes' deliberate
+ * uniform NotFound, and getByAgent's empty-list answer on an agent-read
+ * fault (stigmer/stigmer#1375).
+ */
+import type { Client, ConnectError } from "@connectrpc/connect";
+import { Code, createClient, createRouterTransport } from "@connectrpc/connect";
+import { describe, expect, it } from "vitest";
+
+import { AgentShareCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/command_pb";
+
+import { createLogger } from "../../../boot/logger.js";
+import { createApiResourceInterceptor } from "../../../pipeline/interceptors/apiresource.js";
+import { createVerifierChainInterceptor } from "../../../pipeline/interceptors/auth.js";
+import { errorOf, failingStore } 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 { registerAgentShareServices } from "../controller.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const SHARE_ID = "ash_storefault";
+
+const NOT_FOUND_COPY = `AgentShare not found: ${SHARE_ID}`;
+const LOAD_FAULT_COPY = "failed to load agent share";
+
+const MISSING = (): Error =>
+  new ResourceNotFoundError(`agent_share/${SHARE_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 the load
+ * reads, then Authorize and ValidateProto run and the load is the first step
+ * that reads the store.
+ */
+function shareCommand(
+  store: Store,
+): Client<typeof AgentShareCommandController> {
+  const transport = createRouterTransport(
+    (router) => {
+      registerAgentShareServices(router, {
+        store,
+        logger: silentLogger,
+        authorizer: newPermissiveSingleTeamAuthorizer(),
+        authorizationLifecycle: undefined,
+        listReadScope: undefined,
+      });
+    },
+    {
+      router: {
+        interceptors: [
+          createVerifierChainInterceptor([], [], silentLogger),
+          createApiResourceInterceptor(),
+        ],
+      },
+    },
+  );
+  return createClient(AgentShareCommandController, transport);
+}
+
+describe("rotateShareLink — LoadShareForLinkRotation", () => {
+  function surfaceError(store: Store): Promise<ConnectError> {
+    return errorOf(() =>
+      shareCommand(store).rotateShareLink({ resourceId: SHARE_ID }),
+    );
+  }
+
+  it("a missing share 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/agentshare/controller.ts

@@ -18,8 +18,8 @@
  * cloud edition enforces the same contracts via FGA plus app-level gates
  * for the anonymous resolution paths.
  *
- * Proven by agentshare.conformance.test.ts (CONFORMANCE_TARGET=local)
- * and __tests__/agentshare.test.ts.
+ * Proven by agentshare.conformance.test.ts (CONFORMANCE_TARGET=local),
+ * __tests__/agentshare.test.ts and __tests__/store-faults.test.ts.
  */
 import type { ConnectRouter, HandlerContext } from "@connectrpc/connect";
 import { create, fromBinary } from "@bufbuild/protobuf";
@@ -105,6 +105,7 @@ import { newPersistStep } from "../../pipeline/steps/persist.js";
 import { newResolveSlugStep } from "../../pipeline/steps/slug.js";
 import { newValidateProtoStep } from "../../pipeline/steps/validation.js";
 import { newValidateVisibilityStep } from "../../pipeline/steps/validate-visibility.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import { ORG_REQUIRED_FOR_LOOKUP_MESSAGE } from "./constants.js";
 import {
@@ -335,7 +336,7 @@ async function rotateShareLink(
   return reqCtx.get(ROTATE_SHARE_KEY) as AgentShare;
 }
 
-/** Loads the share by resource_id; ANY load failure → NotFound (Go). */
+/** Loads the share by resource_id; a missing one answers NotFound, a store fault Internal. */
 function newLoadShareForLinkRotationStep(
   store: Store,
 ): PipelineStep<RotateDesc> {
@@ -349,8 +350,11 @@ function newLoadShareForLinkRotationStep(
           ctx.input.resourceId,
           AgentShareSchema,
         );
-      } catch {
-        throw notFoundError("AgentShare", ctx.input.resourceId);
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          throw notFoundError("AgentShare", ctx.input.resourceId);
+        }
+        throw internalError(error, "failed to load agent share");
       }
       ctx.set(ROTATE_SHARE_KEY, share);
     },

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

@@ -0,0 +1,117 @@
+/**
+ * Pins the store-fault contract the artifact load by id shares: a typed
+ * ResourceNotFoundError answers NotFound with the domain's pinned Go copy
+ * (`Artifact not found: <id>`), and any other store failure is an
+ * infrastructure fault answered as a sanitized Internal, never a NotFound
+ * that tells a client a run's output does not exist (stigmer/stigmer#1345).
+ *
+ * The surfaces: the three direct handlers that load through
+ * loadArtifactOrNotFound, delete, getDownloadUrl and getContent, each
+ * reached through the registered handler on an in-process router. All three
+ * load before they authorize (stigmer#224), and a fault answered as Internal
+ * says nothing about whether the artifact exists. The composed suites reach
+ * only a real store, which cannot fail selectively, so each surface runs here
+ * against a store whose read throws. Artifact storage is untouchable: a load
+ * that fails must stop the call before any blob read or URL mint.
+ *
+ * Out of scope: the NotFound copy itself (wire contract, pinned by the
+ * artifact conformance suite) and create's best-effort org derivation
+ * (stigmer/stigmer#1369).
+ */
+import type { Client, ConnectError } from "@connectrpc/connect";
+import { Code, createClient, createRouterTransport } from "@connectrpc/connect";
+import { describe, expect, it } from "vitest";
+
+import { ArtifactCommandController } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/command_pb";
+import { ArtifactQueryController } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/query_pb";
+
+import { createLogger } from "../../../boot/logger.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 { registerArtifactServices } from "../controller.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const ARTIFACT_ID = "art_storefault";
+
+const NOT_FOUND_COPY = `Artifact not found: ${ARTIFACT_ID}`;
+const LOAD_FAULT_COPY = "failed to load artifact";
+
+const MISSING = (): Error =>
+  new ResourceNotFoundError(`artifact/${ARTIFACT_ID}`);
+const LOCKED = (): Error => new Error("SQLITE_BUSY: database is locked");
+
+interface ArtifactClients {
+  readonly command: Client<typeof ArtifactCommandController>;
+  readonly query: Client<typeof ArtifactQueryController>;
+}
+
+/**
+ * The registered handlers on an in-process router (`artifact.test.ts`'s
+ * harness): the verifier chain stamps the trusted-local caller, each handler
+ * checks its id, and the load is the first read of the store.
+ */
+function artifactClients(store: Store): ArtifactClients {
+  const transport = createRouterTransport(
+    (router) => {
+      registerArtifactServices(router, {
+        store,
+        artifactStorage: untouchable("artifactStorage"),
+        logger: silentLogger,
+        authorizer: newPermissiveSingleTeamAuthorizer(),
+      });
+    },
+    {
+      router: {
+        interceptors: [createVerifierChainInterceptor([], [], silentLogger)],
+      },
+    },
+  );
+  return {
+    command: createClient(ArtifactCommandController, transport),
+    query: createClient(ArtifactQueryController, transport),
+  };
+}
+
+const SURFACES: ReadonlyArray<
+  readonly [string, (clients: ArtifactClients) => Promise<unknown>]
+> = [
+  ["delete", ({ command }) => command.delete({ value: ARTIFACT_ID })],
+  [
+    "getDownloadUrl",
+    ({ query }) => query.getDownloadUrl({ value: ARTIFACT_ID }),
+  ],
+  ["getContent", ({ query }) => query.getContent({ artifactId: ARTIFACT_ID })],
+];
+
+describe.each(SURFACES)("%s — loadArtifactOrNotFound", (_name, call) => {
+  function surfaceError(store: Store): Promise<ConnectError> {
+    return errorOf(() => call(artifactClients(store)));
+  }
+
+  it("a missing artifact 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/artifact/controller.ts

@@ -9,7 +9,8 @@
  * storage_state transition rather than the hard-delete pipeline; only
  * get/listByExecution ride pipelines. Proven by
  * artifact.conformance.test.ts (CONFORMANCE_TARGET=local, incl. the
- * file-server lane) and __tests__/artifact.test.ts.
+ * file-server lane), __tests__/artifact.test.ts and
+ * __tests__/store-faults.test.ts.
  *
  * Go tolerates a nil ArtifactStorage (two-phase wiring) and answers
  * Internal "artifact storage not configured"; the TS composition root
@@ -79,6 +80,7 @@ import {
   newLoadTargetStep,
 } from "../../pipeline/steps/load-target.js";
 import { newValidateProtoStep } from "../../pipeline/steps/validation.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import type { ListIndexRow } from "../../store/list-index.js";
 import { artifactListIndex } from "./list-index.js";
@@ -649,7 +651,7 @@ async function getContent(
   });
 }
 
-/** Load by id with the byte-pinned Go NotFound copy. */
+/** Load by id: a missing artifact answers the byte-pinned Go NotFound copy, a store fault Internal. */
 async function loadArtifactOrNotFound(
   deps: ArtifactControllerDeps,
   artifactId: string,
@@ -660,10 +662,14 @@ async function loadArtifactOrNotFound(
       artifactId,
       ArtifactSchema,
     );
-  } catch {
-    // Go answers NotFound for ANY store failure here (status.Errorf on
-    // err != nil), not only missing rows — mirrored.
-    throw new ConnectError(artifactNotFoundMessage(artifactId), Code.NotFound);
+  } catch (error) {
+    if (error instanceof ResourceNotFoundError) {
+      throw new ConnectError(
+        artifactNotFoundMessage(artifactId),
+        Code.NotFound,
+      );
+    }
+    throw internalError(error, "failed to load artifact");
   }
 }
 

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

@@ -0,0 +1,150 @@
+/**
+ * Pins the store-fault contract every environment load by id shares: a typed
+ * ResourceNotFoundError answers NotFound with the domain's pinned copy
+ * (`environment 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 environment does not exist
+ * (stigmer/stigmer#1345).
+ *
+ * The surfaces: updateVisibility (its own load step) and the three RPCs that
+ * share LoadEnvironmentByID, updateVariables, removeVariables and
+ * getSecretValue, each reached through the registered handler on an
+ * in-process router. The composed suites reach only a real store, which
+ * cannot fail selectively, so each surface runs here against a store whose
+ * read throws. The secret service is untouchable: a load that fails must stop
+ * the call before any decrypt or encrypt.
+ *
+ * Out of scope: the NotFound copy itself (wire contract, pinned by
+ * environment.test.ts and the environment conformance suite) and the
+ * personal-environment resolver's fold of a failed secret read into a
+ * missing key (stigmer/stigmer#1360).
+ */
+import type { Client, ConnectError } from "@connectrpc/connect";
+import { Code, createClient, createRouterTransport } from "@connectrpc/connect";
+import { describe, expect, it } from "vitest";
+
+import { EnvironmentCommandController } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/command_pb";
+import { EnvironmentQueryController } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/query_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 { registerEnvironmentServices } from "../controller.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const ENVIRONMENT_ID = "env_storefault";
+
+const NOT_FOUND_COPY = `environment not found: ${ENVIRONMENT_ID}`;
+const LOAD_FAULT_COPY = "failed to load environment";
+
+const MISSING = (): Error =>
+  new ResourceNotFoundError(`environment/${ENVIRONMENT_ID}`);
+const LOCKED = (): Error => new Error("SQLITE_BUSY: database is locked");
+
+interface EnvironmentClients {
+  readonly command: Client<typeof EnvironmentCommandController>;
+  readonly query: Client<typeof EnvironmentQueryController>;
+}
+
+/**
+ * The registered handlers on an in-process router: the verifier chain stamps
+ * the trusted-local caller and the apiresource interceptor the kind both
+ * loads read, then Authorize and ValidateProto run and the load is the first
+ * step that reads the store.
+ */
+function environmentClients(store: Store): EnvironmentClients {
+  const transport = createRouterTransport(
+    (router) => {
+      registerEnvironmentServices(router, {
+        store,
+        logger: silentLogger,
+        authorizer: newPermissiveSingleTeamAuthorizer(),
+        authorizationLifecycle: undefined,
+        secretService: untouchable("secretService"),
+        listReadScope: undefined,
+      });
+    },
+    {
+      router: {
+        interceptors: [
+          createVerifierChainInterceptor([], [], silentLogger),
+          createApiResourceInterceptor(),
+        ],
+      },
+    },
+  );
+  return {
+    command: createClient(EnvironmentCommandController, transport),
+    query: createClient(EnvironmentQueryController, transport),
+  };
+}
+
+/** Each surface with an input valid enough to pass ValidateProto. */
+const SURFACES: ReadonlyArray<
+  readonly [string, (clients: EnvironmentClients) => Promise<unknown>]
+> = [
+  [
+    "updateVisibility — LoadEnvironmentForVisibilityUpdate",
+    ({ command }) =>
+      command.updateVisibility({
+        resourceId: ENVIRONMENT_ID,
+        visibility: ApiResourceVisibility.visibility_private,
+      }),
+  ],
+  [
+    "updateVariables — LoadEnvironmentByID",
+    ({ command }) =>
+      command.updateVariables({
+        environmentId: ENVIRONMENT_ID,
+        variables: { API_KEY: { value: "v", isSecret: false } },
+      }),
+  ],
+  [
+    "removeVariables — LoadEnvironmentByID",
+    ({ command }) =>
+      command.removeVariables({
+        environmentId: ENVIRONMENT_ID,
+        keys: ["API_KEY"],
+      }),
+  ],
+  [
+    "getSecretValue — LoadEnvironmentByID",
+    ({ query }) =>
+      query.getSecretValue({ environmentId: ENVIRONMENT_ID, key: "API_KEY" }),
+  ],
+];
+
+describe.each(SURFACES)("%s", (_name, call) => {
+  function surfaceError(store: Store): Promise<ConnectError> {
+    return errorOf(() => call(environmentClients(store)));
+  }
+
+  it("a missing environment 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/environment/controller.ts

@@ -8,8 +8,8 @@
  * design: limited blast radius, per-key audit, the industry "reveal" UX).
  *
  * Pipeline per RPC mirrors the Go step chains character-for-character.
- * Proven by environment.conformance.test.ts (CONFORMANCE_TARGET=local)
- * and __tests__/environment.test.ts.
+ * Proven by environment.conformance.test.ts (CONFORMANCE_TARGET=local),
+ * __tests__/environment.test.ts and __tests__/store-faults.test.ts.
  *
  * Versus Stigmer Cloud, OSS excludes the Authorize, CreateIamPolicies,
  * FGA-tuple, and Publish steps (no multi-tenant auth, IAM/FGA, or event
@@ -421,7 +421,7 @@ async function updateVisibility(
   return env;
 }
 
-/** Loads the environment by resource_id; ANY load failure → NotFound. */
+/** Loads the environment by resource_id; a missing one answers NotFound, a store fault Internal. */
 function newLoadEnvironmentForVisibilityUpdateStep(
   store: Store,
 ): PipelineStep<UpdateVisibilityDesc> {
@@ -436,8 +436,11 @@ function newLoadEnvironmentForVisibilityUpdateStep(
           input.resourceId,
           EnvironmentSchema,
         );
-      } catch {
-        throw notFoundError("environment", input.resourceId);
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          throw notFoundError("environment", input.resourceId);
+        }
+        throw internalError(error, "failed to load environment");
       }
       ctx.set(UPDATE_VISIBILITY_ENVIRONMENT_KEY, env);
     },