@staal/node 0.0.0-stage → 0.23.0

package/NOTICE

@@ -0,0 +1,5 @@
+Staal
+Copyright 2026 Laurels Ozy Echichinwo
+
+Licensed under the Apache License, Version 2.0, with the LLVM Exceptions; see LICENSE.
+"Staal" is a name of its owner and is not licensed: see section 6 of the License.

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# @staal/node: Staal for Node.js
 
-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.
+Run [Staal](https://github.com/laurells/staal) programs from Node.js and TypeScript.
+Staal is a programming language for software where AI acts: its compiler refuses a
+program that could act without permission, use a model's answer unchecked, or
+overspend, and its runtime never repeats an action after a crash.
+
+Install it with `npm install @staal/node`. This package holds no Staal logic of its own. It calls staalc's C interface
+in-process, so a Node app gets exactly the results `staalc` and the Python package
+give. Runs happen off the event loop and return Promises.
+
+```js
+const staal = require('@staal/node');
+
+// Your app decides the policy; Staal enforces it.
+const limit = customer.tier === 'gold' ? 500 : 50;
+const out = await staal.run('refund.staal', {
+  entry: 'main',
+  inputs: { complaint },
+  grants: { pay: { cap: 'payments.refund', each: { amount: String(limit), currency: 'USD' } } },
+  model: { provider: 'anthropic', model: 'claude-sonnet-5-5', api_key: { env: 'ANTHROPIC_API_KEY' } },
+}, { journal: 'refund.journal' });
+
+if (out.status === 'done') console.log(out.result);
+else if (out.status === 'failed') console.log('refused:', out.failure.message);
+```
+
+`run`, `resume`, `resolve` and `check` resolve to the JSON objects described in
+[include/staal.h](https://github.com/laurells/staal/blob/main/include/staal.h), typed
+in `index.d.ts`: `done` with a `result`, `failed` with a `failure`, `stopped` (an
+action in doubt: `resolve` it, then `resume`), `invalid` with located check errors,
+or `error`. Pass `{ engine: 'native' }` to run pure code as machine code.
+
+**Platforms.** Linux on x86_64 with glibc 2.28 or newer, Node 18 or newer. Other
+platforms come later; until then, build `node/` from the repository.
+
+**Licence.** Apache-2.0 WITH LLVM-exception. The addon contains staalc and its Rust
+dependencies, whose licences are in `LICENSE-THIRD-PARTY.txt`.

package/index.d.ts

@@ -0,0 +1,77 @@
+// Types for the staal package. Results are the JSON objects described in
+// include/staal.h, as returned by staalc.
+
+/** JSON as it crosses into and out of Staal. */
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+
+/** One event of a run's log (RUNTIME.md section 10). */
+export interface LogEvent {
+  event: string;
+  [field: string]: Json;
+}
+
+/** A check error, with where it is and the text staalc check prints. */
+export interface Diagnostic {
+  code: string;
+  file: string;
+  line: number;
+  col: number;
+  message: string;
+  text: string;
+}
+
+/** What made a run fail (RUNTIME.md section 8). */
+export type FailureKind =
+  | 'action'
+  | 'capability'
+  | 'validation'
+  | 'value'
+  | 'budget'
+  | 'provider'
+  | 'step_limit'
+  | 'depth_limit'
+  | 'internal'
+  | 'journal'
+  | 'in_doubt';
+
+export interface Failure {
+  kind: FailureKind;
+  message: string;
+}
+
+interface Ran {
+  log: LogEvent[];
+  /** Present when the run loaded C code, which Staal cannot check (RUNTIME.md section 19). */
+  unchecked?: Json[];
+}
+
+export type RunResult =
+  | (Ran & { status: 'done'; result: Json })
+  | (Ran & { status: 'failed'; failure: Failure })
+  /** Stopped and can continue: resolve the action in doubt, then resume. */
+  | (Ran & { status: 'stopped'; failure: Failure & { kind: 'in_doubt' | 'journal' } })
+  | { status: 'invalid'; errors: Diagnostic[] }
+  | { status: 'error'; error: string };
+
+export type CheckResult = { status: 'ok' } | { status: 'invalid'; errors: Diagnostic[] } | { status: 'error'; error: string };
+
+export type Resolution = { performed: string } | { status: number; body?: string } | { failed: string } | { retry: true };
+
+export type ResolveResult = { status: 'resolved'; summary: Json } | { status: 'error'; error: string };
+
+/** A run config (RUNTIME.md section 1): entry, inputs, grants, model and settings. */
+export type RunConfig = { [key: string]: Json };
+
+export interface RunOptions {
+  /** A journal file: the run survives a crash and can be resumed from it. */
+  journal?: string;
+  engine?: 'interpreter' | 'native';
+}
+
+/** staalc's version, for example "0.23.0". */
+export const version: string;
+
+export function check(program: string): Promise<CheckResult>;
+export function run(program: string, config: RunConfig, options?: RunOptions): Promise<RunResult>;
+export function resume(program: string, config: RunConfig, journal: string, options?: Pick<RunOptions, 'engine'>): Promise<RunResult>;
+export function resolve(journal: string, resolution: Resolution): Promise<ResolveResult>;

package/index.js

@@ -0,0 +1,80 @@
+'use strict';
+// Run Staal programs from Node.js, through Staal's C interface (libstaalc).
+//
+// This package holds no Staal logic: it passes strings to staalc and parses the JSON
+// it returns, exactly as the C interface (include/staal.h) and the Python package do.
+//
+//   const staal = require('@staal/node');
+//   const out = await staal.run('refund.staal', config, { journal: 'run.journal' });
+//   if (out.status === 'done') console.log(out.result);
+
+const fs = require('fs');
+const path = require('path');
+
+function platformDir() {
+  if (process.platform === 'linux') {
+    // The build links against glibc; musl systems (Alpine) cannot load it.
+    const report = typeof process.report?.getReport === 'function' ? process.report.getReport() : null;
+    const glibc = report && report.header && report.header.glibcVersionRuntime;
+    return glibc ? `linux-${process.arch}-gnu` : `linux-${process.arch}-musl`;
+  }
+  return `${process.platform}-${process.arch}`;
+}
+
+function load() {
+  const override = process.env.STAAL_NODE_ADDON;
+  const file = override || path.join(__dirname, 'bin', platformDir(), 'staal.node');
+  if (!fs.existsSync(file)) {
+    throw new Error(
+      `staal: this package has no build for ${platformDir()} yet (looked for ${file}). ` +
+        'Builds exist for linux-x64-gnu; elsewhere, build node/ from https://github.com/laurells/staal',
+    );
+  }
+  return require(file);
+}
+
+const addon = load();
+
+function parse(text) {
+  return JSON.parse(text);
+}
+
+function str(value, name) {
+  if (typeof value !== 'string') throw new TypeError(`staal: ${name} must be a string`);
+  return value;
+}
+
+function engineOf(options) {
+  const engine = options && options.engine;
+  return engine === undefined || engine === null ? undefined : str(engine, 'engine');
+}
+
+/** staalc's version, for example "0.23.0". */
+const version = addon.version();
+
+/** Checks a program without running it. */
+async function check(program) {
+  return parse(await addon.check(str(program, 'program')));
+}
+
+/** Runs a program. `config` is the run config, as an object. */
+async function run(program, config, options = {}) {
+  const journal = options.journal === undefined || options.journal === null ? undefined : str(options.journal, 'journal');
+  return parse(await addon.run(str(program, 'program'), JSON.stringify(config), journal, engineOf(options)));
+}
+
+/** Resumes a run from its journal: finished actions are replayed, not made again. */
+async function resume(program, config, journal, options = {}) {
+  return parse(await addon.resume(str(program, 'program'), JSON.stringify(config), str(journal, 'journal'), engineOf(options)));
+}
+
+/**
+ * Resolves the action in doubt in a stopped run's journal, then call `resume`.
+ * `resolution` is one of { performed: "<receipt>" }, { status: 200, body: "..." },
+ * { failed: "<reason>" } or { retry: true }.
+ */
+async function resolve(journal, resolution) {
+  return parse(await addon.resolve(str(journal, 'journal'), JSON.stringify(resolution)));
+}
+
+module.exports = { version, check, run, resume, resolve };

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@staal/node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.23.0",
+  "description": "Run Staal programs from Node.js: the staalc compiler and runtime, through its C interface",
+  "license": "Apache-2.0 WITH LLVM-exception",
+  "homepage": "https://laurells.github.io/staal/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/laurells/staal.git",
+    "directory": "node"
+  },
+  "bugs": "https://github.com/laurells/staal/issues",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "bin/",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "LICENSE-THIRD-PARTY.txt"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "linux"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "libc": [
+    "glibc"
+  ],
+  "scripts": {
+    "test": "node --test test/staal.test.mjs",
+    "types": "tsc --noEmit -p test/tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/node": "22.10.2",
+    "typescript": "5.7.2"
+  }
+}