@cleocode/core 2026.10.12 → 2026.10.13

package/dist/docs/section-leases.js

@@ -0,0 +1,344 @@
+/**
+ * Local section lease manager — T13356 (Epic T13340 / Saga T13339 · spec
+ * `cleodocs-rearch-design` §2 option b).
+ *
+ * ## Matched semantics
+ *
+ * llmtxt ships a `LeaseManager` concept (`dist/leases.js`, task T285) but
+ * the `llmtxt/leases` subpath is missing from the package exports map
+ * (upstream kryptobaseddev/llmtxt#16), and the class that IS reachable
+ * through the main entry is a REST client (`baseUrl` + `apiKey` + `fetch`
+ * against `/api/v1/documents/:slug/sections/:sid/lease`) — there is no
+ * local server to call. T13356 AC1 therefore accepts this LOCAL lease
+ * module with identical semantics, which mirrors the upstream contract:
+ *
+ * > "Leases are ADVISORY — the CRDT layer still accepts writes from
+ * > non-holders. 409 is a social signal, not a hard lock." — llmtxt
+ * > dist/leases.js (T285)
+ *
+ * - **Identity** — a lease is `{ leaseId, holder, expiresAt }` scoped to
+ *   `(slug, sectionId)`, exactly llmtxt's `Lease` interface. This module
+ *   adds `sessionId`/`acquiredAt`/`reason` (the session tie T13356
+ *   requires; llmtxt's server held equivalent holder metadata).
+ * - **Acquire** — `acquire(slug, sectionId, ttlSeconds, reason?)` with the
+ *   TTL bounded to 1–300 s, llmtxt's documented `durationSeconds` range. A
+ *   held, unexpired lease yields the 409 equivalent: a `LeaseConflict`
+ *   naming `holder`/`expiresAt` (advisory result, not an error). The
+ *   throwing variant's message matches llmtxt byte-for-byte:
+ *   `Section is already leased by <holder> until <expiresAt>`.
+ * - **Release / renew** — holder-session-only (a different session cannot
+ *   release or renew another holder's lease); renewing with no held lease
+ *   fails, mirroring llmtxt's "No active lease to renew".
+ * - **Auto-renew** — `startAutoRenew(thresholdSeconds = 10)` renews when
+ *   the TTL drops below the threshold, llmtxt's default.
+ * - **Expiry / staleness** — a lease never outlives its session without
+ *   renew: only the owning session can renew, so a dead session's lease
+ *   expires at `expiresAt`; an EXPIRED lease is stale and any session may
+ *   take it over (`tookOverFrom` names the stale holder).
+ *
+ * ## Storage — local-only JSON, deliberately NOT a cleo.db table
+ *
+ * Leases NEVER replicate (spec §2: "leases are local-only rows, always").
+ * This module keeps them in `.cleo/section-leases.json`, written
+ * atomically (tmp file + rename, the `writeBackupSidecar` pattern,
+ * T12535). A JSON file — not a table — is the honest choice: no migration,
+ * no gate 21/28/36/37 classification ceremony for ephemeral advisory state,
+ * and it structurally cannot be mistaken for a syncing table. The known
+ * trade-off, accepted deliberately: read-modify-write across PROCESSES is
+ * last-write-wins (no cross-process lock); the lease is advisory, the CRDT
+ * layer preserves content regardless, and CLEO's store discipline is a
+ * single active writer per store. Promote to a classified local-only table
+ * if multi-process contention ever matters (the classification pattern is
+ * `section_crdt_states`, landed with T13354).
+ *
+ * Not wired into the section edit flow yet — that lands with the T13356
+ * wiring slice after #2144 merges.
+ *
+ * @module
+ * @task T13356
+ * @epic T13340
+ * @saga T13339
+ */
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { getCleoDirAbsolute } from '../paths.js';
+/** Minimum lease TTL in seconds (llmtxt's `durationSeconds` lower bound). */
+export const MIN_LEASE_TTL_SECONDS = 1;
+/** Maximum lease TTL in seconds (llmtxt's `durationSeconds` upper bound). */
+export const MAX_LEASE_TTL_SECONDS = 300;
+/** Default auto-renew threshold in seconds (llmtxt's default). */
+export const DEFAULT_RENEW_THRESHOLD_SECONDS = 10;
+/** Thrown by {@link acquireOrThrow} — mirrors llmtxt's `LeaseConflictError`. */
+export class SectionLeaseConflictError extends Error {
+    /** The current holder agent id. */
+    holder;
+    /** When the blocking lease expires (ISO-8601). */
+    expiresAt;
+    constructor(holder, expiresAt) {
+        super(`Section is already leased by ${holder} until ${expiresAt}`);
+        this.name = 'SectionLeaseConflictError';
+        this.holder = holder;
+        this.expiresAt = expiresAt;
+    }
+}
+/** Composite lease key (`${slug}::${sectionId}`). */
+function leaseKey(slug, sectionId) {
+    return `${slug}::${sectionId}`;
+}
+/** Resolve the leases file path for a project root. */
+function leasesFilePath(projectRoot) {
+    return join(getCleoDirAbsolute(projectRoot), 'section-leases.json');
+}
+/** Clamp a requested TTL into llmtxt's 1–300 s range. */
+function clampTtl(seconds) {
+    if (!Number.isFinite(seconds))
+        return MIN_LEASE_TTL_SECONDS;
+    return Math.min(MAX_LEASE_TTL_SECONDS, Math.max(MIN_LEASE_TTL_SECONDS, Math.floor(seconds)));
+}
+/** Read the leases file, tolerating a missing or malformed one. */
+function readLeaseFile(projectRoot) {
+    const path = leasesFilePath(projectRoot);
+    if (!existsSync(path))
+        return { version: 1, leases: {} };
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (parsed &&
+            typeof parsed === 'object' &&
+            parsed.leases &&
+            typeof parsed.leases === 'object') {
+            return { version: 1, leases: parsed.leases };
+        }
+        return { version: 1, leases: {} };
+    }
+    catch {
+        return { version: 1, leases: {} };
+    }
+}
+/**
+ * Atomically persist the leases file (tmp file + rename, the
+ * `writeBackupSidecar` pattern): a crash mid-write can at worst leave an
+ * orphaned tmp file, never a torn JSON document.
+ */
+function writeLeaseFile(projectRoot, file) {
+    const dest = leasesFilePath(projectRoot);
+    mkdirSync(dirname(dest), { recursive: true });
+    const tmp = `${dest}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, JSON.stringify(file, null, 2));
+    renameSync(tmp, dest);
+}
+/** Whether a lease has expired at `nowMs` (epoch ms). */
+function isExpired(lease, nowMs) {
+    const expiryMs = Date.parse(lease.expiresAt);
+    return Number.isNaN(expiryMs) || nowMs >= expiryMs;
+}
+/** Conflict view of a lease. */
+function conflictOf(lease) {
+    return {
+        leaseId: lease.leaseId,
+        holder: lease.holder,
+        sessionId: lease.sessionId,
+        expiresAt: lease.expiresAt,
+    };
+}
+/**
+ * Local advisory lease manager for section edit scopes.
+ *
+ * One manager per (process, session). State is file-backed, so a second
+ * manager on the same project sees this manager's leases (and vice versa).
+ */
+export class SectionLeaseManager {
+    projectRoot;
+    sessionId;
+    holder;
+    now;
+    autoRenewTimer = null;
+    constructor(projectRoot, options) {
+        if (options.sessionId.trim().length === 0) {
+            // @sync-invariant none:local-only a lease must be tied to a session; the leases file is local-only advisory state, not a synced row
+            throw new Error('SectionLeaseManager requires a non-empty sessionId');
+        }
+        this.projectRoot = projectRoot;
+        this.sessionId = options.sessionId;
+        this.holder = options.holder ?? options.sessionId;
+        this.now = options.now ?? Date.now;
+    }
+    /**
+     * Acquire an advisory lease on `(slug, sectionId)`.
+     *
+     * A held, unexpired lease yields `{ ok: false, conflict }` — the 409
+     * equivalent, an advisory signal rather than an error (llmtxt: "409 is a
+     * social signal, not a hard lock"). An EXPIRED lease is stale: any
+     * session may take it over, and `tookOverFrom` names the stale holder.
+     *
+     * @param slug - Document slug.
+     * @param sectionId - Section id.
+     * @param ttlSeconds - Requested TTL, clamped to 1–300 s (llmtxt's range).
+     * @param reason - Optional human-readable reason.
+     */
+    async acquire(slug, sectionId, ttlSeconds, reason) {
+        const file = readLeaseFile(this.projectRoot);
+        const key = leaseKey(slug, sectionId);
+        const existing = file.leases[key];
+        const nowMs = this.now();
+        let tookOverFrom;
+        if (existing !== undefined && !isExpired(existing, nowMs)) {
+            return { ok: false, conflict: conflictOf(existing) };
+        }
+        if (existing !== undefined) {
+            tookOverFrom = conflictOf(existing);
+        }
+        const ttl = clampTtl(ttlSeconds);
+        const lease = {
+            leaseId: randomUUID(),
+            holder: this.holder,
+            sessionId: this.sessionId,
+            slug,
+            sectionId,
+            ...(reason !== undefined ? { reason } : {}),
+            acquiredAt: new Date(nowMs).toISOString(),
+            expiresAt: new Date(nowMs + ttl * 1000).toISOString(),
+        };
+        file.leases[key] = lease;
+        writeLeaseFile(this.projectRoot, file);
+        return tookOverFrom !== undefined ? { ok: true, lease, tookOverFrom } : { ok: true, lease };
+    }
+    /**
+     * Throwing variant of {@link acquire}: raises {@link SectionLeaseConflictError}
+     * with llmtxt's exact message shape when the section is held.
+     *
+     * @returns The acquired lease.
+     */
+    async acquireOrThrow(slug, sectionId, ttlSeconds, reason) {
+        const result = await this.acquire(slug, sectionId, ttlSeconds, reason);
+        if (!result.ok) {
+            // @sync-invariant none:local-only the conflict is the advisory 409 equivalent; the leases file is local-only state, not a synced row
+            throw new SectionLeaseConflictError(result.conflict.holder, result.conflict.expiresAt);
+        }
+        return result.lease;
+    }
+    /**
+     * Release a lease — only the owning session may release it.
+     *
+     * @returns Whether a lease was removed (false when unheld or held by
+     *   another session).
+     */
+    async release(slug, sectionId) {
+        const file = readLeaseFile(this.projectRoot);
+        const key = leaseKey(slug, sectionId);
+        const existing = file.leases[key];
+        if (existing === undefined || existing.sessionId !== this.sessionId)
+            return false;
+        delete file.leases[key];
+        writeLeaseFile(this.projectRoot, file);
+        return true;
+    }
+    /**
+     * Renew a lease, extending its TTL — only the owning session may renew.
+     *
+     * @param slug - Document slug.
+     * @param sectionId - Section id.
+     * @param ttlSeconds - New TTL, clamped to 1–300 s.
+     */
+    async renew(slug, sectionId, ttlSeconds) {
+        const file = readLeaseFile(this.projectRoot);
+        const key = leaseKey(slug, sectionId);
+        const existing = file.leases[key];
+        if (existing === undefined)
+            return { ok: false, notHeld: true };
+        const nowMs = this.now();
+        if (isExpired(existing, nowMs))
+            return { ok: false, notHeld: true };
+        if (existing.sessionId !== this.sessionId) {
+            return { ok: false, conflict: conflictOf(existing) };
+        }
+        const ttl = clampTtl(ttlSeconds);
+        const lease = {
+            ...existing,
+            expiresAt: new Date(nowMs + ttl * 1000).toISOString(),
+        };
+        file.leases[key] = lease;
+        writeLeaseFile(this.projectRoot, file);
+        return { ok: true, lease };
+    }
+    /**
+     * Current lease status for `(slug, sectionId)`: the live (unexpired)
+     * lease, or `null` when free or expired. Never throws.
+     */
+    async status(slug, sectionId) {
+        const file = readLeaseFile(this.projectRoot);
+        const existing = file.leases[leaseKey(slug, sectionId)];
+        if (existing === undefined || isExpired(existing, this.now()))
+            return null;
+        return existing;
+    }
+    /**
+     * Start an auto-renew loop (llmtxt parity): renews when the remaining TTL
+     * drops below `thresholdSeconds` (default 10 s). In-process timer; a
+     * manager that stops renewing (crash, dead session) lets the lease expire
+     * at its TTL, after which any session may take over.
+     *
+     * @param slug - Document slug.
+     * @param sectionId - Section id.
+     * @param ttlSeconds - TTL applied at each renew, clamped to 1–300 s.
+     * @param thresholdSeconds - Renew when the remaining TTL drops below this.
+     */
+    startAutoRenew(slug, sectionId, ttlSeconds, thresholdSeconds = DEFAULT_RENEW_THRESHOLD_SECONDS) {
+        this.stopAutoRenew();
+        const intervalMs = Math.max(250, Math.floor((thresholdSeconds * 1000) / 2));
+        this.autoRenewTimer = setInterval(() => {
+            void (async () => {
+                const current = await this.status(slug, sectionId);
+                if (current === null) {
+                    this.stopAutoRenew();
+                    return;
+                }
+                const remainingMs = Date.parse(current.expiresAt) - this.now();
+                if (remainingMs <= thresholdSeconds * 1000) {
+                    await this.renew(slug, sectionId, ttlSeconds);
+                }
+            })();
+        }, intervalMs);
+        // Advisory coordination only — never keep the process alive on it.
+        if (typeof this.autoRenewTimer.unref === 'function')
+            this.autoRenewTimer.unref();
+    }
+    /** Stop the auto-renew loop (llmtxt parity). */
+    stopAutoRenew() {
+        if (this.autoRenewTimer !== null) {
+            clearInterval(this.autoRenewTimer);
+            this.autoRenewTimer = null;
+        }
+    }
+    /** Whether the auto-renew loop is running. */
+    get autoRenewRunning() {
+        return this.autoRenewTimer !== null;
+    }
+}
+/**
+ * Staleness predicate (T13356): a lease is stale — overwritable by any
+ * session — when its TTL has expired. (Session death alone does not kill an
+ * unexpired lease; conservatism is safe because a dead session cannot
+ * renew, so its lease is bounded by the TTL regardless.)
+ *
+ * @param lease - The lease to check.
+ * @param nowMs - Current time (epoch ms).
+ * @returns Whether the lease is stale.
+ */
+export function isStaleSectionLease(lease, nowMs) {
+    return isExpired(lease, nowMs);
+}
+/**
+ * List the LIVE (unexpired) section leases of one doc. Expired leases are
+ * omitted: they are stale, and the next acquire takes them over.
+ *
+ * @param projectRoot - Absolute path to the CLEO project root.
+ * @param slug - The doc's live slug.
+ * @returns The live leases, in file order.
+ */
+export async function listSectionLeases(projectRoot, slug) {
+    const file = readLeaseFile(projectRoot);
+    const nowMs = Date.now();
+    return Object.values(file.leases).filter((lease) => lease.slug === slug && !isExpired(lease, nowMs));
+}
+//# sourceMappingURL=section-leases.js.map

package/dist/docs/section-leases.js.map

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

package/dist/docs/section-merge.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Section CRDT merge engine — the pure core of the CleoDocs re-architecture
+ * write path (T13355 · spec `cleodocs-rearch-design` §2 option b · D11165).
+ *
+ * Every document section is one Loro document (root `LoroText` named
+ * `content`), persisted as opaque snapshot bytes in the local-only
+ * `section_crdt_states` table. This module is the ONLY production importer of
+ * `llmtxt/crdt-primitives` (the llmtxt WASM-backed Loro primitives); the
+ * store orchestration in `section-write-path.ts` composes these functions
+ * with the canonical `conduit-doc-history.ts` accessors.
+ *
+ * Merge composition (spike finding, T13353): the WASM `crdt_merge_updates`
+ * is LOSSY in llmtxt@2026.5.15 — it returns an empty-doc snapshot for any
+ * input (kryptobaseddev/llmtxt#17, tracked in T13356). All merging here
+ * therefore composes updates via sequential {@link mergeSectionUpdates}
+ * (`crdt_apply_update`), which Loro makes idempotent and convergent:
+ * applying each peer's incremental update in turn yields every edit with an
+ * order-independent final text. `crdt_merge_updates` must NOT be used in the
+ * production path until the upstream fix lands.
+ *
+ * @module
+ * @task T13355
+ * @epic T13340
+ * @saga T13339
+ */
+/**
+ * Deterministic section id for a split index. Section ids are positional
+ * (`s0` is the H1 + preamble, `s1` the first `## ` block, …): stable across
+ * devices for the same document shape and independent of heading text.
+ * Positional ids are a known simplification — heading-anchored ids are the
+ * filed follow-up (T13584).
+ *
+ * @param index - The section's position in {@link splitDocIntoSections}.
+ * @returns The section id recorded in `sections_modified`.
+ */
+export declare function sectionId(index: number): string;
+/**
+ * Split a markdown document into sections deterministically: the H1 +
+ * preamble (everything before the first `## ` heading) is section 0; each
+ * `## ` heading starts a new section that runs (with its nested `###`
+ * blocks) to the next `## ` or EOF. Concatenating the sections with
+ * {@link joinSections} reproduces the input byte-for-byte, so the split is
+ * lossless and order-stable.
+ *
+ * @param markdown - The full document text.
+ * @returns The sections in document order.
+ */
+export declare function splitDocIntoSections(markdown: string): string[];
+/**
+ * The inverse of {@link splitDocIntoSections}.
+ *
+ * @param sections - Sections in document order.
+ * @returns The reassembled document text.
+ */
+export declare function joinSections(sections: readonly string[]): string;
+/**
+ * Seed a section Loro state from full text (a new or re-based section).
+ *
+ * @param text - The section's full text.
+ * @returns A Loro snapshot encoding the section.
+ */
+export declare function seedSectionState(text: string): Buffer;
+/**
+ * Express one local edit as an incremental Loro update against a base
+ * state. The bundled primitives are append-shaped: the edit is the text to
+ * append to the base section (callers compute it as the tail of the new
+ * text when the old text is a prefix of it).
+ *
+ * @param base - The base section snapshot the edit was authored against.
+ * @param appended - The text the edit appends to the base.
+ * @returns The incremental update (the delta only, not a full snapshot).
+ */
+export declare function makeSectionEditUpdate(base: Buffer, appended: string): Buffer;
+/**
+ * Merge incremental section updates onto a base snapshot by sequential
+ * `crdt_apply_update`. This is the production merge composition: Loro import
+ * is idempotent and convergent, so the result carries every applied edit and
+ * is independent of update order. Do NOT replace this with
+ * `crdt_merge_updates` — that WASM export is lossy in llmtxt@2026.5.15
+ * (T13353 spike, T13356, kryptobaseddev/llmtxt#17).
+ *
+ * @param base - The base section snapshot.
+ * @param updates - Peer incremental updates, in any order.
+ * @returns The merged section snapshot.
+ */
+export declare function mergeSectionUpdates(base: Buffer, updates: readonly Buffer[]): Buffer;
+/**
+ * Extract the plain text of a section snapshot.
+ *
+ * @param state - A Loro snapshot from {@link seedSectionState} or {@link mergeSectionUpdates}.
+ * @returns The section's current text.
+ */
+export declare function sectionStateText(state: Buffer): string;
+/**
+ * Apply one section's new text to its stored snapshot.
+ *
+ * `baseText` is the section text the incoming edit was AUTHORED AGAINST —
+ * the caller's concurrency reference (T13674). A base-less write passes the
+ * previous head's section text (single-writer assumption: the writer read
+ * the head and edited it). A write carrying a declared base passes the base
+ * version's section text, so a writer whose fetch predates a concurrent
+ * landing is recognized as stale instead of being mistaken for a
+ * single writer replacing the head.
+ *
+ * While the stored state equals the base text it holds no unlanded edit
+ * relative to what the writer saw, and any difference the writer authored
+ * is an ordinary edit — which the append-shaped primitives cannot express,
+ * so the section is re-seeded from the input and projects EXACTLY
+ * (mid-text replaces and deletions apply verbatim, never a fabricated
+ * concatenation — T13589). When the stored state differs from the base
+ * text, another writer's edit landed after the caller's fetch (T13674):
+ *
+ *   - an incoming edit that is a pure APPEND relative to the common base
+ *     (`nextText` extends `baseText`) composes onto the stored state, so
+ *     both tails survive — this is never a fabrication;
+ *   - any NON-append incoming edit (a replace or delete relative to the
+ *     base) CANNOT be expressed with append-only primitives without
+ *     inventing text, so the function reports `conflicted: true` and keeps
+ *     the stored state untouched. The write path lands the incoming edit as
+ *     its own append-only version row, keeps the stored projection as the
+ *     head, and records the conflict on the head — both versions preserved,
+ *     nothing fabricated.
+ *
+ * Semantics:
+ *
+ *   - `stored === null` (first write of the section): seed a fresh state
+ *     from the new text.
+ *   - The stored text equals the new text: no-op (`changed: false`).
+ *   - `baseText === null` (no base text available for this section — no
+ *     head/base yet, or the reference version's blob is not resolvable
+ *     locally): the single-writer assumption; re-seed from the new text
+ *     (exact).
+ *   - The stored text equals `baseText` (single writer against the
+ *     reference): re-seed from the new text — the input projects exactly,
+ *     deletions included.
+ *   - The stored text differs from `baseText` and the incoming text equals
+ *     `baseText`: the writer authored nothing new; no-op.
+ *   - The stored text differs from `baseText` and the incoming text
+ *     extends `baseText` (append): compose the incoming tail onto the
+ *     stored state; both edits survive, `conflicted: false`.
+ *   - The stored text differs from `baseText` and the incoming edit is a
+ *     non-append relative to `baseText`: `conflicted: true`, stored state
+ *     kept — the write path records the conflict and lands both versions.
+ *
+ * @param stored - The section's stored snapshot, or `null` when none exists.
+ * @param nextText - The section's new full text.
+ * @param baseText - The section's text in the version the incoming edit was
+ *   authored against (previous head for base-less writes, declared base
+ *   otherwise), or `null` when no reference text is available.
+ * @returns The resulting snapshot, whether it changed, and whether the edit
+ *   is a non-append concurrent edit the caller must record as a conflict.
+ * @task T13674 (the baseText reference; T13589/T13595 for the merge shapes)
+ */
+export declare function applySectionTextEdit(stored: Buffer | null, nextText: string, baseText: string | null): {
+    snapshot: Buffer;
+    changed: boolean;
+    conflicted: boolean;
+};
+//# sourceMappingURL=section-merge.d.ts.map

package/dist/docs/section-merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"section-merge.d.ts","sourceRoot":"","sources":["../../src/docs/section-merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AASH;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAa/D;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAMpF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CA8B7D"}