@huynle/hub 0.7.3 → 0.8.0

package/src/central/teams/seats.ts

@@ -0,0 +1,272 @@
+// Team membership storage (HWA-33; contract TeamStaffing / TeamSeat in packages/protocol/src/teams.ts, decision
+// zltiwb4s 2026-10-28: many-to-many membership per (team, role, session, generation)).
+//
+// Storage: `team-seats`, one aggregate per team (key: team ID; collections.ts) holding its staffing records, current
+// and ended, plus the staffing Idempotency-Keys, so the per-role cap, "one current seat per (role, session)" and a
+// key's claim are one version-checked write. A session may hold several roles in one team and seats in several
+// teams. Each record carries its own `revision` (1 on staffing, +1 when ended); a stale expectedRevision is 409
+// conflict with currentRevision. Re-staffing a (role, session) whose seat ended is the next `generation` (counted
+// from the retained records). Additive: `teamVersion`, the published team version the seat was staffed under; current
+// seats pin it against version retention (pinnedVersions).
+//
+// Seats grant no authority: staffing a session needs the caller's existing grants (HWA-35 launches and checks them;
+// this store only records). Pause and archive refuse new seats; existing seats stay (an archived team's seats are
+// ignored by teamDeliveryVerdict, which only consults active teams). Session deletion ends seats via sessionEnded
+// (HWA-35 wires Registry.onSessionDeleted). Ended seats are retained up to endedSeatsRetained per team.
+//
+// Read API for delivery (HWA-34) and discovery (HWA-40): seatsOf(userID, sessionID) and deliveryContext(userID,
+// sessionIDs) give exactly teamDeliveryVerdict's senderSeats / recipientSeats / teams inputs.
+import { createHash, randomBytes } from "node:crypto"
+import {
+  ID_PREFIXES,
+  IDEMPOTENCY_KEY,
+  IDEMPOTENCY_TTL_MS,
+  type IdKind,
+  isExpectedRevision,
+  isSlug,
+  TEAM_LIMITS,
+  type TeamDefinition,
+  type TeamSeat,
+  type TeamStaffing,
+} from "../../protocol"
+import { canonicalBody } from "../agent/idempotency"
+import { AgentError } from "../agent/errors"
+import { updateVersioned } from "../agent/versioned"
+import type { Clock, StateStore } from "../backend/types"
+import { currentSeats, readSeatsDoc, type SeatKey, type SeatsDoc, TEAM_SEATS } from "./collections"
+import type { TeamStore } from "./store"
+import { TEAM_STORE_LIMITS } from "./validation"
+
+const SESSION_ID = /^[A-Za-z0-9_.:-]{1,200}$/
+const STAFF_FIELDS = new Set(["role", "sessionID"])
+/** Live staffing Idempotency-Keys kept per team aggregate (oldest dropped first). */
+const KEYS_PER_TEAM = 1_000
+
+/** A staffing record: the contract TeamStaffing plus the published version it was staffed under. */
+export interface TeamSeatRecord extends TeamStaffing {
+  readonly teamVersion: number
+}
+
+export type DeliveryTeams = ReadonlyMap<string, Pick<TeamDefinition, "mode" | "edges" | "roles" | "state">>
+
+export interface DeliveryContext {
+  /** Each asked session's current seats (empty when it holds none). */
+  readonly seats: ReadonlyMap<string, readonly TeamSeat[]>
+  /** The teams those seats are in, as teamDeliveryVerdict reads them. */
+  readonly teams: DeliveryTeams
+}
+
+export interface TeamSeatStoreDeps {
+  readonly state: StateStore
+  readonly teams: TeamStore
+  readonly now?: Clock
+  readonly newID?: (kind: IdKind) => string
+  /** Says whether the user's directory knows the session (unknown or another user's: not_found). */
+  readonly knowsSession?: (userID: string, sessionID: string) => boolean | Promise<boolean>
+  readonly limits?: { readonly endedSeatsRetained?: number }
+}
+
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+const digestOf = (v: unknown) => createHash("sha256").update(canonicalBody(v)).digest("hex")
+
+export class TeamSeatStore {
+  private readonly state: StateStore
+  private readonly teams: TeamStore
+  private readonly now: Clock
+  private readonly newID: (kind: IdKind) => string
+  private readonly endedRetained: number
+
+  constructor(private readonly deps: TeamSeatStoreDeps) {
+    this.state = deps.state
+    this.teams = deps.teams
+    this.now = deps.now ?? Date.now
+    this.newID = deps.newID ?? ((kind) => `${ID_PREFIXES[kind]}_${randomBytes(12).toString("hex")}`)
+    this.endedRetained = deps.limits?.endedSeatsRetained ?? TEAM_STORE_LIMITS.endedSeatsRetained
+  }
+
+  /**
+   * Staffs a session in a role of an active, unpaused team (its published definition). The same current
+   * (role, session) again returns the seat (created false). 429 past the role's maxMembers (else sessionsPerRole).
+   */
+  async staff(userID: string, teamID: string, input: unknown, options: { readonly idempotencyKey?: string } = {}): Promise<{ staffing: TeamSeatRecord; created: boolean }> {
+    if (!isObj(input)) throw new AgentError("invalid", "body must be an object")
+    const unknown = Object.keys(input).find((k) => !STAFF_FIELDS.has(k))
+    if (unknown !== undefined) throw new AgentError("invalid", `unknown field ${/^[A-Za-z0-9_-]{1,40}$/.test(unknown) ? unknown : "(unprintable)"}`)
+    const { role, sessionID } = input
+    if (!isSlug(role)) throw new AgentError("invalid", "role must be a role name of the team")
+    if (typeof sessionID !== "string" || !SESSION_ID.test(sessionID)) throw new AgentError("invalid", "sessionID must be a session ID")
+    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 _ . : -")
+    const team = await this.teams.require(userID, teamID)
+    if (team.state === "archived") throw new AgentError("invalid", `Team ${teamID} is archived`, { hint: "Restore it first" })
+    if (team.paused) throw new AgentError("invalid", `Team ${teamID} is paused`, { hint: "Resume it first" })
+    const roleSpec = team.roles.find((r) => r.name === role)
+    if (!roleSpec) throw new AgentError("invalid", `Team ${team.name} has no role ${role}`)
+    if (this.deps.knowsSession && !(await this.deps.knowsSession(userID, sessionID))) throw new AgentError("not_found", `No session ${sessionID}`)
+    const limit = Math.min(roleSpec.maxMembers ?? TEAM_LIMITS.sessionsPerRole, TEAM_LIMITS.sessionsPerRole)
+    const digest = digestOf({ role, sessionID })
+    let result: { staffing: TeamSeatRecord; created: boolean } | undefined
+    await updateVersioned<SeatsDoc>(this.state, userID, TEAM_SEATS, teamID, (raw) => {
+      const doc = readSeatsDoc(raw, teamID)
+      const now = this.now()
+      const keys = this.liveKeys(doc, now)
+      const seats = (doc?.seats ?? []) as TeamSeatRecord[]
+      if (key !== undefined && keys[key]) {
+        if (keys[key].digest !== digest) throw new AgentError("conflict", `Idempotency-Key ${key} was used for another staffing`, { hint: "Use a new key for a different body" })
+        const original = seats.find((s) => s.id === keys[key]!.staffingID)
+        if (original) {
+          result = { staffing: original, created: false }
+          return undefined
+        }
+      }
+      const current = currentSeats(doc) as TeamSeatRecord[]
+      const same = current.find((s) => s.role === role && s.sessionID === sessionID)
+      if (same) {
+        result = { staffing: same, created: false }
+        return undefined
+      }
+      if (current.filter((s) => s.role === role).length >= limit)
+        throw new AgentError("rate_limited", `Role ${role} of team ${team.name} holds at most ${limit} sessions`, { hint: "Unstaff a session first", extra: { limit } })
+      const generation = 1 + Math.max(0, ...seats.filter((s) => s.role === role && s.sessionID === sessionID).map((s) => s.generation))
+      const staffing: TeamSeatRecord = { v: 1, id: this.newID("staffing"), teamID, role, sessionID, generation, since: now, revision: 1, teamVersion: team.version }
+      result = { staffing, created: true }
+      const nextKeys = key === undefined ? keys : { ...keys, [key]: { staffingID: staffing.id, digest, at: now } }
+      return { v: 1, teamID, seats: this.retained([...seats, staffing]), keys: this.boundedKeys(nextKeys) }
+    })
+    return result!
+  }
+
+  /** Ends a seat under its expected revision; ending an ended seat is a no-op. Allowed on archived teams. */
+  async unstaff(userID: string, teamID: string, staffingID: string, expectedRevision: number): Promise<TeamSeatRecord> {
+    if (!isExpectedRevision(expectedRevision)) throw new AgentError("invalid", "expectedRevision is required (the revision you read)")
+    await this.teams.require(userID, teamID)
+    let result: TeamSeatRecord | undefined
+    await updateVersioned<SeatsDoc>(this.state, userID, TEAM_SEATS, teamID, (raw) => {
+      const doc = readSeatsDoc(raw, teamID)
+      const seats = (doc?.seats ?? []) as TeamSeatRecord[]
+      const seat = seats.find((s) => s.id === staffingID)
+      if (!seat) throw new AgentError("not_found", `No staffing ${staffingID} in team ${teamID}`)
+      if (seat.revision !== expectedRevision)
+        throw new AgentError("conflict", `Staffing ${staffingID} changed since you read it (revision ${seat.revision} now)`, { hint: "Read it again and retry", extra: { currentRevision: seat.revision } })
+      if (seat.until !== undefined) {
+        result = seat
+        return undefined
+      }
+      const ended: TeamSeatRecord = { ...seat, until: this.now(), revision: seat.revision + 1 }
+      result = ended
+      return { v: 1, teamID, seats: this.retained(seats.map((s) => (s.id === staffingID ? ended : s))), keys: doc?.keys ?? {} }
+    })
+    return result!
+  }
+
+  /** Ends every current seat of a deleted session, in every team; returns the ended seats. */
+  async sessionEnded(userID: string, sessionID: string): Promise<TeamSeatRecord[]> {
+    const ended: TeamSeatRecord[] = []
+    for (const entry of await this.state.list(userID, TEAM_SEATS)) {
+      if (!this.readable(entry.value, entry.key)?.seats.some((s) => s.sessionID === sessionID && s.until === undefined)) continue
+      await updateVersioned<SeatsDoc>(this.state, userID, TEAM_SEATS, entry.key, (raw) => {
+        const doc = readSeatsDoc(raw, entry.key)
+        if (!doc) return undefined
+        const at = this.now()
+        const now: TeamSeatRecord[] = []
+        const seats = (doc.seats as TeamSeatRecord[]).map((s) => {
+          if (s.sessionID !== sessionID || s.until !== undefined) return s
+          const e = { ...s, until: at, revision: s.revision + 1 }
+          now.push(e)
+          return e
+        })
+        if (now.length === 0) return undefined
+        ended.push(...now)
+        return { ...doc, seats: this.retained(seats) }
+      })
+    }
+    return ended
+  }
+
+  /** The team's seats by start time (current only with `current: true`). */
+  async list(userID: string, teamID: string, options: { readonly current?: boolean } = {}): Promise<TeamSeatRecord[]> {
+    await this.teams.require(userID, teamID)
+    const doc = readSeatsDoc((await this.state.get(userID, TEAM_SEATS, teamID))?.value, teamID)
+    const seats = (options.current ? currentSeats(doc) : [...(doc?.seats ?? [])]) as TeamSeatRecord[]
+    return seats.sort((a, b) => a.since - b.since || (a.id < b.id ? -1 : 1))
+  }
+
+  /** The session's current seats in all the user's teams (unreadable aggregates are skipped). */
+  async seatsOf(userID: string, sessionID: string): Promise<TeamSeat[]> {
+    return (await this.seatsBySession(userID, [sessionID])).get(sessionID) ?? []
+  }
+
+  /** Seats of several sessions and the teams they are in: teamDeliveryVerdict's inputs (HWA-34). */
+  async deliveryContext(userID: string, sessionIDs: readonly string[]): Promise<DeliveryContext> {
+    const seats = await this.seatsBySession(userID, sessionIDs)
+    const teams = new Map<string, Pick<TeamDefinition, "mode" | "edges" | "roles" | "state">>()
+    for (const teamID of new Set([...seats.values()].flat().map((s) => s.teamID))) {
+      try {
+        const team = await this.teams.get(userID, teamID)
+        if (team) teams.set(teamID, { mode: team.mode, edges: team.edges, roles: team.roles, state: team.state })
+      } catch {
+        // A team this build cannot read takes no part in delivery (its seats are then ignored by the verdict).
+      }
+    }
+    // Seats of unreadable or missing teams are dropped: the verdict requires every seat's team to be in the map.
+    const known = new Map([...seats].map(([id, list]) => [id, list.filter((s) => teams.has(s.teamID))] as const))
+    return { seats: known, teams }
+  }
+
+  /** (RP-08) Current seat counts per team and role, in one scan of the user's seats. */
+  async currentCounts(userID: string): Promise<Map<string, Map<string, number>>> {
+    const out = new Map<string, Map<string, number>>()
+    for (const entry of await this.state.list(userID, TEAM_SEATS)) {
+      const roles = new Map<string, number>()
+      for (const seat of currentSeats(this.readable(entry.value, entry.key))) roles.set(seat.role, (roles.get(seat.role) ?? 0) + 1)
+      out.set(entry.key, roles)
+    }
+    return out
+  }
+
+  /** Published versions current seats were staffed under (TeamStore retention keeps them). */
+  async pinnedVersions(userID: string, teamID: string): Promise<ReadonlySet<number>> {
+    const doc = this.readable((await this.state.get(userID, TEAM_SEATS, teamID))?.value, teamID)
+    return new Set((currentSeats(doc) as TeamSeatRecord[]).map((s) => s.teamVersion).filter((v) => Number.isSafeInteger(v)))
+  }
+
+  // ---------- internals ----------
+
+  private async seatsBySession(userID: string, sessionIDs: readonly string[]): Promise<Map<string, TeamSeat[]>> {
+    const wanted = new Set(sessionIDs)
+    const out = new Map<string, TeamSeat[]>(sessionIDs.map((id) => [id, []]))
+    for (const entry of await this.state.list(userID, TEAM_SEATS)) {
+      for (const seat of currentSeats(this.readable(entry.value, entry.key))) {
+        if (wanted.has(seat.sessionID)) out.get(seat.sessionID)!.push({ teamID: seat.teamID, role: seat.role })
+      }
+    }
+    return out
+  }
+
+  private readable(raw: unknown, teamID: string): SeatsDoc | undefined {
+    try {
+      return readSeatsDoc(raw, teamID)
+    } catch {
+      return undefined
+    }
+  }
+
+  /** Current seats plus the newest endedRetained ended ones. */
+  private retained(seats: readonly TeamSeatRecord[]): TeamSeatRecord[] {
+    const ended = seats.filter((s) => s.until !== undefined).sort((a, b) => b.until! - a.until! || (a.id < b.id ? 1 : -1))
+    const keep = new Set(ended.slice(0, this.endedRetained).map((s) => s.id))
+    return seats.filter((s) => s.until === undefined || keep.has(s.id))
+  }
+
+  private liveKeys(doc: SeatsDoc | undefined, now: number): Record<string, SeatKey> {
+    const out: Record<string, SeatKey> = {}
+    for (const [k, v] of Object.entries(doc?.keys ?? {})) if (isObj(v) && typeof v.at === "number" && now - v.at < IDEMPOTENCY_TTL_MS) out[k] = v
+    return out
+  }
+
+  private boundedKeys(keys: Record<string, SeatKey>): Record<string, SeatKey> {
+    const entries = Object.entries(keys)
+    if (entries.length <= KEYS_PER_TEAM) return keys
+    return Object.fromEntries(entries.sort((a, b) => b[1].at - a[1].at).slice(0, KEYS_PER_TEAM))
+  }
+}