@huynle/hub 0.7.4 → 0.8.0

package/src/central/workspaces/members.ts

@@ -0,0 +1,632 @@
+// Workspace membership and versioned assignments (HWA-04; contract docs/plans/2026-10-30-hub-workspaces-artifacts-
+// contracts.md, packages/protocol/src/hub-workspace.ts WorkspaceMember / WorkspaceAssignment).
+//
+// Storage: StateStore collections under the hub user (the tenant key), like the workspace store (store.ts):
+// - `workspace-members`: one aggregate per workspace (key: workspace ID) holding its WorkspaceMembers, current and
+//   departed. One aggregate makes the per-workspace cap, "one current membership per session" and an internal
+//   master replacement (old member `replaced`, new one generation + 1) a single version-checked write. Each member
+//   carries its own `revision` (1 on join, +1 per change); a stale `expectedRevision` is a 409 conflict with
+//   `currentRevision`.
+// - `workspace-assignments`: one aggregate per workspace holding its assignments and the assignment
+//   Idempotency-Keys (so a key's claim and its assignment are written together: no crash window). Per-assignment
+//   `revision` as for members, so two reassignments under one revision: exactly one wins.
+//
+// Session references: members name sessions by ID and never own them. Joining needs a session the user's
+// directory knows (unknown or another user's: not_found; deleted: invalid). Offline and archived sessions may join.
+// Reads report every reference truthfully through the presence lookup (online / offline / archived / deleted /
+// unknown) and an assignment's member as current / left / missing; nothing is hidden or silently repaired.
+//
+// Lifecycle and retention:
+// - Departure is explicit: leave (`removed`), sessionEnded (`ended`, for the hub's session-deleted path), an internal
+//   replacement (`replaced`) or archiving the workspace (`archived`). Departed records are kept (they count toward
+//   membersPerWorkspace, as the contract says); a join at the cap prunes the oldest departed member that no open
+//   assignment references, and answers 429 rate_limited when there is none.
+// - Archiving the workspace departs every current member (`archived`); restore re-joins nobody (a re-join is a new
+//   generation). Assignments keep their status. Mutations of an archived workspace's members/assignments are invalid.
+// - Assignment completion is explicit: only setStatus moves an assignment to `done` or `cancelled`; nothing infers it
+//   from idleness, presence or departure. Closed assignments are final and retained up to closedAssignmentsRetained
+//   per workspace (oldest closed dropped); open ones are capped at openAssignmentsPerWorkspace (429).
+//
+// Authority: membership, roles and assignments grant nothing. This store holds records only; grants, native
+// parentID/rootID, the directory and UserRecord.agent are never touched. The master role is not given by joining:
+// HWA-12's explicit replacement passes `allowMaster` and maintains HubWorkspace.masterMemberID.
+// Assignment text (title, criteria) never belongs in events; events (HWA-06) carry IDs, revisions and counts only.
+//
+// Other builds: an aggregate with a newer `v` answers 422 unsupported and is left untouched; a malformed one is a
+// 500. Rollback: older hubs never read these collections, so they stay dormant.
+import { randomBytes } from "node:crypto"
+import {
+  CONTRACT_VERSION,
+  ID_PREFIXES,
+  IDEMPOTENCY_KEY,
+  IDEMPOTENCY_TTL_MS,
+  type IdKind,
+  isContractID,
+  isExpectedRevision,
+  isLabel,
+  LIST_LIMIT_DEFAULT,
+  LIST_LIMIT_MAX,
+  type Page,
+  type WorkspaceAssignment,
+  type WorkspaceMember,
+  WORKSPACE_LIMITS,
+  WORKSPACE_ROLES,
+  type WorkspaceRole,
+  type HubWorkspace,
+} from "../../protocol"
+import type { AgentSession } from "../agent-data"
+import type { Directory } from "../agent/directory"
+import { AgentError } from "../agent/errors"
+import { updateVersioned } from "../agent/versioned"
+import type { Clock, StateStore } from "../backend/types"
+import { digestOf, type WorkspaceStore } from "./store"
+
+export const WORKSPACE_MEMBERS = "workspace-members"
+export const WORKSPACE_ASSIGNMENTS = "workspace-assignments"
+
+export type AssignmentStatus = WorkspaceAssignment["status"]
+export const ASSIGNMENT_STATUSES: readonly AssignmentStatus[] = ["open", "in_progress", "blocked", "done", "cancelled"]
+/** Statuses an assignment may be created with (closing is an explicit later step). */
+const OPENING: readonly AssignmentStatus[] = ["open", "in_progress", "blocked"]
+const CLOSED: ReadonlySet<AssignmentStatus> = new Set(["done", "cancelled"])
+/** Session IDs as the directory resolves them (`ses_…`), bounded. */
+export const SESSION_ID = /^ses_[A-Za-z0-9]{1,124}$/
+
+export interface MembershipLimits {
+  /** Members per workspace, current and departed together (the contract's membersPerWorkspace). */
+  readonly membersPerWorkspace: number
+  /** Assignments not yet done or cancelled, per workspace. */
+  readonly openAssignmentsPerWorkspace: number
+  /** Closed assignments kept per workspace (oldest closed dropped beyond it). */
+  readonly closedAssignmentsRetained: number
+  /** Outcome criteria per assignment, and characters per criterion. */
+  readonly criteriaPerAssignment: number
+  readonly criterionMax: number
+  /** Characters of an assignment's external reference. */
+  readonly refMax: number
+}
+
+export const MEMBERSHIP_LIMITS: MembershipLimits = {
+  membersPerWorkspace: WORKSPACE_LIMITS.membersPerWorkspace,
+  openAssignmentsPerWorkspace: 200,
+  closedAssignmentsRetained: 100,
+  criteriaPerAssignment: 8,
+  criterionMax: 200,
+  refMax: 200,
+}
+
+/** Idempotency-Keys kept per workspace (beyond the TTL bound, oldest dropped). */
+const KEYS_MAX = 500
+
+/** What the hub knows about a referenced session now. `unknown`: not (or no longer) in the user's directory. */
+export type SessionPresence = "online" | "offline" | "archived" | "deleted" | "unknown"
+export type SessionPresenceLookup = (userID: string, sessionID: string) => SessionPresence | Promise<SessionPresence>
+
+/**
+ * A WorkspaceAssignment as stored: the contract fields plus outcome criteria (what "done" means, bounded text;
+ * never in events), creation time and when it was closed.
+ */
+export interface StoredAssignment extends WorkspaceAssignment {
+  readonly criteria?: readonly string[]
+  readonly createdAt: number
+  readonly closedAt?: number
+}
+
+export interface MemberView {
+  readonly member: WorkspaceMember
+  /** Not departed. */
+  readonly current: boolean
+  readonly presence: SessionPresence
+}
+
+export interface AssignmentView {
+  readonly assignment: StoredAssignment
+  /** The assignee's membership: current, departed (left) or no longer retained (missing). */
+  readonly member: "current" | "left" | "missing"
+  /** The assignee session's presence (unknown when the member is missing). */
+  readonly presence: SessionPresence
+}
+
+export interface AssignmentListQuery {
+  readonly memberID?: string
+  readonly status?: string
+  readonly limit?: number
+  readonly cursor?: string
+}
+
+export interface JoinOptions {
+  /** Internal (HWA-12): allows role master; routes for members never pass it. */
+  readonly allowMaster?: boolean
+  /** Internal (HWA-12): departs this current member as `replaced`; the new member gets its generation + 1. */
+  readonly replaces?: string
+  /** Internal (HWA-12): the new member's generation is at least this (a master slot re-staffed after its master left). */
+  readonly minGeneration?: number
+}
+
+export interface MembershipStoreDeps {
+  readonly state: StateStore
+  readonly workspaces: WorkspaceStore
+  readonly presence: SessionPresenceLookup
+  readonly now?: Clock
+  readonly newID?: (kind: IdKind) => string
+  readonly limits?: Partial<MembershipLimits>
+}
+
+interface MembersDoc {
+  readonly v: 1
+  readonly workspaceID: string
+  readonly members: readonly WorkspaceMember[]
+}
+interface KeyEntry {
+  readonly key: string
+  readonly assignmentID: string
+  readonly digest: string
+  readonly at: number
+}
+interface AssignmentsDoc {
+  readonly v: 1
+  readonly workspaceID: string
+  readonly assignments: readonly StoredAssignment[]
+  readonly keys: readonly KeyEntry[]
+}
+
+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 archivedError = (workspaceID: string) => new AgentError("invalid", `Workspace ${workspaceID} is archived`, { hint: "Restore it first" })
+
+function checkExpected(expectedRevision: number | undefined): void {
+  if (expectedRevision !== undefined && !isExpectedRevision(expectedRevision)) throw new AgentError("invalid", "expectedRevision must be the revision you read")
+}
+
+/** A stored per-workspace aggregate, or undefined when missing; newer versions are unsupported, bad ones internal. */
+function aggregate<T>(raw: unknown, workspaceID: string, field: string, feature: string): T | undefined {
+  if (raw === undefined) return undefined
+  if (isObj(raw) && isNum(raw.v) && raw.v > CONTRACT_VERSION)
+    throw new AgentError("unsupported", `Workspace ${workspaceID} ${feature} were written by a newer hub`, { hint: "Upgrade this hub", extra: { feature } })
+  if (!isObj(raw) || raw.v !== CONTRACT_VERSION || raw.workspaceID !== workspaceID || !Array.isArray(raw[field]))
+    throw new AgentError("internal", `Stored workspace ${feature} are malformed`)
+  return raw as T
+}
+
+const membersDoc = (raw: unknown, workspaceID: string) => aggregate<MembersDoc>(raw, workspaceID, "members", "workspace-members")
+function assignmentsDoc(raw: unknown, workspaceID: string): AssignmentsDoc | undefined {
+  const doc = aggregate<AssignmentsDoc>(raw, workspaceID, "assignments", "workspace-assignments")
+  return doc && { ...doc, keys: Array.isArray(doc.keys) ? doc.keys : [] }
+}
+
+function encodeCursor(a: StoredAssignment): string {
+  return Buffer.from(JSON.stringify([a.createdAt, a.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" })
+}
+
+const byCreation = (a: StoredAssignment, b: StoredAssignment) => a.createdAt - b.createdAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)
+
+/**
+ * Presence from the agent directory: exact session IDs of this user only (a prefix or another user's session is
+ * unknown). `sessions` gives the user's stored session records (for deletedAt, which directory entries omit).
+ */
+export function directoryPresence(directory: Pick<Directory, "resolve">, sessions: (userID: string) => readonly AgentSession[]): SessionPresenceLookup {
+  return (userID, sessionID) => {
+    if (!SESSION_ID.test(sessionID)) return "unknown"
+    if (sessions(userID).some((s) => s.sessionID === sessionID && s.deletedAt !== undefined)) return "deleted"
+    let found
+    try {
+      found = directory.resolve(userID, sessionID).sessions.find((s) => s.sessionID === sessionID)
+    } catch (error) {
+      if (error instanceof AgentError) return "unknown"
+      throw error
+    }
+    if (!found) return "unknown"
+    if (found.archived) return "archived"
+    return found.online ? "online" : "offline"
+  }
+}
+
+export class MembershipStore {
+  readonly limits: MembershipLimits
+  private readonly state: StateStore
+  private readonly workspaces: WorkspaceStore
+  private readonly now: Clock
+  private readonly newID: (kind: IdKind) => string
+
+  constructor(private readonly deps: MembershipStoreDeps) {
+    this.state = deps.state
+    this.workspaces = deps.workspaces
+    this.now = deps.now ?? Date.now
+    this.newID = deps.newID ?? ((kind) => `${ID_PREFIXES[kind]}_${randomBytes(12).toString("hex")}`)
+    this.limits = { ...MEMBERSHIP_LIMITS, ...deps.limits }
+  }
+
+  // ---------- membership ----------
+
+  /**
+   * Adds the session as a member. The same session already a current member with the same role returns that
+   * membership (created false); with another role it is a conflict. Not the master role (see JoinOptions).
+   */
+  async join(userID: string, workspaceID: string, input: unknown, options: JoinOptions = {}): Promise<{ member: WorkspaceMember; created: boolean }> {
+    if (!isObj(input)) throw new AgentError("invalid", "body must be an object")
+    const { sessionID, role } = input
+    if (typeof sessionID !== "string" || !SESSION_ID.test(sessionID)) throw new AgentError("invalid", "sessionID must be a session ID (ses_…)")
+    if (!WORKSPACE_ROLES.includes(role as WorkspaceRole)) throw new AgentError("invalid", `role must be one of ${WORKSPACE_ROLES.join(", ")}`)
+    if (role === "master" && !options.allowMaster)
+      throw new AgentError("invalid", "Joining does not make a master", { hint: "The master is set by explicit replacement (POST /workspaces/:id/master)" })
+    if (options.replaces !== undefined && !isContractID("member", options.replaces)) throw new AgentError("invalid", "replaces must be a member ID")
+    await this.active(userID, workspaceID)
+    const presence = await this.deps.presence(userID, sessionID)
+    if (presence === "unknown") throw new AgentError("not_found", `No session ${sessionID}`)
+    if (presence === "deleted") throw new AgentError("invalid", `Session ${sessionID} was deleted`)
+    const busy = await this.openAssignees(userID, workspaceID)
+    let result: { member: WorkspaceMember; created: boolean } | undefined
+    await updateVersioned<MembersDoc>(this.state, userID, WORKSPACE_MEMBERS, workspaceID, (raw) => {
+      let list = [...(membersDoc(raw, workspaceID)?.members ?? [])]
+      const same = list.find((m) => m.sessionID === sessionID && m.leftAt === undefined)
+      if (same) {
+        if (same.role !== role)
+          throw new AgentError("conflict", `Session ${sessionID} is already a ${same.role} here`, { hint: "Change its role instead", extra: { currentRevision: same.revision } })
+        result = { member: same, created: false }
+        return undefined
+      }
+      const at = this.now()
+      let generation = 1 + Math.max(0, ...list.filter((m) => m.sessionID === sessionID).map((m) => m.generation))
+      if (options.replaces !== undefined) {
+        const old = list.find((m) => m.id === options.replaces)
+        if (!old) throw new AgentError("not_found", `No member ${options.replaces} in workspace ${workspaceID}`)
+        if (old.leftAt !== undefined) throw new AgentError("invalid", `Member ${old.id} already left`)
+        generation = old.generation + 1
+        list = list.map((m) => (m.id === old.id ? { ...m, leftAt: at, leftReason: "replaced", revision: m.revision + 1 } : m))
+      }
+      if (options.minGeneration !== undefined) generation = Math.max(generation, options.minGeneration)
+      if (list.length >= this.limits.membersPerWorkspace) {
+        const prunable = list.filter((m) => m.leftAt !== undefined && !busy.has(m.id)).sort((a, b) => a.leftAt! - b.leftAt!)[0]
+        if (!prunable)
+          throw new AgentError("rate_limited", `A workspace has at most ${this.limits.membersPerWorkspace} members, current and departed`, {
+            hint: "Remove members, or close the open assignments of departed ones",
+          })
+        list = list.filter((m) => m.id !== prunable.id)
+      }
+      const member: WorkspaceMember = { v: 1, id: this.newID("member"), workspaceID, sessionID, role: role as WorkspaceRole, generation, joinedAt: at, revision: 1 }
+      result = { member, created: true }
+      return { v: 1, workspaceID, members: [...list, member] }
+    })
+    return result!
+  }
+
+  /** One member (current or departed); not_found otherwise. */
+  async member(userID: string, workspaceID: string, memberID: string): Promise<WorkspaceMember> {
+    const member = (await this.readMembers(userID, workspaceID)).find((m) => m.id === memberID)
+    if (!member) throw new AgentError("not_found", `No member ${memberID} in workspace ${workspaceID}`)
+    return member
+  }
+
+  /** The workspace's members by join order (current only unless includeLeft), with their sessions' presence. */
+  async members(userID: string, workspaceID: string, query: { readonly includeLeft?: boolean } = {}): Promise<MemberView[]> {
+    const members = (await this.readMembers(userID, workspaceID)).filter((m) => query.includeLeft || m.leftAt === undefined)
+    const presence = await this.presenceOf(userID, members.map((m) => m.sessionID))
+    return members.map((member) => ({ member, current: member.leftAt === undefined, presence: presence.get(member.sessionID)! }))
+  }
+
+  /** Changes a current member's role between worker and observer (master: HWA-12's replacement). */
+  async setRole(userID: string, workspaceID: string, memberID: string, role: unknown, expectedRevision?: number): Promise<WorkspaceMember> {
+    checkExpected(expectedRevision)
+    if (role !== "worker" && role !== "observer") throw new AgentError("invalid", "role must be worker or observer", { hint: "The master is set by explicit replacement" })
+    await this.active(userID, workspaceID)
+    return this.mutateMember(userID, workspaceID, memberID, expectedRevision, (m) => {
+      if (m.leftAt !== undefined) throw new AgentError("invalid", `Member ${memberID} left the workspace`, { hint: "Join the session again" })
+      if (m.role === "master") throw new AgentError("invalid", `Member ${memberID} is the master`, { hint: "Replace the master instead" })
+      return m.role === role ? undefined : { ...m, role }
+    })
+  }
+
+  /** Departs a member (record kept). Leaving again is a no-op. Allowed on an archived workspace. */
+  async leave(
+    userID: string,
+    workspaceID: string,
+    memberID: string,
+    options: { readonly expectedRevision?: number; readonly reason?: "removed" | "ended" } = {},
+  ): Promise<WorkspaceMember> {
+    checkExpected(options.expectedRevision)
+    const reason = options.reason ?? "removed"
+    const workspace = await this.workspaces.require(userID, workspaceID)
+    const left = await this.mutateMember(userID, workspaceID, memberID, options.expectedRevision, (m) =>
+      m.leftAt !== undefined ? undefined : { ...m, leftAt: this.now(), leftReason: reason },
+    )
+    if (workspace.masterMemberID === memberID) await this.workspaces.setMaster(userID, workspaceID, undefined)
+    return left
+  }
+
+  /** The session's current memberships across the user's workspaces. */
+  async membershipsOf(userID: string, sessionID: string): Promise<{ workspaceID: string; member: WorkspaceMember }[]> {
+    const out: { workspaceID: string; member: WorkspaceMember }[] = []
+    for (const entry of await this.state.list(userID, WORKSPACE_MEMBERS)) {
+      let doc: MembersDoc | undefined
+      try {
+        doc = membersDoc(entry.value, entry.key)
+      } catch {
+        continue
+      }
+      for (const member of doc?.members ?? []) if (member.sessionID === sessionID && member.leftAt === undefined) out.push({ workspaceID: entry.key, member })
+    }
+    return out
+  }
+
+  /** (RP-08) Current memberships of several sessions, in one scan of the user's workspaces. */
+  async membershipsOfMany(userID: string, sessionIDs: readonly string[]): Promise<Map<string, string[]>> {
+    const wanted = new Set(sessionIDs)
+    const out = new Map<string, string[]>()
+    for (const entry of await this.state.list(userID, WORKSPACE_MEMBERS)) {
+      let doc: MembersDoc | undefined
+      try {
+        doc = membersDoc(entry.value, entry.key)
+      } catch {
+        continue
+      }
+      for (const member of doc?.members ?? []) {
+        if (!wanted.has(member.sessionID) || member.leftAt !== undefined) continue
+        const list = out.get(member.sessionID) ?? []
+        if (!list.includes(entry.key)) list.push(entry.key)
+        out.set(member.sessionID, list)
+      }
+    }
+    return out
+  }
+
+  /** The session ended (deleted): departs its current memberships as `ended`; returns those it departed. */
+  async sessionEnded(userID: string, sessionID: string): Promise<WorkspaceMember[]> {
+    const ended: WorkspaceMember[] = []
+    for (const { workspaceID, member } of await this.membershipsOf(userID, sessionID)) {
+      const left = await this.leave(userID, workspaceID, member.id, { reason: "ended" })
+      if (left.leftReason === "ended" && left.revision !== member.revision) ended.push(left)
+    }
+    return ended
+  }
+
+  /**
+   * Archives the workspace (WorkspaceStore.archive) and departs its current members as `archived`. Re-running it
+   * finishes a sweep a crash interrupted. Assignments keep their status.
+   */
+  async archiveWorkspace(userID: string, workspaceID: string, expectedRevision?: number): Promise<{ workspace: HubWorkspace; departed: number }> {
+    const workspace = await this.workspaces.archive(userID, workspaceID, expectedRevision)
+    let departed = 0
+    await updateVersioned<MembersDoc>(this.state, userID, WORKSPACE_MEMBERS, workspaceID, (raw) => {
+      const doc = membersDoc(raw, workspaceID)
+      departed = doc?.members.filter((m) => m.leftAt === undefined).length ?? 0
+      if (!doc || departed === 0) return undefined
+      const at = this.now()
+      return { ...doc, members: doc.members.map((m) => (m.leftAt === undefined ? { ...m, leftAt: at, leftReason: "archived" as const, revision: m.revision + 1 } : m)) }
+    })
+    return { workspace, departed }
+  }
+
+  /** Makes buffered writes durable (standalone debounce). */
+  async flush(): Promise<void> {
+    await this.state.flush?.()
+  }
+
+  // ---------- assignments ----------
+
+  /**
+   * Gives a current member an assignment (status open unless given in_progress/blocked). With an idempotency key,
+   * the same key and body within IDEMPOTENCY_TTL_MS return the original (created false); another body is a conflict.
+   */
+  async assign(userID: string, workspaceID: string, input: unknown, options: { readonly idempotencyKey?: string } = {}): Promise<{ assignment: StoredAssignment; created: boolean }> {
+    const body = this.assignmentBody(input)
+    const key = options.idempotencyKey
+    if (key !== undefined && !IDEMPOTENCY_KEY.test(key)) throw new AgentError("invalid", "Idempotency-Key must be 1–200 of A-Z a-z 0-9 _ . : -")
+    await this.active(userID, workspaceID)
+    await this.currentMember(userID, workspaceID, body.memberID)
+    const digest = digestOf(body)
+    let result: { assignment: StoredAssignment; created: boolean } | undefined
+    await updateVersioned<AssignmentsDoc>(this.state, userID, WORKSPACE_ASSIGNMENTS, workspaceID, (raw) => {
+      const doc = assignmentsDoc(raw, workspaceID)
+      const at = this.now()
+      const assignments = doc?.assignments ?? []
+      let keys = (doc?.keys ?? []).filter((k) => at - k.at < IDEMPOTENCY_TTL_MS)
+      const held = key === undefined ? undefined : keys.find((k) => k.key === key)
+      if (held) {
+        if (held.digest !== digest)
+          throw new AgentError("conflict", `Idempotency-Key ${key} was used for a different assignment`, { hint: "Use a new key for a different body, or resend the original body" })
+        const existing = assignments.find((a) => a.id === held.assignmentID)
+        if (existing) {
+          result = { assignment: existing, created: false }
+          return undefined
+        }
+        keys = keys.filter((k) => k !== held)
+      }
+      if (assignments.filter((a) => !CLOSED.has(a.status)).length >= this.limits.openAssignmentsPerWorkspace)
+        throw new AgentError("rate_limited", `A workspace has at most ${this.limits.openAssignmentsPerWorkspace} open assignments`, { hint: "Close some first" })
+      const assignment: StoredAssignment = { v: 1, id: this.newID("assignment"), workspaceID, ...body, revision: 1, createdAt: at, updatedAt: at }
+      if (key !== undefined) keys = [...keys, { key, assignmentID: assignment.id, digest, at }].slice(-KEYS_MAX)
+      result = { assignment, created: true }
+      return { v: 1, workspaceID, assignments: [...assignments, assignment], keys }
+    })
+    return result!
+  }
+
+  /** One retained assignment; not_found otherwise. */
+  async assignment(userID: string, workspaceID: string, id: string): Promise<StoredAssignment> {
+    const found = (await this.readAssignments(userID, workspaceID)).find((a) => a.id === id)
+    if (!found) throw new AgentError("not_found", `No assignment ${id} in workspace ${workspaceID}`)
+    return found
+  }
+
+  /** Retained assignments by creation, paged and filtered, each with its assignee's membership and presence. */
+  async assignments(userID: string, workspaceID: string, query: AssignmentListQuery = {}): Promise<Page<AssignmentView>> {
+    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.status !== undefined && !ASSIGNMENT_STATUSES.includes(query.status as AssignmentStatus))
+      throw new AgentError("invalid", `status must be one of ${ASSIGNMENT_STATUSES.join(", ")}`)
+    const after = query.cursor === undefined ? undefined : decodeCursor(query.cursor)
+    const all = (await this.readAssignments(userID, workspaceID))
+      .filter((a) => query.memberID === undefined || a.memberID === query.memberID)
+      .filter((a) => query.status === undefined || a.status === query.status)
+      .filter((a) => !after || a.createdAt > after[0] || (a.createdAt === after[0] && a.id > after[1]))
+      .sort(byCreation)
+    const page = all.slice(0, limit)
+    const members = new Map((await this.readMembers(userID, workspaceID)).map((m) => [m.id, m]))
+    const presence = await this.presenceOf(userID, page.flatMap((a) => members.get(a.memberID)?.sessionID ?? []))
+    const items = page.map((assignment): AssignmentView => {
+      const member = members.get(assignment.memberID)
+      return {
+        assignment,
+        member: !member ? "missing" : member.leftAt === undefined ? "current" : "left",
+        presence: member ? presence.get(member.sessionID)! : "unknown",
+      }
+    })
+    return all.length > limit ? { items, cursor: encodeCursor(page.at(-1)!) } : { items }
+  }
+
+  /** Moves an open assignment to another current member. The same member again is a no-op. */
+  async reassign(userID: string, workspaceID: string, id: string, memberID: unknown, expectedRevision?: number): Promise<StoredAssignment> {
+    checkExpected(expectedRevision)
+    if (!isContractID("member", memberID)) throw new AgentError("invalid", "memberID must be a workspace member ID")
+    await this.active(userID, workspaceID)
+    await this.currentMember(userID, workspaceID, memberID)
+    return this.mutateAssignment(userID, workspaceID, id, expectedRevision, (a) => {
+      if (CLOSED.has(a.status)) throw new AgentError("invalid", `Assignment ${id} is ${a.status}`, { hint: "Create a new assignment" })
+      return a.memberID === memberID ? undefined : { ...a, memberID }
+    })
+  }
+
+  /**
+   * Sets the status. `done` and `cancelled` are the explicit completion: a closed assignment is final (the same
+   * status again is a no-op, anything else invalid). Nothing else ever closes an assignment.
+   */
+  async setStatus(userID: string, workspaceID: string, id: string, status: unknown, expectedRevision?: number): Promise<StoredAssignment> {
+    checkExpected(expectedRevision)
+    if (!ASSIGNMENT_STATUSES.includes(status as AssignmentStatus)) throw new AgentError("invalid", `status must be one of ${ASSIGNMENT_STATUSES.join(", ")}`)
+    await this.active(userID, workspaceID)
+    return this.mutateAssignment(userID, workspaceID, id, expectedRevision, (a) => {
+      if (a.status === status) return undefined
+      if (CLOSED.has(a.status)) throw new AgentError("invalid", `Assignment ${id} is ${a.status}`, { hint: "Create a new assignment" })
+      const next = { ...a, status: status as AssignmentStatus }
+      return CLOSED.has(next.status) ? { ...next, closedAt: this.now() } : next
+    })
+  }
+
+  // ---------- internals ----------
+
+  private assignmentBody(input: unknown): Pick<StoredAssignment, "memberID" | "title" | "status" | "criteria" | "ref"> {
+    if (!isObj(input)) throw new AgentError("invalid", "body must be an object")
+    const { memberID, title, status, criteria, ref } = input
+    if (!isContractID("member", memberID)) throw new AgentError("invalid", "memberID must be a workspace member ID")
+    if (!isLabel(title)) throw new AgentError("invalid", "title must be 1–120 characters of text")
+    if (status !== undefined && !OPENING.includes(status as AssignmentStatus))
+      throw new AgentError("invalid", `status must be one of ${OPENING.join(", ")}`, { hint: "Closing is an explicit status change after creation" })
+    const { criteriaPerAssignment, criterionMax, refMax } = this.limits
+    if (criteria !== undefined && (!Array.isArray(criteria) || criteria.length > criteriaPerAssignment || !criteria.every((c) => isLabel(c, criterionMax))))
+      throw new AgentError("invalid", `criteria must be a list of at most ${criteriaPerAssignment} lines of 1–${criterionMax} characters`)
+    if (ref !== undefined && !isLabel(ref, refMax)) throw new AgentError("invalid", `ref must be 1–${refMax} characters of text`)
+    return {
+      memberID,
+      title,
+      status: (status as AssignmentStatus | undefined) ?? "open",
+      ...(criteria !== undefined ? { criteria: [...(criteria as string[])] } : {}),
+      ...(ref !== undefined ? { ref: ref as string } : {}),
+    }
+  }
+
+  /** The user's active workspace (not_found; invalid when archived). */
+  private async active(userID: string, workspaceID: string): Promise<HubWorkspace> {
+    const workspace = await this.workspaces.require(userID, workspaceID)
+    if (workspace.state === "archived") throw archivedError(workspaceID)
+    return workspace
+  }
+
+  private async readMembers(userID: string, workspaceID: string): Promise<readonly WorkspaceMember[]> {
+    await this.workspaces.require(userID, workspaceID)
+    return membersDoc((await this.state.get(userID, WORKSPACE_MEMBERS, workspaceID))?.value, workspaceID)?.members ?? []
+  }
+
+  private async readAssignments(userID: string, workspaceID: string): Promise<readonly StoredAssignment[]> {
+    await this.workspaces.require(userID, workspaceID)
+    return assignmentsDoc((await this.state.get(userID, WORKSPACE_ASSIGNMENTS, workspaceID))?.value, workspaceID)?.assignments ?? []
+  }
+
+  /** A current member (not_found when missing, invalid when departed). */
+  private async currentMember(userID: string, workspaceID: string, memberID: string): Promise<WorkspaceMember> {
+    const member = await this.member(userID, workspaceID, memberID)
+    if (member.leftAt !== undefined) throw new AgentError("invalid", `Member ${memberID} left the workspace`, { hint: "Assign a current member" })
+    return member
+  }
+
+  /** Members referenced by open assignments (never pruned). */
+  private async openAssignees(userID: string, workspaceID: string): Promise<Set<string>> {
+    const doc = assignmentsDoc((await this.state.get(userID, WORKSPACE_ASSIGNMENTS, workspaceID))?.value, workspaceID)
+    return new Set((doc?.assignments ?? []).filter((a) => !CLOSED.has(a.status)).map((a) => a.memberID))
+  }
+
+  private async presenceOf(userID: string, sessionIDs: readonly string[]): Promise<Map<string, SessionPresence>> {
+    const out = new Map<string, SessionPresence>()
+    for (const id of sessionIDs) if (!out.has(id)) out.set(id, await this.deps.presence(userID, id))
+    return out
+  }
+
+  /** Version-checked change of one member inside the aggregate; `change` returning undefined leaves it alone. */
+  private async mutateMember(
+    userID: string,
+    workspaceID: string,
+    memberID: string,
+    expectedRevision: number | undefined,
+    change: (current: WorkspaceMember) => WorkspaceMember | undefined,
+  ): Promise<WorkspaceMember> {
+    let result: WorkspaceMember | undefined
+    await updateVersioned<MembersDoc>(this.state, userID, WORKSPACE_MEMBERS, workspaceID, (raw) => {
+      const doc = membersDoc(raw, workspaceID)
+      const current = doc?.members.find((m) => m.id === memberID)
+      if (!doc || !current) throw new AgentError("not_found", `No member ${memberID} in workspace ${workspaceID}`)
+      if (expectedRevision !== undefined && current.revision !== expectedRevision) throw conflict(`Member ${memberID}`, current.revision)
+      const next = change(current)
+      result = next ? { ...next, revision: current.revision + 1 } : current
+      return next ? { ...doc, members: doc.members.map((m) => (m.id === memberID ? result! : m)) } : undefined
+    })
+    return result!
+  }
+
+  /** Version-checked change of one assignment, then closed-assignment retention. */
+  private async mutateAssignment(
+    userID: string,
+    workspaceID: string,
+    id: string,
+    expectedRevision: number | undefined,
+    change: (current: StoredAssignment) => StoredAssignment | undefined,
+  ): Promise<StoredAssignment> {
+    let result: StoredAssignment | undefined
+    await updateVersioned<AssignmentsDoc>(this.state, userID, WORKSPACE_ASSIGNMENTS, workspaceID, (raw) => {
+      const doc = assignmentsDoc(raw, workspaceID)
+      const current = doc?.assignments.find((a) => a.id === id)
+      if (!doc || !current) throw new AgentError("not_found", `No assignment ${id} in workspace ${workspaceID}`)
+      if (expectedRevision !== undefined && current.revision !== expectedRevision) throw conflict(`Assignment ${id}`, current.revision)
+      const next = change(current)
+      if (!next) {
+        result = current
+        return undefined
+      }
+      result = { ...next, revision: current.revision + 1, updatedAt: this.now() }
+      return { ...doc, assignments: this.retained(doc.assignments.map((a) => (a.id === id ? result! : a))) }
+    })
+    return result!
+  }
+
+  /** Drops the oldest closed assignments beyond closedAssignmentsRetained. */
+  private retained(assignments: readonly StoredAssignment[]): StoredAssignment[] {
+    const closed = assignments.filter((a) => CLOSED.has(a.status)).sort((a, b) => (a.closedAt ?? 0) - (b.closedAt ?? 0))
+    const drop = new Set(closed.slice(0, Math.max(0, closed.length - this.limits.closedAssignmentsRetained)).map((a) => a.id))
+    return assignments.filter((a) => !drop.has(a.id))
+  }
+}