openalgo-script 0.1.0-alpha.1 → 0.2.0

package/dist/core/engine/arithmetic.js

@@ -0,0 +1,141 @@
+import { ABSENT, numberValue, valuesEqual } from './values/index.js';
+/** Whether a corrupt program reached an operator with tags it cannot take. */
+export class OperandMismatch extends Error {
+    opcode;
+    constructor(opcode) {
+        super(opcode);
+        this.name = 'OperandMismatch';
+        this.opcode = opcode;
+    }
+}
+/**
+ * `ADD`: the sum of two numbers, or the concatenation of two strings.
+ *
+ * The only instruction that reads two tags. Any other combination is a program
+ * the checker should have rejected, and an engine treats it as corrupt rather
+ * than inventing a conversion: `language.md` 5.3 has no coercion anywhere, and
+ * an engine that grows one here becomes the only engine that runs that script.
+ */
+export function add(a, b) {
+    if (a === null || b === null)
+        return ABSENT;
+    if (typeof a === 'number' && typeof b === 'number')
+        return numberValue(a + b);
+    if (typeof a === 'string' && typeof b === 'string')
+        return a + b;
+    throw new OperandMismatch('ADD');
+}
+export function subtract(a, b) {
+    return numeric('SUB', a, b, (x, y) => x - y);
+}
+export function multiply(a, b) {
+    return numeric('MUL', a, b, (x, y) => x * y);
+}
+/** `DIV`: absent when the divisor is zero, including `0 / 0`. */
+export function divide(a, b) {
+    if (a === null || b === null)
+        return ABSENT;
+    if (typeof a !== 'number' || typeof b !== 'number')
+        throw new OperandMismatch('DIV');
+    return b === 0 ? ABSENT : numberValue(a / b);
+}
+/** `MOD`: the remainder of truncated division, sign following the left operand. */
+export function remainder(a, b) {
+    if (a === null || b === null)
+        return ABSENT;
+    if (typeof a !== 'number' || typeof b !== 'number')
+        throw new OperandMismatch('MOD');
+    return b === 0 ? ABSENT : numberValue(a % b);
+}
+export function negate(a) {
+    if (a === null)
+        return ABSENT;
+    if (typeof a !== 'number')
+        throw new OperandMismatch('NEG');
+    return numberValue(-a);
+}
+function numeric(opcode, a, b, of) {
+    if (a === null || b === null)
+        return ABSENT;
+    if (typeof a !== 'number' || typeof b !== 'number')
+        throw new OperandMismatch(opcode);
+    return numberValue(of(a, b));
+}
+/**
+ * The four ordering comparisons, which **propagate absence**.
+ *
+ * An absent operand gives absence rather than `false` (`language.md` 6.4).
+ * Together with `EQ` being total, this is the one place in the language where
+ * absence is treated two ways, and it is deliberate: an operator that can
+ * itself be absent gives a script no way to ask whether a value is absent at
+ * all, so equality is the exception and every other comparison is not.
+ */
+export function compare(opcode, a, b) {
+    if (a === null || b === null)
+        return ABSENT;
+    const bothNumbers = typeof a === 'number' && typeof b === 'number';
+    const bothStrings = typeof a === 'string' && typeof b === 'string';
+    if (!bothNumbers && !bothStrings)
+        throw new OperandMismatch(opcode);
+    switch (opcode) {
+        case 'LT':
+            return a < b;
+        case 'LE':
+            return a <= b;
+        case 'GT':
+            return a > b;
+        default:
+            return a >= b;
+    }
+}
+/** `EQ` and `NE` are total: they always produce a boolean. */
+export function equals(a, b) {
+    return valuesEqual(a, b);
+}
+/** `NOT`: true becomes false, false becomes true, absent stays absent. */
+export function not(a) {
+    if (a === null)
+        return ABSENT;
+    if (typeof a !== 'boolean')
+        throw new OperandMismatch('NOT');
+    return !a;
+}
+/**
+ * `AND`, the three-valued conjunction of `language.md` 6.6.
+ *
+ * The table holds only the cases the short circuit leaves to it: `AND_SHORT`
+ * has already decided a `false` left operand. A `false` on the right fixes the
+ * answer whatever an absent left operand would have held, which is what makes
+ * the operator commutative.
+ */
+export function and(a, b) {
+    if (a === false || b === false)
+        return false;
+    if (a === null || b === null)
+        return ABSENT;
+    if (typeof a !== 'boolean' || typeof b !== 'boolean')
+        throw new OperandMismatch('AND');
+    return a && b;
+}
+/** `OR`, the disjunction beside it. A `true` on either side fixes the answer. */
+export function or(a, b) {
+    if (a === true || b === true)
+        return true;
+    if (a === null || b === null)
+        return ABSENT;
+    if (typeof a !== 'boolean' || typeof b !== 'boolean')
+        throw new OperandMismatch('OR');
+    return a || b;
+}
+/**
+ * Whether a branch is taken, which is the fifth rule.
+ *
+ * `JUMP_FALSE` treats absence as false. This is the one place absence is
+ * absorbed rather than propagated, and it is unavoidable: execution has to go
+ * somewhere. It serves `if`, `else if`, `while`, the ternary and a `switch`
+ * condition arm, so the rule is written once in one instruction.
+ */
+export function isFalsey(value) {
+    return value === false || value === null;
+}
+//# sourceMappingURL=arithmetic.js.map

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

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

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

@@ -0,0 +1,95 @@
+/**
+ * Step 4 of the bar cycle: the host's bar written into every `"bar"` register.
+ *
+ * The derived price fields are written out as expressions rather than as
+ * formulas because **their order of operations is part of the contract**
+ * (`compiled-program.md` 2.10): `hlc3` adds high to low, adds close to that,
+ * then divides. A different association gives a different last bit, and a study
+ * that matches a reference implementation on one engine and not on another is
+ * exactly the failure this project exists to prevent.
+ *
+ * **An absent volume rather than a zero is deliberate**, on the same ground as
+ * the chart contract's treatment of an unknown tick size: a script that sizes
+ * something by volume has to be able to tell "no trades" from "nobody told me".
+ *
+ * Four of the eight bar facts are the host's and four are the engine's, and a
+ * fact the engine can derive is never also stated by the host, because two
+ * sources for one number can disagree and no rule would say which of them wins.
+ * The session facts are on the derived side of that line: they follow from the
+ * hours in the instrument record, and nothing here asks a host about them.
+ */
+import type { BarView } from './library/index.js';
+import type { SessionFacts } from './session/index.js';
+import type { Value } from './values/index.js';
+/** One bar as a host supplies it. */
+export interface HostBar {
+    readonly open: number | null;
+    readonly high: number | null;
+    readonly low: number | null;
+    readonly close: number | null;
+    /** Absent, not zero, when the host has no volume for this instrument. */
+    readonly volume?: number | null;
+    /** Bar open time, milliseconds since the Unix epoch, UTC. */
+    readonly time: number | null;
+    /** Contracts outstanding as at the bar, spelled as `host-interface.md` 3.1. */
+    readonly oi?: number | null;
+}
+/**
+ * What the host states about the execution, `language.md` 7.2.
+ *
+ * Four facts and never a fifth. `isNew` and `updates` are the hand-over itself,
+ * so they are the call the host made rather than a field on it: `append` is a
+ * new bar and `update` is the same bar again, and the engine counts the
+ * executions the host asked for. Everything else about a bar the engine derives
+ * from the dataset and the position in it, and a host that offered one of those
+ * would be a second source for a number the engine already holds.
+ */
+export interface BarState {
+    /** This bar's interval has elapsed. True for every historical bar. */
+    readonly isConfirmed?: boolean;
+    /** A live feed is driving updates. */
+    readonly isRealtime?: boolean;
+}
+/** The facts about the bar being executed, derived once per execution. */
+export interface BarFacts {
+    readonly index: number;
+    readonly count: number;
+    readonly isFirst: boolean;
+    readonly isLast: boolean;
+    readonly isConfirmed: boolean;
+    readonly isRealtime: boolean;
+    readonly isNew: boolean;
+    readonly updates: number;
+    /**
+     * The session this bar falls in, derived from the instrument's own hours.
+     *
+     * Absent where the host stated no session, no timezone or no interval, which
+     * is what `host-interface.md` 4.1 says a script sees when the record holds no
+     * session: absent, and the per-bar session facts absent with it.
+     */
+    readonly isSessionFirst: boolean | null;
+    readonly isSessionLast: boolean | null;
+}
+/** The bar fields 2.10 names, and nothing else. */
+export declare const BAR_FIELDS: readonly string[];
+export declare function isBarField(name: string): boolean;
+/** One bar field's value, by the definitions of 2.10. */
+export declare function barField(field: string, bar: HostBar, facts: BarFacts): Value;
+/**
+ * The eight bar facts.
+ *
+ * `bar.index` is a position in the supplied data, not a universal address:
+ * loading more history shifts every index, which is why a script that has to
+ * remember a bar stores `time` instead.
+ */
+export declare function factsFor(index: number, supplied: number, state: BarState, isNew: boolean, updates: number, session: SessionFacts): BarFacts;
+/**
+ * The bar as a library call sees it, `compiled-program.md` 2.10.
+ *
+ * The same numbers the registers above are filled from, in the shape a call
+ * reads them in, so that a call and a register can never disagree about what
+ * the bar was. `previousClose` is a fact about the dataset rather than about
+ * any one call, which is why it travels here rather than in a state region.
+ */
+export declare function barViewOf(bar: HostBar, facts: BarFacts, previousClose: Value): BarView;
+//# sourceMappingURL=bars.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bars.d.ts","sourceRoot":"","sources":["../../../src/core/engine/bars.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAG/C,qCAAqC;AACrC,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,QAAQ;IACvB,sEAAsE;IACtE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,sCAAsC;IACtC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,0EAA0E;AAC1E,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,OAAO,GAAG,IAAI,CAAC;CACxC;AAED,mDAAmD;AACnD,eAAO,MAAM,UAAU,EAAE,SAAS,MAAM,EAoBvC,CAAC;AAEF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAMD,yDAAyD;AACzD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,GAAG,KAAK,CAkD5E;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,QAAQ,EACf,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,GACpB,QAAQ,CAgBV;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,QAAQ,EACf,aAAa,EAAE,KAAK,GACnB,OAAO,CAkBT"}

package/dist/core/engine/bars.js

@@ -0,0 +1,133 @@
+import { ABSENT, numberValue } from './values/index.js';
+/** The bar fields 2.10 names, and nothing else. */
+export const BAR_FIELDS = [
+    'open',
+    'high',
+    'low',
+    'close',
+    'volume',
+    'time',
+    'hl2',
+    'hlc3',
+    'ohlc4',
+    'hlcc4',
+    'oi',
+    'bar.index',
+    'bar.count',
+    'bar.isFirst',
+    'bar.isLast',
+    'bar.isConfirmed',
+    'bar.isRealtime',
+    'bar.isNew',
+    'bar.updates',
+];
+export function isBarField(name) {
+    return BAR_FIELDS.includes(name);
+}
+function present(value) {
+    return typeof value === 'number';
+}
+/** One bar field's value, by the definitions of 2.10. */
+export function barField(field, bar, facts) {
+    const { open, high, low, close } = bar;
+    switch (field) {
+        case 'open':
+            return open ?? ABSENT;
+        case 'high':
+            return high ?? ABSENT;
+        case 'low':
+            return low ?? ABSENT;
+        case 'close':
+            return close ?? ABSENT;
+        case 'volume':
+            return bar.volume ?? ABSENT;
+        case 'oi':
+            return bar.oi ?? ABSENT;
+        case 'time':
+            return bar.time ?? ABSENT;
+        case 'hl2':
+            return present(high) && present(low) ? numberValue((high + low) / 2) : ABSENT;
+        case 'hlc3':
+            return present(high) && present(low) && present(close)
+                ? numberValue((high + low + close) / 3)
+                : ABSENT;
+        case 'ohlc4':
+            return present(open) && present(high) && present(low) && present(close)
+                ? numberValue((open + high + low + close) / 4)
+                : ABSENT;
+        case 'hlcc4':
+            return present(high) && present(low) && present(close)
+                ? numberValue((high + low + close + close) / 4)
+                : ABSENT;
+        case 'bar.index':
+            return facts.index;
+        case 'bar.count':
+            return facts.count;
+        case 'bar.isFirst':
+            return facts.isFirst;
+        case 'bar.isLast':
+            return facts.isLast;
+        case 'bar.isConfirmed':
+            return facts.isConfirmed;
+        case 'bar.isRealtime':
+            return facts.isRealtime;
+        case 'bar.isNew':
+            return facts.isNew;
+        case 'bar.updates':
+            return facts.updates;
+        default:
+            return ABSENT;
+    }
+}
+/**
+ * The eight bar facts.
+ *
+ * `bar.index` is a position in the supplied data, not a universal address:
+ * loading more history shifts every index, which is why a script that has to
+ * remember a bar stores `time` instead.
+ */
+export function factsFor(index, supplied, state, isNew, updates, session) {
+    return {
+        index,
+        count: index + 1,
+        isFirst: index === 0,
+        // True when this is the greatest index the host has supplied. A live chart
+        // supplies bars one at a time, so its newest bar is always the last; a run
+        // over a whole dataset supplies them together, so only its final bar is.
+        isLast: index === supplied - 1,
+        isConfirmed: state.isConfirmed ?? true,
+        isRealtime: state.isRealtime ?? false,
+        isNew,
+        updates,
+        isSessionFirst: session.isFirstBar,
+        isSessionLast: session.isLastBar,
+    };
+}
+/**
+ * The bar as a library call sees it, `compiled-program.md` 2.10.
+ *
+ * The same numbers the registers above are filled from, in the shape a call
+ * reads them in, so that a call and a register can never disagree about what
+ * the bar was. `previousClose` is a fact about the dataset rather than about
+ * any one call, which is why it travels here rather than in a state region.
+ */
+export function barViewOf(bar, facts, previousClose) {
+    return {
+        index: facts.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: typeof previousClose === 'number' ? previousClose : null,
+        isConfirmed: facts.isConfirmed,
+        isRealtime: facts.isRealtime,
+        isNew: facts.isNew,
+        isLast: facts.isLast,
+        updates: facts.updates,
+        isSessionFirst: facts.isSessionFirst,
+        isSessionLast: facts.isSessionLast,
+    };
+}
+//# sourceMappingURL=bars.js.map

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

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

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

@@ -0,0 +1,162 @@
+/**
+ * The counters that make a runaway script stop.
+ *
+ * The engine owns the loop, so every one of these is a number it increments
+ * rather than something it hopes about. A platform running many customers'
+ * scripts in one process needs exactly that: exceeding a budget is a diagnostic
+ * on the script that did it, never a hang and never a frozen tab.
+ *
+ * **Two kinds of budget, and the difference matters.**
+ *
+ * The *loop budget* is part of the language. `compiled-program.md` 8.5 requires
+ * two engines to fail at the same iteration of the same loop on the same bar,
+ * so it counts `TICK` executions and nothing else, it comes from the program's
+ * own `limits()` line, and it is identical on every engine.
+ *
+ * The *host budgets* are not part of the language and cannot be, because a
+ * wall clock measures the machine rather than the program. They exist so that
+ * one script cannot take a process down, and a host that sets one accepts that
+ * a program refused here may run elsewhere. That is why the clock is off unless
+ * a host asks for it and why the step ceiling is derived from the program
+ * rather than chosen: see `stepBound`.
+ *
+ * The clock is read once every `clockEvery` steps rather than every step. A
+ * clock read costs more than an instruction, and reading it per instruction
+ * would make the wall clock the thing the wall clock measures.
+ */
+import type { Span } from '../span/index.js';
+import type { CompiledProgram } from './types.js';
+export interface EngineLimits {
+    /**
+     * Instructions one bar may execute, or null to derive it from the program.
+     *
+     * A verified program's bar has a bound that can be computed at load, so the
+     * derived value is the honest ceiling and a host rarely needs to set one.
+     */
+    readonly steps: number | null;
+    /** Milliseconds one bar may take, or null for no clock at all. */
+    readonly ms: number | null;
+    /** Elements one array may hold, `language.md` 14.1, OS5002. */
+    readonly arrayElements: number;
+    /** Code points one string may hold, OS5008. */
+    readonly stringLength: number;
+    /**
+     * Drawing objects one script may hold at once, OS5010.
+     *
+     * The host's, like the string ceiling: the language fixes no number, and a
+     * host that sets one accepts that a script refused here draws on another.
+     * What the language does fix is that reaching it is reported and that the
+     * oldest object is never dropped to make room, which is `stdlib.md` 14.4.
+     */
+    readonly drawingObjects: number;
+    /** Call frames, OS5005 at load. */
+    readonly frames: number;
+    /** The most a program's own `limits(loops = ...)` may ask for, OS5003. */
+    readonly loops: number | null;
+    /** The most a program's own `limits(history = ...)` may ask for, OS5003. */
+    readonly history: number | null;
+    /** Instructions in the whole program, OS5009 at load, or null for no ceiling. */
+    readonly instructions: number | null;
+    /** State regions, OS5004 at load, or null for no ceiling. */
+    readonly states: number | null;
+    /**
+     * Higher timeframe and other instrument reads one file may make, OS5006.
+     *
+     * The host's, because each read is a series it fetches and keeps in step with
+     * the chart. Reported at load rather than silently capped: dropping the reads
+     * past a ceiling is a plot that quietly turns absent, and nothing on the chart
+     * would say which one went.
+     */
+    readonly requests: number | null;
+    /** Steps between two readings of the clock. */
+    readonly clockEvery: number;
+}
+/**
+ * What an engine allows when a host says nothing.
+ *
+ * The ceilings that have a catalogue code are set; the clock is off, because a
+ * default wall clock would make the same script pass on a fast machine and fail
+ * on a slow one with nobody having asked for that trade.
+ *
+ * **`arrayElements` is the one number here the language fixes.** `language.md`
+ * 14.1 states it, so it is not a host's choice and a host lowering it refuses a
+ * script that a conforming engine runs. `scripts/check-limits.mjs` compares it
+ * against that sentence on every build, which is the only reason this file may
+ * write the number at all. Every other ceiling below is the host's, because the
+ * specification leaves it open.
+ */
+export declare const DEFAULT_LIMITS: EngineLimits;
+export declare function limitsWith(given: Partial<EngineLimits> | undefined): EngineLimits;
+/**
+ * The most instructions one bar of this program can possibly execute.
+ *
+ * Verification proves three things that together bound a bar: the target of
+ * every backward jump is a `TICK` (3.5 check 6), so no cycle runs without
+ * charging the loop budget; recursion is an error, so the call graph is acyclic
+ * and each call site's body runs at most once per acyclic segment; and the
+ * instruction lists are finite. So a segment between two `TICK` executions
+ * costs at most the program's whole instruction count once, and there are at
+ * most `limits.loops` such segments plus the one that ends at `HALT`.
+ *
+ * The number is generous by design. It is not a performance budget: it is the
+ * proof that a bar terminates, turned into a counter so that a program which
+ * somehow exceeds its own static bound stops instead of running forever.
+ */
+export declare function stepBound(program: CompiledProgram): number;
+/** A reading of the clock, injected so that a test is not at the mercy of one. */
+export type Clock = () => number;
+/**
+ * The per-bar counters.
+ *
+ * One object per engine, reset at step 3 of every execution of a bar, so a long
+ * dataset is never itself a reason to fail.
+ */
+export declare class Budget {
+    private loops;
+    private steps;
+    private started;
+    private nextClockAt;
+    private bar;
+    private readonly limits;
+    private readonly stepCeiling;
+    private readonly loopCeiling;
+    private readonly clock;
+    constructor(limits: EngineLimits, stepCeiling: number, loopCeiling: number, clock: Clock | undefined);
+    /** Step 3: the counters start again for this execution of this bar. */
+    begin(bar: number): void;
+    /**
+     * One instruction executed.
+     *
+     * Returns whether a budget is spent, rather than raising, so the dispatch
+     * loop does the check inline and the cost is one comparison on the path every
+     * instruction takes.
+     */
+    step(): boolean;
+    /** Which budget the last `step` ran out of, and the diagnostic for it. */
+    overrun(span: Span, loopLine: number | undefined): never;
+    /** Step 5.5: one iteration of loop `l` charged to the per-bar budget. */
+    tick(span: Span, line: number): void;
+    private spentLoops;
+    /**
+     * The drawing object ceiling, OS5010, charged before the object is built.
+     *
+     * `held` is what the script holds now, so the object about to be created is
+     * number `held + 1` and the refusal names that number. Checked before
+     * building rather than after, because an engine that allocates first and
+     * complains second has already spent the memory it is refusing to spend.
+     */
+    checkDrawing(span: Span, held: number): void;
+    /** The array ceiling, OS5002. */
+    checkArray(span: Span, name: string, size: number): void;
+    /** The string ceiling, OS5008, counted in code points as 3.1 requires. */
+    checkString(span: Span, text: string): string;
+    /**
+     * The same ceiling against a length that has not been built yet.
+     *
+     * `str.repeat` is where a string ceiling is actually reached, and building
+     * the string first to measure it is how an engine runs out of memory instead
+     * of reporting that it would have.
+     */
+    checkLength(span: Span, length: number): void;
+}
+//# sourceMappingURL=budget.d.ts.map

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

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