[zzcgumn]

Summary

• Adds a context-aware analyse_play(SolverContext&, ...) to the modern C++ API, extracted from legacy AnalysePlayBin's body (which now delegates to it, preserving external behavior).
• Mirrors it through the pure-C ABI shim as dds_c_analyse_play, plus a new dds_c_convert_play_from_pbn converter (PBN play trace → binary), following the shim's existing no-PBN-twin pattern; regenerates the JNI export lists accordingly.
• Adds a Python analyse_play (binary) binding and refactors analyse_play_pbn to drop its call into legacy AnalysePlayPBN, converting PBN→binary in C++ and calling the modern analyse_play directly instead.
• Updates specs/dds-public-api.md to reflect the shim's expanded surface, and fixes two docstrings that overpromised ValueError for illegal plays (they actually raise RuntimeError).
• Parallelizing analyse_all_plays_pbn was explicitly scoped out as a follow-up (deferred, not implemented here).

Test plan

• bazel test //library/tests/system:context_equivalence_test — context vs. legacy equivalence
• bazel test //library/tests/solve_board:analyse_play_consistency_test — regression gate for the AnalysePlayBin extraction
• bazel test //library/tests:dds_c_api_test — shim null-guards, functional, and converter tests
• bazel test //jni/tests:export_set_test — export-list regeneration verified
• bazel test //python:analyse_test — new and refactored Python bindings

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The new source is omitted from both Visual Studio projects, causing link failures, and missing play-trace validation in the binary C entry point permits out-of-bounds memory access.

3 open issues

• Validate play-trace counts, suits, and ranks before indexing · New
• Add adapter source to both Visual Studio project files · New
• Clarify trick totals use the partnership opposite the initial leader · New

What changed in this PR

Adds context-aware play analysis across DDS’s modern C++ API, pure-C shim, and Python bindings while preserving the legacy entry points.

Changes:

• Extracts play analysis into a reusable-context implementation and delegates legacy calls to it.
• Adds C and Python binary analysis entry points, PBN play conversion, and native exports.
• Adds equivalence, context-reuse, and input-validation tests, with API documentation updates.

File	Description
specs/​dds-public-api.md	Documents expanded shim coverage and PBN conversion.
python/​tests/​test_analyse.py	Tests binary analysis, representation equivalence, and contexts.
python/​src/​converters.hpp	Declares binary play-trace conversion.
python/​src/​converters.cpp	Converts and validates Python play sequences.
python/​src/​bindings.cpp	Adds binary analysis and modernizes PBN analysis.
python/​dds3/​__init__.py	Exports analyse_play.
library/​tests/​system/​context_equivalence_test.cpp	Tests legacy equivalence and context reuse.
library/​tests/​dds_c_api_test.cpp	Tests shim analysis, null guards, and conversion.
library/​src/​play_analyser.cpp	Delegates legacy analysis to the modern implementation.
library/​src/​dds.hpp	Includes the new public analysis header.
library/​src/​dds_api.cpp	Implements the context-handle forwarding entry point.
library/​src/​api/​dds_c_api.h	Declares C analysis and play conversion functions.
library/​src/​api/​dds_c_api.cpp	Implements guarded C shim forwarding.
library/​src/​api/​dds_api.hpp	Declares context-handle play analysis.
library/​src/​api/​BUILD.bazel	Registers the new public header.
library/​src/​api/​analyse_play.hpp	Defines the context-aware C++ interface.
library/​src/​analyse_play_adapter.cpp	Holds the extracted play-analysis implementation.
jni/​version_script.lds	Exports the new C functions on ELF platforms.
jni/​exported_symbols.lds	Exports the new C functions on macOS.
docs/​python_interface.md	Documents binary analysis and reusable contexts.

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The C API header does not expose the new play input and result layouts, preventing C consumers from allocating these types and header-based binding generators from reading their definitions.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Expose play structs in the shared C data-types header

library/​src/​api/​dds_c_api.h:124

A consumer including only dds_c_api.h cannot allocate the new play inputs or results: PlayTraceBin, PlayTracePBN, and SolvedPlay are defined only in dds_data_types.hpp, leaving header-based binding generators without their layouts. Move these three POD definitions into dds_c_data_types.h and remove the original definitions; the C++ header already includes that shared header. This also fixes dds_c_convert_play_from_pbn below.

3 resolved since last review

• Add adapter source to both Visual Studio project files
• Validate play-trace counts, suits, and ranks before indexing
• Clarify trick totals use the partnership opposite the initial leader

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Human judgment is needed to weigh the remaining mismatch between documented exceptions and actual behavior for malformed play tokens.

No open issues 🎉

_{Review effort: Balanced}

[zzcgumn]

I have opened #442 to review documented and actual behaviour for malformed inputs. I think this might be wider than the current pull request.

[zzcgumn]

@tameware, here is another one exposing more functions through the C API. Note that I deferred the decision about synchronising documentation and actual error types as I think this might be a wider problem.

[tameware]

LGTM.

I think I've mentioned before that in the long term, I'm not sure we should support the binary interface. There can't be any measurable efficiency gain, and sticking to text-oriented standards such as PBN for externals will make our clients' implementation and debugging easier.