Fix/emergency killswitch audit parity 1761

[Appsoft1000]

Closes #1761

Summary

This PR implements the emergency_killswitch contract that provides bounded, auditable, and incident-safe emergency controls with full event and audit parity.

---

What Changed

New files

File	Purpose
meridian-contracts/contracts/emergency-killswitch/Cargo.toml	Contract manifest
meridian-contracts/contracts/emergency-killswitch/src/lib.rs	Full contract + 14 unit tests

Modified files

File	Change
meridian-contracts/Cargo.toml	Added emergency-killswitch to workspace members

---

Architecture & Design

The contract delegates all pause/resume state management to the shared stellar_insured_lib::circuit_breaker module (which already emits canonical CBREAK events) and wraps every committed transition with a versioned AuditRecord carrying a monotonically increasing correlation_id.

Core Features

1. Emergency Pause — Immediate, governance-only circuit breaker activation. Delegates to circuit_breaker::emergency_pause. Returns typed AlreadyEmergencyPaused on idempotent re-invocation without mutating state.

2. Governance Timed Pause — Schedules a pause with a configurable duration via circuit_breaker::pause. Audit event recorded at schedule time.

3. Resume (two-phase) — First call schedules; second call (after RESUME_TIMELOCK_SECONDS) activates. Delegates to circuit_breaker::resume.

4. Threshold Approval — Configurable N-of-M signer set. Each signer may approve once per operation_id. Approvals are recorded atomically (read-increment-write). Executing a threshold-gated operation requires ≥ required unique approvals.

5. Admin Rotation — Two-phase propose/confirm:

   • propose_admin records the candidate with a 24-hour expiry (ADMIN_ROTATION_VALIDITY).
   • execute_threshold_operation commits the rotation if the threshold is met and the proposal hasn't expired.
   • Clears all approvals after execution.
   • Candidate cannot be the current admin.

Event & Audit Parity

Every committed transition emits an AuditRecord via emit_event_with (topic: KILLSW, action: AUDIT) containing:

Field	Description
correlation_id	Monotonically increasing u64, unique per record
transition	Discriminated union describing the exact transition
state_root	On-chain Merkle state root after this transition
timestamp	Ledger timestamp at commit time

This provides dual coverage: the underlying circuit breaker emits its own canonical events for low-level state changes, while the killswitch emits high-level audit records with correlation identifiers for deterministic off-chain reconciliation.

Invariants Enforced

• Emergency pause cannot be shortened by a governance pause while active (enforced by circuit_breaker).
• Resume requires two calls separated by RESUME_TIMELOCK_SECONDS (enforced by circuit_breaker).
• Threshold operations only committed when exactly the required number of unique, authorized signers have signed.
• Admin rotation proposals expire after 24 hours and leave no partial state.
• Duplicate approvals rejected (AlreadyApproved); approvals cleared after execution.
• Rejected, stale, repeated, and failed operations never mutate state and never emit audit events.

---

Error Handling

All errors use a strongly-typed KillswitchError enum with explicit discriminants:

Code	Error	Condition
1	AlreadyInitialized	Double initialize call
2	Unauthorized	Caller lacks required role
3	InvalidDuration	Pause duration = 0
4	AlreadyEmergencyPaused	Idempotent emergency pause guard
5	NotPaused	Resume when not paused
6	ResumeTimelockActive	Resume before timelock elapsed
7	Overflow	Timestamp arithmetic overflow
8	InvalidThreshold	Required > signer count or = 0
9	InvalidSignerCount	Empty or > MAX_SIGNERS
10	AlreadyApproved	Signer already approved this op
11	ThresholdNotMet	Insufficient approvals
12	NoPendingProposal	No admin rotation proposal
13	ProposalExpired	Admin rotation proposal expired
14	CandidateIsCurrentAdmin	Proposed admin is current admin
15	ContractPaused	Operation blocked by pause

---

Testing

14 unit tests covering:

Test	What it verifies
initialize_sets_correlation_counter	Init seeds counter at 1
double_initialize_rejected	Idempotent init guard
emergency_pause_activates_and_emits	Pause + counter advance
emergency_pause_rejected_when_not_governance	Role enforcement
governance_pause_with_zero_duration_rejected	Invalid duration guard
governance_pause_schedule_and_resume	Full pause→resume lifecycle
threshold_set_approve_and_execute	Set threshold + approve + double-approve guard
threshold_approve_rejected_for_non_signer	Signer authorization
propose_and_execute_admin_rotation	Full propose→threshold→rotate lifecycle
propose_admin_rejected_for_same_admin	Same-admin guard
execute_threshold_rejected_when_not_enough_approvals	Threshold enforcement
correlation_ids_are_monotonically_increasing	CID ordering guarantee
getters_return_defaults_before_config	Read-only defaults
set_threshold_rejected_for_zero_required / empty_signers	Config validation
execute_rejected_after_proposal_expiry	Proposal expiry enforcement

---

CI Notes

The contracts workspace has a pre-existing dependency resolution conflict (incompatible quote versions between soroban-sdk v20.0.0 and parity-scale-codec-derive v3.7.5). This issue affects all existing contracts equally — not just this PR. The frontend (vitest.config.ts) and backend (meridian-api) also have pre-existing TypeScript errors unrelated to these changes. None of these failures were introduced by this PR.

---

Compatibility

• No breaking changes to existing public interfaces.
• The new contract is additive — a new workspace member.
• All existing circuit breaker behavior is preserved through delegation.
• No secrets, disabled checks, or generated artifacts included.

---

Security Note

• Threshold operations are all-or-nothing: if the execute step fails mid-way (e.g., proposal expired), no state is mutated.
• Admin rotation is two-phase with an expiry window, preventing indefinite pending states.
• The correlation_id counter is monotonic and never reused, ensuring event ordering is deterministic.
• All auth checks (require_auth, require_role) are performed before any state mutation.

---