@octaviaflow/flow-rules 0.21.0 → 0.23.0

package/README.md

@@ -50,8 +50,17 @@ const required = action?.inputSchema.fields.filter((f) => f.validation?.required
 
 // Does this flow work?
 const { isValid, errors, warnings } = validateWorkflow(nodes, edges);
+
+// With what the caller knows beyond the canvas (optional, 0.23.0+):
+validateWorkflow(nodes, edges, { connectorTypes: { [connectionId]: "salesforce" } });
 ```
 
+`connectorTypes` maps each connection id the flow uses to its connector type.
+With it, a Transform that upserts or updates into a target whose fallback key is
+its own record id (Salesforce, MongoDB, Shopify, Odoo, HubSpot objects other
+than contacts and companies), with no match field and no mapping that writes
+that id, gets a warning (DEV-646). Without it, that rule says nothing.
+
 ### The severity contract
 
 Unchanged from rules-v2 (DEV-220, ADR-flow-pause-and-rules-v2):

package/dist/catalog/general/transform/config.d.ts

@@ -67,6 +67,18 @@ export interface TransformUnwind {
     /** Keep a row whose list is empty, as one row with no element. Default false. */
     keepEmpty?: boolean;
 }
+/** How rows are written — the Transform panel's "Advanced options" (DEV-267/268). */
+export interface TransformWriteSettings {
+    /** Rows per write call. Empty = the connector's own default. */
+    batchSize?: number;
+    /** `continue` (default): failed rows are reported and the rest are written. `fail`: the step stops at the first failed row. */
+    onError?: 'continue' | 'fail';
+    /** Map and validate, write nothing. */
+    dryRun?: boolean;
+    /** Put the failed rows on the step's output. */
+    exposeFailedRows?: boolean;
+}
+export declare const TRANSFORM_ON_ERROR: readonly NonNullable<TransformWriteSettings['onError']>[];
 export type TransformMode = 'visual' | 'expression';
 /**
  * The authoring modes. `visual` is the Field Mapper and the only mode the panel
@@ -111,6 +123,8 @@ export interface TransformConfigType {
     groupBy?: TransformGroupBy;
     /** One row per element of a list on each row, before mapping (DEV-484). */
     unwind?: TransformUnwind;
+    /** How rows are written (the panel's "Advanced options", DEV-267/268). */
+    writeSettings?: TransformWriteSettings;
     /** Ordered column header names — the exact columns + header text written. */
     sheetHeaders?: string[];
     /** Create the target tab on first write if it doesn't exist (default true). */
@@ -139,6 +153,16 @@ export declare const TransformConfig: {
             options: readonly TransformOperation[];
             description: string;
         };
+        upsertMatchKey: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        writeSettings: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
         connectorId: {
             type: string;
             required: boolean;

package/dist/index.cjs

@@ -85,6 +85,7 @@ __export(exports_src, {
   ManualTriggerConfig: () => ManualTriggerConfig,
   NodeStatus: () => NodeStatus,
   ONEDRIVE_OPERATIONS: () => ONEDRIVE_OPERATIONS,
+  OWN_ID_MATCH_TARGETS: () => OWN_ID_MATCH_TARGETS,
   OneDriveActionConfig: () => OneDriveActionConfig,
   PLATFORM_CONFIG_KEYS: () => PLATFORM_CONFIG_KEYS,
   QUERY_AGGREGATE_FUNCTIONS: () => QUERY_AGGREGATE_FUNCTIONS,
@@ -107,6 +108,7 @@ __export(exports_src, {
   SortDirection: () => SortDirection,
   StorageActionConfig: () => StorageActionConfig,
   TRANSFORM_MODES: () => TRANSFORM_MODES,
+  TRANSFORM_ON_ERROR: () => TRANSFORM_ON_ERROR,
   TRANSFORM_OPERATIONS: () => TRANSFORM_OPERATIONS,
   TransformConfig: () => TransformConfig,
   USER_FUNCTION_PREFIX: () => USER_FUNCTION_PREFIX,
@@ -160,6 +162,7 @@ __export(exports_src, {
   storageConfigKeys: () => storageConfigKeys,
   storageOperations: () => storageOperations,
   summarizeConnectorTriggerEvents: () => summarizeConnectorTriggerEvents,
+  syncMatchKeyWarning: () => syncMatchKeyWarning,
   transformConnectionToEdge: () => transformConnectionToEdge,
   transformFlowToWorkflow: () => transformFlowToWorkflow,
   transformStepToNode: () => transformStepToNode,
@@ -3387,6 +3390,7 @@ var WhatsappSendConfig = {
 };
 
 // src/catalog/general/transform/config.ts
+var TRANSFORM_ON_ERROR = ["continue", "fail"];
 var TRANSFORM_MODES = ["visual", "expression"];
 var TRANSFORM_OPERATIONS = [
   { id: "upsert", label: "Upsert" },
@@ -3411,6 +3415,21 @@ function groupByErrors(config) {
   }
   return errors;
 }
+function writeSettingsErrors(config) {
+  const ws = config.writeSettings;
+  if (ws === undefined || ws === null)
+    return [];
+  if (typeof ws !== "object" || Array.isArray(ws))
+    return ["Write settings must be an object (writeSettings)"];
+  const errors = [];
+  if (ws.onError !== undefined && !isOneOf(TRANSFORM_ON_ERROR, ws.onError)) {
+    errors.push(`Write settings: onError must be one of: ${TRANSFORM_ON_ERROR.join(", ")} (got "${String(ws.onError)}")`);
+  }
+  if (ws.batchSize !== undefined && !(Number.isInteger(ws.batchSize) && ws.batchSize > 0)) {
+    errors.push(`Write settings: batchSize must be a whole number above 0 (got "${String(ws.batchSize)}")`);
+  }
+  return errors;
+}
 function unwindErrors(config) {
   const unwind = config.unwind;
   if (!unwind)
@@ -3452,6 +3471,16 @@ var TransformConfig = {
       options: TRANSFORM_OPERATION_IDS,
       description: "What to do with each mapped record at the target: upsert, insert, update or delete"
     },
+    upsertMatchKey: {
+      type: "text",
+      required: false,
+      description: "For upsert and update: the TARGET field that says which existing record a row is (DEV-646). A row whose value matches a record updates it; " + "no match creates one (upsert). Empty = the connector decides: Salesforce Id, MongoDB _id, the SQL primary key. " + "A sync that may run more than once must upsert on a key that is stable and unique for the SOURCE record, or every run creates the records again. " + "Salesforce: the key must be an External ID field on the object (describe_connector_object) — mapping a source id into a normal field is not enough, and " + 'without one the upsert fails with "External ID is not found in record". If the object has no External ID field for this source, say so and ask the person: ' + "they create one in Salesforce (for example a HubSpot Contact Id text field marked External ID and Unique), or choose insert knowing re-runs duplicate."
+    },
+    writeSettings: {
+      type: "json",
+      required: false,
+      description: 'How rows are written: { "batchSize"?: number, "onError"?: "continue" | "fail", "dryRun"?: boolean, "exposeFailedRows"?: boolean }. ' + 'onError "continue" (the default) writes every row it can and reports the failures (the run ends as partial success); "fail" stops the step at the first failed row. ' + "dryRun maps and validates without writing."
+    },
     connectorId: { type: "connection", required: true },
     database: {
       type: "text",
@@ -3473,7 +3502,7 @@ var TransformConfig = {
     mappings: {
       type: "array",
       required: false,
-      description: "Field mappings: [{ id, sourceField, targetField, targetType, transform? }]. sourceField is a token like {{orders[].email}}; " + "an index picks one list element ({{products[].variants[0].price}}). With groupBy, set lineField: true on the mappings that make each line. " + 'When the target field holds a record id but you have a reference (an email, SHOP-123), add lookup: { "object": "product.product", "matchField": "default_code" } — ' + "the write uses the id of the one record whose matchField equals the value; no match, or more than one, fails that row. Odoo and QuickBooks Online (e.g. CustomerRef.value → Customer by DisplayName; " + "Line.SalesItemLineDetail.ItemRef.value → Item by Name). A QuickBooks transaction upsert matches on DocNumber unless upsertMatchKey says otherwise."
+      description: "Field mappings: [{ id, sourceField, targetField, targetType, transform? }]. sourceField is a token like {{orders[].email}}; " + "targetField is the target app's own field name, normally one describe_connector_object lists; a name it does not list is written as given, so the field must exist in the target app (a custom field the person created). " + "A field the target requires (Salesforce Account Name) must be mapped, and a source value that can be empty needs a fallback or the row fails. " + "an index picks one list element ({{products[].variants[0].price}}). With groupBy, set lineField: true on the mappings that make each line. " + 'When the target field holds a record id but you have a reference (an email, SHOP-123), add lookup: { "object": "product.product", "matchField": "default_code" } — ' + "the write uses the id of the one record whose matchField equals the value; no match, or more than one, fails that row. Odoo and QuickBooks Online (e.g. CustomerRef.value → Customer by DisplayName; " + "Line.SalesItemLineDetail.ItemRef.value → Item by Name). A QuickBooks transaction upsert matches on DocNumber unless upsertMatchKey says otherwise."
     },
     groupBy: {
       type: "json",
@@ -3529,7 +3558,7 @@ var TransformConfig = {
         });
       }
     }
-    errors.push(...groupByErrors(config), ...unwindErrors(config));
+    errors.push(...groupByErrors(config), ...unwindErrors(config), ...writeSettingsErrors(config));
     return { valid: errors.length === 0, errors };
   },
   merge: (userConfig) => {
@@ -5266,9 +5295,52 @@ function contractValidationErrors(node) {
   }
 }
 
+// src/rules/syncMatchKey.ts
+var OWN_ID_MATCH_TARGETS = {
+  salesforce: {
+    app: "Salesforce",
+    idFields: ["Id"],
+    hint: "an External ID field on the object that holds the source record's id"
+  },
+  mongodb: { app: "MongoDB", idFields: ["_id"], hint: "a field that is unique for each source record" },
+  shopify: { app: "Shopify", idFields: ["id"], hint: "a field Shopify can look up, such as email, sku or handle" },
+  odoo: { app: "Odoo", idFields: ["id"], hint: "a field that is unique for each source record" },
+  hubspot: {
+    app: "HubSpot",
+    idFields: ["id", "hs_object_id"],
+    naturalKeyObjects: new Set(["contacts", "companies"]),
+    hint: "a property that is unique for each source record"
+  }
+};
+var MATCHING_OPERATIONS = new Set(["upsert", "update"]);
+var text = (v) => typeof v === "string" ? v.trim() : "";
+function syncMatchKeyWarning(node, connectorTypes) {
+  if (node.actionDefinitionId !== "transform" || !connectorTypes)
+    return null;
+  const config = node.config ?? {};
+  const operation = text(config.operation);
+  if (!MATCHING_OPERATIONS.has(operation))
+    return null;
+  if (text(config.upsertMatchKey))
+    return null;
+  if (text(config.mode) === "expression")
+    return null;
+  const connectionId = text(config.connectorId);
+  const target = connectionId ? OWN_ID_MATCH_TARGETS[connectorTypes[connectionId] ?? ""] : undefined;
+  if (!target)
+    return null;
+  if (target.naturalKeyObjects?.has(text(config.objectName).toLowerCase()))
+    return null;
+  const mappings = Array.isArray(config.mappings) ? config.mappings : [];
+  if (mappings.some((m) => target.idFields.includes(text(m?.targetField))))
+    return null;
+  const consequence = operation === "upsert" ? "the rows from another app don't carry it, so every run fails or, run as insert, creates the records again" : "the rows from another app don't carry it, so nothing is updated";
+  return `No match field: this ${operation} into ${target.app} matches on ${target.app}'s own record id, and ${consequence}. ` + `Set a match field (${target.hint}).`;
+}
+
 // src/rules/workflowValidator.ts
 var nodeName = (n) => n.label || n.id;
-function validateNode(node, allNodes, allEdges) {
+function validateNode(node, allNodes, allEdges, context = {}) {
   const errors = [];
   if (!node.id || node.id.trim().length === 0) {
     errors.push({
@@ -5323,6 +5395,16 @@ function validateNode(node, allNodes, allEdges) {
       nodeId: node.id
     });
   }
+  const syncKey = syncMatchKeyWarning(node, context.connectorTypes);
+  if (syncKey) {
+    errors.push({
+      id: `node-${node.id}-sync-key`,
+      type: "node",
+      severity: "warning",
+      message: syncKey,
+      nodeId: node.id
+    });
+  }
   const hasOutput = allEdges.some((edge) => edge.source === node.id);
   if (!hasOutput && node.type === "trigger") {
     errors.push({
@@ -5381,7 +5463,7 @@ function validateEdge(edge, allNodes, allEdges = []) {
   }
   return errors;
 }
-function validateWorkflow(nodes, edges) {
+function validateWorkflow(nodes, edges, context = {}) {
   const allErrors = [];
   const hasTrigger = nodes.some((node) => node.type === "trigger");
   if (!hasTrigger) {
@@ -5402,7 +5484,7 @@ function validateWorkflow(nodes, edges) {
     });
   }
   nodes.forEach((node) => {
-    const nodeErrors = validateNode(node, nodes, edges);
+    const nodeErrors = validateNode(node, nodes, edges, context);
     allErrors.push(...nodeErrors);
   });
   edges.forEach((edge) => {

package/dist/index.d.ts

@@ -20,7 +20,8 @@
  */
 export * from "./catalog/types";
 export { actionsRegistry, getAllActions, getActionById, getActionsByCategory, } from "./catalog/index";
-export { validateNode, validateEdge, validateWorkflow, getNodeValidationStatus, getEdgeValidationStatus, type ValidationError, type ValidationResult, } from "./rules/workflowValidator";
+export { validateNode, validateEdge, validateWorkflow, getNodeValidationStatus, getEdgeValidationStatus, type ValidationError, type ValidationResult, type ValidationContext, } from "./rules/workflowValidator";
+export { OWN_ID_MATCH_TARGETS, syncMatchKeyWarning } from "./rules/syncMatchKey";
 export { getNodeConfigStatus, missingContractRequired, contractValidationErrors, type NodeConfigStatus, type NodeConfigStatusResult, } from "./rules/nodeConfigStatus";
 export { generateWorkflowId, generateStepId, generateEdgeId, generateUUIDv4, } from "./ids";
 export { CONDITION_OPERATORS, ConditionConfig, type ConditionFilter, type ConditionOperator, } from "./catalog/logic/condition/config";
@@ -36,7 +37,7 @@ export { EmailConfig, } from "./catalog/communication/email-send/config";
 export { queryDefinition, } from "./catalog/general/query/index";
 export { isQueryableConnector, queryFieldsSatisfied, queryTablesSatisfied, validateBuildQueryConfig, validateVisualConfig, QUERY_AUTHORED_SQL_MESSAGE, QUERY_VISUAL_ONLY_MESSAGE, } from "./catalog/general/query/config";
 export { type BuildQueryConfig, type ColumnSchema, type CompiledQuery, type Condition, type ConditionGroup, type ConditionRow, type ConnectorSchema, isConditionGroup, MAX_CONDITION_DEPTH, QUERY_AGGREGATE_FUNCTIONS, QUERY_COMPARISON_OPERATORS, QUERY_CONDITION_OPERATORS, QUERY_MODES, QUERY_RELATIVE_DATE_OPERATORS, QUERY_TYPES, type QueryAggregate, type QueryAggregateFn, type QueryComparisonOperator, type QueryConditionOperator, type QueryExecutionResult, type QueryJoin, type QueryJoinOperator, type QuerySort, RELATIVE_DATE_DIRECTIONS, RELATIVE_DATE_MAX_AMOUNT, RELATIVE_DATE_UNITS, type RelativeDate, type RelativeDateDirection, type RelativeDateUnit, SortDirection, type VisualConfigV2, type VisualQueryConfig, } from "./catalog/general/query/types";
-export { DATABASE_CONNECTOR_IDS, type FieldMapping, TRANSFORM_MODES, TRANSFORM_OPERATIONS, TransformConfig, type TransformConfigType, type TransformGroupBy, type TransformLookup, type TransformUnwind, type TransformOperation, } from "./catalog/general/transform/config";
+export { DATABASE_CONNECTOR_IDS, type FieldMapping, TRANSFORM_MODES, TRANSFORM_ON_ERROR, TRANSFORM_OPERATIONS, TransformConfig, type TransformConfigType, type TransformGroupBy, type TransformLookup, type TransformUnwind, type TransformOperation, type TransformWriteSettings, } from "./catalog/general/transform/config";
 export { AGGREGATE_FUNCTIONS, AGGREGATE_FUNCTION_DESCRIPTIONS, AggregateConfig, type AggregateConfigType, type AggregateFn, type AggregateMetric, type AggregateSchemaNode, groupKeyName, } from "./catalog/general/aggregate/config";
 export { detectRecordFields, resolveRecordSchema, type RecordSchemaLike, } from "./catalog/logic/for-each/recordSchema";
 export { STORAGE_CONNECTOR_IDS, type StorageExtraField, type StoragePathField, getStorageProvider, storageConfigKeys, } from "./catalog/storage/storageCapabilities";

package/dist/index.js

@@ -3210,6 +3210,7 @@ var WhatsappSendConfig = {
 };
 
 // src/catalog/general/transform/config.ts
+var TRANSFORM_ON_ERROR = ["continue", "fail"];
 var TRANSFORM_MODES = ["visual", "expression"];
 var TRANSFORM_OPERATIONS = [
   { id: "upsert", label: "Upsert" },
@@ -3234,6 +3235,21 @@ function groupByErrors(config) {
   }
   return errors;
 }
+function writeSettingsErrors(config) {
+  const ws = config.writeSettings;
+  if (ws === undefined || ws === null)
+    return [];
+  if (typeof ws !== "object" || Array.isArray(ws))
+    return ["Write settings must be an object (writeSettings)"];
+  const errors = [];
+  if (ws.onError !== undefined && !isOneOf(TRANSFORM_ON_ERROR, ws.onError)) {
+    errors.push(`Write settings: onError must be one of: ${TRANSFORM_ON_ERROR.join(", ")} (got "${String(ws.onError)}")`);
+  }
+  if (ws.batchSize !== undefined && !(Number.isInteger(ws.batchSize) && ws.batchSize > 0)) {
+    errors.push(`Write settings: batchSize must be a whole number above 0 (got "${String(ws.batchSize)}")`);
+  }
+  return errors;
+}
 function unwindErrors(config) {
   const unwind = config.unwind;
   if (!unwind)
@@ -3275,6 +3291,16 @@ var TransformConfig = {
       options: TRANSFORM_OPERATION_IDS,
       description: "What to do with each mapped record at the target: upsert, insert, update or delete"
     },
+    upsertMatchKey: {
+      type: "text",
+      required: false,
+      description: "For upsert and update: the TARGET field that says which existing record a row is (DEV-646). A row whose value matches a record updates it; " + "no match creates one (upsert). Empty = the connector decides: Salesforce Id, MongoDB _id, the SQL primary key. " + "A sync that may run more than once must upsert on a key that is stable and unique for the SOURCE record, or every run creates the records again. " + "Salesforce: the key must be an External ID field on the object (describe_connector_object) — mapping a source id into a normal field is not enough, and " + 'without one the upsert fails with "External ID is not found in record". If the object has no External ID field for this source, say so and ask the person: ' + "they create one in Salesforce (for example a HubSpot Contact Id text field marked External ID and Unique), or choose insert knowing re-runs duplicate."
+    },
+    writeSettings: {
+      type: "json",
+      required: false,
+      description: 'How rows are written: { "batchSize"?: number, "onError"?: "continue" | "fail", "dryRun"?: boolean, "exposeFailedRows"?: boolean }. ' + 'onError "continue" (the default) writes every row it can and reports the failures (the run ends as partial success); "fail" stops the step at the first failed row. ' + "dryRun maps and validates without writing."
+    },
     connectorId: { type: "connection", required: true },
     database: {
       type: "text",
@@ -3296,7 +3322,7 @@ var TransformConfig = {
     mappings: {
       type: "array",
       required: false,
-      description: "Field mappings: [{ id, sourceField, targetField, targetType, transform? }]. sourceField is a token like {{orders[].email}}; " + "an index picks one list element ({{products[].variants[0].price}}). With groupBy, set lineField: true on the mappings that make each line. " + 'When the target field holds a record id but you have a reference (an email, SHOP-123), add lookup: { "object": "product.product", "matchField": "default_code" } — ' + "the write uses the id of the one record whose matchField equals the value; no match, or more than one, fails that row. Odoo and QuickBooks Online (e.g. CustomerRef.value → Customer by DisplayName; " + "Line.SalesItemLineDetail.ItemRef.value → Item by Name). A QuickBooks transaction upsert matches on DocNumber unless upsertMatchKey says otherwise."
+      description: "Field mappings: [{ id, sourceField, targetField, targetType, transform? }]. sourceField is a token like {{orders[].email}}; " + "targetField is the target app's own field name, normally one describe_connector_object lists; a name it does not list is written as given, so the field must exist in the target app (a custom field the person created). " + "A field the target requires (Salesforce Account Name) must be mapped, and a source value that can be empty needs a fallback or the row fails. " + "an index picks one list element ({{products[].variants[0].price}}). With groupBy, set lineField: true on the mappings that make each line. " + 'When the target field holds a record id but you have a reference (an email, SHOP-123), add lookup: { "object": "product.product", "matchField": "default_code" } — ' + "the write uses the id of the one record whose matchField equals the value; no match, or more than one, fails that row. Odoo and QuickBooks Online (e.g. CustomerRef.value → Customer by DisplayName; " + "Line.SalesItemLineDetail.ItemRef.value → Item by Name). A QuickBooks transaction upsert matches on DocNumber unless upsertMatchKey says otherwise."
     },
     groupBy: {
       type: "json",
@@ -3352,7 +3378,7 @@ var TransformConfig = {
         });
       }
     }
-    errors.push(...groupByErrors(config), ...unwindErrors(config));
+    errors.push(...groupByErrors(config), ...unwindErrors(config), ...writeSettingsErrors(config));
     return { valid: errors.length === 0, errors };
   },
   merge: (userConfig) => {
@@ -5089,9 +5115,52 @@ function contractValidationErrors(node) {
   }
 }
 
+// src/rules/syncMatchKey.ts
+var OWN_ID_MATCH_TARGETS = {
+  salesforce: {
+    app: "Salesforce",
+    idFields: ["Id"],
+    hint: "an External ID field on the object that holds the source record's id"
+  },
+  mongodb: { app: "MongoDB", idFields: ["_id"], hint: "a field that is unique for each source record" },
+  shopify: { app: "Shopify", idFields: ["id"], hint: "a field Shopify can look up, such as email, sku or handle" },
+  odoo: { app: "Odoo", idFields: ["id"], hint: "a field that is unique for each source record" },
+  hubspot: {
+    app: "HubSpot",
+    idFields: ["id", "hs_object_id"],
+    naturalKeyObjects: new Set(["contacts", "companies"]),
+    hint: "a property that is unique for each source record"
+  }
+};
+var MATCHING_OPERATIONS = new Set(["upsert", "update"]);
+var text = (v) => typeof v === "string" ? v.trim() : "";
+function syncMatchKeyWarning(node, connectorTypes) {
+  if (node.actionDefinitionId !== "transform" || !connectorTypes)
+    return null;
+  const config = node.config ?? {};
+  const operation = text(config.operation);
+  if (!MATCHING_OPERATIONS.has(operation))
+    return null;
+  if (text(config.upsertMatchKey))
+    return null;
+  if (text(config.mode) === "expression")
+    return null;
+  const connectionId = text(config.connectorId);
+  const target = connectionId ? OWN_ID_MATCH_TARGETS[connectorTypes[connectionId] ?? ""] : undefined;
+  if (!target)
+    return null;
+  if (target.naturalKeyObjects?.has(text(config.objectName).toLowerCase()))
+    return null;
+  const mappings = Array.isArray(config.mappings) ? config.mappings : [];
+  if (mappings.some((m) => target.idFields.includes(text(m?.targetField))))
+    return null;
+  const consequence = operation === "upsert" ? "the rows from another app don't carry it, so every run fails or, run as insert, creates the records again" : "the rows from another app don't carry it, so nothing is updated";
+  return `No match field: this ${operation} into ${target.app} matches on ${target.app}'s own record id, and ${consequence}. ` + `Set a match field (${target.hint}).`;
+}
+
 // src/rules/workflowValidator.ts
 var nodeName = (n) => n.label || n.id;
-function validateNode(node, allNodes, allEdges) {
+function validateNode(node, allNodes, allEdges, context = {}) {
   const errors = [];
   if (!node.id || node.id.trim().length === 0) {
     errors.push({
@@ -5146,6 +5215,16 @@ function validateNode(node, allNodes, allEdges) {
       nodeId: node.id
     });
   }
+  const syncKey = syncMatchKeyWarning(node, context.connectorTypes);
+  if (syncKey) {
+    errors.push({
+      id: `node-${node.id}-sync-key`,
+      type: "node",
+      severity: "warning",
+      message: syncKey,
+      nodeId: node.id
+    });
+  }
   const hasOutput = allEdges.some((edge) => edge.source === node.id);
   if (!hasOutput && node.type === "trigger") {
     errors.push({
@@ -5204,7 +5283,7 @@ function validateEdge(edge, allNodes, allEdges = []) {
   }
   return errors;
 }
-function validateWorkflow(nodes, edges) {
+function validateWorkflow(nodes, edges, context = {}) {
   const allErrors = [];
   const hasTrigger = nodes.some((node) => node.type === "trigger");
   if (!hasTrigger) {
@@ -5225,7 +5304,7 @@ function validateWorkflow(nodes, edges) {
     });
   }
   nodes.forEach((node) => {
-    const nodeErrors = validateNode(node, nodes, edges);
+    const nodeErrors = validateNode(node, nodes, edges, context);
     allErrors.push(...nodeErrors);
   });
   edges.forEach((edge) => {
@@ -6221,6 +6300,7 @@ export {
   ManualTriggerConfig,
   NodeStatus,
   ONEDRIVE_OPERATIONS,
+  OWN_ID_MATCH_TARGETS,
   OneDriveActionConfig,
   PLATFORM_CONFIG_KEYS,
   QUERY_AGGREGATE_FUNCTIONS,
@@ -6243,6 +6323,7 @@ export {
   SortDirection,
   StorageActionConfig,
   TRANSFORM_MODES,
+  TRANSFORM_ON_ERROR,
   TRANSFORM_OPERATIONS,
   TransformConfig,
   USER_FUNCTION_PREFIX,
@@ -6296,6 +6377,7 @@ export {
   storageConfigKeys,
   storageOperations,
   summarizeConnectorTriggerEvents,
+  syncMatchKeyWarning,
   transformConnectionToEdge,
   transformFlowToWorkflow,
   transformStepToNode,

package/dist/rules/syncMatchKey.d.ts

@@ -0,0 +1,48 @@
+/**
+ * An upsert or update with nothing to match on (DEV-646).
+ *
+ * Prod, 2026-11-09: a HubSpot → Salesforce "sync" built over the MCP set no
+ * match field. The upsert failed ("External ID is not found in record"); run
+ * as insert instead, every run created all 140 Accounts again.
+ *
+ * With no `upsertMatchKey`, the Engine's writer falls back to a key of its
+ * own. For some targets that key is the target record's OWN id, which rows
+ * coming from another app never carry unless a mapping writes it. Those are
+ * the targets this rule warns about, mirroring the Engine:
+ *
+ *   salesforce  `Id`          writeToSalesforce: matchKey || externalIdField || 'Id'
+ *   mongodb     `_id`         writeToMongoDB:    matchKey || '_id'
+ *   shopify     `id`          isShopifyIdKey:    no key = PUT by id
+ *   odoo        `id`          writeToOdoo:       matchKey || 'id'
+ *   hubspot     own id        writeToHubSpot:    matchKey || email (contacts) / domain (companies) || record id
+ *
+ * Silent, because the fallback is a natural key or can't be known here:
+ * QuickBooks (DocNumber / DisplayName), HubSpot contacts and companies, the
+ * SQL targets and Snowflake (the primary key), and the OData targets (SAP,
+ * Business Central, D365 F&O), whose entity key comes from live metadata.
+ *
+ * The rule needs to know which app a connection is. A Transform's
+ * `connectorId` is a connection (instance) id, so the caller passes
+ * `connectorTypes` (connection id → connector type). Without it, or for a
+ * connection it doesn't list, the rule says nothing.
+ */
+import type { WorkflowNode } from '../catalog/workflow';
+interface OwnIdTarget {
+    /** How the app is named in the message. */
+    readonly app: string;
+    /** Target field names that ARE the record's own id: a mapping to one supplies the match. */
+    readonly idFields: readonly string[];
+    /** Objects whose writer falls back to a natural key instead (lower case). */
+    readonly naturalKeyObjects?: ReadonlySet<string>;
+    /** What to use as the match field, said in the app's terms. */
+    readonly hint: string;
+}
+/** Connector types whose upsert/update, with no match field, matches on the target record's own id. */
+export declare const OWN_ID_MATCH_TARGETS: Readonly<Record<string, OwnIdTarget>>;
+/**
+ * The warning for a Transform that upserts or updates into a target whose
+ * fallback is its own record id, with no match field set and no mapping that
+ * writes that id. `null` when there is nothing to say.
+ */
+export declare function syncMatchKeyWarning(node: WorkflowNode, connectorTypes: Readonly<Record<string, string>> | undefined): string | null;
+export {};

package/dist/rules/workflowValidator.d.ts

@@ -16,6 +16,17 @@
  *             ("won't run" orphans, multi-flow canvas, duplicate edges).
  */
 import { WorkflowNode, WorkflowEdge } from '../catalog/workflow';
+/**
+ * What the caller knows beyond the canvas. Every field is optional: a rule
+ * that needs one says nothing without it.
+ */
+export interface ValidationContext {
+    /**
+     * Connection (instance) id → connector type (`salesforce`, `mongodb`, …),
+     * for the connections the flow's steps use (DEV-646).
+     */
+    connectorTypes?: Readonly<Record<string, string>>;
+}
 export interface ValidationError {
     id: string;
     type: 'node' | 'edge' | 'workflow';
@@ -32,7 +43,7 @@ export interface ValidationResult {
 /**
  * Validate a single node.
  */
-export declare function validateNode(node: WorkflowNode, allNodes: WorkflowNode[], allEdges: WorkflowEdge[]): ValidationError[];
+export declare function validateNode(node: WorkflowNode, allNodes: WorkflowNode[], allEdges: WorkflowEdge[], context?: ValidationContext): ValidationError[];
 /**
  * Validate a single edge. `allEdges` powers real duplicate detection —
  * only the SECOND-and-later instance of a duplicate is flagged, so one
@@ -42,7 +53,7 @@ export declare function validateEdge(edge: WorkflowEdge, allNodes: WorkflowNode[
 /**
  * Validate entire workflow.
  */
-export declare function validateWorkflow(nodes: WorkflowNode[], edges: WorkflowEdge[]): ValidationResult;
+export declare function validateWorkflow(nodes: WorkflowNode[], edges: WorkflowEdge[], context?: ValidationContext): ValidationResult;
 /**
  * Get validation status for a specific node
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octaviaflow/flow-rules",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "The flow action catalog and the rules engine behind Flow Doctor \u2014 one definition of what a step accepts and what makes a flow valid, shared by the editor and the server",
   "type": "module",
   "main": "./dist/index.cjs",