SDK and distribution engineering

Use the SDK guide for client usage and the release qualification guide for packaging and evidence.

Build the distributions

From a source installation, bun run release:package creates source.tar.gz, runtime.tar.gz, and sdks.tar.gz under dist/release. The source archive includes the engine, CLI, dashboard source, tests, SDK source, docs, and package configuration. The runtime archive includes the engine, CLI, migrations, public contracts, docs, and built dashboard. SDK archives contain the TypeScript npm tarball and Python wheel and source distribution. These are local artifacts; packaging does not publish to npm or PyPI.

handoff.json records expanded inventories and archive byte hashes. Packaging refuses to replace an existing handoff; choose a new directory with --out for another build. Retain the previous result when correcting a failed release.

bun run release:package
bun run release:handoff
WORLDSEQ_TEST_DATABASE_URL="$LOCAL_TEST_DATABASE" bun run release:smoke -- --out /new/smoke-receipts

release:handoff checks the expanded files and archive bytes against the manifest and current executable identity. release:smoke performs clean source/runtime installs, Node 22/24/Bun SDK consumer tests, Python 3.11–3.14 wheel tests, a Python source-distribution install, a pinned Linux Bun container install, and live SDK lifecycle examples against the packaged server and a real test database. It retains logs and a receipt and fails if a required tool or interpreter is missing. The live examples create three short development episodes; use a dedicated test PostgreSQL database for LOCAL_TEST_DATABASE.

Source identity uses canonical workspace/... paths rooted in this application. Moving an unchanged package preserves its content identity. Runtime version, operating system, architecture, and pinned OCI image references remain bound separately. Archive inventories also bind installer files, dashboard assets, tests, SDKs, and documentation. File hashes do not provide a sandbox against the host’s operator, and a declared compatibility target is not a passing test result.

Check a source installation

bun install --frozen-lockfile --ignore-scripts
bun run check

check runs sdk:install before typed lint so the separately locked TypeScript SDK and code-generation tools are available. For a manual lint run in a fresh checkout, use bun run sdk:install && bun run lint; lint itself does not install dependencies. Exact packages need network access unless already cached.

SDK generation and Python development checks additionally require uv. SDK consumers do not need that generation toolchain. If typed lint exhausts Node’s heap, a per-command NODE_OPTIONS=--max-old-space-size=1536 is an option only when the runner has enough memory for the heap and runtime overhead.

Engineering checks

These checks protect the interfaces while changing their implementation.

• Generate clients from the explicit public DTO/schema projection. Do not export engine state or verifier modules into SDK packages. Relational checks and finalization remain server-authoritative; successful JSON validation is not task eligibility.
• Preserve JSON wire strings for constrained ISO timestamps and UUIDs in generated Pydantic models. Combining a parsed datetime with a string regex fails at runtime even when generator and import checks pass. Keep full JSON Schema format validation and test actual payloads, not only mocked receipts.
• Keep mutation keys and revisions unchanged. Never automatically retry an ambiguous request with a new key. Player and operator interfaces and credentials remain separate.
• Test installed wheel/tgz artifacts from clean directories, then run the published examples against the packaged server. Unit mocks missed both a generated date-type incompatibility and an example’s pagination signature mismatch.
• Bind standalone execution to application-local runtime dependency manifests and canonical relative paths. Verify archive bytes separately from expanded files. Run final distribution checks from an immutable installed copy; active edits to the main checkout should invalidate a checkout-bound release receipt.
• Stream archives into isolated Linux smoke containers when possible instead of bind-mounting a monorepo. This avoids depending on host file-sharing limits and prevents accidental access to unrelated workspace files.
• A malformed, oversized, redirected, or server-error response does not prove a sent mutation was rejected. Preserve uncertainty in the SDK error even when response validation fails; an explicitly cancelled call before dispatch is different.
• Prefix Bun test directories with ./ to constrain discovery to those directories. Bare names are filters and can accidentally discover SDK consumer tests that require a separate build. Preserve examples when copying the application for isolated tests.