System health & invariants.
Anything marked LEARN is an intentional stub for Hashirr to hand-implement — core double-entry atomicity, idempotency caching, and the on-chain attribution contract. The rest of the system runs end-to-end.
LEARN #1 — Double-entry ledger atomicity
stubapps/api/src/services/ledger.ts currently writes the three entries (debit agent / credit researcher / credit platform) as three separate inserts. If the process dies between inserts, the ledger becomes unbalanced. Your job is to wrap them in db.transaction() so the debit and both credits are atomic — and to add an assertion at commit time that the sum-of-credits minus sum-of-debits is zero for the affected accounts.
Hint: Drizzle exposes await db.transaction(async (tx) => { … }). Use tx, not db, inside.
LEARN #2 — Idempotency middleware
stubapps/api/src/middleware/idempotency.ts currently only checks for the Idempotency-Key header's existence. Real implementation: look up the key, compare request body hash, and if a completed response exists for that key return it verbatim. Mark rows pending before handling and completed on success — otherwise two near-simultaneous requests race each other.
Hint: the idempotency_records table is already shaped for this.
LEARN #3 — LuqmanAttribution.sol
stubpackages/contracts/src/LuqmanAttribution.sol contains the full event signatures, storage, errors, and 10 Foundry tests — but every function body currently reverts with LearnNotImplemented. Implement registerResearcher and recordRetrievalBatch. Watch the tests pass one by one.
Hint: the tests already encode the 85/15 split, rounding crumb, and reentrancy expectations. Let them drive your implementation.