bare-operating-system/docs/deployment/OTA_AND_BUNDLES.md

OTA updates, bundles, and reproducible artifacts

Bare OS aligns with the Holepunch toolchain for shipping JavaScript as Bare bundles and (where applicable) Pear-style drives. This note ties upstream packages to operator workflows.

Also read: release-checklist.md · documentation home · PEAR-RUN.md for channel links.

Upstream primitives

Package	Role
bare-pack / bare-bundle	Resolve module graph → single bundle artifact (imports, resolutions, addons, assets).
bare-build	Platform packaging (desktop/mobile) around Bare runtimes.
bare-run	Cross-target execution of packed graphs for CI and device labs.
pear-pack / pear-bundle	Pear drive staging; prebuild maps for multi-arch.
pear-runtime (+ pear-runtime-updater)	Embeddable OTA patterns (experimental upstream; mirror concepts in boot policy).

Bare OS integration

• System image: kernel/ is staged to the system Hyperdrive by bare-os-seeder; the booter never falls back to a git checkout for production boot.
• Ctx / API semver: bump BARE_OS_CTX_API_VERSION when guest-visible ctx behavior changes; record it in compatibility-matrix.md.
• Offline / LKG: document BARE_OS_OFFLINE_LKG_BOOT and related env in environment appendix.
• Warm cache + proc: bareOsVfsBatchWrite clears /bin / /lib/bare warm read caches and increments vfs.warm_read_cache_invalidate_batch; the same path clears the cached /proc/bare_os/syscalls.json text so replication swaps cannot serve stale syscall metadata. With BARE_OS_VFS_WARM_CACHE_INVALIDATE_ON_REPLICATION, core-length growth triggers ctx.bareOsInvalidateWarmReadCaches('replication:core-length') and increments vfs.replication_warm_full_invalidate in kernelCounters. ctx.bareOsCorestoreSnapshotHint() increments operator.corestore_snapshot_hint for operator dashboards.
• Corestore snapshot E2E: host/seeder tooling may set BARE_OS_SEED_CORESTORE_SNAPSHOT_TAG, BARE_OS_SEED_SNAPSHOT_HINTS_JSON, BARE_OS_CORESTORE_SNAPSHOT_STATE_JSON, and BARE_OS_CORESTORE_SNAPSHOT_PAUSED; the stock booter mirrors a bounded sketch under /proc/bare_os/corestore_snapshot.json (wave-6 replication operator surface) and **disk.os replication_operator_sketch** corestoreSnapshotPaused. Guests read hints only — cutover verification stays on the host.
• Hyperblobs / dedup: when BARE_OS_VFS_HYPERBLOBS_DEDUP is enabled, operators may supply BARE_OS_HYPERBLOBS_STATS_JSON; the booter merges hyperblobsDedupSketch into **disk.os replication_operator_sketch** for fleet dashboards (no guest chunking).
• Corestore operator stats: optional BARE_OS_CORESTORE_STATS_JSON merges corestoreOperatorSketch into replication_operator_sketch (schema 5); keep payloads non-secret (counts and hints only).
• Local Holepunch clones: after patching bare-* sources from a local holepunchto_repos checkout, rebuild with npm run build -w bare-os-bare-libs, mirror kernel/ → packages/bare-os-seeder/kernel/, refresh docs/audit/bundle-health.json, and re-run npm test (see kernel/lib/bare/README.md).
• Extension signer pins: when BARE_OS_BOOT_POLICY=1, the stock kernel copies extensionSignerPinsV2…V5 from boot.policy into ctx.env as BARE_OS_BOOT_POLICY_EXTENSION_SIGNER_PINS_V2_JSON … _V5_JSON (stringified objects). Treat pin churn like ABI bumps — run npm run pretest (verify-boot-policy-extension-signer-pins.mjs, extension manifest schema, capability verifiers) after edits.

Reproducibility checklist

1. Pin workspace dependency versions (lockfile).
2. Run npm run pretest before tag (bundle kernel, verify seeder parity, manifest smoke).
3. Record bareOsCtxApiVersion, BARE_OS_KERNEL_FEATURE_BITS_DOC, and BARE_OS_LIFECYCLE_SCHEMA_VERSION in release notes (see compatibility matrix).

Future work

Delta OTA, A/B slots, and signed rollback indices are roadmap items; track against kernel program batches and capability words.