@yolk-sdk/conformance 0.1.0-canary.96

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yolk SDK contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,316 @@
+# @yolk-sdk/conformance
+
+> **EXPERIMENTAL.** This package is new and its API may change in any canary release, beyond the
+> usual canary instability.
+
+A small Effect-only toolkit for recording real HTTP exchanges with outside services, replaying them
+in tests (offline, fail closed), and injecting wire faults such as mid-stream drops, truncation,
+and rate-limit responses. It also defines conformance cases (small Effect programs that each prove
+one claim about how a service really behaves on the wire) and a runner that decides which cases may
+run where and reports the results.
+
+Canary APIs are unstable. Keep all `@yolk-sdk/*` packages on the same version.
+
+## Install
+
+```bash
+pnpm add -D @yolk-sdk/conformance@canary effect@4.0.0-rc.115
+```
+
+## Subpaths
+
+There is no root export. Import an explicit subpath:
+
+| Subpath                         | Purpose                                                                                                                                          |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `@yolk-sdk/conformance/fixture` | `WireFixture` / `PortFixture` schemas and types, decoders, staleness helpers, secret scans, `redactPortPayload`, `syntheticPortCredentialParams` |
+| `@yolk-sdk/conformance/replay`  | `ReplayHttpClient.layer`, `makeReplayHttpClient`, `ReplayLedger`, `WireFault`                                                                    |
+| `@yolk-sdk/conformance/record`  | `WireRecorder.layer`, `makeRecordingHttpClient`, `makeWireFixture`                                                                               |
+| `@yolk-sdk/conformance/case`    | `defineConformanceCase`, `ConformanceCase`, `ConformanceSafety`, `expectConformance`, `expectEqual`, `ConformanceMismatch`                       |
+| `@yolk-sdk/conformance/runner`  | `runConformance`, `ConformanceTarget`, `ConformanceReport`, `conformanceSkipReason`, `formatConformanceReport`                                   |
+
+## Fixtures
+
+A `WireFixture` is plain data: an id, a `caseId`, `evidence` (`verified` for a live recording,
+`unverified` for a synthetic placeholder), a `recordedAt` date (`YYYY-MM-DD`), a synthetic
+`account` label, the `endpoint`, optional `model` / `note`, and a non-empty list of exchanges.
+Each exchange has a request (method, absolute URL, allowlisted headers, JSON or text body) and a
+response recorded losslessly in exactly one of three shapes:
+
+- `body`: the whole body as a string, when it is valid UTF-8.
+- `bodyBase64`: the whole body's exact bytes in base64, for anything else (for example a PDF).
+- `chunks`: streamed network chunks with their original boundaries. Each entry is a string when
+  that chunk is valid UTF-8 on its own (empty chunks are `""`), or `{ base64 }` holding its exact
+  bytes (for example half of a multi-byte character). Plain strings stay the common, readable case.
+
+**Fixtures must contain synthetic or scrubbed data only.** Never commit credentials, cookies,
+customer names, or real account identifiers. Run `scanFixtureForSecrets` (or build fixtures with
+`makeWireFixture`, which fails on any finding) before committing. The scan flags credential
+headers (including `x-*-token` / `x-*-key` style names), bearer tokens, common API-key prefixes,
+JWTs, private keys, credential query and form parameters, and non-empty string credential JSON
+fields (`access_token`, `client_secret`, `password`, `api_key`, `token`, ...; numeric usage
+counters such as `max_tokens` are not flagged). It covers metadata strings, URLs, headers, request
+bodies, response bodies (including decodable `bodyBase64` text), each chunk, and the reassembled
+stream, so a secret split across chunks is still found; JSON bodies and SSE `data:` payloads get
+the credential-field scan. SSE framing with CRLF, LF, or bare CR line endings is recognized. It
+reports locations, never the secret itself. The scan errs toward flagging: a field named exactly
+`token` (for example an OpenAI `logprobs` entry) is flagged, so avoid recording logprobs. The scan
+is a safety net, not a guarantee: review fixtures before publishing them.
+
+`fixtureAgeDays(fixture, now)` and `isFixtureStale(fixture, now, maxAgeDays = 30)` help hosts
+decide when a recording should be refreshed.
+
+### Port fixtures
+
+Some outside services are reached through a host-provided port rather than HTTP (for example the
+generic `EmailClient` port of `@yolk-sdk/connectors/email`, where the host speaks IMAP and SMTP).
+A `PortFixture` records one such call as plain JSON:
+
+```ts
+import type { PortFixture } from '@yolk-sdk/conformance/fixture'
+
+const listed: PortFixture = {
+  id: 'example.list.synthetic',
+  port: 'ExampleClient',
+  method: 'listItems',
+  request: { folder: 'INBOX', limit: 50 },
+  response: { items: [] }
+}
+```
+
+It carries exactly one of `response` (any JSON value) or `failure` (`{ kind: 'expected' | 'error',
+code, message, status? }`: `expected` is the port's value-level failure, `error` its typed error
+channel). Without `observed` it is a synthetic placeholder (`unverified`); `observed: { account,
+date }` records the live observation and makes it `verified` as of that date
+(`conformanceFixtureEvidence`). Record requests through `redactPortPayload`, which drops
+`credential(s)` and every credential field name at any depth (AWS-style `accessKeyId`,
+`secretAccessKey`, and `sessionToken`, camelCase or snake_case, included), and run
+`scanPortFixtureForSecrets` before committing: it applies the same token patterns and
+credential-field scan as `scanFixtureForSecrets`, flags any non-null `credential(s)` field, and
+flags credential query or form parameters inside every JSON string value, the note, and the failure
+message (a signed URL such as an S3 presigned URL). Every `name=` is found on its own, so no later
+parameter is skipped. The port scan's only exemption: the raw value, up to a structural boundary
+(`&`, `#`, whitespace, `"`, `<`, `>`, or the end; a raw `?` or `'` and encoded delimiters such as
+`%3F`, `%26`, `%23`, `%20` stay inside), percent-decoded, exactly equals that parameter's entry in
+the frozen `syntheticPortCredentialParams` (the SigV4 `x-amz-signature` and `x-amz-credential`
+placeholders). Anything else inside the value, another parameter name, or another scope is flagged;
+`scanFixtureForSecrets` exempts nothing. A placeholder written by hand in prose and followed by `.`,
+`,`, `)`, or `'` (a URL quoted in single quotes) is flagged too (fail-closed). Parameters with
+escaped names (`&amp;` before them, percent-encoded names) are not found: port owners that can meet
+them check them themselves. Replaying port fixtures is up to the port's owner (the email bridge
+ships `makeEmailReplayBackend`); the runner accepts `PortFixture`s next to `WireFixture`s for its
+fixture warnings.
+
+## Replay
+
+```ts
+import { Effect } from 'effect'
+import { HttpClient } from 'effect/unstable/http'
+import { ReplayHttpClient, ReplayLedger, WireFault } from '@yolk-sdk/conformance/replay'
+
+const program = Effect.gen(function* () {
+  const client = yield* HttpClient.HttpClient
+  // ... run the code under test against `client` ...
+  const entries = yield* (yield* ReplayLedger).entries
+  return entries
+}).pipe(
+  Effect.provide(
+    ReplayHttpClient.layer([myFixture], {
+      faults: [WireFault.StatusOnAttempt({ attempt: 1, status: 500 })]
+    })
+  )
+)
+```
+
+- Requests match by method and normalized absolute URL (hash removed, query parameters sorted).
+- Each recorded exchange is consumed once, in recorded order among exchanges with the same method
+  and URL, so create → update → read-back flows and repeated requests replay deterministically.
+- A request with no remaining match fails closed with an `HttpClientError` (`TransportError`)
+  whose message names the method and URL, never headers or body. It is still written to the ledger
+  as `unmatched`. Faults never answer such requests.
+- Replay emits exactly the recorded bytes: one `Uint8Array` per recorded chunk (including empty
+  ones), each produced only when the consumer pulls it; `bodyBase64` replays as the original bytes.
+- `ReplayLedger.entries` records every request: method, URL, headers with credentials redacted,
+  body text and parsed JSON, attempt number per method + URL, how it was answered (`matched`,
+  `injected`, `unmatched`, or `invalid`), and the tag of any fault that applied.
+  `ReplayLedger.remaining` lists recorded exchanges not consumed yet.
+
+Faults (`WireFault.*`) accept an optional `match: { method?, url? }`; `url` matches exactly after
+normalization, or as a prefix when it ends with `*`:
+
+| Fault                 | Effect                                                                                                                                                                                       |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `StatusOnAttempt`     | Answer attempt N with a status/headers/body instead of consuming the recording (500-then-success, 429 + retry). Fires only when an unconsumed recorded exchange exists for the method + URL. |
+| `FailAfterChunks`     | Emit N chunks, then fail the body stream like a dropped connection under `FetchHttpClient`.                                                                                                  |
+| `TruncateAfterChunks` | Emit N chunks, then end the body cleanly (for example without a final event).                                                                                                                |
+| `HoldAfterChunks`     | Emit N chunks, run `release`, then continue (observe progressive delivery).                                                                                                                  |
+
+Chunk faults take an optional 1-based `attempt`. A chunk fault that cannot take effect fails the
+request with an `HttpClientError` whose cause is `WireReplayInvalid` (ledger outcome `invalid`, no
+fault tag, exchange left unconsumed) instead of silently doing nothing: any chunk fault matched
+against a whole-body response, `TruncateAfterChunks` / `HoldAfterChunks` with `chunks` at or beyond
+the recorded chunk count, or `FailAfterChunks` with `chunks` beyond it. The error reason is a
+`TransportError`, which generic transient-retry policies retry; when a test runs through a retrying
+client, also assert the ledger has no `invalid` outcome so a misconfigured fault cannot be retried
+into a silent success.
+
+## Record
+
+This package **never performs network I/O itself**. For live recording, the host supplies the real
+`HttpClient` and the recorder wraps it:
+
+```ts
+import { Effect, Layer } from 'effect'
+import { FetchHttpClient } from 'effect/unstable/http'
+import { makeWireFixture, WireRecorder } from '@yolk-sdk/conformance/record'
+
+const recording = WireRecorder.layer().pipe(Layer.provide(FetchHttpClient.layer))
+
+const fixture = Effect.gen(function* () {
+  // ... run the real client code once ...
+  const exchanges = yield* (yield* WireRecorder).drain
+  return yield* makeWireFixture({
+    id: 'example.case',
+    caseId: 'example.case',
+    evidence: 'verified',
+    recordedAt: '2026-01-01',
+    account: 'synthetic',
+    endpoint: 'https://api.example.test/v1/chat',
+    exchanges
+  })
+})
+```
+
+The recorder keeps only allowlisted headers (request: `content-type`, `accept`; response:
+`content-type`, `retry-after`, `retry-after-ms`, and rate-limit headers). Credential headers such as
+`authorization`, `cookie`, `set-cookie`, and token/key-bearing names such as `x-auth-token`,
+`private-token`, or `x-*-key` are always dropped. `text/event-stream` responses are teed chunk by
+chunk without changing what the caller receives; each network chunk is recorded standalone (text
+when valid UTF-8, otherwise `{ base64 }`). Other bodies are recorded as `body` or `bodyBase64`.
+`drain` fails with `WireRecordingIncomplete` if a request failed or a body was not read to the end.
+A request still pending at `drain` time is reported by that drain and then dropped: if it finishes
+later, it never appears in, or overwrites an entry of, a later drain.
+
+Only record against accounts and data you are allowed to publish, and keep live recording out of CI.
+
+## Cases
+
+A conformance case is a small, named, pure Effect program that proves one claim about how an outside
+service really behaves on the wire, next to what its docs say. It states only what it needs (its
+`R`), so the same case runs unchanged against replayed fixtures, an in-process emulator, a local
+emulator process, or a real practice account: only the layers change.
+
+```ts
+import { Effect } from 'effect'
+import { HttpClient, HttpClientRequest } from 'effect/unstable/http'
+import { defineConformanceCase, expectEqual } from '@yolk-sdk/conformance/case'
+
+export const missingItemCase = defineConformanceCase({
+  id: 'example.items.missing',
+  safety: 'read',
+  docs: 'The docs say a missing item returns 404.',
+  wire: 'A missing item returns 404 with an empty JSON object.',
+  fixtures: ['example.items.missing.synthetic'],
+  run: Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+    const response = yield* client.execute(
+      HttpClientRequest.get('https://api.example.test/items/0')
+    )
+
+    yield* expectEqual(response.status, 404, 'expected 404 for a missing item')
+  })
+})
+```
+
+- `id` is dotted lower-case (`a-z`, `0-9`, inner hyphens; two or more segments).
+- `safety` is `read` (only reads), `write-reversible` (writes but leaves the account as it found
+  it: it creates its own records and cleans up, or the write is rejected and changes nothing), or
+  `write-irreversible` (for example sending an email; never automated against a live account).
+- `docs` is what the documentation claims; `wire` is what the wire actually does.
+- `observed` (`{ account, date }`, a synthetic account label and `YYYY-MM-DD`) records the last time
+  a person watched the claim hold against the real service. Absent means unverified.
+- `fixtures` lists the `WireFixture` ids that back replay of the case.
+- `defineConformanceCase` validates this metadata and **throws** `ConformanceCaseInvalid` for an
+  invalid definition. Cases are module-level constants, so a bad one fails when its module loads
+  rather than mid-run.
+
+`expectConformance(condition, message, details?)` and `expectEqual(actual, expected, message)`
+fail with a `ConformanceMismatch` (`message`, optional JSON `expected` / `actual`). `expectEqual`
+compares JSON values structurally (effect `Equal.equals`: array order matters, object key order
+does not). Cases may also fail with their own errors or with the errors of the ports they use.
+
+## Runner
+
+```ts
+import { Effect } from 'effect'
+import { ReplayHttpClient } from '@yolk-sdk/conformance/replay'
+import { formatConformanceReport, runConformance } from '@yolk-sdk/conformance/runner'
+
+const text = await Effect.runPromise(
+  runConformance([missingItemCase], {
+    target: { kind: 'replay' },
+    fixtures: hostFixtures,
+    layer: testCase =>
+      ReplayHttpClient.layer(hostFixtures.filter(fixture => testCase.fixtures.includes(fixture.id)))
+  }).pipe(Effect.map(formatConformanceReport))
+)
+```
+
+`hostFixtures` is a placeholder for your own fixtures.
+
+Safety policy (`conformanceSkipReason`):
+
+| Target                             | `read` | `write-reversible`                                                    | `write-irreversible`                                                    |
+| ---------------------------------- | ------ | --------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `replay`, `in-process`, `emulated` | runs   | runs                                                                  | runs                                                                    |
+| `live` (`account` required)        | runs   | runs only with `allowWrites: 'reversible'`, else `writes-not-allowed` | runs only if its exact id is in `allowIrreversible`, else `manual-only` |
+
+`allowWrites` defaults to `'none'`. `allowIrreversible` lists the exact case ids a person
+explicitly started and applies regardless of `allowWrites`. Nothing real happens on the other
+targets, so every case runs there.
+
+- `layer(testCase)` is called once per case that runs (never for skipped cases) and must provide
+  what that case needs. It is called inside the case's failure boundary and built with a fresh
+  memo map in its own scope, so state the layer allocates when it is built (replay consumption,
+  ledgers, emulator state) never leaks between cases, even if the factory returns the same `Layer`
+  value. Isolation therefore needs layers that allocate mutable state when built: a service
+  captured in a shared value (one `Layer.succeed(service, instance)` reused across cases) or
+  provided by the caller's environment is not rebuilt and stays shared. Whatever the layers still
+  need (for example a host's live `HttpClient`) becomes the requirement of the run.
+- Cases with different error and requirement types can share a run; the case type is inferred as
+  their union.
+- Each case runs under `Effect.exit`: typed failures, layer build failures, a throwing `layer`
+  factory, and defects become `failed` results and the run continues. Interruption is not captured:
+  interrupting the run, or a case interrupting itself, interrupts the whole run.
+- `concurrency` defaults to 1 (live accounts are shared); results keep case order.
+- `now` defaults to the Effect `Clock`; `maxFixtureAgeDays` defaults to 30.
+
+A `ConformanceReport` has the `target` (kind, plus `account` for live), `startedAt` (ISO), one
+result per case (`id`, `safety`, `status` `passed` / `failed` / `skipped`, `skipReason`, `failure`,
+`durationMs`, `warnings`), and a `summary` count. `failure` is `{ kind, tag?, message }` with `kind`
+`failure` or `defect`. `tag` is the error's `_tag` only when it is identifier-like
+(`^[A-Za-z][A-Za-z0-9_]*$`) and not credential-shaped. A `ConformanceMismatch` keeps its
+case-authored message with credential patterns redacted; every other failure, layer failure, and
+defect message goes through `sanitizeConformanceMessage`, a best-effort sanitizer that redacts the
+credential patterns shared with the fixture secret scan (bearer tokens, API-key prefixes, JWTs,
+credential query/form parameters and field pairs, and credential header lines such as `Cookie:`,
+`X-Api-Key:`, or `Proxy-Authorization:` to the end of the line), replaces JSON-looking spans
+(balanced `{...}` / `[...]`) with `[json]`, collapses whitespace, and caps the length at 300
+characters. Request bodies, headers, and mismatch `expected` / `actual` details are never copied
+into the report; still keep secrets out of error messages.
+
+Warnings are non-fatal and listed per case:
+
+| Warning              | When                                                                                 |
+| -------------------- | ------------------------------------------------------------------------------------ |
+| `unverified-case`    | The case has no `observed`                                                           |
+| `stale-observation`  | `observed.date` is older than `maxFixtureAgeDays` (`ageDays`)                        |
+| `unverified-fixture` | A referenced fixture has `evidence: 'unverified'`                                    |
+| `stale-fixture`      | A referenced fixture is older than `maxFixtureAgeDays` (`ageDays`)                   |
+| `missing-fixture`    | A referenced fixture id is not in `fixtures` (only checked when `fixtures` is given) |
+
+Live targets omit all fixture-level warnings (`unverified-fixture`, `stale-fixture`, and
+`missing-fixture`) because fixtures are not used live; elsewhere fixture warnings need `fixtures`.
+Case-level warnings always apply. `formatConformanceReport` prints one plain-text line per
+case (status, id, safety, skip reason or failure, warnings) and a summary line, without colors.
+`conformanceReportFailed` is true when any case failed; skipped cases never fail a report.

package/dist/case.d.mts

@@ -0,0 +1,89 @@
+import { Effect } from "effect";
+import * as Schema from "effect/Schema";
+
+//#region src/case.d.ts
+/**
+ * What a case does to the account it runs against:
+ *
+ * - `read`: only reads.
+ * - `write-reversible`: writes but leaves the account as it found it (it
+ *   creates its own records and cleans them up, or the write is rejected and
+ *   changes nothing).
+ * - `write-irreversible`: a write that cannot be undone (for example sending
+ *   an email). Never automated against a live account.
+ */
+declare const ConformanceSafety: Schema.Literals<readonly ["read", "write-reversible", "write-irreversible"]>;
+type ConformanceSafety = typeof ConformanceSafety.Type;
+/**
+ * Dotted lower-case case id: two or more segments of `a-z`, `0-9`, and inner
+ * hyphens, for example `vendor.stream.plain-text`.
+ */
+declare const ConformanceCaseId: Schema.String;
+/** When and where a person last watched the claim hold against the real service. */
+declare const ConformanceObservation: Schema.Struct<{
+  /** Synthetic account label, for example `synthetic`; never a real account name. */readonly account: Schema.NonEmptyString; /** Calendar date of the observation (`YYYY-MM-DD`, UTC). */
+  readonly date: Schema.String;
+}>;
+type ConformanceObservation = typeof ConformanceObservation.Type;
+/**
+ * One wire claim. `run` succeeds when the claim holds and fails (with a
+ * `ConformanceMismatch`, its own error, or a port's error) when it does not.
+ */
+type ConformanceCase<E = never, R = never> = {
+  /** Dotted lower-case id (see `ConformanceCaseId`). */readonly id: string;
+  readonly title?: string;
+  readonly safety: ConformanceSafety; /** What the service's documentation claims. */
+  readonly docs: string; /** What the wire actually does (the claim this case proves). */
+  readonly wire: string; /** Last live observation. Absent means the claim is unverified against the real service. */
+  readonly observed?: ConformanceObservation; /** Ids of the fixtures (`WireFixture`s or `PortFixture`s) that back replay of this case. */
+  readonly fixtures: ReadonlyArray<string>;
+  readonly run: Effect.Effect<void, E, R>;
+};
+declare const ConformanceCaseInvalid_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "ConformanceCaseInvalid";
+} & Readonly<A>;
+/**
+ * Thrown by `defineConformanceCase` for an invalid definition. A programmer
+ * error, surfaced when the defining module loads (like `makeTool`).
+ */
+declare class ConformanceCaseInvalid extends ConformanceCaseInvalid_base<{
+  readonly caseId: string;
+  readonly reason: string;
+}> {
+  get message(): string;
+}
+/**
+ * Define a conformance case. The metadata (id format, safety, non-empty
+ * `docs`/`wire`, observation date, fixture ids) is validated here and an
+ * invalid definition throws `ConformanceCaseInvalid`: definitions are
+ * module-level constants, so a bad one fails fast when the module loads
+ * instead of surfacing mid-run.
+ */
+declare const defineConformanceCase: <E = never, R = never>(spec: ConformanceCase<E, R>) => ConformanceCase<E, R>;
+declare const ConformanceMismatch_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "ConformanceMismatch";
+} & Readonly<A>;
+/**
+ * A wire claim did not hold. Model-free: `expected` / `actual` are optional
+ * JSON values chosen by the case author; keep them small and synthetic.
+ */
+declare class ConformanceMismatch extends ConformanceMismatch_base<{
+  readonly message: string;
+  readonly expected?: Schema.Json;
+  readonly actual?: Schema.Json;
+}> {}
+type ConformanceMismatchDetails = {
+  readonly expected?: Schema.Json;
+  readonly actual?: Schema.Json;
+};
+/** Succeed when `condition` holds; otherwise fail with a `ConformanceMismatch`. */
+declare const expectConformance: (condition: boolean, message: string, details?: ConformanceMismatchDetails) => Effect.Effect<void, ConformanceMismatch>;
+/**
+ * Succeed when `actual` and `expected` are structurally equal JSON values
+ * (effect `Equal.equals`: same primitives, same array order, same object keys
+ * and values); otherwise fail with a `ConformanceMismatch` carrying both.
+ */
+declare const expectEqual: (actual: Schema.Json, expected: Schema.Json, message: string) => Effect.Effect<void, ConformanceMismatch>;
+//#endregion
+export { ConformanceCase, ConformanceCaseId, ConformanceCaseInvalid, ConformanceMismatch, ConformanceMismatchDetails, ConformanceObservation, ConformanceSafety, defineConformanceCase, expectConformance, expectEqual };
+//# sourceMappingURL=case.d.mts.map

package/dist/case.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"case.d.mts","names":[],"sources":["../src/case.ts"],"mappings":";;;;AA0B6D;AAM7D;;;;AAEC;AAKD;;;;AAb6D,cAFhD,iBAAA,EAAiB,MAAA,CAAA,QAAA;AAAA,KAElB,iBAAA,UAA2B,iBAAA,CAAkB,IAAI;;;;;cAMhD,iBAAA,EAAiB,MAAA,CAAA,MAE7B;;cAKY,sBAAA,EAAsB,MAAA,CAAA,MAAA;;;;KAOvB,sBAAA,UAAgC,sBAAA,CAAuB,IAAI;;;;AAAA;KAM3D,eAAA;EAAe,+DAEhB,EAAA;EAAA,SACA,KAAA;EAAA,SACA,MAAA,EAAQ,iBAAA,EAQE;EAAA,SANV,IAAA,UAO4B;EAAA,SAL5B,IAAA,UAKkB;EAAA,SAHlB,QAAA,GAAW,sBAAA,EAVM;EAAA,SAYjB,QAAA,EAAU,aAAA;EAAA,SACV,GAAA,EAAK,MAAA,CAAO,MAAA,OAAa,CAAA,EAAG,CAAA;AAAA;AAAA,cACtC,2BAAA;;;;;;;cAkBY,sBAAA,SAA+B,2BAAA;EAAA,SACjC,MAAA;EAAA,SACA,MAAA;AAAA;EAAA,IAEI,OAAA,CAAA;AAAA;;AAvByB;AACvC;;;;;cAkCY,qBAAA,yBACX,IAAA,EAAM,eAAA,CAAgB,CAAA,EAAG,CAAA,MACxB,eAAA,CAAgB,CAAA,EAAG,CAAA;AAAA,cAYrB,wBAAA;;;;;;;cAMY,mBAAA,SAA4B,wBAAA;EAAA,SAC9B,OAAA;EAAA,SACA,QAAA,GAAW,MAAA,CAAO,IAAA;EAAA,SAClB,MAAA,GAAS,MAAA,CAAO,IAAA;AAAA;AAAA,KAGf,0BAAA;EAAA,SACD,QAAA,GAAW,MAAA,CAAO,IAAA;EAAA,SAClB,MAAA,GAAS,MAAA,CAAO,IAAI;AAAA;;cAOlB,iBAAA,GACX,SAAA,WACA,OAAA,UACA,OAAA,GAAU,0BAAA,KACT,MAAA,CAAO,MAAA,OAAa,mBAAA;;;;;AAvDvB;cA+Da,WAAA,GACX,MAAA,EAAQ,MAAA,CAAO,IAAA,EACf,QAAA,EAAU,MAAA,CAAO,IAAA,EACjB,OAAA,aACC,MAAA,CAAO,MAAA,OAAa,mBAAA"}

package/dist/case.mjs

@@ -0,0 +1,101 @@
+import { Data, Effect, Equal, Result } from "effect";
+import * as Schema from "effect/Schema";
+//#region src/case.ts
+/**
+* Conformance cases: small, named, pure Effect programs that each prove one
+* claim about how an outside service really behaves on the wire.
+*
+* A case only states what it needs (its `R`); the same case runs unchanged
+* against replayed fixtures, an in-process emulator, a local emulator
+* process, or a real practice account. Only the layers a host provides
+* change. See `@yolk-sdk/conformance/runner` for the safety policy.
+*
+* @experimental
+*/
+/**
+* What a case does to the account it runs against:
+*
+* - `read`: only reads.
+* - `write-reversible`: writes but leaves the account as it found it (it
+*   creates its own records and cleans them up, or the write is rejected and
+*   changes nothing).
+* - `write-irreversible`: a write that cannot be undone (for example sending
+*   an email). Never automated against a live account.
+*/
+const ConformanceSafety = Schema.Literals([
+	"read",
+	"write-reversible",
+	"write-irreversible"
+]);
+/**
+* Dotted lower-case case id: two or more segments of `a-z`, `0-9`, and inner
+* hyphens, for example `vendor.stream.plain-text`.
+*/
+const ConformanceCaseId = Schema.String.check(Schema.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*(?:\.[a-z0-9]+(?:-[a-z0-9]+)*)+$/));
+const CalendarDate = Schema.String.check(Schema.isPattern(/^\d{4}-\d{2}-\d{2}$/));
+/** When and where a person last watched the claim hold against the real service. */
+const ConformanceObservation = Schema.Struct({
+	/** Synthetic account label, for example `synthetic`; never a real account name. */
+	account: Schema.NonEmptyString,
+	/** Calendar date of the observation (`YYYY-MM-DD`, UTC). */
+	date: CalendarDate
+});
+const ConformanceCaseMetadata = Schema.Struct({
+	id: ConformanceCaseId,
+	title: Schema.optionalKey(Schema.NonEmptyString),
+	safety: ConformanceSafety,
+	docs: Schema.NonEmptyString,
+	wire: Schema.NonEmptyString,
+	observed: Schema.optionalKey(ConformanceObservation),
+	fixtures: Schema.Array(Schema.NonEmptyString)
+});
+const validateMetadata = Schema.decodeUnknownResult(ConformanceCaseMetadata);
+/**
+* Thrown by `defineConformanceCase` for an invalid definition. A programmer
+* error, surfaced when the defining module loads (like `makeTool`).
+*/
+var ConformanceCaseInvalid = class extends Data.TaggedError("ConformanceCaseInvalid") {
+	get message() {
+		return `Invalid conformance case ${JSON.stringify(this.caseId)}: ${this.reason}`;
+	}
+};
+/**
+* Define a conformance case. The metadata (id format, safety, non-empty
+* `docs`/`wire`, observation date, fixture ids) is validated here and an
+* invalid definition throws `ConformanceCaseInvalid`: definitions are
+* module-level constants, so a bad one fails fast when the module loads
+* instead of surfacing mid-run.
+*/
+const defineConformanceCase = (spec) => {
+	const { run: _run, ...metadata } = spec;
+	const result = validateMetadata(metadata);
+	if (Result.isFailure(result)) throw new ConformanceCaseInvalid({
+		caseId: spec.id,
+		reason: new Schema.SchemaError(result.failure.issue).message
+	});
+	return spec;
+};
+/**
+* A wire claim did not hold. Model-free: `expected` / `actual` are optional
+* JSON values chosen by the case author; keep them small and synthetic.
+*/
+var ConformanceMismatch = class extends Data.TaggedError("ConformanceMismatch") {};
+const mismatch = (message, details = {}) => new ConformanceMismatch({
+	message,
+	...details
+});
+/** Succeed when `condition` holds; otherwise fail with a `ConformanceMismatch`. */
+const expectConformance = (condition, message, details) => condition ? Effect.void : Effect.fail(mismatch(message, details));
+/**
+* Succeed when `actual` and `expected` are structurally equal JSON values
+* (effect `Equal.equals`: same primitives, same array order, same object keys
+* and values); otherwise fail with a `ConformanceMismatch` carrying both.
+*/
+const expectEqual = (actual, expected, message) => expectConformance(Equal.equals(actual, expected), message, {
+	expected,
+	actual
+});
+//#endregion
+export { ConformanceCaseId, ConformanceCaseInvalid, ConformanceMismatch, ConformanceObservation, ConformanceSafety, defineConformanceCase, expectConformance, expectEqual };
+
+//# sourceMappingURL=case.mjs.map

package/dist/case.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"case.mjs","names":[],"sources":["../src/case.ts"],"sourcesContent":["/**\n * Conformance cases: small, named, pure Effect programs that each prove one\n * claim about how an outside service really behaves on the wire.\n *\n * A case only states what it needs (its `R`); the same case runs unchanged\n * against replayed fixtures, an in-process emulator, a local emulator\n * process, or a real practice account. Only the layers a host provides\n * change. See `@yolk-sdk/conformance/runner` for the safety policy.\n *\n * @experimental\n */\nimport { Data, Effect, Equal, Result } from 'effect'\nimport * as Schema from 'effect/Schema'\n\n/**\n * What a case does to the account it runs against:\n *\n * - `read`: only reads.\n * - `write-reversible`: writes but leaves the account as it found it (it\n *   creates its own records and cleans them up, or the write is rejected and\n *   changes nothing).\n * - `write-irreversible`: a write that cannot be undone (for example sending\n *   an email). Never automated against a live account.\n */\nexport const ConformanceSafety = Schema.Literals(['read', 'write-reversible', 'write-irreversible'])\n\nexport type ConformanceSafety = typeof ConformanceSafety.Type\n\n/**\n * Dotted lower-case case id: two or more segments of `a-z`, `0-9`, and inner\n * hyphens, for example `vendor.stream.plain-text`.\n */\nexport const ConformanceCaseId = Schema.String.check(\n  Schema.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*(?:\\.[a-z0-9]+(?:-[a-z0-9]+)*)+$/)\n)\n\nconst CalendarDate = Schema.String.check(Schema.isPattern(/^\\d{4}-\\d{2}-\\d{2}$/))\n\n/** When and where a person last watched the claim hold against the real service. */\nexport const ConformanceObservation = Schema.Struct({\n  /** Synthetic account label, for example `synthetic`; never a real account name. */\n  account: Schema.NonEmptyString,\n  /** Calendar date of the observation (`YYYY-MM-DD`, UTC). */\n  date: CalendarDate\n})\n\nexport type ConformanceObservation = typeof ConformanceObservation.Type\n\n/**\n * One wire claim. `run` succeeds when the claim holds and fails (with a\n * `ConformanceMismatch`, its own error, or a port's error) when it does not.\n */\nexport type ConformanceCase<E = never, R = never> = {\n  /** Dotted lower-case id (see `ConformanceCaseId`). */\n  readonly id: string\n  readonly title?: string\n  readonly safety: ConformanceSafety\n  /** What the service's documentation claims. */\n  readonly docs: string\n  /** What the wire actually does (the claim this case proves). */\n  readonly wire: string\n  /** Last live observation. Absent means the claim is unverified against the real service. */\n  readonly observed?: ConformanceObservation\n  /** Ids of the fixtures (`WireFixture`s or `PortFixture`s) that back replay of this case. */\n  readonly fixtures: ReadonlyArray<string>\n  readonly run: Effect.Effect<void, E, R>\n}\n\nconst ConformanceCaseMetadata = Schema.Struct({\n  id: ConformanceCaseId,\n  title: Schema.optionalKey(Schema.NonEmptyString),\n  safety: ConformanceSafety,\n  docs: Schema.NonEmptyString,\n  wire: Schema.NonEmptyString,\n  observed: Schema.optionalKey(ConformanceObservation),\n  fixtures: Schema.Array(Schema.NonEmptyString)\n})\n\nconst validateMetadata = Schema.decodeUnknownResult(ConformanceCaseMetadata)\n\n/**\n * Thrown by `defineConformanceCase` for an invalid definition. A programmer\n * error, surfaced when the defining module loads (like `makeTool`).\n */\nexport class ConformanceCaseInvalid extends Data.TaggedError('ConformanceCaseInvalid')<{\n  readonly caseId: string\n  readonly reason: string\n}> {\n  override get message(): string {\n    return `Invalid conformance case ${JSON.stringify(this.caseId)}: ${this.reason}`\n  }\n}\n\n/**\n * Define a conformance case. The metadata (id format, safety, non-empty\n * `docs`/`wire`, observation date, fixture ids) is validated here and an\n * invalid definition throws `ConformanceCaseInvalid`: definitions are\n * module-level constants, so a bad one fails fast when the module loads\n * instead of surfacing mid-run.\n */\nexport const defineConformanceCase = <E = never, R = never>(\n  spec: ConformanceCase<E, R>\n): ConformanceCase<E, R> => {\n  const { run: _run, ...metadata } = spec\n  const result = validateMetadata(metadata)\n\n  if (Result.isFailure(result)) {\n    throw new ConformanceCaseInvalid({\n      caseId: spec.id,\n      reason: new Schema.SchemaError(result.failure.issue).message\n    })\n  }\n\n  return spec\n}\n\n/**\n * A wire claim did not hold. Model-free: `expected` / `actual` are optional\n * JSON values chosen by the case author; keep them small and synthetic.\n */\nexport class ConformanceMismatch extends Data.TaggedError('ConformanceMismatch')<{\n  readonly message: string\n  readonly expected?: Schema.Json\n  readonly actual?: Schema.Json\n}> {}\n\nexport type ConformanceMismatchDetails = {\n  readonly expected?: Schema.Json\n  readonly actual?: Schema.Json\n}\n\nconst mismatch = (message: string, details: ConformanceMismatchDetails = {}) =>\n  new ConformanceMismatch({ message, ...details })\n\n/** Succeed when `condition` holds; otherwise fail with a `ConformanceMismatch`. */\nexport const expectConformance = (\n  condition: boolean,\n  message: string,\n  details?: ConformanceMismatchDetails\n): Effect.Effect<void, ConformanceMismatch> =>\n  condition ? Effect.void : Effect.fail(mismatch(message, details))\n\n/**\n * Succeed when `actual` and `expected` are structurally equal JSON values\n * (effect `Equal.equals`: same primitives, same array order, same object keys\n * and values); otherwise fail with a `ConformanceMismatch` carrying both.\n */\nexport const expectEqual = (\n  actual: Schema.Json,\n  expected: Schema.Json,\n  message: string\n): Effect.Effect<void, ConformanceMismatch> =>\n  expectConformance(Equal.equals(actual, expected), message, { expected, actual })\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAwBA,MAAa,oBAAoB,OAAO,SAAS;CAAC;CAAQ;CAAoB;AAAoB,CAAC;;;;;AAQnG,MAAa,oBAAoB,OAAO,OAAO,MAC7C,OAAO,UAAU,2DAA2D,CAC9E;AAEA,MAAM,eAAe,OAAO,OAAO,MAAM,OAAO,UAAU,qBAAqB,CAAC;;AAGhF,MAAa,yBAAyB,OAAO,OAAO;;CAElD,SAAS,OAAO;;CAEhB,MAAM;AACR,CAAC;AAwBD,MAAM,0BAA0B,OAAO,OAAO;CAC5C,IAAI;CACJ,OAAO,OAAO,YAAY,OAAO,cAAc;CAC/C,QAAQ;CACR,MAAM,OAAO;CACb,MAAM,OAAO;CACb,UAAU,OAAO,YAAY,sBAAsB;CACnD,UAAU,OAAO,MAAM,OAAO,cAAc;AAC9C,CAAC;AAED,MAAM,mBAAmB,OAAO,oBAAoB,uBAAuB;;;;;AAM3E,IAAa,yBAAb,cAA4C,KAAK,YAAY,wBAAwB,EAGlF;CACD,IAAa,UAAkB;EAC7B,OAAO,4BAA4B,KAAK,UAAU,KAAK,MAAM,EAAE,IAAI,KAAK;CAC1E;AACF;;;;;;;;AASA,MAAa,yBACX,SAC0B;CAC1B,MAAM,EAAE,KAAK,MAAM,GAAG,aAAa;CACnC,MAAM,SAAS,iBAAiB,QAAQ;CAExC,IAAI,OAAO,UAAU,MAAM,GACzB,MAAM,IAAI,uBAAuB;EAC/B,QAAQ,KAAK;EACb,QAAQ,IAAI,OAAO,YAAY,OAAO,QAAQ,KAAK,EAAE;CACvD,CAAC;CAGH,OAAO;AACT;;;;;AAMA,IAAa,sBAAb,cAAyC,KAAK,YAAY,qBAAqB,EAI5E,CAAC;AAOJ,MAAM,YAAY,SAAiB,UAAsC,CAAC,MACxE,IAAI,oBAAoB;CAAE;CAAS,GAAG;AAAQ,CAAC;;AAGjD,MAAa,qBACX,WACA,SACA,YAEA,YAAY,OAAO,OAAO,OAAO,KAAK,SAAS,SAAS,OAAO,CAAC;;;;;;AAOlE,MAAa,eACX,QACA,UACA,YAEA,kBAAkB,MAAM,OAAO,QAAQ,QAAQ,GAAG,SAAS;CAAE;CAAU;AAAO,CAAC"}