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

package/src/readiness-protocols/evidence.mjs

@@ -0,0 +1,282 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { fileURLToPath } from 'node:url'
+import { canonicalize } from '../attestation/jcs.mjs'
+import { buildGraph } from '../graph/graph.mjs'
+import {
+  loadExtensionPacks,
+  createProtocolRegistry,
+} from '../extension-packs/loader.mjs'
+import { readRegularTextNoFollow } from '../project/private-state.mjs'
+import { createCollaborationEventLedger } from '../collaboration/event-ledger.mjs'
+import { inspectPackLifecycle } from '../extension-packs/lifecycle.mjs'
+import { readLocalOverlay } from '../project/config.mjs'
+import { readBoundedSource } from './source-read.mjs'
+export { readBoundedSource } from './source-read.mjs'
+import { validReviewArtifact } from '../collaboration/review-contracts.mjs'
+import { buildReadinessRun, answerForField } from './runtime.mjs'
+
+export const hashEvidence = (value) =>
+  `sha256:${crypto
+    .createHash('sha256')
+    .update(canonicalize(value))
+    .digest('hex')}`
+const hashBytes = (value) =>
+  `sha256:${crypto.createHash('sha256').update(value).digest('hex')}`
+const packageRoot = fileURLToPath(new URL('../../', import.meta.url))
+function evaluatorInventory() {
+  const files = ['package.json']
+  function visit(relative) {
+    for (const name of fs
+      .readdirSync(path.join(packageRoot, relative))
+      .sort()) {
+      const next = path.posix.join(relative, name),
+        stat = fs.lstatSync(path.join(packageRoot, next))
+      if (stat.isSymbolicLink()) throw new Error('redirected evaluator input')
+      if (stat.isDirectory()) visit(next)
+      else if (stat.isFile() && /\.(mjs|json)$/.test(name)) files.push(next)
+    }
+  }
+  visit('src')
+  visit('contracts')
+  return files
+    .sort()
+    .map((file) => ({
+      file,
+      digest: hashBytes(readRegularTextNoFollow(path.join(packageRoot, file))),
+    }))
+}
+const evaluator = hashEvidence(evaluatorInventory())
+
+function currentInputs(project, protocolId, answers) {
+  if (
+    project.configPath &&
+    hashEvidence(JSON.parse(readRegularTextNoFollow(project.configPath))) !==
+      hashEvidence(project.config)
+  )
+    throw new Error('project config changed; resolve the project again')
+  if (hashEvidence(evaluatorInventory()) !== evaluator)
+    throw new Error('evaluator changed; restart before review')
+  if (
+    project.localOverlay &&
+    hashEvidence(readLocalOverlay({ configDir: project.configDir }).overlay) !==
+      hashEvidence(project.localOverlay.overlay)
+  )
+    throw new Error('local overlay changed; resolve again')
+  const loaded = loadExtensionPacks(project)
+  const packs = loaded.packs ?? loaded
+  const lifecycle = inspectPackLifecycle(project, packs)
+  if (!lifecycle.ok) throw new Error(lifecycle.errors.join('; '))
+  const registry = createProtocolRegistry({ packs })
+  const protocol = registry.protocolById(protocolId)
+  if (!protocol) throw new Error('protocol unavailable for evidence binding')
+  const graph = buildGraph(project)
+  if (graph.errors.length)
+    throw new Error('source graph is invalid; evidence capture refused')
+  if (graph.nodes.length > 256)
+    throw new Error('review evidence exceeds bounded source count')
+  const sources = [],
+    excerpts = new Map()
+  for (const node of graph.nodes) {
+    const repo = project.repos.find(
+      (entry) => entry.name === node.repo && !entry.external,
+    )
+    if (!repo?.path) throw new Error('source repository unavailable')
+    const source = readBoundedSource(repo.path, node.path)
+    const metadata = !/\.md$/i.test(node.path)
+      ? readBoundedSource(repo.path, `${node.path}.kg.json`).digest
+      : null
+    excerpts.set(node.id, source.text.slice(0, 2000))
+    sources.push({
+      id: node.id,
+      repo: node.repo,
+      path: node.path,
+      audience: node.audience,
+      digest: source.digest,
+      metadata,
+    })
+  }
+  sources.sort((a, b) =>
+    `${a.repo}/${a.path}`.localeCompare(`${b.repo}/${b.path}`, 'en'),
+  )
+  const claimEvidence = protocol.claimMappings.map((mapping) => {
+    const raw = answerForField(answers, mapping.evidence)
+    const references = (Array.isArray(raw) ? raw.flat(Infinity) : [raw])
+      .filter((value) => typeof value === 'string' && value.trim())
+      .map((value) => value.trim())
+    const resolved = [],
+      unresolved = []
+    for (const reference of references) {
+      const source = sources.find((item) => item.id === reference)
+      if (source)
+        resolved.push({
+          id: source.id,
+          repo: source.repo,
+          path: source.path,
+          digest: source.digest,
+          excerpt: excerpts.get(source.id),
+        })
+      else unresolved.push(reference)
+    }
+    return {
+      mappingId: mapping.id,
+      sourceFields: mapping.sourceFields,
+      answers: Object.fromEntries(
+        mapping.sourceFields.map((field) => [
+          field,
+          answerForField(answers, field) ?? null,
+        ]),
+      ),
+      evidenceField: mapping.evidence,
+      references,
+      resolved,
+      unresolved,
+      status: !references.length
+        ? 'missing'
+        : unresolved.length
+        ? 'unresolved'
+        : 'linked-source',
+    }
+  })
+  const readPolicy = (file) =>
+    fs.existsSync(file) ? hashBytes(readRegularTextNoFollow(file)) : null
+  return {
+    schema: 'atelier-review-evidence@v1',
+    protocolId,
+    protocol,
+    protocolDigest: hashEvidence(protocol),
+    answers,
+    answersDigest: hashEvidence(answers),
+    configDigest: hashEvidence(project.config),
+    lifecycleDigest: hashEvidence(lifecycle),
+    policyDigest: hashEvidence({
+      access: readPolicy(project.repoAccessPath),
+      boundary: readPolicy(project.boundaryPolicyPath),
+    }),
+    packs: packs
+      .map(({ id, version, digest }) => ({ id, version, digest }))
+      .sort((a, b) => a.id.localeCompare(b.id, 'en')),
+    evaluator: { id: 'answer-completeness/v1', digest: evaluator },
+    sources,
+    claimEvidence,
+    limitations: [
+      'Answers are operator assertions; source presence does not substantiate each claim.',
+      'No calibrated evidence confidence or runtime acceptance is established.',
+    ],
+  }
+}
+
+export function captureReviewEvidence(project, protocolId, answers) {
+  const first = currentInputs(project, protocolId, answers)
+  const second = currentInputs(project, protocolId, answers)
+  const digest = hashEvidence(first)
+  if (digest !== hashEvidence(second))
+    throw new Error('review inputs changed during capture')
+  const snapshot = { ...first, digest }
+  if (!validReviewArtifact('evidence', snapshot))
+    throw new Error('evidence contract invalid or exceeds bounds')
+  return snapshot
+}
+
+export function evidenceLedger(project) {
+  return createCollaborationEventLedger({
+    workspaceRoot: project.configDir,
+    ledgerPath: path.join(
+      project.configDir,
+      '.atelier-local/review/evidence.ndjson',
+    ),
+  })
+}
+
+export function recordReviewEvidence(project, run) {
+  const snapshot = captureReviewEvidence(project, run.protocolId, run.answers)
+  if (
+    hashEvidence(
+      buildReadinessRun({
+        project,
+        protocol: snapshot.protocol,
+        answers: run.answers,
+        createdAt: run.createdAt,
+      }),
+    ) !== hashEvidence(run)
+  )
+    throw new Error('run no longer matches its current protocol and evaluator')
+  const payload = {
+    schema: 'atelier-bound-run@v1',
+    run,
+    runDigest: hashEvidence(run),
+    snapshot,
+  }
+  if (!validBoundRun(payload)) throw new Error('bound run contract invalid')
+  const ledger = evidenceLedger(project)
+  const existing = ledger.eventsFor(run.runId)
+  if (!existing.ok) throw new Error(existing.error)
+  if (existing.events.length) {
+    if (hashEvidence(existing.events[0].payload) !== hashEvidence(payload))
+      throw new Error('run identity already has different evidence')
+    return existing.events[0].payload
+  }
+  const result = ledger.append({
+    aggregateId: run.runId,
+    expectedVersion: 0,
+    type: 'run-bound',
+    actor: 'local-runtime',
+    payload,
+  })
+  if (!result.ok) throw new Error(result.error)
+  return payload
+}
+
+export function validBoundRun(payload) {
+  if (!validReviewArtifact('bound', payload)) return false
+  const { digest, ...body } = payload.snapshot
+  const { run, snapshot } = payload
+  return (
+    payload.runDigest === hashEvidence(run) &&
+    digest === hashEvidence(body) &&
+    snapshot.protocolDigest === hashEvidence(snapshot.protocol) &&
+    snapshot.answersDigest === hashEvidence(snapshot.answers) &&
+    snapshot.answersDigest === hashEvidence(run.answers) &&
+    snapshot.protocol.id === run.protocolId &&
+    snapshot.protocolId === run.protocolId &&
+    snapshot.claimEvidence.length === run.claims.length &&
+    snapshot.claimEvidence.every(
+      (entry, index) =>
+        entry.mappingId === snapshot.protocol.claimMappings[index]?.id,
+    )
+  )
+}
+
+export function loadBoundRun(project, runId) {
+  const result = evidenceLedger(project).eventsFor(runId)
+  if (!result.ok) return result
+  if (result.events.length !== 1 || result.events[0].type !== 'run-bound')
+    return {
+      ok: false,
+      status: 409,
+      error: 'run lacks immutable review evidence',
+    }
+  const payload = result.events[0].payload
+  const { digest, ...body } = payload.snapshot ?? {}
+  if (
+    !validBoundRun(payload) ||
+    payload.schema !== 'atelier-bound-run@v1' ||
+    payload.run?.runId !== runId ||
+    payload.runDigest !== hashEvidence(payload.run) ||
+    digest !== hashEvidence(body)
+  )
+    return { ok: false, status: 422, error: 'run evidence is invalid' }
+  return { ok: true, status: 200, ...payload }
+}
+
+export function currentRunEligibility(project, bound) {
+  try {
+    return (
+      captureReviewEvidence(project, bound.run.protocolId, bound.run.answers)
+        .digest === bound.snapshot.digest
+    )
+  } catch {
+    return false
+  }
+}

package/src/readiness-protocols/runtime.mjs

@@ -73,7 +73,7 @@ function nestedAnswer(value, parts) {
   return nestedAnswer(value[head], rest)
 }
 
-function answerForField(answers, fieldId) {
+export function answerForField(answers, fieldId) {
   for (const key of pathVariants(fieldId)) {
     if (Object.hasOwn(answers, key)) return answers[key]
   }
@@ -119,9 +119,8 @@ export function claimsForProtocolRun({ protocol, answers, projectName, runId, cr
     provider: 'atelier-readiness',
     status: 'proposed',
     promoted: false,
-    confidence: Object.values(answers).some(answerPresent) ? 0.7 : 0.2,
     evidence: [`readiness-run:${runId}`],
-    notes: [`Proposed ${mapping.id} from ${protocol.title}.`],
+    notes: [`Proposed ${mapping.id} from ${protocol.title}.`, 'Answer presence is not evidence confidence; human judgment is required.'],
     createdAt,
     }
   })
@@ -147,6 +146,7 @@ export function buildReadinessRun({ project, protocol, answers = {}, createdAt =
     claims: claimsForProtocolRun({ protocol, answers: normalizedAnswers, projectName, runId, createdAt }),
     safety: {
       runtimeMutation: false,
+      runtimeImport: false,
       canonicalWrites: false,
       claimOnly: true,
       storage: 'ignored-local',
@@ -367,6 +367,7 @@ export function buildTenantPacket(project, { runs = listProtocolRuns(project), r
     ext: {
       'mnstry.atelier': {
         extensionPacks: packContribution,
+        scoreMeaning: 'Legacy readinessScore measures completed input dimensions; it is not evidence confidence or runtime admission.',
       },
     },
   }

package/src/readiness-protocols/source-read.mjs

@@ -0,0 +1,39 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { openRegularFileNoFollow } from '../project/private-state.mjs'
+const hashBytes = (value) =>
+  `sha256:${crypto.createHash('sha256').update(value).digest('hex')}`
+
+export function readBoundedSource(root, relative) {
+  if (
+    typeof relative !== 'string' ||
+    path.isAbsolute(relative) ||
+    relative.split(/[\\/]/).some((part) => part === '..' || part === '.git')
+  )
+    throw new Error('source reference escapes declared boundary')
+  const realRoot = fs.realpathSync(root)
+  const file = path.resolve(realRoot, relative)
+  let cursor = realRoot
+  for (const part of path.relative(realRoot, file).split(path.sep)) {
+    cursor = path.join(cursor, part)
+    if (fs.lstatSync(cursor).isSymbolicLink())
+      throw new Error('redirected source reference refused')
+  }
+  const descriptor = openRegularFileNoFollow(file)
+  try {
+    const before = fs.fstatSync(descriptor)
+    if (before.size > 1024 * 1024)
+      throw new Error('source exceeds review byte bound')
+    const bytes = fs.readFileSync(descriptor)
+    const after = fs.fstatSync(descriptor)
+    if (before.size !== after.size || before.mtimeMs !== after.mtimeMs)
+      throw new Error('source changed during read')
+    return {
+      digest: hashBytes(bytes),
+      text: new TextDecoder('utf-8', { fatal: true }).decode(bytes),
+    }
+  } finally {
+    fs.closeSync(descriptor)
+  }
+}

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()

package/src/runtime/obsidian/contributions.mjs

@@ -0,0 +1,27 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { refuse } from './errors.mjs'
+
+// Where later work plugs in without touching a shared file: every module in
+// `contributions/` beside this file is a contribution. Its default export is
+// `{ id, register({ extensions, operations }) }`. The command and the service
+// entry both load the directory, so an apply operation registered there is
+// the one the service dispatches to and the one `status` reports.
+//
+// Only regular `.mjs` files directly in that directory are loaded, in name
+// order. The directory ships with the package; nothing outside it is read.
+
+export const CONTRIBUTIONS_DIRECTORY = path.join(path.dirname(fileURLToPath(import.meta.url)), 'contributions')
+
+export async function loadContributions({ directory = CONTRIBUTIONS_DIRECTORY } = {}) {
+  let entries
+  try { entries = fs.readdirSync(directory, { withFileTypes: true }) } catch (error) { if (error.code === 'ENOENT') return []; throw error }
+  const contributions = []
+  for (const entry of entries.filter((item) => item.isFile() && item.name.endsWith('.mjs')).sort((left, right) => (left.name < right.name ? -1 : 1))) {
+    const loaded = await import(pathToFileURL(path.join(directory, entry.name)).href)
+    if (loaded.default === null || typeof loaded.default !== 'object' || typeof loaded.default.register !== 'function') refuse('invalid-extension', 'a contribution module must export { id, register } by default', { file: entry.name })
+    contributions.push(loaded.default)
+  }
+  return contributions
+}

package/src/runtime/obsidian/documents.mjs

@@ -0,0 +1,37 @@
+import { refuse } from './errors.mjs'
+
+// Helpers shared by this module's private documents. Each document is
+// versioned by its `schema` string, closed (an unknown key refuses) and
+// written in one canonical form, so equal state is equal bytes.
+
+export const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+
+function sortKeys(value) {
+  if (Array.isArray(value)) return value.map(sortKeys)
+  if (!isPlainObject(value)) return value
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortKeys(value[key])]))
+}
+
+// Keys sorted at every depth, two-space indentation, one final newline.
+export function canonicalJson(value) {
+  return `${JSON.stringify(sortKeys(value), null, 2)}\n`
+}
+
+export function closedObject(value, { required = [], optional = [] }, code, label) {
+  if (!isPlainObject(value)) refuse(code, `${label} must be an object`)
+  const allowed = new Set([...required, ...optional])
+  const unknown = Object.keys(value).filter((key) => !allowed.has(key))
+  if (unknown.length > 0) refuse(code, `${label} carries an unknown key`, { keys: unknown.sort() })
+  const missing = required.filter((key) => !Object.hasOwn(value, key))
+  if (missing.length > 0) refuse(code, `${label} lacks a required key`, { keys: missing })
+  return value
+}
+
+export const compareText = (left, right) => (left < right ? -1 : left > right ? 1 : 0)
+
+export function isoTime(clock) {
+  const value = clock()
+  const date = value instanceof Date ? value : new Date(value)
+  if (Number.isNaN(date.getTime())) refuse('missing-clock', 'the injected clock did not return a time')
+  return date.toISOString()
+}