@neoloopy/cld-canvas 0.1.0

package/dist/engine/loopKey.js

@@ -0,0 +1,32 @@
+/**
+ * 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 function loopKey(labels, type) {
+    const letter = type.toUpperCase().startsWith("R") ? "R" : "B";
+    const uniq = [...new Set(labels.map((l) => String(l)))].sort();
+    return `${letter}:${uniq.join("|")}`;
+}
+/**
+ * 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 function loopEchoLabel(labels, type) {
+    const letter = type.toUpperCase().startsWith("R") ? "R" : "B";
+    const uniq = [...new Set(labels.map((l) => String(l)))].sort();
+    return uniq.length === 0 ? letter : `${letter} · ${uniq.join(" | ")}`;
+}

package/dist/engine/loopNote.d.ts

@@ -0,0 +1,40 @@
+/**
+ * One feedback-loop note (`Loops/<slug>.md`): an Obsidian-native markdown file
+ * whose identity is the loop's (type, ordered member variable-ids) — held in
+ * frontmatter, NEVER derived from the filename or from variable labels. The body
+ * owns the narrative; `loop` is a human-readable echo only.
+ *
+ * TypeScript port of `core/lib/vault/loop_note.dart`. The serializer matches the
+ * Dart output byte-for-byte (field order, `members: []` empty form, raw
+ * `valence`, scalar quoting via the shared note codec) so a `Loops/*.md` file
+ * written by the plugin and by the app/CLI round-trips losslessly on one vault.
+ */
+import { YamlParse } from "./noteCodec";
+export interface LoopNote {
+    /** 'R' (reinforcing) or 'B' (balancing). */
+    type: string;
+    /** Canonical-ordered member variable ids (the stable identity). */
+    members: string[];
+    /** Free-text alias shown beside the R/B badge (was `loopTitles`). */
+    title: string;
+    /** 'virtuous' | 'vicious' | '' (was `loopValence`). */
+    valence: string;
+    /** Human-readable label echo (`R:Label|Label`). Non-authoritative. */
+    loopEcho: string;
+    body: string;
+    /** Unknown frontmatter keys, preserved verbatim (carries app-only `archetype`). */
+    extra: Record<string, unknown>;
+    /** True when frontmatter was present but unparseable (body still served). */
+    malformed: boolean;
+}
+export declare function emptyLoopNote(partial?: Partial<LoopNote>): LoopNote;
+export declare function parseLoopNote(source: string, yaml: YamlParse): LoopNote;
+export declare function serializeLoopNote(n: LoopNote): string;
+/**
+ * Rotate a cycle's ids so it starts at its lexicographically smallest id. Loop
+ * identity is rotation-invariant but routing-sensitive (order matters), so two
+ * different routings through the same node set stay distinct.
+ */
+export declare function canonicalLoopMembers(nodeIds: string[]): string[];
+export declare function loopMatchesNote(type: string, nodeIds: string[], note: LoopNote): boolean;
+export declare function loopSlug(type: string, title: string, memberLabels: string[]): string;

package/dist/engine/loopNote.js

@@ -0,0 +1,130 @@
+/**
+ * One feedback-loop note (`Loops/<slug>.md`): an Obsidian-native markdown file
+ * whose identity is the loop's (type, ordered member variable-ids) — held in
+ * frontmatter, NEVER derived from the filename or from variable labels. The body
+ * owns the narrative; `loop` is a human-readable echo only.
+ *
+ * TypeScript port of `core/lib/vault/loop_note.dart`. The serializer matches the
+ * Dart output byte-for-byte (field order, `members: []` empty form, raw
+ * `valence`, scalar quoting via the shared note codec) so a `Loops/*.md` file
+ * written by the plugin and by the app/CLI round-trips losslessly on one vault.
+ */
+import { emitExtra, scalar, splitFrontmatter } from "./noteCodec";
+const FENCE = "---";
+const KNOWN = new Set(["type", "members", "title", "valence", "loop"]);
+export function emptyLoopNote(partial = {}) {
+    return {
+        type: "R",
+        members: [],
+        title: "",
+        valence: "",
+        loopEcho: "",
+        body: "",
+        extra: {},
+        malformed: false,
+        ...partial,
+    };
+}
+export function parseLoopNote(source, yaml) {
+    const [fm, body] = splitFrontmatter(source);
+    if (fm === null)
+        return emptyLoopNote({ body });
+    let node;
+    let malformed = false;
+    try {
+        node = yaml(fm);
+    }
+    catch {
+        malformed = true;
+    }
+    const isMap = node !== null && typeof node === "object" && !Array.isArray(node);
+    if (node !== null && node !== undefined && !isMap)
+        malformed = true;
+    const m = isMap ? node : {};
+    const type = String(m["type"] ?? "R").toUpperCase().startsWith("B") ? "B" : "R";
+    const members = [];
+    if (Array.isArray(m["members"])) {
+        for (const e of m["members"]) {
+            const s = String(e).trim();
+            if (s.length > 0)
+                members.push(s);
+        }
+    }
+    const valenceRaw = String(m["valence"] ?? "").trim().toLowerCase();
+    const extra = {};
+    for (const [k, v] of Object.entries(m))
+        if (!KNOWN.has(k))
+            extra[k] = v;
+    return {
+        type,
+        members,
+        title: String(m["title"] ?? "").trim(),
+        valence: valenceRaw === "virtuous" || valenceRaw === "vicious" ? valenceRaw : "",
+        loopEcho: String(m["loop"] ?? "").trim(),
+        body,
+        extra,
+        malformed,
+    };
+}
+export function serializeLoopNote(n) {
+    const lines = [FENCE];
+    lines.push(`type: ${n.type}`);
+    if (n.members.length === 0) {
+        lines.push("members: []");
+    }
+    else {
+        lines.push("members:");
+        for (const id of n.members)
+            lines.push(`  - ${scalar(id)}`);
+    }
+    if (n.title.length > 0)
+        lines.push(`title: ${scalar(n.title)}`);
+    if (n.valence.length > 0)
+        lines.push(`valence: ${n.valence}`);
+    if (n.loopEcho.length > 0)
+        lines.push(`loop: ${scalar(n.loopEcho)}`);
+    for (const [k, v] of Object.entries(n.extra))
+        emitExtra(lines, k, v, 0);
+    lines.push(FENCE);
+    let out = lines.join("\n") + "\n";
+    if (n.body.trim().length > 0)
+        out += "\n" + n.body.trim() + "\n";
+    return out;
+}
+/**
+ * Rotate a cycle's ids so it starts at its lexicographically smallest id. Loop
+ * identity is rotation-invariant but routing-sensitive (order matters), so two
+ * different routings through the same node set stay distinct.
+ */
+export function canonicalLoopMembers(nodeIds) {
+    if (nodeIds.length === 0)
+        return [];
+    let min = 0;
+    for (let i = 1; i < nodeIds.length; i++) {
+        if (nodeIds[i] < nodeIds[min])
+            min = i;
+    }
+    return [...nodeIds.slice(min), ...nodeIds.slice(0, min)];
+}
+export function loopMatchesNote(type, nodeIds, note) {
+    if (note.type !== type)
+        return false;
+    const a = canonicalLoopMembers(nodeIds);
+    const b = canonicalLoopMembers(note.members);
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+const SLUG_STRIP = /[^a-z0-9]+/g;
+export function loopSlug(type, title, memberLabels) {
+    const basis = title.trim().length > 0 ? title : memberLabels.join("-");
+    const body = basis
+        .toLowerCase()
+        .replace(SLUG_STRIP, "-")
+        .replace(/^-+|-+$/g, "");
+    const t = type.toUpperCase().startsWith("B") ? "b" : "r";
+    return body.length === 0 ? t : `${t}-${body}`;
+}

package/dist/engine/nativeEngine.d.ts

@@ -0,0 +1,175 @@
+/**
+ * NativeEngine — the default, fully-open-source TypeScript implementation of the
+ * qualitative neoloopy surface, working directly on vault files through a
+ * `VaultStorage`. It reuses the Phase-2 engine modules (codec, loop graph,
+ * layout, exporters, signature) so reads/writes are byte-compatible with the
+ * Dart CLI/app and the Python bridge. No `obsidian` import — unit-testable in
+ * plain Node against `MemoryStorage`.
+ *
+ * Vault conventions mirrored from `core/lib/vault/desktop_vault_storage.dart`
+ * and `core/lib/cli/vault_engine.dart`:
+ *   - variable note file = `Nodes/<id>.md`, id = `var_` + 8 hex. Legacy vaults
+ *     wrote `<id>.md` flat at the model root; those are still read (a `Nodes/`
+ *     copy wins on a duplicate id) and swept into `Nodes/` when next written.
+ *   - loop notes live in the model's `Loops/<slug>.md` files (see below).
+ *   - model folder name = slug(name) (`-2`, `-3` … on collision), `model.json`
+ *     manifest pretty-printed (2-space indent)
+ *   - `System.md` / `Futures.md` / `CLA.md` are not variables
+ *   - discovery: any folder with a `model.json` is a model and is NOT recursed
+ *     into, so a model's own `Nodes/`/`Loops/` subfolders are never mistaken for
+ *     nested models; grouped/nested model folders elsewhere are still found.
+ */
+import { BuildSpec, ExportFormat, GraphView, LinkInit, LinkPatch, ModelRef, NeoloopyEngine, NewVariable, QuantPatch, VariablePatch } from "./engine";
+import { VariableFile, Viewport } from "./types";
+import { YamlParse } from "./noteCodec";
+import { contentSignature } from "./specHash";
+import { Rendered } from "./exporters";
+import { VaultStorage } from "./storage";
+import { ParentAnchor } from "./subsystemLinks";
+export interface NativeEngineOptions {
+    /** Vault-relative base folder for newly created models (may be ""). */
+    modelsRoot: string;
+}
+export declare class NativeEngine implements NeoloopyEngine {
+    private readonly storage;
+    private readonly yaml;
+    private readonly opts;
+    constructor(storage: VaultStorage, yaml: YamlParse, opts: NativeEngineOptions);
+    listModels(): Promise<ModelRef[]>;
+    loadGraph(folder: string): Promise<GraphView>;
+    createModel(name: string): Promise<ModelRef>;
+    renameModel(folder: string, name: string): Promise<ModelRef>;
+    retitleModel(folder: string, name: string): Promise<ModelRef>;
+    /**
+     * Sync a node's label to its filename after the user renamed the file in the
+     * vault (`Nodes/<stem>.md`). The node-level inverse of {@link retitleModel}:
+     * the file is already where the user put it, so the label follows it (the
+     * de-slugged stem, underscores → spaces). {@link writeNote} may then
+     * re-normalize the on-disk name (spaces → underscores) so it converges. The
+     * stable `var_…` id and every link to it are untouched, so links never break.
+     */
+    relabelNodeFromFilename(folder: string, fileStem: string): Promise<void>;
+    /** Target folder for renaming `folder`'s model to `name`: the new slug under
+     *  the same parent, suffixed on collision; unchanged when the slug matches. */
+    private destForRename;
+    deleteModel(folder: string): Promise<void>;
+    /** Resolve a folder to its model id (read from `model.json`). */
+    modelId(folder: string): Promise<string>;
+    /**
+     * Duplicate a model as a brand-new model: a byte-for-byte copy of the folder
+     * tree (so prose, layout, loop notes, and System note all come along), then a
+     * full re-key so the copy has a fresh model id, fresh variable ids, and fresh
+     * loop/System identity anchors. `shared` keys are PRESERVED, so the copy stays
+     * joined to the cross-model graph. Lands as a sibling of the source, titled
+     * "<name> (copy)" (bumping to "(copy 2)…" on a name clash).
+     */
+    duplicateModel(srcFolder: string): Promise<ModelRef>;
+    /**
+     * Heal model-id collisions: a raw Obsidian copy of a model (or a folder of
+     * models) clones their ids verbatim, so two folders end up claiming the same
+     * `mdl_…`. Group folders by id; for each colliding group keep the OLDEST (by
+     * `created`) and re-key every newer sibling. Returns one row per re-keyed
+     * folder. A no-op (empty result) when every id is already unique.
+     */
+    healDuplicateIds(): Promise<Array<{
+        folder: string;
+        oldId: string;
+        newId: string;
+    }>>;
+    addVariable(folder: string, init: NewVariable): Promise<VariableFile>;
+    updateVariable(folder: string, id: string, patch: VariablePatch): Promise<VariableFile>;
+    setEquation(folder: string, id: string, patch: QuantPatch): Promise<VariableFile>;
+    setSubsystem(folder: string, varId: string, child: {
+        folder: string;
+        name: string;
+    } | null): Promise<void>;
+    moveVariable(folder: string, id: string, x: number, y: number): Promise<void>;
+    removeVariable(folder: string, id: 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>;
+    getLoopNotes(folder: string): Promise<Record<string, string>>;
+    setLoopNote(folder: string, key: string, text: string): Promise<void>;
+    /**
+     * The vault-relative path of the canonical `Loops/*.md` file for `key`,
+     * creating an empty-but-anchored note if none exists yet. Returns null when no
+     * live loop carries that key (e.g. the graph changed). Used by the canvas to
+     * open the real markdown file for editing.
+     */
+    loopNotePath(folder: string, key: string): Promise<string | null>;
+    ensureSystemNote(folder: string): Promise<string>;
+    deriveParents(folder: string): Promise<ParentAnchor[]>;
+    export(folder: string, format: ExportFormat): Promise<Rendered>;
+    /** The model's `Nodes/` subfolder, where variable notes now live. */
+    private nodesDir;
+    /** A variable note's path for a filename stem: `<folder>/Nodes/<stem>.md`. */
+    private notePath;
+    /** Pre-`Nodes/` location of a variable note, flat at the model root. */
+    private legacyNotePath;
+    private readNote;
+    private writeNote;
+    private readManifest;
+    private writeManifest;
+    /** Bump `model.json` modified after a content change. */
+    private touchManifest;
+    /**
+     * Variable-note id → vault path, gathered from the model's `Nodes/` subfolder
+     * and any legacy flat notes at the model root. A `Nodes/` note wins on a
+     * duplicate id (mirrors the Dart reader). `model.json` and the special notes
+     * (System/Futures/CLA) are excluded.
+     */
+    private noteFilesById;
+    private listNoteFiles;
+    private loadNotes;
+    private loopsDir;
+    /** Sorted `.md` basenames in `Loops/`; tolerant of a missing folder. */
+    private listLoopNoteFiles;
+    private readLoopNoteFile;
+    private writeLoopNoteFile;
+    private uniqueLoopFilename;
+    /**
+     * 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
+     * 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
+     * (and no file) when the graph carries no such loop. */
+    private upsertLoopFileByKey;
+    /** Find-or-create the identity-matched `Loops/` file and apply `fields`
+     * (undefined leaves a field unchanged; `archetype: ""` clears it). Returns the
+     * filename written. Title/valence/extra of an existing file are preserved. */
+    private writeLoopFile;
+    /** Recursively find folders containing a `model.json` (dot-folders pruned). */
+    private findModelFolders;
+    /**
+     * Re-key a model in place: assign a fresh model id, fresh variable ids, and
+     * re-point every internal reference (links, loop-note members, the System
+     * note's identity anchor). Structure, prose, layout, `shared` keys, and
+     * subsystem wikilinks are untouched. Returns the new model id. Used by both
+     * {@link duplicateModel} (on a fresh copy) and {@link healDuplicateIds} (on a
+     * collided clone).
+     */
+    private rekeyModel;
+    /** Recursively copy a folder tree byte-for-byte (the source is untouched). */
+    private copyTree;
+    /** Remove every variable note (flat root + `Nodes/`); keep the special notes. */
+    private removeAllVariableFiles;
+    /** Rewrite `System.md`'s `model:` identity anchor to `newId` (if it exists). */
+    private swapSystemModelId;
+    /** "<base> (copy)" — bumping "(copy 2)…" against existing model titles. */
+    private uniqueModelName;
+    /** A free folder `<parent>/<leaf>` (suffixing `-2/-3…` like createModel). */
+    private uniqueSiblingFolder;
+}
+/** Re-exported from `./loopKey` so existing importers keep their path. */
+export { loopKey } from "./loopKey";
+/** Re-export so callers don't need a second import for the signature helper. */
+export { contentSignature };