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

package/src/projection/obsidian/proposals/backpressure.mjs

@@ -0,0 +1,113 @@
+import { COLLABORATION_LEDGER_LIMITS } from '../../../collaboration/event-ledger.mjs'
+
+// The limits of the existing proposal ledger are contracts of that ledger:
+// 256 KiB a line, 16 MiB in all, 10,000 events, and a line that cannot be read
+// refuses every append. This module asks about them BEFORE the adapter appends
+// anything, and decides what becomes of an operation the ledger cannot take.
+//
+//   proposal-too-large  the event would be longer than a line may be. Refused; a proposal refers to the preserved
+//                       bytes by digest instead of holding them, and nothing is ever cut to fit.
+//   ledger-full         the ledger has no room (or too little: see the reserve). The operation waits in the adapter
+//                       queue as `backpressure`, its preserved edit untouched, and is tried again later.
+//   ledger-corrupt      a line of the ledger cannot be read. Refused, for that repository only.
+//   store-unavailable   the store could not be read or is locked by another writer right now. Waits, like a full one.
+//
+// Nothing here, and nothing in the adapter, compacts, rotates or deletes a
+// ledger or a proposal. Making room is a decision of a person.
+
+export const PROPOSAL_LEDGER_LIMITS = Object.freeze({
+  maxLineBytes: COLLABORATION_LEDGER_LIMITS.maxLineBytes,
+  maxBytes: COLLABORATION_LEDGER_LIMITS.maxBytes,
+  maxEvents: COLLABORATION_LEDGER_LIMITS.maxEvents,
+})
+
+export const PROPOSAL_BACKPRESSURE = Object.freeze({
+  // A proposal the adapter creates is reviewed by people, and a review is two more events. The adapter never takes
+  // the last of the room they need to settle what is already there.
+  reserveEvents: 32,
+  reserveBytes: 512 * 1024,
+  // What the store adds around a proposal when it writes the event (identifiers, timestamps) is a few hundred bytes
+  // of fixed length; the estimate is that and this much more.
+  lineMarginBytes: 1024,
+  // Per tick and per repository.
+  maxBatchPerRepository: 8,
+  // Pending edits looked at per tick to find new structural edits.
+  maxExaminedPerTick: 64,
+  // Pending edits the object store does not know yet that one tick observes and records, never applies.
+  maxObservedPerTick: 16,
+  // An operation under backpressure is tried at most this many times, each time later than the last.
+  maxAttempts: 8,
+  retryIntervalMs: 60 * 1000,
+  maxRetryIntervalMs: 60 * 60 * 1000,
+})
+
+export const BACKPRESSURE_CODES = Object.freeze(['ledger-full', 'store-unavailable', 'route-visibility-unknown'])
+export const STORE_REFUSAL_CODES = Object.freeze(['proposal-too-large', 'ledger-corrupt', 'store-refused', 'identity-not-preserved'])
+
+// What a read of the whole ledger says about it. `read` is the answer of
+// `eventLedger.readAll()` (or of `listProposals()`, which carries the same
+// status, diagnostics and stats).
+export function classifyLedgerRead(read, limits = PROPOSAL_LEDGER_LIMITS) {
+  const events = read?.stats?.eventCount ?? 0
+  const bytes = read?.stats?.bytes ?? 0
+  const headroom = { events: Math.max(0, limits.maxEvents - events), bytes: Math.max(0, limits.maxBytes - bytes) }
+  if (read?.ok) return { state: 'readable', code: null, events, bytes, headroom }
+  const diagnostics = Array.isArray(read?.diagnostics) ? read.diagnostics : []
+  // Larger than a ledger may be, or more events than one may hold: full, and then some. Not a line that is wrong.
+  if (read?.status === 413 || (diagnostics.length > 0 && diagnostics.every((item) => item.code === 'ledger-event-limit'))) {
+    return { state: 'full', code: 'ledger-full', events, bytes, headroom: { events: 0, bytes: read?.status === 413 ? 0 : headroom.bytes } }
+  }
+  if (read?.status === 422) return { state: 'corrupt', code: 'ledger-corrupt', events, bytes, headroom: { events: 0, bytes: 0 }, lines: diagnostics.length }
+  return { state: 'unavailable', code: 'store-unavailable', events, bytes, headroom: { events: 0, bytes: 0 } }
+}
+
+// The length of the line the store would write for `body`, to within the margin, and never less than it. It repeats
+// what createProposal makes of a body: the members it copies, and the payload, which it keeps whole. The identifiers
+// and timestamps the store adds have a fixed length, so placeholders of that length stand for them.
+export function estimateEventLineBytes({ body, workspaceId, marginBytes = PROPOSAL_BACKPRESSURE.lineMarginBytes }) {
+  const at = '2000-01-01T00:00:00.000Z'
+  const id = `proposal-${'0'.repeat(32)}`
+  const record = {
+    schema: 'atelier-proposal@v1', workspaceId,
+    proposal: {
+      id, status: 'proposed', createdAt: at, updatedAt: at, sessionId: String(body.sessionId ?? ''), viewId: String(body.viewId ?? ''), path: String(body.path ?? ''), action: String(body.action ?? ''),
+      intent: String(body.intent ?? ''), reason: String(body.reason ?? ''), storage: { kind: 'local', ignored: true },
+      authority: { action: String(body.action ?? ''), capability: 'proposal.copy-only', copyOnly: true, directWrite: false, applyEndpoint: null }, eventVersion: 1,
+    },
+    diff: typeof body.diff === 'string' ? body.diff : '',
+    payload: body.proposal ?? {},
+  }
+  const event = { schema: 'atelier-collaboration-event@v1', aggregateId: id, version: 1, type: 'proposal-created', actor: String(body.actor ?? ''), at, payload: { record }, id: `event-${'0'.repeat(32)}` }
+  return Buffer.byteLength(`${JSON.stringify(event)}\n`) + marginBytes
+}
+
+// { ok: true } or { ok: false, code, detail }. `ledger` is a classifyLedgerRead answer that is `readable`.
+export function preflightAppend({ ledger, lineBytes, limits = PROPOSAL_LEDGER_LIMITS, bounds = PROPOSAL_BACKPRESSURE }) {
+  if (lineBytes > limits.maxLineBytes) return { ok: false, code: 'proposal-too-large', detail: { lineBytes, limit: limits.maxLineBytes } }
+  if (ledger.headroom.events < 1 + bounds.reserveEvents) return { ok: false, code: 'ledger-full', detail: { member: 'events', headroom: ledger.headroom.events, reserve: bounds.reserveEvents } }
+  if (ledger.headroom.bytes < lineBytes + bounds.reserveBytes) return { ok: false, code: 'ledger-full', detail: { member: 'bytes', headroom: ledger.headroom.bytes, reserve: bounds.reserveBytes, lineBytes } }
+  return { ok: true }
+}
+
+// What a refused createProposal means, from its status.
+export function classifyStoreRefusal(status) {
+  if (status === 413) return 'ledger-full'
+  if (status === 422) return 'ledger-corrupt'
+  if (status === 423 || status === 500 || status === 409) return 'store-unavailable'
+  return 'store-refused'
+}
+
+// When an operation under backpressure is tried next: twice as long after each attempt, up to the maximum.
+export function nextAttemptAt({ attempts, nowMs, bounds = PROPOSAL_BACKPRESSURE }) {
+  const wait = Math.min(bounds.maxRetryIntervalMs, bounds.retryIntervalMs * 2 ** Math.max(0, Math.min(attempts, 30) - 1))
+  return new Date(nowMs + wait).toISOString()
+}
+
+export const isExhausted = (record, bounds = PROPOSAL_BACKPRESSURE) => record.state === 'backpressure' && record.attempts >= bounds.maxAttempts
+
+// Whether the adapter looks at this operation on this tick. Never for one that is settled, refused or exhausted, and
+// never before its time: an unchanged tick reads the queue and nothing else.
+export function isDue(record, { nowMs, bounds = PROPOSAL_BACKPRESSURE }) {
+  if (record.state === 'acknowledged' || record.state === 'refused' || isExhausted(record, bounds)) return false
+  return record.nextAttemptAt === null || Date.parse(record.nextAttemptAt) <= nowMs
+}

package/src/projection/obsidian/proposals/contribution.mjs

@@ -0,0 +1,55 @@
+import { refuse } from '../../../runtime/obsidian/errors.mjs'
+import { protectedRoots } from '../../../runtime/obsidian/machine-settings.mjs'
+import { createProposalAdapter } from './adapter.mjs'
+import { ProposalQueueRefusal } from './queue.mjs'
+import { isAdapterOperationId } from './router.mjs'
+
+// Binds the proposal adapter to the two places that reach it: the maintenance
+// engine, which hands it the pending edits on a tick, and `atelier obsidian
+// proposals`, which is how a person or an agent reads what became of them.
+// The command reads; it creates, accepts and applies nothing.
+
+export const PROPOSAL_ADAPTER_CONTRIBUTION_ID = 'atelier.proposal-adapter'
+const EXIT = Object.freeze({ ok: 0 })
+const SUMMARY = 'list | show OPERATION  Structural edits routed as copy-only proposals: per repository what is queued, submitted, acknowledged, waiting or refused, and the room its ledger has. Read-only.'
+
+export function createProposalsCommandOperation({ create = createProposalAdapter } = {}) {
+  return {
+    name: 'proposals',
+    summary: SUMMARY,
+    async run({ args, env, clock, readable }) {
+      const [sub = 'list', operationId, ...extra] = args
+      const { project, workspace, workspaceId } = readable()
+      if (workspace === null) refuse('workspace-not-prepared', 'this workspace has no private state yet; nothing was ever routed')
+      const context = { project, workspaceRoot: workspace.workspaceRoot, workspaceId, repositoryRoots: protectedRoots(project) }
+      const adapter = create({ env, clock })
+      // An adapter queue that cannot be read is an answer with a code, never an internal error.
+      const typed = (operation) => { try { return operation() } catch (error) { if (error instanceof ProposalQueueRefusal) refuse(error.code, 'the record of the proposal adapter cannot be read; nothing was changed'); throw error } }
+      if (sub === 'list' && operationId === undefined) {
+        const status = typed(() => adapter.status(context))
+        const operations = typed(() => adapter.list(context))
+        return {
+          exit: EXIT.ok, document: { status, operations },
+          human: status.repositories.length === 0 ? ['no enrolled repository'] : status.repositories.map((item) => `${item.repoId}\tqueued ${item.queued}\tsubmitted ${item.submitted}\tacknowledged ${item.acknowledged}\twaiting ${item.backpressure}\trefused ${item.refused}\tledger ${item.ledger.state}${item.ledger.headroom ? ` (${item.ledger.headroom.events} events, ${item.ledger.headroom.bytes} bytes free)` : ''}`),
+        }
+      }
+      if (sub === 'show' && extra.length === 0) {
+        if (!isAdapterOperationId(operationId)) refuse('usage', 'name the operation: an identifier that `obsidian proposals list` printed')
+        const shown = typed(() => adapter.show(context, { adapterOperationId: operationId }))
+        if (shown === null) refuse('unknown-operation', 'the proposal adapter holds no operation of that name')
+        return { exit: EXIT.ok, document: shown, human: [JSON.stringify(shown, null, 2)] }
+      }
+      return refuse('usage', 'proposals takes list or show OPERATION')
+    },
+  }
+}
+
+export function createProposalAdapterContribution(options = {}) {
+  return {
+    id: PROPOSAL_ADAPTER_CONTRIBUTION_ID,
+    register({ extensions, operations }) {
+      extensions.register('proposal-adapter', (options.create ?? createProposalAdapter)(options.adapter ?? {}))
+      operations.register(createProposalsCommandOperation(options))
+    },
+  }
+}

package/src/projection/obsidian/proposals/index.mjs

@@ -0,0 +1,23 @@
+// Structural edits made in a vault, routed as copy-only proposals: which
+// existing proposal store of which enrolled repository an edit belongs to
+// (router.mjs), the private record the adapter keeps of every operation before
+// it asks a store for anything (queue.mjs), what it does when the ledger of a
+// store has no room or cannot be read (backpressure.mjs), and the adapter that
+// creates exactly one proposal per operation (adapter.mjs). Nothing here
+// writes a source file or a vault, and no proposal holds the text of a note.
+export {
+  MAX_CHANGE_OCCURRENCES, PROPOSAL_ADAPTER_ACTOR, PROPOSAL_ADAPTER_CRASH_STEPS, PROPOSAL_ADAPTER_ID, PROPOSAL_ADAPTER_PRIMITIVES, PROPOSAL_LOCK_PURPOSE, PROPOSAL_PAYLOAD_KIND, PROPOSAL_PAYLOAD_SCHEMA,
+  buildProposalContent, createProposalAdapter, createProposalAdapterForOracleTests, describeChange,
+} from './adapter.mjs'
+export {
+  BACKPRESSURE_CODES, PROPOSAL_BACKPRESSURE, PROPOSAL_LEDGER_LIMITS, STORE_REFUSAL_CODES, classifyLedgerRead, classifyStoreRefusal, estimateEventLineBytes, isDue, isExhausted, nextAttemptAt, preflightAppend,
+} from './backpressure.mjs'
+export { PROPOSAL_ADAPTER_CONTRIBUTION_ID, createProposalAdapterContribution, createProposalsCommandOperation } from './contribution.mjs'
+export { createTickObservation, manifestOf, recordedOperationOf, retained } from './observation.mjs'
+export {
+  OPEN_QUEUE_STATES, PROPOSAL_OPERATION_SCHEMA, PROPOSAL_QUEUE_CRASH_STEPS, PROPOSAL_QUEUE_DIRECTORY, PROPOSAL_QUEUE_LIMITS, PROPOSAL_QUEUE_STATES, ProposalQueueRefusal, isProposalOperationRecord, openProposalQueue,
+} from './queue.mjs'
+export {
+  MAX_ROUTED_SOURCE_PATH, PROPOSAL_ROUTER_PRIMITIVES, PROPOSAL_ROUTE_REFUSALS, PROPOSAL_STORE_DIRECTORY, PROPOSAL_STORE_LEDGER, TRANSIENT_ROUTE_REFUSALS, adapterOperationId, createProposalRouterForOracleTests, isAdapterOperationId, isRoutableSourcePath, proposalStoreId, resolveProposalRoute,
+  survivesStoreNormalisation,
+} from './router.mjs'

package/src/projection/obsidian/proposals/observation.mjs

@@ -0,0 +1,216 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { AtelierDiagnosticError } from '../../../project/config.mjs'
+import { compareText, isoTime } from '../../../runtime/obsidian/documents.mjs'
+import { readObsidianEnablement } from '../../../runtime/obsidian/enablement.mjs'
+import { ObsidianMaintenanceRefusal } from '../../../runtime/obsidian/errors.mjs'
+import { OPEN_EDIT_STATES, createMaintenanceStateStore } from '../../../runtime/obsidian/state-store.mjs'
+import { OBSIDIAN_EXT_KEY, ObsidianContractRefusal } from '../contracts.mjs'
+import { SOURCE_APPLY_PRIMITIVES, SourceApplyRefusal, locateSource } from '../edits/apply.mjs'
+import { EditArbitrationRefusal } from '../edits/arbitrate.mjs'
+import { createEditObserverForOracleTests, editIdempotencyKey, observeEdit } from '../edits/observe.mjs'
+import { decideApply } from '../edits/policy.mjs'
+import { PublicationRefusal, readFileBytes, sha256Digest } from '../recovery/store.mjs'
+import { PROPOSAL_BACKPRESSURE } from './backpressure.mjs'
+
+// Observation on a tick: the part of a source apply that comes before its
+// lease, for every open pending edit the object store does not know yet.
+//
+// In manual mode nothing on a tick applies, so until here a structural edit
+// was recorded as `proposed` only after a person asked apply to look at it.
+// Here the same observation runs on the tick itself, in manual and in
+// automatic mode alike: the source is read now, the lens runs over the
+// PRESERVED edit bytes (never the live note) against it, and the resulting
+// operation is recorded in the object store exactly as an apply records it,
+// through the same observer and the same store. A body replacement is recorded
+// `pending` and left for apply, which is the only thing that writes a source;
+// a structural edit is recorded `proposed`, and the adapter routes it in the
+// same tick; a lens refusal is recorded `refused`; a base that moved on is
+// recorded `conflicted`. Nothing here writes a source file or a vault, and
+// nothing takes a lease.
+//
+// Quiet: the object store answers the same for an origin it already holds and
+// appends nothing, and an edit it holds is not offered again. A refusal that
+// comes before anything can be recorded (a source that is missing, a manifest
+// that cannot be read, an object this machine may not see, a note that cannot
+// be prepared again) is remembered in memory with its code and offered again
+// only when the caller says so, which the engine does at its full
+// reconciliation cadence, never on every tick. A bounded number of edits is
+// looked at per tick, in the order they were observed, starting where the last
+// tick stopped.
+
+const EXT = OBSIDIAN_EXT_KEY
+const GONE = new Set(['ENOENT', 'ENOTDIR', 'ELOOP'])
+const segment = (identifier) => identifier.replaceAll(':', '_')
+const refuse = (code, detail) => { throw new SourceApplyRefusal(code, detail) }
+const isTyped = (error) => error instanceof SourceApplyRefusal || error instanceof EditArbitrationRefusal || error instanceof PublicationRefusal || error instanceof ObsidianMaintenanceRefusal
+  || error instanceof ObsidianContractRefusal || error instanceof AtelierDiagnosticError
+
+// Observation of an edit whose base source is no longer the source: a conflict, decided without the lens. The same
+// observer source apply uses for that case.
+const STALE_OBSERVER = createEditObserverForOracleTests({
+  preserve({ store, edit, baseSourceBytes }) {
+    let edited = null
+    try { edited = store.readObject(edit.observedDigest) } catch (error) { if (error.code !== 'ENOENT' && error.code !== 'recovery-object-corrupt') throw error }
+    return edited === null ? { edited: null } : { edited, publishedRef: undefined, baseRef: store.retainObject(baseSourceBytes).ref }
+  },
+  classify: () => ({ kind: 'refusal', code: 'stale-base', detail: {} }),
+})
+
+// One open, never through a symbolic link, and only of a regular file.
+function readNoFollow(file) {
+  const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0))
+  try {
+    if (!fs.fstatSync(descriptor).isFile()) throw Object.assign(new Error('not a regular file'), { code: 'EISDIR' })
+    return fs.readFileSync(descriptor)
+  } finally { fs.closeSync(descriptor) }
+}
+const digestOrNull = (file) => { try { return sha256Digest(readNoFollow(file)) } catch { return null } }
+
+// The immutable manifest of one generation of one view: the current one when it is that generation, else the stored
+// file, whose name carries the generation and the head of its digest. `workspace` answers `recoveryOf(scopeId)`.
+export function manifestOf(workspace, scopeId, generationId) {
+  const current = workspace.recoveryOf(scopeId).readCurrentManifest()
+  if (current?.generationId === generationId) return current
+  const directory = path.join(workspace.workspaceRoot, 'state', 'manifests', segment(scopeId))
+  let names = []
+  try { names = fs.readdirSync(directory) } catch (error) { if (error.code !== 'ENOENT') throw error }
+  for (const name of names.filter((item) => item.startsWith(`${segment(generationId)}--`) && item.endsWith('.json')).sort()) {
+    let bytes
+    try { bytes = readFileBytes(path.join(directory, name)) } catch (error) { if (error.code === 'ENOENT') continue; throw error }
+    if (name !== `${segment(generationId)}--${sha256Digest(bytes).slice(7, 19)}.json`) continue
+    const manifest = JSON.parse(bytes.toString('utf8'))
+    if (manifest.generationId === generationId && manifest.scopeId === scopeId) return manifest
+  }
+  return null
+}
+
+// The retained bytes of that digest, or null when the store does not hold them intact.
+export function retained(store, digest) {
+  if (typeof digest !== 'string') return null
+  try { const bytes = store.readObject(digest); return sha256Digest(bytes) === digest ? bytes : null } catch (error) {
+    if (error?.code === 'ENOENT' || error?.code === 'recovery-object-corrupt') return null
+    throw error
+  }
+}
+
+// The operation the object store recorded for this edit, or null.
+export function recordedOperationOf(objects, edit) {
+  return objects.stateOf({ repoId: edit.identity.repoId, nodeId: edit.identity.nodeId }).operations.find((entry) => entry.origins.some((origin) => origin.editId === edit.editId && origin.scopeId === edit.scopeId)) ?? null
+}
+
+// `seams` prepare a view again when the published note is not retained; `isGitIgnored` and `gitDirectory` are what
+// git is asked through; `bounds.maxObservedPerTick` is how many edits one tick looks at.
+export function createTickObservation(options = {}) {
+  const { seams, isGitIgnored = SOURCE_APPLY_PRIMITIVES.isGitIgnored, gitDirectory = SOURCE_APPLY_PRIMITIVES.gitDirectory, bounds = PROPOSAL_BACKPRESSURE } = options
+  if (!seams || typeof seams.captureSnapshot !== 'function' || typeof seams.prepareView !== 'function') throw new TypeError('tick observation needs the seams that prepare a view')
+  // Edits whose operation the object store holds: a cache, losing it costs one read of an object. And edits whose
+  // observation refused before anything could be recorded, with the code.
+  const recorded = new Set()
+  const unobservable = new Map()
+  let cursor = 0
+
+  // Everything about one pending edit that the manifest of its view says.
+  function resolveEdit(workspace, edit) {
+    const { repoId, nodeId } = edit.identity
+    const scope = readObsidianEnablement(workspace.project).scopes.find((item) => item.scopeId === edit.scopeId)
+    if (!scope) refuse('unknown-scope')
+    const manifest = manifestOf(workspace, edit.scopeId, edit.generationId)
+    const noteEntry = manifest?.notes.find((note) => note.repoId === repoId && note.nodeId === nodeId && note.path === edit.path)
+    if (!noteEntry) refuse('manifest-unavailable')
+    const source = noteEntry.ext?.[EXT]?.source
+    if (typeof source?.rawDigest !== 'string' || typeof source?.path !== 'string') refuse('manifest-unavailable')
+    return { scope, manifest, noteEntry, recorded: source, baseSourceDigest: source.rawDigest, idempotencyKey: editIdempotencyKey({ workspaceId: workspace.workspaceId, repoId, nodeId, baseSourceDigest: source.rawDigest, observedDigest: edit.observedDigest }) }
+  }
+
+  // The note exactly as it was published, which the lens needs to tell generated bytes from authored ones. The
+  // publisher keeps no copy of a note it created, so the note is prepared again from the sources as they are now and
+  // used only when it has the digest the manifest recorded; a retained object of that digest serves as well.
+  function publishedNoteOf(workspace, { scope, manifest, noteEntry }, now) {
+    const store = workspace.recoveryOf(scope.scopeId)
+    const kept = retained(store, noteEntry.noteDigest)
+    if (kept) return kept
+    workspace.prepared ??= new Map()
+    if (!workspace.prepared.has(scope.scopeId)) {
+      let files = []
+      try {
+        const { graph, profile } = workspace.corpus()
+        const snapshot = seams.captureSnapshot({ project: workspace.project, graph, workspaceId: workspace.workspaceId, index: new Map(), configDigest: manifest.ext?.[EXT]?.configDigest ?? `sha256:${'0'.repeat(64)}`, capturedAt: now })
+        const persistentPathRegistry = createMaintenanceStateStore({ workspaceRoot: workspace.workspaceRoot, workspaceId: workspace.workspaceId }).readPathRegistry()
+        files = seams.prepareView({ snapshot, profile, scope, persistentPathRegistry, priorManifest: manifest, existingSettings: null, clock: workspace.clock, vaultRootBytes: Buffer.byteLength(store.vaultRoot, 'utf8') }).files
+      } catch (error) { if (!isTyped(error) && !GONE.has(error?.code)) throw error }
+      workspace.prepared.set(scope.scopeId, files)
+    }
+    const file = workspace.prepared.get(scope.scopeId).find((item) => item.path === noteEntry.path && item.digest === noteEntry.noteDigest)
+    return file ? file.bytes : null
+  }
+
+  // One edit, in the order of an apply up to its lease. Returns what was recorded; throws a typed refusal.
+  function observeOne(workspace, edit, now) {
+    if (edit.identity.workspaceId !== workspace.workspaceId) refuse('foreign-workspace')
+    const identity = { repoId: edit.identity.repoId, nodeId: edit.identity.nodeId }
+    const known = recordedOperationOf(workspace.objects(), edit)
+    if (known) return { code: 'already-observed', kind: known.kind, operationState: known.state, idempotencyKey: known.idempotencyKey }
+
+    // Whether this machine may see the object is asked first, of the canonical graph as it is now, before the
+    // manifest, the record of the object or the source path is looked at: an object that is withheld and one that
+    // is absent get this one answer, with nothing read and nothing recorded.
+    const { graph, profile } = workspace.corpus()
+    const visibility = decideApply({ request: { editId: edit.editId, mode: 'manual' }, workspace: { workspaceRoot: workspace.workspaceRoot, workspaceId: workspace.workspaceId }, graph, profile, object: identity, editClass: 'body-replacement', attempts: [] })
+    if (!visibility.allowed && visibility.code === 'object-not-visible') refuse('object-not-visible')
+    const resolved = resolveEdit(workspace, edit)
+    const node = graph.nodes.find((item) => item.repo === identity.repoId && item.id === identity.nodeId)
+    if (!node) refuse('source-not-in-graph')
+    if (node.path !== resolved.recorded.path) refuse('source-moved')
+
+    // The source, now: the one file of an enrolled repository the manifest names, reached through no link.
+    const vaultRoots = readObsidianEnablement(workspace.project).scopes.map((scope) => workspace.recoveryOf(scope.scopeId).vaultRoot)
+    const located = locateSource({ project: workspace.project, repoId: identity.repoId, relative: node.path, managedRoots: [workspace.workspaceRoot, ...vaultRoots], isGitIgnored, gitDirectory, env: workspace.env ?? process.env })
+    let sourceBytes
+    try { sourceBytes = readNoFollow(located.absolute) } catch (error) { refuse(error.code === 'ENOENT' ? 'source-missing' : error.code === 'ELOOP' ? 'source-symlink' : 'source-not-regular-file') }
+    const sourceDigest = sha256Digest(sourceBytes)
+
+    // The lens over the preserved bytes, or the conflict when the source moved on; then the record, through the store.
+    const store = workspace.recoveryOf(edit.scopeId)
+    let observed
+    if (sourceDigest !== resolved.baseSourceDigest) {
+      observed = STALE_OBSERVER({ edit, manifest: resolved.manifest, publishedNoteBytes: Buffer.alloc(0), baseSourceBytes: sourceBytes, store })
+      delete observed.operation.ext[EXT].publishedNoteRef
+    } else {
+      const publishedNoteBytes = publishedNoteOf(workspace, resolved, now)
+      // Preparing the note reads the source again: a source that changed since it was read here is a stale source.
+      if (publishedNoteBytes === null && digestOrNull(located.absolute) !== sourceDigest) refuse('stale-source', { cause: 'changed-while-reading' })
+      if (publishedNoteBytes === null) refuse('published-note-unavailable')
+      observed = observeEdit({ edit, manifest: resolved.manifest, publishedNoteBytes, baseSourceBytes: sourceBytes, store })
+    }
+    const result = workspace.objects().observe(observed.operation, { presentSourceDigest: sourceDigest })
+    return { code: result.appended ? 'observed' : 'already-observed', kind: observed.operation.kind, operationState: result.operation?.state ?? observed.operation.state, idempotencyKey: observed.operation.idempotencyKey }
+  }
+
+  // `workspace` is the opened workspace of the adapter; `edits` the pending edit records, open and closed;
+  // `retryRefused` offers the edits whose observation refused earlier once more. Returns one entry per edit looked
+  // at: { editId, repoId, nodeId, status: 'observed' | 'refused', code, kind?, operationState?, idempotencyKey? }.
+  return function observePendingEdits(workspace, { edits, retryRefused = false }) {
+    if (retryRefused) unobservable.clear()
+    const now = isoTime(workspace.clock)
+    const candidates = edits.filter((edit) => edit.closedAt === null && OPEN_EDIT_STATES.includes(edit.state) && !recorded.has(edit.editId) && !unobservable.has(edit.editId))
+      .sort((left, right) => compareText(left.observedAt, right.observedAt) || compareText(left.editId, right.editId))
+    const start = candidates.length === 0 ? 0 : cursor % candidates.length
+    const looked = [...candidates.slice(start), ...candidates.slice(0, start)].slice(0, bounds.maxObservedPerTick)
+    cursor = candidates.length > bounds.maxObservedPerTick ? start + looked.length : 0
+    const observed = []
+    for (const edit of looked) {
+      const entry = { editId: edit.editId, repoId: edit.identity.repoId, nodeId: edit.identity.nodeId }
+      try {
+        const outcome = observeOne(workspace, edit, now)
+        recorded.add(edit.editId)
+        observed.push({ ...entry, status: 'observed', ...outcome })
+      } catch (error) {
+        if (!isTyped(error)) throw error
+        unobservable.set(edit.editId, error.code)
+        observed.push({ ...entry, status: 'refused', code: error.code })
+      }
+    }
+    return observed
+  }
+}