@stigmer/server 3.15.2 → 3.15.3-dev.20260914121148

package/src/pipeline/steps/__tests__/authorize.test.ts

@@ -4,9 +4,11 @@
  * annotation's byte-pinned error_msg; unavailable → INTERNAL, never a
  * softened denial), the skip arms (internal caller class, is_public,
  * is_skip_authorization, no-config methods), check-target resolution
- * (field_path, static resource_id, absent field = empty id — never a
- * throw), and the mid-chain resolved-id pattern the traced ListVersions
- * handlers port onto.
+ * (field_path, static resource_id, absent field = empty id, a string
+ * resource_kind_path resolved by enum name with an unknown name = the
+ * unknown kind — never a throw), the direct-handler override in both its
+ * shapes (a server-side id; a server-side kind AND id), and the mid-chain
+ * resolved-id pattern the traced ListVersions handlers port onto.
  */
 import { describe, expect, it } from "vitest";
 import { create } from "@bufbuild/protobuf";
@@ -17,6 +19,7 @@ import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb"
 import { AgentExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/command_pb";
 import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { IamPolicyCommandController } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/command_pb";
+import { IamPolicyQueryController } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/query_pb";
 import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
 import { PlatformQueryController } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
@@ -37,9 +40,7 @@ import {
 } from "../authorize.js";
 
 /** Awaits the rejection and returns it as a ConnectError. */
-async function captureError(
-  run: () => Promise<void>,
-): Promise<ConnectError> {
+async function captureError(run: () => Promise<void>): Promise<ConnectError> {
   try {
     await run();
   } catch (error) {
@@ -290,6 +291,75 @@ describe("check-target resolution (never a throw — byte-identity)", () => {
       },
     ]);
   });
+
+  // 20260913.01 (Q-OR-2): the IamPolicy RPCs name their target inside the
+  // request as a STRING kind (`ApiResourceRef.kind`, "organization"), so
+  // `resource_kind_path` resolves a string through the kind enum's names.
+  // The option had no user before this entry; a numeric field still works.
+  it("resource_kind_path over a string field resolves through the kind enum's names (IamPolicy create)", async () => {
+    const { authorizer, checks } = fakeAuthorizer({ kind: "allow" });
+    const method = IamPolicyCommandController.method.create;
+    const step = newAuthorizeStep(method, authorizer);
+    const ctx = new RequestContext(
+      method.input,
+      create(method.input, {
+        principal: { kind: "identity_account", id: "ida_alice" },
+        relation: "member",
+        resource: { kind: "organization", id: "acme" },
+      }),
+      testCallerIdentity(),
+    );
+    await step.execute(ctx);
+    expect(checks).toEqual([
+      {
+        permission: IamPermission.can_grant_access,
+        resourceKind: ApiResourceKind.organization,
+        resourceId: "acme",
+      },
+    ]);
+  });
+
+  it("an unknown kind name resolves to the unknown kind — never a throw; the Authorizer owns the decision", async () => {
+    const { authorizer, checks } = fakeAuthorizer({ kind: "allow" });
+    const method = IamPolicyCommandController.method.create;
+    const step = newAuthorizeStep(method, authorizer);
+    const ctx = new RequestContext(
+      method.input,
+      create(method.input, {
+        principal: { kind: "identity_account", id: "ida_alice" },
+        relation: "member",
+        resource: { kind: "spaceship", id: "acme" },
+      }),
+      testCallerIdentity(),
+    );
+    await expect(step.execute(ctx)).resolves.toBeUndefined();
+    expect(checks[0]?.resourceKind).toBe(
+      ApiResourceKind.api_resource_kind_unknown,
+    );
+    expect(checks[0]?.resourceId).toBe("acme");
+  });
+
+  it("revokeOrgAccess names the organization statically and its id by field_path (organization_id)", async () => {
+    const { authorizer, checks } = fakeAuthorizer({ kind: "allow" });
+    const method = IamPolicyCommandController.method.revokeOrgAccess;
+    const step = newAuthorizeStep(method, authorizer);
+    const ctx = new RequestContext(
+      method.input,
+      create(method.input, {
+        identityAccountId: "ida_alice",
+        organizationId: "acme",
+      }),
+      testCallerIdentity(),
+    );
+    await step.execute(ctx);
+    expect(checks).toEqual([
+      {
+        permission: IamPermission.can_grant_access,
+        resourceKind: ApiResourceKind.organization,
+        resourceId: "acme",
+      },
+    ]);
+  });
 });
 
 describe("authorizeDirect (the direct-handler arm, C2 Stage 4)", () => {
@@ -348,6 +418,49 @@ describe("authorizeDirect (the direct-handler arm, C2 Stage 4)", () => {
     ]);
   });
 
+  // 20260913.01 (Q-OR-2): the IamPolicy `get(IamPolicyId)` lane. Its
+  // annotation names a permission and NO kind, because the target is the
+  // loaded row's resource — kind AND id are server-side state. The
+  // override carries both; the annotation still owns the permission and
+  // the copy.
+  it("the target override may carry the resource KIND too — the IamPolicy get lane", async () => {
+    const { authorizer, checks } = fakeAuthorizer({ kind: "allow" });
+    const method = IamPolicyQueryController.method.get;
+    await authorizeDirect(
+      method,
+      authorizer,
+      testCallerIdentity(),
+      create(method.input, { value: "iamp_01row" }),
+      { resourceKind: ApiResourceKind.organization, resourceId: "acme" },
+    );
+    expect(checks).toEqual([
+      {
+        permission: IamPermission.can_view_access,
+        resourceKind: ApiResourceKind.organization,
+        resourceId: "acme",
+      },
+    ]);
+  });
+
+  it("an override with the id alone leaves the annotation's kind in place — the completeOAuthConnect lane is unchanged", async () => {
+    const { authorizer, checks } = fakeAuthorizer({ kind: "allow" });
+    const method = IamPolicyQueryController.method.get;
+    // A kind-less annotation plus an id-only override: the kind stays
+    // unknown, exactly what the annotation says. The lane that needs a
+    // kind must say so; nothing is inferred.
+    await authorizeDirect(
+      method,
+      authorizer,
+      testCallerIdentity(),
+      create(method.input, { value: "iamp_01row" }),
+      { resourceId: "acme" },
+    );
+    expect(checks[0]?.resourceKind).toBe(
+      ApiResourceKind.api_resource_kind_unknown,
+    );
+    expect(checks[0]?.resourceId).toBe("acme");
+  });
+
   it("the ruling-Q1 not-found arm maps identically from the direct entry", async () => {
     const { authorizer } = fakeAuthorizer({ kind: "not-found" });
     const error = await authorizeDirect(
@@ -438,18 +551,30 @@ describe("authorizeResolvedResource (the mid-chain resolved-id pattern, 20260830
       ),
     );
     expect(err.code).toBe(Code.PermissionDenied);
-    expect(err.rawMessage).toBe("unauthorized to view workflow version history");
+    expect(err.rawMessage).toBe(
+      "unauthorized to view workflow version history",
+    );
   });
 
   it("deny without lane copy falls back to the reason, then the shared fallback", async () => {
     const reasoned = fakeAuthorizer({ kind: "deny", reason: "because" });
     const err1 = await captureError(() =>
-      authorizeResolvedResource(reasoned.authorizer, testCallerIdentity(), check, ""),
+      authorizeResolvedResource(
+        reasoned.authorizer,
+        testCallerIdentity(),
+        check,
+        "",
+      ),
     );
     expect(err1.rawMessage).toBe("because");
     const bare = fakeAuthorizer({ kind: "deny", reason: "" });
     const err2 = await captureError(() =>
-      authorizeResolvedResource(bare.authorizer, testCallerIdentity(), check, ""),
+      authorizeResolvedResource(
+        bare.authorizer,
+        testCallerIdentity(),
+        check,
+        "",
+      ),
     );
     expect(err2.rawMessage).toBe("permission denied");
   });

package/src/pipeline/steps/__tests__/derived-id.test.ts

@@ -0,0 +1,49 @@
+/**
+ * Pins `derivedId`, the one encoder behind every id a kind derives from its
+ * natural key instead of minting (metadata.proto's `id` comment: a direct
+ * IdentityAccount from its subject, an IamPolicy from its triple; the
+ * Organization's slug needs no encoding). Lifted from the identity-account
+ * domain in 20260913.01 slice 2 so the second derived id did not carry a
+ * second copy of the grammar.
+ *
+ * The vectors here are the two domains' golden vectors restated through
+ * the shared function: `accountIdFor` and `policyIdFor` must equal
+ * `derivedId(prefix, text)` over their canonical text, and those domain
+ * tests pin the wire-adjacent constants. A change to the encoding
+ * re-addresses every derived row open source ever wrote.
+ */
+import { describe, expect, it } from "vitest";
+
+import { derivedId } from "../defaults.js";
+
+const CROCKFORD_26 = /^[0-9abcdefghjkmnpqrstvwxyz]{26}$/;
+
+describe("derivedId — prefix, underscore, the top 130 bits of sha256 as 26 Crockford chars", () => {
+  it("matches the identity-account golden vector", () => {
+    // accountIdFor("auth0|user123") as pinned in identityaccount/__tests__/constants.test.ts.
+    expect(derivedId("ida", "auth0|user123")).toBe(
+      "ida_wtr3jcf281yfk9xx61kj59fsme",
+    );
+  });
+
+  it("matches the IamPolicy golden vector over the canonical triple text", () => {
+    expect(
+      derivedId(
+        "iamp",
+        "identity_account:ida_wtr3jcf281yfk9xx61kj59fsme#@organization:acme#admin",
+      ),
+    ).toBe("iamp_vkbjb6nvqm77vtwnr2bj0x95f9");
+  });
+
+  it("has the minted id's shape whatever the prefix, so nothing downstream learns a second grammar", () => {
+    const id = derivedId("xyz", "anything");
+    expect(id.startsWith("xyz_")).toBe(true);
+    expect(id.slice("xyz_".length)).toMatch(CROCKFORD_26);
+  });
+
+  it("is a pure function of prefix and text: equal inputs, equal ids; a changed byte, a changed id", () => {
+    expect(derivedId("ida", "same")).toBe(derivedId("ida", "same"));
+    expect(derivedId("ida", "same")).not.toBe(derivedId("ida", "same "));
+    expect(derivedId("ida", "same")).not.toBe(derivedId("iamp", "same"));
+  });
+});

package/src/pipeline/steps/authorization-tuples.ts

@@ -78,7 +78,7 @@ import type { PipelineStep } from "../pipeline.js";
 import type { RequestContext } from "../request-context.js";
 import { EXISTING_RESOURCE_KEY } from "./load-existing.js";
 import type { HasMetadataShape } from "./shapes.js";
-import { metadataOf } from "./shapes.js";
+import { metadataOf, parentIdOf } from "./shapes.js";
 
 // ---------------------------------------------------------------------------
 // Visibility shape policy — the reconciler's level→shape mapping, ported
@@ -156,40 +156,19 @@ export function diffVisibilityShapes(
 }
 
 // ---------------------------------------------------------------------------
-// Parent-id resolution — the ParentIdExtractorRegistry port. Zero
-// hardcoded kind knowledge: the proto config names the spec field, this
-// module reads it structurally (protobuf-es spec messages are plain
-// objects whose properties are the camelCase proto field names).
+// Parent-id resolution — the ParentIdExtractorRegistry port. The spec-field
+// read itself is shapes.ts's `parentIdOf`, shared with the list read scope
+// (20260913.04 T04) so the id a tuple is written with and the id the scope
+// asks about are one read. This module adds the create-time rule: a
+// missing parent fails the request.
 // ---------------------------------------------------------------------------
 
-/** proto snake_case field name → the generated property name. */
-function camelCaseFieldName(specField: string): string {
-  return specField.replace(/_([a-z0-9])/g, (_, ch: string) => ch.toUpperCase());
-}
-
-/**
- * Extracts the parent id named by the config from the resource's spec.
- * Returns "" for every miss (no spec, no field, non-string value) — the
- * caller decides whether that is fatal, exactly as Java's registry
- * returns null and the service throws.
- */
-function extractParentId(resource: Message, specField: string): string {
-  // Structural access is the shapes.ts idiom: spec messages are plain
-  // objects; the property name is the camelCase form of the proto field.
-  const spec = (resource as unknown as { spec?: Record<string, unknown> }).spec;
-  if (spec === undefined) {
-    return "";
-  }
-  const value = spec[camelCaseFieldName(specField)];
-  return typeof value === "string" ? value : "";
-}
-
 function resolveParentLink(
   kind: ApiResourceKind,
   resource: Message,
   parentConfig: ParentRelationConfig,
 ): ResolvedParentLink {
-  const parentId = extractParentId(resource, parentConfig.specField);
+  const parentId = parentIdOf(resource, parentConfig.specField);
   if (parentId === "") {
     // Java: "Parent ID required for X but not found" → the request fails.
     throw internalError(

package/src/pipeline/steps/authorize.ts

@@ -31,9 +31,13 @@
  * Resolution never throws: an unresolvable `field_path` yields an empty
  * resource id and an unresolvable `resource_kind_path` yields the unknown
  * kind — the check still reaches the Authorizer, which owns the decision.
- * A thrown resolution would be a NEW wire behavior on requests that are
- * legal today (byte-identity forbids it); an implementation that wants to
- * refuse empty ids does so as a deny, visibly.
+ * A `resource_kind_path` may point at an `ApiResourceKind` field or at a
+ * string carrying a kind's enum member name (an `ApiResourceRef.kind`, the
+ * IamPolicy RPCs' spec-named target; 20260913.01 Q-OR-2); a string that is
+ * not exactly a member name is the unknown kind, which an enforcing
+ * authorizer denies. A thrown resolution would be a NEW wire behavior on
+ * requests that are legal today (byte-identity forbids it); an
+ * implementation that wants to refuse empty ids does so as a deny, visibly.
  *
  * `authorizeDirect` is the SAME evaluation exported for the direct
  * handlers — the config-annotated methods that deliberately run no
@@ -42,11 +46,16 @@
  * two entry shapes; a direct handler calls it after its own input
  * validation and before any load or side effect, mirroring the Java
  * edition's validate → authorize handler order (C2 Stage 4 ruling,
- * 20260827.10). The optional target override serves the one lane whose
- * true target is server-side state rather than caller input
- * (completeOAuthConnect authorizes the PENDING RECORD's server id — a
- * caller-supplied id would be a confused-deputy hole, the Java
- * McpServerCompleteOAuthConnectHandler discipline).
+ * 20260827.10). The optional target override serves the lanes whose true
+ * target is server-side state rather than caller input, in two shapes:
+ * a server-side ID under the annotation's static kind (completeOAuthConnect
+ * authorizes the PENDING RECORD's server id — a caller-supplied id would
+ * be a confused-deputy hole, the Java McpServerCompleteOAuthConnectHandler
+ * discipline; getByEmail/getByIdpId authorize the account they looked up),
+ * and a server-side kind AND id (the IamPolicy `get`, whose annotation
+ * names no kind because the target is the loaded row's resource). The
+ * annotation keeps owning the permission, the copy and the skip arms in
+ * both shapes; only the target is the handler's.
  */
 import { Code, ConnectError } from "@connectrpc/connect";
 import type { DescMethod, DescMessage, Message } from "@bufbuild/protobuf";
@@ -66,7 +75,7 @@ import type {
   AuthzDecision,
 } from "../../extensions/authorizer.js";
 import type { CallerIdentity } from "../../extensions/identity.js";
-import { getKindName } from "../apiresource-meta.js";
+import { getKindName, kindByEnumName } from "../apiresource-meta.js";
 import { internalError, notFoundError } from "../errors.js";
 import type { PipelineStep } from "../pipeline.js";
 import type { RequestContext } from "../request-context.js";
@@ -115,12 +124,16 @@ export function newAuthorizeStep<Desc extends DescMessage>(
 }
 
 /**
- * The one lane whose authorization target is server-side state rather
- * than a request field (see the module header). `resourceId` replaces the
- * annotation's `field_path`/`resource_id` resolution; everything else —
- * skip arms, kind, permission, copy — still comes from the annotation.
+ * The lanes whose authorization target is server-side state rather than a
+ * request field (see the module header). `resourceId` replaces the
+ * annotation's `field_path`/`resource_id` resolution; `resourceKind`, when
+ * given, replaces its `resource_kind`/`resource_kind_path` resolution — the
+ * lane whose annotation names no kind because the kind is inside the row
+ * it loaded. Everything else — skip arms, permission, copy — still comes
+ * from the annotation.
  */
 export interface AuthorizeTargetOverride {
+  readonly resourceKind?: ApiResourceKind;
   readonly resourceId: string;
 }
 
@@ -156,7 +169,8 @@ export async function authorizeDirect(
     identity,
     {
       permission: config.permission,
-      resourceKind: resolveResourceKind(input, config),
+      resourceKind:
+        override?.resourceKind ?? resolveResourceKind(input, config),
       resourceId: override?.resourceId ?? resolveResourceId(input, config),
     },
     config.errorMsg,
@@ -189,7 +203,7 @@ export async function authorizeResolvedResource(
   if (identity.callerClass === "internal") {
     return;
   }
-  const decision = await runAuthorizer(authorizer, identity, check);
+  const decision = await evaluateAuthorizer(authorizer, identity, check);
   switch (decision.kind) {
     case "allow":
       return;
@@ -234,9 +248,13 @@ export async function authorizeResolvedResource(
 /**
  * An Authorizer that THROWS is an evaluation failure by definition —
  * normalized into the unavailable arm so a buggy implementation can never
- * soften an outage into a denial by accident.
+ * soften an outage into a denial by accident. Exported for the one lane
+ * that needs the DECISION rather than the wire mapping: `checkMyPermission`
+ * answers a boolean (allow → true, deny and not-found → false) and maps
+ * only `unavailable` to the wire, through the same INTERNAL copy
+ * (20260913.01, Q-S5-3).
  */
-async function runAuthorizer(
+export async function evaluateAuthorizer(
   authorizer: Authorizer,
   identity: CallerIdentity,
   check: AuthzCheck,
@@ -251,7 +269,10 @@ async function runAuthorizer(
   }
 }
 
-/** Static kind, or the resource_kind_path read, or unknown — never a throw. */
+/**
+ * Static kind, or the resource_kind_path read — an enum field as its
+ * number, a string as an enum member name — or unknown. Never a throw.
+ */
 function resolveResourceKind(
   input: Message,
   config: RpcAuthorizationConfig,
@@ -260,9 +281,13 @@ function resolveResourceKind(
     return config.resourceKind;
   }
   const value = resolveDotPath(input, config.resourceKindPath);
-  return typeof value === "number"
-    ? (value as ApiResourceKind)
-    : ApiResourceKind.api_resource_kind_unknown;
+  if (typeof value === "number") {
+    return value as ApiResourceKind;
+  }
+  if (typeof value === "string") {
+    return kindByEnumName(value);
+  }
+  return ApiResourceKind.api_resource_kind_unknown;
 }
 
 /** Static resource_id, or the field_path read, or "" — never a throw. */

package/src/pipeline/steps/defaults.ts

@@ -14,7 +14,19 @@
  * setAuditFieldsForUpdate call site declares which slot it owns —
  * SpecAudit for definition changes (search recency, version "pushed at"),
  * StatusAudit for operational changes (Recents, lifecycle metadata).
+ *
+ * This module is also the one home of how an id is SPELLED. `generateId`
+ * mints `{prefix}_{ulid}`; `derivedId` is its sibling for the kinds
+ * metadata.proto names as deriving their id from a natural key instead
+ * (a direct IdentityAccount from its issuer subject, an IamPolicy from its
+ * triple): `{prefix}_` + the top 130 bits of sha256 over the key's
+ * canonical text as 26 lowercase Crockford-base32 characters. The two
+ * shapes are indistinguishable on the wire, so nothing downstream learns
+ * a second grammar, and the primary key becomes the one home of "one row
+ * per natural key" without a secondary index or a scan.
  */
+import { createHash } from "node:crypto";
+
 import { create, clone } from "@bufbuild/protobuf";
 import type { DescMessage, Message } from "@bufbuild/protobuf";
 import { reflect } from "@bufbuild/protobuf/reflect";
@@ -353,3 +365,33 @@ function setAuditSlotReflect(
 export function generateId(prefix: string): string {
   return `${prefix}_${ulid().toLowerCase()}`;
 }
+
+/** Crockford base32, lowercased — the alphabet every minted ULID id uses. */
+const CROCKFORD_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
+const DERIVED_ID_CHARS = 26;
+const DERIVED_ID_BITS = BigInt(DERIVED_ID_CHARS * 5);
+const SHA256_BITS = 256n;
+
+/**
+ * The derived id of a kind whose id is a function of its natural key
+ * (metadata.proto `id`): `{prefix}_` + the top 130 bits of
+ * sha256(canonicalText) as 26 lowercase Crockford-base32 characters. Pure
+ * and total; the CALLER owns what `canonicalText` may be (the domains
+ * refuse an empty subject or an ambiguous triple before hashing), and the
+ * domains' golden vectors are the wire-adjacent pin — a change here
+ * re-addresses every derived row open source ever wrote.
+ */
+export function derivedId(prefix: string, canonicalText: string): string {
+  const digest = createHash("sha256").update(canonicalText, "utf8").digest();
+  let bits = 0n;
+  for (const byte of digest) {
+    bits = (bits << 8n) | BigInt(byte);
+  }
+  let top = bits >> (SHA256_BITS - DERIVED_ID_BITS);
+  let encoded = "";
+  for (let i = 0; i < DERIVED_ID_CHARS; i++) {
+    encoded = CROCKFORD_ALPHABET[Number(top & 31n)] + encoded;
+    top >>= 5n;
+  }
+  return `${prefix}_${encoded}`;
+}

package/src/pipeline/steps/shapes.ts

@@ -39,6 +39,37 @@ export function idValueOf(msg: Message): string {
   return typeof value === "string" ? value : "";
 }
 
+/** proto snake_case field name → the generated property name. */
+function camelCaseFieldName(specField: string): string {
+  return specField.replace(/_([a-z0-9])/g, (_, ch: string) => ch.toUpperCase());
+}
+
+/**
+ * The parent id a `kind_meta` ParentRelationConfig names by `spec_field`,
+ * read from the resource's spec — the ParentIdExtractorRegistry port, with
+ * zero hardcoded kind knowledge: the proto config names the field, this
+ * reads it structurally (spec messages are plain objects whose properties
+ * are the camelCase proto field names). Returns "" for every miss (no
+ * spec, no field, non-string value); the caller decides whether that is
+ * fatal — the tuple lifecycle throws at create (Java's registry returned
+ * null and the service threw), the list scope carries no parent.
+ *
+ * ONE reader for both: the id the authorization tuple was written with is
+ * the id the list scope later asks the authorization backend about, so
+ * the two cannot drift (20260913.04 T04). Takes `object` rather than
+ * `Message` because the list lanes hand the scope structurally-typed rows
+ * and their unit suite hands it plain objects — the same posture
+ * `metadataOf` takes behind its cast.
+ */
+export function parentIdOf(resource: object, specField: string): string {
+  const spec = (resource as { spec?: Record<string, unknown> }).spec;
+  if (spec === undefined) {
+    return "";
+  }
+  const value = spec[camelCaseFieldName(specField)];
+  return typeof value === "string" ? value : "";
+}
+
 /** A message-typed field, statically narrowed so get()/set() type-check. */
 export type MessageDescField = Extract<DescField, { fieldKind: "message" }>;
 

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

@@ -0,0 +1,123 @@
+/**
+ * Pins the port-contract runner (../port-contract.ts), the scaffolding every
+ * domain store port's kit is built on (identity-account since 20260911.11;
+ * IamPolicy since 20260913.01 slice 2, when the scaffolding was lifted out
+ * of the first kit so the second did not copy it):
+ *
+ *   - every case makes a FRESH fixture, runs its body over it, and cleans
+ *     up — in that order, once each;
+ *   - a failing body is the failure reported: a cleanup that fails after
+ *     a failed body must not replace the assertion that matters with a
+ *     teardown detail;
+ *   - a cleanup that fails after a PASSING body is a real failure and
+ *     propagates;
+ *   - the case list keeps the declared names in the declared order, so a
+ *     consumer's pinned name list is a faithful diff of the contract.
+ */
+import { describe, expect, it } from "vitest";
+
+import { portContractCases } from "../port-contract.js";
+import type { PortContractFixture } from "../port-contract.js";
+
+interface Probe {
+  readonly label: string;
+}
+
+type ProbeFixture = PortContractFixture<Probe>;
+
+function fixtureFactory(
+  log: string[],
+  options: { readonly failCleanup?: boolean } = {},
+): () => Promise<ProbeFixture> {
+  let made = 0;
+  return async () => {
+    made += 1;
+    const label = `fixture-${made}`;
+    log.push(`make ${label}`);
+    return {
+      store: { label },
+      disconnect: async () => {
+        log.push(`disconnect ${label}`);
+      },
+      cleanup: async () => {
+        log.push(`cleanup ${label}`);
+        if (options.failCleanup === true) {
+          throw new Error(`cleanup of ${label} failed`);
+        }
+      },
+    };
+  };
+}
+
+describe("portContractCases", () => {
+  it("keeps the declared names in the declared order", () => {
+    const cases = portContractCases<Probe>(
+      [
+        ["first line", async () => {}],
+        ["second line", async () => {}],
+      ],
+      fixtureFactory([]),
+    );
+    expect(cases.map((contractCase) => contractCase.name)).toEqual([
+      "first line",
+      "second line",
+    ]);
+  });
+
+  it("makes a fresh fixture per case, runs the body over it, then cleans up — once each", async () => {
+    const log: string[] = [];
+    const cases = portContractCases<Probe>(
+      [
+        [
+          "a",
+          async ({ store }) => {
+            log.push(`body over ${store.label}`);
+          },
+        ],
+        [
+          "b",
+          async ({ store }) => {
+            log.push(`body over ${store.label}`);
+          },
+        ],
+      ],
+      fixtureFactory(log),
+    );
+    for (const contractCase of cases) {
+      await contractCase.run();
+    }
+    expect(log).toEqual([
+      "make fixture-1",
+      "body over fixture-1",
+      "cleanup fixture-1",
+      "make fixture-2",
+      "body over fixture-2",
+      "cleanup fixture-2",
+    ]);
+  });
+
+  it("reports the body's failure, not the cleanup's, when both fail", async () => {
+    const log: string[] = [];
+    const [only] = portContractCases<Probe>(
+      [
+        [
+          "assertion loses to nothing",
+          async () => {
+            throw new Error("the assertion that matters");
+          },
+        ],
+      ],
+      fixtureFactory(log, { failCleanup: true }),
+    );
+    await expect(only?.run()).rejects.toThrow("the assertion that matters");
+    expect(log).toEqual(["make fixture-1", "cleanup fixture-1"]);
+  });
+
+  it("a cleanup failure after a passing body is a real failure", async () => {
+    const [only] = portContractCases<Probe>(
+      [["passes", async () => {}]],
+      fixtureFactory([], { failCleanup: true }),
+    );
+    await expect(only?.run()).rejects.toThrow("cleanup of fixture-1 failed");
+  });
+});