openalgo-script 0.1.0-alpha.1 → 0.4.0

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

@@ -0,0 +1,82 @@
+/**
+ * The six values a running program can hold, `compiled-program.md` 3.1.
+ *
+ * Absence is `null`, a number is a number, a boolean is a boolean and a string
+ * is a string, so four of the six tags are the ones the host language already
+ * carries and cost nothing to test. The two that have no native tag, a colour
+ * and a reference, are objects carrying a `tag` field, so `typeof` answers the
+ * question for every value in one step and no value can be mistaken for
+ * another.
+ *
+ * **Absence is never a number.** Section 3.4 is explicit that a not-a-number
+ * sentinel would make absence propagate through arithmetic by accident, which
+ * is the right answer for four operators and the wrong one for six, and would
+ * turn `isNone` into a floating point comparison. `null` has none of those
+ * properties, and the two rules the arithmetic actually needs, absence in
+ * gives absence out and a non-finite result becomes absent, are then written
+ * once each rather than hidden inside a representation.
+ *
+ * **A reference is an integer into the heap, not a pointer to an object.**
+ * That choice is what makes section 6.2's hardest requirement free: a
+ * checkpoint copies the heap table, every reference in a restored cell is the
+ * same integer it was, and two cells that shared an array still share it. A
+ * representation that put the object itself in the cell would have to work out
+ * which cells pointed at the same object and rebuild the graph, and a restore
+ * that deep copied each cell separately would silently turn one array into two.
+ */
+/** Red, green and blue as whole numbers 0 to 255, alpha as a number 0 to 1. */
+export interface ColourValue {
+    readonly tag: 'color';
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+    readonly a: number;
+}
+/** A handle into the object heap. Opaque to a script, and equal only to itself. */
+export interface Reference {
+    readonly tag: 'ref';
+    readonly id: number;
+}
+/** A value on the machine. */
+export type Value = null | number | boolean | string | ColourValue | Reference;
+/** Absence, the value a script writes `none`. */
+export declare const ABSENT: null;
+export declare function isAbsent(value: Value): value is null;
+export declare function isNumber(value: Value): value is number;
+export declare function isBool(value: Value): value is boolean;
+export declare function isString(value: Value): value is string;
+export declare function isColour(value: Value): value is ColourValue;
+export declare function isRef(value: Value): value is Reference;
+export declare function reference(id: number): Reference;
+/**
+ * A number made safe to store, by the two rules of section 3.1 that hold at
+ * every arithmetic result and every store.
+ *
+ * A result with no finite value is absent, checked here rather than at the end
+ * of an expression so that `(1e308 * 10) / 10` is absent rather than depending
+ * on where an engine happens to round. Negative zero becomes positive zero, so
+ * nothing downstream can observe the sign of a zero and two engines cannot
+ * differ over a minus in front of one.
+ */
+export declare function numberValue(x: number): Value;
+/** The name of a value's tag, for a diagnostic that has to say what it found. */
+export declare function tagOf(value: Value): string;
+/**
+ * Whole channels, and an alpha held to its range.
+ *
+ * `stdlib.md` 11.2 requires every call that computes a colour to round red,
+ * green and blue with the language's own rounding, halves away from zero,
+ * before it returns, so that the value model's invariant holds of every colour
+ * and not only of a literal.
+ */
+export declare function colour(r: number, g: number, b: number, a: number): ColourValue;
+/**
+ * Whether two values are equal under `EQ`, which is total: it always answers.
+ *
+ * Absent equals absent and nothing else. Two colours are equal when all four
+ * channels match. Two references are equal when they are the same object,
+ * which is `language.md` 9.3 and the reason `arrayEqual` exists in the library
+ * for comparing contents.
+ */
+export declare function valuesEqual(a: Value, b: Value): boolean;
+//# sourceMappingURL=value.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"value.d.ts","sourceRoot":"","sources":["../../../../src/core/engine/values/value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,mFAAmF;AACnF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,8BAA8B;AAC9B,MAAM,MAAM,KAAK,GAAG,IAAI,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;AAE/E,iDAAiD;AACjD,eAAO,MAAM,MAAM,MAAO,CAAC;AAE3B,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,IAAI,CAEpD;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,MAAM,CAEtD;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,OAAO,CAErD;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,MAAM,CAEtD;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,WAAW,CAE3D;AAED,wBAAgB,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,SAAS,CAEtD;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAE/C;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,KAAK,CAG5C;AAED,iFAAiF;AACjF,wBAAgB,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAY1C;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,WAAW,CAQ9E;AAiBD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,OAAO,CAUvD"}

package/dist/core/engine/values/value.js

@@ -0,0 +1,134 @@
+/**
+ * The six values a running program can hold, `compiled-program.md` 3.1.
+ *
+ * Absence is `null`, a number is a number, a boolean is a boolean and a string
+ * is a string, so four of the six tags are the ones the host language already
+ * carries and cost nothing to test. The two that have no native tag, a colour
+ * and a reference, are objects carrying a `tag` field, so `typeof` answers the
+ * question for every value in one step and no value can be mistaken for
+ * another.
+ *
+ * **Absence is never a number.** Section 3.4 is explicit that a not-a-number
+ * sentinel would make absence propagate through arithmetic by accident, which
+ * is the right answer for four operators and the wrong one for six, and would
+ * turn `isNone` into a floating point comparison. `null` has none of those
+ * properties, and the two rules the arithmetic actually needs, absence in
+ * gives absence out and a non-finite result becomes absent, are then written
+ * once each rather than hidden inside a representation.
+ *
+ * **A reference is an integer into the heap, not a pointer to an object.**
+ * That choice is what makes section 6.2's hardest requirement free: a
+ * checkpoint copies the heap table, every reference in a restored cell is the
+ * same integer it was, and two cells that shared an array still share it. A
+ * representation that put the object itself in the cell would have to work out
+ * which cells pointed at the same object and rebuild the graph, and a restore
+ * that deep copied each cell separately would silently turn one array into two.
+ */
+/** Absence, the value a script writes `none`. */
+export const ABSENT = null;
+export function isAbsent(value) {
+    return value === null;
+}
+export function isNumber(value) {
+    return typeof value === 'number';
+}
+export function isBool(value) {
+    return typeof value === 'boolean';
+}
+export function isString(value) {
+    return typeof value === 'string';
+}
+export function isColour(value) {
+    return typeof value === 'object' && value !== null && value.tag === 'color';
+}
+export function isRef(value) {
+    return typeof value === 'object' && value !== null && value.tag === 'ref';
+}
+export function reference(id) {
+    return { tag: 'ref', id };
+}
+/**
+ * A number made safe to store, by the two rules of section 3.1 that hold at
+ * every arithmetic result and every store.
+ *
+ * A result with no finite value is absent, checked here rather than at the end
+ * of an expression so that `(1e308 * 10) / 10` is absent rather than depending
+ * on where an engine happens to round. Negative zero becomes positive zero, so
+ * nothing downstream can observe the sign of a zero and two engines cannot
+ * differ over a minus in front of one.
+ */
+export function numberValue(x) {
+    if (!Number.isFinite(x))
+        return ABSENT;
+    return x === 0 ? 0 : x;
+}
+/** The name of a value's tag, for a diagnostic that has to say what it found. */
+export function tagOf(value) {
+    if (value === null)
+        return 'none';
+    switch (typeof value) {
+        case 'number':
+            return 'number';
+        case 'boolean':
+            return 'bool';
+        case 'string':
+            return 'string';
+        default:
+            return value.tag === 'color' ? 'color' : 'reference';
+    }
+}
+/**
+ * Whole channels, and an alpha held to its range.
+ *
+ * `stdlib.md` 11.2 requires every call that computes a colour to round red,
+ * green and blue with the language's own rounding, halves away from zero,
+ * before it returns, so that the value model's invariant holds of every colour
+ * and not only of a literal.
+ */
+export function colour(r, g, b, a) {
+    return {
+        tag: 'color',
+        r: channel(r),
+        g: channel(g),
+        b: channel(b),
+        a: a < 0 ? 0 : a > 1 ? 1 : a === 0 ? 0 : a,
+    };
+}
+function channel(x) {
+    if (!Number.isFinite(x))
+        return 0;
+    const rounded = halfAway(x);
+    return rounded < 0 ? 0 : rounded > 255 ? 255 : rounded;
+}
+/** The language's rounding, halves away from zero, `stdlib.md` 8.1. */
+function halfAway(x) {
+    const below = Math.floor(x);
+    const fraction = x - below;
+    if (fraction > 0.5)
+        return below + 1;
+    if (fraction < 0.5)
+        return below;
+    return x > 0 ? below + 1 : below;
+}
+/**
+ * Whether two values are equal under `EQ`, which is total: it always answers.
+ *
+ * Absent equals absent and nothing else. Two colours are equal when all four
+ * channels match. Two references are equal when they are the same object,
+ * which is `language.md` 9.3 and the reason `arrayEqual` exists in the library
+ * for comparing contents.
+ */
+export function valuesEqual(a, b) {
+    if (a === null || b === null)
+        return a === b;
+    if (typeof a === 'number' || typeof a === 'boolean' || typeof a === 'string') {
+        return a === b;
+    }
+    if (typeof b !== 'object' || b === null)
+        return false;
+    if (a.tag === 'color') {
+        return b.tag === 'color' && a.r === b.r && a.g === b.g && a.b === b.b && a.a === b.a;
+    }
+    return b.tag === 'ref' && a.id === b.id;
+}
+//# sourceMappingURL=value.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"value.js","sourceRoot":"","sources":["../../../../src/core/engine/values/value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAoBH,iDAAiD;AACjD,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,CAAC;AAE3B,MAAM,UAAU,QAAQ,CAAC,KAAY;IACnC,OAAO,KAAK,KAAK,IAAI,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAY;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,KAAY;IACjC,OAAO,OAAO,KAAK,KAAK,SAAS,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAY;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAY;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,GAAG,KAAK,OAAO,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,KAAY;IAChC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,GAAG,KAAK,KAAK,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,EAAU;IAClC,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;AAC5B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,CAAS;IACnC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,MAAM,CAAC;IACvC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACzB,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,KAAK,CAAC,KAAY;IAChC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,QAAQ,OAAO,KAAK,EAAE,CAAC;QACrB,KAAK,QAAQ;YACX,OAAO,QAAQ,CAAC;QAClB,KAAK,SAAS;YACZ,OAAO,MAAM,CAAC;QAChB,KAAK,QAAQ;YACX,OAAO,QAAQ,CAAC;QAClB;YACE,OAAO,KAAK,CAAC,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC;IACzD,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,MAAM,CAAC,CAAS,EAAE,CAAS,EAAE,CAAS,EAAE,CAAS;IAC/D,OAAO;QACL,GAAG,EAAE,OAAO;QACZ,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QACb,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QACb,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QACb,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KAC3C,CAAC;AACJ,CAAC;AAED,SAAS,OAAO,CAAC,CAAS;IACxB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IAClC,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC5B,OAAO,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;AACzD,CAAC;AAED,uEAAuE;AACvE,SAAS,QAAQ,CAAC,CAAS;IACzB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC5B,MAAM,QAAQ,GAAG,CAAC,GAAG,KAAK,CAAC;IAC3B,IAAI,QAAQ,GAAG,GAAG;QAAE,OAAO,KAAK,GAAG,CAAC,CAAC;IACrC,IAAI,QAAQ,GAAG,GAAG;QAAE,OAAO,KAAK,CAAC;IACjC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AACnC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,CAAQ,EAAE,CAAQ;IAC5C,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC7C,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,SAAS,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC7E,OAAO,CAAC,KAAK,CAAC,CAAC;IACjB,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACtD,IAAI,CAAC,CAAC,GAAG,KAAK,OAAO,EAAE,CAAC;QACtB,OAAO,CAAC,CAAC,GAAG,KAAK,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,CAAC,CAAC,GAAG,KAAK,KAAK,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC;AAC1C,CAAC"}

package/dist/core/engine/verify-budgets.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The budgets a host is willing to spend, `compiled-program.md` 2.4 and 9.4 step
+ * 7.
+ *
+ * Separate from `verify.ts` because it answers a different question. Verification
+ * asks whether this is a valid program, which every engine answers the same way
+ * because the specification says how. These ask whether this host will run it,
+ * and two hosts may honestly differ: a ceiling here is a configuration, not a
+ * property of the language.
+ *
+ * **None of them silently caps anything.** 2.4 is explicit: a host refuses at
+ * load, naming the limit and the value it allows. A program that quietly gets a
+ * smaller budget than it asked for produces a wrong number instead of a message,
+ * and nothing on the chart would say which number.
+ *
+ * The walks below read tables that verification has not reached yet, because the
+ * budget refusals are step 7 of 9.4 and verification is step 8. Reading them
+ * defensively is what keeps the specification's order from turning a malformed
+ * program into a thrown error rather than the OS6018 step 8 is about to report,
+ * naming the instruction.
+ */
+import type { Diagnostic } from '../diagnostics/index.js';
+import type { EngineLimits } from './budget.js';
+import type { CompiledProgram, Instruction } from './types.js';
+/** Each ceiling in turn, stopping at the first the program is over. */
+export declare function checkBudgets(program: CompiledProgram, limits: EngineLimits): Diagnostic | undefined;
+/**
+ * Every instruction list in the program, the bodies of its reads included.
+ *
+ * A read's expression is part of the program: an engine that cannot run an
+ * `ELEM` cannot run one inside a read either, and a budget or a tag worked out
+ * from the bar's list alone would say otherwise.
+ */
+export declare function allCode(program: CompiledProgram): (readonly Instruction[])[];
+//# sourceMappingURL=verify-budgets.d.ts.map

package/dist/core/engine/verify-budgets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-budgets.d.ts","sourceRoot":"","sources":["../../../src/core/engine/verify-budgets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAW,MAAM,YAAY,CAAC;AAExE,uEAAuE;AACvE,wBAAgB,YAAY,CAC1B,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,YAAY,GACnB,UAAU,GAAG,SAAS,CAkDxB;AAoGD;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,eAAe,GAAG,CAAC,SAAS,WAAW,EAAE,CAAC,EAAE,CAc5E"}

package/dist/core/engine/verify-budgets.js

@@ -0,0 +1,172 @@
+import { NO_POSITION, failure } from './errors.js';
+/** Each ceiling in turn, stopping at the first the program is over. */
+export function checkBudgets(program, limits) {
+    if (limits.loops !== null && program.limits.loops > limits.loops) {
+        return failure('OS5003', NO_POSITION, {
+            option: 'loops',
+            max: limits.loops,
+            found: program.limits.loops,
+        });
+    }
+    const history = program.limits.history;
+    if (limits.history !== null && history !== null && history > limits.history) {
+        return failure('OS5003', NO_POSITION, {
+            option: 'history',
+            max: limits.history,
+            found: history,
+        });
+    }
+    if (limits.instructions !== null) {
+        let found = 0;
+        for (const code of allCode(program))
+            found += code.length;
+        if (found > limits.instructions) {
+            return failure('OS5009', NO_POSITION, { found, max: limits.instructions });
+        }
+    }
+    if (limits.states !== null && program.states.length > limits.states) {
+        const [first, second] = busiestPair(program);
+        return failure('OS5004', NO_POSITION, {
+            found: program.states.length,
+            max: limits.states,
+            first,
+            second,
+        });
+    }
+    if (limits.requests !== null) {
+        // `host-interface.md` 5.2: the ceiling is the host's and it is stated at
+        // load, because the whole set of reads is known then. A nested read is one
+        // of them: it is a second series the host keeps in step with the chart.
+        const found = countRequests(program.requests);
+        if (found > limits.requests) {
+            return failure('OS5006', NO_POSITION, { found, max: limits.requests });
+        }
+    }
+    const depth = callDepth(program);
+    if (depth > limits.frames) {
+        return failure('OS5005', NO_POSITION, {
+            construct: 'a call',
+            found: depth,
+            max: limits.frames,
+        });
+    }
+    return undefined;
+}
+/** Every read the file makes, the ones written inside another included. */
+function countRequests(requests) {
+    let found = 0;
+    for (const one of requests)
+        found += 1 + countRequests(one.body.requests);
+    return found;
+}
+/**
+ * The opcode of one element of an instruction list, or nothing when it is not
+ * an instruction at all.
+ *
+ * The budget refusals are step 7 of 9.4 and verification is step 8, so the two
+ * walks below read lists that nothing has yet proved are instruction lists.
+ * Reading them defensively is what keeps the specification's order from turning
+ * a malformed program into a thrown error rather than the OS6018 step 8 is
+ * about to report, naming the instruction.
+ */
+function opcodeOf(instruction) {
+    return Array.isArray(instruction) ? instruction[0] : undefined;
+}
+/**
+ * The two functions whose nesting produced the most call paths.
+ *
+ * OS5004's message names them because the number of paths grows
+ * multiplicatively where several functions each call the next more than once,
+ * and a reader who is told only the total has nowhere to start. The pair with
+ * the most call sites between them is where the multiplication happened.
+ */
+function busiestPair(program) {
+    const counts = new Map();
+    const lists = [
+        ['the top level', program.code],
+        ...program.functions.map((one) => [one.name, one.code]),
+    ];
+    for (const [caller, code] of lists) {
+        for (const instruction of code) {
+            if (opcodeOf(instruction) !== 'CALL_FN')
+                continue;
+            const site = program.callSites[instruction[1]];
+            const callee = site === undefined ? undefined : program.functions[site.fn]?.name;
+            if (callee === undefined)
+                continue;
+            const key = `${caller}\u0000${callee}`;
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+        }
+    }
+    let best = ['the top level', 'the functions it calls'];
+    let most = 0;
+    // Sorted before the walk, so the answer does not depend on a map's order.
+    for (const key of [...counts.keys()].sort()) {
+        const count = counts.get(key) ?? 0;
+        if (count <= most)
+            continue;
+        const [caller, callee] = key.split('\u0000');
+        best = [caller ?? '', callee ?? ''];
+        most = count;
+    }
+    return best;
+}
+/**
+ * The deepest chain of call sites, which is the deepest the frame stack goes.
+ *
+ * Recursion is an error in the language, so the call graph is acyclic and the
+ * walk terminates; the visited set is a guard against a program that was
+ * written by something other than this compiler, and it stops rather than
+ * looping forever.
+ */
+function callDepth(program) {
+    const bodies = program.functions.map((one) => one.code);
+    const sitesIn = (code) => code.flatMap((one) => opcodeOf(one) === 'CALL_FN' && typeof one[1] === 'number' ? [one[1]] : []);
+    const known = new Map();
+    const walking = new Set();
+    const depthOf = (site) => {
+        const cached = known.get(site);
+        if (cached !== undefined)
+            return cached;
+        if (walking.has(site))
+            return 1;
+        walking.add(site);
+        const fn = program.callSites[site]?.fn;
+        const body = fn === undefined ? undefined : bodies[fn];
+        let deepest = 0;
+        for (const inner of body === undefined ? [] : sitesIn(body)) {
+            deepest = Math.max(deepest, depthOf(inner));
+        }
+        walking.delete(site);
+        known.set(site, deepest + 1);
+        return deepest + 1;
+    };
+    let deepest = 0;
+    for (const site of sitesIn(program.code))
+        deepest = Math.max(deepest, depthOf(site));
+    return deepest + 1;
+}
+/**
+ * Every instruction list in the program, the bodies of its reads included.
+ *
+ * A read's expression is part of the program: an engine that cannot run an
+ * `ELEM` cannot run one inside a read either, and a budget or a tag worked out
+ * from the bar's list alone would say otherwise.
+ */
+export function allCode(program) {
+    const lists = [
+        program.code,
+        ...program.functions.map((one) => one.code),
+    ];
+    const walk = (requests) => {
+        for (const request of requests) {
+            lists.push(request.body.code);
+            for (const one of request.body.functions)
+                lists.push(one.code);
+            walk(request.body.requests);
+        }
+    };
+    walk(program.requests);
+    return lists;
+}
+//# sourceMappingURL=verify-budgets.js.map

package/dist/core/engine/verify-budgets.js.map

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

package/dist/core/engine/verify-code.d.ts

@@ -0,0 +1,32 @@
+import type { Instruction } from './types.js';
+import type { ShapeCheck } from './verify-shape.js';
+export interface ListLimits {
+    readonly slots: number;
+    readonly cells: number;
+    readonly states: number;
+    readonly registers: number;
+    readonly channels: number;
+    readonly libFunctions: number;
+    readonly callSites: number;
+    readonly loops: number;
+    readonly consts: number;
+    readonly series: number;
+    argcOf(site: number): number;
+}
+/**
+ * Walks one instruction list.
+ *
+ * `terminator` is `HALT` for the bar's own code and `RET` for a function body,
+ * which is check 4, and the depth at it must be zero, which is check 5.
+ */
+export declare function checkList(shape: ShapeCheck, list: string, code: readonly Instruction[], limits: ListLimits, terminator: 'HALT' | 'RET'): boolean;
+/**
+ * Check 7: every channel declared `once` is written exactly once on every path
+ * from instruction 0 to `HALT`.
+ *
+ * That is how a plot column is guaranteed a value, or an explicit absence, for
+ * every bar. The counts are capped at two, because "more than once" is the whole
+ * of what the check needs to know and a loop would otherwise never settle.
+ */
+export declare function checkOnce(shape: ShapeCheck, code: readonly Instruction[], once: readonly boolean[]): boolean;
+//# sourceMappingURL=verify-code.d.ts.map

package/dist/core/engine/verify-code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-code.d.ts","sourceRoot":"","sources":["../../../src/core/engine/verify-code.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CAC9B;AAyCD;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,WAAW,EAAE,EAC5B,MAAM,EAAE,UAAU,EAClB,UAAU,EAAE,MAAM,GAAG,KAAK,GACzB,OAAO,CAiFT;AAsED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,SAAS,WAAW,EAAE,EAC5B,IAAI,EAAE,SAAS,OAAO,EAAE,GACvB,OAAO,CAgFT"}