@huynle/hub 0.7.4 → 0.8.1

package/src/central/workspaces/events.ts

@@ -0,0 +1,85 @@
+// Compact journal events of workspaces (HWA-06; contract: WORKSPACE_EVENT_TYPES, family `manage`). Allowlisted
+// payloads only: IDs, enums (state, role, status, reason, change), revisions and counts. Never titles,
+// descriptions, tags, metadata, labels, repository paths, assignment titles/criteria/refs or any other free text.
+// A reader that missed events (journal reset) re-reads the `workspaces` snapshot (RESET_REFRESH).
+import type { HostRepoBinding, HubWorkspace, SupervisionLink, WorkspaceAssignment, WorkspaceMember } from "../../protocol"
+import type { EventInput } from "../agent/events"
+import type { DepartureResult, SupervisionResult } from "./supervision"
+
+export const workspaceCreatedEvent = (workspace: HubWorkspace): EventInput => ({
+  type: "workspace.created",
+  family: "manage",
+  subject: { workspaceID: workspace.id },
+  data: { revision: workspace.revision, state: workspace.state },
+})
+
+/** Title, description, tags or metadata changed. */
+export const workspacePatchedEvent = (workspace: HubWorkspace): EventInput => ({
+  type: "workspace.updated",
+  family: "manage",
+  subject: { workspaceID: workspace.id },
+  data: { change: "patched", revision: workspace.revision },
+})
+
+/** A host repo binding was added or removed (the binding aggregate, not the workspace record, changed). */
+export const bindingEvent = (workspaceID: string, binding: HostRepoBinding, change: "bound" | "unbound"): EventInput => ({
+  type: "workspace.updated",
+  family: "manage",
+  subject: { workspaceID, bindingID: binding.id, machineID: binding.machineID },
+  data: { change, bindingRevision: binding.revision },
+})
+
+/** Archived (`state: archived`, with how many members departed) or restored (`state: active`). */
+export const workspaceArchivedEvent = (workspace: HubWorkspace, departed: number): EventInput => ({
+  type: "workspace.archived",
+  family: "manage",
+  subject: { workspaceID: workspace.id },
+  data: { state: workspace.state, revision: workspace.revision, departed },
+})
+
+export const memberJoinedEvent = (member: WorkspaceMember): EventInput => ({
+  type: "workspace.member.joined",
+  family: "manage",
+  subject: { workspaceID: member.workspaceID, memberID: member.id, sessionID: member.sessionID },
+  data: { role: member.role, generation: member.generation, revision: member.revision },
+})
+
+/** A current member changed role (a workspace update; joined/left stay for membership itself). */
+export const memberRoleEvent = (member: WorkspaceMember): EventInput => ({
+  type: "workspace.updated",
+  family: "manage",
+  subject: { workspaceID: member.workspaceID, memberID: member.id, sessionID: member.sessionID },
+  data: { change: "member_role", role: member.role, memberRevision: member.revision },
+})
+
+export const memberLeftEvent = (member: WorkspaceMember): EventInput => ({
+  type: "workspace.member.left",
+  family: "manage",
+  subject: { workspaceID: member.workspaceID, memberID: member.id, sessionID: member.sessionID },
+  data: { role: member.role, reason: member.leftReason ?? "removed", revision: member.revision },
+})
+
+/** A PUT /supervision change (attached, moved, reordered, detached) or stale links pruned by it. */
+export function supervisionSetEvent(memberID: string, result: SupervisionResult, link?: SupervisionLink): EventInput {
+  return {
+    type: "workspace.supervision.changed",
+    family: "manage",
+    subject: { workspaceID: result.workspaceID, memberID, ...(link ? { supervisorMemberID: link.supervisorMemberID } : {}) },
+    data: { change: result.change, revision: result.revision, pruned: result.pruned, ...(link ? { order: link.order, linkRevision: link.revision } : {}) },
+  }
+}
+
+/** A departure detached or transferred a member's links. */
+export const supervisionDepartedEvent = (memberID: string, result: DepartureResult): EventInput => ({
+  type: "workspace.supervision.changed",
+  family: "manage",
+  subject: { workspaceID: result.workspaceID, memberID },
+  data: { change: "departed", revision: result.revision, detached: result.detached, transferred: result.transferred, pruned: result.pruned },
+})
+
+export const assignmentChangedEvent = (assignment: WorkspaceAssignment, change: "created" | "status" | "reassigned"): EventInput => ({
+  type: "workspace.assignment.changed",
+  family: "manage",
+  subject: { workspaceID: assignment.workspaceID, assignmentID: assignment.id, memberID: assignment.memberID },
+  data: { change, status: assignment.status, revision: assignment.revision },
+})

package/src/central/workspaces/lifecycle.ts

@@ -0,0 +1,93 @@
+// Departures across the workspace stores (HWA-06; contract clarifications from HWA-04 and HWA-05): whenever a
+// member departs, its supervision links follow, and the journal gets compact events.
+//
+// - leave (DELETE /workspaces/:id/members/:memberID): MembershipStore.leave (`removed`), then
+//   SupervisionStore.memberDeparted.
+// - archive (POST /workspaces/:id/archive): MembershipStore.archiveWorkspace (members depart as `archived`), then
+//   memberDeparted for each member that was current before.
+// - sessionEnded (the hub's session-deleted path): MembershipStore.sessionEnded (`ended`) in every workspace of
+//   the user, then memberDeparted for each.
+//
+// memberDeparted is called even when the membership step was a no-op, so repeating a call finishes a sweep a crash
+// interrupted (the supervision step is idempotent). Events are appended after the writes; an event failure is
+// reported, never thrown (the change already happened). Nothing here grants authority or touches native
+// parentID/rootID.
+import type { HubWorkspace, WorkspaceMember } from "../../protocol"
+import type { AgentEvents, EventInput } from "../agent/events"
+import { memberLeftEvent, supervisionDepartedEvent, workspaceArchivedEvent } from "./events"
+import type { MembershipStore } from "./members"
+import type { WorkspaceStore } from "./store"
+import type { DepartureResult, SupervisionStore } from "./supervision"
+
+export interface WorkspaceLifecycleDeps {
+  readonly workspaces: WorkspaceStore
+  readonly members: MembershipStore
+  readonly supervision: SupervisionStore
+  readonly events?: Pick<AgentEvents, "append">
+  readonly report?: (cause: unknown) => void
+}
+
+export interface Departure {
+  readonly member: WorkspaceMember
+  readonly supervision: DepartureResult
+}
+
+const touched = (r: DepartureResult) => r.detached + r.transferred + r.pruned > 0
+
+export class WorkspaceLifecycle {
+  private readonly report: (cause: unknown) => void
+
+  constructor(private readonly deps: WorkspaceLifecycleDeps) {
+    this.report = deps.report ?? ((cause) => console.error(`[hub] workspace event failed: ${cause instanceof Error ? cause.message : String(cause)}`))
+  }
+
+  /** Appends compact events in order; failures are reported. */
+  async emit(userID: string, ...events: EventInput[]): Promise<void> {
+    if (!this.deps.events) return
+    for (const event of events) await this.deps.events.append(userID, event).catch(this.report)
+  }
+
+  /** Removes a member under its expected revision and detaches its supervision. */
+  async leave(userID: string, workspaceID: string, memberID: string, expectedRevision: number): Promise<Departure> {
+    const member = await this.deps.members.leave(userID, workspaceID, memberID, { expectedRevision, reason: "removed" })
+    const changed = member.revision !== expectedRevision
+    const result = await this.deps.supervision.memberDeparted(userID, workspaceID, memberID)
+    await this.emit(userID, ...(changed ? [memberLeftEvent(member)] : []), ...(touched(result) ? [supervisionDepartedEvent(memberID, result)] : []))
+    return { member, supervision: result }
+  }
+
+  /** Archives the workspace under its expected revision; every current member departs and loses its links. */
+  async archive(userID: string, workspaceID: string, expectedRevision: number): Promise<{ workspace: HubWorkspace; departed: number; supervision: { detached: number } }> {
+    const before = await this.deps.members.members(userID, workspaceID)
+    const { workspace, departed } = await this.deps.members.archiveWorkspace(userID, workspaceID, expectedRevision)
+    const out: EventInput[] = []
+    if (workspace.revision !== expectedRevision || departed > 0) out.push(workspaceArchivedEvent(workspace, departed))
+    let detached = 0
+    for (const { member } of before) {
+      const result = await this.deps.supervision.memberDeparted(userID, workspaceID, member.id)
+      detached += result.detached + result.transferred
+      if (touched(result)) out.push(supervisionDepartedEvent(member.id, result))
+    }
+    await this.emit(userID, ...out)
+    return { workspace, departed, supervision: { detached } }
+  }
+
+  /**
+   * The session was deleted: it departs every workspace of the user as `ended` and its links are detached.
+   * Returns the memberships it ended. Per-workspace supervision failures are reported, not thrown.
+   */
+  async sessionEnded(userID: string, sessionID: string): Promise<WorkspaceMember[]> {
+    const ended = await this.deps.members.sessionEnded(userID, sessionID)
+    for (const member of ended) {
+      const out: EventInput[] = [memberLeftEvent(member)]
+      try {
+        const result = await this.deps.supervision.memberDeparted(userID, member.workspaceID, member.id)
+        if (touched(result)) out.push(supervisionDepartedEvent(member.id, result))
+      } catch (cause) {
+        this.report(cause)
+      }
+      await this.emit(userID, ...out)
+    }
+    return ended
+  }
+}