feat: integrate callable contracts and numeric correctness for 0.11

.github/workflows/ci.yml

@@ -38,6 +38,9 @@ jobs:
         run: npm run test:types
       - name: Build
         run: npm run build
+      - name: Full release checks
+        if: github.event_name == 'workflow_dispatch'
+        run: CI=1 npm run check:all
 
   test:
     if: github.event_name != 'schedule'
@@ -78,6 +81,60 @@ jobs:
           files: ./coverage/lcov.info
           fail_ci_if_error: false
 
+  isolated-consumer:
+    if: github.event_name != 'schedule'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+      - name: Install dependencies
+        run: npm ci --prefer-offline --no-audit
+      - name: Build package candidate
+        run: npm run build
+      - name: Run isolated consumer check
+        env:
+          CI: '1'
+        run: npx vitest run --config vitest.isolated-consumer.config.ts
+
+  pyodide-browser:
+    if: github.event_name != 'schedule'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+      - name: Install dependencies
+        run: npm ci --prefer-offline --no-audit
+      - name: Install tywrap-ir
+        run: python -m pip install -e tywrap_ir
+      - name: Build package
+        run: npm run build
+      - name: Install Chromium
+        run: npx playwright install --with-deps chromium
+      - name: Fetch locked NumPy asset
+        run: node scripts/fetch-pyodide-package.mjs numpy
+      - name: Record pinned runtime evidence
+        run: node scripts/print-pyodide-ci-evidence.mjs
+      - name: Run real Pyodide and browser checks
+        env:
+          CI: '1'
+        run: npx vitest run --config vitest.pyodide.config.ts
+
   python-suite-core:
     if: github.event_name != 'schedule'
     runs-on: ubuntu-latest
@@ -101,7 +158,7 @@ jobs:
       - name: Run Python codec and frame tests
         run: |
           python -m pip install pytest
-          python -m pytest test/python/test_bridge_codec.py test/python/test_frame_codec.py
+          python -m pytest test/python/test_bridge_codec.py test/python/test_bridge_core.py test/python/test_frame_codec.py
 
   python-suite-data:
     if: github.event_name != 'schedule'
@@ -223,11 +280,12 @@ jobs:
           PIP_PROGRESS_BAR: 'off'
         run: |
           python -m pip install -e tywrap_ir
-          python -m pip install numpy==2.3.5 pandas==3.0.2 pyarrow==24.0.0 scipy==1.16.3 scikit-learn==1.8.0
+          python -m pip install numpy==2.3.5 pandas==3.0.2 pyarrow==24.0.0 scipy==1.16.3 scikit-learn==1.8.0 pydantic==2.7.4
           python -m pip install torch==2.10.0 --index-url https://download.pytorch.org/whl/cpu
       - name: Run pinned scientific menagerie
         env:
           TYWRAP_CODEC_PYTHON: python
+          TYWRAP_REQUIRE_TORCH_CONFORMANCE: '1'
         run: npm run test:menagerie
 
   os:
@@ -359,6 +417,8 @@ jobs:
     needs:
       - lint
       - test
+      - isolated-consumer
+      - pyodide-browser
       - python-suite-core
       - python-suite-data
       - living-app
@@ -373,6 +433,8 @@ jobs:
           fail=0
           if [ "${{ needs.lint.result }}" != "success" ]; then echo "::error::lint: ${{ needs.lint.result }}"; fail=1; fi
           if [ "${{ needs.test.result }}" != "success" ]; then echo "::error::test: ${{ needs.test.result }}"; fail=1; fi
+          if [ "${{ needs.isolated-consumer.result }}" != "success" ]; then echo "::error::isolated-consumer: ${{ needs.isolated-consumer.result }}"; fail=1; fi
+          if [ "${{ needs.pyodide-browser.result }}" != "success" ]; then echo "::error::pyodide-browser: ${{ needs.pyodide-browser.result }}"; fail=1; fi
           if [ "${{ needs.python-suite-core.result }}" != "success" ]; then echo "::error::python-suite-core: ${{ needs.python-suite-core.result }}"; fail=1; fi
           if [ "${{ needs.python-suite-data.result }}" != "success" ]; then echo "::error::python-suite-data: ${{ needs.python-suite-data.result }}"; fail=1; fi
           if [ "${{ needs.living-app.result }}" != "success" ]; then echo "::error::living-app: ${{ needs.living-app.result }}"; fail=1; fi

.github/workflows/published-consumer.yml

@@ -0,0 +1,46 @@
+name: Published consumer
+
+# Run only after both exact versions are public on npm and PyPI.
+# From the released repository ref:
+# gh workflow run published-consumer.yml --ref <release-ref> \
+#   -f npm_version=<exact-npm-version> -f pypi_version=<exact-pypi-version>
+on:
+  workflow_dispatch:
+    inputs:
+      npm_version:
+        description: Exact published tywrap version on npm
+        required: true
+        type: string
+      pypi_version:
+        description: Exact published tywrap-ir version on PyPI
+        required: true
+        type: string
+
+run-name: npm ${{ inputs.npm_version }} and PyPI ${{ inputs.pypi_version }}
+
+permissions:
+  contents: read
+
+jobs:
+  published-consumer:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+      - name: Install test runner
+        run: npm ci --ignore-scripts --prefer-offline --no-audit --no-fund
+      - name: Check published packages in a clean consumer
+        env:
+          CI: '1'
+          TYWRAP_CONSUMER_MODE: published
+          TYWRAP_PUBLISHED_NPM_VERSION: ${{ inputs.npm_version }}
+          TYWRAP_PUBLISHED_PYPI_VERSION: ${{ inputs.pypi_version }}
+        run: npx vitest run --config vitest.isolated-consumer.config.ts

ROADMAP.md

@@ -8,6 +8,17 @@ The scientific codec envelope reference lives in
 
 ## Recent releases
 
+### v0.10.0: scientific codec correctness
+
+`v0.10.0` shipped on 13 July 2026. Scientific values now compose inside
+containers, and decoded envelopes validate their shape, dtype, and provenance.
+JSON ndarray and pandas conversions reject values they cannot preserve.
+Torch bfloat16 values use exact float32 storage, and Arrow supports scalar arrays.
+The pinned scientific menagerie checks the supported cases and explicit failures.
+
+The Python package stayed at `tywrap-ir` 0.3.0 with IR schema 0.4.0.
+See [the changelog](./CHANGELOG.md#0100-2026-07-13) for compatibility details.
+
 ### v0.9.0: typed value-RPC
 
 `v0.9.0` narrowed tywrap to one job done well: typed value-RPC between
@@ -113,9 +124,24 @@ and bridge live.
 
 ## Now
 
-The typed value-RPC contract pass (#260) is complete as of `v0.9.0`, and the
-scientific data plane (#237) as of `v0.8.0`. The next release theme is not yet
-locked; candidates are drawn from **Later** below.
+The next planned release is `v0.11.0`, tracked in #342 and #334. It must reject
+unsafe Python integers before JSON encoding and decode Arrow float16 storage
+as numeric values. Generated wrappers must pass a clean consumer installation
+test with the candidate npm and Python packages.
+
+Architecture work in #345 joins callable resolution with shared value contracts.
+Its proof covers safe integers, float16 arrays reused by Torch, and overloads
+that return nested records. Independent tests must exercise generation,
+TypeScript compilation, execution, decoding, and return validation.
+
+Overload preservation and coroutine execution have separate acceptance criteria
+in #336 and #338. Actual Pyodide and browser tests in #341 must pass before any
+browser coroutine claim. The release scope will record only accepted behavior.
+
+Bigint transport, dataclass values, and explicitly bound clients remain bounded
+design prototypes in #337, #339, and #340. Completing their designs does not
+establish general production support. The current integer release policy remains
+rejection outside the JavaScript safe range.
 
 See [docs/codec-envelopes.md](./docs/codec-envelopes.md) for the scientific
 codec envelope reference.

docs/.vitepress/config.ts

@@ -27,6 +27,7 @@ export default defineConfig({
         text: 'Guide',
         items: [
           { text: 'Getting Started', link: '/guide/getting-started' },
+          { text: 'Migrating to 0.11', link: '/guide/migrating-to-0-11' },
           { text: 'Agent Adoption', link: '/guide/agent-adoption' },
           { text: 'Configuration', link: '/guide/configuration' },
           { text: 'Watch & Reload', link: '/guide/dev-reload' },

docs/guide/migrating-to-0-11.md

@@ -0,0 +1,132 @@
+# Migrating to 0.11
+
+This guide covers the planned 0.11 changes. The release is not published yet.
+
+## Large Python integers
+
+Python `int` results still use TypeScript `number`. The supported range is
+`-9007199254740991` through `9007199254740991`, inclusive.
+
+Earlier versions could round larger integers when JavaScript parsed the response.
+The new serializer rejects those values before writing JSON. This applies to root
+results, nested containers, supported NumPy scalars, and model dumps.
+
+For example, a result containing `{"items": [9007199254740993]}` now fails at
+`result.items[0]`. The error identifies the unsafe value and suggests an explicit
+string or an Arrow integer column.
+
+Return a string when the value represents an identifier or must remain an exact
+decimal integer:
+
+```python
+def large_identifier() -> str:
+    return str(9007199254740993)
+```
+
+The generated return type is `Promise<string>`. Convert that string with
+JavaScript `BigInt` if your application needs integer arithmetic. Validate any
+string that comes from an untrusted source before using it.
+
+Keep integer columns in Arrow tables when you need the existing Arrow int64
+representation. Arrow int64 remains exact and can decode as JavaScript `bigint`.
+JSON fallback does not provide that representation and rejects unsafe integers.
+
+Booleans and finite floats remain supported. Converting an integer to a Python
+`float` can lose precision before tywrap receives it. Use a string when exactness
+matters. Tagged bigint transport remains a separate design proposal.
+
+## NumPy and Torch float16
+
+The Arrow decoder now converts float16 storage words into their numeric values
+before reshaping the result. For example, `[15872, 49280]` becomes the intended
+`[1.5, -2.25]`. Remove application code that manually decodes those storage words.
+
+The conversion preserves signed zero, finite subnormal values, and finite extrema.
+NumPy arrays and nested Torch tensors use the same conversion. Non-finite results
+continue to reject under the existing policy.
+
+The scientific envelope format, JSON fallback, and Arrow int64 behavior stay
+compatible. Torch bfloat16 keeps its existing float32 transport conversion.
+
+## Return types that cannot be validated
+
+An unresolved Python `object` result now produces `Promise<unknown>`. Python
+objects can include strings and numbers, which TypeScript's `object` type excludes.
+
+An unresolved generic result also becomes `unknown`. Earlier wrappers could
+declare `Promise<T>` while accepting any returned value. A generic input remains
+generic, but its type alone cannot prove that Python returned the same type.
+This also applies when the unresolved type parameter appears in a nested result.
+
+Generation reports the unresolved conversion. `--fail-on-warn` rejects that
+diagnostic. Use a supported concrete return annotation or overload when the
+Python API has a known result type. Otherwise, check the value before using it:
+
+```ts
+const result = await generatedFunction(input);
+if (typeof result !== 'string') {
+  throw new TypeError('Expected a string result');
+}
+console.log(result.toUpperCase());
+```
+
+The current value contract does not resolve every Python annotation. For example,
+`Literal` results become `unknown`, while their existing literal checks remain.
+Other unresolved returns retain available marker, container or record checks.
+These partial checks do not prove a precise TypeScript return type.
+Type-only Protocol methods keep their declared generic signatures.
+
+Supported string and integer overloads retain their corresponding return types.
+Use Python 3.11 or later to extract registered overloads. Python 3.10 keeps the
+implementation signature when its typing module cannot expose the overloads.
+
+## Coroutine results
+
+The updated Node and Pyodide bridges await Python coroutine results. Generated
+wrappers use the function's resolved result type, such as `Promise<string>`.
+Upgrade the generator and runtime together, then regenerate wrappers.
+
+An HTTP client still depends on its server. Use a compatible server that awaits
+Python results; upgrading the TypeScript client does not update that server.
+
+## Regenerate wrappers
+
+After these versions are published, upgrade both packages:
+
+```bash
+npm install tywrap@0.11.0
+python3 -m pip install --upgrade tywrap-ir==0.3.1
+```
+
+Use the Python executable selected by `runtime.node.pythonPath` and
+`runtime.node.virtualEnv` instead of `python3` when your configuration differs.
+The new extractor captures generic parameters used only in overload annotations.
+Its IR schema remains `0.4.0`, so the schema check alone cannot detect an older
+extractor or an older saved contract.
+
+Extract fresh IR when regenerating:
+
+```bash
+npx tywrap generate --no-cache
+```
+
+This bypasses the on-disk IR cache. It does not replace existing cache entries.
+If you enable caching again, first remove the old generated IR files from
+`.tywrap/cache` so generation extracts and caches the updated contracts.
+
+If you use `contractInput`, temporarily omit it to extract fresh contracts with
+the updated Python package. Review each new `<module>.contract.json` in your
+output directory. Replace the corresponding pinned input file with that contract,
+or point `contractInput` to the new file. Then restore the setting.
+The `--no-cache` option does not replace a pinned input contract.
+
+Regenerate wrappers with the upgraded generator. Python `int` return validators
+then check the safe integer range as well as the JavaScript value type.
+Regeneration also applies the reviewed callable-contract diagnostics.
+
+Update any tests that expected a rounded integer or float16 storage words.
+Assert the corrected value or the specific conversion error instead.
+
+Run your generated calls against the upgraded runtime before deploying them.
+An old wrapper cannot add the new generated return checks by itself, although the
+upgraded Python serializer still rejects unsafe integer results.