@suluk/journeys 0.3.1 → 0.4.0

package/src/emit.ts

@@ -1,6 +1,6 @@
 /**
- * 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.
+ * The RUNNABLE emitter (C038 + C040-P1): 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
@@ -8,11 +8,16 @@
  * 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.
  *
+ * SCENARIO OUTLINES (C040-P1): a scenario with an `Examples:` table is unrolled to ONE test PER ROW; the bound When op's
+ * request body is built FROM THE ROW (an Examples column = a request field of that op, by name). An `input` cell is used
+ * as a literal (coerced to the field's type); a `sourced` cell `<op.select>` is RESOLVED from a prior step's captured
+ * response via the inlined `pick` (carried-data across a journey — `resolveSourced`'s shape). Each bound When's result
+ * is captured under its `op.name`, so a later sourced field chains from it. Where a value isn't supplied (no Examples
+ * table, or an op with path/query args not yet outline-wired) the emitter writes a "provide input" placeholder — a real
+ * gap, never an invented value (the never-launder-thin discipline).
+ *
  * 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).
+ * identity — so the emitted `client.<ns>.<member>(…)` can NEVER drift from the method `generateSdk` emits.
  */
 import type { OpenAPIv4Document } from "@suluk/core";
 import { resolveOps, clientAccessor, type OpInfo } from "@suluk/sdk";
@@ -31,6 +36,35 @@ export interface EmitOptions extends BindOptions {
   tokenEnv?: string;
 }
 
+const JS_ID = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const jsKey = (k: string) => (JS_ID.test(k) ? k : JSON.stringify(k));
+/** A `sourced` Examples cell: the wiring token `<op.select>` (e.g. `<createSubscription.id>`). */
+const SOURCED_CELL = /^<([A-Za-z_][\w]*)\.(.+)>$/;
+
+/** An Examples cell → a TS literal: a `<op.select>` token → `pick(captured,…)`; else coerced by the field's type. */
+function cellLiteral(cell: string, fieldSchema: unknown): string {
+  const m = SOURCED_CELL.exec(cell.trim());
+  if (m) return `pick(captured, ${JSON.stringify(m[1])}, ${JSON.stringify(m[2])})`;
+  const t = fieldSchema && typeof fieldSchema === "object" ? (fieldSchema as { type?: unknown }).type : undefined;
+  const type = Array.isArray(t) ? t[0] : t;
+  if ((type === "integer" || type === "number") && cell.trim() !== "" && Number.isFinite(Number(cell))) return String(Number(cell));
+  if (type === "boolean" && (cell === "true" || cell === "false")) return cell;
+  return JSON.stringify(cell);
+}
+
+/** The call args for an outline row, or null if the op needs path/query args (not yet outline-wired → placeholder). */
+function buildCallArgs(op: OpInfo, cells: Record<string, string>): string | null {
+  if (op.pathParams.length || op.queryRaw != null) return null;
+  if (op.bodyRaw == null) return "";
+  const props = (op.bodyRaw && typeof op.bodyRaw === "object" ? (op.bodyRaw as { properties?: Record<string, unknown> }).properties : undefined) ?? {};
+  const entries: string[] = [];
+  for (const [h, cell] of Object.entries(cells)) {
+    if (!(h in props)) continue; // a column belonging to ANOTHER When op in a multi-step journey
+    entries.push(`${jsKey(h)}: ${cellLiteral(cell, (props as Record<string, unknown>)[h])}`);
+  }
+  return `{ ${entries.join(", ")} }`;
+}
+
 /** 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";
@@ -39,6 +73,9 @@ export function emitRunnableSuite(doc: OpenAPIv4Document, vocab: Vocabulary, fea
   const tokenEnv = opts.tokenEnv ?? "SULUK_USER_TOKEN";
 
   const report = bindFeatures(vocab, features, opts);
+  // report.scenarios is pushed in feature→scenario order, so it aligns 1:1 with the flattened source scenarios; the
+  // source carries the Examples table the binder does not.
+  const sourceScenarios = features.flatMap((f) => f.scenarios);
   // 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]));
@@ -49,6 +86,9 @@ export function emitRunnableSuite(doc: OpenAPIv4Document, vocab: Vocabulary, fea
     `import { test, expect } from "bun:test";`,
     `import { ${clientFactory} } from "${clientModule}";`,
     ``,
+    `// resolve a \`sourced\` Examples cell <op.select> from a prior step's captured response (carried-data across a journey).`,
+    `const pick = (captured: Record<string, any>, op: string, sel: string) => sel.split(".").reduce((v: any, k) => (v == null ? undefined : v[k]), captured[op]);`,
+    ``,
     `const client = ${clientFactory}({`,
     `  baseURL: process.env.${baseUrlEnv},`,
     `  token: () => process.env.${tokenEnv} ?? null, // bearer; cookie auth also works via credentials:"include"`,
@@ -57,14 +97,13 @@ export function emitRunnableSuite(doc: OpenAPIv4Document, vocab: Vocabulary, fea
   ];
 
   const body: string[] = [];
-  for (const sc of report.scenarios) {
-    // 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 () => {`);
+
+  /** Emit the bound When calls (+ outcome assertions) for one scenario run. `cells` non-null ⇒ an outline row (build
+   *  the body + capture for chaining); null ⇒ the plain path (a "provide input" placeholder). */
+  const emitCalls = (results: typeof report.scenarios[number]["results"], cells: Record<string, string> | null) => {
     let n = 0;
     let current: OpInfo | undefined;
-    for (const r of sc.results) {
+    for (const r of results) {
       if (r.state !== "BOUND") continue;
       if (r.step.kind === "when") {
         current = opByHandle.get(r.handle);
@@ -72,15 +111,44 @@ export function emitRunnableSuite(doc: OpenAPIv4Document, vocab: Vocabulary, fea
           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"
+        const acc = clientAccessor(current);
         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 */);`);
+        n++;
+        if (cells) {
+          const args = buildCallArgs(current, cells);
+          body.push(args === null
+            ? `  const result${n} = await client.${acc}(/* provide input — path/query args not yet outline-wired */);`
+            : `  const result${n} = await client.${acc}(${args});`);
+          body.push(`  captured[${JSON.stringify(current.name)}] = result${n};`);
+        } else {
+          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(`});`, ``);
+  };
+
+  for (let i = 0; i < report.scenarios.length; i++) {
+    const sc = report.scenarios[i];
+    if (!sc.results.some((r) => r.state === "BOUND" && r.step.kind === "when")) continue;
+    const ex = sourceScenarios[i]?.examples;
+
+    if (ex && ex.headers.length && ex.rows.length) {
+      // OUTLINE: one test per Examples row, body built from the row + sourced cells chained via `captured`.
+      ex.rows.forEach((row, ri) => {
+        const cells = Object.fromEntries(ex.headers.map((h, ci) => [h, row[ci] ?? ""]));
+        body.push(`test(${JSON.stringify(`${sc.scenario} — example ${ri + 1}`)}, async () => {`);
+        body.push(`  const captured: Record<string, any> = {};`);
+        emitCalls(sc.results, cells);
+        body.push(`});`, ``);
+      });
+    } else {
+      body.push(`test(${JSON.stringify(sc.scenario)}, async () => {`);
+      emitCalls(sc.results, null);
+      body.push(`});`, ``);
+    }
   }
 
   if (!body.length) body.push("// No scenario bound a When-operation yet — author steps from the generated phrasebook.");

package/src/examples.ts

@@ -0,0 +1,6 @@
+/**
+ * Example precedence + origin-aware synthesis. The implementation moved to the shared zero-dep leaf `@suluk/examples`
+ * (so `@suluk/sdk` can read it too — journeys depends on sdk, so the reader had to sit below both). journeys keeps this
+ * re-export so its public API and the projector-core wall (which forbids importing this VALUE layer) are unchanged.
+ */
+export * from "@suluk/examples";

package/src/gherkin.ts

@@ -25,6 +25,11 @@ export interface Scenario {
   rule?: string;
   steps: FeatureStep[];
   line: number;
+  /** tags on this scenario (the leading `@` stripped), e.g. ["public"]. */
+  tags?: string[];
+  /** the captured `Examples:` table of a Scenario Outline (C040-P1); absent for a plain Scenario. `tags` are from a
+   *  `@public`-style line directly above the `Examples:` keyword (C040-P4 promote selection). */
+  examples?: { headers: string[]; rows: string[][]; tags?: string[] };
 }
 
 export interface Feature {
@@ -32,19 +37,41 @@ export interface Feature {
   scenarios: Scenario[];
 }
 
-const KW = /^(Feature|Background|Rule|Scenario|Scenario Outline|Given|When|Then|And|But|Examples)\b:?\s*(.*)$/i;
+// NB: `Scenario Outline` MUST precede `Scenario` — alternation is ordered, else "Scenario Outline: x" matches the
+// shorter `Scenario` and mis-parses the name as "Outline: x".
+const KW = /^(Feature|Background|Rule|Scenario Outline|Scenario|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";
+  let collectingExamples = false;
+  let pendingTags: string[] = [];
   const scenarios: Scenario[] = [];
   const lines = src.split("\n");
 
   lines.forEach((raw, i) => {
     const t = raw.trim();
     if (!t || t.startsWith("#")) return;
+
+    // a tag line (`@public @smoke …`) — attaches to the NEXT Scenario or Examples block.
+    if (t.startsWith("@")) {
+      pendingTags.push(...t.split(/\s+/).filter((x) => x.startsWith("@")).map((x) => x.slice(1)));
+      return;
+    }
+
+    // a `|` table row — captured ONLY while inside an Examples block (a Scenario Outline's table); otherwise ignored.
+    if (t.startsWith("|")) {
+      const c = cur;
+      if (collectingExamples && c?.examples) {
+        const cells = t.split("|").slice(1, -1).map((s) => s.trim());
+        if (c.examples.headers.length === 0) c.examples.headers = cells;
+        else c.examples.rows.push(cells);
+      }
+      return;
+    }
+
     const m = KW.exec(t);
     if (!m) return;
     const kw = m[1].toLowerCase();
@@ -52,17 +79,31 @@ export function parseFeature(src: string): Feature {
     switch (kw) {
       case "feature":
         feature = rest;
+        collectingExamples = false;
+        pendingTags = [];
         return;
       case "rule":
         rule = rest;
+        collectingExamples = false;
+        pendingTags = [];
         return;
       case "background":
+        collectingExamples = false;
+        pendingTags = [];
+        return;
       case "examples":
+        if (cur) {
+          cur.examples = { headers: [], rows: [], ...(pendingTags.length ? { tags: pendingTags } : {}) };
+          collectingExamples = true;
+        }
+        pendingTags = [];
         return;
       case "scenario":
       case "scenario outline":
-        cur = { name: rest, rule, steps: [], line: i + 1 };
+        collectingExamples = false;
+        cur = { name: rest, rule, steps: [], line: i + 1, ...(pendingTags.length ? { tags: pendingTags } : {}) };
         scenarios.push(cur);
+        pendingTags = [];
         return;
     }
     // a step keyword

package/src/index.ts

@@ -22,6 +22,25 @@ export {
 
 export { parseFeature, type Feature, type Scenario, type FeatureStep } from "./gherkin";
 
+export {
+  buildScenarioOutlines,
+  renderScenarioOutlines,
+  type ScenarioOutline,
+  type OutlineColumn,
+  type OutlineRenderOptions,
+} from "./outline";
+
+export {
+  extractPublicRows,
+  buildExampleObject,
+  promoteExampleIntoZod,
+  promoteFeatureExamples,
+  type PublicExampleRow,
+  type PromoteResult,
+  type PromoteTarget,
+  type PromoteFeatureResult,
+} from "./promote";
+
 export {
   bindFeatures,
   detectUndefined,
@@ -38,3 +57,55 @@ export {
 } from "./bind";
 
 export { emitRunnableSuite, type EmitOptions } from "./emit";
+
+export {
+  compileDemos,
+  renderPostman,
+  renderBruno,
+  type DemoScenario,
+  type DemoRequest,
+  type DemoValue,
+  type DemoCapture,
+  type CompileDemoOptions,
+  type RenderOptions,
+} from "./demos";
+
+export {
+  buildDemoFiles,
+  planPromotions,
+  parseTargetSpec,
+  miniDiff,
+  buildAudit,
+  type DemoFormat,
+  type BuildDemoFilesOptions,
+  type DemoFilesResult,
+  type PromoteTargetSpec,
+  type PromotionPlan,
+  type PromotionRow,
+  type PromotionFileResult,
+  type AuditResult,
+  type DimensionAudit,
+} from "./cli";
+
+export { coverageGrade, type CoverageGrade } from "./coverage";
+
+export {
+  resolveExample,
+  synthesize,
+  fieldOrigin,
+  describeInputs,
+  asSourceRef,
+  resolveSourced,
+  ORIGIN_KEYWORD,
+  FROM_KEYWORD,
+  type JsonSchema,
+  type ExampleTier,
+  type ExampleSources,
+  type ResolvedExample,
+  type FieldOrigin,
+  type SourceRef,
+  type FieldSource,
+  type FieldDescriptor,
+  type SynthDirection,
+  type SynthOptions,
+} from "./examples";

package/src/outline.ts

@@ -0,0 +1,102 @@
+/**
+ * Scenario Outline generator (C040, P1). Per operation, project a Gherkin `Scenario Outline:` whose `Examples:` columns
+ * are the request's CLIENT-FACING input fields (origin `input` or `sourced`; `computed`/server-set fields are dropped —
+ * a client never sends them), and whose first seed row comes from the C041-origin-aware resolver:
+ *   • an `input` cell  → a deterministic synthesized value the tester edits;
+ *   • a `sourced` cell → the WIREABLE TOKEN `<op.select>` (e.g. `<createSubscription.id>`), not a value — so the tester
+ *     sees it is wired from a prior step, and the runnable emitter resolves it via `resolveSourced` (the follow-on).
+ *
+ * The tester EXPANDS the table (adds rows / edits cells); the binder + emitter then run each row. This is an authoring
+ * surface, so it lives on the VALUE side (it imports the synth) — never read by the matcher.
+ */
+import type { OpenAPIv4Document } from "@suluk/core";
+import { describeInputs, resolveExample, type FieldOrigin, type JsonSchema } from "@suluk/examples";
+import { generateVocabulary, opHandle } from "./vocabulary";
+
+export interface OutlineColumn {
+  name: string;
+  origin: FieldOrigin;
+  /** the seed cell for the first Examples row: a synthesized value (`input`) or a `<op.select>` wiring token (`sourced`). */
+  seed: string;
+}
+
+export interface ScenarioOutline {
+  /** the operation's v4 by-name handle. */
+  op: string;
+  method: string;
+  uri: string;
+  /** the `When` step text (placeholders reference the Examples columns). */
+  whenPhrase: string;
+  /** client-facing input columns (computed fields dropped). Empty ⇒ a plain Scenario, no Examples table. */
+  columns: OutlineColumn[];
+}
+
+interface RawReq {
+  method: string;
+  contentSchema?: unknown;
+  parameterSchema?: { body?: unknown };
+}
+
+/** Escape a synthesized value for a Gherkin table cell. */
+function cell(v: unknown): string {
+  const s = typeof v === "string" ? v : typeof v === "number" || typeof v === "boolean" ? String(v) : JSON.stringify(v ?? null);
+  return s.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+
+/** Build the structured outlines for every operation that has a client-facing request body. */
+export function buildScenarioOutlines(doc: OpenAPIv4Document): ScenarioOutline[] {
+  // the When uses the contract's OWN generated phrase (so the outline BINDS); the Examples columns carry the request
+  // body — a Suluk convention: for a Scenario Outline, an Examples column = a request field of the bound When op.
+  const whenByHandle = new Map(generateVocabulary(doc).steps.filter((s) => s.kind === "when").map((s) => [s.handle, s.phrase.replace(/^When\s+/i, "")]));
+  const outlines: ScenarioOutline[] = [];
+  for (const [uri, piRaw] of Object.entries(doc.paths ?? {})) {
+    const pi = piRaw as { requests?: Record<string, RawReq> };
+    for (const [name, req] of Object.entries(pi.requests ?? {})) {
+      const body = (req.contentSchema ?? req.parameterSchema?.body) as JsonSchema | undefined;
+      const props = (body?.properties ?? {}) as Record<string, JsonSchema>;
+      const columns: OutlineColumn[] = [];
+      for (const d of describeInputs(body)) {
+        if (d.origin === "computed") continue; // a client never sends a server-computed field
+        const seed =
+          d.origin === "sourced"
+            ? `<${d.source ? `${d.source.op}.${d.source.select ?? "id"}` : d.name}>` // wired, not a value
+            : cell(resolveExample(props[d.name], {}, d.name, { direction: "request" }).value);
+        columns.push({ name: d.name, origin: d.origin, seed });
+      }
+      const whenPhrase = whenByHandle.get(opHandle(name, uri)) ?? `I ${name}`;
+      outlines.push({ op: name, method: req.method.toLowerCase(), uri, whenPhrase, columns });
+    }
+  }
+  return outlines;
+}
+
+/** Render a left-aligned, padded Gherkin table (6-space indent, matching the step indent + 2). */
+function renderTable(headers: string[], rows: string[][]): string {
+  const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)));
+  const line = (cells: string[]) => "      | " + cells.map((c, i) => (c ?? "").padEnd(widths[i])).join(" | ") + " |";
+  return [line(headers), ...rows.map(line)].join("\n");
+}
+
+export interface OutlineRenderOptions {
+  /** only render these operations (by name); default all. */
+  only?: string[];
+  feature?: string;
+}
+
+/**
+ * Render the generated outlines as a `.feature` SIDECAR a tester expands. A column-bearing op becomes a `Scenario
+ * Outline:` + a one-row `Examples:` table; a body-less op becomes a plain `Scenario:`.
+ */
+export function renderScenarioOutlines(doc: OpenAPIv4Document, opts: OutlineRenderOptions = {}): string {
+  const title = opts.feature ?? `${doc.info?.title ?? "API"} — generated scenario outlines (expand the Examples rows)`;
+  const want = opts.only ? new Set(opts.only) : null;
+  const blocks = buildScenarioOutlines(doc)
+    .filter((o) => !want || want.has(o.op))
+    .map((o) => {
+      const head = `  Scenario${o.columns.length ? " Outline" : ""}: ${o.op}\n    When ${o.whenPhrase}\n    Then it succeeds`;
+      if (!o.columns.length) return head;
+      const table = renderTable(o.columns.map((c) => c.name), [o.columns.map((c) => c.seed)]);
+      return `${head}\n\n    Examples:\n${table}`;
+    });
+  return `Feature: ${title}\n\n${blocks.join("\n\n")}\n`;
+}

package/src/promote.ts

@@ -0,0 +1,226 @@
+/**
+ * Promote-into-Zod (C040, P4). A tester marks an `Examples:` block `@public`; this lifts the block's first row into the
+ * matching Zod schema's source as `.meta({ examples: [ … ] })`, provenance-stamped — so Zod stays the LITERAL home for
+ * every example (the operator's fork), and the promoted value flows into the rendered docs as the request `.example`.
+ *
+ * SOURCE-WRITE SAFETY (this edits the maintainer's source file): the edit is MARKED (`@suluk-public`), IDEMPOTENT
+ * (re-promoting replaces the marked block, never double-appends), and NEVER CLOBBERS a hand-authored example (if the
+ * schema already carries an unmarked top-level `.meta({ examples })`, it REFUSES and asks the maintainer to resolve).
+ * The functions here are PURE (string in → string out); the consumer's bin runs `mizan_check_action_safety` before
+ * writing and the maintainer reviews the git diff. Reuses @suluk/examples' coercion shape; never invents a value.
+ */
+import type { Feature } from "./gherkin";
+import type { JsonSchema } from "@suluk/examples";
+
+const PUBLIC_MARK = "@suluk-public";
+
+export interface PublicExampleRow {
+  scenario: string;
+  headers: string[];
+  /** the FIRST row of the `@public`-tagged Examples block — the canonical public example. */
+  row: string[];
+}
+
+/** Every `@public`-tagged Examples block's first row (the tester's curated public example). Pure. */
+export function extractPublicRows(features: Feature[]): PublicExampleRow[] {
+  const out: PublicExampleRow[] = [];
+  for (const f of features) {
+    for (const sc of f.scenarios) {
+      const ex = sc.examples;
+      const isPublic = !!ex && (ex.tags?.includes("public") || sc.tags?.includes("public"));
+      if (ex && isPublic && ex.headers.length && ex.rows.length) {
+        out.push({ scenario: sc.name, headers: ex.headers, row: ex.rows[0] });
+      }
+    }
+  }
+  return out;
+}
+
+/** Coerce a table cell to a concrete value by the field's declared type; with no schema, infer from the cell content. */
+function coerce(cell: string, fieldSchema?: JsonSchema): unknown {
+  const t = fieldSchema && typeof fieldSchema === "object" ? fieldSchema.type : undefined;
+  const type = Array.isArray(t) ? t[0] : t;
+  if ((type === "integer" || type === "number") && cell.trim() !== "" && Number.isFinite(Number(cell))) return Number(cell);
+  if (type === "boolean" && (cell === "true" || cell === "false")) return cell === "true";
+  if (type) return cell; // a declared string/other type stays a string verbatim
+  // no schema: infer a number/boolean from the content, else keep the string.
+  if (/^-?\d+(\.\d+)?$/.test(cell.trim())) return Number(cell);
+  if (cell === "true" || cell === "false") return cell === "true";
+  return cell;
+}
+
+/**
+ * Build a concrete public example object from a row, coercing by the body schema's field types. A WIRING TOKEN cell
+ * (`<op.select>`) is skipped — a public docs example holds concrete values, not a chaining instruction.
+ */
+export function buildExampleObject(headers: string[], row: string[], bodySchema?: JsonSchema): Record<string, unknown> {
+  const props = (bodySchema?.properties ?? {}) as Record<string, JsonSchema>;
+  const out: Record<string, unknown> = {};
+  headers.forEach((h, i) => {
+    const cell = (row[i] ?? "").trim();
+    if (/^<[^>]+>$/.test(cell)) return; // a sourced wiring token is not a concrete public value
+    out[h] = coerce(cell, props[h]);
+  });
+  return out;
+}
+
+// ---- the source-editing core (string-aware paren/bracket scanning; never regex-balances JSON) ----
+
+const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** From `(` at `open`, the index of the matching `)`, skipping string literals. -1 if unbalanced. */
+function matchParen(text: string, open: number): number {
+  let depth = 0;
+  let str: string | null = null;
+  for (let i = open; i < text.length; i++) {
+    const ch = text[i];
+    if (str) {
+      if (ch === "\\") i++;
+      else if (ch === str) str = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") str = ch;
+    else if (ch === "(") depth++;
+    else if (ch === ")" && --depth === 0) return i;
+  }
+  return -1;
+}
+
+/** The index of the top-level `;` ending the expression that starts at `from`, skipping strings + nested brackets. */
+function statementEnd(text: string, from: number): number {
+  let depth = 0;
+  let str: string | null = null;
+  for (let i = from; i < text.length; i++) {
+    const ch = text[i];
+    if (str) {
+      if (ch === "\\") i++;
+      else if (ch === str) str = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") str = ch;
+    else if (ch === "(" || ch === "{" || ch === "[") depth++;
+    else if (ch === ")" || ch === "}" || ch === "]") depth--;
+    else if (ch === ";" && depth === 0) return i;
+  }
+  return -1;
+}
+
+/** The LAST top-level `.meta(…)` call in `expr` (depth 0 — not a property's `.meta`), or null. */
+function topLevelMeta(expr: string): { start: number; end: number; marked: boolean; hasExamples: boolean } | null {
+  let depth = 0;
+  let str: string | null = null;
+  let last: { start: number; end: number; marked: boolean; hasExamples: boolean } | null = null;
+  for (let i = 0; i < expr.length; i++) {
+    const ch = expr[i];
+    if (str) {
+      if (ch === "\\") i++;
+      else if (ch === str) str = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      str = ch;
+      continue;
+    }
+    if (ch === "." && depth === 0 && expr.startsWith(".meta(", i)) {
+      const end = matchParen(expr, i + 5);
+      if (end > 0) {
+        const content = expr.slice(i, end + 1);
+        last = { start: i, end, marked: content.includes(PUBLIC_MARK), hasExamples: /\bexamples\b/.test(content) };
+        i = end;
+        continue;
+      }
+    }
+    if (ch === "(" || ch === "{" || ch === "[") depth++;
+    else if (ch === ")" || ch === "}" || ch === "]") depth--;
+  }
+  return last;
+}
+
+const renderMeta = (example: unknown, provenance: string) => `.meta(/* ${PUBLIC_MARK}: ${provenance} */ { examples: [${JSON.stringify(example)}] })`;
+
+export interface PromoteResult {
+  source: string;
+  changed: boolean;
+  reason: string;
+}
+
+/**
+ * Promote `example` into the source of the Zod schema bound to `const <schemaVar> = …`. Idempotent (re-promote replaces
+ * the marked block), marked, and refuses to clobber a hand-authored top-level `.meta({ examples })`.
+ */
+export function promoteExampleIntoZod(source: string, schemaVar: string, example: unknown, provenance: string): PromoteResult {
+  const decl = new RegExp(`(^|[\\n;{])\\s*(export\\s+)?const\\s+${escapeRe(schemaVar)}\\s*=`);
+  const m = decl.exec(source);
+  if (!m) return { source, changed: false, reason: `schema \`${schemaVar}\` not found` };
+  const eqIdx = m.index + m[0].length - 1; // the "="
+  const exprStart = eqIdx + 1;
+  const semi = statementEnd(source, exprStart);
+  if (semi < 0) return { source, changed: false, reason: `could not find the end of \`${schemaVar}\`'s declaration` };
+
+  const expr = source.slice(exprStart, semi);
+  const meta = renderMeta(example, provenance);
+  const top = topLevelMeta(expr);
+
+  let newExpr: string;
+  if (top?.marked) {
+    newExpr = expr.slice(0, top.start) + meta + expr.slice(top.end + 1); // idempotent replace of the promoted block
+  } else if (top?.hasExamples) {
+    return { source, changed: false, reason: `\`${schemaVar}\` already has a hand-authored .meta({ examples }) — not clobbering; merge the public example manually` };
+  } else if (top) {
+    newExpr = expr.slice(0, top.end + 1) + " " + meta + expr.slice(top.end + 1); // append after a non-example .meta (merges safely)
+  } else {
+    const trimmed = expr.replace(/\s+$/, "").length;
+    newExpr = expr.slice(0, trimmed) + meta + expr.slice(trimmed);
+  }
+
+  if (newExpr === expr) return { source, changed: false, reason: "no change" };
+  return {
+    source: source.slice(0, exprStart) + newExpr + source.slice(semi),
+    changed: true,
+    reason: top?.marked ? `updated the promoted example on \`${schemaVar}\`` : `promoted a public example into \`${schemaVar}\``,
+  };
+}
+
+export interface PromoteTarget {
+  /** the Zod `const` name to edit. */
+  schemaVar: string;
+  /** the op's request body schema (for typed cell coercion); optional. */
+  bodySchema?: JsonSchema;
+}
+
+export interface PromoteFeatureResult {
+  source: string;
+  applied: { scenario: string; schemaVar: string; reason: string }[];
+  skipped: { scenario: string; reason: string }[];
+}
+
+/**
+ * Orchestrate promotion for a whole feature set: for each `@public` Examples row, resolve its target (the consumer maps
+ * scenario → schemaVar + body schema — the app knows that wiring), build the example, and apply it. Adapter-seam shaped.
+ */
+export function promoteFeatureExamples(
+  source: string,
+  features: Feature[],
+  resolveTarget: (scenario: string) => PromoteTarget | null,
+  provenancePrefix = "promoted from",
+): PromoteFeatureResult {
+  let src = source;
+  const applied: PromoteFeatureResult["applied"] = [];
+  const skipped: PromoteFeatureResult["skipped"] = [];
+  for (const pub of extractPublicRows(features)) {
+    const target = resolveTarget(pub.scenario);
+    if (!target) {
+      skipped.push({ scenario: pub.scenario, reason: "no target schema resolved for this scenario" });
+      continue;
+    }
+    const example = buildExampleObject(pub.headers, pub.row, target.bodySchema);
+    const r = promoteExampleIntoZod(src, target.schemaVar, example, `${provenancePrefix} ${pub.scenario}`);
+    if (r.changed) {
+      src = r.source;
+      applied.push({ scenario: pub.scenario, schemaVar: target.schemaVar, reason: r.reason });
+    } else {
+      skipped.push({ scenario: pub.scenario, reason: r.reason });
+    }
+  }
+  return { source: src, applied, skipped };
+}