Quickstart · operator entry

Your first verified run, on your own machine.

One command runs the decision loop against a sealed point-in-time corpus and prints one receipt. It is local and simulation-only: nothing is ordered, wagered, transferred, or sent anywhere.

How to read the receipt Watch three boundaries All refusals

live:falsesimulation-onlyno custodylocal only

Before you begin

Nothing to install beyond the product itself.

The entry point reads sealed corpora and checked-in fixtures that ship with the product source. There is no account, no key, and no service to reach.

What you need

The product source and a Rust toolchain. The corpora the domains read are sealed and shipped; the fixtures are checked in.

What it will not do

It will not contact a broker, sportsbook, exchange, or provider, and it will not touch funds or accounts. The shipped effect adapter is simulation-only.

Where it writes

Completed runs append to a local history file, kalkas.history by default or the path you pass with --history. Nothing leaves your machine.

Run it

One entry point, three domains.

The same command runs every domain module. What changes is the module you bind to and the boundary you ask the run to exercise.

shell

# Sport and racing, default scenario
cargo run --bin kalkas -- run --domain sport

# Quant research, one named boundary, and a history file of your own
cargo run --bin kalkas -- run --domain quant --scenario coverage --history runs.history

# Financial analysis
cargo run --bin kalkas -- run --domain financial --scenario missing-mandate

Run from the product source. Each command prints one receipt to standard output.

The flags the run command takes
Flag	What it does
--domain <sport\|quant\|financial>	Binds the run to one domain module and the sealed point-in-time corpus that module reads.
--scenario <name>	Exercises one named boundary through the same path. Defaults to act.
--history <path>	The local history file that completed runs append to. Defaults to kalkas.history.

What it prints

One receipt, one line per field.

The receipt is the artefact: no dashboard summarises it away. The shape below lists the lines the entry point prints for every run, with placeholders where sealed identities, digests, and counts appear.

receipt shape

entry=kalkas
domain=<sport|quant|financial>
scenario=<act, or a named boundary>
pit_repository=<sealed source authority>
pit_commit=<source revision>
pit_protocol=<source row protocol>
pit_corpus_digest=<content seal over the admitted corpus>
promotion=<accepted|rejected|none>
rejection=<named reason|none>
decision=<act|abstain|none>
decision_run_id=<decision identity|none>
abstention=<named reason|none>
effect=<simulation|closed_read_only|none>
effect_receipt=<adapter receipt class|none>
execution_id=<effect identity|none>
settled=<true|false>
evaluated=<true|false>
outcome_bound=<true|false>
learning_bound=<true|false>
replay_verified=<true|false>
north_star=<verified|none>
weekly_verified=<verified runs in this local history, last seven days>
retry_effects=<adapter executions this run recorded; readbacks are not counted>
live=false
ordinary=none private engine, no public web surface
preview=none local product entry, not a hosted runtime

Field shape, not a captured run: the entry point prints one line per field, with the sealed identities, digests, and counts in place of the placeholders.

LimitWhat not to read into it

No line in this receipt is a performance number. promotion, decision, settled, and replay_verified describe what happened on this run, not what any run will earn. The count on the weekly line is a local count of verified completed runs, and the effect lines describe a simulation.

Every receipt field, what it carries, and how to read it
Field	What it carries	How to read it
entry	The entry point that produced this receipt.	One line, one run. Every receipt starts here.
domain	The domain module the run bound to.	Tells you which sealed corpus supplied the evidence.
scenario	The boundary the run exercised.	act for a normal run; otherwise the named boundary you asked for.
pit_repository, pit_commit, pit_protocol	The sealed source: which authority produced the corpus, which revision it was sealed at, and which row protocol it follows.	Provenance for the evidence, printed in full so it can be checked rather than assumed.
pit_corpus_digest	The content seal over the admitted point-in-time corpus.	The same seal in two receipts means the same corpus was read.
promotion	Whether the candidate cleared the promotion gate.	accepted, rejected, or none when the gate was never reached. A rejection stops the run before any decision.
rejection	The named reason a promotion did not happen.	Read it as the binding constraint, for example a coverage floor the candidate did not answer.
decision	The typed outcome of the run.	act, abstain, or none. none means no decision was emitted, which is what a rejection produces.
decision_run_id	The identity of the decision, or none.	This is the identity that settlement binds to. If it is none, there is nothing to settle.
abstention	The named reason the run chose not to act.	An abstention is a result: it carries its reason, settles, and stays in coverage.
effect	The effect class the run used.	simulation, closed_read_only, or none. There is no live variant: nothing external is contacted.
effect_receipt	Which adapter produced the effect receipt.	The receipt class cannot represent a live order, trade, bet, or transfer.
execution_id	The identity of the effect, or none.	Bound to the run, the decision, and the idempotency key that requested it.
settled	Whether the outcome resolved and bound to this run.	true for acted and abstained runs that reached settlement; false when a rejection left nothing to settle.
evaluated	Whether evaluation ran.	Rejections evaluate too: the gate result is recorded even when nothing settles.
outcome_bound, learning_bound	Whether the outcome and the learning receipt bound to this run.	Read with settled. They hold for abstentions as well as acts.
replay_verified	Whether replay reproduced the decision.	true means the recorded decision is the one those inputs produce, and replay called no adapter.
north_star	The verification status of this run.	verified or none. none means the run did not complete a decision to verify.
weekly_verified	The count of verified completed runs in the local history over the last seven days.	A local count over the history file you pointed at. Rejected candidates leave it unchanged.
retry_effects	How many adapter executions this run recorded. Reading the original receipt back is not a new execution, so the count stays put.	This is the idempotency path. A retry with a conflicting request fails closed rather than repeating the effect.
live	The exposure encoding of the run.	Always false today. The shipped adapter has no live path.
ordinary, preview	The product stating its own exposure in words.	No public web surface, and a local entry point rather than a hosted runtime.

Scenario walkthrough

Three boundaries, watched from the outside.

Each command below runs the same path with one named boundary exercised. Read the receipt fields that change, and nothing else changes.

01
Unavailable evidence
evidence
--scenario unavailable-evidence
```
cargo run --bin kalkas -- run --domain sport --scenario unavailable-evidence
```
Trigger
A fact was published after the decision time.
What the run does
Refused before inference. No belief is produced and nothing downstream runs.
What to watch in the receipt
No receipt at all. The entry prints a named fail-closed error and exits non-zero, because the refusal happened before inference: nothing was promoted, planned, or requested from an adapter.
02
Coverage below floor
candidate
--scenario coverage
```
cargo run --bin kalkas -- run --domain quant --scenario coverage
```
Trigger
Out-of-sample coverage falls below the declared floor.
What the run does
Promotion is rejected, with abstentions still counted in the coverage figure.
What to watch in the receipt
promotion=rejected with decision=none and effect=none, evaluated=true, settled=false. Coverage is measured with abstentions included, so sparse answering cannot be hidden, and the weekly verified count stays where it was.
03
No mandate
mandate
--scenario missing-mandate
```
cargo run --bin kalkas -- run --domain financial --scenario missing-mandate
```
Trigger
No authority is presented for the requested effect.
What the run does
Reasoned abstention. No effect intent is emitted, and the run still settles.
What to watch in the receipt
decision=abstain with the missing mandate named as the reason, effect=none, and settled=true, outcome_bound=true, learning_bound=true, north_star=verified. The run refused to act and is still a completed, verified outcome.

The remaining boundaries work the same way: one token, one named refusal. Every token is listed in the refusal reference.

Troubleshooting

When the run does not do what you expected.

Most surprises here are the product working as designed. Each entry below names the reason and what to check next.

The run stops before a belief and prints an error.

That is the fail-closed path, not a crash. Evidence published after the decision time, a development set that overlaps the holdout, or a retry that presents a known idempotency key with a different request all stop the run before inference and before any adapter. Read the named error, change the input, and run again: no partial receipt is written.

The scenario is rejected before anything runs.

The entry accepts only its published scenario tokens and prints the list when it sees anything else. If you are unsure which token shows the boundary you want, read the refusal reference, which maps every boundary to its token.

The domain is rejected.

--domain accepts sport, quant, or financial. Anything else fails closed and prints the accepted list rather than guessing at a closest match.

I expected an act and the run abstained.

Abstention is a complete outcome, not an error. Read the abstention reason and the mandate bounds: an expired mandate, a prohibited effect, or a belief inside the zone where acting is not justified all produce a reasoned abstention rather than an effect request.

The verified count did not move.

weekly_verified counts completed runs that satisfy every condition, in the last seven days, from the history file you pointed at. A rejected candidate never appends as verified. Pass a fresh --history path when you want a clean count for a walkthrough.

A repeated run refuses at the history file.

A retry that presents a known key with a different requested effect fails closed and the original receipt stands, so the effect is never repeated. If you want to run a variant side by side, point --history at a different path.

From one run to the whole contract.

The domain reference explains what each module supplies and what its gates mean. The proof surface explains what makes the receipt you just read a verified outcome.

Domain reference Proof surface