Report: dol, from delegation traps to a typed boundary-codec architecture (the #86/Option G cycle, complete walkthrough)

[thorwhalen]

dol, from delegation traps to a typed boundary-codec architecture — the complete walkthrough

What this document is. A self-contained report on the 2026-08-10/11 design-and-prototype
cycle around discussion #86: what dol is and
aims for, where its wrapping architecture breaks, the option space we explored, the evidence
we gathered, the six decisions we made (with the options, rationale, and trade-offs for each),
and what remains. Every claim links to its source — issues, discussion comments, ADRs, design
docs, and code — using commit-pinned permalinks, so the links will still point at the right
text years from now. You can hand this document to an agent and ask it to walk you through any
part, drilling into the linked sources for detail.

Pinned states: "pre-work" code links use
2f3aab19
(v0.3.61, the state the studies analyzed); "current" links use
c1a3ac54
(v0.3.63, after PR #88 and
PR #89); s3dol links use
aa16f554.

---

Part I — What dol is, and what it aims for

I.1 The promise

dol ("data object layer") is a pure-Python, zero-dependency
toolkit whose promise is: wrap any storage backend — files, S3, databases, zips, APIs,
plain dicts — behind the built-in Mapping interface, then layer transformations on top and
keep using the result as if nothing changed. The founding statement of intent is
discussion #35, "Present and Future of dol",
which names three principles:

• Domain-oriented — user_store[user_id] = user, with the store responsible for
  serializing/encrypting/dispatching; the caller thinks in domain objects.
• Simple and normalized — CRUD through the Python Mapping protocol (s[k], k in s,
  list(s), del s[k]) instead of a per-backend method zoo.
• Isolated from the data infrastructure — swap a dict for Files for S3 without touching
  business logic.

I.2 The main features (before this work)

• The base hierarchy — Collection → KvReader → KvPersister → Store in
  dol/base.py.
  Store holds the four transform hooks
  (_id_of_key/_key_of_id/_data_of_obj/_obj_of_data, defaulting to identity) and routes
  the Mapping dunders through them.
• wrap_kvs — the heart of the package
  (trans.py#L1899):
  attach key/value transforms (key_of_id, id_of_key, obj_of_data, data_of_obj, plus
  key-aware postget/preset) to any class or instance.
• store_decorator
  (trans.py#L138)
  makes every wrapper usable four ways: class decorator, class factory, instance wrapper,
  parameter-only factory.
• Codecs — Codec/ValueCodec/KeyCodec dataclasses with + composition
  (trans.py#L3608)
  and the ready-made ValueCodecs/KeyCodecs collections.
• Filesystem stores, caching, paths — Files/TextFiles/JsonFiles
  (filesys.py),
  cache_this/cache_vals/store_cached
  (caching.py),
  KeyTemplate/mk_relative_path_store
  (paths.py#L1102).
• An ecosystem: ~76 local dependents, of which 32 import wrap_kvs — the blast-radius
  numbers that gate any change to the core (see the
  architecture map).
  The adapter family includes s3dol,
  mongodol, azuredol,
  sshdol, and more.

I.3 The mechanism underneath: delegation (has-a), via two routes

wrap_kvs(SomeClass) does not return a subclass of SomeClass. It returns a generated
Store subclass holding an instance of SomeClass in self.store and forwarding to it.
Two independent routes do the forwarding:

1. Store.__getattr__
   (base.py#L742)
   — runtime fallback, used by instance-wraps and by
   mk_relative_path_store-built
   classes (which is how dol.Files itself is built:
   filesys.py#L632).
2. DelegatedAttribute descriptors
   (base.py#L252),
   installed one-per-attribute at class-wrap time by
   delegate_to.

Both routes return methods bound to the inner (leaf) object. Keep that sentence in mind;
it is the root of everything in Part II.

---

Part II — The limitations, and the ideal we stated

II.1 The bug family: one root cause, three symptoms

The promise of I.1 holds for the Mapping dunders and fails for everything else. Because
methods are delegated leaf-bound, two symmetric failures arise — consolidated in the
#86 body and the
#83 design study:

Direction	Symptom	Issue
outside → in	a non-Mapping method (url_for, replace, delete_many) receives the outer, unmapped key	#83
inside → out	a wrapped class's own method does self[k] and bypasses the transforms (self is the leaf)	#18
(side effect)	the generated wrapper freezes __signature__, breaking subclass signatures	#6

Nothing raises. Capability detection can't see it (@runtime_checkable Protocols check
presence, not key-correctness). And because there are two delegation routes, every fix
historically had to be applied twice — "the second application is the one people forget"
(#83 study, §5.3).

The scale was measured, not assumed: a 13-package census (indexed from
#83) found the family overwhelmingly latent —
12 survey claims of live damage were refuted — but with real teeth where it does bite:
cosmodol.CosmosItems.replace silently overwrites a different, real document under a key
codec; pydrivedol.GDReader.get_url returns the wrong file's URL and grants permissions on
it. The trigger for the whole cycle was s3dol's measured failure table in
s3dol discussion #14: under a logs/ scope,
url_for signs the wrong object, delete_many(['a.txt']) destroys a root object outside
the scope, and prefixes() leaks a neighboring tenant.

II.2 The other cracks found while looking

• Pickling is broken in most wrap shapes. A 7-case matrix (run for this study) found
  @wrap_kvs-decorated classes, dol.Files, and stacked codec wraps all fail
  pickle.dumps, with one root cause: the generated classes are anonymous or
  name-shadowed (the reduce payload references a class no longer reachable at its dotted
  name — e.g. filesys.py#L632-L641
  where the decorated Files shadows the original).
• Per-layer cost: measured ~420–510 ns per wrap layer per __getitem__ (12× dict at one
  layer, 90× at six), and full iteration 34–42× dict at one layer — each instance-level wrap
  adds two delegation objects, not one.
• Operator-surface leak: dict's __or__/copy/fromkeys get copied as raw delegates —
  wrapped | other returns untransformed inner data silently.
• eq/hash incoherence: Store.__eq__ compares outer (transformed) views while
  Store.__hash__
  hashes the inner store.
• Dead declarative feature: wrap_kvs already ships
  ingoing_key_methods/outcoming_key_methods
  — the embryo of "declare which methods take keys" — but it is untested
  (TODO at trans.py#L2051)
  and verified broken for leaf-defined methods on both wrap routes (its generated body
  calls super(), which never reaches delegated methods).
• Key-scoping corruption (from s3dol's
  ADR-0006):
  dol's shipped prefixed/suffixed key codecs silently corrupt out-of-band keys
  (decode 'z.txt' → ''), and a logs/ scope can surface a neighbor tenant's keys as
  readable and writable.

II.3 The prior option space (A–F) and the blessed answer of the day

The #86 body (and
#83 study §3)
had already priced six options:

Option	One-liner	Verdict then
A — wrapped_self	re-wrap self inside method bodies via a weakref registry (base.py#L350)	shipped, but has a silent lost-reference hole — "a guardrail, not a correctness mechanism"
B — declarative key-method registry	_key_methods = {'url_for': 0}	existing impl broken; "the guard is worth more than the registry"
C — free functions	url_for(store, k) walking the chain	breaks on non-Store layers; "more reliable, not reliable"
D — rebind methods to the wrapper	self = the wrapper	rejected with running-code evidence (#18 doc §4): binds to the innermost layer under stacks; super() crashes; "do not re-propose without new information"
E — capabilities as sibling stores	BucketUrls[k] — route keyed capabilities through __getitem__	correct by construction; adopted by s3dol in ADR-0011
F — is-a wrapping	wrap_kvs(Class) returns a real subclass	"the actual fix", x-large, staged plan in the #18 doc — but commitment was still an open question

II.4 The stated ideal — the carry-forward list

#83 study §5
wrote down what any "great redesign" must deliver. Abbreviated:

1. has-a/is-a is one decision, not several (Key-transform wrappers delegate capability methods with the unmapped key (url_for etc. silently address the wrong object) #83+wrap_kvs will wrap the instance but self of instance is not wrapped #18+Store.wrap breaks the signature of subclasses. #6 are three symptoms of it);
2. a wrapper must be able to express "this method takes a key";
3. the two delegation routes must be unified;
4. key mapping needs an inverse (inward→outward — needed by anything returning keys);
5. resolution helpers must never silently return None;
6. weakrefs are the wrong substrate for correctness — the leaf↔wrapper relation should be strong and structural;
7. non-Store layers exist in the wild — refuse rather than guess;
8. design metric: how many key-taking methods does the design force an adapter to write?
   (azuredol ≈ 0 and is clean.)

And the wish that seeded this cycle had been on the books since 2023: the maintainer's
reading-list comment in #35
lists wrapt's "Proxies and Wrappers"
as material to study "before making any dol re-design choices". Related aspirations sat in
#24 (backend fast-path hooks, e.g. a _filter_
method that filt_iter would consult), #49
(context managers / idempotent connections), and
#46 (dunder-forwarding hooks; stdlib codecs).

II.5 The proposal that started this cycle

The maintainer proposed (2026-08-10; now on record in the
#86 Option G comment):

1. take inspiration from wrapt-style object proxies;
2. wrap incoming/outgoing keys and values in all methods, not just Mapping dunders,
   with codecs hooked up automatically per a specification — e.g. a Protocol class
   annotated with KT/VT;
3. generalize beyond keys/values to any small set of "types of interest";
4. accumulate wrap layers in two flat lists (encoders/decoders) and compile them,
   for speed and validation;
5. take special care that a method calling another method never double-applies a transform.

---

Part III — The work

III.1 Method

The cycle ran as: understand (six parallel deep-reads: wrapt semantics, base.py
delegation, wrap_kvs internals, the prior design docs, s3dol's real needs, and empirical
probes of pickle/isinstance/performance) → design draft → adversarial refute panel
(four independent reviewers briefed to break the draft, with runnable counterexamples) →
prototype → independent code review (a separate adversary on the diff) → decide
(six explicit maintainer decisions). Both adversarial rounds drew blood; the corrections are
flagged inline in the
design doc
(its §12 is the verification log).

III.2 The evidence that shaped the design

On wrapt (verified by running wrapt 2.3.0):

• ObjectProxy gives isinstance/__class__ transparency, attribute passthrough, ~80
  hand-implemented dunders — but inside a wrapped object's method, self is the wrapped
  object. The proxy intercepts only the first hop. wrapt has exactly dol's wrap_kvs will wrap the instance but self of instance is not wrapped #18 hole;
  a proxy on its own fixes nothing about inside→out.
• Pickling refuses loudly by default (NotImplementedError: object proxy must define __reduce__()); a subclass __reduce__ round-trips fine — a posture worth copying and
  improving on.
• The __iter__ regret: one eagerly
  defined dunder permanently poisoned hasattr duck-typing, fixable only via a new base class
  ten years later. Lesson: a proxy must mirror the leaf's capability surface, never
  resurrect a deliberately-missing method (dol's _filt_iter currently does resurrect
  __len__ — same bug class).
• Performance surprise: on CPython 3.12 the pure-Python proxy measured ~5× faster than
  wrapt's C extension for attribute forwarding (~83 vs ~445 ns) — a dependency-free carrier
  costs nothing.

On typing introspection (verified on 3.10 and 3.12): stdlib get_type_hints +
inspect.signature + get_origin/get_args recover, per method, exactly where role
TypeVars occur — bare, Iterable[KT], tuple[KT, VT], Optional[KT], dict[KT, VT],
nested Iterator[tuple[KT, VT]]. No blockers; several version-specific traps (3.10's
implicit-Optional for = None defaults; Callable[[KT], …] hiding roles in a list arg)
were found by the adversarial rounds and are handled.

On s3dol's real needs (from
ADR-0011
and a survey of s3dol/base.py):
the shape vocabulary a real mechanism must express — scalar key args, iterables of keys,
key-keyed dicts, keys in returned iterables (outward mapping — which didn't exist in dol
at all), keys embedded in records and exceptions, key-space-shifting returns (sub(),
handles), cross-keyspace values. Crucially, ADR-0011 had rejected declarative registries
for their silence-by-omission failure mode — so loudness had to be the mechanism, not an
afterthought.

III.3 Option G — the design

A wrap is (leaf, spec, stack) — one proxy object, however many layers. Implemented in
dol/_interface_wrap.py
(private, experimental, stdlib-only), tested in
dol/tests/test_interface_wrap.py
(45 tests). The pieces:

• The spec (InterfaceSpec):
  a Protocol annotated with role TypeVars (KT, VT, or any TypeVar — roles are general),
  compiled per method into "role at path" plans. Mapping dunders are ordinary spec
  entries — no privileged surface (carry-forward item 2 satisfied). A dict form
  ({'__getitem__': {0: 'KT', 'return': 'VT'}}) serves annotation-free use. Roles are matched
  by TypeVar name, not identity — deliberate, because dol itself ships two distinct KT
  objects and identity-matching would silently classify a user's same-named KT as
  "not a key" (found by the panel).
• The stack: a tuple of {role: Codec(encoder, decoder)} layers. Re-wrapping builds a new
  proxy with a copied-and-extended stack over the same leaf — never a wrapper-of-wrapper.
  Compilation fuses encoder/decoder pipelines per role
  (_compile_method_plan).
  Consequences: inner_most_key becomes a total fold; the inverse mapping exists by
  construction (carry-forward 4); the leaf is a strong structural reference,
  w.__wrapped__ (carry-forward 6); stacked wraps pickle by construction (value-based
  __reduce__, no dynamic class in the payload); and per-op cost is one boundary hop at any
  depth — measured 3.6× faster than nested wrap_kvs at depth 6 (675 vs 2426 ns getitem;
  206 vs 700 µs iterating 1000 keys).
• The carrier (InterfaceProxy):
  a generated-and-cached class per (leaf type, spec, surface) containing exactly the
  spec'd methods the leaf actually has — wrapt's lessons (capability mirroring, _self_
  state naming, loud pickling) without its transparency goal. A dunder outside the spec
  simply doesn't exist on the proxy: proxy | other raises TypeError instead of silently
  returning raw inner data.
• Three loudness layers (the ADR-0011 lesson made structural): undeclared public leaf
  attributes (policy-controlled), unannotated parameters inside spec'd methods refuse at
  compile time (UnderAnnotatedSpecError — a spec author who writes url_for(self, k)
  forgot the annotation and k would silently get outer keys), and unsupported shapes refuse
  (UnsupportedSpecShape) — including roles inside Callable[[KT], …] (contravariant
  positions would hand inner keys to outer callbacks) and **kwargs: VT.

The two headline semantic results:

1. No-double-apply is structural, not careful (the proposal's point 5): codecs apply only
   at the proxy boundary and self inside bodies stays the leaf, so internal self.x()
   calls never re-cross the boundary. Verified with a counting encoder: exactly one
   invocation through a spec'd method that internally calls another spec'd method.
2. The boundary invariant with its fine print: a method correct on the bare leaf stays
   correct under the stack — iff the codec laws hold (decoder total + injective on the
   leaf's actual keys; encoder/decoder mutual inverses; container args copied at the
   boundary). The unconditional version was refuted by the panel using dol's own
   suffixed codec on an out-of-band key. The laws are §2.5 of the
   design doc.

And the headline architectural finding (new evidence that corrects the prior corpus):
is-a wrapping does not fix #83 for backend-direct method bodies. A body like
cosmodol.replace that hands its key straight to the backend still receives the outer key
under is-a — hooks on the MRO don't help a body that never routes through them (verified by
panel probe; an is-a hook additionally shadows a leaf that owns its own _id_of_key, the
exact shape of s3dol's S3BucketReader).
So F and G serve disjoint populations — F fixes outer-view bodies (#18), G fixes
leaf-domain bodies (#83) — and #86's option-F verdict "both #83 and #18 disappear" is
retired. This is why Option G is not an interim stand-in for is-a.

III.4 What the adversarial rounds broke (and what was done about it)

The four-lens panel
(§12 rows 6–12) and the independent code review (row 14) produced, among ~30 verdicts:

• w.__wrapped__ is not the Enabling (optional) KeyPath ability to write when path doesn't already exist #16/Making conditional_data_trans better, and generally; recursively applying wrappers #10 write-back boundary — the
  path_set_writeback engine
  needs the raw-scalar surface (leaf plus the value-codec slice of the stack), verified
  by running the real engine both ways. The flat design needs a stack-slicing accessor
  (future work; the draft's "two O(1) accessors" claim was corrected).
• "Dissolves the chain-walking family" is scoped to pure-codec stacks — filt_iter
  changes the key set and cached_keys is stateful; neither is a codec, so mixed
  compositions still nest. The layer vocabulary needs a filter-layer kind (P3).
• The wrap_kvs-subsumption claim (P2) was overclaimed: a layer-i wants_self transform
  today receives the layer-i wrapper, and a layer-i postget observes intermediate keys —
  observable API that a fused pipeline never materializes. P2 is rescoped to
  flat-equivalent configurations with a loud fallback; route 2
  (mk_relative_path_store → Files) migrates separately or not at all.
• The pickle-repair claim was cut down to its true size: the flat __reduce__ fixes the
  stacked-anonymous-class failure by construction, but Files and decorator-form wraps
  fail because the leaf's own class is name-shadowed — a dol-side fix, not a wrapper-side
  one.
• Real bugs in the prototype, found and fixed with regression tests: *keys: KT
  var-positional was silently corrupted (tuple encoded as one key); a 3.10-only failure
  (builtin slots like dict.__getitem__ have no text signature there); dict-form specs
  crashed on unpickle/copy; explicit dunder access (s.__contains__('outer_key')) escaped to
  the leaf and answered in the wrong key domain; iter() on a __getitem__-only proxy
  invented integer-key iteration via the legacy sequence protocol; keyword calls of the fast
  path worked only by parameter-name coincidence; Iterable args were downgraded to one-shot
  maps.
• The rebind rejection was re-examined and re-affirmed on corrected grounds: under a flat
  proxy, rebinding self to the proxy makes internal self-calls re-cross the boundary →
  double-encode (probe-verified) — replacing option D's innermost-binding defect with a
  violation of G's own invariant. The rejection stands; only its premise inventory changed.

III.5 What shipped

• PR #84 and PR #85
  (earlier in the same investigation): export + harden inner_most_key; fix content_url
  and filesys key validation (v0.3.59).
• PR #87: the Key-transform wrappers delegate capability methods with the unmapped key (url_for etc. silently address the wrong object) #83 design study document.
• PR #88 (v0.3.62): the
  Option G design doc
  • the private engine + tests.
• PR #89 (v0.3.63): the six decisions implemented
  (next section).
• Discussion comments tying it together:
  #86 Option G,
  #86 decisions,
  #24,
  #35,
  #49,
  #46.

III.6 The six decisions — options, trade-offs, and what we chose

All decided by the maintainer 2026-08-10; recorded in
design doc §11
and the #86 decisions comment.

Decision 0 — What does wrap_kvs compile to at the endgame?

The biggest fork, forced by the disjoint-populations finding (III.3).

Option	Pros	Cons
Split synthesis ✅	each mechanism serves the population it is uniquely correct for; nothing is left structurally unfixable	two mechanisms to maintain; needs a crisp "which fires when" rule
Flat engine owns everything	one mechanism; universal perf/pickle wins	#18 never structurally fixed — wrapped_self (with its verified silent hole) becomes the permanent answer
Is-a owns everything (the #18 doc Phase 3 as written)	matches the previously blessed plan	verified NOT to fix #83's backend-direct bodies; wrap_kvs users never get flat perf/pickle/inverse-mapping
Defer	more data before committing	the P2/Phase-3 contradiction stays unresolved and blocks planning

Chosen: split synthesis — codec/instance wrapping compiles to the flat engine;
@wrap_kvs class-decoration becomes is-a. Rationale: the two failure populations are
provably disjoint, so a single winner was never available; the split assigns each mechanism
its provable domain.

Decision 1 — Public surface now?

Option	Pros	Cons
Private + facade next ✅	simple gesture never regresses; API can still change after adapter (P1) experience	feedback loop slightly slower
Export now	earlier ecosystem feedback	name + API freeze immediately, before any real adapter has used it
Rename first	a public name is permanent	bikeshedding before evidence

Chosen: private + facade. Shipped in PR #89:
MappingInterface
(the built-in Mapping-shaped spec — deliberately only the six routed dunders; the mixin
methods each need their own vocabulary decision) and
kv_interface_wrap
(wrap_kvs-shaped kwargs — id_of_key/key_of_id/data_of_obj/obj_of_data — compiled
onto the engine), so the one-line gesture is preserved.

Decision 2 — Loudness default for undeclared leaf attributes

The panel's strongest UX finding: wrap-time refusal ('raise') fires on 11 undeclared
publics for a plain dict and 122 for a boto3 client, so users would habitually reach for
'passthrough' — after which omission is silent again ("loud one keystroke deep").

Option	Pros	Cons
'exclude' default ✅	wrap succeeds; every use of an undeclared attribute raises with guidance — refusal at the moment of danger, no habit-forming escape	a capability is hidden until declared (discoverability cost)
Keep 'raise'	maximal, earliest loudness	noise → passthrough-as-habit → silence returns
'raise' + spec generator	keeps strictness, lowers its cost	tooling to build and maintain; still noisy first contact

Chosen: 'exclude', with 'raise' retained as strict mode.

Decision 3 — Typed codecs now?

The codec laws (III.3) are only enforceable if codecs carry type information — which two
in-tree TODOs had already asked for
(trans.py#L3606,
kv_codecs.py#L310).

Option	Pros	Cons
Adopt now ✅	additive; turns the laws from prose into wrap-time seam validation	tags are declarations, not proofs (totality/injectivity remain unprovable statically)
After P1	design informed by real codec populations	the laws stay unenforced meanwhile
Documentation only	zero cost	the invariant's fine print never bites until data corrupts

Chosen: now. Shipped: optional decoded_type/encoded_type on the engine's
Codec,
with _validate_stack_seams
refusing loudly when adjacent layers disagree at their seam; untagged stays unchecked.
Tagging dol.trans.Codec waits for P2 (32-dependent gate).

Decision 4 — eq/hash policy

No member of {__eq__, __hash__, __len__-under-filtering} is derivable from role
mapping, and today's Store is incoherent (outer-view eq, inner-store hash).

Option	Pros	Cons
Outer-view eq, no hash ✅	a Mapping-shaped wrap behaves like a Mapping (wrap == {'a': 1} works); coherent; mutable-mapping convention	eq is O(n); proxies aren't dict-keys (they weren't safely so before either)
Identity semantics	never lies	surprising in tests; a wrap never equals an equal dict
Mirror the leaf	cheap	verified confusing: equal-leaf wraps with different outer views compare equal

Chosen: outer-view eq (when the spec covers __getitem__+__iter__), __hash__ = None.
Store's own incoherence queued for 0.4.

Decision 5 — __class__ transparency (isinstance-as-leaf)

wrapt proves it's feasible; it also changes capability detection and collides with
#5 (wrapper-class control).

Option	Pros	Cons
Opt-in later, with #5 ✅	nothing lies by default; the knob is designed once, with its sibling feature	wrapt-style drop-in scenarios wait
Drop permanently	closes the question	forecloses legitimate uses
Offer the flag now	early experimentation	freezes a knob before #5's design exists

Chosen: off today; co-design with #5.

---

Part IV — Conclusion: what is still ahead

IV.1 The staged plan, as it now stands

P1 — adapter trials (next). The census-family adapters (cosmodol.replace,
pydrivedol.get_url, sshdol.sync_to's siblings, s3dol's url_for) trial
interface_wrap
on their spec-expressible capability surfaces. The governing rule, adopted in the design
doc's §7: spec expressibility is the line — shapes the spec can express may be methods
iff spec'd; shapes it refuses must stay sibling stores, handles, or free functions (this
preserves the "fewest keyed methods" incentive of
#86 §4 and of
ADR-0011).
P1 also owes: the adapter-side reflective conformance helper (the two-desks answer to
"the guard is worth more than the registry"), and a decision on the cheap mitigation of the
P1 enforcement hole — during P0–P1 nothing protects users of the legacy wrap path, so
teaching wrap_kvs to warn when key-wrapping a store whose class declares a spec is worth
considering.

P2 — the split-synthesis build-out. Before any actual wrap_kvs wiring, a
compatibility appendix must answer, in writing: does the facade's product subclass
Store? What does .store return when there is no layer-below object (≥51 lines in dol core
read .store)? Is the #6 signature graft
preserved? Does the engine register the
wrapped_self backref
(today's blessed #18 fix silently degrades to identity on engine-built wraps otherwise —
probe-verified)? How are the two __missing__ paths (leaf-native with inner keys;
Store-level with outer keys) reproduced? And the fire-when rule for the split itself:
exactly which invocation forms of wrap_kvs route to the flat engine vs is-a. The hard
technical constraint to respect: fusion is only semantics-preserving when no inner layer
observes its own domain — inner-layer wants_self/postget/preset need a loud fallback
to nesting.

P3 — the larger vocabulary and the is-a build-out.

• Extend the stack's layer vocabulary beyond role → codec: at minimum a filter-layer
  kind (for filt_iter's key-set change — which would also finally give
  #24's _filter_ fast-path hook a home);
  decide cached_keys separately.
• Build the is-a half of the split for the @wrap_kvs decorator population, folding in the
  newly found hook-collision hazard (a leaf owning _id_of_key gets shadowed by a naive
  is-a hook) and the constraints already listed in the
  #18 staged plan
  (MRO on stacked wraps, dropping Store.__getattr__ on is-a, ABC registration, the
  dependents gate before any default flip).
• The stack-slicing accessor: the #16/#10
  write-back boundary is the leaf plus the value-codec slice of the stack — a derived
  proxy over the same leaf with a stack prefix. Needed before the path/view layers
  (add_path_access,
  _paths_core.path_set_writeback)
  can sit on flat wraps.
• __class__ transparency, co-designed with #5.

IV.2 Known-unsolved issues (the honest list)

1. Under-parameterized annotations are still silent: keys: Iterable (author forgot
   [KT]) is indistinguishable from a deliberately role-free iterable. The unannotated case
   is loud (UnderAnnotatedSpecError); the under-parameterized case remains a review-time
   judgement — exactly where ADR-0011 D5
   put it.
2. Shapes outside the vocabulary (must stay siblings/handles/free functions):
   key-space-shifting returns (sub(), handle-returning methods, #10's territory),
   cross-keyspace values, keys embedded in returned records and exception payloads
   (laziness compounds the latter: the raise site has no boundary frame), untyped operation
   batches, view-dependent no-arg operations (sync_to), replace-the-write strategies,
   pushdown.
3. The pickle root cause dol-side: Files and decorator-form wraps fail because the
   leaf class itself is name-shadowed
   (filesys.py#L632-L641) —
   fixing name-shadowing in dol is its own work item, independent of the wrapper.
4. Mixed old/new stacks: legacy Store layers around/under a flat proxy degrade the
   flat-model guarantees; today the engine warns and treats a legacy Store as an opaque leaf.
   The eventual absorb-or-refuse policy belongs in P2's appendix.
5. Role-name collisions: role matching is by TypeVar name (deliberate — dol ships two
   distinct KT objects), so two genuinely different roles sharing a name is a user
   responsibility.
6. Store's own eq/hash incoherence — queued for 0.4 alongside the decided outer-view
   policy.
7. dol.trans.Codec type tags — decided in principle (Decision 3) but gated on P2's
   32-dependent test gate.
8. The fast path does not enforce the outer signature's arity (the generic bind path
   does) — accepted follow-up, documented in
   design doc §12 row 14.

IV.3 The decision queue (what needs a human)

1. The fire-when rule for the split synthesis (P2, before any wiring).
2. MappingInterface's mixin vocabulary: each of get (default-domain problem), keys()
   (KeysView[KT]), update(**kw) (keyword-names-as-keys) needs its own call before the
   built-in spec can grow.
3. Export timing and final naming of interface_wrap/kv_interface_wrap (after P1).
4. The legacy-path warning (should wrap_kvs consult specs from P1 on?).
5. Sibling-store helper: should dol grow a first-class "derive my codec chain onto a
   sibling store" (= #10) so ADR-0011-style
   siblings stop requiring parallel manual wrapping?

IV.4 One-paragraph summary

dol's core promise — wrap and keep using — held only for the Mapping dunders because
delegation hands every other method the wrong key domain in one direction and the wrong
self in the other. This cycle turned the maintainer's wrapt/typed-spec/flat-compile
proposal into Option G: a spec-carried, flat-compiled, boundary-codec engine that is
loud where the old machinery was silent, picklable where it wasn't, ~3.6× faster at depth,
supplies the long-missing inverse key mapping — and, per the headline finding, is not
made redundant by is-a wrapping, because the two fix provably disjoint populations. Six
decisions now steer the follow-through: split the endgame between the two mechanisms, keep
the engine private behind a simple facade, refuse at the moment of danger, type the codecs,
give Mapping-shaped wraps Mapping equality, and keep __class__ honest until #5 is designed.

---

Appendix — link index

What	Link
The option-space thread (A–G)	discussion #86 · Option G comment · decisions comment
Option G design doc (incl. §11 decision record, §12 verification log)	dol_issue86_design.md
Prior design studies	#83 study · #18 study · #16 study · #10 study · architecture map
Issues	#83 · #18 · #82 · #10 · #16 · #6 · #5
PRs of this cycle	#84 · #85 · #87 · #88 · #89
Context discussions + this cycle's comments	#24 (comment) · #35 (wrapt reading list, comment) · #49 (comment) · #46 (comment)
s3dol sources	discussion #14 · ADR-0011 keyed capability surface · ADR-0006 key scoping · ADR-0005 large-object IO · ADR-0001 layered architecture
The engine (current)	_interface_wrap.py — Codec+tags L151 · InterfaceSpec L297 · _validate_stack_seams L457 · InterfaceProxy L666 · interface_wrap L813 · MappingInterface L958 · kv_interface_wrap L996 · tests
Legacy machinery (pre-work pin)	Store.__getattr__ L742 · DelegatedAttribute L252 · delegate_to L416 · delegator_wrap L491 · wrapped_self L350 · wrap_kvs L1899 · broken *_key_methods L1917 · store_decorator L138 · Codec L3608
wrapt	Proxies and Wrappers