yarramate 0.18.0 → 0.20.0

package/dist/adapters/visual/protocol.js

@@ -1,12 +1,22 @@
 import { posix } from 'node:path';
 import Ajv2020Module from 'ajv/dist/2020.js';
-import { describeSchemaViolation } from '../../source-document.js';
+import { describeSchemaViolation, readableSchemaErrors, } from '../../source-document.js';
 import visualDiagnosticResultSchema from '../../../schema/yarramate-visual-diagnostic-result.schema.json' with { type: 'json'
 };
 import visualEventSchema from '../../../schema/yarramate-visual-event.schema.json' with { type: 'json'
 };
+import visualGraphSchema from '../../../schema/yarramate-visual-graph.schema.json' with { type: 'json'
+};
+import applyResultSchema from '../../../schema/yarramate-apply-result.schema.json' with { type: 'json'
+};
+import operationsSchema from '../../../schema/yarramate-operations.schema.json' with { type: 'json'
+};
+import projectionSchema from '../../../schema/yarramate-projection.schema.json' with { type: 'json'
+};
 import visualHandoffSchema from '../../../schema/yarramate-visual-handoff.schema.json' with { type: 'json'
 };
+import visualLayoutSchema from '../../../schema/yarramate-visual-layout.schema.json' with { type: 'json'
+};
 import visualModelSchema from '../../../schema/yarramate-visual-model.schema.json' with { type: 'json'
 };
 import visualResponseSchema from '../../../schema/yarramate-visual-response.schema.json' with { type: 'json'
@@ -24,17 +34,28 @@ import { VISUAL_LIMITS, } from './protocol-contract.js';
 // validates travel with the validators.
 export * from './protocol-contract.js';
 const Ajv2020 = Ajv2020Module.default;
-const ajv = new Ajv2020({ allErrors: true });
+// `discriminator` on Core's operation union routes a staged edit to the branch
+// its `op` names, so a browser changeset reports the fault the reviewer made
+// rather than one near-miss per operation kind.
+const ajv = new Ajv2020({ allErrors: true, discriminator: true });
 ajv.addSchema([
     visualDiagnosticResultSchema,
-    visualModelSchema,
     visualEventSchema,
+    visualGraphSchema,
+    visualHandoffSchema,
+    visualModelSchema,
     visualResponseSchema,
+    visualSessionDescriptorSchema,
     visualSessionRequestSchema,
     visualSessionStartedSchema,
-    visualSessionDescriptorSchema,
-    visualHandoffSchema,
     visualStatusSchema,
+    visualLayoutSchema,
+    projectionSchema,
+    // The commit path's event and response documents reference Core's operations
+    // and apply-result shapes rather than restating them, so Ajv needs both
+    // resolvable before it compiles the visual validators.
+    operationsSchema,
+    applyResultSchema,
 ]);
 // Diagnostics report the document they came from rather than a source file,
 // because visual protocol documents arrive as parsed JSON over the wire.
@@ -50,7 +71,22 @@ const validateVisualModel = visualValidator('visual-model/v1');
 const validateVisualSessionRequest = visualValidator('visual-session-request/v1');
 const validateVisualSessionStarted = visualValidator('visual-session-started/v1');
 const validateVisualSessionDescriptor = visualValidator('visual-session-descriptor/v1');
-const validateVisualBrowserInput = visualValidator('visual-browser-input/v1', 'https://yarramate.org/schema/visual-event/v1#/$defs/browserInput');
+const BROWSER_INPUT_REFERENCE = 'https://yarramate.org/schema/visual-event/v1#/$defs/browserInput';
+const validateVisualBrowserInput = visualValidator('visual-browser-input/v1', BROWSER_INPUT_REFERENCE);
+/**
+ * One validator per input type, keyed by the `type` its branch fixes.
+ *
+ * The union reports every branch it tried, so a `changeset.commit` that gets
+ * one field wrong arrives as that one violation buried under seven other
+ * types' missing properties - unreadable, and it is the reviewer who has to
+ * read it. An input that names a type the protocol knows is answered against
+ * that type alone. The vocabulary is read off the schema rather than restated
+ * here, so a new input type cannot be added without one.
+ */
+const browserInputBranches = new Map(visualEventSchema.$defs.browserInput.oneOf.map((branch, index) => [
+    branch.properties.type.const,
+    visualValidator('visual-browser-input/v1', `${BROWSER_INPUT_REFERENCE}/oneOf/${index}`),
+]));
 const validateVisualEvent = visualValidator('visual-event/v1');
 const validateVisualResponse = visualValidator('visual-response/v1');
 const validateVisualHandoff = visualValidator('visual-handoff/v1');
@@ -83,13 +119,12 @@ const jsonBytes = (value) => {
         return 0;
     return Buffer.byteLength(encoded, 'utf8');
 };
-const MODEL_ROOT_CONFIG = 'likec4.config.json';
-const MODEL_SOURCE_EXTENSIONS = ['.c4', '.likec4'];
 /**
  * Relative POSIX path confined to the candidate root. Absolute paths, parent
- * traversal, empty segments, dot-prefixed segments (how a staged symlink or
- * metadata entry would be smuggled in), Windows separators, and NUL bytes are
- * all rejected.
+ * traversal, empty segments, `.`/`..` segments, Windows separators, and NUL
+ * bytes are all rejected. A dot-prefixed directory is not an escape and is
+ * kept: every workspace keeps its documents under `.yarramate/`, so the
+ * digests of a canonical model are unrepresentable without it.
  */
 const isConfinedRelativePath = (candidate) => {
     if (candidate.length === 0 || candidate.length > 1024)
@@ -102,35 +137,11 @@ const isConfinedRelativePath = (candidate) => {
         return false;
     return candidate
         .split('/')
-        .every((segment) => segment.length > 0 && !segment.startsWith('.'));
-};
-export const isSafeVisualModelPath = (candidate) => {
-    if (!isConfinedRelativePath(candidate))
-        return false;
-    if (candidate === MODEL_ROOT_CONFIG)
-        return true;
-    const extension = posix.extname(candidate);
-    return MODEL_SOURCE_EXTENSIONS.some((allowed) => allowed === extension);
+        .every((segment) => segment.length > 0 && segment !== '.' && segment !== '..');
 };
 const modelSemantics = (input, path, prefix) => {
     const fields = documentFields(input);
     const diagnostics = [];
-    const files = documentFields(fields.files);
-    const fileKeys = Object.keys(files);
-    if (fileKeys.length > 0) {
-        let sources = 0;
-        for (const key of fileKeys) {
-            if (!isSafeVisualModelPath(key)) {
-                diagnostics.push(visualDiagnostic('YMVS113', `Model file "${key}" escapes the candidate root or is not a LikeC4 source`, path, `${prefix}/files/${pointerSegment(key)}`));
-                continue;
-            }
-            if (key !== MODEL_ROOT_CONFIG)
-                sources += 1;
-        }
-        if (sources === 0) {
-            diagnostics.push(visualDiagnostic('YMVS114', 'A visual model requires at least one .c4 or .likec4 source file', path, `${prefix}/files`));
-        }
-    }
     const digestKeys = Object.keys(documentFields(fields.sourceDigests));
     for (const key of digestKeys) {
         if (isConfinedRelativePath(key))
@@ -140,9 +151,6 @@ const modelSemantics = (input, path, prefix) => {
     if (fields.authority === 'canonical' && digestKeys.length === 0) {
         diagnostics.push(visualDiagnostic('YMVS112', 'A canonical visual model must record the source digests it was derived from', path, `${prefix}/sourceDigests`));
     }
-    if (fields.authority === 'ad-hoc' && digestKeys.length > 0) {
-        diagnostics.push(visualDiagnostic('YMVS112', 'An ad-hoc visual model must not claim canonical source digests', path, `${prefix}/sourceDigests`));
-    }
     if (jsonBytes(input) > VISUAL_LIMITS.modelBytes) {
         diagnostics.push(visualDiagnostic('YMVS115', `A visual model must not exceed ${VISUAL_LIMITS.modelBytes} bytes`, path, prefix === '' ? '/' : prefix));
     }
@@ -182,9 +190,6 @@ const responseSemantics = (input, path) => {
     if (fields.type === 'chat.response') {
         return chatTextSemantics(fields.payload, path, '/payload');
     }
-    if (fields.type === 'model.replace') {
-        return modelSemantics(documentFields(fields.payload).model, path, '/payload/model');
-    }
     return [];
 };
 /**
@@ -233,15 +238,30 @@ const schemaDiagnostics = (errors, code, path) => errors.map((error) => {
         ? `Property "${property}" is not allowed`
         : `${path} schema violation: ${describeSchemaViolation(error)}`, path, pointer);
 });
+/**
+ * The same violation, reported once.
+ *
+ * A union reports the branches it tried, and sibling branches that share a
+ * requirement each raise it - the reviewer reads one document, not the
+ * validator's search. Diagnostics are already sorted, so identical neighbours
+ * are adjacent; nothing that differs in code, pointer, or message is lost.
+ */
+const distinct = (diagnostics) => diagnostics.filter((diagnostic, index) => {
+    if (index === 0)
+        return true;
+    const previous = diagnostics[index - 1];
+    return (previous === undefined ||
+        visualDiagnosticOrder(previous, diagnostic) !== 0);
+});
 const parseWith = (validate, input, code) => {
     const path = documentPaths.get(validate) ?? 'visual-document';
     const semantics = semanticsByDocument[path];
-    const diagnostics = [
+    const diagnostics = distinct([
         ...(validate(input)
             ? []
-            : schemaDiagnostics(validate.errors ?? [], code, path)),
+            : schemaDiagnostics(readableSchemaErrors(validate.errors ?? []), code, path)),
         ...(semantics ? semantics(input, path) : []),
-    ].sort(visualDiagnosticOrder);
+    ].sort(visualDiagnosticOrder));
     if (diagnostics.length > 0)
         return { ok: false, diagnostics };
     return { ok: true, value: input };
@@ -250,7 +270,27 @@ export const parseVisualModel = (input) => parseWith(validateVisualModel, input,
 export const parseVisualSessionRequest = (input) => parseWith(validateVisualSessionRequest, input, 'YMVS101');
 export const parseVisualSessionStarted = (input) => parseWith(validateVisualSessionStarted, input, 'YMVS102');
 export const parseVisualSessionDescriptor = (input) => parseWith(validateVisualSessionDescriptor, input, 'YMVS103');
-export const parseVisualBrowserInput = (input) => parseWith(validateVisualBrowserInput, input, 'YMVS109');
+/**
+ * The type an untrusted frame claims to be, when the protocol has that type.
+ *
+ * A refusal has to say what it refused, and the browser is holding a control
+ * open until it does. The claim is worth reporting before the document is
+ * known to be valid because the frame that named it is the one that failed.
+ */
+export const visualBrowserInputType = (input) => {
+    const claimed = documentFields(input).type;
+    return typeof claimed === 'string' && browserInputBranches.has(claimed)
+        ? claimed
+        : undefined;
+};
+export const parseVisualBrowserInput = (input) => {
+    const claimed = visualBrowserInputType(input);
+    const validate = claimed === undefined
+        ? validateVisualBrowserInput
+        : // The branch is in the map because `claimed` came out of it.
+            browserInputBranches.get(claimed);
+    return parseWith(validate, input, 'YMVS109');
+};
 export const parseVisualEvent = (input) => parseWith(validateVisualEvent, input, 'YMVS104');
 export const parseVisualResponse = (input) => parseWith(validateVisualResponse, input, 'YMVS105');
 export const parseVisualHandoff = (input) => parseWith(validateVisualHandoff, input, 'YMVS107');

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

@@ -0,0 +1,37 @@
+import type { VisualDiagnostic, VisualSessionRequest } from './protocol-contract.js';
+export interface VisualSessionRequestOptions {
+    readonly cwd: string;
+    /** Defaults to the workspace id. */
+    readonly title?: string;
+    /** Defaults to a line naming the workspace and its manifest. */
+    readonly description?: string;
+    /** Defaults to the first projection the workspace declares. */
+    readonly initialView?: string;
+    /** Defaults to `false`: a diagram-only session needs no model provider. */
+    readonly chatEnabled?: boolean;
+}
+export type VisualSessionRequestResult = {
+    readonly ok: true;
+    readonly request: VisualSessionRequest;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly VisualDiagnostic[];
+};
+/**
+ * Builds the `yarramate/visual-session-request/v1` document that `start`
+ * consumes, from the workspace on disk.
+ *
+ * The request carries a whole compiled model — 247 nodes and 338 edges for this
+ * repository's own architecture — so it is a machine's transcription of the
+ * workspace, never something an agent can honestly hand-author. Every input the
+ * document needs is already derivable: the graph from the native compiler, the
+ * digests from the same sources that compiled, and the view list from the
+ * workspace's declared projections.
+ *
+ * The result is validated through `parseVisualSessionRequest` before it is
+ * returned, so the byte ceiling, digest confinement, and authority agreement
+ * are the protocol's own rules rather than a second set restated here. A
+ * builder that cannot produce a valid document refuses instead of handing a
+ * session something it would reject at start.
+ */
+export declare const buildVisualSessionRequest: (options: VisualSessionRequestOptions) => VisualSessionRequestResult;

package/dist/adapters/visual/request.js

@@ -0,0 +1,131 @@
+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 { buildVisualModelGraph } from './session-store.js';
+/**
+ * The one manifest a session can serve. `startVisualServer` resolves exactly
+ * this path relative to its own working directory, so the builder reads the
+ * same file rather than accepting a path that could name a different workspace
+ * than the session about to render it.
+ */
+const MANIFEST_PATH = '.yarramate/workspace.yaml';
+const requestDiagnostic = (code, message, path = MANIFEST_PATH) => ({
+    severity: 'error',
+    code,
+    message,
+    path,
+    pointer: '/',
+    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.
+ *
+ * The request carries a whole compiled model — 247 nodes and 338 edges for this
+ * repository's own architecture — so it is a machine's transcription of the
+ * workspace, never something an agent can honestly hand-author. Every input the
+ * document needs is already derivable: the graph from the native compiler, the
+ * digests from the same sources that compiled, and the view list from the
+ * workspace's declared projections.
+ *
+ * The result is validated through `parseVisualSessionRequest` before it is
+ * returned, so the byte ceiling, digest confinement, and authority agreement
+ * are the protocol's own rules rather than a second set restated here. A
+ * builder that cannot produce a valid document refuses instead of handing a
+ * session something it would reject at start.
+ */
+export const buildVisualSessionRequest = (options) => {
+    const manifestPath = resolve(options.cwd, MANIFEST_PATH);
+    let manifestSource;
+    try {
+        manifestSource = readFileSync(manifestPath, 'utf8');
+    }
+    catch {
+        return {
+            ok: false,
+            diagnostics: [
+                requestDiagnostic('YMVS410', `Workspace manifest ${manifestPath} cannot be read`),
+            ],
+        };
+    }
+    const loaded = loadWorkspaceManifest({ path: manifestPath, source: manifestSource }, options.cwd);
+    if (!loaded.ok) {
+        return { ok: false, diagnostics: loaded.diagnostics };
+    }
+    const workspace = loaded.workspace;
+    // Same order the session's own recompile uses, so the request's graph and
+    // every graph the session rebuilds after a commit come from one input list.
+    const sourcePaths = [...workspace.profiles, ...workspace.documents];
+    const sources = [];
+    for (const path of sourcePaths) {
+        try {
+            sources.push({ path, source: readFileSync(resolve(options.cwd, path), 'utf8') });
+        }
+        catch {
+            return {
+                ok: false,
+                diagnostics: [
+                    requestDiagnostic('YMVS411', `Workspace source ${path} cannot be read`, path),
+                ],
+            };
+        }
+    }
+    const built = buildVisualModelGraph(sources);
+    if (!built.ok)
+        return { ok: false, diagnostics: built.diagnostics };
+    // A projection that does not load is skipped by the session too: the request
+    // names a view the browser will actually be able to open.
+    const viewIds = workspace.projections.flatMap((projectionPath) => {
+        try {
+            const projection = loadProjection({
+                path: projectionPath,
+                source: readFileSync(resolve(options.cwd, projectionPath), 'utf8'),
+            });
+            return projection.ok ? [projection.projection.id] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+    const initialView = options.initialView ?? viewIds[0];
+    if (initialView === undefined) {
+        return {
+            ok: false,
+            diagnostics: [
+                requestDiagnostic('YMVS412', `Workspace ${workspace.id} declares no loadable projection, so a session has no view to open`),
+            ],
+        };
+    }
+    if (!viewIds.includes(initialView)) {
+        return {
+            ok: false,
+            diagnostics: [
+                requestDiagnostic('YMVS413', `Workspace ${workspace.id} declares no projection "${initialView}": ${viewIds.length === 0 ? 'it declares none' : viewIds.join(', ')}`),
+            ],
+        };
+    }
+    const request = {
+        format: 'yarramate/visual-session-request/v1',
+        authority: 'canonical',
+        title: options.title ?? workspace.id,
+        description: options.description ??
+            `Native rendering of workspace ${workspace.id} from ${MANIFEST_PATH}`,
+        chatEnabled: options.chatEnabled ?? false,
+        initialModel: {
+            format: 'yarramate/visual-model/v1',
+            authority: 'canonical',
+            initialView,
+            sourceDigests: Object.fromEntries(sources.map(({ path, source }) => [path, digestOf(source)])),
+            graph: built.graph,
+        },
+    };
+    const parsed = parseVisualSessionRequest(request);
+    if (!parsed.ok)
+        return { ok: false, diagnostics: parsed.diagnostics };
+    return { ok: true, request: parsed.value };
+};

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

@@ -1,6 +1,6 @@
-import { type VisualDiagnostic, type VisualEvent, type VisualFreezeReason, type VisualHandoff, type VisualLifecycle, type VisualSessionRequest, type VisualSessionStarted, type VisualStatus, type VisualTerminationReason } from './protocol.js';
-import { type TerminalEventDependencies, type VisualSessionPaths } from './session-store.js';
-import type { VisualRenderedModel, VisualServerFrame, VisualSessionSnapshot, VisualTranscriptRecord } from './wire.js';
+import { type VisualDiagnostic, type VisualEvent, type VisualFreezeReason, type VisualHandoff, type VisualLifecycle, type VisualSessionRequest, type VisualSessionStarted, type VisualStatus, type VisualTerminationReason } from "./protocol.js";
+import { type TerminalEventDependencies, type VisualSessionPaths } from "./session-store.js";
+import type { VisualRenderedModel, VisualServerFrame, VisualSessionSnapshot, VisualTranscriptRecord } from "./wire.js";
 export type { VisualRenderedModel, VisualServerFrame, VisualSessionSnapshot, VisualTranscriptRecord, };
 /**
  * Document name reported by diagnostics the server itself raises — a refused
@@ -14,9 +14,9 @@ export declare const VISUAL_SERVER_DOCUMENT = "visual-session-server";
  * and the page can be neither framed nor used as a base for relative fetches.
  */
 export declare const VISUAL_BROWSER_HEADERS: {
-    readonly 'Referrer-Policy': 'no-referrer';
-    readonly 'X-Content-Type-Options': 'nosniff';
-    readonly 'Cache-Control': 'no-store';
+    readonly "Referrer-Policy": "no-referrer";
+    readonly "X-Content-Type-Options": "nosniff";
+    readonly "Cache-Control": "no-store";
 };
 /**
  * This session's content policy. Every source stays `'self'`; the one addition
@@ -52,7 +52,6 @@ export type VisualResponseAcceptance = {
     readonly accepted: true;
     readonly duplicate: boolean;
     readonly lastSequence: number;
-    readonly model?: VisualRenderedModel;
     readonly diagnostics: readonly VisualDiagnostic[];
 } | {
     readonly accepted: false;
@@ -67,6 +66,8 @@ export interface VisualServerOptions {
     readonly request: VisualSessionRequest;
     /** Directory that holds one directory per live session. */
     readonly baseDir: string;
+    /** Working directory for resolving .yarramate/workspace.yaml and projections. */
+    readonly cwd: string;
     /** Root of the self-contained browser application. */
     readonly assetRoot?: string;
     readonly now?: () => Date;
@@ -98,8 +99,6 @@ export interface VisualServerHandle {
 export interface ActiveVisualSession {
     readonly paths: VisualSessionPaths;
     lifecycle: VisualLifecycle;
-    /** Cancels whatever the trusted compiler is doing for this session. */
-    readonly compilerAbort: AbortController;
     /** Records why the browser stopped being able to speak. */
     readonly freeze: (reason: VisualFreezeReason) => void;
     /** Settles work already admitted, so recovery reads a quiet journal. */
@@ -115,11 +114,10 @@ export interface ActiveVisualSession {
  * that failed, a browser that never came back, a cancelling main agent, or a
  * runtime shutting itself down.
  *
- * The order is the invariant. Input freezes before anything is read; the
- * compiler is cancelled rather than waited out; work already admitted is still
- * allowed to finish; exactly one terminal event is journaled; and the handoff
- * is recovered without deleting anything, so `stop` — and only `stop` — is what
- * removes the session directory.
+ * The order is the invariant. Input freezes before anything is read; work
+ * already admitted is still allowed to finish; exactly one terminal event is
+ * journaled; and the handoff is recovered without deleting anything, so
+ * `stop` — and only `stop` — is what removes the session directory.
  */
 export declare const terminateVisualSession: (session: ActiveVisualSession, reason: VisualTerminationReason) => Promise<VisualHandoff>;
 /**