@stigmer/server 3.38.3 → 3.39.1-dev.20260928194002

package/src/domain/workflowinstance/controller.ts

@@ -13,8 +13,8 @@
  *
  * Pipeline per RPC mirrors the Go step chains character-for-character.
  * Proven by workflowinstance.conformance.test.ts
- * (CONFORMANCE_TARGET=local) and the family test
- * ../workflow/__tests__/workflow.test.ts (the mutual edge makes the two
+ * (CONFORMANCE_TARGET=local), __tests__/store-faults.test.ts and the family
+ * test ../workflow/__tests__/workflow.test.ts (the mutual edge makes the two
  * domains one testable unit).
  */
 import type { ConnectRouter, HandlerContext } from "@connectrpc/connect";
@@ -104,6 +104,7 @@ import {
   newValidateVisibilityStep,
   newValidateVisibilityUpdateStep,
 } from "../../pipeline/steps/validate-visibility.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import { workflowInstanceSearchExtractor } from "./search-extractor.js";
 import {
@@ -573,9 +574,10 @@ function newSetInstanceExecutionVisibilityStep(): PipelineStep<UpdateExecutionVi
 // ---------------------------------------------------------------------------
 
 /**
- * Loads the instance by resource_id; ANY load failure → NotFound. The
- * accessor keeps the input shape compiler-checked (both targeted-update
- * inputs carry resource_id, but the compiler should prove it, not a cast).
+ * Loads the instance by resource_id; a missing one answers NotFound, a store
+ * fault Internal. The accessor keeps the input shape compiler-checked (both
+ * targeted-update inputs carry resource_id, but the compiler should prove it,
+ * not a cast).
  */
 function newLoadInstanceStep<Desc extends DescMessage>(
   store: Store,
@@ -594,8 +596,11 @@ function newLoadInstanceStep<Desc extends DescMessage>(
           resourceId,
           WorkflowInstanceSchema,
         );
-      } catch {
-        throw notFoundError("workflow instance", resourceId);
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          throw notFoundError("workflow instance", resourceId);
+        }
+        throw internalError(error, "failed to load workflow instance");
       }
       ctx.set(instanceKey, instance);
     },

package/src/domain/workflowinstance/steps.ts

@@ -8,7 +8,7 @@
  * the family test ../workflow/__tests__/workflow.test.ts (the mutual edge
  * makes the two domains one testable unit).
  */
-import { ConnectError } from "@connectrpc/connect";
+import { Code, ConnectError } from "@connectrpc/connect";
 import type { DescMessage } from "@bufbuild/protobuf";
 
 import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
@@ -55,9 +55,11 @@ export type ParentWorkflowLoaderProvider = () => ParentWorkflowLoader;
 
 /**
  * LoadParentWorkflow — create.go: loads the workflow the instance
- * materializes and stashes it for the same-org rule. ANY load failure maps
- * to NotFound("Workflow", id) — Go folds every client error into that arm
- * (capital-W copy is the wire contract).
+ * materializes and stashes it for the same-org rule. The workflow is read
+ * through the in-process query client, so a missing one arrives as a Connect
+ * NotFound and answers NotFound("Workflow", id) (the capital-W copy is the
+ * wire contract); any other failure is a fault answered as Internal, never a
+ * missing parent.
  */
 export function newLoadParentWorkflowStep(
   loaderProvider: ParentWorkflowLoaderProvider,
@@ -74,12 +76,14 @@ export function newLoadParentWorkflowStep(
       try {
         parent = await loaderProvider().get(workflowId);
       } catch (error) {
-        logger.warn("Parent workflow not found", {
-          error:
-            error instanceof ConnectError ? error.rawMessage : String(error),
-          workflowId,
-        });
-        throw notFoundError("Workflow", workflowId);
+        if (error instanceof ConnectError && error.code === Code.NotFound) {
+          logger.warn("Parent workflow not found", {
+            error: error.rawMessage,
+            workflowId,
+          });
+          throw notFoundError("Workflow", workflowId);
+        }
+        throw internalError(error, "failed to load parent workflow");
       }
 
       ctx.set(PARENT_WORKFLOW_KEY, parent);

package/src/extensions/gate-slots.ts

@@ -55,11 +55,13 @@
  *
  * The tenth, `org-delete:pre-delete`: the organization delete chain after
  * LoadExistingForDelete and before any write, so the organization exists
- * and is loaded (EXISTING_RESOURCE_KEY) while its steps run. An
- * organization's id is its slug and its delete frees the slug for anyone,
- * so whatever an edition keeps for the organization must go before the row
- * does, or be refused: a row left behind would belong to whoever creates
- * the slug next. Its steps may refuse (Enterprise refuses while an
+ * and is loaded (EXISTING_RESOURCE_KEY) while its steps run. Whatever an
+ * edition keeps for the organization must go before the row does, or be
+ * refused: a row left behind is trust or state that nobody administers.
+ * (The slug itself is never taken again, domain/organization/slug-ledger.ts,
+ * so nothing left behind can pass to a new holder of the slug; the order
+ * still keeps an edition's rows from outliving their organization.) Its
+ * steps may refuse (Enterprise refuses while an
  * identity provider still signs in platform-managed organizations) or
  * remove the edition's own rows; either way a throw fails the delete with
  * the organization intact, and the retry re-runs every step, so each owns

package/src/index.ts

@@ -293,6 +293,7 @@ export { RequestContext } from "./pipeline/request-context.js";
 export {
   abortedError,
   alreadyExistsError,
+  alreadyExistsWithReasonError,
   ERROR_REASON_DOMAIN,
   failedPreconditionError,
   internalError,
@@ -398,6 +399,16 @@ export {
   AuditNotFoundError,
   ResourceNotFoundError,
 } from "./store/interface.js";
+// The organization-slug ledger (`Store.organizationSlugs`): an
+// organization's slug is its for good. A composition that keeps its own
+// rows by organization id retires the slugs its history holds through it,
+// and a create of a retired slug carries the reason below.
+export type {
+  OrganizationSlugClaim,
+  OrganizationSlugEntry,
+  OrganizationSlugStore,
+} from "./store/interface.js";
+export { ORGANIZATION_SLUG_RESERVED } from "./domain/organization/slug-ledger.js";
 // The list index's read shapes, which `Store.queryResources` speaks
 // (store/list-index.ts). Declaring an index stays internal: the list is
 // the composition root's (boot/list-indexes.ts), one per server.

package/src/pipeline/__tests__/blind-not-found.test.ts

@@ -20,9 +20,8 @@
  *
  * The scan parses each module with the TypeScript compiler API rather than a
  * regular expression, because a catch block's extent (nested braces, a log
- * line before the throw) is a syntax question. `PENDING` is the list of known
- * blind sites still to be fixed; the scan must equal it exactly, so a new
- * blind site fails here, and so does a fixed site still listed.
+ * line before the throw) is a syntax question. The scan must find no blind
+ * site at all, so a new one fails here with its module and line.
  */
 import { readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
@@ -34,23 +33,6 @@ import { describe, expect, it } from "vitest";
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const SRC = path.resolve(HERE, "../..");
 
-/** Known blind sites by module (relative to `src`), with their count. */
-const PENDING: ReadonlyMap<string, number> = new Map([
-  // Store loads, stigmer/stigmer#1345 (fixed domain by domain).
-  ["domain/agent/controller.ts", 1],
-  ["domain/agentchannel/controller.ts", 1],
-  ["domain/agentinstance/controller.ts", 1],
-  ["domain/agentshare/controller.ts", 1],
-  ["domain/plugin/controller.ts", 1],
-  ["domain/skill/controller.ts", 1],
-  ["domain/workflow/controller.ts", 1],
-  ["domain/workflowinstance/controller.ts", 1],
-  // Parent loads through the in-process chain that fold every RPC error,
-  // validation included, stigmer/stigmer#1351.
-  ["domain/agentinstance/steps.ts", 1],
-  ["domain/workflowinstance/steps.ts", 1],
-]);
-
 interface BlindSite {
   readonly module: string;
   readonly line: number;
@@ -262,7 +244,7 @@ describe("the blind-NotFound rule", () => {
 });
 
 describe("the server source", () => {
-  it("has no blind NotFound beyond the pending list, and the list names only live sites", () => {
+  it("has no blind NotFound", () => {
     const sources = serverSources();
     const constructors = notFoundConstructors(sources);
     const found = new Map<string, number[]>();
@@ -282,8 +264,6 @@ describe("the server source", () => {
     const where = [...found]
       .flatMap(([module, lines]) => lines.map((line) => `${module}:${line}`))
       .join("\n");
-    expect(counts, `blind NotFound sites found:\n${where}`).toEqual(
-      Object.fromEntries(PENDING),
-    );
+    expect(counts, `blind NotFound sites found:\n${where}`).toEqual({});
   });
 });

package/src/pipeline/errors.ts

@@ -53,6 +53,29 @@ export function alreadyExistsError(resource: string, id: string): ConnectError {
   );
 }
 
+/**
+ * An AlreadyExists refusal a client acts on without parsing text: the
+ * authored message, and the reason carried as an ErrorInfo detail, exactly
+ * as failedPreconditionError carries one. The code stays AlreadyExists, so
+ * a caller that keys on the code alone (a retry with another name) keeps
+ * working.
+ */
+export function alreadyExistsWithReasonError(
+  message: string,
+  reason: RefusalReason,
+): ConnectError {
+  return new ConnectError(message, Code.AlreadyExists, undefined, [
+    {
+      desc: ErrorInfoSchema,
+      value: create(ErrorInfoSchema, {
+        reason: reason.reason,
+        domain: ERROR_REASON_DOMAIN,
+        metadata: { ...reason.metadata },
+      }),
+    },
+  ]);
+}
+
 /**
  * Go FailedPreconditionError — the system is not in a state required for
  * the operation (vs AlreadyExists, which tells the caller to stop). With a

package/src/store/__tests__/organization-slug-history.test.ts

@@ -0,0 +1,109 @@
+/**
+ * Pins the driver-neutral half of the organization-slug ledger's data
+ * migration (organization-slug-history.ts): the frozen kind table is
+ * exactly the kinds `api_resource_kind.proto` scoped to an organization
+ * when the ledger arrived, spelled out here as the step's statement about
+ * the store as it was, each with a schema whose rows carry the shared
+ * metadata; a row's
+ * organization is read from its bytes, a row with no metadata or an empty
+ * organization names none, and bytes that do not decode are a thrown
+ * fault, never a skipped row. The drivers' replay tests pin the SQL around
+ * these functions.
+ */
+import { create, toBinary } from "@bufbuild/protobuf";
+import { describe, expect, it } from "vitest";
+
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+
+import {
+  ORGANIZATION_SCOPED_KINDS_AT_LEDGER,
+  organizationNamedBy,
+  undecodableRowError,
+} from "../organization-slug-history.js";
+
+const AGENT = ORGANIZATION_SCOPED_KINDS_AT_LEDGER.find(
+  (entry) => entry.kind === "agent",
+)!;
+
+describe("the frozen kind table", () => {
+  it("is exactly the kinds api_resource_kind.proto scoped to an organization when the ledger arrived, in its order", () => {
+    expect(
+      ORGANIZATION_SCOPED_KINDS_AT_LEDGER.map((entry) => entry.kind),
+    ).toEqual([
+      "iam_policy",
+      "invitation",
+      "identity_provider",
+      "oauth_app",
+      "platform_client",
+      "team",
+      "agent",
+      "session",
+      "skill",
+      "mcp_server",
+      "agent_instance",
+      "agent_share",
+      "agent_channel",
+      "channel_app",
+      "workflow",
+      "workflow_instance",
+      "workflow_execution",
+      "environment",
+      "artifact",
+      "schedule",
+      "memory",
+      "plugin",
+      "subscription",
+    ]);
+  });
+
+  it("gives every kind a schema whose rows carry the metadata every resource shares", () => {
+    for (const entry of ORGANIZATION_SCOPED_KINDS_AT_LEDGER) {
+      const metadata = entry.schema.fields.find(
+        (field) => field.name === "metadata",
+      );
+      expect(metadata?.fieldKind, entry.kind).toBe("message");
+    }
+  });
+});
+
+describe("organizationNamedBy", () => {
+  it("reads the organization a row names", () => {
+    const bytes = toBinary(
+      AgentSchema,
+      create(AgentSchema, {
+        metadata: { id: "agt_1", slug: "helper", org: "acme" },
+        spec: { instructions: "a conformant instruction body" },
+      }),
+    );
+    expect(organizationNamedBy(AGENT, bytes)).toBe("acme");
+  });
+
+  it("names no organization for a row with no metadata or an empty org", () => {
+    expect(
+      organizationNamedBy(AGENT, toBinary(AgentSchema, create(AgentSchema))),
+    ).toBe("");
+    expect(
+      organizationNamedBy(
+        AGENT,
+        toBinary(
+          AgentSchema,
+          create(AgentSchema, { metadata: { id: "agt_2", org: "" } }),
+        ),
+      ),
+    ).toBe("");
+  });
+
+  it("throws on bytes that do not decode, and the driver's error names the row", () => {
+    const broken = new Uint8Array([0xff, 0xff, 0xff]);
+    expect(() => organizationNamedBy(AGENT, broken)).toThrow();
+    let caught: unknown;
+    try {
+      organizationNamedBy(AGENT, broken);
+    } catch (error) {
+      caught = error;
+    }
+    expect(undecodableRowError(AGENT, "agt_broken", caught).message).toMatch(
+      /^agent 'agt_broken' cannot be read for the organization it names: /,
+    );
+  });
+});

package/src/store/__tests__/store-contract.ts

@@ -17,7 +17,9 @@
  * token match / single-term prefix / AND; wire-ready 0–1 scores;
  * list-mode newest-first at exactly 1.0 — search-mode ranking ORDER is
  * deliberately NOT asserted here, it is driver-relative), the two-phase
- * signal-dedupe hold (oss#442), OAuth grants, once-only pending-state
+ * signal-dedupe hold (oss#442), the organization-slug ledger (one winner
+ * of concurrent claims, a retire that sticks, a release that frees only
+ * its own unretired claim), OAuth grants, once-only pending-state
  * redemption with its 10-minute TTL, the closed-store failure mode, and
  * the list index (../list-index.ts): one organization's or one parent's
  * rows newest first, a cursor walk with no gap and no duplicate, keys
@@ -1435,6 +1437,86 @@ export function describeStoreContract(
     });
   });
 
+  describe("organization slugs", () => {
+    it("claims a fresh slug once; a second claim loses to the entry that holds it", async () => {
+      expect(await fx.store.organizationSlugs.find("acme")).toBeUndefined();
+
+      const first = await fx.store.organizationSlugs.claim("acme");
+      expect(first.claimed).toBe(true);
+      expect(first.entry.slug).toBe("acme");
+      expect(first.entry.retiredAt).toBe("");
+      expect(Date.parse(first.entry.claimedAt)).not.toBeNaN();
+
+      const second = await fx.store.organizationSlugs.claim("acme");
+      expect(second.claimed).toBe(false);
+      expect(second.entry).toEqual(first.entry);
+      expect(await fx.store.organizationSlugs.find("acme")).toEqual(
+        first.entry,
+      );
+    });
+
+    it("of concurrent claims of one slug, exactly one wins", async () => {
+      const claims = await Promise.all(
+        Array.from({ length: 8 }, () =>
+          fx.store.organizationSlugs.claim("contended"),
+        ),
+      );
+      expect(claims.filter((claim) => claim.claimed)).toHaveLength(1);
+      const winner = claims.find((claim) => claim.claimed)!;
+      for (const loser of claims.filter((claim) => !claim.claimed)) {
+        expect(loser.entry).toEqual(winner.entry);
+      }
+    });
+
+    it("retire marks a held slug retired, keeps the first time, and records an unknown slug retired", async () => {
+      const { entry } = await fx.store.organizationSlugs.claim("acme");
+      await fx.store.organizationSlugs.retire("acme");
+      const retired = await fx.store.organizationSlugs.find("acme");
+      expect(retired?.claimedAt).toBe(entry.claimedAt);
+      expect(retired?.retiredAt).not.toBe("");
+
+      await fx.store.organizationSlugs.retire("acme");
+      expect(await fx.store.organizationSlugs.find("acme")).toEqual(retired);
+
+      // An organization created before the ledger existed has no entry;
+      // its delete still retires the slug.
+      await fx.store.organizationSlugs.retire("older");
+      const older = await fx.store.organizationSlugs.find("older");
+      expect(older?.retiredAt).not.toBe("");
+
+      const lost = await fx.store.organizationSlugs.claim("older");
+      expect(lost.claimed).toBe(false);
+      expect(lost.entry).toEqual(older);
+    });
+
+    it("release frees only its own unretired claim", async () => {
+      const { entry } = await fx.store.organizationSlugs.claim("acme");
+      await fx.store.organizationSlugs.release(entry);
+      expect(await fx.store.organizationSlugs.find("acme")).toBeUndefined();
+      const reclaimed = await fx.store.organizationSlugs.claim("acme");
+      expect(reclaimed.claimed, "a released slug is claimable at once").toBe(
+        true,
+      );
+
+      // Another create's claim of the same slug carries another time, so
+      // a stale release never frees it.
+      await fx.store.organizationSlugs.release({
+        ...reclaimed.entry,
+        claimedAt: "2000-01-01T00:00:00.000Z",
+      });
+      expect(await fx.store.organizationSlugs.find("acme")).toEqual(
+        reclaimed.entry,
+      );
+
+      // A retired slug is never freed, whoever asks.
+      await fx.store.organizationSlugs.retire("acme");
+      await fx.store.organizationSlugs.release(reclaimed.entry);
+      expect(
+        (await fx.store.organizationSlugs.find("acme"))?.retiredAt,
+      ).not.toBe("");
+    });
+  });
+
   describe("oauth grants", () => {
     const grant: OAuthGrant = {
       identityAccountId: "ida_1",
@@ -1880,6 +1962,9 @@ export function describeStoreContract(
       await expect(fx.store.signalDedupe.release("o", "k")).rejects.toThrow(
         "store is closed",
       );
+      await expect(fx.store.organizationSlugs.claim("o")).rejects.toThrow(
+        "store is closed",
+      );
     });
   });
 }

package/src/store/interface.ts

@@ -328,6 +328,75 @@ export interface SignalDedupeStore {
   release(org: string, idempotencyKey: string): Promise<void>;
 }
 
+// =============================================================================
+// Organization slugs (the ledger of every slug an organization ever took)
+// =============================================================================
+
+/**
+ * One slug's line in the ledger. An organization's id is its slug, so this
+ * is also the history of every organization id the store ever issued.
+ */
+export interface OrganizationSlugEntry {
+  readonly slug: string;
+  /**
+   * RFC-3339 time the ledger first recorded the slug: the create's claim,
+   * or, for a slug that predates the ledger, the migration or retire that
+   * wrote it.
+   */
+  readonly claimedAt: string;
+  /** RFC-3339 time the organization holding it was deleted; "" while it is held. */
+  readonly retiredAt: string;
+}
+
+/** A claim's outcome: won with its entry, or lost to the entry that holds the slug. */
+export type OrganizationSlugClaim =
+  | { readonly claimed: true; readonly entry: OrganizationSlugEntry }
+  | { readonly claimed: false; readonly entry: OrganizationSlugEntry };
+
+/**
+ * The organization-slug ledger: a slug is claimed once, atomically, by the
+ * create that takes it, and it is never released by the organization's
+ * delete, which retires it instead. The organization row can go; its slug
+ * stays taken for good, so nothing a deleted organization left behind
+ * (rows that name it in `metadata.org`, an edition's rows kept by its id)
+ * can ever pass to a new holder of the same slug.
+ *
+ * The ledger, not the organization row, decides "taken". A claim is the
+ * create's uniqueness guarantee, which the row cannot give: `saveResource`
+ * upserts, so two creates that both read "absent" would otherwise both
+ * write, the second over the first.
+ *
+ * An unretired entry is a slug held by a live organization, or by a create
+ * between its claim and its row; a retired entry is a slug whose
+ * organization was deleted. A caller tells the two apart, never "no row"
+ * alone, because a create in flight has a claim and no row yet.
+ */
+export interface OrganizationSlugStore {
+  /**
+   * Claims a slug if no entry holds it, atomically: of concurrent claims,
+   * exactly one wins. A loser receives the entry that holds the slug,
+   * retired or not.
+   */
+  claim(slug: string): Promise<OrganizationSlugClaim>;
+  /**
+   * Marks the slug retired: sets `retiredAt` on its entry when it is
+   * empty, or records the slug already retired when no entry exists (an
+   * organization created before the ledger). Idempotent; a second retire
+   * keeps the first time.
+   */
+  retire(slug: string): Promise<void>;
+  /**
+   * Frees a claim whose create failed before its organization was stored,
+   * so the caller's retry can claim again. Guarded: only the unretired
+   * entry carrying this exact `claimedAt` is removed, so a release can
+   * never free a retired slug or another create's claim. Anything else is
+   * a no-op.
+   */
+  release(entry: OrganizationSlugEntry): Promise<void>;
+  /** The slug's entry, or undefined when no organization ever took it. */
+  find(slug: string): Promise<OrganizationSlugEntry | undefined>;
+}
+
 // =============================================================================
 // MCP OAuth (Go: pkg/domain/mcpserver/oauth, tables consolidated by v7 / OD-3)
 // =============================================================================
@@ -863,6 +932,7 @@ export interface Store {
 
   readonly bootstrapState: BootstrapStateStore;
   readonly signalDedupe: SignalDedupeStore;
+  readonly organizationSlugs: OrganizationSlugStore;
   readonly oauthGrants: OAuthGrantStore;
   readonly pendingOAuthStates: PendingOAuthStateStore;