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

package/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/likec4-export.d.ts

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

package/dist/adapters/likec4-export.js

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

package/dist/adapters/visual/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>;