openalgo-script 0.1.0-alpha.1 → 0.4.0

package/dist/adapters/charts/requests.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Another instrument's bars: the one thing a study needs that the chart's own
+ * bars cannot answer.
+ *
+ * Everything else this adapter maps is computed from bars the chart already
+ * holds, this included where the read is of the chart's own instrument: the
+ * engine folds those itself and this is never asked. A read of **another**
+ * instrument is different, and the difference is the whole of this file.
+ *
+ * **The engine asks once and synchronously; the chart answers later.** A
+ * request's identity is fixed before bar 0 (`compiled-program.md` 2.16), so the
+ * engine settles the whole set at load and asks the host for each one there and
+ * then. A chart's transport is a promise. So the two are joined by a station
+ * that lives in the study instance's own store: the engine's question is
+ * answered from what the station holds now, which on the first pass is nothing,
+ * and the answer for a read nobody has fetched yet is `pending`. The read is
+ * absent, `req.isReady` is false, the rest of the study keeps drawing, and that
+ * is exactly what `stdlib.md` 15.5 describes.
+ *
+ * **The lifecycle is what has a transport, and it runs after the first
+ * calculation.** A chart computes a study once before it attaches its
+ * lifecycle, so a station that waited for a transport before answering would
+ * refuse the study at load rather than draw it while the bars arrive. Instead
+ * the first calculation records what it was asked for, the lifecycle brings the
+ * transport and fetches it, and the recompute it then asks for is the one that
+ * has the bars. A study is drawn twice and never refused for a fetch that had
+ * not happened yet.
+ *
+ * **A range is a floor, never a promise.** What the host is asked for is the
+ * chart's own span, extended back by the read's `warmup` in requested bars and
+ * forward to the end of the bucket the newest chart bar is inside, and then
+ * quantised to bucket boundaries. Quantising is what stops a fetch per bar: the
+ * range a chart asks for is then the same range for every bar inside one
+ * requested bar, and it widens once when a bucket closes. A host that serves
+ * less gets a read that is absent for longer, never a wrong number.
+ *
+ * **What was fetched keeps serving while the next fetch is in flight.** The
+ * alternative is a line that breaks every time a bucket closes, which looks like
+ * a defect in the study rather than a refresh in the transport. The first fetch
+ * has nothing to serve and is the only one that reads as pending.
+ *
+ * **A failure is the host's own words.** A transport that rejects is OS6009
+ * carrying the message it rejected with, which is the one the chart writes when
+ * a host registered no provider at all: `req.error(read)` then says so in the
+ * script, the data status says so to the user, and the study keeps drawing
+ * everything that does not depend on the read.
+ */
+import type { RequestProvider } from '../../core/engine/index.js';
+import type { ChartBar, ChartStore } from './contract.js';
+import type { ChartAttachContext } from './surfaces.js';
+export declare class Station {
+    private readonly entries;
+    /** What the last calculation asked about, keyed the same way. */
+    private readonly wanted;
+    private transport;
+    private closed;
+    private unsubscribe;
+    /**
+     * The provider the engine is loaded with, bound to the bars on screen.
+     *
+     * Asking for one is the start of a round: the engine is about to ask about
+     * every read this program makes, so what was wanted before this moment is
+     * what the previous program wanted. A setting that names a different
+     * instrument would otherwise leave the old one being fetched for as long as
+     * the study lives, and reported on.
+     */
+    provider(bars: readonly ChartBar[]): RequestProvider;
+    /**
+     * The range each read needs, against the bars as they now stand.
+     *
+     * A calculation that reused the held engine never asked the provider
+     * anything, so nothing would notice that the newest chart bar has moved into
+     * the next requested bucket. This is what notices: it widens what is wanted,
+     * and the fetch that follows asks for the recompute that reads it. An answer
+     * is never spliced into a run that is already past the bars it would have
+     * changed, which is `host-interface.md` 5.3.
+     */
+    extend(bars: readonly ChartBar[]): void;
+    /**
+     * After a calculation: start what is missing and say where the study stands.
+     *
+     * It is the end of the calculation rather than the middle of it because a
+     * fetch that resolves asks for a recompute, and asking for one from inside the
+     * calculation it would replace is a loop waiting to be written.
+     */
+    settle(): void;
+    /** The lifecycle, with the transport the first calculation did not have. */
+    open(ctx: ChartAttachContext): void;
+    /**
+     * The lifecycle is over: nothing in flight may write anything again.
+     *
+     * What was fetched is kept. A chart runs the lifecycle again after a settings
+     * change, and throwing the bars away there would put a network round trip
+     * behind moving a slider. A fetch that was in flight is marked as not in
+     * flight, so a station that is opened again starts it rather than waiting for
+     * an answer whose callback has been told to do nothing.
+     */
+    close(): void;
+    /** Every read the host refused, tried again from the beginning. */
+    private again;
+    private pump;
+    private fetch;
+    /** An answer, once the transport has one. */
+    private landed;
+    private refused;
+    private failed;
+    /** Where the study's own data stands, in the four words the chart has. */
+    private status;
+}
+/** The station this instance holds, created by whichever half arrives first. */
+export declare function stationIn(store: ChartStore): Station;
+/** The station this instance holds, when it has one. */
+export declare function stationOf(store: ChartStore): Station | undefined;
+//# sourceMappingURL=requests.d.ts.map

package/dist/adapters/charts/requests.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requests.d.ts","sourceRoot":"","sources":["../../../src/adapters/charts/requests.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,OAAO,KAAK,EAGV,eAAe,EAEhB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAmB,MAAM,eAAe,CAAC;AAsCzE,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAClD,OAAO,CAAC,SAAS,CAAwB;IACzC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAA2B;IAE9C;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,GAAG,eAAe;IAepD;;;;;;;;;OASG;IACH,MAAM,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,GAAG,IAAI;IAYvC;;;;;;OAMG;IACH,MAAM,IAAI,IAAI;IAQd,4EAA4E;IAC5E,IAAI,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI;IAyBnC;;;;;;;;OAQG;IACH,KAAK,IAAI,IAAI;IAQb,mEAAmE;IACnE,OAAO,CAAC,KAAK;IAQb,OAAO,CAAC,IAAI;IAYZ,OAAO,CAAC,KAAK;IAoBb,6CAA6C;IAC7C,OAAO,CAAC,MAAM;IAQd,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,MAAM;IAOd,0EAA0E;IAC1E,OAAO,CAAC,MAAM;CAaf;AAED,gFAAgF;AAChF,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAMpD;AAED,wDAAwD;AACxD,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,GAAG,SAAS,CAGhE"}

package/dist/adapters/charts/requests.js

@@ -0,0 +1,277 @@
+import { minutesOf, nominalMinutes, parseTimeframe } from '../../core/engine/index.js';
+import { hostBar } from './bars.js';
+/** The store key. Namespaced, because the store belongs to the host as well. */
+const STATION = 'openscript:requests';
+const MINUTE = 60;
+export class Station {
+    entries = new Map();
+    /** What the last calculation asked about, keyed the same way. */
+    wanted = new Map();
+    transport;
+    closed = false;
+    unsubscribe;
+    /**
+     * The provider the engine is loaded with, bound to the bars on screen.
+     *
+     * Asking for one is the start of a round: the engine is about to ask about
+     * every read this program makes, so what was wanted before this moment is
+     * what the previous program wanted. A setting that names a different
+     * instrument would otherwise leave the old one being fetched for as long as
+     * the study lives, and reported on.
+     */
+    provider(bars) {
+        this.wanted.clear();
+        return (query) => {
+            // A read of the chart's own instrument at a coarser interval is folded
+            // from the bars the engine already holds, which is the read
+            // `host-interface.md` 5.1 says it can satisfy without a host.
+            if (query.read === 'timeframe')
+                return undefined;
+            const need = needFor(query, bars);
+            if (need === undefined)
+                return undefined;
+            const key = keyOf(need);
+            this.wanted.set(key, widest(this.wanted.get(key), need));
+            return answerOf(this.entries.get(key));
+        };
+    }
+    /**
+     * The range each read needs, against the bars as they now stand.
+     *
+     * A calculation that reused the held engine never asked the provider
+     * anything, so nothing would notice that the newest chart bar has moved into
+     * the next requested bucket. This is what notices: it widens what is wanted,
+     * and the fetch that follows asks for the recompute that reads it. An answer
+     * is never spliced into a run that is already past the bars it would have
+     * changed, which is `host-interface.md` 5.3.
+     */
+    extend(bars) {
+        const last = bars[bars.length - 1];
+        if (last === undefined)
+            return;
+        for (const [key, need] of this.wanted) {
+            const timeframe = parseTimeframe(need.interval);
+            if (timeframe === undefined)
+                continue;
+            const span = (minutesOf(timeframe) ?? nominalMinutes(timeframe)) * MINUTE;
+            const to = Math.ceil((last.time + 1) / span) * span;
+            if (to > need.to)
+                this.wanted.set(key, { ...need, to });
+        }
+    }
+    /**
+     * After a calculation: start what is missing and say where the study stands.
+     *
+     * It is the end of the calculation rather than the middle of it because a
+     * fetch that resolves asks for a recompute, and asking for one from inside the
+     * calculation it would replace is a loop waiting to be written.
+     */
+    settle() {
+        this.pump();
+        const transport = this.transport;
+        if (transport === undefined)
+            return;
+        transport.status(this.status());
+        transport.retry(this.failed() ? () => this.again() : null);
+    }
+    /** The lifecycle, with the transport the first calculation did not have. */
+    open(ctx) {
+        const ask = ctx.requestBars;
+        if (ask === undefined)
+            return;
+        this.closed = false;
+        this.transport = {
+            request: (need) => ask({
+                symbol: need.symbol,
+                ...(need.exchange === undefined ? {} : { exchange: need.exchange }),
+                interval: need.interval,
+                from: need.from,
+                to: need.to,
+            }),
+            recompute: () => ctx.requestRecompute(),
+            status: (status) => ctx.setDataStatus?.(status),
+            retry: (retry) => ctx.setDataRetry?.(retry),
+        };
+        // An identity change makes every key a different one, so the entries under
+        // the old identity would sit there for as long as the instance does.
+        this.unsubscribe = ctx.subscribeDataChanges?.((change) => {
+            if (change === 'context')
+                this.entries.clear();
+        });
+        this.settle();
+    }
+    /**
+     * The lifecycle is over: nothing in flight may write anything again.
+     *
+     * What was fetched is kept. A chart runs the lifecycle again after a settings
+     * change, and throwing the bars away there would put a network round trip
+     * behind moving a slider. A fetch that was in flight is marked as not in
+     * flight, so a station that is opened again starts it rather than waiting for
+     * an answer whose callback has been told to do nothing.
+     */
+    close() {
+        this.closed = true;
+        this.transport = undefined;
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+        for (const entry of this.entries.values())
+            entry.fetching = false;
+    }
+    /** Every read the host refused, tried again from the beginning. */
+    again() {
+        for (const [key, entry] of this.entries) {
+            if (entry.reason !== undefined || entry.empty)
+                this.entries.delete(key);
+        }
+        this.pump();
+        this.transport?.recompute();
+    }
+    pump() {
+        const transport = this.transport;
+        if (transport === undefined || this.closed)
+            return;
+        for (const [key, need] of this.wanted) {
+            const entry = this.entries.get(key);
+            if (entry !== undefined && entry.fetching)
+                continue;
+            if (entry !== undefined && entry.reason !== undefined)
+                continue;
+            if (entry !== undefined && need.from >= entry.from && need.to <= entry.to)
+                continue;
+            this.fetch(key, need, entry, transport);
+        }
+    }
+    fetch(key, need, held, transport) {
+        const entry = {
+            from: need.from,
+            to: need.to,
+            fetching: true,
+            bars: held?.bars,
+            reason: undefined,
+            empty: false,
+        };
+        this.entries.set(key, entry);
+        transport.request(need).then((bars) => {
+            this.landed(key, entry, bars);
+        }, (error) => {
+            this.refused(key, entry, error);
+        });
+    }
+    /** An answer, once the transport has one. */
+    landed(key, entry, bars) {
+        if (this.closed || this.entries.get(key) !== entry)
+            return;
+        entry.fetching = false;
+        entry.empty = bars.length === 0;
+        if (bars.length > 0)
+            entry.bars = bars.map(hostBar);
+        this.transport?.recompute();
+    }
+    refused(key, entry, error) {
+        if (this.closed || this.entries.get(key) !== entry)
+            return;
+        entry.fetching = false;
+        entry.reason = reasonOf(error);
+        this.transport?.recompute();
+    }
+    failed() {
+        for (const entry of this.entries.values()) {
+            if (entry.reason !== undefined || entry.empty)
+                return true;
+        }
+        return false;
+    }
+    /** Where the study's own data stands, in the four words the chart has. */
+    status() {
+        let waiting = false;
+        let empty = false;
+        for (const key of this.wanted.keys()) {
+            const entry = this.entries.get(key);
+            if (entry === undefined || entry.fetching)
+                waiting = true;
+            if (entry?.reason !== undefined)
+                return { state: 'error', error: new Error(entry.reason) };
+            if (entry?.empty === true)
+                empty = true;
+        }
+        if (waiting)
+            return { state: 'loading' };
+        if (empty)
+            return { state: 'empty' };
+        return { state: 'ready' };
+    }
+}
+/** The station this instance holds, created by whichever half arrives first. */
+export function stationIn(store) {
+    const held = store[STATION];
+    if (held instanceof Station)
+        return held;
+    const made = new Station();
+    store[STATION] = made;
+    return made;
+}
+/** The station this instance holds, when it has one. */
+export function stationOf(store) {
+    const held = store[STATION];
+    return held instanceof Station ? held : undefined;
+}
+function keyOf(need) {
+    return `${need.symbol}|${need.exchange ?? ''}|${need.interval}`;
+}
+/** Two needs for one series: the wider range, so one fetch serves both. */
+function widest(held, need) {
+    if (held === undefined)
+        return need;
+    return {
+        ...need,
+        from: Math.min(held.from, need.from),
+        to: Math.max(held.to, need.to),
+    };
+}
+function answerOf(entry) {
+    if (entry === undefined)
+        return { pending: true };
+    if (entry.reason !== undefined) {
+        return { refused: { code: 'OS6009', reason: entry.reason } };
+    }
+    if (entry.bars !== undefined)
+        return { bars: entry.bars };
+    if (entry.empty)
+        return { refused: { code: 'OS6008' } };
+    return { pending: true };
+}
+/**
+ * The range one read is fetched over, quantised to requested bar boundaries.
+ *
+ * The nominal length of a requested bar is what the arithmetic uses, a month
+ * included. It decides how far back and how far forward to ask, not where a
+ * bucket begins, which is the calendar's and the engine's; asking for a few
+ * hours too many is a floor being generous and asking for exactly the right
+ * calendar month would need the instrument's zone to be stated here as well.
+ */
+function needFor(query, bars) {
+    const symbol = query.instrument;
+    const first = bars[0];
+    const last = bars[bars.length - 1];
+    if (symbol === null || first === undefined || last === undefined)
+        return undefined;
+    const timeframe = parseTimeframe(query.timeframe);
+    if (timeframe === undefined)
+        return undefined;
+    const span = (minutesOf(timeframe) ?? nominalMinutes(timeframe)) * MINUTE;
+    const warmup = query.warmup ?? 0;
+    return {
+        symbol,
+        exchange: query.exchange ?? undefined,
+        interval: query.timeframe,
+        from: Math.floor((first.time - warmup * span) / span) * span,
+        to: Math.ceil((last.time + 1) / span) * span,
+    };
+}
+/** The host's own words, carried and never paraphrased. */
+function reasonOf(error) {
+    if (error instanceof Error && error.message !== '')
+        return error.message;
+    return typeof error === 'string' && error !== '' ? error : 'the host gave no reason';
+}
+//# sourceMappingURL=requests.js.map

package/dist/adapters/charts/requests.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requests.js","sourceRoot":"","sources":["../../../src/adapters/charts/requests.ts"],"names":[],"mappings":"AAqDA,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACvF,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,gFAAgF;AAChF,MAAM,OAAO,GAAG,qBAAqB,CAAC;AAEtC,MAAM,MAAM,GAAG,EAAE,CAAC;AAiClB,MAAM,OAAO,OAAO;IACD,OAAO,GAAG,IAAI,GAAG,EAAiB,CAAC;IACpD,iEAAiE;IAChD,MAAM,GAAG,IAAI,GAAG,EAAgB,CAAC;IAC1C,SAAS,CAAwB;IACjC,MAAM,GAAG,KAAK,CAAC;IACf,WAAW,CAA2B;IAE9C;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAyB;QAChC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACpB,OAAO,CAAC,KAAmB,EAA6B,EAAE;YACxD,uEAAuE;YACvE,4DAA4D;YAC5D,8DAA8D;YAC9D,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW;gBAAE,OAAO,SAAS,CAAC;YACjD,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAClC,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YACzC,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;YACxB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;YACzD,OAAO,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QACzC,CAAC,CAAC;IACJ,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,IAAyB;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACnC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO;QAC/B,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACtC,MAAM,SAAS,GAAG,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAChD,IAAI,SAAS,KAAK,SAAS;gBAAE,SAAS;YACtC,MAAM,IAAI,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,cAAc,CAAC,SAAS,CAAC,CAAC,GAAG,MAAM,CAAC;YAC1E,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;YACpD,IAAI,EAAE,GAAG,IAAI,CAAC,EAAE;gBAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,MAAM;QACJ,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QACjC,IAAI,SAAS,KAAK,SAAS;YAAE,OAAO;QACpC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QAChC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,GAAS,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACnE,CAAC;IAED,4EAA4E;IAC5E,IAAI,CAAC,GAAuB;QAC1B,MAAM,GAAG,GAAG,GAAG,CAAC,WAAW,CAAC;QAC5B,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO;QAC9B,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,SAAS,GAAG;YACf,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAChB,GAAG,CAAC;gBACF,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACnE,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,EAAE,EAAE,IAAI,CAAC,EAAE;aACZ,CAAC;YACJ,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,gBAAgB,EAAE;YACvC,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC,MAAM,CAAC;YAC/C,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC,KAAK,CAAC;SAC5C,CAAC;QACF,2EAA2E;QAC3E,qEAAqE;QACrE,IAAI,CAAC,WAAW,GAAG,GAAG,CAAC,oBAAoB,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE;YACvD,IAAI,MAAM,KAAK,SAAS;gBAAE,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACjD,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,EAAE,CAAC;IAChB,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;QACrB,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;QAC7B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE;YAAE,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC;IACpE,CAAC;IAED,mEAAmE;IAC3D,KAAK;QACX,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACxC,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK;gBAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1E,CAAC;QACD,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC;IAC9B,CAAC;IAEO,IAAI;QACV,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QACjC,IAAI,SAAS,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACnD,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACtC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACpC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ;gBAAE,SAAS;YACpD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;gBAAE,SAAS;YAChE,IAAI,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE,IAAI,KAAK,CAAC,EAAE;gBAAE,SAAS;YACpF,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,GAAW,EAAE,IAAU,EAAE,IAAuB,EAAE,SAAoB;QAClF,MAAM,KAAK,GAAU;YACnB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,QAAQ,EAAE,IAAI;YACd,IAAI,EAAE,IAAI,EAAE,IAAI;YAChB,MAAM,EAAE,SAAS;YACjB,KAAK,EAAE,KAAK;SACb,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC7B,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAC1B,CAAC,IAAI,EAAE,EAAE;YACP,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;QAChC,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;YACjB,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAClC,CAAC,CACF,CAAC;IACJ,CAAC;IAED,6CAA6C;IACrC,MAAM,CAAC,GAAW,EAAE,KAAY,EAAE,IAAyB;QACjE,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK;YAAE,OAAO;QAC3D,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC;QACvB,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC;QAChC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;YAAE,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACpD,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC;IAC9B,CAAC;IAEO,OAAO,CAAC,GAAW,EAAE,KAAY,EAAE,KAAc;QACvD,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK;YAAE,OAAO;QAC3D,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC;QACvB,KAAK,CAAC,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC/B,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC;IAC9B,CAAC;IAEO,MAAM;QACZ,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YAC1C,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK;gBAAE,OAAO,IAAI,CAAC;QAC7D,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,0EAA0E;IAClE,MAAM;QACZ,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,KAAK,GAAG,KAAK,CAAC;QAClB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;YACrC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACpC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ;gBAAE,OAAO,GAAG,IAAI,CAAC;YAC1D,IAAI,KAAK,EAAE,MAAM,KAAK,SAAS;gBAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3F,IAAI,KAAK,EAAE,KAAK,KAAK,IAAI;gBAAE,KAAK,GAAG,IAAI,CAAC;QAC1C,CAAC;QACD,IAAI,OAAO;YAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QACzC,IAAI,KAAK;YAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QACrC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IAC5B,CAAC;CACF;AAED,gFAAgF;AAChF,MAAM,UAAU,SAAS,CAAC,KAAiB;IACzC,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5B,IAAI,IAAI,YAAY,OAAO;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,IAAI,GAAG,IAAI,OAAO,EAAE,CAAC;IAC3B,KAAK,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IACtB,OAAO,IAAI,CAAC;AACd,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,SAAS,CAAC,KAAiB;IACzC,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5B,OAAO,IAAI,YAAY,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AACpD,CAAC;AAED,SAAS,KAAK,CAAC,IAAU;IACvB,OAAO,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ,IAAI,EAAE,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;AAClE,CAAC;AAED,2EAA2E;AAC3E,SAAS,MAAM,CAAC,IAAsB,EAAE,IAAU;IAChD,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACpC,OAAO;QACL,GAAG,IAAI;QACP,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC;QACpC,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC;KAC/B,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,KAAwB;IACxC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAClD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;IAC/D,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;IAC1D,IAAI,KAAK,CAAC,KAAK;QAAE,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC;IACxD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,OAAO,CAAC,KAAmB,EAAE,IAAyB;IAC7D,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,CAAC;IAChC,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACtB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACnC,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACnF,MAAM,SAAS,GAAG,cAAc,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAClD,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC9C,MAAM,IAAI,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,cAAc,CAAC,SAAS,CAAC,CAAC,GAAG,MAAM,CAAC;IAC1E,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;IACjC,OAAO;QACL,MAAM;QACN,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,SAAS;QACrC,QAAQ,EAAE,KAAK,CAAC,SAAS;QACzB,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI;QAC5D,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI;KAC7C,CAAC;AACJ,CAAC;AAED,2DAA2D;AAC3D,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,OAAO,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC;IACzE,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,yBAAyB,CAAC;AACvF,CAAC"}

package/dist/adapters/charts/run.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Driving the engine from a chart's recompute.
+ *
+ * The descriptor's two calculation hooks are the engine's two entry points
+ * almost exactly. A full recompute is a fresh engine over every bar. A tail
+ * change is `update()` on the bar that moved and `append()` for anything after
+ * it, which is what the engine's rollback exists for: re-executing a moving bar
+ * gives the same numbers as executing it once, so a live chart and a backtest of
+ * the same data agree. Nothing here recomputes anything the engine computes.
+ *
+ * **The tail path is refused rather than trusted.** A held engine is only usable
+ * while it was loaded from the same settings and has executed exactly the bars
+ * before the tail, so the settings are compared by their own spelling and the
+ * first and last bar times are compared against what was run. Anything that does
+ * not line up returns nothing and the chart falls back to a full recompute,
+ * because splicing a tail onto a history that has changed underneath it draws a
+ * wrong study that looks entirely plausible.
+ *
+ * **The engine never throws and a chart's calculation has to.** A failure the
+ * engine returns becomes an error carrying that diagnostic whole, which is the
+ * one place in this adapter where the two error models meet.
+ */
+import type { Clock, EffectRoute, EngineLimits, Grid, Instrument, Drawing, Value } from '../../core/engine/index.js';
+import type { CompiledProgram } from '../../core/emit/index.js';
+import type { SourceFile } from '../../core/index.js';
+import type { ChartBar, ChartCalcContext, ChartSettings, ChartStore } from './contract.js';
+/** What a host tells the adapter that neither the chart nor the program says. */
+export interface ChartAdapterOptions {
+    /**
+     * The registry id, and the name a saved layout stores.
+     *
+     * It defaults to the program's own source hash, so the same script restores
+     * to the same study and an edited script does not silently inherit the
+     * settings of the one it replaced.
+     */
+    readonly id?: string;
+    /** The category a picker groups the study under, when `meta.group` is empty. */
+    readonly category?: string;
+    /**
+     * What the host has stored for this study's inputs, for the declared shape.
+     *
+     * A declaration option may be written as an `input()`, and `docs/inputs.md`
+     * teaches that as how a reader changes something the declaration decides:
+     * `study("S", precision = input(2, "Places"))` puts the pane's precision on
+     * the settings dialog. The engine resolves such a field against the settings
+     * it was loaded with. The descriptor's declared shape is fixed before bar 0
+     * and is a value rather than a call, so the only settings it can be resolved
+     * against are the ones a host states here; built without them, every one of
+     * those fields reads the declared default and a stored value reaches none of
+     * them.
+     *
+     * A host that keeps one descriptor per study instance passes that instance's
+     * stored settings and builds again when a user changes one. A host that
+     * registers one descriptor for a script and runs several instances against it
+     * gets the declared shape of whatever it built with, and the parts that are
+     * asked for again per call follow each instance: which those are is recorded
+     * in `spec/chart-narrowings.json`, and `scripts/check-chart-surface.mjs`
+     * measures both halves rather than leaving the sentence to be believed.
+     *
+     * These are the chart's own settings object, in the chart's own spelling, and
+     * the same conversions apply as on the calculation path: a colour arrives as
+     * a CSS string and a choice as the text of an option.
+     */
+    readonly settings?: ChartSettings;
+    /**
+     * The plate colour a marker takes when the script named none.
+     *
+     * `signal`'s colour argument defaults to absence, which `stdlib.md` 14.3
+     * reads as the host's own default for a marker, and a chart needs a colour
+     * for every marker it draws. A host with a marker colour in its theme states
+     * it here; without one every unnamed marker is drawn in a neutral grey.
+     */
+    readonly markerColor?: string;
+    /** The source, so a diagnostic can carry an offset as well as a line. */
+    readonly source?: SourceFile;
+    /**
+     * Instrument facts a chart does not hold: the exchange, the lot size, and
+     * the trading session.
+     *
+     * The session is where every per-bar session fact comes from
+     * (`host-interface.md` 4.3), so a host that knows its calendar states the
+     * hours here and the engine derives the rest. A chart holds an interval and a
+     * timezone and no exchange calendar, so a host that states none gets a study
+     * whose session never begins, which is the honest answer rather than a
+     * guessed one.
+     */
+    readonly instrument?: Instrument;
+    /**
+     * Where an applied order goes, and where its frames come back from.
+     *
+     * Without one the engine declares no `orders` capability and refuses a
+     * strategy at load with OS6006, naming it. That is deliberate: a chart that
+     * quietly swallowed a strategy's orders while drawing its plots would be a
+     * strategy the user believes is running.
+     *
+     * There is no position option beside it. A strategy's position is folded from
+     * the orders it sent and the frames this route's owner reports back
+     * (`stdlib.md` 17.1), never handed over by the chart.
+     */
+    readonly orders?: EffectRoute;
+    readonly limits?: Partial<EngineLimits>;
+    readonly clock?: Clock;
+    /**
+     * A wall clock string in the chart's zone, as UTC seconds.
+     *
+     * A `"time"` input is stored as a wall clock string so that a saved layout
+     * restores to the same reading in another zone, and turning one into an
+     * instant needs the zone's calendar, which the engine does not have. A host
+     * passes the chart's own conversion; without one the string is read as UTC.
+     */
+    readonly resolveTime?: (text: string, timezone: string) => number;
+}
+/** Every channel's whole column, for the bars that were run. */
+export type Columns = readonly (readonly Value[])[];
+/**
+ * What one run produced beyond the columns.
+ *
+ * The grids and the drawing objects are here because neither is a column of
+ * numbers: a grid is the buffer the last executed bar left behind, and an object
+ * is a shape the script created and has been mutating since. They are read off
+ * the engine while it is in hand rather than left for a caller to go back for,
+ * because after a tail run the engine is the held one and nobody else has it.
+ */
+export interface RunOutput {
+    readonly columns: Columns;
+    readonly tables: readonly Grid[];
+    readonly drawings: readonly Drawing[];
+}
+export declare function fullRun(program: CompiledProgram, bars: readonly ChartBar[], settings: ChartSettings, store: ChartStore, ctx: ChartCalcContext | undefined, options: ChartAdapterOptions): RunOutput;
+/**
+ * The bars from `from` onwards, or nothing when the held engine cannot serve
+ * them.
+ *
+ * `from` is the previously last bar, which may have been replaced rather than
+ * followed, so it is re-executed rather than appended: that is step 1 of the bar
+ * cycle and the reason a moving bar draws the same study however many ticks it
+ * took.
+ */
+export declare function tailRun(program: CompiledProgram, bars: readonly ChartBar[], from: number, settings: ChartSettings, store: ChartStore, ctx: ChartCalcContext | undefined, _options: ChartAdapterOptions): RunOutput | null;
+/**
+ * A held engine is dropped when the descriptor's instance goes away.
+ *
+ * The station goes with it, because a fetch still in flight would otherwise ask
+ * a chart that has removed this study to recompute it.
+ */
+export declare function release(store: ChartStore): void;
+//# sourceMappingURL=run.d.ts.map

package/dist/adapters/charts/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/adapters/charts/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EACV,KAAK,EACL,WAAW,EAGX,YAAY,EACZ,IAAI,EAEJ,UAAU,EACV,OAAO,EAEP,KAAK,EACN,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAK3F,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;IAClC;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;CACnE;AAcD,gEAAgE;AAChE,MAAM,MAAM,OAAO,GAAG,SAAS,CAAC,SAAS,KAAK,EAAE,CAAC,EAAE,CAAC;AAEpD;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;CACvC;AAED,wBAAgB,OAAO,CACrB,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,SAAS,QAAQ,EAAE,EACzB,QAAQ,EAAE,aAAa,EACvB,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,gBAAgB,GAAG,SAAS,EACjC,OAAO,EAAE,mBAAmB,GAC3B,SAAS,CAmBX;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CACrB,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,SAAS,QAAQ,EAAE,EACzB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,aAAa,EACvB,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,gBAAgB,GAAG,SAAS,EAGjC,QAAQ,EAAE,mBAAmB,GAC5B,SAAS,GAAG,IAAI,CA2BlB;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAG/C"}