docs(miner): AMS storage-abstraction research — datastore backend comparison

[lourincedaging0-commits]

Closes #5216.

What

A research-spike comparison document (packages/loopover-miner/docs/ams-storage-abstraction-research.md) evaluating realistic replacement backends for AMS's node:sqlite DatabaseSync local-store, against AMS's actual read/write patterns — not a green-field design.

Method

Enumerated the datastore requirements straight from the stores (local-store.js, portfolio-queue.js, claim-ledger.js, event-ledger.js, run-state.js, governor-state.js), each with a file:line reference — notably the interactive BEGIN IMMEDIATE batchClaim transaction (portfolio-queue.js:334-351), single-statement atomic claims (INSERT … ON CONFLICT / UPDATE … RETURNING), append-only ledgers, PRAGMA user_version migrations, and the existing api_base_url composite-key seam (#5563) as the natural tenant_id insertion point.

Comparison (≥3 options, vs those patterns)

• Managed Postgres (recommended lead) — native interactive transactions (via ORB's pg-adapter.ts runOn(client)), handles batchClaim correctly; SQL differences already covered by pg-dialect.
• Cloudflare D1 (edge-native alternative) — least SQL rewriting (it is SQLite), but no interactive transactions (batch-only), so the read-then-conditional-write claim paths need rework.
• KV / document store — not recommended: a semantic mismatch with AMS's relational atomic-claim core.

Includes a fit matrix, the sync→async migration cost, tenant-scoping fit, and a non-binding recommendation to reuse ORB's existing SqliteDriver seam (src/selfhost/d1-adapter.ts + pg-adapter.ts) rather than invent a new abstraction.

Scope

Docs-only, per the issue boundaries — no schema, storage code, or local-store.js changes; recommendation is non-binding on the maintainer-owned storage-design issue and does not contradict the AMS Cloud Readiness architecture spec.

[superagent-security]

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

[loopover-orb]

Tip

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

✅ LoopOver review result - approve/merge recommended

_{Review updated: 2026-07-14 12:38:37 UTC}

1 file · 1 AI reviewer · no blockers · readiness 95/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This is a docs-only research spike comparing Postgres, D1, and KV as replacement backends for AMS's `node:sqlite` local-store, closing #5216 which explicitly requests exactly this kind of comparison document. The analysis is grounded in real file:line references to the actual store implementations (portfolio-queue.js, claim-ledger.js, local-store.js) rather than a green-field design, correctly identifies the interactive-transaction gap in D1 vs Postgres as the key decision driver, and stays non-binding as scoped. No code, schema, or migration changes are included, so there's nothing to break.

Nits — 5 non-blocking

• Several file:line citations (e.g. `portfolio-queue.js:334-351`, `local-store.js:45-51`, `d1-adapter.ts:20-26`, `pg-adapter.ts:56`) are asserted as fact but unverifiable from this diff alone — worth a spot-check that line numbers still match current source before merging as authoritative documentation.
• The doc claims `pg-dialect` already covers most SQLite→Postgres translation needs but only hedges with 'verify AMS-only constructs' — consider explicitly listing which constructs were actually checked against `pg-dialect`'s implementation versus assumed.
• Consider adding a one-line pointer to where the follow-up maintainer-owned storage-design issue should live/be filed, so the non-binding recommendation has a clear next step.
• If not already done, cross-link this doc from issue Research spike: storage-abstraction candidates to replace AMS's node:sqlite local-store #5216 and from the AMS Cloud Readiness architecture spec mentioned in the intro, to keep the research discoverable.
• Diff looks like trivial or whitespace-only churn — Reduce whitespace-only or formatting-only churn and keep the diff focused on substantive changes.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#5216
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	⚠️ 20/25	Preflight is ready, but the PR body does not name the validation run.
Contributor workload	✅ 10/10	Author activity: 0 registered-repo PR(s), 0 merged, 0 issue(s).
Contributor context	❌ No public Gittensor match	lourincedaging0-commits; not a blocker.
Gate result	✅ Passing	No configured blocker found.
Improvement	⚠️ ℹ️ Insufficient signal	risk: low · value: insufficient-signal — Nothing measurable for the structural-improvement analyzers on this PR (e.g. no code files changed). LLM value judgment: moderate — The document directly closes a maintainer-authorized research-spike issue with a well-grounded, code-referenced comparison that should meaningfully de-risk the follow-up storage-abstraction design work.

Review context

• Author: lourincedaging0-commits
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: HTML
• Contributor context: Public profile only; not a blocker.
• PR-specific overlap: none found.

Contributor next steps

• Add validation command/output.

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.

[BETA] Chat with Gittensory

Ask Gittensory a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @gittensory ask <question> answers contribution-quality Q&A with source citations and freshness.
• @gittensory chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @gittensory mention with a real question is routed to the closest matching read-only command automatically -- no exact syntax required.

Full command reference: https://gittensory.aethereal.dev/docs/gittensory-commands

_{🟩 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 LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[loopover-orb]

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