Documentation

Start Écluse: the entry point the ecluse executable runs (see Main).

Assemble the composition root from configuration. Parse the environment layer and the optional config document, validate everything and fail fast at boot on any problem (a malformed env, an unresolved rule policy, a configured mount with no adapter, a credential reference that does not resolve, or a mirror-queue backend not built in this binary), aggregating the failures so a single run reports them all. On success, build the handles (the shared HTTP Manager, the config-selected mirror queue, the metadata cache, the logger, the process-global credential provider, and the telemetry substrate, off unless ECLUSE_TELEMETRY enables it) into an Env, derive the served mount bindings, then run the server and the mirror worker concurrently over that single Env (runServer and runWorker). Bracketing the Env (and the telemetry providers) for the lifetime of both tears down their shared resources along every exit path.

Run the proxy's HTTP front door over the composition-root Env with the config-derived ServerConfig.

This is the npm-aware composition site: mountBindingFor mounts npm -- its path grammar (Ecluse.Core.Registry.Npm.Route) and its denial renderer (Ecluse.Core.Registry.Npm.Serve) -- into the otherwise ecosystem-neutral web layer (runServer), so the agnostic server stays closed over the shared Route set and only this one place names an ecosystem. Splitting the server into its own binary later reuses this same entry.

Run the supervised mirror worker over the composition-root Env and the per-ecosystem re-evaluation bundles: the consume → re-evaluate → fetch → verify → publish → ack loop against the queue, the publish-side registry client, and the credential handle, in the worker monad (WorkerM) over the worker runtime (workerRuntimeOf). The bundles carry the same prepared rules and public origin the serve path gates with, so the worker re-runs current policy against a job before mirroring it.

This is the composition-root hoist point: it resolves the request-independent dd correlation object (the service identity; no span is active at the worker entry) and installs it as the worker's initial katip context, then discharges the loop to IO through runWorkerM, the worker analogue of the serve path's runHandler boundary. The loop logic lives in Ecluse.Core.Worker; the single-process program runs this alongside runServer.

The fallback server settings: a single npm mount with no packument-serve or publish dependencies, so the packument route is the recognised-but-unserved 501 stub and a publish is 405 (no publication target). Exposed so the composed front door can be driven directly without binding a socket (e.g. embedded in another wai application, or exercised in tests through application) to assert the routing and the unwired-mount surface; a real launch derives its bindings from configuration in run.

Resolve an Ecosystem to its complete MountBinding, or Nothing when that ecosystem has no adapter wired. The ecosystem selects its path grammar (the Classifier) and its denial renderer (the MountRenderer), and its path prefix is derived from it (prefixFor) rather than configured, so the ecosystem is the single thing that drives the binding (see docs/architecture/hosting.md → Mounts). The composition root supplies the packument-serve dependencies once the per-mount registry set is resolved; Nothing for them leaves the packument route the recognised-but-unserved 501 stub.

npm is the only ecosystem with an adapter; the others have no registry client or renderer, so they resolve to Nothing, a loud miss at the call site rather than a silently half-wired mount.

A registry handle with no backend behind it: every effectful field __refuses loudly__ (a typed RegistryUnconfigured) and every pure parse* field returns Left, so an unconfigured fetch/publish or parse fails explicitly rather than silently returning a fabricated success. It holds the handle slot in the composition root where a configured backend is selected elsewhere.

Build the advisory-sync plan from config: nothing without a configured vulnerability-database bucket; otherwise one CveSyncHandle per configured mount ecosystem, each against its own stable per-ecosystem object key and canonical on-disk path under the OSV data dir. Prepares the data dir (created if missing; stray .tmp downloads from an interrupted run swept) so the sync tasks start clean. Note the readiness consequence: an operator who mounts an ecosystem Pilot does not compile has declared an artifact that never arrives, and the pod honestly never reports ready.

One configured ecosystem's advisory-sync wiring.

The rules' boot-bound capabilities for one mount ecosystem: the CVE lookup borrows through that ecosystem's own slot when the sync plan carries one, and abstains otherwise, so a mount's rules can never read a neighbouring ecosystem's advisory database.

The readiness gate over the sync plan: ready once every configured ecosystem's advisory database has first-synced. The flags flip one way, so readiness never flaps on this; an empty plan (no bucket) is vacuously ready.

The sync tasks' timing: the shipped boot burst over the configured poll interval. The microsecond conversion cannot wrap: the config decoder bounds the interval to [1, maxBound div 1_000_000] seconds.