kit

resolve.h (10378B)

---

 #ifndef KIT_BUILD_RESOLVE_H
 #define KIT_BUILD_RESOLVE_H
 
 #include <kit/core.h>
 #include <stddef.h>
 #include <stdint.h>
 
 #include "build.h"
 #include "cfg.h"
 #include "coord.h"
 
 /*
  * The resolution algorithm: resolve(T, cfg, chain) -> {output-tree, path,
  * leafset}, doing the least work necessary. Three phases (see doc/BUILD_COORDINATOR.md
  * §Resolution algorithm):
  *
  *   Phase 1  deep fast path  - same argv-id, matching target-scope projected
  *                              config observations, and an all-clear refresh of
  *                              the deepset closure (every source/glob/blob leaf
  *                              unchanged AND every node's recipe-id still
  *                              recomputes the same) => reuse, no graph walk.
  *   Phase 2  shallow path    - config, argv, and/or sources moved: guard on the
  *                              recipe-id, argv-id, consumed keys + direct leaves,
  *                              then re-resolve each recorded dep under the
  *                              current parent config plus its recorded overlay,
  *                              with its recorded argv, and compare OUTPUT tree-ids;
  *                              a match still skips the recipe (and writes a fresh
  *                              deep trace + deepset).
  *   Phase 3  run the recipe  - no trace holds (runner.h).
  *
  * On a local-record miss, resolution first attempts one lazy trace-remote pull
  * (build_coord_trace_remote_pull_once) and re-scans before Phase 3. The config-
  * dependence is recorded in and verified against the traces; the deep path
  * checks target-scope projected consumed keys + argv-id, the shallow path checks
  * direct consumed keys + argv-id. Recipe identity rides as a per-node scalar in
  * the deepset (Phase 1) and as the recipe-id guard (Phase 2); there is NO
  * whole-definition dependency. Cross-path dedup is the coordinator's targets
  * memo; per-path cycle detection is the build chain below.
  */
 
 /* One frame of the per-path build chain: the (target, config-id, argv-id) at one
  * level, linked to its parent (NULL at the root). The chain is a parent-linked
  * "cactus stack", NOT a mutable array — each dispatched `need` extends the
  * shared, read-only parent prefix with its own frame, so concurrent siblings
  * never copy or mutate one another's chain (the property the future-based `need`
  * fan-out requires). A `need` whose triple already appears on the walk from a
  * frame up to the root is a dependency cycle; walking the links renders the error
  * path (//a -> //b -> //a). Per-path, distinct from the cross-path futures memo:
  * a shared dep appears in many chains, never twice in one. Frames are allocated
  * off the coordinator's per-build arena and live until the build completes
  * (parents outlive their concurrent children by construction — no pop). */
 typedef struct BuildChainFrame {
   const struct BuildChainFrame* parent; /* NULL at the root request */
   BuildActionKind action;
   char target[BUILD_TARGET_MAX];
   uint8_t config_id[BUILD_HASH_LEN];
   uint8_t argv_id[BUILD_HASH_LEN];
 } BuildChainFrame;
 
 /* Extend `parent` (NULL at the root) with (target, config-id, argv-id), returning
  * the new tip in *out. Walks parent links to detect a cycle (the triple already
  * present) -> BUILD_ERR with the rendered path in err. The frame is allocated off
  * the coordinator's per-build arena; there is no pop (frames are immutable). */
 int build_chain_extend(KitBuildCoordinator*, const BuildChainFrame* parent,
                        BuildActionKind action, KitSlice target,
                        const uint8_t config_id[BUILD_HASH_LEN],
                        const uint8_t argv_id[BUILD_HASH_LEN],
                        const BuildChainFrame** out, char* err, size_t errcap);
 
 /* Resolve a target under the effective propagated config `cfg` and effective
  * local `argv` (cfg carries its config-id; argv hashes to its argv-id) — the
  * full (target, config-id, argv-id) identity. `chain` is the parent frame tip
  * (NULL at the root); this call extends it. Equivalent to dispatch+await on the
  * same thread (used by the top-level request and the fused one-shot `need`). On
  * success *out holds the output tree-id, a materialized path, and the deepset
  * node (its closure DAG root). Errors (cycle, recipe failure, missing inputs)
  * surface through the coordinator's diag. */
 int build_resolve(KitBuildCoordinator*, KitSlice target, const BuildConfig* cfg,
                   const BuildArgv* argv, const BuildChainFrame* chain,
                   BuildResolved* out);
 
 int build_test_resolve(KitBuildCoordinator*, KitSlice target,
                        const BuildConfig* cfg, const BuildArgv* argv,
                        const BuildChainFrame* chain, BuildTestResolved* out);
 
 /* The async half of resolution — the engine behind recipe-side `need_submit`.
  * Extends `chain` (cycle-checked here, so submit fails fast on a cycle), interns
  * the (target, config-id, argv-id) future, and — if fresh — drives the 3 phases
  * on a worker thread (build_coord_spawn) that completes the future; a duplicate
  * attaches to the in-flight future with no new thread. Returns the future in
  * *out_future WITHOUT blocking, so a recipe can submit many and let them resolve
  * concurrently. The result is collected later via build_coord_target_await.
  * `build_resolve` is the inline sibling (dispatch's phases run on the caller's
  * thread); in sequential mode (no sched) dispatch resolves inline and returns an
  * already-completed future, so submit/await stays semantically transparent. */
 int build_dispatch(KitBuildCoordinator*, KitSlice target, const BuildConfig* cfg,
                    const BuildArgv* argv, const BuildChainFrame* chain,
                    BuildTargetFuture** out_future, char* err, size_t errcap);
 
 /* Phase 3 of resolution: run the recipe — reached when no trace holds, or a
  * hit's bytes were evicted everywhere (build_materialize returned BUILD_ERR).
  * resolve and runner form one strongly-connected component (resolve calls
  * build_run_recipe for Phase 3; runner's service loop calls build_resolve for
  * each `need`): NOT a DAG edge. To keep that recursion compiling without a
  * resolve.h -> runner.h include, build_run_recipe is DECLARED here (the Phase-3
  * continuation of build_resolve) and IMPLEMENTED in runner.c (which owns the
  * spawn + service-loop machinery). Same *out contract as build_resolve. */
 int build_run_recipe(KitBuildCoordinator*, KitSlice target,
                      const BuildConfig* cfg, const BuildArgv* argv,
                      const BuildChainFrame* chain, BuildResolved* out);
 
 /* Verification-only sibling of build_run_recipe: executes the recipe and
  * ingests/materializes the fresh output tree, but writes NO shallow/deep trace
  * and does not update the target record. Used by verify mode to audit a cache
  * hit without replacing the cache's claim before the comparison succeeds. */
 int build_run_recipe_probe(KitBuildCoordinator*, KitSlice target,
                            const BuildConfig* cfg, const BuildArgv* argv,
                            const BuildChainFrame* chain, BuildResolved* out);
 int build_run_test_recipe(KitBuildCoordinator*, KitSlice target,
                           const BuildConfig* cfg, const BuildArgv* argv,
                           const BuildChainFrame* chain, BuildTestResolved* out,
                           int record_traces);
 
 /* The materialization ladder shared by every cache hit:
  *   tree cache/ -> local CAS -> remote object fetch.
  * A PURE locator: writes the materialized directory path and returns BUILD_OK,
  * or BUILD_ERR when the bytes are gone everywhere (not in the cache, not in the
  * CAS, no remote supplied them). It NEVER runs a recipe — on BUILD_ERR the
  * caller (resolve) falls through to Phase 3, which rebuilds and records the
  * correct output. Keeping it recipe-free removes the resolve->runner edge and
  * the stale-tree-id hazard a rebuild-inside-materialize would create (the cache
  * hit's recorded tree-id always describes the bytes returned). */
 int build_materialize(KitBuildCoordinator*,
                       const uint8_t tree_id[BUILD_HASH_LEN], char* path_out,
                       size_t cap);
 
 /* Build a parent's deepset node from its DIRECT leaves, awaited dep edges, and
  * child nodes. `direct` carries this node's target, recipe-id, and direct leaves
  * (its children fields empty); `deps` and `children` are aligned arrays for the
  * awaited deps. The node stores this target's projected config closure: direct
  * config observations plus child config observations whose keys were not
  * overlaid by that dep edge. Computes
  * the deep-set-id, stores the canonical node as a CAS blob (kit_cas_add_blob —
  * the children's blobs were stored when they were built, so this is incremental
  * and deduped), and returns the interned node. This IS the closure union —
  * "concat direct leaves + projected config leaves + child ids, hash" — never a
  * flat N-way merge. */
 int build_leafset_union(KitBuildCoordinator*, const BuildLeafSet* direct,
                         const BuildDepEdge* deps,
                         const BuildLeafSet* const* children, size_t nchildren,
                         const BuildLeafSet** out);
 
 /* Refresh a deepset node against the live workspace: per node, rehash its direct
  * source leaves (absent stays absent), reglob its glob leaves, check its fetched
  * blobs are still present in the CAS, check the root node's projected config
  * observations against the query config, recompute each node's
  * recipe-id through the LIVE definition (catching a dep repointed to a
  * different-content recipe, treating same-content as unchanged), and recurse
  * into children — all through the per-process memos and the deep-set-id validity
  * cache (build_coord_deepset_valid_*), so a shared subtree is checked once and
  * an unchanged subtree is skipped by id equality without descending. BUILD_OK +
  * *all_match==1 when the whole closure still matches; *all_match==0 on the first
  * divergence (Phase 1 then gives up). Phase 1 calls build_coord_deepset_load to
  * turn the trace's deep-set-id into the node passed here. */
 int build_leafset_refresh(KitBuildCoordinator*, const BuildLeafSet*,
                           const BuildConfig*, int* all_match);
 
 #endif