@mnstry/atelier 0.2.0-alpha.13 → 0.2.0-alpha.14

package/src/runtime/obsidian/service.mjs

@@ -1,8 +1,9 @@
+import { prepareViewCooperatively } from '../../projection/obsidian/materialize/prepare-view.mjs'
 import { randomBytes as cryptoRandomBytes } from 'node:crypto'
 import fs from 'node:fs'
 import path from 'node:path'
 import { AtelierDiagnosticError } from '../../project/config.mjs'
-import { ObsidianContractRefusal } from '../../projection/obsidian/contracts.mjs'
+import { OBSIDIAN_EXT_KEY, ObsidianContractRefusal } from '../../projection/obsidian/contracts.mjs'
 import { prepareView as productionPrepareView } from '../../projection/obsidian/materialize/index.mjs'
 import { preparePluginFiles } from '../../projection/obsidian/plugin-bridge/bundle.mjs'
 import { publishView as productionPublishView } from '../../projection/obsidian/publication/publisher.mjs'
@@ -22,6 +23,7 @@ import {
 import { createServiceServer } from './service-server.mjs'
 import { OPEN_EDIT_STATES, createMaintenanceStateStore } from './state-store.mjs'
 import { DEFAULT_MAX_BACKOFF_MS, DEFAULT_TICK_INTERVAL_MS, createTickLoop } from './tick-loop.mjs'
+import { createLoadReport, createViewPermission } from './view-permission.mjs'
 import { createFsWatcherFactory } from './watchers.mjs'
 
 // The maintenance service of one workspace, inside one process.
@@ -60,8 +62,22 @@ export const SERVICE_STATUS_SCHEMA = 'atelier-obsidian-service-status/v1'
 export const DEFAULT_SHUTDOWN_GRACE_MS = 30 * 1000
 export const RELEASE_CHANGED = 'release-changed'
 
+// What of a project its workspace is resolved from, as a project that holds nothing else: the folder its pointer is
+// under (readLocalPointer), the data root its local overlay prefers (resolveDataRoot), and the repositories private
+// state may not overlap (protectedRoots). resolveServiceWorkspace reads these and nothing else of a project, so two
+// projects with the same inputs resolve alike, and the plugin's status read compares exactly them (view-permission.mjs).
+export function serviceWorkspaceInputs(project) {
+  const preference = project?.localOverlay?.overlay?.preferences?.[OBSIDIAN_EXT_KEY]
+  return {
+    ...(typeof project?.configDir === 'string' ? { configDir: project.configDir } : {}),
+    repos: (Array.isArray(project?.repos) ? project.repos : []).map((repo) => ({ path: repo?.path, external: Boolean(repo?.external) })),
+    localOverlay: { overlay: { preferences: preference === undefined ? {} : { [OBSIDIAN_EXT_KEY]: preference } } },
+  }
+}
+
 // Where a workspace keeps its private state, without creating an identity.
-export function resolveServiceWorkspace({ project, dataRoot, env = process.env, platform = process.platform, create = false }) {
+export function resolveServiceWorkspace({ project: whole, dataRoot, env = process.env, platform = process.platform, create = false }) {
+  const project = serviceWorkspaceInputs(whole)
   const pointer = readLocalPointer(project)
   if (pointer === null) return null
   const requested = workspaceStateRoot(resolveDataRoot({ dataRoot, pointer, project, env, platform }), pointer.workspaceId)
@@ -87,7 +103,10 @@ async function writeRecordPatiently(input) {
 
 export async function runMaintenanceService(options = {}) {
   const {
-    loadProject, dataRoot, adapterFactory, entryPath, runtimeId = `rt-${cryptoRandomBytes(16).toString('hex')}`, startup = false,
+    loadProject, dataRoot,
+    // What the workspace is resolved from at once, where the loader may answer a promise (locatePersonalHome): the service
+    // starts from it, and the engine awaits the loader at its ticks. Without it, the loader's own first answer is used.
+    locateProject = null, adapterFactory, entryPath, runtimeId = `rt-${cryptoRandomBytes(16).toString('hex')}`, startup = false,
     intervalMs = DEFAULT_TICK_INTERVAL_MS, maxBackoffMs = Math.max(DEFAULT_MAX_BACKOFF_MS, intervalMs), shutdownGraceMs = DEFAULT_SHUTDOWN_GRACE_MS,
     clock = () => new Date(), log = () => {}, pid = process.pid, randomBytes = cryptoRandomBytes, env = process.env, platform = process.platform,
     engineOptions = {}, createEngine = createMaintenanceEngine,
@@ -103,7 +122,18 @@ export async function runMaintenanceService(options = {}) {
   if (typeof adapterFactory !== 'function') throw new TypeError('the service needs an adapterFactory')
   if (typeof entryPath !== 'string') throw new TypeError('the service needs the path of its entry module')
 
-  const workspace = resolveServiceWorkspace({ project: loadProject(), dataRoot, env, platform })
+  // The workspace comes from the project the loader answers now, or the locator. A loader without a locator, or a locator,
+  // that answers a promise is refused, typed, before anything is read from the promise (it has no pointer, no overlay and
+  // no repositories); its answer is let go unread. A located project names its folder, or is refused.
+  const project = locateProject === null ? loadProject() : locateProject()
+  if (typeof project?.then === 'function') {
+    // Let go without calling a `then` of its own, which a promise whose `constructor` reads as this realm's `Promise`
+    // may carry and which may throw; any other thenable is adopted, its `then` called once.
+    Promise.prototype.then.call(Promise.resolve(project), undefined, () => {})
+    refuse('service-loader-not-synchronous', 'the service resolves its workspace from a project its loader answers at once; a loader that answers a promise is not supported when the service starts')
+  }
+  if (locateProject !== null && typeof project?.configDir !== 'string') refuse('service-locator-invalid', 'the locator of this service answered no folder to resolve its workspace from')
+  const workspace = resolveServiceWorkspace({ project, dataRoot, env, platform })
   if (!workspace?.workspaceRoot) refuse('service-workspace-not-prepared', 'this workspace has no private state yet; `start` prepares it')
   const { workspaceId, workspaceRoot } = workspace
   const settings = readServiceSettings({ workspaceRoot, workspaceId })
@@ -131,6 +161,10 @@ export async function runMaintenanceService(options = {}) {
   let stopping = false
   let consecutiveFailures = 0
   let lastTick = null
+  // What the last tick that did not fail named each refused view for (refusalCauses). A view the next tick names for the
+  // same reason is not written to the log again: a refusal that lasts (a folder that stays unwritable is tried again at
+  // every tick) is written once, and again when its reason changes or after a tick that failed or did not name it.
+  let refusedLastTick = new Map()
   let settleDone
   const done = new Promise((resolve) => { settleDone = resolve })
 
@@ -160,6 +194,14 @@ export async function runMaintenanceService(options = {}) {
     }
   }
   const prepareWithPlugin = (input) => (engineOptions.seams?.prepareView ?? productionPrepareView)({ ...input, plugin: pluginFor(input.scope.scopeId) })
+  // The engine's rule (engine.mjs): a prepareView that is not the one that ships, handed in with the cooperative
+  // preparation left as it ships or absent, prepares the view, synchronously; the engine then gets no cooperative seam.
+  // Nor does it when the cooperative preparation was handed in as null: that says there is none, as it does to the engine.
+  const handed = engineOptions.seams ?? {}
+  const replacedPrepare = typeof handed.prepareView === 'function' && handed.prepareView !== productionPrepareView
+    && (handed.prepareViewCooperatively === undefined || handed.prepareViewCooperatively === prepareViewCooperatively)
+  const cooperative = replacedPrepare || handed.prepareViewCooperatively === null ? null : handed.prepareViewCooperatively ?? prepareViewCooperatively
+  const prepareCooperativelyWithPlugin = cooperative === null ? null : (input) => cooperative({ ...input, plugin: pluginFor(input.scope.scopeId) })
   // An entry offered to a vault and now in place is confirmed: from then on, a list without it is the person's decision.
   const publishAndConfirm = async (input) => {
     const result = await (engineOptions.seams?.publishView ?? productionPublishView)(input)
@@ -174,8 +216,8 @@ export async function runMaintenanceService(options = {}) {
   // The engine also asks the factory itself (`forget`, on a tick somebody asked for): the wrapper keeps its methods.
   const pluginAwareAdapterFactory = Object.assign((input) => adapterFactory({ ...input, pluginReport: typeof input?.scope?.scopeId === 'string' ? pluginReportOf(input.scope.scopeId) : null }), adapterFactory)
   const engine = createEngine({
-    watcherFactory: createFsWatcherFactory(), ...engineOptions, seams: { ...(engineOptions.seams ?? {}), prepareView: prepareWithPlugin, publishView: publishAndConfirm },
-    loadProject, dataRoot, adapterFactory: pluginAwareAdapterFactory, clock, env, platform, lockOwner: { host, port, runtimeId },
+    watcherFactory: createFsWatcherFactory(), ...engineOptions, seams: { ...(engineOptions.seams ?? {}), prepareView: prepareWithPlugin, prepareViewCooperatively: prepareCooperativelyWithPlugin, publishView: publishAndConfirm },
+    loadProject, locateProject, dataRoot, adapterFactory: pluginAwareAdapterFactory, clock, env, platform, lockOwner: { host, port, runtimeId },
   })
 
   const recordIsOurs = () => {
@@ -187,11 +229,20 @@ export async function runMaintenanceService(options = {}) {
     consecutiveFailures = outcome.consecutiveFailures
     if (outcome.ok) {
       lastTick = { at, state: outcome.report.state, reason: outcome.report.reason ?? outcome.report.refusal?.code ?? null }
+      // A view the tick refused for a file-system error: the view's freshness names the refusal, and this line the error.
+      const refused = new Map()
+      for (const item of outcome.report.refusalCauses ?? []) {
+        const reason = JSON.stringify([item.code, item.cause ?? null, item.cleanupCause ?? null])
+        refused.set(item.scopeId, reason)
+        if (refusedLastTick.get(item.scopeId) !== reason) log({ at, event: 'view-refused', scopeId: item.scopeId, code: item.code, ...(item.cause ? { cause: item.cause } : {}), ...(item.cleanupCause ? { cleanupCause: item.cleanupCause } : {}) })
+      }
+      refusedLastTick = refused
       const previous = readLastServiceError({ workspaceRoot, workspaceId })
       if (previous && previous.resolvedAt === null) writeLastServiceError({ workspaceRoot, workspaceId, document: { ...previous, consecutiveFailures: 0, resolvedAt: at } })
       return
     }
     lastTick = { at, state: 'failed', reason: errorCode(outcome.error) }
+    refusedLastTick = new Map()
     // The message may carry a path or a title: it goes to the private log and nowhere else.
     log({ at, event: 'tick-failed', code: errorCode(outcome.error), name: errorName(outcome.error), message: String(outcome.error?.message ?? outcome.error), consecutiveFailures })
     let previous = null
@@ -251,8 +302,16 @@ export async function runMaintenanceService(options = {}) {
 
   const healthStatus = () => (stopping ? 'stopped' : consecutiveFailures > 0 ? 'degraded' : 'healthy')
 
+  // What is stored about a view is not permission to tell it: the project is asked as it is now (view-permission.mjs).
+  // Its loads are counted for the status document; the log gets a line for those somebody has to see (createLoadReport).
+  const statusLoads = createLoadReport({ write: (entry) => log({ at: isoTime(clock), ...entry }) })
+  const viewPermitted = createViewPermission({
+    loadProject, resolveWorkspace: (loaded) => resolveServiceWorkspace({ project: loaded, dataRoot, env, platform }), workspaceInputsOf: serviceWorkspaceInputs,
+    workspaceId, workspaceRoot, onLoad: statusLoads.onLoad,
+  })
   // One view as the plugin is told about it: its freshness entry with held notes counted, and its open pending edits.
   function pluginStatusOf(scopeId) {
+    if (!viewPermitted(scopeId)) return { view: null, pendingEdits: null }
     let entry = null
     try { entry = stateStore.readFreshness()?.scopes.find((item) => item.scopeId === scopeId) ?? null } catch (error) { if (!isTyped(error)) throw error; return { view: null, pendingEdits: null } }
     let open = null
@@ -281,6 +340,7 @@ export async function runMaintenanceService(options = {}) {
         return {
           schema: SERVICE_STATUS_SCHEMA, service: { ...identity, status: healthStatus() }, loop: loop.state(), lastTick, lastError, freshness: freshnessSummary(),
           plugins: pluginPresence({ sessions: pluginSessions, scopeIds: [...pluginChannel.bearers().keys()], entryOf: (scopeId) => currentPluginChoice({ workspaceRoot, workspaceId, scopeId }).state }),
+          statusLoads: statusLoads.counts(),
           ...(typeof appStatus === 'function' ? { app: appStatus() } : {}),
         }
       },

package/src/runtime/obsidian/view-permission.mjs

@@ -0,0 +1,334 @@
+import { createHash } from 'node:crypto'
+import fs from 'node:fs'
+import { readObsidianEnablement } from './enablement.mjs'
+import { DEFAULT_FULL_RECONCILIATION_INTERVAL_MS, configFilesOf } from './engine.mjs'
+import { readFileFacts } from './observation.mjs'
+
+// Whether the project allows a view of this workspace right now.
+//
+// What the service stored about a view (its freshness, its pending edits) says
+// what was true when it was written. A view can be turned off, or taken out of
+// the project, or the project can point at another workspace, well before the
+// next tick writes that down; and what a tick then writes still carries the
+// view's generations and counts. So before a stored report is told to whoever
+// holds the view open, `permits(scopeId)` asks the project as it is at that
+// moment:
+//
+//   the view        the Obsidian settings are enabled and declare it
+//   the workspace   the project's pointer names this workspace, and its
+//                   private state is where this service keeps it
+//
+// Whatever cannot be established is "no": a project that does not load,
+// settings that refuse, a pointer that cannot be read, a load that has not
+// answered yet. Nothing is written. This is not about who may see a note; the
+// audiences of machine-settings.mjs decide that when a view is prepared.
+//
+// Cost. Loading a project runs Git in child processes, and a plugin asks every
+// two seconds for every vault it holds open. A project is therefore kept, and
+// loaded again only when a file that decides what it is changed: the files the
+// engine observes as configuration (configFilesOf), compared at every request
+// by a digest of what they hold, never by their times. The pointer and the
+// place of the workspace's private state are read at every request.
+//
+//   what a file holds   where it really is and the bytes there: its path
+//                       resolved as the system resolves it when the loader
+//                       opens it (realpath(3), through a link anywhere on the
+//                       way), so a link pointed elsewhere, its own or a
+//                       folder's above it, is a change. Nothing there is a
+//                       state like any other. A folder in a file's place, a
+//                       link that leads nowhere or to anything but a regular
+//                       file, and a file that does not read vouch for nothing.
+//                       Where the system resolves no path for a regular file
+//                       that is there and is not a link (some volumes on
+//                       Windows; a C library that needs /proc and has none),
+//                       the file holds its own path as given and its bytes: a
+//                       link above it pointed elsewhere is not seen there
+//   a project is kept   when two loads in a row, each started after the
+//                       files were read and found to hold the same, returned
+//                       the same project as far as this permission reads one:
+//                       the views it enables, and what the service's
+//                       workspace resolution reads of it, handed in as
+//                       `workspaceInputsOf` (where its pointer
+//                       is, the data root its local overlay prefers, the
+//                       roots it protects). One load is not enough: a file
+//                       changed and changed back while it ran leaves the same
+//                       bytes around a project read from other ones, and
+//                       reading the files once more when it answers shows
+//                       nothing. The second load reads the project again.
+//                       The first load of all only tells which files decide
+//                       the project, so three loads keep the first project
+//                       and two keep one after a change
+//   and used            only while the files hold what they held before
+//                       those loads, read again at every request
+//   and not for long    a kept project is loaded again once it is half as old
+//                       as the engine's full reconciliations are apart, and
+//                       is never used past that interval: whatever no file
+//                       here names is seen by then
+//
+// While a file vouches for nothing no project is kept: a loader that answers
+// at once is asked at every request, and its answer decides that request, as
+// it does for the two requests that come before a project is kept.
+//
+// A loader may answer a promise (one that composes a personal workspace off
+// the event loop). The answer to a request never waits for it: a plugin gives
+// a request a second and a half, and takes an answer that does not come for a
+// service that is gone. The load is started, one at a time, and a request is
+// only ever decided from a kept project: until two loads agreed the view is
+// not permitted, and while a kept project is loaded again it goes on deciding,
+// within its time. A load that has not answered by its deadline is given up,
+// whether a request or its own late answer is the first to see the deadline
+// passed, and what it answers then is ignored.
+//
+// A load that fails (it throws, it is refused, it is given up, or it answers a
+// promise while a file vouches for nothing) ends whatever was kept, and is not
+// asked for again at once: after two seconds, then four, up to thirty, for as
+// long as the files hold the same. A change to them is tried at once, once a
+// load has named them: until a load has answered, a corrected configuration
+// waits for the next try. And while one of them vouches for nothing there is
+// no digest to change: after a load that failed then (one that answers a
+// promise, or one that answers at once and threw), a change to another file
+// waits for the next try as well.
+//
+// `onLoad({ durationMs, outcome, promised, kept, sameFiles, vouched, at })` is
+// told how long each load took and how it ended (`answered`, `failed` or
+// `given-up`), whether a project is kept after it, whether it named the files
+// that decide the project as they were when it started (not the first load,
+// which started over none, nor one that named other files), whether those
+// files vouched then, and when it ended (`now()`): times, codes and flags
+// only. createLoadReport, below, counts them and decides which are worth a
+// log line.
+
+// A kept project is never used for longer than the engine goes without a full reconciliation.
+export const DEFAULT_KEEP_FOR_MS = DEFAULT_FULL_RECONCILIATION_INTERVAL_MS
+// Longer than the two minutes a composition in a worker is given, so one that runs out of its own time answers first.
+export const DEFAULT_LOAD_DEADLINE_MS = 150 * 1000
+export const DEFAULT_RETRY_AFTER_MS = 2 * 1000
+export const DEFAULT_RETRY_AT_MOST_MS = 30 * 1000
+
+// What one file holds, as [path, its real path, digest of the bytes there], or [path, null, null] when it is absent;
+// undefined when it vouches for nothing. The real path is the system's own (realpath(3)): JavaScript's realpathSync
+// takes a `..` after a link away before following the link, and names a file the loader never opens.
+function heldBy(file, realpath) {
+  let real
+  try { real = realpath(file) } catch {
+    // Unresolved. Nothing there is absent. A regular file that is there, and is not a link, is read where it is given
+    // (readFileFacts follows no link at its end). A link, resolved or not, never is: it leads nowhere, or nobody can say where.
+    let stat
+    try { stat = fs.lstatSync(file, { throwIfNoEntry: false }) } catch (inner) { return inner.code === 'ENOTDIR' ? [file, null, null] : undefined }
+    if (stat === undefined) return [file, null, null]
+    if (!stat.isFile()) return undefined
+    real = file
+  }
+  let facts
+  try { facts = readFileFacts(real) } catch { return undefined }
+  return facts === null ? undefined : [file, real, facts.digest]
+}
+
+// One digest over what every file holds, in order. Null when one of them vouches for nothing.
+function digestOver(files, realpath) {
+  const hash = createHash('sha256')
+  for (const file of files) {
+    const held = heldBy(file, realpath)
+    if (held === undefined) return null
+    hash.update(`${JSON.stringify(held)}\n`)
+  }
+  return hash.digest('hex')
+}
+
+// The views the project enables. Settings that refuse enable none.
+function viewsOf(project) {
+  try {
+    const enablement = readObsidianEnablement(project)
+    return new Set(enablement.state === 'enabled' ? enablement.scopes.map((scope) => scope.scopeId) : [])
+  } catch { return new Set() }
+}
+
+export const STATUS_LOAD_EVENT = 'status-project-loaded'
+// A second: most of the second and a half a plugin gives a request, spent on the listener's own event loop.
+export const DEFAULT_SLOW_LOAD_MS = 1000
+// How long a row of failed or slow loads goes on through loads that answered in time between them.
+export const DEFAULT_ROW_ENDS_AFTER_MS = 60 * 1000
+
+// Counts every load a permission is told about (onLoad), and writes a line for the ones somebody has to see:
+//
+//   failed, given up   the first in a row, then when the row is 2, 4, 8, ... long, so a loader that keeps failing
+//                      writes a line less and less often, never one per try
+//   answered           the one that ends a row of failures; one that answered at once and held the event loop for
+//                      `slowMs` or more, on the same doubling row while slow loads follow each other; and one after
+//                      which nothing is kept although it named the files it started over, from the second in a row
+//                      on the same doubling row: a load at every request
+//
+// A row of failures ends only at a load that answers `rowEndsAfterMs` or more after its last failure, and a row of
+// slow loads at a load that answers in time that long after its last slow one. While loads come closer together than
+// that (a load at every request, or the retries after a failure), a loader that fails, or is slow, every other load or
+// every third keeps one row, written less and less often, not a line per load. A kept project is loaded again only
+// every half of its keep time, so there a row of failures ends at the next reload that answers: a loader that answers
+// at least one reload between two failures writes each failure and the load that ends its row, as before, and one that
+// fails at every reload and answers only at its retry keeps one row. A row of loads after which nothing is kept ends
+// at the next that keeps a project. A load that named other files than it started over (the first, or one after a
+// change that names other files) neither counts nor ends that row, so a start and a change, each with one load that
+// has nothing to agree with yet, write none of these, unless the change lands while a load reads the files. Any other
+// load that answered in time and kept the project writes nothing unless it ends a row of failures: that is every load
+// of a healthy service. A line holds the event, milliseconds, the outcome, flags and counts; never a path, a view or a
+// message.
+export function createLoadReport({ write, slowMs = DEFAULT_SLOW_LOAD_MS, rowEndsAfterMs = DEFAULT_ROW_ENDS_AFTER_MS }) {
+  if (typeof write !== 'function') throw new TypeError('a load report needs somewhere to write')
+  const counts = { answered: 0, failed: 0, givenUp: 0, slow: 0, notKept: 0, longestMs: 0 }
+  const doubled = (row) => (row & (row - 1)) === 0
+  let failedInARow = 0
+  let lastFailedAt = 0
+  let slowInARow = 0
+  let lastSlowAt = 0
+  let notKeptInARow = 0
+  return {
+    // `kept` and `sameFiles` default to a load that kept its project, `vouched` to files that vouched, and `at` to now.
+    onLoad({ durationMs, outcome, promised, kept = true, sameFiles = true, vouched = true, at = performance.now() }) {
+      const ms = Math.round(durationMs)
+      counts.longestMs = Math.max(counts.longestMs, ms)
+      if (outcome !== 'answered') {
+        counts[outcome === 'given-up' ? 'givenUp' : 'failed'] += 1
+        failedInARow += 1
+        lastFailedAt = at
+        if (doubled(failedInARow)) write({ event: STATUS_LOAD_EVENT, durationMs: ms, outcome, promised, inARow: failedInARow })
+        return
+      }
+      counts.answered += 1
+      const afterFailures = failedInARow > 0 && at - lastFailedAt >= rowEndsAfterMs ? failedInARow : 0
+      if (afterFailures > 0) failedInARow = 0
+      const slow = !promised && ms >= slowMs
+      if (slow) {
+        counts.slow += 1
+        slowInARow += 1
+        lastSlowAt = at
+      } else if (slowInARow > 0 && at - lastSlowAt >= rowEndsAfterMs) slowInARow = 0
+      const notKept = sameFiles && !kept
+      if (notKept) {
+        counts.notKept += 1
+        notKeptInARow += 1
+      } else if (sameFiles) notKeptInARow = 0
+      const writeSlow = slow && doubled(slowInARow)
+      const writeNotKept = notKept && notKeptInARow >= 2 && doubled(notKeptInARow)
+      if (afterFailures > 0 || writeSlow || writeNotKept) {
+        write({
+          event: STATUS_LOAD_EVENT, durationMs: ms, outcome, promised,
+          ...(afterFailures > 0 ? { afterFailures } : {}),
+          ...(writeSlow ? { slow: true, inARow: slowInARow } : {}),
+          ...(writeNotKept ? { notKept: true, notKeptInARow, vouched } : {}),
+        })
+      }
+    },
+    // answered, failed, givenUp, slow and notKept loads so far, and the longest in milliseconds.
+    counts: () => ({ ...counts }),
+  }
+}
+
+// `resolveWorkspace(project)` answers { workspaceId, workspaceRoot } as the project names them now, or null, and
+// `workspaceInputsOf(project)` what it reads of a project to do so, as JSON: the service hands in its own of both
+// (resolveServiceWorkspace, serviceWorkspaceInputs), so what two loads are compared by is never a copy kept here.
+// `now()` answers milliseconds that only go up; the times are this module's defaults unless a test gives its own.
+// `realpath(file)` resolves a path as the system does; a test hands in one that fails.
+export function createViewPermission({
+  loadProject, resolveWorkspace, workspaceInputsOf, workspaceId, workspaceRoot, now = () => performance.now(),
+  keepForMs = DEFAULT_KEEP_FOR_MS, loadDeadlineMs = DEFAULT_LOAD_DEADLINE_MS, retryAfterMs = DEFAULT_RETRY_AFTER_MS, retryAtMostMs = DEFAULT_RETRY_AT_MOST_MS,
+  onLoad = () => {}, realpath = fs.realpathSync.native,
+}) {
+  if (typeof loadProject !== 'function') throw new TypeError('a view permission needs loadProject')
+  if (typeof resolveWorkspace !== 'function') throw new TypeError('a view permission needs resolveWorkspace')
+  if (typeof workspaceInputsOf !== 'function') throw new TypeError('a view permission needs workspaceInputsOf')
+  const digestOf = (files) => digestOver(files, realpath)
+  // What two loads have to agree on: the views, and what the workspace is resolved from. Nothing else of a project is
+  // compared, so a field that differs from load to load (a time, a binding under a symbol key) does not keep a project
+  // from being kept, and nothing a decision reads is left out.
+  const decidedBy = (project, views) => JSON.stringify([[...views].sort(), workspaceInputsOf(project)])
+  // The files that decided the project last loaded.
+  let files = null
+  // What the last load returned that was started over files that vouched: { digest, shape }.
+  let seen = null
+  // The project two such loads agreed on: { project, views, digest, since }, `since` the start of the second.
+  let kept = null
+  // A load that answered a promise and has not answered yet: { id, digest, startedAt }.
+  let underWay = null
+  // Loads that failed in a row while the files held the same: { digest, times, at }.
+  let failed = null
+  let started = 0
+
+  function fail(digest, at) {
+    kept = null
+    failed = { digest, times: failed !== null && failed.digest === digest ? failed.times + 1 : 1, at }
+  }
+  const tooSoon = (digest, at) => failed !== null && failed.digest === digest && at - failed.at < Math.min(retryAtMostMs, retryAfterMs * 2 ** (failed.times - 1))
+  // `before` and `vouched`: the files that decided the project when the load started, and whether they vouched then.
+  const sameList = (left, right) => left !== null && right !== null && left.length === right.length && left.every((file, index) => file === right[index])
+  const told = (startedAt, outcome, promised, { before, vouched }) => {
+    try { const at = now(); onLoad({ durationMs: Math.max(0, at - startedAt), outcome, promised, kept: kept !== null, sameFiles: sameList(before, files), vouched, at }) } catch { /* only told */ }
+  }
+
+  // What a load returned; `digest` was read before it started. A project that names other files than the ones read
+  // is kept under a digest the next request cannot read again, so it is dropped there, before it decides anything.
+  function answered(project, digest, since) {
+    files = configFilesOf(project).map((file) => file.absolute)
+    const views = viewsOf(project)
+    const loaded = { project, views, digest, since }
+    const shape = digest === null ? null : decidedBy(project, views)
+    kept = digest !== null && seen !== null && seen.digest === digest && seen.shape === shape ? loaded : null
+    seen = digest === null ? null : { digest, shape }
+    return loaded
+  }
+
+  // Asks the loader. What it returned, when it answers at once; null when it answers a promise.
+  function load(digest, at) {
+    const as = { before: files, vouched: digest !== null }
+    let answer
+    try {
+      answer = loadProject()
+      if (typeof answer?.then !== 'function') {
+        const loaded = answered(answer, digest, at)
+        failed = null
+        told(at, 'answered', false, as)
+        return loaded
+      }
+    } catch (error) { fail(digest, at); told(at, 'failed', false, as); throw error }
+    const id = (started += 1)
+    underWay = { id, digest, startedAt: at, as }
+    // Only the load under way is listened to: one given up answers nobody. An answer that comes once the deadline has
+    // passed gives the load up itself, when no request was there to see the deadline pass first.
+    const mine = () => {
+      if (underWay?.id !== id) return false
+      underWay = null
+      if (now() - at < loadDeadlineMs) return true
+      fail(digest, now())
+      told(at, 'given-up', true, as)
+      return false
+    }
+    Promise.resolve(answer).then((project) => {
+      if (!mine()) return
+      answered(project, digest, at)
+      // While a file vouches for nothing, nothing can be kept from this answer, and no request is here to be decided by it.
+      if (digestOf(files) === null) { fail(null, now()); told(at, 'failed', true, as) } else { failed = null; told(at, 'answered', true, as) }
+    }, () => { if (mine()) { fail(digest, now()); told(at, 'failed', true, as) } }).catch(() => { fail(digest, now()); told(at, 'failed', true, as) })
+    return null
+  }
+
+  // The project as it is now, or null while that is not known.
+  function current() {
+    const at = now()
+    const digest = files === null ? null : digestOf(files)
+    if (kept !== null && (digest !== kept.digest || at - kept.since >= keepForMs)) kept = null
+    if (underWay !== null && at - underWay.startedAt >= loadDeadlineMs) { const given = underWay; underWay = null; fail(given.digest, at); told(given.startedAt, 'given-up', true, given.as) }
+    if (kept !== null && at - kept.since < keepForMs / 2) return kept
+    if (underWay === null && !tooSoon(digest, at)) {
+      const loaded = load(digest, at)
+      if (loaded !== null) return loaded
+    }
+    return kept
+  }
+
+  return function permits(scopeId) {
+    try {
+      const known = current()
+      if (known === null || !known.views.has(scopeId)) return false
+      const workspace = resolveWorkspace(known.project)
+      return workspace?.workspaceId === workspaceId && workspace.workspaceRoot === workspaceRoot
+    } catch { return false }
+  }
+}