@kirrosh/zond 0.23.0 → 0.26.0

package/src/core/generator/suite-generator.ts

@@ -2,7 +2,7 @@ import type { OpenAPIV3 } from "openapi-types";
 import type { EndpointInfo, SecuritySchemeInfo, CrudGroup } from "./types.ts";
 import type { RawSuite, RawStep } from "./serializer.ts";
 import type { SourceMetadata } from "../parser/types.ts";
-import { generateFromSchema, generateMultipartFromSchema } from "./data-factory.ts";
+import { generateFromSchema, generateMultipartFromSchema, isFkFixtureField, canonicalVarName, effectiveObjectShape } from "./data-factory.ts";
 import { groupEndpointsByTag } from "./chunker.ts";
 import { getAuthHeaders as sharedGetAuthHeaders } from "../probe/shared.ts";
 import { flattenToFormFields } from "../runner/form-encode.ts";
@@ -48,9 +48,16 @@ export function resourceVar(resource: string, suffix: string): string {
   return `${singular.replace(/[^a-zA-Z0-9]+/g, "_")}_${suffix}`.toLowerCase();
 }
 
-/** Convert OpenAPI path params {param} to test interpolation {{param}} */
-function convertPath(path: string): string {
-  return path.replace(/\{([^}]+)\}/g, "{{$1}}");
+/** Convert OpenAPI path params {param} to test interpolation {{param}}.
+ *  When `ambiguous` is given (ARV-369), a param name reused across
+ *  distinct resources becomes a resource-scoped var (`{{templates_code}}`)
+ *  instead of the raw name, so `.env.yaml` can hold distinct values per
+ *  resource instead of one value silently applying everywhere. */
+function convertPath(path: string, ambiguous?: Set<string>): string {
+  if (!ambiguous || ambiguous.size === 0) {
+    return path.replace(/\{([^}]+)\}/g, "{{$1}}");
+  }
+  return path.replace(/\{([^}]+)\}/g, (_, name) => `{{${fixtureVarNameForPathParam(path, name, ambiguous)}}}`);
 }
 
 /**
@@ -96,6 +103,75 @@ function slugify(s: string): string {
   return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
 }
 
+/** Strip trailing API-version path segments (`v1`, `v30`, `version2`) so
+ *  resource-name derivation doesn't mistake a version marker for the
+ *  resource itself on APIs shaped `/api/<resource>/v{N}` (ARV-372). */
+export function stripTrailingVersionSegments(segments: string[]): string[] {
+  const out = [...segments];
+  while (out.length > 1 && /^v(ersion)?\d+$/i.test(out[out.length - 1]!)) {
+    out.pop();
+  }
+  return out;
+}
+
+/** Owning collection for a path-param: the last non-version path segment
+ *  before its `{name}` placeholder. Used to disambiguate a path-param name
+ *  (`code`, `id`, `key`) that's reused across genuinely distinct resources
+ *  (ARV-369) — e.g. `/api/templates/v30/{code}` → "templates" vs
+ *  `/api/macros/v30/{code}` → "macros". */
+// ARV-376: read-by-id accessor markers — kept in sync with the set in
+// path-param-disambig.ts. `/business-segment20/byid/{id}` is owned by
+// `business-segment20`, not the `byid` accessor verb.
+const ACCESSOR_MARKER_SEGS = new Set(["byid", "by-id", "by_id"]);
+
+export function owningCollectionForPathParam(path: string, paramName: string): string | null {
+  const marker = `{${paramName}}`;
+  const idx = path.indexOf(marker);
+  if (idx === -1) return null;
+  const segments = stripTrailingVersionSegments(path.slice(0, idx).split("/").filter(Boolean));
+  // Skip trailing accessor markers so the owner is the collection, not the
+  // `byid`/`by-code` verb — otherwise a param behind `/byid/{id}` and its
+  // sibling `DELETE /{id}` disagree on owner and get double-scoped.
+  let end = segments.length - 1;
+  while (end >= 0 && ACCESSOR_MARKER_SEGS.has(segments[end]!.toLowerCase())) end--;
+  return end >= 0 ? segments[end]! : null;
+}
+
+/** Path-param names reused by more than one distinct owning collection
+ *  across the whole spec — these need a resource-scoped fixture var name
+ *  (`templates_code`) instead of the raw name (`code`), otherwise one
+ *  `.env.yaml` value silently applies to unrelated resources (ARV-369). */
+export function computeAmbiguousPathParams(endpoints: EndpointInfo[]): Set<string> {
+  const owners = new Map<string, Set<string>>();
+  for (const ep of endpoints) {
+    for (const p of ep.parameters) {
+      if (p.in !== "path" || p.required === false) continue;
+      const owner = owningCollectionForPathParam(ep.path, p.name) ?? "";
+      if (!owners.has(p.name)) owners.set(p.name, new Set());
+      owners.get(p.name)!.add(owner);
+    }
+  }
+  const ambiguous = new Set<string>();
+  for (const [name, ownerSet] of owners) {
+    if (ownerSet.size > 1) ambiguous.add(name);
+  }
+  return ambiguous;
+}
+
+/** Resource-scoped fixture var name for a path-param, when ambiguous;
+ *  otherwise the raw param name (single-owner APIs — the common case —
+ *  keep producing the same var names as before ARV-369). */
+export function fixtureVarNameForPathParam(
+  path: string,
+  paramName: string,
+  ambiguous: Set<string>,
+): string {
+  if (!ambiguous.has(paramName)) return paramName;
+  const owner = owningCollectionForPathParam(path, paramName);
+  if (!owner) return paramName;
+  return `${owner.replace(/[^a-zA-Z0-9]+/g, "_")}_${paramName}`;
+}
+
 function escapeRegex(s: string): string {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -242,6 +318,13 @@ function getSuiteHeaders(
 // stays stateless from the caller's perspective.
 let _suiteDefaultAuthVar: string | null = null;
 
+/** Same module-scoping rationale as `_suiteDefaultAuthVar` above: computed
+ *  once from the full endpoint list at the top of generateSuites (ARV-369
+ *  needs the whole spec to detect a param-name collision), consulted by
+ *  `generateStep`'s path conversion. Reset to empty at the end of
+ *  generateSuites. */
+let _ambiguousPathParams: Set<string> = new Set();
+
 /** Common id-like field names looked up after `id` itself.
  *  TASK-139: many real-world APIs return `slug`, `uuid`, `version`, `key`,
  *  or `name` instead of an `id` field on create responses. Without these,
@@ -348,6 +431,42 @@ export function buildOpenApiSuiteSource(specPath?: string): SourceMetadata | und
 // Public API
 // ──────────────────────────────────────────────
 
+/**
+ * ARV-45: swap FK-shaped required body fields for `{{fixture}}` references so
+ * their values come from `.env.yaml` instead of `{{$randomString}}`/`{{$uuid}}`
+ * junk that 400s and kills the CRUD chain at step 1. Field names that motivated
+ * this — `sequenceTypeCode`, `templateGroupCode` — are closed-vocab codes the
+ * generator can't guess. The var name is canonicalised (`sequence_type_code`)
+ * to match the manifest entry (fixtures-builder step 5); the HTTP body key
+ * keeps the raw spec spelling. Recurses into nested objects for nested FKs.
+ *
+ * Keep the detection predicate (`isFkFixtureField`) in lockstep with the
+ * manifest builder — every var the tests reference must appear in the manifest
+ * (decision-7).
+ */
+export function wireBodyFkRefs(schema: OpenAPIV3.SchemaObject, body: unknown): unknown {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return body;
+  // `effectiveObjectShape` merges allOf so allOf-wrapped bodies (the .NET/
+  // Swagger norm) resolve their properties — a direct schema.properties read
+  // misses every FK on those specs.
+  const { properties, required } = effectiveObjectShape(schema);
+  const out = body as Record<string, unknown>;
+  for (const [name, propSchema] of Object.entries(properties)) {
+    if (!(name in out)) continue;
+    if (required.has(name) && isFkFixtureField(name, propSchema)) {
+      out[name] = `{{${canonicalVarName(name)}}}`;
+    } else if (out[name] && typeof out[name] === "object" && !Array.isArray(out[name])) {
+      out[name] = wireBodyFkRefs(propSchema, out[name]);
+    }
+  }
+  return out;
+}
+
+/** Generate a request body from a schema with FK fields wired to fixtures. */
+function generateBody(schema: OpenAPIV3.SchemaObject): unknown {
+  return wireBodyFkRefs(schema, generateFromSchema(schema));
+}
+
 /** Generate a single test step from an EndpointInfo */
 export function generateStep(
   ep: EndpointInfo,
@@ -355,7 +474,7 @@ export function generateStep(
 ): RawStep {
   const method = ep.method.toUpperCase();
   const name = ep.operationId ?? ep.summary ?? `${method} ${ep.path}`;
-  const path = convertPath(ep.path);
+  const path = convertPath(ep.path, _ambiguousPathParams);
 
   const step: RawStep = {
     name,
@@ -379,9 +498,9 @@ export function generateStep(
       // the runner posts URL-encoded bodies with bracket notation. Without
       // this, generate baked `json:` blocks and every POST 400'd with
       // "wrong content type".
-      step.form = flattenToFormFields(generateFromSchema(ep.requestBodySchema));
+      step.form = flattenToFormFields(generateBody(ep.requestBodySchema));
     } else {
-      step.json = generateFromSchema(ep.requestBodySchema);
+      step.json = generateBody(ep.requestBodySchema);
     }
   }
 
@@ -450,7 +569,13 @@ export function detectCrudGroupsWithDiagnostics(
 
   for (const createEp of postEndpoints) {
     const basePath = stripTrailingSlash(createEp.path);
-    const resource = basePath.split("/").filter(Boolean).pop() ?? "resource";
+    // ARV-372: skip trailing version segments (`v1`, `v30`) before taking the
+    // last segment as the resource name — otherwise every collection on a
+    // spec shaped `/api/<resource>/v{N}` (a common convention) resolves to
+    // the SAME resource name ("v30"), and multiple CRUD suites collide on
+    // the same `crud-<resource>.yaml` output filename, silently overwriting
+    // each other.
+    const resource = stripTrailingVersionSegments(basePath.split("/").filter(Boolean)).pop() ?? "resource";
 
     // Match `<basePath>/{param}` with optional trailing slash. Tolerates
     // both `POST /alerts/` + `GET /alerts/{id}` and `POST /alerts` +
@@ -500,11 +625,15 @@ export function detectCrudGroupsWithDiagnostics(
       ep => ["PUT", "PATCH"].includes(ep.method.toUpperCase()),
     );
     const del = resolvedItemEndpoints.find(ep => ep.method.toUpperCase() === "DELETE");
-    // List endpoint matches with the same trailing-slash tolerance.
+    // List endpoint matches with the same trailing-slash tolerance. ARV-376:
+    // also accept a `/list`, `/search`, `/find` verb suffix on the base path
+    // (`GET /api/deal-kind20/list`) — common in RPC-flavoured REST specs
+    // where the bare collection path has no GET.
+    const listStems = [basePath, `${basePath}/list`, `${basePath}/search`, `${basePath}/find`];
     const list = endpoints.find(
       ep =>
         ep.method.toUpperCase() === "GET" &&
-        stripTrailingSlash(ep.path) === basePath &&
+        listStems.includes(stripTrailingSlash(ep.path)) &&
         !ep.deprecated,
     );
 
@@ -573,11 +702,31 @@ export function detectCrudGroupsWithDiagnostics(
 }
 
 /** Generate a CRUD chain suite from a CrudGroup */
+/** ARV-368: does the create's success response actually carry the capture
+ *  field? If not — a 204 no-body create, or a response schema without the id —
+ *  the runtime capture is empty and `{{captureVar}}` falls back to the
+ *  read-fixture of the SAME name (ARV-137 deliberately shares it). A PUT/DELETE
+ *  then targets a *pre-existing* resource whose id the user harvested for read
+ *  coverage — silent data-loss. Gate mutating chain steps on this so the suite
+ *  can only ever update/delete what it actually captured, never live data. */
+function createCapturesId(
+  create: EndpointInfo | undefined,
+  captureField: string,
+): boolean {
+  if (!create) return false;
+  const props = getSuccessSchema(create)?.properties;
+  return !!props && captureField in props;
+}
+
 export function generateCrudSuite(
   group: CrudGroup,
   securitySchemes: SecuritySchemeInfo[],
 ): RawSuite {
   const captureField = group.create ? getCaptureField(group.create, group.idParam) : "id";
+  // ARV-368: only chain PUT/DELETE when the create response yields the id we'd
+  // capture. Otherwise the capture is empty at runtime and the mutating step
+  // falls back to the shared read-fixture → deletes/overwrites pre-existing data.
+  const canChainMutations = createCapturesId(group.create, captureField);
   // ARV-137: use the spec's path-param name as the capture var. Previously
   // we synthesised `<resource>_id` via `resourceVar(...)`, which produced
   // phantom manifest dupes whenever the spec named the path-param anything
@@ -622,8 +771,9 @@ export function generateCrudSuite(
     tests.push(step);
   }
 
-  // 3. Update
-  if (group.update) {
+  // 3. Update (ARV-368: only if the chain self-captures its id — else the
+  //    fixture-fallback would overwrite a pre-existing resource)
+  if (group.update && canChainMutations) {
     const method = group.update.method.toUpperCase();
     const itemPath = convertPath(group.itemPath).replace(`{{${group.idParam}}}`, `{{${captureVar}}}`);
     const etagVar = resourceVar(group.resource, "etag");
@@ -653,13 +803,14 @@ export function generateCrudSuite(
       step.headers = { "If-Match": `"{{${etagVar}}}"` };
     }
     if (group.update.requestBodySchema) {
-      step.json = generateFromSchema(group.update.requestBodySchema);
+      step.json = generateBody(group.update.requestBodySchema);
     }
     tests.push(step);
   }
 
-  // 4. Delete
-  if (group.delete) {
+  // 4. Delete (ARV-368: only if the chain self-captures its id — else the
+  //    fixture-fallback would DELETE a pre-existing resource → data-loss)
+  if (group.delete && canChainMutations) {
     const itemPath = convertPath(group.itemPath).replace(`{{${group.idParam}}}`, `{{${captureVar}}}`);
     const etagVar = resourceVar(group.resource, "etag");
 
@@ -938,6 +1089,7 @@ export function generateSuites(opts: {
 }): RawSuite[] {
   const { endpoints, securitySchemes, specPath, includeDeprecated, defaultAuthVar } = opts;
   _suiteDefaultAuthVar = defaultAuthVar ?? null;
+  _ambiguousPathParams = computeAmbiguousPathParams(endpoints);
 
   // Filter deprecated unless caller opted in. The list of skipped paths is
   // exposed separately via `getSkippedDeprecated` for stdout reporting.
@@ -1144,5 +1296,6 @@ export function generateSuites(opts: {
   }
 
   _suiteDefaultAuthVar = null;                                                                  // ARV-212
+  _ambiguousPathParams = new Set();                                                              // ARV-369
   return allSuites;
 }

package/src/core/generator/types.ts

@@ -28,6 +28,12 @@ export interface EndpointInfo {
   security: string[];
   deprecated?: boolean;
   requiresEtag?: boolean;
+  /** ARV-189 (m-21): vendor extensions starting with `x-` from the
+   *  operation (and merged from the path item — operation wins on key
+   *  collision). Used by the `x-zond-*` opt-in/skip rules so callers can
+   *  declare check-level policy directly in the spec without an overlay
+   *  yaml file. Empty/undefined when the spec carries no extensions. */
+  extensions?: Record<string, unknown>;
 }
 
 export interface SecuritySchemeInfo {

package/src/core/output/README.md

@@ -1,19 +1,15 @@
 # core/output — typed `--report` / `--output` / `--json` policy
 
 `OutputSpec<Payload>` is the single source-of-truth for how a command
-produces output. Per-command parsers (`checks run`, `probe security`,
-`run`, …) are migrated in ARV-117/118/119 — this directory only ships
-the infrastructure.
-
-Closes the seven divergent-output bugs collected in
+produces output. Closes the seven divergent-output bugs collected in
 `strategy/lessons.md` §E (ARV-50, ARV-82, ARV-97, …) by replacing N
 ad-hoc parsers with one resolver.
 
 ## Policy matrix
 
-The runner (`runCommandWithOutput`) reads `--report`, `--output`, and
-`--json` from the CLI layer and resolves them to a `ResolvedOutput`
-decision according to this matrix:
+`resolveOutput(spec, opts)` reads `--report`, `--output`, and `--json`
+from the CLI layer and resolves them to a `ResolvedOutput` decision
+according to this matrix:
 
 | Input                                | Format         | Channel             | Notes |
 | ------------------------------------ | -------------- | ------------------- | ----- |
@@ -50,30 +46,16 @@ export const CHECKS_RUN_OUTPUT: OutputSpec<ChecksPayload> = {
     // `--report ndjson` is a friendly alias retained from skill prompts.
     ndjson: "ndjson",
   },
-  render: (format, payload) => {
-    if (format === "sarif")  return generateSarifReport(payload);
-    if (format === "ndjson") return payload.findings.map(f => JSON.stringify(f)).join("\n");
-    return JSON.stringify(payload, null, 2);
-  },
 };
 ```
 
-The CLI handler then does:
-
-```ts
-const { resolved, exitCode } = await runCommandWithOutput(
-  CHECKS_RUN_OUTPUT,
-  cmd.opts<OutputOptions>(),
-  async () => runChecks({ /* ... */ }),
-);
-process.exit(exitCode);
-```
-
-`resolveOutput()` can be called standalone (without rendering) when a
-command wants to plug the resolution into its own streaming pipeline —
-e.g. `checks run` opens an fd ahead of time and feeds events into it
-incrementally; in that case the command consumes `resolved.path` and
-`resolved.channel` and handles I/O itself.
+The CLI handler calls `resolveOutput()` and renders/writes the payload
+itself — each command's shape (streaming vs single-shot, envelope vs
+raw) differs enough that a shared render/write runner added indirection
+without removing per-command logic. `checks run` and `probe *` open an
+fd from `resolved.path`/`resolved.channel` and feed output into it
+incrementally; `run` renders a single payload and writes it once. See
+any of `src/cli/commands/{run,checks,probe}.ts` for the pattern.
 
 ## Why the format set is open
 

package/src/core/output/index.ts

@@ -10,4 +10,4 @@ export type {
   ResolvedOutput,
 } from "./types.ts";
 export { OutputSpecError } from "./types.ts";
-export { resolveOutput, runCommandWithOutput, type RunOutputResult } from "./run.ts";
+export { resolveOutput } from "./run.ts";

package/src/core/output/run.ts

@@ -89,38 +89,3 @@ function pickEnvelopeFormat<P>(spec: OutputSpec<P>): string | undefined {
   return undefined;
 }
 
-export interface RunOutputResult<P> {
-  resolved: ResolvedOutput;
-  payload: P;
-  exitCode: number;
-}
-
-/** Render and write the payload according to the resolved decision.
- *  Returns the resolved decision plus the exit code from the spec's
- *  `exitCodePolicy` (0 by default). The CLI handler typically passes
- *  the exit code straight to `process.exit`. */
-export async function runCommandWithOutput<P>(
-  spec: OutputSpec<P>,
-  opts: OutputOptions,
-  produce: () => Promise<P>,
-): Promise<RunOutputResult<P>> {
-  const resolved = resolveOutput(spec, opts);
-  const payload = await produce();
-
-  if (!spec.render) {
-    throw new OutputSpecError(
-      `OutputSpec for "${spec.command}" has no render() hook — cannot serialise payload`,
-    );
-  }
-  const body = spec.render(resolved.format, payload);
-
-  if (resolved.channel === "file") {
-    await Bun.write(resolved.path!, body);
-  } else {
-    process.stdout.write(body);
-    if (!body.endsWith("\n")) process.stdout.write("\n");
-  }
-
-  const exitCode = spec.exitCodePolicy ? spec.exitCodePolicy(payload) : 0;
-  return { resolved, payload, exitCode };
-}

package/src/core/output/types.ts

@@ -83,13 +83,6 @@ export interface OutputSpec<Payload = unknown> {
    *  skill prompts ship it). Keys are flag values seen on the CLI;
    *  values are the resolved format name. */
   aliases?: Record<string, OutputFormat>;
-  /** Optional pre-validated render hook. Called by the runner once
-   *  the format is resolved. Receives the payload plus the resolved
-   *  format and returns the serialized output. */
-  render?: (format: OutputFormat, payload: Payload) => string;
-  /** Optional exit-code policy. Receives the payload after a
-   *  successful run; returns the process exit code (0 by default). */
-  exitCodePolicy?: (payload: Payload) => number;
 }
 
 /** Decision the runner makes after applying the spec to CLI flags. */

package/src/core/parser/dynamic-values.ts

@@ -0,0 +1,160 @@
+/**
+ * `#(funcName)` / `#(funcName(args))` dynamic-value substitution for
+ * loaded YAML values (ARV-190, m-21).
+ *
+ * Lets a workspace avoid stale hardcoded data — UUIDs that get reused
+ * by the API and pin existing rows, dates that expire days after
+ * checkout, idempotency keys that race against past runs. Functions
+ * are evaluated at LOAD time (per-run, not per-request), so a single
+ * `#(uuid)` reference resolves to the same value across every step
+ * inside one run — the idempotency-replay scenarios only work if the
+ * key stays stable for the run's lifetime.
+ *
+ * Supported functions:
+ *   #(uuid)              — fresh UUID v4 (stable within one run via cache)
+ *   #(uuidStable(seed))  — deterministic UUID derived from seed (sha-256 → v4 shape)
+ *   #(today)             — YYYY-MM-DD now (UTC)
+ *   #(todayPlus(N))      — today + N days (N may be negative)
+ *   #(now)               — ISO 8601 timestamp
+ *   #(unix)              — seconds since epoch
+ *   #(alphanumeric(N))   — N random a-z0-9 chars
+ *   #(env:VAR)           — process.env.VAR (alias for ${VAR})
+ *
+ * Resolution order: env-interpolation (${VAR}) runs first because its
+ * default-value syntax can produce strings the dynamic resolver should
+ * see literally. Dynamic values run BEFORE @secret/@identity reference
+ * resolution so the function tokens never leak into a secret-typed
+ * value (and so secret-stored values that happen to look like `#(...)`
+ * stay opaque). Strings that have no `#(` substring short-circuit.
+ *
+ * Nested forms: a single value may carry multiple references mixed
+ * with literal text — `"req-#(uuid)-#(today)"` yields `req-<uuid>-2026-05-16`.
+ */
+
+import { createHash } from "node:crypto";
+
+export interface DynamicValueContext {
+  /** Per-run cache keyed by raw expression (`#(uuid)`, `#(today)`). */
+  cache: Map<string, string>;
+  /** Source of env vars; defaults to process.env. Override in tests. */
+  env?: Record<string, string | undefined>;
+  /** File path the value came from — surfaced in error messages. */
+  filePath?: string;
+}
+
+/** Build a fresh cache for one resolution pass. Exported so the caller
+ *  can share a cache across multiple `resolveDynamicValuesDeep` calls
+ *  that belong to the same run (e.g. workspace + per-API env files). */
+export function newDynamicCache(): Map<string, string> {
+  return new Map();
+}
+
+// Captures `#(funcName)` or `#(funcName(args))`. `args` may contain any
+// chars except an unescaped closing paren — keep it simple, the funcs we
+// support take string or integer args without nested parens.
+const FUNC_RE = /#\(([A-Za-z_][A-Za-z0-9_]*)(?::([^)]*))?(?:\(([^)]*)\))?\)/g;
+
+export function resolveDynamicValues(
+  text: string,
+  ctx: DynamicValueContext,
+): string {
+  if (typeof text !== "string" || text.indexOf("#(") === -1) return text;
+  return text.replace(FUNC_RE, (full, name: string, colonArg: string | undefined, parenArg: string | undefined) => {
+    const cached = ctx.cache.get(full);
+    if (cached !== undefined) return cached;
+    const value = evaluate(name, colonArg ?? parenArg, full, ctx);
+    ctx.cache.set(full, value);
+    return value;
+  });
+}
+
+export function resolveDynamicValuesDeep(
+  obj: Record<string, unknown>,
+  ctx: DynamicValueContext,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (typeof v === "string") {
+      out[k] = resolveDynamicValues(v, ctx);
+    } else {
+      out[k] = String(v);
+    }
+  }
+  return out;
+}
+
+function evaluate(
+  name: string,
+  arg: string | undefined,
+  fullExpr: string,
+  ctx: DynamicValueContext,
+): string {
+  switch (name) {
+    case "uuid":
+      return crypto.randomUUID();
+    case "uuidStable": {
+      if (!arg) throw makeError(`#(uuidStable(seed)) requires a seed argument`, fullExpr, ctx);
+      return seedToUuid(arg);
+    }
+    case "today":
+      return new Date().toISOString().slice(0, 10);
+    case "todayPlus": {
+      if (!arg) throw makeError(`#(todayPlus(N)) requires an integer N`, fullExpr, ctx);
+      const n = Number.parseInt(arg, 10);
+      if (!Number.isFinite(n)) throw makeError(`#(todayPlus(${arg})) — N must be an integer`, fullExpr, ctx);
+      const d = new Date();
+      d.setUTCDate(d.getUTCDate() + n);
+      return d.toISOString().slice(0, 10);
+    }
+    case "now":
+      return new Date().toISOString();
+    case "unix":
+      return String(Math.floor(Date.now() / 1000));
+    case "alphanumeric": {
+      const n = arg ? Number.parseInt(arg, 10) : 8;
+      if (!Number.isFinite(n) || n <= 0 || n > 1024) {
+        throw makeError(`#(alphanumeric(${arg ?? ""})) — length must be 1..1024`, fullExpr, ctx);
+      }
+      return randomAlphanumeric(n);
+    }
+    case "env": {
+      if (!arg) throw makeError(`#(env:VAR) requires a variable name`, fullExpr, ctx);
+      const env = ctx.env ?? (process.env as Record<string, string | undefined>);
+      const v = env[arg];
+      if (v === undefined || v === "") {
+        throw makeError(`#(env:${arg}) is not set — define it in your shell or CI secret`, fullExpr, ctx);
+      }
+      return v;
+    }
+    default:
+      throw makeError(`unknown dynamic function "${name}" in ${fullExpr} — supported: uuid, uuidStable, today, todayPlus, now, unix, alphanumeric, env`, fullExpr, ctx);
+  }
+}
+
+function seedToUuid(seed: string): string {
+  // SHA-256 the seed, take first 16 bytes, format as UUID v4 shape so
+  // any consumer-side `format: uuid` validator accepts it. Variant +
+  // version bits are forced to match v4 — the value is still
+  // deterministic because the source bytes are stable per seed.
+  const hash = createHash("sha256").update(seed).digest();
+  const bytes = Buffer.from(hash.subarray(0, 16));
+  bytes[6] = (bytes[6]! & 0x0f) | 0x40;  // version 4
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80;  // RFC 4122 variant
+  const hex = bytes.toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
+const ALPHANUM = "abcdefghijklmnopqrstuvwxyz0123456789";
+
+function randomAlphanumeric(n: number): string {
+  let out = "";
+  for (let i = 0; i < n; i++) {
+    out += ALPHANUM[Math.floor(Math.random() * ALPHANUM.length)];
+  }
+  return out;
+}
+
+function makeError(msg: string, expr: string, ctx: DynamicValueContext): Error {
+  const where = ctx.filePath ? ` (referenced from ${ctx.filePath})` : "";
+  return new Error(`Dynamic value ${expr}: ${msg}${where}`);
+}

package/src/core/probe/dry-run-envelope.ts

@@ -53,5 +53,9 @@ export function formatDryRunDigest(plans: EndpointPlan[]): string {
   const summary = summarizeDryRun(plans).summary;
   lines.push("");
   lines.push(`Plan: ${summary.planned} planned · ${summary.skipped} skipped · ${summary.totalEndpoints} total`);
+  // ARV-309: the plan above lists what *would* be attacked — no traffic was
+  // sent. Without this line a reader can't tell "ran, found nothing" from
+  // "never fired" (the plan reads like a findings list). State it explicitly.
+  lines.push("Dry-run: mutation probes NOT executed — no requests sent. Re-run without --dry-run to attack live.");
   return lines.join("\n");
 }