@kindgi/platform 0.1.3 → 0.1.4-rc.1

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,73 @@ 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;
+    }
+  | {
+      /**
+       * The org the team 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 `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;
+    }
+  | {
+      /**
+       * The org the team 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 `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

@@ -35,6 +35,8 @@ export interface CreateTeamParams {
 
 export type CreateTeamError =
   | { readonly code: 'slug-conflict'; readonly message: string; readonly cause?: unknown }
+  /** `spec.orgId` isn't the tenant's: it never existed, or it was deleted. */
+  | { readonly code: 'org-not-found'; readonly message: string; readonly orgId: OrgId }
   | { readonly code: 'insert-failed'; readonly message: string; readonly cause?: unknown };
 
 export interface AddTeamMemberParams {
@@ -52,6 +54,8 @@ export interface CreateProjectParams {
 
 export type CreateProjectError =
   | { readonly code: 'slug-conflict'; readonly message: string; readonly cause?: unknown }
+  /** `spec.orgId` isn't the tenant's: it never existed, or it was deleted. */
+  | { readonly code: 'org-not-found'; readonly message: string; readonly orgId: OrgId }
   | { readonly code: 'default-conflict'; readonly message: string; readonly cause?: unknown }
   | { readonly code: 'insert-failed'; readonly message: string; readonly cause?: unknown };
 
@@ -62,10 +66,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 +111,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

package/tests/in-memory-project-binding.test.ts

@@ -7,6 +7,18 @@
  */
 
 import { makeInMemoryProjectBinding } from '../src/in-memory/project-binding.js';
-import { runProjectBindingConformance } from './project-binding.conformance.js';
+import {
+  CONFORMANCE_MISSING_ORG,
+  runProjectBindingConformance,
+} from './project-binding.conformance.js';
 
 runProjectBindingConformance(makeInMemoryProjectBinding, 'InMemoryProjectBinding');
+// With an org check: every org but the missing one is the tenant's.
+runProjectBindingConformance(
+  () =>
+    makeInMemoryProjectBinding({
+      orgExists: (_tenantId, orgId) => orgId !== CONFORMANCE_MISSING_ORG,
+    }),
+  'InMemoryProjectBinding (checking orgs)',
+  { checksOrgs: true },
+);

package/tests/in-memory-team-binding.test.ts

@@ -7,6 +7,13 @@
  */
 
 import { makeInMemoryTeamBinding } from '../src/in-memory/team-binding.js';
-import { runTeamBindingConformance } from './team-binding.conformance.js';
+import { CONFORMANCE_MISSING_ORG, runTeamBindingConformance } from './team-binding.conformance.js';
 
 runTeamBindingConformance(makeInMemoryTeamBinding, 'InMemoryTeamBinding');
+// With an org check: every org but the missing one is the tenant's.
+runTeamBindingConformance(
+  () =>
+    makeInMemoryTeamBinding({ orgExists: (_tenantId, orgId) => orgId !== CONFORMANCE_MISSING_ORG }),
+  'InMemoryTeamBinding (checking orgs)',
+  { checksOrgs: true },
+);

package/tests/org-binding.conformance.ts

@@ -14,7 +14,12 @@
  *   asserted at every reachable read op.
  * - Pagination via `Filter.cursor`.
  * - `nameContains` substring filter.
- * - `get`/`update`/`delete` behaviour on unknown orgIds.
+ * - `get`/`update`/`delete` behaviour on unknown orgIds: `update`
+ *   resolves to `org-not-found`.
+ * - Slug uniqueness within a tenant: `create` and `update` resolve to
+ *   `slug-conflict`; another tenant may reuse the slug.
+ * - `delete` (a tombstone in a durable binding): the org is unknown to
+ *   every read, its slug is free, and deleting again is a no-op.
  */
 
 import { describe, expect, it } from 'vitest';
@@ -22,10 +27,18 @@ import { describe, expect, it } from 'vitest';
 import type { OrgId, TenantId } from '@kindgi/types';
 
 import type { OrgBinding } from '../src/org-binding.js';
+import type { OrgSpec } from '../src/types.js';
 
 const T1 = 'tenant-1' as TenantId;
 const T2 = 'tenant-2' as TenantId;
 
+/** Create an org the test expects to succeed; its id. */
+async function createOrg(b: OrgBinding, tenantId: TenantId, spec: OrgSpec): Promise<OrgId> {
+  const outcome = await b.create(tenantId, spec);
+  if (outcome.kind !== 'ok') throw new Error(`expected the org to be created, got ${outcome.kind}`);
+  return outcome.orgId;
+}
+
 export function runOrgBindingConformance(
   makeBinding: () => OrgBinding,
   label = 'OrgBinding',
@@ -33,7 +46,7 @@ export function runOrgBindingConformance(
   describe(`${label} — CRUD happy paths`, () => {
     it('creates + gets an Org', async () => {
       const b = makeBinding();
-      const id = await b.create(T1, { name: 'Acme', slug: 'acme' });
+      const id = await createOrg(b, T1, { name: 'Acme', slug: 'acme' });
       const got = await b.get(T1, id);
       expect(got).toBeDefined();
       expect(got?.id).toBe(id);
@@ -44,8 +57,8 @@ export function runOrgBindingConformance(
 
     it('updates an Org partially', async () => {
       const b = makeBinding();
-      const id = await b.create(T1, { name: 'Acme', slug: 'acme' });
-      await b.update(T1, id, { name: 'Acme Corp' });
+      const id = await createOrg(b, T1, { name: 'Acme', slug: 'acme' });
+      expect(await b.update(T1, id, { name: 'Acme Corp' })).toEqual({ kind: 'ok' });
       const got = await b.get(T1, id);
       expect(got?.name).toBe('Acme Corp');
       expect(got?.slug).toBe('acme');
@@ -53,12 +66,38 @@ export function runOrgBindingConformance(
 
     it('deletes an Org', async () => {
       const b = makeBinding();
-      const id = await b.create(T1, { name: 'Acme', slug: 'acme' });
+      const id = await createOrg(b, T1, { name: 'Acme', slug: 'acme' });
       await b.delete(T1, id);
       const got = await b.get(T1, id);
       expect(got).toBeUndefined();
     });
 
+    it('a deleted Org is unknown to list and update, and deleting it again is a no-op', async () => {
+      const b = makeBinding();
+      const id = await createOrg(b, T1, { name: 'Acme', slug: 'acme' });
+      const kept = await createOrg(b, T1, { name: 'Kept', slug: 'kept' });
+      await b.delete(T1, id);
+      const page = await b.list(T1, {});
+      expect(page.items.map((o) => o.id)).toEqual([kept]);
+      expect(await b.update(T1, id, { name: 'Acme 2' })).toEqual({ kind: 'org-not-found' });
+      await b.delete(T1, id);
+      expect(await b.get(T1, kept)).toBeDefined();
+    });
+
+    it("a deleted Org's slug is free for a new Org", async () => {
+      const b = makeBinding();
+      const id = await createOrg(b, T1, { name: 'Acme', slug: 'acme' });
+      await b.delete(T1, id);
+      const again = await createOrg(b, T1, { name: 'Acme again', slug: 'acme' });
+      expect(again).not.toBe(id);
+      expect((await b.get(T1, again))?.slug).toBe('acme');
+      const other = await createOrg(b, T1, { name: 'Other', slug: 'other' });
+      expect(await b.update(T1, other, { slug: 'acme' })).toEqual({
+        kind: 'slug-conflict',
+        slug: 'acme',
+      });
+    });
+
     it('lists orgs (empty tenant)', async () => {
       const b = makeBinding();
       const page = await b.list(T1, {});
@@ -70,27 +109,28 @@ export function runOrgBindingConformance(
   describe(`${label} — cross-tenant isolation`, () => {
     it('get on tenant B for tenant-A orgId returns undefined', async () => {
       const b = makeBinding();
-      const id = await b.create(T1, { name: 'Acme', slug: 'acme' });
+      const id = await createOrg(b, T1, { name: 'Acme', slug: 'acme' });
       expect(await b.get(T2, id)).toBeUndefined();
     });
 
     it('list on tenant B does not surface tenant-A orgs', async () => {
       const b = makeBinding();
-      await b.create(T1, { name: 'Acme', slug: 'acme' });
-      await b.create(T1, { name: 'Globex', slug: 'globex' });
+      await createOrg(b, T1, { name: 'Acme', slug: 'acme' });
+      await createOrg(b, T1, { name: 'Globex', slug: 'globex' });
       const t2Page = await b.list(T2, {});
       expect(t2Page.items).toEqual([]);
     });
 
-    it('update on tenant B for tenant-A orgId errors', async () => {
+    it('update on tenant B for tenant-A orgId → org-not-found', async () => {
       const b = makeBinding();
-      const id = await b.create(T1, { name: 'Acme', slug: 'acme' });
-      await expect(b.update(T2, id, { name: 'X' })).rejects.toThrow();
+      const id = await createOrg(b, T1, { name: 'Acme', slug: 'acme' });
+      expect(await b.update(T2, id, { name: 'X' })).toEqual({ kind: 'org-not-found' });
+      expect((await b.get(T1, id))?.name).toBe('Acme');
     });
 
     it('delete on tenant B for tenant-A orgId is a no-op (does not mutate A)', async () => {
       const b = makeBinding();
-      const id = await b.create(T1, { name: 'Acme', slug: 'acme' });
+      const id = await createOrg(b, T1, { name: 'Acme', slug: 'acme' });
       await b.delete(T2, id); // no-op
       const got = await b.get(T1, id);
       expect(got).toBeDefined();
@@ -102,7 +142,7 @@ export function runOrgBindingConformance(
       const b = makeBinding();
       const created: OrgId[] = [];
       for (let i = 0; i < 5; i += 1) {
-        created.push(await b.create(T1, { name: `Org${i}`, slug: `org-${i}` }));
+        created.push(await createOrg(b, T1, { name: `Org${i}`, slug: `org-${i}` }));
       }
       const page1 = await b.list(T1, { limit: 2 });
       expect(page1.items).toHaveLength(2);
@@ -133,9 +173,9 @@ export function runOrgBindingConformance(
   describe(`${label} — nameContains filter`, () => {
     it('narrows to orgs whose name contains the substring', async () => {
       const b = makeBinding();
-      await b.create(T1, { name: 'Litigation', slug: 'lit' });
-      await b.create(T1, { name: 'Corporate', slug: 'corp' });
-      await b.create(T1, { name: 'Litigation-Sub', slug: 'lit-sub' });
+      await createOrg(b, T1, { name: 'Litigation', slug: 'lit' });
+      await createOrg(b, T1, { name: 'Corporate', slug: 'corp' });
+      await createOrg(b, T1, { name: 'Litigation-Sub', slug: 'lit-sub' });
 
       const page = await b.list(T1, { nameContains: 'Litigation' });
       expect(page.items).toHaveLength(2);
@@ -152,9 +192,9 @@ export function runOrgBindingConformance(
       expect(await b.get(T1, unknown)).toBeUndefined();
     });
 
-    it('update on unknown orgId errors', async () => {
+    it('update on unknown orgId → org-not-found', async () => {
       const b = makeBinding();
-      await expect(b.update(T1, unknown, { name: 'X' })).rejects.toThrow();
+      expect(await b.update(T1, unknown, { name: 'X' })).toEqual({ kind: 'org-not-found' });
     });
 
     it('delete on unknown orgId is a no-op', async () => {
@@ -162,4 +202,39 @@ export function runOrgBindingConformance(
       await expect(b.delete(T1, unknown)).resolves.toBeUndefined();
     });
   });
+
+  describe(`${label} — slug uniqueness`, () => {
+    it('create with a slug the tenant already has → slug-conflict', async () => {
+      const b = makeBinding();
+      await createOrg(b, T1, { name: 'Acme', slug: 'acme' });
+      expect(await b.create(T1, { name: 'Acme again', slug: 'acme' })).toEqual({
+        kind: 'slug-conflict',
+        slug: 'acme',
+      });
+      expect((await b.list(T1, {})).items).toHaveLength(1);
+    });
+
+    it('another tenant may use the same slug', async () => {
+      const b = makeBinding();
+      await createOrg(b, T1, { name: 'Acme', slug: 'acme' });
+      expect((await b.create(T2, { name: 'Acme', slug: 'acme' })).kind).toBe('ok');
+    });
+
+    it("update to another org's slug → slug-conflict; the org is unchanged", async () => {
+      const b = makeBinding();
+      await createOrg(b, T1, { name: 'Acme', slug: 'acme' });
+      const id = await createOrg(b, T1, { name: 'Globex', slug: 'globex' });
+      expect(await b.update(T1, id, { slug: 'acme' })).toEqual({
+        kind: 'slug-conflict',
+        slug: 'acme',
+      });
+      expect((await b.get(T1, id))?.slug).toBe('globex');
+    });
+
+    it('update to its own slug → ok', async () => {
+      const b = makeBinding();
+      const id = await createOrg(b, T1, { name: 'Acme', slug: 'acme' });
+      expect(await b.update(T1, id, { name: 'Acme Corp', slug: 'acme' })).toEqual({ kind: 'ok' });
+    });
+  });
 }