@stigmer/server 3.38.3 → 3.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/server",
-  "version": "3.38.3",
+  "version": "3.39.0",
   "description": "The Stigmer OSS control plane as a composable library: composeServer, the extension registry and the driver seams a composition builds on. The self-contained deployable of the same server is @stigmer/server-slim.",
   "license": "Apache-2.0",
   "type": "module",
@@ -63,11 +63,11 @@
     "@connectrpc/connect-node": "^2.0.0",
     "@kubernetes/client-node": "2.0.0",
     "@opentelemetry/api": "^1.9.0",
-    "@stigmer/outbound": "3.38.3",
-    "@stigmer/plugin-package": "3.38.3",
-    "@stigmer/protos": "3.38.3",
-    "@stigmer/temporal-codecs": "3.38.3",
-    "@stigmer/zip-structure": "3.38.3",
+    "@stigmer/outbound": "3.39.0",
+    "@stigmer/plugin-package": "3.39.0",
+    "@stigmer/protos": "3.39.0",
+    "@stigmer/temporal-codecs": "3.39.0",
+    "@stigmer/zip-structure": "3.39.0",
     "@temporalio/activity": "1.16.2",
     "@temporalio/client": "1.16.2",
     "@temporalio/common": "1.16.2",

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

@@ -0,0 +1,105 @@
+/**
+ * Pins the store-fault contract of the agent's visibility-update load: a
+ * typed ResourceNotFoundError answers NotFound with the domain's pinned copy
+ * (`agent 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 agent 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 default-instance applier 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 getByAgent's
+ * empty-list answer on an agent-read fault in the channel and share domains
+ * (stigmer/stigmer#1375).
+ */
+import type { Client, ConnectError } from "@connectrpc/connect";
+import { Code, createClient, createRouterTransport } from "@connectrpc/connect";
+import { describe, expect, it } from "vitest";
+
+import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/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 { registerAgentServices } from "../controller.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const AGENT_ID = "agt_storefault";
+
+const NOT_FOUND_COPY = `agent not found: ${AGENT_ID}`;
+const LOAD_FAULT_COPY = "failed to load agent";
+
+const MISSING = (): Error => new ResourceNotFoundError(`agent/${AGENT_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 agentCommand(store: Store): Client<typeof AgentCommandController> {
+  const transport = createRouterTransport(
+    (router) => {
+      registerAgentServices(router, {
+        store,
+        logger: silentLogger,
+        authorizer: newPermissiveSingleTeamAuthorizer(),
+        authorizationLifecycle: undefined,
+        agentInstanceApplier: untouchable("agentInstanceApplier"),
+      });
+    },
+    {
+      router: {
+        interceptors: [
+          createVerifierChainInterceptor([], [], silentLogger),
+          createApiResourceInterceptor(),
+        ],
+      },
+    },
+  );
+  return createClient(AgentCommandController, transport);
+}
+
+describe("updateVisibility — LoadAgentForVisibilityUpdate", () => {
+  function surfaceError(store: Store): Promise<ConnectError> {
+    return errorOf(() =>
+      agentCommand(store).updateVisibility({
+        resourceId: AGENT_ID,
+        visibility: ApiResourceVisibility.visibility_private,
+      }),
+    );
+  }
+
+  it("a missing agent 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/agent/controller.ts

@@ -8,8 +8,8 @@
  * agent to serve: a session with no agent runs the built-in assistant.
  *
  * Pipeline per RPC mirrors the Go step chains character-for-character.
- * Proven by agent.conformance.test.ts (CONFORMANCE_TARGET=local) and
- * __tests__/agent.test.ts.
+ * Proven by agent.conformance.test.ts (CONFORMANCE_TARGET=local),
+ * __tests__/agent.test.ts and __tests__/store-faults.test.ts.
  *
  * Versus Stigmer Cloud, OSS excludes the Authorize, CreateIamPolicies, and
  * Publish steps (no multi-tenant auth, IAM/FGA, or event publishing here).
@@ -91,6 +91,7 @@ import {
   newValidateVisibilityStep,
   newValidateVisibilityUpdateStep,
 } from "../../pipeline/steps/validate-visibility.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import { agentSearchExtractor } from "./search-extractor.js";
 import {
@@ -382,7 +383,7 @@ async function updateVisibility(
   return reqCtx.get(UPDATE_VISIBILITY_AGENT_KEY) as Agent;
 }
 
-/** Loads the agent by resource_id; ANY load failure → NotFound. */
+/** Loads the agent by resource_id; a missing one answers NotFound, a store fault Internal. */
 function newLoadAgentForVisibilityUpdateStep(
   store: Store,
 ): PipelineStep<UpdateVisibilityDesc> {
@@ -397,8 +398,11 @@ function newLoadAgentForVisibilityUpdateStep(
           input.resourceId,
           AgentSchema,
         );
-      } catch {
-        throw notFoundError("agent", input.resourceId);
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          throw notFoundError("agent", input.resourceId);
+        }
+        throw internalError(error, "failed to load agent");
       }
       ctx.set(UPDATE_VISIBILITY_AGENT_KEY, agent);
     },

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

@@ -0,0 +1,126 @@
+/**
+ * Pins the store-fault contract of the install lane's channel load, which
+ * initiateInstall and completeInstall share: a typed ResourceNotFoundError
+ * answers NotFound with the domain's pinned copy
+ * (`AgentChannel 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 channel does not exist (stigmer/stigmer#1345).
+ *
+ * Both surfaces are reached through the registered handler on an in-process
+ * router. The composed suites reach only a real store, which cannot fail
+ * selectively, so each runs here against a store whose read throws. The
+ * channel runtime and the model registry are untouchable: the load comes
+ * before authorization and before the runtime, so a load that fails must
+ * stop the call before either.
+ *
+ * Out of scope: the NotFound copy itself (wire contract, pinned by
+ * agentchannel.test.ts and the agentchannel conformance suite) 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 { AgentChannelCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/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,
+  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 type { ChannelRuntime } from "../channel-runtime.js";
+import { registerAgentChannelServices } from "../controller.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const CHANNEL_ID = "ach_storefault";
+
+const NOT_FOUND_COPY = `AgentChannel not found: ${CHANNEL_ID}`;
+const LOAD_FAULT_COPY = "failed to load agent channel";
+
+const MISSING = (): Error =>
+  new ResourceNotFoundError(`agent_channel/${CHANNEL_ID}`);
+const LOCKED = (): Error => new Error("SQLITE_BUSY: database is locked");
+
+type ChannelCommand = Client<typeof AgentChannelCommandController>;
+
+/**
+ * The registered handlers on an in-process router: the verifier chain stamps
+ * the trusted-local caller and the apiresource interceptor the kind the
+ * install load reads; the load is the first thing either handler does.
+ */
+function channelCommand(store: Store): ChannelCommand {
+  const transport = createRouterTransport(
+    (router) => {
+      registerAgentChannelServices(router, {
+        store,
+        logger: silentLogger,
+        authorizer: newPermissiveSingleTeamAuthorizer(),
+        authorizationLifecycle: undefined,
+        modelRegistry: untouchable("modelRegistry"),
+        channelRuntime: untouchable<ChannelRuntime>("channelRuntime"),
+        listReadScope: undefined,
+      });
+    },
+    {
+      router: {
+        interceptors: [
+          createVerifierChainInterceptor([], [], silentLogger),
+          createApiResourceInterceptor(),
+        ],
+      },
+    },
+  );
+  return createClient(AgentChannelCommandController, transport);
+}
+
+/** Each surface with the input its proto requires. */
+const SURFACES: ReadonlyArray<
+  readonly [string, (command: ChannelCommand) => Promise<unknown>]
+> = [
+  [
+    "initiateInstall — the install load",
+    (command) => command.initiateInstall({ resourceId: CHANNEL_ID }),
+  ],
+  [
+    "completeInstall — the install load",
+    (command) =>
+      command.completeInstall({
+        resourceId: CHANNEL_ID,
+        state: "install-state",
+        code: "provider-code",
+      }),
+  ],
+];
+
+describe.each(SURFACES)("%s", (_name, call) => {
+  function surfaceError(store: Store): Promise<ConnectError> {
+    return errorOf(() => call(channelCommand(store)));
+  }
+
+  it("a missing channel 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/agentchannel/controller.ts

@@ -23,8 +23,8 @@
  * (only same-org shares are) — a dangling channel is tolerated because
  * OSS has no serving runtime and cloud fails closed elsewhere.
  *
- * Proven by agentchannel.conformance.test.ts (CONFORMANCE_TARGET=local)
- * and __tests__/agentchannel.test.ts.
+ * Proven by agentchannel.conformance.test.ts (CONFORMANCE_TARGET=local),
+ * __tests__/agentchannel.test.ts and __tests__/store-faults.test.ts.
  */
 import type { ConnectRouter, HandlerContext } from "@connectrpc/connect";
 import { create, fromBinary } from "@bufbuild/protobuf";
@@ -108,6 +108,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 type { ModelCatalogProvider } from "../workflow/registry/model-catalog-provider.js";
 import type { ChannelRuntime } from "./channel-runtime.js";
@@ -395,9 +396,10 @@ async function completeInstall(
 }
 
 /**
- * Loads the install target — cloud's LoadChannel NOT_FOUND, verbatim.
- * Returns the loaded channel so a composed runtime receives it without a
- * second load (the load-then-X contract stays OSS-owned).
+ * Loads the install target — cloud's LoadChannel NOT_FOUND, verbatim, for
+ * a missing channel; a store fault answers Internal. Returns the loaded
+ * channel so a composed runtime receives it without a second load (the
+ * load-then-X contract stays OSS-owned).
  */
 async function loadChannelForInstall(
   deps: AgentChannelControllerDeps,
@@ -410,8 +412,11 @@ async function loadChannelForInstall(
       resourceId,
       AgentChannelSchema,
     );
-  } catch {
-    throw notFoundError("AgentChannel", resourceId);
+  } catch (error) {
+    if (error instanceof ResourceNotFoundError) {
+      throw notFoundError("AgentChannel", resourceId);
+    }
+    throw internalError(error, "failed to load agent channel");
   }
 }
 

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