@vzn/vx 0.0.18 → 0.0.21

package/src/orchestrator/hit-restore.ts

@@ -0,0 +1,221 @@
+// What a HIT leaves behind: the outputs of a confirmed cache entry
+// materialised in the project — or proved already current and left alone —
+// the exact changed paths marked so a same-project consumer need not
+// re-spawn git, the stored stdout replayed, and the cache-hit outcome
+// built. There is ONE restore path: `executeCachedTask` and the local
+// short-circuit (a stable hit restored ahead of its deps) both come here,
+// so the two cannot drift. Stale-hit-critical: a line moved here changes
+// which bytes a green run replays. Moved out of execute-task.ts
+// 2026-09-10 as pure code motion, the mirror of miss-save.ts.
+
+import path from 'node:path'
+import type { CacheConfig } from '../config.js'
+import {
+  type CacheEntry,
+  cleanOutputs,
+  cleanWorkspaceOutputs,
+  resolveOutputs,
+  resolveWorkspaceOutputs,
+  WORKSPACE_OUTPUT_PREFIX,
+} from '../cache/index.js'
+import type { TaskOutcome } from '../graph/index.js'
+import { span, wholeSubtreePrefixes } from '../util/index.js'
+import type { ExecuteArgs } from './execute-task.js'
+
+export interface RestoreHitArgs {
+  args: ExecuteArgs
+  hash: string
+  hit: CacheEntry
+  /** `performance.now()` when the cache op (probe) started — the
+   *  user-perceived restore duration is measured from here. */
+  cacheOpStart: number
+  /** ns offset from run start for the outcome's wallclock window. */
+  taskStartNs: bigint
+}
+
+/**
+ * Materialize a confirmed cache hit: decide skip-restore, clean +
+ * restore declared outputs, mark the exact changed paths so downstream
+ * same-project tasks needn't re-spawn git, replay stored stdout, and
+ * build the cache-hit `TaskOutcome`. Extracted from `executeCachedTask`
+ * so the local short-circuit can restore a stable-key hit ahead of the
+ * schedule using the IDENTICAL logic — there is one restore path, not
+ * two that could drift.
+ */
+export async function restoreHit(restore: RestoreHitArgs): Promise<TaskOutcome> {
+  const { args, hash, hit, cacheOpStart, taskStartNs } = restore
+  const { node, log } = args
+  const cacheCfg: CacheConfig | undefined = node.config.cache
+  const outputs = cacheCfg?.outputs.files ?? []
+  const wsOutputs = cacheCfg?.outputs.workspaceFiles ?? []
+  const anyOutputs = outputs.length > 0 || wsOutputs.length > 0
+  const dirPrefixes = wholeSubtreePrefixes(outputs)
+  const cleanArgs = {
+    projectDir: node.projectDir,
+    outputs,
+    nestedProjectDirs: args.nestedProjectDirs,
+  }
+  const wsCleanArgs = { workspaceRoot: args.workspaceRoot, outputs: wsOutputs }
+
+  // "Tree is already current" short-circuit — skip cleanOutputs
+  // + restoreOutputs when the on-disk state matches what this
+  // entry recorded at save time. Integrity-preserving: we
+  // require BOTH that the output-glob walk yields exactly the
+  // expected paths (no strays, no missing) AND that every file's
+  // (size, mode, mtime) matches the stored fingerprint. Any
+  // divergence falls through to a real clean + restore.
+  //
+  // The output-file fingerprints can't be batch-loaded at
+  // prepareRun time — non-leaf task hashes depend on upstream
+  // outputs that haven't been written yet, so hashes are
+  // necessarily computed mid-run. The short-circuit's batched probe
+  // loads the rows with the entry (`hit.outputRows`); only the lazy
+  // path pays one SELECT here. Either beats reading the manifest from
+  // the tar (decompress + parse) at the same point.
+  // A task with no declared outputs has nothing to clean or restore: its
+  // stdout replays from the row (`hit.stdout`), and its artifact holds
+  // only logs. Extracting it anyway cost an `exists` + a tar read per hit
+  // — 1.7 ms each on a four-task real repo whose `link` and `element`
+  // tasks declare `outputs: []` (2026-09-10, VX_TIMING).
+  let skipRestore = !anyOutputs
+  if (anyOutputs) {
+    const endRows = span('output rows')
+    const expected = hit.outputRows ?? args.cache.loadOutputFilesBatch([hash]).get(hash) ?? []
+    endRows()
+    if (expected.length > 0) {
+      // Two namespaces in the rows: bare rels are project outputs,
+      // `workspace-outputs/<rel>` rows anchor at the workspace root.
+      const projExpected = expected.filter((e) => !e.path.startsWith(WORKSPACE_OUTPUT_PREFIX))
+      const wsExpected = expected
+        .filter((e) => e.path.startsWith(WORKSPACE_OUTPUT_PREFIX))
+        .map((e) => ({ ...e, path: e.path.slice(WORKSPACE_OUTPUT_PREFIX.length) }))
+      // The directory short-circuit: for whole-subtree globs, unchanged
+      // mtimes on every directory recorded at the last save/restore prove
+      // the output SET is unchanged (a file added or removed anywhere the
+      // glob could see bumps a recorded directory), so the walk that cost
+      // 0.36 ms per warm hit is replaced by a few stats. The per-file
+      // fingerprint check below still runs; only the enumeration is skipped.
+      let setKnown = false
+      if (dirPrefixes !== null && wsOutputs.length === 0 && args.cache.outputDirsCurrent) {
+        const endDirs = span('output dirs')
+        // Loaded with the entry (batched by getMany, or with the lazy get).
+        const dirRows = hit.outputDirRows ?? []
+        const covers = dirPrefixes.every((pre) => dirRows.some((r) => r.path === pre))
+        setKnown = covers && (await args.cache.outputDirsCurrent!(node.projectDir, dirRows))
+        endDirs()
+      }
+      let actualAbs: string[]
+      let actualWsAbs: string[]
+      if (setKnown) {
+        actualAbs = projExpected.map((e) => path.join(node.projectDir, e.path))
+        actualWsAbs = []
+      } else {
+        const endGlob = span('output glob')
+        actualAbs = await resolveOutputs({
+          projectDir: node.projectDir,
+          outputs,
+          nestedProjectDirs: args.nestedProjectDirs,
+        })
+        actualWsAbs = await resolveWorkspaceOutputs({
+          workspaceRoot: args.workspaceRoot,
+          outputs: wsOutputs,
+        })
+        endGlob()
+      }
+      const setsMatch = (
+        actual: readonly string[],
+        exp: ReadonlyArray<{ path: string }>,
+      ): boolean => {
+        const expSet = new Set(exp.map((e) => e.path))
+        return actual.length === expSet.size && actual.every((r) => expSet.has(r))
+      }
+      const actualRels = actualAbs.map((p) =>
+        path.relative(node.projectDir, p).split(path.sep).join('/'),
+      )
+      const actualWsRels = actualWsAbs.map((p) =>
+        path.relative(args.workspaceRoot, p).split(path.sep).join('/'),
+      )
+      if (setsMatch(actualRels, projExpected) && setsMatch(actualWsRels, wsExpected)) {
+        const endStat = span('output stat')
+        skipRestore =
+          (await args.cache.isOutputsCurrent(node.projectDir, projExpected)) &&
+          (await args.cache.isOutputsCurrent(args.workspaceRoot, wsExpected))
+        endStat()
+        // The walk ran and proved the tree current (rows absent, or a
+        // directory had moved — a benign touch): snapshot the directories
+        // so the next hit skips the walk.
+        if (skipRestore && !setKnown && dirPrefixes !== null) {
+          await args.cache.recordOutputDirs?.(hash, node.projectDir, dirPrefixes)
+        }
+      }
+    }
+  }
+  if (!skipRestore) {
+    let cleanedRels: string[] = []
+    let cleanedWsRels: string[] = []
+    if (outputs.length > 0) cleanedRels = await cleanOutputs(cleanArgs)
+    if (wsOutputs.length > 0) cleanedWsRels = await cleanWorkspaceOutputs(wsCleanArgs)
+    await args.cache.restoreOutputs(hash, node.projectDir, args.workspaceRoot)
+    // The directory snapshot behind the NEXT hit's skip-restore, taken at
+    // run end when the run keeps a list (as the miss path does, see
+    // miss-save.ts): the restore renamed into these directories
+    // microseconds ago, inside the snapshot's racy window, so a snapshot
+    // taken here was refused and the first warm run after every restore
+    // walked its output trees — 41 of payload's 45 tasks, 14,430 files,
+    // ~75 ms of the no-op's CPU (2026-09-11).
+    if (dirPrefixes !== null) {
+      if (args.outputDirSnapshots !== undefined) {
+        args.outputDirSnapshots.push({ hash, projectDir: node.projectDir, prefixes: dirPrefixes })
+      } else {
+        await args.cache.recordOutputDirs?.(hash, node.projectDir, dirPrefixes)
+      }
+    }
+    // Restored outputs changed the project's tree — but on this
+    // path we know the EXACT changed paths (wiped declared
+    // outputs + the artifact's files). Record them instead of
+    // dropping the snapshot; downstream same-project tasks only
+    // re-spawn git when their input globs can actually see one of
+    // these paths. The cache-miss save path keeps the
+    // unconditional drop (an executed task may write undeclared
+    // files only git can see).
+    if (outputs.length > 0) {
+      args.gitFilesCache?.markOutputsChanged(node.projectDir, [
+        ...cleanedRels,
+        ...hit.outputFiles.filter((p) => !p.startsWith(WORKSPACE_OUTPUT_PREFIX)),
+      ])
+    }
+    if (wsOutputs.length > 0) {
+      args.gitFilesCache?.markWorkspaceOutputsChanged(args.workspaceRoot, [
+        ...cleanedWsRels,
+        ...hit.outputFiles
+          .filter((p) => p.startsWith(WORKSPACE_OUTPUT_PREFIX))
+          .map((p) => p.slice(WORKSPACE_OUTPUT_PREFIX.length)),
+      ])
+    }
+  }
+  if (hit.stdout) log.taskStdout(node, hit.stdout)
+  const status =
+    hit.exitCode !== 0 ? 'failed' : hit.source === 'remote' ? 'cache-hit-remote' : 'cache-hit'
+  // `restored` distinguishes "we just wrote files to disk" from
+  // "disk already matched the cached snapshot". Drives the
+  // "up-to-date" vs "local-cache" / "remote-cache" label in the
+  // framed block. Only meaningful when at least one output was
+  // declared — no-outputs tasks never materialize anything, so
+  // they're vacuously up-to-date.
+  const restored = !skipRestore && anyOutputs
+  return {
+    node,
+    status,
+    exitCode: hit.exitCode,
+    // What THIS run spent: probe + restore. NOT the stored exec time — see
+    // `storedDurationMs`, which is what the hit skipped.
+    durationMs: Math.round(performance.now() - cacheOpStart),
+    storedDurationMs: hit.durationMs,
+    ...(hit.cpuMs !== undefined ? { storedCpuMs: hit.cpuMs } : {}),
+    ...(hit.peakRssBytes !== undefined ? { storedPeakRssBytes: hit.peakRssBytes } : {}),
+    hash,
+    restored,
+    wallclockStartNs: taskStartNs,
+    wallclockEndNs: process.hrtime.bigint() - args.runStartHrTimeNs,
+  }
+}

package/src/orchestrator/index.ts

@@ -3,6 +3,13 @@
 
 export { run, planRun } from './run.js'
 export { prepareRun, type PreparedRun } from './prepare.js'
+export {
+  loadProjects,
+  loadResolvedProjects,
+  loadWorkspacePlugins,
+  type LoadedProjects,
+  type LoadProjectsArgs,
+} from './projects.js'
 export { computeTaskHash, createHashCache, type HashCache } from './task-hash.js'
 export type { RunOptions, RunSummary } from './options.js'
 // Re-surface the cache policy contract (defined in the cache module) so
@@ -19,6 +26,8 @@ export {
   toWireEvent,
   projectNode,
   projectOutcome,
+  outcomeWord,
+  outcomeLabel,
 } from './events.js'
 export type {
   EventBus,
@@ -36,6 +45,14 @@ export {
   LocalHistoryProvider,
   type TaskHistory,
 } from './history.js'
+export {
+  detectFlaky,
+  type FailureMode,
+  type FlakyCandidate,
+  type FlakyFinding,
+  type FlakyTask,
+  flakyTasks,
+} from './failure-mode.js'
 export {
   installPlugins,
   type CacheContext,
@@ -46,6 +63,7 @@ export {
   type PluginCommand,
   type ProjectHookContext,
   type ScheduleHookContext,
+  type AdmitContext,
   type WorkspaceHookContext,
   type InstallPluginsArgs,
   type Plugin,
@@ -53,7 +71,13 @@ export {
   type PluginHookHandlers,
   type PluginHookName,
   type PluginSetupContext,
+  type FingerprintChange,
+  type FingerprintClaim,
+  type FingerprintContext,
   type VxPlugin,
+  definePlugin,
+  type PluginHooks,
+  type PluginOrigin,
 } from './plugin.js'
 export {
   applyConfigHooks,
@@ -61,11 +85,20 @@ export {
   applyKeyHooks,
   applyProjectHooks,
   applyScheduleHooks,
+  claimedAffected,
+  fingerprintClaims,
   hasHook,
+  CACHE_LAYER_METHODS,
   resolveCache,
   resolveExecutors,
 } from './plugin-host.js'
-export { MISSING_PLUGIN_HINT } from './missing-plugin.js'
+export {
+  lockfileClaim,
+  reachDigests,
+  type LockfileClaimHooks,
+  type LockfileClaimOptions,
+  type ReachGraph,
+} from './lockfile-claim.js'
 export { subscribeTelemetry, type TelemetryHandle } from './telemetry-host.js'
 // The bounded log-capture buffer every telemetry sink shares — see the
 // module header for why one implementation, not one per sink.
@@ -90,9 +123,6 @@ export type {
   TelemetrySink,
   TelemetrySource,
 } from './telemetry.js'
-// `diffOutputTrees` is the ONE tree-diff implementation — the verify verdict
-// and a serve's cross-machine fingerprint diff must never drift on it.
-export { diffOutputTrees } from './verify.js'
 export { deriveStableKeys } from './stable-keys.js'
 export type { DeriveStableKeysArgs, StableKey } from './stable-keys.js'
 export {
@@ -125,3 +155,4 @@ export type {
   RunSummaryRow,
   WhyDidThisRerun,
 } from './metrics.js'
+export { collectInfo, type CollectInfoOptions, type InfoFacts } from './doctor.js'

package/src/orchestrator/lockfile-claim.ts

@@ -0,0 +1,281 @@
+// The claimant's shell: what every lockfile plugin needs around its
+// parser. A plugin that keys each project on its own dependency closure
+// from a lockfile (`@vzn/vx-lockfile`) claims the file
+// (`VxPlugin.fingerprint`), folds one digest per project through `key`,
+// and answers `--affected` by digesting both sides of a change. Only the
+// parser differs per package manager; the memo, the per-run gate, the
+// fallback for a project the file does not list and the `--affected`
+// diff are one implementation here, so a third lockfile is a parser.
+//
+// The digests are memoised on disk under the cache dir by the file's
+// xxh3, so a warm run pays one read + hash + a small JSON read, never a
+// parse; within one process (a run, a watch cycle) the file's size and
+// mtime gate even the read; and per run the read happens once (a WeakMap
+// on the context core hands every `key` call of a run).
+
+import path from 'node:path'
+import { rename, stat } from 'node:fs/promises'
+import { xxh3hex } from '../util/index.js'
+import type { TaskNode } from '../graph/index.js'
+import type {
+  FingerprintChange,
+  FingerprintClaim,
+  FingerprintContext,
+  KeyHookContext,
+} from './plugin.js'
+
+export interface LockfileClaimOptions {
+  /** The root-relative lockfile name, one of `WORKSPACE_FINGERPRINT_FILES`. */
+  readonly file: string
+  /**
+   * Every project's digest from the file's text: importer directory
+   * (root-relative POSIX, `.` for the root) → digest. Called once per
+   * distinct content; must be deterministic and throw on a file it
+   * cannot read (the plugin's name heads the error).
+   */
+  readonly digest: (text: string) => ReadonlyMap<string, string>
+  /** Folded into the memo's identity: bump when `digest` folds differently. */
+  readonly version: number
+  /**
+   * `'project'` (default): each task folds its own project's digest.
+   * `'workspace'`: the whole file's hash into every task — the coarse key
+   * core would fold, through the plugin.
+   */
+  readonly scope?: 'project' | 'workspace'
+  /**
+   * The key part's name, as `vx why` shows it under the plugin's name
+   * (`@vzn/vx-lockfile/pnpm`). Default `'deps'`.
+   */
+  readonly part?: string
+}
+
+/** The two hooks a lockfile plugin spreads into `definePlugin`. */
+export interface LockfileClaimHooks {
+  readonly fingerprint: FingerprintClaim
+  key(task: TaskNode, ctx: KeyHookContext): Promise<Readonly<Record<string, string>> | undefined>
+}
+
+interface Digests {
+  /** xxh3 of the lockfile bytes; '' when the file is absent. */
+  readonly lock: string
+  readonly importers: ReadonlyMap<string, string>
+}
+
+interface Memo {
+  version: number
+  lock: string
+  importers: Record<string, string>
+}
+
+export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks {
+  const { file, digest, version } = options
+  const scope = options.scope ?? 'project'
+  const part = options.part ?? 'deps'
+  if (scope !== 'project' && scope !== 'workspace') {
+    throw new Error(`scope must be 'project' or 'workspace', not ${JSON.stringify(scope)}`)
+  }
+  // Per workspace root: what the last read saw. `size` + `mtimeMs` gate a
+  // re-read; the content hash decides whether the digests are current.
+  const seen = new Map<string, { size: number; mtimeMs: number; digests: Digests }>()
+  // Per run: every `key` call of one run gets the same context object.
+  const perRun = new WeakMap<object, Promise<Digests>>()
+
+  const load = async (workspaceRoot: string, cacheDir: string): Promise<Digests> => {
+    const full = path.join(workspaceRoot, file)
+    let st: { size: number; mtimeMs: number }
+    try {
+      st = await stat(full)
+    } catch {
+      const digests: Digests = { lock: '', importers: new Map() }
+      seen.set(workspaceRoot, { size: -1, mtimeMs: -1, digests })
+      return digests
+    }
+    const last = seen.get(workspaceRoot)
+    if (last !== undefined && last.size === st.size && last.mtimeMs === st.mtimeMs) {
+      return last.digests
+    }
+    const bytes = await Bun.file(full).bytes()
+    const lock = xxh3hex(bytes)
+    if (last !== undefined && last.digests.lock === lock) {
+      seen.set(workspaceRoot, { size: st.size, mtimeMs: st.mtimeMs, digests: last.digests })
+      return last.digests
+    }
+    const memoFile = path.join(cacheDir, 'lockfile-claims', `${file}.json`)
+    const importers =
+      scope === 'workspace'
+        ? new Map<string, string>()
+        : ((await readMemo(memoFile, version, lock)) ??
+          (await computeAndMemo(memoFile, version, lock, digest(decode(bytes)))))
+    const digests: Digests = { lock, importers }
+    seen.set(workspaceRoot, { size: st.size, mtimeMs: st.mtimeMs, digests })
+    return digests
+  }
+  const loadOnce = (ctx: KeyHookContext): Promise<Digests> => {
+    let p = perRun.get(ctx)
+    if (p === undefined) {
+      p = load(ctx.workspaceRoot, ctx.cacheDir)
+      perRun.set(ctx, p)
+    }
+    return p
+  }
+
+  return {
+    fingerprint: {
+      files: [file],
+      affected(change: FingerprintChange, ctx: FingerprintContext) {
+        // One side absent: the file appeared or went — every project's
+        // installed tree is in question, and core's answer (all) is right.
+        if (change.before === null || change.after === null) return undefined
+        if (scope === 'workspace') return undefined
+        const before = digest(decode(change.before))
+        const after = digest(decode(change.after))
+        const names: string[] = []
+        for (const p of ctx.projects) {
+          const importer = importerOf(ctx.workspaceRoot, p.dir)
+          if (digestFor(before, importer) !== digestFor(after, importer)) names.push(p.name)
+        }
+        return names
+      },
+    },
+    async key(task, ctx) {
+      const digests = await loadOnce(ctx)
+      if (digests.lock === '') return undefined
+      if (scope === 'workspace') return { [part]: digests.lock }
+      return {
+        [part]: digestFor(digests.importers, importerOf(ctx.workspaceRoot, task.projectDir)),
+      }
+    },
+  }
+}
+
+/**
+ * A project's digest: its own importer's, or — for a project the lockfile
+ * has no importer for (outside the workspace's `packages`) — the root
+ * importer's, the only installed tree it can resolve from. A file with
+ * neither folds a constant.
+ */
+function digestFor(importers: ReadonlyMap<string, string>, importer: string): string {
+  return importers.get(importer) ?? importers.get('.') ?? 'no-importer'
+}
+
+/** The lockfile's importer path for a project directory: `.` for the root, POSIX otherwise. */
+function importerOf(workspaceRoot: string, projectDir: string): string {
+  const rel = path.relative(workspaceRoot, projectDir)
+  return rel === '' ? '.' : rel.split(path.sep).join('/')
+}
+
+async function readMemo(
+  memoFile: string,
+  version: number,
+  lock: string,
+): Promise<Map<string, string> | undefined> {
+  try {
+    const memo = (await Bun.file(memoFile).json()) as Memo
+    if (memo.version !== version || memo.lock !== lock) return undefined
+    return new Map(Object.entries(memo.importers))
+  } catch {
+    return undefined
+  }
+}
+
+async function computeAndMemo(
+  memoFile: string,
+  version: number,
+  lock: string,
+  importers: ReadonlyMap<string, string>,
+): Promise<ReadonlyMap<string, string>> {
+  const memo: Memo = { version, lock, importers: Object.fromEntries(importers) }
+  // Write-then-rename: a reader never sees a half-written memo, and two
+  // concurrent runs each land a whole one.
+  const tmp = `${memoFile}.tmp-${process.pid}-${Date.now()}`
+  try {
+    await Bun.write(tmp, JSON.stringify(memo))
+    await rename(tmp, memoFile)
+  } catch {
+    // The memo is a speed-up, never a requirement: the digests are
+    // computed either way, and the next run computes them again.
+  }
+  return importers
+}
+
+function decode(bytes: Uint8Array): string {
+  return new TextDecoder().decode(bytes)
+}
+
+// --- Reach digests -----------------------------------------------------------
+
+/** A dependency graph: one material string per node and its out-edges by index. */
+export interface ReachGraph {
+  readonly material: readonly string[]
+  readonly edges: ReadonlyArray<readonly number[]>
+}
+
+/**
+ * One digest per node over everything the node reaches, Merkle-style: a
+ * change anywhere in a node's reach moves its digest, a change elsewhere
+ * does not. Lockfiles carry dependency cycles, so the unit is the
+ * strongly connected component: Tarjan's walk (iterative — a dependency
+ * chain can be thousands deep) emits components children-first, and each
+ * folds its members' material (sorted) and its child components' digests
+ * (sorted). O(nodes + edges): 1000 importers over 3000 packages digest in
+ * ~20 ms where one traversal per importer took 400.
+ */
+export function reachDigests(g: ReachGraph): string[] {
+  const n = g.material.length
+  const idx = new Int32Array(n).fill(-1)
+  const low = new Int32Array(n)
+  const onStack = new Uint8Array(n)
+  const stack: number[] = []
+  const comp = new Int32Array(n).fill(-1)
+  const compHash: string[] = []
+  let counter = 0
+  for (let root = 0; root < n; root++) {
+    if (idx[root] !== -1) continue
+    const frames: Array<[number, number]> = [[root, 0]]
+    idx[root] = low[root] = counter++
+    stack.push(root)
+    onStack[root] = 1
+    while (frames.length > 0) {
+      const frame = frames[frames.length - 1]!
+      const v = frame[0]
+      const out = g.edges[v]!
+      if (frame[1] < out.length) {
+        const w = out[frame[1]++]!
+        if (idx[w] === -1) {
+          idx[w] = low[w] = counter++
+          stack.push(w)
+          onStack[w] = 1
+          frames.push([w, 0])
+        } else if (onStack[w] === 1) {
+          low[v] = Math.min(low[v]!, idx[w]!)
+        }
+        continue
+      }
+      frames.pop()
+      if (frames.length > 0) {
+        const u = frames[frames.length - 1]![0]
+        low[u] = Math.min(low[u]!, low[v]!)
+      }
+      if (low[v] !== idx[v]) continue
+      const members: number[] = []
+      for (;;) {
+        const w = stack.pop()!
+        onStack[w] = 0
+        comp[w] = compHash.length
+        members.push(w)
+        if (w === v) break
+      }
+      const id = compHash.length
+      const children = new Set<string>()
+      for (const m of members) {
+        for (const w of g.edges[m]!) if (comp[w] !== id) children.add(compHash[comp[w]!]!)
+      }
+      let h = Bun.hash.xxHash3(`members:${members.length}`)
+      for (const m of members.map((m) => g.material[m]!).sort()) h = Bun.hash.xxHash3(`${m}\n`, h)
+      h = Bun.hash.xxHash3(`children:${children.size}`, h)
+      for (const c of [...children].sort()) h = Bun.hash.xxHash3(`${c}\n`, h)
+      compHash.push(h.toString(16).padStart(16, '0'))
+    }
+  }
+  return Array.from({ length: n }, (_, i) => compHash[comp[i]!]!)
+}