kit

runner.h (6483B)

---

 #ifndef KIT_BUILD_RUNNER_H
 #define KIT_BUILD_RUNNER_H
 
 #include <kit/core.h>
 #include <stddef.h>
 #include <stdint.h>
 
 #include "build.h"
 #include "cfg.h"
 #include "coord.h"
 #include "resolve.h"
 #include "trace.h"
 
 /*
  * Phase 3: running a recipe (the server side of the recipe protocol). Acquires
  * a job slot, stages a sandbox, spawns the recipe via the exec host, services
  * its protocol requests over the transport — logging each as a dependency —
  * then on success ingests the output directory into the CAS, writes BOTH trace
  * kinds, prepends them to the target record, installs the output in the tree
  * cache, and returns the result. A nonzero exit propagates failure and writes
  * NO trace.
  *
  * Writing both traces on every real build is what lets a later request take
  * whichever path fits the change it sees.
  */
 
 /* One submitted-but-not-yet-awaited need: the coordinator-assigned token, the
  * (overlay-id, argv-id) it was dispatched under, and the in-flight future.
  * Becomes a recorded dep edge only when AWAITED; un-awaited entries are
  * cancelled when the recipe exits. */
 typedef struct BuildPendingNeed {
   uint64_t token;
   char dep[BUILD_TARGET_MAX];
   uint8_t overlay_id[BUILD_HASH_LEN];
   uint8_t argv_id[BUILD_HASH_LEN];
   BuildTargetFuture* future; /* from build_coord_dispatch */
   int awaited;
   BuildResolved result;
 } BuildPendingNeed;
 
 /* The dependency log accumulated while servicing one recipe: the direct base
  * inputs and direct target-dep edges, plus each dep's resolved deepset node, plus
  * the live pending-needs table (submitted, not yet awaited). Converted on success
  * into a shallow trace (direct inputs + dep edges) and a deep trace (a single
  * pointer to the root deepset node, built by build_leafset_union over these direct
  * leaves + dep edges + child nodes). Sections hang off caller/arena storage (no VLAs). */
 typedef struct BuildDepLog {
   BuildConfigLeaf* configs; /* direct propagated-config observations */
   size_t n_configs, cap_configs;
   BuildSourceLeaf* sources; /* direct source reads (absent recorded) */
   size_t n_sources, cap_sources;
   BuildGlobLeaf* globs; /* direct globs */
   size_t n_globs, cap_globs;
   BuildBlobLeaf* blobs; /* direct hash-pinned blobs */
   size_t n_blobs, cap_blobs;
   BuildDepEdge* deps; /* AWAITED `need` edges (recorded) */
   size_t n_deps, cap_deps;
   const BuildLeafSet** child_leafsets; /* one deepset node per awaited dep */
   size_t n_children, cap_children;
   BuildPendingNeed* pending; /* submitted, not yet awaited */
   size_t n_pending, cap_pending;
   uint64_t next_token; /* monotonic per-recipe token allocator */
 } BuildDepLog;
 
 /* build_run_recipe — the Phase 3 entry, the continuation of build_resolve — is
  * declared in resolve.h (so resolve.c can call it without including runner.h)
  * and IMPLEMENTED in runner.c: it acquires a job slot, stages the sandbox,
  * spawns the recipe (process argv = `argv`, delivered as-is), services its
  * protocol connection via build_runner_service, and on success ingests the
  * output and records both trace kinds. The two helpers below are the pieces of
  * that flow split out so the in-process transport and the trace writer are
  * independently testable.
  *
  * Recipe environment is CLEAN: the recipe receives its COMPLETE environment from
  * the host (KitBuildExec.spawn does not inherit the coordinator's ambient env) —
  * the KIT_BUILD_* vars plus the build's declared pass-through, sourced from the
  * effective config's `env.` namespace (KIT_BUILD_ENV_PREFIX). Those keys are
  * ordinary tracked config, so a recipe's environment is hermetic and cache-
  * visible and replays/bundles like any other config. */
 
 /* Service one recipe connection until it exits: read framed requests and
  * dispatch them, appending each dependency to `log`. Drives the protocol.h
  * codec over the transport. `chain` is this recipe's chain frame (its dispatched
  * needs extend it). Commands:
  *   config-get/source/glob/blob — synchronous; log the dep, reply.
  *   need (fused)           — build_resolve inline on this thread; log the edge.
  *   need-submit            — build_coord_dispatch(dep) (concurrent, no block),
  *                            stash a BuildPendingNeed, reply a token. Cycles and
  *                            unknown targets fail fast here.
  *   need-await <token>     — release this recipe's job slot, await the pending
  *                            need's future, reacquire; THEN log the dep edge +
  *                            push its child node, and reply. The job slot is held
  *                            only while actively running, so a chain deeper than
  *                            `jobs` cannot deadlock (the same release/reacquire
  *                            applies to the fused `need`).
  * On EOF, any still-pending (submitted, never-awaited) needs are cancelled
  * (exec->kill) and recorded as NO dependency. Separated so the in-process
  * transport can reuse it. */
 int build_runner_service(KitBuildCoordinator*, KitBuildConn*, KitSlice target,
                          const BuildConfig* cfg, const BuildChainFrame* chain,
                          BuildDepLog* log);
 
 /* Convert a completed dep-log + output into the canonical persisted state:
  *  - build the root deepset node (build_leafset_union over the log's direct
  *    leaves + recipe-id + dep edges + child nodes), which stores it as a CAS blob and yields
  *    its deep-set-id;
  *  - emit + store the SHALLOW trace (direct inputs + dep edges, by hash) and the
  *    DEEP trace (scalars + the root deep-set-id), and prepend both to the target
  *    record.
  * Records the target's recipe-id and argv-id, its propagated-config
  * observations, and each dep edge's (overlay-id, argv-id). Returns the root
  * deepset node via *out_leafset so the caller can hand it back in
  * BuildResolved. */
 int build_runner_record_traces(KitBuildCoordinator*, KitSlice target,
                                const BuildArgv* argv, const BuildDepLog*,
                                const uint8_t output[BUILD_HASH_LEN],
                                const BuildLeafSet** out_leafset);
 int build_runner_record_test_traces(KitBuildCoordinator*, KitSlice target,
                                     const BuildArgv* argv,
                                     const BuildDepLog*,
                                     const uint8_t result[BUILD_HASH_LEN],
                                     const BuildLeafSet** out_leafset);
 
 #endif