snapback4-expo 0.4.10 → 0.4.12

package/README.md

@@ -31,6 +31,13 @@ SQLite and the native-query Wasm host. The earlier module measured 1.7 MB
 linked and about a millisecond per call; those measurements predate the
 native-query host.
 
+The pinned Expo 57.0.22 apps list `snapback4-expo/plugin` in app.json's
+`plugins`. Keep that entry when generating iOS: it supplies the scene lifecycle
+required by Xcode 27, shared by the reference chat app and both starters.
+After adding it, run `npx expo prebuild --platform ios`, rebuild Release and
+reinstall. Preserve custom native changes when regenerating; the plugin handles
+the standard Swift starter and refuses custom delegates/manifests.
+
 Earlier iOS simulator evidence from the repository's witness in a development
 build (before the published driver, recorded in
 `metrics/witness.jsonl` as `dev-client-native`): a cold sync of 303 rows
@@ -59,13 +66,13 @@ runner, commands and artifact contract are in `snapback4 guide witness`
 “Proving it on an iOS simulator”. No Expo Go or Metro process supplies a
 Release witness.
 
-At every milestone, run `npm run export:ios` for Hermes; on a Mac with Xcode,
-`npm run native:smoke` (about 3 minutes warm). The Expo starters include both scripts.
-The smoke builds and installs your Release app, chooses its own simulator and free
+At every milestone, `npm run export:ios` keeps Hermes in `dist/` and also proves the app runs on iOS when Xcode/runtime are present (warm runs take about 18 s for the plain starter and 27 s for the social one, cold runs 175–230 s, on this mini).
+`npm run native:smoke` always runs the full Release build; `SNAPBACK4_NATIVE_SMOKE=off` skips the automatic smoke. Unavailable hosts skip, app/SDK failures fail.
+The smoke prepares and installs your Release app, chooses its own simulator and free
 port, and keeps receipts in `artifacts/native-smoke/<timestamp>`. It proves local
 store acquisition, cold offline reopen and reconnect. Pending write replay, media
 and application assertions need the deeper scenario in `snapback4 guide witness`.
-An empty starter proves lifecycle only; export alone proves no native execution.
+An empty starter proves lifecycle only; a skipped smoke proves no native execution.
 
 Own-build preparation (`witness ios --build . --smoke`) uses the witness helper
 in matching current `snapback4` and `snapback4-expo` packages. Its synchronous native observation hashes
@@ -80,13 +87,13 @@ update selected at runtime. The JS smoke helper consumes compiler query facts
 from the driver, bound to the generation actually served. It checks every
 runs/held fact against the kept backend before querying. Stale facts fail;
 device-answerable loading fails, while server-only offline
-loading or E_OFFLINE is recorded as expected unavailability. Server-only reads
+E_OFFLINE is recorded as expected unavailability. Server-only reads
 must answer online in prime and restart. Conditional native-module queries
 require an application witness; generic smoke refuses that unsupported shape. Client semantics are unchanged.
 
-After JS/assets edits, repeat `npm run native:smoke`; simulator selection and
-fresh artifact directories are automatic. Warm Xcode intermediates
-are reused; each run builds the current app and seals a new receipt. Repack
-is withdrawn. NS round 0 cohort (2026-09-30), fresh starter: **221.7 s cold**, **83.5 s warm median (3 runs)**; social **186.2 s**.
-Shared Apartment M5 Pro mini, 18 cores/64 GiB, Xcode/iOS 27; one-minute load: cold 3.61–61.41, warm 3.21–7.22, social 14.62–47.52.
-Tools/dependencies installed first. Guidance, not a promise. See `guide witness` for scope.
+After JS edits, repeat `npm run export:ios`; simulator selection and fresh
+artifact directories are automatic. Matching native inputs reuse the Release
+app and install the exact exported bundle/assets. Native changes rebuild;
+`npm run native:smoke` always runs Xcode. Both routes retain the same loaded-file
+hash and prime/offline/restart proof. Measured on the Apartment M5 Pro mini,
+18 cores/64 GiB, Xcode/iOS 27, with tools/dependencies installed first.

package/export-ios.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+// @ref LLP 3000.030#15 — exact export, explicit environment skips, bounded evidence.
+import { spawn, spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import fs from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { createHash } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+
+const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
+function exportFiles(root, relative = '') {
+  return fs.readdirSync(path.join(root, relative)).sort().flatMap(name => {
+    const file = path.join(relative, name), full = path.join(root, file), stat = fs.lstatSync(full);
+    const row = { path: file, mode: stat.mode & 0o777 };
+    if (stat.isDirectory()) return [{ ...row, type: 'directory' }, ...exportFiles(root, file)];
+    if (!stat.isFile()) throw Error('export contains an unsupported file type');
+    const bytes = fs.readFileSync(full);
+    return [{ ...row, type: 'file', bytes: bytes.length, sha256: sha256(bytes) }];
+  });
+}
+function publicationExpectation(artifacts, source, skipped, smoke) {
+  if (skipped) return { proofSha256: null, files: exportFiles(source) };
+  const bytes = fs.readFileSync(path.join(artifacts, 'proof.json'));
+  const proofSha256 = sha256(bytes), files = JSON.parse(bytes).exported?.inventory?.files;
+  if (smoke?.exitStatus !== 0 || smoke?.proof?.sha256 !== proofSha256 || !Array.isArray(files)) throw Error('export proof does not match successful smoke receipt');
+  return { proofSha256, files };
+}
+export function verifyPublication(artifacts, source, target, expected) {
+  let receipt;
+  try { receipt = JSON.parse(fs.readFileSync(path.join(artifacts, 'publication.json'), 'utf8')); }
+  catch { throw Error('missing or unreadable verified publication.json'); }
+  if (receipt.source !== source || receipt.target !== target || !Number.isFinite(receipt.verifiedAt) ||
+      receipt.proofSha256 !== expected.proofSha256 || !isDeepStrictEqual(receipt.files, expected.files)) {
+    throw Error('publication.json does not match the export proved by this run');
+  }
+}
+
+export function skipReason(platform, env) {
+  if (env.SNAPBACK4_NATIVE_SMOKE === 'off') return 'SNAPBACK4_NATIVE_SMOKE=off';
+  if (platform !== 'darwin') return 'macOS is required';
+  return null;
+}
+const environmentConditions = new Set(['simulator-list', 'missing-runtime', 'missing-device-type', 'simulator-create', 'simulator-boot']);
+export function smokeResult(status, receipt) {
+  if (status === 0) return { status: 0, message: 'native smoke passed' };
+  if (receipt?.environmentCondition === 'simulator-create' && /^E_WITNESS_TIMEOUT:/.test(receipt.error)) return { status: status || 1, message: 'native smoke failed' };
+  if (receipt?.phase === 'environment' && environmentConditions.has(receipt.environmentCondition) &&
+      /^(E_WITNESS_PLATFORM|E_WITNESS_SIMULATOR|E_WITNESS_TIMEOUT):/.test(receipt.error)) {
+    return { status: 0, message: `native smoke skipped: ${receipt.error}` };
+  }
+  return { status: status || 1, message: 'native smoke failed' };
+}
+// The Rust driver bounds its own cleanup and keeps its leases until it finishes.
+// Wait for that exit even after a second signal; killing only its wrapper would
+// orphan the driver's backend/app. This also forwards cancellation during export.
+export function runChild(command, args, options = {}) {
+  return new Promise(resolve => {
+    const child = spawn(command, args, { stdio: 'inherit', env: process.env, ...options });
+    let received;
+    const handlers = Object.fromEntries(['SIGINT', 'SIGTERM'].map(signal => [signal, () => {
+      if (!received) { received = signal; child.kill(signal); }
+    }]));
+    for (const [signal, handler] of Object.entries(handlers)) process.on(signal, handler);
+    child.once('error', () => {}); // close also follows a failed spawn
+    child.once('close', (status, signal) => {
+      for (const [name, handler] of Object.entries(handlers)) process.off(name, handler);
+      const cancelled = received ?? signal;
+      resolve({ status: cancelled ? (cancelled === 'SIGINT' ? 130 : 143) : status ?? 1, cancelled });
+    });
+  });
+}
+// OS-locked pruning/recovery lives beside the driver's ownership records.
+// Failure here is maintenance work, never a change to a completed smoke result.
+export function retainEvidence(root, completed, binary = 'snapback4') {
+  const result = spawnSync(binary, ['witness', 'export-cleanup', root, ...(completed ? [completed] : [])], { encoding: 'utf8', timeout: 120_000 });
+  if (result.status !== 0) console.error(`native smoke evidence cleanup deferred: ${result.stderr || result.error?.message || result.status}`);
+  return result.status === 0;
+}
+// The helper locks a duplicate of this descriptor, so the kernel lease stays
+// with this process after the helper exits. Children do not inherit it unless
+// explicitly listed in stdio (the publisher must keep it if this wrapper dies).
+export function acquireExportLease(artifacts, binary = 'snapback4') {
+  const fd = fs.openSync(path.join(artifacts, 'export.lock'), 'a+');
+  const result = spawnSync(binary, ['witness', 'export-lease', artifacts], { encoding: 'utf8', env: { ...process.env, SNAPBACK4_EXPORT_WRAPPER_PID: String(process.pid) }, stdio: ['ignore', 'pipe', 'pipe', fd] });
+  if (result.status !== 0) { fs.closeSync(fd); throw Error(result.stderr || result.error?.message || 'export lease failed'); }
+  return fd;
+}
+export async function main() {
+  const req = createRequire(path.resolve('package.json'));
+  const skip = skipReason(process.platform, process.env);
+  if (skip) {
+    const exported = await runChild(process.execPath, [req.resolve('expo/bin/cli'), 'export', '--platform', 'ios', '--dump-assetmap']);
+    if (exported.status !== 0) return exported.status;
+    console.log(`native smoke skipped: ${skip}`); return 0;
+  }
+  const root = path.resolve('artifacts/native-smoke');
+  const artifacts = path.join(root, `${Date.now()}-${process.pid}`);
+  const privateExport = path.join(artifacts, 'export');
+  const receiptPath = path.join(artifacts, 'smoke-ios-run.json');
+  fs.mkdirSync(artifacts, { recursive: true });
+  const lease = acquireExportLease(artifacts);
+  let publicationAttempted = false;
+  try {
+    const exported = await runChild(process.execPath, [req.resolve('expo/bin/cli'), 'export', '--platform', 'ios', '--dump-assetmap', '--output-dir', privateExport]);
+    if (exported.status !== 0) return exported.status;
+    const result = await runChild('snapback4', ['witness', 'ios', '--build', '.', '--smoke', '--export', privateExport, '--artifacts', artifacts], { env: { ...process.env, SNAPBACK4_EXPORT_WRAPPER_PID: String(process.pid) } });
+    let receipt;
+    try { receipt = JSON.parse(fs.readFileSync(receiptPath, 'utf8')); } catch {}
+    const outcome = result.cancelled ? { status: result.status, message: 'native smoke interrupted' } : smokeResult(result.status, receipt);
+    if (outcome.status === 0) {
+      const expected = publicationExpectation(artifacts, privateExport, result.status !== 0, receipt);
+      publicationAttempted = true;
+      const published = await runChild('snapback4', ['witness', 'export-publish', privateExport, path.resolve('dist'), ...(result.status === 0 ? [] : ['--environment-skip'])], { stdio: ['inherit', 'inherit', 'inherit', lease] });
+      try {
+        verifyPublication(artifacts, privateExport, path.resolve('dist'), expected);
+        if (published.status !== 0) throw Error(`publisher exited with status ${published.status}`);
+      } catch (error) { outcome.status = published.status || 1; outcome.message = `export output publication failed: ${error.message}`; }
+    }
+    console.log(`${outcome.message}; receipt: ${receiptPath}`);
+    return outcome.status;
+  } finally {
+    // After a publication attempt this path may be the displaced last good
+    // export. Only the publisher, under its destination lock, may remove it.
+    try { if (!publicationAttempted) fs.rmSync(privateExport, { recursive: true, force: true }); }
+    finally { fs.closeSync(lease); retainEvidence(root, artifacts); }
+  }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href) {
+  try { process.exitCode = await main(); }
+  catch (error) { console.error(`export:ios failed: ${error.message}`); process.exitCode = 1; }
+}

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "snapback4-expo",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "type": "module",
   "description": "Snapback 4's native module for Expo: the device in Rust (the partition in its own SQLite, the stream applied, the outbox kept, queries and predictions answered) behind one JSON call, and the opener `snapback4/native` takes.",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "exports": {
-    ".": { "types": "./src/index.ts", "default": "./src/index.ts" },
-    "./witness": { "types": "./src/witness.ts", "default": "./src/witness.ts" },
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./witness": {
+      "types": "./src/witness.ts",
+      "default": "./src/witness.ts"
+    },
     "./plugin": "./plugin.cjs",
     "./package.json": "./package.json"
   },
@@ -16,7 +22,8 @@
     "src",
     "ios",
     "expo-module.config.json",
-    "README.md"
+    "README.md",
+    "export-ios.mjs"
   ],
   "peerDependencies": {
     "expo": "*",
@@ -25,5 +32,8 @@
   "devDependencies": {
     "expo-modules-core": "*",
     "typescript": "5.9.3"
+  },
+  "bin": {
+    "snapback4-export-ios": "export-ios.mjs"
   }
 }

package/plugin.cjs

@@ -1,4 +1,4 @@
-// @ref LLP 3000.030#13 — the pinned Expo starter must launch on iOS 27 without a manual migration.
+// @ref LLP 3000.030#13 — one published lifecycle for reference and generated Expo 57.0.22 apps; preserve existing plugin configs.
 const { withAppDelegate, withInfoPlist } = require('expo/config-plugins');
 const marker = '// Snapback4 starter scene lifecycle';
 const legacy = `#if os(iOS) || os(tvOS)

package/src/witness.ts

@@ -21,3 +21,11 @@ export function smokeSegment(): "prime" | "offline" | "restart" | null {
   const config = JSON.parse(container.witnessLaunch);
   return config.smoke === true && ["prime", "offline", "restart"].includes(config.segment) ? config.segment : null;
 }
+
+/** Simulator smoke uses its owned loopback backend; ordinary launches keep the app URL. */
+export function smokeOrigin(fallback: string): string {
+  const container = requireOptionalNativeModule<WitnessContainer>("Snapback4");
+  if (!container?.witnessLaunch) return fallback;
+  const config = JSON.parse(container.witnessLaunch);
+  return config.smoke === true && /^http:\/\/127\.0\.0\.1:[0-9]+$/.test(config.origin) ? config.origin : fallback;
+}