# Development source handoff

`tools/source_bundle.py` assembles the single combined successor project into a deterministic **DEVELOPMENT SOURCE BUNDLE**. This is an editable ZIP, not a native `.pak`, an engine build, a qualified release or a Workshop publication. It does not launch tools, load accounts or change acceptance records.

Preview is the default and writes no archive:

```sh
python3 tools/source_bundle.py
```

The JSON preview lists project identities/dependencies, payload count, byte size and SHA-256 of the exact ZIP it would write. An explicit destination creates a new archive, outside the source checkout, in an existing directory:

```sh
python3 tools/source_bundle.py --output /tmp/escapistsrereintroduced-development-source.zip
```

Existing destinations, symlinks, traversal and missing parent directories are refused. The complete payload is validated and assembled in memory first, then written to a temporary sibling and published with a no-overwrite atomic link. Validation/publication failures leave no new destination or temporary sibling. The command does not create output directories. Do not change the source tree while collecting a handoff; hashes are checked during collection, but this is not continuous filesystem surveillance.

## Included content and validation

The archive contains the exact authored bytes under `addons/core`, plus generated `BUNDLE-README.md`, `BUNDLE-MANIFEST.json` and `EXTERNAL-ADDONS.json`. The README explains opening the combined project, its vanilla and RHS/WCS dependencies, scenario identifiers, extraction into a new development folder and current validation limits. The manifest records all payload SHA-256 hashes (excluding its own self-reference), pinned project IDs/GUIDs and their complete dependency lists. No absolute source path, machine/user name or timestamp is embedded.

Project identities must match the maintained successor catalog and the single fixed identity in the tool. Dependencies are exactly vanilla plus the authorized RHS/WCS direct dependencies. Metadata GUIDs must be unique, refer to an included matching resource, and differ from vanilla identities. Referenced successor resources must be visible through the declared dependencies; vanilla and external resource references must match `docs/vanilla-resources.json` or the authorized `docs/external-addons.json` catalog. Original ecosystem symbols are rejected. These checks protect the known source structure; they cannot establish authorship or license rights for arbitrarily renamed/copied code. The repository's provenance review remains necessary.

The tool reuses the authored addon manifest helper, with a narrower packaging schema covering current text scripts, prefabs, configurations, world/layer, UI/material and resource metadata formats. An unknown asset format or unreviewed directory fails instead of silently dropping a newly required asset. Extend the reviewed schema when intentionally adding another asset kind. Vanilla assets are referenced, never copied from their installation.

Generated resource databases, `.pak`/`.log` files, `.git`, caches, profiles, runtime state, evidence, vendor/vanilla/original directories and other listed generated/private paths are excluded. Symlinks and nonregular source entries are refused. Repository documentation, original reference workspaces, accounts, engine installations, logs and evidence archives are not part of this payload. WORKBENCH-only native probes are included as authored addon source; their presence does not assert that they passed.

Sorted ZIP_STORED entries, fixed 1980 timestamps and fixed regular-file permissions make identical payloads produce identical bytes independent of source mtimes/permissions or output name. The manifest and external archive digest identify bytes, not publisher authenticity.

## Release requests remain gated

```sh
python3 tools/source_bundle.py --mode release --output /tmp/escapistsrereintroduced-qualified-source.zip
```

This invokes the existing `release_check.audit` before and after collection and refuses any outstanding gate. Current release acceptance is pending, so the command returns 1 without writing an archive. It cannot substitute development tests for the fixed release cases, modify the ledger or ignore native errors. Even a future fully passing audit still produces the same clearly labelled development source handoff, not an engine package or publication. Native build and distribution remain separate work.

## Tests

`python3 tests/test_source_bundle.py` exercises the real single-project tree in disposable copies: deterministic bytes and member hashes, timestamp/permission independence, exclusions, changed source, identity/dependency failures, resource visibility and metadata, unknown assets, symlinks/FIFOs, unsafe/case-colliding names, no-overwrite publication, publication cleanup, validation refusal with an output argument, concurrent collection mutation, preview and actual pending-release refusal. The tests create only temporary archives; no engine or network is used. This test is included in `tools/check.py`.