[heqmah]

Closes #219
Closes #223
Closes #226
Closes #240

This pull request implements production-grade solutions for four hard contributor issues across the Utix kernel infrastructure:

1. Issue Utix: Create cross-service contract map for domain events and integration boundaries #219: Cross-Service Contract Map for Domain Events and Integration Boundaries

   • Problem Fixed: Previously, cross-service domain events (telemetry.event, worker.job, export.envelope, etc.) lacked a centralized, locked contract registry defining explicit producer/consumer obligations, SemVer rules, and allowed failure behaviors.
   • How Flow Works Now: The authoritative contract map in core/contract/contract-map.ts locks 10 distinct integration boundaries. Each boundary enforces required payload shapes, type validation, SemVer version negotiation, poison-event policies (halt, skip, quarantine), and idempotency requirements. Runtime payloads are validated via validateEventContractPayload() before consumption.
   • Why It Matters: Prevents silent schema drift across decoupled vertical slices, isolates background workers from corrupt event formats, and provides automated CI verification.

2. Issue Utix: Implement feature-flag rollout guard with automatic rollback verification #223: Feature-Flag Rollout Guard with Automatic Rollback Verification

   • Problem Fixed: Deploying high-risk canary features or experimental Soroban RPC diagnostics lacked automated anomaly-triggered rollbacks, leaving systems vulnerable to cascade failures and inconsistent intermediate states.
   • How Flow Works Now: RolloutGuard in core/feature-flags/rollout-guard.ts monitors canary rollouts by risk tier and error thresholds. If consecutive failures (e.g. 3) or error rate limits are breached, it automatically trips the emergency kill switch and immediately triggers post-rollback state verification (StateConsistencyCheck). Any orphaned state (such as stranded running worker jobs) is automatically remediated, verified, and audited.
   • Why It Matters: Guarantees zero residual corruption or inconsistent state post-rollback, enabling safe continuous deployment of risky features.

3. Issue Utix: Implement risk-scored abuse detection for suspicious high-impact operations #226: Risk-Scored Abuse Detection for Suspicious High-Impact Operations

   • Problem Fixed: High-impact or destructive operations (e.g. account merges, zeroing master key weights, burst faucet requests) lacked explainable risk scoring, forcing binary allow/block decisions that risked blocking legitimate users.
   • How Flow Works Now: core/security/abuse-detection.ts evaluates operations against Stellar protocol rules (AccountMerge prerequisites, forbidden self-merges, subentry checks, master key disabling, threshold hierarchy ordering) using a progressive friction model:
     • 0–39 points (allow): Zero friction for legitimate read queries.
     • 40–69 points (step_up): Confirmation challenge (confirm_dialog) for high-impact operations.
     • 70–89 points (review): Maintainer hold for bulk exports and burst faucet usage.
     • 90–100 points (block): Rate-limit backoff for velocity bursts (>20 ops) and oversized XDR payloads (>256KB).
     • Maintainers can inspect and override false positives via overrideAbuseAssessment().
   • Why It Matters: Protects accounts and platform resources from destructive actions and denial-of-service without introducing friction for legitimate developer workflows.

4. Issue utix: Create migration compatibility checks for the next storage schema version #240: Storage Schema Compatibility Checks for Next Storage Schema Version (V2)

   • Problem Fixed: Migrating browser storage from legacy (V1) to the next storage schema (V2) required comprehensive test coverage across normal, failure, retry, and authorization paths to prevent data loss.
   • How Flow Works Now: core/migration/storage-schema.ts provides pre-flight compatibility inspection, bidirectional transformations (upgradeV1ToV2 and downgradeV2ToV1), and SHA-256 tamper-evident integrity checksums across four distinct paths:
     • Normal Path: Valid V1 records upgrade to V2 with schemaVersion: 2, partition isolation, and checksums passing all post-checks.
     • Failure Path: Corrupt or malformed records fail pre-flight inspection; simulated failures trigger reverse downgrade rollback.
     • Retry Path: Idempotent re-execution skips already-upgraded V2 records without duplicate entries or key collisions.
     • Authorization Path: Unauthorized non-maintainers are rejected with permission_denied and audited.
   • Why It Matters: Guarantees lossless, verifiable client storage upgrades with deterministic rollback safety.

Changed

• Utix: Create cross-service contract map for domain events and integration boundaries #219: Created core/contract/contract-map.ts registering 10 cross-service event contracts with schema, versioning, failure, and idempotency policies.
• Utix: Create cross-service contract map for domain events and integration boundaries #219: Added barrel export core/contract/index.ts and automated tests in core/contract/__tests__/contract-map.test.ts.
• Utix: Create cross-service contract map for domain events and integration boundaries #219: Authored comprehensive documentation in docs/EVENT_CONTRACT_MAP.md.
• Utix: Implement feature-flag rollout guard with automatic rollback verification #223: Implemented RolloutGuard in core/feature-flags/rollout-guard.ts for automated tripping and post-rollback state remediation.
• Utix: Implement feature-flag rollout guard with automatic rollback verification #223: Added barrel export core/feature-flags/index.ts and documentation in docs/ROLLOUT_GUARD_AND_ROLLBACK.md.
• Utix: Implement risk-scored abuse detection for suspicious high-impact operations #226: Implemented risk scoring engine in core/security/abuse-detection.ts with progressive friction and Stellar protocol validation.
• Utix: Implement risk-scored abuse detection for suspicious high-impact operations #226: Added barrel export core/security/index.ts and documentation in docs/ABUSE_DETECTION.md.
• utix: Create migration compatibility checks for the next storage schema version #240: Implemented core/migration/storage-schema.ts covering normal, failure, retry, and authorization migration paths with SHA-256 integrity checksums.
• utix: Create migration compatibility checks for the next storage schema version #240: Updated core/migration/index.ts barrel export and authored documentation in docs/STORAGE_SCHEMA_MIGRATION.md.
• Utix: Create cross-service contract map for domain events and integration boundaries #219, Utix: Implement feature-flag rollout guard with automatic rollback verification #223, Utix: Implement risk-scored abuse detection for suspicious high-impact operations #226, utix: Create migration compatibility checks for the next storage schema version #240: Created automated verification test suite in scripts/verify-issues-219-240.mjs and registered npm run verify:issues-219-240 in package.json.
• Core Tooling: Updated scripts/loader.mjs with Node 18 backwards compatibility and added scripts/shims/util.mjs.

[drips-wave]

@heqmah Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits