yarramate 0.20.0 → 0.21.0

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/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/operations.d.ts

@@ -103,6 +103,22 @@ export type YarramateOperation = {
     readonly relationship: {
         readonly id: string;
     };
+} | {
+    readonly op: 'rename-concept';
+    readonly document: string;
+    readonly concept: {
+        readonly id: string;
+    };
+    /** The local id this subject should have had. Every declarative
+     * reference to the old address moves with it; prose does not. */
+    readonly to: string;
+} | {
+    readonly op: 'rename-relationship';
+    readonly document: string;
+    readonly relationship: {
+        readonly id: string;
+    };
+    readonly to: string;
 } | {
     readonly op: 'add-observation';
     readonly document: string;
@@ -131,6 +147,8 @@ export interface YarramateApplyResult {
         readonly updatedRelationships: number;
         readonly deletedConcepts: number;
         readonly deletedRelationships: number;
+        readonly renamedConcepts: number;
+        readonly renamedRelationships: number;
         readonly addedObservations: number;
         readonly updatedObservations: number;
         readonly deletedObservations: number;

package/dist/subject-references.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Every place a subject address can appear on disk, and the surgery that moves
+ * one. A rename is only honest if it is total: an address left behind is a
+ * dangling reference or, worse, a selector that silently stops matching. The
+ * enumeration below is the single statement of where those addresses live, and
+ * `test/subject-references.test.ts` derives the same set from the JSON Schemas
+ * so a new reference field cannot be added without landing here too.
+ */
+/** The four on-disk document kinds that can name a subject. */
+export type SubjectReferenceGroup = 'document' | 'projection' | 'evidence' | 'adapter-mapping';
+/**
+ * How the address is spelled at a position.
+ * - `declaration`: the subject's own local id, always bare, in its own document.
+ * - `reference`: bare local id (meaning "this document") or fully qualified.
+ * - `qualified`: always `document#local`, optionally with a `~aspect` suffix
+ *   (claim addresses are minted that way - see `compiler.ts`).
+ */
+export type SubjectReferenceForm = 'declaration' | 'reference' | 'qualified';
+export interface SubjectReferencePosition {
+    readonly group: SubjectReferenceGroup;
+    /** Key path from the document root; `*` matches every sequence index. */
+    readonly path: readonly string[];
+    readonly form: SubjectReferenceForm;
+}
+export declare const SUBJECT_REFERENCE_POSITIONS: readonly SubjectReferencePosition[];
+/**
+ * Positions that carry reference *syntax* but are not subject addresses, with
+ * the reason. Kept as data because the schema-derived completeness test asserts
+ * that the two lists together account for every reference-typed position: an
+ * omission has to be argued for here rather than forgotten.
+ */
+export declare const EXCLUDED_REFERENCE_POSITIONS: readonly {
+    readonly group: SubjectReferenceGroup;
+    readonly path: readonly string[];
+    readonly reason: string;
+}[];
+export interface SubjectReferenceHit {
+    /** JSON pointer into the document, for diagnostics. */
+    readonly pointer: string;
+    /** Qualified address with any `~aspect` suffix removed. */
+    readonly address: string;
+    readonly form: SubjectReferenceForm;
+    /** Source offsets of the scalar's own bytes, quotes included. */
+    readonly start: number;
+    readonly end: number;
+    /** The scalar exactly as written, quotes included. */
+    readonly raw: string;
+}
+export interface SubjectReferenceScan {
+    /** The document's own id, `''` when it declares none. */
+    readonly documentId: string;
+    readonly hits: readonly SubjectReferenceHit[];
+    /**
+     * Pointers at reference positions that hold an alias node. The walker cannot
+     * re-point one, so a rename refuses rather than silently leaving it behind.
+     */
+    readonly aliases: readonly string[];
+}
+/**
+ * Every subject address a file of this group holds. Pure read: the parse is
+ * thrown away, so callers stay free to splice the original bytes.
+ */
+export declare const scanSubjectReferences: (source: string, group: SubjectReferenceGroup) => SubjectReferenceScan;
+export interface SubjectRename {
+    /** Qualified address as declared today. */
+    readonly from: string;
+    /** Qualified address it should have had; the document part never moves. */
+    readonly to: string;
+}
+export type SubjectRewriteResult = {
+    readonly ok: true;
+    readonly source: string;
+    /** Pointers this rewrite moved, in document order. */
+    readonly moved: readonly string[];
+} | {
+    readonly ok: false;
+    readonly aliases: readonly string[];
+};
+/**
+ * Re-points every reference to `rename.from` in one file. Only the matched
+ * scalars' own bytes change - nothing is re-rendered, so byte identity holds
+ * everywhere else, a bare reference stays bare, a qualified one stays
+ * qualified, a `~aspect` suffix survives, and the original quoting is kept.
+ */
+export declare const rewriteSubjectReferences: (source: string, group: SubjectReferenceGroup, rename: SubjectRename) => SubjectRewriteResult;
+/**
+ * Local ids of the architecture states a document declares. States share the
+ * `document#local` spelling with subjects but not the id space, so a rename
+ * whose old or new id collides with one cannot be re-pointed unambiguously and
+ * is refused instead.
+ */
+export declare const declaredStateIds: (source: string) => readonly string[];