@sema-ai/core 1.275.1

package/dist/stores/file/file-snapshot-store.js

@@ -0,0 +1,374 @@
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { applyManifest, captureManifest, DEFAULT_SNAPSHOT_BOUNDS, } from "../../core/file-snapshot-store.js";
+import { ensureDir, sanitizePathComponent, sanitizeScope, writeThenLink } from "./fs-atomic.js";
+/**
+ * design/101 §E19 — file-backed {@link FileSnapshotStore} for the local (TOC) backend: content-addressed blobs
+ * on disk + ONE manifest file per `(scope, key)`. Semantics **byte-for-byte identical to
+ * `InMemoryFileSnapshotStore`** (the cross-backend equivalence contract) — it REUSES core's `captureManifest`/
+ * `applyManifest`, so the security-critical convergence (symlink-ancestor neutralization, remove-before-write,
+ * fail-closed) can NEVER drift from the InMemory reference.
+ *
+ * On-disk layout under `<root>/file-snapshots/`:
+ *  - `blobs/<sha256>` — write-ONCE content-addressed blob (an EEXIST is a dedup no-op; shared across all keys).
+ *  - `manifests/<sanitizeScope(scope)>/<key>.json` — a JSON array of `[relPath, sha256]` pairs.
+ *
+ * Atomicity: single-process (the `FileStorageBackend` boot lock); an `inFlight` set guards create-once against
+ * two concurrent `snapshot()`s for the same key. A blob is published atomically (write-then-link); a manifest is
+ * written ONLY after the full capture succeeds (fail-closed — never a partial manifest). Cross-replica durable
+ * snapshots are the Pg/TiDB/object-store backend's job.
+ */
+export class FileFileSnapshotStore {
+    base;
+    blobsDir;
+    manifestsDir;
+    // manifest path → the blob hashes that snapshot has written so far (create-once atomicity AND reap-safety: an
+    // in-flight snapshot's blobs are not yet in any manifest, so `reap` must treat them as LIVE — codex review).
+    inFlight = new Map();
+    bounds;
+    constructor(root, bounds) {
+        this.base = join(root, "file-snapshots");
+        this.blobsDir = join(this.base, "blobs");
+        this.manifestsDir = join(this.base, "manifests");
+        ensureDir(this.blobsDir);
+        ensureDir(this.manifestsDir);
+        this.bounds = {
+            maxFiles: bounds?.maxFiles ?? DEFAULT_SNAPSHOT_BOUNDS.maxFiles,
+            maxBytes: bounds?.maxBytes ?? DEFAULT_SNAPSHOT_BOUNDS.maxBytes,
+            ignoreDirs: new Set(bounds?.ignoreDirs ?? DEFAULT_SNAPSHOT_BOUNDS.ignoreDirs),
+        };
+    }
+    scopeDir(scope) {
+        return join(this.manifestsDir, sanitizeScope(scope));
+    }
+    manifestPath(scope, key) {
+        // key = SessionTreeEntry.id (uuidv7) — already filename-safe; the strict guard is defense-in-depth.
+        return join(this.scopeDir(scope), `${sanitizePathComponent(key)}.json`);
+    }
+    /** manifestPath, but a key that fails the strict path-component guard → null (so the seam's NEVER-throw
+     *  contract holds for a direct SDK caller; engine keys are uuidv7 so this never fires in practice). */
+    tryManifestPath(scope, key) {
+        try {
+            return this.manifestPath(scope, key);
+        }
+        catch {
+            return null; // unsafe key → degrade to a typed result in the caller, never throw out of the seam
+        }
+    }
+    blobPath(hash) {
+        return join(this.blobsDir, sanitizePathComponent(hash));
+    }
+    readManifest(path) {
+        let raw;
+        try {
+            raw = readFileSync(path, "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+        try {
+            // A torn/zero-byte/wrong-shape manifest must NOT throw out of the seam (bug-hunt MAJOR-2): treat it as
+            // absent (→ not_found on restore / re-snapshot allowed) rather than a SyntaxError/TypeError escaping
+            // has/restore/snapshot. Same tolerance as `readJsonlRecords`' torn-tail recovery + reap's guarded read.
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) ? new Map(parsed) : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async snapshot(scope, key, env, root, signal) {
+        const mpath = this.tryManifestPath(scope, key);
+        if (!mpath)
+            return { ok: false, error: { code: "restore_failed", message: `unsafe snapshot key ${JSON.stringify(key)}` } };
+        // create-once + atomic: an in-flight OR a VALID existing snapshot for this immutable entry is a no-op.
+        if (this.inFlight.has(mpath))
+            return { ok: true };
+        if (this.readManifest(mpath) !== null)
+            return { ok: true };
+        // readManifest collapses ABSENT and CORRUPT to null. If the manifest FILE exists but didn't parse it's
+        // corrupt (torn write / fs corruption) — remove it so the re-capture below actually repairs it. Otherwise
+        // writeThenLink(mpath) would EEXIST over the corrupt file → a false-ok no-op leaving restore broken
+        // (not_found) forever. The entry is immutable, so re-capturing reproduces the same content.
+        if (existsSync(mpath)) {
+            try {
+                rmSync(mpath, { force: true });
+            }
+            catch {
+                /* best-effort; a concurrent writer or ENOENT is fine — writeThenLink's EEXIST handling still holds */
+            }
+        }
+        const written = new Set(); // hashes this capture has published (reap treats them as live)
+        this.inFlight.set(mpath, written);
+        try {
+            const captured = await captureManifest(env, root, this.bounds, signal, (hash, bytes) => {
+                written.add(hash); // record BEFORE the write so a racing reap never GCs a blob we are about to/just did link
+                try {
+                    writeThenLink(this.blobPath(hash), bytes); // write-ONCE content-addressed
+                }
+                catch (err) {
+                    if (err.code !== "EEXIST")
+                        throw err; // EEXIST = blob already stored (dedup)
+                }
+            });
+            if (!captured.ok)
+                return captured;
+            // Persist the manifest ONLY after the full capture succeeded (fail-closed — never a partial manifest).
+            ensureDir(this.scopeDir(scope));
+            writeThenLink(mpath, JSON.stringify([...captured.value]));
+            return { ok: true };
+        }
+        catch (err) {
+            // writeThenLink(mpath) EEXIST = a concurrent writer won (still create-once correct); else a real fs error.
+            if (err.code === "EEXIST")
+                return { ok: true };
+            return { ok: false, error: { code: "restore_failed", message: `snapshot persist failed: ${err.message}` } };
+        }
+        finally {
+            this.inFlight.delete(mpath);
+        }
+    }
+    async restore(scope, key, env, root, signal) {
+        const mpath = this.tryManifestPath(scope, key);
+        const manifest = mpath ? this.readManifest(mpath) : null;
+        if (!manifest)
+            return { ok: false, error: { code: "not_found", message: `no snapshot for key ${key}` } };
+        return applyManifest(env, root, this.bounds, signal, manifest, (hash) => {
+            try {
+                return readFileSync(this.blobPath(hash));
+            }
+            catch (err) {
+                // ENOENT (missing blob) OR a tampered/non-hex hash that fails the path guard → undefined → applyManifest
+                // degrades to restore_failed (never throw out of the seam).
+                return undefined;
+            }
+        });
+    }
+    async listKeys(scope) {
+        // [266]: the enumeration half of reap — every committed `.json` manifest's key under this scope (same
+        // readdir + `.json`-strip as reap; NEVER-throws: a missing scope dir → []). Mirrors InMemory exactly.
+        const dir = this.scopeDir(scope);
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return []; // no snapshots for this scope yet
+            return []; // any other fs error (EACCES/ENOTDIR/…) → degrade to "no keys" (never-throw seam; InMemory can't throw)
+        }
+        return entries
+            .filter((f) => f.endsWith(".json"))
+            .filter((f) => this.readManifest(join(dir, f)) !== null) // skip corrupt manifests so listKeys agrees with has()/restore()
+            .map((f) => f.slice(0, -".json".length));
+    }
+    async has(scope, key) {
+        const mpath = this.tryManifestPath(scope, key);
+        return mpath !== null && this.readManifest(mpath) !== null;
+    }
+    async exportManifest(scope, key) {
+        const mpath = this.tryManifestPath(scope, key);
+        return mpath ? this.readManifest(mpath) : null; // readManifest is never-throw (torn/missing → null)
+    }
+    async getBlob(hash) {
+        try {
+            return readFileSync(this.blobPath(hash)); // a Buffer IS a Uint8Array
+        }
+        catch {
+            return undefined; // ENOENT / unsafe-hash path guard → absent (never throw out of the seam)
+        }
+    }
+    async putBlob(hash, bytes) {
+        // content-address integrity (mirrors InMemory + importManifest): bytes under a non-matching hash would poison
+        // the store. Verify FIRST — a passing sha256 also guarantees `hash` is 64-hex (filename-safe). Mismatch →
+        // read_failed, nothing written.
+        if (createHash("sha256").update(bytes).digest("hex") !== hash) {
+            return { ok: false, error: { code: "read_failed", message: `blob bytes fail content-address integrity for ${hash}` } };
+        }
+        try {
+            writeThenLink(this.blobPath(hash), bytes); // write-ONCE content-addressed (immutable)
+        }
+        catch (err) {
+            if (err.code === "EEXIST")
+                return { ok: true }; // already stored (dedup no-op; bytes identical)
+            return { ok: false, error: { code: "restore_failed", message: `putBlob persist failed: ${err.message}` } };
+        }
+        return { ok: true };
+    }
+    async importManifest(scope, key, manifest, srcGetBlob) {
+        const mpath = this.tryManifestPath(scope, key);
+        if (!mpath)
+            return { ok: false, error: { code: "restore_failed", message: `unsafe snapshot key ${JSON.stringify(key)}` } };
+        // create-once + atomic: an in-flight OR a VALID existing snapshot for this immutable entry is a no-op.
+        if (this.inFlight.has(mpath))
+            return { ok: true };
+        if (this.readManifest(mpath) !== null)
+            return { ok: true };
+        // A manifest FILE that exists but is corrupt (readManifest → null) must be removed so the link below repairs
+        // it — else writeThenLink(mpath) would EEXIST over the corrupt file → false-ok (mirrors snapshot()).
+        if (existsSync(mpath)) {
+            try {
+                rmSync(mpath, { force: true });
+            }
+            catch {
+                /* best-effort; a concurrent writer or ENOENT is fine — writeThenLink's EEXIST handling still holds */
+            }
+        }
+        const written = new Set(); // hashes this import has published (reap treats them as live)
+        this.inFlight.set(mpath, written);
+        try {
+            for (const hash of new Set(manifest.values())) {
+                written.add(hash); // record BEFORE the write so a racing reap never GCs a blob we are about to link
+                let bpath;
+                try {
+                    bpath = this.blobPath(hash); // an untrusted manifest could carry a non-hex/path-escaping hash → guard
+                }
+                catch {
+                    return { ok: false, error: { code: "read_failed", message: `unsafe blob hash ${JSON.stringify(hash)}` } };
+                }
+                if (existsSync(bpath))
+                    continue; // already stored (content-addressed dedup; verified when first stored)
+                // `srcGetBlob` is a caller-supplied cross-backend fetch (durable/remote) that CAN reject — catch it HERE
+                // and encode as `read_failed` (the fetch-side code, matching InMemory + missing/mismatch), so a transit
+                // error never falls through to the outer catch (reserved for the manifest-PERSIST fs error = restore_failed).
+                let bytes;
+                try {
+                    bytes = await srcGetBlob(hash);
+                }
+                catch (err) {
+                    return { ok: false, error: { code: "read_failed", message: `source blob ${hash} fetch failed: ${err.message}` } };
+                }
+                if (!bytes)
+                    return { ok: false, error: { code: "read_failed", message: `missing source blob ${hash}` } };
+                if (createHash("sha256").update(bytes).digest("hex") !== hash) {
+                    return { ok: false, error: { code: "read_failed", message: `source blob ${hash} fails content-address integrity` } };
+                }
+                try {
+                    writeThenLink(bpath, bytes); // write-ONCE content-addressed
+                }
+                catch (err) {
+                    if (err.code !== "EEXIST")
+                        throw err; // EEXIST = blob already stored (dedup race)
+                }
+            }
+            // Persist the manifest ONLY after every blob is stored+verified (fail-closed — never a partial manifest).
+            ensureDir(this.scopeDir(scope));
+            writeThenLink(mpath, JSON.stringify([...manifest]));
+            return { ok: true };
+        }
+        catch (err) {
+            // writeThenLink(mpath) EEXIST = a concurrent writer won (still create-once correct); else a real fs error.
+            if (err.code === "EEXIST")
+                return { ok: true };
+            return { ok: false, error: { code: "restore_failed", message: `import persist failed: ${err.message}` } };
+        }
+        finally {
+            this.inFlight.delete(mpath);
+        }
+    }
+    async reap(scope, keepKeys) {
+        const keep = new Set(keepKeys);
+        const dir = this.scopeDir(scope);
+        let removed = 0;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                entries = []; // no snapshots for this scope yet
+            else
+                entries = []; // any other fs error → skip the manifest-deletion pass (never-throw seam); the blob-GC
+            // half below is independently fail-safe (its own complete=false path keeps blobs on an unreadable scope).
+        }
+        for (const file of entries) {
+            if (!file.endsWith(".json"))
+                continue;
+            const key = file.slice(0, -".json".length);
+            if (!keep.has(key)) {
+                if (safeRm(join(dir, file)))
+                    removed++; // a delete we couldn't make (EACCES/EBUSY) leaves the manifest, not counted
+            }
+        }
+        // Blob GC: delete blobs unreferenced by ANY surviving manifest. FAIL-SAFE (codex BLOCKER): build the COMPLETE
+        // live set or ABORT the GC — an incomplete set (a swallowed scan error) would delete still-live blobs. This
+        // whole method body is SYNCHRONOUS (no await), so it runs atomically vs any in-flight snapshot parked at an
+        // await; we still union `inFlight` hashes so a snapshot that has linked a blob but not yet its manifest keeps
+        // it. On ANY unexpected enumeration error → keep all blobs (a leaked blob is harmless; a deleted live one is data loss).
+        const live = new Set();
+        for (const hs of this.inFlight.values())
+            for (const h of hs)
+                live.add(h);
+        let complete = true;
+        let scopeDirs;
+        try {
+            scopeDirs = readdirSync(this.manifestsDir);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                scopeDirs = [];
+            else
+                return removed; // can't list scopes → abort blob GC (keep all blobs)
+        }
+        for (const scopeName of scopeDirs) {
+            const sdir = join(this.manifestsDir, scopeName);
+            let files;
+            try {
+                files = readdirSync(sdir);
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    continue; // a concurrent reap removed it → its blobs are gone-with-it
+                complete = false; // an unexpected error → we may be missing live hashes → do NOT delete blobs
+                break;
+            }
+            for (const file of files) {
+                if (!file.endsWith(".json"))
+                    continue;
+                // `readManifest` returns null for an UNREADABLE/CORRUPT manifest (bug-hunt MAJOR-2 made it lenient for the
+                // never-throw seam). The file came from `readdir` so it EXISTS — a null here means corrupt (or a benign
+                // race-delete). Either way its live hashes are UNKNOWN → ABORT the GC (fail-safe: keep all blobs). NOT
+                // doing this would silently delete still-live blobs that a corrupt sibling manifest references.
+                const m = this.readManifest(join(sdir, file));
+                if (!m) {
+                    complete = false;
+                    break;
+                }
+                for (const h of m.values())
+                    live.add(h);
+            }
+            if (!complete)
+                break;
+        }
+        if (!complete)
+            return removed; // incomplete live set → keep every blob (never delete a possibly-live one)
+        let blobs;
+        try {
+            blobs = readdirSync(this.blobsDir);
+        }
+        catch {
+            return removed; // can't list blobs → nothing to GC
+        }
+        for (const blob of blobs) {
+            if (!live.has(blob))
+                safeRm(join(this.blobsDir, blob)); // a blob we can't delete is leaked GC residue, harmless
+        }
+        return removed;
+    }
+}
+/** rmSync that NEVER throws out of the seam (bug-hunt MINOR-4): `force:true` already swallows ENOENT; this also
+ *  tolerates EACCES/EPERM/EBUSY (reap is fail-safe — a file we can't delete is leaked, never a thrown error or
+ *  data loss). Returns whether the path is gone (or already absent). */
+function safeRm(path) {
+    try {
+        rmSync(path, { force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=file-snapshot-store.js.map

package/dist/stores/file/file-snapshot-store.js.map

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

package/dist/stores/file/fs-atomic.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Validate an engine-minted id (sessionId / tool-result ref) before using it as a path component. These are
+ * `uuidv7` / `tr_<sessionId>_<toolCallId>` — already filename-safe — but a strict guard is cheap
+ * defense-in-depth: reject `.`/`..`/empty/separators so nothing can traverse out of the store dir.
+ */
+export declare function sanitizePathComponent(raw: string): string;
+/**
+ * Map a model-influenced memory `scope` to a safe directory name (CC `sanitizePath` parity). Replace every
+ * non-alphanumeric run with `-`; if the result is over 200 chars, append a short content hash so two long
+ * scopes can't collide. The ORIGINAL scope is the partition key the engine passes — this only affects the
+ * on-disk dir name, never the stored data. Never `path.join` a raw scope.
+ */
+export declare function sanitizeScope(scope: string): string;
+/**
+ * Resolve the data root (CC `getClaudeConfigHomeDir` analog): `$AGENT_DATA_DIR ?? ~/.ai-agent`,
+ * NFC-normalized, and `realpath`-canonicalized once the dir exists. Creates the dir (0o700) if absent.
+ */
+export declare function resolveDataRoot(explicit?: string): string;
+/** Ensure a directory exists with 0o700 perms (idempotent). */
+/**
+ * Atomically CREATE `target` carrying `content` — it appears in ONE step already fully written, no empty/partial
+ * window. Fixes the create-then-write race (codex review BUG-1/BUG-3): a reader/pruner can see a half-written
+ * file, and a crash mid-write leaves a zero-byte target a retry would silently keep. Writes a temp in `target`'s
+ * OWN dir (same FS → `link` is atomic) + fsync, then `linkSync`-publishes it; throws `EEXIST` if `target` exists.
+ */
+export declare function writeThenLink(target: string, content: string | Uint8Array): void;
+export declare function ensureDir(dir: string): void;
+/**
+ * The 5-step atomic whole-file replace (§2.1). Skipping any of steps 3/5/6 is the classic corruption bug:
+ *  1. open a temp under `root/tmp/` (same FS → rename is atomic),
+ *  2. write the bytes,
+ *  3. fsync the DATA (else ext4 "zero-length file after crash"),
+ *  4. close → rename(tmp, target) (atomic intra-FS namespace swap),
+ *  5. fsync the containing DIRECTORY (persists the rename itself).
+ * On any failure the temp is unlinked so a crashed write leaves no scratch behind.
+ */
+export declare function atomicWriteFile(tmpDir: string, target: string, bytes: string): void;
+/**
+ * Read a JSONL file and return every COMPLETE, parseable record — the universal torn-tail recovery (§2.2):
+ *  - a trailing line with no terminating `\n` (a crash mid-write) is discarded,
+ *  - any line (interior or tail) that fails `JSON.parse` is skipped (never throws — `listRemoteAgentMetadata`
+ *    parity), so a single corrupt interior line never poisons the whole replay.
+ * A missing file → `[]`. This is why JSONL beats one big JSON blob: a torn tail can never corrupt the store.
+ */
+export declare function readJsonlRecords<T>(path: string): T[];
+/**
+ * An append-only JSONL log opened once with `O_APPEND` and held for the file's lifetime. One record =
+ * one `JSON.stringify(...) + "\n"` written in a SINGLE `writeSync` call (never split across writes → the
+ * only torn line possible is a crash tail, which {@link readJsonlRecords} drops). `fsync` is opt-in per
+ * append (the checkpoint commit point ALWAYS fsyncs; session/memory cadence is the caller's `fsyncEvery`).
+ */
+export declare class AppendLog {
+    private fd;
+    constructor(path: string);
+    /** Append one record (single write of `json + "\n"`). `fsync:true` makes the record durable before return. */
+    append(record: unknown, fsync: boolean): void;
+    close(): void;
+}
+/**
+ * The SINGLE coarse boot guard (§2.4): an `O_EXCL` PID file at `root/LOCK` that forbids two processes
+ * sharing a data dir. A second instance fails fast ("another instance owns this data dir"). A STALE lock
+ * (the writing PID is dead) is pruned and re-acquired — `proper-lockfile`/CC `concurrentSessions` parity.
+ *
+ * This is the ONLY legitimate file lock in the backend: the once-only CAS is in-process (one event loop +
+ * a per-token async mutex), so there is NO per-operation flock — this fence just guarantees the
+ * in-process model's premise (a single writer to the dir) holds. Cross-process CORRECT concurrency is the
+ * Pg/TiDB backend's job, by design.
+ */
+export declare class BootLock {
+    private readonly lockPath;
+    private held;
+    constructor(lockPath: string);
+    /** Acquire the lock or throw. Prunes a stale lock whose recorded PID is not running. */
+    acquire(): void;
+    private writeLock;
+    private readLockPid;
+    /** Release the lock (only if we hold it). Best-effort; never throws. */
+    release(): void;
+}
+/**
+ * design/84 Seam B (TOC profile) — a per-scope CONSOLIDATION lock factory for the file backend's
+ * {@link import("../../core/consolidate-scope.js").ConsolidateScopeDeps.acquire} injection point. A single
+ * machine may run a periodic-consolidation timer AND a task-end inline pass concurrently; this advisory lock
+ * stops two processes consolidating the SAME scope at once (the in-process model the file backend assumes —
+ * see {@link BootLock} — does not cover a second OS process with its own timer).
+ *
+ * `acquire(scope)` writes `lockDir/<sanitizedScope>.consolidate.lock` carrying THIS pid (atomic
+ * {@link writeThenLink}, so the lock appears with its pid already in it — no empty-window prune race). It
+ * returns a `release` callback on success, or `undefined` when a LIVE owner already holds it (the caller
+ * treats `undefined` as "busy → skip this pass", a no-op). A STALE lock (recorded pid is dead) is pruned and
+ * re-acquired once. The implementation lives HERE (the deployment shell's persist/exec axis), NOT core — core
+ * only DEFINES the injection point (the constitutional split: gate-presence in core, mechanism in the profile).
+ */
+export declare function createFileConsolidationLock(lockDir: string): (scope: string) => (() => void) | undefined;
+//# sourceMappingURL=fs-atomic.d.ts.map

package/dist/stores/file/fs-atomic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-atomic.d.ts","sourceRoot":"","sources":["../../../src/stores/file/fs-atomic.ts"],"names":[],"mappings":"AAyCA;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKzD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASnD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAKzD;AAED,+DAA+D;AAC/D;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CA4BhF;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CA2BnF;AAiCD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,CA2BrD;AAED;;;;;GAKG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,EAAE,CAAS;gBACP,IAAI,EAAE,MAAM;IAKxB,8GAA8G;IAC9G,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAM7C,KAAK,IAAI,IAAI;CAOd;AAED;;;;;;;;;GASG;AACH,qBAAa,QAAQ;IAEP,OAAO,CAAC,QAAQ,CAAC,QAAQ;IADrC,OAAO,CAAC,IAAI,CAAS;gBACQ,QAAQ,EAAE,MAAM;IAE7C,wFAAwF;IACxF,OAAO,IAAI,IAAI;IAyCf,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,WAAW;IAanB,wEAAwE;IACxE,OAAO,IAAI,IAAI;CAUhB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CA2CxG"}