Module program 

Program-level contract and optimized execution strategies.

This module is the “planner + dispatcher” for JOSIE execution.

It takes a JSON program envelope and selects the fastest safe runtime strategy available for that specific shape.

Strategy tiers, from most specialized to most generic:

1. Fast internal plan (CompiledProgramBody::FastInternal) Pattern-matched kernels for high-frequency pipeline shapes (loop/filter/branching/boolean/match/template/mixed workflow). These avoid per-node dynamic dispatch and run as tight Rust loops.

2. Fast external map plan (CompiledProgramBody::FastExternalMapI64) Specialized host-call flow for: x.a(p1,p2,size) -> for_each x.b(item). Uses typed host callbacks and optional metrics-only execution path.

3. Compiled pipeline VM path (CompiledProgramBody::CompiledPipeline) Pre-compiles do, when, and args expressions to typed IR (Expr) and executes via vm::eval_expr with iterator locals.

4. Generic tree/pipeline fallback Preserves full semantics for any valid document not covered above.

Pipeline step contract summary:

op	required fields	notes
call	fn or from	optional into, args, when
set	into, args[0]	writes to runtime var or client.*/server.*
get	from	reads $prev, runtime vars, or state paths
map/filter/for_each/reduce	from, do	reduce optionally uses init value from args[0]
if/match/do/pipe	args	tree-style ops executed in pipeline flow
policy hints	run_hint	planner/runtime hint (inline/worker), not logic semantics

Why this improves performance:

• Removes repeated parse and shape checks from hot loops.
• Avoids recursive serde_json::Value evaluation in known patterns.
• Uses typed host fast-paths for external-heavy workloads.
• Keeps fallback semantics so optimization is additive, not breaking.

Structs

CompiledPipelineStep

A pipeline step with pre-compiled expressions for fast evaluation.

CompiledProgram

Compiled execution artifact.

ExecutionOutput

Execution result with final value and mutated state.

FastExternalMapPlan

FastInternalPlan

Shape-specialized internal pipeline plan.

HostFunctions

Host function registry used by optimized execution paths.

PipelineDoc

Canonical pipeline document shape (type = "pipeline").

PipelineStep

Canonical pipeline step shape used by parser and executor.

Program

Parsed top-level program envelope.

RuntimeError

Structured runtime error produced during execution.

ValidationError

Structured validation error produced before execution.

Enums

CompiledProgramBody

FastInternalKind

StepOnError

StepRunHint

StepType

Functions

compile_program

Compile a validated program into the most efficient execution body.

execute_compiled_program

execute_compiled_program_external_metrics

Execute compiled program and return (checksum, len) when possible.

execute_compiled_program_with_hosts

Execute a precompiled program with optional typed host function registry.

execute_program

execute_program_with_hosts

Compile + execute in one call.

parse_program

validate_pipeline

validate_program

Type Aliases

HostCallFn

Generic host callback used by pipeline call integration.

HostGenerateI64Fn

Typed generator callback for optimized external map fast-paths.

HostMapI64Fn

Typed mapper callback for optimized external map fast-paths.