006 — Execution Queue Engine (v1.0)
WST • PRIVATE • AUDITABLE • HUMAN-FIRST
Purpose
The Execution Queue Engine is the controlled processor that takes accepted intents and advances them into:
transfer.executed
settlement.recorded
fulfillment tracking
It prevents ad hoc execution, bypasses, and silent state changes.
The queue is where agreement stops being potential and becomes system truth.
Core Doctrine
No direct execution from UI
Only READY queue items may execute
Execution must be validated before movement
Execution writes truth
Failures are logged, not hidden
Settlement follows execution, never replaces it
Engine Position in the System
Project
→ intent.created
→ intent.accepted
→ queue item created
→ queue validation
→ transfer.executed
→ settlement hook
→ fulfillment tracking
- Queue Purpose
The queue exists to separate:
human declaration
from
system execution
Why this matters:
prevents accidental movement
allows validation before action
supports retries and failure handling
preserves auditability
- Canonical Queue Location
/portal/_data/execution/queue.ndjson
Optional per-item drill-down:
/portal/_data/execution/by_item/EXQ-....json
- Queue Item Contract
Every queue item should contain:
{
"queue_id": "EXQ-20260417-0001",
"status": "READY",
"intent_id": "INT-20260417-0001",
"project_id": "P-20260416-9NE3A",
"unit_id": "UNIT-001",
"from_member": "WST-M-000002",
"to_member": "WST-M-0000XX",
"charter_no": "WST-CH-US-AR-JONESBORO-001",
"value_class": "service",
"quantity": 1,
"validated": true,
"ready_for_execution": true,
"created_utc": "2026-04-17T15:00:00Z",
"updated_utc": "2026-04-17T15:00:00Z"
}
- Queue Status Model
Allowed statuses:
PENDING
READY
EXECUTING
EXECUTED
SETTLING
SETTLED
FULFILLED
FAILED
VOID
Meaning
PENDING: created but not validated
READY: validated and eligible for execution
EXECUTING: engine is actively processing
EXECUTED: transfer.executed written
SETTLING: waiting on settlement evidence or completion
SETTLED: settlement.recorded complete
FULFILLED: real-world completion confirmed
FAILED: processing failed
VOID: item canceled before execution
- Queue Entry Rules
A queue item may only be created when:
intent.accepted exists
participants are defined
project/unit reference is valid
value class is known
charter scope is known if applicable
Queue creation event
Recommended internal event:
execution.queued
- Validation Rules
Before an item becomes READY, the engine must validate:
Identity
from_member exists
to_member exists if specific target required
Authority
originating seat was valid
charter binding exists where required
Intent
intent.accepted exists
not withdrawn
not already executed
Project linkage
project_id exists
unit_id valid if required
Economic contract
quantity > 0
value_class valid
execution target resolvable
- Validation Output
A validated queue item should explicitly show result:
{
"validated": true,
"validation": {
"intent_ok": true,
"authority_ok": true,
"project_ok": true,
"economic_ok": true
},
"ready_for_execution": true
}
If not valid:
{
"validated": false,
"ready_for_execution": false,
"failure_reason": "missing_charter_binding"
}
- Execution Trigger Rules
Execution may run:
manually by authorized admin/trustee surface
scheduled by engine poller
automatically when item becomes READY
But always through the engine, never directly from form POST into truth.
- Execution Function
Canonical behavior:
READY
→ lock item
→ mark EXECUTING
→ write transfer.executed
→ mark EXECUTED
→ invoke settlement hook
- Locking Rule
To avoid double execution, the engine must lock queue items before processing.
Minimum doctrine:
one item, one processor
no concurrent writes to the same queue_id
lock must expire safely if process crashes
Recommended lock file path:
/portal/_data/execution/locks/{queue_id}.lock
- Execution Output
When successful, engine writes:
transfer.executed
And updates queue item:
{
"status": "EXECUTED",
"executed_utc": "2026-04-17T15:05:00Z",
"uts_cid": "UTS-....",
"transfer_id": "XFR-...."
}
- Settlement Hook
After execution, the engine checks settlement mode.
Internal settlement
If value is internally settled:
write settlement.recorded
mark SETTLED
External settlement
If payment rail is external:
mark SETTLING
wait for verified evidence
then write settlement.recorded
- Fulfillment Hook
If the executed item represents real-world work, the engine tracks fulfillment separately.
This may be:
manual confirmation
uploaded proof
milestone record
After confirmation:
fulfillment.confirmed
Queue item becomes:
{
"status": "FULFILLED",
"fulfilled_utc": "2026-04-17T18:20:00Z"
}
- Failure Handling
If execution fails:
no partial transfer truth
write failure log
mark item FAILED
preserve reason
allow retry only through controlled path
Example:
{
"status": "FAILED",
"failure_reason": "intent_missing",
"failure_utc": "2026-04-17T15:04:00Z"
}
- Retry Rules
Retries are allowed only if:
item is not already EXECUTED
failure reason is resolvable
new validation passes
Retries must increment attempt count:
{
"attempt_count": 2,
"last_retry_utc": "2026-04-17T15:10:00Z"
}
- Anti-Duplicate Rules
The engine must refuse execution if:
same intent_id already produced transfer.executed
queue item already marked EXECUTED
same unit already closed if unit is single-use
This prevents ghost replays.
- Recommended Internal Files
Queue
/portal/_data/execution/queue.ndjson
Locks
/portal/_data/execution/locks/
Failures / logs
/portal/_data/execution/logs/execution_failures.ndjson
Optional processed archive
/portal/_data/execution/archive/
- UI Responsibilities
Project UI may:
create queue candidates
show queue status
show execution result
Project UI may NOT:
directly write transfer.executed
directly write settlement.recorded
That is engine work only.
- City Page Responsibilities
City page may summarize:
queued activity
executed activity
fulfilled work
But it is never the control surface for execution.
- Minimal Engine Functions
Suggested function set:
wst_execution_queue_add(array $payload): array
Create queue item
wst_execution_queue_validate(array $item): array
Run validation checks
wst_execution_queue_lock(string $queueId): bool
Acquire lock
wst_execution_queue_process(array $item): array
Execute one item
wst_execution_queue_mark_failed(string $queueId, string $reason): void
Record failure
wst_execution_queue_settle(array $item): array
Run settlement hook
wst_execution_queue_fulfill(array $item, array $proof = []): array
Record fulfillment
- Minimal Processing Loop
load PENDING/READY items
→ validate
→ mark READY if valid
→ lock first READY item
→ mark EXECUTING
→ write transfer.executed
→ settlement hook
→ unlock
- Example Flow for Your Current System
Project:
Jonesboro Water + Power Pilot
Unit:
Survey local water + power needs
Flow:
intent.created
→ intent.accepted
→ execution.queued
→ READY
→ transfer.executed
→ settlement.recorded (if needed)
→ fulfillment.confirmed
That is the first living project-to-economy pipeline.
- Anti-Drift Rules
No UI-only completion
No direct transfer write from projects page
No settlement before execution
No execution without queue validation
No retry without reason
No silent failure
- Final Principle
The queue is the gate between intention and irreversible truth.
What this unlocks
Once this exists, your system gains:
controlled automation
safe project execution
replay protection
settlement integration
city-level economic reporting