Conversation
Proposes a curated ecosystem of pre-wrapped Python libraries published to npm under the @tywrapped organization. Key proposals: - Governance: Central org with trusted maintainers, Open Collective funding - Versioning: Mirror upstream, compound version for tywrap patches - Quality: Two-badge system (quality tier + support breadth) - Runtime: Auto-detection with explicit override option - Breaking changes: Mirror upstream directly, transparent pass-through Seeking community feedback on this direction before implementation. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> (cherry picked from commit fd6351a)
📝 WalkthroughWalkthroughAdds a new RFC describing the proposed Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
🤖 Fix all issues with AI agents
In `@docs/plans/2026-01-22-tywrapped-ecosystem-vision.md`:
- Around line 82-100: The "Package Naming" section (pattern
`@tywrapped/<library>`) and the "Required disclaimer" block must be reviewed
with legal counsel before public launch: engage an IP/trademark attorney to
validate the nominative fair use claim and proposed disclaimer text, update the
disclaimer phrase under "Required disclaimer in each package" with
counsel-approved language, and have the attorney review the broader trademark
strategy referenced later in the document so you can replace any
speculative/legal-assertion wording with legally vetted wording.
- Around line 339-345: The estimate note is overly optimistic—update the plan
text to mark the 1-week total for adding node-calls-python as a "best-case" or
increase padding; specifically edit the table/nearby paragraph mentioning
NodeCallsPythonIO, Bridge adapter for node-calls-python, Integration tests,
Documentation and the Total to either add a confidence qualifier (e.g., "best
case") or increase the Total to reflect additional buffer for unknowns, and add
a short sentence referencing potential instability of the Transport interface
and first-time runtime-integration risks.
- Around line 223-226: The fenced TypeScript code block using ```typescript with
imports of setRuntime and InProcessBridge from '@tywrapped/numpy' needs blank
lines before and after the fence to satisfy MD031; edit the markdown so there's
an empty line above the opening ```typescript and an empty line after the
closing ``` (i.e., insert a newline between the closing fence and the following
"### Runtime Packages" heading) while keeping the code exactly as-is
(references: setRuntime, InProcessBridge).
- Around line 153-165: The fenced code block containing the numbered flow
diagram (the block starting with "1. Trigger (Dependabot or tywrap release)") is
missing a language specifier; update that opening fence to include a language
hint such as text (e.g., ```text) so the linter recognizes it as a plain text
diagram, or alternatively remove the language token entirely if your linter
prefers an unspecified fenced block—ensure the change is applied to the fenced
block that holds the step-by-step flow.
- Around line 353-378: The Phase headings (e.g., "Phase 1: Foundation", "Phase
2: Template & Tooling", "Phase 3: Proof of Concept", "Phase 4: Expansion",
"Optional (parallel track)") need a blank line after each heading to satisfy
MD022, and each phase's ordered list (the numbered items under those headings)
should restart at 1 instead of continuing sequence to satisfy MD029; edit the
roadmap so each heading is followed by an empty line and each ordered list under
"Phase 1: Foundation", "Phase 2: Template & Tooling", "Phase 3: Proof of
Concept", and "Phase 4: Expansion" begins with "1." (e.g., change 5-7 → 1-3,
8-10 → 1-3, 11-13 → 1-3) while preserving the same list content.
- Around line 198-201: The fenced code block containing "@tywrapped/numpy" needs
proper Markdown fencing per MD031/MD040: add a blank line before and after the
block and include a language specifier (e.g., markdown) on the opening fence so
the block reads as a standalone fenced code block; update the block around the
"@tywrapped/numpy" line, the "Quality: 🥇 Gold..." line, and the closing fence
to ensure the opening fence includes "markdown" and both surrounding blank lines
are present.
- Around line 305-315: The fenced diagram block lacks a language specifier and
surrounding blank lines; update the Transport Interface diagram by adding a
language hint (e.g., "text") after the opening ``` and ensure there is an empty
line before and after the fenced block so it conforms to MD031/MD040; the block
containing "Transport Interface" with symbols init(), send(), dispose(), isReady
and the implementors ProcessIO, HttpIO, PyodideIO should be replaced with a
properly fenced code block (```text ... ```) and blank lines around it.
- Around line 224-232: The document shows inconsistent package scopes between
library wrappers (imports like `@tywrapped/numpy` and symbols
setRuntime/InProcessBridge) and runtime packages listed as `@tywrap/runtime-`*, so
update the text to explicitly state the intended scope policy and make it
consistent: either document that `@tywrapped/` is reserved for public library
wrappers and `@tywrap/` is reserved for internal runtime/infrastructure, or rename
the listed runtime packages to `@tywrapped/runtime-`* for consistency; mention the
example symbols (`@tywrapped/numpy`, setRuntime, InProcessBridge,
`@tywrap/runtime-subprocess`, `@tywrap/runtime-inprocess`, `@tywrap/runtime-pyodide`)
so readers can see which packages follow which convention and why.
📜 Review details
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (1)
docs/plans/2026-01-22-tywrapped-ecosystem-vision.md
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2026-01-19T21:14:40.872Z
Learnt from: bbopen
Repo: bbopen/tywrap PR: 127
File: src/runtime/bridge-core.ts:260-263
Timestamp: 2026-01-19T21:14:40.872Z
Learning: In `src/runtime/bridge-core.ts` and similar hot request/response loop implementations in the tywrap repository, avoid adding extra defensive validation (e.g., runtime shape checks on error payloads) in tight loops unless the protocol boundary is untrusted or there's a concrete bug report. The Python bridge protocol is controlled and validated via tests, so defensive checks would add unnecessary branching overhead without meaningful benefit.
Applied to files:
docs/plans/2026-01-22-tywrapped-ecosystem-vision.md
🪛 markdownlint-cli2 (0.20.0)
docs/plans/2026-01-22-tywrapped-ecosystem-vision.md
[warning] 153-153: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 198-198: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 198-198: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 223-223: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 305-305: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 318-318: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 355-355: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 361-361: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 362-362: Ordered list item prefix
Expected: 1; Actual: 5; Style: 1/2/3
(MD029, ol-prefix)
[warning] 363-363: Ordered list item prefix
Expected: 2; Actual: 6; Style: 1/2/3
(MD029, ol-prefix)
[warning] 364-364: Ordered list item prefix
Expected: 3; Actual: 7; Style: 1/2/3
(MD029, ol-prefix)
[warning] 366-366: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 367-367: Ordered list item prefix
Expected: 1; Actual: 8; Style: 1/2/3
(MD029, ol-prefix)
[warning] 368-368: Ordered list item prefix
Expected: 2; Actual: 9; Style: 1/2/3
(MD029, ol-prefix)
[warning] 369-369: Ordered list item prefix
Expected: 3; Actual: 10; Style: 1/2/3
(MD029, ol-prefix)
[warning] 371-371: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 372-372: Ordered list item prefix
Expected: 1; Actual: 11; Style: 1/2/3
(MD029, ol-prefix)
[warning] 373-373: Ordered list item prefix
Expected: 2; Actual: 12; Style: 1/2/3
(MD029, ol-prefix)
[warning] 374-374: Ordered list item prefix
Expected: 3; Actual: 13; Style: 1/2/3
(MD029, ol-prefix)
[warning] 376-376: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: os (windows-latest)
🔇 Additional comments (5)
docs/plans/2026-01-22-tywrapped-ecosystem-vision.md (5)
1-52: LGTM! Strong opening sections.The RFC header, motivation, goals, and unique value proposition are well-articulated. The comparison table effectively positions tywrap's unique combination of features against alternatives.
103-118: LGTM! Clear and pragmatic versioning strategy.The compound version pattern (e.g.,
1.26.0-tywrap.1) provides a clean way to distinguish tywrap-specific patches from upstream releases. The transparent breaking-change policy (line 117) correctly sets user expectations that they're accepting upstream's upgrade path.
173-211: LGTM! Excellent two-badge system for quality and support.The orthogonal quality tier (testing depth) and support breadth (version coverage) indicators provide clear, actionable metrics. The progression path (line 203-209) creates a natural contribution ladder for maintainers.
246-296: LGTM! Well-researched launch libraries and funding strategy.The initial library candidates are well-prioritized based on clear criteria (lines 249-252). The Open Collective funding model follows proven patterns from other OSS projects, and the trademark registration guidance provides concrete cost estimates and timing recommendations.
318-324: Fix markdown formatting for code block (MD031).The Transport interface shown accurately matches the current implementation in
src/runtime/transport.ts. However, the code block lacks the required blank line above it per markdown standards.📝 Proposed fix
**Key interface** (`src/runtime/transport.ts`): + ```typescript interface Transport extends Disposable {
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
There was a problem hiding this comment.
Actionable comments posted: 9
🤖 Fix all issues with AI agents
In `@docs/plans/2026-01-22-tywrapped-ecosystem-vision.md`:
- Line 292: Replace the single-line estimate "Estimated cost: $250-400 per
class" with a realistic trademark cost that includes legal/search fees; update
the text near that string to something like "Estimated cost: $1,200–3,000 per
class (includes USPTO fees, comprehensive trademark search $300–800, attorney
filing/prosecution $500–1,500 per class, and possible office action responses
$300–800)" so the Phase 1 budget reflects the full expected range and show the
brief breakdown inline for clarity.
- Around line 283-288: Add a new "Governance and Fund Allocation" section under
the "Fund allocation" block that defines who makes allocation decisions and how:
specify the decision body (e.g., maintainers committee or council) and the
mechanism for splitting the 60% maintainer stipends (e.g., contribution metrics,
monthly activity scores, or fixed rates plus appeals), define approval workflow
for disbursing the 15% bounty pool (who can propose bounties, who approves and
timeframe), set rules for tapping the 5% reserve (thresholds, emergency
vote/approval process), and require transparency practices (quarterly financial
reports, public ledger of disbursements) plus a clear dispute-resolution process
(mediation steps, escalation to an independent panel or community vote).
- Around line 186-193: Add a new subsection under "Support Breadth (version
coverage)" that specifies the concrete technical implementation: describe
whether versioning is implemented via npm dist-tags (e.g., "latest",
"latest-1"), separate packages per major (e.g., `@tywrapped/numpy`,
`@tywrapped/numpy-1.24`, `@tywrapped/numpy-1.26`) or a single package that detects
runtime Python via a wrapper library, and how that maps to the four levels
(Basic: dist-tag "latest"; Standard: "latest" + "latest-1" tags; Full:
"upstream" tag matching full upstream matrix; Extended: "upstream+LTS" with LTS
builds). Include concrete examples of the package.json publishing fields and
naming conventions (npm dist-tags, version metadata, and optional engine
fields), a sample CI configuration outline showing matrixed jobs (e.g., GitHub
Actions matrix for PYTHON_VERSION values, build/test/publish steps and tags) and
the publish script logic (how to tag artifacts per version), and a short
user-facing API description explaining install commands and runtime behavior
(install specific package name or rely on auto-detection), referencing symbols
like package.json, dist-tags, publish script, CI matrix, and package names such
as `@tywrapped/numpy-1.24` to make implementation and validation steps clear for
maintainers.
- Around line 117-118: The "Breaking changes" paragraph stating "Mirror upstream
directly..." and the mention of `@tywrapped/numpy` need expanded guidance for
enterprise users: add a short subsection titled "Enterprise stability options"
after the Breaking changes paragraph that (1) defines an optional LTS/stable
channel policy (who can request LTS, cadence, and support window), (2) mandates
a migration guide requirement and minimal checklist for any published breaking
change (linking to a template), (3) documents version-pinning best practices and
example constraints for `@tywrapped/numpy`, and (4) includes a concise
discussion of trade-offs between transparency and stability so enterprises can
make informed adoption decisions.
- Around line 242-248: The doc lacks concrete implementation guidance for
validating and enforcing browser compatibility; add a new subsection under
"Opt-in per package" explaining (1) automated validation: add CI jobs named like
"browser-compat" that run matrixed browser E2E tests (Playwright) and bundler
builds (esbuild/webpack/rollup) for declared runtimes, using the package's
runtimes metadata field (`runtimes: ["node","browser"]`) as the source of truth;
(2) enforcement at package boundary: require template repos to include
build-time gating that fails CI for mismatched builds and a runtime guard in
exported entry points (e.g., check typeof window or a helper like isBrowser() in
the module entry) that throws a clear error when a Node-only package is imported
in the browser; (3) package metadata and publish-time checks: add a lint step
that validates package.json `runtimes` and generates README badges and npm
metadata, and fail publish if artifacts for declared runtimes are missing; and
(4) Pyodide handling: document a pattern for browser-enabled packages to mark
heavy Python deps as optional/browser-only, bundle a Pyodide loader helper (or
reference a CDN/peerDependency) that lazy-loads WASM, include CI smoke tests
that verify Pyodide initialization in headless browsers, and instruct template
repos to include fallback error messages when Pyodide is unavailable.
- Around line 323-331: Add a new subsection to the Transport design notes that
addresses large-data handling: describe limitations of string/JSON in Transport
(interface: Transport, send(message: string, ...), init(), isReady, Disposable),
and propose concrete strategies such as (1) binary protocols (MessagePack, Arrow
IPC) and zero-copy using ArrayBuffer/Transferable, (2) out-of-band transfer or
references (upload streams, object store URIs) for multi-GB tensors and
DataFrames, (3) streaming/chunked APIs and backpressure support (e.g.,
add/sendBinary or streamStart/streamChunk/streamEnd semantics and accept
ReadableStream/AbortSignal), and (4) fallbacks and versioning so transports can
advertise capabilities; keep guidance high-level and include suggested
symbols/method names (sendBinary, streamChunk, transferable ArrayBuffer) so
implementers can extend the Transport abstraction without breaking existing
send(message: string, ...).
- Around line 225-227: The import example currently pulls runtime abstractions
from '@tywrapped/numpy' which conflicts with the scope policy; update the
example to either (A) document that '@tywrapped/numpy' intentionally re-exports
runtime APIs (add a short note above the snippet explaining the re-export
pattern) or (B) change the snippet to import runtime types directly from the
runtime package by replacing the single import with separate imports for
setRuntime (from '@tywrapped/numpy') and InProcessBridge (from
'@tywrap/runtime-inprocess') so readers see the correct package ownership of
setRuntime and InProcessBridge.
- Around line 113-114: Update the "Republish policy" paragraph to assess
operational scalability and add concrete mitigations: describe a phased rollout
(e.g., canary packages and staggered waves), CI batching/parallelism limits,
automated health checks and gating (unit/integration smoke tests) before global
republish, npm rate-limit handling (throttled publish queue), explicit
maintainer approval workflows for package owners, and a rollback strategy for
tywrap regressions; reference the existing "Republish policy" heading and
include actionable parameters (canary percentage, gating thresholds,
retry/backoff policy) so maintainers can operationalize the policy.
- Around line 167-169: Update the "Human Gate" / governance section to add
explicit fallback mechanisms for maintainer unavailability: specify backup
maintainer assignment (minimum two per package), an escalation policy for
time-sensitive releases (security patches), a timeout policy (e.g., auto-approve
after 72 hours for patch releases), and an emergency override process for the
technical committee; add these as a short bulleted subsection under "Human Gate"
so maintainers and the TC can follow a clear, auditable flow when the primary
maintainer is unreachable.
📜 Review details
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (1)
docs/plans/2026-01-22-tywrapped-ecosystem-vision.md
🧰 Additional context used
🧠 Learnings (3)
📚 Learning: 2026-01-19T21:14:40.872Z
Learnt from: bbopen
Repo: bbopen/tywrap PR: 127
File: src/runtime/bridge-core.ts:260-263
Timestamp: 2026-01-19T21:14:40.872Z
Learning: In `src/runtime/bridge-core.ts` and similar hot request/response loop implementations in the tywrap repository, avoid adding extra defensive validation (e.g., runtime shape checks on error payloads) in tight loops unless the protocol boundary is untrusted or there's a concrete bug report. The Python bridge protocol is controlled and validated via tests, so defensive checks would add unnecessary branching overhead without meaningful benefit.
Applied to files:
docs/plans/2026-01-22-tywrapped-ecosystem-vision.md
📚 Learning: 2026-01-19T21:14:37.032Z
Learnt from: bbopen
Repo: bbopen/tywrap PR: 127
File: src/runtime/bridge-core.ts:375-385
Timestamp: 2026-01-19T21:14:37.032Z
Learning: In tywrap (src/runtime/bridge-core.ts and similar), environment variable parsing follows a tolerant/best-effort policy. For example, `TYWRAP_CODEC_MAX_BYTES=1024abc` should be accepted as 1024. Only reject clearly invalid values (non-numeric start or <=0). This avoids surprising failures from minor typos.
Applied to files:
docs/plans/2026-01-22-tywrapped-ecosystem-vision.md
📚 Learning: 2026-01-20T16:01:14.323Z
Learnt from: bbopen
Repo: bbopen/tywrap PR: 152
File: docs/adr/002-bridge-protocol.md:599-602
Timestamp: 2026-01-20T16:01:14.323Z
Learning: In `src/runtime/node-bridge.ts` (NodeBridge), a test message is sent to the Python subprocess to confirm the bridge is responsive before marking it as ready.
Applied to files:
docs/plans/2026-01-22-tywrapped-ecosystem-vision.md
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
| **Republish policy**: Every tywrap core release triggers regeneration and republish of all active packages with compound version. Users on any upstream version benefit from improvements. | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Assess the operational scalability of the republish policy.
The policy states that every tywrap core release triggers regeneration and republishing of all active packages. As the ecosystem grows to 10-20+ packages, this could create significant operational overhead:
- CI resource consumption (parallel builds, test suite execution)
- Manual review bottlenecks (each package maintainer must approve)
- npm registry rate limits
- Rollback complexity if a tywrap regression affects multiple packages
Consider adding a phased rollout strategy (e.g., canary packages first), automated health checks to gate mass republishes, or rate-limiting mechanisms to prevent overwhelming maintainers and CI infrastructure.
🤖 Prompt for AI Agents
In `@docs/plans/2026-01-22-tywrapped-ecosystem-vision.md` around lines 113 - 114,
Update the "Republish policy" paragraph to assess operational scalability and
add concrete mitigations: describe a phased rollout (e.g., canary packages and
staggered waves), CI batching/parallelism limits, automated health checks and
gating (unit/integration smoke tests) before global republish, npm rate-limit
handling (throttled publish queue), explicit maintainer approval workflows for
package owners, and a rollback strategy for tywrap regressions; reference the
existing "Republish policy" heading and include actionable parameters (canary
percentage, gating thresholds, retry/backoff policy) so maintainers can
operationalize the policy.
| **Breaking changes**: Mirror upstream directly. No buffering, no parallel support periods. The wrapper is a transparent pass-through - breaking changes in numpy mean breaking changes in `@tywrapped/numpy`. Document this clearly so users understand they're accepting upstream's upgrade path. | ||
|
|
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Clarify the impact of the aggressive breaking changes policy on enterprise adoption.
The policy explicitly states "no buffering, no parallel support periods" for upstream breaking changes. While this maintains transparency, it may deter enterprise users who require stability guarantees and controlled upgrade cycles. Enterprise adoption is often critical for ecosystem sustainability and funding.
Consider adding:
- Guidance on LTS or stable channels for enterprises
- Migration guide requirements when breaking changes are published
- Version pinning best practices in documentation
- Discussion of trade-offs between transparency and stability
🤖 Prompt for AI Agents
In `@docs/plans/2026-01-22-tywrapped-ecosystem-vision.md` around lines 117 - 118,
The "Breaking changes" paragraph stating "Mirror upstream directly..." and the
mention of `@tywrapped/numpy` need expanded guidance for enterprise users: add a
short subsection titled "Enterprise stability options" after the Breaking
changes paragraph that (1) defines an optional LTS/stable channel policy (who
can request LTS, cadence, and support window), (2) mandates a migration guide
requirement and minimal checklist for any published breaking change (linking to
a template), (3) documents version-pinning best practices and example
constraints for `@tywrapped/numpy`, and (4) includes a concise discussion of
trade-offs between transparency and stability so enterprises can make informed
adoption decisions.
| ### Human Gate | ||
|
|
||
| Library maintainer must approve before publish - automation does the heavy lifting, humans ensure quality. |
There was a problem hiding this comment.
Add fallback mechanisms for maintainer unavailability.
The human gate requires library maintainer approval before publish, but the document doesn't address scenarios where the primary maintainer is unavailable (vacation, emergency, departure). This creates a single point of failure that could block critical security updates or prevent timely upstream releases.
Recommend adding to the governance section:
- Backup maintainer assignment (minimum 2 per package)
- Escalation policy for time-sensitive releases (e.g., security patches)
- Timeout policy (e.g., auto-approve after 72 hours with no response for patch releases)
- Emergency override process for the technical committee
🤖 Prompt for AI Agents
In `@docs/plans/2026-01-22-tywrapped-ecosystem-vision.md` around lines 167 - 169,
Update the "Human Gate" / governance section to add explicit fallback mechanisms
for maintainer unavailability: specify backup maintainer assignment (minimum two
per package), an escalation policy for time-sensitive releases (security
patches), a timeout policy (e.g., auto-approve after 72 hours for patch
releases), and an emergency override process for the technical committee; add
these as a short bulleted subsection under "Human Gate" so maintainers and the
TC can follow a clear, auditable flow when the primary maintainer is
unreachable.
| ### Support Breadth (version coverage) | ||
|
|
||
| | Level | Indicator | Meaning | | ||
| |-------|-----------|---------| | ||
| | Basic | `latest` | Only current upstream version | | ||
| | Standard | `latest+1` | Latest + previous major | | ||
| | Full | `upstream` | Matches upstream's support matrix | | ||
| | Extended | `upstream+LTS` | Upstream support + extended LTS | |
There was a problem hiding this comment.
Specify the technical implementation for version support breadth.
The Support Breadth table defines four levels (Basic, Standard, Full, Extended) but doesn't explain how multiple Python versions are technically supported in a single npm package. Maintainers need to understand:
- Are different Python versions handled via npm dist-tags?
- Does the wrapper detect the installed Python version at runtime?
- Are there separate packages per major version (e.g.,
@tywrapped/numpy-1.24,@tywrapped/numpy-1.26)? - How does CI validate compatibility across multiple upstream versions?
Add a subsection explaining the technical approach for version matrix support, including concrete examples of the package.json structure, CI configuration, and user-facing API.
🤖 Prompt for AI Agents
In `@docs/plans/2026-01-22-tywrapped-ecosystem-vision.md` around lines 186 - 193,
Add a new subsection under "Support Breadth (version coverage)" that specifies
the concrete technical implementation: describe whether versioning is
implemented via npm dist-tags (e.g., "latest", "latest-1"), separate packages
per major (e.g., `@tywrapped/numpy`, `@tywrapped/numpy-1.24`, `@tywrapped/numpy-1.26`)
or a single package that detects runtime Python via a wrapper library, and how
that maps to the four levels (Basic: dist-tag "latest"; Standard: "latest" +
"latest-1" tags; Full: "upstream" tag matching full upstream matrix; Extended:
"upstream+LTS" with LTS builds). Include concrete examples of the package.json
publishing fields and naming conventions (npm dist-tags, version metadata, and
optional engine fields), a sample CI configuration outline showing matrixed jobs
(e.g., GitHub Actions matrix for PYTHON_VERSION values, build/test/publish steps
and tags) and the publish script logic (how to tag artifacts per version), and a
short user-facing API description explaining install commands and runtime
behavior (install specific package name or rely on auto-detection), referencing
symbols like package.json, dist-tags, publish script, CI matrix, and package
names such as `@tywrapped/numpy-1.24` to make implementation and validation steps
clear for maintainers.
| ```typescript | ||
| import { setRuntime, InProcessBridge } from '@tywrapped/numpy'; | ||
| setRuntime(new InProcessBridge()); // Use node-calls-python for speed |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Clarify the source of runtime APIs in the import example.
The code example imports setRuntime and InProcessBridge from @tywrapped/numpy:
import { setRuntime, InProcessBridge } from '@tywrapped/numpy';However, these are runtime abstractions that logically belong in the @tywrap/runtime-* infrastructure packages per the scope policy (lines 232-234). This inconsistency may confuse readers about the package architecture.
Clarify one of the following:
- If library packages re-export runtime APIs for convenience, document this re-export pattern explicitly
- If runtime APIs should be imported directly from
@tywrap/runtime-*packages, update the example to:import { setRuntime } from '@tywrapped/numpy'; import { InProcessBridge } from '@tywrap/runtime-inprocess';
🤖 Prompt for AI Agents
In `@docs/plans/2026-01-22-tywrapped-ecosystem-vision.md` around lines 225 - 227,
The import example currently pulls runtime abstractions from '@tywrapped/numpy'
which conflicts with the scope policy; update the example to either (A) document
that '@tywrapped/numpy' intentionally re-exports runtime APIs (add a short note
above the snippet explaining the re-export pattern) or (B) change the snippet to
import runtime types directly from the runtime package by replacing the single
import with separate imports for setRuntime (from '@tywrapped/numpy') and
InProcessBridge (from '@tywrap/runtime-inprocess') so readers see the correct
package ownership of setRuntime and InProcessBridge.
| Opt-in per package, clearly marked. | ||
|
|
||
| Packages declare supported runtimes in metadata: | ||
| - `runtimes: ["node"]` - Node.js only (heavy libraries like PyTorch) | ||
| - `runtimes: ["node", "browser"]` - Both supported | ||
|
|
||
| Visible in README badge, npm package metadata, and package documentation. |
There was a problem hiding this comment.
Describe how browser compatibility is validated and enforced.
The document states that browser support is "opt-in per package, clearly marked" and that packages declare supported runtimes in metadata. However, it doesn't explain:
- How browser compatibility is technically validated (automated browser tests in CI?)
- How runtime restrictions are enforced at install or import time (package.json
exports? runtime checks?) - What happens if a user tries to use a Node-only package in a browser (build error? runtime error?)
- How Pyodide dependencies are managed for browser-enabled packages
Add implementation details for runtime validation and enforcement to guide template repository design and CI pipeline configuration.
🤖 Prompt for AI Agents
In `@docs/plans/2026-01-22-tywrapped-ecosystem-vision.md` around lines 242 - 248,
The doc lacks concrete implementation guidance for validating and enforcing
browser compatibility; add a new subsection under "Opt-in per package"
explaining (1) automated validation: add CI jobs named like "browser-compat"
that run matrixed browser E2E tests (Playwright) and bundler builds
(esbuild/webpack/rollup) for declared runtimes, using the package's runtimes
metadata field (`runtimes: ["node","browser"]`) as the source of truth; (2)
enforcement at package boundary: require template repos to include build-time
gating that fails CI for mismatched builds and a runtime guard in exported entry
points (e.g., check typeof window or a helper like isBrowser() in the module
entry) that throws a clear error when a Node-only package is imported in the
browser; (3) package metadata and publish-time checks: add a lint step that
validates package.json `runtimes` and generates README badges and npm metadata,
and fail publish if artifacts for declared runtimes are missing; and (4) Pyodide
handling: document a pattern for browser-enabled packages to mark heavy Python
deps as optional/browser-only, bundle a Pyodide loader helper (or reference a
CDN/peerDependency) that lazy-loads WASM, include CI smoke tests that verify
Pyodide initialization in headless browsers, and instruct template repos to
include fallback error messages when Pyodide is unavailable.
| **Fund allocation** (suggested starting point): | ||
| - 60% - Maintainer stipends (proportional to package maintenance) | ||
| - 20% - Infrastructure costs (CI, hosting, tooling) | ||
| - 15% - Bounties for new packages, test improvements, documentation | ||
| - 5% - Reserve for legal/unexpected expenses | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Define the governance process for fund allocation decisions.
The suggested fund allocation percentages are clear, but the document doesn't specify who makes allocation decisions within each category. For example:
- How is the 60% maintainer stipend divided among package maintainers? (contribution metrics? fixed rates? committee vote?)
- Who approves bounty amounts from the 15% pool?
- Who decides when to spend from the 5% reserve?
Add a governance section explaining the decision-making process, transparency requirements (e.g., quarterly reports), and dispute resolution mechanisms to ensure fair and accountable fund distribution.
🤖 Prompt for AI Agents
In `@docs/plans/2026-01-22-tywrapped-ecosystem-vision.md` around lines 283 - 288,
Add a new "Governance and Fund Allocation" section under the "Fund allocation"
block that defines who makes allocation decisions and how: specify the decision
body (e.g., maintainers committee or council) and the mechanism for splitting
the 60% maintainer stipends (e.g., contribution metrics, monthly activity
scores, or fixed rates plus appeals), define approval workflow for disbursing
the 15% bounty pool (who can propose bounties, who approves and timeframe), set
rules for tapping the 5% reserve (thresholds, emergency vote/approval process),
and require transparency practices (quarterly financial reports, public ledger
of disbursements) plus a clear dispute-resolution process (mediation steps,
escalation to an independent panel or community vote).
| ### Trademark: Register Early | ||
|
|
||
| - File trademark application before public launch | ||
| - Estimated cost: $250-400 per class |
There was a problem hiding this comment.
Update trademark cost estimate to include legal fees.
The estimated cost of "$250-400 per class" reflects only USPTO filing fees. A complete trademark registration typically includes:
- Comprehensive trademark search: $300-800
- Attorney filing and prosecution: $500-1500 per class
- Potential office action responses: $300-800 per response
- Total realistic estimate: $1,200-3,000 per class
Update the cost estimate to set accurate budget expectations for Phase 1 foundation work.
🤖 Prompt for AI Agents
In `@docs/plans/2026-01-22-tywrapped-ecosystem-vision.md` at line 292, Replace the
single-line estimate "Estimated cost: $250-400 per class" with a realistic
trademark cost that includes legal/search fees; update the text near that string
to something like "Estimated cost: $1,200–3,000 per class (includes USPTO fees,
comprehensive trademark search $300–800, attorney filing/prosecution $500–1,500
per class, and possible office action responses $300–800)" so the Phase 1 budget
reflects the full expected range and show the brief breakdown inline for
clarity.
| **Key interface** (`src/runtime/transport.ts`): | ||
|
|
||
| ```typescript | ||
| interface Transport extends Disposable { | ||
| init(): Promise<void>; | ||
| send(message: string, timeoutMs: number, signal?: AbortSignal): Promise<string>; | ||
| readonly isReady: boolean; | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Address large data handling in the Transport interface discussion.
The Transport interface uses string-based message passing (send(message: string, ...)), and line 341 recommends JSON passthrough with "Small JSON overhead." However, the document doesn't discuss how this architecture handles large data science workloads:
- Large NumPy arrays (multi-GB tensors)
- Pandas DataFrames with millions of rows
- Streaming or chunked transfer for memory efficiency
- Binary serialization alternatives (MessagePack, Arrow IPC)
For data science libraries like NumPy, PyTorch, and Pandas, JSON serialization of large arrays can cause:
- Memory pressure (multiple copies of data in memory)
- Serialization/deserialization overhead (seconds for large arrays)
- String size limits in JavaScript engines
Add a subsection discussing large data handling strategies, potential use of binary protocols, or out-of-band data transfer mechanisms for the runtime abstraction layer.
🤖 Prompt for AI Agents
In `@docs/plans/2026-01-22-tywrapped-ecosystem-vision.md` around lines 323 - 331,
Add a new subsection to the Transport design notes that addresses large-data
handling: describe limitations of string/JSON in Transport (interface:
Transport, send(message: string, ...), init(), isReady, Disposable), and propose
concrete strategies such as (1) binary protocols (MessagePack, Arrow IPC) and
zero-copy using ArrayBuffer/Transferable, (2) out-of-band transfer or references
(upload streams, object store URIs) for multi-GB tensors and DataFrames, (3)
streaming/chunked APIs and backpressure support (e.g., add/sendBinary or
streamStart/streamChunk/streamEnd semantics and accept
ReadableStream/AbortSignal), and (4) fallbacks and versioning so transports can
advertise capabilities; keep guidance high-level and include suggested
symbols/method names (sendBinary, streamChunk, transferable ArrayBuffer) so
implementers can extend the Transport abstraction without breaking existing
send(message: string, ...).
bbopen
dismissed stale reviews from coderabbitai[bot] and coderabbitai[bot]
Doc PR is intentionally high-level RFC; requested expansion is out of scope for this merge. Dismissing bot review to unblock merge.
1 participant
Adds an RFC-style doc outlining a 2026 ecosystem vision for @tywrapped packages.