@stigmer/server 3.38.3 → 3.39.1-dev.20260928194002

package/src/domain/organization/__tests__/organization-slugs.test.ts

@@ -0,0 +1,386 @@
+/**
+ * Pins the create side of "an organization's slug is its for good"
+ * (slug-ledger.ts) through a composed server in the trusted-local posture:
+ *
+ *   - of two concurrent creates of one slug exactly one succeeds, and the
+ *     other is refused as a duplicate with one owner row between them;
+ *   - a create racing another create's claim, before that create's row
+ *     exists, is refused as a duplicate, never as a deleted organization's;
+ *   - a pre-side-effect gate's refusal leaves no claim, so the create
+ *     succeeds once the gate lets it;
+ *   - a create that fails after its row is stored keeps its slug;
+ *   - an organization no ledger entry records (one an older binary created)
+ *     is still refused as a duplicate by its row, and its delete retires
+ *     the slug.
+ *
+ * And, over doubles, the release a failed create runs: it frees the claim
+ * only when the organization was never stored, and every fault it meets
+ * leaves the slug claimed.
+ *
+ * The delete side (the retire, its order and its faults) is
+ * organization-delete.test.ts's.
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { create } from "@bufbuild/protobuf";
+import type { DescMessage } from "@bufbuild/protobuf";
+import { Code, ConnectError, createClient } from "@connectrpc/connect";
+import type { Client } from "@connectrpc/connect";
+import { createGrpcTransport } from "@connectrpc/connect-node";
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "vitest";
+
+import type { Organization } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
+import { OrganizationSchema } 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";
+import type { ComposedServer } from "../../../boot/compose.js";
+import { createLogger } from "../../../boot/logger.js";
+import type { Logger } from "../../../boot/logger.js";
+import type { GateSlotName } from "../../../extensions/gate-slots.js";
+import type { ServerExtension } from "../../../extensions/registry.js";
+import type { PipelineStep } from "../../../pipeline/pipeline.js";
+import { testCallerIdentity } from "../../../pipeline/__tests__/support.js";
+import { RequestContext } from "../../../pipeline/request-context.js";
+import { metadataOf } from "../../../pipeline/steps/shapes.js";
+import {
+  resetOperatorIdentityForTests,
+  setOperatorIdentity,
+} from "../../../pipeline/steps/defaults.js";
+import { ResourceNotFoundError } from "../../../store/interface.js";
+import type { OrganizationSlugEntry, Store } from "../../../store/interface.js";
+import { fakeIamPolicyStore } from "../../iampolicy/__tests__/support.js";
+import {
+  newClaimOrganizationSlugStep,
+  releaseSlugClaimAfterFailure,
+} from "../slug-ledger.js";
+
+const OPERATOR_EMAIL = "operator@example.com";
+const DUPLICATE_COPY = (slug: string) =>
+  `Organization already exists: slug '${slug}'`;
+
+async function grpcError(run: () => Promise<unknown>): Promise<ConnectError> {
+  try {
+    await run();
+  } catch (error) {
+    if (error instanceof ConnectError) {
+      return error;
+    }
+    throw error;
+  }
+  throw new Error("expected the call to fail");
+}
+
+function organizationInput(slug: string) {
+  return {
+    apiVersion: "tenancy.stigmer.ai/v1",
+    kind: "Organization",
+    metadata: { name: slug, slug, org: "" },
+    spec: { description: "created by the organization slug test" },
+  };
+}
+
+describe("organization slugs on create (composed server, trusted-local posture)", () => {
+  const policies = fakeIamPolicyStore();
+  /** Slugs the pre-side-effect gate refuses while listed. */
+  const gateRefuses = new Set<string>();
+  /** Slugs whose post-persist step fails, after the row is stored. */
+  const postPersistFails = new Set<string>();
+
+  const slugOf = (organization: Organization) =>
+    organization.metadata?.slug ?? "";
+  const gateStep: PipelineStep<DescMessage> = {
+    name: "FakeOrgLimitGate",
+    execute: (ctx) => {
+      const slug = slugOf(ctx.newState as Organization);
+      if (gateRefuses.has(slug)) {
+        throw new ConnectError(
+          "fake limit on organizations",
+          Code.FailedPrecondition,
+        );
+      }
+    },
+  };
+  const postPersistStep: PipelineStep<DescMessage> = {
+    name: "FakeOrgPostPersist",
+    execute: (ctx) => {
+      const slug = slugOf(ctx.newState as Organization);
+      if (postPersistFails.has(slug)) {
+        throw new ConnectError("fake companion failed", Code.Unavailable);
+      }
+    },
+  };
+  const unit: ServerExtension = {
+    name: "fake-org-create",
+    gateSteps: new Map<GateSlotName, ReadonlyArray<PipelineStep<DescMessage>>>([
+      ["org-create:pre-side-effect-gate", [gateStep]],
+      ["org-create:post-persist", [postPersistStep]],
+    ]),
+    drivers: { iamPolicyStore: policies },
+  };
+
+  let dir: string;
+  let server: ComposedServer;
+  let organizations: Client<typeof OrganizationCommandController>;
+  let organizationQuery: Client<typeof OrganizationQueryController>;
+
+  function ownersOf(org: string): number {
+    return [...policies.rows.values()].filter(
+      (policy) =>
+        policy.spec?.resource?.kind === "organization" &&
+        policy.spec.resource.id === org &&
+        policy.spec.relation === "owner",
+    ).length;
+  }
+
+  beforeAll(async () => {
+    dir = mkdtempSync(path.join(tmpdir(), "organization-slugs-test-"));
+    setOperatorIdentity(OPERATOR_EMAIL, "The Operator");
+    server = await composeServer({
+      config: loadConfig({
+        STIGMER_MODEL_REGISTRY_REFRESH: "off",
+        TEMPORAL_HOST_PORT: "127.0.0.1:1",
+        DB_PATH: path.join(dir, "stigmer.db"),
+        STORAGE_PATH: path.join(dir, "storage"),
+        ARTIFACT_LOCAL_BASE_PATH: path.join(dir, "artifacts"),
+        STIGMER_OPERATOR_EMAIL: OPERATOR_EMAIL,
+      }),
+      logger: createLogger({ level: "error", pretty: false, write: () => {} }),
+      extensions: [unit],
+      portOverride: 0,
+      host: "127.0.0.1",
+    });
+    const port = await server.start();
+    const transport = createGrpcTransport({
+      baseUrl: `http://127.0.0.1:${port}`,
+    });
+    organizations = createClient(OrganizationCommandController, transport);
+    organizationQuery = createClient(OrganizationQueryController, transport);
+  });
+
+  afterAll(async () => {
+    await server.shutdown();
+    resetOperatorIdentityForTests();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  beforeEach(() => {
+    gateRefuses.clear();
+    postPersistFails.clear();
+  });
+
+  it("of two concurrent creates of one slug, exactly one succeeds and the other is a duplicate", async () => {
+    const results = await Promise.allSettled([
+      organizations.create(organizationInput("contended")),
+      organizations.create(organizationInput("contended")),
+    ]);
+
+    expect(
+      results.filter((result) => result.status === "fulfilled"),
+    ).toHaveLength(1);
+    const [rejected] = results.filter(
+      (result): result is PromiseRejectedResult => result.status === "rejected",
+    );
+    const refusal = ConnectError.from(rejected?.reason);
+    expect(refusal.code).toBe(Code.AlreadyExists);
+    expect(refusal.rawMessage).toBe(DUPLICATE_COPY("contended"));
+    expect(refusal.findDetails(ErrorInfoSchema)).toEqual([]);
+    expect(ownersOf("contended")).toBe(1);
+  });
+
+  it("a create racing another create's claim, before its row exists, is a duplicate and never a deleted organization's", async () => {
+    const inFlight = await server.store.organizationSlugs.claim("in-flight");
+    expect(inFlight.claimed).toBe(true);
+
+    const refusal = await grpcError(() =>
+      organizations.create(organizationInput("in-flight")),
+    );
+    expect(refusal.code).toBe(Code.AlreadyExists);
+    expect(refusal.rawMessage).toBe(DUPLICATE_COPY("in-flight"));
+    expect(refusal.findDetails(ErrorInfoSchema)).toEqual([]);
+  });
+
+  it("a pre-side-effect gate's refusal leaves no claim, so the create succeeds once the gate lets it", async () => {
+    gateRefuses.add("gated");
+    const refusal = await grpcError(() =>
+      organizations.create(organizationInput("gated")),
+    );
+    expect(refusal.code).toBe(Code.FailedPrecondition);
+    expect(await server.store.organizationSlugs.find("gated")).toBeUndefined();
+
+    gateRefuses.delete("gated");
+    const created = await organizations.create(organizationInput("gated"));
+    expect(created.metadata?.id).toBe("gated");
+  });
+
+  it("a create that fails after its row is stored keeps its slug", async () => {
+    postPersistFails.add("half-made");
+    const refusal = await grpcError(() =>
+      organizations.create(organizationInput("half-made")),
+    );
+    expect(refusal.code).toBe(Code.Unavailable);
+
+    const entry = await server.store.organizationSlugs.find("half-made");
+    expect(entry?.retiredAt).toBe("");
+    expect(
+      (await organizationQuery.get({ value: "half-made" })).metadata?.id,
+    ).toBe("half-made");
+
+    postPersistFails.delete("half-made");
+    const retry = await grpcError(() =>
+      organizations.create(organizationInput("half-made")),
+    );
+    expect(retry.code).toBe(Code.AlreadyExists);
+    expect(retry.rawMessage).toBe(DUPLICATE_COPY("half-made"));
+  });
+
+  it("an organization no ledger entry records is refused as a duplicate by its row, and its delete retires the slug", async () => {
+    await organizations.create(organizationInput("older"));
+    // What an older binary leaves: the row, and no ledger entry.
+    const entry = await server.store.organizationSlugs.find("older");
+    await server.store.organizationSlugs.release(entry!);
+    expect(await server.store.organizationSlugs.find("older")).toBeUndefined();
+
+    const duplicate = await grpcError(() =>
+      organizations.create(organizationInput("older")),
+    );
+    expect(duplicate.code).toBe(Code.AlreadyExists);
+    expect(duplicate.rawMessage).toBe(DUPLICATE_COPY("older"));
+
+    await organizations.delete({ value: "older" });
+    const reserved = await grpcError(() =>
+      organizations.create(organizationInput("older")),
+    );
+    expect(reserved.code).toBe(Code.AlreadyExists);
+    expect(reserved.findDetails(ErrorInfoSchema)[0]?.reason).toBe(
+      "ORGANIZATION_SLUG_RESERVED",
+    );
+  });
+});
+
+describe("releaseSlugClaimAfterFailure", () => {
+  const entry: OrganizationSlugEntry = {
+    slug: "acme",
+    claimedAt: "2026-09-28T00:00:00.000Z",
+    retiredAt: "",
+  };
+
+  function logger(): Logger & { errors: string[] } {
+    const errors: string[] = [];
+    return {
+      errors,
+      error: (message: string) => errors.push(message),
+      warn: () => {},
+      info: () => {},
+      debug: () => {},
+    } as unknown as Logger & { errors: string[] };
+  }
+
+  /** A store double: the organization row's read and the ledger's release. */
+  function storeWith(
+    rowRead: () => Promise<unknown>,
+    release: (claim: OrganizationSlugEntry) => Promise<void>,
+  ): Store {
+    return {
+      getResource: rowRead,
+      organizationSlugs: {
+        claim: async () => ({ claimed: true, entry }),
+        retire: async () => {},
+        release,
+        find: async () => entry,
+      },
+    } as unknown as Store;
+  }
+
+  /** A request whose ClaimOrganizationSlug won `entry`. */
+  async function claimedRequest(): Promise<
+    RequestContext<typeof OrganizationSchema>
+  > {
+    const ctx = new RequestContext(
+      OrganizationSchema,
+      create(OrganizationSchema, { metadata: { slug: "acme" } }),
+      testCallerIdentity(),
+    );
+    const claiming = {
+      organizationSlugs: { claim: async () => ({ claimed: true, entry }) },
+    } as unknown as Store;
+    await newClaimOrganizationSlugStep(claiming).execute(ctx);
+    expect(metadataOf(ctx.newState)?.slug).toBe("acme");
+    return ctx;
+  }
+
+  it("frees the claim when the organization was never stored", async () => {
+    const release = vi.fn(async () => {});
+    const store = storeWith(async () => {
+      throw new ResourceNotFoundError("organization acme");
+    }, release);
+
+    await releaseSlugClaimAfterFailure(store, logger(), await claimedRequest());
+    expect(release).toHaveBeenCalledWith(entry);
+  });
+
+  it("keeps the claim when the organization was stored", async () => {
+    const release = vi.fn(async () => {});
+    const store = storeWith(async () => ({}), release);
+
+    await releaseSlugClaimAfterFailure(store, logger(), await claimedRequest());
+    expect(release).not.toHaveBeenCalled();
+  });
+
+  it("keeps the claim, and logs, when the row cannot be read or the release faults", async () => {
+    const release = vi.fn(async () => {});
+    const unreadable = logger();
+    await releaseSlugClaimAfterFailure(
+      storeWith(async () => {
+        throw new Error("database locked");
+      }, release),
+      unreadable,
+      await claimedRequest(),
+    );
+    expect(release).not.toHaveBeenCalled();
+    expect(unreadable.errors).toHaveLength(1);
+
+    const faulting = logger();
+    await releaseSlugClaimAfterFailure(
+      storeWith(
+        async () => {
+          throw new ResourceNotFoundError("organization acme");
+        },
+        async () => {
+          throw new Error("database locked");
+        },
+      ),
+      faulting,
+      await claimedRequest(),
+    );
+    expect(faulting.errors).toHaveLength(1);
+  });
+
+  it("does nothing for a request that never claimed", async () => {
+    const release = vi.fn(async () => {});
+    const store = storeWith(async () => {
+      throw new ResourceNotFoundError("organization acme");
+    }, release);
+    const unclaimed = new RequestContext(
+      OrganizationSchema,
+      create(OrganizationSchema, { metadata: { slug: "acme" } }),
+      testCallerIdentity(),
+    );
+
+    await releaseSlugClaimAfterFailure(store, logger(), unclaimed);
+    expect(release).not.toHaveBeenCalled();
+  });
+});

package/src/domain/organization/controller.ts

@@ -106,6 +106,11 @@ import { newValidateVisibilityStep } from "../../pipeline/steps/validate-visibil
 import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import { organizationSearchExtractor } from "./search-extractor.js";
+import {
+  newClaimOrganizationSlugStep,
+  newRetireOrganizationSlugStep,
+  releaseSlugClaimAfterFailure,
+} from "./slug-ledger.js";
 import {
   newCheckOrgDuplicateStep,
   newCopySlugToIdStep,
@@ -175,6 +180,13 @@ function kindOf(ctx: HandlerContext): ApiResourceKind {
  * refusal there leaves no organization behind. It is where a limit on
  * which organizations may exist is enforced.
  *
+ * ClaimOrganizationSlug follows the slot, immediately before Persist: the
+ * slug is claimed in the ledger atomically, so of two concurrent creates of
+ * one slug exactly one proceeds, and a slug any organization ever held is
+ * refused (slug-ledger.ts). When the chain fails after the claim and the
+ * organization was never stored, the claim is released so a retry can take
+ * the slug.
+ *
  * The post-persist gate slot splices after Persist, before IndexSearch —
  * the verified Java OrganizationCreateHandler ordering (FGA tuple
  * seeding, billing account getOrCreate: synchronous, a failure fails the
@@ -218,6 +230,7 @@ async function createOrganization(
     builder.addStep(step);
   }
   builder
+    .addStep(newClaimOrganizationSlugStep(deps.store))
     .addStep(newPersistStep(deps.store))
     // The C2 tuple step runs BEFORE the post-persist slot — the verified
     // Java order (createAuthorizationTuples → linkManagedOrgToIdentityProvider
@@ -236,12 +249,17 @@ async function createOrganization(
   )) {
     builder.addStep(step);
   }
-  await builder
+  const pipeline = builder
     .addStep(
       newIndexSearchStep(deps.store, organizationSearchExtractor, deps.logger),
     )
-    .build()
-    .execute(reqCtx);
+    .build();
+  try {
+    await pipeline.execute(reqCtx);
+  } catch (error) {
+    await releaseSlugClaimAfterFailure(deps.store, deps.logger, reqCtx);
+    throw error;
+  }
   return reqCtx.newState;
 }
 
@@ -329,21 +347,24 @@ async function apply(
 /**
  * Delete — returns the deleted organization (gRPC audit-trail convention).
  *
- * Everything that names the organization goes before its row, and a fault
- * stops the delete with the organization intact: an organization's id is
- * its slug, the delete frees the slug for anyone, and whatever outlived
- * the row would belong to the slug's next holder. So, after the load:
+ * An organization's id is its slug, and a slug is never taken again
+ * (slug-ledger.ts), so whatever outlives the row can never pass to a new
+ * holder of the slug. Everything that grants on the organization still
+ * goes before its row, and a fault stops the delete with the organization
+ * intact, so nothing it granted outlives it. After the load:
  *
- *   1. the `org-delete:pre-delete` slot, where an edition refuses or
+ *   1. RetireOrganizationSlug, the slug marked retired in the ledger, so it
+ *      is retired before the row can go;
+ *   2. the `org-delete:pre-delete` slot, where an edition refuses or
  *      removes the rows it keeps for the organization (empty in OSS);
- *   2. RevokeOrganizationPolicies, every policy row naming the
+ *   3. RevokeOrganizationPolicies, every policy row naming the
  *      organization, through the grant path, never caught;
- *   3. the row;
- *   4. CleanupIamPolicies, the lifecycle's post-delete event: best-effort
+ *   4. the row;
+ *   5. CleanupIamPolicies, the lifecycle's post-delete event: best-effort
  *      like every delete chain's, it revokes whatever a concurrent write
- *      named the organization with after step 2, and runs a composed
+ *      named the organization with after step 3, and runs a composed
  *      driver's post-delete companions;
- *   5. the search entry.
+ *   6. the search entry.
  */
 async function deleteOrganization(
   deps: OrganizationControllerDeps,
@@ -366,7 +387,8 @@ async function deleteOrganization(
     )
     .addStep(newValidateProtoStep())
     .addStep(newExtractResourceIdStep())
-    .addStep(newLoadExistingForDeleteStep(deps.store, OrganizationSchema));
+    .addStep(newLoadExistingForDeleteStep(deps.store, OrganizationSchema))
+    .addStep(newRetireOrganizationSlugStep<DeleteInput>(deps.store));
   // The pre-delete gate slot (see the doc comment above). Empty in OSS.
   for (const step of stepsForSlot<DeleteInput>(
     deps.gateSteps,

package/src/domain/organization/slug-ledger.ts

@@ -0,0 +1,209 @@
+/**
+ * The organization domain's use of the slug ledger (the Store's
+ * `organizationSlugs`; store/interface.ts states its guarantees): an
+ * organization's slug is its for good.
+ *
+ * An organization's id is its slug, and the delete removes the row. Rows
+ * that name the organization can outlive it (every organization-scoped
+ * resource names it in `metadata.org`, and an edition may keep its own rows
+ * by the id), so a slug taken again would hand them all to the new holder.
+ * The ledger closes that: the create claims the slug atomically, the delete
+ * retires it, and nothing ever frees a retired slug.
+ *
+ * The create touches the ledger twice. CheckDuplicate reads it first, so a
+ * taken slug is refused before any gate runs (steps.ts). ClaimOrganizationSlug
+ * then claims it immediately before Persist, after the pre-side-effect gate
+ * slot, so a gate's refusal still leaves nothing written; of two concurrent
+ * creates of one slug, exactly one claim wins, which the row alone cannot
+ * give because `saveResource` upserts. A create that fails after its claim
+ * and before its row is stored releases the claim, so the caller's retry
+ * can take the slug again; a create that fails after the row keeps it,
+ * because the organization exists.
+ *
+ * The refusal says why. A retired slug answers AlreadyExists carrying the
+ * ORGANIZATION_SLUG_RESERVED reason (the organization create's contract
+ * documents it), so the CLI and the console can tell a person the slug
+ * belonged to a deleted organization. A held slug keeps the existing copy
+ * with no reason: it covers a live organization and also a create between
+ * its claim and its row, which must never read as "deleted". Both keep the
+ * AlreadyExists code, which the personal-organization retry keys on.
+ *
+ * Proven by __tests__/organization-slugs.test.ts and the organization
+ * conformance suite.
+ */
+import type { DescMessage } from "@bufbuild/protobuf";
+import type { ConnectError } from "@connectrpc/connect";
+
+import type { Logger } from "../../boot/logger.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
+import type { OrganizationSlugEntry, Store } from "../../store/interface.js";
+import {
+  alreadyExistsError,
+  alreadyExistsWithReasonError,
+  internalError,
+} from "../../pipeline/errors.js";
+import type { PipelineStep } from "../../pipeline/pipeline.js";
+import type { RequestContext } from "../../pipeline/request-context.js";
+import { EXISTING_RESOURCE_KEY } from "../../pipeline/steps/load-existing.js";
+import { metadataOf } from "../../pipeline/steps/shapes.js";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { Organization } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
+import { OrganizationSchema } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
+
+/**
+ * The ErrorInfo reason a create of a retired slug carries: a deleted
+ * organization held the slug, and a slug is never reused. Wire contract,
+ * documented on OrganizationCommandController.create; metadata `slug`.
+ */
+export const ORGANIZATION_SLUG_RESERVED = "ORGANIZATION_SLUG_RESERVED";
+
+/** Where ClaimOrganizationSlug leaves the entry it won, for the release after a failure. */
+const CLAIMED_SLUG_KEY = "organizationSlugClaim";
+
+/** The copy of a retired slug's refusal. */
+export function organizationSlugReservedMessage(slug: string): string {
+  return `Organization slug '${slug}' belonged to an organization that was deleted, and a slug is never reused`;
+}
+
+/**
+ * The refusal for a slug an entry already holds: the reserved refusal for a
+ * retired entry, the existing duplicate copy for one still held.
+ */
+export function refusalForHeldSlug(entry: OrganizationSlugEntry): ConnectError {
+  if (entry.retiredAt !== "") {
+    return alreadyExistsWithReasonError(
+      organizationSlugReservedMessage(entry.slug),
+      { reason: ORGANIZATION_SLUG_RESERVED, metadata: { slug: entry.slug } },
+    );
+  }
+  return alreadyExistsError("Organization", `slug '${entry.slug}'`);
+}
+
+/**
+ * Claims the new organization's slug, immediately before Persist. A lost
+ * claim is refused by the entry that holds the slug; a won claim is left in
+ * the request for releaseSlugClaimAfterFailure.
+ */
+export function newClaimOrganizationSlugStep(
+  store: Store,
+): PipelineStep<typeof OrganizationSchema> {
+  return {
+    name: "ClaimOrganizationSlug",
+    async execute(
+      ctx: RequestContext<typeof OrganizationSchema>,
+    ): Promise<void> {
+      const slug = metadataOf(ctx.newState)?.slug ?? "";
+      // ResolveSlug and CheckDuplicate run first, so an empty slug here is
+      // a server-side ordering bug, not bad client input.
+      if (slug === "") {
+        throw internalError(
+          new Error("organization slug is empty"),
+          "failed to claim the organization slug",
+        );
+      }
+      let claim;
+      try {
+        claim = await store.organizationSlugs.claim(slug);
+      } catch (error) {
+        throw internalError(error, "failed to claim the organization slug");
+      }
+      if (!claim.claimed) {
+        throw refusalForHeldSlug(claim.entry);
+      }
+      ctx.set(CLAIMED_SLUG_KEY, claim.entry);
+    },
+  };
+}
+
+/**
+ * Frees the slug a failed create claimed, when its organization was never
+ * stored, so the caller's retry can take the slug again. Called by the
+ * create around its chain, as send-signal.ts releases a dedupe claim.
+ *
+ * Whether the row exists decides, rather than which step failed: a Persist
+ * that stored the row and then failed keeps the claim, as it must, because
+ * the organization exists. Any fault here is logged and leaves the slug
+ * claimed with no organization, which nothing can then take; that is a
+ * hand's to resolve, and far rarer than the failure it follows.
+ */
+export async function releaseSlugClaimAfterFailure(
+  store: Store,
+  logger: Logger,
+  ctx: RequestContext<typeof OrganizationSchema>,
+): Promise<void> {
+  const entry = ctx.get(CLAIMED_SLUG_KEY) as OrganizationSlugEntry | undefined;
+  if (entry === undefined) {
+    return;
+  }
+  try {
+    await store.getResource(
+      ApiResourceKind.organization,
+      entry.slug,
+      OrganizationSchema,
+    );
+    return; // stored: the organization exists and keeps its slug
+  } catch (error) {
+    if (!(error instanceof ResourceNotFoundError)) {
+      logger.error(
+        "organization create failed and its slug claim could not be checked; the slug stays claimed",
+        {
+          slug: entry.slug,
+          error: error instanceof Error ? error.message : String(error),
+        },
+      );
+      return;
+    }
+  }
+  try {
+    await store.organizationSlugs.release(entry);
+  } catch (error) {
+    logger.error(
+      "organization create failed and its slug claim could not be released; the slug stays claimed",
+      {
+        slug: entry.slug,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    );
+  }
+}
+
+/**
+ * Retires the organization's slug before anything else the delete does,
+ * right after the organization is loaded. Its entry may not exist yet (an
+ * organization created before the ledger, or by an older binary during a
+ * rolling upgrade), and retire records it either way, so the slug is
+ * retired before the row can go.
+ *
+ * A fault fails the delete with the organization intact. A delete that
+ * fails later (an edition's refusal on the pre-delete slot, a revocation
+ * fault) leaves a live organization whose slug reads as retired; nothing
+ * observes that, because a create of the slug is refused either way, and a
+ * retry of the delete resumes.
+ */
+export function newRetireOrganizationSlugStep<Desc extends DescMessage>(
+  store: Store,
+): PipelineStep<Desc> {
+  return {
+    name: "RetireOrganizationSlug",
+    async execute(ctx: RequestContext<Desc>): Promise<void> {
+      const organization = ctx.get(EXISTING_RESOURCE_KEY) as
+        | Organization
+        | undefined;
+      const id = organization?.metadata?.id ?? "";
+      if (id === "") {
+        throw internalError(
+          new Error(
+            "organization delete reached RetireOrganizationSlug without its loaded row",
+          ),
+          "failed to retire the organization slug",
+        );
+      }
+      try {
+        await store.organizationSlugs.retire(id);
+      } catch (error) {
+        throw internalError(error, "failed to retire the organization slug");
+      }
+    },
+  };
+}