Add bounded council election contract

[huangminghuang]

Summary

Introduce the sysio.councl system contract, which fills 21 council seats through a deterministic tier-1 → tier-2 → tier-3 nomination and strict-priority voting process.

The contract:

• associates each seat with one frozen tier-1 node owner and lets that owner nominate first;
• escalates failed or timed-out attempts to a selected tier-2 owner, then to non-repeating tier-3 owners;
• elects from three-candidate slates using a greater-than-two-thirds threshold and strict candidate priority;
• preserves completed council rows as generation history; and
• provides a governance backstop when the automatic escalation path is exhausted or must be recovered.

Safety and lifecycle hardening

• Freeze tier snapshots in bounded batches and resume by owner identity so ROA churn cannot corrupt the electorate.
• Cap candidate registration and tier snapshot sizes, validate attempt durations, and bill candidate rows to the registering candidate.
• Replace per-round ballot rows with a bounded vote bitmap and replace linear tier-3 retry tracking with a lazy Fisher–Yates remap.
• Use typed election, initialization, tier, and cleanup phases.
• Treat nomination and voting deadlines as inclusive, while allowing stale nomination/vote actions to settle elapsed state successfully without applying stale input.
• Authenticate public settle and stir callers before incorporating them into the deterministic entropy accumulator.
• Add forceback for governance recovery and staged reset/purge cleanup for all ephemeral generation data.
• Supply Ricardian text for all 13 actions and document the storage, liveness, governance, and entropy tradeoffs.

Tests

Coverage includes:

• candidate RAM billing, removal refunds, handle validation, and the 1,000-candidate cap;
• initialization authorization, tier snapshot completeness, and ROA churn during batched loading;
• tier-1, tier-2, and tier-3 voting and escalation paths;
• duplicate voting, stale actions, exact deadline boundaries, full-turnout failure, and strict-priority resolution;
• authenticated settlement/stirring and governance recovery actions;
• deterministic replay and non-repeating selection across the maximum 1,000-owner tier-3 set;
• cleanup of candidates, roster, tier-2, tier-3, and remap rows while retaining council history; and
• two complete election generations.

Validation

• contracts_project clean build with Wire CDT 4.2.0 from ~/code/wire/wire-cdt/build/release, using -j32
• contracts_unit_test --run_test='council_math_tests,sysio_councl_tests' -- --sys-vm — 38 cases, no errors
• Source ABI/WASM match the build outputs byte-for-byte
• System-contract schema and TypeScript type generation completed successfully
• .clang-format --dry-run --Werror and git diff --check pass
• Complete diff received explicit approval after an independent review/revision loop

Reviewer notes

• Entropy deliberately excludes block number and timestamp. Authenticated callers can still influence ordering by choosing when/who cranks, so selection is deterministic and auditable but not ungrindable.
• Automatic escalation is bounded, but final completion can require governance forceassign; the contract therefore does not promise unconditional wall-clock completion when governance is unavailable.