@mnstry/atelier 0.2.0-alpha.6 → 0.2.0-alpha.8

package/src/runtime/obsidian/machine-settings.mjs

@@ -0,0 +1,260 @@
+import { randomBytes as cryptoRandomBytes } from 'node:crypto'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { LOCAL_STATE_DIR, localStateRoot } from '../../project/config.mjs'
+import { checkManagedRoots } from '../../project/file-class.mjs'
+import { atomicReplacePrivateText, ensureContainedPrivateDirectory, readRegularTextNoFollow } from '../../project/private-state.mjs'
+import { OBSIDIAN_EXT_KEY, ObsidianContractRefusal, assertObsidianContract } from '../../projection/obsidian/contracts.mjs'
+import { refuse } from './errors.mjs'
+import { canonicalJson, closedObject, isPlainObject } from './documents.mjs'
+
+// Machine-private settings of the Obsidian maintenance runtime.
+//
+//   <data>/obsidian/<workspace-id>/state/settings/machine.json       mode, audiences, policy reference
+//   <data>/obsidian/<workspace-id>/state/settings/apply-policy.json  the installed apply policy
+//   <project>/.atelier-local/obsidian.json                           pointer: workspace id, optional data root
+//
+// Nothing here is project configuration and nothing here is ever serialized
+// into a note. The data directory sits outside every enrolled repository. The
+// pointer is the one ignored file a project gains: it holds the persisted
+// random workspace identity (never a hash of a checkout path, so moving a
+// checkout keeps its vaults) and, optionally, where this machine keeps the
+// data directory.
+
+export const MACHINE_SETTINGS_SCHEMA = 'atelier-obsidian-machine-settings/v1'
+export const LOCAL_POINTER_SCHEMA = 'atelier-obsidian-local-pointer/v1'
+export const LOCAL_POINTER_FILE = 'obsidian.json'
+export const MAINTENANCE_MODES = Object.freeze(['manual', 'automatic'])
+
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
+const DIGEST = /^sha256:[0-9a-f]{64}$/
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/
+
+const segment = (identifier) => identifier.replaceAll(':', '_')
+
+// ---------------------------------------------------------------------------
+// Where the data directory is
+// ---------------------------------------------------------------------------
+
+// Pure: computes a path from its arguments and touches nothing.
+export function defaultDataRoot({ platform = process.platform, env = process.env, homedir = os.homedir() } = {}) {
+  const flavor = platform === 'win32' ? path.win32 : path.posix
+  const absolute = (value) => typeof value === 'string' && value !== '' && flavor.isAbsolute(value)
+  if (platform === 'win32') {
+    if (!absolute(env.LOCALAPPDATA)) refuse('data-root-unresolvable', 'LOCALAPPDATA does not name an absolute directory')
+    return flavor.join(env.LOCALAPPDATA, 'Atelier')
+  }
+  if (!absolute(homedir)) refuse('data-root-unresolvable', 'the home directory is not an absolute path')
+  if (platform === 'darwin') return flavor.join(homedir, 'Library', 'Application Support', 'Atelier')
+  // A relative XDG_DATA_HOME is invalid by its specification and is ignored.
+  return flavor.join(absolute(env.XDG_DATA_HOME) ? env.XDG_DATA_HOME : flavor.join(homedir, '.local', 'share'), 'atelier')
+}
+
+// The data root for this run: an injected root, else the project's pointer,
+// else the local overlay preference, else the platform default. Pure. Under
+// the Node test runner the platform default refuses, so a test that forgot to
+// inject a root can never reach a person's real data directory.
+export function resolveDataRoot({ dataRoot, pointer = null, project = null, platform = process.platform, env = process.env, homedir } = {}) {
+  const preference = project?.localOverlay?.overlay?.preferences?.[OBSIDIAN_EXT_KEY]
+  const configured = dataRoot ?? pointer?.dataRoot ?? (isPlainObject(preference) ? preference.dataRoot : undefined)
+  if (configured !== undefined) {
+    if (typeof configured !== 'string' || !path.isAbsolute(configured)) refuse('data-root-not-absolute', 'a configured data root must be an absolute path')
+    return path.resolve(configured)
+  }
+  if (env.NODE_TEST_CONTEXT !== undefined) refuse('real-data-root-under-test', 'the platform data directory is never used under the test runner; inject a data root')
+  return defaultDataRoot({ platform, env, ...(homedir === undefined ? {} : { homedir }) })
+}
+
+export function workspaceStateRoot(dataRoot, workspaceId) {
+  if (typeof workspaceId !== 'string' || !IDENTIFIER.test(workspaceId)) refuse('invalid-workspace-identity', 'a workspace identity must be a contract identifier')
+  return path.join(dataRoot, 'obsidian', segment(workspaceId))
+}
+
+// Every enrolled repository root plus the directories the project itself
+// occupies. Private state may overlap none of them, in either direction.
+export function protectedRoots(project) {
+  const roots = new Set()
+  for (const repo of project?.repos ?? []) if (!repo.external && typeof repo.path === 'string') roots.add(path.resolve(repo.path))
+  if (typeof project?.configDir === 'string') roots.add(path.resolve(project.configDir))
+  return [...roots].sort()
+}
+
+export function assertOutsideRepositories({ managedRoot, repositoryRoots }) {
+  const guard = checkManagedRoots({ managedRoots: [managedRoot], repositoryRoots })
+  if (!guard.ok) refuse(guard.refusals[0].code, guard.refusals[0].message, { refusals: guard.refusals.map(({ code }) => code) })
+}
+
+// ---------------------------------------------------------------------------
+// The pointer a project keeps in its ignored local state
+// ---------------------------------------------------------------------------
+
+function validatePointer(document) {
+  closedObject(document, { required: ['schema', 'workspaceId'], optional: ['dataRoot'] }, 'invalid-local-pointer', 'the Obsidian pointer')
+  if (document.schema !== LOCAL_POINTER_SCHEMA) refuse('invalid-local-pointer', 'the Obsidian pointer names an unknown schema')
+  if (typeof document.workspaceId !== 'string' || !IDENTIFIER.test(document.workspaceId)) refuse('invalid-local-pointer', 'the Obsidian pointer carries no usable workspace identity')
+  if (document.dataRoot !== undefined && (typeof document.dataRoot !== 'string' || !path.isAbsolute(document.dataRoot))) {
+    refuse('invalid-local-pointer', 'the Obsidian pointer names a data root that is not an absolute path')
+  }
+  return document
+}
+
+export const localPointerPath = (project) => path.join(localStateRoot(project), LOCAL_POINTER_FILE)
+
+function readJsonFile(file, code, label) {
+  let text
+  try { text = readRegularTextNoFollow(file) } catch (error) {
+    if (error.code === 'ENOENT') return null
+    refuse(code, `${label} cannot be read`, { cause: error.code ?? String(error.message) })
+  }
+  try { return JSON.parse(text) } catch { return refuse(code, `${label} is not JSON`) }
+}
+
+export function readLocalPointer(project) {
+  const document = readJsonFile(localPointerPath(project), 'invalid-local-pointer', 'the Obsidian pointer')
+  return document === null ? null : validatePointer(document)
+}
+
+// The pointer is written only where the project's local state is proven
+// ignored, so a machine-local value can never be committed by accident.
+export function writeLocalPointer(project, pointer) {
+  validatePointer(pointer)
+  if (project?.localState?.ignored !== true) refuse('local-state-not-ignored', `${LOCAL_STATE_DIR}/ is not ignored in this project; the Obsidian pointer is not written`)
+  const directory = ensureContainedPrivateDirectory({ workspaceRoot: project.configDir, directory: localStateRoot(project), label: 'project local state' })
+  atomicReplacePrivateText(path.join(directory, LOCAL_POINTER_FILE), canonicalJson(pointer))
+  return pointer
+}
+
+// Reads the persisted workspace identity, or issues a random one and persists
+// it. `randomBytes` is injectable so tests are deterministic.
+export function ensureWorkspaceIdentity({ project, dataRoot, randomBytes = cryptoRandomBytes } = {}) {
+  const existing = readLocalPointer(project)
+  if (existing) return existing
+  const pointer = { schema: LOCAL_POINTER_SCHEMA, workspaceId: `ws-${randomBytes(12).toString('hex')}`, ...(dataRoot === undefined ? {} : { dataRoot: path.resolve(dataRoot) }) }
+  return writeLocalPointer(project, pointer)
+}
+
+// ---------------------------------------------------------------------------
+// Machine settings
+// ---------------------------------------------------------------------------
+
+function validateMachineSettings(document, workspaceId) {
+  closedObject(document, { required: ['schema', 'workspaceId', 'maintenanceMode', 'audienceAllow', 'applyPolicy', 'updatedAt'] }, 'invalid-machine-settings', 'machine settings')
+  if (document.schema !== MACHINE_SETTINGS_SCHEMA) refuse('invalid-machine-settings', 'machine settings name an unknown schema')
+  if (document.workspaceId !== workspaceId) refuse('invalid-machine-settings', 'machine settings belong to another workspace')
+  if (!MAINTENANCE_MODES.includes(document.maintenanceMode)) refuse('invalid-machine-settings', 'maintenanceMode must be manual or automatic')
+  if (!Array.isArray(document.audienceAllow) || document.audienceAllow.length > 64 || document.audienceAllow.some((item) => typeof item !== 'string' || !IDENTIFIER.test(item))
+    || new Set(document.audienceAllow).size !== document.audienceAllow.length) {
+    refuse('invalid-machine-settings', 'audienceAllow must be a list of distinct audience identifiers')
+  }
+  if (document.applyPolicy !== null) {
+    closedObject(document.applyPolicy, { required: ['policyId', 'version', 'digest'] }, 'invalid-machine-settings', 'the apply policy reference')
+    const { policyId, version, digest } = document.applyPolicy
+    if (typeof policyId !== 'string' || !IDENTIFIER.test(policyId) || !Number.isInteger(version) || version < 1 || typeof digest !== 'string' || !DIGEST.test(digest)) {
+      refuse('invalid-machine-settings', 'the apply policy reference is malformed')
+    }
+  }
+  if (typeof document.updatedAt !== 'string' || !TIMESTAMP.test(document.updatedAt)) refuse('invalid-machine-settings', 'updatedAt must be a UTC timestamp')
+  return document
+}
+
+// The defaults fail closed: edits are only queued, no audience is visible and
+// no apply policy is installed until the person says otherwise.
+export function defaultMachineSettings({ workspaceId, updatedAt }) {
+  return { schema: MACHINE_SETTINGS_SCHEMA, workspaceId, maintenanceMode: 'manual', audienceAllow: [], applyPolicy: null, updatedAt }
+}
+
+const settingsDirectory = (workspaceRoot) => ensureContainedPrivateDirectory({ workspaceRoot, directory: path.join(workspaceRoot, 'state', 'settings'), label: 'Obsidian machine settings' })
+const settingsFile = (workspaceRoot, name) => path.join(workspaceRoot, 'state', 'settings', name)
+
+export function readMachineSettings({ workspaceRoot, workspaceId }) {
+  const document = readJsonFile(settingsFile(workspaceRoot, 'machine.json'), 'invalid-machine-settings', 'machine settings')
+  return document === null ? null : validateMachineSettings(document, workspaceId)
+}
+
+export function writeMachineSettings({ workspaceRoot, workspaceId, settings, repositoryRoots }) {
+  validateMachineSettings(settings, workspaceId)
+  assertOutsideRepositories({ managedRoot: workspaceRoot, repositoryRoots })
+  fs.mkdirSync(workspaceRoot, { recursive: true, mode: 0o700 })
+  atomicReplacePrivateText(path.join(settingsDirectory(workspaceRoot), 'machine.json'), canonicalJson(settings))
+  return settings
+}
+
+// ---------------------------------------------------------------------------
+// Installed apply policy
+// ---------------------------------------------------------------------------
+
+// `digestOf` is the canonical digest of a policy, handed in by the caller that installs for a person (the command):
+// the decision that reads the policy recomputes that digest on every apply, so a policy that carries another one
+// could be installed and would then refuse every automatic apply. With it, such a policy is refused here, naming the
+// digest it has to carry. A digest is not a secret. The file of the person is never rewritten.
+export function installApplyPolicy({ workspaceRoot, workspaceId, policy, repositoryRoots, updatedAt, digestOf = null }) {
+  try { assertObsidianContract('apply-policy', policy) } catch (error) {
+    if (error instanceof ObsidianContractRefusal) refuse('invalid-apply-policy', 'the apply policy does not satisfy its contract', { errors: error.detail?.errors ?? [] })
+    throw error
+  }
+  if (policy.workspaceId !== workspaceId) refuse('invalid-apply-policy', 'the apply policy belongs to another workspace')
+  if (digestOf !== null) {
+    const expected = digestOf(policy)
+    if (policy.digest !== expected) refuse('policy-digest-mismatch', `the policy does not carry the digest of its content; it has to carry ${expected}`, { expected, carried: policy.digest })
+  }
+  const current = readMachineSettings({ workspaceRoot, workspaceId }) ?? defaultMachineSettings({ workspaceId, updatedAt })
+  assertOutsideRepositories({ managedRoot: workspaceRoot, repositoryRoots })
+  fs.mkdirSync(workspaceRoot, { recursive: true, mode: 0o700 })
+  atomicReplacePrivateText(path.join(settingsDirectory(workspaceRoot), 'apply-policy.json'), canonicalJson(policy))
+  return writeMachineSettings({ workspaceRoot, workspaceId, repositoryRoots, settings: { ...current, applyPolicy: { policyId: policy.policyId, version: policy.version, digest: policy.digest }, updatedAt } })
+}
+
+// Whether an automatic dispatch is authorized right now. Reads both files
+// from disk on every call; the engine calls this immediately before each
+// dispatch, so a revocation or a pause takes effect for the very next edit.
+// Anything missing, malformed or mismatched is "not authorized", never an
+// error that could be mistaken for permission.
+// `assumeAutomatic` answers "would automatic mode be authorized": the check `mode set automatic` makes before it writes.
+export function authorizeAutomaticApply({ workspaceRoot, workspaceId, assumeAutomatic = false }) {
+  const denied = (reason) => ({ authorized: false, reason, policy: null })
+  let settings
+  try { settings = readMachineSettings({ workspaceRoot, workspaceId }) } catch { return denied('machine-settings-invalid') }
+  if (!settings) return denied('machine-settings-absent')
+  if (settings.maintenanceMode !== 'automatic' && assumeAutomatic !== true) return denied('maintenance-mode-manual')
+  if (settings.applyPolicy === null) return denied('no-apply-policy-installed')
+  let policy
+  try {
+    policy = readJsonFile(settingsFile(workspaceRoot, 'apply-policy.json'), 'invalid-apply-policy', 'the apply policy')
+    if (policy !== null) assertObsidianContract('apply-policy', policy)
+  } catch { return denied('apply-policy-invalid') }
+  if (policy === null) return denied('apply-policy-absent')
+  const reference = settings.applyPolicy
+  if (policy.workspaceId !== workspaceId || policy.policyId !== reference.policyId || policy.version !== reference.version || policy.digest !== reference.digest) {
+    return denied('apply-policy-reference-mismatch')
+  }
+  if (policy.mode !== 'automatic') return denied('apply-policy-manual')
+  if (policy.status !== 'active') return denied(`apply-policy-${policy.status}`)
+  return { authorized: true, reason: 'apply-policy-active', policy }
+}
+
+// The installed policy as stored, validated, or null. A stored policy that does not validate refuses.
+export function readInstalledApplyPolicy({ workspaceRoot, workspaceId }) {
+  const policy = readJsonFile(settingsFile(workspaceRoot, 'apply-policy.json'), 'invalid-apply-policy', 'the apply policy')
+  if (policy === null) return null
+  try { assertObsidianContract('apply-policy', policy) } catch (error) {
+    if (error instanceof ObsidianContractRefusal) refuse('invalid-apply-policy', 'the stored apply policy does not satisfy its contract', { errors: error.detail?.errors ?? [] })
+    throw error
+  }
+  if (policy.workspaceId !== workspaceId) refuse('invalid-apply-policy', 'the stored apply policy belongs to another workspace')
+  return policy
+}
+
+// Revocation. The stored policy is marked revoked first: from that write on, every authorization read denies, so an
+// apply that is queued behind it is never dispatched. Then maintenance goes back to manual, so installing a policy
+// later does not resume automatic apply by itself.
+export function revokeApplyPolicy({ workspaceRoot, workspaceId, repositoryRoots, updatedAt }) {
+  const policy = readInstalledApplyPolicy({ workspaceRoot, workspaceId })
+  const current = readMachineSettings({ workspaceRoot, workspaceId })
+  if (policy === null && (current === null || current.applyPolicy === null)) return { revoked: false, reason: 'no-apply-policy-installed', policy: null }
+  assertOutsideRepositories({ managedRoot: workspaceRoot, repositoryRoots })
+  const revoked = policy === null ? null : { ...policy, status: 'revoked' }
+  if (revoked !== null) atomicReplacePrivateText(path.join(settingsDirectory(workspaceRoot), 'apply-policy.json'), canonicalJson(revoked))
+  if (current !== null) writeMachineSettings({ workspaceRoot, workspaceId, repositoryRoots, settings: { ...current, maintenanceMode: 'manual', updatedAt } })
+  return { revoked: true, reason: policy?.status === 'revoked' ? 'already-revoked' : 'revoked', policy: revoked }
+}

package/src/runtime/obsidian/observation.mjs

@@ -0,0 +1,158 @@
+import { createHash } from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { DOC_EXTENSIONS } from '../../graph/knowledge-graph.mjs'
+import { localOverlayCandidatePaths } from '../../project/config.mjs'
+import { openRegularFileNoFollow } from '../../project/private-state.mjs'
+import { compareText } from './documents.mjs'
+
+// Observation by digest. The git-based observation of the synchronization
+// loop sees only what git tracks inside a repository; a vault is outside every
+// repository and ignored by design, so this module looks at files directly and
+// never asks git anything.
+//
+// Three layers, each only ever an accelerator for the next:
+//
+//   watcher event   names a path to look at now. Events may be lost, repeated
+//                   or late on every platform; nothing is decided from one.
+//   stat hint       size, modification time, change time and inode. A
+//                   difference means "hash this file"; equality means "skip it
+//                   on this tick". A hint never reports a change by itself.
+//   digest          the only thing that decides. A full reconciliation hashes
+//                   every observed file whatever its stat says, so a change
+//                   the first two layers missed converges there.
+
+export const sha256Digest = (bytes) => `sha256:${createHash('sha256').update(bytes).digest('hex')}`
+
+const SKIPPED_DIRECTORIES = new Set(['node_modules'])
+const SIDECAR_SUFFIX = '.kg.json'
+
+export const sourceKey = (repoId, relative) => `source\u0000${repoId}\u0000${relative}`
+export const configKey = (absolute) => `config\u0000${absolute}`
+export const vaultKey = (scopeId, relative) => `vault\u0000${scopeId}\u0000${relative}`
+
+function walk(root, relative, found) {
+  let entries
+  try { entries = fs.readdirSync(path.join(root, relative), { withFileTypes: true }) } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return found
+    throw error
+  }
+  for (const entry of entries.sort((left, right) => compareText(left.name, right.name))) {
+    if (entry.name.startsWith('.') || SKIPPED_DIRECTORIES.has(entry.name)) continue
+    const child = relative === '' ? entry.name : `${relative}/${entry.name}`
+    // Links are not followed: a link could lead outside the repository.
+    if (entry.isDirectory()) walk(root, child, found)
+    else if (entry.isFile()) found.push(child)
+  }
+  return found
+}
+
+function sourceClass(relative, names) {
+  if (relative.endsWith(SIDECAR_SUFFIX)) return 'sidecar'
+  const extension = path.posix.extname(relative).toLowerCase()
+  if (extension === '.md') return 'source-body'
+  // Any other file is a source only when the census could enrol it: a document
+  // extension, or a file with a sidecar beside it.
+  return DOC_EXTENSIONS.has(extension) || names.has(`${relative}${SIDECAR_SUFFIX}`) ? 'asset' : null
+}
+
+// Every file whose bytes can change a view: source bodies, sidecars and the
+// assets they enrol, in every enrolled repository. Deliberately a superset of
+// the census (it does not apply ignore rules): observing one file too many
+// costs a rebuild that produces the same generation, observing one too few
+// would leave a view stale.
+export function listSourceFiles(project, { assets = [] } = {}) {
+  const files = []
+  const roots = new Map()
+  for (const repo of project.repos ?? []) {
+    if (repo.external || typeof repo.path !== 'string' || typeof repo.name !== 'string') continue
+    roots.set(repo.name, repo.path)
+    const relatives = walk(repo.path, '', [])
+    const names = new Set(relatives)
+    for (const relative of relatives) {
+      const changeClass = sourceClass(relative, names)
+      if (changeClass) files.push({ key: sourceKey(repo.name, relative), changeClass, absolute: path.join(repo.path, relative), repoId: repo.name, relative })
+    }
+  }
+  // Embedded assets of the last built graph. The resolver accepts a file in a
+  // dot-directory, which the walk skips, and an image has no sidecar, so these
+  // are listed by name. Only assets a view may copy are passed in.
+  const listed = new Set(files.map((file) => file.key))
+  for (const asset of assets) {
+    const key = sourceKey(asset.repo, asset.path)
+    if (!roots.has(asset.repo) || listed.has(key)) continue
+    listed.add(key)
+    files.push({ key, changeClass: 'asset', absolute: path.join(roots.get(asset.repo), ...asset.path.split('/')), repoId: asset.repo, relative: asset.path })
+  }
+  return files
+}
+
+// The files that decide what a project is: its configuration, its repository
+// access file and every place a local overlay may appear. A path that does
+// not exist yet is observed too, so its appearance is a change.
+export function listConfigFiles(project) {
+  const paths = new Set([project.configPath, project.repoAccessPath, ...localOverlayCandidatePaths({ configDir: project.configDir, env: {} }), ...(project.localOverlay?.paths ?? [])].filter((item) => typeof item === 'string'))
+  return [...paths].sort().map((absolute) => ({ key: configKey(absolute), changeClass: 'config', absolute }))
+}
+
+export function listVaultNotes({ scopeId, vaultRoot, manifest }) {
+  return (manifest?.notes ?? []).map((note) => ({ key: vaultKey(scopeId, note.path), changeClass: 'vault-note', absolute: path.join(vaultRoot, ...note.path.split('/')), scopeId, relative: note.path }))
+}
+
+function statHint(file, lstat) {
+  let stat
+  try { stat = lstat(file) } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null
+    throw error
+  }
+  return stat.isFile() ? { size: stat.size, mtimeMs: stat.mtimeMs, ctimeMs: stat.ctimeMs, ino: stat.ino } : null
+}
+
+// One read: the digest and the length are of the same bytes.
+export function readFileFacts(file) {
+  let descriptor
+  try { descriptor = openRegularFileNoFollow(file) } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR' || error.code === 'ELOOP' || error.message === 'state leaf is not a regular file') return null
+    throw error
+  }
+  try {
+    const bytes = fs.readFileSync(descriptor)
+    return { digest: sha256Digest(bytes), byteLength: bytes.length }
+  } finally { fs.closeSync(descriptor) }
+}
+
+const sameHint = (left, right) => left.size === right.size && left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs && left.ino === right.ino
+
+// Reconciles `files` against `index` (a Map owned by the caller) and returns
+// the changes, decided by digest alone. `full` hashes everything; otherwise a
+// file is hashed when it is new, when its stat hint differs or when a watcher
+// named it. Entries under `prefix` that are no longer listed are removals.
+export function reconcile({ index, files, prefix, full, hinted = () => false, lstat = fs.lstatSync }) {
+  const changes = []
+  const present = new Set()
+  let hashed = 0
+  for (const file of files) {
+    present.add(file.key)
+    const previous = index.get(file.key)
+    const hint = statHint(file.absolute, lstat)
+    if (hint === null) {
+      if (previous && previous.digest !== null) changes.push({ key: file.key, changeClass: previous.changeClass, kind: 'removed' })
+      index.set(file.key, { changeClass: file.changeClass, hint: null, digest: null, byteLength: null })
+      continue
+    }
+    if (!full && previous && previous.digest !== null && previous.hint && sameHint(previous.hint, hint) && !hinted(file.key)) continue
+    const facts = readFileFacts(file.absolute)
+    const digest = facts?.digest ?? null
+    hashed += 1
+    if (!previous || previous.digest !== digest || previous.changeClass !== file.changeClass) {
+      if (digest !== null || (previous && previous.digest !== null)) changes.push({ key: file.key, changeClass: file.changeClass, kind: !previous || previous.digest === null ? 'added' : digest === null ? 'removed' : 'changed' })
+    }
+    index.set(file.key, { changeClass: file.changeClass, hint: digest === null ? null : hint, digest, byteLength: facts?.byteLength ?? null })
+  }
+  for (const [key, previous] of index) {
+    if (!key.startsWith(prefix) || present.has(key)) continue
+    if (previous.digest !== null) changes.push({ key, changeClass: previous.changeClass, kind: 'removed' })
+    index.delete(key)
+  }
+  return { changes, hashed }
+}