@stigmer/server 3.38.1 → 3.38.3

package/src/domain/agentexecution/validate-thinking-mode.ts

@@ -1,88 +1,143 @@
 /**
- * ValidateThinkingMode — ports validate_thinking_mode.go: fail-closed
- * validation of ExecutionConfig.thinking_mode against the model registry
- * (stigmer/stigmer#772) — the sibling of ValidateServiceTier for the
- * second variant dimension.
+ * ValidateThinkingMode — fail-closed validation of
+ * ExecutionConfig.thinking_mode against the model registry
+ * (stigmer/stigmer#772), the sibling of ValidateServiceTier for the second
+ * variant dimension, judged on the harness the execution will run on
+ * (stigmer/stigmer#1280).
  *
  * Unlike the fast tier, thinking is capability-gated, not pricing-gated:
- * thinking variants bill at base per-token rates (ledger-verified), so
- * the registry fact that makes ENABLED selectable is
- * capabilities.thinking on the model's CURSOR-harness entry. The harness
- * scoping is deliberate — native entries truthfully declare the same
- * capability (Anthropic models support extended thinking natively) but no
- * native wire mapping exists in v1, so validating them would accept a
- * config the runner silently cannot honor (the exact silent-no-op class
- * #357 exists to kill; mirrors the #361 FAST-on-native hold).
+ * thinking variants bill at base per-token rates (ledger-verified), so the
+ * registry fact that makes ENABLED selectable is a thinking capability on
+ * the model's entry for the execution's harness — `thinking` (a fixed
+ * budget) or `adaptiveThinking` (depth adapts). Both harnesses translate
+ * the mode: Cursor as its thinking variant, native as Anthropic's
+ * `thinking` parameter in the form the entry declares. The harness scoping
+ * is what keeps a selection honest: an id such as claude-sonnet-5 has an
+ * entry on each harness, and only the entry the execution runs on says
+ * what its model does.
  *
- *   - UNSPECIFIED / DISABLED: always valid — every model has a base
- *     variant, and unset resolves to explicitly-requested DISABLED in the
- *     runner (never the provider account default).
+ *   - UNSPECIFIED: always valid — it resolves to DISABLED in the runner,
+ *     and a model that requires thinking thinks under it.
+ *   - DISABLED: valid, except on a model whose entry declares
+ *     `thinkingRequired` — it always thinks and the provider refuses a
+ *     request to turn thinking off.
  *   - ENABLED: requires model_name to be set (Auto has no variant
- *     dimensions) and that model's cursor-harness registry entry to
- *     declare the thinking capability.
+ *     dimensions) and that model's entry on the harness to declare a
+ *     thinking capability.
  *
- * Positioned beside ValidateServiceTier, before any side-effecting step.
- * Mirrors the cloud Java ValidateThinkingModeStep; all three editions
- * must refuse the same request with the same message.
+ * The harness is the one CreateSessionIfNeeded and dispatch will use: the
+ * stored session's for a turn on an existing session, else the bootstrap
+ * session_spec's, UNSPECIFIED read as native (harnessName; the Cloud
+ * billing gate resolves the same way). Reading a stored session is why the
+ * step runs after the run gate: the caller is authorized to add a turn to
+ * that session before anything about it is read, so a refusal never tells
+ * an unauthorized caller which harness a session uses. It is still a pure
+ * step, before any side effect.
  */
-import type { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { AgentExecution, AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { ThinkingMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { Harness } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 
-import { invalidArgumentError } from "../../pipeline/errors.js";
+import { internalError, invalidArgumentError } from "../../pipeline/errors.js";
 import type { PipelineStep } from "../../pipeline/pipeline.js";
+import { ResourceNotFoundError, type Store } from "../../store/interface.js";
 import type { ModelCatalogProvider } from "../workflow/registry/model-catalog-provider.js";
-import { THINKING_CAPABILITY_KEY } from "../workflow/registry/model-registry-store.js";
-import { HARNESS_NAME_CURSOR } from "../workflow/registry/pin-validation.js";
+import {
+  ADAPTIVE_THINKING_CAPABILITY_KEY,
+  THINKING_CAPABILITY_KEY,
+  THINKING_REQUIRED_CAPABILITY_KEY,
+} from "../workflow/registry/model-registry-store.js";
+import { harnessName } from "../workflow/registry/pin-validation.js";
 
 export function newValidateThinkingModeStep(
   registry: ModelCatalogProvider,
+  store: Store,
 ): PipelineStep<typeof AgentExecutionSchema> {
   return {
     name: "ValidateThinkingMode",
-    execute(ctx) {
+    async execute(ctx) {
       const config = ctx.newState.spec?.executionConfig;
-      if (config?.thinkingMode !== ThinkingMode.ENABLED) {
-        // UNSPECIFIED and DISABLED are always valid; unknown enum numbers
-        // were already refused by proto field validation (defined_only).
+      const mode = config?.thinkingMode ?? ThinkingMode.UNSPECIFIED;
+      const modelName = (config?.modelName ?? "").trim();
+      // UNSPECIFIED is always valid, and so is DISABLED on Auto (no model
+      // to require thinking). Unknown enum numbers were already refused by
+      // proto field validation (defined_only).
+      if (mode === ThinkingMode.UNSPECIFIED || (mode === ThinkingMode.DISABLED && modelName === "")) {
+        return;
+      }
+
+      const harness = await executionHarness(ctx.newState, store);
+
+      if (mode === ThinkingMode.DISABLED) {
+        if (registry.hasCapabilityForHarness(harness, modelName, THINKING_REQUIRED_CAPABILITY_KEY)) {
+          throw invalidArgumentError(
+            `thinking_mode 'disabled' is not available for model '${modelName}': the model always ` +
+              `thinks on the ${harness} harness and refuses a request to turn thinking off. ` +
+              "Leave thinking_mode unset, or set it to 'enabled'.",
+          );
+        }
         return;
       }
 
-      const modelName = (config.modelName ?? "").trim();
       if (modelName === "") {
         throw invalidArgumentError(
           "thinking_mode 'enabled' requires execution_config.model_name: thinking is a " +
             "per-model capability, and Auto (no pinned model) has no variant dimensions. " +
-            `Pin a model that supports it${thinkingCapableSuffix(registry)}.`,
+            `Pin a model that supports it${thinkingCapableSuffix(registry, harness)}.`,
         );
       }
 
-      if (
-        !registry.hasCapabilityForHarness(
-          HARNESS_NAME_CURSOR,
-          modelName,
-          THINKING_CAPABILITY_KEY,
-        )
-      ) {
+      if (!canThink(registry, harness, modelName)) {
         throw invalidArgumentError(
           `thinking_mode 'enabled' is not available for model '${modelName}': the model ` +
-            "registry declares no thinking capability for it on the cursor " +
-            `harness${thinkingCapableSuffix(registry)}.`,
+            `registry declares no thinking capability for it on the ${harness} ` +
+            `harness${thinkingCapableSuffix(registry, harness)}.`,
         );
       }
     },
   };
 }
 
+/** The registry section name of the harness this execution will run on. */
+async function executionHarness(execution: AgentExecution, store: Store): Promise<string> {
+  const sessionId = execution.spec?.sessionId ?? "";
+  if (sessionId === "") {
+    return harnessName(execution.spec?.sessionSpec?.harness ?? Harness.UNSPECIFIED);
+  }
+  try {
+    const session = await store.getResource(ApiResourceKind.session, sessionId, SessionSchema);
+    return harnessName(session.spec?.harness ?? Harness.UNSPECIFIED);
+  } catch (error) {
+    // A dangling session id is the loading steps' refusal to make, with
+    // its own NotFound; judge it on the default harness, as dispatch does.
+    // Any other failure is a store fault, never a reading of the session.
+    if (error instanceof ResourceNotFoundError) {
+      return harnessName(Harness.UNSPECIFIED);
+    }
+    throw internalError(error, "failed to load session for thinking-mode validation");
+  }
+}
+
+function canThink(registry: ModelCatalogProvider, harness: string, modelName: string): boolean {
+  return (
+    registry.hasCapabilityForHarness(harness, modelName, THINKING_CAPABILITY_KEY) ||
+    registry.hasCapabilityForHarness(harness, modelName, ADAPTIVE_THINKING_CAPABILITY_KEY)
+  );
+}
+
 /**
- * "; models with a thinking mode: a, b, c" — actionable refusal detail,
- * sorted (the store keeps the list sorted), empty when the registry
- * declares none.
+ * "; models with a thinking mode: a, b, c" — actionable refusal detail for
+ * the harness, sorted, empty when the registry declares none there.
  */
-function thinkingCapableSuffix(registry: ModelCatalogProvider): string {
-  const capable = registry.canonicalModelsWithCapabilityForHarness(
-    HARNESS_NAME_CURSOR,
-    THINKING_CAPABILITY_KEY,
-  );
+function thinkingCapableSuffix(registry: ModelCatalogProvider, harness: string): string {
+  const capable = [
+    ...new Set([
+      ...registry.canonicalModelsWithCapabilityForHarness(harness, THINKING_CAPABILITY_KEY),
+      ...registry.canonicalModelsWithCapabilityForHarness(harness, ADAPTIVE_THINKING_CAPABILITY_KEY),
+    ]),
+  ].sort();
   if (capable.length === 0) {
     return "";
   }

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);
     },

package/src/domain/environment/steps.ts

@@ -15,8 +15,8 @@
  *      by design and must not hit the forgery rejection.
  *   3. Redaction (redact.ts) runs AFTER Persist, outside the pipeline.
  *
- * 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.
  */
 import { create } from "@bufbuild/protobuf";
 import type { DescMessage } from "@bufbuild/protobuf";
@@ -51,6 +51,7 @@ import { findResourceByLabelAndOrg } from "../../pipeline/steps/helpers.js";
 import { EXISTING_RESOURCE_KEY } from "../../pipeline/steps/load-existing.js";
 import { TARGET_RESOURCE_KEY } from "../../pipeline/steps/load-target.js";
 import { destroySecretBackingState } from "../../pipeline/steps/secret-cleanup.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import {
   PERSONAL_LABEL_KEY,
@@ -273,7 +274,8 @@ export function newEnforcePersonalUniquenessStep(
  * environment_id field (the standard LoadTarget expects a `value` id
  * field, but EnvironmentSecretValueInput / Update-/RemoveEnvironment-
  * VariablesRequest carry `environment_id`). Stores under
- * TARGET_RESOURCE_KEY.
+ * TARGET_RESOURCE_KEY. A missing environment answers NotFound, a store
+ * fault Internal.
  */
 export function newLoadEnvironmentByIdStep<Desc extends DescMessage>(
   store: Store,
@@ -294,10 +296,11 @@ export function newLoadEnvironmentByIdStep<Desc extends DescMessage>(
           environmentId,
           EnvironmentSchema,
         );
-      } catch {
-        // Go maps EVERY load failure to NotFound here (store errors
-        // included) — ported as-is.
-        throw notFoundError("environment", environmentId);
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          throw notFoundError("environment", environmentId);
+        }
+        throw internalError(error, "failed to load environment");
       }
 
       ctx.set(TARGET_RESOURCE_KEY, env);