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

package/src/projection/obsidian/selection-ui/focus.mjs

@@ -3,8 +3,11 @@ import { refuse } from '../../../runtime/obsidian/errors.mjs'
 
 // Focus: the full vault stays on disk and the native Graph view is filtered
 // with a "Search files" query derived from the selected set. The query names
-// every selected note by its exact vault-relative path, quoted and escaped
-// the way the app's search syntax reads a quoted term, joined with OR.
+// every selected note by its exact vault-relative path, as an anchored regular
+// expression in the app's `path:/…/` search, joined with OR: a path search
+// matches substrings, and with titles as names one path can lie inside
+// another (`r/a/Plan.md` inside `qr/a/Plan.md`), so only an anchored term
+// matches exactly one note.
 //
 // Nothing here writes a file. The query and the core-Bookmark payload are
 // values a person, an agent or the acceptance procedure applies in the app;
@@ -13,7 +16,9 @@ import { refuse } from '../../../runtime/obsidian/errors.mjs'
 // Atelier. Whether the installed app applies the query as built is an
 // acceptance question (AP-02), not something this module can answer.
 
-export const FOCUS_QUERY_VERSION = 'obsidian-graph-search-paths/v1'
+export const FOCUS_QUERY_VERSION = 'obsidian-graph-search-paths/v2'
+// Versions a persisted focus may carry and still be read: v1 quoted each path as a substring term.
+export const FOCUS_QUERY_VERSIONS_READ = Object.freeze(['obsidian-graph-search-paths/v1', FOCUS_QUERY_VERSION])
 export const FOCUS_BOOKMARK_TYPE = 'graph'
 // The files under .obsidian/ the app's UI owns. Atelier reads none of them
 // and writes none of them; a focus is applied through the app, never by
@@ -21,14 +26,16 @@ export const FOCUS_BOOKMARK_TYPE = 'graph'
 export const UI_OWNED_SETTINGS_FILES = Object.freeze(['workspace.json', 'graph.json', 'bookmarks.json'])
 export const MAX_FOCUS_PATHS = 100000
 
-// A quoted search term: backslash and double quote are escaped; anything
-// that is not printable text cannot be typed into a search box and refuses.
+// An anchored regular-expression term: every metacharacter and the `/`
+// delimiter escaped, a space and a double quote written as hexadecimal escapes
+// so the search box neither splits nor quotes the term; anything that is not
+// printable text cannot be typed into a search box and refuses.
 export const FOCUS_QUERY_PRIMITIVES = Object.freeze({
   escape(value) {
-    return value.replace(/[\\"]/g, (character) => `\\${character}`)
+    return value.replace(/[\\^$.*+?()[\]{}|/]/g, (character) => `\\${character}`).replace(/ /g, '\\x20').replace(/"/g, '\\x22')
   },
   term(path) {
-    return `path:"${path}"`
+    return `path:/^${path}$/`
   },
   join(terms) {
     return terms.join(' OR ')

package/src/projection/obsidian/selection-ui/selection-state.mjs

@@ -6,7 +6,7 @@ import { refuse } from '../../../runtime/obsidian/errors.mjs'
 import { assertOutsideRepositories } from '../../../runtime/obsidian/machine-settings.mjs'
 import { SCOPE_MODES, assertObsidianContract } from '../contracts.mjs'
 import { SETTINGS_ROOT } from '../materialize/settings.mjs'
-import { FOCUS_BOOKMARK_TYPE, FOCUS_QUERY_VERSION } from './focus.mjs'
+import { FOCUS_BOOKMARK_TYPE, FOCUS_QUERY_VERSIONS_READ } from './focus.mjs'
 import { SELECTION_SCHEMA } from './selection.mjs'
 
 // Where a selector is kept: Atelier's own private state of the workspace,
@@ -38,7 +38,7 @@ export function validateSelectionState(document, workspaceId) {
   assertObsidianContract('scope', { schema: 'atelier-obsidian-scope/v1', scopeId: document.scopeId, mode: document.mode, selector: document.selector, ...(document.expansion === null ? {} : { expansion: document.expansion }) })
   if (document.focus !== null) {
     closedObject(document.focus, { required: ['version', 'query', 'queryDigest', 'paths', 'bookmark'] }, code, 'the persisted focus')
-    if (document.focus.version !== FOCUS_QUERY_VERSION || typeof document.focus.query !== 'string' || document.focus.query === '' || !DIGEST.test(String(document.focus.queryDigest))) refuse(code, 'the persisted focus is malformed')
+    if (!FOCUS_QUERY_VERSIONS_READ.includes(document.focus.version) || typeof document.focus.query !== 'string' || document.focus.query === '' || !DIGEST.test(String(document.focus.queryDigest))) refuse(code, 'the persisted focus is malformed')
     if (!Array.isArray(document.focus.paths) || document.focus.paths.length === 0 || document.focus.paths.some((item) => typeof item !== 'string')) refuse(code, 'the persisted focus names no path')
     closedObject(document.focus.bookmark, { required: ['type', 'title', 'options'] }, code, 'the persisted bookmark payload')
     if (document.focus.bookmark.type !== FOCUS_BOOKMARK_TYPE) refuse(code, 'the persisted bookmark payload is not a graph bookmark')

package/src/projection/obsidian/selection-ui/selection.mjs

@@ -1,6 +1,6 @@
 import { refuse } from '../../../runtime/obsidian/errors.mjs'
 import { EXPANSION_DIRECTIONS, EXPANSION_ORDERS, MAX_EXPANSION_DEPTH, ObsidianContractRefusal, SCOPE_MODES, assertObsidianContract, selectScope } from '../contracts.mjs'
-import { allocateWorkspacePaths } from '../materialize/path-registry.mjs'
+import { allocateViewPaths, viewsOfRegistry } from '../materialize/path-registry.mjs'
 import { buildFocusQuery, focusBookmarkPayload } from './focus.mjs'
 
 // Selection: a requested scope (full, scoped or focus, with an optional
@@ -78,9 +78,14 @@ export function resolveSelection({ canonicalSnapshot, profile, scope, allowEmpty
 
   const workspaceId = typeof profile?.workspaceId === 'string' ? profile.workspaceId : 'ws-unnamed'
   const nodeById = new Map(canonicalSnapshot.nodes.map((node) => [node.id, node]))
-  const vaultNodes = result.vaultNodes.map((id) => nodeById.get(id))
+  // Paths are allocated among the view's own notes, as a prepared view allocates them, seeded from the view's last
+  // allocation in the registry: a name that collides takes a qualifier, so which name a note gets depends on the notes
+  // of the view.
   let pathOf
-  try { ({ pathOf } = allocateWorkspacePaths({ registry: pathRegistry, workspaceId, nodes: vaultNodes })) } catch (error) { contractRefusalToTyped(error) }
+  try {
+    const section = viewsOfRegistry(pathRegistry, workspaceId)[document.scopeId] ?? null
+    ;({ pathOf } = allocateViewPaths({ published: section, nodes: result.vaultNodes.map((id) => nodeById.get(id)) }))
+  } catch (error) { contractRefusalToTyped(error) }
   const notePaths = Object.fromEntries(result.nodes.map((id) => [id, pathOf(nodeById.get(id).repo, id)]))
 
   let focus = null

package/src/readiness/readiness.mjs

@@ -123,6 +123,13 @@ function buildPackageReadiness({
   }
 }
 
+// Paths in the written artifact are relative to the project config directory
+// in POSIX form, so `readiness --check` does not depend on where the project
+// is checked out and the artifact names no machine-specific directory.
+function configRelative(project, file) {
+  return path.relative(project.configDir, file).split(path.sep).join('/') || '.'
+}
+
 function buildProjectReadiness({ project, graph = null } = {}) {
   const loadedGraph = graph || (fs.existsSync(project.graphPath) ? readJson(project.graphPath) : null)
   const projectionEntry = path.join(project.outputRoot, 'index.html')
@@ -142,14 +149,14 @@ function buildProjectReadiness({ project, graph = null } = {}) {
     blockers,
     warnings,
     graph: {
-      path: project.graphPath,
+      path: configRelative(project, project.graphPath),
       nodes: loadedGraph?.counts?.nodes ?? loadedGraph?.nodes?.length ?? 0,
       edges: loadedGraph?.counts?.edges ?? loadedGraph?.edges?.length ?? 0,
       diagnostics: loadedGraph?.counts?.diagnostics ?? loadedGraph?.diagnostics?.length ?? 0,
     },
     projection: {
-      outputRoot: project.outputRoot,
-      entry: projectionEntry,
+      outputRoot: configRelative(project, project.outputRoot),
+      entry: configRelative(project, projectionEntry),
     },
     support: {
       telemetry: 'none',

package/src/reflection/index.mjs

@@ -0,0 +1,56 @@
+import fs from 'node:fs'
+import Ajv from 'ajv/dist/2020.js'
+import addFormats from 'ajv-formats'
+import { boundedLearningValue, learningDigest as digest } from '../learning/contracts.mjs'
+const schema = JSON.parse(fs.readFileSync(new URL('../../contracts/atelier-interaction.v1.schema.json', import.meta.url)))
+const ajv = new Ajv({ strict: true, allErrors: true }); addFormats(ajv)
+const validators = new Map()
+export function validateInteraction(value, shape) {
+  try { boundedLearningValue(value) } catch (error) { return [error.message] }
+  if (!['observation', 'assessment', 'act', 'policy'].includes(shape)) return ['unsupported interaction shape']
+  if (!validators.has(shape)) validators.set(shape, ajv.compile({ $schema: schema.$schema, $defs: schema.$defs, $ref: `#/$defs/${shape}` }))
+  const validate = validators.get(shape)
+  return validate(value) ? [] : validate.errors.map(e => `${e.instancePath || '/'}: ${e.message}`)
+}
+export function assertInteraction(value, shape) {
+  const errors = validateInteraction(value, shape)
+  if (errors.length) throw new Error(`invalid ${shape}: ${errors.join('; ')}`)
+  return value
+}
+export function reflectionReference(record) {
+  const kind = record?.schema === 'atelier-reflection-observation@v1' ? 'observation' : 'assessment'
+  assertInteraction(record, kind)
+  return { kind, id: record.id, digest: digest(record) }
+}
+export function qualifyReflection({ assessment, observations, scope, purpose }) {
+  assertInteraction(assessment, 'assessment'); boundedLearningValue(observations)
+  if (!Array.isArray(observations) || observations.length > 128) throw new Error('bounded observations required')
+  for (const o of observations) assertInteraction(o, 'observation')
+  if (new Set(observations.map(o => o.id)).size !== observations.length) throw new Error('ambiguous observation identity')
+  const reasons = []
+  if (assessment.scope !== scope || assessment.purpose !== purpose || assessment.status !== 'active') reasons.push('assessment-outside-active-purpose')
+  if (!assessment.evidence.length) reasons.push('assessment-without-evidence')
+  if (new Set(assessment.evidence.map(e => `${e.kind}:${e.id}`)).size !== assessment.evidence.length) reasons.push('duplicate-evidence')
+  const admitted = []
+  for (const pin of assessment.evidence) {
+    const o = observations.find(o => o.id === pin.id)
+    if (pin.kind !== 'observation' || !o || digest(o) !== pin.digest || o.status !== 'active' || o.scope !== scope || o.purpose !== purpose) reasons.push(`evidence-stale-or-outside-purpose:${pin.id}`)
+    else admitted.push(o)
+  }
+  if (assessment.claimKind === 'independent-capacity' && (assessment.subject.kind !== 'person' || admitted.some(o => o.assistance !== 'independent' || o.subject.kind !== 'person' || o.subject.id !== assessment.subject.id))) reasons.push('independent-capacity-not-supported-by-admitted-evidence')
+  if (assessment.claimKind === 'system-friction' && assessment.subject.kind === 'person') reasons.push('system-friction-cannot-be-a-personal-capacity-claim')
+  return { reference: reflectionReference(assessment), current: reasons.length === 0, reasons,
+    uncertainty: assessment.uncertainty, limits: assessment.limits, semanticTruthVerified: false, observationAuthorityTransferred: false }
+}
+// The caller supplies an attributed judgment. This function qualifies its exact
+// evidence, never invents a developmental score or silently persists a profile.
+export function prepareReflectiveAct({ assessment, observations, act }) {
+  assertInteraction(act, 'act')
+  const result = qualifyReflection({ assessment, observations, scope: act.scope, purpose: act.purpose })
+  if (!result.current) throw new Error(`reflection unavailable: ${result.reasons.join('; ')}`)
+  if (act.origin !== 'witness' || !['reflective', 'coaching'].includes(act.mode)) throw new Error('reflective contribution requires Witness origin and declared mode')
+  const required = [reflectionReference(assessment), ...assessment.evidence]
+  for (const pin of required) if (!act.dependencies.some(p => digest(p) === digest(pin))) throw new Error('reflective act must pin its assessment and evidence')
+  if (act.mode === 'coaching' && !act.dependencies.some(p => p.kind === 'intention')) throw new Error('coaching requires a current chosen intention')
+  return { act: structuredClone(act), assessment: result, deliverable: false, executionAuthorized: false }
+}

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

@@ -13,6 +13,17 @@ import { refuse } from './errors.mjs'
 // is true when the command-line tool answered that no vault is open. The
 // production probe is a separate module that only the real command-line
 // entries load; every test passes its own.
+//
+// A version can also come from Atelier's plugin: a plugin that holds a live
+// lease runs inside the app and reports `apiVersion`, the version of exactly
+// that app. It stands in only where the command-line tool gives no version:
+// the tool reaches the app a publication coordinates with, which may be
+// another app holding the same vault, so its own answer decides wherever it
+// gives one. Such an observation carries `versionSource: 'plugin'` and
+// qualifies with reason `plugin-reported`; whether the app is installed where
+// Atelier looks, with its command-line tool, is still the probe's answer, and
+// so is whether it runs: a lease outlives a crashed app by up to its lease
+// time, so while the process table shows no app, a report stands for none.
 
 // 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
@@ -64,6 +75,13 @@ export function meetsMinimumAppVersion(version, floor = MINIMUM_APP_VERSION) {
 // command, `version` too, with this line (observed on 1.13.7, on either output
 // stream and with either exit status). It is not a version.
 const NO_VAULT_OPEN = /^vault not found\.?$/i
+// While a vault window is still loading, right after the app started or opened
+// a vault, the tool answers a command with this line instead (observed on
+// 1.13.7). The app is not up yet: this is not a version either.
+const COMMAND_NOT_READY = /^error: command "[^"]*" not found\b/i
+// With its command line turned off (the default of a new installation: Settings > General > Advanced), the app
+// answers every command but a URL with this line (1.13.7). It runs and is reachable only by URL: not a version.
+const CLI_TURNED_OFF = /^command line interface is not enabled\b/i
 
 // Pure. What one `version` call of the command-line tool answered:
 // { version, noVaultOpen }. `exited` is false for a call that failed or exited
@@ -71,10 +89,47 @@ const NO_VAULT_OPEN = /^vault not found\.?$/i
 export function readVersionAnswer({ stdout = '', stderr = '', exited = true } = {}) {
   const lines = [stdout, stderr].flatMap((text) => (typeof text === 'string' ? text.split('\n') : [])).map((line) => line.trim())
   if (lines.some((line) => NO_VAULT_OPEN.test(line))) return { version: null, noVaultOpen: true }
+  if (lines.some((line) => CLI_TURNED_OFF.test(line))) return { version: null, noVaultOpen: false, cliOff: true }
+  if (lines.some((line) => COMMAND_NOT_READY.test(line))) return { version: null, noVaultOpen: false }
   const text = typeof stdout === 'string' ? stdout.trim() : ''
   return { version: exited && text !== '' ? text : null, noVaultOpen: false }
 }
 
+// Pure. Whether a reply of the command-line tool came from the app itself: a
+// version, or one of the lines the app answers with (no vault open, a command
+// not ready yet, the command line turned off). The tool's own message while it
+// cannot reach the app ("The CLI is unable to find Obsidian …") is not one, and
+// nor is silence: the app is not up.
+export function appAnswered({ stdout = '', stderr = '', exited = true } = {}) {
+  const lines = [stdout, stderr].flatMap((text) => (typeof text === 'string' ? text.split('\n') : [])).map((line) => line.trim())
+  if (lines.some((line) => NO_VAULT_OPEN.test(line) || CLI_TURNED_OFF.test(line) || COMMAND_NOT_READY.test(line))) return true
+  const text = typeof stdout === 'string' ? stdout.trim() : ''
+  return exited && parseAppVersion(text) !== null
+}
+
+// Pure. What one `eval` call of the command-line tool answered:
+// { answered: true, value } with the value the script returned, parsed as
+// JSON, or { answered: false, reason }. The tool prints a returned string as
+// it is after `=> `; a string that is itself JSON text is parsed once more.
+// `reason` is `no-vault-open` for the answer the app gives with no vault open,
+// `cli-failed` for a call that failed, and `no-value` otherwise.
+export function readEvalAnswer({ stdout = '', stderr = '', failed = false } = {}) {
+  const lines = [stdout, stderr].flatMap((text) => (typeof text === 'string' ? text.split('\n') : [])).map((line) => line.trim())
+  if (lines.some((line) => NO_VAULT_OPEN.test(line))) return { answered: false, reason: 'no-vault-open' }
+  if (lines.some((line) => CLI_TURNED_OFF.test(line))) return { answered: false, reason: 'cli-turned-off' }
+  if (failed) return { answered: false, reason: 'cli-failed' }
+  const text = typeof stdout === 'string' ? stdout : ''
+  const start = text.indexOf('=> ')
+  if (start < 0) return { answered: false, reason: 'no-value' }
+  try {
+    let value = JSON.parse(text.slice(start + 3))
+    if (typeof value === 'string') { try { value = JSON.parse(value) } catch { /* a plain string */ } }
+    return { answered: true, value }
+  } catch {
+    return { answered: false, reason: 'no-value' }
+  }
+}
+
 // 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. An app whose
@@ -83,7 +138,18 @@ export function readVersionAnswer({ stdout = '', stderr = '', exited = true } =
 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.versionSource === 'plugin') {
+    // The plugin runs inside the app it reports: that app runs and has a vault open.
+    const reported = { ...base, running: true, versionSource: 'plugin' }
+    if (seen.installed !== true) return { ...reported, outcome: 'app-missing', reason: 'no-app-found' }
+    if (seen.cli !== true) return { ...reported, outcome: 'app-cli-unavailable', reason: 'cli-capability-absent' }
+    if (reported.version === null) return { ...reported, outcome: 'app-version-unsupported', reason: 'version-unknown' }
+    if (parseAppVersion(reported.version) === null) return { ...reported, outcome: 'app-version-unsupported', reason: 'version-unreadable' }
+    if (!meetsMinimumAppVersion(reported.version, floor)) return { ...reported, outcome: 'app-version-unsupported', reason: 'below-minimum-version' }
+    return { ...reported, outcome: 'qualified', reason: 'plugin-reported', versionChecked: true }
+  }
   if (seen.installed !== true) return { ...base, outcome: 'app-missing', reason: 'no-app-found' }
+  if (seen.cliOff === true) return { ...base, running: true, outcome: 'app-cli-unavailable', reason: 'cli-turned-off' }
   if (seen.cli !== true) return { ...base, outcome: 'app-cli-unavailable', reason: 'cli-capability-absent' }
   if (seen.noVaultOpen === true) return { ...base, outcome: 'app-version-unsupported', reason: 'no-vault-open' }
   if (base.version === null) {
@@ -108,8 +174,23 @@ export async function inspectApp(appProbe) {
 // qualification with its input: an app that was not running qualified without
 // a version, and an adapter built on that answer must not coordinate with an
 // app started since (see createEditorAdapter).
+//
+// The app is asked only when an adapter is wanted, that is when a view is
+// about to be published. An appProbe with `inspect()` is asked without
+// blocking, and the factory and `qualification()` then answer promises; one
+// with only `inspectSync()` is asked synchronously.
+//
+// When the service passes `pluginReport` (one launch of the plugin holds a
+// live lease on the view), the probe is asked as without one, through the same
+// remembered answer, and that answer decides wherever the tool gave a version,
+// found no app or no tool, or the process table showed no app running. Only
+// where the tool gave no version while an app may run does the plugin's
+// version stand in; such an answer is never reused for another view or a later
+// call. The adapter still coordinates through its own channel, which must
+// answer for the vault before anything is published.
 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()')
+  const waits = typeof appProbe?.inspect === 'function'
+  if (!waits && typeof appProbe?.inspectSync !== 'function') throw new TypeError('the qualified adapter factory needs an appProbe with inspect() or inspectSync()')
   if (typeof createAdapter !== 'function') throw new TypeError('the qualified adapter factory needs createAdapter')
   let last = null
   // An answer that lets an adapter through without a checked version (no app
@@ -117,22 +198,33 @@ export function createQualifiedAdapterFactory({ appProbe, createAdapter, floor =
   // asked for its version by the next call, not refused on the old answer. An
   // answer that checked a version, or that refuses, is reused for `maxAgeMs`.
   const reusable = (result) => result.versionChecked === true || (result.outcome !== 'qualified' && result.outcome !== 'app-missing')
-  const qualification = () => {
-    if (last === null || !reusable(last.result) || 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 current = () => last !== null && reusable(last.result) && now() - last.at <= maxAgeMs
+  const learn = (observation) => { last = { at: now(), result: qualifyApp(observation, { requireVersion: false, floor }) }; return last.result }
+  const qualification = waits
+    ? async () => { if (current()) return last.result; let observation; try { observation = await appProbe.inspect() } catch { observation = null } return learn(observation) }
+    : () => { if (current()) return last.result; let observation; try { observation = appProbe.inspectSync() } catch { observation = null } return learn(observation) }
+  const withPlugin = (probed, report) => {
+    if (report === null) return probed
+    // No app in the process table: a live lease is the echo of an app that is gone (it lapses within the lease time) or
+    // of a process holding the key, and vouches for no version. The probe's own answer stands, so an adapter built on it
+    // never coordinates with an app started since, whose version nobody checked.
+    if (probed.version !== null || probed.running === false || probed.outcome === 'app-missing' || probed.outcome === 'app-cli-unavailable') return probed
+    return qualifyApp({ installed: true, cli: true, version: typeof report?.appVersion === 'string' ? report.appVersion : null, versionSource: 'plugin' }, { requireVersion: true, floor })
   }
-  const factory = (input) => {
-    const result = qualification()
+  let shown = null
+  const build = (input, probed) => {
+    const result = withPlugin(probed, input?.pluginReport ?? null)
+    shown = result
     // 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, qualification: result })
   }
+  const factory = waits ? async (input) => build(input, await qualification()) : (input) => build(input, qualification())
   factory.qualification = qualification
-  // What was last learned, without asking again: for a status answer.
-  factory.lastQualification = () => last?.result ?? null
+  // What was last learned, from the probe or from a plugin, without asking again: for a status answer.
+  factory.lastQualification = () => shown ?? last?.result ?? null
+  // Drops what was learned, so the next adapter asks the app again: a tick somebody asked for does not reuse an
+  // answer from before the app changed.
+  factory.forget = () => { last = null; shown = null }
   return factory
 }