openalgo-script 0.2.0 → 0.5.0

package/dist/core/backtest/record.d.ts

@@ -0,0 +1,299 @@
+/**
+ * The run record: a whole run as a plain JSON document.
+ *
+ * **The record is the conformance case.** That is the one decision this module
+ * exists to hold, and everything in it follows from it: no object reference, no
+ * function, no dependence on this implementation's internals, and nothing that
+ * only this engine can read. A record carries the script revision, the compiled
+ * program, the bars, the settings the host chose, the frames the destination
+ * answered in delivery order, the fills the engine folded in fold order, the
+ * ledger the run ended with, the diagnostics and the report.
+ *
+ * **The bars are inline or referenced, and both carry the same hash.** Inline is
+ * the conformance form, because a case has to hold every byte of its own input.
+ * Referenced is the operational form, because the smallest deployment has a one
+ * megabyte request body and nothing that grows with history may travel in one.
+ * A replay whose bars do not hash to the record's hash is OS6022 rather than a
+ * silently different study.
+ *
+ * **The frames name an intent by ordinal and never by an engine's own id**,
+ * because a case cannot know what id another engine minted. The same reason the
+ * ledger rows here are flat words rather than this engine's own types.
+ *
+ * The record is written through the existing canonical encoding, so there is one
+ * canonical writer in the repository and key order and number form are fixed for
+ * everybody.
+ */
+import type { RecordedFill, Report } from '../accounting/index.js';
+import type { Diagnostic } from '../diagnostics/index.js';
+import type { CompiledProgram, SourceStamp } from '../emit/index.js';
+import type { Instrument, LedgerRow } from '../engine/index.js';
+import type { BacktestSettings } from './settings.js';
+/** One bar as a record holds it. */
+export interface RecordedBar {
+    readonly time: number | null;
+    readonly open: number | null;
+    readonly high: number | null;
+    readonly low: number | null;
+    readonly close: number | null;
+    readonly volume: number | null;
+    readonly oi: number | null;
+}
+/**
+ * The bars, held or pointed at.
+ *
+ * Both forms carry the same hash, computed the same way over the canonical
+ * tuple of each bar, so a referenced record can be turned into an inline one by
+ * whoever holds the bars and the result is the same case.
+ */
+export type BarsInRecord = {
+    readonly form: 'inline';
+    readonly hash: string;
+    readonly count: number;
+    readonly rows: readonly RecordedBar[];
+} | {
+    readonly form: 'referenced';
+    readonly hash: string;
+    readonly count: number;
+    readonly firstTime: number | null;
+    readonly lastTime: number | null;
+};
+/** The columns of `conformance.md`'s frames.csv, in its order and with its names. */
+export interface RecordedFrame {
+    readonly afterBar: number;
+    /** An ordinal, 1-based, never an engine's own id. */
+    readonly intent: number;
+    readonly status: string;
+    readonly filledQty: number;
+    readonly avgFillPrice: number | null;
+    readonly orderRef: string | null;
+    readonly text: string | null;
+    /**
+     * The destination's own instant for this frame, or null where it stated none.
+     *
+     * **One field of the ledger is folded from it.** `host-interface.md` 7.2
+     * gives a frame a `time` and `stdlib.md` 17.7 moves `updatedAt` to it, so a
+     * record that dropped it wrote a ledger no engine reading the case back could
+     * fold to: handed frames with no instant, that engine leaves every
+     * `updatedAt` at `placedAt`, and the two disagree on exactly the rows whose
+     * destination answered later than the bar that placed the order.
+     *
+     * Absent rather than substituted, because 7.2 lets a destination state none
+     * and a row whose frame stated none keeps the instant it had.
+     */
+    readonly time: number | null;
+}
+/** A ledger row of `stdlib.md` 17.7, flattened: the `orders` channel of expected.json. */
+export interface RecordedOrder {
+    readonly intent: number;
+    readonly orderRef: string;
+    readonly tag: string;
+    readonly leg: string;
+    readonly positionRef: number;
+    readonly symbol: string | null;
+    readonly exchange: string | null;
+    readonly product: string;
+    readonly side: string;
+    readonly qty: number | null;
+    readonly qtyType: string;
+    readonly type: string | null;
+    readonly price: number | null;
+    readonly trigger: number | null;
+    readonly status: string;
+    readonly filledQty: number;
+    readonly avgFillPrice: number | null;
+    readonly rejection: string | null;
+    readonly placedAt: number | null;
+    readonly updatedAt: number | null;
+    readonly units: number | null;
+}
+/** A diagnostic as a record holds it: the code, the span and the bar. */
+export interface RecordedDiagnostic {
+    readonly code: string;
+    readonly line: number;
+    readonly column: number;
+    readonly severity: string;
+    readonly barIndex: number | null;
+}
+/** One run, whole, and readable by an engine that is not this one. */
+export interface RunRecord {
+    readonly recordVersion: number;
+    readonly engine: {
+        readonly name: string;
+        readonly version: string;
+    };
+    readonly languageVersion: string;
+    /** Already plain data. */
+    readonly program: CompiledProgram;
+    readonly programHash: string;
+    /** Hash, lines, file: the script revision. */
+    readonly source: SourceStamp;
+    /**
+     * The source text itself, or null on a record written before version 2.
+     *
+     * **A record is the conformance case, and a case has to hold `script.os`.**
+     * `source` above identifies the script and cannot reproduce it: a hash is a
+     * fingerprint, so it settles whether two files are the same and yields
+     * neither of them. Without the text a stored record could be replayed months
+     * later and still not be handed to anybody else to run, which is the whole
+     * claim the suite exists to test.
+     *
+     * It lives here and not on the compiled program on purpose. A program is
+     * executable data that no engine needs the source to run, and it is the
+     * versioned artefact adopters depend on; putting the text there would send a
+     * script everywhere its program travels and widen the format every engine
+     * has to read. The record is the thing that wants to be self-contained.
+     */
+    readonly sourceText: string | null;
+    readonly settings: BacktestSettings;
+    /**
+     * The instrument record of `host-interface.md` 4.1, as the engine was handed
+     * it, or null on a record written before version 3.
+     *
+     * **A case holds `instrument.json`, and `conformance.md` section 2 says that
+     * file is this record.** The contract in `settings` is the money layer's
+     * snapshot of the same instrument and holds six of the twelve facts; the
+     * ones a script reads and the money never does, the interval, the timezone,
+     * the session and the volume flag, were handed to the engine and written
+     * down nowhere. A case harvested from such a record either omitted a fact
+     * the page requires or stated one the run never had, and either way the
+     * second engine ran a different study than the one the expected output
+     * came from.
+     *
+     * It is the whole record and not the six facts beside the contract, because
+     * what is recorded is what the engine read at load, verbatim, and a reader
+     * should not have to compose it.
+     */
+    readonly instrument: Instrument | null;
+    readonly bars: BarsInRecord;
+    /** What the destination answered, in delivery order. */
+    readonly frames: readonly RecordedFrame[];
+    /** What the engine folded, in fold order. */
+    readonly fills: readonly RecordedFill[];
+    /** The ledger at the end, oldest first. */
+    readonly orders: readonly RecordedOrder[];
+    readonly diagnostics: readonly RecordedDiagnostic[];
+    readonly report: Report;
+}
+/**
+ * The revision of this document's own shape.
+ *
+ * A reader is handed a record and has to know what it is looking at before it
+ * reads a field, so the number is first in the document and is written by this
+ * file alone. It moves when a channel is added or a meaning changes, never when
+ * a figure in a report does.
+ */
+export declare const RECORD_VERSION = 4;
+/** The parts a run hands over, each already in the shape the record holds. */
+export interface RecordParts {
+    readonly program: CompiledProgram;
+    /**
+     * The script's own text, so the record can become a conformance case.
+     *
+     * Optional because a caller that has only a compiled program cannot invent
+     * it, and a run is still worth recording without it. `caseFilesFrom` is the
+     * one thing that then cannot be served, and it says so rather than writing a
+     * case with a hole in it.
+     */
+    readonly sourceText?: string;
+    readonly settings: BacktestSettings;
+    /** The instrument record the engine was handed, `host-interface.md` 4.1. */
+    readonly instrument: Instrument;
+    readonly bars: readonly RecordedBar[];
+    /**
+     * Whether the bars travel in the record or are pointed at.
+     *
+     * Inline is the conformance form, because a case holds every byte of its own
+     * input. Referenced is the operational form, because nothing that grows with
+     * history may travel in a request body. Both carry the same hash over the
+     * same canonical tuples, so one becomes the other without becoming a
+     * different case.
+     */
+    readonly form: 'inline' | 'referenced';
+    readonly frames: readonly RecordedFrame[];
+    readonly fills: readonly RecordedFill[];
+    readonly orders: readonly RecordedOrder[];
+    readonly diagnostics: readonly RecordedDiagnostic[];
+    readonly report: Report;
+}
+/**
+ * One run, as the document another engine is handed.
+ *
+ * Nothing is computed here. Every channel arrives folded, because what a record
+ * says has to be what the run did rather than what a second fold of the same
+ * inputs came to: a record that recomputed its own report would agree with
+ * itself whatever the engine had actually done.
+ */
+export declare function recordOf(parts: RecordParts): RunRecord;
+/**
+ * The bars, held or pointed at, and the same hash either way.
+ *
+ * The referenced form keeps the first and last times so that a reader can say
+ * which bars are wanted without holding them, and the count so that a set of
+ * the wrong length is known to be wrong before it is hashed.
+ */
+export declare function barsIn(bars: readonly RecordedBar[], form: 'inline' | 'referenced'): BarsInRecord;
+/**
+ * The hash a record names its bars by.
+ *
+ * Over the canonical tuple of each bar, in the order they were supplied, and
+ * through the canonical encoding the compiled program is hashed with, so there
+ * is one canonical writer in the repository rather than two that agree until
+ * one of them is changed. A tuple rather than an object, because the field
+ * order is then the specification's and not a sort's.
+ */
+export declare function barsHash(bars: readonly RecordedBar[]): string;
+/**
+ * The record as the bytes another engine reads.
+ *
+ * Through the canonical encoding, so key order is fixed, every number is in the
+ * shortest decimal form that reads back as itself, and two runs of the same
+ * record produce the same bytes on every machine. That is what makes the
+ * reproducibility test a byte comparison rather than a tour of the fields.
+ */
+export declare function recordToJson(record: RunRecord): string;
+/**
+ * The run, without who produced it.
+ *
+ * **`engine` is provenance, and provenance is not part of the run.** The claim
+ * a rerun makes is that the run is a function of the record, and that claim has
+ * to survive the engine it runs on being upgraded: a record stored under
+ * `0.3.0` and rerun under `0.4.0` produces the same trades, the same fills and
+ * the same money, and a document carrying the version stamp inside the bytes
+ * being compared says it does not.
+ *
+ * It was compared as whole bytes until the first version bump would have broken
+ * it, which is a test that passes for exactly as long as nothing changes and
+ * then fails for the one reason that is not a defect. So the stamp stays in the
+ * record, because knowing which engine wrote a run is worth keeping, and the
+ * comparison is made over everything else.
+ */
+export declare function runBytes(record: RunRecord): string;
+/**
+ * A record read back from those bytes.
+ *
+ * A parse and not a validation: what comes back is the document as it was
+ * written, and a document this engine did not write is the caller's to trust or
+ * not. The one thing asserted is the revision, because reading a later
+ * revision's fields under this one's rules is how a record silently becomes a
+ * different run.
+ */
+export declare function recordFromJson(text: string): RunRecord | null;
+/**
+ * One ledger row, flattened into the words a case file prints.
+ *
+ * The engine's own types do not cross: a second engine has its own, and a
+ * channel written in this one's would be a case only this one could read. The
+ * intent is an ordinal for the same reason, because no engine can know what id
+ * another minted.
+ *
+ * `qtyType` comes from the intent rather than from the row, because the unit a
+ * quantity is counted in is per order and not per leg: an order the engine
+ * sized itself is in units whatever the declaration counts in, and a row that
+ * printed the declaration's unit for it would state a quantity in a unit it was
+ * never measured in.
+ */
+export declare function orderIn(row: LedgerRow, intent: number, qtyType: string): RecordedOrder;
+/** One diagnostic, as a record holds it: the code, the span and the bar. */
+export declare function diagnosticIn(diagnostic: Diagnostic, barIndex: number | null): RecordedDiagnostic;
+//# sourceMappingURL=record.d.ts.map

package/dist/core/backtest/record.d.ts.map

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

package/dist/core/backtest/record.js

@@ -0,0 +1,243 @@
+import { canonicalNumber, canonicalise, programHash, sha256, sourceHash } from '../emit/index.js';
+import { VERSION } from '../version/index.js';
+/**
+ * The revision of this document's own shape.
+ *
+ * A reader is handed a record and has to know what it is looking at before it
+ * reads a field, so the number is first in the document and is written by this
+ * file alone. It moves when a channel is added or a meaning changes, never when
+ * a figure in a report does.
+ */
+export const RECORD_VERSION = 4;
+/**
+ * The revision each later channel arrived in.
+ *
+ * A record written before a channel existed reads with that channel absent,
+ * and this table is what `recordFromJson` reads it from: one row per channel
+ * added since version 1, so the rule for an old record is stated once and
+ * grows by a line when the next channel does.
+ *
+ * `frameTime` is a field of a row rather than a channel of the document, and it
+ * is a row here for the same reason the other two are: what a reader has to
+ * know is which revision it arrived in. Where the absence is written differs,
+ * and that is the reader's business below, not this table's.
+ */
+const ADDED_IN = { sourceText: 2, instrument: 3, frameTime: 4 };
+/** What this engine calls itself in a record it wrote. */
+const ENGINE_NAME = 'openscript';
+/**
+ * One run, as the document another engine is handed.
+ *
+ * Nothing is computed here. Every channel arrives folded, because what a record
+ * says has to be what the run did rather than what a second fold of the same
+ * inputs came to: a record that recomputed its own report would agree with
+ * itself whatever the engine had actually done.
+ */
+export function recordOf(parts) {
+    return {
+        recordVersion: RECORD_VERSION,
+        engine: { name: ENGINE_NAME, version: VERSION },
+        languageVersion: canonicalNumber(parts.program.openscript.language),
+        program: parts.program,
+        programHash: programHash(parts.program),
+        source: parts.program.source,
+        sourceText: textFor(parts),
+        settings: parts.settings,
+        instrument: parts.instrument,
+        bars: barsIn(parts.bars, parts.form),
+        frames: parts.frames,
+        fills: parts.fills,
+        orders: parts.orders,
+        diagnostics: parts.diagnostics,
+        report: parts.report,
+    };
+}
+/**
+ * The source text, checked against the hash the program already carries.
+ *
+ * A check rather than a promise, and it costs one hash of a few kilobytes. The
+ * failure it exists for is quiet: a caller that passes the text of a different
+ * revision than the one it compiled produces a case whose script does not make
+ * its own expected output, and the engine being tested gets the blame for a
+ * disagreement that was in the case all along.
+ */
+function textFor(parts) {
+    const text = parts.sourceText;
+    if (text === undefined)
+        return null;
+    if (sourceHash(text) !== parts.program.source.hash) {
+        throw new Error('openscript: the source text does not hash to the source hash the program carries');
+    }
+    return text;
+}
+/**
+ * The bars, held or pointed at, and the same hash either way.
+ *
+ * The referenced form keeps the first and last times so that a reader can say
+ * which bars are wanted without holding them, and the count so that a set of
+ * the wrong length is known to be wrong before it is hashed.
+ */
+export function barsIn(bars, form) {
+    const hash = barsHash(bars);
+    if (form === 'inline') {
+        return { form: 'inline', hash, count: bars.length, rows: bars };
+    }
+    return {
+        form: 'referenced',
+        hash,
+        count: bars.length,
+        firstTime: bars[0]?.time ?? null,
+        lastTime: bars[bars.length - 1]?.time ?? null,
+    };
+}
+/**
+ * The hash a record names its bars by.
+ *
+ * Over the canonical tuple of each bar, in the order they were supplied, and
+ * through the canonical encoding the compiled program is hashed with, so there
+ * is one canonical writer in the repository rather than two that agree until
+ * one of them is changed. A tuple rather than an object, because the field
+ * order is then the specification's and not a sort's.
+ */
+export function barsHash(bars) {
+    const tuples = bars.map((bar) => [
+        bar.time,
+        bar.open,
+        bar.high,
+        bar.low,
+        bar.close,
+        bar.volume,
+        bar.oi,
+    ]);
+    return 'sha256:' + sha256(canonicalise(tuples));
+}
+/**
+ * The record as the bytes another engine reads.
+ *
+ * Through the canonical encoding, so key order is fixed, every number is in the
+ * shortest decimal form that reads back as itself, and two runs of the same
+ * record produce the same bytes on every machine. That is what makes the
+ * reproducibility test a byte comparison rather than a tour of the fields.
+ */
+export function recordToJson(record) {
+    return canonicalise(record);
+}
+/**
+ * The run, without who produced it.
+ *
+ * **`engine` is provenance, and provenance is not part of the run.** The claim
+ * a rerun makes is that the run is a function of the record, and that claim has
+ * to survive the engine it runs on being upgraded: a record stored under
+ * `0.3.0` and rerun under `0.4.0` produces the same trades, the same fills and
+ * the same money, and a document carrying the version stamp inside the bytes
+ * being compared says it does not.
+ *
+ * It was compared as whole bytes until the first version bump would have broken
+ * it, which is a test that passes for exactly as long as nothing changes and
+ * then fails for the one reason that is not a defect. So the stamp stays in the
+ * record, because knowing which engine wrote a run is worth keeping, and the
+ * comparison is made over everything else.
+ */
+export function runBytes(record) {
+    const { engine: _engine, ...run } = record;
+    return canonicalise(run);
+}
+/**
+ * A record read back from those bytes.
+ *
+ * A parse and not a validation: what comes back is the document as it was
+ * written, and a document this engine did not write is the caller's to trust or
+ * not. The one thing asserted is the revision, because reading a later
+ * revision's fields under this one's rules is how a record silently becomes a
+ * different run.
+ */
+export function recordFromJson(text) {
+    const parsed = JSON.parse(text);
+    if (parsed === null || typeof parsed !== 'object')
+        return null;
+    const record = parsed;
+    const version = record.recordVersion;
+    if (typeof version !== 'number' || version < 1 || version > RECORD_VERSION)
+        return null;
+    // An earlier revision is readable and a later one is not, and the asymmetry
+    // is the point. A later revision may mean something by a field this one
+    // thinks it knows, which is how a record silently becomes a different run. An
+    // earlier one only ever has fewer: every channel it carries means here what
+    // it meant there, and the ones added since are absent rather than wrong. So a
+    // run stored months ago still reads, which is the whole of what it was stored
+    // for, and a channel it never carried reads as absent.
+    if (version === RECORD_VERSION)
+        return record;
+    return {
+        ...record,
+        sourceText: version >= ADDED_IN.sourceText ? record.sourceText : null,
+        instrument: version >= ADDED_IN.instrument ? record.instrument : null,
+        frames: version >= ADDED_IN.frameTime ? record.frames : timeless(record.frames),
+    };
+}
+/**
+ * The frames of a record written before a frame carried an instant.
+ *
+ * The absence is written on every frame rather than on the record, because the
+ * channel is a field of a row: a reader that left the field undefined would
+ * hand the case projection an undefined where the column's absent spelling
+ * belongs, and the file would read `undefined` back to the next engine. The
+ * frames are left as they are when they are not an array, because this is a
+ * parse and not a validation and a document this engine did not write is the
+ * caller's to trust or not.
+ */
+function timeless(frames) {
+    if (!Array.isArray(frames))
+        return frames;
+    return frames.map((frame) => ({ ...frame, time: null }));
+}
+/**
+ * One ledger row, flattened into the words a case file prints.
+ *
+ * The engine's own types do not cross: a second engine has its own, and a
+ * channel written in this one's would be a case only this one could read. The
+ * intent is an ordinal for the same reason, because no engine can know what id
+ * another minted.
+ *
+ * `qtyType` comes from the intent rather than from the row, because the unit a
+ * quantity is counted in is per order and not per leg: an order the engine
+ * sized itself is in units whatever the declaration counts in, and a row that
+ * printed the declaration's unit for it would state a quantity in a unit it was
+ * never measured in.
+ */
+export function orderIn(row, intent, qtyType) {
+    return {
+        intent,
+        orderRef: row.orderRef,
+        tag: row.tag,
+        leg: row.leg,
+        positionRef: row.positionRef,
+        symbol: row.instrument.symbol,
+        exchange: row.instrument.exchange,
+        product: row.product,
+        side: row.side,
+        qty: row.qty,
+        qtyType,
+        type: row.type,
+        price: row.price,
+        trigger: row.trigger,
+        status: row.status,
+        filledQty: row.filledQty,
+        avgFillPrice: row.avgFillPrice,
+        rejection: row.rejection === '' ? null : row.rejection,
+        placedAt: row.placedAt,
+        updatedAt: row.updatedAt,
+        units: row.units,
+    };
+}
+/** One diagnostic, as a record holds it: the code, the span and the bar. */
+export function diagnosticIn(diagnostic, barIndex) {
+    return {
+        code: diagnostic.code,
+        line: diagnostic.span.line,
+        column: diagnostic.span.column,
+        severity: diagnostic.severity,
+        barIndex,
+    };
+}
+//# sourceMappingURL=record.js.map

package/dist/core/backtest/record.js.map

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

package/dist/core/backtest/replay.d.ts

@@ -0,0 +1,48 @@
+import type { Report } from '../accounting/index.js';
+import type { Diagnostic } from '../diagnostics/index.js';
+import type { BacktestResult } from './drive.js';
+import type { RecordedBar, RunRecord } from './record.js';
+/** The report a record folds to, or why it could not be folded. */
+export type ReplayResult = {
+    readonly ok: true;
+    readonly report: Report;
+} | {
+    readonly ok: false;
+    readonly diagnostic: Diagnostic;
+};
+/**
+ * The record's own report, computed again from its own fills.
+ *
+ * The bars are the record's where it carries them and the caller's where it
+ * points at them, and either way they are hashed against what the record names
+ * before a figure is computed from them.
+ */
+export declare function replay(record: RunRecord, bars?: readonly RecordedBar[] | null): ReplayResult;
+/**
+ * The same run, executed again.
+ *
+ * Everything the run depended on is in the record: the program, the bars, the
+ * settings and the inputs. So a rerun takes no argument the record does not
+ * already hold, except the bars a referenced record points at rather than
+ * carries, and the record it produces is comparable with the original field for
+ * field and byte for byte.
+ */
+export declare function rerun(record: RunRecord, bars?: readonly RecordedBar[] | null): BacktestResult;
+type BarsResult = {
+    readonly ok: true;
+    readonly bars: readonly RecordedBar[];
+} | {
+    readonly ok: false;
+    readonly diagnostic: Diagnostic;
+};
+/**
+ * The bars a record was made from, proved to be those bars.
+ *
+ * A record carrying its own bars is still checked against any that are supplied
+ * beside them, because supplying a different set is exactly the mistake worth
+ * catching: the caller believes they are replaying this run and they are
+ * studying another one.
+ */
+export declare function barsOf(record: RunRecord, supplied: readonly RecordedBar[] | null): BarsResult;
+export {};
+//# sourceMappingURL=replay.d.ts.map

package/dist/core/backtest/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../../src/core/backtest/replay.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAkB,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAErE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAG1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAKjD,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE1D,mEAAmE;AACnE,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;CAAE,CAAC;AAE5D;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,GAAE,SAAS,WAAW,EAAE,GAAG,IAAW,GAAG,YAAY,CAoBlG;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,GAAE,SAAS,WAAW,EAAE,GAAG,IAAW,GAAG,cAAc,CAcnG;AAED,KAAK,UAAU,GACX;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;CAAE,CAAC;AAE5D;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,WAAW,EAAE,GAAG,IAAI,GAAG,UAAU,CAY7F"}