feat(miner-selfimprove): local prediction-ledger schema

[jeffrey701]

What

Adds packages/gittensory-miner/lib/prediction-ledger.js — an append-only local SQLite ledger that records every predicted-gate verdict the miner computes, so a later self-improve pass can score each prediction against the realized pr_outcome. It mirrors governor-ledger.js's shape (resolvePredictionLedgerDbPath / initPredictionLedger / appendPrediction / readPredictions / closeDefaultPredictionLedger) with the same SQLite-file-resolution convention, close() semantics, and INSERT+SELECT-only immutability invariant. Normalization is local (like event-ledger.js), so the offline miner package pulls in no engine module.

A PredictionLedgerEntry records small, stable rows: id, ts, repoFullName, targetId + optional headSha (join key), the verdict's conclusion / pack / readinessScore, blocker/warning codes only (no free-text detail, so rows stay diffable), and the ENGINE_VERSION that produced the call.

Deliverables

• prediction-ledger.js (+ .d.ts) mirroring governor-ledger.js: resolvePredictionLedgerDbPath(env?), initPredictionLedger(dbPath?), appendPrediction(input), readPredictions(filter?), closeDefaultPredictionLedger().
• PredictionLedgerEntry recording id/ts/repo, the join key (targetId + optional headSha), conclusion/pack/readinessScore, blocker/warning codes, and the producing ENGINE_VERSION.
• CRUD parity with the existing ledgers: same DB-path resolution (GITTENSORY_MINER_PREDICTION_LEDGER_DB → config-dir → XDG → home), same close() semantics, same fail-safe validation (throws on invalid input, corrupted_prediction_row on a bad read).
• Unit tests: db-path resolution, append+read round-trip, a headSha-less clean pass, per-field input validation, and repo-scoped reads.
• README note alongside the sibling ledgers.

Closes #4263

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.96%. Comparing base (ca5576f) to head (e5f4cc6).
⚠️ Report is 31 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4390   +/-   ##
=======================================
  Coverage   93.96%   93.96%           
=======================================
  Files         401      401           
  Lines       36869    36869           
  Branches    13480    13480           
=======================================
  Hits        34644    34644           
  Misses       1569     1569           
  Partials      656      656           

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-09 17:17:34 UTC}

4 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR adds `prediction-ledger.js`, a local append-only SQLite ledger recording predicted-gate verdicts (conclusion/pack/readinessScore + blocker/warning codes + engineVersion) so a later self-improve pass can score predictions against realized outcomes. It faithfully mirrors the existing `governor-ledger.js`/`event-ledger.js` conventions — same DB-path resolution order, same `0o700`/`0o600` permissions, same INSERT+SELECT-only invariant, same field-by-field validation-throws-on-invalid pattern — and closes linked issue #4263. Tests cover db-path precedence, append+read round-trip, a headSha-less clean pass, per-field validation errors, and repo-scoped ordering; CI (including codecov/patch and codecov/project) is green.

Nits — 5 non-blocking

• prediction-ledger.js's rowToEntry has a `corrupted_prediction_row` catch path (bad JSON in blocker/warning code columns) with no test exercising it — governor-ledger.js has the analogous gap too, so this is consistent with existing convention but still worth a test if you touch this file again.
• normalizeReadinessScore (prediction-ledger.js) accepts any finite number with no bound to a sane 0–100 range — worth a comment or a range check if readinessScore is meant to be a percentage.
• The default-ledger wrapper functions (appendPrediction/readPredictions/closeDefaultPredictionLedger) aren't directly exercised by the new test file — only the ledger instance methods are — matching event-ledger.js's test shape but still a coverage gap worth naming.
• Consider a follow-up test that writes a row with malformed blocker_codes_json directly via the db handle to cover the corrupted_prediction_row throw path.
• If readinessScore is a 0–100 percentage like the gate's other pct fields, add an explicit range check in normalizeReadinessScore (prediction-ledger.js) rather than accepting any finite number.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4263
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 96 registered-repo PR(s), 36 merged, 4 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	jeffrey701; Gittensor profile; 96 PR(s), 4 issue(s).
Gate result	✅ Passing	No configured blocker found.

Linked issue satisfaction

Addressed
The PR adds prediction-ledger.js/.d.ts mirroring governor-ledger.js's CRUD/CLI-precedent shape (resolvePredictionLedgerDbPath/initPredictionLedger/appendPrediction/readPredictions/closeDefaultPredictionLedger), stores a PredictionLedgerEntry with id/ts/repoFullName/targetId+headSha join key/conclusion/pack/readinessScore/blocker+warning codes/engineVersion, and includes unit tests covering db-path

Review context

• Author: jeffrey701
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: TypeScript, Clojure, JavaScript
• Official Gittensor activity: 96 PR(s), 4 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[loopover-orb]

Gittensory approves — the gate is satisfied and CI is green.