functionalscript 0.46.1 → 0.47.0

package/fjs/edag/amnesia/module.f.mjs

@@ -0,0 +1,303 @@
+/**
+ * A tree-walking evaluator for `exp`: `vm(context)(e)` returns a primitive
+ * unchanged and dispatches a tagged tuple through one handler per tag.
+ *
+ * It remembers no node values — every incoming edge evaluates its target
+ * again — so it is the Amnesia model of
+ * [execution-models.md](../execution-models.md), for proving semantics and
+ * not for running FunctionalScript. See [README.md](./README.md).
+ *
+ * @module
+ *
+ * @import { Exp, Op1, Properties } from '../types.ts'
+ * @import { OptionLambda, OptionPropertyLambda, PropertyLambda } from '../types.ts'
+ * @import { Context, Map, ExpOp, TagMap } from './types.ts'
+ */
+
+import { assert } from '../../asserts/module.f.mjs'
+
+const o2lazy =
+    (/**@type {(a: any, b: () => any) => unknown}*/o) =>
+    /**
+     * @template {Exp} A
+     * @param {Context} c
+     * @param {readonly[unknown, A, A]} _2
+     */
+    (c, [, a, b]) => {
+        const f = vm(c)
+        return o(f(a), () => f(b))
+    }
+
+/**
+ * Eager pair: `o2lazy` already *is* the handler, so this forces `b` and
+ * hands it on — it must not wrap another `(c, e) =>` around it, or every
+ * binary op would evaluate to that inner handler instead of to a value.
+ */
+const o2 =
+    (/**@type {(a: any, b: any) => unknown}*/o) =>
+    o2lazy((a, b) => o(a, b()))
+
+/** @typedef {(c: Context, e: Op1) => unknown} _Func1 */
+
+const o1 =
+    (/**@type {(a: any) => unknown}*/o) =>
+    /**@type {_Func1}*/
+    (c, [, a]) => o(vm(c)(a))
+
+/** @typedef {(_: Exp) => unknown} _Eval */
+
+/** Both ways of being nullish, which is what every optional step guards. */
+/** @type {(v: unknown) => boolean} */
+const nullish = v => v === undefined || v === null
+
+/**
+ * The argument array of a call: one node evaluating to the *complete* array,
+ * spread at the call site — `f(a, b)` is `['()', f, ['[]', [a, b]]]`, and `=>`
+ * collects with `(...args)`. Passed as a single argument instead, the callee's
+ * `['args']` would be `[[a, b]]`.
+ *
+ * @type {(f: _Eval, e: Exp) => readonly any[]}
+ */
+const argsOf = (f, e) => /**@type {any}*/(f(e))
+
+/**
+ * Calls a bare value — no receiver.
+ *
+ * The temporary is load-bearing. Written as a property of whatever holds the
+ * callee, this would be a *method* call, so the callee would run with that
+ * holder as `this` — a receiver the chain does not have — and a detached host
+ * method would then silently succeed on the wrapper instead of throwing:
+ * `((a.at)(0))(0)` returned `Array.prototype.at`.
+ *
+ * @type {(f: _Eval, v: unknown, e: Exp) => unknown}
+ */
+const callValue = (f, v, e) => /**@type {any}*/(v)(...argsOf(f, e))
+
+/**
+ * Calls `obj[prop]` *on* `obj`. That receiver is the whole reason a property
+ * access owns its call rather than handing on a value: `[42].at(0)` is `42`
+ * only because `at` is called on the array.
+ *
+ * **The argument node, not the argument array.** Both helpers take the operand
+ * and evaluate it themselves, inside the call expression, so that JavaScript's
+ * own order applies: the callee is read first, then the arguments. That order
+ * is observable — `a.b(...c)` throws at the access when `a` is nullish with
+ * `c` untouched, where `(a?.b)(...c)` reaches the call and so evaluates `c`
+ * before throwing — and it is *not* provable here: both readings throw, this
+ * language has no mutation for an operand to record itself with, and a `throw`
+ * case is pass/fail rather than payload-inspecting (`fjs/AGENTS.md` §1.5). So
+ * the structure carries what a proof cannot. Taking an evaluated array instead
+ * would put every argument list ahead of the property read, and every test
+ * here would still pass.
+ *
+ * @type {(f: _Eval, obj: any, prop: any, e: Exp) => unknown}
+ */
+const callProperty = (f, obj, prop, e) => obj[prop](...argsOf(f, e))
+
+/**
+ * The short-circuit. A region whose guard failed produces `undefined` and
+ * skips every step of its continuation, operands and all — except `|!()`,
+ * which the parentheses put *outside* the region. That step runs anyway, on
+ * the `undefined` the region produced, which is why `(u?.b)(...c)` throws
+ * where `u?.b(...c)` is `undefined`; its arguments are evaluated first, as a
+ * call's always are, and then `undefined` is called.
+ *
+ * The walk carries no state and does not care which lambda type it is in:
+ * every step is `[tag, operand, continuation]`, and a `|!()` is reachable
+ * through `|.` steps from either — `(a?.(...b).c)(...d)` is exactly that.
+ *
+ * @type {(f: _Eval, k: OptionLambda | OptionPropertyLambda) => unknown}
+ */
+const skip = (f, k) => {
+    if (k === null) { return undefined }
+    return k[0] === '|!()'
+        ? callValue(f, undefined, k[1])
+        : skip(f, k[2])
+}
+
+/**
+ * A plain value inside an open region — what `?.()` hands on, and what a call
+ * step leaves. Nothing here can short-circuit: the two productions are a call
+ * that stays in the region and a property access that hands on a receiver.
+ *
+ * @type {(f: _Eval, v: unknown, k: OptionLambda) => unknown}
+ */
+const optionLambda = (f, v, k) => {
+    if (k === null) { return v }
+    const [o, e, cont] = k
+    switch (o) {
+        case '|()': return optionLambda(f, callValue(f, v, e), cont)
+        case '|.': return optionPropertyLambda(f, v, f(e), cont)
+    }
+}
+
+/**
+ * A property access inside an open region — both bits live, so this is the
+ * state every step is available in. `|()` inherits the region's guard,
+ * `|?.()` adds its own, `|!()` escapes it, and `|.` hands the receiver on
+ * within the region, which is the one production that exists to protect a bit
+ * other than the one it consumes.
+ *
+ * `obj[prop]` is read once per step, twice only where the guard has to see
+ * the value before the call is made.
+ *
+ * @type {(f: _Eval, obj: any, prop: any, k: OptionPropertyLambda) => unknown}
+ */
+const optionPropertyLambda = (f, obj, prop, k) => {
+    if (k === null) { return obj[prop] }
+    const [o, e, cont] = k
+    switch (o) {
+        case '|.': return optionPropertyLambda(f, obj[prop], f(e), cont)
+        case '|()': return optionLambda(f, callProperty(f, obj, prop, e), cont)
+        case '|!()': return callProperty(f, obj, prop, e)
+        case '|?.()': return nullish(obj[prop])
+            ? skip(f, cont)
+            : optionLambda(f, callProperty(f, obj, prop, e), cont)
+    }
+}
+
+/**
+ * A property access with **no** region around it — the continuation of a `.`
+ * node. Only a call can be here, because only a call uses the receiver: `|()`
+ * spends it and exits, `|?.()` spends it and opens a region that owns the
+ * rest of the chain. With no region open, that guard failing is simply the
+ * node's value, since `optionLambda` has no `|!()` of its own — but the walk
+ * still goes through `skip`, which reaches one through a `|.`.
+ *
+ * @type {(f: _Eval, obj: any, prop: any, k: PropertyLambda) => unknown}
+ */
+const propertyLambda = (f, obj, prop, k) => {
+    if (k === null) { return obj[prop] }
+    const [o, e, cont] = k
+    switch (o) {
+        case '|()': return callProperty(f, obj, prop, e)
+        case '|?.()': return nullish(obj[prop])
+            ? skip(f, cont)
+            : optionLambda(f, callProperty(f, obj, prop, e), cont)
+    }
+}
+
+/**@type {Map}*/
+const map = {
+    '!': o1(a => !a),
+    '!==': o2((a, b) => a !== b),
+    '%': o2((a, b) => a % b),
+    '&': o2((a, b) => a & b),
+    '&&': o2lazy((a, b) => a && b()),
+    // The call with no receiver and no region: the callee is an ordinary
+    // expression, so `(0, a.b)(...c)` is this node over a complete `.` while
+    // `a.b(...c)` is that `.` node owning its call. The two differ, and
+    // `throw.detachedReceiver` is the difference.
+    '()': (x, [, a, b]) => {
+        const i = vm(x)
+        return callValue(i, i(a), b)
+    },
+    '*': o2((a, b) => a * b),
+    '**': o2((a, b) => a ** b),
+    '+': o2((a, b) => a + b),
+    ',': (x, [, a]) => {
+        const f = vm(x)
+        return a.reduce((/**@type {unknown}*/_, c) => f(c), undefined)
+    },
+    '-': o2((a, b) => a - b),
+    // Property access, owning whatever its receiver is used for: a `null`
+    // continuation drops it, as reading `a.b` for its value does, and the two
+    // call steps are the only things that can spend it.
+    '.': (x, [, a, k, p]) => {
+        const i = vm(x)
+        return propertyLambda(i, i(a), i(k), p)
+    },
+    '/': o2((a, b) => a / b),
+    '<': o2((a, b) => a < b),
+    '<<': o2((a, b) => a << b),
+    '<=': o2((a, b) => a <= b),
+    '===': o2((a, b) => a === b),
+    '=>': (x, [, frameExp, body]) => {
+        const frame = vm(x)(frameExp)
+        /**@type {(...arg: readonly unknown[]) => unknown}*/
+        return (...args) =>vm({ frame, args })(body)
+    },
+    '>': o2((a, b) => a > b),
+    '>=': o2((a, b) => a >= b),
+    '>>': o2((a, b) => a >> b),
+    '>>>': o2((a, b) => a >>> b),
+    // Optional property access, owning the rest of its optional region. On a
+    // nullish input the region short-circuits: the node's own `index` is not
+    // evaluated — which is why `a?.[k]` does not evaluate `k` — and neither is
+    // any step of the continuation, `|!()` excepted. `skip` is what carries
+    // that exception, and it is why `u?.b` and `(u?.b)(d)` part company:
+    // the first is `undefined`, the second calls it.
+    '?.': (x, [, a, k, p]) => {
+        const i = vm(x)
+        const obj = i(a)
+        return nullish(obj) ? skip(i, p) : optionPropertyLambda(i, obj, i(k), p)
+    },
+    // Optional call, the region-opening counterpart of `?.`. The callee is an
+    // ordinary expression, so this node never carries a receiver — `a.b?.(c)`
+    // is a `.` node with a `|?.()` continuation, not this one — and a nullish
+    // callee leaves the arguments unevaluated.
+    '?.()': (x, [, a, b, k]) => {
+        const i = vm(x)
+        const f = i(a)
+        return nullish(f) ? skip(i, k) : optionLambda(i, callValue(i, f, b), k)
+    },
+    '??': o2lazy((a, b) => a ?? b()),
+    Number: o1(Number),
+    String: o1(String),
+    '[]': (x, [, a]) => {
+        const f = vm(x)
+        // A spread operand is iterated, not spliced as one element: `[...'ab']`
+        // is `['a', 'b']` and `[...1]` throws, per "array spread" in
+        // `../README.md`. `flatMap` alone flattens only real arrays.
+        /**@type {(e: Exp) => readonly unknown[]}*/
+        const spread = e => [.../**@type {any}*/(f(e))]
+        return a.flatMap(e =>
+            (e instanceof Array) && e[0] === '...' ? spread(e[1]) : [f(e)])
+    },
+    '^': o2((a, b) => a ^ b),
+    args: ({args}) => args,
+    frame: ({frame}) => frame,
+    neg: o1(a => -a),
+    // The key must *evaluate* to a string — a runtime constraint the
+    // shape-only schema cannot express, so the executor upholds it. Without
+    // the check JS `ToPropertyKey` would coerce, and `['own', o, 1]` would
+    // silently read `o['1']`.
+    own: o2((a, b) => {
+        assert(typeof b === 'string', ['own: key is not a string', b])
+        return Object.getOwnPropertyDescriptor(a, b)?.value
+    }),
+    undefined: () => undefined,
+    '{}': (x, [, a]) => {
+        const f = vm(x)
+        /**@type {(e: Properties) => readonly[unknown, unknown][]}*/
+        const g = e => e[0] === ':'
+            ? [[f(e[1]), f(e[2])]]
+            // `Object(...)` is what makes a nullish operand contribute nothing
+            // (`{...null}` is `{}`) while a string still contributes its
+            // indices — `Object.entries` alone throws on `null`/`undefined`.
+            : Object.entries(Object(f(e[1])))
+        const kv = a.flatMap(g)
+        return Object.fromEntries(kv)
+    },
+    '|': o2((a, b) => a | b),
+    '||': o2lazy((a, b) => a || b()),
+    '~': o1(a => ~a),
+}
+
+export const vm = (/**@type {Context}*/context) => {
+    const compute =
+        /**
+         * Generic over the tag, not `(e: ExpOp) =>`: with a union-typed `e`,
+         * `map[e[0]]` is a union of every handler signature, callable only with
+         * the intersection of their tuples — `never`. Through `K` it stays the
+         * one signature `(c, r: TagMap[K])` — see `TagMap` in `./types.ts`.
+         *
+         * @type {<K extends ExpOp[0]>(
+         *  e: TagMap[K] & readonly [K, ...readonly unknown[]]
+         * ) => unknown}
+         */
+        e => map[e[0]](context, e)
+    return (/**@type{Exp}*/e) => e instanceof Array
+        ? compute(e)
+        : e
+}

package/fjs/edag/amnesia/proof.f.d.mts

@@ -0,0 +1,79 @@
+/**
+ * Execution semantics of `vm` — one section per operand shape, since that is
+ * how `map`'s handlers are built (`o1`/`o2`/`o2lazy`), plus the nodes that
+ * evaluate their operands themselves (`,`, `[]`, `{}`, and the four chain
+ * nodes — `()`, `.`, `?.`, and `?.()`). Nothing is `todo` any more.
+ * This is the executing counterpart of `../proof.f.mjs`, which pins what the
+ * schema *accepts*; nothing here validates.
+ *
+ * @import { Exp } from '../types.ts'
+ * @import { Context } from './types.ts'
+ * @import { Assert } from '../../asserts/types.ts'
+ * @import { Equal } from '../../types/ts/types.ts'
+ * @import { Array as ExpArray, Call, Dot, Index, Op1, Op2 } from '../types.ts'
+ * @import { Get } from './types.ts'
+ */
+import type { Assert } from '../../asserts/types.ts';
+import type { Equal } from '../../types/ts/types.ts';
+import type { Array as ExpArray, Call, Dot, Op1, Op2 } from '../types.ts';
+import type { Get } from './types.ts';
+export type _PlusIsOp2 = Assert<Equal<Get<'+'>, Op2>>;
+export type _NegIsOp1 = Assert<Equal<Get<'neg'>, Op1>>;
+export type _BracketsIsArray = Assert<Equal<Get<'[]'>, ExpArray>>;
+export type _CallIsCall = Assert<Equal<Get<'()'>, Call>>;
+export type _DotIsDot = Assert<Equal<Get<'.'>, Dot>>;
+export declare const proof: {
+    primitive: () => void;
+    op0: () => void;
+    op1: () => void;
+    op2: () => void;
+    property: () => void;
+    lazy: () => void;
+    comma: () => void;
+    array: () => void;
+    object: () => void;
+    nested: () => void;
+    lambda: () => void;
+    call: () => void;
+    chain: {
+        callStep: () => void;
+        optionCallStep: () => void;
+        optionCallStepSkips: () => void;
+        receiver: () => void;
+        throw: {
+            detachedReceiver: () => unknown;
+            detachedReceiverAfterCall: () => unknown;
+            callStepOnNonFunction: () => unknown;
+            propertyOnUndefined: () => unknown;
+            propertyOnNull: () => unknown;
+        };
+    };
+    optionDot: () => void;
+    optionCall: () => void;
+    optionRegion: {
+        skips: () => void;
+        throw: {
+            closeStepOnUndefined: () => unknown;
+            closeStepOnNull: () => unknown;
+            closeStepPastSkippedProperty: () => unknown;
+            closeStepAfterOptionCall: () => unknown;
+            closeStepAfterPropertyGuard: () => unknown;
+            callOfSkippedGuard: () => unknown;
+        };
+    };
+    closure: () => void;
+    higherOrder: () => void;
+    throw: {
+        evaluatedIndex: () => unknown;
+        evaluatedArgument: () => unknown;
+        optionCallOnNonFunction: () => unknown;
+        arraySpreadOfNumber: () => unknown;
+        arraySpreadOfNull: () => unknown;
+        ownNonStringKey: () => unknown;
+        callNonFunction: () => unknown;
+        forcedAnd: () => unknown;
+        forcedOr: () => unknown;
+        forcedCoalesce: () => unknown;
+        forcedEager: () => unknown;
+    };
+};