#198 Catalog retains stale source-file entries when extension version drops a file; no native prune/repair

Summary

.swamp/_extension_catalog.db accumulates rows for source files that an extension removes in a later version. The stale rows continue to participate in model-type resolution and produce intermittent runtime failures ("No such file or directory: .../fetch_kubeconfig.js") and silently-wrong behavior (the older bundle path's logic runs instead of the newer one).

There is no native command to prune the catalog short of swamp extension rm <name> + swamp extension pull <name>, which is heavy-handed and prompts for destructive confirmation. swamp doctor extensions passes ("5 passed, 0 failed — OVERALL: PASS") even though the catalog points at non-existent files.

Reproduction (real, just hit this)

1. Pull @hivemq/harvester/[email protected] — this version ships two files: kubeconfig.ts and fetch_kubeconfig.ts. Both get rows in bundle_types keyed by source path.
2. swamp extension update '@hivemq/harvester/kubeconfig' upgrades to 2026.05.01.38 — this version drops fetch_kubeconfig.ts (logic merged back into kubeconfig.ts). The pulled-extensions directory is rewritten without that file. Bundle dir is rewritten without fetch_kubeconfig.js.
3. bundle_types still has both rows:

('.../kubeconfig.ts',       '@hivemq/harvester/kubeconfig', 'model', '.../bundles/738c72f8/harvester/kubeconfig.js',       '2026.05.01.38', ...)
('.../fetch_kubeconfig.ts', '@hivemq/harvester/kubeconfig', 'model', '.../bundles/738c72f8/harvester/fetch_kubeconfig.js', '2026.04.21.3', ...)

The second source path no longer exists on disk, and its bundle_path no longer exists either.

1. Running swamp model method run <kubeconfig-model> fetch non-deterministically picks one of the two rows. Symptoms:
   • sometimes: FTL error Method execution failed: No such file or directory (os error 2): readfile '.../bundles/738c72f8/harvester/fetch_kubeconfig.js'
   • sometimes: silently runs the v2026.04.21.3 code path (we confirmed this by log-message text — the older bundle's log line Renaming context '{from}' → '{to}' was emitted even though the on-disk bundle for v2026.05.01.38 says Renaming context/cluster/user to '{to}').
2. swamp doctor extensions reports OVERALL: PASS while this is happening.

Why this matters

It looks exactly like a bug in the extension's own logic (the merge of two bundles produces wrong output), so users (and agents) chase the wrong root cause. In our session this consumed ~30 minutes of debugging and led an agent to do rm -rf .swamp/bundles && rm .swamp/_extension_catalog.db* cache surgery before finding the right answer.

Asks (any subset)

1. swamp extension pull / update should prune bundle_types rows whose source_path is not in the freshly-extracted set for the same extension. A version transition that drops a source file is a normal, valid operation; the catalog needs to follow.
2. swamp doctor extensions should detect orphan catalog rows — e.g., bundle_path does not exist on disk, or source_path does not exist on disk. Surface them as warnings/failures with a one-line repair hint.
3. Add a native prune command, e.g. swamp extension reindex <name> or swamp extension repair, that deletes catalog rows for missing files and rebuilds from the pulled-extensions directory tree, without removing the extension.
4. (Stretch) Make resolution deterministic when multiple rows exist for the same (type, kind) — pick the one whose bundle_path exists, or error loudly with a fix-it message instead of silently selecting the broken row.

Environment

• swamp 20260501.010449.0-sha.c24fb601
• Catalog db schema: bundle_meta(key, value), bundle_types(source_path, type_normalized, kind, bundle_path, version, description, extends_type, source_mtime, source_fingerprint)

Related

• systeminit/swamp#1271 — "Document and surface a native cache-refresh path so agents stop doing cache surgery". This issue is the root cause that motivates that one: agents reach for rm -rf because no native repair exists.
• hivemq/swamp-extensions#55 — the bug we were trying to verify a fix for; the stale catalog row made it look like the fix had not landed.

---

Automoved by swampadmin from https://github.com/systeminit/swamp/issues/1272