Merge branch 'main' into feat/issue-255-result-schema-migration-guard

Author: usmanimamu17-create

.devcontainer/README.md

@@ -0,0 +1,64 @@
+# Devcontainer Setup
+
+> Reproducible development environment for ApexChainx smart contracts.
+> Works with GitHub Codespaces and VS Code Dev Containers.
+
+## What's Included
+
+| Tool | Purpose |
+|------|---------|
+| Rust (latest) | Contract compilation and testing |
+| `wasm32-unknown-unknown` target | Soroban WASM builds |
+| `just` command runner | One-command dev workflows |
+| Node.js LTS | TypeScript tooling scripts |
+| `cargo clippy` | Linting on save |
+| `rust-analyzer` | IDE support |
+
+## Getting Started
+
+### GitHub Codespaces
+
+1. Click **Code** → **Codespaces** → **Create codespace on main**
+2. Wait for the environment to build (~3–5 minutes first time)
+3. The post-create script runs `just bootstrap` automatically
+4. Run `just ci` to verify everything works
+
+### VS Code (Local)
+
+1. Install [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+2. Open the repo folder in VS Code
+3. Click **Reopen in Container** when prompted
+4. Run `just ci` to verify
+
+## Daily Workflow
+
+```bash
+# Before committing
+just fmt              # Auto-format code
+just lint             # Run clippy
+just check            # Type-check
+
+# Before opening a PR
+just ci               # Full CI pipeline locally
+
+# Fast release validation
+just release-replay   # Minimal validation (fast)
+
+# Generate a release summary
+just release-summary  # From [Unreleased] in CHANGELOG
+```
+
+## CI Parity
+
+The devcontainer mirrors the CI environment (`ubuntu-latest`, Rust stable,
+`wasm32-unknown-unknown` target). Run `just ci` to reproduce the exact
+sequence that CI gates on before opening a PR.
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `cargo: command not found` | Rebuild the devcontainer |
+| WASM target missing | Run `just bootstrap` |
+| `npx` not found | Ensure Node.js feature was installed |
+| Build errors after pull | Run `cargo clean && just ci` |

.devcontainer/devcontainer.json

@@ -28,7 +28,7 @@
       }
     }
   },
-  "postCreateCommand": "rustup target add wasm32-unknown-unknown && cargo install just && just --list",
+  "postCreateCommand": "cargo install just && just bootstrap && just --list",
   "remoteUser": "vscode",
   "containerEnv": {
     "CARGO_TERM_COLOR": "always",

.github/workflows/ci.yml

@@ -167,6 +167,45 @@ jobs:
         run: cargo test --lib fuzz_tests::
 
 
+  parity-check:
+    name: Parity Check (canonical baseline)
+    runs-on: ubuntu-latest
+    # This job is a release gate: it verifies that the current compute_result
+    # implementation produces identical outputs to the locked-in historical
+    # golden vectors in test_snapshots/tests/parity_baseline.json.
+    # A failure here means a calculation regression has been introduced and
+    # must be reviewed before merging or cutting a release.
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@1.94.1
+
+      - name: Cache cargo registry
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            apexchainx_calculator/target
+          key: parity-${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            parity-${{ runner.os }}-cargo-
+
+      - name: Run parity checker against canonical baseline
+        working-directory: apexchainx_calculator
+        run: cargo test --lib parity_tests::
+
+      - name: Upload parity baseline as artifact (for release traceability)
+        uses: actions/upload-artifact@v4
+        with:
+          name: parity-baseline
+          path: apexchainx_calculator/test_snapshots/tests/parity_baseline.json
+          retention-days: 90
+
+
   provenance-hashes:
     name: Provenance & Hashes
     runs-on: ubuntu-latest
@@ -180,25 +219,19 @@ jobs:
         with:
           targets: wasm32-unknown-unknown
 
-      - name: Build WASM release
-        working-directory: apexchainx_calculator
-        run: cargo build --target wasm32-unknown-unknown --release
+      - name: Install just
+        run: cargo install just
 
-      - name: Generate hash
-        run: |
-          WASM=target/wasm32-unknown-unknown/release/apexchainx_calculator.wasm
-          if [ -f "$WASM" ]; then
-            sha256sum "$WASM" | awk '{print $1 "  apexchainx_calculator.wasm"}' > provenance.sha256
-            echo "Hash generated successfully"
-            cat provenance.sha256
-          else
-            echo "WASM file not found at $WASM"
-            exit 1
-          fi
+      - name: Generate and save hash
+        run: just hash-save
+
+      - name: Verify hash against committed file
+        run: just hash-verify
+        continue-on-error: true
 
       - name: Upload artifact
         uses: actions/upload-artifact@v4
         with:
           name: pr-provenance-hash
-          path: provenance.sha256
+          path: artifacts/apexchainx_calculator.wasm.sha256
           retention-days: 30

.gitignore

@@ -10,7 +10,12 @@ apexchainx_calculator/fuzz/artifacts/
 
 
 # Soroban
-test_snapshots/
+# Exclude volatile CI-generated snapshots but keep the committed parity baseline.
+# Note: git negation cannot un-exclude files inside an excluded directory, so we
+# exclude individual subdirectories/patterns rather than the whole test_snapshots/ tree.
+apexchainx_calculator/test_snapshots/tests/*.snap
+apexchainx_calculator/test_snapshots/tests/*.json.tmp
+# Keep parity_baseline.json tracked (no rule excludes it).
 *.wasm
 
 # IDE
@@ -30,6 +35,9 @@ Thumbs.db
 *.tmp
 *.temp
 
+# Node tooling
+node_modules/
+
 # Environment secrets
 .env
 .env.*

CHANGELOG.md

@@ -8,16 +8,38 @@
 
 ## [Unreleased]
 
+### Changed
+- `test_storage_key_namespace_symbols_are_distinct` now covers all 17 on-chain storage key constants (previously omitted `SEVERITY_CALC_COUNTS_KEY`, `SEVERITY_VIOL_COUNTS_KEY`, `LAST_CALCULATION_LEDGER_KEY`, `LAST_VIOLATION_LEDGER_KEY`, and `LAST_CFG_UPDATE_KEY`). The assertion now includes the colliding indices in its error message for faster diagnosis. A maintenance comment listing every key and a pointer to this test was added to both the storage-key block in `lib.rs` and the test itself so future contributors know to update both locations when adding a new key.
+### Fixed
+- Replaced stale `test_zero_threshold_always_violated` test in `threshold_config.rs`
+  with two correct tests that verify `set_config` rejects `threshold_minutes = 0`
+  with `InvalidThreshold` (code 8). The previous test incorrectly assumed a
+  zero-threshold write would succeed and then tested calculation behaviour on an
+  impossible stored state.
+- Hardened `validate_cross_severity_penalty_ordering` in `lib.rs` to use
+  `.ok_or(SLAError::InvalidSeverity)?` instead of `.unwrap()` when indexing
+  into the canonical severity list. The function is now panic-free: if the
+  internal severity list invariant is ever broken the call surfaces a
+  deterministic `InvalidSeverity` error rather than an unrecoverable host trap.
 ### Added
+- `docs/CONTRACT_SHAPE_CHANGE_CHECKLIST.md` — release-readiness checklist for PRs that touch storage keys, `STORAGE_VERSION`, event topic constants, or event payload fields; cross-referenced from `CONTRIBUTING.md` as SC-100
+- **[SC-509] SLAError Addition Workflow** (#253) — comprehensive contributor guide for adding, deprecating, or reviewing `SLAError` variants without breaking backend adapter logic. See `docs/sla-error-additions-guide.md`.
+- `error_responses::is_severity_not_in_set` — typed helper predicate for `SLAError::SeverityNotInSet` (#253)
+- `docs/sla-error-additions-guide.md` — step-by-step guide covering SLAError enum management, the typed helper layer, compatibility expectations, and testing requirements (#253)- `docs/CONTRACT_MAINTENANCE_POLICY.md` — comprehensive maintenance policy covering `#[contracttype]` compatibility notes (#279), response-shape stability (#283), version negotiation (#284), API archetypes (#285), event payload size checks (#286), event drift review (#287), history write audit (#288), telemetry counters (#289), and role-change incident review (#290)
+- `docs/CONTRACT_LIFECYCLE.md` — Mermaid state-transition diagrams for the `apexchainx_calculator` contract lifecycle: top-level lifecycle, pause/unpause, storage migration, config-freeze, admin transfer (two-step), and operator handoff flows; plus the combined orthogonal state matrix and invariants table (closes #256)- `docs/CONTRACT_MAINTENANCE_POLICY.md` — comprehensive maintenance policy covering `#[contracttype]` compatibility notes (#279), response-shape stability (#283), version negotiation (#284), API archetypes (#285), event payload size checks (#286), event drift review (#287), history write audit (#288), telemetry counters (#289), and role-change incident review (#290)- `tooling/release-summary.ts` — release summary generator for maintainers (#280)
+- `.devcontainer/` — reproducible dev container workspace with Rust + WASM target + just + Node.js (#281)
+- `just bootstrap` target — session-safe, idempotent one-command local bootstrap for the Rust WASM contract workflow: verifies rustup, installs the pinned `1.94.1` toolchain with `rustfmt` + `clippy` components, adds `wasm32-unknown-unknown` target, and verifies `cargo` is on `PATH` (closes #257)
 - `docs/CONTRACT_MAINTENANCE_POLICY.md` — comprehensive maintenance policy covering `#[contracttype]` compatibility notes (#279), response-shape stability (#283), version negotiation (#284), API archetypes (#285), event payload size checks (#286), event drift review (#287), history write audit (#288), telemetry counters (#289), and role-change incident review (#290)
 - `RESULT_SCHEMA_FIELD_COUNT` constant — compile-time sentinel recording the number of named fields in `SLAResult`; must be updated alongside `RESULT_SCHEMA_VERSION` when the result layout changes (#255)
 - `SLAResultSchema::result_field_count` — exposes `RESULT_SCHEMA_FIELD_COUNT` to backend consumers via `get_result_schema()` so they can detect layout drift at runtime (#255)
 - `schema_migration_tests.rs` — CI-backed guardrail tests for `get_result_schema()`: exhaustive `SLAResult` destructure (compile-time gate), field count sentinel, symbol stability, deprecated-symbols invariant, and `get_config_bundle` consistency (closes #255)
 - `docs/result-schema-migration-guard.md` — documentation for the result schema migration process, describing the two-level guardrail, step-by-step change process, and backend consumer guidance (closes #255)
+- `docs/EVENT_DRIFT_CHECKLIST.md` — standalone quick-reference event drift review checklist for everyday maintainer use (#287)
 - `tooling/release-summary.ts` — release summary generator for maintainers (#280)
-- `.devcontainer/` — reproducible dev container workspace with Rust + WASM target + just + Node.js (#281)
-- `just bootstrap` target — one-command local environment setup (#281)
-- Historical parity checker test (`test_historical_parity_golden_results`) — validates current contract behavior against known golden results for release regression detection (#282)
+- `scripts/release-replay.ts` — minimal release candidate validation command for fast pre-release checks (#270)
+- `just release-replay` and `just release-replay-full` targets — fast and full release validation (#270)
+- `.devcontainer/` — reproducible dev container workspace with Rust + WASM target + just + Node.js, including setup README (#281)
+- `just bootstrap` target — one-command local environment setup (#281)- Historical parity checker test (`test_historical_parity_golden_results`) — validates current contract behavior against known golden results for release regression detection (#282)
 - `get_config_version_hash` — deterministic hash of the current config snapshot for backend parity validation
 - `get_result_schema` — explicit schema descriptor for SLA result encoding (status, payment type, rating symbols)
 - `calculate_sla_view` — read-only simulation of SLA calculation without state mutation or auth requirement
@@ -46,6 +68,9 @@
 - Event Correlation IDs — cross-contract tracing via deterministic correlation IDs generated by `generate_correlation_id` from ledger sequence and formatted with `correlation_event_topics` (SC-W5-079)
 - Settlement Intent Event (`set_int`) — Published on every `calculate_sla` call alongside `sla_calc` event for backend reconciliation. It uses topics `(set_int, v1, severity)` and payload `(outage_id: Symbol, status: Symbol, payment_type: Symbol, amount: i128, config_version_hash: u64, recorded_at: u64)` (SC-W5-041)
 - `docs/AUDIT_TRAIL.md` — human-readable one-pager cataloguing every event topic, payload field, emission site, and backend recovery implication, sourced directly from `event_schema.rs` and the `EVENT_*` constants in `lib.rs` (closes #106)
+- `docs/PUBLIC_FUNCTION_DOC_POLICY.md` (SC-102) — repository-level policy enforcing doc comments on all public items with compile-time enforcement via `#![deny(missing_docs)]` (closes #214)
+- `docs/UPGRADE_REVIEW_CHECKLIST.md` (SC-103) — admin-facing checklist for safely reviewing contract upgrade proposals (closes #212)
+- `docs/SECURITY_REVIEW_TEMPLATE.md` (SC-104) — standardised security review template for new contract modules (closes #210)
 
 ### Changed
 - `pause` now requires a `reason: String` parameter, records pause metadata (reason, timestamp, initiator), and emits an event payload with the paused status (breaking)