@cleocode/core 2026.10.4 → 2026.10.5-rc.ci.672

package/dist/store/sync/inbox.js

@@ -0,0 +1,222 @@
+/**
+ * The receive inbox (T12344; journal spec §3.1, §3.2).
+ *
+ * Every received transaction is staged in `_sync_inbox` in stream order,
+ * keyed by `(stream, seq, txn_idx)`, so a re-pull stages nothing twice. The
+ * applier ({@link stagedTxns} → apply → {@link markTxns}) moves each through
+ * its statuses:
+ *
+ * - `staged`: received, not yet tried;
+ * - `pending`: waits for something it needs (a never-seen row or reference,
+ *   or a pending transaction it depends on); retried on every pass;
+ * - `held-skew`: its HLC is beyond the skew bound; retried, FIFO per replica;
+ * - `applied`, `conflict`, `void`: tried; `conflict` and `void` carry their
+ *   records in `_sync_conflict` and are revivable;
+ * - `refused-schema`: written by a newer schema or format; replayed after an
+ *   upgrade, never skipped.
+ *
+ * A split transaction (`part: [i, n]`) is returned only once all n parts are
+ * staged, as one transaction whose ops are the parts' ops in order (Q18).
+ *
+ * @module store/sync/inbox
+ * @task T12344
+ */
+import { LEDGER_TXN_VERSION, LedgerTxn } from '@cleocode/contracts/ledger';
+import { SYNC_SCHEMA_VERSION } from '@cleocode/contracts/sync-schema.js';
+import { withImmediateTransaction } from './clock-store.js';
+/** The statuses the applier tries again. */
+export const OPEN_INBOX_STATUSES = ['staged', 'pending', 'held-skew'];
+/**
+ * Stage a verified segment's transactions. Rows already staged (same
+ * stream, seq, index) are left alone, so a re-pull is idempotent.
+ *
+ * Exactly-once beyond the inbox's own rows is the receiver's: it stages only
+ * segments past its persisted `_sync_cursor` and advances the cursor in the
+ * same transaction (§3.1 step 3), so a segment whose applied rows were
+ * pruned after a verified checkpoint is never staged again. Counter deltas
+ * rely on it.
+ *
+ * @param db - The store (the journal schema applied); opens its own
+ *   transaction unless the caller holds one.
+ * @param stream - The stream id.
+ * @param segment - The segment and its decoded transactions.
+ * @param nowIso - The staging time.
+ * @returns How many transactions were newly staged.
+ */
+export function stageTxns(db, stream, segment, nowIso) {
+    const run = () => {
+        const ins = db.prepare(`INSERT INTO _sync_inbox (stream, seq, txn_idx, replica_id, replica_seq, device_id,
+         schema_version, txn_json, hlc, status, staged_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'staged', ?)
+       ON CONFLICT (stream, seq, txn_idx) DO NOTHING`);
+        let staged = 0;
+        segment.txns.forEach((txn, i) => {
+            const r = ins.run(stream, segment.seq, i, segment.replicaId, segment.replicaSeq, segment.deviceId, segment.schemaVersion, JSON.stringify(txn), txn.hlc, nowIso);
+            staged += Number(r.changes);
+        });
+        return staged;
+    };
+    return db.isTransaction ? run() : withImmediateTransaction(db, run);
+}
+const keyOf = (r) => ({ stream: r.stream, seq: r.seq, txnIdx: r.txn_idx });
+/** The split-transaction marker a refused part's reason carries (T13242). */
+const txnMarker = (txn) => `[txn ${txn}]`;
+/** A refused row's txn id, from its JSON or, when that is unreadable, its text. */
+function txnIdOf(text) {
+    try {
+        const raw = JSON.parse(text);
+        if (typeof raw === 'object' && raw !== null && 'txn' in raw && typeof raw.txn === 'string') {
+            return raw.txn;
+        }
+    }
+    catch {
+        // not JSON: fall back to the text
+    }
+    return /"txn"\s*:\s*"([^"\\]+)"/.exec(text)?.[1] ?? null;
+}
+/**
+ * A staged row's transaction, or why it cannot be read (T13234): a format
+ * newer than this build (`E_SCHEMA_AHEAD`), or a malformed row.
+ */
+function parseStaged(r) {
+    let raw;
+    try {
+        raw = JSON.parse(r.txn_json);
+    }
+    catch {
+        return 'malformed transaction: not JSON';
+    }
+    const ok = LedgerTxn.safeParse(raw);
+    if (ok.success)
+        return ok.data;
+    const v = typeof raw === 'object' && raw !== null && 'v' in raw && typeof raw.v === 'number' ? raw.v : 0;
+    if (v > LEDGER_TXN_VERSION || r.schema_version > SYNC_SCHEMA_VERSION) {
+        return `E_SCHEMA_AHEAD: transaction format v${v} (segment schemaVersion ${r.schema_version}) is newer than this build; upgrade CLEO to apply it`;
+    }
+    return `malformed transaction: ${ok.error.issues[0]?.message ?? 'invalid'}`;
+}
+/**
+ * The transactions the applier may try, in `(seq, txn_idx)` order: every
+ * `staged`, `pending` and `held-skew` row, a split transaction once all of
+ * its parts are staged.
+ *
+ * @param db - The store.
+ * @param stream - The stream id.
+ * @param limit - At most this many transactions; 0 for all.
+ * @returns The transactions, parts joined.
+ */
+export function stagedTxns(db, stream, limit = 0) {
+    const rows = db
+        .prepare(`SELECT stream, seq, txn_idx, replica_id, replica_seq, device_id, schema_version, txn_json, status
+       FROM _sync_inbox WHERE stream = ? AND status IN (${OPEN_INBOX_STATUSES.map(() => '?').join(', ')})
+       ORDER BY seq, txn_idx`)
+        .all(stream, ...OPEN_INBOX_STATUSES);
+    const parsed = [];
+    const nowIso = new Date().toISOString();
+    for (const r of rows) {
+        const txn = parseStaged(r);
+        if (typeof txn === 'string') {
+            // One unreadable row (a newer writer's format) never stalls the stream:
+            // it is refused, kept for replay after an upgrade, and the rest flows.
+            // Its txn id rides in the reason, so its sibling parts are found even
+            // when its JSON is unreadable.
+            const id = txnIdOf(r.txn_json);
+            const reason = id !== null ? `${txn} ${txnMarker(id)}` : txn;
+            markTxns(db, [keyOf(r)], 'refused-schema', { reason, nowIso });
+            continue;
+        }
+        parsed.push({ row: r, txn });
+    }
+    // A split transaction is refused whole (T13242): when one of its parts was
+    // refused (now or in an earlier pass), its other parts can never complete.
+    const refusedPart = db.prepare(`SELECT 1 FROM _sync_inbox WHERE stream = ? AND replica_id = ? AND status = 'refused-schema'
+       AND ((json_valid(txn_json) AND json_extract(txn_json, '$.txn') = ?)
+         OR instr(coalesce(reason, ''), ?) > 0) LIMIT 1`);
+    for (let i = parsed.length - 1; i >= 0; i--) {
+        const p = parsed[i];
+        if (!p.txn.part)
+            continue;
+        if (!refusedPart.get(stream, p.row.replica_id, p.txn.txn, txnMarker(p.txn.txn)))
+            continue;
+        markTxns(db, [keyOf(p.row)], 'refused-schema', {
+            reason: `another part of split transaction ${p.txn.txn} was refused`,
+            nowIso,
+        });
+        parsed.splice(i, 1);
+    }
+    // Parts of one split transaction: same origin replica and txn id.
+    const groups = new Map();
+    for (const p of parsed) {
+        if (!p.txn.part)
+            continue;
+        const g = `${p.row.replica_id}\u0000${p.txn.txn}`;
+        groups.set(g, [...(groups.get(g) ?? []), p]);
+    }
+    const out = [];
+    for (const p of parsed) {
+        if (limit > 0 && out.length >= limit)
+            break;
+        const base = {
+            key: keyOf(p.row),
+            replicaId: p.row.replica_id,
+            replicaSeq: p.row.replica_seq,
+            deviceId: p.row.device_id,
+            schemaVersion: p.row.schema_version,
+            status: p.row.status,
+        };
+        const part = p.txn.part;
+        if (!part) {
+            out.push({ ...base, parts: [base.key], txn: p.txn });
+            continue;
+        }
+        if (part[0] !== 1)
+            continue; // returned at its first part
+        const all = groups.get(`${p.row.replica_id}\u0000${p.txn.txn}`) ?? [];
+        const byIndex = new Map(all.map((x) => [x.txn.part?.[0], x]));
+        const ordered = Array.from({ length: part[1] }, (_, i) => byIndex.get(i + 1));
+        const complete = ordered.filter((x) => x !== undefined);
+        if (complete.length !== part[1])
+            continue; // not every part staged yet
+        const hlc = complete.reduce((m, x) => (x.txn.hlc > m ? x.txn.hlc : m), p.txn.hlc);
+        const { part: _part, ...head } = p.txn;
+        out.push({
+            ...base,
+            parts: complete.map((x) => keyOf(x.row)),
+            txn: { ...head, hlc, ops: complete.flatMap((x) => x.txn.ops) },
+        });
+    }
+    return out;
+}
+/**
+ * Set the status of a transaction's rows (every part of it).
+ *
+ * @param db - The store, inside the applier's transaction (or its own).
+ * @param keys - The transaction's parts.
+ * @param status - The new status.
+ * @param opts - The apply frame, a reason, and the time (`applied_at` for a tried status).
+ */
+export function markTxns(db, keys, status, opts) {
+    const tried = !OPEN_INBOX_STATUSES.includes(status) && status !== 'refused-schema';
+    const up = db.prepare(`UPDATE _sync_inbox SET status = ?, applied_frame = ?, reason = ?, applied_at = ?
+     WHERE stream = ? AND seq = ? AND txn_idx = ?`);
+    for (const k of keys) {
+        up.run(status, opts.frame ?? null, opts.reason ?? null, tried ? opts.nowIso : null, k.stream, k.seq, k.txnIdx);
+    }
+}
+/**
+ * Inbox rows per status for a stream (doctor and tests).
+ *
+ * @param db - The store.
+ * @param stream - The stream id.
+ * @returns Status → row count; absent statuses omitted.
+ */
+export function inboxCounts(db, stream) {
+    const rows = db
+        .prepare('SELECT status, count(*) AS n FROM _sync_inbox WHERE stream = ? GROUP BY status')
+        .all(stream);
+    const out = {};
+    for (const r of rows)
+        out[r.status] = r.n;
+    return out;
+}
+//# sourceMappingURL=inbox.js.map

package/dist/store/sync/inbox.js.map

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

package/dist/store/sync/inherit.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Inherited rows on rebind (journal spec §1.5 H3; T12753).
+ *
+ * A rebind means this store file is no longer the replica that wrote its
+ * outbox: it is a copy, a restore or a rolled-back file. Everything the old
+ * replica captured or sealed and never sent belongs to that replica, not to
+ * the new one. So, in the rebind transaction, every live capture and every
+ * sealed transaction is marked `inherited`. The sealer reads only live
+ * captures, and only non-inherited transactions are ever built or sent, so a
+ * new replica never re-emits the original's rows.
+ *
+ * What a copy changed and never sent is not lost: the S4 reconcile restores
+ * the latest checkpoint, diffs it against this store and re-emits those
+ * fields under the new replica (§1.5 three-way rule). Segmented transactions
+ * and segments are S4's to mark when they arrive.
+ *
+ * @task T12753
+ * @module store/sync/inherit
+ */
+import type { DatabaseSync } from 'node:sqlite';
+/** The rows a rebind marked `inherited`. */
+export interface InheritedRows {
+    /** Captures that were still live (unsealed). */
+    readonly captures: number;
+    /** Sealed transactions not yet carried by a segment. */
+    readonly txns: number;
+}
+/**
+ * Mark every live capture and every sealed transaction `inherited`. Runs in
+ * the caller's (rebind) transaction; a store without the outbox tables has
+ * nothing to mark.
+ *
+ * @returns How many rows were marked.
+ */
+export declare function markInheritedRows(db: DatabaseSync): InheritedRows;
+//# sourceMappingURL=inherit.d.ts.map

package/dist/store/sync/inherit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inherit.d.ts","sourceRoot":"","sources":["../../../src/store/sync/inherit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,YAAY,GAAG,aAAa,CAajE"}

package/dist/store/sync/inherit.js

@@ -0,0 +1,38 @@
+/**
+ * Inherited rows on rebind (journal spec §1.5 H3; T12753).
+ *
+ * A rebind means this store file is no longer the replica that wrote its
+ * outbox: it is a copy, a restore or a rolled-back file. Everything the old
+ * replica captured or sealed and never sent belongs to that replica, not to
+ * the new one. So, in the rebind transaction, every live capture and every
+ * sealed transaction is marked `inherited`. The sealer reads only live
+ * captures, and only non-inherited transactions are ever built or sent, so a
+ * new replica never re-emits the original's rows.
+ *
+ * What a copy changed and never sent is not lost: the S4 reconcile restores
+ * the latest checkpoint, diffs it against this store and re-emits those
+ * fields under the new replica (§1.5 three-way rule). Segmented transactions
+ * and segments are S4's to mark when they arrive.
+ *
+ * @task T12753
+ * @module store/sync/inherit
+ */
+import { hasTable } from './schema.js';
+/**
+ * Mark every live capture and every sealed transaction `inherited`. Runs in
+ * the caller's (rebind) transaction; a store without the outbox tables has
+ * nothing to mark.
+ *
+ * @returns How many rows were marked.
+ */
+export function markInheritedRows(db) {
+    const captures = hasTable(db, '_sync_capture')
+        ? Number(db.prepare("UPDATE _sync_capture SET state = 'inherited' WHERE state = 'live'").run()
+            .changes)
+        : 0;
+    const txns = hasTable(db, '_sync_txn')
+        ? Number(db.prepare("UPDATE _sync_txn SET state = 'inherited' WHERE state = 'sealed'").run().changes)
+        : 0;
+    return { captures, txns };
+}
+//# sourceMappingURL=inherit.js.map

package/dist/store/sync/inherit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inherit.js","sourceRoot":"","sources":["../../../src/store/sync/inherit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAUvC;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAAgB;IAChD,MAAM,QAAQ,GAAG,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAC;QAC5C,CAAC,CAAC,MAAM,CACJ,EAAE,CAAC,OAAO,CAAC,mEAAmE,CAAC,CAAC,GAAG,EAAE;aAClF,OAAO,CACX;QACH,CAAC,CAAC,CAAC,CAAC;IACN,MAAM,IAAI,GAAG,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAC;QACpC,CAAC,CAAC,MAAM,CACJ,EAAE,CAAC,OAAO,CAAC,iEAAiE,CAAC,CAAC,GAAG,EAAE,CAAC,OAAO,CAC5F;QACH,CAAC,CAAC,CAAC,CAAC;IACN,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAC5B,CAAC"}

package/dist/store/sync/merge/engine.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The pure merge engine (T12344; journal spec §1.7, §2.6, §2.9, §3.2, §3.6).
+ *
+ * {@link applyOp} decides one incoming I, U or D op against the stream-derived
+ * state of its row and returns the next state, the row-level effect and the
+ * conflicts to record. Receivers apply in stream `seq` order and decide by HLC
+ * (§2.9), so every replica that folds the same stream reaches the same state:
+ *
+ * - **Per-field LWW by HLC.** A column's incoming HLC is `fh[col] ?? h`; it
+ *   wins when it is greater than the column's stored HLC. LWW is commutative,
+ *   so plain columns converge whatever the order.
+ * - **Groups** merge as one LWW unit and travel whole (T13222): a U op
+ *   carries every member of a group it touches (the capture trigger records
+ *   the whole group, subtraction keeps it whole), an I op's omitted members
+ *   are NULL, and the winner sets every member. A U op carrying part of a
+ *   group is refused (`malformed`), never half-applied.
+ * - **Counters** merge by delta (`sum`: a U carries `{ $inc }` only) or by
+ *   `max`/`min` (absolute numbers only), never by plain LWW; any other shape
+ *   is refused (`malformed`), since mixing deltas and absolute values would
+ *   make the result depend on order.
+ * - **Rank-max** (pipeline_stage) is a max over (rank, HLC), with NULL and
+ *   unranked values lowest, and the winner keeps its own HLC; a restore
+ *   raises a floor below which writes are dead (T13223). It converges in
+ *   every order, HLCs included.
+ * - **Other typed rules** (absorbing states, frozen-while, write-once) are
+ *   evaluated against the current state, so where an explicit op races them
+ *   they depend on stream order and are deterministic for a given stream
+ *   (§3.5 Rule 1).
+ * - **Leave, restore and unfreeze are granted per transaction:** every op of
+ *   a transaction whose `actor.op` is such a command may use it, on every row
+ *   the transaction writes. That is deliberate: the command's own cascade
+ *   (children restored or reopened with their parent) is part of its
+ *   transaction.
+ * - **Deletes:** a D removes a live row whatever its HLC, recording the newer
+ *   edits it removes. Tombstones never resurrect: an op older than the delete
+ *   is skipped; a newer update of a deleted row is voided with an
+ *   `edit-vs-delete` conflict. A newer insert re-creates the row (a
+ *   natural-key re-add), so a re-insert racing a delete is ORDER-SENSITIVE:
+ *   deterministic per stream (§3.5 Rule 1), not order-free, since the row
+ *   state keeps no birth HLC to compare the delete against.
+ * - **Conflicts are never dropped:** a concurrent divergent edit (the op's
+ *   before-image differs from the current value) is recorded whichever side
+ *   wins, as is every typed-rule refusal or override, rank-max included.
+ * - **Schema skew is refused** explicitly: an op naming a column this schema
+ *   lacks is `refused-schema`, never partly applied ({@link checkSchemaVersion}
+ *   covers the segment level).
+ *
+ * K ops are not field merges: the re-key path of the applier handles them.
+ *
+ * @module store/sync/merge/engine
+ * @task T12344
+ */
+import { type LedgerOp, type LedgerWireValue } from '@cleocode/contracts/ledger';
+import type { FieldState, MergeContext, OpOutcome, RowState } from './types.js';
+/** A K op reached the field merge, or a spec is inconsistent. */
+export declare class MergeEngineError extends Error {
+    readonly code = "E_SYNC_MERGE_ENGINE";
+    constructor(message: string);
+}
+/** Why a payload is refused before any op is applied. */
+export interface SchemaRefusal {
+    readonly code: 'E_SCHEMA_AHEAD';
+    readonly message: string;
+}
+/**
+ * Refuse a segment or transaction written by a newer schema or format (§2.9):
+ * a segment `schemaVersion` above {@link SYNC_SCHEMA_VERSION}, or a transaction
+ * `v` above {@link LEDGER_TXN_VERSION}. The receiver stages it `refused-schema`
+ * and replays it after an upgrade; it is never silently skipped.
+ *
+ * @param segmentSchemaVersion - The segment's `schemaVersion`.
+ * @param txnVersion - The transaction's `v`, when checking one.
+ * @returns The refusal, or `null` when this build can apply it.
+ */
+export declare function checkSchemaVersion(segmentSchemaVersion: number, txnVersion?: number): SchemaRefusal | null;
+/** One rank-max candidate write. */
+export interface RankCandidate {
+    readonly value: LedgerWireValue;
+    readonly hlc: string;
+}
+/**
+ * The alive, non-dominated candidates of a rank-max column after `write`,
+ * oldest first (T13223). The current value is ALWAYS a candidate, even when
+ * a stored frontier omits it (T13232): a local write changes the row without
+ * the merge, and a frontier that dropped it would lose that write and
+ * diverge from replicas that folded it.
+ *
+ * @param rule - The column's rank-max rule.
+ * @param cur - The column's current state, or undefined.
+ * @param write - The incoming write.
+ * @param floor - The restore floor after the write, or undefined.
+ * @returns The candidates; the best by (rank, HLC) is the column's value.
+ */
+export declare function rankMaxFrontier(rule: {
+    readonly order: readonly string[];
+}, cur: FieldState | undefined, write: RankCandidate, floor: string | undefined): RankCandidate[];
+/**
+ * Decide one incoming op against the stream-derived state of its row.
+ *
+ * @param row - The row's state at the op's stream position.
+ * @param op - An I, U or D op (K ops go through the re-key path).
+ * @param ctx - The table's merge spec and the transaction's `actor.op`.
+ * @returns The next state, the row-level effect, written and skipped columns,
+ *   and every conflict to record.
+ * @throws {MergeEngineError} On a K op or an inconsistent spec.
+ *
+ * @example
+ * ```ts
+ * const out = applyOp(row, op, { table: spec, actorOp: txn.actor?.op });
+ * if (out.status === 'refused-schema') stage('refused-schema');
+ * ```
+ */
+export declare function applyOp(row: RowState, incoming: LedgerOp, ctx: MergeContext): OpOutcome;
+//# sourceMappingURL=engine.d.ts.map

package/dist/store/sync/merge/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../../src/store/sync/merge/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,EAEL,KAAK,QAAQ,EAEb,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AAIpC,OAAO,KAAK,EAGV,UAAU,EAEV,YAAY,EACZ,SAAS,EACT,QAAQ,EAET,MAAM,YAAY,CAAC;AAGpB,iEAAiE;AACjE,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,yBAAyB;gBAE1B,OAAO,EAAE,MAAM;CAI5B;AAED,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,oBAAoB,EAAE,MAAM,EAC5B,UAAU,CAAC,EAAE,MAAM,GAClB,aAAa,GAAG,IAAI,CAgBtB;AAwLD,oCAAoC;AACpC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EAC3C,GAAG,EAAE,UAAU,GAAG,SAAS,EAC3B,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,aAAa,EAAE,CAqBjB;AA4VD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,YAAY,GAAG,SAAS,CA8EvF"}