@systemfsoftware/trace-spec 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @systemfsoftware/trace-spec
 
+## 0.2.1
+
+### 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.1
+
+## 0.2.0
+
+### Minor Changes
+
+- Judge contracts against traces produced in another process. `RemoteObservation.layer(source, { interval, settle, timeout })` provides `Observation` by reading a trace store until no read has added a span for `settle`. `TempoTraceStore.source({ baseUrl })` reads Grafana Tempo's `/api/v2/traces/<traceId>` through the `HttpClient` you provide; put auth and tenant headers on that client.
+
+  New failures `Observation.IncompleteObservationError` (spans never settled, or the store marked the trace partial) and `Observation.TransportObservationError` (the store could not be read) join `Collector.collect`, `Contract.JudgeFailure`, and `Suite.CaseFailure`. This is a breaking type change: code that matches every case of these unions, or restates them by hand, must handle both.
+
 ## 0.1.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 seven namespaces — `Contract`, `Graph`, `Observation`, `ObservationWindow`, `Rel`, `Stimulus`, `Suite`. Errors and verdicts belong to the capability that raises them: `Contract.ContractDecodeError`, `Contract.TraceDisparityError`, `Observation.EmptyObservationError`, `Suite.StimulusFailure`, and `Rel.Hold`/`Rel.Break`/`Rel.Verdict`.
+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`.
 
 ## Write a contract
 
@@ -38,15 +38,17 @@ const paymentUnderCheckout = Contract.of(checkout)
 
 ## Run the contract
 
-`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`, `Observation.EmptyObservationError`) stay on the error channel.
+`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`.
 
-| Outcome                                       | Failure                             | Meaning                                                                                 |
-| --------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------- |
-| The relation broke                            | `Contract.TraceDisparityError`      | names the broken conjunct, the spans inspected, and where the decoded graph was written |
-| 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                        |
+| Outcome                                       | Failure                                  | Meaning                                                                                            |
+| --------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| The relation broke                            | `Contract.TraceDisparityError`           | names the broken conjunct, the spans inspected, and where the decoded graph was written            |
+| 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   |
+| The trace store could not be read             | `Observation.TransportObservationError`  | the store refused, was unreachable, or answered a body that does not decode; names the request URL |
 
 ## Register cases
 
@@ -66,7 +68,7 @@ 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 three 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, 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.
 
 `.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.
 
@@ -76,6 +78,27 @@ TraceSuite('checkout.place_order')
 
 `ObservationWindow.make(serviceName)` is the cold resource; the service name is required. `.scoped` acquires an `ObservationWindow` handle for one scope — an OpenTelemetry in-memory exporter behind a simple span processor and an always-on sampler, shut down when the scope closes — and `ObservationWindow.collect(window, traceId)` reads one trace back. `.layer` binds a window as `Observation.Observation` plus the Effect tracer, one window per layer build, so two acquisitions never see each other's spans. Only the handle module imports the OpenTelemetry SDK. The export happens outside any test-clock boundary.
 
+## Observe a remote store
+
+When the behaviour runs in another process — a CLI binary, a worker, a container — its spans never reach an in-memory window. Export them to a trace store and read them back with `RemoteObservation.layer`, which provides `Observation.Observation` over a trace source:
+
+```ts
+import { RemoteObservation, TempoTraceStore } from '@systemfsoftware/trace-spec'
+import { Layer } from 'effect'
+import { FetchHttpClient } from 'effect/unstable/http'
+
+const observation = RemoteObservation.layer(
+  TempoTraceStore.source({ baseUrl: 'http://127.0.0.1:3200' }),
+  { interval: '50 millis', settle: '500 millis', timeout: '10 seconds' },
+).pipe(Layer.provide(FetchHttpClient.layer))
+```
+
+`collect(traceId)` reads the source every `interval` and keeps every span it has seen, keyed by span id. It answers once no read has added a span for `settle`, because no trace store says when a trace is complete: a trace read too early looks finished but is missing spans still in flight. A read that returns fewer spans than an earlier one never drops a span. The whole read runs under `timeout`, and a read still in flight at the deadline is cancelled: nothing read by then fails with `Observation.EmptyObservationError`, spans that never settled fail with `Observation.IncompleteObservationError`. A source failure fails at once, without retrying. Every duration must be positive.
+
+`TempoTraceStore.source({ baseUrl })` reads Grafana Tempo's `GET /api/v2/traces/<traceId>` once. It needs only an `HttpClient`, so auth and tenant headers go on the client you provide: `HttpClient.mapRequest(client, HttpClientRequest.setHeader('X-Scope-OrgID', tenant))`. A trace Tempo marks `PARTIAL` fails with `Observation.IncompleteObservationError`; a non-2xx answer, including `404`, or a body that does not decode fails with `Observation.TransportObservationError`.
+
+Another store needs only another source: a `RemoteObservation.TraceSource<R>` is one read that answers the spans the store holds for a trace id now — empty when it holds none — or fails with `Observation.TransportObservationError` or `Observation.IncompleteObservationError`. It never polls, waits, or retries; the layer owns the cadence.
+
 ## Relations
 
 `Rel.exists`, `Rel.absent`, `Rel.unique`, `Rel.child`, `Rel.descendant`, `Rel.status`, `Rel.errorType`, `Rel.attrs`, `Rel.durationLessThan`, `Rel.forall`, `Rel.event`, `Rel.order`, `Rel.any`, `Rel.not`, `Rel.soft`, `Rel.all`, `Rel.fromTaxonomy`.

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-import { Context, Effect, FileSystem, Layer, Result, Schema } from "effect";
+import { Context, Duration, Effect, FileSystem, Layer, Result, Schema } from "effect";
 import { Pipeable } from "effect/Pipeable";
 import { Span, Taxonomy } from "@systemfsoftware/trace-taxonomy";
+import * as HttpClient from "effect/unstable/http/HttpClient";
 import * as OtelTracer from "@effect/opentelemetry/OtelTracer";
 import { BasicTracerProvider, InMemorySpanExporter } from "@opentelemetry/sdk-trace-base";
 import { Suite } from "@systemfsoftware/effect-spec-runtime";
@@ -23,6 +24,14 @@ declare const EmptyObservationError_base: Schema.Class<EmptyObservationError, Sc
 }>, import("effect/Cause").YieldableError>;
 declare class EmptyObservationError extends EmptyObservationError_base {}
 //#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 detail: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+declare class IncompleteObservationError extends IncompleteObservationError_base {}
+//#endregion
 //#region src/TraceGraph.schema.d.ts
 declare const Status: Schema.Literals<readonly ["ok", "unset", "error"]>;
 type Status = typeof Status.Type;
@@ -127,11 +136,20 @@ declare const decode: {
   (spans: ReadonlyArray<SpanRecord>, taxonomy: Taxonomy.Taxonomy): (traceId: string) => Result.Result<TraceGraph, ContractDecodeError>;
   (traceId: string, spans: ReadonlyArray<SpanRecord>, taxonomy: Taxonomy.Taxonomy): Result.Result<TraceGraph, ContractDecodeError>;
 };
+//#endregion
+//#region src/TransportObservationError.schema.d.ts
+declare const TransportObservationError_base: Schema.Class<TransportObservationError, Schema.TaggedStruct<"TransportObservationError", {
+  readonly traceId: Schema.String;
+  readonly source: Schema.String;
+  readonly detail: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+declare class TransportObservationError extends TransportObservationError_base {}
 declare namespace Observation_service_d_exports {
-  export { Collector, EmptyObservationError, Observation };
+  export { Collector, EmptyObservationError, IncompleteObservationError, Observation, ObservationFailure, TransportObservationError };
 }
+type ObservationFailure = EmptyObservationError | IncompleteObservationError | TransportObservationError;
 interface Collector {
-  readonly collect: (traceId: string) => Effect.Effect<ReadonlyArray<SpanRecord>, EmptyObservationError>;
+  readonly collect: (traceId: string) => Effect.Effect<ReadonlyArray<SpanRecord>, ObservationFailure>;
 }
 declare const Observation_base: Context.ServiceClass<Observation, "@systemfsoftware/trace-spec/Observation", Collector>;
 declare class Observation extends Observation_base {}
@@ -252,7 +270,7 @@ declare const TraceDisparityError_base: Schema.Class<TraceDisparityError, Schema
 }>, 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, JudgeFailure, Judgment, Services, Stimulated, TraceDisparityError, TypeId$3 as TypeId, check, holds, judge, of, stimulate };
+  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 };
 }
 declare const TypeId$3: unique symbol;
 type TypeId$3 = typeof TypeId$3;
@@ -290,7 +308,7 @@ interface Judgment<Input, Output> {
 interface CheckOptions {
   readonly dumpName?: string | undefined;
 }
-type JudgeFailure<E> = E | ContractDecodeError | EmptyObservationError;
+type JudgeFailure<E> = E | ContractDecodeError | ObservationFailure;
 type CheckFailure<E> = JudgeFailure<E> | TraceDisparityError;
 type Services<R> = R | Observation | FileSystem.FileSystem;
 declare const judge: {
@@ -301,6 +319,46 @@ 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>>;
 };
+declare namespace RemoteObservation_d_exports {
+  export { Options, TraceSource, layer };
+}
+/**
+ * The cadence of the poll, the quiet window the observed span set must hold
+ * before the read is trusted, and the deadline the whole poll runs under.
+ * Durations are refused unless they are positive, at layer construction.
+ */
+interface Options {
+  readonly interval: Duration.Input;
+  readonly settle: Duration.Input;
+  readonly timeout: Duration.Input;
+}
+/**
+ * One read against one store: the spans that store currently holds for a trace
+ * id, or the store's own transport or unfinished answer. A source never polls,
+ * waits, or retries — the cadence belongs to {@link layer}.
+ */
+type TraceSource<R> = (traceId: string) => Effect.Effect<ReadonlyArray<SpanRecord>, IncompleteObservationError | TransportObservationError, R>;
+/**
+ * The `Observation` service over one trace source. `collect` reads the source at
+ * `options.interval`, keeps every span it has seen keyed by span id, and answers
+ * when that union has stayed unchanged for `options.settle`; a trace the store
+ * never served is `EmptyObservationError`, one that never settled is
+ * `IncompleteObservationError`, and the source's own failure ends the poll
+ * immediately, unchanged. Provides `Observation` alone and requires exactly what
+ * the source requires (`Scope.Scope` is supplied by the layer machinery, as
+ * every Effect layer constructor scopes it away).
+ */
+declare const layer: {
+  (options: Options): <R>(source: TraceSource<R>) => Layer.Layer<Observation, never, Exclude<R, Scope.Scope>>;
+  <R>(source: TraceSource<R>, options: Options): Layer.Layer<Observation, never, Exclude<R, Scope.Scope>>;
+};
+declare namespace tempo_trace_store_d_exports {
+  export { source };
+}
+/** One read against one Tempo endpoint. Its only requirement is the caller's HTTP client. */
+declare const source: (options: {
+  readonly baseUrl: string;
+}) => TraceSource<HttpClient.HttpClient>;
 //#endregion
 //#region src/ObservationWindowSpec.schema.d.ts
 declare const ObservationWindowSpec_base: Schema.Class<ObservationWindowSpec, Schema.Struct<{
@@ -341,6 +399,10 @@ interface ObservationWindowResource extends Pipeable {
 }
 declare const make$1: (serviceName: string) => ObservationWindowResource;
 //#endregion
+//#region src/HarnessFailure.schema.d.ts
+declare const HarnessFailure: Schema.Union<readonly [typeof ContractDecodeError, typeof EmptyObservationError, typeof IncompleteObservationError, typeof TransportObservationError, typeof TraceDisparityError]>;
+type HarnessFailure = typeof HarnessFailure.Type;
+//#endregion
 //#region src/StimulusFailure.schema.d.ts
 declare const StimulusFailure_base: Schema.Class<StimulusFailure, Schema.TaggedStruct<"StimulusFailure", {
   readonly stimulus: Schema.String;
@@ -352,7 +414,7 @@ declare namespace Suite_d_exports {
 }
 declare const TypeId: unique symbol;
 type TypeId = typeof TypeId;
-type CaseFailure = ContractDecodeError | EmptyObservationError | TraceDisparityError | StimulusFailure;
+type CaseFailure = HarnessFailure | StimulusFailure;
 type Harness = Observation | FileSystem.FileSystem;
 type ArbitraryInput<Input> = Schema.Schema<Input> | Arbitrary.Arbitrary<Input>;
 interface CaseRegistrar<Provided> {
@@ -385,4 +447,4 @@ declare const withScenarioLayer: {
 };
 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_resource_d_exports as ObservationWindow, Rel_d_exports as Rel, Stimulus_d_exports as Stimulus, Suite_d_exports as Suite };
+export { Contract_d_exports as Contract, Graph_d_exports as Graph, Observation_service_d_exports as Observation, observation_window_resource_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,9 +1,12 @@
 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 { Array as Array$1, Cause, Clock, Context, Duration, Effect, Encoding, Equal, FileSystem, Layer, Match, Option, Predicate, 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 * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
 import * as OtelTracer from "@effect/opentelemetry/OtelTracer";
 import * as OtelResource from "@effect/opentelemetry/Resource";
 import { SpanStatusCode } from "@opentelemetry/api";
@@ -221,10 +224,26 @@ const decodeImpl = (traceId, spans, taxonomy) => {
 */
 const decode = dual(3, decodeImpl);
 //#endregion
+//#region src/IncompleteObservationError.schema.ts
+var IncompleteObservationError = class extends Schema.TaggedError()("IncompleteObservationError", {
+	traceId: Schema.String,
+	spanCount: Schema.Finite,
+	detail: Schema.String
+}) {};
+//#endregion
+//#region src/TransportObservationError.schema.ts
+var TransportObservationError = class extends Schema.TaggedError()("TransportObservationError", {
+	traceId: Schema.String,
+	source: Schema.String,
+	detail: Schema.String
+}) {};
+//#endregion
 //#region src/Observation.service.ts
 var Observation_service_exports = /* @__PURE__ */ __exportAll({
 	EmptyObservationError: () => EmptyObservationError,
-	Observation: () => Observation
+	IncompleteObservationError: () => IncompleteObservationError,
+	Observation: () => Observation,
+	TransportObservationError: () => TransportObservationError
 });
 var Observation = class extends Context.Service()("@systemfsoftware/trace-spec/Observation") {};
 //#endregion
@@ -240,7 +259,9 @@ var TraceDisparityError = class extends Schema.TaggedError()("TraceDisparityErro
 var Contract_exports = /* @__PURE__ */ __exportAll({
 	ContractDecodeError: () => ContractDecodeError,
 	EmptyObservationError: () => EmptyObservationError,
+	IncompleteObservationError: () => IncompleteObservationError,
 	TraceDisparityError: () => TraceDisparityError,
+	TransportObservationError: () => TransportObservationError,
 	TypeId: () => TypeId$3,
 	check: () => check,
 	holds: () => holds,
@@ -308,6 +329,219 @@ const refuseBreak = (relationId, judgment) => Match.value(judgment.verdict).pipe
 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/drivers/tempo-trace.schema.ts
+/** Proto bytes (base64 on the wire) as the lowercase hex ids traces are addressed by. */
+const HexId = Schema.Uint8ArrayFromBase64.pipe(Schema.decodeTo(Schema.String, {
+	decode: SchemaGetter.transform(Encoding.encodeHex),
+	encode: SchemaGetter.decodeHex()
+}));
+const secondsAndNanos = (nanos) => {
+	const text = nanos.padStart(10, "0");
+	return [Number(text.slice(0, -9)), Number(text.slice(-9))];
+};
+const millisOf$2 = (nanos) => {
+	const [seconds, subMillis] = secondsAndNanos(nanos);
+	return seconds * 1e3 + subMillis / 1e6;
+};
+const MillisFromNanos = Schema.String.pipe(Schema.decodeTo(Schema.Finite, SchemaTransformation.transform({
+	decode: millisOf$2,
+	encode: (millis) => String(Math.round(millis * 1e6))
+})));
+const unsetParent = (parent) => parent === "" || /^0+$/.test(parent);
+const heldParent = (parent) => unsetParent(parent) ? null : parent;
+const parentOf$1 = (parent) => heldParent(parent ?? "");
+const EMPTY_STATUS = {};
+const codeOf = (status) => status.code ?? "STATUS_CODE_UNSET";
+const STATUS_BY_CODE$1 = {
+	STATUS_CODE_UNSET: "unset",
+	STATUS_CODE_OK: "ok",
+	STATUS_CODE_ERROR: "error"
+};
+const statusOf$1 = (status) => STATUS_BY_CODE$1[codeOf(status ?? EMPTY_STATUS)];
+const stringValueOf = (value) => value.stringValue ?? null;
+const numberOf = (value) => value.doubleValue ?? intToNumber(value.intValue);
+const intToNumber = (text) => text === void 0 ? null : Number(text);
+const boolOrNumberOf = (value) => value.boolValue ?? numberOf(value);
+const scalarOf = (value) => stringValueOf(value) ?? boolOrNumberOf(value);
+const isScalarMember = (member) => member !== null;
+const arrayValuesOf = (value) => value.arrayValue?.values;
+const scalarMembersOf = (values) => values.map(scalarOf).filter(isScalarMember);
+const arrayValueOf = (values) => values === void 0 ? null : scalarMembersOf(values);
+const presentValueOf = (value) => scalarOf(value) ?? arrayValueOf(arrayValuesOf(value));
+const isPresent$1 = (entry) => entry[1] !== null;
+const entryOf = (attribute) => [attribute.key, attributeValueOf(attribute.value)];
+const attributeValueOf = (value) => value === void 0 ? null : presentValueOf(value);
+const attributesOf = (attributes) => Object.fromEntries((attributes ?? []).map(entryOf).filter(isPresent$1));
+const errorTypeOf$1 = (attributes) => {
+	const value = attributes["error.type"];
+	return typeof value === "string" ? value : null;
+};
+const eventOf = (event) => ({
+	name: event.name,
+	attributes: attributesOf(event.attributes)
+});
+const linkIdOf = (id) => id ?? "";
+const linkOf = (link) => ({
+	traceId: linkIdOf(link.traceId),
+	spanId: linkIdOf(link.spanId)
+});
+const eventsOf$1 = (span) => (span.events ?? []).map(eventOf);
+const linksOf$1 = (span) => (span.links ?? []).map(linkOf);
+const spanRecordOf$1 = (span) => {
+	const attributes = attributesOf(span.attributes);
+	return {
+		traceId: span.traceId,
+		spanId: span.spanId,
+		parentSpanId: parentOf$1(span.parentSpanId),
+		name: span.name,
+		status: statusOf$1(span.status),
+		errorType: errorTypeOf$1(attributes),
+		startMillis: span.startTimeUnixNano,
+		durationMillis: span.endTimeUnixNano - span.startTimeUnixNano,
+		attributes,
+		events: eventsOf$1(span),
+		links: linksOf$1(span)
+	};
+};
+const wireTextOf = (value) => typeof value === "string" ? { stringValue: value } : void 0;
+const wireBoolOf = (value) => typeof value === "boolean" ? { boolValue: value } : void 0;
+const isValueArray = (value) => Array.isArray(value);
+const wireArrayOf = (value) => ({ arrayValue: { values: isValueArray(value) ? value.map(wireValueOf) : [] } });
+const wireNumberOrArrayOf = (value) => typeof value === "number" ? { doubleValue: value } : wireArrayOf(value);
+const wireBoolOrNumberOf = (value) => wireBoolOf(value) ?? wireNumberOrArrayOf(value);
+const wireValueOf = (value) => wireTextOf(value) ?? wireBoolOrNumberOf(value);
+const wireAttributesOf = (attributes) => Object.entries(attributes).map(([key, value]) => ({
+	key,
+	value: wireValueOf(value)
+}));
+const STATUS_CODE_BY_STATUS = {
+	unset: "STATUS_CODE_UNSET",
+	ok: "STATUS_CODE_OK",
+	error: "STATUS_CODE_ERROR"
+};
+const wireStatusOf = (status) => ({ code: STATUS_CODE_BY_STATUS[status] });
+const wireSpanOf = (record) => ({
+	traceId: record.traceId,
+	spanId: record.spanId,
+	parentSpanId: record.parentSpanId ?? void 0,
+	name: record.name,
+	startTimeUnixNano: record.startMillis,
+	endTimeUnixNano: record.startMillis + record.durationMillis,
+	attributes: wireAttributesOf(record.attributes),
+	events: record.events.map((event) => ({
+		name: event.name,
+		attributes: wireAttributesOf(event.attributes)
+	})),
+	links: record.links.map((link) => ({
+		traceId: link.traceId,
+		spanId: link.spanId
+	})),
+	status: wireStatusOf(record.status)
+});
+const WireAnyValue = Schema.Struct({
+	stringValue: Schema.optional(Schema.String),
+	boolValue: Schema.optional(Schema.Boolean),
+	intValue: Schema.optional(Schema.String),
+	doubleValue: Schema.optional(Schema.Finite),
+	arrayValue: Schema.optional(Schema.Struct({ values: Schema.optional(Schema.Array(Schema.suspend(() => WireAnyValue))) }))
+});
+const WireAttribute = Schema.Struct({
+	key: Schema.String,
+	value: Schema.optional(WireAnyValue)
+});
+const WireStatus = Schema.Struct({
+	message: Schema.optional(Schema.String),
+	code: Schema.optional(Schema.Literals([
+		"STATUS_CODE_UNSET",
+		"STATUS_CODE_OK",
+		"STATUS_CODE_ERROR"
+	]))
+});
+const WireEvent = Schema.Struct({
+	name: Schema.String,
+	timeUnixNano: Schema.optional(MillisFromNanos),
+	attributes: Schema.optional(Schema.Array(WireAttribute))
+});
+const WireLink = Schema.Struct({
+	traceId: Schema.optional(HexId),
+	spanId: Schema.optional(HexId)
+});
+const WireSpan = Schema.Struct({
+	traceId: HexId,
+	spanId: HexId,
+	parentSpanId: Schema.optional(HexId),
+	name: Schema.String,
+	kind: Schema.optional(Schema.String),
+	startTimeUnixNano: MillisFromNanos,
+	endTimeUnixNano: MillisFromNanos,
+	attributes: Schema.optional(Schema.Array(WireAttribute)),
+	events: Schema.optional(Schema.Array(WireEvent)),
+	links: Schema.optional(Schema.Array(WireLink)),
+	status: Schema.optional(WireStatus),
+	traceState: Schema.optional(Schema.String),
+	flags: Schema.optional(Schema.Finite)
+}).pipe(Schema.decodeTo(SpanRecord, SchemaTransformation.transform({
+	decode: spanRecordOf$1,
+	encode: wireSpanOf
+})));
+const WireScopeSpans = Schema.Struct({ spans: Schema.optional(Schema.Array(WireSpan)) });
+const WireResourceSpans = Schema.Struct({ scopeSpans: Schema.optional(Schema.Array(WireScopeSpans)) });
+/** One trace-by-id answer: the spans, plus the store's completeness status when it is not complete. */
+const TempoV2TraceResponse = Schema.Struct({
+	trace: Schema.Struct({ resourceSpans: Schema.optional(Schema.Array(WireResourceSpans)) }),
+	status: Schema.optional(Schema.String),
+	message: Schema.optional(Schema.String)
+});
+//#endregion
+//#region src/drivers/tempo-trace-store.ts
+var tempo_trace_store_exports = /* @__PURE__ */ __exportAll({ source: () => source });
+/**
+* The Grafana Tempo trace source: one read of one trace by id against one
+* store endpoint. It never polls, waits, or retries — completeness belongs
+* to the remote observation layer. Any refusal (unreachable endpoint,
+* non-2xx answer, undecodable body) fails with the transport failure whose
+* `source` is the request URL; an answer the store marked incomplete fails
+* with the incomplete failure, since waiting cannot complete it.
+*/
+const parseBody = Schema.decodeResult(Schema.fromJsonString(TempoV2TraceResponse));
+const orEmpty = (values) => values ?? [];
+const resourceSpansOf = (response) => orEmpty(response.trace.resourceSpans);
+const scopeSpansOf = (resourceSpans) => orEmpty(resourceSpans.scopeSpans);
+const spansOfScope = (scopeSpans) => orEmpty(scopeSpans.spans);
+const spansOf = (response) => resourceSpansOf(response).flatMap((resourceSpans) => scopeSpansOf(resourceSpans).flatMap(spansOfScope));
+const transportFailureOf = (traceId, url, cause) => new TransportObservationError({
+	traceId,
+	source: url,
+	detail: cause
+});
+const refusedOf = (traceId, url, error) => transportFailureOf(traceId, url, error.message);
+const undecodableOf = (traceId, url, error) => transportFailureOf(traceId, url, `undecodable trace body: ${error.message}`);
+const incompleteOf = (traceId, status, spanCount) => new IncompleteObservationError({
+	traceId,
+	spanCount,
+	detail: `the store answered ${status}: waiting cannot complete the trace`
+});
+const isComplete = (status) => status === void 0 || status === "COMPLETE";
+const markedOf = (response) => response.status ?? "INCOMPLETE";
+const recordsOf$1 = (traceId, response) => {
+	const spans = spansOf(response);
+	return isComplete(response.status) ? Effect.succeed(spans) : Effect.fail(incompleteOf(traceId, markedOf(response), spans.length));
+};
+const readTrace = (traceId, url, body) => {
+	const decoded = parseBody(body);
+	return Result.isFailure(decoded) ? Effect.fail(undecodableOf(traceId, url, decoded.failure)) : recordsOf$1(traceId, decoded.success);
+};
+/** One read against one Tempo endpoint. Its only requirement is the caller's HTTP client. */
+const source = (options) => {
+	const urlOf = (traceId) => `${options.baseUrl}/api/v2/traces/${traceId}`;
+	return (traceId) => {
+		const url = urlOf(traceId);
+		return HttpClient.execute(HttpClientRequest.get(url).pipe(HttpClientRequest.acceptJson)).pipe(Effect.flatMap(HttpClientResponse.filterStatusOk), Effect.flatMap((response) => response.text), Effect.mapError((error) => refusedOf(traceId, url, error)), Effect.flatMap((body) => readTrace(traceId, url, body)));
+	};
+};
+Schema.decodeEffect(HexId);
+Schema.encodeEffect(HexId);
+//#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");
@@ -361,7 +595,7 @@ 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 millisOf$1 = (duration) => duration[0] * 1e3 + duration[1] / 1e6;
 const spanRecordOf = (span) => {
 	const attributes = attributeRecordOf(span.attributes);
 	return {
@@ -371,8 +605,8 @@ const spanRecordOf = (span) => {
 		name: span.name,
 		status: statusOf(span.status.code),
 		errorType: errorTypeOf(attributes),
-		startMillis: millisOf(span.startTime),
-		durationMillis: millisOf(span.duration),
+		startMillis: millisOf$1(span.startTime),
+		durationMillis: millisOf$1(span.duration),
 		attributes,
 		events: eventsOf(span),
 		links: linksOf(span)
@@ -402,7 +636,7 @@ var observation_window_resource_exports = /* @__PURE__ */ __exportAll({
 });
 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 layer$1 = (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,
@@ -410,7 +644,7 @@ const makeProto = (spec) => ({
 		return scoped(spec);
 	},
 	get layer() {
-		return layer(spec);
+		return layer$1(spec);
 	},
 	...Prototype
 });
@@ -449,7 +683,7 @@ 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({
+const verdictOf$1 = (options) => options.holds ? Hold.make({
 	conjunct: options.id,
 	inspected: options.inspected
 }) : Break.make({
@@ -463,7 +697,7 @@ const declared = (declaration) => relation({
 	softenable: declaration.softenable,
 	evaluate: (graph) => {
 		const inspected = declaration.spans.flatMap((span) => inspectedOf(byId(graph, span)));
-		return verdictOf({
+		return verdictOf$1({
 			id: declaration.id,
 			inspected,
 			holds: declaration.holds(graph),
@@ -576,7 +810,7 @@ const forallImpl = (spec, predicate, detail) => {
 		softenable: true,
 		evaluate: (graph) => {
 			const nodes = matchedNodes(graph, spec);
-			return verdictOf({
+			return verdictOf$1({
 				id,
 				inspected: inspectedOf(nodes),
 				holds: matchedAll(nodes, predicate),
@@ -667,7 +901,7 @@ const placementOf = (edge) => {
 		evaluate: (graph) => {
 			const placed = matchedNodes(graph, edge.child);
 			const reached = REACH_BY_RELATION[edge.relation](graph, matchedNodes(graph, edge.parent));
-			return verdictOf({
+			return verdictOf$1({
 				id,
 				inspected: inspectedOf(placed),
 				holds: placed.every((node) => reached.has(node.spanId)),
@@ -689,6 +923,120 @@ const fromTaxonomyImpl = (taxonomy, options) => combined({
 });
 const fromTaxonomy = dual(2, fromTaxonomyImpl);
 //#endregion
+//#region src/RemoteObservation.ts
+var RemoteObservation_exports = /* @__PURE__ */ __exportAll({ layer: () => layer });
+const NEVER_READ = {
+	spans: [],
+	addedAtMillis: 0
+};
+const idOf = (span) => span.spanId;
+const sameId = (left, right) => left.spanId === right.spanId;
+const idsOf = (spans) => new Set(spans.map(idOf));
+const firstOfEachId = (read) => Array$1.dedupeWith(read, sameId);
+const freshOf = (settlement, read) => {
+	const known = idsOf(settlement.spans);
+	return firstOfEachId(read).filter((span) => !known.has(span.spanId));
+};
+const absorbed = (settlement, read, elapsedMillis) => {
+	const fresh = freshOf(settlement, read);
+	return fresh.length === 0 ? settlement : {
+		spans: [...settlement.spans, ...fresh],
+		addedAtMillis: elapsedMillis
+	};
+};
+const quietForLongEnough = (settlement, elapsedMillis, windows) => settlement.spans.length > 0 && elapsedMillis - settlement.addedAtMillis >= windows.settleMillis;
+const pastDeadline = (elapsedMillis, windows) => elapsedMillis >= windows.timeoutMillis;
+const settledVerdict = (spans) => Option.some(Result.succeed(spans));
+const refusedVerdict = (refusal) => Option.some(Result.fail(refusal));
+const verdictOf = (settlement, elapsedMillis, windows) => Match.value({
+	quiet: quietForLongEnough(settlement, elapsedMillis, windows),
+	vacant: settlement.spans.length === 0,
+	late: pastDeadline(elapsedMillis, windows)
+}).pipe(Match.when({ quiet: true }, () => settledVerdict(settlement.spans)), Match.when({
+	vacant: true,
+	late: true
+}, () => refusedVerdict("absent")), Match.when({ late: true }, () => refusedVerdict("unfinished")), Match.orElse(() => Option.none()));
+const settleStep = (settlement, read, elapsedMillis, windows) => {
+	const advanced = absorbed(settlement, read, elapsedMillis);
+	return {
+		settlement: advanced,
+		verdict: verdictOf(advanced, elapsedMillis, windows)
+	};
+};
+const lateRefusal = (settlement) => settlement.spans.length === 0 ? "absent" : "unfinished";
+const deadlineVerdict = (settlement, elapsedMillis, windows) => pastDeadline(elapsedMillis, windows) ? refusedVerdict(lateRefusal(settlement)) : Option.none();
+const millisOf = (input) => Duration.toMillis(input);
+const windowsOf = (options) => ({
+	settleMillis: millisOf(options.settle),
+	timeoutMillis: millisOf(options.timeout)
+});
+const nonPositive = (options) => [
+	options.interval,
+	options.settle,
+	options.timeout
+].some((input) => millisOf(input) <= 0);
+const requirePositive = (options) => nonPositive(options) ? Effect.die(/* @__PURE__ */ new Error(`remote observation durations must be positive milliseconds: interval=${millisOf(options.interval)}, settle=${millisOf(options.settle)}, timeout=${millisOf(options.timeout)}`)) : Effect.void;
+const absence = (traceId, windows) => new EmptyObservationError({
+	traceId,
+	detail: `the remote trace store served no span for trace ${traceId} before the ${windows.timeoutMillis}ms timeout`
+});
+const incompleteness = (traceId, spans, windows) => new IncompleteObservationError({
+	traceId,
+	spanCount: spans.length,
+	detail: `the remote trace store served ${spans.length} span(s) for trace ${traceId}, which never stayed unchanged for ${windows.settleMillis}ms before the ${windows.timeoutMillis}ms timeout`
+});
+const answer = (verdict, settlement, traceId, windows) => Result.match(verdict, {
+	onSuccess: (spans) => Effect.succeed(spans),
+	onFailure: (refusal) => refusal === "absent" ? Effect.fail(absence(traceId, windows)) : Effect.fail(incompleteness(traceId, settlement.spans, windows))
+});
+const watching = (windows) => Effect.gen(function* () {
+	const startedAtMillis = yield* Clock.currentTimeMillis;
+	return {
+		settlement: yield* Ref.make(NEVER_READ),
+		windows,
+		startedAtMillis
+	};
+});
+const advanceAt = (watch, read) => Effect.gen(function* () {
+	const elapsedMillis = (yield* Clock.currentTimeMillis) - watch.startedAtMillis;
+	return settleStep(yield* Ref.get(watch.settlement), read, elapsedMillis, watch.windows);
+});
+const elapsedFor = (watch) => Effect.map(Clock.currentTimeMillis, (now) => now - watch.startedAtMillis);
+const poll = (source, traceId, options, watch) => Effect.gen(function* () {
+	const settlement = yield* Ref.get(watch.settlement);
+	const elapsedMillis = yield* elapsedFor(watch);
+	return yield* Option.match(deadlineVerdict(settlement, elapsedMillis, watch.windows), {
+		onNone: () => readOnce(source, traceId, options, watch, watch.windows.timeoutMillis - elapsedMillis),
+		onSome: (reached) => answer(reached, settlement, traceId, watch.windows)
+	});
+});
+const overdue = (traceId, watch) => Effect.flatMap(Ref.get(watch.settlement), (settlement) => answer(Result.fail(lateRefusal(settlement)), settlement, traceId, watch.windows));
+const readOnce = (source, traceId, options, watch, remainingMillis) => Effect.flatMap(Effect.timeoutOption(source(traceId), remainingMillis), (answered) => Option.match(answered, {
+	onNone: () => overdue(traceId, watch),
+	onSome: (read) => judgeRead(source, traceId, options, watch, read)
+}));
+const judgeRead = (source, traceId, options, watch, read) => Effect.flatMap(advanceAt(watch, read), (advance) => Option.match(advance.verdict, {
+	onNone: () => keepPolling(source, traceId, options, watch, advance),
+	onSome: (verdict) => answer(verdict, advance.settlement, traceId, watch.windows)
+}));
+const keepPolling = (source, traceId, options, watch, advance) => Effect.gen(function* () {
+	yield* Ref.set(watch.settlement, advance.settlement);
+	yield* Effect.sleep(options.interval);
+	return yield* Effect.suspend(() => poll(source, traceId, options, watch));
+});
+const collector = (source, options, context) => ({ collect: (traceId) => Effect.flatMap(watching(windowsOf(options)), (watch) => poll(source, traceId, options, watch)).pipe(Effect.provideContext(context)) });
+/**
+* The `Observation` service over one trace source. `collect` reads the source at
+* `options.interval`, keeps every span it has seen keyed by span id, and answers
+* when that union has stayed unchanged for `options.settle`; a trace the store
+* never served is `EmptyObservationError`, one that never settled is
+* `IncompleteObservationError`, and the source's own failure ends the poll
+* immediately, unchanged. Provides `Observation` alone and requires exactly what
+* the source requires (`Scope.Scope` is supplied by the layer machinery, as
+* every Effect layer constructor scopes it away).
+*/
+const layer = dual(2, (source, options) => Layer.effectContext(Effect.map(Effect.andThen(requirePositive(options), Effect.context()), (context) => Context.make(Observation, collector(source, options, context)))));
+//#endregion
 //#region src/Stimulus.ts
 var Stimulus_exports = /* @__PURE__ */ __exportAll({
 	make: () => make$1,
@@ -727,6 +1075,15 @@ const make$1 = (options) => {
 	return stimulus;
 };
 //#endregion
+//#region src/HarnessFailure.schema.ts
+const HarnessFailure = Schema.Union([
+	ContractDecodeError,
+	EmptyObservationError,
+	IncompleteObservationError,
+	TransportObservationError,
+	TraceDisparityError
+]);
+//#endregion
 //#region src/Prop.ts
 const isHold = Schema.is(Hold);
 const isBreak = Schema.is(Break);
@@ -778,12 +1135,8 @@ var Suite_exports = /* @__PURE__ */ __exportAll({
 	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({
+const isHarnessFailure = Schema.is(HarnessFailure);
+const caseFailureOf = (stimulus) => (failure) => isHarnessFailure(failure) ? failure : new StimulusFailure({
 	stimulus,
 	detail: Cause.pretty(Cause.fail(failure))
 });
@@ -828,4 +1181,4 @@ const make = (bindings) => (name) => ({
 	...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 };
+export { Contract_exports as Contract, Graph_exports as Graph, Observation_service_exports as Observation, observation_window_resource_exports as ObservationWindow, Rel_exports as Rel, RemoteObservation_exports as RemoteObservation, Stimulus_exports as Stimulus, Suite_exports as Suite, tempo_trace_store_exports as TempoTraceStore };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@systemfsoftware/trace-spec",
   "license": "Apache-2.0",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "author": "Ryan Lee <drdgvhbh@gmail.com>",
   "repository": {
     "type": "git",
@@ -33,25 +33,25 @@
     "dist"
   ],
   "dependencies": {
-    "@effect/opentelemetry": "4.0.0-rc.116",
+    "@effect/opentelemetry": "4.0.0-rc.117",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/resources": "^2",
     "@opentelemetry/sdk-trace-base": "^2",
     "@opentelemetry/semantic-conventions": "^1.33",
-    "@systemfsoftware/effect-spec-runtime": "^0.1.0",
-    "@systemfsoftware/trace-taxonomy": "^0.0.0"
+    "@systemfsoftware/effect-spec-runtime": "^0.1.1",
+    "@systemfsoftware/trace-taxonomy": "^0.0.1"
   },
   "devDependencies": {
-    "@effect/platform-node": "4.0.0-rc.116",
-    "@effect/vitest": "4.0.0-rc.116",
+    "@effect/platform-node": "4.0.0-rc.117",
+    "@effect/vitest": "4.0.0-rc.117",
     "@systemfsoftware/arethetypeswrong-cli": "^4.2.0",
-    "@systemfsoftware/effect-gherkin-spec": "^4.3.0",
-    "@systemfsoftware/oxlint-config-recommended": "^2.0.0",
-    "@systemfsoftware/tsconfig": "^2.0.0",
+    "@systemfsoftware/effect-gherkin-spec": "^4.3.1",
+    "@systemfsoftware/oxlint-config-recommended": "^2.0.2",
+    "@systemfsoftware/tsconfig": "^2.0.1",
     "@systemfsoftware/tsdown-config": "^0.1.0",
     "@systemfsoftware/vitest-config": "^0.1.0",
     "@types/node": "^26",
-    "effect": "4.0.0-rc.116",
+    "effect": "4.0.0-rc.117",
     "oxlint": "~1.82.0",
     "rimraf": "^6.1.3",
     "tsdown": "^0.23.0",
@@ -59,8 +59,8 @@
     "vitest": "^5"
   },
   "peerDependencies": {
-    "@effect/vitest": "4.0.0-rc.116",
-    "effect": "4.0.0-rc.116",
+    "@effect/vitest": "4.0.0-rc.117",
+    "effect": "4.0.0-rc.117",
     "vitest": "^5"
   },
   "publishConfig": {