@kindgi/platform 0.1.3 → 0.1.4-rc.0

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

@@ -15,16 +15,21 @@
  * 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';
 
@@ -59,8 +64,17 @@ 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 (slugTaken(tenantId, spec.slug)) return { kind: 'slug-conflict', slug: spec.slug };
       const id = nextTeamId();
       const now = nowTimestamp();
       const row: Team = {
@@ -74,7 +88,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 +112,13 @@ 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.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 +138,7 @@ export function makeInMemoryTeamBinding(): {
         ...(nextDescription !== undefined ? { description: nextDescription } : {}),
       };
       teamRows.set(teamId, next);
+      return { kind: 'ok' };
     },
 
     async delete(tenantId, teamId): Promise<void> {
@@ -137,15 +155,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 +172,7 @@ export function makeInMemoryTeamBinding(): {
         joinedAt: nowTimestamp(),
       };
       membershipRows.set(key, row);
+      return { kind: 'ok' };
     },
 
     async remove(tenantId, teamId, userId): Promise<void> {
@@ -187,17 +206,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,
@@ -42,7 +53,9 @@ export {
 } from './in-memory/index.js';
 
 export type {
+  AddProjectMemberError,
   AddProjectMemberParams,
+  AddTeamMemberError,
   AddTeamMemberParams,
   CreateOrgError,
   CreateOrgParams,
@@ -50,7 +63,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,61 @@ 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';
+    };
+
+/** 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;
+    };
+
+/** 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';
+    };

package/src/team-binding.ts

@@ -10,7 +10,9 @@
  * truth.
  *
  * 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, TeamId, TenantId, UserId } from '@kindgi/types';
@@ -46,10 +48,11 @@ export interface TeamMembershipAddInput {
 export interface TeamBinding {
   /**
    * Create a `Team` within the tenant. `spec.orgId` optional (a team
-   * may be cross-org — nullable FK). Returns the assigned
-   * `TeamId`.
+   * may be cross-org — nullable FK). Resolves to `ok` with the
+   * assigned `TeamId`, or to `slug-conflict` when another team in the
+   * tenant has `spec.slug`.
    */
-  create(tenantId: TenantId, spec: TeamSpec): Promise<TeamId>;
+  create(tenantId: TenantId, spec: TeamSpec): Promise<TeamCreateOutcome>;
   /**
    * Look up a `Team` by id. `undefined` when unknown or in a different
    * tenant.
@@ -63,9 +66,11 @@ export interface TeamBinding {
   /**
    * Partially update a `Team`. `TeamPatch.orgId` supports `null` to
    * explicitly re-assign the team out of any org (cross-org), and
-   * `undefined` to leave the FK untouched.
+   * `undefined` to leave the FK untouched. Resolves to `team-not-found`
+   * when no team has `teamId` in the tenant, and to `slug-conflict`
+   * when `patch.slug` is another team's slug.
    */
-  update(tenantId: TenantId, teamId: TeamId, patch: TeamPatch): Promise<void>;
+  update(tenantId: TenantId, teamId: TeamId, patch: TeamPatch): Promise<TeamUpdateOutcome>;
   /**
    * Delete a `Team`. Its membership rows are removed with it (the
    * in-memory adapter deletes them from its map).
@@ -88,9 +93,10 @@ export interface TeamMembershipBinding {
    * silently mutate a differing role).
    *
    * The conformance suite pins this: adding an existing member whose
-   * stored role differs is a no-op (not a role overwrite).
+   * stored role differs is a no-op (not a role overwrite). Resolves to
+   * `team-not-found` when no team has `input.teamId` in the tenant.
    */
-  add(tenantId: TenantId, input: TeamMembershipAddInput): Promise<void>;
+  add(tenantId: TenantId, input: TeamMembershipAddInput): Promise<TeamMembershipAddOutcome>;
   /**
    * Remove a user from a team. Missing membership is a no-op (not an
    * error) — matches every peer platform's membership-remove shape.
@@ -108,9 +114,57 @@ export interface TeamMembershipBinding {
    */
   listForUser(tenantId: TenantId, userId: UserId, filter: Filter): Promise<Page<TeamMembership>>;
   /**
-   * Update an existing membership's role. Errors when the membership
-   * doesn't exist — role mutation of a non-member is a caller mistake,
-   * not a silent add. Conformance suite pins the not-found behaviour.
+   * Update an existing membership's role. Resolves to `team-not-found`
+   * when the team isn't in the tenant, and to
+   * `team-membership-not-found` when the user isn't a member — role
+   * mutation of a non-member is a caller mistake, not a silent add.
    */
-  updateRole(tenantId: TenantId, teamId: TeamId, userId: UserId, role: TeamRole): Promise<void>;
+  updateRole(
+    tenantId: TenantId,
+    teamId: TeamId,
+    userId: UserId,
+    role: TeamRole,
+  ): Promise<TeamMembershipUpdateRoleOutcome>;
 }
+
+/** What `TeamBinding.create` did. */
+export type TeamCreateOutcome =
+  | { readonly kind: 'ok'; readonly teamId: TeamId }
+  | {
+      /** Another team in the tenant already has this slug. */
+      readonly kind: 'slug-conflict';
+      readonly slug: string;
+    };
+
+/** What `TeamBinding.update` did. */
+export type TeamUpdateOutcome =
+  | { readonly kind: 'ok' }
+  | {
+      /** No team with this id in the tenant. */
+      readonly kind: 'team-not-found';
+    }
+  | {
+      /** Another team in the tenant already has the patched slug. */
+      readonly kind: 'slug-conflict';
+      readonly slug: string;
+    };
+
+/** What `TeamMembershipBinding.add` did (`ok` when already a member, too). */
+export type TeamMembershipAddOutcome =
+  | { readonly kind: 'ok' }
+  | {
+      /** No team with this id in the tenant. */
+      readonly kind: 'team-not-found';
+    };
+
+/** What `TeamMembershipBinding.updateRole` did. */
+export type TeamMembershipUpdateRoleOutcome =
+  | { readonly kind: 'ok' }
+  | {
+      /** No team with this id in the tenant. */
+      readonly kind: 'team-not-found';
+    }
+  | {
+      /** The user isn't a member of the team. */
+      readonly kind: 'team-membership-not-found';
+    };

package/src/tenant-hierarchy-binding.ts

@@ -62,10 +62,21 @@ export interface AddProjectMemberParams {
   readonly role: ProjectRole;
 }
 
-export interface MembershipMutationError {
-  readonly code: string;
-  readonly message: string;
-}
+export type AddTeamMemberError =
+  | {
+      /** No team with this id in the tenant. */
+      readonly code: 'team-not-found';
+      readonly message: string;
+    }
+  | { readonly code: 'add-failed'; readonly message: string; readonly cause?: unknown };
+
+export type AddProjectMemberError =
+  | {
+      /** No project with this id in the tenant. */
+      readonly code: 'project-not-found';
+      readonly message: string;
+    }
+  | { readonly code: 'add-failed'; readonly message: string; readonly cause?: unknown };
 
 /**
  * Tenant-summary read shape returned by `getTenant`. Only the fields
@@ -96,8 +107,8 @@ export interface TenantHierarchyBinding {
   createProject(
     params: CreateProjectParams,
   ): Promise<Result<{ readonly projectId: ProjectId }, CreateProjectError>>;
-  addTeamMember(params: AddTeamMemberParams): Promise<Result<void, MembershipMutationError>>;
-  addProjectMember(params: AddProjectMemberParams): Promise<Result<void, MembershipMutationError>>;
+  addTeamMember(params: AddTeamMemberParams): Promise<Result<void, AddTeamMemberError>>;
+  addProjectMember(params: AddProjectMemberParams): Promise<Result<void, AddProjectMemberError>>;
   /**
    * Look up a tenant by id. Returns `null` when no tenant exists.
    * Not itself tenant-scoped: it is how a caller finds out which