@systemfsoftware/trace-spec 0.0.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @systemfsoftware/trace-spec
+
+## 0.0.0
+
+### Minor Changes
+
+- New package: hold a behaviour to the trace it produced. `Contract.of(taxonomy).stimulate(stimulus).holds(relation)` composes a spec; `Contract.judge(contract, input)` runs the behaviour under a trace id it mints, decodes the finished trace against the taxonomy, and answers the verdict with the dump path of a break; `Contract.check` fails a break with `Contract.TraceDisparityError`. `Graph.decode` is pure, answering `Result<TraceGraph, ContractDecodeError>`.
+
+  `ObservationWindow.make(serviceName)` is the in-memory observation resource: `.scoped` acquires a window handle read with `ObservationWindow.collect`, and `.layer` provides `Observation | OtelTracer.OtelTracer`, one window per acquisition. `Suite.make({ it, layer })` registers a `Case` per input or a `Case.prop` per Schema, shrinking through `it.effect.prop` to one dump of the minimal failing input.

package/LICENSE

@@ -0,0 +1,203 @@
+Copyright (c) 2026 Ryan Lee (systemfsoftware)
+
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Ryan Lee (systemfsoftware)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,93 @@
+# @systemfsoftware/trace-spec
+
+Hold a behaviour to the trace it produced.
+
+In a system with queues, workers, and background consumers, a `200` is not the observable output of a behaviour: the response can arrive before the work fails, and the failure lands in a later span nobody is watching. The completed trace is the observable output. This package runs a behaviour under a trace id it owns, reads the finished trace back, decodes it against a declared taxonomy, and answers with a relation that holds or breaks.
+
+## Install
+
+```sh
+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`.
+
+## Write a contract
+
+A stimulus is the behaviour under test made callable: `stimulus(input)` runs it under a trace id the contract owns, injecting the matching `traceparent`. A relation is the judgement made callable: `relation(graph)` answers a verdict.
+
+```ts
+import { Contract, Rel, Stimulus } from '@systemfsoftware/trace-spec'
+import { checkout, PaymentCapture, PlaceOrder } from './checkout.schema.js'
+
+const placeOrder = Stimulus.make({
+  name: 'checkout.place',
+  run: ({ input, traceparent }) => client.place(input, { traceparent }),
+})
+
+const paymentUnderCheckout = Contract.of(checkout)
+  .stimulate(placeOrder)
+  .holds(Rel.all(
+    Rel.exists(PlaceOrder),
+    Rel.child(PlaceOrder, PaymentCapture),
+    Rel.attrs(PlaceOrder, { 'app.order.items.count': 1 }),
+  ))
+```
+
+`Contract.of(taxonomy)` takes the identity first; `Contract.stimulate` and `Contract.holds` are `dual` combinators on Pipeable stages, so the same builder composes in a pipe — `Contract.of(checkout).pipe(Contract.stimulate(placeOrder), Contract.holds(relation))` — and the stage types refuse an out-of-order builder.
+
+## 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.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                        |
+
+## Register cases
+
+```ts
+import { NodeFileSystem } from '@effect/platform-node'
+import { it, layer } from '@effect/vitest'
+import { Observation, ObservationWindow, Suite } from '@systemfsoftware/trace-spec'
+import { Layer } from 'effect'
+
+const TraceSuite = Suite.make({ it, layer })
+const harness = Layer.mergeAll(ObservationWindow.make('checkout').layer, NodeFileSystem.layer, CheckoutDoubles)
+
+TraceSuite('checkout.place_order')
+  .withScenarioLayer(harness)
+  .body(({ Case }) => {
+    Case('one item is paid for under the order', paymentUnderCheckout, { userId, items: 1 })
+  })
+```
+
+`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.
+
+`.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.
+
+`Case.prop(title, contract, schema)` runs the contract over inputs drawn from the Schema's derived arbitrary through `it.effect.prop` on the suite's runner, so shrinking is the runner's own: a failing draw fails the property and the runner reports the smallest failing input. The dump is named after the case title, so every failing draw overwrites one file and the surviving dump is the reported counterexample's evidence. When a case fails with a `Contract.TraceDisparityError`, the test carries a Vitest annotation naming that dump, so the decoded graph is found from the failing test.
+
+## Observe in memory
+
+`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.
+
+## 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`.
+
+A relation is callable: `relation(graph)` answers a `Rel.Verdict` — `Rel.Hold` or `Rel.Break` — carrying the conjunct and the span ids it inspected, so the failure output names what broke without a debugger.
+
+`Rel.forall(spec, predicate, detail)` holds when the span was emitted and every node satisfies the predicate; `Rel.event(spec, name)` when every node carries that event; `Rel.order(before, after)` when every `after` span starts at or after some `before` span. All three break when no matching span was emitted. `Rel.any(...relations)` holds when one conjunct holds and names every conjunct when none does; `Rel.not(relation)` holds when its inner relation breaks. `any` and `not` are never soft.
+
+`Rel.fromTaxonomy(taxonomy, { path })` turns the taxonomy itself into a relation: every declared edge must place each child span under a matching parent (directly for `child`, anywhere above for `descendant`), and every forbidden span must be absent unless its `unless` tag names the given path. Edges constrain placement, not existence — pair it with `Rel.exists` for the spans a scenario requires.
+
+`Rel.all` evaluates hard conjuncts in order and stops at the first hard break; soft conjuncts are all evaluated and reported together. `exists` and `absent` are never soft — a spec cannot go green while the span it is about is missing. `Rel.soft` marks a relation soft when it is softenable at all.
+
+## Assert the graph, not the tool
+
+Span names and attributes come from [`@systemfsoftware/trace-taxonomy`](../trace-taxonomy) declarations, so no spec mentions a raw span name. A renamed span or a new required attribute is a compile error at the declaration's start call sites, not a silently green suite.

package/dist/index.d.ts

@@ -0,0 +1,344 @@
+import { Context, Effect, FileSystem, Layer, Result, Schema } from "effect";
+import { Pipeable } from "effect/Pipeable";
+import { Span, Taxonomy } from "@systemfsoftware/trace-taxonomy";
+import * as OtelTracer from "@effect/opentelemetry/OtelTracer";
+import { BasicTracerProvider, InMemorySpanExporter } from "@opentelemetry/sdk-trace-base";
+import { Suite } from "@systemfsoftware/effect-spec-runtime";
+import * as Scope from "effect/Scope";
+import * as Arbitrary from "effect/unstable/arbitrary/Arbitrary";
+//#region src/ContractDecodeError.schema.d.ts
+declare const ContractDecodeError_base: Schema.Class<ContractDecodeError, Schema.TaggedStruct<"ContractDecodeError", {
+  readonly declarationId: Schema.String;
+  readonly spanName: Schema.String;
+  readonly spanId: Schema.String;
+  readonly attribute: Schema.String;
+  readonly detail: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+declare class ContractDecodeError extends ContractDecodeError_base {}
+//#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 {}
+//#endregion
+//#region src/TraceGraph.schema.d.ts
+declare const Status: Schema.Literals<readonly ["ok", "unset", "error"]>;
+type Status = typeof Status.Type;
+declare const AttributeValue: Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>]>;
+type AttributeValue = typeof AttributeValue.Type;
+declare const Attributes: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>]>>;
+type Attributes = typeof Attributes.Type;
+declare const SpanEvent: Schema.Struct<{
+  readonly name: Schema.String;
+  readonly attributes: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>]>>;
+}>;
+type SpanEvent = typeof SpanEvent.Type;
+declare const SpanLink: Schema.Struct<{
+  readonly traceId: Schema.String;
+  readonly spanId: Schema.String;
+}>;
+type SpanLink = typeof SpanLink.Type;
+declare const SpanRecord: Schema.Struct<{
+  readonly traceId: Schema.String;
+  readonly spanId: Schema.String;
+  readonly parentSpanId: Schema.NullOr<Schema.String>;
+  readonly name: Schema.String;
+  readonly status: Schema.Literals<readonly ["ok", "unset", "error"]>;
+  readonly errorType: Schema.NullOr<Schema.String>;
+  readonly startMillis: Schema.Finite;
+  readonly durationMillis: Schema.Finite;
+  readonly attributes: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>]>>;
+  readonly events: Schema.$Array<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly attributes: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>]>>;
+  }>>;
+  readonly links: Schema.$Array<Schema.Struct<{
+    readonly traceId: Schema.String;
+    readonly spanId: Schema.String;
+  }>>;
+}>;
+type SpanRecord = typeof SpanRecord.Type;
+declare const GraphNode: Schema.Struct<{
+  readonly spanId: Schema.String;
+  readonly parentSpanId: Schema.NullOr<Schema.String>;
+  readonly name: Schema.String;
+  readonly status: Schema.Literals<readonly ["ok", "unset", "error"]>;
+  readonly errorType: Schema.NullOr<Schema.String>;
+  readonly startMillis: Schema.Finite;
+  readonly durationMillis: Schema.Finite;
+  readonly attrs: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>]>>;
+  readonly events: Schema.$Array<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly attributes: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>]>>;
+  }>>;
+  readonly links: Schema.$Array<Schema.Struct<{
+    readonly traceId: Schema.String;
+    readonly spanId: Schema.String;
+  }>>;
+}>;
+type GraphNode = typeof GraphNode.Type;
+declare const TraceGraph: Schema.Struct<{
+  readonly traceId: Schema.String;
+  readonly nodes: Schema.$Array<Schema.Struct<{
+    readonly spanId: Schema.String;
+    readonly parentSpanId: Schema.NullOr<Schema.String>;
+    readonly name: Schema.String;
+    readonly status: Schema.Literals<readonly ["ok", "unset", "error"]>;
+    readonly errorType: Schema.NullOr<Schema.String>;
+    readonly startMillis: Schema.Finite;
+    readonly durationMillis: Schema.Finite;
+    readonly attrs: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>]>>;
+    readonly events: Schema.$Array<Schema.Struct<{
+      readonly name: Schema.String;
+      readonly attributes: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>]>>;
+    }>>;
+    readonly links: Schema.$Array<Schema.Struct<{
+      readonly traceId: Schema.String;
+      readonly spanId: Schema.String;
+    }>>;
+  }>>;
+}>;
+type TraceGraph = typeof TraceGraph.Type;
+declare namespace Graph_d_exports {
+  export { AttributeValue, Attributes, GraphNode, SpanEvent, SpanLink, SpanRecord, Status, TraceGraph, byId, children, decode, descendants };
+}
+declare const byId: (graph: TraceGraph, spec: Span.Span) => ReadonlyArray<GraphNode>;
+declare const children: (graph: TraceGraph, node: GraphNode) => ReadonlyArray<GraphNode>;
+declare const descendants: (graph: TraceGraph, node: GraphNode) => ReadonlyArray<GraphNode>;
+/**
+ * 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.
+ */
+declare const decode: (traceId: string, spans: ReadonlyArray<SpanRecord>, taxonomy: Taxonomy.Taxonomy) => Result.Result<TraceGraph, ContractDecodeError>;
+declare namespace Observation_service_d_exports {
+  export { Collector, EmptyObservationError, Observation };
+}
+interface Collector {
+  readonly collect: (traceId: string) => Effect.Effect<ReadonlyArray<SpanRecord>, EmptyObservationError>;
+}
+declare const Observation_base: Context.ServiceClass<Observation, "@systemfsoftware/trace-spec/Observation", Collector>;
+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", {
+  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", {
+  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 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 };
+}
+interface Relation {
+  readonly id: string;
+  readonly soft: boolean;
+  readonly softenable: boolean;
+  (graph: TraceGraph): Verdict;
+}
+declare const exists: <S extends Span.Span>(spec: S) => Relation;
+declare const absent: <S extends Span.Span>(spec: S) => Relation;
+declare const unique: <S extends Span.Span>(spec: S) => Relation;
+declare const child: (parent: Span.Span, childSpan: Span.Span) => Relation;
+declare const descendant: (parent: Span.Span, childSpan: Span.Span) => Relation;
+declare const order: (before: Span.Span, after: Span.Span) => Relation;
+declare const status: (spec: Span.Span, expected: Status) => Relation;
+declare const errorType: (spec: Span.Span, expected: string) => Relation;
+declare const attrs: <S extends Span.Span>(spec: S, partial: Partial<Span.AttrsOf<S>>) => Relation;
+declare const durationLessThan: (spec: Span.Span, millis: number) => Relation;
+declare const event: (spec: Span.Span, name: string) => Relation;
+declare const forall: (spec: Span.Span, predicate: (node: GraphNode) => boolean, detail: string) => Relation;
+declare const soft: (self: Relation) => Relation;
+declare const not: (self: Relation) => Relation;
+declare const all: (...relations: ReadonlyArray<Relation>) => Relation;
+declare const any: (...relations: ReadonlyArray<Relation>) => Relation;
+declare const fromTaxonomy: (taxonomy: Taxonomy.Taxonomy, options: {
+  readonly path: string;
+}) => Relation;
+declare namespace Stimulus_d_exports {
+  export { Run, Stimulus, TraceContext, make$3 as make, traceContext };
+}
+interface TraceContext {
+  readonly traceId: string;
+  readonly spanId: string;
+  readonly traceparent: string;
+}
+declare const traceContext: Effect.Effect<TraceContext>;
+interface Run<Input, Output> {
+  readonly input: Input;
+  readonly traceId: string;
+  readonly output: Output;
+}
+interface Stimulus<Input, Output, E, R> {
+  readonly name: string;
+  (input: Input): Effect.Effect<Run<Input, Output>, E, R>;
+}
+declare const make$3: <Input, Output, E, R>(options: {
+  readonly name: string;
+  readonly run: (context: {
+    readonly input: Input;
+    readonly traceId: string;
+    readonly traceparent: string;
+  }) => Effect.Effect<Output, E, R>;
+}) => Stimulus<Input, Output, E, R>;
+//#endregion
+//#region src/TraceDisparityError.schema.d.ts
+declare const TraceDisparityError_base: Schema.Class<TraceDisparityError, Schema.TaggedStruct<"TraceDisparityError", {
+  readonly relationId: Schema.String;
+  readonly traceId: Schema.String;
+  readonly breaks: Schema.$Array<typeof Break>;
+  readonly dumpPath: Schema.NullOr<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+declare class TraceDisparityError extends TraceDisparityError_base {}
+declare namespace Contract_d_exports {
+  export { CheckFailure, CheckOptions, Contract, ContractDecodeError, Declared$1 as Declared, EmptyObservationError, JudgeFailure, Judgment, Services, Stimulated, TraceDisparityError, TypeId$3 as TypeId, check, holds, judge, of, stimulate };
+}
+declare const TypeId$3: unique symbol;
+type TypeId$3 = typeof TypeId$3;
+interface Declared$1 extends Pipeable {
+  readonly [TypeId$3]: typeof TypeId$3;
+  readonly taxonomy: Taxonomy.Taxonomy;
+  readonly stimulate: <Input, Output, E, R>(stimulus: Stimulus<Input, Output, E, R>) => Stimulated<Input, Output, E, R>;
+}
+interface Stimulated<Input, Output, E, R> extends Pipeable {
+  readonly [TypeId$3]: typeof TypeId$3;
+  readonly taxonomy: Taxonomy.Taxonomy;
+  readonly stimulus: Stimulus<Input, Output, E, R>;
+  readonly holds: (relation: Relation) => Contract<Input, Output, E, R>;
+}
+interface Contract<Input, Output, E, R> extends Pipeable {
+  readonly [TypeId$3]: typeof TypeId$3;
+  readonly taxonomy: Taxonomy.Taxonomy;
+  readonly stimulus: Stimulus<Input, Output, E, R>;
+  readonly relation: Relation;
+}
+declare const of: (taxonomy: Taxonomy.Taxonomy) => Declared$1;
+declare const stimulate: {
+  <Input, Output, E, R>(stimulus: Stimulus<Input, Output, E, R>): (self: Declared$1) => Stimulated<Input, Output, E, R>;
+  <Input, Output, E, R>(self: Declared$1, stimulus: Stimulus<Input, Output, E, R>): Stimulated<Input, Output, E, R>;
+};
+declare const holds: {
+  (relation: Relation): <Input, Output, E, R>(self: Stimulated<Input, Output, E, R>) => Contract<Input, Output, E, R>;
+  <Input, Output, E, R>(self: Stimulated<Input, Output, E, R>, relation: Relation): Contract<Input, Output, E, R>;
+};
+interface Judgment<Input, Output> {
+  readonly run: Run<Input, Output>;
+  readonly verdict: Verdict;
+  readonly dumpPath: string | null;
+}
+interface CheckOptions {
+  readonly dumpName?: string | undefined;
+}
+type JudgeFailure<E> = E | ContractDecodeError | EmptyObservationError;
+type CheckFailure<E> = JudgeFailure<E> | TraceDisparityError;
+type Services<R> = R | Observation | FileSystem.FileSystem;
+declare const judge: {
+  <Input>(input: Input, options?: CheckOptions): <Output, E, R>(self: Contract<Input, Output, E, R>) => Effect.Effect<Judgment<Input, Output>, JudgeFailure<E>, Services<R>>;
+  <Input, Output, E, R>(self: Contract<Input, Output, E, R>, input: Input, options?: CheckOptions): Effect.Effect<Judgment<Input, Output>, JudgeFailure<E>, Services<R>>;
+};
+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>>;
+};
+//#endregion
+//#region src/ObservationWindowSpec.schema.d.ts
+declare const ObservationWindowSpec_base: Schema.Class<ObservationWindowSpec, Schema.Struct<{
+  readonly serviceName: Schema.NonEmptyString;
+}>, {}>;
+declare class ObservationWindowSpec extends ObservationWindowSpec_base {}
+declare namespace observation_window_handle_d_exports {
+  export { ObservationWindow, TypeId$2 as TypeId, collect, context, isObservationWindow, make$2 as make, shutdown };
+}
+declare const TypeId$2: unique symbol;
+type TypeId$2 = typeof TypeId$2;
+declare const ExporterId: unique symbol;
+declare const ProviderId: unique symbol;
+interface ObservationWindow extends Pipeable {
+  readonly [TypeId$2]: typeof TypeId$2;
+  readonly [ExporterId]: InMemorySpanExporter;
+  readonly [ProviderId]: BasicTracerProvider;
+  readonly serviceName: string;
+}
+declare const isObservationWindow: (u: unknown) => u is ObservationWindow;
+declare const make$2: (spec: ObservationWindowSpec) => ObservationWindow;
+declare const shutdown: (self: ObservationWindow) => Effect.Effect<void>;
+declare const collect: {
+  (traceId: string): (self: ObservationWindow) => Effect.Effect<ReadonlyArray<SpanRecord>, EmptyObservationError>;
+  (self: ObservationWindow, traceId: string): Effect.Effect<ReadonlyArray<SpanRecord>, EmptyObservationError>;
+};
+declare const context: (self: ObservationWindow) => Context.Context<Observation | OtelTracer.OtelTracerProvider>;
+declare namespace observation_window_resource_d_exports {
+  export { ObservationWindow, ObservationWindowResource, ObservationWindowSpec, TypeId$2 as ObservationWindowTypeId, TypeId$1 as TypeId, collect, isObservationWindow, make$1 as make };
+}
+declare const TypeId$1: unique symbol;
+type TypeId$1 = typeof TypeId$1;
+interface ObservationWindowResource extends Pipeable {
+  readonly [TypeId$1]: typeof TypeId$1;
+  readonly spec: ObservationWindowSpec;
+  readonly scoped: Effect.Effect<ObservationWindow, never, Scope.Scope>;
+  readonly layer: Layer.Layer<Observation | OtelTracer.OtelTracer>;
+}
+declare const make$1: (serviceName: string) => ObservationWindowResource;
+//#endregion
+//#region src/StimulusFailure.schema.d.ts
+declare const StimulusFailure_base: Schema.Class<StimulusFailure, Schema.TaggedStruct<"StimulusFailure", {
+  readonly stimulus: Schema.String;
+  readonly detail: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+declare class StimulusFailure extends StimulusFailure_base {}
+declare namespace Suite_d_exports {
+  export { ArbitraryInput, CaseFailure, CaseRegistrar, CaseTools, Declared, Harness, Opened, Shared, StimulusFailure, TypeId, make, withLayer, withScenarioLayer };
+}
+declare const TypeId: unique symbol;
+type TypeId = typeof TypeId;
+type CaseFailure = ContractDecodeError | EmptyObservationError | TraceDisparityError | StimulusFailure;
+type Harness = Observation | FileSystem.FileSystem;
+type ArbitraryInput<Input> = Schema.Schema<Input> | Arbitrary.Arbitrary<Input>;
+interface CaseRegistrar<Provided> {
+  <Input, Output, E>(name: string, contract: Contract<Input, Output, E, Provided>, input: Input): void;
+  prop: <Input, Output, E>(name: string, contract: Contract<Input, Output, E, Provided>, arbitrary: ArbitraryInput<Input>) => void;
+}
+interface CaseTools<Provided> {
+  readonly Case: CaseRegistrar<Provided>;
+}
+interface Opened<Provided> {
+  readonly body: (use: (tools: CaseTools<Provided>) => void) => void;
+}
+interface Declared extends Pipeable {
+  readonly [TypeId]: typeof TypeId;
+  readonly withLayer: <SharedProvided>(shared: Layer.Layer<SharedProvided | Harness>) => Shared<SharedProvided>;
+  readonly withScenarioLayer: <Provided>(scenario: Layer.Layer<Provided | Harness>) => Opened<Provided | Harness>;
+}
+interface Shared<SharedProvided> extends Pipeable {
+  readonly [TypeId]: typeof TypeId;
+  readonly withScenarioLayer: <Provided>(scenario: Layer.Layer<Provided | Harness, never, SharedProvided>) => Opened<Provided | SharedProvided>;
+  readonly body: (use: (tools: CaseTools<SharedProvided>) => void) => void;
+}
+declare const withLayer: {
+  <SharedProvided>(shared: Layer.Layer<SharedProvided | Harness>): (self: Declared) => Shared<SharedProvided>;
+  <SharedProvided>(self: Declared, shared: Layer.Layer<SharedProvided | Harness>): Shared<SharedProvided>;
+};
+declare const withScenarioLayer: {
+  <Provided>(scenario: Layer.Layer<Provided | Harness>): (self: Declared) => Opened<Provided | Harness>;
+  <Provided>(self: Declared, scenario: Layer.Layer<Provided | Harness>): Opened<Provided | Harness>;
+};
+declare const 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 };