@stigmer/server 3.25.0 → 3.27.0

package/src/authorization/model/rewrite.ts

@@ -1,7 +1,7 @@
 /**
  * The relation-rewrite vocabulary the model declarations are written in —
- * the four forms an OpenFGA `define` line takes in the cloud's 27 `.fga`
- * files, and nothing more:
+ * the forms an OpenFGA `define` line takes in the cloud's `.fga` files,
+ * and nothing more:
  *
  *   define organization: [organization]                      → direct(objectOf("organization"))
  *   define owner: [identity_account] or admin from organization
@@ -10,8 +10,20 @@
  *                   or owner or platform_viewer
  *                → union(direct(objectOf(...), usersetOf(...), usersetOf(...)),
  *                        computed("owner"), computed("platform_viewer"))
+ *   define member: [identity_account] and viewer from organization
+ *                → intersection(direct(objectOf("identity_account")), from("viewer", "organization"))
  *   define can_view: viewer                                   → computed("viewer")
  *
+ * `and` exists for one shape: a relation that is true only while another
+ * holds too — a team's member is a person granted the role AND still one
+ * of the organization's viewers, so leaving the organization ends every
+ * team-derived grant with no cleanup. A line is either a union or an
+ * intersection of leaves, never both: the DSL would need parentheses to
+ * mix them, the cloud's reader refuses parentheses, and `declareKind`
+ * refuses the nesting that would need them. `but not` has no node; the day
+ * a line needs it, the transcript cannot be written and the gap is a
+ * design act.
+ *
  * A subject type is an object type or a userset; the model admits no
  * wildcard (`type:*`) and declares no condition, so neither has a form
  * here. The day a line needs one, the transcript cannot be written and
@@ -21,10 +33,7 @@
  * file: the same relations, in the file's order, each line rewritten in
  * these builders so a reader with the model open sees the same text, and
  * so a structural compare against the file (the cloud's drift test at
- * the re-pin) needs no translation table. Intersection and exclusion
- * (`and`, `but not`) do not appear in the model and have no node here;
- * the day they do, the transcript cannot be written and the gap is a
- * design act, not a silent approximation.
+ * the re-pin) needs no translation table.
  *
  * The direct form carries its type restrictions (`[identity_account,
  * organization#viewer]`) because the evaluator ENFORCES them: a tuple
@@ -72,7 +81,12 @@ export type Rewrite =
       readonly tupleset: string;
     }
   /** `a or b or c` — the first true member wins, in the line's order. */
-  | { readonly node: "union"; readonly members: ReadonlyArray<Rewrite> };
+  | { readonly node: "union"; readonly members: ReadonlyArray<Rewrite> }
+  /** `a and b` — true only when every member is, in the line's order; the first false one ends it. */
+  | {
+      readonly node: "intersection";
+      readonly members: ReadonlyArray<Rewrite>;
+    };
 
 // ---------------------------------------------------------------------------
 // Builders — named so a transcript reads like its `.fga` line.
@@ -102,6 +116,10 @@ export function union(...members: ReadonlyArray<Rewrite>): Rewrite {
   return { node: "union", members };
 }
 
+export function intersection(...members: ReadonlyArray<Rewrite>): Rewrite {
+  return { node: "intersection", members };
+}
+
 // ---------------------------------------------------------------------------
 // A kind's declaration.
 // ---------------------------------------------------------------------------
@@ -148,7 +166,10 @@ export interface KindDeclarationInput {
  * module load: a relation declared twice, a `computed` naming a relation
  * the kind does not define, a `from` whose tupleset the kind does not
  * define (its `relation` is the PARENT's and is resolved at evaluation),
- * a derived rule for a relation the transcript does not declare.
+ * a derived rule for a relation the transcript does not declare, and a
+ * line no `.fga` file could hold without parentheses (a union inside an
+ * intersection or the reverse, an operator nested in itself, an operator
+ * over fewer than two members).
  */
 export function declareKind(input: KindDeclarationInput): KindDeclaration {
   const type = kindEnumName(input.kind);
@@ -157,6 +178,10 @@ export function declareKind(input: KindDeclarationInput): KindDeclaration {
     if (relations.has(name)) {
       throw new Error(`${input.source}: relation '${name}' is declared twice`);
     }
+    const shape = unwritableShape(rewrite);
+    if (shape !== undefined) {
+      throw new Error(`${input.source}: '${name}' ${shape}`);
+    }
     relations.set(name, rewrite);
   }
   for (const [name, rewrite] of relations) {
@@ -199,6 +224,7 @@ function localReferences(
     case "from":
       return [{ role: "tupleset", relation: rewrite.tupleset }];
     case "union":
+    case "intersection":
       return rewrite.members.flatMap(localReferences);
     default: {
       const exhaustive: never = rewrite;
@@ -206,3 +232,34 @@ function localReferences(
     }
   }
 }
+
+/**
+ * Why a line could not be written in a `.fga` file without parentheses,
+ * or undefined when it can: an operator's members are leaves (a direct
+ * list, a sibling relation, a tuple-to-userset), and there are at least
+ * two of them.
+ */
+function unwritableShape(rewrite: Rewrite): string | undefined {
+  switch (rewrite.node) {
+    case "this":
+    case "computed":
+    case "from":
+      return undefined;
+    case "union":
+    case "intersection": {
+      if (rewrite.members.length < 2) {
+        return `is ${rewrite.node === "union" ? "an or" : "an and"} over fewer than two members`;
+      }
+      const nested = rewrite.members.find(
+        (member) => member.node === "union" || member.node === "intersection",
+      );
+      return nested === undefined
+        ? undefined
+        : `nests ${nested.node === "union" ? "or" : "and"} inside ${rewrite.node === "union" ? "or" : "and"}, which a .fga line cannot say without parentheses`;
+    }
+    default: {
+      const exhaustive: never = rewrite;
+      throw new Error(`unknown rewrite node: ${JSON.stringify(exhaustive)}`);
+    }
+  }
+}

package/src/authorization/model/schedule.ts

@@ -3,7 +3,9 @@
  * definition, admin-owned like a blueprint and viewable by its owners and
  * explicit grantees. The sessions its fires create name it back through
  * `session#schedule`, a link the cloud writes and this edition does not
- * (session.ts); the schedule's own relations are unaffected.
+ * (session.ts); the schedule's own relations are unaffected. An explicit
+ * grant may name an Enterprise team (`team#member`), which no open-source
+ * tuple ever does.
  */
 import { ScheduleSchema } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/api_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
@@ -15,6 +17,7 @@ import {
   from,
   objectOf,
   union,
+  usersetOf,
 } from "./rewrite.js";
 
 export const scheduleDeclaration = declareKind({
@@ -30,7 +33,13 @@ export const scheduleDeclaration = declareKind({
         from("admin", "organization"),
       ),
     ],
-    ["viewer", union(direct(objectOf("identity_account")), computed("owner"))],
+    [
+      "viewer",
+      union(
+        direct(objectOf("identity_account"), usersetOf("team", "member")),
+        computed("owner"),
+      ),
+    ],
     ["can_view", computed("viewer")],
     ["can_edit", computed("owner")],
     ["can_delete", computed("owner")],

package/src/authorization/model/skill.ts

@@ -3,7 +3,8 @@
  * `can_use` and `can_clone` rather than `can_execute`. Only `can_view`,
  * `can_edit`, `can_delete`, `can_grant_access` and `can_view_access` are
  * in the wire's IamPermission vocabulary; the others are the model's and
- * are carried so the transcript is the file.
+ * are carried so the transcript is the file. `team#member` on `viewer` is
+ * the Enterprise team grant, which no open-source tuple ever names.
  */
 import { SkillSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
@@ -42,6 +43,7 @@ export const skillDeclaration = declareKind({
           objectOf("identity_account"),
           usersetOf("organization", "member"),
           usersetOf("organization", "viewer"),
+          usersetOf("team", "member"),
         ),
         computed("owner"),
         computed("platform_viewer"),

package/src/authorization/model/workflow.ts

@@ -3,7 +3,8 @@
  * without `can_create_instance` (a workflow instance is created through
  * the workflow-instance lane, gated by the organization). Kept as its own
  * transcript, not a shared "blueprint" helper, so the file-by-file drift
- * compare sees exactly this file's lines.
+ * compare sees exactly this file's lines. `team#member` on `viewer` is the
+ * Enterprise team grant, which no open-source tuple ever names.
  */
 import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
@@ -42,6 +43,7 @@ export const workflowDeclaration = declareKind({
           objectOf("identity_account"),
           usersetOf("organization", "member"),
           usersetOf("organization", "viewer"),
+          usersetOf("team", "member"),
         ),
         computed("owner"),
         computed("platform_viewer"),

package/src/authorization/model/workflow_execution.ts

@@ -6,7 +6,8 @@
  * audience through `execution_viewer from workflow_instance`, standing on
  * the `workflow_instance` link the derivation writes from
  * `spec.workflow_instance_id`. No `can_delete`: run history outlives its
- * instance by design.
+ * instance by design. The per-run grant may name an Enterprise team
+ * (`team#member`), which no open-source tuple ever does.
  */
 import { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
@@ -18,6 +19,7 @@ import {
   from,
   objectOf,
   union,
+  usersetOf,
 } from "./rewrite.js";
 
 export const workflowExecutionDeclaration = declareKind({
@@ -31,7 +33,7 @@ export const workflowExecutionDeclaration = declareKind({
     [
       "viewer",
       union(
-        direct(objectOf("identity_account")),
+        direct(objectOf("identity_account"), usersetOf("team", "member")),
         computed("owner"),
         from("execution_viewer", "workflow_instance"),
       ),

package/src/authorization/model/workflow_instance.ts

@@ -14,6 +14,10 @@
  * admits — and `private` or unset derives nothing, so each run stays its
  * triggerer's. The cloud has no writer for this tuple today; this
  * edition enforces the field as the contract states it.
+ *
+ * `team#member` on `viewer` is the Enterprise team grant, which no
+ * open-source tuple ever names; `execution_viewer` is not a grantable role
+ * and admits no team.
  */
 import { isMessage } from "@bufbuild/protobuf";
 
@@ -85,6 +89,7 @@ export const workflowInstanceDeclaration = declareKind({
           objectOf("identity_account"),
           usersetOf("organization", "member"),
           usersetOf("organization", "viewer"),
+          usersetOf("team", "member"),
         ),
         computed("owner"),
         from("viewer", "default_of"),

package/src/boot/__tests__/list-indexes.test.ts

@@ -0,0 +1,65 @@
+/**
+ * Pins the list-indexed surface (list-indexes.ts). The table below is
+ * every declaration's keys against its revision: a store trusts a row's
+ * facts only under the revision they were derived with, so a change to a
+ * declaration's keys without a new revision would read rows written under
+ * the old keys as if they carried the new ones. Changing a declaration
+ * therefore fails here until its revision is bumped and this table is
+ * updated in the same change.
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+  ListIndexRegistry,
+  listIndexFingerprint,
+} from "../../store/list-index.js";
+import { LIST_INDEXES } from "../list-indexes.js";
+
+const PINNED: Readonly<
+  Record<string, { revision: number; fingerprint: string }>
+> = {
+  agent_execution: {
+    revision: 1,
+    fingerprint: "agent_execution{session=field:spec.session_id}",
+  },
+  artifact: {
+    revision: 1,
+    fingerprint:
+      "artifact{agent_execution=field:spec.source.agent_execution_id,workflow_execution=field:spec.source.workflow_execution_id}",
+  },
+  session: {
+    revision: 1,
+    fingerprint:
+      "session{agent_instance=field:spec.agent_instance_id,channel=label:stigmer.ai/channel-id}",
+  },
+  workflow_execution: {
+    revision: 1,
+    fingerprint:
+      "workflow_execution{workflow=field:spec.workflow_id,workflow_instance=field:spec.workflow_instance_id}",
+  },
+};
+
+describe("the list-indexed surface", () => {
+  it("opens as one registry: no kind declared twice", () => {
+    expect(() => new ListIndexRegistry(LIST_INDEXES)).not.toThrow();
+  });
+
+  it("declares exactly the pinned kinds", () => {
+    const kinds = LIST_INDEXES.map(
+      (d) => listIndexFingerprint(d).split("{")[0],
+    );
+    expect(kinds.sort()).toEqual(Object.keys(PINNED).sort());
+  });
+
+  it.each(LIST_INDEXES.map((d) => [listIndexFingerprint(d), d] as const))(
+    "%s carries the revision its keys are pinned to",
+    (fingerprint, declaration) => {
+      const kind = fingerprint.split("{")[0] ?? "";
+      const pinned = PINNED[kind];
+      expect(
+        { revision: declaration.revision, fingerprint },
+        "a declaration's keys changed: bump its revision and update this table together",
+      ).toEqual(pinned);
+    },
+  );
+});

package/src/boot/compose.ts

@@ -213,6 +213,7 @@ import { registerExtensionServicesUnshadowed } from "./route-shadowing.js";
 import type { ServerConfig } from "./config.js";
 import { createInProcessClients } from "./inprocess.js";
 import type { InProcessClients } from "./inprocess.js";
+import { LIST_INDEXES } from "./list-indexes.js";
 import type { Logger } from "./logger.js";
 
 export interface ComposedServer {
@@ -336,20 +337,22 @@ export async function composeServer(
   }
   // Stage: storage — the driver selection seam (DD-010): DATABASE_URL
   // present → Postgres (async connect + advisory-locked migrations), else
-  // sqlite on DB_PATH (migrations v1–v7, incl. adopting a Go-created
+  // sqlite on DB_PATH (its whole chain, incl. adopting a Go-created
   // database — D2 §3 schema continuity). Postgres wins when both are set:
   // DB_PATH always has a default value, so no other precedence could ever
-  // select Postgres (config.ts documents the contract). A failure here is
-  // a loud boot throw, never a degraded server. The operator identity
-  // (#400) is installed by main.ts — once per PROCESS, before any writer
-  // exists — not here: composeServer is re-entrant for tests, the
-  // identity seam deliberately is not.
+  // select Postgres (config.ts documents the contract). Either driver
+  // opens with the list indexes (list-indexes.ts) and reconciles them
+  // before it returns. A failure here is a loud boot throw, never a
+  // degraded server. The operator identity (#400) is installed by main.ts
+  // — once per PROCESS, before any writer exists — not here: composeServer
+  // is re-entrant for tests, the identity seam deliberately is not.
   let store: Store;
+  const storeOptions = { listIndexes: LIST_INDEXES };
   if (config.databaseUrl !== "") {
-    store = await PostgresStore.open(config.databaseUrl, logger);
+    store = await PostgresStore.open(config.databaseUrl, logger, storeOptions);
     logger.info("storage driver selected", { driver: "postgres" });
   } else {
-    store = SqliteStore.open(config.dbPath, logger);
+    store = SqliteStore.open(config.dbPath, logger, storeOptions);
     logger.info("storage driver selected", {
       driver: "sqlite",
       dbPath: config.dbPath,
@@ -1020,7 +1023,10 @@ export async function composeServer(
           reserve: (key, declaredSizeBytes) => {
             const { ttlMs } = skillUploadSlots.reserve(key, declaredSizeBytes);
             return {
-              url: skillUploadUrl(config.skillTransferBaseUrl, uploadRefOf(key)),
+              url: skillUploadUrl(
+                config.skillTransferBaseUrl,
+                uploadRefOf(key),
+              ),
               ttlMs,
             };
           },
@@ -1196,9 +1202,12 @@ export async function composeServer(
     case "configured":
       break;
     case "derived":
-      logger.info("STIGMER_OAUTH_REDIRECT_URI is not set — deriving the served console's callback for MCP server OAuth Connect", {
-        redirectUri: oauthRedirect.uri,
-      });
+      logger.info(
+        "STIGMER_OAUTH_REDIRECT_URI is not set — deriving the served console's callback for MCP server OAuth Connect",
+        {
+          redirectUri: oauthRedirect.uri,
+        },
+      );
       break;
     case "absent":
       logger.warn(
@@ -1210,7 +1219,8 @@ export async function composeServer(
       throw new Error(String(exhaustive));
     }
   }
-  const oauthRedirectUri = oauthRedirect.kind === "absent" ? "" : oauthRedirect.uri;
+  const oauthRedirectUri =
+    oauthRedirect.kind === "absent" ? "" : oauthRedirect.uri;
   // The ONE fetch the McpServer domain dials user-supplied URLs with: the
   // endpoint it probes at save time and the login server it reaches on
   // Sign in. Every hop is judged under the edition's egress policy
@@ -1299,6 +1309,8 @@ export async function composeServer(
       grantScope:
         extensions.drivers.policyGrantScope ?? newOrganizationOnlyGrantScope(),
       queries: extensions.drivers.authorizationQueries,
+      principalDisplay: extensions.drivers.principalDisplay,
+      gateSteps: extensions.gateSteps,
       edition: extensions.edition,
       logger,
     });

package/src/boot/list-indexes.ts

@@ -0,0 +1,25 @@
+/**
+ * The whole list-indexed surface, one explicit list (the search
+ * registry's composition-root idiom, query/search/registry.ts; house rule:
+ * no import side effects). The store is opened with it
+ * (`StoreOpenOptions.listIndexes`), keeps a declared kind's facts on every
+ * write, and refuses a read through a declaration it was not opened with,
+ * so a lane that reads an index and this list cannot disagree silently.
+ *
+ * A kind joins when a lane needs to read one organization's or one
+ * parent's rows without decoding the whole kind; the kinds here were
+ * chosen on the hosted edition's row counts and sizes (2026-09-23: every
+ * other org-scoped kind held under a hundred rows and a hundred kilobytes).
+ */
+import { agentExecutionListIndex } from "../domain/agentexecution/list-index.js";
+import { artifactListIndex } from "../domain/artifact/list-index.js";
+import { sessionListIndex } from "../domain/session/list-index.js";
+import { workflowExecutionListIndex } from "../domain/workflowexecution/list-index.js";
+import type { ListIndexDeclaration } from "../store/list-index.js";
+
+export const LIST_INDEXES: ReadonlyArray<ListIndexDeclaration> = [
+  agentExecutionListIndex,
+  artifactListIndex,
+  sessionListIndex,
+  workflowExecutionListIndex,
+];

package/src/domain/agentexecution/__tests__/agentexecution.test.ts

@@ -12,8 +12,9 @@
  *     byte-for-byte (sub-project DD-001: faithful-port + OSS issue);
  *   - getAgentUsageReport org scoping (oss#389) incl. the no-name-oracle
  *     rule (Go get_agent_usage_report_test.go case-for-case);
- *   - list/listBySession filter semantics over seeded rows and the
- *     total_pages placeholder;
+ *   - list/listBySession filter semantics over seeded rows; list's cursor
+ *     pages (newest created first, one organization, a token refused on
+ *     another request) and listBySession returning its parent whole;
  *   - update's status-clearing standard build and delete's audit-trail
  *     return, over the wire;
  *   - the populated getExecutionSummary arm (phase counts, active count,
@@ -28,6 +29,7 @@ import path from "node:path";
 
 import { create, fromBinary } from "@bufbuild/protobuf";
 import type { MessageInitShape } from "@bufbuild/protobuf";
+import { timestampFromMs } from "@bufbuild/protobuf/wkt";
 import { Code, ConnectError, createClient } from "@connectrpc/connect";
 import type { Client, Transport } from "@connectrpc/connect";
 import { createGrpcTransport } from "@connectrpc/connect-node";
@@ -146,6 +148,7 @@ function seedInput(overrides?: {
   phase?: ExecutionPhase;
   startedAt?: string;
   completedAt?: string;
+  createdAtMs?: number;
 }): MessageInitShape<typeof AgentExecutionSchema> & {
   metadata: { id: string };
 } {
@@ -170,6 +173,12 @@ function seedInput(overrides?: {
       phase: overrides?.phase ?? ExecutionPhase.EXECUTION_COMPLETED,
       startedAt: overrides?.startedAt ?? "",
       completedAt: overrides?.completedAt ?? "",
+      audit:
+        overrides?.createdAtMs === undefined
+          ? undefined
+          : {
+              specAudit: { createdAt: timestampFromMs(overrides.createdAtMs) },
+            },
     },
   };
 }
@@ -322,7 +331,7 @@ describe("get / list / listBySession over the wire", () => {
     expect(got.spec?.message).toBe("Say hello.");
   });
 
-  it("list returns every row with the total_pages placeholder, filtered by phase on request", async () => {
+  it("list with no page_size returns every row whole (total_pages 1), filtered by phase on request", async () => {
     const completed = await seed(
       seedInput({ phase: ExecutionPhase.EXECUTION_COMPLETED }),
     );
@@ -359,6 +368,79 @@ describe("get / list / listBySession over the wire", () => {
     expect(ids).toContain(inSession);
     expect(ids).not.toContain(outOfSession);
   });
+
+  it("list pages one organization newest created first, with a token until the last page", async () => {
+    const org = "paging-org";
+    const base = Date.parse("2026-09-01T00:00:00Z");
+    const newestFirst: string[] = [];
+    for (let i = 0; i < 5; i++) {
+      newestFirst.unshift(
+        await seed(seedInput({ org, createdAtMs: base + i * 1000 })),
+      );
+    }
+    await seed(seedInput({ org: "other-org", createdAtMs: base + 10_000 }));
+
+    const walked: string[] = [];
+    let pageToken = "";
+    do {
+      const page = await query.list({ org, pageSize: 2, pageToken });
+      expect(page.entries.length).toBeLessThanOrEqual(2);
+      expect(page.totalPages).toBe(page.nextPageToken === "" ? 1 : 0);
+      walked.push(...page.entries.map((e) => e.metadata!.id));
+      pageToken = page.nextPageToken;
+    } while (pageToken !== "");
+
+    expect(walked).toEqual(newestFirst);
+  });
+
+  it("list refuses a page_token issued for another request, and a negative page_size", async () => {
+    const org = "token-org";
+    await seed(
+      seedInput({ org, createdAtMs: Date.parse("2026-09-02T00:00:00Z") }),
+    );
+    await seed(
+      seedInput({ org, createdAtMs: Date.parse("2026-09-02T00:00:01Z") }),
+    );
+    const first = await query.list({ org, pageSize: 1 });
+    expect(first.nextPageToken).not.toBe("");
+
+    const replayed = await expectCode(
+      () =>
+        query.list({
+          org,
+          phase: ExecutionPhase.EXECUTION_FAILED,
+          pageSize: 1,
+          pageToken: first.nextPageToken,
+        }),
+      Code.InvalidArgument,
+    );
+    expect(replayed.rawMessage).toBe(
+      "page_token was issued for a different request",
+    );
+    await expectCode(
+      () => query.list({ org, pageToken: "not-a-token" }),
+      Code.InvalidArgument,
+    );
+    await expectCode(
+      () => query.list({ org, pageSize: -1 }),
+      Code.InvalidArgument,
+    );
+  });
+
+  it("listBySession returns the session's executions whole, whatever page_size says", async () => {
+    const ids = new Set<string>();
+    for (let i = 0; i < 3; i++) {
+      ids.add(await seed(seedInput({ sessionId: "ses_whole" })));
+    }
+
+    const result = await query.listBySession({
+      sessionId: "ses_whole",
+      pageSize: 1,
+    });
+    expect(new Set(result.entries.map((e) => e.metadata!.id))).toEqual(ids);
+    expect(result.nextPageToken).toBe("");
+    expect(result.totalPages).toBe(1);
+  });
 });
 
 describe("update / delete over the wire", () => {

package/src/domain/agentexecution/controller.ts

@@ -128,10 +128,8 @@ import { newValidateVisibilityStep } from "../../pipeline/steps/validate-visibil
 import { newBuildNewStateStep } from "../../pipeline/steps/defaults.js";
 import {
   EXECUTION_LIST_KEY,
-  newApplyPhaseFilterStep,
   newBuildExecutionListResponseStep,
-  newQueryAllExecutionsStep,
-  newRestrictByReadScopeStep,
+  newQueryExecutionPageStep,
   newQueryExecutionsBySessionStep,
   newValidateListBySessionRequestStep,
   newValidateListRequestStep,
@@ -527,9 +525,9 @@ async function get(
 }
 
 /**
- * List — list.go: full scan, optional phase filter, no sorting, no
- * pagination (total_pages placeholder 1); the request org field is a
- * deliberate no-op on this single-tenant edition.
+ * List — list.go: one page of the request's org (or every org), newest
+ * first, the optional phase filter and the read scope per batch
+ * (steps.ts, QueryExecutionPage).
  */
 async function list(
   deps: AgentExecutionControllerDeps,
@@ -553,16 +551,16 @@ async function list(
       ),
     )
     .addStep(newValidateListRequestStep())
-    .addStep(newQueryAllExecutionsStep(deps.store, deps.logger))
-    .addStep(newApplyPhaseFilterStep(deps.logger))
-    .addStep(newRestrictByReadScopeStep(deps.listReadScope))
+    .addStep(
+      newQueryExecutionPageStep(deps.store, deps.logger, deps.listReadScope),
+    )
     .addStep(newBuildExecutionListResponseStep())
     .build()
     .execute(reqCtx);
   return requireListResult(reqCtx.get(EXECUTION_LIST_KEY));
 }
 
-/** ListBySession — list_by_session.go: spec.session_id equality filter. */
+/** ListBySession — list_by_session.go: the session's executions, whole, newest first. */
 async function listBySession(
   deps: AgentExecutionControllerDeps,
   req: ListAgentExecutionsBySessionRequest,

package/src/domain/agentexecution/list-index.ts

@@ -0,0 +1,24 @@
+/**
+ * The agent-execution list index (store/list-index.ts): the kind whose
+ * rows are the fattest in the store (every message and tool call of a run
+ * rides the row), so a lane that decodes the whole kind to keep one
+ * session's runs pays for every run on the platform. `session` is the key
+ * `listBySession` reads; the organization and the creation order are
+ * every declaration's.
+ *
+ * A change to `keys` bumps `revision` (boot/__tests__/list-indexes.test.ts
+ * pins the pair).
+ */
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { declareListIndex, field } from "../../store/list-index.js";
+
+export const agentExecutionListIndex = declareListIndex({
+  kind: ApiResourceKind.agent_execution,
+  schema: AgentExecutionSchema,
+  revision: 1,
+  keys: {
+    session: field("spec.session_id"),
+  },
+});