@glubean/sdk 0.2.1 → 0.2.3

package/dist/contract-http/types.d.ts

@@ -10,7 +10,7 @@
  * ContractCase, ContractExpect, etc.).
  */
 import type { HttpClient, SchemaLike, TestContext } from "../types.js";
-import type { CaseDefaultRun, CaseRequires, CaseSeverity, Extensions } from "../contract-types.js";
+import type { BaseCaseSpec, Extensions } from "../contract-types.js";
 /**
  * HTTP security scheme declaration for contract instances.
  * Maps to OpenAPI `securitySchemes`. Authoritative metadata, not docs-only.
@@ -69,7 +69,64 @@ export interface ContractExpect<T = unknown> {
     /** Named response examples (OpenAPI docs). */
     examples?: Record<string, ContractExample<T>>;
 }
-export interface ContractCase<T = unknown, S = void> {
+/**
+ * Static-body shape for HTTP case `body` field. Excludes `unknown` (which
+ * would swallow the function branch in a union and lose `Needs` typing for
+ * function-valued bodies). Function-form `body: (input: Needs) => ...` only
+ * matches when the static-form types reject the value.
+ */
+export type HttpStaticBody = Record<string, unknown> | unknown[] | string | number | boolean | null | FormData | URLSearchParams | Blob;
+/**
+ * v0 HTTP case factory — closes the v3 P2 known-open ("HTTP body Needs
+ * drift"). Inside a contract spec literal, TypeScript can't correlate
+ * `needs: SchemaLike<X>` and `body: (input: Y) => ...` from sibling
+ * fields — author can write drift between them and TS won't flag it
+ * (`body` runs with `input.email` undefined when `body` destructures
+ * a key that isn't on Needs).
+ *
+ * `defineHttpCase<Needs, T>` captures `Needs` once via the explicit
+ * generic; the case literal is then checked against
+ * `ContractCase<T, Needs>` so all action fields (`body`, `params`,
+ * `query`, `headers`) are constrained to `(input: Needs) => ...`. Drift
+ * between `needs` and any action field becomes a compile error.
+ *
+ * Use it for cases that declare `needs` AND have function-valued action
+ * fields. Cases without `needs` (or with only static action fields)
+ * don't need the factory; the runtime invariants are unaffected either
+ * way (this is a typing improvement only).
+ *
+ * @example
+ * ```ts
+ * import { defineHttpCase } from "@glubean/sdk";
+ * import { z } from "zod";
+ *
+ * const successCase = defineHttpCase<{ email: string }>({
+ *   description: "creates a user",
+ *   needs: z.object({ email: z.string() }),
+ *   // body, params, query, headers params now type-checked against
+ *   // { email: string } — author can NOT write `({wrongKey}) => ...`.
+ *   body: ({ email }) => ({ email }),
+ *   expect: { status: 201 },
+ * });
+ *
+ * const api = contract.http.with("users", { client });
+ * export const createUser = api("user.create", {
+ *   endpoint: "POST /users",
+ *   cases: { success: successCase },
+ * });
+ * ```
+ *
+ * @param c The case spec to validate. Returned verbatim.
+ */
+export declare function defineHttpCase<Needs = void, T = unknown>(c: ContractCase<T, Needs>): ContractCase<T, Needs>;
+export interface ContractCase<T = unknown, Needs = void> extends BaseCaseSpec {
+    /**
+     * Per-case logical input schema. Redeclares the `BaseCaseSpec.needs` field
+     * with the case-specific `Needs` parameter so author-provided schema and
+     * function-valued action field parameter types stay locked together —
+     * preventing drift between `needs: SchemaLike<X>` and `body: ({wrong}) => ...`.
+     */
+    needs?: SchemaLike<Needs>;
     /** Per-case HTTP client override. */
     client?: HttpClient;
     /** Why this case exists — required. */
@@ -77,35 +134,26 @@ export interface ContractCase<T = unknown, S = void> {
     /** Expected response. */
     expect: ContractExpect<T>;
     /**
-     * Request body (for POST/PUT/PATCH). Static value, FormData/URLSearchParams
-     * /Blob/string for non-JSON content types, or a function of setup state.
+     * Request body (for POST/PUT/PATCH). Either a static value (HttpStaticBody)
+     * or a function of the case's logical input (matching `needs`). v10
+     * attachment model: no more setup state — input comes from overlay
+     * bootstrap, explicit `--input-json`, or flow `.step() in` lens.
+     *
+     * The static branch deliberately uses concrete types (not `unknown`)
+     * because `unknown` in a union swallows the function branch — `Needs`
+     * typing on the function param would then be silently bypassed.
      */
-    body?: unknown | FormData | URLSearchParams | Blob | ((state: S) => unknown);
+    body?: HttpStaticBody | ((input: Needs) => unknown);
     /** Request content type override for this case. */
     contentType?: string;
     /** URL params. Values can be `ParamValue` objects for OpenAPI metadata. */
-    params?: Record<string, ParamValue> | ((state: S) => Record<string, string>);
+    params?: Record<string, ParamValue> | ((input: Needs) => Record<string, string>);
     /** Query parameters. */
-    query?: Record<string, ParamValue> | ((state: S) => Record<string, string>);
+    query?: Record<string, ParamValue> | ((input: Needs) => Record<string, string>);
     /** Request headers merged with client headers. */
-    headers?: Record<string, string> | ((state: S) => Record<string, string>);
-    /** Setup runs before the request. Return value goes to param/query/body/headers functions + teardown. */
-    setup?: (ctx: TestContext) => Promise<S>;
-    /** Teardown runs after verify, even on failure. */
-    teardown?: (ctx: TestContext, state: S) => Promise<void>;
+    headers?: Record<string, string> | ((input: Needs) => Record<string, string>);
     /** Business-logic verify — runs after status and schema validation. */
     verify?: (ctx: TestContext, res: T) => Promise<void>;
-    /** Not yet executable; reason shown in skip message. */
-    deferred?: string;
-    /** Deprecated; value is the reason. */
-    deprecated?: string;
-    /** Additional tags (merged with contract-level tags). */
-    tags?: string[];
-    severity?: CaseSeverity;
-    requires?: CaseRequires;
-    defaultRun?: CaseDefaultRun;
-    /** Per-case OpenAPI extensions. */
-    extensions?: Extensions;
 }
 /**
  * Structured request specification. Can be a bare SchemaLike (JSON body
@@ -239,7 +287,7 @@ export interface HttpFlowCaseOutput {
  * `contract.http.with("name", defaults)`.
  */
 export interface HttpContractFactory {
-    <Cases extends Record<string, ContractCase<any, any>>>(id: string, spec: HttpContractSpec<Cases>): import("../contract-types.js").ProtocolContract<HttpContractSpec, HttpPayloadSchemas, HttpContractMeta>;
+    <Cases extends Record<string, ContractCase<any, any>>>(id: string, spec: HttpContractSpec<Cases>): import("../contract-types.js").ProtocolContract<HttpContractSpec<Cases>, HttpPayloadSchemas, HttpContractMeta, Cases>;
     with(name: string, defaults: HttpContractDefaults): HttpContractFactory;
 }
 /**

package/dist/contract-http/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/contract-http/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/contract-http/types.ts"],"names":[],"mappings":"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"}

package/dist/contract-http/types.js

@@ -9,5 +9,49 @@
  * Source-of-truth for user-facing authoring types (HttpContractSpec,
  * ContractCase, ContractExpect, etc.).
  */
-export {};
+/**
+ * v0 HTTP case factory — closes the v3 P2 known-open ("HTTP body Needs
+ * drift"). Inside a contract spec literal, TypeScript can't correlate
+ * `needs: SchemaLike<X>` and `body: (input: Y) => ...` from sibling
+ * fields — author can write drift between them and TS won't flag it
+ * (`body` runs with `input.email` undefined when `body` destructures
+ * a key that isn't on Needs).
+ *
+ * `defineHttpCase<Needs, T>` captures `Needs` once via the explicit
+ * generic; the case literal is then checked against
+ * `ContractCase<T, Needs>` so all action fields (`body`, `params`,
+ * `query`, `headers`) are constrained to `(input: Needs) => ...`. Drift
+ * between `needs` and any action field becomes a compile error.
+ *
+ * Use it for cases that declare `needs` AND have function-valued action
+ * fields. Cases without `needs` (or with only static action fields)
+ * don't need the factory; the runtime invariants are unaffected either
+ * way (this is a typing improvement only).
+ *
+ * @example
+ * ```ts
+ * import { defineHttpCase } from "@glubean/sdk";
+ * import { z } from "zod";
+ *
+ * const successCase = defineHttpCase<{ email: string }>({
+ *   description: "creates a user",
+ *   needs: z.object({ email: z.string() }),
+ *   // body, params, query, headers params now type-checked against
+ *   // { email: string } — author can NOT write `({wrongKey}) => ...`.
+ *   body: ({ email }) => ({ email }),
+ *   expect: { status: 201 },
+ * });
+ *
+ * const api = contract.http.with("users", { client });
+ * export const createUser = api("user.create", {
+ *   endpoint: "POST /users",
+ *   cases: { success: successCase },
+ * });
+ * ```
+ *
+ * @param c The case spec to validate. Returned verbatim.
+ */
+export function defineHttpCase(c) {
+    return c;
+}
 //# sourceMappingURL=types.js.map

package/dist/contract-http/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/contract-http/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/contract-http/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA6GH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,UAAU,cAAc,CAC5B,CAAyB;IAEzB,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/contract-types.d.ts

@@ -17,7 +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 { Test, TestContext } from "./types.js";
+import type { SchemaLike, Test, TestContext } from "./types.js";
+import type { KnownArtifacts, KnownArtifactParts, KnownArtifactOptions } from "./index.js";
 /**
  * Case lifecycle.
  *
@@ -73,6 +74,89 @@ export interface FailureClassification {
     retryable?: boolean;
     message?: string;
 }
+/**
+ * Minimum shape every case spec must satisfy. Adapter-specific case specs
+ * (HttpContractCase / GrpcContractCase / GraphqlContractCase / ...) extend
+ * this with protocol-specific fields.
+ *
+ * Core (`dispatchContract`) reads these fields directly from `spec.cases[key]`.
+ * Adapter-specific fields are opaque to core and passed through to the adapter.
+ *
+ * @see contract-attachment-model.md v1.3 for `needs` / `given` / `runnability` semantics.
+ */
+export interface BaseCaseSpec {
+    description?: string;
+    /**
+     * Logical input schema for the case. The only public input contract.
+     * Protocol action fields (HTTP body/headers/params/query etc.) receive
+     * this typed input as their argument.
+     *
+     * Typed as `SchemaLike<unknown>` at the base to accept any concrete
+     * schema. The specific type is extracted per-case via `InferCaseInput<C>`
+     * when `ProtocolContract.case<K>()` types its return — TS infers the
+     * concrete T from the literal `SchemaLike<T>` the author wrote.
+     *
+     * This avoids a generic on `BaseCaseSpec<Needs>` which would force every
+     * adapter's case type (ContractCase / GrpcContractCase / GraphqlContractCase)
+     * to thread a Needs parameter through — too invasive for the authoring API.
+     */
+    needs?: SchemaLike<unknown>;
+    /**
+     * World-state precondition this case assumes. Projected as part of the
+     * contract because it changes what `expect` means (see §0.9 of the
+     * attachment model proposal). Bootstrap may *satisfy* `given` at
+     * runtime, but it must not be the only place where a semantically
+     * relevant precondition is declared.
+     */
+    given?: string;
+    /**
+     * Runnability metadata — grouped under `runnability` to make the
+     * "not contract semantic" stance structurally visible. Fields here
+     * do NOT enter contract projection; they enter runnable inventory.
+     */
+    runnability?: {
+        requireAttachment?: boolean;
+    };
+    deferred?: string;
+    deprecated?: string;
+    severity?: CaseSeverity;
+    requires?: CaseRequires;
+    defaultRun?: CaseDefaultRun;
+    tags?: string[];
+    extensions?: Extensions;
+}
+/**
+ * Context passed to `bootstrap.run(ctx, params)`. Extends TestContext with
+ * cleanup registration — cleanups run LIFO after standalone case execution,
+ * even if case expect/verify fails.
+ *
+ * Flow NEVER invokes bootstrap, so StandaloneBootstrapContext only exists
+ * for the standalone execution path.
+ */
+export interface StandaloneBootstrapContext extends TestContext {
+    cleanup(fn: () => Promise<void> | void): void;
+}
+/**
+ * Bootstrap spec. Plain function form is shorthand for structured form
+ * with no `params`.
+ *
+ * Body is opaque (§4.2 attachment model); only `params` schema is projectable.
+ */
+export type Bootstrap<Params, Output> = ((ctx: StandaloneBootstrapContext) => Promise<Output>) | {
+    params?: SchemaLike<Params>;
+    run: (ctx: StandaloneBootstrapContext, params: Params) => Promise<Output>;
+};
+/**
+ * Runtime marker carried by a registered bootstrap overlay. Scanner reads
+ * the __glubean_type discriminator; runner consults the registry at
+ * runnable resolution time.
+ */
+export interface BootstrapAttachment<Needs = void, Params = void> {
+    readonly __glubean_type: "bootstrap-attachment";
+    readonly testId: string;
+    readonly __phantom_needs?: Needs;
+    readonly __phantom_params?: Params;
+}
 /**
  * Protocol-agnostic case metadata. `schemas` is plugin-defined payload shape,
  * opaque to core.
@@ -97,6 +181,39 @@ export interface CaseMeta<PayloadSchemas = unknown, Meta = unknown> {
     schemas?: PayloadSchemas;
     /** Plugin-defined free-form metadata. Opaque to core. */
     meta?: Meta;
+    /**
+     * World-state precondition (contract-attachment-model.md §0.9). Projected
+     * as part of the contract because it changes what `expect` means.
+     * Adapter-independent — threaded verbatim from `BaseCaseSpec.given`.
+     */
+    given?: string;
+    /**
+     * Runnability metadata (contract-attachment-model.md §7.2). Not contract
+     * semantic; drives runnable inventory (e.g. `requireAttachment` blocks
+     * raw execution). Threaded verbatim from `BaseCaseSpec.runnability`.
+     */
+    runnability?: {
+        requireAttachment?: boolean;
+    };
+    /**
+     * v10 attachment-model — the case's logical-input (`needs`) schema in
+     * JSON-safe form. Populated by adapter.normalize() when the case's
+     * `needs` schema can be projected (`schemaToJsonSchema` returns
+     * something). Absent when the case has no `needs` OR when the schema
+     * shape isn't projectable (custom `safeParse`-only validator).
+     *
+     * To decide whether `rawBypass` is available, consumers should check
+     * `hasNeeds` below — it is true whenever the case declared `needs`
+     * regardless of whether the schema survives projection.
+     */
+    needsSchema?: unknown;
+    /**
+     * True iff the case declares `needs`. Independent from `needsSchema`
+     * (which may be undefined even when `hasNeeds` is true, e.g. opaque
+     * `safeParse`-only schemas). Inventory uses this to decide whether
+     * the `rawBypass` execution path should appear on an overlay.
+     */
+    hasNeeds?: boolean;
 }
 /**
  * Runtime contract projection — adapter.project() output.
@@ -157,8 +274,45 @@ export interface ContractProtocolAdapter<Spec = unknown, RuntimeSchemas = unknow
      * Execute a single case. Called by the core dispatcher for each spec case.
      * Adapter does the full case lifecycle: setup → request/invoke → expect →
      * verify → teardown.
+     *
+     * **Legacy path** — uses case-local `setup` / `teardown` fields.
+     * Replaced by `executeCase` in v10 attachment model (setup/teardown are
+     * removed from contract case surface; state is provided via bootstrap
+     * overlay or explicit input). Kept for backward compat during migration;
+     * removed in Spike 2 Phase 2c.
      */
     execute: (ctx: TestContext, caseSpec: unknown, contractSpec: Spec) => Promise<void>;
+    /**
+     * Execute a single case in **standalone mode** with an already-resolved
+     * logical input.
+     *
+     * Scope note: this method is **standalone-only**. Flow dispatch continues
+     * to use `executeCaseInFlow` (below). The two paths coexist because flow
+     * never invokes bootstrap (attachment model §14.0 non-negotiable invariant)
+     * — if executeCase took `mode: "flow"`, it would imply flow could route
+     * through here, which contradicts the invariant.
+     *
+     * v10 attachment model entry point. Core dispatcher calls this after:
+     *   - resolving bootstrap overlay (if registered) to produce `resolvedInput`
+     *   - OR receiving explicit `--input-json` / `input` from runner
+     *   - validating against the case's `needs` schema
+     *
+     * Adapter responsibilities:
+     *   1. Receive already-validated `resolvedInput` (no re-validation needed)
+     *   2. Call function-valued action fields (body / headers / etc.) with the input
+     *   3. Execute request / expect / verify
+     *   4. No setup / teardown — those are gone in v10
+     *
+     * @see contract-attachment-model.md v1.3 §10.1
+     * @see single-case-execution-api.md v1 §5
+     */
+    executeCase?: (options: {
+        ctx: TestContext;
+        contract: ProtocolContract<Spec, SafeSchemas, SafeMeta>;
+        caseKey: string;
+        /** Logical input already validated against `needs`. `void` when case has no needs. */
+        resolvedInput: unknown;
+    }) => Promise<void>;
     /**
      * Project the spec to a Runtime projection (may contain live schemas).
      *
@@ -182,7 +336,17 @@ export interface ContractProtocolAdapter<Spec = unknown, RuntimeSchemas = unknow
      * protocol-agnostic skeleton (no `schemas` / `meta`). See `contract-flow.md`
      * §3.5.3 rule 3.
      */
-    normalize?: (projection: ContractProjection<RuntimeSchemas, RuntimeMeta> & {
+    /**
+     * Convert the runtime projection (may contain live refs like Zod schemas)
+     * into the JSON-safe `Extracted` form consumed by downstream (scanner /
+     * MCP / CLI / cloud). SDK's `dispatchContract` calls this unconditionally
+     * at contract construction and stores the result on the carrier as
+     * `_extracted` — scanner reads that directly. Adapter is responsible for
+     * knowing which fields are schemas (convert Zod → JSON Schema) vs literal
+     * example data (pass through) vs protocol-specific metadata that must
+     * survive normalize (e.g. HTTP `security`).
+     */
+    normalize: (projection: ContractProjection<RuntimeSchemas, RuntimeMeta> & {
         id: string;
     }) => ExtractedContractProjection<SafeSchemas, SafeMeta>;
     /**
@@ -197,16 +361,23 @@ export interface ContractProtocolAdapter<Spec = unknown, RuntimeSchemas = unknow
         }>;
     }) => FailureClassification | undefined;
     /**
-     * Optional: render contract as an OpenAPI fragment. Input is the Extracted
-     * projection (after normalize). Used by MCP `glubean_openapi` tool.
-     */
-    toOpenApi?: (projection: ExtractedContractProjection<SafeSchemas, SafeMeta>) => Record<string, unknown> | undefined;
-    /**
-     * Optional: render contract as Markdown documentation. Used by
-     * CLI `glubean contracts --format md-outline` and
-     * MCP `glubean_project_contracts`.
+     * Artifact producers declared by this adapter. Each entry is a
+     * per-contract renderer for a registered artifact kind (see
+     * `@glubean/sdk`'s `ArtifactKind` + `renderArtifact` / `KnownArtifacts`).
+     * Producers return the kind's Part type; cross-contract merging is the
+     * kind's responsibility.
+     *
+     * Keyed by `ArtifactKind.name`. Third-party plugins add new keys by
+     * augmenting `KnownArtifacts` / `KnownArtifactParts` / `KnownArtifactOptions`
+     * at the package root via `declare module "@glubean/sdk"`.
+     *
+     * Replaces the deprecated per-adapter `toMarkdown?` / `toOpenApi?` hooks
+     * (removed after v0.2.x) which polluted the generic interface with
+     * protocol-specific artifacts (OpenAPI is HTTP-only).
      */
-    toMarkdown?: (projection: ExtractedContractProjection<SafeSchemas, SafeMeta>) => string;
+    artifacts?: {
+        [K in keyof KnownArtifacts]?: (projection: ExtractedContractProjection<SafeSchemas, SafeMeta>, options?: KnownArtifactOptions[K]) => KnownArtifactParts[K];
+    };
     /**
      * Optional: render the `target` string for display. HTTP: "POST /users"
      * stays as-is. gRPC: "Greeter/SayHello" might become "Greeter.SayHello()".
@@ -222,16 +393,23 @@ export interface ContractProtocolAdapter<Spec = unknown, RuntimeSchemas = unknow
      * Optional: execute a single case as a flow step.
      *
      * Core has already:
-     *   1. Computed `resolvedInputs` via `step.bindings.in(state)` (may be partial)
+     *   1. Computed `resolvedInputs` via `step.bindings.in(state)`
      *   2. Prepared current flow state
-     *   3. Passed the live contract instance (access merged scoped-factory state
+     *   3. **v10 (for migrated protocols)**: validated `resolvedInputs` against
+     *      the case's `needs` schema via `runFlow` → `validateNeedsOutput`, so
+     *      the adapter receives already-validated logical input.
+     *   4. Passed the live contract instance (access merged scoped-factory state
      *      via `contract._spec`)
      *
-     * Adapter responsibilities:
-     *   1. Deep-merge `resolvedInputs` into the case's static input fields
-     *   2. Run case setup / request / expect / verify / case teardown
-     *      (Rule 1: case teardown is step-local finally — see contract-flow §7.3)
-     *   3. Return adapter-specific CaseOutput shape (HTTP: { status, headers, body })
+     * Adapter responsibility (post-Spike-4; uniform across HTTP / gRPC /
+     * GraphQL): treat `resolvedInputs` as the case's **logical input**
+     * matching `needs`. Call function-valued action fields (HTTP:
+     * `body`/`params`/`query`/`headers`; gRPC: `request`/`metadata`;
+     * GraphQL: `variables`/`headers`) with it. The contract case has no
+     * lifecycle in v10 — setup-style work belongs to a
+     * `contract.bootstrap()` overlay, NOT to the case itself. Return an
+     * adapter-specific CaseOutput (HTTP: `{ status, headers, body }`;
+     * gRPC: `GrpcCaseResult`; GraphQL: `GraphqlCaseResult`).
      *
      * Not implemented = this protocol cannot be referenced in a flow.
      */
@@ -242,11 +420,21 @@ export interface ContractProtocolAdapter<Spec = unknown, RuntimeSchemas = unknow
         resolvedInputs: unknown;
     }) => Promise<unknown>;
     /**
-     * Optional: validate that a case can be referenced in a flow. Called by
-     * ProtocolContract.case(key). HTTP's implementation rejects cases with
-     * function-valued input fields (body/params/query/headers) because those
-     * depend on case-local setup state unavailable in flow mode. See
-     * contract-flow v9 §5.1.1 for rationale.
+     * Optional: validate that a case can be referenced in a flow.
+     *
+     * v10 call-site: `FlowBuilder.step(ref, bindings)` — fires at
+     * step-declaration time, NOT at `ProtocolContract.case(key)` time.
+     * Case-ref creation is pure in v10 (attachment model §4.1);
+     * flow-safety is a step-declaration concern.
+     *
+     * Post-Spike-4 reality: NO built-in adapter implements this hook
+     * anymore. The v9 rule "function-valued action fields can't resolve
+     * in flow" is semantically reversed in v10 — function fields ARE the
+     * canonical flow input channel, receiving `resolvedInputs` via
+     * logical input. The hook is kept on the interface for protocol-
+     * adapter authors who have legitimate per-protocol flow constraints
+     * (e.g. streaming-only methods rejected from non-streaming flows in
+     * a future plugin).
      *
      * Throws on invalid case; returns undefined on success.
      */
@@ -270,13 +458,26 @@ export interface PayloadDescriptor {
  * @template PayloadSchemas Runtime (live) payload shape.
  * @template Meta Runtime free-form meta.
  */
-export interface ProtocolContract<Spec = unknown, PayloadSchemas = unknown, Meta = unknown> extends Array<Test> {
+export interface ProtocolContract<Spec = unknown, PayloadSchemas = unknown, Meta = unknown, Cases extends Record<string, unknown> = Record<string, unknown>> extends Array<Test> {
     /**
      * Runtime projection with `id` injected by core. Consumers duck-type this.
      */
     readonly _projection: ContractProjection<PayloadSchemas, Meta> & {
         id: string;
     };
+    /**
+     * JSON-safe extracted projection — result of `adapter.normalize(_projection)`,
+     * computed by the dispatcher at contract construction. Scanner / MCP / CLI
+     * / cloud read this field directly as the canonical safe form. Never
+     * contains live refs (Zod schemas converted to plain JSON Schema etc.).
+     *
+     * Typed with the same generic slot as `_projection` for structural
+     * compatibility; at runtime it is always the Safe shape produced by
+     * the adapter's `normalize`.
+     */
+    readonly _extracted: ExtractedContractProjection<PayloadSchemas, Meta> & {
+        id: string;
+    };
     /**
      * Adapter-private runtime spec carrier. Holds the merged executable spec
      * (scoped-factory defaults + contract spec) used by `executeCaseInFlow`
@@ -294,7 +495,7 @@ export interface ProtocolContract<Spec = unknown, PayloadSchemas = unknown, Meta
      * headers as functions). Function fields reference case-local setup state
      * which is not available in flow mode. See contract-flow §5.1.1.
      */
-    case(key: string): ContractCaseRef<InferInputs<PayloadSchemas>, InferOutput<PayloadSchemas>>;
+    case<K extends keyof Cases & string>(key: K): ContractCaseRef<InferCaseInput<Cases[K]>, InferOutput<PayloadSchemas>>;
 }
 /**
  * Adapter-defined helper: extract the "case inputs" shape from PayloadSchemas.
@@ -308,6 +509,23 @@ export interface ProtocolContract<Spec = unknown, PayloadSchemas = unknown, Meta
  * direct typing of their own ContractCaseRef.
  */
 export type InferInputs<_PayloadSchemas> = unknown;
+/**
+ * Extract per-case logical input type from a case spec's `needs` field.
+ *
+ * Works for any case spec that extends `BaseCaseSpec<Needs>` and declares
+ * `needs: SchemaLike<T>`. Returns `void` for cases without `needs`.
+ *
+ * Used by `ProtocolContract.case<K>()` to infer `ContractCaseRef<Needs, ...>`
+ * per-case, so `contract.bootstrap(ref, { run: ... })` can type-check the
+ * run return against the specific case's Needs.
+ *
+ * @see contract-attachment-model.md v1.3 §4.1 / §5.3
+ * @see Spike 0 Finding 2 — requires `any` (not `unknown`) in don't-care slot
+ *      for contravariant positions.
+ */
+export type InferCaseInput<C> = C extends {
+    needs?: SchemaLike<infer N>;
+} ? unknown extends N ? void : N : void;
 /** Adapter-defined helper: extract the "case output" shape from PayloadSchemas. */
 export type InferOutput<_PayloadSchemas> = unknown;
 /**
@@ -468,12 +686,34 @@ export interface FlowBuilder<State = unknown> {
      * 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, NewState = State>(ref: ContractCaseRef<CaseInputs, CaseOutput>, bindings?: {
-        in?: (state: State) => CaseInputs;
-        out?: (state: State, response: CaseOutput) => NewState;
-        name?: string;
-    }): FlowBuilder<NewState>;
+    step<CaseInputs, CaseOutput, NewState = State>(ref: ContractCaseRef<CaseInputs, CaseOutput>, ...args: [CaseInputs] extends [void] ? [
+        bindings?: {
+            out?: (state: State, response: CaseOutput) => NewState;
+            name?: string;
+        }
+    ] : [
+        bindings: {
+            in: (state: State) => CaseInputs;
+            out?: (state: State, response: CaseOutput) => NewState;
+            name?: string;
+        }
+    ]): FlowBuilder<NewState>;
     /**
      * Add a pure synchronous data-transform step. Accepts any synchronous TS
      * expression (template literals, method calls, .map()). Projection records