yarramate 0.18.0 → 0.19.0

package/README.md

@@ -184,7 +184,8 @@ people, CI, skills, and agent harnesses.
 
 Optional adapters provide LikeC4 visualization from semantic projections,
 Graphify observations as evidence overlays, loopback-only visual
-conversations over a published protocol (beta), and separately governed
+conversations that render the native model and land reviewer edits through
+the same validated `apply` batch (beta), and separately governed
 compatibility profiles for external languages. Core depends on none of them.
 
 YarraMate is not affiliated with or certified by The Open Group. ArchiMate®

package/catalogues/core-enrichment.yaml

@@ -1,6 +1,6 @@
 format: yarramate/question-catalogue/v1
 id: core-enrichment
-version: "0.7"
+version: "0.8"
 profile: yarramate/core@0.1
 presentation:
   title: Core enrichment interview
@@ -1075,3 +1075,54 @@ questions:
     resolution: >-
       Declare architecture states and mark presence with present-in where the
       distinction carries decisions; explicitly decline states otherwise.
+
+  - id: kind-untested
+    wave: hygiene
+    since: "0.8"
+    scope: subject
+    subjects:
+      kinds:
+        - yarramate/core@0.1#resource
+        - yarramate/core@0.1#businessActor
+        - yarramate/core@0.1#businessRole
+        - yarramate/core@0.1#businessCollaboration
+        - yarramate/core@0.1#businessInterface
+        - yarramate/core@0.1#applicationComponent
+        - yarramate/core@0.1#applicationCollaboration
+        - yarramate/core@0.1#applicationInterface
+        - yarramate/core@0.1#node
+        - yarramate/core@0.1#device
+        - yarramate/core@0.1#systemSoftware
+        - yarramate/core@0.1#technologyCollaboration
+        - yarramate/core@0.1#technologyInterface
+        - yarramate/core@0.1#path
+        - yarramate/core@0.1#communicationNetwork
+        - yarramate/core@0.1#equipment
+        - yarramate/core@0.1#facility
+        - yarramate/core@0.1#distributionNetwork
+    trigger:
+      - condition: unconstrained-kind
+    question: >-
+      Nothing in the model tests that {subject.name} is a structural element
+      at all: no behaviour is assigned to it, so reclassifying it as a
+      service, an object, or a goal would compile exactly the same. What
+      does it run, host, or perform?
+    askPlain: >-
+      What does {subject.name} actually do, or what runs on it? The model
+      says what it is but nothing says what it takes part in.
+    materiality: >-
+      A structural kind is a promise that something behaves through this
+      element. Only four relationship kinds constrain the aspect of an
+      endpoint, so where none of them touches the subject the kind is a
+      label no check can contradict — the choice between a node, a piece of
+      system software, and an application component stops carrying
+      information, and diagrams inherit a distinction the model never made.
+    authority: either
+    resolution: >-
+      Assign {subject.name} to the behaviour it performs — the process,
+      function, service, or capability it carries. Assignment is the one
+      claim whose source endpoint must be an active structure, so recording
+      it makes the classification falsifiable. If nothing in scope is
+      assigned to it, reclassify it to a kind that does carry a claim, or
+      retire it with a description saying why it sits outside this
+      architecture.

package/dist/adapters/visual/client.js

@@ -359,7 +359,6 @@ const localVisualStatus = async (descriptor) => {
                 chat: false,
                 choices: false,
                 navigation: false,
-                modelReplacement: false,
                 transcript: false,
             },
             transcriptBytes,

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

@@ -8,7 +8,10 @@
  * contract: it can import these declarations and limits without pulling Ajv,
  * `node:path`, or the schema documents into its bundle.
  */
-export declare const VISUAL_PROTOCOL_VERSION: 'yarramate/visual-protocol/v1';
+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_LIMITS: {
     readonly messageBytes: number;
     readonly modelBytes: number;
@@ -17,9 +20,9 @@ export declare const VISUAL_LIMITS: {
     readonly reconnectMs: number;
     readonly staleSessionMs: number;
 };
-export type VisualAuthority = 'canonical' | 'ad-hoc';
+export type VisualAuthority = "canonical";
 export interface VisualDiagnostic {
-    readonly severity: 'error';
+    readonly severity: "error";
     readonly code: string;
     readonly message: string;
     readonly path: string;
@@ -28,38 +31,32 @@ export interface VisualDiagnostic {
     readonly column: number;
 }
 export interface VisualDiagnosticResult {
-    readonly format: 'yarramate/visual-diagnostic-result/v1';
+    readonly format: "yarramate/visual-diagnostic-result/v1";
     readonly diagnostics: readonly VisualDiagnostic[];
 }
 export interface VisualCapabilities {
     readonly chat: boolean;
     readonly choices: boolean;
     readonly navigation: boolean;
-    readonly modelReplacement: boolean;
     readonly transcript: boolean;
 }
 export interface VisualModel {
-    readonly format: 'yarramate/visual-model/v1';
+    readonly format: "yarramate/visual-model/v1";
     readonly authority: VisualAuthority;
     readonly initialView: string;
     readonly sourceDigests: Readonly<Record<string, string>>;
-    readonly files: Readonly<Record<string, string>>;
-}
-export interface VisualCompilerCommand {
-    readonly command: string;
-    readonly args: readonly string[];
+    readonly graph: CanvasGraph;
 }
 export interface VisualSessionRequest {
-    readonly format: 'yarramate/visual-session-request/v1';
-    readonly authority: VisualModel['authority'];
+    readonly format: "yarramate/visual-session-request/v1";
+    readonly authority: VisualModel["authority"];
     readonly title: string;
     readonly description: string;
     readonly chatEnabled: boolean;
-    readonly compiler: VisualCompilerCommand;
     readonly initialModel: VisualModel;
 }
 export interface VisualSessionStarted {
-    readonly format: 'yarramate/visual-session-started/v1';
+    readonly format: "yarramate/visual-session-started/v1";
     readonly protocolVersion: typeof VISUAL_PROTOCOL_VERSION;
     readonly sessionId: string;
     readonly authority: VisualAuthority;
@@ -74,7 +71,7 @@ export interface VisualSessionStarted {
     readonly startedAt: string;
 }
 export interface VisualSessionDescriptor {
-    readonly format: 'yarramate/visual-session-descriptor/v1';
+    readonly format: "yarramate/visual-session-descriptor/v1";
     readonly protocolVersion: typeof VISUAL_PROTOCOL_VERSION;
     readonly sessionId: string;
     readonly origin: string;
@@ -94,6 +91,44 @@ export interface VisualViewNavigatePayload {
     readonly viewId: string;
     readonly requiresAttention: boolean;
 }
+export interface VisualViewSummary {
+    readonly id: string;
+    readonly title: string;
+    readonly description: string;
+    readonly query: ProjectionQuery;
+    readonly presentation: ProjectionDefinition["presentation"];
+}
+export interface VisualKindOption {
+    readonly id: string;
+    readonly label: string;
+}
+export interface VisualFilterQueryPayload {
+    readonly query: ProjectionQuery;
+}
+export interface VisualFilterResultPayload {
+    readonly query: ProjectionQuery;
+    readonly matchedIds: readonly string[];
+}
+export interface VisualViewSavePayload {
+    readonly id?: string;
+    readonly title: string;
+    readonly description: string;
+    readonly query: ProjectionQuery;
+    readonly presentation: ProjectionDefinition["presentation"];
+}
+export interface VisualLayoutPositions {
+    readonly [subjectId: string]: {
+        readonly x: number;
+        readonly y: number;
+    };
+}
+export interface VisualChangesetCommitPayload {
+    readonly operations: readonly YarramateOperation[];
+}
+export interface VisualLayoutSavePayload {
+    readonly projectionId: string;
+    readonly positions: VisualLayoutPositions;
+}
 /**
  * Terminal event payload. Every reason is the runtime's to choose: only it
  * knows whether a session ended by request, by a failing child, by a browser
@@ -104,7 +139,7 @@ export interface VisualSessionEndPayload {
 }
 /** End as an untrusted browser may ask for it, and nothing more. */
 export interface VisualBrowserSessionEndPayload {
-    readonly reason: 'user-ended';
+    readonly reason: "user-ended";
 }
 export interface VisualBrowserConnectedPayload {
     readonly connectionId: string;
@@ -125,24 +160,40 @@ export interface VisualBrowserDisconnectedPayload {
  * sequence and event identifier.
  */
 export type VisualBrowserInput = {
-    readonly type: 'chat.message';
+    readonly type: "chat.message";
     readonly lastAcknowledgedSequence: number;
     readonly payload: VisualChatMessagePayload;
 } | {
-    readonly type: 'choice.selected';
+    readonly type: "choice.selected";
     readonly lastAcknowledgedSequence: number;
     readonly payload: VisualChoiceSelectedPayload;
 } | {
-    readonly type: 'view.navigate';
+    readonly type: "view.navigate";
     readonly lastAcknowledgedSequence: number;
     readonly payload: VisualViewNavigatePayload;
 } | {
-    readonly type: 'session.end';
+    readonly type: "filter.query";
+    readonly lastAcknowledgedSequence: number;
+    readonly payload: VisualFilterQueryPayload;
+} | {
+    readonly type: "view.save";
+    readonly lastAcknowledgedSequence: number;
+    readonly payload: VisualViewSavePayload;
+} | {
+    readonly type: "changeset.commit";
+    readonly lastAcknowledgedSequence: number;
+    readonly payload: VisualChangesetCommitPayload;
+} | {
+    readonly type: "layout.save";
+    readonly lastAcknowledgedSequence: number;
+    readonly payload: VisualLayoutSavePayload;
+} | {
+    readonly type: "session.end";
     readonly lastAcknowledgedSequence: number;
     readonly payload: VisualBrowserSessionEndPayload;
 };
 interface VisualEventEnvelope<Type extends string, Payload> {
-    readonly format: 'yarramate/visual-event/v1';
+    readonly format: "yarramate/visual-event/v1";
     readonly sessionId: string;
     readonly sequence: number;
     readonly eventId: string;
@@ -150,12 +201,25 @@ interface VisualEventEnvelope<Type extends string, Payload> {
     readonly timestamp: string;
     readonly payload: Payload;
 }
-export type VisualEvent = VisualEventEnvelope<'chat.message', VisualChatMessagePayload> | VisualEventEnvelope<'choice.selected', VisualChoiceSelectedPayload> | VisualEventEnvelope<'view.navigate', VisualViewNavigatePayload> | VisualEventEnvelope<'session.end', VisualSessionEndPayload> | VisualEventEnvelope<'browser.connected', VisualBrowserConnectedPayload> | VisualEventEnvelope<'browser.disconnected', VisualBrowserDisconnectedPayload>;
+export type VisualEvent = VisualEventEnvelope<"chat.message", VisualChatMessagePayload> | VisualEventEnvelope<"choice.selected", VisualChoiceSelectedPayload> | VisualEventEnvelope<"view.navigate", VisualViewNavigatePayload> | VisualEventEnvelope<"session.end", VisualSessionEndPayload> | VisualEventEnvelope<"browser.connected", VisualBrowserConnectedPayload> | VisualEventEnvelope<"browser.disconnected", VisualBrowserDisconnectedPayload> | VisualEventEnvelope<"filter.query", VisualFilterQueryPayload> | VisualEventEnvelope<"view.save", VisualViewSavePayload> | VisualEventEnvelope<"changeset.commit", VisualChangesetCommitPayload> | VisualEventEnvelope<"layout.save", VisualLayoutSavePayload>;
+/**
+ * The filter a chat turn resolved to. The agent states `query` and nothing
+ * else: the runtime evaluates it against the same graph a `filter.query`
+ * event is evaluated against and fills `matchedIds` in before the response
+ * is journaled or streamed (ADR 0090). `matchedIds` is optional so a
+ * resolved response survives a transcript round-trip - an agent that sends
+ * one is refused.
+ */
+export interface VisualChatAppliedQuery {
+    readonly query: ProjectionQuery;
+    readonly matchedIds?: readonly string[];
+}
 export interface VisualChatResponsePayload {
     readonly text: string;
+    readonly appliedQuery?: VisualChatAppliedQuery;
 }
 export interface VisualAgentStatusPayload {
-    readonly state: 'thinking' | 'compiling' | 'waiting' | 'idle';
+    readonly state: "thinking" | "compiling" | "waiting" | "idle";
     readonly detail?: string;
 }
 export interface VisualChoiceOption {
@@ -168,9 +232,6 @@ export interface VisualChoicePresentPayload {
     readonly question: string;
     readonly options: readonly VisualChoiceOption[];
 }
-export interface VisualModelReplacePayload {
-    readonly model: VisualModel;
-}
 export interface VisualHandoffSummary {
     readonly summary: string;
     readonly confirmedDecisions: readonly string[];
@@ -181,8 +242,30 @@ export interface VisualHandoffSummary {
 export interface VisualDiagnosticPayload {
     readonly diagnostics: readonly VisualDiagnostic[];
 }
+export type VisualViewSaveResultPayload = {
+    readonly ok: true;
+    readonly id: string;
+    readonly path: string;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly VisualDiagnostic[];
+};
+export type VisualApplyResultPayload = {
+    readonly ok: true;
+    readonly result: YarramateApplyResult;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly VisualDiagnostic[];
+};
+export type VisualLayoutSaveResultPayload = {
+    readonly ok: true;
+    readonly path: string;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
 interface VisualResponseEnvelope<Type extends string, Payload> {
-    readonly format: 'yarramate/visual-response/v1';
+    readonly format: "yarramate/visual-response/v1";
     readonly sessionId: string;
     readonly responseId: string;
     readonly eventId: string;
@@ -190,11 +273,11 @@ interface VisualResponseEnvelope<Type extends string, Payload> {
     readonly timestamp: string;
     readonly payload: Payload;
 }
-export type VisualResponse = VisualResponseEnvelope<'chat.response', VisualChatResponsePayload> | VisualResponseEnvelope<'agent.status', VisualAgentStatusPayload> | VisualResponseEnvelope<'choice.present', VisualChoicePresentPayload> | VisualResponseEnvelope<'model.replace', VisualModelReplacePayload> | VisualResponseEnvelope<'handoff.complete', VisualHandoffSummary> | VisualResponseEnvelope<'diagnostic', VisualDiagnosticPayload>;
-export type VisualHandoffDecision = 'completed' | 'cancelled' | 'failed';
-export type VisualTerminationReason = 'user-ended' | 'child-failed' | 'browser-timeout' | 'main-cancelled' | 'server-failed' | 'compiler-failed';
+export type VisualResponse = VisualResponseEnvelope<"chat.response", VisualChatResponsePayload> | VisualResponseEnvelope<"agent.status", VisualAgentStatusPayload> | VisualResponseEnvelope<"choice.present", VisualChoicePresentPayload> | VisualResponseEnvelope<"handoff.complete", VisualHandoffSummary> | VisualResponseEnvelope<"diagnostic", VisualDiagnosticPayload>;
+export type VisualHandoffDecision = "completed" | "cancelled" | "failed";
+export type VisualTerminationReason = "user-ended" | "child-failed" | "browser-timeout" | "main-cancelled" | "server-failed" | "compiler-failed";
 export interface VisualHandoff extends VisualHandoffSummary {
-    readonly format: 'yarramate/visual-handoff/v1';
+    readonly format: "yarramate/visual-handoff/v1";
     readonly sessionId: string;
     readonly authority: VisualAuthority;
     readonly decision: VisualHandoffDecision;
@@ -204,10 +287,10 @@ export interface VisualHandoff extends VisualHandoffSummary {
     readonly transcript?: readonly (VisualEvent | VisualResponse)[];
     readonly completedAt: string;
 }
-export type VisualLifecycle = 'starting' | 'running' | 'draining' | 'stopped';
-export type VisualFreezeReason = 'message-bytes' | 'model-bytes' | 'transcript-bytes' | 'pending-events' | 'browser-disconnected' | 'terminal-event';
+export type VisualLifecycle = "starting" | "running" | "draining" | "stopped";
+export type VisualFreezeReason = "message-bytes" | "model-bytes" | "transcript-bytes" | "pending-events" | "browser-disconnected" | "terminal-event" | "recompile-failed";
 export interface VisualStatus {
-    readonly format: 'yarramate/visual-status/v1';
+    readonly format: "yarramate/visual-status/v1";
     readonly protocolVersion: typeof VISUAL_PROTOCOL_VERSION;
     readonly sessionId: string;
     readonly lifecycle: VisualLifecycle;

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

@@ -1,14 +1,4 @@
-/**
- * Every visual protocol declaration, and the limits they are measured against,
- * with no runtime dependency of any kind.
- *
- * The validators that police these documents live in `./protocol.js`, which
- * re-exports this module so a Node consumer still has one import for the whole
- * protocol. The split exists because the browser application ships the same
- * contract: it can import these declarations and limits without pulling Ajv,
- * `node:path`, or the schema documents into its bundle.
- */
-export const VISUAL_PROTOCOL_VERSION = 'yarramate/visual-protocol/v1';
+export const VISUAL_PROTOCOL_VERSION = "yarramate/visual-protocol/v2";
 export const VISUAL_LIMITS = {
     messageBytes: 64 * 1024,
     modelBytes: 5 * 1024 * 1024,

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

@@ -1,10 +1,17 @@
 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';
-export declare const isSafeVisualModelPath: (candidate: string) => boolean;
 export declare const parseVisualModel: (input: unknown) => ParseResult<VisualModel>;
 export declare const parseVisualSessionRequest: (input: unknown) => ParseResult<VisualSessionRequest>;
 export declare const parseVisualSessionStarted: (input: unknown) => ParseResult<VisualSessionStarted>;
 export declare const parseVisualSessionDescriptor: (input: unknown) => ParseResult<VisualSessionDescriptor>;
+/**
+ * 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 declare const visualBrowserInputType: (input: unknown) => VisualBrowserInput['type'] | undefined;
 export declare const parseVisualBrowserInput: (input: unknown) => ParseResult<VisualBrowserInput>;
 export declare const parseVisualEvent: (input: unknown) => ParseResult<VisualEvent>;
 export declare const parseVisualResponse: (input: unknown) => ParseResult<VisualResponse>;

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;