@kindgi/api 0.1.5-rc.0 → 0.1.5

package/dist/routes/readable-projects.js

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { ref } from '@kindgi/authz';
+const PROJECT_PAGE = 200;
+/** The tenant's projects, every page; none without a project binding. */
+export async function allProjects(c, projects) {
+    if (projects === undefined)
+        return [];
+    const tenantId = c.get('tenantId');
+    const all = [];
+    let cursor;
+    for (;;) {
+        const page = await projects.list(tenantId, {
+            limit: PROJECT_PAGE,
+            ...(cursor !== undefined && { cursor }),
+        });
+        all.push(...page.items.map((p) => ({ id: p.id, ...(p.orgId !== undefined && { orgId: p.orgId }) })));
+        if (page.nextCursor === undefined)
+            break;
+        cursor = page.nextCursor;
+    }
+    return all;
+}
+/**
+ * The ids of the projects the caller may `action`: listed by the
+ * authorizer, else the tenant's projects checked one by one. `undefined`
+ * when neither can say (the authorizer can't list, and there's no project
+ * binding to check against).
+ */
+export async function projectIdsCallerMay(c, authorizer, projects, action) {
+    const listed = await authorizer.listObjects?.(c, action, 'project');
+    if (listed !== undefined)
+        return listed.map((id) => id);
+    if (projects === undefined)
+        return undefined;
+    const may = await authorizer.filterByCan(c, action, await allProjects(c, projects), (p) => ref('project', p.id));
+    return may.map((p) => p.id);
+}
+//# sourceMappingURL=readable-projects.js.map

package/dist/routes/readable-projects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readable-projects.js","sourceRoot":"","sources":["../../src/routes/readable-projects.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAWjC,OAAO,EAAe,GAAG,EAAE,MAAM,eAAe,CAAC;AAOjD,MAAM,YAAY,GAAG,GAAG,CAAC;AAIzB,yEAAyE;AACzE,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,CAAkB,EAClB,QAAkD;IAElD,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACtC,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,UAAU,CAAa,CAAC;IAC/C,MAAM,GAAG,GAAiB,EAAE,CAAC;IAC7B,IAAI,MAAuD,CAAC;IAC5D,SAAS,CAAC;QACR,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE;YACzC,KAAK,EAAE,YAAY;YACnB,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,CAAC;SACxC,CAAC,CAAC;QACH,GAAG,CAAC,IAAI,CACN,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAC3F,CAAC;QACF,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS;YAAE,MAAM;QACzC,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC;IAC3B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,CAAkB,EAClB,UAAsB,EACtB,QAAkD,EAClD,MAAc;IAEd,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;IACpE,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAe,CAAC,CAAC;IACrE,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC7C,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CACxF,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,EAAuB,CAAC,CAC1C,CAAC;IACF,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAC9B,CAAC"}

package/openapi.json

@@ -248,6 +248,7 @@
           "tool-already-registered": 409,
           "tool-project-mismatch": 409,
           "guardrail-already-registered": 409,
+          "guardrail-project-mismatch": 409,
           "guardrail-config-invalid": 422,
           "flow-already-registered": 409,
           "flow-project-mismatch": 409,
@@ -4468,7 +4469,7 @@
               "same-project",
               "tenant"
             ],
-            "description": "What the intent selects within what the run may see. Facts: this conversation's; this run's end user's and user's; the run's project's (none without a project); or every fact of the type it may see (`tenant`). Conversations: this person's other conversations with the agent (`same-user`); this conversation's messages older than the history window (`same-conversation`); conversations in the run's segment path (`same-segment`) or its project (`same-project`), whoever had them: those two quote other people's conversations, so publishing warns and their messages are marked as another person's. `same-segment` is for conversations only, `tenant` for facts only."
+            "description": "What the intent selects within what the run may see. Facts: this conversation's; the run's end user's only (`same-user`: none when the run names no `participantId`); the run's project's (none without a project); or every fact of the type it may see (`tenant`). Conversations: this end user's other conversations with the agent (`same-user`: none when the run names no `participantId`); this conversation's messages older than the history window (`same-conversation`); conversations in the run's segment path (`same-segment`) or its project (`same-project`), whoever had them: those two quote other people's conversations, so publishing warns and their messages are marked as another person's. `same-segment` is for conversations only, `tenant` for facts only."
           },
           "limit": {
             "type": "integer",
@@ -31574,7 +31575,7 @@
             }
           }
         },
-        "description": "Primary consumer path for dashboards. `groupBy` is required (comma-separated dimensions from the closed set); time range is required (both `from` and `to`, or both omitted for the default last-30-days window echoed back in `timeRange`). Filters compose on top of the time window. `?scopeKind + ?scopeId` narrow the aggregate to a scope: `org` covers every project in the org, so one call sums an org's spend. Each group, and the total, carries its cost and its token sums (`tokens`). `groups` is ordered by `totalUsd`, highest first (ties by key), and capped at `limit` (default 1000): `truncated` and `totalGroups` say when there were more, and the totals still cover every record. For every record, page through `/v1/cost/records`. `inherit` has no effect on cost records, which always belong to a project.",
+        "description": "Primary consumer path for dashboards. `groupBy` is required (comma-separated dimensions from the closed set); time range is required (both `from` and `to`, or both omitted for the default last-30-days window echoed back in `timeRange`). Filters compose on top of the time window. `?scopeKind + ?scopeId` narrow the aggregate to a scope: `org` covers every project in the org, so one call sums an org's spend. It needs `read` on the scope, and across projects (no scope, the tenant, or an org) it counts only the projects the caller may read, and records with no project; a tenant admin's counts every project. Each group, and the total, carries its cost and its token sums (`tokens`). `groups` is ordered by `totalUsd`, highest first (ties by key), and capped at `limit` (default 1000): `truncated` and `totalGroups` say when there were more, and the totals still cover every record. For every record, page through `/v1/cost/records`. `inherit` has no effect on cost records, which always belong to a project.",
         "parameters": [
           {
             "name": "groupBy",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/api",
-  "version": "0.1.5-rc.0",
+  "version": "0.1.5",
   "description": "REST + SSE HTTP surface for Kindgi™. createApp assembles a Hono app serving the /v1/* REST API (bearer or session-token auth; OpenAPI 3.1 document at /v1/openapi.json) and an optional S3-compatible /s3/* surface (SigV4), over caller-plugged bindings for the runtime (runs, agents, flows, HITL, supervisor) and for storage. Route conventions: docs/API-ROUTE-CONVENTIONS.md.",
   "license": "Apache-2.0",
   "repository": {
@@ -37,30 +37,30 @@
     "openapi.json"
   ],
   "dependencies": {
-    "@kindgi/agents": "0.1.5-rc.0",
-    "@kindgi/audit-events": "0.1.5-rc.0",
-    "@kindgi/compliance": "0.1.5-rc.0",
-    "@kindgi/authz": "0.1.5-rc.0",
-    "@kindgi/blob-binding": "0.1.5-rc.0",
-    "@kindgi/capabilities": "0.1.5-rc.0",
-    "@kindgi/crypto": "0.1.5-rc.0",
-    "@kindgi/flow": "0.1.5-rc.0",
-    "@kindgi/guardrails": "0.1.5-rc.0",
-    "@kindgi/log": "0.1.5-rc.0",
-    "@kindgi/memory": "0.1.5-rc.0",
-    "@kindgi/platform": "0.1.5-rc.0",
-    "@kindgi/provenance": "0.1.5-rc.0",
-    "@kindgi/runtime": "0.1.5-rc.0",
-    "@kindgi/policy-contract": "0.1.5-rc.0",
-    "@kindgi/schema": "0.1.5-rc.0",
-    "@kindgi/tools": "0.1.5-rc.0",
-    "@kindgi/types": "0.1.5-rc.0",
+    "@kindgi/agents": "0.1.5",
+    "@kindgi/audit-events": "0.1.5",
+    "@kindgi/compliance": "0.1.5",
+    "@kindgi/authz": "0.1.5",
+    "@kindgi/blob-binding": "0.1.5",
+    "@kindgi/capabilities": "0.1.5",
+    "@kindgi/crypto": "0.1.5",
+    "@kindgi/flow": "0.1.5",
+    "@kindgi/guardrails": "0.1.5",
+    "@kindgi/log": "0.1.5",
+    "@kindgi/memory": "0.1.5",
+    "@kindgi/platform": "0.1.5",
+    "@kindgi/provenance": "0.1.5",
+    "@kindgi/runtime": "0.1.5",
+    "@kindgi/policy-contract": "0.1.5",
+    "@kindgi/schema": "0.1.5",
+    "@kindgi/tools": "0.1.5",
+    "@kindgi/types": "0.1.5",
     "@scalar/hono-api-reference": "^0.12.2",
     "hono": "^4.6.14"
   },
   "devDependencies": {
-    "@kindgi/audit-events-inmemory": "0.1.5-rc.0",
-    "@kindgi/specs": "0.1.5-rc.0",
+    "@kindgi/audit-events-inmemory": "0.1.5",
+    "@kindgi/specs": "0.1.5",
     "@types/aws4": "^1.11.6",
     "@types/node": "^22.10.5",
     "aws4": "^1.13.2",

package/src/app.ts

@@ -1386,7 +1386,7 @@ export function createApp(input: CreateAppInput): Hono<AppEnv> {
     }),
   );
   if (input.cost !== undefined) {
-    v1.route('/cost', costRouter(input.cost, authorizer));
+    v1.route('/cost', costRouter(input.cost, authorizer, input.projectBinding));
   }
   if (input.adapterRegistry !== undefined) {
     v1.route(

package/src/cost-binding.ts

@@ -50,6 +50,14 @@ export interface CostBinding {
    * every group is capped by the route.
    */
   aggregate(input: CostAggregateInput): Promise<CostAggregateResult>;
+  /**
+   * `true` when `aggregate` honours `CostAggregateInput.readableProjectIds`,
+   * counting only those projects' records. Without it, the route answers
+   * an aggregate across projects (no scope, or an org) only for a caller
+   * who may read every project in it, and refuses anyone else rather than
+   * count projects they can't read.
+   */
+  readonly aggregatesReadableProjects?: boolean;
 }
 
 // A binding throws when its store fails: the route answers 500. It never
@@ -198,6 +206,17 @@ export interface CostAggregateInput {
    * shape uniformity.
    */
   readonly inherit?: boolean;
+  /**
+   * Count only records in these projects, and records with no project
+   * (the tenant's own, which `/v1/cost/records` shows to anyone who may
+   * read the tenant), within `scope`. An org scope covers only the org's
+   * projects: a record with no project never counts there, and nor does a
+   * listed project outside the org. The route sets it when the caller
+   * may not read every project (`read` on each listed one); absent, every
+   * record in `scope` counts. Empty: no project's records count. A binding
+   * that applies it says so with `CostBinding.aggregatesReadableProjects`.
+   */
+  readonly readableProjectIds?: readonly string[];
   /**
    * The most groups the caller wants (`?limit=`, 1..`COST_AGGREGATE_MAX_LIMIT`,
    * default `COST_AGGREGATE_DEFAULT_LIMIT`): the most expensive ones. A

package/src/errors.ts

@@ -94,6 +94,8 @@ export const ERROR_CODE_TO_STATUS: Readonly<Record<string, number>> = {
   'tool-already-registered': 409,
   'tool-project-mismatch': 409,
   'guardrail-already-registered': 409,
+  // A deploy's guardrail id is live in another project: a deploy never takes it.
+  'guardrail-project-mismatch': 409,
   'guardrail-config-invalid': 422,
   'flow-already-registered': 409,
   'flow-project-mismatch': 409,

package/src/middleware/authorize.ts

@@ -61,8 +61,11 @@ export interface Authorizer {
   ) => Promise<T[]>;
   /**
    * The ids of every object of `type` the caller may `action`
-   * (`AuthzCheckBinding.listObjects`); `undefined` when the binding
-   * can't list, so the caller falls back to `filterByCan`.
+   * (`AuthzCheckBinding.listObjects`), within its API key's limits as
+   * `filterByCan` holds them: a key limited to a project lists no project
+   * but its own, and other types as a check decides them (it still reads
+   * the orgs its user reads); `undefined` when the binding can't list, so
+   * the caller falls back to `filterByCan`.
    */
   readonly listObjects?: (
     c: Context<AppEnv>,
@@ -199,7 +202,20 @@ export function createAuthorizer(binding: AuthzCheckBinding): Authorizer {
         typeof requestId === 'string' && requestId.length > 0
           ? { correlationId: requestId }
           : undefined;
-      return binding.listObjects(principal, action, type, ctx);
+      const ids = await binding.listObjects(principal, action, type, ctx);
+      // The key's own limits, as `filterByCan` holds them: the store lists
+      // what the user may do, and a key limited to a project lists no other
+      // project (other types as a check decides them).
+      const withinKey = await Promise.all(
+        ids.map(async (id) => {
+          const resource: ResourceRef = { type, id };
+          return (
+            keyCeilingDeny(c, action, resource) === undefined &&
+            (await inKeyProject(c, principal, resource))
+          );
+        }),
+      );
+      return ids.filter((_, i) => withinKey[i]);
     },
   };
 }

package/src/openapi/operations.ts

@@ -4306,7 +4306,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     operationId: 'cost.aggregate',
     summary: 'Aggregate cost across a time window',
     description:
-      "Primary consumer path for dashboards. `groupBy` is required (comma-separated dimensions from the closed set); time range is required (both `from` and `to`, or both omitted for the default last-30-days window echoed back in `timeRange`). Filters compose on top of the time window. `?scopeKind + ?scopeId` narrow the aggregate to a scope: `org` covers every project in the org, so one call sums an org's spend. Each group, and the total, carries its cost and its token sums (`tokens`). `groups` is ordered by `totalUsd`, highest first (ties by key), and capped at `limit` (default 1000): `truncated` and `totalGroups` say when there were more, and the totals still cover every record. For every record, page through `/v1/cost/records`. `inherit` has no effect on cost records, which always belong to a project.",
+      "Primary consumer path for dashboards. `groupBy` is required (comma-separated dimensions from the closed set); time range is required (both `from` and `to`, or both omitted for the default last-30-days window echoed back in `timeRange`). Filters compose on top of the time window. `?scopeKind + ?scopeId` narrow the aggregate to a scope: `org` covers every project in the org, so one call sums an org's spend. It needs `read` on the scope, and across projects (no scope, the tenant, or an org) it counts only the projects the caller may read, and records with no project; a tenant admin's counts every project. Each group, and the total, carries its cost and its token sums (`tokens`). `groups` is ordered by `totalUsd`, highest first (ties by key), and capped at `limit` (default 1000): `truncated` and `totalGroups` say when there were more, and the totals still cover every record. For every record, page through `/v1/cost/records`. `inherit` has no effect on cost records, which always belong to a project.",
     tags: ['cost'],
     security: 'bearer',
     parameters: [

package/src/openapi/schemas.ts

@@ -1618,7 +1618,7 @@ export const RetrievalIntentSchema: JsonSchema = {
       type: 'string',
       enum: ['same-conversation', 'same-user', 'same-segment', 'same-project', 'tenant'],
       description:
-        "What the intent selects within what the run may see. Facts: this conversation's; this run's end user's and user's; the run's project's (none without a project); or every fact of the type it may see (`tenant`). Conversations: this person's other conversations with the agent (`same-user`); this conversation's messages older than the history window (`same-conversation`); conversations in the run's segment path (`same-segment`) or its project (`same-project`), whoever had them: those two quote other people's conversations, so publishing warns and their messages are marked as another person's. `same-segment` is for conversations only, `tenant` for facts only.",
+        "What the intent selects within what the run may see. Facts: this conversation's; the run's end user's only (`same-user`: none when the run names no `participantId`); the run's project's (none without a project); or every fact of the type it may see (`tenant`). Conversations: this end user's other conversations with the agent (`same-user`: none when the run names no `participantId`); this conversation's messages older than the history window (`same-conversation`); conversations in the run's segment path (`same-segment`) or its project (`same-project`), whoever had them: those two quote other people's conversations, so publishing warns and their messages are marked as another person's. `same-segment` is for conversations only, `tenant` for facts only.",
     },
     limit: { type: 'integer', minimum: 1 },
     mode: {

package/src/publish-refused.ts

@@ -19,6 +19,17 @@ type RefusedOutcome = Exclude<
   { readonly kind: 'ok' | 'already-registered' }
 >;
 
+/**
+ * A refusal the deploy decides itself, when its registry answered
+ * `already-registered` for a live guardrail it can't keep: one in another
+ * project (whose project the registry doesn't say), or one in its own
+ * project with a different definition.
+ */
+interface DeployRefusal {
+  readonly code: 'guardrail-project-mismatch' | 'guardrail-already-registered';
+  readonly reason: string;
+}
+
 /**
  * A deploy's primitive came back from its registry with an outcome other
  * than `ok` or `already-registered` (e.g. `project-not-found`): the deploy
@@ -35,15 +46,22 @@ export class PublishRefused extends Error {
   /** The code the deploy answers with. */
   readonly code:
     | Exclude<RefusedOutcome['kind'], 'project-mismatch'>
-    | `${PublishedPrimitive}-project-mismatch`;
+    | `${PublishedPrimitive}-project-mismatch`
+    | DeployRefusal['code'];
   /** With `…-project-mismatch`: the project the primitive belongs to, for the log only. */
   readonly projectId?: ProjectId;
 
   constructor(
     readonly primitive: PublishedPrimitive,
     readonly id: string,
-    outcome: RefusedOutcome,
+    outcome: RefusedOutcome | DeployRefusal,
   ) {
+    if ('code' in outcome) {
+      super(`The ${primitive} ${id} wasn't published: ${outcome.reason}`);
+      this.name = 'PublishRefused';
+      this.code = outcome.code;
+      return;
+    }
     const code =
       outcome.kind === 'project-mismatch'
         ? (`${primitive}-project-mismatch` as const)

package/src/routes/cost.ts

@@ -1,16 +1,18 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 
-import { Hono } from 'hono';
+import { type Context, Hono } from 'hono';
 
 import type { Cursor, TenantId, Timestamp } from '@kindgi/types';
 
-import { type ResourceRef, ref } from '@kindgi/authz';
+import { type ResourceRef, denyPayload, ref } from '@kindgi/authz';
+import type { ProjectBinding } from '@kindgi/platform';
 import {
   COST_AGGREGATE_DEFAULT_LIMIT,
   COST_AGGREGATE_MAX_LIMIT,
   COST_GROUP_DIMENSIONS,
   type CostAggregateGroup,
+  type CostAggregateInput,
   type CostBinding,
   type CostGroupDimension,
   type CostRecord,
@@ -23,6 +25,7 @@ import type { Authorizer } from '../middleware/authorize.js';
 import type { AppEnv } from '../types.js';
 import { deniedBy } from './denied.js';
 import { clampLimit } from './pagination.js';
+import { projectIdsCallerMay } from './readable-projects.js';
 import { parseScopeParams, scopeResourceRef } from './scope-params.js';
 
 /**
@@ -45,10 +48,14 @@ import { parseScopeParams, scopeResourceRef } from './scope-params.js';
 export function costRouter(
   binding: CostBinding,
   /**
-   * With one (T243 A): a record needs `read` on its project (the tenant,
-   * for one with no project); an aggregate, on the scope it's asked for.
+   * With one: a record needs `read` on its project (the tenant, for one
+   * with no project); an aggregate, `read` on the scope it's asked for,
+   * and across projects (no scope, or an org) it counts only the projects
+   * the caller may read, unless the caller is a tenant admin.
    */
   authorizer?: Authorizer,
+  /** The tenant's projects, to check one by one when the authorizer can't list them. */
+  projects?: Pick<ProjectBinding, 'list'>,
 ): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
   const recordRef = (tenantId: TenantId, rec: { readonly projectId?: unknown }): ResourceRef =>
@@ -278,6 +285,16 @@ export function costRouter(
     );
     if (refused !== undefined) return refused;
 
+    // Across projects, only what the caller may read counts (`aggregateReach`).
+    const reach = await aggregateReach(c, {
+      binding,
+      tenantId,
+      authorizer,
+      projects,
+      scope: scopeParsed.scope,
+    });
+    if (reach.kind === 'refused') return reach.response;
+
     const result = await binding.aggregate({
       tenantId,
       groupBy,
@@ -286,6 +303,7 @@ export function costRouter(
       ...(Object.keys(filter.value).length > 0 && { filter: filter.value }),
       ...(scopeParsed.scope !== undefined && { scope: scopeParsed.scope }),
       ...(scopeParsed.inherit !== undefined && { inherit: scopeParsed.inherit }),
+      ...(reach.kind === 'projects' && { readableProjectIds: reach.ids }),
       limit,
     });
 
@@ -314,6 +332,65 @@ export function costRouter(
 
 // -------- helpers --------
 
+/**
+ * What an aggregate may count for this caller. Across projects (no scope,
+ * the tenant, or an org), `read` on the scope lets a member ask, not see
+ * every project's spend: only the projects they may read count, applied in
+ * the binding's query (`readableProjectIds`). A tenant admin's, a project
+ * scope's (already checked) and one without authorization count everything
+ * the scope holds. When the readable projects can't be worked out, or the
+ * binding can't apply them, the aggregate is refused rather than
+ * over-counted.
+ */
+async function aggregateReach(
+  c: Context<AppEnv>,
+  args: {
+    readonly binding: CostBinding;
+    readonly tenantId: TenantId;
+    readonly authorizer: Authorizer | undefined;
+    readonly projects: Pick<ProjectBinding, 'list'> | undefined;
+    readonly scope: CostAggregateInput['scope'] | undefined;
+  },
+): Promise<
+  | { readonly kind: 'all' }
+  | { readonly kind: 'projects'; readonly ids: readonly string[] }
+  | { readonly kind: 'refused'; readonly response: Response }
+> {
+  const { binding, tenantId, authorizer, projects, scope } = args;
+  if (authorizer === undefined || scope?.kind === 'project') return { kind: 'all' };
+  if (await authorizer.can(c, 'admin', ref('tenant', tenantId as unknown as string))) {
+    return { kind: 'all' };
+  }
+  const ids = await projectIdsCallerMay(c, authorizer, projects, 'read');
+  if (ids !== undefined && binding.aggregatesReadableProjects === true) {
+    return { kind: 'projects', ids };
+  }
+  const deny = denyPayload(
+    'read',
+    scope?.kind === 'org' ? 'org' : 'tenant',
+    scope?.kind === 'org' ? (scope.orgId as unknown as string) : (tenantId as unknown as string),
+    ids === undefined
+      ? "the projects you may read can't be listed here, so an aggregate across projects can't be limited to them; ask per project (scopeKind=project)"
+      : "this deployment's cost store can't limit an aggregate to the projects you may read; ask per project (scopeKind=project)",
+  );
+  c.status(403);
+  return {
+    kind: 'refused',
+    response: c.json(
+      toWireError(
+        {
+          code: deny.code,
+          message: `Permission denied: ${deny.reason}`,
+          action: deny.action,
+          resource: deny.resource,
+          reason: deny.reason,
+        },
+        c.get('requestId'),
+      ),
+    ),
+  };
+}
+
 function parseRecordFilter(
   query: Readonly<Record<string, string | undefined>>,
   opts: { skipTime?: boolean } = {},

package/src/routes/deployments.ts

@@ -616,7 +616,21 @@ export function deploymentsRouter(
             rolled.push(async () => {
               await bindings.guardrailRegistry?.unregister({ tenantId, guardrailId });
             });
-          } else if (outcome.kind !== 'already-registered') {
+          } else if (outcome.kind === 'already-registered') {
+            const kept = await keepRegisteredGuardrail(
+              bindings.guardrailRegistry,
+              tenantId,
+              projectIdForGuardrail,
+              guardrail,
+            );
+            // Unregistered since the registry answered: registered afresh.
+            if (kept === 'registered') {
+              const guardrailId = guardrail.id;
+              rolled.push(async () => {
+                await bindings.guardrailRegistry?.unregister({ tenantId, guardrailId });
+              });
+            }
+          } else {
             throw new PublishRefused('guardrail', guardrail.id, outcome);
           }
         }
@@ -1234,6 +1248,139 @@ interface DeployedImage {
   readonly artifactVersion: string;
 }
 
+/**
+ * A deploy keeps a guardrail id that's already live only when it's the
+ * deploy's own: in the project the deploy registers into, with the same
+ * definition (`sameGuardrailDefinition`, what its author declares). An id live in another project
+ * is refused (`guardrail-project-mismatch`, its project never named): the
+ * pack's agents would otherwise run that project's guardrail. One in this
+ * project with another definition is refused too
+ * (`guardrail-already-registered`): a deploy never changes a guardrail,
+ * and keeping the old one would run what the pack no longer says.
+ *
+ * `get` answers a guardrail without its project, so whether the id is in
+ * this project comes from the project's list. When the row is gone by the
+ * time it's looked at (unregistered meanwhile), the guardrail is
+ * registered again: `'registered'`, for the deploy to roll back.
+ */
+async function keepRegisteredGuardrail(
+  registry: GuardrailRegistryBinding,
+  tenantId: TenantId,
+  projectId: ProjectId,
+  guardrail: Guardrail,
+): Promise<'kept' | 'registered'> {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const existing = await registry.get({ tenantId, guardrailId: guardrail.id });
+    if (existing !== null) {
+      if (!(await guardrailInProject(registry, tenantId, projectId, guardrail.id))) {
+        throw new PublishRefused('guardrail', guardrail.id, {
+          code: 'guardrail-project-mismatch',
+          reason: 'it belongs to another project',
+        });
+      }
+      if (!sameGuardrailDefinition(existing, guardrail)) {
+        throw new PublishRefused('guardrail', guardrail.id, {
+          code: 'guardrail-already-registered',
+          reason: `it is already registered with a different definition; unregister it (\`kindgi guardrails unregister ${guardrail.id}\`) and deploy again`,
+        });
+      }
+      return 'kept';
+    }
+    const again = await registry.register({
+      tenantId,
+      projectId,
+      guardrail,
+      enqueueTuples: (guardrailId) =>
+        tuplesForCreate({
+          kind: 'guardrail',
+          id: guardrailId as GuardrailId,
+          tenantId,
+          projectId,
+        }),
+    });
+    if (again.kind === 'ok') return 'registered';
+    if (again.kind !== 'already-registered') {
+      throw new PublishRefused('guardrail', guardrail.id, again);
+    }
+  }
+  throw new Error(`guardrail ${guardrail.id}: registered and unregistered while deploying`);
+}
+
+/** Whether the live guardrail `id` is in `projectId`, by that project's list. */
+async function guardrailInProject(
+  registry: GuardrailRegistryBinding,
+  tenantId: TenantId,
+  projectId: ProjectId,
+  id: GuardrailId,
+): Promise<boolean> {
+  let cursor: Cursor | undefined;
+  do {
+    const page = await registry.list({
+      tenantId,
+      limit: 100,
+      nameFilter: id,
+      scope: { kind: 'project', tenantId, projectId },
+      ...(cursor !== undefined && { cursor }),
+    });
+    if (page.data.some((g) => g.id === id)) return true;
+    cursor = page.nextCursor;
+  } while (cursor !== undefined);
+  return false;
+}
+
+/**
+ * The fields of a guardrail its author declares, which a deploy compares.
+ * Never compared: what a deploy or a release derives. That includes
+ * `configSchema`, which the deploy route dropped before 0.1.5, so a row a
+ * 0.1.4 deploy stored has none; the image and artifact version a code
+ * pointer names, which every new image changes; and any field a later
+ * release adds. So an unchanged pack redeploys across releases.
+ */
+const DECLARED_GUARDRAIL_FIELDS = [
+  'name',
+  'description',
+  'kind',
+  'check',
+  'config',
+  'action',
+  'severity',
+  'scope',
+  'budget',
+  'judgeCapabilities',
+  'sandbox',
+  'limits',
+  'network',
+  'needsSpec',
+] as const;
+
+/**
+ * The same guardrail definition: equal in what its author declares
+ * (`DECLARED_GUARDRAIL_FIELDS`, and of where its code lives only the
+ * module path), as JSON with keys in any order (a registry may store it as
+ * JSONB) and an absent field the same as an `undefined` one.
+ */
+export function sameGuardrailDefinition(a: Guardrail, b: Guardrail): boolean {
+  return canonicalJson(definitionOf(a)) === canonicalJson(definitionOf(b));
+}
+
+function definitionOf(guardrail: Guardrail): Record<string, unknown> {
+  const declared: Record<string, unknown> = {};
+  for (const field of DECLARED_GUARDRAIL_FIELDS) {
+    declared[field] = (guardrail as unknown as Record<string, unknown>)[field];
+  }
+  declared.modulePath = guardrail.codeArtifactRef?.modulePath;
+  return declared;
+}
+
+/** JSON with every object's keys sorted, and absent and `undefined` alike. */
+function canonicalJson(value: unknown): string {
+  return JSON.stringify(JSON.parse(JSON.stringify(value) ?? 'null'), (_key, v: unknown) =>
+    v !== null && typeof v === 'object' && !Array.isArray(v)
+      ? Object.fromEntries(Object.entries(v).sort(([x], [y]) => (x < y ? -1 : x > y ? 1 : 0)))
+      : v,
+  );
+}
+
 /** The pointer to a tool's or guardrail's module inside the deployed image. */
 function ociCodeArtifactRef(image: DeployedImage, modulePath: unknown) {
   return typeof modulePath === 'string' && modulePath.length > 0

package/src/routes/eval-runs.ts

@@ -173,7 +173,10 @@ function startRouter(
       agentRef !== undefined
         ? ref('agent', agentRef.agentId as unknown as string)
         : ref('flow', flowRef?.flowId as unknown as string);
+    // Running the suite takes `execute` on it (an editor of its project, or
+    // an executor), whichever project the run lands in.
     const refused =
+      (await deniedBy(authorizer, c, 'execute', ref('eval_suite', suiteId))) ??
       (await deniedBy(authorizer, c, 'write', ref('project', projectId as unknown as string))) ??
       (await deniedBy(authorizer, c, 'execute', target));
     if (refused !== undefined) return refused;

package/src/routes/eval-suites.ts

@@ -2,6 +2,7 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import { Hono } from 'hono';
+import { routePath } from 'hono/route';
 
 import { type Principal, ref, tuplesForCreate } from '@kindgi/authz';
 import type { Cursor, ProjectId, TenantId, UserId } from '@kindgi/types';
@@ -76,8 +77,13 @@ export function evalSuitesRouter(
       return mw(c, next);
     });
     r.use('/:suiteId/*', async (c, next) => {
-      const action = c.req.method === 'GET' ? 'read' : 'admin';
       const suiteId = c.req.param('suiteId') ?? '';
+      // Starting a run (`POST /:suiteId/runs`, exactly) doesn't change the
+      // suite, and the start route checks it all itself: `execute` on the
+      // suite, `write` on the project and `execute` on the agent or flow.
+      const under = c.req.path.split('/').slice(routePath(c).split('/').length - 1);
+      if (c.req.method === 'POST' && under.length === 1 && under[0] === 'runs') return next();
+      const action = c.req.method === 'GET' ? 'read' : 'admin';
       // A test set built from judgments under a suite id never registered
       // (no head row) has no suite to check yet: the build checks `admin`
       // on the project it names, the project the new suite belongs to. A