openalgo-script 0.1.0-alpha.1 → 0.2.0

package/dist/core/engine/request-body.d.ts

@@ -0,0 +1,138 @@
+/**
+ * A request expression, executed over the requested bars,
+ * `compiled-program.md` 2.16.1.
+ *
+ * **The body is a program the machine already knows how to run.** It holds the
+ * tables a program holds for the machine of section 3 and none of the tables
+ * that describe a chart, so the whole of this file is: build a program-shaped
+ * view whose code, frame, registers, cells, states, functions and loops are the
+ * body's own, keep the constant pool and the library manifest the program's,
+ * and drive the same interpreter over it once per requested bar. Nothing new is
+ * asked of the instruction loop, which is why the body ends in `RET` rather
+ * than in an opcode of its own.
+ *
+ * **Every table is counted from zero and none of them is the program's.** The
+ * registers are the requested instrument's bars and the cells and state regions
+ * step once per requested bar, so an engine that reached into the program's
+ * tables would put this chart's history behind another chart's name. The two
+ * that are shared, `consts` and `lib.functions`, hold nothing that depends on a
+ * bar.
+ *
+ * **A requested bar moves exactly as the chart's newest bar does.** `settle` is
+ * a bar that has closed and `peek` is the one still forming, and `peek` rolls
+ * the state back before it runs so that peeking the same bucket on ten chart
+ * bars gives the same answer as peeking it once. That is the mechanism of
+ * section 6 applied one level down, and it is what makes a `"developing"` read
+ * mean the bucket so far rather than the bucket in full.
+ */
+import type { Span } from '../span/index.js';
+import type { HostBar } from './bars.js';
+import type { Clock, EngineLimits } from './budget.js';
+import { Registers } from './registers.js';
+import type { HostFacts, ManifestEntry, PositionFacts } from './library/index.js';
+import type { CompiledProgram, Request } from './types.js';
+import { Heap } from './values/index.js';
+import type { Value } from './values/index.js';
+/** One setting the body reads, resolved once at load like every other input. */
+export interface BodyInput {
+    readonly series: number;
+    readonly value: Value;
+}
+/**
+ * The reads written inside this one, as the body drives them.
+ *
+ * Declared here rather than imported, so the dependency points one way: the
+ * fold knows about a body and a body knows only the shape of what it has to
+ * step. A nested read folds the bars this body is running on, which are handed
+ * over one requested bar at a time, so a nested `"lookahead"` read sees no
+ * further than the requested bar being executed. That is the same thing the
+ * mode does on a live chart's newest bucket, one level down.
+ */
+export interface NestedRequests {
+    readonly empty: boolean;
+    fill(registers: Registers, bars: readonly HostBar[], index: number, fresh: boolean): void;
+}
+export interface BodyParts {
+    /** The program-shaped view of the body, built by `bodyProgram`. */
+    readonly program: CompiledProgram;
+    readonly limits: EngineLimits;
+    readonly clock: Clock | undefined;
+    readonly host: HostFacts;
+    readonly position: PositionFacts;
+    readonly library: readonly ManifestEntry[];
+    readonly inputs: readonly BodyInput[];
+    readonly nested: NestedRequests | undefined;
+    spanAt(line: number, column: number): Span;
+}
+/**
+ * The body's tables wearing a program's shape.
+ *
+ * A copy of the parent with nine fields replaced, rather than a second
+ * declaration, so that the one thing the two share by design, the constant pool
+ * and the manifest, is shared by construction and cannot drift.
+ */
+export declare function bodyProgram(parent: CompiledProgram, request: Request): CompiledProgram;
+export declare class RequestBody {
+    private readonly parts;
+    private readonly registers;
+    private readonly memory;
+    private readonly heap;
+    private readonly budget;
+    private readonly machine;
+    /** Requested bars that have closed, which is the index the next one takes. */
+    private settled;
+    /** Executions of the requested bar currently forming, for `bar.updates`. */
+    private touches;
+    /** The previous requested bar's close, which `trueRange` inside a body needs. */
+    private lastClose;
+    /** The requested bars themselves, kept only when a read inside folds them. */
+    private readonly history;
+    /**
+     * The value the last closed requested bar handed back.
+     *
+     * Held so that the sweep does not reclaim it. A confirmed read takes the last
+     * closed bucket's value on every chart bar of the next bucket, so the value
+     * outlives the execution that produced it, and if it is an object the object
+     * has to outlive it too.
+     */
+    private handed;
+    constructor(parts: BodyParts);
+    /** How many requested bars have closed, which a warmup is counted against. */
+    get closed(): number;
+    /** The body's own heap, which a read written inside it lands its value in. */
+    get objects(): Heap;
+    /**
+     * The requested bar still forming.
+     *
+     * Rolls back to the last closed bar first, so a bucket peeked on every chart
+     * bar inside it costs one execution each and leaves no trace of the previous
+     * one. Nothing is committed: the bucket is still moving.
+     */
+    peek(bar: HostBar): Value;
+    /**
+     * The requested bar has closed.
+     *
+     * The last execution of that bar is the one that counts, and the state it
+     * leaves becomes the checkpoint the next bar starts from. `settle` is
+     * idempotent only in the sense every checkpoint is: it is called once per
+     * requested bar, by the one place that knows a bucket has ended.
+     */
+    settle(bar: HostBar): Value;
+    private execute;
+    /**
+     * A value the body produced, as a value of the machine that asked for it.
+     *
+     * A number, a string, a colour or absence is the same value in both, and
+     * nothing is copied. An object is not: a reference is an index into one heap,
+     * and the body's heap is its own, so handing the index over would name
+     * whatever the other heap happens to hold at that index. So the object is
+     * copied, and copied again on every bar that reads it, because the copy lives
+     * in a heap whose rollback undoes the bar it was made on.
+     *
+     * Only an array can arrive here. A read that declared a grid or drew an object
+     * is refused at the call (OS3006), so those two kinds cannot exist in a body.
+     */
+    carry(value: Value, into: Heap): Value;
+    private viewOf;
+}
+//# sourceMappingURL=request-body.d.ts.map

package/dist/core/engine/request-body.d.ts.map

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

package/dist/core/engine/request-body.js

@@ -0,0 +1,227 @@
+import { barField, factsFor } from './bars.js';
+import { Budget, stepBound } from './budget.js';
+import { Channels } from './channels.js';
+import { guardFor } from './guard.js';
+import { Machine } from './machine.js';
+import { NO_SESSION } from './session/index.js';
+import { Memory } from './memory.js';
+import { Registers } from './registers.js';
+import { ABSENT, Heap, isRef, reference } from './values/index.js';
+/**
+ * The body's tables wearing a program's shape.
+ *
+ * A copy of the parent with nine fields replaced, rather than a second
+ * declaration, so that the one thing the two share by design, the constant pool
+ * and the manifest, is shared by construction and cannot drift.
+ */
+export function bodyProgram(parent, request) {
+    const body = request.body;
+    return {
+        ...parent,
+        frame: body.frame,
+        series: body.series,
+        cells: body.cells,
+        states: body.states,
+        functions: body.functions,
+        callSites: body.callSites,
+        loops: body.loops,
+        code: body.code,
+        requests: body.requests,
+        debug: { ...parent.debug, pos: body.pos, fnPos: body.fnPos },
+    };
+}
+export class RequestBody {
+    parts;
+    registers;
+    memory;
+    heap = new Heap();
+    budget;
+    machine;
+    /** Requested bars that have closed, which is the index the next one takes. */
+    settled = 0;
+    /** Executions of the requested bar currently forming, for `bar.updates`. */
+    touches = 0;
+    /** The previous requested bar's close, which `trueRange` inside a body needs. */
+    lastClose = null;
+    /** The requested bars themselves, kept only when a read inside folds them. */
+    history = [];
+    /**
+     * The value the last closed requested bar handed back.
+     *
+     * Held so that the sweep does not reclaim it. A confirmed read takes the last
+     * closed bucket's value on every chart bar of the next bucket, so the value
+     * outlives the execution that produced it, and if it is an object the object
+     * has to outlive it too.
+     */
+    handed = ABSENT;
+    constructor(parts) {
+        this.parts = parts;
+        const { program } = parts;
+        this.registers = new Registers(program.series.length);
+        this.memory = new Memory(program.cells, program.states);
+        this.budget = new Budget(parts.limits, parts.limits.steps ?? stepBound(program), program.limits.loops, parts.clock);
+        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,
+            // A read carries no channel, no plot and no declaration: those are the
+            // calls the language refuses inside a request expression, so nothing in
+            // a body can write a column and verification refuses an `EMIT` against
+            // an empty table.
+            channels: new Channels([]),
+            heap: this.heap,
+            budget: this.budget,
+            guard: guardFor(this.budget),
+            host: parts.host,
+            position: parts.position,
+            library: parts.library,
+            fnPositions,
+            spanAt: parts.spanAt,
+        }, this.viewOf({ open: null, high: null, low: null, close: null, time: null }, 0, false));
+    }
+    /** How many requested bars have closed, which a warmup is counted against. */
+    get closed() {
+        return this.settled;
+    }
+    /** The body's own heap, which a read written inside it lands its value in. */
+    get objects() {
+        return this.heap;
+    }
+    /**
+     * The requested bar still forming.
+     *
+     * Rolls back to the last closed bar first, so a bucket peeked on every chart
+     * bar inside it costs one execution each and leaves no trace of the previous
+     * one. Nothing is committed: the bucket is still moving.
+     */
+    peek(bar) {
+        const value = this.execute(bar, false);
+        this.touches += 1;
+        return value;
+    }
+    /**
+     * The requested bar has closed.
+     *
+     * The last execution of that bar is the one that counts, and the state it
+     * leaves becomes the checkpoint the next bar starts from. `settle` is
+     * idempotent only in the sense every checkpoint is: it is called once per
+     * requested bar, by the one place that knows a bucket has ended.
+     */
+    settle(bar) {
+        const value = this.execute(bar, true);
+        this.handed = value;
+        this.memory.commit();
+        this.heap.commit();
+        this.heap.sweep((visit) => {
+            this.memory.walk(visit);
+            this.registers.walk(visit);
+            visit(this.handed);
+        });
+        this.registers.trim(this.settled, this.parts.program.limits.history);
+        this.lastClose = bar.close ?? null;
+        this.settled += 1;
+        this.touches = 0;
+        return value;
+    }
+    execute(bar, closed) {
+        const index = this.settled;
+        // Steps 1 and 2 of the bar cycle, one level down: the checkpoint from the
+        // end of the previous requested bar, and the history entry this bar may
+        // already have written.
+        this.memory.rollback();
+        this.heap.rollback();
+        this.registers.truncate(index);
+        this.registers.clearCurrent();
+        this.budget.begin(index);
+        const view = this.viewOf(bar, index, closed);
+        this.machine.begin(view, index);
+        const facts = factsFor(index, 
+        // A bar that has closed is not the last one: something later is what
+        // closed it. The one still forming is.
+        index + (closed ? 2 : 1), { isConfirmed: closed }, this.touches === 0, this.touches + 1, NO_SESSION);
+        for (const register of this.parts.program.series) {
+            if (register.kind !== 'bar' || register.field === null)
+                continue;
+            this.registers.set(register.id, barField(register.field, bar, facts));
+        }
+        // A body is one expression with no statement to write a slot from, so a
+        // setting it reads arrives as a register rather than as a slot (2.16.1).
+        for (const input of this.parts.inputs)
+            this.registers.set(input.series, input.value);
+        const nested = this.parts.nested;
+        if (nested !== undefined && !nested.empty) {
+            this.history[index] = bar;
+            nested.fill(this.registers, this.history, index, this.touches === 0);
+        }
+        this.machine.run();
+        this.registers.close(index);
+        return this.machine.result();
+    }
+    /**
+     * A value the body produced, as a value of the machine that asked for it.
+     *
+     * A number, a string, a colour or absence is the same value in both, and
+     * nothing is copied. An object is not: a reference is an index into one heap,
+     * and the body's heap is its own, so handing the index over would name
+     * whatever the other heap happens to hold at that index. So the object is
+     * copied, and copied again on every bar that reads it, because the copy lives
+     * in a heap whose rollback undoes the bar it was made on.
+     *
+     * Only an array can arrive here. A read that declared a grid or drew an object
+     * is refused at the call (OS3006), so those two kinds cannot exist in a body.
+     */
+    carry(value, into) {
+        return copyInto(value, this.heap, into, new Map());
+    }
+    viewOf(bar, index, closed) {
+        return {
+            index,
+            open: bar.open ?? null,
+            high: bar.high ?? null,
+            low: bar.low ?? null,
+            close: bar.close ?? null,
+            volume: bar.volume ?? null,
+            time: bar.time ?? null,
+            previousClose: this.lastClose,
+            isConfirmed: closed,
+            isRealtime: false,
+            isNew: this.touches === 0,
+            isLast: !closed,
+            updates: this.touches + 1,
+            // The instrument record describes the chart's instrument, not the one a
+            // read names, and a requested bar is not on the chart's own grid either.
+            // So a body has no session, and it is told absence rather than false: a
+            // false would say this bar closes no session, which is a claim about an
+            // instrument whose hours the engine was never given.
+            isSessionFirst: null,
+            isSessionLast: null,
+        };
+    }
+}
+/**
+ * One value copied from one heap into another, sharing what it shared.
+ *
+ * The map is what keeps two references to one array two references to one copy,
+ * and it is what stops a value that refers to itself from recursing forever.
+ */
+function copyInto(value, from, into, copied) {
+    if (!isRef(value))
+        return value;
+    const already = copied.get(value.id);
+    if (already !== undefined)
+        return reference(already);
+    const object = from.get(value.id);
+    if (object === undefined || object.kind !== 'array')
+        return ABSENT;
+    const items = [];
+    const id = into.allocate({ kind: 'array', items });
+    copied.set(value.id, id);
+    for (const item of object.items)
+        items.push(copyInto(item, from, into, copied));
+    into.countElements(items.length);
+    return reference(id);
+}
+//# sourceMappingURL=request-body.js.map

package/dist/core/engine/request-body.js.map

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

package/dist/core/engine/request-plan.d.ts

@@ -0,0 +1,79 @@
+import type { Diagnostic } from '../diagnostics/index.js';
+import type { EngineHost, RequestAnswer, RequestQuery, RequestRefusal } from './host.js';
+import type { ResolvedInput } from './inputs.js';
+import type { Request, RequestField } from './types.js';
+import type { Timeframe } from './timeframe.js';
+/** What a read holds once its identity, its timeframe and its source are fixed. */
+export interface RequestPlan {
+    readonly request: Request;
+    readonly query: RequestQuery;
+    readonly timeframe: Timeframe;
+    /** The zone a calendar bucket is dated in, or nothing when none was stated. */
+    readonly zone: string | null;
+}
+export type PlanResult = {
+    readonly ok: true;
+    readonly plans: readonly RequestPlan[];
+} | {
+    readonly ok: false;
+    readonly diagnostic: Diagnostic;
+};
+/**
+ * One of the three identity fields, resolved.
+ *
+ * Three forms and no fourth: the string the script wrote, the value of the
+ * setting it named, and one of the three chart facts that identify a chart
+ * rather than describe it.
+ */
+export declare function identityOf(field: RequestField, inputs: readonly ResolvedInput[], host: EngineHost): string | null;
+/**
+ * Every read the program makes, with its identity settled.
+ *
+ * Walks the nested reads as well, because a read written inside another is part
+ * of the program and a host handed a list with one missing would fetch less
+ * than the file asks for.
+ */
+export declare function planRequests(requests: readonly Request[], inputs: readonly ResolvedInput[], host: EngineHost): PlanResult;
+/**
+ * What the host says about one read.
+ *
+ * A host with no provider is not asked. A read of the chart's own instrument is
+ * then folded from the bars the engine already holds, and a read of another
+ * instrument cannot be: the engine holds none of that instrument's bars, so
+ * nothing to serve is the same answer as an instrument the host does not know.
+ */
+export declare function askHost(plan: RequestPlan, host: EngineHost): RequestAnswer | undefined;
+/**
+ * Whether this read can date a bucket at all.
+ *
+ * A day, week or month request is folded by the calendar, and a calendar
+ * boundary is a civil date read in a zone (`timeframe.ts`). A host that stated
+ * no timezone leaves the fold with no key for any bar, so the read is absent on
+ * every bar of the run and will be on every future one: nothing that arrives
+ * later supplies a fact the instrument record does not hold.
+ *
+ * That is a dead read, and a dead read a study cannot explain is the worst of
+ * the three: the trader has already looked at the blank pane. So it is answered
+ * here rather than left as absence, and `req.isReady` and `req.error` say it.
+ */
+export declare function undatable(plan: RequestPlan): boolean;
+/**
+ * What `req.error(read)` says about a read with no zone to date its buckets.
+ *
+ * OS6012's own message, because the zone is an instrument fact the host did not
+ * supply and that is exactly what this read needs and cannot default. Nothing
+ * is raised: a fact the host did not state leaves the read absent, and this is
+ * the sentence that explains the absence rather than a second answer to the
+ * question `host-interface.md` 4.5 leaves open.
+ */
+export declare function undatableReason(query: RequestQuery): string;
+/**
+ * The reason a refusal reads as through `req.error(read)`.
+ *
+ * The catalogue's own message, filled with the identity the read asked for and
+ * with the host's own words where it gave them. The host's words are carried
+ * and not paraphrased, because "the account's data subscription does not cover
+ * this instrument" is actionable and "the request failed" is not.
+ */
+export declare function reasonFor(refusal: RequestRefusal, query: RequestQuery): string;
+//# sourceMappingURL=request-plan.d.ts.map

package/dist/core/engine/request-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-plan.d.ts","sourceRoot":"","sources":["../../../src/core/engine/request-plan.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACzF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAExD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAA;CAAE,GAC7D;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;CAAE,CAAC;AAE5D;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,IAAI,EAAE,UAAU,GACf,MAAM,GAAG,IAAI,CAaf;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,IAAI,EAAE,UAAU,GACf,UAAU,CAMZ;AAkGD;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,GAAG,aAAa,GAAG,SAAS,CAKtF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAEpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAE3D;AAOD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,CA4B9E"}