Concepts
Because Spiral operates in real time and must respond quickly to tagged input requests, it monitors
its own responsiveness and optimisation capacity, dynamically adjusting how sophisticated the
optimisation is — backing off if it detects slowness, and increasing depth when performance allows.
That sophistication is expressed as the gear, with 11 standard levels (0–10); higher gears give
more comprehensive optimisation. Spiral defaults to gear 0 unless configured otherwise, and the
set command can force a gear for testing.
Quality
Section titled “Quality”DARK_IDLE | IDLE | DARK_RELIABLE | RELIABLE | null
Stops carry a quality metric reflecting confidence in completion timing and location during planning. Quality is usually inferred from current state:
- IDLE — resource is signed on and awaiting work.
- RELIABLE — completion is reliable when every intervening stop (up to the current ARVD or deferred stop) is also RELIABLE.
Discounts can bias placement toward RELIABLE or IDLE positions, while constraints ensure solution
quality only improves through optimisation. The DARK prefix tells the optimiser to apply quality
metrics when responding to whatIf transactions — e.g. keeping high-priority stops stable, or
evaluating whether an on-scene vs alternative resource should handle emerging work without triggering
surrounding replanning.
Skills
Section titled “Skills”"skill": <integer>
Stops, resources and desks can all carry skills. Within stops, skills optionally carry a value expressing the required amount. Resources implement skills in three ways:
- Capability — simple presence or absence.
- Constraint — a fixed capacity amount (e.g. ladder reach in emergency services).
- Capacity — an amount modified by scheduled stops (e.g. transporter availability in logistics).
Solution tiers
Section titled “Solution tiers”Spiral uses solnTiers to control discretionary spend. Four tiers exist:
- STD — contracted, non-discretionary time.
- EXT — discretionary but contractually required time.
- VOL — voluntary, discretionary time.
- SURGE — dynamic call-out or stand-down rostered time.
Solutions at a discretionary tier require at least one affected stop meeting the appropriate
useStby, useVoluntary or useExtended
condition.
"tag": <integer>
Any input transaction can carry a tag, guaranteed to appear in the consequential output. The tag is an arbitrary integer letting the host uniquely identify a transaction (usually just an incrementing number). Tags synchronise the input and output streams and resolve conflicts when host-generated contradictions occur before output is processed.
Voluntary
Section titled “Voluntary”A Spiral stop may be declared voluntary, allowing resources to decline deployment when scheduled.