@suluk/journeys 0.1.0 → 0.3.0

package/README.md

@@ -68,6 +68,33 @@ mutates the accessor in place during collision resolution, so accessor-keyed ide
 operation is added. (Witnessed on toolfactory's `api/billing/subscription`, which holds both `getSubscription` and
 `cancelSubscription`.)
 
+## Two-role authoring + composition (no developer)
+
+A non-technical author can write stories in their **own words** and hand them to a **scaffolder** (a more technical
+author — *not* a developer) who maps that free prose onto the runnable vocabulary. Neither role writes code.
+
+- **`detectUndefined(vocab, features, defs)`** is the scaffolder's worklist (Cucumber-style undefined-step detection,
+  resolved by *mapping* not coding). It splits each not-yet-runnable step into **"the scaffolder can define this"**
+  (an operation/step exists → alias or decompose) vs **"escalate to a developer"** (`NEEDS-CONTRACT` — no operation
+  backs it). `renderScaffold(...)` prints it with paste-ready stubs.
+- A **`Definitions`** artifact (author/scaffolder-owned data) turns prose into runnable steps three ways:
+  - **alias** — `"prose": "When I checkout"` (one canonical step)
+  - **decomposition** — `"I sign up and buy credits": ["Given I am a signed-in user", "When I checkout", "Then it succeeds"]`
+  - **journey** — a named, reusable sequence referenced from a story with `When I complete the "top up" journey`
+
+```ts
+const defs = {
+  steps: { "when i sign up and buy credits": ["Given I am a signed-in user", "When I checkout", "Then it succeeds"] },
+  journeys: { "top up": ["Given I am a signed-in user", "When I checkout", "Then it succeeds"] },
+};
+const report = bindFeatures(vocab, [story], { definitions: defs });   // composed + decomposed, all bound
+const todo = detectUndefined(vocab, [story], { definitions: defs });  // what still needs defining / escalation
+```
+
+**Composition** lets authors build bigger journeys out of existing ones (`complete the "…" journey`), and outcome
+steps bind to the **most-recent** action, so multi-step journeys bind each `Then` to its own `When`. The only thing
+that ever needs a developer is genuinely new backend capability (`NEEDS-CONTRACT`) — composition and mapping do not.
+
 ## Discovery (designed, gated)
 
 A semantic *reuse* search — "find an existing flow to reuse / modify / rebuild" — is designed (a deterministic

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/journeys",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Intuitive, runnable BDD over a v4 'Suluk' contract. Projects a deterministic Gherkin step VOCABULARY from the contract (Given from x-suluk-access, When from each operation, Then from declared statuses + x-suluk-store + x-suluk-cost), binds authored .feature stories EXACT-or-UNBOUND with outcome steps resolved relative to the scenario's When-subject, and emits a BIDIRECTIONAL tri-state gap report (PARAPHRASE / NEEDS-DEV-GLUE / NEEDS-CONTRACT) + contract->authored coverage holes. A pure function of the document. CANDIDATE tooling.",
   "publishConfig": {
     "access": "public"
@@ -16,9 +16,11 @@
   "type": "module",
   "main": "src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./hatch": "./src/hatch/index.ts"
   },
   "dependencies": {
+    "@suluk/cloudflare": "^0.2.0",
     "@suluk/core": "^0.1.13",
     "@suluk/sdk": "^0.2.2"
   },

package/src/bind.ts

@@ -1,24 +1,41 @@
 /**
- * The BINDER (C038): authored .feature steps → contract handles, plus the bidirectional, tri-state GAP report.
+ * The BINDER (C038): authored .feature steps → contract handles, the bidirectional tri-state GAP report, plus the
+ * TWO-ROLE authoring layer (a definitions/decomposition map + undefined detection) and named-journey COMPOSITION.
  *
  * The decision rule is EXACT-or-UNBOUND and statically decidable:
  *   - A step's skeleton equals a generated step skeleton → BOUND to that single stable handle.
- *   - Outcome (THEN) steps are resolved RELATIVE to the scenario's WHEN-subject (the operation the scenario is about),
- *     not via a global phrase→handle map — otherwise a generic "Then it succeeds" (shared by ~every op) mis-binds to
- *     an arbitrary one. This subject-relative rule is the spike-witnessed correction on the toolfactory contract.
- *   - Otherwise the step is UNBOUND, then DETERMINISTICALLY classified into a tri-state for a human:
- *       PARAPHRASE (an author-owned alias resolves it — no dev), NEEDS-DEV-GLUE (an operation exists but no step wires
- *       it), NEEDS-CONTRACT (nothing backs the intent — a dev extends the contract).
- *   - A WHEN phrase shared by >1 operation is AMBIGUOUS (a disambiguation the projector must resolve).
+ *   - Outcome (THEN) steps resolve relative to the MOST-RECENT bound WHEN (the action currently in play) — so a generic
+ *     "Then it succeeds" never mis-binds, AND a multi-step / composed journey binds each outcome to its own action.
+ *   - Otherwise the step is UNBOUND, then DETERMINISTICALLY classified for a human: PARAPHRASE (an alias resolves it,
+ *     no dev), NEEDS-DEV-GLUE (an operation exists but no step wires it), NEEDS-CONTRACT (nothing backs it — a dev
+ *     extends the contract). A WHEN phrase shared by >1 operation is AMBIGUOUS; a ref to an undefined journey is UNDEFINED.
+ *
+ * TWO ROLES (no developer for either): a NON-TECHNICAL author writes stories in their own words; a SCAFFOLDER maps that
+ * free prose onto the runnable vocabulary via a `Definitions` artifact — an ALIAS (prose → one canonical step), a
+ * DECOMPOSITION (prose → a sequence of canonical steps), or a named JOURNEY (composed by reference). `detectUndefined`
+ * tells the scaffolder exactly what is not yet runnable, and whether they can define it or must escalate to a developer.
  *
  * No scoring/lemmatization/embedding EVER decides a bind. Token similarity appears ONLY to rank the presentational
  * "did you mean?" suggestion on an already-UNBOUND step.
  */
 import { camel, jaccard, norm, tok } from "./normalize";
-import type { FeatureStep, Feature } from "./gherkin";
+import type { FeatureStep, Feature, StepKind } from "./gherkin";
 import type { JourneyStep, Vocabulary } from "./vocabulary";
 
-export type BindState = "BOUND" | "PARAPHRASE" | "NEEDS-DEV-GLUE" | "NEEDS-CONTRACT" | "AMBIGUOUS";
+export type BindState = "BOUND" | "PARAPHRASE" | "NEEDS-DEV-GLUE" | "NEEDS-CONTRACT" | "AMBIGUOUS" | "UNDEFINED";
+
+/**
+ * The SCAFFOLDER's mapping layer (author-owned data, no developer). Turns a non-technical author's free prose into
+ * runnable Gherkin without touching code.
+ */
+export interface Definitions {
+  /** a free-prose step (normalized) → a canonical generated phrase (ALIAS) OR an ordered list of canonical phrases
+   *  (manual DECOMPOSITION). Each canonical phrase carries its keyword, e.g. "When I checkout" / "Then it succeeds". */
+  steps?: Record<string, string | string[]>;
+  /** named JOURNEYS for composition: a journey name → an ordered list of step phrases (each itself bound or defined).
+   *  Referenced from a story with `When I complete the "<name>" journey`. */
+  journeys?: Record<string, string[]>;
+}
 
 export interface StepResult {
   step: FeatureStep;
@@ -29,12 +46,16 @@ export interface StepResult {
   via: string;
   /** a human next-action for a non-BOUND step. */
   suggest: string;
+  /** when this resolved step came from an alias/decomposition/journey expansion: the original authored prose it expanded from. */
+  expandedFrom?: { text: string; line: number };
+  /** the canonical step phrase this UNBOUND step most likely maps to (drives the scaffolder's alias stub). */
+  canonical?: string;
 }
 
 export interface ScenarioResult {
   scenario: string;
   rule?: string;
-  /** the resolved subject operation handle (the scenario's When-op), if any. */
+  /** the FIRST bound When-op handle (a label/back-compat handle; outcomes bind to the most-recent When, see results). */
   subject: string;
   results: StepResult[];
 }
@@ -57,17 +78,32 @@ export interface GapReport {
 }
 
 export interface BindOptions {
-  /** an author-owned synonym map: normalized authored skeleton → a canonical generated skeleton. Resolves PARAPHRASE without a dev. */
+  /** shorthand for `definitions.steps` with 1:1 string values — an author-owned synonym map. Merged into definitions. */
   aliases?: Record<string, string>;
+  /** the scaffolder's full mapping layer (aliases + decompositions + named journeys). */
+  definitions?: Definitions;
   /** how many coverage-hole stubs to emit (default: all). */
   maxHoles?: number;
 }
 
+// ---- a step after alias/decomposition/journey expansion ----
+interface ResolvedStep {
+  kind: StepKind;
+  text: string;
+  raw: string;
+  line: number;
+  /** set when produced by expanding an alias / decomposition / journey. */
+  origin?: { text: string; line: number };
+  /** set when a journey-ref names a journey that is not defined. */
+  undefinedJourney?: string;
+}
+
 interface Indexes {
   whenBySkeleton: Map<string, JourneyStep[]>;
   thenByHandle: Map<string, Set<string>>;
   givenSkeletons: Set<string>;
   whenSteps: JourneyStep[];
+  whenByHandle: Map<string, JourneyStep>;
 }
 
 function buildIndexes(vocab: Vocabulary): Indexes {
@@ -75,94 +111,143 @@ function buildIndexes(vocab: Vocabulary): Indexes {
   const thenByHandle = new Map<string, Set<string>>();
   const givenSkeletons = new Set<string>();
   const whenSteps: JourneyStep[] = [];
+  const whenByHandle = new Map<string, JourneyStep>();
   for (const s of vocab.steps) {
     if (s.kind === "given") givenSkeletons.add(s.skeleton);
     else if (s.kind === "when") {
       (whenBySkeleton.get(s.skeleton) ?? whenBySkeleton.set(s.skeleton, []).get(s.skeleton)!).push(s);
       whenSteps.push(s);
+      whenByHandle.set(s.handle, s);
     } else {
       (thenByHandle.get(s.handle) ?? thenByHandle.set(s.handle, new Set()).get(s.handle)!).add(s.skeleton);
     }
   }
-  return { whenBySkeleton, thenByHandle, givenSkeletons, whenSteps };
+  return { whenBySkeleton, thenByHandle, givenSkeletons, whenSteps, whenByHandle };
+}
+
+function mergeDefinitions(opts: BindOptions): Definitions {
+  const steps: Record<string, string | string[]> = { ...opts.aliases, ...opts.definitions?.steps };
+  return { steps, journeys: opts.definitions?.journeys ?? {} };
+}
+
+/** Parse 'complete the "<name>" journey' (and a couple of natural variants) → the journey name, else null. */
+function journeyRefName(text: string): string | null {
+  const m = /(?:complete[sd]?|run|do|perform|go through)\s+the\s+["“](.+?)["”]\s+journey/i.exec(text) || /the\s+["“](.+?)["”]\s+journey\s+(?:is|has|was)\s+(?:done|completed|complete)/i.exec(text);
+  return m ? m[1].trim() : null;
 }
 
-const res = (step: FeatureStep, state: BindState, handle = "", via = "", suggest = ""): StepResult => ({ step, state, handle, via, suggest });
+/** Parse a canonical phrase ("When I checkout" / "And it succeeds") into a step, inheriting `last` for And/But. */
+function phraseToStep(phrase: string, last: StepKind, origin: { text: string; line: number }): { step: ResolvedStep; kind: StepKind } {
+  const m = /^(given|when|then|and|but)\b\s*(.*)$/i.exec(phrase.trim());
+  const kw = m ? m[1].toLowerCase() : last;
+  const text = m ? m[2] : phrase.trim();
+  const kind: StepKind = kw === "given" || kw === "when" || kw === "then" ? (kw as StepKind) : last;
+  return { step: { kind, text, raw: phrase.trim(), line: origin.line, origin }, kind };
+}
+
+function phrasesToSteps(phrases: string[], origin: { text: string; line: number }): ResolvedStep[] {
+  const out: ResolvedStep[] = [];
+  let last: StepKind = "given";
+  for (const p of phrases) {
+    const { step, kind } = phraseToStep(p, last, origin);
+    last = kind;
+    out.push(step);
+  }
+  return out;
+}
+
+/** Expand a scenario's authored steps by applying aliases / decompositions / named-journey references. */
+function expandScenario(steps: FeatureStep[], defs: Definitions): ResolvedStep[] {
+  const out: ResolvedStep[] = [];
+  for (const s of steps) {
+    const origin = { text: s.text, line: s.line };
+    const jname = journeyRefName(s.text);
+    if (jname) {
+      const journey = defs.journeys?.[jname];
+      if (journey) out.push(...phrasesToSteps(journey, origin));
+      else out.push({ kind: s.kind, text: s.text, raw: s.raw, line: s.line, undefinedJourney: jname });
+      continue;
+    }
+    const def = defs.steps?.[norm(`${s.kind} ${s.text}`)];
+    if (Array.isArray(def)) out.push(...phrasesToSteps(def, origin));
+    else if (typeof def === "string") out.push(phraseToStep(def, s.kind, origin).step);
+    else out.push({ kind: s.kind, text: s.text, raw: s.raw, line: s.line });
+  }
+  return out;
+}
+
+const res = (step: FeatureStep, state: BindState, extra: Partial<StepResult> = {}): StepResult => ({ step, state, handle: "", via: "", suggest: "", ...extra });
+
+const whenPhraseOf = (handle: string, idx: Indexes): string => idx.whenByHandle.get(handle)?.phrase ?? "";
 
 function classifyUnbound(step: FeatureStep, vocab: Vocabulary, idx: Indexes): StepResult {
   const st = tok(step.text);
-  // best WHEN phrase (paraphrase suggestion) — presentational only.
   let best: { s: JourneyStep; score: number } | null = null;
   for (const w of idx.whenSteps) {
     const score = jaccard(st, tok(w.phrase));
     if (!best || score > best.score) best = { s: w, score };
   }
-  if (best && best.score >= 0.6) return res(step, "PARAPHRASE", best.s.handle, "", `try "${best.s.phrase}" — or add it to your alias map (no dev)`);
-  // does any operation relate? (a real op exists, but no generated phrase matches the author's wording)
-  let opBest: { op: { handle: string; name: string; method: string; path: string }; score: number } | null = null;
+  if (best && best.score >= 0.6) return res(step, "PARAPHRASE", { handle: best.s.handle, canonical: best.s.phrase, suggest: `alias to "${best.s.phrase}" (no dev)` });
+  let opBest: { handle: string; name: string; method: string; path: string; score: number } | null = null;
   for (const op of vocab.operations) {
     const score = jaccard(st, tok(camel(op.name)));
-    if (!opBest || score > opBest.score) opBest = { op, score };
+    if (!opBest || score > opBest.score) opBest = { ...op, score };
   }
-  if (opBest && opBest.score >= 0.34) return res(step, "NEEDS-DEV-GLUE", opBest.op.handle, "", `relates to '${opBest.op.name}' (${opBest.op.method.toUpperCase()} ${opBest.op.path}) — wire or alias a step`);
-  return res(step, "NEEDS-CONTRACT", "", "", "no operation backs this intent — a developer adds it to the contract");
+  if (opBest && opBest.score >= 0.34) return res(step, "NEEDS-DEV-GLUE", { handle: opBest.handle, canonical: whenPhraseOf(opBest.handle, idx), suggest: `relates to '${opBest.name}' (${opBest.method.toUpperCase()} ${opBest.path}) — define a step that maps here` });
+  return res(step, "NEEDS-CONTRACT", { suggest: "no operation backs this intent — escalate to a developer to add it to the contract" });
 }
 
-function bindStep(step: FeatureStep, subject: string, vocab: Vocabulary, idx: Indexes, aliases: Record<string, string>): StepResult {
-  let skel = norm(`${step.kind} ${step.text}`); // resolved keyword (And/But already folded by the parser)
-  if (aliases[skel]) skel = aliases[skel]; // author-owned alias layer (presentational; never widens the matcher)
-
-  if (step.kind === "given") {
-    if (idx.givenSkeletons.has(skel)) return res(step, "BOUND", "@access:authenticated", "x-suluk-access");
-    return classifyUnbound(step, vocab, idx);
+function bindResolved(rs: ResolvedStep, subject: string, vocab: Vocabulary, idx: Indexes): StepResult {
+  const step: FeatureStep = { kind: rs.kind, text: rs.text, raw: rs.raw, line: rs.line };
+  const tag = (r: StepResult): StepResult => (rs.origin ? { ...r, expandedFrom: rs.origin } : r);
+  if (rs.undefinedJourney) return tag(res(step, "UNDEFINED", { suggest: `journey "${rs.undefinedJourney}" is not defined — add it to definitions.journeys (no dev)` }));
+  const skel = norm(`${rs.kind} ${rs.text}`);
+  if (rs.kind === "given") {
+    if (idx.givenSkeletons.has(skel)) return tag(res(step, "BOUND", { handle: "@access:authenticated", via: "x-suluk-access" }));
+    return tag(classifyUnbound(step, vocab, idx));
   }
-  if (step.kind === "when") {
+  if (rs.kind === "when") {
     const hit = idx.whenBySkeleton.get(skel);
-    if (hit && hit.length === 1) return res(step, "BOUND", hit[0].handle, hit[0].via);
-    if (hit && hit.length > 1) return res(step, "AMBIGUOUS", "", "", `${hit.length} operations render this phrase — the projector must disambiguate`);
-    return classifyUnbound(step, vocab, idx);
+    if (hit && hit.length === 1) return tag(res(step, "BOUND", { handle: hit[0].handle, via: hit[0].via }));
+    if (hit && hit.length > 1) return tag(res(step, "AMBIGUOUS", { suggest: `${hit.length} operations render this phrase — the projector must disambiguate` }));
+    return tag(classifyUnbound(step, vocab, idx));
   }
-  // THEN — bind relative to the scenario subject.
-  const thens = idx.thenByHandle.get(subject);
-  if (thens?.has(skel)) return res(step, "BOUND", subject, "outcome of the scenario's When-subject");
-  return classifyUnbound(step, vocab, idx);
+  // THEN — bind relative to the most-recent bound When subject.
+  if (subject && idx.thenByHandle.get(subject)?.has(skel)) return tag(res(step, "BOUND", { handle: subject, via: "outcome of the current When-subject" }));
+  return tag(classifyUnbound(step, vocab, idx));
 }
 
-/** Bind a parsed feature set against the vocabulary and produce the bidirectional gap report. */
+/** Bind a parsed feature set against the vocabulary (applying the scaffolder's definitions) and produce the gap report. */
 export function bindFeatures(vocab: Vocabulary, features: Feature[], opts: BindOptions = {}): GapReport {
   const idx = buildIndexes(vocab);
-  const aliases = opts.aliases ?? {};
+  const defs = mergeDefinitions(opts);
   const scenarios: ScenarioResult[] = [];
-  const counts: Record<BindState, number> = { BOUND: 0, PARAPHRASE: 0, "NEEDS-DEV-GLUE": 0, "NEEDS-CONTRACT": 0, AMBIGUOUS: 0 };
+  const counts: Record<BindState, number> = { BOUND: 0, PARAPHRASE: 0, "NEEDS-DEV-GLUE": 0, "NEEDS-CONTRACT": 0, AMBIGUOUS: 0, UNDEFINED: 0 };
   const coveredWhen = new Set<string>();
 
   for (const feat of features) {
     for (const sc of feat.scenarios) {
-      // subject = the first When-step that binds to exactly one operation.
-      let subject = "";
-      for (const step of sc.steps) {
-        if (step.kind !== "when") continue;
-        const hit = idx.whenBySkeleton.get(norm(`when ${step.text}`));
-        if (hit && hit.length === 1) {
-          subject = hit[0].handle;
-          break;
-        }
-      }
-      const results = sc.steps.map((step) => {
-        const r = bindStep(step, subject, vocab, idx, aliases);
+      const resolved = expandScenario(sc.steps, defs);
+      let subject = ""; // most-recent bound When
+      let firstSubject = "";
+      const results = resolved.map((rs) => {
+        const r = bindResolved(rs, subject, vocab, idx);
         counts[r.state]++;
-        if (r.state === "BOUND" && step.kind === "when") coveredWhen.add(r.handle);
+        if (r.state === "BOUND" && rs.kind === "when") {
+          subject = r.handle;
+          if (!firstSubject) firstSubject = r.handle;
+          coveredWhen.add(r.handle);
+        }
         return r;
       });
-      scenarios.push({ scenario: sc.name, rule: sc.rule, subject, results });
+      scenarios.push({ scenario: sc.name, rule: sc.rule, subject: firstSubject, results });
     }
   }
 
   // direction (ii): contract → authored coverage holes.
-  const whenByHandle = new Map(idx.whenSteps.map((s) => [s.handle, s]));
   const holesAll = vocab.operations.filter((op) => !coveredWhen.has(op.handle));
   const holes: CoverageHole[] = holesAll.slice(0, opts.maxHoles ?? holesAll.length).map((op) => {
-    const when = whenByHandle.get(op.handle);
+    const when = idx.whenByHandle.get(op.handle);
     const given = op.access === "authenticated" ? "    Given I am a signed-in user\n" : "";
     return { handle: op.handle, name: op.name, stub: `  Scenario: cover ${op.name}\n${given}    ${when?.phrase ?? "When I " + camel(op.name)}\n    Then it succeeds` };
   });
@@ -170,14 +255,94 @@ export function bindFeatures(vocab: Vocabulary, features: Feature[], opts: BindO
   return { scenarios, counts, coverage: { total: vocab.operations.length, covered: vocab.operations.length - holesAll.length, holes } };
 }
 
+// ---- the SCAFFOLDER's tooling: detect what is not yet runnable ----
+export interface UndefinedStep {
+  scenario: string;
+  /** the original authored prose (the non-technical author's words). */
+  text: string;
+  line: number;
+  /**
+   * How to make it run. NONE of these requires a developer EXCEPT where the scaffolder, on review, finds no operation
+   * provides the capability — then they escalate. The tool only ever SUGGESTS; it never asserts "a developer is required",
+   * because absence of a lexical match is not evidence the capability is missing.
+   *  - `alias` — a confident 1:1 target was found (a paraphrase of a generated step).
+   *  - `map` — a related operation was found; map it (alias or decompose) to that op's steps.
+   *  - `review` — no automatic match; the scaffolder maps it from the phrasebook, or escalates only if nothing backs it.
+   *  - `define-journey` — a reference to a journey that is not defined yet.
+   */
+  resolution: "alias" | "map" | "review" | "define-journey";
+  /** a paste-ready definitions stub (or, for `review`, the honest "decide" note). */
+  suggestion: string;
+}
+
+/**
+ * Detect every authored step that is not yet runnable — the scaffolder's worklist (Cucumber-style "undefined steps",
+ * here resolved by MAPPING, not by writing code). It SUGGESTS a target when there is a lexical signal and otherwise
+ * defers to the scaffolder; it never falsely claims a developer is required (absence of a word-match ≠ missing
+ * capability). Reports against the ORIGINAL prose, deduped.
+ */
+export function detectUndefined(vocab: Vocabulary, features: Feature[], opts: BindOptions = {}): UndefinedStep[] {
+  const report = bindFeatures(vocab, features, opts);
+  const out: UndefinedStep[] = [];
+  const seen = new Set<string>();
+  for (const sc of report.scenarios) {
+    for (const r of sc.results) {
+      if (r.state === "BOUND") continue;
+      const prose = r.expandedFrom?.text ?? r.step.text;
+      const line = r.expandedFrom?.line ?? r.step.line;
+      const key = `${sc.scenario}::${norm(prose)}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const skel = norm(`${r.step.kind} ${prose}`);
+      const stub = (target: string) => `definitions.steps: { ${JSON.stringify(skel)}: ${JSON.stringify(target)} }  // or an array to decompose`;
+      let resolution: UndefinedStep["resolution"];
+      let suggestion: string;
+      if (r.state === "UNDEFINED") {
+        resolution = "define-journey";
+        suggestion = r.suggest;
+      } else if (r.state === "PARAPHRASE" && r.canonical) {
+        resolution = "alias";
+        suggestion = stub(r.canonical);
+      } else if (r.state === "NEEDS-DEV-GLUE" && r.canonical) {
+        resolution = "map";
+        suggestion = `likely maps to "${r.canonical}" — ${stub(r.canonical)}`;
+      } else {
+        resolution = "review"; // NEEDS-CONTRACT / AMBIGUOUS: no automatic match
+        suggestion = `no automatic match — map it to a step from the phrasebook (renderPhrasebook), or escalate to a developer only if no operation provides this capability`;
+      }
+      out.push({ scenario: sc.scenario, text: prose, line, resolution, suggestion });
+    }
+  }
+  return out;
+}
+
+/** Render the scaffolder worklist: what a non-technical author wrote that is not yet runnable, and how to resolve it. */
+export function renderScaffold(undefinedSteps: UndefinedStep[]): string {
+  if (!undefinedSteps.length) return "All authored steps are runnable — nothing to define. ✓";
+  const suggested = undefinedSteps.filter((u) => u.resolution !== "review");
+  const review = undefinedSteps.filter((u) => u.resolution === "review");
+  const out: string[] = ["# Undefined steps — make the stories run (the scaffolder maps prose → bound steps; no code)", ""];
+  if (suggested.length) {
+    out.push("## Suggested mappings (a likely target was found — no developer):");
+    for (const u of suggested) out.push(`  • [${u.resolution}] "${u.text}"  (${u.scenario}:${u.line})\n      ${u.suggestion}`);
+    out.push("");
+  }
+  if (review.length) {
+    out.push("## Needs your decision (no automatic match — map from the phrasebook, or escalate to a developer if nothing backs it):");
+    for (const u of review) out.push(`  • "${u.text}"  (${u.scenario}:${u.line})\n      ${u.suggestion}`);
+  }
+  return out.join("\n");
+}
+
 /** Render the gap report as readable text (for a CLI / a download endpoint). */
 export function renderGapReport(report: GapReport): string {
-  const TAG: Record<BindState, string> = { BOUND: "✓ BOUND", PARAPHRASE: "≈ PARAPHRASE", "NEEDS-DEV-GLUE": "⚙ NEEDS-DEV-GLUE", "NEEDS-CONTRACT": "✗ NEEDS-CONTRACT", AMBIGUOUS: "⚠ AMBIGUOUS" };
+  const TAG: Record<BindState, string> = { BOUND: "✓ BOUND", PARAPHRASE: "≈ PARAPHRASE", "NEEDS-DEV-GLUE": "⚙ NEEDS-DEV-GLUE", "NEEDS-CONTRACT": "✗ NEEDS-CONTRACT", AMBIGUOUS: "⚠ AMBIGUOUS", UNDEFINED: "? UNDEFINED" };
   const out: string[] = [];
   for (const sc of report.scenarios) {
     out.push(`\n  Scenario: ${sc.scenario}${sc.rule ? `   (Rule: ${sc.rule})` : ""}`);
     for (const r of sc.results) {
-      out.push(`    ${r.step.kind.toUpperCase().padEnd(5)} ${r.step.text}`);
+      const from = r.expandedFrom ? `  «${r.expandedFrom.text}»` : "";
+      out.push(`    ${r.step.kind.toUpperCase().padEnd(5)} ${r.step.text}${from}`);
       out.push(`          → ${TAG[r.state]}${r.handle ? `  [${r.handle}]` : ""}`);
       if (r.suggest) out.push(`            ↳ ${r.suggest}`);
     }

package/src/emit.ts

@@ -58,20 +58,28 @@ export function emitRunnableSuite(doc: OpenAPIv4Document, vocab: Vocabulary, fea
 
   const body: string[] = [];
   for (const sc of report.scenarios) {
-    if (!sc.subject) continue; // only emit scenarios whose When-action bound to an operation
-    const op = opByHandle.get(sc.subject);
-    if (!op) {
-      body.push(`// skipped "${sc.scenario}" — ${sc.subject} is not an SDK-surfaced operation (e.g. a webhook); bind via raw HTTP.`, ``);
-      continue;
-    }
-    const acc = clientAccessor(op); // e.g. "billing.checkout", "credits.get"
-    const expectsSuccess = sc.results.some((r) => r.state === "BOUND" && r.step.kind === "then" && /succeed/i.test(r.step.text));
+    // emit a call for EACH bound When (a composed / multi-step journey drives several actions in order).
+    const bound = sc.results.filter((r) => r.state === "BOUND" && r.step.kind === "when");
+    if (!bound.length) continue;
     body.push(`test(${JSON.stringify(sc.scenario)}, async () => {`);
-    body.push(`  // ${op.method.toUpperCase()} ${op.uri}${op.requires !== "anyone" ? `  (requires ${op.requires}: set ${tokenEnv})` : ""}`);
-    body.push(`  const result = await client.${acc}(/* provide input */);`);
-    if (expectsSuccess) body.push(`  expect(result).toBeDefined();`);
-    // C037 store assertions: a mutation should refresh the stores it invalidates.
-    for (const key of op.store?.invalidates ?? []) body.push(`  // store: expect $${key} to have refreshed after this mutation`);
+    let n = 0;
+    let current: OpInfo | undefined;
+    for (const r of sc.results) {
+      if (r.state !== "BOUND") continue;
+      if (r.step.kind === "when") {
+        current = opByHandle.get(r.handle);
+        if (!current) {
+          body.push(`  // skipped ${r.handle} — not an SDK-surfaced operation (e.g. a webhook); bind via raw HTTP.`);
+          continue;
+        }
+        const acc = clientAccessor(current); // e.g. "billing.checkout", "credits.get"
+        body.push(`  // ${current.method.toUpperCase()} ${current.uri}${current.requires !== "anyone" ? `  (requires ${current.requires}: set ${tokenEnv})` : ""}`);
+        body.push(`  const result${++n} = await client.${acc}(/* provide input */);`);
+      } else if (r.step.kind === "then" && current) {
+        if (/succeed/i.test(r.step.text) && n) body.push(`  expect(result${n}).toBeDefined();`);
+        if (/refresh/i.test(r.step.text)) for (const key of current.store?.invalidates ?? []) body.push(`  // store: expect $${key} to have refreshed after this mutation`);
+      }
+    }
     body.push(`});`, ``);
   }
 

package/src/hatch/auth.ts

@@ -0,0 +1,81 @@
+/**
+ * The AUTH HATCH (C039) — "be a signed-in user" WITHOUT the OAuth dance, for auth that cannot be scripted as a user
+ * (toolfactory is Google-OAuth-only). Works identically on a local or a real-deployment backend.
+ *
+ * Two safety properties make it fail-LOUD rather than manufacture a false green:
+ *  1. It NEVER hand-forges a session row. The consumer supplies `mintSession` — Better Auth's OWN server-side session
+ *     create (token hashing/signing, expiry, the OAuth account-link) — because only the app knows its session shape.
+ *  2. It SELF-VERIFIES: after minting, it round-trips the cookie against ONE real authenticated endpoint and THROWS if
+ *     the app does not accept it. A forged-but-invalid session fails the test loudly; it can never make a green.
+ *
+ * It writes only through a TEST-USER-SCOPED write hatch, so the seeded user + session belong to the test user alone —
+ * safe even against the production database (the BDD-as-living-documentation model: the seeded entity IS a test user).
+ */
+import type { StateHatchWrite, TestUser } from "./types";
+
+/** The tables/columns the teardown deletes the test user's rows from (app-specific; defaults to Better Auth's shape). */
+export interface CleanupTarget {
+  table: string;
+  column: string;
+}
+
+export interface SignInAsOptions {
+  /** a WRITE state hatch whose scope is THIS test user (provides the user row + scoped teardown). */
+  state: StateHatchWrite;
+  /** the test user to be signed in as. */
+  user: TestUser;
+  /**
+   * INSERT-OR-GET the Better Auth `user` (and any required `account` link) row, returning the user id. The consumer
+   * provides this because the exact Better Auth table/column shape is theirs (use state.d1.seed with the scope).
+   */
+  ensureUser: (state: StateHatchWrite, user: TestUser) => Promise<string>;
+  /**
+   * Mint a session via Better Auth's OWN API (e.g. `betterAuth({ database: drizzleAdapter(<D1>) })` + its session
+   * create) and return the session cookie. NEVER hand-build the token. Required.
+   */
+  mintSession: (userId: string, user: TestUser) => Promise<{ cookie: string }>;
+  /**
+   * Probe ONE x-suluk-access:authenticated endpoint WITH the cookie through the real API and resolve true iff the app
+   * ACCEPTS it (e.g. getSession returns a user / a 200, not 401). The hatch throws if false — fail-closed.
+   */
+  verify: (cookie: string) => Promise<boolean>;
+  /** scoped teardown targets (default: Better Auth's `session.userId` + `user.id`). */
+  cleanupTargets?: CleanupTarget[];
+}
+
+export interface SignedInSession {
+  /** the session cookie to hand the @suluk/sdk client (the `token`/cookie seam in the generated runnable suite). */
+  cookie: string;
+  userId: string;
+  /** delete the seeded session/user rows for THIS test user (scoped). Best-effort; pair with an external reaper. */
+  teardown: () => Promise<void>;
+}
+
+/**
+ * Sign in as a test user via the auth hatch, verifying the minted session against the live API before returning.
+ * Throws (never returns a trusted-but-unverified credential) if the app rejects the minted session.
+ */
+export async function signInAs(opts: SignInAsOptions): Promise<SignedInSession> {
+  const userId = await opts.ensureUser(opts.state, opts.user);
+  const { cookie } = await opts.mintSession(userId, opts.user);
+
+  const accepted = await opts.verify(cookie);
+  if (!accepted) {
+    throw new Error(
+      "@suluk/journeys/hatch: the minted session was REJECTED by the live API (the auth hatch fails closed rather than manufacture a false green). Check the Better Auth session shape (cookie name/__Secure- prefix, token hashing, expiry, account-link).",
+    );
+  }
+
+  const targets = opts.cleanupTargets ?? [{ table: "session", column: "userId" }, { table: "user", column: "id" }];
+  return {
+    cookie,
+    userId,
+    async teardown() {
+      try {
+        await opts.state.d1.cleanupScope(targets);
+      } catch {
+        /* best-effort; the external reaper sweep is the backstop */
+      }
+    },
+  };
+}

package/src/hatch/backends.ts

@@ -0,0 +1,56 @@
+/**
+ * The two D1 BACKENDS (C039) — no separate test infrastructure is ever provisioned.
+ *
+ *  - LOCAL  : bun:sqlite directly over the miniflare local D1 file (the `wrangler dev` state). Completely local,
+ *             zero-cost, zero prod risk, param-bound, full capability (a throwaway sqlite file).
+ *  - REMOTE : the REAL deployment over @suluk/cloudflare's CF REST `queryD1`. Highest fidelity; the seeded entities
+ *             ARE test users (BDD-as-living-documentation). The write surface is SCOPED (see state.ts) so it cannot
+ *             touch real users; reaching it requires an explicit `acknowledgeRealDeployment` — a conscious choice, not
+ *             an accident.
+ */
+import { queryD1, d1Rows, type CloudflareClient } from "@suluk/cloudflare";
+import type { D1Exec } from "./types";
+
+/** A D1 backend over the miniflare LOCAL sqlite file (bun:sqlite). Pass ":memory:" for tests, or the `.wrangler` path. */
+export async function localD1(d1Path: string): Promise<D1Exec> {
+  const { Database } = await import("bun:sqlite"); // lazy: only loaded when running locally
+  const db = new Database(d1Path);
+  return {
+    kind: "local",
+    async run(sql, params) {
+      return db.query(sql).all(...((params ?? []) as never[])) as Record<string, unknown>[];
+    },
+    close() {
+      db.close();
+    },
+  };
+}
+
+/** A D1 backend over the REAL deployment's database via the CF REST /query endpoint (params bound). */
+export function remoteD1(cf: CloudflareClient, databaseId: string): D1Exec {
+  return {
+    kind: "remote",
+    async run(sql, params) {
+      return d1Rows(await queryD1(cf, databaseId, sql, params));
+    },
+  };
+}
+
+export type BackendSpec =
+  | { mode: "local"; d1Path: string }
+  | { mode: "remote"; cf: CloudflareClient; d1DatabaseId: string; acknowledgeRealDeployment: true };
+
+/**
+ * Resolve a D1 backend. `local` needs nothing remote. `remote` runs against the REAL deployment and therefore requires
+ * an explicit `acknowledgeRealDeployment: true` — the operator consciously accepting that seeded rows are test users on
+ * the live database (the write surface is still test-user-scoped; see stateHatch). Fail-closed without it.
+ */
+export async function resolveBackend(spec: BackendSpec): Promise<D1Exec> {
+  if (spec.mode === "local") return localD1(spec.d1Path);
+  if (!spec.acknowledgeRealDeployment) {
+    throw new Error(
+      "@suluk/journeys/hatch: a remote hatch runs against the REAL deployment — pass acknowledgeRealDeployment:true to confirm the seeded rows are test users on live data. (Prefer mode:'local' for CI; the remote write surface is test-user-scoped regardless.)",
+    );
+  }
+  return remoteD1(spec.cf, spec.d1DatabaseId);
+}

package/src/hatch/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @suluk/journeys/hatch — the ESCAPE HATCHES (C039), a deliberately-secondary subpath. Importing it is the explicit,
+ * visible act of stepping OUT of the user-path; a scenario that composes BDD as a real user imports NONE of this.
+ *
+ * No separate test infrastructure is provisioned. A hatch runs against one of two backends:
+ *  - resolveBackend({ mode: "local", d1Path })            — bun:sqlite over the miniflare local D1 (completely local).
+ *  - resolveBackend({ mode: "remote", cf, d1DatabaseId,   — the REAL deployment; seeded rows are TEST USERS, and the
+ *                     acknowledgeRealDeployment: true })     write surface is test-user-scoped so it can't touch real ones.
+ *
+ *  - stateHatch  — typed D1 read (default) + scoped write (seed/cleanupScope; raw exec local-only).
+ *  - signInAs    — the auth/OAuth hatch: mint via the app's OWN Better Auth, verified against the live API (fails
+ *                  closed, never a false green).
+ *
+ * Runtime IO only — provably outside the deterministic core (bind.ts / vocabulary.ts), enforced by hatch-wall.test.ts.
+ */
+export { resolveBackend, localD1, remoteD1, type BackendSpec } from "./backends";
+export { stateHatch, type StateHatchOptions } from "./state";
+export { signInAs, type SignInAsOptions, type SignedInSession, type CleanupTarget } from "./auth";
+export type { HatchBackendKind, TestUserScope, HatchUse, TestUser, D1Exec, D1Read, D1Write, StateHatchRead, StateHatchWrite } from "./types";

package/src/hatch/state.ts

@@ -0,0 +1,80 @@
+/**
+ * The STATE HATCH (C039) over a D1 backend (local bun:sqlite OR the real deployment's CF REST). Capability-by-type:
+ * the read hatch is the default; WRITE methods exist on the returned object ONLY when `{ write: true }` is requested.
+ *
+ * TEST-USER SCOPING is the write-safety guarantee (works identically on local and prod):
+ *  - `seed(table, ownerColumn, rows)` FORCES `row[ownerColumn] = scope.value` — you cannot seed a row owned by anyone
+ *    but the test user.
+ *  - `cleanupScope(targets)` deletes ONLY rows whose owner column equals the test user id.
+ *  - `exec(rawSql)` (full, unscoped capability) is available ONLY on the LOCAL backend (a throwaway sqlite file); on
+ *    the real deployment it THROWS — unscoped writes to live data are exactly the wipe-real-users risk.
+ * All values are bound params; table/column identifiers are validated.
+ */
+import type { D1Exec, D1Read, HatchUse, StateHatchRead, StateHatchWrite, TestUserScope } from "./types";
+
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ident = (name: string, kind: string): string => {
+  if (!IDENT.test(name)) throw new Error(`@suluk/journeys/hatch: unsafe ${kind} identifier ${JSON.stringify(name)} — only [A-Za-z0-9_] allowed (values go through bound params, identifiers cannot).`);
+  return name;
+};
+
+function d1Read(d1: D1Exec): D1Read {
+  return {
+    select: (sql, params) => d1.run(sql, params),
+    async get(sql, params) {
+      return (await d1.run(sql, params))[0] ?? null;
+    },
+  };
+}
+
+export interface StateHatchOptions {
+  /** grant write capability (seed/cleanup, + raw exec on local). Default: read-only. */
+  write?: boolean;
+  /** the test-user scope — REQUIRED for seed/cleanup. The auth hatch supplies it. */
+  scope?: TestUserScope;
+}
+
+export function stateHatch(d1: D1Exec): StateHatchRead;
+export function stateHatch(d1: D1Exec, opts: StateHatchOptions & { write: true }): StateHatchWrite;
+export function stateHatch(d1: D1Exec, opts?: StateHatchOptions): StateHatchRead | StateHatchWrite {
+  const read: StateHatchRead = { kind: d1.kind, d1: d1Read(d1) };
+  if (!opts?.write) return read;
+
+  const scope = opts.scope;
+  const needScope = (): TestUserScope => {
+    if (!scope) throw new Error("@suluk/journeys/hatch: a scoped write (seed/cleanupScope) requires a test-user scope (the seeded test user id) — so it can only ever touch that user's rows.");
+    return scope;
+  };
+
+  return {
+    kind: d1.kind,
+    scope,
+    d1: {
+      ...read.d1,
+      async seed(table, ownerColumn, rows, why: HatchUse) {
+        if (!why?.because) throw new Error("@suluk/journeys/hatch: seed requires a `because` (why no user-path can do this) — recorded for the audit trail.");
+        const s = needScope();
+        const t = ident(table, "table");
+        const oc = ident(ownerColumn, "owner column");
+        for (const row of rows) {
+          const stamped = { ...row, [oc]: s.value }; // FORCE ownership to the test user — cannot seed another user's row
+          const cols = Object.keys(stamped).map((c) => ident(c, "column"));
+          const ph = cols.map(() => "?").join(", ");
+          await d1.run(`INSERT INTO ${t} (${cols.join(", ")}) VALUES (${ph})`, cols.map((c) => stamped[c]));
+        }
+      },
+      async cleanupScope(targets) {
+        const s = needScope();
+        for (const { table, column } of targets) {
+          await d1.run(`DELETE FROM ${ident(table, "table")} WHERE ${ident(column, "column")} = ?`, [s.value]);
+        }
+      },
+      async exec(sql, params) {
+        if (d1.kind === "remote") {
+          throw new Error("@suluk/journeys/hatch: raw exec is refused on the REAL deployment (an unscoped write to live data) — use seed/cleanupScope (test-user-scoped), or run mode:'local'.");
+        }
+        await d1.run(sql, params);
+      },
+    },
+  };
+}

package/src/hatch/types.ts

@@ -0,0 +1,87 @@
+/**
+ * @suluk/journeys/hatch — types for the ESCAPE HATCHES (C039).
+ *
+ * Composing BDD AS A REAL USER (through @suluk/sdk) is the default. A hatch is the deliberately-secondary, clearly-
+ * marked escape for the cases a user-path cannot reach: AUTH bootstrap (OAuth — mint a session), an irreducible
+ * precondition with no API, internal-state inspection a Then can't observe, and teardown.
+ *
+ * NO separate test infrastructure is provisioned. A hatch runs against one of two backends:
+ *  - `local`  — bun:sqlite over the miniflare LOCAL D1 file (`wrangler dev` state): completely local, zero-cost,
+ *               zero prod risk, full capability (it is a throwaway file).
+ *  - `remote` — the REAL deployment over the CF REST API: highest fidelity, "use prod, the seeded entities ARE test
+ *               users" (BDD-as-living-documentation). The write surface is SCOPED to a test user so it cannot touch
+ *               real users — raw unscoped exec/delete is refused on remote.
+ *
+ * These types live OUTSIDE the deterministic core (bind.ts / vocabulary.ts): a hatch is runtime IO over live state,
+ * never an input to the contract or the request→operation matcher (the C038 wall; enforced by hatch-wall.test.ts).
+ */
+
+/** The two backends a hatch can run against. */
+export type HatchBackendKind = "local" | "remote";
+
+/**
+ * A TEST-USER SCOPE — the structural write-safety guarantee, just the seeded test user's id. Every scoped write FORCES
+ * the row's owner column to this value (you cannot seed another user's row); every scoped delete is bounded to it. So a
+ * hatch can never touch a real user's data — even on the production database. The auth hatch sets this.
+ */
+export interface TestUserScope {
+  /** the seeded test user's id — the ONLY owner value any scoped write/delete may touch. */
+  value: string;
+}
+
+/** A typed marker that a scenario stepped OUT of the user-path — surfaced in the gap report so hatch use is visible. */
+export interface HatchUse {
+  kind: "auth" | "state";
+  /** the author's justification (why a user-path can't do this) — recorded; an empty `because` is a lint smell. */
+  because: string;
+  /** did the author confirm no user-path exists? false → the linter ▲-nudges back to the front door. */
+  userPathChecked: boolean;
+}
+
+/** A seeded test user for the auth hatch. */
+export interface TestUser {
+  email: string;
+  name?: string;
+  /** provider id link for the OAuth account row (defaults to a synthetic test id). */
+  providerAccountId?: string;
+}
+
+/** The low-level D1 access a backend provides (params ALWAYS bound — never string-interpolated). */
+export interface D1Exec {
+  readonly kind: HatchBackendKind;
+  run(sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
+  close?(): void;
+}
+
+// ---- capability-by-type: read methods always present; WRITE methods exist only on a write-granted hatch ----
+
+export interface D1Read {
+  /** SELECT — values bound via params. Returns the rows of the last statement. */
+  select(sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
+  /** the first row, or null. */
+  get(sql: string, params?: unknown[]): Promise<Record<string, unknown> | null>;
+}
+export interface D1Write extends D1Read {
+  /**
+   * Seed rows the user-path genuinely cannot create. Each row's `ownerColumn` is FORCED to the test-user scope value,
+   * so a seeded row can only ever belong to the test user. `why` is recorded (anti-rot audit trail).
+   */
+  seed(table: string, ownerColumn: string, rows: Record<string, unknown>[], why: HatchUse): Promise<void>;
+  /** delete the test user's rows across the given `{ table, column }` targets (the scoped teardown). Requires a scope. */
+  cleanupScope(targets: { table: string; column: string }[]): Promise<void>;
+  /**
+   * Raw SQL (full capability) — available ONLY on the LOCAL backend (a throwaway sqlite file). On the remote/real
+   * deployment this THROWS: unscoped writes against live data are the wipe-real-users risk; use `seed`/`cleanupScope`.
+   */
+  exec(sql: string, params?: unknown[]): Promise<void>;
+}
+
+export interface StateHatchRead {
+  kind: HatchBackendKind;
+  d1: D1Read;
+}
+export interface StateHatchWrite {
+  kind: HatchBackendKind;
+  scope?: TestUserScope;
+  d1: D1Write;
+}

package/src/index.ts

@@ -24,13 +24,17 @@ export { parseFeature, type Feature, type Scenario, type FeatureStep } from "./g
 
 export {
   bindFeatures,
+  detectUndefined,
   renderGapReport,
+  renderScaffold,
   type GapReport,
   type ScenarioResult,
   type StepResult,
   type BindState,
   type BindOptions,
   type CoverageHole,
+  type Definitions,
+  type UndefinedStep,
 } from "./bind";
 
 export { emitRunnableSuite, type EmitOptions } from "./emit";

package/test/hatch-wall.test.ts

@@ -0,0 +1,38 @@
+import { test, expect, describe } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * THE CONTRACT WALL (C039) — the security council's strongest, verified property: the deterministic core of
+ * @suluk/journeys (the vocabulary projection + the binder) must NEVER transitively reach the escape hatches, the CF
+ * write-client, raw fetch, or env. A hatch is runtime IO over live state; it is invisible to the contract and the
+ * request→operation matcher. Subpath naming alone is not compiler-enforced, so this asserts it over the source.
+ */
+const src = (rel: string) => readFileSync(join(import.meta.dir, "..", "src", rel), "utf8");
+
+// The deterministic projector/binder core: produces the contract-derived artifacts and the bind decision. It must do
+// NO runtime IO and reach NOTHING in the hatch/CF/env/fetch world — not even reference it.
+const PROJECTOR_CORE = ["vocabulary.ts", "bind.ts", "gherkin.ts", "normalize.ts"];
+const NO_IO = [/from\s+["']\.{1,2}\/hatch/, /@suluk\/cloudflare/, /@suluk\/env/, /\bprocess\.env\b/, /\bfetch\s*\(/];
+
+// The emitter + the package barrel: the emitter is the user-path bridge (it may import @suluk/sdk and EMIT a
+// `process.env.SULUK_BASE_URL` string into the generated suite), but neither may import the hatch or the CF write-client.
+const BRIDGE = ["emit.ts", "index.ts"];
+const NO_HATCH = [/from\s+["']\.{1,2}\/hatch/, /@suluk\/cloudflare/];
+
+describe("C039 contract wall — the deterministic core never reaches the hatch / CF write-client / fetch / env", () => {
+  for (const file of PROJECTOR_CORE) {
+    test(`src/${file}: no hatch, no @suluk/cloudflare, no env, no fetch (pure projection)`, () => {
+      for (const pattern of NO_IO) expect(pattern.test(src(file))).toBe(false);
+    });
+  }
+  for (const file of BRIDGE) {
+    test(`src/${file}: imports neither the hatch nor the CF write-client`, () => {
+      for (const pattern of NO_HATCH) expect(pattern.test(src(file))).toBe(false);
+    });
+  }
+  test("the hatch DOES live in its own subtree (the CF client is imported only under hatch/, never in the core)", () => {
+    expect(/@suluk\/cloudflare/.test(src("hatch/backends.ts"))).toBe(true);
+    expect(/@suluk\/cloudflare/.test(src("index.ts"))).toBe(false);
+  });
+});

package/test/hatch.test.ts

@@ -0,0 +1,93 @@
+import { test, expect, describe, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { localD1, remoteD1, resolveBackend } from "../src/hatch/backends";
+import { stateHatch } from "../src/hatch/state";
+import { CloudflareClient } from "@suluk/cloudflare";
+import type { D1Exec, HatchUse } from "../src/hatch/types";
+
+const WHY: HatchUse = { kind: "state", because: "OAuth-only signup; no API seeds a verified user", userPathChecked: true };
+
+/** A CloudflareClient whose injected fetch records D1 /query bodies and returns canned envelopes (no network). */
+function mockRemote() {
+  const bodies: { sql: string; params?: unknown[] }[] = [];
+  const fetchImpl = (async (_url: unknown, init: { body?: string }) => {
+    if (init.body) bodies.push(JSON.parse(init.body));
+    return { ok: true, status: 200, statusText: "OK", text: async () => JSON.stringify({ success: true, result: [{ results: [], success: true }] }) } as unknown as Response;
+  }) as unknown as typeof fetch;
+  const cf = new CloudflareClient({ apiToken: "t", accountId: "acct", fetch: fetchImpl });
+  return { d1: remoteD1(cf, "db"), bodies };
+}
+
+describe("backends — local (bun:sqlite) is completely local; remote needs an explicit acknowledgement", () => {
+  test("resolveBackend(local) opens the sqlite file; no remote needed", async () => {
+    const b = await resolveBackend({ mode: "local", d1Path: ":memory:" });
+    expect(b.kind).toBe("local");
+    b.close?.();
+  });
+
+  test("resolveBackend(remote) THROWS without acknowledgeRealDeployment (it is the real deployment)", async () => {
+    await expect(resolveBackend({ mode: "remote", cf: {} as never, d1DatabaseId: "db" } as never)).rejects.toThrow(/acknowledgeRealDeployment/);
+  });
+});
+
+describe("stateHatch over LOCAL (the completely-local path, fully exercised)", () => {
+  let d1: D1Exec;
+  beforeEach(async () => {
+    d1 = await localD1(":memory:");
+    await d1.run("CREATE TABLE credits (id TEXT, userId TEXT, balance INTEGER)");
+  });
+
+  test("read-only by default — write methods are absent", () => {
+    const h = stateHatch(d1);
+    expect(typeof h.d1.select).toBe("function");
+    expect((h.d1 as unknown as Record<string, unknown>).seed).toBeUndefined();
+    expect((h.d1 as unknown as Record<string, unknown>).exec).toBeUndefined();
+  });
+
+  test("seed FORCES the owner column to the test-user id, then select reads it back (real round-trip)", async () => {
+    const h = stateHatch(d1, { write: true, scope: { value: "testuser_1" } });
+    // even if the caller passes a different userId, seed overwrites it to the scope value:
+    await h.d1.seed("credits", "userId", [{ id: "c1", userId: "SOMEONE_ELSE", balance: 5 }], WHY);
+    const rows = await h.d1.select("SELECT id, userId, balance FROM credits");
+    expect(rows).toEqual([{ id: "c1", userId: "testuser_1", balance: 5 }]);
+  });
+
+  test("cleanupScope deletes ONLY the test user's rows", async () => {
+    const h = stateHatch(d1, { write: true, scope: { value: "testuser_1" } });
+    await h.d1.seed("credits", "userId", [{ id: "c1", balance: 5 }], WHY);
+    await d1.run("INSERT INTO credits (id, userId, balance) VALUES (?,?,?)", ["c2", "REAL_USER", 99]); // a 'real' row
+    await h.d1.cleanupScope([{ table: "credits", column: "userId" }]);
+    const left = await h.d1.select("SELECT userId FROM credits");
+    expect(left).toEqual([{ userId: "REAL_USER" }]); // the real user's row is untouched
+  });
+
+  test("raw exec IS available on local (throwaway sqlite, full capability)", async () => {
+    const h = stateHatch(d1, { write: true, scope: { value: "t" } });
+    await h.d1.exec("DELETE FROM credits"); // allowed locally
+    expect(await h.d1.select("SELECT * FROM credits")).toEqual([]);
+  });
+
+  test("seed requires a `because`, validates identifiers, and a scoped write needs a scope", async () => {
+    const h = stateHatch(d1, { write: true, scope: { value: "t" } });
+    await expect(h.d1.seed("credits", "userId", [{ id: "x" }], { kind: "state", because: "", userPathChecked: true })).rejects.toThrow(/because/);
+    await expect(h.d1.seed("credits; DROP TABLE credits", "userId", [{ id: "x" }], WHY)).rejects.toThrow(/identifier/);
+    const noScope = stateHatch(d1, { write: true });
+    await expect(noScope.d1.cleanupScope([{ table: "credits", column: "userId" }])).rejects.toThrow(/scope/);
+  });
+});
+
+describe("stateHatch over REMOTE (the real deployment) — writes are bound to params and refuse unscoped exec", () => {
+  test("seed sends a parameterized INSERT with the owner forced to the test user", async () => {
+    const { d1, bodies } = mockRemote();
+    const h = stateHatch(d1, { write: true, scope: { value: "testuser_1" } });
+    await h.d1.seed("user", "id", [{ id: "ignored", email: "bdd@example.test" }], WHY);
+    expect(bodies[0].sql).toContain("INSERT INTO user");
+    expect(bodies[0].params).toEqual(["testuser_1", "bdd@example.test"]); // id forced to the scope value; values bound
+  });
+
+  test("raw exec is REFUSED on the real deployment (unscoped write to live data)", async () => {
+    const { d1 } = mockRemote();
+    const h = stateHatch(d1, { write: true, scope: { value: "t" } });
+    await expect(h.d1.exec("DELETE FROM user")).rejects.toThrow(/refused on the REAL deployment/);
+  });
+});

package/test/journeys.test.ts

@@ -2,7 +2,7 @@ import { test, expect, describe } from "bun:test";
 import type { OpenAPIv4Document } from "@suluk/core";
 import { generateVocabulary, vocabularyHash, opHandle } from "../src/vocabulary";
 import { parseFeature } from "../src/gherkin";
-import { bindFeatures } from "../src/bind";
+import { bindFeatures, detectUndefined, renderScaffold } from "../src/bind";
 import { emitRunnableSuite } from "../src/emit";
 
 /** A minimal v4 fixture echoing real toolfactory shapes (incl. the shared `api/billing/subscription` path). */
@@ -170,3 +170,112 @@ Feature: f
     expect(suite).toContain("requires authenticated");
   });
 });
+
+describe("most-recent-When subject — multi-step journeys bind each outcome to its own action", () => {
+  const vocab = generateVocabulary(DOC);
+  test("a second When re-targets the following Then (not the first action)", () => {
+    const feature = parseFeature(`
+Feature: f
+  Scenario: top up then check balance
+    Given I am a signed-in user
+    When I checkout
+    Then it succeeds
+    When I view credits
+    Then I see my credits
+`);
+    const r = bindFeatures(vocab, [feature]).scenarios[0].results;
+    expect(r[1].handle).toBe(opHandle("checkout", "api/billing/checkout")); // When I checkout
+    expect(r[2].handle).toBe(opHandle("checkout", "api/billing/checkout")); // Then it succeeds → checkout
+    expect(r[3].handle).toBe(opHandle("getCredits", "api/credits")); // When I view credits (subject moves)
+    expect(r[4].state).toBe("BOUND"); // Then I see my credits → getCredits, NOT checkout
+    expect(r[4].handle).toBe(opHandle("getCredits", "api/credits"));
+  });
+});
+
+describe("composition — compose a story out of a named journey (no developer)", () => {
+  const vocab = generateVocabulary(DOC);
+  const definitions = { journeys: { "top up": ["Given I am a signed-in user", "When I checkout", "Then it succeeds"] } };
+
+  test("a journey reference expands into its (already-bound) steps", () => {
+    const feature = parseFeature(`
+Feature: f
+  Scenario: onboarding
+    When I complete the "top up" journey
+    When I view credits
+    Then I see my credits
+`);
+    const r = bindFeatures(vocab, [feature], { definitions }).scenarios[0].results;
+    // the journey ref expanded to 3 steps, all bound, each tagged with the original prose
+    expect(r.length).toBe(5);
+    expect(r.slice(0, 3).every((x) => x.state === "BOUND")).toBe(true);
+    expect(r[0].expandedFrom?.text).toContain('complete the "top up" journey');
+    expect(r[1].handle).toBe(opHandle("checkout", "api/billing/checkout"));
+    expect(r[4].handle).toBe(opHandle("getCredits", "api/credits"));
+  });
+
+  test("a reference to an UNDEFINED journey is flagged UNDEFINED (scaffolder defines it, no dev)", () => {
+    const feature = parseFeature(`
+Feature: f
+  Scenario: missing
+    When I complete the "checkout flow" journey
+`);
+    const r = bindFeatures(vocab, [feature]).scenarios[0].results;
+    expect(r[0].state).toBe("UNDEFINED");
+    expect(r[0].suggest).toContain("checkout flow");
+  });
+});
+
+describe("two-role authoring — free prose, a scaffolder maps it, undefined is detected", () => {
+  const vocab = generateVocabulary(DOC);
+
+  test("a free-prose decomposition makes a non-technical author's step run (no dev)", () => {
+    const feature = parseFeature(`
+Feature: f
+  Scenario: combined
+    When I sign up and buy credits
+`);
+    const definitions = { steps: { "when i sign up and buy credits": ["Given I am a signed-in user", "When I checkout", "Then it succeeds"] } };
+    const r = bindFeatures(vocab, [feature], { definitions }).scenarios[0].results;
+    expect(r.length).toBe(3);
+    expect(r.every((x) => x.state === "BOUND")).toBe(true);
+    expect(r[1].expandedFrom?.text).toBe("I sign up and buy credits");
+  });
+
+  test("detectUndefined splits 'scaffolder can define' (alias) from 'escalate to a developer'", () => {
+    const feature = parseFeature(`
+Feature: f
+  Scenario: free prose
+    Given I am a signed-in user
+    When I cancel my subscription
+    Then I get a refund to my card
+`);
+    const undefinedSteps = detectUndefined(vocab, [feature]);
+    const cancel = undefinedSteps.find((u) => /cancel my subscription/i.test(u.text))!;
+    expect(cancel.resolution).toBe("alias");
+    expect(cancel.suggestion).toContain("When I cancel subscription"); // the canonical step to map to
+    const refund = undefinedSteps.find((u) => /refund/i.test(u.text))!;
+    expect(refund.resolution).toBe("review"); // no lexical match — the scaffolder decides (NOT falsely 'needs a dev')
+
+    const scaffold = renderScaffold(undefinedSteps);
+    expect(scaffold).toContain("Suggested mappings");
+    expect(scaffold).toContain("Needs your decision");
+  });
+});
+
+describe("emit — a composed/multi-step journey lowers to a sequence of SDK calls", () => {
+  const vocab = generateVocabulary(DOC);
+  test("two bound Whens emit two client calls in order", () => {
+    const feature = parseFeature(`
+Feature: f
+  Scenario: top up then check
+    Given I am a signed-in user
+    When I checkout
+    Then it succeeds
+    When I view credits
+    Then I see my credits
+`);
+    const suite = emitRunnableSuite(DOC, vocab, [feature]);
+    expect(suite).toContain("const result1 = await client.billing.checkout(");
+    expect(suite).toContain("const result2 = await client.credits.get(");
+  });
+});