@systemfsoftware/trace-spec 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @systemfsoftware/trace-spec
 
+## 0.4.0
+
+### Minor Changes
+
+- `Contract.check(expect, input, options?)` takes the test's `expect` and ends in one check: a break fails it with the report as the message. `Contract.judge` returns the `{ verdict: 'Hold' | 'Break', report }` value, and `Contract.verdictCheck(contract, expect, judgment)` turns one into a check. `TraceDisparityError` is removed. `Suite` cases register as generator tests and judge each case once.
+
+### Patch Changes
+
+- Updated dependencies:
+  - @systemfsoftware/vitest@0.1.0
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -10,7 +10,7 @@ In a system with queues, workers, and background consumers, a `200` is not the o
 pnpm add @systemfsoftware/trace-spec @systemfsoftware/trace-taxonomy effect
 ```
 
-The package exports nine namespaces — `Contract`, `Graph`, `Observation`, `ObservationWindow`, `RemoteObservation`, `Rel`, `Stimulus`, `Suite`, `TempoTraceStore`. Errors and verdicts belong to the capability that raises them: `Contract.ContractDecodeError`, `Contract.TraceDisparityError`, `Observation.EmptyObservationError`, `Observation.IncompleteObservationError`, `Observation.TransportObservationError`, `Suite.StimulusFailure`, and `Rel.Hold`/`Rel.Break`/`Rel.Verdict`.
+The package exports nine namespaces — `Contract`, `Graph`, `Observation`, `ObservationWindow`, `RemoteObservation`, `Rel`, `Stimulus`, `Suite`, `TempoTraceStore`. Errors belong to the capability that raises them: `Contract.ContractDecodeError`, `Observation.EmptyObservationError`, `Observation.IncompleteObservationError`, `Observation.TransportObservationError`, `Suite.StimulusFailure`; the verdicts are `Rel.Hold`/`Rel.Break`/`Rel.Verdict`. A break is not an error: it is the check the contract states in the test, and the report is that check's message.
 
 ## Write a contract
 
@@ -40,11 +40,22 @@ const paymentUnderCheckout = Contract.of(checkout)
 
 `Contract.judge(contract, input)` stimulates the behaviour under its minted trace, collects that trace's spans, decodes them against the taxonomy (`Graph.decode` answers `Result<TraceGraph, Contract.ContractDecodeError>`), applies the relation, and on a break writes the decoded graph under `artifacts/traces/`. It answers a `Contract.Judgment` — the run, the verdict, and the dump path — so a break is a value, not a failure. Behaviour failures and infrastructure refusals (`Contract.ContractDecodeError` and the three `Observation` failures) stay on the error channel.
 
-`Contract.check(contract, input)` is the test edge over `judge`: a break fails with `Contract.TraceDisparityError`. Navigation over the decoded graph is standalone: `Graph.byId`, `Graph.children`, and `Graph.descendants`.
+`Contract.check(contract, expect, input)` is the test edge over `judge`, and takes the `expect` the test body received. It ends in the judgement's one check: a hold is the check passing, and a break fails it with the report — the relation that broke, the conjunct it was evaluating, the spans it inspected, the trace, and where the decoded graph was written. `Contract.verdictCheck(contract, expect, judgment)` states an already judged contract the same way, and `Contract.Report` — `{ verdict, report }`, the report empty on a hold — is what the check asserts.
+
+```ts
+import { Contract } from '@systemfsoftware/trace-spec'
+import { it } from '@systemfsoftware/vitest'
+
+it('a charged settlement satisfies the contract', function*({ expect }) {
+  yield* Contract.check(chargeBeneathSettlement, expect, { orderId: 'order-7', charge: true })
+})
+```
+
+Navigation over the decoded graph is standalone: `Graph.byId`, `Graph.children`, and `Graph.descendants`.
 
 | Outcome                                       | Failure                                  | Meaning                                                                                            |
 | --------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| The relation broke                            | `Contract.TraceDisparityError`           | names the broken conjunct, the spans inspected, and where the decoded graph was written            |
+| The relation broke                            | the judgement's check                    | its message is the report: the broken conjunct, the spans inspected, the trace and the dump path   |
 | A contracted span lacked a required attribute | `Contract.ContractDecodeError`           | names the declaration and the attribute — never reported as a broken relation                      |
 | Nothing ran under the owned trace             | `Observation.EmptyObservationError`      | the observation was empty, which is its own outcome, not a break                                   |
 | The trace never finished arriving             | `Observation.IncompleteObservationError` | spans were read but kept changing, or the store marked the trace partial; carries the span count   |
@@ -54,11 +65,11 @@ const paymentUnderCheckout = Contract.of(checkout)
 
 ```ts
 import { NodeFileSystem } from '@effect/platform-node'
-import { it, layer } from '@effect/vitest'
 import { Observation, ObservationWindow, Suite } from '@systemfsoftware/trace-spec'
+import { it } from '@systemfsoftware/vitest'
 import { Layer } from 'effect'
 
-const TraceSuite = Suite.make({ it, layer })
+const TraceSuite = Suite.make({ it })
 const harness = Layer.mergeAll(ObservationWindow.make('checkout').layer, NodeFileSystem.layer, CheckoutDoubles)
 
 TraceSuite('checkout.place_order')
@@ -68,11 +79,11 @@ TraceSuite('checkout.place_order')
   })
 ```
 
-`Suite.make({ it, layer })(name)` stages a suite as a Pipeable builder, and `withLayer`/`withScenarioLayer` are `dual` combinators whose terminal `body` registers the cases. The scenario layer is built fresh per case and must provide `Observation.Observation` and a `FileSystem` for failure dumps, plus whatever the stimulated behaviour needs — the requirement is enforced at the type level. A failing case fails with the harness's own error channel — the outcomes above, or `Suite.StimulusFailure` when the behaviour itself failed before its trace could be judged. Cases run on the live clock.
+`Suite.make({ it })(name)` stages a suite as a Pipeable builder, and `withLayer`/`withScenarioLayer` are `dual` combinators whose terminal `body` registers the cases. The scenario layer is built fresh per case and must provide `Observation.Observation` and a `FileSystem` for failure dumps, plus whatever the stimulated behaviour needs — the requirement is enforced at the type level. A failing case fails with the harness's own error channel — the outcomes above, or `Suite.StimulusFailure` when the behaviour itself failed before its trace could be judged. Cases run on the kernel under the zero-preemption schedule plus the profile's seeded PCT schedules; every case gets its own crypto-random salt, so two cases never share a trace id. A case that must stay on the live clock declares why with `.live(reason)` at any stage before `body` (including the `Suite.live` dual), and the reason appears in the run report.
 
-`.withLayer(shared)` registers the suite over a layer built once for the whole suite; the shared layer then carries the observation harness, and `.withScenarioLayer(scenario)` can follow it for what each case needs fresh.
+`.withLayer(shared)` registers the suite over a layer rebuilt fresh for each case for replay; the shared layer then carries the observation harness, and `.withScenarioLayer(scenario)` can follow it for what each case needs fresh.
 
-`Case.prop(title, contract, schema)` runs the contract over inputs drawn from the Schema's derived arbitrary through `it.effect.prop` on the suite's runner, so shrinking is the runner's own: a failing draw fails the property and the runner reports the smallest failing input. The dump is named after the case title, so every failing draw overwrites one file and the surviving dump is the reported counterexample's evidence. When a case fails with a `Contract.TraceDisparityError`, the test carries a Vitest annotation naming that dump, so the decoded graph is found from the failing test.
+`Case.prop(title, contract, schema)` runs the contract over inputs drawn from the Schema's derived arbitrary through `it.effect.prop` on the suite's runner, so shrinking is the runner's own: a failing draw fails the property and the runner reports the smallest failing input. The dump is named after the case title, so every failing draw overwrites one file and the surviving dump is the reported counterexample's evidence. When a case's relation breaks, its check fails with the report and the test carries a Vitest annotation naming that dump, so the decoded graph is found from the failing test.
 
 ## Observe in memory
 

package/dist/index.d.ts

@@ -4,8 +4,9 @@ import { Span, Taxonomy } from "@systemfsoftware/trace-taxonomy";
 import * as HttpClient from "effect/unstable/http/HttpClient";
 import * as OtelTracer from "@effect/opentelemetry/OtelTracer";
 import { Blueprint, Handle } from "@systemfsoftware/effect-cell-types";
-import { BasicTracerProvider, InMemorySpanExporter } from "@opentelemetry/sdk-trace-base";
+import { BasicTracerProvider, ReadableSpan } from "@opentelemetry/sdk-trace-base";
 import { Suite } from "@systemfsoftware/effect-spec-runtime";
+import { Asserted, Check, Expect } from "@systemfsoftware/vitest";
 import * as Scope from "effect/Scope";
 import * as Arbitrary from "effect/unstable/arbitrary/Arbitrary";
 //#region src/ContractDecodeError.schema.d.ts
@@ -261,17 +262,8 @@ declare const make$3: <Input, Output, E, R>(options: {
     readonly traceparent: string;
   }) => Effect.Effect<Output, E, R>;
 }) => Stimulus<Input, Output, E, R>;
-//#endregion
-//#region src/TraceDisparityError.schema.d.ts
-declare const TraceDisparityError_base: Schema.Class<TraceDisparityError, Schema.TaggedStruct<"TraceDisparityError", {
-  readonly relationId: Schema.String;
-  readonly traceId: Schema.String;
-  readonly breaks: Schema.$Array<typeof Break>;
-  readonly dumpPath: Schema.NullOr<Schema.String>;
-}>, import("effect/Cause").YieldableError>;
-declare class TraceDisparityError extends TraceDisparityError_base {}
 declare namespace Contract_d_exports {
-  export { CheckFailure, CheckOptions, Contract, ContractDecodeError, Declared$1 as Declared, EmptyObservationError, IncompleteObservationError, JudgeFailure, Judgment, Services, Stimulated, TraceDisparityError, TransportObservationError, TypeId$3 as TypeId, check, holds, judge, of, stimulate };
+  export { CheckOptions, Contract, ContractDecodeError, Declared$1 as Declared, EmptyObservationError, IncompleteObservationError, JudgeFailure, Judgment, Report, Services, Stimulated, TransportObservationError, TypeId$3 as TypeId, check, holds, judge, of, stimulate, verdictCheck };
 }
 declare const TypeId$3: unique symbol;
 type TypeId$3 = typeof TypeId$3;
@@ -310,15 +302,38 @@ interface CheckOptions {
   readonly dumpName?: string | undefined;
 }
 type JudgeFailure<E> = E | ContractDecodeError | ObservationFailure;
-type CheckFailure<E> = JudgeFailure<E> | TraceDisparityError;
 type Services<R> = R | Observation | FileSystem.FileSystem;
 declare const judge: {
   <Input>(input: Input, options?: CheckOptions): <Output, E, R>(self: Contract<Input, Output, E, R>) => Effect.Effect<Judgment<Input, Output>, JudgeFailure<E>, Services<R>>;
   <Input, Output, E, R>(self: Contract<Input, Output, E, R>, input: Input, options?: CheckOptions): Effect.Effect<Judgment<Input, Output>, JudgeFailure<E>, Services<R>>;
 };
+/**
+ * What a judged contract answers: the verdict, and — when the relation broke — the report the judgement
+ * leaves behind. The report is empty only for a hold, so a check over it asserts the whole judgement.
+ */
+interface Report {
+  readonly verdict: 'Hold' | 'Break';
+  /**
+   * The relation that broke, the conjunct it was evaluating, the spans it inspected, the trace, and where the
+   * decoded graph was written.
+   */
+  readonly report: string;
+}
+/**
+ * The one check a judgement makes: it passes only when the relation held, and its message is the report, so a
+ * break names the conjunct that broke, the spans it inspected and where the evidence was written.
+ */
+declare const verdictCheck: {
+  <Input, Output, E, R>(expect: Expect, judgment: Judgment<Input, Output>): (self: Contract<Input, Output, E, R>) => Check;
+  <Input, Output, E, R>(self: Contract<Input, Output, E, R>, expect: Expect, judgment: Judgment<Input, Output>): Check;
+};
+/**
+ * The test edge over `judge`: the judgement and its one check. A break fails the check with the report;
+ * behaviour failures and infrastructure refusals stay on the error channel.
+ */
 declare const check: {
-  <Input>(input: Input, options?: CheckOptions): <Output, E, R>(self: Contract<Input, Output, E, R>) => Effect.Effect<Judgment<Input, Output>, CheckFailure<E>, Services<R>>;
-  <Input, Output, E, R>(self: Contract<Input, Output, E, R>, input: Input, options?: CheckOptions): Effect.Effect<Judgment<Input, Output>, CheckFailure<E>, Services<R>>;
+  <Input>(expect: Expect, input: Input, options?: CheckOptions): <Output, E, R>(self: Contract<Input, Output, E, R>) => Effect.Effect<void, JudgeFailure<E>, Asserted | Services<R>>;
+  <Input, Output, E, R>(self: Contract<Input, Output, E, R>, expect: Expect, input: Input, options?: CheckOptions): Effect.Effect<void, JudgeFailure<E>, Asserted | Services<R>>;
 };
 declare namespace RemoteObservation_d_exports {
   export { Options, TraceSource, layer$1 as layer };
@@ -371,17 +386,23 @@ declare namespace observation_window_handle_d_exports {
 }
 declare const TypeId$2: unique symbol;
 type TypeId$2 = typeof TypeId$2;
+/**
+ * The finished-span storage a window reads back through.
+ */
+interface SpanRecordStore {
+  readonly getFinishedSpans: () => ReadonlyArray<ReadableSpan>;
+}
 declare const ObservationWindow: Handle.Definition<typeof TypeId$2, {
   readonly serviceName: string;
 }, {
-  readonly exporter: InMemorySpanExporter;
+  readonly store: SpanRecordStore;
   readonly provider: BasicTracerProvider;
 }, never>;
 type ObservationWindow = Handle.Of<typeof ObservationWindow>;
 declare const isObservationWindow: (u: unknown) => u is Handle.Handle<typeof TypeId$2, {
   readonly serviceName: string;
 }, {
-  readonly exporter: InMemorySpanExporter;
+  readonly store: SpanRecordStore;
   readonly provider: BasicTracerProvider;
 }, never>;
 declare const make$2: (spec: ObservationWindowSpec) => ObservationWindow;
@@ -406,7 +427,7 @@ type ObservationWindowBlueprint = Blueprint.Of<typeof ObservationWindows>;
 declare const make$1: (serviceName: string) => ObservationWindowBlueprint;
 //#endregion
 //#region src/HarnessFailure.schema.d.ts
-declare const HarnessFailure: Schema.Union<readonly [typeof ContractDecodeError, typeof EmptyObservationError, typeof IncompleteObservationError, typeof TransportObservationError, typeof TraceDisparityError]>;
+declare const HarnessFailure: Schema.Union<readonly [typeof ContractDecodeError, typeof EmptyObservationError, typeof IncompleteObservationError, typeof TransportObservationError]>;
 type HarnessFailure = typeof HarnessFailure.Type;
 //#endregion
 //#region src/StimulusFailure.schema.d.ts
@@ -416,11 +437,17 @@ declare const StimulusFailure_base: Schema.Class<StimulusFailure, Schema.TaggedS
 }>, import("effect/Cause").YieldableError>;
 declare class StimulusFailure extends StimulusFailure_base {}
 declare namespace Suite_d_exports {
-  export { ArbitraryInput, CaseFailure, CaseRegistrar, CaseTools, Declared, Harness, Opened, Shared, StimulusFailure, TypeId, make, withLayer, withScenarioLayer };
+  export { ArbitraryInput, CaseFailure, CaseRegistrar, CaseTools, Declared, Harness, LiveStage, Opened, Shared, StimulusFailure, TypeId, live, make, withLayer, withScenarioLayer };
 }
 declare const TypeId: unique symbol;
 type TypeId = typeof TypeId;
 type CaseFailure = HarnessFailure | StimulusFailure;
+/**
+ * What every case's layers carry around the body: the observation harness and
+ * the file system failure dumps are written through. Trace ids draw through
+ * the `Random` reference, which the runner salts per case with
+ * `Random.withSeed`, so no layer has to provide it.
+ */
 type Harness = Observation | FileSystem.FileSystem;
 type ArbitraryInput<Input> = Schema.Schema<Input> | Arbitrary.Arbitrary<Input>;
 interface CaseRegistrar<Provided> {
@@ -430,18 +457,26 @@ interface CaseRegistrar<Provided> {
 interface CaseTools<Provided> {
   readonly Case: CaseRegistrar<Provided>;
 }
-interface Opened<Provided> {
+/**
+ * Every stage that can still reach `body` also declares whether its cases stay
+ * on the live clock, and a live declaration carries the reason it stayed there
+ * (KTD11). Without one, the stage's cases run on the kernel.
+ */
+interface LiveStage<Self> {
+  readonly live: (reason: string) => Self;
+}
+interface Opened<Provided> extends LiveStage<Opened<Provided>> {
   readonly body: (use: (tools: CaseTools<Provided>) => void) => void;
 }
-interface Declared extends Pipeable {
+interface Declared extends Pipeable, LiveStage<Declared> {
   readonly [TypeId]: typeof TypeId;
   readonly withLayer: <SharedProvided>(shared: Layer.Layer<SharedProvided | Harness>) => Shared<SharedProvided>;
   readonly withScenarioLayer: <Provided>(scenario: Layer.Layer<Provided | Harness>) => Opened<Provided | Harness>;
 }
-interface Shared<SharedProvided> extends Pipeable {
+interface Shared<SharedProvided> extends Pipeable, LiveStage<Shared<SharedProvided>> {
   readonly [TypeId]: typeof TypeId;
-  readonly withScenarioLayer: <Provided>(scenario: Layer.Layer<Provided | Harness, never, SharedProvided>) => Opened<Provided | SharedProvided>;
-  readonly body: (use: (tools: CaseTools<SharedProvided>) => void) => void;
+  readonly withScenarioLayer: <Provided>(scenario: Layer.Layer<Provided | Harness, never, SharedProvided>) => Opened<Provided | SharedProvided | Harness>;
+  readonly body: (use: (tools: CaseTools<SharedProvided | Harness>) => void) => void;
 }
 declare const withLayer: {
   <SharedProvided>(shared: Layer.Layer<SharedProvided | Harness>): (self: Declared) => Shared<SharedProvided>;
@@ -451,6 +486,10 @@ declare const withScenarioLayer: {
   <Provided>(scenario: Layer.Layer<Provided | Harness>): (self: Declared) => Opened<Provided | Harness>;
   <Provided>(self: Declared, scenario: Layer.Layer<Provided | Harness>): Opened<Provided | Harness>;
 };
+declare const live: {
+  (reason: string): <Self>(self: LiveStage<Self>) => Self;
+  <Self>(self: LiveStage<Self>, reason: string): Self;
+};
 declare const make: (bindings: Suite.Bindings) => (name: string) => Declared;
 //#endregion
 export { Contract_d_exports as Contract, Graph_d_exports as Graph, Observation_service_d_exports as Observation, observation_window_blueprint_d_exports as ObservationWindow, Rel_d_exports as Rel, RemoteObservation_d_exports as RemoteObservation, Stimulus_d_exports as Stimulus, Suite_d_exports as Suite, tempo_trace_store_d_exports as TempoTraceStore };

package/dist/index.mjs

@@ -1,6 +1,5 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
-import { recordAssertion } from "@effect/vitest";
-import { Array as Array$1, Cause, Clock, Context, Duration, Effect, Encoding, Equal, FileSystem, Layer, Match, Option, Predicate, Ref, Result, Schema, SchemaGetter, SchemaTransformation } from "effect";
+import { Array as Array$1, Cause, Clock, Context, Duration, Effect, Encoding, Equal, FileSystem, Layer, Match, Option, Predicate, Random, Ref, Result, Schema, SchemaGetter, SchemaTransformation } from "effect";
 import { dual } from "effect/Function";
 import { Prototype } from "effect/Pipeable";
 import "effect/PlatformError";
@@ -12,7 +11,7 @@ import * as OtelTracer from "@effect/opentelemetry/OtelTracer";
 import * as OtelResource from "@effect/opentelemetry/Resource";
 import { Blueprint, Handle } from "@systemfsoftware/effect-cell-types";
 import { SpanStatusCode } from "@opentelemetry/api";
-import { AlwaysOnSampler, BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { AlwaysOnSampler, BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
 import { Suite, TaskRef } from "@systemfsoftware/effect-spec-runtime";
 //#region src/ContractDecodeError.schema.ts
 var ContractDecodeError = class extends Schema.TaggedError()("ContractDecodeError", {
@@ -48,11 +47,11 @@ const Verdict = Schema.Union([Hold, Break]);
 //#endregion
 //#region src/FailureDump.ts
 const DEFAULT_DIRECTORY = "artifacts/traces";
-const isBreak$2 = Schema.is(Break);
+const isBreak$1 = Schema.is(Break);
 /**
 * The rendered evidence a break carries; a held verdict leaves nothing to write.
 */
-const report = (verdict) => Option.map(Option.liftPredicate(verdict, isBreak$2), renderBreach);
+const report = (verdict) => Option.map(Option.liftPredicate(verdict, isBreak$1), renderBreach);
 const renderValue = (value) => JSON.stringify(value);
 const renderEntries = (entries) => [...entries].map(([key, value]) => `${key}=${renderValue(value)}`).join(" ");
 const indentOf = (depth) => "  ".repeat(depth);
@@ -249,27 +248,19 @@ var Observation_service_exports = /* @__PURE__ */ __exportAll({
 });
 var Observation = class extends Context.Service()("@systemfsoftware/trace-spec/Observation") {};
 //#endregion
-//#region src/TraceDisparityError.schema.ts
-var TraceDisparityError = class extends Schema.TaggedError()("TraceDisparityError", {
-	relationId: Schema.String,
-	traceId: Schema.String,
-	breaks: Schema.Array(Break),
-	dumpPath: Schema.NullOr(Schema.String)
-}) {};
-//#endregion
 //#region src/Contract.ts
 var Contract_exports = /* @__PURE__ */ __exportAll({
 	ContractDecodeError: () => ContractDecodeError,
 	EmptyObservationError: () => EmptyObservationError,
 	IncompleteObservationError: () => IncompleteObservationError,
-	TraceDisparityError: () => TraceDisparityError,
 	TransportObservationError: () => TransportObservationError,
 	TypeId: () => TypeId$3,
 	check: () => check,
 	holds: () => holds,
 	judge: () => judge,
 	of: () => of,
-	stimulate: () => stimulate
+	stimulate: () => stimulate,
+	verdictCheck: () => verdictCheck
 });
 const TypeId$3 = Symbol.for("@systemfsoftware/trace-spec/Contract");
 const stimulatedOf = (taxonomy, stimulus) => ({
@@ -322,13 +313,34 @@ const judgeDual = (self, input, options) => Effect.gen(function* () {
 	};
 });
 const judge = dual((args) => isContract(args[0]), judgeDual);
-const refuseBreak = (relationId, judgment) => Match.value(judgment.verdict).pipe(Match.tag("Break", (breach) => Effect.fail(TraceDisparityError.make({
-	relationId,
-	traceId: judgment.run.traceId,
-	breaks: [breach],
-	dumpPath: judgment.dumpPath
-}))), Match.tag("Hold", () => Effect.succeed(judgment)), Match.exhaustive);
-const checkDual = (self, input, options) => Effect.flatMap(judgeDual(self, input, options), (judgment) => Effect.andThen(Effect.sync(recordAssertion), refuseBreak(self.relation.id, judgment)));
+/** What a hold answers: nothing to report. */
+const held = {
+	verdict: "Hold",
+	report: ""
+};
+const reportOf = (relationId, judgment) => Match.value(judgment.verdict).pipe(Match.tag("Hold", () => held), Match.tag("Break", (breach) => ({
+	verdict: "Break",
+	report: [
+		`trace contract broke: ${relationId}`,
+		Option.getOrElse(report(breach), () => ""),
+		`trace ${judgment.run.traceId}`,
+		`dump ${judgment.dumpPath ?? "(not written)"}`
+	].join("\n")
+})), Match.exhaustive);
+const verdictCheckImpl = (self, expect, judgment) => {
+	const report = reportOf(self.relation.id, judgment);
+	return expect(report, report.report).toEqual(held);
+};
+/**
+* The one check a judgement makes: it passes only when the relation held, and its message is the report, so a
+* break names the conjunct that broke, the spans it inspected and where the evidence was written.
+*/
+const verdictCheck = dual(3, verdictCheckImpl);
+const checkDual = (self, expect, input, options) => Effect.flatMap(judgeDual(self, input, options), (judgment) => verdictCheckImpl(self, expect, judgment));
+/**
+* The test edge over `judge`: the judgement and its one check. A break fails the check with the report;
+* behaviour failures and infrastructure refusals stay on the error channel.
+*/
 const check = dual((args) => isContract(args[0]), checkDual);
 //#endregion
 //#region src/drivers/tempo-trace.schema.ts
@@ -547,15 +559,40 @@ Schema.encodeEffect(HexId);
 //#region src/observation-window.handle.ts
 const TypeId$2 = Symbol.for("~systemfsoftware/trace-spec/ObservationWindow");
 const ObservationWindow = Handle.make()(TypeId$2);
+/**
+* Records every finished span the moment it ends, and answers `shutdown`
+* inline. The OpenTelemetry `InMemorySpanExporter` defers its result callback
+* to a `setTimeout`, a real timer the kernel must fail as an escaped schedule;
+* a window records nothing that waits, so it records synchronously.
+*/
+const spanRecorder = () => {
+	const finishedSpans = [];
+	let stopped = false;
+	return {
+		processor: {
+			onStart: () => void 0,
+			onEnd: (span) => {
+				if (!stopped) finishedSpans.push(span);
+			},
+			shutdown: () => {
+				stopped = true;
+				finishedSpans.length = 0;
+				return Promise.resolve();
+			},
+			forceFlush: () => Promise.resolve()
+		},
+		store: { getFinishedSpans: () => finishedSpans }
+	};
+};
 const isObservationWindow = ObservationWindow.is;
 const make$3 = (spec) => {
-	const exporter = new InMemorySpanExporter();
+	const { processor, store } = spanRecorder();
 	const provider = new BasicTracerProvider({
 		sampler: new AlwaysOnSampler(),
-		spanProcessors: [new SimpleSpanProcessor(exporter)]
+		spanProcessors: [processor]
 	});
 	return ObservationWindow.make({ serviceName: spec.serviceName }, {
-		exporter,
+		store,
 		provider
 	});
 };
@@ -614,7 +651,7 @@ const emptyObservation = (traceId) => new EmptyObservationError({
 	traceId,
 	detail: "the observation window closed with no span carrying the stimulated trace id"
 });
-const recordsOf = (self, traceId) => ObservationWindow.slot(self).exporter.getFinishedSpans().filter((span) => span.spanContext().traceId === traceId).map(spanRecordOf);
+const recordsOf = (self, traceId) => ObservationWindow.slot(self).store.getFinishedSpans().filter((span) => span.spanContext().traceId === traceId).map(spanRecordOf);
 const collect = dual(2, (self, traceId) => Effect.suspend(() => {
 	const records = recordsOf(self, traceId);
 	return records.length > 0 ? Effect.succeed(records) : Effect.fail(emptyObservation(traceId));
@@ -676,7 +713,7 @@ const relation = (parts) => Object.assign((graph) => parts.evaluate(graph), {
 const matchedNodes = (graph, spec) => byId(graph, spec);
 const inspectedOf = (nodes) => nodes.map((node) => node.spanId);
 const matchedAll = (items, predicate) => items.length > 0 && items.every(predicate);
-const isBreak$1 = (verdict) => Schema.is(Break)(verdict);
+const isBreak = (verdict) => Schema.is(Break)(verdict);
 const isHold$1 = (verdict) => Schema.is(Hold)(verdict);
 const verdictOf$1 = (options) => options.holds ? Hold.make({
 	conjunct: options.id,
@@ -686,7 +723,7 @@ const verdictOf$1 = (options) => options.holds ? Hold.make({
 	inspected: options.inspected,
 	detail: options.detail
 });
-const declared = (declaration) => relation({
+const declared$1 = (declaration) => relation({
 	id: declaration.id,
 	soft: false,
 	softenable: declaration.softenable,
@@ -702,21 +739,21 @@ const declared = (declaration) => relation({
 });
 const holdsCountOf = (spec, expected) => (graph) => expected(matchedNodes(graph, spec).length);
 const holdsEveryOf = (spec, predicate) => (graph) => matchedAll(matchedNodes(graph, spec), predicate);
-const exists = (spec) => declared({
+const exists = (spec) => declared$1({
 	id: `exists(${spec.id})`,
 	spans: [spec],
 	softenable: false,
 	detail: `no ${spec.id} span was emitted`,
 	holds: holdsCountOf(spec, (count) => count > 0)
 });
-const absent = (spec) => declared({
+const absent = (spec) => declared$1({
 	id: `absent(${spec.id})`,
 	spans: [spec],
 	softenable: false,
 	detail: `a ${spec.id} span was emitted`,
 	holds: holdsCountOf(spec, (count) => count === 0)
 });
-const unique = (spec) => declared({
+const unique = (spec) => declared$1({
 	id: `unique(${spec.id})`,
 	spans: [spec],
 	softenable: true,
@@ -731,7 +768,7 @@ const reachedUnder = (graph, parent, childSpan, reach) => {
 	const reached = reach(graph, matchedNodes(graph, parent));
 	return matchedNodes(graph, childSpan).some((node) => reached.has(node.spanId));
 };
-const childImpl = (parent, childSpan) => declared({
+const childImpl = (parent, childSpan) => declared$1({
 	id: `child(${parent.id},${childSpan.id})`,
 	spans: [parent, childSpan],
 	softenable: true,
@@ -739,7 +776,7 @@ const childImpl = (parent, childSpan) => declared({
 	holds: (graph) => reachedUnder(graph, parent, childSpan, childIdsOf)
 });
 const child = dual(2, childImpl);
-const descendantImpl = (parent, childSpan) => declared({
+const descendantImpl = (parent, childSpan) => declared$1({
 	id: `descendant(${parent.id},${childSpan.id})`,
 	spans: [parent, childSpan],
 	softenable: true,
@@ -747,7 +784,7 @@ const descendantImpl = (parent, childSpan) => declared({
 	holds: (graph) => reachedUnder(graph, parent, childSpan, descendantIdsOf)
 });
 const descendant = dual(2, descendantImpl);
-const orderImpl = (before, after) => declared({
+const orderImpl = (before, after) => declared$1({
 	id: `order(${before.id},${after.id})`,
 	spans: [before, after],
 	softenable: true,
@@ -755,7 +792,7 @@ const orderImpl = (before, after) => declared({
 	holds: (graph) => matchedAll(matchedNodes(graph, after), (node) => startsAfterSome(matchedNodes(graph, before), node))
 });
 const order = dual(2, orderImpl);
-const statusImpl = (spec, expected) => declared({
+const statusImpl = (spec, expected) => declared$1({
 	id: `status(${spec.id},${expected})`,
 	spans: [spec],
 	softenable: true,
@@ -763,7 +800,7 @@ const statusImpl = (spec, expected) => declared({
 	holds: holdsEveryOf(spec, (node) => node.status === expected)
 });
 const status = dual(2, statusImpl);
-const errorTypeImpl = (spec, expected) => declared({
+const errorTypeImpl = (spec, expected) => declared$1({
 	id: `errorType(${spec.id},${expected})`,
 	spans: [spec],
 	softenable: true,
@@ -772,7 +809,7 @@ const errorTypeImpl = (spec, expected) => declared({
 });
 const errorType = dual(2, errorTypeImpl);
 const partialMatches = (attributes, partial) => Object.entries(partial).filter(([, value]) => value !== void 0).every(([key, value]) => Equal.equals(attributes[key], value));
-const attrsImpl = (spec, partial) => declared({
+const attrsImpl = (spec, partial) => declared$1({
 	id: `attrs(${spec.id})`,
 	spans: [spec],
 	softenable: true,
@@ -780,7 +817,7 @@ const attrsImpl = (spec, partial) => declared({
 	holds: holdsEveryOf(spec, (node) => partialMatches(node.attrs, partial))
 });
 const attrs = dual(2, attrsImpl);
-const durationLessThanImpl = (spec, millis) => declared({
+const durationLessThanImpl = (spec, millis) => declared$1({
 	id: `durationLessThan(${spec.id},${millis})`,
 	spans: [spec],
 	softenable: true,
@@ -789,7 +826,7 @@ const durationLessThanImpl = (spec, millis) => declared({
 });
 const durationLessThan = dual(2, durationLessThanImpl);
 const carriesEvent = (name) => (node) => node.events.some((event) => event.name === name);
-const eventImpl = (spec, name) => declared({
+const eventImpl = (spec, name) => declared$1({
 	id: `event(${spec.id},${name})`,
 	spans: [spec],
 	softenable: true,
@@ -849,8 +886,8 @@ const collectSoft = (id, breaks) => {
 		detail: breaks.map((breach) => breach.conjunct).join(", ")
 	});
 };
-const firstHardBreak = (relations, graph) => relations.filter((relation) => !relation.soft).map((relation) => relation(graph)).find(isBreak$1) ?? null;
-const softBreaks = (relations, graph) => relations.filter((relation) => relation.soft).map((relation) => relation(graph)).filter(isBreak$1);
+const firstHardBreak = (relations, graph) => relations.filter((relation) => !relation.soft).map((relation) => relation(graph)).find(isBreak) ?? null;
+const softBreaks = (relations, graph) => relations.filter((relation) => relation.soft).map((relation) => relation(graph)).filter(isBreak);
 const combined = (options) => relation({
 	id: options.id,
 	soft: options.soft,
@@ -1038,10 +1075,11 @@ var Stimulus_exports = /* @__PURE__ */ __exportAll({
 	traceContext: () => traceContext
 });
 const byteHex = (byte) => byte.toString(16).padStart(2, "0");
-const randomHex = (byteLength) => Array.from(crypto.getRandomValues(new Uint8Array(byteLength)), byteHex).join("");
-const traceContext = Effect.sync(() => {
-	const traceId = randomHex(16);
-	const spanId = randomHex(8);
+const randomByte = Random.nextIntBetween(0, 255);
+const randomHex = (byteLength) => Effect.map(Effect.all(Array.from({ length: byteLength }, () => randomByte)), (bytes) => bytes.map(byteHex).join(""));
+const traceContext = Effect.gen(function* () {
+	const traceId = yield* randomHex(16);
+	const spanId = yield* randomHex(8);
 	return {
 		traceId,
 		spanId,
@@ -1075,25 +1113,33 @@ const HarnessFailure = Schema.Union([
 	ContractDecodeError,
 	EmptyObservationError,
 	IncompleteObservationError,
-	TransportObservationError,
-	TraceDisparityError
+	TransportObservationError
 ]);
 //#endregion
-//#region src/Prop.ts
-const isHold = Schema.is(Hold);
-const isBreak = Schema.is(Break);
-const annotate = (message) => Effect.gen(function* () {
-	const task = yield* TaskRef.RawVitestTaskRef;
-	return yield* Option.match(Option.fromNullishOr(task?.annotate), {
-		onNone: () => Effect.void,
-		onSome: (record) => Effect.promise(() => Promise.resolve(record(message, "info")))
-	});
+//#region src/TaskAnnounce.ts
+const forget = (annotation) => {
+	Promise.resolve(annotation);
+};
+const dispatchAnnotate = (annotate, message, type) => Option.match(Option.fromNullishOr(annotate), {
+	onNone: () => Effect.void,
+	onSome: (record) => Effect.sync(() => forget(record(message, type)))
+});
+const announcement = (taskContext, message, type) => Option.match(Option.fromNullishOr(taskContext), {
+	onNone: () => Effect.void,
+	onSome: (context) => dispatchAnnotate(context.annotate, message, type)
+});
+const record = (message, type) => Effect.gen(function* () {
+	const taskContext = yield* TaskRef.RawVitestTaskRef;
+	return yield* announcement(taskContext, message, type);
 });
-const dumpMessageOf = (verdict, dumpPath) => Option.map(Option.flatMap(Option.liftPredicate(verdict, isBreak), () => Option.fromNullishOr(dumpPath)), (path) => `trace contract failed; observed graph dumped to ${path}`);
-const announce = (verdict, dumpPath) => Option.match(dumpMessageOf(verdict, dumpPath), {
+const dumpMessageOf = (judged) => Option.map(Option.flatMap(Option.liftPredicate(judged.verdict, Schema.is(Break)), () => Option.fromNullishOr(judged.dumpPath)), (dumpPath) => `trace contract failed; observed graph dumped to ${dumpPath}`);
+const announceDump = (judged) => Option.match(dumpMessageOf(judged), {
 	onNone: () => Effect.void,
-	onSome: (message) => annotate(message)
+	onSome: (message) => record(message, "info")
 });
+//#endregion
+//#region src/Prop.ts
+const isHold = Schema.is(Hold);
 /**
 * The contract with its stimulus replaced by the function the property was handed: the impostor gate
 * swaps in a constant fake, so the judgement must reach the stimulus through the argument, never the
@@ -1108,11 +1154,12 @@ const judgedOver = (contract, subject) => ({
 * frozen run satisfies every relation about that run, so the input pin is what refutes it.
 */
 const consumedInput = (judgment, input) => judgment.run.input === input;
-const predicateImpl = (title, contract, scenario) => {
-	const checked = (subject, input) => judge(judgedOver(contract, subject), input, { dumpName: title }).pipe(Effect.tap((judgment) => announce(judgment.verdict, judgment.dumpPath)), Effect.map((judgment) => isHold(judgment.verdict) && consumedInput(judgment, input)), Effect.provide(Layer.fresh(scenario)));
+const predicateImpl = (title, contract, scenario, shared) => {
+	const provided = scenario.pipe(Layer.provideMerge(shared));
+	const checked = (subject, input) => judge(judgedOver(contract, subject), input, { dumpName: title }).pipe(Effect.tap(announceDump), Effect.map((judgment) => isHold(judgment.verdict) && consumedInput(judgment, input)), Effect.provide(Layer.fresh(provided)));
 	return (subject, input) => checked(subject, input);
 };
-const predicate = dual(3, predicateImpl);
+const predicate = dual(4, predicateImpl);
 //#endregion
 //#region src/StimulusFailure.schema.ts
 var StimulusFailure = class extends Schema.TaggedError()("StimulusFailure", {
@@ -1120,80 +1167,86 @@ var StimulusFailure = class extends Schema.TaggedError()("StimulusFailure", {
 	detail: Schema.String
 }) {};
 //#endregion
-//#region src/TaskAnnounce.ts
-const dispatchAnnotate = (annotate, message, type) => Option.match(Option.fromNullishOr(annotate), {
-	onNone: () => Effect.void,
-	onSome: (record) => Effect.promise(() => Promise.resolve(record(message, type)))
-});
-const announcement = (taskContext, message, type) => Option.match(Option.fromNullishOr(taskContext), {
-	onNone: () => Effect.void,
-	onSome: (context) => dispatchAnnotate(context.annotate, message, type)
-});
-const record = (message, type) => Effect.gen(function* () {
-	const taskContext = yield* TaskRef.RawVitestTaskRef;
-	return yield* announcement(taskContext, message, type);
-});
-const announceDump = (error) => Option.match(Option.fromNullishOr(error.dumpPath), {
-	onNone: () => Effect.void,
-	onSome: (dumpPath) => record(`trace contract failed; observed graph dumped to ${dumpPath}`, "info")
-});
-//#endregion
 //#region src/Suite.ts
 var Suite_exports = /* @__PURE__ */ __exportAll({
 	StimulusFailure: () => StimulusFailure,
 	TypeId: () => TypeId,
+	live: () => live,
 	make: () => make,
 	withLayer: () => withLayer,
 	withScenarioLayer: () => withScenarioLayer
 });
 const TypeId = Symbol.for("@systemfsoftware/trace-spec/Suite");
 const isHarnessFailure = Schema.is(HarnessFailure);
-const caseFailureOf = (stimulus) => (failure) => isHarnessFailure(failure) ? failure : new StimulusFailure({
+const SALT_BYTES = 8;
+/**
+* Per-case salt for globally unique W3C trace ids: drawn here, at case
+* registration and outside any kernel run, so a seeded Random inside the run
+* never replays another case's ids and the raw crypto source never enters an
+* explored body.
+*/
+const saltOf = () => {
+	const bytes = crypto.getRandomValues(new Uint8Array(SALT_BYTES));
+	return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+};
+const caseFailureOf = (stimulus, salt) => (failure) => isHarnessFailure(failure) ? failure : new StimulusFailure({
 	stimulus,
-	detail: Cause.pretty(Cause.fail(failure))
+	detail: `${Cause.pretty(Cause.fail(failure))}\nrandom salt: ${salt}`
 });
-const rethrowAfter = (annotation, error) => Effect.andThen(annotation, () => Effect.fail(error));
-const annotateDisparity = (error) => rethrowAfter(announceDump(error), error);
-const caseBody = (contract, input) => check(contract, input).pipe(Effect.catchIf(Schema.is(TraceDisparityError), annotateDisparity), Effect.asVoid, Effect.mapError(caseFailureOf(contract.stimulus.name)));
-const caseTools = (register, propIt, scenario) => {
-	const Case = (name, contract, input) => register(name, caseBody(contract, input), "run");
+const caseBody = (expect, contract, input, salt) => judge(contract, input).pipe(Effect.tap(announceDump), Effect.flatMap((judgment) => verdictCheck(contract, expect, judgment)), Effect.mapError(caseFailureOf(contract.stimulus.name, salt)));
+const caseTools = (register, propIt, scenario, shared) => {
+	const Case = (name, contract, input) => {
+		const salt = saltOf();
+		register(name, (expect) => caseBody(expect, contract, input, salt).pipe(Random.withSeed(salt)), "run");
+	};
 	Case.prop = (name, contract, arbitrary) => {
+		const salt = saltOf();
 		propIt.effect.prop(name, {
 			of: [arbitrary],
 			subject: contract.stimulus
-		}, (subject, values) => predicate(name, contract, scenario)(subject, values[0]));
+		}, (subject, values) => predicate(name, contract, scenario, shared)(subject, values[0]).pipe(Random.withSeed(salt)));
 	};
 	return { Case };
 };
-const config = (name) => ({
+const config = (name, live) => live === void 0 ? {
+	name,
+	describe: "describe",
+	options: void 0
+} : {
 	name,
 	describe: "describe",
 	options: void 0,
-	liveClock: true
-});
-const openScenario = (bindings, name, scenario) => ({ body: (use) => Suite.openCase(bindings, config(name), scenario, (register, propIt) => use(caseTools(register, propIt, scenario))) });
-const openSharedScenario = (bindings, name, shared, scenario) => ({ body: (use) => Suite.openSharedCase(bindings, config(name), {
-	layer: shared,
-	excludeTestServices: false
-}, scenario, (register, propIt) => use(caseTools(register, propIt, scenario.pipe(Layer.provideMerge(shared))))) });
-const openShared = (bindings, name, shared) => ({
+	live
+};
+const openedScenario = (bindings, name, live, scenario) => ({
+	live: (reason) => openedScenario(bindings, name, { reason }, scenario),
+	body: (use) => Suite.openCase(config(name, live), scenario, (register, propIt) => use(caseTools(register, propIt, scenario, Layer.empty)))(bindings)
+});
+const openedSharedScenario = (bindings, name, live, shared, scenario) => ({
+	live: (reason) => openedSharedScenario(bindings, name, { reason }, shared, scenario),
+	body: (use) => Suite.openSharedCase(config(name, live), { layer: shared }, scenario, (register, propIt) => use(caseTools(register, propIt, scenario.pipe(Layer.provideMerge(shared)), shared)))(bindings)
+});
+const registerSharedCases = (bindings, name, live, shared, use) => Suite.openShared(config(name, live), { layer: shared }, (register, propIt) => use(caseTools(register, propIt, shared, shared)))(bindings);
+const sharedOver = (bindings, name, live, shared) => ({
+	[TypeId]: TypeId,
+	live: (reason) => sharedOver(bindings, name, { reason }, shared),
+	withScenarioLayer: (scenario) => openedSharedScenario(bindings, name, live, shared, scenario),
+	body: (use) => registerSharedCases(bindings, name, live, shared, use),
+	...Prototype
+});
+const declared = (bindings, name, live) => ({
 	[TypeId]: TypeId,
-	body: (use) => Suite.openShared(bindings, config(name), {
-		layer: shared,
-		excludeTestServices: false
-	}, (register, propIt) => use(caseTools(register, propIt, shared))),
-	withScenarioLayer: (scenario) => openSharedScenario(bindings, name, shared, scenario),
+	live: (reason) => declared(bindings, name, { reason }),
+	withLayer: (shared) => sharedOver(bindings, name, live, shared),
+	withScenarioLayer: (scenario) => openedScenario(bindings, name, live, scenario),
 	...Prototype
 });
 const withLayerDual = (self, shared) => self.withLayer(shared);
 const withLayer = dual(2, withLayerDual);
 const withScenarioLayerDual = (self, scenario) => self.withScenarioLayer(scenario);
 const withScenarioLayer = dual(2, withScenarioLayerDual);
-const make = (bindings) => (name) => ({
-	[TypeId]: TypeId,
-	withLayer: (shared) => openShared(bindings, name, shared),
-	withScenarioLayer: (scenario) => openScenario(bindings, name, scenario),
-	...Prototype
-});
+const liveDual = (self, reason) => self.live(reason);
+const live = dual(2, liveDual);
+const make = (bindings) => (name) => declared(bindings, name, void 0);
 //#endregion
 export { Contract_exports as Contract, Graph_exports as Graph, Observation_service_exports as Observation, observation_window_blueprint_exports as ObservationWindow, Rel_exports as Rel, RemoteObservation_exports as RemoteObservation, Stimulus_exports as Stimulus, Suite_exports as Suite, tempo_trace_store_exports as TempoTraceStore };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@systemfsoftware/trace-spec",
   "license": "Apache-2.0",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "author": "Ryan Lee <drdgvhbh@gmail.com>",
   "repository": {
     "type": "git",
@@ -39,17 +39,18 @@
     "@opentelemetry/sdk-trace-base": "^2",
     "@opentelemetry/semantic-conventions": "^1.33",
     "@systemfsoftware/effect-cell-types": "^10.2.0",
-    "@systemfsoftware/effect-spec-runtime": "^0.2.0",
+    "@systemfsoftware/effect-spec-runtime": "^0.3.0",
     "@systemfsoftware/trace-taxonomy": "^0.0.1"
   },
   "devDependencies": {
     "@effect/platform-node": "4.0.0-rc.117",
-    "@effect/vitest": "npm:@systemfsoftware/vitest@0.0.0",
     "@systemfsoftware/arethetypeswrong-cli": "^4.2.0",
-    "@systemfsoftware/effect-gherkin-spec": "^4.4.0",
-    "@systemfsoftware/oxlint-config-recommended": "^3.0.0",
+    "@systemfsoftware/conformance-spec": "^0.1.0",
+    "@systemfsoftware/effect-gherkin-spec": "^5.0.0",
+    "@systemfsoftware/oxlint-config-recommended": "^3.1.0",
     "@systemfsoftware/tsconfig": "^2.0.1",
     "@systemfsoftware/tsdown-config": "^0.1.0",
+    "@systemfsoftware/vitest": "^0.1.0",
     "@systemfsoftware/vitest-config": "^0.1.0",
     "@types/node": "^26",
     "effect": "4.0.0-rc.117",
@@ -60,7 +61,7 @@
     "vitest": "^5"
   },
   "peerDependencies": {
-    "@effect/vitest": "npm:@systemfsoftware/vitest@*",
+    "@systemfsoftware/vitest": "^0.1.0",
     "effect": "4.0.0-rc.117",
     "vitest": "^5"
   },