Loading
docs(plans): add the Maven version size accounting plan (issue #550)
What
Adds the implementation plan for issue #550 — the Maven slice of ADR-007's artifact-level storage accounting — plus its docs/plans/README.md index row.
Six steps off two roots:
maven_versions.size_bytescolumn, backfill, index — transactional migration (column recurses to the 64 partitions), set-based backfill grouped by version (distinct blobs joined toblob_storage_blobson(namespace_id, sha256)), the size-DESC partial index, regen (structure.sql + jet) and schema-suite updates, plus a migration-level backfill test against seeded data.- Post-commit size maintenance on upload —
MavenVersionStore.RecomputeVersionSize: correlated distinct-blob recompute writeback, emitted after the file-write transaction commits on the store's own connection (noFOR UPDATE, no tx threading throughUploadStore), per ADR-007's buffered counter. The decrement side is recorded as an S28/#472 (closed) dependency — no Maven deleter exists. - Remote twin writer —
AddMavenRemoteVersionSizeBytesmirroring npm's twin (GREATEST-at-zero clamp, off-path semantics); S14 Track B's cache-fill step is the recorded caller. - Artifact-level reconciliation — reuses
RecomputeVersionSize(the same blobs-table walk) called out of band; the direct join is named inApproachas a deliberate deviation from ADR-007's shadow-based example queries (single-version walks issue bounded equality probes, not namespace-wide sums). No S22 dependency. - S17 version size serialization — optional
size_bytesfield on the sharedVersionschema (npm omits it), Bruno + OpenAPI in lockstep. - S10 buffered-column enumeration correction — the seventh column; no mechanism carve-out needed, since the column follows the interim post-commit implementation the section describes.
Decisions made during drafting
- Post-commit recompute-writeback, per ADR-007's buffered counter: the S22 spec's Accounting layers section puts artifact-level accounting entirely out of S22's scope, so its in-transaction sentence describes the layer boundary, not the mechanism; no ADR amendment is needed.
- Remote twin keeps its column and gains the writer (wire, not drop): npm-parity; the issue's done-when clause for that item lands with S14 Track B's fill path.
- Reconciliation joins
blob_storage_blobsdirectly rather than ADR-007'sblob_storage_blobs_by_namespaceshadow: the shadow prunes a namespace-wide sum to one partition, a benefit these single-version walks do not need.
Review
Reviewed via the personae review pass (coherence, feasibility, adversarial, security-lens); all 10 actionable findings folded into the plan, Open Questions empty, links verified against main. Post-draft review feedback (two blocking findings on the maintenance mechanism and the reconciliation size source) folded in via 5d5d209b and a27938c6.
Related to #550 (closed)
Edited by Moaz Khalifa