@glubean/sdk 0.5.0 → 0.7.0

package/dist/contract-types.d.ts

@@ -17,10 +17,8 @@
  * See `internal/40-discovery/proposals/contract-generics-complete.md` v5
  * and `internal/40-discovery/proposals/contract-flow.md` v9 for design.
  */
-import type { SchemaLike, Test, TestContext } from "./types.js";
+import type { SchemaLike, SecretsAccessor, Test, TestContext } from "./types.js";
 import type { KnownArtifacts, KnownArtifactParts, KnownArtifactOptions } from "./index.js";
-import type { RuntimeBranchStep, ExtractedBranchStep, ExtractedPredicate, JsonScalar, BranchPredicate, PredicateScope } from "./contract-flow-condition.js";
-import type { RuntimePollStep, ExtractedPollStep } from "./contract-flow-poll.js";
 /**
  * Case lifecycle.
  *
@@ -261,6 +259,20 @@ export interface CaseMeta<PayloadSchemas = unknown, Meta = unknown> {
      * the `rawBypass` execution path should appear on an overlay.
      */
     hasNeeds?: boolean;
+    /**
+     * Direction of the case relative to the system under test. Absent =
+     * outbound (we call them — the default since contracts began). "inbound"
+     * = the counterparty calls us (inbound-contract-design §9.2); such cases
+     * are awaited via a workflow inbound poll, never executed.
+     */
+    direction?: "inbound";
+    /**
+     * Set to `false` by adapters whose case cannot be executed as a Test
+     * (inbound-contract-design §9.5). The dispatcher then registers NO Test
+     * and NO runnable-inventory entry for it — the case exists only in
+     * projection/metadata. Absent = runnable (every pre-existing case).
+     */
+    runnable?: boolean;
 }
 /**
  * Runtime contract projection — adapter.project() output.
@@ -305,6 +317,20 @@ export interface ExtractedContractProjection<SafeSchemas = unknown, SafeMeta = u
     cases: Array<ExtractedCaseMeta<SafeSchemas, SafeMeta>>;
     schemas?: SafeSchemas;
     meta?: SafeMeta;
+    /**
+     * Fully-qualified logical paths of schemas that were DECLARED but could not
+     * be projected to JSON Schema (the live `toJSONSchema()` threw, or the value
+     * was an unrecognized non-plain object). Distinct from "no schema declared":
+     * an absent schema does not appear here. Paths are dotted, e.g.
+     * `"request.body"`, `"cases.login.response.body"`, `"cases.login.needsSchema"`.
+     *
+     * The schema VALUE stays `undefined` in the projection (so OpenAPI / MCP /
+     * descriptors degrade exactly as before); this list is the explicit record
+     * a snapshot consumer uses to compute `projectionComplete` (false when
+     * non-empty) and warn about the specific holes. Undefined/omitted when every
+     * declared schema projected cleanly.
+     */
+    unprojectableSchemas?: string[];
 }
 /**
  * Protocol adapter interface. Implement to add support for a new protocol
@@ -423,7 +449,7 @@ export interface ContractProtocolAdapter<Spec = unknown, RuntimeSchemas = unknow
      * protocol-specific artifacts (OpenAPI is HTTP-only).
      */
     artifacts?: {
-        [K in keyof KnownArtifacts]?: (projection: ExtractedContractProjection<SafeSchemas, SafeMeta>, options?: KnownArtifactOptions[K]) => KnownArtifactParts[K];
+        [K in keyof KnownArtifacts]?: (projection: ExtractedContractProjection<SafeSchemas, SafeMeta>, options?: KnownArtifactOptions[K]) => KnownArtifactParts[K] | null;
     };
     /**
      * Optional: render the `target` string for display. HTTP: "POST /users"
@@ -443,7 +469,7 @@ export interface ContractProtocolAdapter<Spec = unknown, RuntimeSchemas = unknow
      *   1. Computed `resolvedInputs` via `step.bindings.in(state)`
      *   2. Prepared current flow state
      *   3. **v10 (for migrated protocols)**: validated `resolvedInputs` against
-     *      the case's `needs` schema via `runFlow` → `validateNeedsOutput`, so
+     *      the case's `needs` schema via `validateNeedsOutput`, so
      *      the adapter receives already-validated logical input.
      *   4. Passed the live contract instance (access merged scoped-factory state
      *      via `contract._spec`)
@@ -505,6 +531,51 @@ export interface ContractProtocolAdapter<Spec = unknown, RuntimeSchemas = unknow
      * Throws on invalid case; returns undefined on success.
      */
     validateCaseForFlow?: (spec: Spec, caseKey: string, contractId: string) => void;
+    /**
+     * Optional: classify ONE delivery against an inbound case
+     * (inbound-contract-design §9.4/§9.4a). Called by the workflow inbound
+     * poll once per unclaimed delivery, in receiver order; the FIRST terminal
+     * classification wins (consult #4). Authentication decides failure;
+     * content decides attribution: fail-class results come only from the
+     * channel (signature / staleness / non-JSON), mismatches are probes.
+     *
+     * Preflight errors (unknown verifier scheme, missing secret) MUST throw —
+     * bad config must never hide as a probe (§9.4 preflight row).
+     *
+     * The poll resolves the state side itself (it owns the state) and hands
+     * the matcher the concrete value + the event's EXTRACTED selector path —
+     * a path, not the lens, because the matcher must walk unrelated webhook
+     * shapes safely: `e => e.data.id` THROWS on a body without `data`, while
+     * a safe path walk yields `undefined` → `type-mismatch` probe (codex I3
+     * R1 P2).
+     *
+     * The staleness clock for timestamped signature schemes is the delivery's
+     * own `receivedAt` — verification must reflect RECEIPT time, not whenever
+     * the poll happened to scan the inbox, or a pre-existing valid delivery
+     * (allowed evidence, §9.4a #3) would misclassify as stale after a slow
+     * setup (codex I3 R2 P2).
+     */
+    matchInboundCase?: (input: {
+        caseSpec: unknown;
+        delivery: InboundDelivery;
+        secrets: SecretsAccessor;
+        correlate?: {
+            eventPath: readonly string[];
+            stateValue: unknown;
+        };
+    }) => InboundMatchResult;
+    /**
+     * Optional: validate inbound-case CONFIG without a delivery — throw on an
+     * unknown verifier scheme / missing secret (§9.4 preflight row). The poll
+     * calls this every attempt BEFORE reading the receiver: an empty inbox
+     * must not let bad config exhaust as a timeout (codex I3 R3 P2 — the
+     * matcher's own preflight only runs when a delivery exists). Adapters
+     * implementing matchInboundCase should implement this too.
+     */
+    preflightInboundCase?: (input: {
+        caseSpec: unknown;
+        secrets: SecretsAccessor;
+    }) => void;
 }
 /**
  * Protocol-agnostic payload summary. Adapter-provided via describePayload.
@@ -554,14 +625,20 @@ export interface ProtocolContract<Spec = unknown, PayloadSchemas = unknown, Meta
      */
     readonly _spec: Spec;
     /**
-     * Return a ContractCaseRef for use in `contract.flow(...).step(...)`.
+     * Return a ContractCaseRef for use in `workflow().call/.poll(...)`.
      *
      * Runtime validation: adapter's `.case(key)` implementation MUST fail-fast
      * if the case contains function-valued input fields (body/params/query/
      * headers as functions). Function fields reference case-local setup state
      * which is not available in flow mode. See contract-flow §5.1.1.
      */
-    case<K extends keyof Cases & string>(key: K): ContractCaseRef<InferCaseInput<Cases[K]>, InferOutput<PayloadSchemas>, InferAcceptKey<PayloadSchemas>, InferRawOutcome<PayloadSchemas, InferOutput<PayloadSchemas>>>;
+    case<K extends keyof Cases & string>(key: K): ContractCaseRef<InferCaseInput<Cases[K]>, ApplyCaseOutput<PayloadSchemas, Cases[K]>, InferAcceptKey<PayloadSchemas>, InferRawOutcome<PayloadSchemas, InferOutput<PayloadSchemas>>> & (Cases[K] extends {
+        direction: "inbound";
+    } ? {
+        readonly direction: "inbound";
+    } : {
+        readonly direction?: undefined;
+    });
 }
 /**
  * Adapter-defined helper: extract the "case inputs" shape from PayloadSchemas.
@@ -594,6 +671,33 @@ export type InferCaseInput<C> = C extends {
 } ? unknown extends N ? void : N : void;
 /** Adapter-defined helper: extract the "case output" shape from PayloadSchemas. */
 export type InferOutput<_PayloadSchemas> = unknown;
+/**
+ * Per-case flow `CaseOutput` (the type of `res` in a `.step`/`.poll` `out`/`until`
+ * lens, sans `accept`). Adapters that carry a `__caseOutputShape` marker on their
+ * `PayloadSchemas` (HTTP = `HttpFlowCaseOutput`) get that shape with its `body`
+ * replaced by THIS case's validated response (`ExtractCaseResponse`); adapters
+ * without the marker fall back to `InferOutput`. Computed INSIDE the base `.case()`
+ * (not a subtype override) so HTTP contracts stay assignable to the base
+ * `ProtocolContract` while still typing `res.body` per case.
+ */
+export type ApplyCaseOutput<PayloadSchemas, Case> = PayloadSchemas extends {
+    readonly __caseOutputShape?: infer Shape;
+} ? [unknown] extends [Shape] ? InferOutput<PayloadSchemas> : Shape extends {
+    body: unknown;
+} ? Omit<Shape, "body"> & {
+    body: ExtractCaseResponse<Case>;
+} : InferOutput<PayloadSchemas> : InferOutput<PayloadSchemas>;
+/**
+ * A case's validated response body — ONLY from a PRESENT `expect.schema` (matched
+ * as required, not `schema?:`). A docs-only `expect.example`, an explicit response
+ * generic with no schema value, or any schema-less case stays `unknown`, so a flow
+ * lens never types a body the runtime didn't validate.
+ */
+export type ExtractCaseResponse<Case> = Case extends {
+    expect: {
+        schema: SchemaLike<infer S>;
+    };
+} ? [unknown] extends [S] ? unknown : S : unknown;
 /**
  * Adapter-defined helper: the element type of a step's `accept` list (the
  * "accepted alternate outcome key"). HTTP = `number` (status); other protocols
@@ -615,6 +719,66 @@ export type InferAcceptKey<P> = P extends {
 export type InferRawOutcome<P, Fallback = unknown> = P extends {
     readonly __rawOutcome?: infer R;
 } ? [unknown] extends [R] ? Fallback : NonNullable<R> : Fallback;
+/**
+ * One delivery as received — RAW. `bodyBytes` is the exact byte sequence the
+ * counterparty sent: HMAC-style signatures are computed over raw bytes, so
+ * any parsing or decoding before verification would destroy the evidence
+ * (design §9.1, blind spot 3). Protocol-agnostic: core's inbound-poll
+ * machinery and adapter `matchInboundCase` hooks both consume it (the
+ * zero-dependency local implementation lives in `contract-http/inbound.ts`).
+ */
+export interface InboundDelivery {
+    /** Receiver-assigned, unique per delivery (claim key). */
+    id: string;
+    /** EXACT body bytes as received — THE signature input. */
+    bodyBytes: Uint8Array;
+    /**
+     * UTF-8 decoded view of `bodyBytes`, for JSON parsing and display. LOSSY
+     * for non-UTF-8 payloads — never feed this to a signature verifier.
+     */
+    rawBody: string;
+    /** Header names lowercased. */
+    headers: Record<string, string>;
+    method: string;
+    path: string;
+    /** Epoch ms at receipt — the measured side of `within` evidence. */
+    receivedAt: number;
+}
+/**
+ * The receiver protocol an inbound poll (`.poll(ref, { via })`) consumes
+ * (design §9.1). NON-DESTRUCTIVE by construction: matching inspects
+ * `deliveries()` snapshots and `claim()`s only the matched delivery — other
+ * consumers' events are never swallowed by a failed match.
+ *
+ * ONE handle corresponds to ONE endpoint/secret domain (design §9.4):
+ * the matcher never checks method/path — full grade means "received through
+ * THIS handle" (consult #7), so multi-source channels must be split into
+ * per-domain handles at the receiver layer.
+ */
+export interface ReceiverHandle {
+    /** Snapshot of UNCLAIMED deliveries, oldest first. */
+    deliveries(): readonly InboundDelivery[];
+    /** Mark one delivery consumed (idempotent; unknown ids are a no-op). */
+    claim(id: string): void;
+    /** The URL the counterparty should be pointed at. */
+    url: string;
+    close(): Promise<void>;
+}
+/**
+ * Result of an adapter's `matchInboundCase` over ONE delivery (§9.4/§9.4a).
+ * Fail-class results (signature-invalid / stale / unparseable) FAIL the poll
+ * node; mismatch results are probes whose labels exist for diagnosis;
+ * `matched` claims the delivery and satisfies the poll.
+ */
+export type InboundMatchResult = {
+    kind: "matched";
+    parsed: unknown;
+} | {
+    kind: "type-mismatch" | "correlation-mismatch" | "schema-mismatch";
+} | {
+    kind: "signature-invalid" | "stale" | "unparseable";
+    detail?: string;
+};
 /**
  * Opaque reference to a single case of a contract. Produced by
  * `ProtocolContract.case(key)`. Used as input to `FlowBuilder.step(...)`.
@@ -638,28 +802,6 @@ export interface ContractCaseRef<CaseInputs = unknown, CaseOutput = unknown, Acc
     /** Phantom — `out`'s `res` type when `accept` is present (adapter raw outcome). */
     readonly __phantom_raw_outcome?: RawOutcome;
 }
-/** Contract-level metadata for a flow (set via `.meta()`). */
-export interface FlowMeta {
-    id: string;
-    name?: string;
-    description?: string;
-    tags?: string[];
-    extensions?: Extensions;
-    /**
-     * Mark this flow as skipped at run time. Value is the skip reason
-     * displayed in reports. Useful for illustrative examples that should
-     * be discoverable (for scanner extraction / docs rendering) but must
-     * not attempt live HTTP calls.
-     *
-     * Mirrors `TestMeta.skip`.
-     */
-    skip?: string;
-    /**
-     * Mark this flow as focused. When any flows/tests in a run are `only`,
-     * non-focused ones may be excluded. Mirrors `TestMeta.only`.
-     */
-    only?: boolean;
-}
 /**
  * Field dependency / mapping produced by Proxy dry-run of a lens function.
  * Consumed by downstream (MCP/CLI/Cloud) to render flow data-flow diagrams.
@@ -679,371 +821,14 @@ export interface FieldMapping {
     };
 }
 /**
- * Runtime flow step — discriminated union.
- * kind "contract-call" = a ContractCaseRef with bindings (Rule 1 teardown applies).
- * kind "compute" = a pure sync data-transform function (no adapter, no teardown).
- */
-export type RuntimeFlowStep = RuntimeContractCallStep | RuntimeComputeStep | RuntimeBranchStep | RuntimePollStep;
-export interface RuntimeContractCallStep {
-    kind: "contract-call";
-    name?: string;
-    ref: ContractCaseRef<any, any, any, any>;
-    caseKey: string;
-    /** Live contract instance (mirrors ref.contract, kept for direct access). */
-    contract: ProtocolContract<any, any, any>;
-    bindings?: {
-        in?: (state: any) => any;
-        out?: (state: any, response: any) => any;
-        /**
-         * Accepted alternate outcome keys (HTTP: status numbers). When the actual
-         * outcome key is in this list AND differs from the case's primary expected
-         * outcome, the adapter treats it as a legal outcome: it skips the case's
-         * primary result validation (schema / headers / verify) and hands the RAW
-         * outcome to `out`, so a condition can branch on it. Protocol-agnostic in
-         * core; the adapter interprets the element type.
-         */
-        accept?: readonly unknown[];
-    };
-}
-export interface RuntimeComputeStep {
-    kind: "compute";
-    name?: string;
-    /**
-     * Synchronous pure function. NOT subject to lens Proxy purity — may use
-     * template literals / method calls / .map(). MUST be synchronous and
-     * MUST NOT return a thenable (enforced at runtime).
-     */
-    fn: (state: any) => any;
-}
-/**
- * Runtime flow projection. Carries live callbacks + live contract refs.
- * Never crosses serialization boundaries. `normalizeFlow()` converts to
- * ExtractedFlowProjection for downstream consumers.
- */
-export interface RuntimeFlowProjection<State = unknown> {
-    protocol: "flow";
-    description?: string;
-    tags?: string[];
-    extensions?: Extensions;
-    /** Mirrors `FlowMeta.skip` — skip reason for discoverable-but-not-runnable flows. */
-    skip?: string;
-    /** Mirrors `FlowMeta.only` — focus filter. */
-    only?: boolean;
-    /** Live flow-level setup callback (only I/O-capable callback in flow). */
-    setup?: (ctx: TestContext) => Promise<State>;
-    /** Live flow-level teardown callback. Rule 2: outer finally. */
-    teardown?: (ctx: TestContext, state: State) => Promise<void>;
-    steps: RuntimeFlowStep[];
-}
-/**
- * Extracted flow step — discriminated union, JSON-safe.
- */
-export type ExtractedFlowStep = ExtractedContractCallStep | ExtractedComputeStep | ExtractedBranchStep | ExtractedPollStep;
-export interface ExtractedContractCallStep {
-    kind: "contract-call";
-    name?: string;
-    contractId: string;
-    caseKey: string;
-    protocol: string;
-    target: string;
-    /** Proxy dry-run output — input mappings. */
-    inputs?: FieldMapping[];
-    /** Proxy dry-run output — state update mappings. */
-    outputs?: FieldMapping[];
-    /**
-     * Accepted alternate outcome keys (HTTP: status numbers) — present when the
-     * step declared `accept`. Surfaces the multi-status contract to downstream
-     * consumers (scanner / MCP / CLI / Cloud) so a status-gated step is not
-     * indistinguishable from a single-primary-status one.
-     */
-    accept?: ReadonlyArray<string | number>;
-}
-export interface ExtractedComputeStep {
-    kind: "compute";
-    name?: string;
-    /** Top-level state paths read (from Proxy dry-run). */
-    reads: string[];
-    /** Top-level state keys written (keys of returned object). */
-    writes: string[];
-}
-/**
- * JSON-safe flow projection. Downstream (scanner / MCP / CLI / Cloud) consume
- * this. Produced by `normalizeFlow(runtime)`.
- */
-export interface ExtractedFlowProjection {
-    id: string;
-    protocol: "flow";
-    description?: string;
-    tags?: string[];
-    extensions?: Extensions;
-    /** Mirrors `FlowMeta.skip`. */
-    skip?: string;
-    /** Mirrors `FlowMeta.only`. */
-    only?: boolean;
-    /** Present when flow has a setup callback (state source is dynamic). */
-    setupDynamic?: true;
-    steps: ExtractedFlowStep[];
-}
-/**
- * Base options shared by `poll` / `pollFn` / `pollAsync`. `Res` switches on
- * `accept` exactly like `step` (no accept → CaseOutput; accept → RawOutcome).
- * `accept?: Accept` is what drives the `Accept` inference. Bound semantics +
- * the build-time rules live in `validatePollBounds`. (Spike P.)
- */
-export interface PollOptsBase<State, Res, NewState, Accept extends readonly unknown[]> {
-    /** The exit (satisfying) response written into state. */
-    out?: (state: State, response: Res) => NewState;
-    /** Accepted alternate outcome keys (HTTP: status numbers) — drives `Accept` inference. */
-    accept?: Accept;
-    name?: string;
-    /** Total wall-clock bound (ms). */
-    timeout?: number;
-    /** Max attempts (incl. the first). */
-    maxAttempts?: number;
-    /** Per-attempt budget (ms) — required when `timeout` is absent. */
-    perAttemptTimeout?: number;
-    /** Interval between attempts (ms, default 1000). */
-    every?: number;
-    /** Backoff multiplier applied to `every` after each retry (default 1, capped). */
-    backoff?: number;
-}
-/**
- * Poll argument tuple. Mirrors `step`'s conditional tuple: `in` is REQUIRED for
- * a needs-input case and FORBIDDEN for a void-input case. `Exit` is each tier's
- * `{ until, message }` fragment (L2 declarative vs opaque). (Spike P.)
- */
-export type PollArgs<State, CaseInputs, Res, NewState, Accept extends readonly unknown[], Exit> = [
-    CaseInputs
-] extends [void] ? [opts: PollOptsBase<State, Res, NewState, Accept> & Exit] : [opts: PollOptsBase<State, Res, NewState, Accept> & Exit & {
-    in: (state: State) => CaseInputs;
-}];
-/**
- * Builder for `contract.flow(id)`. State chain threads through `.step()` /
- * `.compute()` via TypeScript generics.
- */
-export interface FlowBuilder<State = unknown> {
-    readonly __glubean_type: "flow-builder";
-    meta(m: Omit<FlowMeta, "id">): FlowBuilder<State>;
-    /**
-     * Flow-level setup — the ONLY I/O-capable callback in a flow. May be async,
-     * may read ctx, may call external services. Returns the initial state.
-     */
-    setup<NewState>(fn: (ctx: TestContext) => Promise<NewState>): FlowBuilder<NewState>;
-    /**
-     * Add a contract-call step. `bindings.in` and `bindings.out` MUST be pure
-     * lens functions (select / repack only; no I/O, no method calls, no
-     * branching). Lens purity is enforced at Proxy dry-run time during
-     * projection extraction.
-     *
-     * Single signature with rest-parameter conditional tuple (Spike 0 Finding 3).
-     * Two-overload form (historically tried) has a subtle hole: overload 1
-     * (void-input, no `in`) excess-property-fails when `in` is passed → TS
-     * falls through to overload 2, which accepts because `() => X` is
-     * bivariant-assignable to `() => void`. Conditional tuple is a single
-     * signature so TS doesn't get a second chance:
-     *   - void-input case → `bindings` optional; `in` not present in the
-     *     allowed shape
-     *   - typed-input case → `bindings.in` REQUIRED
-     *
-     * In v10, `in` returns LOGICAL case input (matches the case's `needs`),
-     * NOT an adapter patch. HTTP adapter's `executeCaseInFlow` calls
-     * function-valued body/headers/params/query with this logical input
-     * (same mechanism as standalone `executeStandaloneCase`).
-     */
-    step<CaseInputs, CaseOutput, AcceptKey, RawOutcome, Accept extends readonly AcceptKey[] = never, NewState = State>(ref: ContractCaseRef<CaseInputs, CaseOutput, AcceptKey, RawOutcome>, ...args: [CaseInputs] extends [void] ? [
-        bindings?: {
-            accept?: Accept;
-            out?: (state: State, response: [Accept] extends [never] ? CaseOutput : RawOutcome) => NewState;
-            name?: string;
-        }
-    ] : [
-        bindings: {
-            in: (state: State) => CaseInputs;
-            accept?: Accept;
-            out?: (state: State, response: [Accept] extends [never] ? CaseOutput : RawOutcome) => NewState;
-            name?: string;
-        }
-    ]): FlowBuilder<NewState>;
-    /**
-     * Add a pure synchronous data-transform step. Accepts any synchronous TS
-     * expression (template literals, method calls, .map()). Projection records
-     * only read/write dependencies, NOT the formula.
-     *
-     * Runtime enforcement: throws if `fn` is async or returns a thenable.
-     */
-    compute<NewState>(fn: (state: State) => NewState): FlowBuilder<NewState>;
-    /**
-     * Flow-level teardown — runs in Rule 2 outer-finally, receives last-
-     * committed state. If flow.setup threw, teardown does NOT run.
-     */
-    teardown(fn: (ctx: TestContext, state: State) => Promise<void>): FlowBuilder<State>;
-    /** L2 — declarative predicate (precisely projectable). No else → then keeps State's shape (values may narrow). */
-    condition<R extends State = State>(spec: {
-        predicate: (w: PredicateScope<State>) => BranchPredicate<State>;
-        message?: string;
-    }, thenBranch: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<R & NoExtraKeys<R, State>>): FlowBuilder<State>;
-    /** L2 with else — `T` is inferred from `then`; `else` is checked against it (`NoInfer`). */
-    condition<T>(spec: {
-        predicate: (w: PredicateScope<State>) => BranchPredicate<State>;
-        message?: string;
-    }, thenBranch: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<T>, elseBranch: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<NoInfer<T>>): FlowBuilder<T>;
-    /** L1 — opaque sync predicate. `message` is required (projection marks ⚠ opaque-gate). */
-    conditionFn<R extends State = State>(spec: {
-        predicate: (ctx: TestContext, s: State) => boolean;
-        message: string;
-    }, thenBranch: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<R & NoExtraKeys<R, State>>): FlowBuilder<State>;
-    conditionFn<T>(spec: {
-        predicate: (ctx: TestContext, s: State) => boolean;
-        message: string;
-    }, thenBranch: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<T>, elseBranch: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<NoInfer<T>>): FlowBuilder<T>;
-    /** L0 — opaque async predicate (may do out-of-contract I/O). `message` required (⚠ dynamic-gate). */
-    conditionAsync<R extends State = State>(spec: {
-        predicate: (ctx: TestContext, s: State) => Promise<boolean>;
-        message: string;
-    }, thenBranch: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<R & NoExtraKeys<R, State>>): FlowBuilder<State>;
-    conditionAsync<T>(spec: {
-        predicate: (ctx: TestContext, s: State) => Promise<boolean>;
-        message: string;
-    }, thenBranch: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<T>, elseBranch: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<NoInfer<T>>): FlowBuilder<T>;
-    /**
-     * value-switch (single lens × N scalar values). Curried so `V` infers from
-     * the lens alone (Spike 0): first call fixes `V`, second checks each `value`
-     * against it. `default` is required (anchors `T`; the no-match path). switch
-     * is always L2 — a clean decision table.
-     */
-    switchOn<V>(lens: (s: State) => V): <T>(cases: ReadonlyArray<{
-        value: [Exclude<V, undefined>] extends [JsonScalar] ? Exclude<V, undefined> : never;
-        then: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<NoInfer<T>>;
-    }>, deflt: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<T>) => FlowBuilder<T>;
-    /** cond-switch (ordered, possibly-overlapping declarative predicates; first-match). */
-    switchCond<T>(cases: ReadonlyArray<{
-        when: (w: PredicateScope<State>) => BranchPredicate<State>;
-        then: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<NoInfer<T>>;
-    }>, deflt: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<T>): FlowBuilder<T>;
-    /** L2 — declarative exit predicate over the response (precisely projectable). poll-on-status needs `accept`. */
-    poll<CaseInputs, CaseOutput, AcceptKey, RawOutcome, Accept extends readonly AcceptKey[] = never, NewState = State>(ref: ContractCaseRef<CaseInputs, CaseOutput, AcceptKey, RawOutcome>, ...args: PollArgs<State, CaseInputs, [Accept] extends [never] ? CaseOutput : RawOutcome, NewState, Accept, {
-        until: (w: PredicateScope<[Accept] extends [never] ? CaseOutput : RawOutcome>) => BranchPredicate<[Accept] extends [never] ? CaseOutput : RawOutcome>;
-        message?: string;
-    }>): FlowBuilder<NewState>;
-    /** L1 — opaque sync exit predicate (gets ctx, res, state). `message` required (marked gate). */
-    pollFn<CaseInputs, CaseOutput, AcceptKey, RawOutcome, Accept extends readonly AcceptKey[] = never, NewState = State>(ref: ContractCaseRef<CaseInputs, CaseOutput, AcceptKey, RawOutcome>, ...args: PollArgs<State, CaseInputs, [Accept] extends [never] ? CaseOutput : RawOutcome, NewState, Accept, {
-        until: (ctx: TestContext, res: [Accept] extends [never] ? CaseOutput : RawOutcome, state: State) => boolean;
-        message: string;
-    }>): FlowBuilder<NewState>;
-    /** L0 — opaque async exit predicate (may do contract-external I/O). `message` required (marked gate). */
-    pollAsync<CaseInputs, CaseOutput, AcceptKey, RawOutcome, Accept extends readonly AcceptKey[] = never, NewState = State>(ref: ContractCaseRef<CaseInputs, CaseOutput, AcceptKey, RawOutcome>, ...args: PollArgs<State, CaseInputs, [Accept] extends [never] ? CaseOutput : RawOutcome, NewState, Accept, {
-        until: (ctx: TestContext, res: [Accept] extends [never] ? CaseOutput : RawOutcome, state: State) => Promise<boolean>;
-        message: string;
-    }>): FlowBuilder<NewState>;
-    build(): FlowContract<State>;
-}
-/**
- * Restricted builder for a branch body (condition then/else, switch case/default).
- * Accumulates step / compute / nested branch into the branch node's
- * `cases[].steps` / `default`; it deliberately does NOT expose flow-level
- * setup / teardown / meta / build.
- *
- * INVARIANT BRAND (Spike 0 / §8.1): `State` appears in both covariant (return)
- * and contravariant (parameter) position via the phantom `[FRAGMENT_STATE]`
- * field, making `FlowFragmentBuilder` *invariant* in `State`. Without this,
- * TS structural width-subtyping would let `FlowFragmentBuilder<{...State, x}>`
- * be assignable to `FlowFragmentBuilder<State>`, so a no-else branch could
- * silently add fields (or an else could return a `T` supertype) and bypass
- * convergence. The phantom is type-only — never read at runtime.
- */
-export interface FlowFragmentBuilder<State = unknown> {
-    readonly [FRAGMENT_STATE]: (s: State) => State;
-    step<CaseInputs, CaseOutput, AcceptKey, RawOutcome, Accept extends readonly AcceptKey[] = never, NewState = State>(ref: ContractCaseRef<CaseInputs, CaseOutput, AcceptKey, RawOutcome>, ...args: [CaseInputs] extends [void] ? [
-        bindings?: {
-            accept?: Accept;
-            out?: (state: State, response: [Accept] extends [never] ? CaseOutput : RawOutcome) => NewState;
-            name?: string;
-        }
-    ] : [
-        bindings: {
-            in: (state: State) => CaseInputs;
-            accept?: Accept;
-            out?: (state: State, response: [Accept] extends [never] ? CaseOutput : RawOutcome) => NewState;
-            name?: string;
-        }
-    ]): FlowFragmentBuilder<NewState>;
-    compute<NewState>(fn: (state: State) => NewState): FlowFragmentBuilder<NewState>;
-    condition<R extends State = State>(spec: {
-        predicate: (w: PredicateScope<State>) => BranchPredicate<State>;
-        message?: string;
-    }, thenBranch: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<R & NoExtraKeys<R, State>>): FlowFragmentBuilder<State>;
-    condition<T>(spec: {
-        predicate: (w: PredicateScope<State>) => BranchPredicate<State>;
-        message?: string;
-    }, thenBranch: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<T>, elseBranch: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<NoInfer<T>>): FlowFragmentBuilder<T>;
-    conditionFn<R extends State = State>(spec: {
-        predicate: (ctx: TestContext, s: State) => boolean;
-        message: string;
-    }, thenBranch: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<R & NoExtraKeys<R, State>>): FlowFragmentBuilder<State>;
-    conditionFn<T>(spec: {
-        predicate: (ctx: TestContext, s: State) => boolean;
-        message: string;
-    }, thenBranch: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<T>, elseBranch: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<NoInfer<T>>): FlowFragmentBuilder<T>;
-    conditionAsync<R extends State = State>(spec: {
-        predicate: (ctx: TestContext, s: State) => Promise<boolean>;
-        message: string;
-    }, thenBranch: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<R & NoExtraKeys<R, State>>): FlowFragmentBuilder<State>;
-    conditionAsync<T>(spec: {
-        predicate: (ctx: TestContext, s: State) => Promise<boolean>;
-        message: string;
-    }, thenBranch: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<T>, elseBranch: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<NoInfer<T>>): FlowFragmentBuilder<T>;
-    switchOn<V>(lens: (s: State) => V): <T>(cases: ReadonlyArray<{
-        value: [Exclude<V, undefined>] extends [JsonScalar] ? Exclude<V, undefined> : never;
-        then: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<NoInfer<T>>;
-    }>, deflt: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<T>) => FlowFragmentBuilder<T>;
-    switchCond<T>(cases: ReadonlyArray<{
-        when: (w: PredicateScope<State>) => BranchPredicate<State>;
-        then: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<NoInfer<T>>;
-    }>, deflt: (b: FlowFragmentBuilder<State>) => FlowFragmentBuilder<T>): FlowFragmentBuilder<T>;
-    poll<CaseInputs, CaseOutput, AcceptKey, RawOutcome, Accept extends readonly AcceptKey[] = never, NewState = State>(ref: ContractCaseRef<CaseInputs, CaseOutput, AcceptKey, RawOutcome>, ...args: PollArgs<State, CaseInputs, [Accept] extends [never] ? CaseOutput : RawOutcome, NewState, Accept, {
-        until: (w: PredicateScope<[Accept] extends [never] ? CaseOutput : RawOutcome>) => BranchPredicate<[Accept] extends [never] ? CaseOutput : RawOutcome>;
-        message?: string;
-    }>): FlowFragmentBuilder<NewState>;
-    pollFn<CaseInputs, CaseOutput, AcceptKey, RawOutcome, Accept extends readonly AcceptKey[] = never, NewState = State>(ref: ContractCaseRef<CaseInputs, CaseOutput, AcceptKey, RawOutcome>, ...args: PollArgs<State, CaseInputs, [Accept] extends [never] ? CaseOutput : RawOutcome, NewState, Accept, {
-        until: (ctx: TestContext, res: [Accept] extends [never] ? CaseOutput : RawOutcome, state: State) => boolean;
-        message: string;
-    }>): FlowFragmentBuilder<NewState>;
-    pollAsync<CaseInputs, CaseOutput, AcceptKey, RawOutcome, Accept extends readonly AcceptKey[] = never, NewState = State>(ref: ContractCaseRef<CaseInputs, CaseOutput, AcceptKey, RawOutcome>, ...args: PollArgs<State, CaseInputs, [Accept] extends [never] ? CaseOutput : RawOutcome, NewState, Accept, {
-        until: (ctx: TestContext, res: [Accept] extends [never] ? CaseOutput : RawOutcome, state: State) => Promise<boolean>;
-        message: string;
-    }>): FlowFragmentBuilder<NewState>;
-}
-/** Module-private phantom brand making FlowFragmentBuilder invariant in State. */
-declare const FRAGMENT_STATE: unique symbol;
-/**
- * No-else branch shape guard. A no-else `then` must NOT add/remove state keys
- * (when the predicate is false the branch is skipped, so downstream state stays
- * `State`), but it MAY narrow an existing key's value (e.g. flip `ok: boolean`
- * to `ok: true`). Encoded as `R extends State` (no removed keys, values only
- * narrow) intersected with `NoExtraKeys<R, State>` (any extra key collapses to
- * `never`, so adding a field fails to type-check). This is the ergonomic
- * counterpart to the invariant brand: it blocks shape drift without rejecting
- * safe literal narrowing.
+ * "No extra keys" structural guard — maps any key of R that is NOT in State to
+ * `never`, so a branch/fragment returning extra keys fails to type-check.
+ * (Shared type utility; survived the legacy-flow deletion because the vNext
+ * builder's strict-S sides use the same trick.)
  */
 export type NoExtraKeys<R, State> = {
     [K in Exclude<keyof R, keyof State>]: never;
 };
-/**
- * Runtime flow contract. Extends Array<Test> so runner iterates directly.
- * The single Test inside orchestrates setup → steps → teardown via runFlow.
- */
-export interface FlowContract<State = unknown> extends Array<Test> {
-    readonly _flow: RuntimeFlowProjection<State> & {
-        id: string;
-    };
-    /**
-     * Pre-computed JSON-safe extracted projection. Populated by the flow
-     * builder via `normalizeFlow(_flow)` so downstream consumers (scanner,
-     * CLI, MCP, Cloud) don't need to import the SDK to get field mappings
-     * for `.step()` lenses and reads/writes for `.compute()` nodes.
-     */
-    readonly _extracted: ExtractedFlowProjection;
-}
 /**
  * Contract registry metadata attached to tests produced by `contract[protocol]()`.
  * Mirrored by `RegisteredTestMeta.contract` in types.ts.
@@ -1066,60 +851,4 @@ export interface ContractRegistryMeta {
     /** Plugin-defined free-form meta; core does not inspect. */
     meta?: unknown;
 }
-/**
- * Flow registry metadata attached to the single Test generated by
- * `contract.flow()`. Mirrored by `RegisteredTestMeta.flow` in types.ts.
- */
-/** Registry step descriptor — same shape family as ExtractedFlowStep (recursive for branch). */
-export type FlowRegistryStep = {
-    kind: "contract-call" | "compute";
-    name?: string;
-    contractId?: string;
-    caseKey?: string;
-    protocol?: string;
-    target?: string;
-    inputs?: FieldMapping[];
-    outputs?: FieldMapping[];
-    reads?: string[];
-    writes?: string[];
-    accept?: ReadonlyArray<string | number>;
-} | {
-    kind: "branch";
-    mode: "value" | "predicate";
-    name?: string;
-    subjectPath?: string[];
-    cases: Array<{
-        value?: JsonScalar;
-        message?: string;
-        predicate?: ExtractedPredicate;
-        steps: FlowRegistryStep[];
-    }>;
-    default: FlowRegistryStep[];
-} | {
-    kind: "poll";
-    name?: string;
-    contractId?: string;
-    caseKey?: string;
-    protocol?: string;
-    target?: string;
-    inputs?: FieldMapping[];
-    outputs?: FieldMapping[];
-    accept?: ReadonlyArray<string | number>;
-    until?: ExtractedPredicate;
-    message?: string;
-    every?: number;
-    backoff?: number;
-    timeoutMs?: number;
-    perAttemptTimeoutMs?: number;
-    maxAttempts?: number;
-};
-export interface FlowRegistryMeta {
-    id: string;
-    description?: string;
-    tags?: string[];
-    /** Step descriptors (same shape family as ExtractedFlowStep; branch nests recursively). */
-    steps: FlowRegistryStep[];
-    setupDynamic?: true;
-}
-export {};
 //# sourceMappingURL=contract-types.d.ts.map