@stigmer/server 3.27.2 → 3.29.0

package/src/authorization/__tests__/support.ts

@@ -15,6 +15,11 @@
  * parent), which is what lets the parity pin run over all of them.
  * `spec` and `status` overrides sit on top for the arms that need a
  * pointer or a level set.
+ *
+ * A fixture row exists only for a kind this edition stores rows of: every
+ * type of the model but a rowless one (`platform`, model/bindings.ts), so
+ * the builders take a StoredKindDeclaration and `storedDeclaration`
+ * refuses a rowless type by name.
  */
 import { create } from "@bufbuild/protobuf";
 import type { DescMessage, Message } from "@bufbuild/protobuf";
@@ -26,6 +31,7 @@ import {
   getKindMeta,
   kindEnumName,
 } from "../../pipeline/apiresource-meta.js";
+import { builtInModel } from "../model/index.js";
 import type { KindDeclaration } from "../model/rewrite.js";
 
 export interface FixtureRowFacts {
@@ -39,6 +45,28 @@ export interface FixtureRowFacts {
   readonly status?: Readonly<Record<string, unknown>>;
 }
 
+/** A declaration of a kind with stored rows: what a fixture row is built, saved and decoded with. */
+export type StoredKindDeclaration = KindDeclaration & { readonly schema: DescMessage };
+
+/** Whether rows of the declaration's kind are stored: every type but a rowless one. */
+export function hasStoredRows(
+  declaration: KindDeclaration,
+): declaration is StoredKindDeclaration {
+  return declaration.schema !== undefined;
+}
+
+/** The built-in model's declaration of `type`, which must be a kind with stored rows. */
+export function storedDeclaration(type: string): StoredKindDeclaration {
+  const declaration = builtInModel.byType(type);
+  if (declaration === undefined) {
+    throw new Error(`${type} is not a type of the model`);
+  }
+  if (!hasStoredRows(declaration)) {
+    throw new Error(`${type} is rowless: no row of it is stored`);
+  }
+  return declaration;
+}
+
 /** The id the fixture gives the parent of `parentKind`: `<type>-1`. */
 export function fixtureParentId(parentKind: string): string {
   return `${kindEnumName(getKindEnum(parentKind))}-1`;
@@ -46,7 +74,7 @@ export function fixtureParentId(parentKind: string): string {
 
 /** A row of `declaration.kind` carrying exactly the given facts, its parents filled. */
 export function fixtureRow(
-  declaration: KindDeclaration,
+  declaration: StoredKindDeclaration,
   facts: FixtureRowFacts,
 ): Message {
   // Typed loosely on purpose: the schema is any declared kind's, and
@@ -70,7 +98,7 @@ export function fixtureRow(
 }
 
 /** `kind_meta`'s parent spec fields for the kind, by generated name, each naming `<parentKind>-1`. */
-function parentFieldsOf(declaration: KindDeclaration): Record<string, string> {
+function parentFieldsOf(declaration: StoredKindDeclaration): Record<string, string> {
   const config = getKindMeta(declaration.kind).authorization;
   const spec = specSchemaOf(declaration.schema);
   const fields: Record<string, string> = {};

package/src/authorization/__tests__/throwaway-model.ts

@@ -0,0 +1,75 @@
+/**
+ * Builders for tests' throwaway models: a declaration written by hand in
+ * the evaluator's vocabulary (model/rewrite.ts), for the shapes the one
+ * real model must never hold (a cycle, a chain past the depth bound) and
+ * for proving a mechanism over a model small enough to read in the test.
+ * The built-in model is never written this way: it is the compiled
+ * OpenFGA JSON, read by model/openfga-json.ts.
+ *
+ * Nothing here validates: a test that declares a cycle means to. The
+ * builders are named so a declaration reads like the `.fga` line it
+ * stands for:
+ *
+ *   define viewer: [identity_account, organization#viewer] or owner
+ *     → union(direct(objectOf("identity_account"), usersetOf("organization", "viewer")), computed("owner"))
+ */
+import type { DescMessage } from "@bufbuild/protobuf";
+
+import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { kindEnumName } from "../../pipeline/apiresource-meta.js";
+import type {
+  DerivedRelation,
+  KindDeclaration,
+  Rewrite,
+  SubjectType,
+} from "../model/rewrite.js";
+
+export function objectOf(type: string): SubjectType {
+  return { form: "object", type };
+}
+
+export function usersetOf(type: string, relation: string): SubjectType {
+  return { form: "userset", type, relation };
+}
+
+export function direct(...subjects: ReadonlyArray<SubjectType>): Rewrite {
+  return { node: "this", subjects };
+}
+
+export function computed(relation: string): Rewrite {
+  return { node: "computed", relation };
+}
+
+export function from(relation: string, tupleset: string): Rewrite {
+  return { node: "from", relation, tupleset };
+}
+
+export function union(...members: ReadonlyArray<Rewrite>): Rewrite {
+  return { node: "union", members };
+}
+
+export function intersection(...members: ReadonlyArray<Rewrite>): Rewrite {
+  return { node: "intersection", members };
+}
+
+export interface ThrowawayDeclarationInput {
+  readonly kind: ApiResourceKind;
+  /** Omitted for a rowless type. */
+  readonly schema?: DescMessage;
+  readonly source?: string;
+  readonly relations: ReadonlyArray<readonly [name: string, rewrite: Rewrite]>;
+  readonly derived?: ReadonlyArray<readonly [name: string, rule: DerivedRelation]>;
+}
+
+/** A declaration exactly as written, for `newModel`. */
+export function throwawayDeclaration(input: ThrowawayDeclarationInput): KindDeclaration {
+  return {
+    kind: input.kind,
+    type: kindEnumName(input.kind),
+    schema: input.schema,
+    source: input.source ?? "throwaway",
+    relations: new Map(input.relations),
+    derived: new Map(input.derived ?? []),
+  };
+}

package/src/authorization/__tests__/wire-permissions.test.ts

@@ -1,83 +1,136 @@
 /**
- * Pins that every question the wire can ask this edition's authorizer
- * has a line in the model: for every `rpc.config`-annotated method the
- * open-source server SERVES whose annotation names a static kind this
- * edition serves, the permission is a relation that kind's transcript
- * declares. A relation the kind does not define answers `deny` here
- * (evaluator.ts) — an RPC annotated with such a pair would refuse every
- * caller, green on the permissive `local*` targets and dark only under
- * enforcement, so the gap is caught at the registry instead of on a
- * self-host.
+ * Pins the contract to the model over the whole wire: every question an
+ * RPC annotation asks the authorization model is a relation the model
+ * defines. The model (fga/model) and the contract (apis/, reaching this
+ * package as `@stigmer/protos`) are both this repository's, so their
+ * agreement is this repository's to keep, whichever edition serves the
+ * RPC. That is why the scope here is every service in `@stigmer/protos`,
+ * where authorize-annotation-completeness.test.ts scopes itself to the
+ * methods open source serves: that test governs the Authorize step, and a
+ * composition's own services are its own conformance suite's business;
+ * this one asks whether the model and the contract say the same thing.
  *
- * Scope follows authorize-annotation-completeness.test.ts: the empty
- * composition's routes, replayed into a recorder, are exactly the methods
- * the OSS Authorize step governs. Outside the pin, each for a stated
- * reason: `is_public` and `is_skip_authorization` methods (the annotation
- * is never resolved); a kind the edition does not serve (`platform`; the
- * driver refuses it before any evaluation, so under the built-in posture
- * nobody holds a platform permission); a kind named by
- * `resource_kind_path` (the IamPolicy lane's — the kind is the request's,
- * and the target's own declaration answers at run time).
+ * Two invariants:
+ *   - every `rpc.config` annotation that names a static kind asks a
+ *     permission that kind's type defines. A relation the type does not
+ *     define answers `deny` in the built-in evaluator and a validation
+ *     error in OpenFGA, so such an RPC refuses every caller, dark until
+ *     someone runs it under enforcement;
+ *   - the permission of every `resource_kind_path` lane (the IamPolicy
+ *     lanes, whose kind is the request's) is defined on every kind whose
+ *     `kind_meta` lists grantable roles, because each such kind is one the
+ *     grant path admits.
+ *
+ * Outside the pin, as in the annotation-completeness precedent: `is_public`
+ * and `is_skip_authorization` methods (their annotation is never
+ * resolved), and a `config` that names no kind (`IamPolicyQueryController.get`,
+ * which authorizes the loaded policy's resource).
+ *
+ * What does not hold today is pinned, never dropped: `KNOWN_GAPS` lists
+ * each disagreement, and the test requires the computed list to equal it,
+ * so a fix to the model or the contract fails here until its line is
+ * removed.
+ *
+ * The walk reads the stubs' built `dist`. `make test-server` builds them
+ * first; a bare `vitest` run in a checkout whose `dist` is stale reads
+ * services the contract no longer has.
  */
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { readdirSync } from "node:fs";
+import { createRequire } from "node:module";
 import path from "node:path";
 
+import type { DescService } from "@bufbuild/protobuf";
 import { getOption, hasOption } from "@bufbuild/protobuf";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { beforeAll, describe, expect, it } from "vitest";
 
-import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import {
+  ApiResourceKind,
+  ApiResourceKindSchema,
+} from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import {
   config as rpcAuthorizationConfig,
   is_public,
   is_skip_authorization,
 } from "@stigmer/protos/ai/stigmer/commons/rpc/method_options_pb";
 import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
-import { ServerEdition } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
 
-import { loadConfig } from "../../boot/config.js";
-import { composeServer } from "../../boot/compose.js";
-import type { ComposedServer } from "../../boot/compose.js";
-import {
-  baseConfig,
-  servedServices,
-  silentLogger,
-} from "../../extensions/__tests__/composed-support.js";
-import {
-  kindEnumName,
-  kindServedByEdition,
-} from "../../pipeline/apiresource-meta.js";
-import { declarationFor } from "../model/index.js";
+import { grantableRolesFor, kindEnumName } from "../../pipeline/apiresource-meta.js";
+import { builtInModel } from "../model/index.js";
+
+/**
+ * Today's disagreements between the contract and the model, each with its
+ * reason. Removing a gap from the model or the contract fails the test
+ * until its line is removed here.
+ */
+const KNOWN_GAPS: ReadonlyArray<string> = [
+  // Contract ahead of model, on purpose: Plan's proto says the relation
+  // lands in the model with the entry that serves the kind
+  // (apis/ai/stigmer/billing/plan/v1/command.proto), and no edition serves
+  // Plan yet.
+  "ai.stigmer.billing.plan.v1.PlanCommandController/create asks can_manage_plans on platform",
+  "ai.stigmer.billing.plan.v1.PlanCommandController/retire asks can_manage_plans on platform",
+  // Artifacts are grantable in kind_meta, but the model defines no access
+  // relations on them: https://github.com/stigmer/stigmer/issues/1268.
+  "the resource_kind_path lanes ask can_grant_access on artifact",
+  "the resource_kind_path lanes ask can_view_access on artifact",
+];
 
-/** One annotated, served, statically-targeted method: the question the wire asks. */
+/** One annotated method: the question it asks the model. */
 interface WireQuestion {
   readonly method: string;
+  /** The static kind, or unknown when the kind is the request's (`kindPath`). */
   readonly kind: ApiResourceKind;
+  readonly kindPath: string;
   readonly permission: string;
 }
 
-describe("every static (kind, permission) the served RPCs ask about is a declared relation", () => {
-  let dir: string;
-  let server: ComposedServer;
+/** Every service descriptor the stubs package exports, loaded through its own specifiers. */
+async function everyService(): Promise<ReadonlyArray<DescService>> {
+  const require = createRequire(import.meta.url);
+  const anchor = "ai/stigmer/iam/v1/enum_pb";
+  const resolved = require.resolve(`@stigmer/protos/${anchor}`);
+  const dist = resolved.slice(0, resolved.length - `${anchor}.js`.length);
+  const modules = readdirSync(path.join(dist, "ai"), { recursive: true, encoding: "utf8" })
+    .filter((file) => file.endsWith("_pb.js"))
+    .map((file) => `ai/${file.slice(0, -".js".length).split(path.sep).join("/")}`)
+    .sort();
+  const services: DescService[] = [];
+  for (const specifier of modules) {
+    const loaded: Record<string, unknown> = await import(`@stigmer/protos/${specifier}`);
+    for (const value of Object.values(loaded)) {
+      if (isService(value)) {
+        services.push(value);
+      }
+    }
+  }
+  return services;
+}
 
-  beforeAll(async () => {
-    dir = mkdtempSync(path.join(tmpdir(), "wire-permissions-test-"));
-    server = await composeServer({
-      config: loadConfig(baseConfig(dir)),
-      logger: silentLogger,
-      portOverride: 0,
-      host: "127.0.0.1",
-    });
-  });
+function isService(value: unknown): value is DescService {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "kind" in value &&
+    value.kind === "service" &&
+    "methods" in value
+  );
+}
 
-  afterAll(async () => {
-    await server.shutdown();
-    rmSync(dir, { recursive: true, force: true });
+/** The model's relations on a kind, or none when the model does not define it. */
+function relationsOf(kind: ApiResourceKind): ReadonlySet<string> {
+  return new Set(builtInModel.byKind(kind)?.relations.keys() ?? []);
+}
+
+describe("the contract asks the model only what the model defines", () => {
+  let services: ReadonlyArray<DescService>;
+
+  beforeAll(async () => {
+    services = await everyService();
   });
 
-  function wireQuestions(): WireQuestion[] {
-    const questions: WireQuestion[] = [];
-    for (const service of servedServices(server.routes)) {
+  function annotated(): ReadonlyArray<WireQuestion> {
+    const out: WireQuestion[] = [];
+    for (const service of services) {
       for (const method of service.methods) {
         if (
           !hasOption(method, rpcAuthorizationConfig) ||
@@ -87,68 +140,49 @@ describe("every static (kind, permission) the served RPCs ask about is a declare
           continue;
         }
         const config = getOption(method, rpcAuthorizationConfig);
-        if (
-          config.resourceKind === ApiResourceKind.api_resource_kind_unknown ||
-          !kindServedByEdition(config.resourceKind, ServerEdition.oss)
-        ) {
-          continue;
-        }
-        questions.push({
+        out.push({
           method: `${service.typeName}/${method.name}`,
           kind: config.resourceKind,
+          kindPath: config.resourceKindPath,
           permission: IamPermission[config.permission] ?? "",
         });
       }
     }
-    return questions;
+    return out;
   }
 
-  it("names a declared relation for every question, with none undeclared", () => {
-    const questions = wireQuestions();
-    expect(questions.length).toBeGreaterThan(60);
-    const undeclared = questions
-      .filter(
-        (q) => declarationFor(q.kind)?.relations.has(q.permission) !== true,
-      )
-      .map(
-        (q) =>
-          `${q.method} asks ${q.permission} on ${kindEnumName(q.kind)}, which its transcript does not declare`,
-      );
-    expect(undeclared).toEqual([]);
+  it("reads the whole contract, the IamPolicy lanes included", () => {
+    const questions = annotated();
+    expect(services.length).toBeGreaterThan(60);
+    expect(questions.length).toBeGreaterThan(150);
+    expect(questions.some((q) => q.kindPath !== "")).toBe(true);
   });
 
-  it("asks about every served kind the model declares except the one no RPC targets statically", () => {
-    // iam_policy's RPCs target the policy's RESOURCE (`resource_kind_path`
-    // or the load-then-authorize `get`). Every other declared kind is asked
-    // about by at least one static annotation — execution_context through
-    // its `get` and `delete`; its runner-token lane stays a skip.
-    const asked = new Set(wireQuestions().map((q) => kindEnumName(q.kind)));
-    expect([...asked].sort()).toEqual(
-      [
-        "agent",
-        "agent_channel",
-        "agent_execution",
-        "agent_instance",
-        "agent_share",
-        "api_key",
-        "artifact",
-        "channel_app",
-        "environment",
-        "execution_context",
-        "identity_account",
-        "mcp_server",
-        "memory",
-        "oauth_app",
-        "organization",
-        "platform_client",
-        "plugin",
-        "schedule",
-        "session",
-        "skill",
-        "workflow",
-        "workflow_execution",
-        "workflow_instance",
-      ].sort(),
+  it("defines every relation the contract asks about, except the known gaps", () => {
+    const questions = annotated();
+    const gaps: string[] = [];
+
+    for (const q of questions) {
+      if (q.kind !== ApiResourceKind.api_resource_kind_unknown && !relationsOf(q.kind).has(q.permission)) {
+        gaps.push(`${q.method} asks ${q.permission} on ${kindEnumName(q.kind)}`);
+      }
+    }
+
+    const pathPermissions = new Set(
+      questions.filter((q) => q.kindPath !== "").map((q) => q.permission),
     );
+    for (const value of ApiResourceKindSchema.values) {
+      const kind = value.number as ApiResourceKind;
+      if (kind === ApiResourceKind.api_resource_kind_unknown || grantableRolesFor(kind).length === 0) {
+        continue;
+      }
+      for (const permission of [...pathPermissions].sort()) {
+        if (!relationsOf(kind).has(permission)) {
+          gaps.push(`the resource_kind_path lanes ask ${permission} on ${kindEnumName(kind)}`);
+        }
+      }
+    }
+
+    expect(gaps.sort()).toEqual([...KNOWN_GAPS].sort());
   });
 });

package/src/authorization/authorizer.ts

@@ -5,8 +5,8 @@
  * tuples this row would have had, derived on the fly (evaluator.ts over
  * derived-tuples.ts). Every arm below mirrors the cloud's driver
  * (stigmer-cloud src/authorizer/fga-authorizer.ts) by name and copy, so
- * the two editions answer one question the same way and the drift test
- * can pin the arms and not only the model.
+ * the two editions answer one question the same way, over the one model
+ * both read (model/index.ts).
  *
  * The arms, in order:
  *   1. The cloud's four pre-checks with the Java service's copy, each a
@@ -87,7 +87,7 @@ import { formatObjectRef } from "./tuples.js";
  * their rows live in its own tables, out of its probe's reach; matching
  * the set here keeps the wire identical across editions (an unknown
  * platform client's id is PERMISSION_DENIED with the annotation's copy in
- * both). The cloud's model drift test pins every kind here inside its
+ * both). The cloud pins every kind here inside its own
  * `PROBE_EXEMPT_KINDS`, which is why this set is exported; a kind that
  * moves into open source joins this set in the same change.
  *

package/src/authorization/derived-tuples.ts

@@ -12,7 +12,7 @@
  *   - owner SELF:     <row>#owner@identity_account:<row id>
  *   - creator:        <row>#creator@identity_account:<creator stamp>   (kinds flagged requires_creator_tuple)
  *   - org-viewer:     <row>#viewer@organization:<org>#viewer          (visibility_org; cloud#257's shape)
- *   - platform-viewer: none — it fans out over identity providers, a kind this edition does not serve
+ *   - platform-viewer: none — it fans out over identity providers, which this edition does not serve: the model defines the type, and no tuple of it is derived here
  *
  * Two facts are this edition's own and are stated here, nowhere else:
  *   - The ORGANIZATION's owner is a ROW, not a derivation. 2b's role
@@ -372,7 +372,11 @@ export function newDerivedTupleSource(
   };
 }
 
-/** The decoded row for an object, or undefined when the kind is not declared or the row does not exist. */
+/**
+ * The decoded row for an object, or undefined when the kind is not
+ * declared, is rowless (`platform`, which resolves over tuples alone), or
+ * the row does not exist.
+ */
 async function loadRow(
   deps: Pick<DerivedTupleSourceDeps, "store" | "accounts">,
   model: Model,
@@ -382,6 +386,7 @@ async function loadRow(
   const kind = kindByEnumName(object.type);
   if (
     declaration === undefined ||
+    declaration.schema === undefined ||
     kind === ApiResourceKind.api_resource_kind_unknown ||
     object.id === ""
   ) {

package/src/authorization/evaluator.ts

@@ -30,11 +30,11 @@
  * it is being resolved is a cycle in the declarations, which is a bug,
  * and a resolution deeper than MAX_RESOLUTION_DEPTH is the same class of
  * bug; both throw, because the alternative — a quiet `false` — would turn
- * a broken transcript into a lockout nobody can see. A kind the model does
- * not declare is a fault as the check's TARGET (the driver refuses
- * unserved kinds before evaluation, so reaching here is a registry gap)
- * and simply an object with no relations when reached through a tuple
- * (`identity_provider#platform_user`, which no open-source tuple names).
+ * a broken model into a lockout nobody can see. A kind the model does
+ * not declare is a fault as the check's TARGET (the built-in model
+ * declares every kind, so reaching here is a registry gap) and simply an
+ * object with no relations when reached through a tuple (only a test's
+ * throwaway model omits a type).
  * A relation the kind does not declare is `false` — the ruled answer for
  * a wire question the model has no line for, where OpenFGA
  * itself answers a validation error.
@@ -59,14 +59,12 @@ import { ACCOUNT_TYPE, formatObjectRef, pairKey } from "./tuples.js";
 export const MAX_RESOLUTION_DEPTH = 25;
 
 /**
- * The faults an evaluation can raise. Two are consumer bugs by the seam
- * contracts (a kind the model does not declare; the `internal` class
- * offered to the list scope's restrict verb, which the shared helper
- * answers before any driver); the rest are the model's own.
+ * The faults an evaluation can raise. One is a consumer bug by the seam
+ * contracts (a kind the model does not declare, or a rowless one asked
+ * for its rows); the rest are the model's own.
  */
 export type EvaluationFault =
   | "undeclared-target-kind"
-  | "internal-caller-offered"
   | "resolution-depth-exceeded"
   | "resolution-cycle";
 

package/src/authorization/list-read-scope.ts

@@ -40,27 +40,30 @@
  * returns the org-narrowed rows for the class before any driver is asked
  * (extensions/list-read-scope.ts, the header's contract line), the
  * Authorize step's trust-domain rule applied to a list answer. So this
- * driver's `restrictListEntries` REFUSES the class (`internal-caller-offered`):
- * being offered it means a caller reached the driver around the one
- * consumption idiom, and evaluating the server as a person would return
- * a quiet short list — the failure shape stigmer#1207 fixed. The
- * enumeration verb has no helper in front of it and keeps its own arm:
- * every id of the kind, as the built-in directory answers the class with
- * every organization. No in-process edge reaches an enumeration lane
- * today; the arm is pinned so a future one meets the rule.
+ * driver's `restrictListEntries` REFUSES the class with the seam's
+ * `InternalCallerOfferedError`: being offered it means a caller reached
+ * the driver around the one consumption idiom, and evaluating the server
+ * as a person would return a quiet short list — the failure shape
+ * stigmer#1207 fixed. The enumeration verb has no helper in front of it
+ * and keeps its own arm: every id of the kind, as the built-in directory
+ * answers the class with every organization. No in-process edge reaches
+ * an enumeration lane today; the arm is pinned so a future one meets the
+ * rule.
  *
  * Faults THROW and are never an empty answer (the seam: an empty set means
  * "authorized to see nothing"; an outage is the pipeline's sanitized
- * INTERNAL). A kind the model does not declare, like the internal class
- * above, is a consumer bug by the seam's contract and faults through the
- * evaluator, loud; the model declares exactly the open-source tier, so no
- * served lane can reach it.
+ * INTERNAL). A kind the model does not declare, or a rowless one
+ * (`platform`, which has no stored rows to list), is, like the internal
+ * class above, a consumer bug by the seam's contract, and faults through
+ * the evaluator's own error, loud; every served list lane lists a kind
+ * with rows.
  *
  * Logging. One debug line per call — kind, offered, kept, elapsed — what
  * an operator needs to answer "why is Alice's list short" beside the
  * Authorizer's per-denial lines; never the token.
  */
 import { fromBinary } from "@bufbuild/protobuf";
+import type { DescMessage } from "@bufbuild/protobuf";
 
 import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 
@@ -71,6 +74,7 @@ import type {
   ListEntryMeta,
   ListReadScope,
 } from "../extensions/list-read-scope.js";
+import { InternalCallerOfferedError } from "../extensions/list-read-scope.js";
 import { kindEnumName } from "../pipeline/apiresource-meta.js";
 import type { Store } from "../store/interface.js";
 import { newDerivedTupleSource } from "./derived-tuples.js";
@@ -87,6 +91,9 @@ import type { ObjectRef, Person } from "./tuples.js";
 /** The relation every list lane reads through (the cloud's LIST_RELATION). */
 const LIST_RELATION = "can_view";
 
+/** A declaration of a kind with stored rows: the only kind a list lane can list. */
+type ListableDeclaration = KindDeclaration & { readonly schema: DescMessage };
+
 export interface BuiltInListReadScopeDeps {
   readonly store: Store;
   /** The port the grant path writes through — the person's rows are read from the same instance. */
@@ -153,8 +160,12 @@ export function newBuiltInListReadScope(
     return kept;
   }
 
-  /** The declaration a verb evaluates against; an undeclared kind is the evaluator's own fault, raised before any read. */
-  function requireDeclared(kind: ApiResourceKind): KindDeclaration {
+  /**
+   * The declaration a verb evaluates against, which must be a kind with
+   * stored rows. An undeclared kind, or a rowless one, is the evaluator's
+   * own fault, raised before any read.
+   */
+  function requireListable(kind: ApiResourceKind): ListableDeclaration {
     const declaration = model.byKind(kind);
     if (declaration === undefined) {
       throw new AuthorizationEvaluationError(
@@ -162,11 +173,18 @@ export function newBuiltInListReadScope(
         `no declaration for kind '${kindEnumName(kind)}' — a list lane asked the scope about a kind the model does not declare`,
       );
     }
-    return declaration;
+    const schema = declaration.schema;
+    if (schema === undefined) {
+      throw new AuthorizationEvaluationError(
+        "undeclared-target-kind",
+        `kind '${kindEnumName(kind)}' has no stored rows — a list lane asked the scope about a rowless kind`,
+      );
+    }
+    return { ...declaration, schema };
   }
 
   /** Every row of `kind` the store holds, as facts; a row that does not decode is skipped. */
-  async function everyRowOf(declaration: KindDeclaration): Promise<RowFacts[]> {
+  async function everyRowOf(declaration: ListableDeclaration): Promise<RowFacts[]> {
     const kind = declaration.kind;
     const rows = await deps.store.listResources(kind);
     const facts: RowFacts[] = [];
@@ -189,12 +207,9 @@ export function newBuiltInListReadScope(
       kind: ApiResourceKind,
       entries: ReadonlyArray<ListEntryMeta>,
     ): Promise<ReadonlySet<string>> {
-      requireDeclared(kind);
+      requireListable(kind);
       if (caller.callerClass === "internal") {
-        throw new AuthorizationEvaluationError(
-          "internal-caller-offered",
-          `the internal caller class was offered to the list scope for kind '${kindEnumName(kind)}' — the shared helper answers that class before any driver; a list lane reached the driver around it`,
-        );
+        throw new InternalCallerOfferedError(kind);
       }
       // One candidate per unique id: a lane offers each row once, and a
       // duplicate would only spend a walk to learn the same answer.
@@ -211,7 +226,7 @@ export function newBuiltInListReadScope(
       caller: CallerIdentity,
       kind: ApiResourceKind,
     ): Promise<ReadonlySet<string>> {
-      const candidates = await everyRowOf(requireDeclared(kind));
+      const candidates = await everyRowOf(requireListable(kind));
       if (caller.callerClass === "internal") {
         return new Set(candidates.map((facts) => facts.id));
       }