Skip to main content

The plugin bus & decision precedence

Every intercepted query passes through an ordered plugin bus. Each plugin inspects the parsed statement and emits zero or more Decisions; the bus then merges them with a fixed precedence ladder. Plugins never talk to each other directly — they communicate only through Decision. This keeps the hot path deterministic and every behaviour independently testable and kill-switchable.

The precedence ladder​

  parsed query + fingerprint
    v
  ┌────────────────────────────────────────────────┐
  │ plugins each emit zero or more Decisions:      │
  │ cache / router / rewrite / suspend / attribute │
  └─┬──────────────────────────────────────────────┘
    │  merge by precedence (highest first):
    v
    Veto?              -- yes -->  forward verbatim, skip the rest
    │
    ServeFromCache?    -- yes -->  return cached result
    │
    Route?             -- yes -->  send to an alternate engine
    │
    Rewrite?           -- yes -->  substitute tested SQL
    │
    SetWarehouseSize?  -- yes -->  resize before it runs
    │
    Annotate           ------->   stamp tags / lineage (always)
    │
    v
    forward to Snowflake

Precedence, highest first:

DecisionEmitted byEffect when it wins
Vetoany plugin (determinism gate, safety)force verbatim passthrough; no other decision applies
ServeFromCachecachereturn a verified cached result; skip the warehouse
Routeroutersend to an alternate engine (e.g. embedded DuckDB on an Iceberg replica)
Rewriterewritesubstitute an equivalence-tested SQL rewrite
SetWarehouseSizebandit / suspendadjust warehouse before execution
Annotateattributestamp query tags / lineage; never changes results

Veto always wins — this is how the determinism gate guarantees a non-deterministic query is never served from cache. Annotate is lowest because it is side-effect-only and composes with everything above it.

Why an ordered bus instead of a pipeline​

A naive pipeline would let an earlier plugin's rewrite change what a later plugin sees. The bus instead collects all decisions against the same parsed input, then resolves once. The benefits:

  • Determinism — the same query always produces the same merged decision.
  • Isolation — a plugin panic is contained and treated as fail open; the query still flows.
  • Kill-switchability — each plugin is toggled via CHUKEI_PLUGINS_<NAME>_ENABLED (see configuration) with no code change.

The built-in plugins​

The five P0 plugins map directly onto the cost optimization hierarchy: cache (elimination), router (elimination), rewrite (efficiency), suspend / SetWarehouseSize (efficiency), and attribute (visibility + attribution). Each is documented in the plugin reference.