@toolbench/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Elmalt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# @toolbench/sdk
+
+The contract a [Toolbench](https://github.com/eknowledger/toolbench) tool implements. No dependencies,
+no DOM.
+
+```sh
+pnpm add @toolbench/sdk
+```
+
+A tool is one function and one JSON file:
+
+```ts
+import type { Tool } from "@toolbench/sdk";
+
+export default {
+  run({ text }) {
+    return { kind: "fields", fields: [{ label: "reversed", value: [...text].reverse().join("") }] };
+  },
+} satisfies Tool<{ text: string }>;
+```
+
+This package holds four things:
+
+| Export | What it does |
+|---|---|
+| Types (`Tool`, `Ctx`, `Output`, `InputSpec`, `Manifest`) | The whole agreement between a tool and a host |
+| `validateManifest` | Turns unknown JSON into a `Manifest`, or throws naming the field and saying what to do |
+| `upgradeManifest`, `upgradeOutput`, `canLoad` | Version migration, so a tool written against an older contract keeps working |
+| `runCases`, `assertCases`, `compare` | The fixture runner. Known-answer cases run in Node with no browser and no build step |
+
+Nothing here touches the DOM, because `run` has to work in three places: Node during tests, a Web
+Worker where no DOM exists, and a site build computing a precomputed result.
+
+To render and run a tool in a page, add [`@toolbench/runtime`](https://www.npmjs.com/package/@toolbench/runtime).
+
+## Documentation
+
+- [Writing a tool](https://github.com/eknowledger/toolbench/blob/main/docs/authoring-a-tool.md)
+- [Architecture](https://github.com/eknowledger/toolbench/blob/main/docs/architecture.md)
+- [Versioning and compatibility](https://github.com/eknowledger/toolbench/blob/main/docs/versioning.md)
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @toolbench/sdk — the contract a tool implements.
+ *
+ * A tool is one function plus one manifest. Nothing here touches the DOM, a framework, or a host
+ * site, which is what lets a tool be tested in plain Node and reused by any runtime.
+ *
+ *   import type { Tool } from "@toolbench/sdk";
+ *
+ *   export default {
+ *     run({ value }, ctx) {
+ *       return { kind: "fields", fields: [{ label: "doubled", value: String(Number(value) * 2) }] };
+ *     },
+ *   } satisfies Tool<{ value: string }>;
+ */
+export { CAPABILITIES, INPUT_TYPES, OUTPUT_KINDS, type Capability, type Case, type Cell, type Chart, type Column, type Ctx, type Field, type InputSpec, type InputType, type InputValues, type LoadedTool, type Manifest, type Output, type OutputKind, type Series, type Tone, type Tool, type ToolModule, } from "./types.ts";
+export { ManifestError, describeSdkVersion, validateManifest } from "./validate.ts";
+export { MIGRATIONS, VersionError, canLoad, upgradeManifest, upgradeOutput, type Migration } from "./migrate.ts";
+export { assertCases, compare, runCases, testCtx, type CaseResult, type RunCasesOptions } from "./testing.ts";
+export { SDK_CHANGELOG, SDK_VERSION, SUPPORTED_SDK_VERSIONS } from "./version.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EACN,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,IAAI,EACT,KAAK,KAAK,EACV,KAAK,MAAM,EACX,KAAK,GAAG,EACR,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,MAAM,EACX,KAAK,IAAI,EACT,KAAK,IAAI,EACT,KAAK,UAAU,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACpF,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AACjH,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAC9G,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * @toolbench/sdk — the contract a tool implements.
+ *
+ * A tool is one function plus one manifest. Nothing here touches the DOM, a framework, or a host
+ * site, which is what lets a tool be tested in plain Node and reused by any runtime.
+ *
+ *   import type { Tool } from "@toolbench/sdk";
+ *
+ *   export default {
+ *     run({ value }, ctx) {
+ *       return { kind: "fields", fields: [{ label: "doubled", value: String(Number(value) * 2) }] };
+ *     },
+ *   } satisfies Tool<{ value: string }>;
+ */
+export { CAPABILITIES, INPUT_TYPES, OUTPUT_KINDS, } from "./types.js";
+export { ManifestError, describeSdkVersion, validateManifest } from "./validate.js";
+export { MIGRATIONS, VersionError, canLoad, upgradeManifest, upgradeOutput } from "./migrate.js";
+export { assertCases, compare, runCases, testCtx } from "./testing.js";
+export { SDK_CHANGELOG, SDK_VERSION, SUPPORTED_SDK_VERSIONS } from "./version.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EACN,YAAY,EACZ,WAAW,EACX,YAAY,GAmBZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACpF,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAkB,MAAM,cAAc,CAAC;AACjH,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAyC,MAAM,cAAc,CAAC;AAC9G,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC"}

package/dist/migrate.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Backward compatibility, as a mechanism rather than a promise.
+ *
+ * A tool is pinned to the contract version it was written against. The runtime keeps moving. So
+ * every version boundary gets a **migration**: a pair of pure functions that carry an old manifest
+ * and an old output forward one step. Loading a tool runs the chain from its declared version up to
+ * the current one, and after that the rest of the system only ever sees current shapes.
+ *
+ * ```
+ *  tool declares sdk: 1        runtime speaks 3
+ *          │
+ *          └──▶ migrate 1→2 ──▶ migrate 2→3 ──▶ current
+ * ```
+ *
+ * Why a chain and not one big adapter: each step is small enough to read, and each step is testable
+ * on its own. Adding version 4 means writing one 3→4 step, not revisiting the previous three.
+ *
+ * The rules that keep this honest, and that `docs/versioning.md` states as policy:
+ *
+ *  - **Additive only.** A new version may add output kinds, input types and optional fields. It may
+ *    not remove or repurpose anything, because a migration cannot invent information an old tool
+ *    never had.
+ *  - **A migration never fails.** If a step would need to guess, the change was not additive and
+ *    does not belong in a version bump.
+ *  - **Old fixtures run forever.** Every tool's cases are checked against the current runtime in CI,
+ *    which is what turns this file from a good intention into a tested claim.
+ */
+import type { Manifest, Output } from "./types.ts";
+export interface Migration {
+    /** Migrates a manifest from `from` to `from + 1`. */
+    readonly from: number;
+    manifest(raw: Record<string, unknown>): Record<string, unknown>;
+    /** Migrates an output produced by a tool written against `from`. */
+    output(out: Output): Output;
+}
+/**
+ * The chain, ordered by `from`.
+ *
+ * Empty at contract version 1 — there is nothing before it. The machinery exists now, with tests,
+ * because a compatibility mechanism written at the moment it is first needed is a compatibility
+ * mechanism written under pressure.
+ *
+ * A future entry looks like this (from the real plan for version 2, which adds a `bytes` output for
+ * hex dumps):
+ *
+ * ```ts
+ * {
+ *   from: 1,
+ *   // A v1 manifest cannot mention `bytes`, so nothing to change.
+ *   manifest: (m) => m,
+ *   // A v1 tool cannot return `bytes` either. Identity — and that is the shape of a healthy
+ *   // additive change: the migration is trivial precisely because nothing was taken away.
+ *   output: (o) => o,
+ * }
+ * ```
+ */
+export declare const MIGRATIONS: readonly Migration[];
+export declare class VersionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Read a raw manifest of any supported version and return one shaped for the current contract.
+ *
+ * `migrations` is injectable so the chain itself can be tested without shipping a fake version.
+ */
+export declare function upgradeManifest(raw: unknown, migrations?: readonly Migration[], currentVersion?: number): Record<string, unknown>;
+/** Carry an output produced by a tool written against `declaredVersion` up to the current shape. */
+export declare function upgradeOutput(out: Output, declaredVersion: number, migrations?: readonly Migration[], currentVersion?: number): Output;
+/** True when this runtime can load a tool declaring `version`. */
+export declare function canLoad(version: number, currentVersion?: number): boolean;
+export type { Manifest };
+//# sourceMappingURL=migrate.d.ts.map

package/dist/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGnD,MAAM,WAAW,SAAS;IACzB,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChE,oEAAoE;IACpE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,UAAU,EAAE,SAAS,SAAS,EAAO,CAAC;AAEnD,qBAAa,YAAa,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI3B;AAyBD;;;;GAIG;AACH,wBAAgB,eAAe,CAC9B,GAAG,EAAE,OAAO,EACZ,UAAU,GAAE,SAAS,SAAS,EAAe,EAC7C,cAAc,GAAE,MAAoB,GAClC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwBzB;AAED,oGAAoG;AACpG,wBAAgB,aAAa,CAC5B,GAAG,EAAE,MAAM,EACX,eAAe,EAAE,MAAM,EACvB,UAAU,GAAE,SAAS,SAAS,EAAe,EAC7C,cAAc,GAAE,MAAoB,GAClC,MAAM,CAOR;AAED,kEAAkE;AAClE,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,GAAE,MAAoB,GAAG,OAAO,CAEtF;AAED,YAAY,EAAE,QAAQ,EAAE,CAAC"}

package/dist/migrate.js

@@ -0,0 +1,89 @@
+import { SDK_VERSION } from "./version.js";
+/**
+ * The chain, ordered by `from`.
+ *
+ * Empty at contract version 1 — there is nothing before it. The machinery exists now, with tests,
+ * because a compatibility mechanism written at the moment it is first needed is a compatibility
+ * mechanism written under pressure.
+ *
+ * A future entry looks like this (from the real plan for version 2, which adds a `bytes` output for
+ * hex dumps):
+ *
+ * ```ts
+ * {
+ *   from: 1,
+ *   // A v1 manifest cannot mention `bytes`, so nothing to change.
+ *   manifest: (m) => m,
+ *   // A v1 tool cannot return `bytes` either. Identity — and that is the shape of a healthy
+ *   // additive change: the migration is trivial precisely because nothing was taken away.
+ *   output: (o) => o,
+ * }
+ * ```
+ */
+export const MIGRATIONS = [];
+export class VersionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "VersionError";
+    }
+}
+/**
+ * The steps needed to carry `version` up to `currentVersion`, in order.
+ *
+ * ⚠️ `currentVersion` is a parameter, not the module constant. It was the constant in the first
+ * draft, which meant the injected version was ignored and the chain silently did nothing — the
+ * migration tests caught it, which is the argument for testing a compatibility mechanism before the
+ * day you need it.
+ */
+function chainFrom(version, migrations, currentVersion) {
+    const steps = [];
+    for (let v = version; v < currentVersion; v++) {
+        const step = migrations.find((m) => m.from === v);
+        if (!step) {
+            throw new VersionError(`No migration from contract version ${v} to ${v + 1}. This is a bug in @toolbench/sdk: ` +
+                `the current version is ${currentVersion}, so every version below it needs a migration step.`);
+        }
+        steps.push(step);
+    }
+    return steps;
+}
+/**
+ * Read a raw manifest of any supported version and return one shaped for the current contract.
+ *
+ * `migrations` is injectable so the chain itself can be tested without shipping a fake version.
+ */
+export function upgradeManifest(raw, migrations = MIGRATIONS, currentVersion = SDK_VERSION) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw new VersionError("A manifest must be an object.");
+    }
+    const manifest = raw;
+    const declared = manifest.sdk;
+    if (typeof declared !== "number" || !Number.isInteger(declared) || declared < 1) {
+        throw new VersionError(`A manifest must declare an integer contract version, e.g. { "sdk": ${currentVersion} }. Got ${JSON.stringify(declared)}.`);
+    }
+    if (declared > currentVersion) {
+        throw new VersionError(`This tool needs contract version ${declared}; this runtime speaks ${currentVersion}. ` +
+            "Upgrade @toolbench/runtime, or lower the tool's sdk if it does not use the newer features.");
+    }
+    let out = manifest;
+    for (const step of chainFrom(declared, migrations, currentVersion)) {
+        out = step.manifest(out);
+        out = { ...out, sdk: step.from + 1 };
+    }
+    return { ...out, sdk: currentVersion };
+}
+/** Carry an output produced by a tool written against `declaredVersion` up to the current shape. */
+export function upgradeOutput(out, declaredVersion, migrations = MIGRATIONS, currentVersion = SDK_VERSION) {
+    if (declaredVersion > currentVersion) {
+        throw new VersionError(`Cannot downgrade an output from version ${declaredVersion} to ${currentVersion}.`);
+    }
+    let value = out;
+    for (const step of chainFrom(declaredVersion, migrations, currentVersion))
+        value = step.output(value);
+    return value;
+}
+/** True when this runtime can load a tool declaring `version`. */
+export function canLoad(version, currentVersion = SDK_VERSION) {
+    return Number.isInteger(version) && version >= 1 && version <= currentVersion;
+}
+//# sourceMappingURL=migrate.js.map

package/dist/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"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"}

package/dist/testing.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The fixture runner: a tool's `cases.json` is its test suite, and this runs it.
+ *
+ * It lives in the SDK rather than in the runtime for one reason — **a tool's correctness has nothing
+ * to do with a browser.** Cases run in plain Node, which means a tool author gets a red test in
+ * milliseconds, CI needs no browser, and the same fixtures can be re-run by a host site's build to
+ * prove that the tool it pinned still does what it claimed.
+ *
+ * Matching is exact by default. That is deliberate: subset matching quietly passes a field emitted
+ * twice, fields reordered, a field dropped, or garbage returned beside a correct error message. A
+ * case may opt out with `match: "subset"`, and then it owes two things — a `why`, and a `fieldCount`
+ * so a disappearing field is still a failure.
+ */
+import type { Case, Ctx, Output, Tool } from "./types.ts";
+export interface CaseResult {
+    name: string;
+    ok: boolean;
+    /** Present when `ok` is false: a human-readable account of the difference. */
+    detail?: string;
+    /** Wall-clock duration, so a "main thread" tool can be held to a bound. */
+    ms: number;
+}
+export interface RunCasesOptions {
+    /** Fails any case that takes longer than this. Use it to hold main-thread tools to a bound. */
+    maxMs?: number;
+    /** Aborts a case that hangs, so a bad loop fails the suite instead of wedging it. */
+    timeoutMs?: number;
+}
+/** A `Ctx` for a headless run: nothing to draw progress on, and an abort that a timeout can pull. */
+export declare function testCtx(signal?: AbortSignal): Ctx;
+export declare function runCases(tool: Tool, cases: readonly Case[], options?: RunCasesOptions): Promise<CaseResult[]>;
+/** Throws with every failure listed. The shape most test runners want. */
+export declare function assertCases(tool: Tool, cases: readonly Case[], options?: RunCasesOptions): Promise<void>;
+/** Returns undefined when the output matches, or a description of the first difference. */
+export declare function compare(actual: Output, testCase: Case): string | undefined;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,GAAG,EAAS,MAAM,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEjE,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,EAAE,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,eAAe;IAC/B,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qGAAqG;AACrG,wBAAgB,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,GAAG,CAKjD;AAED,wBAAsB,QAAQ,CAC7B,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,OAAO,GAAE,eAAoB,GAC3B,OAAO,CAAC,UAAU,EAAE,CAAC,CAqCvB;AAED,0EAA0E;AAC1E,wBAAsB,WAAW,CAChC,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,OAAO,GAAE,eAAoB,GAC3B,OAAO,CAAC,IAAI,CAAC,CASf;AAMD,2FAA2F;AAC3F,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,CAY1E"}

package/dist/testing.js

@@ -0,0 +1,211 @@
+/** A `Ctx` for a headless run: nothing to draw progress on, and an abort that a timeout can pull. */
+export function testCtx(signal) {
+    return {
+        signal: signal ?? new AbortController().signal,
+        progress: () => { },
+    };
+}
+export async function runCases(tool, cases, options = {}) {
+    const results = [];
+    for (const testCase of cases) {
+        const controller = new AbortController();
+        const timeout = options.timeoutMs
+            ? setTimeout(() => controller.abort(new Error(`case exceeded ${options.timeoutMs}ms`)), options.timeoutMs)
+            : undefined;
+        const started = performance.now();
+        try {
+            const actual = await tool.run(testCase.input, testCtx(controller.signal));
+            const ms = performance.now() - started;
+            const detail = compare(actual, testCase);
+            const tooSlow = options.maxMs !== undefined && ms > options.maxMs;
+            results.push({
+                name: testCase.name,
+                ok: detail === undefined && !tooSlow,
+                ms,
+                ...(detail !== undefined
+                    ? { detail }
+                    : tooSlow
+                        ? { detail: `took ${ms.toFixed(1)}ms, over the ${options.maxMs}ms bound for this tool` }
+                        : {}),
+            });
+        }
+        catch (error) {
+            results.push({
+                name: testCase.name,
+                ok: false,
+                ms: performance.now() - started,
+                detail: `threw ${error?.name ?? "Error"}: ${error?.message ?? String(error)}\n` +
+                    "A tool should THROW only when the tool itself is broken. If this input is simply invalid, " +
+                    'return { kind: "error", message, input } instead.',
+            });
+        }
+        finally {
+            if (timeout)
+                clearTimeout(timeout);
+        }
+    }
+    return results;
+}
+/** Throws with every failure listed. The shape most test runners want. */
+export async function assertCases(tool, cases, options = {}) {
+    const results = await runCases(tool, cases, options);
+    const failed = results.filter((r) => !r.ok);
+    if (failed.length > 0) {
+        throw new Error(`${failed.length} of ${results.length} cases failed:\n\n` +
+            failed.map((f) => `  ✗ ${f.name}\n    ${f.detail?.split("\n").join("\n    ")}`).join("\n\n"));
+    }
+}
+// ---------------------------------------------------------------------------
+// comparison
+// ---------------------------------------------------------------------------
+/** Returns undefined when the output matches, or a description of the first difference. */
+export function compare(actual, testCase) {
+    const mode = testCase.match ?? "exact";
+    if (mode === "subset") {
+        if (!testCase.why) {
+            return 'match: "subset" requires a `why` — an opt-out of exact matching needs a stated reason.';
+        }
+        if (testCase.expect.kind === "fields" && testCase.fieldCount === undefined) {
+            return 'match: "subset" on a fields output requires `fieldCount`, or a dropped field would pass.';
+        }
+        return subset(actual, testCase);
+    }
+    return exact(actual, testCase.expect, "output");
+}
+function exact(actual, expected, path) {
+    if (expected === actual)
+        return undefined;
+    if (typeof expected !== typeof actual) {
+        return `${path}: expected ${typeof expected} ${show(expected)}, got ${typeof actual} ${show(actual)}`;
+    }
+    if (Array.isArray(expected) || Array.isArray(actual)) {
+        if (!Array.isArray(expected) || !Array.isArray(actual)) {
+            return `${path}: expected ${show(expected)}, got ${show(actual)}`;
+        }
+        if (expected.length !== actual.length) {
+            return `${path}: expected ${expected.length} item(s), got ${actual.length}\n  expected: ${show(expected)}\n  actual:   ${show(actual)}`;
+        }
+        for (let i = 0; i < expected.length; i++) {
+            const diff = exact(actual[i], expected[i], `${path}[${i}]`);
+            if (diff)
+                return diff;
+        }
+        return undefined;
+    }
+    if (expected !== null && actual !== null && typeof expected === "object") {
+        const e = expected;
+        const a = actual;
+        const keys = [...new Set([...Object.keys(e), ...Object.keys(a)])].sort();
+        for (const key of keys) {
+            if (!(key in e))
+                return `${path}.${key}: unexpected field ${show(a[key])}`;
+            if (!(key in a))
+                return `${path}.${key}: missing, expected ${show(e[key])}`;
+            const diff = exact(a[key], e[key], `${path}.${key}`);
+            if (diff)
+                return diff;
+        }
+        return undefined;
+    }
+    return `${path}: expected ${show(expected)}, got ${show(actual)}`;
+}
+function subset(actual, testCase) {
+    const expected = testCase.expect;
+    /*
+     * ⚠️ A subset case looks INSIDE a group.
+     *
+     * Composite output is the normal case, not the exception — a decode that returns both a field list
+     * and a table is a `group` — so a case asserting "somewhere in there, these fields have these
+     * values" has to be able to reach the part it means. Without this, subset matching is unusable for
+     * exactly the tools most likely to need it.
+     *
+     * The rule is "some part matches", chosen because it is predictable: with two `fields` parts, a
+     * case that matches either one passes, and a case that matches neither reports what it tried.
+     */
+    if (actual.kind === "group" && expected.kind !== "group") {
+        const candidates = flatten(actual).filter((part) => part.kind === expected.kind);
+        if (candidates.length === 0) {
+            return `output: no "${expected.kind}" part inside the group (it has ${flatten(actual).map((p) => p.kind).join(", ")})`;
+        }
+        const diffs = candidates.map((candidate) => subset(candidate, testCase)).filter((d) => d !== undefined);
+        if (diffs.length < candidates.length)
+            return undefined; // at least one part matched
+        return candidates.length === 1
+            ? diffs[0]
+            : `output: none of the ${candidates.length} "${expected.kind}" parts matched. Closest: ${diffs[0]}`;
+    }
+    if (actual.kind !== expected.kind) {
+        return `output.kind: expected "${expected.kind}", got "${actual.kind}"`;
+    }
+    if (expected.kind === "fields" && actual.kind === "fields") {
+        if (actual.fields.length !== testCase.fieldCount) {
+            return `output.fields: expected exactly ${testCase.fieldCount} field(s) (from fieldCount), got ${actual.fields.length}`;
+        }
+        /*
+         * ⚠️ Fields are identified by GROUP + LABEL, not by label alone.
+         *
+         * A tool that reports the same quantity two ways — "time in system" under "Formula" and again
+         * under "Simulation" — is the normal case, and that is exactly what `group` is for. Keying on
+         * the label alone made those two collide and reported a duplicate that was not one.
+         */
+        const key = (f) => `${f.group ?? ""}\u0000${f.label}`;
+        const byKey = new Map();
+        for (const f of actual.fields)
+            byKey.set(key(f), [...(byKey.get(key(f)) ?? []), f]);
+        for (const want of expected.fields) {
+            const where = want.group ? `"${want.label}" in group "${want.group}"` : `"${want.label}"`;
+            const got = byKey.get(key(want));
+            if (!got) {
+                const labels = actual.fields.map((f) => (f.group ? `${f.group}/${f.label}` : f.label)).join(", ");
+                return `output.fields: no field ${where}. Present: ${labels}`;
+            }
+            if (got.length > 1)
+                return `output.fields: ${where} appears ${got.length} times`;
+            const diff = exact(got[0], { ...got[0], ...want }, `output.fields[${where}]`);
+            if (diff)
+                return diff;
+        }
+        return undefined;
+    }
+    /*
+     * A chart in subset mode asserts its FRAME, not its data: axis labels, units and annotations.
+     *
+     * Pinning hundreds of computed points in a fixture is both unreadable and the wrong test — the
+     * numbers belong in a unit test that says why they are right. What a fixture usefully checks is
+     * that the chart the tool describes is the chart the renderer will get.
+     */
+    if (expected.kind === "series" && actual.kind === "series") {
+        const { x: _ax, series: _as, ...actualFrame } = actual.chart;
+        const { x: _ex, series: _es, ...expectedFrame } = expected.chart;
+        const diff = exact(actualFrame, { ...actualFrame, ...expectedFrame }, "output.chart");
+        if (diff)
+            return diff;
+        if (actual.chart.series.length === 0)
+            return "output.chart.series: the chart has no series at all";
+        if (actual.chart.x.length === 0)
+            return "output.chart.x: the chart has no x values";
+        return undefined;
+    }
+    if (expected.kind === "error" && actual.kind === "error") {
+        if (!actual.message.includes(expected.message)) {
+            return `output.message: expected to contain "${expected.message}", got "${actual.message}"`;
+        }
+        if (expected.input !== undefined && actual.input !== expected.input) {
+            return `output.input: expected "${expected.input}", got ${show(actual.input)}`;
+        }
+        return undefined;
+    }
+    // For every other kind, subset has no defined meaning — fall back to exact rather than pretend.
+    return exact(actual, expected, "output");
+}
+/** Every part of a possibly-nested group, in order, excluding the groups themselves. */
+function flatten(output) {
+    return output.kind === "group" ? output.parts.flatMap(flatten) : [output];
+}
+function show(value) {
+    const json = JSON.stringify(value);
+    if (json === undefined)
+        return String(value);
+    return json.length > 160 ? `${json.slice(0, 157)}…` : json;
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,269 @@
+/**
+ * The contract. A tool is a function; everything else here describes what goes in and what comes
+ * out, so a runtime can build an interface for a tool it has never seen.
+ *
+ * Two rules govern every change to this file:
+ *
+ *  1. **Additive only.** New output kinds and input types get added. Existing ones never change
+ *     meaning, never lose a field, and never gain a required one.
+ *  2. **No DOM, no framework, no host.** A tool must be runnable in plain Node, because that is how
+ *     its fixtures are checked. Anything that needs a browser belongs in the runtime, not here.
+ */
+/** A label and a value. The plainest thing a tool can say. */
+export interface Field {
+    label: string;
+    value: string;
+    /** A qualifier shown beside the value: a unit, a caveat, "(dynamic)". */
+    note?: string;
+    /** Fields sharing a group are rendered together under its name. */
+    group?: string;
+    /** Draws attention without inventing a severity scale. */
+    tone?: Tone;
+}
+export type Tone = "normal" | "warn" | "bad" | "good";
+export interface Column {
+    label: string;
+    align?: "start" | "end";
+    /** Monospace, for anything the reader will compare digit by digit. */
+    mono?: boolean;
+}
+export type Cell = string | number | {
+    text: string;
+    mono?: boolean;
+    tone?: Tone;
+};
+/** One line, bar or area on a chart. */
+export interface Series {
+    label: string;
+    /** One value per x. A `null` is a gap, not a zero — the distinction matters on a chart. */
+    points: (number | null)[];
+    unit?: string;
+    shape?: "line" | "area" | "bar";
+    axis?: "left" | "right";
+}
+export interface Chart {
+    xLabel: string;
+    yLabel: string;
+    x: number[];
+    series: Series[];
+    xUnit?: string;
+    yUnit?: string;
+    /** A vertical marker with a name: "the knee", "capacity", "p99". */
+    annotations?: {
+        x: number;
+        label: string;
+    }[];
+    /** Second axis label, required if any series sets `axis: "right"`. */
+    yLabelRight?: string;
+}
+/**
+ * What a tool returns. A closed union: a runtime can render every member, and a tool cannot invent
+ * a shape nobody can draw.
+ *
+ * ⚠️ `group` is what lets one tool answer in more than one shape — a decode that produces both a
+ * field list and a table is the common case, not the exception.
+ */
+export type Output = {
+    kind: "fields";
+    fields: Field[];
+} | {
+    kind: "text";
+    text: string;
+    mono?: boolean;
+} | {
+    kind: "code";
+    lang: string;
+    source: string;
+} | {
+    kind: "table";
+    columns: Column[];
+    rows: Cell[][];
+    caption?: string;
+} | {
+    kind: "series";
+    chart: Chart;
+} | {
+    kind: "group";
+    parts: Output[];
+}
+/**
+ * The INPUT was wrong, and the tool worked correctly by saying so. `input` names the control at
+ * fault so a generated form can mark it invalid and point a screen reader at the message —
+ * without it, an error can only ever float unattached.
+ *
+ * A tool that is itself broken should THROW instead. The two render differently on purpose.
+ */
+ | {
+    kind: "error";
+    message: string;
+    input?: string;
+    at?: number;
+    len?: number;
+};
+export type OutputKind = Output["kind"];
+/** Every kind this contract version can express. The runtime checks its renderers against this. */
+export declare const OUTPUT_KINDS: readonly OutputKind[];
+interface InputBase {
+    id: string;
+    label: string;
+    /** The hint a form shows and a screen reader reads. Not a placeholder — those vanish on focus. */
+    description?: string;
+    /** Shown after the control: "ms", "req/s", "bytes". A number without one is a riddle. */
+    unit?: string;
+    /** The one input a compact card shows. At most one per tool. */
+    primary?: boolean;
+    /**
+     * Force text direction. Bytes, code and identifiers are left-to-right even inside right-to-left
+     * prose, and a runtime cannot know which is which — the tool says.
+     */
+    dir?: "ltr" | "auto";
+}
+export type InputSpec = (InputBase & {
+    type: "text";
+    default: string;
+    maxLength?: number;
+}) | (InputBase & {
+    type: "textarea";
+    default: string;
+    rows?: number;
+    maxLength?: number;
+}) | (InputBase & {
+    type: "number";
+    default: number;
+    min: number;
+    max: number;
+    step?: number;
+}) | (InputBase & {
+    type: "select";
+    default: string;
+    options: {
+        value: string;
+        label: string;
+    }[];
+}) | (InputBase & {
+    type: "toggle";
+    default: boolean;
+});
+export type InputType = InputSpec["type"];
+export declare const INPUT_TYPES: readonly InputType[];
+/** The shape a tool's `run` receives: one entry per declared input, keyed by id. */
+export type InputValues = Record<string, string | number | boolean>;
+/**
+ * `pure` is the only capability in contract version 1: a function of its inputs, no I/O, no clock,
+ * no randomness that is not seeded. That is not a limitation to apologise for — it is what makes a
+ * tool testable by fixture, runnable at build time, and safe to put on a landing page.
+ *
+ * Reading files and calling networks arrive in later versions, each with its own capability, so a
+ * runtime can always tell from the manifest what a tool will try to do before it runs.
+ */
+export type Capability = "pure";
+export declare const CAPABILITIES: readonly Capability[];
+export interface Manifest {
+    /** The contract version this tool was written against. */
+    sdk: number;
+    /** Stable, lowercase, hyphenated. Also the directory name and the URL segment. */
+    id: string;
+    name: string;
+    /** One sentence. Shown on cards and used as a page description. */
+    blurb: string;
+    /** The tool's own version, independent of `sdk`. */
+    version: string;
+    capabilities: Capability[];
+    inputs: InputSpec[];
+    /** Every kind `run` can return, so a host can refuse a tool it cannot draw. */
+    kinds: OutputKind[];
+    runtime: {
+        /** Entry file, relative to the tool's directory. */
+        entry: string;
+        /**
+         * `main` is the default and costs nothing. `worker` is for a tool whose running time depends
+         * on its input — it is the only mode where a timeout can actually stop anything.
+         */
+        thread?: "main" | "worker";
+    };
+    status?: "live" | "deprecated" | "retired";
+    /** How the tool appears in a compact slot: runnable, a summary that links out, or not at all. */
+    card?: "live" | "info" | "none";
+    /** How many fields a card shows before it stops. Errors are never truncated. */
+    cardFields?: number;
+    /**
+     * Re-run as the reader types, instead of waiting for the Run button.
+     *
+     * Off by default, and that default is deliberate. A tool that runs on every keystroke does work
+     * nobody asked for, makes the Run button look broken (the answer is already there), and takes the
+     * decision away from the reader. Opt in only for a tool that is genuinely instant and reads better
+     * live — a unit converter, say. Anything with a worker or a heavy loop should leave it alone.
+     */
+    autoRun?: boolean;
+    /** Worker mode only. A tool that declares this on the main thread is rejected: nothing there can be stopped. */
+    timeoutMs?: number;
+    /** Markdown file, relative to the tool's directory, rendered as the tool's help. */
+    help?: string;
+    tags?: string[];
+    /**
+     * Anything the tool wants to point at: a spec it implements, a post explaining it, a reference
+     * decoder. Deliberately generic — a host site's own content relations are the host's business.
+     */
+    links?: {
+        label: string;
+        href: string;
+    }[];
+}
+/** Passed to `run`. Built by whatever is executing the tool, never sent across a boundary. */
+export interface Ctx {
+    /**
+     * Aborted when the reader cancels, when the input changes mid-run, or when a worker-mode timeout
+     * fires. A loop whose length depends on input MUST check it — on the main thread it is the only
+     * way to stop.
+     */
+    signal: AbortSignal;
+    /**
+     * Progress, and optionally a partial result. A runtime renders `partial` at most once per frame,
+     * which is what lets a simulation show itself converging instead of hiding behind a bar.
+     */
+    progress(fraction: number, partial?: Output): void;
+}
+/**
+ * What a tool is.
+ *
+ * ⚠️ **Declare your input type as a `type`, not an `interface`.** TypeScript gives an implicit index
+ * signature to a type alias of an object literal and not to an interface, so an interface will not
+ * satisfy `InputValues` and the error message ("index signature is missing") does not hint at the
+ * fix. This is the first thing a new tool author trips over.
+ *
+ * ```ts
+ * type Input = { values: string; method: string };   // ✓
+ * interface Input { values: string }                 // ✗ won't satisfy InputValues
+ *
+ * export default { run(input: Input, ctx) { … } } satisfies Tool<Input>;
+ * ```
+ */
+export interface Tool<I extends InputValues = InputValues> {
+    run(input: I, ctx: Ctx): Output | Promise<Output>;
+}
+/** What a tool module default-exports. */
+export type ToolModule<I extends InputValues = InputValues> = {
+    default: Tool<I>;
+};
+/** A manifest plus the module that implements it, which is what a runtime actually consumes. */
+export interface LoadedTool<I extends InputValues = InputValues> {
+    manifest: Manifest;
+    tool: Tool<I>;
+}
+export interface Case {
+    name: string;
+    input: InputValues;
+    expect: Output;
+    /**
+     * Exact deep equality by default, because that is what catches a duplicated field, a reordered
+     * one, or garbage emitted beside a correct error.
+     *
+     * `subset` is an opt-in escape for a tool whose output is genuinely open-ended, and it demands
+     * two things in return: a `why`, and a `fieldCount`, so a dropped field is still a failure.
+     */
+    match?: "exact" | "subset";
+    why?: string;
+    fieldCount?: number;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,24 @@
+/**
+ * The contract. A tool is a function; everything else here describes what goes in and what comes
+ * out, so a runtime can build an interface for a tool it has never seen.
+ *
+ * Two rules govern every change to this file:
+ *
+ *  1. **Additive only.** New output kinds and input types get added. Existing ones never change
+ *     meaning, never lose a field, and never gain a required one.
+ *  2. **No DOM, no framework, no host.** A tool must be runnable in plain Node, because that is how
+ *     its fixtures are checked. Anything that needs a browser belongs in the runtime, not here.
+ */
+/** Every kind this contract version can express. The runtime checks its renderers against this. */
+export const OUTPUT_KINDS = [
+    "fields",
+    "text",
+    "code",
+    "table",
+    "series",
+    "group",
+    "error",
+];
+export const INPUT_TYPES = ["text", "textarea", "number", "select", "toggle"];
+export const CAPABILITIES = ["pure"];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA6EH,mGAAmG;AACnG,MAAM,CAAC,MAAM,YAAY,GAA0B;IAClD,QAAQ;IACR,MAAM;IACN,MAAM;IACN,OAAO;IACP,QAAQ;IACR,OAAO;IACP,OAAO;CACP,CAAC;AA+BF,MAAM,CAAC,MAAM,WAAW,GAAyB,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAmBpG,MAAM,CAAC,MAAM,YAAY,GAA0B,CAAC,MAAM,CAAC,CAAC"}

package/dist/validate.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Manifest validation, hand-written on purpose.
+ *
+ * A schema library would be shorter, but it would also be a runtime dependency of the one package
+ * every tool author installs — and the error messages would be about JSON paths rather than about
+ * tools. These messages name the field, say what was wrong, and say what to do instead, because the
+ * person reading them is usually writing their first tool.
+ *
+ * ⚠️ The invariants at the bottom are the interesting part. They encode rules the rest of the system
+ * relies on, so a bad combination fails here rather than three layers later:
+ *
+ *  - a compact card may only run a `pure` tool;
+ *  - `timeoutMs` is meaningless on the main thread, so declaring it there is an error rather than a
+ *    silently ignored field;
+ *  - a tool may not declare an output kind this contract version cannot express.
+ */
+import { type Manifest } from "./types.ts";
+export declare class ManifestError extends Error {
+    readonly field: string;
+    constructor(field: string, message: string);
+}
+/**
+ * Validate a manifest that has already been brought up to the current contract version.
+ *
+ * Call `upgradeManifest` first unless you know the manifest is current — this function deliberately
+ * rejects an `sdk` it does not recognise rather than guessing.
+ */
+export declare function validateManifest(raw: unknown): Manifest;
+/** Human-readable summary of what a contract version offers. Used in error messages and docs. */
+export declare function describeSdkVersion(version: number): string;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAKN,KAAK,QAAQ,EAGb,MAAM,YAAY,CAAC;AAGpB,qBAAa,aAAc,SAAQ,KAAK;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBACX,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAwFD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAgHvD;AAED,iGAAiG;AACjG,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1D"}

package/dist/validate.js

@@ -0,0 +1,231 @@
+/**
+ * Manifest validation, hand-written on purpose.
+ *
+ * A schema library would be shorter, but it would also be a runtime dependency of the one package
+ * every tool author installs — and the error messages would be about JSON paths rather than about
+ * tools. These messages name the field, say what was wrong, and say what to do instead, because the
+ * person reading them is usually writing their first tool.
+ *
+ * ⚠️ The invariants at the bottom are the interesting part. They encode rules the rest of the system
+ * relies on, so a bad combination fails here rather than three layers later:
+ *
+ *  - a compact card may only run a `pure` tool;
+ *  - `timeoutMs` is meaningless on the main thread, so declaring it there is an error rather than a
+ *    silently ignored field;
+ *  - a tool may not declare an output kind this contract version cannot express.
+ */
+import { CAPABILITIES, INPUT_TYPES, OUTPUT_KINDS, } from "./types.js";
+import { SDK_CHANGELOG, SDK_VERSION, SUPPORTED_SDK_VERSIONS } from "./version.js";
+export class ManifestError extends Error {
+    field;
+    constructor(field, message) {
+        super(`${field}: ${message}`);
+        this.name = "ManifestError";
+        this.field = field;
+    }
+}
+const ID = /^[a-z0-9][a-z0-9-]*$/;
+function fail(field, message) {
+    throw new ManifestError(field, message);
+}
+function str(o, field, path) {
+    const v = o[field];
+    if (typeof v !== "string" || v.length === 0)
+        fail(`${path}${field}`, "must be a non-empty string");
+    return v;
+}
+function optStr(o, field, path) {
+    if (o[field] === undefined)
+        return undefined;
+    return str(o, field, path);
+}
+function obj(v, path) {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        fail(path, "must be an object");
+    return v;
+}
+function arr(v, path) {
+    if (!Array.isArray(v))
+        fail(path, "must be an array");
+    return v;
+}
+function oneOf(value, allowed, path) {
+    if (typeof value !== "string" || !allowed.includes(value)) {
+        fail(path, `must be one of ${allowed.map((a) => `"${a}"`).join(", ")}, got ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+function validateInput(raw, path) {
+    const o = obj(raw, path);
+    const id = str(o, "id", `${path}.`);
+    if (!ID.test(id))
+        fail(`${path}.id`, `"${id}" must be lowercase letters, digits and hyphens`);
+    str(o, "label", `${path}.`);
+    optStr(o, "description", `${path}.`);
+    optStr(o, "unit", `${path}.`);
+    if (o.primary !== undefined && typeof o.primary !== "boolean")
+        fail(`${path}.primary`, "must be a boolean");
+    if (o.dir !== undefined)
+        oneOf(o.dir, ["ltr", "auto"], `${path}.dir`);
+    const type = oneOf(o.type, INPUT_TYPES, `${path}.type`);
+    switch (type) {
+        case "text":
+        case "textarea": {
+            if (typeof o.default !== "string")
+                fail(`${path}.default`, `a ${type} input needs a string default`);
+            break;
+        }
+        case "number": {
+            if (typeof o.default !== "number" || !Number.isFinite(o.default)) {
+                fail(`${path}.default`, "a number input needs a finite number default");
+            }
+            if (typeof o.min !== "number" || typeof o.max !== "number") {
+                fail(`${path}.min/max`, "a number input must declare min and max — they are the only guard against a runaway input");
+            }
+            if (o.min >= o.max)
+                fail(`${path}.min`, `min (${o.min}) must be below max (${o.max})`);
+            if (o.default < o.min || o.default > o.max) {
+                fail(`${path}.default`, `default ${o.default} is outside min..max (${o.min}..${o.max})`);
+            }
+            break;
+        }
+        case "select": {
+            const options = arr(o.options, `${path}.options`);
+            if (options.length < 2)
+                fail(`${path}.options`, "a select needs at least two options; with one, use a fixed value");
+            const values = options.map((opt, i) => {
+                const oo = obj(opt, `${path}.options[${i}]`);
+                str(oo, "label", `${path}.options[${i}].`);
+                return str(oo, "value", `${path}.options[${i}].`);
+            });
+            if (new Set(values).size !== values.length)
+                fail(`${path}.options`, "option values must be unique");
+            if (typeof o.default !== "string" || !values.includes(o.default)) {
+                fail(`${path}.default`, `must be one of the option values: ${values.join(", ")}`);
+            }
+            break;
+        }
+        case "toggle": {
+            if (typeof o.default !== "boolean")
+                fail(`${path}.default`, "a toggle input needs a boolean default");
+            break;
+        }
+    }
+    return raw;
+}
+/**
+ * Validate a manifest that has already been brought up to the current contract version.
+ *
+ * Call `upgradeManifest` first unless you know the manifest is current — this function deliberately
+ * rejects an `sdk` it does not recognise rather than guessing.
+ */
+export function validateManifest(raw) {
+    const o = obj(raw, "manifest");
+    // --- the contract version, first, because it decides how to read everything else -------------
+    if (typeof o.sdk !== "number" || !Number.isInteger(o.sdk)) {
+        fail("sdk", `must be an integer contract version; this SDK speaks ${SUPPORTED_SDK_VERSIONS.join(", ")}`);
+    }
+    if (o.sdk > SDK_VERSION) {
+        fail("sdk", `this tool needs contract version ${o.sdk}, but this runtime only speaks up to ${SDK_VERSION}. ` +
+            "Upgrade @toolbench/runtime, or lower the tool's sdk if it does not use the newer features.");
+    }
+    if (!SUPPORTED_SDK_VERSIONS.includes(o.sdk)) {
+        fail("sdk", `contract version ${o.sdk} is not one this SDK can read (${SUPPORTED_SDK_VERSIONS.join(", ")})`);
+    }
+    // --- identity ---------------------------------------------------------------------------------
+    const id = str(o, "id", "");
+    if (!ID.test(id))
+        fail("id", `"${id}" must be lowercase letters, digits and hyphens — it is also a directory name and a URL segment`);
+    str(o, "name", "");
+    const blurb = str(o, "blurb", "");
+    if (blurb.length > 200)
+        fail("blurb", `is ${blurb.length} characters; keep it under 200 so it works as a card line and a page description`);
+    str(o, "version", "");
+    if (o.status !== undefined)
+        oneOf(o.status, ["live", "deprecated", "retired"], "status");
+    if (o.help !== undefined)
+        optStr(o, "help", "");
+    if (o.tags !== undefined)
+        arr(o.tags, "tags").forEach((t, i) => { if (typeof t !== "string")
+            fail(`tags[${i}]`, "must be a string"); });
+    if (o.links !== undefined) {
+        arr(o.links, "links").forEach((l, i) => {
+            const lo = obj(l, `links[${i}]`);
+            str(lo, "label", `links[${i}].`);
+            str(lo, "href", `links[${i}].`);
+        });
+    }
+    // --- capabilities -----------------------------------------------------------------------------
+    const caps = arr(o.capabilities, "capabilities");
+    if (caps.length === 0)
+        fail("capabilities", `must declare at least one of ${CAPABILITIES.join(", ")}`);
+    const capabilities = caps.map((c, i) => oneOf(c, CAPABILITIES, `capabilities[${i}]`));
+    // --- runtime ----------------------------------------------------------------------------------
+    const runtime = obj(o.runtime, "runtime");
+    str(runtime, "entry", "runtime.");
+    const thread = runtime.thread === undefined ? "main" : oneOf(runtime.thread, ["main", "worker"], "runtime.thread");
+    // --- inputs -----------------------------------------------------------------------------------
+    const inputs = arr(o.inputs, "inputs");
+    if (inputs.length === 0)
+        fail("inputs", "a tool needs at least one input; a tool with none is a constant");
+    const specs = inputs.map((input, i) => validateInput(input, `inputs[${i}]`));
+    const ids = specs.map((s) => s.id);
+    if (new Set(ids).size !== ids.length)
+        fail("inputs", `input ids must be unique, got ${ids.join(", ")}`);
+    const primaries = specs.filter((s) => s.primary === true);
+    if (primaries.length > 1) {
+        fail("inputs", `only one input may be primary (a compact card shows exactly one), got ${primaries.map((p) => p.id).join(", ")}`);
+    }
+    // --- output kinds -----------------------------------------------------------------------------
+    const kinds = arr(o.kinds, "kinds");
+    if (kinds.length === 0)
+        fail("kinds", "declare every output kind `run` can return, so a host can refuse a tool it cannot draw");
+    const outputKinds = kinds.map((k, i) => oneOf(k, OUTPUT_KINDS, `kinds[${i}]`));
+    if (!outputKinds.includes("error")) {
+        fail("kinds", 'must include "error" — every tool can be given bad input, and saying so is part of working correctly');
+    }
+    // --- card -------------------------------------------------------------------------------------
+    const card = o.card === undefined ? "info" : oneOf(o.card, ["live", "info", "none"], "card");
+    if (o.cardFields !== undefined && (typeof o.cardFields !== "number" || o.cardFields < 1)) {
+        fail("cardFields", "must be a positive number of fields");
+    }
+    if (o.autoRun !== undefined && typeof o.autoRun !== "boolean")
+        fail("autoRun", "must be a boolean");
+    // --- timeout ----------------------------------------------------------------------------------
+    if (o.timeoutMs !== undefined) {
+        if (typeof o.timeoutMs !== "number" || o.timeoutMs < 100 || o.timeoutMs > 30_000) {
+            fail("timeoutMs", "must be between 100 and 30000 ms");
+        }
+    }
+    /*
+     * --- the invariants ---------------------------------------------------------------------------
+     * These are the rules the rest of the system leans on. Failing here is the whole point: a bad
+     * combination becomes a manifest error the author sees immediately, rather than a subtle problem
+     * a reader finds later.
+     */
+    if (card === "live" && !(capabilities.length === 1 && capabilities[0] === "pure")) {
+        fail("card", 'only a "pure" tool may be a live card — a compact slot must not read files or call networks');
+    }
+    if (o.autoRun === true && thread === "worker") {
+        fail("autoRun", 'is for tools that are instant, and a worker-mode tool is by definition not — it declared thread: "worker" ' +
+            "because its running time depends on its input. Leave autoRun off and let the reader press Run.");
+    }
+    if (thread === "main" && o.timeoutMs !== undefined) {
+        fail("timeoutMs", "is only meaningful with runtime.thread = \"worker\". On the main thread there is nothing to terminate, " +
+            "so a timeout here would be a field that lies. Either move the tool to a worker or bound its input.");
+    }
+    return {
+        ...raw,
+        capabilities,
+        inputs: specs,
+        kinds: outputKinds,
+        runtime: { ...runtime, entry: runtime.entry, thread },
+        card,
+        status: o.status ?? "live",
+    };
+}
+/** Human-readable summary of what a contract version offers. Used in error messages and docs. */
+export function describeSdkVersion(version) {
+    return SDK_CHANGELOG[version] ?? `unknown contract version ${version}`;
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The version of the CONTRACT, not of any package.
+ *
+ * Every tool declares `sdk: <n>` in its manifest, and the runtime supports every version it has
+ * ever shipped. Raising this number is a deliberate act with a checklist — see docs/versioning.md.
+ */
+export declare const SDK_VERSION = 1;
+/** Every contract version this SDK can read. Never shrinks. */
+export declare const SUPPORTED_SDK_VERSIONS: readonly number[];
+/**
+ * What each contract version added. Kept as data so the runtime can explain itself: when a tool
+ * asks for a version we do not have, the error can say what it would need rather than just failing.
+ */
+export declare const SDK_CHANGELOG: Record<number, string>;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,WAAW,IAAI,CAAC;AAE7B,+DAA+D;AAC/D,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAAQ,CAAC;AAE7D;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAEhD,CAAC"}

package/dist/version.js

@@ -0,0 +1,17 @@
+/**
+ * The version of the CONTRACT, not of any package.
+ *
+ * Every tool declares `sdk: <n>` in its manifest, and the runtime supports every version it has
+ * ever shipped. Raising this number is a deliberate act with a checklist — see docs/versioning.md.
+ */
+export const SDK_VERSION = 1;
+/** Every contract version this SDK can read. Never shrinks. */
+export const SUPPORTED_SDK_VERSIONS = [1];
+/**
+ * What each contract version added. Kept as data so the runtime can explain itself: when a tool
+ * asks for a version we do not have, the error can say what it would need rather than just failing.
+ */
+export const SDK_CHANGELOG = {
+    1: "computation and visualisation: fields, text, code, table, series, group, error outputs; text, textarea, number, select, toggle inputs; pure capability; main and worker threads.",
+};
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC;AAE7B,+DAA+D;AAC/D,MAAM,CAAC,MAAM,sBAAsB,GAAsB,CAAC,CAAC,CAAC,CAAC;AAE7D;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAA2B;IACpD,CAAC,EAAE,kLAAkL;CACrL,CAAC"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@toolbench/sdk",
+  "version": "0.1.0",
+  "description": "The contract a Toolbench tool implements: types, manifest validation, version migration, and a fixture runner. No runtime dependencies, no DOM.",
+  "license": "MIT",
+  "author": "Ahmed Elmalt",
+  "homepage": "https://github.com/eknowledger/toolbench#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eknowledger/toolbench.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/eknowledger/toolbench/issues"
+  },
+  "keywords": [
+    "toolbench",
+    "interactive",
+    "widget",
+    "tool",
+    "manifest",
+    "validation",
+    "fixtures",
+    "typescript",
+    "zero-dependencies"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  }
+}