@volter/world-platform 2.0.0

package/src/db/migrations/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1790550512216,
+      "tag": "0000_init",
+      "breakpoints": true
+    }
+  ]
+}

package/src/db/migrations.ts

@@ -0,0 +1,33 @@
+// GENERATED by `bun src/db/pack-migrations.ts --write` from ./migrations/*.sql (drizzle-kit's): do not edit.
+export const MIGRATIONS: ReadonlyArray<{ tag: string; statements: readonly string[] }> = [
+  {
+    "tag": "0000_init",
+    "statements": [
+      "CREATE TABLE `audit` (\n\t`seq` integer PRIMARY KEY AUTOINCREMENT NOT NULL,\n\t`org` text NOT NULL,\n\t`at` text NOT NULL,\n\t`event` text NOT NULL,\n\t`actor` text NOT NULL,\n\t`target` text,\n\t`data` text\n);",
+      "CREATE INDEX `audit_org` ON `audit` (`org`,`seq`);",
+      "CREATE TABLE `biller_records` (\n\t`key` text PRIMARY KEY NOT NULL,\n\t`value` text NOT NULL\n);",
+      "CREATE TABLE `deliveries` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`org_id` text NOT NULL,\n\t`endpoint_id` text NOT NULL,\n\t`event_id` text NOT NULL,\n\t`event` text NOT NULL,\n\t`body` text NOT NULL,\n\t`attempt` integer NOT NULL,\n\t`next_at` text NOT NULL,\n\t`attempts` text NOT NULL,\n\t`state` text NOT NULL,\n\t`seq` integer NOT NULL\n);",
+      "CREATE INDEX `deliveries_state` ON `deliveries` (`state`,`next_at`);",
+      "CREATE INDEX `deliveries_endpoint` ON `deliveries` (`endpoint_id`);",
+      "CREATE TABLE `dir_members` (\n\t`org_id` text NOT NULL,\n\t`user_id` text NOT NULL,\n\t`role` text NOT NULL,\n\tPRIMARY KEY(`org_id`, `user_id`)\n);",
+      "CREATE INDEX `dir_members_user` ON `dir_members` (`user_id`);",
+      "CREATE TABLE `dir_orgs` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`slug` text NOT NULL,\n\t`name` text NOT NULL,\n\t`created_at` text NOT NULL\n);",
+      "CREATE UNIQUE INDEX `dir_orgs_slug_unique` ON `dir_orgs` (`slug`);",
+      "CREATE TABLE `invitations` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`org_id` text NOT NULL,\n\t`email` text NOT NULL,\n\t`role` text NOT NULL,\n\t`inviter_id` text NOT NULL,\n\t`created_at` text NOT NULL,\n\t`expires_at` text NOT NULL\n);",
+      "CREATE INDEX `invitations_org` ON `invitations` (`org_id`);",
+      "CREATE INDEX `invitations_email` ON `invitations` (`email`);",
+      "CREATE TABLE `meta` (\n\t`key` text PRIMARY KEY NOT NULL,\n\t`value` text\n);",
+      "CREATE TABLE `org_settings` (\n\t`org_id` text PRIMARY KEY NOT NULL,\n\t`security` text,\n\t`flags` text,\n\t`early_adopter` integer,\n\t`support_access` text\n);",
+      "CREATE TABLE `org_worlds` (\n\t`org_id` text NOT NULL,\n\t`name` text NOT NULL,\n\t`host` text NOT NULL,\n\t`base` text NOT NULL,\n\t`provisioned_at` text NOT NULL,\n\tPRIMARY KEY(`org_id`, `name`)\n);",
+      "CREATE TABLE `people` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`email` text,\n\t`email_verified` integer NOT NULL,\n\t`name` text,\n\t`first_seen_at` text NOT NULL,\n\t`last_seen_at` text NOT NULL\n);",
+      "CREATE INDEX `people_email` ON `people` (`email`);",
+      "CREATE TABLE `sessions` (\n\t`id_hash` text PRIMARY KEY NOT NULL,\n\t`subject` text NOT NULL,\n\t`email` text,\n\t`name` text,\n\t`expires_at` text NOT NULL\n);",
+      "CREATE TABLE `support_requests` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`at` text NOT NULL,\n\t`person` text NOT NULL,\n\t`org` text,\n\t`world` text,\n\t`category` text NOT NULL,\n\t`severity` text NOT NULL,\n\t`subject` text NOT NULL,\n\t`message` text NOT NULL,\n\t`status` text NOT NULL\n);",
+      "CREATE TABLE `tokens` (\n\t`hash` text PRIMARY KEY NOT NULL,\n\t`user_id` text NOT NULL,\n\t`name` text NOT NULL,\n\t`created_at` text NOT NULL,\n\t`last4` text NOT NULL,\n\t`last_used_at` text,\n\t`expires_at` text,\n\t`scopes` text,\n\t`org_id` text,\n\t`support` text,\n\t`world_keys` text\n);",
+      "CREATE INDEX `tokens_user` ON `tokens` (`user_id`);",
+      "CREATE INDEX `tokens_org` ON `tokens` (`org_id`);",
+      "CREATE TABLE `webhooks` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`org_id` text NOT NULL,\n\t`url` text NOT NULL,\n\t`secret` text NOT NULL,\n\t`events` text NOT NULL,\n\t`description` text NOT NULL,\n\t`created_at` text NOT NULL,\n\t`consecutive_failures` integer NOT NULL,\n\t`last_failed_at` text,\n\t`disabled_at` text\n);",
+      "CREATE INDEX `webhooks_org` ON `webhooks` (`org_id`);"
+    ]
+  }
+];

package/src/db/open.ts

@@ -0,0 +1,92 @@
+// OPENING THE PLATFORM'S DATABASE (docs/contributing/architecture.md, "The platform's state is SQLite"): one Drizzle
+// database, synchronous on every driver the platform runs on — Bun's `bun:sqlite`, Node's built-in `node:sqlite` (behind
+// Drizzle's better-sqlite3 session, which it answers like), and a Durable Object's SQLite (`openDurableDatabase`). The
+// migrations (./migrations.ts) are applied once, in order, and recorded.
+import { createRequire } from 'node:module';
+import { chmodSync, existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { BaseSQLiteDatabase, SQLiteSyncDialect } from 'drizzle-orm/sqlite-core';
+import { BetterSQLiteSession } from 'drizzle-orm/better-sqlite3/session';
+import { MIGRATIONS } from './migrations.ts';
+
+// biome-ignore lint/suspicious/noExplicitAny: the three drivers' result types differ; every store reads rows the schema types
+export type PlatformDb = BaseSQLiteDatabase<'sync', any>;
+
+type Statement = { run: (...p: unknown[]) => unknown; all: (...p: unknown[]) => unknown[]; get: (...p: unknown[]) => unknown; raw: () => { all: (...p: unknown[]) => unknown[]; get: (...p: unknown[]) => unknown } };
+/** Node's DatabaseSync, answering as better-sqlite3 does where Drizzle's session reads it. */
+function nodeClient(path: string): { prepare: (sql: string) => Statement; transaction: (fn: (...a: unknown[]) => unknown) => unknown; exec: (sql: string) => void; close: () => void } {
+  const { DatabaseSync } = createRequire(import.meta.url)('node:sqlite') as typeof import('node:sqlite');
+  const raw = new DatabaseSync(path);
+  const prepare = (sql: string): Statement => {
+    const st = raw.prepare(sql);
+    const arrays = <T>(fn: () => T): T => { st.setReturnArrays(true); try { return fn(); } finally { st.setReturnArrays(false); } };
+    return {
+      run: (...p) => { const r = st.run(...(p as never[])); return { changes: Number(r.changes), lastInsertRowid: r.lastInsertRowid }; },
+      all: (...p) => st.all(...(p as never[])),
+      get: (...p) => st.get(...(p as never[])),
+      raw: () => ({ all: (...p) => arrays(() => st.all(...(p as never[]))), get: (...p) => arrays(() => st.get(...(p as never[]))) }),
+    };
+  };
+  // better-sqlite3's transaction(fn): a function that runs fn between BEGIN and COMMIT, rolling back on a throw
+  const transaction = (fn: (...a: unknown[]) => unknown) => {
+    const run = (mode: string) => (...a: unknown[]): unknown => { raw.exec(`BEGIN ${mode}`); try { const r = fn(...a); raw.exec('COMMIT'); return r; } catch (e) { raw.exec('ROLLBACK'); throw e; } };
+    return Object.assign(run('DEFERRED'), { deferred: run('DEFERRED'), immediate: run('IMMEDIATE'), exclusive: run('EXCLUSIVE') });
+  };
+  return { prepare, transaction, exec: (sql) => raw.exec(sql), close: () => raw.close() };
+}
+
+/** Apply what has not been applied, each migration in one transaction, and record it. */
+function migrate(exec: (sql: string) => void, applied: () => string[], inTransaction: (fn: () => void) => void): void {
+  exec('CREATE TABLE IF NOT EXISTS _migrations (tag TEXT PRIMARY KEY, applied_at TEXT NOT NULL)');
+  const done = new Set(applied());
+  for (const m of MIGRATIONS) {
+    if (done.has(m.tag)) continue;
+    inTransaction(() => { for (const s of m.statements) exec(s); exec(`INSERT INTO _migrations (tag, applied_at) VALUES ('${m.tag.replace(/'/g, "''")}', '${new Date().toISOString()}')`); });
+  }
+}
+
+/** The database's file in the state directory, and a restored one staged beside it (backup.ts). */
+export const DB_FILE = 'platform.db';
+export const RESTORE_FILE = 'platform.db.restore';
+
+const opened = new Map<string, PlatformDb>();
+const closers = new Map<string, () => void>();
+/** The platform's database at `<stateDir>/platform.db` (`:memory:` with no state directory), opened once per process.
+ *  A restore staged since the last start (`platform.db.restore`) is put in place first. */
+export function openDatabase(stateDir?: string): PlatformDb {
+  const path = stateDir ? join(resolve(stateDir), DB_FILE) : ':memory:';
+  const known = opened.get(path); if (known) return known;
+  if (stateDir) {
+    mkdirSync(dirname(path), { recursive: true });
+    const staged = join(resolve(stateDir), RESTORE_FILE);
+    if (existsSync(staged)) { for (const f of [`${path}-wal`, `${path}-shm`]) rmSync(f, { force: true }); renameSync(staged, path); }
+    // owner-only, like the platform's other state; SQLite gives its write-ahead log and index the database's mode
+    if (!existsSync(path)) writeFileSync(path, '', { mode: 0o600 });
+    chmodSync(path, 0o600);
+  }
+  const req = createRequire(import.meta.url);
+  let db: PlatformDb;
+  if ((globalThis as { Bun?: unknown }).Bun) {
+    const { Database } = req('bun:sqlite') as typeof import('bun:sqlite');
+    const { drizzle } = req('drizzle-orm/bun-sqlite') as typeof import('drizzle-orm/bun-sqlite');
+    const raw = new Database(path, { create: true });
+    raw.run('PRAGMA journal_mode = WAL'); raw.run('PRAGMA busy_timeout = 5000'); raw.run('PRAGMA foreign_keys = ON');
+    migrate((s) => raw.run(s), () => (raw.query('SELECT tag FROM _migrations').all() as Array<{ tag: string }>).map((r) => r.tag), (fn) => raw.transaction(fn)());
+    db = drizzle(raw) as unknown as PlatformDb; closers.set(path, () => raw.close());
+  } else {
+    const client = nodeClient(path);
+    client.exec('PRAGMA journal_mode = WAL'); client.exec('PRAGMA busy_timeout = 5000'); client.exec('PRAGMA foreign_keys = ON');
+    migrate((s) => client.exec(s), () => (client.prepare('SELECT tag FROM _migrations').all() as Array<{ tag: string }>).map((r) => r.tag), (fn) => (client.transaction(fn) as () => void)());
+    const dialect = new SQLiteSyncDialect();
+    db = new BaseSQLiteDatabase('sync', dialect, new BetterSQLiteSession(client as never, dialect, undefined, {}), undefined as never) as PlatformDb; closers.set(path, client.close);
+  }
+  opened.set(path, db);
+  return db;
+}
+
+/** Close the state directory's database in this process (its file can then be moved or removed); the next
+ *  openDatabase opens it again. */
+export function closeDatabase(stateDir: string): void {
+  const path = join(resolve(stateDir), DB_FILE);
+  closers.get(path)?.(); closers.delete(path); opened.delete(path);
+}

package/src/db/pack-migrations.ts

@@ -0,0 +1,19 @@
+// The migrations as a module (./migrations.ts): what `drizzle-kit generate` wrote under ./migrations, split into
+// statements, so every driver (a Durable Object reads no files) applies the same SQL.
+//   bun src/db/pack-migrations.ts --write    after `drizzle-kit generate --dialect sqlite --schema ./src/db/schema.ts --out ./src/db/migrations`
+//   bun src/db/pack-migrations.ts --check    exits 1 when migrations.ts is behind the .sql files
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const dir = join(import.meta.dir, 'migrations');
+const target = join(import.meta.dir, 'migrations.ts');
+export function packed(): string {
+  const files = readdirSync(dir).filter((f) => /^\d{4}_.+\.sql$/.test(f)).sort();
+  const list = files.map((f) => ({ tag: f.replace(/\.sql$/, ''), statements: readFileSync(join(dir, f), 'utf8').split('--> statement-breakpoint').map((s) => s.trim()).filter(Boolean) }));
+  return `// GENERATED by \`bun src/db/pack-migrations.ts --write\` from ./migrations/*.sql (drizzle-kit's): do not edit.\nexport const MIGRATIONS: ReadonlyArray<{ tag: string; statements: readonly string[] }> = ${JSON.stringify(list, null, 2)};\n`;
+}
+if (import.meta.main) {
+  if (process.argv.includes('--write')) { writeFileSync(target, packed()); console.log(`wrote ${target}`); }
+  else if (process.argv.includes('--check')) { let current = ''; try { current = readFileSync(target, 'utf8'); } catch { /* none */ } if (current.replace(/\r\n/g, '\n') !== packed()) { console.error('src/db/migrations.ts is behind src/db/migrations/*.sql — run: bun src/db/pack-migrations.ts --write'); process.exit(1); } console.log('migrations.ts is current'); }
+  else process.stdout.write(packed());
+}

package/src/db/schema.ts

@@ -0,0 +1,137 @@
+// THE PLATFORM'S STATE (docs/contributing/architecture.md, "The platform's state is SQLite"): one schema, whose
+// migrations `drizzle-kit generate` writes as plain SQL under ./migrations. Every table is the platform's own record:
+// a World's state is never here (it stays behind WorldStore). JSON columns hold only small nested lists.
+import { index, integer, primaryKey, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+
+/** The Worlds an org holds, and where each lives: the platform records where, never a World's log. */
+export const orgWorlds = sqliteTable('org_worlds', {
+  orgId: text('org_id').notNull(),
+  name: text('name').notNull(),
+  host: text('host').notNull(),
+  base: text('base').notNull(),
+  provisionedAt: text('provisioned_at').notNull(),
+}, (t) => [primaryKey({ columns: [t.orgId, t.name] })]);
+
+/** An org's settings: its security switches, labs and support consent (absent: the defaults). */
+export const orgSettings = sqliteTable('org_settings', {
+  orgId: text('org_id').primaryKey(),
+  security: text('security', { mode: 'json' }).$type<{ membersCanInvite: boolean; membersCanUsePersonalTokens: boolean; approvedEmailDomains: string[] }>(),
+  flags: text('flags', { mode: 'json' }).$type<Record<string, boolean>>(),
+  earlyAdopter: integer('early_adopter', { mode: 'boolean' }),
+  supportAccess: text('support_access', { mode: 'json' }).$type<{ until: string; grantedBy: string; requestId: string } | null>(),
+});
+
+export const webhooks = sqliteTable('webhooks', {
+  id: text('id').primaryKey(),
+  orgId: text('org_id').notNull(),
+  url: text('url').notNull(),
+  secret: text('secret').notNull(),
+  events: text('events', { mode: 'json' }).$type<string[]>().notNull(),
+  description: text('description').notNull(),
+  createdAt: text('created_at').notNull(),
+  consecutiveFailures: integer('consecutive_failures').notNull(),
+  lastFailedAt: text('last_failed_at'),
+  disabledAt: text('disabled_at'),
+}, (t) => [index('webhooks_org').on(t.orgId)]);
+
+export const deliveries = sqliteTable('deliveries', {
+  id: text('id').primaryKey(),
+  orgId: text('org_id').notNull(),
+  endpointId: text('endpoint_id').notNull(),
+  eventId: text('event_id').notNull(),
+  event: text('event').notNull(),
+  body: text('body').notNull(),
+  attempt: integer('attempt').notNull(),
+  nextAt: text('next_at').notNull(),
+  attempts: text('attempts', { mode: 'json' }).$type<Array<{ at: string; status: number | null; ok: boolean; response: string }>>().notNull(),
+  state: text('state', { enum: ['pending', 'delivered', 'failed'] }).notNull(),
+  /** the order the queue keeps */
+  seq: integer('seq').notNull(),
+}, (t) => [index('deliveries_state').on(t.state, t.nextAt), index('deliveries_endpoint').on(t.endpointId)]);
+
+export const supportRequests = sqliteTable('support_requests', {
+  id: text('id').primaryKey(),
+  at: text('at').notNull(),
+  person: text('person', { mode: 'json' }).$type<{ id: string; email?: string }>().notNull(),
+  org: text('org'),
+  world: text('world'),
+  category: text('category').notNull(),
+  severity: text('severity').notNull(),
+  subject: text('subject').notNull(),
+  message: text('message').notNull(),
+  status: text('status', { enum: ['open', 'closed'] }).notNull(),
+});
+
+/** The platform's own position: the last backup, the operator's notice; one row per key. */
+export const meta = sqliteTable('meta', { key: text('key').primaryKey(), value: text('value', { mode: 'json' }) });
+
+/** Personal, org and support tokens: only their hash is kept. */
+export const tokens = sqliteTable('tokens', {
+  hash: text('hash').primaryKey(),
+  userId: text('user_id').notNull(),
+  name: text('name').notNull(),
+  createdAt: text('created_at').notNull(),
+  last4: text('last4').notNull(),
+  lastUsedAt: text('last_used_at'),
+  expiresAt: text('expires_at'),
+  scopes: text('scopes', { mode: 'json' }).$type<string[]>(),
+  orgId: text('org_id'),
+  support: text('support', { mode: 'json' }).$type<{ reason: string; category: string }>(),
+  worldKeys: text('world_keys', { mode: 'json' }).$type<Array<{ world: string; keyId: string; command?: boolean }>>(),
+}, (t) => [index('tokens_user').on(t.userId), index('tokens_org').on(t.orgId)]);
+
+/** The platform's browser sessions, by the SHA-256 of the cookie's id. */
+export const sessions = sqliteTable('sessions', {
+  idHash: text('id_hash').primaryKey(),
+  subject: text('subject').notNull(),
+  email: text('email'),
+  name: text('name'),
+  expiresAt: text('expires_at').notNull(),
+});
+
+/** The audit log: append-only, per org, in order. */
+export const audit = sqliteTable('audit', {
+  seq: integer('seq').primaryKey({ autoIncrement: true }),
+  org: text('org').notNull(),
+  at: text('at').notNull(),
+  event: text('event').notNull(),
+  actor: text('actor', { mode: 'json' }).notNull(),
+  target: text('target'),
+  data: text('data', { mode: 'json' }),
+}, (t) => [index('audit_org').on(t.org, t.seq)]);
+
+// ── the directory the platform keeps when its provider only signs people in (directory.ts localDirectory) ──
+export const people = sqliteTable('people', {
+  id: text('id').primaryKey(),
+  email: text('email'),
+  emailVerified: integer('email_verified', { mode: 'boolean' }).notNull(),
+  name: text('name'),
+  firstSeenAt: text('first_seen_at').notNull(),
+  lastSeenAt: text('last_seen_at').notNull(),
+}, (t) => [index('people_email').on(t.email)]);
+
+export const dirOrgs = sqliteTable('dir_orgs', {
+  id: text('id').primaryKey(),
+  slug: text('slug').notNull().unique(),
+  name: text('name').notNull(),
+  createdAt: text('created_at').notNull(),
+});
+
+export const dirMembers = sqliteTable('dir_members', {
+  orgId: text('org_id').notNull(),
+  userId: text('user_id').notNull(),
+  role: text('role', { enum: ['org:admin', 'org:member'] }).notNull(),
+}, (t) => [primaryKey({ columns: [t.orgId, t.userId] }), index('dir_members_user').on(t.userId)]);
+
+export const invitations = sqliteTable('invitations', {
+  id: text('id').primaryKey(),
+  orgId: text('org_id').notNull(),
+  email: text('email').notNull(),
+  role: text('role', { enum: ['org:admin', 'org:member'] }).notNull(),
+  inviterId: text('inviter_id').notNull(),
+  createdAt: text('created_at').notNull(),
+  expiresAt: text('expires_at').notNull(),
+}, (t) => [index('invitations_org').on(t.orgId), index('invitations_email').on(t.email)]);
+
+/** What an attached biller keeps (apps/billing), by its own keys: the platform names no plan or price. */
+export const billerRecords = sqliteTable('biller_records', { key: text('key').primaryKey(), value: text('value', { mode: 'json' }).notNull() });

package/src/directory.ts

@@ -0,0 +1,216 @@
+// THE DIRECTORY (docs/contributing/architecture.md, "The hosted product": a platform has one access provider, which
+// brings its directory): who the people are, the orgs, their members, roles and invitations. The platform reads one
+// vocabulary through this interface and never learns which directory answers:
+//
+// - `volterDirectory`: the Volter identity service's (volter-ai/identity ADR-0002, "a product keeps its
+//   organizations here, with its own credential"), through its product door (`/api/organizations`, `/api/people`)
+//   with the platform's own `client_credentials` token. The service mails its own invitations.
+// - `localDirectory`: the platform's own, in its state directory, for an OpenID Connect provider that only signs
+//   people in (Google, Entra, Okta, Keycloak). A person is known once they have signed in; an invitation waits for
+//   the address to sign in with a verified email, and the platform mails it.
+//
+// Roles are one vocabulary here: `org:admin` and `org:member` (the identity service's `owner` and `admin` read as
+// `org:admin`).
+import { randomBytes } from 'node:crypto';
+import { and, asc, eq, gt, ne, or, sql } from 'drizzle-orm';
+import { openDatabase } from './db/open.ts';
+import { dirMembers, dirOrgs, invitations, people } from './db/schema.ts';
+import type { Identity } from './identity.ts';
+
+export type OrgRef = { id: string; slug: string | null; name: string; role: string };
+export type Member = { id: string; userId: string; email: string | null; name: string | null; role: string };
+export type PendingInvitation = { id: string; email: string; role: string; createdAt: string | null; expiresAt: string | null };
+export type Person = { id: string; email?: string; name?: string };
+/** Who a provider signed in, as its id token (or userinfo) named them. */
+export type SignedInPerson = { subject: string; email?: string; emailVerified?: boolean; name?: string };
+
+export type Directory = {
+  /** The organizations a person belongs to, with their role, by slug. */
+  orgsOf: (userId: string) => Promise<OrgRef[]>;
+  /** An org a person belongs to, by id or slug — the only way the platform resolves a person's org. */
+  memberOf: (userId: string, ref: string) => Promise<OrgRef | null>;
+  /** An org by id or slug, whoever asks (an org token, the operator's claim). */
+  orgById: (ref: string) => Promise<OrgRef | null>;
+  /** Make an org named `name` (its slug) with the person as its admin. */
+  createOrg: (name: string, userId: string) => Promise<OrgRef>;
+  renameOrg: (orgId: string, name: string) => Promise<OrgRef>;
+  deleteOrg: (orgId: string) => Promise<void>;
+  membersOf: (orgId: string) => Promise<Member[]>;
+  /** Add a person the directory knows, by id or by email. */
+  addMember: (orgId: string, who: { sub?: string; email?: string }) => Promise<void>;
+  /** Remove a member; a directory that can refuses, in the same write, to leave the org without an admin (OnlyAdmin). */
+  removeMember: (orgId: string, userId: string) => Promise<void>;
+  /** Change a role; the org's only admin stepping down is refused as removeMember's is. */
+  setMemberRole: (orgId: string, userId: string, role: 'org:admin' | 'org:member') => Promise<void>;
+  /** Invite an address the directory does not know yet; it joins when that address signs in. */
+  inviteMember: (orgId: string, email: string, inviterUserId: string, role?: string) => Promise<PendingInvitation>;
+  pendingInvitations: (orgId: string) => Promise<PendingInvitation[]>;
+  revokeInvitation: (orgId: string, invitationId: string) => Promise<void>;
+  /** The person an address belongs to, when the directory knows it (verified). */
+  userIdByEmail: (email: string) => Promise<string | null>;
+  personById: (userId: string) => Promise<Person | null>;
+  /** A person signed in: the directory records them and lets their invitations in. */
+  seen: (person: SignedInPerson) => Promise<void>;
+  /** Whether the directory mails its own invitations (else the platform does). */
+  mailsInvitations: boolean;
+};
+
+export const isAdmin = (o: OrgRef): boolean => o.role === 'org:admin' || o.role === 'admin';
+
+// ── the Volter identity service's ───────────────────────────────────────────────────────────────
+type OrgRow = { id: string; slug: string; name: string; role?: string };
+type InvitationRow = { id: string; email: string; role: string; createdAt?: string | null; expiresAt?: string | null };
+const readRole = (role: string): 'org:admin' | 'org:member' => (role.split(',').some((r) => r.trim() === 'owner' || r.trim() === 'admin') ? 'org:admin' : 'org:member');
+const writeRole = (role: string): 'admin' | 'member' => (role === 'org:admin' || role === 'admin' ? 'admin' : 'member');
+const seg = (s: string): string => encodeURIComponent(s);
+
+export function volterDirectory(identity: Identity): Directory {
+  const call = identity.call;
+  const invitationView = (inv: InvitationRow): PendingInvitation => ({ id: inv.id, email: inv.email, role: readRole(inv.role), createdAt: inv.createdAt ?? null, expiresAt: inv.expiresAt ?? null });
+  const userIdByEmail = async (email: string): Promise<string | null> => (await call<{ id: string }>('GET', `/api/people?email=${encodeURIComponent(email)}`))?.id ?? null;
+  const orgsOf = async (userId: string): Promise<OrgRef[]> => ((await call<OrgRow[]>('GET', `/api/people/${seg(userId)}/organizations`)) ?? [])
+    .map((o) => ({ id: o.id, slug: o.slug, name: o.name, role: readRole(o.role ?? 'member') }))
+    .sort((a, b) => (a.slug ?? a.name).localeCompare(b.slug ?? b.name));
+  return {
+    mailsInvitations: true,
+    orgsOf,
+    memberOf: async (userId, ref) => (await orgsOf(userId)).find((o) => o.id === ref || o.slug === ref) ?? null,
+    // the service answers an org by id or by slug
+    async orgById(ref) { try { const o = await call<OrgRow>('GET', `/api/organizations/${seg(ref)}`); return o ? { id: o.id, slug: o.slug, name: o.name, role: 'org:member' } : null; } catch { return null; } },
+    async createOrg(name, userId) {
+      const org = await call<OrgRow>('POST', '/api/organizations', { name, slug: name, createdBy: userId });
+      if (!org) throw new Error('the identity service has no organizations door');
+      return { id: org.id, slug: org.slug, name: org.name, role: 'org:admin' };
+    },
+    async renameOrg(orgId, name) {
+      const org = await call<OrgRow>('PATCH', `/api/organizations/${seg(orgId)}`, { name }); // the slug stays: it is the served prefix of every World the org holds
+      if (!org) throw new Error('no such organization');
+      return { id: org.id, slug: org.slug, name: org.name, role: 'org:admin' };
+    },
+    async deleteOrg(orgId) { await call('DELETE', `/api/organizations/${seg(orgId)}`); },
+    async membersOf(orgId) {
+      const rows = (await call<Array<{ id: string; userId: string; email?: string | null; name?: string | null; role: string }>>('GET', `/api/organizations/${seg(orgId)}/members`)) ?? [];
+      return rows.map((m) => ({ id: m.id, userId: m.userId, email: m.email ?? null, name: m.name || null, role: readRole(m.role) }));
+    },
+    async addMember(orgId, who) {
+      let userId = who.sub;
+      if (!userId && who.email) userId = (await userIdByEmail(who.email)) ?? undefined;
+      if (!userId) throw new Error('no such person at the identity service: a member is named by Volter id or by an email that has a Volter identity');
+      if (!(await call('POST', `/api/organizations/${seg(orgId)}/members`, { userId, role: 'member' }))) throw new Error('no such organization');
+    },
+    async removeMember(orgId, userId) { await call('DELETE', `/api/organizations/${seg(orgId)}/members/${seg(userId)}`); },
+    async setMemberRole(orgId, userId, role) { if (!(await call('PATCH', `/api/organizations/${seg(orgId)}/members/${seg(userId)}`, { role: writeRole(role) }))) throw new Error('not a member'); },
+    async inviteMember(orgId, email, inviterUserId, role = 'org:member') {
+      const inv = await call<InvitationRow>('POST', `/api/organizations/${seg(orgId)}/invitations`, { email, role: writeRole(role), inviterId: inviterUserId });
+      if (!inv) throw new Error('no such organization');
+      return invitationView(inv);
+    },
+    pendingInvitations: async (orgId) => ((await call<InvitationRow[]>('GET', `/api/organizations/${seg(orgId)}/invitations`)) ?? []).map(invitationView),
+    async revokeInvitation(orgId, invitationId) { await call('DELETE', `/api/organizations/${seg(orgId)}/invitations/${seg(invitationId)}`); },
+    userIdByEmail,
+    async personById(userId) {
+      try {
+        const p = await call<{ id: string; email?: string; name?: string }>('GET', `/api/people/${seg(userId)}`);
+        return p ? { id: p.id, ...(p.email ? { email: p.email } : {}), ...(p.name ? { name: p.name } : {}) } : null;
+      } catch { return null; }
+    },
+    // the identity service keeps its people and accepts its own invitations
+    async seen() { /* nothing to record */ },
+  };
+}
+
+/** Refused: the change would leave the org without an admin. */
+export class OnlyAdmin extends Error { constructor() { super("the org's only admin"); } }
+
+// ── the platform's own, in its database ────────────────────────────────────────────────────────
+const INVITATION_DAYS = 7;
+type Role = 'org:admin' | 'org:member';
+
+/** The directory the platform keeps in its database (db/schema.ts people, dir_orgs, dir_members, invitations), for a
+ *  platform whose provider only signs people in. Each change is one statement or one transaction. */
+export function localDirectory(stateDir: string): Directory {
+  const db = openDatabase(stateDir);
+  const orgRow = (ref: string) => db.select().from(dirOrgs).where(or(eq(dirOrgs.id, ref), eq(dirOrgs.slug, ref))).get() as (typeof dirOrgs.$inferSelect) | undefined;
+  const refOf = (o: typeof dirOrgs.$inferSelect, role: string): OrgRef => ({ id: o.id, slug: o.slug, name: o.name, role });
+  const mustOrg = (orgId: string) => { const o = db.select().from(dirOrgs).where(eq(dirOrgs.id, orgId)).get() as (typeof dirOrgs.$inferSelect) | undefined; if (!o) throw new Error('no such organization'); return o; };
+  const roleOf = (orgId: string, userId: string): Role | null => (db.select({ role: dirMembers.role }).from(dirMembers).where(and(eq(dirMembers.orgId, orgId), eq(dirMembers.userId, userId))).get() as { role: Role } | undefined)?.role ?? null;
+  // the member is not an admin, or another admin remains
+  const keepsAnAdmin = (orgId: string, userId: string) => or(ne(dirMembers.role, 'org:admin'), sql`exists (select 1 from ${dirMembers} as other where other.org_id = ${orgId} and other.user_id <> ${userId} and other.role = 'org:admin')`);
+  const view = (i: typeof invitations.$inferSelect): PendingInvitation => ({ id: i.id, email: i.email, role: i.role, createdAt: i.createdAt, expiresAt: i.expiresAt });
+  // only an address the provider verified names a person: an unverified one could be anyone's
+  const byEmail = (email: string): string | null => (db.select({ id: people.id }).from(people).where(and(eq(people.email, email.trim().toLowerCase()), eq(people.emailVerified, true))).get() as { id: string } | undefined)?.id ?? null;
+  return {
+    mailsInvitations: false,
+    async orgsOf(userId) {
+      return (db.select({ o: dirOrgs, role: dirMembers.role }).from(dirMembers).innerJoin(dirOrgs, eq(dirOrgs.id, dirMembers.orgId)).where(eq(dirMembers.userId, userId)).orderBy(asc(dirOrgs.slug)).all() as Array<{ o: typeof dirOrgs.$inferSelect; role: Role }>)
+        .map(({ o, role }) => refOf(o, role));
+    },
+    async memberOf(userId, r) { const o = orgRow(r); const role = o ? roleOf(o.id, userId) : null; return o && role ? refOf(o, role) : null; },
+    async orgById(r) { const o = orgRow(r); return o ? refOf(o, 'org:member') : null; },
+    async createOrg(name, userId) {
+      const id = `org_${randomBytes(9).toString('base64url').replace(/[^A-Za-z0-9]/g, 'x')}`;
+      try {
+        db.transaction((tx) => {
+          tx.insert(dirOrgs).values({ id, slug: name, name, createdAt: new Date().toISOString() }).run();
+          tx.insert(dirMembers).values({ orgId: id, userId, role: 'org:admin' }).run();
+        });
+      } catch (e) { if (/UNIQUE/i.test(String((e as Error).message))) throw new Error(`an org named ${name} exists`); throw e; }
+      return { id, slug: name, name, role: 'org:admin' };
+    },
+    async renameOrg(orgId, name) { const o = mustOrg(orgId); db.update(dirOrgs).set({ name }).where(eq(dirOrgs.id, orgId)).run(); return refOf({ ...o, name }, 'org:admin'); },
+    async deleteOrg(orgId) {
+      db.transaction((tx) => { tx.delete(dirMembers).where(eq(dirMembers.orgId, orgId)).run(); tx.delete(invitations).where(eq(invitations.orgId, orgId)).run(); tx.delete(dirOrgs).where(eq(dirOrgs.id, orgId)).run(); });
+    },
+    async membersOf(orgId) {
+      mustOrg(orgId);
+      return (db.select({ userId: dirMembers.userId, role: dirMembers.role, email: people.email, name: people.name }).from(dirMembers).leftJoin(people, eq(people.id, dirMembers.userId)).where(eq(dirMembers.orgId, orgId)).all() as Array<{ userId: string; role: Role; email: string | null; name: string | null }>)
+        .map((m) => ({ id: `${orgId}:${m.userId}`, userId: m.userId, email: m.email ?? null, name: m.name ?? null, role: m.role }));
+    },
+    async addMember(orgId, who) {
+      mustOrg(orgId);
+      const known = who.sub ? (db.select({ id: people.id }).from(people).where(eq(people.id, who.sub)).get() as { id: string } | undefined)?.id ?? null : null;
+      const userId = known ?? (who.email ? byEmail(who.email) : null);
+      if (!userId) throw new Error('no such person here: a member is someone who has signed in to this platform (invite an address that has not)');
+      db.insert(dirMembers).values({ orgId, userId, role: 'org:member' }).onConflictDoNothing().run();
+    },
+    // one statement each: the check that another admin remains and the write cannot be split by a concurrent change
+    async removeMember(orgId, userId) {
+      mustOrg(orgId);
+      const r = db.delete(dirMembers).where(and(eq(dirMembers.orgId, orgId), eq(dirMembers.userId, userId), keepsAnAdmin(orgId, userId))).run() as { changes?: number };
+      if (!r.changes && roleOf(orgId, userId)) throw new OnlyAdmin();
+    },
+    async setMemberRole(orgId, userId, role) {
+      mustOrg(orgId);
+      const r = db.update(dirMembers).set({ role }).where(and(eq(dirMembers.orgId, orgId), eq(dirMembers.userId, userId), role === 'org:member' ? keepsAnAdmin(orgId, userId) : undefined)).run() as { changes?: number };
+      if (!r.changes) { if (roleOf(orgId, userId)) throw new OnlyAdmin(); throw new Error('not a member'); }
+    },
+    async inviteMember(orgId, email, inviterUserId, role = 'org:member') {
+      mustOrg(orgId);
+      const address = email.trim().toLowerCase();
+      if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(address)) throw new Error('not an email address');
+      const now = Date.now();
+      const inv = { id: `inv_${randomBytes(8).toString('hex')}`, orgId, email: address, role: (role === 'org:admin' ? 'org:admin' : 'org:member') as Role, inviterId: inviterUserId, createdAt: new Date(now).toISOString(), expiresAt: new Date(now + INVITATION_DAYS * 86_400_000).toISOString() };
+      // a second invitation to an address replaces the first
+      db.transaction((tx) => { tx.delete(invitations).where(and(eq(invitations.orgId, orgId), eq(invitations.email, address))).run(); tx.insert(invitations).values(inv).run(); });
+      return view(inv);
+    },
+    async pendingInvitations(orgId) { return (db.select().from(invitations).where(and(eq(invitations.orgId, orgId), gt(invitations.expiresAt, new Date().toISOString()))).orderBy(asc(invitations.createdAt)).all() as Array<typeof invitations.$inferSelect>).map(view); },
+    async revokeInvitation(orgId, invitationId) { db.delete(invitations).where(and(eq(invitations.orgId, orgId), eq(invitations.id, invitationId))).run(); },
+    async userIdByEmail(email) { return byEmail(email); },
+    async personById(userId) { const p = db.select().from(people).where(eq(people.id, userId)).get() as (typeof people.$inferSelect) | undefined; return p ? { id: userId, ...(p.email ? { email: p.email } : {}), ...(p.name ? { name: p.name } : {}) } : null; },
+    async seen(person) {
+      const now = new Date().toISOString();
+      const email = person.email ? person.email.toLowerCase() : null;
+      db.transaction((tx) => {
+        tx.insert(people).values({ id: person.subject, email, emailVerified: Boolean(person.emailVerified), name: person.name ?? null, firstSeenAt: now, lastSeenAt: now })
+          .onConflictDoUpdate({ target: people.id, set: { email, emailVerified: Boolean(person.emailVerified), name: person.name ?? null, lastSeenAt: now } }).run();
+        // an invitation lets in the person who signs in with its address, verified by the provider
+        if (email && person.emailVerified) {
+          const due = tx.select().from(invitations).where(and(eq(invitations.email, email), gt(invitations.expiresAt, now))).all() as Array<typeof invitations.$inferSelect>;
+          for (const inv of due) tx.insert(dirMembers).values({ orgId: inv.orgId, userId: person.subject, role: inv.role }).onConflictDoNothing().run();
+          tx.delete(invitations).where(eq(invitations.email, email)).run();
+        }
+      });
+    },
+  };
+}