@defrex/autobuild 0.8.0

package/packages/core/src/cli/context.ts

@@ -0,0 +1,470 @@
+/**
+ * The `ab context` materializer (SPEC §8.3): a phase-scoped hydration of the
+ * gitignored `.ab/` scratch dir. Everything derives from
+ * `PHASE_SPECS[phase].inputs` — the table drives, so the CLI, the manifest,
+ * and the engine all validate against the same data (no per-phase switch
+ * sprawl). Scoping is deliberate: what a phase *can't* see is part of its
+ * design (the planner never sees code-review rounds; the reviewer sees prior
+ * findings but not the producer's session).
+ *
+ * Disposable `.ab/` content is wiped and recreated on every run — stale
+ * context is worse than no context — while legacy tracked entries are restored
+ * byte-for-byte from the index. Git's local exclude keeps generated scratch
+ * ignored without mutating the repository's own `.gitignore`.
+ */
+import { mkdir, rm, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { parseConfig } from '../config/load'
+import type { VerifyStepConfig } from '../config/schema'
+import type { AbEvent } from '../events/catalog'
+import {
+  allowedTerminals,
+  phaseSpecFor,
+  type PhaseSpec,
+  type TerminalCommand,
+} from '../kernel/phases'
+import { reduceBuild, type BuildState } from '../kernel/reducer'
+import {
+  isVerifyPhase,
+  verifyReportKind,
+  verifyStep,
+  type ArtifactRef,
+  type CommitRange,
+  type Feedback,
+  type Finding,
+  type Phase,
+} from '../ontology'
+import { KERNEL } from '../events/envelope'
+import type { IdSource } from '../ids'
+import {
+  allocateScratchPath,
+  ensureScratchExcluded,
+  restoreTrackedScratch,
+  trackedScratchPaths,
+} from '../ports/workspace/phase-scratch'
+import type { Exec } from '../ports/workspace/git-worktree'
+import type { BuildStore } from '../store/types'
+import type { CliEnv } from './env'
+
+export interface ContextDeps {
+  store: BuildStore
+  env: CliEnv
+  /** Root of the working copy; `.ab/` is created directly under it. */
+  workspacePath: string
+  /** Present in the wired CLI; optional for non-Git materializer unit tests. */
+  exec?: Exec
+  ids?: IdSource
+}
+
+/** Paths are relative to `.ab/`, forward-slash separated. */
+export type MaterializedEntry = ArtifactRef | 'derived'
+
+/**
+ * The manifest (§8.3): the agent's contract — `required` deposits and
+ * `allowedTerminals` — sourced from the same PHASE_SPECS table the terminal
+ * commands validate with, so skills are self-checking.
+ */
+export interface ContextManifest {
+  build: string
+  phase: Phase
+  round: number
+  /**
+   * Artifact kinds the phase's terminal will validate (D5). For agent-verify
+   * phases this is `verify-report:<step>`, required only on a `fail` verdict
+   * (§8.2) — listed so the agent knows the kind name up front.
+   */
+  required: string[]
+  allowedTerminals: TerminalCommand[]
+  /** Workspace-relative path where this manifest was written. */
+  manifestPath: string
+  /** Safe workspace-relative producer notes path (implement/reconcile only). */
+  notesPath?: string
+  /** relPath (under .ab/) → source artifact ref, or 'derived'. */
+  materialized: Record<string, MaterializedEntry>
+  /** From the latest `implement.completed` (§8.3 code-review/verify inputs). */
+  commitRange?: CommitRange
+  /** Reconcile: `{baseSha}` freshly recorded by this attempt's phase start (§15.7). */
+  conflict?: { baseSha: string }
+  /** Agent-verify: the step's config from the workspace's autobuild.toml (§16.1). */
+  step?: { name: string; config: VerifyStepConfig }
+  /** The feedback this phase occurrence was started with (§15.3, §10). */
+  feedback?: Feedback
+  /** Chains a human resolved via dismiss-finding — the reviewer is told so (§15.6-B). */
+  dismissedFindingIds?: string[]
+}
+
+function requiredKinds(spec: PhaseSpec, phase: Phase): string[] {
+  if (spec.requiredArtifact !== undefined) return [spec.requiredArtifact]
+  // Agent-verify: the per-step report kind, required only on fail (§8.2).
+  if (isVerifyPhase(phase)) return [verifyReportKind(verifyStep(phase))]
+  return []
+}
+
+/** All finding objects ever deposited, by id — verdict payloads carry them in
+ * full (§15.3), so feedback-by-id resolves without touching artifacts. */
+function findingsById(events: AbEvent[]): Map<string, Finding> {
+  const byId = new Map<string, Finding>()
+  for (const event of events) {
+    if (event.type === 'plan-review.verdict' || event.type === 'code-review.verdict') {
+      for (const finding of event.payload.findings) byId.set(finding.id, finding)
+    }
+  }
+  return byId
+}
+
+/**
+ * The feedback carried by this occurrence's `*.started` event (§15.3).
+ * `implement.started`, `plan.started`, and agent `verify.started` may carry
+ * feedback — the carrier that gets answered guidance to a fresh session after
+ * a parked build re-attaches (§15.6-B). A `plan.started` without one (logs
+ * predating the field) falls
+ * back to deriving round-N feedback from the round-(N-1)
+ * `plan-review.verdict` — the plan loop's verdicts ARE its findings channel
+ * (§8.3: "prior plan rev + findings").
+ */
+function currentFeedback(events: AbEvent[], phase: Phase, round: number): Feedback | null {
+  if (isVerifyPhase(phase)) {
+    const step = verifyStep(phase)
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+      const event = events[i]!
+      if (
+        event.type === 'verify.started' &&
+        event.payload.step === step &&
+        event.payload.attempt === round
+      ) {
+        return event.payload.feedback ?? null
+      }
+    }
+    return null
+  }
+  if (phase === 'implement') {
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+      const event = events[i]!
+      if (event.type === 'implement.started' && event.payload.round === round) {
+        return event.payload.feedback ?? null
+      }
+    }
+    return null
+  }
+  if (phase === 'plan') {
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+      const event = events[i]!
+      if (event.type === 'plan.started' && event.payload.round === round) {
+        if (event.payload.feedback !== undefined) return event.payload.feedback
+        break // legacy start without the field — derive from the prior verdict
+      }
+    }
+    if (round <= 1) return null
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+      const event = events[i]!
+      if (event.type === 'plan-review.verdict' && event.payload.round === round - 1) {
+        return event.payload.verdict === 'revise'
+          ? { findings: event.payload.findings.map((finding) => finding.id) }
+          : null
+      }
+    }
+  }
+  return null
+}
+
+/** Empty and recreate `.ab/`; callers restore any tracked legacy entries. */
+async function wipeAbDir(abDir: string): Promise<void> {
+  await rm(abDir, { recursive: true, force: true })
+  await mkdir(abDir, { recursive: true })
+}
+
+function dismissedIds(state: BuildState, events: AbEvent[]): string[] {
+  const known = findingsById(events)
+  const ids = new Set<string>()
+  for (const escalation of state.answeredEscalations) {
+    if (escalation.resolution !== 'dismiss-finding') continue
+    for (const ref of escalation.refs ?? []) {
+      if (known.has(ref)) ids.add(ref)
+    }
+  }
+  return [...ids]
+}
+
+/**
+ * Materialize the phase's `.ab/` tree and return the manifest (also written
+ * as `.ab/context.json`).
+ */
+export async function buildContext(deps: ContextDeps): Promise<ContextManifest> {
+  const { store, env, workspacePath } = deps
+  const { build, phase, round } = env
+  const spec = phaseSpecFor(phase)
+  const inputs = spec.inputs
+  const events = await store.getEvents(build)
+  const state = reduceBuild(events)
+
+  // Preserve legacy tracked scratch exactly while replacing disposable files.
+  // Some adapter contract fixtures intentionally use a non-Git workspace;
+  // context hydration still works there, while publication remains Git-only.
+  const abDir = join(workspacePath, '.ab')
+  const gitWorkspace =
+    deps.exec !== undefined &&
+    (await deps.exec(['git', 'rev-parse', '--is-inside-work-tree'], { cwd: workspacePath }))
+      .exitCode === 0
+  const tracked = gitWorkspace ? await trackedScratchPaths(deps.exec!, workspacePath) : []
+  await wipeAbDir(abDir)
+  if (gitWorkspace) {
+    await restoreTrackedScratch(deps.exec!, workspacePath, tracked)
+    await ensureScratchExcluded(deps.exec!, workspacePath)
+  }
+  if (!tracked.includes('.ab/.gitignore')) await writeFile(join(abDir, '.gitignore'), '*\n')
+
+  const trackedSet = new Set(tracked)
+  const allocated = new Set<string>()
+  const locations = new Map<string, string>()
+  const locate = (desired: string): string => {
+    const prior = locations.get(desired)
+    if (prior !== undefined) return prior
+    const path = allocateScratchPath(desired, trackedSet, allocated)
+    locations.set(desired, path)
+    return path
+  }
+  const manifestRelPath = locate('context.json')
+  const notesRelPath =
+    phase === 'implement' || phase === 'reconcile' ? locate(`${phase}-notes.md`) : undefined
+  const materialized: Record<string, MaterializedEntry> = {}
+
+  async function writeDerived(desiredPath: string, content: string): Promise<void> {
+    const relPath = locate(desiredPath)
+    const target = join(abDir, relPath)
+    await mkdir(dirname(target), { recursive: true })
+    await writeFile(target, content)
+    materialized[relPath] = 'derived'
+  }
+
+  /** Latest rev when `rev` omitted; silently skips absent kinds — the tree is
+   * a projection of what exists, and the manifest shows what materialized. */
+  async function writeArtifact(desiredPath: string, kind: string, rev?: number): Promise<void> {
+    const artifact = await store.getArtifact(build, kind, rev)
+    if (artifact === null) return
+    const relPath = locate(desiredPath)
+    const target = join(abDir, relPath)
+    await mkdir(dirname(target), { recursive: true })
+    await writeFile(target, artifact.content)
+    materialized[relPath] = { kind: artifact.meta.kind, rev: artifact.meta.revision }
+  }
+
+  const manifest: ContextManifest = {
+    build,
+    phase,
+    round,
+    required: requiredKinds(spec, phase),
+    allowedTerminals: allowedTerminals(phase),
+    manifestPath: `.ab/${manifestRelPath}`,
+    ...(notesRelPath !== undefined ? { notesPath: `.ab/${notesRelPath}` } : {}),
+    materialized,
+  }
+
+  if (inputs.ticket === true) {
+    const created = events.find((event) => event.type === 'build.created')
+    if (created !== undefined && created.type === 'build.created') {
+      const ticket = created.payload.ticket
+      const lines = [
+        `# Ticket: ${ticket.title ?? ticket.id}`,
+        '',
+        `- source: ${ticket.source}`,
+        `- id: ${ticket.id}`,
+        ...(ticket.url !== undefined ? [`- url: ${ticket.url}`] : []),
+        ...(ticket.title !== undefined ? [`- title: ${ticket.title}`] : []),
+        '',
+      ]
+      await writeDerived('ticket.md', lines.join('\n'))
+    }
+  }
+
+  if (inputs.spec === true) {
+    // §6.3 immutability: the spec a phase sees is the rev the spec.* events
+    // anchor (spec.imported/authored/revised → state.specRev), never the
+    // newest deposit — so a stray spec rev with no sanctioning event can
+    // never swap the contract downstream reviewers approve conformance to.
+    await writeArtifact('spec.md', 'spec', state.specRev)
+  }
+
+  // The plan a phase sees is the rev cited by the latest `plan.completed`
+  // (D5: the terminal validates and cites this round's deposit). For
+  // 'approved' inputs the engine only advances past the plan loop on an
+  // approve verdict (§10), so the cited rev IS the approved one; for
+  // plan-review's 'latest' it is the rev under review. Pinning to the
+  // event-derived rev — never the newest deposit — keeps an out-of-loop
+  // `ab artifact put plan` from swapping in a never-reviewed plan (§6.3's
+  // drift argument, applied to the plan).
+  if (inputs.plan !== undefined) {
+    await writeArtifact('plan.md', 'plan', state.plan.artifactRev)
+  }
+
+  // Producer's own prior-round artifacts (§8.3: plan sees its prior rev,
+  // implement its own prior notes) — the phase's required kind at latest rev;
+  // absent on round 1 by construction.
+  if (inputs.priorOwnArtifacts === true && spec.requiredArtifact !== undefined) {
+    await writeArtifact(`${spec.requiredArtifact}.md`, spec.requiredArtifact)
+  }
+
+  if (inputs.implementNotes === true) {
+    await writeArtifact('implement-notes.md', 'implement-notes')
+  }
+
+  // Verify reports at latest rev, one file per step (§8.3: routed-back
+  // failure reports for implement; the full set for finalize).
+  if (inputs.verifyReports === true) {
+    const metas = await store.listArtifacts(build)
+    const kinds = new Set(
+      metas.map((meta) => meta.kind).filter((kind) => kind.startsWith('verify-report:')),
+    )
+    for (const kind of kinds) {
+      const step = kind.slice('verify-report:'.length)
+      await writeArtifact(`verify/${step}.md`, kind)
+    }
+  }
+
+  if (inputs.findings === 'current' || inputs.currentFeedback === true) {
+    const feedback = currentFeedback(events, phase, round)
+    if (feedback !== null) {
+      manifest.feedback = feedback
+      if ('findings' in feedback) {
+        // Ids → full Finding objects from the verdict that produced them.
+        const byId = findingsById(events)
+        const resolved = feedback.findings
+          .map((id) => byId.get(id))
+          .filter((finding): finding is Finding => finding !== undefined)
+        await writeDerived('findings.json', `${JSON.stringify(resolved, null, 2)}\n`)
+      } else if ('verify' in feedback) {
+        // The verify failure report routed back into the code loop (§5) — the
+        // exact rev the feedback cites, not just the latest.
+        await writeArtifact(
+          `verify/${feedback.verify.step}.md`,
+          feedback.verify.report.kind,
+          feedback.verify.report.rev,
+        )
+      } else {
+        // A human escalation answer fed in as authoritative feedback (§15.6-B).
+        await writeDerived('guidance.json', `${JSON.stringify(feedback.guidance, null, 2)}\n`)
+      }
+    }
+  }
+
+  if (inputs.findings === 'all-rounds') {
+    // Every prior round's findings, for `persists` marking (§15.4), plus the
+    // human-dismissed ids — the reviewer is told so (§15.6-B).
+    const loop =
+      phase === 'plan-review' ? state.reviewFindings.planReview : state.reviewFindings.codeReview
+    for (let r = 1; r < round && r <= loop.length; r += 1) {
+      await writeDerived(`history/findings-r${r}.json`, `${JSON.stringify(loop[r - 1], null, 2)}\n`)
+    }
+    const dismissed = dismissedIds(state, events)
+    manifest.dismissedFindingIds = dismissed
+    if (dismissed.length > 0) {
+      await writeDerived('dismissed-findings.json', `${JSON.stringify(dismissed, null, 2)}\n`)
+    }
+  }
+
+  // Answered guidance addressed to THIS phase (§15.6-B, §11): finalize and
+  // reconcile have no producer round for the engine to feed the answer into,
+  // so `ab context` IS their delivery channel — without this the answer would
+  // be recorded but never reach any agent. Latest answer wins, matching the
+  // engine's loop-feedback rule; the file shape matches the loop producers'
+  // guidance.json so skills read one format.
+  if (inputs.answeredGuidance === true) {
+    const answered = state.answeredEscalations.filter(
+      (escalation) => escalation.resolution === 'guidance' && escalation.phase === phase,
+    )
+    const latest = answered.at(-1) // answeredEscalations is in answer order
+    if (latest !== undefined) {
+      await writeDerived(
+        'guidance.json',
+        `${JSON.stringify({ escalation: latest.id, answer: latest.answer }, null, 2)}\n`,
+      )
+    }
+  }
+
+  if (inputs.commitRange === true && state.implement.commits !== undefined) {
+    manifest.commitRange = state.implement.commits
+  }
+
+  if (inputs.conflict === true) {
+    // `pr.conflicted.baseSha` is the janitor's detection-time evidence. The
+    // runner refreshes the remote base immediately before each actual run and
+    // records the execution input in reconcile.started. A crashed same-attempt
+    // rerun can therefore have multiple starts; the newest matching AB_PHASE
+    // attempt is authoritative.
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+      const event = events[i]!
+      if (event.type === 'reconcile.started' && event.payload.attempt === round) {
+        manifest.conflict = { baseSha: event.payload.baseSha }
+        break
+      }
+    }
+    if (manifest.conflict === undefined) {
+      throw new Error(
+        `reconcile@${round} context requires a matching reconcile.started event ` +
+          'with the freshly resolved base SHA — the runner must record the phase start before launching the session',
+      )
+    }
+  }
+
+  if (inputs.stepConfig === true && isVerifyPhase(phase)) {
+    const step = verifyStep(phase)
+    const tomlPath = join(workspacePath, 'autobuild.toml')
+    const file = Bun.file(tomlPath)
+    if (!(await file.exists())) {
+      throw new Error(
+        `verify:${step} needs its step config, but ${tomlPath} does not exist — ` +
+          'autobuild.toml declares [verify.<step>] tables (SPEC §16.1)',
+      )
+    }
+    const config = parseConfig(await file.text(), tomlPath)
+    const stepConfig = config.verify.stepConfigs[step]
+    if (stepConfig === undefined) {
+      const known = Object.keys(config.verify.stepConfigs)
+      throw new Error(
+        `verify step "${step}" is not configured in autobuild.toml — ` +
+          `configured steps: ${known.join(', ') || '(none)'} (SPEC §16.1)`,
+      )
+    }
+    manifest.step = { name: step, config: stepConfig }
+  }
+
+  // inputs.prTemplate (§8.3 finalize): autobuild.toml declares no PR-template
+  // table in §16.1, so there is nothing to materialize yet — the input stays
+  // in the table for when config grows one.
+
+  await writeFile(join(abDir, manifestRelPath), `${JSON.stringify(manifest, null, 2)}\n`)
+
+  // Legacy tracked scratch is repository debt, not content Autobuild rewrites.
+  // Record it once per build from the provisioned base so harvest can groom it.
+  if (gitWorkspace && deps.ids !== undefined) {
+    const provisioned = events.find((event) => event.type === 'workspace.provisioned')
+    const marker = 'phase-scratch:tracked-at-provisioned-base'
+    const alreadyRecorded = events.some(
+      (event) => event.type === 'observation.recorded' && event.payload.refs?.includes(marker),
+    )
+    if (
+      provisioned !== undefined &&
+      provisioned.type === 'workspace.provisioned' &&
+      !alreadyRecorded
+    ) {
+      const baseTracked = await trackedScratchPaths(
+        deps.exec!,
+        workspacePath,
+        provisioned.payload.base.sha,
+      )
+      if (baseTracked.length > 0) {
+        await store.append(build, {
+          actor: KERNEL,
+          type: 'observation.recorded',
+          payload: {
+            id: deps.ids('obs'),
+            kind: 'followup',
+            summary: `repository base tracks Autobuild phase scratch: ${baseTracked.join(', ')}`,
+            files: baseTracked,
+            refs: [marker],
+          },
+        })
+      }
+    }
+  }
+  return manifest
+}

package/packages/core/src/cli/dashboard/actions.ts

@@ -0,0 +1,59 @@
+import type { DashboardBuild, DashboardHarvest, DashboardModel, EffectiveStatus } from './model'
+
+export type DashboardBuildControl =
+  | { key: 'p'; action: 'pause'; label: 'pause' }
+  | { key: 'p'; action: 'cancel-pause'; label: 'cancel pause' }
+  | { key: 'r'; action: 'resume'; label: 'resume' }
+
+/** Authoritative effective-status mapping consumed by every dashboard frontend. */
+export function dashboardBuildControl(status: EffectiveStatus): DashboardBuildControl | undefined {
+  switch (status) {
+    case 'running':
+      return { key: 'p', action: 'pause', label: 'pause' }
+    case 'pausing':
+      return { key: 'p', action: 'cancel-pause', label: 'cancel pause' }
+    case 'paused':
+    case 'blocked':
+      return { key: 'r', action: 'resume', label: 'resume' }
+    case 'queued':
+    case 'resuming':
+    case 'aborting':
+    case 'cleaning':
+      return undefined
+  }
+}
+
+export interface DashboardActionAvailability {
+  primary?: DashboardBuildControl['action']
+  abort: boolean
+  discard: boolean
+  autoMerge: boolean
+  answer: boolean
+}
+
+export function buildActionAvailability(build: DashboardBuild): DashboardActionAvailability {
+  return {
+    ...(dashboardBuildControl(build.status)
+      ? { primary: dashboardBuildControl(build.status)!.action }
+      : {}),
+    abort: ['queued', 'running', 'pausing', 'paused', 'resuming', 'blocked'].includes(build.status),
+    discard: build.status === 'queued',
+    autoMerge: !['aborting', 'cleaning'].includes(build.status),
+    answer: build.blockers.length > 0,
+  }
+}
+
+export function repositoryActionAvailability(model: DashboardModel) {
+  return {
+    intake: true,
+    defaultAutoMerge: true,
+    bulkPause: model.builds.some((build) => build.status === 'running'),
+    bulkResume: model.builds.some((build) => build.status === 'paused'),
+    harvestToggle: true,
+    harvestRun: model.harvestPaused === false,
+  }
+}
+
+export function harvestActionAvailability(harvest: DashboardHarvest | undefined) {
+  return { resume: harvest?.action === 'resume', acknowledge: harvest?.action === 'acknowledge' }
+}

package/packages/core/src/cli/dashboard/cells.ts

@@ -0,0 +1,92 @@
+/** Unicode text geometry shared by every dashboard compositor. */
+
+const SEGMENTER = new Intl.Segmenter(undefined, { granularity: 'grapheme' })
+
+export interface Grapheme {
+  /** Exact source bytes represented by this cluster. */
+  text: string
+  /** UTF-16 boundaries, suitable for String.prototype.slice. */
+  start: number
+  end: number
+  /** Terminal display-cell width. */
+  width: number
+}
+
+/** Segment a string into indivisible extended grapheme clusters. */
+export function graphemes(value: string): Grapheme[] {
+  return [...SEGMENTER.segment(value)].map(({ segment, index }) => ({
+    text: segment,
+    start: index,
+    end: index + segment.length,
+    width: Bun.stringWidth(segment),
+  }))
+}
+
+function isTerminalControl(code: number): boolean {
+  return code < 0x20 || code === 0x7f || (code >= 0x80 && code <= 0x9f)
+}
+
+/**
+ * Preserve readable Unicode while making terminal control characters visible.
+ * This is display-only: callers retain and submit the original value.
+ */
+export function displayText(value: string): string {
+  let displayed = ''
+  for (const character of value) {
+    const code = character.codePointAt(0)!
+    displayed += isTerminalControl(code) ? `\\u{${code.toString(16)}}` : character
+  }
+  return displayed
+}
+
+/** Display-safe clusters, with widths measured after controls are escaped. */
+export function displayGraphemes(value: string): Grapheme[] {
+  return graphemes(displayText(value))
+}
+
+/** Width in terminal display cells. Input must not contain ANSI sequences. */
+export function cellWidth(value: string): number {
+  return graphemes(value).reduce((sum, cluster) => sum + cluster.width, 0)
+}
+
+/** Pad to a terminal-cell width without trimming an over-wide value. */
+export function padEndCells(value: string, width: number): string {
+  return `${value}${' '.repeat(Math.max(0, width - cellWidth(value)))}`
+}
+
+/**
+ * Split into cell-bounded rows without splitting a grapheme cluster. A cluster
+ * wider than the complete row budget is omitted, and later clusters resume.
+ */
+export function splitCells(value: string, width: number): string[] {
+  if (width <= 0) return []
+  const rows: string[] = []
+  let row = ''
+  let used = 0
+  for (const cluster of graphemes(value)) {
+    // At an impossible width, omission is safer than a partial cluster or an
+    // overflowing physical terminal row.
+    if (cluster.width > width) continue
+    if (cluster.width > 0 && used + cluster.width > width) {
+      rows.push(row)
+      row = ''
+      used = 0
+    }
+    row += cluster.text
+    used += cluster.width
+  }
+  if (row !== '' || rows.length === 0) rows.push(row)
+  return rows
+}
+
+/** Normalize an arbitrary UTF-16 offset to the preceding grapheme boundary. */
+export function graphemeBoundary(value: string, offset: number): number {
+  if (!Number.isFinite(offset)) return value.length
+  const wanted = Math.max(0, Math.min(value.length, Math.floor(offset)))
+  let boundary = 0
+  for (const cluster of graphemes(value)) {
+    if (cluster.end > wanted) return cluster.start
+    boundary = cluster.end
+  }
+  return boundary
+}