@systemfsoftware/trace-spec 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @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

package/dist/index.d.ts

@@ -9,6 +9,14 @@ 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;
@@ -17,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"]>;
@@ -145,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 };
 }
@@ -157,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 };
@@ -263,7 +280,7 @@ declare const make$3: <Input, Output, E, R>(options: {
   }) => Effect.Effect<Output, E, R>;
 }) => Stimulus<Input, Output, E, R>;
 declare namespace Contract_d_exports {
-  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 };
+  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;
@@ -377,10 +394,10 @@ 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 };
 }
@@ -419,10 +436,16 @@ 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
@@ -435,7 +458,9 @@ 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, LiveStage, Opened, Shared, StimulusFailure, TypeId, live, make, withLayer, withScenarioLayer };
 }

package/dist/index.mjs

@@ -1,9 +1,12 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
+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";
@@ -13,6 +16,13 @@ import { Blueprint, Handle } from "@systemfsoftware/effect-cell-types";
 import { SpanStatusCode } from "@opentelemetry/api";
 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,
@@ -20,29 +30,32 @@ 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
@@ -116,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,
@@ -123,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)
@@ -135,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)
@@ -226,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({
@@ -250,6 +273,7 @@ var Observation = class extends Context.Service()("@systemfsoftware/trace-spec/O
 //#endregion
 //#region src/Contract.ts
 var Contract_exports = /* @__PURE__ */ __exportAll({
+	BreakFailure: () => BreakFailure,
 	ContractDecodeError: () => ContractDecodeError,
 	EmptyObservationError: () => EmptyObservationError,
 	IncompleteObservationError: () => IncompleteObservationError,
@@ -262,6 +286,8 @@ var Contract_exports = /* @__PURE__ */ __exportAll({
 	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,
@@ -318,6 +344,7 @@ 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: [
@@ -327,16 +354,20 @@ const reportOf = (relationId, judgment) => Match.value(judgment.verdict).pipe(Ma
 		`dump ${judgment.dumpPath ?? "(not written)"}`
 	].join("\n")
 })), Match.exhaustive);
-const verdictCheckImpl = (self, expect, judgment) => {
+const verdictCheckWith = (self, expect, judgment, frame) => {
 	const report = reportOf(self.relation.id, judgment);
-	return expect(report, report.report).toEqual(held);
+	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) => Effect.flatMap(judgeDual(self, input, options), (judgment) => verdictCheckImpl(self, expect, judgment));
+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.
@@ -659,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({
@@ -680,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({
@@ -1162,10 +1193,15 @@ const predicateImpl = (title, contract, scenario, shared) => {
 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
-}) {};
+}) {
+	get message() {
+		return `The stimulus "${this.stimulus}" failed: ${firstLine(this.detail)}`;
+	}
+};
 //#endregion
 //#region src/Suite.ts
 var Suite_exports = /* @__PURE__ */ __exportAll({

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@systemfsoftware/trace-spec",
   "license": "Apache-2.0",
-  "version": "0.4.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,19 +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.3.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",
     "@systemfsoftware/arethetypeswrong-cli": "^4.2.0",
-    "@systemfsoftware/conformance-spec": "^0.1.0",
-    "@systemfsoftware/effect-gherkin-spec": "^5.0.0",
-    "@systemfsoftware/oxlint-config-recommended": "^3.1.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.1.0",
+    "@systemfsoftware/vitest": "^0.2.0",
     "@systemfsoftware/vitest-config": "^0.1.0",
     "@types/node": "^26",
     "effect": "4.0.0-rc.117",
@@ -61,11 +61,12 @@
     "vitest": "^5"
   },
   "peerDependencies": {
-    "@systemfsoftware/vitest": "^0.1.0",
+    "@systemfsoftware/vitest": "^0.2.0",
     "effect": "4.0.0-rc.117",
     "vitest": "^5"
   },
   "publishConfig": {
+    "access": "public",
     "provenance": true
   },
   "scripts": {