@powersync/service-sync-rules 0.42.0 → 0.44.0

package/README.md

@@ -1,19 +1,56 @@
-# powersync-sync-rules
+# @powersync/service-sync-rules
 
-A library containing logic for PowerSync sync config.
+A library containing the parsing, compilation and evaluation logic for the PowerSync sync config.
 
 This is not intended to be used directly by users of PowerSync. If you are interested in the internals, read on.
 
 # Overview
 
-A core design constraint is that the sync config defines two operations:
+The sync config is the YAML document that defines which data each client receives. It supports two engines:
 
-1. Given a data row, compute a list of buckets that it belongs to.
-2. Given an authenticated user, return a list of buckets for the user.
+- **Sync Streams** (`streams:`): the current engine. Queries are compiled by `src/compiler/` into a sync plan and evaluated by `src/sync_plan/`. Requires `config: edition: 3`.
+- **Legacy Sync Rules** (`bucket_definitions:`): deprecated. Implemented in `src/legacy/` and kept only so that existing deployments keep working. Do not add features there. See [Legacy Sync Rules](#legacy-sync-rules-deprecated).
 
-This implementation of sync config uses SQL queries to declaratively define those operations using familiar SQL operations.
+Both engines define the same two operations:
 
-We define (1) using data queries, and (2) using parameter queries.
+1. Given a data row, compute the list of buckets it belongs to.
+2. Given an authenticated request, return the list of buckets to sync.
+
+None of the SQL is executed against a database. It is used to pre-process replicated rows into a format for efficient sync.
+
+`SqlSyncRules.fromYaml()` in `src/SqlSyncRules.ts` parses either engine into a `SyncConfig`. The service hydrates it with persisted state into a `HydratedSyncConfig` (`src/HydratedSyncConfig.ts`), which is what replication and sync use at runtime.
+
+# Sync Streams
+
+Example:
+
+```yaml
+config:
+  edition: 3
+
+streams:
+  lists:
+    auto_subscribe: true
+    query: SELECT * FROM lists WHERE owner_id = auth.user_id()
+  todos:
+    query: SELECT * FROM todos WHERE list_id = subscription.parameter('list_id')
+```
+
+A stream is one or more SQL queries over source tables. Streams with `auto_subscribe: true` sync when the client connects. Other streams sync when the client subscribes to them, optionally with parameters read through `subscription.parameter()`. Request-level values come from `auth.*` functions (JWT claims) and `connection.parameters()`.
+
+Compilation and evaluation:
+
+1. `SyncStreamsCompiler` (`src/compiler/compiler.ts`) parses each query and builds an intermediate representation. Compilation is schema-independent; the source schema, when available, is only used for validation warnings and output schema inference.
+2. `toSyncPlan()` produces a `SyncPlan` (`src/sync_plan/plan.ts`) describing bucket data sources, parameter lookups and queriers. The plan is serialized and stored alongside the deployed config.
+3. `PrecompiledSyncConfig` (`src/sync_plan/evaluator/`) evaluates the plan at runtime, using either the JavaScript or the SQLite expression engine (`src/sync_plan/engine/`).
+
+The grammar is in `grammar/sync-streams-compiler.ebnf`. User documentation: https://docs.powersync.com/sync/streams/overview.
+
+# Legacy Sync Rules (deprecated)
+
+Sync Rules are deprecated in favour of Sync Streams. The sections below document the legacy implementation in `src/legacy/`, which is preserved for backwards compatibility only.
+
+Legacy Sync Rules define the two operations above with explicit queries: parameter queries return the buckets for a request, and data queries assign rows to buckets.
 
 Example:
 
@@ -30,8 +67,6 @@ bucket_definitions:
 
 For the above example, a document with `org_id: 'org1'` will belong to a single bucket `by_org["org1"]`. Similarly, a user with `org_id: 'org1'` will sync the bucket `by_org["org1"]`.
 
-An important aspect is that none of these SQL queries are actually executed against any SQL database. Instead, it is used to pre-process data before storing the data in a format for efficient sync operations.
-
 When data is replicated from the source database to PowerSync, we do two things for each row:
 
 1. Evaluate data queries on the row: `syncRules.evaluateRow(row)`.
@@ -39,9 +74,9 @@ When data is replicated from the source database to PowerSync, we do two things
 
 Data queries also have the option to transform the row instead of just using `select *`. We store the transformed data for each of the buckets it belongs to.
 
-# Query Structure
+## Query Structure
 
-## Data queries
+### Data queries
 
 A data query is turned into a function `(row) => Array<{bucket, data}>`. The main implementation is in the `SqlDataQuery` class.
 
@@ -67,14 +102,14 @@ bucket.param IN mytable.some_array -- ParameterMatchClause
 (mytable.column1 = bucket.param) OR (mytable.column2 = bucket.param) -- ParameterMatchClause
 ```
 
-## Parameter Queries
+### Parameter Queries
 
 There are two types of parameter queries:
 
 1. Queries without tables. These just operate on request parameters. Example: `select token_parameters.user_id`. Thes are implemented in the `StaticSqlParameterQuery` class.
 2. Queries with tables. Example: `select org_id from users where id = token_parameters.user_id`. These use parameter tables, and are implemented in `SqlParameterQuery`. These are used to pre-process rows in the parameter tables for efficient lookup later.
 
-### StaticSqlParameterQuery
+#### StaticSqlParameterQuery
 
 These are effecitively just a function of `(request) => Array[{bucket}]`. These queries can select values from request parameters, and apply filters from request parameters.
 
@@ -90,7 +125,7 @@ request.parameters() -- ParameterValueClause
 fn(token_parameters.param) -- ParameterValueClause. This includes most operators.
 ```
 
-### SqlParameterQuery
+#### SqlParameterQuery
 
 These queries pre-process parameter tables to effectively create an "index" for efficient queries when syncing.
 

package/dist/BucketSource.d.ts

@@ -20,7 +20,7 @@ export interface HydrationInput extends CreateSourceParams {
     scalarExpressions: ScalarExpressionEngine;
 }
 /**
- * A BucketSource is a _logical_ bucket or sync stream definition. It is primarily used to group together
+ * A BucketSource is a _logical_ bucket or Sync Stream definition. It is primarily used to group together
  * related BucketDataSource, BucketParameterLookupSource and BucketParameterQuerierSource definitions,
  * for the purpose of subscribing to specific streams. It does not directly define the implementation
  * or replication process.
@@ -70,7 +70,7 @@ export type ScopedEvaluateParameterRow = (sourceTable: SourceTableRef, row: Sqli
  * Encodes a static definition of a bucket source, as parsed from sync rules or stream definitions.
  *
  * This does not require any "hydration" itself: All results are independent of bucket names.
- * The higher-level HydratedSyncRules will use a HydrationState to generate bucket names.
+ * The higher-level HydratedSyncConfig will use a HydrationState to generate bucket names.
  */
 export interface BucketDataSource {
     /**

package/dist/HydratedSyncConfig.d.ts

@@ -1,5 +1,6 @@
 import { BucketDataSource } from './BucketSource.js';
 import { BucketSource, CompatibilityContext, EvaluatedParameters, EvaluatedRow, EvaluationError, GetBucketParameterQuerierResult, GetQuerierOptions, HydratedEventDescriptor, HydrateSyncConfigParams, ParameterIndexLookupCreator, SqliteInputValue, SqliteValue, SyncConfig, TablePattern } from './index.js';
+import { SourceTableConfigMap } from './SourceTableConfig.js';
 import { SourceTableRef } from './SourceTableRef.js';
 import { EvaluateRowOptions, SqliteRow } from './types.js';
 export interface MatchingSources {
@@ -17,6 +18,7 @@ export interface MatchingSources {
  */
 export declare class HydratedSyncConfig {
     #private;
+    readonly sourceTableConfig: SourceTableConfigMap;
     /**
      * These are used by queriers, and do not support merging across multiple SyncConfigs.
      */

package/dist/HydratedSyncConfig.js

@@ -1,6 +1,7 @@
 import { CompatibilityContext, isEvaluatedParameters, isEvaluatedRow, isEvaluationError, mergeBucketParameterQueriers, mergeDataSources, mergeParameterIndexLookupCreators, parameterLookupScopeKey } from './index.js';
 import { sourceTableRefKey } from './SourceTableRef.js';
 import { createScalarExpressionEngine } from './sync_plan/engine/factory.js';
+import { PrecompiledSyncConfig } from './sync_plan/evaluator/index.js';
 import { applyRowContext, uniqueBy } from './utils.js';
 /**
  * HydratedSyncConfig is sync config definitions along with persisted state.
@@ -12,6 +13,7 @@ import { applyRowContext, uniqueBy } from './utils.js';
  * The persisted state specifically affects bucket names, as well as V3+ storage structure.
  */
 export class HydratedSyncConfig {
+    sourceTableConfig;
     /**
      * These are used by queriers, and do not support merging across multiple SyncConfigs.
      */
@@ -54,8 +56,12 @@ export class HydratedSyncConfig {
         const hydrationState = params.createParams.hydrationState;
         const definitions = params.definitions;
         if (definitions.length == 0) {
-            throw new Error('HydratedSyncRules requires at least one SyncConfig definition');
+            throw new Error('HydratedSyncConfig requires at least one SyncConfig definition');
         }
+        // The service validates that definitions sharing a source reader have compatible source-table options.
+        const firstConfig = definitions[0];
+        this.sourceTableConfig =
+            firstConfig instanceof PrecompiledSyncConfig ? (firstConfig.plan.sourceTableConfig ?? {}) : {};
         this.sourceDefinitions = [...definitions];
         this.compatibility = assertSharedCompatibility(this.sourceDefinitions);
         this.hydrationInput = {
@@ -199,7 +205,7 @@ export class HydratedSyncConfig {
     assertSingleSourceDefinition(debugName) {
         // We may split the types in the future to enforce this on a type level instead of runtime level
         if (this.sourceDefinitions.length != 1) {
-            throw new Error(`${debugName} is not supported for HydratedSyncRules with multiple SyncConfigs`);
+            throw new Error(`${debugName} is not supported for HydratedSyncConfig with multiple SyncConfigs`);
         }
     }
 }
@@ -210,7 +216,7 @@ function assertSharedCompatibility(definitions) {
     }
     for (const definition of definitions) {
         if (!definition.compatibility.equals(compatibility)) {
-            throw new Error('All SyncConfigs in a HydratedSyncRules instance must use the same CompatibilityContext');
+            throw new Error('All SyncConfigs in a HydratedSyncConfig instance must use the same CompatibilityContext');
         }
     }
     return compatibility;

package/dist/HydratedSyncConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"HydratedSyncConfig.js","sourceRoot":"","sources":["../src/HydratedSyncConfig.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"HydratedSyncConfig.js","sourceRoot":"","sources":["../src/HydratedSyncConfig.ts"],"names":[],"mappings":"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"}

package/dist/SourceTableConfig.d.ts

@@ -0,0 +1,42 @@
+import type { JsonObject } from './json.js';
+import { type MongoTableFilter } from './mongo/MongoFilterExpression.js';
+import { ImplicitSchemaTablePattern } from './TablePattern.js';
+/**
+ * Options for one entry in `config.source_table_options`. MongoDB filtering is parsed in every edition; execution support is validated by the source adapter.
+ */
+export interface SourceTableConfig {
+    mongodb_filter_expression?: MongoTableFilter;
+}
+/**
+ * Source-table options keyed by an authored table pattern.
+ */
+export type SourceTableConfigMap<TTableConfig extends SourceTableConfig = SourceTableConfig> = Readonly<Partial<Record<string, TTableConfig>>>;
+/**
+ * Generate the source-table options schema with MongoDB pre-filtering expressions.
+ */
+export declare function createSourceTableConfigSchema(): JsonObject;
+/**
+ * Parse a source-table key using the same right-to-left qualification as Sync Stream table references.
+ */
+export declare function parseSourceTableConfigKey(name: string): ImplicitSchemaTablePattern;
+/**
+ * Find authored keys that identify the same pattern after SQL identifier normalization.
+ * Invalid keys are left to the source-table schema validator.
+ */
+export declare function findDuplicateSourceTableConfigKeys(keys: Iterable<string>): Array<[string, string]>;
+/**
+ * Validate and copy source-table options while preserving declaration order.
+ */
+export declare function normalizeSourceTableConfig(value: unknown): SourceTableConfigMap;
+/**
+ * Reject filter connection tags that query hydration cannot honor.
+ */
+export declare function assertMongoFilterConnection(pattern: ImplicitSchemaTablePattern): void;
+/**
+ * Conservative equality: declaration order and expression order are significant.
+ */
+export declare function sourceTableConfigsEqual(left: SourceTableConfigMap, right: SourceTableConfigMap): boolean;
+/**
+ * Configured expressions require execution support even when current collections opt out.
+ */
+export declare function hasMongoFilterExpressions(config: SourceTableConfigMap, connectionTag: string): boolean;

package/dist/SourceTableConfig.js

@@ -0,0 +1,152 @@
+import { MONGO_FILTER_VALIDATOR } from './mongo/MongoFilterExpression.js';
+import { DEFAULT_TAG, ImplicitSchemaTablePattern, TablePattern } from './TablePattern.js';
+const SOURCE_TABLE_NAME_ERROR = 'Source table patterns must use <table>, <database>.<table>, or <connection>.<database>.<table>. Double-quote names containing dots or quotes.';
+/**
+ * Generate the source-table options schema with MongoDB pre-filtering expressions.
+ */
+export function createSourceTableConfigSchema() {
+    return {
+        type: 'object',
+        propertyNames: {
+            minLength: 1,
+            pattern: '^(?:[^."]+|"(?:[^"]|"")+")(?:\\.(?:[^."]+|"(?:[^"]|"")+")){0,2}$'
+        },
+        additionalProperties: {
+            type: 'object',
+            properties: {
+                mongodb_filter_expression: {
+                    anyOf: [{ $ref: '#/definitions/mongodb_filter_expression' }, { const: 'disabled' }]
+                }
+            },
+            additionalProperties: false
+        }
+    };
+}
+/**
+ * Parse a source-table key using the same right-to-left qualification as Sync Stream table references.
+ */
+export function parseSourceTableConfigKey(name) {
+    const parts = parseQualifiedIdentifiers(name);
+    if (parts.length > 3)
+        throw new Error(SOURCE_TABLE_NAME_ERROR);
+    if (parts.length == 1)
+        return new ImplicitSchemaTablePattern(null, parts[0]);
+    if (parts.length == 2)
+        return new TablePattern(parts[0], parts[1], DEFAULT_TAG);
+    return new TablePattern(parts[1], parts[2], parts[0]);
+}
+/**
+ * Find authored keys that identify the same pattern after SQL identifier normalization.
+ * Invalid keys are left to the source-table schema validator.
+ */
+export function findDuplicateSourceTableConfigKeys(keys) {
+    const seen = new Map();
+    const duplicates = [];
+    for (const key of keys) {
+        let pattern;
+        try {
+            pattern = parseSourceTableConfigKey(key);
+        }
+        catch {
+            continue;
+        }
+        const identity = JSON.stringify([pattern.connectionTag, pattern.schema, pattern.tablePattern]);
+        const previous = seen.get(identity);
+        if (previous !== undefined) {
+            duplicates.push([previous, key]);
+        }
+        else {
+            seen.set(identity, key);
+        }
+    }
+    return duplicates;
+}
+/**
+ * Split a source-table key on unquoted dots and normalize each identifier.
+ */
+function parseQualifiedIdentifiers(name) {
+    /*
+     * Match <table>, <database>.<table>, or <connection>.<database>.<table> from right to left.
+     * Each component is either unquoted without dots or quotes, or quoted to allow dots and escaped quotes within it.
+     * A quote inside a quoted component is represented by two consecutive quotes, following SQL identifier syntax.
+     */
+    const qualifiedIdentifier = /^(?:(?:(?<connection>"(?:[^"]|"")+"|[^."]+)\.)?(?<database>"(?:[^"]|"")+"|[^."]+)\.)?(?<table>"(?:[^"]|"")+"|[^."]+)$/;
+    const match = qualifiedIdentifier.exec(name);
+    if (match == null)
+        throw new Error(SOURCE_TABLE_NAME_ERROR);
+    // Nesting the optional groups aligns one-, two-, and three-part names from the right.
+    return [match.groups.connection, match.groups.database, match.groups.table]
+        .filter((part) => part != null)
+        .map((part) => {
+        // Quoted names preserve case and may contain dots or escaped quotes. Unquoted names follow SQL case folding.
+        return part.startsWith('"') ? part.slice(1, -1).replaceAll('""', '"') : part.toLowerCase();
+    });
+}
+/**
+ * Validate and copy source-table options while preserving declaration order.
+ */
+export function normalizeSourceTableConfig(value) {
+    if (value === undefined)
+        return {};
+    assertObject(value, 'Source table configuration must be a JSON object.');
+    const duplicate = findDuplicateSourceTableConfigKeys(Object.keys(value))[0];
+    if (duplicate != null) {
+        const [previous, key] = duplicate;
+        throw new Error(`Source-table keys ${JSON.stringify(previous)} and ${JSON.stringify(key)} resolve to the same pattern.`);
+    }
+    return Object.fromEntries(Object.entries(value).map(([table, options]) => {
+        if (!table)
+            throw new Error('A source table name must not be empty.');
+        const pattern = parseSourceTableConfigKey(table);
+        assertObject(options, 'Source table options must be JSON objects.');
+        for (const key of Object.keys(options)) {
+            if (key !== 'mongodb_filter_expression')
+                throw new Error(`Unknown source-table option: ${key}`);
+        }
+        const filter = options.mongodb_filter_expression;
+        if (filter !== undefined && filter !== 'disabled') {
+            assertMongoFilterConnection(pattern);
+            const result = MONGO_FILTER_VALIDATOR.safeParse(filter);
+            if (!result.success) {
+                throw new Error(`Invalid MongoDB pre-filtering expression for source table ${JSON.stringify(table)}: ${result.error.message}`);
+            }
+        }
+        return [table, structuredClone(options)];
+    }));
+}
+/**
+ * Reject filter connection tags that query hydration cannot honor.
+ */
+export function assertMongoFilterConnection(pattern) {
+    // FIXME: Revisit when multiple connections are supported and query hydration honors explicit tags.
+    // Until then, accepting another tag can silently omit its filter while the query reads the default connection.
+    const tag = pattern.connectionTag ?? DEFAULT_TAG;
+    if (tag !== DEFAULT_TAG) {
+        throw new Error(`MongoDB replication pre-filtering only supports the "${DEFAULT_TAG}" connection; connection ${JSON.stringify(tag)} is not supported.`);
+    }
+}
+/**
+ * Conservative equality: declaration order and expression order are significant.
+ */
+export function sourceTableConfigsEqual(left, right) {
+    try {
+        return JSON.stringify(normalizeSourceTableConfig(left)) == JSON.stringify(normalizeSourceTableConfig(right));
+    }
+    catch {
+        // Saved options may no longer validate after an upgrade. Do not reuse their replication stream.
+        return false;
+    }
+}
+function assertObject(value, message) {
+    if (value == null || typeof value != 'object' || Array.isArray(value))
+        throw new Error(message);
+}
+/**
+ * Configured expressions require execution support even when current collections opt out.
+ */
+export function hasMongoFilterExpressions(config, connectionTag) {
+    return Object.entries(config).some(([name, options]) => (parseSourceTableConfigKey(name).connectionTag ?? DEFAULT_TAG) === connectionTag &&
+        options?.mongodb_filter_expression !== undefined &&
+        options.mongodb_filter_expression !== 'disabled');
+}
+//# sourceMappingURL=SourceTableConfig.js.map

package/dist/SourceTableConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SourceTableConfig.js","sourceRoot":"","sources":["../src/SourceTableConfig.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAyB,MAAM,kCAAkC,CAAC;AACjG,OAAO,EAAE,WAAW,EAAE,0BAA0B,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE1F,MAAM,uBAAuB,GAC3B,+IAA+I,CAAC;AAgBlJ;;GAEG;AACH,MAAM,UAAU,6BAA6B;IAC3C,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,aAAa,EAAE;YACb,SAAS,EAAE,CAAC;YACZ,OAAO,EAAE,kEAAkE;SAC5E;QACD,oBAAoB,EAAE;YACpB,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,yBAAyB,EAAE;oBACzB,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,yCAAyC,EAAE,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;iBACpF;aACF;YACD,oBAAoB,EAAE,KAAK;SAC5B;KACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAAY;IACpD,MAAM,KAAK,GAAG,yBAAyB,CAAC,IAAI,CAAC,CAAC;IAC9C,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;IAE/D,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,IAAI,0BAA0B,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7E,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;IAChF,OAAO,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACxD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kCAAkC,CAAC,IAAsB;IACvE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvC,MAAM,UAAU,GAA4B,EAAE,CAAC;IAC/C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,OAAmC,CAAC;QACxC,IAAI,CAAC;YACH,OAAO,GAAG,yBAAyB,CAAC,GAAG,CAAC,CAAC;QAC3C,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;QAC/F,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACpC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,UAAU,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC;QACnC,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;GAEG;AACH,SAAS,yBAAyB,CAAC,IAAY;IAC7C;;;;OAIG;IACH,MAAM,mBAAmB,GACvB,uHAAuH,CAAC;IAC1H,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,KAAK,IAAI,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;IAE5D,sFAAsF;IACtF,OAAO,CAAC,KAAK,CAAC,MAAO,CAAC,UAAU,EAAE,KAAK,CAAC,MAAO,CAAC,QAAQ,EAAE,KAAK,CAAC,MAAO,CAAC,KAAK,CAAC;SAC3E,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,IAAI,IAAI,IAAI,CAAC;SAC9C,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACZ,6GAA6G;QAC7G,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;IAC7F,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,0BAA0B,CAAC,KAAc;IACvD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACnC,YAAY,CAAC,KAAK,EAAE,mDAAmD,CAAC,CAAC;IACzE,MAAM,SAAS,GAAG,kCAAkC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5E,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;QACtB,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;QAClC,MAAM,IAAI,KAAK,CACb,qBAAqB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,QAAQ,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,+BAA+B,CACxG,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,EAAE;QAC7C,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;QACtE,MAAM,OAAO,GAAG,yBAAyB,CAAC,KAAK,CAAC,CAAC;QACjD,YAAY,CAAC,OAAO,EAAE,4CAA4C,CAAC,CAAC;QACpE,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACvC,IAAI,GAAG,KAAK,2BAA2B;gBAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,GAAG,EAAE,CAAC,CAAC;QAClG,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,yBAAyB,CAAC;QACjD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;YAClD,2BAA2B,CAAC,OAAO,CAAC,CAAC;YACrC,MAAM,MAAM,GAAG,sBAAsB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YACxD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACpB,MAAM,IAAI,KAAK,CACb,6DAA6D,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAC9G,CAAC;YACJ,CAAC;QACH,CAAC;QACD,OAAO,CAAC,KAAK,EAAE,eAAe,CAAC,OAAO,CAAsB,CAAC,CAAC;IAChE,CAAC,CAAC,CACH,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,2BAA2B,CAAC,OAAmC;IAC7E,mGAAmG;IACnG,+GAA+G;IAC/G,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,IAAI,WAAW,CAAC;IACjD,IAAI,GAAG,KAAK,WAAW,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,wDAAwD,WAAW,4BAA4B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,oBAAoB,CACvI,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAA0B,EAAE,KAA2B;IAC7F,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,0BAA0B,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,0BAA0B,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/G,CAAC;IAAC,MAAM,CAAC;QACP,gGAAgG;QAChG,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,KAAc,EAAE,OAAe;IACnD,IAAI,KAAK,IAAI,IAAI,IAAI,OAAO,KAAK,IAAI,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;AAClG,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAA4B,EAAE,aAAqB;IAC3F,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAChC,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE,CAClB,CAAC,yBAAyB,CAAC,IAAI,CAAC,CAAC,aAAa,IAAI,WAAW,CAAC,KAAK,aAAa;QAChF,OAAO,EAAE,yBAAyB,KAAK,SAAS;QAChD,OAAO,CAAC,yBAAyB,KAAK,UAAU,CACnD,CAAC;AACJ,CAAC"}

package/dist/SqlSyncRules.d.ts

@@ -2,7 +2,16 @@ import { BucketPriority } from './BucketDescription.js';
 import { SyncConfig, SyncConfigWithErrors } from './SyncConfig.js';
 import { YamlError } from './errors.js';
 import { RequestParameters, SourceSchema, SqliteJsonRow } from './types.js';
+/**
+ * Source connection types keyed by connection tag for sync config validation.
+ */
+export type SourceConnectionMap = Record<string, {
+    type: string;
+}>;
 export interface SyncRulesOptions {
+    /**
+     * Source database schema.
+     */
     schema?: SourceSchema;
     /**
      * The default schema to use when only a table name is specified.
@@ -10,6 +19,11 @@ export interface SyncRulesOptions {
      * 'public' for Postgres, default database for MongoDB/MySQL.
      */
     defaultSchema: string;
+    /**
+     * Source connection types keyed by connection tag. When omitted, source-specific options report warnings
+     * if their connection type cannot be checked.
+     */
+    connections?: SourceConnectionMap;
     throwOnError?: boolean;
 }
 export interface RequestedStream {

package/dist/SqlSyncRules.js

@@ -23,7 +23,8 @@ export class SqlSyncRules extends SyncConfig {
         const parser = new SyncConfigFromYaml({
             throwOnError: options.throwOnError ?? true,
             schema: options.schema,
-            defaultSchema: options.defaultSchema
+            defaultSchema: options.defaultSchema,
+            connections: options.connections
         }, yaml);
         return parser.read();
     }

package/dist/SqlSyncRules.js.map

@@ -1 +1 @@
-{"version":3,"file":"SqlSyncRules.js","sourceRoot":"","sources":["../src/SqlSyncRules.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAwB,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAwDpD,MAAM,OAAO,YAAa,SAAQ,UAAU;IAC1C,MAAM,CAAC,QAAQ,CAAC,IAAY,EAAE,OAAyB;QACrD,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAC3C,OAAO,KAAK,CAAC,MAAM,CAAC;QACtB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,eAAe,EAAE,CAAC;gBACjC,OAAO,CAAC,CAAC,MAAM,CAAC;YAClB,CAAC;iBAAM,IAAI,CAAC,YAAY,SAAS,EAAE,CAAC;gBAClC,OAAO,CAAC,CAAC,CAAC,CAAC;YACb,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,CAAC,QAAQ,CAAC,IAAY,EAAE,OAAyB;QACrD,MAAM,MAAM,GAAG,IAAI,kBAAkB,CACnC;YACE,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,IAAI;YAC1C,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,aAAa,EAAE,OAAO,CAAC,aAAa;SACrC,EACD,IAAI,CACL,CAAC;QAEF,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;IACvB,CAAC;CACF"}
+{"version":3,"file":"SqlSyncRules.js","sourceRoot":"","sources":["../src/SqlSyncRules.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAwB,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAuEpD,MAAM,OAAO,YAAa,SAAQ,UAAU;IAC1C,MAAM,CAAC,QAAQ,CAAC,IAAY,EAAE,OAAyB;QACrD,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAC3C,OAAO,KAAK,CAAC,MAAM,CAAC;QACtB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,eAAe,EAAE,CAAC;gBACjC,OAAO,CAAC,CAAC,MAAM,CAAC;YAClB,CAAC;iBAAM,IAAI,CAAC,YAAY,SAAS,EAAE,CAAC;gBAClC,OAAO,CAAC,CAAC,CAAC,CAAC;YACb,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,CAAC,QAAQ,CAAC,IAAY,EAAE,OAAyB;QACrD,MAAM,MAAM,GAAG,IAAI,kBAAkB,CACnC;YACE,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,IAAI;YAC1C,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,aAAa,EAAE,OAAO,CAAC,aAAa;YACpC,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC,EACD,IAAI,CACL,CAAC;QAEF,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;IACvB,CAAC;CACF"}

package/dist/StorageVersion.d.ts

@@ -16,7 +16,6 @@ export interface ValidatedStorageVersion {
     stable: boolean;
 }
 export declare const STORAGE_VERSIONS: Map<number, ValidatedStorageVersion>;
-export declare const DEFAULT_STORAGE_VERSION: ValidatedStorageVersion;
 /**
  * Parse a storage version.
  *

package/dist/StorageVersion.js

@@ -4,7 +4,6 @@ export const STORAGE_VERSIONS = new Map([
     [3, { version: 3, stable: false }],
     [4, { version: 4, stable: true }]
 ]);
-export const DEFAULT_STORAGE_VERSION = STORAGE_VERSIONS.get(2);
 /**
  * Parse a storage version.
  *

package/dist/StorageVersion.js.map

@@ -1 +1 @@
-{"version":3,"file":"StorageVersion.js","sourceRoot":"","sources":["../src/StorageVersion.ts"],"names":[],"mappings":"AAmBA,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAkC;IACvE,mFAAmF;IACnF,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACjC,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAClC,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;CAClC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,uBAAuB,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAe;IACpD,OAAO,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AACvC,CAAC"}
+{"version":3,"file":"StorageVersion.js","sourceRoot":"","sources":["../src/StorageVersion.ts"],"names":[],"mappings":"AAmBA,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAkC;IACvE,mFAAmF;IACnF,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACjC,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAClC,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;CAClC,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAe;IACpD,OAAO,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AACvC,CAAC"}

package/dist/SyncConfig.d.ts

@@ -14,7 +14,9 @@ export declare abstract class SyncConfig {
     bucketDataSources: BucketDataSource[];
     bucketParameterLookupSources: ParameterIndexLookupCreator[];
     bucketSources: BucketSource[];
-    /** Prepared event definitions. Executable event descriptors only exist on {@link HydratedSyncConfig}. */
+    /**
+     * Prepared event definitions. Executable event descriptors only exist on {@link HydratedSyncConfig}.
+     */
     eventDefinitions: EventDefinition[];
     compatibility: CompatibilityContext;
     /**

package/dist/SyncConfig.js

@@ -9,7 +9,9 @@ export class SyncConfig {
     bucketDataSources = [];
     bucketParameterLookupSources = [];
     bucketSources = [];
-    /** Prepared event definitions. Executable event descriptors only exist on {@link HydratedSyncConfig}. */
+    /**
+     * Prepared event definitions. Executable event descriptors only exist on {@link HydratedSyncConfig}.
+     */
     eventDefinitions = [];
     compatibility = CompatibilityContext.FULL_BACKWARDS_COMPATIBILITY;
     /**

package/dist/SyncConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"SyncConfig.js","sourceRoot":"","sources":["../src/SyncConfig.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SyncConfig.js","sourceRoot":"","sources":["../src/SyncConfig.ts"],"names":[],"mappings":"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"}

package/dist/SyncConfigDiagnostics.d.ts

@@ -0,0 +1,12 @@
+import type { ErrorLocation } from './errors.js';
+/**
+ * A decoded config path, for example `['config', 'source_table_options', 'orders', 'option']`.
+ */
+export type SyncConfigSourcePath = readonly (string | number)[];
+export type SyncConfigSourceLocationTarget = 'key' | 'value';
+export interface SyncConfigSourceLocationResolver {
+    /**
+     * Resolve a field to its source span, falling back to its nearest existing ancestor.
+     */
+    getLocation(path: SyncConfigSourcePath, target?: SyncConfigSourceLocationTarget): ErrorLocation | undefined;
+}

package/dist/SyncConfigDiagnostics.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=SyncConfigDiagnostics.js.map

package/dist/SyncConfigDiagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SyncConfigDiagnostics.js","sourceRoot":"","sources":["../src/SyncConfigDiagnostics.ts"],"names":[],"mappings":""}

package/dist/TablePattern.d.ts

@@ -14,7 +14,7 @@ export declare class ImplicitSchemaTablePattern implements Equatable {
     readonly tablePattern: string;
     readonly connectionTag: string | null;
     readonly schema: string | null;
-    constructor(schema: string | null, tablePattern: string);
+    constructor(schema: string | null, tablePattern: string, connectionTag?: string | null);
     get isWildcard(): boolean;
     get isSchemaWildcard(): boolean;
     get name(): string;
@@ -28,7 +28,7 @@ export declare class ImplicitSchemaTablePattern implements Equatable {
 export declare class TablePattern extends ImplicitSchemaTablePattern {
     readonly connectionTag: string;
     readonly schema: string;
-    constructor(schema: string, tablePattern: string);
+    constructor(schema: string, tablePattern: string, connectionTag?: string);
     /**
      * Unique key for this table pattern, used for caching.
      *

package/dist/TablePattern.js

@@ -12,13 +12,19 @@ export class ImplicitSchemaTablePattern {
     tablePattern;
     connectionTag;
     schema;
-    constructor(schema, tablePattern) {
+    constructor(schema, tablePattern, connectionTag) {
         this.tablePattern = tablePattern;
-        if (schema) {
+        if (connectionTag != null) {
+            // A connection tag identifies a database on that connection, so a schema must be provided with it.
+            if (schema == null)
+                throw new Error('A schema is required when a connection tag is set.');
+            this.connectionTag = connectionTag;
+            this.schema = schema;
+        }
+        else if (schema) {
             const splitSchema = schema.split('.');
-            if (splitSchema.length > 2) {
+            if (splitSchema.length > 2)
                 throw new Error(`Invalid schema: ${schema}`);
-            }
             if (splitSchema.length == 2) {
                 this.connectionTag = splitSchema[0];
                 this.schema = splitSchema[1];
@@ -46,7 +52,11 @@ export class ImplicitSchemaTablePattern {
         return this.tablePattern;
     }
     toTablePattern(defaultSchema) {
-        return new TablePattern(this.schema ?? defaultSchema, this.tablePattern);
+        // Preserve existing hydration behavior: explicit connection tags are stored but resolve to the default tag.
+        // FIXME: When multiple connections are supported, honor explicit tags consistently across SQL, source-table options,
+        // and hydration while preserving the interpretation of existing saved plans.
+        // Pass a tag for explicit schemas so quoted dots stay literal; undefined lets runtime defaults retain qualification.
+        return new TablePattern(this.schema ?? defaultSchema, this.tablePattern, this.schema == null ? undefined : DEFAULT_TAG);
     }
     buildHash(hasher) {
         if (this.connectionTag) {
@@ -68,8 +78,8 @@ export class ImplicitSchemaTablePattern {
  * Some pattern matching SourceTables.
  */
 export class TablePattern extends ImplicitSchemaTablePattern {
-    constructor(schema, tablePattern) {
-        super(schema, tablePattern);
+    constructor(schema, tablePattern, connectionTag) {
+        super(schema, tablePattern, connectionTag);
     }
     /**
      * Unique key for this table pattern, used for caching.