Kalkasautonomous decisions

Command reference · operator entry

Every mode, every flag, and what a refusal prints.

Five modes run the same product entry: the local decision run, a sourced history run, the service door, one serverless wake, and the merge gate on its own. This page is the reference for that surface — what each mode binds, which flags it requires, and the refusals you can expect instead of a receipt.

The five modesScenario tokensThe failure contract
live:falsesimulation-onlylocal entry pointrefusal names itself

How to read a command

One binary, one mode, then flags.

The published usage names the binary. From the product source you reach the same surface through the Rust toolchain, and nothing else on the command line is interpreted.

usage
kalkas run --domain <sport|quant|financial> [--scenario <name>] [--history <path>]
kalkas source-run --domain sport --source <history.jsonl> [--rows <N>] [--seed <N>] [--cases <N>] [--confidence-floor-bps <N>] [--max-price-bps <N>] [--expect-sha256 <64 hex>] [--rows-out <path>] [--history <path>] [--no-history]
kalkas serve
kalkas serverless-cycle --domain <sport|quant|financial> --tick-receipt <json> --probe <json> --shard-receipts <json> --floor-bps <N> --deflation-bps <N> [--history <path>]
kalkas distributed-merge --shard-receipts <json> --floor-bps <N> --deflation-bps <N>
The published usage text, printed by --help, by no arguments at all, and after any usage error.

EntryReaching the entry from the product source

The usage text names the binary. From a checkout the same surface is reached with cargo run --bin kalkas -- followed by the mode and its flags, which is how every example on this page is written.

ContractA flag is a promise

Everything on this page is the published surface: a flag that is not here does not exist, and a flag that is here does what this page says. A removed flag is refused by name rather than accepted and ignored.

Modes

Five modes, one entry point.

Each mode below carries its own flags, its own required inputs, and one example you can paste. The domain flag selects a sealed corpus; the serverless modes consume receipts minted by their owning authorities.

  1. 01

    One decision run against the sealed corpus the domain module names.

    run

    Binds the domain module to its sealed point-in-time corpus, runs the loop, and prints one receipt. Scenario names exercise a named refusal boundary through the same path instead of a happy path.

    usage · run
    kalkas run --domain <sport|quant|financial> [--scenario <name>] [--history <path>]
    The published usage for this mode: the command as the entry names it, required flags as they are, and optional flags in brackets.
    The flags the run mode accepts, and whether each one is required
    FlagValueRequirementWhat it does
    --domain<sport|quant|financial>RequiredSelects the domain module and therefore the corpus the run may read.
    --scenario<name>OptionalExercises one named boundary instead of the admitted path. Default: act.
    --history<path>OptionalThe local run history a completed run appends to. Default: kalkas.history.
    • The domain flag is required here; the other modes name their own inputs.
    • Scenario tokens are published contract: see the refusal reference for all fifteen.
    example · run
    # The admitted path: every gate passes and the act is simulated
cargo run --bin kalkas -- run --domain sport

# One named boundary, against a history file of your own
cargo run --bin kalkas -- run --domain quant --scenario coverage --history walkthrough.history
    Run from the product source; replace the placeholder values with your own paths and digests.
  2. 02

    A decision run over a chronological history file you supply.

    source-run

    Reads one externally produced racing history, maps its declared pre-off fields onto the sealed corpus row schema, trains on the earlier window, and decides the sampled later window under the print mandate. It never fetches, buys, or writes peer data.

    usage · source-run
    kalkas source-run --domain sport --source <history.jsonl> [--rows <N>] [--seed <N>] [--cases <N>] [--confidence-floor-bps <N>] [--max-price-bps <N>] [--expect-sha256 <64 hex>] [--rows-out <path>] [--history <path>] [--no-history]
    The published usage for this mode: the command as the entry names it, required flags as they are, and optional flags in brackets.
    The flags the source-run mode accepts, and whether each one is required
    FlagValueRequirementWhat it does
    --domain<sport>OptionalThe only domain this mode reads. It defaults to sport, and any other value is refused rather than ignored.
    --source<history.jsonl>RequiredRead-only path to the history file.
    --rows<N>OptionalRow bound applied to the source slice.
    --seed<N>OptionalSampling seed, so the same file and seed decide the same window.
    --cases<N>OptionalHow many sampled later cases to evaluate.
    --confidence-floor-bps<N>OptionalConfidence floor in basis points.
    --max-price-bps<N>OptionalPrice ceiling in basis points.
    --expect-sha256<64 hex>OptionalRefuses to run unless the source matches this digest.
    --rows-out<path>OptionalWrites the mapped rows for inspection.
    --history<path>OptionalHistory file to append to.
    --no-history—OptionalRuns without touching the history file.
    • --history and --no-history are alternatives: one appends, the other keeps the run in memory only.
    • The digest check is the difference between "I read a file" and "I read the file I meant".
    example · source-run
    # One externally produced racing history in, sampled decisions out
cargo run --bin kalkas -- source-run \
  --domain sport \
  --source history.jsonl \
  --rows 384 --cases 16 --seed 7 \
  --expect-sha256 <64 hex of the whole file> \
  --no-history
    Run from the product source; replace the placeholder values with your own paths and digests.
  3. 03

    The service door: health plus the Compute wake, on the platform-injected port.

    serve

    Binds the port the platform injects, runs the boot self-check over the shipped history slice before it answers, and exposes GET /healthz and the Compute wake at POST /internal/compute/cycle. The wake fails closed until signed-tick verification exists.

    usage · serve
    kalkas serve
    The published usage for this mode: the command as the entry names it, required flags as they are, and optional flags in brackets.

    This mode takes no flags. Its runtime facts come from the environment, and an argument is refused rather than ignored.

    • serve takes no arguments. A flag is refused rather than ignored.
    • Health reports whether the process answers; it never reports a decision.
    example · serve
    # The service door on the platform-injected port, over a local slice
PORT=8080 KALKAS_HISTORY_SOURCE=history.jsonl \
  cargo run --bin kalkas -- serve
    Run from the product source; replace the placeholder values with your own paths and digests.
  4. 04

    One wake: consume the authorities’ receipts, gate the candidate, decide.

    serverless-cycle

    Consumes receipts minted by their owning authorities — the Compute tick, the data probe, the shard executions — verifies each one against its schema, seal, audience, and coverage, then merges, gates, and decides. It never synthesizes a receipt or a score.

    usage · serverless-cycle
    kalkas serverless-cycle --domain <sport|quant|financial> --tick-receipt <json> --probe <json> --shard-receipts <json> --floor-bps <N> --deflation-bps <N> [--history <path>]
    The published usage for this mode: the command as the entry names it, required flags as they are, and optional flags in brackets.
    The flags the serverless-cycle mode accepts, and whether each one is required
    FlagValueRequirementWhat it does
    --domain<sport|quant|financial>RequiredThe domain module this wake runs.
    --tick-receipt<json>RequiredCompute tick receipt (v1).
    --probe<json>RequiredData probe status (v1).
    --shard-receipts<json>RequiredShard execution receipts (v1); also carries the shard count.
    --floor-bps<N>RequiredPromotion floor. No implicit default.
    --deflation-bps<N>RequiredDeflation penalty charged before the floor. No implicit default.
    --history<path>OptionalThe local run history a completed run appends to. Default: kalkas.history.
    • A missing, malformed, unsealed, out-of-range, or incomplete receipt fails closed with a named error and prints no metric.
    • --shards was removed: the shard count comes from the receipts themselves.
    example · serverless-cycle
    # One wake: verify the authorities' receipts, gate the candidate, decide
cargo run --bin kalkas -- serverless-cycle --domain quant --tick-receipt tests/fixtures/serverless/tick_receipt.json --probe tests/fixtures/serverless/probe_present.json --shard-receipts tests/fixtures/serverless/shard_receipts_4.json --floor-bps 500 --deflation-bps 100
    Run from the product source; replace the placeholder values with your own paths and digests.
  5. 05

    The merge gate on its own, over receipts you already hold.

    distributed-merge

    Merges the shard receipts, computes the median and the deflated score, and answers whether the candidate is promoted. It prints nothing until every receipt verified.

    usage · distributed-merge
    kalkas distributed-merge --shard-receipts <json> --floor-bps <N> --deflation-bps <N>
    The published usage for this mode: the command as the entry names it, required flags as they are, and optional flags in brackets.
    The flags the distributed-merge mode accepts, and whether each one is required
    FlagValueRequirementWhat it does
    --shard-receipts<json>RequiredThe receipts to merge.
    --floor-bps<N>RequiredPromotion floor. No implicit default.
    --deflation-bps<N>RequiredDeflation penalty. No implicit default.
    • This is the same gate the cycle runs; running it alone is for review, not for a second decision path.
    example · distributed-merge
    # The merge gate on its own, over receipts you already hold
cargo run --bin kalkas -- distributed-merge --shard-receipts tests/fixtures/serverless/shard_receipts_4.json --floor-bps 500 --deflation-bps 100
    Run from the product source; replace the placeholder values with your own paths and digests.

Scenario tokens

Fifteen tokens, one per boundary.

The run mode takes one scenario token. act is the admitted path; every other token exercises one named boundary through the same code path, so a refusal is reproducible rather than anecdotal.

The scenario tokens the run mode accepts, with the boundary each one exercises
TokenBoundaryStage
actAdmitted actEffect
rejectCandidate rejectedCandidate
abstainConfidence too lowMandate and risk
unavailable-evidenceUnavailable evidenceEvidence
invalid-timelineInvalid observation timelineEvidence
oos-leakDevelopment and holdout overlapCandidate
missing-mandateNo mandateMandate and risk
expired-mandateExpired mandateMandate and risk
invalid-mandateInvalid mandateMandate and risk
prohibited-effectProhibited effectMandate and risk
exposure-limitExposure limitMandate and risk
ruin-policyRuin policyMandate and risk
in-sampleIn-sample onlyCandidate
coverageCoverage below floorCandidate
idempotency-conflictIdempotency conflictEffect

This table is the token contract. The trigger behind each boundary, the behaviour to expect, and the receipt lines it changes are in the refusal reference, which owns that detail.

Failure contract

What a refusal prints.

Every refusal in this entry is named and exits non-zero. The table below pairs the trigger with the line you will see, so a failed run is readable without a debugger.

What happened, what the entry prints, and what that leaves you holding
What happenedWhat the entry printsWhat it leaves you
A mode the entry does not knowexpected run, source-run, serve, serverless-cycle, or distributed-mergeThe usage text follows the line, so the whole accepted surface is in front of you.
A flag the mode does not knowunknown argument <the flag you passed>Nothing is guessed and nothing is ignored: an unknown flag stops the run.
A flag that was removed--shards was removed: total_shards comes from --shard-receiptsThe refusal names where the value moved instead of quietly running without it.
A flag with no valuemissing --domain value, missing --source <history.jsonl>, or the same shape per flagThe run stops before reading anything: a half-specified command is never completed for you.
A domain the entry does not knowdomain must be sport, quant, or financialThe accepted list is printed; no closest match is chosen.
A scenario token the entry does not knowscenario must be act, reject, abstain, and the rest of the published listThe tokens are contract, so the run names them rather than approximating.
An argument to the service doorserve takes no arguments, found <the argument>The door reads its facts from the environment; a flag is refused rather than ignored.
A receipt document the mode requires was not suppliederror=missing_required_receipt flag=<the flag>, then what that flag expectsNo metric is printed; the entry never synthesises a receipt or a score.
A gate flag was not suppliederror=missing_required_input flag=--floor-bpsThe promotion gates have no implicit default, so an absent one stops the run.
A receipt document cannot be readerror=receipt_unreadable flag=<the flag> path=<the path> reason=<the read failure>An unreadable document is a refusal, not an empty result.
A document fails its schema, its field law, or its content sealerror=schema_mismatch, error=field_invalid, or error=digest_mismatchThe document is rejected before the merge gate, and no score is reported from it.
A probe reports no object, or an unreachable platformerror=probe_unavailable status=no_probe (or status=platform_objects_unreachable)The cycle requires present evidence; an absent object fails closed before the merge gate.
The merge gate rejects the supplied shard coverageerror=merge_rejected input=<the flag> reason=<the named reason>No score is printed from an unmerged run, and no partial merge is kept.
A run refuses at one of its own gatesentry=kalkas domain=<domain> scenario=<token> live=false error=<named refusal>The refusal names the boundary; the run writes no receipt and appends nothing.
The service door cannot startentry=kalkas mode=serve live=false error=door_start_rejected reason=<the reason>A door that cannot bind or self-check fails closed rather than serving a half-known state.

RuleWhat a refusal never does

  • No metric is printed from an unverified document or a refused gate.
  • No receipt is written for a refusal, and no partial record is appended to the history file.
  • No refusal retries itself: the run stops, and the next attempt is yours.
  • No flag is silently ignored, and no required value is guessed.

AbstainA refusal is a result you can act on

At a gate, refusing is the correct outcome rather than a fault: evidence that arrived late, an expired mandate, coverage below the floor, or a conflicting retry all stop the run because acting anyway would be the defect. The troubleshooting page maps each refusal to what to check before asking for help.

From the command to the receipt.

The receipt reference explains every line a successful run prints and what each one binds. The quickstart walks one run from the command to the receipt it hands back.

Receipt referenceQuickstart