docs: add Conductor module interface conventions page - #814
Merged
Conversation
Records design decisions made while migrating bundles to Conductor, worked out with Martin Henz during the py-slang#307 discussion (source-academy/py-slang#307): numbers are always floats crossing a module boundary in either direction with no exceptions (and why - keeps modules bigint-free, for simplicity/performance/future-language portability); there is no distinct "pair" representation anymore, pairs are just 2-element arrays, and array conversion should be untyped and recursive; DataType.OPAQUE is where structural recursion stops; and binary_tree's is_tree/assertNonEmptyTree hardcoded-PAIR-check exception (#813) is called out explicitly so it isn't "fixed" into false consistency later. Requested by Lee Yi - a Slack conversation isn't discoverable to future bundle authors the way a docs page is.
Contributor
|
Caution The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased. |
CI's spellcheck flagged it in Martin's directly-quoted Slack message
("ints are silently converted to floats") - added to the word list rather
than reword a direct quote.
leeyi45
reviewed
Jul 23, 2026
leeyi45
left a comment
leeyi45
left a comment
Contributor
There was a problem hiding this comment.
In general I think the listing of the reasoning should be put in its own section of docs: The conventions section is about how to write bundle functions, not necessarily about the why we made these design decisions.
It might fall better under the advanced section, or even a new section entirely.
It might be worth to split each "issue" into different pages (files) as well.
Lee's review on #814: "the listing of the reasoning should be put in its own section of docs: The conventions section is about how to write bundle functions, not necessarily about the why we made these design decisions ... It might fall better under the advanced section ... worth splitting each 'issue' into different pages too." - Moved out of 2-bundle/4-conventions/ into a new 5-advanced/conductor-interop/ subsection. - Split the single page into four: numbers.md, pairs-and-arrays.md, opaque.md, binary-tree-exception.md, plus an index.md linking them. - Updated pairs-and-arrays.md to reflect Martin's follow-up review comment on py-slang#307 (now merged): DataType.PAIR is slated for full removal from py-slang, not just being treated as interchangeable with DataType.ARRAY - Aarav Malani owns that follow-up PR. Called this out explicitly rather than describing the interchangeable-bridge state as final. - Added the empty-list-vs-None pitfall (caught by live testing after an earlier version of the py-slang fix got this wrong) as its own callout. - Added 'Aarav'/'Malani' to the cspell word list.
Contributor
Author
|
Thx for the review, done - moved out of `2-bundle/4-conventions/` into a new `5-advanced/conductor-interop/` section, split into 4 focused pages (numbers, pairs-and-arrays, opaque, the binary_tree exception) plus an index linking them. Also updated the pairs-and-arrays page to reflect Martin's follow-up comment on py-slang#307 (which has since merged) - DataType.PAIR is actually slated for full removal from py-slang, not just being bridged as interchangeable with DataType.ARRAY. |
Keep the substantive content (a follow-up PR has been claimed to fully remove DataType.PAIR from py-slang) without naming who's doing it in the docs content itself.
…ns' into docs/conductor-interop-conventions
Lee's inline review comment on the original single-page version (before the restructure moved this line into opaque.md): "Use a dialog box for this - I think of all the languages supported only Python supports complex numbers as a primitive. so it's more of an aside."
This docs site's sidebar plugin (vitepress-sidebar) uses useFolderLinkFromSameNameSubFile to make a folder itself clickable in the sidebar - it needs a same-named file inside the folder (see the existing 5-advanced/flow/flow.md precedent), not index.md. Using index.md instead left the folder's sidebar entry as unclickable text (its title pulled from useFolderTitleFromIndexFile) with no page behind it, and the file itself unreachable through normal site navigation.
vitepress-sidebar sorts alphabetically by filename by default, which put the pages in the wrong order (binary_tree exception, Numbers, OPAQUE, Pairs and arrays - alphabetical, not the intended reading order). Matches the existing 2-bundle/4-conventions/ convention (1-basic.md, 2-abstractions.md, ...) for forcing a deliberate order. Updated every internal cross-reference between the pages to match the new filenames.
Pointed at the bare folder URL (./conductor-interop/), which 404s now that the landing page is conductor-interop.md instead of index.md (see previous commit) - VitePress only auto-serves a folder's trailing-slash URL from an index.md. Point directly at the actual file instead.
leeyi45
approved these changes
Jul 23, 2026
leeyi45
left a comment
leeyi45
left a comment
Contributor
There was a problem hiding this comment.
LGTM. Let us keep in mind that these should be updated as we progress along.
Per Lee Yi's review on modules#796: document why IDataHandler.closure_call_sync exists as an optional fast path (Conductor's ExternCallable contract mandates AsyncGenerator closure calls, which is correct but costs measurable overhead at 44.1kHz sample-rate hot loops), which engines actually implement it today (py2js only, via dual compilation - PVML/CSE don't have it), and why a module has to check for it at runtime rather than assume it per-engine. Numbers pulled from py-slang's experiments/py2js benchmarks, condensed to what's forward-looking rather than a blow-by-blow history.
5 tasks
Member
|
should this PR be against master or conductor-migration? |
Per modules#832: write up, as a general pattern rather than a sound-specific trick, why a module should attach a .sync twin to any closure handed back to cadet code that's provably synchronous, not just the ones the module itself expects to sample in a hot loop. A closure in cadet hands can end up composed and passed into a different module's own synchronous sampling loop, which is exactly the failure mode modules#833 had to defend closureToWave against. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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
3 participants
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.
Summary
Documentation.
Covers:
DataType.PAIRandDataType.ARRAYshould be treated interchangeably by an evaluator's own conversion code; array conversion should be untyped and recursive (an array can be heterogeneous, e.g.sound'sSound).DataType.OPAQUEas the boundary where structural recursion stops.binary_tree's hardcoded-PAIR-check exception (#813), called out explicitly so it isn't quietly "fixed" into consistency with the rest later.OPAQUEin practice).Companion to source-academy/py-slang#307 and #813.
Test plan