@stigmer/server 3.25.0 → 3.27.0

package/src/domain/workflowexecution/queries.ts

@@ -1,48 +1,159 @@
 /**
- * Shared full-scan load for the workflowexecution read surfaces (list,
- * listByWorkflow, getExecutionSummary, listPendingApprovals) — Go's
- * store.ListResources + proto.Unmarshal-continue loop, where malformed
- * rows are skipped rather than failing the read.
+ * The workflowexecution read surfaces' shared reads (list,
+ * listByWorkflow, getExecutionSummary, listPendingApprovals), all through
+ * the list index (list-index.ts beside this file; the store's contract in
+ * store/interface.ts) — the request's org or workflow key narrows in the
+ * store, newest created first. Malformed rows are skipped rather than
+ * failing the read, Go's proto.Unmarshal-continue loop.
+ *
+ * The two lists share one reader: the default order pages
+ * (pipeline/steps/list-page.ts), with the lane's filters and then the read
+ * scope on each batch; another sort field sorts the whole matching set and
+ * returns its first page_size entries with no token, because only the
+ * creation order is an index order.
  */
-import { fromBinary } from "@bufbuild/protobuf";
+import { create, fromBinary } from "@bufbuild/protobuf";
 
 import type { WorkflowExecution } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
 import { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import {
+  ExecutionSortField,
+  WorkflowExecutionListSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import type { WorkflowExecutionList } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 
 import type { Logger } from "../../boot/logger.js";
-import { internalError } from "../../pipeline/errors.js";
+import type { CallerIdentity } from "../../extensions/identity.js";
+import type { ListReadScope } from "../../extensions/list-read-scope.js";
+import { restrictListByReadScope } from "../../extensions/list-read-scope.js";
+import { internalError, invalidArgumentError } from "../../pipeline/errors.js";
+import {
+  LIST_PAGE_MAX_SIZE,
+  listPageFingerprint,
+  readListPage,
+} from "../../pipeline/steps/list-page.js";
+import type { ListPageRequest } from "../../pipeline/steps/list-page.js";
 import type { Store } from "../../store/interface.js";
+import type { ListIndexQuery, ListIndexRow } from "../../store/list-index.js";
+import { applySortField } from "./execution-filter.js";
+import { workflowExecutionListIndex } from "./list-index.js";
+
+/** The keys the workflow-execution index declares. */
+export type WorkflowExecutionListKey = "workflow" | "workflow_instance";
+
+/** A stored row, or undefined (logged) when it does not decode. */
+export function decodeWorkflowExecution(
+  data: Uint8Array,
+  logger: Logger,
+): WorkflowExecution | undefined {
+  try {
+    return fromBinary(WorkflowExecutionSchema, data);
+  } catch (error) {
+    logger.warn("Failed to unmarshal workflow execution, skipping", {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return undefined;
+  }
+}
 
 /**
- * Loads every workflow execution. The Internal message varies by caller in
- * Go (each handler wraps the same store error with its own text), so the
- * caller supplies it.
+ * Every workflow execution the query matches, newest created first. The
+ * Internal message varies by caller in Go (each handler wraps the same
+ * store error with its own text), so the caller supplies it.
  */
-export async function loadAllWorkflowExecutions(
+export async function loadWorkflowExecutions(
   store: Store,
   logger: Logger,
+  query: ListIndexQuery<WorkflowExecutionListKey>,
   internalMessage: string,
 ): Promise<WorkflowExecution[]> {
-  let rows: Uint8Array[];
+  let rows: ListIndexRow[];
   try {
-    rows = await store.listResources(ApiResourceKind.workflow_execution);
+    rows = await store.queryResources(workflowExecutionListIndex, query);
   } catch (error) {
     throw internalError(error, internalMessage);
   }
-
   const executions: WorkflowExecution[] = [];
-  for (const data of rows) {
-    let execution: WorkflowExecution;
-    try {
-      execution = fromBinary(WorkflowExecutionSchema, data);
-    } catch (error) {
-      logger.warn("Failed to unmarshal workflow execution, skipping", {
-        error: error instanceof Error ? error.message : String(error),
-      });
-      continue;
+  for (const row of rows) {
+    const execution = decodeWorkflowExecution(row.data, logger);
+    if (execution !== undefined) {
+      executions.push(execution);
     }
-    executions.push(execution);
   }
   return executions;
 }
+
+export interface WorkflowExecutionListRead {
+  readonly store: Store;
+  readonly logger: Logger;
+  readonly listReadScope: ListReadScope | undefined;
+  readonly identity: CallerIdentity;
+  readonly query: ListIndexQuery<WorkflowExecutionListKey>;
+  readonly request: ListPageRequest;
+  readonly sortField: ExecutionSortField;
+  readonly sortAscending: boolean;
+  /** The lane's filters beyond the indexed predicates. */
+  readonly keep: (execution: WorkflowExecution) => boolean;
+  /** The request's other fields, which its token is bound to. */
+  readonly fingerprint: Readonly<Record<string, unknown>>;
+}
+
+/** One list response: a page in the default order, or the whole set sorted by another field. */
+export async function readWorkflowExecutionList(
+  read: WorkflowExecutionListRead,
+): Promise<WorkflowExecutionList> {
+  const scope = (
+    executions: WorkflowExecution[],
+  ): Promise<WorkflowExecution[]> =>
+    restrictListByReadScope(
+      read.listReadScope,
+      read.identity,
+      ApiResourceKind.workflow_execution,
+      executions,
+      "",
+    );
+
+  if (read.sortField === ExecutionSortField.UNSPECIFIED) {
+    const page = await readListPage({
+      store: read.store,
+      declaration: workflowExecutionListIndex,
+      query: read.query,
+      request: read.request,
+      fingerprint: listPageFingerprint(read.fingerprint),
+      decode: (data) => decodeWorkflowExecution(data, read.logger),
+      keep: read.keep,
+      scope,
+      failure: "failed to list workflow executions",
+    });
+    return create(WorkflowExecutionListSchema, {
+      entries: page.entries,
+      nextPageToken: page.nextPageToken,
+      totalPages: page.nextPageToken === "" ? 1 : 0,
+    });
+  }
+
+  // Another sort field never issues a token, so none can be continued.
+  if (read.request.pageToken !== "") {
+    throw invalidArgumentError("invalid page_token");
+  }
+  if (read.request.pageSize < 0) {
+    throw invalidArgumentError("page_size must not be negative");
+  }
+  const executions = await scope(
+    (
+      await loadWorkflowExecutions(
+        read.store,
+        read.logger,
+        read.query,
+        "failed to list workflow executions",
+      )
+    ).filter(read.keep),
+  );
+  applySortField(executions, read.sortField, read.sortAscending);
+  const size = Math.min(read.request.pageSize, LIST_PAGE_MAX_SIZE);
+  return create(WorkflowExecutionListSchema, {
+    entries: size === 0 ? executions : executions.slice(0, size),
+    totalPages: 1,
+  });
+}

package/src/extensions/__tests__/iam-policy-points.test.ts

@@ -15,6 +15,9 @@
  *     contextual checkMyPermission refuse UNIMPLEMENTED with the edition
  *     reason (the domain suite pins the refusal; this file pins the
  *     registry);
+ *   - `drivers.principalDisplay` — how an access list names a grantee
+ *     that is not a person (a team); single instance; absent = the id
+ *     fallback shape;
  *   - `ResourceAuthorizationLifecycle` gains the OPTIONAL `onPolicyGranted`
  *     and `onPolicyRevoked` (Q7 i): a unit's lifecycle that carries them
  *     resolves through the existing single-instance point with both hooks
@@ -26,6 +29,7 @@ import { describe, expect, it } from "vitest";
 import type { IamPolicyStore } from "../../domain/iampolicy/store.js";
 import type { AuthorizationQueryEngine } from "../authorization-queries.js";
 import type { PolicyGrantScope } from "../policy-grant-scope.js";
+import type { PrincipalDisplay } from "../principal-display.js";
 import { resolveExtensions } from "../registry.js";
 import type { ResourceAuthorizationLifecycle } from "../resource-authorization.js";
 
@@ -125,6 +129,32 @@ describe("the authorizationQueries capability point", () => {
   });
 });
 
+describe("the principalDisplay driver point", () => {
+  const display: PrincipalDisplay = { resolve: unimplemented };
+
+  it("is undefined with no extensions — a non-person grantee renders by its id", () => {
+    expect(resolveExtensions([]).drivers.principalDisplay).toBeUndefined();
+  });
+
+  it("carries the one registered instance through", () => {
+    const resolved = resolveExtensions([
+      { name: "cloud-iam", drivers: { principalDisplay: display } },
+    ]);
+    expect(resolved.drivers.principalDisplay).toBe(display);
+  });
+
+  it("throws on a second registration, naming both units", () => {
+    expect(() =>
+      resolveExtensions([
+        { name: "display-a", drivers: { principalDisplay: display } },
+        { name: "display-b", drivers: { principalDisplay: display } },
+      ]),
+    ).toThrowError(
+      /extension 'display-b' registers a PrincipalDisplay, but 'display-a' already did/,
+    );
+  });
+});
+
 describe("the widened ResourceAuthorizationLifecycle contract", () => {
   const resourceHooks = {
     onResourceCreated: unimplemented,

package/src/extensions/__tests__/registry.test.ts

@@ -480,6 +480,9 @@ describe("resolveExtensions — loud-fail throws (DD-006 §2b)", () => {
       "agent-execution-create:pre-side-effect-gate",
       "agent-execution-recover:pre-side-effect-gate",
       "agent-execution-submit-approval:gate",
+      // The eighth: the IamPolicy create chain before the write, where an
+      // edition that serves teams refuses a team it cannot admit.
+      "iam-policy-create:pre-side-effect-gate",
       // 20260911.11 Q-IA-9: the seventh ratified slot — after the account
       // persists inside provisionMyAccount, before the reply (the cloud's
       // personal-organization ensure and backfill ride it).

package/src/extensions/drivers.ts

@@ -31,6 +31,9 @@
  *     port, which kinds an edition grants on, and the tuple-half query
  *     engine only an authorization backend can answer) — landed with
  *     20260913.01, gate ruling Q-OR-10
+ *   - principal display (how an access list names a grantee that is not
+ *     a person: a team, in the editions that serve teams) — landed with
+ *     the Team kind
  *   - outbound egress (which addresses the control plane may dial when
  *     it reaches a URL a user supplied: the MCP endpoint it probes at save
  *     time and the login server it reaches on Sign in) — landed with the
@@ -70,6 +73,7 @@ import type { OutboundEgressPolicy } from "./outbound-egress.js";
 import type { ListReadScope } from "./list-read-scope.js";
 import type { OrganizationDirectory } from "./organization-directory.js";
 import type { PolicyGrantScope } from "./policy-grant-scope.js";
+import type { PrincipalDisplay } from "./principal-display.js";
 import type { ResourceAuthorizationLifecycle } from "./resource-authorization.js";
 import type { ScheduleFireCallerMint } from "./schedule-fire-caller.js";
 
@@ -233,6 +237,14 @@ export interface ExtensionDrivers {
    * with the edition reason — the identityFederation absent shape.
    */
   readonly authorizationQueries?: AuthorizationQueryEngine;
+  /**
+   * The principal display (single-instance point): how an access list
+   * names a grantee that is not a person — a team, in the editions that
+   * serve teams (extensions/principal-display.ts carries the contract).
+   * When absent, such a grantee renders by its id, the fallback shape
+   * every access list has always had.
+   */
+  readonly principalDisplay?: PrincipalDisplay;
   /**
    * The license-status provider (single-instance point): what license
    * this server holds, answered by PlatformQueryController.getLicenseStatus

package/src/extensions/gate-slots.ts

@@ -34,6 +34,15 @@
  * Non-transactional in the `org-create:post-persist` sense: a gate
  * failure fails the request, the row survives, the next call heals.
  *
+ * The eighth, `iam-policy-create:pre-side-effect-gate`: the IamPolicy
+ * `create` chain (the user grant lane), after ValidateGrantableRole and
+ * before Grant, so nothing is written when a gate refuses. It exists for
+ * the checks a grant needs that take a read, which the synchronous grant
+ * scope may not make: the Enterprise and Cloud editions refuse a team
+ * that does not exist, a team of another organization than the granted
+ * resource, and a team member who is not one of the organization's
+ * viewers. Never on `bootstrapPolicy`, the platform's structural lane.
+ *
  * Two enforcement layers, deliberately redundant, both derived from the
  * ONE literal tuple below (lockstep by construction):
  *   - GateSlotName (compile time): the union of declared slot literals.
@@ -71,6 +80,7 @@ export const GATE_SLOT_NAMES = [
   "org-create:post-persist",
   "sandbox-acquisition:gate",
   "identity-account-provision:post-persist",
+  "iam-policy-create:pre-side-effect-gate",
 ] as const;
 
 /** The declared slot-name union — a registration outside it fails tsc. */

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

@@ -81,18 +81,15 @@
  *     driver's cost is proportional to the candidates offered (the cloud
  *     checks each one against its authorization engine), and the whole
  *     kind across every tenant is what rolled back on 2026-09-14; the
- *     request's org is tens of rows. Two idioms carry the rule and both
- *     keep their reason: a lane whose Go/Java contract org-narrows in
- *     BOTH editions (environment, memory, schedule, agent-instance,
- *     agent-share and agent-channel lists; the getBy* parent filters)
- *     applies its own filter ABOVE the helper call and passes `""`; a lane
- *     whose contract is cross-org on OSS (`agentExecution.list`,
- *     `workflowExecution.list`, `listPendingApprovals`) hands the request
- *     org to the helper, which applies it before the scope ONLY when a
- *     scope is composed — a scope-less server still returns the input
- *     untouched with the org unconsulted (the first line above). Two lanes
- *     have no org on the wire (`session.list`, `apiKey.findAll`) and offer
- *     the kind until P1 entry 12 pages them.
+ *     request's org is tens of rows. The lanes over the session, execution
+ *     and artifact kinds narrow by the request's org or parent in the
+ *     store's indexed read (store/list-index.ts; every posture honours the
+ *     request) and page there (pipeline/steps/list-page.ts, one batch per
+ *     scope call), passing `""`; the small org-scoped lists (environment,
+ *     memory, schedule, agent-instance, agent-share and agent-channel; the
+ *     getBy* parent filters) apply their own filter above the helper call
+ *     and pass `""` too. `apiKey.findAll` has no org on the wire and offers
+ *     the kind: a few rows per person.
  *   - A KIND WHOSE AUTHORIZATION IS ITS PARENT'S CARRIES THAT PARENT ON
  *     EVERY CANDIDATE (stigmer-cloud 20260913.04 T04, Q-LB-33..36). When
  *     `kind_meta` declares PARENT scope with INHERITED owner

package/src/extensions/principal-display.ts

@@ -0,0 +1,37 @@
+/**
+ * The principal-display driver point: how an access list names a grantee
+ * that is not a person. Single instance, registered as
+ * `drivers.principalDisplay`.
+ *
+ * An access list ("who has access to this agent, with which roles") names
+ * every grantee. People are resolved by the core from the identity-account
+ * port (domain/iampolicy/display-resolver.ts), the same in every edition.
+ * A grantee of another kind — a team, in the Enterprise and Cloud editions
+ * — lives in a store only that edition holds, so its name comes from this
+ * point. Absent (open source, which grants to no team), such a grantee
+ * renders in the fallback shape the access list has always used: its kind,
+ * with its id standing in as its name.
+ *
+ * The contract:
+ *   - It answers for the ids it knows and omits the rest; an omitted id
+ *     takes the fallback shape, never an error (a team deleted between
+ *     the grant read and this call is an omission, not a fault).
+ *   - It is never asked about the identity account; the core owns people.
+ *   - A fault it cannot answer through THROWS (the ListReadScope rule:
+ *     an empty answer is a real answer, never an outage in disguise), and
+ *     the list RPC fails with it.
+ */
+import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { ApiResourceRefView } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/io_pb";
+
+/** The principal-display contract (single-instance point, ExtensionDrivers.principalDisplay). */
+export interface PrincipalDisplay {
+  /**
+   * Display views for the principals of `kind` with these ids, keyed by
+   * id; ids it does not know are absent from the map.
+   */
+  resolve(
+    kind: ApiResourceKind,
+    ids: ReadonlyArray<string>,
+  ): Promise<ReadonlyMap<string, ApiResourceRefView>>;
+}

package/src/extensions/registry.ts

@@ -60,6 +60,7 @@ import type { LicenseStatusProvider } from "./license-status.js";
 import type { OutboundEgressPolicy } from "./outbound-egress.js";
 import type { ListReadScope } from "./list-read-scope.js";
 import type { PolicyGrantScope } from "./policy-grant-scope.js";
+import type { PrincipalDisplay } from "./principal-display.js";
 import type { ModelCatalogProvider } from "../domain/workflow/registry/model-catalog-provider.js";
 import type { VisitorErrorPolicy } from "../pipeline/interceptors/error-boundary.js";
 import type { PipelineStep } from "../pipeline/pipeline.js";
@@ -288,6 +289,11 @@ export interface ResolvedExtensionDrivers {
    * tuple-half RPC arms refuse UNIMPLEMENTED with the edition reason.
    */
   readonly authorizationQueries: AuthorizationQueryEngine | undefined;
+  /**
+   * The principal display — undefined = an access list names a grantee
+   * that is not a person by its id (the fallback shape).
+   */
+  readonly principalDisplay: PrincipalDisplay | undefined;
   /**
    * The license-status provider — undefined = compose.ts installs the
    * built-in `absent` answer, so every edition serves getLicenseStatus.
@@ -367,6 +373,8 @@ export function resolveExtensions(
   let policyGrantScopeDeclaredBy: string | undefined;
   let authorizationQueries: AuthorizationQueryEngine | undefined;
   let authorizationQueriesDeclaredBy: string | undefined;
+  let principalDisplay: PrincipalDisplay | undefined;
+  let principalDisplayDeclaredBy: string | undefined;
   let licenseStatus: LicenseStatusProvider | undefined;
   let licenseStatusDeclaredBy: string | undefined;
   let outboundEgress: OutboundEgressPolicy | undefined;
@@ -568,6 +576,16 @@ export function resolveExtensions(
       authorizationQueriesDeclaredBy = unit.name;
     }
 
+    if (unit.drivers?.principalDisplay !== undefined) {
+      if (principalDisplayDeclaredBy !== undefined) {
+        throw new Error(
+          `extension '${unit.name}' registers a PrincipalDisplay, but '${principalDisplayDeclaredBy}' already did — exactly one may be composed`,
+        );
+      }
+      principalDisplay = unit.drivers.principalDisplay;
+      principalDisplayDeclaredBy = unit.name;
+    }
+
     if (unit.drivers?.licenseStatus !== undefined) {
       if (licenseStatusDeclaredBy !== undefined) {
         throw new Error(
@@ -748,6 +766,7 @@ export function resolveExtensions(
       iamPolicyStore,
       policyGrantScope,
       authorizationQueries,
+      principalDisplay,
       licenseStatus,
       outboundEgress,
       platformClientStore,

package/src/index.ts

@@ -164,6 +164,9 @@ export type {
 export { iamPolicyStoreContract } from "./domain/iampolicy/store-contract.js";
 export type { PolicyGrantScope } from "./extensions/policy-grant-scope.js";
 export type { AuthorizationQueryEngine } from "./extensions/authorization-queries.js";
+// How an access list names a grantee that is not a person
+// (drivers.principalDisplay): a team, in the editions that serve teams.
+export type { PrincipalDisplay } from "./extensions/principal-display.js";
 export type { IdentityFederation } from "./extensions/identity-federation.js";
 export type { AccountsBySubject } from "./domain/identityaccount/resolve.js";
 export { identityIdForSubject } from "./domain/identityaccount/resolve.js";
@@ -288,8 +291,14 @@ export { ScheduleFireCallerRefusedError } from "./extensions/schedule-fire-calle
 // through the REAL boundary mechanism, never a re-derivation.
 export type { VisitorErrorPolicy } from "./pipeline/interceptors/error-boundary.js";
 export { createErrorBoundaryInterceptor } from "./pipeline/interceptors/error-boundary.js";
+// The tuple lifecycle's resolution, for a kind a composition serves outside
+// the generic chains (a cloud-served create): `resolveResourceCreatedEvent`
+// derives the creation event from the kind's `kind_meta` exactly as the
+// shared CreateAuthorizationTuples step does, so the driver sees one shape
+// whichever chain created the row.
 export {
   diffVisibilityShapes,
+  resolveResourceCreatedEvent,
   visibilityShapesFor,
 } from "./pipeline/steps/authorization-tuples.js";
 
@@ -380,11 +389,20 @@ export { newResolveSlugStep } from "./pipeline/steps/slug.js";
 // The driver interfaces and the store-fault classes the ratified mapping
 // keys on (typed not-found → NotFound; anything else rethrows as an
 // infrastructure fault — the guidelines' instanceof idiom).
-export type { Store } from "./store/interface.js";
+export type { Store, StoreOpenOptions } from "./store/interface.js";
 export {
   AuditNotFoundError,
   ResourceNotFoundError,
 } from "./store/interface.js";
+// The list index's read shapes, which `Store.queryResources` speaks
+// (store/list-index.ts). Declaring an index stays internal: the list is
+// the composition root's (boot/list-indexes.ts), one per server.
+export type {
+  ListIndexCursor,
+  ListIndexDeclaration,
+  ListIndexQuery,
+  ListIndexRow,
+} from "./store/list-index.js";
 // The maintenance-surface row shape (20260830.04 Stage 1, ruling Q3):
 // what findResourcesRawOrderedAfter pages and what
 // replaceResourceDataIfUnchanged guards on — the secret-convergence

package/src/pipeline/apiresource-meta.ts

@@ -200,6 +200,27 @@ export function grantableRolesFor(
   return getOption(valueDesc, kind_meta).authorization?.grantableRoles ?? [];
 }
 
+/**
+ * The roles a TEAM may be granted on a resource of `kind` according to the
+ * contract — `kind_meta.authorization.team_grantable_roles`, a subset of
+ * `grantableRolesFor(kind)` (the subset is pinned by a test, never assumed
+ * here). Empty for every kind a team cannot be granted access to, and for
+ * `organization`, so an edition that grants only on organizations grants
+ * nothing to a team. Total, never a throw, for the same reason as
+ * `grantableRolesFor`.
+ */
+export function teamGrantableRolesFor(
+  kind: ApiResourceKind,
+): ReadonlyArray<IamRole> {
+  const valueDesc = kindValueDescriptor(kind);
+  if (valueDesc === undefined || !hasOption(valueDesc, kind_meta)) {
+    return [];
+  }
+  return (
+    getOption(valueDesc, kind_meta).authorization?.teamGrantableRoles ?? []
+  );
+}
+
 /**
  * Whether an edition serves a tier: the tier names the MINIMUM edition,
  * the editions are ordered oss < enterprise < cloud (each composes the