@neoloopy/cld-canvas 0.1.0

package/dist/engine/analysis.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Pure graph-analysis helpers for the insight panel — no DOM, no I/O.
+ *
+ * - `endogeneity` mirrors the app's `CanvasController.endogeneity()` (keyed by
+ *   variable id): how much of the system sits inside feedback vs. drives it from
+ *   outside.
+ */
+import { DetectedLoop, VariableFile } from "./types";
+export interface EndogeneityResult {
+    total: number;
+    inLoop: number;
+    exogenous: string[];
+    openLoop: string[];
+}
+export declare function endogeneity(nodes: VariableFile[], loops: DetectedLoop[]): EndogeneityResult;

package/dist/engine/analysis.js

@@ -0,0 +1,30 @@
+/**
+ * Pure graph-analysis helpers for the insight panel — no DOM, no I/O.
+ *
+ * - `endogeneity` mirrors the app's `CanvasController.endogeneity()` (keyed by
+ *   variable id): how much of the system sits inside feedback vs. drives it from
+ *   outside.
+ */
+export function endogeneity(nodes, loops) {
+    const ids = new Set(nodes.map((n) => n.id));
+    const inLoop = new Set();
+    for (const l of loops)
+        for (const id of l.nodeIds)
+            inLoop.add(id);
+    const sources = new Set();
+    const targets = new Set();
+    for (const n of nodes) {
+        for (const lk of n.links) {
+            if (!ids.has(lk.to))
+                continue;
+            sources.add(n.id);
+            targets.add(lk.to);
+        }
+    }
+    return {
+        total: nodes.length,
+        inLoop: nodes.filter((n) => inLoop.has(n.id)).length,
+        exogenous: nodes.filter((n) => !targets.has(n.id) && sources.has(n.id)).map((n) => n.id),
+        openLoop: nodes.filter((n) => !inLoop.has(n.id)).map((n) => n.id),
+    };
+}

package/dist/engine/engine.d.ts

@@ -0,0 +1,203 @@
+/**
+ * The engine seam. Everything UI-facing talks to a `NeoloopyEngine`; the sole
+ * implementation is `NativeEngine` (pure TypeScript, runs on every platform
+ * including mobile, no binary, no network). The interface is kept narrow so the
+ * view and tests can depend on it (and mock it) without touching internals.
+ */
+import { DetectedLoop, ModelManifest, VarType, VariableFile, Viewport } from "./types";
+import { Rendered } from "./exporters";
+import { ParentAnchor } from "./subsystemLinks";
+/** Lightweight model descriptor for pickers/lists (no notes loaded). */
+export interface ModelRef {
+    id: string;
+    name: string;
+    /** Vault-relative folder path that holds `model.json` + the notes. */
+    folder: string;
+    /**
+     * Organizational grouping label (the `model.json` `folder` field, set via
+     * `set-folder`) — NOT the directory path above. Null/empty when ungrouped.
+     * The picker groups by this, mirroring the app's folder-grouped models screen.
+     */
+    group: string | null;
+    modified: string;
+    variableCount: number;
+    /** Carries quantitative data — read-only in this qualitative engine. */
+    quant: boolean;
+}
+/** A fully loaded model plus its detected loops and labels. */
+export interface GraphView {
+    folder: string;
+    manifest: ModelManifest;
+    nodes: VariableFile[];
+    loops: DetectedLoop[];
+    /** loop.key -> "R1" / "B2" badge label. */
+    labels: Map<string, string>;
+    quant: boolean;
+}
+export interface NewVariable {
+    label: string;
+    type?: VarType;
+    x?: number;
+    y?: number;
+    group?: string;
+    shared?: string;
+    claLayer?: string;
+}
+/**
+ * Partial update for a variable. A field left `undefined` is untouched; an
+ * explicit `null` on a nullable field clears it.
+ */
+export interface VariablePatch {
+    label?: string;
+    type?: VarType;
+    group?: string | null;
+    shared?: string | null;
+    claLayer?: string | null;
+    status?: string | null;
+    tags?: string[];
+    body?: string;
+}
+/**
+ * A partial edit to a variable's quantitative definition (`extra.quant`). A
+ * field left `undefined` is untouched; an empty string clears that field. When
+ * the block ends up empty it is dropped so plain notes stay clean.
+ */
+export interface QuantPatch {
+    equation?: string;
+    initial?: string;
+    units?: string;
+}
+export interface LinkInit {
+    polarity?: "+" | "-";
+    delay?: boolean;
+    indirect?: boolean;
+    nonlinear?: boolean;
+    weight?: number;
+    curvature?: number;
+    confidence?: number;
+    basis?: string;
+}
+/** Like `LinkInit`, but `curvature: null` explicitly clears it (auto-bow). */
+export interface LinkPatch {
+    polarity?: "+" | "-";
+    delay?: boolean;
+    indirect?: boolean;
+    nonlinear?: boolean;
+    weight?: number;
+    curvature?: number | null;
+    confidence?: number;
+    basis?: string;
+}
+export interface BuildSpec {
+    variables: Array<{
+        id?: string;
+        label: string;
+        type?: VarType;
+        group?: string;
+        shared?: string;
+    }>;
+    /** `from`/`to` may be a variable label or id (labels resolved first). */
+    links: Array<{
+        from: string;
+        to: string;
+    } & LinkInit>;
+    /** Auto-layout positions after building (default true). */
+    layout?: boolean;
+}
+export type ExportFormat = "json" | "mermaid" | "markdown";
+export interface NeoloopyEngine {
+    listModels(): Promise<ModelRef[]>;
+    createModel(name: string): Promise<ModelRef>;
+    /**
+     * Rename a model from the canvas (title is canonical): set the `model.json`
+     * `name` AND re-slug + move the folder to match, suffixing `-2/-3…` on
+     * collision. The move is link-aware so wikilinks and subsystem anchors follow.
+     * Skips the move when the slug is unchanged. Rejects a blank title.
+     */
+    renameModel(folder: string, name: string): Promise<ModelRef>;
+    /**
+     * The inverse of renameModel for an *external* folder rename (folder is
+     * canonical): set the `model.json` `name` to the new folder name IN PLACE,
+     * without re-slugging or moving the directory. Rejects a blank title.
+     */
+    retitleModel(folder: string, name: string): Promise<ModelRef>;
+    /**
+     * The node-level inverse of retitleModel: after the user renames a variable
+     * note in the vault (`Nodes/<stem>.md`), set its label to the de-slugged
+     * stem. The stable `var_…` id and inbound links are untouched. No-op when the
+     * file is gone or the label already matches.
+     */
+    relabelNodeFromFilename(folder: string, fileStem: string): Promise<void>;
+    deleteModel(folder: string): Promise<void>;
+    /**
+     * Duplicate a model as a NEW model with fresh ids (model + every variable,
+     * plus re-pointed loop-note members and System anchor). `shared` keys are
+     * preserved so the copy stays in the cross-model graph. Lands as a sibling of
+     * the source, titled "<name> (copy)". Returns the copy's ref.
+     */
+    duplicateModel(srcFolder: string): Promise<ModelRef>;
+    /**
+     * Re-key models that share an id (a raw Obsidian copy clones ids verbatim):
+     * keep the oldest, re-key every newer sibling. Returns one row per re-keyed
+     * folder; empty when all ids are already unique.
+     */
+    healDuplicateIds(): Promise<Array<{
+        folder: string;
+        oldId: string;
+        newId: string;
+    }>>;
+    loadGraph(folder: string): Promise<GraphView>;
+    addVariable(folder: string, init: NewVariable): Promise<VariableFile>;
+    updateVariable(folder: string, id: string, patch: VariablePatch): Promise<VariableFile>;
+    /**
+     * Edit a variable's quantitative definition (`extra.quant`): equation,
+     * initial value, and/or units. Merges into any existing block, preserving
+     * keys it does not manage (e.g. a subscript dimension).
+     */
+    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>;
+    removeVariable(folder: string, id: 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
+     * drill-in mark round-trips across all surfaces.
+     */
+    setSubsystem(folder: string, varId: string, child: {
+        folder: string;
+        name: string;
+    } | null): 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>;
+    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).
+     */
+    getLoopNotes(folder: string): Promise<Record<string, string>>;
+    setLoopNote(folder: string, key: string, text: string): Promise<void>;
+    /**
+     * Vault-relative path of the canonical `Loops/*.md` file for `key`, creating
+     * an empty anchored note if none exists. Null when no live loop carries that
+     * key. The canvas opens this file directly for editing.
+     */
+    loopNotePath(folder: string, key: string): Promise<string | null>;
+    /**
+     * Ensure the model has a `System.md`, creating a minimal valid one (frontmatter
+     * `model: "<id>"`) when absent. Returns its vault-relative path. The canvas
+     * opens this file directly.
+     */
+    ensureSystemNote(folder: string): Promise<string>;
+    /**
+     * Parent systems of `folder` — models whose nodes anchor it as a subsystem.
+     * Each anchor names the parent model + the linking variable. Empty when none.
+     */
+    deriveParents(folder: string): Promise<ParentAnchor[]>;
+}

package/dist/engine/engine.js

@@ -0,0 +1,7 @@
+/**
+ * The engine seam. Everything UI-facing talks to a `NeoloopyEngine`; the sole
+ * implementation is `NativeEngine` (pure TypeScript, runs on every platform
+ * including mobile, no binary, no network). The interface is kept narrow so the
+ * view and tests can depend on it (and mock it) without touching internals.
+ */
+export {};

package/dist/engine/exporters.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Export renderers — TypeScript port of the qualitative subset of
+ * `core/lib/cli/formats.dart` (`buildMermaid`, `loopNoteKey`, and `render` for
+ * json | markdown | mermaid). SVG and Cypher are intentionally out of v1 scope.
+ * Operates on plain node/edge/loop records so it stays storage-agnostic.
+ */
+export interface ExportNode {
+    id: string;
+    name: string;
+    kind?: string;
+    x?: number;
+    y?: number;
+    group?: string;
+}
+export interface ExportEdge {
+    id?: string;
+    source: string;
+    target: string;
+    polarity?: number;
+    delay?: boolean;
+    curvature?: number;
+    dashed?: boolean;
+    weight?: number;
+}
+export interface ExportLoop {
+    loop: string[];
+    type: string;
+    label?: string;
+}
+export interface Rendered {
+    content: string;
+    mime: string;
+    ext: string;
+}
+export interface RenderOpts {
+    notes?: Record<string, string>;
+    valence?: Record<string, string>;
+    titles?: Record<string, string>;
+    hypothesis?: Record<string, unknown>;
+}
+/** Stable identity for a loop's note: `<R|B>:<sorted unique variable names>`. */
+export declare function loopNoteKey(loop: string[], typeStr: string): string;
+export declare function buildMermaid(nodes: ExportNode[], edges: ExportEdge[]): string;
+/** Render a model in json | mermaid | markdown. */
+export declare function render(fmt: string, modelId: string, name: string, nodes: ExportNode[], edges: ExportEdge[], loops: ExportLoop[], opts?: RenderOpts): Rendered;

package/dist/engine/exporters.js

@@ -0,0 +1,110 @@
+/**
+ * Export renderers — TypeScript port of the qualitative subset of
+ * `core/lib/cli/formats.dart` (`buildMermaid`, `loopNoteKey`, and `render` for
+ * json | markdown | mermaid). SVG and Cypher are intentionally out of v1 scope.
+ * Operates on plain node/edge/loop records so it stays storage-agnostic.
+ */
+/** Stable identity for a loop's note: `<R|B>:<sorted unique variable names>`. */
+export function loopNoteKey(loop, typeStr) {
+    const core = loop.length > 1 && loop.length > 0 && loop[0] === loop[loop.length - 1]
+        ? loop.slice(0, loop.length - 1)
+        : loop;
+    const letter = typeStr.toUpperCase().startsWith("R") ? "R" : "B";
+    const uniq = [...new Set(core.map(String))].sort();
+    return `${letter}:${uniq.join("|")}`;
+}
+export function buildMermaid(nodes, edges) {
+    const key = new Map();
+    nodes.forEach((n, i) => key.set(String(n.id), `v${i}`));
+    const lines = ["graph LR"];
+    for (const n of nodes) {
+        const label = n.name.replace(/"/g, "'");
+        lines.push(`  ${key.get(String(n.id))}["${label}"]`);
+    }
+    for (const e of edges) {
+        const s = key.get(String(e.source));
+        const t = key.get(String(e.target));
+        if (!s || !t)
+            continue;
+        const sym = (e.polarity ?? 1) >= 0 ? "+" : "−";
+        const arrow = e.delay === true ? "-.->" : "-->";
+        lines.push(`  ${s} ${arrow}|${sym}| ${t}`);
+    }
+    return lines.join("\n");
+}
+function loopJson(l, titles, valence, notes) {
+    const key = loopNoteKey(l.loop, l.type);
+    const out = { ...l };
+    if (titles[key] !== undefined)
+        out["title"] = titles[key];
+    if (valence[key] !== undefined)
+        out["valence"] = valence[key];
+    if (notes[key] !== undefined)
+        out["note"] = notes[key];
+    return out;
+}
+/** Render a model in json | mermaid | markdown. */
+export function render(fmt, modelId, name, nodes, edges, loops, opts = {}) {
+    fmt = fmt.toLowerCase();
+    const notes = opts.notes ?? {};
+    const valence = opts.valence ?? {};
+    const titles = opts.titles ?? {};
+    if (fmt === "json") {
+        const loopsOut = loops.map((l) => loopJson(l, titles, valence, notes));
+        const payload = {
+            model: { id: modelId, name },
+        };
+        if (opts.hypothesis)
+            payload["dynamic_hypothesis"] = opts.hypothesis;
+        payload["graph"] = { nodes, edges };
+        payload["loops"] = loopsOut;
+        return { content: JSON.stringify(payload, null, 2), mime: "application/json", ext: "json" };
+    }
+    const mermaid = buildMermaid(nodes, edges);
+    if (fmt === "mermaid")
+        return { content: mermaid, mime: "text/plain", ext: "mmd" };
+    // Markdown
+    const md = [`# ${name}`, ""];
+    if (opts.hypothesis) {
+        const h = opts.hypothesis;
+        const problem = String(h["problem"] ?? "").trim();
+        const horizon = String(h["horizon"] ?? "").trim();
+        const narrative = String(h["narrative"] ?? "").trim();
+        if (problem || horizon || narrative) {
+            md.push("## Dynamic hypothesis", "");
+            if (problem)
+                md.push(`**Behavior of interest:** ${problem}  `);
+            if (horizon)
+                md.push(`**Time horizon:** ${horizon}`);
+            if (problem || horizon)
+                md.push("");
+            if (narrative)
+                md.push(narrative, "");
+        }
+    }
+    md.push("```mermaid", mermaid, "```", "");
+    if (loops.length > 0) {
+        md.push("## Feedback loops", "");
+        for (const l of loops) {
+            const cycle = l.loop.join(" → ");
+            const key = loopNoteKey(l.loop, l.type);
+            const val = valence[key];
+            const tag = val === "virtuous" ? " _(virtuous cycle)_" : val === "vicious" ? " _(vicious cycle)_" : "";
+            const lead = [];
+            if (l.label)
+                lead.push(`**${l.label}**`);
+            const title = titles[key];
+            if (title && title.trim().length > 0)
+                lead.push(`**${title}**`);
+            const leadStr = lead.length > 0 ? lead.join(" · ") + " · " : "";
+            md.push(`- ${leadStr}**${l.type}** — ${cycle}${tag}`);
+            const note = notes[key];
+            if (note !== undefined) {
+                for (const ln of note.split("\n"))
+                    md.push(ln.trim().length === 0 ? "  >" : `  > ${ln}`);
+            }
+        }
+        md.push("");
+    }
+    return { content: md.join("\n"), mime: "text/markdown", ext: "md" };
+}

package/dist/engine/layout.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Deterministic Fruchterman-Reingold layout (circle seed, no RNG) — TypeScript
+ * port of `autoLayout` in `core/lib/cli/formats.dart`. Produces round, evenly
+ * spaced loops; an overlap-removal pass nudges only the node boxes that still
+ * collide. Identical inputs yield identical positions across CLI/app/plugin, so
+ * "Tidy" is consistent everywhere.
+ */
+export interface LayoutNode {
+    id: string;
+    name: string;
+    kind?: string;
+}
+export interface LayoutEdge {
+    source: string;
+    target: string;
+}
+export declare function boxSize(name: string, kind?: string): [number, number];
+/** Returns id -> [x, y]. */
+export declare function autoLayout(nodes: LayoutNode[], edges: LayoutEdge[], cx?: number, cy?: number): Map<string, [number, number]>;

package/dist/engine/layout.js

@@ -0,0 +1,142 @@
+/**
+ * Deterministic Fruchterman-Reingold layout (circle seed, no RNG) — TypeScript
+ * port of `autoLayout` in `core/lib/cli/formats.dart`. Produces round, evenly
+ * spaced loops; an overlap-removal pass nudges only the node boxes that still
+ * collide. Identical inputs yield identical positions across CLI/app/plugin, so
+ * "Tidy" is consistent everywhere.
+ */
+const clampMin = (d, lo) => (d < lo ? lo : d);
+export function boxSize(name, kind) {
+    const h = kind === "stock" ? 40 : 34;
+    const extra = kind === "flow" ? 40 : 36;
+    const w = Math.max(60, name.length * 7.2 + extra);
+    return [w, h];
+}
+/** Returns id -> [x, y]. */
+export function autoLayout(nodes, edges, cx = 280, cy = 300) {
+    const ids = nodes.map((v) => v.id);
+    const n = ids.length;
+    const result = new Map();
+    if (n === 0)
+        return result;
+    if (n === 1) {
+        result.set(ids[0], [cx, cy]);
+        return result;
+    }
+    const idx = new Map();
+    ids.forEach((id, i) => idx.set(id, i));
+    const radius = Math.max(170, n * 34);
+    const pos = new Map();
+    for (let i = 0; i < n; i++) {
+        const a = (2 * Math.PI * i) / n;
+        pos.set(ids[i], [cx + radius * Math.cos(a), cy + radius * Math.sin(a)]);
+    }
+    const adj = [];
+    for (const e of edges) {
+        const s = String(e.source);
+        const t = String(e.target);
+        if (idx.has(s) && idx.has(t) && s !== t)
+            adj.push([s, t]);
+    }
+    const area = Math.pow(2.2 * radius, 2);
+    const k = 1.15 * Math.sqrt(area / n);
+    let temp = radius * 0.3;
+    for (let iter = 0; iter < 320; iter++) {
+        const disp = new Map();
+        for (const id of ids)
+            disp.set(id, [0, 0]);
+        for (let i = 0; i < n; i++) {
+            for (let j = i + 1; j < n; j++) {
+                const vi = ids[i];
+                const vj = ids[j];
+                const pi = pos.get(vi);
+                const pj = pos.get(vj);
+                const dx = pi[0] - pj[0];
+                const dy = pi[1] - pj[1];
+                const d = clampMin(Math.sqrt(dx * dx + dy * dy), 0.01);
+                const f = (k * k) / d;
+                const ux = dx / d;
+                const uy = dy / d;
+                const di = disp.get(vi);
+                const dj = disp.get(vj);
+                di[0] += ux * f;
+                di[1] += uy * f;
+                dj[0] -= ux * f;
+                dj[1] -= uy * f;
+            }
+        }
+        for (const [a, b] of adj) {
+            const pa = pos.get(a);
+            const pb = pos.get(b);
+            const dx = pa[0] - pb[0];
+            const dy = pa[1] - pb[1];
+            const d = clampMin(Math.sqrt(dx * dx + dy * dy), 0.01);
+            const f = (d * d) / k;
+            const ux = dx / d;
+            const uy = dy / d;
+            const da = disp.get(a);
+            const db = disp.get(b);
+            da[0] -= ux * f;
+            da[1] -= uy * f;
+            db[0] += ux * f;
+            db[1] += uy * f;
+        }
+        for (const id of ids) {
+            const dp = disp.get(id);
+            const p = pos.get(id);
+            const d = clampMin(Math.sqrt(dp[0] * dp[0] + dp[1] * dp[1]), 0.01);
+            p[0] += (dp[0] / d) * Math.min(d, temp);
+            p[1] += (dp[1] / d) * Math.min(d, temp);
+        }
+        temp *= 0.97;
+    }
+    // Overlap removal using real label box sizes.
+    const sizes = new Map();
+    for (const v of nodes)
+        sizes.set(v.id, boxSize(v.name, v.kind));
+    const margin = 18;
+    for (let iter = 0; iter < 120; iter++) {
+        let moved = false;
+        for (let i = 0; i < n; i++) {
+            for (let j = i + 1; j < n; j++) {
+                const vi = ids[i];
+                const vj = ids[j];
+                const si = sizes.get(vi);
+                const sj = sizes.get(vj);
+                const pi = pos.get(vi);
+                const pj = pos.get(vj);
+                const dx = pj[0] - pi[0];
+                const dy = pj[1] - pi[1];
+                const ox = (si[0] + sj[0]) / 2 + margin - Math.abs(dx);
+                const oy = (si[1] + sj[1]) / 2 + margin - Math.abs(dy);
+                if (ox > 0 && oy > 0) {
+                    if (ox <= oy) {
+                        const push = (ox / 2) * (dx < 0 ? -1 : 1);
+                        pi[0] -= push;
+                        pj[0] += push;
+                    }
+                    else {
+                        const push = (oy / 2) * (dy < 0 ? -1 : 1);
+                        pi[1] -= push;
+                        pj[1] += push;
+                    }
+                    moved = true;
+                }
+            }
+        }
+        if (!moved)
+            break;
+    }
+    let mx = 0;
+    let my = 0;
+    for (const p of pos.values()) {
+        mx += p[0];
+        my += p[1];
+    }
+    mx /= n;
+    my /= n;
+    for (const [id, p] of pos) {
+        result.set(id, [Number((p[0] - mx + cx).toFixed(1)), Number((p[1] - my + cy).toFixed(1))]);
+    }
+    return result;
+}

package/dist/engine/loopGraph.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Pure in-memory graph built from parsed vault notes — TypeScript port of
+ * `core/lib/graph/loop_graph.dart`.
+ *
+ * Loop detection excludes `indirect` (dashed) links and classifies each simple
+ * directed cycle by the product of its link polarities: even number of `-` -> R
+ * (reinforcing), odd -> B (balancing). `delay` is ignored. Enumeration
+ * canonicalizes each cycle to start at its minimum node id and only extends to
+ * ids >= the start, yielding each cycle once with no artificial depth bound.
+ */
+import { DetectedLoop, VariableFile } from "./types";
+/** One adjacency edge as seen by a trace. */
+export interface TracedEdge {
+    to: string;
+    polarity: number;
+    indirect: boolean;
+    confidence?: number;
+    basis?: string;
+}
+export interface VarMetrics {
+    inDegree: number;
+    outDegree: number;
+    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.
+ */
+export declare function labelLoopsByKey(loops: DetectedLoop[], name: (id: string) => string): Map<string, string>;
+export declare class LoopGraph {
+    private readonly nodes;
+    constructor(notes: Iterable<VariableFile>);
+    get allNodes(): VariableFile[];
+    node(id: string): VariableFile | undefined;
+    /** Full causal adjacency including `indirect` links, with evidence carries. */
+    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. */
+    detectLoops(): DetectedLoop[];
+    /**
+     * The Shortest Independent Loop Set (SILS): the minimum-weight basis of the
+     * cycle space, found by a greedy GF(2) XOR-basis pass over cycles sorted by
+     * length (ties broken on `key`). Covers every loop edge with a minimal,
+     * independent set.
+     */
+    shortestIndependentLoopSet(): DetectedLoop[];
+    /** Degree (in/out over ALL links) + loop participation per variable. */
+    metrics(): Map<string, VarMetrics>;
+}

package/dist/engine/loopKey.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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
+ * the loop's on-disk identity (that lives in each `Loops/*.md` frontmatter as
+ * the ordered member ids — see `loopNote.ts`). Mirrors Dart `fmt.loopNoteKey`.
+ *
+ * Pure and dependency-free so both the engine (`nativeEngine`) and the view
+ * (`view/loopKeys`) derive the key from one definition instead of each carrying
+ * its own copy.
+ */
+export declare function loopKey(labels: string[], type: 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
+ * `loopKey` (dedupe + sort) but rendered for humans — it deliberately avoids a
+ * leading `scheme:` so Obsidian's property view does not show it as a (dead)
+ * external link. Display only; NEVER an identity/lookup/export/API key (that is
+ * `loopKey`). Mirrors Dart `fmt.loopEchoLabel`.
+ *
+ * The Set dedupe absorbs a closed-cycle duplicate, so no explicit `first==last`
+ * trim is needed. Keep this symmetric with the Dart twin: do not add a trim to
+ * only one side — divergent membership handling would break byte parity.
+ */
+export declare function loopEchoLabel(labels: string[], type: string): string;