@ashlr/stack-core 0.3.1 → 0.3.6

package/src/ai/phantom-wire-errors.test.ts

@@ -0,0 +1,296 @@
+import { afterAll, afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { EventEmitter } from "node:events";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { StackError } from "../errors.ts";
+import { __resetPhantomCache, __setPhantomSpawn, exec, listSecrets } from "../phantom.ts";
+import { wirePhantomForRecipe } from "./phantom-wire.ts";
+import type { Recipe } from "./recipe.ts";
+
+// Stubbed `phantom` subprocess, like the sibling phantom-wire-*.test.ts files,
+// extended for the failure shapes a spawned child can report that a clean exit
+// cannot: a signal that killed it, a `close` with no exit code, and spawn
+// errors beyond ENOENT. `script` answers per argv, so `--version` can succeed
+// while the inventory read fails. `calls` records every argv: whatever the
+// failure, wiring may only ever probe (`--version`) or read (`list --json`) —
+// never a mutating verb.
+type ScriptResult = {
+  code?: number | null;
+  signal?: NodeJS.Signals | null;
+  stdout?: string;
+  stderr?: string;
+  error?: string;
+};
+let script: (args: string[]) => ScriptResult = () => ({ code: 0 });
+let calls: string[][] = [];
+
+function fakeSpawn(_bin: string, args: string[]) {
+  calls.push([...args]);
+  const child = new EventEmitter() as EventEmitter & Record<string, unknown>;
+  const out = new EventEmitter();
+  const err = new EventEmitter();
+  Object.assign(child, {
+    stdout: Object.assign(out, { destroy() {} }),
+    stderr: Object.assign(err, { destroy() {} }),
+    stdin: { on() {}, write() {}, end() {}, destroy() {} },
+    pid: undefined,
+    kill() {},
+    unref() {},
+  });
+  queueMicrotask(() => {
+    const r = script(args);
+    if (r.error) {
+      child.emit("error", Object.assign(new Error(`spawn phantom ${r.error}`), { code: r.error }));
+      return;
+    }
+    if (r.stdout) out.emit("data", Buffer.from(r.stdout));
+    if (r.stderr) err.emit("data", Buffer.from(r.stderr));
+    // An omitted code is a clean exit; explicit null is the shape Node reports
+    // for a child that never produced an exit status (signal or unknown end).
+    child.emit("close", r.code === undefined ? 0 : r.code, r.signal ?? null);
+  });
+  return child;
+}
+
+const INSTALLED: ScriptResult = { code: 0, stdout: "phantom 0.7.9\n" };
+
+// `--version` answers; the inventory read fails as each test scripted it.
+const failList = (result: ScriptResult) => (args: string[]) =>
+  args[0] === "list" ? result : INSTALLED;
+
+const RECIPE: Recipe = {
+  id: "wire-errors",
+  query: "payments",
+  createdAt: "2026-04-18T00:00:00.000Z",
+  providers: [{ name: "stripe" }, { name: "neon" }],
+};
+
+describe("ai/phantom-wire subprocess errors", () => {
+  const savedPath = process.env.PATH;
+  let binDir: string;
+  let projectDir: string;
+  let stubPath: string;
+
+  beforeEach(() => {
+    binDir = realpathSync(mkdtempSync(join(tmpdir(), "wire-errors-bin-")));
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), "wire-errors-")));
+    // The binary only needs to resolve on PATH; spawn is stubbed. The `.sh`
+    // target matches the sibling tests (macOS provenance policy).
+    writeFileSync(join(binDir, "phantom.sh"), "#!/bin/sh\n");
+    chmodSync(join(binDir, "phantom.sh"), 0o755);
+    symlinkSync(join(binDir, "phantom.sh"), join(binDir, "phantom"));
+    process.env.PATH = binDir;
+    stubPath = join(projectDir, ".stack/webhooks/stripe.ts");
+    script = () => ({ code: 0 });
+    calls = [];
+    __resetPhantomCache();
+    __setPhantomSpawn(fakeSpawn as never);
+  });
+
+  afterEach(() => {
+    process.env.PATH = savedPath;
+    rmSync(binDir, { recursive: true, force: true });
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  afterAll(() => {
+    __setPhantomSpawn();
+    __resetPhantomCache();
+  });
+
+  it("reaches the caller as a failed read, never as success, when `list` is killed mid-stream", async () => {
+    // SIGKILL lands after stdout already carried a valid-looking inventory. A
+    // killed child cannot attest a completed read, so those bytes must never
+    // legitimize the name they contain.
+    script = failList({
+      code: null,
+      signal: "SIGKILL",
+      stdout: '[{"name":"STRIPE_SECRET_KEY"}]',
+    });
+
+    // exec() reports the close fields faithfully: a non-zero code, the signal,
+    // and a "signal" completion — distinguishable from a clean exit on its own.
+    const execResult = await exec(["list", "--json"], {
+      cwd: projectDir,
+      allowFailure: true,
+    });
+    expect(execResult).toMatchObject({ code: 1, signal: "SIGKILL", completion: "signal" });
+    expect(execResult.code).not.toBe(0);
+
+    // listSecrets' caller gets the typed unavailable-inventory error, not the
+    // plausible name the dying child emitted.
+    await expect(listSecrets(projectDir)).rejects.toMatchObject({
+      code: "PHANTOM_METADATA_UNAVAILABLE",
+      message: "Phantom secret inventory is unavailable; stored names are unknown.",
+    });
+
+    // And the wire caller sees every provider skipped — never `present` or
+    // `missing`, which only a completed read can justify.
+    expect(await wirePhantomForRecipe(RECIPE, { cwd: projectDir })).toEqual({
+      present: [],
+      missing: [],
+      webhooks: [stubPath],
+      skipped: ["stripe", "neon"],
+    });
+    expect(existsSync(stubPath)).toBe(true);
+    expect(calls).toEqual([
+      ["list", "--json"],
+      ["--version"],
+      ["list", "--json"],
+      ["list", "--json"],
+    ]);
+  });
+
+  it("keeps a `close` with no exit code and no signal unknown, never a completed read", async () => {
+    script = failList({ code: null });
+
+    const execResult = await exec(["list", "--json"], {
+      cwd: projectDir,
+      allowFailure: true,
+    });
+    // No exit status and no signal: completion stays "unknown" and the code is
+    // non-zero — there is nothing a caller could mistake for success.
+    expect(execResult).toMatchObject({ code: 1, completion: "unknown" });
+    expect(execResult.signal).toBeUndefined();
+
+    await expect(listSecrets(projectDir)).rejects.toMatchObject({
+      code: "PHANTOM_METADATA_UNAVAILABLE",
+    });
+    expect(await wirePhantomForRecipe(RECIPE, { cwd: projectDir })).toEqual({
+      present: [],
+      missing: [],
+      webhooks: [stubPath],
+      skipped: ["stripe", "neon"],
+    });
+  });
+
+  it.each(["EACCES", "EMFILE"])(
+    "delivers a refused `list` spawn (%s) to its caller unwrapped, never as an empty vault",
+    async (errno) => {
+      // ENOENT has a typed mapping (Phantom missing); every other spawn error
+      // reaches the caller as itself — unwrapped, not downgraded to a fake
+      // inventory or a not-installed hint.
+      script = failList({ error: errno });
+
+      await expect(exec(["list", "--json"], { cwd: projectDir })).rejects.toMatchObject({
+        code: errno,
+      });
+      const err = await listSecrets(projectDir).catch((e: unknown) => e);
+      expect(err).toMatchObject({ code: errno });
+      expect(err).not.toBeInstanceOf(StackError);
+
+      // The wire caller still gets a faithful answer: providers are skipped —
+      // the refused spawn never becomes `present`, `missing`, or an empty list.
+      expect(await wirePhantomForRecipe(RECIPE, { cwd: projectDir })).toEqual({
+        present: [],
+        missing: [],
+        webhooks: [stubPath],
+        skipped: ["stripe", "neon"],
+      });
+      expect(calls).toEqual([
+        ["list", "--json"],
+        ["--version"],
+        ["list", "--json"],
+        ["list", "--json"],
+      ]);
+    },
+  );
+
+  it("treats a binary that vanishes between probe and read as missing — never an empty vault", async () => {
+    // `--version` answered, then `list` hits ENOENT: the not-installed mapping
+    // surfaces mid-wiring, and `skipped` keeps the providers' secrets unknown —
+    // `missing` would falsely claim they were verified absent.
+    script = failList({ error: "ENOENT" });
+
+    await expect(listSecrets(projectDir)).rejects.toMatchObject({
+      code: "PHANTOM_NOT_INSTALLED",
+    });
+    expect(await wirePhantomForRecipe(RECIPE, { cwd: projectDir })).toEqual({
+      present: [],
+      missing: [],
+      webhooks: [stubPath],
+      skipped: ["stripe", "neon"],
+    });
+    expect(calls).toEqual([["--version"], ["list", "--json"], ["list", "--json"]]);
+  });
+
+  it.each<[string, ScriptResult]>([
+    ["a refused spawn (EACCES)", { error: "EACCES" }],
+    ["a signal kill (SIGTERM)", { code: null, signal: "SIGTERM" }],
+  ])(
+    "maps %s on the `--version` probe to not-installed, never to a working phantom",
+    async (_label, probeResult) => {
+      script = (args) => (args[0] === "--version" ? probeResult : INSTALLED);
+
+      const expected = {
+        present: [],
+        missing: [],
+        webhooks: [stubPath],
+        skipped: ["stripe", "neon"],
+      };
+      expect(await wirePhantomForRecipe(RECIPE, { cwd: projectDir })).toEqual(expected);
+      expect(existsSync(stubPath)).toBe(true);
+      // The inventory read is never attempted.
+      expect(calls).toEqual([["--version"]]);
+
+      // A failed probe is cached for the process: a repeat request reports the
+      // same skipped result without re-spawning `--version`.
+      expect(await wirePhantomForRecipe(RECIPE, { cwd: projectDir })).toEqual(expected);
+      expect(calls).toEqual([["--version"]]);
+    },
+  );
+
+  it("does not cache a failed inventory read: the next call reports the recovered vault truthfully", async () => {
+    let listCalls = 0;
+    script = (args) => {
+      if (args[0] !== "list") return INSTALLED;
+      listCalls += 1;
+      return listCalls === 1
+        ? { code: 1, stderr: "vault locked" }
+        : { code: 0, stdout: '[{"name":"STRIPE_SECRET_KEY"}]' };
+    };
+
+    // The first caller gets the failure: both providers skipped, nothing
+    // claimed present or missing.
+    expect(await wirePhantomForRecipe(RECIPE, { cwd: projectDir })).toEqual({
+      present: [],
+      missing: [],
+      webhooks: [stubPath],
+      skipped: ["stripe", "neon"],
+    });
+
+    // The failure is not latched: once `list` answers, the next caller gets
+    // the real split — stored names present, absent names missing.
+    expect(await wirePhantomForRecipe(RECIPE, { cwd: projectDir })).toEqual({
+      present: ["stripe:STRIPE_SECRET_KEY"],
+      missing: ["neon:NEON_API_KEY", "neon:DATABASE_URL"],
+      webhooks: [stubPath],
+      skipped: [],
+    });
+    expect(calls).toEqual([["--version"], ["list", "--json"], ["list", "--json"]]);
+  });
+
+  it("rejects to the caller when a stub write fails on top of a failed read", async () => {
+    script = failList({ code: 1, stderr: "vault locked" });
+    // `stripe.ts` is a directory: writeFile refuses with EISDIR after the
+    // inventory read already failed.
+    mkdirSync(join(projectDir, ".stack/webhooks/stripe.ts"), { recursive: true });
+
+    // The write failure reaches the caller as the fs error itself — not a
+    // WireResult carrying half-finished state a caller could read as success.
+    await expect(wirePhantomForRecipe(RECIPE, { cwd: projectDir })).rejects.toMatchObject({
+      code: "EISDIR",
+    });
+    expect(calls).toEqual([["--version"], ["list", "--json"]]);
+  });
+});

package/src/ai/phantom-wire-known-placeholder-adjacent-punctuation.test.ts

@@ -0,0 +1,188 @@
+import { afterEach, beforeEach, describe, expect, it, setDefaultTimeout } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type Harness, setupFakePhantom } from "../__tests__/_harness.ts";
+import { verificationHintFor, webhookStubFor, wirePhantomForRecipe } from "./phantom-wire.ts";
+import type { Recipe } from "./recipe.ts";
+
+// The wiring check spawns the fake `phantom` shim (bash + python3); keep the
+// sibling files' raised timeout.
+setDefaultTimeout(30_000);
+
+const count = (s: string, needle: string) => s.split(needle).length - 1;
+
+describe("ai/phantom-wire known placeholder adjacent to punctuation", () => {
+  let harness: Harness;
+  let dir: string;
+
+  beforeEach(() => {
+    harness = setupFakePhantom();
+    dir = mkdtempSync(join(tmpdir(), "wire-punct-adjacent-"));
+  });
+  afterEach(() => {
+    harness.cleanup();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const recipe = (...names: string[]): Recipe => ({
+    id: "punct-adjacent",
+    query: "q",
+    createdAt: "2026-04-18T00:00:00.000Z",
+    providers: names.map((name) => ({ name })),
+  });
+
+  // The template's own marks (periods, parens, quotes, colons, dashes)
+  // measured off a mark-free name, so the per-mark arithmetic tracks
+  // template drift instead of pinning counts by hand.
+  const baseline = webhookStubFor("zzq");
+
+  it.each([
+    "pay.${provider}!", // `.` before and `!` after, mid-name
+    "(${capitalize(provider)})", // parens flush around the token
+    "hook:${webhookSecretKeyFor(provider)};", // `:` before, `;` after
+    "a,${signatureHeaderFor(provider)}?", // `,` before, `?` after
+    "x-${verificationHintFor(provider)}", // `-` before a trailing token
+    "${provider}.hook", // `.` after a leading token
+  ])("keeps the marks flush against the carried token at every site for %j", (name) => {
+    // Each name is ordinary text carrying one of the template's own slot
+    // spellings — a known placeholder — with punctuation flush on at least
+    // one side. Both are data: expansion fills the template's slots with the
+    // whole name, so the marks must land byte-for-byte beside the token,
+    // neither consumed into the slot's syntax nor split off it — while the
+    // token itself never resolves to the value its spelling names.
+    const stub = webhookStubFor(name);
+    const token = name.match(/\$\{[^}]*\}/)?.[0] as string;
+    const at = name.indexOf(token);
+    const left = name.slice(0, at);
+    const right = name.slice(at + token.length);
+
+    // The name — token and marks together — lands byte-for-byte at the
+    // three case-preserving sites and whole-name uppercased at the two
+    // secret-key sites. `capitalize` folds only the first code point: a
+    // letter-led name folds (`pay` → `Pay`); a mark- or `$`-led name passes
+    // through unchanged.
+    expect(stub).toContain(`webhook handler stub for ${name}.`);
+    expect(stub).toContain(`forge a ${name} webhook.`);
+    expect(stub).toContain(`handle${name[0].toUpperCase()}${name.slice(1)}Webhook(req: Request)`);
+    expect(count(stub, `phantom reveal ${name.toUpperCase()}_WEBHOOK_SECRET`)).toBe(2);
+
+    // Flank census: at every occurrence of the token — exact case at the
+    // three mixed-case sites, uppercased at the two reveal sites — the
+    // bytes immediately beside it are the name's own flanks (in that site's
+    // case), never the template's text. A slot-skipping render would leave
+    // the bare token hugged by `for `/`.`; a mark-eating one would show the
+    // name's letters or the template beside it instead.
+    const contexts: string[] = [];
+    for (const variant of [token, token.toUpperCase()]) {
+      for (let i = stub.indexOf(variant); i !== -1; i = stub.indexOf(variant, i + 1)) {
+        const l = stub.slice(i - left.length, i);
+        const r = stub.slice(i + variant.length, i + variant.length + right.length);
+        contexts.push(`${l}|${r}`.toLowerCase());
+      }
+    }
+    expect(contexts).toEqual(Array.from({ length: 5 }, () => `${left}|${right}`.toLowerCase()));
+
+    // Five `${...}` spans — one per expansion site — every one the carried
+    // token in that site's case: none resolved to the value its spelling
+    // names, none dropped, none duplicated.
+    const spans = [...stub.matchAll(/\$\{[^}]*\}/g)].map((m) => m[0]);
+    expect(spans).toHaveLength(5);
+    for (const span of spans) expect(span.toLowerCase()).toBe(token.toLowerCase());
+
+    // Mark accounting: every punctuation mark in the stub is either one the
+    // template contributes itself or one the name carried into its five
+    // expansion sites — none eaten, none doubled. The token's own `${`/`}`
+    // bytes are tracked by the span census above.
+    for (const mark of new Set(name.match(/[^a-zA-Z0-9${}]/g) ?? [])) {
+      expect(count(stub, mark)).toBe(count(baseline, mark) + 5 * count(name, mark));
+    }
+
+    // A second pass would re-resolve the carried token into the whole name,
+    // splicing the flanks around it again; neither flank ever repeats.
+    if (left) expect(stub).not.toContain(`${left}${left}`);
+    if (right) expect(stub).not.toContain(`${right}${right}`);
+
+    // The remaining slots took their own generic values in the same single
+    // pass — the carried token never reached their switch cases either.
+    expect(count(stub, 'req.headers.get("x-webhook-signature")')).toBe(1);
+    expect(count(stub, "//   // Verify per the provider's documented signature scheme.")).toBe(1);
+    expect(verificationHintFor(name)).toBe(verificationHintFor("zzq"));
+  });
+
+  it("pins `pay.${provider}!` line-for-line — the slot took the whole value, the marks stayed put", () => {
+    // The sharpest form: the carried token spells the name slot itself, so
+    // at the name sites the emitted text is indistinguishable from an
+    // unresolved slot. Exact-line equality pins every site: the slot was
+    // replaced once by `pay.${provider}!` — the `.` before and the `!`
+    // after the token arriving as data — and the template's own `.`
+    // follows the whole value untouched.
+    const stub = webhookStubFor("pay.${provider}!");
+
+    expect(stub).toContain(
+      "// Auto-generated by `stack apply` — webhook handler stub for pay.${provider}!.",
+    );
+    expect(stub).toContain("//   phantom reveal PAY.${PROVIDER}!_WEBHOOK_SECRET");
+    expect(stub).toContain(
+      "// export async function handlePay.${provider}!Webhook(req: Request): Promise<Response> {",
+    );
+    expect(stub).toContain("//   // to this endpoint can forge a pay.${provider}! webhook.");
+    expect(stub).toContain(
+      "//   // (`phantom reveal PAY.${PROVIDER}!_WEBHOOK_SECRET`) and compare in",
+    );
+
+    // Census: exactly five `${...}` spans — three original-case at the
+    // case-preserving sites, two folded at the reveal sites. A second pass
+    // would re-resolve each `${provider}` into `pay.${provider}!` again,
+    // doubling the `pay.` prefix and the `!` suffix; neither appears.
+    const tokens = [...stub.matchAll(/\$\{[^}]*\}/g)].map((m) => m[0]);
+    expect(tokens).toEqual([
+      "${provider}",
+      "${PROVIDER}",
+      "${provider}",
+      "${provider}",
+      "${PROVIDER}",
+    ]);
+    expect(stub).not.toContain("pay.pay");
+    expect(stub).not.toContain("!!");
+  });
+
+  it("skips a mark-adjacent placeholder name byte-for-byte through wiring and writes nothing for it", async () => {
+    // Through `wirePhantomForRecipe` the name matches no catalog provider:
+    // it returns in `skipped` byte-for-byte — marks and token intact — gets
+    // no stub on disk, and provokes no vault write. The known provider
+    // listed beside it wires normally, unaffected by the mark-wrapped,
+    // placeholder-shaped neighbour.
+    const name = "pay.${provider}!";
+    const stubPath = join(dir, ".stack", "webhooks", "supabase.ts");
+    const result = await wirePhantomForRecipe(recipe(name, "supabase"), { cwd: dir });
+
+    expect(result).toEqual({
+      present: [],
+      missing: [
+        "supabase:SUPABASE_URL",
+        "supabase:SUPABASE_ANON_KEY",
+        "supabase:SUPABASE_SERVICE_ROLE_KEY",
+      ],
+      webhooks: [stubPath],
+      skipped: [name],
+    });
+    expect(result.skipped[0]).toBe(name);
+
+    // Only supabase's documented stub lands — nothing for the mark-carrying
+    // name, and the stub on disk is the same render `webhookStubFor`
+    // returns, fully substituted.
+    expect(readdirSync(join(dir, ".stack", "webhooks"))).toEqual(["supabase.ts"]);
+    expect(readFileSync(stubPath, "utf-8")).toBe(webhookStubFor("supabase"));
+    expect(existsSync(join(dir, ".stack", "webhooks", `${name}.ts`))).toBe(false);
+
+    // The whole call log is reads (`--version`, `list`); the vault file
+    // still parses to an empty object.
+    expect(harness.calls().every((c) => c.cmd === "--version" || c.cmd === "list")).toBe(true);
+    expect(harness.callsTo("add")).toEqual([]);
+    expect(JSON.parse(readFileSync(harness.vaultPath, "utf-8"))).toEqual({});
+
+    // The hint is a fixed string: a mark-adjacent token never leaks into it.
+    expect(verificationHintFor(name)).toBe(verificationHintFor("zzq"));
+  });
+});

package/src/ai/phantom-wire-known-placeholder-at-end.test.ts

@@ -0,0 +1,160 @@
+import { afterEach, beforeEach, describe, expect, it, setDefaultTimeout } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type Harness, setupFakePhantom } from "../__tests__/_harness.ts";
+import { verificationHintFor, webhookStubFor, wirePhantomForRecipe } from "./phantom-wire.ts";
+import type { Recipe } from "./recipe.ts";
+
+// The wiring check spawns the fake `phantom` shim (bash + python3); keep the
+// sibling files' raised timeout.
+setDefaultTimeout(30_000);
+
+const count = (s: string, needle: string) => s.split(needle).length - 1;
+
+describe("ai/phantom-wire known placeholder at the end of a template", () => {
+  let harness: Harness;
+  let dir: string;
+
+  beforeEach(() => {
+    harness = setupFakePhantom();
+    dir = mkdtempSync(join(tmpdir(), "wire-trailing-known-"));
+  });
+  afterEach(() => {
+    harness.cleanup();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const recipe = (...names: string[]): Recipe => ({
+    id: "trailing-known-placeholder",
+    query: "q",
+    createdAt: "2026-04-18T00:00:00.000Z",
+    providers: names.map((name) => ({ name })),
+  });
+
+  it.each([
+    "${provider}", // the name slot's own spelling
+    "${capitalize(provider)}", // the handler-name slot's spelling
+    "${webhookSecretKeyFor(provider)}", // the secret-key slot's spelling
+    "${signatureHeaderFor(provider)}", // the header slot's spelling
+    "${verificationHintFor(provider)}", // the hint slot's spelling
+  ])(
+    "emits the trailing token %j verbatim with the preceding text intact at every site",
+    (slot) => {
+      // The name is ordinary text ending in one of the template's own slot
+      // spellings — a known placeholder at the very end, with nothing after
+      // it. `pay` is the preceding text the substitution must preserve.
+      // Because the token would resolve if inserted text were ever fed back
+      // through the slots, this is also a re-expansion case: a second pass
+      // would splice the whole name in again and double the `pay` prefix.
+      const name = `pay${slot}`;
+      const stub = webhookStubFor(name);
+
+      // The slot was replaced by the full name — prefix plus token — at the
+      // three case-preserving sites. A skipped slot would emit the bare
+      // `${provider}` after `for `; the `pay` prefix landing before the token
+      // proves the value was substituted whole.
+      expect(stub).toContain(`webhook handler stub for ${name}.`);
+      expect(stub).toContain(`forge a ${name} webhook.`);
+      // `capitalize` folds only the name's first letter: `pay` → `Pay`, and
+      // the trailing token rides along untouched.
+      expect(stub).toContain(`handlePay${slot}Webhook(req: Request)`);
+      // Both `toUpperCase()` secret-key sites fold prefix and token together —
+      // work only the substitution path does.
+      expect(count(stub, `phantom reveal PAY${slot.toUpperCase()}_WEBHOOK_SECRET`)).toBe(2);
+
+      // Five `${...}` spans — one per expansion site — every one the carried
+      // token in that site's case. Each sits flush at the END of the emitted
+      // name: the three bytes in front of it are always the name's own `pay`
+      // prefix (in whatever case that site's transform gives it), never the
+      // template's fixed text — proof the slot was replaced, not left raw.
+      const spans = [...stub.matchAll(/\$\{[^}]*\}/g)];
+      expect(spans).toHaveLength(5);
+      for (const span of spans) {
+        expect(span[0].toLowerCase()).toBe(slot.toLowerCase());
+        const at = span.index as number;
+        expect(stub.slice(at - 3, at).toLowerCase()).toBe("pay");
+      }
+      // And each is the last thing the name contributes — the template's own
+      // post-slot text (`.`, `Webhook`, ` webhook.`, `_WEBHOOK_SECRET`) picks
+      // up right where the token ends, never eaten or doubled.
+      expect(stub).not.toMatch(/paypay/i);
+      expect(count(stub, "_WEBHOOK_SECRET")).toBe(2);
+
+      // The remaining slots took their own generic values in the same single
+      // pass — the carried token never reached their switch cases either.
+      expect(stub).toContain('req.headers.get("x-webhook-signature")');
+      expect(stub).toContain("//   // Verify per the provider's documented signature scheme.");
+      expect(verificationHintFor(name)).toBe(verificationHintFor("zzq"));
+    },
+  );
+
+  it("pins `pay${provider}` line-for-line — the slot took the value, the prefix survived", () => {
+    // The sharpest form: the trailing token spells the name slot itself, so
+    // at the name sites the emitted text is indistinguishable from an
+    // unresolved slot. Exact-line equality pins every site: the slot was
+    // replaced by the name once, the `pay` prefix before it is intact, and
+    // no second pass spliced the name around the token again.
+    const stub = webhookStubFor("pay${provider}");
+
+    expect(stub).toContain(
+      "// Auto-generated by `stack apply` — webhook handler stub for pay${provider}.",
+    );
+    expect(stub).toContain("//   phantom reveal PAY${PROVIDER}_WEBHOOK_SECRET");
+    expect(stub).toContain(
+      "// export async function handlePay${provider}Webhook(req: Request): Promise<Response> {",
+    );
+    expect(stub).toContain("//   // to this endpoint can forge a pay${provider} webhook.");
+    expect(stub).toContain(
+      "//   // (`phantom reveal PAY${PROVIDER}_WEBHOOK_SECRET`) and compare in",
+    );
+
+    // Census: exactly five `${...}` spans — three original-case at the
+    // case-preserving sites, two folded at the reveal sites. Re-expansion
+    // would have produced `paypay${provider}` at every site; none appears.
+    const tokens = [...stub.matchAll(/\$\{[^}]*\}/g)].map((m) => m[0]);
+    expect(tokens).toEqual([
+      "${provider}",
+      "${PROVIDER}",
+      "${provider}",
+      "${provider}",
+      "${PROVIDER}",
+    ]);
+    expect(stub).not.toMatch(/paypay/i);
+  });
+
+  it("skips a trailing-placeholder name byte-for-byte through wiring and writes nothing for it", async () => {
+    // Through `wirePhantomForRecipe` the name matches no catalog provider:
+    // it returns in `skipped` byte-for-byte — `pay` prefix and trailing
+    // token intact — gets no stub on disk, and provokes no vault write. The
+    // known provider listed beside it wires normally, unaffected by the
+    // placeholder-shaped neighbour.
+    const name = "pay${provider}";
+    const stubPath = join(dir, ".stack", "webhooks", "github.ts");
+    const result = await wirePhantomForRecipe(recipe(name, "github"), { cwd: dir });
+
+    expect(result).toEqual({
+      present: [],
+      missing: ["github:GITHUB_TOKEN"],
+      webhooks: [stubPath],
+      skipped: [name],
+    });
+    expect(result.skipped[0]).toBe(name);
+
+    // Only github's documented stub lands — nothing for the
+    // placeholder-ended name, and the stub on disk is the same render
+    // `webhookStubFor` returns, fully substituted.
+    expect(readdirSync(join(dir, ".stack", "webhooks"))).toEqual(["github.ts"]);
+    expect(readFileSync(stubPath, "utf-8")).toBe(webhookStubFor("github"));
+    expect(existsSync(join(dir, ".stack", "webhooks", `${name}.ts`))).toBe(false);
+
+    // The whole call log is reads (`--version`, `list`); the vault file
+    // still parses to an empty object.
+    expect(harness.calls().every((c) => c.cmd === "--version" || c.cmd === "list")).toBe(true);
+    expect(harness.callsTo("add")).toEqual([]);
+    expect(JSON.parse(readFileSync(harness.vaultPath, "utf-8"))).toEqual({});
+
+    // The hint is a fixed string: a trailing-token name never leaks into it.
+    expect(verificationHintFor(name)).toBe(verificationHintFor("zzq"));
+  });
+});