[Backend]: On-chain vs off-chain reconciliation worker for the vault ledger

[grantfox-oss]

The orchestrator keeps an off-chain view of task spend and balances (packages/orchestrator/src/vault-ledger.ts, task-results.ts, orchestrator-store.ts) alongside the authoritative on-chain state in CleverVault. These can drift: a release that succeeded on-chain but whose local write failed, a crash between the two, an RPC timeout that hid a successful settlement, or a manual on-chain action. Today nothing detects or repairs that drift, so the operator has no way to know the local ledger still matches the chain. For a payments system, silent drift is how money goes missing on the books.

Goal

Build a reconciliation worker that treats the contract as the source of truth, diffs it against the local ledger, reports drift, and (in a separate, explicit step) repairs the local records, writing an append-only audit trail of everything it changes.

Requirements and constraints

• Pull authoritative state per task/user/asset from the vault via agent-vault-client.ts (get_task, get_account, get_user_task_infos, token_balance) and compare to the local ledger.
• Two modes: dry-run (report a structured diff, change nothing) and repair (apply fixes). Dry-run is the default; repair must be explicitly requested.
• Every repair writes an append-only audit entry (what changed, old value, new value, on-chain reference, timestamp). Never silently overwrite.
• Idempotent and safe to run on a schedule; a second run with no drift makes no changes.
• Expose results via the metrics/health surface (a reconciliation block: last run, drift count, repaired count) and optionally a GET /reconciliation endpoint.
• Do not attempt to change on-chain state; this worker only reconciles the local view to the chain.

Edge cases

• Local record exists for a task the chain has finalized (reconcile to completed).
• Chain shows spend the local ledger missed (record it, audit it).
• Partial-release drift (local spent behind chain spent).
• A task present on-chain but absent locally, and vice versa.
• Amounts in stroops vs display units (fixed-point correctness).

Acceptance criteria

• Worker computes a structured drift report between local ledger and on-chain state per task/asset
• Dry-run changes nothing; repair mode applies fixes only when explicitly enabled
• Every repair produces an append-only audit record
• Idempotent: a clean second run makes no changes
• Drift/repair counts surfaced via metrics (and/or an endpoint)
• Vitest coverage with fixture chain states vs local states for each drift class, plus an idempotency test
• npm test passes; behavior documented in docs/

Pointers

• packages/orchestrator/src/vault-ledger.ts, agent-vault-client.ts, task-results.ts, orchestrator-store.ts, metrics.ts, server.ts.

Notes for contributors

Comment with your diff model (what fields you compare and how you classify drift) before implementing. See CONTRIBUTING.md.

[Times-stack]

I will Implement a reconciliation worker that fetches authoritative task/account/balance state from agent-vault-client.ts, normalizes fixed-point amounts, and compares it against the local vault ledger. Produce a structured diff for missing tasks, finalized tasks, missed spend, and partial-release drift.
Make dry-run the default and require an explicit repair mode. In repair mode, update only the local ledger and create an append-only audit record containing the old value, new value, on-chain reference, and timestamp—never modify the contract. Make the reconciliation idempotent so repeated clean runs produce no changes.
Expose lastRun, driftCount, and repairedCount through the existing metrics/health surface (and optionally /reconciliation). Add Vitest fixtures for every drift type, dry-run safety, repair auditing, fixed-point conversion, and a second-run idempotency check, then document the reconciliation and repair workflow in docs/.

[grantfox-oss]

🦊 GrantFox — @Times-stack has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #105)
2. Your PR will be reviewed by the clevercon-protocol maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@Times-stack's PR #115 was approved and merged by @Bosun-Josh121.

🏆 @Times-stack: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (484 total points). Track your full progress on GrantFox.

👏 Great work, @Times-stack! Keep contributing to clevercon-protocol.