@powersync/service-sync-rules 0.39.0 → 0.41.0

package/dist/sync_plan/evaluator/row_projection.js

@@ -0,0 +1,71 @@
+import { filterJsonRow, isJsonValue } from '../../utils.js';
+import { scalarStatementToSql } from '../engine/scalar_expression_engine.js';
+import { resolveRowMetadata, TableProcessorToSqlHelper } from './table_processor_to_sql.js';
+/**
+ * Prepares the shared projection/filter portion of bucket and event row evaluators.
+ */
+export class PendingRowProjection {
+    tablePattern;
+    outputs = [];
+    numberOfOutputExpressions;
+    numberOfParameters;
+    evaluatorInputs;
+    statement;
+    constructor(evaluator, defaultSchema) {
+        const translationHelper = new TableProcessorToSqlHelper(evaluator);
+        const outputExpressions = [];
+        for (const column of evaluator.columns) {
+            if (column === 'star') {
+                this.outputs.push('star');
+            }
+            else {
+                const expressionIndex = outputExpressions.length;
+                outputExpressions.push(translationHelper.mapper.transform(column.expr));
+                this.outputs.push({ index: expressionIndex, alias: column.alias });
+            }
+        }
+        this.numberOfOutputExpressions = outputExpressions.length;
+        for (const parameter of evaluator.parameters) {
+            outputExpressions.push(translationHelper.mapper.transform(parameter.expr));
+        }
+        this.numberOfParameters = evaluator.parameters.length;
+        this.statement = {
+            outputs: outputExpressions,
+            filters: translationHelper.filterExpressions,
+            tableValuedFunctions: translationHelper.tableValuedFunctions
+        };
+        this.tablePattern = evaluator.sourceTable.toTablePattern(defaultSchema);
+        this.evaluatorInputs = translationHelper.mapper.instantiation;
+    }
+    get debugSql() {
+        return scalarStatementToSql(this.statement);
+    }
+    instantiate(engine) {
+        const evaluator = engine.prepareEvaluator(this.statement);
+        const pattern = this.tablePattern;
+        return (options) => {
+            const inputInstantiation = this.evaluatorInputs.map((input) => 'column' in input ? options.record[input.column] : resolveRowMetadata(input, pattern, options.sourceTable));
+            const results = [];
+            for (const source of evaluator.evaluate(inputInstantiation)) {
+                const record = {};
+                for (const output of this.outputs) {
+                    if (output === 'star') {
+                        Object.assign(record, filterJsonRow(options.record));
+                    }
+                    else {
+                        const value = source[output.index];
+                        if (isJsonValue(value)) {
+                            record[output.alias] = value;
+                        }
+                    }
+                }
+                results.push({
+                    data: record,
+                    partitionValues: source.slice(this.numberOfOutputExpressions, this.numberOfOutputExpressions + this.numberOfParameters)
+                });
+            }
+            return results;
+        };
+    }
+}
+//# sourceMappingURL=row_projection.js.map

package/dist/sync_plan/evaluator/row_projection.js.map

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

package/dist/sync_plan/evaluator/table_processor_to_sql.d.ts

@@ -1,3 +1,5 @@
+import { SourceTableRef } from '../../SourceTableRef.js';
+import { TablePattern } from '../../TablePattern.js';
 import { TableValuedFunction, TableValuedFunctionOutput } from '../engine/scalar_expression_engine.js';
 import { SqlExpression } from '../expression.js';
 import * as plan from '../plan.js';
@@ -9,12 +11,13 @@ import * as plan from '../plan.js';
  */
 export declare class TableProcessorToSqlHelper {
     mapper: {
-        instantiation: plan.ColumnSqlParameterValue[];
+        instantiation: (plan.ColumnSqlParameterValue | plan.RowMetadataSqlValue)[];
         tableValuedFunctions: Map<plan.TableProcessorTableValuedFunction, TableValuedFunction>;
         transform(expr: SqlExpression<plan.SqlParameterValue>): SqlExpression<number | TableValuedFunctionOutput>;
-        transformWithoutTableValued(expr: SqlExpression<plan.ColumnSqlParameterValue>): SqlExpression<number>;
+        transformWithoutTableValued(expr: SqlExpression<plan.ColumnSqlParameterValue | plan.RowMetadataSqlValue>): SqlExpression<number>;
     };
     readonly filterExpressions: SqlExpression<number | TableValuedFunctionOutput>[];
     get tableValuedFunctions(): TableValuedFunction[];
     constructor(source: plan.TableProcessor);
 }
+export declare function resolveRowMetadata(value: plan.RowMetadataSqlValue, pattern: TablePattern, table: SourceTableRef): string;

package/dist/sync_plan/evaluator/table_processor_to_sql.js

@@ -25,4 +25,14 @@ export class TableProcessorToSqlHelper {
         }
     }
 }
+export function resolveRowMetadata(value, pattern, table) {
+    switch (value.metadata) {
+        case 'schema':
+            return table.schema;
+        case 'table_name':
+            return table.name;
+        case 'table_suffix':
+            return pattern.isWildcard ? pattern.suffix(table.name) : '';
+    }
+}
 //# sourceMappingURL=table_processor_to_sql.js.map

package/dist/sync_plan/evaluator/table_processor_to_sql.js.map

@@ -1 +1 @@
-{"version":3,"file":"table_processor_to_sql.js","sourceRoot":"","sources":["../../../src/sync_plan/evaluator/table_processor_to_sql.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,8BAA8B,EAG/B,MAAM,uCAAuC,CAAC;AAI/C;;;;;GAKG;AACH,MAAM,OAAO,yBAAyB;IACpC,MAAM,GAAG,8BAA8B,EAAgC,CAAC;IAC/D,iBAAiB,GAAwD,EAAE,CAAC;IAErF,IAAI,oBAAoB;QACtB,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,YAAY,MAA2B;QACrC,yCAAyC;QACzC,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,oBAAoB,EAAE,CAAC;YAC7C,MAAM,MAAM,GAAwB;gBAClC,IAAI,EAAE,EAAE,CAAC,YAAY;gBACrB,MAAM,EAAE,EAAE,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,2BAA2B,CAAC,CAAC,CAAC,CAAC;aACjF,CAAC;YACF,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QACnD,CAAC;QAED,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACpC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"table_processor_to_sql.js","sourceRoot":"","sources":["../../../src/sync_plan/evaluator/table_processor_to_sql.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,8BAA8B,EAG/B,MAAM,uCAAuC,CAAC;AAI/C;;;;;GAKG;AACH,MAAM,OAAO,yBAAyB;IACpC,MAAM,GAAG,8BAA8B,EAA2D,CAAC;IAC1F,iBAAiB,GAAwD,EAAE,CAAC;IAErF,IAAI,oBAAoB;QACtB,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,YAAY,MAA2B;QACrC,yCAAyC;QACzC,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,oBAAoB,EAAE,CAAC;YAC7C,MAAM,MAAM,GAAwB;gBAClC,IAAI,EAAE,EAAE,CAAC,YAAY;gBACrB,MAAM,EAAE,EAAE,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,2BAA2B,CAAC,CAAC,CAAC,CAAC;aACjF,CAAC;YACF,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QACnD,CAAC;QAED,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACpC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;CACF;AAED,MAAM,UAAU,kBAAkB,CAChC,KAA+B,EAC/B,OAAqB,EACrB,KAAqB;IAErB,QAAQ,KAAK,CAAC,QAAQ,EAAE,CAAC;QACvB,KAAK,QAAQ;YACX,OAAO,KAAK,CAAC,MAAM,CAAC;QACtB,KAAK,YAAY;YACf,OAAO,KAAK,CAAC,IAAI,CAAC;QACpB,KAAK,cAAc;YACjB,OAAO,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAChE,CAAC;AACH,CAAC"}

package/dist/sync_plan/plan.d.ts

@@ -24,6 +24,7 @@ export interface SyncPlan {
     buckets: StreamBucketDataSource[];
     parameterIndexes: StreamParameterIndexLookupCreator[];
     streams: CompiledSyncStream[];
+    events: CompiledEventDescriptor[];
 }
 /**
  * Something that processes a source row if it matches filters.
@@ -88,10 +89,10 @@ export interface TableProcessorTableValuedFunctionOutput {
 /**
  * External data that can be used in expressions for {@link TableProcessor}s.
  *
- * This allows references to the row in the table being processed, and references to outputs of joined
- * {@link TableProcessor#tableValuedFunctions}.
+ * This allows references to the row in the table being processed, metadata about the row's source table, and
+ * references to outputs of joined {@link TableProcessor#tableValuedFunctions}.
  */
-export type TableProcessorData = ColumnSqlParameterValue | TableProcessorTableValuedFunctionOutput;
+export type TableProcessorData = ColumnSqlParameterValue | RowMetadataSqlValue | TableProcessorTableValuedFunctionOutput;
 /**
  * A scalar partition key evaluates to a single value in the source or parameter row. For instance, a stream definition
  * like `SELECT * FROM users WHERE id = auth.user_id()` would generate a scalar key to partition users by the `id`
@@ -107,22 +108,52 @@ export interface PartitionKey {
  * duplicate bucket data but can still share the actual processing logic between multiple streams (to avoid evaluating
  * the same filters and expressions multiple times).
  */
-export interface StreamDataSource extends TableProcessor {
+export interface RowProjection extends TableProcessor {
+    /**
+     * Output columns produced when a matching source row is evaluated.
+     */
+    columns: ColumnSource[];
+}
+export interface StreamDataSource extends RowProjection {
     /**
      * The name of the output table for evaluated rows.
      *
      * If null, the name of the table being evaluated should be used instead.
      */
     outputTableName?: string;
-    /**
-     * Output columns describing the row to store in buckets.
-     */
-    columns: ColumnSource[];
 }
 export type ColumnSource = 'star' | {
     expr: SqlExpression<TableProcessorData>;
     alias: string;
 };
+/**
+ * A named replication event compiled from `event_definitions`.
+ */
+export interface CompiledEventDescriptor {
+    name: string;
+    sourceQueries: CompiledEventSourceQuery[];
+}
+/**
+ * A single payload query for an event.
+ *
+ * Event payload queries are restricted to one physical source table. A query can have multiple variants after its
+ * filter has been normalized to disjunctive normal form. Evaluation stops after the first matching variant, which may
+ * itself produce multiple payload rows, for example through a table-valued expansion.
+ */
+export interface CompiledEventSourceQuery {
+    /**
+     * Original SQL retained as a compatibility mirror for services using the legacy event evaluator. Compiled event
+     * evaluation uses the remaining fields.
+     */
+    sql: string;
+    sourceTable: ImplicitSchemaTablePattern;
+    variants: EventRowEvaluator[];
+}
+/**
+ * A row projection used by one normalized filter variant of an event payload query.
+ */
+export interface EventRowEvaluator extends RowProjection {
+}
 /**
  * A mapping describing how {@link StreamDataSource}s are combined into buckets.
  *
@@ -197,6 +228,15 @@ export interface StreamQuerier {
 export interface ColumnSqlParameterValue {
     column: string;
 }
+export type RowMetadataKind = 'schema' | 'table_name' | 'table_suffix';
+/**
+ * A value that resolves to metadata about the source table of the row being processed: the schema containing the
+ * table (`schema()`), the name of the table (`table_name()`) or, for wildcard table patterns, the matched
+ * suffix of the table name (`table_suffix()`).
+ */
+export interface RowMetadataSqlValue {
+    metadata: RowMetadataKind;
+}
 export type ConnectionParameterSource = 'auth' | 'subscription' | 'connection';
 /**
  * A value that resolves to either the current subscription parameters, the JWT of the connecting user or global
@@ -205,7 +245,7 @@ export type ConnectionParameterSource = 'auth' | 'subscription' | 'connection';
 export interface RequestSqlParameterValue {
     request: ConnectionParameterSource;
 }
-export type SqlParameterValue = ColumnSqlParameterValue | RequestSqlParameterValue | TableProcessorTableValuedFunctionOutput;
+export type SqlParameterValue = ColumnSqlParameterValue | RowMetadataSqlValue | RequestSqlParameterValue | TableProcessorTableValuedFunctionOutput;
 /**
  * A lookup returning multiple rows when instantiated.
  */

package/dist/sync_plan/plan_equality_serialized.d.ts

@@ -1,5 +1,5 @@
-import { Equality } from '../compiler/equality.js';
-import { SerializedBucketDataSource, SerializedDataSource, SerializedParameterIndexLookupCreator } from './serialize.js';
+import type { Equality } from '../compiler/equality.js';
+import type { SerializedBucketDataSource, SerializedDataSource, SerializedEventDescriptor, SerializedParameterIndexLookupCreator } from './serialize.js';
 export interface SerializedBucketDataSourceWithDataSources {
     bucket: SerializedBucketDataSource;
     dataSources: readonly SerializedDataSource[];
@@ -13,6 +13,16 @@ export interface SerializedBucketDataSourceWithDataSources {
  * These are only considered equal if the lookupName remains the same, so may be affected by changing order of queries.
  */
 export declare const serializedStreamParameterIndexLookupCreatorEquality: Equality<SerializedParameterIndexLookupCreator>;
+/**
+ * Equality for persisted replication events.
+ *
+ * Raw SQL is a rolling-upgrade compatibility mirror and cached evaluator hashes are not equality checks, so neither is
+ * part of event behavior. Payload queries are unordered because runtime evaluates every query matching the source
+ * table and treats the resulting payloads as an unordered collection. Normalized variants are unordered because they
+ * share a projection and only determine whether a row matches. The remaining serialized plan is a stable,
+ * self-contained behavior representation: Expression ASTs include both their shape and external-data bindings.
+ */
+export declare const serializedEventDefinitionEquality: Equality<SerializedEventDescriptor>;
 /**
  * SerializedBucketDataSource is not safe to compare _directly_, since it contains index references to SerializedDataSource
  * in the serialized sync plan. However, each SerializedDataSource is self-contained and safe to compare directly.

package/dist/sync_plan/plan_equality_serialized.js

@@ -7,6 +7,23 @@
  * These are only considered equal if the lookupName remains the same, so may be affected by changing order of queries.
  */
 export const serializedStreamParameterIndexLookupCreatorEquality = jsonEquality();
+/**
+ * Equality for persisted replication events.
+ *
+ * Raw SQL is a rolling-upgrade compatibility mirror and cached evaluator hashes are not equality checks, so neither is
+ * part of event behavior. Payload queries are unordered because runtime evaluates every query matching the source
+ * table and treats the resulting payloads as an unordered collection. Normalized variants are unordered because they
+ * share a projection and only determine whether a row matches. The remaining serialized plan is a stable,
+ * self-contained behavior representation: Expression ASTs include both their shape and external-data bindings.
+ */
+export const serializedEventDefinitionEquality = {
+    hash(hasher, value) {
+        hasher.addString(persistedJson(eventIdentity(value)));
+    },
+    equals(a, b) {
+        return a === b || persistedJson(eventIdentity(a)) == persistedJson(eventIdentity(b));
+    }
+};
 /**
  * SerializedBucketDataSource is not safe to compare _directly_, since it contains index references to SerializedDataSource
  * in the serialized sync plan. However, each SerializedDataSource is self-contained and safe to compare directly.
@@ -33,6 +50,45 @@ function bucketIdentity(value) {
         sources: bucket.sources.map((index) => JSON.stringify(dataSources[index])).sort()
     };
 }
+/**
+ * Builds a normalized identity for comparing serialized event descriptors from persisted sync plans.
+ *
+ * Raw SQL is excluded, while source queries and variants are sorted because their order does not affect event
+ * behavior.
+ */
+function eventIdentity(event) {
+    return {
+        name: event.name,
+        sourceQueries: event.sourceQueries
+            .map((query) => persistedJson({
+            table: query.table,
+            variants: query.variants.map((variant) => persistedJson(eventRowEvaluatorIdentity(variant))).sort()
+        }))
+            .sort()
+    };
+}
+/**
+ * Selects the behavioral fields used when comparing row evaluators within serialized event descriptors.
+ *
+ * The cached evaluator hash is deliberately omitted. Ordering inside an evaluator is retained conservatively so
+ * changes to projected column order or the compiler's filter-expression order invalidate persisted compatibility.
+ */
+function eventRowEvaluatorIdentity(evaluator) {
+    return {
+        table: evaluator.table,
+        tableValuedFunctions: evaluator.tableValuedFunctions,
+        filters: evaluator.filters,
+        partitionBy: evaluator.partitionBy,
+        columns: evaluator.columns
+    };
+}
+/**
+ * MongoDB persists undefined object properties as null. Treat the two forms as the same so a plan compares equal
+ * before and after it has been stored and loaded again.
+ */
+function persistedJson(value) {
+    return JSON.stringify(value, (_key, item) => (item === undefined ? null : item));
+}
 function jsonEquality() {
     return {
         hash(hasher, value) {

package/dist/sync_plan/plan_equality_serialized.js.map

@@ -1 +1 @@
-{"version":3,"file":"plan_equality_serialized.js","sourceRoot":"","sources":["../../src/sync_plan/plan_equality_serialized.ts"],"names":[],"mappings":"AAYA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mDAAmD,GAC9D,YAAY,EAAyC,CAAC;AAExD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,wCAAwC,GAAwD;IAC3G,IAAI,CAAC,MAAM,EAAE,KAAK;QAChB,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC1D,CAAC;IACD,MAAM,CAAC,CAAC,EAAE,CAAC;QACT,OAAO,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3F,CAAC;CACF,CAAC;AAEF,SAAS,cAAc,CAAC,KAAgD;IACtE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,KAAK,CAAC;IAEtC,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,6GAA6G;QAC7G,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE;KAClF,CAAC;AACJ,CAAC;AAED,SAAS,YAAY;IACnB,OAAO;QACL,IAAI,CAAC,MAAM,EAAE,KAAK;YAChB,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1C,CAAC;QACD,MAAM,CAAC,CAAC,EAAE,CAAC;YACT,OAAO,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QAC3D,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"plan_equality_serialized.js","sourceRoot":"","sources":["../../src/sync_plan/plan_equality_serialized.ts"],"names":[],"mappings":"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"}

package/dist/sync_plan/serialize.d.ts

@@ -1,6 +1,6 @@
 import { ParameterLookupDefinitionId } from '../HydrationState.js';
 import { SqlExpression } from './expression.js';
-import { ColumnSqlParameterValue, RequestSqlParameterValue, StreamOptions, SyncPlan, TableProcessorTableValuedFunction } from './plan.js';
+import { ColumnSqlParameterValue, RequestSqlParameterValue, RowMetadataSqlValue, StreamOptions, SyncPlan, TableProcessorTableValuedFunction } from './plan.js';
 /**
  * Serializes a sync plan into a simple JSON object.
  *
@@ -8,14 +8,40 @@ import { ColumnSqlParameterValue, RequestSqlParameterValue, StreamOptions, SyncP
  * queriers to bucket creators. To represent this efficiently, we assign numbers to referenced elements while
  * serializing instead of duplicating definitions.
  */
-export declare function serializeSyncPlan(plan: SyncPlan): SerializedSyncPlanV1;
+export declare function serializeSyncPlan(plan: SyncPlan): SerializedSyncPlan;
 export declare function deserializeSyncPlan(serialized: unknown): SyncPlan;
-export interface SerializedSyncPlanV1 {
-    version: number;
+/**
+ * Changes to {@link SerializedSyncPlan} require a version bump when older services would interpret the plan
+ * incorrectly. Optional additive fields are only safe without a bump when older readers can ignore them while another
+ * persisted representation preserves equivalent behavior.
+ *
+ * Compiled `events` are an explicit additive exception: service-core continues to persist raw event SQL alongside the
+ * plan for the legacy evaluator. Older readers ignore `events` and use that legacy mirror. Removing the mirror or
+ * relying on compiled-only event semantics will require a version bump.
+ *
+ * ### Version 2
+ *
+ * - Add {@link RowMetadataSqlValue} to data for row and parameter evaluators, exposing the exact table and schema name
+ *   when matching on wildcard table patterns.
+ *   The deserialization logic can remain the same for v1 and v2.
+ *
+ * ### Version 1
+ *
+ * - Initial version
+ */
+export type SerializedSyncPlanVersion = 1 | 2;
+export declare const maxSupportedSyncPlanVersion: SerializedSyncPlanVersion;
+export interface SerializedSyncPlan {
+    version: SerializedSyncPlanVersion;
     dataSources: SerializedDataSource[];
     buckets: SerializedBucketDataSource[];
     parameterIndexes: SerializedParameterIndexLookupCreator[];
     streams: SerializedStream[];
+    /**
+     * Optional additive compiled event definitions. Older readers safely ignore this because service-core dual-writes
+     * equivalent raw SQL in its legacy `eventDescriptors` field.
+     */
+    events?: SerializedEventDescriptor[];
 }
 export interface SerializedBucketDataSource {
     hash: number;
@@ -31,7 +57,7 @@ export interface SerializedTableProcessorTableValuedFunctionOutput {
     function: number;
     outputName: string;
 }
-export type SerializedTableProcessorData = ColumnSqlParameterValue | SerializedTableProcessorTableValuedFunctionOutput;
+export type SerializedTableProcessorData = ColumnSqlParameterValue | RowMetadataSqlValue | SerializedTableProcessorTableValuedFunctionOutput;
 export interface SerializedPartitionKey {
     expr: SqlExpression<SerializedTableProcessorData>;
 }
@@ -48,6 +74,29 @@ export interface SerializedDataSource {
     tableValuedFunctions: TableProcessorTableValuedFunction[];
     partitionBy: SerializedPartitionKey[];
 }
+export interface SerializedEventDescriptor {
+    name: string;
+    sourceQueries: SerializedEventSourceQuery[];
+}
+export interface SerializedEventSourceQuery {
+    /** Raw SQL retained for the legacy compatibility mirror. */
+    sql: string;
+    table: SerializedTablePattern;
+    variants: SerializedEventRowEvaluator[];
+}
+export interface SerializedEventRowEvaluator {
+    table: SerializedTablePattern;
+    /**
+     * The compiler's structural hash, retained only for round-trip symmetry with data sources (which reuse the same
+     * projection shape). It is not part of event identity (the compiler model compares behavior directly), and events
+     * are never deduplicated by it at runtime.
+     */
+    hash: number;
+    columns: SerializedColumnSource[];
+    filters: SqlExpression<SerializedTableProcessorData>[];
+    tableValuedFunctions: TableProcessorTableValuedFunction[];
+    partitionBy: SerializedPartitionKey[];
+}
 export interface SerializedParameterIndexLookupCreator {
     table: SerializedTablePattern;
     hash: number;

package/dist/sync_plan/serialize.js

@@ -1,19 +1,10 @@
 import { ImplicitSchemaTablePattern, TablePattern } from '../TablePattern.js';
 import { MapSourceVisitor, visitExpr } from './expression_visitor.js';
-/**
- * Serializes a sync plan into a simple JSON object.
- *
- * While {@link SyncPlan}s are already serializable for the most part, it contains a graph of references from e.g.
- * queriers to bucket creators. To represent this efficiently, we assign numbers to referenced elements while
- * serializing instead of duplicating definitions.
- */
-export function serializeSyncPlan(plan) {
-    const dataSourceIndex = new Map();
-    const bucketIndex = new Map();
-    const parameterIndex = new Map();
-    const expandingLookups = new Map();
+function createTableProcessorSerializer() {
     const addedTableValuedFunctions = new Map();
+    let usesRowMetadataSqlValue = false;
     const replaceFunctionReferenceWithIndex = new MapSourceVisitor((value) => {
+        usesRowMetadataSqlValue ||= 'metadata' in value;
         if ('function' in value) {
             return { function: addedTableValuedFunctions.get(value.function), outputName: value.outputName };
         }
@@ -34,7 +25,13 @@ export function serializeSyncPlan(plan) {
     function serializeTableValued(source) {
         return source.tableValuedFunctions.map((fn, i) => {
             addedTableValuedFunctions.set(fn, i);
-            return fn;
+            return {
+                functionName: fn.functionName,
+                functionInputs: fn.functionInputs.map(
+                // Since we don't support table-valued functions as inputs to other table-valued functions, this doesn't
+                // change expressions. It ensures we track row metadata use in any input, though.
+                (s) => serializeTableProcessorDataExpr(s))
+            };
         });
     }
     function translateParameters(source) {
@@ -42,6 +39,56 @@ export function serializeSyncPlan(plan) {
             return { expr: serializeTableProcessorDataExpr(key.expr) };
         });
     }
+    function serializeEventRowEvaluator(source) {
+        return {
+            hash: source.hashCode,
+            table: serializeTablePattern(source.sourceTable),
+            tableValuedFunctions: serializeTableValued(source),
+            filters: source.filters.map(serializeTableProcessorDataExpr),
+            partitionBy: translateParameters(source),
+            columns: source.columns.map((column) => {
+                if (column == 'star') {
+                    return 'star';
+                }
+                return { expr: serializeTableProcessorDataExpr(column.expr), alias: column.alias };
+            })
+        };
+    }
+    function serializeEventDefinition(event) {
+        return {
+            name: event.name,
+            sourceQueries: event.sourceQueries.map((query) => ({
+                sql: query.sql,
+                table: serializeTablePattern(query.sourceTable),
+                variants: query.variants.map(serializeEventRowEvaluator)
+            }))
+        };
+    }
+    return {
+        get usesRowMetadataSqlValue() {
+            return usesRowMetadataSqlValue;
+        },
+        serializeTableProcessorDataExpr,
+        serializeTablePattern,
+        serializeTableValued,
+        translateParameters,
+        serializeEventDefinition
+    };
+}
+/**
+ * Serializes a sync plan into a simple JSON object.
+ *
+ * While {@link SyncPlan}s are already serializable for the most part, it contains a graph of references from e.g.
+ * queriers to bucket creators. To represent this efficiently, we assign numbers to referenced elements while
+ * serializing instead of duplicating definitions.
+ */
+export function serializeSyncPlan(plan) {
+    const dataSourceIndex = new Map();
+    const bucketIndex = new Map();
+    const parameterIndex = new Map();
+    const expandingLookups = new Map();
+    const tableProcessorSerializer = createTableProcessorSerializer();
+    const { serializeTableProcessorDataExpr, serializeTablePattern, serializeTableValued, translateParameters } = tableProcessorSerializer;
     function serializeDataSources() {
         return plan.dataSources.map((source, i) => {
             dataSourceIndex.set(source, i);
@@ -72,7 +119,7 @@ export function serializeSyncPlan(plan) {
                 tableValuedFunctions: serializeTableValued(source),
                 filters: source.filters.map(serializeTableProcessorDataExpr),
                 partitionBy: translateParameters(source),
-                output: source.outputs.map((out) => visitExpr(replaceFunctionReferenceWithIndex, out, null)),
+                output: source.outputs.map(serializeTableProcessorDataExpr),
                 lookupScope: source.defaultLookupScope
             };
         });
@@ -124,8 +171,8 @@ export function serializeSyncPlan(plan) {
             sourceInstantiation: source.sourceInstantiation.map(serializeParameterValue)
         };
     }
-    return {
-        version: 1,
+    const events = plan.events.map(tableProcessorSerializer.serializeEventDefinition);
+    const serialized = {
         dataSources: serializeDataSources(),
         buckets: plan.buckets.map((bkt, index) => {
             bucketIndex.set(bkt, index);
@@ -139,13 +186,24 @@ export function serializeSyncPlan(plan) {
         streams: plan.streams.map((s) => ({
             stream: s.stream,
             queriers: s.queriers.map(serializeStreamQuerier)
-        }))
+        })),
+        version: tableProcessorSerializer.usesRowMetadataSqlValue ? 2 : 1
     };
+    // Compiled events are intentionally additive to plan versions 1 and 2. The service also persists their raw SQL in
+    // the legacy eventDescriptors field, so older readers can ignore this field and retain equivalent event behavior.
+    if (events.length != 0) {
+        serialized.events = events;
+    }
+    return serialized;
 }
 export function deserializeSyncPlan(serialized) {
-    if (serialized.version != 1) {
+    const { version } = serialized;
+    if (version < 1) {
         throw new Error('Unknown sync plan version passed to deserializeSyncPlan()');
     }
+    if (version > maxSupportedSyncPlanVersion) {
+        throw new Error(`Encountered a sync plan with version ${version}, the maximum supported version is ${maxSupportedSyncPlanVersion}. This can happen when the PowerSync service version is downgraded after deploying Sync Streams, consider upgrading or re-deploying.`);
+    }
     function deserializeTablePattern(pattern) {
         if (pattern.schema) {
             return new TablePattern(`${pattern.connection}.${pattern.schema}`, pattern.table);
@@ -210,6 +268,36 @@ export function deserializeSyncPlan(serialized) {
             defaultLookupScope: source.lookupScope
         };
     });
+    function deserializeEventRowEvaluator(source) {
+        const functions = (tableValuedFunctionsInScope = source.tableValuedFunctions);
+        return {
+            hashCode: source.hash,
+            sourceTable: deserializeTablePattern(source.table),
+            tableValuedFunctions: functions,
+            filters: source.filters.map(deserializeTableProcessorDataExpr),
+            parameters: deserializeParameters(source.partitionBy),
+            columns: source.columns.map((column) => {
+                if (column == 'star') {
+                    return 'star';
+                }
+                return { expr: deserializeTableProcessorDataExpr(column.expr), alias: column.alias };
+            })
+        };
+    }
+    if (plan.events != null && !Array.isArray(plan.events)) {
+        throw new Error('Compiled sync plan events must be an array.');
+    }
+    const serializedEvents = plan.events ?? [];
+    const events = serializedEvents.map((event) => {
+        return {
+            name: event.name,
+            sourceQueries: event.sourceQueries.map((query) => ({
+                sql: query.sql,
+                sourceTable: deserializeTablePattern(query.table),
+                variants: query.variants.map(deserializeEventRowEvaluator)
+            }))
+        };
+    });
     function deserializeParameterValue(stages, value) {
         switch (value.type) {
             case 'request':
@@ -268,7 +356,9 @@ export function deserializeSyncPlan(serialized) {
         dataSources,
         buckets,
         parameterIndexes,
-        streams
+        streams,
+        events
     };
 }
+export const maxSupportedSyncPlanVersion = 2;
 //# sourceMappingURL=serialize.js.map