dualdict 0.1.0a1__tar.gz

dualdict-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anjani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dualdict-0.1.0a1/MANIFEST.in

@@ -0,0 +1,12 @@
+include README.md
+include LICENSE
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include tests *.py
+recursive-include benchmarks *.py *.md
+prune benchmarks/versions
+prune benchmarks/comparisons
+recursive-include cpp *.md *.toml *.txt *.py *.cpp
+include cpp/LICENSE
+prune cpp/dist
+prune cpp/build

dualdict-0.1.0a1/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: dualdict
+Version: 0.1.0a1
+Summary: Bidirectional mapping with live tuple field proxies
+License: MIT License
+        
+        Copyright (c) 2026 Anjani
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Keywords: bidirectional,mapping,tuple,live-proxy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: benchmark
+Requires-Dist: bidict==0.24.1; extra == "benchmark"
+Dynamic: license-file
+
+# DualDict
+
+Experimental bidirectional mapping with unique keys and values. Live handles follow
+a record through endpoint replacement and tuple-field edits. Deleting a record
+permanently invalidates its handles, even if its old key is inserted again.
+
+This is an alpha personal project under the MIT License. APIs may change.
+Development is intermittent; no support or release schedule is promised.
+
+## Installation
+
+Once this version is published on PyPI:
+
+```sh
+python -m pip install dualdict==0.1.0a1
+```
+
+The default implementation is pure Python, requires Python 3.10+, and needs no
+compiler. Source-build CI exercises Python 3.10, 3.12 and 3.14 on Windows, Linux and
+macOS; this is not a claim that every intervening version or platform was tested.
+
+The optional native distribution is installed separately:
+
+```sh
+python -m pip install dualdict-cpp==0.3.3a1
+```
+
+The initial native wheel targets **Windows x64, GIL-enabled CPython 3.12**. Other
+configurations require a source build with a C++17 toolchain and Python development
+headers (MSVC Build Tools on Windows). Isolated builds obtain CMake, nanobind and
+other declared build dependencies. Source CI covers Windows, Linux and macOS but
+does not provide a complete wheel matrix. Native code supports the main interpreter
+only; free-threaded Python, PyPy and subinterpreters are unsupported.
+
+## Python example
+
+```python
+from dualdict import DualDict
+
+d = DualDict([(101, ("Alice", "Engineering"))])
+employee = d.by_key[101]  # live handle
+employee[1] = "Research"
+assert employee.snapshot() == ("Alice", "Research")
+assert d.by_value[("Alice", "Research")].snapshot() == 101
+```
+
+## Optional native API
+
+```python
+from dualdict.v331_cpp import DualDict
+
+d = DualDict([(101, ("Alice", "Engineering"))])
+before = d.by_key[101]  # raw endpoint
+employee = d.by_key.live(101)
+d.by_key.set_field(101, 1, "Research")
+assert before == ("Alice", "Engineering")
+assert employee.snapshot() == ("Alice", "Research")
+assert d.by_value[("Alice", "Research")] == 101
+```
+
+Backend selection is explicit. Installing the native package does not change
+`from dualdict import DualDict`. Python indexed reads return live proxies; native
+V3.3.1 indexed reads return raw endpoints. `view.snapshot(key)` returns a raw
+endpoint in both APIs. Snapshots do not follow replacements and do not copy objects.
+
+## Semantics and limitations
+
+- Both endpoints must be hashable with stable, non-raising, non-reentrant hash and
+  equality behavior for their entire stored lifetime, including tuple members.
+  Do not externally mutate fields used by hash/equality. Equal objects collide.
+- `add` rejects duplicate keys or values, including identical pairs. Assignment
+  inserts or replaces an endpoint but rejects another record's endpoint.
+- Tuple-field edits require a plain tuple; nested edits, slices and deletion of
+  individual fields are excluded. Equal replacement retains the original object.
+- Deletion and clear invalidate handles. Handles retain their mapping owner.
+- `CollisionError`, `KeyError`, `TypeError` and `DeletedRecordError` report
+  collisions, missing lookups, invalid inputs and stale handles respectively.
+- Bulk operations commit one entry at a time. Multiple calls are not transactions
+  and require application synchronization when shared. Hostile callbacks and
+  asynchronous interruption do not have transaction-level guarantees. A native
+  owner that cannot restore indexes after rollback failure disables itself and
+  must be discarded.
+- Average lookup is O(1), excluding hash/equality cost. Tuple edits reconstruct
+  and hash an O(width) tuple. Benchmarks are workload-specific; no universal
+  speedup, memory saving or production-grade security assurance is claimed.
+
+## Documentation, examples and reproducible benchmarks
+
+The Python **source archive** includes `README.md`, `docs/`, `examples/`, `tests/`
+and `benchmarks/`, including benchmark methodology in `benchmarks/README.md`.
+These are not installed as runtime modules by the wheel. No public GitHub checkout
+is required: download and extract the source archive from this version's package
+files, then run these commands from the extracted directory:
+
+```sh
+python -m pip install ".[benchmark]"
+python -m pip install dualdict-cpp==0.3.3a1
+python -m examples.employee_directory
+python -m examples.employee_directory --backend v331
+python -m benchmarks.bidict_v331 --access random --seed 331
+python -m benchmarks.bidict_v331 --access skewed --seed 331
+```
+
+Native comparisons require the optional native package and a production build
+without allocation-failure hooks. The benchmark extra pins `bidict==0.24.1`.
+Reports record environment, configuration, exact timing statements and raw samples.
+Random and skewed runs measure different access patterns; results do not establish
+application-wide performance. Consult the included methodology before comparing.

dualdict-0.1.0a1/README.md

@@ -0,0 +1,170 @@
+# DualDict
+
+DualDict is an experimental bidirectional mapping with unique keys and values.
+Its live handles follow a record through endpoint replacements and tuple-field
+edits. Deleting a record permanently invalidates its handles, even if its old key
+is inserted again.
+
+This is an experimental personal project. Development is intermittent; no support
+or release schedule is promised. APIs may change before a stable release.
+
+Licensed under the [MIT License](LICENSE).
+
+## Experimental package release
+
+The alpha release uses `dualdict==0.1.0a1` and optional
+`dualdict-cpp==0.3.3a1` (backend V3.3.1). Once uploaded to PyPI:
+
+```powershell
+python -m pip install dualdict==0.1.0a1
+python -m pip install dualdict-cpp==0.3.3a1
+```
+
+The default Python package requires Python 3.10+ and no compiler. The initial
+native wheel targets **Windows x64 / GIL-enabled CPython 3.12**. Other
+configurations require a C++17 compiler and Python development headers; source CI
+exercises CPython 3.10, 3.12 and 3.14 on Windows, Linux and macOS, without providing
+a complete wheel matrix. Free-threaded Python, PyPy and subinterpreters are
+unsupported by the native backend.
+
+The GitHub repository remains private. The published source archives include
+documentation, examples and benchmark sources without exposing Git history.
+See [release notes](docs/release-0.1.0a1.md) and the
+[TestPyPI rehearsal](docs/packaging.md#testpypi-rehearsal-and-pypi-publication).
+
+## Install from a checkout
+
+The default Python implementation needs Python 3.10+ and no compiler:
+
+```powershell
+python -m pip install -e .
+```
+
+For the optional native backends, use GIL-enabled CPython and a C++17 toolchain
+(MSVC Build Tools on Windows). Install both distributions from this checkout:
+
+```powershell
+python -m pip install -e .
+python -m pip install ./cpp
+```
+
+The native prototype targets the main interpreter. Free-threaded Python, PyPy and
+subinterpreters are not supported by the native backend. See
+[package build and installation checks](docs/packaging.md).
+
+## Choose an API explicitly
+
+| Import | Backend | Indexed read | Live handle |
+|---|---|---|---|
+| `from dualdict import DualDict` | V1, default Python | `view[key]` returns a proxy | `view[key]` |
+| `from dualdict.v2_python import DualDict` | V2 Python | `view[key]` returns a proxy | `view[key]` |
+| `from dualdict.v331_cpp import DualDict` | V3.3.1 native | `view[key]` returns the raw endpoint | `view.live(key)` |
+
+`view.snapshot(key)` returns a raw endpoint in all three backends. Switching to
+the native API is explicit; installing the extension does not change the default
+import. Older native experiments remain available for comparisons:
+[V3](cpp/README.md), [V3.1](cpp/V31.md), [V3.3](cpp/V33.md).
+
+## V3.3.1 quick start
+
+```python
+from dualdict.v331_cpp import DualDict
+
+d = DualDict([(101, ("Alice", "Engineering"))])
+assert d.by_key[101] == ("Alice", "Engineering")
+assert d.by_value[("Alice", "Engineering")] == 101
+
+before = d.by_key[101]                 # raw endpoint, not a live handle
+employee = d.by_key.live(101)
+d.by_key.set_field(101, 1, "Research")
+assert employee.snapshot() == ("Alice", "Research")
+assert before == ("Alice", "Engineering")
+assert d.by_value[("Alice", "Research")] == 101
+```
+
+Without the extension, use the default API:
+
+```python
+from dualdict import DualDict
+
+d = DualDict([(101, ("Alice", "Engineering"))])
+employee = d.by_key[101]
+employee[1] = "Research"
+assert employee.snapshot() == ("Alice", "Research")
+```
+
+Run the complete example, including reverse replacement, collision rejection and
+stale-handle behavior:
+
+```powershell
+python -m examples.employee_directory
+python -m examples.employee_directory --backend v331
+```
+
+## Operation semantics
+
+| Operation | Behavior |
+|---|---|
+| `d.add(key, value)` | Rejects duplicate keys or values, including an identical pair |
+| `d.by_key[key] = value` | Inserts or replaces the value; rejects another record's value |
+| `d.by_value[value] = key` | Symmetric insertion/replacement of the key |
+| `del d.by_key[key]` | Deletes the record and invalidates its live handles |
+| `d.clear()` | Deletes all records and invalidates all live handles |
+| `d.items()` | Iterates raw `(key, value)` pairs |
+| `view.snapshot(lookup)` | Returns the current raw endpoint without copying |
+| `view.field(lookup, index)` | V3.3.1 direct endpoint indexing |
+| `view.set_field(lookup, index, value)` | V3.3.1 positional field update of an exact tuple |
+
+Both views support length, iteration, membership and deletion. Proxies are
+unhashable and support snapshots, equality, indexing, iteration and tuple-field
+assignment; they do not transparently emulate every operation of their endpoint.
+Snapshots neither copy nor freeze custom objects, and do not follow replacements.
+
+Field assignment requires a plain tuple; nested edits, slices and field deletion
+are excluded. Tuple subclasses may be stored and replaced as whole endpoints.
+Equal replacement is a no-op that retains the original endpoint object.
+`CollisionError` reports uniqueness violations, `KeyError` missing lookups,
+`TypeError` invalid hashability/types, and `DeletedRecordError` stale handles.
+
+## Endpoint and safety contract
+
+Both endpoints must have stable, non-raising, non-reentrant hash/equality behavior
+for their entire stored lifetime. This includes objects inside tuples/frozensets.
+Equal objects, including `1` and `True`, collide. Do not externally mutate fields
+used by an endpoint's hash/equality. Hashability alone does not prove immutability.
+Use immutable identifiers or replace endpoints through the mapping.
+
+Validation failures preserve mappings under that contract. Arbitrary hostile
+callbacks and asynchronous interruption do not have transaction-level guarantees.
+If V3.3.1 cannot restore its indexes after a callback-induced rollback failure,
+it disables the owner: public access and retained handles raise `RuntimeError`.
+Discard that instance; no repair API is provided. Bulk operations commit one entry
+at a time. Multi-call sequences require application synchronization; GIL-enabled
+execution does not make them transactions. Handles retain their owner.
+
+Average lookup is O(1), excluding endpoint hashing/equality. Tuple edits reconstruct
+and hash an O(width) tuple. The native slot/generation architecture is described in
+[V3.3.1 safety and validation notes](cpp/V331.md).
+
+## Tests and benchmarks
+
+```powershell
+python -m unittest discover -s tests -v
+$env:DUALDICT_BACKEND = "v3.3.1-cpp"
+python -X dev -X faulthandler -m unittest discover -s tests -v
+Remove-Item Env:DUALDICT_BACKEND
+python -m pip install -e ".[benchmark]"
+python -m benchmarks.bidict_v331 --access random
+python -m benchmarks.bidict_v331 --access skewed
+```
+
+See [benchmark methodology and commands](benchmarks/README.md). Timings compare
+both directions, tuple widths, writes, and mixed read/write workloads. Same-record,
+shuffled full-dataset and 80/20 access patterns answer different questions.
+Randomized lookup tests have favored bidict; write-heavy tests have favored
+DualDict in the measured configurations. Results are workload/machine-specific,
+not a universal speedup claim. These runners do not measure memory or production
+latency. Native allocator/sanitizer checks are described in the safety guide.
+
+The native backend remains experimental. Passing tests and CI add evidence;
+they do not establish production-grade security assurance.

dualdict-0.1.0a1/benchmarks/README.md

@@ -0,0 +1,142 @@
+# Benchmark workloads
+
+`forward_lookup_snapshot`/`reverse_lookup_snapshot` measure proxy allocation
+followed by proxy `.snapshot()` in DualDict. The new `*_lookup_raw` metrics use
+view `.snapshot(lookup)` without allocating a proxy. bidict uses direct lookup
+for both metric families, timed independently. Differences include method calls,
+index selection and endpoint access, not just allocation. Regenerate both reports
+to include the new raw metrics.
+
+Run both implementations and generate a fresh comparison with one command:
+
+```powershell
+python -m benchmarks.compare
+```
+
+It accepts `--sizes`, `--widths`, `--operations`, `--repeats`, and `--output-dir`.
+Each run creates a unique UTC-stamped directory under `benchmarks/comparisons`
+with `dualdict.json`, `bidict.json`, `comparison.json`, and `comparison.md`.
+Ratios are DualDict divided by bidict: below 1 means less time or memory.
+Runs are sequential in separate processes using the same Python interpreter.
+Existing results are preserved. A missing dependency stops the run before benchmarking.
+
+Run `python -m benchmarks.run > benchmarks/results.json` from the project root.
+Configure `--sizes 1000 10000 100000 --widths 2 8 32 --operations 10000 --repeats 5`.
+Generation and setup are outside timed regions, except construction itself.
+Seeded probes include repeated random hits. Mutations use fresh mappings each repeat.
+Results include raw samples, median/minimum nanoseconds per operation and environment.
+Throughput is `1e9 / median_ns_per_op`. Construction is normalized per entry.
+
+Memory uses tracemalloc with pre-created inputs: it measures mapping overhead,
+excluding endpoint objects allocated before tracing. It is not process RSS.
+Tuple edits use a retained proxy; lookup includes proxy creation and snapshot.
+Whole replacement uses a two-element tuple for both input families.
+This is a local microbenchmark, not a production latency test.
+Run on an idle machine and compare identical configurations and Python versions.
+
+## bidict comparison
+
+Install the optional dependency with `python -m pip install bidict`. Alternatively,
+install locally with `python -m pip install --target .benchmark_deps bidict` and
+set `$env:PYTHONPATH = "$PWD/.benchmark_deps"` in PowerShell before running.
+
+```powershell
+python -m benchmarks.run > benchmarks/results_dualdict.json
+python -m benchmarks.run_bidict > benchmarks/results_bidict.json
+```
+
+Both runners accept identical arguments and share the same seeded input generator.
+The bidict output records its installed version. Lookup includes a proxy and snapshot
+for DualDict, and direct retrieval for bidict. `manual_tuple_edit` uses lookup,
+list reconstruction and assignment in bidict; compare it with DualDict's
+`retained_proxy_tuple_edit`, which uses a retained proxy. These achieve the same
+field update but do not provide equivalent retained-reference semantics.
+
+Duplicate rejection now attempts a new key with an existing value in both runners.
+The earlier identical-pair workload was incompatible with bidict's no-op behavior;
+regenerate previous DualDict results before comparing. Memory excludes input
+objects for both runners. No live-proxy survival comparison is implied.
+
+## Same-record V3.3.1 versus bidict
+
+```powershell
+Remove-Item Env:PYTHONMALLOC -ErrorAction SilentlyContinue
+python -m benchmarks.bidict_v331 --sizes 10000 100000 --widths 2 8 32 --operations 200000 --repeats 7
+```
+
+Requires the normal V3.3.1 extension (allocation test hooks disabled) and bidict.
+The runner checks validation and duplicate rejection before timing, then verifies
+both indexes and identical final mappings after every sample. Both directions
+use cached views and identical tuple records. Timings include native direct field
+reads, bidict raw lookup plus indexing, full endpoint replacement, and field edits
+with exact-tuple/index/hashability/uniqueness validation. Bidict implements field
+edits through a Python helper; DualDict performs that work in its native API.
+
+Mixed workloads use seeded, precomputed schedules with 90%/50% raw reads and
+10%/50% field updates on one hot record (integer rounding for tiny runs). They
+are not random-record workloads. Insert/delete use distinct-record batches,
+limited to min(size, operations). Insert begins with size records; delete begins
+with size plus batch records. These measure assignment of absent endpoints and
+deletion, not strict duplicate-key insertion or a create/delete cycle.
+
+Every sample starts fresh; one warmup is discarded and backend order alternates.
+Generation, construction and correctness checks are outside timing; GC is disabled
+inside timing. Reports under benchmarks/versions/*-bidict retain environment,
+source timing statements, operation counts, raw samples, median/min/max, and a
+side-by-side Markdown table. Ratio is bidict time / DualDict time: above 1 favors
+DualDict. This direction differs from the older runners described above.
+
+No proxy equivalence, memory savings, callback safety or application-wide speedup
+is implied. Measure memory separately; this runner measures operation timings.
+
+## Randomized full-dataset access
+
+```powershell
+python -m benchmarks.bidict_v331 --access random --seed 331 --sizes 10000 100000 --widths 2 8 32 --operations 200000 --repeats 7
+```
+
+`--access hot` remains the default for comparison with the earlier experiment.
+Random mode precomputes seeded shuffled passes over record indexes. Every record
+is visited once per pass before any repeats, so the default 200K operations cover
+the entire 10K/100K dataset. A shorter operation count gives partial coverage;
+JSON records `records_visited` per row. This is randomized order without
+replacement within a pass, not independent uniform sampling with replacement.
+
+Each direction has its own fresh mapping. Writes change the opposite endpoint,
+so lookup keys remain stable. Replacements preserve a unique identity field and
+field updates change field one. Mixed schedules retain the same read/write ratios;
+all operations visit the dataset, while only the write subset changes records.
+Both backends reuse the same original key objects, rather than freshly recreated
+equal keys. Lookup iterator advancement is included equally in timings. Insert
+and delete shuffle their distinct-record batches; insertion targets new records,
+not existing records in the dataset. Setup, RNG and validation remain untimed.
+
+Reports have distinct `-bidict-hot`/`-bidict-random` directories, with access mode,
+seed, record coverage, exact statements and raw timing samples in results.json.
+
+
+## Skewed application-style access
+
+```powershell
+python -m benchmarks.bidict_v331 --access skewed --seed 331 --sizes 100000 --widths 8 --operations 50000 --repeats 3
+```
+
+Exactly 80% of requests (rounded down) sample with replacement from a seeded
+20% hot set (at least one record). Remaining requests sample the cold set.
+For a one-record dataset every request is hot. This models access concentration;
+it is an 80/20 distribution, not Zipf and not a claim about every application.
+Mixed 90/10 and 50/50 workloads use separately generated read/write schedules.
+JSON reports actual distinct-record coverage. Insert/delete still shuffle their
+separate distinct-record batches and do **not** model an 80/20 distribution.
+Both distributions are checked against a simple dictionary oracle before timing.
+
+For a scaling experiment, start with a bounded run and increase the operation
+count to suit available time and memory:
+
+```powershell
+python -m benchmarks.bidict_v331 --access random --sizes 1000000 --widths 2 --operations 1000000 --repeats 3
+```
+
+This command is a suggested experiment, not a recorded 1M-record result.
+All runners allocate setup data and validate complete mappings outside timing,
+so process memory and elapsed wall time exceed what the per-operation figures show.

dualdict-0.1.0a1/benchmarks/api_v33.py

@@ -0,0 +1,70 @@
+"""Complete raw/live API workloads, in both directions; source timing statements are saved."""
+import argparse
+import json
+import os
+import platform
+from pathlib import Path
+import subprocess
+import sys
+import timeit
+from datetime import datetime, timezone
+from statistics import median
+from .workloads import make_pairs
+from dualdict.backends import load_backend
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--operations", type=int, default=200000)
+    parser.add_argument("--repeats", type=int, default=7)
+    a = parser.parse_args()
+    if min(a.operations, a.repeats) < 1:
+        parser.error("positive arguments required")
+    out = Path("benchmarks/versions") / (datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ") + "-api")
+    out.mkdir(parents=True)
+    rows = []
+    for backend in ("v3.3-cpp", "v3.3.1-cpp"):
+        test = subprocess.run([sys.executable, "-X", "faulthandler", "-m", "unittest", "discover", "-s", "tests", "-v"],
+                              env=dict(os.environ, DUALDICT_BACKEND=backend), capture_output=True, text=True)
+        (out / (backend + "-tests.txt")).write_text(test.stdout + test.stderr)
+        test.check_returncode()
+        cls = load_backend(backend)
+        print("Benchmarking " + backend, flush=True)
+        for size in (10000, 100000):
+            for kind, width in (("scalar", 1), ("tuple", 2), ("tuple", 8), ("tuple", 32)):
+                pairs = make_pairs(size, width, kind)
+                for reverse in (False, True):
+                    statements = {"raw_read": "view[key]", "snapshot": "view.snapshot(key)",
+                                  "live_creation": "view.live(key)"}
+                    if kind == "tuple":
+                        statements.update(field_read="view.field(key, 1)", snapshot_field="view.snapshot(key)[1]",
+                            live_field="view.live(key)[1]", retained_read="proxy[1]",
+                            set_field="view.set_field(key, 1, next(changes))",
+                            retained_update="proxy[1] = next(changes)")
+                    for name, statement in statements.items():
+                        samples = []
+                        for _ in range(a.repeats):
+                            d = cls(pairs)
+                            view = d.by_value if reverse else d.by_key
+                            key = pairs[0][1 if reverse else 0]
+                            scope = dict(view=view, key=key, proxy=view.live(key), changes=iter(range(100, a.operations + 100)))
+                            seconds = timeit.Timer(statement, globals=scope).timeit(number=a.operations)
+                            samples.append(seconds * 1e9 / a.operations)
+                            if name in ("set_field", "retained_update"):
+                                assert view[key][1] == a.operations + 99
+                        rows.append(dict(backend=backend, size=size, kind=kind, width=width,
+                            direction="reverse" if reverse else "forward", metric=name,
+                            statement=statement, median_ns=median(samples), samples_ns=samples))
+    (out / "results.json").write_text(json.dumps(dict(python=platform.python_version(), platform=platform.platform(),
+        operations=a.operations, repeats=a.repeats, rows=rows), indent=2))
+    lines = ["# Complete V3.3 API comparison", "", "Median ns/op, lower is faster. Same-record workloads with cached view and lookup; setup outside timing.",
+             "Fresh mapping each sample. Updates include next(changes) overhead. Scalar field operations excluded.",
+             "timeit disables cyclic GC during each timed sample. Endpoint hashing, field indexing and proxy lifetime remain included.", "",
+             "| Backend | Entries | Kind | Width | Direction | Operation | ns/op |", "|---|---:|---|---:|---|---|---:|"]
+    lines += [f"| {r['backend']} | {r['size']} | {r['kind']} | {r['width']} | {r['direction']} | {r['metric']} | {r['median_ns']:.1f} |" for r in rows]
+    (out / "comparison.md").write_text("\n".join(lines))
+    print((out / "comparison.md").resolve())
+
+
+if __name__ == "__main__":
+    main()