snapback4-expo 0.2.6 → 0.2.7

package/README.md

@@ -32,7 +32,7 @@ linked and about a millisecond per call; those measurements predate the
 native-query host.
 
 Earlier iOS simulator evidence from the repository's witness in a development
-build (`WITNESS_DEV_CLIENT=1 node witness/expo.mjs`, recorded in
+build (before the published driver, recorded in
 `metrics/witness.jsonl` as `dev-client-native`): a cold sync of 303 rows
 in 31 ms, a reopen in 6 ms, a cold start with no network answering the
 thread from the store in 2 ms, and writes composed offline surviving a
@@ -46,3 +46,15 @@ file storage beside each device store in Documents. Offline `client.asset` and
 on home-row revocation, deletion, clearing or expiry and on sign-out; `once`
 bytes never enter file storage. Rebuild the native app to include this storage
 capability. `keep: "none"` (default) retains no bytes.
+
+## Simulator witness
+
+Import `witness` from `snapback4-expo/witness` in an installed iOS Release
+app. `witness()` is null on ordinary launches; under `snapback4 witness ios`
+it returns `{ segment, step(name, fn), receipt(object), waitFor(label) }`.
+The `Witness` type is exported from the same subpath. Rebuild the native app
+to include the launch-environment and Documents-file bridge. The full chat
+runner, commands and artifact contract are in `snapback4 guide witness`
+(aliases: `simulator`, `offline proof`) and the client package README's
+“Proving it on an iOS simulator”. No Expo Go or Metro process supplies a
+Release witness.

package/ios/Snapback4Expo.podspec

@@ -19,8 +19,15 @@ Pod::Spec.new do |s|
   # built by scripts/build-xcframework.sh.
   s.vendored_frameworks = 'Snapback4Device.xcframework'
   s.source_files = '*.swift'
+  # The xcframework carries arm64 device and arm64 simulator slices only, so a
+  # Release simulator build (which otherwise builds x86_64 too) must not ask
+  # for an Intel slice: exclude it for simulator SDKs in the pod and the app.
   s.pod_target_xcconfig = {
     'DEFINES_MODULE' => 'YES',
-    'SWIFT_COMPILATION_MODE' => 'wholemodule'
+    'SWIFT_COMPILATION_MODE' => 'wholemodule',
+    'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'x86_64'
+  }
+  s.user_target_xcconfig = {
+    'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'x86_64'
   }
 end

package/ios/Snapback4Module.swift

@@ -13,6 +13,10 @@ public final class Snapback4Module: Module {
   public func definition() -> ModuleDefinition {
     Name("Snapback4")
 
+    Constant("witnessLaunch") { WitnessContainer.launch }
+    Function("witnessAppend") { (line: String) in try WitnessContainer.append(line) }
+    Function("witnessSignaled") { (label: String) -> Bool in try WitnessContainer.signaled(label) }
+
     // Where an app keeps its stores: the documents directory.
     Constant("documentDirectory") {
       FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first?.path ?? NSTemporaryDirectory()

package/ios/WitnessContainer.swift

@@ -0,0 +1,46 @@
+import Foundation
+
+// Runtime environment is not exposed to Hermes by Expo. This small bridge
+// supplies it and durable file append; the scenario and protocol live in JS.
+enum WitnessContainer {
+  static var launch: String? {
+    #if targetEnvironment(simulator)
+    return ProcessInfo.processInfo.environment["SNAPBACK4_WITNESS"]
+    #else
+    return nil
+    #endif
+  }
+
+  private static func directory() throws -> URL {
+    guard let launch, let bytes = launch.data(using: .utf8),
+      let config = try JSONSerialization.jsonObject(with: bytes) as? [String: Any],
+      let run = config["run"] as? String, !run.isEmpty,
+      run.utf8.allSatisfy({ ($0 >= 48 && $0 <= 57) || ($0 >= 97 && $0 <= 122) || $0 == 45 })
+    else { throw Snapback4OpenException("E_WITNESS_INPUT: no valid simulator witness launch") }
+    let documents = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
+    return documents.appendingPathComponent(".snapback4-witness/\(run)", isDirectory: true)
+  }
+
+  static func append(_ line: String) throws {
+    let directory = try directory()
+    try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+    let file = directory.appendingPathComponent("receipts.jsonl")
+    if !FileManager.default.fileExists(atPath: file.path) {
+      guard FileManager.default.createFile(atPath: file.path, contents: nil) else {
+        throw Snapback4OpenException("E_WITNESS_RECEIPT: cannot create receipts file")
+      }
+    }
+    let handle = try FileHandle(forWritingTo: file)
+    defer { try? handle.close() }
+    try handle.seekToEnd()
+    try handle.write(contentsOf: Data(line.utf8))
+    try handle.synchronize()
+  }
+
+  static func signaled(_ label: String) throws -> Bool {
+    guard !label.isEmpty, label.utf8.allSatisfy({
+      ($0 >= 48 && $0 <= 57) || ($0 >= 65 && $0 <= 90) || ($0 >= 97 && $0 <= 122) || $0 == 45 || $0 == 95
+    }) else { throw Snapback4OpenException("E_WITNESS_INPUT: invalid signal label") }
+    return FileManager.default.fileExists(atPath: try directory().appendingPathComponent(label).path)
+  }
+}

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "snapback4-expo",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "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" },
+    "./package.json": "./package.json"
+  },
   "files": [
     "src",
     "ios",

package/src/witness-core.ts

@@ -0,0 +1,66 @@
+/** The app owns receipt fields; only `witness` is reserved for this protocol. */
+export interface Witness {
+  readonly segment: string;
+  step<T>(name: string, fn: () => T | Promise<T>): Promise<T>;
+  receipt(object: Record<string, unknown>): Promise<void>;
+  waitFor(label: string): Promise<void>;
+}
+
+export interface WitnessContainer {
+  readonly witnessLaunch: string | null;
+  witnessAppend(line: string): void;
+  witnessSignaled(label: string): boolean;
+}
+
+// @ref LLP 3000.007#20.10 — app-owned receipts, completed steps and container-file signals
+export function createWitness(container: WitnessContainer | null): Witness | null {
+  if (!container?.witnessLaunch) return null;
+  const { segment, timeoutMs } = JSON.parse(container.witnessLaunch);
+  if (typeof segment !== "string" || !segment || !Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+    throw new Error("E_WITNESS_INPUT: invalid witness launch configuration");
+  }
+  const native = container;
+  let current = "launched";
+  let active = false;
+  const append = (object: Record<string, unknown>, step: string) => {
+    if (!object || Array.isArray(object) || typeof object !== "object" || "witness" in object) {
+      throw new Error("E_WITNESS_RECEIPT: receipt must be an object without the reserved witness key");
+    }
+    // Serialize app code before installing the protocol envelope: neither a
+    // getter nor toJSON can run again on the parsed plain object.
+    let serialized: Record<string, unknown>;
+    try {
+      serialized = JSON.parse(JSON.stringify(object));
+      if (!serialized || Array.isArray(serialized) || typeof serialized !== "object" || "witness" in serialized) throw Error();
+    } catch {
+      throw new Error("E_WITNESS_RECEIPT: serialized receipt must be an object without the reserved witness key");
+    }
+    native.witnessAppend(`${JSON.stringify({ ...serialized, witness: { at: new Date().toISOString(), step } })}\n`);
+  };
+  return {
+    segment,
+    async receipt(object) { append(object, current); },
+    async step(name, fn) {
+      if (!/^[a-zA-Z0-9_-]+$/.test(name) || active) throw new Error("E_WITNESS_STEP: steps must be named and sequential");
+      active = true;
+      current = `${name}:running`;
+      try {
+        const value = await fn();
+        append({}, name);
+        return value;
+      } catch (error) {
+        // The failure's own message is the first thing anyone reading the receipts needs.
+        append({ error: error instanceof Error ? error.message : String(error) }, `${name}:failed`);
+        throw error;
+      } finally { active = false; current = "between-steps"; }
+    },
+    async waitFor(label) {
+      if (!/^[a-zA-Z0-9_-]+$/.test(label)) throw new Error("E_WITNESS_INPUT: invalid signal label");
+      const end = Date.now() + timeoutMs;
+      while (!native.witnessSignaled(label)) {
+        if (Date.now() >= end) throw new Error(`E_WITNESS_TIMEOUT: waiting for ${label}`);
+        await new Promise((resolve) => setTimeout(resolve, 100));
+      }
+    },
+  };
+}

package/src/witness.ts

@@ -0,0 +1,10 @@
+import { requireOptionalNativeModule } from "expo-modules-core";
+import { createWitness, type Witness, type WitnessContainer } from "./witness-core";
+export type { Witness } from "./witness-core";
+
+let instance: Witness | null | undefined;
+/** Null on ordinary launches and outside an iOS simulator driven by `snapback4 witness ios`. */
+export function witness(): Witness | null {
+  if (instance === undefined) instance = createWitness(requireOptionalNativeModule<WitnessContainer>("Snapback4"));
+  return instance;
+}