# 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](../release-checklist.md) · [documentation home](../README.md) · [PEAR-RUN.md](../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](../reference/compatibility-matrix.md).
- **Offline / LKG**: document **`BARE_OS_OFFLINE_LKG_BOOT`** and related env in [environment appendix](../reference/environment-and-posix-appendix.md).
- **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`](../../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](../../handbook/11-kernel-program-and-research.md) batches and capability words.