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:

  1. maven_versions.size_bytes column, backfill, index — transactional migration (column recurses to the 64 partitions), set-based backfill grouped by version (distinct blobs joined to blob_storage_blobs on (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.
  2. Post-commit size maintenance on uploadMavenVersionStore.RecomputeVersionSize: correlated distinct-blob recompute writeback, emitted after the file-write transaction commits on the store's own connection (no FOR UPDATE, no tx threading through UploadStore), per ADR-007's buffered counter. The decrement side is recorded as an S28/#472 (closed) dependency — no Maven deleter exists.
  3. Remote twin writerAddMavenRemoteVersionSizeBytes mirroring npm's twin (GREATEST-at-zero clamp, off-path semantics); S14 Track B's cache-fill step is the recorded caller.
  4. Artifact-level reconciliation — reuses RecomputeVersionSize (the same blobs-table walk) called out of band; the direct join is named in Approach as 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.
  5. S17 version size serialization — optional size_bytes field on the shared Version schema (npm omits it), Bruno + OpenAPI in lockstep.
  6. 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_blobs directly rather than ADR-007's blob_storage_blobs_by_namespace shadow: 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

Merge request reports

Loading
Loading