@kindgi/platform 0.0.0-bootstrap.0 → 0.1.1

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

@@ -0,0 +1,205 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * `makeInMemoryTeamBinding` — reference in-memory implementations of
+ * `TeamBinding` + `TeamMembershipBinding`. Used by tests + dev-time
+ * defaults.
+ *
+ * Storage: two maps — one keyed by `TeamId`, the other keyed by a
+ * composite `(teamId, userId)` string for memberships. Every op
+ * filters by `tenantId` at the row level. The membership map only
+ * stores memberships whose parent team belongs to the tenant — the
+ * `add` code path validates team existence before writing.
+ *
+ * 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).
+ */
+
+import type { Filter, Page, TeamId, TenantId, UserId } from '@kindgi/types';
+
+import type {
+  TeamBinding,
+  TeamListFilter,
+  TeamMembershipAddInput,
+  TeamMembershipBinding,
+} from '../team-binding.js';
+import type { Team, TeamMembership, TeamPatch, TeamRole, TeamSpec } from '../types.js';
+
+import { nowTimestamp, paginate } from './util.js';
+
+let teamIdCounter = 0;
+function nextTeamId(): TeamId {
+  teamIdCounter += 1;
+  return `team-${teamIdCounter}` as TeamId;
+}
+
+function membershipKey(teamId: TeamId, userId: UserId): string {
+  return `${teamId}::${userId}`;
+}
+
+/**
+ * Combined factory — returns a `TeamBinding` + `TeamMembershipBinding`
+ * pair that share underlying storage. The pair is the atomic unit
+ * (memberships reference teams; the two must agree on tenant
+ * membership at every op).
+ */
+export function makeInMemoryTeamBinding(): {
+  readonly teams: TeamBinding;
+  readonly memberships: TeamMembershipBinding;
+} {
+  const teamRows = new Map<TeamId, Team>();
+  const membershipRows = new Map<string, TeamMembership>();
+
+  function findTeamInTenant(tenantId: TenantId, teamId: TeamId): Team | undefined {
+    const t = teamRows.get(teamId);
+    if (t === undefined || t.tenantId !== tenantId) return undefined;
+    return t;
+  }
+
+  const teams: TeamBinding = {
+    async create(tenantId, spec: TeamSpec): Promise<TeamId> {
+      const id = nextTeamId();
+      const now = nowTimestamp();
+      const row: Team = {
+        id,
+        tenantId,
+        name: spec.name,
+        slug: spec.slug,
+        createdAt: now,
+        updatedAt: now,
+        ...(spec.orgId !== undefined ? { orgId: spec.orgId } : {}),
+        ...(spec.description !== undefined ? { description: spec.description } : {}),
+      };
+      teamRows.set(id, row);
+      return id;
+    },
+
+    async get(tenantId, teamId): Promise<Team | undefined> {
+      return findTeamInTenant(tenantId, teamId);
+    },
+
+    async list(tenantId, filter: TeamListFilter): Promise<Page<Team>> {
+      const all: Team[] = [];
+      for (const row of teamRows.values()) {
+        if (row.tenantId !== tenantId) continue;
+        if (filter.orgId !== undefined && row.orgId !== filter.orgId) continue;
+        if (filter.nameContains !== undefined && !row.name.includes(filter.nameContains)) {
+          continue;
+        }
+        all.push(row);
+      }
+      all.sort((a, b) => {
+        if (a.createdAt !== b.createdAt) return a.createdAt < b.createdAt ? -1 : 1;
+        return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+      });
+      return paginate(all, filter.limit, filter.cursor);
+    },
+
+    async update(tenantId, teamId, patch: TeamPatch): Promise<void> {
+      const row = findTeamInTenant(tenantId, teamId);
+      if (row === undefined) {
+        throw new Error(`team-not-found: ${teamId}`);
+      }
+      // orgId patch tri-state: undefined = untouched; null = clear;
+      // OrgId value = set.
+      let nextOrgId = row.orgId;
+      if (patch.orgId !== undefined) {
+        nextOrgId = patch.orgId === null ? undefined : patch.orgId;
+      }
+      const nextDescription = patch.description ?? row.description;
+      const next: Team = {
+        id: row.id,
+        tenantId: row.tenantId,
+        name: patch.name ?? row.name,
+        slug: patch.slug ?? row.slug,
+        createdAt: row.createdAt,
+        updatedAt: nowTimestamp(),
+        ...(nextOrgId !== undefined ? { orgId: nextOrgId } : {}),
+        ...(nextDescription !== undefined ? { description: nextDescription } : {}),
+      };
+      teamRows.set(teamId, next);
+    },
+
+    async delete(tenantId, teamId): Promise<void> {
+      const row = findTeamInTenant(tenantId, teamId);
+      if (row === undefined) return;
+      teamRows.delete(teamId);
+      // Cascade — every membership row for this team drops with it.
+      for (const key of membershipRows.keys()) {
+        if (key.startsWith(`${teamId}::`)) {
+          membershipRows.delete(key);
+        }
+      }
+    },
+  };
+
+  const memberships: TeamMembershipBinding = {
+    async add(tenantId, input: TeamMembershipAddInput): Promise<void> {
+      const team = findTeamInTenant(tenantId, input.teamId);
+      if (team === undefined) {
+        throw new Error(`team-not-found: ${input.teamId}`);
+      }
+      const key = membershipKey(input.teamId, input.userId);
+      if (membershipRows.has(key)) {
+        // Idempotent — role mutation goes through updateRole.
+        return;
+      }
+      const row: TeamMembership = {
+        teamId: input.teamId,
+        userId: input.userId,
+        role: input.role,
+        joinedAt: nowTimestamp(),
+      };
+      membershipRows.set(key, row);
+    },
+
+    async remove(tenantId, teamId, userId): Promise<void> {
+      const team = findTeamInTenant(tenantId, teamId);
+      if (team === undefined) return;
+      membershipRows.delete(membershipKey(teamId, userId));
+    },
+
+    async list(tenantId, teamId, filter: Filter): Promise<Page<TeamMembership>> {
+      const team = findTeamInTenant(tenantId, teamId);
+      if (team === undefined) return { items: [] };
+      const all: TeamMembership[] = [];
+      for (const row of membershipRows.values()) {
+        if (row.teamId !== teamId) continue;
+        all.push(row);
+      }
+      all.sort((a, b) => (a.joinedAt < b.joinedAt ? -1 : a.joinedAt > b.joinedAt ? 1 : 0));
+      return paginate(all, filter.limit, filter.cursor);
+    },
+
+    async listForUser(tenantId, userId, filter: Filter): Promise<Page<TeamMembership>> {
+      const all: TeamMembership[] = [];
+      for (const row of membershipRows.values()) {
+        if (row.userId !== userId) continue;
+        // Confirm the parent team belongs to the tenant.
+        const t = teamRows.get(row.teamId);
+        if (t === undefined || t.tenantId !== tenantId) continue;
+        all.push(row);
+      }
+      all.sort((a, b) => (a.joinedAt < b.joinedAt ? -1 : a.joinedAt > b.joinedAt ? 1 : 0));
+      return paginate(all, filter.limit, filter.cursor);
+    },
+
+    async updateRole(tenantId, teamId, userId, role: TeamRole): Promise<void> {
+      const team = findTeamInTenant(tenantId, teamId);
+      if (team === undefined) {
+        throw new Error(`team-not-found: ${teamId}`);
+      }
+      const key = membershipKey(teamId, userId);
+      const row = membershipRows.get(key);
+      if (row === undefined) {
+        throw new Error(`team-membership-not-found: ${teamId}/${userId}`);
+      }
+      membershipRows.set(key, { ...row, role });
+    },
+  };
+
+  return { teams, memberships };
+}

package/src/in-memory/util.ts

@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Shared helpers for the in-memory reference adapters.
+ *
+ * - `nowTimestamp()` — monotonic-ish `Timestamp` from `Date.now()`.
+ *   Uses a per-call increment fallback so two calls in the same
+ *   millisecond still produce a strictly-increasing pair (matters for
+ *   `list` ordering by `createdAt`).
+ * - `paginate(all, limit, cursor)` — takes a sorted array + optional
+ *   `limit` + optional opaque `Cursor` and returns a `Page<T>`. Cursor
+ *   encoding is `String(offset)` — trivial for the in-memory adapter,
+ *   opaque to callers per the `Cursor` doc-comment in
+ *   `packages/types/src/filter.ts`.
+ */
+
+import type { Cursor, Page, Timestamp } from '@kindgi/types';
+
+// Monotonic counter so back-to-back calls inside a single millisecond
+// still produce strictly-increasing `Timestamp` values. Kept module-
+// local; not exposed.
+let lastMs = 0;
+let lastCounter = 0;
+
+export function nowTimestamp(): Timestamp {
+  const ms = Date.now();
+  if (ms === lastMs) {
+    lastCounter += 1;
+  } else {
+    lastMs = ms;
+    lastCounter = 0;
+  }
+  const date = new Date(ms).toISOString();
+  // Encode the sub-ms counter as a trailing `#NNNN` suffix so the
+  // resulting string still sorts lexicographically in creation order —
+  // the in-memory adapter only compares strings.
+  const suffix = lastCounter === 0 ? '' : `#${String(lastCounter).padStart(4, '0')}`;
+  return `${date}${suffix}` as Timestamp;
+}
+
+/**
+ * Default page size when a caller passes no `limit` ("small default,
+ * high ceiling").
+ */
+export const DEFAULT_PAGE_LIMIT = 100;
+
+/**
+ * Maximum page size — clamps runaway `limit` values so a caller
+ * can't accidentally exfiltrate an entire table.
+ */
+export const MAX_PAGE_LIMIT = 500;
+
+export function paginate<T>(
+  all: readonly T[],
+  limit: number | undefined,
+  cursor: Cursor | undefined,
+): Page<T> {
+  const effectiveLimit = Math.min(Math.max(1, limit ?? DEFAULT_PAGE_LIMIT), MAX_PAGE_LIMIT);
+  const offset = cursor === undefined ? 0 : Number.parseInt(cursor, 10);
+  const safeOffset = Number.isFinite(offset) && offset >= 0 ? offset : 0;
+  const slice = all.slice(safeOffset, safeOffset + effectiveLimit);
+  const nextOffset = safeOffset + slice.length;
+  const hasMore = nextOffset < all.length;
+  if (hasMore) {
+    return {
+      items: slice,
+      nextCursor: String(nextOffset) as Cursor,
+    };
+  }
+  return { items: slice };
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * `@kindgi/platform` — the multi-tenant hierarchy primitives. Ships
+ * the type surface + binding interfaces (plus reference in-memory
+ * adapters); durable implementations are supplied by the deployment.
+ * Authorization vocabulary (object types, actions, tuple builders, PEP
+ * helpers) lives in `@kindgi/authz`, not here.
+ */
+
+export type * from './scope.js';
+export type * from './types.js';
+export { scopeKey } from './scope.js';
+
+export type {
+  OrgBinding,
+  OrgListFilter,
+} from './org-binding.js';
+export type {
+  TeamBinding,
+  TeamListFilter,
+  TeamMembershipAddInput,
+  TeamMembershipBinding,
+} from './team-binding.js';
+export type {
+  ProjectBinding,
+  ProjectListFilter,
+  ProjectMembershipAddInput,
+  ProjectMembershipBinding,
+} from './project-binding.js';
+export type {
+  TeamProjectGrant,
+  TeamProjectGrantAddInput,
+  TeamProjectGrantBinding,
+} from './team-project-grant-binding.js';
+
+export {
+  makeInMemoryOrgBinding,
+  makeInMemoryTeamBinding,
+  makeInMemoryProjectBinding,
+} from './in-memory/index.js';
+
+export type {
+  AddProjectMemberParams,
+  AddTeamMemberParams,
+  CreateOrgError,
+  CreateOrgParams,
+  CreateProjectError,
+  CreateProjectParams,
+  CreateTeamError,
+  CreateTeamParams,
+  MembershipMutationError,
+  TenantHierarchyBinding,
+  TenantSummary,
+} from './tenant-hierarchy-binding.js';

package/src/org-binding.ts

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * `OrgBinding` — CRUD surface for the `Org` primitive within a tenant.
+ *
+ * Conventions shared by every binding in this package:
+ * - Every method takes `tenantId: TenantId` as its first argument. The
+ *   binding is responsible for enforcing tenant isolation: a call from
+ *   tenant A must never surface a row from tenant B.
+ * - `list` returns the shared `Page<T>` envelope from
+ *   `@kindgi/types` (`items` + `nextCursor`).
+ * - `list` filters extend the shared `Filter` shape so every list call
+ *   shares the same pagination fields.
+ *
+ * This package ships the interface + reference in-memory adapter
+ * (in `./in-memory/org-binding.ts`). Any adapter can be checked with
+ * the conformance suite in `packages/platform/tests/`
+ * (`runOrgBindingConformance`).
+ */
+
+import type { Filter, OrgId, Page, TenantId } from '@kindgi/types';
+
+import type { Org, OrgPatch, OrgSpec } from './types.js';
+
+/**
+ * `list` filter for orgs. Extends the shared `Filter` with `orgs`-
+ * specific facets. Every additional field on the list contract lives
+ * here (not on the method signature) so the shape survives SDK codegen
+ * unchanged.
+ *
+ * - `nameContains` — case-sensitive substring match on `Org.name`.
+ *   Optional; absent = no name filter. The `@kindgi/api` orgs route
+ *   exposes it as `?nameContains=`.
+ */
+export interface OrgListFilter extends Filter {
+  readonly nameContains?: string;
+}
+
+/**
+ * The org CRUD binding. Framework consumers implement one of these
+ * per persistence backend (Postgres, in-memory for tests).
+ */
+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(tenantId: TenantId, spec: OrgSpec): Promise<OrgId>;
+  /**
+   * 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
+   * (tenant isolation is by construction, never a silent leak).
+   */
+  get(tenantId: TenantId, orgId: OrgId): Promise<Org | undefined>;
+  /**
+   * Cursor-paginated list of orgs within a tenant. Uses the shared
+   * `Page<Org>` envelope from `@kindgi/types` — consumers loop on
+   * `nextCursor` until it's absent.
+   */
+  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.
+   */
+  update(tenantId: TenantId, orgId: OrgId, patch: OrgPatch): Promise<void>;
+  /**
+   * Delete an `Org`. Cascade semantics (dependent teams / projects) are
+   * a storage-layer concern — the in-memory adapter does the delete
+   * unconditionally.
+   */
+  delete(tenantId: TenantId, orgId: OrgId): Promise<void>;
+}

package/src/project-binding.ts

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * `ProjectBinding` + `ProjectMembershipBinding` — the project CRUD
+ * surface + the user↔project direct-grant membership surface within a
+ * tenant.
+ *
+ * Projects are the primary content-scope; all content (memory /
+ * agents / flows / guardrails / runs / artifacts / cost / evals /
+ * approvals / evidence / provenance / observations) carries a
+ * required `projectId` and is read/written filtered by it.
+ *
+ * `getDefault` returns the tenant's auto-created "Default" project.
+ * That row is the only one where `Project.isDefault = true`;
+ * implementations keep exactly one per tenant (this binding's
+ * in-memory adapter checks at write time, before the row lands in the
+ * map). Callers that don't naturally know a project resolve the
+ * Default with `getDefault` and pass its id explicitly (see e.g.
+ * `AgentPublishInput.projectId` in `@kindgi/api`).
+ *
+ * Same convention as `org-binding.ts`: `tenantId` first, `Page<T>`
+ * return, `Filter`-extending filter shapes.
+ */
+
+import type { Filter, OrgId, Page, ProjectId, TenantId, UserId } from '@kindgi/types';
+
+import type {
+  Project,
+  ProjectMembership,
+  ProjectPatch,
+  ProjectRole,
+  ProjectSpec,
+} from './types.js';
+
+/**
+ * `list` filter for projects. Same shape as `TeamListFilter` — `orgId`
+ * narrows to a specific org's projects (nullable FK);
+ * `nameContains` is a substring match on `Project.name`.
+ */
+export interface ProjectListFilter extends Filter {
+  readonly orgId?: OrgId;
+  readonly nameContains?: string;
+}
+
+/**
+ * Input for `ProjectMembershipBinding.add`. Distinct interface so
+ * downstream additions extend without breaking call sites.
+ */
+export interface ProjectMembershipAddInput {
+  readonly projectId: ProjectId;
+  readonly userId: UserId;
+  readonly role: ProjectRole;
+}
+
+/**
+ * The project CRUD binding.
+ */
+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(tenantId: TenantId, spec: ProjectSpec): Promise<ProjectId>;
+  /**
+   * Look up a `Project` by id. `undefined` when unknown or in a
+   * different tenant.
+   */
+  get(tenantId: TenantId, projectId: ProjectId): Promise<Project | undefined>;
+  /**
+   * Cursor-paginated list of projects. Filter by `orgId` or
+   * `nameContains`.
+   */
+  list(tenantId: TenantId, filter: ProjectListFilter): Promise<Page<Project>>;
+  /**
+   * The tenant's Default project (`isDefault: true`). Returns
+   * `undefined` when no Default project exists for the tenant.
+   */
+  getDefault(tenantId: TenantId): Promise<Project | undefined>;
+  /**
+   * Partially update a `Project`. `ProjectPatch.orgId` supports
+   * `null` to re-assign the project out of any org.
+   */
+  update(tenantId: TenantId, projectId: ProjectId, patch: ProjectPatch): Promise<void>;
+  /**
+   * Delete a `Project`. What happens to content rows that still
+   * reference the project is the storage layer's concern; the
+   * in-memory adapter removes the project's direct memberships and
+   * team grants with it.
+   */
+  delete(tenantId: TenantId, projectId: ProjectId): Promise<void>;
+}
+
+/**
+ * User↔project direct-grant membership. Additive with team grants
+ * (the union rules); a user may have both a direct
+ * `ProjectMembership` and access via a team-project grant.
+ * Authorization resolves the union.
+ */
+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.
+   */
+  add(tenantId: TenantId, input: ProjectMembershipAddInput): Promise<void>;
+  /**
+   * Remove the direct project grant. No-op when absent.
+   */
+  remove(tenantId: TenantId, projectId: ProjectId, userId: UserId): Promise<void>;
+  /**
+   * Cursor-paginated direct memberships of a project. Ordered by
+   * `joinedAt` ascending.
+   */
+  list(tenantId: TenantId, projectId: ProjectId, filter: Filter): Promise<Page<ProjectMembership>>;
+  /**
+   * Cursor-paginated direct memberships of a user (across every
+   * project the user is directly a member of within the tenant).
+   * Used to resolve a user's direct project set.
+   */
+  listForUser(tenantId: TenantId, userId: UserId, filter: Filter): Promise<Page<ProjectMembership>>;
+  /**
+   * Update an existing direct-membership's role. Errors when the
+   * membership doesn't exist.
+   */
+  updateRole(
+    tenantId: TenantId,
+    projectId: ProjectId,
+    userId: UserId,
+    role: ProjectRole,
+  ): Promise<void>;
+}

package/src/scope.ts

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * The `Scope` primitive — a required, discriminated access boundary.
+ *
+ * Design decision: a subset of framework resources —
+ * those that describe policy, configuration, or authoring templates
+ * rather than run-time content — carry a required, discriminated
+ * `Scope` value that names the level at which the resource is
+ * visible. The `Scope` is not a filter; it's a **row-level property**
+ * recorded at insert time.
+ *
+ * Which resources carry `Scope` (vs `projectId`)?
+ * - **Content-scoped** (agents, flows, tools, guardrails, memory
+ *   facts, artifacts, runs, cost records, eval suites, eval runs,
+ *   approvals, evidence, provenance, observations): a required
+ *   `projectId`. Rows are the *contents* of a project.
+ * - **Policy/config-scoped** (MCP endpoints, secrets, env values,
+ *   pack templates, S3 credentials): `Scope` discriminated
+ *   (Tenant / Org / Project). Describes *how* content is served —
+ *   auth providers, credentials, template catalogs. A firm may want
+ *   firm-wide MCP endpoints OR matter-scoped MCP endpoints; fixed to
+ *   one level is wrong, nullable is worse.
+ * - **Tenant-only** (adapters, capabilities, identity providers,
+ *   deployment ledger, signing keys, tenant config): a required
+ *   `tenantId` only. Deployment-wide framework configuration.
+ *
+ * Resolution semantics (most-specific-wins): for a resource lookup
+ * within a request context that carries `{ tenantId, projectId }`,
+ * walk `project → org → tenant` (the org is the project's `orgId`);
+ * first match wins.
+ */
+
+import type { OrgId, ProjectId, TenantId } from '@kindgi/types';
+
+export type Scope =
+  | { readonly kind: 'tenant'; readonly tenantId: TenantId }
+  | { readonly kind: 'org'; readonly tenantId: TenantId; readonly orgId: OrgId }
+  | { readonly kind: 'project'; readonly tenantId: TenantId; readonly projectId: ProjectId };
+
+export function scopeKey(s: Scope): string {
+  switch (s.kind) {
+    case 'tenant':
+      return `tenant:${s.tenantId}`;
+    case 'org':
+      return `org:${s.orgId}`;
+    case 'project':
+      return `project:${s.projectId}`;
+  }
+}