@feasibleone/blong-chain 1.9.0 → 1.11.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [1.11.0](https://github.com/feasibleone/blong/compare/blong-chain-v1.10.0...blong-chain-v1.11.0) (2026-09-26)
+
+
+### Features
+
+* progress points in test reports ([fb73036](https://github.com/feasibleone/blong/commit/fb730360877eb371ab3d1603ae7bf35976c170dc))
+
+
+### Bug Fixes
+
+* misc CI failures ([60689af](https://github.com/feasibleone/blong/commit/60689af66dc246ef8f88fef8edbd2b8a16a6c4d9))
+
+## [1.10.0](https://github.com/feasibleone/blong/compare/blong-chain-v1.9.0...blong-chain-v1.10.0) (2026-09-24)
+
+
+### Features
+
+* sequence diagram progress points ([dc5b153](https://github.com/feasibleone/blong/commit/dc5b15327f31698a26a75ec73bdf9a0956a43dd9))
+
 ## [1.9.0](https://github.com/feasibleone/blong/compare/blong-chain-v1.8.2...blong-chain-v1.9.0) (2026-09-15)
 
 

package/README.md

@@ -2,9 +2,9 @@
 
 **Parallel test execution with automatic dependency detection through thenable proxies.**
 
-`blong-chain` is a TypeScript test framework that automatically detects
-dependencies between test steps and executes them in parallel when possible,
-maximizing performance while maintaining correctness.
+`blong-chain` is a TypeScript test framework that automatically detects dependencies between test
+steps and executes them in parallel when possible, maximizing performance while maintaining
+correctness.
 
 ## Key Features
 
@@ -14,10 +14,8 @@ maximizing performance while maintaining correctness.
 - 🎯 **Thenable Proxies** - Natural async/await syntax for step dependencies
 - 📈 **Performance Metrics** - Queue time, execution time, and critical path analysis
 - 🌳 **Nested Groups** - Hierarchical test organization with proper indentation
-- 🔧 **Error Handling** - Graceful failure with continued execution of
-  independent steps
-- 🧪 **Test Framework Integration** - Works seamlessly with node:test, tap,
-  and others
+- 🔧 **Error Handling** - Graceful failure with continued execution of independent steps
+- 🧪 **Test Framework Integration** - Works seamlessly with node:test, tap, and others
 
 ## Installation
 
@@ -32,7 +30,7 @@ import {TestExecutor} from '@feasibleone/blong-chain';
 import assert from 'node:assert/strict';
 import {test} from 'node:test';
 
-test('parallel execution example', async (t) => {
+test('parallel execution example', async t => {
     const executor = new TestExecutor({concurrency: 10});
 
     const steps = [
@@ -69,8 +67,7 @@ test('parallel execution example', async (t) => {
 
 ### Thenable Proxies
 
-Steps access previous results through thenable proxies that automatically track
-dependencies:
+Steps access previous results through thenable proxies that automatically track dependencies:
 
 ```typescript
 // Pattern 1: Direct await
@@ -89,7 +86,14 @@ async function step3(assert, {previousStep}) {
 }
 
 // Pattern 4: Deep destructuring
-async function step4(assert, {previousStep: {user: {name}}}) {
+async function step4(
+    assert,
+    {
+        previousStep: {
+            user: {name},
+        },
+    },
+) {
     const userName = await name;
 }
 ```
@@ -155,23 +159,37 @@ Organize steps into hierarchical groups for better structure and output:
 
 ```typescript
 const databaseSetup = [
-    async function connect() { return {connected: true}; },
-    async function createSchema() { return {created: true}; },
-    async function seedData() { return {users: []}; },
+    async function connect() {
+        return {connected: true};
+    },
+    async function createSchema() {
+        return {created: true};
+    },
+    async function seedData() {
+        return {users: []};
+    },
 ] as any;
 databaseSetup.name = 'Database Setup';
 
 const apiTests = [
-    async function testEndpoint1() { return {status: 200}; },
-    async function testEndpoint2() { return {status: 200}; },
+    async function testEndpoint1() {
+        return {status: 200};
+    },
+    async function testEndpoint2() {
+        return {status: 200};
+    },
 ] as any;
 apiTests.name = 'API Tests';
 
 const steps = [
-    async function initialize() { return {ready: true}; },
-    databaseSetup,  // Nested group
-    apiTests,       // Nested group
-    async function cleanup() { return {done: true}; },
+    async function initialize() {
+        return {ready: true};
+    },
+    databaseSetup, // Nested group
+    apiTests, // Nested group
+    async function cleanup() {
+        return {done: true};
+    },
 ];
 
 await executor.execute(steps, {}, t);
@@ -194,9 +212,13 @@ await executor.execute(steps, {}, t);
   ✔ cleanup
 ```
 
-### Checkpoints (Synchronization Barriers)
+### Sync Barriers
+
+Use empty arrays `[]` as sync barriers to synchronize parallel execution. All steps before a barrier
+must complete before any steps after it begin:
 
-Use empty arrays `[]` as checkpoints to synchronize parallel execution. All steps before a checkpoint must complete before any steps after it begin:
+(A _snapshot marker_ — `snapshot('name', ...steps)` — is a different thing: it waits for steps
+**and** snapshots their results. A sync barrier snapshots nothing.)
 
 ```typescript
 const steps = [
@@ -216,7 +238,7 @@ const steps = [
         return {loggerReady: true};
     },
 
-    // Checkpoint: Wait for all Phase 1 steps to complete
+    // Sync barrier: Wait for all Phase 1 steps to complete
     [],
 
     // Phase 2: These run in parallel, but only after Phase 1 completes
@@ -230,7 +252,7 @@ const steps = [
         return await fetchProducts(config.apiUrl);
     },
 
-    // Another checkpoint
+    // Another barrier
     [],
 
     // Phase 3: Runs only after Phase 2 completes
@@ -243,6 +265,7 @@ const steps = [
 ```
 
 **Use Cases:**
+
 - **Phased execution**: Separate initialization, data loading, processing, and cleanup phases
 - **Resource management**: Ensure all resources are ready before proceeding
 - **Testing stages**: Complete all setup before running tests, then cleanup
@@ -255,7 +278,7 @@ Monitor test execution in real-time:
 ```typescript
 const executor = new TestExecutor({concurrency: 10});
 
-executor.on('test:start', (progress) => {
+executor.on('test:start', progress => {
     console.log('Test started:', progress.testName);
 });
 
@@ -314,9 +337,7 @@ console.log(`Critical path: ${latency.criticalPath.join(' → ')}`);
 
 // View bottlenecks
 for (const bottleneck of latency.bottlenecks) {
-    console.log(
-        `${bottleneck.stepName} blocked ${bottleneck.blockedSteps.length} steps`
-    );
+    console.log(`${bottleneck.stepName} blocked ${bottleneck.blockedSteps.length} steps`);
 }
 
 // View individual step metrics
@@ -391,7 +412,7 @@ const executor = new TestExecutor({
 ## Real-World Example
 
 ```typescript
-test('e-commerce checkout flow', async (t) => {
+test('e-commerce checkout flow', async t => {
     const executor = new TestExecutor({concurrency: 5});
 
     const steps = [
@@ -421,9 +442,7 @@ test('e-commerce checkout flow', async (t) => {
             return {amount: product.price * 0.08};
         },
 
-        async function calculateTotal(assert, {
-            loadProduct, calculateShipping, calculateTax
-        }) {
+        async function calculateTotal(assert, {loadProduct, calculateShipping, calculateTax}) {
             const product = await loadProduct;
             const shipping = await calculateShipping;
             const tax = await calculateTax;
@@ -438,9 +457,7 @@ test('e-commerce checkout flow', async (t) => {
             };
         },
 
-        async function processPayment(assert, {
-            calculateTotal, validateInventory
-        }) {
+        async function processPayment(assert, {calculateTotal, validateInventory}) {
             const total = await calculateTotal;
             const inventory = await validateInventory;
 
@@ -465,10 +482,14 @@ test('e-commerce checkout flow', async (t) => {
         },
     ];
 
-    await executor.execute(steps, {
-        testId: 'checkout-001',
-        environment: 'test',
-    }, t);
+    await executor.execute(
+        steps,
+        {
+            testId: 'checkout-001',
+            environment: 'test',
+        },
+        t,
+    );
 
     // Verify results
     const progress = executor.getProgress();
@@ -494,8 +515,7 @@ In this example:
 
 - **[SHOWCASE.md](./SHOWCASE.md)** - Comprehensive feature showcase with all patterns
 - **[TESTING.md](./TESTING.md)** - Testing guide and CI integration
-- **[NESTED_TEST_CONTEXT.md](./NESTED_TEST_CONTEXT.md)** - Test framework
-  integration details
+- **[NESTED_TEST_CONTEXT.md](./NESTED_TEST_CONTEXT.md)** - Test framework integration details
 - **[test-types.ts](./test-types.ts)** - Complete TypeScript API documentation
 
 ## Running Tests
@@ -514,17 +534,17 @@ npm run test:all
 
 ## How It Works
 
-1. **Detection Phase**: When you destructure or access `context.stepName`, a
-   thenable proxy is returned
+1. **Detection Phase**: When you destructure or access `context.stepName`, a thenable proxy is
+   returned
 2. **Dependency Tracking**: The access is recorded as a dependency
 3. **Scheduling Phase**: Steps are added to a priority queue based on dependencies
 4. **Execution Phase**: Steps run as soon as all their dependencies complete
 5. **Resolution Phase**: Step results are stored and proxies are resolved
-6. **Checkpoints**: Empty arrays `[]` create synchronization barriers, waiting for
-   all previous steps to complete before continuing
+6. **Sync Barriers**: Empty arrays `[]` create synchronization barriers, waiting for all previous
+   steps to complete before continuing
 
-This creates a dynamic dependency graph that enables maximum parallelization
-while ensuring correctness, with optional synchronization points for phased execution.
+This creates a dynamic dependency graph that enables maximum parallelization while ensuring
+correctness, with optional synchronization points for phased execution.
 
 ## Use Cases
 

package/index.ts

@@ -13,10 +13,12 @@
 import assert from 'node:assert';
 import {EventEmitter} from 'node:events';
 import PQueue from 'p-queue';
+import {progressTree, reportProgress} from './progress.ts';
 import type {
     IDependencyEdge,
     IDependencyGraph,
     IMeta,
+    IProgressEntry,
     IPromiseEntry,
     ISourceLocation,
     IStepError,
@@ -371,7 +373,7 @@ function captureSourceLocation(): ISourceLocation {
 const DEFAULT_MAX_RETRIES = 1;
 
 // ============================================================================
-// Masking helpers (also used by assert.snapshot and checkpoint snapshots)
+// Masking helpers (also used by assert.snapshot and snapshot markers)
 // ============================================================================
 
 /**
@@ -542,13 +544,13 @@ export class TestExecutor extends EventEmitter {
     ): Promise<void> {
         const stepPromises: Promise<void>[] = [];
         const namedPromises = new Map<string, Promise<void>>();
-        let checkpointIndex = 0;
+        let snapshotIndex = 0;
 
         for (const step of steps) {
             if (Array.isArray(step)) {
                 // Distinguish by element type:
                 //   [] empty array        → sync barrier (existing behaviour)
-                //   ['*'] / ['s1','s2']  → snapshot checkpoint (new)
+                //   ['*'] / ['s1','s2']  → snapshot marker
                 //   [fn, ...] nested     → nested step group (existing behaviour)
                 if (step.length === 0) {
                     // Sync barrier — wait for all parallel steps in this batch
@@ -558,37 +560,35 @@ export class TestExecutor extends EventEmitter {
                 }
 
                 if (step.every(s => typeof s === 'string')) {
-                    // Snapshot checkpoint: await relevant steps, then snapshot
-                    const checkpoint = step as unknown as string[];
+                    // Snapshot marker: await the relevant steps, then snapshot
+                    const marker = step as unknown as string[];
 
-                    if (checkpoint.length === 1 && checkpoint[0] === '*') {
+                    if (marker.length === 1 && marker[0] === '*') {
                         // ['*'] — wait for entire current batch
                         await Promise.all(stepPromises);
                         stepPromises.length = 0;
                     } else {
                         // ['step1','step2'] — wait only for the named steps
-                        const namedToWait = checkpoint
+                        const namedToWait = marker
                             .map(name => namedPromises.get(name))
                             .filter((p): p is Promise<void> => p !== undefined);
                         await Promise.all(namedToWait);
                         // stepPromises is NOT cleared — other steps keep running
                     }
                     const cpName =
-                        (checkpoint as {name?: string}).name ??
-                        (checkpoint.length === 1 && checkpoint[0] === '*'
-                            ? `context`
-                            : checkpoint.join('-'));
+                        (marker as {name?: string}).name ??
+                        (marker.length === 1 && marker[0] === '*' ? `context` : marker.join('-'));
                     // Disambiguate when the same name is used more than once
                     const snapshotName =
-                        checkpointIndex === 0 ? cpName : `${cpName}-${checkpointIndex}`;
-                    checkpointIndex++;
+                        snapshotIndex === 0 ? cpName : `${cpName}-${snapshotIndex}`;
+                    snapshotIndex++;
 
                     const stepsToSnapshot =
-                        checkpoint.length === 1 && checkpoint[0] === '*'
+                        marker.length === 1 && marker[0] === '*'
                             ? [...this.progress.steps.entries()]
                                   .filter(([, s]) => s.status === 'completed')
                                   .map(([name]) => name)
-                            : checkpoint.filter(name =>
+                            : marker.filter(name =>
                                   Object.prototype.hasOwnProperty.call(this.realContext, name),
                               );
 
@@ -653,6 +653,43 @@ export class TestExecutor extends EventEmitter {
         await Promise.all(stepPromises);
     }
 
+    /**
+     * The invocation's progress list as it stands, for a read at a step boundary (PRD R26/R27).
+     *
+     * The `$meta` object is the one every step of this run shares — the same object the steps
+     * destructure, and the one the handlers they call are handed.
+     */
+    private _progressList(): IProgressEntry[] | undefined {
+        const progress = (this.realContext.$meta as IMeta | undefined)?.progress;
+        return Array.isArray(progress) ? progress : undefined;
+    }
+
+    /**
+     * What was announced since `seen`, or `undefined` when nothing was (PRD R26/R27).
+     *
+     * Two shapes, and both are ordinary. A list that still holds what it held is *appended* to,
+     * and the difference between the two boundary reads is the step's own progress. A list that
+     * no longer begins with those entries was **replaced**: a step that resets it to scope its
+     * own assertions (`$meta.progress = []`, which is how a scenario keeps one step's
+     * checkpoints out of the next one's) then owns everything in the new list, including when it
+     * happens to end up as long as it started.
+     *
+     * Best-effort attribution, and deliberately so: steps that run in parallel share the one
+     * list, so a point announced while two of them were running is reported by whichever
+     * boundary read it. It is never lost, and a scenario whose steps are ordered by their
+     * dependencies — which is what a test that asserts on progress is — has one at a time.
+     */
+    private _announcedSince(seen: IProgressEntry[] | undefined): IProgressEntry[] | undefined {
+        const progress = this._progressList();
+        if (progress === undefined || progress.length === 0) {
+            return undefined;
+        }
+        if (!keeps(progress, seen)) {
+            return progress;
+        }
+        return progress.length > seen.length ? progress.slice(seen.length) : undefined;
+    }
+
     /**
      * Executes a single step function
      */
@@ -703,8 +740,6 @@ export class TestExecutor extends EventEmitter {
         // Wrap execution function for potential test context wrapping
         // When a TAP sub-test context is supplied, assert is augmented with:
         //   assert.snapshot(value, 'name', opts?)   — explicit snapshot
-        //   assert.snapshot({mask?: []})             — deferred: snapshot the
-        //                                              step's return value
         //   assert.snapshot()                        — deferred, no extra mask
         // Deferred snapshots are taken after fn() returns, under the step name.
         // eslint-disable-next-line @typescript-eslint/no-this-alias
@@ -762,6 +797,7 @@ export class TestExecutor extends EventEmitter {
             this.graph.nodes.get(stepName)!.status = 'running';
             this.graph.nodes.get(stepName)!.startTime = latency.startedAt;
 
+            const progressBefore = this._progressList();
             this.emit('step:start', stepName, stepProgress);
 
             try {
@@ -823,6 +859,11 @@ export class TestExecutor extends EventEmitter {
                 // Store result in real context
                 this.realContext[stepName] = result;
 
+                // What this step announced, read at the boundary before the event so a
+                // listener that writes the step's result file sees it (see `step:end`).
+                const announced = this._announcedSince(progressBefore);
+                if (announced !== undefined) stepProgress.progress = announced;
+
                 // Resolve all promises for this step
                 this.promiseManager.resolveStep(stepName, result);
 
@@ -847,6 +888,24 @@ export class TestExecutor extends EventEmitter {
 
                 this.progress.completedSteps++;
                 this.emit('step:end', stepName, stepProgress);
+
+                // A point becomes a sub-test of the step that announced it, and a branch the
+                // sub-test holding the points taken inside it — a checkpoint as a *step* in
+                // the report, which is what "checkpoints drive test reporting" claims
+                // (PRD R26/R27). Rendered from the same entries `blong-allure` maps into
+                // Allure steps, so the two reports cannot describe different shapes.
+                //
+                // The context is checked the way the snapshot handling checks it, because
+                // the queue hands the task its own options where there is no test context:
+                // only a context that can nest a test gets progress nested in it.
+                if (
+                    typeof stepTestContext?.test === 'function' &&
+                    stepProgress.progress !== undefined
+                ) {
+                    for (const node of progressTree(stepProgress.progress)) {
+                        await reportProgress(stepTestContext, node);
+                    }
+                }
             } catch (error) {
                 // Handle error
                 latency.completedAt = Date.now();
@@ -871,6 +930,12 @@ export class TestExecutor extends EventEmitter {
                 this.graph.nodes.get(stepName)!.endTime = latency.completedAt;
                 this.graph.nodes.get(stepName)!.error = error as Error;
 
+                // Kept even though the step failed, and especially then: what a failing step
+                // announced is the evidence a reader wants, and Allure renders it from here.
+                // The tap side leaves it out — sub-tests are not added to a step that threw.
+                const announcedOnFailure = this._announcedSince(progressBefore);
+                if (announcedOnFailure !== undefined) stepProgress.progress = announcedOnFailure;
+
                 this.progress.failedSteps++;
                 this.emit('step:error', stepName, error as Error, stepProgress);
                 this.log?.error?.({err: error}, `step ${stepName} failed`);
@@ -940,7 +1005,7 @@ export class TestExecutor extends EventEmitter {
 
         for (const step of steps) {
             if (Array.isArray(step)) {
-                // Skip checkpoint markers (string-only arrays) — they are not steps
+                // Skip snapshot markers (string-only arrays) — they are not steps
                 if (step.every(s => typeof s === 'string')) continue;
                 // Recursively collect from nested step groups
                 const nested = this._collectStepNames(step as StepArray);
@@ -1119,3 +1184,21 @@ export class TestExecutor extends EventEmitter {
 
 // Export all types
 export type * from './test-types.js';
+export {progressTree, reportProgress} from './progress.ts';
+
+/**
+ * Whether a progress list still holds what it held, entry for entry and by identity.
+ *
+ * Identity rather than equality, because the entries are objects the recorder pushed: a list
+ * that kept them is one that was spread back with additions, and a list whose first entry is a
+ * different object is one that was reset and announced afresh — which is the difference between
+ * a step *adding* to the invocation's progress and *replacing* it.
+ */
+const keeps = (
+    progress: IProgressEntry[],
+    seen: IProgressEntry[] | undefined,
+): seen is IProgressEntry[] =>
+    progress === seen ||
+    (seen !== undefined &&
+        progress.length >= seen.length &&
+        seen.every((entry, at) => progress[at] === entry));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feasibleone/blong-chain",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "Parallel testing with automatic dependencies",
   "keywords": [
     "blong",
@@ -24,7 +24,7 @@
     "@types/node": "^24",
     "tap": "^21.6.3",
     "typescript": "^6.0.3",
-    "@feasibleone/blong-dev": "1.4.0"
+    "@feasibleone/blong-dev": "1.7.0"
   },
   "scripts": {
     "build": "heft build --clean",
@@ -33,7 +33,7 @@
     "ci-lint": "blong-dev lint",
     "ci-publish": "node ../../common/scripts/install-run-rush-pnpm.js publish --access public --provenance",
     "ci-test": "blong-dev test '*.test.ts';./test-examples-ci.sh",
-    "test": "tap *.test.ts",
-    "test:examples": "node --test dist/examples/*.test.js"
+    "test": "blong-dev test '*.test.ts';./test-examples-ci.sh",
+    "test:examples": "node --test examples/*.test.ts"
   }
 }

package/test-types.ts

@@ -49,26 +49,28 @@ export type StepFunction = (
 ) => unknown | Promise<unknown>;
 
 /**
- * A snapshot checkpoint — an array of step-name strings placed inside the
- * steps array. At runtime, when the executor encounters it the current batch
- * is awaited and the listed step results are snapshotted into the TAP context.
+ * A snapshot marker — an array of step-name strings placed inside the
+ * steps array. At runtime, when the executor encounters it the relevant steps
+ * are awaited and their results snapshotted into the TAP context.
  *
  * - `['*']`            — snapshot ALL completed steps' results into one context object
  * - `['step1', 'step2']` — snapshot only those specific steps
- * - `[]`               — sync barrier only, no snapshot (existing behaviour)
+ * - `[]`               — sync barrier only, no snapshot (the empty array is the spelling;
+ *                        there is no symbol for it, because inventing one would touch every
+ *                        call site for no gain)
  *
  * The array may carry an optional `.name` to give the snapshot a stable name:
  * ```
- * const cp = Object.assign(['*'], {name: 'provisioning-complete'});
+ * const marker = Object.assign(['*'], {name: 'provisioning-complete'});
  * ```
  */
-export type CheckpointMarker = string[] & {name?: string};
+export type SnapshotMarker = string[] & {name?: string};
 
 /**
  * Array of test steps. May contain step functions, nested step groups, or
- * checkpoint markers (string arrays).
+ * snapshot markers (string arrays; `[]` being a sync barrier).
  */
-export type StepArray = (StepFunction | StepArray | CheckpointMarker)[] & {name?: string};
+export type StepArray = (StepFunction | StepArray | SnapshotMarker)[] & {name?: string};
 
 /**
  * Meta information passed through test execution
@@ -76,6 +78,15 @@ export type StepArray = (StepFunction | StepArray | CheckpointMarker)[] & {name?
 export interface IMeta {
     /** Optional concurrency limit for parallel step execution */
     concurrency?: number;
+    /**
+     * What the invocation has announced so far, in the order it announced it (PRD R26/R27).
+     *
+     * The same array a framework dispatch keeps on its own `$meta`: the handlers a step calls
+     * are handed this object, so whatever they announce while it runs appears here — which is
+     * the only place the executor can read a step's progress from, and why it reads it at the
+     * step's boundaries.
+     */
+    progress?: IProgressEntry[];
     /** Additional metadata properties */
     [key: string]: unknown;
 }
@@ -87,6 +98,14 @@ export interface IMeta {
 export interface ITestFrameworkContext {
     /** Creates a nested test scope for proper indentation */
     test: (name: string, fn: (t: unknown) => void | Promise<void>) => unknown;
+    /**
+     * Writes a comment into the run's output (`# …` in TAP).
+     *
+     * What a point is reported as: a moment a step passed through is not a test,
+     * so it does not deserve a sub-test of its own — but it is what a reader
+     * wants to see beside the step, which is what a comment is.
+     */
+    comment?: (text: string) => void;
     /** Captures a snapshot of a value under the given name */
     matchSnapshot?: (value: unknown, name: string) => void;
 }
@@ -199,6 +218,71 @@ export interface IDependencyEdge {
 // Progress Tracking Types
 // ============================================================================
 
+/**
+ * A branch as a progress entry names it (PRD R11/R26).
+ *
+ * Declared structurally here, matching the framework's own declaration in
+ * `core/blong/types.ts` the way {@link IMeta} does, because this package stands at the bottom
+ * of the dependency graph with `p-queue` as its only dependency. The names are what a report
+ * groups by; the position a log mints for itself is deliberately not here.
+ */
+export interface IRegionMark {
+    /** What the branch was about, stable across runs. */
+    discriminator: string;
+    /** Every candidate considered, in evaluation order. */
+    candidates: string[];
+    /** The branch taken, or `none` when none of them matched. */
+    chosen: string;
+}
+
+/** A milestone an invocation announced (PRD R26). */
+export interface IProgressPoint {
+    /** Which of the two shapes this entry is; one array holds both. */
+    kind: 'point';
+    /** Stable name of the moment, e.g. `total-calculated`. */
+    name: string;
+    /** What was true there; kept locally, exactly as a record keeps it. */
+    data?: unknown;
+    /** When it was announced, in epoch milliseconds. */
+    timestamp: number;
+    /** The branches it was announced *inside*, outermost first. */
+    regions?: IRegionMark[];
+}
+
+/** A branch the invocation took, in the same array as the points (PRD R11/R26). */
+export interface IProgressRegion extends IRegionMark {
+    /** Which of the two shapes this entry is; one array holds both. */
+    kind: 'region';
+    /** The values the decision was made from. */
+    values: Record<string, unknown>;
+    /** The branches this one was itself taken inside, outermost first. */
+    regions?: IRegionMark[];
+}
+
+/** One entry of an invocation's `progress` list. */
+export type IProgressEntry = IProgressPoint | IProgressRegion;
+
+/**
+ * One node of the progress tree a report is drawn from (PRD R26/R27).
+ *
+ * `name` is the display name rather than the raw entry, so both renderers label a branch the
+ * same way: `<discriminator> = <chosen>` for a region, the point's own name for a point.
+ */
+export interface IProgressNode {
+    /** What a report calls it: the point's name, or `<discriminator> = <chosen>`. */
+    name: string;
+    /** Which of the two shapes it is. */
+    kind: 'point' | 'region';
+    /**
+     * What the point announced, printed beside it when it is small enough to read.
+     *
+     * A branch carries none: what it has to say is its name.
+     */
+    data?: Record<string, unknown>;
+    /** The points and branches announced inside it, in the order they were announced. */
+    children: IProgressNode[];
+}
+
 /**
  * Overall test execution progress
  */
@@ -257,6 +341,17 @@ export interface IStepProgress {
     result?: unknown;
     /** Error information if step failed */
     error?: IStepError;
+    /**
+     * What this step announced while it ran (PRD R26/R27), or absent when it announced
+     * nothing.
+     *
+     * Read from the invocation's own list at the step's boundaries rather than reported by the
+     * step: the handlers it called announced into the `$meta` every step shares, so the window
+     * is the only thing that attributes a point to the step that made it. A report draws these
+     * as the step's nested steps — a point as a step, a branch as the group of the points
+     * taken inside it.
+     */
+    progress?: IProgressEntry[];
 }
 
 /**
@@ -370,7 +465,7 @@ export interface ITestExecutorConfig {
     log?: ITestLogger;
     /**
      * Chain-level mask paths. Applied to ALL snapshot operations in this chain:
-     * `autoSnapshot`, `assert.snapshot()`, and checkpoint snapshots.
+     * `autoSnapshot`, `assert.snapshot()`, and snapshot markers.
      *
      * Supports:
      * - Simple name: `'id'` — masks the `id` field in the snapshotted value