@nodes-dev/core 0.0.0

package/dist/snapshot.js

@@ -0,0 +1,252 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { NodeId } from "./ids.js";
+import { SearchIndex } from "./search.js";
+import { VectorIndex } from "./similarity.js";
+import { Index } from "./structural-index.js";
+export const SNAPSHOT_SCHEMA_VERSION = 1;
+export const SNAPSHOT_LANG = "ts";
+const SHA256_RE = /^[0-9a-f]{64}$/;
+const SNAPSHOT_KEYS = ["version", "lang", "manifest", "structural", "search", "vectors"];
+const MANIFEST_ROW_KEYS = ["path", "sha256", "uid"];
+export function snapshotPath(root) {
+    return join(root, ".nodes-index", "snapshot.ts.json");
+}
+export function hashBytes(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+/** Root-relative POSIX path (forward slashes on every platform), the cross-language form. */
+function relPosix(root, full) {
+    return relative(root, full).split(/[\\/]/).join("/");
+}
+function listCorpusMarkdownPaths(root) {
+    const files = [];
+    const walk = (dir) => {
+        if (!existsSync(dir))
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = join(dir, entry.name);
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                if (relPosix(root, full) === ".nodes-index")
+                    continue;
+                walk(full);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".md")) {
+                files.push({ path: relPosix(root, full), fullPath: full });
+            }
+        }
+    };
+    walk(root);
+    files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return files;
+}
+/** Byte-level walk: read each .md file's bytes once and hash them. Skips the private
+ * `.nodes-index` tree, symlinks, and non-files. Sorted by root-relative POSIX path so the
+ * order matches Python's `sorted(root.rglob("*.md"))`. */
+export function iterCorpusFiles(root) {
+    return listCorpusMarkdownPaths(root).map(({ path, fullPath }) => {
+        const data = readFileSync(fullPath);
+        return { path, data, sha256: hashBytes(data) };
+    });
+}
+/** Stat-level walk over the same corpus file set as `iterCorpusFiles`. Does not read file bodies. */
+export function listCorpusFileStats(root) {
+    return listCorpusMarkdownPaths(root).map(({ path, fullPath }) => {
+        const stat = statSync(fullPath);
+        return { path, mtimeMs: stat.mtimeMs, size: stat.size };
+    });
+}
+/** Cheap external-change fingerprint for resident consumers. Not a content-identity hash. */
+export function readCorpusFingerprint(root) {
+    return { files: listCorpusFileStats(root) };
+}
+export function sameCorpusFingerprint(a, b) {
+    if (a.files.length !== b.files.length)
+        return false;
+    for (let i = 0; i < a.files.length; i++) {
+        const left = a.files[i];
+        const right = b.files[i];
+        if (left.path !== right.path || left.mtimeMs !== right.mtimeMs || left.size !== right.size)
+            return false;
+    }
+    return true;
+}
+/** Write JSON atomically (tmp + rename). Rejects any non-finite number — JS `JSON.stringify`
+ * silently emits `null` for NaN/Infinity, so a replacer enforces the rejection (parity with
+ * Python's `json.dumps(..., allow_nan=False)`). Throws before any write, so no partial file. */
+export function writeJsonAtomic(path, obj) {
+    const payload = JSON.stringify(obj, (_key, value) => {
+        if (typeof value === "number" && !Number.isFinite(value)) {
+            throw new RangeError("cannot serialize non-finite number to JSON");
+        }
+        return value;
+    });
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, payload, "utf-8");
+    renameSync(tmp, path);
+}
+/** Read + parse JSON. Returns `null` only for a genuinely-absent path. A directory, a broken
+ * symlink, or invalid JSON throws (JS `JSON.parse` already rejects the `NaN`/`Infinity`
+ * constants, so Python's explicit `parse_constant` guard is free here). */
+export function readJson(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf-8");
+    }
+    catch (e) {
+        const err = e;
+        if (err.code === "ENOENT") {
+            try {
+                lstatSync(path); // a broken symlink reads ENOENT but lstats fine
+            }
+            catch {
+                return null; // genuinely absent
+            }
+            throw err; // path exists as a (broken) symlink
+        }
+        throw err; // EISDIR and anything else
+    }
+    return JSON.parse(raw);
+}
+export function pathForNodeId(nodeId) {
+    const nid = NodeId.parse(nodeId);
+    return `${nid.kind}/${nid.slug.replace(/:/g, "__")}.md`;
+}
+export function writeSnapshot(root, manifest, index, searchIndex, vectorIndex) {
+    const doc = {
+        version: SNAPSHOT_SCHEMA_VERSION,
+        lang: SNAPSHOT_LANG,
+        manifest: manifest.map((m) => ({ path: m.path, sha256: m.sha256, uid: m.uid })),
+        structural: index.toDict(),
+        search: searchIndex.toDict(),
+        vectors: vectorIndex !== undefined ? vectorIndex.toDict() : null,
+    };
+    writeJsonAtomic(snapshotPath(root), doc);
+}
+function validateManifestPath(path) {
+    const parts = path.split("/");
+    if (!path ||
+        path.startsWith("/") ||
+        path.includes("\\") ||
+        path.endsWith("/") ||
+        !path.endsWith(".md") ||
+        parts[0] === ".nodes-index" ||
+        parts.some((part) => part === "" || part === "." || part === "..")) {
+        throw new Error("snapshot manifest row path must be a root-relative POSIX .md path");
+    }
+}
+function parseManifest(raw) {
+    if (!Array.isArray(raw))
+        throw new Error("snapshot manifest is not an array");
+    const entries = [];
+    for (const e of raw) {
+        if (typeof e !== "object" || e === null)
+            throw new Error("snapshot manifest row is not an object");
+        const row = e;
+        for (const key of MANIFEST_ROW_KEYS) {
+            if (!(key in row))
+                throw new Error(`snapshot manifest row missing ${key}`);
+        }
+        const { path, sha256, uid } = row;
+        if (typeof path !== "string")
+            throw new Error("snapshot manifest row path must be a string");
+        validateManifestPath(path);
+        if (typeof sha256 !== "string")
+            throw new Error("snapshot manifest row sha256 must be a string");
+        if (!SHA256_RE.test(sha256))
+            throw new Error("snapshot manifest row sha256 must be 64 lowercase hex chars");
+        if (typeof uid !== "string")
+            throw new Error("snapshot manifest row uid must be a string");
+        entries.push({ path, sha256, uid });
+    }
+    if (new Set(entries.map((m) => m.uid)).size !== entries.length)
+        throw new Error("snapshot manifest: duplicate uid");
+    if (new Set(entries.map((m) => m.path)).size !== entries.length)
+        throw new Error("snapshot manifest: duplicate path");
+    return entries;
+}
+function setsEqual(a, b) {
+    return a.size === b.size && [...a].every((x) => b.has(x));
+}
+function mapsEqual(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const [k, v] of a)
+        if (b.get(k) !== v)
+            return false;
+    return true;
+}
+/** Reads and validates ONLY the cache file. Returns null for any cache problem (missing file,
+ * invalid JSON, version/lang mismatch, integrity failure, embedder-configured vector mismatch).
+ * Never parses corpus files, so it can never raise a corpus error — any throw here is a cache
+ * problem and resolves to a silent full rebuild upstream. */
+export function loadSnapshot(root, embedderNamespace) {
+    try {
+        const doc = readJson(snapshotPath(root));
+        if (doc === null)
+            return null;
+        if (typeof doc !== "object")
+            return null;
+        const d = doc;
+        for (const key of SNAPSHOT_KEYS) {
+            if (!(key in d))
+                throw new Error(`snapshot document missing ${key}`);
+        }
+        if (d.version !== SNAPSHOT_SCHEMA_VERSION || d.lang !== SNAPSHOT_LANG)
+            return null;
+        const manifest = parseManifest(d.manifest);
+        const manifestUids = new Set(manifest.map((m) => m.uid));
+        const index = Index.fromDict(d.structural);
+        if (!setsEqual(new Set(index.byUid.keys()), manifestUids))
+            return null;
+        const expectedIds = new Map();
+        for (const [uid, entry] of index.byUid)
+            expectedIds.set(uid, entry.id);
+        for (const m of manifest) {
+            if (m.path !== pathForNodeId(expectedIds.get(m.uid))) {
+                throw new Error("snapshot manifest path does not match structural id");
+            }
+        }
+        const searchIndex = SearchIndex.fromDict(d.search);
+        if (!setsEqual(new Set(searchIndex.lengths.keys()), manifestUids))
+            return null;
+        if (!mapsEqual(searchIndex.idByUid, expectedIds))
+            return null;
+        let vectorIndex = null;
+        if (embedderNamespace !== null) {
+            const vec = d.vectors;
+            if (typeof vec !== "object" || vec === null)
+                return null;
+            if (vec.namespace !== embedderNamespace)
+                return null;
+            vectorIndex = VectorIndex.fromDict(vec);
+            if (!setsEqual(new Set(vectorIndex.vectors.keys()), manifestUids))
+                return null;
+            if (!mapsEqual(vectorIndex.idByUid, expectedIds))
+                return null;
+        }
+        return { manifest, index, searchIndex, vectorIndex };
+    }
+    catch (e) {
+        // loadSnapshot only ever reads the cache file, so any thrown Error is a cache problem
+        // (absent/locked file, malformed JSON, failed integrity check) -> rebuild. This is the
+        // closest faithful mirror of Python's `except (OSError, ValueError)`: every cache-unusable
+        // signal here surfaces as an Error subclass, while JS's error taxonomy gives no class-based
+        // way to separate them further. A non-Error throw is not a cache signal — rethrow it.
+        if (!(e instanceof Error))
+            throw e;
+        return null;
+    }
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"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"}

package/dist/store.d.ts

@@ -0,0 +1,15 @@
+import type { Node } from "./node.js";
+/**
+ * Pure file mechanics over a corpus directory. No cross-corpus logic.
+ * Collision detection, ref resolution, and rename live in `Corpus`/`Index`.
+ */
+export declare class Store {
+    readonly root: string;
+    constructor(root: string);
+    pathFor(nodeId: string): string;
+    writeFile(node: Node): string;
+    readFile(nodeId: string): Node;
+    deleteFile(nodeId: string): void;
+    allNodes(): Node[];
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGtC;;;GAGG;AACH,qBAAa,KAAK;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM;IAIxB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAK/B,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM;IAO7B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQ9B,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQhC,QAAQ,IAAI,IAAI,EAAE;CAGnB"}

package/dist/store.js

@@ -0,0 +1,44 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { RefError } from "./errors.js";
+import { nodeFromMarkdown, nodeToMarkdown } from "./frontmatter.js";
+import { NodeId } from "./ids.js";
+import { iterCorpusFiles } from "./snapshot.js";
+/**
+ * Pure file mechanics over a corpus directory. No cross-corpus logic.
+ * Collision detection, ref resolution, and rename live in `Corpus`/`Index`.
+ */
+export class Store {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    pathFor(nodeId) {
+        const nid = NodeId.parse(nodeId);
+        return join(this.root, nid.kind, `${nid.slug.replace(/:/g, "__")}.md`);
+    }
+    writeFile(node) {
+        const path = this.pathFor(node.id);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, nodeToMarkdown(node), "utf-8");
+        return path;
+    }
+    readFile(nodeId) {
+        const path = this.pathFor(nodeId);
+        if (!(existsSync(path) && statSync(path).isFile())) {
+            throw new RefError(`no node at ${JSON.stringify(nodeId)}`);
+        }
+        return nodeFromMarkdown(readFileSync(path, "utf-8"));
+    }
+    deleteFile(nodeId) {
+        const path = this.pathFor(nodeId);
+        if (!(existsSync(path) && statSync(path).isFile())) {
+            throw new RefError(`no node at ${JSON.stringify(nodeId)}`);
+        }
+        rmSync(path);
+    }
+    allNodes() {
+        return iterCorpusFiles(this.root).map((f) => nodeFromMarkdown(f.data.toString("utf-8")));
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC/F,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD;;;GAGG;AACH,MAAM,OAAO,KAAK;IACP,IAAI,CAAS;IAEtB,YAAY,IAAY;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,OAAO,CAAC,MAAc;QACpB,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IACzE,CAAC;IAED,SAAS,CAAC,IAAU;QAClB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACnC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9C,aAAa,CAAC,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,QAAQ,CAAC,MAAc;QACrB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAClC,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;YACnD,MAAM,IAAI,QAAQ,CAAC,cAAc,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC7D,CAAC;QACD,OAAO,gBAAgB,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IACvD,CAAC;IAED,UAAU,CAAC,MAAc;QACvB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAClC,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;YACnD,MAAM,IAAI,QAAQ,CAAC,cAAc,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC7D,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IAED,QAAQ;QACN,OAAO,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3F,CAAC;CACF"}

package/dist/structural-index.d.ts

@@ -0,0 +1,72 @@
+import type { Node } from "./node.js";
+import { type Relation } from "./relations.js";
+export type Role = "relation_source" | "relation_target" | "membership_member" | "edges_source" | "edges_target" | "order_member" | "keys_value";
+export interface OutRef {
+    ref: string;
+    role: Role;
+    relation?: Relation;
+}
+export interface InRef {
+    sourceUid: string;
+    outRef: OutRef;
+}
+export interface IndexEntry {
+    uid: string;
+    id: string;
+    kind: string;
+    deprecatedIds: ReadonlySet<string>;
+    outRefs: OutRef[];
+}
+export interface ResolvedEdge {
+    relation: Relation;
+    sourceUid: string | null;
+    targetUid: string | null;
+}
+/** In-memory structural index. Pure data; no file I/O. */
+export declare class Index {
+    byUid: Map<string, IndexEntry>;
+    idToUid: Map<string, string>;
+    deprecatedToUid: Map<string, string>;
+    inRefs: Map<string, InRef[]>;
+    static build(nodes: Iterable<Node>): Index;
+    resolveUid(ref: string): string | null;
+    assertAddable(node: Node): void;
+    upsert(node: Node): void;
+    toDict(): {
+        entries: Array<{
+            uid: string;
+            id: string;
+            kind: string;
+            deprecatedIds: string[];
+            relations: Array<Record<string, unknown>>;
+            structuralRefs: Array<{
+                ref: string;
+                role: Role;
+            }>;
+        }>;
+    };
+    static fromDict(d: unknown): Index;
+    remove(uid: string): void;
+    private drop;
+    private refsForUid;
+    private resolveEdge;
+    private relationsByRole;
+    outboundEdges(uid: string): ResolvedEdge[];
+    inboundEdges(uid: string): ResolvedEdge[];
+    danglingEdges(): ResolvedEdge[];
+    /** Uids of this node's resolvable direct members. Dangling member refs are skipped
+     * (check reports them); duplicate entries and live+deprecated refs dedupe by uid. */
+    membersOf(uid: string): Set<string>;
+    /** Uids of the nodes whose membership facet lists any of this node's identity claims
+     * (live id or deprecated ids — the same attribution rule as relationsByRole). */
+    containersOf(uid: string): Set<string>;
+    /** Transitive membership closure (BFS). The visited set is seeded with the start uid,
+     * which is excluded from the result even when a membership cycle reaches it. */
+    membershipClosure(uid: string, direction: "members" | "containers"): Set<string>;
+    /** Every unresolved membership ref, deduped by (container uid, ref). */
+    danglingMembers(): Array<{
+        sourceUid: string;
+        ref: string;
+    }>;
+}
+//# sourceMappingURL=structural-index.d.ts.map

package/dist/structural-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-index.d.ts","sourceRoot":"","sources":["../src/structural-index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,KAAK,QAAQ,EAAkB,MAAM,gBAAgB,CAAC;AAG/D,MAAM,MAAM,IAAI,GACZ,iBAAiB,GACjB,iBAAiB,GACjB,mBAAmB,GACnB,cAAc,GACd,cAAc,GACd,cAAc,GACd,YAAY,CAAC;AAWjB,MAAM,WAAW,MAAM;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,MAAM,WAAW,KAAK;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACnC,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,QAAQ,CAAC;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AA0GD,0DAA0D;AAC1D,qBAAa,KAAK;IAChB,KAAK,0BAAiC;IACtC,OAAO,sBAA6B;IACpC,eAAe,sBAA6B;IAC5C,MAAM,uBAA8B;IAEpC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK;IAY1C,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAOtC,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAiB/B,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAmBxB,MAAM,IAAI;QACR,OAAO,EAAE,KAAK,CAAC;YACb,GAAG,EAAE,MAAM,CAAC;YACZ,EAAE,EAAE,MAAM,CAAC;YACX,IAAI,EAAE,MAAM,CAAC;YACb,aAAa,EAAE,MAAM,EAAE,CAAC;YACxB,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;YAC1C,cAAc,EAAE,KAAK,CAAC;gBAAE,GAAG,EAAE,MAAM,CAAC;gBAAC,IAAI,EAAE,IAAI,CAAA;aAAE,CAAC,CAAC;SACpD,CAAC,CAAC;KACJ;IA+BD,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,KAAK;IAqElC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,OAAO,CAAC,IAAI;IAkBZ,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,eAAe;IAevB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,EAAE;IAI1C,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,EAAE;IAIzC,aAAa,IAAI,YAAY,EAAE;IAkB/B;yFACqF;IACrF,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;IAYnC;qFACiF;IACjF,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;IAWtC;oFACgF;IAChF,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,YAAY,GAAG,GAAG,CAAC,MAAM,CAAC;IAiBhF,wEAAwE;IACxE,eAAe,IAAI,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CAe7D"}