@kindgi/platform 0.0.0-bootstrap.0 → 0.1.0

package/src/team-binding.ts

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * `TeamBinding` + `TeamMembershipBinding` — the team CRUD surface + the
+ * user↔team membership surface within a tenant.
+ *
+ * Team memberships are **framework-owned**: there is no external
+ * directory sync. `TeamMembershipBinding` is the sole source of
+ * truth.
+ *
+ * Same convention as `org-binding.ts`: `tenantId` first, `Page<T>`
+ * return, `Filter`-extending filter shapes.
+ */
+
+import type { Filter, OrgId, Page, TeamId, TenantId, UserId } from '@kindgi/types';
+
+import type { Team, TeamMembership, TeamPatch, TeamRole, TeamSpec } from './types.js';
+
+/**
+ * `list` filter for teams. `orgId` narrows to teams belonging to a
+ * specific org (the `Team.orgId?` nullable FK); absent =
+ * no org filter, including cross-org teams. `nameContains` mirrors
+ * the org shape.
+ */
+export interface TeamListFilter extends Filter {
+  readonly orgId?: OrgId;
+  readonly nameContains?: string;
+}
+
+/**
+ * Input for `TeamMembershipBinding.add`. Distinct interface (not
+ * positional args) so downstream additions — e.g., an `addedBy?:
+ * UserId` audit field added later — extend without breaking
+ * every call site.
+ */
+export interface TeamMembershipAddInput {
+  readonly teamId: TeamId;
+  readonly userId: UserId;
+  readonly role: TeamRole;
+}
+
+/**
+ * The team CRUD binding.
+ */
+export interface TeamBinding {
+  /**
+   * Create a `Team` within the tenant. `spec.orgId` optional (a team
+   * may be cross-org — nullable FK). Returns the assigned
+   * `TeamId`.
+   */
+  create(tenantId: TenantId, spec: TeamSpec): Promise<TeamId>;
+  /**
+   * Look up a `Team` by id. `undefined` when unknown or in a different
+   * tenant.
+   */
+  get(tenantId: TenantId, teamId: TeamId): Promise<Team | undefined>;
+  /**
+   * Cursor-paginated list of teams. Filter by `orgId` (narrow to one
+   * org's teams) or `nameContains` (substring match on `Team.name`).
+   */
+  list(tenantId: TenantId, filter: TeamListFilter): Promise<Page<Team>>;
+  /**
+   * 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.
+   */
+  update(tenantId: TenantId, teamId: TeamId, patch: TeamPatch): Promise<void>;
+  /**
+   * Delete a `Team`. Its membership rows are removed with it (the
+   * in-memory adapter deletes them from its map).
+   */
+  delete(tenantId: TenantId, teamId: TeamId): Promise<void>;
+}
+
+/**
+ * User↔team membership CRUD. Typical consumers: identity views that
+ * show a user's teams, and authorization, where the `team:T#member`
+ * userset (see `@kindgi/authz`) gives members access to projects
+ * through a team-project grant.
+ */
+export interface TeamMembershipBinding {
+  /**
+   * Add a user to a team with a given role. Idempotent on the
+   * `(teamId, userId)` primary key — re-adding the same user does not
+   * duplicate the row. To change an existing member's role use
+   * `updateRole` (semantics are explicit; add-with-role does not
+   * 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).
+   */
+  add(tenantId: TenantId, input: TeamMembershipAddInput): Promise<void>;
+  /**
+   * Remove a user from a team. Missing membership is a no-op (not an
+   * error) — matches every peer platform's membership-remove shape.
+   */
+  remove(tenantId: TenantId, teamId: TeamId, userId: UserId): Promise<void>;
+  /**
+   * Cursor-paginated memberships of a team. Ordered by `joinedAt`
+   * ascending; the conformance suite pins this ordering.
+   */
+  list(tenantId: TenantId, teamId: TeamId, filter: Filter): Promise<Page<TeamMembership>>;
+  /**
+   * Cursor-paginated memberships of a user (across every team the
+   * user belongs to within the tenant). Used to resolve a user's team
+   * set (identity views, authorization inheritance).
+   */
+  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.
+   */
+  updateRole(tenantId: TenantId, teamId: TeamId, userId: UserId, role: TeamRole): Promise<void>;
+}

package/src/team-project-grant-binding.ts

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * `TeamProjectGrant` — the team↔project join surface. One row per
+ * `(teamId, projectId)` primary key; the `role` names the project-
+ * scope grant every team member inherits via the FGA `team:T#member`
+ * userset (see `@kindgi/authz`).
+ *
+ * Same tenant-first convention as every other binding in
+ * `@kindgi/platform`. The in-memory reference implementation is part
+ * of `makeInMemoryProjectBinding` (its `grants` binding).
+ */
+
+import type { Filter, Page, ProjectId, TeamId, TenantId } from '@kindgi/types';
+
+import type { ProjectRole } from './types.js';
+
+/**
+ * A team-mediated grant on a project. The `role` uses the same
+ * `ProjectRole` union as direct `ProjectMembership.role` — semantics
+ * compose (the authorization model resolves the union / inheritance).
+ */
+export interface TeamProjectGrant {
+  readonly teamId: TeamId;
+  readonly projectId: ProjectId;
+  readonly role: ProjectRole;
+}
+
+export interface TeamProjectGrantAddInput {
+  readonly teamId: TeamId;
+  readonly projectId: ProjectId;
+  readonly role: ProjectRole;
+}
+
+/**
+ * CRUD for team↔project grants.
+ */
+export interface TeamProjectGrantBinding {
+  /**
+   * Add a team-project grant. Idempotent on `(teamId, projectId)` —
+   * re-adding the same team on the same project does not mutate a
+   * stored differing role. Use `updateRole` to change roles.
+   */
+  add(tenantId: TenantId, input: TeamProjectGrantAddInput): Promise<void>;
+  /** Remove a team-project grant. No-op when absent. */
+  remove(tenantId: TenantId, teamId: TeamId, projectId: ProjectId): Promise<void>;
+  /** Cursor-paginated grants filtered by tenant. */
+  list(tenantId: TenantId, filter: Filter): Promise<Page<TeamProjectGrant>>;
+  /** Cursor-paginated grants for a specific team. */
+  listForTeam(tenantId: TenantId, teamId: TeamId, filter: Filter): Promise<Page<TeamProjectGrant>>;
+  /** Cursor-paginated grants for a specific project. */
+  listForProject(
+    tenantId: TenantId,
+    projectId: ProjectId,
+    filter: Filter,
+  ): Promise<Page<TeamProjectGrant>>;
+  /** Update a grant's role. Errors when the grant doesn't exist. */
+  updateRole(
+    tenantId: TenantId,
+    teamId: TeamId,
+    projectId: ProjectId,
+    role: ProjectRole,
+  ): Promise<void>;
+}

package/src/tenant-hierarchy-binding.ts

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+//
+// TenantHierarchyBinding — the public shape for Org/Team/Project CRUD
+// operations that write authz tuples in the same transaction as the
+// entity insert. Implementations are supplied by the deployment and
+// plugged in via `CreateAppInput.tenantHierarchyBinding` in
+// `@kindgi/api`.
+//
+// The `Params` shapes are self-contained — reference only public
+// types from @kindgi/{platform,types}. Error shapes are structural
+// so callers don't need to import an Error type from any
+// implementation.
+//
+
+import type { OrgId, ProjectId, Result, TeamId, TenantId, UserId } from '@kindgi/types';
+import type { OrgSpec, ProjectRole, ProjectSpec, TeamRole, TeamSpec } from './types.js';
+
+export interface CreateOrgParams {
+  readonly tenantId: TenantId;
+  readonly creatorUserId: UserId;
+  readonly spec: OrgSpec;
+}
+
+export type CreateOrgError =
+  | { readonly code: 'slug-conflict'; readonly message: string; readonly cause?: unknown }
+  | { readonly code: 'insert-failed'; readonly message: string; readonly cause?: unknown };
+
+export interface CreateTeamParams {
+  readonly tenantId: TenantId;
+  readonly creatorUserId: UserId;
+  readonly spec: TeamSpec;
+}
+
+export type CreateTeamError =
+  | { readonly code: 'slug-conflict'; readonly message: string; readonly cause?: unknown }
+  | { readonly code: 'insert-failed'; readonly message: string; readonly cause?: unknown };
+
+export interface AddTeamMemberParams {
+  readonly tenantId: TenantId;
+  readonly teamId: TeamId;
+  readonly userId: UserId;
+  readonly role: TeamRole;
+}
+
+export interface CreateProjectParams {
+  readonly tenantId: TenantId;
+  readonly creatorUserId: UserId;
+  readonly spec: ProjectSpec;
+}
+
+export type CreateProjectError =
+  | { readonly code: 'slug-conflict'; readonly message: string; readonly cause?: unknown }
+  | { readonly code: 'default-conflict'; readonly message: string; readonly cause?: unknown }
+  | { readonly code: 'insert-failed'; readonly message: string; readonly cause?: unknown };
+
+export interface AddProjectMemberParams {
+  readonly tenantId: TenantId;
+  readonly projectId: ProjectId;
+  readonly userId: UserId;
+  readonly role: ProjectRole;
+}
+
+export interface MembershipMutationError {
+  readonly code: string;
+  readonly message: string;
+}
+
+/**
+ * Tenant-summary read shape returned by `getTenant`. Only the fields
+ * the `/v1/tenant` GET route surfaces — id / name / slug / createdAt /
+ * updatedAt. Timestamps are ISO 8601 strings; impls that hold Date
+ * objects convert at the boundary.
+ */
+export interface TenantSummary {
+  readonly id: TenantId;
+  readonly name: string;
+  readonly slug: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}
+
+/**
+ * Tenant-hierarchy CRUD binding. Every route that creates orgs /
+ * teams / projects or adds members writes atomically: entity insert
+ * + FGA parent/owner tuples in the same transaction.
+ *
+ * Deployments supply the implementation; tests can substitute a mock.
+ */
+export interface TenantHierarchyBinding {
+  createOrg(params: CreateOrgParams): Promise<Result<{ readonly orgId: OrgId }, CreateOrgError>>;
+  createTeam(
+    params: CreateTeamParams,
+  ): Promise<Result<{ readonly teamId: TeamId }, CreateTeamError>>;
+  createProject(
+    params: CreateProjectParams,
+  ): Promise<Result<{ readonly projectId: ProjectId }, CreateProjectError>>;
+  addTeamMember(params: AddTeamMemberParams): Promise<Result<void, MembershipMutationError>>;
+  addProjectMember(params: AddProjectMemberParams): Promise<Result<void, MembershipMutationError>>;
+  /**
+   * Look up a tenant by id. Returns `null` when no tenant exists.
+   * Not itself tenant-scoped: it is how a caller finds out which
+   * tenant it is operating as.
+   */
+  getTenant(tenantId: TenantId): Promise<TenantSummary | null>;
+}

package/src/types.ts

@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Multi-tenant hierarchy primitives — the type surface for the
+ * `Tenant → Org → Team → Project + User` flow.
+ *
+ * **Pure type shapes.** No runtime code, no validation, no defaults.
+ * Binding interfaces live in the sibling `*-binding.ts` files;
+ * reference in-memory adapters live under `in-memory/`.
+ *
+ * Branded IDs are imported from `@kindgi/types` — this package
+ * adds no new IDs. `Tenant` itself has no full shape here (only the
+ * read-only `TenantSummary` in `tenant-hierarchy-binding.ts`); this
+ * package models the hierarchy that sits *under* the tenant.
+ */
+
+import type { OrgId, ProjectId, TeamId, TenantId, Timestamp, UserId } from '@kindgi/types';
+
+// ============================================================
+// Org — optional structural subdivision within a tenant.
+// A firm's litigation department; a hospital's cardiology; a bank's
+// commercial-lending LOB. Small tenants ignore Org entirely (no rows,
+// no reference on child entities). Large tenants use Org to enforce
+// structural boundaries.
+// ============================================================
+
+export interface Org {
+  readonly id: OrgId;
+  readonly tenantId: TenantId;
+  readonly name: string;
+  readonly slug: string;
+  readonly createdAt: Timestamp;
+  readonly updatedAt: Timestamp;
+}
+
+export interface OrgSpec {
+  readonly name: string;
+  readonly slug: string;
+}
+
+export interface OrgPatch {
+  readonly name?: string;
+  readonly slug?: string;
+}
+
+// ============================================================
+// Team — people-group. A named collection of users who work together.
+// A matter team; a care team; a deal team. Users belong to many teams.
+// Same team works on many projects; same project can have many teams
+// collaborating. Distinct from Org (structural) — Team is about
+// *working groups*, which cross Org boundaries. Team↔Project is N..N
+// via `TeamProjectGrant`.
+// ============================================================
+
+export interface Team {
+  readonly id: TeamId;
+  readonly tenantId: TenantId;
+  /**
+   * Optional — a team may belong to an org, or be cross-org (no
+   * `orgId`).
+   */
+  readonly orgId?: OrgId;
+  readonly name: string;
+  readonly slug: string;
+  readonly description?: string;
+  readonly createdAt: Timestamp;
+  readonly updatedAt: Timestamp;
+}
+
+export interface TeamSpec {
+  readonly name: string;
+  readonly slug: string;
+  readonly description?: string;
+  readonly orgId?: OrgId;
+}
+
+export interface TeamPatch {
+  readonly name?: string;
+  readonly slug?: string;
+  readonly description?: string;
+  /**
+   * `null` explicitly re-assigns the team out of any org (cross-org).
+   * `undefined` leaves the FK untouched.
+   */
+  readonly orgId?: OrgId | null;
+}
+
+/**
+ * Roles on a `TeamMembership`. Aligned with org/project vocabulary:
+ * `admin` + `member`. Additive with project-level grants: a user in
+ * three teams has the union of the three teams' project grants.
+ * Framework-owned — no external directory sync.
+ */
+export type TeamRole = 'member' | 'admin';
+
+export interface TeamMembership {
+  readonly teamId: TeamId;
+  readonly userId: UserId;
+  readonly role: TeamRole;
+  readonly joinedAt: Timestamp;
+}
+
+// ============================================================
+// Project — the primary content-scope. Facts, artifacts, runs, blobs,
+// evidence, approvals belong to a Project. Vertical-agnostic on the
+// wire; verticalized in packs (`Matter` in legal, `Case` in HR,
+// `Engagement` in accounting, `Episode` in healthcare, `Deal` in
+// finance).
+//
+// `isDefault` marks the auto-created "Default" project per tenant.
+// Implementations keep exactly one per tenant (the in-memory adapter
+// rejects a second Default on `create`).
+// ============================================================
+
+export interface Project {
+  readonly id: ProjectId;
+  readonly tenantId: TenantId;
+  /**
+   * Optional — a project may belong to an org, or be cross-org (no
+   * `orgId`).
+   */
+  readonly orgId?: OrgId;
+  readonly name: string;
+  readonly slug: string;
+  /**
+   * `true` for the tenant's auto-created "Default" project. Exactly
+   * one row per tenant carries `isDefault = true`.
+   * `false` for every user-created project.
+   */
+  readonly isDefault: boolean;
+  readonly description?: string;
+  readonly createdAt: Timestamp;
+  readonly updatedAt: Timestamp;
+}
+
+export interface ProjectSpec {
+  readonly name: string;
+  readonly slug: string;
+  readonly description?: string;
+  readonly orgId?: OrgId;
+  /**
+   * Optional at spec time — the tenant's Default project is created
+   * by the framework at tenant-inception, not by a caller. User
+   * projects created via `POST /v1/projects` default to `false`.
+   */
+  readonly isDefault?: boolean;
+}
+
+export interface ProjectPatch {
+  readonly name?: string;
+  readonly slug?: string;
+  readonly description?: string;
+  /**
+   * `null` explicitly re-assigns the project out of any org.
+   * `undefined` leaves the FK untouched.
+   */
+  readonly orgId?: OrgId | null;
+}
+
+/**
+ * Roles on a `ProjectMembership` — the direct `User → Project` grant
+ * shape. Additive with team-grants. Mirrors the OpenFGA project-type
+ * relations (owner / editor / viewer) plus the
+ * lightweight `member` and administrative `admin` shorthands.
+ */
+export type ProjectRole = 'viewer' | 'editor' | 'owner' | 'admin' | 'member';
+
+export interface ProjectMembership {
+  readonly projectId: ProjectId;
+  readonly userId: UserId;
+  readonly role: ProjectRole;
+  readonly joinedAt: Timestamp;
+}
+
+// Authorization types (object types, actions, tuples, checks) live in
+// `@kindgi/authz`.

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

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Wire the shared `runOrgBindingConformance` suite against the
+ * in-memory reference adapter.
+ */
+
+import { makeInMemoryOrgBinding } from '../src/in-memory/org-binding.js';
+import { runOrgBindingConformance } from './org-binding.conformance.js';
+
+runOrgBindingConformance(makeInMemoryOrgBinding, 'InMemoryOrgBinding');

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

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Wire the shared `runProjectBindingConformance` suite against the
+ * in-memory reference adapter.
+ */
+
+import { makeInMemoryProjectBinding } from '../src/in-memory/project-binding.js';
+import { runProjectBindingConformance } from './project-binding.conformance.js';
+
+runProjectBindingConformance(makeInMemoryProjectBinding, 'InMemoryProjectBinding');

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

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Wire the shared `runTeamBindingConformance` suite against the
+ * in-memory reference adapter.
+ */
+
+import { makeInMemoryTeamBinding } from '../src/in-memory/team-binding.js';
+import { runTeamBindingConformance } from './team-binding.conformance.js';
+
+runTeamBindingConformance(makeInMemoryTeamBinding, 'InMemoryTeamBinding');

package/tests/org-binding.conformance.ts

@@ -0,0 +1,165 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Conformance suite for `OrgBinding`. Any adapter (the in-memory
+ * reference impl; a Postgres impl) invokes
+ * `runOrgBindingConformance(makeBinding)` and inherits the full
+ * behavioural contract.
+ *
+ * Cases covered:
+ * - CRUD happy paths (create → get → list → update → delete).
+ * - Cross-tenant isolation: an Org in tenant A never surfaces in
+ *   tenant B's list/get. This is the guardrail, not a feature —
+ *   asserted at every reachable read op.
+ * - Pagination via `Filter.cursor`.
+ * - `nameContains` substring filter.
+ * - `get`/`update`/`delete` behaviour on unknown orgIds.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import type { OrgId, TenantId } from '@kindgi/types';
+
+import type { OrgBinding } from '../src/org-binding.js';
+
+const T1 = 'tenant-1' as TenantId;
+const T2 = 'tenant-2' as TenantId;
+
+export function runOrgBindingConformance(
+  makeBinding: () => OrgBinding,
+  label = 'OrgBinding',
+): void {
+  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 got = await b.get(T1, id);
+      expect(got).toBeDefined();
+      expect(got?.id).toBe(id);
+      expect(got?.tenantId).toBe(T1);
+      expect(got?.name).toBe('Acme');
+      expect(got?.slug).toBe('acme');
+    });
+
+    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 got = await b.get(T1, id);
+      expect(got?.name).toBe('Acme Corp');
+      expect(got?.slug).toBe('acme');
+    });
+
+    it('deletes an Org', async () => {
+      const b = makeBinding();
+      const id = await b.create(T1, { name: 'Acme', slug: 'acme' });
+      await b.delete(T1, id);
+      const got = await b.get(T1, id);
+      expect(got).toBeUndefined();
+    });
+
+    it('lists orgs (empty tenant)', async () => {
+      const b = makeBinding();
+      const page = await b.list(T1, {});
+      expect(page.items).toEqual([]);
+      expect(page.nextCursor).toBeUndefined();
+    });
+  });
+
+  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' });
+      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' });
+      const t2Page = await b.list(T2, {});
+      expect(t2Page.items).toEqual([]);
+    });
+
+    it('update on tenant B for tenant-A orgId errors', async () => {
+      const b = makeBinding();
+      const id = await b.create(T1, { name: 'Acme', slug: 'acme' });
+      await expect(b.update(T2, id, { name: 'X' })).rejects.toThrow();
+    });
+
+    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' });
+      await b.delete(T2, id); // no-op
+      const got = await b.get(T1, id);
+      expect(got).toBeDefined();
+    });
+  });
+
+  describe(`${label} — pagination`, () => {
+    it('paginates via Filter.cursor', async () => {
+      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}` }));
+      }
+      const page1 = await b.list(T1, { limit: 2 });
+      expect(page1.items).toHaveLength(2);
+      expect(page1.nextCursor).toBeDefined();
+
+      const page2 = await b.list(T1, {
+        limit: 2,
+        ...(page1.nextCursor !== undefined ? { cursor: page1.nextCursor } : {}),
+      });
+      expect(page2.items).toHaveLength(2);
+      expect(page2.nextCursor).toBeDefined();
+
+      const page3 = await b.list(T1, {
+        limit: 2,
+        ...(page2.nextCursor !== undefined ? { cursor: page2.nextCursor } : {}),
+      });
+      expect(page3.items).toHaveLength(1);
+      expect(page3.nextCursor).toBeUndefined();
+
+      const seen = new Set<string>();
+      for (const p of [page1, page2, page3]) {
+        for (const item of p.items) seen.add(item.id);
+      }
+      expect(seen.size).toBe(5);
+    });
+  });
+
+  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' });
+
+      const page = await b.list(T1, { nameContains: 'Litigation' });
+      expect(page.items).toHaveLength(2);
+      const names = page.items.map((o) => o.name).sort();
+      expect(names).toEqual(['Litigation', 'Litigation-Sub']);
+    });
+  });
+
+  describe(`${label} — not-found behaviour`, () => {
+    const unknown = 'org-unknown' as OrgId;
+
+    it('get on unknown orgId returns undefined', async () => {
+      const b = makeBinding();
+      expect(await b.get(T1, unknown)).toBeUndefined();
+    });
+
+    it('update on unknown orgId errors', async () => {
+      const b = makeBinding();
+      await expect(b.update(T1, unknown, { name: 'X' })).rejects.toThrow();
+    });
+
+    it('delete on unknown orgId is a no-op', async () => {
+      const b = makeBinding();
+      await expect(b.delete(T1, unknown)).resolves.toBeUndefined();
+    });
+  });
+}