@stigmer/server 3.27.1 → 3.28.0

package/src/authorization/__tests__/store-test-kit.ts

@@ -0,0 +1,246 @@
+/**
+ * The OpenFGA store-test kit: runs a `.fga.yaml` document (the format
+ * `fga model test` reads: fixture tuples, then named tests with `check`
+ * and `list_objects` assertions) against the built-in evaluator. The
+ * documents are the model's own suites (fga/tests/), which the real
+ * engine runs too (`make test-authorization-model`), so every assertion
+ * answered here is answered by OpenFGA over the same compiled model: the
+ * proof that the evaluator and the engine mean one thing.
+ *
+ * One case per named test. A case asserts every `check`, relation by
+ * relation, and every `list_objects`, and fails on the first disagreement
+ * with a message in the document's own words. Nothing is skipped: the
+ * built-in model declares every type a document can name.
+ *
+ * `list_objects` is evaluated exactly. An object holds a relation only
+ * through a tuple on that object: a direct tuple, a tupleset link, or a
+ * computed relation that bottoms out in one of those, which are the only
+ * forms the model uses (the reader refuses wildcards, the one form that
+ * would grant without a tuple on the object). So the objects of the asked
+ * type that the document's tuples name are the complete candidate set;
+ * each is checked, and the kept ones are compared with the expectation as
+ * a set, the way OpenFGA answers it (in no order). This is also how the
+ * server's list scope works: rows first, then checks.
+ *
+ * The parser is strict on purpose (strict-json.ts): an unknown key
+ * anywhere is a thrown fault, so a change to the format upstream is loud
+ * here rather than half-run. The model declares no condition, so a
+ * tuple's `condition` and a check's `context` are among the keys refused.
+ */
+import assert from "node:assert/strict";
+
+import { checkRelation } from "../evaluator.js";
+import type { Model } from "../model/index.js";
+import { list, optionalList, record, text } from "../strict-json.js";
+import type { Person, Tuple } from "../tuples.js";
+import {
+  ACCOUNT_TYPE,
+  formatObjectRef,
+  newInMemoryTupleSource,
+  parseObjectRef,
+  parseSubject,
+} from "../tuples.js";
+
+// ---------------------------------------------------------------------------
+// The document, typed exactly as the suites use the format.
+// ---------------------------------------------------------------------------
+
+export interface StoreTestTuple {
+  readonly user: string;
+  readonly relation: string;
+  readonly object: string;
+}
+
+export interface StoreTestCheck {
+  readonly user: string;
+  readonly object: string;
+  readonly assertions: Readonly<Record<string, boolean>>;
+}
+
+export interface StoreTestListObjects {
+  readonly user: string;
+  readonly type: string;
+  readonly assertions: Readonly<Record<string, ReadonlyArray<string>>>;
+}
+
+export interface StoreTest {
+  readonly name: string;
+  readonly check: ReadonlyArray<StoreTestCheck>;
+  readonly list_objects: ReadonlyArray<StoreTestListObjects>;
+}
+
+export interface StoreTestDocument {
+  readonly name: string;
+  readonly tuples: ReadonlyArray<StoreTestTuple>;
+  readonly tests: ReadonlyArray<StoreTest>;
+}
+
+/**
+ * Parses a loaded YAML value into a document, refusing anything the
+ * format the suites use does not carry (`sourceName` names the file in
+ * every message).
+ */
+export function parseStoreTestDocument(
+  value: unknown,
+  sourceName: string,
+): StoreTestDocument {
+  const root = record(value, sourceName, [
+    "name",
+    "model_file",
+    "tuples",
+    "tests",
+  ]);
+  return {
+    name: text(root["name"], `${sourceName}: name`),
+    tuples: list(root["tuples"], `${sourceName}: tuples`).map((entry, index) =>
+      parseTuple(entry, `${sourceName}: tuples[${index}]`),
+    ),
+    tests: list(root["tests"], `${sourceName}: tests`).map((entry, index) =>
+      parseTest(entry, `${sourceName}: tests[${index}]`),
+    ),
+  };
+}
+
+function parseTuple(value: unknown, where: string): StoreTestTuple {
+  const entry = record(value, where, ["user", "relation", "object"]);
+  return {
+    user: text(entry["user"], `${where}.user`),
+    relation: text(entry["relation"], `${where}.relation`),
+    object: text(entry["object"], `${where}.object`),
+  };
+}
+
+function parseTest(value: unknown, where: string): StoreTest {
+  const entry = record(value, where, ["name", "check", "list_objects"]);
+  return {
+    name: text(entry["name"], `${where}.name`),
+    check: optionalList(entry["check"], `${where}.check`).map((item, index) =>
+      parseCheck(item, `${where}.check[${index}]`),
+    ),
+    list_objects: optionalList(
+      entry["list_objects"],
+      `${where}.list_objects`,
+    ).map((item, index) =>
+      parseListObjects(item, `${where}.list_objects[${index}]`),
+    ),
+  };
+}
+
+function parseCheck(value: unknown, where: string): StoreTestCheck {
+  const entry = record(value, where, ["user", "object", "assertions"]);
+  const assertions = record(entry["assertions"], `${where}.assertions`);
+  const parsed: Record<string, boolean> = {};
+  for (const [relation, expected] of Object.entries(assertions)) {
+    if (typeof expected !== "boolean") {
+      throw new Error(`${where}.assertions.${relation}: expected a boolean`);
+    }
+    parsed[relation] = expected;
+  }
+  return {
+    user: text(entry["user"], `${where}.user`),
+    object: text(entry["object"], `${where}.object`),
+    assertions: parsed,
+  };
+}
+
+function parseListObjects(value: unknown, where: string): StoreTestListObjects {
+  const entry = record(value, where, ["user", "type", "assertions"]);
+  const assertions = record(entry["assertions"], `${where}.assertions`);
+  const parsed: Record<string, ReadonlyArray<string>> = {};
+  for (const [relation, expected] of Object.entries(assertions)) {
+    parsed[relation] = list(expected, `${where}.assertions.${relation}`).map(
+      (item, index) => text(item, `${where}.assertions.${relation}[${index}]`),
+    );
+  }
+  return {
+    user: text(entry["user"], `${where}.user`),
+    type: text(entry["type"], `${where}.type`),
+    assertions: parsed,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The cases.
+// ---------------------------------------------------------------------------
+
+export interface StoreTestCase {
+  /** `<document> :: <test name>`: the framework prints it as the test name. */
+  readonly name: string;
+  run(): Promise<void>;
+}
+
+/** The document's tests as runnable cases over `model`. */
+export function storeTestCases(
+  document: StoreTestDocument,
+  model: Model,
+): ReadonlyArray<StoreTestCase> {
+  const tuples = document.tuples.map(tupleOf);
+  const source = newInMemoryTupleSource(tuples);
+  const deps = { model, source };
+
+  return document.tests.map((test) => ({
+    name: `${document.name} :: ${test.name}`,
+    async run() {
+      for (const item of test.check) {
+        const object = parseObjectRef(item.object);
+        const person = personOf(item.user);
+        for (const [relation, expected] of Object.entries(item.assertions)) {
+          const actual = await checkRelation(deps, object, relation, person);
+          assert.equal(
+            actual,
+            expected,
+            `${document.name} :: ${test.name}: ${item.user} ${relation} ${item.object} expected ${String(expected)}, got ${String(actual)}`,
+          );
+        }
+      }
+      for (const item of test.list_objects) {
+        const person = personOf(item.user);
+        const candidates = objectsOfType(tuples, item.type);
+        for (const [relation, expected] of Object.entries(item.assertions)) {
+          const kept: string[] = [];
+          for (const candidate of candidates) {
+            if (await checkRelation(deps, parseObjectRef(candidate), relation, person)) {
+              kept.push(candidate);
+            }
+          }
+          assert.deepEqual(
+            kept.sort(),
+            [...expected].sort(),
+            `${document.name} :: ${test.name}: ${item.user} ${relation} objects of type ${item.type}`,
+          );
+        }
+      }
+    },
+  }));
+}
+
+/** Every object of `type` a tuple is written on, each once, in first-seen order: the complete candidate set (the module header). */
+export function objectsOfType(
+  tuples: ReadonlyArray<Tuple>,
+  type: string,
+): ReadonlyArray<string> {
+  const seen = new Set<string>();
+  for (const tuple of tuples) {
+    if (tuple.object.type === type) {
+      seen.add(formatObjectRef(tuple.object));
+    }
+  }
+  return [...seen];
+}
+
+function tupleOf(entry: StoreTestTuple): Tuple {
+  return {
+    object: parseObjectRef(entry.object),
+    relation: entry.relation,
+    subject: parseSubject(entry.user),
+  };
+}
+
+/** The document's users are plain accounts; a user of another type is a format the kit does not run. */
+function personOf(user: string): Person {
+  const object = parseObjectRef(user);
+  if (object.type !== ACCOUNT_TYPE || object.id === "*") {
+    throw new Error(`store test users are accounts; got '${user}'`);
+  }
+  return { accountId: object.id, aliases: new Set([object.id]) };
+}

package/src/authorization/__tests__/store-tests.test.ts

@@ -1,24 +1,20 @@
 /**
- * Runs the cloud's own OpenFGA store tests against the built-in
- * evaluator: the documents under fixtures/fga/ are pinned copies of
- * stigmer-cloud's `fga/tests/*.fga.yaml` (each header names its source
- * and commit), written by the model's authors and run against real
- * OpenFGA in the cloud's CI. Every `check` assertion on a kind this
- * edition declares must answer the same here — the proof that "the model
- * evaluated over derived tuples" means the SAME model.
+ * Runs the model's own suites (fga/tests/*.fga.yaml) through the built-in
+ * evaluator. The same documents run on the real OpenFGA engine against the
+ * same compiled model (`make test-authorization-model`, and CI's
+ * authorization-model lane), so every `check` and every `list_objects`
+ * assertion answered here is answered by OpenFGA too: the proof that the
+ * evaluator and the engine mean one thing by the model.
  *
- * What is not run is reported, never dropped: a check that targets a kind
- * this edition does not serve, every `list_objects` assertion (the list
- * scope's proof), and an assertion whose walk read a grant through a
- * type this edition does not declare come back from the kit as a skipped
- * set this file pins entry by entry, so a fixture that gains a scenario
- * is a visible diff here and not a silently smaller proof. The second
- * describe below pins the walk-dependent reason's own behaviour over a
- * throwaway model, so the kit is proven and not only used.
+ * Nothing is skipped. `DOCUMENTS` is the folder's listing, so a suite
+ * added to the folder without a line here fails, and a suite is never
+ * silently out of the proof.
  *
- * The cloud re-runs the LIVE documents through the same kit at the
- * re-pin (the drift test's second table), which is what makes the pinned
- * copies safe to hold.
+ * The second describe proves the kit's `list_objects` rule over a
+ * throwaway model: candidates are the objects the document's tuples are
+ * written on, checked one by one, so an object reached through a tupleset
+ * link is listed, one no relation reaches is not, and a wrong expectation
+ * fails.
  */
 import { readdirSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -28,26 +24,28 @@ import { describe, expect, it } from "vitest";
 
 import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { OrganizationSchema } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
 
 import { builtInModel, newModel } from "../model/index.js";
+import { parseObjectRef } from "../tuples.js";
+import type { StoreTestDocument } from "./store-test-kit.js";
+import {
+  objectsOfType,
+  parseStoreTestDocument,
+  storeTestCases,
+} from "./store-test-kit.js";
 import {
   computed,
-  declareKind,
   direct,
+  from,
   objectOf,
+  throwawayDeclaration,
   union,
-  usersetOf,
-} from "../model/rewrite.js";
-import type { StoreTestDocument, StoreTestSkip } from "../store-test-kit.js";
-import { parseStoreTestDocument, storeTestCases } from "../store-test-kit.js";
+} from "./throwaway-model.js";
 
-const FIXTURES = new URL("./fixtures/fga/", import.meta.url);
+const SUITES = new URL("../../../fga/tests/", import.meta.url);
 
-/**
- * Every document the cloud's `fga/tests/` folder holds, by file name — the
- * fixtures folder is a byte-exact mirror of it; a file added to either
- * without a line here fails.
- */
+/** Every suite the model's folder holds, by file name. */
 const DOCUMENTS = [
   "agent-channel-owner.fga.yaml",
   "agent-instance-creation.fga.yaml",
@@ -58,247 +56,117 @@ const DOCUMENTS = [
   "channel-participation.fga.yaml",
   "channel-session-visibility.fga.yaml",
   "default-instance-inheritance.fga.yaml",
+  "identity-provider-administration.fga.yaml",
+  "invitation-administration.fga.yaml",
+  "license-issuer.fga.yaml",
   "mcp-server-authoring.fga.yaml",
   "memory-subject-only.fga.yaml",
   "org-admin-owner-inheritance.fga.yaml",
   "org-shared-environment.fga.yaml",
   "platform-visibility.fga.yaml",
+  "plugin-owner.fga.yaml",
   "provider-standing-viewer.fga.yaml",
   "reserved-label-writer.fga.yaml",
   "schedule-owner.fga.yaml",
   "schedule-session-visibility.fga.yaml",
   "session-personal-resource.fga.yaml",
+  "team-membership.fga.yaml",
   "workflow-execution-sharing.fga.yaml",
 ] as const;
 
-function skipLine(skip: StoreTestSkip): string {
-  const relation = skip.relation === undefined ? "" : ` ${skip.relation}`;
-  const types = skip.types === undefined ? "" : ` (${skip.types.join(", ")})`;
-  return `${skip.document} :: ${skip.test} :: ${skip.subject}${relation} ${skip.object} :: ${skip.reason}${types}`;
-}
-
-/**
- * Every assertion the kit did not run, pinned, in the kit's three
- * reasons. `list-objects` lines are the list scope's proof and run when
- * it lands. `undeclared-kind` lines target `platform`, a kind this
- * edition never serves (the driver refuses it before any evaluation).
- * `undeclared-subject-type` lines are the checks whose walk read the
- * cloud's platform-tenancy grant, `identity_provider:<idp>#platform_user`
- * — a userset on a kind this edition does not declare, so the answer here
- * (nobody) is not the oracle's and is not asserted; the cloud runs the
- * same lines over its full model at the re-pin.
- */
-const SKIPPED_PINNED: ReadonlyArray<string> = [
-  // list-objects
-  "agent-channel-owner :: listing channels reflects ownership and grants, not membership :: identity_account:alice <agent_channel> :: list-objects",
-  "agent-channel-owner :: listing channels reflects ownership and grants, not membership :: identity_account:carol <agent_channel> :: list-objects",
-  "agent-channel-owner :: listing channels reflects ownership and grants, not membership :: identity_account:mallory <agent_channel> :: list-objects",
-  "agent-share-owner :: listing shares reflects ownership and grants, not membership :: identity_account:alice <agent_share> :: list-objects",
-  "agent-share-owner :: listing shares reflects ownership and grants, not membership :: identity_account:carol <agent_share> :: list-objects",
-  "agent-share-owner :: listing shares reflects ownership and grants, not membership :: identity_account:mallory <agent_share> :: list-objects",
-  "artifact-org-and-owner :: listing reflects org inheritance plus creator ownership :: identity_account:acme-guest <artifact> :: list-objects",
-  "artifact-org-and-owner :: listing reflects org inheritance plus creator ownership :: identity_account:eve <artifact> :: list-objects",
-  "artifact-org-and-owner :: listing reflects org inheritance plus creator ownership :: identity_account:victor <artifact> :: list-objects",
-  "blueprint-private-visibility :: org admin's listable agents include private ones (T08) :: identity_account:oscar <agent> :: list-objects",
-  "blueprint-private-visibility :: org member's listable agents exclude private ones :: identity_account:dave <agent> :: list-objects",
-  "blueprint-private-visibility :: org viewer's listable agents are exactly the viewer-shaped org-visible ones :: identity_account:vera <agent> :: list-objects",
-  "blueprint-private-visibility :: owner's listable agents include everything they authored :: identity_account:carol <agent> :: list-objects",
-  "channel-app-owner :: listing channel apps reflects ownership and grants, not membership :: identity_account:alice <channel_app> :: list-objects",
-  "channel-app-owner :: listing channel apps reflects ownership and grants, not membership :: identity_account:carol <channel_app> :: list-objects",
-  "channel-app-owner :: listing channel apps reflects ownership and grants, not membership :: identity_account:mallory <channel_app> :: list-objects",
-  "channel-participation :: list viewable and participable channels resolve per grant (drives listConversations) :: identity_account:carol <agent_channel> :: list-objects",
-  "channel-participation :: list viewable and participable channels resolve per grant (drives listConversations) :: identity_account:dave <agent_channel> :: list-objects",
-  "channel-participation :: list viewable and participable channels resolve per grant (drives listConversations) :: identity_account:trina <agent_channel> :: list-objects",
-  "channel-session-visibility :: list viewable sessions resolves the channel chain (drives listByChannel) :: identity_account:alice <session> :: list-objects",
-  "channel-session-visibility :: list viewable sessions resolves the channel chain (drives listByChannel) :: identity_account:bob <session> :: list-objects",
-  "channel-session-visibility :: list viewable sessions resolves the channel chain (drives listByChannel) :: identity_account:carol <session> :: list-objects",
-  "default-instance-inheritance :: list managed-org member's viewable agent instances resolves the default_of chain :: identity_account:alice <agent_instance> :: list-objects",
-  "memory-subject-only :: list-objects returns only the subject's own records :: identity_account:alice <memory> :: list-objects",
-  "memory-subject-only :: list-objects returns only the subject's own records :: identity_account:mallory <memory> :: list-objects",
-  "org-admin-owner-inheritance :: admin's listable resources include private blueprints, never personal kinds :: identity_account:ana <agent> :: list-objects",
-  "org-admin-owner-inheritance :: admin's listable resources include private blueprints, never personal kinds :: identity_account:ana <agent_instance> :: list-objects",
-  "org-admin-owner-inheritance :: admin's listable resources include private blueprints, never personal kinds :: identity_account:ana <session> :: list-objects",
-  "org-shared-environment :: org-members-can-list-shared-environments-only :: identity_account:dave <environment> :: list-objects",
-  "platform-visibility :: list managed-org member's viewable agents includes only the shared one :: identity_account:alice <agent> :: list-objects",
-  "schedule-owner :: listing schedules reflects ownership and grants, not membership :: identity_account:alice <schedule> :: list-objects",
-  "schedule-owner :: listing schedules reflects ownership and grants, not membership :: identity_account:carol <schedule> :: list-objects",
-  "schedule-owner :: listing schedules reflects ownership and grants, not membership :: identity_account:mallory <schedule> :: list-objects",
-  "schedule-session-visibility :: list viewable sessions resolves the schedule chain :: identity_account:alice <session> :: list-objects",
-  "schedule-session-visibility :: list viewable sessions resolves the schedule chain :: identity_account:bob <session> :: list-objects",
-  "schedule-session-visibility :: list viewable sessions resolves the schedule chain :: identity_account:carol <session> :: list-objects",
-  "workflow-execution-sharing :: list a teammate's viewable runs reflects both sharing axes :: identity_account:bob <workflow_execution> :: list-objects",
-  // undeclared-kind: platform
-  "provider-standing-viewer :: operator may view provider standing, tenants may not :: identity_account:mallory platform:stigmer :: undeclared-kind",
-  "provider-standing-viewer :: operator may view provider standing, tenants may not :: identity_account:opal platform:stigmer :: undeclared-kind",
-  "reserved-label-writer :: operator may write reserved labels, tenants may not :: identity_account:machine platform:stigmer :: undeclared-kind",
-  "reserved-label-writer :: operator may write reserved labels, tenants may not :: identity_account:mallory platform:stigmer :: undeclared-kind",
-  // undeclared-subject-type: identity_provider#platform_user
-  "agent-instance-creation :: the tenant-family case, the agent half from platform_viewer and the organization half at home :: identity_account:mia can_create_instance agent:open-bot :: undeclared-subject-type (identity_provider)",
-  "default-instance-inheritance :: managed-org member reaches the default instance of a platform-shared agent :: identity_account:alice can_execute agent_instance:sara-default :: undeclared-subject-type (identity_provider)",
-  "default-instance-inheritance :: managed-org member reaches the default instance of a platform-shared agent :: identity_account:alice can_view agent_instance:sara-default :: undeclared-subject-type (identity_provider)",
-  "default-instance-inheritance :: managed-org member reaches the default instance of a platform-shared workflow :: identity_account:alice can_execute workflow_instance:onboarding-default :: undeclared-subject-type (identity_provider)",
-  "default-instance-inheritance :: managed-org member reaches the default instance of a platform-shared workflow :: identity_account:alice can_view workflow_instance:onboarding-default :: undeclared-subject-type (identity_provider)",
-  "default-instance-inheritance :: outsiders get nothing from the default_of link :: identity_account:mallory can_execute agent_instance:sara-default :: undeclared-subject-type (identity_provider)",
-  "default-instance-inheritance :: outsiders get nothing from the default_of link :: identity_account:mallory can_view agent_instance:sara-default :: undeclared-subject-type (identity_provider)",
-  "platform-visibility :: managed-org members can view and execute a platform-shared agent :: identity_account:alice can_create_instance agent:sara :: undeclared-subject-type (identity_provider)",
-  "platform-visibility :: managed-org members can view and execute a platform-shared agent :: identity_account:alice can_execute agent:sara :: undeclared-subject-type (identity_provider)",
-  "platform-visibility :: managed-org members can view and execute a platform-shared agent :: identity_account:alice can_view agent:sara :: undeclared-subject-type (identity_provider)",
-  "platform-visibility :: managed-org members can view and execute a platform-shared agent :: identity_account:bob can_execute agent:sara :: undeclared-subject-type (identity_provider)",
-  "platform-visibility :: managed-org members can view and execute a platform-shared agent :: identity_account:bob can_view agent:sara :: undeclared-subject-type (identity_provider)",
-  "platform-visibility :: outsiders and unrelated orgs get nothing from platform visibility :: identity_account:mallory can_create_instance agent:sara :: undeclared-subject-type (identity_provider)",
-  "platform-visibility :: outsiders and unrelated orgs get nothing from platform visibility :: identity_account:mallory can_execute agent:sara :: undeclared-subject-type (identity_provider)",
-  "platform-visibility :: outsiders and unrelated orgs get nothing from platform visibility :: identity_account:mallory can_view agent:sara :: undeclared-subject-type (identity_provider)",
-  "platform-visibility :: platform-shared mcp_server is usable by managed-org members :: identity_account:alice can_connect mcp_server:github :: undeclared-subject-type (identity_provider)",
-  "platform-visibility :: platform-shared mcp_server is usable by managed-org members :: identity_account:alice can_use mcp_server:github :: undeclared-subject-type (identity_provider)",
-  "platform-visibility :: platform-shared mcp_server is usable by managed-org members :: identity_account:alice can_view mcp_server:github :: undeclared-subject-type (identity_provider)",
-  "platform-visibility :: platform-shared skill is usable by managed-org members :: identity_account:alice can_use skill:research :: undeclared-subject-type (identity_provider)",
-  "platform-visibility :: platform-shared skill is usable by managed-org members :: identity_account:alice can_view skill:research :: undeclared-subject-type (identity_provider)",
-  "platform-visibility :: platform-shared workflow is viewable and executable by managed-org members :: identity_account:alice can_execute workflow:onboarding :: undeclared-subject-type (identity_provider)",
-  "platform-visibility :: platform-shared workflow is viewable and executable by managed-org members :: identity_account:alice can_view workflow:onboarding :: undeclared-subject-type (identity_provider)",
-];
-
-describe("the cloud's OpenFGA store tests over the built-in evaluator", () => {
-  it("the fixtures folder holds exactly the documents this file pins", () => {
+describe("the model's suites over the built-in evaluator", () => {
+  it("the suites folder holds exactly the documents this file pins", () => {
     expect(
-      readdirSync(FIXTURES)
+      readdirSync(SUITES)
         .filter((name) => name.endsWith(".fga.yaml"))
         .sort(),
     ).toEqual([...DOCUMENTS]);
   });
 
-  const kits = DOCUMENTS.map((name) => {
+  for (const name of DOCUMENTS) {
     const document = parseStoreTestDocument(
-      yaml.load(readFileSync(fileURLToPath(new URL(name, FIXTURES)), "utf8")),
+      yaml.load(readFileSync(fileURLToPath(new URL(name, SUITES)), "utf8")),
       name,
     );
-    return { document, kit: storeTestCases(document, builtInModel) };
-  });
-
-  for (const { document, kit } of kits) {
-    if (kit.cases.length === 0) {
-      // Every check targets a kind this edition does not declare (the
-      // platform documents); reported as skipped, pinned below.
-      it.skip(`${document.name}: no check targets a declared kind`, () => {});
-      continue;
-    }
     describe(document.name, () => {
-      for (const storeTestCase of kit.cases) {
+      for (const storeTestCase of storeTestCases(document, builtInModel)) {
         it(storeTestCase.name, storeTestCase.run);
       }
     });
   }
-
-  // Declared after every case: a kit's `skipped` is complete once its
-  // cases have run (the walk-dependent reason is decided per assertion).
-  it("reports every assertion it did not run, and the list is the pinned one", () => {
-    const skipped = kits.flatMap(({ kit }) => kit.skipped.map(skipLine));
-    expect(skipped.sort()).toEqual([...SKIPPED_PINNED].sort());
-  });
 });
 
 /**
- * The kit's walk-dependent skip, proven over a throwaway model shaped
- * like a blueprint whose `viewer` line reads, in order, a direct person,
- * `owner`, then a userset on a type the model does not declare — the
- * platform-tenancy shape — so each arm below settles at a different point
- * of the union.
+ * The kit's `list_objects` rule over a throwaway model: an agent whose
+ * `owner` is a direct person or an admin of its organization, reached
+ * through the `organization` tupleset link.
  */
-describe("the kit skips an assertion whose walk read a type the model does not declare", () => {
+describe("the kit lists exactly the objects a relation reaches", () => {
   const model = newModel([
-    declareKind({
+    throwawayDeclaration({
+      kind: ApiResourceKind.organization,
+      schema: OrganizationSchema,
+      relations: [["admin", direct(objectOf("identity_account"))]],
+    }),
+    throwawayDeclaration({
       kind: ApiResourceKind.agent,
       schema: AgentSchema,
-      source: "fga/model/agentic/agent.fga",
       relations: [
-        ["owner", direct(objectOf("identity_account"))],
-        [
-          "platform_viewer",
-          direct(usersetOf("identity_provider", "platform_user")),
-        ],
-        [
-          "viewer",
-          union(
-            direct(objectOf("identity_account")),
-            computed("owner"),
-            computed("platform_viewer"),
-          ),
-        ],
-        ["can_view", computed("viewer")],
+        ["organization", direct(objectOf("organization"))],
+        ["owner", union(direct(objectOf("identity_account")), from("admin", "organization"))],
         ["can_edit", computed("owner")],
       ],
     }),
   ]);
 
-  const document: StoreTestDocument = {
-    name: "throwaway",
-    tuples: [
-      { user: "identity_account:carol", relation: "owner", object: "agent:a" },
-      {
-        user: "identity_provider:idp#platform_user",
-        relation: "platform_viewer",
-        object: "agent:a",
-      },
-      { user: "identity_account:carol", relation: "owner", object: "agent:b" },
-    ],
-    tests: [
-      {
-        name: "arms",
-        check: [
-          // The owner: `viewer` settles on the direct line; `can_edit` never reads platform_viewer.
-          {
-            user: "identity_account:carol",
-            object: "agent:a",
-            assertions: { can_view: true, can_edit: true },
-          },
-          // A stranger: the union walks to platform_viewer and reads the undeclared userset.
-          {
-            user: "identity_account:mallory",
-            object: "agent:a",
-            assertions: { can_view: false, can_edit: false },
-          },
-          // No such tuple on this object: the same stranger's walk reads nothing undeclared.
-          {
-            user: "identity_account:mallory",
-            object: "agent:b",
-            assertions: { can_view: false },
-          },
-        ],
-        list_objects: [],
-      },
-    ],
-  };
-
-  it("runs the arms the walk settles before the undeclared type, skips exactly the one that read it — whatever it would have answered", async () => {
-    const kit = storeTestCases(document, model);
-    expect(kit.skipped).toEqual([]);
-    for (const storeTestCase of kit.cases) {
-      await storeTestCase.run();
-    }
-    expect(kit.skipped.map(skipLine)).toEqual([
-      "throwaway :: arms :: identity_account:mallory can_view agent:a :: undeclared-subject-type (identity_provider)",
-    ]);
-  });
+  const tuples = [
+    { user: "identity_account:ada", relation: "owner", object: "agent:mine" },
+    { user: "organization:acme", relation: "organization", object: "agent:org" },
+    { user: "identity_account:ada", relation: "admin", object: "organization:acme" },
+    { user: "organization:other", relation: "organization", object: "agent:elsewhere" },
+  ];
 
-  it("asserts the arms it runs: a wrong expectation on a settled arm still fails", async () => {
-    const wrong: StoreTestDocument = {
-      ...document,
+  function documentExpecting(expected: ReadonlyArray<string>): StoreTestDocument {
+    return {
+      name: "throwaway",
+      tuples,
       tests: [
         {
-          name: "wrong",
-          check: [
-            {
-              user: "identity_account:carol",
-              object: "agent:a",
-              assertions: { can_edit: false },
-            },
+          name: "listing",
+          check: [],
+          list_objects: [
+            { user: "identity_account:ada", type: "agent", assertions: { can_edit: expected } },
           ],
-          list_objects: [],
         },
       ],
     };
-    const kit = storeTestCases(wrong, model);
-    await expect(kit.cases[0]?.run()).rejects.toThrow(
-      /expected false, got true/,
+  }
+
+  it("takes as candidates every object of the type a tuple is written on", () => {
+    expect(
+      objectsOfType(
+        tuples.map((tuple) => ({
+          object: parseObjectRef(tuple.object),
+          relation: tuple.relation,
+          subject: { form: "object" as const, object: parseObjectRef(tuple.user) },
+        })),
+        "agent",
+      ),
+    ).toEqual(["agent:mine", "agent:org", "agent:elsewhere"]);
+  });
+
+  it("lists the direct object and the one reached through the tupleset, in any order", async () => {
+    const [listing] = storeTestCases(documentExpecting(["agent:org", "agent:mine"]), model);
+    await expect(listing?.run()).resolves.toBeUndefined();
+  });
+
+  it("fails an expectation that lists an object no relation reaches, or misses one", async () => {
+    const [extra] = storeTestCases(
+      documentExpecting(["agent:mine", "agent:org", "agent:elsewhere"]),
+      model,
     );
+    await expect(extra?.run()).rejects.toThrow("identity_account:ada can_edit objects of type agent");
+    const [missing] = storeTestCases(documentExpecting(["agent:mine"]), model);
+    await expect(missing?.run()).rejects.toThrow("identity_account:ada can_edit objects of type agent");
   });
 });