yarramate 0.23.0 → 1.0.0

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

@@ -2,18 +2,19 @@ import { createHash, createHmac, randomBytes as randomSource, timingSafeEqual, }
 import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { lstat, readFile } from "node:fs/promises";
 import { createServer, } from "node:http";
-import { basename, extname, join, resolve, sep } from "node:path";
+import { basename, extname, join, relative, resolve, sep } from "node:path";
 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, digestOf, parseVisualBrowserInput, parseVisualResponse, parseVisualSessionStarted, parseVisualStatus, visualBrowserInputType, } from "./protocol.js";
+import { VISUAL_LIMITS, VISUAL_PROTOCOL_VERSION, digestOf, parseVisualBrowserInput, parseVisualResponse, parseVisualSessionStarted, parseVisualStatus, toWireFileUri, visualBrowserInputType, } from "./protocol.js";
 import { appendTerminalEvent, appendVisualEvent, appendVisualResponse, createVisualSession, isActionableVisualEvent, recoverVisualSession, removeVisualSession, writeVisualSessionDescriptor, } from "./session-store.js";
-import { loadProjection, evaluateProjection, } from "../../projection.js";
+import { loadProjection, } from "../../projection.js";
+export { VISUAL_SERVER_DOCUMENT } from "./workspace-model.js";
+import { adoptLandedViews, exclusionsOf, matchedIdsOf, planViewWrites, published, renderedWorkspaceOf, serverDiagnostic, viewSummaryOf, } from "./workspace-model.js";
 import { compileWorkspaceWithProfileContext, } from "../../compiler.js";
-import { applyOperations } from "../../apply-command.js";
-import { projectGraphForCanvas } from "../../graph-projection.js";
-import { kindLabelOf } from "../../kind-label.js";
+import { planOperations, posixDirectoryOf, writeConflictDiagnostics, } from "../../apply-command.js";
+import { createFileSystemStore } from "../../source-store.js";
 import { loadWorkspaceManifest, } from "../../workspace.js";
 import visualLayoutSchema from "../../../schema/yarramate-visual-layout.schema.json" with { type: "json" };
 import visualProjectionSchema from "../../../schema/yarramate-projection.schema.json" with { type: "json" };
@@ -26,12 +27,6 @@ const Ajv2020 = Ajv2020Module.default;
 const layoutAjv = new Ajv2020({ allErrors: true });
 layoutAjv.addSchema(visualProjectionSchema);
 const validateVisualLayout = layoutAjv.compile(visualLayoutSchema);
-/**
- * Document name reported by diagnostics the server itself raises — a refused
- * frame, a frozen queue, or a transport violation that no protocol document
- * owns.
- */
-export const VISUAL_SERVER_DOCUMENT = "visual-session-server";
 /**
  * Returned on every response. The policy admits no external origin at all, so
  * neither a compromised model nor a hostile chat message can reach the network,
@@ -152,15 +147,17 @@ const serverError = (code, message) => new Error(`${code}: ${message}`);
  * `/`, because these diagnostics are published in `visual-diagnostic-result/v1`
  * documents and read back by the one-shot agent clients.
  */
-const serverDiagnostic = (code, message, pointer = "/") => ({
-    severity: "error",
-    code,
-    message,
-    path: VISUAL_SERVER_DOCUMENT,
-    pointer,
-    line: 1,
-    column: 1,
-});
+/**
+ * Names the subjects a Core diagnostic is about, so the canvas can mark the
+ * element a rule refused rather than reporting a failure with nothing on
+ * screen changed.
+ *
+ * Core derives this at the boundary that publishes a result rather than inside
+ * `compileWorkspace`, which keeps compiler diagnostics a pure function of the
+ * model. `check` has always done it. This adapter is the consumer the
+ * derivation was written for and never did, so every diagnostic it sent to a
+ * browser arrived anchored to a byte offset the browser cannot use.
+ */
 /**
  * Compares two capabilities without leaking where they differ, or how long the
  * presented one is: both sides are reduced to a fixed-width digest first, so
@@ -248,8 +245,6 @@ const eventFrom = (input, envelope) => {
             return { ...envelope, type: input.type, payload: input.payload };
         case "filter.query":
             return { ...envelope, type: input.type, payload: input.payload };
-        case "view.save":
-            return { ...envelope, type: input.type, payload: input.payload };
         case "changeset.commit":
             return { ...envelope, type: input.type, payload: input.payload };
         case "layout.save":
@@ -257,27 +252,70 @@ const eventFrom = (input, envelope) => {
     }
 };
 /**
- * Turns a view title into a schema-valid projection id: lowercase,
- * hyphen-separated, letter-led. A title with no letters or digits degrades
- * to "view" rather than producing an id the schema would reject.
+ * What a batch that changes no subject reports.
+ *
+ * A commit carrying only view operations never reaches Core: an operations
+ * document with an empty list is refused by the operations schema (`YM201`),
+ * and rightly - "apply nothing" is not a batch. The receipt still has to name
+ * the documents that changed, which here are the projections.
  */
-const slugify = (title) => {
-    const cleaned = title
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "");
-    if (cleaned.length === 0)
-        return "view";
-    return /^[a-z]/.test(cleaned) ? cleaned : `view-${cleaned}`;
-};
-/** Appends a numeric suffix only when the base id collides with a known view. */
-const uniqueViewId = (base, taken) => {
-    if (!taken.has(base))
-        return base;
-    let suffix = 2;
-    while (taken.has(`${base}-${suffix}`))
-        suffix += 1;
-    return `${base}-${suffix}`;
+const noModelChange = (workspace, documents) => ({
+    format: "yarramate/apply-result/v1",
+    workspace,
+    applied: {
+        addedConcepts: 0,
+        addedRelationships: 0,
+        updatedConcepts: 0,
+        updatedRelationships: 0,
+        deletedConcepts: 0,
+        deletedRelationships: 0,
+        renamedConcepts: 0,
+        renamedRelationships: 0,
+        addedObservations: 0,
+        updatedObservations: 0,
+        deletedObservations: 0,
+    },
+    documents,
+});
+/**
+ * Lands a planned batch plus the view writes beside it, as one `writeAll`.
+ *
+ * `landOperations` would write the model's half on its own, which is the one
+ * thing this must not do: two calls are two batches, and a view removed in one
+ * and a subject edited in the other can half land.
+ */
+const landPlanned = (store, planned, viewWrites, operationsPath, workspaceId) => {
+    if (planned !== null && !planned.ok)
+        return planned.outcome;
+    const writes = [...(planned?.writes ?? []), ...viewWrites];
+    const viewPaths = viewWrites.map((write) => write.path);
+    const outcome = planned === null
+        ? {
+            ok: true,
+            sources: [],
+            result: noModelChange(workspaceId, viewPaths),
+        }
+        : {
+            ...planned.outcome,
+            // Core names the documents IT rewrote, which is the model's half.
+            // The projections went out in the same `writeAll`, so a receipt that
+            // named only Core's half would report one file where two landed -
+            // and a mixed batch is the ordinary case now that creating a subject
+            // also puts it in the view that created it (#255).
+            result: {
+                ...planned.outcome.result,
+                documents: [...planned.outcome.result.documents, ...viewPaths],
+            },
+        };
+    if (writes.length === 0)
+        return outcome;
+    const written = store.writeAll(writes);
+    if (written.ok)
+        return outcome;
+    return {
+        ok: false,
+        diagnostics: writeConflictDiagnostics(written.conflicts, operationsPath),
+    };
 };
 /**
  * Serves one authenticated visual session over loopback. The handle owns the
@@ -344,10 +382,16 @@ export const startVisualServer = async (options) => {
         }
         return abandon(serverError("YMVS132", `Session requires a resolvable workspace manifest at ${manifestPath}`));
     })();
-    // Saved views join this list as they are written (see `view.save`), because
-    // a reconnecting browser is handed it in its snapshot and `layout.save`
-    // checks projection ids against it.
-    const views = resolvedWorkspace.projections.flatMap((projectionPath) => {
+    /**
+     * One view, read off disk. `undefined` for a projection that is unreadable
+     * or that the schema refuses — a broken saved view skips rather than failing
+     * the session, the same way a broken layout sidecar does.
+     *
+     * `subjectCount` is left at zero here and refreshed by
+     * `renderedWorkspaceOf`: counting needs the compiled graph, which does not
+     * exist yet when the session builds its first list.
+     */
+    const readViewSummary = (projectionPath) => {
         try {
             const projectionSource = readFileSync(resolve(options.cwd, projectionPath), "utf8");
             const loaded = loadProjection({
@@ -355,22 +399,19 @@ export const startVisualServer = async (options) => {
                 source: projectionSource,
             });
             if (!loaded.ok)
-                return [];
-            const { projection } = loaded;
-            return [
-                {
-                    id: projection.id,
-                    title: projection.presentation?.title ?? projection.id,
-                    description: projection.presentation?.description ?? "",
-                    query: projection.query,
-                    presentation: projection.presentation,
-                },
-            ];
+                return undefined;
+            return viewSummaryOf(loaded.projection, projectionPath);
         }
         catch {
-            // Skipped projection: session continues with remaining views.
-            return [];
+            return undefined;
         }
+    };
+    // Saved views join this list as a commit lands them (see `adoptLandedViews`),
+    // because a reconnecting browser is handed it in its snapshot and
+    // `layout.save` checks projection ids against it.
+    const views = resolvedWorkspace.projections.flatMap((projectionPath) => {
+        const summary = readViewSummary(projectionPath);
+        return summary === undefined ? [] : [summary];
     });
     // Drag positions are adapter-owned presentation state (ADR 0023): never
     // validated by Core. An invalid or unreadable sidecar is skipped exactly
@@ -416,6 +457,10 @@ export const startVisualServer = async (options) => {
         vocabulary: { conceptKinds: [], relationshipKinds: [] },
         layouts,
         sourceDigests: request.initialModel.sourceDigests,
+        // The request's model has no projections in it - `visual-model/v1` carries
+        // a graph, not a workspace - so the fallback states nothing rather than
+        // guessing. `recompileWorkspace` below fills it from disk immediately.
+        projectionDigests: {},
     };
     const capabilities = {
         chat: request.chatEnabled,
@@ -440,15 +485,49 @@ export const startVisualServer = async (options) => {
      * Returns whether it compiled, so a post-write failure can freeze the
      * session instead of serving a stale graph.
      */
-    const recompileWorkspace = () => {
+    const workspaceSources = () => {
         try {
-            const sources = [
+            return [
                 ...resolvedWorkspace.profiles,
                 ...resolvedWorkspace.documents,
             ].map((path) => ({
                 path,
                 source: readFileSync(resolve(options.cwd, path), "utf8"),
             }));
+        }
+        catch {
+            // A source that cannot be read is one whose diagnostics belong to no
+            // subject anyway, so an empty list is the right answer rather than a
+            // throw from a path that is only trying to add detail.
+            return [];
+        }
+    };
+    /**
+     * The digest of every projection the session knows about, read now.
+     *
+     * Read from `views` rather than from `resolvedWorkspace.projections`,
+     * because a view created mid-session joins the former and never the latter:
+     * the manifest is resolved once at startup and never again. One that has
+     * been removed is simply absent, which is the same thing the map says about
+     * one that never existed — and the browser reads both as "no pin", which is
+     * correct for a create and refused by the store for a delete.
+     */
+    const projectionDigestsNow = () => {
+        const digests = {};
+        for (const view of views) {
+            try {
+                digests[view.path] = digestOf(readFileSync(resolve(options.cwd, view.path), "utf8"));
+            }
+            catch {
+                // Gone from disk: nothing to pin against, and the commit's own
+                // conflict check is what reports it rather than a guess made here.
+            }
+        }
+        return digests;
+    };
+    const recompileWorkspace = () => {
+        try {
+            const sources = workspaceSources();
             const compiled = compileWorkspaceWithProfileContext(sources);
             if (!compiled.ok) {
                 compiledWorkspace = undefined;
@@ -458,23 +537,24 @@ export const startVisualServer = async (options) => {
                 graph: compiled.graph,
                 profileContext: compiled.profileContext,
             };
-            const conceptKinds = [
-                ...compiled.profileContext.conceptKindLineages.keys(),
-            ].map((id) => ({ id, label: kindLabelOf(id) }));
-            const relationshipKinds = [
-                ...compiled.profileContext.relationshipKindLineages.keys(),
-            ].map((id) => ({ id, label: kindLabelOf(id) }));
-            rendered = {
+            const workspaceModel = renderedWorkspaceOf(compiledWorkspace, views, {
                 authority: rendered.authority,
                 initialView: rendered.initialView,
-                graph: projectGraphForCanvas(compiled.graph, compiled.profileContext),
                 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)])),
-            };
+                // Kept apart from `sourceDigests`, which means what this graph was
+                // compiled from and is what `YMVS112` checks — a projection is not
+                // that. A staged view operation pins against these (ADR 0103), and a
+                // projection missing from the map is one the commit will create.
+                projectionDigests: projectionDigestsNow(),
+            });
+            // Closures below retain this array, so refresh its contents without
+            // replacing the identity the session started with.
+            views.splice(0, views.length, ...workspaceModel.views);
+            rendered = workspaceModel.model;
             return true;
         }
         catch {
@@ -483,12 +563,23 @@ export const startVisualServer = async (options) => {
         }
     };
     recompileWorkspace();
-    const filterMatchedIds = (query) => {
-        if (compiledWorkspace === undefined)
-            return [];
-        const result = evaluateProjection(compiledWorkspace.graph, { format: "yarramate/projection/v1", id: "ad-hoc", version: "0", query }, compiledWorkspace.profileContext);
-        return result.subjects.map(({ id }) => id);
-    };
+    const filterMatchedIds = (query) => compiledWorkspace === undefined
+        ? []
+        : matchedIdsOf(compiledWorkspace.graph, query, compiledWorkspace.profileContext);
+    /**
+     * Why a query dropped what it dropped, as the editor's "excluded, and why"
+     * list reads it (#248).
+     *
+     * Resolved here rather than in the browser for the same reason the match set
+     * is: a `ProjectionQuery` needs the semantic graph to answer, and the browser
+     * has the rendered model rather than the graph. One evaluator, one answer -
+     * `explainProjection` shares `conceptSelector` with `evaluateProjection`, so
+     * the reason the editor shows and the set the canvas draws cannot come from
+     * two readings of the same query.
+     */
+    const filterExclusions = (query) => compiledWorkspace === undefined
+        ? []
+        : exclusionsOf(compiledWorkspace.graph, query, compiledWorkspace.profileContext);
     let listening = false;
     let bootstrapSpent = false;
     let agentAttached = false;
@@ -996,64 +1087,11 @@ export const startVisualServer = async (options) => {
                     result: {
                         query: event.payload.query,
                         matchedIds: filterMatchedIds(event.payload.query),
+                        excluded: filterExclusions(event.payload.query),
                     },
                 });
                 return;
             }
-            if (event.type === "view.save") {
-                // Saving a view is a pure filesystem write plus schema validation: it
-                // never asks the agent anything, so it is answered here directly
-                // rather than through the pending queue a poll would drain.
-                const existingIds = new Set(views.map((view) => view.id));
-                const id = event.payload.id ??
-                    uniqueViewId(slugify(event.payload.title), existingIds);
-                const presentation = {
-                    ...(event.payload.presentation ?? {}),
-                    title: event.payload.title,
-                    description: event.payload.description,
-                };
-                const candidate = {
-                    format: "yarramate/projection/v1",
-                    id,
-                    version: "1.0",
-                    query: event.payload.query,
-                    presentation,
-                };
-                const path = `.yarramate/projections/${id}.yaml`;
-                const source = stringify(candidate);
-                const loaded = loadProjection({ path, source });
-                if (!loaded.ok) {
-                    sendFrame(socket, {
-                        kind: "view-save-result",
-                        result: { ok: false, diagnostics: loaded.diagnostics },
-                    });
-                    return;
-                }
-                mkdirSync(resolve(options.cwd, ".yarramate/projections"), {
-                    recursive: true,
-                });
-                writeFileSync(resolve(options.cwd, path), source, "utf8");
-                // On disk is not enough: the list handed to a reconnecting browser and
-                // checked by `layout.save` lives here, so an overwrite replaces its
-                // summary in place and a new view joins the end.
-                const summary = {
-                    id,
-                    title: event.payload.title,
-                    description: event.payload.description,
-                    query: event.payload.query,
-                    presentation,
-                };
-                const saved = views.findIndex((view) => view.id === id);
-                if (saved === -1)
-                    views.push(summary);
-                else
-                    views[saved] = summary;
-                sendFrame(socket, {
-                    kind: "view-save-result",
-                    result: { ok: true, id, path },
-                });
-                return;
-            }
             if (event.type === "changeset.commit") {
                 // Landing a batch is mechanical: Core's `applyOperations` never asks
                 // the agent anything, so it is answered here directly rather than
@@ -1073,7 +1111,14 @@ export const startVisualServer = async (options) => {
                 // state is decoration.
                 const pins = event.payload.sourceDigests;
                 const refused = [];
-                for (const path of new Set(event.payload.operations.map((operation) => operation.document))) {
+                for (const path of new Set([
+                    ...event.payload.operations.map((operation) => operation.document),
+                    // A staged view is a document this batch touches like any other, so
+                    // it answers to the same precondition (ADR 0103). Without this a
+                    // projection someone edited on disk would be overwritten by a
+                    // reviewer who never saw the edit.
+                    ...event.payload.viewOperations.map((operation) => operation.path),
+                ])) {
                     let held;
                     try {
                         held = digestOf(readFileSync(resolve(options.cwd, path), "utf8"));
@@ -1106,29 +1151,84 @@ export const startVisualServer = async (options) => {
                         result: { ok: false, diagnostics: refused },
                     });
                     if (recompileWorkspace())
-                        broadcast({ kind: "model", model: rendered });
+                        broadcast({ kind: "model", model: rendered, views });
                     return;
                 }
                 const operationsSource = stringify({
                     format: "yarramate/operations/v1",
                     operations: event.payload.operations,
                 });
-                const outcome = applyOperations({ path: "changeset.yaml", source: operationsSource }, { path: manifestPath, source: readFileSync(manifestPath, "utf8") }, options.cwd);
+                // The pin check above is about the reviewer's view: whether the value
+                // on screen is still the value on disk. What follows is about the
+                // bytes: Core is handed the sources, returns the ones it changed, and
+                // the store writes them only if each still holds what Core was shown
+                // (ADR 0100). That second check is what closes the window the pin
+                // check alone left open, which used to span a whole workspace compile
+                // between the digest that satisfied it and the write that acted on it.
+                const loadedWorkspace = loadWorkspaceManifest({ path: manifestPath, source: readFileSync(manifestPath, "utf8") }, options.cwd);
+                if (!loadedWorkspace.ok) {
+                    sendFrame(socket, {
+                        kind: "apply-result",
+                        result: {
+                            ok: false,
+                            diagnostics: published(loadedWorkspace.diagnostics, workspaceSources()),
+                        },
+                    });
+                    return;
+                }
+                const store = createFileSystemStore(options.cwd);
+                // Core is asked nothing when nothing about the model changed: an
+                // operations document with an empty list is refused by the operations
+                // schema, and a batch of views only is a legitimate thing to commit.
+                const planned = event.payload.operations.length === 0
+                    ? null
+                    : planOperations(store, {
+                        workspace: loadedWorkspace.workspace,
+                        operations: {
+                            path: "changeset.yaml",
+                            source: operationsSource,
+                        },
+                        manifestDirectory: posixDirectoryOf(relative(options.cwd, manifestPath)),
+                    });
+                // The views' own writes, composed and validated the same way
+                // `view.save` used to compose one, but not yet written: both halves go
+                // to the store in a single batch so a view and the subjects it shows
+                // land together or not at all (ADR 0103).
+                const viewWrites = planViewWrites(event.payload.viewOperations, loadedWorkspace.workspace, store);
+                if (!viewWrites.ok) {
+                    sendFrame(socket, {
+                        kind: "apply-result",
+                        result: { ok: false, diagnostics: viewWrites.diagnostics },
+                    });
+                    return;
+                }
+                const outcome = landPlanned(store, planned, viewWrites.writes, "changeset.yaml", loadedWorkspace.workspace.id);
                 if (!outcome.ok) {
                     // Nothing landed: forward Core's diagnostics verbatim (ADR 0062)
                     // rather than recompiling or broadcasting anything.
                     sendFrame(socket, {
                         kind: "apply-result",
-                        result: { ok: false, diagnostics: outcome.diagnostics },
+                        result: {
+                            ok: false,
+                            diagnostics: published(outcome.diagnostics, workspaceSources()),
+                        },
                     });
                     return;
                 }
+                // The views list is maintained by hand, because nothing else will:
+                // `resolvedWorkspace` was resolved once at startup and never again, so
+                // a recompile re-reads the documents it already knew about and learns
+                // nothing about a projection this batch just created or removed. The
+                // rail, `layout.save`'s id check, and a reconnecting browser all read
+                // this list, so leaving it stale is how they come to disagree with the
+                // disk. Preserve the mutable list identity that session closures hold.
+                views.splice(0, views.length, ...adoptLandedViews(views, event.payload.viewOperations, readViewSummary));
                 sendFrame(socket, {
                     kind: "apply-result",
                     result: { ok: true, result: outcome.result },
                 });
                 if (recompileWorkspace()) {
-                    broadcast({ kind: "model", model: rendered });
+                    broadcast({ kind: "model", model: rendered, views });
                     return;
                 }
                 // A post-write compile failure is a bug, not a user error: the batch
@@ -1781,17 +1881,17 @@ export const startVisualServer = async (options) => {
     let started;
     try {
         await writeVisualSessionDescriptor(paths, {
-            format: "yarramate/visual-session-descriptor/v1",
+            format: "yarramate/visual-session-descriptor/v2",
             protocolVersion: VISUAL_PROTOCOL_VERSION,
             sessionId,
             origin,
             agentCapability: session.agentToken,
-            sessionRoot: paths.root,
-            journalPath: paths.journal,
+            sessionRoot: toWireFileUri(paths.root),
+            journalPath: toWireFileUri(paths.journal),
             createdAt: stamp(),
         });
         started = {
-            format: "yarramate/visual-session-started/v1",
+            format: "yarramate/visual-session-started/v2",
             protocolVersion: VISUAL_PROTOCOL_VERSION,
             sessionId,
             authority: request.authority,
@@ -1800,8 +1900,8 @@ export const startVisualServer = async (options) => {
             browserUrl: `${origin}/bootstrap?key=${session.browserToken}`,
             webSocketUrl,
             origin,
-            descriptorPath: paths.descriptor,
-            sessionRoot: paths.root,
+            descriptorPath: toWireFileUri(paths.descriptor),
+            sessionRoot: toWireFileUri(paths.root),
             capabilities,
             startedAt: stamp(),
         };

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

@@ -61,6 +61,15 @@ export interface VisualAppendRejected {
     readonly diagnostics: readonly VisualDiagnostic[];
 }
 export type VisualAppendResult = VisualAppendAccepted | VisualAppendRejected;
+/**
+ * The one place `VisualSessionPaths` is constructed. Every field stays a
+ * native filesystem path — the form `fs`/`path` APIs, the in-process state
+ * maps keyed by `paths.journal`, and directory cleanup all need — because
+ * this is consumed as a filesystem path far more often than it is ever
+ * serialized. The few sites that write one of these fields into a
+ * schema-checked wire document encode it there, with `toWireFileUri`, rather
+ * than here.
+ */
 export declare const visualSessionPaths: (root: string) => VisualSessionPaths;
 export declare const createVisualSession: (request: VisualSessionRequest, deps: SessionDependencies) => Promise<VisualSessionCreated>;
 /**

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

@@ -1,7 +1,7 @@
 import { constants } from 'node:fs';
 import { lstat, mkdir, open, readFile, readdir, rename, rm, stat, truncate, writeFile, } from 'node:fs/promises';
 import { basename, dirname, join, resolve } from 'node:path';
-import { VISUAL_LIMITS, parseVisualEvent, parseVisualHandoff, parseVisualResponse, parseVisualSessionDescriptor, parseVisualSessionRequest, } from './protocol.js';
+import { VISUAL_LIMITS, parseVisualEvent, parseVisualHandoff, parseVisualResponse, parseVisualSessionDescriptor, parseVisualSessionRequest, toWireFileUri, } from './protocol.js';
 import { compileWorkspaceWithProfileContext, } from '../../compiler.js';
 import { projectGraphForCanvas } from '../../graph-projection.js';
 export const VISUAL_SESSION_MARKER_FORMAT = 'yarramate/visual-session-marker/v1';
@@ -105,6 +105,15 @@ const writePrivateJson = async (path, value) => {
     await rename(temporary, path);
     await syncDirectory(dirname(path));
 };
+/**
+ * The one place `VisualSessionPaths` is constructed. Every field stays a
+ * native filesystem path — the form `fs`/`path` APIs, the in-process state
+ * maps keyed by `paths.journal`, and directory cleanup all need — because
+ * this is consumed as a filesystem path far more often than it is ever
+ * serialized. The few sites that write one of these fields into a
+ * schema-checked wire document encode it there, with `toWireFileUri`, rather
+ * than here.
+ */
 export const visualSessionPaths = (root) => {
     const base = resolve(root);
     return {
@@ -298,8 +307,8 @@ export const writeVisualSessionDescriptor = async (paths, descriptor) => {
     if (validated.value.sessionId !== marker.id) {
         throw storeError('YMVS126', `Descriptor belongs to session "${validated.value.sessionId}", not "${marker.id}"`);
     }
-    if (validated.value.sessionRoot !== paths.root ||
-        validated.value.journalPath !== paths.journal) {
+    if (validated.value.sessionRoot !== toWireFileUri(paths.root) ||
+        validated.value.journalPath !== toWireFileUri(paths.journal)) {
         throw storeError('YMVS125', `Descriptor for session "${marker.id}" names artefacts outside "${paths.root}"`);
     }
     await writePrivateJson(paths.descriptor, validated.value);
@@ -521,7 +530,7 @@ export const recoverVisualSession = async (paths, includeTranscript = false) =>
             : 'cancelled';
     const last = journal.records.at(-1);
     const handoff = {
-        format: 'yarramate/visual-handoff/v1',
+        format: 'yarramate/visual-handoff/v2',
         sessionId: marker.id,
         authority: marker.authority,
         decision,
@@ -533,7 +542,7 @@ export const recoverVisualSession = async (paths, includeTranscript = false) =>
         requestedChanges: summary?.requestedChanges ?? [],
         unresolvedQuestions: summary?.unresolvedQuestions ?? [],
         finalViews: summary?.finalViews ?? visited.slice(-256),
-        transcriptPath: paths.journal,
+        transcriptPath: toWireFileUri(paths.journal),
         completedAt: last?.timestamp ?? marker.createdAt,
         // Present and undefined rather than absent, so a caller cannot mistake the
         // summary-only handoff for one whose transcript it forgot to read.