@suluk/journeys 0.1.0

package/README.md

@@ -0,0 +1,80 @@
+# @suluk/journeys
+
+**Intuitive, runnable BDD over a v4 "Suluk" contract** — a non-technical author (PM / BA / QA) writes Gherkin
+user-stories and journeys against a step vocabulary *generated from the contract*, and a bidirectional gap report
+tells everyone exactly what the contract can and cannot yet back.
+
+> **CANDIDATE tooling — not official OpenAPI.** Suluk is a single-contributor candidate for OpenAPI v4.0 ("Moonwalk"),
+> unaffiliated with the OpenAPI Initiative. See [ADR C038](../../../../doc/architecture/decisions/C038-suluk-journeys-bdd.md).
+
+## The loop
+
+```
+contract ──generateVocabulary──▶ step palette ──▶ humans author .feature stories
+   ▲                                                        │
+   └── dev fills the gap ◀── bidirectional gap report ◀── bindFeatures
+```
+
+1. **`generateVocabulary(doc)`** projects the contract into a deterministic Gherkin step palette:
+   - **Given** ← `x-suluk-access` (`authenticated` → *"Given I am a signed-in user"*)
+   - **When** ← each operation (`checkout` → *"When I checkout"*, `getCredits` → *"When I view credits"*)
+   - **Then** ← declared statuses (*"Then it succeeds"*), `x-suluk-store` (*"Then my credits refreshes"*), per-unit
+     `x-suluk-cost` (*"Then I am charged credits"*)
+2. A non-technical author writes plain `.feature` files against that palette (the prose lives in a **sidecar**, never
+   in the contract — the [D1 wall](../../../../doc/architecture/decisions/C038-suluk-journeys-bdd.md)).
+3. **`bindFeatures(vocab, features)`** binds each step **exact-or-UNBOUND**, with outcome (`Then`) steps resolved
+   relative to the scenario's `When`-subject, and reports the gaps **both ways**.
+
+## What a "gap" is — bidirectional, tri-state
+
+- **authored → contract.** An unbound step is classified deterministically:
+  - **PARAPHRASE** — you wrote it differently; an author-owned alias resolves it, *no developer needed*.
+  - **NEEDS-DEV-GLUE** — the operation exists, but no step wires it; a developer adds one.
+  - **NEEDS-CONTRACT** — nothing backs the intent; a developer extends the contract.
+- **contract → authored.** A pure set-difference over the stable handle space surfaces every operation/store with **no
+  covering scenario** — the *"complete"* guarantee — and emits a drop-in stub for each.
+
+Binding never uses scoring, lemmatization, or embeddings — those would make the decision non-deterministic. String
+similarity appears only in the *presentational* "did you mean?" suggestion on an already-unbound step.
+
+## Runnable — and it partly tests your frontend
+
+`emitRunnableSuite(vocab, features)` lowers bound scenarios to a self-contained `bun:test` suite driven through
+**`@suluk/sdk`'s generated client** — the same client your frontend ships on. A green scenario exercises the real
+frontend **data-path**: typed dispatch, input validation, the auth interceptor, response decode, and the C037 store
+invalidation/refetch. **Honest boundary:** it tests client + contract + wire + the store data layer — **not** rendered
+UI, layout, or visual behavior (there is no DOM in a `bun:test`). That last mile is `@suluk/visual` + a browser.
+
+## Usage
+
+```ts
+import { generateVocabulary, parseFeature, bindFeatures, renderGapReport, renderPhrasebook } from "@suluk/journeys";
+import { apiDocument } from "./contract"; // your v4 contract
+
+const vocab = generateVocabulary(apiDocument());
+console.log(renderPhrasebook(vocab)); // the palette an author picks from
+
+const feature = parseFeature(await Bun.file("./billing.feature").text());
+const report = bindFeatures(vocab, [feature], {
+  aliases: { "given i am a logged in user": "given i am a signed-in user" }, // author-owned, no dev
+});
+console.log(renderGapReport(report));
+```
+
+## Stable identity
+
+Step identity is `op.name@path-uri` (the by-name handle), **not** the `@suluk/sdk` client accessor — `resolveOps`
+mutates the accessor in place during collision resolution, so accessor-keyed identity would churn when a sibling
+operation is added. (Witnessed on toolfactory's `api/billing/subscription`, which holds both `getSubscription` and
+`cancelSubscription`.)
+
+## Discovery (designed, gated)
+
+A semantic *reuse* search — "find an existing flow to reuse / modify / rebuild" — is designed (a deterministic
+faceted handle-index inside this package; the reuse verdict is set algebra over contract-handle overlap; an embedding
+overlay is a walled-off, gated sibling). It is **deferred until a real corpus exists**. See ADR C038.
+
+## Status
+
+`0.1.0`, ceiling **0.45** — originated, projection-model-native, spike-witnessed on the real toolfactory contract; the
+open question is whether the constrained-vocabulary-plus-alias UX feels intuitive to a real non-technical author.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@suluk/journeys",
+  "version": "0.1.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"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MahmoodKhalil57/suluk.git",
+    "directory": "tooling/ts/packages/journeys"
+  },
+  "homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
+  "bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@suluk/core": "^0.1.13",
+    "@suluk/sdk": "^0.2.2"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit -p ."
+  }
+}

package/src/bind.ts

@@ -0,0 +1,189 @@
+/**
+ * The BINDER (C038): authored .feature steps → contract handles, plus the bidirectional, tri-state GAP report.
+ *
+ * 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).
+ *
+ * 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 { JourneyStep, Vocabulary } from "./vocabulary";
+
+export type BindState = "BOUND" | "PARAPHRASE" | "NEEDS-DEV-GLUE" | "NEEDS-CONTRACT" | "AMBIGUOUS";
+
+export interface StepResult {
+  step: FeatureStep;
+  state: BindState;
+  /** the bound (or suggested) handle, when there is one. */
+  handle: string;
+  /** provenance of a BOUND step. */
+  via: string;
+  /** a human next-action for a non-BOUND step. */
+  suggest: string;
+}
+
+export interface ScenarioResult {
+  scenario: string;
+  rule?: string;
+  /** the resolved subject operation handle (the scenario's When-op), if any. */
+  subject: string;
+  results: StepResult[];
+}
+
+export interface CoverageHole {
+  handle: string;
+  name: string;
+  /** a one-line drop-in stub scenario to cover this operation. */
+  stub: string;
+}
+
+export interface GapReport {
+  scenarios: ScenarioResult[];
+  counts: Record<BindState, number>;
+  coverage: {
+    total: number;
+    covered: number;
+    holes: CoverageHole[];
+  };
+}
+
+export interface BindOptions {
+  /** an author-owned synonym map: normalized authored skeleton → a canonical generated skeleton. Resolves PARAPHRASE without a dev. */
+  aliases?: Record<string, string>;
+  /** how many coverage-hole stubs to emit (default: all). */
+  maxHoles?: number;
+}
+
+interface Indexes {
+  whenBySkeleton: Map<string, JourneyStep[]>;
+  thenByHandle: Map<string, Set<string>>;
+  givenSkeletons: Set<string>;
+  whenSteps: JourneyStep[];
+}
+
+function buildIndexes(vocab: Vocabulary): Indexes {
+  const whenBySkeleton = new Map<string, JourneyStep[]>();
+  const thenByHandle = new Map<string, Set<string>>();
+  const givenSkeletons = new Set<string>();
+  const whenSteps: 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);
+    } else {
+      (thenByHandle.get(s.handle) ?? thenByHandle.set(s.handle, new Set()).get(s.handle)!).add(s.skeleton);
+    }
+  }
+  return { whenBySkeleton, thenByHandle, givenSkeletons, whenSteps };
+}
+
+const res = (step: FeatureStep, state: BindState, handle = "", via = "", suggest = ""): StepResult => ({ step, state, handle, via, suggest });
+
+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;
+  for (const op of vocab.operations) {
+    const score = jaccard(st, tok(camel(op.name)));
+    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");
+}
+
+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);
+  }
+  if (step.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);
+  }
+  // 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);
+}
+
+/** Bind a parsed feature set against the vocabulary and produce the bidirectional gap report. */
+export function bindFeatures(vocab: Vocabulary, features: Feature[], opts: BindOptions = {}): GapReport {
+  const idx = buildIndexes(vocab);
+  const aliases = opts.aliases ?? {};
+  const scenarios: ScenarioResult[] = [];
+  const counts: Record<BindState, number> = { BOUND: 0, PARAPHRASE: 0, "NEEDS-DEV-GLUE": 0, "NEEDS-CONTRACT": 0, AMBIGUOUS: 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);
+        counts[r.state]++;
+        if (r.state === "BOUND" && step.kind === "when") coveredWhen.add(r.handle);
+        return r;
+      });
+      scenarios.push({ scenario: sc.name, rule: sc.rule, subject, 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 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` };
+  });
+
+  return { scenarios, counts, coverage: { total: vocab.operations.length, covered: vocab.operations.length - holesAll.length, holes } };
+}
+
+/** 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 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}`);
+      out.push(`          → ${TAG[r.state]}${r.handle ? `  [${r.handle}]` : ""}`);
+      if (r.suggest) out.push(`            ↳ ${r.suggest}`);
+    }
+  }
+  out.push(`\n  GAP SUMMARY  ${Object.entries(report.counts).filter(([, v]) => v).map(([k, v]) => `${k}: ${v}`).join("   ")}`);
+  out.push(`  COVERAGE  ${report.coverage.covered}/${report.coverage.total} operations covered; ${report.coverage.holes.length} stub(s) below.`);
+  for (const h of report.coverage.holes) out.push(h.stub);
+  return out.join("\n");
+}

package/src/emit.ts

@@ -0,0 +1,80 @@
+/**
+ * The RUNNABLE emitter (C038): a bound feature set → a self-contained `bun:test` suite that drives each scenario
+ * through the consumer's GENERATED @suluk/sdk client (+ its reactive stores), against a LIVE deployment.
+ *
+ * Why the SDK client and not raw HTTP (the distinction from @suluk/testgen, which calls a raw `fetch(BASE+path)`
+ * harness): the SDK client is the SAME one a Suluk frontend ships on, so a green scenario exercises the real frontend
+ * DATA-PATH — typed dispatch, input validation, the auth interceptor, response decode, and the C037 store
+ * invalidation/refetch. HONEST BOUNDARY (emitted as a literal header in the suite): it tests
+ * client + contract + wire + the store data layer, NOT rendered UI / layout / visual — there is no DOM in a bun:test.
+ *
+ * The call site is lowered with @suluk/sdk's OWN `resolveOps` + `clientAccessor` — the single source of accessor
+ * identity — so the emitted `client.<ns>.<member>(…)` can NEVER drift from the method `generateSdk` actually emits.
+ * Journeys keeps `op.name@path` as the stable handle for IDENTITY; the SDK accessor (which `resolveOps` mutates) is
+ * used ONLY here, at the late call-site lowering. Where an operation needs a request value the emitter writes a
+ * "provide input" placeholder (a real NEEDS-DEV-GLUE), never an invented value (the never-launder-thin discipline).
+ */
+import type { OpenAPIv4Document } from "@suluk/core";
+import { resolveOps, clientAccessor, type OpInfo } from "@suluk/sdk";
+import type { Feature } from "./gherkin";
+import type { Vocabulary } from "./vocabulary";
+import { bindFeatures, type BindOptions } from "./bind";
+
+export interface EmitOptions extends BindOptions {
+  /** import specifier for the consumer's generated SDK (default: the consumer's local "./sdk"). */
+  clientModule?: string;
+  /** named export that creates a client (default: "createClient"). */
+  clientFactory?: string;
+  /** env var holding the live base URL (default: "SULUK_BASE_URL"). */
+  baseUrlEnv?: string;
+  /** env var holding a bearer token for authenticated scenarios (default: "SULUK_USER_TOKEN"). */
+  tokenEnv?: string;
+}
+
+/** Emit a runnable bun:test suite (a string) from a parsed, bound feature set, lowered to the real SDK client. */
+export function emitRunnableSuite(doc: OpenAPIv4Document, vocab: Vocabulary, features: Feature[], opts: EmitOptions = {}): string {
+  const clientModule = opts.clientModule ?? "./sdk";
+  const clientFactory = opts.clientFactory ?? "createClient";
+  const baseUrlEnv = opts.baseUrlEnv ?? "SULUK_BASE_URL";
+  const tokenEnv = opts.tokenEnv ?? "SULUK_USER_TOKEN";
+
+  const report = bindFeatures(vocab, features, opts);
+  // accessor identity comes from @suluk/sdk itself, keyed by the STABLE handle (name@uri — neither is mutated by resolveOps).
+  const { ops } = resolveOps(doc);
+  const opByHandle = new Map<string, OpInfo>(ops.map((op) => [`${op.name}@${op.uri}`, op]));
+
+  const head = [
+    "// GENERATED by @suluk/journeys — do not edit by hand; regenerate from the contract + .feature sidecars.",
+    "// Coverage: this exercises the frontend DATA-PATH (client + contract + wire + store), NOT rendered UI / visual.",
+    `import { test, expect } from "bun:test";`,
+    `import { ${clientFactory} } from "${clientModule}";`,
+    ``,
+    `const client = ${clientFactory}({`,
+    `  baseURL: process.env.${baseUrlEnv},`,
+    `  token: () => process.env.${tokenEnv} ?? null, // bearer; cookie auth also works via credentials:"include"`,
+    `});`,
+    ``,
+  ];
+
+  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));
+    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`);
+    body.push(`});`, ``);
+  }
+
+  if (!body.length) body.push("// No scenario bound a When-operation yet — author steps from the generated phrasebook.");
+  return head.join("\n") + body.join("\n");
+}

package/src/gherkin.ts

@@ -0,0 +1,79 @@
+/**
+ * A minimal, dependency-free Gherkin parser (no cucumber dep; Bun-native like @suluk/sdk / @suluk/testgen).
+ *
+ * Supports Feature / Rule / Scenario / Given / When / Then / And / But and `#` comments. `And`/`But` inherit the
+ * previous step keyword (Given/When/Then) — the resolved keyword is what the binder matches on, never the raw `And`.
+ * This is an authoring surface, not a runtime; it parses the SIDECAR `.feature` text (free human prose) that the
+ * D1 wall keeps out of the contract.
+ */
+export type StepKind = "given" | "when" | "then";
+
+export interface FeatureStep {
+  /** the RESOLVED keyword (And/But fold into the preceding Given/When/Then). */
+  kind: StepKind;
+  /** the step text after the keyword. */
+  text: string;
+  /** the raw line as written (for reporting). */
+  raw: string;
+  /** 1-based source line number (for file:line hand-offs). */
+  line: number;
+}
+
+export interface Scenario {
+  name: string;
+  /** the `Rule:` this scenario sits under, if any. */
+  rule?: string;
+  steps: FeatureStep[];
+  line: number;
+}
+
+export interface Feature {
+  feature: string;
+  scenarios: Scenario[];
+}
+
+const KW = /^(Feature|Background|Rule|Scenario|Scenario Outline|Given|When|Then|And|But|Examples)\b:?\s*(.*)$/i;
+
+export function parseFeature(src: string): Feature {
+  let feature = "";
+  let rule: string | undefined;
+  let cur: Scenario | null = null;
+  let last: StepKind = "given";
+  const scenarios: Scenario[] = [];
+  const lines = src.split("\n");
+
+  lines.forEach((raw, i) => {
+    const t = raw.trim();
+    if (!t || t.startsWith("#")) return;
+    const m = KW.exec(t);
+    if (!m) return;
+    const kw = m[1].toLowerCase();
+    const rest = m[2];
+    switch (kw) {
+      case "feature":
+        feature = rest;
+        return;
+      case "rule":
+        rule = rest;
+        return;
+      case "background":
+      case "examples":
+        return;
+      case "scenario":
+      case "scenario outline":
+        cur = { name: rest, rule, steps: [], line: i + 1 };
+        scenarios.push(cur);
+        return;
+    }
+    // a step keyword
+    if (!cur) {
+      cur = { name: "(unnamed)", rule, steps: [], line: i + 1 };
+      scenarios.push(cur);
+    }
+    const k: StepKind = kw === "given" || kw === "when" || kw === "then" ? (kw as StepKind) : last;
+    last = k;
+    cur.steps.push({ kind: k, text: rest, raw: t, line: i + 1 });
+  });
+
+  return { feature, scenarios };
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+/**
+ * @suluk/journeys — intuitive, runnable BDD over a v4 "Suluk" contract.
+ *
+ * A non-technical author (PM / BA / QA) writes Gherkin user-stories/journeys against a step VOCABULARY projected
+ * deterministically from the contract; the BINDER resolves each step EXACT-or-UNBOUND (outcomes relative to the
+ * scenario's When-subject) and emits a bidirectional TRI-STATE gap report; the EMITTER lowers bound scenarios to a
+ * runnable bun:test suite driven through @suluk/sdk's generated client. A pure function of the document. CANDIDATE tooling.
+ *
+ * The vocabulary names only contract facts (operations, params, statuses, store keys, access roles) — never request
+ * VALUES — so it stays on the safe side of the D1 wall; the @suluk/core matcher never imports this package.
+ */
+export {
+  generateVocabulary,
+  renderPhrasebook,
+  vocabularyHash,
+  opHandle,
+  type Vocabulary,
+  type JourneyStep,
+  type VocabOperation,
+  type StepKind,
+} from "./vocabulary";
+
+export { parseFeature, type Feature, type Scenario, type FeatureStep } from "./gherkin";
+
+export {
+  bindFeatures,
+  renderGapReport,
+  type GapReport,
+  type ScenarioResult,
+  type StepResult,
+  type BindState,
+  type BindOptions,
+  type CoverageHole,
+} from "./bind";
+
+export { emitRunnableSuite, type EmitOptions } from "./emit";

package/src/normalize.ts

@@ -0,0 +1,47 @@
+/**
+ * Deterministic text normalization shared by the vocabulary projector and the binder.
+ *
+ * The wall (C038 / D1): `norm` produces the matching SKELETON used to decide a BIND — it strips slot VALUES
+ * (numbers, $amounts, quoted strings, `<placeholders>`) to a `*` token so a step's literal data never enters the
+ * decision. `tok`/`jaccard` are used ONLY in the presentational tri-state classifier ("did you mean?"), never to
+ * decide a bind. No lemmatization, stemming, or embedding anywhere — pure, local, statically decidable.
+ */
+
+/** camelCase / snake_case / kebab → lower-case space-separated words. `getAutoTopup` → "get auto topup". */
+export function camel(s: string): string {
+  return s
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[_-]+/g, " ")
+    .toLowerCase()
+    .trim();
+}
+
+/** The matching skeleton: lower-cased, punctuation-flattened, slot-VALUES collapsed to `*`, whitespace-collapsed. */
+export function norm(s: string): string {
+  return s
+    .toLowerCase()
+    .replace(/["'`.]/g, " ")
+    .replace(/<[^>]+>/g, " * ") // <slot>
+    .replace(/\$?\b\d[\d,.]*\b/g, " * ") // numbers / $amounts → slot
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+const STOP = new Set("i a an the my me of to is are for and it as on with you your".split(" "));
+
+/** Content tokens for the presentational similarity classifier (stopwords + slots removed). */
+export function tok(s: string): string[] {
+  return norm(s)
+    .split(" ")
+    .filter((w) => w && w !== "*" && !STOP.has(w));
+}
+
+/** Jaccard overlap of two token bags — presentational ranking only. */
+export function jaccard(a: string[], b: string[]): number {
+  const A = new Set(a);
+  const B = new Set(b);
+  if (!A.size || !B.size) return 0;
+  let inter = 0;
+  for (const x of A) if (B.has(x)) inter++;
+  return inter / (A.size + B.size - inter);
+}

package/src/vocabulary.ts

@@ -0,0 +1,136 @@
+/**
+ * The VOCABULARY projection (C038): a v4 document → a deterministic Gherkin step palette.
+ *
+ * Pure function of the document — same contract in, same vocabulary out, no network. Every step phrase is derived
+ * from a name the contract already holds, so the vocabulary carries ZERO information the contract lacks:
+ *   - GIVEN  ← `x-suluk-access.requires` (the WHO axis): authenticated → "Given I am a signed-in user".
+ *   - WHEN   ← the operation (method + name): "When I checkout", "When I view credits".
+ *   - THEN   ← declared statuses ("Then it succeeds"), `x-suluk-store` (query key → "Then I see my <key>";
+ *             mutation invalidates → "Then my <key> refreshes"), and per-unit `x-suluk-cost` ("Then I am charged credits").
+ *
+ * Step IDENTITY is `op.name @ path-uri` (the stable C009 by-name handle), NEVER the @suluk/sdk client accessor
+ * (which `resolveOps` mutates in place). GIVEN steps key on a synthetic `@access:<role>` handle.
+ */
+import type { OpenAPIv4Document, Request } from "@suluk/core";
+import { camel, norm } from "./normalize";
+
+export type StepKind = "given" | "when" | "then";
+
+export interface JourneyStep {
+  /** Given / When / Then. */
+  kind: StepKind;
+  /** the human-readable phrase an author writes, e.g. "When I checkout". */
+  phrase: string;
+  /** the normalized matching skeleton (slot values stripped). */
+  skeleton: string;
+  /** stable identity: `op.name@path-uri`, or `@access:<role>` for a Given. */
+  handle: string;
+  /** provenance of this phrase (which contract fact produced it). */
+  via: string;
+}
+
+export interface VocabOperation {
+  handle: string;
+  name: string;
+  path: string;
+  method: string;
+  access: string;
+}
+
+export interface Vocabulary {
+  /** every generated step, sorted deterministically. */
+  steps: JourneyStep[];
+  /** the operation table (for coverage + the phrasebook). */
+  operations: VocabOperation[];
+}
+
+/** Stable by-name handle. */
+export const opHandle = (name: string, path: string): string => `${name}@${path}`;
+
+interface AccessFacet {
+  requires?: string;
+}
+interface CostComponent {
+  basis?: string;
+}
+interface CostFacet {
+  components?: CostComponent[];
+  estimateMicroUsd?: number;
+}
+
+// x-suluk-access / x-suluk-cost are advisory vendor facets NOT modeled on the typed `Request` (a consumer stamps them,
+// e.g. toolfactory via Object.assign) — read them through an untyped view rather than the typed surface.
+const ext = (op: Request): Record<string, unknown> => op as unknown as Record<string, unknown>;
+const accessOf = (op: Request): string => {
+  const a = ext(op)["x-suluk-access"] as AccessFacet | undefined;
+  return typeof a?.requires === "string" ? a.requires : "anyone";
+};
+const isMetered = (op: Request): boolean => {
+  const c = ext(op)["x-suluk-cost"] as CostFacet | undefined;
+  return Array.isArray(c?.components) && c.components.some((x) => x?.basis === "per-unit");
+};
+const statusesOf = (op: Request): string[] =>
+  op.responses ? Object.keys(op.responses) : [];
+
+/** Derive the canonical WHEN phrase for an operation from its method + name. */
+function whenPhrase(name: string, method: string): string {
+  const words = camel(name).split(" ");
+  const verb = method === "get" && (words[0] === "get" || words[0] === "list") ? "view " + words.slice(1).join(" ") : words.join(" ");
+  return `When I ${verb}`.replace(/\s+/g, " ").trim();
+}
+
+/** Project a v4 document into the deterministic step vocabulary. */
+export function generateVocabulary(doc: OpenAPIv4Document): Vocabulary {
+  const steps: JourneyStep[] = [];
+  const operations: VocabOperation[] = [];
+  const push = (kind: StepKind, phrase: string, handle: string, via: string) => steps.push({ kind, phrase, skeleton: norm(phrase), handle, via });
+
+  for (const [path, item] of Object.entries(doc.paths)) {
+    for (const [name, op] of Object.entries(item.requests ?? {})) {
+      const handle = opHandle(name, path);
+      const access = accessOf(op);
+      operations.push({ handle, name, path, method: op.method, access });
+
+      if (access === "authenticated") push("given", "Given I am a signed-in user", "@access:authenticated", "x-suluk-access");
+      push("when", whenPhrase(name, op.method), handle, `op ${op.method.toUpperCase()} ${path}`);
+
+      const statuses = statusesOf(op);
+      if (statuses.includes("200")) push("then", "Then it succeeds", handle, "status 200");
+      const store = op["x-suluk-store"];
+      if (store?.key) push("then", `Then I see my ${camel(store.key)}`, handle, `x-suluk-store key:${store.key}`);
+      for (const inv of store?.invalidates ?? []) push("then", `Then my ${camel(inv)} refreshes`, handle, `x-suluk-store invalidates:${inv}`);
+      if (isMetered(op)) push("then", "Then I am charged credits", handle, "x-suluk-cost per-unit");
+    }
+  }
+
+  // deterministic order: kind, then phrase, then handle.
+  const ORDER: Record<StepKind, number> = { given: 0, when: 1, then: 2 };
+  steps.sort((a, b) => ORDER[a.kind] - ORDER[b.kind] || a.phrase.localeCompare(b.phrase) || a.handle.localeCompare(b.handle));
+  operations.sort((a, b) => a.handle.localeCompare(b.handle));
+  return { steps, operations };
+}
+
+/** A foldable, entity-grouped phrasebook (Markdown) — the human surface an author picks step phrases from. */
+export function renderPhrasebook(vocab: Vocabulary): string {
+  const byHandle = new Map<string, JourneyStep[]>();
+  for (const s of vocab.steps) {
+    if (s.handle.startsWith("@access:")) continue;
+    (byHandle.get(s.handle) ?? byHandle.set(s.handle, []).get(s.handle)!).push(s);
+  }
+  const lines: string[] = ["# Available steps (generated from the contract)\n", "_Given I am a signed-in user_ — available on every authenticated operation.\n"];
+  for (const op of vocab.operations) {
+    const steps = byHandle.get(op.handle);
+    if (!steps?.length) continue;
+    lines.push(`\n### ${op.name}  \`${op.method.toUpperCase()} ${op.path}\``);
+    for (const s of steps) lines.push(`- ${s.phrase}`);
+  }
+  return lines.join("\n");
+}
+
+/** A deterministic content hash of the vocabulary (djb2 hex) — for drift detection / the build artifact. */
+export function vocabularyHash(vocab: Vocabulary): string {
+  const payload = JSON.stringify(vocab.steps.map((s) => [s.kind, s.skeleton, s.handle]));
+  let h = 5381;
+  for (let i = 0; i < payload.length; i++) h = (((h << 5) + h) ^ payload.charCodeAt(i)) >>> 0;
+  return h.toString(16).padStart(8, "0");
+}

package/test/journeys.test.ts

@@ -0,0 +1,172 @@
+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 { emitRunnableSuite } from "../src/emit";
+
+/** A minimal v4 fixture echoing real toolfactory shapes (incl. the shared `api/billing/subscription` path). */
+const DOC: OpenAPIv4Document = {
+  openapi: "4.0.0-candidate",
+  info: { title: "fixture", version: "0.0.0" },
+  paths: {
+    "api/credits": {
+      requests: { getCredits: { method: "get", responses: { "200": { status: 200 } }, "x-suluk-access": { requires: "authenticated" }, "x-suluk-store": { key: "credits" } } },
+    },
+    "api/billing/checkout": {
+      requests: { checkout: { method: "post", responses: { "200": { status: 200 }, "400": { status: 400 } }, "x-suluk-access": { requires: "authenticated" } } },
+    },
+    "api/billing/subscription": {
+      requests: {
+        getSubscription: { method: "get", responses: { "200": { status: 200 } }, "x-suluk-access": { requires: "authenticated" }, "x-suluk-store": { key: "subscription" } },
+        cancelSubscription: { method: "post", responses: { "200": { status: 200 } }, "x-suluk-access": { requires: "authenticated" }, "x-suluk-store": { invalidates: ["subscription"] } },
+      },
+    },
+    "api/transcribe": {
+      requests: { transcribe: { method: "post", responses: { "200": { status: 200 } }, "x-suluk-access": { requires: "authenticated" }, "x-suluk-cost": { components: [{ basis: "per-unit" }] } } },
+    },
+  },
+} as unknown as OpenAPIv4Document;
+
+describe("generateVocabulary", () => {
+  const vocab = generateVocabulary(DOC);
+  const phrases = vocab.steps.map((s) => s.phrase);
+
+  test("projects When phrases from method + operation name", () => {
+    expect(phrases).toContain("When I checkout");
+    expect(phrases).toContain("When I view credits"); // get + 'get' prefix → 'view'
+    expect(phrases).toContain("When I transcribe");
+  });
+
+  test("projects a Given from x-suluk-access, a charge-Then from per-unit x-suluk-cost, and a store-Then", () => {
+    expect(phrases).toContain("Given I am a signed-in user");
+    expect(phrases).toContain("Then I am charged credits"); // transcribe is per-unit metered
+    expect(phrases).toContain("Then my subscription refreshes"); // cancelSubscription invalidates subscription
+    expect(phrases).toContain("Then I see my credits"); // getCredits query store
+  });
+
+  test("is deterministic — same doc → same hash", () => {
+    expect(vocabularyHash(generateVocabulary(DOC))).toBe(vocabularyHash(vocab));
+  });
+});
+
+describe("stable identity (name@path-uri)", () => {
+  test("two operations sharing a path stay DISTINCT by name+path", () => {
+    const vocab = generateVocabulary(DOC);
+    const handles = vocab.operations.map((o) => o.handle);
+    expect(handles).toContain(opHandle("getSubscription", "api/billing/subscription"));
+    expect(handles).toContain(opHandle("cancelSubscription", "api/billing/subscription"));
+    expect(new Set(handles).size).toBe(handles.length); // no collisions
+  });
+});
+
+describe("bindFeatures — exact-or-UNBOUND, subject-relative outcomes, tri-state", () => {
+  const vocab = generateVocabulary(DOC);
+
+  test("binds exact steps; the generic 'Then it succeeds' binds to the scenario's When-subject (not an arbitrary op)", () => {
+    const feature = parseFeature(`
+Feature: f
+  Scenario: top up
+    Given I am a signed-in user
+    When I checkout
+    Then it succeeds
+`);
+    const report = bindFeatures(vocab, [feature]);
+    const r = report.scenarios[0].results;
+    expect(r[0].state).toBe("BOUND"); // Given
+    expect(r[1].state).toBe("BOUND"); // When → checkout
+    expect(r[1].handle).toBe(opHandle("checkout", "api/billing/checkout"));
+    expect(r[2].state).toBe("BOUND"); // Then it succeeds → SUBJECT (checkout), the regression guard
+    expect(r[2].handle).toBe(opHandle("checkout", "api/billing/checkout"));
+  });
+
+  test("an 'And' outcome inherits Then and binds to a mutation's invalidated store", () => {
+    const feature = parseFeature(`
+Feature: f
+  Scenario: cancel
+    Given I am a signed-in user
+    When I cancel subscription
+    Then my subscription refreshes
+`);
+    const r = bindFeatures(vocab, [feature]).scenarios[0].results;
+    expect(r[2].state).toBe("BOUND");
+    expect(r[2].handle).toBe(opHandle("cancelSubscription", "api/billing/subscription"));
+  });
+
+  test("an unbacked intent is NEEDS-CONTRACT; a paraphrase resolves via the alias map", () => {
+    const feature = parseFeature(`
+Feature: f
+  Scenario: word doc
+    Given I am a logged in user
+    When I transcribe
+    Then I download it as a Word document
+`);
+    const report = bindFeatures(vocab, [feature], { aliases: { "given i am a logged in user": "given i am a signed-in user" } });
+    const r = report.scenarios[0].results;
+    expect(r[0].state).toBe("BOUND"); // alias resolved the paraphrase → no dev
+    expect(r[1].state).toBe("BOUND"); // transcribe
+    expect(r[2].state).toBe("NEEDS-CONTRACT"); // no operation backs a Word-doc download
+  });
+
+  test("a paraphrased When does NOT silently bind (exact-or-UNBOUND)", () => {
+    const feature = parseFeature(`
+Feature: f
+  Scenario: para
+    When I start a checkout
+`);
+    const r = bindFeatures(vocab, [feature]).scenarios[0].results;
+    expect(r[0].state).not.toBe("BOUND");
+    expect(["PARAPHRASE", "NEEDS-DEV-GLUE"]).toContain(r[0].state);
+  });
+
+  test("coverage (contract → authored): uncovered operations are surfaced with stubs", () => {
+    const feature = parseFeature(`
+Feature: f
+  Scenario: only checkout
+    When I checkout
+`);
+    const report = bindFeatures(vocab, [feature]);
+    expect(report.coverage.total).toBe(5);
+    expect(report.coverage.covered).toBe(1);
+    expect(report.coverage.holes.some((h) => h.name === "transcribe")).toBe(true);
+    expect(report.coverage.holes.find((h) => h.name === "getCredits")!.stub).toContain("When I view credits");
+  });
+});
+
+describe("emitRunnableSuite — lowers to the REAL @suluk/sdk entity-grouped accessor", () => {
+  const vocab = generateVocabulary(DOC);
+  const suite = emitRunnableSuite(
+    DOC,
+    vocab,
+    [
+      parseFeature(`
+Feature: f
+  Scenario: top up
+    Given I am a signed-in user
+    When I checkout
+    Then it succeeds
+  Scenario: balance
+    Given I am a signed-in user
+    When I view credits
+    Then I see my credits
+`),
+    ],
+  );
+
+  test("imports the consumer's createClient and wires baseURL + token from env", () => {
+    expect(suite).toContain('import { createClient } from "./sdk"');
+    expect(suite).toContain("process.env.SULUK_BASE_URL");
+    expect(suite).toContain("process.env.SULUK_USER_TOKEN");
+  });
+
+  test("calls the SDK's entity-grouped accessor (resolveOps/clientAccessor), NOT the flat op name", () => {
+    expect(suite).toContain("client.billing.checkout("); // checkout (custom op) → billing.checkout
+    expect(suite).toContain("client.credits.get("); // getCredits (CRUD) → credits.get
+    expect(suite).not.toContain("client.checkout("); // never the flat by-name accessor
+    expect(suite).not.toContain("client.getCredits(");
+  });
+
+  test("annotates the auth requirement for authenticated operations", () => {
+    expect(suite).toContain("requires authenticated");
+  });
+});

package/tsconfig.json

@@ -0,0 +1 @@
+{ "extends": "../../tsconfig.base.json", "compilerOptions": { "types": ["bun"] }, "include": ["src", "test"] }