@huynle/hub 0.7.4 → 0.8.0

package/src/central/workspaces/store.ts

@@ -0,0 +1,571 @@
+// Logical coordination workspaces and their host repository bindings (HWA-03; contract
+// docs/plans/2026-10-30-hub-workspaces-artifacts-contracts.md, packages/protocol/src/hub-workspace.ts).
+//
+// Storage: StateStore collections under the hub user (the tenant key), so the standalone file store and the
+// cluster's Postgres hub_state table behave alike and no schema migration is needed:
+// - `workspaces`: one HubWorkspace per key (its ID). `revision` is the StateStore version of the key: every write
+//   is version-checked (ifVersion), so a stale `expectedRevision` is a 409 conflict with `currentRevision`, and of
+//   two writers holding one revision exactly one wins. Keys are never deleted, so revisions are never reused.
+// - `workspace-bindings`: one aggregate per workspace (key: workspace ID) holding its HostRepoBindings. Identity is
+//   the explicit machineID + canonical absolute repo; IDs are minted, never derived from paths.
+// - `workspace-index` (key `active`): the reservations counting active workspaces toward the per-user cap. A
+//   create or restore reserves a slot by CAS before writing the record; archive gives it back. The index is
+//   derived state: when it is missing or full it is rebuilt from the records (active records count, reservations
+//   younger than RESERVATION_MS whose record is not active yet count, anything else is dropped), so a creator that
+//   crashed between reservation and write frees its slot after RESERVATION_MS.
+// - `workspace-idempotency`: Idempotency-Key → {workspaceID, digest, at}, created with ifVersion 0 (the claim),
+//   valid IDEMPOTENCY_TTL_MS and pruned when expired.
+//
+// Records from other builds: a v1 record missing optional fields reads with defaults (state active, updatedAt =
+// createdAt, revision = stored version). A record with a newer `v` is never guessed at: lists skip it and reads
+// and writes answer 422 unsupported, leaving it untouched. A malformed record is skipped by lists and a 500 on read.
+// Rollback: hubs before HWA-03 never read these collections (separate files / hub_state rows), so rolling back
+// leaves them dormant and rolling forward picks them up again.
+//
+// Durability: writes go through the StateStore; the standalone file store debounces (FILE_STATE_DEBOUNCE_MS) and
+// flushes on stop. Callers that acknowledge durability (HWA-11 checkpoints) call `flush()` before answering.
+// Membership, masters and supervision grant nothing: this store holds records, never authority. Native session
+// ancestry (parentID/rootID), UserRecord.agent and the console's inferred groups are not touched.
+import { createHash, randomBytes } from "node:crypto"
+import {
+  CONTRACT_VERSION,
+  DESCRIPTION_MAX,
+  type HostRepoBinding,
+  type HubWorkspace,
+  ID_PREFIXES,
+  IDEMPOTENCY_KEY,
+  IDEMPOTENCY_TTL_MS,
+  type IdKind,
+  isAbsolutePath,
+  isContractID,
+  isExpectedRevision,
+  isLabel,
+  isText,
+  LIST_LIMIT_DEFAULT,
+  LIST_LIMIT_MAX,
+  metadataProblem,
+  type Page,
+  RECORD_STATES,
+  type RecordState,
+  tagsProblem,
+  WORKSPACE_LIMITS,
+  workspaceInputProblem,
+} from "../../protocol"
+import { AgentError } from "../agent/errors"
+import { updateVersioned } from "../agent/versioned"
+import type { Clock, StateStore } from "../backend/types"
+
+export const WORKSPACES = "workspaces"
+export const WORKSPACE_BINDINGS = "workspace-bindings"
+export const WORKSPACE_INDEX = "workspace-index"
+export const WORKSPACE_IDEMPOTENCY = "workspace-idempotency"
+/** The workspace-index key. */
+const ACTIVE = "active"
+/** How long a reservation (index slot, idempotency key) without its record blocks, before it counts as crashed. */
+export const RESERVATION_MS = 60_000
+/** Machine IDs as the hub mints them (`mch_…`), bounded. */
+export const MACHINE_ID = /^[A-Za-z0-9_.:-]{1,128}$/
+/** Version-checked write attempts before a contended change gives up. */
+const ATTEMPTS = 16
+/** Reads of an idempotency key's workspace: its creator may be between the claim and the write. */
+const READS = 5
+
+export type WorkspaceStoreLimits = { readonly [K in "workspacesPerUser" | "bindingsPerWorkspace"]: number }
+
+/** Says whether the user owns the (unrevoked) machine; routes wire it to the hub's machine records. */
+export type MachineOwnership = (userID: string, machineID: string) => boolean | Promise<boolean>
+
+export interface WorkspaceStoreDeps {
+  readonly state: StateStore
+  /** Required: a binding names a machine of the binding user only. */
+  readonly ownsMachine: MachineOwnership
+  readonly now?: Clock
+  readonly newID?: (kind: IdKind) => string
+  /** Lower caps for tests; defaults are WORKSPACE_LIMITS. */
+  readonly limits?: Partial<WorkspaceStoreLimits>
+}
+
+export interface WorkspaceListQuery {
+  /** Only this state (default: both). */
+  readonly state?: string
+  readonly limit?: number
+  readonly cursor?: string
+}
+
+/** The fields PATCH /workspaces/:id may change; null clears an optional one. */
+export interface WorkspacePatch {
+  readonly title?: string
+  readonly description?: string | null
+  readonly tags?: readonly string[] | null
+  readonly metadata?: Readonly<Record<string, string>> | null
+}
+
+export interface MachineBinding {
+  readonly workspaceID: string
+  readonly binding: HostRepoBinding
+}
+
+interface IndexEntry {
+  readonly id: string
+  readonly at: number
+}
+interface IndexDoc {
+  readonly v: 1
+  readonly entries: readonly IndexEntry[]
+}
+interface IdempotencyDoc {
+  readonly v: 1
+  readonly workspaceID: string
+  readonly digest: string
+  readonly at: number
+}
+interface BindingsDoc {
+  readonly v: 1
+  readonly workspaceID: string
+  readonly bindings: readonly HostRepoBinding[]
+}
+
+type Readout = { readonly ok: true; readonly workspace: HubWorkspace } | { 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 PATCH_KEYS = new Set(["title", "description", "tags", "metadata"])
+
+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 },
+  })
+
+/** A stored workspace as this build reads it (defaults for older v1 records; newer versions are refused). */
+export function readWorkspace(key: string, raw: unknown, version: number): Readout {
+  if (!isObj(raw)) return { ok: false, why: "malformed" }
+  const v = raw.v ?? CONTRACT_VERSION
+  if (isNum(v) && v > CONTRACT_VERSION) return { ok: false, why: "newer", v }
+  if (v !== CONTRACT_VERSION) return { ok: false, why: "malformed" }
+  const { id, title, description, tags, metadata, masterMemberID } = raw
+  const state = raw.state ?? "active"
+  const createdAt = raw.createdAt ?? 0
+  const updatedAt = raw.updatedAt ?? createdAt
+  const valid =
+    id === key &&
+    typeof title === "string" &&
+    (description === undefined || typeof description === "string") &&
+    (tags === undefined || (Array.isArray(tags) && tags.every((t) => typeof t === "string"))) &&
+    (metadata === undefined || (isObj(metadata) && Object.values(metadata).every((m) => typeof m === "string"))) &&
+    (masterMemberID === undefined || typeof masterMemberID === "string") &&
+    RECORD_STATES.includes(state as RecordState) &&
+    isNum(createdAt) &&
+    isNum(updatedAt)
+  if (!valid) return { ok: false, why: "malformed" }
+  return {
+    ok: true,
+    workspace: {
+      v: 1,
+      id: id as string,
+      title: title as string,
+      ...(description !== undefined ? { description: description as string } : {}),
+      state: state as RecordState,
+      ...(tags !== undefined ? { tags: tags as string[] } : {}),
+      ...(metadata !== undefined ? { metadata: metadata as Record<string, string> } : {}),
+      ...(masterMemberID !== undefined ? { masterMemberID: masterMemberID as string } : {}),
+      revision: version,
+      createdAt: createdAt as number,
+      updatedAt: updatedAt as number,
+    },
+  }
+}
+
+/** The create body, validated by the contract and reduced to the fields a client may set. */
+function createBody(input: unknown): Pick<HubWorkspace, "title" | "description" | "tags" | "metadata"> {
+  const problem = workspaceInputProblem(input)
+  if (problem) throw new AgentError("invalid", problem)
+  const body = input as Record<string, unknown>
+  return {
+    title: body.title as string,
+    ...(body.description !== undefined ? { description: body.description as string } : {}),
+    ...(body.tags !== undefined ? { tags: [...(body.tags as string[])] } : {}),
+    ...(body.metadata !== undefined ? { metadata: { ...(body.metadata as Record<string, string>) } } : {}),
+  }
+}
+
+function patchBody(input: unknown): WorkspacePatch {
+  if (!isObj(input)) throw new AgentError("invalid", "body must be an object")
+  const keys = Object.keys(input)
+  const unknown = keys.find((k) => !PATCH_KEYS.has(k))
+  if (unknown !== undefined)
+    throw new AgentError("invalid", `${JSON.stringify(unknown.slice(0, 50))} cannot be changed here`, { hint: "Patch title, description, tags or metadata; archive and restore have their own routes" })
+  if (keys.length === 0) throw new AgentError("invalid", "Nothing to change")
+  if (input.title !== undefined && !isLabel(input.title)) throw new AgentError("invalid", "title must be 1–120 characters of text")
+  if (input.description !== undefined && input.description !== null && !isText(input.description, DESCRIPTION_MAX))
+    throw new AgentError("invalid", `description must be at most ${DESCRIPTION_MAX} characters`)
+  const problem = (input.tags === null ? undefined : tagsProblem(input.tags)) ?? (input.metadata === null ? undefined : metadataProblem(input.metadata))
+  if (problem) throw new AgentError("invalid", problem)
+  return input as WorkspacePatch
+}
+
+function checkExpected(expectedRevision: number | undefined): void {
+  if (expectedRevision !== undefined && !isExpectedRevision(expectedRevision)) throw new AgentError("invalid", "expectedRevision must be the revision you read")
+}
+
+/** Canonical JSON (sorted keys) for comparing request bodies. */
+function canonical(v: unknown): string {
+  if (Array.isArray(v)) return `[${v.map(canonical).join(",")}]`
+  if (isObj(v))
+    return `{${Object.keys(v)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`)
+      .join(",")}}`
+  return JSON.stringify(v)
+}
+
+/** sha256 of the canonical JSON of a request body (idempotency comparisons). */
+export const digestOf = (body: unknown) => createHash("sha256").update(canonical(body)).digest("hex")
+
+/** An absolute repo path without its trailing slash (the root stays "/"). */
+const canonicalRepo = (repo: string) => (repo.length > 1 ? repo.replace(/\/$/, "") : repo)
+
+const byCreation = (a: HubWorkspace, b: HubWorkspace) => a.createdAt - b.createdAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)
+
+function encodeCursor(w: HubWorkspace): string {
+  return Buffer.from(JSON.stringify([w.createdAt, w.id])).toString("base64url")
+}
+
+function decodeCursor(cursor: string): [number, string] {
+  try {
+    const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8")) as unknown
+    if (Array.isArray(parsed) && parsed.length === 2 && isNum(parsed[0]) && typeof parsed[1] === "string") return [parsed[0], parsed[1]]
+  } catch {
+    // answered below
+  }
+  throw new AgentError("invalid", "cursor is not one this list gave", { hint: "Start again without a cursor" })
+}
+
+function bindingsDoc(raw: unknown, workspaceID: string): BindingsDoc | undefined {
+  if (raw === undefined) return undefined
+  if (isObj(raw) && isNum(raw.v) && raw.v > CONTRACT_VERSION)
+    throw new AgentError("unsupported", "These bindings were written by a newer hub", { extra: { feature: "workspace-bindings" } })
+  if (!isObj(raw) || raw.v !== 1 || raw.workspaceID !== workspaceID || !Array.isArray(raw.bindings)) throw new AgentError("internal", "Stored workspace bindings are malformed")
+  return raw as unknown as BindingsDoc
+}
+
+export class WorkspaceStore {
+  readonly limits: WorkspaceStoreLimits
+  /** The StateStore under these records (route helpers keep their records next to them). */
+  readonly state: StateStore
+  private readonly now: Clock
+  private readonly newID: (kind: IdKind) => string
+
+  constructor(private readonly deps: WorkspaceStoreDeps) {
+    this.state = deps.state
+    this.now = deps.now ?? Date.now
+    this.newID = deps.newID ?? ((kind) => `${ID_PREFIXES[kind]}_${randomBytes(12).toString("hex")}`)
+    this.limits = {
+      workspacesPerUser: deps.limits?.workspacesPerUser ?? WORKSPACE_LIMITS.workspacesPerUser,
+      bindingsPerWorkspace: deps.limits?.bindingsPerWorkspace ?? WORKSPACE_LIMITS.bindingsPerWorkspace,
+    }
+  }
+
+  // ---------- workspaces ----------
+
+  /**
+   * Creates an active workspace (rate_limited at the per-user 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<{ workspace: HubWorkspace; created: boolean }> {
+    const body = createBody(input)
+    const key = options.idempotencyKey
+    if (key === undefined) return { workspace: await this.insert(userID, this.newID("workspace"), body), 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 = digestOf(body)
+    await this.pruneKeys(userID)
+    for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+      const held = await this.state.get<IdempotencyDoc>(userID, WORKSPACE_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 workspace`, { hint: "Use a new key for a different body, or resend the original body" })
+        const existing = await this.readSoon(userID, live.workspaceID)
+        if (existing) return { workspace: existing, created: false }
+        if (this.now() - live.at < RESERVATION_MS)
+          throw new AgentError("rate_limited", `The workspace for Idempotency-Key ${key} is still being created`, { extra: { retryAfter: 1 } })
+        // Its creator crashed before writing the workspace: take the key over.
+      }
+      const id = this.newID("workspace")
+      const doc: IdempotencyDoc = { v: 1, workspaceID: id, digest, at: this.now() }
+      const claimed = await this.state.put(userID, WORKSPACE_IDEMPOTENCY, key, doc, { ifVersion: held?.version ?? 0 })
+      if (!claimed.ok) continue
+      try {
+        return { workspace: await this.insert(userID, id, body), created: true }
+      } catch (error) {
+        await this.state.delete(userID, WORKSPACE_IDEMPOTENCY, key, { ifVersion: claimed.version })
+        throw error
+      }
+    }
+    throw new Error(`workspace idempotency key ${key} kept conflicting`)
+  }
+
+  /** The user's workspace, or undefined (also for another user's); throws for records this build cannot read. */
+  async get(userID: string, id: string): Promise<HubWorkspace | undefined> {
+    const stored = await this.state.get(userID, WORKSPACES, id)
+    if (!stored) return undefined
+    return this.usable(id, readWorkspace(id, stored.value, stored.version))
+  }
+
+  /** The user's workspace, or not_found. */
+  async require(userID: string, id: string): Promise<HubWorkspace> {
+    const workspace = await this.get(userID, id)
+    if (!workspace) throw new AgentError("not_found", `No workspace ${id}`)
+    return workspace
+  }
+
+  /** The user's readable workspaces by creation, paged (records this build cannot read are skipped). */
+  async list(userID: string, query: WorkspaceListQuery = {}): Promise<Page<HubWorkspace>> {
+    const limit = query.limit ?? LIST_LIMIT_DEFAULT
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > LIST_LIMIT_MAX) throw new AgentError("invalid", `limit must be 1–${LIST_LIMIT_MAX}`)
+    if (query.state !== undefined && !RECORD_STATES.includes(query.state as RecordState)) throw new AgentError("invalid", `state must be one of ${RECORD_STATES.join(", ")}`)
+    const after = query.cursor === undefined ? undefined : decodeCursor(query.cursor)
+    const all = (await this.readAll(userID))
+      .filter((w) => query.state === undefined || w.state === query.state)
+      .filter((w) => !after || w.createdAt > after[0] || (w.createdAt === after[0] && w.id > after[1]))
+      .sort(byCreation)
+    const items = all.slice(0, limit)
+    return all.length > limit ? { items, cursor: encodeCursor(items.at(-1)!) } : { items }
+  }
+
+  /** Changes title, description, tags or metadata of an active workspace under its expected revision. */
+  async update(userID: string, id: string, patch: unknown, expectedRevision: number): Promise<HubWorkspace> {
+    if (!isExpectedRevision(expectedRevision)) throw new AgentError("invalid", "expectedRevision must be the revision you read")
+    const change = patchBody(patch)
+    return this.mutate(userID, id, expectedRevision, (current) => {
+      if (current.state === "archived") throw new AgentError("invalid", `Workspace ${id} is archived`, { hint: "Restore it first" })
+      const next: Record<string, unknown> = { ...current }
+      for (const [field, value] of Object.entries(change)) {
+        if (value === null) delete next[field]
+        else next[field] = value
+      }
+      return next as unknown as HubWorkspace
+    })
+  }
+
+  /** Archives the workspace (reversible; its bindings and records stay). Archiving an archived one is a no-op. */
+  async archive(userID: string, id: string, expectedRevision?: number): Promise<HubWorkspace> {
+    checkExpected(expectedRevision)
+    const archived = await this.mutate(userID, id, expectedRevision, (current) => (current.state === "archived" ? undefined : { ...current, state: "archived" }))
+    await this.unreserve(userID, id)
+    return archived
+  }
+
+  /** Makes an archived workspace active again (rate_limited at the cap). Restoring an active one is a no-op. */
+  async restore(userID: string, id: string, expectedRevision?: number): Promise<HubWorkspace> {
+    checkExpected(expectedRevision)
+    const current = await this.require(userID, id)
+    if (expectedRevision !== undefined && current.revision !== expectedRevision) throw conflict(`Workspace ${id}`, current.revision)
+    if (current.state === "active") return current
+    await this.reserve(userID, id)
+    try {
+      return await this.mutate(userID, id, expectedRevision, (w) => (w.state === "active" ? undefined : { ...w, state: "active" }))
+    } catch (error) {
+      await this.unreserve(userID, id)
+      throw error
+    }
+  }
+
+  /** Records (or clears) the current master membership; HWA-04/12 own the membership semantics. */
+  async setMaster(userID: string, id: string, masterMemberID: string | undefined, expectedRevision?: number): Promise<HubWorkspace> {
+    checkExpected(expectedRevision)
+    if (masterMemberID !== undefined && !isContractID("member", masterMemberID)) throw new AgentError("invalid", "masterMemberID must be a workspace member ID")
+    return this.mutate(userID, id, expectedRevision, (current) => {
+      if (current.masterMemberID === masterMemberID) return undefined
+      const { masterMemberID: _old, ...rest } = current
+      return masterMemberID === undefined ? rest : { ...rest, masterMemberID }
+    })
+  }
+
+  /** Makes buffered writes durable (standalone debounce); a no-op for write-through stores. */
+  async flush(): Promise<void> {
+    await this.state.flush?.()
+  }
+
+  // ---------- host repository bindings ----------
+
+  /** The workspace's bindings (not_found for a missing or another user's workspace). */
+  async bindings(userID: string, workspaceID: string): Promise<HostRepoBinding[]> {
+    await this.require(userID, workspaceID)
+    const doc = bindingsDoc((await this.state.get(userID, WORKSPACE_BINDINGS, workspaceID))?.value, workspaceID)
+    return [...(doc?.bindings ?? [])]
+  }
+
+  /**
+   * Binds the workspace to a repository on one of the user's machines. The same machine + canonical repo again
+   * returns the existing binding (created false); with another label it is a conflict.
+   */
+  async bind(userID: string, workspaceID: string, input: unknown): Promise<{ binding: HostRepoBinding; created: boolean }> {
+    if (!isObj(input)) throw new AgentError("invalid", "body must be an object")
+    const { machineID, repo: rawRepo, label } = input
+    if (typeof machineID !== "string" || !MACHINE_ID.test(machineID)) throw new AgentError("invalid", "machineID must be a machine ID")
+    if (!isAbsolutePath(rawRepo)) throw new AgentError("invalid", "repo must be an absolute path without . or .. segments")
+    if (label !== undefined && !isLabel(label)) throw new AgentError("invalid", "label must be 1–120 characters of text")
+    const repo = canonicalRepo(rawRepo)
+    const workspace = await this.require(userID, workspaceID)
+    if (workspace.state === "archived") throw new AgentError("invalid", `Workspace ${workspaceID} is archived`, { hint: "Restore it first" })
+    if (!(await this.deps.ownsMachine(userID, machineID))) throw new AgentError("not_found", `No machine ${machineID}`)
+    let result: { binding: HostRepoBinding; created: boolean } | undefined
+    await updateVersioned<BindingsDoc>(this.state, userID, WORKSPACE_BINDINGS, workspaceID, (raw) => {
+      const list = bindingsDoc(raw, workspaceID)?.bindings ?? []
+      const same = list.find((b) => b.machineID === machineID && b.repo === repo)
+      if (same) {
+        if (same.label !== label) throw new AgentError("conflict", `${repo} on ${machineID} is already bound with another label`, { extra: { currentRevision: same.revision } })
+        result = { binding: same, created: false }
+        return undefined
+      }
+      if (list.length >= this.limits.bindingsPerWorkspace)
+        throw new AgentError("rate_limited", `A workspace has at most ${this.limits.bindingsPerWorkspace} repository bindings`, { hint: "Remove a binding first" })
+      const binding: HostRepoBinding = { v: 1, id: this.newID("binding"), workspaceID, machineID, repo, ...(label !== undefined ? { label } : {}), revision: 1 }
+      result = { binding, created: true }
+      return { v: 1, workspaceID, bindings: [...list, binding] }
+    })
+    return result!
+  }
+
+  /** Removes a binding (optionally only at the expected revision); not_found when it does not exist. */
+  async unbind(userID: string, workspaceID: string, bindingID: string, expectedRevision?: number): Promise<HostRepoBinding> {
+    checkExpected(expectedRevision)
+    await this.require(userID, workspaceID)
+    let removed: HostRepoBinding | undefined
+    await updateVersioned<BindingsDoc>(this.state, userID, WORKSPACE_BINDINGS, workspaceID, (raw) => {
+      const list = bindingsDoc(raw, workspaceID)?.bindings ?? []
+      const binding = list.find((b) => b.id === bindingID)
+      if (!binding) throw new AgentError("not_found", `No binding ${bindingID} in workspace ${workspaceID}`)
+      if (expectedRevision !== undefined && binding.revision !== expectedRevision) throw conflict(`Binding ${bindingID}`, binding.revision)
+      removed = binding
+      return { v: 1, workspaceID, bindings: list.filter((b) => b.id !== bindingID) }
+    })
+    return removed!
+  }
+
+  /** Every binding of the user on one machine, with its workspace (for placement and offline reporting). */
+  async bindingsForMachine(userID: string, machineID: string): Promise<MachineBinding[]> {
+    const docs = await this.state.list(userID, WORKSPACE_BINDINGS)
+    const out: MachineBinding[] = []
+    for (const entry of docs) {
+      let doc: BindingsDoc | undefined
+      try {
+        doc = bindingsDoc(entry.value, entry.key)
+      } catch {
+        continue
+      }
+      for (const binding of doc?.bindings ?? []) if (binding.machineID === machineID) out.push({ workspaceID: entry.key, binding })
+    }
+    return out
+  }
+
+  // ---------- internals ----------
+
+  private usable(id: string, read: Readout): HubWorkspace {
+    if (read.ok) return read.workspace
+    if (read.why === "newer")
+      throw new AgentError("unsupported", `Workspace ${id} was written by a newer hub`, { hint: "Upgrade this hub", extra: { feature: "workspaces", recordVersion: read.v } })
+    throw new AgentError("internal", `Stored workspace ${id} is malformed`)
+  }
+
+  private async readAll(userID: string): Promise<HubWorkspace[]> {
+    const out: HubWorkspace[] = []
+    for (const entry of await this.state.list(userID, WORKSPACES)) {
+      const read = readWorkspace(entry.key, entry.value, entry.version)
+      if (read.ok) out.push(read.workspace)
+    }
+    return out
+  }
+
+  /** A workspace a concurrent creator may be about to write: re-read a few times. */
+  private async readSoon(userID: string, id: string): Promise<HubWorkspace | undefined> {
+    for (let i = 0; i < READS; i++) {
+      const workspace = await this.get(userID, id)
+      if (workspace) return workspace
+    }
+    return undefined
+  }
+
+  /** Version-checked change of a workspace; `change` returning undefined leaves it alone. */
+  private async mutate(userID: string, id: string, expectedRevision: number | undefined, change: (current: HubWorkspace) => HubWorkspace | undefined): Promise<HubWorkspace> {
+    for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+      const current = await this.require(userID, id)
+      if (expectedRevision !== undefined && current.revision !== expectedRevision) throw conflict(`Workspace ${id}`, current.revision)
+      const next = change(current)
+      if (!next) return current
+      const written: HubWorkspace = { ...next, v: 1, id, createdAt: current.createdAt, revision: current.revision + 1, updatedAt: this.now() }
+      const result = await this.state.put(userID, WORKSPACES, id, written, { ifVersion: current.revision })
+      if (result.ok) return { ...written, revision: result.version }
+      if (expectedRevision !== undefined) throw conflict(`Workspace ${id}`, result.version)
+    }
+    throw new Error(`workspace ${id} kept conflicting`)
+  }
+
+  private async insert(userID: string, id: string, body: Pick<HubWorkspace, "title" | "description" | "tags" | "metadata">): Promise<HubWorkspace> {
+    await this.reserve(userID, id)
+    const at = this.now()
+    const workspace: HubWorkspace = { v: 1, id, ...body, state: "active", revision: 1, createdAt: at, updatedAt: at }
+    const written = await this.state.put(userID, WORKSPACES, id, workspace, { ifVersion: 0 })
+    if (!written.ok) {
+      await this.unreserve(userID, id)
+      throw new Error(`workspace id ${id} already exists`)
+    }
+    return workspace
+  }
+
+  /** Takes an active slot for `id` (rate_limited when the user is at the cap even after rebuilding the index). */
+  private async reserve(userID: string, id: string): Promise<void> {
+    const missing = (await this.state.get(userID, WORKSPACE_INDEX, ACTIVE)) === undefined
+    if (await this.tryReserve(userID, id, missing)) return
+    if (!missing && (await this.tryReserve(userID, id, true))) return
+    throw new AgentError("rate_limited", `A user has at most ${this.limits.workspacesPerUser} active workspaces`, { hint: "Archive a workspace first" })
+  }
+
+  private async tryReserve(userID: string, id: string, rebuild: boolean): Promise<boolean> {
+    const records = rebuild ? await this.state.list(userID, WORKSPACES) : undefined
+    let reserved = false
+    await updateVersioned<IndexDoc>(this.state, userID, WORKSPACE_INDEX, ACTIVE, (raw) => {
+      const stored = isObj(raw) && Array.isArray(raw.entries) ? (raw.entries as IndexEntry[]) : []
+      const entries = records ? this.rebuilt(stored, records) : stored
+      reserved = entries.some((e) => e.id === id)
+      if (!reserved && entries.length < this.limits.workspacesPerUser) {
+        reserved = true
+        return { v: 1, entries: [...entries, { id, at: this.now() }] }
+      }
+      return records ? { v: 1, entries } : undefined
+    })
+    return reserved
+  }
+
+  /** The index from the records: active (or unreadable-newer) ones count, plus fresh reservations. */
+  private rebuilt(stored: readonly IndexEntry[], records: readonly { key: string; value: unknown; version: number }[]): IndexEntry[] {
+    const live = new Map<string, number>()
+    for (const record of records) {
+      const read = readWorkspace(record.key, record.value, record.version)
+      if (read.ok ? read.workspace.state === "active" : read.why === "newer") live.set(record.key, read.ok ? read.workspace.createdAt : this.now())
+    }
+    const now = this.now()
+    const entries = stored.filter((e) => isObj(e) && typeof e.id === "string" && isNum(e.at) && (live.has(e.id) || now - e.at < RESERVATION_MS))
+    const have = new Set(entries.map((e) => e.id))
+    for (const [id, at] of live) if (!have.has(id)) entries.push({ id, at })
+    return entries
+  }
+
+  private async unreserve(userID: string, id: string): Promise<void> {
+    await updateVersioned<IndexDoc>(this.state, userID, WORKSPACE_INDEX, ACTIVE, (raw) => {
+      if (!isObj(raw) || !Array.isArray(raw.entries)) return undefined
+      const entries = (raw.entries as IndexEntry[]).filter((e) => e.id !== id)
+      return entries.length === raw.entries.length ? undefined : { v: 1, entries }
+    })
+  }
+
+  /** Drops expired idempotency keys. */
+  private async pruneKeys(userID: string): Promise<void> {
+    const now = this.now()
+    for (const entry of await this.state.list<IdempotencyDoc>(userID, WORKSPACE_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, WORKSPACE_IDEMPOTENCY, entry.key, { ifVersion: entry.version })
+    }
+  }
+}