Catalog version history only accrues by observation — a fresh Forge cannot reach older ctl versions

[jgruberf5]

Problem

D-033 version rows are created only by observing a version bump during a sync. A content repo publishes one version at HEAD, so the catalog's version list is a function of how long that Forge has been watching the repo — not of what versions actually exist.

Consequence: a freshly installed bnk-forge syncs bnkctl-index and sees exactly one version. There is no path to deploy a known-good older ctl release. Older versions exist only in the content repo's git history, and nothing reconstructs them.

This is a production problem, not a theoretical one. ctl binaries gain features continuously; an operator hitting a regression wants to redeploy a version that worked. On an established Forge that's possible only by luck of having been synced at the right moment. On a new install it's impossible.

Evidence

mwiget/ocibnkctl has 14 releases. mwiget/bnkctl-index publishes a single pack directory (tools/ocibnkctl/) with one module.version and one pinned digest — every prior version is a git-history commit, not a catalog row.

Observed directly on a live instance. Before sync:

 id |   name    |      path       | version  | is_latest
 64 | ocibnkctl | tools/ocibnkctl | 2.3.1.18 | t

After bumping the index to 2.3.1.19 and re-syncing (modules_created: 1):

 id |   name    |      path       | version  | is_latest
 64 | ocibnkctl | tools/ocibnkctl | 2.3.1.18 | f
 66 | ocibnkctl | tools/ocibnkctl | 2.3.1.19 | t

Two rows — but only because this Forge happened to be running for both. A Forge installed an hour later gets row 66 alone, with 2.3.1.18 unreachable.

Why the current code produces this

The mechanism is working as designed; the design just can't serve the use case.

• backend/services/module_sync_service.py _upsert_pack_module (~1040-1200) — identity is (module_source_id, source_path, version); a bump falls through the existing-row lookups and creates a NEW immutable row. Accumulation is correct but strictly incremental.
• _inactivate_stale_manifest_modules (~1243) prunes by path, not version, so accrued rows survive later syncs. Good — the rows persist once they exist. The gap is purely that they are never created retroactively.
• backend/services/module_version_query.py available_module_versions / recompute_is_latest — the version axis and re-pin action work correctly on whatever rows exist.

See docs/adr/D-033-multi-version-module-catalog.md.

Directions

Not a recommendation yet — the tradeoff is a product call.

A. Index publishes every version. One pack directory per released ctl version, so any fresh sync yields the full set immediately. Works with the sync exactly as written today — zero backend change. Costs repo bloat and publishing discipline in the content repo. Note module.path must equal the pack's directory path, so per-version directories would be distinct source_paths and land as separate modules, not versions of one — this needs design work to avoid fragmenting the version axis.

B. A source type that enumerates upstream releases. The sync reads GitHub releases for the wrapped tool and synthesizes version rows from one pack template. Less duplication and it tracks reality automatically, but it needs a resolvable digest per release and a way to express "these releases map to this pack".

C. Backfill on demand. An action that walks the content repo's git history for a path and materializes the version rows it finds. Recovers history for existing repos without changing the publishing model. Older rows would pin digests carrying known bugs — acceptable, since that is the point, but it should be visible in the UI.

A stopgap available today: re-point a source's git_ref at successive older commits and sync each. Each deposits that commit's version row and they persist. Workable but manual and easy to get wrong.

Open questions

• Should an older version row be selectable for a new deployment, or only for re-pinning an existing module that already ran it?
• How should versions whose runner images have been deleted from the registry be represented — hidden, or shown as unavailable?
• Does option A's per-version-directory problem have a clean answer, or does it force B/C?

Raised by @mwiget after a live deploy: "a user might want to redeploy a known working version on a new bnk-forge that doesn't have the version history built up over time."

---

_{Migrated from sp-prod-field/bnk-forge #482 (opened 2026-07-20; original labels: enhancement). That repository is archived and read-only.
Bare #NNN references in the text above refer to issues and PRs in the original repository, not to numbering here.}

[jgruberf5]

Triaged during the container-runner sweep. No PR from me on this one, on purpose — and I want to be explicit about why, since every other open container-runner issue now has one (#156, #157, #159, #160, #161).

The analysis above is already the design work: three directions (A: index publishes every version; B: a source type that enumerates upstream releases; C: backfill from git history), an honest "not a recommendation yet — the tradeoff is a product call", and open questions that change the implementation materially (is an older row selectable for a new deployment, or only for re-pinning? what happens when a pinned runner image has been deleted from the registry?). Picking a direction and answering those is a product/ADR decision, not something I should invent in a branch and present as a fix. A PR here without that decision would either guess at the product call or implement the stopgap dressed up as a feature.

Two things that would unblock a PR, from having read the sync code:

1. Pick C or B. A has a real problem the issue already spots: module.path must equal the pack directory, so per-version directories land as separate modules and fragment the version axis — fixing that is its own design. C (backfill) needs no content-repo change and recovers history for repos that already exist, which is the stated production case ("a freshly installed bnk-forge"). B is cleaner long-term but needs a digest-per-release resolution story. If I had to recommend, C first — it's the smallest thing that serves the actual complaint.
2. Answer the selectability question. If older rows are re-pin-only, C is mostly _upsert_pack_module walked over git log -- <path> with is_latest=False, plus a UI badge. If they're deployable-new, the "deleted runner image" question has to be answered first or a user can pick a version that can't start.

Happy to take it the moment there's a direction. Until then it would be a guess, and the issue deserves better than that. Leaving the container-runner label — it is about the artifact catalog — and adding enhancement is already there.

[jgruberf5]

Won't fix — closing as not planned.

Keeping the catalog on the current, tested ctl tool version is the expected behavior, not a gap. Version support is the ctl tool's responsibility: each ctl tool supports the versions of BNK that it supports, and BNK Forge deploys the tool the index currently publishes. Forge is not the place to reconstruct or re-offer older ctl releases from a content repo's git history.

So the three directions above (A: publish every version in the index; B: enumerate upstream releases; C: backfill from git history) are all out of scope for Forge. An operator who needs a specific older ctl behaviour should get it from that tool's own release/support story, not from Forge reaching back for it.

The mechanism is working as designed (D-033 immutable rows accrue as versions are observed), and the stopgap noted above — re-pointing a source's git_ref at an older commit and syncing — remains available for anyone who explicitly wants an older row, but it is not something Forge will automate or encourage.

Decision by @jgruberf5; recording it here so the reasoning is on the issue and not just in a conversation.