@vzn/vx 0.0.649 → 0.0.651

package/src/orchestrator/lockfile-claim.ts

@@ -7,14 +7,22 @@
 // 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,
-// mtime, ctime and inode gate even the read; and per run the read happens once (a WeakMap
-// on the context core hands every `key` call of a run).
+// A run's key reads each project's digest from `.vx/dependencies.lock.json`
+// (`KeyHookContext.locked`), never the file: only `vx lock` and
+// `--affected` digest it, and a run whose extra file (a `link:` directory,
+// edited with no install) moved since the lock, as the record is stale
+// for it then. What the `discover` and `project` stages read
+// (the edges, the recorded names) is memoised in cache.db
+// (`lockfile_memos`, one row per lockfile and claimant) by the file's xxh3,
+// so a warm run pays one read + hash + one row read, never a parse; within
+// one process (a run, a watch cycle) the file's size, mtime, ctime and
+// inode gate even the read. A run's read leaves the digests out (most of a
+// parse: 9-25 ms on this repo's bun.lock, against 4-13 for the text), and
+// `vx lock` adds them to the memo.
 
 import path from 'node:path'
-import { rename, stat } from 'node:fs/promises'
+import { stat } from 'node:fs/promises'
+import { type LockfileMemo, readLockfileMemo, writeLockfileMemo } from '../cache/index.js'
 import { relPosix, UserError, xxh3, xxh3hex } from '../util/index.js'
 import type { TaskNode } from '../graph/index.js'
 import type {
@@ -62,6 +70,12 @@ export interface LockfileClaimOptions {
    * parse. Called once per distinct content, under either scope.
    */
   readonly importers?: (text: string) => ReadonlyMap<string, LockfileImporter>
+  /**
+   * Each importer's recorded dependency names, from the same text, kept in
+   * the memo so a staleness check reads them without a parse. Called once
+   * per distinct content.
+   */
+  readonly recorded?: (text: string) => ReadonlyMap<string, readonly string[]>
 }
 
 /**
@@ -89,33 +103,35 @@ export interface LockfileClaimHooks {
     readonly workspaceRoot: string
     readonly cacheDir: string
   }): Promise<ReadonlyMap<string, LockfileImporter> | undefined>
+  /** `recorded`'s answer for the file as it is now, as `importers` reads it; undefined when the file is absent or `recorded` is unset. */
+  recorded(ctx: {
+    readonly workspaceRoot: string
+    readonly cacheDir: string
+  }): Promise<ReadonlyMap<string, ReadonlySet<string>> | undefined>
 }
 
 interface Digests {
-  /** xxh3 of the lockfile bytes; '' when the file is absent. */
+  /** xxh3 of the lockfile bytes and the extra files' hashes; '' when the file is absent. */
   readonly lock: string
-  readonly importers: ReadonlyMap<string, string>
+  /** xxh3 of the lockfile bytes alone. */
+  readonly bytes: string
+  /** The extra files the digests read. */
+  readonly extras: readonly string[]
+  /** Each importer's digest; undefined when the read that made this left them out. */
+  readonly importers: ReadonlyMap<string, string> | undefined
   readonly edges: ReadonlyMap<string, LockfileImporter>
-}
-
-interface Memo {
-  version: number
-  claimant: string
-  lock: string
-  /** `extraFiles` → content hash when the digests were computed. */
-  extras?: Record<string, string>
-  importers: Record<string, string>
-  edges?: Record<string, LockfileImporter>
+  readonly recorded: ReadonlyMap<string, ReadonlySet<string>> | undefined
 }
 
 /**
- * A root-relative extra file's content hash, '' when absent; a path leaving
- * the root is never read. One there but unreadable (EACCES, a symlink loop)
- * refuses, as a settings file does: folded as '', it keyed as no file at all.
+ * A root-relative extra file's content hash, '' when absent. A path above
+ * the root is read too: a `file:` or `link:` directory beside the checkout
+ * is what a task imports, and left unread an edit in it moved no key. One
+ * there but unreadable (EACCES, a symlink loop) refuses, as a settings file
+ * does: folded as '', it keyed as no file at all.
  */
-async function hashExtra(workspaceRoot: string, rel: string): Promise<string> {
-  if (path.isAbsolute(rel) || rel.split(/[\\/]/).includes('..')) return 'outside-root'
-  const abs = path.join(workspaceRoot, rel)
+export async function hashExtra(workspaceRoot: string, rel: string): Promise<string> {
+  const abs = path.resolve(workspaceRoot, rel)
   try {
     return xxh3hex(await Bun.file(abs).bytes())
   } catch (err) {
@@ -165,7 +181,7 @@ function identityOf(st: { size: number; mtimeMs: number; ctimeMs: number; ino: n
 async function statsOf(workspaceRoot: string, rels: readonly string[]): Promise<string[]> {
   return Promise.all(
     rels.map((rel) =>
-      stat(path.join(workspaceRoot, rel)).then(
+      stat(path.resolve(workspaceRoot, rel)).then(
         (st) => (st.isDirectory() ? hashExtra(workspaceRoot, rel) : identityOf(st)),
         () => 'gone',
       ),
@@ -202,6 +218,7 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
       String(digest),
       String(options.extraFiles ?? ''),
       String(options.importers ?? ''),
+      String(options.recorded ?? ''),
     ].join('\0'),
   )
   if (scope !== 'project' && scope !== 'workspace') {
@@ -216,48 +233,84 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
       extras: readonly string[]
       extraStats: Readonly<Record<string, string>>
       digests: Digests
+      /** The memo a run found no index to keep in (a discover before the first run's open). */
+      unsaved?: LockfileMemo
     }
   >()
+  // Workspace scope with nothing else to keep has nothing a memo saves.
+  const memoises =
+    scope === 'project' || options.importers !== undefined || options.recorded !== undefined
+  const readMemo = (cacheDir: string, lock: string) => {
+    const memo = readLockfileMemo(cacheDir, file, claimant)
+    if (memo === undefined || memo.version !== version || memo.lock !== lock) return undefined
+    return memo
+  }
   // Per run: every `key` call of one run gets the same context object.
   const perRun = new WeakMap<object, Promise<Digests>>()
+  const lockedPerRun = new WeakMap<
+    object,
+    Promise<((dir: string) => string | undefined) | undefined>
+  >()
 
-  const load = async (workspaceRoot: string, cacheDir: string): Promise<Digests> => {
+  /** `withDigests`: each importer's digest too, which only `vx lock` and `--affected` read. */
+  const load = async (
+    workspaceRoot: string,
+    cacheDir: string,
+    withDigests: boolean,
+  ): Promise<Digests> => {
     const full = path.join(workspaceRoot, file)
     let identity: string
     try {
       identity = identityOf(await stat(full))
     } catch {
-      const digests: Digests = { lock: '', importers: new Map(), edges: new Map() }
+      const digests: Digests = {
+        lock: '',
+        bytes: '',
+        extras: [],
+        importers: new Map(),
+        edges: new Map(),
+        recorded: undefined,
+      }
       seen.set(workspaceRoot, { identity: 'gone', extras: [], extraStats: {}, digests })
       return digests
     }
     const last = seen.get(workspaceRoot)
-    if (last !== undefined && last.identity === identity) {
+    if (
+      last !== undefined &&
+      last.identity === identity &&
+      (!withDigests || last.digests.importers !== undefined)
+    ) {
       const now = await statsOf(workspaceRoot, last.extras)
       if (now.every((s, i) => s === last.extraStats[last.extras[i]!])) {
+        if (last.unsaved !== undefined && writeLockfileMemo(cacheDir, file, claimant, last.unsaved))
+          delete last.unsaved
         return last.digests
       }
     }
     const bytes = await Bun.file(full).bytes()
     const lockHash = xxh3hex(bytes)
-    const memoFile = path.join(cacheDir, 'lockfile-claims', `${file}.json`)
     // The extra files the last digest read, and their hashes now: a warm run
     // re-hashes the files the memo names and never parses to learn them.
-    const memo = await readMemo(memoFile, version, claimant, lockHash)
+    const memo = memoises ? readMemo(cacheDir, lockHash) : undefined
     let extras: Record<string, string> = {}
     let extraStats: Record<string, string> = {}
     let importers: ReadonlyMap<string, string> | undefined
     let edges: ReadonlyMap<string, LockfileImporter> = new Map()
-    if (memo !== undefined) {
+    let recorded: ReadonlyMap<string, readonly string[]> | undefined
+    let unsaved: LockfileMemo | undefined
+    let served = false
+    if (memo !== undefined && (!withDigests || memo.importers !== null)) {
       const now = await hashExtras(workspaceRoot, Object.keys(memo.extras))
       if (Object.entries(memo.extras).every(([rel, h]) => now.hashes[rel] === h)) {
+        served = true
         extras = memo.extras
         extraStats = now.stats
-        importers = memo.importers
-        edges = memo.edges
+        importers = memo.importers === null ? undefined : new Map(Object.entries(memo.importers))
+        edges = new Map(Object.entries(memo.edges as Record<string, LockfileImporter>))
+        recorded = memo.recorded === undefined ? undefined : new Map(Object.entries(memo.recorded))
       }
     }
-    if (importers === undefined) {
+    if (!served) {
       const text = decode(bytes)
       const rels = [...new Set(options.extraFiles?.(text) ?? [])].sort()
       const now = await hashExtras(workspaceRoot, rels)
@@ -266,11 +319,21 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
       importers =
         scope === 'workspace'
           ? new Map<string, string>()
-          : digest(text, new Map(Object.entries(extras)))
+          : withDigests
+            ? digest(text, new Map(Object.entries(extras)))
+            : undefined
       edges = options.importers?.(text) ?? new Map()
-      // Workspace scope with no edges to keep has nothing a memo saves.
-      if (scope === 'project' || options.importers !== undefined) {
-        await writeMemo(memoFile, { version, claimant, lock: lockHash }, extras, importers, edges)
+      recorded = options.recorded?.(text)
+      if (memoises) {
+        const kept: LockfileMemo = {
+          version,
+          lock: lockHash,
+          extras,
+          importers: importers === undefined ? null : Object.fromEntries(importers),
+          edges: Object.fromEntries(edges),
+          ...(recorded !== undefined ? { recorded: Object.fromEntries(recorded) } : {}),
+        }
+        if (!writeLockfileMemo(cacheDir, file, claimant, kept)) unsaved = kept
       }
     }
     const rels = Object.keys(extras)
@@ -278,14 +341,56 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
       rels.length === 0
         ? lockHash
         : xxh3hex([lockHash, ...rels.map((r) => `${r}\0${extras[r]}`)].join('\0'))
-    const digests: Digests = { lock, importers, edges }
-    seen.set(workspaceRoot, { identity, extras: rels, extraStats, digests })
+    const digests: Digests = {
+      lock,
+      bytes: lockHash,
+      extras: rels,
+      importers,
+      edges,
+      recorded:
+        recorded === undefined
+          ? undefined
+          : new Map([...recorded].map(([i, names]) => [i, new Set(names)])),
+    }
+    seen.set(workspaceRoot, {
+      identity,
+      extras: rels,
+      extraStats,
+      digests,
+      ...(unsaved !== undefined ? { unsaved } : {}),
+    })
     return digests
   }
+  /**
+   * Each project's digest for this run: the lock's, unless an extra file
+   * it records moved since (then a digest of the file as it is now, as
+   * `vx lock` would record it); undefined when the file is absent.
+   */
+  const lockedOnce = (
+    ctx: KeyHookContext,
+  ): Promise<((dir: string) => string | undefined) | undefined> => {
+    let p = lockedPerRun.get(ctx)
+    if (p === undefined) {
+      p = (async () => {
+        const rec = await ctx.locked(file)
+        if (rec === undefined) return undefined
+        const rels = Object.keys(rec.extras)
+        const now = await Promise.all(rels.map((rel) => hashExtra(ctx.workspaceRoot, rel)))
+        if (now.every((h, i) => h === rec.extras[rels[i]!])) {
+          return (dir: string) => rec.digest(dir)
+        }
+        const digests = await load(ctx.workspaceRoot, ctx.cacheDir, true)
+        const importers = digests.importers!
+        return (dir: string) => digestFor(importers, importerOf(ctx.workspaceRoot, dir))
+      })()
+      lockedPerRun.set(ctx, p)
+    }
+    return p
+  }
   const loadOnce = (ctx: KeyHookContext): Promise<Digests> => {
     let p = perRun.get(ctx)
     if (p === undefined) {
-      p = load(ctx.workspaceRoot, ctx.cacheDir)
+      p = load(ctx.workspaceRoot, ctx.cacheDir, false)
       perRun.set(ctx, p)
     }
     return p
@@ -333,14 +438,31 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
         }
         return names
       },
+      // What `vx lock` commits, so `--affected` reads the base's digests
+      // instead of parsing the base's file.
+      async digests(_file: string, ctx: FingerprintContext) {
+        if (scope === 'workspace') return undefined
+        const digests = await load(ctx.workspaceRoot, ctx.cacheDir, true)
+        if (digests.lock === '') return undefined
+        const importers = digests.importers!
+        return {
+          hash: digests.bytes,
+          projects: Object.fromEntries(
+            ctx.projects.map((p) => [
+              p.name,
+              digestFor(importers, importerOf(ctx.workspaceRoot, p.dir)),
+            ]),
+          ),
+          ...(digests.extras.length > 0 ? { extras: digests.extras } : {}),
+        }
+      },
       ...(options.extraFiles !== undefined
         ? {
             // The memo records which files these exact bytes name, for this
             // parser: `--affected` asks on every diff, and a cold parse of
             // a large lockfile was most of its selection's cost.
             async extraFiles(_file: string, bytes: Uint8Array, ctx: FingerprintContext) {
-              const memoFile = path.join(ctx.cacheDir, 'lockfile-claims', `${file}.json`)
-              const memo = await readMemo(memoFile, version, claimant, xxh3hex(bytes))
+              const memo = memoises ? readMemo(ctx.cacheDir, xxh3hex(bytes)) : undefined
               return memo !== undefined
                 ? Object.keys(memo.extras)
                 : options.extraFiles!(decode(bytes))
@@ -349,17 +471,22 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
         : {}),
     },
     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)),
+      if (scope === 'project') {
+        const digestOf = await lockedOnce(ctx)
+        const digest = digestOf?.(task.projectDir)
+        return digest === undefined ? undefined : { [part]: digest }
       }
+      const digests = await loadOnce(ctx)
+      return digests.lock === '' ? undefined : { [part]: digests.lock }
     },
     async importers(ctx) {
-      const digests = await load(ctx.workspaceRoot, ctx.cacheDir)
+      const digests = await load(ctx.workspaceRoot, ctx.cacheDir, false)
       return digests.lock === '' ? undefined : digests.edges
     },
+    async recorded(ctx) {
+      const digests = await load(ctx.workspaceRoot, ctx.cacheDir, false)
+      return digests.lock === '' ? undefined : digests.recorded
+    },
   }
 }
 
@@ -394,59 +521,6 @@ function importerOf(workspaceRoot: string, projectDir: string): string {
   return relPosix(workspaceRoot, projectDir) || '.'
 }
 
-async function readMemo(
-  memoFile: string,
-  version: number,
-  claimant: string,
-  lock: string,
-): Promise<
-  | {
-      extras: Record<string, string>
-      importers: Map<string, string>
-      edges: Map<string, LockfileImporter>
-    }
-  | undefined
-> {
-  try {
-    const memo = (await Bun.file(memoFile).json()) as Memo
-    if (memo.version !== version || memo.claimant !== claimant || memo.lock !== lock) {
-      return undefined
-    }
-    return {
-      extras: memo.extras ?? {},
-      importers: new Map(Object.entries(memo.importers)),
-      edges: new Map(Object.entries(memo.edges ?? {})),
-    }
-  } catch {
-    return undefined
-  }
-}
-
-async function writeMemo(
-  memoFile: string,
-  identity: Pick<Memo, 'version' | 'claimant' | 'lock'>,
-  extras: Record<string, string>,
-  importers: ReadonlyMap<string, string>,
-  edges: ReadonlyMap<string, LockfileImporter>,
-): Promise<void> {
-  const memo: Memo = {
-    ...identity,
-    extras,
-    importers: Object.fromEntries(importers),
-    ...(edges.size > 0 ? { edges: Object.fromEntries(edges) } : {}),
-  }
-  // 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.
-  }
-}
-
 function decode(bytes: Uint8Array): string {
   return new TextDecoder().decode(bytes)
 }

package/src/orchestrator/miss-save.ts

@@ -146,6 +146,8 @@ export interface SaveMissArgs {
 export interface SaveFacts {
   saveMs?: number
   artifactBytes?: number
+  /** The saved files' bytes, as a hit's `outputBytes` counts them: the row's `outputs`. */
+  outputBytes?: number
   /** The entry landed: the outcome's `saved`, set only once it has. */
   saved?: true
 }
@@ -239,6 +241,8 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
       },
     })
     endSave()
+    const bytes = cache.outputBytes?.(a.hash)
+    if (bytes !== undefined) facts.outputBytes = bytes
     if (a.measure === true) {
       facts.saveMs = Math.round(performance.now() - saveStart)
       // No local artifact (local writes off): no size to say.
@@ -294,9 +298,26 @@ export type UnsavedArgs = Pick<
  * A miss that ran here and saves nothing (it failed, the policy writes
  * nothing, an upstream failed, its key no longer held) still wrote its
  * outputs, and a same-project reader after it must see them as it sees a
- * save's: resolved and marked the same way.
+ * save's: resolved and marked the same way. Returns their bytes, the
+ * row's `outputs`: blank, an unsaved miss read as one that wrote nothing.
  */
-export async function markUnsaved(a: UnsavedArgs): Promise<void> {
+export async function markUnsaved(a: UnsavedArgs): Promise<number> {
+  const { outputFiles, wsOutputFiles } = await resolveUnsaved(a)
+  markWritten(a, outputFiles, wsOutputFiles)
+  return sizeOf(a.node.projectDir, outputFiles) + sizeOf(a.workspaceRoot, wsOutputFiles)
+}
+
+/** An unsaved miss nothing reads after: only the bytes of its outputs, its row's `outputs`. */
+export async function unsavedOutputBytes(
+  a: Pick<UnsavedArgs, 'node' | 'workspaceRoot' | 'nestedProjectDirs' | 'outputs' | 'wsOutputs'>,
+): Promise<number> {
+  const { outputFiles, wsOutputFiles } = await resolveUnsaved(a)
+  return sizeOf(a.node.projectDir, outputFiles) + sizeOf(a.workspaceRoot, wsOutputFiles)
+}
+
+async function resolveUnsaved(
+  a: Pick<UnsavedArgs, 'node' | 'workspaceRoot' | 'nestedProjectDirs' | 'outputs' | 'wsOutputs'>,
+): Promise<{ outputFiles: string[]; wsOutputFiles: string[] }> {
   const endResolve = span('miss: resolve outputs')
   const outputFiles = await resolveOutputs({
     projectDir: a.node.projectDir,
@@ -308,7 +329,14 @@ export async function markUnsaved(a: UnsavedArgs): Promise<void> {
     outputs: a.wsOutputs,
   })
   endResolve()
-  markWritten(a, outputFiles, wsOutputFiles)
+  return { outputFiles, wsOutputFiles }
+}
+
+/** The bytes of `files` (absolute, or under `base`); one gone since it was listed counts none. */
+function sizeOf(base: string, files: readonly string[]): number {
+  let n = 0
+  for (const f of files) n += statSync(path.resolve(base, f), { throwIfNoEntry: false })?.size ?? 0
+  return n
 }
 
 /**

package/src/orchestrator/persistent-task.ts

@@ -283,7 +283,9 @@ export async function executePersistentTask(args: ExecuteArgs): Promise<TaskOutc
     const message = err instanceof Error ? err.message : String(err)
     // The task's OWN stream, not the process's: the frame is where a
     // reader looks for why a task failed, and a run with a custom logger
-    // (an embedder) never saw a bare stderr write at all.
+    // (an embedder) never saw a bare stderr write at all. What waited on
+    // an open line goes first.
+    ends.end()
     log.taskStderr(
       node,
       ends.own(`[vx] ${node.id}: persistent task failed to become ready: ${message}\n`),

package/src/orchestrator/plan.ts

@@ -225,7 +225,11 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
     )
     const dependents = new Map<string, string[]>()
     for (const node of args.nodes.values())
-      for (const dep of node.deps) dependents.set(dep, [...(dependents.get(dep) ?? []), node.id])
+      for (const dep of node.deps) {
+        const ds = dependents.get(dep)
+        if (ds === undefined) dependents.set(dep, [node.id])
+        else ds.push(node.id)
+      }
     for (const id of idleServers(args.nodes, dependents, restoreTier))
       cacheStatusById.set(id, 'not-started')
   }

package/src/orchestrator/plugin-host.ts

@@ -33,6 +33,7 @@ import type {
   DiscoverContext,
   ExecutorContext,
   FingerprintChange,
+  FingerprintDigests,
   FingerprintContext,
   GraphHookContext,
   KeyHookContext,
@@ -44,6 +45,7 @@ import type {
   ConfigContext,
 } from './plugin.js'
 import type { ProjectMeta } from '../workspace/index.js'
+import { hashExtra } from './lockfile-claim.js'
 
 /** `a string`, `an array`, `null`, `a number` — for a refusal that names what came back. */
 function describeValue(v: unknown): string {
@@ -392,6 +394,65 @@ export async function claimedAffected(
   ctx: FingerprintContext,
 ): Promise<Set<string> | undefined> {
   const answer = await safe(plugin, 'fingerprint', () => plugin.fingerprint!.affected(change, ctx))
+  return projectNames(plugin, answer, ctx)
+}
+
+/**
+ * `FingerprintClaim.digests`' answer for `file`, each extra file it names
+ * with its hash now (`hashExtra`, as a run checks it); `undefined` when the
+ * plugin has none. A digest of a name no project carries, or a value that
+ * is not a string, is refused by name: `vx lock` would commit it.
+ */
+export async function claimedDigests(
+  plugin: VxPlugin,
+  file: string,
+  ctx: FingerprintContext,
+): Promise<
+  | {
+      hash: string
+      projects: FingerprintDigests['projects']
+      extras?: Readonly<Record<string, string>>
+    }
+  | undefined
+> {
+  const digests = plugin.fingerprint?.digests
+  if (digests === undefined) return undefined
+  const answer: unknown = await safe(plugin, 'fingerprint', () =>
+    digests.call(plugin.fingerprint, file, ctx),
+  )
+  if (answer === undefined) return undefined
+  const { hash, projects, extras } = (answer ?? {}) as Partial<FingerprintDigests>
+  if (
+    typeof hash !== 'string' ||
+    typeof projects !== 'object' ||
+    projects === null ||
+    Object.values(projects).some((d) => typeof d !== 'string') ||
+    (extras !== undefined &&
+      (!Array.isArray(extras) || extras.some((rel) => typeof rel !== 'string')))
+  ) {
+    throw new UserError(
+      `plugin '${plugin.name}' failed in fingerprint: digests returned ${describeValue(answer)}, not { hash, projects: { name: digest }, extras?: [path] }`,
+    )
+  }
+  const known = new Set(ctx.projects.map((p) => p.name))
+  const stray = Object.keys(projects).find((n) => !known.has(n))
+  if (stray !== undefined) {
+    throw new UserError(
+      `plugin '${plugin.name}' failed in fingerprint: digest of ${JSON.stringify(stray)}, which is not a project in this workspace`,
+    )
+  }
+  if (extras === undefined || extras.length === 0) return { hash, projects }
+  const hashed = await Promise.all(
+    extras.map(async (rel) => [rel, await hashExtra(ctx.workspaceRoot, rel)] as const),
+  )
+  return { hash, projects, extras: Object.fromEntries(hashed) }
+}
+
+async function projectNames(
+  plugin: VxPlugin,
+  answer: unknown,
+  ctx: FingerprintContext,
+): Promise<Set<string> | undefined> {
   if (answer === undefined) return undefined
   // A plain object is no list: `for…of` threw "is not iterable", naming
   // neither the plugin nor the hook.

package/src/orchestrator/plugin.ts

@@ -27,9 +27,9 @@ import {
   type PluginSecrets,
   SecretBroker,
   thrownMessage,
-  ui,
   UserError,
 } from '../util/index.js'
+import * as ui from '../ui/index.js'
 import type { ProjectMeta } from '../workspace/index.js'
 import type { EventBus, Logger, RunStartInfo } from '../report/index.js'
 import type { CiContext } from './run-context.js'
@@ -460,7 +460,29 @@ export interface GraphHookContext extends BaseContext {
   readonly requested: readonly string[]
 }
 
-export interface KeyHookContext extends BaseContext {}
+export interface KeyHookContext extends BaseContext {
+  /**
+   * What `vx lock` recorded of the claimed `file` in
+   * `.vx/dependencies.lock.json` (`FingerprintClaim.digests`): a run keys
+   * from the record and never parses the file. Undefined when the file is
+   * absent and unrecorded. Refuses, naming `vx lock`, when the lock is
+   * absent or records no such present file; a recorded file whose bytes
+   * moved since refused the run before the key stage.
+   */
+  locked(file: string): Promise<LockedFile | undefined>
+}
+
+/** `KeyHookContext.locked`'s answer. */
+export interface LockedFile {
+  /**
+   * The other files the digests read → each one's hash then (`hashExtra`).
+   * Not checked by core: a `link:` directory is edited with no install,
+   * so a claimant whose extra file moved digests anew.
+   */
+  readonly extras: Readonly<Record<string, string>>
+  /** The project at `projectDir`'s digest; undefined when none. Refuses for a project the lock does not list. */
+  digest(projectDir: string): string | undefined
+}
 
 /** A plugin's claim on workspace-root files — see `VxPlugin.fingerprint`. */
 export interface FingerprintClaim {
@@ -491,6 +513,29 @@ export interface FingerprintClaim {
     bytes: Uint8Array,
     ctx: FingerprintContext,
   ): readonly string[] | Promise<readonly string[]>
+  /**
+   * Each project's digest of the claimed `file` as it is now, by project
+   * name, with `hash`, the xxh3 of the bytes they came from (`xxh3hex`),
+   * and `extras`, the other files they read. `vx lock` records them in
+   * `.vx/dependencies.lock.json` with each extra file's hash; a run keys
+   * from that record (`KeyHookContext.locked`), and `--affected`
+   * reads the base's copy there instead of asking `affected` to parse the
+   * base side, when its `hash` is the base file's xxh3. `undefined`:
+   * nothing to record.
+   */
+  digests?(
+    file: string,
+    ctx: FingerprintContext,
+  ): FingerprintDigests | undefined | Promise<FingerprintDigests | undefined>
+}
+
+/** `FingerprintClaim.digests`' answer. */
+export interface FingerprintDigests {
+  readonly hash: string
+  /** Project name → its digest of the file. */
+  readonly projects: Readonly<Record<string, string>>
+  /** Root-relative files besides `file` whose bytes the digests read (a `bun.lock` patch). */
+  readonly extras?: readonly string[]
 }
 
 export interface FingerprintChange {
@@ -527,9 +572,9 @@ export interface AdmitContext {
 }
 
 export interface ScheduleHookContext extends BaseContext {
-  /** The run's local cache handle — its `dbHandle()` holds the run history a policy can learn from. */
+  /** The run's local cache: `localHistory(localCache)` reads the run history a policy learns from. */
   readonly localCache: Cache
-  /** The run's branch (`currentBranch`), the timings a forecast reads first: pass it to `LocalHistoryProvider`. */
+  /** The run's branch (`currentBranch`), the timings a forecast reads first: pass it to `localHistory`. */
   readonly branch: string | null
   /** The refs the run reads, in order (`CacheContext.refs`): a remote's timings are read by them too. */
   readonly refs: readonly string[]