yarramate 0.19.0 → 0.21.0

package/README.md

@@ -252,6 +252,13 @@ const result = compileWorkspace([
 lineage for operations that explicitly require kind ancestry. Graph v2
 remains the stable, graph-only interchange result.
 
+`compileWorkspaceIncremental(sources, previous)` is the entry point for a
+consumer that recompiles a whole workspace on every write. It returns the
+same result plus an opaque `cache` to hand back on the next call, and
+re-parses only the sources whose text changed; `incremental: false` reports
+that it fell back to a full compile. Reuse is decided by source-text
+equality, so a stale cache costs work but never changes output.
+
 Normative schemas are available through package exports such as
 `yarramate/schema/document`, `yarramate/schema/workspace`,
 `yarramate/schema/graph-v2`, `yarramate/schema/projection`,

package/dist/adapters/likec4-export.d.ts

@@ -4,7 +4,7 @@ import type { ProjectionResult } from '../projection.js';
 import type { LikeC4KindMapping } from './likec4-kind-mapping.js';
 export interface LikeC4ExportDiagnostic {
     readonly severity: 'error';
-    readonly code: 'YMLC101' | 'YMLC102' | 'YMLC103' | 'YMLC104' | 'YMLC105' | 'YMLC106' | 'YMLC107' | 'YMLC108' | 'YMLC109' | 'YMLC111';
+    readonly code: 'YMLC101' | 'YMLC102' | 'YMLC103' | 'YMLC104' | 'YMLC105' | 'YMLC106' | 'YMLC107' | 'YMLC108' | 'YMLC109' | 'YMLC111' | 'YMLC112';
     readonly message: string;
     readonly subject?: string;
     readonly path: string;

package/dist/adapters/likec4-export.js

@@ -155,6 +155,38 @@ export function exportLikeC4(projection, mapping, kindMapping, options = {}) {
                 : [`    description ${quote(description)}`]), ...metadata, '  }');
         }
     }
+    // `likec4 validate` accepts an empty model as valid, so it can never notice
+    // that selected concepts stopped reaching the emitted text. The shortfall is
+    // only visible here, and it is measured on the assembled lines rather than on
+    // loop iterations so that a dropped definition is what fails, not a skipped
+    // turn of the loop.
+    const rendered = new Set(lines.flatMap((line) => {
+        if (!line.startsWith('  ') || line.startsWith('   '))
+            return [];
+        const [head, ...rest] = line.slice(2).split(' = ');
+        return rest.length > 0 ? [head] : [];
+    }));
+    const unrendered = concepts.filter(({ id }) => !rendered.has(externalByNative.get(id)));
+    const missing = unrendered[0];
+    if (missing !== undefined) {
+        const source = sourceForConcept(projection.claims, missing.id) ??
+            adapterMappingLocation(mapping, 'adapter');
+        return {
+            ok: false,
+            diagnostics: [
+                {
+                    severity: 'error',
+                    code: 'YMLC112',
+                    message: `Rendering coverage: ${concepts.length - unrendered.length} of ${concepts.length} projected concepts reached the LikeC4 model`,
+                    subject: missing.id,
+                    path: source.path,
+                    pointer: source.pointer,
+                    line: source.line,
+                    column: source.column,
+                },
+            ],
+        };
+    }
     const relationships = projection.subjects
         .filter(({ type }) => type === 'relationship')
         .sort((left, right) => left.id.localeCompare(right.id));

package/dist/adapters/visual/protocol-contract.d.ts

@@ -11,7 +11,7 @@
 import type { CanvasGraph } from "../../graph-projection.js";
 import type { YarramateApplyResult, YarramateOperation } from "../../operations.js";
 import type { ProjectionDefinition, ProjectionQuery } from "../../projection.js";
-export declare const VISUAL_PROTOCOL_VERSION: "yarramate/visual-protocol/v2";
+export declare const VISUAL_PROTOCOL_VERSION: "yarramate/visual-protocol/v3";
 export declare const VISUAL_LIMITS: {
     readonly messageBytes: number;
     readonly modelBytes: number;
@@ -124,6 +124,18 @@ export interface VisualLayoutPositions {
 }
 export interface VisualChangesetCommitPayload {
     readonly operations: readonly YarramateOperation[];
+    /**
+     * What the browser believed each targeted document held when the rows were
+     * staged — sha256 keyed by manifest-relative path, pinned at staging time and
+     * never refreshed while rows remain staged. The runtime refuses the batch when
+     * a pin no longer matches the file, so a same-field overwrite of a write the
+     * reviewer never saw cannot land silently (ADR 0093).
+     *
+     * Required, not optional: a browser that omits it is exactly the browser that
+     * cannot detect the conflict, which is why this field is what makes the
+     * protocol `v3`.
+     */
+    readonly sourceDigests: Readonly<Record<string, string>>;
 }
 export interface VisualLayoutSavePayload {
     readonly projectionId: string;

package/dist/adapters/visual/protocol-contract.js

@@ -1,4 +1,4 @@
-export const VISUAL_PROTOCOL_VERSION = "yarramate/visual-protocol/v2";
+export const VISUAL_PROTOCOL_VERSION = "yarramate/visual-protocol/v3";
 export const VISUAL_LIMITS = {
     messageBytes: 64 * 1024,
     modelBytes: 5 * 1024 * 1024,

package/dist/adapters/visual/protocol.d.ts

@@ -1,5 +1,16 @@
 import { type ParseResult, type VisualBrowserInput, type VisualDiagnosticResult, type VisualEvent, type VisualHandoff, type VisualModel, type VisualResponse, type VisualSessionDescriptor, type VisualSessionRequest, type VisualSessionStarted, type VisualStatus } from './protocol-contract.js';
 export * from './protocol-contract.js';
+/**
+ * The one way this adapter mints a source digest.
+ *
+ * `visual-model/v1` requires a canonical model to record the digests it was
+ * derived from (`YMVS112`) and pins their shape to 64 lowercase hex characters,
+ * so the value lives beside the validator that enforces it: the request builder
+ * mints them for the initial model, the session server re-mints them on every
+ * recompile and checks a commit's pins against the files on disk, and all three
+ * are the same hash by construction rather than by three matching literals.
+ */
+export declare const digestOf: (source: string) => string;
 export declare const parseVisualModel: (input: unknown) => ParseResult<VisualModel>;
 export declare const parseVisualSessionRequest: (input: unknown) => ParseResult<VisualSessionRequest>;
 export declare const parseVisualSessionStarted: (input: unknown) => ParseResult<VisualSessionStarted>;

package/dist/adapters/visual/protocol.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { posix } from 'node:path';
 import Ajv2020Module from 'ajv/dist/2020.js';
 import { describeSchemaViolation, readableSchemaErrors, } from '../../source-document.js';
@@ -57,6 +58,17 @@ ajv.addSchema([
     operationsSchema,
     applyResultSchema,
 ]);
+/**
+ * The one way this adapter mints a source digest.
+ *
+ * `visual-model/v1` requires a canonical model to record the digests it was
+ * derived from (`YMVS112`) and pins their shape to 64 lowercase hex characters,
+ * so the value lives beside the validator that enforces it: the request builder
+ * mints them for the initial model, the session server re-mints them on every
+ * recompile and checks a commit's pins against the files on disk, and all three
+ * are the same hash by construction rather than by three matching literals.
+ */
+export const digestOf = (source) => createHash('sha256').update(source).digest('hex');
 // Diagnostics report the document they came from rather than a source file,
 // because visual protocol documents arrive as parsed JSON over the wire.
 const documentPaths = new WeakMap();

package/dist/adapters/visual/request.js

@@ -1,9 +1,8 @@
-import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { loadProjection } from '../../projection.js';
 import { loadWorkspaceManifest } from '../../workspace.js';
-import { parseVisualSessionRequest } from './protocol.js';
+import { digestOf, parseVisualSessionRequest } from './protocol.js';
 import { buildVisualModelGraph } from './session-store.js';
 /**
  * The one manifest a session can serve. `startVisualServer` resolves exactly
@@ -21,7 +20,6 @@ const requestDiagnostic = (code, message, path = MANIFEST_PATH) => ({
     line: 1,
     column: 1,
 });
-const digestOf = (source) => createHash('sha256').update(source).digest('hex');
 /**
  * Builds the `yarramate/visual-session-request/v1` document that `start`
  * consumes, from the workspace on disk.

package/dist/adapters/visual/session-server.js

@@ -7,7 +7,7 @@ import { fileURLToPath } from "node:url";
 import Ajv2020Module from "ajv/dist/2020.js";
 import { WebSocketServer } from "ws";
 import { parse, stringify } from "yaml";
-import { VISUAL_LIMITS, VISUAL_PROTOCOL_VERSION, parseVisualBrowserInput, parseVisualResponse, parseVisualSessionStarted, parseVisualStatus, visualBrowserInputType, } from "./protocol.js";
+import { VISUAL_LIMITS, VISUAL_PROTOCOL_VERSION, digestOf, parseVisualBrowserInput, parseVisualResponse, parseVisualSessionStarted, parseVisualStatus, visualBrowserInputType, } from "./protocol.js";
 import { appendTerminalEvent, appendVisualEvent, appendVisualResponse, createVisualSession, isActionableVisualEvent, recoverVisualSession, removeVisualSession, writeVisualSessionDescriptor, } from "./session-store.js";
 import { loadProjection, evaluateProjection, } from "../../projection.js";
 import { compileWorkspaceWithProfileContext, } from "../../compiler.js";
@@ -415,6 +415,7 @@ export const startVisualServer = async (options) => {
         documents: [],
         vocabulary: { conceptKinds: [], relationshipKinds: [] },
         layouts,
+        sourceDigests: request.initialModel.sourceDigests,
     };
     const capabilities = {
         chat: request.chatEnabled,
@@ -470,6 +471,9 @@ export const startVisualServer = async (options) => {
                 documents: resolvedWorkspace.documents,
                 vocabulary: { conceptKinds, relationshipKinds },
                 layouts: rendered.layouts,
+                // Minted from the bytes this compile just read, so what the browser
+                // renders and what it can later claim it rendered are the same read.
+                sourceDigests: Object.fromEntries(sources.map(({ path, source }) => [path, digestOf(source)])),
             };
             return true;
         }
@@ -1055,6 +1059,56 @@ export const startVisualServer = async (options) => {
                 // the agent anything, so it is answered here directly rather than
                 // through the pending queue a poll would drain. This never runs
                 // `git commit` - the user reverts a landed batch with `git revert`.
+                // A batch states what it expected each document it touches to hold, and
+                // that expectation is checked against the files before anything is
+                // written. Without it `applyOperations` below would read the workspace
+                // at commit time and do exactly as told, so a row staged against a
+                // value some other writer has since replaced overwrites that writer
+                // silently - the one path left where this adapter loses a write it
+                // reports as landed (ADR 0093).
+                //
+                // Every targeted document that exists is checked, not just every pin
+                // sent: a batch that vouches for nothing would otherwise buy back the
+                // unconditional write by omission, and a precondition nobody has to
+                // state is decoration.
+                const pins = event.payload.sourceDigests;
+                const refused = [];
+                for (const path of new Set(event.payload.operations.map((operation) => operation.document))) {
+                    let held;
+                    try {
+                        held = digestOf(readFileSync(resolve(options.cwd, path), "utf8"));
+                    }
+                    catch {
+                        // Not there to read: `apply` creates it, or something removed it.
+                        held = undefined;
+                    }
+                    const pinned = pins[path];
+                    if (held === undefined) {
+                        if (pinned !== undefined) {
+                            refused.push(serverDiagnostic("YMVS312", `Document "${path}" no longer exists; these edits were staged against it`));
+                        }
+                        continue;
+                    }
+                    if (pinned === undefined) {
+                        refused.push(serverDiagnostic("YMVS313", `Document "${path}" is edited without stating what it held when the edit was staged`));
+                        continue;
+                    }
+                    if (pinned !== held) {
+                        refused.push(serverDiagnostic("YMVS312", `Document "${path}" changed after these edits were staged`));
+                    }
+                }
+                if (refused.length > 0) {
+                    // Preserve-and-refresh: the rows stay staged in the browser exactly as
+                    // a refused apply already leaves them, and the fresh model follows so
+                    // the reviewer re-reads the value before deciding what to do with it.
+                    sendFrame(socket, {
+                        kind: "apply-result",
+                        result: { ok: false, diagnostics: refused },
+                    });
+                    if (recompileWorkspace())
+                        broadcast({ kind: "model", model: rendered });
+                    return;
+                }
                 const operationsSource = stringify({
                     format: "yarramate/operations/v1",
                     operations: event.payload.operations,

package/dist/adapters/visual/session-store.d.ts

@@ -110,7 +110,9 @@ export declare const buildVisualModelGraph: (sources: readonly WorkspaceSource[]
 /**
  * Recovers the handoff and only then deletes the session, so cleanup can never
  * be the step that loses confirmed state. Returns `undefined` when the session
- * is already gone, which makes a repeated stop idempotent.
+ * is already gone, which makes a repeated stop idempotent, and when a previous
+ * cleanup already took the journal: there is no handoff left to recover, and
+ * refusing would strand a marked directory that only this call will remove.
  */
 export declare const removeVisualSession: (paths: VisualSessionPaths, includeTranscript?: boolean) => Promise<VisualHandoff | undefined>;
 /**

package/dist/adapters/visual/session-store.js

@@ -582,10 +582,66 @@ export const buildVisualModelGraph = (sources) => {
         graph: projectGraphForCanvas(compiled.graph, compiled.profileContext),
     };
 };
+/**
+ * Whether a journal is still on disk. A cleanup that failed partway can leave
+ * a marked session without one, and that is a question about the filesystem
+ * rather than a corruption to report.
+ */
+const journalExists = async (paths) => {
+    try {
+        await lstat(paths.journal);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Deletes a session directory one entry at a time, journal and marker last.
+ *
+ * `rm(..., { recursive: true })` rejects the moment one entry fails while the
+ * sibling removals it already started are still in flight; those stragglers go
+ * on deleting after the caller has already seen the rejection. A cleanup that
+ * failed could therefore still take the journal with it, leaving the retry that
+ * follows nothing to recover from. Removing entries in a decided order, and
+ * awaiting each one, keeps the two files a retry depends on - the journal it
+ * recovers from, and the marker that authorises deleting this directory at all
+ * - on disk for as long as any other trace of the session is. The marker goes
+ * last of the two: a directory that outlives its marker is one no later pass
+ * would agree to remove.
+ */
+const removeSessionDirectory = async (paths) => {
+    let entries;
+    try {
+        entries = await readdir(paths.root, { withFileTypes: true });
+    }
+    catch (cause) {
+        // A session already gone is a completed cleanup, not a failed one.
+        if (typeof cause === 'object' &&
+            cause !== null &&
+            'code' in cause &&
+            cause.code === 'ENOENT') {
+            return;
+        }
+        throw cause;
+    }
+    const journal = basename(paths.journal);
+    const marker = basename(paths.marker);
+    for (const entry of entries) {
+        if (entry.name === journal || entry.name === marker)
+            continue;
+        await rm(join(paths.root, entry.name), { recursive: true, force: true });
+    }
+    await rm(paths.journal, { force: true });
+    await rm(paths.marker, { force: true });
+    await rm(paths.root, { recursive: true, force: true });
+};
 /**
  * Recovers the handoff and only then deletes the session, so cleanup can never
  * be the step that loses confirmed state. Returns `undefined` when the session
- * is already gone, which makes a repeated stop idempotent.
+ * is already gone, which makes a repeated stop idempotent, and when a previous
+ * cleanup already took the journal: there is no handoff left to recover, and
+ * refusing would strand a marked directory that only this call will remove.
  */
 export const removeVisualSession = async (paths, includeTranscript = false) => {
     let entry;
@@ -599,8 +655,12 @@ export const removeVisualSession = async (paths, includeTranscript = false) => {
     if (!entry.isDirectory()) {
         throw storeError('YMVS125', `Session root "${paths.root}" is not a directory`);
     }
-    const handoff = await recoverVisualSession(paths, includeTranscript);
-    await rm(paths.root, { recursive: true, force: true });
+    // The marker authorises the deletion whether or not a journal survived it.
+    await readSessionMarker(paths);
+    const handoff = (await journalExists(paths))
+        ? await recoverVisualSession(paths, includeTranscript)
+        : undefined;
+    await removeSessionDirectory(paths);
     await syncDirectory(dirname(paths.root));
     forget(paths);
     return handoff;
@@ -683,8 +743,9 @@ export const pruneStaleVisualSessions = async (baseDir, now, limit = VISUAL_SESS
     stale.sort((left, right) => left.activeAt - right.activeAt || left.root.localeCompare(right.root));
     const removed = [];
     for (const candidate of stale.slice(0, Math.max(0, limit))) {
-        await rm(candidate.root, { recursive: true, force: true });
-        forget(visualSessionPaths(candidate.root));
+        const paths = visualSessionPaths(candidate.root);
+        await removeSessionDirectory(paths);
+        forget(paths);
         removed.push(candidate.root);
     }
     if (removed.length > 0) {

package/dist/adapters/visual/wire.d.ts

@@ -25,6 +25,13 @@ export interface VisualRenderedModel {
     readonly layouts: {
         readonly [projectionId: string]: VisualLayoutPositions;
     };
+    /**
+     * The sha256 of every workspace source this graph was compiled from, keyed by
+     * manifest-relative path — the same map `visual-model/v1` already requires of
+     * a canonical model (`YMVS112`), forwarded rather than dropped so the browser
+     * can state what it rendered when it asks for a commit.
+     */
+    readonly sourceDigests: Readonly<Record<string, string>>;
 }
 /**
  * One line of the conversation, as plain text.

package/dist/apply-command.js

@@ -2,16 +2,19 @@ import { readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { isMap, isScalar, isSeq, parseDocument, stringify, } from 'yaml';
 import Ajv2020Module from 'ajv/dist/2020.js';
+import { loadAdapterMapping } from './adapter-mapping.js';
 import { diagnosticJson, humanDiagnostics, usage, } from './cli-support.js';
 import { compileWorkspace } from './compiler.js';
 import { evaluateEvidence, loadEvidence } from './evidence.js';
+import { loadProjection } from './projection.js';
 import { loadSourceDocument, locateSourcePath, } from './source-document.js';
+import { declaredStateIds, rewriteSubjectReferences, scanSubjectReferences, } from './subject-references.js';
 import { loadWorkspaceManifest } from './workspace.js';
 import operationsSchema from '../schema/yarramate-operations.schema.json' with { type: 'json'
 };
 const Ajv2020 = Ajv2020Module.default;
 // `discriminator` routes a batch entry to the single branch its `op` names, so
-// one malformed operation reports one fault instead of nine near-misses.
+// one malformed operation reports one fault instead of ten near-misses.
 const validateOperations = new Ajv2020({
     allErrors: true,
     discriminator: true,
@@ -302,6 +305,18 @@ export const applyOperations = (operations, workspace, cwd) => {
     // 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]));
+    // A rename re-points references, and references live in four kinds of file,
+    // so the write set is wider than the two above. Projections and adapter
+    // mappings are never an operation's own target — they are only ever carried
+    // along by a rename — but they are written, so they carry their manifest
+    // path for the touched-document list and their group for the walker.
+    const referenceFiles = [
+        ['document', resolvedWorkspace.documents],
+        ['projection', resolvedWorkspace.projections],
+        ['evidence', resolvedWorkspace.evidence],
+        ['adapter-mapping', resolvedWorkspace.adapterMappings],
+    ].flatMap(([group, paths]) => paths.map((path) => ({ absolute: resolve(cwd, path), path, group })));
+    const referenceFileOf = new Map(referenceFiles.map((file) => [file.absolute, file]));
     const candidates = new Map();
     const counts = {
         addedConcepts: 0,
@@ -310,14 +325,19 @@ export const applyOperations = (operations, workspace, cwd) => {
         updatedRelationships: 0,
         deletedConcepts: 0,
         deletedRelationships: 0,
+        renamedConcepts: 0,
+        renamedRelationships: 0,
         addedObservations: 0,
         updatedObservations: 0,
         deletedObservations: 0,
     };
     const deletions = [];
-    const locateOperation = (index, message) => ({
+    // Addresses this batch moved off, so the residue walk below can prove none of
+    // them survived anywhere.
+    const renames = [];
+    const locateOperation = (index, message, code = 'YM912') => ({
         severity: 'error',
-        code: 'YM912',
+        code,
         message,
         ...locateSourcePath(operationsPath, yaml, lineCounter, ['operations', index, 'document'], `/operations/${index}/document`),
     });
@@ -365,6 +385,72 @@ export const applyOperations = (operations, workspace, cwd) => {
                 counts.deletedRelationships += 1;
             }
         }
+        else if (operation.op === 'rename-concept' ||
+            operation.op === 'rename-relationship') {
+            const collection = operation.op === 'rename-concept' ? 'concepts' : 'relationships';
+            const id = operation.op === 'rename-concept'
+                ? operation.concept.id
+                : operation.relationship.id;
+            if (itemMap(source, collection, id) === undefined) {
+                return failed([
+                    locate(`Operation ${index} renames "${id}", which does not exist in ${operation.document}`),
+                ]);
+            }
+            // A rename that does not move the address would report every reference to
+            // it as residue below, which reads as a rewrite fault rather than what it
+            // is. Nothing would be written either, so `renamedConcepts: 1` over an
+            // empty document list would be a false receipt.
+            if (operation.to === id) {
+                return failed([
+                    locate(`Operation ${index} renames "${id}" to itself, so no address moves`),
+                ]);
+            }
+            // A state shares the `document#local` spelling with a subject but not the
+            // id space. A collision on either end would make one address name two
+            // things, so it is refused rather than re-pointed by guess.
+            const states = declaredStateIds(source);
+            const collision = states.includes(id)
+                ? id
+                : states.includes(operation.to)
+                    ? operation.to
+                    : undefined;
+            if (collision !== undefined) {
+                return failed([
+                    locate(`Operation ${index} renames "${id}" to "${operation.to}", but ${operation.document} declares a state "${collision}" — one address would name two things`),
+                ]);
+            }
+            const { documentId } = scanSubjectReferences(source, 'document');
+            const rename = {
+                from: `${documentId}#${id}`,
+                to: `${documentId}#${operation.to}`,
+            };
+            // Total within the workspace: the declaration and every declarative
+            // reference to it move in this one batch, so nothing is left addressing an
+            // id that stopped existing. Staged text is the input, so a second rename
+            // in the same batch reads the first one's result.
+            for (const file of referenceFiles) {
+                const before = candidates.get(file.absolute) ?? readFileSync(file.absolute, 'utf8');
+                const rewrite = rewriteSubjectReferences(before, file.group, rename);
+                if (!rewrite.ok) {
+                    return failed([
+                        locate(`Operation ${index} cannot move "${rename.from}": ${file.path} holds ${rewrite.aliases.length === 1 ? 'an alias' : 'aliases'} at ${rewrite.aliases.join(', ')}, which the rewrite cannot re-point`),
+                    ]);
+                }
+                if (rewrite.source !== before) {
+                    candidates.set(file.absolute, rewrite.source);
+                }
+            }
+            // The target document's own declaration moved in that same walk, so the
+            // staged text is the authority from here on.
+            source = candidates.get(absolute) ?? source;
+            renames.push({ index, from: rename.from });
+            if (operation.op === 'rename-concept') {
+                counts.renamedConcepts += 1;
+            }
+            else {
+                counts.renamedRelationships += 1;
+            }
+        }
         else if (operation.op === 'add-observation') {
             const address = observationAddress(operation.observation);
             const matches = byObservation(operation.observation);
@@ -604,11 +690,50 @@ export const applyOperations = (operations, workspace, cwd) => {
         if (!evaluation.ok)
             return failed(evaluation.diagnostics);
     }
+    // Totality is checked, not trusted: no file this batch touched may still name
+    // an address a rename moved off. A splice that landed text re-parsing to the
+    // old value refuses here rather than shipping a reference to an id that
+    // stopped existing. A position the enumeration omits is invisible to this
+    // walk - the schema-derived completeness test is what covers that.
+    if (renames.length > 0) {
+        const movedFrom = new Map(renames.map(({ from, index }) => [from, index]));
+        const residue = referenceFiles.flatMap((file) => {
+            const source = candidates.get(file.absolute);
+            if (source === undefined)
+                return [];
+            return scanSubjectReferences(source, file.group)
+                .hits.filter((hit) => movedFrom.has(hit.address))
+                .map((hit) => {
+                const index = movedFrom.get(hit.address);
+                return locateOperation(index, `Operation ${index} moved "${hit.address}", but ${file.path} still names it at ${hit.pointer}`, 'YM913');
+            });
+        });
+        if (residue.length > 0)
+            return failed(residue);
+    }
+    // Projections and adapter mappings are not `compileWorkspace` input, so a
+    // rewrite that produced an unreadable address is caught here rather than by
+    // the next command to read the file.
+    for (const file of referenceFiles) {
+        const source = candidates.get(file.absolute);
+        if (source === undefined)
+            continue;
+        if (file.group === 'projection') {
+            const loaded = loadProjection({ path: file.path, source });
+            if (!loaded.ok)
+                return failed(loaded.diagnostics);
+        }
+        else if (file.group === 'adapter-mapping') {
+            const loaded = loadAdapterMapping({ path: file.path, source });
+            if (!loaded.ok)
+                return failed(loaded.diagnostics);
+        }
+    }
     for (const [absolute, source] of candidates) {
         writeFileSync(absolute, source, 'utf8');
     }
     const touched = [...candidates.keys()]
-        .map((absolute) => workspaceDocuments.get(absolute) ?? workspaceEvidence.get(absolute))
+        .map((absolute) => referenceFileOf.get(absolute).path)
         .sort();
     return {
         ok: true,
@@ -658,15 +783,9 @@ export function runApplyCommand(options, cwd) {
                 stderr: '',
             };
         }
-        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;
+        // Every counter, summed by iteration rather than by hand, so a new
+        // operation kind cannot silently report zero work.
+        const applied = Object.values(result.applied).reduce((total, count) => total + count, 0);
         return {
             exitCode: 0,
             stdout: `Applied ${applied} operation${applied === 1 ? '' : 's'} to ${result.documents.join(', ')}\n`,

package/dist/compiler.d.ts

@@ -70,6 +70,44 @@ export type ContextualCompilationResult = {
     readonly ok: false;
     readonly diagnostics: readonly Diagnostic[];
 };
+/**
+ * One parsed workspace source, retained by a {@link CompilationCache}. Hold it
+ * and hand it back; never construct one. `value` is the composed YAML of
+ * `source` and nothing else, so an entry is a pure function of its text.
+ */
+export interface ParsedWorkspaceSource {
+    readonly source: string;
+    readonly kind: 'profile' | 'document';
+    readonly value: unknown;
+    readonly schemaDiagnostics: readonly Diagnostic[];
+    /**
+     * Line/column already resolved for this text, keyed by YAML path. An
+     * internal memo of the compiler, filled as positions are asked for; a
+     * consumer that mutates it corrupts the `source` of later claims.
+     */
+    readonly positions: Map<string, ResolvedPosition>;
+}
+/**
+ * Opaque parse cache returned by {@link compileWorkspaceIncremental} and
+ * accepted by its next call. Reuse is decided by exact source-text equality,
+ * not by a caller-declared change set and not by a digest, so a stale cache
+ * cannot change the compiled output - it can only fail to save work.
+ */
+export interface CompilationCache {
+    readonly sources: ReadonlyMap<string, ParsedWorkspaceSource>;
+}
+export type IncrementalCompilationResult = ({
+    readonly ok: true;
+    readonly graph: SemanticGraph;
+    readonly profileContext: ResolvedProfileContext;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly Diagnostic[];
+}) & {
+    /** False when every source had to be parsed, e.g. the first call. */
+    readonly incremental: boolean;
+    readonly cache: CompilationCache;
+};
 export declare const ATTESTATION_PREDICATE_PREFIX = "yarramate/attestation/";
 export declare const attestationClaimValue: (attestation: {
     readonly by: string;
@@ -88,5 +126,20 @@ export interface ConstraintExpectsParts {
     readonly value: string;
 }
 export declare const parseConstraintExpectsValue: (value: string) => ConstraintExpectsParts | undefined;
+interface ResolvedPosition {
+    readonly line: number;
+    readonly col: number;
+}
 export declare function compileWorkspace(sources: readonly WorkspaceSource[]): CompilationResult;
 export declare const compileWorkspaceWithProfileContext: (sources: readonly WorkspaceSource[]) => ContextualCompilationResult;
+/**
+ * Compiles the whole workspace, reusing the YAML parse of every source whose
+ * text is unchanged since `previous`. The compiled output is byte-identical to
+ * {@link compileWorkspaceWithProfileContext} for the same sources: the cache
+ * holds parse results only, and every cross-document decision is re-derived.
+ *
+ * Hold the returned `cache` and pass it to the next call. It retains one
+ * composed value per current source and drops sources that left the workspace.
+ */
+export declare const compileWorkspaceIncremental: (sources: readonly WorkspaceSource[], previous?: CompilationCache) => IncrementalCompilationResult;
+export {};