@systemfsoftware/trace-spec 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @systemfsoftware/trace-spec
 
+## 0.5.0
+
+### Minor Changes
+
+- `Rel.Hold`, `Rel.Break` and `ObservationWindow.ObservationWindowSpec` are schema structs instead of classes, with unchanged encoded shapes: build them with `.make(...)` instead of `new`. The `VerdictTypeId` type is removed. `IncompleteObservationError.spanCount` must be a non-negative integer, and span `startMillis` and `durationMillis` must be finite and non-negative.
+
+- `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.
+
+- The lawful test runner is now a peer dependency under its own name, `@systemfsoftware/vitest`, instead of the `@effect/vitest` alias that pointed at it. Install `@systemfsoftware/vitest` and import `it`, `layer`, `expect`, and the rest from `@systemfsoftware/vitest`. `@systemfsoftware/effect-gherkin-spec` re-exports `it` and `layer` from `@systemfsoftware/vitest`.
+
+- A broken contract now fails the check with `BreakFailure`, whose message is the break report, pointing at the line that called the check.
+
+- Cases now run on the simulation kernel — the zero-preemption schedule, then the profile's seeded schedules — instead of always on the live clock, and each case draws its own crypto-random salt, so two cases never share a trace id.
+
+  - `Suite.make({ it, layer })` → `Suite.make({ it })`.
+  - A case that must stay live declares a reason on any stage: `.live('...')`, or the new `Suite.live` combinator (`self.pipe(Suite.live(reason))`).
+  - `withLayer(shared)` rebuilds the shared layer freshly for every case rather than once per suite.
+  - `Stimulus.traceContext` draws its ids through Effect's `Random`, so a seeded run replays the same trace ids.
+
+### Patch Changes
+
+- Update peer and runtime dependency on `effect` and companion packages to `4.0.0-rc.117`.
+
+- Updated dependencies:
+  - @systemfsoftware/trace-taxonomy@0.0.2
+  - @systemfsoftware/vitest@0.2.0
+
+## 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,10 +4,19 @@ 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/BreakFailure.schema.d.ts
+declare const BreakFailure_base: Schema.Class<BreakFailure, Schema.TaggedStruct<"BreakFailure", {
+  readonly report: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+declare class BreakFailure extends BreakFailure_base {
+  get message(): string;
+}
+//#endregion
 //#region src/ContractDecodeError.schema.d.ts
 declare const ContractDecodeError_base: Schema.Class<ContractDecodeError, Schema.TaggedStruct<"ContractDecodeError", {
   readonly declarationId: Schema.String;
@@ -16,22 +25,28 @@ declare const ContractDecodeError_base: Schema.Class<ContractDecodeError, Schema
   readonly attribute: Schema.String;
   readonly detail: Schema.String;
 }>, import("effect/Cause").YieldableError>;
-declare class ContractDecodeError extends ContractDecodeError_base {}
+declare class ContractDecodeError extends ContractDecodeError_base {
+  get message(): string;
+}
 //#endregion
 //#region src/EmptyObservationError.schema.d.ts
 declare const EmptyObservationError_base: Schema.Class<EmptyObservationError, Schema.TaggedStruct<"EmptyObservationError", {
   readonly traceId: Schema.String;
   readonly detail: Schema.String;
 }>, import("effect/Cause").YieldableError>;
-declare class EmptyObservationError extends EmptyObservationError_base {}
+declare class EmptyObservationError extends EmptyObservationError_base {
+  get message(): string;
+}
 //#endregion
 //#region src/IncompleteObservationError.schema.d.ts
 declare const IncompleteObservationError_base: Schema.Class<IncompleteObservationError, Schema.TaggedStruct<"IncompleteObservationError", {
   readonly traceId: Schema.String;
-  readonly spanCount: Schema.Finite;
+  readonly spanCount: Schema.Int;
   readonly detail: Schema.String;
 }>, import("effect/Cause").YieldableError>;
-declare class IncompleteObservationError extends IncompleteObservationError_base {}
+declare class IncompleteObservationError extends IncompleteObservationError_base {
+  get message(): string;
+}
 //#endregion
 //#region src/TraceGraph.schema.d.ts
 declare const Status: Schema.Literals<readonly ["ok", "unset", "error"]>;
@@ -144,7 +159,9 @@ declare const TransportObservationError_base: Schema.Class<TransportObservationE
   readonly source: Schema.String;
   readonly detail: Schema.String;
 }>, import("effect/Cause").YieldableError>;
-declare class TransportObservationError extends TransportObservationError_base {}
+declare class TransportObservationError extends TransportObservationError_base {
+  get message(): string;
+}
 declare namespace Observation_service_d_exports {
   export { Collector, EmptyObservationError, IncompleteObservationError, Observation, ObservationFailure, TransportObservationError };
 }
@@ -156,24 +173,25 @@ declare const Observation_base: Context.ServiceClass<Observation, "@systemfsoftw
 declare class Observation extends Observation_base {}
 //#endregion
 //#region src/Verdict.schema.d.ts
-declare const VerdictTypeId: unique symbol;
-type VerdictTypeId = typeof VerdictTypeId;
-declare const Hold_base: Schema.Class<Hold, Schema.TaggedStruct<"Hold", {
+declare const Hold: Schema.TaggedStruct<"Hold", {
   readonly conjunct: Schema.String;
   readonly inspected: Schema.$Array<Schema.String>;
-}>, {}>;
-declare class Hold extends Hold_base {
-  readonly [VerdictTypeId]: symbol;
-}
-declare const Break_base: Schema.Class<Break, Schema.TaggedStruct<"Break", {
+}>;
+type Hold = typeof Hold.Type;
+declare const Break: Schema.TaggedStruct<"Break", {
   readonly conjunct: Schema.String;
   readonly inspected: Schema.$Array<Schema.String>;
   readonly detail: Schema.String;
-}>, {}>;
-declare class Break extends Break_base {
-  readonly [VerdictTypeId]: symbol;
-}
-declare const Verdict: Schema.Union<readonly [typeof Hold, typeof Break]>;
+}>;
+type Break = typeof Break.Type;
+declare const Verdict: Schema.Union<readonly [Schema.TaggedStruct<"Hold", {
+  readonly conjunct: Schema.String;
+  readonly inspected: Schema.$Array<Schema.String>;
+}>, Schema.TaggedStruct<"Break", {
+  readonly conjunct: Schema.String;
+  readonly inspected: Schema.$Array<Schema.String>;
+  readonly detail: Schema.String;
+}>]>;
 type Verdict = typeof Verdict.Type;
 declare namespace Rel_d_exports {
   export { Break, Hold, Relation, Verdict, absent, all, any, attrs, child, descendant, durationLessThan, errorType, event, exists, forall, fromTaxonomy, not, order, soft, status, unique };
@@ -261,17 +279,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 { BreakFailure, 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 +319,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 };
@@ -362,26 +394,32 @@ declare const source: (options: {
 }) => TraceSource<HttpClient.HttpClient>;
 //#endregion
 //#region src/ObservationWindowSpec.schema.d.ts
-declare const ObservationWindowSpec_base: Schema.Class<ObservationWindowSpec, Schema.Struct<{
+declare const ObservationWindowSpec: Schema.Struct<{
   readonly serviceName: Schema.NonEmptyString;
-}>, {}>;
-declare class ObservationWindowSpec extends ObservationWindowSpec_base {}
+}>;
+type ObservationWindowSpec = typeof ObservationWindowSpec.Type;
 declare namespace observation_window_handle_d_exports {
   export { ObservationWindow, TypeId$2 as TypeId, collect, context, isObservationWindow, make$2 as make, shutdown };
 }
 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;
@@ -398,15 +436,21 @@ declare const TypeId$1: unique symbol;
 type TypeId$1 = typeof TypeId$1;
 declare const scoped: (spec: ObservationWindowSpec) => Effect.Effect<ObservationWindow, never, Scope.Scope>;
 declare const layer: (spec: ObservationWindowSpec) => Layer.Layer<Observation | OtelTracer.OtelTracer>;
-declare const ObservationWindows: Blueprint.Definition<typeof TypeId$1, ObservationWindowSpec, Blueprint.Derived<ObservationWindowSpec, {}, {
+declare const ObservationWindows: Blueprint.Definition<typeof TypeId$1, {
+  readonly serviceName: string;
+}, Blueprint.Derived<{
+  readonly serviceName: string;
+}, {}, {
   readonly scoped: typeof scoped;
   readonly layer: typeof layer;
-}>, ObservationWindowSpec>;
+}>, {
+  readonly serviceName: string;
+}>;
 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
@@ -414,13 +458,21 @@ declare const StimulusFailure_base: Schema.Class<StimulusFailure, Schema.TaggedS
   readonly stimulus: Schema.String;
   readonly detail: Schema.String;
 }>, import("effect/Cause").YieldableError>;
-declare class StimulusFailure extends StimulusFailure_base {}
+declare class StimulusFailure extends StimulusFailure_base {
+  get message(): string;
+}
 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 +482,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 +511,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,10 +1,12 @@
 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 { callFrameOutside, withRaisingFrame } from "@systemfsoftware/vitest/failure";
+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";
 import "@systemfsoftware/trace-taxonomy";
+import "effect/Array";
+import "effect/Result";
 import * as HttpClient from "effect/unstable/http/HttpClient";
 import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
 import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
@@ -12,8 +14,15 @@ 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/BreakFailure.schema.ts
+var BreakFailure = class extends Schema.TaggedError()("BreakFailure", { report: Schema.String }) {
+	get message() {
+		return this.report;
+	}
+};
+//#endregion
 //#region src/ContractDecodeError.schema.ts
 var ContractDecodeError = class extends Schema.TaggedError()("ContractDecodeError", {
 	declarationId: Schema.String,
@@ -21,38 +30,41 @@ var ContractDecodeError = class extends Schema.TaggedError()("ContractDecodeErro
 	spanId: Schema.String,
 	attribute: Schema.String,
 	detail: Schema.String
-}) {};
+}) {
+	get message() {
+		return `Span "${this.spanName}" (${this.spanId}) does not satisfy contract "${this.declarationId}": ${this.detail}`;
+	}
+};
 //#endregion
 //#region src/EmptyObservationError.schema.ts
 var EmptyObservationError = class extends Schema.TaggedError()("EmptyObservationError", {
 	traceId: Schema.String,
 	detail: Schema.String
-}) {};
+}) {
+	get message() {
+		return `Trace "${this.traceId}" recorded no spans: ${this.detail}`;
+	}
+};
 //#endregion
 //#region src/Verdict.schema.ts
-const VerdictTypeId = Symbol.for("@systemfsoftware/trace-spec/Verdict");
-var Hold = class extends Schema.TaggedClass()("Hold", {
+const Hold = Schema.TaggedStruct("Hold", {
 	conjunct: Schema.String,
 	inspected: Schema.Array(Schema.String)
-}) {
-	[VerdictTypeId] = VerdictTypeId;
-};
-var Break = class extends Schema.TaggedClass()("Break", {
+});
+const Break = Schema.TaggedStruct("Break", {
 	conjunct: Schema.String,
 	inspected: Schema.Array(Schema.String),
 	detail: Schema.String
-}) {
-	[VerdictTypeId] = VerdictTypeId;
-};
+});
 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);
@@ -117,6 +129,7 @@ const SpanLink = Schema.Struct({
 	traceId: Schema.String,
 	spanId: Schema.String
 });
+const SpanMillis = Schema.Finite.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0)));
 const SpanRecord = Schema.Struct({
 	traceId: Schema.String,
 	spanId: Schema.String,
@@ -124,8 +137,8 @@ const SpanRecord = Schema.Struct({
 	name: Schema.String,
 	status: Status,
 	errorType: Schema.NullOr(Schema.String),
-	startMillis: Schema.Finite,
-	durationMillis: Schema.Finite,
+	startMillis: SpanMillis,
+	durationMillis: SpanMillis,
 	attributes: Attributes,
 	events: Schema.Array(SpanEvent),
 	links: Schema.Array(SpanLink)
@@ -136,8 +149,8 @@ const GraphNode = Schema.Struct({
 	name: Schema.String,
 	status: Status,
 	errorType: Schema.NullOr(Schema.String),
-	startMillis: Schema.Finite,
-	durationMillis: Schema.Finite,
+	startMillis: SpanMillis,
+	durationMillis: SpanMillis,
 	attrs: Attributes,
 	events: Schema.Array(SpanEvent),
 	links: Schema.Array(SpanLink)
@@ -227,18 +240,27 @@ const decodeImpl = (traceId, spans, taxonomy) => {
 const decode = dual(3, decodeImpl);
 //#endregion
 //#region src/IncompleteObservationError.schema.ts
+const SpanCount = Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0, { message: "a span count is a non-negative integer" })));
 var IncompleteObservationError = class extends Schema.TaggedError()("IncompleteObservationError", {
 	traceId: Schema.String,
-	spanCount: Schema.Finite,
+	spanCount: SpanCount,
 	detail: Schema.String
-}) {};
+}) {
+	get message() {
+		return `Trace "${this.traceId}" is incomplete after ${this.spanCount} spans: ${this.detail}`;
+	}
+};
 //#endregion
 //#region src/TransportObservationError.schema.ts
 var TransportObservationError = class extends Schema.TaggedError()("TransportObservationError", {
 	traceId: Schema.String,
 	source: Schema.String,
 	detail: Schema.String
-}) {};
+}) {
+	get message() {
+		return `The trace store at "${this.source}" could not serve trace "${this.traceId}": ${this.detail}`;
+	}
+};
 //#endregion
 //#region src/Observation.service.ts
 var Observation_service_exports = /* @__PURE__ */ __exportAll({
@@ -249,28 +271,23 @@ 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({
+	BreakFailure: () => BreakFailure,
 	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 OWN_FRAMES = /\/trace-spec\/(?:src|dist)\//u;
+const callFrame = () => callFrameOutside(OWN_FRAMES);
 const TypeId$3 = Symbol.for("@systemfsoftware/trace-spec/Contract");
 const stimulatedOf = (taxonomy, stimulus) => ({
 	[TypeId$3]: TypeId$3,
@@ -322,13 +339,39 @@ 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 failureOfReport = (report) => new BreakFailure({ report: report.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 verdictCheckWith = (self, expect, judgment, frame) => {
+	const report = reportOf(self.relation.id, judgment);
+	return report.verdict === "Break" ? Effect.die(withRaisingFrame(failureOfReport(report), frame)) : expect(report, report.report).toEqual(held);
+};
+const verdictCheckImpl = (self, expect, judgment) => verdictCheckWith(self, expect, judgment, callFrame());
+/**
+* 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) => {
+	const frame = callFrame();
+	return Effect.flatMap(judgeDual(self, input, options), (judgment) => verdictCheckWith(self, expect, judgment, frame));
+};
+/**
+* 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 +590,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 +682,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));
@@ -622,7 +690,7 @@ const collect = dual(2, (self, traceId) => Effect.suspend(() => {
 const context = (self) => Context.make(Observation, { collect: (traceId) => collect(self, traceId) }).pipe(Context.add(OtelTracer.OtelTracerProvider, ObservationWindow.slot(self).provider));
 //#endregion
 //#region src/ObservationWindowSpec.schema.ts
-var ObservationWindowSpec = class extends Schema.Class("ObservationWindowSpec")({ serviceName: Schema.NonEmptyString }) {};
+const ObservationWindowSpec = Schema.Struct({ serviceName: Schema.NonEmptyString });
 //#endregion
 //#region src/observation-window.blueprint.ts
 var observation_window_blueprint_exports = /* @__PURE__ */ __exportAll({
@@ -643,7 +711,7 @@ const ObservationWindows = Blueprint.make()(TypeId$1).steps({
 		layer: layer$1
 	}
 });
-const make$2 = (serviceName) => ObservationWindows.of(new ObservationWindowSpec({ serviceName }));
+const make$2 = (serviceName) => ObservationWindows.of(ObservationWindowSpec.make({ serviceName }));
 //#endregion
 //#region src/Rel.ts
 var Rel_exports = /* @__PURE__ */ __exportAll({
@@ -676,7 +744,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 +754,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 +770,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 +799,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 +807,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 +815,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 +823,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 +831,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 +840,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 +848,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 +857,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 +917,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 +1106,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 +1144,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 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 announcement = (taskContext, message, type) => Option.match(Option.fromNullishOr(taskContext), {
 	onNone: () => Effect.void,
-	onSome: (message) => annotate(message)
+	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 = (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) => 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,92 +1185,104 @@ 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
+const firstLine = (text) => text.split("\n")[0] ?? "";
 var StimulusFailure = class extends Schema.TaggedError()("StimulusFailure", {
 	stimulus: Schema.String,
 	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")
-});
+}) {
+	get message() {
+		return `The stimulus "${this.stimulus}" failed: ${firstLine(this.detail)}`;
+	}
+};
 //#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,14 +1,14 @@
 {
   "name": "@systemfsoftware/trace-spec",
   "license": "Apache-2.0",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "author": "Ryan Lee <drdgvhbh@gmail.com>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/systemfsoftware/systemfsoftware.git",
-    "directory": "packages/trace-spec"
+    "directory": "packages/trace/trace-spec"
   },
-  "homepage": "https://github.com/systemfsoftware/systemfsoftware/tree/main/packages/trace-spec#readme",
+  "homepage": "https://github.com/systemfsoftware/systemfsoftware/tree/main/packages/trace/trace-spec#readme",
   "bugs": "https://github.com/systemfsoftware/systemfsoftware/issues",
   "description": "Trace contracts as executable specs — own a trace id, observe the finished trace through an in-memory exporter, and relate the decoded span graph to a declared taxonomy.",
   "keywords": [
@@ -38,18 +38,19 @@
     "@opentelemetry/resources": "^2",
     "@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/trace-taxonomy": "^0.0.1"
+    "@systemfsoftware/effect-cell-types": "^10.3.0",
+    "@systemfsoftware/effect-spec-runtime": "^0.3.1",
+    "@systemfsoftware/trace-taxonomy": "^0.0.2"
   },
   "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.2.0",
+    "@systemfsoftware/effect-gherkin-spec": "^6.0.0",
+    "@systemfsoftware/oxlint-config-recommended": "^3.2.0",
     "@systemfsoftware/tsconfig": "^2.0.1",
     "@systemfsoftware/tsdown-config": "^0.1.0",
+    "@systemfsoftware/vitest": "^0.2.0",
     "@systemfsoftware/vitest-config": "^0.1.0",
     "@types/node": "^26",
     "effect": "4.0.0-rc.117",
@@ -60,11 +61,12 @@
     "vitest": "^5"
   },
   "peerDependencies": {
-    "@effect/vitest": "npm:@systemfsoftware/vitest@*",
+    "@systemfsoftware/vitest": "^0.2.0",
     "effect": "4.0.0-rc.117",
     "vitest": "^5"
   },
   "publishConfig": {
+    "access": "public",
     "provenance": true
   },
   "scripts": {