@cleocode/cant 2026.9.18 → 2026.9.20

package/README.md

@@ -140,15 +140,38 @@ pnpm --filter @cleocode/cant test
 Tests use real `.cant` fixtures from `crates/cant-core/fixtures/` and
 seed agents from `packages/agents/seed-agents/`.
 
-## Rebuilding the napi binary
+## Native binaries and the WebAssembly fallback
+
+The published package bundles the cant-napi addon for every supported
+platform in `napi/` (T12382): native binaries for linux x64/arm64 (glibc and
+musl), darwin x64/arm64 and win32 x64/arm64, plus
+`cant.wasm32-wasi.wasm`, the same crate built for `wasm32-wasip1-threads`.
+The napi-rs generated loader (`napi/index.cjs`) uses the native binary for
+the host and falls back to the WebAssembly build automatically when none
+matches. `NAPI_RS_FORCE_WASI=error` forces the WebAssembly build (tests use
+it to prove the fallback). `cantAddonBackend()` reports which one loaded.
+
+Parsing, validation and profile extraction are identical on both backends
+(`tests/native-wasi-parity.test.ts`). One function differs:
+`cantExecutePipelineNative` needs the native backend, because pipelines spawn
+subprocesses through cant-runtime's multi-thread tokio runtime, which WASI
+cannot provide. Under WASI it resolves to `success: false` with an `error`
+saying so; it does not throw. Node prints a one-time
+`ExperimentalWarning: WASI is an experimental feature` to stderr when the
+WebAssembly build loads.
+
+To build locally (Rust toolchain required; nothing in `napi/` is committed):
 
 ```bash
-pnpm --filter @cleocode/cant build:napi
+pnpm --filter @cleocode/cant build:napi       # host native binary + loader
+# WebAssembly build: needs `rustup target add wasm32-wasip1-threads`, and
+# RUSTC must be a full path so napi-build can find crt1-reactor.o.
+RUSTC="$(rustup which rustc)" pnpm --filter @cleocode/cant build:napi:wasi
 ```
 
-Requires a Rust toolchain. Produces `napi/cant.linux-x64-gnu.node`.
-Other platform triples are added via the workspace release pipeline,
-not locally.
+CI builds all 9 artifacts in `.github/workflows/cant-napi-build.yml`, which
+the release calls; the release fails unless every triple is packed and
+stamped with the released commit.
 
 ## Crate track
 

package/dist/index.d.ts

@@ -12,8 +12,8 @@ export type { ConsolidateOptions, MentalModel, MentalModelObservation, MentalMod
 export { consolidate, createEmptyModel, harvestObservations, renderMentalModel, } from './mental-model.js';
 export type { ConvertedFile, MigrationOptions, MigrationResult, UnconvertedSection, } from './migrate/index';
 export { migrateMarkdown, serializeCantDocument, showDiff, showSummary } from './migrate/index';
-export type { AgentProfile, NativeDiagnostic, NativeParseDocumentResult, NativeParseError, NativeParseResult, NativePipelineResult, NativePipelineStep, NativeValidateResult, SeedPersonaId, } from './native-loader';
-export { cantClassifyDirectiveNative, cantExecutePipelineNative, cantExtractAgentProfilesNative, cantParseDocumentNative, cantParseNative, cantValidateDocumentNative, extractAgentProfilesTyped, extractAgentSkills, initWasm, isNativeAvailable, isWasmAvailable, loadSeedAgentIdentities, SEED_PERSONA_IDS, validateAgentCantPath, } from './native-loader';
+export type { AgentProfile, CantAddonBackend, NativeDiagnostic, NativeParseDocumentResult, NativeParseError, NativeParseResult, NativePipelineResult, NativePipelineStep, NativeValidateResult, SeedPersonaId, } from './native-loader';
+export { cantAddonBackend, cantAddonBuildInfo, cantClassifyDirectiveNative, cantExecutePipelineNative, cantExtractAgentProfilesNative, cantParseDocumentNative, cantParseNative, cantValidateDocumentNative, extractAgentProfilesTyped, extractAgentSkills, initWasm, isNativeAvailable, isWasmAvailable, loadSeedAgentIdentities, SEED_PERSONA_IDS, validateAgentCantPath, } from './native-loader';
 export type { ParsedCANTMessage } from './parse';
 export { initCantParser, parseCANTMessage } from './parse';
 export type { CantAgentV3, CantContextSourceDef, CantContractBlock, CantContractClause, CantMentalModelRef, CantOverflowStrategy, CantPathPermissions, CantTier, DirectiveType, } from './types';

package/dist/index.js

@@ -2,7 +2,7 @@
 // JIT Agent Composer (ULTRAPLAN Wave 5)
 // Wave 7a: BRAIN-backed ContextProvider (T432)
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isCantAgentV3 = exports.parseCANTMessage = exports.initCantParser = exports.validateAgentCantPath = exports.SEED_PERSONA_IDS = exports.loadSeedAgentIdentities = exports.isWasmAvailable = exports.isNativeAvailable = exports.initWasm = exports.extractAgentSkills = exports.extractAgentProfilesTyped = exports.cantValidateDocumentNative = exports.cantParseNative = exports.cantParseDocumentNative = exports.cantExtractAgentProfilesNative = exports.cantExecutePipelineNative = exports.cantClassifyDirectiveNative = exports.showSummary = exports.showDiff = exports.serializeCantDocument = exports.migrateMarkdown = exports.renderMentalModel = exports.harvestObservations = exports.createEmptyModel = exports.consolidate = exports.WORKER_FORBIDDEN_SPAWN_TOOLS = exports.validateSpawnRequest = exports.THIN_AGENT_TOOLS_STRIPPED = exports.stripSpawnToolsForWorker = exports.ORCHESTRATOR_FORBIDDEN_TOOLS = exports.LEAD_FORBIDDEN_TOOLS = exports.filterToolsForRole = exports.validateDocument = exports.parseDocument = exports.listSections = exports.executePipeline = exports.brainContextProvider = exports.TIER_CAPS = exports.estimateTokens = exports.escalateTier = exports.composeSpawnPayload = exports.toCantAgentV3 = exports.compileBundle = void 0;
+exports.isCantAgentV3 = exports.parseCANTMessage = exports.initCantParser = exports.validateAgentCantPath = exports.SEED_PERSONA_IDS = exports.loadSeedAgentIdentities = exports.isWasmAvailable = exports.isNativeAvailable = exports.initWasm = exports.extractAgentSkills = exports.extractAgentProfilesTyped = exports.cantValidateDocumentNative = exports.cantParseNative = exports.cantParseDocumentNative = exports.cantExtractAgentProfilesNative = exports.cantExecutePipelineNative = exports.cantClassifyDirectiveNative = exports.cantAddonBuildInfo = exports.cantAddonBackend = exports.showSummary = exports.showDiff = exports.serializeCantDocument = exports.migrateMarkdown = exports.renderMentalModel = exports.harvestObservations = exports.createEmptyModel = exports.consolidate = exports.WORKER_FORBIDDEN_SPAWN_TOOLS = exports.validateSpawnRequest = exports.THIN_AGENT_TOOLS_STRIPPED = exports.stripSpawnToolsForWorker = exports.ORCHESTRATOR_FORBIDDEN_TOOLS = exports.LEAD_FORBIDDEN_TOOLS = exports.filterToolsForRole = exports.validateDocument = exports.parseDocument = exports.listSections = exports.executePipeline = exports.brainContextProvider = exports.TIER_CAPS = exports.estimateTokens = exports.escalateTier = exports.composeSpawnPayload = exports.toCantAgentV3 = exports.compileBundle = void 0;
 // Bundle compiler
 var bundle_1 = require("./bundle");
 Object.defineProperty(exports, "compileBundle", { enumerable: true, get: function () { return bundle_1.compileBundle; } });
@@ -43,6 +43,8 @@ Object.defineProperty(exports, "showDiff", { enumerable: true, get: function ()
 Object.defineProperty(exports, "showSummary", { enumerable: true, get: function () { return index_1.showSummary; } });
 // Native loader (replaces wasm-loader)
 var native_loader_1 = require("./native-loader");
+Object.defineProperty(exports, "cantAddonBackend", { enumerable: true, get: function () { return native_loader_1.cantAddonBackend; } });
+Object.defineProperty(exports, "cantAddonBuildInfo", { enumerable: true, get: function () { return native_loader_1.cantAddonBuildInfo; } });
 Object.defineProperty(exports, "cantClassifyDirectiveNative", { enumerable: true, get: function () { return native_loader_1.cantClassifyDirectiveNative; } });
 Object.defineProperty(exports, "cantExecutePipelineNative", { enumerable: true, get: function () { return native_loader_1.cantExecutePipelineNative; } });
 Object.defineProperty(exports, "cantExtractAgentProfilesNative", { enumerable: true, get: function () { return native_loader_1.cantExtractAgentProfilesNative; } });

package/dist/native-loader.d.ts

@@ -1,14 +1,24 @@
 /**
- * Native addon loader for cant-core via napi-rs.
+ * Addon loader for cant-core via napi-rs.
  *
  * @remarks
- * Loads the napi-rs native addon synchronously on first use. Tries the
- * package-local binary first (`packages/cant/napi/cant.linux-x64-gnu.node`),
- * then falls back to the workspace `cant-napi` crate's `index.cjs` for
- * dev-mode builds where the package binary may not be present yet.
- *
- * Replaces the previous WASM loader. Follows the same pattern as
- * `packages/lafs/src/native-loader.ts`.
+ * Loads the cant-napi addon synchronously on first use through the napi-rs
+ * GENERATED loader shipped as `napi/index.cjs` (T12382). That loader tries a
+ * native binary for this OS/CPU first (`napi/cant.<triple>.node`, built for
+ * linux x64/arm64 gnu+musl, darwin x64/arm64 and win32 x64/arm64) and falls
+ * back automatically to the WebAssembly build of the same crate
+ * (`napi/cant.wasm32-wasi.wasm`, target `wasm32-wasip1-threads`) when no
+ * native binary matches. `NAPI_RS_FORCE_WASI=error` forces the WASI path.
+ *
+ * Both backends compile the same Rust source, so parse/validate/extract
+ * results are identical (proven by `tests/native-wasi-parity.test.ts`). The
+ * one difference is {@link cantExecutePipelineNative}: pipelines spawn
+ * subprocesses through cant-runtime's multi-thread tokio runtime, which WASI
+ * cannot provide, so under WASI it resolves to `success: false` with an
+ * `error` explaining why instead of running.
+ *
+ * In a source checkout, build the addon with
+ * `pnpm --filter @cleocode/cant build:napi` (and `build:napi:wasi`).
  */
 import type { PeerIdentity } from '@cleocode/contracts';
 /** Shape of a parsed CANT message returned by the native binding. */
@@ -107,11 +117,45 @@ export interface NativePipelineResult {
     error?: string | null;
 }
 /**
- * Check if the native addon is available.
+ * Which build of the cant-napi addon is serving calls.
+ *
+ * - `native` — a per-OS/CPU `.node` binary.
+ * - `wasi` — the `wasm32-wasip1-threads` WebAssembly fallback.
+ */
+export type CantAddonBackend = 'native' | 'wasi';
+/**
+ * Check if the cant-napi addon (native or WebAssembly) is available.
+ *
+ * @remarks
+ * The name predates the WASI fallback and is kept for compatibility: it is
+ * `true` when EITHER backend loaded. Use {@link cantAddonBackend} to tell
+ * which one.
  *
- * @returns `true` if the native Rust binding loaded successfully.
+ * @returns `true` if the Rust binding loaded successfully.
  */
 export declare function isNativeAvailable(): boolean;
+/**
+ * Report which backend of the cant-napi addon loaded.
+ *
+ * @returns `'native'` or `'wasi'`, or `null` when neither could be loaded.
+ *
+ * @example
+ * ```ts
+ * import { cantAddonBackend } from '@cleocode/cant';
+ *
+ * if (cantAddonBackend() === 'wasi') {
+ *   // pipelines cannot run here; parsing and validation still work
+ * }
+ * ```
+ */
+export declare function cantAddonBackend(): CantAddonBackend | null;
+/**
+ * Return the source-revision stamp compiled into the loaded addon, e.g.
+ * `"cant-napi-source-rev:<git sha>"` (`"…:unversioned"` for local builds).
+ *
+ * @returns The stamp, or `null` when the addon could not be loaded.
+ */
+export declare function cantAddonBuildInfo(): string | null;
 /**
  * Parse a CANT message using the native addon.
  *
@@ -226,6 +270,12 @@ export declare function validateAgentCantPath(cantPath: string, rootDir: string)
 /**
  * Execute a deterministic pipeline from a `.cant` file via the native addon.
  *
+ * @remarks
+ * Native backend only. Under the WebAssembly (WASI) fallback this resolves
+ * to `success: false` with an `error` explaining that pipelines need a native
+ * binary: they spawn subprocesses through cant-runtime's multi-thread tokio
+ * runtime, which WASI cannot provide. It never throws for that case.
+ *
  * @param filePath - Absolute or relative path to a `.cant` file.
  * @param pipelineName - The name of the `pipeline { ... }` block to run.
  */

package/dist/native-loader.js

@@ -1,19 +1,31 @@
 "use strict";
 /**
- * Native addon loader for cant-core via napi-rs.
+ * Addon loader for cant-core via napi-rs.
  *
  * @remarks
- * Loads the napi-rs native addon synchronously on first use. Tries the
- * package-local binary first (`packages/cant/napi/cant.linux-x64-gnu.node`),
- * then falls back to the workspace `cant-napi` crate's `index.cjs` for
- * dev-mode builds where the package binary may not be present yet.
- *
- * Replaces the previous WASM loader. Follows the same pattern as
- * `packages/lafs/src/native-loader.ts`.
+ * Loads the cant-napi addon synchronously on first use through the napi-rs
+ * GENERATED loader shipped as `napi/index.cjs` (T12382). That loader tries a
+ * native binary for this OS/CPU first (`napi/cant.<triple>.node`, built for
+ * linux x64/arm64 gnu+musl, darwin x64/arm64 and win32 x64/arm64) and falls
+ * back automatically to the WebAssembly build of the same crate
+ * (`napi/cant.wasm32-wasi.wasm`, target `wasm32-wasip1-threads`) when no
+ * native binary matches. `NAPI_RS_FORCE_WASI=error` forces the WASI path.
+ *
+ * Both backends compile the same Rust source, so parse/validate/extract
+ * results are identical (proven by `tests/native-wasi-parity.test.ts`). The
+ * one difference is {@link cantExecutePipelineNative}: pipelines spawn
+ * subprocesses through cant-runtime's multi-thread tokio runtime, which WASI
+ * cannot provide, so under WASI it resolves to `success: false` with an
+ * `error` explaining why instead of running.
+ *
+ * In a source checkout, build the addon with
+ * `pnpm --filter @cleocode/cant build:napi` (and `build:napi:wasi`).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.initWasm = exports.isWasmAvailable = exports.SEED_PERSONA_IDS = void 0;
 exports.isNativeAvailable = isNativeAvailable;
+exports.cantAddonBackend = cantAddonBackend;
+exports.cantAddonBuildInfo = cantAddonBuildInfo;
 exports.cantParseNative = cantParseNative;
 exports.cantClassifyDirectiveNative = cantClassifyDirectiveNative;
 exports.cantParseDocumentNative = cantParseDocumentNative;
@@ -29,65 +41,83 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 let nativeModule = null;
 let loadAttempted = false;
+let loadError = null;
 /**
- * Attempt to load the native addon. Called lazily on first use.
- * Native addons load synchronously via require() — no async init needed.
+ * Attempt to load the addon. Called lazily on first use.
+ * The generated loader is synchronous (native `require()`, or a synchronous
+ * WASI instantiation), so no async init is needed.
  */
 function ensureLoaded() {
     if (loadAttempted)
         return;
     loadAttempted = true;
-    // The compiled file lives at packages/cant/dist/native-loader.js, so
-    // ../napi resolves to packages/cant/napi/cant.<platform>.node.
-    const packageBinary = (0, node_path_1.join)(__dirname, '..', 'napi', `cant.${nativePlatformTriple()}.node`);
-    try {
-        nativeModule = require(packageBinary);
-        return;
-    }
-    catch {
-        // Fall through to workspace dev fallback.
-    }
+    // Both packages/cant/src/ (tests) and packages/cant/dist/ (built, installed)
+    // sit next to packages/cant/napi/, which holds the generated loader.
     try {
-        // Development fallback: load via the cant-napi crate's index.cjs.
-        // From packages/cant/dist/ -> ../../../crates/cant-napi/index.cjs.
-        nativeModule = require('../../../crates/cant-napi/index.cjs');
+        const binding = require((0, node_path_1.join)(__dirname, '..', 'napi', 'index.cjs'));
+        nativeModule = binding;
     }
-    catch {
+    catch (err) {
         nativeModule = null;
+        loadError = err instanceof Error ? err.message : String(err);
     }
 }
-/** Resolve the package-local napi-rs binary suffix for the current platform. */
-function nativePlatformTriple() {
-    if (process.platform === 'darwin') {
-        return process.arch === 'arm64' ? 'darwin-arm64' : 'darwin-x64';
-    }
-    if (process.platform === 'linux') {
-        return process.arch === 'arm64' ? 'linux-arm64-gnu' : 'linux-x64-gnu';
-    }
-    if (process.platform === 'win32') {
-        return process.arch === 'arm64' ? 'win32-arm64-msvc' : 'win32-x64-msvc';
-    }
-    return `${process.platform}-${process.arch}`;
-}
 /**
- * Check if the native addon is available.
+ * Check if the cant-napi addon (native or WebAssembly) is available.
+ *
+ * @remarks
+ * The name predates the WASI fallback and is kept for compatibility: it is
+ * `true` when EITHER backend loaded. Use {@link cantAddonBackend} to tell
+ * which one.
  *
- * @returns `true` if the native Rust binding loaded successfully.
+ * @returns `true` if the Rust binding loaded successfully.
  */
 function isNativeAvailable() {
     ensureLoaded();
     return nativeModule !== null;
 }
 /**
- * Get the native module, throwing if it failed to load.
+ * Report which backend of the cant-napi addon loaded.
+ *
+ * @returns `'native'` or `'wasi'`, or `null` when neither could be loaded.
+ *
+ * @example
+ * ```ts
+ * import { cantAddonBackend } from '@cleocode/cant';
+ *
+ * if (cantAddonBackend() === 'wasi') {
+ *   // pipelines cannot run here; parsing and validation still work
+ * }
+ * ```
+ */
+function cantAddonBackend() {
+    ensureLoaded();
+    if (!nativeModule)
+        return null;
+    return nativeModule.cantBackend() === 'wasi' ? 'wasi' : 'native';
+}
+/**
+ * Return the source-revision stamp compiled into the loaded addon, e.g.
+ * `"cant-napi-source-rev:<git sha>"` (`"…:unversioned"` for local builds).
+ *
+ * @returns The stamp, or `null` when the addon could not be loaded.
+ */
+function cantAddonBuildInfo() {
+    ensureLoaded();
+    return nativeModule ? nativeModule.cantBuildInfo() : null;
+}
+/**
+ * Get the addon module, throwing if it failed to load.
  *
  * @internal
- * @throws Error when the native addon could not be loaded.
+ * @throws Error when neither a native binary nor the WebAssembly fallback loaded.
  */
 function requireNative() {
     ensureLoaded();
     if (!nativeModule) {
-        throw new Error('cant-napi native addon not available. Build it with: cargo build --release -p cant-napi');
+        throw new Error(`CANT parser addon not available: no native binary for ${process.platform}-${process.arch} ` +
+            `loaded and the WebAssembly fallback did not load either (${loadError ?? 'no load error was recorded'}). ` +
+            'Reinstall @cleocode/cant; in a source checkout run: pnpm --filter @cleocode/cant build:napi');
     }
     return nativeModule;
 }
@@ -236,10 +266,16 @@ function validateAgentCantPath(cantPath, rootDir) {
 /**
  * Execute a deterministic pipeline from a `.cant` file via the native addon.
  *
+ * @remarks
+ * Native backend only. Under the WebAssembly (WASI) fallback this resolves
+ * to `success: false` with an `error` explaining that pipelines need a native
+ * binary: they spawn subprocesses through cant-runtime's multi-thread tokio
+ * runtime, which WASI cannot provide. It never throws for that case.
+ *
  * @param filePath - Absolute or relative path to a `.cant` file.
  * @param pipelineName - The name of the `pipeline { ... }` block to run.
  */
-function cantExecutePipelineNative(filePath, pipelineName) {
+async function cantExecutePipelineNative(filePath, pipelineName) {
     return requireNative().cantExecutePipeline(filePath, pipelineName);
 }
 // ============================================================================

package/dist/parse.js

@@ -73,7 +73,8 @@ function parseCANTMessage(content) {
     // in environments without the binary (CI matrix, edge runtimes) must
     // set CLEO_CANT_ALLOW_JS_FALLBACK=1 explicitly.
     if (process.env.CLEO_CANT_ALLOW_JS_FALLBACK !== '1') {
-        throw new Error('cant-core native addon not available. Build it with: cargo build --release -p cant-napi\n' +
+        throw new Error('cant-core addon not available (no native binary and no WebAssembly fallback). Reinstall ' +
+            '@cleocode/cant; in a source checkout run: pnpm --filter @cleocode/cant build:napi\n' +
             'Or set CLEO_CANT_ALLOW_JS_FALLBACK=1 to enable the degraded JS fallback parser.');
     }
     // Degraded JS fallback — header/body split with basic regex.