@semiont/core 0.5.23 → 0.5.24

package/dist/testing.d.ts

@@ -1,71 +1,5 @@
-import { Observable, BehaviorSubject } from 'rxjs';
-import { StateUnit, ITransport, BaseUrl, ConnectionState, SemiontError, BusOperationKey, EventMap, ResourceId, EventBus } from '@semiont/core';
-import * as fc from 'fast-check';
-
-/**
- * Executable enforcement of the StateUnit pattern — the runtime twin of
- * `packages/sdk/docs/STATE-UNITS.md` and the ledger in
- * `.plans/STATE-UNIT-AXIOMS.md`. The `StateUnit` interface's own comment notes
- * the pattern is convention; this file makes it executable.
- *
- * `assertStateUnitAxioms(spec)` runs every applicable axiom against a factory in
- * one shot, throwing a labeled Error on the first violation (the axiom id is in
- * the message). It is framework-agnostic on purpose — only `rxjs` + `fast-check`,
- * no `vitest` — so it ships through `@semiont/core/testing` and any package's test
- * runner can invoke it from a single `it(...)` per state unit. It lives in core
- * (not sdk) so even packages below sdk (e.g. `http-transport`) can use it without
- * a dependency cycle.
- *
- * Axioms (random-input dimension; fast-check):
- *   A5        dispose() is idempotent and total (n ∈ [1,20] calls never throw)
- *   A5b       post-dispose inertness — every public method is a no-op after dispose
- *   A6        every pre-dispose subscriber (k ∈ [1,10]) sees `complete` on dispose
- *   X3-runtime instance isolation — driving one instance never moves another's surfaces
- * Structural assertions (single-shot):
- *   A1        plain-object identity (no class instance)
- *   X1        no raw Subject on the public surface
- *   A7-passed disposing the unit must NOT dispose an injected dependency
- *   A7-owned  disposing the unit MUST dispose its internally-constructed children
- */
-
-/**
- * A disposable stand-in for an injected dependency. Pass one as a unit's
- * constructor arg, then list it in `setup().passedIn` so A7-passed can assert
- * the unit never disposed it. Counts calls so A7-passed also holds under the
- * repeated-dispose stress of A5.
- */
-interface DisposeProbe extends StateUnit {
-    readonly disposeCount: number;
-}
-declare function disposeProbe(): DisposeProbe;
-type SetupResult<T extends StateUnit> = T | {
-    unit: T;
-    passedIn?: readonly DisposeProbe[];
-    teardown?: () => void;
-};
-interface StateUnitAxiomSpec<T extends StateUnit> {
-    /**
-     * Build a FRESH unit. Called many times (fast-check re-runs), so it must
-     * return an independent instance each call. Return the bare unit, or an object
-     * carrying the injected `passedIn` probes (A7-passed) and a `teardown` to
-     * release per-instance resources (e.g. a mock bus).
-     */
-    setup: () => SetupResult<T>;
-    /** Owned public Observables — Subjects the unit completes on dispose (A6, X3, post-dispose inertness). */
-    surfaces?: (unit: T) => readonly Observable<unknown>[];
-    /** Public input methods as zero-arg callers (A5b post-dispose, X3 drive). */
-    invocations?: (unit: T) => readonly (() => unknown)[];
-    /** Surfaces of internally-constructed children — must complete when the outer disposes (A7-owned). */
-    ownedChildSurfaces?: (unit: T) => readonly Observable<unknown>[];
-    /** fast-check run budget per property (default 30). */
-    numRuns?: number;
-}
-/**
- * Run every applicable axiom against `spec`. Throws a labeled Error on the first
- * violation. Axioms whose accessors are omitted are skipped (e.g. A7-passed
- * runs only when `setup` returns `passedIn`; A6 only when `surfaces` is given).
- */
-declare function assertStateUnitAxioms<T extends StateUnit>(spec: StateUnitAxiomSpec<T>): void;
+import { BehaviorSubject, Observable } from 'rxjs';
+import { ITransport, BaseUrl, ConnectionState, SemiontError, BusOperationKey, EventMap, ResourceId, EventBus } from '@semiont/core';
 
 /**
  * FaultyTransport — a seeded, scriptable `ITransport` simulator for the
@@ -111,6 +45,18 @@ interface RequestLogEntry {
      * the same key are the same logical request re-issued.
      */
     retryKey: string;
+    /**
+     * The payload as emitted — envelope, options, params, `correlationId` and
+     * all. This is the surface for "assert what my orchestrator actually SENT"
+     * (SDK-TESTING-DOUBLE gap 6): without it every consumer harness re-invented
+     * a per-channel `transport.on(...)` wire recorder alongside this log.
+     *
+     * SHALLOW snapshot: the top level is copied at emit time, so a caller that
+     * mutates its own payload object afterwards cannot rewrite history. Nested
+     * objects are shared by reference — deep-freeze is not worth the cost in a
+     * double, and no in-repo caller mutates nested request payloads.
+     */
+    payload: Record<string, unknown>;
 }
 interface FaultyTransportConfig {
     /**
@@ -169,113 +115,5 @@ declare class FaultyTransport implements ITransport {
     dispose(): void;
 }
 
-/**
- * Executable enforcement of the liveness axioms — the runtime twin of
- * `.plans/LIVENESS-AXIOMS.md`, and the composition-level sibling of
- * `assertStateUnitAxioms` (state-unit-axioms.ts). Where the StateUnit axioms
- * make *per-unit* wrongness mechanically detectable, these make *silence*
- * detectable: every existing enforcement tier is safety (nothing wrong is
- * delivered); these assert liveness (something is eventually delivered).
- *
- * Axioms (fault-schedule dimension; fast-check):
- *   L1  Subscriber liveness — every output emits next|error within the bound,
- *       under any fault schedule. Error is a permitted outcome; the forbidden
- *       fourth state is pending-forever.
- *   L2  Request settlement — every awaited path settles within the bound;
- *       re-issues per logical request stay within the retry budget (B14: one);
- *       a faulted request must be re-issued or surfaced, never swallowed.
- *   L3  Delivery across lifecycle transitions — every event written to a live
- *       connection reaches the output exactly once, wherever a client-initiated
- *       transition (handover / reconnect / scope change) lands. Retirement is
- *       by drain, never by abort (TRANSPORT-HTTP.md, Abort discipline).
- *
- * Framework-agnostic on purpose — only `rxjs` + `fast-check`, no `vitest` — so
- * it ships through `@semiont/core/testing` and any package's test runner can
- * invoke it. Deterministic virtual time: properties pass a small explicit
- * `timeoutMs` to `busRequest`; no `Date.now`, no 30 s real waits.
- */
-
-/** What one fresh run of the composition exposes to the axioms. */
-interface LivenessScenario {
-    /**
-     * Live-query-shaped outputs. The harness subscribes each one; every
-     * subscription must see `next` or `error` within the bound (L1).
-     */
-    outputs: readonly Observable<unknown>[];
-    /**
-     * Awaited paths. Each promise must settle — resolve or reject — within the
-     * bound (L2). Rejections are fine; pending-forever is the violation.
-     */
-    settlements?: readonly Promise<unknown>[];
-    teardown?: () => void;
-}
-interface LivenessAxiomSpec {
-    /** Build a FRESH composition wired to the given transport. Called per run. */
-    setup: (transport: FaultyTransport) => LivenessScenario | Promise<LivenessScenario>;
-    /**
-     * The timeoutMs the scenario passes to `busRequest` — the bound is derived
-     * from it: (timeoutMs × (1 + retryBudget) + Σdelays) × slackFactor.
-     */
-    timeoutMs: number;
-    /** Max sanctioned re-issues per logical request (B14 budget). Default 1. */
-    retryBudget?: number;
-    /** Override the generated fault schedules (teeth tests pin one). */
-    scheduleArb?: fc.Arbitrary<readonly FaultAction[]>;
-    /** Passed through to FaultyTransport (reply synthesis). */
-    makeResponse?: (operation: string, payload: Record<string, unknown>) => unknown;
-    /** fast-check run budget (default 25 — CI-fast; crank locally). */
-    numRuns?: number;
-    /** Real-scheduler jitter headroom on the bound (default 4×). */
-    slackFactor?: number;
-}
-/** The five wire behaviors, uniformly weighted; delays stay small (≤5 ms). */
-declare function arbFaultAction(): fc.Arbitrary<FaultAction>;
-declare function arbFaultSchedule(maxLength?: number): fc.Arbitrary<readonly FaultAction[]>;
-/**
- * Run L1 + L2 against `spec` across generated fault schedules. Throws a
- * labeled Error (`L1: …` / `L2: …`) on the first violation.
- */
-declare function assertLivenessAxioms(spec: LivenessAxiomSpec): Promise<void>;
-/**
- * A connection-stream-shaped subject: something that accepts writes to the
- * live connection, can be told to transition (handover / reconnect / scope
- * change), and exposes the subscriber-facing output. P3 adapts the real
- * actor's mock-connection harness to this shape; the teeth tests drive
- * reconstructed pre-fix doubles.
- */
-interface DeliverySubject {
-    /** Write the event with this id to the currently-live connection. */
-    write: (eventId: string) => void;
-    /** Client-initiated lifecycle transition. */
-    transition: () => void | Promise<void>;
-    /** Subscriber-facing output; each emission is a delivered event id. */
-    output$: Observable<string>;
-    /**
-     * Drain pending asynchronous delivery at end of sequence (a live connection
-     * eventually flushes). Default: one macrotask tick.
-     */
-    settle?: () => Promise<void>;
-    teardown?: () => void;
-}
-type DeliveryOp = 'write' | 'transition';
-interface DeliveryAxiomSpec {
-    /** Build a FRESH subject. Called per run. */
-    setup: () => DeliverySubject;
-    /** Override the generated op sequences (teeth tests pin one). */
-    opsArb?: fc.Arbitrary<readonly DeliveryOp[]>;
-    /** Max generated sequence length (default 12). */
-    maxOps?: number;
-    /** fast-check run budget (default 50 — these runs are cheap). */
-    numRuns?: number;
-}
-declare function arbDeliveryOps(maxOps?: number): fc.Arbitrary<readonly DeliveryOp[]>;
-/**
- * Run L3 against `spec` across generated write/transition interleavings.
- * Throws a labeled Error (`L3: …`) on the first violation: an event written
- * to a live connection delivered zero times (lost — retired by abort instead
- * of drain) or more than once (duplicate).
- */
-declare function assertExactlyOnceDelivery(spec: DeliveryAxiomSpec): Promise<void>;
-
-export { FaultyTransport, arbDeliveryOps, arbFaultAction, arbFaultSchedule, assertExactlyOnceDelivery, assertLivenessAxioms, assertStateUnitAxioms, disposeProbe, retryKeyOf };
-export type { DeliveryAxiomSpec, DeliveryOp, DeliverySubject, DisposeProbe, FaultAction, FaultyTransportConfig, LivenessAxiomSpec, LivenessScenario, RequestLogEntry, StateUnitAxiomSpec };
+export { FaultyTransport, retryKeyOf };
+export type { FaultAction, FaultyTransportConfig, RequestLogEntry };