docs: dol architecture map + issues triage/tackle-order report#71
Merged
Conversation
Adds two code-verified study docs under misc/docs/: - dol_architecture_map.md: module map, internal dependency graph, public API surface, class hierarchy, and a deep dive on the wrap_kvs/store_decorator/codec machinery (incl. the exact signature-conditioning logic behind #9), plus a ranked tech-debt list and notes for dev-skill authors. - dol_issues_report.md: prioritized triage — which open issues are already resolved (#40/#50/#52/#58) and a wave-by-wave tackle order for the rest. Also refreshes issues_and_discussions.md (corrects the #9 root-cause: it is first-parameter-*name* matching, not arg-count; marks Windows/caching issues resolved) and updates the docs index. A local-only ecosystem dependents+usage inventory is generated under misc/data/ (gitignored). Claude-Session: https://claude.ai/code/session_01UpwjDSfDpXWjSgSSubiEiM
This was referenced Jul 2, 2026
…rgIsMapping wrap_kvs decided whether to call a transform as f(data) vs f(self, data) purely by the first parameter NAME (self/store/mapping). This misfired on unary callables whose first param happens to be named 'self' -- e.g. bytes.decode -> TypeError. - _has_unbound_self now also requires >=2 required positional params, so unary builtins like bytes.decode/str.upper are correctly treated as f(data) (#9). - Add explicit opt-in marker FirstArgIsMapping (wired in, was dead code) and a single resolver _resolve_self_convention used by all 4 call sites (_wrap_outcoming, _wrap_ingoing, postget, preset) (#12). Exported from dol. - Regression tests in tests/test_trans.py; new doctests. Backward-compatible: AST scan of dol + 76 dependents found 0 behavior-changing call sites; dependents test-gate (baseline vs modified) showed 0 pass->fail regressions. Also adds dev skill dol-dev-wrap-kvs (machinery + traps + test-gate) and consumer skill dol-store-building, and indexes them + the new misc/docs in CLAUDE.md. Refs #9 #12 #18 #6 Claude-Session: https://claude.ai/code/session_01UpwjDSfDpXWjSgSSubiEiM
Keeps the analysis docs, the consumer skill (dol-store-building), and the CLAUDE index on this branch; the wrap_kvs code change and its dev skill are reviewed separately in PR #72 to keep that behavior change independently reviewable. Claude-Session: https://claude.ai/code/session_01UpwjDSfDpXWjSgSSubiEiM
Member
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Kicks off the "tighten dol" effort with two code-verified study docs (no source changes).
What's here
misc/docs/dol_architecture_map.md— module map + internal dependency graph, public API surface, class hierarchy, and a deep dive on thewrap_kvs/store_decorator/codec machinery (including the exact signature-conditioning logic behindwrap_kvsinconsistencies (due to incorrect signature-based conditioning) #9). Ends with a ranked tech-debt list and "notes for dev-skill authors."misc/docs/dol_issues_report.md— prioritized triage: which open issues are already resolved (re.error: incomplete escape \U at position 2 #40/Stackingcache_thisdecorators #50/Make dol tests windows compatible #52/Make dol tests work on windows. #58 → close) and a wave-by-wave tackle order for the rest.issues_and_discussions.md(corrects thewrap_kvsinconsistencies (due to incorrect signature-based conditioning) #9 root-cause — it's first-parameter-name matching, not arg-count; flags resolved issues) and updates the docs index.Verified during this pass
naming.pyescapes literal template text); Stackingcache_thisdecorators #50 fixed (PR Enable stacking cache_this decorators for cascaded caching #57 + 4 tests); Make dol tests windows compatible #52/Make dol tests work on windows. #58 — Windows CI re-run onmasteris green (28→0).wrap_kvsinconsistencies (due to incorrect signature-based conditioning) #9,Store.wrapbreaks the signature of subclasses. #6, FilesBytesReader not working with tempfiles #3 reproduced against current code.Also done (outside this diff)
wrap_kvs/windows/caching/pathsclusters).misc/data/(gitignored — it names private dependents): dol's 76 dependents, their usages (file:line), and a pre-PR test-gate order.https://claude.ai/code/session_01UpwjDSfDpXWjSgSSubiEiM