@stigmer/server 3.38.2 → 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/domain/workflow/registry/data/model-registry.json

@@ -963,7 +963,8 @@
       "vision" : true,
       "streaming" : true,
       "thinking" : false,
-      "adaptiveThinking" : true
+      "adaptiveThinking" : true,
+      "thinkingRequired" : true
     }
   }, {
     "id" : "claude-haiku-4.5",
@@ -995,8 +996,9 @@
       "toolUse" : true,
       "vision" : true,
       "streaming" : true,
-      "thinking" : false,
-      "adaptiveThinking" : false
+      "thinking" : true,
+      "adaptiveThinking" : false,
+      "thinkingRequired" : false
     }
   }, {
     "id" : "claude-opus-4.5",
@@ -1017,7 +1019,7 @@
       "effectiveAt" : "2026-05-03T00:00:00Z"
     },
     "contextWindowTokens" : 200000,
-    "maxOutputTokens" : 65536,
+    "maxOutputTokens" : 64000,
     "tokenCounterMethod" : "anthropic_native",
     "summarization" : {
       "triggerThreshold" : 180000,
@@ -1029,7 +1031,8 @@
       "vision" : true,
       "streaming" : true,
       "thinking" : true,
-      "adaptiveThinking" : false
+      "adaptiveThinking" : false,
+      "thinkingRequired" : false
     }
   }, {
     "id" : "claude-opus-4.6",
@@ -1050,7 +1053,7 @@
       "effectiveAt" : "2026-05-03T00:00:00Z"
     },
     "contextWindowTokens" : 200000,
-    "maxOutputTokens" : 131072,
+    "maxOutputTokens" : 128000,
     "tokenCounterMethod" : "anthropic_native",
     "summarization" : {
       "triggerThreshold" : 180000,
@@ -1062,7 +1065,8 @@
       "vision" : true,
       "streaming" : true,
       "thinking" : false,
-      "adaptiveThinking" : true
+      "adaptiveThinking" : true,
+      "thinkingRequired" : false
     }
   }, {
     "id" : "claude-opus-4.7",
@@ -1096,7 +1100,8 @@
       "vision" : true,
       "streaming" : true,
       "thinking" : false,
-      "adaptiveThinking" : true
+      "adaptiveThinking" : true,
+      "thinkingRequired" : false
     }
   }, {
     "id" : "claude-opus-4.8",
@@ -1130,7 +1135,8 @@
       "vision" : true,
       "streaming" : true,
       "thinking" : false,
-      "adaptiveThinking" : true
+      "adaptiveThinking" : true,
+      "thinkingRequired" : false
     }
   }, {
     "id" : "claude-sonnet-4.5",
@@ -1151,7 +1157,7 @@
       "effectiveAt" : "2026-05-03T00:00:00Z"
     },
     "contextWindowTokens" : 200000,
-    "maxOutputTokens" : 65536,
+    "maxOutputTokens" : 64000,
     "tokenCounterMethod" : "anthropic_native",
     "summarization" : {
       "triggerThreshold" : 180000,
@@ -1163,7 +1169,8 @@
       "vision" : true,
       "streaming" : true,
       "thinking" : true,
-      "adaptiveThinking" : false
+      "adaptiveThinking" : false,
+      "thinkingRequired" : false
     }
   }, {
     "id" : "claude-sonnet-4.6",
@@ -1195,8 +1202,9 @@
       "toolUse" : true,
       "vision" : true,
       "streaming" : true,
-      "thinking" : true,
-      "adaptiveThinking" : false
+      "thinking" : false,
+      "adaptiveThinking" : true,
+      "thinkingRequired" : false
     }
   }, {
     "id" : "claude-sonnet-5",
@@ -1230,7 +1238,8 @@
       "vision" : true,
       "streaming" : true,
       "thinking" : false,
-      "adaptiveThinking" : true
+      "adaptiveThinking" : true,
+      "thinkingRequired" : false
     }
   } ]
 }

package/src/domain/workflow/registry/model-registry-store.ts

@@ -63,6 +63,19 @@ export const FAST_VARIANT_KEY = "fast";
  */
 export const THINKING_CAPABILITY_KEY = "thinking";
 
+/**
+ * The registry capability key of adaptive thinking, the second form that
+ * makes THINKING_MODE_ENABLED selectable (stigmer/stigmer#1280).
+ */
+export const ADAPTIVE_THINKING_CAPABILITY_KEY = "adaptiveThinking";
+
+/**
+ * The registry capability key naming a model that always thinks and refuses
+ * a request to turn thinking off: an explicit THINKING_MODE_DISABLED is
+ * refused for it at create.
+ */
+export const THINKING_REQUIRED_CAPABILITY_KEY = "thinkingRequired";
+
 export interface ModelRegistryStoreOptions {
   /** Bundled build-time snapshot; MUST pass the sanity gate at boot. */
   bundledDocument: string;
@@ -202,9 +215,9 @@ export class ModelRegistryStore implements ModelCatalogProvider {
    * "thinking") true under the given harness. Capability flags are
    * harness-scoped facts (they describe what works through that serving
    * path), so there is no any-harness form: THINKING_MODE_ENABLED validates
-   * against the cursor harness specifically — the only harness with a
-   * thinking translation in v1 (oss#772) — and native entries declaring the
-   * same capability stay unselectable until a native wire mapping exists.
+   * against the entry of the harness the execution runs on (oss#772,
+   * stigmer/stigmer#1280), because an id with an entry on both harnesses
+   * can declare different capabilities on each.
    */
   hasCapabilityForHarness(
     harness: string,

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,13 +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/artifact/controller.ts", 1],
-  ["domain/environment/controller.ts", 1],
-  ["domain/environment/steps.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: /,
+    );
+  });
+});