@stigmer/server 3.24.0 → 3.26.0

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

@@ -140,6 +140,7 @@ describe("every static (kind, permission) the served RPCs ask about is a declare
         "memory",
         "oauth_app",
         "organization",
+        "platform_client",
         "plugin",
         "schedule",
         "session",

package/src/authorization/authorizer.ts

@@ -78,10 +78,16 @@ import { formatObjectRef } from "./tuples.js";
 
 /**
  * Kinds whose missing row is a denial, never `not-found` (arm 4): the
- * cloud's `PROBE_EXEMPT_KINDS` restricted to the kinds this edition
- * serves — `platform`, `identity_provider`, `platform_client` and
- * `invitation` are refused by arm 2 before any row is asked about. The
- * cloud's drift test pins the two sets equal over the open-source tier.
+ * cloud's `PROBE_EXEMPT_KINDS` (stigmer-cloud
+ * src/authorizer/fga-authorizer.ts) restricted to the kinds this edition
+ * serves — `platform`, `identity_provider` and `invitation` are refused by
+ * arm 2 before any row is asked about. The cloud exempts them because
+ * 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
+ * `PROBE_EXEMPT_KINDS`, which is why this set is exported; a kind that
+ * moves into open source joins this set in the same change.
  *
  * `iam_policy` is reachable as a target through the IamPolicy RPCs' own
  * `resource.kind` (a caller may name it); the grant scope refuses such a
@@ -91,6 +97,7 @@ import { formatObjectRef } from "./tuples.js";
 export const NOT_FOUND_EXEMPT_KINDS: ReadonlySet<ApiResourceKind> = new Set([
   ApiResourceKind.identity_account,
   ApiResourceKind.iam_policy,
+  ApiResourceKind.platform_client,
 ]);
 
 /** The Java RequestAuthorizationService's pre-check copy, byte for byte (the cloud renders the same). */

package/src/authorization/model/__tests__/registry.test.ts

@@ -34,6 +34,7 @@ const DECLARED_KINDS = [
   ApiResourceKind.iam_policy,
   ApiResourceKind.api_key,
   ApiResourceKind.oauth_app,
+  ApiResourceKind.platform_client,
   ApiResourceKind.organization,
   ApiResourceKind.agent,
   ApiResourceKind.agent_channel,
@@ -94,6 +95,13 @@ const WIRE_PERMISSIONS_BY_TYPE: Readonly<
     "can_grant_access",
     "can_view_access",
   ],
+  platform_client: [
+    "can_view",
+    "can_edit",
+    "can_delete",
+    "can_grant_access",
+    "can_view_access",
+  ],
   organization: [
     "can_view",
     "can_edit",
@@ -262,7 +270,6 @@ describe("the built-in model's registry", () => {
     for (const unserved of [
       ApiResourceKind.platform,
       ApiResourceKind.identity_provider,
-      ApiResourceKind.platform_client,
       ApiResourceKind.invitation,
     ]) {
       expect(declarationFor(unserved), kindEnumName(unserved)).toBeUndefined();

package/src/authorization/model/index.ts

@@ -12,11 +12,11 @@
  * chain past the depth bound) and for the cloud's drift test, which
  * builds a model from the live `.fga` files and compares.
  *
- * Registered: every kind of the open-source tier — the twenty-three
- * `kind_meta.tier: open_source` members — and nothing else. The four
+ * Registered: every kind of the open-source tier — the twenty-four
+ * `kind_meta.tier: open_source` members — and nothing else. The three
  * files `fga.mod` lists that have no declaration here (`platform`,
- * `identity_provider`, `platform_client`, `invitation`) are kinds this
- * edition does not serve: a check that targets one is refused by the
+ * `identity_provider`, `invitation`) are kinds this edition does not
+ * serve: a check that targets one is refused by the
  * driver, and a tuple that names one (`identity_provider#platform_user`)
  * resolves to nobody. The registry test pins the list against the tier.
  */
@@ -38,6 +38,7 @@ import { mcpServerDeclaration } from "./mcp_server.js";
 import { memoryDeclaration } from "./memory.js";
 import { oauthAppDeclaration } from "./oauth_app.js";
 import { organizationDeclaration } from "./organization.js";
+import { platformClientDeclaration } from "./platform_client.js";
 import { pluginDeclaration } from "./plugin.js";
 import type { KindDeclaration } from "./rewrite.js";
 import { scheduleDeclaration } from "./schedule.js";
@@ -77,6 +78,7 @@ export const builtInModel: Model = newModel([
   iamPolicyDeclaration,
   apiKeyDeclaration,
   oauthAppDeclaration,
+  platformClientDeclaration,
   organizationDeclaration,
   agentDeclaration,
   agentChannelDeclaration,

package/src/authorization/model/oauth_app.ts

@@ -1,6 +1,7 @@
 /**
- * Transcript of fga/model/iam/oauth_app.fga — the one organization-scoped
- * kind whose `owner` has NO admin arm while its `viewer` does: the file's
+ * Transcript of fga/model/iam/oauth_app.fga — an organization-scoped kind
+ * whose `owner` has NO admin arm while its `viewer` does (platform_client
+ * shares the shape, for the same reason): the file's
  * "administrative visibility" for the organization's admins over a
  * registration that holds vendor client credentials, with change and
  * deletion the creator's (or an explicit grant's) alone, and no public

package/src/authorization/model/platform_client.ts

@@ -0,0 +1,43 @@
+/**
+ * Transcript of fga/model/iam/platform_client.fga — relation for relation
+ * the oauth_app shape: organization-scoped, an `owner` with no admin arm
+ * and a `viewer` that has one. A platform client holds credential material,
+ * so the model is restricted: its creator (the owner) edits, deletes,
+ * rotates and grants; the organization's admins may view it; ordinary
+ * members have no access at all, which is why listByOrg narrows through
+ * the list read scope. There is no public level.
+ */
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { PlatformClientSchema } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
+
+import {
+  computed,
+  declareKind,
+  direct,
+  from,
+  objectOf,
+  union,
+} from "./rewrite.js";
+
+export const platformClientDeclaration = declareKind({
+  kind: ApiResourceKind.platform_client,
+  schema: PlatformClientSchema,
+  source: "fga/model/iam/platform_client.fga",
+  relations: [
+    ["organization", direct(objectOf("organization"))],
+    ["owner", direct(objectOf("identity_account"))],
+    [
+      "viewer",
+      union(
+        direct(objectOf("identity_account")),
+        computed("owner"),
+        from("admin", "organization"),
+      ),
+    ],
+    ["can_view", computed("viewer")],
+    ["can_edit", computed("owner")],
+    ["can_delete", computed("owner")],
+    ["can_grant_access", computed("owner")],
+    ["can_view_access", computed("viewer")],
+  ],
+});

package/src/boot/__tests__/auth-enabled-composition.test.ts

@@ -236,10 +236,11 @@ describe("the require-authentication posture on the wire", () => {
     );
   });
 
-  it("is_public methods stay reachable tokenless (getServerInfo)", async () => {
+  it("is_public methods stay reachable tokenless (getServerInfo), and it reports the posture", async () => {
     const platform = createClient(PlatformQueryController, transportWith());
     const info = await platform.getServerInfo({});
     expect(info.edition).not.toBe("");
+    expect(info.authenticationRequired).toBe(true);
   });
 
   it("the gRPC health service stays reachable tokenless — a Kubernetes grpc probe survives the posture (stigmer#974)", async () => {

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/__tests__/route-shadowing.test.ts

@@ -0,0 +1,67 @@
+/**
+ * Pins the routes stage's refusal of a shadowing registration: Connect's
+ * router lets the last registration of a path win silently, so an
+ * extension that registers a service the core already serves — or that
+ * another extension already registered — must fail boot, naming itself and
+ * whoever serves the path. Distinct services pass untouched, in order.
+ */
+import { createConnectRouter } from "@connectrpc/connect";
+import { describe, expect, it } from "vitest";
+
+import { OAuthAppQueryController } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/query_pb";
+import { PlatformClientQueryController } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/query_pb";
+import { PlatformClientTokenController } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/token_pb";
+
+import { registerExtensionServicesUnshadowed } from "../route-shadowing.js";
+
+describe("registerExtensionServicesUnshadowed", () => {
+  it("refuses an extension service the core already serves, naming the unit and the path", () => {
+    const router = createConnectRouter();
+    router.service(PlatformClientTokenController, {});
+    expect(() =>
+      registerExtensionServicesUnshadowed(router, [
+        {
+          unit: "cloud-iam",
+          register: (r) => void r.service(PlatformClientTokenController, {}),
+        },
+      ]),
+    ).toThrow(
+      /extension 'cloud-iam' registers \/ai\.stigmer\.iam\.platformclient\.v1\.PlatformClientTokenController\/mintUserToken, which the core already serves/,
+    );
+  });
+
+  it("refuses a second extension registering what a first one did", () => {
+    const router = createConnectRouter();
+    expect(() =>
+      registerExtensionServicesUnshadowed(router, [
+        {
+          unit: "first",
+          register: (r) => void r.service(OAuthAppQueryController, {}),
+        },
+        {
+          unit: "second",
+          register: (r) =>
+            void r.rpc(OAuthAppQueryController.method.get, () => {
+              throw new Error("never called");
+            }),
+        },
+      ]),
+    ).toThrow(
+      /extension 'second' registers .*OAuthAppQueryController\/get, which extension 'first' already serves/,
+    );
+  });
+
+  it("registers distinct services from every unit", () => {
+    const router = createConnectRouter();
+    router.service(OAuthAppQueryController, {});
+    registerExtensionServicesUnshadowed(router, [
+      {
+        unit: "billing",
+        register: (r) => void r.service(PlatformClientQueryController, {}),
+      },
+    ]);
+    expect(router.handlers.map((handler) => handler.requestPath)).toContain(
+      "/ai.stigmer.iam.platformclient.v1.PlatformClientQueryController/listByOrg",
+    );
+  });
+});

package/src/boot/compose.ts

@@ -108,6 +108,11 @@ import { registerExecutionContextServices } from "../domain/executioncontext/con
 import { registerGitHubServices } from "../domain/github/controller.js";
 import { registerMemoryServices } from "../domain/memory/controller.js";
 import { registerOAuthAppServices } from "../domain/oauthapp/controller.js";
+import { registerPlatformClientServices } from "../domain/platformclient/controller.js";
+import { newPlatformClientOriginGuard } from "../domain/platformclient/origin-guard.js";
+import { newResourcePlatformClientStore } from "../domain/platformclient/resource-store.js";
+import { registerPlatformClientTokenService } from "../domain/platformclient/token-controller.js";
+import { newPlatformClientTokenVerifier } from "../domain/platformclient/verifier.js";
 import { registerOrganizationServices } from "../domain/organization/controller.js";
 import { registerMcpServerServices } from "../domain/mcpserver/controller.js";
 import { registerPlatformServices } from "../domain/platform/controller.js";
@@ -144,6 +149,7 @@ import {
 import type { SecretCodec } from "../encryption/codec.js";
 import { getOrCreateNamedKey } from "../encryption/key-manager.js";
 import { V1_VERSION } from "../encryption/v1-codec.js";
+import { resolvePlatformTokenKeys } from "../platformtoken/key-ring.js";
 import { registerActivityServices } from "../query/activity/controller.js";
 import { ActivityHandler } from "../query/activity/handler.js";
 import { registerSearchServices } from "../query/search/controller.js";
@@ -203,9 +209,11 @@ import {
 } from "../transport/console/handler.js";
 import { createRegistryLanes } from "../transport/registry/lanes.js";
 import { createUnifiedPortServer } from "../transport/server.js";
+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 {
@@ -329,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,
@@ -413,6 +423,14 @@ export async function composeServer(
   // bindings are what the IamPolicy controller registers over (routes).
   const iamPolicies =
     extensions.drivers.iamPolicyStore ?? newResourceIamPolicyStore(store);
+  // The PlatformClient store PORT, bound the same way
+  // (`drivers.platformClientStore`; open source's adapter over `store`
+  // when absent): the chains, the mint and the verifier's liveness read all
+  // go through this one binding, so a composed driver is followed
+  // everywhere by construction.
+  const platformClients =
+    extensions.drivers.platformClientStore ??
+    newResourcePlatformClientStore(store);
   const iamPolicyGrantPath = newIamPolicyGrantPath({
     policies: iamPolicies,
     lifecycle: extensions.drivers.resourceAuthorizationLifecycle,
@@ -690,6 +708,26 @@ export async function composeServer(
       writeVersionValue === "" ? DEFAULT_WRITE_VERSION : writeVersionValue,
     registeredCodecs: [...secretCodecs.keys()].sort(),
   });
+  // The platform-token key ring joins the FATAL side of the asymmetry:
+  // under an authentication posture a server that cannot sign or verify
+  // its own tokens would refuse every PlatformClient-minted caller, and an
+  // explicitly configured key that does not load is configuration the
+  // operator meant (the ladder's rule). No posture, no ring
+  // (resolvePlatformTokenKeys carries the four arms).
+  const platformTokenKeys = resolvePlatformTokenKeys({
+    requireAuthentication,
+    supplied: extensions.drivers.platformTokenKeys,
+    edition: extensions.edition,
+  });
+  logger.info("platform-token keys resolved", {
+    source:
+      platformTokenKeys === undefined
+        ? "none (no authentication posture)"
+        : extensions.drivers.platformTokenKeys !== undefined
+          ? "extension"
+          : "open-source ladder",
+    signing: platformTokenKeys?.signer !== undefined,
+  });
   // Stage: temporal (#18). Construction is sync and connection-free —
   // initialConnect/startWorkers/startHealthMonitor run in start(), all
   // NON-fatal (Go server.go: the server boots and serves with the engine
@@ -985,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,
             };
           },
@@ -1161,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(
@@ -1175,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
@@ -1284,6 +1329,34 @@ export async function composeServer(
       authorizer,
       authorizationLifecycle,
     });
+    // PlatformClient, OAuthApp's inbound counterpart: served in every
+    // composition over the store PORT bound above. The token service is
+    // registered here too — mintGuestToken dispatches to the composed
+    // capability — so nothing else may register it (route-shadowing.ts).
+    // The mint writes end users through the identity-account create path
+    // and the one grant path, as the platform client (mint.ts), and signs
+    // with the ring the keys stage resolved (none without a posture: the
+    // mint then refuses).
+    registerPlatformClientServices(router, {
+      clients: platformClients,
+      store,
+      logger,
+      authorizer,
+      authorizationLifecycle,
+      listReadScope,
+    });
+    registerPlatformClientTokenService(router, {
+      mint: {
+        clients: platformClients,
+        accounts: identityAccounts,
+        createAccount: createIdentityAccount,
+        grantPath: iamPolicyGrantPath,
+        keys: platformTokenKeys,
+        logger,
+        now: () => new Date(),
+      },
+      guestTokenMinting: extensions.drivers.guestTokenMinting,
+    });
     registerExecutionContextServices(router, {
       store,
       logger,
@@ -1549,6 +1622,7 @@ export async function composeServer(
       runnerAuthService: runnerCredentials,
       edition: extensions.edition,
       version: options.version ?? SERVER_VERSION,
+      authenticationRequired: requireAuthentication,
       // The built-in `absent` answer installs here, at the consumer, when
       // no unit registered a license-status provider: open source and the
       // cloud hold no key, and only an Enterprise unit ever has one.
@@ -1559,10 +1633,9 @@ export async function composeServer(
     // Extension services register after the whole OSS set, inside the ONE
     // routes closure — so the serving router AND the in-process transport
     // see them by construction (blueprint §2a; DD-002's parity doctrine
-    // extends to extension services unchanged).
-    for (const registerExtensionServices of extensions.services) {
-      registerExtensionServices(router);
-    }
+    // extends to extension services unchanged). A registration that would
+    // shadow a route already served is a boot throw (route-shadowing.ts).
+    registerExtensionServicesUnshadowed(router, extensions.services);
   };
   const inProcessWiring = createInProcessClients(routes, logger);
   inProcess = inProcessWiring.clients;
@@ -1610,6 +1683,18 @@ export async function composeServer(
     ...(requireAuthentication
       ? [newApiKeyIdentityVerifier({ store, accounts: identityAccounts })]
       : []),
+    // The PlatformClient user-token lane rides the ring, which the keys
+    // stage resolves only under an authentication posture. It sits before
+    // `oidc` for the runner-subject verifier's reason (stigmer#1137): the
+    // OIDC verifier would claim the platform token and throw on it.
+    ...(platformTokenKeys !== undefined
+      ? [
+          newPlatformClientTokenVerifier({
+            keys: platformTokenKeys,
+            clients: platformClients,
+          }),
+        ]
+      : []),
     ...(authorizationPosture === "built-in"
       ? [
           newRunnerSubjectIdentityVerifier({
@@ -1652,6 +1737,16 @@ export async function composeServer(
       ? [`extension '${extensions.requireAuthentication.declaredBy}'`]
       : []),
   ];
+  // Caller guards: open source's own first, then the extensions' — the
+  // rule the verifier list follows ("OSS entries first"). The origin guard
+  // exists only where PlatformClient tokens can be presented, under the
+  // posture that verifies them.
+  const callerGuards = [
+    ...(platformTokenKeys !== undefined
+      ? [newPlatformClientOriginGuard({ clients: platformClients, logger })]
+      : []),
+    ...extensions.callerGuards,
+  ];
   logger.info("authentication posture resolved", {
     posture: requireAuthentication ? "required" : "trusted-local",
     source: postureSources.length > 0 ? postureSources.join(" + ") : "none",
@@ -1680,7 +1775,7 @@ export async function composeServer(
       logger,
       createVerifierChainInterceptor(
         identityVerifiers,
-        extensions.callerGuards,
+        callerGuards,
         logger,
         requireAuthentication,
       ),

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/boot/route-shadowing.ts

@@ -0,0 +1,47 @@
+/**
+ * The routes stage's one refusal: an extension may not register a route
+ * the router already serves.
+ *
+ * Connect's router keeps every registration, and both the serving adapter
+ * and the in-process transport build their path table with a plain map
+ * set, so a second registration of `/<service>/<method>` silently wins.
+ * Extensions register after the whole core set (compose.ts), so a
+ * composition that re-registers a service the core has come to serve —
+ * the moment a cloud domain moves into open source and the cloud's pin
+ * advances without deleting its own handlers — would shadow the core with
+ * no error, and serve from whatever store its old handlers read. Refusing
+ * at boot turns that into the loudest possible failure; the fix is always
+ * the domain's driver point, never a second service.
+ *
+ * Checked per request path, because `router.service` registers every
+ * method of a descriptor (the unimplemented ones answering UNIMPLEMENTED)
+ * and `router.rpc` registers one; two extensions colliding with each
+ * other are refused the same way.
+ */
+import type { ConnectRouter } from "@connectrpc/connect";
+
+import type { ResolvedServiceRegistration } from "../extensions/registry.js";
+
+/** Runs each extension registration, refusing any path already routed. */
+export function registerExtensionServicesUnshadowed(
+  router: ConnectRouter,
+  registrations: ReadonlyArray<ResolvedServiceRegistration>,
+): void {
+  // Request path → who serves it, as the refusal names them.
+  const servedBy = new Map<string, string>(
+    router.handlers.map((handler) => [handler.requestPath, "the core"]),
+  );
+  for (const { unit, register } of registrations) {
+    const before = router.handlers.length;
+    register(router);
+    for (const handler of router.handlers.slice(before)) {
+      const server = servedBy.get(handler.requestPath);
+      if (server !== undefined) {
+        throw new Error(
+          `extension '${unit}' registers ${handler.requestPath}, which ${server} already serves — a route is never registered twice; an edition changes a core domain's behaviour through its driver points`,
+        );
+      }
+      servedBy.set(handler.requestPath, `extension '${unit}'`);
+    }
+  }
+}