@cleocode/core 2026.9.26 → 2026.10.2

package/dist/cloud/nexus-vault-state.js

@@ -0,0 +1,274 @@
+/**
+ * This machine's cloud vault state (`<cleoHome>/nexus-vault.json`):
+ * secret-free, machine-local bookkeeping the vault needs between runs.
+ *
+ * - Per account: the signer {@link TrustState} learned from
+ *   `certifiedSigners` (trust only tightens, so it must survive restarts).
+ * - Per (stream, local store): the snapshot this store last pushed or
+ *   restored, which decides "behind" (another device pushed since) and
+ *   "pending changes" (this store changed since).
+ *
+ * Every read-modify-write runs under a lock file and writes atomically (temp
+ * file + rename). A file this version cannot read (truncated, invalid, or
+ * written by a newer CLEO) is moved aside with a warning, never reset in
+ * place, so a downgrade or a torn write cannot silently discard the signer
+ * pins. Nothing here is secret: keys and tokens stay in the sealed device
+ * store.
+ *
+ * @task T12336
+ * @epic T12322
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveNexusVaultStatePath } from '@cleocode/paths';
+import lockfile from 'proper-lockfile';
+import { z } from 'zod';
+import { initialTrustState } from './keys.js';
+const trustStateSchema = z.object({
+    keyVersion: z.number().int().nonnegative(),
+    pins: z.record(z.string(), z.object({
+        replicas: z.record(z.string(), z.number().int().nonnegative()),
+        checkpoints: z.record(z.string(), z.number().int().nonnegative()),
+    })),
+    revoked: z.array(z.string()),
+});
+const streamStateSchema = z.looseObject({
+    /** The snapshot this store last pushed or restored. */
+    lastCheckpointId: z.string().nullable(),
+    /** Its coversSeq: an older snapshot is never restored over it without `--checkpoint`. */
+    lastCoversSeq: z.number().int().nonnegative(),
+    updatedAt: z.string(),
+    /**
+     * A push from this store that had not recorded its snapshot yet: the parent it
+     * pushed over (T13007). Cleared when the snapshot is recorded.
+     */
+    pushInFlight: z
+        .object({
+        parentCheckpointId: z.string().nullable(),
+        at: z.string(),
+        /** The pushed snapshot's marks and per-path digests, for a recovered push (#1773 R6). */
+        gitTracked: z.array(z.string()).optional(),
+        files: z.record(z.string(), z.string()).optional(),
+    })
+        .optional(),
+    /**
+     * Paths (relative to the section root) the last synced snapshot marks as
+     * git-tracked: git's job, so they are left out of every file comparison
+     * with it, and a machine without git carries the marks on (T13019).
+     */
+    gitTracked: z.array(z.string()).optional(),
+    /**
+     * The last synced snapshot's plain files, path to digest (a prefix of the
+     * vault file digest), so a later comparison judges each file on its own,
+     * whatever either side's git tracks (T13038).
+     */
+    files: z.record(z.string(), z.string()).optional(),
+});
+const accountStateSchema = z.looseObject({
+    trust: trustStateSchema,
+    streams: z.record(z.string(), streamStateSchema).default({}),
+});
+const stateSchema = z.looseObject({
+    version: z.literal(1),
+    accounts: z.record(z.string(), accountStateSchema).default({}),
+});
+/** Key of one account in the state file. */
+const accountKey = (apiUrl, userId) => `${apiUrl} ${userId}`;
+/** Key of one local store on one stream. */
+export const vaultStreamKey = (streamId, storeRoot) => `${streamId}|${path.resolve(storeRoot)}`;
+/** How long a state access waits for another process's lock. */
+const LOCK_WAIT_MS = 15_000;
+/** Age after which a lock whose holder stopped refreshing it may be taken over. */
+const LOCK_STALE_MS = 10_000;
+/** Warning code: the state file was unreadable or newer, and was moved aside. */
+export const W_NEXUS_VAULT_STATE_MOVED = 'W_NEXUS_VAULT_STATE_MOVED';
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Read/modify/write access to the vault state file.
+ */
+export class NexusVaultState {
+    /** Absolute path of the state file. */
+    path;
+    warnings = [];
+    /** @param filePath - Override for tests; defaults to {@link resolveNexusVaultStatePath}. */
+    constructor(filePath) {
+        this.path = filePath ?? resolveNexusVaultStatePath();
+    }
+    /** Warnings raised since the last call (a moved-aside file), for the command's result. */
+    drainWarnings() {
+        const out = this.warnings;
+        this.warnings = [];
+        return out;
+    }
+    /** Run `fn` holding the state file's lock. */
+    locked(fn) {
+        fs.mkdirSync(path.dirname(this.path), { recursive: true });
+        const deadline = Date.now() + LOCK_WAIT_MS;
+        let release;
+        for (;;) {
+            try {
+                release = lockfile.lockSync(this.path, { realpath: false, stale: LOCK_STALE_MS });
+                break;
+            }
+            catch (err) {
+                const code = err.code;
+                if (code !== 'ELOCKED' || Date.now() > deadline) {
+                    throw new Error(`cannot lock the cloud vault state ${this.path}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                sleepSync(25);
+            }
+        }
+        try {
+            return fn();
+        }
+        finally {
+            release();
+        }
+    }
+    /** Move an unusable file aside (never overwrite it) and start empty. */
+    moveAside(why) {
+        const aside = `${this.path}.${why}-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+        fs.renameSync(this.path, aside);
+        this.warnings.push({
+            code: W_NEXUS_VAULT_STATE_MOVED,
+            message: why === 'newer'
+                ? `the cloud vault state was written by a newer CLEO; it was moved to ${aside} and this machine starts with empty vault state (re-run with the newer CLEO, or restore that file after upgrading)`
+                : `the cloud vault state could not be read; it was moved to ${aside} and this machine starts with empty vault state (signer trust is re-learned on the next command; the next push or pull resyncs)`,
+        });
+        return { version: 1, accounts: {} };
+    }
+    read() {
+        let raw;
+        try {
+            raw = fs.readFileSync(this.path, 'utf8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return { version: 1, accounts: {} };
+            throw err;
+        }
+        let json;
+        try {
+            json = JSON.parse(raw);
+        }
+        catch {
+            return this.moveAside('unreadable');
+        }
+        const version = json !== null && typeof json === 'object' ? json.version : null;
+        if (typeof version === 'number' && version > 1)
+            return this.moveAside('newer');
+        const parsed = stateSchema.safeParse(json);
+        return parsed.success ? parsed.data : this.moveAside('unreadable');
+    }
+    write(state) {
+        const tmp = `${this.path}.${process.pid}.${Date.now()}.tmp`;
+        const fd = fs.openSync(tmp, 'w', 0o600);
+        try {
+            fs.writeSync(fd, `${JSON.stringify(state, null, 2)}\n`);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(tmp, this.path);
+    }
+    /** Read, let `fn` change the state, and write it back, all under the lock. */
+    update(fn) {
+        return this.locked(() => {
+            const state = this.read();
+            const out = fn(state);
+            this.write(state);
+            return out;
+        });
+    }
+    /** Read under the lock (moving an unusable file aside). */
+    snapshot() {
+        return this.locked(() => this.read());
+    }
+    account(state, apiUrl, userId) {
+        const k = accountKey(apiUrl, userId);
+        state.accounts[k] ??= { trust: initialTrustState(), streams: {} };
+        return state.accounts[k];
+    }
+    /** The account's persisted signer trust state. */
+    trust(apiUrl, userId) {
+        const s = this.snapshot();
+        return structuredClone(this.account(s, apiUrl, userId).trust);
+    }
+    /** Persist the trust state returned by `certifiedSigners`. */
+    saveTrust(apiUrl, userId, trust) {
+        this.update((s) => {
+            this.account(s, apiUrl, userId).trust = structuredClone(trust);
+        });
+    }
+    /**
+     * Read the account's trust state, let `fn` evaluate it, and persist the
+     * trust it returns, all under one lock.
+     *
+     * @param apiUrl - Account API URL.
+     * @param userId - Account user id.
+     * @param fn - Receives the current trust; returns the trust to store and a result.
+     * @returns `fn`'s result.
+     */
+    updateTrust(apiUrl, userId, fn) {
+        return this.update((s) => {
+            const a = this.account(s, apiUrl, userId);
+            const { trust, result } = fn(structuredClone(a.trust));
+            a.trust = structuredClone(trust);
+            return result;
+        });
+    }
+    /** What `storeRoot` last synced with on `streamId`, or `null`. */
+    stream(apiUrl, userId, streamId, storeRoot) {
+        const s = this.snapshot();
+        return this.account(s, apiUrl, userId).streams[vaultStreamKey(streamId, storeRoot)] ?? null;
+    }
+    /**
+     * Record that a push from `storeRoot` is about to create a snapshot over
+     * `parentCheckpointId` (T13007). {@link saveStream} clears the mark; when a
+     * crash loses that write, the mark tells the next command that the head
+     * this device and replica pushed over that parent is this store's own, and
+     * what that snapshot marks and holds (`pushed`), so recovering it loses no
+     * per-path digest.
+     */
+    markPushInFlight(apiUrl, userId, streamId, storeRoot, parentCheckpointId, pushed = {}) {
+        this.update((s) => {
+            const streams = this.account(s, apiUrl, userId).streams;
+            const key = vaultStreamKey(streamId, storeRoot);
+            const prior = streams[key];
+            streams[key] = {
+                ...prior,
+                lastCheckpointId: prior?.lastCheckpointId ?? null,
+                lastCoversSeq: prior?.lastCoversSeq ?? 0,
+                // Never synced: any fork is news to this store.
+                updatedAt: prior?.updatedAt ?? new Date(0).toISOString(),
+                pushInFlight: {
+                    parentCheckpointId,
+                    at: new Date().toISOString(),
+                    ...(pushed.gitTracked !== undefined && pushed.gitTracked.length > 0
+                        ? { gitTracked: [...pushed.gitTracked].sort() }
+                        : {}),
+                    ...(pushed.files !== undefined ? { files: { ...pushed.files } } : {}),
+                },
+            };
+        });
+    }
+    /** Record that `storeRoot` now holds `checkpointId` on `streamId`. */
+    saveStream(apiUrl, userId, streamId, storeRoot, value) {
+        const { gitTracked, files, ...rest } = value;
+        this.update((s) => {
+            // In the schema's key order, so a later read-modify-write keeps the bytes.
+            this.account(s, apiUrl, userId).streams[vaultStreamKey(streamId, storeRoot)] = {
+                ...rest,
+                updatedAt: new Date().toISOString(),
+                ...(gitTracked !== undefined && gitTracked.length > 0
+                    ? { gitTracked: [...gitTracked].sort() }
+                    : {}),
+                ...(files !== undefined ? { files: { ...files } } : {}),
+            };
+        });
+    }
+}
+//# sourceMappingURL=nexus-vault-state.js.map

package/dist/cloud/nexus-vault-state.js.map

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

package/dist/cloud/nexus-vault.d.ts

@@ -0,0 +1,160 @@
+/**
+ * The cloud vault: encrypted snapshots of a project's (or this account's
+ * global) CLEO store on Cleo Nexus, with lineage, a single-writer lease and
+ * verified restore (T12336 protocol, T12337 CLI, T12338 lease handoff).
+ *
+ * A snapshot is a checkpoint on the store's journal stream (`project:<id>`,
+ * or the account's `home:<userId>`):
+ *
+ * - **Bundle**: the store's portable bundle (`exportPortableBundle`, no
+ *   secrets; for the global store without machine-local state or the config
+ *   home), sealed with the stream data key and uploaded as a blob. The data
+ *   key derives from the account master key, which is escrowed on Cleo Nexus
+ *   (released only to your approved devices; see `nexus-vault-keys.ts` for the
+ *   threat model), so this is encrypted at rest, not zero-knowledge.
+ * - **Manifest** (plaintext): per-table row counts and keyed hashes of the
+ *   store's syncing tables (`buildVaultManifest`). The server checks counts
+ *   reconcile with the journal; only key holders can check hashes.
+ * - **Lineage**: each snapshot names its parent; the server refuses one that
+ *   does not descend from the stream head (E_LINEAGE). The client refuses
+ *   earlier, with `E_NEXUS_VAULT_BEHIND`, when the head is not the snapshot
+ *   this store last pushed or restored: another device wrote since.
+ * - **Counts**: a non-genesis snapshot's counts must equal the parent's plus
+ *   the per-table deltas of the journal segments between them. A push whose
+ *   counts changed appends one signed "vault delta" segment carrying exactly
+ *   the difference (the journal sync of Stage C will carry real ops).
+ * - **Lease**: a push takes the stream's `writer` lease. Another device's
+ *   live lease refuses the push (`E_NEXUS_VAULT_LEASE_HELD`); `--force`
+ *   takes it, and the server labels the take as a fork from the holder.
+ * - **Fork label**: a `--force` push over a head this store had not synced,
+ *   or over another device's lease, carries `zz_vault_fork` (0 rows) in its
+ *   signed manifest, so every device's verify still sees the fork after the
+ *   lease is released (T13007).
+ * - **Stream format** (T13034): the vault writes checkpoint/v2 and stamps
+ *   `SYNC_SCHEMA_VERSION` (shared with the change journal) on its segments
+ *   and manifests. It reads and verifies the segment/v3 and checkpoint/v3 the
+ *   journal writes, and refuses a push onto a stream whose head snapshot is
+ *   checkpoint/v3 (the server's `E_STREAM_VERSION` ratchet) or that holds a
+ *   newer sync schema before it writes anything
+ *   (`E_NEXUS_VAULT_STREAM_UPGRADED`).
+ *
+ * Restore downloads, verifies the author's signature, decrypts, and checks
+ * every table's count and hash against the manifest before anything is
+ * placed; this machine's `local-only` rows are carried into the snapshot so
+ * machine state (replica binding, registry paths) is never overwritten, and
+ * what the snapshot no longer lists is removed afterwards (T13004).
+ *
+ * Nothing here blocks normal commands: the vault runs only when asked.
+ *
+ * @task T12336
+ * @task T12337
+ * @task T12338
+ * @epic T12322
+ */
+import type { CloudLeaseReleaseResult, CloudPushResult, CloudRestoreResult, CloudVaultScope, CloudVaultStatusResult, CloudVerifyResult } from '@cleocode/contracts';
+import { type NexusVaultOptions } from './nexus-vault-keys.js';
+/** Default lease length of a push: long enough for a large upload, short enough to hand off. */
+export declare const NEXUS_VAULT_LEASE_TTL_SECONDS = 900;
+/**
+ * Global-home paths a vault snapshot never carries (T12968): this machine's
+ * identity and runtime state, and the content CLEO's installer writes for its
+ * own version (T13022: templates, harness skills, hooks, extensions, the
+ * model catalog, migration markers, the CleoOS hub extensions and identity,
+ * and the CANT starter bundle the CleoOS postinstall rewrites, T13038).
+ * A global pull must leave them as they are, so the bundle does not hold them
+ * at all. The config home is left out too.
+ */
+export declare const VAULT_GLOBAL_EXCLUSIONS: {
+    readonly dirs: {
+        readonly state: "machine-local state (on macOS the replica registries live here); never in a vault snapshot";
+        readonly keys: "machine-local keys (evidence cache key); never in a vault snapshot";
+        readonly 'rate-limit-state': "machine-local rate-limit counters; never in a vault snapshot";
+        readonly templates: "installed by this machine's CLEO version (devices on other versions would downgrade it); never in a vault snapshot";
+        readonly skills: "installed by this machine's CLEO version (devices on other versions would downgrade it); never in a vault snapshot";
+        readonly hooks: "installed by this machine's CLEO version (devices on other versions would downgrade it); never in a vault snapshot";
+        readonly extensions: "installed by this machine's CLEO version (devices on other versions would downgrade it); never in a vault snapshot";
+        readonly 'pi-extensions': "installed by this machine's CLEO version (devices on other versions would downgrade it); never in a vault snapshot";
+        readonly 'llm-catalog': "installed by this machine's CLEO version (devices on other versions would downgrade it); never in a vault snapshot";
+        readonly '.migrations': "installed by this machine's CLEO version (devices on other versions would downgrade it); never in a vault snapshot";
+        readonly 'cant/starter': "installed by this machine's CLEO version (devices on other versions would downgrade it); never in a vault snapshot";
+    };
+    readonly files: {
+        readonly 'CLEOOS-IDENTITY.md': "installed by this machine's CLEO version (devices on other versions would downgrade it); never in a vault snapshot";
+        readonly 'device-id': "this machine's stable device id; never in a vault snapshot";
+        readonly 'web-server.json': "machine-local web server runtime state; never in a vault snapshot";
+        readonly 'sentient-state.json': "machine-local daemon state; never in a vault snapshot";
+        readonly 'device-heartbeat.stamp': "machine-local heartbeat; never in a vault snapshot";
+        readonly 'nexus.db': "machine-local code index (rebuilt per machine); never in a vault snapshot";
+        readonly 'exodus-complete': "machine-local migration marker; never in a vault snapshot";
+        readonly 'telemetry-config.json': "this install's telemetry opt-in and anonymous id; never in a vault snapshot";
+        readonly 'decide/spend.json': "this machine's decision spend ledger (in-flight reservations); never in a vault snapshot";
+        readonly 'decide/budget.json': "this machine's decision request token bucket; never in a vault snapshot";
+    };
+};
+/** Options shared by the vault commands. */
+export interface NexusVaultCommandOptions extends NexusVaultOptions {
+    /** `project` (the current project, default) or `global` (this account's global store). */
+    scope?: CloudVaultScope;
+}
+/** Options of {@link restoreNexusVault}. */
+export interface NexusVaultRestoreOptions extends NexusVaultCommandOptions {
+    /** `pull`: bring this store to the head; `restore`: any snapshot (`checkpointId`), or a project onto a new machine. */
+    mode: 'pull' | 'restore';
+    /** A specific snapshot (restore only). */
+    checkpointId?: string;
+    /** Overwrite local changes (a safety backup is taken first). */
+    force?: boolean;
+    /** Restore a project this machine does not have: its server id. */
+    projectId?: string;
+    /** Where to place a project restored onto this machine (default: the current directory). */
+    into?: string;
+    /** Called after a project restore to attach this store (defaults to `linkProjectToNexus`). */
+    relink?: (projectRoot: string) => Promise<string[]>;
+}
+/** Safety bundles kept per store under `backups/vault`; older ones are removed (T13007). */
+export declare const NEXUS_VAULT_SAFETY_BUNDLES_KEPT = 10;
+/**
+ * `cleo cloud push`: snapshot this store into the vault under the write lease.
+ *
+ * @param opts - Scope, `force` (take the lease, push over a newer head as a labelled fork),
+ *   `hold` (keep the writer lease after the push instead of releasing it) and overrides.
+ * @returns What was pushed.
+ * @throws {NexusAccountError} `E_NEXUS_VAULT_LEASE_HELD`, `E_NEXUS_VAULT_BEHIND`, `E_NEXUS_VAULT_REFUSED`,
+ *   `E_NEXUS_VAULT_STREAM_UPGRADED`, `E_NEXUS_VAULT_NOT_LINKED`, `E_NEXUS_VAULT_KEY_UNAVAILABLE`, or a
+ *   mapped API error.
+ */
+export declare function pushNexusVault(opts?: NexusVaultCommandOptions & {
+    force?: boolean;
+    hold?: boolean;
+}): Promise<CloudPushResult>;
+/**
+ * `cleo cloud pull` / `cleo cloud restore`: verify and activate a snapshot.
+ *
+ * @param opts - Mode, snapshot, project and target overrides.
+ * @returns What was restored.
+ * @throws {NexusAccountError} `E_NEXUS_VAULT_LOCAL_CHANGES`, `E_NEXUS_VAULT_VERIFY_FAILED`,
+ *   `E_NEXUS_VAULT_EMPTY`, `E_NEXUS_VAULT_KEY_UNAVAILABLE`, or a mapped API error.
+ */
+export declare function restoreNexusVault(opts: NexusVaultRestoreOptions): Promise<CloudRestoreResult>;
+/**
+ * `cleo cloud vault`: the vault's lineage, last push per device, pending changes and leases.
+ *
+ * @param opts - Scope and overrides.
+ * @returns The vault status.
+ */
+export declare function nexusVaultStatus(opts?: NexusVaultCommandOptions): Promise<CloudVaultStatusResult>;
+/**
+ * `cleo cloud verify`: compare this store with the cloud and every device's newest snapshot.
+ *
+ * @param opts - Scope and overrides.
+ * @returns The verdict and per-table comparison.
+ */
+export declare function verifyNexusVault(opts?: NexusVaultCommandOptions): Promise<CloudVerifyResult>;
+/**
+ * `cleo cloud lease release`: hand the write lease back.
+ *
+ * @param opts - Scope and overrides.
+ * @returns Whether a lease was released.
+ */
+export declare function releaseNexusVaultLease(opts?: NexusVaultCommandOptions): Promise<CloudLeaseReleaseResult>;
+//# sourceMappingURL=nexus-vault.d.ts.map

package/dist/cloud/nexus-vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nexus-vault.d.ts","sourceRoot":"","sources":["../../src/cloud/nexus-vault.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAMH,OAAO,KAAK,EACV,uBAAuB,EACvB,eAAe,EACf,kBAAkB,EAElB,eAAe,EAEf,sBAAsB,EAEtB,iBAAiB,EAGlB,MAAM,qBAAqB,CAAC;AA+D7B,OAAO,EAGL,KAAK,iBAAiB,EAIvB,MAAM,uBAAuB,CAAC;AAI/B,gGAAgG;AAChG,eAAO,MAAM,6BAA6B,MAAM,CAAC;AAMjD;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;CA6B1B,CAAC;AAkCX,4CAA4C;AAC5C,MAAM,WAAW,wBAAyB,SAAQ,iBAAiB;IACjE,0FAA0F;IAC1F,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAgkCD,4CAA4C;AAC5C,MAAM,WAAW,wBAAyB,SAAQ,wBAAwB;IACxE,uHAAuH;IACvH,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8FAA8F;IAC9F,MAAM,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACrD;AAyDD,4FAA4F;AAC5F,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAitBlD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,IAAI,GAAE,wBAAwB,GAAG;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GACxE,OAAO,CAAC,eAAe,CAAC,CAE1B;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAE7F;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,GAAE,wBAA6B,GAClC,OAAO,CAAC,sBAAsB,CAAC,CAEjC;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,wBAA6B,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAEhG;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,GAAE,wBAA6B,GAClC,OAAO,CAAC,uBAAuB,CAAC,CAElC"}