@kirrosh/zond 0.26.1 → 0.27.1

package/src/core/generator/resources-builder.ts

@@ -1,898 +0,0 @@
-/**
- * Build `.api-resources.yaml` — the CRUD-chain map of an API.
- *
- * Purpose: skill code (scenario authoring, audit setup) reads this instead
- * of grep'ing the OpenAPI spec to answer "what resources can I CRUD, what
- * field captures the id, are there ETag / soft-delete pitfalls". The
- * extended form also lists FK dependencies so a scenario can plan a
- * setup chain (audience → contact requires audience_id, etc.).
- *
- * The file is git-trackable evidence of the API's surface; regenerated
- * by `zond add api` and (later) `zond refresh-api`.
- */
-
-import type { EndpointInfo, CrudGroup } from "./types.ts";
-import type { OpenAPIV3 } from "openapi-types";
-import { detectCrudGroups, singularizeResource, stripTrailingVersionSegments } from "./suite-generator.ts";
-
-export interface ResourceFkRef {
-  /** Variable name expected in `.env.yaml` to satisfy the FK (e.g. `audience_id`). */
-  var: string;
-  /** Path-parameter or body-field name that consumes the FK in the API. */
-  param: string;
-  /** Where the value gets injected: path | body. */
-  in: "path" | "body";
-  /** Resource name we believe owns this id (best-effort, may be null). */
-  ownerResource: string | null;
-}
-
-/**
- * ARV-169 (m-20 cross-call drift): per-resource overrides for the
- * POST→GET shape-diff probe. All fields optional — when absent the
- * check falls back to `DEFAULT_READBACK_IGNORE` (timestamp / etag /
- * envelope quirks) so a probe works on a stock spec without yaml work.
- * Authored by `zond api annotate --readback` (ARV-187) or by hand.
- */
-export interface ReadbackDiffConfig {
-  /** Field names dropped before diff. Suppresses known API-quirks
-   *  (Stripe `metadata` stripping, livemode, object discriminators)
-   *  so they don't drown out real drift. */
-  ignoreFields?: string[];
-  /** Write-shape → read-shape rename. Stripe takes `tax_id_data` on
-   *  create but exposes it as `tax_ids` on read; without this the
-   *  field looks like state-not-persisted on every probe. */
-  writeToReadMap?: Record<string, string>;
-}
-
-/**
- * ARV-170 (m-20 idempotency-replay): per-resource declaration that the
- * create endpoint honors an Idempotency-Key header. When present, the
- * `idempotency_replay` stateful check sends POST twice with the same
- * key and asserts (a) no duplicate resource is created and (b) the two
- * responses are bit-identical modulo `ignoreResponseFields`.
- *
- * Auto-detect fallback: if `idempotency:` is absent from yaml but the
- * create endpoint declares an `Idempotency-Key` header parameter in
- * the spec, the check still runs with `header="Idempotency-Key"` and
- * the default ignore list. Explicit yaml is preferred — it documents
- * intent and lets the user customise the ignore list per API quirks
- * (Stripe `request_id`, Resend `retry_after`).
- */
-export interface IdempotencyConfig {
-  /** Header that carries the key. Default `Idempotency-Key`. */
-  header?: string;
-  /** Informational. `endpoint` = key scoped per-endpoint (Stripe).
-   *  `global` = same key replays across endpoints. Today the check
-   *  uses the same flow either way; field is read for diagnostics. */
-  scope?: "endpoint" | "global";
-  /** Response-body field names stripped before the R1==R2 compare.
-   *  Defaults to a baseline list shared with readback-diff
-   *  (timestamps, request_id, etag) when omitted. */
-  ignoreResponseFields?: string[];
-}
-
-/**
- * ARV-171 (m-20 pagination-invariants): per-list-endpoint declaration
- * of the pagination strategy. The `pagination_invariants` stateful
- * check uses this to ask for two consecutive pages and assert
- * disjointness + has_more consistency.
- *
- * Supported types in this milestone:
- *   • `cursor` — Stripe-style: caller passes a cursor (e.g.
- *     `starting_after=<id>`) derived from the last item of the
- *     previous page.
- *   • `page` — page-number style (GitHub, GitLab, Atlassian, Notion,
- *     Linear): `?page=N&per_page=M`. ARV-220 enabled this in m-21.
- *   • `offset` and `token` — declared for forward compatibility; the
- *     check currently skips with a "pagination type not implemented"
- *     reason so the yaml block stays a stable schema.
- *
- * Auto-detect fallback: if the list endpoint declares `starting_after`
- * / `cursor` / `page_token` query parameters in the spec, the check
- * uses sensible defaults (cursor_field=`id`, items_field=`data` →
- * `items` → `results`, has_more_field=`has_more`). Explicit yaml is
- * preferred — it documents intent and survives spec changes that
- * rename query params.
- */
-/**
- * ARV-172 (m-20 lifecycle-transitions): declared state machine for a
- * resource. Used by the `lifecycle_transitions` stateful check to
- * verify that documented actions (cancel / archive / publish / ...)
- * move a resource between declared states and that double-invoking an
- * action either 4xx's or stays idempotent (no state regression).
- *
- * The yaml block has three parts:
- *   • `field` + `states` — name of the response field carrying the
- *     state, plus the closed enum of legal values.
- *   • `transitions` — a from→to graph; the check uses it to flag
- *     forbidden transitions (cancelled → active) when an action lands
- *     a resource somewhere the graph doesn't allow.
- *   • `actions` — POST endpoints that should drive a transition.
- *     `expected_state` is the state the resource must be in after a
- *     successful action call.
- *
- * Manifest validation runs at load time and surfaces obvious
- * authoring bugs (unreachable states, missing terminal, action
- * referencing an undeclared state) before any HTTP call goes out.
- */
-export interface LifecycleAction {
-  /** Endpoint label, e.g. "POST /v1/subscriptions/{id}/cancel". The
-   *  `{id}` placeholder is substituted with the created resource id. */
-  endpoint: string;
-  /** State the resource must be in after this action lands. */
-  expectedState: string;
-  /** Optional request body sent with the action POST. Most lifecycle
-   *  actions are body-less (cancel, archive, publish); leave empty
-   *  when not needed. Serialised as JSON or form depending on the
-   *  endpoint's declared content type. */
-  body?: Record<string, unknown>;
-}
-
-export interface LifecycleConfig {
-  /** Response field name carrying the state (e.g. `status`). */
-  field: string;
-  /** Closed enum of legal state values. Any state observed on the
-   *  wire that isn't in this list is a finding. */
-  states: string[];
-  /** Allowed from→to graph. States not listed as `from` are assumed
-   *  terminal (no outgoing transition). States not listed as `to` of
-   *  any transition are starting-only (unreachable post-create). */
-  transitions: { from: string; to: string[] }[];
-  /** Named actions keyed by action name (cancel / archive / publish).
-   *  The check runs through them in object-key order. */
-  actions: Record<string, LifecycleAction>;
-}
-
-/**
- * Static validation of a lifecycle manifest. Returns the list of
- * authoring bugs without throwing — callers decide whether to fail
- * the run or just warn. Empty array = clean manifest.
- */
-export function validateLifecycleManifest(cfg: LifecycleConfig): string[] {
-  const errors: string[] = [];
-  if (!cfg.field || cfg.field.length === 0) errors.push("lifecycle.field is empty");
-  if (!cfg.states || cfg.states.length === 0) errors.push("lifecycle.states is empty");
-  const stateSet = new Set(cfg.states ?? []);
-  for (const t of cfg.transitions ?? []) {
-    if (!stateSet.has(t.from)) errors.push(`transitions: unknown "from" state "${t.from}"`);
-    for (const to of t.to) {
-      if (!stateSet.has(to)) errors.push(`transitions[${t.from}]: unknown "to" state "${to}"`);
-    }
-  }
-  // At least one terminal — a state with no outgoing transition (or
-  // an explicit `to: []`). A graph with every state having outgoing
-  // edges is suspicious (no end-of-life, infinite churn).
-  const hasOutgoing = new Set((cfg.transitions ?? []).filter((t) => t.to.length > 0).map((t) => t.from));
-  const terminals = (cfg.states ?? []).filter((s) => !hasOutgoing.has(s));
-  if (terminals.length === 0) errors.push("no terminal state — every declared state has outgoing transitions");
-  // Actions must reference declared states.
-  for (const [name, a] of Object.entries(cfg.actions ?? {})) {
-    if (!stateSet.has(a.expectedState)) {
-      errors.push(`actions.${name}.expected_state "${a.expectedState}" is not in states[]`);
-    }
-    if (!a.endpoint || a.endpoint.length === 0) {
-      errors.push(`actions.${name}.endpoint is empty`);
-    }
-  }
-  return errors;
-}
-
-export interface PaginationConfig {
-  /** Pagination flavor. Default `cursor`. */
-  type?: "cursor" | "page" | "offset" | "token";
-  /** Query-param name that takes the cursor value. Default `starting_after`.
-   *  Only used when `type: cursor`. */
-  cursorParam?: string;
-  /** Response field on each item that becomes the next cursor (cursor-style)
-   *  and the dedupe key when comparing pages (both styles). Default `id`. */
-  cursorField?: string;
-  /** Response field that signals "more pages remain". Default `has_more`.
-   *  Only consulted for `type: cursor` — page-style APIs typically rely on
-   *  Link headers or `total_pages` instead, so the field is ignored there. */
-  hasMoreField?: string;
-  /** Query-param name for page size. Default `limit` for cursor-style,
-   *  `per_page` for page-style. */
-  limitParam?: string;
-  /** Probe page-size. Default 2 (small enough to land two replies fast). */
-  defaultLimit?: number;
-  /** Response field carrying the array of items. Default `data` (Stripe);
-   *  falls back to `items` / `results` when missing. */
-  itemsField?: string;
-  /** Page-number query-param name. Default `page`. Only used when `type: page`. */
-  pageParam?: string;
-  /** First page number (1-based on GitHub/GitLab, 0-based on some custom APIs).
-   *  Default 1. Only used when `type: page`. */
-  startPage?: number;
-}
-
-/** ARV-187: LLM-authored example POST body. Stateful checks prefer this
- *  over generateFromSchema(create) when present. */
-export interface SeedBodyConfig {
-  /** Defaults to the create endpoint's requestBodyContentType. */
-  contentType?: string;
-  body: Record<string, unknown>;
-}
-
-export interface ApiResourceEntry {
-  resource: string;
-  basePath: string;
-  itemPath: string;
-  idParam: string;
-  /** What field on the create response carries the new id (typically `id`). */
-  captureField: string;
-  /** True when the resource exposes List + Create + Read at minimum. */
-  hasFullCrud: boolean;
-  endpoints: {
-    list?: string;     // "GET /audiences"
-    create?: string;
-    read?: string;
-    update?: string;
-    delete?: string;
-  };
-  /** Update/Delete demand If-Match? (heuristic: 412 in spec or ETag in headers). */
-  requiresEtag?: boolean;
-  /** Heuristic: read-after-delete returns 200 instead of 404 (filled at runtime, default false). */
-  softDelete?: boolean;
-  /** Other resources whose ids this resource consumes (FK chain). */
-  fkDependencies: ResourceFkRef[];
-  /** ARV-169: optional cross-call-drift overrides. */
-  readbackDiff?: ReadbackDiffConfig;
-  /** ARV-170: opt-in idempotency-replay probe. */
-  idempotency?: IdempotencyConfig;
-  /** ARV-171: pagination-invariants probe. */
-  pagination?: PaginationConfig;
-  /** ARV-172: state-machine for the resource. */
-  lifecycle?: LifecycleConfig;
-}
-
-export interface ApiResourceMap {
-  generatedAt: string;
-  specHash: string;
-  resourceCount: number;
-  resources: ApiResourceEntry[];
-  /** Endpoints that didn't fit any CRUD group (action endpoints, RPC-style). */
-  orphanEndpoints: string[];
-}
-
-function epLabel(ep: EndpointInfo): string {
-  return `${ep.method.toUpperCase()} ${ep.path}`;
-}
-
-function pathStripSlash(p: string): string {
-  return p.length > 1 && p.endsWith("/") ? p.slice(0, -1) : p;
-}
-
-function isParamSeg(seg: string | undefined): boolean {
-  return !!seg && /^\{[^}]+\}$/.test(seg);
-}
-
-function escapeRegex(s: string): string {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-/**
- * ARV-134 (resource-builder fix #1): when two CRUD groups would collide on
- * the same `resource` name (e.g. `POST /segments` and `POST /contacts/
- * {contact_id}/segments` both produce `resource: "segments"`), keep the
- * canonical (shortest basePath) entry and rename the nested ones to
- * `<parent-noun>_<resource>` — `contact_segments` here. Without this,
- * `.api-resources.yaml` ends up with duplicate entries that break
- * map-by-name lookups (annotate overlay, refresh-api idempotence,
- * stateful-check resource configs).
- */
-function disambiguateResourceCollisions(groups: CrudGroup[]): CrudGroup[] {
-  const byName = new Map<string, CrudGroup[]>();
-  for (const g of groups) {
-    const arr = byName.get(g.resource) ?? [];
-    arr.push(g);
-    byName.set(g.resource, arr);
-  }
-
-  const renames = new Map<CrudGroup, string>();
-  const usedNames = new Set<string>(byName.keys());
-
-  for (const [name, members] of byName) {
-    if (members.length < 2) continue;
-    // Canonical name goes to the entry with the *strictly* shortest
-    // basePath (the top-level collection in the typical /segments vs
-    // /contacts/{id}/segments case). If two members tie for shortest,
-    // there is no obvious winner — rename all of them so the yaml never
-    // silently picks one arbitrary entry as canonical.
-    const sorted = [...members].sort((a, b) => a.basePath.length - b.basePath.length);
-    const shortest = sorted[0]!.basePath.length;
-    const tiedAtShortest = sorted.filter(g => g.basePath.length === shortest).length;
-    const startFromIndex = tiedAtShortest === 1 ? 1 : 0;
-
-    for (let i = startFromIndex; i < sorted.length; i++) {
-      const g = sorted[i]!;
-      const prefix = parentNounForBasePath(g.basePath);
-      const singularPrefix = prefix ? singularizeResource(prefix) : null;
-      let candidate = singularPrefix ? `${singularPrefix}_${name}` : `${name}_${i + 1}`;
-      let n = 2;
-      while (usedNames.has(candidate)) {
-        candidate = singularPrefix ? `${singularPrefix}_${name}_${n++}` : `${name}_${n++}`;
-      }
-      usedNames.add(candidate);
-      renames.set(g, candidate);
-    }
-  }
-
-  if (renames.size === 0) return groups;
-  return groups.map(g => (renames.has(g) ? { ...g, resource: renames.get(g)! } : g));
-}
-
-/**
- * ARV-134 follow-up: same rename strategy as `disambiguateResourceCollisions`,
- * but operating on the final `ApiResourceEntry[]` so CRUD-vs-implicit
- * name clashes also get resolved. Keeps the implementation parallel so
- * the behaviour stays consistent (strictly-shortest basePath keeps the
- * canonical name; ties get all-renamed; suffix-bumping on hash
- * collision).
- */
-function disambiguateEntryCollisions(entries: ApiResourceEntry[]): ApiResourceEntry[] {
-  const byName = new Map<string, ApiResourceEntry[]>();
-  for (const e of entries) {
-    const arr = byName.get(e.resource) ?? [];
-    arr.push(e);
-    byName.set(e.resource, arr);
-  }
-
-  const renames = new Map<ApiResourceEntry, string>();
-  const usedNames = new Set<string>(byName.keys());
-
-  for (const [name, members] of byName) {
-    if (members.length < 2) continue;
-    const sorted = [...members].sort((a, b) => a.basePath.length - b.basePath.length);
-    const shortest = sorted[0]!.basePath.length;
-    const tiedAtShortest = sorted.filter(e => e.basePath.length === shortest).length;
-    const startFromIndex = tiedAtShortest === 1 ? 1 : 0;
-
-    for (let i = startFromIndex; i < sorted.length; i++) {
-      const e = sorted[i]!;
-      const prefix = parentNounForBasePath(e.basePath);
-      const singularPrefix = prefix ? singularizeResource(prefix) : null;
-      let candidate = singularPrefix ? `${singularPrefix}_${name}` : `${name}_${i + 1}`;
-      let n = 2;
-      while (usedNames.has(candidate)) {
-        candidate = singularPrefix ? `${singularPrefix}_${name}_${n++}` : `${name}_${n++}`;
-      }
-      usedNames.add(candidate);
-      renames.set(e, candidate);
-    }
-  }
-
-  if (renames.size === 0) return entries;
-  return entries.map(e => (renames.has(e) ? { ...e, resource: renames.get(e)! } : e));
-}
-
-function parentNounForBasePath(basePath: string): string | null {
-  const segs = pathStripSlash(basePath).split("/").filter(Boolean);
-  // Skip the last segment (the resource itself); walk back to the nearest
-  // non-param noun. `/contacts/{contact_id}/segments` → "contacts".
-  for (let i = segs.length - 2; i >= 0; i--) {
-    if (!isParamSeg(segs[i])) return segs[i]!;
-  }
-  return null;
-}
-
-/**
- * ARV-134 (resource-builder fix #2): for an implicit list-only resource
- * (no CRUD group), look for a GET-by-id companion endpoint that gives us
- * a real idParam + itemPath. Resend's `/logs/{log_id}` and `/automations/
- * {automation_id}/runs/{run_id}` were getting `idParam: ""` because the
- * implicit-resource constructor never inspected the spec for their item
- * endpoints — `prepare-fixtures` then skipped them.
- */
-function findItemEndpointForListPath(
-  listPath: string,
-  endpoints: EndpointInfo[],
-): EndpointInfo | null {
-  const itemRe = new RegExp(`^${escapeRegex(listPath)}/\\{([^}]+)\\}/?$`);
-  for (const ep of endpoints) {
-    if (ep.method.toUpperCase() !== "GET" || ep.deprecated) continue;
-    if (itemRe.test(pathStripSlash(ep.path))) return ep;
-  }
-  return null;
-}
-
-function getCaptureField(create: EndpointInfo): string {
-  // Look at the create endpoint's success response schema for an `id`-ish
-  // field. Falls back to "id" — the universal default.
-  const success = create.responses.find(r => r.statusCode >= 200 && r.statusCode < 300);
-  const schema = success?.schema as OpenAPIV3.SchemaObject | undefined;
-  if (schema?.properties) {
-    const props = schema.properties as Record<string, OpenAPIV3.SchemaObject>;
-    for (const candidate of ["id", "uuid", "key", "code"]) {
-      if (props[candidate]) return candidate;
-    }
-  }
-  return "id";
-}
-
-/**
- * Structurally infer the list-endpoint that owns each path-parameter by
- * walking the actual URL graph in the spec. Beats name-stemming because
- *
- *  • `_id_or_slug`, `_or_name`, non-English plurals, weird casing — all
- *    transparent: we only look at segment positions, not at param names.
- *  • Returns the *exact* GET path to call, not a guessed resource name we
- *    later have to hope is wired up correctly.
- *  • Two-strategy lookup so it survives both canonical nesting
- *    (`/orgs/{org}/projects/{proj}/...` — prev seg `projects` is a list)
- *    and common SaaS-style sibling-param chains
- *    (`/projects/{org}/{proj}/...` — prev seg is itself a param;
- *    we walk back to the nearest non-param segment and search for any
- *    GET path ending with that hint).
- */
-// ARV-376: list-shaped verb suffixes. `/api/business-segment20/list` is the
-// collection listing for stem `/api/business-segment20`, even though the
-// stem itself is not a GET endpoint. Same for `/search` and `/find`.
-const LIST_VERB_SUFFIXES = new Set(["list", "search", "find"]);
-
-export function resolveOwnerListPaths(endpoints: EndpointInfo[]): Map<string, string> {
-  const getPathSet = new Set<string>();
-  const getPathsByLastSeg = new Map<string, string[]>();
-  // ARV-376: a `/list`-style endpoint indexed by its collection stem
-  // (path minus the verb suffix) and by that stem's last noun segment, so a
-  // read-by-id sibling (`/{code}`, `/byid/{id}`) can find its listing even
-  // though the bare collection path has no GET.
-  const listByStem = new Map<string, string>();
-  const listByStemLastSeg = new Map<string, string[]>();
-  const considerShortest = (map: Map<string, string>, key: string, path: string) => {
-    const cur = map.get(key);
-    if (!cur || path.length < cur.length) map.set(key, path);
-  };
-  for (const ep of endpoints) {
-    if (ep.method.toUpperCase() !== "GET" || ep.deprecated) continue;
-    const path = pathStripSlash(ep.path);
-    getPathSet.add(path);
-    const segs = path.split("/").filter(Boolean);
-    const last = segs[segs.length - 1];
-    if (last && !isParamSeg(last)) {
-      const arr = getPathsByLastSeg.get(last) ?? [];
-      arr.push(path);
-      getPathsByLastSeg.set(last, arr);
-    }
-    // Index list-verb endpoints against their collection stem. The stem key
-    // is the leading-slash path form the resolution loop below builds its
-    // prefixes in (NOT the filtered form) so the two sides compare equal.
-    if (last && LIST_VERB_SUFFIXES.has(last.toLowerCase()) && segs.length >= 2) {
-      const stemLast = segs[segs.length - 2];
-      if (stemLast && !isParamSeg(stemLast)) {
-        const lastSlash = path.lastIndexOf("/");
-        const stemPath = lastSlash > 0 ? path.slice(0, lastSlash) : "";
-        considerShortest(listByStem, stemPath, path);
-        const arr = listByStemLastSeg.get(stemLast) ?? [];
-        arr.push(path);
-        listByStemLastSeg.set(stemLast, arr);
-      }
-    }
-  }
-
-  const result = new Map<string, string>();
-  const consider = (param: string, candidate: string) => {
-    const existing = result.get(param);
-    // Prefer shorter (more canonical/top-level) list path.
-    if (!existing || candidate.length < existing.length) result.set(param, candidate);
-  };
-
-  for (const ep of endpoints) {
-    if (ep.deprecated) continue;
-    const segs = pathStripSlash(ep.path).split("/");
-    for (let i = 0; i < segs.length; i++) {
-      const seg = segs[i]!;
-      const m = /^\{([^}]+)\}$/.exec(seg);
-      if (!m) continue;
-      const param = m[1]!;
-
-      // Strategy 1 (canonical + ARV-376): walk back over the run of
-      // consecutive non-param segments before `{param}`; for each candidate
-      // prefix match either a collection GET or a `/list`-style endpoint.
-      // Longest (most specific) prefix wins. Stops at the first param
-      // segment so we never attribute a child id to a grandparent list. This
-      // tolerates read-by-id marker segments (`/byid/{id}` → owner is the
-      // `/business-segment20/list` two segments up).
-      let matched = false;
-      for (let k = i; k >= 1; k--) {
-        if (isParamSeg(segs[k - 1]!)) break; // hit a param boundary — stop
-        const prefix = segs.slice(0, k).join("/");
-        if (getPathSet.has(prefix)) { consider(param, prefix); matched = true; break; }
-        const listPath = listByStem.get(prefix);
-        if (listPath) { consider(param, listPath); matched = true; break; }
-      }
-      if (matched) continue;
-
-      // Strategy 2 (sibling-param chain): walk back to the nearest
-      // non-param segment, then look for *any* GET path that terminates
-      // with that segment (or a `/list`-style endpoint for that stem).
-      let hint: string | undefined;
-      for (let j = i - 1; j >= 0; j--) {
-        const s = segs[j]!;
-        if (!isParamSeg(s) && s !== "") {
-          hint = s;
-          break;
-        }
-      }
-      if (!hint) continue;
-      const candidates = getPathsByLastSeg.get(hint) ?? listByStemLastSeg.get(hint);
-      if (!candidates || candidates.length === 0) continue;
-      const shortest = candidates.reduce((a, b) => (a.length <= b.length ? a : b));
-      consider(param, shortest);
-    }
-  }
-
-  return result;
-}
-
-function listPathToResourceName(listPath: string): string {
-  // ARV-372/ARV-369 follow-up: strip trailing version segments (`v30`)
-  // before scanning backward, same as the CRUD-group resource-name
-  // derivation in suite-generator.ts — otherwise list-only resources on a
-  // spec shaped `/api/<resource>/v{N}` all collapse to "v30".
-  const segs = stripTrailingVersionSegments(pathStripSlash(listPath).split("/").filter(Boolean));
-  for (let i = segs.length - 1; i >= 0; i--) {
-    if (!isParamSeg(segs[i])) return segs[i]!;
-  }
-  return "resource";
-}
-
-/**
- * Body-FK fallback. Used only when a body field's name doesn't appear
- * as a path-param anywhere (so the structural resolver has nothing to
- * say). Cheap heuristic — kept narrow on purpose.
- */
-function inferFkOwnerByName(paramName: string, allResources: string[]): string | null {
-  const stem = paramName
-    .replace(/_id_or_slug$|_id_or_name$|_or_slug$|_or_name$/, "")
-    .replace(/_id$|Id$|_uuid$|_slug$/, "")
-    .toLowerCase();
-  if (!stem) return null;
-  for (const res of allResources) {
-    const r = res.toLowerCase();
-    if (r === stem || r === `${stem}s` || `${r}s` === stem || r.replace(/s$/, "") === stem) {
-      return res;
-    }
-  }
-  return null;
-}
-
-function collectPathFkDeps(
-  basePath: string,
-  idParam: string,
-  ownerListPaths: Map<string, string>,
-  resourceByListPath: Map<string, string>,
-): ResourceFkRef[] {
-  const deps: ResourceFkRef[] = [];
-  const seen = new Set<string>();
-  const pathParamRe = /\{([^}]+)\}/g;
-  let match: RegExpExecArray | null;
-  while ((match = pathParamRe.exec(basePath)) !== null) {
-    const param = match[1]!;
-    if (param === idParam) continue;
-    if (seen.has(param)) continue;
-    seen.add(param);
-    const listPath = ownerListPaths.get(param);
-    const ownerResource = listPath ? (resourceByListPath.get(listPath) ?? null) : null;
-    deps.push({ var: param, param, in: "path", ownerResource });
-  }
-  return deps;
-}
-
-function collectBodyFkDeps(
-  group: CrudGroup,
-  ownerListPaths: Map<string, string>,
-  resourceByListPath: Map<string, string>,
-  allResources: string[],
-): ResourceFkRef[] {
-  const deps: ResourceFkRef[] = [];
-  if (!group.create?.requestBodySchema) return deps;
-  const schema = group.create.requestBodySchema as OpenAPIV3.SchemaObject;
-  const props = (schema.properties ?? {}) as Record<string, OpenAPIV3.SchemaObject>;
-  const required = new Set(schema.required ?? []);
-  for (const [name] of Object.entries(props)) {
-    if (!/_id$|Id$|_uuid$/.test(name)) continue;
-    if (!required.has(name)) continue;
-    // Try structural resolution first (the body field name often matches a
-    // path-param elsewhere — `audience_id` body field, `audience_id` path
-    // param both point at /audiences/). Fall back to name-stemming.
-    let ownerResource: string | null = null;
-    const listPath = ownerListPaths.get(name);
-    if (listPath) ownerResource = resourceByListPath.get(listPath) ?? null;
-    if (!ownerResource) ownerResource = inferFkOwnerByName(name, allResources);
-    deps.push({ var: name, param: name, in: "body", ownerResource });
-  }
-  return deps;
-}
-
-export interface BuildResourcesParams {
-  endpoints: EndpointInfo[];
-  specHash: string;
-}
-
-export function buildApiResourceMap(params: BuildResourcesParams): ApiResourceMap {
-  const groups = disambiguateResourceCollisions(detectCrudGroups(params.endpoints));
-  const ownerListPaths = resolveOwnerListPaths(params.endpoints);
-
-  // ARV-134: reverse-index ownerListPaths so implicit resources can fall
-  // back to the FK param name when no direct GET-by-id companion exists.
-  const paramsByListPath = new Map<string, string[]>();
-  for (const [param, listPath] of ownerListPaths) {
-    const arr = paramsByListPath.get(listPath) ?? [];
-    arr.push(param);
-    paramsByListPath.set(listPath, arr);
-  }
-
-  // Index CRUD-group list paths by normalised path so the FK resolver can
-  // hand back the resource name a structural lookup pointed at.
-  const resourceByListPath = new Map<string, string>();
-  for (const g of groups) {
-    if (g.list) resourceByListPath.set(pathStripSlash(g.list.path), g.resource);
-  }
-
-  // Imp resources: any list path that path-FKs point at structurally but
-  // no CRUD group claims (top-level GET-only collections like
-  // `/api/0/organizations/`, nested list-only collections, etc.). Without
-  // these, every FK that depends on a non-CRUD parent ends up with
-  // `ownerResource: null` and `discover` skips them — the actual root
-  // cause of the "discover --apply is a no-op" symptom.
-  const implicitResources: ApiResourceEntry[] = [];
-  const seenImplicit = new Set<string>();
-  for (const [, listPath] of ownerListPaths) {
-    if (resourceByListPath.has(listPath)) continue;
-    if (seenImplicit.has(listPath)) continue;
-    seenImplicit.add(listPath);
-    const listEp = params.endpoints.find(
-      e =>
-        e.method.toUpperCase() === "GET" &&
-        !e.deprecated &&
-        pathStripSlash(e.path) === listPath,
-    );
-    if (!listEp) continue;
-    const name = listPathToResourceName(listPath);
-
-    // ARV-134: try to recover idParam + itemPath from a GET-by-id companion
-    // (e.g. implicit `logs` at `/logs` + `GET /logs/{log_id}` → log_id).
-    // Falls back to the reverse-indexed ownerListPaths param when no direct
-    // item endpoint exists — preferring a name that matches the resource's
-    // singular form so e.g. `attachment_id` wins over a sibling FK that
-    // happens to point at the same list path.
-    const itemEp = findItemEndpointForListPath(listPath, params.endpoints);
-    let idParam = "";
-    let itemPath = "";
-    const endpoints: ApiResourceEntry["endpoints"] = { list: epLabel(listEp) };
-    if (itemEp) {
-      const m = pathStripSlash(itemEp.path).match(/\{([^}]+)\}\/?$/);
-      if (m) {
-        idParam = m[1]!;
-        itemPath = itemEp.path;
-        endpoints.read = epLabel(itemEp);
-      }
-    }
-    if (!idParam) {
-      const candidates = paramsByListPath.get(listPath) ?? [];
-      if (candidates.length > 0) {
-        const singular = singularizeResource(name).toLowerCase();
-        const preferred = candidates.find(p => {
-          const lower = p.toLowerCase();
-          return lower === singular || lower.startsWith(`${singular}_`);
-        });
-        idParam = preferred ?? candidates[0]!;
-      }
-    }
-
-    implicitResources.push({
-      resource: name,
-      basePath: listPath,
-      itemPath,
-      idParam,
-      captureField: "id",
-      hasFullCrud: false,
-      endpoints,
-      fkDependencies: [],
-    });
-    resourceByListPath.set(listPath, name);
-  }
-
-  const resourceNames = [
-    ...groups.map(g => g.resource),
-    ...implicitResources.map(r => r.resource),
-  ];
-
-  const crudResources: ApiResourceEntry[] = groups.map(g => {
-    const captureField = g.create ? getCaptureField(g.create) : "id";
-    const requiresEtag = !!(g.update?.requiresEtag || g.delete?.requiresEtag);
-    return {
-      resource: g.resource,
-      basePath: g.basePath,
-      itemPath: g.itemPath,
-      idParam: g.idParam,
-      captureField,
-      hasFullCrud: !!(g.list && g.create && g.read),
-      endpoints: {
-        ...(g.list ? { list: epLabel(g.list) } : {}),
-        ...(g.create ? { create: epLabel(g.create) } : {}),
-        ...(g.read ? { read: epLabel(g.read) } : {}),
-        ...(g.update ? { update: epLabel(g.update) } : {}),
-        ...(g.delete ? { delete: epLabel(g.delete) } : {}),
-      },
-      ...(requiresEtag ? { requiresEtag: true } : {}),
-      fkDependencies: [
-        ...collectPathFkDeps(g.basePath, g.idParam, ownerListPaths, resourceByListPath),
-        ...collectBodyFkDeps(g, ownerListPaths, resourceByListPath, resourceNames),
-      ],
-    };
-  });
-
-  // Implicit resources also chain — `/orgs/{org}/projects/` lists projects
-  // but needs `organization_id_or_slug` set to call. Surface that so
-  // `discover` knows to fetch the parent first.
-  for (const r of implicitResources) {
-    r.fkDependencies = collectPathFkDeps(r.basePath, "", ownerListPaths, resourceByListPath);
-  }
-
-
-  // ARV-134 (follow-up): the early disambiguation pass only operated on
-  // CRUD groups, but collisions also fire CRUD-vs-implicit (`/repos/
-  // {owner}/{repo}/check-runs` is CRUD, `/repos/{owner}/{repo}/commits/
-  // {ref}/check-runs` is implicit-list-only — both end up named
-  // `check-runs`). Run the same prefix-rename here on the combined list
-  // so the final yaml never carries duplicate `resource:` lines.
-  const resources = disambiguateEntryCollisions([...crudResources, ...implicitResources]);
-
-  // ARV-376: surface a resource's OWN secondary lookup keys (e.g. the
-  // `/{code}` read-by-code param, or a `/byid/{id}` param that isn't the
-  // canonical idParam) as fillable targets. resolveOwnerListPaths already
-  // links each such param to this resource's `/list` endpoint; expose it as a
-  // self-referential fkDependency so prepare-fixtures reports a candidate
-  // (GET the list, pick a value) instead of `miss-no-list`. Runs after
-  // disambiguateEntryCollisions so it keys off the FINAL unique resource
-  // names (pre-disambig implicit names collide on `list`).
-  const byOwnListPath = new Map<string, ApiResourceEntry>();
-  for (const r of resources) {
-    const label = r.endpoints.list;
-    if (!label) continue;
-    byOwnListPath.set(pathStripSlash(label.slice(label.indexOf(" ") + 1)), r);
-  }
-  for (const [param, listPath] of ownerListPaths) {
-    const r = byOwnListPath.get(pathStripSlash(listPath));
-    if (!r || param === r.idParam) continue;
-    if ((r.fkDependencies ?? []).some(d => d.var === param)) continue;
-    r.fkDependencies.push({ var: param, param, in: "path", ownerResource: r.resource });
-  }
-
-  // Endpoints that aren't in any CRUD group — RPC-style actions, webhook
-  // accept-only routes, etc. Implicit-list endpoints stay in orphans
-  // because they're not full CRUD; they're surfaced through resources for
-  // discovery purposes only.
-  const claimedEps = new Set<string>();
-  for (const g of groups) {
-    if (g.list) claimedEps.add(epLabel(g.list));
-    if (g.create) claimedEps.add(epLabel(g.create));
-    if (g.read) claimedEps.add(epLabel(g.read));
-    if (g.update) claimedEps.add(epLabel(g.update));
-    if (g.delete) claimedEps.add(epLabel(g.delete));
-  }
-  const orphanEndpoints = params.endpoints
-    .filter(ep => !claimedEps.has(epLabel(ep)))
-    .map(epLabel);
-
-  return {
-    generatedAt: new Date().toISOString(),
-    specHash: params.specHash,
-    resourceCount: resources.length,
-    resources,
-    orphanEndpoints,
-  };
-}
-
-// ── YAML serialization (minimal, no dep on yaml lib for the workspace) ──
-
-function escape(s: string): string {
-  if (/[:#\[\]{}&*!|>'"@`,%]/.test(s) || s.includes("\n") || s === "") {
-    return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-  }
-  return s;
-}
-
-export function serializeApiResourceMap(m: ApiResourceMap): string {
-  const lines: string[] = [];
-  lines.push("# Auto-generated by zond. Do not edit by hand.");
-  lines.push("# Regenerate via: zond refresh-api <name>");
-  lines.push(`generatedAt: ${escape(m.generatedAt)}`);
-  lines.push(`specHash: ${escape(m.specHash)}`);
-  lines.push(`resourceCount: ${m.resourceCount}`);
-  if (m.resources.length === 0) {
-    lines.push("resources: []");
-  } else {
-    lines.push("resources:");
-  }
-  for (const r of m.resources) {
-    lines.push(`  - resource: ${escape(r.resource)}`);
-    lines.push(`    basePath: ${escape(r.basePath)}`);
-    lines.push(`    itemPath: ${escape(r.itemPath)}`);
-    lines.push(`    idParam: ${escape(r.idParam)}`);
-    lines.push(`    captureField: ${escape(r.captureField)}`);
-    lines.push(`    hasFullCrud: ${r.hasFullCrud}`);
-    if (r.requiresEtag) lines.push(`    requiresEtag: true`);
-    lines.push(`    endpoints:`);
-    for (const [k, v] of Object.entries(r.endpoints)) {
-      lines.push(`      ${k}: ${escape(v as string)}`);
-    }
-    if (r.fkDependencies.length === 0) {
-      lines.push(`    fkDependencies: []`);
-    } else {
-      lines.push(`    fkDependencies:`);
-      for (const d of r.fkDependencies) {
-        lines.push(`      - var: ${escape(d.var)}`);
-        lines.push(`        param: ${escape(d.param)}`);
-        lines.push(`        in: ${d.in}`);
-        lines.push(`        ownerResource: ${d.ownerResource ? escape(d.ownerResource) : "null"}`);
-      }
-    }
-    if (r.readbackDiff) {
-      lines.push(`    readback_diff:`);
-      const ig = r.readbackDiff.ignoreFields ?? [];
-      if (ig.length > 0) {
-        lines.push(`      ignore_fields:`);
-        for (const f of ig) lines.push(`        - ${escape(f)}`);
-      }
-      const map = r.readbackDiff.writeToReadMap ?? {};
-      const mapKeys = Object.keys(map);
-      if (mapKeys.length > 0) {
-        lines.push(`      write_to_read_map:`);
-        for (const k of mapKeys) lines.push(`        ${escape(k)}: ${escape(map[k]!)}`);
-      }
-    }
-    if (r.idempotency) {
-      lines.push(`    idempotency:`);
-      if (r.idempotency.header) lines.push(`      header: ${escape(r.idempotency.header)}`);
-      if (r.idempotency.scope) lines.push(`      scope: ${r.idempotency.scope}`);
-      const ig = r.idempotency.ignoreResponseFields ?? [];
-      if (ig.length > 0) {
-        lines.push(`      ignore_response_fields:`);
-        for (const f of ig) lines.push(`        - ${escape(f)}`);
-      }
-    }
-    if (r.pagination) {
-      lines.push(`    pagination:`);
-      if (r.pagination.type) lines.push(`      type: ${r.pagination.type}`);
-      if (r.pagination.cursorParam) lines.push(`      cursor_param: ${escape(r.pagination.cursorParam)}`);
-      if (r.pagination.cursorField) lines.push(`      cursor_field: ${escape(r.pagination.cursorField)}`);
-      if (r.pagination.hasMoreField) lines.push(`      has_more_field: ${escape(r.pagination.hasMoreField)}`);
-      if (r.pagination.limitParam) lines.push(`      limit_param: ${escape(r.pagination.limitParam)}`);
-      if (r.pagination.defaultLimit != null) lines.push(`      default_limit: ${r.pagination.defaultLimit}`);
-      if (r.pagination.itemsField) lines.push(`      items_field: ${escape(r.pagination.itemsField)}`);
-      if (r.pagination.pageParam) lines.push(`      page_param: ${escape(r.pagination.pageParam)}`);
-      if (r.pagination.startPage != null) lines.push(`      start_page: ${r.pagination.startPage}`);
-    }
-    if (r.lifecycle) {
-      lines.push(`    lifecycle:`);
-      lines.push(`      field: ${escape(r.lifecycle.field)}`);
-      lines.push(`      states:`);
-      for (const s of r.lifecycle.states) lines.push(`        - ${escape(s)}`);
-      lines.push(`      transitions:`);
-      for (const t of r.lifecycle.transitions) {
-        lines.push(`        - from: ${escape(t.from)}`);
-        if (t.to.length === 0) {
-          lines.push(`          to: []`);
-        } else {
-          lines.push(`          to:`);
-          for (const to of t.to) lines.push(`            - ${escape(to)}`);
-        }
-      }
-      lines.push(`      actions:`);
-      for (const [name, a] of Object.entries(r.lifecycle.actions)) {
-        lines.push(`        ${escape(name)}:`);
-        lines.push(`          endpoint: ${escape(a.endpoint)}`);
-        lines.push(`          expected_state: ${escape(a.expectedState)}`);
-      }
-    }
-  }
-  if (m.orphanEndpoints.length === 0) {
-    lines.push("orphanEndpoints: []");
-  } else {
-    lines.push("orphanEndpoints:");
-    for (const e of m.orphanEndpoints) lines.push(`  - ${escape(e)}`);
-  }
-  return lines.join("\n") + "\n";
-}