openalgo-script 0.1.0-alpha.1 → 0.4.0

package/dist/core/engine/engine.d.ts

@@ -0,0 +1,140 @@
+import type { BarState, HostBar } from './bars.js';
+import type { EngineLimits } from './budget.js';
+import type { ResolvedInput } from './inputs.js';
+import type { LoadOptions } from './load.js';
+import type { Grid } from './grids.js';
+import type { LedgerRow, OrderFrame } from './ledger/index.js';
+import type { CompiledProgram } from './types.js';
+import type { RequestPlan } from './request-plan.js';
+import type { Value } from './values/index.js';
+import type { Drawing } from './drawings.js';
+import type { BarResult, RunResult } from './results.js';
+export declare class Engine {
+    private readonly registers;
+    private readonly memory;
+    private readonly channels;
+    private readonly heap;
+    private readonly budget;
+    private readonly machine;
+    private readonly library;
+    private readonly grids;
+    private readonly onUnconfirmed;
+    private readonly alerting;
+    private readonly requests;
+    /**
+     * What this strategy sent and what became of it, `stdlib.md` 17.7. Held by
+     * the run rather than asked of the host, because a host's position row is per
+     * contract and shared: reading it is reading somebody else's trade.
+     */
+    private readonly ledger;
+    /**
+     * The instrument's session, read once from the record it belongs to.
+     *
+     * Once because the record is read once, at load, and is constant for the
+     * whole run (`host-interface.md` 4.4). A session that changed between bar ten
+     * and bar eleven would anchor the first ten bars of a study to one schedule
+     * and the rest of the same chart to another.
+     */
+    private readonly sessions;
+    /**
+     * The bars the engine has been given, which a read folds.
+     *
+     * A read of the chart's own instrument at a coarser interval is folded from
+     * these, so the fold needs the bars themselves and not only the registers
+     * derived from them. `run` seeds the whole dataset before bar 0 and `append`
+     * adds one at a time, which is the difference a `"lookahead"` read shows and
+     * the other two modes do not: lookahead reads to the end of the bucket the
+     * chart bar is inside, and on a live feed there is nothing there yet. That is
+     * the mode repainting on history, permanently and by design.
+     */
+    private known;
+    private supplied;
+    private index;
+    private updates;
+    private started;
+    private previousClose;
+    private lastClose;
+    private facts;
+    private view;
+    private failure;
+    readonly program: CompiledProgram;
+    private readonly inputs;
+    private readonly options;
+    constructor(program: CompiledProgram, inputs: readonly ResolvedInput[], options: LoadOptions, limits: EngineLimits, plans?: readonly RequestPlan[]);
+    /** Whether a failure has stopped this script. A stopped script stays stopped. */
+    get failed(): boolean;
+    /** How many bars the engine has been given. */
+    get barCount(): number;
+    /**
+     * A new bar arrives.
+     *
+     * Step 11 of the previous bar happens here rather than at the end of it,
+     * because a checkpoint is taken only if the engine is moving on to the next
+     * bar, and until one arrives the previous bar may still be re-executed.
+     */
+    append(bar: HostBar, state?: BarState, supplied?: number): BarResult;
+    /**
+     * The newest bar changed, so it runs again.
+     *
+     * Step 1: the checkpoint from the end of the previous bar is restored, except
+     * that `"live"` cells keep their current values, which is the whole of
+     * `live var`. Everything else rolls back, so executing a moving bar ten times
+     * gives the same answer as executing it once.
+     */
+    update(bar: HostBar, state?: BarState): BarResult;
+    /**
+     * A whole dataset, appended in order. Stops at the first bar that fails.
+     *
+     * The whole set is handed to the fold before bar 0 rather than discovered one
+     * bar at a time. Nothing about a confirmed or a developing read changes: both
+     * stop at the bar being executed, so running a dataset and appending it bar by
+     * bar give the same numbers. A `"lookahead"` read is the one that differs, and
+     * that difference is the mode: it reads to the end of the bucket the chart bar
+     * is inside, which exists in a dataset and does not exist on a live feed.
+     *
+     * A dataset with nothing in it is OS6010 and not an empty result, because a
+     * pane with nothing drawn on it is what a study that computed nothing also
+     * produces and only the engine can tell the two apart.
+     */
+    run(bars: readonly HostBar[], states?: readonly BarState[]): RunResult;
+    /**
+     * A frame from the destination, `host-interface.md` 7.2. Held until the next
+     * bar begins rather than folded where it lands: nothing reaches a running
+     * execution, so every position fact is constant for the length of one and a
+     * moving bar sees what its first execution saw.
+     */
+    deliver(frame: OrderFrame): void;
+    /** The strategy's own ledger, `stdlib.md` 17.7, oldest row first. */
+    orders(): readonly LedgerRow[];
+    private execute;
+    /**
+     * A bar that failed.
+     *
+     * Steps 7 to 11 do not run, the bar's output columns keep whatever the
+     * previous execution published or stay absent, and the engine reports the
+     * error with its code and source position. It does not continue to the next
+     * bar with a half executed state, so the journal is rolled back and the
+     * script is marked stopped.
+     */
+    /**
+     * A hand-over the engine refuses, before any of it has been executed.
+     *
+     * Nothing is rolled back because nothing has run: the bar was never begun,
+     * the previous bar's checkpoint still stands, and the columns already
+     * published stay as they are. The script is stopped for the same reason a
+     * failed bar stops it, which is that the next bar would be computed on a
+     * state nobody can account for.
+     */
+    private refuse;
+    private stopped;
+    /** Step 11, and the sweep that pays for the objects the bar left behind. */
+    private checkpoint;
+    private rollback;
+    /** One channel's column over every bar executed so far. */
+    column(channel: number): readonly Value[];
+    /** The drawing objects a host should render, in creation order. */
+    drawings(): readonly Drawing[];
+    /** The grids and the cells the last executed bar wrote into them. */
+    tables(): readonly Grid[];
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/core/engine/engine.d.ts.map

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

package/dist/core/engine/engine.js

@@ -0,0 +1,405 @@
+import { barField, barViewOf, factsFor } from './bars.js';
+import { alertsFor } from './alerts.js';
+import { Budget, stepBound } from './budget.js';
+import { Channels } from './channels.js';
+import { ScriptError, spanAt, unexpected } from './errors.js';
+import { guardFor } from './guard.js';
+import { hostFactsFor } from './host.js';
+import { fieldValue } from './inputs.js';
+import { manifestEntry } from './library/index.js';
+import { Machine } from './machine.js';
+import { Memory } from './memory.js';
+import { Registers } from './registers.js';
+import { Grids } from './grids.js';
+import { ledgerFor, routedEffects } from './orders.js';
+import { NO_SESSION, sessionReader } from './session/index.js';
+import { noBars, outOfOrder } from './series.js';
+import { barMinutesOf } from './timeframe.js';
+import { RequestSet } from './requests.js';
+import { Heap } from './values/index.js';
+import { drawingsIn } from './drawings.js';
+export class Engine {
+    registers;
+    memory;
+    channels;
+    heap = new Heap();
+    budget;
+    machine;
+    library = [];
+    grids;
+    onUnconfirmed;
+    alerting;
+    requests;
+    /**
+     * What this strategy sent and what became of it, `stdlib.md` 17.7. Held by
+     * the run rather than asked of the host, because a host's position row is per
+     * contract and shared: reading it is reading somebody else's trade.
+     */
+    ledger;
+    /**
+     * The instrument's session, read once from the record it belongs to.
+     *
+     * Once because the record is read once, at load, and is constant for the
+     * whole run (`host-interface.md` 4.4). A session that changed between bar ten
+     * and bar eleven would anchor the first ten bars of a study to one schedule
+     * and the rest of the same chart to another.
+     */
+    sessions;
+    /**
+     * The bars the engine has been given, which a read folds.
+     *
+     * A read of the chart's own instrument at a coarser interval is folded from
+     * these, so the fold needs the bars themselves and not only the registers
+     * derived from them. `run` seeds the whole dataset before bar 0 and `append`
+     * adds one at a time, which is the difference a `"lookahead"` read shows and
+     * the other two modes do not: lookahead reads to the end of the bucket the
+     * chart bar is inside, and on a live feed there is nothing there yet. That is
+     * the mode repainting on history, permanently and by design.
+     */
+    known = [];
+    supplied = 0;
+    index = -1;
+    updates = 0;
+    started = false;
+    previousClose = null;
+    lastClose = null;
+    facts;
+    view;
+    failure;
+    program;
+    inputs;
+    options;
+    constructor(program, inputs, options, limits, plans = []) {
+        this.program = program;
+        this.inputs = inputs;
+        this.options = options;
+        this.registers = new Registers(program.series.length);
+        this.memory = new Memory(program.cells, program.states);
+        this.channels = new Channels(program.channels);
+        this.budget = new Budget(limits, limits.steps ?? stepBound(program), program.limits.loops, options.clock);
+        this.onUnconfirmed = fieldValue(program.meta.onUnconfirmed, inputs) === true;
+        // A watched condition's title and frequency are declaration fields, which a
+        // script may write with an `input()`, and inputs are resolved at load. So
+        // they are read once here rather than per bar, as every other declaration
+        // the descriptor is built from is.
+        this.alerting = alertsFor(program, inputs);
+        for (const entry of program.lib.functions) {
+            // Verification refused a name this engine does not have, so the lookup
+            // cannot fail here and the table is resolved once rather than per call.
+            this.library.push(manifestEntry(entry.name, entry.arity));
+        }
+        const instrument = options.host?.instrument;
+        this.sessions = sessionReader(instrument?.session, typeof instrument?.timezone === 'string' ? instrument.timezone : null, barMinutesOf(instrument?.interval));
+        const facts = hostFactsFor(() => this.options.host ?? {}, {
+            answered: (id) => this.requests.answered(id),
+            failure: (id) => this.requests.failure(id),
+        });
+        this.ledger = ledgerFor(program, inputs, instrument);
+        const position = {
+            size: () => this.ledger.size(),
+            avgPrice: () => this.ledger.avgPrice(),
+        };
+        this.facts = factsFor(0, 1, {}, true, 1, NO_SESSION);
+        this.view = barViewOf({ open: null, high: null, low: null, close: null, time: null }, this.facts, null);
+        const fnPositions = program.functions.map(() => []);
+        for (const [fn, positions] of program.debug.fnPos)
+            fnPositions[fn] = positions;
+        this.machine = new Machine({
+            program,
+            registers: this.registers,
+            memory: this.memory,
+            channels: this.channels,
+            heap: this.heap,
+            budget: this.budget,
+            guard: guardFor(this.budget),
+            host: facts,
+            position,
+            library: this.library,
+            fnPositions,
+            spanAt: (line, column) => spanAt(options.source, line, column),
+        }, this.view);
+        this.requests = new RequestSet({
+            program,
+            plans: new Map(plans.map((one) => [one.request.id, one])),
+            host: options.host ?? {},
+            limits,
+            clock: options.clock,
+            library: this.library,
+            inputs,
+            facts,
+            position,
+            heapOf: () => this.heap,
+            spanAt: (line, column) => spanAt(options.source, line, column),
+        }, program.requests);
+        this.grids = new Grids(program, inputs, this.heap);
+    }
+    /** Whether a failure has stopped this script. A stopped script stays stopped. */
+    get failed() {
+        return this.failure !== undefined;
+    }
+    /** How many bars the engine has been given. */
+    get barCount() {
+        return this.supplied;
+    }
+    /**
+     * A new bar arrives.
+     *
+     * Step 11 of the previous bar happens here rather than at the end of it,
+     * because a checkpoint is taken only if the engine is moving on to the next
+     * bar, and until one arrives the previous bar may still be re-executed.
+     */
+    append(bar, state = {}, supplied = this.supplied + 1) {
+        // Before anything moves: a bar that does not follow the one before it is
+        // refused rather than executed, because every value the bar produces would
+        // be derived from a history that never happened (`series.ts`). A script
+        // that has already failed keeps the failure it has, which is the one that
+        // explains what went wrong first.
+        if (this.failure === undefined) {
+            const problem = outOfOrder(bar, this.known[this.index], this.index + 1);
+            if (problem !== undefined)
+                return this.refuse(problem);
+        }
+        if (this.started)
+            this.checkpoint();
+        this.index += 1;
+        this.supplied = Math.max(supplied, this.index + 1);
+        this.updates = 1;
+        this.started = true;
+        this.previousClose = this.lastClose;
+        if (this.known.length <= this.index)
+            this.known[this.index] = bar;
+        return this.execute(bar, state, true);
+    }
+    /**
+     * The newest bar changed, so it runs again.
+     *
+     * Step 1: the checkpoint from the end of the previous bar is restored, except
+     * that `"live"` cells keep their current values, which is the whole of
+     * `live var`. Everything else rolls back, so executing a moving bar ten times
+     * gives the same answer as executing it once.
+     */
+    update(bar, state = {}) {
+        if (!this.started)
+            return this.append(bar, state);
+        // A revision is the same bar again, so it is held to the same order: an
+        // update whose time has moved back onto the bar before it is a series the
+        // engine cannot run on, whatever it is called.
+        if (this.failure === undefined) {
+            const problem = outOfOrder(bar, this.known[this.index - 1], this.index);
+            if (problem !== undefined)
+                return this.refuse(problem);
+        }
+        this.rollback();
+        this.updates += 1;
+        // A revision replaces the bar the fold already read, so the bucket it is
+        // inside is rebuilt from this reading rather than from the one it replaced.
+        this.known[this.index] = bar;
+        return this.execute(bar, state, false);
+    }
+    /**
+     * A whole dataset, appended in order. Stops at the first bar that fails.
+     *
+     * The whole set is handed to the fold before bar 0 rather than discovered one
+     * bar at a time. Nothing about a confirmed or a developing read changes: both
+     * stop at the bar being executed, so running a dataset and appending it bar by
+     * bar give the same numbers. A `"lookahead"` read is the one that differs, and
+     * that difference is the mode: it reads to the end of the bucket the chart bar
+     * is inside, which exists in a dataset and does not exist on a live feed.
+     *
+     * A dataset with nothing in it is OS6010 and not an empty result, because a
+     * pane with nothing drawn on it is what a study that computed nothing also
+     * produces and only the engine can tell the two apart.
+     */
+    run(bars, states = []) {
+        const out = [];
+        // A dataset with nothing in it is the one hand-over that has no bar to
+        // report against, so it is answered here rather than by the loop below,
+        // which would run no iterations and return a clean, empty, wordless result.
+        if (bars.length === 0 && !this.started) {
+            const diagnostic = this.failure ?? noBars(this.options.host?.instrument);
+            this.failure = diagnostic;
+            return { bars: [], diagnostic };
+        }
+        this.known = [...bars];
+        for (let i = 0; i < bars.length; i += 1) {
+            const bar = bars[i];
+            if (bar === undefined)
+                continue;
+            const result = this.append(bar, states[i] ?? {}, bars.length);
+            out.push(result);
+            if (result.diagnostic !== undefined)
+                return { bars: out, diagnostic: result.diagnostic };
+        }
+        return { bars: out, diagnostic: undefined };
+    }
+    /**
+     * A frame from the destination, `host-interface.md` 7.2. Held until the next
+     * bar begins rather than folded where it lands: nothing reaches a running
+     * execution, so every position fact is constant for the length of one and a
+     * moving bar sees what its first execution saw.
+     */
+    deliver(frame) {
+        this.ledger.deliver(frame);
+    }
+    /** The strategy's own ledger, `stdlib.md` 17.7, oldest row first. */
+    orders() {
+        return this.ledger.rows();
+    }
+    execute(bar, state, isNew) {
+        if (this.failure !== undefined) {
+            return {
+                index: this.index,
+                columns: [],
+                applied: false,
+                effects: [],
+                frames: [],
+                alerts: [],
+                diagnostic: this.failure,
+            };
+        }
+        const index = this.index;
+        // The fold, at the boundary between two bars and before step 4. A
+        // re-execution folds nothing: the same frames reaching one bar twice would
+        // settle the same fill twice.
+        const frames = isNew ? this.ledger.settle() : [];
+        // The bar before this one, which is what says whether this bar opened a
+        // session or is inside the one that bar was already in. Read from the bars
+        // themselves rather than carried, so a re-executed bar compares against the
+        // same neighbour it compared against the first time.
+        const previous = this.known[index - 1]?.time ?? null;
+        this.facts = factsFor(index, this.supplied, state, isNew, this.updates, this.sessions.factsAt(bar.time ?? null, previous));
+        this.view = barViewOf(bar, this.facts, this.previousClose);
+        try {
+            // Step 2. Any entry a previous execution of this bar wrote is discarded.
+            this.registers.truncate(index);
+            // Step 3.
+            this.channels.clear();
+            this.registers.clearCurrent();
+            this.budget.begin(index);
+            this.grids.clear();
+            this.machine.begin(this.view, index);
+            // Step 4.
+            const slots = this.machine.slots();
+            for (const register of this.program.series) {
+                if (register.kind !== 'bar' || register.field === null)
+                    continue;
+                this.registers.set(register.id, barField(register.field, bar, this.facts));
+            }
+            // The same step fills each read's `"request"` register, absent where the
+            // answer has not arrived or the read's mode allows no value yet (2.16).
+            if (!this.requests.empty)
+                this.requests.fill(this.registers, this.known, index, isNew);
+            // Step 5. An input's value and a grid's handle land in their slots here,
+            // and nothing is resolved: that happened once, at load.
+            for (const input of this.inputs) {
+                slots[input.slot] =
+                    input.field === undefined ? input.value : barField(input.field, bar, this.facts);
+            }
+            this.grids.fill(slots);
+            // Step 6.
+            this.machine.run();
+        }
+        catch (thrown) {
+            return this.stopped(thrown);
+        }
+        // Step 7.
+        this.registers.close(index);
+        // Step 8: the columns, whatever the bar's state.
+        this.channels.publish(index);
+        // Step 9. The deferred channels and the pending effects, together: a
+        // marker, an alert and an order are one decision about one bar, and an
+        // order the language will not place stops the bar with nothing routed.
+        const applied = this.facts.isConfirmed || this.onUnconfirmed;
+        const pending = this.channels.decide(index, applied);
+        const sending = { index, time: bar.time ?? null };
+        const routed = routedEffects(this.ledger, pending, sending, this.options.host?.route);
+        if (routed.refusal !== undefined)
+            return this.stopped(new ScriptError(routed.refusal));
+        const alerts = applied
+            ? this.alerting.raise({ index, time: bar.time ?? null, isRealtime: this.facts.isRealtime }, (channel) => this.channels.at(channel, index))
+            : [];
+        // Step 10.
+        this.registers.trim(index, this.program.limits.history);
+        this.lastClose = bar.close ?? null;
+        return {
+            index,
+            columns: this.channels.row(index),
+            applied,
+            effects: routed.effects,
+            frames,
+            alerts,
+            diagnostic: undefined,
+        };
+    }
+    /**
+     * A bar that failed.
+     *
+     * Steps 7 to 11 do not run, the bar's output columns keep whatever the
+     * previous execution published or stay absent, and the engine reports the
+     * error with its code and source position. It does not continue to the next
+     * bar with a half executed state, so the journal is rolled back and the
+     * script is marked stopped.
+     */
+    /**
+     * A hand-over the engine refuses, before any of it has been executed.
+     *
+     * Nothing is rolled back because nothing has run: the bar was never begun,
+     * the previous bar's checkpoint still stands, and the columns already
+     * published stay as they are. The script is stopped for the same reason a
+     * failed bar stops it, which is that the next bar would be computed on a
+     * state nobody can account for.
+     */
+    refuse(diagnostic) {
+        this.failure = diagnostic;
+        return {
+            index: this.index,
+            columns: [],
+            applied: false,
+            effects: [],
+            frames: [],
+            alerts: [],
+            diagnostic,
+        };
+    }
+    stopped(thrown) {
+        const diagnostic = thrown instanceof ScriptError ? thrown.diagnostic : unexpected('the bar', thrown);
+        this.rollback();
+        this.failure = diagnostic;
+        return {
+            index: this.index,
+            columns: [],
+            applied: false,
+            effects: [],
+            frames: [],
+            alerts: [],
+            diagnostic,
+        };
+    }
+    /** Step 11, and the sweep that pays for the objects the bar left behind. */
+    checkpoint() {
+        this.memory.commit();
+        this.heap.commit();
+        this.heap.sweep((visit) => {
+            this.memory.walk(visit);
+            this.registers.walk(visit);
+            this.grids.walk(visit);
+        });
+    }
+    rollback() {
+        this.memory.rollback();
+        this.heap.rollback();
+    }
+    /** One channel's column over every bar executed so far. */
+    column(channel) {
+        return this.channels.column(channel, this.supplied);
+    }
+    /** The drawing objects a host should render, in creation order. */
+    drawings() {
+        return drawingsIn(this.heap);
+    }
+    /** The grids and the cells the last executed bar wrote into them. */
+    tables() {
+        return this.grids.read();
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/core/engine/engine.js.map

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

package/dist/core/engine/errors.d.ts

@@ -0,0 +1,64 @@
+/**
+ * How the engine says something went wrong, and why it does it by throwing.
+ *
+ * **Nothing the engine exposes ever throws.** A host draws many studies in one
+ * render loop and runs many customers' scripts in one process, so a script that
+ * fails has to become a diagnostic about that script and nothing else. The
+ * public surface catches everything and returns.
+ *
+ * Inside, a failure is thrown, because an error in the middle of an expression
+ * has to abandon the rest of the bar and there is no answer to return from a
+ * `DIV` that would not have to be checked again by every instruction above it.
+ * The throw crosses the interpreter and stops at the one boundary that knows
+ * what to do with it.
+ *
+ * Every failure carries a catalogue code and a position. A bare string is not
+ * available here: `diagnosticFor` is typed per code, so a call that forgets a
+ * placeholder does not compile.
+ */
+import type { DiagnosticCode, DiagnosticValues } from '../catalogue/index.js';
+import type { Diagnostic } from '../diagnostics/index.js';
+import type { SourceFile } from '../source/index.js';
+import type { Span } from '../span/index.js';
+/** A diagnostic on its way out of the machine. */
+export declare class ScriptError extends Error {
+    readonly diagnostic: Diagnostic;
+    constructor(diagnostic: Diagnostic);
+}
+/**
+ * Where a diagnostic points.
+ *
+ * A compiled program carries a line and a column per instruction and not an
+ * offset, because `debug.pos` is a position in the source rather than an index
+ * into text the engine was never given. When a host hands the engine the source
+ * file as well, the offset is worked out from the position and a renderer can
+ * draw the caret under the line; without it the line and the column still say
+ * where, which is what an error message needs.
+ */
+export declare function spanAt(source: SourceFile | undefined, line: number, column: number): Span;
+/** The position a load-time failure carries: the program, not a line of source. */
+export declare const NO_POSITION: Span;
+export declare function raise<Code extends DiagnosticCode>(code: Code, span: Span, values: DiagnosticValues[Code]): never;
+export declare function failure<Code extends DiagnosticCode>(code: Code, span: Span, values: DiagnosticValues[Code]): Diagnostic;
+/**
+ * A verification failure, `compiled-program.md` 3.5.
+ *
+ * One code covers a malformed instruction list, an unreadable encoding and an
+ * input reference naming an input that was never declared, because they are not
+ * separate fixes: all three are defects of the compiler that wrote the program
+ * and none of them is repairable by hand.
+ */
+export declare function malformed(location: string, reason: string): Diagnostic;
+/** The location half of OS6018 for an instruction, in the spelling 3.5 gives. */
+export declare function atInstruction(list: string, index: number): string;
+/**
+ * Whatever escaped that was not a diagnostic.
+ *
+ * A verified program cannot underflow the stack, jump out of bounds or address
+ * a slot that does not exist, so an exception from inside the interpreter means
+ * the program is not what verification said it was. It becomes a diagnostic on
+ * this script rather than an exception in the host's render loop, which is the
+ * whole of "one script failing takes nothing else down".
+ */
+export declare function unexpected(where: string, thrown: unknown): Diagnostic;
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/engine/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/core/engine/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C,kDAAkD;AAClD,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;gBAEpB,UAAU,EAAE,UAAU;CAKnC;AAED;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAGzF;AAED,mFAAmF;AACnF,eAAO,MAAM,WAAW,EAAE,IAA2B,CAAC;AAEtD,wBAAgB,KAAK,CAAC,IAAI,SAAS,cAAc,EAC/C,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,gBAAgB,CAAC,IAAI,CAAC,GAC7B,KAAK,CAEP;AAED,wBAAgB,OAAO,CAAC,IAAI,SAAS,cAAc,EACjD,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,gBAAgB,CAAC,IAAI,CAAC,GAC7B,UAAU,CAEZ;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAEtE;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,UAAU,CAGrE"}