@maligator/cli 0.1.0-alpha.26 → 0.1.0-alpha.28

package/README.md

@@ -38,7 +38,7 @@ maligator run -- first-argument "two words"
 
 `maligator init` creates `maligator.build.ts`. If it cannot find an existing entry
 point, it also creates `src/index.ts`. `doctor` checks the native build toolchain,
-`build` produces a development executable, and `run` builds and launches it while
+`build` produces a development executable, and `run` compiles a development image and executes it while
 forwarding everything after `--` to the application.
 
 Useful commands:
@@ -64,200 +64,31 @@ native toolchain. `dev` retains compiler identities between edits and restarts a
 application VM after every successful rebuild. Build failures keep the watcher alive
 for recovery on the next edit.
 
-## Testing
-
-`maligator test` discovers conventional JavaScript and erasable-TypeScript test
-files and runs them through Maligator's embedded interpreter. Test runs do not
-generate C or invoke the native toolchain. Import the Maligator-owned API from
-`maligator:test`:
-
-```typescript
-import { beforeEach, describe, expect, test } from "maligator:test";
-import { createRouter, RouteError, type Router } from "./router.ts";
-
-describe("router", () => {
-	let router: Router;
-
-	beforeEach(() => {
-		router = createRouter();
-	});
-
-	test("matches parameters", async () => {
-		await expect(router.match("/users/42")).resolves.toMatchObject({
-			id: expect.any(Number),
-		});
-	});
-
-	test("rejects malformed parameters", async () => {
-		await expect(router.match("/users/nope")).rejects.toThrow(RouteError);
-	});
-});
-```
-
-By default, discovery includes `*.test.js`, `*.test.mjs`, `*.test.ts`,
-`*.test.mts`, and the corresponding `*.spec.*` names. Pass files, directories,
-or both:
-
-```shell
-maligator test
-maligator test src/router
-maligator test src/router/router.test.ts
-maligator test --run "router > parameters"
-maligator test --shuffle
-maligator test --shuffle 18492
-maligator test --repeat 10
-maligator test --bail
-```
-
-`--run` filters hierarchical suite and test names. `--shuffle [seed]` changes
-execution order reproducibly and always prints the seed. `--repeat` executes the
-selected tests again while reusing unchanged compilation artifacts. The default
-policy completes the selected suite; `--bail` stops scheduling after the first
-failure.
-
-The authoring API includes nested `describe` suites, `beforeAll`, `afterAll`,
-`beforeEach`, `afterEach`, synchronous and promise-returning callbacks,
-`test.skip`, `test.todo`, `test.only`, and `test.each`. A committed `.only`
-focuses execution and prints a warning. Matchers include identity, structural
-equality, truthiness, containment, length, string/regular-expression matching,
-partial-object matching, throwing, `.not`, `.resolves`, `.rejects`, and the
-`expect.any`, `expect.anything`, `expect.stringMatching`,
-`expect.objectContaining`, and `expect.arrayContaining` asymmetric helpers.
-Maligator owns this API and does not claim Jest, Vitest, or `node:test`
-compatibility.
-
-Test files currently execute serially in one Realm. Registration and lifecycle
-state are separated by test file, but globals, prototypes, imported module
-singletons, host state, and asynchronous work left running by a test can be
-shared. Do not rely on process-per-file isolation.
-
-Frontend bytecode is content-addressed by source, transitive dependencies,
-resolved module identities, relevant build configuration, and compiler/runtime
-format versions. A warm run restores a shared base plus independently cached
-test-file registration fragments. Test results are never cached: every selected
-test executes on every invocation.
-
-The package ships documented declarations for `maligator:test`. Projects whose
-TypeScript configuration does not include `maligator.build.ts` should load the
-package declarations explicitly:
-
-```json
-{
-	"compilerOptions": {
-		"types": ["@maligator/cli"]
-	}
-}
-```
-
-## Build cache
-
-Normal `maligator build`, `maligator run`, and `maligator test` commands share a
-content-addressed portable VM definition store. On a valid hit, Maligator skips
-parsing, module-graph construction, semantic analysis, optimization, register
-allocation, and VM lowering. For supported Intl-disabled development profiles, `run`
-executes the restored definition with a matching compile-time-specialized runtime
-embedded in the platform CLI; it does not generate C or invoke a native toolchain.
-Normal and production `build` commands emit
-native translation units from the same restored definition. Those units and the native driver are
-compiled into independently content-addressed objects, so unchanged objects can
-be relinked without repeating C compilation. The final link still runs, and
-native runtime and Rust archives remain separately content-addressed. Runtime C
-objects use their preprocessed input as the feature projection, while distinct
-Rust feature archives share Cargo dependency work. Output executables remain
-statically linked and self-contained.
-
-Build cache invalidation includes source and transitive dependency content,
-package-resolution metadata, relevant configuration, the TypeScript erasure
-frontend, and compiler/wire versions. Generated-object identity additionally
-includes the exact C source, source identity, native headers/runtime artifact,
-compiler/toolchain, target, flags, and build environment. Compiler diagnostic
-dump flags deliberately recompile the frontend because they require live
-semantic and IR objects.
-
-## Production builds
-
-Use production mode for a deployable binary:
-
-```shell
-maligator build --production
-```
-
-Production builds use optimized native compilation, add LTO when the toolchain
-supports it, and strip native symbols when possible. To create a self-contained
-artifact directory with a manifest, license, checksum, and binary:
-
-```shell
-maligator build --production --artifact dist/my-application
-```
-
-The artifact destination must be absent or empty. Launch the reported binary
-directly; neither Node.js nor the Maligator CLI is needed at runtime.
-
-## Configuration
-
-`maligator.build.ts` is trusted TypeScript configuration. A small configuration
-looks like this:
-
-```typescript
-import { defineBuild } from "@maligator/cli";
-
-export default defineBuild({
-	entry: "src/index.ts",
-	outputName: "my-application",
-	engine: {
-		eval: false,
-		intl: { enabled: false },
-	},
-	surface: {
-		webPlatform: false,
-		node: false,
-	},
-});
-```
-
-All fields are optional. Maligator excludes optional engine and host surfaces unless
-the configuration requests them. See the
-[full configuration reference](https://github.com/dirkdev98/maligator#configuration)
-for assets, Intl features, Node compatibility, web-platform support, and target
-selection.
-
-## TypeScript
-
-The package includes declarations for `maligator.build.ts` and Maligator's runtime
-globals. Keeping the generated build file inside your TypeScript project makes the
-types available automatically:
-
-```typescript
-const path = mal.assets.materialize("templates", {
-	baseDirectory: ".cache/my-application",
-});
-
-const server = Mal.serve({
-	hostname: "127.0.0.1",
-	port: 3000,
-	async fetch(request) {
-		return new Response(`Hello from ${request.url}`);
-	},
-});
-
-console.log(path, server.port);
-```
-
-`mal` is present when `surface.maligator` is enabled. `Mal` and `Mal.serve` are
-present when `surface.webPlatform` is enabled. The declarations describe both
-optional surfaces, while `maligator.build.ts` controls which globals exist in the
-compiled application.
-
-If your `tsconfig.json` excludes `maligator.build.ts`, load the declarations
-explicitly:
-
-```json
-{
-	"compilerOptions": {
-		"types": ["@maligator/cli"]
-	}
-}
-```
+## Documentation
+
+Use the [guides](https://maligator.ddv.tools/guides) for application workflows and
+the [API reference](https://maligator.ddv.tools/api) for exact contracts.
+
+- [Getting started](https://maligator.ddv.tools/guides/getting-started)
+- [Development](https://maligator.ddv.tools/guides/development) and
+  [TypeScript](https://maligator.ddv.tools/guides/typescript)
+- [Application testing](https://maligator.ddv.tools/guides/testing)
+- [Workers](https://maligator.ddv.tools/guides/workers)
+- [Build configuration](https://maligator.ddv.tools/guides/build-configuration)
+- [Embedded files](https://maligator.ddv.tools/guides/assets) and
+  [HTTP](https://maligator.ddv.tools/guides/http)
+- [Production](https://maligator.ddv.tools/guides/production) and
+  [profiling](https://maligator.ddv.tools/guides/profiling)
+- [CLI commands and flags](https://maligator.ddv.tools/api/cli)
+
+The package ships types for configuration, runtime globals, and public `maligator:`
+modules. Include `@maligator/cli` in `compilerOptions.types` when your TypeScript
+project excludes the build file. Declarations do not enable optional runtime surfaces;
+choose those in `maligator.build.ts`.
+
+Every page has a Markdown counterpart. The
+[public symbol index](https://maligator.ddv.tools/reference.json) provides signatures,
+defaults, availability, and direct links.
 
 ## Build toolchain
 

package/application-api.d.ts

@@ -0,0 +1,23 @@
+// Generated from src/platform/catalog.ts; edit the catalog and regenerate.
+/**
+ * Runtime lifecycle notifications for supervised applications. Module evaluation and
+ * application readiness are separate events; readiness means the application has
+ * finished its own startup work.
+ */
+declare module "maligator:application" {
+	/**
+	 * Notify the development supervisor that this application is ready. Repeated calls
+	 * are harmless. Returns true in a supervised application and false in a standalone
+	 * application or ordinary worker. Call after resources such as a server listener are
+	 * accepting work; this does not reserve ports or transfer traffic.
+	 *
+	 * @example
+	 * import { ready } from "maligator:application";
+	 * import { createServer } from "node:http";
+	 *
+	 * createServer((_request, response) => response.end("hello")).listen(3000, () => ready());
+	 *
+	 * @see https://maligator.ddv.tools/api/application#ready
+	 */
+	export const ready: () => boolean;
+}

package/index.d.ts

@@ -2,6 +2,7 @@
 
 import "./platform-api.d.ts";
 
+/** Service selections used when Intl is enabled; an empty list includes every service. */
 export type MaligatorIntlFeature =
 	| "collator"
 	| "number-format"
@@ -13,56 +14,106 @@ export type MaligatorIntlFeature =
 	| "relative-time-format"
 	| "duration-format";
 
+/**
+ * Capture a regular file or a directory tree at build time. Paths are relative to
+ * the project root. Directory patterns support *, ?, and whole-segment **;
+ * every pattern must match a regular file. Symlinks are rejected.
+ * @see https://maligator.ddv.tools/api/build#AssetInclusion
+ */
 export type AssetInclusion =
 	| { type: "file"; path: string }
 	| { type: "directory"; path: string; include: Array<string> };
 
+/** Trusted, strictly validated configuration evaluated for each CLI invocation.
+ * @see https://maligator.ddv.tools/guides/build-configuration
+ */
 export interface MaligatorBuildConfig {
+	/** Project-root-relative entry; an explicit CLI entry takes precedence. */
 	entry?: string;
+	/** Binary name; otherwise inferred from the unscoped package name or project directory. */
 	outputName?: string;
+	/** Named build-time snapshots. Requires surface.maligator; portable serialized images cannot carry these filesystem resources. */
 	assets?: Record<string, AssetInclusion>;
 	modules?: {
-		/** Exact specifier replacements applied before module resolution. */
+		/** Exact specifier replacements applied before module resolution. Defaults to an empty map. */
 		aliases?: Record<string, string>;
 	};
 	engine?: {
-		/**
-		 * Lock ECMAScript primordials for this entire build. Locked is the default;
-		 * mutable is intended for conformance suites and compatibility experiments.
+		/** Lock built-in objects for the entire build. Mutable is intended for compatibility experiments.
+		 * @default "locked"
 		 */
 		primordials?: "locked" | "mutable";
-		/**
-		 * `true` embeds the runtime compiler. `false` keeps eval/Function present
-		 * but makes dynamic compilation throw at runtime. `"compile-check"` also
-		 * rejects statically visible eval/Function calls during the build.
+		/** Control dynamic compilation. false leaves eval/Function present but makes calls throw;
+		 * true embeds the compiler; compile-check also rejects statically visible calls at build time.
+		 * @default false
+		 * @see https://maligator.ddv.tools/api/build#engine.eval
 		 */
 		eval?: boolean | "compile-check";
+		/** Include Realm support.
+		 * @default false
+		 */
 		realms?: boolean;
+		/** Include RegExp; disabling it trades compatibility for binary size.
+		 * @default true
+		 */
 		regexp?: boolean;
-		/** Include the Temporal global and its calendar/time-zone data. */
+		/** Include Temporal and its calendar/time-zone data.
+		 * @default false
+		 */
 		temporal?: boolean;
 		intl?: {
+			/** Include internationalization services and their native data.
+			 * @default false
+			 */
 			enabled?: boolean;
+			/** Select services. An empty list includes all services when enabled.
+			 * @default []
+			 */
 			features?: Array<MaligatorIntlFeature>;
+			/** Locale-data filtering is not implemented; only an empty list is accepted.
+			 * @default []
+			 */
 			languages?: Array<string>;
 		};
 	};
 	surface?: {
+		/** Include Web APIs and Mal.serve. Declarations alone do not enable them.
+		 * @default false
+		 */
 		webPlatform?: boolean;
+		/** Include supported node: modules; see the compatibility table for coverage.
+		 * @default false
+		 */
 		node?: boolean;
+		/** Include the mal namespace. Required for configured assets.
+		 * @default true
+		 */
 		maligator?: boolean;
 	};
 }
 
+/** Preserve the inferred config type. Validation happens when the CLI loads the config.
+ * @example
+ * import { defineBuild } from "@maligator/cli";
+ * export default defineBuild({ entry: "src/index.ts" });
+ * @see https://maligator.ddv.tools/api/build#defineBuild
+ */
 export declare function defineBuild<const Config extends MaligatorBuildConfig>(
 	config: Config,
 ): Config;
 
 export interface MaligatorMaterializeOptions {
+	/** Parent directory for the content-addressed materialization. Defaults to the OS temporary directory. */
 	baseDirectory?: string;
 }
 
 export interface MaligatorAssets {
+	/**
+	 * Atomically write a named snapshot and return its absolute file/directory path.
+	 * Completed materializations are reused by content identity. Unknown names,
+	 * invalid options, and filesystem failures throw synchronously.
+	 * @see https://maligator.ddv.tools/api/runtime#mal.assets.materialize
+	 */
 	materialize(name: string, options?: MaligatorMaterializeOptions): string;
 }
 
@@ -71,29 +122,47 @@ export interface MaligatorRuntime {
 }
 
 export interface MaligatorServeOptions {
+	/** Bind address. Defaults to 0.0.0.0; use 127.0.0.1 for a local-only listener. */
 	hostname?: string;
+	/** TCP port, 0 through 65535. Defaults to 0, which asks the OS to choose a port. */
 	port?: number;
+	/** Handle a request with a Response or an awaited response. */
 	fetch(request: Request): Response | PromiseLike<Response>;
+	/** Header deadline in milliseconds; 0 also selects the default. Integer 0..2147483647.
+	 * @default 60000 */
+	headersTimeout?: number;
+	/** Request deadline in milliseconds; 0 also selects the default. Integer 0..2147483647.
+	 * @default 300000 */
+	requestTimeout?: number;
+	/** Idle keep-alive deadline in milliseconds; 0 also selects the default. Integer 0..2147483647.
+	 * @default 5000 */
+	keepAliveTimeout?: number;
+	/** Concurrent connection limit; 0 also selects the default. Integer 0..2147483647.
+	 * @default 1024 */
+	maxConnections?: number;
 }
 
 export interface MaligatorServer {
+	/** Actual bound port, including an OS-selected port when the requested port was 0. */
 	readonly port: number;
 }
 
 export interface MaligatorWebRuntime {
+	/**
+	 * Start an HTTP listener. Requires surface.webPlatform. The current handle exposes
+	 * its bound port; it has no public stop method. Invalid timeout/connection limits throw.
+	 * @see https://maligator.ddv.tools/api/runtime#Mal.serve
+	 */
 	serve(options: MaligatorServeOptions): MaligatorServer;
 }
 
 declare global {
-	/**
-	 * Maligator's core runtime namespace. Present when
-	 * `surface.maligator` is enabled.
+	/** Core namespace, available when surface.maligator is enabled.
+	 * @see https://maligator.ddv.tools/api/runtime#mal
 	 */
 	var mal: MaligatorRuntime;
-
-	/**
-	 * Maligator's web-host extension namespace. Present when
-	 * `surface.webPlatform` is enabled.
+	/** Web host namespace, available when surface.webPlatform is enabled.
+	 * @see https://maligator.ddv.tools/api/runtime#Mal
 	 */
 	var Mal: MaligatorWebRuntime;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@maligator/cli",
-	"version": "0.1.0-alpha.26",
+	"version": "0.1.0-alpha.28",
 	"description": "Ahead-of-time JavaScript compiler and native runtime",
 	"license": "MIT",
 	"homepage": "https://github.com/dirkdev98/maligator#readme",
@@ -31,8 +31,11 @@
 		"index.js",
 		"index.d.ts",
 		"platform-api.d.ts",
+		"application-api.d.ts",
 		"process-api.d.ts",
 		"test-api.d.ts",
+		"workers-api.d.ts",
+		"workers-host-api.d.ts",
 		"README.md",
 		"LICENSE"
 	],
@@ -47,6 +50,9 @@
 		}
 	},
 	"optionalDependencies": {
-		"@maligator/cli-darwin-arm64": "0.1.0-alpha.26"
+		"@maligator/cli-darwin-arm64": "0.1.0-alpha.28",
+		"@maligator/cli-darwin-x64": "0.1.0-alpha.28",
+		"@maligator/cli-linux-arm64": "0.1.0-alpha.28",
+		"@maligator/cli-linux-x64": "0.1.0-alpha.28"
 	}
 }

package/platform-api.d.ts

@@ -1,3 +1,6 @@
 // Generated from src/platform/catalog.ts; edit the catalog and regenerate.
+import "./application-api.d.ts";
+import "./workers-api.d.ts";
+import "./workers-host-api.d.ts";
 import "./process-api.d.ts";
 import "./test-api.d.ts";

package/process-api.d.ts

@@ -1,20 +1,23 @@
 // Generated from src/platform/catalog.ts; edit the catalog and regenerate.
 /**
- * Application execution context. Importing this module has no externally observable
- * effects and requires no configuration switch. Unused exports and native
- * implementation dependencies are eliminated. Process arguments, environment, working
- * directory, and PID are runtime concerns outside execution.
+ * Read the compile-time command, target, and resolved application configuration. No
+ * surface flag is required. Runtime arguments, environment, working directory, and
+ * PID are separate process values.
  */
 declare module "maligator:process" {
 	/**
 	 * Profiling instrumentation: none by default; sampling for --profile; compiler for
 	 * --profile=compiler. Both profiling modes select full optimization without
 	 * selecting production application behavior.
+	 *
+	 * @see https://maligator.ddv.tools/api/process#ExecutionProfile
 	 */
 	export type ExecutionProfile = "none" | "sampling" | "compiler";
 
 	/**
 	 * The fixed platform contract of the application image.
+	 *
+	 * @see https://maligator.ddv.tools/api/process#ExecutionTarget
 	 */
 	export type ExecutionTarget = {
 		/**
@@ -36,6 +39,8 @@ declare module "maligator:process" {
 	/**
 	 * Options shared by build, run, and dev. Output paths, verbosity, and compiler
 	 * scheduling are tool settings and are not exposed.
+	 *
+	 * @see https://maligator.ddv.tools/api/process#ExecutionOptions
 	 */
 	export type ExecutionOptions = {
 		/**
@@ -48,6 +53,8 @@ declare module "maligator:process" {
 	/**
 	 * Normalized test settings, fixed for the application image. Changing these values
 	 * invalidates specialized test artifacts.
+	 *
+	 * @see https://maligator.ddv.tools/api/process#TestExecutionOptions
 	 */
 	export type TestExecutionOptions = {
 		/**
@@ -70,8 +77,7 @@ declare module "maligator:process" {
 		 */
 		readonly bail: boolean;
 		/**
-		 * Default test timeout in milliseconds from --timeout. Defaults to 5000; individual
-		 * test APIs can select a different timeout.
+		 * Test callback timeout in milliseconds from --timeout. Defaults to 5000.
 		 */
 		readonly timeoutMs: number;
 		/**
@@ -85,6 +91,8 @@ declare module "maligator:process" {
 	/**
 	 * Resolved engine policies. These describe build inputs, never post-DCE native
 	 * feature inclusion.
+	 *
+	 * @see https://maligator.ddv.tools/api/process#ExecutionEngineConfig
 	 */
 	export type ExecutionEngineConfig = {
 		/**
@@ -133,9 +141,10 @@ declare module "maligator:process" {
 	};
 
 	/**
-	 * Public application policies from the selected build configuration. Excludes
-	 * build-host paths, asset declarations, output controls, and the obsolete Maligator
-	 * surface switch.
+	 * Resolved application engine, Web/Node surface, and module policies. Excludes
+	 * build-host paths, asset declarations, and output controls.
+	 *
+	 * @see https://maligator.ddv.tools/api/process#ExecutionConfig
 	 */
 	export type ExecutionConfig = {
 		/**
@@ -173,6 +182,8 @@ declare module "maligator:process" {
 	/**
 	 * Fields shared by every execution workflow. All nested objects and arrays are
 	 * deeply frozen at runtime.
+	 *
+	 * @see https://maligator.ddv.tools/api/process#ExecutionCommon
 	 */
 	export type ExecutionCommon = {
 		/**
@@ -208,6 +219,8 @@ declare module "maligator:process" {
 	/**
 	 * An immutable application-image description, discriminated by command. The command
 	 * describes the workflow that prepared the image, not a transient process phase.
+	 *
+	 * @see https://maligator.ddv.tools/api/process#Execution
 	 */
 	export type Execution = ExecutionCommon &
 		(
@@ -249,16 +262,11 @@ declare module "maligator:process" {
 		);
 
 	/**
-	 * The canonical execution description, fixed before application compilation. Reads
-	 * of known own properties, import aliases and re-exports, immutable aliases and
-	 * destructuring, primitive comparisons, boolean expressions, and if/switch branches
-	 * specialize in development and full compilation. Dynamic keys and opaque calls
-	 * remain ordinary JavaScript and may retain the runtime object. The snapshot has
-	 * stable identity within an application context and deeply frozen own data
-	 * properties; reflection sees the complete shape. Static and dynamic imports return
-	 * the same export. A different command, option, configuration, target, or backend
-	 * creates a different compilation context. Profiling does not change production
-	 * intent. Importing the module does not keep unused native code alive.
+	 * An immutable snapshot of the workflow, target, and resolved configuration, fixed
+	 * before compilation. Known property reads can specialize application branches.
+	 * Runtime arguments, environment, working directory, and PID are outside this
+	 * snapshot. Profiling does not change production intent. Static and dynamic imports
+	 * share its identity, and reflection sees the complete deeply frozen shape.
 	 *
 	 * @example
 	 * import { execution } from "maligator:process";
@@ -267,12 +275,7 @@ declare module "maligator:process" {
 	 *   console.log("native production application");
 	 * }
 	 *
-	 * @example
-	 * import { execution } from "maligator:process";
-	 *
-	 * if (execution.command === "test") {
-	 *   console.log(execution.options.repeat);
-	 * }
+	 * @see https://maligator.ddv.tools/api/process#execution
 	 */
 	export const execution: Execution;
 }

package/test-api.d.ts

@@ -9,16 +9,22 @@ declare module "maligator:test" {
 	/**
 	 * A test or hook body. Maligator waits for a returned promise or thenable before
 	 * advancing the lifecycle.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#TestCallback
 	 */
 	export type TestCallback = () => unknown;
 
 	/**
 	 * A lifecycle hook body, with the same async completion contract as a test.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#HookCallback
 	 */
 	export type HookCallback = TestCallback;
 
 	/**
 	 * A constructable value accepted by {@link expect.any}.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#Constructor
 	 */
 	export type Constructor = abstract new (...args: Array<never>) => unknown;
 
@@ -26,6 +32,8 @@ declare module "maligator:test" {
 	 * Opaque partial-match value produced by helpers such as {@link
 	 * expect.objectContaining}. It may be nested inside `toEqual`, `toStrictEqual`, and
 	 * `toMatchObject` expectations.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#AsymmetricMatcher
 	 */
 	export type AsymmetricMatcher = {
 		readonly __maligator_asymmetric__: string;
@@ -33,6 +41,8 @@ declare module "maligator:test" {
 
 	/**
 	 * Matchers for a synchronously received value.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#Matchers
 	 */
 	export type Matchers = {
 		/** Negate the following matcher. */
@@ -86,6 +96,8 @@ declare module "maligator:test" {
 	 * Promise-returning matcher surface exposed by {@link Matchers.resolves} and {@link
 	 * Matchers.rejects}. Await these calls so the test cannot finish before the
 	 * assertion.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#AsyncMatchers
 	 */
 	export type AsyncMatchers = {
 		/** Negate the following asynchronous matcher. */
@@ -113,6 +125,8 @@ declare module "maligator:test" {
 
 	/**
 	 * Assertion entrypoint and Maligator-owned asymmetric matcher factories.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#ExpectFunction
 	 */
 	export type ExpectFunction = {
 		/** Create matchers for `received`. The assertion position is captured here. */
@@ -131,6 +145,8 @@ declare module "maligator:test" {
 
 	/**
 	 * Register tests in the current suite during module evaluation.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#TestFunction
 	 */
 	export type TestFunction = {
 		/** Register a test. Returned promises are awaited by the runner. */
@@ -155,6 +171,8 @@ declare module "maligator:test" {
 
 	/**
 	 * Register nested suites synchronously during module evaluation.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#DescribeFunction
 	 */
 	export type DescribeFunction = {
 		/** Register a suite. Suite callbacks must not return a promise. */
@@ -167,32 +185,46 @@ declare module "maligator:test" {
 
 	/**
 	 * Register a test in the current suite.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#test
 	 */
 	export const test: TestFunction;
 	/**
 	 * Register a nested suite in the current suite.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#describe
 	 */
 	export const describe: DescribeFunction;
 	/**
 	 * Create fluent matchers for a received value.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#expect
 	 */
 	export const expect: ExpectFunction;
 	/**
 	 * Run once before tests in the current suite.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#beforeAll
 	 */
 	export const beforeAll: (callback: HookCallback) => void;
 	/**
 	 * Run once after tests in the current suite, including after test failures.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#afterAll
 	 */
 	export const afterAll: (callback: HookCallback) => void;
 	/**
 	 * Run before every selected descendant test. Ancestor hooks run before hooks
 	 * declared by a nested suite.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#beforeEach
 	 */
 	export const beforeEach: (callback: HookCallback) => void;
 	/**
 	 * Run after every selected descendant test. Nested-suite hooks run before ancestor
 	 * hooks.
+	 *
+	 * @see https://maligator.ddv.tools/api/test#afterEach
 	 */
 	export const afterEach: (callback: HookCallback) => void;
 }

package/workers-api.d.ts

@@ -0,0 +1,445 @@
+// Generated from src/platform/catalog.ts; edit the catalog and regenerate.
+/**
+ * Parallel computation and isolated event loops. Declared entries are bundled into
+ * the application image; workers do not compile or load source files at runtime.
+ * Native executors and GC helpers are shared across JavaScript isolates.
+ */
+declare module "maligator:workers" {
+	/**
+	 * An immutable image-local worker entry declaration. The compiler resolves the
+	 * declaration independently of how libraries pass the descriptor or its href onward.
+	 * Erased module types express the caller's assertion; runtime entry identity is
+	 * validated.
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#WorkerUrl
+	 */
+	export type WorkerUrl<Module = unknown> = {
+		readonly href: string;
+		readonly __workerModule?: Module;
+	};
+
+	/**
+	 * ArrayBuffer stores move at admission. MessagePort endpoints transfer ownership.
+	 * SharedArrayBuffer is cloned by sharing its backing and cannot be transferred.
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#Transferable
+	 */
+	export type Transferable = ArrayBuffer | MessagePort;
+
+	/**
+	 * Cancellation is cooperative while a pool task runs. The worker remains occupied
+	 * until the task's returned promise settles.
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#TaskContext
+	 */
+	export type TaskContext = {
+		/** Worker-local cancellation signal. Cancellation does not preempt JavaScript. */
+		readonly signal: AbortSignal;
+		/** Throws if cancelled. Check between bounded pieces of work. */
+		throwIfCancelled(): void;
+	};
+
+	/**
+	 * An opaque result envelope. Constructing it does not detach buffers; publication
+	 * commits transfers.
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#TransferResult
+	 */
+	export type TransferResult<Value> = {
+		readonly value: Value;
+		readonly __transferResult: unique symbol;
+	};
+
+	/**
+	 * Names of context-first exported task functions.
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#TaskNames
+	 */
+	export type TaskNames<Module> = {
+		[Key in keyof Module]-?: Module[Key] extends (
+			context: TaskContext,
+			...args: infer Args
+		) => unknown
+			? Key
+			: never;
+	}[keyof Module] &
+		string;
+
+	/**
+	 * The task's argument tuple, excluding its local cancellation context.
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#TaskArgs
+	 */
+	export type TaskArgs<Function> = Function extends (
+		context: TaskContext,
+		...args: infer Args
+	) => unknown
+		? Args
+		: never;
+
+	/**
+	 * The settled task result after unwrapping an explicit transfer envelope.
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#TaskValue
+	 */
+	export type TaskValue<Function> = Function extends (
+		...args: Array<never>
+	) => infer Result
+		? Awaited<Result> extends TransferResult<infer Value>
+			? Value
+			: Awaited<Result>
+		: never;
+
+	/**
+	 * Fixed persistent worker count and admission bounds. Every worker has independent
+	 * module state. A size-one pool dispatches admitted tasks serially.
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#PoolOptions
+	 */
+	export type PoolOptions = {
+		/** Positive safe integer; defaults to host parallelism, falling back to 1. */
+		size?: number;
+		/** Nonnegative safe integer; defaults to four times size. Zero disables the waiting queue. */
+		maxQueuedTasks?: number;
+		/** Positive safe integer in bytes; defaults to 67108864 (64 MiB). */
+		maxQueuedBytes?: number;
+		/** Positive safe integer in bytes; defaults to maxQueuedBytes. */
+		maxMessageBytes?: number;
+		/** Worker name prefix; each worker receives a one-based suffix. */
+		name?: string;
+	};
+
+	/**
+	 * The transfer list commits synchronously when run returns normally. Validation,
+	 * saturation, closed pools and already-aborted signals throw before admission.
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#RunOptions
+	 */
+	export type RunOptions = {
+		/** Already-aborted signals throw before admission. Running cancellation is cooperative. */
+		signal?: AbortSignal;
+		/** Ownership moves synchronously on successful admission; rejection leaves values unchanged. */
+		transfer?: ReadonlyArray<Transferable>;
+	};
+
+	/**
+	 * The window bounds pulled inputs and buffered results together. Results are yielded
+	 * in input order; iterator return cancels this map's work and closes its input.
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#MapOptions
+	 */
+	export type MapOptions<Args> = {
+		/** Cancels only work owned by this map; running tasks must cooperate. */
+		signal?: AbortSignal;
+		/** Positive safe integer; defaults to pool size. Bounds pulled inputs and buffered results together. */
+		window?: number;
+		/** Called for each input before admission to choose values whose ownership moves. */
+		transfer?: (args: Args, index: number) => ReadonlyArray<Transferable>;
+	};
+
+	/**
+	 * A snapshot of this pool's scheduling and settled operations.
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#PoolStats
+	 */
+	export type PoolStats = {
+		readonly size: number;
+		readonly active: number;
+		readonly queued: number;
+		readonly completed: number;
+		readonly failed: number;
+		readonly cancelled: number;
+	};
+
+	/**
+	 * A bounded task scheduler over isolated persistent workers. Each worker executes
+	 * one task through asynchronous settlement. No accepted task is replayed after
+	 * worker failure.
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#WorkerPool
+	 */
+	export type WorkerPool<Module> = {
+		/** Resolves after every worker evaluates the entry; rejects on startup failure. */
+		readonly ready: Promise<void>;
+		/** Throws on failed admission; returns a promise for the accepted task's result or failure. */
+		run<Key extends TaskNames<Module>>(
+			name: Key,
+			args: TaskArgs<Module[Key]>,
+			options?: RunOptions,
+		): Promise<TaskValue<Module[Key]>>;
+		/** Yields in input order. Returning from the iterator cancels its work and closes its input. */
+		map<Key extends TaskNames<Module>>(
+			name: Key,
+			args: Iterable<TaskArgs<Module[Key]>> | AsyncIterable<TaskArgs<Module[Key]>>,
+			options?: MapOptions<TaskArgs<Module[Key]>>,
+		): AsyncIterable<TaskValue<Module[Key]>>;
+		/** Stops admission, drains accepted tasks, then joins every worker. Idempotent. */
+		close(): Promise<void>;
+		/** Rejects outstanding tasks with AbortError; joins workers after running tasks cooperate and settle. */
+		terminate(): Promise<void>;
+		/** Returns a scheduling snapshot; counts are not a subscription. */
+		stats(): PoolStats;
+		/** Keeps the process alive while pool workers exist; returns this pool. */
+		ref(): WorkerPool<Module>;
+		/** Allows the process to exit without waiting for this pool; returns this pool. */
+		unref(): WorkerPool<Module>;
+		/** Reports whether this pool currently keeps the process alive. */
+		hasRef(): boolean;
+	};
+
+	/**
+	 * A terminal record published only after the native worker is joined and its slot is
+	 * released.
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#WorkerExit
+	 */
+	export type WorkerExit = {
+		readonly id: number;
+		readonly code: number;
+		readonly reason: "completed" | "terminated" | "error";
+		readonly error?: unknown;
+	};
+
+	/**
+	 * Worker data is snapshotted before startup. The native host bounds live workers and
+	 * message admission process-wide.
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#WorkerOptions
+	 */
+	export type WorkerOptions = {
+		name?: string;
+		/** Cloned into workerData before startup; later caller mutations are not shared. */
+		data?: unknown;
+		/** Values moved as part of startup-data admission. */
+		transfer?: ReadonlyArray<Transferable>;
+		/** Positive safe integer, at most 4294967295; defaults to 4096 messages per endpoint. */
+		maxQueuedMessages?: number;
+		/** Positive safe integer in bytes; defaults to 67108864 (64 MiB) per endpoint. */
+		maxQueuedBytes?: number;
+		/** Positive safe integer in bytes; defaults to 16777216 (16 MiB) per message. */
+		maxMessageBytes?: number;
+	};
+
+	/**
+	 * Each endpoint bounds its pending message count and bytes. Rejection leaves the
+	 * sender's transferables unchanged.
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#MessageChannelOptions
+	 */
+	export type MessageChannelOptions = {
+		/** Positive safe integer, at most 4294967295; defaults to 4096 messages per endpoint. */
+		maxQueuedMessages?: number;
+		/** Positive safe integer in bytes; defaults to 67108864 (64 MiB) per endpoint. */
+		maxQueuedBytes?: number;
+		/** Positive safe integer in bytes; defaults to 16777216 (16 MiB) per message. */
+		maxMessageBytes?: number;
+	};
+
+	/**
+	 * An ordered bidirectional endpoint with transactional transfer and bounded queues.
+	 * Message listeners and values are owned by the receiving isolate.
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#MessagePort.type
+	 */
+	export interface MessagePort<Send = unknown, Receive = unknown> extends EventTarget {
+		/** Clones and admits a message synchronously. Transfer commits only after successful validation/admission. */
+		postMessage(value: Send, transfer?: ReadonlyArray<Transferable>): void;
+		/** Setting this handler starts delivery. addEventListener listeners need start(). */
+		onmessage: ((event: MessageEvent<Receive>) => void) | null;
+		/** Receives message decoding failures in the receiving isolate. */
+		onmessageerror: ((event: MessageEvent<unknown>) => void) | null;
+		/** Enables delivery to event listeners; repeated calls are harmless. */
+		start(): void;
+		/** Discards queued messages and closes this endpoint. */
+		close(): void;
+		/** Keeps the receiving isolate alive; returns this port. */
+		ref(): MessagePort<Send, Receive>;
+		/** Allows the receiving isolate to exit; returns this port. */
+		unref(): MessagePort<Send, Receive>;
+		hasRef(): boolean;
+	}
+
+	/**
+	 * A standalone channel whose endpoints may be transferred to workers.
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#MessageChannel.type
+	 */
+	export type MessageChannel = {
+		readonly port1: MessagePort;
+		readonly port2: MessagePort;
+	};
+
+	/**
+	 * A long-lived isolated module and its parent communication port. Startup completes
+	 * after module evaluation; shutdown completes after native thread reaping.
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#Worker.type
+	 */
+	export type Worker<Send = unknown, Receive = unknown> = EventTarget & {
+		readonly id: number;
+		/** Resolves after entry evaluation; rejects on startup failure. */
+		readonly ready: Promise<void>;
+		/** Resolves with a terminal record after the native thread is joined and its slot released. */
+		readonly closed: Promise<WorkerExit>;
+		readonly port: MessagePort<Send, Receive>;
+		/** Requests shutdown and resolves after thread reaping. */
+		terminate(): Promise<WorkerExit>;
+		ref(): Worker<Send, Receive>;
+		unref(): Worker<Send, Receive>;
+		hasRef(): boolean;
+	};
+
+	/**
+	 * Declare an entry using a static string literal and explicit import.meta.url base.
+	 * The immutable href projection can be passed to existing worker libraries.
+	 *
+	 * @example
+	 * // declaration.ts
+	 * import { createWorkerUrl } from "maligator:workers";
+	 *
+	 * export const tasks = createWorkerUrl<typeof import("./sum.ts")>(
+	 * 	"./sum.ts",
+	 * 	import.meta.url,
+	 * );
+	 *
+	 * console.log(Object.isFrozen(tasks), tasks.href.startsWith("file:"));
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#createWorkerUrl
+	 */
+	export const createWorkerUrl: <Module = unknown>(
+		specifier: string,
+		base: string,
+	) => WorkerUrl<Module>;
+	/**
+	 * Create a bounded pool of persistent workers for a declared entry. Submission
+	 * failures throw synchronously; admitted tasks settle asynchronously. Await ready
+	 * before submitting startup-dependent work and close the pool when finished. Throws
+	 * NotSupportedError without threads and RangeError for invalid bounds.
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#createPool
+	 */
+	export const createPool: <Module>(
+		entry: WorkerUrl<Module>,
+		options?: PoolOptions,
+	) => WorkerPool<Module>;
+	/**
+	 * Wrap a result for transfer when the worker publishes it.
+	 *
+	 * @example
+	 * // transfer-task.ts
+	 * import { transfer } from "maligator:workers";
+	 * import type { TaskContext } from "maligator:workers";
+	 *
+	 * export function reverse(context: TaskContext, buffer: ArrayBuffer) {
+	 * 	context.throwIfCancelled();
+	 * 	new Uint8Array(buffer).reverse();
+	 * 	return transfer(buffer, [buffer]);
+	 * }
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#transfer
+	 */
+	export const transfer: <Value>(
+		value: Value,
+		transfer: ReadonlyArray<Transferable>,
+	) => TransferResult<Value>;
+	/**
+	 * Start a declared isolated module and expose its ordered port and complete
+	 * lifecycle.
+	 *
+	 * @example
+	 * // echo.ts
+	 * import { parentPort } from "maligator:workers";
+	 *
+	 * if (parentPort === null) throw new Error("Run this module as a worker");
+	 * const port = parentPort;
+	 * port.onmessage = (event) => {
+	 * 	port.postMessage(String(event.data));
+	 * };
+	 * port.start();
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#Worker
+	 */
+	export const Worker: {
+		new <Send = unknown, Receive = unknown>(
+			entry: WorkerUrl,
+			options?: WorkerOptions,
+		): Worker<Send, Receive>;
+	};
+	/**
+	 * Create two transferable endpoints independently of worker startup.
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#MessageChannel
+	 */
+	export const MessageChannel: { new (options?: MessageChannelOptions): MessageChannel };
+	/**
+	 * The port prototype for type and identity checks. Ports are created by channels and
+	 * workers.
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#MessagePort
+	 */
+	export const MessagePort: { readonly prototype: MessagePort };
+	/**
+	 * Synchronously dequeue one pending message without running unrelated callbacks.
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#receiveMessageOnPort
+	 */
+	export const receiveMessageOnPort: <Receive>(
+		port: MessagePort<unknown, Receive>,
+	) => { message: Receive } | undefined;
+	/**
+	 * Report the running host's worker facilities and capacity.
+	 *
+	 * @example
+	 * // capabilities.ts
+	 * import { capabilities } from "maligator:workers";
+	 *
+	 * const host = capabilities();
+	 * console.log(host.threads, host.sharedMemory);
+	 * console.log(host.parallelism >= 1, host.maxWorkers >= 1);
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#capabilities
+	 */
+	export const capabilities: () => {
+		readonly threads: boolean;
+		readonly sharedMemory: boolean;
+		readonly parallelism: number;
+		readonly maxWorkers: number;
+	};
+	/**
+	 * The worker's parent endpoint; null in the main isolate.
+	 *
+	 * @example
+	 * // echo.ts
+	 * import { parentPort } from "maligator:workers";
+	 *
+	 * if (parentPort === null) throw new Error("Run this module as a worker");
+	 * const port = parentPort;
+	 * port.onmessage = (event) => {
+	 * 	port.postMessage(String(event.data));
+	 * };
+	 * port.start();
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#parentPort
+	 */
+	export const parentPort: MessagePort | null;
+	/**
+	 * The worker-owned clone of startup data.
+	 *
+	 * @example
+	 * // configuration.ts
+	 * import { createWorkerUrl, Worker } from "maligator:workers";
+	 *
+	 * const entry = createWorkerUrl("./worker-data.ts", import.meta.url);
+	 * const worker = new Worker(entry, { data: { label: "thumbnail" } });
+	 * try {
+	 * 	await worker.ready;
+	 * 	const exit = await worker.closed;
+	 * 	if (exit.code !== 0) throw new Error("Worker failed");
+	 * } finally {
+	 * 	await worker.terminate();
+	 * }
+	 *
+	 * @see https://maligator.ddv.tools/api/workers#workerData
+	 */
+	export const workerData: unknown;
+}

package/workers-host-api.d.ts

@@ -0,0 +1,135 @@
+// Generated from src/platform/catalog.ts; edit the catalog and regenerate.
+/**
+ * Toolchain-owned worker substrate used by the public source API and Node
+ * compatibility personality.
+ */
+declare module "maligator:internal/workers" {
+	import type * as Workers from "maligator:workers";
+	/**
+	 * Values whose ownership moves when a message is admitted.
+	 */
+	export type Transferable = Workers.Transferable;
+
+	/**
+	 * A terminal record. The error is the uncaught value as thrown.
+	 */
+	export type WorkerExit = {
+		readonly id: number;
+		readonly code: number;
+		readonly reason: "completed" | "terminated" | "error";
+		readonly error?: unknown;
+	};
+
+	/**
+	 * A worker's uncaught value as thrown and its own string message, or the empty
+	 * string.
+	 */
+	export type WorkerErrorEvent = Event & {
+		readonly error: unknown;
+		readonly message: string;
+	};
+
+	/**
+	 * A transactional endpoint. postMessage returns the admission ticket, or undefined
+	 * when nothing was queued; _discard drops a posted message the peer has not
+	 * received.
+	 */
+	export type MessagePort<Send = unknown, Receive = unknown> = {
+		postMessage(value: Send, transfer?: ReadonlyArray<Transferable>): number | undefined;
+		_discard(ticket: number): boolean;
+		addEventListener(
+			type: "message",
+			listener: (event: MessageEvent<Receive>) => void | Promise<void>,
+			options?: AddEventListenerOptions | boolean,
+		): void;
+		onmessage: ((event: MessageEvent<Receive>) => void) | null;
+		onmessageerror: ((event: MessageEvent<unknown>) => void) | null;
+		start(): void;
+		close(): void;
+		ref(): MessagePort<Send, Receive>;
+		unref(): MessagePort<Send, Receive>;
+		hasRef(): boolean;
+	} & EventTarget;
+
+	/**
+	 * A channel whose first port sends Forward messages and receives Backward messages.
+	 */
+	export type MessageChannel<Forward = unknown, Backward = unknown> = {
+		readonly port1: MessagePort<Forward, Backward>;
+		readonly port2: MessagePort<Backward, Forward>;
+	};
+
+	/**
+	 * A source-API worker handle over a transactional parent port.
+	 */
+	export type Worker<Send = unknown, Receive = unknown> = {
+		readonly id: number;
+		readonly ready: Promise<void>;
+		readonly closed: Promise<WorkerExit>;
+		readonly port: MessagePort<Send, Receive>;
+		addEventListener(
+			type: "error",
+			listener: (event: WorkerErrorEvent) => void,
+			options?: AddEventListenerOptions | boolean,
+		): void;
+		terminate(): Promise<WorkerExit>;
+		ref(): Worker<Send, Receive>;
+		unref(): Worker<Send, Receive>;
+		hasRef(): boolean;
+	} & EventTarget;
+
+	/**
+	 * Start a declared isolated module with a transactional parent port.
+	 */
+	export const Worker: {
+		new <Send = unknown, Receive = unknown>(
+			entry: { readonly href: string },
+			options?: Workers.WorkerOptions,
+		): Worker<Send, Receive>;
+	};
+	/**
+	 * Create two transactional endpoints.
+	 */
+	export const MessageChannel: {
+		new <Forward = unknown, Backward = unknown>(
+			options?: Workers.MessageChannelOptions,
+		): MessageChannel<Forward, Backward>;
+	};
+	/**
+	 * The transactional port prototype.
+	 */
+	export const MessagePort: { readonly prototype: MessagePort };
+	/**
+	 * Synchronously dequeue one pending message without running unrelated callbacks.
+	 */
+	export const receiveMessageOnPort: <Receive>(
+		port: MessagePort<unknown, Receive>,
+	) => { readonly message: Receive } | undefined;
+	/**
+	 * Report the running host's worker facilities and capacity.
+	 */
+	export const capabilities: typeof Workers.capabilities;
+	/**
+	 * Fail the current worker after its outcome cannot be published.
+	 */
+	export const failCurrent: () => void;
+	/**
+	 * Internal static entry declaration.
+	 */
+	export const createWorkerUrl: (
+		specifier: string,
+		base: string,
+	) => { readonly href: string };
+	/**
+	 * Isolate-owned worker state.
+	 */
+	export const parentPort: MessagePort | null;
+	/**
+	 * Isolate-owned worker state.
+	 */
+	export const workerData: unknown;
+	/**
+	 * The task-pool bootstrap entry.
+	 */
+	export const poolEntry: { readonly href: string };
+}