openryoko 2026.10.8 → 2026.10.13

package/dist/src/backup/layout.d.ts

@@ -0,0 +1,11 @@
+import type { DatabaseBackupName } from "../sessions/backup.js";
+/**
+ * Re-bases a path that `shared/paths.ts` defines under the running home onto
+ * `home`. The backup code takes the home as an argument so it can be pointed at
+ * any directory, but where things live inside one is defined in exactly one
+ * place and read from there.
+ */
+export declare function inHome(home: string, pathInRunningHome: string): string;
+/** Where a database lives inside a home. */
+export declare function databasePath(home: string, name: DatabaseBackupName): string;
+//# sourceMappingURL=layout.d.ts.map

package/dist/src/backup/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/backup/layout.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAGhE;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,4CAA4C;AAC5C,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAE3E"}

package/dist/src/backup/layout.js

@@ -0,0 +1,16 @@
+import path from "node:path";
+import { JINN_HOME, SESSIONS_DB, WORKFLOWS_DB_PATH } from "../shared/paths.js";
+/**
+ * Re-bases a path that `shared/paths.ts` defines under the running home onto
+ * `home`. The backup code takes the home as an argument so it can be pointed at
+ * any directory, but where things live inside one is defined in exactly one
+ * place and read from there.
+ */
+export function inHome(home, pathInRunningHome) {
+    return path.join(home, path.relative(JINN_HOME, pathInRunningHome));
+}
+/** Where a database lives inside a home. */
+export function databasePath(home, name) {
+    return inHome(home, name === "sessions" ? SESSIONS_DB : WORKFLOWS_DB_PATH);
+}
+//# sourceMappingURL=layout.js.map

package/dist/src/backup/layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../../../src/backup/layout.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE/E;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAC,IAAY,EAAE,iBAAyB;IAC5D,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAAC,CAAC;AACtE,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,IAAwB;IACjE,OAAO,MAAM,CAAC,IAAI,EAAE,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC;AAC7E,CAAC"}

package/dist/src/backup/limits.d.ts

@@ -0,0 +1,54 @@
+/**
+ * What one archive may hold. Applied when an archive is written and again when
+ * one is read, because both happen where running out of memory is an outage:
+ * the daily backup runs inside the gateway, and `verify` and `restore` read
+ * whatever file is sitting in the backup directory.
+ *
+ * A cap on bytes alone is not a cap. Directories, symlinks and empty files
+ * weigh nothing, and every one of them is still an object held in memory while
+ * the home is listed and a line in the manifest. A hundred thousand of them fit
+ * in a megabyte of gzip.
+ */
+export interface ArchiveLimits {
+    /** Files, directories and symlinks together. */
+    maxEntries: number;
+    /** Uncompressed bytes of file content. */
+    maxBytes: number;
+    /** Longest home-relative path carried. Past it an entry is left out and reported. Default: {@link MAX_ENTRY_PATH_BYTES}. */
+    maxPathBytes?: number;
+}
+/**
+ * Far longer than anything a home holds, and short enough that the entry limit
+ * bounds memory: without it, fifty thousand paths of four kilobytes each are
+ * two hundred megabytes of names.
+ */
+export declare const MAX_ENTRY_PATH_BYTES = 1024;
+/** How much of what was skipped or found wrong is kept, by item. The total is always counted. */
+export declare const MAX_RECORDED_ITEMS = 100;
+/**
+ * The largest manifest an archive under these limits may carry. The manifest
+ * names every entry, so this is what bounds the memory a reader needs - and a
+ * writer too: a home of few entries with enormous names is refused here.
+ */
+export declare function manifestByteLimit(limits: ArchiveLimits): number;
+export declare function pathByteLimit(limits: ArchiveLimits): number;
+/**
+ * The most an archive under these limits can unpack to: its content, its
+ * manifest, what tar adds around every entry, and its closing. A reader stops
+ * when the stream goes past this.
+ *
+ * The other limits are judged from what the headers announce, so they say
+ * nothing about bytes that are announced by no entry at all - pax records with
+ * nothing behind them, or whatever else a file is padded out with. Without
+ * this, such a file is read to its end however long that is.
+ */
+export declare function unpackedByteLimit(limits: ArchiveLimits): number;
+/**
+ * The home, or an archive, holds more than one archive is allowed to. Trying
+ * again changes nothing until the operator raises a limit or moves the bulk
+ * out, so the scheduler leaves this for the next daily run.
+ */
+export declare class ArchiveTooLargeError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=limits.d.ts.map

package/dist/src/backup/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../../src/backup/limits.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,4HAA4H;IAC5H,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAKzC,iGAAiG;AACjG,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAE/D;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAE3D;AAYD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAK/D;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B"}

package/dist/src/backup/limits.js

@@ -0,0 +1,59 @@
+import { MAX_TRAILING_PADDING_BYTES, TAR_BLOCK_BYTES } from "./tar.js";
+/**
+ * Far longer than anything a home holds, and short enough that the entry limit
+ * bounds memory: without it, fifty thousand paths of four kilobytes each are
+ * two hundred megabytes of names.
+ */
+export const MAX_ENTRY_PATH_BYTES = 1024;
+/** What one entry may cost in the manifest on average, name included. */
+const MANIFEST_BYTES_PER_ENTRY = 640;
+/** How much of what was skipped or found wrong is kept, by item. The total is always counted. */
+export const MAX_RECORDED_ITEMS = 100;
+/**
+ * The largest manifest an archive under these limits may carry. The manifest
+ * names every entry, so this is what bounds the memory a reader needs - and a
+ * writer too: a home of few entries with enormous names is refused here.
+ */
+export function manifestByteLimit(limits) {
+    return limits.maxEntries * MANIFEST_BYTES_PER_ENTRY;
+}
+export function pathByteLimit(limits) {
+    return limits.maxPathBytes ?? MAX_ENTRY_PATH_BYTES;
+}
+/**
+ * What one entry can add to an archive besides its content: its header, the
+ * padding after its data, and - for a path or a link target too long for the
+ * header - a pax header with both spelled out.
+ */
+function tarOverheadPerEntry(limits) {
+    const paxRecords = Math.ceil((2 * (pathByteLimit(limits) + 32)) / TAR_BLOCK_BYTES) * TAR_BLOCK_BYTES;
+    return 3 * TAR_BLOCK_BYTES + paxRecords;
+}
+/**
+ * The most an archive under these limits can unpack to: its content, its
+ * manifest, what tar adds around every entry, and its closing. A reader stops
+ * when the stream goes past this.
+ *
+ * The other limits are judged from what the headers announce, so they say
+ * nothing about bytes that are announced by no entry at all - pax records with
+ * nothing behind them, or whatever else a file is padded out with. Without
+ * this, such a file is read to its end however long that is.
+ */
+export function unpackedByteLimit(limits) {
+    return limits.maxBytes
+        + manifestByteLimit(limits)
+        + (limits.maxEntries + 1) * tarOverheadPerEntry(limits)
+        + 2 * TAR_BLOCK_BYTES + MAX_TRAILING_PADDING_BYTES;
+}
+/**
+ * The home, or an archive, holds more than one archive is allowed to. Trying
+ * again changes nothing until the operator raises a limit or moves the bulk
+ * out, so the scheduler leaves this for the next daily run.
+ */
+export class ArchiveTooLargeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ArchiveTooLargeError";
+    }
+}
+//# sourceMappingURL=limits.js.map

package/dist/src/backup/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../../src/backup/limits.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAsBvE;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAEzC,yEAAyE;AACzE,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAErC,iGAAiG;AACjG,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAEtC;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAqB;IACrD,OAAO,MAAM,CAAC,UAAU,GAAG,wBAAwB,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAqB;IACjD,OAAO,MAAM,CAAC,YAAY,IAAI,oBAAoB,CAAC;AACrD,CAAC;AAED;;;;GAIG;AACH,SAAS,mBAAmB,CAAC,MAAqB;IAChD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,eAAe,CAAC,GAAG,eAAe,CAAC;IACrG,OAAO,CAAC,GAAG,eAAe,GAAG,UAAU,CAAC;AAC1C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAqB;IACrD,OAAO,MAAM,CAAC,QAAQ;UAClB,iBAAiB,CAAC,MAAM,CAAC;UACzB,CAAC,MAAM,CAAC,UAAU,GAAG,CAAC,CAAC,GAAG,mBAAmB,CAAC,MAAM,CAAC;UACrD,CAAC,GAAG,eAAe,GAAG,0BAA0B,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF"}

package/dist/src/backup/manifest.d.ts

@@ -0,0 +1,45 @@
+export declare const MANIFEST_SCHEMA_VERSION = 1;
+export declare const MANIFEST_FORMAT = "openryoko-home-archive";
+export interface ManifestEntry {
+    /** Home-relative, slash-separated. */
+    path: string;
+    type: "file" | "directory" | "symlink";
+    mode: number;
+    /** Files only. */
+    size?: number;
+    /** Files only. */
+    sha256?: string;
+    /** Symlinks only: the link text, exactly as it was read. */
+    target?: string;
+}
+export interface SkippedEntry {
+    path: string;
+    reason: string;
+}
+/**
+ * Travels inside the archive as its last entry: the hashes are only known once
+ * every file has been streamed past, and one pass is what keeps a file that
+ * changes during the backup from disagreeing with its own record.
+ */
+export interface BackupManifest {
+    schemaVersion: typeof MANIFEST_SCHEMA_VERSION;
+    format: typeof MANIFEST_FORMAT;
+    id: string;
+    createdAt: string;
+    /** The home this was taken from. Informational: restore never trusts it as a destination. */
+    home: string;
+    /** Uncompressed bytes of every archived file. */
+    contentBytes: number;
+    entries: ManifestEntry[];
+    /** What the walk met and deliberately left out (unreadable, not a regular file). */
+    skipped: SkippedEntry[];
+}
+/**
+ * The entry for `entryPath`, by binary search. A manifest lists its entries in
+ * path order, so nothing has to be indexed to look one up.
+ */
+export declare function findManifestEntry(entries: readonly ManifestEntry[], entryPath: string): ManifestEntry | undefined;
+export declare function serializeManifest(manifest: BackupManifest): Buffer;
+/** Reads a manifest, refusing one this version does not understand or that is not shaped like one. */
+export declare function parseManifest(bytes: Buffer): BackupManifest;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/src/backup/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/backup/manifest.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,IAAI,CAAC;AACzC,eAAO,MAAM,eAAe,2BAA2B,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,OAAO,uBAAuB,CAAC;IAC9C,MAAM,EAAE,OAAO,eAAe,CAAC;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,oFAAoF;IACpF,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAWjH;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAElE;AAyBD,sGAAsG;AACtG,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CA2B3D"}

package/dist/src/backup/manifest.js

@@ -0,0 +1,77 @@
+export const MANIFEST_SCHEMA_VERSION = 1;
+export const MANIFEST_FORMAT = "openryoko-home-archive";
+/**
+ * The entry for `entryPath`, by binary search. A manifest lists its entries in
+ * path order, so nothing has to be indexed to look one up.
+ */
+export function findManifestEntry(entries, entryPath) {
+    let low = 0;
+    let high = entries.length - 1;
+    while (low <= high) {
+        const middle = (low + high) >> 1;
+        const candidate = entries[middle].path;
+        if (candidate === entryPath)
+            return entries[middle];
+        if (candidate < entryPath)
+            low = middle + 1;
+        else
+            high = middle - 1;
+    }
+    return undefined;
+}
+export function serializeManifest(manifest) {
+    return Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseEntry(value, index) {
+    if (!isRecord(value) || typeof value.path !== "string" || typeof value.mode !== "number") {
+        throw new Error(`manifest entry ${index} is malformed`);
+    }
+    // Keys in the order the writer emits them, so a manifest that is read and
+    // written again comes out byte for byte the same and can be compared as bytes.
+    const { path: entryPath, mode } = value;
+    if (value.type === "directory")
+        return { path: entryPath, type: "directory", mode };
+    if (value.type === "symlink" && typeof value.target === "string")
+        return { path: entryPath, type: "symlink", mode, target: value.target };
+    if (value.type === "file"
+        && typeof value.size === "number" && Number.isSafeInteger(value.size) && value.size >= 0
+        && typeof value.sha256 === "string" && /^[0-9a-f]{64}$/.test(value.sha256)) {
+        return { path: entryPath, type: "file", mode, size: value.size, sha256: value.sha256 };
+    }
+    throw new Error(`manifest entry ${index} (${value.path}) is malformed`);
+}
+/** Reads a manifest, refusing one this version does not understand or that is not shaped like one. */
+export function parseManifest(bytes) {
+    let parsed;
+    try {
+        parsed = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        throw new Error("manifest is not valid JSON");
+    }
+    if (!isRecord(parsed) || parsed.format !== MANIFEST_FORMAT)
+        throw new Error("manifest is not a home archive manifest");
+    if (parsed.schemaVersion !== MANIFEST_SCHEMA_VERSION) {
+        throw new Error(`unsupported manifest version ${String(parsed.schemaVersion)}`);
+    }
+    if (typeof parsed.id !== "string" || typeof parsed.createdAt !== "string" || !Array.isArray(parsed.entries)) {
+        throw new Error("manifest is missing required fields");
+    }
+    const skipped = Array.isArray(parsed.skipped)
+        ? parsed.skipped.filter(isRecord).map((item) => ({ path: String(item.path), reason: String(item.reason) }))
+        : [];
+    return {
+        schemaVersion: MANIFEST_SCHEMA_VERSION,
+        format: MANIFEST_FORMAT,
+        id: parsed.id,
+        createdAt: parsed.createdAt,
+        home: typeof parsed.home === "string" ? parsed.home : "",
+        contentBytes: typeof parsed.contentBytes === "number" ? parsed.contentBytes : 0,
+        entries: parsed.entries.map(parseEntry),
+        skipped,
+    };
+}
+//# sourceMappingURL=manifest.js.map

package/dist/src/backup/manifest.js.map

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

package/dist/src/backup/restore.d.ts

@@ -0,0 +1,73 @@
+import { type ArchiveInspection, type InspectOptions } from "./archive.js";
+import type { ArchiveLimits } from "./limits.js";
+import { type ManifestEntry } from "./manifest.js";
+import { type DiskSpaceProbe } from "./space.js";
+import { type BackupKind } from "./targets.js";
+export interface RestoreOptions {
+    archive: string;
+    home: string;
+    /** Limits the restore to these kinds. Default: everything the archive holds. */
+    only?: readonly BackupKind[];
+    /** Work out what would change and stop there. */
+    dryRun?: boolean;
+    /** Recreate symlinks whose target lies outside the home. Refused unless set. */
+    allowExternalSymlinks?: boolean;
+    /** Where the snapshot of the current state goes before anything is written. */
+    backupDirectory: string;
+    now: Date;
+    /**
+     * What an archive may hold - the one being restored, and the snapshot taken
+     * first of what it will overwrite. Default: what an instance uses when its config says nothing.
+     */
+    limits?: ArchiveLimits;
+    /** The existing free-space judgement, replaceable in tests. */
+    diskSpace?: DiskSpaceProbe;
+    /** Overrides the verification pass. The seam that lets a test stand in for an inspector that misses something. */
+    inspect?: (file: string, context: InspectOptions) => Promise<ArchiveInspection>;
+}
+/** "mode": the bytes already match and only the permissions are put back. */
+export type RestoreAction = "create" | "replace" | "mode" | "unchanged";
+export interface RestoreChange {
+    path: string;
+    type: ManifestEntry["type"];
+    /** Null for a directory that only exists to hold a restored path, like `cron`. */
+    kind: BackupKind | null;
+    action: Exclude<RestoreAction, "unchanged">;
+}
+export interface RestoreResult {
+    id: string;
+    archive: string;
+    home: string;
+    dryRun: boolean;
+    /** The kinds actually restored: the ones asked for that the archive holds. */
+    kinds: BackupKind[];
+    changes: RestoreChange[];
+    unchanged: number;
+    /** In the home under the restored kinds, absent from the archive. Left exactly as they are. */
+    untouched: string[];
+    /** In the archive but under no archive target. Never written. */
+    ignored: string[];
+    /** The snapshot taken before writing. Null on a dry run or when nothing needed saving. */
+    preRestore: {
+        id: string;
+        file: string;
+    } | null;
+    /** What the restore did and the operator should still know: at present, a working directory it could not clear away. */
+    warnings: string[];
+}
+/**
+ * Restores files from a home archive into `home`.
+ *
+ * Nothing is written until the archive has been read end to end and checked
+ * against its manifest, the plan has been worked out, and what the plan will
+ * overwrite has been archived as it stands, as a pre-restore snapshot. Files
+ * are then extracted into a staging directory, verified again, and moved into
+ * place.
+ *
+ * A restore brings back what the archive has. It deletes nothing: a file added
+ * to the home since the backup stays where it is and is reported as untouched.
+ * It writes only under the paths a home archive is made of, never through a
+ * symlink, and never recreates a symlink leading out of the home unless asked.
+ */
+export declare function restoreHomeArchive(options: RestoreOptions): Promise<RestoreResult>;
+//# sourceMappingURL=restore.d.ts.map

package/dist/src/backup/restore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restore.d.ts","sourceRoot":"","sources":["../../../src/backup/restore.ts"],"names":[],"mappings":"AAIA,OAAO,EAML,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,cAAc,CAAC;AAItB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAA0C,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAE3F,OAAO,EAAqC,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AACpF,OAAO,EAAoE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAOjH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,IAAI,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAC7B,iDAAiD;IACjD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gFAAgF;IAChF,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,+EAA+E;IAC/E,eAAe,EAAE,MAAM,CAAC;IACxB,GAAG,EAAE,IAAI,CAAC;IACV;;;OAGG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,kHAAkH;IAClH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACjF;AAED,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,CAAC;AAKxE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5B,kFAAkF;IAClF,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,OAAO,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,8EAA8E;IAC9E,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,+FAA+F;IAC/F,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,iEAAiE;IACjE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0FAA0F;IAC1F,UAAU,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAChD,wHAAwH;IACxH,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAgoBD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAsCxF"}