[jeffrey-graham]

What and why

Closes #102

Previously PriceGuard::evaluate returned ts: now on every branch, including Degraded and Halted evaluations that held and returned last_good, and DataKey::LastGood stored only a bare i128 value without recording when that baseline was established. Off-chain monitors, lenders, and the console had no way to measure how stale the held fallback price was from guarded_price() alone.

This change:

• Stores LastGood { value: i128, ts: u64 } under DataKey::LastGood(Address) in PriceGuard, migrating pre-upgrade bare i128 entries via Val + TryFromVal with ts = 0 until the next Ok evaluation or confirm_halt_cleared writes the structured value.
• Returns ts = last_good.ts (0 when no prior good price exists, or rolling_ref_ts if a rolling-reference halt ever falls back to reference without last_good) on Degraded and Halted evaluations, while keeping ts = now when status == PriceStatus::Ok.
• Updates GuardedPrice::ts rustdoc in contracts/common/src/price.rs and documents the LastGood { value, ts } invariant in contracts/AUDIT_NOTES.md.
• Adds unit tests verifying Degraded, Halted, confirm_halt_cleared, and legacy bare-i128 LastGood migration across simulated ledger time advances.

Surfaces touched

• contracts/
• services/ or packages/
• apps/console/
• packages/db schema (migration committed)
• scripts/ or deploy/
• Docs only

Checks run

• pnpm build && pnpm typecheck && pnpm test (TypeScript changes)
• cd contracts && cargo test --workspace (contract changes)
• scripts/e2e-*.sh against a running stack (on-chain behaviour or services/api route changes), or say below why not

CI on GitHub Actions is awaiting first-time contributor workflow approval. Ran locally:

• cd contracts && cargo test --workspace → 261 passed; 0 failed (ballast-price-guard: 67, ballast-common: 29, ballast-registry: 35, ballast-credit-line: 30, ballast-exit-desk: 23, ballast-pledge-vault: 23, ballast-repo-dvp: 52, ballast-integration-tests: 2)
• wasm32v1-none release build → ballast_price_guard.wasm is 84,724 bytes (82.7 KiB), within the 102,400-byte (100.0 KiB) budget across all 6 deployable contracts
• scripts/check-no-mocks.sh and for f in scripts/*.sh; do bash -n "$f"; done → passed (scripts/check-docker-context.sh skipped locally because Docker is not installed on this host)
• scripts/e2e-*.sh not run locally (no local Soroban/Postgres Docker stack running; covered by PriceGuard unit tests across Ok → Degraded → Halted → confirm_halt_cleared and bare-i128 storage migration).

Checklist

• No mock or fake data added outside *.test.ts / __fixtures__/
• No secret, key or credential hardcoded; new config is in .env.example with a comment
• Docs updated if behaviour, setup or env vars changed
• If this touches CreditLine, PledgeVault, RepoDvP or PriceGuard, the reasoning is in the description and contracts/AUDIT_NOTES.md is updated if an assumption changed