Intent record (maintainer, 2026-08-21). The key_of_id / id_of_key / obj_of_data / data_of_obj transform language has confused developers for as long as it has existed, and the earlier outcoming_keys / ingoing_keys alternative never caught on. The horizon we want: {kind}_{encoder|decoder|codec} — key_encoder, key_decoder, value_codec, and so on. This issue records the intent and the migration strategy; it is not the design.
Three vocabularies to reconcile, not one
wrap_kvs's X_of_Y family (key_of_id, id_of_key, obj_of_data, data_of_obj) — the main public surface.kv_wrap's outcoming_keys / ingoing_keys / outcoming_vals / ingoing_vals — the older attempt, still alive in trans.py.- The flat engine's
role -> Codec(encoder, decoder) (dol/_interface_wrap.py) — already the target language. Note wrap_kvs also already accepts key_codec/value_codec sugar, so the target vocabulary has a beachhead on the legacy surface too.
Strategy intent
- Successor surface, not rename-in-place. Write the successor (better design and better name — presumably the flat-engine facade per the Robustly wrapping stores that have key- and value-taking methods #86 Q0 split synthesis), migrate the fleet to it, and keep
wrap_kvs as a back-compat facade implemented over it. Apply the same pattern to the other major surfaces when their turn comes (filt_iter, cached_keys, …).
- Fleet plan. (a) Pin the fleet's commit hashes and baseline test results (the fleet-usage-ledger issue) so back-compat tooling can be tested against a frozen state; (b) migrate the whole fleet to the new language and run every dependent's tests; (c) a breaking change is acceptable with version signaling, plus accommodations (aliases, deprecation warnings, possibly a migration script).
- Scope evidence needed first. The only kwarg-granular data today is a 12-call-site scan across 5 repos — a floor, not a census. The ledger's AST kwarg census is the prerequisite for scoping the break.
- Sequencing / reconciliation. Discussion Robustly wrapping stores that have key- and value-taking methods #86's decision round (recorded in Report: dol, from delegation traps to a typed boundary-codec architecture (the #86/Option G cycle, complete walkthrough) #90) explicitly chose private + facade over rename first — "a public name is permanent; bikeshedding before evidence." This issue does not reopen that: it fixes the destination vocabulary now (new surfaces adopt encoder/decoder from day one, as
_interface_wrap.Codec already does) and defers execution on the legacy surface until the P1 adapter evidence and P2 facade exist.
Definition of done (for this intent issue)
A design doc + plan issue that: names the final vocabulary; enumerates every legacy name it replaces (all three families, underscored Store hooks included); specifies the back-compat mechanism and its sunset; and schedules the fleet migration with the ledger as its test harness. Tracked in misc/docs/dol_roadmap.md.
Intent record (maintainer, 2026-08-21). The
key_of_id/id_of_key/obj_of_data/data_of_objtransform language has confused developers for as long as it has existed, and the earlieroutcoming_keys/ingoing_keysalternative never caught on. The horizon we want:{kind}_{encoder|decoder|codec}—key_encoder,key_decoder,value_codec, and so on. This issue records the intent and the migration strategy; it is not the design.Three vocabularies to reconcile, not one
wrap_kvs'sX_of_Yfamily (key_of_id,id_of_key,obj_of_data,data_of_obj) — the main public surface.kv_wrap'soutcoming_keys/ingoing_keys/outcoming_vals/ingoing_vals— the older attempt, still alive intrans.py.role -> Codec(encoder, decoder)(dol/_interface_wrap.py) — already the target language. Notewrap_kvsalso already acceptskey_codec/value_codecsugar, so the target vocabulary has a beachhead on the legacy surface too.Strategy intent
wrap_kvsas a back-compat facade implemented over it. Apply the same pattern to the other major surfaces when their turn comes (filt_iter,cached_keys, …)._interface_wrap.Codecalready does) and defers execution on the legacy surface until the P1 adapter evidence and P2 facade exist.Definition of done (for this intent issue)
A design doc + plan issue that: names the final vocabulary; enumerates every legacy name it replaces (all three families, underscored
Storehooks included); specifies the back-compat mechanism and its sunset; and schedules the fleet migration with the ledger as its test harness. Tracked inmisc/docs/dol_roadmap.md.