babavoss 0.0.1 → 0.12.0

package/src/runtime/bridge.ts

@@ -0,0 +1,85 @@
+// The services bridge: turns a context's calls into `service` messages and
+// resolves their `serviced` answers. Shared by the bundled harness and the
+// in-process worker.
+import type { Context, Services, Who } from "../kernel/context.ts";
+import { ServiceError } from "../kernel/context.ts";
+import { isStream, type Serviced, type ServiceName, type ServiceRequest, type Cancel, type Credit } from "../transport/messages.ts";
+import type { Port } from "../ecs/runtime.ts";
+
+const errorOf = (m: Serviced) => new ServiceError(m.code === "denied" || m.code === "notfound" || m.code === "args" ? m.code : "failed", m.error ?? `${m.code}`);
+
+/**
+ * The bridge: a request once, or a stream many times, each with the job's
+ * signal. Aborted, a request's promise rejects and a stream's iterator ends,
+ * and the kernel is told to let go, whether or not it ever answers again.
+ */
+export function makeBridge(post: (m: ServiceRequest | Cancel | Credit) => void): { bridge: Services; answer(m: Serviced): void } {
+  const waiting = new Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void }>();
+  const streams = new Map<number, { push: (v: unknown[]) => void; end: (e?: Error) => void }>();
+  let next = 1;
+  const request = (who: Who, service: ServiceName, op: string, args: unknown[], signal?: AbortSignal) => new Promise<unknown>((resolve, reject) => {
+    const id = next++;
+    if (signal?.aborted) { reject(new ServiceError("failed", `${service}.${op}: cancelled`)); return; }
+    const cancel = () => { if (!waiting.has(id)) return; waiting.delete(id); post({ type: "cancel", id }); reject(new ServiceError("failed", `${service}.${op}: cancelled`)); };
+    signal?.addEventListener("abort", cancel, { once: true });
+    waiting.set(id, { resolve: (v) => { signal?.removeEventListener("abort", cancel); resolve(v); }, reject: (e) => { signal?.removeEventListener("abort", cancel); reject(e); } });
+    post({ type: "service", id, system: who.system, effect: who.effect, job: who.job, entity: who.entity, service, op, args });
+  });
+  const stream = (who: Who, service: ServiceName, op: string, args: unknown[], signal?: AbortSignal): AsyncIterable<unknown> => ({
+    // Lazy: constructing an unused iterator never allocates an OS resource.
+    async *[Symbol.asyncIterator]() {
+      if (signal?.aborted) throw new ServiceError("failed", `${service}.${op}: cancelled`);
+      const id = next++;
+      const queue: unknown[] = [];
+      let done = false, error: Error | null = null;
+      let wake: (() => void) | null = null;
+      const finish = (e?: Error) => { if (done) return; done = true; if (e) error = e; streams.delete(id); signal?.removeEventListener("abort", cancel); wake?.(); };
+      const cancel = () => { if (done) return; post({ type: "cancel", id }); queue.length = 0; finish(); };
+      streams.set(id, { push: (vs) => { queue.push(...vs); wake?.(); }, end: finish });
+      signal?.addEventListener("abort", cancel, { once: true });
+      post({ type: "service", id, system: who.system, effect: who.effect, job: who.job, entity: who.entity, service, op, args });
+      try {
+        for (;;) {
+          if (queue.length) {
+            yield queue.shift();
+            if (!done && service === "exec") post({ type: "credit", id });
+            continue;
+          }
+          if (done) { if (error) throw error; return; }
+          await new Promise<void>((r) => { wake = r; }); wake = null;
+        }
+      } finally { cancel(); }
+    },
+  });
+  const ask = (who: Who, service: ServiceName, op: string, args: unknown[], signal?: AbortSignal) => isStream(service, op) ? stream(who, service, op, args, signal) : request(who, service, op, args, signal);
+  return {
+    bridge: {
+      fs: (who, op, args, signal) => ask(who, "fs", op, args, signal),
+      http: (who, op, args, signal) => ask(who, "http", op, args, signal),
+      exec: (who, op, args, signal) => ask(who, "exec", op, args, signal),
+      secrets: (who, op, args, signal) => ask(who, "secrets", op, args, signal),
+    },
+    answer(m) {
+      const s = streams.get(m.id);
+      if (s) { if (m.more) s.push(m.values ?? []); else s.end(m.ok ? undefined : errorOf(m)); return; }
+      const w = waiting.get(m.id);
+      if (!w) return;
+      waiting.delete(m.id);
+      if (m.ok) w.resolve(m.value);
+      else w.reject(errorOf(m));
+    },
+  };
+}
+
+/** The port a runtime gives its jobs: a context per run, every service a message with who asked, carrying the job's signal. */
+export function portOver(bridge: Services, project: string, env: Record<string, string>): Port {
+  const frozen = Object.freeze({ ...env });
+  return (system, effect, job, signal, entity) => {
+    const who: Who = { project, system, effect, job, entity };
+    const service = <S extends keyof Services>(name: S) => new Proxy({}, {
+      get: (_, op: string) => (...args: unknown[]) => bridge[name](who, op as never, args, signal),
+    });
+    const ctx: Context = { project, fs: service("fs") as Context["fs"], http: service("http") as Context["http"], exec: service("exec") as Context["exec"], secrets: service("secrets") as Context["secrets"], env: frozen, signal };
+    return ctx;
+  };
+}

package/src/runtime/connect.ts

@@ -0,0 +1,54 @@
+// A Node's transport to a runtime process: the same program in the
+// `--runtime` role, spoken to as the worker is. `load-dir` becomes a
+// bundle of the project, its .env files and a `load`. The rest passes
+// through. The spawn hook is where the integrator puts the wall.
+import { join } from "node:path";
+import { framework } from "../kernel/where.ts";
+import { ProcessTransport, type Transport } from "../transport/transport.ts";
+import type { ToRuntime, FromRuntime } from "../transport/messages.ts";
+import type { Snapshot } from "../ecs/state.ts";
+import type { ToWorker, FromWorker } from "../baba/worker.ts";
+import type { Connect } from "../baba/node.ts";
+import { openProject, type Project } from "../baba/project.ts";
+import { InProcessBuilder, type Builder } from "../build/builder.ts";
+import { readEnv } from "./env.ts";
+
+export interface SpawnOptions { cwd: string; env: Record<string, string>; stdout: "inherit" | "pipe" | "ignore"; stderr: "inherit" | "pipe" | "ignore" }
+export type Spawn = (cmd: string[], options: SpawnOptions) => Transport<ToRuntime, FromRuntime>;
+
+/** The command that starts voss in a role: Bun on the framework's entry. */
+export function roleCommand(role: "--runtime" | "--builder" | "--server" | "--exec" | "--exec-watch"): string[] {
+  return [process.execPath, join(framework, "bin/voss.ts"), role];
+}
+export const runtimeCommand = () => roleCommand("--runtime");
+
+export const spawnProcess: Spawn = (cmd, options) => new ProcessTransport<ToRuntime, FromRuntime>(cmd, options);
+
+/**
+ * `project` names the directory; each load reads it again, so the entry
+ * follows the files. The bundle comes from `builder`, in-process unless
+ * the kernel gives its walled one.
+ */
+export function runtimeConnect(project: Project, spawn: Spawn = spawnProcess, builder: Builder = new InProcessBuilder()): Connect {
+  return () => {
+    const inner = spawn(runtimeCommand(), { cwd: "/", env: {}, stdout: "inherit", stderr: "inherit" });
+    let handler: ((m: FromWorker) => void) | null = null;
+    inner.onMessage((m) => handler?.(m));
+    const load = async (dir: string, snapshot: Snapshot | null, prepare?: boolean) => {
+      try {
+        const p = await openProject(dir);
+        const code = await builder.project(p);
+        const env = await readEnv(p.baba);
+        inner.send({ type: "load", project: { name: p.name, dir: p.dir, baba: p.baba }, code, env, snapshot, prepare });
+      } catch (err) {
+        handler?.({ type: "failed", error: err instanceof Error ? err.message : String(err) });
+      }
+    };
+    return {
+      send(m: ToWorker) { if (m.type === "load-dir") void load(m.dir ?? project.dir, m.snapshot, m.prepare); else inner.send(m); },
+      onMessage(h) { handler = h; },
+      onClose(h) { inner.onClose(h); },
+      close() { inner.close(); },
+    };
+  };
+}

package/src/runtime/env.ts

@@ -0,0 +1,35 @@
+// The baba's environment: .env and .env.local under .baba, the local
+// file laid over the other. KEY=VALUE lines, an optional `export `,
+// single or double quotes, and # comments.
+import { join } from "node:path";
+
+export function parseEnv(text: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const m = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    if (!m) continue;
+    let value = m[2]!;
+    const q = value[0];
+    if ((q === '"' || q === "'") && value.lastIndexOf(q) > 0) {
+      value = value.slice(1, value.lastIndexOf(q));
+      if (q === '"') value = value.replace(/\\n/g, "\n").replace(/\\"/g, '"');
+    } else {
+      const hash = value.indexOf(" #");
+      if (hash >= 0) value = value.slice(0, hash);
+      value = value.trim();
+    }
+    out[m[1]!] = value;
+  }
+  return out;
+}
+
+export async function readEnv(baba: string): Promise<Record<string, string>> {
+  const env: Record<string, string> = {};
+  for (const name of [".env", ".env.local"]) {
+    const f = Bun.file(join(baba, name));
+    if (await f.exists()) Object.assign(env, parseEnv(await f.text()));
+  }
+  return env;
+}

package/src/runtime/harness.ts

@@ -0,0 +1,80 @@
+// What both workers share: a baba, loaded, answering the kernel's messages.
+// The runtime owns the rounds; this turns fire, read, state, raw and retire
+// into its calls, and every round into a `round` the kernel may keep.
+import type { ToRuntime, FromRuntime, Result, ResultCode } from "../transport/messages.ts";
+import { manifestOf, type Baba } from "../ecs/baba.ts";
+import { Runtime, ContractError } from "../ecs/runtime.ts";
+import { StateError, type Snapshot } from "../ecs/state.ts";
+import { makeBridge, portOver } from "./bridge.ts";
+import { withPromptware } from "../promptware/system.ts";
+
+/** How long a `state` read waits for the round past `since` before answering the state as it is. */
+export const STATE_WAIT_MS = 25_000;
+
+export class Harness {
+  private rt: Runtime | null = null;
+  private activate: ((snapshot: Snapshot | null) => void) | null = null;
+  private readonly bridge: ReturnType<typeof makeBridge>;
+
+  constructor(private post: (m: FromRuntime) => void) {
+    this.bridge = makeBridge(post);
+  }
+
+  /** Loads the baba over the snapshot given; answers `loaded`, or throws for `failed`. */
+  load(own: Baba, project: { name: string; dir: string; baba: string }, env: Record<string, string>, snapshot: Snapshot | null, prepare = false): void {
+    // Voss's own systems join every baba after its own.
+    const v = withPromptware(own);
+    const manifest = manifestOf(v);
+    const make = (snapshot: Snapshot | null, auto: boolean) => new Runtime(v, {
+      auto,
+      port: portOver(this.bridge.bridge, project.dir, env),
+      snapshot: snapshot ?? undefined,
+      onRound: (state) => this.post({ type: "round", state, frame: this.rt!.frame(state.round - 1) }),
+      log: (line) => console.error(`${project.name}: ${line}`),
+    });
+    this.rt?.stop();
+    this.rt = make(snapshot, !prepare);
+    this.activate = prepare ? (latest) => { this.rt?.stop(); this.rt = make(latest, true); this.post({ type: "loaded", manifest, snapshot: this.rt.snapshot() }); } : null;
+    this.post({ type: "loaded", manifest, snapshot: this.rt.snapshot() });
+  }
+
+  async handle(m: ToRuntime): Promise<void> {
+    if (m.type === "hello" || m.type === "load") return;
+    if (m.type === "activate") {
+      const go = this.activate; this.activate = null;
+      try { if (!go) throw new Error("generation is not prepared"); go(m.snapshot); }
+      catch (e) { this.post({ type: "failed", error: e instanceof Error ? e.message : String(e) }); }
+      return;
+    }
+    if (m.type === "serviced") { this.bridge.answer(m); return; }
+    if (m.type === "retire") {
+      // Check and stop in the same turn: no new job can start in between.
+      if (m.unlessBusy && this.rt && [...this.rt.w.jobs.values()].some((j) => j.status === "running" && !j.effect.repeat)) {
+        this.post({ type: "retired", errors: [], snapshot: this.rt.snapshot(), busy: true }); return;
+      }
+      this.activate = null;
+      const snapshot = this.rt?.stop() ?? { round: 0, resources: {}, entities: {}, jobs: [] };
+      this.rt = null;
+      this.post({ type: "retired", errors: [], snapshot });
+      return;
+    }
+    const rt = this.rt;
+    if (!rt) { this.post({ type: "result", id: m.id, ok: false, code: "down", error: "not loaded" }); return; }
+    try {
+      let value: unknown;
+      if (m.type === "fire") value = await rt.fire(m.name, m.args, m.coerce, m.key);
+      else if (m.type === "read") value = rt.read(m.name, m.args, m.coerce);
+      else if (m.type === "state") { if (m.parts) value = rt.parts(m.parts); else { if (m.wait !== false) await rt.waitRound(m.since, STATE_WAIT_MS); value = m.frame ? rt.frame(m.since) : rt.state(m.since, { redacted: true }); } }
+      else value = await rt.raw(m.raw);
+      // A fire or a raw write resolves inside its round, so the round is the one it ran in: what a window waits for.
+      this.post({ type: "result", id: m.id, ok: true, value, ...(m.type === "fire" || m.type === "raw" ? { round: rt.round } : {}) });
+    } catch (err) {
+      this.post(failure(m.id, err));
+    }
+  }
+}
+
+export function failure(id: number, err: unknown): Result {
+  const code: ResultCode = err instanceof ContractError ? err.code : err instanceof StateError ? (err.code === "value" ? "args" : err.code) : "failed";
+  return { type: "result", id, ok: false, code, error: err instanceof Error ? err.message : String(err) };
+}

package/src/runtime/main.ts

@@ -0,0 +1,119 @@
+// The runtime role: one process per baba, walled, speaking IPC to the
+// kernel. The main thread owns the channel; the baba's bundle runs as a
+// Worker made from the text the kernel sends. Requests go to the worker and
+// results come back; the worker's service requests go to the kernel and
+// its answers back. A new load makes a new worker and retires the old one
+// once the new is live; a load that fails leaves the old one serving.
+import { ParentTransport } from "../transport/transport.ts";
+import { PROTOCOL, type ToRuntime, type FromRuntime, type Load } from "../transport/messages.ts";
+import type { FromHarness, ToHarness } from "./worker.ts";
+
+interface Live { worker: Worker; url: string; loaded: boolean }
+
+const parent = new ParentTransport<FromRuntime, ToRuntime>();
+let live: Live | null = null;
+let loading: Promise<void> = Promise.resolve();
+// Service requests by the id the kernel sees; the worker's own id is smaller in scope. Both ways, so a cancel finds its request.
+const asked = new Map<number, { live: Live; id: number }>();
+const kernelIds = new Map<Live, Map<number, number>>();
+let nextAsk = 1;
+
+parent.onMessage((m) => {
+  switch (m.type) {
+    case "hello": return;
+    case "load": loading = loading.then(() => load(m)); return;
+    case "activate":
+      if (!live) parent.send({ type: "failed", error: "no prepared generation" });
+      else live.worker.postMessage(m satisfies ToHarness);
+      return;
+    case "fire": case "read": case "state": case "raw":
+      if (!live) return parent.send({ type: "result", id: m.id, ok: false, code: "down", error: "no baba loaded" });
+      live.worker.postMessage(m satisfies ToHarness);
+      return;
+    case "serviced": {
+      const a = asked.get(m.id);
+      if (!a) return;
+      if (!m.more) { asked.delete(m.id); kernelIds.get(a.live)?.delete(a.id); }
+      a.live.worker.postMessage({ ...m, id: a.id } satisfies ToHarness);
+      return;
+    }
+    case "retire": {
+      const l = live;
+      if (!l) return parent.send({ type: "retired", errors: [], snapshot: { round: 0, resources: {}, entities: {}, jobs: [] } });
+      l.worker.postMessage(m satisfies ToHarness);
+      // The worker answers `retired`, forwarded by fromWorker, then is dropped.
+      return;
+    }
+  }
+});
+parent.send({ type: "hello", protocol: PROTOCOL, role: "runtime" });
+
+async function load(m: Load): Promise<void> {
+  const url = URL.createObjectURL(new Blob([m.code], { type: "application/javascript" }));
+  const fresh: Live = { worker: new Worker(url), url, loaded: false };
+  try {
+    const loaded = await new Promise<Extract<FromHarness, { type: "loaded" }>>((resolve, reject) => {
+      fresh.worker.onmessage = (e: MessageEvent<FromHarness>) => {
+        const h = e.data;
+        if (h.type === "loaded") resolve(h);
+        else if (h.type === "failed") reject(new Error(h.error));
+        else fromWorker(fresh, h);   // a job asked for at load reaches the kernel before the load is reported
+      };
+      fresh.worker.onerror = (e) => reject(new Error(e.message));
+      fresh.worker.postMessage({ type: "init", project: m.project, env: m.env, snapshot: m.snapshot, prepare: m.prepare } satisfies ToHarness);
+    });
+    fresh.worker.onmessage = (e: MessageEvent<FromHarness>) => fromWorker(fresh, e.data);
+    fresh.worker.onerror = (e) => died(fresh, e.message);
+    fresh.loaded = true;
+    const old = live;
+    live = fresh;
+    if (old) drop(old);
+    parent.send(loaded);
+  } catch (err) {
+    drop(fresh);
+    parent.send({ type: "failed", error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+function fromWorker(from: Live, h: FromHarness) {
+  if (h.type === "service") {
+    const id = nextAsk++;
+    asked.set(id, { live: from, id: h.id });
+    if (!kernelIds.has(from)) kernelIds.set(from, new Map());
+    kernelIds.get(from)!.set(h.id, id);
+    parent.send({ ...h, id });
+  } else if (h.type === "credit") {
+    const id = kernelIds.get(from)?.get(h.id);
+    if (id !== undefined) parent.send({ type: "credit", id });
+  } else if (h.type === "cancel") {
+    const id = kernelIds.get(from)?.get(h.id);
+    if (id === undefined) return;
+    kernelIds.get(from)!.delete(h.id);
+    asked.delete(id);
+    parent.send({ type: "cancel", id });
+  } else if (h.type === "retired") {
+    parent.send(h);
+    if (!h.busy) { if (live === from) live = null; drop(from); }
+  } else if (h.type === "failed") {
+    if (from === live) parent.send(h);
+  } else if (h.type === "loaded") {
+    if (from === live) parent.send(h);
+  } else if (h.type === "result" || h.type === "round") {
+    if (from === live || h.type === "result") parent.send(h);
+  }
+}
+
+/** The worker crashed: its service answers are unwanted; the kernel hears nothing more from it. */
+function died(from: Live, why: string) {
+  console.error(`the baba's worker died: ${why}`);
+  if (live === from) { live = null; parent.send({ type: "failed", error: `runtime worker died: ${why}` }); }
+  drop(from);
+}
+
+/** Ends a generation's worker; whatever it still asked the kernel for is cancelled. */
+function drop(l: Live) {
+  for (const [id, a] of [...asked]) if (a.live === l) { asked.delete(id); parent.send({ type: "cancel", id }); }
+  kernelIds.delete(l);
+  l.worker.terminate();
+  URL.revokeObjectURL(l.url);
+}

package/src/runtime/worker.ts

@@ -0,0 +1,33 @@
+// The harness bundled with a baba: runs inside the Worker the bundle is,
+// and turns every service a job asks for into a request the runtime's main
+// thread carries to the kernel. Messages in: init, then the kernel's. Out:
+// loaded, failed, result, round, retired, service.
+import type { FromRuntime, ToRuntime, Load } from "../transport/messages.ts";
+import { isBaba, type Baba } from "../ecs/baba.ts";
+import { Harness } from "./harness.ts";
+
+declare const self: Worker;
+
+export interface Init { type: "init"; project: Load["project"]; env: Record<string, string>; snapshot: Load["snapshot"]; prepare?: boolean }
+export type ToHarness = Init | Exclude<ToRuntime, Load>;
+export type FromHarness = FromRuntime;
+
+/** Called by the bundle's entry with the baba its default export is; does nothing outside a worker. */
+export function serve(v: unknown): void {
+  if (Bun.isMainThread) return;
+  const post = (m: FromHarness) => self.postMessage(m);
+  const h = new Harness(post);
+  self.onmessage = (e: MessageEvent<ToHarness>) => {
+    const m = e.data;
+    if (m.type === "init") {
+      try {
+        if (!isBaba(v)) throw new Error("the entry's default export is not a baba(); export default baba({ systems: [...] })");
+        h.load(v as Baba, m.project, m.env, m.snapshot, m.prepare);
+      } catch (err) {
+        post({ type: "failed", error: err instanceof Error ? err.message : String(err) });
+      }
+      return;
+    }
+    void h.handle(m);
+  };
+}