Docs

Docs

Orientation here; the repository holds the authoritative reference: github.com/coherera/quelor.

Quickstart

Install quelord, run it, and call the lease API. The commands below are indicative. The repository README is authoritative. The Go module is github.com/coherera/quelor, licensed Apache-2.0.

# Indicative. The repository README is authoritative.
# Module: github.com/coherera/quelor

go install github.com/coherera/quelor/cmd/quelord@latest
quelord

# AcquireLease before spend.
#   returns ADMIT, DEFER(until, reason), SHED, or DENY
# SettleLease when the work ends.
#   idempotent by lease id; returns declared vs consumed

AcquireLease is the call before spend. SettleLease closes the lease, is idempotent by lease id, and returns declared cost against consumed cost. RenewLease issues the next quantum for a long session and is documented beside them. The first adapter is the GitHub Action. The LiteLLM plugin is second.

Concepts

Quelor admits work against machine resources: API budgets, executor slots, model credit windows, dollar budgets, dependency health. Resource classes are extensible by profile.

Envelope

The work envelope is what a Decider sees.

  • id, the work identity
  • tenant_id, the tenant scope
  • coalesce_key, the key used to collapse duplicate work
  • priority, highest first: operator-directive, release-critical, change, scheduled, maintenance
  • declared_costs, the cost the caller expects to consume
  • deps, dependencies whose health the decision must consider
  • resources, the machine resource classes this work draws on
  • generation, supplied by the caller
  • not_before, the earliest time the work may be admitted
  • opaque payload, passed through and not interpreted by the engine
  • holder_id, the identity of the lease holder

Leases and verdicts

A lease is the grant an admitted caller holds. RenewLease extends it by one quantum. SettleLease closes it.

  • ADMIT grants a lease before spend.
  • DEFER(until, reason) parks the work until the stated time and records why.
  • SHED refuses the start so load can be shed.
  • DENY refuses the start on policy.

Unknown readings are never treated as available. Fail-static is the rule: a missing or stale reading is not spare capacity, and the engine does not fail open.

Failure taxonomy

Settlement is classified deterministically into five classes: resource-exhausted, dependency-unavailable, flaky, real-defect, and unknown. Exhaustion and dependency outages exit degraded. Red is reserved for a real defect.

Modes and wake grants

Mode A is pull with a grant token. You keep the credentials and the queue. The engine decides; your runner spends. Mode B is optional: the engine can hold the work in a queue. A wake grant releases parked work when an event arrives, such as a window reset, a health recovery, or lease expiry. Callers do not stand up a poll.

Decider interface

A Decider implements three operations: Decider.decide, Decider.renew, and RecordOutcome. RecordOutcome reports the settled result back to the Decider. The hot path does not call a model.

What every answer carries

  • decision_ref
  • ruleset_id and ruleset_hash
  • optional expect_ruleset_hash; a mismatch yields ruleset-moved
  • rule_ids
  • readings, each with a freshness mark
  • abstains, the rules that declined to answer
  • trace_id
  • decider_api_version

Answer states

An answer is one of answered, abstained, unavailable, or killed. answered is a verdict. abstained is a deliberate refusal to decide. unavailable means the Decider could not be reached. killed means the Decider was switched off by its kill switch.

On unavailable, the engine applies class policy and stamps the verdict bound-unreachable.

Where a Decider runs

In-process Go is first. An HTTP or gRPC sidecar is next. WASM is later. Rulesets are content-addressed: ruleset_hash is the address of the ruleset bytes.

Reference Decider

The reference Decider is YAML plus bounded CEL. Shadow slots record an additional answer beside the live verdict and do not replace it. One environment variable forces the reference Decider.

Replay and conformance

Replay runs a captured trace through a named Decider. The command below is the interface; the repository README is authoritative for flags.

quelord replay --trace t.jsonl --decider X

X names the Decider under test. The trace is JSONL of prior decisions. Conformance tests in the repository report three badge levels.

  • Engine. The deterministic quelord engine.
  • Adapter. A client adapter, such as the GitHub Action or the LiteLLM plugin.
  • Decider. An implementation of the Decider interface.

Repository docs

Documentation lives in the repository. The README there is authoritative for install commands, engine flags, and Action inputs.

Go module: github.com/coherera/quelor. License: Apache-2.0.