Skip to content

Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.

109 KB
Raw Blame
#include "foundation/constants.h"
/*
 * pipeline_internal.h — Internal pipeline state shared between pass files.
 *
 * NOT a public header. Only included by pipeline.c and pass_*.c files.
 * Exposes the pipeline context struct for direct field access by passes.
 */
#ifndef CBM_PIPELINE_INTERNAL_H
#define CBM_PIPELINE_INTERNAL_H

#include "pipeline/pipeline.h"
#include "pipeline/path_alias.h"
#include "graph_buffer/graph_buffer.h"
#include "store/store.h"
#include "discover/discover.h"
#include "discover/userconfig.h"
#include "discover/test_conventions.h"
#include "git/git_context.h"
#include "foundation/hash_table.h"
#include "spawn_patterns.h"
#include "service_patterns.h" /* cbm_svc_kind_t */
#include "cbm.h"
#include "lsp/php_lsp.h"
#include "lsp/go_lsp.h" /* CBMLSPDef for cbm_parallel_resolve cross-LSP inputs */
#include <stdatomic.h>
#include <string.h>

typedef struct cbm_pipeline_frozen cbm_pipeline_frozen_t;

typedef enum {
    CBM_PIPELINE_FROZEN_OK = 0,
    CBM_PIPELINE_FROZEN_INVALID,
    CBM_PIPELINE_FROZEN_CONFIG,
    CBM_PIPELINE_FROZEN_UNSUPPORTED,
    CBM_PIPELINE_FROZEN_BUSY,
    CBM_PIPELINE_FROZEN_DEST_EXISTS,
    CBM_PIPELINE_FROZEN_INPUT_CHANGED,
    CBM_PIPELINE_FROZEN_CANCELLED,
    CBM_PIPELINE_FROZEN_LIMIT,
    CBM_PIPELINE_FROZEN_OOM,
    CBM_PIPELINE_FROZEN_IO,
    CBM_PIPELINE_FROZEN_PIPELINE_ERROR
} cbm_pipeline_frozen_status_t;

/* One file of a classified pinned ledger: a path relative to source_root
 * ('/'-separated; no empty, "." or ".." segment) and the language the ledger
 * gave it. CBM_LANG_COUNT: the file has no supported language and is not
 * indexed, as discovery does not index it. */
typedef struct {
    const char *rel_path;
    CBMLanguage language;
} cbm_pipeline_frozen_file_t;

typedef struct {
    /* Explicit native absolute paths. Source root and destination parent are
     * private, caller-owned directories for the entire owner lifetime.
     * DB is outside source_root and must not exist (including sidecars).
     */
    const char *source_root;
    const char *candidate_db_path;
    const char *project; /* exact accepted project label; never silently renamed */

    cbm_userconfig_source_state_t config_state; /* ABSENT or PRESENT */
    const void *config_bytes;
    size_t config_len; /* PRESENT: strict JSON object, 1..65536 bytes */

    /* Display/semantic-input data, NOT authenticated facts. All nine string
     * members are required non-NULL and copied. head_sha is pinned H and
     * base_sha is actual pinned merge-base M, each full 40/64 hex characters.
     * Their lengths must match; copied OIDs normalize to lowercase.
     * No resolver is invoked and no path in this context is traversed.
     */
    const cbm_git_context_t *pinned_git;

    /* Existing discovery policy value, copied. Existing disabled/finite-limit
     * semantics remain; this is not a new whole-process memory/time budget.
     */
    cbm_index_resource_policy_t resource_policy;

    /* Optional external cancellation flag. Borrowed until owner free, including
     * after build returns; caller initializes it and keeps it alive. Observed
     * cancellation is latched internally even if caller later clears the flag.
     * Sampled at owner/orchestration/manifest checkpoints. Nested existing
     * consumers may see only the internal latch until the next such sample.
     */
    atomic_int *cancelled;

    /* Optional: the files to index, from a classified pinned ledger (see
     * test_impact_classify.h). With a list the build walks no directory: it
     * indexes exactly these files under these languages, and the pre-commit
     * reconciliation re-hashes exactly them, so a file added to source_root
     * after the ledger was made is never indexed and a listed file that is not
     * there is INPUT_CHANGED. NULL with 0 discovers source_root. Copied. */
    const cbm_pipeline_frozen_file_t *files;
    size_t file_count;

    /* Optional: an earlier candidate of the SAME project label (the team
     * artifact's graph, imported). The build copies it into its stage and routes
     * through the incremental closure repair; every doubt there declines to the
     * full build, so the candidate is the full build's graph either way.
     * Absolute, a regular SQLite file outside source_root; never modified.
     * NULL builds from scratch. Copied. */
    const char *base_db_path;
} cbm_pipeline_frozen_inputs_t;

/* Which route built the candidate. A base whose repair declined is FULL. */
typedef enum {
    CBM_PIPELINE_FROZEN_ROUTE_FULL = 0,
    CBM_PIPELINE_FROZEN_ROUTE_INCREMENTAL = 1,
} cbm_pipeline_frozen_route_t;

/* Clear *out first. Deep-copy/validate all input; no Git/config filesystem
 * reads, no pipeline/global changes, no directory/DB creation. Caller input
 * buffers may be destroyed after return. NULL result on any failure.
 */
cbm_pipeline_frozen_status_t cbm_pipeline_frozen_create(const cbm_pipeline_frozen_inputs_t *inputs,
                                                        cbm_pipeline_frozen_t **out);

/* Synchronous, single-use after successful start. Internally try-acquires the
 * existing global pipeline lock; BUSY leaves the owner READY and may retry.
 * Fixed FULL / one worker / no Git history / no artifact export; no existing DB
 * backup, incremental route or mode promotion. Final reconciliation compares
 * the retained baseline with freshly read tree inputs using the OWNED config
 * and Git context. OK means a sealed private candidate exists, not admission.
 * No call is allowed to overlap build except cancel. Ordinary setters/run are
 * never exposed on this owner's pipeline. See text for downstream limits.
 */
cbm_pipeline_frozen_status_t cbm_pipeline_frozen_build(cbm_pipeline_frozen_t *owner);

/* Inside a frozen build: whether the owner was given a file list, and that
 * list as discovery records (absolute path under the source root, the listed
 * language, the size on disk), sorted by relative path, files without a
 * language left out. A listed file that is not a regular file records
 * INPUT_CHANGED and returns CBM_NOT_FOUND. Free with cbm_discover_free. */
bool cbm_pipeline_frozen_has_file_list(const cbm_pipeline_t *p);
int cbm_pipeline_frozen_listed_files(cbm_pipeline_t *p, cbm_file_info_t **out, int *count);

/* Thread-safe while owner is alive; sets the internal atomic immediately.
 * No concurrent free. This does not await a sample of the external flag. */
void cbm_pipeline_frozen_cancel(cbm_pipeline_frozen_t *owner);

/* Borrowed immutable diagnostic source, only before/after (not during) build.
 * Valid until owner free. Use existing const getters for file errors, ignored
 * paths, exclusions, counts and resource violations. Never cast away const or
 * pass this to a mutating ordinary-pipeline API. No completeness getter exists.
 */
const cbm_pipeline_t *cbm_pipeline_frozen_diagnostics(const cbm_pipeline_frozen_t *owner);
/* FULL until a build produced a candidate; then the route that built it. */
cbm_pipeline_frozen_route_t cbm_pipeline_frozen_route(const cbm_pipeline_frozen_t *owner);

/* Monotone negative observations; zero is NOT a completeness certificate.
 * PARSE_GAP alone does not refuse the candidate: a file that parsed only
 * partially stays in the graph with its unparsed ranges recorded, and the
 * selection treats a change to it as a parse gap (the file is seeded whole and
 * its language's lane runs whole). Every other bit refuses publication. */
enum {
    CBM_PIPELINE_FROZEN_FILE_DIAGNOSTIC = 1,
    CBM_PIPELINE_FROZEN_DIAGNOSTIC_INCOMPLETE = 2,
    CBM_PIPELINE_FROZEN_DIAGNOSTIC_OOM = 4,
    CBM_PIPELINE_FROZEN_PARSE_GAP = 8,
    /* A file indexed without configured test roles (degraded per file). */
    CBM_PIPELINE_FROZEN_TEST_DECLARATION_GAP = 16
};

/* Clears supplied output first. Returns false for NULL owner/output or while
 * BUILDING; otherwise copies the mask. No overlap with build is permitted.
 * Evidence survives failed/invalid retries until owner free; no reset API.
 */
bool cbm_pipeline_frozen_negative_evidence(const cbm_pipeline_frozen_t *owner, unsigned *out_flags);

/* Borrowed copied path only after build returned OK; otherwise NULL. */
const char *cbm_pipeline_frozen_candidate_path(const cbm_pipeline_frozen_t *owner);

/* NULL-safe; never concurrent with build/cancel. Does not delete the caller's
 * source tree, candidate DB or destination directory. Build cleans its own
 * temporary stages; caller owns final namespace cleanup and later publication.
 */
void cbm_pipeline_frozen_free(cbm_pipeline_frozen_t *owner);

#if defined(CBM_ENABLE_TEST_SEAMS) && CBM_ENABLE_TEST_SEAMS
/* One-shot failures at the frozen recorder's allocation boundaries only. */
typedef enum {
    CBM_PIPELINE_FROZEN_DIAG_FAULT_NONE = 0,
    CBM_PIPELINE_FROZEN_DIAG_FAULT_GROW = 1,
    CBM_PIPELINE_FROZEN_DIAG_FAULT_PATH = 2,
    CBM_PIPELINE_FROZEN_DIAG_FAULT_REASON = 3,
    CBM_PIPELINE_FROZEN_DIAG_FAULT_PHASE = 4
} cbm_pipeline_frozen_diag_fault_t;

/* READY-only. Invalid input leaves the prior setting unchanged; NONE clears.
 * A fault is consumed only at its matching allocation, not by other records
 * or allocations. This simulates NULL, not physical allocator exhaustion.
 */
cbm_pipeline_frozen_status_t cbm_pipeline_frozen_set_diagnostic_fault_for_tests(
    cbm_pipeline_frozen_t *owner, cbm_pipeline_frozen_diag_fault_t fault);

/* Actual dispatch observations, emitted only when the corresponding frozen
 * orchestration branch is reached. worker_count includes the calling thread
 * for a serial dispatch (1); it is 0 for HISTORY_SKIPPED. It says nothing about
 * nested pass threads or successful completion of the dispatched work.
 */
typedef enum {
    CBM_PIPELINE_FROZEN_ROUTE_EXTRACTION_WORKERS = 0,
    CBM_PIPELINE_FROZEN_ROUTE_MANIFEST_WORKERS,
    CBM_PIPELINE_FROZEN_ROUTE_HISTORY_SKIPPED
} cbm_pipeline_frozen_route_kind_t;

typedef struct {
    cbm_pipeline_frozen_route_kind_t kind;
    unsigned worker_count;
} cbm_pipeline_frozen_route_event_t;

typedef void (*cbm_pipeline_frozen_route_observer_t)(const cbm_pipeline_frozen_route_event_t *event,
                                                     void *context);

/* READY-only, instance-local, synchronous observer. NULL clears it/context.
 * The event is borrowed only during the callback; copy it to retain it.
 * Context remains borrowed until cleared or owner free. The callback only
 * records observations: no pipeline/store/scope reentry, mutation or freeing.
 * No callback-count/order promise; repeated reconciliation may emit repeated
 * manifest events. No globals and no effect on production routing or results.
 */
cbm_pipeline_frozen_status_t cbm_pipeline_frozen_set_route_observer_for_tests(
    cbm_pipeline_frozen_t *owner, cbm_pipeline_frozen_route_observer_t observer, void *context);

/* A READY-only adapter to existing per-instance publication/rename hooks.
 * No new fault allocator or phase/callback-count contract. These hooks may
 * mutate fixture inputs/cancel or simulate rename failure. The before-publish
 * hook may also invoke cbm_pipeline_add_file_error on its supplied pipeline.
 * They cannot run a pipeline, free owner, install config/options, or
 * publish/admit a witness.
 */
cbm_pipeline_frozen_status_t cbm_pipeline_frozen_set_publish_hooks_for_tests(
    cbm_pipeline_frozen_t *owner, void (*before_publish)(cbm_pipeline_t *, const char *, void *),
    int (*rename_stage)(const char *, const char *, void *), void *context);
#endif

/* Frozen-only orchestration/manifest bridge; NULL/ordinary p are no-ops. */
bool cbm_pipeline_is_frozen(const cbm_pipeline_t *p);
int cbm_pipeline_frozen_checkpoint(cbm_pipeline_t *p);
const cbm_git_context_t *cbm_pipeline_frozen_git(const cbm_pipeline_t *p);
const cbm_userconfig_t *cbm_pipeline_frozen_config(const cbm_pipeline_t *p);
void cbm_pipeline_frozen_manifest_dispatch(cbm_pipeline_t *p);
int cbm_pipeline_build_frozen_manifest(cbm_pipeline_t *p, const cbm_file_info_t *files,
                                       int file_count, char **excluded, int excluded_count,
                                       cbm_file_hash_t **out, int *out_count);
bool cbm_pipeline_frozen_manifests_equal(cbm_pipeline_t *p, const cbm_file_hash_t *left,
                                         int left_count, const cbm_file_hash_t *right,
                                         int right_count);

/* Internal explicit-language resolution; public raw/lineage APIs stay raw. */
cbm_resolution_t cbm_registry_resolve_lang(const cbm_registry_t *r, const char *callee_name,
                                           const char *module_qn, const char **import_map_keys,
                                           const char **import_map_vals, int import_map_count,
                                           CBMLanguage lang);
/* The CALLS variant: as cbm_registry_resolve_lang, except that a bare C call
 * (no `.` / `->`) does not consider Field or Method nodes, which it can never
 * call. */
cbm_resolution_t cbm_registry_resolve_call_lang(const cbm_registry_t *r, const char *callee_name,
                                                const char *module_qn, const char **import_map_keys,
                                                const char **import_map_vals, int import_map_count,
                                                CBMLanguage lang);
/* The registry step of BOTH call resolvers once the LSP has not answered:
 * for Python, the def or class `callee_name` binds in the nearest def enclosing
 * `scope_qn` (cbm_registry_resolve_lexical, "lexical_scope"); otherwise, or
 * when there is no such local, cbm_registry_resolve_call_lang. */
cbm_resolution_t cbm_registry_resolve_call_scoped(const cbm_registry_t *r, const char *callee_name,
                                                  const char *module_qn,
                                                  const char **import_map_keys,
                                                  const char **import_map_vals,
                                                  int import_map_count, CBMLanguage lang,
                                                  const char *scope_qn);
/* Python: the bare base `base` of the class `class_qn` nested in a class body
 * binds the sibling class of that body (`<enclosing class>.<base>`) when the
 * sibling is defined earlier in the same file (Python evaluates the bases in
 * the class body). Exact lookups only; the registry-owned sibling QN, or NULL
 * to resolve the base as before. Every base-class resolver asks this first. */
const char *cbm_registry_resolve_python_class_body_base(const cbm_registry_t *r,
                                                        const cbm_gbuf_t *gb, const char *class_qn,
                                                        const char *base, CBMLanguage lang);
#ifdef CBM_ENABLE_TEST_SEAMS
void cbm_pxc_test_import_probe_fail_after(int successful_allocations);
#endif

/* ── Shared pipeline constants ─────────────────────────────────── */

/* Per-file tree-sitter parse budget, in MICROSECONDS of this thread's CPU time
 * (5 s). Passed as cbm_extract_file*()'s timeout_micros; a generous wall-clock
 * ceiling (CBM_PARSE_WALL_CEILING_FACTOR x, ~60 s) backstops a stuck parse.
 * It is a time budget, not a byte budget. */
#define CBM_EXTRACT_BUDGET 5000000

/* Route node QN buffer size (must fit __route__METHOD__/full/url/path) */
#define CBM_ROUTE_QN_SIZE 768

/* CBM_PIPELINE_ABORT_PRESERVE_DB / CBM_PIPELINE_PERSIST_FAILED moved to
 * pipeline.h — callers legitimately distinguish them (the header's contract
 * always said so). FORCE_FULL_REINDEX never escapes the orchestrator and
 * stays internal. All three are distinct from CBM_NOT_FOUND, the normal
 * "no incremental route; continue with a full index" sentinel. */
#define CBM_PIPELINE_FORCE_FULL_REINDEX (-3)

/* cbm_route_canon_path: cbm.h (route_path.c). */

/* A definition's decorator route (def->route_path, e.g. an ASP.NET [HttpGet("x")]
 * action): upsert its Route node and the definition -> Route HANDLES edge. Both
 * resolvers call it per DEFINITION at node creation (pass_parallel.c,
 * pass_definitions.c), so overloads sharing one QN -- a GET form action and its
 * POST submit -- each keep their route; the merged node properties hold only one
 * of them. Defined in pass_route_nodes.c. */
void cbm_pipeline_emit_def_route(cbm_gbuf_t *gb, int64_t func_id, const CBMDefinition *def,
                                 const char *rel);

/* A file and the directory beside it share a stem (`pkg/foo.sh` beside
 * `pkg/foo/`): the file's Module QN equals the directory's Folder QN, and the
 * graph buffer keeps only the Folder. One side yields:
 * - the Folder, spelled `proj.pkg.foo/` (cbm_stem_marks_folder_qn);
 * - but a Java/Go package directory keeps its plain QN -- it IS their module,
 *   and their imports resolve to it -- so there the file's Module yields,
 *   spelled `proj.pkg.foo#sh` (cbm_stem_marks_module_qn).
 * Symbol QNs never change. Built from the discovered files once per run,
 * read-only while extraction workers consult it. */
typedef struct {
    CBMArena arena;               /* owns the QN keys of both tables */
    CBMHashTable *module_qns;     /* Module QNs of files outside Java/Go */
    CBMHashTable *dir_module_qns; /* Module QNs of Java/Go files: their package dirs */
} cbm_stem_marks_t;

void cbm_stem_marks_init(cbm_stem_marks_t *m, const char *project, const cbm_file_info_t *files,
                         int file_count);
void cbm_stem_marks_free(cbm_stem_marks_t *m);
/* rel_dir's Folder QN, marked when it must yield, written into buf; NULL
 * when it does not fit. */
const char *cbm_stem_marks_folder_qn(const cbm_stem_marks_t *m, const char *project,
                                     const char *rel_dir, char *buf, size_t buf_size);
/* The QN a file's Module definition takes: `qn#ext` when it must yield,
 * written into buf; qn itself otherwise (and when m is NULL). */
const char *cbm_stem_marks_module_qn(const cbm_stem_marks_t *m, const char *qn,
                                     const char *rel_path, CBMLanguage lang, char *buf,
                                     size_t buf_size);

/* True when a graph node is a structural directory container (Folder/Project)
 * rather than a code node. In a directory-based-module language (Java/Go, see
 * cbm_lang_module_is_dir) a file's module QN equals its directory QN, so an
 * enclosing-scope lookup for a CLASS-LEVEL usage/call (enclosing_func_qn ==
 * module_qn) resolves to the ONE Folder/Project node shared by every file in
 * that package. Sourcing an edge there conflates all same-package files into a
 * single source node with an arbitrary file_path (#787). Source-node finders
 * must treat such a hit as a miss and fall back to the per-file File node. */
static inline bool cbm_pipeline_node_is_dir_container(const cbm_gbuf_node_t *node) {
    return node && node->label &&
           (strcmp(node->label, "Folder") == 0 || strcmp(node->label, "Project") == 0);
}

/* Time unit conversions */
#define CBM_NS_PER_SEC 1000000000LL
#define CBM_US_PER_SEC 1000000LL
#define CBM_MS_PER_SEC 1000.0
#define CBM_US_PER_SEC_F 1e6

/* ── Pipeline context (internal) ─────────────────────────────────── */

/* Per-worker manifest collection entry. */
typedef struct {
    char *pkg_name;  /* heap: "@myorg/pkg", "github.com/foo/bar" */
    char *entry_rel; /* heap: "packages/pkg/src/index" (no extension) */
} cbm_pkg_entry_t;

/* Growable array of package entries (per-worker, no thread contention). */
typedef struct {
    cbm_pkg_entry_t *items;
    int count;
    int cap;
} cbm_pkg_entries_t;

void cbm_pkg_entries_init(cbm_pkg_entries_t *e);
void cbm_pkg_entries_free(cbm_pkg_entries_t *e);

/* The env join's inputs held by the unchanged files of an incremental
 * repair (pass_envjoin.c), read from the store before the K8s pass; ids are
 * the stored rows, i.e. the repair buffer's proxies. */
typedef struct {
    int64_t node;      /* a Dockerfile Module */
    const char *path;  /* its file */
    const char *props; /* its properties (image_files, image_ignore) */
} cbm_envjoin_set_row_t;

typedef struct {
    int64_t owner; /* USAGE {ref:image} source */
    int64_t image; /* its Image */
    const char *props;
} cbm_envjoin_img_row_t;

typedef struct {
    int64_t reader; /* CONFIGURES {strategy:env_access} source */
    const char *file;
    const char *key; /* the global EnvVar's name */
} cbm_envjoin_reader_row_t;

typedef struct {
    CBMArena arena; /* owns every string and array */
    cbm_envjoin_set_row_t *sets;
    int set_count;
    cbm_envjoin_img_row_t *imgs;
    int img_count;
    cbm_envjoin_reader_row_t *readers;
    int reader_count;
} cbm_envjoin_base_t;

/* A Terraform helm_release (pass_terraform.c): the chart it DEPLOYS and its
 * values -- `values = [...]` coalesced in order, then `set` -- as JSON; NULL
 * when a part is not a literal (an interpolation, a variable). pass_k8s.c
 * renders the chart's images with them. */
typedef struct cbm_tf_release {
    int64_t src;   /* the resource.helm_release node */
    int64_t chart; /* the Chart node */
    char *values;  /* owned (cbm_free); NULL: unknown */
} cbm_tf_release_t;

/* Shared context passed to each pass function.
 * Derived from cbm_pipeline_t fields during run. */
typedef struct {
    const char *project_name; /* borrowed from pipeline */
    const char *repo_path;    /* borrowed from pipeline */
    /* An incremental run: the unchanged files whose earlier run declared
     * image builds (docker build ...), read again by the shell pass, as
     * those edges are recomputed whole. Borrowed; NULL in a full run. */
    const char *const *build_decl_files;
    int build_decl_count;
    cbm_gbuf_t *gbuf;         /* owned by pipeline */
    cbm_registry_t *registry; /* owned by pipeline */
    atomic_int *cancelled;    /* pointer to pipeline's cancelled flag */
    cbm_pipeline_t *pipeline; /* back-pointer for recording per-file skips
                               * (Stage 2 / Track B). May be NULL on paths that
                               * don't record; cbm_pipeline_add_file_error is
                               * NULL-safe. */
    int mode;                 /* cbm_index_mode_t (0=full, 1=moderate, 2=fast, 3=advanced) */

    /* Extraction result cache (sequential pipeline optimization).
     * When non-NULL, pass_definitions stores results here instead of freeing,
     * and pass_calls/usages/semantic reuse cached results instead of re-extracting.
     * Indexed by file position in the files[] array. Owned by pipeline.c. */
    CBMFileResult **result_cache;

    /* Run-owned immutable snapshot; direct borrow also works for probe contexts
     * whose pipeline back-pointer is NULL. Workers only write the fatal latch. */
    const cbm_test_declarations_t *test_declarations;
    _Atomic int test_declarations_failed;
    /* Negative-obligation witness, not a completeness certificate: at least
     * one extracted definition needs the configured-owner cross walk. */
    _Atomic int test_definition_owners_seen;
#if defined(CBM_ENABLE_TEST_SEAMS) && CBM_ENABLE_TEST_SEAMS
    unsigned test_fault_mask; /* copied from one pipeline instance, immutable */
#endif

    /* Build-tool path aliases (tsconfig/jsconfig today; webpack/vite-style
     * configs are an easy follow-on). NULL when no usable configs were found.
     * Owned by pipeline.c / pipeline_incremental.c. */
    const cbm_path_alias_collection_t *path_aliases;

    /* Directory subtrees excluded during discovery. Borrowed from pipeline.c. */
    char **excluded_dirs;
    int excluded_count;

    /* Stem collisions of the discovered files: which Module definitions take
     * `qn#ext`. Borrowed for the extraction phase; NULL elsewhere. */
    const cbm_stem_marks_t *stem_marks;

    /* An incremental repair: the env join's inputs held by the unchanged
     * files (pass_envjoin.c). Borrowed; NULL in a full run. */
    const cbm_envjoin_base_t *envjoin_base;

    /* Sequential cross-LSP registry arena. The lsp_cross pass builds its
     * shared per-language registries here; resolved_calls entries may BORROW
     * strings owned by these registries, and the later calls pass still
     * reads them — so the arena is OWNED and destroyed by
     * run_sequential_pipeline AFTER all passes, never by the lsp_cross pass
     * itself (destroying at pass end was a use-after-free in pass_calls).
     * Mirrors the parallel path, where cross_lsp_arena outlives the fused
     * resolve. */
    CBMArena seq_cross_arena;
    bool seq_cross_arena_live;
    /* Sequential lsp_cross only: the per-file module-QN strings the collected
     * defs (and through them the shared cross registries in seq_cross_arena)
     * borrow. The registries outlive the pass so pass_calls can read borrowed
     * strings -- these must too. Ownership transfers here at the end of the
     * pass; released beside the arena. Freeing them at pass end was a
     * use-after-free first observable on the real-repo corpus tier. */
    char **seq_cross_def_modules;
    int seq_cross_def_module_count;

    /* ObjectScript $$$macro table built from .inc files in the repo (NULL if
     * no ObjectScript include files were found). Owned by pipeline.c. */
    const CBMMacroTable *macro_table;

    /* ObjectScript method-return-type table built from extracted definitions
     * (NULL until pass_calls builds it). Owned by pipeline.c. */
    const CBMReturnTypeTable *return_type_table;

    /* Spill / admission control (2026-09-13). spill_mode latches on the first
     * over-budget observation in the extract gate (or on CBM_MEM_SPILL=1):
     * from then on every compacted result is parked on disk instead of held
     * in the cache, results already cached are swept out, and every later
     * consumer (registry build, def collection, resolve) loads a result only
     * for the moment it reads it. Memory then sits at the floor -- graph +
     * registries + in-flight files -- and the run pays with disk reads.
     * NULL/0 = results stay in memory as always. Owned by pipeline.c. */
    struct cbm_result_spill *spill;
    _Atomic int spill_mode;
    /* Set by the ONE owner whose every result-cache consumer goes through
     * cbm_pipeline_result_acquire()/release() and that closes the store
     * (run_parallel_pipeline). An owner that leaves it false never spills:
     * the incremental and probe routes still hand the cache array to passes
     * that index it directly, so they keep results in memory (follow-up). */
    bool spill_allowed;

    /* Doc-comment references -> MENTIONS (doc_links.h). doc_links is the
     * run's resolver state while the resolve phase runs (NULL otherwise);
     * doc_link_base holds the stored scopes of the files an incremental run
     * does not re-extract (borrowed from the route that loaded them);
     * doc_links_failed records a failed build so publication can mark it. */
    struct cbm_doclinks *doc_links;
    const struct cbm_doclink_scope *doc_link_base;
    int doc_link_base_count;
    bool doc_links_failed;

    /* The run's Terraform helm_releases (pass_terraform.c fills them, the K8s
     * pass reads and frees them right after). */
    cbm_tf_release_t *tf_releases;
    int tf_release_n;
    int tf_release_cap;
} cbm_pipeline_ctx_t;

/* Origin-aware LSP returns only success/failure. Never retain partial output
 * when its configured owner proof cannot be applied to current source. */
static inline void cbm_pipeline_test_owner_error(CBMFileResult *result) {
    if (!result || result->test_declarations_status != CBM_TEST_EXTRACT_OK) {
        return;
    }
    result->test_declarations_status = CBM_TEST_EXTRACT_UNSUPPORTED_FORM;
    result->test_declaration_index = -1;
    result->test_declaration_line = 0;
    if (!result->has_error) {
        result->test_error_only = true;
    }
    result->has_error = true;
    result->error_msg =
        cbm_arena_strdup(&result->arena, "configured test body ownership could not be verified");
    if (!result->error_msg) {
        result->test_declarations_status = CBM_TEST_EXTRACT_OOM;
    }
    cbm_test_declarations_degrade(result); /* per file, not the index */
}

static inline bool cbm_pipeline_test_result_ok(cbm_pipeline_ctx_t *ctx,
                                               const CBMFileResult *result) {
    if (result && result->test_declarations_status != CBM_TEST_EXTRACT_OK) {
        atomic_store(&ctx->test_declarations_failed, 1);
        return false;
    }
    if (result && result->has_test_definition_owners) {
        atomic_store(&ctx->test_definition_owners_seen, 1);
    }
    return true;
}

/* Mirror the extractor's consumed definition language/preset activation.
 * Registration records and the legacy native presets do not activate the
 * configured-definition adapter. NULL/default snapshots keep legacy skips. */
static inline bool cbm_pipeline_test_definitions_apply(const cbm_pipeline_ctx_t *ctx,
                                                       CBMLanguage language) {
    const cbm_test_declarations_t *snapshot = ctx ? ctx->test_declarations : NULL;
    if (!snapshot ||
        (language != CBM_LANG_C && language != CBM_LANG_CPP && language != CBM_LANG_CUDA)) {
        return false;
    }
    bool enabled = false;
    if (language == CBM_LANG_C &&
        cbm_test_declarations_preset(snapshot, CBM_TEST_PRESET_C_CBM, &enabled) && enabled) {
        return true;
    }
    int count = 0;
    const cbm_test_declaration_t *items = cbm_test_declarations_items(snapshot, &count);
    for (int i = 0; i < count; i++) {
        if (items[i].role != CBM_TEST_DECL_CASE && items[i].role != CBM_TEST_DECL_SUITE) {
            continue;
        }
        const char *name = items[i].language;
        if (name &&
            ((language == CBM_LANG_C && (strcmp(name, "c") == 0 || strcmp(name, "C") == 0)) ||
             (language == CBM_LANG_CPP &&
              (strcmp(name, "cpp") == 0 || strcmp(name, "c++") == 0 || strcmp(name, "C++") == 0)) ||
             (language == CBM_LANG_CUDA &&
              (strcmp(name, "cuda") == 0 || strcmp(name, "CUDA") == 0)))) {
            return true;
        }
    }
    return false;
}

static inline bool cbm_pipeline_test_extraction_ok(cbm_pipeline_ctx_t *ctx, CBMLanguage language,
                                                   const CBMFileResult *result) {
    if (!result && cbm_pipeline_test_definitions_apply(ctx, language)) {
        atomic_store(&ctx->test_declarations_failed, 1);
        return false;
    }
    return cbm_pipeline_test_result_ok(ctx, result);
}

#if defined(CBM_ENABLE_TEST_SEAMS) && CBM_ENABLE_TEST_SEAMS
enum {
    CBM_PIPELINE_TEST_FAULT_EXTRACT_NULL = 1u << 0,
    CBM_PIPELINE_TEST_FAULT_DEF_MODULES_NULL = 1u << 1,
    CBM_PIPELINE_TEST_FAULT_COLLECT_SPILL_NULL = 1u << 2
};
void cbm_pipeline_test_set_fault_mask(cbm_pipeline_t *p, unsigned mask);
unsigned cbm_pipeline_test_fault_mask(const cbm_pipeline_t *p);
#endif

static inline bool cbm_pipeline_test_force_extract_null(const cbm_pipeline_ctx_t *ctx,
                                                        CBMLanguage language) {
#if defined(CBM_ENABLE_TEST_SEAMS) && CBM_ENABLE_TEST_SEAMS
    return ctx && (ctx->test_fault_mask & CBM_PIPELINE_TEST_FAULT_EXTRACT_NULL) &&
           cbm_pipeline_test_definitions_apply(ctx, language);
#else
    (void)ctx;
    (void)language;
    return false;
#endif
}

static inline bool cbm_pipeline_test_force_def_modules_null(const cbm_pipeline_ctx_t *ctx) {
#if defined(CBM_ENABLE_TEST_SEAMS) && CBM_ENABLE_TEST_SEAMS
    return ctx && (ctx->test_fault_mask & CBM_PIPELINE_TEST_FAULT_DEF_MODULES_NULL) &&
           atomic_load(&ctx->test_definition_owners_seen);
#else
    (void)ctx;
    return false;
#endif
}

/* ── Result-cache access contract (spill mode) ────────────────────────
 * After extraction a slot of the result cache is either the in-memory result
 * or NULL with the result parked on disk (ctx->spill). Every consumer reads a
 * slot through this pair; a pass that indexes the array itself is blind to
 * parked results (the infra-route passes lost every __route__infra__ node
 * that way, 2026-09-13). `want` (NULL = always) sees the parked HEADER first
 * -- counts are valid, pointers are not -- and can veto the load, so a pass
 * after one rare list does not read every parked result back from disk. */
typedef bool (*cbm_result_want_fn)(const CBMFileResult *header);
CBMFileResult *cbm_pipeline_result_acquire(const cbm_pipeline_ctx_t *ctx, CBMFileResult **cache,
                                           int i, cbm_result_want_fn want, bool *loaded);
void cbm_pipeline_result_release(CBMFileResult *r, bool loaded);

/* Log the store counters, close and delete the store, drop the latch. */
void cbm_pipeline_spill_close(cbm_pipeline_ctx_t *ctx);

/* The File node of `rel` in `gbuf` (NULL when it has none): the one lookup
 * for "this file as an edge source", by the name cbm_pipeline_fqn_compute
 * gives every File node. */
const cbm_gbuf_node_t *cbm_pipeline_file_node(const cbm_gbuf_t *gbuf, const char *project,
                                              const char *rel);

/* Transcode an ObjectScript Studio Export XML file and compose every generated
 * UDL class into one cacheable result. The returned result owns all child
 * extraction arenas and is released with the ordinary cbm_free_result(). */
CBMFileResult *cbm_pipeline_extract_objectscript_export(
    const char *source, int source_len, const char *project_name, const char *rel_path,
    const CBMMacroTable *macro_table, const CBMReturnTypeTable *return_type_table);

/* Explicit per-class parse deadline for bounded extraction and ownership tests.
 * Zero disables the parse deadline; production callers use the wrapper above. */
CBMFileResult *cbm_pipeline_extract_objectscript_export_with_timeout(
    const char *source, int source_len, const char *project_name, const char *rel_path,
    const CBMMacroTable *macro_table, const CBMReturnTypeTable *return_type_table,
    int64_t timeout_micros);

/* Synchronous thread-local extraction seam for verifying timeout forwarding.
 * NULL restores cbm_extract_file_ex; tests must restore it before asserting. */
typedef CBMFileResult *(*cbm_objectscript_export_extractor_t)(const char *, int, CBMLanguage,
                                                              const char *, const char *, int64_t,
                                                              const char **, const char **,
                                                              const CBMMacroTable *,
                                                              const CBMReturnTypeTable *);
void cbm_pipeline_set_objectscript_export_extractor_for_tests(
    cbm_objectscript_export_extractor_t extractor);

/* Materialize CONFIGURES edges from one extracted file's env-access carriers.
 * Shared by sequential definition processing and the parallel cache registry. */
int cbm_pipeline_create_env_configures_for_file(cbm_pipeline_ctx_t *ctx,
                                                const CBMFileResult *result, const char *rel);

static inline int cbm_pipeline_relpath_is_excluded(const char *rel_path, char *const *excluded_dirs,
                                                   int excluded_count) {
    if (!rel_path || rel_path[0] == '\0' || !excluded_dirs || excluded_count <= 0) {
        return 0;
    }
    for (int i = 0; i < excluded_count; i++) {
        const char *excluded = excluded_dirs[i];
        if (!excluded || excluded[0] == '\0') {
            continue;
        }
        size_t n = strlen(excluded);
        if (strncmp(rel_path, excluded, n) == 0 && (rel_path[n] == '\0' || rel_path[n] == '/')) {
            return SKIP_ONE;
        }
    }
    return 0;
}

/* Diagrams (pass_diagrams.c). The DEFINES edge from a Diagram's or a
 * DiagramElement's container (the Section a diagram block sits in, the
 * Diagram of an element) to the definition's node; nothing for other
 * definitions. */
void cbm_pipeline_diagram_parent_edge(cbm_pipeline_ctx_t *ctx, const CBMDefinition *def,
                                      int64_t node_id);
/* The DIAGRAM_ARROW edges of one file's diagrams. */
void cbm_pipeline_diagram_arrows(cbm_pipeline_ctx_t *ctx, const CBMFileResult *result);

/* Get the current pipeline's package map (NULL if none). */
CBMHashTable *cbm_pipeline_get_pkgmap(void);
void cbm_pipeline_set_pkgmap(CBMHashTable *map);

/* Resolve a route handler reference (the registry's answer for route passes).
 * A class-qualified "Ns\\Class::method" reference — the extractor's form for
 * Laravel `[Class::class, 'method']` and invokable `Class::class` handlers
 * (#1146), with the class already qualified through the file's `use` imports
 * and namespace — is placed on a method QN only by what places the class file:
 * the composer.json PSR-4 class file in gbuf (cbm_pipeline_psr4_member_qn).
 * When a PSR-4 prefix covers the class, that answer is final: a covered class
 * whose file or member is absent stays unresolved, as its `use` import does
 * (#1186). Only a class no prefix covers falls back to the one candidate whose
 * directories end with the class's namespace. Never by short name alone, so a
 * vendor controller that is not in the repo gets no handler. A reference
 * without "::" resolves exactly as cbm_registry_resolve_lang does for the
 * calling file's language. */
cbm_resolution_t cbm_registry_resolve_handler(const cbm_registry_t *r, const char *handler_ref,
                                              const char *module_qn, const char **import_map_keys,
                                              const char **import_map_vals, int import_map_count,
                                              const cbm_gbuf_t *gbuf, CBMLanguage lang);

/* Where composer's PSR-4 autoloader places a PHP class member. Tri-state, so
 * "no prefix covers the class" (another strategy may answer) is never
 * confused with "a prefix covers it but places nothing" (final). */
typedef enum {
    CBM_PSR4_MEMBER_NOT_COVERED = 0, /* no psr-4 prefix covers the class */
    CBM_PSR4_MEMBER_RESOLVED,        /* *out_qn is the member's QN */
    CBM_PSR4_MEMBER_UNRESOLVED,      /* covered, but no class file holds the
                                      * class with this member: leave it
                                      * unresolved, never guess elsewhere */
} cbm_psr4_member_t;

/* Place `member` on the PHP class `class_fqn` ("Ns\\Class", NUL-terminated)
 * the way composer's PSR-4 autoloader places the class: the class file the
 * import resolver picks for `use Ns\\Class;` (#1186), the class that file
 * defines, then that class's member. *out_qn is set only on
 * CBM_PSR4_MEMBER_RESOLVED (else NULL) and is owned by gbuf. Missing
 * arguments or no package map give CBM_PSR4_MEMBER_NOT_COVERED. Read-only on
 * gbuf. */
cbm_psr4_member_t cbm_pipeline_psr4_member_qn(const cbm_gbuf_t *gbuf, const char *class_fqn,
                                              const char *member, const char **out_qn);

/* Get the current pipeline's declared-package map (NULL if none): the
 * namespace/package → File-QN map built by cbm_pipeline_namespace_map_build
 * from every indexed file's own `package`/`namespace`/`using` declaration.
 * The import passes build it to resolve namespace imports; it is published
 * here so the call passes can ask whether a package-path specifier names a
 * package the tree itself declares (#1355). Set before resolve starts, read
 * only afterwards — same single-writer contract as the pkgmap above. */
CBMHashTable *cbm_pipeline_get_nsmap(void);
void cbm_pipeline_set_nsmap(CBMHashTable *map);

/* Unified module resolver: relative → pkgmap → fqn_module fallback.
 * Handles bare specifiers via pkgmap lookup with prefix matching.
 * Caller must free() the returned string. */
char *cbm_pipeline_resolve_module(const cbm_pipeline_ctx_t *ctx, const char *source_rel,
                                  const char *module_path);

/* #1916: HTTP client-instance calls. When `call` is `<recv>.<verb>(url)` with
 * an HTTP verb suffix and a path/URL first argument, and `recv` is bound —
 * in the calling module itself, or via an ES import (named or default) — to a
 * binding the extractor marked as an `axios.create(...)` instance
 * (`http_client` node property), write the request URL to `out` (the
 * instance's literal `http_base_url` joined with a '/'-leading path, the path
 * unchanged when the base is unknown or the URL is absolute) and return true.
 * Both call resolvers (pass_calls.c, pass_parallel.c) call this before any
 * route-registration or registry fallback, so a wrapper client's `api.get`
 * is never mistaken for an Express `app.get` route registration. */
bool cbm_pipeline_http_client_call_url(const cbm_gbuf_t *gbuf, const char *project, const char *rel,
                                       const CBMFileResult *result, const char **imp_keys,
                                       const char **imp_vals, int imp_count, const CBMCall *call,
                                       char *out, size_t out_sz);

/* Finish a call edge's props: `props` is a CBM_SZ_2K buffer holding `n` bytes
 * of an unclosed JSON object. Appends the call's ,"args":[...] (and, when
 * `with_line`, its ,"line":N), then the closing brace. The one formatter
 * behind both passes' HTTP_CALLS / ASYNC_CALLS props (pass_parallel.c). */
void cbm_pipeline_close_call_props(char *props, int n, const CBMCall *call, bool with_line);

/* Go 1.22 ServeMux registrations may name a method and a host before the path
 * ("POST /v1/x", "GET api.example.com/v1/x", #2537). For a Go `Handle` /
 * `HandleFunc` call, the path inside its first argument; NULL for any other
 * language or callee (`store.Get("users/123")`), for a URL argument, and for an
 * argument that is no such pattern (a plain "/v1/x" included). The one reader
 * of that grammar behind both passes (pass_parallel.c). */
const char *cbm_pipeline_mux_route_path(const CBMCall *call, CBMLanguage lang);

/* The method of a route registration's Route: the verb its callee names
 * (`router.GET`), else the method its Go ServeMux pattern names
 * (`mux.HandleFunc("POST /v1/x", h)`, #2537), else the callee's own answer
 * (ANY or NULL). `buf` (CBM_SZ_16) holds a pattern method. Shared by both
 * passes so their Routes stay byte-identical (pass_parallel.c). */
const char *cbm_pipeline_route_reg_method(const CBMCall *call, CBMLanguage lang, char *buf,
                                          size_t buf_sz);

/* Per-file index of the names a file's imports bind onto EXTERNAL modules:
 * local name -> the binding import. Built lazily, on the first call that
 * asks, from the file's extraction imports and its IMPORTS edges; one hash
 * lookup per call after that. Zero-initialize, pass to
 * cbm_pipeline_external_import_service for every call of ONE file, then
 * release with cbm_pipeline_external_import_index_free. */
typedef struct {
    CBMHashTable *by_local;
    bool built;
} cbm_external_import_index_t;

void cbm_pipeline_external_import_index_free(cbm_external_import_index_t *index);

/* A call no project symbol resolved, whose callee is bound by an import of an
 * EXTERNAL library: `send(...)` under `from paho.mqtt import publish as send`,
 * `navigate(...)` under `import { get as navigate } from 'axios'`. Spells the
 * callee as its import makes it (paho.mqtt.publish, axios.get), runs the
 * service patterns on that name, and returns CBM_SVC_HTTP or CBM_SVC_ASYNC
 * (writing the spelled name to `spelled`) for an HTTP request -- the spelled
 * name ends in a request verb, so urllib.parse.urljoin is none -- with a URL
 * argument, or a messaging call with a URL or topic argument; CBM_SVC_NONE
 * otherwise.
 *
 * Only adds what the resolvers had no answer for: a project import (one an
 * IMPORTS edge materialized, or a relative path), a name bound by two
 * different imports, a Python callee rebound as a parameter, and every call
 * the route-suffix and global-fetch fallbacks already own are left alone.
 * Python and JS/TS today; a language plugs in with its binding rule in
 * pass_calls.c. Both call resolvers call this, so they cannot diverge. */
cbm_svc_kind_t cbm_pipeline_external_import_service(cbm_external_import_index_t *index,
                                                    const cbm_gbuf_t *gbuf, const char *project,
                                                    const char *rel, CBMLanguage lang,
                                                    const CBMImportArray *imports,
                                                    const CBMCall *call, char *spelled,
                                                    size_t spelled_sz);

/* A spawn site (pass_spawns.c): the API the call names and the program it
 * starts (CBM_SPAWN_DYNAMIC when not a literal). */
typedef struct {
    const char *api;
    char program[CBM_SPAWN_PROGRAM_MAX];
} cbm_pipeline_spawn_t;

/* True when `call` starts another program (spawn_patterns.h) and `res`, the
 * registry answer after the cross-language veto, does not make it a call into
 * the project's own code. `imports` are the file's extracted imports, not the
 * resolver's import map: that one holds only imports that resolved to project
 * nodes, and subprocess or os/exec never do. Both call resolvers ask at the
 * same point and, on true, emit cbm_pipeline_emit_spawn INSTEAD of a CALLS
 * edge. */
bool cbm_pipeline_spawn_site(const cbm_gbuf_t *gbuf, CBMLanguage lang, const CBMCall *call,
                             const CBMImportArray *imports, const cbm_resolution_t *res,
                             cbm_pipeline_spawn_t *out);

/* The Process node of the spawned program (QN __process__<program>, one per
 * program) and the SPAWNS edge from `source` to it. */
void cbm_pipeline_emit_spawn(cbm_gbuf_t *gbuf, const cbm_gbuf_node_t *source, const CBMCall *call,
                             const cbm_pipeline_spawn_t *spawn);

/* Resolve an import to its in-graph target node, or NULL if unresolvable.
 *
 * Resolution order (first hit wins):
 *   1. Module-path resolution (relative / pkgmap / fqn_module) → existing node.
 *      This preserves the behavior for Python/TS/Go whose module path maps
 *      directly to a sibling Module/File QN.
 *   2. namespace_map[module_path-prefix] → File node QN (Java/Kotlin/C#/PHP
 *      `using`/`import` of a NAMESPACE that the path-based QN cannot express).
 *   3. Symbol-name fallback: the import's last path segment matched against an
 *      in-graph definition node of the same simple name in a different file
 *      (Rust `use crate::util::helper`, Java `import com.example.Util`, ...).
 *
 * `namespace_map` may be NULL (skips step 2).  `source_file_qn` is the importing
 * file's __file__ QN, used to avoid self-imports in step 3. */
const cbm_gbuf_node_t *cbm_pipeline_resolve_import_node(const cbm_pipeline_ctx_t *ctx,
                                                        const char *source_rel,
                                                        const char *source_file_qn,
                                                        const CBMImport *imp,
                                                        CBMHashTable *namespace_map);

/* PHP binding arrays borrow current result and graph strings. Free before
 * releasing/reloading the result; never cache this state across files. */
typedef CBMPHPImportBindings cbm_php_vendor_names_t;
void cbm_pipeline_php_vendor_names_build(const cbm_gbuf_t *gbuf, const char *project_name,
                                         const char *rel, const CBMFileResult *result,
                                         cbm_php_vendor_names_t *out);
void cbm_pipeline_php_vendor_names_free(cbm_php_vendor_names_t *value);
bool cbm_pipeline_php_vendor_bound(const cbm_php_vendor_names_t *value, const char *name);
bool cbm_pipeline_php_vendor_call(const cbm_php_vendor_names_t *value, const CBMFileResult *result,
                                  const CBMCall *call);
bool cbm_pipeline_php_vendor_usage(const cbm_php_vendor_names_t *value, const CBMFileResult *result,
                                   const CBMUsage *usage);
int cbm_pipeline_php_create_import_edges(cbm_pipeline_ctx_t *ctx, const CBMFileResult *result,
                                         const char *rel, const char *file_qn,
                                         const cbm_gbuf_node_t *file, CBMHashTable *namespace_map);

/* Build a namespace → File-node-QN map from a set of extraction results.
 * Each result that declared a namespace/package contributes one entry keyed by
 * the namespace string (e.g. "App.Utils", "com.example").  Returns NULL when no
 * results declared a namespace.  Caller frees via cbm_pipeline_namespace_map_free. */
CBMHashTable *cbm_pipeline_namespace_map_build(const char *project_name,
                                               CBMFileResult *const *results,
                                               const char *const *rels, int count);
/* The same map built from the namespace names directly. The parallel pass needs
 * this: results it has spilled are NULL in its cache, and a file missing from
 * the map does not fail to resolve -- it resolves through the looser fallback,
 * so an incomplete map CHANGES the graph instead of shrinking it. */
CBMHashTable *cbm_pipeline_namespace_map_build_names(const char *project_name,
                                                     const char *const *namespaces,
                                                     const char *const *rels, int count);
void cbm_pipeline_namespace_map_free(CBMHashTable *map);

/* Parse a manifest file and collect pkg entries. Returns true if basename matched. */
bool cbm_pkgmap_try_parse(const char *basename, const char *rel_path, const char *source,
                          int source_len, cbm_pkg_entries_t *entries);

/* Merge per-worker entries into a hash table. Returns NULL if no entries. */
CBMHashTable *cbm_pkgmap_build(cbm_pkg_entries_t *worker_entries, int worker_count,
                               const char *project_name);

/* Build pkgmap by reading manifest files from the files array (sequential path). */
int cbm_pkgmap_scan_repo(const char *repo_path, cbm_pkg_entries_t *entries, char **excluded_dirs,
                         int excluded_count);
CBMHashTable *cbm_pkgmap_build_from_repo(const char *repo_path, const cbm_file_info_t *files,
                                         int file_count, const char *project_name,
                                         char **excluded_dirs, int excluded_count);
CBMHashTable *cbm_pkgmap_build_from_files(const cbm_file_info_t *files, int file_count,
                                          const char *project_name);

/* Free pkgmap and all owned strings. */
void cbm_pkgmap_free(CBMHashTable *pkgmap);

/* Check cancellation. Returns non-zero if cancelled. */
static inline int cbm_pipeline_check_cancel(const cbm_pipeline_ctx_t *ctx) {
    return atomic_load(ctx->cancelled) ? CBM_NOT_FOUND : 0;
}

/* ── Testable helpers ────────────────────────────────────────────── */

/* #1934: whether the import resolver's name-guess fallbacks — Strategy 1b
 * (sibling file; its label filter admits symbols) and Strategy 3 (symbol
 * name) — may run for imports from this language. False for Go: an import
 * path names a package, never a symbol, so a Strategy-1 miss means the import
 * is external and the correct result is no edge. Pure; exercised through
 * ei_go_import_never_binds_symbol. */
bool cbm_import_symbol_fallback_allowed(CBMLanguage lang);

/* #2127: true when the module segments preceding `name` in a Python import
 * path (`unittest.mock.patch` -> unittest, mock) occur, in order, among the
 * enclosing segments of `hit_qn`. Leading relative dots and ` as alias` are
 * ignored; a path with no module chain before `name` always matches. Gates
 * the import resolver's symbol-name fallback for Python. */
bool cbm_python_import_path_matches_qn(const char *module_path, const char *name,
                                       const char *hit_qn);

/* #2127: true when the callee's root identifier is bound by the file's Python
 * imports and every such binding is EXTERNAL (no IMPORTS edge from `rel_path`
 * in `gbuf` carries its local name; NULL gbuf = none) with a module chain that
 * contradicts `resolved_qn`. Feeds cbm_suppress_weak_import_bound_call at both
 * resolver call sites. */
bool cbm_python_import_binding_contradicts(const CBMImportArray *imports, const char *callee_name,
                                           const char *resolved_qn, const cbm_gbuf_t *gbuf,
                                           const char *project_name, const char *rel_path);

/* Base-class twin: true when a Python base spelling (`unittest.TestCase`,
 * `TestCase` under `from unittest import TestCase`, `ut.TestCase` under
 * `import unittest as ut`) is bound by an EXTERNAL import whose chain
 * contradicts `base_qn` -- the INHERITS / embedded-type resolution must then
 * leave the base unresolved. False for every other language. Shared by
 * pass_semantic.c, pass_parallel.c and pass_lsp_cross.c. */
bool cbm_python_external_base_contradicts(CBMLanguage lang, const CBMImportArray *imports,
                                          const char *base_spelling, const char *base_qn,
                                          const cbm_gbuf_t *gbuf, const char *project_name,
                                          const char *rel_path);

/* Check if a file path is worth tracking for git history analysis. */
bool cbm_is_trackable_file(const char *path);

/* Check if a file path looks like a test file (language-agnostic). */
bool cbm_is_test_path(const char *path);

/* Check if a function name looks like a test function (language-agnostic). */
bool cbm_is_test_func_name(const char *name);

/* Coupling result from computeChangeCoupling */
typedef struct {
    char file_a[CBM_SZ_512];
    char file_b[CBM_SZ_512];
    int co_change_count;
    double coupling_score;
    /* Unix epoch of the most recent commit that touched both files together.
     * 0 when no timestamp was available (e.g. older callers / popen path
     * without %ct). */
    long long last_co_change;
} cbm_change_coupling_t;

/* Commit data for coupling analysis */
typedef struct {
    char **files;
    int count;
    /* Unix epoch of the commit. 0 means unknown — coupling computation
     * still works but last_co_change on the resulting edge will be 0. */
    long long timestamp;
} cbm_commit_files_t;

/* Per-file temporal metadata. Populated alongside change-coupling so File
 * nodes can carry change_count and last_modified for hotspot / risk
 * analysis queries. */
typedef struct {
    char file_path[CBM_SZ_512];
    int change_count;
    long long last_modified; /* unix epoch of most recent commit */
} cbm_file_temporal_t;

/* Compute change coupling from commit history.
 * Returns number of couplings written to out (up to max_out).
 * Caller owns out[]. */
int cbm_compute_change_coupling(const cbm_commit_files_t *commits, int commit_count,
                                cbm_change_coupling_t *out, int max_out);

/* Go-style implicit interface satisfaction on graph buffer.
 * Finds Interface nodes, matches method sets against Class nodes,
 * creates IMPLEMENTS + OVERRIDE edges. Returns edge count created. */
int cbm_pipeline_implements_go(cbm_pipeline_ctx_t *ctx);

/* Edge type for an explicit base-class relation, keyed off the resolved
 * TARGET node's label: Interface → IMPLEMENTS, anything else → INHERITS.
 * The single decision point for BOTH the sequential semantic pass and the
 * parallel per-file resolve — the two venues must never diverge. */
const char *cbm_semantic_base_edge_type(const cbm_gbuf_node_t *base_node);

/* Explicit-language override detection on the full graph (serial tail).
 * For every IMPLEMENTS/INHERITS edge whose source is a non-Go class, matches
 * the class's DEFINES_METHOD children by name against the base's and creates
 * Method→Method OVERRIDE edges (Java @Override, TS/C#/Kotlin override, PHP
 * redefinition). Go is excluded: implicit satisfaction already covers it.
 * Returns edge count created. */
int cbm_pipeline_override_explicit(cbm_pipeline_ctx_t *ctx);

/* ── Git diff helpers (pass_gitdiff.c) ───────────────────────────── */

typedef struct {
    char status[CBM_SZ_4]; /* M/A/D/R */ /* "M", "A", "D", "R" */
    char path[CBM_SZ_512];
    char old_path[CBM_SZ_512]; /* non-empty only for renames */
} cbm_changed_file_t;

/* cbm_changed_hunk_t + cbm_parse_hunks moved to pipeline.h (public — consumed
 * by src/mcp/mcp.c's detect_changes for line-scoped seed detection). Visible
 * here via the `#include "pipeline/pipeline.h"` above. */

/* Parse git diff --name-status output. Returns count written to out. */
int cbm_parse_name_status(const char *output, cbm_changed_file_t *out, int max_out);

/* Parse "start,count" or "start" → (start, count). */
void cbm_parse_range(const char *s, int *out_start, int *out_count);

/* ── Config helpers (pass_configures.c) ──────────────────────────── */

/* Check if a string looks like an environment variable name
 * (uppercase + underscore + digits, at least 2 chars with uppercase). */
bool cbm_is_env_var_name(const char *s);

/* Normalize a config key: split camelCase/snake/dots, lowercase.
 * Writes normalized form to norm_out (underscore-joined).
 * Returns token count. tokens_out[] receives borrowed pointers into norm_out. */
int cbm_normalize_config_key(const char *key, char *norm_out, size_t norm_sz);

/* Check if a file path has a config file extension (.toml, .yaml, .env, etc.) */
bool cbm_has_config_extension(const char *path);

/* ── Enrichment helpers (pass_enrichment.c) ──────────────────────── */

/* Split camelCase string on lowercase→uppercase transitions.
 * Writes substrings to out[]. Returns count. Caller must free each out[i]. */
int cbm_split_camel_case(const char *s, char **out, int max_out);

/* Tokenize a decorator into lowercase words, filtering stopwords.
 * E.g. "@login_required" → ["login", "required"].
 * Writes words to out[]. Returns count. Caller must free each out[i]. */
int cbm_tokenize_decorator(const char *dec, char **out, int max_out);

/* ── Compile commands helpers (pass_compile_commands.c) ──────────── */

typedef struct {
    char **include_paths;
    int include_count;
    char **defines;
    int define_count;
    char standard[CBM_SZ_32];
} cbm_compile_flags_t;

/* Split a shell command string into arguments (handles quoting).
 * Writes args to out[]. Returns count. Caller must free each out[i]. */
int cbm_split_command(const char *cmd, char **out, int max_out);

/* Extract -I, -isystem, -D, -std= flags from compiler arguments.
 * Caller must free result with cbm_compile_flags_free(). */
cbm_compile_flags_t *cbm_extract_flags(const char **args, int argc, const char *directory);

/* Free a compile_flags_t allocated by cbm_extract_flags(). */
void cbm_compile_flags_free(cbm_compile_flags_t *f);

/* Parse compile_commands.json content. Returns map as parallel arrays.
 * out_paths[i] is the relative file path, out_flags[i] is its flags.
 * Returns count. Caller must free out_paths[i] and cbm_compile_flags_free(out_flags[i]). */
int cbm_parse_compile_commands(const char *json_data, const char *repo_path, char ***out_paths,
                               cbm_compile_flags_t ***out_flags);

/* ── Infrascan helpers (pass_infrascan.c) ─────────────────────────── */

/* File identification helpers */
bool cbm_is_kustomize_file(const char *name);
bool cbm_is_k8s_manifest(const char *name, const char *content);
/* A Helm values file name: values.yaml / .yml, values-<x>.yaml / .yml
 * (pass_k8s.c; beside Chart.yaml it CONFIGURES the chart). */
bool cbm_helm_values_name(const char *base);
/* Is `dir` (repository relative) a werf chart: a `.helm` directory without a
 * Chart.yaml whose parent holds werf.yaml (pass_k8s.c)? */
bool cbm_werf_helm_dir(const char *repo_path, const char *dir);

/* Secret detection */
bool cbm_is_secret_binding(const char *key, const char *value);
bool cbm_is_secret_value(const char *value);

/* Helm Chart.yaml parse result: chart name + its dependencies (#338). */
enum { CBM_HELM_NAME_MAX = 128, CBM_HELM_REPO_MAX = 512 };
typedef struct {
    char name[CBM_HELM_NAME_MAX];
    char repository[CBM_HELM_REPO_MAX]; /* "" when the entry names none */
} cbm_helm_dep_t;
typedef struct {
    char chart_name[CBM_HELM_NAME_MAX];
    cbm_helm_dep_t *deps; /* heap-owned; release with cbm_helm_chart_free */
    int dep_count;
    int dep_cap;
} cbm_helm_chart_t;

/* Parse a Helm Chart.yaml: top-level `name:` and every `dependencies:` entry's
 * name and repository. Returns 0 if parsed (name or deps found), -1 otherwise;
 * either way the caller releases `out` with cbm_helm_chart_free. */
int cbm_parse_helm_chart(const char *source, cbm_helm_chart_t *out);
void cbm_helm_chart_free(cbm_helm_chart_t *hc);

/* Build an infrastructure QN. Caller must free the returned string. */
char *cbm_infra_qn(const char *project_name, const char *rel_path, const char *infra_type,
                   const char *service_name);

/* ── Parallel pipeline prototypes (pass_parallel.c) ─────────────── */

/* Phase 3A: Parallel extract + create definition nodes.
 * Each worker creates nodes in a per-worker gbuf, then merges into ctx->gbuf.
 * Caches CBMFileResult* in result_cache[file_idx] for reuse in Phase 3B/4.
 * shared_ids provides globally unique node/edge IDs across workers. */

/* Source-retention tuning for cbm_parallel_extract_ex. Zero-valued byte caps
 * mean "use the derived default" (RAM-fraction total, clamped to an absolute
 * ceiling; modest per-file cap); CBM_RETAIN_TOTAL_MB / CBM_RETAIN_PER_FILE_MB
 * override those. retain_sources_set=false keeps the default retain policy. */
typedef struct {
    bool retain_sources;
    bool retain_sources_set; /* false keeps the default retain_sources policy */
    size_t retain_total_budget_bytes;
    size_t retain_per_file_max_bytes;
} cbm_parallel_extract_opts_t;

int cbm_parallel_extract_ex(cbm_pipeline_ctx_t *ctx, const cbm_file_info_t *files, int file_count,
                            CBMFileResult **result_cache, _Atomic int64_t *shared_ids,
                            int worker_count, const cbm_parallel_extract_opts_t *opts);
int cbm_parallel_extract(cbm_pipeline_ctx_t *ctx, const cbm_file_info_t *files, int file_count,
                         CBMFileResult **result_cache, _Atomic int64_t *shared_ids,
                         int worker_count);

/* Sync the main buffer's id counter after a parallel extract or resolve.
 * Merged worker nodes keep their shared ids, and merged edges take fresh ids
 * from the main counter after the highest of them, so the main counter can
 * end above the shared one. */
void cbm_pipeline_sync_next_id(cbm_gbuf_t *gb, _Atomic int64_t *shared_ids);
/* Test seam: runs on the syncing thread right before each such sync. */
void cbm_pipeline_set_id_sync_hook_for_tests(void (*hook)(cbm_gbuf_t *, void *), void *ctx);

/* Phase 3B: Serial registry build from cached extraction results.
 * Creates DEFINES, DEFINES_METHOD, and IMPORTS edges in ctx->gbuf.
 * Registers callable symbols (Function/Method/Class) in ctx->registry. */
int cbm_build_registry_from_cache(cbm_pipeline_ctx_t *ctx, const cbm_file_info_t *files,
                                  int file_count, CBMFileResult **result_cache);

/* Phase 4: Parallel call/usage/semantic resolution.
 * Each worker resolves calls, usages, throws, rw, inherits, decorates,
 * and implements edges into per-worker edge bufs, then merges.
 * Runs Go-style implicit IMPLEMENTS as serial post-step. */
/* Opaque module-def index — defined in pass_lsp_cross.c. Forward-declared
 * here so we can include it in cbm_parallel_resolve's signature without
 * pulling the pass header into every consumer of pipeline_internal.h. */
struct CBMModuleDefIndex;

/* cbm_parallel_resolve's cross_registries param is typed `void*` to avoid
 * pulling lsp/go_lsp.h into every TU that includes pipeline_internal.h.
 * Callers cast a CBMCrossLspRegistries* (defined in pass_lsp_cross.h). */

int cbm_parallel_resolve(cbm_pipeline_ctx_t *ctx, const cbm_file_info_t *files, int file_count,
                         CBMFileResult **result_cache, _Atomic int64_t *shared_ids,
                         int worker_count,
                         /* Cross-file LSP inputs — pre-built once by the caller and
                          * shared read-only across workers (typed non-const to match
                          * the existing cbm_run_X_lsp_cross signatures the resolve
                          * worker forwards them to). Pass NULL/0/NULL to skip. */
                         CBMLSPDef *all_defs, int def_count, char *const *def_modules,
                         /* Optional inverted index module_qn → defs[] — fallback
                          * path when there's no pre-built registry for this lang. */
                         struct CBMModuleDefIndex *module_def_index,
                         /* Optional Tier 2 full: pre-built per-language registries.
                          * For each language with a non-NULL entry, workers use the
                          * cbm_run_X_lsp_cross_with_registry fast path (skip per-
                          * file registry build entirely). Falls back to the filter
                          * + per-file build path when entry is NULL or struct is NULL.
                          * Typed as void* here to dodge the typedef/tag ordering
                          * problem — pass_parallel.c casts back to CBMCrossLspRegistries*. */
                         void *cross_registries);

/* Post-merge: create Route nodes for HTTP_CALLS/ASYNC_CALLS edges that
 * have url_path in properties but point to library functions instead of routes.
 * Re-targets these edges to Route nodes for cross-service traversal. */
void cbm_pipeline_create_route_nodes(cbm_gbuf_t *gb);

/* ── Pass function prototypes ────────────────────────────────────── */

int cbm_pipeline_pass_definitions(cbm_pipeline_ctx_t *ctx, const cbm_file_info_t *files,
                                  int file_count);

int cbm_pipeline_pass_k8s(cbm_pipeline_ctx_t *ctx, const cbm_file_info_t *files, int file_count);

int cbm_pipeline_pass_calls(cbm_pipeline_ctx_t *ctx, const cbm_file_info_t *files, int file_count);

/* Cross-file LSP type-aware call resolution pass. Augments per-file
 * resolved_calls with cross-file resolutions before call edges are emitted.
 * Implementation: src/pipeline/pass_lsp_cross.c. */
int cbm_pipeline_pass_lsp_cross(cbm_pipeline_ctx_t *ctx, const cbm_file_info_t *files,
                                int file_count, CBMFileResult **cache);

/* Sub-passes called from pass_calls: pattern-based edge extraction */
void cbm_pipeline_pass_fastapi_depends(cbm_pipeline_ctx_t *ctx, const cbm_file_info_t *files,
                                       int file_count);

int cbm_pipeline_pass_usages(cbm_pipeline_ctx_t *ctx, const cbm_file_info_t *files, int file_count);

int cbm_pipeline_pass_semantic(cbm_pipeline_ctx_t *ctx, const cbm_file_info_t *files,
                               int file_count);

int cbm_pipeline_pass_tests(cbm_pipeline_ctx_t *ctx, const cbm_file_info_t *files, int file_count);

int cbm_pipeline_pass_githistory(cbm_pipeline_ctx_t *ctx);

/* Pre-computed git history result for fused post-pass parallelism. */
typedef struct {
    cbm_change_coupling_t *couplings;
    int count;
    int commit_count;
    /* Per-file temporal data (change_count + last_modified) for File nodes.
     * NULL when the history pass had no commits to analyse. */
    cbm_file_temporal_t *file_temporal;
    int file_temporal_count;
} cbm_githistory_result_t;

/* Compute change couplings without touching the graph buffer.
 * Can run on a separate thread while other passes use the gbuf. */
int cbm_pipeline_githistory_compute(const char *repo_path, cbm_githistory_result_t *result);

/* Apply pre-computed couplings to the graph buffer (main thread only). */
int cbm_pipeline_githistory_apply(cbm_pipeline_ctx_t *ctx, const cbm_githistory_result_t *result);

/* Pre-dump pass: decorator tags enrichment (operates on gbuf). */
int cbm_pipeline_pass_decorator_tags(cbm_gbuf_t *gbuf, const char *project);

/* Pre-dump pass: config ↔ code linking. */
int cbm_pipeline_pass_configlink(cbm_pipeline_ctx_t *ctx);

/* Go Kubernetes operators (pass_operator.c): controller-runtime controllers
 * HANDLES the kinds they reconcile, CRDs -> their Go types, //go:embed files.
 * Runs after USAGE resolution. */
int cbm_pipeline_pass_operator(cbm_pipeline_ctx_t *ctx);

/* Shell scripts, Make recipes and the commands CI runs (pass_shell.c): a
 * command that puts manifests, kustomizations or charts on a cluster DEPLOYS
 * them; one that starts a program by a path, or a script of the repository,
 * SPAWNS it. Run at the end of the K8s pass, over the same files. */
void cbm_pipeline_pass_shell(cbm_pipeline_ctx_t *ctx, const cbm_file_info_t *files, int file_count);

/* One command line a CI configuration runs (pass_ci.c). */
typedef struct {
    const char *ci;         /* "github-actions" | "prow" */
    const char *job;        /* the job; NULL: none (a composite action's step) */
    const char *text;       /* shell text; CBM_SZ_16 zero bytes past len */
    size_t len;             /* bytes of text */
    int row;                /* 0-based source row of the text's first line */
    const char *wd;         /* start directory, repo-relative ("" = root); NULL: unknown */
    const char *action_dir; /* a composite action's directory; NULL: none */
    const char **env;       /* name, value pairs (a value NULL: unknown) */
    int nenv;               /* pairs in env */
    bool exec;              /* an argv exec'd without a shell, quoted into text */
} cbm_ci_cmd_t;

typedef void (*cbm_ci_cmd_fn)(const cbm_ci_cmd_t *cmd, void *ud);

/* `rel` is a CI configuration by its path: a GitHub workflow
 * (.github/workflows/<name>.yml|yaml) or a composite action (action.yml|yaml). */
bool cbm_ci_path(const char *rel);

/* Hand each command line the CI configuration `rel` (YAML text src) runs to
 * fn: GitHub Actions run: steps for a workflow or composite action, else
 * Prow job containers. Strings live in arena `a`. */
void cbm_ci_commands(CBMArena *a, const char *rel, const char *src, size_t len, cbm_ci_cmd_fn fn,
                     void *ud);

/* An image a build configuration builds from a Dockerfile (pass_ci.c). */
typedef struct {
    const char *via;        /* "skaffold" / "compose" */
    const char *image;      /* the reference, variables expanded */
    const char *dockerfile; /* repository path */
    const char *build_args; /* compose build.args as a JSON object; NULL: none */
    int line;
} cbm_build_site_t;
typedef void (*cbm_build_site_fn)(const cbm_build_site_t *site, void *ud);

/* A compose service (pass_ci.c): its image (a reference, variables
 * expanded; NULL: none or unknown), the Dockerfile its build names
 * (repository path; NULL: no build, or unknown), the service names its
 * depends_on and links list, and the names of the environment variables its
 * environment sets (map keys / list items' names -- never a value), with
 * their 1-based lines and the service name each value addresses (a bare
 * name, `name:port`, a URL's host; NULL: none -- cbm_env_address).
 * image_default_of: the variables whose inline default (${X:-d}) named the
 * image; image_override_of: those whose default the project's .env replaced
 * (JSON arrays, NULL: none), and default_image the image those defaults
 * name. */
typedef struct {
    const char *name;
    const char *image;
    const char *image_default_of;
    const char *image_override_of;
    const char *default_image;
    const char *dockerfile;
    const char **deps;
    int ndeps;
    const char **env;
    const int *env_lines;
    const char **env_hosts;
    int nenv;
    int line;
    int end_line;
} cbm_compose_service_t;
typedef void (*cbm_compose_service_fn)(const cbm_compose_service_t *svc, void *ud);

/* Hand fn each service of compose file `rel` (YAML text src; `dotenv` the
 * project's .env text or NULL). Nothing for a file that is no compose file. */
void cbm_compose_services(CBMArena *a, const char *rel, const char *src, size_t len,
                          const char *dotenv, cbm_compose_service_fn fn, void *ud);

/* Whether `rel` names a build configuration: skaffold*.yaml|yml,
 * [docker-]compose[.x].yaml|yml. */
bool cbm_build_path(const char *rel);

/* Hand fn each image build configuration `rel` (YAML text src) declares:
 * skaffold build.artifacts (top level and profiles; the docker builder),
 * compose services with build and image. `dotenv` (may be NULL): the text of
 * the compose project's .env, whose variables compose interpolates. */
void cbm_build_sites(CBMArena *a, const char *rel, const char *src, size_t len, const char *dotenv,
                     cbm_build_site_fn fn, void *ud);

/* Terraform / OpenTofu / Terragrunt (pass_terraform.c): references, module
 * calls, tfvars, Terragrunt units; a helm_release DEPLOYS its chart. Run at
 * the end of the K8s pass, over the same files. */
void cbm_pipeline_pass_terraform(cbm_pipeline_ctx_t *ctx, const cbm_file_info_t *files,
                                 int file_count);

/* Kubernetes objects Terraform declares (pass_terraform.c): a
 * kubernetes_<type> resource with a literal name is a Resource of the K8s
 * identity scheme, ecosystem terraform. Run by the K8s pass before its joins. */
void cbm_pipeline_tf_k8s_objects(cbm_pipeline_ctx_t *ctx, const cbm_file_info_t *files,
                                 int file_count);

/* A Resource's properties from its identity QN (pass_k8s.c,
 * k8s_resource_props); `ecosystem` NULL for a manifest's. Caller frees. */
char *cbm_k8s_resource_props(const char *qn, const char *effective_ns, const char *version,
                             const char *labels, const char *ecosystem);

/* Ansible (pass_ansible.c): a playbook or task file IMPORTS the playbooks,
 * task files and roles its directives name; its tasks and handlers are
 * Functions, a notify CALLS the handlers it names, a kube / k8s task
 * DEPLOYS the template it applies. Run at the end of the K8s pass, over the
 * same files. */
void cbm_pipeline_pass_ansible(cbm_pipeline_ctx_t *ctx, const cbm_file_info_t *files,
                               int file_count);

/* Does a YAML text's first content line start a sequence item (pass_ansible.c)?
 * The incremental planner's test for Ansible content. */
bool cbm_ansible_is_sequence(const char *src);

/* `v` (a path; "./" and "../" allowed) from repository directory `dir`, as a
 * repository path into out; false past the root or when it does not fit
 * (pass_terraform.c). */
bool cbm_repo_rel_join(const char *dir, const char *v, char *out, size_t sz);

/* The Image node of image reference `ref` (its repository as written, tag
 * and digest dropped; Docker Hub's host spellings as docker.io with library/
 * for an official image; registry "unknown" when the reference names no
 * host -- none is invented), made when new; 0 for scratch or no image. */
int64_t cbm_pipeline_image_node(cbm_pipeline_ctx_t *ctx, const char *ref);
/* Does `ref` follow the image reference grammar (distribution/reference):
 * [host[:port]/]path[:tag][@algo:hex], path components lowercase alphanumerics
 * joined by `.`, `_`, `__` or dashes, a tag of word characters, `.` and `-`
 * (128 at most)? A value rendered from a template is checked before it names
 * an Image (pass_docker.c). */
bool cbm_image_ref_valid(const char *ref);

/* A chart repository URL as an identity (pass_k8s.c): `url` trimmed, its
 * scheme and host lower-cased, trailing `/` and `.git` dropped. False for no
 * URL: no scheme or host, a file:// directory, credentials in the authority,
 * a query or fragment (`?`, `#`: a token may ride there), or a byte no
 * stated URL holds (whitespace, quote, template, `$`). A
 * repository URL is never cut: oci://host/x with chart x is oci://host/x/x. */
bool cbm_chart_repo_url(const char *url, char *out, size_t sz);

/* The repository of chart reference `ref` (a Flux OCIRepository url, a
 * Terraform `chart = "oci://..."`): all before its last segment, the chart.
 * False when none is left. */
bool cbm_chart_ref_repo(const char *ref, char *out, size_t sz);

/* The external Chart node of chart `name` from repository `url` (pass_k8s.c),
 * made when new and owned by `file`: `__chart__<url>/<name>` {source,
 * external, repository} -- one QN in every project -- when `url` resolves
 * (cbm_chart_repo_url), else `<project>.__helm_dep__.<name>`. */
int64_t cbm_pipeline_external_chart(cbm_pipeline_ctx_t *ctx, const char *name, const char *url,
                                    const char *file);

/* Is Chart node `node` an external chart (either identity) rather than one
 * a Chart.yaml of this repository declares? */
bool cbm_pipeline_chart_is_external(const cbm_gbuf_node_t *node);

/* Environment variable `key` that `owner` sets (pass_docker.c): a K8s or
 * compose Resource for its container `container`, a Dockerfile Module for
 * its image (container NULL). Makes the container-scoped EnvVar
 * `<owner QN>#env/<container | ->/<key>` {env_key, scope, container,
 * source}, owned by the owner's file at `line`, and owner -CONFIGURES
 * {strategy:env_set, source}-> it. No edge to the global EnvVar of the key:
 * the same name read elsewhere is another program's. `source` says where the
 * value comes from; the value is never stored. 0 when `key` is no variable
 * name ([A-Za-z_][A-Za-z0-9_.-]*). */
int64_t cbm_pipeline_env_setter(cbm_pipeline_ctx_t *ctx, const cbm_gbuf_node_t *owner,
                                const char *container, const char *key, const char *source,
                                int line);

/* Container builds (pass_docker.c): a Dockerfile DEPENDS_ON the Images it
 * builds on (FROM, COPY --from). Run at the end of the K8s pass. */
void cbm_pipeline_pass_docker(cbm_pipeline_ctx_t *ctx, const cbm_file_info_t *files,
                              int file_count);

/* The env join (pass_envjoin.c): a container's EnvVar CONFIGURES {strategy:
 * env_read} each reader of its name inside the files the container's image
 * is built from. Recomputes every such edge; after the Docker pass. Returns
 * how many. */
int cbm_pipeline_env_join(cbm_pipeline_ctx_t *ctx);

/* Whether a Dockerfile Module's properties (image_files) copy `path` into
 * the image, ignore patterns aside. */
bool cbm_envjoin_props_hold(const char *props, const char *path);

/* Pre-dump pass: markdown → file REFERENCES_FILE linking. */
int cbm_pipeline_pass_doclinks(cbm_pipeline_ctx_t *ctx);

/* Pre-dump pass: SIMILAR_TO edges via MinHash fingerprinting. */
int cbm_pipeline_pass_similarity(cbm_pipeline_ctx_t *ctx);

/* Pre-dump pass: SEMANTICALLY_RELATED edges via algorithmic embeddings.
 * Opt-in: only runs when CBM_SEMANTIC_ENABLED=1. */
int cbm_pipeline_pass_semantic_edges(cbm_pipeline_ctx_t *ctx);

/* Pre-dump pass: interprocedural complexity propagation (Tier B).
 * Propagates per-function loop_depth along CALLS edges into a transitive
 * worst-case nested-loop estimate (transitive_loop_depth) and flags call-graph
 * cycles (recursive). Runs on the graph buffer before the dump. */
void cbm_pipeline_pass_complexity(cbm_pipeline_ctx_t *ctx);

/* Pre-dump pass: per-symbol importance score (weighted degree).
 *   importance = sqrt(num_refs) * priv * generic * distinct * test_penalty
 * Stored as a numeric "importance" key inside the node's EXISTING
 * properties_json — no schema change and no index-format bump; indexes written
 * by older builds simply lack the key and consumers must tolerate its absence.
 * MUST run after pass_tests and after CALLS/USAGE extraction — a pass ordered
 * earlier would see zero TESTS edges and num_refs = 0 everywhere. It is
 * therefore registered last in run_predump_passes and last in the incremental
 * post-pass sequence. */
void cbm_pipeline_pass_importance(cbm_pipeline_ctx_t *ctx);

/* Gathered inputs for one symbol. Each scoring route fills this its own way
 * (gbuf lookups, or SQL aggregates) and then calls the ONE rule below. */
typedef struct {
    const char *name;
    const char *file_path;
    int num_refs;            /* incoming CALLS + USAGE */
    int name_distinct_files; /* distinct files the NAME is defined in */
    bool tests_target;       /* has an incoming TESTS edge */
} cbm_importance_inputs_t;

/* THE scoring rule — single definition, shared by every route, so the two
 * gathering strategies cannot drift apart in what a score means. */
double cbm_pipeline_importance_score(const cbm_importance_inputs_t *in);

/* Produce a copy of `json` with the numeric "importance" key set to `score`,
 * or NULL when `json` is not a JSON object or allocation fails. Caller owns
 * the result. IDEMPOTENT: an existing key is overwritten in place, never
 * appended twice — every re-scoring route sees nodes that already carry it.
 * Single definition, shared by the in-memory and SQL writers alike. */
char *cbm_pipeline_importance_set_prop(const char *json, double score);

/* gbuf-node convenience wrapper around cbm_pipeline_importance_set_prop. */
void cbm_pipeline_importance_append_prop(cbm_gbuf_node_t *node, double score);

/* Recompute importance for an ENTIRE project directly in a store, in SQL.
 * Used by the closure-delta incremental route, whose in-RAM graph is a proxy
 * buffer with no project-wide edges — scoring there would persist a near-zero
 * in-degree for heavily-referenced symbols in the changed files. Must be
 * called on the STAGING store AFTER cbm_delta_patch has merged nodes and
 * re-linked inbound edges. Returns 0 on success; the caller treats failure as
 * a delta-route failure and falls back to a full rebuild. */
int cbm_pipeline_importance_recompute_store(cbm_store_t *store, const char *project);

/* transitive_loop_depth/recursive over the complete staging store of the
 * closure-delta route (the in-memory pass's traversal, gathered from SQL).
 * Runs before the importance rescore. 0 on success. */
int cbm_pipeline_complexity_recompute_store(cbm_store_t *store, const char *project);

/* Work counters for the importance pass (pass_importance.c). Deltas are read
 * by the complexity suite's linearity gate; never reset by the pass itself, so
 * nested/repeated runs compose. g_importance_name_visits counts same-name-group
 * member visits during distinct-file counting — the quantity that goes
 * superlinear if the per-distinct-name memoization is ever lost. */
extern _Atomic uint64_t g_importance_nodes;
extern _Atomic uint64_t g_importance_name_visits;
/* Rows rescored by the SQL-level store recompute. Lets a test prove the
 * closure-delta route actually took that path instead of passing vacuously. */
extern _Atomic uint64_t g_importance_store_rows;

/* Work counters of the infra resolvers, gated by the complexity suite:
 * candidate objects the K8s pass examines for references, selectors and
 * CRDs (pass_k8s.c), and candidate Go types / package dirs the operator pass
 * examines (pass_operator.c). Independent copies must grow them linearly. */
extern _Atomic uint64_t g_k8s_candidates;
extern _Atomic uint64_t g_op_candidates;
extern _Atomic uint64_t g_sh_candidates;

/* ── Incremental pipeline (pipeline_incremental.c) ───────────────── */

/* Run incremental re-index on an existing disk DB.
 * Classifies files by mtime+size, deletes changed nodes, re-parses changed
 * files, merges into disk DB. Returns 0 on success. */
int cbm_pipeline_run_incremental(cbm_pipeline_t *p, const char *db_path, cbm_file_info_t *files,
                                 int file_count, const cbm_file_hash_t *baseline_manifest,
                                 int baseline_count, bool force_full_on_mismatch);

/* The exact no-op test cbm_pipeline_run_incremental routes by, read-only on
 * an already opened generation: true when that generation is current for the
 * pipeline's mode and records exactly the baseline manifest. */
bool cbm_pipeline_incremental_generation_exact(cbm_pipeline_t *p, cbm_store_t *store,
                                               const cbm_file_hash_t *baseline_manifest,
                                               int baseline_count);

/* Exact semantic inputs for no-op/forced-full routing. The manifest contains
 * every discovered source plus repository controls actually consumed by
 * discovery, package mapping, path aliases, and extension overrides. */
#define CBM_SEMANTIC_INPUT_PREFIX ".codebase-memory/.semantic-input/"
#define CBM_SEMANTIC_INPUT_GIT_CONTEXT CBM_SEMANTIC_INPUT_PREFIX "git-context-v1"
#define CBM_SEMANTIC_INPUT_GLOBAL_CONFIG CBM_SEMANTIC_INPUT_PREFIX "global-extension-config-v1"
#define CBM_SEMANTIC_INPUT_PROJECT_CONFIG CBM_SEMANTIC_INPUT_PREFIX "project-extension-config-v1"

int cbm_pipeline_build_semantic_manifest(const cbm_pipeline_t *p, const char *project,
                                         const char *repo_path, const cbm_file_info_t *files,
                                         int file_count, char **excluded_dirs, int excluded_count,
                                         const cbm_git_context_t *git_ctx,
                                         const cbm_userconfig_t *userconfig, cbm_file_hash_t **out,
                                         int *out_count);
void cbm_pipeline_free_semantic_manifest(cbm_file_hash_t *manifest, int count);
bool cbm_pipeline_semantic_manifests_equal(const cbm_file_hash_t *left, int left_count,
                                           const cbm_file_hash_t *right, int right_count);
/* Re-run discovery and hash its exact semantic inputs. Used at the publication
 * boundary so late additions/deletions cannot escape a frozen file list. */
int cbm_pipeline_build_fresh_semantic_manifest(cbm_pipeline_t *p, const char *project,
                                               cbm_file_hash_t **out, int *out_count);

/* Compatibility contract persisted in coverage metadata. Increment when a
 * graph/manifest semantic change makes prior exact-input indexes unsafe.
 *   4: C-family node identities changed. A preprocessor macro's QN ends in
 *      "#macro"; unscoped C/C++/Objective-C enumerators are `<scope>.<NAME>`
 *      (the enum name is no longer a segment); typedef names, anonymous-enum
 *      constants and macro-prefixed functions are nodes; a bodyless
 *      `struct X` is no node. An index written before this holds the old
 *      QNs for every unchanged file, so it is rebuilt in full once.
 *   5: doc-comment references became MENTIONS edges and doc_link_unresolved
 *      rows, and C# LSP surfaces carry the doc-link scope ("dl"); an index
 *      built before has neither, so it rebuilds once on upgrade.
 *   6: documents became link sources: Markdown, reStructuredText and AsciiDoc
 *      sections and PDF pages hold MENTIONS edges into the code, ADR records
 *      are nodes, and AsciiDoc files, PDFs and a Sphinx project's extra
 *      source suffixes are indexed. An index built before has none of this
 *      for its unchanged documents, so it rebuilds once on upgrade.
 *   7: SEMANTICALLY_RELATED changed: TF-IDF compares vocabulary, string
 *      properties are read with their escapes, admission is best-first and
 *      every edge carries "p"; doc_link_candidates holds doc section -> code
 *      candidates. An index built before has the old pairs and no
 *      candidates, so it rebuilds once on upgrade. Released together with
 *      7 (no release in between, so no number of its own): doc comments of
 *      Go, Java, Kotlin, Rust, Perl, TS/JS, PHP and C hold MENTIONS edges;
 *      diagrams are Diagram/DiagramElement nodes with DIAGRAM_ARROW edges;
 *      OpenAPI operations are Routes; a Markdown section's text keeps a
 *      diagram fence's labels instead of its syntax, and its candidates
 *      carry the p of its diagrams' kind family; a non-static file-scope
 *      C/C++/CUDA/ObjC function in a platform file or directory (foo_win.c,
 *      src/unix/) keeps its path QN and carries a `variant_key` property
 *      (its platform-neutral QN) that relates its platform variants.
 *   8: a file and the directory beside it with one stem (`pkg/foo.sh`,
 *      `pkg/foo/`) no longer share a QN (cbm_stem_marks_t): the Folder is
 *      spelled `proj.pkg.foo/`, or, where the directory is a Java/Go package,
 *      the file's Module is `proj.pkg.foo#sh`. The Module the Folder used to
 *      swallow is a node again. An index built before holds neither, so it
 *      rebuilds once on upgrade.
 *   9: a container's variable reaches its program: the EnvVar a container
 *      sets CONFIGURES {strategy:env_read} the readers of its name inside the
 *      files the container's image is built from (pass_envjoin.c); a K8s
 *      image reference says its container (USAGE {ref:image, container}) and
 *      a Dockerfile's Module its image's files (image_context, image_files,
 *      image_ignore). A workload or compose service CONNECTS_TO the Service
 *      its environment addresses (extract_k8s.c, pass_docker.c). A script's
 *      curl / wget HTTP_CALLS the Route of the URL it states (pass_shell.c).
 *      A kustomize patch OVERRIDEs the objects of its build it changes, its
 *      file an IMPORTS of the kustomization; a Resource keeps the version of
 *      its apiVersion and its labels; a kustomization DEPLOYS the charts it inflates
 *      (helmCharts); an object a namePrefix / nameSuffix renames has a
 *      variant Resource {ecosystem:kustomize} with its deployed name, which
 *      OVERRIDEs {via:namePrefix|nameSuffix} it (extract_k8s.c,
 *      pass_k8s.c). A Terraform reference
 *      USAGEs {ref, via:terraform}, from its block, the block of its module
 *      (directory) declaring it (one in depends_on: DEPENDS_ON), instead of
 *      the generic name matcher's USAGE / CALLS; a bare block label names
 *      its block like a quoted one; a module call with a local source
 *      IMPORTS its directory's Folder (the root: the Project) and module.X.Y
 *      USAGEs {ref:output} the output there; a .tfvars assignment OVERRIDEs
 *      {via:tfvars} the variable block of its own directory (or, inferred,
 *      of the nearest ancestor module declaring its names); a Terragrunt
 *      unit's include / read_terragrunt_config IMPORTS {via:terragrunt} the
 *      file it names, a dependency DEPENDS_ON the other unit; a
 *      kubernetes_* resource with a literal name is a Resource
 *      {ecosystem:terraform} its block DEPLOYS
 *      (pass_terraform.c, extract_unified.c, extract_defs.c); an Ansible
 *      playbook / task file IMPORTS {via:ansible} the playbooks, task files
 *      and roles its directives name, its tasks and handlers are Functions
 *      {source:ansible}, a notify CALLS {via:notify} the handlers it names,
 *      a kube / k8s task DEPLOYS {via:ansible} the template it applies
 *      (pass_ansible.c). An external Chart is keyed by its publisher URL.
 *      An index built before holds none of them, so it rebuilds once on
 *      upgrade.
 *  10: combine the platform variants, stem disambiguation and infrastructure
 *      layers above with unresolved-call evidence capture and its candidate
 *      index. Both upstream version 9 and this branch's earlier version 9
 *      lack part of these semantics, so unchanged files rebuild once.
 *  11: Python local defs and classes bind through their enclosing lexical
 *      scope, including app-factory route handlers. Published version 10
 *      predates this resolution, so unchanged files rebuild once on upgrade.
 *  12: repeated ATX and Setext Markdown headings use parent-qualified Section
 *      names only when distinct parent chains separate them. Unchanged bare names
 *      are preserved and dotted-name collisions are disambiguated before section
 *      references resolve. Old indices rebuild once so Section nodes, MENTIONS
 *      and diagram owners agree.
 *  13: a Next.js App Router route handler, the HTTP verb Function a route.ts
 *      / route.js under app/ or src/app/ exports, carries the route_path its
 *      directories name and HANDLES its Route (extract_nextjs.c). An index
 *      built before has none of these Routes for its unchanged route files,
 *      so it rebuilds once on upgrade.
 * The unresolved-call coverage threshold remains independent. */
enum { CBM_SEMANTIC_INDEX_VERSION = 13 };

typedef struct {
    cbm_gbuf_t *gbuf;
    const char *final_db_path;
    const char *project;
    atomic_int *cancelled;
    const cbm_file_hash_t *manifest;
    int manifest_count;
    const cbm_coverage_row_t *coverage;
    int coverage_count;
    cbm_coverage_meta_t coverage_meta;
    /* Per-file LSP surfaces for the generation being published (may be NULL:
     * cross-LSP disabled, or a caller that has none). Written into the
     * staging store alongside the manifest so surface data and graph always
     * belong to the same generation. */
    const cbm_lsp_surface_row_t *surface_rows;
    int surface_row_count;
    /* True when the caller already wrote this generation's surface rows
     * into the staging store (delta patch); publish then skips the
     * wholesale delete+rewrite. */
    bool surfaces_in_place;
    /* The generation's doc_link_unresolved rows (complete: an incremental
     * route passes the merge of carried-forward and fresh rows), and whether
     * the doc-link layer failed for it (publish then adds the error marker
     * row that index_status reports as doc_links.status = "error"). */
    const cbm_doc_link_row_t *doc_link_rows;
    int doc_link_row_count;
    bool doc_links_failed;
    /* Doc -> code candidates of this generation (pass_semantic_edges; may be
     * NULL: none found, or a mode without the semantic pass), written into
     * the staging store with the graph. */
    const cbm_doc_candidate_t *doc_candidates;
    int doc_candidate_count;
    /* True when the staging store already holds this generation's
     * candidates: the delta clone keeps the previous generation's rows (its
     * proxy buffer has no section text or function tokens to recompute
     * them); a row whose node is gone resolves to nothing when read. */
    bool doc_candidates_in_place;
} cbm_pipeline_generation_t;

/* Serialize and fully populate a sibling staging database, then atomically
 * replace final_db_path. The old generation is untouched on every failure or
 * cancellation observed before the rename commit point. */
int cbm_pipeline_publish_generation(const cbm_pipeline_generation_t *generation);
/* Final leg shared by the dump-built and delta-patched publication paths:
 * sidecar removal, previous-generation quarantine, atomic rename. The stage
 * must be complete and sealed with its store handle closed. Discards the
 * stage on every failure. Does NOT free stage_path. */
int cbm_pipeline_finalize_staged_generation(char *stage_path, const char *final_db_path,
                                            atomic_int *cancelled, bool destination_known_healthy);
/* Metadata writes + FTS policy + integrity + seal + finalize for an
 * already-materialized staging DB. Takes ownership of stage_path. The dump
 * path passes fts_wholesale=true; the delta path passes false (its patch
 * wrote row-level FTS inserts). generation->gbuf is not read here. */
int cbm_pipeline_publish_staged(char *stage_path, const cbm_pipeline_generation_t *generation,
                                bool fts_wholesale, bool destination_known_healthy);

/* mkstemp-minted staging sibling of final_path (exported for the delta
 * executor; the dump path uses it internally). malloc'd, caller frees. */
char *cbm_pipeline_create_staging_path(const char *final_path);

/* Stage ownership (#1839). Every stage minted by cbm_pipeline_create_staging_path
 * is owned through an exclusive kernel lock on the sidecar "<stage>.lock" for
 * as long as the stage exists; the lock -- and the sidecar -- go away when the
 * stage is discarded or renamed into place, and the kernel drops the lock
 * when the writer dies. Hold/drop are the same primitive, exposed so a test
 * can stand in for a live writer. hold returns a descriptor >= 0, or -1 when
 * another holder is live or the sidecar cannot be created. drop releases the
 * lock and unlinks the sidecar. */
int cbm_pipeline_stage_lock_hold(const char *stage_path);
void cbm_pipeline_stage_lock_drop(const char *stage_path, int lock_fd);

/* ── Delta-repair staging primitives (pipeline_delta.c) ──────────
 * Closure-route-only subsystem: clone the live generation, patch exactly
 * the repaired node/edge set, publish through the shared finalize leg. */
typedef struct {
    char *source_qn;
    char *target_qn;
    char *type;
    char *props;
} cbm_delta_saved_edge_t;

int cbm_delta_stage_clone(const char *final_db_path, char **out_stage_path);
int cbm_delta_snapshot_inbound(cbm_store_t *store, const char *project, const char *const *paths,
                               int path_count, cbm_delta_saved_edge_t **out, int *out_count);
void cbm_delta_free_snapshot(cbm_delta_saved_edge_t *items, int count);
int cbm_delta_purge(cbm_store_t *store, const char *project, const char *const *paths,
                    int path_count);
/* Delete the project's `label` nodes no edge of `edge_types` (NULL-terminated)
 * touches as source or target (a Process whose last spawner was purged, an
 * Image no Dockerfile or workload names any more); returns how many, or -1
 * on failure. */
int cbm_delta_drop_unreferenced(cbm_store_t *store, const char *project, const char *label,
                                const char *const *edge_types);
/* Delete the project's `label` nodes that carry no file and that no edge of
 * any type touches (a Route whose last caller and handler were purged);
 * returns how many, or -1 on failure. */
int cbm_delta_drop_edgeless(cbm_store_t *store, const char *project, const char *label);
/* An Image's build edges (Image -DEPENDS_ON {via:build}-> Dockerfile,
 * pass_docker.c) belong to the build configuration declaring them, not to
 * either end: every run recomputes them whole from all build files, the
 * incremental routes drop the old set first and write the new one even
 * between pre-existing nodes. */
#define CBM_BUILD_EDGE_TYPE "DEPENDS_ON"
#define CBM_BUILD_EDGE_SOURCE "Image"
/* The env join's edges (EnvVar -CONFIGURES {strategy:env_read}-> reader,
 * pass_envjoin.c) likewise: no other producer draws CONFIGURES from an
 * EnvVar, every run recomputes them whole. */
#define CBM_ENVJOIN_EDGE_TYPE "CONFIGURES"
#define CBM_ENVJOIN_EDGE_SOURCE "EnvVar"

/* The env join's inputs the store holds (the unchanged files of a closure
 * repair, read after the purge), into `out` (its arena owns them); 0, or -1
 * on failure. cbm_envjoin_base_free releases it. */
int cbm_delta_envjoin_base(cbm_store_t *store, const char *project, cbm_envjoin_base_t *out);
void cbm_envjoin_base_free(cbm_envjoin_base_t *b);
/* 1 when a stored image copies one of `paths` (a deletion then changes
 * which context the Dockerfile's sources resolve in), 0 when none, -1 on
 * failure. */
int cbm_delta_image_holds_any(cbm_store_t *store, const char *project, const char *const *paths,
                              int path_count);

/* The files whose File node the shell pass marked as running a container
 * build ({"declares_build":true}), into arena `a`; returns how many, or -1
 * on failure. */
int cbm_delta_build_decl_files(cbm_store_t *store, const char *project, CBMArena *a,
                               const char ***out);

/* The QNs of the component Images a split repository gave its components
 * (pass_docker.c P4.2b: Images with a `component` property), sorted, into
 * arena `a`; returns how many, or -1 on failure. A closure repair compares
 * them with the run's own: references in files it does not repair point at
 * the old ones. */
int cbm_delta_image_components(cbm_store_t *store, const char *project, CBMArena *a,
                               const char ***out);

/* Delete the project's `type` edges whose source node has label `label`;
 * returns how many, or -1 on failure. */
int cbm_delta_drop_edges_from_label(cbm_store_t *store, const char *project, const char *type,
                                    const char *label);
/* The edges that keep a file-less shared node alive. */
#define SH_PROCESS_EDGES ((const char *const[]){"SPAWNS", NULL})
/* An Image a release DEPLOYS (pass_k8s.c release images) may have no other edge. */
#define DK_IMAGE_EDGES ((const char *const[]){"DEPENDS_ON", "USAGE", "DEPLOYS", NULL})
/* Pre-seed proxy nodes with their REAL database ids and move the gbuf id
 * watermark above MAX(id); returns that max id, or -1 on failure. */
int64_t cbm_delta_preseed(cbm_store_t *store, const char *project, cbm_gbuf_t *gbuf);
int cbm_delta_patch(cbm_store_t *store, const char *project, cbm_gbuf_t *gbuf, int64_t max_db_id,
                    const cbm_delta_saved_edge_t *snapshot, int snapshot_count);
/* discard helper shared with the delta executor (unlink stage + sidecars). */
void cbm_pipeline_discard_stage(const char *stage_path);
/* Hand the pipeline the per-file LSP-surface rows serialized at the
 * collect_all_defs seam (the only moment the result cache is alive).
 * Takes ownership; dump_and_persist_hashes writes them into the staging
 * store and cbm_pipeline_free releases them. Passing NULL/0 clears. */
void cbm_pipeline_set_lsp_surfaces(cbm_pipeline_t *p, cbm_lsp_surface_row_t *rows, int count);
/* One entry per call, owned by the current file's resolve pass. Candidate
 * strings are borrowed from the graph and copied by coverage capture. */
typedef struct {
    const char *candidate_qn;
    bool calls_emitted;
} CBMCallEvidence;
void cbm_pipeline_record_unresolved_calls(cbm_pipeline_t *p, const char *rel_path,
                                          const CBMFileResult *result,
                                          const CBMCallEvidence *evidence);
void cbm_pipeline_mark_unresolved_capture_failed(cbm_pipeline_t *p);
void cbm_pipeline_get_unresolved_calls(cbm_pipeline_t *p, cbm_coverage_row_t **rows, int *count,
                                       bool *complete);

/* The run's doc_link_unresolved rows and failure flag (doc_links.h), taken
 * over by the pipeline (set replaces and frees earlier rows; NULL p frees).
 * A full run publishes them from dump_and_persist_hashes; an incremental
 * route takes them back for its carry-forward merge. `ran` stays false until
 * a doc-link phase hands rows over, so a route that never resolved can tell. */
void cbm_pipeline_set_doc_link_rows(cbm_pipeline_t *p, cbm_doc_link_row_t *rows, int count,
                                    bool failed);
void cbm_pipeline_take_doc_link_rows(cbm_pipeline_t *p, cbm_doc_link_row_t **rows, int *count,
                                     bool *failed, bool *ran);

/* Hand the run's doc -> code candidates (pass_semantic_edges) to the
 * pipeline. Takes ownership (rows and strings in CBM_MEM_CLASS_STORE, released
 * with cbm_store_doc_candidates_free); a NULL p frees them. NULL/0 clears. */
void cbm_pipeline_set_doc_candidates(cbm_pipeline_t *p, cbm_doc_candidate_t *rows, int count);
const cbm_doc_candidate_t *cbm_pipeline_doc_candidates(const cbm_pipeline_t *p, int *count);

/* Pipeline accessors for incremental use */
const char *cbm_pipeline_repo_path(const cbm_pipeline_t *p);
const cbm_test_declarations_t *cbm_pipeline_test_declarations(const cbm_pipeline_t *p);
/* Without an active run snapshot this only validates fresh's source state. */
bool cbm_pipeline_project_source_matches(const cbm_pipeline_t *p, const cbm_userconfig_t *fresh);
const cbm_index_resource_policy_t *cbm_pipeline_resource_policy(const cbm_pipeline_t *p);
cbm_index_resource_violation_t *cbm_pipeline_resource_violation(cbm_pipeline_t *p);
/* Borrowed checkout identity captured and validated for this pipeline run. */
const char *cbm_pipeline_indexed_checkout_sha(const cbm_pipeline_t *p);
atomic_int *cbm_pipeline_cancelled_ptr(cbm_pipeline_t *p);
/* Record committed graph size (#334 gate axis) from the incremental path,
 * which cannot see the opaque cbm_pipeline struct. Call before the dump. */
void cbm_pipeline_set_committed_counts(cbm_pipeline_t *p, int nodes, int edges);

/* Test seam: invoked after a complete staging DB is sealed and immediately
 * before the cancellation check + atomic replace. Not part of the public API. */
void cbm_pipeline_set_before_publish_hook_for_tests(
    cbm_pipeline_t *p, void (*hook)(cbm_pipeline_t *, const char *, void *), void *ctx);
/* Test seam: invoked with the complete graph buffer just before the full
 * route dumps it (the dump releases the buffer's indexes). */
void cbm_pipeline_set_before_dump_hook_for_tests(cbm_pipeline_t *p,
                                                 void (*hook)(const cbm_gbuf_t *, void *),
                                                 void *ctx);
void cbm_pipeline_set_rename_hook_for_tests(cbm_pipeline_t *p,
                                            int (*hook)(const char *, const char *, void *),
                                            void *ctx);

/* Test seam: the sequential CALLS pass's args formatter (pass_calls.c), so a
 * test can hand it an argument longer than its formatting buffer and read the
 * props it leaves behind. `props` is a NUL-terminated JSON object of `cap`
 * bytes; the formatter appends its "args" array in place. */
void cbm_pipeline_calls_append_args_for_tests(char *props, size_t cap, const CBMCall *call);

/* Synchronous thread-local seam for deterministic cross-repo cancellation
 * tests. The callback runs immediately after a CROSS_* edge is committed and
 * is never retained; it must not re-enter cross-repo matching. */
typedef void (*cbm_cross_repo_after_insert_test_hook_t)(const char *project, const char *edge_type,
                                                        void *context);
void cbm_cross_repo_set_after_insert_hook_for_tests(cbm_cross_repo_after_insert_test_hook_t hook,
                                                    void *context);

/* Parse a gRPC stub call "<service-stub>.<method>" into the canonical proto
 * service name + method. Returns true ONLY when a recognized gRPC stub/client
 * suffix is present (the stub-type signal that gates Route emission, #294).
 * Exposed for testing. */
bool extract_grpc_service_method(const char *callee, char *service, size_t srv_sz, char *method,
                                 size_t meth_sz);

/* Extraction back-pressure observability (pass_parallel.c): nap-cycle counter
 * for the over-budget collect+nap gate. Test hook — asserts the gate stops
 * re-paying the nap tax once a full cycle failed to reclaim under budget
 * (futile: the resident floor, not transients, holds the memory). */
long cbm_pp_bp_nap_cycles(void);
void cbm_pp_bp_nap_cycles_reset(void);

/* Number of resolved-call rows handed to the parallel resolver's linear LSP
 * fallback since the last reset. Test observability for occurrence-index
 * coverage; deterministic and independent of wall-clock timing. */
uint64_t cbm_pp_lsp_linear_fallback_rows(void);
void cbm_pp_lsp_linear_fallback_rows_reset(void);

#if defined(CBM_COVERAGE_MARKER_TEST_API) && CBM_COVERAGE_MARKER_TEST_API
/* Test-only view of the Studio Export range join, so the ",+<N>" truncation
 * marker rules can be checked without building a 256-region export file. */
bool cbm_pipeline_coverage_marker_test_join(CBMFileResult *aggregate, const CBMFileResult *part);
#endif

#if defined(CBM_CALL_REFERENCE_LOOKUP_TEST_API) && CBM_CALL_REFERENCE_LOOKUP_TEST_API
/* Deterministic test-only operation count for the shared semantic-reference
 * matcher used by both sequential and fused-parallel usage materialization. */
void cbm_pipeline_lsp_reference_lookup_test_reset(void);
uint64_t cbm_pipeline_lsp_reference_lookup_test_rows_examined(void);
#endif

#if defined(CBM_INCREMENTAL_TEST_API) && CBM_INCREMENTAL_TEST_API
typedef enum {
    CBM_INCREMENTAL_ROUTE_NONE = 0,
    CBM_INCREMENTAL_ROUTE_NOOP,
    CBM_INCREMENTAL_ROUTE_FORCED_FULL,
    CBM_INCREMENTAL_ROUTE_LEGACY_PARTIAL,
    CBM_INCREMENTAL_ROUTE_CLOSURE_REPAIR,
} cbm_incremental_route_t;

/* Deterministic one-shot fault injection for the incremental-parallel result
 * cache allocation. Reset explicitly so one test cannot affect another. */
void cbm_pipeline_incremental_test_fail_result_cache_alloc_once(void);
void cbm_pipeline_incremental_test_force_legacy_partial_once(void);
void cbm_pipeline_incremental_test_fail_after_stage_dump_once(void);
void cbm_pipeline_incremental_test_cancel_after_predump_once(void);
void cbm_pipeline_incremental_test_cancel_after_destination_prepare_once(void);
typedef void (*cbm_pipeline_test_hook_fn)(void *userdata);
void cbm_pipeline_incremental_test_before_final_manifest_once(cbm_pipeline_test_hook_fn hook,
                                                              void *userdata);
/* Fires from create_staging_path(), right after the stage's main file is
 * created with O_EXCL. In the current lock-before-visible ordering its sidecar
 * lock is already held at this point, so a test hook installed here can run a
 * concurrent sweep (via another cbm_pipeline_run() against the same
 * final_path) and confirm the just-created stage survives it. Under the OLD
 * create-then-lock ordering this was the unlocked window, so the hook also
 * binds RED if that ordering regresses. */
void cbm_pipeline_incremental_test_after_stage_created_once(cbm_pipeline_test_hook_fn hook,
                                                            void *userdata);
cbm_incremental_route_t cbm_pipeline_incremental_test_last_route(void);
void cbm_pipeline_incremental_test_reset_faults(void);

/* Shared persistence-hook plumbing. Tests use the incremental facade above so
 * one reset covers route, extraction, and publication faults. */
bool cbm_pipeline_persist_test_take_failure_after_stage_dump(void);
bool cbm_pipeline_persist_test_take_cancel_after_predump(void);
bool cbm_pipeline_persist_test_take_cancel_after_destination_prepare(void);
void cbm_pipeline_persist_test_run_before_final_manifest(void);
void cbm_pipeline_persist_test_run_after_stage_created(void);
void cbm_pipeline_persist_test_reset_faults(void);
#endif

#endif /* CBM_PIPELINE_INTERNAL_H */