Verify plugin wire protocol declarations

[gabek]

This adds an executable contract check for the plugin wire protocol and corrects the SDK declarations and examples that had drifted from the host implementation.

• Compare every JavaScript and Python host import with the core contract
• Correct parameter and pointer signatures and binary-safe Python handling
• Add focused scenario coverage for registration and binary uploads

Focused verification passed for issue #5080.

The contract test covers all 46 JavaScript and Python imports. I also ran the SDK Go tests and focused JavaScript and Python scenario suites.

This branch is based on the SQL SDK change already on the stack where required. It does not change unrelated plugin behavior.

Fixes owncast/owncast#5080

[Copilot]

Pull request overview

This PR adds an executable “drift/contract” check for host-function stack signatures and updates the JS/Python SDKs, docs, and scenario tooling to match the host wire protocol—most notably adding storage.sql, correcting users.register fields, and making storage/asset/file operations binary-safe in Python.

Changes:

• Added a host-runtime contract test that derives host-function stack signatures from the Go runtime and verifies the JavaScript and Python shared-engine declarations match.
• Introduced storage.sql across host-runtime (dev/test/demo), JS/Python SDK facades, permissions, and new worked examples + scenarios.
• Corrected/expanded users.register request shapes and improved scenario expectation handling (presence-sensitive optional fields and binary upload assertions).

Reviewed changes

Copilot reviewed 56 out of 61 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
sdks/python/README.md	Updates Python SDK permission/API table and documents binary-safe read/write/upload behaviors.
sdks/python/owncast_plugin/template/AGENTS.md	Adds guidance for storage.sql usage/limits in the Python template agent notes.
sdks/python/owncast_plugin/template/.agents/skills/create-owncast-plugin-py/SKILL.md	Updates plugin-authoring skill docs to include storage.sql guidance.
sdks/python/owncast_plugin/init.py	Makes Python fs/assets/storage binary-safe, adds owncast.sql facade, expands users.register fields.
sdks/js/index.js	Adds storage.sql permission + SDK facade, updates users.register request mapping, adjusts fs path docs.
sdks/js/index.d.ts	Adds storage.sql types and API, expands UserRegisterRequest, updates fs path docs.
sdks/js/create-owncast-plugin/template/AGENTS.md	Adds storage.sql guidance to JS template agent notes.
sdks/js/create-owncast-plugin/template/.agents/skills/create-owncast-plugin-js/SKILL.md	Updates plugin-authoring skill docs to include storage.sql guidance.
host-runtime/sqlstore/sqlstore.go	Adds pure-Go SQLite store used by non-production hosts to support storage.sql.
host-runtime/sqlstore/sqlstore_test.go	Tests that the pure-Go SQL store enforces the same value-size limit as production.
host-runtime/plugin/testing/sql.go	Wires the SQL store into the scenario/mock host environment.
host-runtime/plugin/testing/sql_test.go	Adds scenario host SQL tests for isolation, limits, error normalization, and refusals.
host-runtime/plugin/testing/scenario.go	Makes user registration expectations presence-sensitive; adds base64 upload expectation field.
host-runtime/plugin/testing/scenario_test.go	Adds tests pinning “presence vs omitted” behavior for optional fields and upload base64 assertions.
host-runtime/plugin/testing/runner.go	Cleans up per-scenario SQL lifecycle and adds base64 upload expectation comparisons.
host-runtime/plugin/testing/mocks.go	Records expanded user registration fields and exposes SQL host env functions in the mock host.
host-runtime/main.go	Wires storage.sql into the demo host and updates storage.fs path docs.
host-runtime/host_function_contract_test.go	Adds a contract test to validate JS/Python engine declarations match Go-derived host ABI.
host-runtime/go.sum	Updates module sums for new dependencies (notably modernc SQLite).
host-runtime/go.mod	Adds modernc SQLite and updates Owncast dependency version and indirect deps.
host-runtime/cmd/owncast-plugin-serve/main.go	Switches dev storage root path and wires in storage.sql via the in-memory SQL store.
examples/python/README.md	Adds the Python chat-leaderboard SQL example to the example index.
examples/python/github-auth/src/plugin.py	Updates to pass new verified-profile metadata fields to users.register.
examples/python/github-auth/README.md	Documents updated users.register signature and public guidance.
examples/python/github-auth/tests/auth.test.json	Updates scenario fixtures to include html_url + expanded users.register expectation fields.
examples/python/file-manager/src/plugin.py	Updates docs/comments to new plugin-storage/<slug>/files/ fs layout.
examples/python/file-manager/README.md	Updates docs to new plugin-storage/<slug>/files/ fs layout.
examples/python/file-manager/public/admin/index.html	Updates UI hint text for new storage path.
examples/python/file-manager/INSTRUCTIONS.md	Updates instructions to new storage path.
examples/python/chat-leaderboard/src/plugin.py	Adds a Python SQL worked example implementing leaderboard ranking with bounded queries.
examples/python/chat-leaderboard/README.md	Documents the SQL leaderboard example and host-enforced limits/semantics.
examples/python/chat-leaderboard/plugin.manifest.json	Adds manifest for the new Python SQL example with storage.sql permission.
examples/python/chat-leaderboard/INSTRUCTIONS.md	Adds operator-facing instructions for the Python SQL example.
examples/python/chat-leaderboard/tests/chat-leaderboard.test.json	Adds scenario coverage for ranking, tie ordering, reset atomicity, and moderator gating.
examples/python/all-permissions-test/src/plugin.py	Adds a focused binary round-trip scenario via assets/fs/upload to guard byte correctness.
examples/python/all-permissions-test/README.md	Documents the new focused binary scenario and its purpose.
examples/python/all-permissions-test/plugin.manifest.json	Adds storage.sql permission to the Python all-permissions canary manifest.
examples/python/all-permissions-test/tests/binary.test.json	Adds scenario asserting invalid UTF-8 survives assets/fs/upload round-trip.
examples/js/README.md	Adds the JS chat-leaderboard SQL example to the example index.
examples/js/github-auth/src/plugin.js	Updates to pass new verified-profile metadata fields to users.register.
examples/js/github-auth/README.md	Documents updated users.register signature and public guidance.
examples/js/github-auth/tests/auth.test.json	Updates scenario fixtures to include html_url + expanded users.register expectation fields.
examples/js/file-manager/src/plugin.js	Updates docs/comments to new plugin-storage/<slug>/files/ fs layout.
examples/js/file-manager/README.md	Updates docs to new plugin-storage/<slug>/files/ fs layout.
examples/js/file-manager/public/admin/index.html	Updates UI hint text for new storage path.
examples/js/file-manager/INSTRUCTIONS.md	Updates instructions to new storage path.
examples/js/chat-leaderboard/src/plugin.js	Adds a JS SQL worked example implementing leaderboard ranking with bounded queries.
examples/js/chat-leaderboard/README.md	Documents the SQL leaderboard example and host-enforced limits/semantics.
examples/js/chat-leaderboard/plugin.manifest.json	Adds manifest for the new JS SQL example with storage.sql permission.
examples/js/chat-leaderboard/package.json	Adds package for the new JS SQL example wired to local @owncast/plugin-sdk.
examples/js/chat-leaderboard/package-lock.json	Adds lockfile for the new JS SQL example.
examples/js/chat-leaderboard/INSTRUCTIONS.md	Adds operator-facing instructions for the JS SQL example.
examples/js/chat-leaderboard/tests/chat-leaderboard.test.json	Adds scenario coverage for ranking, tie ordering, reset atomicity, and moderator gating.
examples/js/all-permissions-test/plugin.manifest.json	Adds storage.sql permission to the JS all-permissions canary manifest.
engines/javascript/engine.d.ts	Adds owncast_sql_exec/owncast_sql_query imports to the shared JS engine declaration.
engines/build_py.py	Updates Python engine import declarations for binary-safe types and adds SQL host imports.
docs/WIRE_PROTOCOL.md	Expands and corrects wire protocol documentation (ABI types, binary pointers, SQL, signatures).
docs/PLUGIN_AUTHOR_GUIDE.md	Updates author docs for binary safety, new storage.sql, and expanded users.register.
docs/ARCHITECTURE.md	Updates architecture docs around payload types, permission enforcement, and SQL host differences.
.github/workflows/examples-js.yml	Ensures Go tests run when building host binaries for JS example workflows.

Files not reviewed (1)

• examples/js/chat-leaderboard/package-lock.json: Generated file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.