@pikku/core 0.12.72 → 0.12.77

package/dist/wirings/workflow/run-timeline.d.ts

@@ -1,50 +1,20 @@
 import type { SerializedError } from '../../types/core.types.js';
 import type { StepState, StepStatus } from './workflow.types.js';
-/**
- * Time-travel over a workflow run.
- *
- * A run's durable history (`getRunHistory`) is one row per step *attempt*, each
- * carrying lifecycle timestamps (created/scheduled/running/succeeded/failed).
- * `buildRunTimeline` explodes those rows into a flat, chronologically-ordered
- * event stream, and `reconstructStateAt` folds the stream up to any point to
- * recover what the run "knew" then — the same step cache a replay would hold:
- * per-step status, accumulated results, and the walked path.
- *
- * These are pure functions over history — no IO — so they're trivially testable
- * and transport-independent (the same fold works for Redis/Kysely/in-memory).
- */
-/** A single observable transition of one step attempt. */
 export interface RunTimelineEvent {
-    /** Monotonic 0-based position in the timeline. */
     seq: number;
-    /** When it happened. */
     at: Date;
-    /** The step's new status at this event (matches StepStatus lifecycle). */
     type: Extract<StepStatus, 'pending' | 'scheduled' | 'running' | 'succeeded' | 'failed'>;
-    /** Physical step name (includes revisit ordinal, e.g. `attempt#2`). */
     stepName: string;
-    /** Which attempt this event belongs to (1-based). */
     attemptCount: number;
-    /** Predecessor that scheduled this step — only on the `pending` (created)
-     *  event; undefined for entry steps. Reconstructs the walked edge. */
     fromStepName?: string;
-    /** Result snapshot — only on `succeeded`. */
     result?: unknown;
-    /** Error snapshot — only on `failed`. */
     error?: SerializedError;
 }
 export type RunTimeline = RunTimelineEvent[];
 type HistoryEntry = StepState & {
     stepName: string;
 };
-/**
- * Build the ordered event stream for a run from its raw history.
- *
- * History is expected oldest-first but is sorted defensively by (timestamp,
- * lifecycle, original index) so simultaneous timestamps stay deterministic.
- */
 export declare function buildRunTimeline(history: HistoryEntry[]): RunTimeline;
-/** A step's reconstructed state at a point in the timeline. */
 export interface ReconstructedStep {
     stepName: string;
     status: StepStatus;
@@ -53,33 +23,16 @@ export interface ReconstructedStep {
     result?: unknown;
     error?: SerializedError;
 }
-/** Coarse run phase derived purely from step states (not the run's output). */
 export type RunPhase = 'pending' | 'running' | 'failed' | 'idle';
-/** The whole run's reconstructed state at a point in the timeline. */
 export interface ReconstructedRunState {
     /** seq of the last applied event, or -1 if the point precedes all events. */
     seq: number;
-    /** Wall-clock time of the last applied event. */
     at?: Date;
-    /** Per-step latest state, in first-seen (walked) order. */
     steps: ReconstructedStep[];
-    /** Outputs available to downstream steps — the replay step cache at this
-     *  point (succeeded steps only). */
     results: Record<string, unknown>;
-    /** Step names in the order they were first created — the walked path. */
     path: string[];
-    /** Derived phase: `running` if any step is in-flight, else `failed` if a step
-     *  is failed with no in-flight work, else `idle` (between transitions). */
     phase: RunPhase;
 }
-/**
- * Fold the timeline up to `at` and return the run's state at that point.
- *
- * `at` is either a seq index (inclusive — apply events `0..at`) or a `Date`
- * (inclusive — apply every event at or before that instant). A point before the
- * first event yields the empty initial state.
- */
 export declare function reconstructStateAt(timeline: RunTimeline, at: number | Date): ReconstructedRunState;
-/** Reconstruct the final state (fold the whole timeline). */
 export declare function reconstructFinalState(timeline: RunTimeline): ReconstructedRunState;
 export {};

package/dist/wirings/workflow/run-timeline.js

@@ -1,4 +1,3 @@
-/** Lifecycle tiebreak for events that share a timestamp. */
 const LIFECYCLE_ORDER = {
     pending: 0,
     scheduled: 1,
@@ -6,12 +5,6 @@ const LIFECYCLE_ORDER = {
     succeeded: 3,
     failed: 3,
 };
-/**
- * Build the ordered event stream for a run from its raw history.
- *
- * History is expected oldest-first but is sorted defensively by (timestamp,
- * lifecycle, original index) so simultaneous timestamps stay deterministic.
- */
 export function buildRunTimeline(history) {
     const raw = [];
     history.forEach((entry, order) => {
@@ -20,24 +13,18 @@ export function buildRunTimeline(history) {
             attemptCount: entry.attemptCount,
             order,
         };
-        // The created event always exists; it carries provenance.
         raw.push({
             ...base,
             at: entry.createdAt,
             type: 'pending',
             fromStepName: entry.fromStepName,
         });
-        // Intermediate events are optional enrichment — emit only if the backend
-        // recorded their timestamp.
         if (entry.scheduledAt) {
             raw.push({ ...base, at: entry.scheduledAt, type: 'scheduled' });
         }
         if (entry.runningAt) {
             raw.push({ ...base, at: entry.runningAt, type: 'running' });
         }
-        // The terminal event is driven by the row's authoritative status (the
-        // lifecycle timestamps aren't populated by every backend — Kysely leaves
-        // them null), falling back to updatedAt when the specific stamp is absent.
         if (entry.status === 'succeeded') {
             raw.push({
                 ...base,
@@ -73,13 +60,6 @@ const IN_FLIGHT = new Set([
     'scheduled',
     'running',
 ]);
-/**
- * Fold the timeline up to `at` and return the run's state at that point.
- *
- * `at` is either a seq index (inclusive — apply events `0..at`) or a `Date`
- * (inclusive — apply every event at or before that instant). A point before the
- * first event yields the empty initial state.
- */
 export function reconstructStateAt(timeline, at) {
     const cutoff = (event) => typeof at === 'number'
         ? event.seq <= at
@@ -109,7 +89,6 @@ export function reconstructStateAt(timeline, at) {
         if (event.fromStepName !== undefined) {
             step.fromStepName = event.fromStepName;
         }
-        // A retry's created event reopens the step — drop the prior outcome.
         if (event.type === 'pending') {
             delete step.result;
             delete step.error;
@@ -138,7 +117,6 @@ export function reconstructStateAt(timeline, at) {
         phase: derivePhase(orderedSteps),
     };
 }
-/** Reconstruct the final state (fold the whole timeline). */
 export function reconstructFinalState(timeline) {
     return reconstructStateAt(timeline, timeline.length - 1);
 }

package/dist/wirings/workflow/scenario-cookie-jar.d.ts

@@ -1,29 +1,6 @@
-/** A session held the way a browser holds one, for code driving a real target. */
 export interface ScenarioCookieJar {
-    /** `fetch`, but it sends what the target has set and keeps what it sets. */
     fetch: typeof fetch;
-    /** Forgets the session — what an actor does before signing in again. */
     clear(): void;
-    /**
-     * Whether the target has set anything yet. This is a fact about the jar, not
-     * about the session: a target that sets a CSRF or locale cookie before anyone
-     * signs in fills the jar without establishing one. Whoever needs to know
-     * whether a sign-in happened has to track the sign-in.
-     */
     readonly empty: boolean;
 }
-/**
- * A `fetch` that remembers cookies.
- *
- * A browser persists the session cookie on its own; anything driving a target
- * from this process has to. Every response is read, not just the sign-in, so a
- * cookie the target rotates mid-session is followed rather than dropped.
- *
- * The jar is a closure local, so two jars never share a session — which is what
- * lets one scenario sign in as several people without one of them inheriting
- * the other's session.
- *
- * It also stamps `Origin`, because Better Auth rejects a state-changing POST
- * whose Origin does not match its baseURL.
- */
 export declare const createCookieJar: (apiUrl: string) => ScenarioCookieJar;

package/dist/wirings/workflow/scenario-cookie-jar.js

@@ -1,17 +1,3 @@
-/**
- * A `fetch` that remembers cookies.
- *
- * A browser persists the session cookie on its own; anything driving a target
- * from this process has to. Every response is read, not just the sign-in, so a
- * cookie the target rotates mid-session is followed rather than dropped.
- *
- * The jar is a closure local, so two jars never share a session — which is what
- * lets one scenario sign in as several people without one of them inheriting
- * the other's session.
- *
- * It also stamps `Origin`, because Better Auth rejects a state-changing POST
- * whose Origin does not match its baseURL.
- */
 export const createCookieJar = (apiUrl) => {
     const jar = new Map();
     const origin = new URL(apiUrl).origin;
@@ -31,8 +17,6 @@ export const createCookieJar = (apiUrl) => {
                 if (separator > 0) {
                     const name = pair.slice(0, separator);
                     const value = pair.slice(separator + 1);
-                    // An empty value is how a target deletes a cookie — drop the name
-                    // rather than holding a cookie whose value says it is gone.
                     if (value) {
                         jar.set(name, value);
                     }

package/dist/wirings/workflow/scenario-poll.d.ts

@@ -1,20 +1,5 @@
-/** How long to keep trying, and how long to wait between tries. */
 export interface PollOptions {
-    /** Total time to keep attempting before giving up. Default 15s. */
     timeoutMs?: number;
-    /** Gap between attempts. Default 250ms. */
     intervalMs?: number;
 }
-/**
- * Attempt something until it answers, or the deadline passes.
- *
- * `undefined` means "not yet" and nothing else — `false`, `0` and `''` are all
- * answers, because a probe asking whether something happened reports `false`
- * when it did not. Answering `undefined` at the deadline rather than throwing
- * leaves the error to the caller, who is the only one who knows what was being
- * waited for.
- *
- * A step that polls its target — a delivery reaching a terminal status, a run
- * finishing — reaches for this rather than writing the deadline loop again.
- */
 export declare const pollUntil: <T>(attempt: () => Promise<T | undefined> | T | undefined, { timeoutMs, intervalMs }?: PollOptions) => Promise<T | undefined>;

package/dist/wirings/workflow/scenario-poll.js

@@ -1,15 +1,3 @@
-/**
- * Attempt something until it answers, or the deadline passes.
- *
- * `undefined` means "not yet" and nothing else — `false`, `0` and `''` are all
- * answers, because a probe asking whether something happened reports `false`
- * when it did not. Answering `undefined` at the deadline rather than throwing
- * leaves the error to the caller, who is the only one who knows what was being
- * waited for.
- *
- * A step that polls its target — a delivery reaching a terminal status, a run
- * finishing — reaches for this rather than writing the deadline loop again.
- */
 export const pollUntil = async (attempt, { timeoutMs = 15_000, intervalMs = 250 } = {}) => {
     const deadline = Date.now() + timeoutMs;
     for (;;) {

package/dist/wirings/workflow/scenario-prose.d.ts

@@ -1,38 +1,10 @@
 import type { ScenarioStepPhase } from './scenario-step.types.js';
-/**
- * Renders the English sentence a reporter shows for a scenario step.
- *
- * This is the inversion of cucumber: rather than parsing English into a call,
- * we render English out of a typed call, so the readable report survives
- * without a regex registry paying for it.
- *
- * Lives in core so the CLI reporter and the console render identically.
- */
-/**
- * Fill a step's `template` from the input that step was actually called with,
- * so the reported sentence names the values under test — "sees @pikku/addon-todos"
- * rather than "sees an addon in the gallery" repeated three times.
- *
- * A placeholder with no recorded value renders as nothing and the surrounding
- * whitespace collapses, so an optional input that was omitted reads as a shorter
- * sentence rather than a literal `{state}` leaking into the report.
- */
 export declare const renderStepTemplate: (template: string, input: unknown) => string;
 export declare const composeStepProse: ({ phase, description, template, input, actor, keywordWidth, }: {
     phase: ScenarioStepPhase;
     description: string;
-    /**
-     * The prose this step renders, with `{placeholders}` filled from `input`.
-     * Unlike `description`, which documents what the step does, this is what a
-     * reader of the report sees. Falls back to `description` when absent.
-     */
     template?: string;
-    /** The input this step was called with, as recorded on the run. */
     input?: unknown;
     actor?: string;
-    /**
-     * Pad the keyword to this width so a ladder of steps lines its sentences up
-     * under each other. Omit for inline prose.
-     */
     keywordWidth?: number;
 }) => string;

package/dist/wirings/workflow/scenario-prose.js

@@ -1,21 +1,3 @@
-/**
- * Renders the English sentence a reporter shows for a scenario step.
- *
- * This is the inversion of cucumber: rather than parsing English into a call,
- * we render English out of a typed call, so the readable report survives
- * without a regex registry paying for it.
- *
- * Lives in core so the CLI reporter and the console render identically.
- */
-/**
- * Fill a step's `template` from the input that step was actually called with,
- * so the reported sentence names the values under test — "sees @pikku/addon-todos"
- * rather than "sees an addon in the gallery" repeated three times.
- *
- * A placeholder with no recorded value renders as nothing and the surrounding
- * whitespace collapses, so an optional input that was omitted reads as a shorter
- * sentence rather than a literal `{state}` leaking into the report.
- */
 export const renderStepTemplate = (template, input) => {
     const values = input && typeof input === 'object' ? input : {};
     return template
@@ -33,7 +15,7 @@ const formatValue = (value) => {
     return String(value);
 };
 export const composeStepProse = ({ phase, description, template, input, actor, keywordWidth, }) => {
-    const keyword = phase === 'step' ? '' : capitalise(phase);
+    const keyword = capitalise(phase);
     const subject = actor ? `the ${actor}` : '';
     const rendered = template ? renderStepTemplate(template, input) : description;
     const sentence = [subject, rendered].filter(Boolean).join(' ');

package/dist/wirings/workflow/scenario-step-guards.d.ts

@@ -1,16 +1,3 @@
 import type { PikkuScenarioStepWire, ScenarioEnvironment } from './scenario-step.types.js';
-/**
- * The actor this step was called with, or a loud error naming the step.
- *
- * A step that talks to the target app needs an identity, but `actor` is
- * optional on the wire because a pure assertion step needs none. This is the
- * one place that narrowing happens, so every step file stops writing its own
- * `actorOf(...)` guard.
- */
 export declare const requireActor: <TActor>(scenarioStep: PikkuScenarioStepWire<TActor> | undefined) => TActor;
-/**
- * The environment this run targets, or a loud error naming the step. A run
- * started outside `pikku scenario run` only carries one when the server has
- * `API_URL` configured.
- */
 export declare const requireScenarioEnv: (scenarioStep: PikkuScenarioStepWire<unknown> | undefined) => ScenarioEnvironment;

package/dist/wirings/workflow/scenario-step-guards.js

@@ -1,11 +1,3 @@
-/**
- * The actor this step was called with, or a loud error naming the step.
- *
- * A step that talks to the target app needs an identity, but `actor` is
- * optional on the wire because a pure assertion step needs none. This is the
- * one place that narrowing happens, so every step file stops writing its own
- * `actorOf(...)` guard.
- */
 export const requireActor = (scenarioStep) => {
     const actor = scenarioStep?.actor;
     if (!actor) {
@@ -14,16 +6,11 @@ export const requireActor = (scenarioStep) => {
     }
     return actor;
 };
-/**
- * The environment this run targets, or a loud error naming the step. A run
- * started outside `pikku scenario run` only carries one when the server has
- * `API_URL` configured.
- */
 export const requireScenarioEnv = (scenarioStep) => {
     const env = scenarioStep?.env;
     if (!env) {
         throw new Error(`[scenario] step '${scenarioStep?.name ?? 'unknown'}' needs the target environment, but this run carries none. ` +
-            `Run it through 'pikku scenario run <environment>' with scenarios.environments.<environment> declared in pikku.config.json.`);
+            `Run it through 'pikku scenario run <environment>' with environments.<environment> declared in pikku.config.json.`);
     }
     return env;
 };

package/dist/wirings/workflow/scenario-step.types.d.ts

@@ -1,25 +1,92 @@
-import type { ScenarioActor } from '../../services/scenario-actors-service.js';
+import type { ScenarioPersona } from '../../services/personas-service.js';
 /**
  * Scenario steps: named, typed units of scenario behaviour.
  *
  * A step's body is an ordinary pikku function, so it may drive a browser, call
- * an RPC as its actor, or run a workflow. `given`/`when`/`then` are sugar over
- * `step` — they only change the prose the reporter renders.
+ * an RPC as its actor, or run a workflow. `given` and `when` differ only in the
+ * prose the reporter renders; `then` also changes what runs, because its
+ * bindings are witnesses — every declared surface is observed and the
+ * observations must agree. See {@link ScenarioSurfaceResolution}.
  */
 /**
- * Which Gherkin-style keyword the reporter prefixes this step with. `step`
- * renders no prefix at all.
+ * Which Gherkin-style keyword the reporter prefixes this step with.
+ *
+ * Every step takes one. A scenario is read by people deciding whether it
+ * describes the behaviour they wanted, and a step that says only what it does
+ * without saying whether it is setup, action or claim is the one nobody can
+ * check — which is also why PKU680 can tell a scenario that never asserts.
+ */
+export type ScenarioStepPhase = 'given' | 'when' | 'then';
+/**
+ * Who acts in a step.
+ *
+ * `persona` is a person driving the system through one of its surfaces — the
+ * ordinary `pikkuScenarioStep`. `platform` is the app acting on itself ("the
+ * platform has expired the trial"), and `addon` is a third-party system acting
+ * on it ("Stripe's webhook arrives"), contributed by the addon that wraps that
+ * service.
+ *
+ * The three are separate declarations rather than a field on one, so the
+ * inspector verifies a step's kind by which function was called rather than by
+ * trusting a string literal — and so an addon package exports only addon steps,
+ * which is checkable.
  */
-export type ScenarioStepPhase = 'step' | 'given' | 'when' | 'then';
+export type ScenarioStepKind = 'persona' | 'platform' | 'addon';
 /**
- * Options accepted by `scenario.step/given/when/then`.
+ * How an actor drives the system for one step.
+ *
+ * A step declares one implementation per surface it supports, and the runner
+ * picks between them — so the same ladder can run through a real browser, over
+ * the websocket, or entirely server-side.
+ *
+ * `default` is the floor: it is what every other surface falls back to, so it
+ * can never itself fall back.
+ */
+export type ScenarioSurface = 'browser' | 'cli' | 'default';
+export declare const SCENARIO_SURFACES: readonly ScenarioSurface[];
+/**
+ * How a step's declared surfaces resolve for one run.
+ *
+ * `given`/`when` bindings are **alternatives** — clicking Buy and calling
+ * `createOrder` are two ways to cause one effect, so exactly one runs.
+ *
+ * `then` bindings are **witnesses** — "the order row says paid" and "the
+ * confirmation panel says paid" are different claims that share a name, and the
+ * gap between them is the bug nobody catches. So every declared witness runs and
+ * they must agree.
+ */
+export type ScenarioSurfaceResolution = {
+    kind: 'action';
+    surface: ScenarioSurface;
+    /** The run asked for a surface this step does not implement. */
+    fellBack: boolean;
+} | {
+    kind: 'witness';
+    /**
+     * Every witness to run, surface first. Empty means the assertion has no
+     * binding this run can execute at all — nothing would check anything, so
+     * the step fails rather than reporting a pass it never earned.
+     */
+    surfaces: ScenarioSurface[];
+    /**
+     * Something checked the assertion, but not on the surface its prose
+     * claims — so nobody looked at the UI. Reported as its own state and
+     * counted against coverage: not being in the UI *is* the finding.
+     *
+     * Disjoint from an empty `surfaces`; an assertion that ran nowhere is a
+     * failure, not a coverage statistic.
+     */
+    unwitnessed: boolean;
+};
+/**
+ * Options accepted by `scenario.given/when/then`.
  *
  * Note the retry default differs from an ordinary workflow step: retrying a
  * failed assertion is the wrong behaviour for a test primitive, so steps
  * default to no retries.
  */
 export interface ScenarioStepOptions {
-    /** The actor this step runs as. Required for steps declaring `browser: true`. */
+    /** The actor this step runs as. Required for steps declaring a `browser` binding. */
     actor?: unknown;
     /** Overrides the step's own `description` for this call site only. */
     description?: string;
@@ -29,7 +96,7 @@ export interface ScenarioStepOptions {
 }
 /**
  * The environment a scenario run targets, as declared in pikku.config.json
- * under `scenarios.environments`.
+ * under `environments`.
  */
 export interface ScenarioEnvironment {
     /** Base API URL of the target app, INCLUDING the HTTP prefix. */
@@ -41,16 +108,21 @@ export interface ScenarioEnvironment {
  * The `scenarioStep` wire, present on every scenario step invocation.
  *
  * `TActor` is the project's own actor type, so a step reaches only the RPCs its
- * actors can actually call. It defaults to the open `ScenarioActor` for a
+ * actors can actually call. It defaults to the open `ScenarioPersona` for a
  * project that declares no registry.
  */
-export interface PikkuScenarioStepWire<TActor = ScenarioActor> {
+export interface PikkuScenarioStepWire<TActor = ScenarioPersona> {
     /** Registered step name (also its pikkuFuncId) */
     name: string;
     /** Durable key within the run; may carry an `#ordinal` suffix when repeated */
     stepName: string;
     runId: string;
     phase: ScenarioStepPhase;
+    /**
+     * Which of the step's bindings is currently executing. A `then` step runs once
+     * per witness, so its body sees this change between invocations.
+     */
+    surface: ScenarioSurface;
     /**
      * The actor this step runs as, when one was given. Call RPCs through it
      * (`actor.invoke(...)`) so they run against the target environment as that
@@ -89,7 +161,7 @@ export interface TestIdSelector {
 }
 /**
  * Structural browser handle, present only when the runner provisioned a
- * browser for this step (`browser: true` on the step config).
+ * browser for this step (a `browser` binding on the step config).
  *
  * `@pikku/core` deliberately never imports playwright — it must stay
  * dependency-free for edge runtimes. `@pikku/playwright` augments this

package/dist/wirings/workflow/scenario-step.types.js

@@ -1 +1,5 @@
-export {};
+export const SCENARIO_SURFACES = [
+    'browser',
+    'cli',
+    'default',
+];

package/dist/wirings/workflow/scenario-surface.d.ts

@@ -0,0 +1,16 @@
+import type { ScenarioStepPhase, ScenarioSurface, ScenarioSurfaceResolution } from './scenario-step.types.js';
+/**
+ * Resolve which of a step's declared bindings run, for one step, in one run.
+ *
+ * The asymmetry between phases is the whole point — see
+ * {@link ScenarioSurfaceResolution}.
+ */
+export declare const resolveScenarioSurfaces: (phase: ScenarioStepPhase, declared: readonly ScenarioSurface[], runSurface: ScenarioSurface) => ScenarioSurfaceResolution;
+/**
+ * Structural comparison of two witnesses' observations.
+ *
+ * A witness that returns `undefined` asserted by throwing rather than by
+ * reporting what it saw, so it is not compared — that keeps assertion-style
+ * steps working without forcing every one of them to return a value.
+ */
+export declare const witnessesAgree: (a: unknown, b: unknown) => boolean;

package/dist/wirings/workflow/scenario-surface.js

@@ -0,0 +1,56 @@
+/**
+ * Resolve which of a step's declared bindings run, for one step, in one run.
+ *
+ * The asymmetry between phases is the whole point — see
+ * {@link ScenarioSurfaceResolution}.
+ */
+export const resolveScenarioSurfaces = (phase, declared, runSurface) => {
+    const has = (surface) => declared.includes(surface);
+    if (phase !== 'then') {
+        if (has(runSurface)) {
+            return { kind: 'action', surface: runSurface, fellBack: false };
+        }
+        return { kind: 'action', surface: 'default', fellBack: true };
+    }
+    const surfaces = [];
+    if (runSurface !== 'default' && has(runSurface)) {
+        surfaces.push(runSurface);
+    }
+    if (has('default')) {
+        surfaces.push('default');
+    }
+    return {
+        kind: 'witness',
+        surfaces,
+        // Only meaningful once something ran: an assertion checked server-side
+        // under `--run browser` is a coverage gap, but one checked nowhere at all
+        // is a step that did not happen, which the caller fails rather than counts.
+        unwitnessed: surfaces.length > 0 && runSurface !== 'default' && !has(runSurface),
+    };
+};
+/**
+ * Structural comparison of two witnesses' observations.
+ *
+ * A witness that returns `undefined` asserted by throwing rather than by
+ * reporting what it saw, so it is not compared — that keeps assertion-style
+ * steps working without forcing every one of them to return a value.
+ */
+export const witnessesAgree = (a, b) => {
+    if (a === undefined || b === undefined) {
+        return true;
+    }
+    return stableStringify(a) === stableStringify(b);
+};
+const stableStringify = (value) => {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value) ?? 'undefined';
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(',')}]`;
+    }
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
+    return `{${entries.join(',')}}`;
+};

package/dist/wirings/workflow/workflow-invocation-id.d.ts

@@ -1,20 +1,2 @@
-/**
- * RFC 4122 v5 (SHA-1, name-based) UUID. Deterministic: the same name +
- * namespace always yields the same UUID — no `uuid` dependency needed.
- */
 export declare const uuidv5: (name: string, namespace?: string) => string;
-/**
- * The stable identity of one step *invocation* within a run — the idempotency /
- * dedupe key handed to a step. Unlike `stepId` (minted fresh per attempt), this
- * stays identical across every retry of the same call, because it is derived
- * purely from `runId` + `stepName`, both of which are stable across replays.
- *
- * Same inputs → same UUID, so a step can safely
- * `INSERT … ON CONFLICT (invocation_id)` / pass it as a Stripe idempotency key,
- * and a retry of a half-applied side effect is collapsed onto the first attempt.
- *
- * NOTE: calling the *same* `stepName` more than once in a run is not yet
- * disambiguated here (the store still keys steps by `runId:stepName`); when
- * per-invocation ordinals land, the ordinal becomes the third hash component.
- */
 export declare const deriveInvocationId: (runId: string, stepName: string) => string;

package/dist/wirings/workflow/workflow-invocation-id.js

@@ -1,38 +1,18 @@
 import { createHash } from 'node:crypto';
-// Fixed namespace for pikku workflow step invocation IDs. Frozen — changing it
-// would alter every derived invocationId and break dedupe across a deploy.
 const PIKKU_WORKFLOW_NAMESPACE = '70696b6b-7500-5770-9f6c-6f77000a0001';
 const parseUuid = (uuid) => Buffer.from(uuid.replace(/-/g, ''), 'hex');
 const formatUuid = (bytes) => {
     const hex = bytes.toString('hex');
     return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
 };
-/**
- * RFC 4122 v5 (SHA-1, name-based) UUID. Deterministic: the same name +
- * namespace always yields the same UUID — no `uuid` dependency needed.
- */
 export const uuidv5 = (name, namespace = PIKKU_WORKFLOW_NAMESPACE) => {
     const hash = createHash('sha1')
         .update(parseUuid(namespace))
         .update(name, 'utf8')
         .digest();
     const bytes = hash.subarray(0, 16);
-    bytes[6] = (bytes[6] & 0x0f) | 0x50; // version 5
-    bytes[8] = (bytes[8] & 0x3f) | 0x80; // RFC 4122 variant
+    bytes[6] = (bytes[6] & 0x0f) | 0x50;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
     return formatUuid(bytes);
 };
-/**
- * The stable identity of one step *invocation* within a run — the idempotency /
- * dedupe key handed to a step. Unlike `stepId` (minted fresh per attempt), this
- * stays identical across every retry of the same call, because it is derived
- * purely from `runId` + `stepName`, both of which are stable across replays.
- *
- * Same inputs → same UUID, so a step can safely
- * `INSERT … ON CONFLICT (invocation_id)` / pass it as a Stripe idempotency key,
- * and a retry of a half-applied side effect is collapsed onto the first attempt.
- *
- * NOTE: calling the *same* `stepName` more than once in a run is not yet
- * disambiguated here (the store still keys steps by `runId:stepName`); when
- * per-invocation ordinals land, the ordinal becomes the third hash component.
- */
 export const deriveInvocationId = (runId, stepName) => uuidv5(`${runId}:${stepName}`);