@stigmer/server 3.32.0 → 3.34.0

package/src/domain/apikey/verifier.ts

@@ -33,14 +33,28 @@
  * identityId changes on a hit: email/displayName stay the stamp's, the
  * actor the key recorded at minting. The credential checks run first, so
  * a revoked or expired key never reaches the account store.
+ *
+ * An accepted key's use is then recorded on its status.last_used_at
+ * (identity/credential-use.ts): at most once a resolution, judged from the
+ * row this read already holds, written atomically through
+ * Store.updateResource so it can never undo a concurrent update of the
+ * key, and best-effort — a failed stamp is logged and the request
+ * proceeds. A refused key records nothing (stigmer/stigmer#1255).
  */
 import { Code, ConnectError } from "@connectrpc/connect";
+import { create } from "@bufbuild/protobuf";
 import { timestampDate } from "@bufbuild/protobuf/wkt";
 
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiKeySchema, ApiKeyStatusSchema } from "@stigmer/protos/ai/stigmer/iam/apikey/v1/api_pb";
+import type { ApiKey } from "@stigmer/protos/ai/stigmer/iam/apikey/v1/api_pb";
+
+import type { Logger } from "../../boot/logger.js";
 import type {
   CallerIdentity,
   IdentityVerifier,
 } from "../../extensions/identity.js";
+import { recordCredentialUse } from "../../identity/credential-use.js";
 import type { Store } from "../../store/interface.js";
 import { identityIdForSubject } from "../identityaccount/resolve.js";
 import type { AccountsBySubject } from "../identityaccount/resolve.js";
@@ -58,12 +72,16 @@ export interface ApiKeyVerifierDeps {
   readonly store: Store;
   /** The identity-account domain's subject lookup the creator stamp resolves through (A6). */
   readonly accounts: AccountsBySubject;
+  /** Where a failed last-use stamp is reported. */
+  readonly logger: Logger;
+  /** The clock both the expiry check and the last-use stamp read. */
+  readonly now: () => Date;
 }
 
 export function newApiKeyIdentityVerifier(
   deps: ApiKeyVerifierDeps,
 ): IdentityVerifier {
-  const { store, accounts } = deps;
+  const { store, accounts, logger } = deps;
   return {
     name: "apikey",
     async verify(token: string): Promise<CallerIdentity | null> {
@@ -74,8 +92,9 @@ export function newApiKeyIdentityVerifier(
       if (key === undefined) {
         throw new ConnectError(INVALID_TOKEN_MESSAGE, Code.Unauthenticated);
       }
+      const now = deps.now();
       const expiresAt = key.spec?.expiresAt;
-      if (expiresAt !== undefined && timestampDate(expiresAt) <= new Date()) {
+      if (expiresAt !== undefined && timestampDate(expiresAt) <= now) {
         throw new ConnectError(TOKEN_EXPIRED_MESSAGE, Code.Unauthenticated);
       }
       const owner = key.status?.audit?.specAudit?.createdBy;
@@ -85,8 +104,10 @@ export function newApiKeyIdentityVerifier(
         // through the pipeline; guards hand-seeded or corrupted rows).
         throw new ConnectError(INVALID_TOKEN_MESSAGE, Code.Unauthenticated);
       }
+      const identityId = await identityIdForSubject(accounts, owner.id);
+      await recordKeyUse(store, logger, key, now);
       return {
-        identityId: await identityIdForSubject(accounts, owner.id),
+        identityId,
         callerClass: "user",
         issuer: "",
         rawToken: token,
@@ -96,3 +117,25 @@ export function newApiKeyIdentityVerifier(
     },
   };
 }
+
+/** Stamps the accepted key's last use on its own row, atomically. */
+function recordKeyUse(
+  store: Store,
+  logger: Logger,
+  key: ApiKey,
+  now: Date,
+): Promise<void> {
+  const id = key.metadata?.id ?? "";
+  return recordCredentialUse({
+    credential: "api key",
+    id,
+    lastUsedAt: key.status?.lastUsedAt,
+    now,
+    logger,
+    write: (stamp) =>
+      store.updateResource(ApiResourceKind.api_key, id, ApiKeySchema, (live) => {
+        live.status ??= create(ApiKeyStatusSchema);
+        stamp(live.status);
+      }),
+  });
+}

package/src/domain/organization/controller.ts

@@ -156,6 +156,11 @@ function kindOf(ctx: HandlerContext): ApiResourceKind {
  * ValidateProto so clients can omit the slug and have it derived before
  * field constraints (slug pattern, 2–15 chars) are checked.
  *
+ * The pre-side-effect gate slot splices before Persist, after the last pure
+ * step, the session chain's position: every step above it only reads, so a
+ * refusal there leaves no organization behind. It is where a limit on
+ * which organizations may exist is enforced.
+ *
  * 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
@@ -190,11 +195,19 @@ async function createOrganization(
     .addStep(newCheckOrgDuplicateStep(deps.store))
     .addStep(newBuildNewStateStep())
     .addStep(newGuardReservedLabelsStep(deps.authorizer))
-    .addStep(newCopySlugToIdStep())
+    .addStep(newCopySlugToIdStep());
+  // The pre-side-effect gate slot (see the doc comment above). Empty in OSS.
+  for (const step of stepsForSlot<typeof OrganizationSchema>(
+    deps.gateSteps,
+    "org-create:pre-side-effect-gate",
+  )) {
+    builder.addStep(step);
+  }
+  builder
     .addStep(newPersistStep(deps.store))
-    // The C2 tuple step runs BEFORE the slot — the verified Java order
-    // (createAuthorizationTuples → linkManagedOrgToIdentityProvider →
-    // provisionBillingAccount). No-op with no driver composed.
+    // The C2 tuple step runs BEFORE the post-persist slot — the verified
+    // Java order (createAuthorizationTuples → linkManagedOrgToIdentityProvider
+    // → provisionBillingAccount). No-op with no driver composed.
     .addStep(
       newCreateAuthorizationTuplesStep(
         deps.authorizationLifecycle,

package/src/domain/platformclient/__tests__/mint.test.ts

@@ -15,13 +15,17 @@
  *     nothing; a failed create leaves the grant, and the next mint completes
  *     the account; a concurrent winner is read back;
  *   - the default role is viewer, owner is refused, and the token carries
- *     the cloud's claim set for the account.
+ *     the cloud's claim set for the account;
+ *   - a successful mint stamps the client's last use through the port's
+ *     atomic modifyById (never the whole-row update), once per resolution;
+ *     a refused mint records nothing; a stamp that cannot be written is
+ *     logged and the token is still answered (stigmer/stigmer#1255).
  */
 import { generateKeyPairSync } from "node:crypto";
 
 import { Code, ConnectError } from "@connectrpc/connect";
-import { create } from "@bufbuild/protobuf";
-import { timestampFromDate } from "@bufbuild/protobuf/wkt";
+import { clone, create } from "@bufbuild/protobuf";
+import { timestampDate, timestampFromDate } from "@bufbuild/protobuf/wkt";
 import { describe, expect, it } from "vitest";
 
 import type { IdentityAccount } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
@@ -30,12 +34,18 @@ import { IdentityAccountProvisioningMode } from "@stigmer/protos/ai/stigmer/iam/
 import { IamPolicySchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
 import type { IamPolicySpec } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
 import type { PlatformClient } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
-import { PlatformClientSchema } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
+import {
+  PlatformClientSchema,
+  PlatformClientStatusSchema,
+} from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
 import { MintUserTokenRequestSchema } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/token_pb";
 import { IamRole } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
 
+import { createLogger } from "../../../boot/logger.js";
+import type { Logger } from "../../../boot/logger.js";
 import type { CallerIdentity } from "../../../extensions/identity.js";
 import { silentLogger } from "../../../extensions/__tests__/composed-support.js";
+import { LAST_USED_RESOLUTION_MS } from "../../../identity/credential-use.js";
 import { verifyPlatformToken } from "../../../platformtoken/envelope.js";
 import { platformTokenKeyRingFromPem } from "../../../platformtoken/key-ring.js";
 import type { PlatformTokenKeyRing } from "../../../platformtoken/key-ring.js";
@@ -101,6 +111,10 @@ interface Harness {
   }>;
   readonly granted: Array<{ spec: IamPolicySpec; caller: CallerIdentity }>;
   readonly accounts: Map<string, IdentityAccount>;
+  /** The client row as the port holds it; modifyById writes here. */
+  readonly stored: { client: PlatformClient };
+  /** Every port write, by method: the stamp must ride modifyById alone. */
+  readonly clientWrites: string[];
 }
 
 function harness(
@@ -109,9 +123,12 @@ function harness(
     keys?: PlatformTokenKeyRing | undefined;
     failGrant?: boolean;
     failCreate?: "fault" | "lost-race";
+    failStamp?: boolean;
+    logger?: Logger;
   } = {},
 ): Harness {
-  const client = options.client ?? platformClient();
+  const stored = { client: options.client ?? platformClient() };
+  const clientWrites: string[] = [];
   const events: string[] = [];
   const created: Harness["created"] = [];
   const granted: Harness["granted"] = [];
@@ -126,12 +143,25 @@ function harness(
   };
   const deps: PlatformClientMintDeps = {
     clients: {
-      save: async () => {},
-      update: async () => {},
+      save: async () => {
+        clientWrites.push("save");
+      },
+      update: async () => {
+        clientWrites.push("update");
+      },
+      modifyById: async (id, modify) => {
+        clientWrites.push("modifyById");
+        if (options.failStamp === true) throw new Error("client store down");
+        if (id !== stored.client.metadata?.id) return undefined;
+        const next = clone(PlatformClientSchema, stored.client);
+        modify(next);
+        stored.client = next;
+        return next;
+      },
       deleteById: async () => {},
-      findById: async () => client,
+      findById: async () => stored.client,
       findByClientId: async (clientId) =>
-        clientId === client.spec?.clientId ? client : undefined,
+        clientId === stored.client.spec?.clientId ? stored.client : undefined,
       findByOrgAndSlug: async () => undefined,
       findByOrg: async () => [],
     },
@@ -156,10 +186,10 @@ function harness(
     },
     grantPath,
     keys: "keys" in options ? options.keys : RING,
-    logger: silentLogger,
+    logger: options.logger ?? silentLogger,
     now: () => NOW,
   };
-  return { deps, events, created, granted, accounts };
+  return { deps, events, created, granted, accounts, stored, clientWrites };
 }
 
 function request(
@@ -419,3 +449,59 @@ describe("mintUserToken — the user", () => {
     );
   });
 });
+
+describe("mintUserToken — the client's last use", () => {
+  it("a successful mint stamps the client's last use at the mint's clock, through modifyById alone", async () => {
+    const h = harness();
+    await mintUserToken(h.deps, request());
+    expect(h.clientWrites).toEqual(["modifyById"]);
+    expect(timestampDate(h.stored.client.status!.lastUsedAt!)).toEqual(NOW);
+    expect(h.stored.client.status?.audit?.statusAudit?.event).toBe("updated");
+    expect(
+      h.stored.client.spec?.clientSecretHash,
+      "the stamp never rewrites the credential",
+    ).toBe(hashClientSecret(SECRET));
+  });
+
+  it("a mint inside the resolution writes nothing", async () => {
+    const recent = platformClient();
+    recent.status = create(PlatformClientStatusSchema, {
+      lastUsedAt: timestampFromDate(
+        new Date(NOW.getTime() - LAST_USED_RESOLUTION_MS / 2),
+      ),
+    });
+    const h = harness({ client: recent });
+    await mintUserToken(h.deps, request());
+    expect(h.clientWrites).toEqual([]);
+  });
+
+  it("a refused mint records nothing", async () => {
+    const h = harness();
+    await refusal(mintUserToken(h.deps, request({ clientSecret: "wrong" })));
+    await refusal(mintUserToken(h.deps, request({ orgId: "globex" })));
+    expect(h.clientWrites).toEqual([]);
+    expect(h.stored.client.status?.lastUsedAt).toBeUndefined();
+  });
+
+  it("a stamp that cannot be written is logged with the client's id and the token is still answered", async () => {
+    const lines: string[] = [];
+    const h = harness({
+      failStamp: true,
+      logger: createLogger({
+        level: "warn",
+        pretty: false,
+        write: (line) => lines.push(line),
+      }),
+    });
+    const response = await mintUserToken(h.deps, request());
+    expect(response.accessToken).not.toBe("");
+    expect(lines).toHaveLength(1);
+    expect(JSON.parse(lines[0]!)).toMatchObject({
+      level: "warn",
+      credential: "platform client",
+      id: "pcl_dashboard",
+      error: "client store down",
+    });
+    expect(lines[0], "the secret is never logged").not.toContain(SECRET);
+  });
+});

package/src/domain/platformclient/__tests__/resource-store.test.ts

@@ -39,6 +39,10 @@ const CONTRACT_CASE_NAMES = [
   "the same slug in another organization is a different client",
   "update replaces the row in place",
   "update of an unknown id writes nothing",
+  "modifyById persists what modify did, answers the persisted row, and the lookups follow it",
+  "modifyById of an unknown id answers undefined and writes nothing",
+  "a modify that throws writes nothing and rejects with its error",
+  "concurrent modifyById calls on one row lose no write",
   "deleteById frees the id, the client_id and the slug; deleting an unknown id resolves",
   "findByOrg answers every client of the organization and no other",
   "a disconnected store is an infrastructure fault, never 'not found'",

package/src/domain/platformclient/mint.ts

@@ -44,6 +44,14 @@
  *
  * The email and name in the token and on the account are the platform's
  * assertion; nothing on the server derives authority from either.
+ *
+ * A signed token is a successful mint, so the client's use is then
+ * recorded on its status.last_used_at (identity/credential-use.ts): at most
+ * once a resolution, judged from the row authentication already read,
+ * written through the port's atomic `modifyById` — never the whole-row
+ * `update`, which could write back the secret hash a concurrent rotation
+ * just replaced — and best-effort: a failed stamp is logged and the token
+ * is still answered. A refused mint records nothing (stigmer/stigmer#1255).
  */
 import { Code, ConnectError } from "@connectrpc/connect";
 import { create } from "@bufbuild/protobuf";
@@ -54,6 +62,7 @@ import type { IdentityAccount } from "@stigmer/protos/ai/stigmer/iam/identityacc
 import { IdentityAccountProvisioningMode } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/enum_pb";
 import { IdentityAccountSpecSchema } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/spec_pb";
 import type { PlatformClient } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
+import { PlatformClientStatusSchema } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
 import type {
   MintUserTokenRequest,
   MintUserTokenResponse,
@@ -63,6 +72,7 @@ import { IamRole } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
 
 import type { Logger } from "../../boot/logger.js";
 import type { CallerIdentity } from "../../extensions/identity.js";
+import { recordCredentialUse } from "../../identity/credential-use.js";
 import { internalError } from "../../pipeline/errors.js";
 import { serverActingFor } from "../../pipeline/interceptors/auth.js";
 import { validator } from "../../pipeline/steps/validation.js";
@@ -164,6 +174,7 @@ export async function mintUserToken(
     user,
   );
 
+  const now = deps.now();
   const signed = signPlatformToken(
     keys,
     {
@@ -174,8 +185,9 @@ export async function mintUserToken(
       [USER_TOKEN_CLAIMS.org]: owningOrg,
       [USER_TOKEN_CLAIMS.platformClientId]: client.metadata?.id ?? "",
     },
-    { now: deps.now() },
+    { now },
   );
+  await recordClientUse(deps, client, now);
   return create(MintUserTokenResponseSchema, {
     accessToken: signed.token,
     tokenType: BEARER_TOKEN_TYPE,
@@ -223,6 +235,27 @@ async function authenticateClient(
   return client;
 }
 
+/** Stamps the minting client's last use on its own row, through the port's atomic write. */
+function recordClientUse(
+  deps: PlatformClientMintDeps,
+  client: PlatformClient,
+  now: Date,
+): Promise<void> {
+  const id = client.metadata?.id ?? "";
+  return recordCredentialUse({
+    credential: "platform client",
+    id,
+    lastUsedAt: client.status?.lastUsedAt,
+    now,
+    logger: deps.logger,
+    write: (stamp) =>
+      deps.clients.modifyById(id, (live) => {
+        live.status ??= create(PlatformClientStatusSchema);
+        stamp(live.status);
+      }),
+  });
+}
+
 /** The account id for the user: the existing platform-client account, or one provisioned now. */
 async function resolveOrProvisionAccount(
   deps: PlatformClientMintDeps,

package/src/domain/platformclient/resource-store.ts

@@ -20,6 +20,8 @@
  * (org, slug) or client_id; `update` writes nothing for an unknown id; the
  * residual window between the read and the write is the platform-wide
  * CheckDuplicate-then-upsert window, not this adapter's to close.
+ * `modifyById` has no such window: it IS Store.updateResource, the generic
+ * store's own atomic read-modify-write, its not-found read as `undefined`.
  *
  * Store faults follow the ratified mapping: a typed ResourceNotFoundError
  * reads as `undefined`; anything else propagates — an outage must never
@@ -135,6 +137,22 @@ export function newResourcePlatformClientStore(
       await store.saveResource(KIND, id, PlatformClientSchema, client);
     },
 
+    async modifyById(id, modify): Promise<PlatformClient | undefined> {
+      try {
+        return await store.updateResource(
+          KIND,
+          id,
+          PlatformClientSchema,
+          modify,
+        );
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          return undefined;
+        }
+        throw error;
+      }
+    },
+
     async deleteById(id): Promise<void> {
       await store.deleteResource(KIND, id);
     },

package/src/domain/platformclient/store-contract.ts

@@ -242,6 +242,106 @@ const CASES: ReadonlyArray<PortContractDeclaration<PlatformClientStore>> = [
       );
     },
   ],
+  [
+    "modifyById persists what modify did, answers the persisted row, and the lookups follow it",
+    async ({ store }) => {
+      await store.save(ACME_DASHBOARD);
+      const answered = await store.modifyById(
+        "pcl_contract_acme_dashboard",
+        (client) => {
+          assert.ok(client.spec, "the saved client carries a spec");
+          client.spec.allowedOrigins = ["https://app.acme.example"];
+        },
+      );
+      const expected = platformClient({
+        id: "pcl_contract_acme_dashboard",
+        org: "acme",
+        slug: "dashboard",
+        clientId: "stgm_cid_contract_acme_dashboard",
+        allowedOrigins: ["https://app.acme.example"],
+      });
+      assertSameClient(answered, expected, "modifyById must answer the persisted row");
+      assertSameClient(
+        await store.findById("pcl_contract_acme_dashboard"),
+        expected,
+        "findById must answer the modified row",
+      );
+      assertSameClient(
+        await store.findByClientId("stgm_cid_contract_acme_dashboard"),
+        expected,
+        "findByClientId must answer the modified row",
+      );
+      assertSameClient(
+        await store.findByOrgAndSlug("acme", "dashboard"),
+        expected,
+        "findByOrgAndSlug must answer the modified row",
+      );
+    },
+  ],
+  [
+    "modifyById of an unknown id answers undefined and writes nothing",
+    async ({ store }) => {
+      let called = false;
+      const answered = await store.modifyById(
+        "pcl_contract_acme_dashboard",
+        () => {
+          called = true;
+        },
+      );
+      assert.equal(answered, undefined);
+      assert.equal(called, false, "modify must not run for a row that is not held");
+      assert.equal(
+        await store.findById("pcl_contract_acme_dashboard"),
+        undefined,
+        "modifyById must modify, never create",
+      );
+    },
+  ],
+  [
+    "a modify that throws writes nothing and rejects with its error",
+    async ({ store }) => {
+      await store.save(ACME_DASHBOARD);
+      const refusal = new Error("modify refused");
+      await assert.rejects(
+        store.modifyById("pcl_contract_acme_dashboard", (client) => {
+          assert.ok(client.spec, "the saved client carries a spec");
+          client.spec.allowedOrigins = ["https://half.written.example"];
+          throw refusal;
+        }),
+        (error: unknown) => error === refusal,
+        "the modify's own error must propagate",
+      );
+      assertSameClient(
+        await store.findById("pcl_contract_acme_dashboard"),
+        ACME_DASHBOARD,
+        "nothing a throwing modify did may persist",
+      );
+    },
+  ],
+  [
+    "concurrent modifyById calls on one row lose no write",
+    async ({ store }) => {
+      await store.save(ACME_DASHBOARD);
+      const origins = Array.from(
+        { length: 8 },
+        (_, i) => `https://writer-${i}.acme.example`,
+      );
+      await Promise.all(
+        origins.map((origin) =>
+          store.modifyById("pcl_contract_acme_dashboard", (client) => {
+            assert.ok(client.spec, "the saved client carries a spec");
+            client.spec.allowedOrigins.push(origin);
+          }),
+        ),
+      );
+      const stored = await store.findById("pcl_contract_acme_dashboard");
+      assert.deepEqual(
+        [...(stored?.spec?.allowedOrigins ?? [])].sort(),
+        [...origins].sort(),
+        "every concurrent modify must see the one before it: a read-then-write driver loses edits here",
+      );
+    },
+  ],
   [
     "deleteById frees the id, the client_id and the slug; deleting an unknown id resolves",
     async ({ store }) => {

package/src/domain/platformclient/store.ts

@@ -13,6 +13,14 @@
  * duplicate check), by organization (listByOrg). A port carries nothing
  * only one edition calls.
  *
+ * One write is atomic: `modifyById`, the port's rendering of
+ * `Store.updateResource`, for the status the platform writes on its own
+ * (the mint's last-use stamp, identity/credential-use.ts). `update` stays
+ * a whole-row replace for the chains that load, edit and persist; a stamp
+ * written that way would race them and could restore a rotated secret. The
+ * driver supplies only the atomicity; what `modify` does stays the
+ * domain's, written once for every edition.
+ *
  * Contract every implementation must satisfy — proven by the port-contract
  * kit (store-contract.ts, exported), which the OSS adapter's test iterates
  * on both drivers and a composition's driver test iterates too:
@@ -21,6 +29,10 @@
  *     overwrite;
  *   - `update` replaces by id and never creates: an unknown id writes
  *     nothing;
+ *   - `modifyById` reads the row, applies `modify` and persists the result
+ *     in one atomic step, so no concurrent write is lost; it answers the
+ *     persisted row, an unknown id answers `undefined` and writes nothing,
+ *     and a `modify` that throws writes nothing and rejects with its error;
  *   - `deleteById` of an unknown id resolves;
  *   - `findByOrg` answers every client of the organization and no other,
  *     in no promised order (the chain sorts);
@@ -49,6 +61,17 @@ export interface PlatformClientStore {
   save(client: PlatformClient): Promise<void>;
   /** Full-row replace by id; an unknown id writes nothing. */
   update(client: PlatformClient): Promise<void>;
+  /**
+   * Atomic read-modify-write by id: `modify` mutates the stored client in
+   * place and the result is persisted, or nothing is. `modify` MUST be
+   * synchronous (Store.updateResource's rule: a driver may hold a write
+   * transaction or a row lock while it runs). Answers the persisted client;
+   * an unknown id answers `undefined`.
+   */
+  modifyById(
+    id: string,
+    modify: (client: PlatformClient) => void,
+  ): Promise<PlatformClient | undefined>;
   /** Removes the row; no error when it does not exist. */
   deleteById(id: string): Promise<void>;
   findById(id: string): Promise<PlatformClient | undefined>;

package/src/extensions/__tests__/extension-composition.test.ts

@@ -736,9 +736,10 @@ describe("extension composition (O5 driver substitution)", () => {
 /**
  * The O4 gate-slot + status-hook arms: an extension gate spliced into a
  * declared slot refuses with its own ConnectError code and copy — before
- * the side effect on the pre-side-effect slot (nothing persisted), after
- * it on the post-persist slot (the row survives the failed request, the
- * inherited Java semantics — O4 verification V1); the status observers
+ * the side effect on a pre-side-effect slot (nothing persisted: the
+ * session and organization chains), after it on the post-persist slot
+ * (the row survives the failed request, the inherited Java semantics — O4
+ * verification V1); the status observers
  * see the terminal updateStatus transition exactly once (the Q4
  * phase-change rule) and the response decorator contributes the control
  * signal on the shared reply schema.
@@ -746,6 +747,7 @@ describe("extension composition (O5 driver substitution)", () => {
 describe("extension composition (O4 gate slots + status hooks)", () => {
   const REFUSED_SESSION = "o4-refused-session";
   const REFUSED_ORG_SLUG = "o4refusedorg";
+  const PRE_REFUSED_ORG_SLUG = "prerefusedorg";
   let server: ComposedServer;
   let dir: string;
   let portTransport: Transport;
@@ -777,11 +779,25 @@ describe("extension composition (O4 gate slots + status hooks)", () => {
     },
   };
 
+  const orgPreSideEffectGate: PipelineStep<DescMessage> = {
+    name: "FakeOrgPreSideEffectGate",
+    execute: (ctx) => {
+      const org = ctx.newState as { metadata?: { slug?: string } };
+      if (org.metadata?.slug === PRE_REFUSED_ORG_SLUG) {
+        throw new ConnectError(
+          "fake organization limit reached",
+          Code.FailedPrecondition,
+        );
+      }
+    },
+  };
+
   const gateExtension: ServerExtension = {
     name: "fake-gates-and-hooks",
     gateSteps: new Map<GateSlotName, ReadonlyArray<PipelineStep<DescMessage>>>([
       ["session-create:pre-side-effect-gate", [sessionGate]],
       ["org-create:post-persist", [orgPostPersistGate]],
+      ["org-create:pre-side-effect-gate", [orgPreSideEffectGate]],
     ]),
     statusTransitionHooks: {
       observers: [
@@ -892,6 +908,36 @@ describe("extension composition (O4 gate slots + status hooks)", () => {
     expect(org.metadata?.slug).toBe(REFUSED_ORG_SLUG);
   });
 
+  it("a pre-side-effect gate refusal aborts organization create with no row written", async () => {
+    const command = createClient(OrganizationCommandController, portTransport);
+    const query = createClient(OrganizationQueryController, portTransport);
+
+    let refused: ConnectError | undefined;
+    try {
+      await command.create(
+        create(OrganizationSchema, {
+          apiVersion: "tenancy.stigmer.ai/v1",
+          kind: "Organization",
+          metadata: { name: "Pre Refused Org", slug: PRE_REFUSED_ORG_SLUG },
+        }),
+      );
+    } catch (error) {
+      refused = ConnectError.from(error);
+    }
+    expect(refused?.code).toBe(Code.FailedPrecondition);
+    expect(refused?.rawMessage).toBe("fake organization limit reached");
+
+    // The slot sits BEFORE Persist: the refused organization was never
+    // written, which is the whole reason the slot exists.
+    let getError: ConnectError | undefined;
+    try {
+      await query.get({ value: PRE_REFUSED_ORG_SLUG });
+    } catch (error) {
+      getError = ConnectError.from(error);
+    }
+    expect(getError?.code).toBe(Code.NotFound);
+  });
+
   it("observers see the terminal updateStatus transition once and the decorator contributes the signal", async () => {
     const executionId = "aexec_o4_hooks";
     await server.store.saveResource(

package/src/extensions/__tests__/registry.test.ts

@@ -488,6 +488,9 @@ describe("resolveExtensions — loud-fail throws (DD-006 §2b)", () => {
       // personal-organization ensure and backfill ride it).
       "identity-account-provision:post-persist",
       "org-create:post-persist",
+      // The ninth: the organization create chain before Persist, where a
+      // limit on which organizations may exist refuses with nothing written.
+      "org-create:pre-side-effect-gate",
       "sandbox-acquisition:gate",
       "session-create:pre-side-effect-gate",
     ]);