@cronch/kernel 0.0.0-stage → 0.12.0

package/index.js

@@ -0,0 +1,96 @@
+/**
+ * The kernel, compiled to WebAssembly (`crates/kernel-abi`). Requests and responses cross in deterministic CBOR.
+ */
+
+import { decode, encode } from "./cbor.js";
+
+export { decode, EncodeError, encode } from "./cbor.js";
+
+/** The kernel refused a request: it was not one it understands. A bug in the caller, never a verdict. */
+export class KernelError extends Error {
+  name = "KernelError";
+
+  /** @param {unknown} detail */
+  constructor(detail) {
+    super(`The kernel refused the request: ${JSON.stringify(detail)}`);
+    this.detail = detail;
+  }
+}
+
+/** @param {BufferSource | WebAssembly.Module} source */
+export async function instantiate(source) {
+  // A Worker can't compile bytes at runtime; it imports a compiled module instead.
+  const instance =
+    source instanceof WebAssembly.Module
+      ? await WebAssembly.instantiate(source, {})
+      : (await WebAssembly.instantiate(source, {})).instance;
+  const exports = instance.exports;
+
+  const call = (request) => {
+    const bytes = encode(request);
+    const pointer = exports.cronch_alloc(bytes.length);
+    new Uint8Array(exports.memory.buffer, pointer, bytes.length).set(bytes);
+    const packed = exports.cronch_call(pointer, bytes.length);
+    const outPointer = Number(packed >> 32n);
+    const outLength = Number(packed & 0xffffffffn);
+    // Copy out before freeing: the call may have grown, and so replaced, the memory buffer.
+    const out = new Uint8Array(exports.memory.buffer, outPointer, outLength).slice();
+    exports.cronch_free(outPointer, outLength);
+    const decoded = decode(out);
+    if (!decoded.ok) throw new KernelError({ kind: "undecodableResponse", error: decoded.error });
+    const response = decoded.value;
+    if (!response.ok) throw new KernelError(response.error);
+    return response.result;
+  };
+
+  return {
+    infer: (expr, vars, expected) =>
+      call({ op: "infer", expr, vars: vars ?? {}, ...(expected ? { expected } : {}) }),
+    evaluate: (expr, vars) => call({ op: "evaluate", expr, vars: vars ?? {} }),
+    checkHarness: (harness, iface) =>
+      call({ op: "checkHarness", harness, interface: iface }).problems,
+    inputType: (harness, iface) => call({ op: "inputType", harness, interface: iface }).type,
+    actionType: (iface, result, spawns) =>
+      call({ op: "actionType", interface: iface, result, spawns: spawns ?? {} }).type,
+    checkInterface: (iface) => call({ op: "checkInterface", interface: iface }).problems,
+    install: (capabilities) => call({ op: "install", capabilities }),
+    narrow: (iface, narrowings) => call({ op: "narrow", interface: iface, narrowings }),
+    init: ({ harness, interface: iface }) => call({ op: "init", harness, interface: iface ?? {} }),
+    deliver: (system, delivery) => call({ op: "deliver", system, delivery }),
+    view: (events) => call({ op: "view", events }).events,
+    eventType: (harness, iface) => call({ op: "eventType", harness, interface: iface }).type,
+    checkProperty: (property, harness, iface) =>
+      call({ op: "checkProperty", property, harness, interface: iface }).problems,
+    monitor: (property, trace) => call({ op: "monitor", property, trace }),
+    monitorStart: (property) => call({ op: "monitorStart", property }),
+    monitorStep: (property, state, events) =>
+      call({ op: "monitorStep", property, state: state ?? {}, events }),
+    prove: (subject, method) => call({ op: "prove", ...subject, method }),
+    verify: (subject, evidence) => call({ op: "verify", ...subject, evidence }),
+    certificate: (subject, alphabet, limit) =>
+      call({ op: "certificate", ...subject, alphabet, limit: limit ?? 10000 }),
+    obligation: ({ harness, interface: iface, invariant, floats }) =>
+      call({
+        op: "obligation",
+        harness,
+        interface: iface ?? {},
+        invariant,
+        floats: floats ?? "exact",
+      }),
+    checkInduction: ({ harness, interface: iface, invariant, state, input }) =>
+      call({ op: "checkInduction", harness, interface: iface ?? {}, invariant, state, input }),
+    elaborate: (source, capabilities, harnesses) =>
+      call({ op: "elaborate", source, capabilities, harnesses: harnesses ?? {} }),
+    key: (kind, object) => call({ op: "objectKey", kind, object }).key,
+    smtlib: (definitions, floats) => call({ op: "smtlib", definitions, floats: floats ?? "exact" }),
+    ruleObligations: ({ interface: iface, rule, floats, format }) =>
+      call({
+        op: "ruleObligations",
+        interface: iface,
+        rule,
+        floats: floats ?? "exact",
+        format: format ?? "smtlib",
+      }),
+    readValues: (reply, types) => call({ op: "readValues", reply, types }),
+  };
+}

package/kernel.sha256

@@ -0,0 +1 @@
+36b02b56a03c4bd45afdcdf78d048fca345bdea60c1bed6998a6c70d56e92ee0

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@cronch/kernel",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.12.0",
+  "description": "The reference kernel for Pata (Proven Agents, Trusted Actions): agent harnesses whose safety can be proved",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cronch-ai/kernel.git",
+    "directory": "javascript"
+  },
+  "homepage": "https://github.com/cronch-ai/kernel#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "pata": "./cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./kernel.wasm": "./kernel.wasm",
+    "./kernel.sha256": "./kernel.sha256",
+    "./run": {
+      "types": "./run.d.ts",
+      "default": "./run.js"
+    }
+  },
+  "files": [
+    "cli.js",
+    "index.js",
+    "cbor.js",
+    "index.d.ts",
+    "run.js",
+    "run.d.ts",
+    "kernel.wasm",
+    "kernel.sha256",
+    "examples/claude-code/*.pata",
+    "examples/claude-code/*.json",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "../scripts/build-wasm.sh",
+    "test": "node --test",
+    "prepack": "rm -rf examples && mkdir -p examples/claude-code && cp ../examples/claude-code/*.pata ../examples/claude-code/*.json examples/claude-code/",
+    "clean": "npm run clean --prefix .."
+  },
+  "license": "Apache-2.0"
+}

package/run.d.ts

@@ -0,0 +1,67 @@
+import type {
+  Delivery,
+  Event,
+  Harness,
+  Interface,
+  Kernel,
+  Label,
+  Outcome,
+  System,
+  Value,
+} from "./index.js";
+
+/** The `prev` of a log's first entry. */
+export const GENESIS: string;
+
+/** The error a call fails with when its implementation answered with a result the kernel withheld. */
+export const NO_FIT: string;
+
+/** The kernel this package ships, instantiated once. Node only. */
+export function kernel(): Promise<Kernel>;
+
+export interface CallContext {
+  /** The call's identifier, as the kernel numbered it. */
+  readonly call: number;
+  /** Aborted when the run cancels the call. The handler should still answer (H6). */
+  readonly signal: AbortSignal;
+  /** Deliver a message to the run on `channel`, as `prefix.channel`. */
+  send(channel: string, value: Value): void;
+}
+
+/** An operation's implementation: its result is the call's, and a throw fails the call. */
+export type Handler = (args: Value, context: CallContext) => Promise<Value>;
+
+export interface RunOptions {
+  /** The start's value. */
+  readonly input?: Value;
+  /** The sources the starting principal is no more trusted than. None: a trusted principal. */
+  readonly label?: Label;
+  readonly kernel?: Kernel;
+  /** For a term, in place of the interface installed from `capabilities`, each under its own name. */
+  readonly interface?: Interface;
+}
+
+export interface LogEntry {
+  readonly seq: number;
+  readonly prev: string;
+  readonly delivery: Delivery;
+  readonly events: readonly Event[];
+  /** The kernel's `logEntry` key of the entry without it. */
+  readonly key: string;
+}
+
+/**
+ * Run `harness`, Pata source or an elaborated term, to the end, with each operation (`prefix.op`) answered by its
+ * handler. A local host that keeps the host protocol: no network, no state beyond the run.
+ */
+export function run(
+  harness: string | Harness,
+  capabilities: Readonly<Record<string, Interface>>,
+  handlers: Readonly<Record<string, Handler>>,
+  options?: RunOptions,
+): Promise<{
+  readonly outcome: Outcome | undefined;
+  readonly system: System;
+  readonly events: readonly Event[];
+  readonly log: readonly LogEntry[];
+}>;

package/run.js

@@ -0,0 +1,145 @@
+/**
+ * A local host: runs a harness against capabilities implemented by JavaScript functions, with no network and no state
+ * beyond the run. It keeps the host protocol (`docs/2026-11-06-host-protocol.md`); each duty is marked where it is
+ * kept.
+ */
+
+import { readFile } from "node:fs/promises";
+import { instantiate } from "./index.js";
+
+/** The `prev` of a log's first entry. */
+export const GENESIS = `sha256:${"0".repeat(64)}`;
+
+/** The error a call fails with when its implementation answered with a result the kernel withheld. */
+export const NO_FIT = "no result that fits";
+
+let shared;
+
+/** The kernel this package ships. */
+export function kernel() {
+  shared ??= readFile(new URL("./kernel.wasm", import.meta.url)).then(instantiate);
+  return shared;
+}
+
+/**
+ * Runs `harness`, Pata source or an elaborated term, to the end.
+ *
+ * `capabilities` maps each capability's name, as `uses` names it, to its contract. `handlers` maps an operation, as
+ * `prefix.op`, to an async function of its arguments and `{ call, signal, send }`: its result is the call's, and a
+ * throw fails the call. `send(channel, value)` delivers a message to the run.
+ *
+ * Options: `input`, the start's value; `label`, the sources the starting principal is no more trusted than (none: a
+ * trusted principal); `kernel`, an instantiated kernel; `interface`, for a term, in place of one installed from
+ * `capabilities` with each under its own name.
+ *
+ * Resolves to the run's `outcome`, its final `system`, every event, and the `log`, hash-chained as `logEntry`s.
+ */
+export async function run(harness, capabilities, handlers, options = {}) {
+  const k = options.kernel ?? (await kernel());
+  const { term, iface } = load(k, harness, capabilities, options.interface);
+
+  const ready = k.init({ harness: term, interface: iface });
+  if (ready.kind !== "ready") throw new Error(`init: ${JSON.stringify(ready)}`);
+  let system = ready.system;
+  const events = [];
+  const log = [];
+  const queue = [];
+  const inFlight = new Map();
+  let wake = () => {};
+
+  const enqueue = (delivery) => {
+    queue.push(delivery);
+    wake();
+  };
+
+  const perform = (event) => {
+    const { action } = event;
+    const id = event.call;
+    const handler = handlers[action.op];
+    const controller = new AbortController();
+    const send = (channel, value) => enqueue({ input: { kind: "msg", channel, value } });
+    const done = (async () => {
+      if (handler === undefined) throw new Error(`no handler for ${action.op}`);
+      return handler(action.args, { call: id, signal: controller.signal, send });
+    })().then(
+      (value) => ({ kind: "ret", call: id, value }),
+      (error) => ({ kind: "failed", call: id, error: String(error?.message ?? error) }),
+    );
+    inFlight.set(key(event.origin, id), controller);
+    // H8: every call ends, with its result or `failed`.
+    done.then((input) => {
+      inFlight.delete(key(event.origin, id));
+      enqueue(event.origin.length === 0 ? { input } : { to: event.origin, input });
+    });
+  };
+
+  const step = (delivery) => {
+    // H1, H3: each delivery steps the configuration the last one returned, unchanged, one at a time.
+    const out = k.deliver(system, delivery);
+    system = out.system;
+    events.push(...out.events);
+    // H7: every delivery and its events, in order, each entry keyed with the last one's key as `prev`.
+    const seq = log.length;
+    const prev = seq === 0 ? GENESIS : log[seq - 1].key;
+    const entry = { seq, prev, delivery, events: out.events };
+    log.push({ ...entry, key: k.key("logEntry", entry) });
+    for (const event of out.events) {
+      if (event.kind === "out" && event.performed && event.action.kind === "call") {
+        // H5: exactly the calls the interpreter performed, each once.
+        perform(event);
+      } else if (event.kind === "out" && event.performed && event.action.kind === "cancel") {
+        // H6: cancellation goes to the implementation, which still answers.
+        inFlight.get(key(event.origin, event.action.call))?.abort();
+      } else if (event.kind === "withheld" && fits(event.reason) && delivery.input.kind === "ret") {
+        // H8: a result that didn't fit leaves the call pending, so it fails instead.
+        const input = { kind: "failed", call: delivery.input.call, error: NO_FIT };
+        queue.unshift(delivery.to === undefined ? { input } : { to: delivery.to, input });
+      }
+    }
+  };
+
+  // H4: the start comes from the principal, with an honest label; results only from their implementations.
+  const start = { kind: "start", value: options.input ?? null };
+  if (options.label !== undefined) start.label = options.label;
+  step({ input: start });
+  for (;;) {
+    while (queue.length > 0) step(queue.shift());
+    if (inFlight.size === 0) break;
+    await new Promise((resolve) => {
+      wake = resolve;
+    });
+  }
+  return { outcome: system.root.outcome, system, events, log };
+}
+
+/** Whether a withheld result left its call pending: it was the call's, but didn't fit. */
+const fits = (reason) => reason.kind === "mismatch" || reason.kind === "postcondition";
+
+const key = (origin, call) => `${origin.join("/")}:${call}`;
+
+function load(k, harness, capabilities, given) {
+  if (typeof harness !== "string") {
+    return { term: harness, iface: given ?? install(k, Object.keys(capabilities), capabilities) };
+  }
+  const out = k.elaborate(harness, capabilities);
+  if (out.kind !== "elaborated") throw new Error(`elaborate: ${JSON.stringify(out.problems)}`);
+  const iface =
+    given ??
+    install(
+      k,
+      out.uses.map((u) => [u.name, u.capability]),
+      capabilities,
+    );
+  return { term: out.harness, iface };
+}
+
+function install(k, uses, capabilities) {
+  const installed = k.install(
+    uses.map((u) => {
+      const [prefix, name] = Array.isArray(u) ? u : [u, u];
+      return { prefix, capability: capabilities[name] };
+    }),
+  );
+  if (installed.kind !== "installed") throw new Error(`install: ${JSON.stringify(installed)}`);
+  return installed.interface;
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.