@namzu/sdk 43.0.0 → 44.1.0

package/dist/store/session-log/disk.js

@@ -0,0 +1,169 @@
+import { createReadStream } from 'node:fs';
+import { mkdir, open, stat } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { sessionLocatorFromLogFile, } from '../../session/paths.js';
+import { SessionLogConflictError, SessionLogCore, collect, walkSessionLog, } from './core.js';
+import { DiskSessionLeaseStore } from './lease.js';
+import { DiskSpillStore, syncDirectory } from './spill.js';
+/**
+ * The session log on disk: `<session-id>.jsonl` beside `<session-id>/`.
+ *
+ * ## Appends
+ *
+ * Each record is one `write` to a file opened `O_APPEND`, so a line is never
+ * interleaved with another writer's bytes. Before the write the file must be
+ * exactly as long as the writer last verified it; after it, the bytes must be
+ * where the writer put them. Either check failing is a
+ * `SessionLogConflictError`: another writer got in, which the lease exists to
+ * prevent and the fence check makes rare (a holder stalled past its expiry
+ * in the microseconds between its fence check and its write).
+ *
+ * Records others depend on — the turn lifecycle, checkpoints, decisions —
+ * are fsynced by default (`sync: 'boundaries'`). Other records are not: a
+ * process crash keeps the page cache, and a power loss that drops them leaves
+ * a torn or short tail, which the next writer repairs or which a checkpoint's
+ * anchor refuses. `sync: 'all'` fsyncs every record.
+ */
+function isErrno(error, code) {
+    return error?.code === code;
+}
+/** The bytes of one log file. */
+export class DiskLogMedium {
+    file;
+    constructor(file) {
+        this.file = file;
+    }
+    async size() {
+        try {
+            return (await stat(this.file)).size;
+        }
+        catch (error) {
+            if (isErrno(error, 'ENOENT'))
+                return 0;
+            throw error;
+        }
+    }
+    async read(offset, length) {
+        let handle;
+        try {
+            handle = await open(this.file, 'r');
+        }
+        catch (error) {
+            if (isErrno(error, 'ENOENT'))
+                return new Uint8Array(0);
+            throw error;
+        }
+        try {
+            const buffer = Buffer.alloc(length);
+            const { bytesRead } = await handle.read(buffer, 0, length, offset);
+            return buffer.subarray(0, bytesRead);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async *stream(offset) {
+        if ((await this.size()) <= offset)
+            return;
+        const stream = createReadStream(this.file, { start: offset, highWaterMark: 1 << 20 });
+        try {
+            for await (const chunk of stream)
+                yield chunk;
+        }
+        catch (error) {
+            if (!isErrno(error, 'ENOENT'))
+                throw error;
+        }
+    }
+    async append(bytes, expectedOffset, sync) {
+        await mkdir(dirname(this.file), { recursive: true });
+        const handle = await open(this.file, 'a', 0o600);
+        try {
+            const before = (await handle.stat()).size;
+            if (before !== expectedOffset) {
+                throw new SessionLogConflictError(`${this.file} is ${before} bytes; this writer verified it at ${expectedOffset}. Another writer appended; refusing to write a record that would not chain.`);
+            }
+            await handle.write(bytes);
+            if (sync)
+                await handle.datasync();
+            const after = (await handle.stat()).size;
+            if (after !== expectedOffset + bytes.byteLength) {
+                const landed = Buffer.alloc(bytes.byteLength);
+                await handle.read(landed, 0, bytes.byteLength, expectedOffset);
+                if (!landed.equals(bytes)) {
+                    throw new SessionLogConflictError(`${this.file} was appended to by another writer at the same moment; this record did not land at byte ${expectedOffset}.`);
+                }
+            }
+        }
+        finally {
+            await handle.close();
+        }
+        // The directory entry of a newly created log, before anything depends on it.
+        if (expectedOffset === 0 && sync)
+            await syncDirectory(dirname(this.file));
+    }
+    async truncate(size, expectedSize) {
+        const handle = await open(this.file, 'r+');
+        try {
+            const current = (await handle.stat()).size;
+            if (current !== expectedSize) {
+                throw new SessionLogConflictError(`${this.file} is ${current} bytes, not the ${expectedSize} measured before repairing its tail; refusing to cut a log that is still changing.`);
+            }
+            await handle.truncate(size);
+            await handle.datasync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+}
+/** A session log on disk. One instance per writer process; readers may open their own. */
+export class DiskSessionLog extends SessionLogCore {
+    file;
+    sessionDir;
+    /**
+     * See {@link DiskSessionLogOptions.locator}. `undefined` only for a log
+     * whose file is not named `<session-id>.jsonl`.
+     */
+    locator;
+    constructor(options) {
+        super({
+            sessionId: options.sessionId,
+            medium: new DiskLogMedium(options.file),
+            leases: new DiskSessionLeaseStore(options.sessionDir),
+            spills: new DiskSpillStore(options.sessionDir, options.now),
+            now: options.now,
+            spillAboveBytes: options.spillAboveBytes,
+            sync: options.sync,
+        });
+        this.file = options.file;
+        this.sessionDir = options.sessionDir;
+        if (options.locator !== undefined && options.locator.sessionId !== options.sessionId) {
+            throw new Error(`A session log's locator names session ${options.locator.sessionId}, not ${options.sessionId}.`);
+        }
+        this.locator = options.locator ?? sessionLocatorFromLogFile(options.file, options.sessionId);
+    }
+    /** The log of `locator` in a project's layout. */
+    static at(paths, locator, options = {}) {
+        return new DiskSessionLog({
+            ...options,
+            sessionId: locator.sessionId,
+            file: paths.sessionLog(locator),
+            sessionDir: paths.sessionDir(locator),
+            locator,
+        });
+    }
+}
+/**
+ * Walk a session log file, verifying the chain (spec §4.1). Yields each
+ * record with its pointer and returns the summary. A missing file is an empty
+ * log.
+ */
+export function streamSessionLog(file, options = {}) {
+    return walkSessionLog(new DiskLogMedium(file), options);
+}
+/** Read a whole session log file: strict by default, or tolerant (stops at the first break). */
+export function readSessionLog(file, options = {}) {
+    return collect(streamSessionLog(file, options));
+}
+//# sourceMappingURL=disk.js.map

package/dist/store/session-log/disk.js.map

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

package/dist/store/session-log/fold.d.ts

@@ -0,0 +1,115 @@
+import type { CheckpointId, MessageId, TurnId } from '../../types/ids/index.js';
+import type { Message } from '../../types/message/index.js';
+import type { SessionRecord } from '../../types/session/records.js';
+import type { SpillRef } from './spill.js';
+/**
+ * Folds over a session log's records: the conversation a model sees, and
+ * which turn (if any) is active.
+ *
+ * ## The message fold (spec §4.5)
+ *
+ * The context is, in order:
+ *
+ * 1. the latest `compaction`'s summary;
+ * 2. then the messages it kept (`keptMessageIds`, plus any `pinned`);
+ * 3. then every message after its `replacesSeqRange`;
+ * 4. with every `message_replaced` applied.
+ *
+ * A replacement changes a message's content in place and keeps its id and
+ * position. It applies whenever its target is in the context, including a
+ * target that a compaction keeps. So a guardrail's rewrite, a review's
+ * override or a structured-output answer is what every reader of the fold
+ * sees; the model's raw text stays in the log for audit only.
+ *
+ * Only `message`, `message_replaced` and `compaction` records move the fold.
+ * The live compaction events (`compaction_completed` and the rest) are
+ * reports, not instructions.
+ */
+/** One message of the folded context. */
+export interface FoldedMessage {
+    /** Absent for a compaction summary message, which has no record of its own. */
+    readonly messageId?: MessageId;
+    /** Seq of the record that put the message in the log (the compaction's, for a summary). */
+    readonly seq: number;
+    readonly message: Message;
+    /** Set when the record's content is a preview and the full message is in a spill. */
+    readonly spill?: SpillRef;
+    /** Set when a `message_replaced` changed this message. */
+    readonly replacedAtSeq?: number;
+}
+/** A compaction whose summary was spilled; the fold resolves it on demand. */
+export interface SpilledSummary {
+    readonly seq: number;
+    readonly spill: SpillRef;
+}
+/**
+ * The message fold, applied one record at a time.
+ *
+ * Synchronous and pure: spilled bodies are left as references
+ * ({@link FoldedMessage.spill}, {@link SessionMessageFold.spilledSummary});
+ * {@link foldSessionMessages} resolves them.
+ */
+export declare class SessionMessageFold {
+    #private;
+    get throughSeq(): number;
+    get spilledSummary(): SpilledSummary | undefined;
+    apply(record: SessionRecord): void;
+    /** The folded context, oldest first. A spilled summary is not included; see {@link foldSessionMessages}. */
+    entries(): FoldedMessage[];
+    messages(): Message[];
+}
+export interface FoldSessionMessagesOptions {
+    /** Fold only records with `seq <= throughSeq` (a checkpoint's context). */
+    readonly throughSeq?: number;
+    /** Reads a spilled body. Required when the log holds a spill; the fold refuses without it. */
+    readonly readSpill?: (ref: SpillRef) => Promise<string>;
+}
+/** A spill the fold met with no way to read it. */
+export declare class SpillUnavailableError extends Error {
+    readonly name = "SpillUnavailableError";
+}
+/**
+ * The conversation a session log holds: the fold of every record (or of the
+ * records through `throughSeq`), spilled bodies read back and checked.
+ */
+export declare function foldSessionMessages(records: Iterable<SessionRecord> | AsyncIterable<SessionRecord>, options?: FoldSessionMessagesOptions): Promise<Message[]>;
+/** The active turn as the log records it, before any lease is consulted. */
+export interface ActiveTurnRecord {
+    readonly turnId: TurnId;
+    /** Seq of its `turn_started`. */
+    readonly startedSeq: number;
+    readonly startedAt: string;
+    /** Set while its last segment record is `turn_paused`. */
+    readonly paused: boolean;
+    readonly pausedCheckpointId?: CheckpointId;
+    /**
+     * The `gen` of its latest `turn_started` or `turn_resuming`: the lease
+     * holding that is running it. A lease at a higher fence did not start it.
+     */
+    readonly ownerGen: number;
+}
+/** A record that the turn rules refuse at append time. */
+export declare class TurnRuleError extends Error {
+    readonly name = "TurnRuleError";
+}
+/**
+ * Tracks the session's one active turn (spec §4.5), record by record.
+ *
+ * `apply` in strict mode throws {@link TurnRuleError} for a record the turn
+ * rules forbid — the writer uses it to refuse an append before it is written.
+ * A reader applies records tolerantly: what is in the log is what happened.
+ */
+export declare class SessionTurnState {
+    #private;
+    get active(): ActiveTurnRecord | undefined;
+    /** The last turn that started, active or not. */
+    get lastTurnId(): TurnId | undefined;
+    /** Whether `session_started` has been applied. */
+    get started(): boolean;
+    /** Throws {@link TurnRuleError} if `record` may not follow the records applied so far. */
+    check(record: Pick<SessionRecord, 'type' | 'turnId'>): void;
+    apply(record: SessionRecord, options?: {
+        readonly strict?: boolean;
+    }): void;
+}
+//# sourceMappingURL=fold.d.ts.map

package/dist/store/session-log/fold.d.ts.map

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

package/dist/store/session-log/fold.js

@@ -0,0 +1,265 @@
+/**
+ * The message fold, applied one record at a time.
+ *
+ * Synchronous and pure: spilled bodies are left as references
+ * ({@link FoldedMessage.spill}, {@link SessionMessageFold.spilledSummary});
+ * {@link foldSessionMessages} resolves them.
+ */
+export class SessionMessageFold {
+    #slots = [];
+    #byId = new Map();
+    /**
+     * The latest replacement of every message id, whether or not its target
+     * was in the context when it was applied. Kept for good: a later record of
+     * the same message must not bring the replaced (raw) content back (§4.4).
+     */
+    #replacements = new Map();
+    #spilledSummary;
+    /** Seq of the last record applied. */
+    #throughSeq = 0;
+    get throughSeq() {
+        return this.#throughSeq;
+    }
+    get spilledSummary() {
+        return this.#spilledSummary;
+    }
+    apply(record) {
+        this.#throughSeq = record.seq;
+        switch (record.type) {
+            case 'message':
+                this.#message(record);
+                return;
+            case 'message_replaced': {
+                const spill = record.spill;
+                this.#replacements.set(record.targetMessageId, {
+                    message: record.content,
+                    seq: record.seq,
+                    ...(spill === undefined ? {} : { spill }),
+                });
+                const slot = this.#byId.get(record.targetMessageId);
+                if (slot === undefined)
+                    return;
+                slot.message = record.content;
+                slot.replacedAtSeq = record.seq;
+                // The target's own spill no longer applies; a replacement too large
+                // for its record carries its own.
+                slot.spill = spill;
+                return;
+            }
+            case 'compaction':
+                this.#compaction(record);
+                return;
+            default:
+                return;
+        }
+    }
+    #message(record) {
+        const replaced = this.#replacements.get(record.messageId);
+        const existing = this.#byId.get(record.messageId);
+        const slot = {
+            messageId: record.messageId,
+            seq: record.seq,
+            message: replaced?.message ?? record.content,
+            ...(replaced !== undefined
+                ? replaced.spill === undefined
+                    ? {}
+                    : { spill: replaced.spill }
+                : record.spill === undefined
+                    ? {}
+                    : { spill: record.spill }),
+            ...(replaced === undefined ? {} : { replacedAtSeq: replaced.seq }),
+        };
+        if (existing !== undefined) {
+            // The same message recorded twice is one message; the later record
+            // wins in place, except over a replacement, which outranks every
+            // record of its target.
+            existing.seq = slot.seq;
+            existing.message = slot.message;
+            existing.spill = slot.spill;
+            existing.replacedAtSeq = slot.replacedAtSeq;
+            return;
+        }
+        this.#slots.push(slot);
+        this.#byId.set(record.messageId, slot);
+    }
+    #compaction(record) {
+        const [, toSeq] = record.replacesSeqRange;
+        const keep = new Set([...record.keptMessageIds, ...(record.pinned ?? [])]);
+        const summary = Array.isArray(record.summary)
+            ? record.summary.map((message) => ({ seq: record.seq, message }))
+            : [];
+        this.#spilledSummary = Array.isArray(record.summary)
+            ? undefined
+            : { seq: record.seq, spill: record.summary };
+        const kept = this.#slots.filter((slot) => slot.messageId !== undefined && keep.has(slot.messageId));
+        const after = this.#slots.filter((slot) => slot.messageId !== undefined && slot.seq > toSeq && !keep.has(slot.messageId));
+        this.#slots = [...summary, ...kept, ...after];
+        this.#byId.clear();
+        for (const slot of this.#slots) {
+            if (slot.messageId !== undefined)
+                this.#byId.set(slot.messageId, slot);
+        }
+    }
+    /** The folded context, oldest first. A spilled summary is not included; see {@link foldSessionMessages}. */
+    entries() {
+        return this.#slots.map((slot) => ({ ...slot }));
+    }
+    messages() {
+        return this.#slots.map((slot) => slot.message);
+    }
+}
+/** A spill the fold met with no way to read it. */
+export class SpillUnavailableError extends Error {
+    name = 'SpillUnavailableError';
+}
+function spillMissing(ref) {
+    throw new SpillUnavailableError(`The session log references spilled content at ${ref.path}, and no spill reader was given.`);
+}
+/**
+ * The conversation a session log holds: the fold of every record (or of the
+ * records through `throughSeq`), spilled bodies read back and checked.
+ */
+export async function foldSessionMessages(records, options = {}) {
+    const fold = new SessionMessageFold();
+    for await (const record of records) {
+        if (options.throughSeq !== undefined && record.seq > options.throughSeq)
+            break;
+        fold.apply(record);
+    }
+    const out = [];
+    const spilled = fold.spilledSummary;
+    if (spilled !== undefined) {
+        const text = await (options.readSpill ?? spillMissing)(spilled.spill);
+        out.push(...JSON.parse(text));
+    }
+    for (const entry of fold.entries()) {
+        if (entry.spill === undefined) {
+            out.push(entry.message);
+            continue;
+        }
+        const text = await (options.readSpill ?? spillMissing)(entry.spill);
+        out.push(JSON.parse(text));
+    }
+    return out;
+}
+/** A record that the turn rules refuse at append time. */
+export class TurnRuleError extends Error {
+    name = 'TurnRuleError';
+}
+/**
+ * Tracks the session's one active turn (spec §4.5), record by record.
+ *
+ * `apply` in strict mode throws {@link TurnRuleError} for a record the turn
+ * rules forbid — the writer uses it to refuse an append before it is written.
+ * A reader applies records tolerantly: what is in the log is what happened.
+ */
+export class SessionTurnState {
+    #active;
+    #lastTurnId;
+    #started = false;
+    get active() {
+        return this.#active;
+    }
+    /** The last turn that started, active or not. */
+    get lastTurnId() {
+        return this.#lastTurnId;
+    }
+    /** Whether `session_started` has been applied. */
+    get started() {
+        return this.#started;
+    }
+    /** Throws {@link TurnRuleError} if `record` may not follow the records applied so far. */
+    check(record) {
+        const active = this.#active;
+        const refuse = (message) => {
+            throw new TurnRuleError(message);
+        };
+        if (record.type === 'session_started') {
+            if (this.#started)
+                refuse('session_started is the first record of a log, and only the first');
+            return;
+        }
+        if (!this.#started)
+            refuse('the first record of a log is session_started');
+        if (record.type === 'turn_started') {
+            if (active !== undefined) {
+                refuse(`turn ${active.turnId} is still active; a session has one active turn at a time`);
+            }
+            return;
+        }
+        if (record.turnId === undefined)
+            return;
+        if (active === undefined) {
+            refuse(`the record names turn ${record.turnId}, and no turn is active`);
+        }
+        const current = active;
+        if (record.turnId !== current.turnId) {
+            refuse(`the record names turn ${record.turnId}; the active turn is ${current.turnId}`);
+        }
+        if (record.type === 'turn_resuming' && !current.paused) {
+            // Resuming an interrupted turn is allowed; the writer decides interrupted vs running.
+            return;
+        }
+        if (current.paused && record.type !== 'turn_resuming' && !CLOSES_OR_DECIDES.has(record.type)) {
+            refuse(`turn ${current.turnId} is paused; only turn_resuming, a decision record or a terminal record may follow`);
+        }
+        if (record.type === 'turn_paused' && current.paused) {
+            refuse(`turn ${current.turnId} is already paused`);
+        }
+    }
+    apply(record, options = {}) {
+        if (options.strict)
+            this.check(record);
+        switch (record.type) {
+            case 'session_started':
+                this.#started = true;
+                return;
+            case 'turn_started':
+                this.#active = {
+                    turnId: record.turnId,
+                    startedSeq: record.seq,
+                    startedAt: record.ts,
+                    paused: false,
+                    ownerGen: record.gen,
+                };
+                this.#lastTurnId = record.turnId;
+                return;
+            case 'turn_paused':
+                if (this.#active?.turnId === record.turnId) {
+                    this.#active = {
+                        ...this.#active,
+                        paused: true,
+                        pausedCheckpointId: record.checkpointId,
+                    };
+                }
+                return;
+            case 'turn_resuming':
+                if (this.#active?.turnId === record.turnId) {
+                    const { pausedCheckpointId: _dropped, ...rest } = this.#active;
+                    this.#active = { ...rest, paused: false, ownerGen: record.gen };
+                }
+                return;
+            case 'turn_completed':
+            case 'turn_failed':
+                if (this.#active?.turnId === record.turnId)
+                    this.#active = undefined;
+                return;
+            default:
+                return;
+        }
+    }
+}
+/** Records that may follow a paused turn without resuming it. */
+const CLOSES_OR_DECIDES = new Set([
+    'turn_completed',
+    'turn_failed',
+    'decision_requested',
+    'decision_resolved',
+    'decision_expired',
+    'checkpoint_pruned',
+    'audit',
+    'log_repaired',
+    'message_replaced',
+    'session_updated',
+]);
+//# sourceMappingURL=fold.js.map

package/dist/store/session-log/fold.js.map

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

package/dist/store/session-log/heal.d.ts

@@ -0,0 +1,34 @@
+import type { TurnId } from '../../types/ids/index.js';
+import type { SessionRecordDraft } from './core.js';
+/**
+ * Repairing a torn tail (spec §4.1).
+ *
+ * A crash in the middle of an append leaves a last line with no newline. It
+ * is not a record, and appending after it would glue the next record onto the
+ * fragment and break the chain for good. So the writer that takes the lease
+ * next cuts the log back to the end of its last complete line — durably, and
+ * only if the log is still the length it measured — and appends
+ * `log_repaired{truncatedBytes, lastGoodSeq}` so the repair is itself on the
+ * record.
+ *
+ * Only a torn TAIL is repaired. A complete line that fails the chain is not a
+ * crash artefact, and a writer refuses to append to it: collecting around
+ * damage could erase the only bytes that explain it.
+ *
+ * The record is appended inside the active turn when there is one (the
+ * envelope carries `turnId` exactly when a record is inside a turn). A log
+ * torn before its `session_started` was complete is cut to zero and gets no
+ * record, because nothing may precede `session_started`; the caller starts
+ * the session again.
+ */
+export interface TornTailRepair {
+    /** Bytes cut from the end of the log. */
+    readonly truncatedBytes: number;
+    /** The last complete record kept; 0 when the log was cut to nothing. */
+    readonly lastGoodSeq: number;
+    /** The active turn at the repair, if any. */
+    readonly activeTurnId?: TurnId;
+}
+/** The `log_repaired` record for a repair, or `undefined` when the log was cut to nothing. */
+export declare function repairRecordDraft(repair: TornTailRepair): SessionRecordDraft | undefined;
+//# sourceMappingURL=heal.d.ts.map

package/dist/store/session-log/heal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heal.d.ts","sourceRoot":"","sources":["../../../src/store/session-log/heal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAA;AACtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAEnD;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,WAAW,cAAc;IAC9B,yCAAyC;IACzC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,6CAA6C;IAC7C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,kBAAkB,GAAG,SAAS,CAQxF"}

package/dist/store/session-log/heal.js

@@ -0,0 +1,12 @@
+/** The `log_repaired` record for a repair, or `undefined` when the log was cut to nothing. */
+export function repairRecordDraft(repair) {
+    if (repair.truncatedBytes <= 0 || repair.lastGoodSeq === 0)
+        return undefined;
+    return {
+        type: 'log_repaired',
+        ...(repair.activeTurnId === undefined ? {} : { turnId: repair.activeTurnId }),
+        truncatedBytes: repair.truncatedBytes,
+        lastGoodSeq: repair.lastGoodSeq,
+    };
+}
+//# sourceMappingURL=heal.js.map

package/dist/store/session-log/heal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heal.js","sourceRoot":"","sources":["../../../src/store/session-log/heal.ts"],"names":[],"mappings":"AAkCA,8FAA8F;AAC9F,MAAM,UAAU,iBAAiB,CAAC,MAAsB;IACvD,IAAI,MAAM,CAAC,cAAc,IAAI,CAAC,IAAI,MAAM,CAAC,WAAW,KAAK,CAAC;QAAE,OAAO,SAAS,CAAA;IAC5E,OAAO;QACN,IAAI,EAAE,cAAc;QACpB,GAAG,CAAC,MAAM,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC;QAC7E,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,WAAW,EAAE,MAAM,CAAC,WAAW;KACT,CAAA;AACxB,CAAC"}