openalgo-script 0.2.0 → 0.4.0

package/dist/adapters/codemirror/stream.js

@@ -0,0 +1,70 @@
+/**
+ * Highlighting, as the editor's line at a time tokenizer.
+ *
+ * The editor asks for one line's tokens at a time and remembers nothing between
+ * lines except the state this file hands back. The tier's `highlight` takes a
+ * whole file. So the line is what is lexed here, by the real lexer, through the
+ * same `highlight` a host would call itself.
+ *
+ * **That is an equivalence rather than an approximation, and it is measured.**
+ * `tests/adapters/codemirror/stream.test.ts` puts every script in the repository
+ * and the malformed corpus through both routes and compares them piece for
+ * piece: 4279 lines of real scripts, and not one of them differs. It holds
+ * because nothing in this language crosses a line ending: a string literal is
+ * refused at the end of its line, there is no block comment, and the layout
+ * tokens that do depend on the lines above are painted as whitespace either way.
+ * If the language ever grows something that does cross one, that test fails on
+ * the day it is added rather than on the day somebody notices a half painted
+ * line, and this becomes a line the narrowings file has to carry.
+ *
+ * A line is lexed once, not once per token: the pieces are computed when the
+ * editor arrives at the start of a line and walked from there. Without that, a
+ * line of twenty tokens would be lexed twenty times, which is the shape that
+ * makes a tokenizer show up in a frame budget.
+ */
+import { highlight } from '../../editor/index.js';
+import { HIGHLIGHT_TOKENS } from './tokens.js';
+/** The pieces of one line, computed once and kept until the line changes. */
+function piecesFor(state, line) {
+    if (state.line !== line || state.pieces.length === 0) {
+        state.line = line;
+        state.pieces = highlight(line);
+    }
+    return state.pieces;
+}
+/**
+ * The tokenizer, which a host turns into a language with one call.
+ *
+ * ```ts
+ * const openscript = StreamLanguage.define(openscriptStream);
+ * ```
+ *
+ * `token` moves the stream to the end of the piece that starts where it is and
+ * returns that piece's style. A stream that has somehow been left inside a piece,
+ * which the editor does when it re-tokenizes from a column rather than from the
+ * start of a line, is moved to the end of the piece containing it, so the
+ * tokenizer always advances and the editor cannot be made to loop.
+ */
+export const openscriptStream = {
+    name: 'openscript',
+    startState: () => ({ line: '', pieces: [] }),
+    copyState: (state) => ({ line: state.line, pieces: state.pieces }),
+    token(stream, state) {
+        if (stream.eol())
+            return null;
+        const pieces = piecesFor(state, stream.string);
+        const at = stream.pos;
+        const piece = pieces.find((one) => at >= one.span.offset && at < one.span.offset + one.span.length);
+        if (piece === undefined) {
+            // No piece covers the position, which cannot happen for a line the tier
+            // has covered and is still answered rather than trusted: the pieces tile
+            // the line, so this is a position outside it. Moving to the end leaves the
+            // editor with an unstyled remainder instead of an infinite loop.
+            stream.pos = stream.string.length;
+            return null;
+        }
+        stream.pos = piece.span.offset + piece.span.length;
+        return HIGHLIGHT_TOKENS[piece.kind];
+    },
+};
+//# sourceMappingURL=stream.js.map

package/dist/adapters/codemirror/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../../src/adapters/codemirror/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGlD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAS/C,6EAA6E;AAC7E,SAAS,SAAS,CAAC,KAAkB,EAAE,IAAY;IACjD,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrD,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;QAClB,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAoC;IAC/D,IAAI,EAAE,YAAY;IAElB,UAAU,EAAE,GAAgB,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAEzD,SAAS,EAAE,CAAC,KAAkB,EAAe,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;IAE5F,KAAK,CAAC,MAA0B,EAAE,KAAkB;QAClD,IAAI,MAAM,CAAC,GAAG,EAAE;YAAE,OAAO,IAAI,CAAC;QAE9B,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAC/C,MAAM,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC;QACtB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CACvB,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,CACzE,CAAC;QAEF,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,wEAAwE;YACxE,yEAAyE;YACzE,2EAA2E;YAC3E,iEAAiE;YACjE,MAAM,CAAC,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;YAClC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,CAAC,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC;QACnD,OAAO,gBAAgB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;CACF,CAAC"}

package/dist/adapters/codemirror/tokens.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The eleven kinds, as the editor's own highlighting tags.
+ *
+ * This is the translation an adapter exists to do: the language has eleven
+ * kinds, closed, and the editor has a vocabulary of tags its themes are written
+ * against. Neither knows about the other, and this file is the only place that
+ * knows both.
+ *
+ * **It is one record rather than a switch on purpose.** A style name is the one
+ * thing in this adapter that no type can hold: the editor looks a name up in its
+ * own tag table at run time and warns on a console about one it does not know,
+ * so a name that is wrong here is invisible to every check in this repository
+ * and shows up as an unpainted keyword in somebody's product. A host that
+ * disagrees with any of these, or whose theme is written against different
+ * names, replaces the row in one line:
+ *
+ * ```ts
+ * const tokens = { ...HIGHLIGHT_TOKENS, unknown: "invalid" };
+ * ```
+ *
+ * Two of the eleven are deliberately unstyled. `whitespace` has nothing to
+ * paint. `unknown` is the honest name for source the lexer took no token from,
+ * which is a character the language does not have, a region somebody wrote as a
+ * block comment, or a line continuation backslash: the first is a mistake and
+ * the last is not, so painting all three as invalid would paint a correct line
+ * red. `diagnose` is what says which of them is wrong, and the linter below is
+ * how a host shows that.
+ */
+import type { HighlightKind } from '../../editor/index.js';
+/**
+ * A style name per kind, or null for one the editor should leave alone.
+ *
+ * `builtin` uses the editor's modifier syntax for a name the environment
+ * supplies rather than the file, which is what a library name is.
+ */
+export declare const HIGHLIGHT_TOKENS: Readonly<Record<HighlightKind, string | null>>;
+/**
+ * The editor's name for the icon beside a completion row, per kind.
+ *
+ * The editor ships icons for a fixed set of names and shows none for a name it
+ * does not know, which is a missing icon rather than a missing row.
+ */
+export declare const COMPLETION_TYPES: Readonly<Record<string, string>>;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/adapters/codemirror/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../../src/adapters/codemirror/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC,CAY3E,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAO7D,CAAC"}

package/dist/adapters/codemirror/tokens.js

@@ -0,0 +1,34 @@
+/**
+ * A style name per kind, or null for one the editor should leave alone.
+ *
+ * `builtin` uses the editor's modifier syntax for a name the environment
+ * supplies rather than the file, which is what a library name is.
+ */
+export const HIGHLIGHT_TOKENS = {
+    keyword: 'keyword',
+    builtin: 'variableName.standard',
+    name: 'variableName',
+    number: 'number',
+    string: 'string',
+    color: 'color',
+    comment: 'comment',
+    operator: 'operator',
+    punctuation: 'punctuation',
+    whitespace: null,
+    unknown: null,
+};
+/**
+ * The editor's name for the icon beside a completion row, per kind.
+ *
+ * The editor ships icons for a fixed set of names and shows none for a name it
+ * does not know, which is a missing icon rather than a missing row.
+ */
+export const COMPLETION_TYPES = {
+    function: 'function',
+    value: 'constant',
+    namespace: 'namespace',
+    member: 'property',
+    variable: 'variable',
+    argument: 'property',
+};
+//# sourceMappingURL=tokens.js.map

package/dist/adapters/codemirror/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../../src/adapters/codemirror/tokens.ts"],"names":[],"mappings":"AA8BA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAmD;IAC9E,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,uBAAuB;IAChC,IAAI,EAAE,cAAc;IACpB,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,QAAQ,EAAE,UAAU;IACpB,WAAW,EAAE,aAAa;IAC1B,UAAU,EAAE,IAAI;IAChB,OAAO,EAAE,IAAI;CACd,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAqC;IAChE,QAAQ,EAAE,UAAU;IACpB,KAAK,EAAE,UAAU;IACjB,SAAS,EAAE,WAAW;IACtB,MAAM,EAAE,UAAU;IAClB,QAAQ,EAAE,UAAU;IACpB,QAAQ,EAAE,UAAU;CACrB,CAAC"}

package/dist/adapters/codemirror/tooltips.d.ts

@@ -0,0 +1,35 @@
+import type { Hover, SignatureHelp } from '../../editor/index.js';
+import type { EditorState, EditorTooltip, EditorTooltipView, EditorView } from './contract.js';
+/** What a host supplies to draw a tooltip, which is the whole of the markup. */
+export interface Renderer<Held> {
+    (held: Held): EditorTooltipView;
+}
+/**
+ * The lines a hover shows, in the order it shows them.
+ *
+ * Every one of them came from the compiler: the signatures from the library
+ * manifest, the sentence and the warmup from the specification's own tables, the
+ * type from the checker, and the refusal from the error catalogue. Nothing is
+ * written here, which is why this function is a join rather than a template.
+ */
+export declare function hoverLines(held: Hover): readonly string[];
+/** The lines a signature tooltip shows, with the active parameter named. */
+export declare function signatureLines(held: SignatureHelp): readonly string[];
+/**
+ * A hover tooltip source, which a host wires in one line.
+ *
+ * ```ts
+ * hoverTooltip(openscriptHoverTooltip(render))
+ * ```
+ */
+export declare function openscriptHoverTooltip(render: Renderer<Hover>): (view: EditorView, pos: number) => EditorTooltip | null;
+/**
+ * A signature tooltip for wherever the cursor is, or nothing where it is in no
+ * call.
+ *
+ * ```ts
+ * showTooltip.compute(["doc", "selection"], openscriptSignatureTooltip(render))
+ * ```
+ */
+export declare function openscriptSignatureTooltip(render: Renderer<SignatureHelp>): (state: EditorState) => EditorTooltip | null;
+//# sourceMappingURL=tooltips.d.ts.map

package/dist/adapters/codemirror/tooltips.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tooltips.d.ts","sourceRoot":"","sources":["../../../src/adapters/codemirror/tooltips.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAG/F,gFAAgF;AAChF,MAAM,WAAW,QAAQ,CAAC,IAAI;IAC5B,CAAC,IAAI,EAAE,IAAI,GAAG,iBAAiB,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,KAAK,GAAG,SAAS,MAAM,EAAE,CAOzD;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,MAAM,EAAE,CAYrE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,GACtB,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,KAAK,aAAa,GAAG,IAAI,CAWzD;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,QAAQ,CAAC,aAAa,CAAC,GAC9B,CAAC,KAAK,EAAE,WAAW,KAAK,aAAa,GAAG,IAAI,CAY9C"}

package/dist/adapters/codemirror/tooltips.js

@@ -0,0 +1,108 @@
+/**
+ * Hover and signature, as the editor's tooltips.
+ *
+ * This is the one part of the adapter that would put something on screen, and it
+ * is the one part that does not: the markup is a parameter, and there is no
+ * default for it. So nothing in this package, at any tier, names a browser
+ * global, and `scripts/check-layering.mjs` fails the build if anything under
+ * `src` does. The same files load in a worker, on a server and inside somebody
+ * else's application.
+ *
+ * It costs a host four lines and it is the whole point of the split. Every
+ * platform has a design system and none of them wants to fight a styled panel
+ * that arrived with a language package; a default renderer here would be that
+ * panel, and it would be the one thing in this adapter a host could not replace
+ * without replacing the adapter.
+ *
+ * What is not a parameter is the content. `hoverLines` and `signatureLines`
+ * below are what a tooltip says, in order, and every line of it came from the
+ * compiler: the signatures from the library manifest, the sentence and the
+ * warmup from the specification's own tables, the type from the checker, and the
+ * refusal from the error catalogue.
+ *
+ * ```ts
+ * hoverTooltip(openscriptHoverTooltip((held) => ({ dom: yourPanel(hoverLines(held)) })))
+ * ```
+ */
+import { hover, signature } from '../../editor/index.js';
+import { documentOf, normalisedOffset } from './positions.js';
+/**
+ * The lines a hover shows, in the order it shows them.
+ *
+ * Every one of them came from the compiler: the signatures from the library
+ * manifest, the sentence and the warmup from the specification's own tables, the
+ * type from the checker, and the refusal from the error catalogue. Nothing is
+ * written here, which is why this function is a join rather than a template.
+ */
+export function hoverLines(held) {
+    const lines = [...held.signatures];
+    if (held.summary !== undefined)
+        lines.push(held.summary);
+    if (held.warmup !== undefined)
+        lines.push(`First value: ${held.warmup}`);
+    if (held.refusal !== undefined)
+        lines.push(held.refusal);
+    if (held.kind === 'keyword')
+        lines.push('A reserved word of the language.');
+    return lines;
+}
+/** The lines a signature tooltip shows, with the active parameter named. */
+export function signatureLines(held) {
+    const lines = [held.signature];
+    const active = held.parameters[held.active];
+    if (active !== undefined) {
+        const value = active.defaultText === undefined ? '' : ` = ${active.defaultText}`;
+        const need = active.required ? 'required' : 'optional';
+        lines.push(`${active.name}: ${active.type}${value} (${need})`);
+        if (active.values.length > 0)
+            lines.push(`One of: ${active.values.join(', ')}`);
+    }
+    if (held.summary !== undefined)
+        lines.push(held.summary);
+    if (held.refusal !== undefined)
+        lines.push(held.refusal);
+    return lines;
+}
+/**
+ * A hover tooltip source, which a host wires in one line.
+ *
+ * ```ts
+ * hoverTooltip(openscriptHoverTooltip(render))
+ * ```
+ */
+export function openscriptHoverTooltip(render) {
+    return (view, pos) => {
+        const held = documentOf(view.state.doc.toString());
+        const found = hover(held.text, normalisedOffset(held, pos));
+        if (found === undefined)
+            return null;
+        return {
+            pos: held.at(found.span.offset),
+            end: held.at(found.span.offset + found.span.length),
+            create: () => render(found),
+        };
+    };
+}
+/**
+ * A signature tooltip for wherever the cursor is, or nothing where it is in no
+ * call.
+ *
+ * ```ts
+ * showTooltip.compute(["doc", "selection"], openscriptSignatureTooltip(render))
+ * ```
+ */
+export function openscriptSignatureTooltip(render) {
+    return (state) => {
+        const held = documentOf(state.doc.toString());
+        const at = normalisedOffset(held, state.selection.main.head);
+        const found = signature(held.text, at);
+        if (found === undefined)
+            return null;
+        return {
+            pos: state.selection.main.head,
+            above: true,
+            create: () => render(found),
+        };
+    };
+}
+//# sourceMappingURL=tooltips.js.map

package/dist/adapters/codemirror/tooltips.js.map

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

package/dist/core/accounting/charges.d.ts

@@ -0,0 +1,136 @@
+import type { Diagnostic } from '../diagnostics/index.js';
+import type { Contract, Money, RecordedFill } from './shapes.js';
+/**
+ * What a line's rate is measured against.
+ *
+ * Four bases cover every stack the documentation describes without naming a
+ * market: a fraction of turnover, money per unit, money per fill, and a
+ * fraction of the lines named before this one, which is the charge on a charge.
+ */
+export type ChargeBase = 'turnover' | 'units' | 'order' | 'charges';
+/**
+ * Which side of the trade a line applies to.
+ *
+ * A transaction tax levied on one side is expressed exactly rather than smeared
+ * across both fills at half the rate, which is what a reader doing it by hand
+ * has to do and what makes their figure disagree with their broker's.
+ */
+export type ChargeSide = 'buy' | 'sell' | 'both';
+/** One line of a schedule, applied to one fill. */
+export interface ChargeLine {
+    /** The platform's own word. */
+    readonly name: string;
+    readonly base: ChargeBase;
+    readonly side: ChargeSide;
+    /**
+     * Fraction for turnover and charges, money per unit for units, money for
+     * order.
+     */
+    readonly rate: number;
+    /** Floor per application. */
+    readonly min: Money | null;
+    /** Cap per application. */
+    readonly max: Money | null;
+    /** Base 'charges' only: names of lines declared before this one. */
+    readonly of: readonly string[];
+}
+/** The whole cost model a run was carried out under. */
+export interface ChargeSchedule {
+    readonly currency: string;
+    readonly digits: number;
+    readonly slippageTicks: number;
+    /** Applied in order, and order is part of the result. */
+    readonly lines: readonly ChargeLine[];
+    /**
+     * Where the schedule came from.
+     *
+     * A schedule derived from the declaration is derived again on replay rather
+     * than stored, because what the program states is stored once, as the
+     * program. A supplied one is the host's choice and travels with the record.
+     */
+    readonly source: 'declaration' | 'supplied';
+}
+/** What one fill was charged, line by line and in total. */
+export interface ChargeBreakdown {
+    readonly lines: readonly {
+        readonly name: string;
+        readonly amount: Money;
+    }[];
+    readonly total: Money;
+}
+/**
+ * What one fill cost, line by line and in total.
+ *
+ * **The lines are the arithmetic and the total is the money.** Each line's
+ * amount is computed in binary64 and left unrounded, and the per-fill total is
+ * rounded once, half to even, to the contract's digits. Rounding each line
+ * would round once per line, and two engines rounding in two places disagree in
+ * the last bit, which is a failed conformance comparison months later on
+ * somebody else's engine. So a reader adding the lines up by hand may land a
+ * fraction of the last digit away from the total, and that is the honest way
+ * round: the total is the figure the report accumulates.
+ *
+ * **Half to even, and not the language's own rounding.** `round()` in the
+ * language is halves away from zero, because a price a trader reads should
+ * agree with what they would write down (`stdlib.md` 8.1). Money folded over
+ * thousands of fills is a different question: away from zero biases every exact
+ * half upward, and half a unit of the last digit per fill is a bias that grows
+ * with the length of the backtest. Two rules, two reasons, both written down.
+ *
+ * **A line that does not apply to this side is not in the breakdown at all.** A
+ * name beside a zero reads as a charge that was levied and came to nothing,
+ * which is not what happened, and a later line levied on that name is levied on
+ * nothing, which is exactly what a tax on one side of the trade does.
+ */
+export declare function chargeFor(schedule: ChargeSchedule, fill: RecordedFill, contract: Contract): ChargeBreakdown;
+/**
+ * The declaration's own cost model, as the one schedule this module evaluates.
+ *
+ * **The declaration is not a second cost engine.** Its three commission
+ * spellings are a schedule of one line: a flat fee is a line charged per fill,
+ * a per unit fee is a line charged per unit, and a percentage is a line charged
+ * on turnover. A second evaluator for the declaration would be the same money
+ * computed two ways, and the day the two disagreed the report and the
+ * platform's own cost panel would both be defensible.
+ *
+ * **A commission of zero is no line at all**, rather than a line charging
+ * nothing. A zero line would put a name in every breakdown, and it would make a
+ * declaration that states no commission indistinguishable from one that states
+ * a commission, which is the distinction a run has to make before it accepts a
+ * schedule from the host as well.
+ *
+ * **A flat fee is charged per fill**, which is the one place `language.md` 13.3
+ * lets a reasonable person read the words two ways: per order, or per completed
+ * round trip. A charge is attributed to the fill that incurred it everywhere in
+ * this module, because that is what attributes it to a trade, so a round trip of
+ * two fills is charged twice.
+ *
+ * The currency and the digit count are parameters because neither is the
+ * declaration's to state: the declaration's currency is a label and is often
+ * left blank, and money rounding is a fact about the contract. A default here
+ * would be this module inventing a rounding rule for somebody else's market.
+ *
+ * `commissionType`'s value set is declared once, in `check/declaration.ts`, and
+ * is not restated here: what is below is a mapping from each spelling to the
+ * line it means. A program reaching this has been checked, so a fourth spelling
+ * cannot arrive, and the spelling that falls through is the declaration's own
+ * default rather than a shape this module made up.
+ */
+export declare function scheduleFromDeclaration(commission: number, commissionType: string, slippage: number, currency: string, digits: number): ChargeSchedule;
+/**
+ * Why this schedule cannot be carried out, or null.
+ *
+ * **Asked before the first bar, and answered once.** Everything here is a fact
+ * about the schedule rather than about any fill, so a run that would produce a
+ * number nobody can explain is refused while nothing has been computed and the
+ * cost of correcting it is one run. The contract is optional because a schedule
+ * is checkable on its own: what it adds is the three questions that need both,
+ * which are the currency the money is in, the digits it is rounded to, and the
+ * tick a slippage in ticks is measured in.
+ *
+ * The first problem found is the one reported. A list of everything wrong with
+ * a schedule reads as a worse schedule than it is, and it is corrected one line
+ * at a time regardless.
+ */
+export declare function scheduleProblem(schedule: ChargeSchedule, contract?: Contract | null): Diagnostic | null;
+//# sourceMappingURL=charges.d.ts.map

package/dist/core/accounting/charges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"charges.d.ts","sourceRoot":"","sources":["../../../src/core/accounting/charges.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEjE;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;AAEpE;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;AAEjD,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,QAAQ,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,CAAC;IAC3B,2BAA2B;IAC3B,QAAQ,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,EAAE,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,UAAU,CAAC;CAC7C;AAED,4DAA4D;AAC5D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAA;KAAE,EAAE,CAAC;IAC7E,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAgCD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,QAAQ,GACjB,eAAe,CAcjB;AAyED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,cAAc,CAQhB;AAcD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,cAAc,EACxB,QAAQ,GAAE,QAAQ,GAAG,IAAW,GAC/B,UAAU,GAAG,IAAI,CAQnB"}