@neoloopy/cld-canvas 0.1.4 → 0.1.7

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 neoloopy
+Copyright (c) 2026 Abraham Kim
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -472,21 +472,40 @@ import { buildMermaid, render } from "@neoloopy/cld-canvas";
 <sub>The same loop detection these helpers expose, surfaced in a neoloopy surface — a project-dynamics model with its reinforcing and balancing loops and the insight panel.</sub>
 
 ```ts
-import { LoopGraph, endogeneity } from "@neoloopy/cld-canvas";
+import { LoopGraph, discoverCanvasLoops, endogeneity } from "@neoloopy/cld-canvas";
 
 const loopGraph = new LoopGraph(graph.nodes);
-const loops = loopGraph.detectLoops();
+const qualitative = loopGraph.detectLoops();
+const { loops, analysisError } = discoverCanvasLoops(graph.nodes, qualitative, {
+  manifest: graph.manifest,
+});
 const metrics = loopGraph.metrics();
 const summary = endogeneity(graph.nodes, loops);
 ```
 
+`discoverCanvasLoops` first enriches each declared qualitative loop whose whole
+authored route resolves to exact visible connectors or material pipe legs, even
+when quantitative analysis is unavailable or incomplete. It adds a synthesized
+quantitative loop only when its complete executable route resolves just as
+exactly.
+Material endpoints may be explicit or use the unique, direct, signed legacy
+flow-to-stock encoding already supported by SFD rendering. It preserves
+qualitative loop identity and deduplicates exact counterparts. Quantitative
+discovery failures surface as `analysisError` and add no partial quantitative
+badge. A declared qualitative loop whose exact canvas route cannot be resolved
+keeps its established CLD identity and badge but is excluded from SFD; that
+qualitative exclusion by itself does not set `analysisError`. SFD retains every
+exactly resolved qualitative loop; a quantitative-only SFD badge additionally
+requires at least one first-class material leg.
+
 ## What is exported
 
 The package exports the public modules from `src/index.ts`, including:
 
 - Engine: `NativeEngine`, `NeoloopyEngine`, `MemoryStorage`, `VaultStorage`
 - Domain types: `VariableFile`, `VaultLink`, `ModelManifest`, `GraphView`
-- Graph logic: `LoopGraph`, `DetectedLoop`, `LoopType`, `labelLoopsByKey`
+- Graph logic: `LoopGraph`, `DetectedLoop`, `LoopType`, `labelLoopsByKey`,
+  `discoverCanvasLoops`
 - Rendering: `paint`, `SceneCache`, `Camera`, `LIGHT`, `DARK`, geometry helpers
 - File codecs: `parseNote`, `serializeNote`, `manifestFromJson`
 - Exporters: `render`, `buildMermaid`, `loopNoteKey`

package/dist/engine/engine.d.ts

@@ -34,6 +34,8 @@ export interface GraphView {
     /** loop.key -> "R1" / "B2" badge label. */
     labels: Map<string, string>;
     quant: boolean;
+    /** Non-null when quantitative canvas-loop discovery could not complete. */
+    analysisError?: string | null;
 }
 export interface NewVariable {
     label: string;
@@ -158,7 +160,17 @@ export interface NeoloopyEngine {
     setEquation(folder: string, id: string, patch: QuantPatch): Promise<VariableFile>;
     /** Cosmetic position change — never bumps rev/modified. */
     moveVariable(folder: string, id: string, x: number, y: number): Promise<void>;
+    /** Cosmetic SFD-view position change (`extra.sfd`) — never bumps rev/modified. */
+    moveVariableSfd(folder: string, id: string, x: number, y: number): Promise<void>;
+    /**
+     * If a model has no authored SFD coordinates, persist the deterministic SFD
+     * fallback positions into `extra.sfd` so the first manual SFD edit does not
+     * make the diagram jump back to CLD coordinates.
+     */
+    pinSfdLayout(folder: string): Promise<void>;
     removeVariable(folder: string, id: string): Promise<void>;
+    /** Validated SFD material topology write for a flow note (`extra.flow`). */
+    setFlowEndpoints(folder: string, flowId: string, from: string, to: string): Promise<void>;
     /**
      * Link (or clear, with `child=null`) a node's subsystem anchor — the same
      * `[[../<childDir>/System|<Child Name>]]` wikilink the app/CLI write, so the
@@ -177,10 +189,10 @@ export interface NeoloopyEngine {
     export(folder: string, format: ExportFormat): Promise<Rendered>;
     /**
      * Loop notes — one `Loops/<slug>.md` file per feedback loop, identity-anchored
-     * in frontmatter (the same files the Dart app/CLI write). Resolved into a map
-     * keyed by `<R|B>:<sorted unique variable names>` so both surfaces agree.
-     * `getLoopNotes` returns the body text per live loop; `setLoopNote` writes it
-     * into the identity-matched file (preserving title/valence/archetype).
+     * in frontmatter (the same files the Dart app/CLI write). Qualitative entries
+     * retain the established `<R|B>:<sorted unique variable names>` map key;
+     * quantitative-only entries use their exact directed `loop.key` so distinct
+     * routes cannot collide. `setLoopNote` accepts that one resolved key.
      */
     getLoopNotes(folder: string): Promise<Record<string, string>>;
     setLoopNote(folder: string, key: string, text: string): Promise<void>;

package/dist/engine/exporters.d.ts

@@ -16,7 +16,7 @@ export interface ExportEdge {
     id?: string;
     source: string;
     target: string;
-    polarity?: number;
+    polarity?: number | "?";
     delay?: boolean;
     curvature?: number;
     dashed?: boolean;

package/dist/engine/exporters.js

@@ -26,7 +26,7 @@ export function buildMermaid(nodes, edges) {
         const t = key.get(String(e.target));
         if (!s || !t)
             continue;
-        const sym = (e.polarity ?? 1) >= 0 ? "+" : "−";
+        const sym = e.polarity === "?" ? "?" : (e.polarity ?? 1) >= 0 ? "+" : "−";
         const arrow = e.delay === true ? "-.->" : "-->";
         lines.push(`  ${s} ${arrow}|${sym}| ${t}`);
     }

package/dist/engine/loopGraph.d.ts

@@ -23,9 +23,9 @@ export interface VarMetrics {
     loopCount: number;
 }
 /**
- * Deterministic loop labels: reinforcing -> R1,R2,… and balancing -> B1,B2,…,
- * ordered within each type by case-insensitive sorted variable names. Returns a
- * map from `DetectedLoop.key` to its label.
+ * Deterministic loop labels: reinforcing -> R1,R2,… and balancing -> B1,B2,….
+ * Existing qualitative loops keep their historical ordering and numbering;
+ * quantitative-only loops follow them in the same deterministic name order.
  */
 export declare function labelLoopsByKey(loops: DetectedLoop[], name: (id: string) => string): Map<string, string>;
 export declare class LoopGraph {
@@ -37,7 +37,11 @@ export declare class LoopGraph {
     adjacency(reverse?: boolean): Map<string, TracedEdge[]>;
     /** Direct (loop-relevant) adjacency: source -> [target, polaritySign]. */
     private directAdjacency;
-    /** All simple directed cycles, R/B classified, deduped to one per node-set. */
+    /**
+     * All simple directed cycles, R/B classified, deduped by the legacy node
+     * set. When distinct directed routes collapse to that compatibility key, the
+     * retained CLD loop is marked ambiguous so SFD resolution can fail closed.
+     */
     detectLoops(): DetectedLoop[];
     /**
      * The Shortest Independent Loop Set (SILS): the minimum-weight basis of the

package/dist/engine/loopKey.d.ts

@@ -1,3 +1,4 @@
+import { DetectedLoop } from "./types";
 /**
  * The resolved-map key for a feedback loop: `<R|B>:<sorted unique member
  * labels>`. This is the key every UI consumer indexes loop notes by; it is NOT
@@ -9,6 +10,14 @@
  * its own copy.
  */
 export declare function loopKey(labels: string[], type: string): string;
+/**
+ * The one UI/engine lookup key for a detected loop note. Existing qualitative
+ * loops, including a qualitative counterpart enriched with a quantitative
+ * canvas path, retain the sorted-label key shared with earlier releases.
+ * Quantitative-only loops use exact directed id identity so different routes
+ * through the same displayed members remain independent.
+ */
+export declare function resolvedLoopNoteKey(loop: DetectedLoop, nameOf: (id: string) => string): string;
 /**
  * Human-readable, non-link echo for a loop note's `loop:` frontmatter field:
  * `<R|B> · <sorted unique labels joined by " | ">`. Same membership rule as

package/dist/engine/loopKey.js

@@ -1,3 +1,4 @@
+import { LoopType } from "./types";
 /**
  * The resolved-map key for a feedback loop: `<R|B>:<sorted unique member
  * labels>`. This is the key every UI consumer indexes loop notes by; it is NOT
@@ -13,6 +14,19 @@ export function loopKey(labels, type) {
     const uniq = [...new Set(labels.map((l) => String(l)))].sort();
     return `${letter}:${uniq.join("|")}`;
 }
+/**
+ * The one UI/engine lookup key for a detected loop note. Existing qualitative
+ * loops, including a qualitative counterpart enriched with a quantitative
+ * canvas path, retain the sorted-label key shared with earlier releases.
+ * Quantitative-only loops use exact directed id identity so different routes
+ * through the same displayed members remain independent.
+ */
+export function resolvedLoopNoteKey(loop, nameOf) {
+    if (loop.identityMode === "quantitative")
+        return loop.exactKey;
+    const type = loop.type === LoopType.reinforcing ? "R" : "B";
+    return loopKey(loop.nodeIds.map(nameOf), type);
+}
 /**
  * Human-readable, non-link echo for a loop note's `loop:` frontmatter field:
  * `<R|B> · <sorted unique labels joined by " | ">`. Same membership rule as

package/dist/engine/nativeEngine.d.ts

@@ -85,13 +85,17 @@ export declare class NativeEngine implements NeoloopyEngine {
         name: string;
     } | null): Promise<void>;
     moveVariable(folder: string, id: string, x: number, y: number): Promise<void>;
+    moveVariableSfd(folder: string, id: string, x: number, y: number): Promise<void>;
+    pinSfdLayout(folder: string): Promise<void>;
     removeVariable(folder: string, id: string): Promise<void>;
+    setFlowEndpoints(folder: string, flowId: string, from: string, to: string): Promise<void>;
     addLink(folder: string, from: string, to: string, init?: LinkInit): Promise<void>;
     updateLink(folder: string, from: string, to: string, patch: LinkPatch): Promise<void>;
     removeLink(folder: string, from: string, to: string): Promise<void>;
     buildModel(folder: string, spec: BuildSpec): Promise<void>;
     relayout(folder: string): Promise<void>;
     setViewport(folder: string, viewport: Viewport): Promise<void>;
+    private liveLoopContext;
     getLoopNotes(folder: string): Promise<Record<string, string>>;
     setLoopNote(folder: string, key: string, text: string): Promise<void>;
     /**
@@ -112,6 +116,8 @@ export declare class NativeEngine implements NeoloopyEngine {
     /** Pre-`Nodes/` location of a variable note, flat at the model root. */
     private legacyNotePath;
     private readNote;
+    private removeNoteById;
+    private detachStockFlowEndpoints;
     private writeNote;
     private readManifest;
     private writeManifest;
@@ -136,13 +142,13 @@ export declare class NativeEngine implements NeoloopyEngine {
      * One-way, idempotent migration of legacy loop annotations from the
      * `model.json` maps into `Loops/*.md` files. Guard: if any `Loops/` file
      * exists the model is treated as migrated and this returns immediately. Each
-     * legacy key is matched to a live loop by its `loopKey`; a matched key keeps
+     * legacy key is matched to a live loop by its resolved note key; a match keeps
      * the loop's canonical member ids, an unmatched key becomes a pre-flagged
      * orphan (`members: []`, original key kept in `loop:`) so nothing is lost.
      * After writing, the four legacy keys are stripped from the manifest.
      */
     private migrateLoopNotesIfNeeded;
-    /** Find the live loop whose `loopKey` == `key`, then upsert its file. No-op
+    /** Find the live loop whose resolved note key == `key`, then upsert its file. No-op
      * (and no file) when the graph carries no such loop. */
     private upsertLoopFileByKey;
     /** Find-or-create the identity-matched `Loops/` file and apply `fields`

package/dist/engine/nativeEngine.js

@@ -21,20 +21,25 @@
  */
 import { emptyVariable, manifestFromJson, manifestToJson, normalizeBasis, normalizeConfidence, } from "./types";
 import { LoopGraph, labelLoopsByKey } from "./loopGraph";
+import { discoverCanvasLoops } from "./quantCanvasLoops";
 import { parseNote, serializeNote, splitFrontmatter } from "./noteCodec";
 import { noteSlug, noteUnslug } from "./noteNaming";
 import { canonicalLoopMembers, loopMatchesNote, loopSlug, parseLoopNote, serializeLoopNote, } from "./loopNote";
 import { contentSignature, stampMeta, WRITE_SOURCE_PLUGIN } from "./specHash";
-import { loopEchoLabel, loopKey } from "./loopKey";
+import { loopEchoLabel, resolvedLoopNoteKey } from "./loopKey";
 import { autoLayout } from "./layout";
 import { render, } from "./exporters";
 import { LoopType } from "./types";
 import { baseName, joinPath, parentPath, } from "./storage";
 import { deriveParentAnchors, linkPointsToModel, parseSubsystemLink, } from "./subsystemLinks";
 import { isPublicInput, isPublicOutput, } from "./publicInterface";
+import { SINK_CLOUD, SOURCE_CLOUD, extraWithFlow, extraWithSfdPosition, extraWithoutFlow, flowOf, hasAuthoredSfd, sfdPositionsFor, validateFlowEndpoints, } from "./sfd";
 /** Non-variable notes that share a model folder. */
 const SPECIAL_NOTES = new Set(["System.md", "Futures.md", "CLA.md"]);
 const MAX_SCAN_DEPTH = 12;
+function loopTypeLetter(loop) {
+    return loop.type === LoopType.reinforcing ? "R" : "B";
+}
 export class NativeEngine {
     constructor(storage, yaml, opts) {
         this.storage = storage;
@@ -70,10 +75,19 @@ export class NativeEngine {
         const manifest = await this.readManifest(folder);
         const nodes = await this.loadNotes(folder);
         const graph = new LoopGraph(nodes);
-        const loops = graph.detectLoops();
+        const discovered = discoverCanvasLoops(nodes, graph.detectLoops(), { manifest });
+        const loops = discovered.loops;
         const labels = labelLoopsByKey(loops, (id) => graph.node(id)?.label ?? id);
         const quant = manifestIsQuant(manifest) || nodes.some((n) => "quant" in n.extra);
-        return { folder, manifest, nodes, loops, labels, quant };
+        return {
+            folder,
+            manifest,
+            nodes,
+            loops,
+            labels,
+            quant,
+            analysisError: discovered.analysisError,
+        };
     }
     // ---- model lifecycle -----------------------------------------------------
     async createModel(name) {
@@ -306,7 +320,13 @@ export class NativeEngine {
             next.tags = [...patch.tags];
         if (patch.body !== undefined)
             next.body = patch.body;
+        if (patch.type !== undefined && patch.type !== "flow" && prev.type === "flow") {
+            next.extra = extraWithoutFlow(next.extra);
+        }
         const out = await this.writeNote(folder, prev, next);
+        if (prev.type === "stock" && patch.type !== undefined && patch.type !== "stock") {
+            await this.detachStockFlowEndpoints(folder, prev.id);
+        }
         await this.touchManifest(folder);
         return out;
     }
@@ -351,26 +371,94 @@ export class NativeEngine {
         // stampMeta treats an x/y-only change as cosmetic → rev/modified preserved.
         await this.writeNote(folder, prev, { ...prev, x, y });
     }
-    async removeVariable(folder, id) {
-        // The note is named by its label now, so resolve its real path by id; also
-        // clear any stale id-named copies (a legacy flat note or an old Nodes/<id>.md).
-        const resolved = (await this.noteFilesById(folder)).get(id);
-        if (resolved)
-            await this.storage.remove(resolved);
-        for (const p of [this.notePath(folder, id), this.legacyNotePath(folder, id)]) {
-            if (p !== resolved)
-                await this.storage.remove(p);
-        }
-        // Drop inbound links so loop detection and the manifest stay consistent.
+    async moveVariableSfd(folder, id, x, y) {
+        const prev = await this.readNote(folder, id);
+        await this.writeNote(folder, prev, {
+            ...prev,
+            extra: extraWithSfdPosition(prev.extra, x, y),
+        });
+    }
+    async pinSfdLayout(folder) {
         const notes = await this.loadNotes(folder);
+        if (hasAuthoredSfd(notes))
+            return;
+        const pos = sfdPositionsFor(notes);
         for (const n of notes) {
-            if (n.links.some((l) => l.to === id)) {
+            const p = pos.get(n.id);
+            if (p) {
                 await this.writeNote(folder, n, {
                     ...n,
-                    links: n.links.filter((l) => l.to !== id),
+                    extra: extraWithSfdPosition(n.extra, p.x, p.y),
                 });
             }
         }
+    }
+    async removeVariable(folder, id) {
+        const notes = await this.loadNotes(folder);
+        const removed = notes.find((n) => n.id === id);
+        const removeIds = new Set([id]);
+        if (removed?.type === "stock") {
+            for (const n of notes) {
+                if (n.type !== "flow" || n.id === id)
+                    continue;
+                const spec = flowOf(n);
+                if (!spec || (spec.from !== id && spec.to !== id))
+                    continue;
+                const from = spec.from === id ? SOURCE_CLOUD : spec.from;
+                const to = spec.to === id ? SINK_CLOUD : spec.to;
+                if (from === SOURCE_CLOUD && to === SINK_CLOUD)
+                    removeIds.add(n.id);
+            }
+        }
+        for (const rid of removeIds)
+            await this.removeNoteById(folder, rid);
+        // Drop inbound links to removed notes and recloud flow endpoints that touched
+        // a removed stock, so the SFD topology remains valid after deletion.
+        for (const n of notes) {
+            if (removeIds.has(n.id))
+                continue;
+            let changed = false;
+            const links = n.links.filter((l) => !removeIds.has(l.to));
+            let next = n;
+            if (links.length !== n.links.length) {
+                next = { ...next, links };
+                changed = true;
+            }
+            if (removed?.type === "stock" && n.type === "flow") {
+                const spec = flowOf(n);
+                if (spec && (spec.from === id || spec.to === id)) {
+                    next = {
+                        ...next,
+                        extra: extraWithFlow(next.extra, {
+                            from: spec.from === id ? SOURCE_CLOUD : spec.from,
+                            to: spec.to === id ? SINK_CLOUD : spec.to,
+                        }),
+                    };
+                    changed = true;
+                }
+            }
+            if (changed)
+                await this.writeNote(folder, n, next);
+        }
+        await this.touchManifest(folder);
+    }
+    async setFlowEndpoints(folder, flowId, from, to) {
+        const flow = await this.readNote(folder, flowId);
+        if (flow.type !== "flow")
+            throw new Error(`Flow endpoints apply to flow variables only: ${flow.label || flow.id}`);
+        const notes = await this.loadNotes(folder);
+        const byId = new Map(notes.map((n) => [n.id, n]));
+        const check = validateFlowEndpoints(from, to, byId);
+        if (!check.ok)
+            throw new Error(check.error);
+        const next = {
+            ...flow,
+            extra: extraWithFlow(flow.extra, { from, to }),
+            // Once the pipe is explicit, legacy flow->stock links become redundant
+            // material edges. Preserve all remaining information connectors.
+            links: flow.links.filter((l) => byId.get(l.to)?.type !== "stock"),
+        };
+        await this.writeNote(folder, flow, next);
         await this.touchManifest(folder);
     }
     // ---- links ---------------------------------------------------------------
@@ -446,8 +534,18 @@ export class NativeEngine {
     // filename or the labels. The legacy `model.json` maps (loopNotes/loopTitles/
     // loopValence/loopArchetypes) are auto-migrated to files on first touch. This
     // mirrors `core/lib/cli/vault_engine.dart` so the plugin and the app/CLI agree
-    // on one vault. Resolved maps stay keyed by the legacy `<R|B>:<sorted labels>`
-    // key (see `loopKey`) so existing UI consumers are unchanged.
+    // on one vault. Qualitative resolved maps retain the legacy sorted-label key;
+    // quantitative-only loops use their exact directed id so routes cannot fold.
+    async liveLoopContext(folder) {
+        const manifest = await this.readManifest(folder);
+        const nodes = await this.loadNotes(folder);
+        const graph = new LoopGraph(nodes);
+        const loops = discoverCanvasLoops(nodes, graph.detectLoops(), { manifest }).loops;
+        return {
+            loops,
+            nameOf: (id) => graph.node(id)?.label ?? id,
+        };
+    }
     async getLoopNotes(folder) {
         await this.migrateLoopNotesIfNeeded(folder);
         const files = await this.listLoopNoteFiles(folder);
@@ -461,12 +559,11 @@ export class NativeEngine {
             }
             return out;
         }
-        const graph = new LoopGraph(await this.loadNotes(folder));
-        const nameOf = (id) => graph.node(id)?.label ?? id;
+        const { loops, nameOf } = await this.liveLoopContext(folder);
         const out = {};
         const matched = new Set();
-        for (const l of graph.detectLoops()) {
-            const type = l.type === LoopType.reinforcing ? "R" : "B";
+        for (const l of loops) {
+            const type = loopTypeLetter(l);
             let note;
             for (const f of files) {
                 if (matched.has(f))
@@ -481,7 +578,7 @@ export class NativeEngine {
             if (!note)
                 continue;
             if (note.body.trim().length > 0) {
-                out[loopKey(l.nodeIds.map(nameOf), type)] = note.body;
+                out[resolvedLoopNoteKey(l, nameOf)] = note.body;
             }
         }
         return out;
@@ -497,23 +594,21 @@ export class NativeEngine {
      */
     async loopNotePath(folder, key) {
         await this.migrateLoopNotesIfNeeded(folder);
-        const graph = new LoopGraph(await this.loadNotes(folder));
-        const nameOf = (id) => graph.node(id)?.label ?? id;
-        for (const l of graph.detectLoops()) {
-            const type = l.type === LoopType.reinforcing ? "R" : "B";
-            const memberLabels = l.nodeIds.map(nameOf);
-            if (loopKey(memberLabels, type) !== key)
-                continue;
-            for (const f of await this.listLoopNoteFiles(folder)) {
-                const parsed = parseLoopNote((await this.readLoopNoteFile(folder, f)) ?? "", this.yaml);
-                if (loopMatchesNote(type, l.nodeIds, parsed)) {
-                    return joinPath(this.loopsDir(folder), f);
-                }
+        const { loops, nameOf } = await this.liveLoopContext(folder);
+        const matches = loops.filter((loop) => resolvedLoopNoteKey(loop, nameOf) === key);
+        if (matches.length !== 1)
+            return null;
+        const l = matches[0];
+        const type = loopTypeLetter(l);
+        const memberLabels = l.nodeIds.map(nameOf);
+        for (const f of await this.listLoopNoteFiles(folder)) {
+            const parsed = parseLoopNote((await this.readLoopNoteFile(folder, f)) ?? "", this.yaml);
+            if (loopMatchesNote(type, l.nodeIds, parsed)) {
+                return joinPath(this.loopsDir(folder), f);
             }
-            const file = await this.writeLoopFile(folder, l.nodeIds, type, memberLabels, {});
-            return joinPath(this.loopsDir(folder), file);
         }
-        return null;
+        const file = await this.writeLoopFile(folder, l.nodeIds, type, memberLabels, {});
+        return joinPath(this.loopsDir(folder), file);
     }
     async ensureSystemNote(folder) {
         const path = joinPath(folder, "System.md");
@@ -585,6 +680,45 @@ export class NativeEngine {
         const path = (await this.noteFilesById(folder)).get(id) ?? this.notePath(folder, id);
         return parseNote(await this.storage.read(path), this.yaml, id);
     }
+    async removeNoteById(folder, id) {
+        const resolved = (await this.noteFilesById(folder)).get(id);
+        if (resolved)
+            await this.storage.remove(resolved);
+        for (const p of [this.notePath(folder, id), this.legacyNotePath(folder, id)]) {
+            if (p !== resolved)
+                await this.storage.remove(p);
+        }
+    }
+    async detachStockFlowEndpoints(folder, stockId) {
+        const notes = await this.loadNotes(folder);
+        const removeIds = new Set();
+        for (const n of notes) {
+            if (n.type !== "flow")
+                continue;
+            const spec = flowOf(n);
+            if (!spec || (spec.from !== stockId && spec.to !== stockId))
+                continue;
+            const from = spec.from === stockId ? SOURCE_CLOUD : spec.from;
+            const to = spec.to === stockId ? SINK_CLOUD : spec.to;
+            if (from === SOURCE_CLOUD && to === SINK_CLOUD) {
+                removeIds.add(n.id);
+            }
+            else {
+                await this.writeNote(folder, n, { ...n, extra: extraWithFlow(n.extra, { from, to }) });
+            }
+        }
+        if (removeIds.size === 0)
+            return;
+        for (const id of removeIds)
+            await this.removeNoteById(folder, id);
+        for (const n of notes) {
+            if (removeIds.has(n.id))
+                continue;
+            const links = n.links.filter((l) => !removeIds.has(l.to));
+            if (links.length !== n.links.length)
+                await this.writeNote(folder, n, { ...n, links });
+        }
+    }
     async writeNote(folder, prev, next) {
         const stamped = stampMeta(prev, next, WRITE_SOURCE_PLUGIN);
         // The file is named after the label (so the vault reads like the diagram);
@@ -739,7 +873,7 @@ export class NativeEngine {
      * One-way, idempotent migration of legacy loop annotations from the
      * `model.json` maps into `Loops/*.md` files. Guard: if any `Loops/` file
      * exists the model is treated as migrated and this returns immediately. Each
-     * legacy key is matched to a live loop by its `loopKey`; a matched key keeps
+     * legacy key is matched to a live loop by its resolved note key; a match keeps
      * the loop's canonical member ids, an unmatched key becomes a pre-flagged
      * orphan (`members: []`, original key kept in `loop:`) so nothing is lost.
      * After writing, the four legacy keys are stripped from the manifest.
@@ -771,16 +905,15 @@ export class NativeEngine {
             ...Object.keys(valence),
             ...Object.keys(archetypes),
         ]);
-        const graph = new LoopGraph(await this.loadNotes(folder));
-        const nameOf = (id) => graph.node(id)?.label ?? id;
+        const { loops, nameOf } = await this.liveLoopContext(folder);
         const liveByKey = new Map();
-        for (const l of graph.detectLoops()) {
-            const type = l.type === LoopType.reinforcing ? "R" : "B";
-            liveByKey.set(loopKey(l.nodeIds.map(nameOf), type), l);
+        for (const l of loops) {
+            const key = resolvedLoopNoteKey(l, nameOf);
+            liveByKey.set(key, liveByKey.has(key) ? null : l);
         }
         for (const key of allKeys) {
             const type = key.startsWith("B") ? "B" : "R";
-            const live = liveByKey.get(key);
+            const live = liveByKey.get(key) ?? undefined;
             const members = live ? canonicalLoopMembers(live.nodeIds) : [];
             const labels = live
                 ? live.nodeIds.map(nameOf)
@@ -810,20 +943,16 @@ export class NativeEngine {
             modified: new Date().toISOString(),
         });
     }
-    /** Find the live loop whose `loopKey` == `key`, then upsert its file. No-op
+    /** Find the live loop whose resolved note key == `key`, then upsert its file. No-op
      * (and no file) when the graph carries no such loop. */
     async upsertLoopFileByKey(folder, key, fields) {
         await this.migrateLoopNotesIfNeeded(folder);
-        const graph = new LoopGraph(await this.loadNotes(folder));
-        const nameOf = (id) => graph.node(id)?.label ?? id;
-        for (const l of graph.detectLoops()) {
-            const type = l.type === LoopType.reinforcing ? "R" : "B";
-            const memberLabels = l.nodeIds.map(nameOf);
-            if (loopKey(memberLabels, type) !== key)
-                continue;
-            await this.writeLoopFile(folder, l.nodeIds, type, memberLabels, fields);
+        const { loops, nameOf } = await this.liveLoopContext(folder);
+        const matches = loops.filter((loop) => resolvedLoopNoteKey(loop, nameOf) === key);
+        if (matches.length !== 1)
             return;
-        }
+        const loop = matches[0];
+        await this.writeLoopFile(folder, loop.nodeIds, loopTypeLetter(loop), loop.nodeIds.map(nameOf), fields);
     }
     /** Find-or-create the identity-matched `Loops/` file and apply `fields`
      * (undefined leaves a field unchanged; `archetype: ""` clears it). Returns the
@@ -1007,10 +1136,18 @@ export class NativeEngine {
 // ---- pure helpers ----------------------------------------------------------
 /** A copy of `v` with its id and every link target re-pointed through `idMap`. */
 function remapVariableIds(v, idMap) {
+    const flow = flowOf(v);
+    const extra = flow
+        ? extraWithFlow(v.extra, {
+            from: idMap.get(flow.from) ?? flow.from,
+            to: idMap.get(flow.to) ?? flow.to,
+        })
+        : v.extra;
     return {
         ...v,
         id: idMap.get(v.id) ?? v.id,
         links: v.links.map((l) => ({ ...l, to: idMap.get(l.to) ?? l.to })),
+        extra,
     };
 }
 function makeLink(to, init) {
@@ -1074,7 +1211,7 @@ function toExportGraph(view) {
                 id: `${n.id}__${l.to}`,
                 source: n.id,
                 target: l.to,
-                polarity: l.polarity === "-" ? -1 : 1,
+                polarity: l.polarity === "-" ? -1 : l.polarity === "+" ? 1 : "?",
                 delay: l.delay,
                 curvature: l.curvature,
                 dashed: l.indirect,