@stigmer/server 3.38.3 → 3.39.0

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

package/src/domain/organization/steps.ts

@@ -10,9 +10,11 @@
  * uniqueness guarantee, mirroring cloud's OrganizationCreateHandler
  * (CheckDuplicate + CopySlugToId) step-for-step.
  *
- * The same deviation shapes the delete: a freed slug is anyone's to take,
- * so newRevokeOrganizationPoliciesStep revokes the organization's policy
- * rows BEFORE its row is deleted, and fails the delete when it cannot.
+ * The same deviation shapes the delete. A slug is never taken twice
+ * (slug-ledger.ts), and newRevokeOrganizationPoliciesStep still revokes
+ * the organization's policy rows BEFORE its row is deleted, and fails the
+ * delete when it cannot, so nothing that grants on the organization
+ * outlives it.
  *
  * Proven by organization.conformance.test.ts (CONFORMANCE_TARGET=local),
  * __tests__/organization.test.ts and __tests__/organization-delete.test.ts.
@@ -28,6 +30,7 @@ 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 type { IamPolicyGrantPath } from "../iampolicy/grant-path.js";
+import { refusalForHeldSlug } from "./slug-ledger.js";
 
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { ApiResourceRefSchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
@@ -48,6 +51,13 @@ import { OrganizationSchema } from "@stigmer/protos/ai/stigmer/tenancy/organizat
  * organization. Checking existence by id (== the resolved slug) closes
  * that hole and mirrors cloud's OrganizationCreateHandler.CheckDuplicate.
  *
+ * A slug is taken for good (slug-ledger.ts), so the slug ledger is read
+ * first: a retired slug is refused with the reserved reason, a held one
+ * with the duplicate copy. The row is read after it for an organization no
+ * ledger entry records yet, one an older binary created during a rolling
+ * upgrade. This read is the early refusal, before any gate; the atomic
+ * guarantee is ClaimOrganizationSlug's, immediately before Persist.
+ *
  * Runs after ResolveSlug (slug is set) and before BuildNewState/
  * CopySlugToId (the id is not yet minted), so it keys on the slug value
  * that will become the id.
@@ -70,6 +80,16 @@ export function newCheckOrgDuplicateStep(
         throw internalError(new Error("organization slug is empty"), "duplicate check");
       }
 
+      let entry;
+      try {
+        entry = await store.organizationSlugs.find(metadata.slug);
+      } catch (error) {
+        throw internalError(error, "failed to check for duplicate organization");
+      }
+      if (entry !== undefined) {
+        throw refusalForHeldSlug(entry);
+      }
+
       try {
         await store.getResource(
           ctx.apiResourceKind,
@@ -120,9 +140,11 @@ export function newCopySlugToIdStep(): PipelineStep<typeof OrganizationSchema> {
  *
  * The generic delete chains clean up after the row and log a fault,
  * because a deleted resource's rows grant nothing once it is gone. An
- * organization is the exception: its id is its slug, the delete frees the
- * slug, and a row left behind would grant whoever creates the slug next.
- * So this step does not catch. A fault fails the delete with the
+ * organization is the exception: its rows are the grants on the tenancy
+ * root itself, and the scope link of every resource under it. The slug is
+ * never taken again (slug-ledger.ts), so they cannot pass to a new holder,
+ * but a row left behind would still be a grant nobody administers. So this
+ * step does not catch. A fault fails the delete with the
  * organization in place, and a retry resumes where the revocation stopped
  * (the grant path revokes the organization's owners last, so the owner
  * who retries still can). The grant path fires the composed driver's

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

@@ -37,10 +37,6 @@ 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],

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;