@g9tm/lynxcontrols-native 0.0.0-stage → 1.4.0

package/ios/src/core/G9PreferencesCore.m

@@ -0,0 +1,114 @@
+#import "G9PreferencesCore.h"
+
+static NSDictionary *G9PreferenceError(NSString *code, NSString *message) {
+  return [NSDictionary dictionaryWithObjectsAndKeys:code, @"code", message, @"message", nil];
+}
+
+static BOOL G9IsInt(id value) {
+  if (![value isKindOfClass:[NSNumber class]]) return NO;
+  const char t = [value objCType][0];
+  return t == 'i' || t == 'q' || t == 'l' || t == 's' || t == 'c';
+}
+
+@implementation G9PreferencesCore
+
+- (instancetype)initWithBackend:(id<G9PreferenceBackend>)backend {
+  if ((self = [super init])) _backend = backend;
+  return self;
+}
+
+- (id)get:(NSString *)key {
+  id value = [[_backend allValues] objectForKey:key];
+  if (G9IsInt(value)) {
+    return [NSDictionary dictionaryWithObjectsAndKeys:@"int", @"type", [NSNumber numberWithDouble:[value doubleValue]], @"value", nil];
+  }
+  if ([value isKindOfClass:[NSString class]]) {
+    return [NSDictionary dictionaryWithObjectsAndKeys:@"string", @"type", value, @"value", nil];
+  }
+  return [NSNull null];
+}
+
+- (BOOL)set:(NSString *)key kind:(NSString *)kind value:(NSString *)value error:(NSDictionary **)error {
+  if (![key isKindOfClass:[NSString class]] || [key length] == 0) {
+    if (error) *error = G9PreferenceError(@"preference-key", @"A preference key must be a non-empty string.");
+    return NO;
+  }
+  if ([kind isEqualToString:@"int"]) {
+    NSScanner *scanner = value != nil ? [NSScanner scannerWithString:value] : nil;
+    long long parsed = 0;
+    if (scanner == nil || ![scanner scanLongLong:&parsed] || ![scanner isAtEnd] || parsed < INT32_MIN || parsed > INT32_MAX) {
+      if (error) {
+        *error = G9PreferenceError(@"preference-value", [NSString stringWithFormat:@"Preference '%@' needs a 32-bit integer, got %@.", key, value]);
+      }
+      return NO;
+    }
+    [_backend setValue:[NSNumber numberWithInt:(int)parsed] forPreference:key];
+  } else if ([kind isEqualToString:@"string"]) {
+    if (value == nil || (id)value == (id)[NSNull null]) [_backend removePreference:key];
+    else [_backend setValue:value forPreference:key];
+  } else if ([kind isEqualToString:@"remove"]) {
+    [_backend removePreference:key];
+  } else {
+    if (error) *error = G9PreferenceError(@"preference-value", [NSString stringWithFormat:@"Unknown preference kind '%@'.", kind]);
+    return NO;
+  }
+  return YES;
+}
+
+- (NSArray *)entries:(NSString *)prefix {
+  NSDictionary *all = [_backend allValues];
+  NSArray *keys = [[all allKeys] sortedArrayUsingSelector:@selector(compare:)];
+  NSMutableArray *out = [NSMutableArray array];
+  for (NSString *key in keys) {
+    if (![key isKindOfClass:[NSString class]] || ![key hasPrefix:prefix]) continue;
+    id value = [all objectForKey:key];
+    if (G9IsInt(value)) [out addObject:[NSArray arrayWithObjects:key, [NSNumber numberWithDouble:[value doubleValue]], nil]];
+    else if ([value isKindOfClass:[NSString class]]) [out addObject:[NSArray arrayWithObjects:key, value, nil]];
+  }
+  return out;
+}
+
+@end
+
+@implementation G9UserDefaultsBackend
+- (instancetype)initWithSuiteName:(NSString *)suite {
+  if ((self = [super init])) {
+    _suite = [suite copy];
+    _defaults = [[NSUserDefaults alloc] initWithSuiteName:suite];
+  }
+  return self;
+}
+- (NSDictionary *)allValues {
+  // Only this suite's own values (dictionaryRepresentation would add the global and registration domains).
+  NSDictionary *domain = [_defaults persistentDomainForName:_suite];
+  return domain != nil ? domain : [NSDictionary dictionary];
+}
+- (void)setValue:(id)value forPreference:(NSString *)key {
+  [_defaults setObject:value forKey:key];
+}
+- (void)removePreference:(NSString *)key {
+  [_defaults removeObjectForKey:key];
+}
+@end
+
+@implementation G9MemoryPreferenceBackend
+- (instancetype)init {
+  if ((self = [super init])) _values = [[NSMutableDictionary alloc] init];
+  return self;
+}
+- (NSDictionary *)allValues {
+  @synchronized(self) {
+    return [NSDictionary dictionaryWithDictionary:_values];
+  }
+}
+- (void)setValue:(id)value forPreference:(NSString *)key {
+  @synchronized(self) {
+    [_values setObject:value forKey:key];
+  }
+}
+- (void)removePreference:(NSString *)key {
+  @synchronized(self) {
+    [_values removeObjectForKey:key];
+  }
+}
+@end

package/ios/src/core/G9SqliteCore.h

@@ -0,0 +1,62 @@
+// The iOS SQLite driver core (plan/specs/06 §5): sessions, transaction tokens, a statement cache per session, value
+// conversion and error mapping over the system sqlite3 C API. Foundation + sqlite3 only, written so it also compiles
+// with clang + GNUstep on Linux (no blocks, no subscripting, explicit ivars): the contract runs there in the cloud
+// (`npm run test:ios-core`) and on a simulator through XCTest.
+//
+// Errors are returned through `error` as G9 error dictionaries (`code`, `message`, `sqliteCode`, `sql`,
+// `completedStatements`), the same fields the Android core sends. Calls for one session must not overlap (the module
+// runs each session on its own serial queue); `interrupt:` may be called from any thread.
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/** Largest integer JS represents exactly (2^53 − 1). */
+extern const long long G9MaxSafeInteger;
+
+/** A G9 error dictionary. */
+NSDictionary *G9SqliteErrorMake(NSString *code, NSString *message);
+
+/** SQLite primary result code → G9 error code (mirrors `sqliteErrorCodeFor` in @g9tm/lynxcontrols-sqlite). */
+NSString *G9SqliteErrorCodeFor(int resultCode);
+
+@interface G9SqliteCore : NSObject {
+ @private
+  NSMutableDictionary *_sessions;  // token → session
+  NSMutableDictionary *_txs;       // tx → token
+  long long _counter;
+}
+
+/** Capabilities of the linked SQLite (`interrupt` is true: sqlite3_interrupt). */
+- (nullable NSDictionary *)capabilitiesWithError:(NSDictionary *_Nullable *_Nullable)error;
+
+/** `{ path, readOnly?, create?, pragmas[] }` → session token. */
+- (nullable NSString *)open:(NSDictionary *)options error:(NSDictionary *_Nullable *_Nullable)error;
+
+/**
+ * Runs a batch. `statements`: `[{ sql, params }]` with bridge values (NSNumber, NSString, NSData, NSNull,
+ * `{ int64 }`, `{ undefined: true }`). `options`: `{ tx?, maxRows?, atomic? }`. Returns one result per statement:
+ * `{ columns, rows, changes, lastInsertRowId }` with typed cells (NSNumber long long / double, NSString, NSData,
+ * NSNull); G9SqliteTransport encodes them for the bridge.
+ */
+- (nullable NSArray *)run:(NSString *)session
+               statements:(NSArray *)statements
+                  options:(NSDictionary *)options
+                    error:(NSDictionary *_Nullable *_Nullable)error;
+
+- (nullable NSString *)begin:(NSString *)session mode:(NSString *)mode error:(NSDictionary *_Nullable *_Nullable)error;
+- (BOOL)commit:(NSString *)tx error:(NSDictionary *_Nullable *_Nullable)error;
+- (BOOL)rollback:(NSString *)tx error:(NSDictionary *_Nullable *_Nullable)error;
+- (BOOL)close:(NSString *)session error:(NSDictionary *_Nullable *_Nullable)error;
+
+/** The session a transaction belongs to (the module queues tx work there), or nil. */
+- (nullable NSString *)sessionOfTx:(NSString *)tx;
+
+/** Interrupts whatever runs on the session (`sqlite3_interrupt`); the batch fails with `interrupted`. Any thread. */
+- (void)interrupt:(NSString *)session;
+
+/** Closes every session (module teardown). */
+- (void)closeAll;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/src/core/G9SqliteCore.m

@@ -0,0 +1,497 @@
+#import "G9SqliteCore.h"
+
+#include <math.h>
+#include <sqlite3.h>
+
+const long long G9MaxSafeInteger = 9007199254740991LL;
+static const NSUInteger G9StatementCacheSize = 64;
+
+NSDictionary *G9SqliteErrorMake(NSString *code, NSString *message) {
+  return [NSDictionary dictionaryWithObjectsAndKeys:code, @"code", message, @"message", nil];
+}
+
+NSString *G9SqliteErrorCodeFor(int resultCode) {
+  switch (resultCode & 0xff) {
+    case SQLITE_BUSY:
+      return @"busy";
+    case SQLITE_LOCKED:
+      return @"locked";
+    case SQLITE_CONSTRAINT:
+      return @"constraint";
+    case SQLITE_CORRUPT:
+    case SQLITE_NOTADB:
+      return @"corrupt";
+    case SQLITE_READONLY:
+      return @"readonly";
+    case SQLITE_FULL:
+      return @"full";
+    case SQLITE_INTERRUPT:
+      return @"interrupted";
+    case SQLITE_MISUSE:
+      return @"misuse";
+    case SQLITE_CANTOPEN:
+      return @"not-found";
+    default:
+      return @"other";
+  }
+}
+
+/** An error with optional context; `sqliteCode` < 0 means none. */
+static NSDictionary *G9Error(NSString *code, NSString *message, int sqliteCode, NSString *sql, NSInteger completed) {
+  NSMutableDictionary *e = [NSMutableDictionary dictionaryWithDictionary:G9SqliteErrorMake(code, message)];
+  if (sqliteCode >= 0) [e setObject:[NSNumber numberWithInt:sqliteCode] forKey:@"sqliteCode"];
+  if (sql != nil) [e setObject:sql forKey:@"sql"];
+  if (completed >= 0) [e setObject:[NSNumber numberWithInteger:completed] forKey:@"completedStatements"];
+  return e;
+}
+
+/** The connection's current error. */
+static NSDictionary *G9DbError(sqlite3 *db, NSString *sql, NSInteger completed) {
+  int code = sqlite3_extended_errcode(db);
+  NSString *message = [NSString stringWithUTF8String:sqlite3_errmsg(db)];
+  return G9Error(G9SqliteErrorCodeFor(code), message != nil ? message : @"SQLite error", code, sql, completed);
+}
+
+/** Adds statement context to an error that has none yet. */
+static NSDictionary *G9WithContext(NSDictionary *error, NSString *sql, NSInteger completed) {
+  NSMutableDictionary *e = [NSMutableDictionary dictionaryWithDictionary:error];
+  if ([e objectForKey:@"sql"] == nil && sql != nil) [e setObject:sql forKey:@"sql"];
+  if ([e objectForKey:@"completedStatements"] == nil && completed >= 0) {
+    [e setObject:[NSNumber numberWithInteger:completed] forKey:@"completedStatements"];
+  }
+  return e;
+}
+
+static void G9SetError(NSDictionary **out, NSDictionary *error) {
+  if (out != NULL) *out = error;
+}
+
+@interface G9SqliteSession : NSObject {
+ @public
+  sqlite3 *db;
+  NSMutableDictionary *statements;  // sql → NSValue(sqlite3_stmt *)
+  NSMutableArray *order;            // least recently used first
+  NSString *tx;
+  long long lastInsertRowId;
+}
+@end
+
+@implementation G9SqliteSession
+- (instancetype)init {
+  if ((self = [super init])) {
+    statements = [[NSMutableDictionary alloc] init];
+    order = [[NSMutableArray alloc] init];
+  }
+  return self;
+}
+@end
+
+@implementation G9SqliteCore
+
+- (instancetype)init {
+  if ((self = [super init])) {
+    _sessions = [[NSMutableDictionary alloc] init];
+    _txs = [[NSMutableDictionary alloc] init];
+  }
+  return self;
+}
+
+- (NSString *)nextToken:(NSString *)prefix {
+  @synchronized(self) {
+    _counter += 1;
+    return [NSString stringWithFormat:@"%@%lld", prefix, _counter];
+  }
+}
+
+- (G9SqliteSession *)session:(NSString *)token error:(NSDictionary **)error {
+  G9SqliteSession *session = nil;
+  if ([token isKindOfClass:[NSString class]]) {
+    @synchronized(self) {
+      session = [_sessions objectForKey:token];
+    }
+  }
+  if (session == nil) G9SetError(error, G9SqliteErrorMake(@"misuse", @"The database session is closed or unknown."));
+  return session;
+}
+
+- (NSDictionary *)capabilitiesWithError:(NSDictionary **)error {
+  NSString *version = [NSString stringWithUTF8String:sqlite3_libversion()];
+  int number = sqlite3_libversion_number();
+  return [NSDictionary dictionaryWithObjectsAndKeys:version, @"sqliteVersion",
+                                                    [NSNumber numberWithInt:32766], @"maxVariables",
+                                                    [NSNumber numberWithBool:YES], @"json1",
+                                                    [NSNumber numberWithBool:number >= 3035000], @"returning",
+                                                    [NSNumber numberWithBool:number >= 3024000], @"upsert",
+                                                    [NSNumber numberWithBool:YES], @"interrupt", nil];
+}
+
+- (NSString *)open:(NSDictionary *)options error:(NSDictionary **)error {
+  NSString *path = [options objectForKey:@"path"];
+  if (![path isKindOfClass:[NSString class]]) {
+    G9SetError(error, G9SqliteErrorMake(@"misuse", @"open needs a path."));
+    return nil;
+  }
+  BOOL readOnly = [[options objectForKey:@"readOnly"] isEqual:[NSNumber numberWithBool:YES]];
+  BOOL create = [[options objectForKey:@"create"] isEqual:[NSNumber numberWithBool:YES]];
+  BOOL memory = [path length] == 0 || [path isEqualToString:@":memory:"];
+  if (!memory) {
+    NSFileManager *files = [NSFileManager defaultManager];
+    if (!create && ![files fileExistsAtPath:path]) {
+      G9SetError(error, G9SqliteErrorMake(@"not-found", [NSString stringWithFormat:@"Database file does not exist: %@", path]));
+      return nil;
+    }
+    if (create) {
+      [files createDirectoryAtPath:[path stringByDeletingLastPathComponent]
+          withIntermediateDirectories:YES
+                           attributes:nil
+                                error:NULL];
+    }
+  }
+  int flags = (readOnly ? SQLITE_OPEN_READONLY : SQLITE_OPEN_READWRITE) | (create && !readOnly ? SQLITE_OPEN_CREATE : 0) |
+              SQLITE_OPEN_FULLMUTEX;
+  sqlite3 *db = NULL;
+  int rc = sqlite3_open_v2(memory ? ":memory:" : [path fileSystemRepresentation], &db, flags, NULL);
+  if (rc != SQLITE_OK) {
+    NSDictionary *e = db != NULL ? G9DbError(db, nil, -1)
+                                 : G9Error(G9SqliteErrorCodeFor(rc), @"Cannot open the database.", rc, nil, -1);
+    sqlite3_close(db);
+    G9SetError(error, e);
+    return nil;
+  }
+  sqlite3_extended_result_codes(db, 1);
+  NSArray *pragmas = [options objectForKey:@"pragmas"];
+  if ([pragmas isKindOfClass:[NSArray class]]) {
+    for (NSString *sql in pragmas) {
+      if (sqlite3_exec(db, [sql UTF8String], NULL, NULL, NULL) != SQLITE_OK) {
+        // journal_mode cannot change on a read-only or in-memory database; tuning never fails an open.
+        if (![sql hasPrefix:@"PRAGMA journal_mode"]) {
+          NSDictionary *e = G9DbError(db, sql, -1);
+          sqlite3_close(db);
+          G9SetError(error, e);
+          return nil;
+        }
+      }
+    }
+  }
+  G9SqliteSession *session = [[G9SqliteSession alloc] init];
+  session->db = db;
+  NSString *token = [self nextToken:@"s"];
+  @synchronized(self) {
+    [_sessions setObject:session forKey:token];
+  }
+  return token;
+}
+
+- (sqlite3_stmt *)prepare:(G9SqliteSession *)session sql:(NSString *)sql error:(NSDictionary **)error {
+  NSValue *cached = [session->statements objectForKey:sql];
+  if (cached != nil) {
+    [session->order removeObject:sql];
+    [session->order addObject:sql];
+    return (sqlite3_stmt *)[cached pointerValue];
+  }
+  sqlite3_stmt *stmt = NULL;
+  if (sqlite3_prepare_v2(session->db, [sql UTF8String], -1, &stmt, NULL) != SQLITE_OK) {
+    G9SetError(error, G9DbError(session->db, sql, -1));
+    return NULL;
+  }
+  [session->statements setObject:[NSValue valueWithPointer:stmt] forKey:sql];
+  [session->order addObject:sql];
+  if ([session->order count] > G9StatementCacheSize) {
+    NSString *eldest = [session->order objectAtIndex:0];
+    sqlite3_finalize((sqlite3_stmt *)[[session->statements objectForKey:eldest] pointerValue]);
+    [session->statements removeObjectForKey:eldest];
+    [session->order removeObjectAtIndex:0];
+  }
+  return stmt;
+}
+
+/** Binds one bridge value; NO with `error` set when the value is not a SQL value. */
+- (BOOL)bind:(id)value to:(sqlite3_stmt *)stmt at:(int)index sql:(NSString *)sql error:(NSDictionary **)error {
+  int rc;
+  if (value == nil || value == (id)[NSNull null]) {
+    rc = sqlite3_bind_null(stmt, index);
+  } else if ([value isKindOfClass:[NSString class]]) {
+    NSString *text = value;
+    if ([text rangeOfString:[NSString stringWithFormat:@"%C", (unichar)0]].location != NSNotFound) {
+      G9SetError(error, G9Error(@"misuse", [NSString stringWithFormat:@"Parameter %d is text containing NUL; use a BLOB.", index], -1, sql, -1));
+      return NO;
+    }
+    rc = sqlite3_bind_text(stmt, index, [text UTF8String], -1, SQLITE_TRANSIENT);
+  } else if ([value isKindOfClass:[NSData class]]) {
+    NSData *data = value;
+    rc = [data length] == 0 ? sqlite3_bind_zeroblob(stmt, index, 0)
+                            : sqlite3_bind_blob(stmt, index, [data bytes], (int)[data length], SQLITE_TRANSIENT);
+  } else if ([value isKindOfClass:[NSNumber class]]) {
+    NSNumber *number = value;
+    const char *type = [number objCType];
+    BOOL integral = type[0] == 'q' || type[0] == 'l' || type[0] == 'i' || type[0] == 's' || type[0] == 'c' ||
+                    type[0] == 'Q' || type[0] == 'L' || type[0] == 'I' || type[0] == 'S' || type[0] == 'C' || type[0] == 'B';
+    if (integral) {
+      rc = sqlite3_bind_int64(stmt, index, [number longLongValue]);
+    } else {
+      double d = [number doubleValue];
+      if (isnan(d)) {
+        G9SetError(error, G9Error(@"misuse", [NSString stringWithFormat:@"Parameter %d is NaN.", index], -1, sql, -1));
+        return NO;
+      }
+      // Safe-integer doubles bind as INTEGER, as Node does (Number.isSafeInteger).
+      if (d == floor(d) && fabs(d) <= (double)G9MaxSafeInteger) {
+        rc = sqlite3_bind_int64(stmt, index, (sqlite3_int64)d);
+      } else {
+        rc = sqlite3_bind_double(stmt, index, d);
+      }
+    }
+  } else if ([value isKindOfClass:[NSDictionary class]] && [[value objectForKey:@"int64"] isKindOfClass:[NSString class]]) {
+    NSString *decimal = [value objectForKey:@"int64"];
+    NSScanner *scanner = [NSScanner scannerWithString:decimal];
+    long long parsed = 0;
+    if (![scanner scanLongLong:&parsed] || ![scanner isAtEnd]) {
+      G9SetError(error, G9Error(@"misuse", [NSString stringWithFormat:@"Parameter %d is not a 64-bit integer.", index], -1, sql, -1));
+      return NO;
+    }
+    rc = sqlite3_bind_int64(stmt, index, parsed);
+  } else if ([value isKindOfClass:[NSDictionary class]] && [value objectForKey:@"undefined"] != nil) {
+    G9SetError(error, G9Error(@"misuse", @"undefined is not a SQL value (use null).", -1, sql, -1));
+    return NO;
+  } else {
+    G9SetError(error, G9Error(@"misuse", [NSString stringWithFormat:@"Parameter %d is not a SQL value.", index], -1, sql, -1));
+    return NO;
+  }
+  if (rc != SQLITE_OK) {
+    G9SetError(error, G9Error(G9SqliteErrorCodeFor(rc), [NSString stringWithUTF8String:sqlite3_errstr(rc)], rc, sql, -1));
+    return NO;
+  }
+  return YES;
+}
+
+static id G9ReadColumn(sqlite3_stmt *stmt, int column) {
+  switch (sqlite3_column_type(stmt, column)) {
+    case SQLITE_NULL:
+      return [NSNull null];
+    case SQLITE_INTEGER:
+      return [NSNumber numberWithLongLong:sqlite3_column_int64(stmt, column)];
+    case SQLITE_FLOAT:
+      return [NSNumber numberWithDouble:sqlite3_column_double(stmt, column)];
+    case SQLITE_TEXT: {
+      const unsigned char *text = sqlite3_column_text(stmt, column);
+      int length = sqlite3_column_bytes(stmt, column);
+      NSString *s = [[NSString alloc] initWithBytes:text length:(NSUInteger)length encoding:NSUTF8StringEncoding];
+      return s != nil ? s : @"";
+    }
+    default: {
+      const void *bytes = sqlite3_column_blob(stmt, column);
+      int length = sqlite3_column_bytes(stmt, column);
+      return length > 0 ? [NSData dataWithBytes:bytes length:(NSUInteger)length] : [NSData data];
+    }
+  }
+}
+
+- (NSDictionary *)execute:(G9SqliteSession *)session
+                statement:(NSDictionary *)statement
+                  maxRows:(NSInteger)maxRows
+                    error:(NSDictionary **)error {
+  NSString *sql = [statement isKindOfClass:[NSDictionary class]] ? [statement objectForKey:@"sql"] : nil;
+  if (![sql isKindOfClass:[NSString class]]) {
+    G9SetError(error, G9SqliteErrorMake(@"misuse", @"A statement must be an object { sql, params }."));
+    return nil;
+  }
+  sqlite3_stmt *stmt = [self prepare:session sql:sql error:error];
+  if (stmt == NULL) return nil;
+  NSArray *params = [statement objectForKey:@"params"];
+  NSDictionary *result = nil;
+  BOOL ok = YES;
+  if ([params isKindOfClass:[NSArray class]]) {
+    for (NSUInteger i = 0; i < [params count] && ok; i++) {
+      ok = [self bind:[params objectAtIndex:i] to:stmt at:(int)i + 1 sql:sql error:error];
+    }
+  }
+  if (ok) {
+    int count = sqlite3_column_count(stmt);
+    if (count > 0) {
+      NSMutableArray *columns = [NSMutableArray arrayWithCapacity:(NSUInteger)count];
+      for (int c = 0; c < count; c++) [columns addObject:[NSString stringWithUTF8String:sqlite3_column_name(stmt, c)]];
+      NSMutableArray *rows = [NSMutableArray array];
+      int rc;
+      while ((rc = sqlite3_step(stmt)) == SQLITE_ROW) {
+        if (maxRows >= 0 && (NSInteger)[rows count] >= maxRows) {
+          G9SetError(error, G9Error(@"too-many-rows", [NSString stringWithFormat:@"The statement returned more than %ld rows.", (long)maxRows], -1, sql, -1));
+          ok = NO;
+          break;
+        }
+        NSMutableArray *row = [NSMutableArray arrayWithCapacity:(NSUInteger)count];
+        for (int c = 0; c < count; c++) [row addObject:G9ReadColumn(stmt, c)];
+        [rows addObject:row];
+      }
+      if (ok && rc != SQLITE_DONE) {
+        G9SetError(error, G9DbError(session->db, sql, -1));
+        ok = NO;
+      }
+      if (ok) {
+        result = [NSDictionary dictionaryWithObjectsAndKeys:columns, @"columns", rows, @"rows",
+                                                           [NSNumber numberWithLongLong:0], @"changes",
+                                                           [NSNumber numberWithLongLong:session->lastInsertRowId], @"lastInsertRowId", nil];
+      }
+    } else {
+      int rc;
+      while ((rc = sqlite3_step(stmt)) == SQLITE_ROW) {
+      }
+      if (rc != SQLITE_DONE) {
+        G9SetError(error, G9DbError(session->db, sql, -1));
+        ok = NO;
+      } else {
+        session->lastInsertRowId = sqlite3_last_insert_rowid(session->db);
+        result = [NSDictionary dictionaryWithObjectsAndKeys:[NSArray array], @"columns", [NSArray array], @"rows",
+                                                           [NSNumber numberWithLongLong:sqlite3_changes(session->db)], @"changes",
+                                                           [NSNumber numberWithLongLong:session->lastInsertRowId], @"lastInsertRowId", nil];
+      }
+    }
+  }
+  sqlite3_reset(stmt);
+  sqlite3_clear_bindings(stmt);
+  return ok ? result : nil;
+}
+
+- (NSArray *)run:(NSString *)token statements:(NSArray *)statements options:(NSDictionary *)options error:(NSDictionary **)error {
+  G9SqliteSession *session = [self session:token error:error];
+  if (session == nil) return nil;
+  NSString *tx = [options objectForKey:@"tx"];
+  if (![tx isKindOfClass:[NSString class]]) tx = nil;
+  if (tx != nil && ![tx isEqual:session->tx]) {
+    G9SetError(error, G9SqliteErrorMake(@"misuse", @"The transaction is finished or belongs to another session."));
+    return nil;
+  }
+  if (tx == nil && session->tx != nil) {
+    G9SetError(error, G9SqliteErrorMake(@"misuse", @"A transaction is open on this session; pass its token (tx)."));
+    return nil;
+  }
+  NSNumber *maxRowsValue = [options objectForKey:@"maxRows"];
+  NSInteger maxRows = [maxRowsValue isKindOfClass:[NSNumber class]] ? [maxRowsValue integerValue] : -1;
+  BOOL atomic = [[options objectForKey:@"atomic"] isEqual:[NSNumber numberWithBool:YES]] && tx == nil && [statements count] > 0;
+  if (atomic && sqlite3_exec(session->db, "BEGIN", NULL, NULL, NULL) != SQLITE_OK) {
+    G9SetError(error, G9DbError(session->db, @"BEGIN", 0));
+    return nil;
+  }
+  NSMutableArray *results = [NSMutableArray arrayWithCapacity:[statements count]];
+  for (NSDictionary *statement in statements) {
+    NSDictionary *failure = nil;
+    NSDictionary *result = [self execute:session statement:statement maxRows:maxRows error:&failure];
+    if (result == nil) {
+      NSString *sql = [statement isKindOfClass:[NSDictionary class]] ? [statement objectForKey:@"sql"] : nil;
+      if (atomic) sqlite3_exec(session->db, "ROLLBACK", NULL, NULL, NULL);  // SQLite may already have rolled back.
+      G9SetError(error, G9WithContext(failure, [sql isKindOfClass:[NSString class]] ? sql : nil, (NSInteger)[results count]));
+      return nil;
+    }
+    [results addObject:result];
+  }
+  if (atomic && sqlite3_exec(session->db, "COMMIT", NULL, NULL, NULL) != SQLITE_OK) {
+    NSDictionary *e = G9DbError(session->db, @"COMMIT", (NSInteger)[results count]);
+    sqlite3_exec(session->db, "ROLLBACK", NULL, NULL, NULL);
+    G9SetError(error, e);
+    return nil;
+  }
+  return results;
+}
+
+- (NSString *)begin:(NSString *)token mode:(NSString *)mode error:(NSDictionary **)error {
+  G9SqliteSession *session = [self session:token error:error];
+  if (session == nil) return nil;
+  if (session->tx != nil) {
+    G9SetError(error, G9SqliteErrorMake(@"misuse", @"A transaction is already open on this session."));
+    return nil;
+  }
+  const char *sql = [mode isEqualToString:@"immediate"] ? "BEGIN IMMEDIATE" : "BEGIN DEFERRED";
+  if (sqlite3_exec(session->db, sql, NULL, NULL, NULL) != SQLITE_OK) {
+    G9SetError(error, G9DbError(session->db, nil, -1));
+    return nil;
+  }
+  NSString *tx = [self nextToken:@"x"];
+  session->tx = tx;
+  @synchronized(self) {
+    [_txs setObject:token forKey:tx];
+  }
+  return tx;
+}
+
+- (NSString *)sessionOfTx:(NSString *)tx {
+  if (![tx isKindOfClass:[NSString class]]) return nil;
+  @synchronized(self) {
+    return [_txs objectForKey:tx];
+  }
+}
+
+- (G9SqliteSession *)sessionForTx:(NSString *)tx error:(NSDictionary **)error {
+  NSString *token = [self sessionOfTx:tx];
+  G9SqliteSession *session = nil;
+  if (token != nil) {
+    @synchronized(self) {
+      session = [_sessions objectForKey:token];
+    }
+  }
+  if (session == nil || ![session->tx isEqual:tx]) {
+    G9SetError(error, G9SqliteErrorMake(@"misuse", @"The transaction is finished or unknown."));
+    return nil;
+  }
+  return session;
+}
+
+- (BOOL)commit:(NSString *)tx error:(NSDictionary **)error {
+  G9SqliteSession *session = [self sessionForTx:tx error:error];
+  if (session == nil) return NO;
+  if (sqlite3_exec(session->db, "COMMIT", NULL, NULL, NULL) != SQLITE_OK) {
+    // A failed COMMIT (busy) leaves the transaction open: the caller may retry or roll back.
+    G9SetError(error, G9DbError(session->db, nil, -1));
+    return NO;
+  }
+  session->tx = nil;
+  @synchronized(self) {
+    [_txs removeObjectForKey:tx];
+  }
+  return YES;
+}
+
+- (BOOL)rollback:(NSString *)tx error:(NSDictionary **)error {
+  G9SqliteSession *session = [self sessionForTx:tx error:error];
+  if (session == nil) return NO;
+  session->tx = nil;
+  @synchronized(self) {
+    [_txs removeObjectForKey:tx];
+  }
+  // SQLite may already have rolled back on an error; the transaction is over either way.
+  sqlite3_exec(session->db, "ROLLBACK", NULL, NULL, NULL);
+  return YES;
+}
+
+- (BOOL)close:(NSString *)token error:(NSDictionary **)error {
+  G9SqliteSession *session = [self session:token error:error];
+  if (session == nil) return NO;
+  @synchronized(self) {
+    [_sessions removeObjectForKey:token];
+    if (session->tx != nil) [_txs removeObjectForKey:session->tx];
+    session->tx = nil;
+    for (NSValue *value in [session->statements allValues]) sqlite3_finalize((sqlite3_stmt *)[value pointerValue]);
+    [session->statements removeAllObjects];
+    [session->order removeAllObjects];
+    // Under the lock, so a concurrent interrupt: never touches a closed handle.
+    sqlite3_close_v2(session->db);
+    session->db = NULL;
+  }
+  return YES;
+}
+
+- (void)interrupt:(NSString *)token {
+  if (![token isKindOfClass:[NSString class]]) return;
+  @synchronized(self) {
+    G9SqliteSession *session = [_sessions objectForKey:token];
+    if (session != nil && session->db != NULL) sqlite3_interrupt(session->db);
+  }
+}
+
+- (void)closeAll {
+  NSArray *tokens;
+  @synchronized(self) {
+    tokens = [_sessions allKeys];
+  }
+  for (NSString *token in tokens) [self close:token error:NULL];
+}
+
+@end

package/ios/src/core/G9SqliteTransport.h

@@ -0,0 +1,16 @@
+// How results cross to JS (plan/specs/06 §6), byte-identical to the Android encoder (G9SqliteTransport.kt) and pinned
+// by packages/native/contract/transport-golden.json: `columnar` (default) or `rows`. Foundation only.
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface G9SqliteTransport : NSObject
+/** A 64-bit integer as the bridge carries it: a safe integer as a double NSNumber, otherwise `{ int64: "…" }`. */
++ (id)wireNumber:(long long)value;
+/** `{ transport, results }` for the core's results. */
++ (NSDictionary *)encode:(NSArray *)results transport:(nullable NSString *)transport;
++ (NSDictionary *)rows:(NSDictionary *)result;
++ (NSDictionary *)columnar:(NSDictionary *)result;
+@end
+
+NS_ASSUME_NONNULL_END