snapback4-expo 0.4.15 → 0.4.25

package/README.md

@@ -102,3 +102,7 @@ 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. Automatic smoke creates and removes its own
 recorded simulator, with project and device leases held through cleanup.
+
+For durable offline media, use the local client's `uploadAndPlace` or `useUpload`
+(re-exported here). `saveAsset(client, id, name?)` presents the iOS save/share sheet
+from authorized or retained bytes. See [the shared upload contract](../snapback4/OFFLINE-UPLOADS.md).

package/export-ios.mjs

@@ -138,11 +138,22 @@ export async function main() {
   } 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 (created && !publicationAttempted) fs.rmSync(artifacts, { recursive: true, force: true }); }
+    try {
+      if (created && !publicationAttempted) {
+        // Keep custody paths and the live wrapper journal while deleting bulk
+        // output. Other exports never wait for that I/O on initialization.lock.
+        for (const name of fs.readdirSync(artifacts)) {
+          if (!['run.lock', 'export.lock', 'live.json'].includes(name)) fs.rmSync(path.join(artifacts, name), { recursive: true, force: true });
+        }
+        // @ref LLP 3000.030#15 — final removal shares shell-repair custody.
+        // A worker cannot recreate a lease file after rm's final enumeration.
+        initialization ??= acquireExportLease(root, 'snapback4', true);
+        fs.rmSync(artifacts, { recursive: true, force: true });
+      }
+    }
     finally {
       try {
         if (lease !== undefined) fs.closeSync(lease);
-        else if (created) fs.rmSync(artifacts, { recursive: true, force: true });
       } finally { if (initialization !== undefined) fs.closeSync(initialization); }
     }
   }

package/ios/SavedAsset.swift

@@ -0,0 +1,31 @@
+import Foundation
+
+// A task-owned save copy; no network fetch, token, or original cache file escapes to the sheet.
+final class SavedAsset {
+  let directory: URL
+  let url: URL
+  init(hex: String, name: String) throws {
+    guard !name.isEmpty, name != ".", name != "..", !name.contains("/"), !name.contains("\\"),
+      !name.unicodeScalars.contains(where: { CharacterSet.controlCharacters.contains($0) }),
+      hex.utf8.count <= 128 << 20, hex.utf8.count % 2 == 0 else {
+      throw NSError(domain: "Snapback4", code: 1, userInfo: [NSLocalizedDescriptionKey: "invalid save bytes or filename"])
+    }
+    let chars = Array(hex.utf8)
+    var data = Data(capacity: chars.count / 2)
+    for i in stride(from: 0, to: chars.count, by: 2) {
+      guard let byte = UInt8(String(bytes: chars[i...i+1], encoding: .utf8) ?? "", radix: 16) else {
+        throw NSError(domain: "Snapback4", code: 1, userInfo: [NSLocalizedDescriptionKey: "invalid save bytes"])
+      }
+      data.append(byte)
+    }
+    directory = FileManager.default.temporaryDirectory.appendingPathComponent("snapback4-save-" + UUID().uuidString, isDirectory: true)
+    url = directory.appendingPathComponent(name)
+    try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: false, attributes: [.posixPermissions: 0o700])
+    do {
+      try data.write(to: url, options: .atomic)
+      try FileManager.default.setAttributes([.posixPermissions: 0o600], ofItemAtPath: url.path)
+    } catch { try? FileManager.default.removeItem(at: directory); throw error }
+  }
+  func remove() { try? FileManager.default.removeItem(at: directory) }
+  deinit { remove() }
+}

package/ios/Snapback4Device.xcframework/Info.plist

@@ -10,7 +10,7 @@
 			<key>HeadersPath</key>
 			<string>Headers</string>
 			<key>LibraryIdentifier</key>
-			<string>ios-arm64</string>
+			<string>ios-arm64-simulator</string>
 			<key>LibraryPath</key>
 			<string>libsnapback4_device.a</string>
 			<key>SupportedArchitectures</key>
@@ -19,6 +19,8 @@
 			</array>
 			<key>SupportedPlatform</key>
 			<string>ios</string>
+			<key>SupportedPlatformVariant</key>
+			<string>simulator</string>
 		</dict>
 		<dict>
 			<key>BinaryPath</key>
@@ -26,7 +28,7 @@
 			<key>HeadersPath</key>
 			<string>Headers</string>
 			<key>LibraryIdentifier</key>
-			<string>ios-arm64-simulator</string>
+			<string>ios-arm64</string>
 			<key>LibraryPath</key>
 			<string>libsnapback4_device.a</string>
 			<key>SupportedArchitectures</key>
@@ -35,8 +37,6 @@
 			</array>
 			<key>SupportedPlatform</key>
 			<string>ios</string>
-			<key>SupportedPlatformVariant</key>
-			<string>simulator</string>
 		</dict>
 	</array>
 	<key>CFBundlePackageType</key>

package/ios/Snapback4Device.xcframework/ios-arm64/Headers/snapback4.h

@@ -14,6 +14,10 @@
  * panic=abort and terminates before unwinding. Every answer is JSON the
  * caller frees. A device is not thread-safe: one caller at a time, as the
  * store is one transaction at a time.
+ * A `query` answer is not always the device's to give: `unknown` without
+ * `retained` means ask the server (POST /q/<op>), and `speculative` data is a
+ * placeholder. The reply contract is "The device reply" in the snapback4
+ * package's CLIENT-AND-OPERATIONS.md.
  * `apply.first` must be true on the first page of a snapshot. It defaults
  * to false so an omitted marker cannot discard a snapshot already staged.
  */
@@ -24,6 +28,9 @@
 extern "C" {
 #endif
 
+/* Engine identity without opening a store; free the JSON with sb4_free. */
+char *sb4_engine_info(void);
+
 typedef struct sb4_device sb4_device;
 
 /* Backend may be GET /schema JSON, null for the kept backend, or

package/ios/Snapback4Device.xcframework/ios-arm64-simulator/Headers/snapback4.h

@@ -14,6 +14,10 @@
  * panic=abort and terminates before unwinding. Every answer is JSON the
  * caller frees. A device is not thread-safe: one caller at a time, as the
  * store is one transaction at a time.
+ * A `query` answer is not always the device's to give: `unknown` without
+ * `retained` means ask the server (POST /q/<op>), and `speculative` data is a
+ * placeholder. The reply contract is "The device reply" in the snapback4
+ * package's CLIENT-AND-OPERATIONS.md.
  * `apply.first` must be true on the first page of a snapshot. It defaults
  * to false so an omitted marker cannot discard a snapshot already staged.
  */
@@ -24,6 +28,9 @@
 extern "C" {
 #endif
 
+/* Engine identity without opening a store; free the JSON with sb4_free. */
+char *sb4_engine_info(void);
+
 typedef struct sb4_device sb4_device;
 
 /* Backend may be GET /schema JSON, null for the kept backend, or

package/ios/Snapback4Module.swift

@@ -1,4 +1,5 @@
 import ExpoModulesCore
+import UIKit
 import Snapback4Device
 
 // The device in Rust, opened once per store and reached through one JSON
@@ -12,6 +13,11 @@ public final class Snapback4Module: Module {
 
   public func definition() -> ModuleDefinition {
     Name("Snapback4")
+    Function("engineInfo") { () -> String in
+      guard let stamp = sb4_engine_info() else { return "{}" }
+      defer { sb4_free(stamp) }
+      return String(cString: stamp)
+    }
 
     Constant("witnessLaunch") { WitnessContainer.launch }
     Function("witnessObservation") { (scriptURL: String?) -> [String: Any]? in try WitnessContainer.observation(scriptURL) }
@@ -70,6 +76,28 @@ public final class Snapback4Module: Module {
       try self.withMedia(handle) { try $0.uri(id) }
     }
 
+    // @ref LLP 3000.038.000#4 — saving is a user action over authorized bytes, with private temporary custody.
+    AsyncFunction("saveAsset") { (hex: String, name: String, promise: Promise) in
+      do {
+        let temporary = try SavedAsset(hex: hex, name: name)
+        guard let root = UIApplication.shared.connectedScenes.compactMap({ $0 as? UIWindowScene })
+          .flatMap({ $0.windows }).first(where: { $0.isKeyWindow })?.rootViewController else {
+          temporary.remove()
+          throw Snapback4OpenException("no view can present the save sheet")
+        }
+        var presenter = root
+        while let next = presenter.presentedViewController { presenter = next }
+        let sheet = UIActivityViewController(activityItems: [temporary.url], applicationActivities: nil)
+        sheet.popoverPresentationController?.sourceView = presenter.view
+        sheet.popoverPresentationController?.sourceRect = CGRect(x: presenter.view.bounds.midX, y: presenter.view.bounds.midY, width: 1, height: 1)
+        sheet.completionWithItemsHandler = { _, completed, _, error in
+          temporary.remove()
+          if let error { promise.reject(error) } else { promise.resolve(completed) }
+        }
+        presenter.present(sheet, animated: true)
+      } catch { promise.reject(error) }
+    }.runOnQueue(.main)
+
     Function("close") { (handle: Int) in
       self.lock.lock()
       defer { self.lock.unlock() }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snapback4-expo",
-  "version": "0.4.15",
+  "version": "0.4.25",
   "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",

package/src/index.ts

@@ -8,7 +8,9 @@ import { witnessRuntime } from "./witness-runtime";
 import type { WitnessContainer } from "./witness-core";
 
 interface Snapback4Native extends WitnessContainer {
+  saveAsset(hex: string, name: string): Promise<boolean>;
   readonly documentDirectory: string;
+  engineInfo?(): string;
   open(path: string, backend: string | null): Promise<number>;
   call(handle: number, request: string): Promise<string>;
   close(handle: number): void;
@@ -36,6 +38,7 @@ export function documentDirectory(): string {
 }
 
 export const nativeDevice: DeviceOpener = {
+  async engineInfo() { try { if (native?.engineInfo) return JSON.parse(native.engineInfo()); } catch {} return { format: 0, version: "unknown (unstamped)", capabilities: [] }; },
   async open(name, backend): Promise<DeviceCore> {
     if (!native) throw new Error("snapback4-expo: the native module is not in this build (Expo Go loads no custom native code; make a development build)");
     const handle = await native.open(`${native.documentDirectory.replace(/\/$/, "")}/${name}.sqlite`, backend ? JSON.stringify(backend) : null);
@@ -60,3 +63,12 @@ export const nativeDevice: DeviceOpener = {
     return core;
   },
 };
+
+import { saveWithHost } from "./save-asset";
+import type { Client } from "snapback4/contract";
+/** Presents the native save/share sheet; cancellation is a typed refusal. */
+export function saveAsset(client: Pick<Client, "asset">, id: string, name?: string) {
+  return saveWithHost(client, id, name, native ? (hex, filename) => native.saveAsset(hex, filename) : undefined);
+}
+export { uploadAndPlace, type UploadIntent, type UploadAndPlaceOptions } from "snapback4/local";
+export { useUpload } from "snapback4/react";

package/src/save-asset.ts

@@ -0,0 +1,25 @@
+import type { Client } from "snapback4/contract";
+import type { Saved } from "snapback4/react";
+import { blobArrayBuffer } from "snapback4/local";
+
+/** Save/share only bytes already authorized by client.asset, including retained offline files. */
+export async function saveWithHost(client: Pick<Client, "asset">, id: string, name: string | undefined,
+  present: ((hex: string, name: string) => Promise<boolean>) | undefined, read: typeof fetch = fetch): Promise<Saved> {
+  if (!present) return { ok: false, why: { code: "E_CLIENT", family: "client", message: "saveAsset needs the Snapback native module in a development or production build" } };
+  let revoke: (() => void) | undefined;
+  try {
+    const asset = await client.asset(id);
+    if ("denied" in asset) return { ok: false, why: asset.denied };
+    revoke = () => asset.revoke();
+    const selected = name ?? asset.name ?? "file";
+    // Keep a single safe leaf. The native host independently validates it.
+    const filename = selected.split(/[\\/]/).pop()!.replace(/[\x00-\x1f\x7f\u202a-\u202e\u2066-\u2069]/g, "").trim().replace(/^\.+/, "").slice(0, 128) || "file";
+    if (!/^(file:|blob:|data:)/.test(asset.url)) throw new Error("asset handle is not a local byte source");
+    const response = await read(asset.url);
+    const bytes = new Uint8Array(await blobArrayBuffer(await response.blob()));
+    const completed = await present(Array.from(bytes, b => b.toString(16).padStart(2, "0")).join(""), filename);
+    return completed ? { ok: true, name: filename } : { ok: false, why: { code: "E_CANCELLED", family: "client", message: "the save sheet was cancelled" } };
+  } catch (error) {
+    return { ok: false, why: { code: "E_CLIENT", family: "client", message: `the asset could not be saved: ${String(error)}` } };
+  } finally { revoke?.(); }
+}