@kindgi/platform 0.1.3 → 0.1.4-rc.1

package/src/in-memory/project-binding.ts

@@ -13,16 +13,22 @@
  *
  * `create` enforces the `Project.isDefault = true` uniqueness
  * guardrail at write time: creating a second Default in the same
- * tenant rejects.
+ * tenant resolves to `project-default-already-exists`. A project's
+ * slug is unique within its org, and a project without an org's among
+ * the tenant's projects without one (`slug-conflict`).
  */
 
-import type { Filter, Page, ProjectId, TeamId, TenantId, UserId } from '@kindgi/types';
+import type { Filter, OrgId, Page, ProjectId, TeamId, TenantId, UserId } from '@kindgi/types';
 
 import type {
   ProjectBinding,
+  ProjectCreateOutcome,
   ProjectListFilter,
   ProjectMembershipAddInput,
+  ProjectMembershipAddOutcome,
   ProjectMembershipBinding,
+  ProjectMembershipUpdateRoleOutcome,
+  ProjectUpdateOutcome,
 } from '../project-binding.js';
 import type {
   TeamProjectGrant,
@@ -53,12 +59,21 @@ function grantKey(teamId: TeamId, projectId: ProjectId): string {
   return `${teamId}::${projectId}`;
 }
 
+/**
+ * `orgExists`: whether an org is the tenant's (live). Given, a project or
+ * team created in or moved to another org is `org-not-found`, as the
+ * durable bindings answer; absent, any `orgId` is taken as it is.
+ */
+export interface InMemoryHierarchyOptions {
+  readonly orgExists?: (tenantId: TenantId, orgId: OrgId) => boolean | Promise<boolean>;
+}
+
 /**
  * Combined factory — returns the three project-related bindings that
  * share underlying storage. Any of them can be plucked out and passed
  * individually to consumers that need just one.
  */
-export function makeInMemoryProjectBinding(): {
+export function makeInMemoryProjectBinding(options: InMemoryHierarchyOptions = {}): {
   readonly projects: ProjectBinding;
   readonly memberships: ProjectMembershipBinding;
   readonly grants: TeamProjectGrantBinding;
@@ -82,13 +97,43 @@ export function makeInMemoryProjectBinding(): {
     return false;
   }
 
+  /**
+   * Is `slug` held by another project (not `exceptId`) where a project of
+   * `orgId` lives: in that org, or, without an org, among the tenant's
+   * projects without one?
+   */
+  function slugTaken(
+    tenantId: TenantId,
+    orgId: Project['orgId'],
+    slug: string,
+    exceptId?: ProjectId,
+  ): boolean {
+    for (const row of projectRows.values()) {
+      if (
+        row.tenantId === tenantId &&
+        row.orgId === orgId &&
+        row.slug === slug &&
+        row.id !== exceptId
+      ) {
+        return true;
+      }
+    }
+    return false;
+  }
+
   const projects: ProjectBinding = {
-    async create(tenantId, spec: ProjectSpec): Promise<ProjectId> {
+    async create(tenantId, spec: ProjectSpec): Promise<ProjectCreateOutcome> {
       const isDefault = spec.isDefault === true;
+      // The Default guardrail first: a caller asking for the Default
+      // wants to hear that one exists, whatever its slug.
       if (isDefault && tenantAlreadyHasDefault(tenantId)) {
-        throw new Error(
-          `project-default-already-exists: tenant ${tenantId} already has an isDefault=true project`,
-        );
+        return { kind: 'project-default-already-exists' };
+      }
+      if (spec.orgId !== undefined && (await options.orgExists?.(tenantId, spec.orgId)) === false) {
+        return { kind: 'org-not-found', orgId: spec.orgId };
+      }
+      if (slugTaken(tenantId, spec.orgId, spec.slug)) {
+        return { kind: 'slug-conflict', slug: spec.slug };
       }
       const id = nextProjectId();
       const now = nowTimestamp();
@@ -104,7 +149,7 @@ export function makeInMemoryProjectBinding(): {
         ...(spec.description !== undefined ? { description: spec.description } : {}),
       };
       projectRows.set(id, row);
-      return id;
+      return { kind: 'ok', projectId: id };
     },
 
     async get(tenantId, projectId): Promise<Project | undefined> {
@@ -135,15 +180,31 @@ export function makeInMemoryProjectBinding(): {
       return undefined;
     },
 
-    async update(tenantId, projectId, patch: ProjectPatch): Promise<void> {
+    async update(tenantId, projectId, patch: ProjectPatch): Promise<ProjectUpdateOutcome> {
       const row = findProjectInTenant(tenantId, projectId);
       if (row === undefined) {
-        throw new Error(`project-not-found: ${projectId}`);
+        return { kind: 'project-not-found' };
       }
       let nextOrgId = row.orgId;
       if (patch.orgId !== undefined) {
         nextOrgId = patch.orgId === null ? undefined : patch.orgId;
       }
+      if (
+        patch.orgId !== undefined &&
+        patch.orgId !== null &&
+        (await options.orgExists?.(tenantId, patch.orgId)) === false
+      ) {
+        return { kind: 'org-not-found', orgId: patch.orgId };
+      }
+      // The slug it ends up with, where it ends up: a move to another org
+      // (or out of one) can meet a project with the same slug there.
+      const nextSlug = patch.slug ?? row.slug;
+      if (
+        (patch.slug !== undefined || patch.orgId !== undefined) &&
+        slugTaken(tenantId, nextOrgId, nextSlug, projectId)
+      ) {
+        return { kind: 'slug-conflict', slug: nextSlug };
+      }
       const nextDescription = patch.description ?? row.description;
       const next: Project = {
         id: row.id,
@@ -157,6 +218,7 @@ export function makeInMemoryProjectBinding(): {
         ...(nextDescription !== undefined ? { description: nextDescription } : {}),
       };
       projectRows.set(projectId, next);
+      return { kind: 'ok' };
     },
 
     async delete(tenantId, projectId): Promise<void> {
@@ -181,13 +243,13 @@ export function makeInMemoryProjectBinding(): {
   };
 
   const memberships: ProjectMembershipBinding = {
-    async add(tenantId, input: ProjectMembershipAddInput): Promise<void> {
+    async add(tenantId, input: ProjectMembershipAddInput): Promise<ProjectMembershipAddOutcome> {
       const proj = findProjectInTenant(tenantId, input.projectId);
       if (proj === undefined) {
-        throw new Error(`project-not-found: ${input.projectId}`);
+        return { kind: 'project-not-found' };
       }
       const key = projMembershipKey(input.projectId, input.userId);
-      if (membershipRows.has(key)) return;
+      if (membershipRows.has(key)) return { kind: 'ok' };
       const row: ProjectMembership = {
         projectId: input.projectId,
         userId: input.userId,
@@ -195,6 +257,7 @@ export function makeInMemoryProjectBinding(): {
         joinedAt: nowTimestamp(),
       };
       membershipRows.set(key, row);
+      return { kind: 'ok' };
     },
 
     async remove(tenantId, projectId, userId): Promise<void> {
@@ -227,17 +290,23 @@ export function makeInMemoryProjectBinding(): {
       return paginate(all, filter.limit, filter.cursor);
     },
 
-    async updateRole(tenantId, projectId, userId, role: ProjectRole): Promise<void> {
+    async updateRole(
+      tenantId,
+      projectId,
+      userId,
+      role: ProjectRole,
+    ): Promise<ProjectMembershipUpdateRoleOutcome> {
       const proj = findProjectInTenant(tenantId, projectId);
       if (proj === undefined) {
-        throw new Error(`project-not-found: ${projectId}`);
+        return { kind: 'project-not-found' };
       }
       const key = projMembershipKey(projectId, userId);
       const row = membershipRows.get(key);
       if (row === undefined) {
-        throw new Error(`project-membership-not-found: ${projectId}/${userId}`);
+        return { kind: 'project-membership-not-found' };
       }
       membershipRows.set(key, { ...row, role });
+      return { kind: 'ok' };
     },
   };
 

package/src/in-memory/team-binding.ts

@@ -15,18 +15,24 @@
  * Both factories are returned together so the two adapters share the
  * same team map (a membership add must fail cleanly for a
  * non-existent team; splitting into two disjoint factories would
- * require an extra cross-binding contract).
+ * require an extra cross-binding contract). Team slugs are unique
+ * within a tenant.
  */
 
 import type { Filter, Page, TeamId, TenantId, UserId } from '@kindgi/types';
 
 import type {
   TeamBinding,
+  TeamCreateOutcome,
   TeamListFilter,
   TeamMembershipAddInput,
+  TeamMembershipAddOutcome,
   TeamMembershipBinding,
+  TeamMembershipUpdateRoleOutcome,
+  TeamUpdateOutcome,
 } from '../team-binding.js';
 import type { Team, TeamMembership, TeamPatch, TeamRole, TeamSpec } from '../types.js';
+import type { InMemoryHierarchyOptions } from './project-binding.js';
 
 import { nowTimestamp, paginate } from './util.js';
 
@@ -46,7 +52,7 @@ function membershipKey(teamId: TeamId, userId: UserId): string {
  * (memberships reference teams; the two must agree on tenant
  * membership at every op).
  */
-export function makeInMemoryTeamBinding(): {
+export function makeInMemoryTeamBinding(options: InMemoryHierarchyOptions = {}): {
   readonly teams: TeamBinding;
   readonly memberships: TeamMembershipBinding;
 } {
@@ -59,8 +65,20 @@ export function makeInMemoryTeamBinding(): {
     return t;
   }
 
+  /** Is `slug` held by a team in the tenant other than `exceptId`? */
+  function slugTaken(tenantId: TenantId, slug: string, exceptId?: TeamId): boolean {
+    for (const row of teamRows.values()) {
+      if (row.tenantId === tenantId && row.slug === slug && row.id !== exceptId) return true;
+    }
+    return false;
+  }
+
   const teams: TeamBinding = {
-    async create(tenantId, spec: TeamSpec): Promise<TeamId> {
+    async create(tenantId, spec: TeamSpec): Promise<TeamCreateOutcome> {
+      if (spec.orgId !== undefined && (await options.orgExists?.(tenantId, spec.orgId)) === false) {
+        return { kind: 'org-not-found', orgId: spec.orgId };
+      }
+      if (slugTaken(tenantId, spec.slug)) return { kind: 'slug-conflict', slug: spec.slug };
       const id = nextTeamId();
       const now = nowTimestamp();
       const row: Team = {
@@ -74,7 +92,7 @@ export function makeInMemoryTeamBinding(): {
         ...(spec.description !== undefined ? { description: spec.description } : {}),
       };
       teamRows.set(id, row);
-      return id;
+      return { kind: 'ok', teamId: id };
     },
 
     async get(tenantId, teamId): Promise<Team | undefined> {
@@ -98,10 +116,20 @@ export function makeInMemoryTeamBinding(): {
       return paginate(all, filter.limit, filter.cursor);
     },
 
-    async update(tenantId, teamId, patch: TeamPatch): Promise<void> {
+    async update(tenantId, teamId, patch: TeamPatch): Promise<TeamUpdateOutcome> {
       const row = findTeamInTenant(tenantId, teamId);
       if (row === undefined) {
-        throw new Error(`team-not-found: ${teamId}`);
+        return { kind: 'team-not-found' };
+      }
+      if (
+        patch.orgId !== undefined &&
+        patch.orgId !== null &&
+        (await options.orgExists?.(tenantId, patch.orgId)) === false
+      ) {
+        return { kind: 'org-not-found', orgId: patch.orgId };
+      }
+      if (patch.slug !== undefined && slugTaken(tenantId, patch.slug, teamId)) {
+        return { kind: 'slug-conflict', slug: patch.slug };
       }
       // orgId patch tri-state: undefined = untouched; null = clear;
       // OrgId value = set.
@@ -121,6 +149,7 @@ export function makeInMemoryTeamBinding(): {
         ...(nextDescription !== undefined ? { description: nextDescription } : {}),
       };
       teamRows.set(teamId, next);
+      return { kind: 'ok' };
     },
 
     async delete(tenantId, teamId): Promise<void> {
@@ -137,15 +166,15 @@ export function makeInMemoryTeamBinding(): {
   };
 
   const memberships: TeamMembershipBinding = {
-    async add(tenantId, input: TeamMembershipAddInput): Promise<void> {
+    async add(tenantId, input: TeamMembershipAddInput): Promise<TeamMembershipAddOutcome> {
       const team = findTeamInTenant(tenantId, input.teamId);
       if (team === undefined) {
-        throw new Error(`team-not-found: ${input.teamId}`);
+        return { kind: 'team-not-found' };
       }
       const key = membershipKey(input.teamId, input.userId);
       if (membershipRows.has(key)) {
         // Idempotent — role mutation goes through updateRole.
-        return;
+        return { kind: 'ok' };
       }
       const row: TeamMembership = {
         teamId: input.teamId,
@@ -154,6 +183,7 @@ export function makeInMemoryTeamBinding(): {
         joinedAt: nowTimestamp(),
       };
       membershipRows.set(key, row);
+      return { kind: 'ok' };
     },
 
     async remove(tenantId, teamId, userId): Promise<void> {
@@ -187,17 +217,23 @@ export function makeInMemoryTeamBinding(): {
       return paginate(all, filter.limit, filter.cursor);
     },
 
-    async updateRole(tenantId, teamId, userId, role: TeamRole): Promise<void> {
+    async updateRole(
+      tenantId,
+      teamId,
+      userId,
+      role: TeamRole,
+    ): Promise<TeamMembershipUpdateRoleOutcome> {
       const team = findTeamInTenant(tenantId, teamId);
       if (team === undefined) {
-        throw new Error(`team-not-found: ${teamId}`);
+        return { kind: 'team-not-found' };
       }
       const key = membershipKey(teamId, userId);
       const row = membershipRows.get(key);
       if (row === undefined) {
-        throw new Error(`team-membership-not-found: ${teamId}/${userId}`);
+        return { kind: 'team-membership-not-found' };
       }
       membershipRows.set(key, { ...row, role });
+      return { kind: 'ok' };
     },
   };
 

package/src/index.ts

@@ -15,19 +15,30 @@ export { scopeKey } from './scope.js';
 
 export type {
   OrgBinding,
+  OrgCreateOutcome,
   OrgListFilter,
+  OrgDeleteConflict,
+  OrgUpdateOutcome,
 } from './org-binding.js';
 export type {
   TeamBinding,
+  TeamCreateOutcome,
   TeamListFilter,
   TeamMembershipAddInput,
+  TeamMembershipAddOutcome,
   TeamMembershipBinding,
+  TeamMembershipUpdateRoleOutcome,
+  TeamUpdateOutcome,
 } from './team-binding.js';
 export type {
   ProjectBinding,
+  ProjectCreateOutcome,
   ProjectListFilter,
   ProjectMembershipAddInput,
+  ProjectMembershipAddOutcome,
   ProjectMembershipBinding,
+  ProjectMembershipUpdateRoleOutcome,
+  ProjectUpdateOutcome,
 } from './project-binding.js';
 export type {
   TeamProjectGrant,
@@ -40,9 +51,12 @@ export {
   makeInMemoryTeamBinding,
   makeInMemoryProjectBinding,
 } from './in-memory/index.js';
+export type { InMemoryHierarchyOptions } from './in-memory/index.js';
 
 export type {
+  AddProjectMemberError,
   AddProjectMemberParams,
+  AddTeamMemberError,
   AddTeamMemberParams,
   CreateOrgError,
   CreateOrgParams,
@@ -50,7 +64,6 @@ export type {
   CreateProjectParams,
   CreateTeamError,
   CreateTeamParams,
-  MembershipMutationError,
   TenantHierarchyBinding,
   TenantSummary,
 } from './tenant-hierarchy-binding.js';

package/src/org-binding.ts

@@ -12,6 +12,12 @@
  *   `@kindgi/types` (`items` + `nextCursor`).
  * - `list` filters extend the shared `Filter` shape so every list call
  *   shares the same pagination fields.
+ * - A write the caller can get wrong (a slug already taken, a row that
+ *   doesn't exist) resolves to an outcome — a union discriminated on
+ *   `kind`, `'ok'` on success — and never rejects for it. Each
+ *   non-`ok` `kind` is also the API error code the routes answer with
+ *   (`slug-conflict` is a 409, `org-not-found` a 404). A rejected
+ *   promise means the backend failed.
  *
  * This package ships the interface + reference in-memory adapter
  * (in `./in-memory/org-binding.ts`). Any adapter can be checked with
@@ -43,11 +49,13 @@ export interface OrgListFilter extends Filter {
  */
 export interface OrgBinding {
   /**
-   * Create a new `Org` in the given tenant. Returns the freshly-
-   * assigned `OrgId`. The binding is responsible for allocating IDs,
-   * timestamps, and slug-uniqueness enforcement within the tenant.
+   * Create a new `Org` in the given tenant. Resolves to `ok` with the
+   * freshly-assigned `OrgId`, or to `slug-conflict` when another org in
+   * the tenant has `spec.slug`. The binding is responsible for
+   * allocating IDs, timestamps, and slug-uniqueness enforcement within
+   * the tenant.
    */
-  create(tenantId: TenantId, spec: OrgSpec): Promise<OrgId>;
+  create(tenantId: TenantId, spec: OrgSpec): Promise<OrgCreateOutcome>;
   /**
    * Look up an `Org` by id. Returns `undefined` when no row exists in
    * the given tenant, or when the row exists in a different tenant
@@ -62,15 +70,55 @@ export interface OrgBinding {
   list(tenantId: TenantId, filter: OrgListFilter): Promise<Page<Org>>;
   /**
    * Partially update an `Org`. Fields absent from `patch` are left
-   * unchanged; fields present are set to the new value. Not-found is
-   * an error the adapter surfaces (e.g. as a rejected promise); the
-   * conformance suite specifies the exact shape.
+   * unchanged; fields present are set to the new value. Resolves to
+   * `org-not-found` when no org has `orgId` in the tenant, and to
+   * `slug-conflict` when `patch.slug` is another org's slug.
    */
-  update(tenantId: TenantId, orgId: OrgId, patch: OrgPatch): Promise<void>;
+  update(tenantId: TenantId, orgId: OrgId, patch: OrgPatch): Promise<OrgUpdateOutcome>;
   /**
-   * Delete an `Org`. Cascade semantics (dependent teams / projects) are
-   * a storage-layer concern — the in-memory adapter does the delete
-   * unconditionally.
+   * Delete an `Org`: a tombstone, not an erase. From then on `get`,
+   * `list` and `update` treat it as unknown, and its slug is free for a
+   * new org; a retention policy on the `org` domain purges the row.
+   * What happens to dependents (teams, projects, org-scoped config) is
+   * the storage's concern; the in-memory adapter has none. A storage
+   * whose projects leave a deleted org (the Kindgi runtime's: they
+   * become projects without an org) answers `slug-conflict` instead
+   * when one of them has the slug of a project that has no org, and
+   * deletes nothing. Nothing (`void`): the org is deleted, or wasn't
+   * there (or was already deleted).
    */
-  delete(tenantId: TenantId, orgId: OrgId): Promise<void>;
+  // biome-ignore lint/suspicious/noConfusingVoidType: `void`, not `undefined`, so a binding whose `delete` returns `Promise<void>` still conforms.
+  delete(tenantId: TenantId, orgId: OrgId): Promise<void | OrgDeleteConflict>;
 }
+
+/**
+ * Why `OrgBinding.delete` deleted nothing: the org's projects would leave
+ * it with `slugs` that projects without an org already have. Rename or
+ * move them first.
+ */
+export interface OrgDeleteConflict {
+  readonly kind: 'slug-conflict';
+  readonly slugs: readonly string[];
+}
+
+/** What `OrgBinding.create` did. */
+export type OrgCreateOutcome =
+  | { readonly kind: 'ok'; readonly orgId: OrgId }
+  | {
+      /** Another org in the tenant already has this slug. */
+      readonly kind: 'slug-conflict';
+      readonly slug: string;
+    };
+
+/** What `OrgBinding.update` did. */
+export type OrgUpdateOutcome =
+  | { readonly kind: 'ok' }
+  | {
+      /** No org with this id in the tenant. */
+      readonly kind: 'org-not-found';
+    }
+  | {
+      /** Another org in the tenant already has the patched slug. */
+      readonly kind: 'slug-conflict';
+      readonly slug: string;
+    };

package/src/project-binding.ts

@@ -20,7 +20,9 @@
  * `AgentPublishInput.projectId` in `@kindgi/api`).
  *
  * Same convention as `org-binding.ts`: `tenantId` first, `Page<T>`
- * return, `Filter`-extending filter shapes.
+ * return, `Filter`-extending filter shapes, and writes the caller can
+ * get wrong resolve to an outcome discriminated on `kind` instead of
+ * rejecting.
  */
 
 import type { Filter, OrgId, Page, ProjectId, TenantId, UserId } from '@kindgi/types';
@@ -58,12 +60,14 @@ export interface ProjectMembershipAddInput {
  */
 export interface ProjectBinding {
   /**
-   * Create a `Project` within the tenant. `spec.orgId` optional. If
-   * `spec.isDefault === true` and a Default already exists, the
-   * binding rejects — the isDefault-uniqueness guardrail is enforced
-   * at write time.
+   * Create a `Project` within the tenant. `spec.orgId` optional.
+   * Resolves to `ok` with the assigned `ProjectId`; to `slug-conflict`
+   * when another project in the tenant has `spec.slug`; and, when
+   * `spec.isDefault === true` and the tenant already has a Default, to
+   * `project-default-already-exists` — the isDefault-uniqueness
+   * guardrail is enforced at write time.
    */
-  create(tenantId: TenantId, spec: ProjectSpec): Promise<ProjectId>;
+  create(tenantId: TenantId, spec: ProjectSpec): Promise<ProjectCreateOutcome>;
   /**
    * Look up a `Project` by id. `undefined` when unknown or in a
    * different tenant.
@@ -81,9 +85,15 @@ export interface ProjectBinding {
   getDefault(tenantId: TenantId): Promise<Project | undefined>;
   /**
    * Partially update a `Project`. `ProjectPatch.orgId` supports
-   * `null` to re-assign the project out of any org.
+   * `null` to re-assign the project out of any org. Resolves to
+   * `project-not-found` when no project has `projectId` in the tenant,
+   * and to `slug-conflict` when `patch.slug` is another project's slug.
    */
-  update(tenantId: TenantId, projectId: ProjectId, patch: ProjectPatch): Promise<void>;
+  update(
+    tenantId: TenantId,
+    projectId: ProjectId,
+    patch: ProjectPatch,
+  ): Promise<ProjectUpdateOutcome>;
   /**
    * Delete a `Project`. What happens to content rows that still
    * reference the project is the storage layer's concern; the
@@ -104,8 +114,10 @@ export interface ProjectMembershipBinding {
    * Add a user directly to a project. Idempotent on
    * `(projectId, userId)` — re-adding the same user does not mutate
    * a stored differing role. Use `updateRole` to change roles.
+   * Resolves to `project-not-found` when no project has
+   * `input.projectId` in the tenant.
    */
-  add(tenantId: TenantId, input: ProjectMembershipAddInput): Promise<void>;
+  add(tenantId: TenantId, input: ProjectMembershipAddInput): Promise<ProjectMembershipAddOutcome>;
   /**
    * Remove the direct project grant. No-op when absent.
    */
@@ -122,13 +134,77 @@ export interface ProjectMembershipBinding {
    */
   listForUser(tenantId: TenantId, userId: UserId, filter: Filter): Promise<Page<ProjectMembership>>;
   /**
-   * Update an existing direct-membership's role. Errors when the
-   * membership doesn't exist.
+   * Update an existing direct-membership's role. Resolves to
+   * `project-not-found` when the project isn't in the tenant, and to
+   * `project-membership-not-found` when the user has no direct
+   * membership.
    */
   updateRole(
     tenantId: TenantId,
     projectId: ProjectId,
     userId: UserId,
     role: ProjectRole,
-  ): Promise<void>;
+  ): Promise<ProjectMembershipUpdateRoleOutcome>;
 }
+
+/** What `ProjectBinding.create` did. */
+export type ProjectCreateOutcome =
+  | { readonly kind: 'ok'; readonly projectId: ProjectId }
+  | {
+      /** Another project in the tenant already has this slug. */
+      readonly kind: 'slug-conflict';
+      readonly slug: string;
+    }
+  | {
+      /** `spec.isDefault` was `true` and the tenant already has a Default project. */
+      readonly kind: 'project-default-already-exists';
+    }
+  | {
+      /**
+       * The org the project would be in isn't one of the tenant's: it never
+       * existed, or it was deleted. Nothing changed.
+       */
+      readonly kind: 'org-not-found';
+      readonly orgId: OrgId;
+    };
+
+/** What `ProjectBinding.update` did. */
+export type ProjectUpdateOutcome =
+  | { readonly kind: 'ok' }
+  | {
+      /** No project with this id in the tenant. */
+      readonly kind: 'project-not-found';
+    }
+  | {
+      /** Another project in the tenant already has the patched slug. */
+      readonly kind: 'slug-conflict';
+      readonly slug: string;
+    }
+  | {
+      /**
+       * The org the project would be in isn't one of the tenant's: it never
+       * existed, or it was deleted. Nothing changed.
+       */
+      readonly kind: 'org-not-found';
+      readonly orgId: OrgId;
+    };
+
+/** What `ProjectMembershipBinding.add` did (`ok` when already a member, too). */
+export type ProjectMembershipAddOutcome =
+  | { readonly kind: 'ok' }
+  | {
+      /** No project with this id in the tenant. */
+      readonly kind: 'project-not-found';
+    };
+
+/** What `ProjectMembershipBinding.updateRole` did. */
+export type ProjectMembershipUpdateRoleOutcome =
+  | { readonly kind: 'ok' }
+  | {
+      /** No project with this id in the tenant. */
+      readonly kind: 'project-not-found';
+    }
+  | {
+      /** The user has no direct membership on the project. */
+      readonly kind: 'project-membership-not-found';
+    };