yarramate 0.18.0 → 0.19.0

package/dist/apply-command.js

@@ -4,12 +4,18 @@ import { isMap, isScalar, isSeq, parseDocument, stringify, } from 'yaml';
 import Ajv2020Module from 'ajv/dist/2020.js';
 import { diagnosticJson, humanDiagnostics, usage, } from './cli-support.js';
 import { compileWorkspace } from './compiler.js';
+import { evaluateEvidence, loadEvidence } from './evidence.js';
 import { loadSourceDocument, locateSourcePath, } from './source-document.js';
 import { loadWorkspaceManifest } from './workspace.js';
 import operationsSchema from '../schema/yarramate-operations.schema.json' with { type: 'json'
 };
 const Ajv2020 = Ajv2020Module.default;
-const validateOperations = new Ajv2020({ allErrors: true }).compile(operationsSchema);
+// `discriminator` routes a batch entry to the single branch its `op` names, so
+// one malformed operation reports one fault instead of nine near-misses.
+const validateOperations = new Ajv2020({
+    allErrors: true,
+    discriminator: true,
+}).compile(operationsSchema);
 // Scalar fields replace; list fields append; `remove` retracts (ADR 0062).
 // An answer enriches what is there and may explicitly take back what it
 // asserted — it never silently shrinks anything.
@@ -17,6 +23,11 @@ const SCALAR_CONCEPT_FIELDS = ['kind', 'name', 'description', 'status', 'owner']
 const LIST_CONCEPT_FIELDS = ['aka', 'constraints', 'references', 'presentIn', 'attestations', 'distinctFrom', 'supersedes'];
 const SCALAR_RELATIONSHIP_FIELDS = ['kind', 'from', 'to', 'name', 'description', 'status', 'mode', 'content'];
 const LIST_RELATIONSHIP_FIELDS = ['references', 'presentIn'];
+// An overlay entry's address is the pair (target, key); everything else it
+// carries is editable. `uri` and `message` sit one level down, inside the
+// entry's own `evidence:` mapping.
+const SCALAR_OBSERVATION_FIELDS = ['result', 'value'];
+const EVIDENCE_FIELDS = ['uri', 'message'];
 // ---------------------------------------------------------------------------
 // The splice layer. Every operation becomes a minimal text edit against the
 // document's current source, so bytes the batch never touched stay
@@ -69,8 +80,9 @@ const itemFieldInsertAt = (source, map) => {
         : nodeRange(lastPair.value)[1];
     return afterContentLine(source, anchor);
 };
-// Appends one item to a top-level block collection (`concepts:` or
-// `relationships:`), creating or converting the collection when needed.
+// Appends one item to a top-level block collection (`concepts:`,
+// `relationships:` or an overlay's `observations:`), creating or converting
+// the collection when needed.
 const appendCollectionItem = (source, collection, item) => {
     const document = parseDocument(source);
     const root = document.contents;
@@ -105,7 +117,17 @@ const appendCollectionItem = (source, collection, item) => {
         start -= 1;
     return splice(source, start, valueEnd, `\n${sequenceEntries([...existing, item], 2)}`);
 };
-const itemMap = (source, collection, id) => {
+const byId = (id) => (fields) => fields.id === id;
+// An overlay entry has no `id`: it is addressed by the pair (target, key) -
+// what `reconcile` already treats as unique per document (ADR 0075, and the
+// YM803 duplicate-target diagnostic). A keyless address matches the keyless
+// entry, the presence claim for that target, and never stands in for every
+// key the target carries.
+const byObservation = (target) => (fields) => fields.subject === target.subject &&
+    fields.claim === target.claim &&
+    fields.key === target.key;
+const observationAddress = (target) => `"${target.subject ?? target.claim}"${target.key === undefined ? '' : ` (${target.key})`}`;
+const itemMatching = (source, collection, matches) => {
     const document = parseDocument(source);
     const root = document.contents;
     if (!isMap(root))
@@ -114,15 +136,19 @@ const itemMap = (source, collection, id) => {
     if (pair === undefined || !isSeq(pair.value))
         return undefined;
     const sequence = pair.value;
-    const found = sequence.items.find((candidate) => isMap(candidate) &&
-        candidate.items.some((field) => isScalar(field.key) &&
-            field.key.value === 'id' &&
-            isScalar(field.value) &&
-            field.value.value === id));
+    const found = sequence.items.find((candidate) => isMap(candidate) && matches(candidate.toJSON()));
     return found === undefined
         ? undefined
         : { map: found, sequence };
 };
+const itemMap = (source, collection, id) => itemMatching(source, collection, byId(id));
+// An observation's locator is a mapping inside the entry; edits descend into
+// it so a changed URI splices that one line rather than re-rendering the
+// entry around it.
+const nestedMap = (map, key) => {
+    const pair = pairFor(map, key);
+    return pair !== undefined && isMap(pair.value) ? pair.value : undefined;
+};
 // The indent item fields sit at, read off the item's own first field.
 const fieldIndentOf = (source, map) => indentAt(source, nodeRange(map.items[0].key)[0]);
 // A flow-style item (`- { id: x, ... }`) cannot take block field lines;
@@ -218,10 +244,10 @@ const removeField = (source, map, key) => {
 // flow collection rewrites the collection value instead, and removing
 // the last item leaves an explicit empty collection: the document
 // schema requires the key.
-const removeCollectionItem = (source, collection, id) => {
-    const { map, sequence } = itemMap(source, collection, id);
+const removeCollectionItem = (source, collection, matches) => {
+    const { map, sequence } = itemMatching(source, collection, matches);
     if (sequence.flow) {
-        const remaining = sequence.toJSON().filter((item) => item.id !== id);
+        const remaining = sequence.toJSON().filter((item) => !matches(item));
         const [start, valueEnd] = nodeRange(sequence);
         return splice(source, start, valueEnd, remaining.length === 0
             ? '[]'
@@ -244,280 +270,406 @@ const removeCollectionItem = (source, collection, id) => {
     }
     return splice(source, lineStartOf(source, nodeRange(map)[0]), end, '');
 };
-// ---------------------------------------------------------------------------
-export function runApplyCommand(options, cwd) {
-    const json = options.includes('--json');
-    const rest = options.filter((option) => option !== '--json');
-    const [operationsPath, workspacePath] = rest;
-    if (rest.length !== 2 ||
-        operationsPath === undefined ||
-        workspacePath === undefined ||
-        rest.some((option) => option.startsWith('-'))) {
-        return { exitCode: 2, stdout: '', stderr: usage };
-    }
-    try {
-        const manifestSource = readFileSync(resolve(cwd, workspacePath), 'utf8');
-        if (parseDocument(manifestSource).get('format') !== 'yarramate/workspace/v1') {
-            return {
-                exitCode: 2,
-                stdout: '',
-                stderr: 'apply requires an explicit workspace manifest (yarramate/workspace/v1)\n',
-            };
+// The programmatic core, split out of the CLI wrapper below so a long-lived
+// caller (the visual session server) can apply a batch without shelling
+// out. Takes raw sources rather than a parsed array so loadSourceDocument /
+// locateSourcePath keep producing diagnostics whose pointers read
+// `/operations/<i>/<field>` — that pointer is how a caller maps a rejection
+// back onto whatever authored the operation. No shell-out, no temp files,
+// no process access, no module-level mutable state: safe to call
+// repeatedly and concurrently against different workspaces.
+export const applyOperations = (operations, workspace, cwd) => {
+    const failed = (diagnostics) => ({
+        ok: false,
+        diagnostics,
+    });
+    const loadedWorkspace = loadWorkspaceManifest(workspace, cwd);
+    if (!loadedWorkspace.ok)
+        return failed(loadedWorkspace.diagnostics);
+    const resolvedWorkspace = loadedWorkspace.workspace;
+    const loadedOperations = loadSourceDocument(operations, validateOperations, 'Operations');
+    if (!loadedOperations.ok)
+        return failed(loadedOperations.diagnostics);
+    const operationList = loadedOperations.document.value.operations;
+    const yaml = loadedOperations.document.yaml;
+    const lineCounter = loadedOperations.document.lineCounter;
+    const operationsPath = operations.path;
+    // Documents are addressed by their manifest paths; an operation aimed
+    // anywhere else is rejected before anything is touched.
+    const workspaceDocuments = new Map(resolvedWorkspace.documents.map((path) => [resolve(cwd, path), path]));
+    // Overlay entries live in the workspace's evidence documents, addressed the
+    // same way. The two sets stay apart: a concept operation aimed at an
+    // overlay — or an observation aimed at a compiler document — is rejected
+    // before anything is touched.
+    const workspaceEvidence = new Map(resolvedWorkspace.evidence.map((path) => [resolve(cwd, path), path]));
+    const candidates = new Map();
+    const counts = {
+        addedConcepts: 0,
+        addedRelationships: 0,
+        updatedConcepts: 0,
+        updatedRelationships: 0,
+        deletedConcepts: 0,
+        deletedRelationships: 0,
+        addedObservations: 0,
+        updatedObservations: 0,
+        deletedObservations: 0,
+    };
+    const deletions = [];
+    const locateOperation = (index, message) => ({
+        severity: 'error',
+        code: 'YM912',
+        message,
+        ...locateSourcePath(operationsPath, yaml, lineCounter, ['operations', index, 'document'], `/operations/${index}/document`),
+    });
+    for (const [index, operation] of operationList.entries()) {
+        const absolute = resolve(cwd, operation.document);
+        const overlay = operation.op.endsWith('-observation');
+        const manifestPath = overlay
+            ? workspaceEvidence.get(absolute)
+            : workspaceDocuments.get(absolute);
+        const locate = (message) => locateOperation(index, message);
+        if (manifestPath === undefined) {
+            return failed([
+                locate(`Operation ${index} targets "${operation.document}", which is not ${overlay ? 'an evidence document' : 'a document'} of workspace "${resolvedWorkspace.id}"`),
+            ]);
         }
-        const failed = (diagnostics) => ({
-            exitCode: 1,
-            stdout: json ? diagnosticJson(diagnostics) : humanDiagnostics(diagnostics),
-            stderr: '',
-        });
-        const loadedWorkspace = loadWorkspaceManifest({ path: workspacePath, source: manifestSource }, cwd);
-        if (!loadedWorkspace.ok)
-            return failed(loadedWorkspace.diagnostics);
-        const workspace = loadedWorkspace.workspace;
-        const operationsSource = readFileSync(resolve(cwd, operationsPath), 'utf8');
-        const loadedOperations = loadSourceDocument({ path: operationsPath, source: operationsSource }, validateOperations, 'Operations');
-        if (!loadedOperations.ok)
-            return failed(loadedOperations.diagnostics);
-        const operations = loadedOperations.document.value.operations;
-        const yaml = loadedOperations.document.yaml;
-        const lineCounter = loadedOperations.document.lineCounter;
-        // Documents are addressed by their manifest paths; an operation aimed
-        // anywhere else is rejected before anything is touched.
-        const workspaceDocuments = new Map(workspace.documents.map((path) => [resolve(cwd, path), path]));
-        const candidates = new Map();
-        const counts = {
-            addedConcepts: 0,
-            addedRelationships: 0,
-            updatedConcepts: 0,
-            updatedRelationships: 0,
-            deletedConcepts: 0,
-            deletedRelationships: 0,
-        };
-        const deletions = [];
-        const locateOperation = (index, message) => ({
-            severity: 'error',
-            code: 'YM912',
-            message,
-            ...locateSourcePath(operationsPath, yaml, lineCounter, ['operations', index, 'document'], `/operations/${index}/document`),
-        });
-        for (const [index, operation] of operations.entries()) {
-            const absolute = resolve(cwd, operation.document);
-            const manifestPath = workspaceDocuments.get(absolute);
-            const locate = (message) => locateOperation(index, message);
-            if (manifestPath === undefined) {
+        let source = candidates.get(absolute);
+        if (source === undefined) {
+            source = readFileSync(absolute, 'utf8');
+        }
+        if (operation.op === 'add-concept') {
+            source = appendCollectionItem(source, 'concepts', operation.concept);
+            counts.addedConcepts += 1;
+        }
+        else if (operation.op === 'add-relationship') {
+            source = appendCollectionItem(source, 'relationships', operation.relationship);
+            counts.addedRelationships += 1;
+        }
+        else if (operation.op === 'delete-concept' ||
+            operation.op === 'delete-relationship') {
+            const collection = operation.op === 'delete-concept' ? 'concepts' : 'relationships';
+            const id = operation.op === 'delete-concept'
+                ? operation.concept.id
+                : operation.relationship.id;
+            if (itemMap(source, collection, id) === undefined) {
                 return failed([
-                    locate(`Operation ${index} targets "${operation.document}", which is not a document of workspace "${workspace.id}"`),
+                    locate(`Operation ${index} deletes "${id}", which does not exist in ${operation.document}`),
                 ]);
             }
-            let source = candidates.get(absolute);
-            if (source === undefined) {
-                source = readFileSync(absolute, 'utf8');
+            source = removeCollectionItem(source, collection, byId(id));
+            deletions.push({ index, absolute, id });
+            if (operation.op === 'delete-concept') {
+                counts.deletedConcepts += 1;
             }
-            if (operation.op === 'add-concept') {
-                source = appendCollectionItem(source, 'concepts', operation.concept);
-                counts.addedConcepts += 1;
+            else {
+                counts.deletedRelationships += 1;
+            }
+        }
+        else if (operation.op === 'add-observation') {
+            const address = observationAddress(operation.observation);
+            const matches = byObservation(operation.observation);
+            if (itemMatching(source, 'observations', matches) !== undefined) {
+                return failed([
+                    locate(`Operation ${index} adds an observation of ${address}, which ${operation.document} already records`),
+                ]);
             }
-            else if (operation.op === 'add-relationship') {
-                source = appendCollectionItem(source, 'relationships', operation.relationship);
-                counts.addedRelationships += 1;
+            source = appendCollectionItem(source, 'observations', operation.observation);
+            counts.addedObservations += 1;
+        }
+        else if (operation.op === 'update-observation') {
+            const target = operation.observation;
+            const address = observationAddress(target);
+            const matches = byObservation(target);
+            const removals = operation.remove ?? [];
+            if (removals.includes('message') && target.evidence?.message !== undefined) {
+                return failed([
+                    locate(`Operation ${index} both sets and removes "message" on ${address}`),
+                ]);
             }
-            else if (operation.op === 'delete-concept' ||
-                operation.op === 'delete-relationship') {
-                const collection = operation.op === 'delete-concept' ? 'concepts' : 'relationships';
-                const id = operation.op === 'delete-concept'
-                    ? operation.concept.id
-                    : operation.relationship.id;
-                if (itemMap(source, collection, id) === undefined) {
+            if (itemMatching(source, 'observations', matches) === undefined) {
+                return failed([
+                    locate(`Operation ${index} updates an observation of ${address}, which does not exist in ${operation.document}`),
+                ]);
+            }
+            const fields = target;
+            for (const key of SCALAR_OBSERVATION_FIELDS) {
+                if (fields[key] === undefined)
+                    continue;
+                source = setScalarField(source, itemMatching(source, 'observations', matches).map, key, fields[key]);
+            }
+            for (const key of EVIDENCE_FIELDS) {
+                const value = target.evidence?.[key];
+                if (value === undefined)
+                    continue;
+                const locator = nestedMap(itemMatching(source, 'observations', matches).map, 'evidence');
+                if (locator === undefined) {
                     return failed([
-                        locate(`Operation ${index} deletes "${id}", which does not exist in ${operation.document}`),
+                        locate(`Operation ${index} updates the evidence of ${address}, which ${operation.document} does not record as a mapping`),
                     ]);
                 }
-                source = removeCollectionItem(source, collection, id);
-                deletions.push({ index, absolute, id });
-                if (operation.op === 'delete-concept') {
-                    counts.deletedConcepts += 1;
-                }
-                else {
-                    counts.deletedRelationships += 1;
-                }
+                source = setScalarField(source, locator, key, value);
             }
-            else {
-                const collection = operation.op === 'update-concept' ? 'concepts' : 'relationships';
-                const payload = (operation.op === 'update-concept'
-                    ? operation.concept
-                    : operation.relationship);
-                const scalars = operation.op === 'update-concept'
-                    ? SCALAR_CONCEPT_FIELDS
-                    : SCALAR_RELATIONSHIP_FIELDS;
-                const lists = operation.op === 'update-concept'
-                    ? LIST_CONCEPT_FIELDS
-                    : LIST_RELATIONSHIP_FIELDS;
-                const id = payload.id;
-                const removals = operation.remove ?? [];
-                const contradiction = removals.find((key) => payload[key] !== undefined);
-                if (contradiction !== undefined) {
+            for (const key of removals) {
+                const locator = nestedMap(itemMatching(source, 'observations', matches).map, 'evidence');
+                // Annotated: without it the assignment below feeds `source` back
+                // into its own inferred type through this call.
+                const removed = locator === undefined ? undefined : removeField(source, locator, key);
+                if (removed === undefined) {
                     return failed([
-                        locate(`Operation ${index} both sets and removes "${contradiction}" on "${id}"`),
+                        locate(`Operation ${index} removes "${key}", which is not set on ${address}`),
                     ]);
                 }
-                const located = itemMap(source, collection, id);
-                if (located === undefined) {
+                source = removed;
+            }
+            counts.updatedObservations += 1;
+        }
+        else if (operation.op === 'delete-observation') {
+            const address = observationAddress(operation.observation);
+            const matches = byObservation(operation.observation);
+            if (itemMatching(source, 'observations', matches) === undefined) {
+                return failed([
+                    locate(`Operation ${index} deletes an observation of ${address}, which does not exist in ${operation.document}`),
+                ]);
+            }
+            // An overlay entry is nobody's reference target, so unlike a concept
+            // deletion this stages no reference-integrity check.
+            source = removeCollectionItem(source, 'observations', matches);
+            counts.deletedObservations += 1;
+        }
+        else {
+            const collection = operation.op === 'update-concept' ? 'concepts' : 'relationships';
+            const payload = (operation.op === 'update-concept'
+                ? operation.concept
+                : operation.relationship);
+            const scalars = operation.op === 'update-concept'
+                ? SCALAR_CONCEPT_FIELDS
+                : SCALAR_RELATIONSHIP_FIELDS;
+            const lists = operation.op === 'update-concept'
+                ? LIST_CONCEPT_FIELDS
+                : LIST_RELATIONSHIP_FIELDS;
+            const id = payload.id;
+            const removals = operation.remove ?? [];
+            const contradiction = removals.find((key) => payload[key] !== undefined);
+            if (contradiction !== undefined) {
+                return failed([
+                    locate(`Operation ${index} both sets and removes "${contradiction}" on "${id}"`),
+                ]);
+            }
+            const located = itemMap(source, collection, id);
+            if (located === undefined) {
+                return failed([
+                    locate(`Operation ${index} updates "${id}", which does not exist in ${operation.document}`),
+                ]);
+            }
+            for (const key of scalars) {
+                if (payload[key] === undefined)
+                    continue;
+                source = setScalarField(source, itemMap(source, collection, id).map, key, payload[key]);
+            }
+            for (const key of lists) {
+                const additions = payload[key];
+                if (additions === undefined || additions.length === 0)
+                    continue;
+                source = appendListField(source, itemMap(source, collection, id).map, key, additions);
+            }
+            for (const key of removals) {
+                const removed = removeField(source, itemMap(source, collection, id).map, key);
+                if (removed === undefined) {
                     return failed([
-                        locate(`Operation ${index} updates "${id}", which does not exist in ${operation.document}`),
+                        locate(`Operation ${index} removes "${key}", which is not set on "${id}"`),
                     ]);
                 }
-                for (const key of scalars) {
-                    if (payload[key] === undefined)
-                        continue;
-                    source = setScalarField(source, itemMap(source, collection, id).map, key, payload[key]);
-                }
-                for (const key of lists) {
-                    const additions = payload[key];
-                    if (additions === undefined || additions.length === 0)
-                        continue;
-                    source = appendListField(source, itemMap(source, collection, id).map, key, additions);
-                }
-                for (const key of removals) {
-                    const removed = removeField(source, itemMap(source, collection, id).map, key);
-                    if (removed === undefined) {
-                        return failed([
-                            locate(`Operation ${index} removes "${key}", which is not set on "${id}"`),
-                        ]);
-                    }
-                    source = removed;
+                source = removed;
+            }
+            if (operation.op === 'update-concept') {
+                counts.updatedConcepts += 1;
+            }
+            else {
+                counts.updatedRelationships += 1;
+            }
+        }
+        candidates.set(absolute, source);
+    }
+    // Reference integrity for deletes (#123), evaluated against the
+    // post-batch state: stage everything first, then look, so a concept
+    // deleted together with its referring relationships in one batch
+    // succeeds while a target anything still points at rejects the
+    // whole batch. Referring sites are relationship endpoints, owner,
+    // constraint and identified references; projection selectors are
+    // deliberately unchecked — they tolerate no-match by design. The
+    // compile gate below stays the backstop.
+    if (deletions.length > 0) {
+        const staged = resolvedWorkspace.documents.map((path) => {
+            const absolute = resolve(cwd, path);
+            return {
+                absolute,
+                value: parseDocument(candidates.get(absolute) ?? readFileSync(absolute, 'utf8')).toJSON(),
+            };
+        });
+        const qualify = (documentId, reference) => reference.includes('#') ? reference : `${documentId}#${reference}`;
+        const referrers = staged.flatMap(({ value }) => {
+            const documentId = value?.id;
+            if (documentId === undefined)
+                return [];
+            const sites = [];
+            for (const concept of value?.concepts ?? []) {
+                const subject = `${documentId}#${concept.id}`;
+                if (concept.owner !== undefined) {
+                    sites.push({
+                        ref: qualify(documentId, concept.owner),
+                        subject,
+                        field: 'owner',
+                    });
                 }
-                if (operation.op === 'update-concept') {
-                    counts.updatedConcepts += 1;
+                for (const constraint of concept.constraints ?? []) {
+                    sites.push({
+                        ref: qualify(documentId, constraint.ref),
+                        subject,
+                        field: 'constraints',
+                    });
                 }
-                else {
-                    counts.updatedRelationships += 1;
+                for (const reference of concept.references ?? []) {
+                    sites.push({
+                        ref: qualify(documentId, reference.ref),
+                        subject,
+                        field: 'references',
+                    });
                 }
             }
-            candidates.set(absolute, source);
-        }
-        // Reference integrity for deletes (#123), evaluated against the
-        // post-batch state: stage everything first, then look, so a concept
-        // deleted together with its referring relationships in one batch
-        // succeeds while a target anything still points at rejects the
-        // whole batch. Referring sites are relationship endpoints, owner,
-        // constraint and identified references; projection selectors are
-        // deliberately unchecked — they tolerate no-match by design. The
-        // compile gate below stays the backstop.
-        if (deletions.length > 0) {
-            const staged = workspace.documents.map((path) => {
-                const absolute = resolve(cwd, path);
-                return {
-                    absolute,
-                    value: parseDocument(candidates.get(absolute) ?? readFileSync(absolute, 'utf8')).toJSON(),
-                };
-            });
-            const qualify = (documentId, reference) => reference.includes('#') ? reference : `${documentId}#${reference}`;
-            const referrers = staged.flatMap(({ value }) => {
-                const documentId = value?.id;
-                if (documentId === undefined)
-                    return [];
-                const sites = [];
-                for (const concept of value?.concepts ?? []) {
-                    const subject = `${documentId}#${concept.id}`;
-                    if (concept.owner !== undefined) {
+            for (const relationship of value?.relationships ?? []) {
+                const subject = `${documentId}#${relationship.id}`;
+                for (const endpoint of ['from', 'to']) {
+                    const reference = relationship[endpoint];
+                    if (reference !== undefined) {
                         sites.push({
-                            ref: qualify(documentId, concept.owner),
+                            ref: qualify(documentId, reference),
                             subject,
-                            field: 'owner',
-                        });
-                    }
-                    for (const constraint of concept.constraints ?? []) {
-                        sites.push({
-                            ref: qualify(documentId, constraint.ref),
-                            subject,
-                            field: 'constraints',
-                        });
-                    }
-                    for (const reference of concept.references ?? []) {
-                        sites.push({
-                            ref: qualify(documentId, reference.ref),
-                            subject,
-                            field: 'references',
+                            field: endpoint,
                         });
                     }
                 }
-                for (const relationship of value?.relationships ?? []) {
-                    const subject = `${documentId}#${relationship.id}`;
-                    for (const endpoint of ['from', 'to']) {
-                        const reference = relationship[endpoint];
-                        if (reference !== undefined) {
-                            sites.push({
-                                ref: qualify(documentId, reference),
-                                subject,
-                                field: endpoint,
-                            });
-                        }
-                    }
-                    for (const reference of relationship.references ?? []) {
-                        sites.push({
-                            ref: qualify(documentId, reference.ref),
-                            subject,
-                            field: 'references',
-                        });
-                    }
+                for (const reference of relationship.references ?? []) {
+                    sites.push({
+                        ref: qualify(documentId, reference.ref),
+                        subject,
+                        field: 'references',
+                    });
                 }
-                return sites;
-            });
-            const documentIds = new Map(staged.map(({ absolute, value }) => [absolute, value?.id]));
-            const violations = deletions.flatMap((deletion) => {
-                const documentId = documentIds.get(deletion.absolute);
-                if (documentId === undefined)
-                    return [];
-                const target = `${documentId}#${deletion.id}`;
-                const referring = referrers.filter((site) => site.ref === target);
-                if (referring.length === 0)
-                    return [];
-                return [
-                    locateOperation(deletion.index, `Operation ${deletion.index} deletes "${deletion.id}", which is still referenced by ${referring
-                        .map((site) => `"${site.subject}" (${site.field})`)
-                        .join(', ')}`),
-                ];
-            });
-            if (violations.length > 0)
-                return failed(violations);
+            }
+            return sites;
+        });
+        const documentIds = new Map(staged.map(({ absolute, value }) => [absolute, value?.id]));
+        const violations = deletions.flatMap((deletion) => {
+            const documentId = documentIds.get(deletion.absolute);
+            if (documentId === undefined)
+                return [];
+            const target = `${documentId}#${deletion.id}`;
+            const referring = referrers.filter((site) => site.ref === target);
+            if (referring.length === 0)
+                return [];
+            return [
+                locateOperation(deletion.index, `Operation ${deletion.index} deletes "${deletion.id}", which is still referenced by ${referring
+                    .map((site) => `"${site.subject}" (${site.field})`)
+                    .join(', ')}`),
+            ];
+        });
+        if (violations.length > 0)
+            return failed(violations);
+    }
+    // The atomic gate: the whole candidate workspace must compile before a
+    // single byte is written; any diagnostic rejects the entire batch.
+    const compilation = compileWorkspace([...resolvedWorkspace.profiles, ...resolvedWorkspace.documents].map((path) => {
+        const absolute = resolve(cwd, path);
+        return {
+            path,
+            source: candidates.get(absolute) ?? readFileSync(absolute, 'utf8'),
+        };
+    }));
+    if (!compilation.ok)
+        return failed(compilation.diagnostics);
+    // The overlay gate: an observation the batch authored must load and must
+    // evaluate against the graph the batch just proved compiles, so an entry
+    // naming a subject that does not exist is rejected here rather than
+    // discovered later by `reconcile`. Only touched overlays are evaluated —
+    // pre-existing drift elsewhere is reconcile's report to make, not this
+    // batch's failure.
+    for (const [absolute, path] of workspaceEvidence) {
+        const source = candidates.get(absolute);
+        if (source === undefined)
+            continue;
+        const loaded = loadEvidence({ path, source });
+        if (!loaded.ok)
+            return failed(loaded.diagnostics);
+        const evaluation = evaluateEvidence(compilation.graph, loaded.evidence);
+        if (!evaluation.ok)
+            return failed(evaluation.diagnostics);
+    }
+    for (const [absolute, source] of candidates) {
+        writeFileSync(absolute, source, 'utf8');
+    }
+    const touched = [...candidates.keys()]
+        .map((absolute) => workspaceDocuments.get(absolute) ?? workspaceEvidence.get(absolute))
+        .sort();
+    return {
+        ok: true,
+        result: {
+            format: 'yarramate/apply-result/v1',
+            workspace: resolvedWorkspace.id,
+            applied: counts,
+            documents: touched,
+        },
+    };
+};
+export function runApplyCommand(options, cwd) {
+    const json = options.includes('--json');
+    const rest = options.filter((option) => option !== '--json');
+    const [operationsPath, workspacePath] = rest;
+    if (rest.length !== 2 ||
+        operationsPath === undefined ||
+        workspacePath === undefined ||
+        rest.some((option) => option.startsWith('-'))) {
+        return { exitCode: 2, stdout: '', stderr: usage };
+    }
+    try {
+        const manifestSource = readFileSync(resolve(cwd, workspacePath), 'utf8');
+        if (parseDocument(manifestSource).get('format') !== 'yarramate/workspace/v1') {
+            return {
+                exitCode: 2,
+                stdout: '',
+                stderr: 'apply requires an explicit workspace manifest (yarramate/workspace/v1)\n',
+            };
         }
-        // The atomic gate: the whole candidate workspace must compile before a
-        // single byte is written; any diagnostic rejects the entire batch.
-        const compilation = compileWorkspace([...workspace.profiles, ...workspace.documents].map((path) => {
-            const absolute = resolve(cwd, path);
+        const operationsSource = readFileSync(resolve(cwd, operationsPath), 'utf8');
+        const outcome = applyOperations({ path: operationsPath, source: operationsSource }, { path: workspacePath, source: manifestSource }, cwd);
+        if (!outcome.ok) {
             return {
-                path,
-                source: candidates.get(absolute) ?? readFileSync(absolute, 'utf8'),
+                exitCode: 1,
+                stdout: json
+                    ? diagnosticJson(outcome.diagnostics)
+                    : humanDiagnostics(outcome.diagnostics),
+                stderr: '',
             };
-        }));
-        if (!compilation.ok)
-            return failed(compilation.diagnostics);
-        for (const [absolute, source] of candidates) {
-            writeFileSync(absolute, source, 'utf8');
         }
-        const touched = [...candidates.keys()]
-            .map((absolute) => workspaceDocuments.get(absolute))
-            .sort();
+        const { result } = outcome;
         if (json) {
             return {
                 exitCode: 0,
-                stdout: `${JSON.stringify({
-                    format: 'yarramate/apply-result/v1',
-                    workspace: workspace.id,
-                    applied: counts,
-                    documents: touched,
-                }, null, 2)}\n`,
+                stdout: `${JSON.stringify(result, null, 2)}\n`,
                 stderr: '',
             };
         }
-        const applied = counts.addedConcepts +
-            counts.addedRelationships +
-            counts.updatedConcepts +
-            counts.updatedRelationships +
-            counts.deletedConcepts +
-            counts.deletedRelationships;
+        const applied = result.applied.addedConcepts +
+            result.applied.addedRelationships +
+            result.applied.updatedConcepts +
+            result.applied.updatedRelationships +
+            result.applied.deletedConcepts +
+            result.applied.deletedRelationships +
+            result.applied.addedObservations +
+            result.applied.updatedObservations +
+            result.applied.deletedObservations;
         return {
             exitCode: 0,
-            stdout: `Applied ${applied} operation${applied === 1 ? '' : 's'} to ${touched.join(', ')}\n`,
+            stdout: `Applied ${applied} operation${applied === 1 ? '' : 's'} to ${result.documents.join(', ')}\n`,
             stderr: '',
         };
     }