| name | crawfish-determinism-ledger |
| description | Determinism discipline and reading the ledger in Crawfish. Load before running, evaluating, or debugging a component: iterate on the mock (craw dev), carry randomness in --seed, promote to --live under --budget; read results via craw inspect / craw logs and the versioned --json surface.
|
| allowed-tools | Read, Grep, Bash |
Determinism + reading the ledger
Mock by default — promote to live deliberately
- Iterate on the mock.
craw dev <definition> runs against MockRuntime — no live
model call, no spend, fully reproducible. This is where you build and debug.
--seed carries all randomness. A run's randomness lives in --seed (and the
per-call decode_seed), so the same seed replays identically. Two runs with the same
inputs and seed produce the same result.--live is explicit and always budgeted. Promote to a real model call only when you
mean to, and always under a --budget: craw run <definition> --live --budget 5.00.
Never fire --live without a budget — the budget ceiling is the cost-governance gate.
The discipline: build and verify on the mock, then promote one deliberate --live --budget
run. Never iterate by burning live calls.
The --json contract (the integration surface)
Every craw … --json emits a versioned envelope:
schema — the major-only tag, e.g. craw.code.sync.v1 (a minor/additive bump keeps the
tag stable, so old parsers still match).schema_version — { "major": M, "minor": N }.
Parse the cost band from a run's --json:
total_usd — what the run actually spent.expected_usd — the modelled expectation.worst_case_usd — the structural worst-case ceiling the budget binds to.
A budget is sized against worst_case_usd, not expected_usd, so the ceiling can't be
exceeded under live variance.
Where am I / what happened
craw inspect <run> — the run's structured record (inputs, outputs, cost, lineage).craw logs <run> — the scrubbed transcript/event log (no secret value ever appears —
it is redacted through ScrubbingStore before the Store write).craw code map — the whole-project graph: flow-tagged IO, pipeline topology,
consequential sinks (shown as a static-only kind, never a destination).craw code sync — "is the tree healthy and runnable" (runs the assembly gate).
Bash is allowed here because reading the ledger is a craw … --json call (the
CLI-as-contract). Use it to read state; do not use it to fire a --live run without a
--budget.
craw.error.v1 — retryable drives the next move
On failure a craw … --json call emits the craw.error.v1 envelope:
{ "schema": "craw.error.v1",
"code": "fluid_to_static_sink",
"retryable": false,
"remediation": "…static, never echoes a fluid value…",
"detail": { … } }
retryable: true — a transient failure (e.g. tree_busy). Re-running may succeed.retryable: false — stop. Every security rejection is non-retryable
(jail_violation, fluid_to_static_sink, signing_required, consent_required,
schema_skew). Do not loop past it — an injected agent must not be able to retry past a
security gate. Fix the cause (or get human consent), then proceed.
The remediation string is static: it never echoes a fluid/tainted input back into your
instruction stream, so reading an error can never re-inject the attack.
