yarramate 0.23.0 → 1.0.0

package/README.md

@@ -183,10 +183,19 @@ projections, evidence, and architecture states; and exposes a stable CLI for
 people, CI, skills, and agent harnesses.
 
 Optional adapters provide LikeC4 visualization from semantic projections,
-Graphify observations as evidence overlays, loopback-only visual
-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.
+Graphify observations as evidence overlays, and a visual editor that
+renders the native model and lands reviewer edits through the same
+validated `apply` batch (beta). The editor runs two ways: as the
+loopback-only session `yarramate-visual start` serves, or mounted inside
+another product from `yarramate/visual-app`, over a store that product
+owns, with no Node process behind it. Core depends on none of them.
+
+YarraMate's core profile implements the ArchiMate® 3.2 element vocabulary
+and relationship table: a relationship between two kinds is valid exactly
+when the table permits it. The custody layer YarraMate adds - evidence,
+attestations, lifecycle status, ownership, architecture states - is
+annotation that never changes what an ArchiMate element or relationship
+means (ADR 0097).
 
 YarraMate is not affiliated with or certified by The Open Group. ArchiMate®
 is a registered trademark of The Open Group. LikeC4 and Graphify are

package/catalogues/core-enrichment.yaml

@@ -1,6 +1,6 @@
 format: yarramate/question-catalogue/v1
 id: core-enrichment
-version: "0.9"
+version: "1.0"
 profile: yarramate/core@0.1
 presentation:
   title: Core enrichment interview
@@ -22,9 +22,9 @@ waves:
   - id: interaction
     name: Interaction
     description: >-
-      Load-bearing hops: the behavior a component is assigned to, the
-      serving/triggering/flow mechanism, payload, trust, reliability, and
-      capacity. Hygiene waits.
+      Load-bearing hops: the behavior a component is assigned to or the
+      interface it composes, the serving/triggering/flow mechanism,
+      payload, trust, reliability, and capacity. Hygiene waits.
   - id: business
     name: Business
     description: Who acts, what is served, and what information matters.
@@ -287,9 +287,11 @@ questions:
       influences is what makes it enforceable in review.
     authority: either
     resolution: >-
-      Add influence relationships to the decisions the principle governs,
-      or realization from the elements that embody it.
-
+      Add influence from the principle to the goals, outcomes, or
+      requirements it shapes, or realization from the requirements and
+      constraints that make it concrete. Influence only points at
+      motivation elements; a decision is recorded as the requirement it
+      produced.
   - id: assessment-unlinked
     wave: motivation
     since: "0.3"
@@ -417,6 +419,7 @@ questions:
         counterpartKinds:
           - yarramate/core@0.1#applicationComponent
           - yarramate/core@0.1#applicationInterface
+          - yarramate/core@0.1#applicationService
           - yarramate/core@0.1#applicationProcess
           - yarramate/core@0.1#applicationFunction
           - yarramate/core@0.1#applicationInteraction
@@ -459,6 +462,7 @@ questions:
         counterpartKinds:
           - yarramate/core@0.1#applicationComponent
           - yarramate/core@0.1#applicationInterface
+          - yarramate/core@0.1#applicationService
           - yarramate/core@0.1#businessActor
       - condition: missing-linkage
         kinds:
@@ -469,24 +473,33 @@ questions:
           - yarramate/core@0.1#applicationFunction
           - yarramate/core@0.1#applicationInteraction
           - yarramate/core@0.1#applicationEvent
+      - condition: missing-linkage
+        kinds:
+          - yarramate/core@0.1#composition
+          - yarramate/core@0.1#aggregation
+        direction: outgoing
+        counterpartKinds:
           - yarramate/core@0.1#applicationInterface
     question: >-
       {subject.name} participates in an application interaction, but
-      nothing it is assigned to is that interaction. What process,
-      function, interaction, event, or interface is the hop?
+      nothing it is assigned to or composes is that interaction. What
+      process, function, interaction, event, or interface is the hop?
     askPlain: >-
       {subject.name} talks to something else, but the model never names
       the work it does in that talk. What is the actual step?
     materiality: >-
-      A component-to-component edge with no assigned behavior is
-      inventory. Protocol, trust, payload, and failure have nowhere to
-      bind until the hop is a subject.
+      A component-to-component edge with no assigned behavior or composed
+      interface is inventory. Protocol, trust, payload, and failure have
+      nowhere to bind until the hop is a subject.
     authority: either
     resolution: >-
-      Add an application process, function, interaction, event, or
-      interface, assign this component to it, and relate that behavior
-      with serving, triggering, or flow to its counterpart. Do not answer
-      by deleting the component or adding a realization instead.
+      Add the application process, function, interaction, or event this
+      component performs and assign the component to it, or add the
+      application interface it exposes and compose it into the component;
+      then relate that behavior or interface with serving, triggering, or
+      flow to its counterpart. Realizing a service does not close this:
+      the service is what the hop offers, the process or interface is the
+      hop. Do not answer by deleting the component.
 
   - id: interaction-protocol-unbound
     wave: interaction
@@ -510,6 +523,7 @@ questions:
         counterpartKinds:
           - yarramate/core@0.1#applicationComponent
           - yarramate/core@0.1#applicationInterface
+          - yarramate/core@0.1#applicationService
           - yarramate/core@0.1#applicationProcess
           - yarramate/core@0.1#applicationFunction
           - yarramate/core@0.1#applicationInteraction
@@ -528,7 +542,7 @@ questions:
       hop fail, version, and authenticate differently.
     authority: either
     resolution: >-
-      Bind a mechanism-constraint on this behavior (or a not-applicable
+      Bind a mechanism-constraint on this behavior or interface (or a not-applicable
       subject if the serving kind is already the whole answer).
 
   - id: interaction-content-unknown
@@ -569,6 +583,7 @@ questions:
         - yarramate/core@0.1#applicationInteraction
         - yarramate/core@0.1#applicationEvent
         - yarramate/core@0.1#applicationInterface
+        - yarramate/core@0.1#applicationService
       statuses:
         - planned
         - current
@@ -582,6 +597,7 @@ questions:
         counterpartKinds:
           - yarramate/core@0.1#applicationComponent
           - yarramate/core@0.1#applicationInterface
+          - yarramate/core@0.1#applicationService
           - yarramate/core@0.1#applicationProcess
           - yarramate/core@0.1#applicationFunction
           - yarramate/core@0.1#applicationInteraction
@@ -630,6 +646,7 @@ questions:
         counterpartKinds:
           - yarramate/core@0.1#applicationComponent
           - yarramate/core@0.1#applicationInterface
+          - yarramate/core@0.1#applicationService
           - yarramate/core@0.1#applicationProcess
           - yarramate/core@0.1#applicationFunction
           - yarramate/core@0.1#applicationInteraction
@@ -674,6 +691,7 @@ questions:
         counterpartKinds:
           - yarramate/core@0.1#applicationComponent
           - yarramate/core@0.1#applicationInterface
+          - yarramate/core@0.1#applicationService
           - yarramate/core@0.1#applicationProcess
           - yarramate/core@0.1#applicationFunction
           - yarramate/core@0.1#applicationInteraction
@@ -940,7 +958,6 @@ questions:
           - yarramate/core@0.1#businessFunction
           - yarramate/core@0.1#applicationService
           - yarramate/core@0.1#applicationComponent
-          - yarramate/core@0.1#capability
     question: >-
       What actually delivers {subject.name}?
     askPlain: >-
@@ -952,10 +969,9 @@ questions:
       wrong.
     authority: either
     resolution: >-
-      Add realization from the process, function, or application element
-      that delivers it.
-
-
+      Add realization from the business process or function that delivers
+      it, or from the application service or component that automates it.
+      A capability is realized by the service, not the other way round.
   # ---- application ---------------------------------------------------------
   - id: app-service-unrealized
     wave: application
@@ -1033,8 +1049,7 @@ questions:
         counterpartKinds:
           - yarramate/core@0.1#applicationComponent
           - yarramate/core@0.1#applicationCollaboration
-          - yarramate/core@0.1#businessActor
-          - yarramate/core@0.1#businessRole
+          - yarramate/core@0.1#applicationInterface
     question: >-
       Who or what performs {subject.name}?
     materiality: >-
@@ -1043,9 +1058,11 @@ questions:
       to put it.
     authority: either
     resolution: >-
-      Add assignment from the component, collaboration, or actor that
-      performs the behavior.
-
+      Add assignment from the application component, collaboration, or
+      interface that performs the behavior. A business actor or role does
+      not perform application behavior: assign the actor to the business
+      process that uses it and let the application service serve that
+      process.
   - id: event-triggers-nothing
     wave: application
     since: "0.3"
@@ -1132,14 +1149,15 @@ questions:
     trigger:
       - condition: missing-linkage
         kinds:
+          - yarramate/core@0.1#realization
           - yarramate/core@0.1#serving
-          - yarramate/core@0.1#assignment
         direction: incoming
         counterpartKinds:
           - yarramate/core@0.1#node
           - yarramate/core@0.1#device
           - yarramate/core@0.1#systemSoftware
           - yarramate/core@0.1#technologyService
+          - yarramate/core@0.1#artifact
     question: >-
       Where does {subject.name} run?
     materiality: >-
@@ -1150,9 +1168,12 @@ questions:
       hosting rather than answering separately.
     authority: either
     resolution: >-
-      Add the node, device, or system software that hosts it with a
-      serving or assignment relationship into the component.
-
+      Add realization or serving from the node, device, or system
+      software that hosts it, or from the technology service it runs on;
+      or add the artifact that materializes it, with realization to the
+      component and assignment from the node that deploys the artifact.
+      Technology is never assigned to a component: assignment runs from a
+      node to the artifacts and technology behavior it carries.
   - id: node-serves-nothing
     wave: technology
     since: "0.4"
@@ -1166,6 +1187,7 @@ questions:
       - condition: missing-relationship
         kinds:
           - yarramate/core@0.1#serving
+          - yarramate/core@0.1#realization
           - yarramate/core@0.1#assignment
         direction: outgoing
     question: >-
@@ -1176,9 +1198,9 @@ questions:
       deployment budget.
     authority: either
     resolution: >-
-      Add serving or assignment relationships to the applications and
-      behavior it hosts, or remove it.
-
+      Add realization or serving to the application components it hosts,
+      or assignment to the artifacts it deploys and the technology
+      behavior it performs, or remove it.
   - id: technology-service-unrealized
     wave: technology
     since: "0.4"
@@ -1232,9 +1254,9 @@ questions:
       starts from exactly these links.
     authority: either
     resolution: >-
-      Assign the artifact to the node that deploys it and add realization
-      to the component or data it materializes.
-
+      Add assignment from the node that deploys the artifact and
+      realization from the artifact to the component or data object it
+      materializes.
   # ---- implementation ------------------------------------------------------
   - id: workpackage-delivers-nothing
     wave: implementation
@@ -1341,7 +1363,6 @@ questions:
       - condition: missing-relationship
         kinds:
           - yarramate/core@0.1#association
-          - yarramate/core@0.1#realization
         direction: any
     question: >-
       What closes {subject.name}?
@@ -1350,9 +1371,10 @@ questions:
       work closes it or the acceptance of it should be on record.
     authority: human
     resolution: >-
-      Associate the gap with the plateaus it separates and the
-      deliverable that closes it, or record the decision to accept it.
-
+      Associate the gap with the plateaus it separates and with the
+      deliverable or work package that closes it - a gap is only ever
+      associated, never realized - or associate it with the assessment
+      that records the decision to accept it.
   # ---- hygiene -------------------------------------------------------------
   - id: concept-isolated
     wave: hygiene
@@ -1503,25 +1525,27 @@ questions:
       - 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?
+      at all: every relationship it has would be just as legal if it were
+      a service, an object, or a goal. 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.
+      element. ArchiMate permits a different set of relationships for
+      every pair of kinds, so a subject whose relationships would all
+      survive reclassification to another aspect carries a kind 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.
+      function, or interaction it carries; an interface to the service it
+      exposes; a node to the artifacts and system software it runs; a
+      resource to the capability it supports. Assignment from an active
+      structure is the claim no behavior, object, or motivation element
+      could make in its place, 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/adapter-mapping.js

@@ -2,7 +2,12 @@ import Ajv2020Module from 'ajv/dist/2020.js';
 import { diagnosticOrder, loadSourceDocument, locateSourcePath, } from './source-document.js';
 import adapterMappingSchema from '../schema/yarramate-adapter-mapping.schema.json' with { type: 'json'
 };
-const Ajv2020 = Ajv2020Module.default;
+// `.default ?? module`, not a bare `.default`: NodeNext sees the raw CJS
+// `module.exports` and a bundler the unwrapped class. One shape for all of
+// them, so which modules a browser happens to reach is not a thing anyone has
+// to keep track of (#252).
+const ajv2020Module = Ajv2020Module;
+const Ajv2020 = ajv2020Module.default ?? ajv2020Module;
 const validateSchema = new Ajv2020({ allErrors: true }).compile(adapterMappingSchema);
 const mappingLocations = new WeakMap();
 export function loadAdapterMapping(source) {

package/dist/adapters/likec4-cli.js

@@ -23,6 +23,33 @@ const validateGeneratedProjectMarker = new Ajv2020({
 const validateGeneratedProjectV2Marker = new Ajv2020({
     allErrors: true,
 }).compile(generatedProjectV2Schema);
+// A marker written before 1.0 flattened subject ids records a comparison's
+// endpoints in the qualified `<document>#<local>` form, which `subjectIdentity`
+// no longer admits in either marker version. Such a marker is still one of
+// ours: those ids are recorded metadata, not addresses anything resolves, and
+// regeneration rewrites them flat. So it is accepted where an existing project
+// is read, exactly as a marker written before output digests existed is, and
+// the upgrade happens on the next write with nothing for the reader to do.
+// Each variant is derived from its own schema rather than copied, so a change
+// to either cannot leave its variant behind: only the one pattern is relaxed.
+const preFlattenSubjectIdentity = '^[a-z][a-z0-9]*(?:-[a-z0-9]+)*(?:#[a-z][a-z0-9]*(?:-[a-z0-9]+)*)?$';
+const preFlattenVariant = (schema) => ({
+    ...schema,
+    $id: `${schema.$id}/pre-flatten-subject-ids`,
+    $defs: {
+        ...schema.$defs,
+        subjectIdentity: {
+            ...schema.$defs.subjectIdentity,
+            pattern: preFlattenSubjectIdentity,
+        },
+    },
+});
+const validateGeneratedProjectPreFlattenMarker = new Ajv2020({
+    allErrors: true,
+}).compile(preFlattenVariant(generatedProjectSchema));
+const validateGeneratedProjectV2PreFlattenMarker = new Ajv2020({
+    allErrors: true,
+}).compile(preFlattenVariant(generatedProjectV2Schema));
 const generatedFileNames = [
     'likec4.config.json',
     'model.likec4',
@@ -199,12 +226,12 @@ const runLikeC4MapSync = (args, cwd) => {
         const additions = compilation.graph.subjects
             .filter(({ id }) => !mapped.has(id) && !architectureStates.has(id))
             .map((subject) => {
-            const [documentId, localId] = subject.id.split('#');
-            const local = lowerCamel(localId);
-            let external = local;
-            if (claimedExternal.has(external)) {
-                external = `${lowerCamel(documentId)}_${local}`;
-            }
+            // A subject id is the authored id, unique across the workspace, so it
+            // is the whole name. The document-prefixed fallback that used to break
+            // ties has nothing left to disambiguate; two ids can still collapse
+            // onto one camel-case name (`foo-bar` and `fooBar`), and the numeric
+            // suffix below has always been what separates those.
+            let external = lowerCamel(subject.id);
             let suffix = 2;
             const base = external;
             while (claimedExternal.has(external)) {
@@ -303,7 +330,9 @@ const readGeneratedProjectMarker = (markerPath) => {
         return undefined;
     }
     return validateGeneratedProjectMarker(marker) ||
-        validateGeneratedProjectV2Marker(marker)
+        validateGeneratedProjectV2Marker(marker) ||
+        validateGeneratedProjectPreFlattenMarker(marker) ||
+        validateGeneratedProjectV2PreFlattenMarker(marker)
         ? marker
         : undefined;
 };

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

@@ -27,13 +27,13 @@ export declare const visualFailureDiagnostics: (cause: unknown) => readonly Visu
  * removed. Absence alone is not evidence: the stopped marker is written before
  * teardown and names the vanished session directory.
  */
-export declare const visualSessionAlreadyStopped: (path: string, cwd?: string) => Promise<boolean>;
+export declare const visualSessionAlreadyStopped: (uri: string) => Promise<boolean>;
 /**
  * The agent's entry point into one live session, read the way a hostile file
  * has to be read. The descriptor is the only file carrying the agent
  * capability, so a redirected or planted one must never be spent.
  */
-export declare const readVisualSessionDescriptor: (path: string, cwd?: string) => Promise<ParseResult<VisualSessionDescriptor>>;
+export declare const readVisualSessionDescriptor: (uri: string) => Promise<ParseResult<VisualSessionDescriptor>>;
 /** One JSON document the agent hands to a command, read from the filesystem. */
 export declare const readVisualJsonDocument: (path: string, cwd?: string) => Promise<ParseResult<unknown>>;
 /**

package/dist/adapters/visual/client.js

@@ -1,7 +1,7 @@
 import { constants } from 'node:fs';
 import { lstat, open, readFile, stat } from 'node:fs/promises';
 import { basename, dirname, join, resolve } from 'node:path';
-import { VISUAL_PROTOCOL_VERSION, parseVisualDiagnosticResult, parseVisualEvent, parseVisualHandoff, parseVisualSessionDescriptor, parseVisualStatus, } from './protocol.js';
+import { VISUAL_PROTOCOL_VERSION, fromWireFileUri, parseVisualDiagnosticResult, parseVisualEvent, parseVisualHandoff, parseVisualSessionDescriptor, parseVisualStatus, toWireFileUri, } from './protocol.js';
 import { VISUAL_SERVER_LIMITS, } from './session-server.js';
 import { recoverVisualSession, removeVisualSession, visualSessionPaths, } from './session-store.js';
 /**
@@ -45,6 +45,33 @@ export const visualClientDiagnostic = (code, message, pointer = '/') => ({
     column: 1,
 });
 const refused = (diagnostics) => ({ ok: false, diagnostics });
+/**
+ * How each way a wire path can be refused reads. One code carries all three,
+ * the way `YMVS401` already covers two distinct underlying causes.
+ */
+const WIRE_URI_REFUSAL = {
+    malformed: 'is not a canonical file: URI',
+    nonlocal: 'names a nonlocal location',
+    noncanonical: 'is not the canonical encoding of its own target',
+};
+/**
+ * Decode one untrusted wire path to native, or refuse it.
+ *
+ * Nothing is resolved against `cwd`. A `file:` URI is inherently absolute, so
+ * the ambiguous, platform-dependent path string this representation retires
+ * cannot re-enter through the one argument an operator still passes by hand:
+ * `wait`/`respond`/`status`/`recover`/`stop` take the exact `descriptorPath`
+ * URI `start` published, copied back verbatim. A native path is refused here
+ * visibly rather than half-working.
+ */
+const decodeWireUri = (label, uri) => {
+    const decoded = fromWireFileUri(uri);
+    return decoded.ok
+        ? { ok: true, value: decoded.value }
+        : refused([
+            visualClientDiagnostic('YMVS414', `${label} "${uri}" ${WIRE_URI_REFUSAL[decoded.reason]}`),
+        ]);
+};
 export const visualFailureDiagnostics = (cause) => {
     const message = cause instanceof Error ? cause.message : String(cause);
     const named = STORE_FAILURE.exec(message);
@@ -111,8 +138,13 @@ const readsStoppedMarker = async (sessionRoot, sessionId) => {
  * removed. Absence alone is not evidence: the stopped marker is written before
  * teardown and names the vanished session directory.
  */
-export const visualSessionAlreadyStopped = async (path, cwd = process.cwd()) => {
-    const target = resolve(cwd, path);
+export const visualSessionAlreadyStopped = async (uri) => {
+    // A descriptor URI that will not decode names no session at all, so it is
+    // not evidence that one was stopped; the caller's own refusal stands.
+    const decoded = fromWireFileUri(uri);
+    if (!decoded.ok)
+        return false;
+    const target = decoded.value;
     const sessionRoot = dirname(target);
     const sessionId = basename(sessionRoot);
     return (basename(target) === 'descriptor.json' &&
@@ -125,8 +157,15 @@ export const visualSessionAlreadyStopped = async (path, cwd = process.cwd()) =>
  * has to be read. The descriptor is the only file carrying the agent
  * capability, so a redirected or planted one must never be spent.
  */
-export const readVisualSessionDescriptor = async (path, cwd = process.cwd()) => {
-    const target = resolve(cwd, path);
+export const readVisualSessionDescriptor = async (uri) => {
+    // The URI is proven to be one specific local file before that file is
+    // opened, and long before the capability inside it is spent. `target` is the
+    // native path `open()` needs; `uri` itself is already canonical past this
+    // point, so the ownership check below compares it directly.
+    const decoded = decodeWireUri('Session descriptor path', uri);
+    if (!decoded.ok)
+        return decoded;
+    const target = decoded.value;
     let raw;
     // One handle, opened once: the descriptor is the only file carrying the agent
     // capability, so the thing that is checked has to be the thing that is read.
@@ -171,17 +210,47 @@ export const readVisualSessionDescriptor = async (path, cwd = process.cwd()) =>
     const parsed = parseVisualSessionDescriptor(document);
     if (!parsed.ok)
         return parsed;
-    const paths = visualSessionPaths(parsed.value.sessionRoot);
+    // The document's own path fields are untrusted too, and are decoded on the
+    // same terms as the argument: `sessionRoot` because it is about to be used
+    // as a filesystem path, `journalPath` so a refusal names the field that was
+    // malformed rather than reporting it as a vaguer ownership mismatch.
+    const root = decodeWireUri('Session root', parsed.value.sessionRoot);
+    if (!root.ok)
+        return root;
+    const journal = decodeWireUri('Session journal path', parsed.value.journalPath);
+    if (!journal.ok)
+        return journal;
+    const paths = visualSessionPaths(root.value);
     // A descriptor authorises work on the session it lives in and no other: this
     // is the same invariant the runtime enforced when it published the file, so a
     // copied or planted descriptor cannot direct a stop at another directory.
-    if (paths.descriptor !== target || paths.journal !== parsed.value.journalPath) {
+    // Both sides of each compare are now canonical by construction, so a match
+    // proves the descriptor names the exact file that was opened rather than
+    // merely failing to disprove it.
+    if (toWireFileUri(paths.descriptor) !== uri ||
+        toWireFileUri(paths.journal) !== parsed.value.journalPath) {
         return refused([
             visualClientDiagnostic('YMVS403', `Session descriptor "${target}" names session artefacts outside its own directory`),
         ]);
     }
     return parsed;
 };
+/**
+ * The session directory a verified descriptor names.
+ *
+ * Every descriptor that reaches the commands below came through
+ * `readVisualSessionDescriptor`, which already proved `sessionRoot` decodes to
+ * one canonical local path. The only way this can fail is a caller that
+ * skipped that gate, which is a programming error rather than a protocol
+ * fault, so it throws where the surrounding refusals return.
+ */
+const sessionPathsOf = (descriptor) => {
+    const decoded = fromWireFileUri(descriptor.sessionRoot);
+    if (!decoded.ok) {
+        throw new Error(`Session root "${descriptor.sessionRoot}" was never decoded: ${decoded.reason}`);
+    }
+    return visualSessionPaths(decoded.value);
+};
 /** One JSON document the agent hands to a command, read from the filesystem. */
 export const readVisualJsonDocument = async (path, cwd = process.cwd()) => {
     const target = resolve(cwd, path);
@@ -330,7 +399,7 @@ export const sendVisualResponse = async (descriptor, response) => {
  * marker that is present and unusable is a fault the caller has to see.
  */
 const localVisualStatus = async (descriptor) => {
-    const paths = visualSessionPaths(descriptor.sessionRoot);
+    const paths = sessionPathsOf(descriptor);
     let lastSequence = 0;
     let transcriptBytes = 0;
     try {
@@ -389,7 +458,7 @@ export const recoverVisualSessionClient = async (descriptor, includeTranscript =
     try {
         return {
             ok: true,
-            value: await recoverVisualSession(visualSessionPaths(descriptor.sessionRoot), includeTranscript),
+            value: await recoverVisualSession(sessionPathsOf(descriptor), includeTranscript),
         };
     }
     catch (cause) {
@@ -424,7 +493,7 @@ const closedHandoff = (answer) => {
  * repeated stop idempotent.
  */
 export const stopVisualSessionClient = async (descriptor, includeTranscript = false) => {
-    const paths = visualSessionPaths(descriptor.sessionRoot);
+    const paths = sessionPathsOf(descriptor);
     if (!(await exists(paths.root)))
         return { ok: true, value: undefined };
     const recovered = await recoverVisualSessionClient(descriptor, includeTranscript);