@evoke-build/evoke 0.6.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Radhi Guennichi
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,2 @@
+evoke
+Copyright 2026 Radhi Guennichi

package/README.md

@@ -0,0 +1,74 @@
+# @evoke-build/evoke
+
+You invoke a function; you evoke a reflex. A reflex is a small program a classifier selects and calls. The SDK
+loads a project of reflexes, decides what an input asks for, and runs it. The classifier is
+[Jev](https://typesafe.ai), TypeSafe AI's System One model. It answers closed questions with calibrated
+probabilities. `jev()` reaches it through TypeSafe AI's own API and `openjev()` through OpenJEV, an independent
+service; the core is bound to neither. The rules run in `core.wasm`, the same core as the `evoke` CLI. The SDK adds files, the network
+and a process.
+
+Six things to learn, in order: `reflex()` · `load()` · `handle()` · a `Decision` · `run()` · `replay()`. Each is
+explained in full in [the manual](https://evoke.build/manual/sdk/getting-started.html).
+
+## The first hour
+
+```ts
+// app.ts · npm i @evoke-build/evoke · export TYPESAFE_API_KEY=… · node app.ts "timer for 10 minutes"
+import { load, reflex } from "@evoke-build/evoke"
+import { jev } from "@evoke-build/evoke/jev"
+
+const timer = reflex({
+  description: "Start a countdown timer.",
+  effect: "write",
+  confirm: "Start a {duration} timer?",
+  args: { duration: { ask: "How long?", pick: "duration" } },
+  examples: { "timer for 10 minutes": { duration: "10 minutes" } },
+}, async ({ duration }) => {                                   // duration: number — seconds, typed from the manifest
+  setTimeout(() => console.log("ring"), duration * 1000)
+  return `ringing in ${duration} s`
+})
+
+const project = await load({ reflexes: { timer }, adapter: jev() })
+
+const handled = await project.handle(process.argv[2] ?? "", {
+  confirm: async d => { console.log(d.prompt.template); return true },   // "Start a 10 minutes timer?"
+  ask: async d => ({ duration: "10 minutes" }),                           // d.missing says what is missing and why
+})
+console.log(handled.outcome === "ran" ? handled.result.text : handled.outcome)
+```
+
+A `Decision` is a union. Narrow it by `outcome`, one of `run`, `confirm`, `ask` and `abstain`, then by `reflex`.
+It carries `args` as the classifier read them, `values` as the body receives them, `call` as one line,
+`confidence`, the `prompt` of a confirm, the `missing` of an ask, and the `trace` of every adapter call.
+
+## With files
+
+`evoke add evoke-build/reflexes` next to the app writes `evoke.toml`, `evoke.lock` and `evoke.d.ts`. Overlays and
+vocabularies under the same root tune the wording. That includes a reflex handed as code.
+
+```ts
+import type { Reflexes } from "./evoke.d.ts"
+
+const project = await load<Reflexes>({ root: import.meta.dirname })       // the adapter evoke.toml names
+const tenant = project.with({ vocab: { rooms: await db.rooms(user) } })   // a tenant's words, a tenant's plan; milliseconds
+const d = await tenant.decide("kill the lights in the den")
+if (d.outcome === "run" && d.reflex === "lights") console.log(d.values.room, d.values.state)   // typed by evoke.d.ts
+```
+
+## Tests
+
+```ts
+import { replay } from "@evoke-build/evoke/testing"
+
+const record = process.env.RECORD ? jev() : undefined                     // RECORD=1 asks Jev once and writes the file
+const project = await load({ reflexes: { timer }, adapter: replay("answers.toml", { record }) })
+```
+
+Every run after the first is offline, and always gives the same answers. The file is the CLI's own `answers.toml`.
+
+## Errors
+
+Every error ends in what to do: `lights: vocabulary "rooms" is empty  →  evoke vocab rooms add <word> "<meaning>"`.
+`DiagnosticError` is something a person fixes. `FaultError` is the adapter. `FailureError` is a body or the
+machine. Each carries the structured value, and the fixing line as `command`. Aborts reject with the signal's own
+reason.

package/dist/adapter.d.ts

@@ -0,0 +1,24 @@
+import type { Gate, Limits, Question, Raw, Request, State } from "./types.ts";
+/** An adapter: what it declares, and one stateless `answer` over any subset of a plan's questions. */
+export interface Adapter {
+    /** Opaque; changes whenever answers could. */
+    readonly id: string;
+    readonly limits?: Limits | undefined;
+    /** The floors, each meaning P(correct); none means every decision confirms. */
+    readonly gate?: Gate | undefined;
+    /** The plan digest a recording stands for; a project over another plan refuses it. */
+    readonly plan?: string | undefined;
+    /** A distribution per question asked, keys among those offered; `signal` aborts at the deadline. */
+    answer(state: State, questions: Record<string, Question>, signal: AbortSignal): Promise<Raw>;
+}
+/** One call as the SDK saw it: which adapter, how many questions, how long. */
+export interface Trace {
+    adapter: string;
+    questions: number;
+    ms: number;
+}
+/** The adapter asked within the deadline, its answers timed. */
+export declare function answered(adapter: Adapter, request: Request, deadline: number, signal: AbortSignal | undefined, invoked: string): Promise<{
+    raw: Raw;
+    trace: Trace;
+}>;

package/dist/adapter.js

@@ -0,0 +1,74 @@
+// Who answers: the contract every adapter meets — one object, the design's — and what the SDK does around one
+// call: the deadline as a signal joined with the caller's, the answer raced against it so an adapter that ignores
+// it still ends, the call timed, a throw that is not evoke's own turned into a transport fault. In: an adapter,
+// a request, a deadline, a signal. Out: the raw answers with one trace entry, or a FaultError; the caller's abort
+// passes through as its own reason.
+import { faulted } from "./core.js";
+import { EvokeError, FaultError } from "./errors.js";
+/** The adapter asked within the deadline, its answers timed. */
+export async function answered(adapter, request, deadline, signal, invoked) {
+    signal?.throwIfAborted();
+    // A referenced timer, so a hung adapter that holds no handle cannot let the process exit before the deadline.
+    const timeout = new AbortController();
+    const timer = setTimeout(() => timeout.abort(new DOMException(`no answer within ${deadline} ms`, "TimeoutError")), deadline);
+    const own = signal === undefined ? timeout.signal : AbortSignal.any([signal, timeout.signal]);
+    const started = performance.now();
+    try {
+        const raw = await Promise.race([adapter.answer(request.state, request.questions, own), aborted(own)]);
+        const ms = Math.round(performance.now() - started);
+        return { raw: checked(raw, request, invoked), trace: { adapter: adapter.id, questions: Object.keys(request.questions).length, ms } };
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw signal.reason;
+        // An adapter that could not name the call renders its fault again with it; one that knew better stands.
+        if (error instanceof FaultError)
+            throw error.command === "" ? faulted(error.fault, invoked) : error;
+        if (error instanceof EvokeError)
+            throw error;
+        const message = timeout.signal.aborted
+            ? `did not answer within ${deadline} ms`
+            : error instanceof Error
+                ? error.message
+                : String(error);
+        throw faulted({ type: "transport", message }, invoked);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** The answer as the core reads it — a distribution per question, every probability a finite number — or the
+ *  adapter's fault, named before the boundary: `NaN` and `undefined` cross as nothing, and would read as a bug. */
+function checked(raw, request, invoked) {
+    const first = Object.keys(request.questions)[0] ?? "route";
+    const malformed = (question, message) => faulted({ type: "malformed", question, message }, invoked);
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        throw malformed(first, `the answer is ${kind(raw)}, not an object`);
+    for (const [question, answer] of Object.entries(raw)) {
+        if (answer === null || typeof answer !== "object" || Array.isArray(answer))
+            throw malformed(question, `${kind(answer)}, not a distribution`);
+        for (const [key, p] of Object.entries(answer)) {
+            if (typeof p !== "number" || !Number.isFinite(p))
+                throw malformed(question, `${key} is ${kind(p)}, not a probability`);
+        }
+    }
+    return raw;
+}
+function kind(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    if (typeof value === "number")
+        return Number.isNaN(value) ? "NaN" : "infinite";
+    return typeof value;
+}
+/** A promise that rejects with the signal's reason, at once when it is already aborted. */
+function aborted(signal) {
+    return new Promise((_, reject) => {
+        if (signal.aborted)
+            reject(signal.reason);
+        else
+            signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+    });
+}

package/dist/contain.d.ts

@@ -0,0 +1,34 @@
+import type { Contained, Facts, NeedsKey, Place, Policy, Program } from "./types.ts";
+/** What the machine lacks that the declaration names: a path, or a program `PATH` does not hold. */
+export type Missing = {
+    place: Place;
+    key: NeedsKey;
+} | {
+    program: Program;
+};
+/** The policy and the facts a body runs under. */
+export interface Layers {
+    policy: Policy;
+    facts: Facts;
+}
+/** Whether this machine holds a whole declaration: macOS through Seatbelt, when `sandbox-exec` is there; Linux
+ *  through Node's layer alone, which holds a file body's files and programs, and the network from Node 25, never
+ *  what a program reaches, and holds nothing of an argv body. */
+export declare function status(body: "file" | "argv"): Contained;
+/** A private temporary folder for one run, under the system's, readable by its owner alone, by its real path;
+ *  removed after the run. */
+export declare function scratch(): {
+    path: string;
+    remove(): void;
+};
+/** The facts the core's rules need: each declared path's real form and kind, each program's place, and for a
+ *  file body this process's own runtime; a path or a program the machine lacks is the miss, before anything runs. */
+export declare function facts(policy: Policy, body: "file" | "argv", bodyDir: string, tmp: string): Facts | Missing;
+/** Node's flags for a file body, from the core. */
+export declare function flags(layers: Layers): string[];
+/** The command that runs a program under the layers: on macOS `sandbox-exec -p` with the core's profile in front;
+ *  on Linux the program itself, Node's flags being the one layer the SDK has. */
+export declare function under(program: string, args: string[], layers: Layers): {
+    file: string;
+    args: string[];
+};

package/dist/contain.js

@@ -0,0 +1,146 @@
+// The layers around a body in the SDK: Node's permission flags on both systems, and on macOS `sandbox-exec -p`
+// with the core's profile in front of the command; on Linux the kernel layer needs native code the SDK does not
+// carry, so the status says so. The facts the core's rules take, gathered here: this process's runtime as it runs
+// and whether it holds the network, each declared path's real form and kind, each program's place on PATH and the
+// interpreters it runs through, a private temporary folder for the run. In: a policy, the body's directory. Out:
+// the facts or what is missing, the command that runs a program under the layers, the status.
+import { accessSync, closeSync, constants, mkdtempSync, openSync, readSync, realpathSync, rmSync, statSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { call } from "./core.js";
+const PLATFORM = process.platform === "linux" ? "linux" : "macos";
+const SANDBOX_EXEC = "/usr/bin/sandbox-exec";
+/** Whether this runtime's permission model holds the network: from Node 25, the first to know `--allow-net`. */
+const HOLDS_NETWORK = process.allowedNodeEnvironmentFlags.has("--allow-net");
+/** Whether this machine holds a whole declaration: macOS through Seatbelt, when `sandbox-exec` is there; Linux
+ *  through Node's layer alone, which holds a file body's files and programs, and the network from Node 25, never
+ *  what a program reaches, and holds nothing of an argv body. */
+export function status(body) {
+    if (PLATFORM === "linux") {
+        if (body === "argv")
+            return { type: "none", why: "an argv body runs under no layer here; the kernel's needs native code the package does not carry" };
+        if (HOLDS_NETWORK)
+            return { type: "partial", why: "Node holds files, programs and the network; what a program reaches is not held" };
+        return { type: "partial", why: "Node holds files and programs; the network and what a program reaches are not held" };
+    }
+    return runs(SANDBOX_EXEC) ? { type: "full" } : { type: "none", why: "sandbox-exec is missing" };
+}
+/** A private temporary folder for one run, under the system's, readable by its owner alone, by its real path;
+ *  removed after the run. */
+export function scratch() {
+    const path = realpathSync(mkdtempSync(join(tmpdir(), "evoke-")));
+    return { path, remove: () => rmSync(path, { recursive: true, force: true }) };
+}
+/** The facts the core's rules need: each declared path's real form and kind, each program's place, and for a
+ *  file body this process's own runtime; a path or a program the machine lacks is the miss, before anything runs. */
+export function facts(policy, body, bodyDir, tmp) {
+    const found = {};
+    for (const [key, places] of [
+        ["reads", policy.reads ?? []],
+        ["writes", policy.writes ?? []],
+    ]) {
+        for (const place of places) {
+            let stats;
+            try {
+                stats = statSync(place.path);
+            }
+            catch {
+                return { place, key };
+            }
+            found[place.path] = { real: realpathSync(place.path), dir: stats.isDirectory() };
+        }
+    }
+    const programs = {};
+    for (const program of policy.runs ?? []) {
+        const path = locate(program);
+        if (path === undefined)
+            return { program };
+        programs[program] = executable(path);
+    }
+    return {
+        platform: PLATFORM,
+        ...(body === "argv" ? {} : { runtime: own() }),
+        body_dir: bodyDir,
+        tmp,
+        home: homedir(),
+        ...(Object.keys(found).length === 0 ? {} : { found }),
+        ...(Object.keys(programs).length === 0 ? {} : { programs }),
+    };
+}
+/** Node's flags for a file body, from the core. */
+export function flags(layers) {
+    return call("contain.node_flags", layers);
+}
+/** The command that runs a program under the layers: on macOS `sandbox-exec -p` with the core's profile in front;
+ *  on Linux the program itself, Node's flags being the one layer the SDK has. */
+export function under(program, args, layers) {
+    if (PLATFORM === "macos")
+        return { file: SANDBOX_EXEC, args: ["-p", call("contain.seatbelt", layers), program, ...args] };
+    return { file: program, args };
+}
+/** This process's runtime, which runs every file body: its program, and whether it holds the network. */
+function own() {
+    return { ...executable(process.execPath), ...(HOLDS_NETWORK ? { holds_network: true } : {}) };
+}
+/** A program by its absolute path, or the first executable of its name on `PATH`. */
+function locate(program) {
+    if (program.startsWith("/"))
+        return runs(program) ? program : undefined;
+    for (const dir of (process.env.PATH ?? "").split(":")) {
+        if (dir === "")
+            continue;
+        const candidate = join(dir, program);
+        if (runs(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+function runs(path) {
+    try {
+        accessSync(path, constants.X_OK);
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** A program as the kernel runs it: its real path, and on macOS the interpreters a script runs through — its
+ *  shebang's, and the program `env` hands over to, found on `PATH`. */
+function executable(path) {
+    const real = realpathSync(path);
+    const interpreters = PLATFORM === "macos" ? viaShebang(real) : [];
+    return { path: real, ...(interpreters.length === 0 ? {} : { interpreters }) };
+}
+function viaShebang(program) {
+    let first;
+    try {
+        first = head(program);
+    }
+    catch {
+        return [];
+    }
+    if (!first.startsWith("#!"))
+        return [];
+    const [interpreter, argument] = (first.slice(2).split("\n")[0] ?? "").trim().split(/\s+/);
+    if (interpreter === undefined || !interpreter.startsWith("/"))
+        return [];
+    const interpreters = [realpathSync(interpreter)];
+    if (interpreter.endsWith("/env") && argument !== undefined && !argument.startsWith("-")) {
+        const handed = locate(argument);
+        if (handed !== undefined)
+            interpreters.push(realpathSync(handed));
+    }
+    return interpreters;
+}
+/** A program's first bytes, where a script names its interpreter: never the whole of a binary. */
+function head(program) {
+    const fd = openSync(program, "r");
+    try {
+        const buffer = Buffer.alloc(256);
+        const read = readSync(fd, buffer, 0, buffer.length, 0);
+        return buffer.toString("latin1", 0, read);
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/dist/core.d.ts

@@ -0,0 +1,34 @@
+import { DiagnosticError, FaultError, type Problem } from "./errors.ts";
+import type { Op, Ops } from "./ops.ts";
+import type { Diagnostic, Fault, Fix, Result } from "./types.ts";
+/** What the op table answers: the result, the function's own error, or a bug in the call the SDK made. */
+export type Reply = {
+    ok: unknown;
+} | {
+    err: unknown;
+} | {
+    bug: string;
+};
+/** One op on one input: the raw reply. A trap in the core is a bug in evoke, thrown as one. A lone surrogate in
+ *  any string — `JSON.stringify` writes it as an escape, and no Rust string can hold it — crosses as U+FFFD. */
+export declare function reply(op: string, input: object): Reply;
+/** An op's value: what it answers under `ok`, the Result unwrapped where the function returns one. */
+export type Ok<O extends Op> = Ops[O]["output"] extends Result<infer T, infer _E> ? T : Ops[O]["output"];
+/**
+ * One op, typed: the value, or the op's own error thrown as the CLI would print it — a `DiagnosticError` for
+ * diagnostics, a `FaultError` for a fault. `invoked` names the SDK call for a fix that says to try again.
+ */
+export declare function call<O extends Op>(op: O, input: Ops[O]["input"], invoked?: string): Ok<O>;
+/** The command that fixes a problem, rendered by the core. */
+export declare function command(fix: Fix, invoked?: string): string;
+/** A diagnostic with its command rendered. */
+export declare function problem(diagnostic: Diagnostic, invoked?: string): Problem;
+/** Diagnostics over something given in code — a manifest, words, a gate — where the core's `evoke check`, meant
+ *  for a file, cannot apply: the fix is the call itself. */
+export declare function fromCode(diagnostics: readonly Diagnostic[], invoked: string): DiagnosticError;
+/** A fault as the error it is, its words and command rendered by the core. */
+export declare function faulted(fault: Fault, invoked?: string): FaultError;
+/** Why a text is no local or vocabulary name by the core's grammar, or nothing when it is one. */
+export declare function misnamed(text: string, kind: "local" | "vocab"): string | undefined;
+/** A bug in evoke — never a user error. */
+export declare function bug(message: string): Error;