@akshatmittal/invoker 0.3.0 → 0.4.0

package/README.md

@@ -98,23 +98,29 @@ scheduler intentionally has no HTTP health endpoint.
 
 ## Define a Workflow
 
+Declare a Task's required parameters once, then bind them from each Workflow.
+TypeScript checks the bindings while inferring the Task's Matrix, setup, and Output:
+
 ```ts
 // regressions/model/tasks/evaluate-models.ts
 import { defineTask } from "@akshatmittal/invoker";
 
-export const evaluateModels = defineTask({
+type EvaluateParams = {
+  environment: "staging" | "production";
+  baseline: string;
+};
+
+export const evaluateModels = defineTask<EvaluateParams>()({
   name: "evaluate-models",
-  matrix: async () => ({
-    model: ["gpt-5", "gpt-5-mini"],
+  matrix: async ({ params }) => ({
+    model: await discoverModels(params.environment),
     dataset: ["support", "sales"],
   }),
-  setup: async ({ cases }) => loadFixtures(cases),
-  run: async ({ matrix, setup, vitest }) => {
+  setup: async ({ params, cases }) => loadFixtures(params.environment, cases),
+  run: async ({ params, matrix, setup, vitest }) => {
     vitest.expect(setup.has(matrix.dataset)).toBe(true);
-
     return {
-      model: matrix.model,
-      dataset: matrix.dataset,
+      baseline: params.baseline,
       score: await evaluate(matrix, setup),
     };
   },
@@ -131,21 +137,51 @@ import { evaluateModels } from "../tasks/evaluate-models.js";
 
 defineWorkflow({
   name: "model-regressions",
-  metadata: {
-    commit: process.env.GITHUB_SHA ?? "local",
-    baseline: "2026-08-01",
-  },
-  tasks: [evaluateModels],
+  metadata: { commit: process.env.GITHUB_SHA ?? "local" },
+  matrix: async () => ({ environment: ["staging", "production"] }),
+  tasks: ({ matrix }) => [
+    evaluateModels({
+      environment: matrix.environment,
+      baseline: "2026-09-01",
+    }),
+  ],
 });
 ```
 
-The Matrix function runs during collection and its returned literal determines the exact
-`matrix` type. `setup` determines the exact
-shared setup type, and the exact JSON return type is retained on the Task.
-Axis names must be non-empty, enumerable strings that are not array indexes.
-Omitting `matrix` creates one Case with `{}`. Setup runs once per Task, Cases
-within that Task run concurrently, and teardown runs once after successful
-setup. Tasks run sequentially in their Workflow.
+Calling `evaluateModels(...)` binds inputs; it does not execute the Task. All
+parameter properties are required and JSON-compatible. Missing fields, optional
+parameter declarations, and incompatible bindings fail typechecking. There is no
+SDK defaults mechanism. Use setup for clients and other non-JSON resources.
+
+For a parameterless Task, use `defineTask()({ name, run })` and bind it with no
+argument. Workflow `tasks` is always a synchronous callback returning a nonempty
+Task list. It can select different Tasks per Workflow coordinate; names must be
+unique within each coordinate. Reuse the same Task in other Workflows with new
+bindings.
+
+Both Matrix functions run during collection. The Workflow Matrix resolves once;
+Task binding runs once per Workflow coordinate, and each bound Task discovers its
+own Matrix once. Task discovery can run concurrently across coordinates. All
+bindings and matrices are validated before executable suites are registered; a
+discovery failure prevents that Workflow's execution.
+
+Workflow axes multiply Task axes. For two environments and three Task models,
+there are six Cases. Execution follows the complete Task sequence for staging,
+then the complete sequence for production. Each bound Task gets its own setup and
+teardown, and its Cases run concurrently under Vitest's limits. Execution failures
+normally allow later Tasks to continue; Vitest's bail configuration controls
+stopping early.
+
+Parameters are validated and snapshotted during collection and passed readonly to
+Matrix discovery, setup, run, and teardown. Task `matrix` and setup's `cases`
+contain only Task coordinates; Workflow coordinates enter through explicit
+parameter binding. Retries share that binding's parameter snapshot and setup
+result. Teardown runs once after successful setup.
+
+Omitting either Matrix creates one coordinate, `{}`. Axis names must be non-empty,
+enumerable strings that are not array indexes. Empty axes and duplicate values
+are errors. Vitest shows Workflow → Workflow coordinate → Task → Case, with `[1]`
+for empty coordinates and numbered axis values otherwise.
 
 ## Configure Vitest
 
@@ -178,34 +214,43 @@ Define additional Workflows in separate `*.test.ts` files. Vitest discovers
 them automatically; Invoker does not scan directories or require a central
 index.
 
-The metadata envelope is stable and JSON-compatible:
+Schema 2 keeps both coordinate scopes and all bound parameters in the JSON report:
 
 ```json
 {
-  "schema": 1,
-  "matrix": { "model": "gpt-5", "dataset": "support" },
+  "schema": 2,
+  "matrix": {
+    "workflow": { "environment": "staging" },
+    "task": { "model": "model-a", "dataset": "support" }
+  },
+  "params": { "environment": "staging", "baseline": "2026-09-01" },
   "metadata": { "commit": "abc123" },
-  "output": { "model": "gpt-5", "dataset": "support", "score": 0.92 }
+  "output": { "baseline": "2026-09-01", "score": 0.92 }
 }
 ```
 
-`output` is present only after a successful, JSON-valid Task return. Vitest's
-report remains authoritative for status, failures, timing, hierarchy, and
+`matrix.workflow`, `matrix.task`, and `params` are always present, with `{}` for
+empty scopes. Parameters are persisted in full, including fixed configuration;
+there is no automatic redaction. Static coordinates and parameters survive setup
+failures, skips, and retries. `output` is present only after a successful,
+JSON-valid Task return and is cleared before every retry. Vitest's report remains authoritative for status, failures, timing, hierarchy, and
 retries.
 
 ## Notify Slack
 
 Invoker's optional Slack reporter posts one `Invoker Report` parent message per
-Vitest run. It places additional Workflow cards in the message thread so every
-Task table remains within Slack's row and character limits. Each card includes
-aggregate results, Workflow metadata, and a table of Task counts and durations.
-A shared footer contains the elapsed span from the first Case start to the final
-Case completion, a localized timestamp, and the optional run link. Final
-failures are posted in the same thread with one reply per failed Task in each
-Workflow. Unhandled run errors are reported once. Delivery failures are
-isolated to the affected reply. Ambiguous transport failures are not retried;
-an explicit Slack rate-limit rejection is reattempted only after its required
-delay.
+Vitest run containing every Workflow card. Each card includes aggregate results,
+Workflow metadata, and a table with counts and durations per Workflow
+coordinate/Task pair. Failures, retries, and skips identify both Matrix scopes.
+Collection failures produce a failed Workflow card even without collected Cases.
+Full parameters are persisted in JSON rather than printed automatically in Slack.
+A shared footer
+contains the elapsed span from the first Case start to the final Case completion,
+a localized timestamp, and the optional run link. Final failures, successful
+retry details, skipped Case reasons, and unhandled run errors are posted in the
+same thread. Delivery failures are isolated to the affected reply. Ambiguous
+transport failures are not retried; an explicit Slack rate-limit rejection is
+reattempted only after its required delay.
 
 ```ts
 import { slackReporter } from "@akshatmittal/invoker/slack";

package/dist/errors-CMczwLz9.mjs

@@ -0,0 +1,16 @@
+import { z } from "zod";
+//#region src/errors.ts
+const errorMessageSchema = z.object({ message: z.string() });
+const errorStackSchema = z.object({ stack: z.string() });
+function errorMessage(cause) {
+	const message = errorMessageSchema.safeParse(cause);
+	if (message.success) return message.data.message;
+	const stack = errorStackSchema.safeParse(cause);
+	if (stack.success) return stack.data.stack.split("\n", 1)[0];
+	return String(cause);
+}
+function errorWithContext(context, cause) {
+	return new Error(`${context}: ${errorMessage(cause)}`, { cause });
+}
+//#endregion
+export { errorWithContext as n, errorMessage as t };

package/dist/index.d.mts

@@ -11,63 +11,70 @@ type Matrix = {
   readonly [axis: string]: readonly JsonValue[];
 };
 type CaseCoordinates<M extends Matrix> = { readonly [K in keyof M]: M[K][number]; };
-interface InvokerMeta<Coordinates extends JsonObject, Output extends JsonValue, Metadata extends JsonObject = JsonObject> {
-  schema: 1;
-  matrix: Coordinates;
+interface InvokerMeta<Coordinates extends JsonObject, Output extends JsonValue, Metadata extends JsonObject = JsonObject, WorkflowCoordinates extends JsonObject = JsonObject, Params extends JsonObject = JsonObject> {
+  schema: 2;
+  matrix: {
+    workflow: WorkflowCoordinates;
+    task: Coordinates;
+  };
+  params: Params;
   metadata?: Metadata;
   output?: Output;
 }
-interface TaskContext<Coordinates, Setup> {
+interface TaskContext<Coordinates, Setup, Params = Record<never, never>> extends ParamsContext<Params> {
   readonly matrix: Coordinates;
   readonly setup: Setup;
   readonly vitest: TestContext;
 }
 type Awaitable<Value> = Value | PromiseLike<Value>;
-type SetupContext<M extends Matrix> = {
+type DeepReadonly<Value> = JsonValue extends Value ? Value : { readonly [Key in keyof Value]: DeepReadonly<Value[Key]>; };
+type ParamsContext<Params> = {
+  readonly params: DeepReadonly<Params>;
+};
+type SetupContext<M extends Matrix, Params = Record<never, never>> = ParamsContext<Params> & {
   readonly cases: readonly CaseCoordinates<M>[];
 };
-type TeardownContext<M extends Matrix, Setup> = SetupContext<M> & {
+type TeardownContext<M extends Matrix, Setup, Params = Record<never, never>> = SetupContext<M, Params> & {
   readonly setup: Setup;
 };
 //#endregion
 //#region src/task.d.ts
-declare const taskDefinitionBrand: unique symbol;
-interface TaskDefinition<Name extends string = string, M extends Matrix = Matrix, Setup = unknown, Output extends JsonValue = JsonValue> {
-  readonly name: Name;
-  readonly matrix: () => Promise<M>;
-  readonly [taskDefinitionBrand]: true;
-  readonly setup?: (context: SetupContext<M>) => Awaitable<Setup>;
-  readonly run: (context: TaskContext<CaseCoordinates<M>, Setup>) => Awaitable<Output>;
-  readonly teardown?: (context: TeardownContext<M, Setup>) => Awaitable<void>;
-}
-type TaskWithSetup<Name extends string, M extends Matrix, Setup, Output extends JsonValue> = {
-  readonly name: Name;
-  readonly matrix?: () => Promise<M>;
-  readonly setup: (context: SetupContext<M>) => Awaitable<Setup>;
-  readonly run: (context: TaskContext<CaseCoordinates<M>, Setup>) => Awaitable<Output>;
-  readonly teardown?: (context: TeardownContext<M, Setup>) => Awaitable<void>;
-};
-type TaskWithoutSetup<Name extends string, M extends Matrix, Output extends JsonValue> = {
+declare const taskBindingBrand: unique symbol;
+type ParameterArguments<Params> = [Params] extends [Record<string, never>] ? [] : [params: Params];
+type RequiredParameters<Params> = { [Key in keyof Params]-?: Params[Key] extends JsonValue ? RequiredParameters<Params[Key]> : never; };
+type TaskDefinition<Name extends string = string, M extends Matrix = Matrix, Setup = unknown, Output extends JsonValue = JsonValue, Params extends JsonObject = Record<never, never>> = (...args: ParameterArguments<Params>) => BoundTask<Name, M, Setup, Output, Params>;
+type TaskOptions<Name extends string, M extends Matrix, Setup, Output extends JsonValue, Params> = {
   readonly name: Name;
-  readonly matrix?: () => Promise<M>;
-  readonly setup?: never;
-  readonly run: (context: TaskContext<CaseCoordinates<M>, undefined>) => Awaitable<Output>;
-  readonly teardown?: never;
+  readonly matrix?: (context: ParamsContext<Params>) => Promise<M>;
+  readonly setup?: (context: SetupContext<M, Params>) => Awaitable<Setup>;
+  readonly run: (context: TaskContext<CaseCoordinates<M>, Setup, Params>) => Awaitable<Output>;
+  readonly teardown?: (context: TeardownContext<M, Setup, Params>) => Awaitable<void>;
 };
-declare function defineTask<const Name extends string, const M extends Matrix = Record<never, never>, Setup = unknown, const Output extends JsonValue = JsonValue>(definition: TaskWithSetup<Name, M, Setup, Output>): TaskDefinition<Name, M, Setup, Output>;
-declare function defineTask<const Name extends string, const M extends Matrix = Record<never, never>, const Output extends JsonValue = JsonValue>(definition: TaskWithoutSetup<Name, M, Output>): TaskDefinition<Name, M, undefined, Output>;
-type AnyTaskDefinition = {
-  readonly name: string;
-  readonly matrix: () => Promise<Matrix>;
-  readonly [taskDefinitionBrand]: true;
+interface BoundTask<Name extends string, M extends Matrix, Setup, Output extends JsonValue, Params extends JsonObject> extends TaskOptions<Name, M, Setup, Output, Params>, ParamsContext<Params> {
+  readonly matrix: (context: ParamsContext<Params>) => Promise<M>;
+  readonly [taskBindingBrand]: true;
+}
+declare function defineTask<Params extends Record<keyof Params, JsonValue> & RequiredParameters<Params> = Record<never, never>>(): {
+  <const Name extends string, const M extends Matrix = Record<never, never>, Setup = unknown, const Output extends JsonValue = JsonValue>(definition: TaskOptions<Name, M, Setup, Output, Params> & {
+    readonly setup: (context: SetupContext<M, Params>) => Awaitable<Setup>;
+  }): TaskDefinition<Name, M, Setup, Output, Params>;
+  <const Name extends string, const M extends Matrix = Record<never, never>, const Output extends JsonValue = JsonValue>(definition: TaskOptions<Name, M, undefined, Output, Params> & {
+    readonly setup?: never;
+    readonly teardown?: never;
+  }): TaskDefinition<Name, M, undefined, Output, Params>;
 };
+type AnyTaskBinding = Pick<RuntimeTask, "name" | "params" | typeof taskBindingBrand>;
+type RuntimeTask = BoundTask<string, Matrix, unknown, JsonValue, JsonObject>;
 //#endregion
 //#region src/workflow.d.ts
-type WorkflowDefinition<Tasks extends readonly [AnyTaskDefinition, ...AnyTaskDefinition[]], Metadata extends JsonObject> = {
+type WorkflowDefinition<M extends Matrix, Metadata extends JsonObject> = {
   readonly name: string;
   readonly metadata?: Metadata;
-  readonly tasks: Tasks;
+  readonly matrix?: () => Promise<M>;
+  readonly tasks: (context: {
+    readonly matrix: CaseCoordinates<M>;
+  }) => readonly [AnyTaskBinding, ...AnyTaskBinding[]];
 };
-declare function defineWorkflow<const Tasks extends readonly [AnyTaskDefinition, ...AnyTaskDefinition[]], const Metadata extends JsonObject = JsonObject>(definition: WorkflowDefinition<Tasks, Metadata>): void;
+declare function defineWorkflow<const M extends Matrix = Record<never, never>, const Metadata extends JsonObject = JsonObject>(definition: WorkflowDefinition<M, Metadata>): void;
 //#endregion
 export { type CaseCoordinates, type InvokerMeta, type JsonObject, type JsonPrimitive, type JsonValue, type Matrix, type TaskContext, type TaskDefinition, defineTask, defineWorkflow };

package/dist/index.mjs

@@ -1,13 +1,20 @@
-import { beforeAll, describe, test } from "vitest";
+import { n as errorWithContext } from "./errors-CMczwLz9.mjs";
+import { TestRunner, beforeAll, describe, test } from "vitest";
 import { z } from "zod";
 //#region src/task.ts
-const taskDefinitionBrand = Symbol("invoker.task");
-function defineTask(definition) {
-	return {
-		...definition,
-		matrix: definition.matrix ?? (async () => ({})),
-		[taskDefinitionBrand]: true
-	};
+const taskBindingBrand = Symbol("invoker.task-binding");
+function defineTask() {
+	function define(definition) {
+		return (...args) => {
+			return {
+				...definition,
+				params: args.length === 0 ? {} : args[0],
+				matrix: definition.matrix ?? (async () => ({})),
+				[taskBindingBrand]: true
+			};
+		};
+	}
+	return define;
 }
 //#endregion
 //#region src/json.ts
@@ -18,8 +25,8 @@ const scalarSchema = z.union([
 	z.number()
 ]);
 const nameSchema = z.string().trim().min(1);
-function snapshotJson(value, owner, path, ancestors = /* @__PURE__ */ new Set()) {
-	return cloneJson(value, owner, path, ancestors);
+function snapshotJson(value, owner, path) {
+	return cloneJson(value, owner, path, /* @__PURE__ */ new Set());
 }
 function cloneJson(value, owner, path, ancestors) {
 	if (scalarSchema.safeParse(value).success) return value;
@@ -34,13 +41,12 @@ function cloneJson(value, owner, path, ancestors) {
 		}
 		ancestors.delete(value);
 		return snapshot;
-	} else {
-		assertPlainObject(value, owner, path);
-		if (Object.getOwnPropertySymbols(value).length > 0) fail(owner, path, "JSON objects cannot have symbol keys");
-		const snapshot = Object.fromEntries(Object.entries(value).map(([key, child]) => [key, cloneJson(child, owner, `${path}.${key}`, ancestors)]));
-		ancestors.delete(value);
-		return snapshot;
 	}
+	assertPlainObject(value, owner, path);
+	if (Object.getOwnPropertySymbols(value).length > 0) fail(owner, path, "JSON objects cannot have symbol keys");
+	const snapshot = Object.fromEntries(Object.entries(value).map(([key, child]) => [key, cloneJson(child, owner, `${path}.${key}`, ancestors)]));
+	ancestors.delete(value);
+	return snapshot;
 }
 function assertPlainObject(value, owner, path) {
 	if (Object(value) !== value || Array.isArray(value)) fail(owner, path, "expected a plain object");
@@ -103,89 +109,155 @@ function caseName(matrix, index) {
 }
 //#endregion
 //#region src/workflow.ts
+const functionSchema = z.function();
 function defineWorkflow(definition) {
-	describe(definition.name, { concurrent: false }, async () => {
-		const tasks = await prepareWorkflow(definition);
-		for (const prepared of tasks) describe(prepared.task.name, { concurrent: false }, () => {
-			let setup;
-			const setupTask = prepared.task.setup;
-			if (setupTask) beforeAll(async () => {
-				setup = await setupTask({ cases: prepared.cases });
-				const teardownTask = prepared.task.teardown;
-				if (teardownTask) return () => teardownTask({
-					cases: prepared.cases,
-					setup
-				});
+	const info = { name: definition.name };
+	const meta = { invokerWorkflow: info };
+	describe(definition.name, {
+		concurrent: false,
+		shuffle: false,
+		meta
+	}, async () => {
+		const file = TestRunner.getCurrentSuite().file;
+		try {
+			const coordinates = await prepareWorkflow(definition, info);
+			for (const [index, coordinate] of coordinates.entries()) describe(caseName(coordinate.matrix, index), {
+				concurrent: false,
+				meta: { invokerWorkflow: null }
+			}, () => {
+				for (const prepared of coordinate.tasks) registerTask(prepared, coordinate.matrix, info.metadata);
+			});
+		} catch (cause) {
+			Object.assign(file.meta, { invokerCollectionError: info });
+			throw errorWithContext(`Workflow ${JSON.stringify(info.name)} collection failed`, cause);
+		}
+	});
+}
+function registerTask(prepared, workflow, metadata) {
+	const { task, cases } = prepared;
+	const { params } = task;
+	describe(task.name, { concurrent: false }, () => {
+		let setup;
+		const setupTask = task.setup;
+		if (setupTask) beforeAll(async () => {
+			setup = await setupTask({
+				params,
+				cases
+			});
+			const teardownTask = task.teardown;
+			if (teardownTask) return () => teardownTask({
+				params,
+				cases,
+				setup
 			});
-			for (const [index, matrix] of prepared.cases.entries()) {
-				const name = prepared.names[index];
-				const invoker = prepared.metadata[index];
-				test.concurrent(name, { meta: { invoker } }, async (vitest) => {
-					const meta = vitest.task.meta;
-					delete meta.invoker.output;
-					const output = await prepared.task.run({
-						matrix,
-						setup,
-						vitest
-					});
-					meta.invoker.output = snapshotJson(output, `Task ${JSON.stringify(prepared.task.name)}`, ".output");
-				});
-			}
 		});
+		for (const [index, matrix] of cases.entries()) {
+			const invoker = {
+				schema: 2,
+				matrix: {
+					workflow,
+					task: matrix
+				},
+				params
+			};
+			if (metadata !== void 0) invoker.metadata = metadata;
+			test.concurrent(caseName(matrix, index), { meta: { invoker } }, async (vitest) => {
+				const meta = vitest.task.meta;
+				delete meta.invoker.output;
+				const output = await task.run({
+					params,
+					matrix,
+					setup,
+					vitest
+				});
+				meta.invoker.output = snapshotJson(output, `Task ${JSON.stringify(task.name)}`, ".output");
+			});
+		}
 	});
 }
-async function prepareWorkflow(definition) {
+async function prepareWorkflow(definition, info) {
 	assertPlainObject(definition, "Workflow", "");
 	assertOnlyKeys(definition, [
 		"name",
 		"metadata",
+		"matrix",
 		"tasks"
 	], "Workflow");
-	const { name, metadata: workflowMetadata, tasks: taskDefinitions } = definition;
-	assertName(name, "Workflow", ".name");
-	const metadata = workflowMetadata === void 0 ? void 0 : snapshotJson(workflowMetadata, `Workflow ${JSON.stringify(name)}`, ".metadata");
-	if (metadata !== void 0) assertPlainObject(metadata, `Workflow ${JSON.stringify(name)}`, ".metadata");
-	if (!Array.isArray(taskDefinitions) || taskDefinitions.length === 0) fail("Workflow", ".tasks", "expected a non-empty Task tuple");
-	const names = /* @__PURE__ */ new Set();
-	const tasks = taskDefinitions.map((value, index) => {
-		const owner = `Workflow ${JSON.stringify(name)} Task ${index + 1}`;
-		assertPlainObject(value, owner, "");
-		if (value[taskDefinitionBrand] !== true) fail(owner, "", "expected a Task created by defineTask");
-		const task = value;
-		assertOnlyKeys(task, [
-			"name",
-			"matrix",
-			"setup",
-			"run",
-			"teardown"
-		], owner);
-		const taskSnapshot = { ...task };
-		assertName(taskSnapshot.name, owner, ".name");
-		if (names.has(taskSnapshot.name)) fail(owner, ".name", `duplicate Task name ${JSON.stringify(taskSnapshot.name)}`);
-		names.add(taskSnapshot.name);
-		if (!z.function().safeParse(taskSnapshot.run).success) fail(owner, ".run", "expected a function");
-		if (!z.function().safeParse(taskSnapshot.matrix).success) fail(owner, ".matrix", "expected a function");
-		if (taskSnapshot.setup !== void 0 && !z.function().safeParse(taskSnapshot.setup).success) fail(owner, ".setup", "expected a function");
-		if (taskSnapshot.teardown !== void 0 && !z.function().safeParse(taskSnapshot.teardown).success) fail(owner, ".teardown", "expected a function");
-		if (taskSnapshot.teardown && !taskSnapshot.setup) fail(owner, ".teardown", "requires setup");
-		return taskSnapshot;
+	assertName(definition.name, "Workflow", ".name");
+	const owner = `Workflow ${JSON.stringify(definition.name)}`;
+	if (definition.metadata !== void 0) {
+		const metadata = snapshotJson(definition.metadata, owner, ".metadata");
+		assertPlainObject(metadata, owner, ".metadata");
+		info.metadata = metadata;
+	}
+	if (!functionSchema.safeParse(definition.tasks).success) fail(owner, ".tasks", "expected a synchronous function");
+	if (definition.matrix !== void 0 && !functionSchema.safeParse(definition.matrix).success) fail(owner, ".matrix", "expected a function");
+	const coordinates = expandMatrix(definition.matrix ? await definition.matrix() : {}, owner).map((coordinate, index) => {
+		const coordinateOwner = `${owner} coordinate ${caseName(coordinate, index)}`;
+		return {
+			matrix: coordinate,
+			owner: coordinateOwner,
+			tasks: bindTasks(definition, coordinate, coordinateOwner)
+		};
 	});
-	return await Promise.all(tasks.map(async (task) => {
-		const cases = expandMatrix(await task.matrix(), `Task ${JSON.stringify(task.name)}`);
+	return Promise.all(coordinates.map(async (coordinate) => ({
+		matrix: coordinate.matrix,
+		tasks: await Promise.all(coordinate.tasks.map((task) => discoverTask(task, coordinate.owner)))
+	})));
+}
+function bindTasks(definition, matrix, owner) {
+	try {
+		const bindings = definition.tasks({ matrix });
+		if (!Array.isArray(bindings) || bindings.length === 0) fail(owner, ".tasks", "expected a non-empty Task tuple");
+		const names = /* @__PURE__ */ new Set();
+		return bindings.map((binding) => prepareBinding(binding, owner, names));
+	} catch (cause) {
+		throw errorWithContext(`${owner} Task binding failed`, cause);
+	}
+}
+async function discoverTask(task, owner) {
+	const taskOwner = `${owner} Task ${JSON.stringify(task.name)}`;
+	try {
 		return {
 			task,
-			cases,
-			names: cases.map(caseName),
-			metadata: cases.map((matrix) => metadata === void 0 ? {
-				schema: 1,
-				matrix
-			} : {
-				schema: 1,
-				matrix,
-				metadata
-			})
+			cases: expandMatrix(await task.matrix({ params: task.params }), taskOwner)
 		};
-	}));
+	} catch (cause) {
+		throw errorWithContext(`${taskOwner} Matrix discovery failed`, cause);
+	}
+}
+function prepareBinding(binding, owner, names) {
+	assertPlainObject(binding, owner, ".tasks");
+	if (binding[taskBindingBrand] !== true) fail(owner, ".tasks", "expected a bound Task created by defineTask");
+	const task = binding;
+	assertOnlyKeys(task, [
+		"name",
+		"params",
+		"matrix",
+		"setup",
+		"run",
+		"teardown"
+	], owner);
+	assertName(task.name, owner, ".tasks.name");
+	if (names.has(task.name)) fail(owner, ".tasks", `duplicate Task name ${JSON.stringify(task.name)}`);
+	names.add(task.name);
+	const taskOwner = `${owner} Task ${JSON.stringify(task.name)}`;
+	for (const key of [
+		"matrix",
+		"run",
+		"setup",
+		"teardown"
+	]) {
+		if ((key === "setup" || key === "teardown") && task[key] === void 0) continue;
+		if (!functionSchema.safeParse(task[key]).success) fail(taskOwner, `.${key}`, "expected a function");
+	}
+	if (task.teardown && !task.setup) fail(taskOwner, ".teardown", "requires setup");
+	const params = snapshotJson(task.params, taskOwner, ".params");
+	assertPlainObject(params, taskOwner, ".params");
+	return {
+		...task,
+		params
+	};
 }
 //#endregion
 export { defineTask, defineWorkflow };

package/dist/slack.mjs

@@ -1,67 +1,89 @@
+import { t as errorMessage } from "./errors-CMczwLz9.mjs";
 import { z } from "zod";
 import { WebAPIRateLimitedError, WebClient } from "@slack/web-api";
 import { setTimeout } from "node:timers/promises";
-//#region src/slack/report.ts
-const stringSchema = z.string();
-const jsonObjectSchema = z.record(stringSchema, z.json());
-const invokerMetaSchema = z.strictObject({
-	schema: z.literal(1),
-	matrix: jsonObjectSchema,
+//#region src/slack/collect.ts
+const jsonObjectSchema = z.record(z.string(), z.json());
+const workflowInfoSchema = z.object({
+	name: z.string(),
+	metadata: jsonObjectSchema.optional()
+});
+const workflowMetaSchema = z.object({ invokerWorkflow: workflowInfoSchema });
+const collectionErrorSchema = z.object({ invokerCollectionError: workflowInfoSchema });
+const testMetaSchema = z.object({ invoker: z.strictObject({
+	schema: z.literal(2),
+	matrix: z.strictObject({
+		workflow: jsonObjectSchema,
+		task: jsonObjectSchema
+	}),
+	params: jsonObjectSchema,
 	metadata: jsonObjectSchema.optional(),
 	output: z.json().optional()
-});
-const testMetaSchema = z.object({ invoker: invokerMetaSchema.optional() });
-const errorMessageSchema = z.object({ message: stringSchema });
-const errorStackSchema = z.object({ stack: stringSchema });
-const TABLE_ROW_LIMIT = 100;
-const TABLE_CHARACTER_LIMIT = 1e4;
-const SECTION_CHARACTER_LIMIT = 3e3;
-const NAME_CHARACTER_LIMIT = 200;
-const METADATA_CHARACTER_LIMIT = 1800;
+}) });
 function collectWorkflowReports(modules) {
-	const workflows = /* @__PURE__ */ new Map();
-	for (const module of modules) for (const testCase of module.children.allTests()) {
-		const meta = testMetaSchema.safeParse(testCase.meta());
-		const invoker = meta.success ? meta.data.invoker : void 0;
-		const taskSuite = testCase.parent;
-		const workflowSuite = taskSuite.type === "suite" ? taskSuite.parent : void 0;
-		if (!invoker || taskSuite.type !== "suite" || workflowSuite?.type !== "suite") continue;
-		let workflow = workflows.get(workflowSuite);
-		if (!workflow) {
-			workflow = {
-				name: workflowSuite.name,
-				module,
-				suite: workflowSuite,
-				metadata: invoker.metadata,
-				tasks: /* @__PURE__ */ new Map()
-			};
-			workflows.set(workflowSuite, workflow);
+	const workflows = [];
+	for (const module of modules) {
+		for (const suite of module.children.allSuites()) {
+			const meta = workflowMetaSchema.safeParse(suite.meta());
+			if (!meta.success) continue;
+			const tasks = [...suite.children.suites()].flatMap((coordinate) => [...coordinate.children.suites()].map((task) => collectTask(task, coordinate.name)));
+			const failures = [];
+			addErrors(failures, suite.errors());
+			for (const coordinate of suite.children.suites()) addErrors(failures, coordinate.errors(), coordinate.name);
+			workflows.push({
+				...meta.data.invokerWorkflow,
+				tasks: tasks.map((task) => task.report),
+				failures: deduplicateFailures([...failures, ...tasks.flatMap((task) => task.failures)]),
+				retries: tasks.flatMap((task) => task.retries),
+				skips: tasks.flatMap((task) => task.skips),
+				...timeSpan(tasks)
+			});
 		}
-		let task = workflow.tasks.get(taskSuite);
-		if (!task) {
-			task = {
-				name: taskSuite.name,
-				suite: taskSuite,
-				total: 0,
-				passed: 0,
-				retried: 0,
-				failed: 0,
-				skipped: 0,
-				incomplete: 0,
-				failures: [],
-				retries: []
-			};
-			workflow.tasks.set(taskSuite, task);
+		const collection = collectionErrorSchema.safeParse(module.meta());
+		if (collection.success) {
+			const failures = [];
+			addErrors(failures, module.errors());
+			workflows.push({
+				...collection.data.invokerCollectionError,
+				tasks: [],
+				failures,
+				retries: [],
+				skips: []
+			});
 		}
-		task.total += 1;
+	}
+	return workflows;
+}
+function collectTask(suite, coordinateName) {
+	const name = `${coordinateName} · ${suite.name}`;
+	const report = {
+		name,
+		total: 0,
+		passed: 0,
+		retried: 0,
+		failed: 0,
+		skipped: 0,
+		incomplete: 0,
+		duration: 0
+	};
+	const failures = [];
+	const retries = [];
+	const skips = [];
+	let startedAt;
+	let endedAt;
+	for (const testCase of suite.children.tests()) {
+		const meta = testMetaSchema.safeParse(testCase.meta());
+		if (!meta.success) continue;
+		const { invoker } = meta.data;
 		const result = testCase.result();
 		const diagnostic = testCase.diagnostic();
-		task[result.state === "pending" ? "incomplete" : result.state] += 1;
+		report.total += 1;
+		report[result.state === "pending" ? "incomplete" : result.state] += 1;
 		const retryCount = diagnostic?.retryCount ?? 0;
 		if (retryCount > 0) {
-			task.retried += 1;
-			if (result.state === "passed") task.retries.push({
-				task: task.name,
+			report.retried += 1;
+			if (result.state === "passed") retries.push({
+				task: name,
 				caseName: testCase.name,
 				matrix: invoker.matrix,
 				count: retryCount,
@@ -69,42 +91,80 @@ function collectWorkflowReports(modules) {
 			});
 		}
 		if (diagnostic) {
-			task.startedAt = Math.min(task.startedAt ?? diagnostic.startTime, diagnostic.startTime);
-			task.endedAt = Math.max(task.endedAt ?? 0, diagnostic.startTime + diagnostic.duration);
+			startedAt = Math.min(startedAt ?? diagnostic.startTime, diagnostic.startTime);
+			endedAt = Math.max(endedAt ?? 0, diagnostic.startTime + diagnostic.duration);
 		}
-		if (result.state === "failed") task.failures.push({
-			task: task.name,
+		if (result.state === "failed") failures.push({
+			task: name,
 			caseName: testCase.name,
 			matrix: invoker.matrix,
 			messages: result.errors.map(errorMessage)
 		});
+		else if (result.state === "skipped") skips.push({
+			task: name,
+			caseName: testCase.name,
+			matrix: invoker.matrix,
+			reason: result.note || "No reason provided"
+		});
 	}
-	return [...workflows.values()].map((workflow) => {
-		const failures = [];
-		const retries = [];
-		addErrors(failures, workflow.suite.errors());
-		addErrors(failures, workflow.module.errors());
-		const collectedTasks = [...workflow.tasks.values()];
-		for (const task of collectedTasks) {
-			failures.push(...task.failures);
-			retries.push(...task.retries);
-			addErrors(failures, task.suite.errors(), task.name);
-		}
-		const { startedAt, endedAt } = timeSpan(collectedTasks);
-		return {
-			name: workflow.name,
-			metadata: workflow.metadata,
-			tasks: collectedTasks.map(({ suite: _suite, failures: _failures, retries: _retries, startedAt, endedAt, ...task }) => ({
-				...task,
-				duration: startedAt === void 0 || endedAt === void 0 ? 0 : endedAt - startedAt
-			})),
-			failures: deduplicateFailures(failures),
-			retries,
-			startedAt,
-			endedAt
-		};
+	addErrors(failures, suite.errors(), name);
+	report.duration = startedAt === void 0 || endedAt === void 0 ? 0 : endedAt - startedAt;
+	return {
+		report,
+		failures,
+		retries,
+		skips,
+		startedAt,
+		endedAt
+	};
+}
+function addErrors(failures, errors, task) {
+	const messages = errors.map(errorMessage);
+	if (messages.length > 0) failures.push({
+		task,
+		messages
+	});
+}
+function deduplicateFailures(failures) {
+	const seen = /* @__PURE__ */ new Set();
+	return failures.flatMap((failure) => {
+		const messages = failure.messages.filter((message) => {
+			const key = JSON.stringify([
+				failure.task,
+				failure.caseName,
+				failure.matrix,
+				message
+			]);
+			if (seen.has(key)) return false;
+			seen.add(key);
+			return true;
+		});
+		return messages.length > 0 ? [{
+			...failure,
+			messages
+		}] : [];
 	});
 }
+function timeSpan(values) {
+	let startedAt;
+	let endedAt;
+	for (const value of values) {
+		if (value.startedAt !== void 0) startedAt = Math.min(startedAt ?? value.startedAt, value.startedAt);
+		if (value.endedAt !== void 0) endedAt = Math.max(endedAt ?? value.endedAt, value.endedAt);
+	}
+	return {
+		startedAt,
+		endedAt
+	};
+}
+//#endregion
+//#region src/slack/report.ts
+const stringSchema = z.string();
+const TABLE_ROW_LIMIT = 100;
+const TABLE_CHARACTER_LIMIT = 1e4;
+const SECTION_CHARACTER_LIMIT = 3e3;
+const NAME_CHARACTER_LIMIT = 200;
+const METADATA_CHARACTER_LIMIT = 1800;
 function summaryMessage(reports, runUrl) {
 	const timestamp = Math.floor(Date.now() / 1e3);
 	const { startedAt, endedAt } = timeSpan(reports);
@@ -133,7 +193,8 @@ function workflowAttachment(report, rows, index, pages) {
 	const status = workflowStatus(report);
 	const metadata = metadataText(report.metadata);
 	const page = pages > 1 ? ` (${index + 1}/${pages})` : "";
-	const headline = `${status.emoji} *${escapeSlack(truncate(report.name, NAME_CHARACTER_LIMIT))} — ${totals.passed}/${totals.total} passed${page}*`;
+	const result = report.tasks.length === 0 ? "Collection failed" : `${totals.passed}/${totals.total} passed`;
+	const headline = `${status.emoji} *${escapeSlack(truncate(report.name, NAME_CHARACTER_LIMIT))} — ${result}${page}*`;
 	return {
 		color: status.color,
 		blocks: [
@@ -168,88 +229,66 @@ function workflowAttachment(report, rows, index, pages) {
 }
 function failureMessages(report) {
 	return [...Map.groupBy(report.failures, (failure) => failure.task)].flatMap(([task, failures]) => {
-		const title = escapeSlack(truncate(task ?? "Workflow errors", NAME_CHARACTER_LIMIT));
-		const workflow = `*Workflow:* ${escapeSlack(truncate(report.name, NAME_CHARACTER_LIMIT))}`;
-		const metadata = metadataText(report.metadata);
-		const context = metadata ? `${workflow}  •  ${metadata}` : workflow;
-		return chunk(failures.map((failure) => {
+		return detailMessages(report, task, "failed", failures.map((failure) => {
 			return `${failure.caseName ? `*${escapeSlack(failure.caseName)}*` : task ? "*Task error*" : "*Workflow error*"}${failure.matrix ? `\nMatrix: ${escapeSlack(JSON.stringify(failure.matrix))}` : ""}${failure.messages.map((message) => `\n• ${escapeSlack(message)}`).join("")}`;
-		}), 3e3).map((details, index, messages) => {
-			const part = messages.length > 1 ? ` (${index + 1}/${messages.length})` : "";
-			return {
-				text: `${truncate(report.name, NAME_CHARACTER_LIMIT)} › ${truncate(task ?? "Workflow", NAME_CHARACTER_LIMIT)} — ${failures.length} failed${part}`,
-				attachments: [{
-					color: "danger",
-					blocks: [
-						{
-							type: "section",
-							text: {
-								type: "mrkdwn",
-								text: `🔴 *${title} — ${failures.length} failed${part}*`
-							}
-						},
-						{
-							type: "context",
-							elements: [{
-								type: "mrkdwn",
-								text: context
-							}]
-						},
-						{
-							type: "section",
-							text: {
-								type: "mrkdwn",
-								text: details
-							}
-						}
-					]
-				}]
-			};
-		});
+		}));
 	});
 }
 function retryMessages(report) {
 	return [...Map.groupBy(report.retries, (retry) => retry.task)].flatMap(([task, retries]) => {
-		const title = escapeSlack(truncate(task, NAME_CHARACTER_LIMIT));
-		const workflow = `*Workflow:* ${escapeSlack(truncate(report.name, NAME_CHARACTER_LIMIT))}`;
-		const metadata = metadataText(report.metadata);
-		const context = metadata ? `${workflow}  •  ${metadata}` : workflow;
-		return chunk(retries.map((retry) => {
+		return detailMessages(report, task, "retried", retries.map((retry) => {
 			const matrix = `\nMatrix: ${escapeSlack(JSON.stringify(retry.matrix))}`;
 			const messages = retry.messages.map((message) => `\n• ${escapeSlack(message)}`).join("");
 			return `*${escapeSlack(retry.caseName)}*\nRetries: ${retry.count}${matrix}${messages}`;
-		}), SECTION_CHARACTER_LIMIT).map((details, index, messages) => {
-			const part = messages.length > 1 ? ` (${index + 1}/${messages.length})` : "";
-			return {
-				text: `${truncate(report.name, NAME_CHARACTER_LIMIT)} › ${truncate(task, NAME_CHARACTER_LIMIT)} — ${retries.length} retried${part}`,
-				attachments: [{
-					color: "warning",
-					blocks: [
-						{
-							type: "section",
-							text: {
-								type: "mrkdwn",
-								text: `🟡 *${title} — ${retries.length} retried${part}*`
-							}
-						},
-						{
-							type: "context",
-							elements: [{
-								type: "mrkdwn",
-								text: context
-							}]
-						},
-						{
-							type: "section",
-							text: {
-								type: "mrkdwn",
-								text: details
-							}
+		}));
+	});
+}
+function skipMessages(report) {
+	return [...Map.groupBy(report.skips, (skip) => skip.task)].flatMap(([task, skips]) => {
+		return detailMessages(report, task, "skipped", skips.map((skip) => {
+			const matrix = `\nMatrix: ${escapeSlack(JSON.stringify(skip.matrix))}`;
+			return `*${escapeSlack(skip.caseName)}*${matrix}\nReason: ${escapeSlack(skip.reason)}`;
+		}));
+	});
+}
+function detailMessages(report, task, outcome, entries) {
+	const title = escapeSlack(truncate(task ?? "Workflow errors", NAME_CHARACTER_LIMIT));
+	const workflow = `*Workflow:* ${escapeSlack(truncate(report.name, NAME_CHARACTER_LIMIT))}`;
+	const metadata = metadataText(report.metadata);
+	const context = metadata ? `${workflow}  •  ${metadata}` : workflow;
+	const emoji = outcome === "failed" ? "🔴" : "🟡";
+	return chunk(entries, SECTION_CHARACTER_LIMIT).map((details, index, messages) => {
+		const part = messages.length > 1 ? ` (${index + 1}/${messages.length})` : "";
+		const count = `${entries.length} ${outcome}${part}`;
+		return {
+			text: `${truncate(report.name, NAME_CHARACTER_LIMIT)} › ${truncate(task ?? "Workflow", NAME_CHARACTER_LIMIT)} — ${count}`,
+			attachments: [{
+				color: outcome === "failed" ? "danger" : "warning",
+				blocks: [
+					{
+						type: "section",
+						text: {
+							type: "mrkdwn",
+							text: `${emoji} *${title} — ${count}*`
 						}
-					]
-				}]
-			};
-		});
+					},
+					{
+						type: "context",
+						elements: [{
+							type: "mrkdwn",
+							text: context
+						}]
+					},
+					{
+						type: "section",
+						text: {
+							type: "mrkdwn",
+							text: details
+						}
+					}
+				]
+			}]
+		};
 	});
 }
 function unhandledErrorMessages(errors) {
@@ -277,40 +316,6 @@ function unhandledErrorMessages(errors) {
 		};
 	});
 }
-function addErrors(failures, errors, task) {
-	const messages = errors.map(errorMessage);
-	if (messages.length > 0) failures.push({
-		task,
-		messages
-	});
-}
-function errorMessage(cause) {
-	const message = errorMessageSchema.safeParse(cause);
-	if (message.success) return message.data.message;
-	const stack = errorStackSchema.safeParse(cause);
-	if (stack.success) return stack.data.stack.split("\n", 1)[0];
-	return String(cause);
-}
-function deduplicateFailures(failures) {
-	const seen = /* @__PURE__ */ new Set();
-	return failures.flatMap((failure) => {
-		const messages = failure.messages.filter((message) => {
-			const key = JSON.stringify([
-				failure.task,
-				failure.caseName,
-				failure.matrix,
-				message
-			]);
-			if (seen.has(key)) return false;
-			seen.add(key);
-			return true;
-		});
-		return messages.length > 0 ? [{
-			...failure,
-			messages
-		}] : [];
-	});
-}
 function escapeSlack(value) {
 	return escapeSlackControl(value).replaceAll("*", "∗").replaceAll("_", "＿").replaceAll("~", "∼").replaceAll("`", "ˋ");
 }
@@ -398,7 +403,7 @@ function formatDuration(milliseconds) {
 function chunk(entries, limit) {
 	const chunks = [];
 	for (const entry of entries) {
-		const value = entry.length > limit ? `${entry.slice(0, limit - 1)}…` : entry;
+		const value = truncate(entry, limit);
 		const previous = chunks.at(-1);
 		if (previous && previous.length + value.length + 2 <= limit) chunks[chunks.length - 1] = `${previous}\n\n${value}`;
 		else chunks.push(value);
@@ -408,18 +413,6 @@ function chunk(entries, limit) {
 function truncate(value, limit) {
 	return value.length > limit ? `${value.slice(0, limit - 1)}…` : value;
 }
-function timeSpan(values) {
-	let startedAt;
-	let endedAt;
-	for (const value of values) {
-		if (value.startedAt !== void 0) startedAt = Math.min(startedAt ?? value.startedAt, value.startedAt);
-		if (value.endedAt !== void 0) endedAt = Math.max(endedAt ?? value.endedAt, value.endedAt);
-	}
-	return {
-		startedAt,
-		endedAt
-	};
-}
 //#endregion
 //#region src/slack/reporter.ts
 function slackReporter(options) {
@@ -457,6 +450,7 @@ function slackReporter(options) {
 		const replies = [
 			...reports.flatMap(failureMessages),
 			...reports.flatMap(retryMessages),
+			...reports.flatMap(skipMessages),
 			...unhandledErrorMessages(unhandledErrors)
 		];
 		if (replies.length > 0 && !parentTimestamp) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akshatmittal/invoker",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Typed matrix-driven regression workflows for Vitest.",
   "keywords": [
     "matrix",