@huynle/hub 0.7.4 → 0.8.1

package/src/central/artifacts/store.ts

@@ -0,0 +1,776 @@
+// Persistent artifacts (HWA-20; contract docs/plans/2026-10-30-hub-workspaces-artifacts-contracts.md, Artifacts):
+// versioned per-user metadata and immutable revisions in the StateStore, bytes in a BlobStore. Not LaunchArtifacts
+// (launch git metadata): these records have their own collections and lifecycle, so launch pruning and session or
+// launch expiry never touch them.
+//
+// Storage, per user (the tenant key):
+// - "artifacts" (ARTIFACTS): artifactID → { artifact, head, archivedAt?, deletingAt? }. `head` is the number of
+//   the latest revision; `artifact.revision` is the record's CAS counter (every change, including a new revision).
+// - "artifact-revisions.<artifactID>": zero-padded revision number → ArtifactRevision (immutable). Only numbers up
+//   to `head` are visible; a higher one is an upload that has not committed (or never will).
+// - "artifact-blob-refs" (BLOB_REFS): hash → { holders }. A holder is an artifact ID (a published revision of it
+//   uses the blob) or `<artifactID>/<revisionID>` (an upload in flight). A blob without holders is unreferenced.
+// - "artifact-uploads" (UPLOADS): revisionID → the upload in flight (phase storing → publishing).
+//
+// Commit before publish. A new revision (create or revise) is published in this order:
+//   1. record the upload; 2. store each file's bytes (the BlobStore verifies size, quota and hash) and add the
+//   upload's holder to its blob; 3. touch every blob (fails if one vanished); 4. claim the publishing phase (CAS on
+//   the upload); 5. write the revision record (create-only); 6. CAS the artifact to point at it: the only step that
+//   makes the revision visible; 7. turn the upload's holders into artifact holders and drop the upload record.
+// Every stored file of a bundle records progress on the upload, so the grace period below is an inactivity limit.
+// A failure before 6 that is known not to have committed cleans up at once. A failure whose outcome is unknown (a
+// lost reply on step 6) leaves everything for recover(), which after the grace period decides from the artifact
+// record whether the revision was published, and finishes or undoes it.
+//
+// Deleting bytes. Removing a blob's last holder is followed by BlobStore.delete(hash, {touchedBefore: readTime -
+// grace}). A writer always adds its holder before touching the blob, so a writer the deleter could not see has
+// touched it later than that and keeps it; bytes that were stored but never referenced (a failed upload) are
+// removed by recover() once untouched for the grace period. The grace period also covers clock skew between hub
+// replicas.
+//
+// Lifecycle: archive is reversible and keeps everything; delete is irreversible (tombstone first, so a crash half
+// way is finished by recover()); archived artifacts are purged only when `archivedRetentionMs` is set (default:
+// kept until deleted).
+import { randomBytes } from "node:crypto"
+import {
+  ARTIFACT_LIMITS,
+  ARTIFACT_MEDIA_TYPES,
+  artifactInputProblem,
+  blobRefProblem,
+  ID_PREFIXES,
+  type IdKind,
+  isContractID,
+  isExpectedRevision,
+  LIST_LIMIT_DEFAULT,
+  LIST_LIMIT_MAX,
+  type Artifact,
+  type ArtifactKind,
+  type ArtifactRevision,
+  type ArtifactVisibility,
+  type BlobRef,
+  type Page,
+  type RecordState,
+} from "../../protocol"
+import { AgentError } from "../agent/errors"
+import type { Clock, StateStore } from "../backend/types"
+import { type ArtifactAction, type ArtifactAuthorizer, type ArtifactPrincipal, type ArtifactWorkspaces, defaultArtifactPolicy } from "./access"
+import { type BlobBody, BlobHashMismatchError, BlobInputError, BlobQuotaError, type BlobRead, type BlobStore, BlobTooLargeError } from "./blob-store"
+
+export type { ArtifactPrincipal, ArtifactWorkspaces } from "./access"
+
+export const ARTIFACTS = "artifacts"
+export const BLOB_REFS = "artifact-blob-refs"
+export const UPLOADS = "artifact-uploads"
+export const revisionsCollection = (artifactID: string): string => `artifact-revisions.${artifactID}`
+/** How long an upload may run, and an unreferenced blob stays, before recovery treats it as abandoned. */
+export const ARTIFACT_GRACE_MS = 15 * 60_000
+/** CAS attempts on the artifact record when unrelated changes race a commit. */
+const ATTEMPTS = 16
+
+export interface ArtifactLimits {
+  readonly artifactsPerUser: number
+  readonly revisionsPerArtifact: number
+  readonly blobBytes: number
+  readonly userBlobBytes: number
+  readonly bundleFiles: number
+}
+
+/** Compact event payload: IDs, kinds, revisions and counts only (never titles or content). */
+export interface ArtifactEvent {
+  readonly type: "artifact.created" | "artifact.revised" | "artifact.archived" | "artifact.visibility"
+  readonly artifactID: string
+  readonly kind: ArtifactKind
+  readonly revision: number
+  readonly revisionID?: string
+  readonly number?: number
+  /** artifact.archived: the state it moved to (archive and unarchive share the event). */
+  readonly state?: RecordState
+}
+
+export interface ArtifactStoreOptions {
+  readonly state: StateStore
+  readonly blobs: BlobStore
+  readonly now?: Clock
+  /** Workspace facts; without them workspace visibility is `unsupported`. */
+  readonly workspaces?: ArtifactWorkspaces
+  /** Access policy (default: defaultArtifactPolicy). */
+  readonly authorize?: ArtifactAuthorizer
+  /** Tighter limits than ARTIFACT_LIMITS (never looser for blobBytes). */
+  readonly limits?: Partial<ArtifactLimits>
+  readonly graceMs?: number
+  /** Purge archived artifacts this long after archiving (default: never). */
+  readonly archivedRetentionMs?: number
+  readonly onEvent?: (userID: string, event: ArtifactEvent) => void
+  readonly newID?: (kind: IdKind) => string
+}
+
+/** A file of a new revision: new bytes, or a blob this user already stored (unchanged bundle files). */
+export type RevisionFile =
+  | { readonly body: BlobBody; readonly mediaType: string; readonly path?: string; readonly expectedHash?: string }
+  | { readonly ref: BlobRef }
+
+export interface RevisionInput {
+  readonly files: readonly RevisionFile[]
+  /** Entry file of a bundle: one of the files' paths. */
+  readonly entry?: string
+}
+
+export interface ArtifactInput {
+  readonly title: string
+  readonly kind: string
+  readonly description?: string
+  readonly visibility?: ArtifactVisibility
+  readonly workspaceID?: string
+  readonly tags?: readonly string[]
+  readonly metadata?: Readonly<Record<string, string>>
+}
+
+export interface ArtifactUpdate {
+  readonly expectedRevision: number
+  readonly title?: string
+  readonly description?: string
+  readonly tags?: readonly string[]
+  readonly metadata?: Readonly<Record<string, string>>
+}
+
+export interface ArtifactListOptions {
+  readonly limit?: number
+  readonly cursor?: string
+  /** Default "active". */
+  readonly state?: RecordState
+  readonly workspaceID?: string
+}
+
+export interface RecoveryReport {
+  readonly artifactsDeleted: number
+  readonly uploadsRecovered: number
+  readonly revisionsRemoved: number
+  readonly holdersRemoved: number
+  readonly blobsDeleted: number
+}
+
+interface StoredArtifact {
+  readonly artifact: Artifact
+  readonly head: number
+  readonly archivedAt?: number
+  readonly deletingAt?: number
+}
+
+interface Holder {
+  readonly id: string
+  readonly at: number
+}
+
+interface StoredRefs {
+  readonly holders: readonly Holder[]
+}
+
+interface Upload {
+  readonly artifactID: string
+  readonly revisionID: string
+  readonly number: number
+  readonly phase: "storing" | "publishing"
+  readonly startedAt: number
+  readonly phaseAt: number
+}
+
+type Published = { readonly artifact: Artifact; readonly revision: ArtifactRevision }
+
+const ID_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
+const randomID = (kind: IdKind): string => `${ID_PREFIXES[kind]}_${[...randomBytes(24)].map((b) => ID_ALPHABET[b % ID_ALPHABET.length]).join("")}`
+const revisionKey = (number: number): string => String(number).padStart(6, "0")
+const pendingHolder = (artifactID: string, revisionID: string): string => `${artifactID}/${revisionID}`
+/** Any placeholder hash: request checks of a file's media type and path happen before its bytes are read. */
+const NO_HASH = `sha256:${"0".repeat(64)}`
+
+const notFound = (): AgentError => new AgentError("not_found", "No such artifact")
+const forbidden = (): AgentError => new AgentError("forbidden", "Not allowed on this artifact")
+const invalid = (message: string): AgentError => new AgentError("invalid", message)
+const conflict = (message: string, stored: StoredArtifact | undefined): AgentError =>
+  new AgentError("conflict", message, {
+    extra: { currentRevision: stored?.artifact.revision ?? 0, ...(stored ? { latestRevisionID: stored.artifact.latestRevisionID } : {}) },
+  })
+const capReached = (what: string, limit: number): AgentError => new AgentError("rate_limited", `${what} limit of ${limit} reached`, { extra: { limit } })
+
+const encodeCursor = (value: unknown): string => Buffer.from(JSON.stringify(value), "utf8").toString("base64url")
+function decodeCursor(cursor: string): unknown {
+  try {
+    return JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"))
+  } catch {
+    throw invalid("cursor is not valid")
+  }
+}
+function pageLimit(limit: number | undefined): number {
+  const value = limit ?? LIST_LIMIT_DEFAULT
+  if (!Number.isSafeInteger(value) || value < 1 || value > LIST_LIMIT_MAX) throw invalid(`limit must be 1–${LIST_LIMIT_MAX}`)
+  return value
+}
+
+export class ArtifactStore {
+  private readonly state: StateStore
+  private readonly blobs: BlobStore
+  private readonly now: Clock
+  private readonly workspaces: ArtifactWorkspaces | undefined
+  private readonly authorize: ArtifactAuthorizer
+  private readonly limits: ArtifactLimits
+  private readonly graceMs: number
+  private readonly archivedRetentionMs: number | undefined
+  private readonly onEvent: ((userID: string, event: ArtifactEvent) => void) | undefined
+  private readonly newID: (kind: IdKind) => string
+
+  constructor(options: ArtifactStoreOptions) {
+    this.state = options.state
+    this.blobs = options.blobs
+    this.now = options.now ?? Date.now
+    this.workspaces = options.workspaces
+    this.authorize = options.authorize ?? defaultArtifactPolicy
+    this.limits = { ...ARTIFACT_LIMITS, ...options.limits }
+    if (this.limits.blobBytes > ARTIFACT_LIMITS.blobBytes) throw new Error("limits.blobBytes exceeds ARTIFACT_LIMITS.blobBytes")
+    this.graceMs = options.graceMs ?? ARTIFACT_GRACE_MS
+    this.archivedRetentionMs = options.archivedRetentionMs
+    this.onEvent = options.onEvent
+    this.newID = options.newID ?? randomID
+  }
+
+  // ---- reads ----------------------------------------------------------------------------------------------
+
+  async get(userID: string, principal: ArtifactPrincipal, id: string): Promise<Artifact> {
+    return (await this.load(userID, principal, id, "read")).stored.artifact
+  }
+
+  /** The artifacts the principal may read, most recently updated first. */
+  async list(userID: string, principal: ArtifactPrincipal, options: ArtifactListOptions = {}): Promise<Page<Artifact>> {
+    const limit = pageLimit(options.limit)
+    let after: { updatedAt: number; id: string } | undefined
+    if (options.cursor !== undefined) {
+      const raw = decodeCursor(options.cursor)
+      if (!Array.isArray(raw) || typeof raw[0] !== "number" || typeof raw[1] !== "string") throw invalid("cursor is not valid")
+      after = { updatedAt: raw[0], id: raw[1] }
+    }
+    const state = options.state ?? "active"
+    const candidates = (await this.state.list<StoredArtifact>(userID, ARTIFACTS))
+      .map((entry) => entry.value)
+      .filter((s) => s.deletingAt === undefined && s.artifact.state === state)
+      .filter((s) => options.workspaceID === undefined || s.artifact.workspaceID === options.workspaceID)
+      .map((s) => s.artifact)
+      .sort((a, b) => b.updatedAt - a.updatedAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+      .filter((a) => !after || a.updatedAt < after.updatedAt || (a.updatedAt === after.updatedAt && a.id > after.id))
+    const items: Artifact[] = []
+    let more = false
+    for (const artifact of candidates) {
+      if (!(await this.allowed(userID, principal, "read", artifact))) continue
+      if (items.length === limit) {
+        more = true
+        break
+      }
+      items.push(artifact)
+    }
+    const last = items[items.length - 1]
+    return more && last ? { items, cursor: encodeCursor([last.updatedAt, last.id]) } : { items }
+  }
+
+  /** The visible revisions, newest first. */
+  async listRevisions(userID: string, principal: ArtifactPrincipal, id: string, options: { limit?: number; cursor?: string } = {}): Promise<Page<ArtifactRevision>> {
+    const limit = pageLimit(options.limit)
+    let before = Infinity
+    if (options.cursor !== undefined) {
+      const raw = decodeCursor(options.cursor)
+      if (typeof raw !== "number" || !Number.isSafeInteger(raw) || raw < 1) throw invalid("cursor is not valid")
+      before = raw
+    }
+    const { stored } = await this.load(userID, principal, id, "read")
+    const visible = (await this.visibleRevisions(userID, stored)).filter((r) => r.number < before)
+    const items = visible.slice(0, limit)
+    const last = items[items.length - 1]
+    return visible.length > limit && last ? { items, cursor: encodeCursor(last.number) } : { items }
+  }
+
+  async getRevision(userID: string, principal: ArtifactPrincipal, id: string, revisionID: string): Promise<ArtifactRevision> {
+    const { stored } = await this.load(userID, principal, id, "read")
+    if (!isContractID("revision", revisionID)) throw new AgentError("not_found", "No such revision")
+    const revision = (await this.visibleRevisions(userID, stored)).find((r) => r.id === revisionID)
+    if (!revision) throw new AgentError("not_found", "No such revision")
+    return revision
+  }
+
+  /** One blob of a visible revision, checked against that revision's references. */
+  async readBlob(userID: string, principal: ArtifactPrincipal, id: string, revisionID: string, hash: string): Promise<{ ref: BlobRef; blob: BlobRead }> {
+    const revision = await this.getRevision(userID, principal, id, revisionID)
+    const ref = revision.blobs.find((b) => b.hash === hash)
+    if (!ref) throw new AgentError("not_found", "No such blob in this revision")
+    const blob = await this.blobs.get(userID, hash)
+    // Bytes are stored before a revision is published and kept while it exists: a miss is a broken store.
+    if (!blob) throw new AgentError("internal", "The artifact's bytes are missing")
+    return { ref, blob }
+  }
+
+  // ---- revisions ------------------------------------------------------------------------------------------
+
+  /** Creates an artifact with its first revision; the artifact appears only after the revision's bytes are stored. */
+  async create(userID: string, principal: ArtifactPrincipal, input: ArtifactInput, revision: RevisionInput): Promise<Published> {
+    const problem = artifactInputProblem(input)
+    if (problem) throw invalid(problem)
+    if (input.workspaceID !== undefined) await this.checkWorkspace(userID, input.workspaceID)
+    if (!(await this.allowed(userID, principal, "create"))) throw forbidden()
+    this.checkRevisionInput(revision)
+    const live = (await this.state.list<StoredArtifact>(userID, ARTIFACTS)).filter((e) => e.value.deletingAt === undefined)
+    if (live.length >= this.limits.artifactsPerUser) throw capReached("Artifact", this.limits.artifactsPerUser)
+    const artifactID = this.newID("artifact")
+    const published = await this.publish(userID, artifactID, 1, undefined, revision, authorOf(principal), async (rev) => {
+      const at = rev.createdAt
+      const artifact: Artifact = {
+        v: 1,
+        id: artifactID,
+        revision: 1,
+        title: input.title,
+        ...(input.description !== undefined ? { description: input.description } : {}),
+        kind: input.kind as ArtifactKind,
+        state: "active",
+        visibility: input.visibility ?? "private",
+        ...(input.workspaceID !== undefined ? { workspaceID: input.workspaceID } : {}),
+        ...(principal.kind === "session" ? { createdBySessionID: principal.sessionID } : {}),
+        latestRevisionID: rev.id,
+        ...(input.tags !== undefined ? { tags: [...input.tags] } : {}),
+        ...(input.metadata !== undefined ? { metadata: { ...input.metadata } } : {}),
+        createdAt: at,
+        updatedAt: at,
+      }
+      const written = await this.state.put<StoredArtifact>(userID, ARTIFACTS, artifactID, { artifact, head: 1 }, { ifVersion: 0 })
+      if (!written.ok) throw conflict("Artifact ID collision; retry", undefined)
+      return artifact
+    })
+    this.emit(userID, { type: "artifact.created", artifactID, kind: published.artifact.kind, revision: 1, revisionID: published.revision.id, number: 1 })
+    return published
+  }
+
+  /** Adds a revision on `baseRevisionID`, which must be the latest (else 409 conflict; there is no silent merge). */
+  async revise(
+    userID: string,
+    principal: ArtifactPrincipal,
+    id: string,
+    input: RevisionInput & { readonly baseRevisionID: string },
+    options: { readonly aiJobID?: string } = {},
+  ): Promise<Published> {
+    const { stored } = await this.load(userID, principal, id, "revise")
+    if (stored.artifact.state === "archived") throw invalid("The artifact is archived; unarchive it first")
+    const base = input.baseRevisionID
+    if (stored.artifact.latestRevisionID !== base) throw conflict("baseRevisionID is not the latest revision", stored)
+    const number = stored.head + 1
+    if (number > this.limits.revisionsPerArtifact) throw capReached("Revision", this.limits.revisionsPerArtifact)
+    if (options.aiJobID !== undefined && !isContractID("aiJob", options.aiJobID)) throw invalid("aiJobID must be a job ID")
+    this.checkRevisionInput(input)
+    const author: ArtifactRevision["author"] = options.aiJobID !== undefined ? { kind: "ai_job", jobID: options.aiJobID } : authorOf(principal)
+    const published = await this.publish(userID, id, number, base, input, author, async (rev) => {
+      for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+        const current = await this.state.get<StoredArtifact>(userID, ARTIFACTS, id)
+        if (!current || current.value.deletingAt !== undefined) throw notFound()
+        if (current.value.artifact.state === "archived") throw invalid("The artifact is archived; unarchive it first")
+        if (current.value.artifact.latestRevisionID !== base) throw conflict("baseRevisionID is not the latest revision", current.value)
+        const artifact: Artifact = { ...current.value.artifact, latestRevisionID: rev.id, revision: current.value.artifact.revision + 1, updatedAt: rev.createdAt }
+        const written = await this.state.put<StoredArtifact>(userID, ARTIFACTS, id, { ...current.value, artifact, head: rev.number }, { ifVersion: current.version })
+        if (written.ok) return artifact
+      }
+      throw conflict("The artifact kept changing; retry", undefined)
+    })
+    this.emit(userID, { type: "artifact.revised", artifactID: id, kind: published.artifact.kind, revision: published.artifact.revision, revisionID: published.revision.id, number })
+    return published
+  }
+
+  // ---- metadata and lifecycle -----------------------------------------------------------------------------
+
+  async update(userID: string, principal: ArtifactPrincipal, id: string, input: ArtifactUpdate): Promise<Artifact> {
+    return this.mutate(userID, principal, id, input.expectedRevision, async (s) => {
+      const a = s.artifact
+      const next = {
+        title: input.title ?? a.title,
+        description: input.description ?? a.description,
+        kind: a.kind,
+        visibility: a.visibility,
+        workspaceID: a.workspaceID,
+        tags: input.tags ?? a.tags,
+        metadata: input.metadata ?? a.metadata,
+      }
+      const problem = artifactInputProblem(dropUndefined(next))
+      if (problem) throw invalid(problem)
+      return { ...s, artifact: dropUndefined({ ...a, ...next, tags: next.tags && [...next.tags], metadata: next.metadata && { ...next.metadata } }) as Artifact }
+    })
+  }
+
+  async setVisibility(
+    userID: string,
+    principal: ArtifactPrincipal,
+    id: string,
+    input: { readonly expectedRevision: number; readonly visibility: ArtifactVisibility; readonly workspaceID?: string },
+  ): Promise<Artifact> {
+    const artifact = await this.mutate(userID, principal, id, input.expectedRevision, async (s) => {
+      const workspaceID = input.workspaceID ?? s.artifact.workspaceID
+      const problem = artifactInputProblem(dropUndefined({ title: s.artifact.title, kind: s.artifact.kind, visibility: input.visibility, workspaceID }))
+      if (problem) throw invalid(problem)
+      // Making an artifact private never needs the workspace directory; sharing or moving it does.
+      if (workspaceID !== undefined && (input.visibility === "workspace" || workspaceID !== s.artifact.workspaceID)) await this.checkWorkspace(userID, workspaceID)
+      return { ...s, artifact: dropUndefined({ ...s.artifact, visibility: input.visibility, workspaceID }) as Artifact }
+    })
+    this.emit(userID, { type: "artifact.visibility", artifactID: id, kind: artifact.kind, revision: artifact.revision })
+    return artifact
+  }
+
+  async archive(userID: string, principal: ArtifactPrincipal, id: string, expectedRevision: number): Promise<Artifact> {
+    return this.setState(userID, principal, id, expectedRevision, "archived")
+  }
+
+  async unarchive(userID: string, principal: ArtifactPrincipal, id: string, expectedRevision: number): Promise<Artifact> {
+    return this.setState(userID, principal, id, expectedRevision, "active")
+  }
+
+  /** Irreversible: removes the artifact, its revisions and its blob references (unreferenced bytes go too). */
+  async delete(userID: string, principal: ArtifactPrincipal, id: string, expectedRevision: number): Promise<void> {
+    await this.mutate(userID, principal, id, expectedRevision, async (s) => ({ ...s, deletingAt: this.now() }))
+    await this.finishDelete(userID, id)
+  }
+
+  /** Purges archived artifacts older than archivedRetentionMs (none when unset); resolves with their IDs. */
+  async purgeArchived(userID: string): Promise<string[]> {
+    if (this.archivedRetentionMs === undefined) return []
+    const cutoff = this.now() - this.archivedRetentionMs
+    const purged: string[] = []
+    for (const entry of await this.state.list<StoredArtifact>(userID, ARTIFACTS)) {
+      const s = entry.value
+      if (s.deletingAt !== undefined || s.artifact.state !== "archived" || s.archivedAt === undefined || s.archivedAt > cutoff) continue
+      const marked = await this.state.put<StoredArtifact>(userID, ARTIFACTS, entry.key, { ...s, deletingAt: this.now() }, { ifVersion: entry.version })
+      if (!marked.ok) continue
+      await this.finishDelete(userID, entry.key)
+      purged.push(entry.key)
+    }
+    return purged
+  }
+
+  // ---- recovery -------------------------------------------------------------------------------------------
+
+  /**
+   * Settles what crashed or lost writers left behind, for one user: finishes deletes, decides stale uploads
+   * (published: keep and finalize; not: remove the record and holders), drops dangling holders, and removes
+   * blobs without holders that nobody touched for the grace period. Safe to run any time and concurrently.
+   */
+  async recover(userID: string): Promise<RecoveryReport> {
+    let artifactsDeleted = 0
+    let uploadsRecovered = 0
+    let revisionsRemoved = 0
+    let holdersRemoved = 0
+    let blobsDeleted = 0
+    for (const entry of await this.state.list<StoredArtifact>(userID, ARTIFACTS)) {
+      if (entry.value.deletingAt === undefined) continue
+      await this.finishDelete(userID, entry.key)
+      artifactsDeleted++
+    }
+    const stale = this.now() - this.graceMs
+    for (const entry of await this.state.list<Upload>(userID, UPLOADS)) {
+      const upload = entry.value
+      if (upload.phaseAt > stale) continue
+      // Taking the record first: a writer still alive fails its next CAS on it instead of racing us.
+      if (!(await this.state.delete(userID, UPLOADS, entry.key, { ifVersion: entry.version })).ok) continue
+      uploadsRecovered++
+      const published = await this.isPublished(userID, upload)
+      const holder = pendingHolder(upload.artifactID, upload.revisionID)
+      for (const ref of await this.state.list<StoredRefs>(userID, BLOB_REFS)) {
+        if (!ref.value.holders.some((h) => h.id === holder)) continue
+        await this.changeHolders(userID, ref.key, (holders) => [...holders.filter((h) => h.id !== holder && h.id !== upload.artifactID), ...(published ? [{ id: upload.artifactID, at: this.now() }] : [])])
+      }
+      if (!published && (await this.removeRevisionRecord(userID, upload))) revisionsRemoved++
+    }
+    const uploads = new Set((await this.state.list<Upload>(userID, UPLOADS)).map((e) => e.key))
+    const artifacts = new Set((await this.state.list<StoredArtifact>(userID, ARTIFACTS)).map((e) => e.key))
+    for (const ref of await this.state.list<StoredRefs>(userID, BLOB_REFS)) {
+      // Only holders older than the grace period: a fresh one may belong to a write after our snapshots.
+      const dangling = (h: Holder): boolean => {
+        if (h.at > stale) return false
+        const slash = h.id.indexOf("/")
+        return slash < 0 ? !artifacts.has(h.id) : !uploads.has(h.id.slice(slash + 1))
+      }
+      if (!ref.value.holders.some(dangling)) continue
+      const before = ref.value.holders.length
+      const left = await this.changeHolders(userID, ref.key, (holders) => holders.filter((h) => !dangling(h)))
+      holdersRemoved += Math.max(0, before - left)
+    }
+    let cursor: string | undefined
+    do {
+      const page = await this.blobs.list(userID, { limit: LIST_LIMIT_MAX, ...(cursor !== undefined ? { cursor } : {}) })
+      for (const blob of page.items) if (await this.deleteIfUnreferenced(userID, blob.hash)) blobsDeleted++
+      cursor = page.cursor
+    } while (cursor !== undefined)
+    return { artifactsDeleted, uploadsRecovered, revisionsRemoved, holdersRemoved, blobsDeleted }
+  }
+
+  // ---- internals ------------------------------------------------------------------------------------------
+
+  /** The steps of "commit before publish" (see the header); `commit` is step 6 and the only publishing write. */
+  private async publish(
+    userID: string,
+    artifactID: string,
+    number: number,
+    baseRevisionID: string | undefined,
+    input: RevisionInput,
+    author: ArtifactRevision["author"],
+    commit: (revision: ArtifactRevision) => Promise<Artifact>,
+  ): Promise<Published> {
+    const revisionID = this.newID("revision")
+    const startedAt = this.now()
+    const upload: Upload = { artifactID, revisionID, number, phase: "storing", startedAt, phaseAt: startedAt }
+    const recorded = await this.state.put<Upload>(userID, UPLOADS, revisionID, upload, { ifVersion: 0 })
+    if (!recorded.ok) throw conflict("Revision ID collision; retry", undefined)
+    let uploadVersion = recorded.version
+    /** Keeps the upload alive: the grace period counts from its latest progress, not its start. */
+    const progress = async (phase: Upload["phase"]): Promise<number> => {
+      const at = this.now()
+      const written = await this.state.put<Upload>(userID, UPLOADS, revisionID, { ...upload, phase, phaseAt: at }, { ifVersion: uploadVersion })
+      if (!written.ok) throw conflict("The upload expired; retry", undefined)
+      uploadVersion = written.version
+      return at
+    }
+    const holder = pendingHolder(artifactID, revisionID)
+    const held = new Set<string>()
+    /** Past step 6's write: its outcome may be unknown, so only recover() may undo anything. */
+    let committing = false
+    try {
+      const refs: BlobRef[] = []
+      for (const file of input.files) {
+        const ref = await this.storeFile(userID, file)
+        if (!held.has(ref.hash)) {
+          await this.changeHolders(userID, ref.hash, (holders) => [...holders.filter((h) => h.id !== holder), { id: holder, at: this.now() }])
+          held.add(ref.hash)
+        }
+        refs.push(ref)
+        if (input.files.length > 1) await progress("storing")
+      }
+      for (const hash of held) {
+        if (!(await this.blobs.touch(userID, hash))) throw conflict("A blob was removed during the upload; retry", undefined)
+      }
+      const publishingAt = await progress("publishing")
+      const revision: ArtifactRevision = {
+        v: 1,
+        id: revisionID,
+        artifactID,
+        number,
+        ...(baseRevisionID !== undefined ? { baseRevisionID } : {}),
+        blobs: refs,
+        ...(input.entry !== undefined ? { entry: input.entry } : {}),
+        author,
+        createdAt: publishingAt,
+      }
+      await this.writeRevision(userID, revision)
+      if (this.now() - publishingAt > this.graceMs / 2) throw conflict("The upload expired; retry", undefined)
+      committing = true
+      let artifact: Artifact
+      try {
+        artifact = await commit(revision)
+      } catch (error) {
+        // An AgentError is a decided refusal (nothing written); anything else may have committed.
+        if (error instanceof AgentError) committing = false
+        throw error
+      }
+      try {
+        for (const hash of held) {
+          await this.changeHolders(userID, hash, (holders) => [...holders.filter((h) => h.id !== holder && h.id !== artifactID), { id: artifactID, at: this.now() }])
+        }
+        await this.state.delete(userID, UPLOADS, revisionID)
+      } catch {
+        // Published already; recover() finalizes the holders and the upload record after the grace period.
+      }
+      return { artifact, revision }
+    } catch (error) {
+      if (!committing) await this.abandon(userID, upload, held).catch(() => {})
+      throw error
+    }
+  }
+
+  /** Undoes an upload known not to have committed: its record, its holders and its revision record. */
+  private async abandon(userID: string, upload: Upload, held: Iterable<string>): Promise<void> {
+    const holder = pendingHolder(upload.artifactID, upload.revisionID)
+    for (const hash of held) await this.changeHolders(userID, hash, (holders) => holders.filter((h) => h.id !== holder))
+    await this.removeRevisionRecord(userID, upload)
+    await this.state.delete(userID, UPLOADS, upload.revisionID)
+  }
+
+  /** Writes the revision record create-only; replaces a stale one left by a crashed writer, else 409 conflict. */
+  private async writeRevision(userID: string, revision: ArtifactRevision): Promise<void> {
+    const collection = revisionsCollection(revision.artifactID)
+    const key = revisionKey(revision.number)
+    for (let attempt = 0; attempt < 2; attempt++) {
+      if ((await this.state.put(userID, collection, key, revision, { ifVersion: 0 })).ok) return
+      const existing = await this.state.get<ArtifactRevision>(userID, collection, key)
+      if (!existing) continue
+      const stored = (await this.state.get<StoredArtifact>(userID, ARTIFACTS, revision.artifactID))?.value
+      if (stored && stored.head >= revision.number) throw conflict("baseRevisionID is not the latest revision", stored)
+      const other = (await this.state.get<Upload>(userID, UPLOADS, existing.value.id))?.value
+      if (other && other.phaseAt > this.now() - this.graceMs) throw conflict("Another revision on this base is being published", stored)
+      await this.state.delete(userID, collection, key, { ifVersion: existing.version })
+    }
+    throw conflict("Another revision on this base is being published", undefined)
+  }
+
+  private async removeRevisionRecord(userID: string, upload: Upload): Promise<boolean> {
+    const collection = revisionsCollection(upload.artifactID)
+    const key = revisionKey(upload.number)
+    const existing = await this.state.get<ArtifactRevision>(userID, collection, key)
+    if (existing?.value.id !== upload.revisionID) return false
+    const stored = (await this.state.get<StoredArtifact>(userID, ARTIFACTS, upload.artifactID))?.value
+    if (stored && stored.head >= upload.number && stored.deletingAt === undefined) return false
+    return (await this.state.delete(userID, collection, key, { ifVersion: existing.version })).ok
+  }
+
+  private async isPublished(userID: string, upload: Upload): Promise<boolean> {
+    const stored = (await this.state.get<StoredArtifact>(userID, ARTIFACTS, upload.artifactID))?.value
+    if (!stored || stored.deletingAt !== undefined || stored.head < upload.number) return false
+    const record = await this.state.get<ArtifactRevision>(userID, revisionsCollection(upload.artifactID), revisionKey(upload.number))
+    return record?.value.id === upload.revisionID
+  }
+
+  /** Stores one file's bytes (or checks a reused blob) and answers its reference; BlobStore errors become agent errors. */
+  private async storeFile(userID: string, file: RevisionFile): Promise<BlobRef> {
+    if ("ref" in file) {
+      const info = await this.blobs.stat(userID, file.ref.hash)
+      if (!info || info.bytes !== file.ref.bytes) throw invalid(`blob ${file.ref.hash} is not stored`)
+      return { hash: file.ref.hash, bytes: file.ref.bytes, mediaType: file.ref.mediaType, ...(file.ref.path !== undefined ? { path: file.ref.path } : {}) }
+    }
+    try {
+      const ref = await this.blobs.put(userID, file.body, file.mediaType, {
+        maxBytes: this.limits.blobBytes,
+        quotaBytes: this.limits.userBlobBytes,
+        ...(file.expectedHash !== undefined ? { expectedHash: file.expectedHash } : {}),
+      })
+      return { ...ref, ...(file.path !== undefined ? { path: file.path } : {}) }
+    } catch (error) {
+      if (error instanceof BlobQuotaError) throw capReached("Blob storage", error.quotaBytes)
+      if (error instanceof BlobTooLargeError || error instanceof BlobHashMismatchError || error instanceof BlobInputError) throw invalid(error.message)
+      throw error
+    }
+  }
+
+  /** Request checks before any bytes are read: counts, media types, paths, the entry. */
+  private checkRevisionInput(input: RevisionInput): void {
+    const files = input.files
+    if (!Array.isArray(files) || files.length < 1) throw invalid("a revision needs at least one file")
+    if (files.length > this.limits.bundleFiles) throw invalid(`a revision has at most ${this.limits.bundleFiles} files`)
+    const paths = new Set<string>()
+    for (const file of files) {
+      const ref = "ref" in file ? file.ref : { hash: file.expectedHash ?? NO_HASH, bytes: 0, mediaType: file.mediaType, ...(file.path !== undefined ? { path: file.path } : {}) }
+      const problem = blobRefProblem(ref)
+      if (problem) throw invalid(problem)
+      if (!(ARTIFACT_MEDIA_TYPES as readonly string[]).includes(ref.mediaType)) throw invalid("mediaType is not allowed")
+      if (ref.path !== undefined) {
+        if (paths.has(ref.path)) throw invalid(`path ${ref.path} appears twice`)
+        paths.add(ref.path)
+      } else if (files.length > 1) {
+        throw invalid("every file of a bundle needs a path")
+      }
+    }
+    if (input.entry !== undefined && !paths.has(input.entry)) throw invalid("entry must be the path of one of the files")
+  }
+
+  /** Read-modify-write of the holders of a blob (deleting the record when none are left); resolves with how many are left. */
+  private async changeHolders(userID: string, hash: string, change: (holders: readonly Holder[]) => Holder[]): Promise<number> {
+    for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+      const current = await this.state.get<StoredRefs>(userID, BLOB_REFS, hash)
+      const holders = change(current?.value.holders ?? [])
+      if (holders.length === 0) {
+        if (!current) return 0
+        if ((await this.state.delete(userID, BLOB_REFS, hash, { ifVersion: current.version })).ok) return 0
+      } else if ((await this.state.put<StoredRefs>(userID, BLOB_REFS, hash, { holders }, { ifVersion: current?.version ?? 0 })).ok) {
+        return holders.length
+      }
+    }
+    throw new Error(`blob references of ${hash} kept conflicting`)
+  }
+
+  /** Deletes the bytes when nothing holds them and nobody touched them within the grace period. */
+  private async deleteIfUnreferenced(userID: string, hash: string): Promise<boolean> {
+    const readAt = this.now()
+    const refs = await this.state.get<StoredRefs>(userID, BLOB_REFS, hash)
+    if (refs && refs.value.holders.length > 0) return false
+    return this.blobs.delete(userID, hash, { touchedBefore: readAt - this.graceMs })
+  }
+
+  /** The rest of a delete after the tombstone: holders, unreferenced bytes, revision records, the record. */
+  private async finishDelete(userID: string, artifactID: string): Promise<void> {
+    const collection = revisionsCollection(artifactID)
+    const revisions = await this.state.list<ArtifactRevision>(userID, collection)
+    const hashes = new Set(revisions.flatMap((r) => r.value.blobs.map((b) => b.hash)))
+    for (const hash of hashes) {
+      const left = await this.changeHolders(userID, hash, (holders) => holders.filter((h) => h.id !== artifactID && !h.id.startsWith(`${artifactID}/`)))
+      if (left === 0) await this.deleteIfUnreferenced(userID, hash)
+    }
+    for (const entry of revisions) await this.state.delete(userID, collection, entry.key)
+    await this.state.delete(userID, ARTIFACTS, artifactID)
+  }
+
+  private async setState(userID: string, principal: ArtifactPrincipal, id: string, expectedRevision: number, to: RecordState): Promise<Artifact> {
+    const artifact = await this.mutate(userID, principal, id, expectedRevision, async (s) => {
+      const { archivedAt: _, ...rest } = s
+      return { ...rest, ...(to === "archived" ? { archivedAt: this.now() } : {}), artifact: { ...s.artifact, state: to } }
+    })
+    this.emit(userID, { type: "artifact.archived", artifactID: id, kind: artifact.kind, revision: artifact.revision, state: to })
+    return artifact
+  }
+
+  /** A versioned change of the artifact record by a principal allowed to manage it. */
+  private async mutate(
+    userID: string,
+    principal: ArtifactPrincipal,
+    id: string,
+    expectedRevision: number,
+    change: (stored: StoredArtifact) => Promise<StoredArtifact>,
+  ): Promise<Artifact> {
+    if (!isExpectedRevision(expectedRevision)) throw invalid("expectedRevision must be a non-negative integer")
+    const { stored, version } = await this.load(userID, principal, id, "manage")
+    if (stored.artifact.revision !== expectedRevision) throw conflict("expectedRevision is not the current revision", stored)
+    const changed = await change(stored)
+    const next: StoredArtifact = { ...changed, artifact: { ...changed.artifact, revision: stored.artifact.revision + 1, updatedAt: this.now() } }
+    const written = await this.state.put<StoredArtifact>(userID, ARTIFACTS, id, next, { ifVersion: version })
+    if (!written.ok) {
+      const current = (await this.state.get<StoredArtifact>(userID, ARTIFACTS, id))?.value
+      throw conflict("expectedRevision is not the current revision", current)
+    }
+    return next.artifact
+  }
+
+  /** The record, if the principal may read it (else not_found) and do `action` (else forbidden). */
+  private async load(userID: string, principal: ArtifactPrincipal, id: string, action: ArtifactAction): Promise<{ stored: StoredArtifact; version: number }> {
+    if (!isContractID("artifact", id)) throw notFound()
+    const entry = await this.state.get<StoredArtifact>(userID, ARTIFACTS, id)
+    if (!entry || entry.value.deletingAt !== undefined) throw notFound()
+    if (!(await this.allowed(userID, principal, "read", entry.value.artifact))) throw notFound()
+    if (action !== "read" && !(await this.allowed(userID, principal, action, entry.value.artifact))) throw forbidden()
+    return { stored: entry.value, version: entry.version }
+  }
+
+  private allowed(userID: string, principal: ArtifactPrincipal, action: ArtifactAction, artifact?: Artifact): Promise<boolean> {
+    return this.authorize({ userID, principal, action, ...(artifact ? { artifact } : {}), ...(this.workspaces ? { workspaces: this.workspaces } : {}) })
+  }
+
+  private async visibleRevisions(userID: string, stored: StoredArtifact): Promise<ArtifactRevision[]> {
+    return (await this.state.list<ArtifactRevision>(userID, revisionsCollection(stored.artifact.id)))
+      .map((e) => e.value)
+      .filter((r) => r.number <= stored.head)
+      .sort((a, b) => b.number - a.number)
+  }
+
+  private async checkWorkspace(userID: string, workspaceID: string): Promise<void> {
+    if (!this.workspaces) throw new AgentError("unsupported", "Workspaces are not available on this hub", { extra: { feature: "workspaces" } })
+    if (!(await this.workspaces.exists(userID, workspaceID))) throw invalid("workspaceID is not a workspace of this user")
+  }
+
+  private emit(userID: string, event: ArtifactEvent): void {
+    try {
+      this.onEvent?.(userID, event)
+    } catch {
+      // An event sink never fails the write that happened.
+    }
+  }
+}
+
+function authorOf(principal: ArtifactPrincipal): ArtifactRevision["author"] {
+  return principal.kind === "session" ? { kind: "session", sessionID: principal.sessionID } : { kind: "user" }
+}
+
+function dropUndefined<T extends object>(value: T): T {
+  return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined)) as T
+}