From c9f73a1bcb83720b11583ab963f55fed83297c62 Mon Sep 17 00:00:00 2001 From: Willy Antunez Date: Wed, 11 Nov 2026 07:11:43 -0600 Subject: [PATCH 01/28] docs: design and plan for Expo SDK 56 --- docs/design/plans/2026-11-11-expo-sdk-56.md | 531 ++++++++++++++++++ .../specs/2026-11-11-expo-sdk-56-design.md | 324 +++++++++++ 2 files changed, 855 insertions(+) create mode 100644 docs/design/plans/2026-11-11-expo-sdk-56.md create mode 100644 docs/design/specs/2026-11-11-expo-sdk-56-design.md diff --git a/docs/design/plans/2026-11-11-expo-sdk-56.md b/docs/design/plans/2026-11-11-expo-sdk-56.md new file mode 100644 index 0000000..cef41fa --- /dev/null +++ b/docs/design/plans/2026-11-11-expo-sdk-56.md @@ -0,0 +1,531 @@ +# Expo SDK 56 Implementation Plan + +**Goal:** `rn-xtool doctor | build | install | start | run` work on Expo SDK 56 projects (expo 56.x from 56.0.24, +react-native exactly 0.85.3), proved on a fresh `default@sdk-56` template built from zero, on the owner's device pass +and on the owner's SDK 56 app, with Expo SDK 57, Expo SDK 58 and bare 0.85 unchanged except for the generic fixes +listed. The row merges only after the owner's device pass. + +**Architecture:** SDK 56 runs on SDK 57's path: the vendored Expo 58.0.19 plugin, the vendored React Native 0.88.0 +scripts, the adapted 0.85.3 artifacts of the bare 0.85 line, the `jsi` step before `rn-spm`, and the precompiled modules +that ship in the npm packages (ExpoModulesCore, ExpoModulesWorklets, ExpoFileSystem, ExpoFont, ExpoImage and its +`spm-deps`). The line is one `SUPPORTED_LINES` row, which the gate, `doctor`, the overrides remedy and the drift watch +already read. Four generic changes close the spike's four gaps: a bundled jsi 56 patch, the JSI headers found in either +layout, a readable ExpoModulesJSI interface behind a guard, and vendored edit P7 (each Expo package at its podspec's +iOS floor). No code path branches on the SDK number. + +**Tech Stack:** TypeScript (Node 22.12+, ESM), vitest, `tsc --noEmit` as lint, the vendored Expo plugin (`vendor/expo-spm`, +CommonJS, MIT 650 Industries), the vendored RN scripts (`vendor/rn-spm`), patch-package, xtool 1.24.0, Swift 6.4 with the +Darwin SDK (investigation and proof only), `llvm-nm` (G4). + +**Spec:** `docs/design/specs/2026-11-11-expo-sdk-56-design.md` (approved 2026-11-11). The owner confirmed its +failure-walk rulings; this plan carries each row's owner below. + +## Global Constraints + +- Linux, Node 22.12+, Swift 6.4 (6.4.1 here), xtool 1.24.0, `IOS_MIN` 16.4, `SCAFFOLD_REVISION` 8, `ADAPTER_VERSION` + 1: unchanged. `JSI_HEADERS_GENERATOR_VERSION` goes from 1 to 2 only on Task 4's exit B2. +- **The row, verbatim**, first in `SUPPORTED_LINES` (before `expo-57`): + `{ kind: "expo", sdk: 56, plugin: "vendored", policy: "floor", scripts: "vendored", artifacts: "adapted", pins: { expo: "56.0.24", "react-native": "0.85.3", "expo-modules-core": "56.0.27", "expo-modules-jsi": "56.0.14", "expo-modules-autolinking": "56.0.24", "expo-file-system": "56.0.11", "expo-font": "56.0.7" }, templates: ["default"], createExpo: "5.1.5" }`. +- **Bundled patches after Task 2 (seven):** `expo+58.0.21.patch`, `expo-modules-autolinking+58.0.16.patch`, + `expo-modules-jsi+56.0.14.patch`, `expo-modules-jsi+57.1.3.patch`, `expo-modules-jsi+58.0.21.patch`, + `react-native+0.88.0.patch`, `react-native+0.88.1.patch`. `patches/expo+58.0.21.patch` is not edited. +- `vendor/expo-spm` stays expo 58.0.19 (`EXPO_TARBALL`, `EXPO_INTEGRITY` unchanged); its vendored-only edits become + P1–P7. `vendor/rn-spm` is not touched. +- **No version branch.** `grep -rnE '\b56\.' src` lists only the row. No hard-coded iOS floor in `vendor/expo-spm`. +- **Texts are verbatim** (`${…}` marks a value): + - Refusal: `Expo SDK ${n} is not supported; rn-xtool supports SDK 56 (expo 56.0.24 or newer 56.x), SDK 57 (expo 57.0.31 or newer 57.x) and SDK 58 or newer.` + - G1 prefix: `Expo SDK 56 needs react-native 0.85.3 and at least expo 56.0.24, expo-modules-core 56.0.27, expo-modules-jsi 56.0.14, expo-modules-autolinking 56.0.24, expo-file-system 56.0.11 and expo-font 56.0.7; installed: ${list}. ${remedy}` (the remedy as `floorRemedy` builds it for SDK 57 and 58). + - Warning: `⚠ Newer than the Expo SDK 56 set this rn-xtool release was verified with: ${list}. Verified: expo 56.0.24, react-native 0.85.3, expo-modules-core 56.0.27, expo-modules-jsi 56.0.14, expo-modules-autolinking 56.0.24, expo-file-system 56.0.11 and expo-font 56.0.7. The build continues; if it fails or the app crashes at launch, report it at https://github.com/WillyAntunez/react-native-xtool/issues.` + - `doctor --project` versions line: `Expo SDK 56: expo 56.0.24 (verified 56.0.24), react-native 0.85.3 (verified 0.85.3)`. + - Overrides block (patch failure on SDK 56): `"overrides": { "expo-modules-core": "56.0.27", "expo-modules-jsi": "56.0.14", "expo-modules-autolinking": "56.0.24" }`. + - Headers error (Task 3): `ExpoModulesJSI needs React Native's headers at ${dir}, which does not exist. rnArtifactsDir must hold the adapted slots of the project's React Native version, as rn-xtool's rn-artifacts step writes them.` + - Missing `NativeState.h` (Task 3): `The ExpoModulesJSI build produced no NativeState.h (expected in ${include}/Public or ${include}); cannot make ExpoModulesJSIHeaders.xcframework for expo-modules-jsi ${jsiVersion}.` + - Local include (Task 3): `NativeState.h of expo-modules-jsi ${jsiVersion} includes "${name}", which is not next to it in ${dir}; cannot make ExpoModulesJSIHeaders.xcframework.` + - Guard (Task 4): ``The ExpoModulesJSI.swiftinterface built for expo-modules-jsi ${jsiVersion} (${compiler}) has ${n} ${n === 1 ? "line" : "lines"} no Swift compiler can parse, for example line ${line}: ${text}. Every module that imports ExpoModulesJSI would fail to compile. Report it at https://github.com/WillyAntunez/react-native-xtool/issues with this message.`` (`compiler` is the value of the interface's `// swift-compiler-version:` line, else `unknown compiler`; `line` and `text` are the first unreadable line's.) + - Drill error: `unknown drift line "x"; lines: expo-56, expo-57, expo-58, bare-0.85, bare-0.86, bare-0.87, bare-0.88`. +- **Privacy.** No absolute home path, Team ID, UDID, Apple ID, e-mail or real IP in committed files, tests or the PR + body. Placeholders: `/home/me`, `TEAMID0000`, `192.168.1.2`. Scratch folders are written `/…`; the + owner's work app is "the owner's SDK 56 app", with no name, path or library list. +- **Heavy steps** (builds, downloads) appear only in Task 4 Step 1 and Task 6, each "needs the owner's go-ahead". The + machine has under 9 GB free (7.2 GB on 2026-11-11). Before each build `df -h ~` must show at least 5 GB free, + otherwise stop and ask. Each heavy step deletes only the outputs it created, by literal path, after its results are + recorded; before any `rm -rf` of more than one path, `ls -ld` each path and check that none is a symlink + (`find -maxdepth 0 -type l` prints nothing). +- Every task that changes code ends with `npm test && npm run lint` green. Every commit runs `npm run scan:private` after + `git add`, before `git commit`. +- Commits: Conventional Commits in English, the subject given in the task (≤ 50 characters), no body, one logical + change each, red before green, no scratch code. Never push, rebase, amend or stash; the controller pushes with + `git push -u origin feature/expo-sdk-56` when the owner asks, and checks that `@{u}` is `origin/feature/expo-sdk-56`. + +## Failure-walk owners + +The spec's rows with their rulings and owners, confirmed by the owner on 2026-11-11. + +| # | Hop | Ruling | Owner | +|---|---|---|---| +| 1 | npm install: ERESOLVE or network | accept | Task 6 Step 1 records the install; Task 7 adds a troubleshooting entry only if one appears | +| 2 | npm install: macro binary left out | handle | Task 1 expo.test `checks the expo-modules-macros copy the vendored plugin finds on SDK 56` | +| 3 | lockfile holds core, file-system or font below the set | handle | Task 1 expo.test `names each SDK 56 pin below the floor`, `reads expo-file-system and expo-font where expo resolves them on SDK 56` | +| 4 | expo-image on another core | handle | G4 unchanged; Task 6 Step 2 | +| 5 | nested expo-modules-jsi | handle | Task 1 expo.test `refuses a nested expo-modules-jsi on SDK 56` | +| 6 | react-native other than 0.85.3 | handle | Task 1 expo.test `refuses react-native other than 0.85.3` | +| 7 | newer 56.x | accept | Task 1 plan note; expo.test `warns and continues on a newer 56.x`; the daily watch | +| 8 | another SDK's package | handle | Task 1 expo.test `refuses a package of another SDK's line on SDK 56` | +| 9 | SDK 55 or older | handle | Task 1 expo.test `rejects SDK %i`; versions.test `lists the supported Expo SDKs from the table` | +| 10 | hybrid on SDK 56 | handle | existing bare.test `refuses a hybrid app on Expo SDK %s` (56 case), unchanged | +| 11 | jsi patch fails on a newer 56.x | handle | Task 2 patches.test `names the SDK 56 overrides when its jsi patch fails on a newer 56.x`; Task 1 targets.test | +| 12 | another SDK's patch staged | handle | Task 2 patches.test `never stages another SDK's patch on SDK 56` | +| 13 | a later core imports `CppError.message` | accept | Task 7 troubleshooting entry; G4 unchanged | +| 14 | `rn-artifacts` network | accept | as ruled for bare 0.85; Task 7 sizes | +| 15 | jsi compile fails | handle (this set), accept (later toolchain) | Task 6 Step 1; owner's ruling 1 | +| 16 | `rnArtifactsDir` wrong | handle | Task 3 jsi.test `stops when the React Native headers are missing` | +| 17 | `NativeState.h` or a local include missing | handle | Task 3 jsiHeaders.test `names a local include that is not next to NativeState.h`, `a failed synthesis leaves no stamped xcframework` | +| 18 | stale or partial headers tree | handle | existing jsiHeaders tests; Task 4 `rewrites a tree stamped by an older generator` (B2) | +| 19 | unreadable lines in an unknown shape | handle | Task 4 jsiInterface.test `stops on a broken line it does not know` | +| 20 | cleanup removes too much | handle | Task 4 jsiInterface.test `removes exactly the four stub pairs from jsi 56.0.14's interface` (B2) | +| 21 | the fix changes SDK 57 or 58 | handle | Task 6 Step 3 (Task 4's re-proof) | +| 22 | podspec asks for more iOS | handle | Task 5 vendor-expo-spm.test `P7 reads the iOS deployment target a podspec declares`, `P7 raises a module to its podspec's iOS floor` | +| 23 | podspec above the App's 16.4 | accept | Task 7 troubleshooting entry | +| 24 | podspec platform P7 cannot read | accept | Task 5 README limits; P7 test asserts `null` | +| 25 | P7 changes SDK 57 | handle | Task 5 test (never lowered); Task 6 Step 3 `platforms:` check | +| 26 | JSI and core C++ layout skew | accept | Task 7 docs (G4's limit); owner's ruling 2 | +| 27 | ExpoModulesWorkletsAdapter left out | handle | Task 6 Step 4; Task 7 note | +| 28 | stale scaffold patches, Xcode-only resources | accept | existing behaviour | +| 29 | AppleDouble and xattrs | handle | existing vendor-expo-spm.test `P5 extracts without AppleDouble entries or xattr warnings` | +| 30 | damaged tarball | accept | Task 7 troubleshooting line | +| 31 | ExpoImage `spm-deps` | handle | Task 6 Steps 1, 2 and 4 | +| 32 | G4 false positive | handle | Task 6 Steps 1–2 | +| 33 | Icon Composer icon | accept | Task 7 notes | +| 34 | unseen compile failure | handle | Task 6 Step 1 | +| 35 | runtime on the device | handle | Task 6 Step 4 | +| 36 | the owner's SDK 56 app | handle | Task 6 Step 5 | +| 37 | newer 56.x over time | handle (gates, patches), accept (compile, interface, G4) | Task 1 targets.test; RELEASING limits | +| 38 | newer Swift 6.4.x | accept | owner's ruling 1 | +| 39 | SDK 56 leaves the exploration | accept | Task 7 explore.test | +| 40 | disk | accept | Task 7 sizes | + +## Review Focus + +1. **Where npm puts expo-file-system and expo-font.** SDK 56 hoists them; a lockfile can nest one under `expo` next to + a hoisted stray of another version. The gate must read the copy the build resolves (Task 1 test `reads + expo-file-system and expo-font where expo resolves them on SDK 56`). +2. **A jsi newer than 56.0.14.** It must get 56.0.14's patch, never 57.1.3's, and a patch failure must name the SDK 56 + overrides (Task 2 tests `never stages another SDK's patch on SDK 56` and `names the SDK 56 overrides when its jsi + patch fails on a newer 56.x`). +3. **A jsi package in either header layout**, including one whose `NativeState.h` includes a header that is not there + (Task 3 tests `writes jsi 56's layout: NativeState.h from include/ with its local includes` and `names a local + include that is not next to NativeState.h`). +4. **An interface with an unreadable line the fix does not know**, from a newer jsi or Swift 6.4.x: it must stop at + `jsi` by name, never reach `xtool-build` (Task 4 test `stops on a broken line it does not know`). +5. **Podspec platform forms** beyond the template's: one line or several, `s.ios.deployment_target`, + `s.platform = :ios, '…'`, a `test_spec`'s own platforms, a variable (Task 5 test `P7 reads the iOS deployment + target a podspec declares`). +6. Before the final verdict, the reviewer answers without hints: "Name three ways this fails in production that no + test covers." Any answer not in the failure-walk table goes to the owner as a decision, not to the implementer as a + fix. + +--- + +### Task 1: The SDK 56 row and its gate + +Plan note (row 7, accept): a newer 56.x of a pinned package builds with the newer-than warning, as on SDK 57 and 58; +the daily watch creates the newest 56.x set every day. + +**Files:** +- Modify: + - `src/versions.ts`: the row first in `SUPPORTED_LINES` (`:71`); the table comment (`:66-70`: SDK 56 and 57 build + through the vendored plugin); `supportedExpoList()` (new, next to `supportedRnList`, `:240`). + - `src/project/expo.ts:377-383`: the refusal uses `supportedExpoList()`. + - Comments only: `src/project/types.ts:23`, `src/paths.ts:10`, `src/pipeline/rnSpm.ts:74` ("SDK 56 and 57"). + - `tests/support/expo57.ts`: export `fakeExpoModules`, which `fakeExpo57Modules` now calls. +- Create: + - `tests/support/expo56.ts`. + - `tests/fixtures/expo-56/`: `app.json` (name and slug `Expo56`, `ios.bundleIdentifier` `com.anonymous.expo56`, + `ios.icon` `./assets/expo.icon` as the template has it), `package.json` (`"expo": "~56.0.24"`, + `"react-native": "0.85.3"`), `ios/Expo56/AppDelegate.swift` (a copy of + `tests/fixtures/expo-57/ios/Spike57/AppDelegate.swift`: the gate tests need only the target folder). +- Test: `tests/versions.test.ts`, `tests/project/expo.test.ts`, `tests/capabilities.test.ts`, `tests/doctor.test.ts`, + `tests/drift/targets.test.ts`, `tests/drift/issues.test.ts` + +**Interfaces:** +- Produces: + ```ts + // src/versions.ts + /** "SDK 56 (expo 56.0.24 or newer 56.x), SDK 57 (expo 57.0.31 or newer 57.x) and SDK 58 or newer" */ + export function supportedExpoList(): string; + // every Expo row but the last: `SDK ${sdk} (expo ${pins.expo} or newer ${sdk}.x)`; the last: `SDK ${sdk} or newer`; andList + // tests/support/expo57.ts + export async function fakeExpoModules( + dir: string, + pins: Partial>, + overrides?: Partial>, + nested?: Partial>, + ): Promise; + // tests/support/expo56.ts + export const EXPO56_PINS: Partial>; // the row's pins, written out + export async function fakeExpo56Modules(dir: string, overrides?: …, nested?: …): Promise; // fakeExpoModules(dir, EXPO56_PINS, …) + ``` +- Consumes: `checkExpoPackages`, `expoMacrosBinaryError`, `vendoredExpoPlugin` (unchanged). + +- [ ] **Step 1: Write the failing tests.** + - versions.test: + - `holds every supported line in one table`: ids `["expo-56", "expo-57", "expo-58", "bare-0.85", "bare-0.86", "bare-0.87", "bare-0.88"]`; the first row equals the Global Constraints row with `pins: EXPO56_PINS`. + - `lists the supported Expo SDKs from the table` (new): `supportedExpoList()` is `SDK 56 (expo 56.0.24 or newer 56.x), SDK 57 (expo 57.0.31 or newer 57.x) and SDK 58 or newer`. + - expo.test: + - `rejects SDK %i` (`:81`): `it.each([55, 54])`, the refusal text above. + - `has the SDK 57 pins and plugin in the supported table` (`:237-242`): `[expoPluginFor(55), expoPluginFor(56), expoPluginFor(57), expoPluginFor(58), expoPluginFor(59)]` is `[undefined, "vendored", "vendored", "installed", "installed"]`. + - a new `describe("Expo SDK 56")` on the `expo-56` fixture with `fakeExpo56Modules`: + - `has the SDK 56 pins in the supported table`: `expoPinsFor(56)` equals `EXPO56_PINS`; `expoPinPolicyFor(56)` is `"floor"`. + - `accepts the SDK 56 floor set`: resolves to `{ sdkVersion: 56, rnVersion: "0.85.3", rnScripts: "vendored", expoPlugin: "vendored" }`, `iosTargetDir` is `/ios/Expo56`, `readExpoPins(dir, 56)` equals `EXPO56_PINS`, `log` not called. + - `names each SDK 56 pin below the floor`: `it.each` over expo 56.0.23, expo-modules-core 56.0.26, expo-modules-jsi 56.0.13, expo-modules-autolinking 56.0.23, expo-file-system 56.0.10, expo-font 56.0.6; the message starts with the G1 prefix followed by `${name} ${version}. `; it is a `VersionGateError`. + - `refuses react-native other than 0.85.3`: 0.85.2 → `${prefix}react-native 0.85.2. Run \`npx expo install react-native@0.85.3\`.`; 0.85.4 → the same plus ` React Native 0.85.4 is newer than this rn-xtool release supports: pin react-native to 0.85.3, or update rn-xtool.` + - `warns and continues on a newer 56.x`: expo 56.0.25 and expo-modules-jsi 56.0.15 → resolves; `log` called once with the warning text above, `${list}` = `expo 56.0.25, expo-modules-jsi 56.0.15`. + - `refuses a package of another SDK's line on SDK 56`: expo-modules-jsi 57.1.3 → G1 naming `expo-modules-jsi 57.1.3`; `log` not called. + - `reads expo-file-system and expo-font where expo resolves them on SDK 56`: the default (hoisted) set is accepted; with a nested `node_modules/expo/node_modules/expo-font` 56.0.6 next to the hoisted 56.0.7, G1 names `expo-font 56.0.6`. + - `refuses a nested expo-modules-jsi on SDK 56`: core's own jsi 56.0.14 nested under `node_modules/expo-modules-core`, a hoisted stray 57.1.3 → the error starts with `expo-modules-jsi 56.0.14 resolves from node_modules/expo-modules-core/node_modules/expo-modules-jsi, not from the project's top-level node_modules`. + - `checks the expo-modules-macros copy the vendored plugin finds on SDK 56`: `expoMacrosBinaryError({ root, pluginDir: path.dirname(vendoredExpoPlugin()), arch: "riscv64", resolve: () => { throw new Error("x") } })` is `expo-modules-macros 0.22.0 has no Linux binary for riscv64 (@expo/modules-macros-linux-riscv64); reinstall react-native-xtool without --omit=optional.` + - capabilities.test: + - `gives unsupported versions a reason` (`:1006-1008`): the Expo case becomes `expoOther("55.0.4", "0.83.2")` → `Expo SDK 55: expo ships no SwiftPM plugin; React Native 0.83: no SwiftPM scripts; support comes with the translator`. + - `says when an Expo SDK below 57 ships the plugin` (`:1030`): renamed `… below 56 …`, on `expoOther("55.0.4", "0.83.2")` → `Expo SDK 55: expo ships its SwiftPM plugin; React Native 0.83: no SwiftPM scripts; support comes with the translator`. + - `has no reason for the lines it supports`: adds `expoOther("56.0.24", "0.85.3")` → `undefined`. + - doctor.test, the capability-line table (`:1036-1040`): adds `["versions", "Expo 56", expo(56, "56.0.24", "0.85.3"), "ok", "Expo SDK 56: expo 56.0.24 (verified 56.0.24), react-native 0.85.3 (verified 0.85.3)"]`; the `"Expo 56"` fail row becomes `["versions", "Expo 55", { ...expo(55, "55.0.0", "0.83.2"), expoPlugin: "none" }, "fail", "Expo SDK 55: expo ships no SwiftPM plugin; React Native 0.83: no SwiftPM scripts; support comes with the translator"]`. + - drift targets.test `one target per template and bare line` (`:30`): `expo-56/default` first, equal to `{ id: "expo-56/default", slug: "expo-56-default", line: "expo-56", title: "Drift: Expo SDK 56", kind: "expo", sdk: 56, template: "default", createExpo: "5.1.5" }`. + - drift issues.test (`:142`, `:153`): the drill error text above; `checkDrill("expo-56")` does not throw. +- [ ] **Step 2: Run** `npx vitest run tests/versions.test.ts tests/project tests/capabilities.test.ts tests/doctor.test.ts tests/drift` → FAIL (no SDK 56 row). +- [ ] **Step 3: Implement** the row, `supportedExpoList()`, the refusal, the comments, the fixture and the test support. +- [ ] **Step 4: Run** the same tests, then `npm test && npm run lint` → PASS. `grep -rnE '\b56\.' src` lists only the row. +- [ ] **Step 5: Commit** `git add src tests && npm run scan:private && git commit -m "feat: add the Expo SDK 56 line"` + +### Task 2: The jsi 56 patch + +**Files:** +- Create: `patches/expo-modules-jsi+56.0.14.patch`: patch-package format, one hunk `@@ -82,7 +82,7 @@` in + `node_modules/expo-modules-jsi/apple/Sources/ExpoModulesJSI/Runtime/Values/JavaScriptError.swift`, + ` public var message: String {` → ` var message: String {` (the same change as `expo-modules-jsi+57.1.3.patch`). +- Test: `tests/patches.test.ts` + +**Interfaces:** none new. `selectBundledPatches` and `floorRemedy` are unchanged; the tests pin their SDK 56 answers. + +- [ ] **Step 1: Write the failing tests** in `tests/patches.test.ts`: + - `has exactly 7 patch-package files` (was 6, `:88`): the seven names of Global Constraints. + - `stages only the jsi patch on an SDK 56 project`: expo 56.0.24, expo-modules-autolinking 56.0.24, expo-modules-jsi 56.0.14, react-native 0.85.3 → `selectBundledPatches(root, bundled, { lineOnly: true })` is `["expo-modules-jsi+56.0.14.patch"]`. + - `never stages another SDK's patch on SDK 56`: expo 56.0.25, autolinking 56.0.25, jsi 56.0.15, react-native 0.85.3 → `["expo-modules-jsi+56.0.14.patch"]`. + - `names the SDK 56 overrides when its jsi patch fails on a newer 56.x`: expo 56.0.24, jsi 56.0.15, an exec that fails naming `node_modules/expo-modules-jsi` → the error matches `/^rn-xtool could not patch expo-modules-jsi@56\.0\.15 \(patch file: expo-modules-jsi\+56\.0\.14\.patch\)/`, contains the SDK 56 overrides block of Global Constraints, and does not contain `pin "expo-modules-jsi"`. + - In `describe("a bundled patch over a package an earlier release patched differently")` (`:506`): `jsiProject` takes `{ version, before }` (installed jsi version, number of filler lines before the doc comment; today's call is `{ version: "58.0.21", before: 87 }`). New test `applies the SDK 56 jsi patch to the original file`: `{ version: "56.0.14", before: 81 }`, `applyPatches(root, undefined, { rnScripts: "vendored", expoPlugin: "vendored" })` with the real patch-package → the file contains `\n var message: String {\n` (timeout 30 s). + - `stages only the jsi patch on an SDK 57 project` and `never stages another SDK's patch on SDK 57` stay as they are: 57 still gets only `expo-modules-jsi+57.1.3.patch`. +- [ ] **Step 2: Run** `npx vitest run tests/patches.test.ts` → FAIL (the patch file is missing). +- [ ] **Step 3: Implement**: the spike app's `node_modules/expo-modules-jsi` is already patched, so copy its `JavaScriptError.swift` to a scratch folder, restore line 85 to ` public var message: String {` (the pristine file; patch-package changed nothing else), then write the patch with `git diff --no-index` and rewrite its header to patch-package's form as `docs/RELEASING.md` describes. Task 6 Step 1 applies it to a fresh install. +- [ ] **Step 4: Run** the same file, then `npm test && npm run lint` → PASS (`every bundled patch parses as patch-package reads it` covers the new file). +- [ ] **Step 5: Commit** `git add patches tests && npm run scan:private && git commit -m "feat: patch expo-modules-jsi 56 for Swift 6.4"` + +### Task 3: JSI headers in either layout, and the version-free texts + +**Files:** +- Modify: `src/pipeline/jsiHeaders.ts` (`:88-101`, `:126`), `src/pipeline/jsi.ts:43-44`, `src/commands/build.ts:537`, + `tests/support/fakeJsiBuild.ts` +- Test: `tests/jsiHeaders.test.ts`, `tests/jsi.test.ts` + +**Interfaces:** +- Produces: + ```ts + // src/pipeline/jsiHeaders.ts + /** + * The public C++ headers of expo-modules-jsi `jsiVersion` at `jsiDir`: `dir` is + * `/apple/Sources/ExpoModulesJSI-Cxx/include/Public` when it holds NativeState.h (jsi 57 and newer), else + * `…/include` (jsi 56); `files` is "NativeState.h", then each header it includes with quotes, transitively, found in + * `dir`, in include order, each once. Throws the missing-NativeState.h or the local-include text (Global Constraints). + */ + export function nativeStateHeaders(jsiDir: string, jsiVersion: string): { dir: string; files: string[] }; + // writeJsiHeadersXcframework: unchanged signature; copies `files` (relative paths kept) into each slice's + // Headers/ExpoModulesJSI. JSI_HEADERS_MODULE_MAP is unchanged. + // tests/support/fakeJsiBuild.ts + export const FAKE_NATIVE_STATE_FLAT: string; // '// NativeState.h\n#pragma once\n#include \n#include "RetainedSwiftPointer.h"\n' + export const FAKE_RETAINED_POINTER: string; // '// RetainedSwiftPointer.h\n#pragma once\n#include \n' + export function makeFakeJsiBuild(dir: string, opts?: { layout?: "public" | "flat" }): { objectsDir: string; jsiDir: string }; + // "public" (default): today's files; "flat": NativeState.h and RetainedSwiftPointer.h directly under include/ + ``` +- `src/commands/build.ts:537` reads `internal error: the vendored-plugin jsi step has no React Native artifacts (rn-artifacts was not planned and rnArtifactsDir is unset)`. + +- [ ] **Step 1: Write the failing tests** in `tests/jsiHeaders.test.ts`: + - `writes jsi 56's layout: NativeState.h from include/ with its local includes`: `setup("56.0.14")` on `makeFakeJsiBuild(dir, { layout: "flat" })` → `"written"`; the file list is the one of `writes 58's tarball layout` plus `ios-arm64/Headers/ExpoModulesJSI/RetainedSwiftPointer.h` and `ios-arm64_x86_64-simulator/Headers/ExpoModulesJSI/RetainedSwiftPointer.h`; in each slice `NativeState.h` equals `FAKE_NATIVE_STATE_FLAT`, `RetainedSwiftPointer.h` equals `FAKE_RETAINED_POINTER`, `module.modulemap` equals `JSI_HEADERS_MODULE_MAP`. + - `writes 58's tarball layout` stays as it is (57's layout gets no extra file). + - `prefers include/Public when both layouts hold NativeState.h`: both written, different contents → the copied file equals the `Public/` one. + - `names a local include that is not next to NativeState.h`: the flat layout without `RetainedSwiftPointer.h` → rejects with the local-include text (`${name}` `RetainedSwiftPointer.h`, `${dir}` the `include` dir, version 56.0.14); neither the xcframework, a `*.tmp-*` dir nor the stamp exists. + - `a failed synthesis leaves no stamped xcframework` (`:167`): the expected text becomes the missing-NativeState.h text with `${include}` = `/apple/Sources/ExpoModulesJSI-Cxx/include`. +- [ ] **Step 2: Run** `npx vitest run tests/jsiHeaders.test.ts` → FAIL. +- [ ] **Step 3: Implement** `nativeStateHeaders` and its use in `writeJsiHeadersXcframework` (the input check runs it before anything is written). +- [ ] **Step 4: Run** `npx vitest run tests/jsiHeaders.test.ts`, then `npm test && npm run lint` → PASS. +- [ ] **Step 5: Commit** `git add src/pipeline/jsiHeaders.ts tests/jsiHeaders.test.ts tests/support/fakeJsiBuild.ts && npm run scan:private && git commit -m "feat: find NativeState.h in either jsi layout"` +- [ ] **Step 6: Write the failing tests** in `tests/jsi.test.ts`: `stops when the React Native headers are missing` and `stops when only the dependencies headers are missing` (`:41-61`) expect the headers error of Global Constraints. **Run** `npx vitest run tests/jsi.test.ts` → FAIL. +- [ ] **Step 7: Implement** the two texts (`jsi.ts`, `build.ts:537`). **Run** `npx vitest run tests/jsi.test.ts tests/build.test.ts`, then `npm test && npm run lint` → PASS. +- [ ] **Step 8: Commit** `git add src/pipeline/jsi.ts src/commands/build.ts tests/jsi.test.ts && npm run scan:private && git commit -m "fix: drop 0.86.3 from the jsi step's errors"` + +### Task 4: A readable ExpoModulesJSI interface (investigation, then one of two exits) + +The guard ships on both exits; the owner picks the exit at Step 2 on the evidence of Step 1. Plan note (row 21): the +re-proof of SDK 57 and 58 that this task owns runs in Task 6 Step 3, once, after Task 5 (spec Decision 10). + +**Files:** +- Create: `src/pipeline/jsiInterface.ts`, `tests/jsiInterface.test.ts`, + `tests/fixtures/jsi-interface/ExpoModulesJSI-56.0.14.swiftinterface` (from `$S/jsi56.swiftinterface` of Step 1: its + four header lines, then its stub block, from the `@available(*, unavailable)` line before the first + `Swift::Optional` stub through `internal protocol _ConstraintThatIsNotPartOfTheAPIOfThisLibrary {}`, verbatim; + checked to hold no absolute path before it is added). +- Exit B2 also creates `tests/fixtures/jsi-interface/ExpoModulesJSI-56.0.14.cleaned.swiftinterface` (the expected + output, written by hand from the fixture: the four pairs removed, nothing else). +- Modify: `src/pipeline/jsiHeaders.ts` (the interface is written through `readableJsiInterface` instead of copied; + B2: `JSI_HEADERS_GENERATOR_VERSION = 2`); B1 instead: `scripts/build-expo-modules-jsi.sh` (the flag) or + `patches/expo-modules-jsi+56.0.14.patch` (a source hunk). +- Test: `tests/jsiInterface.test.ts`, `tests/jsiHeaders.test.ts`, and on B1 `tests/jsi.test.ts` + +**Interfaces:** +- Produces: + ```ts + // src/pipeline/jsiInterface.ts + export interface UnreadableLine { line: number; text: string } // 1-based + /** The lines that declare an extension with an empty conformance list: `extension :where …`. */ + export function unreadableInterfaceLines(text: string): UnreadableLine[]; + /** + * The interface ExpoModulesJSIHeaders.xcframework ships. B2 only: first removes each pair + * `@available(*, unavailable)` + `extension : where <…> : _ConstraintThatIsNotPartOfTheAPIOfThisLibrary {}`. + * Both exits: throws UnreadableInterfaceError (the guard text) when an unreadable line remains. + */ + export function readableJsiInterface(text: string, jsiVersion: string): string; + export class UnreadableInterfaceError extends Error {} + ``` +- Consumes: `writeJsiHeadersXcframework` (Task 3). The stamp keeps the raw interface's sha256. + +- [ ] **Step 1 (investigation; needs the owner's go-ahead; about 2 GB of scratch at most, deleted at the end).** + `S=/sdk56-iface`, `RNX="node /bin/rn-xtool.js"` after `npm run build` on Tasks 1–3. + `df -h ~` shows at least 5 GB free. Record everything in `$S/results.md` (never committed). + 1. **The 56 baseline.** The 56 app is the spike's (`/sdk56-spike/app56`) if it is still there, else Task 6 Step 1's create and install, done now in `/sdk56-proof/app56`. Check that `/ios` does not exist, note whether `/ios-xtool` does, then run `$RNX build` there and stop it with Ctrl-C after `✔ jsi`. Copy `/ios-xtool/jsi-out//ExpoModulesJSI.swiftinterface` (`` is the part `jsiObjectsDir()` adds) to `$S/jsi56.swiftinterface`. The adapted 0.85.3 slots are now at `/ios/build/rn-artifacts/0.85.3`. + 2. **A fresh 57 interface on the same toolchain.** Check that `../app-expo-57/ios` and `../app-expo-57/ios-xtool` do not exist. In `../app-expo-57`, `$RNX build` and stop it with Ctrl-C after `✔ jsi`. Copy its interface to `$S/jsi57.swiftinterface`. Record `swift --version`. + 3. **Compare.** `grep -nE '^extension .+ :[[:space:]]+where ' $S/jsi56.swiftinterface $S/jsi57.swiftinterface`; the two `swift-module-flags` lines; `diff` of the `_ConstraintThatIsNotPartOfTheAPIOfThisLibrary` blocks. + - **57 has the same lines:** the cause is the toolchain, and SDK 57 is broken today for anyone on Swift 6.4.1. Stop and tell the owner before going on (spec owner's ruling 1). + - **57 is clean:** the cause is in jsi 56's sources or flags; go on. + 4. **Candidate causes**, each a jsi-only rebuild into `$S/try-` with a scratch copy of `scripts/build-expo-modules-jsi.sh` at `$S/build-jsi.sh` (never the repo's), run as `RN_XTOOL_REACT_HEADERS=/ios/build/rn-artifacts/0.85.3/debug/ReactNativeHeaders.xcframework/ios-arm64/Headers RN_XTOOL_DEPS_HEADERS=/ios/build/rn-artifacts/0.85.3/debug/ReactNativeDependenciesHeaders.xcframework/ios-arm64/Headers bash $S/build-jsi.sh $S/try-`, where `` is the 56 app of item 1. After each: count the unreadable lines, keep the interface as `$S/try-.swiftinterface`, `rm -rf $S/try-`. + - (a) **How the compiler prints suppressed conformances:** list the options with `swiftc -frontend -help-hidden 2>&1 | grep -iE 'escapable|inverse|suppress|noncopyable|interface'` and try each plausible one (`-Xswiftc -Xfrontend -Xswiftc