@cotal-ai/lang 0.23.0 → 0.25.0

package/dist/engine/ctx.d.ts

@@ -0,0 +1,140 @@
+/**
+ * `__ctx`: the WHOLE seam between the transformed program and the host.
+ *
+ * The transform emits a CLOSED function expression with zero free identifiers; the host
+ * evaluates it in a Compartment with ZERO endowments and passes this object as the call argument
+ * (the seam contract). So this file is the complete list of what a program can reach. Anything not
+ * here is not reachable, which is why the member list is a surface both sides hold each other to.
+ *
+ * Every law lives here, and every table it needs is IMPORTED. `library.ts` owns the curated method
+ * tables and the free builtins; `values.ts` owns freezing, birth-depth stamping and the crossing
+ * check; `keys.ts` owns key allocation; `journal.ts` owns the entries. Nothing in this file is a
+ * second copy of any of them: a copied table is a table that disagrees with the walker on its
+ * first edit, and the walker is the differential oracle.
+ *
+ * WHAT THIS FILE IS NOT: it is not the walker rewritten. The walker enforces these laws inline
+ * while it walks; here they are the host side of a native program's calls. The behaviours must be
+ * identical and the differential suite is what says so: same programs, walker and engine,
+ * identical journals (entry sequences and step keys, not merely output).
+ */
+import { type EffectHandler } from "../effects.js";
+import type { Journal } from "../journal.js";
+import type { RunPins } from "../pins.js";
+/**
+ * A static per-call-site payload the transform computes from the input AST.
+ *
+ * It exists because the engine has NO AST at run time and one journal field is a function of one:
+ * a settled `race` records a `branchDigest` over its unwalked arms. Without this the engine could
+ * not produce a byte-identical entry for any race that settled, and the differential gate would
+ * fail on shape rather than on behaviour.
+ */
+export interface Site {
+    /** Branch key -> `digest(stripPositions(armBody))`, computed with the walker's own functions. */
+    readonly branchDigests?: Readonly<Record<string, unknown>>;
+}
+/**
+ * The seam. Fourteen members, and the count is the point: a member added here without a joint rule
+ * is a widening, and the transform's surface cell reddens on any call to a name not on this
+ * interface. Thirteen came with the seam contract; `callee` is the fourteenth, added under the
+ * adaptation invariant below.
+ */
+export interface EngineCtx {
+    /** L4013 step budget, plus the yield that keeps the macrotask queue alive and applies the cut. */
+    fuel(): void | Promise<void>;
+    /**
+     * Read a member: L4014 (no prototype reach, curated tables), L4020, L4018 on a computed key.
+     *
+     * `binding` is the cell read, taken as a third argument rather than a fifteenth member. A binding
+     * the transform classified as a CELL is emitted as `get(cell, "v", "x")`, and an absent OWN key
+     * means the declaration has not run yet, which is L2004 for that binding by name. PRESENCE is
+     * `hasOwn` and not truthiness, because `v: undefined` is a binding that HAS been initialised, to
+     * undefined. Without the argument, `get` is byte-unchanged.
+     */
+    get(o: unknown, k: unknown, binding?: string): unknown;
+    /**
+     * Write a member: L2031, L2032, L4014, L4017, L4019. Answers `v`, as an assignment does.
+     *
+     * `binding` is the cell WRITE, taken as a fourth argument for the same reason `get` took a third.
+     * It is present ONLY on an ASSIGNMENT to a cell, never on the declaration's own initialising write,
+     * and an absent OWN key there means the declaration has not run: L2004 naming the binding, in the
+     * walker's assignment words, which are not the read's. The key is LEFT ABSENT by the refusal, so
+     * the declaration that has not run yet still initialises the binding when it does.
+     */
+    set(o: unknown, k: unknown, v: unknown, binding?: string): unknown;
+    /**
+     * Call a member. The single L4020 exception: a method is resolved AT the call and nowhere else.
+     *
+     * `optional` is `o.m?.()`, a flag rather than a fifteenth member. It guards a
+     * NULLISH MEMBER and nothing else (measured on the walker, `?.` softens neither L4014 nor L4011),
+     * and a short-circuited call evaluates NO ARGUMENT, which is why the optional form takes a thunk.
+     *
+     * `chain` is EVERYTHING WRITTEN AFTER the optional call, as a closure. A short-circuit swallows the
+     * whole rest of the chain, and only the host knows a short-circuit happened: measured, `o.z?.().x`
+     * on an absent member is `undefined` while `o.m?.().x` on a member that RETURNS undefined is L4010,
+     * and a guard on the returned value cannot tell those apart, so it would drop a refusal in silence.
+     * Handing the continuation here lets the one place that made the decision apply it.
+     */
+    call(o: unknown, k: unknown, args: unknown[] | (() => unknown[] | Promise<unknown[]>), optional?: boolean, chain?: (value: unknown) => unknown): Promise<unknown>;
+    /** Stamp a freshly built container with this frame's depth (L2032's runtime half). */
+    born<T>(v: T): T;
+    /** A journalled primitive. */
+    effect(name: string, args: unknown[], site?: Site): Promise<unknown>;
+    /** A free builtin: called with `args`, or READ as a value when `args` is omitted. */
+    free(name: string, args?: unknown[]): unknown;
+    /** The thenable gate, before the host's await machinery can run a program closure. */
+    await(v: unknown): Promise<unknown>;
+    /** Template interpolation: L4018, no implicit conversion. */
+    template(parts: readonly string[], values: readonly unknown[]): string;
+    /** The binary operators' coercion law (L4018) and JavaScript's meaning. `===`/`!==` stay native. */
+    binary(op: string, l: unknown, r: unknown): unknown;
+    /** `-`, `+`, `~` under the same law, and `update` for the operand of `++`/`--`. `!`/`typeof` are native. */
+    unary(op: string, v: unknown): unknown;
+    /** The iterability law (L4015): arrays and strings, nothing else. */
+    iter(v: unknown): unknown[];
+    /** The L4011 refusal at a non-function callee. Emitted behind a `typeof`, so only the refusal runs. */
+    callee(v: unknown): unknown;
+    /** At the head of every emitted catch: rethrow the uncatchable, else the program-visible error. */
+    caught(e: unknown): unknown;
+}
+/** What a run hands the seam. */
+export interface EngineRun {
+    readonly runId: string;
+    readonly programHash: string;
+    readonly journal: Journal;
+    readonly handler: EffectHandler;
+    readonly pins: RunPins;
+    readonly onLog?: (line: {
+        scope: string;
+        values: readonly unknown[];
+    }) => void;
+    readonly shouldStop?: () => string | undefined;
+}
+/**
+ * The seam, plus the one thing the HOST needs from it that the program must never see.
+ *
+ * `steps()` is the count charged against the step budget, which a `RunResult` reports so a host can
+ * see how close a program runs to the ceiling before the ceiling is what tells it. It is deliberately
+ * NOT a member of {@link EngineCtx}: everything on that interface is reachable from inside the
+ * compartment, and a program that can read its own fuel gauge can shape its behaviour around one.
+ */
+export declare function createEngine(run: EngineRun): {
+    readonly ctx: EngineCtx;
+    steps(): number;
+};
+/** The seam alone. */
+export declare function createCtx(run: EngineRun): EngineCtx;
+/**
+ * The engine broke its own contract, and no program may catch that.
+ *
+ * The one thing that reaches this today is a native `ReferenceError`. The emitted module is a closed
+ * expression with zero free identifiers, so nothing the program wrote can name a binding that is not
+ * there; a ReferenceError therefore means a TDZ read the transform's classifier missed or an emitter
+ * temporary read before it was bound. It is not the program's error, it is not converted to one, and
+ * it is never mapped to L2004 by reading its message - that mapping would make a compiler bug
+ * indistinguishable from the language rule it imitates.
+ */
+export declare class EngineFault extends Error {
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
+//# sourceMappingURL=ctx.d.ts.map

package/dist/engine/ctx.d.ts.map

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