Merge pull request #122 from harvard-lil/fat-binoc-distribution

Fat binoc: bundle format packs, pause per-plugin publishing, add ABI canary (v0.2.0)

Author: jcushman

.github/workflows/publish.yml

@@ -4,8 +4,9 @@ on:
   push:
     tags:
       - "binoc-v*"
-      - "binoc-sqlite-v*"
-      - "binoc-stat-binary-v*"
+      # binoc-sqlite and binoc-stat-binary publishing is paused; both ship
+      # in-process via the fat `binoc` wheel. See
+      # docs/adr/2026-06-30-fat_binoc_distribution_and_abi_canary.md.
       - "binoc-sdk-v*"
   workflow_dispatch:
 
@@ -107,180 +108,6 @@ jobs:
         with:
           packages-dir: dist
 
-  build-binoc-sqlite-wheels:
-    name: Build binoc-sqlite wheels (${{ matrix.artifact }})
-    if: startsWith(github.ref_name, 'binoc-sqlite-v')
-    runs-on: ${{ matrix.os }}
-    permissions:
-      contents: read
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - os: ubuntu-latest
-            artifact: linux-x86_64
-            target: x86_64-unknown-linux-gnu
-            manylinux: auto
-            interpreter: python3.10
-          - os: windows-latest
-            artifact: windows-x86_64
-            target: x86_64-pc-windows-msvc
-            manylinux: off
-            interpreter: python
-          - os: macos-15-intel
-            artifact: macos-x86_64
-            target: x86_64-apple-darwin
-            manylinux: off
-            interpreter: python
-          - os: macos-14
-            artifact: macos-aarch64
-            target: aarch64-apple-darwin
-            manylinux: off
-            interpreter: python
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
-        with:
-          python-version: "3.10"
-      - uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1
-        with:
-          command: build
-          working-directory: model-plugins/binoc-sqlite
-          target: ${{ matrix.target }}
-          manylinux: ${{ matrix.manylinux }}
-          args: --release --interpreter ${{ matrix.interpreter }} --out dist
-          sccache: "true"
-      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: binoc-sqlite-dist-${{ matrix.artifact }}
-          path: model-plugins/binoc-sqlite/dist
-
-  build-binoc-sqlite-sdist:
-    name: Build binoc-sqlite sdist
-    if: startsWith(github.ref_name, 'binoc-sqlite-v')
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1
-        with:
-          command: sdist
-          working-directory: model-plugins/binoc-sqlite
-          args: --out dist
-      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: binoc-sqlite-dist-sdist
-          path: model-plugins/binoc-sqlite/dist
-
-  publish-binoc-sqlite:
-    name: Publish binoc-sqlite to PyPI
-    if: startsWith(github.ref_name, 'binoc-sqlite-v')
-    runs-on: ubuntu-latest
-    needs: [build-binoc-sqlite-wheels, build-binoc-sqlite-sdist]
-    environment:
-      name: pypi-binoc-sqlite
-      url: https://pypi.org/project/binoc-sqlite/
-    permissions:
-      contents: read
-      id-token: write
-    steps:
-      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          pattern: binoc-sqlite-dist-*
-          path: dist
-          merge-multiple: true
-      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
-        with:
-          packages-dir: dist
-
-  build-binoc-stat-binary-wheels:
-    name: Build binoc-stat-binary wheels (${{ matrix.artifact }})
-    if: startsWith(github.ref_name, 'binoc-stat-binary-v')
-    runs-on: ${{ matrix.os }}
-    permissions:
-      contents: read
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - os: ubuntu-latest
-            artifact: linux-x86_64
-            target: x86_64-unknown-linux-gnu
-            manylinux: auto
-            interpreter: python3.10
-          - os: windows-latest
-            artifact: windows-x86_64
-            target: x86_64-pc-windows-msvc
-            manylinux: off
-            interpreter: python
-          - os: macos-15-intel
-            artifact: macos-x86_64
-            target: x86_64-apple-darwin
-            manylinux: off
-            interpreter: python
-          - os: macos-14
-            artifact: macos-aarch64
-            target: aarch64-apple-darwin
-            manylinux: off
-            interpreter: python
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
-        with:
-          python-version: "3.10"
-      - uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1
-        with:
-          command: build
-          working-directory: model-plugins/binoc-stat-binary
-          target: ${{ matrix.target }}
-          manylinux: ${{ matrix.manylinux }}
-          args: --release --interpreter ${{ matrix.interpreter }} --out dist
-          sccache: "true"
-      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: binoc-stat-binary-dist-${{ matrix.artifact }}
-          path: model-plugins/binoc-stat-binary/dist
-
-  build-binoc-stat-binary-sdist:
-    name: Build binoc-stat-binary sdist
-    if: startsWith(github.ref_name, 'binoc-stat-binary-v')
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1
-        with:
-          command: sdist
-          working-directory: model-plugins/binoc-stat-binary
-          args: --out dist
-      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: binoc-stat-binary-dist-sdist
-          path: model-plugins/binoc-stat-binary/dist
-
-  publish-binoc-stat-binary:
-    name: Publish binoc-stat-binary to PyPI
-    if: startsWith(github.ref_name, 'binoc-stat-binary-v')
-    runs-on: ubuntu-latest
-    needs: [build-binoc-stat-binary-wheels, build-binoc-stat-binary-sdist]
-    environment:
-      name: pypi-binoc-stat-binary
-      url: https://pypi.org/project/binoc-stat-binary/
-    permissions:
-      contents: read
-      id-token: write
-    steps:
-      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          pattern: binoc-stat-binary-dist-*
-          path: dist
-          merge-multiple: true
-      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
-        with:
-          packages-dir: dist
-
   publish-binoc-sdk:
     name: Publish binoc-sdk to crates.io
     if: startsWith(github.ref_name, 'binoc-sdk-v')

Cargo.lock

@@ -5,6 +5,7 @@ members = [
     "binoc-stdlib",
     "binoc-cli",
     "binoc-python",
+    "binoc-abi-canary",
     "model-plugins/binoc-sqlite",
     "model-plugins/binoc-row-reorder",
     "model-plugins/binoc-stat-binary",
@@ -21,6 +22,7 @@ default-members = [
     "binoc-core",
     "binoc-stdlib",
     "binoc-cli",
+    "binoc-abi-canary",
     "model-plugins/binoc-sqlite",
     "model-plugins/binoc-row-reorder",
     "model-plugins/binoc-stat-binary",

Cargo.toml

@@ -0,0 +1,28 @@
+[package]
+name = "binoc-abi-canary"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+homepage.workspace = true
+documentation.workspace = true
+description = "ABI canary: a native renderer built as a cdylib and loaded over the plugin C ABI in tests, so the boundary stays compiler/linker-enforced"
+publish = false
+
+[lib]
+name = "binoc_abi_canary"
+crate-type = ["cdylib", "rlib"]
+
+# `export_plugin!` emits a `#[cfg(feature = "python")]` pymodule. This crate
+# deliberately has no `python` feature (no pyo3); tell check-cfg the value is
+# expected rather than declaring a feature that would fail to build if enabled.
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(feature, values("python"))'] }
+
+[dependencies]
+binoc-sdk = { workspace = true }
+serde_json = { workspace = true }
+
+[dev-dependencies]
+libloading = "0.9.0"

binoc-abi-canary/Cargo.toml

@@ -0,0 +1,49 @@
+//! ABI canary: a native renderer exported over the plugin C ABI.
+//!
+//! This crate exists to keep the renderer ABI boundary *honest*. It is a real,
+//! separately-compiled `cdylib` that goes through [`binoc_sdk::export_plugin!`],
+//! and [`tests/abi_crossing.rs`](../tests/abi_crossing.rs) loads the built
+//! artifact over `libloading` — the same path `binoc-python` uses — and asserts
+//! a render round-trips.
+//!
+//! Why this matters: compiling plugins in-process (the fat-`binoc` wheel) means
+//! the compiler no longer forces plugin-facing types to be expressible across a
+//! process boundary. This crate restores that guarantee for the stable
+//! (renderer) tier: if the renderer ABI drifts to something that cannot cross
+//! `extern "C"` + JSON, `export_plugin!` fails to compile here, and if the wire
+//! contract drifts, the crossing test fails to load or round-trip. It is also
+//! the template each rule family must satisfy when it graduates into
+//! `plugin_abi`. See
+//! `docs/adr/2026-06-30-fat_binoc_distribution_and_abi_canary.md`.
+
+use binoc_sdk::{BinocResult, Changeset, Renderer, RendererDescriptor};
+
+/// A trivial renderer that echoes a few open-vocabulary IR fields back as JSON.
+/// Its only job is to exercise the real `cdylib` → `libloading` crossing.
+#[derive(Default)]
+pub struct EchoRenderer;
+
+impl Renderer for EchoRenderer {
+    fn descriptor(&self) -> RendererDescriptor {
+        RendererDescriptor::new("canary.echo", "json")
+    }
+
+    fn render(&self, changesets: &[Changeset], config: &serde_json::Value) -> BinocResult<String> {
+        let root_action = changesets
+            .first()
+            .and_then(|changeset| changeset.root.as_ref())
+            .map(|root| root.action.clone())
+            .unwrap_or_else(|| "none".to_string());
+        Ok(serde_json::json!({
+            "changesets": changesets.len(),
+            "root_action": root_action,
+            "mode": config.get("mode"),
+        })
+        .to_string())
+    }
+}
+
+binoc_sdk::export_plugin! {
+    module: binoc_abi_canary,
+    renderers: [EchoRenderer],
+}