@100xprompt/brain 0.0.0-stage → 0.1.0

package/src/org/server.ts

@@ -0,0 +1,920 @@
+// brain org: the organisation memory server. One process, one database file (see db.ts), Chitta for the text and the ranking.
+//
+// WHAT RELIES ON WHAT
+//   * Chitta's own permission engine (graph ACL: `permissions` edges from principals to records, `belongsTo` edges from users to
+//     groups, an `anyone` node for org-wide records) decides which records a user's SEARCH may rank at all: the search is
+//     scoped to the accessible set BEFORE ranking, so other people's records can neither appear nor crowd out the top-k.
+//       private -> a permission edge from `u:<owner>` only
+//       project -> `u:<owner>` plus the group `proj:<hash of project id>`  (members have `belongsTo` edges to it)
+//       team    -> `u:<owner>` plus the group `team:<team id>`
+//       org     -> `u:<owner>` plus the `anyone:<record>` node for this organisation
+//     The owner always keeps a permission edge on their own records (so they can still recall, demote and forget what they
+//     promoted, even after being removed from a project). An admin gets NO special edge: roles in Chitta only gate writes.
+//   * The SERVER (this file + db.ts) owns everything else: who a token belongs to, roles, rate limits, size limits, policy and
+//     redaction, who may promote/forget what, membership (the source of truth: `syncGroups` rebuilds Chitta's group edges from
+//     the membership tables after every change), retention and the audit log. The visibility rule is ALSO enforced a second,
+//     independent time in SQL (db.VISIBLE_SQL) on every record a search returns, so a mistake in either layer alone cannot leak.
+//   * Fail closed: a record is first written visible to its owner only; its real ACL is applied in the same synchronous step
+//     that records it; on an update the old record is removed before the new one is written.
+//
+// ENTITIES, RELATIONS, PROCEDURES: Chitta's entity graph is shared by everyone in the store (names are folded onto one canonical
+// entity across records), so it is NEVER fed (`extractGraph: false`). An item's entities and relations are kept in the server's
+// own tables keyed by the item and used only through the visibility predicate (see graph.ts). Procedures are validated and
+// discarded. Ranking is project-aware BEFORE ranking: recall searches Chitta as a synthetic (user, project) principal that can
+// see only that project's items the user may see (see graph.ts), so other projects can never crowd the answer out.
+//
+// DECISIONS the brief left open
+//   * Ingesting at scope `private` is allowed into any project id (a project id is just a label until something is shared in
+//     it). Scope `project` requires membership of the project, scope `team` membership of the team; there is no "open project".
+//   * Re-ingesting an item that already exists updates its text but NEVER changes its scope or team (promotion is explicit; a
+//     sync must not widen or re-widen anything). New items get the requested (or default) scope.
+//   * Item ids from clients are per owner: two users may use the same item id; promote/forget by id act on the CALLER'S rows.
+//   * Another user's id in promote behaves exactly like an unknown id (no "forbidden"): existence of other people's items is
+//     never revealed to non-admins. Admin forget by explicit ids may remove any owner's item (it still cannot read it).
+//   * `forget` is limited to the caller's own items unless an admin names ids, or passes `mine:false`. At least one of
+//     project/source/ids is required (an empty filter is refused, never "everything").
+//   * Retention measures age from when an item's CONTENT was last stored or changed (an unchanged re-sync does not renew it).
+//   * The audit log hashes queries and (for private/recall events) project ids with a per-organisation secret, so an admin
+//     cannot confirm a guessed query or learn which project someone keeps private notes about.
+//
+// API: exactly src/org/types.ts (the admin shapes are at the bottom of that file). Extras: PromoteResponse may carry
+// `dropped: [{id, reason}]` for items the (tightened) policy no longer allows to be shared; `disable` also accepts {id, disabled?:false} to re-enable.
+import type { Database } from "bun:sqlite"
+import { existsSync } from "node:fs"
+import { createHmac } from "node:crypto"
+import { pathToFileURL } from "node:url"
+import { chittaCandidates } from "../memory/store.ts"
+import { redact } from "../memory/redact.ts"
+import { approxTokens, type MemoryItem, type MemoryKind, type ProjectKey } from "../memory/types.ts"
+import { authenticate, sha256Hex, WindowLimiter } from "./auth.ts"
+import { OrgDb, isId, type ItemRow, type UserRow } from "./db.ts"
+import { OrgKeyError, chittaWithLibsql, claimServerLock, dbState, resolveKey, withKeyEnv } from "./crypto.ts"
+import { loadTls } from "./tls.ts"
+import { OrgGraph, aclPrincipals, cleanExtras, expansionScore, type Extras } from "./graph.ts"
+import { MEMORY_KINDS, checkItem, effectiveScope, normalizePolicy } from "./policy.ts"
+import { SsoInputError, getSsoAdmin, putSsoAdmin } from "./sso.ts"
+import {
+  SCOPES,
+  scopeRank,
+  type AuditEvent,
+  type ForgetResponse,
+  type IngestResponse,
+  type OrgError,
+  type OrgRecalled,
+  type Policy,
+  type ProjectsResponse,
+  type PromoteResponse,
+  type RecallResponse,
+  type Role,
+  type Scope,
+  type WhoAmI,
+} from "./types.ts"
+
+export { initOrg, openOrgDb, isId } from "./db.ts"
+
+export interface OrgServerOptions {
+  dbPath: string
+  /** Default 4500; 0 picks a free port. */
+  port?: number
+  /** Default 127.0.0.1. Put TLS in front before listening on anything else. */
+  host?: string
+  /** Default "auto" (a real embedder when available, else hashing); tests use "hash". */
+  embeddings?: "hash" | "auto"
+  now?: () => number
+  /** Requests per minute per token. Default 120. */
+  rateLimitPerMinute?: number
+  /** Items one user may own. Default 50,000. */
+  maxItemsPerUser?: number
+  /**
+   * Behind a TLS-terminating proxy every request comes from the proxy's address, so the per-IP failed-authentication limit would be
+   * shared by everyone. With this on, the address is read from the LAST entry of X-Forwarded-For (the one the trusted proxy itself
+   * appended; earlier entries are supplied by the client and can be forged). Leave it off unless a proxy you control is in front:
+   * without one, a client could pick its own "address" and escape the limit.
+   */
+  trustProxy?: boolean
+  /** Encryption at rest (crypto.ts). The key itself, or the path of a file holding it; else `BRAIN_ORG_KEY`. An encrypted database
+   *  cannot be opened without it, and a key given for a plain database is refused. */
+  key?: string
+  keyFile?: string
+  /** TLS in the server itself (tls.ts): PEM file paths. The URL is then https://. Both or neither. */
+  tlsCertFile?: string
+  tlsKeyFile?: string
+  /** How often the retention job runs while the server is up (default one hour; 0 turns the timer off). It also runs at startup. */
+  retentionIntervalMs?: number
+}
+
+const IP_LIKE = /^[0-9a-fA-F:.]{3,45}$/
+
+/** The client's address for rate limiting: the socket's, or with `trust` the proxy-appended last X-Forwarded-For entry. */
+export function clientAddress(req: Request, socketAddress: string | undefined, trust: boolean): string {
+  if (trust) {
+    const parts = (req.headers.get("x-forwarded-for") ?? "").split(",").map((x) => x.trim()).filter(Boolean)
+    const last = parts[parts.length - 1]
+    if (last && IP_LIKE.test(last)) return last
+  }
+  return socketAddress ?? "-"
+}
+export interface OrgServerHandle {
+  url: string
+  port: number
+  stop(): Promise<void>
+}
+
+export const MAX_BODY_BYTES = 1_000_000
+export const MAX_ITEM_TEXT = 2_000
+export const MAX_ITEMS_PER_CALL = 200
+const ROLES: Role[] = ["viewer", "editor", "admin"]
+const roleRank = (r: Role): number => ROLES.indexOf(r)
+
+class HttpError extends Error {
+  constructor(
+    readonly status: number,
+    readonly code: string,
+    message: string,
+    readonly headers?: Record<string, string>,
+  ) {
+    super(message)
+  }
+}
+const bad = (message: string) => new HttpError(400, "invalid_request", message)
+const forbidden = (message: string) => new HttpError(403, "forbidden", message)
+
+// ---- request validation (strict about types, sizes and enums; unknown keys are ignored and never used) -----------------------
+
+type Obj = Record<string, unknown>
+const isObj = (x: unknown): x is Obj => typeof x === "object" && x !== null && !Array.isArray(x)
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/
+
+function str(o: Obj, key: string, opt: { min?: number; max: number; required?: boolean; control?: boolean }): string | undefined {
+  const v = o[key]
+  if (v === undefined || v === null) {
+    if (opt.required) throw bad(`${key} is required`)
+    return undefined
+  }
+  if (typeof v !== "string") throw bad(`${key} must be a string`)
+  if (v.length > opt.max) throw bad(`${key} is too long (at most ${opt.max} characters)`)
+  if (v.length < (opt.min ?? 0)) throw bad(`${key} is too short`)
+  if (v.includes("\u0000") || (opt.control && CONTROL.test(v))) throw bad(`${key} contains control characters`)
+  return v
+}
+const reqStr = (o: Obj, key: string, max: number, min = 1): string => str(o, key, { max, min, required: true })!
+
+function scopeOf(x: unknown, key: string): Scope | undefined {
+  if (x === undefined || x === null) return undefined
+  if (typeof x !== "string" || !(SCOPES as string[]).includes(x)) throw bad(`${key} must be one of ${SCOPES.join(", ")}`)
+  return x as Scope
+}
+function intOf(o: Obj, key: string, min: number, max: number): number | undefined {
+  const v = o[key]
+  if (v === undefined || v === null) return undefined
+  if (typeof v !== "number" || !Number.isInteger(v) || v < min || v > max) throw bad(`${key} must be an integer from ${min} to ${max}`)
+  return v
+}
+function strList(x: unknown, key: string, maxLen: number, maxEach: number): string[] {
+  if (x === undefined || x === null) return []
+  if (!Array.isArray(x) || x.length > maxLen) throw bad(`${key} must be a list of at most ${maxLen} strings`)
+  for (const s of x) if (typeof s !== "string" || !s.length || s.length > maxEach || s.includes("\u0000")) throw bad(`${key} must hold non-empty strings of at most ${maxEach} characters`)
+  return x as string[]
+}
+function projectOf(x: unknown): ProjectKey {
+  if (!isObj(x)) throw bad("project must be an object {id, label}")
+  const id = reqStr(x, "project.id" in x ? "project.id" : "id", 500)
+  const label = str(x, "label", { max: 200, control: true }) ?? id
+  return { id, label: label || id }
+}
+
+function parseItem(x: unknown, index: number): MemoryItem {
+  if (!isObj(x)) throw bad(`items[${index}] must be an object`)
+  const where = `items[${index}]`
+  const wrap = <T>(f: () => T): T => {
+    try {
+      return f()
+    } catch (e) {
+      throw e instanceof HttpError ? bad(`${where}: ${e.message}`) : e
+    }
+  }
+  return wrap(() => {
+    const id = str(x, "id", { min: 1, max: 200, required: true, control: true })!
+    const kind = x.kind
+    if (typeof kind !== "string" || !(MEMORY_KINDS as string[]).includes(kind)) throw bad(`kind must be one of ${MEMORY_KINDS.join(", ")}`)
+    const name = str(x, "name", { max: 300, control: true }) ?? ""
+    const text = str(x, "text", { min: 1, max: MAX_ITEM_TEXT, required: true })!
+    const source = str(x, "source", { min: 1, max: 300, required: true, control: true })!
+    const occurredAt = str(x, "occurredAt", { max: 64, control: true })
+    // Validated for shape and size, then discarded (see the header comment): they never reach the store.
+    const list = (k: string, max: number) => {
+      const v = x[k]
+      if (v === undefined || v === null) return
+      if (!Array.isArray(v) || v.length > max) throw bad(`${k} must be a list of at most ${max} entries`)
+      for (const e of v) if (!isObj(e) || JSON.stringify(e).length > 2_000) throw bad(`${k} entries must be small objects`)
+    }
+    list("entities", 100)
+    list("relations", 100)
+    list("procedures", 50)
+    // entities and relations are kept as sent (the policy reads them as sent; graph.ts cleans and redacts them before storing)
+    const ents = Array.isArray(x.entities) ? { entities: x.entities as MemoryItem["entities"] } : {}
+    const rels = Array.isArray(x.relations) ? { relations: x.relations as MemoryItem["relations"] } : {}
+    return { id, kind: kind as MemoryKind, name, text, source, ...(occurredAt ? { occurredAt } : {}), ...ents, ...rels }
+  })
+}
+
+// ---- the server ------------------------------------------------------------------------------------------------------------
+
+interface ChittaLike {
+  ctx: {
+    store: { db: Database; addNode(id: string, coll: string, data?: Record<string, unknown>): void; addEdge(src: string, dst: string, label: string): void; bumpVersion(): void }
+    ingestor: { registerUser(id: string, org: string, email?: string, role?: "admin" | "editor" | "viewer"): void; registerGroup(id: string): void }
+    authorizedIngest(actingUserId: string, doc: Record<string, unknown>): Promise<unknown>
+    deleteRecord(actingUserId: string, recordId: string): void
+    searchWithGraph(query: string, userId: string, orgId: string, trace?: undefined, limit?: number): Promise<{ searchResults: Array<{ score: number; metadata: { recordId?: string } }> }>
+  }
+  user(id: string, opts?: { role?: Role; org?: string }): { recall(query: string, opts?: { limit?: number }): Promise<Array<{ score: number; recordId?: string }>> }
+  close(): void
+}
+
+async function loadChitta(only?: string): Promise<new (o: Record<string, unknown>) => ChittaLike> {
+  const tried: string[] = []
+  for (const file of only ? [only] : chittaCandidates()) {
+    if (!existsSync(file)) continue
+    try {
+      const mod = await import(pathToFileURL(file).href)
+      if (typeof mod.Chitta === "function") return mod.Chitta
+      tried.push(`${file} (no Chitta export)`)
+    } catch (e) {
+      tried.push(`${file} (${(e as Error).message.split("\n")[0]})`)
+    }
+  }
+  throw new Error(tried.length ? `Chitta could not be loaded: ${tried.join("; ")}` : "Chitta is not installed (set BRAIN_CHITTA to its folder, or install @100xprompt/chitta)")
+}
+
+const userP = (id: string): string => `u:${id}`
+const teamP = (id: string): string => `team:${id}`
+const projP = (project: string): string => `proj:${sha256Hex(project).slice(0, 32)}`
+const ridOf = (owner: string, project: string, source: string, itemId: string): string => `o~${sha256Hex(`${owner}\u0000${project}\u0000${source}\u0000${itemId}`).slice(0, 32)}`
+
+export async function startOrgServer(opts: OrgServerOptions): Promise<OrgServerHandle> {
+  const now = opts.now ?? Date.now
+  const { dbPath } = opts
+  if (!existsSync(dbPath)) throw new Error(`no organisation database at ${dbPath}: create one with \`brain org admin init\``)
+  if ((opts.tlsCertFile === undefined) !== (opts.tlsKeyFile === undefined)) throw new Error("TLS needs both a certificate and a private key (tlsCertFile and tlsKeyFile)")
+  const tls = opts.tlsCertFile && opts.tlsKeyFile ? loadTls({ certFile: opts.tlsCertFile, keyFile: opts.tlsKeyFile }, now) : undefined
+  // encryption at rest: an encrypted file needs its key, a key needs an encrypted file (crypto.ts says which and how to fix it)
+  const { key } = resolveKey({ key: opts.key, keyFile: opts.keyFile })
+  if (dbState(dbPath) === "encrypted" && !key) throw new OrgKeyError(`${dbPath} is encrypted: give the key with BRAIN_ORG_KEY or --key-file <path>`)
+  const probe = OrgDb.open(dbPath, now, key)
+  const orgMaybe = probe.org()
+  probe.close()
+  if (!orgMaybe) throw new Error(`${dbPath} holds no organisation: create one with \`brain org admin init\``)
+
+  const org: { id: string; name: string } = orgMaybe
+  // Chitta switches to libSQL (needed for the cipher) when it sees CONTEXT_DB_KEY at construction: use a Chitta whose folder can load libsql
+  const chittaFile = key ? chittaWithLibsql() : undefined
+  if (key && !chittaFile) throw new OrgKeyError("an encrypted database needs the `libsql` package next to Chitta: `cd <chitta folder> && bun add libsql` (BRAIN_CHITTA points to that folder)")
+  const Chitta = await loadChitta(chittaFile)
+  const chitta = withKeyEnv(key, () => new Chitta({ path: dbPath, embeddings: opts.embeddings ?? "auto", rerank: false, org: org.id }))
+  const releaseLock = claimServerLock(dbPath)
+  const store = chitta.ctx.store
+  try {
+    store.db.exec("PRAGMA busy_timeout = 5000")
+  } catch {}
+  const db = new OrgDb(store.db, now)
+  // libSQL's handle has no `transaction`: give Chitta's own handle the adapted one so every `store.db.transaction(...)` below works on both drivers
+  if (typeof (store.db as { transaction?: unknown }).transaction !== "function") (store.db as unknown as { transaction: unknown }).transaction = db.db.transaction
+  db.migrate()
+  const graph = new OrgGraph(db, store, (id) => chitta.ctx.ingestor.registerUser(id, org.id, undefined, "editor"))
+  const auditKey = db.auditKey()
+  const rateLimit = new WindowLimiter(opts.rateLimitPerMinute ?? 120)
+  const failLimit = new WindowLimiter(30) // failed authentications per IP per minute
+  const signInLimit = new WindowLimiter(60) // single sign-on requests per IP per minute
+  const maxItems = opts.maxItemsPerUser ?? 50_000
+
+  // ---- serialised writes: everything that touches Chitta's records goes one at a time ----
+  let chain: Promise<unknown> = Promise.resolve()
+  const locked = <T>(fn: () => Promise<T> | T): Promise<T> => {
+    const run = chain.then(fn)
+    chain = run.then(() => undefined, () => undefined)
+    return run
+  }
+
+  // ---- audit ----
+  const hmac = (s: string): string => createHmac("sha256", auditKey).update(s).digest("hex")
+  const audit = (actor: string, action: string, e: { project?: string; scope?: Scope; count?: number; detail?: string } = {}) => db.audit({ actor, action, ...e })
+  /** A project id as an admin may see it: in the clear when something was shared there, hashed when it is private/unknown. */
+  const auditProject = (project: string, scope?: Scope): string => (scope && scope !== "private" ? project : `p:${hmac(project).slice(0, 12)}`)
+  let authFailWindow = { start: 0, n: 0, suppressed: 0 }
+  const auditAuthFail = (reason: string, actor: string | undefined) => {
+    const t = now()
+    if (t - authFailWindow.start >= 60_000) {
+      if (authFailWindow.suppressed) audit("-", "auth.fail.suppressed", { count: authFailWindow.suppressed })
+      authFailWindow = { start: t, n: 0, suppressed: 0 }
+    }
+    if (++authFailWindow.n > 20) authFailWindow.suppressed++
+    else audit(actor ?? "-", "auth.fail", { detail: reason })
+  }
+
+  // ---- Chitta plumbing ----
+  const provisioned = new Set<string>()
+  const ensureUser = (userId: string) => {
+    if (provisioned.has(userId)) return
+    chitta.ctx.ingestor.registerUser(userP(userId), org.id, undefined, "editor")
+    provisioned.add(userId)
+  }
+  const chittaUser = (userId: string) => {
+    ensureUser(userId)
+    return chitta.user(userP(userId), { role: "editor", org: org.id })
+  }
+
+  /** Membership is NOT copied into Chitta any more: the synthetic (user, project) principal a recall searches as is brought up to
+   *  date from the membership tables at every recall (graph.ts), so a change applies on the next call and nothing is rebuilt in bulk.
+   *  Called after every membership change (kept so each change still invalidates Chitta's caches at once). */
+  function syncGroups() {
+    store.bumpVersion()
+  }
+
+  /** Makes a record's Chitta ACL exactly what its row says. Synchronous (no await between the checks and the write). The groups
+   *  are per project (see graph.ts), which is what lets Chitta rank one project's items only. */
+  function applyAcl(row: ItemRow) {
+    const rid = row.rid
+    store.db.query("DELETE FROM edges WHERE dst = ? AND label = 'permissions'").run(rid)
+    store.db.query("DELETE FROM nodes WHERE id = ? AND coll = 'anyone'").run(`anyone:${rid}`)
+    ensureUser(row.owner)
+    for (const principal of aclPrincipals(row)) store.addEdge(principal, rid, "permissions")
+    store.bumpVersion()
+  }
+
+  async function chittaWrite(row: { rid: string; owner: string; kind: MemoryKind; name: string; text: string }) {
+    ensureUser(row.owner)
+    // owner-only until applyAcl runs (fail closed); no graph (see header)
+    await chitta.ctx.authorizedIngest(userP(row.owner), {
+      recordId: row.rid,
+      orgId: org.id,
+      recordName: `${row.kind}: ${row.name}`,
+      text: row.text,
+      permittedPrincipals: [],
+      extractGraph: false,
+    })
+  }
+  function chittaRemove(rid: string, owner: string) {
+    try {
+      chitta.ctx.deleteRecord(userP(owner), rid)
+    } catch {
+      // not there (an orphaned row) or not ours: remove whatever carries this id, the same statements deleteRecord runs
+      store.db.query("DELETE FROM nodes WHERE id = ?").run(rid)
+      store.db.query("DELETE FROM edges WHERE src = ? OR dst = ?").run(rid, rid)
+      store.db.query("DELETE FROM chunks WHERE point_id LIKE ?").run(`${rid}#%`)
+      store.db.query("DELETE FROM chunks WHERE virtual_record_id = ?").run(rid)
+      store.bumpVersion()
+    }
+    store.db.query("DELETE FROM nodes WHERE id = ? AND coll = 'anyone'").run(`anyone:${rid}`)
+  }
+
+  function removeRows(rows: ItemRow[]): number {
+    for (const r of rows) {
+      chittaRemove(r.rid, r.owner)
+      db.deleteItem(r.rid)
+    }
+    return rows.length
+  }
+
+  function runRetention(actor: string, via?: string): Promise<number> {
+    return locked(() => {
+      const days = db.policy().retentionDays
+      if (!days) return 0
+      const rows = db.expiredItems(now() - days * 86_400_000)
+      removeRows(rows)
+      if (rows.length) audit(actor, "retention", { count: rows.length, detail: `retentionDays=${days}${via ? ` via=${via}` : ""}` })
+      return rows.length
+    })
+  }
+
+  syncGroups()
+  if (graph.aclIsLegacy()) {
+    // a database made before per-project groups: rewrite every item's permission edges once, then drop the old global groups
+    store.db.transaction(() => {
+      for (const r of graph.allItemRows()) applyAcl(r)
+      graph.dropLegacyGroups()
+      graph.markAclCurrent()
+    })()
+  }
+  await runRetention("-", "startup")
+  // The retention timer: the same job, every `retentionIntervalMs`, for as long as the server runs. unref'd (it never keeps the process
+  // alive) and cleared in stop(). A run that throws is logged in one terse line (never a message that could hold item text) and the
+  // timer keeps going; a run that removed something is audited by runRetention itself.
+  const retentionEvery = opts.retentionIntervalMs ?? 3_600_000
+  const retentionTimer =
+    retentionEvery > 0
+      ? setInterval(() => {
+          runRetention("-", "timer").catch((e) => process.stderr.write(`brain org: retention run failed: ${(e as Error)?.name ?? "Error"}\n`))
+        }, retentionEvery)
+      : undefined
+  retentionTimer?.unref?.()
+
+  // ---- handlers ----------------------------------------------------------------------------------------------------------
+
+  const needRole = (u: UserRow, min: Role, what: string) => {
+    if (roleRank(u.role) < roleRank(min)) throw forbidden(`your role (${u.role}) may not ${what}`)
+  }
+
+  async function ingest(u: UserRow, body: Obj): Promise<IngestResponse> {
+    needRole(u, "editor", "add memory")
+    const project = projectOf(body.project)
+    const requested = scopeOf(body.scope, "scope")
+    const team = str(body, "team", { max: 64 })
+    if (!Array.isArray(body.items)) throw bad("items must be a list")
+    if (body.items.length > MAX_ITEMS_PER_CALL) throw bad(`too many items (at most ${MAX_ITEMS_PER_CALL} per call)`)
+    const items = body.items.map(parseItem)
+    const policy = db.policy()
+    const eff = effectiveScope(requested, policy)
+    if (!eff.ok) throw new HttpError(403, eff.code, eff.reason)
+    const scope = eff.scope
+    if (scope === "project" && !db.isProjectMember(u.id, project.id)) throw forbidden("you are not a member of this project, so nothing can be shared into it")
+    if (scope === "team") {
+      if (!team) throw bad("team is required for scope team")
+      if (!isId(team) || !db.isTeamMember(u.id, team)) throw forbidden("you are not a member of that team")
+    }
+    const dropped: IngestResponse["dropped"] = []
+    const ready: Array<{ item: MemoryItem; text: string; name: string; source: string; extras: Extras }> = []
+    for (const item of items) {
+      const verdict = checkItem(item, policy) // on the text as sent: the stricter reading
+      if (!verdict.ok) {
+        dropped.push({ id: item.id, reason: verdict.reason })
+        continue
+      }
+      // the server never trusts the client's redaction
+      ready.push({ item, text: redact(item.text), name: redact(item.name), source: redact(item.source), extras: cleanExtras(item.entities, item.relations) })
+    }
+    let stored = 0
+    await locked(async () => {
+      for (const { item, text, name, source, extras } of ready) {
+        const rid = ridOf(u.id, project.id, source, item.id)
+        const existing = db.item(rid)
+        if (!existing && db.countOwned(u.id) >= maxItems) {
+          dropped.push({ id: item.id, reason: "quota_exceeded" })
+          continue
+        }
+        const unchanged = existing && existing.text === text && existing.name === name && existing.kind === item.kind
+        if (existing && !unchanged) chittaRemove(rid, u.id)
+        if (!unchanged) await chittaWrite({ rid, owner: u.id, kind: item.kind, name, text })
+        // from here to the end of the iteration there is no await: the row and the ACL appear together
+        if (existing) {
+          if (!unchanged) db.updateItemContent(rid, { label: project.label, kind: item.kind, name, text, occurred_at: item.occurredAt ?? null, stored_at: now() })
+          applyAcl(db.item(rid)!)
+        } else {
+          const row: ItemRow = { rid, item_id: item.id, project: project.id, label: project.label, scope, owner: u.id, team: scope === "team" ? team! : null, source, kind: item.kind, name, text, occurred_at: item.occurredAt ?? null, stored_at: now() }
+          db.insertItem(row)
+          applyAcl(row)
+        }
+        graph.saveExtras(rid, extras) // the item's entities and relations: the server's own tables, never Chitta's shared graph
+        stored++
+      }
+    })
+    audit(u.id, "ingest", { project: auditProject(project.id, scope), scope, count: stored, ...(dropped.length ? { detail: `dropped=${dropped.length}` } : {}) })
+    return { stored, dropped, scope }
+  }
+
+  async function recall(u: UserRow, body: Obj): Promise<RecallResponse> {
+    const project = projectOf(body.project)
+    const query = reqStr(body, "query", 2_000, 0)
+    const limit = intOf(body, "limit", 1, 50) ?? 8
+    const maxTokens = intOf(body, "maxTokens", 1, 20_000) ?? 1_500
+    const hash = hmac(query).slice(0, 16)
+    // Chitta's keyword leg parses its input: keep letters, digits and plain punctuation only
+    const q = query.replace(/[^\p{L}\p{N}\s_.-]/gu, " ").replace(/\s+/g, " ").trim()
+    const out: OrgRecalled[] = []
+    if (q) {
+      // Chitta ranks as the synthetic (user, project) principal: only this project's items the user may see are even candidates
+      const principal = graph.syncSynthetic(u.id, project.id)
+      const res = await chitta.ctx.searchWithGraph(q, principal, org.id, undefined, Math.min(200, Math.max(limit * 10, 50)))
+      const hits = res.searchResults.map((r) => ({ score: r.score, recordId: r.metadata.recordId }))
+      const rids = [...new Set(hits.map((h) => h.recordId).filter((r): r is string => !!r))]
+      const visible = db.visibleRows(u.id, rids) // the second, independent gate
+      const seen = new Set<string>()
+      const rows: ItemRow[] = []
+      const costs: number[] = []
+      let tokens = 0
+      for (const hit of hits) {
+        const row = hit.recordId ? visible.get(hit.recordId) : undefined
+        if (!row || seen.has(row.rid) || !(hit.score > 0) || row.project !== project.id) continue
+        seen.add(row.rid)
+        const text = redact(row.text)
+        const cost = approxTokens(text)
+        if (out.length && tokens + cost > maxTokens) continue
+        out.push({ text, kind: row.kind, name: row.name, score: hit.score, source: row.source, id: row.item_id, scope: row.scope, owner: row.owner, project: row.project, ...(row.team ? { team: row.team } : {}) })
+        rows.push(row)
+        costs.push(cost)
+        tokens += cost
+        if (out.length >= limit) break
+      }
+      // graph expansion: other VISIBLE items of this project that share an entity with the top hits, below every direct hit,
+      // within `limit` and the token budget (graph.ts: the visibility predicate is part of the statement that finds them)
+      if (out.length) {
+        const extra = graph.expansion(u.id, project.id, rows.slice(0, 5), seen, limit)
+        const extraRows = extra.length ? db.visibleRows(u.id, extra.map((e) => e.rid)) : new Map<string, ItemRow>()
+        const wanted = extra.filter((e) => extraRows.has(e.rid))
+        if (wanted.length) {
+          // Make room for extras only when they can actually be used: giving up a direct hit must buy an extra that fits the token budget
+          // (otherwise a tight budget would lose a direct hit for nothing).
+          const cand = wanted.map((e) => extraRows.get(e.rid)!).filter((r) => r.project === project.id).map((r) => ({ cost: approxTokens(redact(r.text)) }))
+          const slotsWanted = Math.min(cand.length, Math.floor(limit / 4))
+          const fits = (pop: number) => {
+            let t = tokens - costs.slice(costs.length - pop).reduce((a, b) => a + b, 0)
+            let n = 0
+            for (const c of cand) {
+              if (n >= limit - out.length + pop) break
+              if (t + c.cost > maxTokens) continue
+              t += c.cost
+              n++
+            }
+            return n
+          }
+          let pop = 0
+          while (limit - out.length + pop < slotsWanted && out.length - pop > 1 && fits(pop + 1) > fits(pop)) pop++
+          for (let i = 0; i < pop; i++) (tokens -= costs.pop()!, out.pop(), rows.pop())
+          const lowest = out[out.length - 1]!.score
+          for (const e of wanted) {
+            if (out.length >= limit) break
+            const row = extraRows.get(e.rid)!
+            if (row.project !== project.id) continue
+            const text = redact(row.text)
+            const cost = approxTokens(text)
+            if (tokens + cost > maxTokens) continue
+            out.push({ text, kind: row.kind, name: row.name, score: expansionScore(lowest, e.overlap), source: row.source, id: row.item_id, scope: row.scope, owner: row.owner, project: row.project, ...(row.team ? { team: row.team } : {}) })
+            tokens += cost
+          }
+        }
+      }
+    }
+    audit(u.id, "recall", { project: auditProject(project.id), count: out.length, detail: `q=${hash}` })
+    return { items: out }
+  }
+
+  async function promote(u: UserRow, body: Obj): Promise<PromoteResponse> {
+    needRole(u, "editor", "promote or demote memory")
+    const ids = body.ids === undefined || body.ids === null ? undefined : strList(body.ids, "ids", MAX_ITEMS_PER_CALL, 200)
+    const source = str(body, "source", { max: 300 })
+    const bySource = source !== undefined ? projectOf(body.project) : undefined
+    if (ids ? !ids.length : !bySource) throw bad("give ids, or source with project")
+    const to = scopeOf(body.to, "to")
+    if (!to) throw bad("to is required")
+    const team = str(body, "team", { max: 64 })
+    const policy = db.policy()
+    if (scopeRank(to) > scopeRank(policy.maxScope)) throw new HttpError(403, "scope_above_policy", `scope ${to} is above what this organisation allows (${policy.maxScope})`)
+    if (to === "team") {
+      if (!team) throw bad("team is required for scope team")
+      if (!isId(team) || !db.isTeamMember(u.id, team)) throw forbidden("you are not a member of that team")
+    }
+    return await locked(async () => {
+      const rows = ids ? db.ownedByItemIds(u.id, ids) : db.itemsWhere({ owner: u.id, project: bySource!.id, source: source! }) // someone else's id is simply not here: same answer as an unknown id
+      if (to === "project") for (const r of rows) if (!db.isProjectMember(u.id, r.project)) throw forbidden("you are not a member of the project of one of these items")
+      let changed = 0
+      let widened = 0
+      let narrowed = 0
+      const dropped: Array<{ id: string; reason: string }> = []
+      for (const r of rows) {
+        const newTeam = to === "team" ? team! : null
+        if (r.scope === to && r.team === newTeam) continue
+        if (to !== "private") {
+          // the policy may have tightened since the item was stored
+          const x = graph.loadExtras(r.rid) // its entities and relations are part of what would be shared
+          const v = checkItem({ id: r.item_id, kind: r.kind, name: r.name, text: r.text, source: r.source, entities: x.entities, relations: x.relations }, policy)
+          if (!v.ok) {
+            dropped.push({ id: r.item_id, reason: v.reason })
+            continue
+          }
+        }
+        if (scopeRank(to) > scopeRank(r.scope)) widened++
+        else narrowed++
+        db.setItemScope(r.rid, to, newTeam)
+        applyAcl({ ...r, scope: to, team: newTeam })
+        changed++
+      }
+      const project = rows[0]?.project
+      const pj = project && rows.every((r) => r.project === project) ? auditProject(project, to === "private" ? "private" : to) : undefined
+      if (widened) audit(u.id, "promote", { scope: to, count: widened, ...(pj ? { project: pj } : {}) })
+      if (narrowed) audit(u.id, "demote", { scope: to, count: narrowed, ...(pj ? { project: pj } : {}) })
+      return { changed, ...(dropped.length ? { dropped } : {}) }
+    })
+  }
+
+  async function forget(u: UserRow, body: Obj): Promise<ForgetResponse> {
+    needRole(u, "editor", "forget memory")
+    const isAdmin = u.role === "admin"
+    if (body.mine === false && !isAdmin) throw forbidden("only an admin may forget other people's items")
+    const project = body.project === undefined || body.project === null ? undefined : projectOf(body.project)
+    const source = str(body, "source", { max: 300 })
+    const ids = body.ids === undefined || body.ids === null ? undefined : strList(body.ids, "ids", MAX_ITEMS_PER_CALL, 200)
+    if (!project && source === undefined && !ids) throw bad("say what to forget: ids, a project or a source")
+    const ownOnly = !isAdmin || body.mine === true || (ids === undefined && body.mine !== false)
+    return await locked(() => {
+      const rows = db.itemsWhere({ ...(ownOnly ? { owner: u.id } : {}), ...(project ? { project: project.id } : {}), ...(source !== undefined ? { source } : {}), ...(ids ? { ids } : {}) })
+      const removed = removeRows(rows)
+      const others = rows.filter((r) => r.owner !== u.id).length
+      audit(u.id, "forget", {
+        ...(project ? { project: auditProject(project.id, "private") } : {}),
+        count: removed,
+        ...(others ? { detail: `others=${others}` } : {}),
+      })
+      return { removed }
+    })
+  }
+
+  function projects(u: UserRow): ProjectsResponse {
+    return { projects: db.visibleProjects(u.id) }
+  }
+
+  /** GET /v1/graph?project=<id>[&entity=<name>]: the entities of a project as the caller may see them (shapes: graph.ts). */
+  function graphView(u: UserRow, url: URL) {
+    const project = url.searchParams.get("project")
+    const entity = url.searchParams.get("entity")
+    if (!project || project.length > 500 || project.includes("\u0000")) throw bad("project is required (at most 500 characters)")
+    if (entity !== null && (!entity.length || entity.length > 200 || CONTROL.test(entity))) throw bad("entity must be 1-200 characters")
+    const view = graph.view(u.id, project, entity ?? undefined)
+    const count = "entities" in view ? view.entities.length : view.items.length
+    audit(u.id, "graph", { project: auditProject(project), count, ...(entity !== null ? { detail: `e=${hmac(entity.normalize("NFKC").toLowerCase().trim()).slice(0, 16)}` } : {}) })
+    return view
+  }
+
+  function whoami(u: UserRow): WhoAmI {
+    return { user: db.orgUser(u), org, policy: db.policy(), api: 1 }
+  }
+
+  // ---- admin ----
+  function addUser(a: UserRow, body: Obj) {
+    const id = reqStr(body, "id", 64)
+    if (!isId(id)) throw bad("id must be 1-64 characters: letters, digits, . _ @ - (starting with a letter or digit)")
+    const name = reqStr(body, "name", 200)
+    const role = body.role
+    if (typeof role !== "string" || !(ROLES as string[]).includes(role)) throw bad(`role must be one of ${ROLES.join(", ")}`)
+    const teams = strList(body.teams, "teams", 50, 64)
+    for (const t of teams) if (!db.team(t)) throw new HttpError(404, "not_found", `no such team: ${t}`)
+    if (db.user(id)) throw bad("a user with that id already exists")
+    db.tx(() => {
+      db.addUser(id, name.trim() || id, role as Role)
+      for (const t of teams) db.addTeamMember(t, id)
+    })
+    if (teams.length) syncGroups()
+    audit(a.id, "admin.user.add", { detail: `user=${id} role=${role}${teams.length ? ` teams=${teams.join(",")}` : ""}` })
+    return db.orgUser(db.user(id)!)
+  }
+  function disableUser(a: UserRow, body: Obj) {
+    const id = reqStr(body, body.id === undefined ? "user" : "id", 64)
+    const disabled = body.disabled === undefined ? true : body.disabled
+    if (typeof disabled !== "boolean") throw bad("disabled must be true or false")
+    const target = db.user(id)
+    if (!target) throw new HttpError(404, "not_found", "no such user")
+    if (disabled && target.role === "admin" && !target.disabled && db.activeAdmins() <= 1) throw new HttpError(400, "last_admin", "that is the last active admin: create another admin first")
+    db.setDisabled(id, disabled)
+    audit(a.id, disabled ? "admin.user.disable" : "admin.user.enable", { detail: `user=${id}` })
+    return { ok: true }
+  }
+  function createToken(a: UserRow, body: Obj) {
+    const user = reqStr(body, "user", 64)
+    const days = intOf(body, "expiresInDays", 1, 3650)
+    const target = db.user(user)
+    if (!target) throw new HttpError(404, "not_found", "no such user")
+    if (target.disabled) throw bad("that user is disabled")
+    const t = db.createToken(user, days)
+    audit(a.id, "admin.token.create", { detail: `user=${user} token=${t.id}${days ? ` expiresInDays=${days}` : ""}` })
+    return t
+  }
+  function revokeToken(a: UserRow, body: Obj) {
+    const id = reqStr(body, "id", 64)
+    if (!db.revokeToken(id)) throw new HttpError(404, "not_found", "no such token")
+    audit(a.id, "admin.token.revoke", { detail: `token=${id}` })
+    return { ok: true }
+  }
+  function setTeam(a: UserRow, body: Obj) {
+    const id = reqStr(body, "id", 64)
+    if (!isId(id)) throw bad("team id must be 1-64 characters: letters, digits, . _ @ - (starting with a letter or digit)")
+    const name = reqStr(body, "name", 200)
+    const members = strList(body.members, "members", 1_000, 64)
+    for (const m of members) if (!db.user(m)) throw new HttpError(404, "not_found", `no such user: ${m}`)
+    db.setTeam(id, name.trim() || id, members)
+    syncGroups()
+    audit(a.id, "admin.team.set", { detail: `team=${id} members=${new Set(members).size}` })
+    return { ok: true }
+  }
+  function projectMembers(a: UserRow, body: Obj) {
+    const project = reqStr(body, "project", 500)
+    const parse = (x: unknown, key: string): { users: string[]; teams: string[] } => {
+      if (x === undefined || x === null) return { users: [], teams: [] }
+      if (Array.isArray(x)) {
+        const list = strList(x, key, 1_000, 70)
+        return { users: list.filter((s) => !s.startsWith("team:")).map((s) => s.replace(/^user:/, "")), teams: list.filter((s) => s.startsWith("team:")).map((s) => s.slice(5)) }
+      }
+      if (!isObj(x)) throw bad(`${key} must be {users?: string[], teams?: string[]}`)
+      return { users: strList(x.users, `${key}.users`, 1_000, 64), teams: strList(x.teams, `${key}.teams`, 1_000, 64) }
+    }
+    const add = parse(body.add, "add")
+    const remove = parse(body.remove, "remove")
+    for (const u of add.users) if (!db.user(u)) throw new HttpError(404, "not_found", `no such user: ${u}`)
+    for (const t of add.teams) if (!db.team(t)) throw new HttpError(404, "not_found", `no such team: ${t}`)
+    db.tx(() => {
+      for (const u of add.users) db.addProjectMember(project, "user", u)
+      for (const t of add.teams) db.addProjectMember(project, "team", t)
+      for (const u of remove.users) db.removeProjectMember(project, "user", u)
+      for (const t of remove.teams) db.removeProjectMember(project, "team", t)
+    })
+    syncGroups()
+    audit(a.id, "admin.project.members", {
+      project,
+      detail: `add=${add.users.length + add.teams.length} remove=${remove.users.length + remove.teams.length}`,
+    })
+    return { ok: true }
+  }
+  function putPolicy(a: UserRow, body: unknown): Policy {
+    let p: Policy
+    try {
+      p = normalizePolicy(body)
+    } catch (e) {
+      throw new HttpError(400, "invalid_policy", (e as Error).message)
+    }
+    db.setPolicy(p)
+    audit(a.id, "admin.policy.set", { detail: `maxScope=${p.maxScope} defaultScope=${p.defaultScope}` })
+    return p
+  }
+  function auditLog(url: URL): AuditEvent[] {
+    const sinceRaw = url.searchParams.get("since")
+    let since: string | undefined
+    if (sinceRaw) {
+      const t = /^\d+$/.test(sinceRaw) ? Number(sinceRaw) : Date.parse(sinceRaw)
+      if (!Number.isFinite(t)) throw bad("since must be an ISO date or a millisecond timestamp")
+      since = new Date(t).toISOString()
+    }
+    const lim = url.searchParams.get("limit")
+    const limit = lim === null ? 200 : Number(lim)
+    if (!Number.isInteger(limit) || limit < 1 || limit > 1_000) throw bad("limit must be an integer from 1 to 1000")
+    return db.auditEvents(since, limit)
+  }
+
+  // ---- HTTP --------------------------------------------------------------------------------------------------------------
+
+  const baseHeaders = { "content-type": "application/json; charset=utf-8", "cache-control": "no-store", "x-content-type-options": "nosniff" }
+  const json = (status: number, body: unknown, extra?: Record<string, string>): Response => new Response(JSON.stringify(body), { status, headers: { ...baseHeaders, ...extra } })
+  const fail = (e: HttpError): Response => json(e.status, { error: e.message, code: e.code } satisfies OrgError, e.headers)
+
+  async function readJson(req: Request): Promise<Obj> {
+    const declared = Number(req.headers.get("content-length") ?? "0")
+    const tooLarge = () => new HttpError(413, "too_large", `request body is too large (at most ${MAX_BODY_BYTES} bytes)`, { connection: "close" })
+    if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+      // Read and discard (Bun's own backstop limits this to 2x the cap): answering while the client is still sending can stall it.
+      if (req.body) {
+        const r = req.body.getReader()
+        try {
+          while (!(await r.read()).done);
+        } catch {}
+      }
+      throw tooLarge()
+    }
+    const chunks: Uint8Array[] = []
+    let total = 0
+    if (req.body) {
+      const reader = req.body.getReader()
+      for (;;) {
+        const { done, value } = await reader.read()
+        if (done) break
+        total += value.byteLength
+        if (total > MAX_BODY_BYTES) {
+          void reader.cancel().catch(() => {})
+          throw tooLarge()
+        }
+        chunks.push(value)
+      }
+    }
+    if (!total) return {}
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"))
+    } catch {
+      throw new HttpError(400, "invalid_json", "the request body is not valid JSON")
+    }
+    if (!isObj(parsed)) throw new HttpError(400, "invalid_json", "the request body must be a JSON object")
+    return parsed
+  }
+
+  type Route = { admin?: boolean; body?: boolean; run: (u: UserRow, body: Obj, url: URL) => unknown | Promise<unknown> }
+  const routes: Record<string, Route> = {
+    "GET /v1/whoami": { run: (u) => whoami(u) },
+    "POST /v1/ingest": { body: true, run: (u, b) => ingest(u, b) },
+    "POST /v1/recall": { body: true, run: (u, b) => recall(u, b) },
+    "POST /v1/promote": { body: true, run: (u, b) => promote(u, b) },
+    "POST /v1/forget": { body: true, run: (u, b) => forget(u, b) },
+    "GET /v1/projects": { run: (u) => projects(u) },
+    "GET /v1/graph": { run: (u, _b, url) => graphView(u, url) },
+    "POST /v1/admin/users": { admin: true, body: true, run: (u, b) => addUser(u, b) },
+    "GET /v1/admin/users": { admin: true, run: () => db.users().map((r) => db.orgUser(r)) },
+    "POST /v1/admin/users/disable": { admin: true, body: true, run: (u, b) => disableUser(u, b) },
+    "POST /v1/admin/tokens": { admin: true, body: true, run: (u, b) => createToken(u, b) },
+    "GET /v1/admin/tokens": { admin: true, run: () => db.tokens() },
+    "POST /v1/admin/tokens/revoke": { admin: true, body: true, run: (u, b) => revokeToken(u, b) },
+    "POST /v1/admin/teams": { admin: true, body: true, run: (u, b) => setTeam(u, b) },
+    "POST /v1/admin/projects/members": { admin: true, body: true, run: (u, b) => projectMembers(u, b) },
+    "GET /v1/admin/policy": { admin: true, run: () => db.policy() },
+    "PUT /v1/admin/policy": { admin: true, body: true, run: (u, b) => putPolicy(u, b) },
+    "GET /v1/admin/sso": { admin: true, run: () => getSsoAdmin(db) },
+    "PUT /v1/admin/sso": {
+      admin: true,
+      body: true,
+      run: (u, b) => {
+        try {
+          return putSsoAdmin(db, u.id, b)
+        } catch (e) {
+          if (e instanceof SsoInputError) throw new HttpError(400, "invalid_sso", e.message)
+          throw e
+        }
+      },
+    },
+    "GET /v1/admin/audit": { admin: true, run: (_u, _b, url) => auditLog(url) },
+    "POST /v1/admin/retention/run": { admin: true, run: async (u) => ({ removed: await runRetention(u.id) }) },
+  }
+  const paths = new Set(Object.keys(routes).map((k) => k.split(" ")[1]!))
+
+  async function handle(req: Request, ip: string): Promise<Response> {
+    const url = new URL(req.url)
+    const path = url.pathname
+    if (path === "/v1/health") {
+      if (req.method !== "GET") throw new HttpError(405, "method_not_allowed", "use GET")
+      return json(200, { ok: true, api: 1 })
+    }
+    // Single sign-on endpoints come before authentication: they are how a person gets a token (see sso.ts).
+    if (path.startsWith("/v1/auth/")) {
+      const t0 = now()
+      if (!signInLimit.hit(ip, t0)) throw new HttpError(429, "rate_limited", "too many sign-in attempts; wait a minute", { "retry-after": String(signInLimit.retryAfter(ip, t0)) })
+      const { handleSso } = await import("./sso.ts")
+      const r = await handleSso(req, { db, now, ip })
+      if (r) return r
+      throw new HttpError(404, "not_found", "no such endpoint")
+    }
+    const t = now()
+    const auth = authenticate(db, req.headers.get("authorization"), t)
+    if (!auth.ok) {
+      // a valid token is never throttled by someone else's failures from the same address; failures are
+      if (failLimit.blocked(ip, t)) throw new HttpError(429, "rate_limited", "too many failed attempts; wait a minute", { "retry-after": String(failLimit.retryAfter(ip, t)) })
+      failLimit.hit(ip, t)
+      auditAuthFail(auth.reason, auth.actor)
+      throw new HttpError(401, "unauthorized", "missing, invalid, expired or revoked token")
+    }
+    if (!rateLimit.hit(auth.tokenId, t)) throw new HttpError(429, "rate_limited", "too many requests; slow down", { "retry-after": String(rateLimit.retryAfter(auth.tokenId, t)) })
+    const route = routes[`${req.method} ${path}`]
+    if (!route) {
+      if (paths.has(path)) throw new HttpError(405, "method_not_allowed", "wrong method for this path")
+      throw new HttpError(404, "not_found", "no such endpoint")
+    }
+    // the user row is re-read per request: a role or disabled flag changed a moment ago applies now
+    const u = auth.user
+    if (route.admin && u.role !== "admin") throw forbidden("this needs the admin role")
+    const body = route.body ? await readJson(req) : {}
+    const result = await route.run(u, body, url)
+    return json(200, result)
+  }
+
+  let server: ReturnType<typeof Bun.serve>
+  try {
+    server = Bun.serve({
+    port: opts.port ?? 4500,
+    hostname: opts.host ?? "127.0.0.1",
+    ...(tls ? { tls: { cert: tls.cert, key: tls.key } } : {}),
+    maxRequestBodySize: MAX_BODY_BYTES * 2, // backstop; the handler enforces the real cap with a proper error body
+    idleTimeout: 30,
+    async fetch(req, srv) {
+      try {
+        return await handle(req, clientAddress(req, srv.requestIP(req)?.address, !!opts.trustProxy))
+      } catch (e) {
+        if (e instanceof HttpError) return fail(e)
+        // never a stack trace or a message to the client; one terse line for the operator
+        process.stderr.write(`brain org: internal error: ${(e as Error)?.name ?? "Error"}\n`)
+        return json(500, { error: "internal error", code: "internal" } satisfies OrgError)
+      }
+    },
+    error() {
+      return json(500, { error: "internal error", code: "internal" } satisfies OrgError)
+    },
+  })
+  } catch (e) {
+    // the port is taken or the address is invalid: leave nothing behind (timer, lock file, open database)
+    if (retentionTimer) clearInterval(retentionTimer)
+    try {
+      chitta.close()
+    } catch {}
+    releaseLock()
+    throw e
+  }
+
+  let stopped = false
+  return {
+    url: `${tls ? "https" : "http"}://${server.hostname}:${server.port}`,
+    port: server.port ?? 0,
+    async stop() {
+      if (stopped) return
+      stopped = true
+      if (retentionTimer) clearInterval(retentionTimer)
+      await server.stop(true)
+      await chain
+      try {
+        chitta.close()
+      } catch {}
+      releaseLock()
+    },
+  }
+}