@systemfsoftware/trace-spec 0.0.0

package/dist/index.mjs

@@ -0,0 +1,824 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
+import { Cause, Context, Effect, Equal, FileSystem, Layer, Match, Option, Predicate, Result, Schema } from "effect";
+import { dual } from "effect/Function";
+import { Prototype } from "effect/Pipeable";
+import "effect/PlatformError";
+import "@systemfsoftware/trace-taxonomy";
+import * as OtelTracer from "@effect/opentelemetry/OtelTracer";
+import * as OtelResource from "@effect/opentelemetry/Resource";
+import { SpanStatusCode } from "@opentelemetry/api";
+import { AlwaysOnSampler, BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor } 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", {
+	declarationId: Schema.String,
+	spanName: Schema.String,
+	spanId: Schema.String,
+	attribute: Schema.String,
+	detail: Schema.String
+}) {};
+//#endregion
+//#region src/EmptyObservationError.schema.ts
+var EmptyObservationError = class extends Schema.TaggedError()("EmptyObservationError", {
+	traceId: Schema.String,
+	detail: Schema.String
+}) {};
+//#endregion
+//#region src/Verdict.schema.ts
+const VerdictTypeId = Symbol.for("@systemfsoftware/trace-spec/Verdict");
+var Hold = class extends Schema.TaggedClass()("Hold", {
+	conjunct: Schema.String,
+	inspected: Schema.Array(Schema.String)
+}) {
+	[VerdictTypeId] = VerdictTypeId;
+};
+var Break = class extends Schema.TaggedClass()("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);
+/**
+* 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 renderValue = (value) => JSON.stringify(value);
+const renderEntries = (entries) => [...entries].map(([key, value]) => `${key}=${renderValue(value)}`).join(" ");
+const indentOf = (depth) => "  ".repeat(depth);
+const renderBreach = (breach) => `break ${breach.conjunct} inspected=[${breach.inspected.join(", ")}]\n${indentOf(1)}${breach.detail}`;
+const childrenOf = (spans, spanId) => spans.filter((span) => span.parentSpanId === spanId);
+const renderNode = (spans, node, depth) => {
+	return [`${indentOf(depth)}${node.name} (${node.spanId}) status=${node.status} error.type=${String(node.errorType)} duration=${node.durationMillis}ms`, ...[
+		`${indentOf(depth)}  attrs: ${renderEntries(Object.entries(node.attributes))}`,
+		...node.events.map((event) => `${indentOf(depth)}  event ${event.name} ${renderEntries(Object.entries(event.attributes))}`),
+		...node.links.map((link) => `${indentOf(depth)}  link ${link.traceId}/${link.spanId}`),
+		...childrenOf(spans, node.spanId).map((child) => renderNode(spans, child, depth + 1))
+	]].join("\n");
+};
+/**
+* The dump document: the trace it belongs to, the break that refused it, and the recorded
+* spans as the observation window saw them.
+*/
+const document = (observed, report) => [
+	`trace ${observed.traceId}`,
+	report,
+	...observed.spans.map((node) => renderNode(observed.spans, node, 0))
+].join("\n");
+const sanitize = (value) => value.replace(/[^a-zA-Z0-9._-]+/g, "-");
+const fileNameOf = (request) => `${sanitize(request.name ?? request.traceId)}.${sanitize(request.conjunct)}.txt`;
+/**
+* Writes the dump under the artifacts directory and answers with its path. The file is
+* named after the request's name when one is given — a generated case names its dump after
+* itself, so every failing draw overwrites one file and the last write is the reported
+* counterexample.
+*/
+const write = (request) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	yield* fs.makeDirectory(DEFAULT_DIRECTORY, { recursive: true });
+	const path = `${DEFAULT_DIRECTORY}/${fileNameOf(request)}`;
+	yield* fs.writeFileString(path, document(request, request.report));
+	return path;
+});
+//#endregion
+//#region src/TraceGraph.schema.ts
+const Status = Schema.Literals([
+	"ok",
+	"unset",
+	"error"
+]);
+const AttributeValue = Schema.Union([
+	Schema.String,
+	Schema.Finite,
+	Schema.Boolean,
+	Schema.Array(Schema.Union([
+		Schema.String,
+		Schema.Finite,
+		Schema.Boolean
+	]))
+]);
+const Attributes = Schema.Record(Schema.String, AttributeValue);
+const SpanEvent = Schema.Struct({
+	name: Schema.String,
+	attributes: Attributes
+});
+const SpanLink = Schema.Struct({
+	traceId: Schema.String,
+	spanId: Schema.String
+});
+const SpanRecord = Schema.Struct({
+	traceId: Schema.String,
+	spanId: Schema.String,
+	parentSpanId: Schema.NullOr(Schema.String),
+	name: Schema.String,
+	status: Status,
+	errorType: Schema.NullOr(Schema.String),
+	startMillis: Schema.Finite,
+	durationMillis: Schema.Finite,
+	attributes: Attributes,
+	events: Schema.Array(SpanEvent),
+	links: Schema.Array(SpanLink)
+});
+const GraphNode = Schema.Struct({
+	spanId: Schema.String,
+	parentSpanId: Schema.NullOr(Schema.String),
+	name: Schema.String,
+	status: Status,
+	errorType: Schema.NullOr(Schema.String),
+	startMillis: Schema.Finite,
+	durationMillis: Schema.Finite,
+	attrs: Attributes,
+	events: Schema.Array(SpanEvent),
+	links: Schema.Array(SpanLink)
+});
+const TraceGraph = Schema.Struct({
+	traceId: Schema.String,
+	nodes: Schema.Array(GraphNode)
+});
+//#endregion
+//#region src/Graph.ts
+var Graph_exports = /* @__PURE__ */ __exportAll({
+	AttributeValue: () => AttributeValue,
+	Attributes: () => Attributes,
+	GraphNode: () => GraphNode,
+	SpanEvent: () => SpanEvent,
+	SpanLink: () => SpanLink,
+	SpanRecord: () => SpanRecord,
+	Status: () => Status,
+	TraceGraph: () => TraceGraph,
+	byId: () => byId,
+	children: () => children,
+	decode: () => decode,
+	descendants: () => descendants
+});
+const byId = (graph, spec) => graph.nodes.filter((node) => node.name === spec.name);
+const children = (graph, node) => graph.nodes.filter((candidate) => candidate.parentSpanId === node.spanId);
+const descendants = (graph, node) => {
+	const direct = children(graph, node);
+	return [...direct, ...direct.flatMap((child) => descendants(graph, child))];
+};
+const indexDeclarations = (taxonomy) => new Map(taxonomy.spans.map((span) => [span.name, span]));
+const keyOfPath = (path) => {
+	const last = path.at(-1);
+	return last === void 0 ? null : String(last);
+};
+const pointerAttributeName = (pointer) => keyOfPath(pointer.path) ?? attributeNameOf(pointer.issue);
+const filterAttributeName = (filter) => attributeNameOf(filter.issue);
+const encodingAttributeName = (encoding) => attributeNameOf(encoding.issue);
+const compositeAttributeName = (composite) => firstAttributeName(composite.issues);
+const anyOfAttributeName = (anyOf) => firstAttributeName(anyOf.issues);
+const noAttributeName = () => null;
+const attributeNameOf = (issue) => Match.value(issue).pipe(Match.tag("Pointer", pointerAttributeName), Match.tag("Filter", filterAttributeName), Match.tag("Encoding", encodingAttributeName), Match.tag("Composite", compositeAttributeName), Match.tag("AnyOf", anyOfAttributeName), Match.orElse(noAttributeName));
+const firstAttributeName = (issues) => issues.map(attributeNameOf).find((name) => name !== null) ?? null;
+const decodeFailure = (spec, record, detail, attribute) => ContractDecodeError.make({
+	declarationId: spec.id,
+	spanName: record.name,
+	spanId: record.spanId,
+	attribute: attribute ?? "*",
+	detail
+});
+const decodeAttrs = (spec, record) => Result.mapError(Schema.decodeResult(Schema.toType(spec.attrs))(record.attributes), (error) => decodeFailure(spec, record, error.message, attributeNameOf(error.issue)));
+const nodeOf = (record, attrs) => ({
+	spanId: record.spanId,
+	parentSpanId: record.parentSpanId,
+	name: record.name,
+	status: record.status,
+	errorType: record.errorType,
+	startMillis: record.startMillis,
+	durationMillis: record.durationMillis,
+	attrs,
+	events: record.events,
+	links: record.links
+});
+const decodedNodeOf = (record, spec) => Result.map(decodeAttrs(spec, record), (attrs) => nodeOf(record, attrs));
+const declaredNodeOf = (record, declarations) => {
+	const spec = declarations.get(record.name);
+	return spec === void 0 ? Result.succeed(nodeOf(record, record.attributes)) : decodedNodeOf(record, spec);
+};
+const graphOf = (traceId, nodes) => ({
+	traceId,
+	nodes
+});
+/**
+* Decodes the recorded spans of one trace against a taxonomy, purely: a declared span
+* whose required attributes do not decode refuses with {@link ContractDecodeError}
+* naming the declaration and the attribute, and a span no declaration accounts for enters
+* the graph as recorded. Failure is a `Result`, so the phase that reads the trace cannot
+* fail the pipeline by accident.
+*/
+const decode = (traceId, spans, taxonomy) => {
+	const declarations = indexDeclarations(taxonomy);
+	return Result.map(Result.all(spans.map((record) => declaredNodeOf(record, declarations))), (nodes) => graphOf(traceId, nodes));
+};
+//#endregion
+//#region src/Observation.service.ts
+var Observation_service_exports = /* @__PURE__ */ __exportAll({
+	EmptyObservationError: () => EmptyObservationError,
+	Observation: () => Observation
+});
+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,
+	TraceDisparityError: () => TraceDisparityError,
+	TypeId: () => TypeId$3,
+	check: () => check,
+	holds: () => holds,
+	judge: () => judge,
+	of: () => of,
+	stimulate: () => stimulate
+});
+const TypeId$3 = Symbol.for("@systemfsoftware/trace-spec/Contract");
+const stimulatedOf = (taxonomy, stimulus) => ({
+	[TypeId$3]: TypeId$3,
+	taxonomy,
+	stimulus,
+	holds: (relation) => contractOf(taxonomy, stimulus, relation),
+	...Prototype
+});
+const contractOf = (taxonomy, stimulus, relation) => ({
+	[TypeId$3]: TypeId$3,
+	taxonomy,
+	stimulus,
+	relation,
+	...Prototype
+});
+const of = (taxonomy) => ({
+	[TypeId$3]: TypeId$3,
+	taxonomy,
+	stimulate: (stimulus) => stimulatedOf(taxonomy, stimulus),
+	...Prototype
+});
+const stimulateDual = (self, stimulus) => stimulatedOf(self.taxonomy, stimulus);
+const stimulate = dual(2, stimulateDual);
+const holdsDual = (self, relation) => contractOf(self.taxonomy, self.stimulus, relation);
+const holds = dual(2, holdsDual);
+const isContract = (value) => Predicate.hasProperty(value, TypeId$3);
+const dumpOf = (observed, verdict, options) => Option.match(report(verdict), {
+	onNone: () => Effect.succeed(null),
+	onSome: (report) => Effect.map(Effect.option(write({
+		...observed,
+		conjunct: verdict.conjunct,
+		report,
+		name: options?.dumpName
+	})), Option.getOrNull)
+});
+const judgeDual = (self, input, options) => Effect.gen(function* () {
+	const observation = yield* Observation;
+	const run = yield* self.stimulus(input);
+	const spans = yield* observation.collect(run.traceId);
+	const graph = yield* Effect.fromResult(decode(run.traceId, spans, self.taxonomy));
+	const verdict = self.relation(graph);
+	return {
+		run,
+		verdict,
+		dumpPath: yield* dumpOf({
+			traceId: run.traceId,
+			spans
+		}, verdict, options)
+	};
+});
+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) => refuseBreak(self.relation.id, judgment));
+const check = dual((args) => isContract(args[0]), checkDual);
+//#endregion
+//#region src/observation-window.handle.ts
+const TypeId$2 = Symbol.for("~systemfsoftware/trace-spec/ObservationWindow");
+const ExporterId = Symbol.for("~systemfsoftware/trace-spec/ObservationWindow/exporter");
+const ProviderId = Symbol.for("~systemfsoftware/trace-spec/ObservationWindow/provider");
+const isObservationWindow = (u) => Predicate.hasProperty(u, TypeId$2);
+const make$3 = (spec) => {
+	const exporter = new InMemorySpanExporter();
+	const provider = new BasicTracerProvider({
+		sampler: new AlwaysOnSampler(),
+		spanProcessors: [new SimpleSpanProcessor(exporter)]
+	});
+	return {
+		[TypeId$2]: TypeId$2,
+		[ExporterId]: exporter,
+		[ProviderId]: provider,
+		serviceName: spec.serviceName,
+		...Prototype
+	};
+};
+const shutdown = (self) => Effect.promise(() => self[ProviderId].shutdown());
+const SCALAR_TYPES = {
+	string: true,
+	number: true,
+	boolean: true
+};
+const isScalar = (value) => SCALAR_TYPES[typeof value] === true;
+const scalarArrayOrNull = (value) => Array.isArray(value) ? value.filter(isScalar) : null;
+const definedOrEmpty = (value) => value ?? [];
+const attributeValue = (value) => isScalar(value) ? value : scalarArrayOrNull(definedOrEmpty(value));
+const isPresent = (entry) => entry[1] !== null;
+const attributeRecordOf = (attributes) => Object.fromEntries(Object.entries(attributes).map((entry) => [entry[0], attributeValue(entry[1])]).filter(isPresent));
+const STATUS_BY_CODE = {
+	[SpanStatusCode.OK]: "ok",
+	[SpanStatusCode.ERROR]: "error",
+	[SpanStatusCode.UNSET]: "unset"
+};
+const statusOf = (code) => STATUS_BY_CODE[code] ?? "unset";
+const errorTypeOf = (attributes) => {
+	const value = attributes["error.type"];
+	return typeof value === "string" ? value : null;
+};
+const parentOf = (span) => {
+	const parent = span.parentSpanContext;
+	return parent === void 0 ? null : parent.spanId;
+};
+const eventsOf = (span) => span.events.map((event) => ({
+	name: event.name,
+	attributes: attributeRecordOf(event.attributes ?? {})
+}));
+const linksOf = (span) => span.links.map((link) => ({
+	traceId: link.context.traceId,
+	spanId: link.context.spanId
+}));
+const millisOf = (duration) => duration[0] * 1e3 + duration[1] / 1e6;
+const spanRecordOf = (span) => {
+	const attributes = attributeRecordOf(span.attributes);
+	return {
+		traceId: span.spanContext().traceId,
+		spanId: span.spanContext().spanId,
+		parentSpanId: parentOf(span),
+		name: span.name,
+		status: statusOf(span.status.code),
+		errorType: errorTypeOf(attributes),
+		startMillis: millisOf(span.startTime),
+		durationMillis: millisOf(span.duration),
+		attributes,
+		events: eventsOf(span),
+		links: linksOf(span)
+	};
+};
+const emptyObservation = (traceId) => new EmptyObservationError({
+	traceId,
+	detail: "the observation window closed with no span carrying the stimulated trace id"
+});
+const recordsOf = (self, traceId) => self[ExporterId].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));
+}));
+const context = (self) => Context.make(Observation, { collect: (traceId) => collect(self, traceId) }).pipe(Context.add(OtelTracer.OtelTracerProvider, self[ProviderId]));
+//#endregion
+//#region src/ObservationWindowSpec.schema.ts
+var ObservationWindowSpec = class extends Schema.Class("ObservationWindowSpec")({ serviceName: Schema.NonEmptyString }) {};
+//#endregion
+//#region src/observation-window.resource.ts
+var observation_window_resource_exports = /* @__PURE__ */ __exportAll({
+	ObservationWindowSpec: () => ObservationWindowSpec,
+	ObservationWindowTypeId: () => TypeId$2,
+	collect: () => collect,
+	isObservationWindow: () => isObservationWindow,
+	make: () => make$2
+});
+const TypeId$1 = Symbol.for("~systemfsoftware/trace-spec/ObservationWindowResource");
+const scoped = (spec) => Effect.acquireRelease(Effect.sync(() => make$3(spec)), shutdown);
+const layer = (spec) => OtelTracer.layer.pipe(Layer.provideMerge(OtelResource.layer({ serviceName: spec.serviceName })), Layer.provideMerge(Layer.effectContext(Effect.map(scoped(spec), context))));
+const makeProto = (spec) => ({
+	[TypeId$1]: TypeId$1,
+	spec,
+	get scoped() {
+		return scoped(spec);
+	},
+	get layer() {
+		return layer(spec);
+	},
+	...Prototype
+});
+const make$2 = (serviceName) => makeProto(new ObservationWindowSpec({ serviceName }));
+//#endregion
+//#region src/Rel.ts
+var Rel_exports = /* @__PURE__ */ __exportAll({
+	Break: () => Break,
+	Hold: () => Hold,
+	Verdict: () => Verdict,
+	absent: () => absent,
+	all: () => all,
+	any: () => any,
+	attrs: () => attrs,
+	child: () => child,
+	descendant: () => descendant,
+	durationLessThan: () => durationLessThan,
+	errorType: () => errorType,
+	event: () => event,
+	exists: () => exists,
+	forall: () => forall,
+	fromTaxonomy: () => fromTaxonomy,
+	not: () => not,
+	order: () => order,
+	soft: () => soft,
+	status: () => status,
+	unique: () => unique
+});
+const relation = (parts) => Object.assign((graph) => parts.evaluate(graph), {
+	id: parts.id,
+	soft: parts.soft,
+	softenable: parts.softenable
+});
+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 isHold$1 = (verdict) => Schema.is(Hold)(verdict);
+const verdictOf = (options) => options.holds ? Hold.make({
+	conjunct: options.id,
+	inspected: options.inspected
+}) : Break.make({
+	conjunct: options.id,
+	inspected: options.inspected,
+	detail: options.detail
+});
+const declared = (declaration) => relation({
+	id: declaration.id,
+	soft: false,
+	softenable: declaration.softenable,
+	evaluate: (graph) => {
+		const inspected = declaration.spans.flatMap((span) => inspectedOf(byId(graph, span)));
+		return verdictOf({
+			id: declaration.id,
+			inspected,
+			holds: declaration.holds(graph),
+			detail: declaration.detail
+		});
+	}
+});
+const holdsCountOf = (spec, expected) => (graph) => expected(matchedNodes(graph, spec).length);
+const holdsEveryOf = (spec, predicate) => (graph) => matchedAll(matchedNodes(graph, spec), predicate);
+const exists = (spec) => declared({
+	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({
+	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({
+	id: `unique(${spec.id})`,
+	spans: [spec],
+	softenable: true,
+	detail: `expected exactly one ${spec.id} span`,
+	holds: holdsCountOf(spec, (count) => count === 1)
+});
+const childIdsOf = (graph, parents) => new Set(parents.flatMap((parent) => children(graph, parent)).map((node) => node.spanId));
+const descendantIdsOf = (graph, parents) => new Set(parents.flatMap((parent) => descendants(graph, parent)).map((node) => node.spanId));
+const startsAtOrAfter = (earlier, later) => later.startMillis >= earlier.startMillis;
+const startsAfterSome = (earlier, later) => earlier.some((node) => startsAtOrAfter(node, later));
+const reachedUnder = (graph, parent, childSpan, reach) => {
+	const reached = reach(graph, matchedNodes(graph, parent));
+	return matchedNodes(graph, childSpan).some((node) => reached.has(node.spanId));
+};
+const child = (parent, childSpan) => declared({
+	id: `child(${parent.id},${childSpan.id})`,
+	spans: [parent, childSpan],
+	softenable: true,
+	detail: `no ${childSpan.id} span is a direct child of a ${parent.id} span`,
+	holds: (graph) => reachedUnder(graph, parent, childSpan, childIdsOf)
+});
+const descendant = (parent, childSpan) => declared({
+	id: `descendant(${parent.id},${childSpan.id})`,
+	spans: [parent, childSpan],
+	softenable: true,
+	detail: `no ${childSpan.id} span descends from a ${parent.id} span`,
+	holds: (graph) => reachedUnder(graph, parent, childSpan, descendantIdsOf)
+});
+const order = (before, after) => declared({
+	id: `order(${before.id},${after.id})`,
+	spans: [before, after],
+	softenable: true,
+	detail: `a ${after.id} span starts before every ${before.id} span`,
+	holds: (graph) => matchedAll(matchedNodes(graph, after), (node) => startsAfterSome(matchedNodes(graph, before), node))
+});
+const status = (spec, expected) => declared({
+	id: `status(${spec.id},${expected})`,
+	spans: [spec],
+	softenable: true,
+	detail: `a ${spec.id} span is not ${expected}`,
+	holds: holdsEveryOf(spec, (node) => node.status === expected)
+});
+const errorType = (spec, expected) => declared({
+	id: `errorType(${spec.id},${expected})`,
+	spans: [spec],
+	softenable: true,
+	detail: `a ${spec.id} span carries a different error.type`,
+	holds: holdsEveryOf(spec, (node) => node.errorType === expected)
+});
+const partialMatches = (attributes, partial) => Object.entries(partial).filter(([, value]) => value !== void 0).every(([key, value]) => Equal.equals(attributes[key], value));
+const attrs = (spec, partial) => declared({
+	id: `attrs(${spec.id})`,
+	spans: [spec],
+	softenable: true,
+	detail: `a ${spec.id} span carries a different declared attribute`,
+	holds: holdsEveryOf(spec, (node) => partialMatches(node.attrs, partial))
+});
+const durationLessThan = (spec, millis) => declared({
+	id: `durationLessThan(${spec.id},${millis})`,
+	spans: [spec],
+	softenable: true,
+	detail: `a ${spec.id} span exceeded ${millis}ms`,
+	holds: holdsEveryOf(spec, (node) => node.durationMillis < millis)
+});
+const carriesEvent = (name) => (node) => node.events.some((event) => event.name === name);
+const event = (spec, name) => declared({
+	id: `event(${spec.id},${name})`,
+	spans: [spec],
+	softenable: true,
+	detail: `a ${spec.id} span carries no ${name} event`,
+	holds: holdsEveryOf(spec, carriesEvent(name))
+});
+const forall = (spec, predicate, detail) => {
+	const id = `forall(${spec.id})`;
+	return relation({
+		id,
+		soft: false,
+		softenable: true,
+		evaluate: (graph) => {
+			const nodes = matchedNodes(graph, spec);
+			return verdictOf({
+				id,
+				inspected: inspectedOf(nodes),
+				holds: matchedAll(nodes, predicate),
+				detail: nodes.length === 0 ? `no ${spec.id} span was emitted: forall is non-vacuous` : detail
+			});
+		}
+	});
+};
+const soft = (self) => self.softenable ? relation({
+	id: self.id,
+	soft: true,
+	softenable: true,
+	evaluate: (graph) => self(graph)
+}) : self;
+const negatedVerdict = (id, inner) => Match.value(inner).pipe(Match.tag("Hold", (held) => Break.make({
+	conjunct: id,
+	inspected: held.inspected,
+	detail: `${held.conjunct} held`
+})), Match.tag("Break", (breach) => Hold.make({
+	conjunct: id,
+	inspected: breach.inspected
+})), Match.exhaustive);
+const not = (self) => {
+	const id = `not(${self.id})`;
+	return relation({
+		id,
+		soft: false,
+		softenable: false,
+		evaluate: (graph) => negatedVerdict(id, self(graph))
+	});
+};
+const collectSoft = (id, breaks) => {
+	const inspected = breaks.flatMap((breach) => breach.inspected);
+	return breaks.length === 0 ? Hold.make({
+		conjunct: id,
+		inspected
+	}) : Break.make({
+		conjunct: id,
+		inspected,
+		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 combined = (options) => relation({
+	id: options.id,
+	soft: options.soft,
+	softenable: options.softenable,
+	evaluate: (graph) => firstHardBreak(options.relations, graph) ?? collectSoft(options.id, softBreaks(options.relations, graph))
+});
+const all = (...relations) => combined({
+	id: `all(${relations.map((relation) => relation.id).join(", ")})`,
+	relations,
+	soft: relations.every((relation) => relation.soft),
+	softenable: true
+});
+const any = (...relations) => {
+	const id = `any(${relations.map((relation) => relation.id).join(", ")})`;
+	return relation({
+		id,
+		soft: false,
+		softenable: false,
+		evaluate: (graph) => {
+			const verdicts = relations.map((relation) => relation(graph));
+			const inspected = verdicts.flatMap((verdict) => verdict.inspected);
+			return verdicts.some(isHold$1) ? Hold.make({
+				conjunct: id,
+				inspected
+			}) : Break.make({
+				conjunct: id,
+				inspected,
+				detail: verdicts.map((verdict) => verdict.conjunct).join(", ")
+			});
+		}
+	});
+};
+const REACH_BY_RELATION = {
+	child: childIdsOf,
+	descendant: descendantIdsOf
+};
+const placementOf = (edge) => {
+	const id = `placement(${edge.relation}:${edge.parent.id},${edge.child.id})`;
+	return relation({
+		id,
+		soft: false,
+		softenable: false,
+		evaluate: (graph) => {
+			const placed = matchedNodes(graph, edge.child);
+			const reached = REACH_BY_RELATION[edge.relation](graph, matchedNodes(graph, edge.parent));
+			return verdictOf({
+				id,
+				inspected: inspectedOf(placed),
+				holds: placed.every((node) => reached.has(node.spanId)),
+				detail: `a ${edge.child.id} span is not a ${edge.relation} of any ${edge.parent.id} span`
+			});
+		}
+	});
+};
+const forbidsAt = (entry, path) => Option.match(entry.unless, {
+	onNone: () => true,
+	onSome: (tag) => tag !== path
+});
+const forbiddenOn = (path) => (entry) => forbidsAt(entry, path) ? [absent(entry.span)] : [];
+const fromTaxonomy = (taxonomy, options) => combined({
+	id: `fromTaxonomy(${taxonomy.id},${options.path})`,
+	relations: [...taxonomy.edges.map(placementOf), ...taxonomy.forbidden.flatMap(forbiddenOn(options.path))],
+	soft: false,
+	softenable: false
+});
+//#endregion
+//#region src/Stimulus.ts
+var Stimulus_exports = /* @__PURE__ */ __exportAll({
+	make: () => make$1,
+	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);
+	return {
+		traceId,
+		spanId,
+		traceparent: `00-${traceId}-${spanId}-01`
+	};
+});
+const make$1 = (options) => {
+	const stimulus = (input) => Effect.gen(function* () {
+		const context = yield* traceContext;
+		const output = yield* options.run({
+			input,
+			traceId: context.traceId,
+			traceparent: context.traceparent
+		}).pipe(Effect.withParentSpan(OtelTracer.makeExternalSpan({
+			traceId: context.traceId,
+			spanId: context.spanId,
+			traceFlags: 1
+		})));
+		return {
+			input,
+			traceId: context.traceId,
+			output
+		};
+	});
+	Object.defineProperty(stimulus, "name", { value: options.name });
+	return stimulus;
+};
+//#endregion
+//#region src/Prop.ts
+const isHold = Schema.is(Hold);
+const isBreak = Schema.is(Break);
+const annotate = (context, message) => Option.match(Option.flatMap(Option.fromNullishOr(context), (task) => Option.fromNullishOr(task.annotate)), {
+	onNone: () => Effect.void,
+	onSome: (record) => Effect.promise(() => Promise.resolve(record(message, "info")))
+});
+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 = (context, verdict, dumpPath) => Option.match(dumpMessageOf(verdict, dumpPath), {
+	onNone: () => Effect.void,
+	onSome: (message) => annotate(context, message)
+});
+/**
+* The generated-case predicate for one case: a factory that runs the contract's cell with
+* the dump named after the case — so every failing draw overwrites one file and the last
+* failing draw is the shrunk counterexample the runner reports — and answers the verdict as
+* the boolean: `true` while the relation held, `false` on a break, falsifying the property.
+* Only infrastructure refusals — a failing behaviour, an undecodable span, an empty
+* observation — stay on the error channel. The scenario layer is built fresh per draw, so
+* each draw owns its observation window.
+*/
+function predicate(title, contract, scenario) {
+	const checked = (input, context) => judge(contract, input, { dumpName: title }).pipe(Effect.tap((judgment) => announce(context, judgment.verdict, judgment.dumpPath)), Effect.map((judgment) => isHold(judgment.verdict)), Effect.provide(Layer.fresh(scenario)));
+	return (input, context) => checked(input, context);
+}
+//#endregion
+//#region src/StimulusFailure.schema.ts
+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")
+});
+//#endregion
+//#region src/Suite.ts
+var Suite_exports = /* @__PURE__ */ __exportAll({
+	StimulusFailure: () => StimulusFailure,
+	TypeId: () => TypeId,
+	make: () => make,
+	withLayer: () => withLayer,
+	withScenarioLayer: () => withScenarioLayer
+});
+const TypeId = Symbol.for("@systemfsoftware/trace-spec/Suite");
+const isCheckFailure = Schema.is(Schema.Union([
+	ContractDecodeError,
+	EmptyObservationError,
+	TraceDisparityError
+]));
+const caseFailureOf = (stimulus) => (failure) => isCheckFailure(failure) ? failure : new StimulusFailure({
+	stimulus,
+	detail: Cause.pretty(Cause.fail(failure))
+});
+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");
+	Case.prop = (name, contract, arbitrary) => {
+		propIt.effect.prop(name, [arbitrary], (values, context) => predicate(name, contract, scenario)(values[0], context));
+	};
+	return { Case };
+};
+const config = (name) => ({
+	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) => ({
+	[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),
+	...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
+});
+//#endregion
+export { Contract_exports as Contract, Graph_exports as Graph, Observation_service_exports as Observation, observation_window_resource_exports as ObservationWindow, Rel_exports as Rel, Stimulus_exports as Stimulus, Suite_exports as Suite };