@neoloopy/cld-canvas 0.1.0

package/dist/engine/noteCodec.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Reads & writes a single variable note: YAML frontmatter + Markdown body.
+ * TypeScript port of `core/lib/vault/note_codec.dart`.
+ *
+ * Round-trip invariant: parsing then serializing preserves the structured fields
+ * AND any unknown frontmatter keys (format rule §3 — never clobber another
+ * tool's / the user's data). The serializer is hand-rolled to match the Dart
+ * output byte-for-byte (field order, scalar quoting, x/y one-decimal format,
+ * block-list link indentation), so notes written by the plugin and the app share
+ * an identical content signature and round-trip losslessly on one vault.
+ *
+ * Parsing is delegated to an injected YAML parser (Obsidian's `parseYaml` at
+ * runtime; the `yaml` package in tests) so this module stays pure and testable.
+ *
+ * Known limitation: a JS number cannot distinguish int from float, so a
+ * whole-number float inside a *preserved unknown* key (e.g. a quant block's
+ * `100.0`) may re-serialize as `100`. Structured qualitative fields handle this
+ * exactly; preserved blocks keep the value, not necessarily the `.0` suffix.
+ */
+import { VariableFile } from "./types";
+export type YamlParse = (s: string) => unknown;
+/** Returns [frontmatterText|null, body]. Tolerates notes with no frontmatter. */
+export declare function splitFrontmatter(source: string): [string | null, string];
+export declare function parseNote(source: string, yaml: YamlParse, fallbackId?: string): VariableFile;
+/** Emit a YAML scalar, quoting when needed so it parses back identically. */
+export declare function scalar(v: unknown): string;
+/** Emit `key`/`value` as YAML into `lines` at the given indent level. */
+export declare function emitExtra(lines: string[], key: string, value: unknown, indent: number): void;
+export declare function serializeNote(v: VariableFile): string;

package/dist/engine/noteCodec.js

@@ -0,0 +1,254 @@
+/**
+ * Reads & writes a single variable note: YAML frontmatter + Markdown body.
+ * TypeScript port of `core/lib/vault/note_codec.dart`.
+ *
+ * Round-trip invariant: parsing then serializing preserves the structured fields
+ * AND any unknown frontmatter keys (format rule §3 — never clobber another
+ * tool's / the user's data). The serializer is hand-rolled to match the Dart
+ * output byte-for-byte (field order, scalar quoting, x/y one-decimal format,
+ * block-list link indentation), so notes written by the plugin and the app share
+ * an identical content signature and round-trip losslessly on one vault.
+ *
+ * Parsing is delegated to an injected YAML parser (Obsidian's `parseYaml` at
+ * runtime; the `yaml` package in tests) so this module stays pure and testable.
+ *
+ * Known limitation: a JS number cannot distinguish int from float, so a
+ * whole-number float inside a *preserved unknown* key (e.g. a quant block's
+ * `100.0`) may re-serialize as `100`. Structured qualitative fields handle this
+ * exactly; preserved blocks keep the value, not necessarily the `.0` suffix.
+ */
+import { varTypeFrom, linkFromMap, linkToMap, toUtcIso, } from "./types";
+const FENCE = "---";
+/** Frontmatter keys this codec owns; everything else is carried in `extra`. */
+const KNOWN = new Set([
+    "id",
+    "type",
+    "label",
+    "group",
+    "claLayer",
+    "shared",
+    "x",
+    "y",
+    "links",
+    "tags",
+    "status",
+    "created",
+    "modified",
+    "rev",
+    "source",
+    "reviewed",
+    "reviewedBy",
+    "h",
+    "subsystem",
+]);
+/** Returns [frontmatterText|null, body]. Tolerates notes with no frontmatter. */
+export function splitFrontmatter(source) {
+    const s = source.replace(/\r\n/g, "\n");
+    const t = s.startsWith(`${FENCE}\n`) ? s : s.replace(/^\s+/, "");
+    if (!t.startsWith(`${FENCE}\n`))
+        return [null, source.trim()];
+    const end = t.indexOf(`\n${FENCE}`, FENCE.length);
+    if (end < 0)
+        return [null, source.trim()];
+    const fm = t.substring(FENCE.length + 1, end + 1);
+    let rest = t.substring(end + 1 + FENCE.length + 1);
+    if (rest.startsWith("\n"))
+        rest = rest.substring(1);
+    return [fm, rest.trim()];
+}
+function nonEmpty(v) {
+    if (v === null || v === undefined)
+        return undefined;
+    const s = String(v);
+    return s.length === 0 ? undefined : s;
+}
+function tagsFrom(v) {
+    if (Array.isArray(v))
+        return v.map((e) => String(e).trim()).filter((s) => s.length > 0);
+    if (typeof v === "string")
+        return v.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    return [];
+}
+/**
+ * Read a top-level scalar straight from the frontmatter *text*. Timestamps must
+ * survive byte-for-byte (Dart writes microsecond precision, `2026-..Z`), but
+ * YAML parsers vary: the `yaml` package keeps them as strings while js-yaml may
+ * coerce `!!timestamp` to a `Date` and silently truncate to milliseconds. Going
+ * back to the raw bytes makes timestamp round-trip parser-independent.
+ */
+function rawScalar(frontmatter, key) {
+    if (frontmatter === null)
+        return undefined;
+    const m = new RegExp(`^${key}:[ \\t]*(.+?)[ \\t]*$`, "m").exec(frontmatter);
+    if (!m)
+        return undefined;
+    let s = m[1];
+    if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+        s = s.slice(1, -1);
+    }
+    return s.length === 0 ? undefined : s;
+}
+/** Prefer the exact on-disk timestamp bytes; fall back to normalizing the parsed value. */
+function tsField(frontmatter, key, parsed) {
+    return rawScalar(frontmatter, key) ?? toUtcIso(parsed);
+}
+export function parseNote(source, yaml, fallbackId) {
+    const [frontmatter, body] = splitFrontmatter(source);
+    const parsed = frontmatter === null ? {} : yaml(frontmatter);
+    const m = parsed && typeof parsed === "object" && !Array.isArray(parsed)
+        ? parsed
+        : {};
+    const links = [];
+    const rawLinks = m["links"];
+    if (Array.isArray(rawLinks)) {
+        for (const e of rawLinks) {
+            if (e && typeof e === "object")
+                links.push(linkFromMap(e));
+        }
+    }
+    const numOr0 = (v) => (typeof v === "number" ? v : 0);
+    const extra = {};
+    for (const [k, v] of Object.entries(m))
+        if (!KNOWN.has(k))
+            extra[k] = v;
+    return {
+        id: String(m["id"] ?? fallbackId ?? ""),
+        type: varTypeFrom(typeof m["type"] === "string" ? (m["type"]) : undefined),
+        label: String(m["label"] ?? ""),
+        group: nonEmpty(m["group"]),
+        claLayer: nonEmpty(m["claLayer"]),
+        shared: nonEmpty(m["shared"]),
+        x: numOr0(m["x"]),
+        y: numOr0(m["y"]),
+        links,
+        tags: tagsFrom(m["tags"]),
+        status: nonEmpty(m["status"]),
+        created: tsField(frontmatter, "created", m["created"]),
+        modified: tsField(frontmatter, "modified", m["modified"]),
+        rev: typeof m["rev"] === "number" ? Math.trunc(m["rev"]) : 0,
+        source: nonEmpty(m["source"]),
+        reviewed: tsField(frontmatter, "reviewed", m["reviewed"]),
+        reviewedBy: nonEmpty(m["reviewedBy"]),
+        h: nonEmpty(m["h"]),
+        subsystem: nonEmpty(m["subsystem"]),
+        body,
+        extra,
+    };
+}
+/** Emit a YAML scalar, quoting when needed so it parses back identically. */
+export function scalar(v) {
+    if (v === null || v === undefined)
+        return "null";
+    if (typeof v === "number" || typeof v === "boolean")
+        return String(v);
+    const s = String(v);
+    const needsQuote = s.length === 0 ||
+        /^[\s\-+?:,[\]{}#&*!|>%@`"']/.test(s) ||
+        /\s$/.test(s) ||
+        s.includes(": ") ||
+        s.includes(" #") ||
+        s.includes("\n") ||
+        /^(true|false|null|yes|no|on|off)$/i.test(s) ||
+        /^[-+]?\d/.test(s);
+    if (!needsQuote)
+        return s;
+    return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+/** Match Dart's `'$d'` for a double-typed value: whole numbers keep a `.0`. */
+function dartDouble(d) {
+    return Number.isInteger(d) ? `${d}.0` : String(d);
+}
+/** x/y formatting: integer-valued -> one decimal, else minimal. */
+function numToYaml(d) {
+    return Number.isInteger(d) ? d.toFixed(1) : String(d);
+}
+/** Serialize a link entry value with the correct numeric type (Dart parity). */
+function linkScalar(key, val) {
+    if (typeof val === "boolean")
+        return String(val);
+    if (typeof val === "number")
+        return key === "weight" ? String(Math.trunc(val)) : dartDouble(val);
+    return scalar(val);
+}
+/** Emit `key`/`value` as YAML into `lines` at the given indent level. */
+export function emitExtra(lines, key, value, indent) {
+    const pad = "  ".repeat(indent);
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        lines.push(`${pad}${key}:`);
+        for (const [k, val] of Object.entries(value)) {
+            emitExtra(lines, k, val, indent + 1);
+        }
+    }
+    else if (Array.isArray(value)) {
+        lines.push(`${pad}${key}:`);
+        for (const item of value) {
+            if (item !== null && typeof item === "object" && !Array.isArray(item)) {
+                let first = true;
+                for (const [k, val] of Object.entries(item)) {
+                    lines.push(`${pad}  ${first ? "- " : "  "}${k}: ${scalar(val)}`);
+                    first = false;
+                }
+            }
+            else {
+                lines.push(`${pad}  - ${scalar(item)}`);
+            }
+        }
+    }
+    else {
+        lines.push(`${pad}${key}: ${scalar(value)}`);
+    }
+}
+export function serializeNote(v) {
+    const lines = [FENCE];
+    lines.push(`id: ${scalar(v.id)}`);
+    lines.push(`type: ${v.type}`);
+    lines.push(`label: ${scalar(v.label)}`);
+    if (v.group && v.group.length > 0)
+        lines.push(`group: ${scalar(v.group)}`);
+    if (v.claLayer && v.claLayer.length > 0)
+        lines.push(`claLayer: ${scalar(v.claLayer)}`);
+    if (v.shared && v.shared.length > 0)
+        lines.push(`shared: ${scalar(v.shared)}`);
+    if (v.tags.length > 0) {
+        lines.push("tags:");
+        for (const t of v.tags)
+            lines.push(`  - ${scalar(t)}`);
+    }
+    if (v.status && v.status.length > 0)
+        lines.push(`status: ${scalar(v.status)}`);
+    if (v.created)
+        lines.push(`created: ${v.created}`);
+    if (v.modified)
+        lines.push(`modified: ${v.modified}`);
+    if (v.rev > 0)
+        lines.push(`rev: ${v.rev}`);
+    if (v.source && v.source.length > 0)
+        lines.push(`source: ${scalar(v.source)}`);
+    if (v.reviewed)
+        lines.push(`reviewed: ${v.reviewed}`);
+    if (v.reviewedBy && v.reviewedBy.length > 0)
+        lines.push(`reviewedBy: ${scalar(v.reviewedBy)}`);
+    if (v.h && v.h.length > 0)
+        lines.push(`h: ${scalar(v.h)}`);
+    if (v.subsystem && v.subsystem.length > 0)
+        lines.push(`subsystem: ${scalar(v.subsystem)}`);
+    lines.push(`x: ${numToYaml(v.x)}`);
+    lines.push(`y: ${numToYaml(v.y)}`);
+    if (v.links.length > 0) {
+        lines.push("links:");
+        for (const l of v.links) {
+            let first = true;
+            for (const [key, val] of linkToMap(l)) {
+                lines.push(`${first ? "  - " : "    "}${key}: ${linkScalar(key, val)}`);
+                first = false;
+            }
+        }
+    }
+    for (const [k, val] of Object.entries(v.extra))
+        emitExtra(lines, k, val, 0);
+    lines.push(FENCE);
+    let out = lines.join("\n") + "\n";
+    if (v.body.trim().length > 0)
+        out += "\n" + v.body.trim() + "\n";
+    return out;
+}

package/dist/engine/noteNaming.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Filename ⇄ label mapping for variable ("node") notes. A node's Markdown file
+ * is named after its label so the vault reads like the diagram (`Birth_Rate.md`
+ * rather than `var_9c1b.md`), while the stable `var_…` id in the frontmatter
+ * stays the link target — so renaming a node never breaks a link.
+ *
+ * The rule (per product decision): spaces become underscores, case is kept, and
+ * characters that are illegal in a path or significant in an Obsidian wikilink
+ * are dropped. Pure and obsidian-free so both the engine and the view can use it.
+ */
+/**
+ * Filename stem (no extension) for a label. Returns "" when the label is blank
+ * or made entirely of reserved characters — callers fall back to the id then.
+ */
+export declare function noteSlug(label: string): string;
+/** Best-effort inverse, for when a user renames the file in the vault: turn the
+ *  filename stem back into a label (underscores → spaces). */
+export declare function noteUnslug(stem: string): string;

package/dist/engine/noteNaming.js

@@ -0,0 +1,28 @@
+/**
+ * Filename ⇄ label mapping for variable ("node") notes. A node's Markdown file
+ * is named after its label so the vault reads like the diagram (`Birth_Rate.md`
+ * rather than `var_9c1b.md`), while the stable `var_…` id in the frontmatter
+ * stays the link target — so renaming a node never breaks a link.
+ *
+ * The rule (per product decision): spaces become underscores, case is kept, and
+ * characters that are illegal in a path or significant in an Obsidian wikilink
+ * are dropped. Pure and obsidian-free so both the engine and the view can use it.
+ */
+// Path-illegal (\ / : * ? " < > |) plus wikilink-significant (# ^ [ ]) characters.
+const RESERVED = /[\\/:*?"<>|#^[\]]/g;
+/**
+ * Filename stem (no extension) for a label. Returns "" when the label is blank
+ * or made entirely of reserved characters — callers fall back to the id then.
+ */
+export function noteSlug(label) {
+    return label
+        .replace(RESERVED, "")
+        .replace(/\s+/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^_+|_+$/g, "");
+}
+/** Best-effort inverse, for when a user renames the file in the vault: turn the
+ *  filename stem back into a label (underscores → spaces). */
+export function noteUnslug(stem) {
+    return stem.replace(/_+/g, " ").trim();
+}

package/dist/engine/specHash.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Content signature + metadata stamping — TypeScript port of
+ * `core/lib/vault/meta_stamp.dart`.
+ *
+ * `fnv1a32` is the dependency-free 32-bit FNV-1a the Dart and Python codecs use,
+ * so all three produce identical 8-hex signatures (mirror: Dart `fnv1a32`,
+ * Python `_fnv1a32`). The signature covers a note's CONTENT fields only — it
+ * excludes x/y, cosmetic link attributes, and the derived
+ * created/modified/rev/source/h — so cosmetic moves and field reordering are not
+ * treated as content changes, and the plugin's writes are not falsely flagged as
+ * external edits by the app.
+ *
+ * The 64-bit quant spec hash (`quant_spec_hash`) is intentionally NOT ported:
+ * the qualitative plugin never computes quant staleness.
+ */
+import { VariableFile } from "./types";
+/** Provenance value stored in a note's `source` key for plugin writes. */
+export declare const WRITE_SOURCE_PLUGIN = "plugin";
+/** FNV-1a 32-bit hash of `s` (UTF-8), as 8 lowercase hex chars. */
+export declare function fnv1a32(s: string): string;
+/**
+ * Canonical, deterministic string over a note's content fields only. Links
+ * sorted by target, tags sorted; `shared` and per-link `confidence`/`basis` are
+ * appended only when set, so a note without them hashes byte-identically to
+ * before those fields existed.
+ */
+export declare function canonicalContent(v: VariableFile): string;
+/** 8-hex content signature stored as the note's `h` key. */
+export declare function contentSignature(v: VariableFile): string;
+/**
+ * Stamp recency metadata onto `next` before writing it.
+ * - `prev` is the note's prior on-disk state (undefined = creation).
+ * - A content change (signature differs, or creation) bumps modified/rev/source.
+ *   A cosmetic change (x/y only) preserves them.
+ * - `h` is always refreshed to the current content signature.
+ */
+export declare function stampMeta(prev: VariableFile | undefined, next: VariableFile, source: string, now?: Date): VariableFile;

package/dist/engine/specHash.js

@@ -0,0 +1,86 @@
+/**
+ * Content signature + metadata stamping — TypeScript port of
+ * `core/lib/vault/meta_stamp.dart`.
+ *
+ * `fnv1a32` is the dependency-free 32-bit FNV-1a the Dart and Python codecs use,
+ * so all three produce identical 8-hex signatures (mirror: Dart `fnv1a32`,
+ * Python `_fnv1a32`). The signature covers a note's CONTENT fields only — it
+ * excludes x/y, cosmetic link attributes, and the derived
+ * created/modified/rev/source/h — so cosmetic moves and field reordering are not
+ * treated as content changes, and the plugin's writes are not falsely flagged as
+ * external edits by the app.
+ *
+ * The 64-bit quant spec hash (`quant_spec_hash`) is intentionally NOT ported:
+ * the qualitative plugin never computes quant staleness.
+ */
+import { varTypeName } from "./types";
+/** Provenance value stored in a note's `source` key for plugin writes. */
+export const WRITE_SOURCE_PLUGIN = "plugin";
+const encoder = new TextEncoder();
+/** FNV-1a 32-bit hash of `s` (UTF-8), as 8 lowercase hex chars. */
+export function fnv1a32(s) {
+    let hash = 0x811c9dc5;
+    for (const b of encoder.encode(s)) {
+        hash ^= b;
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+}
+/**
+ * Canonical, deterministic string over a note's content fields only. Links
+ * sorted by target, tags sorted; `shared` and per-link `confidence`/`basis` are
+ * appended only when set, so a note without them hashes byte-identically to
+ * before those fields existed.
+ */
+export function canonicalContent(v) {
+    const tags = [...v.tags].sort();
+    const links = [...v.links].sort((a, b) => (a.to < b.to ? -1 : a.to > b.to ? 1 : 0));
+    const linkPart = (l) => {
+        const base = `${l.to}|${l.polarity}|${l.delay ? 1 : 0}|${l.indirect ? 1 : 0}|${l.nonlinear ? 1 : 0}`;
+        const conf = l.confidence !== undefined ? `|c${l.confidence.toFixed(3)}` : "";
+        const basis = l.basis !== undefined && l.basis.length > 0 ? `|b${l.basis}` : "";
+        return `${base}${conf}${basis}`;
+    };
+    const parts = [
+        v.label,
+        varTypeName(v.type),
+        v.group ?? "",
+        v.claLayer ?? "",
+        v.subsystem ?? "",
+        v.status ?? "",
+        tags.join(","),
+        ...links.map(linkPart),
+        v.body.trim(),
+    ];
+    if ((v.shared ?? "").length > 0)
+        parts.push(v.shared);
+    return parts.join("\n");
+}
+/** 8-hex content signature stored as the note's `h` key. */
+export function contentSignature(v) {
+    return fnv1a32(canonicalContent(v));
+}
+/**
+ * Stamp recency metadata onto `next` before writing it.
+ * - `prev` is the note's prior on-disk state (undefined = creation).
+ * - A content change (signature differs, or creation) bumps modified/rev/source.
+ *   A cosmetic change (x/y only) preserves them.
+ * - `h` is always refreshed to the current content signature.
+ */
+export function stampMeta(prev, next, source, now) {
+    const ts = (now ?? new Date()).toISOString();
+    const sig = contentSignature(next);
+    const created = prev?.created ?? next.created ?? ts;
+    const contentChanged = prev === undefined || contentSignature(prev) !== sig;
+    if (contentChanged) {
+        return { ...next, created, modified: ts, rev: (prev?.rev ?? 0) + 1, source, h: sig };
+    }
+    return {
+        ...next,
+        created,
+        modified: prev.modified ?? ts,
+        rev: prev.rev === 0 ? 1 : prev.rev,
+        source: prev.source ?? source,
+        h: sig,
+    };
+}

package/dist/engine/storage.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Storage seam for the engine — a small filesystem-like interface plus an
+ * in-memory implementation for tests. The Obsidian-backed implementation lives
+ * in `obsidianStorage.ts` (kept separate so this module and the engine never
+ * import the `obsidian` package and stay unit-testable in plain Node).
+ *
+ * All paths are vault-relative, "/"-separated.
+ */
+export interface DirListing {
+    files: string[];
+    folders: string[];
+}
+export interface VaultStorage {
+    exists(path: string): Promise<boolean>;
+    read(path: string): Promise<string>;
+    write(path: string, data: string): Promise<void>;
+    remove(path: string): Promise<void>;
+    /** Create `path` and any missing ancestor folders. */
+    mkdirs(path: string): Promise<void>;
+    /** Remove a folder and everything under it. */
+    rmdir(path: string): Promise<void>;
+    /**
+     * Move/rename a file or folder (and everything under it) from one
+     * vault-relative path to another, creating the destination's parent as needed.
+     * The Obsidian implementation routes through `fileManager.renameFile` so every
+     * wikilink/backlink pointing into the moved tree (subsystem anchors included)
+     * is rewritten to the new location.
+     */
+    move(from: string, to: string): Promise<void>;
+    /** Immediate children of `path` (vault-relative paths). */
+    list(path: string): Promise<DirListing>;
+}
+/** Join + normalize vault-relative path segments. */
+export declare function joinPath(...parts: string[]): string;
+export declare function parentPath(path: string): string;
+export declare function baseName(path: string): string;
+/** In-memory storage for tests. */
+export declare class MemoryStorage implements VaultStorage {
+    private files;
+    private folders;
+    exists(path: string): Promise<boolean>;
+    read(path: string): Promise<string>;
+    write(path: string, data: string): Promise<void>;
+    remove(path: string): Promise<void>;
+    mkdirs(path: string): Promise<void>;
+    rmdir(path: string): Promise<void>;
+    move(from: string, to: string): Promise<void>;
+    list(path: string): Promise<DirListing>;
+}

package/dist/engine/storage.js

@@ -0,0 +1,116 @@
+/**
+ * Storage seam for the engine — a small filesystem-like interface plus an
+ * in-memory implementation for tests. The Obsidian-backed implementation lives
+ * in `obsidianStorage.ts` (kept separate so this module and the engine never
+ * import the `obsidian` package and stay unit-testable in plain Node).
+ *
+ * All paths are vault-relative, "/"-separated.
+ */
+/** Join + normalize vault-relative path segments. */
+export function joinPath(...parts) {
+    return parts
+        .flatMap((p) => p.split("/"))
+        .filter((s) => s.length > 0 && s !== ".")
+        .join("/");
+}
+export function parentPath(path) {
+    const i = path.lastIndexOf("/");
+    return i < 0 ? "" : path.substring(0, i);
+}
+export function baseName(path) {
+    const i = path.lastIndexOf("/");
+    return i < 0 ? path : path.substring(i + 1);
+}
+/** In-memory storage for tests. */
+export class MemoryStorage {
+    constructor() {
+        this.files = new Map();
+        this.folders = new Set([""]);
+    }
+    async exists(path) {
+        const p = joinPath(path);
+        return this.files.has(p) || this.folders.has(p);
+    }
+    async read(path) {
+        const p = joinPath(path);
+        const v = this.files.get(p);
+        if (v === undefined)
+            throw new Error(`ENOENT: ${p}`);
+        return v;
+    }
+    async write(path, data) {
+        const p = joinPath(path);
+        await this.mkdirs(parentPath(p));
+        this.files.set(p, data);
+    }
+    async remove(path) {
+        this.files.delete(joinPath(path));
+    }
+    async mkdirs(path) {
+        const p = joinPath(path);
+        if (p === "")
+            return;
+        const segs = p.split("/");
+        let cur = "";
+        for (const s of segs) {
+            cur = cur === "" ? s : `${cur}/${s}`;
+            this.folders.add(cur);
+        }
+    }
+    async rmdir(path) {
+        const p = joinPath(path);
+        const prefix = p + "/";
+        for (const f of [...this.files.keys()]) {
+            if (f === p || f.startsWith(prefix))
+                this.files.delete(f);
+        }
+        for (const d of [...this.folders]) {
+            if (d === p || d.startsWith(prefix))
+                this.folders.delete(d);
+        }
+    }
+    async move(from, to) {
+        const src = joinPath(from);
+        const dst = joinPath(to);
+        if (src === dst)
+            return;
+        await this.mkdirs(parentPath(dst));
+        const prefix = src + "/";
+        const rename = (p) => (p === src ? dst : dst + "/" + p.substring(prefix.length));
+        for (const f of [...this.files.keys()]) {
+            if (f === src || f.startsWith(prefix)) {
+                this.files.set(rename(f), this.files.get(f));
+                this.files.delete(f);
+            }
+        }
+        for (const d of [...this.folders]) {
+            if (d === src || d.startsWith(prefix)) {
+                this.folders.delete(d);
+                this.folders.add(rename(d));
+            }
+        }
+    }
+    async list(path) {
+        const p = joinPath(path);
+        const prefix = p === "" ? "" : p + "/";
+        const files = [];
+        const folders = [];
+        for (const f of this.files.keys()) {
+            if (f.startsWith(prefix)) {
+                const rest = f.substring(prefix.length);
+                if (rest.length > 0 && !rest.includes("/"))
+                    files.push(f);
+            }
+        }
+        for (const d of this.folders) {
+            if (d === "")
+                continue;
+            if (d.startsWith(prefix)) {
+                const rest = d.substring(prefix.length);
+                if (rest.length > 0 && !rest.includes("/"))
+                    folders.push(d);
+            }
+        }
+        return { files: files.sort(), folders: folders.sort() };
+    }
+}

package/dist/engine/subsystemLinks.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Subsystem-link resolution + parent-anchor derivation — the TypeScript mirror
+ * of `core/lib/vault/subsystem_link.dart`. A node's `subsystem` field holds a
+ * relative wikilink `[[../<dir>/System|<alias>]]` pointing DOWN into a child
+ * model; deriving parents is the inverse — scanning other models for nodes that
+ * point at us. Pure: IO is injected via `readNodes` so it stays unit-testable.
+ */
+import { VariableFile } from "./types";
+/** One parent-model node that anchors a given child model as its subsystem. */
+export interface ParentAnchor {
+    modelFolder: string;
+    modelName: string;
+    anchorVarId: string;
+    anchorVarLabel: string;
+}
+/** The minimal model identity the link rules need. */
+export interface ModelKey {
+    folder: string;
+    name: string;
+}
+/** Parse `[[../<dir>/System|<alias>]]` into its folder-basename hint + alias. */
+export declare function parseSubsystemLink(raw: string): {
+    dir: string | null;
+    alias: string | null;
+};
+/** Does a stored subsystem link resolve to `model`? Folder basename, then name. */
+export declare function linkPointsToModel(raw: string, model: ModelKey): boolean;
+/** Scan `others` for nodes whose `subsystem` link points back at `current`. */
+export declare function deriveParentAnchors(current: ModelKey, others: ModelKey[], readNodes: (folder: string) => Promise<VariableFile[]>): Promise<ParentAnchor[]>;