phoxal-bundle

Persisted runtime bundle contract for Phoxal.

phoxal-manifest compiles authored YAML/URDF into canonical source facts. Build tooling combines those facts with selected binaries and participant metadata to construct one [RuntimeDocument]. Runtime participant instances select reusable executable artifacts, so one staged binary can implement more than one component-bound process. BundleWriter streams those executable sources into a canonical executable mode and persists the document as runtime.json beside the indexed assets/ and supervisor-only bin/ trees. RuntimeBundle::open_verified validates the complete artifact and its schema, canonical model, participant set, artifact contracts, embedded config schemas, normalized paths, canonical file modes, file sizes, and SHA-256 digests. BundleWriter pins each executable source descriptor, assembles through descriptor-relative no-follow writes in a private sibling directory, verifies that candidate completely, and only then publishes with a no-replace rename syscall; an existing target (including any symlink below it) is refused, so a failed build cannot modify an installed bundle or escape its root. Linux uses renameat2 with RENAME_NOREPLACE; macOS uses renameatx_np with RENAME_EXCL. Other targets fail closed rather than falling back to a check-then-rename race.

The reader has no source-parser or catalog dependency. A supervisor or builder uses RuntimeBundle::open_verified to verify the complete installed artifact once. A participant uses ParticipantBundle::open to select one typed ParticipantId record before opening its bus; it verifies its running image against the selected artifact and checks participant assets lazily rather than re-hashing unrelated binaries. The process receives one validated ParticipantRuntimeInputs value. Assets are logical and digest checked from the same owned file descriptor that is consumed. On Unix, the root directory is pinned first; layout enumeration and every path component are then descriptor-relative, using fstatat/openat with O_NOFOLLOW. Targets without a robust native no-follow traversal currently return UnsupportedSecureOpen; they never downgrade to an lstat/open best-effort check. Binaries are never reachable through ParticipantAssets, and no trusted asset pathname API is exposed.