@huynle/hub 0.7.4 → 0.8.1

package/src/central/profiles/store.ts

@@ -0,0 +1,597 @@
+// The versioned profile registry (HWA-14; contract docs/plans/2026-10-30-hub-workspaces-artifacts-contracts.md,
+// packages/protocol/src/profiles.ts). Per user (the StateStore userID is the tenant key; another user's records
+// are simply absent):
+//
+//   profiles                 key prof_…        the AgentProfile plus its internal version history (number, digest,
+//                                              bytes, createdAt), never more than versionsPerProfile entries
+//   profile-index            key "names"       one aggregate {name → {id, at}}: unique names and the count bound
+//   profile-version.<prof_…> key "<n>"         one immutable AgentProfileVersion per collection (one small file each
+//                                              in the file store), written once with ifVersion 0
+//   profile-assignments      key <sessionID>   ProfileAssignment pins (HWA-15 applies them)
+//
+// Concurrency: every mutation names expectedRevision; a mismatch is 409 conflict with currentRevision. A new
+// version races for its number through the version slot (ifVersion 0): the first writer wins and the record is
+// never overwritten. A slot left by a writer that stopped before updating the profile is adopted (healed) by the
+// next writer, which then gets conflict and retries with the new revision. Retention drops the oldest versions
+// no session pins once a profile holds more than versionsPerProfile; when every older version is pinned, a new
+// one is refused (rate_limited). Archiving is reversible; an archived profile takes no versions or new pins.
+// Bounded: profiles per user, versions per profile, bytes of retained versions per user (bytesPerUser).
+import { randomBytes } from "node:crypto"
+import {
+  type AgentProfile,
+  type AgentProfileVersion,
+  DESCRIPTION_MAX,
+  isExpectedRevision,
+  isLabel,
+  isText,
+  LIST_LIMIT_DEFAULT,
+  LIST_LIMIT_MAX,
+  metadataProblem,
+  type Page,
+  PROFILE_APPLY_LIMITS,
+  PROFILE_LIMITS,
+  type ProfileAck,
+  type ProfileAssignment,
+  type ProfileVersionContent,
+  profileInputProblem,
+  profileProjectsProblem,
+  RECORD_STATES,
+  type RecordState,
+  tagsProblem,
+} from "../../protocol"
+import type { Clock, StateStore } from "../backend/types"
+import { AgentError } from "../agent/errors"
+import { updateVersioned } from "../agent/versioned"
+import { checkContent, contentBytes, contentDigest, credentialFinding, ProfileContentError } from "./content"
+
+export const PROFILES = "profiles"
+export const PROFILE_INDEX = "profile-index"
+export const PROFILE_ASSIGNMENTS = "profile-assignments"
+export const versionCollection = (profileID: string): string => `profile-version.${profileID}`
+
+export interface ProfileStoreLimits {
+  readonly profilesPerUser: number
+  readonly versionsPerProfile: number
+  readonly bytesPerUser: number
+  readonly reservationMs: number
+}
+
+export const PROFILE_STORE_LIMITS: ProfileStoreLimits = {
+  profilesPerUser: PROFILE_LIMITS.profilesPerUser,
+  versionsPerProfile: PROFILE_LIMITS.versionsPerProfile,
+  /** Serialized bytes of all retained versions of one user (extension of the frozen limits). */
+  bytesPerUser: 32 * 1024 * 1024,
+  /** A name reservation whose profile never got written is reclaimed after this long. */
+  reservationMs: 60_000,
+}
+
+/** One retained version as the history shows it (never its content). */
+export interface VersionEntry {
+  readonly version: number
+  readonly digest: string
+  readonly bytes: number
+  readonly createdAt: number
+  /** (RP-08) Cached counts of the version's content (absent on entries written before; summaries() reads those). */
+  readonly skills?: number
+  readonly commands?: number
+  readonly instructions?: boolean
+}
+
+/** (RP-08) The latest version of a listed profile, without reading it (list rows). */
+export interface LatestSummary {
+  readonly version: number
+  readonly skills: number
+  readonly commands: number
+  readonly instructions: boolean
+}
+
+const countsOf = (content: ProfileVersionContent) => ({ skills: content.skills.length, commands: content.commands.length, instructions: content.instructions !== undefined })
+
+interface ProfileRecord extends AgentProfile {
+  readonly createdAt: number
+  readonly history: readonly VersionEntry[]
+}
+
+interface NameIndex {
+  readonly v: 1
+  readonly names: Readonly<Record<string, { readonly id: string; readonly at: number }>>
+}
+
+/** The acknowledgment recorded when a pin is stored (HWA-15 plugs in the spoke application). */
+export type AckFor = (userID: string, assignment: ProfileAssignment, version: AgentProfileVersion) => Promise<ProfileAck>
+
+export interface ProfileStoreOptions {
+  readonly state: StateStore
+  readonly now?: Clock
+  readonly limits?: Partial<ProfileStoreLimits>
+  /** Without it a pin is recorded as `unsupported` (this hub does not apply profiles yet), never as applied. */
+  readonly ack?: AckFor
+  readonly newID?: () => string
+}
+
+export interface CreateResult {
+  readonly profile: AgentProfile
+  readonly version: AgentProfileVersion
+}
+
+export interface VersionInput {
+  readonly expectedRevision?: unknown
+  readonly content?: unknown
+  /** Explicit rollback: copy this retained version into a new one. */
+  readonly fromVersion?: unknown
+}
+
+export interface ProfilePatch {
+  readonly expectedRevision?: unknown
+  readonly title?: unknown
+  readonly description?: unknown
+  readonly tags?: unknown
+  readonly state?: unknown
+  /** (RP-08) Replaces the metadata; null clears it. */
+  readonly metadata?: unknown
+  /** (RP-08) Replaces the projects; null clears them. */
+  readonly projects?: unknown
+}
+
+export interface AssignInput {
+  readonly profileID?: unknown
+  readonly version?: unknown
+  readonly expectedRevision?: unknown
+}
+
+export interface ListOptions {
+  readonly state?: string
+  readonly limit?: number
+  readonly cursor?: string
+}
+
+const CREATE_FIELDS = new Set(["name", "title", "description", "tags", "metadata", "projects", "content"])
+const PATCH_FIELDS = new Set(["expectedRevision", "title", "description", "tags", "state", "metadata", "projects"])
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+export const conflict = (message: string, currentRevision: number, extra: Record<string, unknown> = {}): AgentError =>
+  new AgentError("conflict", message, { extra: { ...extra, currentRevision }, hint: "Read the current record and retry with its revision" })
+
+/** A refused content body as the agent error envelope. */
+export function contentError(cause: unknown): unknown {
+  if (!(cause instanceof ProfileContentError)) return cause
+  return cause.code === "unsupported" ? new AgentError("unsupported", cause.message, { extra: { feature: "setupHooks" } }) : new AgentError("invalid", cause.message)
+}
+
+/** Validated, normalized version content; throws the agent error. */
+export function contentOf(v: unknown): ProfileVersionContent {
+  try {
+    return checkContent(v)
+  } catch (cause) {
+    throw contentError(cause)
+  }
+}
+
+function noCredential(field: string, value: unknown): void {
+  if (typeof value !== "string") return
+  const kind = credentialFinding(value)
+  if (kind) throw new AgentError("invalid", `${field} contains what looks like a ${kind}; keep credentials out of profiles`)
+}
+
+/** Metadata values are free text: no credentials in them either. */
+function noCredentialIn(metadata: unknown, projects?: unknown): void {
+  if (typeof metadata === "object" && metadata !== null) for (const [key, value] of Object.entries(metadata)) noCredential(`metadata.${key}`, value)
+  if (Array.isArray(projects)) for (const project of projects) noCredential("projects", project)
+}
+
+function unknownField(body: Record<string, unknown>, allowed: ReadonlySet<string>): void {
+  for (const key of Object.keys(body)) {
+    if (allowed.has(key)) continue
+    if (key === "name") throw new AgentError("invalid", "A profile's name cannot change; create a new profile")
+    throw new AgentError("invalid", `unknown field ${/^[A-Za-z0-9_-]{1,40}$/.test(key) ? key : "(unprintable)"}`)
+  }
+}
+
+const encodeCursor = (value: string | number): string => Buffer.from(JSON.stringify({ k: value })).toString("base64url")
+function decodeCursor(cursor: string | undefined): string | number | undefined {
+  if (cursor === undefined) return undefined
+  try {
+    const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8")) as { k?: unknown }
+    if (typeof parsed.k === "string" || typeof parsed.k === "number") return parsed.k
+  } catch {
+    // answered below
+  }
+  throw new AgentError("invalid", "Bad cursor; start again without one")
+}
+
+function pageLimit(limit: number | undefined): number {
+  if (limit === undefined) return LIST_LIMIT_DEFAULT
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > LIST_LIMIT_MAX) throw new AgentError("invalid", `limit must be 1–${LIST_LIMIT_MAX}`)
+  return limit
+}
+
+/** A profile as the API shows it: the contract record, never the internal history. */
+export function profileView(record: ProfileRecord): AgentProfile {
+  const { history: _history, createdAt: _createdAt, ...profile } = record
+  return profile
+}
+
+export class ProfileStore {
+  readonly state: StateStore
+  private readonly now: Clock
+  readonly limits: ProfileStoreLimits
+  private readonly ack?: AckFor
+  private readonly newID: () => string
+
+  constructor(options: ProfileStoreOptions) {
+    this.state = options.state
+    this.now = options.now ?? Date.now
+    this.limits = { ...PROFILE_STORE_LIMITS, ...options.limits }
+    this.ack = options.ack
+    this.newID = options.newID ?? (() => `prof_${randomBytes(12).toString("hex")}`)
+  }
+
+  // ---------- profiles ----------
+
+  async create(userID: string, body: unknown): Promise<CreateResult> {
+    if (!isRecord(body)) throw new AgentError("invalid", "Body must be a JSON object")
+    unknownField(body, CREATE_FIELDS)
+    const content = contentOf(body.content)
+    const problem = profileInputProblem({ ...body, content })
+    if (problem) throw new AgentError("invalid", problem)
+    noCredential("title", body.title)
+    noCredential("description", body.description)
+    noCredentialIn(body.metadata, body.projects)
+    const name = body.name as string
+    const bytes = contentBytes(content)
+    await this.ensureQuota(userID, bytes)
+
+    const id = this.newID()
+    const now = this.now()
+    await this.reserveName(userID, name, id, now)
+    try {
+      const version: AgentProfileVersion = { v: 1, profileID: id, version: 1, content, digest: contentDigest(content), createdAt: now }
+      const record: ProfileRecord = {
+        v: 1,
+        id,
+        name,
+        title: body.title as string,
+        ...(body.description !== undefined ? { description: body.description as string } : {}),
+        state: "active",
+        ...(body.tags !== undefined ? { tags: [...(body.tags as string[])] } : {}),
+        ...(body.metadata !== undefined ? { metadata: { ...(body.metadata as Record<string, string>) } } : {}),
+        ...(body.projects !== undefined ? { projects: [...(body.projects as string[])] } : {}),
+        latestVersion: 1,
+        revision: 1,
+        updatedAt: now,
+        createdAt: now,
+        history: [{ version: 1, digest: version.digest, bytes, createdAt: now, ...countsOf(content) }],
+      }
+      if (!(await this.state.put(userID, versionCollection(id), "1", version, { ifVersion: 0 })).ok) throw new Error(`profile version slot ${id}/1 already exists`)
+      if (!(await this.state.put(userID, PROFILES, id, record, { ifVersion: 0 })).ok) throw new Error(`profile ${id} already exists`)
+      return { profile: profileView(record), version }
+    } catch (cause) {
+      await this.releaseName(userID, name, id).catch(() => {})
+      throw cause
+    }
+  }
+
+  async get(userID: string, id: string): Promise<AgentProfile | undefined> {
+    const record = await this.record(userID, id)
+    return record && profileView(record)
+  }
+
+  async list(userID: string, options: ListOptions): Promise<Page<AgentProfile>> {
+    const limit = pageLimit(options.limit)
+    const wanted = options.state ?? "active"
+    if (wanted !== "all" && !RECORD_STATES.includes(wanted as RecordState)) throw new AgentError("invalid", "state must be active, archived or all")
+    const after = decodeCursor(options.cursor)
+    const all = (await this.state.list<ProfileRecord>(userID, PROFILES))
+      .map((e) => e.value)
+      .filter((p) => wanted === "all" || p.state === wanted)
+      .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+    const rest = after === undefined ? all : all.filter((p) => p.name > String(after))
+    const items = rest.slice(0, limit)
+    return { items: items.map(profileView), ...(rest.length > limit ? { cursor: encodeCursor(items[items.length - 1]!.name) } : {}) }
+  }
+
+  async update(userID: string, id: string, patch: ProfilePatch): Promise<AgentProfile> {
+    return (await this.updateWithPrior(userID, id, patch)).after
+  }
+
+  /** The update, with the profile before it (the routes announce state changes). */
+  async updateWithPrior(userID: string, id: string, patch: ProfilePatch): Promise<{ before: AgentProfile; after: AgentProfile }> {
+    if (!isRecord(patch)) throw new AgentError("invalid", "Body must be a JSON object")
+    unknownField(patch, PATCH_FIELDS)
+    const expected = this.expected(patch.expectedRevision)
+    if (patch.title !== undefined && !isLabel(patch.title)) throw new AgentError("invalid", "title must be 1–120 characters of text")
+    if (patch.description !== undefined && patch.description !== null && !isText(patch.description, DESCRIPTION_MAX)) throw new AgentError("invalid", `description must be at most ${DESCRIPTION_MAX} characters`)
+    const tags = tagsProblem(patch.tags)
+    if (tags) throw new AgentError("invalid", tags)
+    if (patch.state !== undefined && !RECORD_STATES.includes(patch.state as RecordState)) throw new AgentError("invalid", "state must be active or archived")
+    const extra = (patch.metadata === null ? undefined : metadataProblem(patch.metadata)) ?? (patch.projects === null ? undefined : profileProjectsProblem(patch.projects))
+    if (extra) throw new AgentError("invalid", extra)
+    noCredential("title", patch.title)
+    noCredential("description", patch.description)
+    noCredentialIn(patch.metadata, patch.projects)
+    let before: ProfileRecord | undefined
+    const after = await updateVersioned<ProfileRecord>(this.state, userID, PROFILES, id, (current) => {
+      if (!current) throw notFound(id)
+      if (current.revision !== expected) throw conflict(`Profile ${id} changed (revision ${current.revision})`, current.revision)
+      before = current
+      const { description: _d, metadata: _m, projects: _p, ...rest } = current
+      const description = patch.description === undefined ? current.description : (patch.description as string | null) ?? undefined
+      const metadata = patch.metadata === undefined ? current.metadata : (patch.metadata as Record<string, string> | null) ?? undefined
+      const projects = patch.projects === undefined ? current.projects : (patch.projects as string[] | null) ?? undefined
+      return {
+        ...rest,
+        ...(patch.title !== undefined ? { title: patch.title as string } : {}),
+        ...(description !== undefined ? { description } : {}),
+        ...(metadata !== undefined ? { metadata: { ...metadata } } : {}),
+        ...(projects !== undefined ? { projects: [...projects] } : {}),
+        ...(patch.tags !== undefined ? { tags: [...(patch.tags as string[])] } : {}),
+        ...(patch.state !== undefined ? { state: patch.state as RecordState } : {}),
+        revision: current.revision + 1,
+        updatedAt: this.now(),
+      }
+    })
+    return { before: profileView(before!), after: profileView(after!) }
+  }
+
+  // ---------- versions ----------
+
+  async addVersion(userID: string, id: string, input: VersionInput): Promise<CreateResult> {
+    if (!isRecord(input)) throw new AgentError("invalid", "Body must be a JSON object")
+    const expected = this.expected(input.expectedRevision)
+    if ((input.content === undefined) === (input.fromVersion === undefined)) throw new AgentError("invalid", "Send exactly one of content or fromVersion")
+    const profile = await this.record(userID, id)
+    if (!profile) throw notFound(id)
+    if (profile.revision !== expected) throw conflict(`Profile ${id} changed (revision ${profile.revision})`, profile.revision)
+    if (profile.state !== "active") throw conflict(`Profile ${id} is archived; unarchive it first`, profile.revision, { state: profile.state })
+    let content: ProfileVersionContent
+    if (input.fromVersion !== undefined) {
+      if (!Number.isSafeInteger(input.fromVersion) || (input.fromVersion as number) < 1) throw new AgentError("invalid", "fromVersion must be a version number")
+      const old = await this.version(userID, id, input.fromVersion as number)
+      if (!old) throw new AgentError("not_found", `Profile ${id} has no retained version ${input.fromVersion as number}`)
+      content = old.content
+    } else content = contentOf(input.content)
+    const bytes = contentBytes(content)
+    await this.ensureQuota(userID, bytes)
+
+    // Retention: which older versions go once this one is in (oldest first, never a pinned one).
+    const pinned = await this.pinnedVersions(userID, id)
+    const excess = profile.history.length + 1 - this.limits.versionsPerProfile
+    const candidates = [...profile.history].sort((a, b) => a.version - b.version).filter((h) => !pinned.has(h.version))
+    if (excess > candidates.length) {
+      throw new AgentError("rate_limited", `Profile ${id} already keeps ${profile.history.length} versions and sessions pin the older ones`, { hint: "Unassign an old version from its sessions first" })
+    }
+    const victims = excess > 0 ? candidates.slice(0, excess) : []
+
+    const number = profile.latestVersion + 1
+    const now = this.now()
+    const version: AgentProfileVersion = { v: 1, profileID: id, version: number, content, digest: contentDigest(content), createdAt: now }
+    if (!(await this.state.put(userID, versionCollection(id), String(number), version, { ifVersion: 0 })).ok) {
+      const healed = await this.heal(userID, id)
+      throw conflict(`Profile ${id} got version ${number} from another writer`, healed?.revision ?? profile.revision)
+    }
+    const entry: VersionEntry = { version: number, digest: version.digest, bytes, createdAt: now, ...countsOf(content) }
+    const gone = new Set(victims.map((v) => v.version))
+    const written = await updateVersioned<ProfileRecord>(this.state, userID, PROFILES, id, (current) => {
+      if (!current) return undefined
+      const present = current.history.some((h) => h.version === number)
+      if (present && !victims.length) return undefined
+      const history = [...current.history.filter((h) => !gone.has(h.version) && h.version !== number), entry].sort((a, b) => a.version - b.version)
+      return { ...current, history, latestVersion: Math.max(current.latestVersion, number), revision: current.revision + (present ? 0 : 1), updatedAt: now }
+    })
+    const after = written ?? (await this.record(userID, id))
+    if (!after) throw notFound(id)
+    await this.dropVersions(userID, id, victims)
+    return { profile: profileView(after), version }
+  }
+
+  /** A retained version (pruned or never written: undefined). */
+  async version(userID: string, id: string, number: number): Promise<AgentProfileVersion | undefined> {
+    const profile = await this.record(userID, id)
+    if (!profile || !profile.history.some((h) => h.version === number)) return undefined
+    return (await this.state.get<AgentProfileVersion>(userID, versionCollection(id), String(number)))?.value
+  }
+
+  /**
+   * (RP-08) The latest version's counts for these profiles: one scan of the records, plus one version read only for
+   * a profile whose latest entry predates the cached counts (bounded by the page).
+   */
+  async summaries(userID: string, ids: readonly string[]): Promise<Record<string, LatestSummary>> {
+    const wanted = new Set(ids)
+    const out: Record<string, LatestSummary> = {}
+    for (const { value } of await this.state.list<ProfileRecord>(userID, PROFILES)) {
+      if (!wanted.has(value.id)) continue
+      const entry = value.history.find((h) => h.version === value.latestVersion)
+      if (entry?.skills !== undefined && entry.commands !== undefined) {
+        out[value.id] = { version: value.latestVersion, skills: entry.skills, commands: entry.commands, instructions: entry.instructions === true }
+        continue
+      }
+      const latest = (await this.state.get<AgentProfileVersion>(userID, versionCollection(value.id), String(value.latestVersion)))?.value
+      if (latest) out[value.id] = { version: value.latestVersion, ...countsOf(latest.content) }
+    }
+    return out
+  }
+
+  /** The retained versions, newest first. */
+  async history(userID: string, id: string, options: { limit?: number; cursor?: string }): Promise<Page<VersionEntry>> {
+    const limit = pageLimit(options.limit)
+    const after = decodeCursor(options.cursor)
+    const profile = await this.record(userID, id)
+    if (!profile) throw notFound(id)
+    const all = [...profile.history].sort((a, b) => b.version - a.version)
+    const rest = after === undefined ? all : all.filter((h) => h.version < Number(after))
+    const items = rest.slice(0, limit)
+    return { items, ...(rest.length > limit ? { cursor: encodeCursor(items[items.length - 1]!.version) } : {}) }
+  }
+
+  // ---------- assignments (pins) ----------
+
+  async assignment(userID: string, sessionID: string): Promise<ProfileAssignment | undefined> {
+    return (await this.state.get<ProfileAssignment>(userID, PROFILE_ASSIGNMENTS, sessionID))?.value
+  }
+
+  /**
+   * (RP-08) The user's pins in one scan, at most `cap` of them (usage reads; no reverse index, see usage.ts).
+   * `truncated` when the user has more.
+   */
+  async assignmentsScan(userID: string, cap: number): Promise<{ items: ProfileAssignment[]; truncated: boolean }> {
+    const all = await this.state.list<ProfileAssignment>(userID, PROFILE_ASSIGNMENTS)
+    return { items: all.slice(0, cap).map((e) => e.value), truncated: all.length > cap }
+  }
+
+  /** Pins a retained version of an active profile to a session (CAS on the session's assignment). */
+  async assign(userID: string, sessionID: string, input: AssignInput): Promise<ProfileAssignment> {
+    if (!isRecord(input)) throw new AgentError("invalid", "Body must be a JSON object")
+    const expected = this.expected(input.expectedRevision)
+    if (typeof input.profileID !== "string" || !input.profileID) throw new AgentError("invalid", "profileID is required")
+    if (!Number.isSafeInteger(input.version) || (input.version as number) < 1) throw new AgentError("invalid", "version must be a version number")
+    const profileID = input.profileID
+    const number = input.version as number
+    const profile = await this.record(userID, profileID)
+    if (!profile) throw notFound(profileID)
+    if (profile.state !== "active") throw conflict(`Profile ${profileID} is archived; unarchive it first`, profile.revision, { state: profile.state })
+    const version = await this.version(userID, profileID, number)
+    if (!version) throw new AgentError("not_found", `Profile ${profileID} has no retained version ${number}`)
+
+    const now = this.now()
+    const pending: ProfileAck = { status: "unsupported", digest: version.digest, notes: ["this hub does not apply profiles to sessions yet"], at: now }
+    const written = await updateVersioned<ProfileAssignment>(this.state, userID, PROFILE_ASSIGNMENTS, sessionID, (current) => {
+      const revision = current?.revision ?? 0
+      if (revision !== expected) throw conflict(`The profile assignment of ${sessionID} changed (revision ${revision})`, revision)
+      // The effective version (what the session last confirmed) outlives re-pins until a spoke confirms another.
+      return { v: 1, sessionID, profileID, version: number, revision: revision + 1, ...(current?.effective ? { effective: current.effective } : {}), ...(this.ack ? {} : { ack: pending }) }
+    })
+    let assignment = written!
+    // Retention may have dropped the version between the check and the pin: undo rather than pin a gone version.
+    if (!(await this.version(userID, profileID, number))) {
+      const stored = await this.state.get<ProfileAssignment>(userID, PROFILE_ASSIGNMENTS, sessionID)
+      if (stored && stored.value.revision === assignment.revision) await this.state.delete(userID, PROFILE_ASSIGNMENTS, sessionID, { ifVersion: stored.version })
+      throw conflict(`Profile ${profileID} version ${number} was just dropped`, profile.revision)
+    }
+    if (this.ack) {
+      const ack = await this.ack(userID, assignment, version)
+      assignment = (await this.recordAck(userID, sessionID, assignment.revision, ack)) ?? assignment
+    }
+    return assignment
+  }
+
+  /**
+   * Records the latest acknowledgment of a pin (HWA-15). Acknowledgments are the hub's own status, not a user
+   * mutation: they keep the assignment's revision. Undefined when the pin changed meanwhile. A pending ack never
+   * replaces a final one of the same revision and digest (the spoke may answer before the pending is stored);
+   * applied and partial also become the session's effective version.
+   */
+  async recordAck(userID: string, sessionID: string, revision: number, ack: ProfileAck): Promise<ProfileAssignment | undefined> {
+    let kept: ProfileAssignment | undefined
+    const written = await updateVersioned<ProfileAssignment>(this.state, userID, PROFILE_ASSIGNMENTS, sessionID, (current) => {
+      if (!current || current.revision !== revision) return undefined
+      if (ack.status === "pending" && current.ack && current.ack.status !== "pending" && current.ack.digest === ack.digest) {
+        kept = current
+        return undefined
+      }
+      const notes = ack.notes ? { notes: ack.notes.slice(0, PROFILE_APPLY_LIMITS.notes) } : {}
+      const effective =
+        ack.status === "applied" || ack.status === "partial"
+          ? { effective: { profileID: current.profileID, version: current.version, digest: ack.digest, status: ack.status, at: ack.at } }
+          : {}
+      return { ...current, ack: { ...ack, ...notes }, ...effective }
+    })
+    return written ?? kept
+  }
+
+  async unassign(userID: string, sessionID: string, expectedRevision: unknown): Promise<ProfileAssignment> {
+    const expected = this.expected(expectedRevision)
+    const stored = await this.state.get<ProfileAssignment>(userID, PROFILE_ASSIGNMENTS, sessionID)
+    if (!stored) throw new AgentError("not_found", `Session ${sessionID} has no profile`)
+    if (stored.value.revision !== expected) throw conflict(`The profile assignment of ${sessionID} changed (revision ${stored.value.revision})`, stored.value.revision)
+    if (!(await this.state.delete(userID, PROFILE_ASSIGNMENTS, sessionID, { ifVersion: stored.version })).ok) {
+      const now = await this.assignment(userID, sessionID)
+      throw conflict(`The profile assignment of ${sessionID} changed`, now?.revision ?? 0)
+    }
+    return stored.value
+  }
+
+  // ---------- internals ----------
+
+  private expected(v: unknown): number {
+    if (!isExpectedRevision(v)) throw new AgentError("invalid", "expectedRevision is required (the revision you read; 0 when there is none)")
+    return v
+  }
+
+  private async record(userID: string, id: string): Promise<ProfileRecord | undefined> {
+    return (await this.state.get<ProfileRecord>(userID, PROFILES, id))?.value
+  }
+
+  private async pinnedVersions(userID: string, profileID: string): Promise<Set<number>> {
+    const out = new Set<number>()
+    for (const { value } of await this.state.list<ProfileAssignment>(userID, PROFILE_ASSIGNMENTS)) if (value.profileID === profileID) out.add(value.version)
+    return out
+  }
+
+  /** Bytes of retained versions per user stay under bytesPerUser (a soft bound: concurrent writers may pass it by one version). */
+  private async ensureQuota(userID: string, bytes: number): Promise<void> {
+    let used = 0
+    for (const { value } of await this.state.list<ProfileRecord>(userID, PROFILES)) for (const h of value.history) used += h.bytes
+    if (used + bytes > this.limits.bytesPerUser) {
+      throw new AgentError("rate_limited", `Profile storage is full (${this.limits.bytesPerUser} bytes per user)`, { hint: "Unpin and drop old versions or profiles you no longer use" })
+    }
+  }
+
+  private async reserveName(userID: string, name: string, id: string, now: number): Promise<void> {
+    const index = (await this.state.get<NameIndex>(userID, PROFILE_INDEX, "names"))?.value
+    const held = index?.names[name]
+    const stale = held && now - held.at > this.limits.reservationMs && !(await this.record(userID, held.id)) ? held.id : undefined
+    await updateVersioned<NameIndex>(this.state, userID, PROFILE_INDEX, "names", (current) => {
+      const names = { ...current?.names }
+      const holder = names[name]
+      if (holder && holder.id !== stale) throw new AgentError("name_taken", `You already have a profile named ${name}`)
+      delete names[name]
+      if (Object.keys(names).length >= this.limits.profilesPerUser) throw new AgentError("rate_limited", `At most ${this.limits.profilesPerUser} profiles per user`, { hint: "Reuse or archive profiles" })
+      names[name] = { id, at: now }
+      return { v: 1, names }
+    })
+  }
+
+  private async releaseName(userID: string, name: string, id: string): Promise<void> {
+    await updateVersioned<NameIndex>(this.state, userID, PROFILE_INDEX, "names", (current) => {
+      if (current?.names[name]?.id !== id) return undefined
+      const names = { ...current.names }
+      delete names[name]
+      return { v: 1, names }
+    })
+  }
+
+  /** Adopts version slots past latestVersion that a stopped writer left; returns the profile. */
+  private async heal(userID: string, id: string): Promise<ProfileRecord | undefined> {
+    const profile = await this.record(userID, id)
+    if (!profile) return undefined
+    const found: VersionEntry[] = []
+    for (let n = profile.latestVersion + 1; ; n++) {
+      const slot = await this.state.get<AgentProfileVersion>(userID, versionCollection(id), String(n))
+      if (!slot) break
+      found.push({ version: n, digest: slot.value.digest, bytes: contentBytes(slot.value.content), createdAt: slot.value.createdAt, ...countsOf(slot.value.content) })
+    }
+    if (!found.length) return profile
+    return updateVersioned<ProfileRecord>(this.state, userID, PROFILES, id, (current) => {
+      if (!current) return undefined
+      const add = found.filter((f) => f.version > current.latestVersion)
+      if (!add.length) return undefined
+      return { ...current, history: [...current.history, ...add], latestVersion: add[add.length - 1]!.version, revision: current.revision + 1, updatedAt: this.now() }
+    }).then(async (written) => written ?? (await this.record(userID, id)))
+  }
+
+  /** Deletes pruned version records, except any a session pinned meanwhile (those go back into the history). */
+  private async dropVersions(userID: string, id: string, victims: readonly VersionEntry[]): Promise<void> {
+    if (!victims.length) return
+    const pinned = await this.pinnedVersions(userID, id)
+    const keep = victims.filter((v) => pinned.has(v.version))
+    if (keep.length) {
+      await updateVersioned<ProfileRecord>(this.state, userID, PROFILES, id, (current) =>
+        current ? { ...current, history: [...current.history, ...keep.filter((k) => !current.history.some((h) => h.version === k.version))].sort((a, b) => a.version - b.version) } : undefined,
+      )
+    }
+    for (const victim of victims) if (!pinned.has(victim.version)) await this.state.delete(userID, versionCollection(id), String(victim.version))
+  }
+}
+
+const notFound = (id: string) => new AgentError("not_found", `No profile ${id}`)