@glubean/sdk 0.2.2 → 0.2.3

package/dist/bootstrap-registry.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Bootstrap attachment registry.
+ *
+ * Per contract-attachment-model.md v1.3:
+ *   - `contract.bootstrap(ref, spec)` registers an overlay targeting a
+ *     specific contract case (identified by testId = `${contractId}.${caseKey}`).
+ *   - Each test id may have at most one bootstrap overlay. Duplicate
+ *     registration throws.
+ *   - Registry is consulted by the runner at runnable resolution time
+ *     (single-case-execution-api §5.1 algorithm).
+ *
+ * The registry is a process-global side-effect map. Modules that export
+ * `contract.bootstrap(...)` register on evaluation. Scanner / runner are
+ * responsible for eager module loading per attachment model §7.4.
+ */
+import type { BootstrapAttachment, Bootstrap, ContractCaseRef } from "./contract-types.js";
+interface BootstrapRegistration {
+    testId: string;
+    contractId: string;
+    caseKey: string;
+    protocol: string;
+    spec: Bootstrap<unknown, unknown>;
+}
+/**
+ * Register a bootstrap overlay for a specific case. Called by
+ * `contract.bootstrap(ref, spec)`.
+ *
+ * Throws if another overlay is already registered for the same testId.
+ */
+export declare function registerBootstrap<Needs, Params = void>(ref: ContractCaseRef<Needs, unknown>, spec: Bootstrap<Params, Needs>): BootstrapAttachment<Needs, Params>;
+/** Look up a bootstrap registration by testId. Returns undefined if none. */
+export declare function getBootstrap(testId: string): BootstrapRegistration | undefined;
+/** Enumerate all registered bootstrap overlays. Used by scanner / CLI list. */
+export declare function listBootstraps(): BootstrapRegistration[];
+/** Test-only: clear the registry between test runs. Not part of public API. */
+export declare function clearBootstrapRegistry(): void;
+export {};
+//# sourceMappingURL=bootstrap-registry.d.ts.map

package/dist/bootstrap-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap-registry.d.ts","sourceRoot":"","sources":["../src/bootstrap-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,SAAS,EACT,eAAe,EAChB,MAAM,qBAAqB,CAAC;AAE7B,UAAU,qBAAqB;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;CACnC;AAID;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EACpD,GAAG,EAAE,eAAe,CAAC,KAAK,EAAE,OAAO,CAAC,EACpC,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,GAC7B,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,CAuBpC;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,GACb,qBAAqB,GAAG,SAAS,CAEnC;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,IAAI,qBAAqB,EAAE,CAExD;AAED,+EAA+E;AAC/E,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/dist/bootstrap-registry.js

@@ -0,0 +1,54 @@
+/**
+ * Bootstrap attachment registry.
+ *
+ * Per contract-attachment-model.md v1.3:
+ *   - `contract.bootstrap(ref, spec)` registers an overlay targeting a
+ *     specific contract case (identified by testId = `${contractId}.${caseKey}`).
+ *   - Each test id may have at most one bootstrap overlay. Duplicate
+ *     registration throws.
+ *   - Registry is consulted by the runner at runnable resolution time
+ *     (single-case-execution-api §5.1 algorithm).
+ *
+ * The registry is a process-global side-effect map. Modules that export
+ * `contract.bootstrap(...)` register on evaluation. Scanner / runner are
+ * responsible for eager module loading per attachment model §7.4.
+ */
+const _bootstrapRegistry = new Map();
+/**
+ * Register a bootstrap overlay for a specific case. Called by
+ * `contract.bootstrap(ref, spec)`.
+ *
+ * Throws if another overlay is already registered for the same testId.
+ */
+export function registerBootstrap(ref, spec) {
+    const testId = `${ref.contractId}.${ref.caseKey}`;
+    if (_bootstrapRegistry.has(testId)) {
+        throw new Error(`contract.bootstrap: duplicate overlay for case "${testId}". ` +
+            `Only one bootstrap overlay per case is allowed. ` +
+            `If you need multiple variants, use the \`bootstrap.params\` schema.`);
+    }
+    _bootstrapRegistry.set(testId, {
+        testId,
+        contractId: ref.contractId,
+        caseKey: ref.caseKey,
+        protocol: ref.protocol,
+        spec: spec,
+    });
+    return {
+        __glubean_type: "bootstrap-attachment",
+        testId,
+    };
+}
+/** Look up a bootstrap registration by testId. Returns undefined if none. */
+export function getBootstrap(testId) {
+    return _bootstrapRegistry.get(testId);
+}
+/** Enumerate all registered bootstrap overlays. Used by scanner / CLI list. */
+export function listBootstraps() {
+    return [..._bootstrapRegistry.values()];
+}
+/** Test-only: clear the registry between test runs. Not part of public API. */
+export function clearBootstrapRegistry() {
+    _bootstrapRegistry.clear();
+}
+//# sourceMappingURL=bootstrap-registry.js.map

package/dist/bootstrap-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap-registry.js","sourceRoot":"","sources":["../src/bootstrap-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAgBH,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAAiC,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,GAAoC,EACpC,IAA8B;IAE9B,MAAM,MAAM,GAAG,GAAG,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;IAElD,IAAI,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CACb,mDAAmD,MAAM,KAAK;YAC5D,kDAAkD;YAClD,qEAAqE,CACxE,CAAC;IACJ,CAAC;IAED,kBAAkB,CAAC,GAAG,CAAC,MAAM,EAAE;QAC7B,MAAM;QACN,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,IAAI,EAAE,IAAmC;KAC1C,CAAC,CAAC;IAEH,OAAO;QACL,cAAc,EAAE,sBAAsB;QACtC,MAAM;KAC+B,CAAC;AAC1C,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,YAAY,CAC1B,MAAc;IAEd,OAAO,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACxC,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,cAAc;IAC5B,OAAO,CAAC,GAAG,kBAAkB,CAAC,MAAM,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,sBAAsB;IACpC,kBAAkB,CAAC,KAAK,EAAE,CAAC;AAC7B,CAAC"}

package/dist/contract-core.d.ts

@@ -19,7 +19,7 @@
  *   - `internal/40-discovery/proposals/contract-flow.md` v9
  */
 import type { TestContext } from "./types.js";
-import type { ContractProtocolAdapter, ExtractedFlowProjection, FieldMapping, FlowBuilder, FlowContract, FlowMeta, RuntimeFlowProjection } from "./contract-types.js";
+import type { Bootstrap, BootstrapAttachment, ContractCaseRef, ContractProtocolAdapter, ExtractedFlowProjection, FieldMapping, FlowBuilder, FlowContract, FlowMeta, RuntimeFlowProjection } from "./contract-types.js";
 /** Internal accessor for plugins / downstream (scanner, runner). */
 export declare function getAdapter(protocol: string): ContractProtocolAdapter<any, any, any, any, any> | undefined;
 /**
@@ -62,8 +62,20 @@ declare function register<Spec, RuntimeSchemas = unknown, RuntimeMeta = unknown,
 type ContractNamespace = {
     register: typeof register;
     flow: typeof flow;
+    bootstrap: typeof bootstrap;
     [protocol: string]: unknown;
 };
+/**
+ * Register a bootstrap overlay for a contract case. Standalone-only
+ * execution path; flow NEVER invokes bootstrap (non-negotiable invariant
+ * from attachment model §0.4 / §14.0).
+ *
+ * `NoInfer<Needs>` on the spec parameter prevents TypeScript's multi-site
+ * inference from silently accepting a mismatched `run` return type —
+ * without it, TS merges inferences from ref + spec and produces a
+ * compatible Needs, masking real type errors (Spike 0 Finding 1).
+ */
+export declare function bootstrap<Needs, Params = void>(ref: ContractCaseRef<Needs, unknown>, spec: Bootstrap<Params, NoInfer<Needs>>): BootstrapAttachment<Needs, Params>;
 export declare const contract: ContractNamespace;
 /**
  * Protocol-agnostic flow builder. See contract-flow.md v9 §4.1.

package/dist/contract-core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract-core.d.ts","sourceRoot":"","sources":["../src/contract-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAQ,WAAW,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAGV,uBAAuB,EAGvB,uBAAuB,EAEvB,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,QAAQ,EAKR,qBAAqB,EAEtB,MAAM,qBAAqB,CAAC;AAS7B,oEAAoE;AACpE,wBAAgB,UAAU,CACxB,QAAQ,EAAE,MAAM,GACf,uBAAuB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,SAAS,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,EAAE,CAElD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAIrE;AAED;;;;;;;GAOG;AACH,wBAAgB,gCAAgC,IAAI,IAAI,CAIvD;AAaD;;;;;GAKG;AACH,iBAAS,QAAQ,CACf,IAAI,EACJ,cAAc,GAAG,OAAO,EACxB,WAAW,GAAG,OAAO,EACrB,WAAW,GAAG,OAAO,EACrB,QAAQ,GAAG,OAAO,EAElB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,uBAAuB,CAAC,IAAI,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,CAAC,GACzF,IAAI,CAgBN;AAwOD,KAAK,iBAAiB,GAAG;IACvB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,IAAI,EAAE,OAAO,IAAI,CAAC;IAClB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC7B,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,iBAGtB,CAAC;AAMF;;GAEG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,CAqJtE;AAyBD;;;GAGG;AACH,wBAAsB,OAAO,CAAC,KAAK,EACjC,YAAY,EAAE,YAAY,CAAC,KAAK,CAAC,EACjC,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,IAAI,CAAC,CAuEf;AAMD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EACjC,OAAO,EAAE,qBAAqB,CAAC,KAAK,CAAC,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GACrD,uBAAuB,CAoEzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,GAAG,GAAG,YAAY,EAAE,CAIvE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,KAAK,GAAG,GACrC,YAAY,EAAE,CAMhB;AAkED;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBACf,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAY5C;AAiDD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,GAAG,GACtB;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAavC"}
+{"version":3,"file":"contract-core.d.ts","sourceRoot":"","sources":["../src/contract-core.ts"],"names":[],"mappings":"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"}

package/dist/contract-core.js

@@ -19,6 +19,64 @@
  *   - `internal/40-discovery/proposals/contract-flow.md` v9
  */
 import { registerTest } from "./internal.js";
+import { getBootstrap, registerBootstrap } from "./bootstrap-registry.js";
+import { getExplicitInput, getBootstrapInput, isForceStandalone, } from "./runner-input-channel.js";
+/**
+ * Validate a value against a `needs` schema. Used by the v10 attachment model
+ * dispatcher after bootstrap overlay produces `resolvedInput` — before passing
+ * to `adapter.executeCase`. Keeps the invariant that adapter receives
+ * already-validated input.
+ *
+ * Handles both SchemaLike flavors (safeParse preferred, parse fallback).
+ * When neither is present, passes value through — the schema was purely
+ * type-level and carries no runtime check.
+ */
+/**
+ * Run all registered cleanup callbacks in LIFO order. Each cleanup error is
+ * reported via console.error and does NOT mask the primary failure (the
+ * caller has already thrown or will throw whatever brought them here).
+ *
+ * Used by the v10 dispatcher's overlay path — same helper in all three
+ * failure sites (bootstrap run threw, needs validation failed, executeCase
+ * threw / succeeded). Before v3 feedback, the first two paths swallowed
+ * cleanup errors silently; this helper unifies reporting.
+ *
+ * Cleanup error reporting is `console.error` today. Spike 3 routes it
+ * through structured events so CI/agent consumers see it in test output.
+ */
+async function runCleanupsLifo(cleanups, testId) {
+    while (cleanups.length > 0) {
+        const cleanup = cleanups.pop();
+        try {
+            await cleanup();
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.error(`bootstrap cleanup error for ${testId}:`, err);
+        }
+    }
+}
+function validateNeedsOutput(needsSchema, value, ctx) {
+    const sp = needsSchema.safeParse;
+    if (typeof sp === "function") {
+        const result = sp(value);
+        if (result.success)
+            return result.data;
+        const lines = result.error.issues.map((i) => `  - ${i.path?.join(".") ?? "<root>"}: ${i.message}`);
+        const sourceLabel = ctx.source === "bootstrap" ? "Bootstrap output"
+            : ctx.source === "explicit" ? "Explicit input"
+                : ctx.source === "bootstrap-params" ? "Bootstrap params"
+                    : "Flow `in` output";
+        const schemaLabel = ctx.source === "bootstrap-params" ? "params schema" : "needs schema";
+        throw new Error(`${sourceLabel} for case "${ctx.testId}" does not satisfy ${schemaLabel}:\n${lines.join("\n")}`);
+    }
+    const p = needsSchema.parse;
+    if (typeof p === "function") {
+        return p(value);
+    }
+    // Schema declares neither safeParse nor parse — type-level only, pass through.
+    return value;
+}
 // =============================================================================
 // Adapter registry
 // =============================================================================
@@ -88,6 +146,10 @@ function register(protocol, adapter) {
     }
     _adapters.set(protocol, adapter);
     // Attach contract[protocol] dispatcher dynamically.
+    // Generic `Cases` preserves per-case Needs/Output through ProtocolContract
+    // so `.case("key")` returns a properly-typed ContractCaseRef. Without this,
+    // `contract.bootstrap(ref, { run })` cannot type-check the run return
+    // against the specific case's needs.
     contract[protocol] = (id, spec) => {
         return dispatchContract(protocol, adapter, id, spec);
     };
@@ -106,6 +168,11 @@ function dispatchContract(protocol, adapter, id, spec) {
     };
     // 1:1 key invariant between spec.cases and projection.cases
     validateCaseKeys(protocol, spec.cases ?? {}, projection.cases);
+    // Forward-declared carrier reference. Populated below via Object.assign and
+    // captured by each test.fn closure so that v10 bootstrap overlay dispatch
+    // can pass `contract` to `adapter.executeCase({ ..., contract, ... })` at
+    // runtime. Safe because fn closures only execute after contractObj is set.
+    let contractObj;
     const cases = spec.cases ?? {};
     const contractTagsRaw = spec.tags;
     const contractTags = Array.isArray(contractTagsRaw)
@@ -157,6 +224,201 @@ function dispatchContract(protocol, adapter, id, spec) {
                     ctx.skip(skipDeprecated);
                 if (skipDeferred)
                     ctx.skip(skipDeferred);
+                // ── §5.1 runnable resolution algorithm ───────────────────────────
+                //
+                // Step 1: explicit input wins over everything.
+                //   - case has needs → validate, run raw with that input
+                //   - case has no needs → reject (input has no schema target)
+                // Step 2: requireAttachment + no overlay → hard error
+                //   (bypassed by setForceStandalone via internal channel; debug only)
+                // Step 3: overlay registered → run overlay path; bootstrap params
+                //   come from getBootstrapInput; validated against overlay's
+                //   `params` schema if structured form
+                // Step 4: needs declared, no overlay, no input → hard error
+                // Step 5: no needs, no overlay → run raw with no input
+                //
+                // The order below mirrors §5.1 exactly. Tests for each path live
+                // in `contract.test.ts` (search "§5.1").
+                const needsSchema = caseSpec.needs;
+                const requireAttachment = caseSpec.runnability?.requireAttachment;
+                // §5.1 Step 1 — explicit input always wins. Bootstrap overlay (even
+                // if registered) is NOT invoked. No "run bootstrap for side-effects
+                // then use my input" mode (per §5.1 invariants).
+                const explicit = getExplicitInput(testId);
+                if (explicit.has) {
+                    if (!needsSchema) {
+                        const requireHint = requireAttachment
+                            ? " Use --force-standalone for debug, or attach a bootstrap."
+                            : "";
+                        throw new Error(`case "${testId}" has no \`needs\` schema; explicit input is ` +
+                            `meaningless (no schema to satisfy).${requireHint}`);
+                    }
+                    if (!contractObj) {
+                        throw new Error(`Internal: contract carrier not assembled when running "${testId}".`);
+                    }
+                    if (!adapter.executeCase) {
+                        throw new Error(`Explicit input provided for "${testId}" but the adapter for ` +
+                            `protocol "${protocol}" has not been migrated to the ` +
+                            `attachment model (missing executeCase method).`);
+                    }
+                    const validatedInput = validateNeedsOutput(needsSchema, explicit.value, { testId, source: "explicit" });
+                    await adapter.executeCase({
+                        ctx,
+                        contract: contractObj,
+                        caseKey,
+                        resolvedInput: validatedInput,
+                    });
+                    return;
+                }
+                // §5.1 Step 3 — overlay path. Step 2 (requireAttachment + no
+                // overlay) is handled in the no-overlay branch below.
+                const overlay = getBootstrap(testId);
+                if (overlay) {
+                    // Hard error if adapter hasn't implemented the attachment-model
+                    // entry point. Better to fail loudly at dispatch than to run the
+                    // raw case as if no overlay existed.
+                    if (!adapter.executeCase) {
+                        throw new Error(`Bootstrap overlay registered for "${testId}" but the adapter ` +
+                            `for protocol "${protocol}" has not been migrated to the ` +
+                            `attachment model (missing executeCase method). The overlay ` +
+                            `would be silently ignored. Either remove the overlay or ` +
+                            `migrate the adapter runtime.`);
+                    }
+                    if (!contractObj) {
+                        // Unreachable at fn-call time (contractObj is assigned before
+                        // any test.fn runs). Defensive check keeps TS narrowing clean.
+                        throw new Error(`Internal: contract carrier not assembled when running "${testId}".`);
+                    }
+                    const cleanups = [];
+                    const bootstrapCtx = Object.assign(Object.create(ctx), ctx, {
+                        cleanup(fn) {
+                            cleanups.push(fn);
+                        },
+                    });
+                    const runFn = typeof overlay.spec === "function"
+                        ? overlay.spec
+                        : overlay.spec.run;
+                    // §5.1 step 3a-3b: structured-form `params` schema validation.
+                    // Bootstrap input comes from the runner channel (CLI
+                    // `--bootstrap-json`, MCP `bootstrapInput`, programmatic
+                    // `bootstrapInput`).
+                    const paramsSchema = typeof overlay.spec === "object" && overlay.spec !== null
+                        ? overlay.spec.params
+                        : undefined;
+                    const providedBootstrap = getBootstrapInput(testId);
+                    // Plain-function overlay (or structured form without `params`)
+                    // does NOT accept bootstrap input. If the runner supplied one,
+                    // the user almost certainly forgot to declare a `params` schema
+                    // or mistyped the testId — silently dropping the input would
+                    // mask the bug. Hard-error before invoking run().
+                    if (!paramsSchema && providedBootstrap.has) {
+                        throw new Error(`case "${testId}": runner supplied bootstrap input but the ` +
+                            `registered overlay does not declare a \`params\` schema. ` +
+                            `Plain-function overlays (and structured overlays without ` +
+                            `\`params\`) cannot consume bootstrap input — declare ` +
+                            `\`params: SchemaLike<...>\` on the overlay spec, or remove ` +
+                            `the bootstrap input from the runner invocation.`);
+                    }
+                    let validatedParams = undefined;
+                    if (paramsSchema) {
+                        // §5.1 step 3a: "Take bootstrapInput from runner options
+                        // (may be empty if no params)". Validation happens whether
+                        // or not the runner supplied input — schema may have
+                        // defaults, or all fields may be optional.
+                        validatedParams = validateNeedsOutput(paramsSchema, providedBootstrap.has ? providedBootstrap.value : undefined, { testId, source: "bootstrap-params" });
+                    }
+                    let resolvedInput;
+                    try {
+                        resolvedInput = await runFn(bootstrapCtx, validatedParams);
+                    }
+                    catch (err) {
+                        await runCleanupsLifo(cleanups, testId);
+                        throw err;
+                    }
+                    // v10 Phase 2b Step 2: validate bootstrap output against `needs`
+                    // schema before handing off to adapter. Adapter's contract is
+                    // "receives already-validated input"; validation at the runner
+                    // boundary matches single-case-execution-api.md §7.
+                    if (needsSchema) {
+                        try {
+                            resolvedInput = validateNeedsOutput(needsSchema, resolvedInput, { testId, source: "bootstrap" });
+                        }
+                        catch (err) {
+                            await runCleanupsLifo(cleanups, testId);
+                            throw err;
+                        }
+                    }
+                    try {
+                        await adapter.executeCase({
+                            ctx,
+                            contract: contractObj,
+                            caseKey,
+                            resolvedInput,
+                        });
+                    }
+                    finally {
+                        await runCleanupsLifo(cleanups, testId);
+                    }
+                    return;
+                }
+                // ── No-overlay standalone path ───────────────────────────────────
+                //
+                // First: bootstrap input supplied but no overlay registered. The
+                // user provided `--bootstrap-json` / `bootstrapInput` for a case
+                // that has no `contract.bootstrap()`. Almost always a typo or a
+                // missing overlay file; silently dropping the input would mask
+                // the bug. Hard-error before any other resolution.
+                const providedBootstrapNoOverlay = getBootstrapInput(testId);
+                if (providedBootstrapNoOverlay.has) {
+                    throw new Error(`case "${testId}": runner supplied bootstrap input but no ` +
+                        `bootstrap overlay is registered for this case. Register an ` +
+                        `overlay via \`contract.bootstrap(ref, { params, run })\`, ` +
+                        `or remove the bootstrap input from the runner invocation. ` +
+                        `(If you meant to bypass the overlay and pass case input ` +
+                        `directly, use --input-json / inputJson instead.)`);
+                }
+                // §5.1 step 2: requireAttachment + no overlay → hard error
+                //   (UNLESS isForceStandalone(testId) — debug bypass per §6.3).
+                // §5.1 step 4: needs declared, no overlay, no input → hard error.
+                // §5.1 step 5: no needs, no overlay → run raw with no input.
+                //
+                // Order matters: step 2 fires before step 4 because requireAttachment
+                // is the stronger declaration ("don't run bare under any input
+                // condition"). A case with both needs + requireAttachment + no
+                // overlay + no input gets the requireAttachment error message,
+                // which carries the more actionable hint (attach a bootstrap or
+                // pass --input-json depending on needs presence).
+                if (requireAttachment) {
+                    if (isForceStandalone(testId)) {
+                        // §6.3 debug escape valve. Author opted out of the guard via
+                        // --force-standalone; emit a runtime warning so it's visible
+                        // in test output, then fall through to step 4/5.
+                        // eslint-disable-next-line no-console
+                        console.warn(`⚠ case "${testId}": bypassing runnability.requireAttachment ` +
+                            `via --force-standalone (debug). Do not use this in normal runs.`);
+                    }
+                    else {
+                        throw new Error(`case "${testId}" sets \`runnability.requireAttachment: true\` ` +
+                            `but no bootstrap overlay is registered. Per attachment model ` +
+                            `§7.2: register a bootstrap overlay via \`contract.bootstrap(...)\`, ` +
+                            `attach the case to a flow step, or pass \`--input-json\` (if ` +
+                            `the case declares \`needs\`). Raw execution is disabled for ` +
+                            `this case by its own declaration.`);
+                    }
+                }
+                // §5.1 step 4: needs case with no overlay + no input → hard error.
+                // (Step 1 already returned for cases with explicit input above.)
+                if (needsSchema) {
+                    throw new Error(`case "${testId}" declares \`needs\` but has no bootstrap overlay ` +
+                        `and no explicit input. Per attachment model §5.1: register a ` +
+                        `bootstrap overlay via \`contract.bootstrap(...)\`, or pass ` +
+                        `\`--input-json\` to provide explicit input.`);
+                }
+                // §5.1 step 5: no needs, no overlay (or requireAttachment+force-
+                // standalone) → run case with no input. Static body / headers /
+                // params / query work as-is; function-valued action fields receive
+                // undefined (author responsibility — typically a no-needs case has
+                // no function-valued fields).
                 await adapter.execute(ctx, caseSpec, spec);
             },
         };
@@ -205,14 +467,18 @@ function dispatchContract(protocol, adapter, id, spec) {
     // implement is a compile error, not a silent runtime hole.
     const extracted = adapter.normalize(enrichedProjection);
     const arr = [...tests];
-    const contractObj = Object.assign(arr, {
+    contractObj = Object.assign(arr, {
         _projection: enrichedProjection,
         _extracted: extracted,
         _spec: spec,
         case(key) {
-            // Delegate fail-fast validation to adapter (e.g. HTTP rejects
-            // function-valued body/params/query/headers).
-            adapter.validateCaseForFlow?.(spec, key, id);
+            // v10: .case(key) is pure case-ref creation — no flow-only validation
+            // here. Flow-safety checks (e.g. HTTP's "function-valued body/params/
+            // headers can't be resolved in flow mode") moved to FlowBuilder.step()
+            // where the ref's flow usage is actually being declared. The same
+            // ref used via contract.bootstrap(overlay) legitimately uses
+            // function-valued fields with `resolvedInput` — v9's
+            // validateCaseForFlow incorrectly rejected that at .case() time.
             return makeContractCaseRef(protocol, id, projection.target, key, contractObj, spec);
         },
     });
@@ -261,9 +527,23 @@ function makeContractCaseRef(protocol, contractId, target, caseKey, contract, _s
         contract,
     };
 }
+/**
+ * Register a bootstrap overlay for a contract case. Standalone-only
+ * execution path; flow NEVER invokes bootstrap (non-negotiable invariant
+ * from attachment model §0.4 / §14.0).
+ *
+ * `NoInfer<Needs>` on the spec parameter prevents TypeScript's multi-site
+ * inference from silently accepting a mismatched `run` return type —
+ * without it, TS merges inferences from ref + spec and produces a
+ * compatible Needs, masking real type errors (Spike 0 Finding 1).
+ */
+export function bootstrap(ref, spec) {
+    return registerBootstrap(ref, spec);
+}
 export const contract = {
     register,
     flow,
+    bootstrap,
 };
 // =============================================================================
 // Flow: FlowBuilder + runFlow + normalizeFlow + tracePureFn
@@ -304,6 +584,14 @@ export function flow(idOrMeta) {
                 throw new Error(`contract.flow(${JSON.stringify(meta.id)}).step: adapter for "${ref.protocol}" ` +
                     `does not implement executeCaseInFlow — this protocol cannot appear in a flow.`);
             }
+            // v10: flow-safety validation fires here (at step-declaration time),
+            // not at .case() time. The ref itself is pure; only when it enters a
+            // flow do we enforce adapter-specific rules like HTTP's "function-
+            // valued body/params/headers can't resolve in flow mode". This lets
+            // contract.bootstrap(ref) attach to the same ref (where function-
+            // valued fields legitimately receive resolvedInput).
+            const contractRef = ref.contract;
+            adapter.validateCaseForFlow?.(contractRef._spec, ref.caseKey, ref.contractId);
             const step = {
                 kind: "contract-call",
                 name: bindings?.name,
@@ -461,7 +749,43 @@ export async function runFlow(flowContract, ctx) {
                 throw new Error(`flow "${runtime.id}" step "${step.name ?? step.caseKey}": ` +
                     `adapter for "${step.ref.protocol}" does not implement executeCaseInFlow`);
             }
-            const resolvedInputs = step.bindings?.in?.(state);
+            // v10 Phase 2d Step 2+3 follow-up (RFR v2 / v2.1 P1): enforce `needs`
+            // schema at flow boundary, not just standalone. The conditional-tuple
+            // `step()` signature catches TS authoring shape mismatches, but runtime
+            // validation is the only line of defense against:
+            //   - `as any` / JS callers that bypass the TS check
+            //   - Zod parse / coerce / default semantics (schema can transform
+            //     the value, not just validate it)
+            //   - State drift producing invalid values at runtime despite valid
+            //     authoring types
+            // Standalone overlay path already validates via the same helper in
+            // `dispatchContract`'s test.fn closure; flow mirrors that to keep
+            // `needs` a true contract semantic rather than a TS-only boundary.
+            //
+            // Two-branch guard:
+            //   needs present + bindings.in missing  → throw (contract requires input)
+            //   needs present + bindings.in present  → validate unconditionally
+            //   needs absent                          → no guard
+            const contractSpec = step.contract._spec;
+            const caseSpec = contractSpec?.cases?.[step.caseKey];
+            const needsSchema = caseSpec?.needs;
+            const hasIn = typeof step.bindings?.in === "function";
+            if (needsSchema && !hasIn) {
+                throw new Error(`flow "${runtime.id}" step "${step.name ?? step.caseKey}": ` +
+                    `case "${step.ref.contractId}.${step.caseKey}" declares \`needs\` ` +
+                    `but the step has no \`bindings.in\`. The TypeScript conditional ` +
+                    `tuple on FlowBuilder.step() usually prevents this at compile time; ` +
+                    `this runtime check catches \`as any\` / JS bypass. Provide an ` +
+                    `\`in: (state) => <logical input>\` binding or remove the \`needs\` ` +
+                    `schema from the case.`);
+            }
+            let resolvedInputs = step.bindings?.in?.(state);
+            if (needsSchema) {
+                resolvedInputs = validateNeedsOutput(needsSchema, resolvedInputs, {
+                    testId: `${step.ref.contractId}.${step.caseKey}`,
+                    source: "flow",
+                });
+            }
             const response = await adapter.executeCaseInFlow({
                 ctx,
                 contract: step.contract,