tests: OXT runtime self-test harness + docs: next-extensions plan & engine playbook#23
Merged
Merged
Conversation
Adds tests/torrent-selftest.livecodescript - the OXT-pass companion to the C++ smoke test. The smoke test proves the shim against libtorrent in CI; this proves the .lcb BINDING actually runs (the foreign-decl signatures, the record walkers, the Data<->Pointer buffer round-trips) - the one layer CI cannot reach, since OXT has no headless way to compile or run .lcb. Paste into a one-card stack's STACK script and close+reopen: it self-builds a UI, starts a session, and runs ~70 checks, then shows a green/red PASS/FAIL list with a summary. It exercises 71 of the 75 public handlers, including round-trips that prove end-to-end wiring: - create + seed a tiny temp torrent -> btFileList returns the file table - btAddWebSeed -> btWebSeeds lists it -> btRemoveWebSeed -> gone - btAddTracker -> btTrackers lists it - btInfoHash -> btFindTorrent recovers the same handle - btSessionPause -> btSessionIsPaused true -> btSessionResume - btDhtKeypair determinism; btDhtPutImmutable -> 40-hex target The four not auto-checked (btMoveStorage, btSetFilePriorities, btAddTorrentWithResume, plain btAddMagnet) are destructive / async / binary-buffer cases, noted in-app for a manual pass. The whole run is wrapped in try/catch, so a mis-declared foreign handler is REPORTED (which call, what error) instead of silently halting the stack - exactly the failure this harness exists to catch, and it doubles as a regression tool for future ABI bumps. check-livecodescript.py now also lints tests/ by default (so CI gates the harness too); verified statically (5 files OK, ASCII-clean, balanced handlers + try/catch, all 70 distinct bt* calls resolve to real public handlers). Needs an OXT run to exercise it for real - that is its whole point. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01371AXB4CUUke7enHHS8okc
…ybook Adds docs/NEXT-EXTENSIONS-PLAN.md - the implementation plan for the next three native wraps (the "secure decentralized real-time" stack on top of TorrentXT): libsodium (trust), ENet (reliable-UDP real-time), libdatachannel/libjuice (WebRTC + NAT traversal). It opens with Part I, a consolidated ENGINE PLAYBOOK that captures every OXT/LiveCode/LCB/FFI gotcha we have uncovered so the next wraps do not repeat them: - the three rules and how each library's threading model changes them (sodium has no threads; ENet is pump-driven; libdatachannel fires callbacks from its own threads -> a mutex-guarded poll queue is mandatory); - LiveCodeScript + LCB gotchas (ASCII-only; itemDelimiter global; no repeat-for-each-line in LCB; constants literal-before-use; unsafe brackets; declarations at handler top; Boolean<->CInt; ZStringUTF8); - the FFI contract (Data<->Pointer does not auto-bridge; the out-buffer bytes-written/-needed convention; no 64-bit foreign int; the getter -1 caveat); - the C-preprocessor macro-comma trap; the exception firewall; the record codec and gen-tagged handle tables; the no-unload-hook lifecycle; the single-thread performance playbook; and the toolchain gotchas (the ABI-version sync gate, committed per-platform binaries, the static gates, "verified statically"). Parts II-IV are the per-library plans (prefix/ABI, phased surface, library gotchas, testing, milestones). Part V covers sequencing, the shared oxtkit/ scaffolding to extract from TorrentXT, a risk register, and a per-library definition of done. Linked from the README documentation list. Plan only - no code/ABI change. ASCII-clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01371AXB4CUUke7enHHS8okc
SethMorrowSoftware
changed the title
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
2 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.
Two post-v8 follow-ups (the plan doc joined this PR before the harness merged — independent changes, both docs/tests only).
1.
tests/torrent-selftest.livecodescript— the OXT runtime self-test harnessThe OXT-pass companion to the C++ smoke test: it proves the
.lcbbinding actually runs (foreign-decl signatures, record walkers,Data↔Pointerround-trips) — the one layer CI can't reach. Paste into a one-card stack's stack script, reopen, and it self-builds a UI, starts a session, runs ~70 checks across 71 of 75 handlers (with real round-trips: create+seed →btFileList; add/list/remove web seed; info-hash →btFindTorrent; pause →btSessionIsPaused; keypair determinism), and shows a green/red PASS/FAIL list. The whole run istry-wrapped so a mis-declared handler is reported, not a silent halt — and it doubles as a regression tool for future ABI bumps.check-livecodescript.pynow lintstests/too, so CI gates it.2.
docs/NEXT-EXTENSIONS-PLAN.md— forward plan + engine playbookThe implementation plan for the next three native wraps — the "secure decentralized real-time" stack on top of TorrentXT:
Part I is the consolidated OXT/LiveCode engine playbook — every FFI / LCB / runtime gotcha we've uncovered (the
Data↔Pointernon-bridge, no 64-bit foreign int, the out-buffer convention, the macro-comma trap, norepeat-for-each-linein LCB, constants-before-use, the ABI-sync gate, the no-unload-hook lifecycle, the single-thread playbook, …) so the next wraps don't repeat them. Parts II–IV are per-library plans (prefix/ABI, phased surface, library-specific gotchas, testing, milestones); Part V is sequencing, the sharedoxtkit/scaffolding to extract, a risk register, and a definition of done. Linked from the README.Verification
check-livecodescriptpasses (5 files, incl. the harness); ASCII-clean; balanced handlers +try/catch; all 70 distinctbt*calls resolve.🤖 Generated with Claude Code
https://claude.ai/code/session_01371AXB4CUUke7enHHS8okc