@kindgi/api 0.1.4-rc.0 → 0.1.4-rc.2

package/src/routes/projects.ts

@@ -10,6 +10,7 @@ import type {
   ProjectBinding,
   ProjectMembership,
   ProjectMembershipBinding,
+  ProjectMembershipUpdateRoleOutcome,
   ProjectPatch,
   ProjectRole,
   ProjectSpec,
@@ -19,7 +20,12 @@ import type { Cursor, OrgId, ProjectId, TenantId, UserId } from '@kindgi/types';
 import { statusFor, toWireError } from '../errors.js';
 import type { Authorizer } from '../middleware/authorize.js';
 import type { AppEnv } from '../types.js';
-import { projectDefaultAlreadyExistsError, slugConflictError } from './hierarchy-errors.js';
+import {
+  membershipNotKeptInStepError,
+  orgNotFoundError,
+  projectDefaultAlreadyExistsError,
+  slugConflictError,
+} from './hierarchy-errors.js';
 import { clampLimit } from './pagination.js';
 
 /**
@@ -74,6 +80,39 @@ export function projectsRouter(
 ): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
 
+  /**
+   * Change a member's role. With an authorizer, the row and its FGA tuple
+   * change together through the tenant-hierarchy binding, or the change
+   * is refused; without one, the membership binding alone.
+   */
+  async function updateMemberRole(
+    tenantId: TenantId,
+    projectId: ProjectId,
+    userId: UserId,
+    role: ProjectRole,
+  ): Promise<
+    | { readonly kind: 'done'; readonly outcome: ProjectMembershipUpdateRoleOutcome }
+    | { readonly kind: 'refused'; readonly error: ReturnType<typeof membershipNotKeptInStepError> }
+  > {
+    if (authorizer === undefined) {
+      return {
+        kind: 'done',
+        outcome: await membershipBinding.updateRole(tenantId, projectId, userId, role),
+      };
+    }
+    if (tenantHierarchy.updateProjectMemberRole === undefined) {
+      return { kind: 'refused', error: membershipNotKeptInStepError('updateProjectMemberRole') };
+    }
+    const res = await tenantHierarchy.updateProjectMemberRole({
+      tenantId,
+      projectId,
+      userId,
+      role,
+    });
+    if (res.kind === 'err') throw new Error(res.error.message, { cause: res.error });
+    return { kind: 'done', outcome: res.value };
+  }
+
   // ---------- GET /default (literal segment; must precede /:projectId) ----------
   r.get('/default', async (c) => {
     const requestId = c.get('requestId');
@@ -247,9 +286,11 @@ export function projectsRouter(
         const error =
           result.error.code === 'slug-conflict'
             ? slugConflictError('project', spec.slug)
-            : result.error.code === 'default-conflict'
-              ? projectDefaultAlreadyExistsError()
-              : { code: 'internal-server-error', message: result.error.message };
+            : result.error.code === 'org-not-found'
+              ? orgNotFoundError(result.error.orgId as unknown as string)
+              : result.error.code === 'default-conflict'
+                ? projectDefaultAlreadyExistsError()
+                : { code: 'internal-server-error', message: result.error.message };
         c.status(statusFor(error.code) as never);
         return c.json(toWireError(error, requestId));
       }
@@ -263,7 +304,9 @@ export function projectsRouter(
       const error =
         outcome.kind === 'slug-conflict'
           ? slugConflictError('project', outcome.slug)
-          : projectDefaultAlreadyExistsError();
+          : outcome.kind === 'org-not-found'
+            ? orgNotFoundError(outcome.orgId as unknown as string)
+            : projectDefaultAlreadyExistsError();
       c.status(statusFor(error.code) as never);
       return c.json(toWireError(error, requestId));
     }
@@ -412,7 +455,19 @@ export function projectsRouter(
     const tenantId = c.get('tenantId') as TenantId;
     const projectId = c.req.param('projectId') as ProjectId;
     const userId = c.req.param('userId') as UserId;
-    await membershipBinding.remove(tenantId, projectId, userId);
+    // With an authorizer, the row and its FGA tuple go together, or not
+    // at all: removing the row alone would leave the permission in place.
+    if (authorizer !== undefined) {
+      if (tenantHierarchy.removeProjectMember === undefined) {
+        const refusal = membershipNotKeptInStepError('removeProjectMember');
+        c.status(statusFor(refusal.code) as never);
+        return c.json(toWireError(refusal, c.get('requestId')));
+      }
+      const res = await tenantHierarchy.removeProjectMember({ tenantId, projectId, userId });
+      if (res.kind === 'err') throw new Error(res.error.message, { cause: res.error });
+    } else {
+      await membershipBinding.remove(tenantId, projectId, userId);
+    }
     c.status(204);
     return c.body(null);
   });
@@ -452,7 +507,12 @@ export function projectsRouter(
         ),
       );
     }
-    const outcome = await membershipBinding.updateRole(tenantId, projectId, userId, b.role);
+    const updated = await updateMemberRole(tenantId, projectId, userId, b.role);
+    if (updated.kind === 'refused') {
+      c.status(statusFor(updated.error.code) as never);
+      return c.json(toWireError(updated.error, requestId));
+    }
+    const { outcome } = updated;
     if (outcome.kind === 'project-membership-not-found') {
       c.status(statusFor('project-membership-not-found') as never);
       return c.json(
@@ -596,8 +656,11 @@ export function projectsRouter(
         ),
       );
     }
-    if (outcome.kind === 'slug-conflict') {
-      const error = slugConflictError('project', outcome.slug);
+    if (outcome.kind === 'slug-conflict' || outcome.kind === 'org-not-found') {
+      const error =
+        outcome.kind === 'slug-conflict'
+          ? slugConflictError('project', outcome.slug)
+          : orgNotFoundError(outcome.orgId as unknown as string);
       c.status(statusFor(error.code) as never);
       return c.json(toWireError(error, requestId));
     }

package/src/routes/retention.ts

@@ -62,15 +62,21 @@ export function retentionRouter(binding: RetentionBinding, authorizer?: Authoriz
     const limit = clampLimit(url.searchParams.get('limit') ?? undefined);
     const pastGraceRaw = url.searchParams.get('pastGraceOnly');
     const pastGraceOnly = pastGraceRaw === 'true';
+    const cursor = url.searchParams.get('cursor') ?? '';
 
-    const page = await binding.scheduled({
+    const { hasMore, nextCursor, ...page } = await binding.scheduled({
       tenantId,
       limit,
       pastGraceOnly,
       ...(domain !== undefined && { domain }),
+      ...(cursor !== '' && { cursor }),
     });
 
-    return c.json(page);
+    return c.json({
+      ...page,
+      hasMore: hasMore ?? someDomainFilled(page.data, limit),
+      ...(nextCursor !== undefined && { nextCursor }),
+    });
   });
 
   r.post('/sweep', async (c) => {
@@ -153,6 +159,19 @@ export function retentionRouter(binding: RetentionBinding, authorizer?: Authoriz
   return r;
 }
 
+/**
+ * A runtime that doesn't report `hasMore`: there may be more when some
+ * domain's rows fill `limit` (each domain is read up to `limit`).
+ */
+function someDomainFilled(
+  data: readonly { readonly domain: RetentionDomain }[],
+  limit: number,
+): boolean {
+  const perDomain = new Map<RetentionDomain, number>();
+  for (const row of data) perDomain.set(row.domain, (perDomain.get(row.domain) ?? 0) + 1);
+  return [...perDomain.values()].some((n) => n >= limit);
+}
+
 function parseDomain(raw: string | null | undefined): RetentionDomain | 'invalid' | undefined {
   if (raw === null || raw === undefined || raw === '') return undefined;
   if ((RETENTION_DOMAINS as readonly string[]).includes(raw)) return raw as RetentionDomain;

package/src/routes/reviewers.ts

@@ -3,10 +3,11 @@
 
 import { Hono } from 'hono';
 
-import type { ReviewerRole } from '@kindgi/authz';
+import { type ReviewerRole, ref } from '@kindgi/authz';
 import type { Cursor, ReviewerId, TenantId, UserId } from '@kindgi/types';
 
 import { statusFor, toWireError } from '../errors.js';
+import type { Authorizer } from '../middleware/authorize.js';
 import type { ReviewerRecord, ReviewerRegistryBinding } from '../reviewer-binding.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit } from './pagination.js';
@@ -20,8 +21,9 @@ import { clampLimit } from './pagination.js';
  * inside `approvalsRouter`: registering a reviewer is an admin surface
  * action, not a reviewer-only one, so requiring a `reviewerRole` on the
  * caller would be circular ("only reviewers can appoint reviewers").
- * The caller still needs a valid bearer token — the `/v1/*` auth chain
- * covers that upstream.
+ * With authorization enforced, registering or unregistering needs
+ * `admin` on the tenant; reading the roster needs only a valid bearer
+ * token (the `/v1/*` auth chain upstream).
  *
  * Mounted BEFORE `approvalsRouter` on the parent `/v1` router so path
  * matching resolves `/v1/approvals/reviewers/*` here rather than being
@@ -29,9 +31,26 @@ import { clampLimit } from './pagination.js';
  */
 const ROLE_VALUES: ReadonlySet<ReviewerRole> = new Set(['standard', 'senior', 'admin']);
 
-export function reviewersRouter(binding: ReviewerRegistryBinding): Hono<AppEnv> {
+export function reviewersRouter(
+  binding: ReviewerRegistryBinding,
+  /**
+   * When set, registering or unregistering a reviewer needs `admin` on
+   * the tenant: a reviewer (an `admin` one above all) decides approvals.
+   * Reading the list doesn't.
+   */
+  authorizer?: Authorizer,
+): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
 
+  if (authorizer !== undefined) {
+    r.use('*', async (c, next) => {
+      if (c.req.method === 'GET') return next();
+      const tenantId = c.get('tenantId') as TenantId;
+      const mw = authorizer.authorize('admin', () => ref('tenant', tenantId as unknown as string));
+      return mw(c, next);
+    });
+  }
+
   // ---------- GET / (list, cursor-paginated) ----------
   r.get('/', async (c) => {
     const requestId = c.get('requestId');

package/src/routes/runs.ts

@@ -2,11 +2,18 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import { Hono } from 'hono';
-import type { MiddlewareHandler } from 'hono';
 
 import type { AgentId } from '@kindgi/agents';
 import type { KernelRunRecord, ListRunsInput, RunBinding } from '@kindgi/runtime';
-import type { FlowId, ListScope, ProjectId, RunId, Semver, TenantId } from '@kindgi/types';
+import type {
+  FlowId,
+  ListScope,
+  ProjectId,
+  RunId,
+  ScopeSegment,
+  Semver,
+  TenantId,
+} from '@kindgi/types';
 
 import { ref } from '@kindgi/authz';
 
@@ -20,9 +27,11 @@ import type {
 import type { Authorizer } from '../middleware/authorize.js';
 import type { MintPublicRunTokenResult } from '../public-run-token.js';
 import type { AppEnv } from '../types.js';
+import { liveScopeToWire } from './live-scope-wire.js';
 import type { DecodedCursor } from './pagination.js';
 import { clampLimit, decodeCursor } from './pagination.js';
 import { parseListScope } from './scope-params.js';
+import { parseSegmentsBody } from './segments.js';
 import {
   formatSseFrame,
   isTerminalWireKind,
@@ -30,6 +39,7 @@ import {
   projectJournalEntry,
   toRunProgressEvent,
 } from './sse.js';
+import { UUID_RE, refuseMalformedUuidParam } from './uuid-param.js';
 
 const KERNEL_RUN_CHANNEL_PREFIX = 'kernel:run:';
 
@@ -61,23 +71,8 @@ const MAX_RUN_ANCESTRY = 16;
  * `POST /:runId/cancel`, `POST /:runId/resume`, `GET /:runId/stream`
  * (SSE), `GET /:runId/journal`.
  */
-/** A run id: a UUID. */
-const RUN_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-/**
- * A `:runId` that isn't a run id is a 400, before it reaches a query (where
- * Postgres's uuid cast would fail it as a 500).
- */
-const refuseMalformedRunId: MiddlewareHandler<AppEnv> = async (c, next) => {
-  if (RUN_ID_RE.test(c.req.param('runId') ?? '')) return next();
-  c.status(statusFor('bad-input') as never);
-  return c.json(
-    toWireError(
-      { code: 'bad-input', message: '`runId` must be a run id (a UUID)' },
-      c.get('requestId'),
-    ),
-  );
-};
+/** A `:runId` that isn't a run id is a 400 (`uuid-param.ts`). */
+const refuseMalformedRunId = refuseMalformedUuidParam('runId', 'a run id');
 
 export function runsRouter(
   binding: RunHandlerBinding,
@@ -634,6 +629,7 @@ function invokeFromBody(
     tenantId,
     ...(body.projectId !== undefined && { projectId: body.projectId }),
     input: body.input,
+    ...(body.segments !== undefined && { segments: body.segments }),
     ...(body.dryRun !== undefined && { dryRun: body.dryRun }),
     ...(body.wait !== undefined && { wait: body.wait }),
   };
@@ -681,10 +677,19 @@ function serializeRun(
         id: row.agent.id,
         version: row.agent.version,
         conversationId: row.agent.conversationId as unknown as string,
+        ...(row.agent.via !== undefined && { via: row.agent.via }),
+        ...(row.agent.liveScope !== undefined && {
+          liveScope: liveScopeToWire(row.agent.liveScope),
+        }),
       },
     }),
     ...(row.replayOf != null && { replayOf: row.replayOf as unknown as string }),
     ...(row.evalRunId != null && { evalRunId: row.evalRunId }),
+    ...(row.versions != null && { versions: row.versions }),
+    ...(row.segments !== undefined &&
+      row.segments.length > 0 && {
+        segments: row.segments.map(({ key, value }) => ({ key, value })),
+      }),
   };
 }
 
@@ -776,7 +781,7 @@ function parseRunListFilter(
     return { kind: 'err', message: '`topLevel` must be `true` or `false`' };
   }
   const topLevelOnly = topLevel === 'true';
-  if (parentRunId !== undefined && !RUN_ID_RE.test(parentRunId)) {
+  if (parentRunId !== undefined && !UUID_RE.test(parentRunId)) {
     return { kind: 'err', message: '`parentRunId` must be a run id (a UUID)' };
   }
   if (parentRunId !== undefined && topLevelOnly) {
@@ -848,6 +853,7 @@ type ParsedStartRunBody =
       readonly agentId: AgentId;
       readonly agentVersion?: Semver;
       readonly projectId?: ProjectId;
+      readonly segments?: readonly ScopeSegment[];
       readonly input: unknown;
       readonly dryRun?: boolean;
       readonly wait?: boolean;
@@ -857,6 +863,7 @@ type ParsedStartRunBody =
       readonly flowId: FlowId;
       readonly flowVersion?: Semver;
       readonly projectId?: ProjectId;
+      readonly segments?: readonly ScopeSegment[];
       readonly input: unknown;
       readonly dryRun?: boolean;
       readonly wait?: boolean;
@@ -892,6 +899,11 @@ function parseStartRunBody(
   const options = parseStartOptions(b.options);
   if (options.kind === 'err') return options;
   const { dryRun, wait } = options.value;
+  const parsedSegments = parseSegmentsBody(b.segments);
+  if (parsedSegments.kind === 'err') {
+    return { kind: 'err', error: { code: 'bad-input', message: parsedSegments.message } };
+  }
+  const { segments } = parsedSegments;
   if (hasAgent) {
     const agentVersion = b.agentVersion;
     if (agentVersion !== undefined && typeof agentVersion !== 'string') {
@@ -914,6 +926,7 @@ function parseStartRunBody(
         agentId: b.agent as AgentId,
         ...(agentVersion !== undefined && { agentVersion: agentVersion as Semver }),
         ...(agentProjectIdRaw !== undefined && { projectId: agentProjectIdRaw as ProjectId }),
+        ...(segments !== undefined && { segments }),
         input: b.input,
         ...(dryRun !== undefined && { dryRun }),
         ...(wait !== undefined && { wait }),
@@ -941,6 +954,7 @@ function parseStartRunBody(
       flowId: b.flow as FlowId,
       ...(flowVersion !== undefined && { flowVersion: flowVersion as Semver }),
       ...(projectId !== undefined && { projectId: projectId as ProjectId }),
+      ...(segments !== undefined && { segments }),
       input: b.input,
       ...(dryRun !== undefined && { dryRun }),
       ...(wait !== undefined && { wait }),

package/src/routes/secrets.ts

@@ -160,6 +160,7 @@ export function secretsRouter(options: SecretsRouterOptions): Hono<AppEnv> {
     });
     return c.json({
       data: page.data.map(serializeSecretRecord),
+      hasMore: page.nextCursor !== undefined,
       ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
     });
   });
@@ -232,6 +233,7 @@ export function secretsRouter(options: SecretsRouterOptions): Hono<AppEnv> {
     });
     return c.json({
       data: page.data.map(serializeVersion),
+      hasMore: page.nextCursor !== undefined,
       ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
     });
   });

package/src/routes/segments.ts

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { ScopeSegment } from '@kindgi/types';
+
+/** A segment key: lowercase, like an identifier (`company`, `contact-role`). */
+const SEGMENT_KEY_RE = /^[a-z][a-z0-9_-]{0,63}$/;
+const MAX_SEGMENTS = 8;
+const MAX_VALUE_LENGTH = 256;
+
+type Parsed =
+  | { readonly kind: 'ok'; readonly segments?: readonly ScopeSegment[] }
+  | { readonly kind: 'err'; readonly message: string };
+
+function checked(segments: readonly ScopeSegment[], field: string): Parsed {
+  if (segments.length === 0) return { kind: 'ok' };
+  if (segments.length > MAX_SEGMENTS) {
+    return { kind: 'err', message: `\`${field}\` takes at most ${MAX_SEGMENTS} segments` };
+  }
+  const seen = new Set<string>();
+  for (const { key, value } of segments) {
+    if (!SEGMENT_KEY_RE.test(key)) {
+      return {
+        kind: 'err',
+        message: `\`${field}\`: a segment key is lowercase letters, digits, - and _ (starting with a letter); got "${key}"`,
+      };
+    }
+    if (seen.has(key))
+      return { kind: 'err', message: `\`${field}\`: the key "${key}" appears twice` };
+    seen.add(key);
+    if (value.length === 0 || value.length > MAX_VALUE_LENGTH) {
+      return {
+        kind: 'err',
+        message: `\`${field}\`: a segment value is 1–${MAX_VALUE_LENGTH} characters (key "${key}")`,
+      };
+    }
+  }
+  return { kind: 'ok', segments };
+}
+
+/**
+ * A run's or a pin's segment path from a JSON body: an ordered list of
+ * `{key, value}`, coarse to fine (e.g. `company` then `role`).
+ */
+export function parseSegmentsBody(raw: unknown, field = 'segments'): Parsed {
+  if (raw === undefined) return { kind: 'ok' };
+  if (!Array.isArray(raw)) {
+    return {
+      kind: 'err',
+      message: `\`${field}\` must be an array of {key, value}, coarse to fine`,
+    };
+  }
+  const segments: ScopeSegment[] = [];
+  for (const item of raw) {
+    const { key, value } = (item ?? {}) as { key?: unknown; value?: unknown };
+    if (typeof key !== 'string' || typeof value !== 'string') {
+      return { kind: 'err', message: `\`${field}\`: each segment is {key: string, value: string}` };
+    }
+    segments.push({ key, value });
+  }
+  return checked(segments, field);
+}
+
+/** The same from a query: repeated `segment=key:value`, in order. */
+export function parseSegmentsQuery(values: readonly string[]): Parsed {
+  const segments: ScopeSegment[] = [];
+  for (const raw of values) {
+    const colon = raw.indexOf(':');
+    if (colon <= 0) {
+      return { kind: 'err', message: `\`segment\` is key:value; got "${raw}"` };
+    }
+    segments.push({ key: raw.slice(0, colon), value: raw.slice(colon + 1) });
+  }
+  return checked(segments, 'segment');
+}

package/src/routes/teams.ts

@@ -10,6 +10,7 @@ import type {
   TeamBinding,
   TeamMembership,
   TeamMembershipBinding,
+  TeamMembershipUpdateRoleOutcome,
   TeamPatch,
   TeamRole,
   TeamSpec,
@@ -19,7 +20,11 @@ import type { Cursor, OrgId, TeamId, TenantId, UserId } from '@kindgi/types';
 import { statusFor, toWireError } from '../errors.js';
 import type { Authorizer } from '../middleware/authorize.js';
 import type { AppEnv } from '../types.js';
-import { slugConflictError } from './hierarchy-errors.js';
+import {
+  membershipNotKeptInStepError,
+  orgNotFoundError,
+  slugConflictError,
+} from './hierarchy-errors.js';
 import { clampLimit } from './pagination.js';
 
 /**
@@ -57,6 +62,34 @@ export function teamsRouter(
 ): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
 
+  /**
+   * Change a member's role. With an authorizer, the row and its FGA tuple
+   * change together through the tenant-hierarchy binding, or the change
+   * is refused; without one, the membership binding alone.
+   */
+  async function updateMemberRole(
+    tenantId: TenantId,
+    teamId: TeamId,
+    userId: UserId,
+    role: TeamRole,
+  ): Promise<
+    | { readonly kind: 'done'; readonly outcome: TeamMembershipUpdateRoleOutcome }
+    | { readonly kind: 'refused'; readonly error: ReturnType<typeof membershipNotKeptInStepError> }
+  > {
+    if (authorizer === undefined) {
+      return {
+        kind: 'done',
+        outcome: await membershipBinding.updateRole(tenantId, teamId, userId, role),
+      };
+    }
+    if (tenantHierarchy.updateTeamMemberRole === undefined) {
+      return { kind: 'refused', error: membershipNotKeptInStepError('updateTeamMemberRole') };
+    }
+    const res = await tenantHierarchy.updateTeamMemberRole({ tenantId, teamId, userId, role });
+    if (res.kind === 'err') throw new Error(res.error.message, { cause: res.error });
+    return { kind: 'done', outcome: res.value };
+  }
+
   // ---------- Authorization middleware ----------
   // Full PEP surface:
   //   POST /                                    → admin on tenant
@@ -201,7 +234,9 @@ export function teamsRouter(
         const error =
           result.error.code === 'slug-conflict'
             ? slugConflictError('team', spec.slug)
-            : { code: 'internal-server-error', message: result.error.message };
+            : result.error.code === 'org-not-found'
+              ? orgNotFoundError(result.error.orgId as unknown as string)
+              : { code: 'internal-server-error', message: result.error.message };
         c.status(statusFor(error.code) as never);
         return c.json(toWireError(error, requestId));
       }
@@ -209,8 +244,11 @@ export function teamsRouter(
       return c.json({ id: result.value.teamId as unknown as string });
     }
     const outcome = await binding.create(tenantId, spec);
-    if (outcome.kind === 'slug-conflict') {
-      const error = slugConflictError('team', outcome.slug);
+    if (outcome.kind === 'slug-conflict' || outcome.kind === 'org-not-found') {
+      const error =
+        outcome.kind === 'slug-conflict'
+          ? slugConflictError('team', outcome.slug)
+          : orgNotFoundError(outcome.orgId as unknown as string);
       c.status(statusFor(error.code) as never);
       return c.json(toWireError(error, requestId));
     }
@@ -358,7 +396,19 @@ export function teamsRouter(
     const tenantId = c.get('tenantId') as TenantId;
     const teamId = c.req.param('teamId') as TeamId;
     const userId = c.req.param('userId') as UserId;
-    await membershipBinding.remove(tenantId, teamId, userId);
+    // With an authorizer, the row and its FGA tuple go together, or not
+    // at all: removing the row alone would leave the permission in place.
+    if (authorizer !== undefined) {
+      if (tenantHierarchy.removeTeamMember === undefined) {
+        const refusal = membershipNotKeptInStepError('removeTeamMember');
+        c.status(statusFor(refusal.code) as never);
+        return c.json(toWireError(refusal, c.get('requestId')));
+      }
+      const res = await tenantHierarchy.removeTeamMember({ tenantId, teamId, userId });
+      if (res.kind === 'err') throw new Error(res.error.message, { cause: res.error });
+    } else {
+      await membershipBinding.remove(tenantId, teamId, userId);
+    }
     c.status(204);
     return c.body(null);
   });
@@ -398,7 +448,12 @@ export function teamsRouter(
         ),
       );
     }
-    const outcome = await membershipBinding.updateRole(tenantId, teamId, userId, b.role);
+    const updated = await updateMemberRole(tenantId, teamId, userId, b.role);
+    if (updated.kind === 'refused') {
+      c.status(statusFor(updated.error.code) as never);
+      return c.json(toWireError(updated.error, requestId));
+    }
+    const { outcome } = updated;
     if (outcome.kind === 'team-membership-not-found') {
       c.status(statusFor('team-membership-not-found') as never);
       return c.json(
@@ -542,8 +597,11 @@ export function teamsRouter(
         ),
       );
     }
-    if (outcome.kind === 'slug-conflict') {
-      const error = slugConflictError('team', outcome.slug);
+    if (outcome.kind === 'slug-conflict' || outcome.kind === 'org-not-found') {
+      const error =
+        outcome.kind === 'slug-conflict'
+          ? slugConflictError('team', outcome.slug)
+          : orgNotFoundError(outcome.orgId as unknown as string);
       c.status(statusFor(error.code) as never);
       return c.json(toWireError(error, requestId));
     }

package/src/routes/tools.ts

@@ -9,6 +9,7 @@ import type { Cursor, ProjectId, TenantId, ToolId, UserId } from '@kindgi/types'
 
 import { statusFor, toWireError } from '../errors.js';
 import type { Authorizer } from '../middleware/authorize.js';
+import { refuseWritesWhenReadOnly } from '../registry-read-only.js';
 import type { ToolRegistryBinding } from '../tool-binding.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit } from './pagination.js';
@@ -47,6 +48,12 @@ export function toolsRouter(
   onWrite?: ToolWriteHook,
 ): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
+  // A read-only registry (under `kindgi dev`, the pack's files) refuses
+  // every write before anything else runs.
+  r.use(
+    '*',
+    refuseWritesWhenReadOnly(() => binding.readOnly),
+  );
 
   // Authorization (PEP) — mirrors agents. Cascade via `tool#parent@project`
   // written in-tx by publish; direct check via `ref('tool', businessId)`.

package/src/routes/uuid-param.ts

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { MiddlewareHandler } from 'hono';
+
+import { statusFor, toWireError } from '../errors.js';
+import type { AppEnv } from '../types.js';
+
+/** A UUID, the shape of a run's and a conversation's id. */
+export const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * A path parameter that must be a UUID: one that isn't is a 400 naming
+ * it, before it reaches a query (where Postgres's uuid cast would fail it
+ * as a 500). `what` names the id, e.g. `a run id`.
+ */
+export function refuseMalformedUuidParam(param: string, what: string): MiddlewareHandler<AppEnv> {
+  return async (c, next) => {
+    if (UUID_RE.test(c.req.param(param) ?? '')) return next();
+    c.status(statusFor('bad-input') as never);
+    return c.json(
+      toWireError(
+        { code: 'bad-input', message: `\`${param}\` must be ${what} (a UUID)` },
+        c.get('requestId'),
+      ),
+    );
+  };
+}

package/src/tool-binding.ts

@@ -6,6 +6,8 @@ import type { Scope } from '@kindgi/platform';
 import type { ToolManifest } from '@kindgi/tools';
 import type { Cursor, ProjectId, Semver, TenantId, ToolId } from '@kindgi/types';
 
+import type { RegistryReadOnly } from './registry-read-only.js';
+
 /**
  * Caller-plugged surface for the tool catalog. Versioned CRUD mirroring
  * `AgentRegistryBinding` — the API package does NOT own registry
@@ -30,6 +32,13 @@ import type { Cursor, ProjectId, Semver, TenantId, ToolId } from '@kindgi/types'
  * not-found via `headExists`).
  */
 export interface ToolRegistryBinding {
+  /**
+   * Set when this registry takes no writes (under `kindgi dev`, the
+   * pack's files are the source of its tools): every write is refused
+   * with `409 registry-read-only` and this reason, before the binding is
+   * called. See `RegistryReadOnly`.
+   */
+  readonly readOnly?: RegistryReadOnly;
   /**
    * Cursor-paginated list of tools (latest active version per id).
    * Optional `nameFilter` is a prefix match on the tool id — tools use