@trainstar/synchro-react-native 0.1.1 → 0.3.1

package/lib/module/SynchroClient.js

@@ -2,27 +2,505 @@
 
 import { Platform } from 'react-native';
 import NativeSynchro from "./NativeSynchro.js";
-import { mapNativeError } from "./errors.js";
+import { InvalidResponseError, SynchroError, mapNativeError, parseSyncFailure } from "./errors.js";
+import { assertValidSQLiteBindParams } from "./sqliteValues.js";
+import { SYNC_OPERATION_KINDS, SYNC_STATUS_TYPES } from "./types.js";
 let observerCounter = 0;
+let activeNativeOwner = null;
+const inspectionOwners = new WeakMap();
+const inspectionCapacities = new WeakMap();
+const inspectionRequireNewDatabases = new WeakMap();
 function nextObserverID() {
   return `obs_${++observerCounter}_${Date.now()}`;
 }
+function nullableRow(row) {
+  return row == null ? null : row;
+}
+const SYNC_EVENT_TYPES = ['state_changed', 'backoff', 'schema_applying', 'schema_applied', 'mutation_accepted', 'mutation_rejected', 'rebuild_requested', 'rebuild_completed', 'failure'];
+const SCHEMA_ACTIONS = ['none', 'replace', 'rebuild_local', 'unsupported'];
+const MUTATION_STATUSES = ['applied', 'conflict', 'rejected_terminal'];
+const MUTATION_REJECTION_CODES = ['version_conflict', 'row_already_exists', 'row_deleted', 'row_not_found', 'schema_incompatible', 'policy_rejected', 'validation_failed', 'table_not_synced'];
+const MUTATION_OPERATIONS = ['insert', 'upsert', 'update', 'delete'];
+const LOCAL_MUTATION_STATUSES = ['pending', 'sealed', 'superseded_before_send', 'cancelled_before_send', 'blocked_by_predecessor', 'server_rejected'];
+const TRANSPORT_OPERATION_CLASSES = ['connect', 'pull', 'push', 'checkpoint', 'schemas', 'rebuild', 'other'];
+const LEGAL_SYNC_STATUS_TRANSITIONS = {
+  uninitialized: ['local_ready', 'error', 'stopped'],
+  local_ready: ['connecting', 'error', 'stopped'],
+  connecting: ['schema_applying', 'ready', 'backoff', 'error', 'stopped'],
+  schema_applying: ['ready', 'rebuilding', 'error', 'stopped'],
+  ready: ['connecting', 'pushing', 'pulling', 'rebuilding', 'error', 'stopped'],
+  pushing: ['pushing', 'ready', 'pulling', 'connecting', 'backoff', 'error', 'stopped'],
+  pulling: ['pulling', 'ready', 'rebuilding', 'connecting', 'backoff', 'error', 'stopped'],
+  rebuilding: ['rebuilding', 'ready', 'connecting', 'backoff', 'error', 'stopped'],
+  backoff: ['connecting', 'pushing', 'pulling', 'rebuilding', 'error', 'stopped'],
+  error: ['local_ready', 'stopped'],
+  stopped: ['local_ready']
+};
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function requiredString(value, name) {
+  if (typeof value !== 'string') {
+    throw new InvalidResponseError(`Native bridge returned an invalid ${name}`);
+  }
+  return value;
+}
+function nullableString(value, name) {
+  if (value == null) {
+    return null;
+  }
+  return requiredString(value, name);
+}
+function requiredSafeInteger(value, name) {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
+    throw new InvalidResponseError(`Native bridge returned an invalid ${name}`);
+  }
+  return value;
+}
+function requiredNonnegativeSafeInteger(value, name) {
+  const integer = requiredSafeInteger(value, name);
+  if (integer < 0) {
+    throw new InvalidResponseError(`Native bridge returned an invalid ${name}`);
+  }
+  return integer;
+}
+function nullableSafeInteger(value, name) {
+  return value == null ? null : requiredSafeInteger(value, name);
+}
+function parseDate(value, name) {
+  const stringValue = nullableString(value, name);
+  if (stringValue === null) {
+    return null;
+  }
+  const date = new Date(stringValue);
+  if (Number.isNaN(date.getTime())) {
+    throw new InvalidResponseError(`Native bridge returned an invalid ${name}`);
+  }
+  return date;
+}
+function parseStatus(value) {
+  if (!isRecord(value) || typeof value.status !== 'string') {
+    throw new InvalidResponseError('Native bridge returned an invalid sync status');
+  }
+  if (!SYNC_STATUS_TYPES.includes(value.status)) {
+    return null;
+  }
+  const status = value.status;
+  const retryAt = parseDate(value.retryAt, 'retryAt');
+  const operationValue = nullableString(value.operation, 'status operation');
+  const operation = operationValue === null ? null : SYNC_OPERATION_KINDS.includes(operationValue) ? operationValue : (() => {
+    throw new InvalidResponseError('Native bridge returned an invalid status operation');
+  })();
+  const failure = value.failure == null ? null : parseSyncFailure(value.failure);
+  if (status === 'backoff') {
+    if (retryAt === null || operation === null || failure !== null) {
+      throw new InvalidResponseError('Native bridge returned invalid backoff status details');
+    }
+    return {
+      status,
+      retryAt,
+      operation,
+      failure: null
+    };
+  }
+  if (status === 'error') {
+    if (retryAt !== null || operation !== null || failure === null) {
+      throw new InvalidResponseError('Native bridge returned invalid error status details');
+    }
+    return {
+      status,
+      retryAt: null,
+      operation: null,
+      failure
+    };
+  }
+  if (retryAt !== null || operation !== null || failure !== null) {
+    throw new InvalidResponseError('Native bridge returned invalid state detail fields');
+  }
+  return {
+    status,
+    retryAt: null,
+    operation: null,
+    failure: null
+  };
+}
+function parseSchemaRef(value, name) {
+  if (!isRecord(value) || typeof value.version !== 'number' || !Number.isSafeInteger(value.version)) {
+    throw new InvalidResponseError(`Native bridge returned an invalid ${name}`);
+  }
+  return {
+    version: value.version,
+    hash: requiredString(value.hash, `${name} hash`)
+  };
+}
+function parseMutationStatus(value) {
+  if (!MUTATION_STATUSES.includes(value)) {
+    throw new InvalidResponseError('Native bridge returned an invalid mutation status');
+  }
+  return value;
+}
+function parseRejectionCode(value) {
+  if (value == null) {
+    return null;
+  }
+  if (!MUTATION_REJECTION_CODES.includes(value)) {
+    throw new InvalidResponseError('Native bridge returned an invalid mutation rejection code');
+  }
+  return value;
+}
+function parseSchemaAction(value) {
+  if (!SCHEMA_ACTIONS.includes(value)) {
+    throw new InvalidResponseError('Native bridge returned an invalid schema action');
+  }
+  return value;
+}
+function parseSyncEvent(value) {
+  if (typeof value.type !== 'string') {
+    throw new InvalidResponseError('Native bridge returned an invalid sync event');
+  }
+  if (!SYNC_EVENT_TYPES.includes(value.type)) {
+    return null;
+  }
+  switch (value.type) {
+    case 'state_changed':
+      {
+        if (typeof value.from !== 'string' || typeof value.to !== 'string') {
+          throw new InvalidResponseError('Native bridge returned an invalid lifecycle event');
+        }
+        if (!SYNC_STATUS_TYPES.includes(value.from) || !SYNC_STATUS_TYPES.includes(value.to)) {
+          return null;
+        }
+        const from = value.from;
+        const to = value.to;
+        if (!LEGAL_SYNC_STATUS_TRANSITIONS[from].includes(to)) {
+          throw new InvalidResponseError('Native bridge returned an invalid lifecycle event');
+        }
+        return {
+          type: 'state_changed',
+          from,
+          to
+        };
+      }
+    case 'backoff':
+      {
+        const attempt = value.attempt;
+        if (typeof attempt !== 'number' || !Number.isSafeInteger(attempt) || attempt < 0) {
+          throw new InvalidResponseError('Native bridge returned an invalid backoff attempt');
+        }
+        const retryAt = parseDate(value.retryAt, 'backoff retryAt');
+        if (retryAt === null) {
+          throw new InvalidResponseError('Native bridge returned a missing backoff retryAt');
+        }
+        return {
+          type: 'backoff',
+          operation: SYNC_OPERATION_KINDS.includes(value.operation) ? value.operation : (() => {
+            throw new InvalidResponseError('Native bridge returned an invalid backoff operation');
+          })(),
+          attempt,
+          retryAt
+        };
+      }
+    case 'schema_applying':
+    case 'schema_applied':
+      return {
+        type: value.type,
+        source: parseSchemaRef(value.source, 'schema source'),
+        target: parseSchemaRef(value.target, 'schema target'),
+        action: parseSchemaAction(value.action)
+      };
+    case 'mutation_accepted':
+    case 'mutation_rejected':
+      {
+        const mutationID = requiredString(value.mutationID, 'mutation ID');
+        return {
+          type: value.type,
+          mutationID,
+          tableID: requiredString(value.tableID, 'mutation table ID'),
+          status: parseMutationStatus(value.mutationStatus),
+          rejectionCode: parseRejectionCode(value.rejectionCode)
+        };
+      }
+    case 'rebuild_requested':
+    case 'rebuild_completed':
+      return {
+        type: value.type,
+        scopeID: requiredString(value.scopeID, 'rebuild scope ID'),
+        rebuildID: requiredString(value.rebuildID, 'rebuild ID')
+      };
+    case 'failure':
+      {
+        return {
+          type: 'failure',
+          failure: parseSyncFailure(value.failure)
+        };
+      }
+  }
+}
+function parseNativeDTO(json) {
+  try {
+    return JSON.parse(json);
+  } catch {
+    throw new InvalidResponseError('Native bridge returned malformed JSON');
+  }
+}
+function parseNativeArray(json, name) {
+  const value = parseNativeDTO(json);
+  if (!Array.isArray(value)) {
+    throw new InvalidResponseError(`Native bridge returned invalid ${name}`);
+  }
+  return value;
+}
+function parsePendingMutationInspection(value, index) {
+  const name = `pending mutation at index ${index}`;
+  if (!isRecord(value)) {
+    throw new InvalidResponseError(`Native bridge returned an invalid ${name}`);
+  }
+  if (!MUTATION_OPERATIONS.includes(value.operation)) {
+    throw new InvalidResponseError(`Native bridge returned an invalid ${name} operation`);
+  }
+  if (!LOCAL_MUTATION_STATUSES.includes(value.status)) {
+    throw new InvalidResponseError(`Native bridge returned an invalid ${name} status`);
+  }
+  if (!Array.isArray(value.authoredFields)) {
+    throw new InvalidResponseError(`Native bridge returned invalid ${name} fields`);
+  }
+  const authoredFields = value.authoredFields.map((field, fieldIndex) => {
+    if (!isRecord(field) || !Object.prototype.hasOwnProperty.call(field, 'value')) {
+      throw new InvalidResponseError(`Native bridge returned an invalid ${name} field at index ${fieldIndex}`);
+    }
+    return {
+      fieldID: requiredString(field.fieldID, `${name} field ID`),
+      logicalType: requiredString(field.logicalType, `${name} field logical type`),
+      value: field.value
+    };
+  });
+  return {
+    mutationID: requiredString(value.mutationID, `${name} ID`),
+    localOrder: requiredSafeInteger(value.localOrder, `${name} local order`),
+    tableID: requiredString(value.tableID, `${name} table ID`),
+    tableName: requiredString(value.tableName, `${name} table name`),
+    recordID: requiredString(value.recordID, `${name} record ID`),
+    primaryKeyFieldID: requiredString(value.primaryKeyFieldID, `${name} primary-key field ID`),
+    primaryKeyLogicalType: requiredString(value.primaryKeyLogicalType, `${name} primary-key logical type`),
+    operation: value.operation,
+    authoredSchema: parseSchemaRef(value.authoredSchema, `${name} authored schema`),
+    baseVersion: nullableString(value.baseVersion, `${name} base version`),
+    clientVersion: requiredString(value.clientVersion, `${name} client version`),
+    status: value.status,
+    sourceKind: requiredString(value.sourceKind, `${name} source kind`),
+    dependsOnMutationID: nullableString(value.dependsOnMutationID, `${name} predecessor mutation ID`),
+    normalizedMutationID: nullableString(value.normalizedMutationID, `${name} normalized mutation ID`),
+    sealedBatchID: nullableString(value.sealedBatchID, `${name} sealed batch ID`),
+    sealedOrdinal: nullableSafeInteger(value.sealedOrdinal, `${name} sealed ordinal`),
+    authoredFields
+  };
+}
+function parseRejectedMutationInspection(value, index) {
+  const name = `rejected mutation at index ${index}`;
+  if (!isRecord(value)) {
+    throw new InvalidResponseError(`Native bridge returned an invalid ${name}`);
+  }
+  const code = parseRejectionCode(value.code);
+  if (code === null) {
+    throw new InvalidResponseError(`Native bridge returned a missing ${name} code`);
+  }
+  return {
+    mutationID: requiredString(value.mutationID, `${name} ID`),
+    tableName: requiredString(value.tableName, `${name} table name`),
+    recordID: requiredString(value.recordID, `${name} record ID`),
+    status: parseMutationStatus(value.status),
+    code,
+    message: nullableString(value.message, `${name} message`),
+    serverRowJSON: nullableString(value.serverRowJSON, `${name} server row JSON`),
+    serverVersion: nullableString(value.serverVersion, `${name} server version`),
+    mutationJSON: requiredString(value.mutationJSON, `${name} mutation JSON`),
+    rejectionJSON: requiredString(value.rejectionJSON, `${name} rejection JSON`),
+    createdAt: requiredString(value.createdAt, `${name} creation time`),
+    updatedAt: requiredString(value.updatedAt, `${name} update time`)
+  };
+}
+function parseScopeStateInspection(value, index) {
+  const name = `scope state at index ${index}`;
+  if (!isRecord(value)) {
+    throw new InvalidResponseError(`Native bridge returned an invalid ${name}`);
+  }
+  return {
+    scopeID: requiredString(value.scope_id, `${name} ID`),
+    cursor: nullableString(value.cursor, `${name} cursor`),
+    checksum: nullableString(value.checksum, `${name} checksum`),
+    localChecksum: requiredString(value.local_checksum, `${name} local checksum`),
+    generation: requiredSafeInteger(value.generation, `${name} generation`)
+  };
+}
+function parseScopeRowInspection(value, index) {
+  const name = `scope row at index ${index}`;
+  if (!isRecord(value)) {
+    throw new InvalidResponseError(`Native bridge returned an invalid ${name}`);
+  }
+  return {
+    scopeID: requiredString(value.scope_id, `${name} scope ID`),
+    tableName: requiredString(value.table_name, `${name} table name`),
+    recordID: requiredString(value.record_id, `${name} record ID`),
+    checksum: requiredString(value.checksum, `${name} checksum`),
+    generation: requiredSafeInteger(value.generation, `${name} generation`)
+  };
+}
+function parseRebuildAttemptInspection(value, index) {
+  const name = `rebuild attempt at index ${index}`;
+  if (!isRecord(value)) {
+    throw new InvalidResponseError(`Native bridge returned an invalid ${name}`);
+  }
+  return {
+    scopeID: requiredString(value.scope_id, `${name} scope ID`),
+    rebuildID: requiredString(value.rebuild_id, `${name} rebuild ID`),
+    clientGeneration: requiredSafeInteger(value.client_generation, `${name} client generation`),
+    schemaVersion: requiredSafeInteger(value.schema_version, `${name} schema version`),
+    schemaHash: requiredString(value.schema_hash, `${name} schema hash`),
+    generation: requiredSafeInteger(value.generation, `${name} generation`),
+    cursor: nullableString(value.cursor, `${name} cursor`),
+    pageLimit: requiredSafeInteger(value.page_limit, `${name} page limit`)
+  };
+}
+export function parseClientStateInspection(value) {
+  if (!isRecord(value)) {
+    throw new InvalidResponseError('Native bridge returned invalid client state inspection');
+  }
+  const schema = value.schema == null ? null : parseSchemaRef(value.schema, 'client schema');
+  if (!Array.isArray(value.scope_states) || !Array.isArray(value.scope_rows) || !Array.isArray(value.rebuild_attempts)) {
+    throw new InvalidResponseError('Native bridge returned incomplete client state inspection');
+  }
+  return {
+    schema,
+    scopeStates: value.scope_states.map(parseScopeStateInspection),
+    scopeRows: value.scope_rows.map(parseScopeRowInspection),
+    rebuildAttempts: value.rebuild_attempts.map(parseRebuildAttemptInspection),
+    applicationRowCount: requiredNonnegativeSafeInteger(value.application_row_count, 'application row count'),
+    mutationLedgerCount: requiredNonnegativeSafeInteger(value.mutation_ledger_count, 'mutation ledger count'),
+    mutationOutcomeCount: requiredNonnegativeSafeInteger(value.mutation_outcome_count, 'mutation outcome count'),
+    sealedBatchCount: requiredNonnegativeSafeInteger(value.sealed_batch_count, 'sealed batch count'),
+    rejectedMutationCount: requiredNonnegativeSafeInteger(value.rejected_mutation_count, 'rejected mutation count'),
+    scopeStateCount: requiredNonnegativeSafeInteger(value.scope_state_count, 'scope state count'),
+    scopeRowCount: requiredNonnegativeSafeInteger(value.scope_row_count, 'scope row count'),
+    provenanceCount: requiredNonnegativeSafeInteger(value.provenance_count, 'provenance count'),
+    rowMetadataCount: requiredNonnegativeSafeInteger(value.row_metadata_count, 'row metadata count'),
+    rebuildAttemptCount: requiredNonnegativeSafeInteger(value.rebuild_attempt_count, 'rebuild attempt count'),
+    rebuildReceiptCount: requiredNonnegativeSafeInteger(value.rebuild_receipt_count, 'rebuild receipt count'),
+    provenanceMaintenanceWorkCursor: requiredNonnegativeInt64String(value.provenance_maintenance_work_cursor, 'provenance maintenance work cursor')
+  };
+}
+function requiredNonnegativeInt64String(value, name) {
+  const maximum = '9223372036854775807';
+  if (typeof value !== 'string' || !/^(0|[1-9][0-9]*)$/.test(value) || value.length > maximum.length || value.length === maximum.length && value > maximum) {
+    throw new InvalidResponseError(`Native bridge returned invalid ${name}`);
+  }
+  return value;
+}
+function optionalTransportFacts(value, name) {
+  if (value == null) {
+    return undefined;
+  }
+  if (!isRecord(value)) {
+    throw new InvalidResponseError(`Native bridge returned invalid ${name}`);
+  }
+  return value;
+}
+function optionalTransportRequestFacts(value, name) {
+  const facts = optionalTransportFacts(value, name);
+  const mutationCount = facts?.mutation_count;
+  if (facts !== undefined && Object.prototype.hasOwnProperty.call(facts, 'mutation_count') && (typeof mutationCount !== 'number' || !Number.isSafeInteger(mutationCount) || mutationCount < 0)) {
+    throw new InvalidResponseError(`Native bridge returned invalid ${name} mutation count`);
+  }
+  return facts;
+}
+function parseTransportObservation(value, index) {
+  const name = `transport observation at index ${index}`;
+  if (!isRecord(value) || !TRANSPORT_OPERATION_CLASSES.includes(value.operation_class)) {
+    throw new InvalidResponseError(`Native bridge returned an invalid ${name}`);
+  }
+  const cursorFingerprints = value.cursor_fingerprints;
+  if (cursorFingerprints !== undefined && (!Array.isArray(cursorFingerprints) || !cursorFingerprints.every(item => typeof item === 'string'))) {
+    throw new InvalidResponseError(`Native bridge returned invalid ${name} cursor fingerprints`);
+  }
+  const cursorFingerprintsComplete = value.cursor_fingerprints_complete;
+  if (cursorFingerprintsComplete !== undefined && typeof cursorFingerprintsComplete !== 'boolean') {
+    throw new InvalidResponseError(`Native bridge returned invalid ${name} cursor completeness`);
+  }
+  return {
+    sequence: requiredSafeInteger(value.sequence, `${name} sequence`),
+    operationClass: value.operation_class,
+    statusCode: requiredSafeInteger(value.status_code, `${name} status code`),
+    durationNanoseconds: requiredSafeInteger(value.duration_nanoseconds, `${name} duration`),
+    ...(cursorFingerprints === undefined ? {} : {
+      cursorFingerprints: [...cursorFingerprints]
+    }),
+    ...(cursorFingerprintsComplete === undefined ? {} : {
+      cursorFingerprintsComplete
+    }),
+    ...(value.request_facts == null ? {} : {
+      requestFacts: optionalTransportRequestFacts(value.request_facts, `${name} request facts`)
+    }),
+    ...(value.rebuild_response_facts == null ? {} : {
+      rebuildResponseFacts: optionalTransportFacts(value.rebuild_response_facts, `${name} rebuild response facts`)
+    }),
+    ...(value.pull_response_facts == null ? {} : {
+      pullResponseFacts: optionalTransportFacts(value.pull_response_facts, `${name} pull response facts`)
+    })
+  };
+}
+export function parseTransportObservationSnapshot(value) {
+  if (!isRecord(value) || !Array.isArray(value.observations) || typeof value.overflowed !== 'boolean') {
+    throw new InvalidResponseError('Native bridge returned invalid transport observations');
+  }
+  return {
+    observations: value.observations.map(parseTransportObservation),
+    overflowed: value.overflowed,
+    sequenceCheckpoint: requiredSafeInteger(value.sequence_checkpoint, 'transport sequence checkpoint')
+  };
+}
+function checkedParams(params) {
+  return assertValidSQLiteBindParams(params);
+}
 export class SynchroClient {
-  native = NativeSynchro;
+  nativeOwner = {};
   authSubscription = null;
   constructor(config) {
     this.config = config;
-
-    // Wire auth callback using Codegen EventEmitter pattern
-    this.authSubscription = this.native.onAuthRequest(event => {
+    inspectionOwners.set(this, this.nativeOwner);
+  }
+  get native() {
+    if (activeNativeOwner !== null && activeNativeOwner !== this.nativeOwner) {
+      throw new SynchroError('CLIENT_ALREADY_ACTIVE', 'Another SynchroClient owns the native runtime');
+    }
+    return NativeSynchro;
+  }
+  installAuthSubscription() {
+    this.authSubscription?.remove();
+    const owner = this.nativeOwner;
+    this.authSubscription = NativeSynchro.onAuthRequest(event => {
       this.config.authProvider().then(token => {
-        this.native.resolveAuthRequest(event.requestID, token);
+        if (activeNativeOwner === owner) {
+          NativeSynchro.resolveAuthRequest(event.requestID, token);
+        }
       }).catch(err => {
-        this.native.rejectAuthRequest(event.requestID, err instanceof Error ? err.message : String(err));
+        if (activeNativeOwner === owner) {
+          NativeSynchro.rejectAuthRequest(event.requestID, err instanceof Error ? err.message : String(err));
+        }
       });
     });
   }
+  releaseNativeOwnership() {
+    this.authSubscription?.remove();
+    this.authSubscription = null;
+    if (activeNativeOwner === this.nativeOwner) {
+      activeNativeOwner = null;
+    }
+  }
   async initialize() {
+    if (activeNativeOwner !== null && activeNativeOwner !== this.nativeOwner) {
+      throw new SynchroError('CLIENT_ALREADY_ACTIVE', 'Another SynchroClient owns the native runtime');
+    }
+    activeNativeOwner = this.nativeOwner;
+    this.installAuthSubscription();
     try {
       await this.native.initialize({
         dbPath: this.config.dbPath,
@@ -35,34 +513,42 @@ export class SynchroClient {
         maxRetryAttempts: this.config.maxRetryAttempts ?? 5,
         pullPageSize: this.config.pullPageSize ?? 100,
         pushBatchSize: this.config.pushBatchSize ?? 100,
-        snapshotPageSize: this.config.snapshotPageSize ?? 100
+        seedDatabasePath: this.config.seedDatabasePath,
+        transportObservationCapacity: inspectionCapacities.get(this) ?? 0,
+        requireNewDatabase: inspectionRequireNewDatabases.get(this) ?? false
       });
     } catch (error) {
+      this.releaseNativeOwnership();
       throw mapNativeError(error);
     }
   }
 
-  // -- Core SQL --
+  // Core SQL
 
   async query(sql, params) {
     try {
-      const json = await this.native.query(sql, JSON.stringify(params ?? []));
-      return JSON.parse(json);
+      return [...(await this.native.query(sql, checkedParams(params ?? [])))];
     } catch (error) {
       throw mapNativeError(error);
     }
   }
   async queryOne(sql, params) {
     try {
-      const json = await this.native.queryOne(sql, JSON.stringify(params ?? []));
-      return json ? JSON.parse(json) : null;
+      return nullableRow(await this.native.queryOne(sql, checkedParams(params ?? [])));
     } catch (error) {
       throw mapNativeError(error);
     }
   }
   async execute(sql, params) {
     try {
-      return await this.native.execute(sql, JSON.stringify(params ?? []));
+      return await this.native.execute(sql, checkedParams(params ?? []));
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+  async executeAuthoredWrite(tableName, operation, columnNames, sql, values) {
+    try {
+      return await this.native.executeAuthoredWrite(tableName, operation, columnNames, sql, checkedParams(values ?? []));
     } catch (error) {
       throw mapNativeError(error);
     }
@@ -71,15 +557,15 @@ export class SynchroClient {
     try {
       const payload = statements.map(s => ({
         sql: s.sql,
-        params: s.params ?? []
+        params: checkedParams(s.params ?? [])
       }));
-      return await this.native.executeBatch(JSON.stringify(payload));
+      return await this.native.executeBatch(payload);
     } catch (error) {
       throw mapNativeError(error);
     }
   }
 
-  // -- Transactions --
+  // Transactions
 
   async writeTransaction(callback) {
     let txID;
@@ -91,15 +577,13 @@ export class SynchroClient {
     try {
       const tx = {
         query: async (sql, params) => {
-          const json = await this.native.txQuery(txID, sql, JSON.stringify(params ?? []));
-          return JSON.parse(json);
+          return [...(await this.native.txQuery(txID, sql, checkedParams(params ?? [])))];
         },
         queryOne: async (sql, params) => {
-          const json = await this.native.txQueryOne(txID, sql, JSON.stringify(params ?? []));
-          return json ? JSON.parse(json) : null;
+          return nullableRow(await this.native.txQueryOne(txID, sql, checkedParams(params ?? [])));
         },
         execute: async (sql, params) => {
-          return await this.native.txExecute(txID, sql, JSON.stringify(params ?? []));
+          return await this.native.txExecute(txID, sql, checkedParams(params ?? []));
         }
       };
       const result = await callback(tx);
@@ -124,15 +608,10 @@ export class SynchroClient {
     try {
       const tx = {
         query: async (sql, params) => {
-          const json = await this.native.txQuery(txID, sql, JSON.stringify(params ?? []));
-          return JSON.parse(json);
+          return [...(await this.native.txQuery(txID, sql, checkedParams(params ?? [])))];
         },
         queryOne: async (sql, params) => {
-          const json = await this.native.txQueryOne(txID, sql, JSON.stringify(params ?? []));
-          return json ? JSON.parse(json) : null;
-        },
-        execute: async (sql, params) => {
-          return await this.native.txExecute(txID, sql, JSON.stringify(params ?? []));
+          return nullableRow(await this.native.txQueryOne(txID, sql, checkedParams(params ?? [])));
         }
       };
       const result = await callback(tx);
@@ -148,7 +627,7 @@ export class SynchroClient {
     }
   }
 
-  // -- Schema (local-only) --
+  // Schema, local-only
 
   async createTable(name, columns, options) {
     try {
@@ -172,50 +651,62 @@ export class SynchroClient {
     }
   }
 
-  // -- Observation --
+  // Observation
 
-  onChange(tables, callback) {
+  async onChange(tables, callback) {
     const observerID = nextObserverID();
     const subscription = this.native.onChange(event => {
       if (event.observerID === observerID) {
         callback();
       }
     });
-    this.native.addChangeObserver(observerID, tables);
-    return () => {
+    try {
+      await this.native.addChangeObserver(observerID, tables);
+    } catch (error) {
+      subscription.remove();
+      throw mapNativeError(error);
+    }
+    return async () => {
       subscription.remove();
-      this.native.removeObserver(observerID);
+      try {
+        await NativeSynchro.removeObserver(observerID);
+      } catch (error) {
+        throw mapNativeError(error);
+      }
     };
   }
-  watch(sql, params, tables, callback) {
+  async watch(sql, params, tables, callback) {
     const observerID = nextObserverID();
     const subscription = this.native.onQueryResult(event => {
       if (event.observerID === observerID) {
-        callback(JSON.parse(event.rowsJson));
+        callback([...event.rows]);
       }
     });
-    this.native.addQueryObserver(observerID, sql, JSON.stringify(params ?? []), tables);
-    return () => {
-      subscription.remove();
-      this.native.removeObserver(observerID);
-    };
-  }
-
-  // -- WAL --
-
-  async checkpoint(mode = 'passive') {
     try {
-      await this.native.checkpoint(mode);
+      await this.native.addQueryObserver(observerID, sql, checkedParams(params ?? []), tables);
     } catch (error) {
+      subscription.remove();
       throw mapNativeError(error);
     }
+    return async () => {
+      subscription.remove();
+      try {
+        await NativeSynchro.removeObserver(observerID);
+      } catch (error) {
+        throw mapNativeError(error);
+      }
+    };
   }
 
-  // -- Lifecycle --
+  // Lifecycle
 
   async close() {
+    if (activeNativeOwner !== null && activeNativeOwner !== this.nativeOwner) {
+      throw new SynchroError('CLIENT_ALREADY_ACTIVE', 'Another SynchroClient owns the native runtime');
+    }
     try {
-      await this.native.close();
+      await NativeSynchro.close();
+      this.releaseNativeOwnership();
     } catch (error) {
       throw mapNativeError(error);
     }
@@ -234,8 +725,48 @@ export class SynchroClient {
       throw mapNativeError(error);
     }
   }
+  async getSyncStatus() {
+    try {
+      const status = parseNativeDTO(await this.native.getSyncStatus());
+      const parsed = parseStatus(status);
+      if (parsed === null) {
+        throw new InvalidResponseError('Native bridge returned an unknown sync status');
+      }
+      return parsed;
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+  async inspectPendingMutations() {
+    try {
+      return parseNativeArray(await this.native.inspectPendingMutations(), 'pending mutation inspection').map(parsePendingMutationInspection);
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+  async inspectRetainedMutations() {
+    try {
+      return parseNativeArray(await this.native.inspectRetainedMutations(), 'retained mutation inspection').map(parsePendingMutationInspection);
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+  async inspectRejectedMutations() {
+    try {
+      return parseNativeArray(await this.native.inspectRejectedMutations(), 'rejected mutation inspection').map(parseRejectedMutationInspection);
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+  async clearRejectedMutations() {
+    try {
+      await this.native.clearRejectedMutations();
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
 
-  // -- Sync --
+  // Sync
 
   async start() {
     try {
@@ -251,6 +782,34 @@ export class SynchroClient {
       throw mapNativeError(error);
     }
   }
+  async enterBackground() {
+    try {
+      await this.native.enterBackground();
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+  async enterForeground() {
+    try {
+      await this.native.enterForeground();
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+  async retryAfterError() {
+    try {
+      await this.native.retryAfterError();
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+  async resetSchemaAndStart() {
+    try {
+      await this.native.resetSchemaAndStart();
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
   async syncNow() {
     try {
       await this.native.syncNow();
@@ -259,14 +818,19 @@ export class SynchroClient {
     }
   }
 
-  // -- Status & Events --
+  // Status and events
 
   onStatusChange(callback) {
     const subscription = this.native.onStatusChange(event => {
-      callback({
-        status: event.status,
-        retryAt: event.retryAt ? new Date(event.retryAt) : null
-      });
+      const status = parseStatus(event);
+      if (status !== null) callback(status);
+    });
+    return () => subscription.remove();
+  }
+  onSyncEvent(callback) {
+    const subscription = this.native.onSyncEvent(event => {
+      const parsed = parseSyncEvent(event);
+      if (parsed !== null) callback(parsed);
     });
     return () => subscription.remove();
   }
@@ -281,15 +845,23 @@ export class SynchroClient {
     });
     return () => subscription.remove();
   }
-  onSnapshotRequired(handler) {
-    const subscription = this.native.onSnapshotRequired(event => {
-      handler().then(approved => {
-        this.native.resolveSnapshotRequest(event.requestID, approved);
-      }).catch(() => {
-        this.native.resolveSnapshotRequest(event.requestID, false);
-      });
-    });
-    return () => subscription.remove();
+}
+export function configureInspection(client, transportObservationCapacity, requireNewDatabase) {
+  const owner = inspectionOwners.get(client);
+  if (owner !== undefined && activeNativeOwner === owner && transportObservationCapacity === 0 && !requireNewDatabase) {
+    return;
+  }
+  if (owner === undefined || activeNativeOwner === owner || typeof requireNewDatabase !== 'boolean' || !Number.isSafeInteger(transportObservationCapacity) || transportObservationCapacity < 0 || transportObservationCapacity > 512) {
+    throw new InvalidResponseError('Inspection configuration is invalid');
+  }
+  inspectionCapacities.set(client, transportObservationCapacity);
+  inspectionRequireNewDatabases.set(client, requireNewDatabase);
+}
+export function nativeForInspection(client) {
+  const owner = inspectionOwners.get(client);
+  if (owner === undefined || activeNativeOwner !== owner) {
+    throw new SynchroError('NOT_CONNECTED', 'SynchroClient is not initialized');
   }
+  return NativeSynchro;
 }
 //# sourceMappingURL=SynchroClient.js.map