@stigmer/server 3.38.3 → 3.39.1-dev.20260928194002

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

@@ -0,0 +1,161 @@
+/**
+ * Pins the store-fault contract of the agent instance's two loads. The
+ * 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). Create's parent-agent load reads the agent through
+ * the in-process query client, so the store's typed miss arrives as a Connect
+ * NotFound: that answers the pinned `Agent not found: <id>`, and any other
+ * failure an Internal, never a missing parent (stigmer/stigmer#1351).
+ *
+ * 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 the visibility update runs 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 { 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 { 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 { registerAgentInstanceServices } from "../controller.js";
+import type { ParentAgentLoaderProvider } from "../steps.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const INSTANCE_ID = "ain_storefault";
+const AGENT_ID = "agt_storefault";
+
+const NOT_FOUND_COPY = `agent instance not found: ${INSTANCE_ID}`;
+const LOAD_FAULT_COPY = "failed to load agent instance";
+const PARENT_NOT_FOUND_COPY = `Agent not found: ${AGENT_ID}`;
+const PARENT_LOAD_FAULT_COPY = "failed to load parent agent";
+
+const MISSING = (): Error =>
+  new ResourceNotFoundError(`agent_instance/${INSTANCE_ID}`);
+const LOCKED = (): Error => new Error("SQLITE_BUSY: database is locked");
+
+/** What the agent query's `get` answers for a missing and a faulted agent. */
+const PARENT_MISSING = (): Error =>
+  new ConnectError(`Agent not found: ${AGENT_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,
+  parentAgentLoader: ParentAgentLoaderProvider = untouchable(
+    "parentAgentLoader",
+  ),
+): Client<typeof AgentInstanceCommandController> {
+  const transport = createRouterTransport(
+    (router) => {
+      registerAgentInstanceServices(router, {
+        store,
+        logger: silentLogger,
+        authorizer: newPermissiveSingleTeamAuthorizer(),
+        authorizationLifecycle: undefined,
+        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);
+  });
+});
+
+describe("create — LoadParentAgent", () => {
+  function surfaceError(parentError: Error): Promise<ConnectError> {
+    const failingParent: ParentAgentLoaderProvider = () => ({
+      get: () => Promise.reject(parentError),
+    });
+    return errorOf(() =>
+      instanceCommand(untouchable("store"), failingParent).create({
+        apiVersion: "agentic.stigmer.ai/v1",
+        kind: "AgentInstance",
+        metadata: { name: "Store Fault Instance", org: "org_storefault" },
+        spec: { agentId: AGENT_ID },
+      }),
+    );
+  }
+
+  it("a missing parent agent answers NotFound with the pinned copy", async () => {
+    const error = await surfaceError(PARENT_MISSING());
+
+    expect(error.code).toBe(Code.NotFound);
+    expect(error.rawMessage).toBe(PARENT_NOT_FOUND_COPY);
+  });
+
+  it("any other parent-load failure answers a sanitized Internal", async () => {
+    const error = await surfaceError(PARENT_FAULTED());
+
+    expect(error.code).toBe(Code.Internal);
+    expect(error.rawMessage).toBe(PARENT_LOAD_FAULT_COPY);
+  });
+});

package/src/domain/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/agentinstance/steps.ts

@@ -6,6 +6,7 @@
  * contracts: the parent-agent edge, the immutable agent_id, the
  * default-instance visibility guard, and the org/label list filters.
  */
+import { Code, ConnectError } from "@connectrpc/connect";
 import { create, fromBinary } from "@bufbuild/protobuf";
 import type { DescMessage } from "@bufbuild/protobuf";
 
@@ -69,7 +70,9 @@ export const PARENT_AGENT_KEY = "parent_agent";
  * an agent is a shareable blueprint and one agent legitimately has
  * instances in several orgs (the marketplace case) — the instance's
  * organization is the caller's, and the check below asks the caller's
- * standing there.
+ * standing there. The agent is read through the in-process query client, so
+ * a missing one arrives as a Connect NotFound; any other failure is a fault
+ * answered as Internal, never a missing parent.
  */
 export function newLoadParentAgentStep(
   agentLoader: ParentAgentLoaderProvider,
@@ -88,11 +91,14 @@ export function newLoadParentAgentStep(
       try {
         parentAgent = await agentLoader().get(agentId);
       } catch (error) {
-        logger.warn("Parent agent not found", {
-          agentId,
-          error: error instanceof Error ? error.message : String(error),
-        });
-        throw notFoundError("Agent", agentId);
+        if (error instanceof ConnectError && error.code === Code.NotFound) {
+          logger.warn("Parent agent not found", {
+            agentId,
+            error: error.rawMessage,
+          });
+          throw notFoundError("Agent", agentId);
+        }
+        throw internalError(error, "failed to load parent agent");
       }
 
       logger.debug("Loaded parent agent", {

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/organization/__tests__/organization-delete.test.ts

@@ -1,20 +1,24 @@
 /**
  * Pins the organization delete's order through a composed server in the
- * trusted-local posture: everything that names the organization goes
- * before its row, and a fault stops the delete with the organization in
- * place. An organization's id is its slug and the delete frees the slug for
- * anyone, so a row left behind would belong to the slug's next holder.
+ * trusted-local posture: the slug is retired first, everything that grants
+ * on the organization goes before its row, and a fault stops the delete
+ * with the organization in place. An organization's id is its slug, and a
+ * slug is never taken again, so nothing a deleted organization left behind
+ * can pass to a new holder.
  *
  *   - the `org-delete:pre-delete` slot runs with the organization loaded
  *     and still stored, and its rows still in place;
  *   - a slot step's refusal answers its own code and copy, and leaves the
- *     organization and its rows;
+ *     organization and its rows, its slug already retired;
+ *   - a fault retiring the slug fails the delete before anything else, with
+ *     the organization and its rows in place;
  *   - the organization's policy rows are revoked before its row, as
  *     principal and as resource: a revocation fault answers Internal with
  *     fixed copy, leaves the organization and its owner row, and a retry
  *     completes the delete;
- *   - a slug freed by the delete and created again carries none of the old
- *     organization's rows.
+ *   - a create of a deleted organization's slug is refused with the
+ *     ORGANIZATION_SLUG_RESERVED reason, and no row of the old organization
+ *     gains an owner.
  *
  * The policy store is the library's in-memory double, composed as the
  * IamPolicy store driver so a test can make one row's delete fault; the
@@ -28,13 +32,22 @@ import type { DescMessage } from "@bufbuild/protobuf";
 import { Code, ConnectError, createClient } from "@connectrpc/connect";
 import type { Client, Transport } from "@connectrpc/connect";
 import { createGrpcTransport } from "@connectrpc/connect-node";
-import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "vitest";
 
 import { IamPolicyCommandController } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/command_pb";
 import type { IamPolicy } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
 import type { Organization } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
 import { OrganizationCommandController } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/command_pb";
 import { OrganizationQueryController } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/query_pb";
+import { ErrorInfoSchema } from "@stigmer/protos/google/rpc/error_details_pb";
 
 import { loadConfig } from "../../../boot/config.js";
 import { composeServer } from "../../../boot/compose.js";
@@ -215,6 +228,36 @@ describe("organization delete (composed server, trusted-local posture)", () => {
       (await organizationQuery.get({ value: REFUSED_SLUG })).metadata?.id,
     ).toBe(REFUSED_SLUG);
     expect(rowsNaming(REFUSED_SLUG)).toHaveLength(3);
+    // The slug was retired before the slot refused; the organization lives
+    // on, and its slug is refused to a create either way.
+    expect(
+      (await server.store.organizationSlugs.find(REFUSED_SLUG))?.retiredAt,
+    ).not.toBe("");
+  });
+
+  it("a fault retiring the slug fails the delete before anything else, with the organization and its rows in place", async () => {
+    await organizationWithRows("delete-retire-faults");
+    const retire = vi
+      .spyOn(server.store.organizationSlugs, "retire")
+      .mockRejectedValueOnce(new Error("ledger unavailable"));
+    try {
+      const failed = await grpcError(() =>
+        organizations.delete({ value: "delete-retire-faults" }),
+      );
+      expect(failed.code).toBe(Code.Internal);
+      expect(failed.rawMessage).toBe("failed to retire the organization slug");
+    } finally {
+      retire.mockRestore();
+    }
+    expect(seenBySlot.has("delete-retire-faults")).toBe(false);
+    expect(
+      (await organizationQuery.get({ value: "delete-retire-faults" })).metadata
+        ?.id,
+    ).toBe("delete-retire-faults");
+    expect(rowsNaming("delete-retire-faults")).toHaveLength(3);
+
+    await organizations.delete({ value: "delete-retire-faults" });
+    expect(rowsNaming("delete-retire-faults")).toEqual([]);
   });
 
   it("a revocation fault fails the delete with the organization and its owner in place, and the retry completes it", async () => {
@@ -248,19 +291,31 @@ describe("organization delete (composed server, trusted-local posture)", () => {
     expect(rowsNaming("delete-faults")).toEqual([]);
   });
 
-  it("a slug freed by the delete and created again carries none of the old organization's rows", async () => {
+  it("a deleted organization's slug is never taken again: the create is refused with the reserved reason", async () => {
     await organizationWithRows("delete-reborn");
     await organizations.delete({ value: "delete-reborn" });
 
-    await organizations.create({
-      apiVersion: "tenancy.stigmer.ai/v1",
-      kind: "Organization",
-      metadata: { name: "delete-reborn", slug: "delete-reborn", org: "" },
-      spec: { description: "the slug, taken again" },
-    });
+    const refused = await grpcError(() =>
+      organizations.create({
+        apiVersion: "tenancy.stigmer.ai/v1",
+        kind: "Organization",
+        metadata: { name: "delete-reborn", slug: "delete-reborn", org: "" },
+        spec: { description: "the slug, taken again" },
+      }),
+    );
 
-    expect(
-      rowsNaming("delete-reborn").map((row) => row.spec?.relation),
-    ).toEqual(["owner"]);
+    expect(refused.code).toBe(Code.AlreadyExists);
+    expect(refused.rawMessage).toBe(
+      "Organization slug 'delete-reborn' belonged to an organization that was deleted, and a slug is never reused",
+    );
+    const [reason] = refused.findDetails(ErrorInfoSchema);
+    expect(reason?.reason).toBe("ORGANIZATION_SLUG_RESERVED");
+    expect(reason?.domain).toBe("stigmer.ai");
+    expect(reason?.metadata).toEqual({ slug: "delete-reborn" });
+    expect(rowsNaming("delete-reborn")).toEqual([]);
+    const gone = await grpcError(() =>
+      organizationQuery.get({ value: "delete-reborn" }),
+    );
+    expect(gone.code).toBe(Code.NotFound);
   });
 });