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

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

@@ -0,0 +1,141 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { isoTime } from '../../../runtime/obsidian/documents.mjs'
+import { refuse } from '../../../runtime/obsidian/errors.mjs'
+import { protectedRoots, readMachineSettings } from '../../../runtime/obsidian/machine-settings.mjs'
+import { resolveScope } from '../../../runtime/obsidian/opening.mjs'
+import { DEFAULT_ELIGIBILITY, createProductionSeams } from '../../../runtime/obsidian/pipeline.mjs'
+import { createMaintenanceStateStore } from '../../../runtime/obsidian/state-store.mjs'
+import { readConflictView } from './conflict-view.mjs'
+import { runPolicySetup } from './policy-setup.mjs'
+import { listSelectionStates, readSelectionState, writeSelectionState } from './selection-state.mjs'
+import { resolveSelection } from './selection.mjs'
+
+// The `obsidian` command operations of selection, conflict state and policy
+// setup, registered on the command's operation registry the way AOP-1 laid
+// out: a contribution `{ id, register({ operations }) }`. Nothing in the
+// command dispatcher is edited. The built-in `scope`, `policy` and `mode`
+// names are reserved, so these are `selection`, `conflicts` and
+// `apply-policy`.
+//
+// Every operation is noninteractive and read-only towards sources, vaults
+// and the app: `selection persist` writes the workspace's private selection
+// state, `apply-policy create|revoke` write the private policy files through
+// AOP-1's installer and revocation, and nothing else writes at all.
+
+export const SELECTION_CONTRIBUTION_ID = 'atelier.selection-ui'
+const EXIT = Object.freeze({ ok: 0, notSuccess: 3 })
+const MAX_REQUEST_BYTES = 64 * 1024
+
+// The canonical snapshot selectScope reads, built exactly as the engine
+// builds it: the canonical graph with fail-closed eligibility, and the
+// declared relations whose both endpoints the census knows.
+function snapshotNow({ project, seams, eligibility }) {
+  const graph = seams.buildGraph({ project, eligibility })
+  const known = new Set(graph.nodes.map((node) => node.id))
+  return { nodes: graph.nodes, edges: graph.edges.filter((edge) => known.has(edge.source) && known.has(edge.target)) }
+}
+
+// FILE is resolved from the working directory of the process, as the built-in `policy install FILE` resolves its file.
+function readRequest(value) {
+  if (value === undefined) refuse('usage', 'apply-policy create FILE')
+  const file = path.resolve(value)
+  try {
+    if (fs.statSync(file).size > MAX_REQUEST_BYTES) refuse('invalid-apply-policy', 'the request file is larger than a request can be')
+    return JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch (error) {
+    if (typeof error?.code === 'string' && error.name === 'ObsidianMaintenanceRefusal') throw error
+    return refuse('invalid-apply-policy', 'the request file cannot be read as JSON', { cause: error.code ?? 'not-json' })
+  }
+}
+
+export function createSelectionOperation({ seams = createProductionSeams(), eligibility = DEFAULT_ELIGIBILITY } = {}) {
+  return {
+    name: 'selection',
+    summary: 'resolve ID | persist ID [allow-empty] | show ID | list  The exact selected set of a declared view, its note paths and, for a focus, the graph query; persisted in Atelier state.',
+    async run({ args, readable, writable, clock }) {
+      const [sub = 'list', requested, option] = args
+      if (option !== undefined && !(sub === 'persist' && option === 'allow-empty')) refuse('usage', 'selection persist ID [allow-empty]')
+      if (sub === 'list') {
+        const { workspace, workspaceId } = readable()
+        const selections = workspace === null ? [] : listSelectionStates({ workspaceRoot: workspace.workspaceRoot, workspaceId })
+        return { exit: EXIT.ok, document: { selections }, human: selections.length === 0 ? ['no persisted selection'] : selections.map((item) => `${item.scopeId}\t${item.mode}\t${item.updatedAt}${item.focus ? `\t${item.focus.paths.length} focused note(s)` : ''}`) }
+      }
+      if (!['resolve', 'persist', 'show'].includes(sub)) refuse('usage', 'selection resolve ID | persist ID | show ID | list')
+      if (sub === 'show') {
+        const { enablement, workspace, workspaceId } = readable()
+        const scopeId = resolveScope(enablement, requested)
+        const selection = workspace === null ? null : readSelectionState({ workspaceRoot: workspace.workspaceRoot, workspaceId, scopeId })
+        return { exit: selection === null ? EXIT.notSuccess : EXIT.ok, document: { scopeId, persisted: selection !== null, selection }, human: [selection === null ? `no persisted selection for ${scopeId}` : JSON.stringify(selection, null, 2)] }
+      }
+      const { project, enablement, workspace, repositoryRoots, now } = sub === 'persist' ? writable() : { ...readable(), repositoryRoots: null, now: isoTime(clock) }
+      const scopeId = resolveScope(enablement, requested)
+      const scope = enablement.scopes.find((item) => item.scopeId === scopeId)
+      const usable = workspace !== null && workspace.workspaceRoot !== null
+      const machine = usable ? readMachineSettings(workspace) : null
+      const profile = seams.profileFor({ project, workspaceId: workspace?.workspaceId ?? 'ws-unprepared', audienceAllow: machine?.audienceAllow ?? [] })
+      const canonicalSnapshot = snapshotNow({ project, seams, eligibility })
+      const pathRegistry = usable ? createMaintenanceStateStore(workspace).readPathRegistry() : null
+      // Explicit empty is an honest answer of `resolve`; `persist` of an empty selection is refused and asks for it by name.
+      const selection = resolveSelection({ canonicalSnapshot, profile, scope, pathRegistry, allowEmpty: sub === 'resolve' || option === 'allow-empty' })
+      if (sub === 'resolve') {
+        return { exit: EXIT.ok, document: { scopeId, selection, persisted: false }, human: [`${scopeId}: ${selection.mode}, ${selection.nodes.length} note(s), ${selection.edges.length} edge(s)${selection.truncated ? ', expansion truncated' : ''}${selection.focus ? `; focus query ${selection.focus.query}` : ''}`] }
+      }
+      const written = writeSelectionState({ workspaceRoot: workspace.workspaceRoot, workspaceId: workspace.workspaceId, repositoryRoots, selection, now })
+      return { exit: EXIT.ok, document: { scopeId, selection, persisted: true, changed: written.changed, file: path.relative(workspace.workspaceRoot, written.file).split(path.sep).join('/') }, human: [`${scopeId}: persisted${written.changed ? '' : ' (unchanged)'}; ${selection.nodes.length} note(s)${selection.focus ? `; focus query ${selection.focus.query}` : ''}`, 'No file under .obsidian/ was written; apply a focus in the app.'] }
+    },
+  }
+}
+
+export function createConflictsOperation() {
+  return {
+    name: 'conflicts',
+    summary: '[ID]  The shared conflict state of edited objects, read from the arbitration record: what is conflicted, pending or unreadable, and what a person does next. Read-only.',
+    async run({ args, readable, clock }) {
+      const [requested] = args
+      const { project, enablement, workspace, workspaceId } = readable()
+      const scopeId = requested === undefined ? undefined : resolveScope(enablement, requested)
+      if (workspace === null) return { exit: EXIT.ok, document: { scopeId: scopeId ?? null, objects: [], summary: { total: 0 }, needsPerson: false, workspace: 'not-prepared' }, human: ['no private state yet: no edit was ever recorded'] }
+      const view = readConflictView({ workspaceRoot: workspace.workspaceRoot, workspaceId, repositoryRoots: protectedRoots(project), clock, scopeId })
+      return {
+        exit: EXIT.ok, document: view,
+        human: view.objects.length === 0 ? ['no recorded object'] : view.objects.map((object) => `${object.repoId}\t${object.nodeId}\t${object.state}${object.needsPerson ? '\tneeds a person' : ''}\t${object.next}`),
+      }
+    },
+  }
+}
+
+export function createApplyPolicyOperation() {
+  return {
+    name: 'apply-policy',
+    summary: 'create FILE | show | revoke  Build, digest and install a manual or automatic apply policy from a JSON request; show it; revoke it durably.',
+    async run({ args, readable, writable }) {
+      const [action, value] = args
+      if (action === undefined || action === 'show') {
+        const { workspace } = readable()
+        if (workspace === null) return { exit: EXIT.ok, document: { ok: true, action: 'show', installed: false, policy: null, reference: null, automaticApply: { authorized: false, reason: 'machine-settings-absent' } }, human: ['no apply policy is installed'] }
+        const result = runPolicySetup({ action: 'show', workspace })
+        return { exit: result.ok ? EXIT.ok : EXIT.notSuccess, document: result, human: [result.ok ? (result.installed ? `${result.policy.policyId} v${result.policy.version} ${result.policy.mode} ${result.policy.status}; automatic apply ${result.automaticApply.authorized ? 'authorized' : `not authorized (${result.automaticApply.reason})`}` : 'no apply policy is installed') : `[${result.refusal.code}] ${result.refusal.message}`] }
+      }
+      if (action !== 'create' && action !== 'revoke') refuse('usage', 'apply-policy create FILE | show | revoke')
+      const input = action === 'create' ? readRequest(value) : {}
+      const { workspace, repositoryRoots, now } = writable()
+      const result = runPolicySetup({ action, input, workspace, repositoryRoots, now })
+      const human = result.ok
+        ? [action === 'create' ? `installed ${result.policy.policyId} v${result.policy.version} (${result.policy.mode}, ${result.policy.status}); maintenance mode ${result.maintenanceMode}` : (result.revoked ? `revoked (${result.reason}); no queued edit is applied from now on, and the mode is manual` : 'no apply policy was installed')]
+        : [`[${result.refusal.code}] ${result.refusal.message}`]
+      return { exit: result.ok ? EXIT.ok : EXIT.notSuccess, document: result, human }
+    },
+  }
+}
+
+export function createSelectionContribution(options = {}) {
+  return {
+    id: SELECTION_CONTRIBUTION_ID,
+    register({ operations }) {
+      operations.register(createSelectionOperation(options))
+      operations.register(createConflictsOperation())
+      operations.register(createApplyPolicyOperation())
+    },
+  }
+}

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

@@ -0,0 +1,82 @@
+import { createHash } from 'node:crypto'
+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.
+//
+// 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;
+// `.obsidian/workspace.json`, `.obsidian/graph.json` and
+// `.obsidian/bookmarks.json` belong to the person and are never written by
+// 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_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
+// editing these.
+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.
+export const FOCUS_QUERY_PRIMITIVES = Object.freeze({
+  escape(value) {
+    return value.replace(/[\\"]/g, (character) => `\\${character}`)
+  },
+  term(path) {
+    return `path:"${path}"`
+  },
+  join(terms) {
+    return terms.join(' OR ')
+  },
+})
+
+function normalizePath(value, index) {
+  if (typeof value !== 'string' || value === '') refuse('focus-path-unrepresentable', 'a focus path must be a non-empty string', { index })
+  const normalized = value.normalize('NFC')
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/.test(normalized)) refuse('focus-path-unrepresentable', 'a focus path carries a control character and cannot be a search term', { index })
+  if (normalized.startsWith('/') || normalized.includes('\\') || normalized.split('/').some((part) => part === '' || part === '.' || part === '..')) {
+    refuse('focus-path-unrepresentable', 'a focus path must be a normalized vault-relative path', { index })
+  }
+  return normalized
+}
+
+// Test seam: the oracles in test/obsidian-acceptance.test.mjs substitute a
+// builder that drops escaping to prove the escaping oracle can fail.
+// Production uses buildFocusQuery.
+export function createFocusQueryBuilderForOracleTests(primitives = FOCUS_QUERY_PRIMITIVES) {
+  const { escape, term, join } = { ...FOCUS_QUERY_PRIMITIVES, ...primitives }
+  return function buildFocusQuery(paths) {
+    if (!Array.isArray(paths)) refuse('focus-selection-empty', 'a focus needs the list of selected note paths')
+    if (paths.length === 0) refuse('focus-selection-empty', 'a focus with no selected note would filter nothing; it is refused, never widened to the whole vault')
+    if (paths.length > MAX_FOCUS_PATHS) refuse('focus-too-large', `a focus names at most ${MAX_FOCUS_PATHS} notes`, { count: paths.length })
+    const normalized = paths.map(normalizePath)
+    if (new Set(normalized).size !== normalized.length) refuse('duplicate-identity', 'a focus names a note path more than once')
+    // The order is the order given (canonical-id order from the selection), so the same selection is the same query.
+    const terms = normalized.map((path) => term(escape(path)))
+    const query = join(terms)
+    return {
+      version: FOCUS_QUERY_VERSION,
+      query,
+      queryDigest: `sha256:${createHash('sha256').update(query, 'utf8').digest('hex')}`,
+      paths: normalized,
+    }
+  }
+}
+
+export const buildFocusQuery = createFocusQueryBuilderForOracleTests()
+
+// The payload of a core-plugin graph bookmark that retains this focus. The
+// app assigns the creation time when the bookmark is made there; nothing
+// nondeterministic is part of the payload. Only the graph type is supported:
+// core Bookmarks retain graph views, not local-graph views.
+export function focusBookmarkPayload({ scopeId, query }) {
+  if (typeof scopeId !== 'string' || scopeId === '') refuse('invalid-scope', 'a focus bookmark names its scope')
+  if (typeof query !== 'string' || query === '') refuse('focus-selection-empty', 'a focus bookmark carries a non-empty query')
+  return { type: FOCUS_BOOKMARK_TYPE, title: `Atelier focus ${scopeId}`, options: { search: query } }
+}

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

@@ -0,0 +1,12 @@
+// Selection, focus, apply policy setup, conflict state and acceptance receipt
+// validation for the Obsidian projection. Selection and focus are pure;
+// selection state, policy setup and the conflict view read and write the
+// workspace's private state through the runtime's own primitives; the receipt
+// validator is schema validation only and closes no gate.
+export { FOCUS_BOOKMARK_TYPE, FOCUS_QUERY_PRIMITIVES, FOCUS_QUERY_VERSION, MAX_FOCUS_PATHS, UI_OWNED_SETTINGS_FILES, buildFocusQuery, createFocusQueryBuilderForOracleTests, focusBookmarkPayload } from './focus.mjs'
+export { EMPTY_SELECTION_REASONS, SCOPE_CONTRACT_SCHEMA, SELECTION_SCHEMA, resolveSelection, scopeDocumentOf } from './selection.mjs'
+export { SELECTION_DIRECTORY, SELECTION_STATE_SCHEMA, assertWritableSelectionPath, listSelectionStates, readSelectionState, selectionStateDocument, validateSelectionState, writeSelectionState } from './selection-state.mjs'
+export { CONFLICT_DISPOSITION, DEFAULT_MAX_BATCH_SIZE, DEFAULT_RETRY_BUDGET, POLICY_SETUP_ACTIONS, POLICY_SETUP_SCHEMA, buildApplyPolicy, dispatchGate, runPolicySetup } from './policy-setup.mjs'
+export { CONFLICT_VIEW_SCHEMA, OBJECT_VIEW_STATES, conflictView, readConflictView } from './conflict-view.mjs'
+export { ACCEPTANCE_KINDS, RECEIPT_EXT_KEY, RECEIPT_GATES, RECEIPT_GATE_IDS, RECEIPT_RULES, RECEIPT_VALIDATION_LABEL, createReceiptValidatorForOracleTests, receiptRequirementsFor, validateAcceptanceReceipt } from './receipt.mjs'
+export { SELECTION_CONTRIBUTION_ID, createApplyPolicyOperation, createConflictsOperation, createSelectionContribution, createSelectionOperation } from './contribution.mjs'

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

@@ -0,0 +1,107 @@
+import { ObsidianMaintenanceRefusal, refuse } from '../../../runtime/obsidian/errors.mjs'
+import { authorizeAutomaticApply, installApplyPolicy, readInstalledApplyPolicy, readMachineSettings, revokeApplyPolicy } from '../../../runtime/obsidian/machine-settings.mjs'
+import { IMPLEMENTED_EDIT_CLASSES, ObsidianContractRefusal, assertObsidianContract } from '../contracts.mjs'
+import { APPLY_MODES, applyPolicyDigest, withApplyPolicyDigest } from '../edits/policy.mjs'
+
+// Apply policy setup, noninteractive: a structured request in, a structured
+// answer out. Three actions:
+//
+//   create   build a manual or automatic policy document from a request,
+//            digest it, validate it against the frozen contract and install
+//            it through AOP-1's installer. Only the implemented edit class
+//            can be allowed; the conflict disposition is `hold`, the only
+//            one that exists.
+//   show     the installed policy, the reference machine settings hold, and
+//            whether an automatic apply would be authorized right now.
+//   revoke   AOP-1's revocation: the stored policy is written `revoked`
+//            first, then maintenance goes back to manual. Every later
+//            authorization read denies, and the engine reads authorization
+//            again immediately before each queued dispatch, so a revocation
+//            is durable and wins over anything queued behind it.
+//
+// Nothing here changes the maintenance mode to automatic: that is the
+// person's separate `mode set automatic`, which itself checks that an active
+// automatic policy is installed.
+
+export const POLICY_SETUP_ACTIONS = Object.freeze(['create', 'show', 'revoke'])
+export const POLICY_SETUP_SCHEMA = 'atelier-obsidian-policy-setup/v1'
+export const DEFAULT_MAX_BATCH_SIZE = 10
+export const DEFAULT_RETRY_BUDGET = 0
+export const CONFLICT_DISPOSITION = 'hold'
+
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+const isTyped = (error) => error instanceof ObsidianMaintenanceRefusal || error instanceof ObsidianContractRefusal
+
+// The policy document a request describes, with the digest of its content.
+// `version` is taken from the request, else one above the installed policy of
+// the same identity, else 1.
+export function buildApplyPolicy({ workspaceId, policyId, mode, actor, selector, allowedEditClasses, maxBatchSize = DEFAULT_MAX_BATCH_SIZE, retryBudget = DEFAULT_RETRY_BUDGET, version = 1, status = 'active', ext } = {}) {
+  if (!APPLY_MODES.includes(mode)) refuse('invalid-apply-policy', 'policy mode must be manual or automatic', { mode: String(mode).slice(0, 32) })
+  if (!isPlainObject(actor) || !['user', 'agent'].includes(actor.kind) || typeof actor.id !== 'string' || !IDENTIFIER.test(actor.id)) refuse('invalid-apply-policy', 'the actor is { kind: user|agent, id }')
+  const classes = allowedEditClasses === undefined ? (mode === 'automatic' ? [...IMPLEMENTED_EDIT_CLASSES] : []) : allowedEditClasses
+  if (!Array.isArray(classes) || classes.some((item) => typeof item !== 'string')) refuse('invalid-apply-policy', 'allowedEditClasses is a list of edit classes')
+  const unimplemented = classes.filter((item) => !IMPLEMENTED_EDIT_CLASSES.includes(item))
+  if (unimplemented.length > 0) refuse('unimplemented-edit-class', 'only an edit class with an apply implementation can be allowed', { editClasses: unimplemented.map((item) => item.slice(0, 64)) })
+  const content = {
+    schema: 'atelier-obsidian-apply-policy/v1',
+    policyId, workspaceId, mode, status,
+    actor: { kind: actor.kind, id: actor.id },
+    version, allowedEditClasses: classes, selector, maxBatchSize, retryBudget,
+    conflictDisposition: CONFLICT_DISPOSITION,
+    ...(ext === undefined ? {} : { ext }),
+  }
+  const policy = withApplyPolicyDigest(content)
+  try { assertObsidianContract('apply-policy', policy) } catch (error) {
+    if (error instanceof ObsidianContractRefusal) refuse('invalid-apply-policy', 'the policy does not satisfy its contract', { errors: error.detail?.errors ?? [] })
+    throw error
+  }
+  return policy
+}
+
+const reference = (policy) => (policy === null ? null : { policyId: policy.policyId, version: policy.version, digest: policy.digest, mode: policy.mode, status: policy.status })
+const authorizationOf = (workspace) => {
+  const { authorized, reason } = authorizeAutomaticApply(workspace)
+  return { authorized, reason }
+}
+
+// The authorization the engine reads before each queued dispatch, in the
+// form a caller sees: read from disk now, never cached.
+export function dispatchGate(workspace) {
+  const authorization = authorizeAutomaticApply(workspace)
+  return { authorized: authorization.authorized, reason: authorization.reason, policyDigest: authorization.policy?.digest ?? null }
+}
+
+function showDocument(workspace) {
+  const policy = readInstalledApplyPolicy(workspace)
+  let machine = null
+  try { machine = readMachineSettings(workspace) } catch (error) { if (!isTyped(error)) throw error }
+  return { installed: policy !== null, policy, reference: machine?.applyPolicy ?? null, maintenanceMode: machine?.maintenanceMode ?? null, automaticApply: authorizationOf(workspace) }
+}
+
+// `workspace` is { workspaceRoot, workspaceId }; `repositoryRoots` the roots
+// private state may not overlap; `now` the timestamp to record.
+export function runPolicySetup({ action, input = {}, workspace, repositoryRoots, now }) {
+  const answer = (document) => ({ schema: POLICY_SETUP_SCHEMA, ok: true, action, ...document })
+  try {
+    if (!POLICY_SETUP_ACTIONS.includes(action)) refuse('usage', 'policy setup takes create, show or revoke', { action: String(action).slice(0, 32) })
+    if (!isPlainObject(workspace) || typeof workspace.workspaceRoot !== 'string' || typeof workspace.workspaceId !== 'string') refuse('usage', 'policy setup needs the workspace')
+    if (action === 'show') return answer(showDocument(workspace))
+    if (action === 'revoke') {
+      const result = revokeApplyPolicy({ ...workspace, repositoryRoots, updatedAt: now })
+      return answer({ revoked: result.revoked, reason: result.reason, policy: reference(result.policy), maintenanceMode: 'manual', automaticApply: authorizationOf(workspace) })
+    }
+    if (!isPlainObject(input)) refuse('usage', 'create takes a request object')
+    const installed = readInstalledApplyPolicy(workspace)
+    const version = input.version ?? (installed !== null && installed.policyId === input.policyId ? installed.version + 1 : 1)
+    if (installed !== null && installed.policyId === input.policyId && installed.version >= version) {
+      refuse('policy-version-not-newer', 'a policy of this identity is installed with an equal or higher version', { installed: installed.version, requested: version })
+    }
+    const policy = buildApplyPolicy({ ...input, workspaceId: workspace.workspaceId, version })
+    installApplyPolicy({ ...workspace, policy, repositoryRoots, updatedAt: now, digestOf: applyPolicyDigest })
+    return answer({ installed: true, policy, reference: reference(policy), maintenanceMode: readMachineSettings(workspace)?.maintenanceMode ?? 'manual', automaticApply: authorizationOf(workspace) })
+  } catch (error) {
+    if (!isTyped(error)) throw error
+    return { schema: POLICY_SETUP_SCHEMA, ok: false, action, refusal: { code: error.code, message: String(error.message).replace(`${error.code}: `, ''), detail: error.detail ?? {} } }
+  }
+}

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

@@ -0,0 +1,173 @@
+import { OBSIDIAN_EXT_KEY, validateObsidianContract } from '../contracts.mjs'
+
+// Acceptance receipt validation for the gates AOP-4 owns. This is schema
+// validation and required-field checking of a document. It proves that a
+// receipt is shaped as a receipt of that gate: exact candidate, pinned
+// versions, host and operator identity, hashed raw evidence in every role
+// the procedure calls for, and the separately recorded human or adopter
+// acceptance where the gate needs one.
+//
+// It proves nothing about what happened in the app, on the host or with the
+// adopter. `gateClosed` is always false. A gate is closed by its owner
+// inspecting the actual evidence and recording that in the parent matrix; a
+// document that passes here is an input to that inspection, never its result.
+
+export const RECEIPT_VALIDATION_LABEL = 'schema-validation-only'
+export const RECEIPT_EXT_KEY = OBSIDIAN_EXT_KEY
+export const ACCEPTANCE_KINDS = Object.freeze(['human', 'adopter'])
+
+// Per gate: the procedure of ACCEPTANCE.md that produces it, the evidence
+// type the receipt carries, the evidence roles that must each name a hashed
+// raw-evidence entry, and what is separately recorded.
+export const RECEIPT_GATES = Object.freeze({
+  G07: Object.freeze({ procedure: 'AP-01', evidenceType: 'real-app', roles: Object.freeze(['cli-link-inspection', 'app-observation']), acceptance: 'human', wallClock: false, dataset: false, tarball: false }),
+  G13: Object.freeze({ procedure: 'AP-02', evidenceType: 'real-app', roles: Object.freeze(['on-disk-membership', 'app-index-membership', 'graph-filter-observation']), acceptance: 'human', wallClock: false, dataset: false, tarball: false }),
+  G14: Object.freeze({ procedure: 'AP-03', evidenceType: 'host', roles: Object.freeze(['source-refresh-trace', 'dropped-event-recovery', 'sleep-wake-clock']), acceptance: null, wallClock: true, dataset: false, tarball: false }),
+  G15: Object.freeze({ procedure: 'AP-03', evidenceType: 'host', roles: Object.freeze(['ownership-health', 'terminal-closure']), acceptance: null, wallClock: true, dataset: false, tarball: false }),
+  G16: Object.freeze({ procedure: 'AP-04', evidenceType: 'real-app', roles: Object.freeze(['dataset-manifest', 'resource-samples', 'app-indexing-timings', 'warm-update-latencies']), acceptance: null, wallClock: true, dataset: true, tarball: false }),
+  G17: Object.freeze({ procedure: 'AP-05', evidenceType: 'real-app', roles: Object.freeze(['multi-vault-edit-trace', 'manual-apply-trace', 'automatic-apply-trace', 'uninstall-retention']), acceptance: 'human', wallClock: false, dataset: false, tarball: false }),
+  G18: Object.freeze({ procedure: 'AP-06', evidenceType: 'human', roles: Object.freeze(['tarball-audit', 'adopter-acceptance']), acceptance: 'adopter', wallClock: false, dataset: false, tarball: true }),
+})
+export const RECEIPT_GATE_IDS = Object.freeze(Object.keys(RECEIPT_GATES))
+
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
+const DIGEST = /^sha256:[0-9a-f]{64}$/
+const PLACEHOLDER = /^(?:unknown|n\/a|na|none|null|tbd|todo|latest|-+|\?+|0)$/i
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+const isIdentifier = (value) => typeof value === 'string' && IDENTIFIER.test(value)
+const isTime = (value) => typeof value === 'string' && !Number.isNaN(Date.parse(value))
+const pinned = (value) => typeof value === 'string' && value.trim() !== '' && !PLACEHOLDER.test(value.trim())
+
+// Every check answers a list of { code, pointer, message }. Each is a
+// separate rule so the mutation controls of the test suite can switch one
+// off and prove the negative case that depends on it then passes.
+export const RECEIPT_RULES = Object.freeze({
+  gate(receipt, { gateId }) {
+    return receipt.gate === gateId ? [] : [{ code: 'gate-mismatch', pointer: '/gate', message: `the receipt is for ${receipt.gate}, not ${gateId}` }]
+  },
+  procedure(receipt, { gate }) {
+    const expected = new RegExp(`^${gate.procedure}(?:[.:-][A-Za-z0-9._:-]+)?$`)
+    return expected.test(receipt.procedureId) ? [] : [{ code: 'procedure-mismatch', pointer: '/procedureId', message: `this gate is produced by ${gate.procedure}` }]
+  },
+  evidenceType(receipt, { gate }) {
+    return receipt.evidenceType === gate.evidenceType ? [] : [{ code: 'evidence-type-mismatch', pointer: '/evidenceType', message: `this gate needs ${gate.evidenceType} evidence; a node result cannot stand for it` }]
+  },
+  versionPins(receipt) {
+    const missing = []
+    for (const [pointer, value] of [['/environment/os/name', receipt.environment.os.name], ['/environment/os/version', receipt.environment.os.version], ['/environment/app/name', receipt.environment.app.name], ['/environment/app/version', receipt.environment.app.version], ['/environment/cli/version', receipt.environment.cli.version]]) {
+      if (!pinned(value)) missing.push({ code: 'version-not-pinned', pointer, message: 'an exact installed version is recorded, never a placeholder' })
+    }
+    return missing
+  },
+  candidateIdentity(receipt, { gate }) {
+    const missing = []
+    if (/^0{40}$/.test(receipt.candidate.commit)) missing.push({ code: 'candidate-not-pinned', pointer: '/candidate/commit', message: 'the candidate commit is a placeholder' })
+    if (!DIGEST.test(String(receipt.candidate.treeDigest))) missing.push({ code: 'candidate-not-pinned', pointer: '/candidate/treeDigest', message: 'the candidate tree digest is missing' })
+    if (gate.tarball && !DIGEST.test(String(receipt.candidate.tarballDigest ?? ''))) missing.push({ code: 'candidate-not-pinned', pointer: '/candidate/tarballDigest', message: 'this gate binds the exact tarball' })
+    return missing
+  },
+  hostIdentity(receipt, { ext }) {
+    const missing = []
+    if (!isPlainObject(ext.host) || !isIdentifier(ext.host.id)) missing.push({ code: 'host-identity-missing', pointer: `/ext/${RECEIPT_EXT_KEY}/host/id`, message: 'the host the procedure ran on is identified' })
+    if (!isPlainObject(ext.operator) || !isIdentifier(ext.operator.id)) missing.push({ code: 'operator-identity-missing', pointer: `/ext/${RECEIPT_EXT_KEY}/operator/id`, message: 'the operator who ran the procedure is identified' })
+    return missing
+  },
+  evidenceHashes(receipt, { gate, ext }) {
+    const missing = []
+    const names = new Map(receipt.evidence.map((item) => [item.name, item]))
+    receipt.evidence.forEach((item, index) => {
+      if (!DIGEST.test(String(item.digest)) || !Number.isInteger(item.byteLength) || item.byteLength < 1) missing.push({ code: 'evidence-not-hashed', pointer: `/evidence/${index}`, message: 'every raw evidence file is hashed and non-empty' })
+    })
+    const roles = isPlainObject(ext.evidenceRoles) ? ext.evidenceRoles : {}
+    for (const role of gate.roles) {
+      const name = roles[role]
+      if (typeof name !== 'string' || !names.has(name)) missing.push({ code: 'evidence-role-missing', pointer: `/ext/${RECEIPT_EXT_KEY}/evidenceRoles/${role}`, message: `the procedure records ${role} as hashed raw evidence` })
+    }
+    for (const role of Object.keys(roles)) if (!gate.roles.includes(role)) missing.push({ code: 'evidence-role-unknown', pointer: `/ext/${RECEIPT_EXT_KEY}/evidenceRoles/${role}`, message: 'this gate has no such evidence role' })
+    return missing
+  },
+  acceptance(receipt, { gate, ext }) {
+    const pointer = `/ext/${RECEIPT_EXT_KEY}/acceptance`
+    if (gate.acceptance === null) return ext.acceptance === undefined ? [] : [{ code: 'acceptance-not-expected', pointer, message: 'this gate records automation and host evidence; a separate acceptance belongs to another gate' }]
+    const acceptance = ext.acceptance
+    if (!isPlainObject(acceptance)) return [{ code: 'acceptance-missing', pointer, message: `this gate needs the separately recorded ${gate.acceptance} acceptance` }]
+    const missing = []
+    if (acceptance.kind !== gate.acceptance) missing.push({ code: 'acceptance-kind-mismatch', pointer: `${pointer}/kind`, message: `this gate needs a ${gate.acceptance} acceptance` })
+    if (!isIdentifier(acceptance.actor)) missing.push({ code: 'acceptance-missing', pointer: `${pointer}/actor`, message: 'the person who accepted is identified' })
+    if (!isTime(acceptance.recordedAt)) missing.push({ code: 'acceptance-missing', pointer: `${pointer}/recordedAt`, message: 'when the acceptance was recorded' })
+    if (typeof acceptance.evidenceName !== 'string' || !receipt.evidence.some((item) => item.name === acceptance.evidenceName)) missing.push({ code: 'acceptance-missing', pointer: `${pointer}/evidenceName`, message: 'the acceptance names its own hashed evidence entry' })
+    if (isPlainObject(ext.operator) && isIdentifier(acceptance.actor) && acceptance.actor === ext.operator.id && gate.acceptance === 'adopter') missing.push({ code: 'acceptance-not-separate', pointer: `${pointer}/actor`, message: 'the adopter acceptance is recorded by the adopter, not the operator' })
+    return missing
+  },
+  wallClock(receipt, { gate, ext }) {
+    if (!gate.wallClock) return []
+    const clock = ext.wallClock
+    const pointer = `/ext/${RECEIPT_EXT_KEY}/wallClock`
+    if (!isPlainObject(clock) || !isTime(clock.startedAt) || !isTime(clock.endedAt)) return [{ code: 'wall-clock-missing', pointer, message: 'host procedures record the wall clock before and after' }]
+    return Date.parse(clock.endedAt) >= Date.parse(clock.startedAt) ? [] : [{ code: 'wall-clock-missing', pointer, message: 'the wall clock ends after it starts' }]
+  },
+  dataset(receipt, { gate, ext }) {
+    if (!gate.dataset) return []
+    const dataset = ext.dataset
+    const pointer = `/ext/${RECEIPT_EXT_KEY}/dataset`
+    if (!isPlainObject(dataset) || !Number.isInteger(dataset.nodes) || dataset.nodes < 1 || !Number.isInteger(dataset.edges) || dataset.edges < 0 || !DIGEST.test(String(dataset.fixtureDigest))) {
+      return [{ code: 'dataset-missing', pointer, message: 'the generated dataset is described by node count, edge count and fixture digest' }]
+    }
+    return []
+  },
+})
+
+const EXT_KEYS = new Set(['host', 'operator', 'evidenceRoles', 'acceptance', 'wallClock', 'dataset'])
+
+function extensionOf(receipt) {
+  const ext = receipt.ext?.[RECEIPT_EXT_KEY]
+  if (ext === undefined) return { ext: {}, missing: [{ code: 'extension-missing', pointer: `/ext/${RECEIPT_EXT_KEY}`, message: 'host, operator, evidence roles and acceptance are recorded under the extension key' }] }
+  if (!isPlainObject(ext)) return { ext: {}, missing: [{ code: 'extension-missing', pointer: `/ext/${RECEIPT_EXT_KEY}`, message: 'the extension member is an object' }] }
+  const unknown = Object.keys(ext).filter((key) => !EXT_KEYS.has(key)).sort()
+  return { ext, missing: unknown.map((key) => ({ code: 'extension-key-unknown', pointer: `/ext/${RECEIPT_EXT_KEY}/${key}`, message: 'the receipt extension is a closed shape' })) }
+}
+
+// Test seam: the mutation controls substitute a rule table with one rule
+// switched off. Production uses validateAcceptanceReceipt.
+export function createReceiptValidatorForOracleTests(rules = RECEIPT_RULES) {
+  const table = { ...RECEIPT_RULES, ...rules }
+  return function validateAcceptanceReceipt(receipt, { gate: gateId } = {}) {
+    const constant = { label: RECEIPT_VALIDATION_LABEL, gateClosed: false, closes: 'nothing', note: 'A schema-valid receipt closes no gate. The gate owner inspects the actual app, host or adopter evidence and records the closing in the parent matrix.' }
+    const requested = gateId ?? (isPlainObject(receipt) ? receipt.gate : undefined)
+    if (!RECEIPT_GATE_IDS.includes(requested)) {
+      return { ...constant, gate: typeof requested === 'string' ? requested.slice(0, 8) : null, schemaValid: false, requirementsMet: false, valid: false, outcome: null, evidenceType: null, missing: [{ code: 'gate-not-owned', pointer: '/gate', message: `this validator knows the gates ${RECEIPT_GATE_IDS.join(', ')}` }] }
+    }
+    const gate = RECEIPT_GATES[requested]
+    const schemaErrors = validateObsidianContract('acceptance-receipt', receipt)
+    if (schemaErrors.length > 0) {
+      return { ...constant, gate: requested, schemaValid: false, requirementsMet: false, valid: false, outcome: null, evidenceType: null, missing: schemaErrors.map((error) => ({ code: error.code, pointer: null, message: error.message })) }
+    }
+    const { ext, missing: extensionShape } = extensionOf(receipt)
+    const context = { gateId: requested, gate, ext }
+    // The rules run in table order, gate identity first, so a receipt of another gate is told that before anything about its extension.
+    const missing = []
+    for (const name of Object.keys(RECEIPT_RULES)) missing.push(...table[name](receipt, context))
+    missing.push(...extensionShape)
+    const requirementsMet = missing.length === 0
+    return { ...constant, gate: requested, schemaValid: true, requirementsMet, valid: requirementsMet, outcome: receipt.outcome, evidenceType: receipt.evidenceType, missing }
+  }
+}
+
+export const validateAcceptanceReceipt = createReceiptValidatorForOracleTests()
+
+// The field table, for documentation and for the test that pins it.
+export function receiptRequirementsFor(gateId) {
+  const gate = RECEIPT_GATES[gateId]
+  if (!gate) return null
+  return {
+    gate: gateId,
+    procedure: gate.procedure,
+    evidenceType: gate.evidenceType,
+    always: ['candidate.commit', 'candidate.treeDigest', 'environment.os.{name,version}', 'environment.app.{name,version}', 'environment.cli.version', 'evidence[].{name,digest,byteLength>0}', `ext.${RECEIPT_EXT_KEY}.host.id`, `ext.${RECEIPT_EXT_KEY}.operator.id`],
+    evidenceRoles: [...gate.roles],
+    acceptance: gate.acceptance,
+    wallClock: gate.wallClock,
+    dataset: gate.dataset,
+    tarballDigest: gate.tarball,
+  }
+}