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

package/src/runtime/local-state.mjs

@@ -0,0 +1,439 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import {
+  atomicReplacePrivateText,
+  ensureContainedPrivateDirectory,
+  openRegularFileNoFollow,
+  readRegularTextNoFollow,
+} from '../project/private-state.mjs'
+import { runGit } from './git-adapter.mjs'
+
+export const ATELIER_RUNTIME_STATE_SCHEMA = 'atelier-runtime-state@v1'
+export const ATELIER_RUNTIME_ENROLLMENT_SCHEMA = 'atelier-runtime-enrollment@v1'
+export const ATELIER_RUNTIME_TRACE_SCHEMA = 'atelier-runtime-operation@v1'
+export const ATELIER_RUNTIME_TRACE_MAX_BYTES = 2 * 1024 * 1024
+export const ATELIER_RUNTIME_TRACE_MAX_RECORDS = 2048
+export const ATELIER_RUNTIME_TRACE_MAX_EVENT_BYTES = 256 * 1024
+export const ATELIER_RUNTIME_PLAN_MAX_AGE_MS = 24 * 60 * 60 * 1000
+export const ATELIER_RUNTIME_PLAN_MAX_FILES = 256
+export const ATELIER_RUNTIME_PLAN_MAX_BYTES = 4 * 1024 * 1024
+export const ATELIER_RUNTIME_STATE_MAX_BYTES = 512 * 1024
+export const ATELIER_RUNTIME_LIVE_OWNER_MAX_AGE_MS = 24 * 60 * 60 * 1000
+
+function lstatIfPresent(file) {
+  try {
+    return fs.lstatSync(file)
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null
+    throw error
+  }
+}
+
+function runtimeWorkspaceRoot(file) {
+  const absolute = path.resolve(file)
+  const marker = `${path.sep}.atelier-local${path.sep}`
+  const index = absolute.lastIndexOf(marker)
+  if (index <= 0) throw new Error('runtime state path is outside .atelier-local')
+  return absolute.slice(0, index)
+}
+
+function secureRuntimeLeaf(file) {
+  const workspaceRoot = runtimeWorkspaceRoot(file)
+  const directory = ensureContainedPrivateDirectory({
+    workspaceRoot,
+    directory: path.dirname(path.resolve(file)),
+    label: 'runtime state directory',
+  })
+  return path.join(directory, path.basename(file))
+}
+
+export function atomicWriteJson(file, value) {
+  const secured = secureRuntimeLeaf(file)
+  atomicReplacePrivateText(secured, `${JSON.stringify(value, null, 2)}\n`)
+}
+
+export function readJsonIfPresent(file) {
+  const secured = secureRuntimeLeaf(file)
+  const stat = lstatIfPresent(secured)
+  if (!stat) return null
+  if (stat.size > ATELIER_RUNTIME_PLAN_MAX_BYTES) throw new Error('runtime JSON exceeds the resident byte ceiling')
+  return JSON.parse(readRegularTextNoFollow(secured))
+}
+
+export function removeRuntimeLeaf(file) {
+  const secured = secureRuntimeLeaf(file)
+  const stat = lstatIfPresent(secured)
+  if (!stat) return false
+  if (stat.isSymbolicLink() || !stat.isFile()) throw new Error('state leaf is not a regular file')
+  fs.unlinkSync(secured)
+  return true
+}
+
+export function runtimePlanInventory(plansPath) {
+  const directory = ensureContainedPrivateDirectory({
+    workspaceRoot: runtimeWorkspaceRoot(plansPath),
+    directory: plansPath,
+    label: 'runtime plans directory',
+  })
+  const files = []
+  let bytes = 0
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    if (!entry.name.endsWith('.json')) continue
+    if (entry.isSymbolicLink() || !entry.isFile()) throw new Error('runtime plans directory contains a redirected or non-file entry')
+    const file = path.join(directory, entry.name)
+    const stat = fs.lstatSync(file)
+    files.push({ file, name: entry.name, bytes: stat.size, mtimeMs: stat.mtimeMs })
+    bytes += stat.size
+  }
+  return { files, bytes }
+}
+
+export function runtimePaths(repoRoot) {
+  const root = path.join(repoRoot, '.atelier-local', 'runtime')
+  return {
+    root,
+    enrollment: path.join(root, 'enrollment.json'),
+    state: path.join(root, 'state.json'),
+    control: path.join(root, 'control.json'),
+    trace: path.join(root, 'operations.ndjson'),
+    plans: path.join(root, 'plans'),
+    lock: path.join(root, 'operation.lock'),
+  }
+}
+
+export function ensureRuntimeStateRoot(repoRoot, gitExecutable) {
+  const probe = '.atelier-local/runtime/.ignore-probe'
+  const ignored = runGit(gitExecutable, repoRoot, ['check-ignore', '-q', probe], { allowFailure: true })
+  if (!ignored.ok) {
+    throw new Error('.atelier-local/ must be Git-ignored before Atelier Sync writes machine-local state')
+  }
+  const root = ensureContainedPrivateDirectory({
+    workspaceRoot: repoRoot,
+    directory: path.join(repoRoot, '.atelier-local', 'runtime'),
+    label: 'runtime state directory',
+  })
+  const plans = ensureContainedPrivateDirectory({
+    workspaceRoot: repoRoot,
+    directory: path.join(root, 'plans'),
+    label: 'runtime plans directory',
+  })
+  return { ...runtimePaths(repoRoot), root, plans, lock: path.join(root, 'operation.lock') }
+}
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`
+  if (!value || typeof value !== 'object') return JSON.stringify(value)
+  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`
+}
+
+function digest(value) {
+  return crypto.createHash('sha256').update(stableJson(value)).digest('hex')
+}
+
+export function readOperationTrace(tracePath) {
+  const secured = secureRuntimeLeaf(tracePath)
+  const stat = lstatIfPresent(secured)
+  if (!stat) return []
+  if (stat.size > ATELIER_RUNTIME_TRACE_MAX_BYTES) throw new Error('runtime trace exceeds the resident byte ceiling')
+  const records = readRegularTextNoFollow(secured).split('\n').filter(Boolean).map((line, index) => {
+    try {
+      return JSON.parse(line)
+    } catch (error) {
+      throw new Error(`invalid runtime trace line ${index + 1}: ${error.message}`)
+    }
+  })
+  if (records.length > ATELIER_RUNTIME_TRACE_MAX_RECORDS) throw new Error('runtime trace exceeds the resident record ceiling')
+  let previousHash = null
+  records.forEach((record, index) => {
+    const { hash, ...unsigned } = record
+    if (record.sequence !== index + 1) throw new Error(`runtime trace sequence gap at line ${index + 1}`)
+    if ((record.previousHash ?? null) !== previousHash) throw new Error(`runtime trace chain mismatch at line ${index + 1}`)
+    if (digest(unsigned) !== hash) throw new Error(`runtime trace hash mismatch at line ${index + 1}`)
+    previousHash = hash
+  })
+  return records
+}
+
+function boundedTraceEvent(event) {
+  const encoded = JSON.stringify(event)
+  const originalBytes = Buffer.byteLength(encoded)
+  if (originalBytes <= ATELIER_RUNTIME_TRACE_MAX_EVENT_BYTES) return event
+  return {
+    at: event?.at,
+    operation: event?.operation || 'trace-event',
+    outcome: event?.outcome || 'recorded',
+    ...(event?.operationId ? { operationId: String(event.operationId) } : {}),
+    ...(event?.mode ? { mode: String(event.mode) } : {}),
+    details: {
+      truncated: true,
+      originalBytes,
+      originalSha256: crypto.createHash('sha256').update(encoded).digest('hex'),
+    },
+  }
+}
+
+function traceRecoveryCheckpoint(secured, event, reason) {
+  const stat = lstatIfPresent(secured)
+  let priorSha256 = null
+  try {
+    if ((stat?.size ?? 0) <= ATELIER_RUNTIME_TRACE_MAX_BYTES) {
+      priorSha256 = crypto.createHash('sha256').update(readRegularTextNoFollow(secured)).digest('hex')
+    }
+  } catch {
+    // The recovery checkpoint still records the size and reason if the old
+    // regular file cannot be read completely.
+  }
+  const checkpointUnsigned = {
+    schema: ATELIER_RUNTIME_TRACE_SCHEMA,
+    sequence: 1,
+    previousHash: null,
+    at: event.at,
+    operation: 'trace-checkpoint',
+    outcome: 'recovered',
+    details: { reason, priorBytes: stat?.size ?? 0, priorSha256 },
+  }
+  const checkpoint = { ...checkpointUnsigned, hash: digest(checkpointUnsigned) }
+  atomicReplacePrivateText(secured, `${JSON.stringify(checkpoint)}\n`)
+  return checkpoint
+}
+
+export function appendOperationTrace(tracePath, event) {
+  const secured = secureRuntimeLeaf(tracePath)
+  const boundedEvent = boundedTraceEvent(event)
+  let records
+  try {
+    records = readOperationTrace(secured)
+  } catch (error) {
+    records = [traceRecoveryCheckpoint(secured, boundedEvent, error.message)]
+  }
+  let previousHash = records.at(-1)?.hash ?? null
+  const nextProbe = JSON.stringify({ schema: ATELIER_RUNTIME_TRACE_SCHEMA, sequence: records.length + 1, previousHash, ...boundedEvent, hash: '0'.repeat(64) })
+  const currentBytes = lstatIfPresent(secured)?.size ?? 0
+  if (records.length >= ATELIER_RUNTIME_TRACE_MAX_RECORDS || currentBytes + Buffer.byteLength(`${nextProbe}\n`) > ATELIER_RUNTIME_TRACE_MAX_BYTES) {
+    const checkpointUnsigned = {
+      schema: ATELIER_RUNTIME_TRACE_SCHEMA,
+      sequence: 1,
+      previousHash: null,
+      at: boundedEvent.at,
+      operation: 'trace-checkpoint',
+      outcome: 'compacted',
+      details: { compactedRecords: records.length, priorLastHash: previousHash },
+    }
+    const checkpoint = { ...checkpointUnsigned, hash: digest(checkpointUnsigned) }
+    atomicReplacePrivateText(secured, `${JSON.stringify(checkpoint)}\n`)
+    records = [checkpoint]
+    previousHash = checkpoint.hash
+  }
+  const unsigned = {
+    schema: ATELIER_RUNTIME_TRACE_SCHEMA,
+    sequence: records.length + 1,
+    previousHash,
+    ...boundedEvent,
+  }
+  const record = { ...unsigned, hash: digest(unsigned) }
+  const descriptor = openRegularFileNoFollow(
+    secured,
+    fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT,
+    0o600,
+  )
+  try {
+    fs.writeFileSync(descriptor, `${JSON.stringify(record)}\n`)
+    fs.fsyncSync(descriptor)
+  } finally {
+    fs.closeSync(descriptor)
+  }
+  try {
+    fs.chmodSync(secured, 0o600)
+  } catch {
+    // Windows inherits the current user's ACL; POSIX mode is best effort.
+  }
+  return record
+}
+
+function processAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return error?.code === 'EPERM'
+  }
+}
+
+function removeOwnedLock(lockPath, lockNonce) {
+  const stat = lstatIfPresent(lockPath)
+  if (!stat) return
+  if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error('runtime lock is redirected or not a directory')
+  const ownerFile = path.join(lockPath, 'owner.json')
+  const owner = readJsonIfPresent(ownerFile)
+  if (!lockNonce || owner?.lockNonce !== lockNonce) throw new Error('runtime lock ownership changed before release')
+  const quarantine = `${lockPath}.release-${lockNonce}`
+  fs.renameSync(lockPath, quarantine)
+  fs.rmSync(quarantine, { recursive: true, force: true })
+}
+
+export function acquireRepositoryLock(paths, { operation, clock = () => new Date().toISOString(), ownerWriteGraceMs = 30_000 } = {}) {
+  ensureContainedPrivateDirectory({ workspaceRoot: runtimeWorkspaceRoot(paths.root), directory: paths.root, label: 'runtime state directory' })
+  const lockNonce = crypto.randomBytes(16).toString('hex')
+  try {
+    fs.mkdirSync(paths.lock, { mode: 0o700 })
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error
+    const lockStat = lstatIfPresent(paths.lock)
+    if (!lockStat || lockStat.isSymbolicLink() || !lockStat.isDirectory()) {
+      throw new Error('runtime lock is redirected or not a directory')
+    }
+    let owner = null
+    try {
+      owner = readJsonIfPresent(path.join(paths.lock, 'owner.json'))
+    } catch (ownerError) {
+      if (/redirected|regular file|escapes workspace/.test(ownerError.message)) throw ownerError
+      // A truncated owner file is not authority to delete a possibly live lock.
+    }
+    const ownerTimestamp = Date.parse(owner?.acquiredAt || '')
+    const ownerAgeMs = Date.now() - (Number.isFinite(ownerTimestamp) ? ownerTimestamp : lockStat.mtimeMs)
+    if (owner && processAlive(owner.pid) && ownerAgeMs < ATELIER_RUNTIME_LIVE_OWNER_MAX_AGE_MS) {
+      return { ok: false, code: 'repository-busy', owner }
+    }
+    const currentLockStat = lstatIfPresent(paths.lock)
+    if (!currentLockStat || currentLockStat.isSymbolicLink() || !currentLockStat.isDirectory()) {
+      throw new Error('runtime lock is redirected or not a directory')
+    }
+    const ageMs = Date.now() - currentLockStat.mtimeMs
+    if (ageMs < ownerWriteGraceMs) return { ok: false, code: 'repository-busy', owner: owner || { operation: 'lock-owner-pending', ageMs } }
+    const claimPath = path.join(paths.lock, 'recovery.claim')
+    let claimDescriptor
+    try {
+      claimDescriptor = openRegularFileNoFollow(
+        claimPath,
+        fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL,
+        0o600,
+      )
+      fs.writeFileSync(claimDescriptor, lockNonce)
+      fs.fsyncSync(claimDescriptor)
+    } catch (claimError) {
+      if (claimError?.code === 'EEXIST') {
+        const claimStat = lstatIfPresent(claimPath)
+        if (!claimStat || claimStat.isSymbolicLink() || !claimStat.isFile()) throw new Error('runtime recovery claim is redirected or not a regular file')
+        const claimAgeMs = Date.now() - claimStat.mtimeMs
+        if (claimAgeMs < ownerWriteGraceMs) {
+          return { ok: false, code: 'repository-busy', owner: owner || { operation: 'stale-lock-recovery', ageMs: claimAgeMs } }
+        }
+        const staleClaim = `${claimPath}.stale-${lockNonce}`
+        try {
+          fs.renameSync(claimPath, staleClaim)
+          const movedClaimStat = lstatIfPresent(staleClaim)
+          if (!movedClaimStat || movedClaimStat.dev !== claimStat.dev || movedClaimStat.ino !== claimStat.ino) {
+            if (movedClaimStat && !lstatIfPresent(claimPath)) fs.renameSync(staleClaim, claimPath)
+            return { ok: false, code: 'repository-busy', owner: owner || { operation: 'stale-lock-recovery-identity-changed' } }
+          }
+          fs.unlinkSync(staleClaim)
+          claimDescriptor = openRegularFileNoFollow(
+            claimPath,
+            fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL,
+            0o600,
+          )
+          fs.writeFileSync(claimDescriptor, lockNonce)
+          fs.fsyncSync(claimDescriptor)
+        } catch (retryError) {
+          if (retryError?.code === 'EEXIST' || retryError?.code === 'ENOENT') {
+            return { ok: false, code: 'repository-busy', owner: owner || { operation: 'stale-lock-recovery-lost' } }
+          }
+          throw retryError
+        }
+      } else if (claimError?.code === 'ENOENT') {
+        return { ok: false, code: 'repository-busy', owner: owner || { operation: 'stale-lock-recovery' } }
+      } else {
+        throw claimError
+      }
+    } finally {
+      if (claimDescriptor != null) fs.closeSync(claimDescriptor)
+    }
+    let currentOwner = null
+    try {
+      currentOwner = readJsonIfPresent(path.join(paths.lock, 'owner.json'))
+    } catch (ownerError) {
+      if (/redirected|regular file|escapes workspace/.test(ownerError.message)) throw ownerError
+      // The exclusive recovery claim and age gate permit quarantining a stale,
+      // corrupt owner record; corruption is never authority to touch a new lock.
+    }
+    const currentOwnerTimestamp = Date.parse(currentOwner?.acquiredAt || '')
+    const currentOwnerAgeMs = Date.now() - (Number.isFinite(currentOwnerTimestamp) ? currentOwnerTimestamp : lockStat.mtimeMs)
+    if (currentOwner && processAlive(currentOwner.pid) && currentOwnerAgeMs < ATELIER_RUNTIME_LIVE_OWNER_MAX_AGE_MS) {
+      try {
+        if (readRegularTextNoFollow(claimPath) === lockNonce) fs.unlinkSync(claimPath)
+      } catch {
+        // The current owner controls the lock; leave it untouched on uncertainty.
+      }
+      return { ok: false, code: 'repository-busy', owner: currentOwner }
+    }
+    const quarantine = `${paths.lock}.stale-${lockNonce}`
+    try {
+      const beforeRecovery = lstatIfPresent(paths.lock)
+      if (!beforeRecovery || beforeRecovery.dev !== lockStat.dev || beforeRecovery.ino !== lockStat.ino) {
+        return { ok: false, code: 'repository-busy', owner: { operation: 'stale-lock-recovery-identity-changed' } }
+      }
+      fs.renameSync(paths.lock, quarantine)
+      const movedLock = lstatIfPresent(quarantine)
+      if (!movedLock || movedLock.dev !== lockStat.dev || movedLock.ino !== lockStat.ino) {
+        if (movedLock && !lstatIfPresent(paths.lock)) fs.renameSync(quarantine, paths.lock)
+        return { ok: false, code: 'repository-busy', owner: { operation: 'stale-lock-recovery-identity-changed' } }
+      }
+      fs.mkdirSync(paths.lock, { mode: 0o700 })
+    } catch (recoveryError) {
+      if (recoveryError?.code === 'EEXIST' || recoveryError?.code === 'ENOENT') {
+        if (lstatIfPresent(quarantine)) fs.rmSync(quarantine, { recursive: true, force: true })
+        return { ok: false, code: 'repository-busy', owner: { operation: 'stale-lock-recovery-lost' } }
+      }
+      throw recoveryError
+    }
+    fs.rmSync(quarantine, { recursive: true, force: true })
+  }
+  const owner = { lockNonce, pid: process.pid, operation, acquiredAt: clock() }
+  atomicWriteJson(path.join(paths.lock, 'owner.json'), owner)
+  return {
+    ok: true,
+    owner,
+    release() {
+      removeOwnedLock(paths.lock, lockNonce)
+    },
+  }
+}
+
+export function writeRuntimeState(paths, state) {
+  let value = { schema: ATELIER_RUNTIME_STATE_SCHEMA, ...state }
+  const encodedBytes = Buffer.byteLength(`${JSON.stringify(value, null, 2)}\n`)
+  if (encodedBytes > ATELIER_RUNTIME_STATE_MAX_BYTES) {
+    value = {
+      schema: ATELIER_RUNTIME_STATE_SCHEMA,
+      status: 'attention',
+      code: 'runtime-state-resident-ceiling',
+      message: 'runtime state exceeded its resident byte ceiling and was compacted',
+      incidentId: state.incidentId ?? null,
+      updatedAt: state.updatedAt ?? new Date().toISOString(),
+      observation: state.observation ? {
+        sourceSchema: state.observation.sourceSchema ?? state.observation.schema,
+        observedAt: state.observation.observedAt,
+        complete: false,
+        root: state.observation.root,
+        branch: state.observation.branch ? { branch: state.observation.branch.branch, head: state.observation.branch.head } : null,
+        status: state.observation.status ? { clean: state.observation.status.clean, digest: state.observation.status.digest } : null,
+        blockers: [{ code: 'runtime-state-resident-ceiling', message: 'full resident state was too large to retain', details: { limitBytes: ATELIER_RUNTIME_STATE_MAX_BYTES, observedBytes: encodedBytes } }],
+      } : null,
+      details: { limitBytes: ATELIER_RUNTIME_STATE_MAX_BYTES, observedBytes: encodedBytes },
+    }
+  }
+  atomicWriteJson(paths.state, value)
+  return value
+}
+
+export function readRuntimeControl(paths) {
+  return readJsonIfPresent(paths.control) || { paused: false, reason: null, updatedAt: null }
+}
+
+export function writeRuntimeControl(paths, { paused, reason = null, updatedAt = new Date().toISOString() }) {
+  const control = { paused: Boolean(paused), reason: paused ? String(reason || 'paused by user') : null, updatedAt }
+  atomicWriteJson(paths.control, control)
+  return control
+}

package/src/runtime/obsidian/app-capability.mjs

@@ -0,0 +1,110 @@
+import { refuse } from './errors.mjs'
+
+// Whether the installed Obsidian may be published through and opened.
+//
+// Nothing here looks at this machine. What is installed is learned through an
+// injected `appProbe`:
+//
+//   appProbe.inspect()                 -> { installed, cli, running, version }
+//   appProbe.vaultState({ vaultRoot }) -> { answered, indexReady }
+//
+// `installed` and `cli` are booleans, `running` is true, false or null (not
+// known) and `version` is the app's own version text or null. The production
+// probe is a separate module that only the real command-line entries load;
+// every test passes its own.
+
+// The publication protocol sets the view's undocumented `lastSavedData` field.
+// 1.13.7 is the only app version that protocol was proven on, so it is the
+// floor. Raising the ceiling needs the protocol cases re-run on that release.
+export const MINIMUM_APP_VERSION = '1.13.7'
+
+export const APP_OUTCOMES = Object.freeze(['qualified', 'app-missing', 'app-cli-unavailable', 'app-version-unsupported'])
+
+const VERSION = /^v?(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})(?:-([0-9A-Za-z]+(?:\.[0-9A-Za-z]+)*))?(?:\+[0-9A-Za-z.-]+)?(?=$|[\s(])/
+
+// { major, minor, patch, prerelease: string[] } or null. Only a version at the
+// very start of the text counts; anything else is not a version.
+export function parseAppVersion(text) {
+  if (typeof text !== 'string' || text.length > 200) return null
+  const match = VERSION.exec(text.trim())
+  if (!match) return null
+  return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]), prerelease: match[4] === undefined ? [] : match[4].split('.') }
+}
+
+function comparePrerelease(left, right) {
+  // No prerelease ranks above any prerelease of the same version.
+  if (left.length === 0 || right.length === 0) return left.length === right.length ? 0 : left.length === 0 ? 1 : -1
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    if (left[index] === undefined) return -1
+    if (right[index] === undefined) return 1
+    const [a, b] = [left[index], right[index]]
+    const [aNumeric, bNumeric] = [/^\d+$/.test(a), /^\d+$/.test(b)]
+    if (aNumeric && bNumeric) { if (Number(a) !== Number(b)) return Number(a) < Number(b) ? -1 : 1 } else if (aNumeric !== bNumeric) return aNumeric ? -1 : 1
+    else if (a !== b) return a < b ? -1 : 1
+  }
+  return 0
+}
+
+// Pure. -1, 0 or 1; null when either side is not a version.
+export function compareAppVersions(left, right) {
+  const [a, b] = [parseAppVersion(left), parseAppVersion(right)]
+  if (a === null || b === null) return null
+  for (const part of ['major', 'minor', 'patch']) if (a[part] !== b[part]) return a[part] < b[part] ? -1 : 1
+  return comparePrerelease(a.prerelease, b.prerelease)
+}
+
+// Pure. A version that cannot be read does not meet the floor.
+export function meetsMinimumAppVersion(version, floor = MINIMUM_APP_VERSION) {
+  const order = compareAppVersions(version, floor)
+  return order !== null && order >= 0
+}
+
+// Pure. `requireVersion: false` lets an installed app that is positively not
+// running pass without a version: nothing is published through an app that
+// does not run, and the version is asked for again once it does.
+export function qualifyApp(observation, { requireVersion = true, floor = MINIMUM_APP_VERSION } = {}) {
+  const seen = observation !== null && typeof observation === 'object' ? observation : {}
+  const base = { floor, version: typeof seen.version === 'string' ? seen.version.slice(0, 80) : null, running: seen.running === true ? true : seen.running === false ? false : null }
+  if (seen.installed !== true) return { ...base, outcome: 'app-missing', reason: 'no-app-found' }
+  if (seen.cli !== true) return { ...base, outcome: 'app-cli-unavailable', reason: 'cli-capability-absent' }
+  if (base.version === null) {
+    if (!requireVersion && base.running === false) return { ...base, outcome: 'qualified', reason: 'app-not-running-version-not-needed', versionChecked: false }
+    return { ...base, outcome: 'app-version-unsupported', reason: 'version-unknown' }
+  }
+  if (parseAppVersion(base.version) === null) return { ...base, outcome: 'app-version-unsupported', reason: 'version-unreadable' }
+  if (!meetsMinimumAppVersion(base.version, floor)) return { ...base, outcome: 'app-version-unsupported', reason: 'below-minimum-version' }
+  return { ...base, outcome: 'qualified', reason: 'meets-minimum-version', versionChecked: true }
+}
+
+export async function inspectApp(appProbe) {
+  if (typeof appProbe?.inspect !== 'function') throw new TypeError('an appProbe with inspect() is required')
+  try { return await appProbe.inspect() } catch { return { installed: false, cli: false, running: null, version: null } }
+}
+
+// The adapter factory of a service that reaches a real app. The editor adapter
+// is constructed only after the app qualified; otherwise the factory refuses,
+// typed, and the engine records that reason and publishes nothing. The answer
+// is remembered briefly so a tick over many views asks once.
+export function createQualifiedAdapterFactory({ appProbe, createAdapter, floor = MINIMUM_APP_VERSION, maxAgeMs = 10_000, now = () => Date.now() } = {}) {
+  if (typeof appProbe?.inspectSync !== 'function') throw new TypeError('the qualified adapter factory needs an appProbe with inspectSync()')
+  if (typeof createAdapter !== 'function') throw new TypeError('the qualified adapter factory needs createAdapter')
+  let last = null
+  const qualification = () => {
+    if (last === null || now() - last.at > maxAgeMs) {
+      let observation
+      try { observation = appProbe.inspectSync() } catch { observation = null }
+      last = { at: now(), result: qualifyApp(observation, { requireVersion: false, floor }) }
+    }
+    return last.result
+  }
+  const factory = (input) => {
+    const result = qualification()
+    // No app at all is not an unqualified app: the publisher's own path needs none, and its adapter finds no process.
+    if (result.outcome !== 'qualified' && result.outcome !== 'app-missing') refuse(result.outcome, 'the installed Obsidian does not qualify; nothing is published through it', { reason: result.reason, floor: result.floor, version: result.version })
+    return createAdapter(input)
+  }
+  factory.qualification = qualification
+  // What was last learned, without asking again: for a status answer.
+  factory.lastQualification = () => last?.result ?? null
+  return factory
+}

package/src/runtime/obsidian/app-production-seams.mjs

@@ -0,0 +1,96 @@
+import { execFile, execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { defaultCliPath, defaultObsidianProcessProbe } from '../../projection/obsidian/publication/transport.mjs'
+
+// The production seams of `obsidian open` and of the service's adapter
+// factory: the only code that asks the installed Obsidian anything or asks the
+// operating system to open it.
+//
+// This module is imported by exactly two places, both real command-line
+// entries and both behind an explicit `--adapter=obsidian-cli`: the service
+// entry (service-main.mjs) and the command entry (src/commands/obsidian.mjs,
+// `production: true`). No test imports it, and importing it leaves a trace
+// below that the test suite asserts is absent.
+//
+// Status: written against the documented command-line interface and NOT yet
+// exercised against a running app. The acceptance work qualifies it on an
+// isolated host before any of it is relied on; until then every answer it
+// cannot establish is the failing one.
+globalThis[Symbol.for('mnstry.atelier.obsidian.production-seams-loaded')] = true
+
+const CLI_TIMEOUT_MS = 5000
+
+function installedAppPath(platform) {
+  if (platform === 'darwin') return '/Applications/Obsidian.app'
+  return null
+}
+
+function cliExists(cliPath) {
+  if (!path.isAbsolute(cliPath)) return null // found through PATH or not at all: only running it tells
+  try { return fs.statSync(cliPath).isFile() } catch { return false }
+}
+
+const observationOf = ({ platform, cliPath, processes, versionText }) => {
+  const appPath = installedAppPath(platform)
+  const present = cliExists(cliPath)
+  const answered = typeof versionText === 'string' && versionText.trim() !== ''
+  return {
+    installed: appPath === null ? (present !== false && (answered || present === true)) : fs.existsSync(appPath),
+    cli: present === true || answered,
+    running: processes === 'running' ? true : processes === 'absent' ? false : null,
+    version: answered ? versionText.trim() : null,
+  }
+}
+
+export function createProductionAppProbe({ platform = process.platform, env = process.env, cliPath = defaultCliPath(platform) } = {}) {
+  const options = { env, timeout: CLI_TIMEOUT_MS, killSignal: 'SIGKILL', encoding: 'utf8', maxBuffer: 1024 * 1024 }
+  return {
+    // For the service's adapter factory, which is synchronous. The version is asked for only while an app runs.
+    inspectSync() {
+      const processes = defaultObsidianProcessProbe({ platform })
+      let versionText = null
+      if (processes !== 'absent') { try { versionText = execFileSync(cliPath, ['version'], { ...options, stdio: ['ignore', 'pipe', 'ignore'] }) } catch { versionText = null } }
+      return observationOf({ platform, cliPath, processes, versionText })
+    },
+    inspect() {
+      const processes = defaultObsidianProcessProbe({ platform })
+      if (processes === 'absent') return Promise.resolve(observationOf({ platform, cliPath, processes, versionText: null }))
+      return new Promise((resolve) => {
+        execFile(cliPath, ['version'], options, (error, stdout) => resolve(observationOf({ platform, cliPath, processes, versionText: error ? null : stdout })))
+      })
+    },
+    // Whether the app answers for exactly this vault and has finished reading it.
+    vaultState({ vaultRoot }) {
+      const code = '(()=>JSON.stringify({basePath:app.vault.adapter.basePath,ready:app.metadataCache.initialized===true}))()'
+      return new Promise((resolve) => {
+        execFile(cliPath, ['eval', `code=${code}`], options, (error, stdout) => {
+          if (error) return resolve({ answered: false, indexReady: false })
+          try {
+            const text = String(stdout)
+            const value = JSON.parse(JSON.parse(text.slice(text.indexOf('=> ') + 3)))
+            return resolve({ answered: value.basePath === vaultRoot, indexReady: value.basePath === vaultRoot && value.ready === true })
+          } catch { return resolve({ answered: false, indexReady: false }) }
+        })
+      })
+    },
+  }
+}
+
+// Asks the operating system to open the vault in Obsidian. No shell.
+export function createProductionLauncher({ platform = process.platform, env = process.env } = {}) {
+  const command = platform === 'darwin' ? '/usr/bin/open' : platform === 'linux' ? 'xdg-open' : null
+  return {
+    open({ vaultRoot }) {
+      if (command === null) return Promise.resolve({ launched: false, reason: 'launcher-platform-unqualified' })
+      const uri = `obsidian://open?path=${encodeURIComponent(vaultRoot)}`
+      return new Promise((resolve) => {
+        execFile(command, [uri], { env, timeout: 15_000 }, (error) => resolve(error ? { launched: false, reason: 'os-open-failed' } : { launched: true, reason: 'os-open-accepted' }))
+      })
+    },
+  }
+}
+
+export function createProductionAppSeams(options = {}) {
+  return { appProbe: createProductionAppProbe(options), launcher: createProductionLauncher(options) }
+}

package/src/runtime/obsidian/contributions/proposal-adapter.mjs

@@ -0,0 +1,4 @@
+import { createProposalAdapterContribution } from '../../../projection/obsidian/proposals/contribution.mjs'
+
+// The proposal adapter: what the engine hands structural edits to on a tick, and `atelier obsidian proposals`.
+export default createProposalAdapterContribution()

package/src/runtime/obsidian/contributions/selection-ui.mjs

@@ -0,0 +1,4 @@
+import { createSelectionContribution } from '../../../projection/obsidian/selection-ui/contribution.mjs'
+
+// The selection, conflict and apply-policy operations: `atelier obsidian selection`, `conflicts` and `apply-policy`.
+export default createSelectionContribution()

package/src/runtime/obsidian/contributions/source-apply.mjs

@@ -0,0 +1,4 @@
+import { createSourceApplyContribution } from '../../../projection/obsidian/edits/contribution.mjs'
+
+// The source apply operation: what the engine dispatches to in automatic mode, and `atelier obsidian apply`.
+export default createSourceApplyContribution()