Load-bearing port from joulesperbit/crates/rce. The substrate
primitive of RCE's discipline: when the foreman resolves an
escalation, it picks a HandlerSpec variant; the substrate
promotes it into a permanent deterministic handler that NEVER
calls a model again for the same query class.
This is where the "compile AI into determinism" actually lives.
jouleclaw-skill::Procedure covers 3 trivial shapes (Constant /
Passthrough / Format); HandlerSpec covers the realistic 10:
Passthrough echo input unchanged
Constant { value } return fixed value
Project { field } extract one field; escalate if missing
Validate { required_fields, on_success }
require fields, descend on success,
escalate on first missing
Wrap { envelope_field }
wrap input in one-field envelope
Pipeline { stages } chain stages; Escalate / Error
short-circuits
AlwaysEscalate{ reason } stub: always send to foreman
AlwaysError { message } circuit breaker
IfHasField { field, then_branch, else_branch }
conditional branching
GeneratedRust { source, fallback }
AI-generated Rust kept for human
review + offline compilation; the
runtime ALWAYS runs the safe `fallback`
interpretive spec — substrate never at
risk of running unaudited code in the
hot path.
HandlerResult three corners (every handler returns one of):
Ok { value } output produced
Escalate { reason, input } send back to foreman
Error { message } bug; surfaces to supervisor
Escalation and Error are DIFFERENT shapes by design — escalations
are routed; errors are crashes. Two distinct words for two
distinct conditions.
CONTRACT
- Determinism: same (spec, input) → byte-identical
HandlerResult.
- content_hash() via canonical (sort-keys) JSON → BLAKE3 hex,
so promoted handler bodies content-address + dedupe.
- kind_name() returns the serialised discriminator tag,
so promotion-history tracking can see "the last 5
promotions for this class were all `validate`."
24 tests:
- one per variant (semantics + edge cases)
- project / validate escalate paths
- pipeline short-circuits on Escalate AND on Error
- pipeline empty-stages identity
- generated_rust always runs the safe fallback
- kind_name covers all 10 variants
- content_hash deterministic across reordered-key JSON,
differs across variants
- HandlerResult helpers (is_ok / is_escalate / is_error /
ok_value)
- full HandlerSpec + HandlerResult JSON round-trips
- realistic compound scenario (validated pipeline that
extracts nested name field, escalates on missing session_id)
cargo check --workspace --all-targets clean.
NEXT IN THE RCE PORT
4. jouleclaw-promotion-path — 9-step typed gate
(PrototypeWritten → SchemaValidated → CurrencyChecked →
RustGenerated → CompilerPassed → PropertyTested →
FormallyVerified → ReasonAttached → Promoted) makes the
promotion discipline auditable. Composes with this crate
(the promoted body IS a HandlerSpec) + jouleclaw-reason
(the "ReasonAttached" gate) + jouleclaw-currency (the
"CurrencyChecked" gate).
Co-Authored-By: Claude Opus 4.7 <[email protected]>
592083890f