@opice/harness 0.3.0 → 0.4.0

package/README.md

@@ -19,7 +19,7 @@ Runs under the Bun test runner.
 import { test, describe } from 'bun:test'
 import { browserTest, el, byRole, byLabel, step, expect } from '@opice/harness'
 
-browserTest('DataGrid', () => {
+browserTest({ name: 'DataGrid', hash: 'datagrid' }, () => {
   test('renders and is interactive', async () => {
     await step('table is visible', async () => {
       await expect(el('datagrid-table')).toBeVisible()
@@ -30,7 +30,7 @@ browserTest('DataGrid', () => {
       await expect(el('datagrid-row-0')).toHaveAttribute('data-highlighted', '')
     })
   }, 60_000)
-}, { hash: 'datagrid' })
+})
 ```
 
 The DSL is **async** and returns Playwright `Locator`s, so the full Locator API

package/dist/accessible.d.ts

@@ -1,6 +1,8 @@
 import type { Locator, Page } from 'playwright';
 /** The ARIA role union accepted by Playwright's `getByRole`. */
 type Role = Parameters<Page['getByRole']>[0];
+/** Playwright's `getByRole` options minus `name` (which is passed positionally). */
+type RoleOptions = Omit<NonNullable<Parameters<Page['getByRole']>[1]>, 'name'>;
 /**
  * Accessible-name selectors — `byRole` / `byLabel` / `byText`.
  *
@@ -17,9 +19,14 @@ type Role = Parameters<Page['getByRole']>[0];
  */
 /**
  * Find an element by ARIA role and (optionally) its accessible name.
- * `name` does a substring, case-insensitive match by default.
+ * `name` does a substring, case-insensitive match when a string; pass a
+ * `RegExp` to match the accessible name by pattern (e.g. a generated id).
+ *
+ * `options` forwards the rest of Playwright's `getByRole` filters — most useful
+ * is `level` to pin a heading (`byRole('heading', 'Title', { level: 2 })`), plus
+ * `exact`, `checked`, `pressed`, `expanded`, `disabled`, etc.
  */
-export declare function byRole(role: Role, name?: string): Locator;
+export declare function byRole(role: Role, name?: string | RegExp, options?: RoleOptions): Locator;
 /** Find a form control by its associated `<label>` (or `aria-label`) text. */
 export declare function byLabel(text: string): Locator;
 /** Find an element by its visible text (substring, case-insensitive). */

package/dist/accessible.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"accessible.d.ts","sourceRoot":"","sources":["../src/accessible.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAG/C,gEAAgE;AAChE,KAAK,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAE5C;;;;;;;;;;;;;GAaG;AAEH;;;GAGG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,8EAA8E;AAC9E,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7C;AAED,yEAAyE;AACzE,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5C"}
+{"version":3,"file":"accessible.d.ts","sourceRoot":"","sources":["../src/accessible.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAG/C,gEAAgE;AAChE,KAAK,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAC5C,oFAAoF;AACpF,KAAK,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;AAE9E;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAGzF;AAED,8EAA8E;AAC9E,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7C;AAED,yEAAyE;AACzE,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5C"}

package/dist/accessible.js

@@ -15,10 +15,16 @@ import { getPage } from './context.js';
  */
 /**
  * Find an element by ARIA role and (optionally) its accessible name.
- * `name` does a substring, case-insensitive match by default.
+ * `name` does a substring, case-insensitive match when a string; pass a
+ * `RegExp` to match the accessible name by pattern (e.g. a generated id).
+ *
+ * `options` forwards the rest of Playwright's `getByRole` filters — most useful
+ * is `level` to pin a heading (`byRole('heading', 'Title', { level: 2 })`), plus
+ * `exact`, `checked`, `pressed`, `expanded`, `disabled`, etc.
  */
-export function byRole(role, name) {
-    return getPage().getByRole(role, name == null ? undefined : { name });
+export function byRole(role, name, options) {
+    const opts = { ...options, ...(name == null ? {} : { name }) };
+    return getPage().getByRole(role, Object.keys(opts).length > 0 ? opts : undefined);
 }
 /** Find a form control by its associated `<label>` (or `aria-label`) text. */
 export function byLabel(text) {

package/dist/accessible.js.map

@@ -1 +1 @@
-{"version":3,"file":"accessible.js","sourceRoot":"","sources":["../src/accessible.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAKtC;;;;;;;;;;;;;GAaG;AAEH;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,IAAU,EAAE,IAAa;IAC/C,OAAO,OAAO,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAA;AACtE,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,OAAO,CAAC,IAAY;IACnC,OAAO,OAAO,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAA;AAClC,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,MAAM,CAAC,IAAY;IAClC,OAAO,OAAO,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;AACjC,CAAC"}
+{"version":3,"file":"accessible.js","sourceRoot":"","sources":["../src/accessible.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAOtC;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,MAAM,CAAC,IAAU,EAAE,IAAsB,EAAE,OAAqB;IAC/E,MAAM,IAAI,GAAG,EAAE,GAAG,OAAO,EAAE,GAAG,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAA;IAC9D,OAAO,OAAO,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;AAClF,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,OAAO,CAAC,IAAY;IACnC,OAAO,OAAO,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAA;AAClC,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,MAAM,CAAC,IAAY;IAClC,OAAO,OAAO,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;AACjC,CAAC"}

package/dist/index.d.ts

@@ -2,8 +2,8 @@ export { el, tid, waitFor, wait, evalJs, screenshot } from './element.js';
 export { byLabel, byRole, byText } from './accessible.js';
 export { back, currentPath, currentUrl, forward, open, reload } from './navigation.js';
 export { getPage, getContext } from './context.js';
-export { browserTest, step } from './scenario.js';
-export type { BrowserTestOptions } from './scenario.js';
+export { browserTest, invariant, step } from './scenario.js';
+export type { BrowserTestMeta, StepContract } from './scenario.js';
 export { getReporter, setReporter, configureFromEnv } from './reporter.js';
 export type { Reporter, ReporterConfig, StepEvent, ScenarioStart, ScenarioFinish } from './reporter.js';
 export { parseOpiceDsn } from './dsn.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEzE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAEzD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAEtF,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAElD,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AACjD,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAEvD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAC1E,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAEvG,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,YAAY,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAExC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,CAAC,EAAE,MAAM,cAAc,CAAA;AAC5G,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEvD,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAC7D,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAI9C,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAGzC,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEzE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAEzD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAEtF,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAElD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AAC5D,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAElE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAC1E,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAEvG,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,YAAY,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAExC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,CAAC,EAAE,MAAM,cAAc,CAAA;AAC5G,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEvD,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAC7D,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAI9C,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAGzC,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -2,7 +2,7 @@ export { el, tid, waitFor, wait, evalJs, screenshot } from './element.js';
 export { byLabel, byRole, byText } from './accessible.js';
 export { back, currentPath, currentUrl, forward, open, reload } from './navigation.js';
 export { getPage, getContext } from './context.js';
-export { browserTest, step } from './scenario.js';
+export { browserTest, invariant, step } from './scenario.js';
 export { getReporter, setReporter, configureFromEnv } from './reporter.js';
 export { parseOpiceDsn } from './dsn.js';
 export { command, call, runCommand, makeCtx, loadUserCommands, findUserCommandsFile, z } from './command.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEzE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAEzD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAEtF,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAElD,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AAGjD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAG1E,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAGxC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,CAAC,EAAE,MAAM,cAAc,CAAA;AAG5G,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAG7D,iFAAiF;AACjF,uEAAuE;AACvE,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEzE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAEzD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAEtF,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAElD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AAG5D,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAG1E,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAGxC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,CAAC,EAAE,MAAM,cAAc,CAAA;AAG5G,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAG7D,iFAAiF;AACjF,uEAAuE;AACvE,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/reporter.d.ts

@@ -26,16 +26,27 @@ export interface StepEvent {
     scenarioId: string;
     /** Authoring order within the scenario, assigned at step() call time. */
     sequence: number;
+    /**
+     * 'step' (a procedural step) or 'invariant' (a scenario-level acceptance).
+     * The platform may render invariants distinctly; older workers ignore it.
+     */
+    kind?: 'step' | 'invariant';
     name: string;
     /**
      * 'fixme' (a step.fixme that failed, as expected) and 'fixmepass' (a
      * step.fixme that unexpectedly passed) are tolerated warnings — neither
-     * fails the scenario.
+     * fails the scenario. 'pending' is a phase-1 stub that never ran (no body
+     * yet); a scenario carrying one reads as 'incomplete'.
      */
-    status: 'passed' | 'failed' | 'fixme' | 'fixmepass';
+    status: 'passed' | 'failed' | 'fixme' | 'fixmepass' | 'pending';
     durationMs: number;
     error?: string;
-    /** Mandatory note from step.fixme — why the failure is tolerated. */
+    /**
+     * Durable rationale carried from the unit's contract (phase-1 `intent`) —
+     * why it exists / what it proves. Surfaced on the dashboard.
+     */
+    intent?: string;
+    /** Mandatory note from .fixme — why the failure is tolerated. */
     reason?: string;
     screenshotPath?: string;
 }
@@ -43,7 +54,12 @@ export interface ScenarioStart {
     name: string;
     hash?: string;
     testFile?: string;
-    scenarioFile?: string;
+    /** Requirement / feature id this scenario covers (grouping). */
+    feature?: string;
+    /** Seeds required for the scenario (machine-checkable preconditions). */
+    seeds?: string[];
+    /** Identities / roles the scenario acts as. */
+    roles?: string[];
 }
 export interface ScenarioFinish {
     scenarioId: string;

package/dist/reporter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reporter.d.ts","sourceRoot":"","sources":["../src/reporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAaH,MAAM,WAAW,cAAc;IAC9B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oEAAoE;IACpE,MAAM,CAAC,EAAE,IAAI,GAAG,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,SAAS;IACzB,UAAU,EAAE,MAAM,CAAA;IAClB,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,WAAW,CAAA;IACnD,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,cAAc,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,cAAc;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC3B,UAAU,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,QAAQ;IACxB,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACpD,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3C,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACtB;AAWD,eAAO,MAAM,WAAW,QAAwC,CAAA;AAMhE,MAAM,WAAW,UAAU;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;CACb;AA+JD,wBAAgB,WAAW,IAAI,QAAQ,CAEtC;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAEpD;AAED,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,QAAQ,CA8B/E"}
+{"version":3,"file":"reporter.d.ts","sourceRoot":"","sources":["../src/reporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAaH,MAAM,WAAW,cAAc;IAC9B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oEAAoE;IACpE,MAAM,CAAC,EAAE,IAAI,GAAG,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,SAAS;IACzB,UAAU,EAAE,MAAM,CAAA;IAClB,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,CAAA;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,WAAW,GAAG,SAAS,CAAA;IAC/D,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,cAAc,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,MAAM,WAAW,cAAc;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC3B,UAAU,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,QAAQ;IACxB,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACpD,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3C,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACtB;AAWD,eAAO,MAAM,WAAW,QAAwC,CAAA;AAMhE,MAAM,WAAW,UAAU;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;CACb;AAmKD,wBAAgB,WAAW,IAAI,QAAQ,CAEtC;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAEpD;AAED,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,QAAQ,CA8B/E"}

package/dist/reporter.js

@@ -73,7 +73,9 @@ class HttpReporter {
             name: input.name,
             hash: input.hash,
             testFile: input.testFile,
-            scenarioFile: input.scenarioFile,
+            feature: input.feature,
+            seeds: input.seeds,
+            roles: input.roles,
         });
         return response['scenarioId'];
     }
@@ -92,10 +94,12 @@ class HttpReporter {
             : undefined;
         await this.fetch('POST', `/api/v1/runs/${runId}/scenarios/${event.scenarioId}/steps`, {
             sequence: event.sequence,
+            kind: event.kind,
             name: event.name,
             status: event.status,
             durationMs: event.durationMs,
             error: event.error,
+            intent: event.intent,
             reason: event.reason,
             screenshot,
         });

package/dist/reporter.js.map

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

package/dist/scenario.d.ts

@@ -1,24 +1,85 @@
-export interface BrowserTestOptions {
-    /** Hash fragment appended to PLAYGROUND_URL (e.g. 'datagrid'). */
-    hash?: string;
-    /** Override base URL (defaults to PLAYGROUND_URL env). */
+/**
+ * Scenario metadata — the **first** argument to `browserTest`.
+ *
+ * This is the durable, machine-relevant context an opice scenario carries
+ * independent of its concrete steps: where it runs, what it presupposes, what
+ * requirement it covers. It is written in **phase 1** (planning, `opice-plan`)
+ * and preserved through **phase 2** (authoring, `opice-author`) — the scenario
+ * file IS the spec, so this metadata never lives in a separate `.md` that can
+ * drift from the test.
+ *
+ * The rule of thumb for what belongs here vs. a code comment: *does anything
+ * other than a human read it?* Seeds (a precondition a runner could verify),
+ * the feature id (grouping on the dashboard), the acting roles — yes, so they
+ * are first-class fields. Background rationale that only a human reads stays a
+ * comment next to the relevant step.
+ */
+export interface BrowserTestMeta {
+    /** Scenario name — becomes the `describe()` title. Required. */
+    name: string;
+    /** Override base URL (defaults to the `PLAYGROUND_URL` env var). */
     url?: string;
+    /** Hash fragment appended to the base URL (e.g. `'datagrid'`). */
+    hash?: string;
+    /** Feature / requirement id this scenario covers (e.g. `'F-SML-03a'`). */
+    feature?: string;
     /**
-     * Path to the human-readable `*.scenario.md` this test was authored from.
-     * Reported to the platform so the re-eval workflow can find the source.
-     * If omitted, defaults to the test file path with `.test.ts` → `.scenario.md`.
+     * Seeds that must be loaded for this scenario to run — machine-checkable
+     * preconditions, not prose. e.g. `['initial-data', 'crm-master-data']`.
      */
-    scenarioFile?: string;
+    seeds?: string[];
+    /** Identities / roles the scenario acts as, e.g. `['crmOperator']`. */
+    roles?: string[];
 }
 /**
  * Register a top-level browser test scenario.
  *
- * Each `browserTest(name, fn)` launches its own isolated Playwright browser +
+ * Each `browserTest(meta, fn)` launches its own isolated Playwright browser +
  * context + page, navigates to the playground URL, runs the given `fn` (which
  * typically contains nested `describe`/`test` blocks), and tears the browser
  * down in `afterAll`.
+ *
+ * Metadata is the **first** argument (`{ name, url, hash, feature, seeds,
+ * roles }`); `name` is required.
  */
-export declare function browserTest(name: string, fn: () => void, options?: BrowserTestOptions | string): void;
+export declare function browserTest(meta: BrowserTestMeta, fn: () => void): void;
+/**
+ * The durable contract of a step or invariant, separate from its mechanics.
+ *
+ * `intent` is written in **phase 1** and survives **verbatim** into the
+ * authored test — it's the "why this exists / what it proves", the independent
+ * statement of intent that the concrete body is checked against. `hint` is
+ * phase-1 scaffolding *for the authoring agent* ("what to actually do here");
+ * it is consumed when the step is authored and dropped once a body exists.
+ */
+export interface StepContract {
+    /** Durable rationale: why this step/invariant exists, what it proves. */
+    intent?: string;
+    /**
+     * Phase-1 instruction to the authoring agent — what to do on the page here.
+     * Ephemeral: drop it once the body is written.
+     */
+    hint?: string;
+}
+type StepBody = () => void | Promise<void>;
+interface StepFn {
+    /** Executable step. */
+    (name: string, fn: StepBody): Promise<void>;
+    /** Phase-1 stub: a step with a contract but no body yet (status: pending). */
+    (name: string, contract: StepContract): Promise<void>;
+    /** Authored step that keeps its durable contract. */
+    (name: string, contract: StepContract, fn: StepBody): Promise<void>;
+}
+interface StepExtras {
+    fixme: (name: string, reason: string, fn: StepBody) => Promise<void>;
+    /**
+     * A **blocked** pending stub: the step can't be authored yet because the app
+     * feature it covers isn't implemented. Reports as 'pending' with the reason
+     * attached (the dashboard shows it as blocked, distinct from a plain stub
+     * that's merely awaiting a test). `reason` is mandatory — say what's missing.
+     */
+    blocked: (name: string, reason: string, contract?: StepContract) => Promise<void>;
+}
 /**
  * A reportable step inside a scenario. Captures duration + screenshot on
  * finish, forwards to the active reporter (no-op unless configured via env).
@@ -26,6 +87,14 @@ export declare function browserTest(name: string, fn: () => void, options?: Brow
  * The body may be sync or async; `step` always returns a promise, so call it
  * with `await step('…', async () => { … })`.
  *
+ * Three forms:
+ * - `step(name, fn)` — executable step (the common case).
+ * - `step(name, { intent, hint })` — a **pending** phase-1 stub: declares the
+ *   step's intent and what to do, but has no body yet. It does not run and
+ *   reports as `pending`; `opice-author` fills in the body.
+ * - `step(name, { intent }, fn)` — an authored step that keeps its durable
+ *   `intent` (preserved verbatim from phase 1) alongside the body.
+ *
  * `step.fixme(name, reason, fn)` marks a **known, tolerated failure**: the body
  * still runs, but a failure inside it does NOT fail the scenario or the CI run —
  * it's reported as an amber warning instead. The `reason` is mandatory (use it
@@ -33,8 +102,41 @@ export declare function browserTest(name: string, fn: () => void, options?: Brow
  * step unexpectedly *passes*, it's flagged too ('fixmepass') so a stale marker
  * doesn't linger. Unlike Playwright's `test.fixme()`, which **skips** the test,
  * `step.fixme` **runs** it — the mandatory reason is there to keep them apart.
+ *
+ * `step.blocked(name, reason, contract?)` is a pending stub that **can't be
+ * authored yet** because the app feature doesn't exist — distinct from a plain
+ * `step(name, contract)` stub that's simply awaiting a test. Both report as
+ * 'pending' (scenario reads 'incomplete'); the blocked one carries its reason.
+ */
+export declare const step: StepFn & StepExtras;
+/**
+ * A scenario-level **invariant** — an acceptance property the scenario
+ * enforces, independent of the procedural steps. This is the durable "what
+ * must be true" that used to live in a scenario's prose Notes; expressing it as
+ * a call keeps it in the one source of truth (the test) instead of a separate
+ * `.md` that drifts.
+ *
+ * A failing `invariant` fails the scenario like any hard assertion — it's an
+ * acceptance, not a nicety.
+ *
+ * - `invariant(name, fn)` — enforced now.
+ * - `invariant.todo(name, hint?)` — phase-1 stub: states the acceptance but
+ *   isn't wired yet (status: pending). `opice-author` promotes it to an
+ *   enforced `invariant(...)` (or an `invariant.fixme(...)` if it can't hold
+ *   yet) once it knows how to check it.
+ * - `invariant.blocked(name, reason)` — a pending acceptance that can't be
+ *   wired yet because the feature it guards isn't implemented (vs `.todo`,
+ *   which is merely awaiting authoring). Reports 'pending' with the reason.
+ * - `invariant.fixme(name, reason, fn)` — a known-unenforceable acceptance,
+ *   tolerated like `step.fixme` (e.g. a security property deferred to a
+ *   ticket). The body runs and is expected to fail; the failure is reported as
+ *   an amber warning and neither fails the scenario nor the run.
  */
-export declare const step: ((name: string, fn: () => void | Promise<void>) => Promise<void>) & {
-    fixme: (name: string, reason: string, fn: () => void | Promise<void>) => Promise<void>;
+export declare const invariant: {
+    (name: string, fn: StepBody): Promise<void>;
+    todo: (name: string, hint?: string) => Promise<void>;
+    blocked: (name: string, reason: string) => Promise<void>;
+    fixme: (name: string, reason: string, fn: StepBody) => Promise<void>;
 };
+export {};
 //# sourceMappingURL=scenario.d.ts.map

package/dist/scenario.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scenario.d.ts","sourceRoot":"","sources":["../src/scenario.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,kBAAkB;IAClC,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACrB;AAuCD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,IAAI,EAAE,OAAO,GAAE,kBAAkB,GAAG,MAAW,GAAG,IAAI,CA6DzG;AAsDD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,IAAI,UACT,MAAM,MAAM,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAG,OAAO,CAAC,IAAI,CAAC;kBAE9C,MAAM,UAAU,MAAM,MAAM,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAG,OAAO,CAAC,IAAI,CAAC;CAGrF,CAAA"}
+{"version":3,"file":"scenario.d.ts","sourceRoot":"","sources":["../src/scenario.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,eAAe;IAC/B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAA;IACZ,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CAChB;AAmCD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAuFvE;AAKD;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC5B,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;CACb;AA6FD,KAAK,QAAQ,GAAG,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAE1C,UAAU,MAAM;IACf,uBAAuB;IACvB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3C,8EAA8E;IAC9E,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrD,qDAAqD;IACrD,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACnE;AAED,UAAU,UAAU;IACnB,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACpE;;;;;OAKG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACjF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,IAAI,EAAE,MAAM,GAAG,UAa3B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,SAAS,EAAE;IACvB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3C,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACpD,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACxD,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAWpE,CAAA"}

package/dist/scenario.js

@@ -40,14 +40,10 @@ function captureTestFile() {
     }
     return undefined;
 }
-function defaultScenarioFile(testFile) {
-    if (!testFile)
-        return undefined;
-    return testFile.replace(/\.test\.[tj]sx?$/, '.scenario.md');
-}
 let currentScenarioId = null;
 let currentScenarioStart = 0;
 let currentScenarioFailures = 0;
+let currentScenarioPending = 0;
 // Monotonic per-scenario step counter. Assigned synchronously at each step()
 // call so order reflects authoring order — step records are POSTed
 // fire-and-forget and would otherwise be sequenced by arrival order at the
@@ -56,24 +52,41 @@ let currentScenarioStepSeq = 0;
 /**
  * Register a top-level browser test scenario.
  *
- * Each `browserTest(name, fn)` launches its own isolated Playwright browser +
+ * Each `browserTest(meta, fn)` launches its own isolated Playwright browser +
  * context + page, navigates to the playground URL, runs the given `fn` (which
  * typically contains nested `describe`/`test` blocks), and tears the browser
  * down in `afterAll`.
+ *
+ * Metadata is the **first** argument (`{ name, url, hash, feature, seeds,
+ * roles }`); `name` is required.
  */
-export function browserTest(name, fn, options = {}) {
-    const opts = typeof options === 'string' ? { hash: options } : options;
+export function browserTest(meta, fn) {
+    if (typeof meta === 'string') {
+        // Migration aid: the old signature was `browserTest(name, fn, options)`.
+        throw new Error('opice: browserTest now takes metadata first — browserTest({ name, url, hash, … }, fn). '
+            + `Got a string name (${JSON.stringify(meta)}); wrap it: browserTest({ name: ${JSON.stringify(meta)} }, fn).`);
+    }
+    if (!meta?.name) {
+        throw new Error('opice: browserTest requires a `name` in its metadata — browserTest({ name: "…" }, fn).');
+    }
     const reporter = getReporter();
     const testFile = captureTestFile();
-    const scenarioFile = opts.scenarioFile ?? defaultScenarioFile(testFile);
     const { describe, beforeAll, afterAll } = bunTest();
-    describe(name, () => {
+    describe(meta.name, () => {
         beforeAll(async () => {
             currentScenarioStart = Date.now();
             currentScenarioFailures = 0;
+            currentScenarioPending = 0;
             currentScenarioStepSeq = 0;
             try {
-                currentScenarioId = await reporter.startScenario({ name, hash: opts.hash, testFile, scenarioFile });
+                currentScenarioId = await reporter.startScenario({
+                    name: meta.name,
+                    hash: meta.hash,
+                    testFile,
+                    feature: meta.feature,
+                    seeds: meta.seeds,
+                    roles: meta.roles,
+                });
             }
             catch {
                 currentScenarioId = null;
@@ -85,8 +98,8 @@ export function browserTest(name, fn, options = {}) {
             const setup = await loadUserSetup();
             if (setup)
                 await setup(getContext());
-            const base = opts.url ?? PLAYGROUND_URL;
-            const url = opts.hash ? `${base}#${opts.hash}` : base;
+            const base = meta.url ?? PLAYGROUND_URL;
+            const url = meta.hash ? `${base}#${meta.hash}` : base;
             // `domcontentloaded`, not the default `load`: an SPA paints after its JS
             // runs and may hold `load` on a slow chunk or long-lived connection, so
             // waiting for `load` flakily times out under CI contention. Readiness is
@@ -100,6 +113,14 @@ export function browserTest(name, fn, options = {}) {
             catch {
                 // ignore close errors
             }
+            // A scenario still carrying unfilled (pending) steps is a phase-1
+            // skeleton that was run before authoring. It's not a failure, but it's
+            // not done either — make it loud so a half-authored test isn't mistaken
+            // for a passing one.
+            if (currentScenarioPending > 0) {
+                console.warn(`[opice] scenario "${meta.name}" has ${currentScenarioPending} pending step(s) — `
+                    + 'authored skeleton, not yet filled in by opice-author. The body did NOT run.');
+            }
             if (currentScenarioId) {
                 // Drain pending step records (incl. their screenshot uploads)
                 // before marking the scenario done. step() fires recordStep
@@ -125,17 +146,40 @@ export function browserTest(name, fn, options = {}) {
         fn();
     });
 }
-async function runStep(name, fn, fixmeReason) {
+async function runUnit(unit) {
     const reporter = getReporter();
     // Capture order at call time, before the fire-and-forget record below.
     const sequence = currentScenarioStepSeq++;
+    // A reason *with* a body is a .fixme (tolerated failure). A reason *without*
+    // a body is .blocked (a pending stub that can't be authored yet).
+    const fixme = unit.reason !== undefined && unit.fn !== undefined;
+    // Phase-1 stub: no body to run. Report it as 'pending' (so the dashboard
+    // shows the skeleton — a scenario carrying one reads as 'incomplete') and
+    // count it so afterAll can warn. A `reason` here marks it 'blocked' (the
+    // feature isn't built); no reason is a plain todo awaiting authoring. No
+    // screenshot, zero duration.
+    if (!unit.fn) {
+        currentScenarioPending++;
+        if (currentScenarioId) {
+            void reporter.recordStep({
+                scenarioId: currentScenarioId,
+                sequence,
+                kind: unit.kind,
+                name: unit.name,
+                status: 'pending',
+                durationMs: 0,
+                intent: unit.contract?.intent,
+                reason: unit.reason,
+            });
+        }
+        return;
+    }
     const start = Date.now();
-    const fixme = fixmeReason !== undefined;
     let status = 'passed';
     let error;
     try {
-        await fn();
-        // A fixme step that *passes* is a stale marker: surface it as an
+        await unit.fn();
+        // A fixme unit that *passes* is a stale marker: surface it as a
         // 'fixmepass' warning so the author knows they can drop the marker,
         // rather than letting it pass silently.
         if (fixme)
@@ -146,7 +190,7 @@ async function runStep(name, fn, fixmeReason) {
         if (fixme) {
             // Known / tolerated failure. Record it as 'fixme', but DON'T count it
             // toward scenario failures and DON'T re-throw — that's the whole point
-            // of step.fixme: the scenario (and the CI run) stay green, the failure
+            // of .fixme: the scenario (and the CI run) stay green, the failure
             // surfaces as an amber warning on the dashboard.
             status = 'fixme';
         }
@@ -169,11 +213,13 @@ async function runStep(name, fn, fixmeReason) {
             void reporter.recordStep({
                 scenarioId: currentScenarioId,
                 sequence,
-                name,
+                kind: unit.kind,
+                name: unit.name,
                 status,
                 durationMs,
                 error,
-                reason: fixmeReason,
+                intent: unit.contract?.intent,
+                reason: unit.reason,
                 screenshotPath,
             });
         }
@@ -186,6 +232,14 @@ async function runStep(name, fn, fixmeReason) {
  * The body may be sync or async; `step` always returns a promise, so call it
  * with `await step('…', async () => { … })`.
  *
+ * Three forms:
+ * - `step(name, fn)` — executable step (the common case).
+ * - `step(name, { intent, hint })` — a **pending** phase-1 stub: declares the
+ *   step's intent and what to do, but has no body yet. It does not run and
+ *   reports as `pending`; `opice-author` fills in the body.
+ * - `step(name, { intent }, fn)` — an authored step that keeps its durable
+ *   `intent` (preserved verbatim from phase 1) alongside the body.
+ *
  * `step.fixme(name, reason, fn)` marks a **known, tolerated failure**: the body
  * still runs, but a failure inside it does NOT fail the scenario or the CI run —
  * it's reported as an amber warning instead. The `reason` is mandatory (use it
@@ -193,8 +247,47 @@ async function runStep(name, fn, fixmeReason) {
  * step unexpectedly *passes*, it's flagged too ('fixmepass') so a stale marker
  * doesn't linger. Unlike Playwright's `test.fixme()`, which **skips** the test,
  * `step.fixme` **runs** it — the mandatory reason is there to keep them apart.
+ *
+ * `step.blocked(name, reason, contract?)` is a pending stub that **can't be
+ * authored yet** because the app feature doesn't exist — distinct from a plain
+ * `step(name, contract)` stub that's simply awaiting a test. Both report as
+ * 'pending' (scenario reads 'incomplete'); the blocked one carries its reason.
+ */
+export const step = Object.assign((name, arg2, arg3) => {
+    if (typeof arg2 === 'function') {
+        return runUnit({ kind: 'step', name, fn: arg2 });
+    }
+    return runUnit({ kind: 'step', name, contract: arg2, fn: arg3 });
+}, {
+    fixme: (name, reason, fn) => runUnit({ kind: 'step', name, reason, fn }),
+    blocked: (name, reason, contract) => runUnit({ kind: 'step', name, contract, reason }),
+});
+/**
+ * A scenario-level **invariant** — an acceptance property the scenario
+ * enforces, independent of the procedural steps. This is the durable "what
+ * must be true" that used to live in a scenario's prose Notes; expressing it as
+ * a call keeps it in the one source of truth (the test) instead of a separate
+ * `.md` that drifts.
+ *
+ * A failing `invariant` fails the scenario like any hard assertion — it's an
+ * acceptance, not a nicety.
+ *
+ * - `invariant(name, fn)` — enforced now.
+ * - `invariant.todo(name, hint?)` — phase-1 stub: states the acceptance but
+ *   isn't wired yet (status: pending). `opice-author` promotes it to an
+ *   enforced `invariant(...)` (or an `invariant.fixme(...)` if it can't hold
+ *   yet) once it knows how to check it.
+ * - `invariant.blocked(name, reason)` — a pending acceptance that can't be
+ *   wired yet because the feature it guards isn't implemented (vs `.todo`,
+ *   which is merely awaiting authoring). Reports 'pending' with the reason.
+ * - `invariant.fixme(name, reason, fn)` — a known-unenforceable acceptance,
+ *   tolerated like `step.fixme` (e.g. a security property deferred to a
+ *   ticket). The body runs and is expected to fail; the failure is reported as
+ *   an amber warning and neither fails the scenario nor the run.
  */
-export const step = Object.assign((name, fn) => runStep(name, fn), {
-    fixme: (name, reason, fn) => runStep(name, fn, reason),
+export const invariant = Object.assign((name, fn) => runUnit({ kind: 'invariant', name, fn }), {
+    todo: (name, hint) => runUnit({ kind: 'invariant', name, contract: hint ? { hint } : undefined }),
+    blocked: (name, reason) => runUnit({ kind: 'invariant', name, reason }),
+    fixme: (name, reason, fn) => runUnit({ kind: 'invariant', name, reason, fn }),
 });
 //# sourceMappingURL=scenario.js.map

package/dist/scenario.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@opice/harness",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "Runtime primitives for opice — AI-driven E2E browser tests on top of Playwright",
 	"type": "module",
 	"main": "./src/index.ts",

package/src/accessible.ts

@@ -3,6 +3,8 @@ import { getPage } from './context.js'
 
 /** The ARIA role union accepted by Playwright's `getByRole`. */
 type Role = Parameters<Page['getByRole']>[0]
+/** Playwright's `getByRole` options minus `name` (which is passed positionally). */
+type RoleOptions = Omit<NonNullable<Parameters<Page['getByRole']>[1]>, 'name'>
 
 /**
  * Accessible-name selectors — `byRole` / `byLabel` / `byText`.
@@ -21,10 +23,16 @@ type Role = Parameters<Page['getByRole']>[0]
 
 /**
  * Find an element by ARIA role and (optionally) its accessible name.
- * `name` does a substring, case-insensitive match by default.
+ * `name` does a substring, case-insensitive match when a string; pass a
+ * `RegExp` to match the accessible name by pattern (e.g. a generated id).
+ *
+ * `options` forwards the rest of Playwright's `getByRole` filters — most useful
+ * is `level` to pin a heading (`byRole('heading', 'Title', { level: 2 })`), plus
+ * `exact`, `checked`, `pressed`, `expanded`, `disabled`, etc.
  */
-export function byRole(role: Role, name?: string): Locator {
-	return getPage().getByRole(role, name == null ? undefined : { name })
+export function byRole(role: Role, name?: string | RegExp, options?: RoleOptions): Locator {
+	const opts = { ...options, ...(name == null ? {} : { name }) }
+	return getPage().getByRole(role, Object.keys(opts).length > 0 ? opts : undefined)
 }
 
 /** Find a form control by its associated `<label>` (or `aria-label`) text. */

package/src/index.ts

@@ -6,8 +6,8 @@ export { back, currentPath, currentUrl, forward, open, reload } from './navigati
 
 export { getPage, getContext } from './context.js'
 
-export { browserTest, step } from './scenario.js'
-export type { BrowserTestOptions } from './scenario.js'
+export { browserTest, invariant, step } from './scenario.js'
+export type { BrowserTestMeta, StepContract } from './scenario.js'
 
 export { getReporter, setReporter, configureFromEnv } from './reporter.js'
 export type { Reporter, ReporterConfig, StepEvent, ScenarioStart, ScenarioFinish } from './reporter.js'

package/src/reporter.ts

@@ -39,16 +39,27 @@ export interface StepEvent {
 	scenarioId: string
 	/** Authoring order within the scenario, assigned at step() call time. */
 	sequence: number
+	/**
+	 * 'step' (a procedural step) or 'invariant' (a scenario-level acceptance).
+	 * The platform may render invariants distinctly; older workers ignore it.
+	 */
+	kind?: 'step' | 'invariant'
 	name: string
 	/**
 	 * 'fixme' (a step.fixme that failed, as expected) and 'fixmepass' (a
 	 * step.fixme that unexpectedly passed) are tolerated warnings — neither
-	 * fails the scenario.
+	 * fails the scenario. 'pending' is a phase-1 stub that never ran (no body
+	 * yet); a scenario carrying one reads as 'incomplete'.
 	 */
-	status: 'passed' | 'failed' | 'fixme' | 'fixmepass'
+	status: 'passed' | 'failed' | 'fixme' | 'fixmepass' | 'pending'
 	durationMs: number
 	error?: string
-	/** Mandatory note from step.fixme — why the failure is tolerated. */
+	/**
+	 * Durable rationale carried from the unit's contract (phase-1 `intent`) —
+	 * why it exists / what it proves. Surfaced on the dashboard.
+	 */
+	intent?: string
+	/** Mandatory note from .fixme — why the failure is tolerated. */
 	reason?: string
 	screenshotPath?: string
 }
@@ -57,7 +68,12 @@ export interface ScenarioStart {
 	name: string
 	hash?: string
 	testFile?: string
-	scenarioFile?: string
+	/** Requirement / feature id this scenario covers (grouping). */
+	feature?: string
+	/** Seeds required for the scenario (machine-checkable preconditions). */
+	seeds?: string[]
+	/** Identities / roles the scenario acts as. */
+	roles?: string[]
 }
 
 export interface ScenarioFinish {
@@ -133,7 +149,9 @@ class HttpReporter implements Reporter {
 			name: input.name,
 			hash: input.hash,
 			testFile: input.testFile,
-			scenarioFile: input.scenarioFile,
+			feature: input.feature,
+			seeds: input.seeds,
+			roles: input.roles,
 		})
 		return response['scenarioId'] as string
 	}
@@ -154,10 +172,12 @@ class HttpReporter implements Reporter {
 			: undefined
 		await this.fetch('POST', `/api/v1/runs/${runId}/scenarios/${event.scenarioId}/steps`, {
 			sequence: event.sequence,
+			kind: event.kind,
 			name: event.name,
 			status: event.status,
 			durationMs: event.durationMs,
 			error: event.error,
+			intent: event.intent,
 			reason: event.reason,
 			screenshot,
 		})

package/src/scenario.ts

@@ -19,17 +19,38 @@ function bunTest(): typeof import('bun:test') {
 
 const PLAYGROUND_URL = process.env['PLAYGROUND_URL'] ?? 'http://localhost:15180'
 
-export interface BrowserTestOptions {
-	/** Hash fragment appended to PLAYGROUND_URL (e.g. 'datagrid'). */
-	hash?: string
-	/** Override base URL (defaults to PLAYGROUND_URL env). */
+/**
+ * Scenario metadata — the **first** argument to `browserTest`.
+ *
+ * This is the durable, machine-relevant context an opice scenario carries
+ * independent of its concrete steps: where it runs, what it presupposes, what
+ * requirement it covers. It is written in **phase 1** (planning, `opice-plan`)
+ * and preserved through **phase 2** (authoring, `opice-author`) — the scenario
+ * file IS the spec, so this metadata never lives in a separate `.md` that can
+ * drift from the test.
+ *
+ * The rule of thumb for what belongs here vs. a code comment: *does anything
+ * other than a human read it?* Seeds (a precondition a runner could verify),
+ * the feature id (grouping on the dashboard), the acting roles — yes, so they
+ * are first-class fields. Background rationale that only a human reads stays a
+ * comment next to the relevant step.
+ */
+export interface BrowserTestMeta {
+	/** Scenario name — becomes the `describe()` title. Required. */
+	name: string
+	/** Override base URL (defaults to the `PLAYGROUND_URL` env var). */
 	url?: string
+	/** Hash fragment appended to the base URL (e.g. `'datagrid'`). */
+	hash?: string
+	/** Feature / requirement id this scenario covers (e.g. `'F-SML-03a'`). */
+	feature?: string
 	/**
-	 * Path to the human-readable `*.scenario.md` this test was authored from.
-	 * Reported to the platform so the re-eval workflow can find the source.
-	 * If omitted, defaults to the test file path with `.test.ts` → `.scenario.md`.
+	 * Seeds that must be loaded for this scenario to run — machine-checkable
+	 * preconditions, not prose. e.g. `['initial-data', 'crm-master-data']`.
 	 */
-	scenarioFile?: string
+	seeds?: string[]
+	/** Identities / roles the scenario acts as, e.g. `['crmOperator']`. */
+	roles?: string[]
 }
 
 /**
@@ -55,14 +76,10 @@ function captureTestFile(): string | undefined {
 	return undefined
 }
 
-function defaultScenarioFile(testFile: string | undefined): string | undefined {
-	if (!testFile) return undefined
-	return testFile.replace(/\.test\.[tj]sx?$/, '.scenario.md')
-}
-
 let currentScenarioId: string | null = null
 let currentScenarioStart: number = 0
 let currentScenarioFailures = 0
+let currentScenarioPending = 0
 // Monotonic per-scenario step counter. Assigned synchronously at each step()
 // call so order reflects authoring order — step records are POSTed
 // fire-and-forget and would otherwise be sequenced by arrival order at the
@@ -72,25 +89,44 @@ let currentScenarioStepSeq = 0
 /**
  * Register a top-level browser test scenario.
  *
- * Each `browserTest(name, fn)` launches its own isolated Playwright browser +
+ * Each `browserTest(meta, fn)` launches its own isolated Playwright browser +
  * context + page, navigates to the playground URL, runs the given `fn` (which
  * typically contains nested `describe`/`test` blocks), and tears the browser
  * down in `afterAll`.
+ *
+ * Metadata is the **first** argument (`{ name, url, hash, feature, seeds,
+ * roles }`); `name` is required.
  */
-export function browserTest(name: string, fn: () => void, options: BrowserTestOptions | string = {}): void {
-	const opts: BrowserTestOptions = typeof options === 'string' ? { hash: options } : options
+export function browserTest(meta: BrowserTestMeta, fn: () => void): void {
+	if (typeof meta === 'string') {
+		// Migration aid: the old signature was `browserTest(name, fn, options)`.
+		throw new Error(
+			'opice: browserTest now takes metadata first — browserTest({ name, url, hash, … }, fn). '
+			+ `Got a string name (${JSON.stringify(meta)}); wrap it: browserTest({ name: ${JSON.stringify(meta)} }, fn).`,
+		)
+	}
+	if (!meta?.name) {
+		throw new Error('opice: browserTest requires a `name` in its metadata — browserTest({ name: "…" }, fn).')
+	}
 	const reporter = getReporter()
 	const testFile = captureTestFile()
-	const scenarioFile = opts.scenarioFile ?? defaultScenarioFile(testFile)
 	const { describe, beforeAll, afterAll } = bunTest()
 
-	describe(name, () => {
+	describe(meta.name, () => {
 		beforeAll(async () => {
 			currentScenarioStart = Date.now()
 			currentScenarioFailures = 0
+			currentScenarioPending = 0
 			currentScenarioStepSeq = 0
 			try {
-				currentScenarioId = await reporter.startScenario({ name, hash: opts.hash, testFile, scenarioFile })
+				currentScenarioId = await reporter.startScenario({
+					name: meta.name,
+					hash: meta.hash,
+					testFile,
+					feature: meta.feature,
+					seeds: meta.seeds,
+					roles: meta.roles,
+				})
 			} catch {
 				currentScenarioId = null
 			}
@@ -100,8 +136,8 @@ export function browserTest(name: string, fn: () => void, options: BrowserTestOp
 			// own scripts on first paint.
 			const setup = await loadUserSetup()
 			if (setup) await setup(getContext())
-			const base = opts.url ?? PLAYGROUND_URL
-			const url = opts.hash ? `${base}#${opts.hash}` : base
+			const base = meta.url ?? PLAYGROUND_URL
+			const url = meta.hash ? `${base}#${meta.hash}` : base
 			// `domcontentloaded`, not the default `load`: an SPA paints after its JS
 				// runs and may hold `load` on a slow chunk or long-lived connection, so
 				// waiting for `load` flakily times out under CI contention. Readiness is
@@ -115,6 +151,16 @@ export function browserTest(name: string, fn: () => void, options: BrowserTestOp
 			} catch {
 				// ignore close errors
 			}
+			// A scenario still carrying unfilled (pending) steps is a phase-1
+			// skeleton that was run before authoring. It's not a failure, but it's
+			// not done either — make it loud so a half-authored test isn't mistaken
+			// for a passing one.
+			if (currentScenarioPending > 0) {
+				console.warn(
+					`[opice] scenario "${meta.name}" has ${currentScenarioPending} pending step(s) — `
+					+ 'authored skeleton, not yet filled in by opice-author. The body did NOT run.',
+				)
+			}
 			if (currentScenarioId) {
 				// Drain pending step records (incl. their screenshot uploads)
 				// before marking the scenario done. step() fires recordStep
@@ -140,19 +186,78 @@ export function browserTest(name: string, fn: () => void, options: BrowserTestOp
 	})
 }
 
-type StepStatus = 'passed' | 'failed' | 'fixme' | 'fixmepass'
+type StepStatus = 'passed' | 'failed' | 'fixme' | 'fixmepass' | 'pending'
+type StepKind = 'step' | 'invariant'
+
+/**
+ * The durable contract of a step or invariant, separate from its mechanics.
+ *
+ * `intent` is written in **phase 1** and survives **verbatim** into the
+ * authored test — it's the "why this exists / what it proves", the independent
+ * statement of intent that the concrete body is checked against. `hint` is
+ * phase-1 scaffolding *for the authoring agent* ("what to actually do here");
+ * it is consumed when the step is authored and dropped once a body exists.
+ */
+export interface StepContract {
+	/** Durable rationale: why this step/invariant exists, what it proves. */
+	intent?: string
+	/**
+	 * Phase-1 instruction to the authoring agent — what to do on the page here.
+	 * Ephemeral: drop it once the body is written.
+	 */
+	hint?: string
+}
+
+interface RunUnit {
+	kind: StepKind
+	name: string
+	contract?: StepContract
+	/** Present once authored. Absent ⇒ a pending (phase-1) stub. */
+	fn?: () => void | Promise<void>
+	/**
+	 * A human note. With a body (`.fixme`): why a tolerated failure is allowed.
+	 * Without a body (`.blocked`): why the stub can't be authored yet (the app
+	 * feature isn't implemented). A plain pending stub has no reason.
+	 */
+	reason?: string
+}
 
-async function runStep(name: string, fn: () => void | Promise<void>, fixmeReason?: string): Promise<void> {
+async function runUnit(unit: RunUnit): Promise<void> {
 	const reporter = getReporter()
 	// Capture order at call time, before the fire-and-forget record below.
 	const sequence = currentScenarioStepSeq++
+	// A reason *with* a body is a .fixme (tolerated failure). A reason *without*
+	// a body is .blocked (a pending stub that can't be authored yet).
+	const fixme = unit.reason !== undefined && unit.fn !== undefined
+
+	// Phase-1 stub: no body to run. Report it as 'pending' (so the dashboard
+	// shows the skeleton — a scenario carrying one reads as 'incomplete') and
+	// count it so afterAll can warn. A `reason` here marks it 'blocked' (the
+	// feature isn't built); no reason is a plain todo awaiting authoring. No
+	// screenshot, zero duration.
+	if (!unit.fn) {
+		currentScenarioPending++
+		if (currentScenarioId) {
+			void reporter.recordStep({
+				scenarioId: currentScenarioId,
+				sequence,
+				kind: unit.kind,
+				name: unit.name,
+				status: 'pending',
+				durationMs: 0,
+				intent: unit.contract?.intent,
+				reason: unit.reason,
+			})
+		}
+		return
+	}
+
 	const start = Date.now()
-	const fixme = fixmeReason !== undefined
 	let status: StepStatus = 'passed'
 	let error: string | undefined
 	try {
-		await fn()
-		// A fixme step that *passes* is a stale marker: surface it as an
+		await unit.fn()
+		// A fixme unit that *passes* is a stale marker: surface it as a
 		// 'fixmepass' warning so the author knows they can drop the marker,
 		// rather than letting it pass silently.
 		if (fixme) status = 'fixmepass'
@@ -161,7 +266,7 @@ async function runStep(name: string, fn: () => void | Promise<void>, fixmeReason
 		if (fixme) {
 			// Known / tolerated failure. Record it as 'fixme', but DON'T count it
 			// toward scenario failures and DON'T re-throw — that's the whole point
-			// of step.fixme: the scenario (and the CI run) stay green, the failure
+			// of .fixme: the scenario (and the CI run) stay green, the failure
 			// surfaces as an amber warning on the dashboard.
 			status = 'fixme'
 		} else {
@@ -181,17 +286,41 @@ async function runStep(name: string, fn: () => void | Promise<void>, fixmeReason
 			void reporter.recordStep({
 				scenarioId: currentScenarioId,
 				sequence,
-				name,
+				kind: unit.kind,
+				name: unit.name,
 				status,
 				durationMs,
 				error,
-				reason: fixmeReason,
+				intent: unit.contract?.intent,
+				reason: unit.reason,
 				screenshotPath,
 			})
 		}
 	}
 }
 
+type StepBody = () => void | Promise<void>
+
+interface StepFn {
+	/** Executable step. */
+	(name: string, fn: StepBody): Promise<void>
+	/** Phase-1 stub: a step with a contract but no body yet (status: pending). */
+	(name: string, contract: StepContract): Promise<void>
+	/** Authored step that keeps its durable contract. */
+	(name: string, contract: StepContract, fn: StepBody): Promise<void>
+}
+
+interface StepExtras {
+	fixme: (name: string, reason: string, fn: StepBody) => Promise<void>
+	/**
+	 * A **blocked** pending stub: the step can't be authored yet because the app
+	 * feature it covers isn't implemented. Reports as 'pending' with the reason
+	 * attached (the dashboard shows it as blocked, distinct from a plain stub
+	 * that's merely awaiting a test). `reason` is mandatory — say what's missing.
+	 */
+	blocked: (name: string, reason: string, contract?: StepContract) => Promise<void>
+}
+
 /**
  * A reportable step inside a scenario. Captures duration + screenshot on
  * finish, forwards to the active reporter (no-op unless configured via env).
@@ -199,6 +328,14 @@ async function runStep(name: string, fn: () => void | Promise<void>, fixmeReason
  * The body may be sync or async; `step` always returns a promise, so call it
  * with `await step('…', async () => { … })`.
  *
+ * Three forms:
+ * - `step(name, fn)` — executable step (the common case).
+ * - `step(name, { intent, hint })` — a **pending** phase-1 stub: declares the
+ *   step's intent and what to do, but has no body yet. It does not run and
+ *   reports as `pending`; `opice-author` fills in the body.
+ * - `step(name, { intent }, fn)` — an authored step that keeps its durable
+ *   `intent` (preserved verbatim from phase 1) alongside the body.
+ *
  * `step.fixme(name, reason, fn)` marks a **known, tolerated failure**: the body
  * still runs, but a failure inside it does NOT fail the scenario or the CI run —
  * it's reported as an amber warning instead. The `reason` is mandatory (use it
@@ -206,11 +343,63 @@ async function runStep(name: string, fn: () => void | Promise<void>, fixmeReason
  * step unexpectedly *passes*, it's flagged too ('fixmepass') so a stale marker
  * doesn't linger. Unlike Playwright's `test.fixme()`, which **skips** the test,
  * `step.fixme` **runs** it — the mandatory reason is there to keep them apart.
+ *
+ * `step.blocked(name, reason, contract?)` is a pending stub that **can't be
+ * authored yet** because the app feature doesn't exist — distinct from a plain
+ * `step(name, contract)` stub that's simply awaiting a test. Both report as
+ * 'pending' (scenario reads 'incomplete'); the blocked one carries its reason.
+ */
+export const step: StepFn & StepExtras = Object.assign(
+	(name: string, arg2: StepBody | StepContract, arg3?: StepBody): Promise<void> => {
+		if (typeof arg2 === 'function') {
+			return runUnit({ kind: 'step', name, fn: arg2 })
+		}
+		return runUnit({ kind: 'step', name, contract: arg2, fn: arg3 })
+	},
+	{
+		fixme: (name: string, reason: string, fn: StepBody): Promise<void> =>
+			runUnit({ kind: 'step', name, reason, fn }),
+		blocked: (name: string, reason: string, contract?: StepContract): Promise<void> =>
+			runUnit({ kind: 'step', name, contract, reason }),
+	},
+)
+
+/**
+ * A scenario-level **invariant** — an acceptance property the scenario
+ * enforces, independent of the procedural steps. This is the durable "what
+ * must be true" that used to live in a scenario's prose Notes; expressing it as
+ * a call keeps it in the one source of truth (the test) instead of a separate
+ * `.md` that drifts.
+ *
+ * A failing `invariant` fails the scenario like any hard assertion — it's an
+ * acceptance, not a nicety.
+ *
+ * - `invariant(name, fn)` — enforced now.
+ * - `invariant.todo(name, hint?)` — phase-1 stub: states the acceptance but
+ *   isn't wired yet (status: pending). `opice-author` promotes it to an
+ *   enforced `invariant(...)` (or an `invariant.fixme(...)` if it can't hold
+ *   yet) once it knows how to check it.
+ * - `invariant.blocked(name, reason)` — a pending acceptance that can't be
+ *   wired yet because the feature it guards isn't implemented (vs `.todo`,
+ *   which is merely awaiting authoring). Reports 'pending' with the reason.
+ * - `invariant.fixme(name, reason, fn)` — a known-unenforceable acceptance,
+ *   tolerated like `step.fixme` (e.g. a security property deferred to a
+ *   ticket). The body runs and is expected to fail; the failure is reported as
+ *   an amber warning and neither fails the scenario nor the run.
  */
-export const step = Object.assign(
-	(name: string, fn: () => void | Promise<void>): Promise<void> => runStep(name, fn),
+export const invariant: {
+	(name: string, fn: StepBody): Promise<void>
+	todo: (name: string, hint?: string) => Promise<void>
+	blocked: (name: string, reason: string) => Promise<void>
+	fixme: (name: string, reason: string, fn: StepBody) => Promise<void>
+} = Object.assign(
+	(name: string, fn: StepBody): Promise<void> => runUnit({ kind: 'invariant', name, fn }),
 	{
-		fixme: (name: string, reason: string, fn: () => void | Promise<void>): Promise<void> =>
-			runStep(name, fn, reason),
+		todo: (name: string, hint?: string): Promise<void> =>
+			runUnit({ kind: 'invariant', name, contract: hint ? { hint } : undefined }),
+		blocked: (name: string, reason: string): Promise<void> =>
+			runUnit({ kind: 'invariant', name, reason }),
+		fixme: (name: string, reason: string, fn: StepBody): Promise<void> =>
+			runUnit({ kind: 'invariant', name, reason, fn }),
 	},
 )