backpack-ontology 0.2.25 → 0.3.0

package/dist/core/remote-registry.js

@@ -0,0 +1,296 @@
+// ============================================================
+// Local registry of remote learning graphs.
+//
+// Stores user subscriptions to graphs hosted at HTTPS URLs.
+// Persists to ~/.local/share/backpack/remotes.json.
+// Caches fetched graph contents to ~/.local/share/backpack/remote-cache/<name>.json.
+//
+// This module owns the registry file and the cache directory. It does
+// NOT fetch URLs (that's remote-fetch.ts) and does NOT validate graph
+// content (that's remote-schema.ts). It glues those together and
+// persists state.
+// ============================================================
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+import { dataDir } from "./paths.js";
+import { remoteFetch, RemoteFetchError } from "./remote-fetch.js";
+import { validateRemoteGraph, RemoteSchemaError } from "./remote-schema.js";
+const REGISTRY_VERSION = 1;
+const NAME_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+// --- Errors ---
+export class RemoteRegistryError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "RemoteRegistryError";
+    }
+}
+// --- Helpers ---
+function emptyRegistry() {
+    return { version: REGISTRY_VERSION, remotes: [] };
+}
+function validateName(name) {
+    if (typeof name !== "string" || !NAME_RE.test(name)) {
+        throw new RemoteRegistryError(`invalid remote name '${name}': must match /^[a-z0-9][a-z0-9_-]{0,63}$/`, "INVALID_NAME");
+    }
+}
+function sha256Hex(s) {
+    return crypto.createHash("sha256").update(s).digest("hex");
+}
+// --- The registry class ---
+export class RemoteRegistry {
+    baseDir;
+    constructor(baseDir) {
+        this.baseDir = baseDir ?? dataDir();
+    }
+    registryFile() {
+        return path.join(this.baseDir, "remotes.json");
+    }
+    cacheDir() {
+        return path.join(this.baseDir, "remote-cache");
+    }
+    cacheFile(name) {
+        validateName(name);
+        const resolved = path.resolve(this.cacheDir(), `${name}.json`);
+        const cacheRoot = path.resolve(this.cacheDir());
+        // Defense in depth: ensure the resolved path is inside the cache dir
+        if (!resolved.startsWith(cacheRoot + path.sep) && resolved !== cacheRoot) {
+            throw new RemoteRegistryError(`cache path escapes cache directory`, "PATH_TRAVERSAL");
+        }
+        return resolved;
+    }
+    /**
+     * Ensures the base directory and cache directory exist.
+     * Safe to call multiple times.
+     */
+    async initialize() {
+        await fs.mkdir(this.baseDir, { recursive: true });
+        await fs.mkdir(this.cacheDir(), { recursive: true });
+    }
+    /**
+     * Reads the registry file. Returns an empty registry if the file
+     * doesn't exist yet.
+     */
+    async load() {
+        try {
+            const text = await fs.readFile(this.registryFile(), "utf8");
+            const parsed = JSON.parse(text);
+            if (typeof parsed !== "object" ||
+                parsed === null ||
+                parsed.version !== REGISTRY_VERSION ||
+                !Array.isArray(parsed.remotes)) {
+                throw new RemoteRegistryError("registry file is malformed", "CORRUPT_REGISTRY");
+            }
+            return parsed;
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                return emptyRegistry();
+            }
+            throw err;
+        }
+    }
+    /**
+     * Atomically writes the registry file.
+     */
+    async save(reg) {
+        const tmp = `${this.registryFile()}.tmp`;
+        await fs.writeFile(tmp, JSON.stringify(reg, null, 2), "utf8");
+        await fs.rename(tmp, this.registryFile());
+    }
+    /**
+     * List all registered remotes.
+     */
+    async list() {
+        const reg = await this.load();
+        return reg.remotes;
+    }
+    /**
+     * Look up a single remote by name.
+     */
+    async get(name) {
+        validateName(name);
+        const reg = await this.load();
+        return reg.remotes.find((r) => r.name === name) ?? null;
+    }
+    /**
+     * Register a new remote: validate the name, fetch the URL, validate
+     * the graph schema, write to cache, and append to the registry.
+     *
+     * Throws if the name already exists, if the URL fails to fetch, or
+     * if the schema validation fails.
+     *
+     * The caller is responsible for ensuring the name does not collide
+     * with a local graph (this module doesn't know about local graphs).
+     */
+    async register(opts) {
+        validateName(opts.name);
+        await this.initialize();
+        const reg = await this.load();
+        if (reg.remotes.some((r) => r.name === opts.name)) {
+            throw new RemoteRegistryError(`remote '${opts.name}' is already registered`, "DUPLICATE_NAME");
+        }
+        // Fetch
+        let result;
+        try {
+            result = await remoteFetch(opts.url);
+        }
+        catch (err) {
+            if (err instanceof RemoteFetchError) {
+                throw new RemoteRegistryError(`fetch failed: ${err.message}`, err.code);
+            }
+            throw err;
+        }
+        // Parse + validate
+        let parsed;
+        try {
+            parsed = JSON.parse(result.body);
+        }
+        catch (err) {
+            throw new RemoteRegistryError(`response is not valid JSON: ${err.message}`, "INVALID_JSON");
+        }
+        let validated;
+        try {
+            validated = validateRemoteGraph(parsed);
+        }
+        catch (err) {
+            if (err instanceof RemoteSchemaError) {
+                throw new RemoteRegistryError(`schema validation failed: ${err.message}`, "SCHEMA_ERROR");
+            }
+            throw err;
+        }
+        // Write cache atomically
+        const cachePath = this.cacheFile(opts.name);
+        const cacheBody = JSON.stringify(validated.data);
+        const tmp = `${cachePath}.tmp`;
+        await fs.writeFile(tmp, cacheBody, "utf8");
+        await fs.rename(tmp, cachePath);
+        const now = new Date().toISOString();
+        const entry = {
+            name: opts.name,
+            url: opts.url,
+            source: opts.source,
+            addedAt: now,
+            lastFetched: now,
+            etag: result.etag,
+            sha256: sha256Hex(cacheBody),
+            pinned: !!opts.pin,
+            sizeBytes: cacheBody.length,
+        };
+        reg.remotes.push(entry);
+        await this.save(reg);
+        return entry;
+    }
+    /**
+     * Refetch a registered remote. Uses ETag for conditional GET.
+     *
+     * If pinned and the SHA256 changes, throws RemoteRegistryError with
+     * code "PIN_VIOLATION" without overwriting the cache.
+     */
+    async refresh(name) {
+        validateName(name);
+        const reg = await this.load();
+        const existing = reg.remotes.find((r) => r.name === name);
+        if (!existing) {
+            throw new RemoteRegistryError(`remote '${name}' is not registered`, "NOT_FOUND");
+        }
+        let result;
+        try {
+            result = await remoteFetch(existing.url, {
+                ifNoneMatch: existing.etag ?? undefined,
+            });
+        }
+        catch (err) {
+            if (err instanceof RemoteFetchError) {
+                throw new RemoteRegistryError(`fetch failed: ${err.message}`, err.code);
+            }
+            throw err;
+        }
+        if (result.notModified) {
+            existing.lastFetched = new Date().toISOString();
+            await this.save(reg);
+            return { entry: existing, changed: false, notModified: true };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(result.body);
+        }
+        catch (err) {
+            throw new RemoteRegistryError(`response is not valid JSON: ${err.message}`, "INVALID_JSON");
+        }
+        let validated;
+        try {
+            validated = validateRemoteGraph(parsed);
+        }
+        catch (err) {
+            if (err instanceof RemoteSchemaError) {
+                throw new RemoteRegistryError(`schema validation failed: ${err.message}`, "SCHEMA_ERROR");
+            }
+            throw err;
+        }
+        const cacheBody = JSON.stringify(validated.data);
+        const newSha = sha256Hex(cacheBody);
+        const changed = newSha !== existing.sha256;
+        if (existing.pinned && changed) {
+            throw new RemoteRegistryError(`remote '${name}' is pinned and content has changed (was ${existing.sha256}, now ${newSha})`, "PIN_VIOLATION");
+        }
+        const cachePath = this.cacheFile(name);
+        const tmp = `${cachePath}.tmp`;
+        await fs.writeFile(tmp, cacheBody, "utf8");
+        await fs.rename(tmp, cachePath);
+        existing.lastFetched = new Date().toISOString();
+        existing.etag = result.etag;
+        existing.sha256 = newSha;
+        existing.sizeBytes = cacheBody.length;
+        await this.save(reg);
+        return { entry: existing, changed, notModified: false };
+    }
+    /**
+     * Remove a remote from the registry and delete its cache file.
+     */
+    async unregister(name) {
+        validateName(name);
+        const reg = await this.load();
+        const idx = reg.remotes.findIndex((r) => r.name === name);
+        if (idx === -1) {
+            throw new RemoteRegistryError(`remote '${name}' is not registered`, "NOT_FOUND");
+        }
+        reg.remotes.splice(idx, 1);
+        await this.save(reg);
+        // Best-effort cache deletion
+        try {
+            await fs.unlink(this.cacheFile(name));
+        }
+        catch (err) {
+            if (err.code !== "ENOENT") {
+                throw err;
+            }
+        }
+    }
+    /**
+     * Load the cached graph contents for a registered remote.
+     * Throws if the remote is not registered or the cache file is missing.
+     */
+    async loadCached(name) {
+        validateName(name);
+        const reg = await this.load();
+        const entry = reg.remotes.find((r) => r.name === name);
+        if (!entry) {
+            throw new RemoteRegistryError(`remote '${name}' is not registered`, "NOT_FOUND");
+        }
+        let text;
+        try {
+            text = await fs.readFile(this.cacheFile(name), "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                throw new RemoteRegistryError(`cache file for '${name}' is missing — try refreshing`, "CACHE_MISSING");
+            }
+            throw err;
+        }
+        return JSON.parse(text);
+    }
+}
+//# sourceMappingURL=remote-registry.js.map

package/dist/core/remote-registry.js.map

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

package/dist/core/remote-schema.d.ts

@@ -0,0 +1,31 @@
+import type { LearningGraphData } from "./types.js";
+export declare const REMOTE_GRAPH_LIMITS: {
+    readonly maxNodes: 50000;
+    readonly maxEdges: 200000;
+    readonly maxPropertyKeys: 64;
+    readonly maxPropertyKeyLength: 128;
+    readonly maxPropertyStringLength: 16384;
+    readonly maxArrayLength: 256;
+    readonly maxIdLength: 256;
+    readonly maxTypeLength: 128;
+    readonly maxNameLength: 256;
+    readonly maxDescriptionLength: 4096;
+};
+export declare class RemoteSchemaError extends Error {
+    readonly path: string;
+    constructor(message: string, path: string);
+}
+/**
+ * Validates a parsed JSON value against the remote graph schema.
+ * Throws RemoteSchemaError on any violation.
+ *
+ * The returned object is a fresh, type-safe LearningGraphData. Edges
+ * that reference node IDs not in the graph are dropped (not an error —
+ * remote graphs may legitimately have hanging references after partial
+ * exports). Use the `droppedEdges` count from the result if you care.
+ */
+export declare function validateRemoteGraph(raw: unknown): {
+    data: LearningGraphData;
+    droppedEdges: number;
+};
+//# sourceMappingURL=remote-schema.d.ts.map

package/dist/core/remote-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-schema.d.ts","sourceRoot":"","sources":["../../src/core/remote-schema.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,iBAAiB,EAAc,MAAM,YAAY,CAAC;AAIhE,eAAO,MAAM,mBAAmB;;;;;;;;;;;CAWtB,CAAC;AAIX,qBAAa,iBAAkB,SAAQ,KAAK;aAGxB,IAAI,EAAE,MAAM;gBAD5B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM;CAK/B;AAwND;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG;IACjD,IAAI,EAAE,iBAAiB,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;CACtB,CAmGA"}

package/dist/core/remote-schema.js

@@ -0,0 +1,252 @@
+// ============================================================
+// Strict validation for remote learning graphs.
+//
+// Anything fetched from a third-party URL must pass through this
+// validator before any other code touches it. The goal is to:
+//   1. Reject malformed input that could crash the parser
+//   2. Reject oversized graphs that could exhaust memory
+//   3. Reject unknown structures that could carry future exploits
+//   4. Coerce property values to a safe primitive subset
+//
+// This is intentionally STRICTER than the schema used for local
+// graphs. Local graphs are trusted (the user wrote them); remote
+// graphs are not.
+// ============================================================
+// --- Limits ---
+export const REMOTE_GRAPH_LIMITS = {
+    maxNodes: 50_000,
+    maxEdges: 200_000,
+    maxPropertyKeys: 64,
+    maxPropertyKeyLength: 128,
+    maxPropertyStringLength: 16_384,
+    maxArrayLength: 256,
+    maxIdLength: 256,
+    maxTypeLength: 128,
+    maxNameLength: 256,
+    maxDescriptionLength: 4_096,
+};
+// --- Errors ---
+export class RemoteSchemaError extends Error {
+    path;
+    constructor(message, path) {
+        super(`${path}: ${message}`);
+        this.path = path;
+        this.name = "RemoteSchemaError";
+    }
+}
+// --- Validators ---
+function isPlainObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.getPrototypeOf(value) === Object.prototype);
+}
+function validateString(value, path, maxLength, required = true) {
+    if (value === undefined || value === null) {
+        if (required) {
+            throw new RemoteSchemaError("missing required string", path);
+        }
+        return "";
+    }
+    if (typeof value !== "string") {
+        throw new RemoteSchemaError(`expected string, got ${typeof value}`, path);
+    }
+    if (value.length > maxLength) {
+        throw new RemoteSchemaError(`string exceeds max length ${maxLength} (got ${value.length})`, path);
+    }
+    return value;
+}
+/**
+ * Validates a property value. Allowed: string, number (finite), boolean,
+ * or array of those primitives. Rejects nested objects, functions, symbols,
+ * bigints, and any non-finite numbers.
+ */
+function validatePropertyValue(value, path) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (typeof value === "string") {
+        if (value.length > REMOTE_GRAPH_LIMITS.maxPropertyStringLength) {
+            throw new RemoteSchemaError(`property string exceeds max length ${REMOTE_GRAPH_LIMITS.maxPropertyStringLength}`, path);
+        }
+        return value;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new RemoteSchemaError("number must be finite", path);
+        }
+        return value;
+    }
+    if (typeof value === "boolean") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        if (value.length > REMOTE_GRAPH_LIMITS.maxArrayLength) {
+            throw new RemoteSchemaError(`array exceeds max length ${REMOTE_GRAPH_LIMITS.maxArrayLength}`, path);
+        }
+        return value.map((item, i) => {
+            if (item === null || item === undefined)
+                return item;
+            if (typeof item === "string") {
+                if (item.length > REMOTE_GRAPH_LIMITS.maxPropertyStringLength) {
+                    throw new RemoteSchemaError(`array item string exceeds max length`, `${path}[${i}]`);
+                }
+                return item;
+            }
+            if (typeof item === "number") {
+                if (!Number.isFinite(item)) {
+                    throw new RemoteSchemaError("number must be finite", `${path}[${i}]`);
+                }
+                return item;
+            }
+            if (typeof item === "boolean")
+                return item;
+            throw new RemoteSchemaError(`array items must be string, number, or boolean (got ${typeof item})`, `${path}[${i}]`);
+        });
+    }
+    throw new RemoteSchemaError(`properties must be string, number, boolean, null, or array of those (got ${typeof value})`, path);
+}
+function validateProperties(value, path) {
+    if (value === undefined || value === null) {
+        return {};
+    }
+    if (!isPlainObject(value)) {
+        throw new RemoteSchemaError("properties must be a plain object", path);
+    }
+    const keys = Object.keys(value);
+    if (keys.length > REMOTE_GRAPH_LIMITS.maxPropertyKeys) {
+        throw new RemoteSchemaError(`too many property keys (max ${REMOTE_GRAPH_LIMITS.maxPropertyKeys})`, path);
+    }
+    const out = {};
+    for (const key of keys) {
+        if (key.length > REMOTE_GRAPH_LIMITS.maxPropertyKeyLength) {
+            throw new RemoteSchemaError(`property key exceeds max length`, `${path}.${key.slice(0, 32)}...`);
+        }
+        // Reject prototype-pollution attempts
+        if (key === "__proto__" || key === "constructor" || key === "prototype") {
+            throw new RemoteSchemaError(`property key '${key}' is not allowed`, path);
+        }
+        out[key] = validatePropertyValue(value[key], `${path}.${key}`);
+    }
+    return out;
+}
+function validateNode(raw, index) {
+    const path = `nodes[${index}]`;
+    if (!isPlainObject(raw)) {
+        throw new RemoteSchemaError("node must be a plain object", path);
+    }
+    const id = validateString(raw.id, `${path}.id`, REMOTE_GRAPH_LIMITS.maxIdLength);
+    const type = validateString(raw.type, `${path}.type`, REMOTE_GRAPH_LIMITS.maxTypeLength);
+    const properties = validateProperties(raw.properties, `${path}.properties`);
+    const createdAt = validateString(raw.createdAt, `${path}.createdAt`, 64, false);
+    const updatedAt = validateString(raw.updatedAt, `${path}.updatedAt`, 64, false);
+    return {
+        id,
+        type,
+        properties,
+        createdAt: createdAt || new Date().toISOString(),
+        updatedAt: updatedAt || new Date().toISOString(),
+    };
+}
+function validateEdge(raw, index) {
+    const path = `edges[${index}]`;
+    if (!isPlainObject(raw)) {
+        throw new RemoteSchemaError("edge must be a plain object", path);
+    }
+    const id = validateString(raw.id, `${path}.id`, REMOTE_GRAPH_LIMITS.maxIdLength);
+    const type = validateString(raw.type, `${path}.type`, REMOTE_GRAPH_LIMITS.maxTypeLength);
+    const sourceId = validateString(raw.sourceId, `${path}.sourceId`, REMOTE_GRAPH_LIMITS.maxIdLength);
+    const targetId = validateString(raw.targetId, `${path}.targetId`, REMOTE_GRAPH_LIMITS.maxIdLength);
+    const properties = validateProperties(raw.properties, `${path}.properties`);
+    const createdAt = validateString(raw.createdAt, `${path}.createdAt`, 64, false);
+    const updatedAt = validateString(raw.updatedAt, `${path}.updatedAt`, 64, false);
+    return {
+        id,
+        type,
+        sourceId,
+        targetId,
+        properties,
+        createdAt: createdAt || new Date().toISOString(),
+        updatedAt: updatedAt || new Date().toISOString(),
+    };
+}
+/**
+ * Validates a parsed JSON value against the remote graph schema.
+ * Throws RemoteSchemaError on any violation.
+ *
+ * The returned object is a fresh, type-safe LearningGraphData. Edges
+ * that reference node IDs not in the graph are dropped (not an error —
+ * remote graphs may legitimately have hanging references after partial
+ * exports). Use the `droppedEdges` count from the result if you care.
+ */
+export function validateRemoteGraph(raw) {
+    if (!isPlainObject(raw)) {
+        throw new RemoteSchemaError("root must be a plain object", "$");
+    }
+    // Allowed top-level keys only
+    const allowedKeys = new Set(["metadata", "nodes", "edges"]);
+    for (const key of Object.keys(raw)) {
+        if (!allowedKeys.has(key)) {
+            throw new RemoteSchemaError(`unknown top-level key '${key}'`, "$");
+        }
+    }
+    // metadata
+    if (!isPlainObject(raw.metadata)) {
+        throw new RemoteSchemaError("metadata must be a plain object", "metadata");
+    }
+    const metaName = validateString(raw.metadata.name, "metadata.name", REMOTE_GRAPH_LIMITS.maxNameLength);
+    const metaDescription = validateString(raw.metadata.description, "metadata.description", REMOTE_GRAPH_LIMITS.maxDescriptionLength, false);
+    const metaCreatedAt = validateString(raw.metadata.createdAt, "metadata.createdAt", 64, false);
+    const metaUpdatedAt = validateString(raw.metadata.updatedAt, "metadata.updatedAt", 64, false);
+    // nodes
+    if (!Array.isArray(raw.nodes)) {
+        throw new RemoteSchemaError("nodes must be an array", "nodes");
+    }
+    if (raw.nodes.length > REMOTE_GRAPH_LIMITS.maxNodes) {
+        throw new RemoteSchemaError(`node count ${raw.nodes.length} exceeds max ${REMOTE_GRAPH_LIMITS.maxNodes}`, "nodes");
+    }
+    const nodes = [];
+    const nodeIds = new Set();
+    for (let i = 0; i < raw.nodes.length; i++) {
+        const node = validateNode(raw.nodes[i], i);
+        if (nodeIds.has(node.id)) {
+            throw new RemoteSchemaError(`duplicate node id '${node.id}'`, `nodes[${i}]`);
+        }
+        nodeIds.add(node.id);
+        nodes.push(node);
+    }
+    // edges
+    if (!Array.isArray(raw.edges)) {
+        throw new RemoteSchemaError("edges must be an array", "edges");
+    }
+    if (raw.edges.length > REMOTE_GRAPH_LIMITS.maxEdges) {
+        throw new RemoteSchemaError(`edge count ${raw.edges.length} exceeds max ${REMOTE_GRAPH_LIMITS.maxEdges}`, "edges");
+    }
+    const edges = [];
+    let droppedEdges = 0;
+    for (let i = 0; i < raw.edges.length; i++) {
+        const edge = validateEdge(raw.edges[i], i);
+        // Drop edges that reference nodes outside this graph — these are
+        // legitimate orphans, not malicious, but they break traversal
+        if (!nodeIds.has(edge.sourceId) || !nodeIds.has(edge.targetId)) {
+            droppedEdges++;
+            continue;
+        }
+        edges.push(edge);
+    }
+    const now = new Date().toISOString();
+    return {
+        data: {
+            metadata: {
+                name: metaName,
+                description: metaDescription,
+                createdAt: metaCreatedAt || now,
+                updatedAt: metaUpdatedAt || now,
+            },
+            nodes,
+            edges,
+        },
+        droppedEdges,
+    };
+}
+//# sourceMappingURL=remote-schema.js.map

package/dist/core/remote-schema.js.map

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

package/dist/core/role-audit.d.ts

@@ -0,0 +1,20 @@
+import type { Node } from "./types.js";
+export interface RoleAuditCandidate {
+    nodeId: string;
+    type: string;
+    label: string;
+    reason: string;
+    suggestion: string;
+}
+export interface RoleAuditResult {
+    proceduralCandidates: RoleAuditCandidate[];
+    briefingCandidates: RoleAuditCandidate[];
+    summary: {
+        nodesScanned: number;
+        proceduralCount: number;
+        briefingCount: number;
+        cleanCount: number;
+    };
+}
+export declare function auditRoles(nodes: Node[]): RoleAuditResult;
+//# sourceMappingURL=role-audit.d.ts.map

package/dist/core/role-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-audit.d.ts","sourceRoot":"","sources":["../../src/core/role-audit.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvC,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,oBAAoB,EAAE,kBAAkB,EAAE,CAAC;IAC3C,kBAAkB,EAAE,kBAAkB,EAAE,CAAC;IACzC,OAAO,EAAE;QACP,YAAY,EAAE,MAAM,CAAC;QACrB,eAAe,EAAE,MAAM,CAAC;QACxB,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AA6KD,wBAAgB,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,eAAe,CAwCzD"}