@neoloopy/cld-canvas 0.1.3 → 0.1.7

package/dist/engine/nativeEngine.js

@@ -21,19 +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 } from "./subsystemLinks";
+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;
@@ -69,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) {
@@ -305,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;
     }
@@ -350,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 ---------------------------------------------------------------
@@ -445,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);
@@ -460,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))
@@ -480,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;
@@ -496,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");
@@ -532,6 +628,33 @@ export class NativeEngine {
             return [];
         return deriveParentAnchors({ folder: current.folder, name: current.name }, models.filter((m) => m.folder !== folder).map((m) => ({ folder: m.folder, name: m.name })), (f) => this.loadNotes(f));
     }
+    async childInterface(folder, varId) {
+        const nodes = await this.loadNotes(folder);
+        const anchor = nodes.find((n) => n.id === varId);
+        const raw = (anchor?.subsystem ?? "").trim();
+        if (!raw)
+            return null;
+        const { alias } = parseSubsystemLink(raw);
+        const models = await this.listModels();
+        const match = models.find((m) => linkPointsToModel(raw, { folder: m.folder, name: m.name }));
+        if (!match)
+            return null;
+        try {
+            const childNodes = await this.loadNotes(match.folder);
+            const outputs = [];
+            const inputs = [];
+            for (const v of childNodes) {
+                if (isPublicOutput(v))
+                    outputs.push(v.label || v.id);
+                if (isPublicInput(v))
+                    inputs.push(v.label || v.id);
+            }
+            return { qualifier: alias ?? match.name, outputs, inputs };
+        }
+        catch {
+            return null;
+        }
+    }
     // ---- export --------------------------------------------------------------
     async export(folder, format) {
         const view = await this.loadGraph(folder);
@@ -557,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);
@@ -711,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.
@@ -743,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)
@@ -782,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
@@ -979,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) {
@@ -1046,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,
@@ -1091,18 +1256,11 @@ function slug(s) {
 }
 function randomHex(bytes) {
     const arr = new Uint8Array(bytes);
-    // Web Crypto is exposed as the global `crypto` in both Obsidian (Electron)
-    // and Node (this pure engine's vitest tests). Referenced bare — not via
-    // `window`/`globalThis` — so it resolves under Node too; `typeof`-guarded so
-    // it falls back to Math.random anywhere it is unavailable.
     const c = typeof crypto !== "undefined" ? crypto : undefined;
-    if (c && typeof c.getRandomValues === "function") {
-        c.getRandomValues(arr);
-    }
-    else {
-        for (let i = 0; i < bytes; i++)
-            arr[i] = Math.floor(Math.random() * 256);
+    if (!c || typeof c.getRandomValues !== "function") {
+        throw new Error("Web Crypto is required to generate neoloopy ids.");
     }
+    c.getRandomValues(arr);
     let s = "";
     for (const b of arr)
         s += b.toString(16).padStart(2, "0");
@@ -1112,9 +1270,7 @@ function genVarId() {
     return `var_${randomHex(4)}`;
 }
 function genModelId() {
-    const n = Date.now() * 1000 + Math.floor(Math.random() * 1000);
-    const hex = n.toString(16);
-    return `mdl_${hex.slice(-6)}`;
+    return `mdl_${randomHex(4)}`;
 }
 /** Re-export so callers don't need a second import for the signature helper. */
 export { contentSignature };

package/dist/engine/noteCodec.js

@@ -79,10 +79,18 @@ function tagsFrom(v) {
 function rawScalar(frontmatter, key) {
     if (frontmatter === null)
         return undefined;
-    const m = new RegExp(`^${key}:[ \\t]*(.+?)[ \\t]*$`, "m").exec(frontmatter);
-    if (!m)
+    let s;
+    for (const line of frontmatter.split("\n")) {
+        const colon = line.indexOf(":");
+        if (colon < 0)
+            continue;
+        if (line.slice(0, colon).trim() !== key)
+            continue;
+        s = line.slice(colon + 1).trim();
+        break;
+    }
+    if (s === undefined)
         return undefined;
-    let s = m[1];
     if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
         s = s.slice(1, -1);
     }
@@ -198,6 +206,44 @@ export function emitExtra(lines, key, value, indent) {
         lines.push(`${pad}${key}: ${scalar(value)}`);
     }
 }
+function emitFlowExtra(lines, value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        emitExtra(lines, "flow", value, 0);
+        return;
+    }
+    const m = value;
+    lines.push("flow:");
+    if (m["from"] !== undefined)
+        lines.push(`  from: ${scalar(m["from"])}`);
+    if (m["to"] !== undefined)
+        lines.push(`  to: ${scalar(m["to"])}`);
+    for (const [k, v] of Object.entries(m)) {
+        if (k === "from" || k === "to")
+            continue;
+        emitExtra(lines, k, v, 1);
+    }
+}
+function emitSfdExtra(lines, value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        emitExtra(lines, "sfd", value, 0);
+        return;
+    }
+    const m = value;
+    lines.push("sfd:");
+    if (m["x"] !== undefined) {
+        const x = m["x"];
+        lines.push(`  x: ${typeof x === "number" ? numToYaml(x) : scalar(x)}`);
+    }
+    if (m["y"] !== undefined) {
+        const y = m["y"];
+        lines.push(`  y: ${typeof y === "number" ? numToYaml(y) : scalar(y)}`);
+    }
+    for (const [k, v] of Object.entries(m)) {
+        if (k === "x" || k === "y")
+            continue;
+        emitExtra(lines, k, v, 1);
+    }
+}
 export function serializeNote(v) {
     const lines = [FENCE];
     lines.push(`id: ${scalar(v.id)}`);
@@ -244,8 +290,14 @@ export function serializeNote(v) {
             }
         }
     }
-    for (const [k, val] of Object.entries(v.extra))
-        emitExtra(lines, k, val, 0);
+    for (const [k, val] of Object.entries(v.extra)) {
+        if (k === "flow")
+            emitFlowExtra(lines, val);
+        else if (k === "sfd")
+            emitSfdExtra(lines, val);
+        else
+            emitExtra(lines, k, val, 0);
+    }
     lines.push(FENCE);
     let out = lines.join("\n") + "\n";
     if (v.body.trim().length > 0)

package/dist/engine/publicInterface.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Public-interface readers — the TypeScript mirror of the READ side of
+ * `core/lib/quant/public_interface.dart`. In a subsystem-composed model a
+ * variable is exposed to its parent by tagging it under `extra.quant.visibility`
+ * (`'input'` | `'output'`; absent ⇒ private); a parent drives a child's public
+ * input via `inputBindings` declared on the anchor node (the node carrying the
+ * `subsystem` link). The qualitative plugin only READS these — publishing and
+ * binding are quant authoring, which lives in the app/CLI/MCP. Both fields are
+ * preserved verbatim on write (unknown-key carry, format rule §3), so reading
+ * them never risks the data.
+ */
+import { VariableFile } from "./types";
+export type Visibility = "input" | "output";
+/** `'input'` | `'output'` | `null` (private — the default). */
+export declare function quantVisibility(v: VariableFile): Visibility | null;
+export declare function isPublicInput(v: VariableFile): boolean;
+export declare function isPublicOutput(v: VariableFile): boolean;
+/** A parent-side wiring that drives a linked child's public input. */
+export interface InputBinding {
+    /** Qualifier of the linked child (link alias or model name). */
+    child: string;
+    /** Child public-input label or id. */
+    target: string;
+    /** Parent-scope expression that drives the input. */
+    expr: string;
+}
+/** Input bindings declared on this anchor node (empty when none). */
+export declare function quantInputBindings(v: VariableFile): InputBinding[];
+/** A child model's public interface as resolved through a parent's subsystem link. */
+export interface ChildInterface {
+    /** Display qualifier — the link alias, else the child model name. */
+    qualifier: string;
+    /** Labels of the child's public outputs (offered to the parent). */
+    outputs: string[];
+    /** Labels of the child's public inputs (the parent may drive). */
+    inputs: string[];
+}
+/**
+ * A child output as a qualified reference: bracket form when the label has a
+ * space (`ReworkCycle.[Defect Rate]`), bare otherwise. Mirrors the app's `_ref`
+ * in `subsystem_interface_section.dart`.
+ */
+export declare function qualifiedRef(qualifier: string, label: string): string;

package/dist/engine/publicInterface.js

@@ -0,0 +1,52 @@
+/**
+ * Public-interface readers — the TypeScript mirror of the READ side of
+ * `core/lib/quant/public_interface.dart`. In a subsystem-composed model a
+ * variable is exposed to its parent by tagging it under `extra.quant.visibility`
+ * (`'input'` | `'output'`; absent ⇒ private); a parent drives a child's public
+ * input via `inputBindings` declared on the anchor node (the node carrying the
+ * `subsystem` link). The qualitative plugin only READS these — publishing and
+ * binding are quant authoring, which lives in the app/CLI/MCP. Both fields are
+ * preserved verbatim on write (unknown-key carry, format rule §3), so reading
+ * them never risks the data.
+ */
+function quantBlock(v) {
+    const q = v.extra["quant"];
+    return q && typeof q === "object" ? q : {};
+}
+/** `'input'` | `'output'` | `null` (private — the default). */
+export function quantVisibility(v) {
+    const s = String(quantBlock(v)["visibility"] ?? "").trim();
+    return s === "input" || s === "output" ? s : null;
+}
+export function isPublicInput(v) {
+    return quantVisibility(v) === "input";
+}
+export function isPublicOutput(v) {
+    return quantVisibility(v) === "output";
+}
+/** Input bindings declared on this anchor node (empty when none). */
+export function quantInputBindings(v) {
+    const raw = quantBlock(v)["inputBindings"];
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const e of raw) {
+        if (e && typeof e === "object") {
+            const m = e;
+            out.push({
+                child: String(m["child"] ?? ""),
+                target: String(m["target"] ?? ""),
+                expr: String(m["expr"] ?? ""),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * A child output as a qualified reference: bracket form when the label has a
+ * space (`ReworkCycle.[Defect Rate]`), bare otherwise. Mirrors the app's `_ref`
+ * in `subsystem_interface_section.dart`.
+ */
+export function qualifiedRef(qualifier, label) {
+    return `${qualifier}.${label.includes(" ") ? `[${label}]` : label}`;
+}

package/dist/engine/quantCanvasLoops.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Conservative, renderer-facing resolution of qualitative and quantitative loops.
+ *
+ * This is deliberately not a simulation or dominance implementation. It only
+ * enriches a declared qualitative cycle independently when every authored leg
+ * maps to one exact visible connector or material pipe. It admits a synthesized
+ * static scalar cycle only when every equation dependency and material effect
+ * is equally exact. Incomplete quantitative analysis returns no synthesized
+ * prefix but never strips an independently resolved qualitative path.
+ */
+import { DetectedLoop, ModelManifest, VariableFile } from "./types";
+export interface CanvasLoopDiscoveryLimits {
+    readonly maxLoops: number;
+    readonly maxEdgeVisits: number;
+    readonly maxDepth: number;
+}
+export declare const USER_FACING_CANVAS_LOOP_LIMITS: CanvasLoopDiscoveryLimits;
+export interface CanvasLoopDiscoveryOptions {
+    readonly manifest?: ModelManifest;
+    readonly limits?: CanvasLoopDiscoveryLimits;
+}
+export interface CanvasLoopDiscoveryResult {
+    readonly loops: DetectedLoop[];
+    readonly analysisError: string | null;
+}
+/** Stable first-class SFD pipe-leg identity. */
+export declare function materialPipeLegId(flowId: string, stockId: string): string;
+/** Stable base id for a non-persistent CLD projection of a material effect. */
+export declare function materialProjectionEdgeId(flowId: string, stockId: string): string;
+/**
+ * Discover complete canvas-resolvable quantitative cycles and merge them with
+ * exact qualitative counterparts. Declared loops are first resolved from their
+ * own authored topology, so a quantitative error never suppresses their honest
+ * CLD/SFD representation.
+ */
+export declare function discoverCanvasLoops(nodes: readonly VariableFile[], qualitativeLoops: readonly DetectedLoop[], options?: CanvasLoopDiscoveryOptions): CanvasLoopDiscoveryResult;