@huynle/hub 0.7.3 → 0.8.0

package/src/central/teams/store.ts

@@ -0,0 +1,667 @@
+// Persistent team definitions (HWA-33; contract packages/protocol/src/teams.ts and docs/plans/2026-10-30-hub-
+// workspaces-artifacts-contracts.md, Teams + clarifications; decisions zltiwb4s, 5etngvgm, r3vv4eon, qxzrdc6c).
+//
+// A team is a versioned definition (roles, one entry role, open/restricted communication with directed edges,
+// tags/metadata/projects), independent of any running session. It grants no authority.
+//
+// Storage: StateStore collections under the hub user (the tenant key; another user's records are absent), so the
+// standalone file store and the cluster's Postgres hub_state behave alike and need no migration:
+// - `teams` (key team ID): the record — the published spec, state (active/archived), `paused`, the published
+//   `version`, the retained version history (number, digest, publishedAt) and at most one pending `draft`.
+//   `revision` is the StateStore version of the key: every write is version-checked (ifVersion), so a stale
+//   expectedRevision is 409 conflict with currentRevision, and of two writers holding one revision exactly one wins.
+// - `team-version.<team ID>` (key `<n>`): one immutable published revision each ({spec, digest, publishedAt}).
+//   Slot n is written only by the writer whose record CAS made n the published version (or rebuilt from the record
+//   while n is still current, after a crash between the two writes), so a slot never holds another writer's spec.
+// - `team-index` (key `names`): {name → {id, at, archived?}} — unique names per user (the `#team` address) and the
+//   cap on active teams (TEAM_LIMITS.teamsPerUser, 429). A reservation whose record never appeared is reclaimed
+//   after reservationMs.
+// - `team-idempotency` (key: Idempotency-Key): {teamID, digest, at}, valid IDEMPOTENCY_TTL_MS.
+// - `team-settings` (key `owner`): the owner's `teamIsolation` setting (default off; HWA-40 reads it).
+//
+// Edits are drafts: saveDraft builds on the pending draft (or the published spec) and publish freezes it as the next
+// version; the published spec is what delivery (HWA-34) and staffing (HWA-35) use. Retention keeps the newest
+// versionsRetained versions plus any a caller pins (pinnedVersions, e.g. staffing referencing a revision).
+// Pause and archive are operational states and change no definition. Archived teams keep their name reserved and
+// do not count toward the cap; restore re-checks it.
+//
+// Records from other builds: a newer `v` is never guessed at (lists skip it; reads and writes answer 422
+// unsupported); a malformed record is skipped by lists and a 500 on read. Older hubs never read these collections.
+import { randomBytes } from "node:crypto"
+import {
+  CONTRACT_VERSION,
+  ID_PREFIXES,
+  IDEMPOTENCY_KEY,
+  IDEMPOTENCY_TTL_MS,
+  type IdKind,
+  isExpectedRevision,
+  isLabel,
+  LIST_LIMIT_DEFAULT,
+  LIST_LIMIT_MAX,
+  metadataProblem,
+  type Page,
+  RECORD_STATES,
+  type RecordState,
+  TEAM_LIMITS,
+  type TeamDefinition,
+  tagsProblem,
+} from "../../protocol"
+import { AgentError } from "../agent/errors"
+import { updateVersioned } from "../agent/versioned"
+import type { Clock, StateStore } from "../backend/types"
+import { currentSeats, readSeatsDoc, TEAM_SEATS } from "./collections"
+import { diffTeamSpecs, specDigest, TEAM_STORE_LIMITS, type TeamDiff, type TeamRoleSpec, type TeamSpec, teamPatchOf, teamSpecOf } from "./validation"
+
+export const TEAMS = "teams"
+export const TEAM_INDEX = "team-index"
+export const TEAM_IDEMPOTENCY = "team-idempotency"
+export const TEAM_SETTINGS = "team-settings"
+export const teamVersionCollection = (teamID: string): string => `team-version.${teamID}`
+const NAMES = "names"
+const OWNER = "owner"
+const ATTEMPTS = 16
+/** Reads of an idempotency key's team: its creator may be between the claim and the write. */
+const READS = 5
+
+export interface TeamStoreLimits {
+  readonly teamsPerUser: number
+  readonly versionsRetained: number
+  /** A reservation (name, idempotency key) whose team never got written blocks this long. */
+  readonly reservationMs: number
+}
+
+/** One retained published revision as history shows it. */
+export interface TeamVersionEntry {
+  readonly version: number
+  readonly digest: string
+  readonly publishedAt: number
+}
+
+/** An immutable published revision. */
+export interface TeamVersion {
+  readonly v: 1
+  readonly teamID: string
+  readonly version: number
+  readonly spec: TeamSpec
+  readonly digest: string
+  readonly publishedAt: number
+}
+
+/** Pending edits (published on explicit publish). */
+export interface TeamDraft {
+  readonly baseVersion: number
+  readonly spec: TeamSpec
+  readonly digest: string
+  readonly savedAt: number
+}
+
+/** A team as reads show it: the contract TeamDefinition of the published spec plus the additive fields. */
+export interface Team extends TeamDefinition {
+  readonly roles: readonly TeamRoleSpec[]
+  readonly projects?: readonly string[]
+  /** The published revision number (1 on create, +1 per publish). */
+  readonly version: number
+  /** Present (true) while paused: intake and new staffing stop; policy still applies. */
+  readonly paused?: true
+  readonly draft?: Omit<TeamDraft, "spec">
+  readonly createdAt: number
+  readonly publishedAt: number
+}
+
+export interface TeamListQuery {
+  /** active (default), archived or all. */
+  readonly state?: string
+  /** Teams carrying every one of these tags. */
+  readonly tags?: readonly string[]
+  readonly project?: string
+  /** Teams whose metadata has every one of these key/value pairs. */
+  readonly metadata?: Readonly<Record<string, string>>
+  readonly paused?: boolean
+  readonly limit?: number
+  readonly cursor?: string
+}
+
+export interface TeamSettings {
+  readonly teamIsolation: boolean
+  readonly revision: number
+  readonly updatedAt?: number
+}
+
+/** Versions a caller still references (never dropped by retention). */
+export type PinnedVersions = (userID: string, teamID: string) => Promise<ReadonlySet<number>>
+
+export interface TeamStoreDeps {
+  readonly state: StateStore
+  readonly now?: Clock
+  readonly newID?: (kind: IdKind) => string
+  readonly limits?: Partial<TeamStoreLimits>
+  readonly pinnedVersions?: PinnedVersions
+}
+
+interface TeamRecord {
+  readonly v: 1
+  readonly id: string
+  readonly spec: TeamSpec
+  readonly state: RecordState
+  readonly paused?: true
+  readonly version: number
+  readonly history: readonly TeamVersionEntry[]
+  readonly draft?: TeamDraft
+  readonly createdAt: number
+  readonly publishedAt: number
+  readonly updatedAt: number
+}
+
+interface NameEntry {
+  readonly id: string
+  readonly at: number
+  readonly archived?: true
+}
+interface NameIndex {
+  readonly v: 1
+  readonly names: Readonly<Record<string, NameEntry>>
+}
+interface IdempotencyDoc {
+  readonly v: 1
+  readonly teamID: string
+  readonly digest: string
+  readonly at: number
+}
+interface SettingsDoc {
+  readonly v: 1
+  readonly teamIsolation: boolean
+  readonly updatedAt: number
+}
+
+type Readout = { readonly ok: true; readonly record: TeamRecord } | { readonly ok: false; readonly why: "newer" | "malformed"; readonly v?: unknown }
+
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+const isNum = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v)
+
+const conflict = (what: string, currentRevision: number) =>
+  new AgentError("conflict", `${what} changed since you read it (revision ${currentRevision} now)`, {
+    hint: "Read it again and retry with its current revision",
+    extra: { currentRevision },
+  })
+
+const notFound = (id: string) => new AgentError("not_found", `No team ${id}`)
+
+function checkExpected(v: unknown): number {
+  if (!isExpectedRevision(v)) throw new AgentError("invalid", "expectedRevision is required (the revision you read)")
+  return v
+}
+
+function isSpecShape(v: unknown): v is TeamSpec {
+  return isObj(v) && typeof v.name === "string" && typeof v.title === "string" && typeof v.entryRole === "string" && Array.isArray(v.roles) && Array.isArray(v.edges) && (v.mode === "open" || v.mode === "restricted")
+}
+
+/** A stored team as this build reads it (newer versions are refused, malformed ones reported). */
+export function readTeam(key: string, raw: unknown): Readout {
+  if (!isObj(raw)) return { ok: false, why: "malformed" }
+  const v = raw.v
+  if (isNum(v) && v > CONTRACT_VERSION) return { ok: false, why: "newer", v }
+  if (v !== CONTRACT_VERSION) return { ok: false, why: "malformed" }
+  const draft = raw.draft
+  const valid =
+    raw.id === key &&
+    isSpecShape(raw.spec) &&
+    RECORD_STATES.includes(raw.state as RecordState) &&
+    (raw.paused === undefined || raw.paused === true) &&
+    Number.isSafeInteger(raw.version) &&
+    (raw.version as number) >= 1 &&
+    Array.isArray(raw.history) &&
+    (draft === undefined || (isObj(draft) && isSpecShape(draft.spec) && typeof draft.digest === "string")) &&
+    isNum(raw.createdAt) &&
+    isNum(raw.publishedAt) &&
+    isNum(raw.updatedAt)
+  return valid ? { ok: true, record: raw as unknown as TeamRecord } : { ok: false, why: "malformed" }
+}
+
+/** The API view of a record at a StateStore version. */
+export function teamView(record: TeamRecord, revision: number): Team {
+  const d = record.draft
+  return {
+    v: 1,
+    id: record.id,
+    ...record.spec,
+    state: record.state,
+    ...(record.paused ? { paused: true as const } : {}),
+    version: record.version,
+    revision,
+    ...(d ? { draft: { baseVersion: d.baseVersion, digest: d.digest, savedAt: d.savedAt } } : {}),
+    createdAt: record.createdAt,
+    publishedAt: record.publishedAt,
+    updatedAt: record.updatedAt,
+  }
+}
+
+const byCreation = (a: Team, b: Team) => a.createdAt - b.createdAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)
+const encodeCursor = (value: unknown) => Buffer.from(JSON.stringify(value)).toString("base64url")
+function decodeCursor(cursor: string): unknown {
+  try {
+    return JSON.parse(Buffer.from(cursor, "base64url").toString("utf8")) as unknown
+  } catch {
+    throw new AgentError("invalid", "cursor is not one this list gave", { hint: "Start again without a cursor" })
+  }
+}
+function pageLimit(limit: number | undefined): number {
+  const n = limit ?? LIST_LIMIT_DEFAULT
+  if (!Number.isSafeInteger(n) || n < 1 || n > LIST_LIMIT_MAX) throw new AgentError("invalid", `limit must be 1–${LIST_LIMIT_MAX}`)
+  return n
+}
+
+export class TeamStore {
+  readonly state: StateStore
+  readonly limits: TeamStoreLimits
+  private readonly now: Clock
+  private readonly newID: (kind: IdKind) => string
+  private readonly pinned?: PinnedVersions
+
+  constructor(deps: TeamStoreDeps) {
+    this.state = deps.state
+    this.now = deps.now ?? Date.now
+    this.newID = deps.newID ?? ((kind) => `${ID_PREFIXES[kind]}_${randomBytes(12).toString("hex")}`)
+    this.pinned = deps.pinnedVersions
+    this.limits = {
+      teamsPerUser: deps.limits?.teamsPerUser ?? TEAM_LIMITS.teamsPerUser,
+      versionsRetained: deps.limits?.versionsRetained ?? TEAM_STORE_LIMITS.versionsRetained,
+      reservationMs: deps.limits?.reservationMs ?? 60_000,
+    }
+  }
+
+  // ---------- create and read ----------
+
+  /**
+   * Creates an active team whose version 1 is published at once (name_taken for a used name, 429 at the cap).
+   * With an Idempotency-Key, the same key and body within IDEMPOTENCY_TTL_MS return the original (created false);
+   * another body is a conflict.
+   */
+  async create(userID: string, input: unknown, options: { readonly idempotencyKey?: string } = {}): Promise<{ team: Team; created: boolean }> {
+    const spec = teamSpecOf(input)
+    const key = options.idempotencyKey
+    if (key === undefined) return { team: await this.insert(userID, this.newID("team"), spec), created: true }
+    if (!IDEMPOTENCY_KEY.test(key)) throw new AgentError("invalid", "Idempotency-Key must be 1–200 of A-Z a-z 0-9 _ . : -")
+    const digest = specDigest(spec)
+    await this.pruneKeys(userID)
+    for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+      const held = await this.state.get<IdempotencyDoc>(userID, TEAM_IDEMPOTENCY, key)
+      const live = held && isObj(held.value) && isNum(held.value.at) && this.now() - held.value.at < IDEMPOTENCY_TTL_MS ? held.value : undefined
+      if (live) {
+        if (live.digest !== digest) throw new AgentError("conflict", `Idempotency-Key ${key} was used for a different team`, { hint: "Use a new key for a different body, or resend the original body" })
+        const existing = await this.readSoon(userID, live.teamID)
+        if (existing) return { team: existing, created: false }
+        if (this.now() - live.at < this.limits.reservationMs)
+          throw new AgentError("rate_limited", `The team for Idempotency-Key ${key} is still being created`, { extra: { retryAfter: 1 } })
+      }
+      const id = this.newID("team")
+      const claimed = await this.state.put<IdempotencyDoc>(userID, TEAM_IDEMPOTENCY, key, { v: 1, teamID: id, digest, at: this.now() }, { ifVersion: held?.version ?? 0 })
+      if (!claimed.ok) continue
+      try {
+        return { team: await this.insert(userID, id, spec), created: true }
+      } catch (error) {
+        await this.state.delete(userID, TEAM_IDEMPOTENCY, key, { ifVersion: claimed.version })
+        throw error
+      }
+    }
+    throw new Error(`team idempotency key ${key} kept conflicting`)
+  }
+
+  /** The user's team, or undefined (also another user's); throws for records this build cannot read. */
+  async get(userID: string, id: string): Promise<Team | undefined> {
+    const stored = await this.loaded(userID, id)
+    return stored && teamView(stored.record, stored.revision)
+  }
+
+  async require(userID: string, id: string): Promise<Team> {
+    const team = await this.get(userID, id)
+    if (!team) throw notFound(id)
+    return team
+  }
+
+  /** The user's team by its name (the `#team` address), or undefined. */
+  async byName(userID: string, name: string): Promise<Team | undefined> {
+    const entry = (await this.index(userID))?.names[name]
+    if (!entry) return undefined
+    const team = await this.get(userID, entry.id)
+    return team?.name === name ? team : undefined
+  }
+
+  /** Teams by creation, filtered by state (default active), tags, project, metadata and pause; paged. */
+  async list(userID: string, query: TeamListQuery = {}): Promise<Page<Team>> {
+    const limit = pageLimit(query.limit)
+    const wanted = query.state ?? "active"
+    if (wanted !== "all" && !RECORD_STATES.includes(wanted as RecordState)) throw new AgentError("invalid", "state must be active, archived or all")
+    const problem = tagsProblem(query.tags) ?? metadataProblem(query.metadata)
+    if (problem) throw new AgentError("invalid", problem)
+    if (query.project !== undefined && !isLabel(query.project)) throw new AgentError("invalid", "project must be a project name")
+    let after: [number, string] | undefined
+    if (query.cursor !== undefined) {
+      const parsed = decodeCursor(query.cursor)
+      if (!Array.isArray(parsed) || parsed.length !== 2 || !isNum(parsed[0]) || typeof parsed[1] !== "string")
+        throw new AgentError("invalid", "cursor is not one this list gave", { hint: "Start again without a cursor" })
+      after = [parsed[0], parsed[1]]
+    }
+    const all = (await this.readAll(userID))
+      .filter((t) => wanted === "all" || t.state === wanted)
+      .filter((t) => !query.tags || query.tags.every((tag) => t.tags?.includes(tag)))
+      .filter((t) => query.project === undefined || (t.projects ?? []).includes(query.project))
+      .filter((t) => !query.metadata || Object.entries(query.metadata).every(([k, v]) => t.metadata?.[k] === v))
+      .filter((t) => query.paused === undefined || (t.paused === true) === query.paused)
+      .filter((t) => !after || t.createdAt > after[0] || (t.createdAt === after[0] && t.id > after[1]))
+      .sort(byCreation)
+    const items = all.slice(0, limit)
+    return all.length > limit ? { items, cursor: encodeCursor([items.at(-1)!.createdAt, items.at(-1)!.id]) } : { items }
+  }
+
+  // ---------- drafts, publish, history ----------
+
+  /** The pending draft, if any. */
+  async draft(userID: string, id: string): Promise<TeamDraft | undefined> {
+    return (await this.requireLoaded(userID, id)).record.draft
+  }
+
+  /** Saves edits as the pending draft (built on the draft or the published spec); the published spec is unchanged. */
+  async saveDraft(userID: string, id: string, patch: unknown, expectedRevision: number): Promise<Team> {
+    const expected = checkExpected(expectedRevision)
+    return this.mutate(userID, id, expected, (record) => {
+      this.active(record)
+      const spec = teamPatchOf(record.draft?.spec ?? record.spec, patch)
+      return { ...record, draft: { baseVersion: record.version, spec, digest: specDigest(spec), savedAt: this.now() } }
+    })
+  }
+
+  async discardDraft(userID: string, id: string, expectedRevision: number): Promise<Team> {
+    const expected = checkExpected(expectedRevision)
+    return this.mutate(userID, id, expected, (record) => {
+      if (!record.draft) throw new AgentError("invalid", `Team ${id} has no draft`)
+      const { draft: _d, ...rest } = record
+      return rest
+    })
+  }
+
+  /**
+   * Publishes the draft as the next immutable version. A draft equal to the published spec is dropped without a
+   * new version (published false). Refused while sessions are staffed in a role the draft removes.
+   */
+  async publish(userID: string, id: string, expectedRevision: number): Promise<{ team: Team; published: boolean }> {
+    const expected = checkExpected(expectedRevision)
+    const { record, revision } = await this.requireLoaded(userID, id)
+    if (revision !== expected) throw conflict(`Team ${id}`, revision)
+    this.active(record)
+    const draft = record.draft
+    if (!draft) throw new AgentError("invalid", `Team ${id} has no draft to publish`, { hint: "Save a draft first" })
+    if (draft.digest === specDigest(record.spec)) {
+      const { draft: _d, ...rest } = record
+      return { team: await this.write(userID, id, rest, revision), published: false }
+    }
+    const roles = new Set(draft.spec.roles.map((r) => r.name))
+    const staffed = [...new Set(currentSeats(readSeatsDoc((await this.state.get(userID, TEAM_SEATS, id))?.value, id)).map((s) => s.role))].filter((r) => !roles.has(r)).sort()
+    if (staffed.length > 0)
+      throw new AgentError("invalid", `Sessions are staffed in roles this draft removes: ${staffed.join(", ")}`, { hint: "Unstaff those roles first", extra: { roles: staffed } })
+    await this.ensureSlot(userID, record)
+    const at = this.now()
+    const number = record.version + 1
+    const entry: TeamVersionEntry = { version: number, digest: draft.digest, publishedAt: at }
+    const pinned = (await this.pinned?.(userID, id)) ?? new Set<number>()
+    const history = [...record.history, entry].sort((a, b) => b.version - a.version)
+    const kept = history.filter((h, i) => i < this.limits.versionsRetained || pinned.has(h.version))
+    const dropped = history.filter((h) => !kept.includes(h))
+    const { draft: _d, ...rest } = record
+    const team = await this.write(userID, id, { ...rest, spec: draft.spec, version: number, history: kept.sort((a, b) => a.version - b.version), publishedAt: at }, revision)
+    await this.state.put<TeamVersion>(userID, teamVersionCollection(id), String(number), { v: 1, teamID: id, version: number, spec: draft.spec, digest: draft.digest, publishedAt: at }, { ifVersion: 0 })
+    for (const victim of dropped) await this.state.delete(userID, teamVersionCollection(id), String(victim.version))
+    return { team, published: true }
+  }
+
+  /** A retained published revision (undefined when dropped or never published). */
+  async version(userID: string, id: string, number: number): Promise<TeamVersion | undefined> {
+    const { record } = await this.requireLoaded(userID, id)
+    if (!record.history.some((h) => h.version === number)) return undefined
+    const slot = await this.state.get<TeamVersion>(userID, teamVersionCollection(id), String(number))
+    if (slot) return slot.value
+    if (number !== record.version) return undefined
+    return this.ensureSlot(userID, record)
+  }
+
+  /** Retained versions, newest first, paged. */
+  async history(userID: string, id: string, options: { readonly limit?: number; readonly cursor?: string } = {}): Promise<Page<TeamVersionEntry>> {
+    const limit = pageLimit(options.limit)
+    let before = Number.POSITIVE_INFINITY
+    if (options.cursor !== undefined) {
+      const parsed = decodeCursor(options.cursor)
+      if (!Number.isSafeInteger(parsed)) throw new AgentError("invalid", "cursor is not one this list gave", { hint: "Start again without a cursor" })
+      before = parsed as number
+    }
+    const { record } = await this.requireLoaded(userID, id)
+    const all = [...record.history].sort((a, b) => b.version - a.version).filter((h) => h.version < before)
+    const items = all.slice(0, limit)
+    return all.length > limit ? { items, cursor: encodeCursor(items.at(-1)!.version) } : { items }
+  }
+
+  /** What changed between two retained versions, or from a version to the pending draft. */
+  async diff(userID: string, id: string, from: number, to: number | "draft"): Promise<TeamDiff> {
+    const a = await this.version(userID, id, from)
+    if (!a) throw new AgentError("not_found", `Team ${id} has no retained version ${from}`)
+    if (to === "draft") {
+      const draft = await this.draft(userID, id)
+      if (!draft) throw new AgentError("not_found", `Team ${id} has no draft`)
+      return diffTeamSpecs(a.spec, draft.spec)
+    }
+    const b = await this.version(userID, id, to)
+    if (!b) throw new AgentError("not_found", `Team ${id} has no retained version ${to}`)
+    return diffTeamSpecs(a.spec, b.spec)
+  }
+
+  // ---------- status ----------
+
+  /** Pauses an active team (intake and new staffing stop; HWA-35/36). Pausing a paused team is a no-op. */
+  async pause(userID: string, id: string, expectedRevision: number): Promise<Team> {
+    const expected = checkExpected(expectedRevision)
+    return this.mutate(userID, id, expected, (record) => {
+      this.active(record)
+      return record.paused ? undefined : { ...record, paused: true }
+    })
+  }
+
+  async resume(userID: string, id: string, expectedRevision: number): Promise<Team> {
+    const expected = checkExpected(expectedRevision)
+    return this.mutate(userID, id, expected, (record) => {
+      this.active(record)
+      if (!record.paused) return undefined
+      const { paused: _p, ...rest } = record
+      return rest
+    })
+  }
+
+  /** Archives the team (reversible; its name stays reserved). Archiving an archived team is a no-op. */
+  async archive(userID: string, id: string, expectedRevision: number): Promise<Team> {
+    const expected = checkExpected(expectedRevision)
+    const team = await this.mutate(userID, id, expected, (record) => (record.state === "archived" ? undefined : { ...record, state: "archived" }))
+    await this.markArchived(userID, team.name, id, true)
+    return team
+  }
+
+  /** Makes an archived team active again (429 at the cap). Restoring an active team is a no-op. */
+  async restore(userID: string, id: string, expectedRevision: number): Promise<Team> {
+    const expected = checkExpected(expectedRevision)
+    const { record, revision } = await this.requireLoaded(userID, id)
+    if (revision !== expected) throw conflict(`Team ${id}`, revision)
+    if (record.state === "active") return teamView(record, revision)
+    await this.markArchived(userID, record.spec.name, id, false)
+    try {
+      return await this.mutate(userID, id, expected, (r) => (r.state === "active" ? undefined : { ...r, state: "active" }))
+    } catch (error) {
+      await this.markArchived(userID, record.spec.name, id, true)
+      throw error
+    }
+  }
+
+  // ---------- owner settings ----------
+
+  async settings(userID: string): Promise<TeamSettings> {
+    const stored = await this.state.get<SettingsDoc>(userID, TEAM_SETTINGS, OWNER)
+    if (!stored) return { teamIsolation: false, revision: 0 }
+    return this.settingsOf(stored.value, stored.version)
+  }
+
+  /** Changes the owner's team settings under CAS (expectedRevision 0 when never set). */
+  async setSettings(userID: string, input: unknown, expectedRevision: number): Promise<TeamSettings> {
+    const expected = checkExpected(expectedRevision)
+    if (!isObj(input) || Object.keys(input).some((k) => k !== "teamIsolation") || typeof input.teamIsolation !== "boolean")
+      throw new AgentError("invalid", "Send {teamIsolation: true|false}")
+    const current = await this.state.get<SettingsDoc>(userID, TEAM_SETTINGS, OWNER)
+    if (current) this.settingsOf(current.value, current.version)
+    const doc: SettingsDoc = { v: 1, teamIsolation: input.teamIsolation, updatedAt: this.now() }
+    const result = await this.state.put(userID, TEAM_SETTINGS, OWNER, doc, { ifVersion: expected })
+    if (!result.ok) throw conflict("Team settings", result.version)
+    return { teamIsolation: doc.teamIsolation, revision: result.version, updatedAt: doc.updatedAt }
+  }
+
+  /** Makes buffered writes durable (standalone debounce); a no-op for write-through stores. */
+  async flush(): Promise<void> {
+    await this.state.flush?.()
+  }
+
+  // ---------- internals ----------
+
+  private settingsOf(raw: unknown, version: number): TeamSettings {
+    if (isObj(raw) && isNum(raw.v) && raw.v > CONTRACT_VERSION) throw new AgentError("unsupported", "Team settings were written by a newer hub", { extra: { feature: "team-settings" } })
+    if (!isObj(raw) || typeof raw.teamIsolation !== "boolean") throw new AgentError("internal", "Stored team settings are malformed")
+    return { teamIsolation: raw.teamIsolation, revision: version, ...(isNum(raw.updatedAt) ? { updatedAt: raw.updatedAt } : {}) }
+  }
+
+  private active(record: TeamRecord): void {
+    if (record.state === "archived") throw new AgentError("invalid", `Team ${record.id} is archived`, { hint: "Restore it first" })
+  }
+
+  private async loaded(userID: string, id: string): Promise<{ record: TeamRecord; revision: number } | undefined> {
+    const stored = await this.state.get(userID, TEAMS, id)
+    if (!stored) return undefined
+    const read = readTeam(id, stored.value)
+    if (read.ok) return { record: read.record, revision: stored.version }
+    if (read.why === "newer") throw new AgentError("unsupported", `Team ${id} was written by a newer hub`, { hint: "Upgrade this hub", extra: { feature: "teams", recordVersion: read.v } })
+    throw new AgentError("internal", `Stored team ${id} is malformed`)
+  }
+
+  private async requireLoaded(userID: string, id: string): Promise<{ record: TeamRecord; revision: number }> {
+    const stored = await this.loaded(userID, id)
+    if (!stored) throw notFound(id)
+    return stored
+  }
+
+  private async readAll(userID: string): Promise<Team[]> {
+    const out: Team[] = []
+    for (const entry of await this.state.list(userID, TEAMS)) {
+      const read = readTeam(entry.key, entry.value)
+      if (read.ok) out.push(teamView(read.record, entry.version))
+    }
+    return out
+  }
+
+  private async readSoon(userID: string, id: string): Promise<Team | undefined> {
+    for (let i = 0; i < READS; i++) {
+      const team = await this.get(userID, id)
+      if (team) return team
+    }
+    return undefined
+  }
+
+  /** Version-checked change of a record; `change` returning undefined leaves it alone. */
+  private async mutate(userID: string, id: string, expected: number, change: (record: TeamRecord) => TeamRecord | undefined): Promise<Team> {
+    const { record, revision } = await this.requireLoaded(userID, id)
+    if (revision !== expected) throw conflict(`Team ${id}`, revision)
+    const next = change(record)
+    if (!next) return teamView(record, revision)
+    return this.write(userID, id, next, revision)
+  }
+
+  private async write(userID: string, id: string, next: TeamRecord, revision: number): Promise<Team> {
+    const written: TeamRecord = { ...next, v: 1, id, updatedAt: this.now() }
+    const result = await this.state.put(userID, TEAMS, id, written, { ifVersion: revision })
+    if (!result.ok) throw conflict(`Team ${id}`, result.version)
+    return teamView(written, result.version)
+  }
+
+  private async insert(userID: string, id: string, spec: TeamSpec): Promise<Team> {
+    const at = this.now()
+    await this.reserveName(userID, spec.name, id, at)
+    try {
+      const digest = specDigest(spec)
+      const record: TeamRecord = { v: 1, id, spec, state: "active", version: 1, history: [{ version: 1, digest, publishedAt: at }], createdAt: at, publishedAt: at, updatedAt: at }
+      const written = await this.state.put(userID, TEAMS, id, record, { ifVersion: 0 })
+      if (!written.ok) throw new Error(`team id ${id} already exists`)
+      await this.state.put<TeamVersion>(userID, teamVersionCollection(id), "1", { v: 1, teamID: id, version: 1, spec, digest, publishedAt: at }, { ifVersion: 0 })
+      return teamView(record, written.version)
+    } catch (error) {
+      await this.releaseName(userID, spec.name, id).catch(() => {})
+      throw error
+    }
+  }
+
+  /** Writes the slot of the record's current version when it is missing (crash between record and slot). */
+  private async ensureSlot(userID: string, record: TeamRecord): Promise<TeamVersion> {
+    const key = String(record.version)
+    const slot = await this.state.get<TeamVersion>(userID, teamVersionCollection(record.id), key)
+    if (slot) return slot.value
+    const entry = record.history.find((h) => h.version === record.version)
+    const version: TeamVersion = { v: 1, teamID: record.id, version: record.version, spec: record.spec, digest: entry?.digest ?? specDigest(record.spec), publishedAt: record.publishedAt }
+    await this.state.put(userID, teamVersionCollection(record.id), key, version, { ifVersion: 0 })
+    return version
+  }
+
+  private async index(userID: string): Promise<NameIndex | undefined> {
+    const raw = (await this.state.get<NameIndex>(userID, TEAM_INDEX, NAMES))?.value
+    return isObj(raw) && isObj(raw.names) ? raw : undefined
+  }
+
+  /** Reserves the name for `id` (name_taken; 429 when the user has teamsPerUser active teams). */
+  private async reserveName(userID: string, name: string, id: string, now: number): Promise<void> {
+    const ids = new Set((await this.state.list(userID, TEAMS)).map((e) => e.key))
+    const dead = (e: NameEntry) => !ids.has(e.id) && now - e.at > this.limits.reservationMs
+    await updateVersioned<NameIndex>(this.state, userID, TEAM_INDEX, NAMES, (current) => {
+      const names: Record<string, NameEntry> = {}
+      for (const [n, e] of Object.entries(current?.names ?? {})) if (!dead(e)) names[n] = e
+      if (names[name]) throw new AgentError("name_taken", `You already have a team named ${name}`, { hint: "Pick another name, or restore the archived team" })
+      const active = Object.values(names).filter((e) => !e.archived).length
+      if (active >= this.limits.teamsPerUser)
+        throw new AgentError("rate_limited", `A user has at most ${this.limits.teamsPerUser} active teams`, { hint: "Archive a team first", extra: { limit: this.limits.teamsPerUser } })
+      names[name] = { id, at: now }
+      return { v: 1, names }
+    })
+  }
+
+  private async releaseName(userID: string, name: string, id: string): Promise<void> {
+    await updateVersioned<NameIndex>(this.state, userID, TEAM_INDEX, NAMES, (current) => {
+      if (current?.names[name]?.id !== id) return undefined
+      const names = { ...current.names }
+      delete names[name]
+      return { v: 1, names }
+    })
+  }
+
+  /** Flags the name entry archived (frees a cap slot) or active again (429 at the cap). */
+  private async markArchived(userID: string, name: string, id: string, archived: boolean): Promise<void> {
+    await updateVersioned<NameIndex>(this.state, userID, TEAM_INDEX, NAMES, (current) => {
+      const names = { ...current?.names }
+      const entry = names[name]
+      if (entry && entry.id !== id) return undefined
+      if (entry && (entry.archived === true) === archived) return undefined
+      if (archived) names[name] = { id, at: entry?.at ?? this.now(), archived: true }
+      else {
+        const active = Object.values(names).filter((e) => !e.archived).length
+        if (active >= this.limits.teamsPerUser)
+          throw new AgentError("rate_limited", `A user has at most ${this.limits.teamsPerUser} active teams`, { hint: "Archive a team first", extra: { limit: this.limits.teamsPerUser } })
+        names[name] = { id, at: entry?.at ?? this.now() }
+      }
+      return { v: 1, names }
+    })
+  }
+
+  private async pruneKeys(userID: string): Promise<void> {
+    const now = this.now()
+    for (const entry of await this.state.list<IdempotencyDoc>(userID, TEAM_IDEMPOTENCY)) {
+      const at = isObj(entry.value) && isNum(entry.value.at) ? entry.value.at : 0
+      if (now - at >= IDEMPOTENCY_TTL_MS) await this.state.delete(userID, TEAM_IDEMPOTENCY, entry.key, { ifVersion: entry.version })
+    }
+  }
+}