@radhya/mach 2.0.30 → 2.0.32

package/docs/ota-implementation-plan.md

@@ -0,0 +1,1004 @@
+# Mach OTA Implementation Plan
+
+## Goal
+
+Build a Mach-owned over-the-air update system for Expo and vanilla React Native apps without depending on EAS Update or App Center.
+
+Mach should own the update publish command, storage, release metadata, channel routing, runtime compatibility, dashboard history, rollback, and download URLs. Expo may be used as an open-source client/runtime only when the project is Expo or explicitly chooses `expo-updates`.
+
+## Current State Check
+
+### CLI
+
+Existing files:
+
+- `src/index.ts` registers `mach update`.
+- `src/commands/update.ts` implements the current OTA prototype.
+- `src/lib/config.ts` has a small `update` block with `channel` and `url`.
+- `README.md` lists `mach update`.
+
+Current `mach update` flow:
+
+1. Reads `mach.config.json`.
+2. Defaults channel to `production`.
+3. Uses `package.json` version as `runtimeVersion`.
+4. Runs `npx expo export --platform all`.
+5. Zips `dist/`.
+6. Uploads the zip with `/builds/source-upload-url`, which stores it as `builds/<updateId>/source.zip`.
+7. Calls `/updates/publish` twice, once for Android and once for iOS, both pointing `manifestKey` at the uploaded zip key.
+
+Problems:
+
+- It assumes every project is Expo.
+- It uses `expo export` for vanilla React Native, which is wrong.
+- It uploads a zip but tells the API it is a manifest.
+- It does not generate or upload individual immutable assets.
+- It does not produce a valid Expo Updates manifest.
+- It does not support vanilla RN client setup.
+- It does not support setup, verify, list, rollback, promote, rollout, or dashboard visibility.
+- It does not use build profile or latest successful Mach build runtime.
+- It has no native-change guard.
+- It uses `update` as the public command name, which is too generic.
+
+### API
+
+Existing files:
+
+- `mach-api/api/src/index.ts` defines `TABLE_UPDATES`.
+- `GET /api/manifest` returns an Expo-style manifest response.
+- `POST /updates/publish` stores update metadata.
+
+Current API behavior:
+
+1. Manifest route reads `expo-runtime-version`, `expo-channel-name`, and `expo-platform`.
+2. It scans `MachUpdates` by channel, platform, and runtime version.
+3. It sorts by `createdAt`.
+4. It reads `latestUpdate.manifestKey` from S3.
+5. It parses the S3 object body as JSON.
+
+Problems:
+
+- It does not filter by `projectId`, so updates can collide across projects.
+- It uses `ScanCommand`, not a query-friendly table/index.
+- It reads a zip uploaded by the CLI and tries to parse it as JSON.
+- It has no `GET /updates`, rollback, promote, disable, delete, or asset download routes.
+- It has no `MachUpdates` table setup script.
+- It does not support directives such as rollback-to-embedded for Expo.
+- It does not support a vanilla RN update protocol.
+- It does not expose low-cost immutable public asset URLs cleanly.
+
+### Dashboard
+
+Existing dashboard docs only mention `mach update` in the command list. There is no OTA updates screen, update history, rollback UI, rollout UI, channel UI, or runtime compatibility explanation.
+
+### Existing Mach Patterns To Reuse
+
+Deep-link automation already solved several UX problems that OTA should copy:
+
+- Compact Mach config.
+- Command flags have highest precedence.
+- Auto-detect framework when config is missing.
+- Prompt only for missing values.
+- Expo config plugin with packaged plugin preferred.
+- Local fallback plugin only when package plugin cannot be used.
+- `setup` runs `verify` at the end.
+- Dynamic Expo config is patched only when safe.
+
+Build framework adapters also provide a good pattern:
+
+- `src/lib/builds/frameworks/expo.ts`
+- `src/lib/builds/frameworks/react-native.ts`
+- `src/lib/builds/frameworks/types.ts`
+
+OTA should introduce a parallel adapter boundary rather than growing `src/commands/update.ts`.
+
+## External Constraints
+
+Expo:
+
+- `expo-updates` can point at a custom update server by setting `updates.url` and `runtimeVersion`.
+- The custom server must implement the Expo Updates protocol.
+- Expo update manifests include `id`, `createdAt`, `runtimeVersion`, `launchAsset`, `assets`, `metadata`, and `extra`.
+- Runtime version is the compatibility boundary between native binary and JS/assets.
+
+Vanilla React Native:
+
+- OTA can update JavaScript bundles and static assets only.
+- OTA must not be published when native files, native dependencies, pods, Gradle, permissions, entitlements, or manifest settings changed without a new binary.
+- Vanilla RN should not require Expo unless the user explicitly chooses `expo-updates`.
+
+CodePush/App Center:
+
+- App Center features, including CodePush service, were retired after March 31, 2025.
+- Microsoft published standalone CodePush server/client compatibility material, but those repos are archived.
+- Mach should not depend on App Center or treat CodePush as the core architecture.
+
+References:
+
+- https://docs.expo.dev/versions/latest/sdk/updates/
+- https://docs.expo.dev/technical-specs/expo-updates-1/
+- https://docs.expo.dev/eas-update/runtime-versions/
+- https://learn.microsoft.com/en-us/appcenter/retirement
+
+## Product Decision
+
+Use a new command namespace:
+
+```bash
+mach ota
+```
+
+Keep legacy compatibility:
+
+```bash
+mach update
+```
+
+`mach update` should become a deprecated alias for:
+
+```bash
+mach ota publish
+```
+
+Show a warning:
+
+```text
+mach update is deprecated. Use mach ota publish.
+```
+
+## Command Surface
+
+Primary commands:
+
+```bash
+mach ota setup
+mach ota publish
+mach ota verify
+mach ota list
+mach ota rollback
+mach ota promote
+```
+
+Useful flags:
+
+```bash
+mach ota setup --profile production
+mach ota setup --platform ios
+mach ota setup --platform android
+mach ota setup --engine expo-updates
+mach ota setup --engine mach-react-native
+mach ota setup --yes
+
+mach ota publish --channel production
+mach ota publish --profile production
+mach ota publish --platform all
+mach ota publish --message "Fix login crash"
+mach ota publish --runtime-version 1.2.0
+mach ota publish --rollout 10
+mach ota publish --mandatory
+mach ota publish --skip-native-check
+
+mach ota verify
+mach ota verify --live
+mach ota verify --native-check
+
+mach ota list --channel production
+mach ota rollback --channel production
+mach ota rollback --to <updateId>
+mach ota promote --from staging --to production --update-id <updateId>
+```
+
+`--skip-native-check` should be dangerous and explicit. It should require `--yes` in CI or confirmation interactively.
+
+## Config Shape
+
+Use a new `ota` block for clarity. Read legacy `update` as a backward-compatible alias, but migrate it during `mach ota setup`.
+
+Minimal generated config:
+
+```json
+{
+  "framework": "expo",
+  "projectId": "project-id",
+  "ota": {
+    "channel": "production"
+  }
+}
+```
+
+Full shape:
+
+```json
+{
+  "ota": {
+    "engine": "auto",
+    "channel": "production",
+    "runtimeVersionPolicy": "nativeFingerprint",
+    "runtimeVersion": null,
+    "url": "https://mach-api.securejs.in/api/ota/expo/project-id",
+    "checkAutomatically": "ON_LOAD",
+    "fallbackToCacheTimeout": 0,
+    "codeSigning": {
+      "enabled": false,
+      "keyId": "root"
+    },
+    "reactNative": {
+      "entryFile": "index.js",
+      "iosBundleOutput": "main.jsbundle",
+      "androidBundleOutput": "index.android.bundle"
+    }
+  }
+}
+```
+
+Keep config compact. Do not duplicate values already available elsewhere:
+
+- `projectId` from root config.
+- platform package/bundle identifiers from root `android` and `ios` config.
+- profile-specific platform settings from `build.<profile>`.
+- Expo `runtimeVersion` from app config when already present.
+
+Precedence:
+
+```text
+command flags
+> ota config
+> legacy update config
+> selected build profile
+> root mach.config.json
+> Expo app config/native files/package.json
+> prompts/defaults
+```
+
+## Engine Detection
+
+`ota.engine` should be optional.
+
+Supported values:
+
+```text
+auto
+expo-updates
+mach-react-native
+codepush-compatible
+```
+
+Initial implementation should support:
+
+- `expo-updates`
+- `mach-react-native`
+
+Later implementation may add:
+
+- `codepush-compatible`
+
+Detection rules:
+
+1. If command has `--engine`, use it.
+2. Else if `ota.engine` exists and is not `auto`, use it.
+3. Else if `framework` is `expo`, prefer `expo-updates`.
+4. Else if `framework` is `react-native`, prefer `mach-react-native`.
+5. Else inspect `package.json`, Expo config files, `ios/`, and `android/`.
+6. If ambiguous and interactive, ask.
+7. If ambiguous and non-interactive, fail with a clear message.
+
+Do not require users to set `engine` in normal projects.
+
+## Runtime Version Strategy
+
+Runtime version is required for OTA.
+
+Definition:
+
+```text
+The native runtime compatibility identifier for a build. An OTA update may only run on app binaries with the same runtime version.
+```
+
+Mach should support these policies:
+
+```text
+manual             use ota.runtimeVersion or --runtime-version
+appVersion         use app version
+nativeVersion      use app version plus iOS build number or Android version code
+nativeFingerprint  hash native-affecting files and dependency metadata
+latestBuild        use latest successful Mach build runtime for profile/channel
+```
+
+Default:
+
+```text
+nativeFingerprint for new Mach OTA setup
+```
+
+Why:
+
+- `package.json` version is not enough.
+- app version is easy but can be forgotten.
+- native fingerprint is safer because native-affecting changes create a new runtime.
+- latest successful Mach build should be used when publishing after a Mach build.
+
+Runtime version resolution:
+
+1. `--runtime-version`
+2. `ota.runtimeVersion`
+3. Expo platform-specific `runtimeVersion`
+4. Expo top-level `runtimeVersion`
+5. latest successful Mach build runtime for `projectId`, `profile`, `platform`
+6. computed `runtimeVersionPolicy`
+7. fail with setup guidance
+
+Build records must be extended to store:
+
+```json
+{
+  "runtimeVersions": {
+    "ios": "rv-ios",
+    "android": "rv-android"
+  },
+  "nativeFingerprints": {
+    "ios": "hash",
+    "android": "hash"
+  },
+  "ota": {
+    "enabled": true,
+    "engine": "expo-updates",
+    "channel": "production"
+  }
+}
+```
+
+## Native Change Guard
+
+Before publish, Mach should compare the current native fingerprint to the latest compatible build fingerprint.
+
+Native-affecting files include:
+
+```text
+package.json
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+bun.lockb
+app.json
+app.config.js
+app.config.ts
+expo-plugin files
+ios/Podfile
+ios/Podfile.lock
+ios/*.xcodeproj/project.pbxproj
+ios/**/Info.plist
+ios/**/*.entitlements
+android/build.gradle
+android/settings.gradle
+android/gradle.properties
+android/app/build.gradle
+android/app/src/main/AndroidManifest.xml
+react-native.config.js
+metro.config.js
+babel.config.js
+```
+
+Dependency classification:
+
+- Any added/removed package that contains native code should block OTA.
+- Expo modules, React Native modules, Firebase, maps, camera, permissions, notifications, and other native libraries should be treated as native-affecting.
+- Pure JS dependencies can be allowed.
+
+Initial implementation can be conservative:
+
+- If lockfile or native config changed since latest runtime and Mach cannot prove it is safe, block OTA.
+- Print the files that changed.
+- Recommend `mach build`.
+
+## Storage Model
+
+Use Cloudflare R2 as the default OTA artifact store. R2 avoids the large egress
+cost that OTA assets can create on S3, while Mach API keeps private R2
+credentials server-side and issues short-lived upload URLs to the CLI. S3 can
+remain a fallback for self-hosted/internal deployments, but managed Mach OTA
+should use R2.
+
+Prefix:
+
+```text
+ota/<projectId>/updates/<updateId>/
+ota/<projectId>/<platform>/<runtimeVersion>/<channel>/manifest.json
+```
+
+Objects:
+
+```text
+ota/<projectId>/updates/<updateId>/<platform>/manifest.json
+ota/<projectId>/updates/<updateId>/<platform>/metadata.json
+ota/<projectId>/updates/<updateId>/<platform>/main.jsbundle
+ota/<projectId>/updates/<updateId>/<platform>/assets/<hash>.<ext>
+ota/<projectId>/<platform>/<runtimeVersion>/<channel>/manifest.json
+```
+
+Rules:
+
+- Assets are immutable.
+- Assets should use content hash names.
+- Manifest points to stable public R2 custom-domain URLs.
+- R2 credentials are never shipped to mobile apps.
+- R2 lifecycle rules can expire old inactive updates after a configurable retention period.
+- Active updates must not be deleted while clients can request them.
+
+Cost posture:
+
+- No EAS Update cost.
+- No App Center cost.
+- No extra server if using existing Mach API.
+- No managed OTA SaaS cost.
+- Use DynamoDB `PAY_PER_REQUEST`.
+- Use R2 public custom domain for assets and manifest pointers.
+- Use Cloudflare cache/WAF controls on the custom domain when needed.
+
+The only unavoidable costs are usage-based:
+
+- R2 storage and operations.
+- DynamoDB reads/writes.
+- Mach API traffic.
+
+## DynamoDB Model
+
+Create a proper `MachUpdates` table.
+
+Recommended key:
+
+```text
+PK: projectId
+SK: updateId
+```
+
+Recommended GSIs:
+
+```text
+ChannelRuntimeIndex
+PK: projectChannelRuntimePlatform
+SK: createdAt
+
+ChannelIndex
+PK: projectChannel
+SK: createdAt
+```
+
+Derived keys:
+
+```text
+projectChannel = <projectId>#<channel>
+projectChannelRuntimePlatform = <projectId>#<channel>#<runtimeVersion>#<platform>
+```
+
+Dashboard counters are aggregate fields on the update record. Do not write one
+row per user or one row per download:
+
+```text
+statsTotalIosDownloaded
+statsTotalIosApplied
+statsTotalIosFailed
+statsTotalAndroidDownloaded
+statsTotalAndroidApplied
+statsTotalAndroidFailed
+statsDailyYYYYMMDDIosDownloaded
+statsDailyYYYYMMDDAndroidDownloaded
+```
+
+This keeps dashboard counts accurate enough, private, and very cheap while
+still allowing daily charts.
+
+Item:
+
+```json
+{
+  "projectId": "project-id",
+  "updateId": "uuid",
+  "channel": "production",
+  "platform": "ios",
+  "engine": "expo-updates",
+  "runtimeVersion": "runtime",
+  "runtimeVersionPolicy": "nativeFingerprint",
+  "nativeFingerprint": "hash",
+  "manifestKey": "ota/project/update/manifest.json",
+  "launchAssetKey": "ota/project/update/ios/main.jsbundle",
+  "assetKeys": [],
+  "message": "Fix login crash",
+  "commitSha": "abc123",
+  "branch": "main",
+  "status": "active",
+  "rollout": 100,
+  "mandatory": false,
+  "createdAt": 1783750000000,
+  "createdBy": "user-id",
+  "promotedFrom": null,
+  "disabledAt": null,
+  "rollbackOf": null
+}
+```
+
+Statuses:
+
+```text
+draft
+active
+disabled
+rolled_back
+deleted
+```
+
+Only `active` updates are served to clients.
+
+## API Plan
+
+Replace the current generic manifest route with project-scoped routes.
+
+Publish and management:
+
+```text
+POST   /projects/:projectId/ota/upload-url
+POST   /projects/:projectId/ota/publish
+GET    /projects/:projectId/ota/updates
+GET    /projects/:projectId/ota/updates/:updateId
+POST   /projects/:projectId/ota/updates/:updateId/promote
+POST   /projects/:projectId/ota/channels/:channel/rollback
+PATCH  /projects/:projectId/ota/updates/:updateId
+```
+
+Client manifest routes:
+
+```text
+GET /api/ota/expo/:projectId
+GET /api/ota/react-native/:projectId
+GET /api/ota/assets/:projectId/:updateId/:assetName
+```
+
+Expo manifest request:
+
+- Read `expo-runtime-version`.
+- Read `expo-platform`.
+- Read `expo-channel-name` or configured request header.
+- Query `ChannelRuntimeIndex`.
+- Apply rollout gating.
+- Return Expo Updates protocol response.
+- Return `204` if no update is available.
+
+Vanilla RN manifest request:
+
+- Read app id, channel, runtime version, platform, current update id.
+- Query the same update table.
+- Return Mach RN manifest.
+- Return no-op when already current.
+
+Important fix:
+
+- Never point `manifestKey` to a zip.
+- Store and serve a real manifest JSON.
+- Store bundle/assets separately.
+
+## Expo Engine
+
+Engine id:
+
+```text
+expo-updates
+```
+
+Setup:
+
+1. Ensure project has `expo-updates`.
+2. Configure Expo app with Mach update URL.
+3. Configure runtime version.
+4. Configure request headers for channel if needed.
+5. Add/use `@radhya/mach/expo-plugin` when possible.
+6. Avoid writing any EAS Update URL.
+7. Warn when existing `updates.url` points to `https://u.expo.dev`.
+8. Ask before replacing the URL, unless `--yes`.
+
+Expo config plugin should apply:
+
+```js
+config.updates = {
+  ...(config.updates || {}),
+  url: `https://mach-api.securejs.in/api/ota/expo/${projectId}`,
+  checkAutomatically: ota.checkAutomatically || 'ON_LOAD',
+  fallbackToCacheTimeout: ota.fallbackToCacheTimeout || 0,
+}
+config.runtimeVersion = resolvedRuntimeVersion
+```
+
+Publishing:
+
+1. Resolve project/channel/platform/profile/runtime.
+2. Run native-change guard.
+3. Export bundles/assets with Expo tooling.
+4. Convert export output into Expo Updates manifest.
+5. Upload launch asset and assets individually.
+6. Save manifest JSON.
+7. Publish update metadata.
+8. Print dashboard link and next verification command.
+
+Open implementation question:
+
+- Validate exact Expo export output across current SDK versions before coding. The implementation must parse the actual export metadata rather than assume folder shape.
+
+## Vanilla React Native Engine
+
+Engine id:
+
+```text
+mach-react-native
+```
+
+Setup:
+
+1. Install or verify a Mach RN OTA client package.
+2. Patch iOS native loader to ask Mach client for a JS bundle path before falling back to embedded bundle.
+3. Patch Android native loader similarly.
+4. Store Mach update URL, channel, runtime version, and app id in native config.
+5. Do not require Expo.
+
+Possible package names:
+
+```text
+@radhya/mach-react-native
+@radhya/mach-ota-react-native
+```
+
+The client package should support:
+
+- check for update
+- download update
+- install on next restart
+- reload now
+- rollback to previous working update
+- mandatory update handling
+- current update id reporting
+- binary embedded fallback
+
+Publishing:
+
+```bash
+npx react-native bundle --platform ios --dev false --entry-file index.js --bundle-output build/mach-ota/ios/main.jsbundle --assets-dest build/mach-ota/ios/assets
+npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output build/mach-ota/android/index.android.bundle --assets-dest build/mach-ota/android/res
+```
+
+The exact command should use project config:
+
+- `ota.reactNative.entryFile`
+- custom Metro config when present
+- platform selection
+- Hermes bytecode decision later
+
+Manifest shape:
+
+```json
+{
+  "id": "update-id",
+  "platform": "ios",
+  "channel": "production",
+  "runtimeVersion": "runtime",
+  "mandatory": false,
+  "rollout": 100,
+  "createdAt": "2026-07-11T00:00:00.000Z",
+  "bundle": {
+    "url": "https://mach-api.securejs.in/api/ota/assets/...",
+    "hash": "sha256"
+  },
+  "assets": [
+    {
+      "url": "https://mach-api.securejs.in/api/ota/assets/...",
+      "hash": "sha256",
+      "path": "assets/image.png"
+    }
+  ]
+}
+```
+
+## CodePush Compatibility
+
+Do not make CodePush the core.
+
+Later, add optional compatibility:
+
+```json
+{
+  "ota": {
+    "engine": "codepush-compatible"
+  }
+}
+```
+
+This can help existing vanilla RN users migrate, but it should adapt Mach's update records to a CodePush-like client protocol. It should not depend on App Center service.
+
+## Rollout Logic
+
+Rollout should be deterministic per installation.
+
+Inputs:
+
+```text
+projectId
+channel
+updateId
+installationId
+```
+
+Algorithm:
+
+1. Hash inputs.
+2. Convert hash to bucket 0-99.
+3. Serve update if bucket is less than rollout percentage.
+
+The client needs a stable anonymous installation id. For Expo, use headers if practical or store in app code with `expo-updates` request headers later. For initial implementation, rollout may be server-side by device id only for Mach RN and disabled for Expo until stable headers are solved.
+
+## Rollback
+
+Expo rollback:
+
+- Prefer serving a directive compatible with Expo Updates protocol for rollback-to-embedded when rolling back all updates for a runtime.
+- For normal rollback to a previous update, mark newer update disabled and serve the previous active update.
+
+Vanilla RN rollback:
+
+- Mark update disabled.
+- Client should keep previous working update locally.
+- Server can return previous active update or no-op.
+
+Dashboard rollback should:
+
+1. Show current active update.
+2. Show compatible previous updates.
+3. Confirm affected channel/platform/runtime.
+4. Record who performed rollback.
+
+## Security
+
+Initial:
+
+- Only authenticated developers can publish updates.
+- Client manifest routes are public but project-scoped.
+- Asset URLs are immutable and can be public or signed.
+- Never expose secrets in manifests.
+
+Phase 2:
+
+- Add manifest code signing.
+- Store public certificate in app config.
+- Store private signing key in Mach secrets.
+- Sign manifest/directives on API or CLI.
+- Verify signatures in Expo when configured.
+- Add Mach RN client signature verification.
+
+## Dashboard Plan
+
+Add an OTA tab or project subpage:
+
+```text
+Project -> OTA Updates
+```
+
+Views:
+
+- Channels.
+- Active update per channel/platform/runtime.
+- Update history.
+- Runtime versions.
+- Rollout percentage.
+- Publish source: CLI user, commit, branch.
+- Rollback/promote actions.
+- Setup instructions.
+
+Build detail page:
+
+- Show runtime versions generated by the build.
+- Show whether OTA is enabled for that build.
+- Show compatible update channel.
+
+Docs:
+
+- Add a full OTA docs page.
+- Explain that Mach does not use EAS Update.
+- Explain Expo custom server setup.
+- Explain vanilla RN Mach client setup.
+- Explain runtime version and native-change guard.
+- Explain cost model.
+
+## Cost Plan
+
+No new fixed-cost service is required for v1.
+
+Use:
+
+- existing Mach API
+- Cloudflare R2 for OTA bundles/assets/manifests
+- DynamoDB on-demand table
+- existing dashboard
+
+Avoid:
+
+- EAS Update
+- App Center
+- new always-on worker
+- proxying OTA asset downloads through Mach API
+
+Controls:
+
+- Store immutable assets once by hash.
+- Reuse identical assets across updates later.
+- Retention policy for inactive updates.
+- Compression for JS bundles.
+- Warn about large assets.
+- Dashboard storage usage per project.
+
+## Implementation Files
+
+CLI:
+
+```text
+src/commands/ota.ts
+src/lib/ota/types.ts
+src/lib/ota/config.ts
+src/lib/ota/detect.ts
+src/lib/ota/runtime.ts
+src/lib/ota/native-fingerprint.ts
+src/lib/ota/verify.ts
+src/lib/ota/engines/index.ts
+src/lib/ota/engines/expo-updates.ts
+src/lib/ota/engines/mach-react-native.ts
+src/lib/ota/expo-plugin.ts
+```
+
+Packaged Expo plugin:
+
+```text
+expo-plugin/index.js
+```
+
+Add OTA behavior to the existing plugin or split:
+
+```text
+@radhya/mach/expo-plugin
+```
+
+The plugin can configure both deep links and OTA from `mach.config.json`.
+
+API:
+
+```text
+api/src/index.ts
+api/scripts/create-updates-table.js
+```
+
+Dashboard:
+
+```text
+app/(tabs)/ota.tsx
+app/(tabs)/project/[id].tsx
+app/(tabs)/build/[id].tsx
+app/(tabs)/docs.tsx
+```
+
+Docs:
+
+```text
+docs/ota-implementation-plan.md
+docs/ota.md
+```
+
+## Phased Delivery
+
+### Phase 0: Disable Broken Path Safely
+
+- Keep `mach update` available, but do not let it pretend success if the API cannot serve the update.
+- Add warning that current OTA is experimental until `mach ota` is ready.
+- Avoid publishing zip-as-manifest records.
+
+### Phase 1: Core Model And API
+
+- Create `MachUpdates` table script with query-friendly indexes.
+- Add project-scoped publish/list/get routes.
+- Add R2 upload URLs for OTA objects.
+- Store real manifest metadata.
+- Add project-scoped Expo manifest route.
+- Return `204` for no update.
+
+### Phase 2: Runtime Version And Build Integration
+
+- Add runtime version computation to Mach build.
+- Store runtime versions and native fingerprints on build records.
+- Add native fingerprint helper in CLI.
+- Add latest-compatible-build resolution.
+- Add native-change guard.
+
+### Phase 3: Expo OTA
+
+- Add `mach ota setup` for Expo.
+- Configure `expo-updates` to use Mach URL.
+- Add `ota` config writing and migration from legacy `update`.
+- Add Expo export parsing.
+- Generate valid Expo manifest.
+- Upload individual immutable assets.
+- Publish and verify.
+- Confirm updates do not appear in Expo dashboard because `eas update` is never called.
+
+### Phase 4: Vanilla React Native OTA
+
+- Create Mach RN OTA client package.
+- Add `mach ota setup` native patching for iOS and Android.
+- Add `react-native bundle` export engine.
+- Add Mach RN manifest route.
+- Add install/reload/rollback client behavior.
+- Verify on real iOS/Android app.
+
+### Phase 5: Dashboard
+
+- Add OTA update list page.
+- Add rollback/promote actions.
+- Add runtime compatibility display.
+- Add docs.
+
+### Phase 6: Rollout, Promotion, Signing, Retention
+
+- Add rollout percentage.
+- Add channel promotion.
+- Add code signing.
+- Add retention cleanup.
+- Add asset dedupe.
+
+## Acceptance Tests
+
+Expo:
+
+- `mach ota setup` updates Mach config and Expo plugin without EAS URL.
+- Existing `updates.url` pointing to `u.expo.dev` is detected and replaced only with confirmation.
+- `mach ota publish --channel staging` uploads real manifest and assets.
+- Expo client requests Mach endpoint and receives valid Expo Updates manifest.
+- Expo dashboard does not show the update.
+- Native dependency change blocks OTA.
+
+Vanilla RN:
+
+- `mach ota setup` installs Mach RN client and patches native code.
+- `mach ota publish --platform ios` runs RN bundler and uploads iOS bundle/assets.
+- `mach ota publish --platform android` runs RN bundler and uploads Android bundle/assets.
+- Client downloads update, restarts, and runs new JS.
+- Bad update rolls back to previous working bundle.
+- Native change blocks OTA.
+
+API:
+
+- Updates are scoped by project.
+- Latest active update is returned for matching project/channel/platform/runtime.
+- No matching update returns no-op/204.
+- Disabled update is not served.
+- Rollback serves previous active update.
+
+Dashboard:
+
+- Update appears in project OTA history.
+- Runtime version is visible.
+- Rollback action changes served update.
+- Cost/storage data is visible or planned clearly.
+
+## Open Questions
+
+- Should the first Mach RN client use JSI/TurboModule, classic native module, or a minimal native bridge?
+- Should Expo rollout wait until stable installation-id request headers are implemented?
+- Should OTA assets be public immutable URLs or signed API URLs in v1?
+- Should code signing be mandatory for production channels from day one?
+- Should `ota.runtimeVersionPolicy` default to `nativeFingerprint` for all projects, or `latestBuild` after the first successful Mach build?
+- Should `mach build` automatically create/update OTA channel metadata when `ota.enabled` is true?
+
+## Recommended First Implementation Slice
+
+Do not start with vanilla RN client code first. Start with the shared core.
+
+1. Add `mach ota` namespace and make `mach update` a deprecated alias.
+2. Add `ota` config type and migration from `update`.
+3. Add runtime version and native fingerprint helpers.
+4. Add `MachUpdates` table script and project-scoped API.
+5. Fix Expo path end to end because `expo-updates` already provides the native client.
+6. Add dashboard docs and update history.
+7. Then implement Mach RN client for vanilla React Native.
+
+This keeps the first usable release smaller, fixes the broken current path, avoids new cost, and leaves a clean adapter boundary for vanilla React Native.