Developer manual

The current branch is a draft local/cloud integration candidate. Start with the CONTRIBUTING.md and docs/host-retirement.md. Original Lite updates require verified resource identity and explicit confirmation that all competitions have completed on the installed version. Published cloud-v1 installations require their matching release or a separate environment/database; this branch does not migrate their data automatically.

Prepare and run

git submodule update --init --recursive
bun install --frozen-lockfile --ignore-scripts
bun run build:host
make local LOCAL_ARGS="--no-build"

Bun 1.3.11 is pinned. The host serves the organizer and participant applications and persists competition state in SQLite. Use a private dedicated data directory. Docker problem execution requires Docker; the built-in Battle runs in Bun. AWS-service problems are cloud-only. Lambda + Turso/DynamoDB hosting and the full cloud lifecycle remain under verification.

Code ownership

Verify

Run bun run test:host, bun run test:authoring, bun run typecheck and make before-commit. Keep existing lint and coverage thresholds. Test the real HTTP/SQLite path for state and authorization changes. Follow the docs/host-build-verification.md for distribution changes. Record browser and optional live AWS/IdP evidence separately; local tests do not prove external account access.

make down preserves local event and Docker data. Cloud make deploy / make destroy call the existing CLI with reviewed AWS setup and ownership-checked teardown. Cloud hosting uses Lambda and Cognito, selectable Turso or DynamoDB, generic CloudFormation deployment, flag/multi-flag and scheduled scoring, participant Console/CLI access, and native coordination including Cryptography Battle. Docker/Compose exercises are local-only and are not listed in the cloud catalog. Live AWS and hosted Turso event capacity remain unverified. Use CLOUD_ARGS="--help" to inspect either command without AWS access.

New installations use tenkacloud-cloud stack names; existing tenkacloud-lite stacks keep their names. The CLI discovers Lite/cloud installations; if both exist, explicitly choose TENKACLOUD_STACK_LAYOUT=lite or cloud. Original Lite updates verify ownership and persistent resource IDs. Original unpinned Lite installations require a one-time confirmation that no active competitions remain, after resource/schema checks and before bootstrap, source upload or deployment. Keep active competitions on their installed version until completion. After verifying that condition, confirm interactively or use CLOUD_ARGS="--confirm-no-active-events" for a noninteractive upgrade; generic --yes cannot bypass this check. A legacy catalog key alone does not prove a safe upgrade, and historical data is not migrated automatically. New and already-restored installations keep ordinary automatic make deploy behavior. Published cloud-v1 resource/database layouts cannot be updated in place, and no data is migrated automatically. --drain-events is unavailable; finish event Teardown before removing the platform.

Both databases admit 99 teams; SQL coordination retains the original 4 MiB state policy. Nine current catalog templates exceed the 51,200-byte TemplateBody limit, and TemplateURL is not implemented. This is not an all-AWS-problems deployment claim.

Cloud events and deployments save catalogKey for a private snapshot of catalog maps, hints, plugins and raw sources. An event created with catalog A continues using A after B is deployed or removes its problem. Lambda verifies pinned source hashes; CodeBuild uses the saved source ZIP key and exact S3 VersionId. Older unpinned records require recovery of their verified original snapshot through CDK_LEGACY_CATALOG_KEY; never assign the current catalog by guesswork. This recovery setting does not authorize upgrading an active original installation; finish its competitions on the installed version and satisfy the no-active-events preflight first.

Each cloud deployment uploads a fresh <configured-key>.executions/<uuid>.zip and requires source-bucket versioning. Current unique keys are not removed by the noncurrent-version lifecycle. Archives consume storage until separately reviewed source-bucket cleanup after referencing events finish. Platform destroy removes its owned execution snapshots, while the separate source archive bucket survives. Source tests and synthesis do not establish a live AWS or hosted Turso rehearsal.