@g9tm/lynxcontrols-native 0.0.0-stage → 1.4.2

package/ios/Tests/G9NativeTestSuite.m

@@ -0,0 +1,560 @@
+#import "G9NativeTestSuite.h"
+
+#include <math.h>
+#include <unistd.h>
+
+#import "../src/core/G9HostPaths.h"
+#import "../src/core/G9PreferencesCore.h"
+#import "../src/core/G9VideoCore.h"
+#import "../src/core/G9SqliteCore.h"
+#import "../src/core/G9SqliteTransport.h"
+
+#pragma mark - Values
+
+static NSData *G9Hex(NSString *hex) {
+  NSMutableData *data = [NSMutableData dataWithCapacity:[hex length] / 2];
+  for (NSUInteger i = 0; i + 1 < [hex length]; i += 2) {
+    unsigned int byte = 0;
+    [[NSScanner scannerWithString:[hex substringWithRange:NSMakeRange(i, 2)]] scanHexInt:&byte];
+    uint8_t b = (uint8_t)byte;
+    [data appendBytes:&b length:1];
+  }
+  return data;
+}
+
+static NSString *G9ToHex(NSData *data) {
+  NSMutableString *out = [NSMutableString stringWithCapacity:[data length] * 2];
+  const uint8_t *bytes = [data bytes];
+  for (NSUInteger i = 0; i < [data length]; i++) [out appendFormat:@"%02x", bytes[i]];
+  return out;
+}
+
+/** A cases.json value → what the JS adapter sends (numbers as doubles, BLOBs as NSData). */
+static id G9ToBridge(id value) {
+  if (value == nil || value == (id)[NSNull null]) return [NSNull null];
+  if ([value isKindOfClass:[NSString class]]) return value;
+  if ([value isKindOfClass:[NSNumber class]]) return [NSNumber numberWithDouble:[value doubleValue]];
+  NSDictionary *d = value;
+  if ([d objectForKey:@"int64"] != nil) return [NSDictionary dictionaryWithObject:[d objectForKey:@"int64"] forKey:@"int64"];
+  if ([d objectForKey:@"blob"] != nil) return G9Hex([d objectForKey:@"blob"]);
+  if ([d objectForKey:@"blobRepeat"] != nil) {
+    NSDictionary *r = [d objectForKey:@"blobRepeat"];
+    NSMutableData *data = [NSMutableData dataWithLength:[[r objectForKey:@"count"] unsignedIntegerValue]];
+    memset([data mutableBytes], [[r objectForKey:@"byte"] intValue], [data length]);
+    return data;
+  }
+  if ([d objectForKey:@"real"] != nil) {
+    return [NSNumber numberWithDouble:[[d objectForKey:@"real"] isEqual:@"Infinity"] ? INFINITY : -INFINITY];
+  }
+  return [NSDictionary dictionaryWithObject:[NSNumber numberWithBool:YES] forKey:@"undefined"];
+}
+
+/** `Object.is` between a decoded cell and an expected contract value. */
+static BOOL G9Same(id actual, id expected) {
+  id e = G9ToBridge(expected);
+  if (e == (id)[NSNull null]) return actual == (id)[NSNull null];
+  if ([e isKindOfClass:[NSData class]]) return [actual isKindOfClass:[NSData class]] && [actual isEqualToData:e];
+  if ([e isKindOfClass:[NSDictionary class]]) {
+    return [actual isKindOfClass:[NSDictionary class]] && [[actual objectForKey:@"int64"] isEqual:[e objectForKey:@"int64"]];
+  }
+  if ([e isKindOfClass:[NSNumber class]]) {
+    if (![actual isKindOfClass:[NSNumber class]]) return NO;
+    double a = [actual doubleValue], b = [e doubleValue];
+    return a == b && signbit(a) == signbit(b);
+  }
+  return [actual isEqual:e];
+}
+
+static NSString *G9Describe(id value) {
+  if ([value isKindOfClass:[NSData class]]) {
+    return [value length] > 32 ? [NSString stringWithFormat:@"blob(%lu)", (unsigned long)[value length]]
+                               : [NSString stringWithFormat:@"blob(%@)", G9ToHex(value)];
+  }
+  return [value description];
+}
+
+#pragma mark - Decoder (twin of packages/native/src/transport.ts)
+
+static NSArray *G9Decode(NSDictionary *value) {
+  NSMutableArray *out = [NSMutableArray array];
+  BOOL rows = [[value objectForKey:@"transport"] isEqual:@"rows"];
+  for (NSDictionary *result in [value objectForKey:@"results"]) {
+    if (rows) {
+      [out addObject:result];
+      continue;
+    }
+    NSArray *columns = [result objectForKey:@"columns"];
+    NSInteger rowCount = [[result objectForKey:@"rowCount"] integerValue];
+    const uint8_t *types = [[result objectForKey:@"types"] bytes];
+    const uint8_t *numbers = [[result objectForKey:@"numbers"] bytes];
+    NSData *blobs = [result objectForKey:@"blobs"];
+    NSArray *strings = [result objectForKey:@"strings"];
+    NSUInteger cell = 0, number = 0, string = 0, blob = 0;
+    NSMutableArray *decoded = [NSMutableArray array];
+    for (NSInteger r = 0; r < rowCount; r++) {
+      NSMutableArray *row = [NSMutableArray array];
+      for (NSUInteger c = 0; c < [columns count]; c++) {
+        uint8_t tag = types[cell++];
+        if (tag == 1 || tag == 4) {
+          double d;
+          memcpy(&d, numbers + number * 8, 8);
+          number++;
+          if (tag == 1) {
+            [row addObject:[NSNumber numberWithDouble:d]];
+          } else {
+            [row addObject:[blobs subdataWithRange:NSMakeRange(blob, (NSUInteger)d)]];
+            blob += (NSUInteger)d;
+          }
+        } else if (tag == 2) {
+          [row addObject:[NSDictionary dictionaryWithObject:[strings objectAtIndex:string++] forKey:@"int64"]];
+        } else if (tag == 3) {
+          [row addObject:[strings objectAtIndex:string++]];
+        } else {
+          [row addObject:[NSNull null]];
+        }
+      }
+      [decoded addObject:row];
+    }
+    [out addObject:[NSDictionary dictionaryWithObjectsAndKeys:columns, @"columns", decoded, @"rows",
+                                                             [result objectForKey:@"changes"], @"changes",
+                                                             [result objectForKey:@"lastInsertRowId"], @"lastInsertRowId", nil]];
+  }
+  return out;
+}
+
+#pragma mark - Contract runner (step for step as run-contract.ts / ContractRunner.kt)
+
+@interface G9ContractRun : NSObject {
+ @public
+  G9SqliteCore *core;
+  NSString *transport;
+  NSString *dir;
+}
+@end
+
+@implementation G9ContractRun
+
+- (NSArray *)pragmas:(NSDictionary *)options {
+  NSMutableArray *out = [NSMutableArray array];
+  NSDictionary *p = options;
+  if (p == nil) {
+    p = [NSDictionary dictionaryWithObjectsAndKeys:@"wal", @"journalMode", [NSNumber numberWithInt:0], @"busyTimeoutMs", nil];
+  }
+  if ([p objectForKey:@"journalMode"] != nil) {
+    [out addObject:[NSString stringWithFormat:@"PRAGMA journal_mode=%@", [[p objectForKey:@"journalMode"] uppercaseString]]];
+  }
+  [out addObject:@"PRAGMA synchronous=FULL"];
+  if ([p objectForKey:@"busyTimeoutMs"] != nil) {
+    [out addObject:[NSString stringWithFormat:@"PRAGMA busy_timeout=%d", [[p objectForKey:@"busyTimeoutMs"] intValue]]];
+  }
+  return out;
+}
+
+- (NSString *)path:(NSString *)caseId kind:(NSString *)kind {
+  if ([kind isEqual:@"missing"]) return [dir stringByAppendingPathComponent:[caseId stringByAppendingString:@"-missing.db"]];
+  if ([kind isEqual:@"nested"]) return [[[dir stringByAppendingPathComponent:caseId] stringByAppendingPathComponent:@"nested/deeper"] stringByAppendingPathComponent:@"db.sqlite"];
+  return [dir stringByAppendingPathComponent:[caseId stringByAppendingString:@".db"]];
+}
+
+- (NSString *)check:(NSDictionary *)result expected:(NSDictionary *)expected index:(NSUInteger)k {
+  if ([expected objectForKey:@"changes"] != nil && [[result objectForKey:@"changes"] doubleValue] != [[expected objectForKey:@"changes"] doubleValue]) {
+    return [NSString stringWithFormat:@"statement %lu: changes %@, expected %@", (unsigned long)k, [result objectForKey:@"changes"], [expected objectForKey:@"changes"]];
+  }
+  if ([expected objectForKey:@"lastInsertRowId"] != nil && !G9Same([result objectForKey:@"lastInsertRowId"], [expected objectForKey:@"lastInsertRowId"])) {
+    return [NSString stringWithFormat:@"statement %lu: lastInsertRowId %@", (unsigned long)k, G9Describe([result objectForKey:@"lastInsertRowId"])];
+  }
+  if ([expected objectForKey:@"columns"] != nil && ![[result objectForKey:@"columns"] isEqual:[expected objectForKey:@"columns"]]) {
+    return [NSString stringWithFormat:@"statement %lu: columns %@", (unsigned long)k, [result objectForKey:@"columns"]];
+  }
+  NSArray *want = [expected objectForKey:@"rows"];
+  if (want != nil) {
+    NSArray *got = [result objectForKey:@"rows"];
+    if ([got count] != [want count]) return [NSString stringWithFormat:@"statement %lu: %lu rows, expected %lu", (unsigned long)k, (unsigned long)[got count], (unsigned long)[want count]];
+    for (NSUInteger r = 0; r < [want count]; r++) {
+      NSArray *w = [want objectAtIndex:r], *g = [got objectAtIndex:r];
+      if ([g count] != [w count]) return [NSString stringWithFormat:@"statement %lu row %lu: %lu values", (unsigned long)k, (unsigned long)r, (unsigned long)[g count]];
+      for (NSUInteger c = 0; c < [w count]; c++) {
+        if (!G9Same([g objectAtIndex:c], [w objectAtIndex:c])) {
+          return [NSString stringWithFormat:@"statement %lu row %lu col %lu: %@", (unsigned long)k, (unsigned long)r, (unsigned long)c, G9Describe([g objectAtIndex:c])];
+        }
+      }
+    }
+  }
+  return nil;
+}
+
+/** nil on success, otherwise the failure. */
+- (NSString *)runCase:(NSDictionary *)testCase {
+  NSString *caseId = [testCase objectForKey:@"id"];
+  NSMutableDictionary *sessions = [NSMutableDictionary dictionary];
+  NSMutableDictionary *txs = [NSMutableDictionary dictionary];
+  NSString *main = [self path:caseId kind:@"main"];
+  NSString *failure = nil;
+  NSDictionary *error = nil;
+  NSString *a = [core open:[NSDictionary dictionaryWithObjectsAndKeys:main, @"path", [NSNumber numberWithBool:YES], @"create",
+                                                                      [self pragmas:nil], @"pragmas", nil]
+                     error:&error];
+  if (a == nil) return [NSString stringWithFormat:@"%@ setup: %@", caseId, error];
+  [sessions setObject:a forKey:@"a"];
+  NSArray *steps = [testCase objectForKey:@"steps"];
+  for (NSUInteger i = 0; i < [steps count] && failure == nil; i++) {
+    NSDictionary *step = [steps objectAtIndex:i];
+    NSDictionary *options = [step objectForKey:@"options"];
+    NSString *sessionName = [step objectForKey:@"session"] != nil ? [step objectForKey:@"session"] : @"a";
+    NSArray *outcome = nil;
+    error = nil;
+    BOOL ok = YES;
+    if ([step objectForKey:@"run"] != nil) {
+      NSString *token = [sessions objectForKey:sessionName] != nil ? [sessions objectForKey:sessionName] : @"closed";
+      NSMutableArray *statements = [NSMutableArray array];
+      for (NSDictionary *s in [step objectForKey:@"run"]) {
+        NSMutableArray *params = [NSMutableArray array];
+        for (id p in [s objectForKey:@"params"]) [params addObject:G9ToBridge(p)];
+        [statements addObject:[NSDictionary dictionaryWithObjectsAndKeys:[s objectForKey:@"sql"], @"sql", params, @"params", nil]];
+      }
+      NSMutableDictionary *run = [NSMutableDictionary dictionaryWithObject:transport forKey:@"transport"];
+      if ([step objectForKey:@"tx"] != nil) {
+        id tx = [txs objectForKey:[step objectForKey:@"tx"]];
+        [run setObject:tx != nil ? tx : [@"finished-" stringByAppendingString:[step objectForKey:@"tx"]] forKey:@"tx"];
+      }
+      if ([[options objectForKey:@"atomic"] boolValue]) [run setObject:[NSNumber numberWithBool:YES] forKey:@"atomic"];
+      if ([options objectForKey:@"maxRows"] != nil) [run setObject:[options objectForKey:@"maxRows"] forKey:@"maxRows"];
+      if ([[options objectForKey:@"abortedSignal"] boolValue]) {
+        // The JS adapter rejects an aborted batch before it reaches the module.
+        error = G9SqliteErrorMake(@"cancelled", @"Cancelled before the batch started.");
+        ok = NO;
+      } else {
+        NSArray *results = [core run:token statements:statements options:run error:&error];
+        ok = results != nil;
+        if (ok) outcome = G9Decode([G9SqliteTransport encode:results transport:transport]);
+      }
+    } else if ([step objectForKey:@"open"] != nil) {
+      NSString *target = [[step objectForKey:@"missingPath"] boolValue] ? [self path:caseId kind:@"missing"]
+                         : [[step objectForKey:@"nestedPath"] boolValue] ? [self path:caseId kind:@"nested"] : main;
+      NSMutableDictionary *open = [NSMutableDictionary dictionaryWithObject:target forKey:@"path"];
+      BOOL create = [options objectForKey:@"create"] != nil ? [[options objectForKey:@"create"] boolValue]
+                                                            : ![[step objectForKey:@"missingPath"] boolValue];
+      [open setObject:[NSNumber numberWithBool:create] forKey:@"create"];
+      if ([[options objectForKey:@"readOnly"] boolValue]) [open setObject:[NSNumber numberWithBool:YES] forKey:@"readOnly"];
+      NSDictionary *pragmas = [options objectForKey:@"pragmas"];
+      [open setObject:[self pragmas:pragmas != nil ? pragmas : [NSDictionary dictionary]] forKey:@"pragmas"];
+      NSString *token = [core open:open error:&error];
+      ok = token != nil;
+      if (ok) [sessions setObject:token forKey:[step objectForKey:@"open"]];
+    } else if ([step objectForKey:@"begin"] != nil) {
+      NSString *token = [sessions objectForKey:sessionName] != nil ? [sessions objectForKey:sessionName] : @"closed";
+      NSString *tx = [core begin:token mode:[step objectForKey:@"mode"] != nil ? [step objectForKey:@"mode"] : @"deferred" error:&error];
+      ok = tx != nil;
+      if (ok) [txs setObject:tx forKey:[step objectForKey:@"begin"]];
+    } else if ([step objectForKey:@"commit"] != nil) {
+      NSString *tx = [txs objectForKey:[step objectForKey:@"commit"]];
+      ok = tx != nil && [core commit:tx error:&error];
+      if (tx == nil) error = G9SqliteErrorMake(@"misuse", @"unknown tx");
+      if (ok) [txs removeObjectForKey:[step objectForKey:@"commit"]];
+    } else if ([step objectForKey:@"rollback"] != nil) {
+      NSString *tx = [txs objectForKey:[step objectForKey:@"rollback"]];
+      ok = tx != nil && [core rollback:tx error:&error];
+      if (tx == nil) error = G9SqliteErrorMake(@"misuse", @"unknown tx");
+      if (ok) [txs removeObjectForKey:[step objectForKey:@"rollback"]];
+    } else if ([step objectForKey:@"close"] != nil) {
+      NSString *token = [sessions objectForKey:[step objectForKey:@"close"]];
+      [sessions removeObjectForKey:[step objectForKey:@"close"]];
+      ok = [core close:token != nil ? token : @"closed" error:&error];
+    }
+    NSString *expectError = [step objectForKey:@"expectError"];
+    if (!ok) {
+      if (expectError == nil) {
+        failure = [NSString stringWithFormat:@"%@ step %lu: unexpected error %@", caseId, (unsigned long)i, error];
+      } else if (![[error objectForKey:@"code"] isEqual:expectError]) {
+        failure = [NSString stringWithFormat:@"%@ step %lu: error code %@, expected %@", caseId, (unsigned long)i, [error objectForKey:@"code"], expectError];
+      } else if ([step objectForKey:@"expectCompletedStatements"] != nil &&
+                 ![[error objectForKey:@"completedStatements"] isEqual:[step objectForKey:@"expectCompletedStatements"]]) {
+        failure = [NSString stringWithFormat:@"%@ step %lu: completedStatements %@", caseId, (unsigned long)i, [error objectForKey:@"completedStatements"]];
+      }
+      continue;
+    }
+    if (expectError != nil) {
+      failure = [NSString stringWithFormat:@"%@ step %lu: expected error %@, got success", caseId, (unsigned long)i, expectError];
+      continue;
+    }
+    NSArray *expect = [step objectForKey:@"expect"];
+    if (expect != nil && outcome != nil) {
+      if ([outcome count] != [expect count]) {
+        failure = [NSString stringWithFormat:@"%@ step %lu: %lu results", caseId, (unsigned long)i, (unsigned long)[outcome count]];
+        continue;
+      }
+      for (NSUInteger k = 0; k < [expect count] && failure == nil; k++) {
+        NSString *problem = [self check:[outcome objectAtIndex:k] expected:[expect objectAtIndex:k] index:k];
+        if (problem != nil) failure = [NSString stringWithFormat:@"%@ step %lu: %@", caseId, (unsigned long)i, problem];
+      }
+    }
+  }
+  for (NSString *tx in [txs allValues]) [core rollback:tx error:NULL];
+  for (NSString *token in [sessions allValues]) [core close:token error:NULL];
+  return failure;
+}
+
+@end
+
+#pragma mark - Interrupt helper
+
+@interface G9InterruptProbe : NSObject {
+ @public
+  G9SqliteCore *core;
+  NSString *session;
+  NSDictionary *error;
+  volatile BOOL done;
+}
+- (void)runLongQuery:(id)unused;
+@end
+
+@implementation G9InterruptProbe
+- (void)runLongQuery:(id)unused {
+  @autoreleasepool {
+  NSDictionary *e = nil;
+  NSString *sql = @"WITH RECURSIVE c(x) AS (SELECT 1 UNION ALL SELECT x + 1 FROM c LIMIT 2000000000) SELECT count(*) FROM c";
+  NSArray *results = [core run:session
+                    statements:[NSArray arrayWithObject:[NSDictionary dictionaryWithObjectsAndKeys:sql, @"sql", [NSArray array], @"params", nil]]
+                       options:[NSDictionary dictionary]
+                         error:&e];
+  error = results == nil ? [e copy] : nil;
+  }
+  done = YES;
+}
+@end
+
+#pragma mark - Suite
+
+@implementation G9NativeTestSuite
+
++ (NSArray *)contractWithRepo:(NSString *)repo transport:(NSString *)transport passed:(NSInteger *)passed {
+  NSData *json = [NSData dataWithContentsOfFile:[repo stringByAppendingPathComponent:@"packages/sqlite/contract/cases.json"]];
+  NSDictionary *cases = json != nil ? [NSJSONSerialization JSONObjectWithData:json options:0 error:NULL] : nil;
+  if (cases == nil) return [NSArray arrayWithObject:@"cases.json not found or not JSON"];
+  G9ContractRun *run = [[G9ContractRun alloc] init];
+  run->core = [[G9SqliteCore alloc] init];
+  run->transport = transport;
+  run->dir = [NSTemporaryDirectory() stringByAppendingPathComponent:[NSString stringWithFormat:@"g9-ios-contract-%@-%d", transport, (int)getpid()]];
+  [[NSFileManager defaultManager] removeItemAtPath:run->dir error:NULL];
+  [[NSFileManager defaultManager] createDirectoryAtPath:run->dir withIntermediateDirectories:YES attributes:nil error:NULL];
+  NSMutableArray *failures = [NSMutableArray array];
+  NSArray *list = [cases objectForKey:@"cases"];
+  for (NSDictionary *testCase in list) {
+    NSString *failure = [run runCase:testCase];
+    if (failure != nil) [failures addObject:failure];
+  }
+  if (passed != NULL) *passed = (NSInteger)[list count] - (NSInteger)[failures count];
+  if ([list count] < 27) [failures addObject:[NSString stringWithFormat:@"only %lu cases", (unsigned long)[list count]]];
+  [[NSFileManager defaultManager] removeItemAtPath:run->dir error:NULL];
+  return failures;
+}
+
+/** Golden JSON → bridge values: `{ $bytes }` → NSData, `{ $number }` → NSNumber. */
+static id G9Revive(id value) {
+  if ([value isKindOfClass:[NSArray class]]) {
+    NSMutableArray *out = [NSMutableArray array];
+    for (id v in value) [out addObject:G9Revive(v)];
+    return out;
+  }
+  if ([value isKindOfClass:[NSDictionary class]]) {
+    if ([value objectForKey:@"$bytes"] != nil) return G9Hex([value objectForKey:@"$bytes"]);
+    NSString *number = [value objectForKey:@"$number"];
+    if (number != nil) {
+      // NSString parses neither "Infinity" nor "-Infinity" (Kotlin's Double.toString spelling).
+      if ([number isEqualToString:@"Infinity"]) return [NSNumber numberWithDouble:INFINITY];
+      if ([number isEqualToString:@"-Infinity"]) return [NSNumber numberWithDouble:-INFINITY];
+      return [NSNumber numberWithDouble:[number doubleValue]];
+    }
+    NSMutableDictionary *out = [NSMutableDictionary dictionary];
+    for (NSString *k in value) [out setObject:G9Revive([value objectForKey:k]) forKey:k];
+    return out;
+  }
+  return value;
+}
+
+/** Deep equality where numbers compare as doubles (incl. the sign of zero) and NSData by bytes. */
+static BOOL G9DeepEqual(id a, id b) {
+  if ([a isKindOfClass:[NSNumber class]] && [b isKindOfClass:[NSNumber class]]) {
+    double x = [a doubleValue], y = [b doubleValue];
+    return x == y && signbit(x) == signbit(y);
+  }
+  if ([a isKindOfClass:[NSArray class]] && [b isKindOfClass:[NSArray class]]) {
+    if ([a count] != [b count]) return NO;
+    for (NSUInteger i = 0; i < [a count]; i++) if (!G9DeepEqual([a objectAtIndex:i], [b objectAtIndex:i])) return NO;
+    return YES;
+  }
+  if ([a isKindOfClass:[NSDictionary class]] && [b isKindOfClass:[NSDictionary class]]) {
+    if ([a count] != [b count]) return NO;
+    for (NSString *k in a) if (!G9DeepEqual([a objectForKey:k], [b objectForKey:k])) return NO;
+    return YES;
+  }
+  return [a isEqual:b];
+}
+
+/** Rebuilds core results from the golden's `expected` (rows form): int64 tags and integral numbers become integers. */
+static NSArray *G9CoreResultsFromExpected(NSArray *expected) {
+  NSMutableArray *out = [NSMutableArray array];
+  for (NSDictionary *r in expected) {
+    NSMutableArray *rows = [NSMutableArray array];
+    for (NSArray *row in [r objectForKey:@"rows"]) {
+      NSMutableArray *cells = [NSMutableArray array];
+      for (id cell in row) {
+        if ([cell isKindOfClass:[NSDictionary class]]) {
+          [cells addObject:[NSNumber numberWithLongLong:[[cell objectForKey:@"int64"] longLongValue]]];
+        } else {
+          [cells addObject:cell];
+        }
+      }
+      [rows addObject:cells];
+    }
+    id last = [r objectForKey:@"lastInsertRowId"];
+    long long lastId = [last isKindOfClass:[NSDictionary class]] ? [[last objectForKey:@"int64"] longLongValue] : [last longLongValue];
+    [out addObject:[NSDictionary dictionaryWithObjectsAndKeys:[r objectForKey:@"columns"], @"columns", rows, @"rows",
+                                                             [NSNumber numberWithLongLong:[[r objectForKey:@"changes"] longLongValue]], @"changes",
+                                                             [NSNumber numberWithLongLong:lastId], @"lastInsertRowId", nil]];
+  }
+  return out;
+}
+
++ (NSArray *)goldenWithRepo:(NSString *)repo {
+  NSData *json = [NSData dataWithContentsOfFile:[repo stringByAppendingPathComponent:@"packages/native/contract/transport-golden.json"]];
+  NSDictionary *golden = json != nil ? G9Revive([NSJSONSerialization JSONObjectWithData:json options:0 error:NULL]) : nil;
+  if (golden == nil) return [NSArray arrayWithObject:@"transport-golden.json not found"];
+  NSMutableArray *failures = [NSMutableArray array];
+  NSArray *results = G9CoreResultsFromExpected([golden objectForKey:@"expected"]);
+  for (NSString *transport in [NSArray arrayWithObjects:@"columnar", @"rows", nil]) {
+    NSDictionary *mine = [G9SqliteTransport encode:results transport:transport];
+    if (!G9DeepEqual(mine, [golden objectForKey:transport])) {
+      [failures addObject:[NSString stringWithFormat:@"%@ frame differs from the golden:\n%@", transport, mine]];
+    }
+  }
+  return failures;
+}
+
++ (NSArray *)interrupt {
+  NSMutableArray *failures = [NSMutableArray array];
+  G9InterruptProbe *probe = [[G9InterruptProbe alloc] init];
+  probe->core = [[G9SqliteCore alloc] init];
+  probe->session = [probe->core open:[NSDictionary dictionaryWithObject:@":memory:" forKey:@"path"] error:NULL];
+  [NSThread detachNewThreadSelector:@selector(runLongQuery:) toTarget:probe withObject:nil];
+  usleep(200000);
+  [probe->core interrupt:probe->session];
+  for (int i = 0; i < 200 && !probe->done; i++) usleep(50000);
+  if (!probe->done) [failures addObject:@"the interrupted statement did not stop within 10 s"];
+  else if (![[probe->error objectForKey:@"code"] isEqual:@"interrupted"]) {
+    [failures addObject:[NSString stringWithFormat:@"interrupt gave %@", probe->error]];
+  }
+  // The session stays usable after an interrupt.
+  NSArray *after = [probe->core run:probe->session
+                         statements:[NSArray arrayWithObject:[NSDictionary dictionaryWithObjectsAndKeys:@"SELECT 1", @"sql", nil]]
+                            options:[NSDictionary dictionary]
+                              error:NULL];
+  if ([after count] != 1) [failures addObject:@"the session failed after an interrupt"];
+  [probe->core interrupt:@"unknown"];
+  [probe->core closeAll];
+  return failures;
+}
+
++ (NSArray *)coreEdges {
+  NSMutableArray *f = [NSMutableArray array];
+  G9SqliteCore *core = [[G9SqliteCore alloc] init];
+  NSDictionary *e = nil;
+  NSDictionary *caps = [core capabilitiesWithError:&e];
+  if (![[caps objectForKey:@"interrupt"] boolValue] || ![[caps objectForKey:@"returning"] boolValue]) [f addObject:@"capabilities"];
+  if ([core open:[NSDictionary dictionary] error:&e] != nil || ![[e objectForKey:@"code"] isEqual:@"misuse"]) [f addObject:@"open without path"];
+  NSString *s = [core open:[NSDictionary dictionaryWithObject:@"" forKey:@"path"] error:NULL];
+  NSDictionary *bad = [NSDictionary dictionaryWithObjectsAndKeys:@"SELECT ?", @"sql", [NSArray arrayWithObject:[NSNumber numberWithDouble:NAN]], @"params", nil];
+  e = nil;
+  if ([core run:s statements:[NSArray arrayWithObject:bad] options:[NSDictionary dictionary] error:&e] != nil ||
+      ![[e objectForKey:@"code"] isEqual:@"misuse"] || ![[e objectForKey:@"sql"] isEqual:@"SELECT ?"]) {
+    [f addObject:[NSString stringWithFormat:@"NaN: %@", e]];
+  }
+  NSDictionary *badInt = [NSDictionary dictionaryWithObjectsAndKeys:@"SELECT ?", @"sql",
+                                                                    [NSArray arrayWithObject:[NSDictionary dictionaryWithObject:@"12x" forKey:@"int64"]], @"params", nil];
+  if ([core run:s statements:[NSArray arrayWithObject:badInt] options:[NSDictionary dictionary] error:&e] != nil) [f addObject:@"bad int64"];
+  NSDictionary *other = [NSDictionary dictionaryWithObjectsAndKeys:@"SELECT ?", @"sql", [NSArray arrayWithObject:[NSArray array]], @"params", nil];
+  if ([core run:s statements:[NSArray arrayWithObject:other] options:[NSDictionary dictionary] error:&e] != nil) [f addObject:@"array param"];
+  if ([core run:s statements:[NSArray arrayWithObject:@"SELECT 1"] options:[NSDictionary dictionary] error:&e] != nil) [f addObject:@"statement shape"];
+  // Statement cache eviction (64) keeps working.
+  for (int i = 0; i < 70; i++) {
+    NSString *sql = [NSString stringWithFormat:@"SELECT %d", i];
+    NSArray *r = [core run:s statements:[NSArray arrayWithObject:[NSDictionary dictionaryWithObject:sql forKey:@"sql"]] options:[NSDictionary dictionary] error:NULL];
+    if ([[[[[r objectAtIndex:0] objectForKey:@"rows"] objectAtIndex:0] objectAtIndex:0] intValue] != i) [f addObject:sql];
+  }
+  NSString *tx = [core begin:s mode:@"immediate" error:NULL];
+  if (![[core sessionOfTx:tx] isEqual:s]) [f addObject:@"sessionOfTx"];
+  if ([core begin:s mode:@"deferred" error:&e] != nil) [f addObject:@"nested begin"];
+  if ([core sessionOfTx:(id)[NSNull null]] != nil) [f addObject:@"sessionOfTx type"];
+  [core close:s error:NULL];
+  if ([core commit:tx error:&e] || ![[e objectForKey:@"code"] isEqual:@"misuse"]) [f addObject:@"commit after close"];
+  if ([core close:(id)[NSNull null] error:&e]) [f addObject:@"close type"];
+  if (![G9SqliteErrorCodeFor(2067) isEqual:@"constraint"] || ![G9SqliteErrorCodeFor(26) isEqual:@"corrupt"] ||
+      ![G9SqliteErrorCodeFor(13) isEqual:@"full"] || ![G9SqliteErrorCodeFor(21) isEqual:@"misuse"] ||
+      ![G9SqliteErrorCodeFor(262) isEqual:@"locked"]) {
+    [f addObject:@"error codes"];
+  }
+  return f;
+}
+
++ (NSArray *)preferences {
+  NSMutableArray *f = [NSMutableArray array];
+  G9PreferencesCore *prefs = [[G9PreferencesCore alloc] initWithBackend:[[G9MemoryPreferenceBackend alloc] init]];
+  NSDictionary *e = nil;
+  [prefs set:@"g9.a" kind:@"int" value:@"-2147483648" error:NULL];
+  [prefs set:@"g9.b" kind:@"string" value:@"سلام" error:NULL];
+  [prefs set:@"other" kind:@"string" value:@"x" error:NULL];
+  if (![[[prefs get:@"g9.a"] objectForKey:@"type"] isEqual:@"int"] || [[[prefs get:@"g9.a"] objectForKey:@"value"] doubleValue] != -2147483648.0) [f addObject:@"int"];
+  if (![[[prefs get:@"g9.b"] objectForKey:@"value"] isEqual:@"سلام"]) [f addObject:@"string"];
+  if ([prefs get:@"missing"] != (id)[NSNull null]) [f addObject:@"missing"];
+  if ([[prefs entries:@"g9."] count] != 2) [f addObject:@"entries"];
+  if ([prefs set:@"k" kind:@"int" value:@"2147483648" error:&e] || ![[e objectForKey:@"code"] isEqual:@"preference-value"]) [f addObject:@"int range"];
+  if ([prefs set:@"" kind:@"string" value:@"v" error:&e] || ![[e objectForKey:@"code"] isEqual:@"preference-key"]) [f addObject:@"empty key"];
+  if ([prefs set:@"k" kind:@"float" value:@"1" error:&e]) [f addObject:@"kind"];
+  [prefs set:@"g9.b" kind:@"string" value:nil error:NULL];
+  [prefs set:@"g9.a" kind:@"remove" value:nil error:NULL];
+  if ([[prefs entries:@"g9."] count] != 0) [f addObject:@"remove"];
+  return f;
+}
+
++ (NSArray *)hostPaths {
+  NSMutableArray *f = [NSMutableArray array];
+  NSFileManager *files = [NSFileManager defaultManager];
+  NSString *dir = [G9HostPaths appDataDirectory];
+  BOOL isDir = NO;
+  if (![dir isAbsolutePath] || ![[dir lastPathComponent] isEqual:@"Library"]) [f addObject:@"app data directory path"];
+  if (![files fileExistsAtPath:dir isDirectory:&isDir] || !isDir) [f addObject:@"app data directory exists"];
+  NSString *root = [NSTemporaryDirectory() stringByAppendingPathComponent:[[NSProcessInfo processInfo] globallyUniqueString]];
+  [files createDirectoryAtPath:[root stringByAppendingPathComponent:@"Onboarding"] withIntermediateDirectories:YES attributes:nil error:NULL];
+  [@"x" writeToFile:[root stringByAppendingPathComponent:@"Onboarding/2video.mp4"] atomically:YES encoding:NSUTF8StringEncoding error:NULL];
+  NSString *uri = [G9HostPaths assetURIForPath:@"/Onboarding/2video.mp4" resourceRoot:root];
+  if (![uri hasPrefix:@"file://"] || ![uri hasSuffix:@"/Onboarding/2video.mp4"]) [f addObject:[NSString stringWithFormat:@"asset uri %@", uri]];
+  if ([G9HostPaths assetURIForPath:@"Onboarding/missing.mp4" resourceRoot:root] != nil) [f addObject:@"missing asset"];
+  if ([G9HostPaths assetURIForPath:@"Onboarding" resourceRoot:root] != nil) [f addObject:@"directory as asset"];
+  if ([G9HostPaths assetURIForPath:@"../etc/passwd" resourceRoot:root] != nil) [f addObject:@"escaping path"];
+  if ([G9HostPaths assetURIForPath:@"/" resourceRoot:root] != nil) [f addObject:@"empty path"];
+  [files removeItemAtPath:root error:NULL];
+  return f;
+}
+
++ (NSArray *)videoCore {
+  NSMutableArray *f = [NSMutableArray array];
+  G9VideoLoopTracker *tracker = [[G9VideoLoopTracker alloc] init];
+  [tracker setNearEndSeconds:0.5];
+  if ([tracker progressPositionMs:1000 durationMs:10000] != nil) [f addObject:@"early"];
+  NSNumber *left = [tracker progressPositionMs:9600 durationMs:10000];
+  if (left == nil || fabs([left doubleValue] - 0.4) > 1e-9) [f addObject:@"near end"];
+  if ([tracker progressPositionMs:9800 durationMs:10000] != nil) [f addObject:@"once per loop"];
+  [tracker looped];
+  if ([tracker progressPositionMs:9900 durationMs:10000] == nil) [f addObject:@"re-armed after loop"];
+  [tracker looped];
+  if ([tracker progressPositionMs:9900 durationMs:0] != nil) [f addObject:@"unknown duration"];
+  [tracker setNearEndSeconds:NAN];
+  if ([tracker nearEndSeconds] != 0 || [tracker progressPositionMs:9900 durationMs:10000] != nil) [f addObject:@"off"];
+  if ([[G9VideoMath startPositionMsForSeconds:2.5 durationMs:10000] doubleValue] != 2500) [f addObject:@"start"];
+  if ([G9VideoMath startPositionMsForSeconds:10 durationMs:10000] != nil) [f addObject:@"start past end"];
+  if ([G9VideoMath startPositionMsForSeconds:0 durationMs:10000] != nil) [f addObject:@"no start"];
+  if ([[G9VideoMath startPositionMsForSeconds:3 durationMs:-1] doubleValue] != 3000) [f addObject:@"start, unknown duration"];
+  return f;
+}
+
+@end

package/ios/Tests/G9NativeTests.m

@@ -0,0 +1,52 @@
+// XCTest target (simulator, macOS runner): the portable suite in G9NativeTestSuite.m. Paths come from this file's
+// location in the repository (the simulator can read the host file system).
+#import <XCTest/XCTest.h>
+#import "G9NativeTestSuite.h"
+
+@interface G9NativeTests : XCTestCase
+@end
+
+@implementation G9NativeTests
+
+- (NSString *)repo {
+  // packages/native/ios/Tests/G9NativeTests.m → repository root.
+  NSString *file = [NSString stringWithUTF8String:__FILE__];
+  for (int i = 0; i < 5; i++) file = [file stringByDeletingLastPathComponent];
+  return file;
+}
+
+- (void)testContractColumnar {
+  NSInteger passed = 0;
+  XCTAssertEqualObjects([G9NativeTestSuite contractWithRepo:self.repo transport:@"columnar" passed:&passed], @[]);
+  XCTAssertGreaterThanOrEqual(passed, 27);
+}
+
+- (void)testContractRows {
+  XCTAssertEqualObjects([G9NativeTestSuite contractWithRepo:self.repo transport:@"rows" passed:NULL], @[]);
+}
+
+- (void)testTransportGolden {
+  XCTAssertEqualObjects([G9NativeTestSuite goldenWithRepo:self.repo], @[]);
+}
+
+- (void)testInterrupt {
+  XCTAssertEqualObjects([G9NativeTestSuite interrupt], @[]);
+}
+
+- (void)testCoreEdges {
+  XCTAssertEqualObjects([G9NativeTestSuite coreEdges], @[]);
+}
+
+- (void)testPreferences {
+  XCTAssertEqualObjects([G9NativeTestSuite preferences], @[]);
+}
+
+- (void)testHostPaths {
+  XCTAssertEqualObjects([G9NativeTestSuite hostPaths], @[]);
+}
+
+- (void)testVideoCore {
+  XCTAssertEqualObjects([G9NativeTestSuite videoCore], @[]);
+}
+
+@end

package/ios/g9lynx-native.podspec

@@ -0,0 +1,29 @@
+# @g9tm/lynxcontrols-native for iOS (plan/specs/06 §5, specs/08 §3). Linked into a host by Lynx Autolink (CocoaPods) from
+# node_modules. Lynx 4.0.3 is the latest stable release on CocoaPods trunk (4.1.x is nightly-only, 2026-10-03).
+# The pod name `g9lynx-native` is an internal identifier that did not follow the npm rename (D12); the version is the
+# package version, which always equals the pinned G9MAUIControls version (npm run check:versions).
+Pod::Spec.new do |s|
+  s.name = 'g9lynx-native'
+  s.version = '1.4.2'
+  s.summary = 'G9 SQLite and host native modules and the <g9-video> element for Lynx (sqlite3, NSUserDefaults, UIKit, AVFoundation).'
+  s.homepage = 'https://github.com/imankari/g9lynxcontrols'
+  s.license = { :type => 'MIT' }
+  s.author = 'G9LynxControls'
+  s.platform = :ios, '15.0'
+  s.source = { :path => '.' }
+  s.source_files = 'src/**/*.{h,m}'
+  # Keep src/'s folders in the public headers: G9HostModule.h imports "generated/G9HostModuleSpec.h", which a
+  # flattened Pods/Headers/Public cannot resolve from the host app (found building apps/ios-host, 2026-10-06).
+  s.header_mappings_dir = 'src'
+  s.libraries = 'sqlite3'
+  s.frameworks = 'UIKit', 'AVFoundation'
+  s.requires_arc = true
+  s.dependency 'Lynx', '4.0.3'
+
+  # XCTest on a simulator: the shared contract (packages/sqlite/contract/cases.json), the Kotlin-written transport
+  # golden, interrupt, core edges and preferences (Tests/G9NativeTestSuite.m, also run on Linux by test:ios-core).
+  s.test_spec 'Tests' do |t|
+    t.source_files = 'Tests/G9NativeTestSuite.{h,m}', 'Tests/G9NativeTests.m'
+    t.frameworks = 'XCTest'
+  end
+end

package/ios/src/G9HostModule.h

@@ -0,0 +1,14 @@
+#import <Foundation/Foundation.h>
+#import <Lynx/LynxModule.h>
+#import "generated/G9HostModuleSpec.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+// Lynx 4.0.3 (the iOS pods) has no @LynxNativeModuleRegister: hosts register the module on their LynxConfig
+// (`[config registerModule:G9HostModule.class]`, apps/ios-host/Sources/GalleryViewController.m).
+
+/** `NativeModules.G9HostModule` on iOS (plan/specs/06 §7): NSUserDefaults preferences, keyboard dismiss, haptics, insets. */
+@interface G9HostModule : NSObject <G9HostModuleSpec>
+@end
+
+NS_ASSUME_NONNULL_END