@reventlessdev/reventless-aws 3.0.0-alpha.171 → 3.0.0-alpha.173

package/src/adapter/Runtime/AggregateRuntime_Builder_Single.res.mjs

@@ -187,7 +187,7 @@ function finish() {
       }));
       let match = Util_Bundle$ReventlessAws.buildCodeArchive("@reventlessdev/reventless-aws/src/adapter/Runtime/AggregateEntryPoint.mjs", packageDirs, undefined);
       Stdlib_Option.forEach(cfg.sqsBatchSize, CommandTopicChannel_SQS_Sync$ReventlessAws.setBatchSize);
-      let runtime = RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset("AllAggregatesCmdHandler", match.code, match.sourceCodeHash, envVars, cfg.memorySize, cfg.timeout, cfg.reservedConcurrency, cfg.ephemeralStorageMb, cfg.logRetentionDays, undefined, opts);
+      let runtime = RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset("AllAggregatesCmdHandler", match.code, match.sourceCodeHash, envVars, cfg.memorySize, cfg.timeout, cfg.reservedConcurrency, cfg.ephemeralStorageMb, cfg.logRetentionDays, undefined, undefined, opts);
       let tableName$1 = pluginRmTableName.contents;
       if (tableName$1 !== undefined) {
         Pulumi.all([

package/src/adapter/Runtime/AggregateRuntime_Builder_Single_Async.res.mjs

@@ -174,7 +174,7 @@ function finish() {
       }));
       let match = Util_Bundle$ReventlessAws.buildCodeArchive("@reventlessdev/reventless-aws/src/adapter/Runtime/AggregateEntryPoint.mjs", packageDirs, undefined);
       Stdlib_Option.forEach(cfg.sqsBatchSize, CommandTopicChannel_SQS_Async$ReventlessAws.setBatchSize);
-      let runtime = RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset("AllAggregatesAsyncCmdHandler", match.code, match.sourceCodeHash, envVars, cfg.memorySize, cfg.timeout, cfg.reservedConcurrency, cfg.ephemeralStorageMb, cfg.logRetentionDays, undefined, opts);
+      let runtime = RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset("AllAggregatesAsyncCmdHandler", match.code, match.sourceCodeHash, envVars, cfg.memorySize, cfg.timeout, cfg.reservedConcurrency, cfg.ephemeralStorageMb, cfg.logRetentionDays, undefined, undefined, opts);
       specs.forEach(param => {
         param.connects.forEach(connect => connect(runtime));
       });

package/src/adapter/Runtime/AutomationSliceRuntime_Builder_Single.res.mjs

@@ -116,7 +116,7 @@ function finish() {
       let envVars = {};
       envVars["HANDLER_CONFIG"] = handlerConfigOutput;
       let match$1 = Util_Bundle$ReventlessAws.buildCodeArchive("@reventlessdev/reventless-aws/src/adapter/Runtime/AutomationSliceEntryPoint.mjs", packageDirs, undefined);
-      let runtime = RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset("AllAutomationSlices", match$1.code, match$1.sourceCodeHash, envVars, match[0], match[1], undefined, undefined, undefined, undefined, opts);
+      let runtime = RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset("AllAutomationSlices", match$1.code, match$1.sourceCodeHash, envVars, match[0], match[1], undefined, undefined, undefined, undefined, undefined, opts);
       let channelSpecs = storedSpecs.map(param => param.channelSpec);
       EventCollectorChannel_DynamoDbStream$ReventlessAws.connect("AllAutomationSlices", channelSpecs, runtime, opts);
     } else {

package/src/adapter/Runtime/DcbCommandTopicEntryPoint.mjs

@@ -22,6 +22,7 @@ import { makeGenerateCommand } from "@reventlessdev/reventless-core/src/componen
 import { commandOutcomeToJson, runInlineAndCollect } from "@reventlessdev/reventless-core/src/components/CommandTopic/CommandTopic_Helpers.res.mjs";
 import { json as jsonSchema } from "sury/src/S.res.mjs";
 import { read, append, readStream } from "@reventlessdev/reventless-aws/src/adapter/DcbEventLog/DcbEventLogStorage_DynamoDb_Runtime.res.mjs";
+import { opsFor as pgDcbEventLogOpsFor } from "@reventlessdev/reventless-aws/src/adapter/DcbEventLog/DcbEventLogStorage_Postgres_Runtime.res.mjs";
 import { handleQueueEvent, publishJsons as sqsPublishJsons } from "@reventlessdev/reventless-aws/src/adapter/CommandTopic/CommandTopicChannel_SQS_Runtime.res.mjs";
 
 const dynamicImport = (specifier) => import('/var/task/node_modules/' + specifier);
@@ -90,12 +91,25 @@ function getIdStringSchema() {
 // can drive the real `cmdGenHandler` end-to-end against DynamoDB Local.
 export async function buildHandlersForConfig(config, opts = {}) {
   const loadModule = opts.loadModule ?? dynamicImport;
-  const resolvedTable = { name: config.dcbEventLogTableName };
-  const rawStorageOps = {
-    read: read(resolvedTable),
-    append: append(resolvedTable),
-    readStream: readStream(resolvedTable),
-  };
+  // `pgConnection`, when present in HANDLER_CONFIG, selects the Postgres DCB
+  // runtime (dcbEventLogTableName doubles as the `dcb_event.log_name`); absence
+  // keeps the DynamoDB path byte-identical. NB: this swaps only the *storage*
+  // ops — event propagation (within-plugin projections + cross-plugin SNS) is
+  // stream-driven on AWS and is handled separately by the change-feed relay
+  // (see docs/plans/aws-postgres-change-feed-bridge.md), not by this Lambda.
+  const rawStorageOps = config.pgConnection
+    ? (() => {
+        const pgOps = pgDcbEventLogOpsFor(config.pgConnection, config.dcbEventLogTableName);
+        return { read: pgOps.read, append: pgOps.append, readStream: pgOps.readStream };
+      })()
+    : (() => {
+        const resolvedTable = { name: config.dcbEventLogTableName };
+        return {
+          read: read(resolvedTable),
+          append: append(resolvedTable),
+          readStream: readStream(resolvedTable),
+        };
+      })();
 
   const handlersByType = {};
   const sharedDcbEventLogOps = dcbEventLogOperationsMake({

package/src/adapter/Runtime/EventCollectorRuntime_Builder_PerEventCollector.res.mjs

@@ -61,7 +61,7 @@ function forEventCollector(param, eventTopics, resources, memorySizeOpt, timeout
   packageDirs[specPkg] = Util_Bundle$ReventlessAws.resolvePackageRoot(specPkg);
   packageDirs[mappingsPkg] = Util_Bundle$ReventlessAws.resolvePackageRoot(mappingsPkg);
   let match = Util_Bundle$ReventlessAws.buildCodeArchive("@reventlessdev/reventless-aws/src/adapter/Runtime/ReadModelEntryPoint.mjs", packageDirs, undefined);
-  let runtime = RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset(name, match.code, match.sourceCodeHash, envVars, memorySize, timeout, undefined, undefined, undefined, undefined, opts);
+  let runtime = RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset(name, match.code, match.sourceCodeHash, envVars, memorySize, timeout, undefined, undefined, undefined, undefined, undefined, opts);
   EventCollectorChannel_DynamoDbStream$ReventlessAws.connect(name, [{
       channel: channel,
       eventTopics: eventTopics,

package/src/adapter/Runtime/EventCollectorRuntime_Builder_Single.res.mjs

@@ -108,7 +108,7 @@ function finish() {
       let envVars = {};
       envVars["HANDLER_CONFIG"] = handlerConfigOutput;
       let match$1 = Util_Bundle$ReventlessAws.buildCodeArchive("@reventlessdev/reventless-aws/src/adapter/Runtime/ReadModelEntryPoint.mjs", packageDirs, undefined);
-      let runtime = RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset("AllReadModels", match$1.code, match$1.sourceCodeHash, envVars, match[0], match[1], undefined, undefined, undefined, undefined, opts);
+      let runtime = RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset("AllReadModels", match$1.code, match$1.sourceCodeHash, envVars, match[0], match[1], undefined, undefined, undefined, undefined, undefined, opts);
       let channelSpecs = storedSpecs.map(param => param.channelSpec);
       EventCollectorChannel_DynamoDbStream$ReventlessAws.connect("AllReadModels", channelSpecs, runtime, opts);
     } else {

package/src/adapter/Runtime/ExtensionPointRuntime_Builder_PerExtensionPoint.res.mjs

@@ -39,7 +39,7 @@ function forCommandTopic(param, connect, memorySizeOpt, timeoutOpt, specModuleUr
   packageDirs[specPkg] = Util_Bundle$ReventlessAws.resolvePackageRoot(specPkg);
   packageDirs[mappingsPkg] = Util_Bundle$ReventlessAws.resolvePackageRoot(mappingsPkg);
   let match = Util_Bundle$ReventlessAws.buildCodeArchive("@reventlessdev/reventless-aws/src/adapter/Runtime/ExtensionPointEntryPoint.mjs", packageDirs, undefined);
-  return connect(RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset(name, match.code, match.sourceCodeHash, envVars, memorySize, timeout, undefined, undefined, undefined, undefined, opts));
+  return connect(RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset(name, match.code, match.sourceCodeHash, envVars, memorySize, timeout, undefined, undefined, undefined, undefined, undefined, opts));
 }
 
 function finish() {

package/src/adapter/Runtime/PgChangeFeedRelayEntryPoint.mjs

@@ -0,0 +1,52 @@
+// PgChangeFeedRelay Lambda entry point (scheduled poll — B2.3).
+//
+// Triggered on a schedule (EventBridge rate rule). Each invocation drains every
+// Postgres DCB log listed in HANDLER_CONFIG from its checkpoint and relays the
+// events, transformed into the {id, meta, event} shape, onto the plugin
+// EventCollector SQS queue — which then fans out to projections, aggregate
+// command topics, and the cross-plugin SNS EventTopic.
+// See docs/plans/aws-postgres-change-feed-bridge.md.
+//
+// HANDLER_CONFIG shape:
+//   { "logs": [ { "pgConnection": {host,port,database,username,secretArn},
+//                 "logName": string,          // dcb_event.log_name
+//                 "subscriber": string,        // dcb_subscription checkpoint key
+//                 "targetQueueUrl": string,    // plugin EventCollector SQS URL
+//                 "partitionTag"?: <derivedPartitionTag> } ] }
+
+import { relay } from "@reventlessdev/reventless-aws/src/adapter/Postgres/PgChangeFeedRelay_Runtime.res.mjs";
+import { sendMessage } from "@reventlessdev/reventless-aws/src/util/Util_SQS_Runtime.res.mjs";
+import { makeQueueRef, log } from "./HandlerFactoryHelpers.mjs";
+
+// Standard (non-FIFO) EventCollector queue — no message group id needed. The
+// SQS handler parses each body straight back to JSON (Util_SQS_Runtime.parseSqsRecord).
+function makeSendBatch(targetQueueUrl) {
+  const queue = makeQueueRef(targetQueueUrl);
+  return (jsons) =>
+    Promise.all(jsons.map((json) => sendMessage(queue, undefined, JSON.stringify(json)))).then(
+      () => {}
+    );
+}
+
+export async function handler(_event, _context) {
+  const configStr = process.env["HANDLER_CONFIG"] || '{"logs":[]}';
+  const config = JSON.parse(configStr);
+  const logs = config.logs || [];
+
+  await Promise.all(
+    logs.map(async (l) => {
+      const sendBatch = makeSendBatch(l.targetQueueUrl);
+      try {
+        const count = await relay(l.pgConnection, l.logName, l.subscriber, l.partitionTag, sendBatch);
+        log.debug("relayed " + count + " event(s) for " + l.logName, { comp: "PgChangeFeedRelay" });
+      } catch (err) {
+        // Log and continue — a failed log this tick is retried next tick from its
+        // unchanged checkpoint (at-least-once; projections are idempotent).
+        log.warn("relay failed for " + l.logName + ": " + (err?.message ?? String(err)), {
+          comp: "PgChangeFeedRelay",
+        });
+      }
+    })
+  );
+  return "";
+}

package/src/adapter/Runtime/RuntimeEnvironment_Lambda.res

@@ -78,6 +78,11 @@ let makeFromCodeAsset: (
       Lambda's log group (command-handler Lambdas only). Requires a managed log
       group, so it only takes effect when `~logRetentionDays` is also set. */
   ~dcbMetrics: bool=?,
+  /** Place the Lambda in a VPC (needed to reach RDS/managed Postgres). When set,
+      the execution role also gets the EC2 network-interface permissions AWS
+      requires for VPC Lambdas. Build it from `PgConnection.{securityGroupId,
+      subnetIds}`. */
+  ~vpcConfig: Pulumi.Input.t<PulumiAws.Lambda.Function.vpcConfig>=?,
   ~opts: Pulumi.ComponentResource.options=?,
 ) => ReventlessCore.Runtime.environment<parts> = (
   ~name,
@@ -90,6 +95,7 @@ let makeFromCodeAsset: (
   ~ephemeralStorageMb=?,
   ~logRetentionDays=?,
   ~dcbMetrics=false,
+  ~vpcConfig=?,
   ~opts=?,
 ) => {
   open PulumiAws
@@ -102,6 +108,37 @@ let makeFromCodeAsset: (
     ~opts?,
   )
 
+  // VPC Lambdas must be able to manage ENIs in the target subnets. Attach the
+  // standard EC2 network-interface permissions (resource "*", as ENIs have no
+  // predictable ARN) whenever the function is VPC-placed.
+  vpcConfig->Option.forEach(_ => {
+    let _ = PulumiAws.IAM.RolePolicy.make(
+      ~name=`${name}VpcAccess`,
+      ~args={
+        policy: PolicyDocument.make(
+          ~id=`${name}VpcAccessPolicy`,
+          ~statements=[
+            {
+              sid: "AllowVpcEni",
+              effect: Allow,
+              actions: Actions([
+                "ec2:CreateNetworkInterface",
+                "ec2:DescribeNetworkInterfaces",
+                "ec2:DeleteNetworkInterface",
+                "ec2:AssignPrivateIpAddresses",
+                "ec2:UnassignPrivateIpAddresses",
+              ]),
+              resources: Resource("*"),
+            },
+          ],
+        )
+        ->PolicyDocument.toJsonString
+        ->Pulumi.Input.make,
+        role: lambdaRole.id->Pulumi.Output.asInput,
+      },
+    )
+  })
+
   // Create additional IAM policies registered by consumers.
   additionalIamPolicies->Array.forEach(({suffix, actions, resourceArn}) => {
     let _ = resourceArn->Pulumi.Output.apply(arn => {
@@ -160,6 +197,7 @@ let makeFromCodeAsset: (
       ),
       layers,
       tags,
+      vpcConfig: ?vpcConfig,
       environment: ({Lambda.Function.variables: variables}: Lambda.Function.functionEnvironment)
         ->Pulumi.Input.make,
     },

package/src/adapter/Runtime/RuntimeEnvironment_Lambda.res.mjs

@@ -41,13 +41,30 @@ function make(name, handler, memorySizeOpt, timeoutOpt, opts) {
   };
 }
 
-function makeFromCodeAsset(name, code, sourceCodeHash, envVarsOpt, memorySizeOpt, timeoutOpt, reservedConcurrency, ephemeralStorageMb, logRetentionDays, dcbMetricsOpt, opts) {
+function makeFromCodeAsset(name, code, sourceCodeHash, envVarsOpt, memorySizeOpt, timeoutOpt, reservedConcurrency, ephemeralStorageMb, logRetentionDays, dcbMetricsOpt, vpcConfig, opts) {
   let envVars = envVarsOpt !== undefined ? envVarsOpt : ({});
   let memorySize = memorySizeOpt !== undefined ? memorySizeOpt : Runtime$ReventlessCore.CommandHandlerDefaults.memorySize;
   let timeout = timeoutOpt !== undefined ? timeoutOpt : Runtime$ReventlessCore.CommandHandlerDefaults.timeout;
   let dcbMetrics = dcbMetricsOpt !== undefined ? dcbMetricsOpt : false;
   let opts$1 = Stdlib_Option.map(opts, Util_Pulumi$ReventlessCore.ComponentResourceOptions.toCustomResourceOptions);
   let lambdaRole = IAM$PulumiAws.Role.makeWithDefaultPolicy(name, Pulumi.output(AWS$ReventlessAws.Lambda.principal), opts$1);
+  Stdlib_Option.forEach(vpcConfig, param => {
+    new (Aws.iam.RolePolicy)(name + `VpcAccess`, {
+      policy: PolicyDocument$PulumiAws.toJsonString(PolicyDocument$PulumiAws.make(undefined, name + `VpcAccessPolicy`, [{
+          Sid: "AllowVpcEni",
+          Effect: "Allow",
+          Action: [
+            "ec2:CreateNetworkInterface",
+            "ec2:DescribeNetworkInterfaces",
+            "ec2:DeleteNetworkInterface",
+            "ec2:AssignPrivateIpAddresses",
+            "ec2:UnassignPrivateIpAddresses"
+          ],
+          Resource: "*"
+        }])),
+      role: lambdaRole.id
+    });
+  });
   additionalIamPolicies.forEach(param => {
     let actions = param.actions;
     let suffix = param.suffix;
@@ -91,7 +108,8 @@ function makeFromCodeAsset(name, code, sourceCodeHash, envVarsOpt, memorySizeOpt
     reservedConcurrentExecutions: Stdlib_Option.map(reservedConcurrency, prim => prim),
     ephemeralStorage: Stdlib_Option.map(ephemeralStorageMb, mb => ({
       size: mb
-    }))
+    })),
+    vpcConfig: vpcConfig
   }, opts$1 !== undefined ? Primitive_option.valFromOption(opts$1) : undefined);
   Stdlib_Option.forEach(logRetentionDays, days => {
     let logGroup = new (Aws.cloudwatch.LogGroup)(name + `LogGroup`, {

package/src/adapter/Runtime/SideEffectHandlerRuntime_Builder_Single.res.mjs

@@ -100,7 +100,7 @@ function finish() {
       let envVars = {};
       envVars["HANDLER_CONFIG"] = handlerConfigOutput;
       let match$1 = Util_Bundle$ReventlessAws.buildCodeArchive("@reventlessdev/reventless-aws/src/adapter/Runtime/SideEffectEntryPoint.mjs", packageDirs, undefined);
-      let runtime = RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset("AllSideEffectHandlers", match$1.code, match$1.sourceCodeHash, envVars, match[0], match[1], undefined, undefined, undefined, undefined, opts);
+      let runtime = RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset("AllSideEffectHandlers", match$1.code, match$1.sourceCodeHash, envVars, match[0], match[1], undefined, undefined, undefined, undefined, undefined, opts);
       let channelSpecs = storedSpecs.map(param => param.channelSpec);
       EventCollectorChannel_DynamoDbStream$ReventlessAws.connect("AllSideEffectHandlers", channelSpecs, runtime, opts);
     } else {

package/src/adapter/Runtime/StateChangeSliceRuntime_Builder_Single.res.mjs

@@ -66,7 +66,7 @@ function forDcbCommandTopic(slicePaths, dcbTableName, pluginName, syncConfig, as
   packageDirs["@reventlessdev/reventless-core"] = Util_Bundle$ReventlessAws.resolvePackageRoot("@reventlessdev/reventless-core");
   let match = Util_Bundle$ReventlessAws.buildCodeArchive("@reventlessdev/reventless-aws/src/adapter/Runtime/DcbCommandTopicEntryPoint.mjs", packageDirs, undefined);
   Stdlib_Option.forEach(cfg.sqsBatchSize, CommandTopicChannel_SQS$ReventlessAws.setBatchSize);
-  let runtime = RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset(name, match.code, match.sourceCodeHash, envVars, cfg.memorySize, cfg.timeout, cfg.reservedConcurrency, cfg.ephemeralStorageMb, cfg.logRetentionDays, true, opts);
+  let runtime = RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset(name, match.code, match.sourceCodeHash, envVars, cfg.memorySize, cfg.timeout, cfg.reservedConcurrency, cfg.ephemeralStorageMb, cfg.logRetentionDays, true, undefined, opts);
   queue.arn.apply(queueArn => new (Aws.iam.RolePolicy)(name + `-sqsSend`, {
     policy: PolicyDocument$PulumiAws.toJsonString(PolicyDocument$PulumiAws.make(undefined, name + `-sqsSendPolicy`, [{
         Sid: "AllowSqsSend",

package/src/adapter/Runtime/StateViewSliceRuntime_Builder_Single.res.mjs

@@ -117,7 +117,7 @@ function buildLambda(parent, handlerOutputs, packageDirs, channelSpecs, memorySi
   packageDirs["@reventlessdev/reventless-aws"] = Util_Bundle$ReventlessAws.resolvePackageRoot("@reventlessdev/reventless-aws");
   packageDirs["@reventlessdev/reventless-core"] = Util_Bundle$ReventlessAws.resolvePackageRoot("@reventlessdev/reventless-core");
   let match = Util_Bundle$ReventlessAws.buildCodeArchive("@reventlessdev/reventless-aws/src/adapter/Runtime/StateViewSliceEntryPoint.mjs", packageDirs, undefined);
-  let runtime = RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset("AllStateViewSlices", match.code, match.sourceCodeHash, envVars, memorySize, timeout, undefined, undefined, undefined, undefined, opts);
+  let runtime = RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset("AllStateViewSlices", match.code, match.sourceCodeHash, envVars, memorySize, timeout, undefined, undefined, undefined, undefined, undefined, opts);
   EventCollectorChannel_DynamoDbStream$ReventlessAws.connect("AllStateViewSlices", channelSpecs, runtime, opts);
 }
 

package/src/adapter/Runtime/TaskRuntime_Builder_PerBucket.res.mjs

@@ -29,7 +29,7 @@ function forBucketCallback(param, connect, memorySizeOpt, timeoutOpt, name, call
   let pkg = Util_Bundle$ReventlessAws.extractPackageName(callbackModulePath);
   packageDirs[pkg] = Util_Bundle$ReventlessAws.resolvePackageRoot(pkg);
   let match = Util_Bundle$ReventlessAws.buildCodeArchive("@reventlessdev/reventless-aws/src/adapter/Runtime/TaskBucketEntryPoint.mjs", packageDirs, undefined);
-  let runtime = RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset(fullName, match.code, match.sourceCodeHash, envVars, memorySize, timeout, undefined, undefined, undefined, undefined, {
+  let runtime = RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset(fullName, match.code, match.sourceCodeHash, envVars, memorySize, timeout, undefined, undefined, undefined, undefined, undefined, {
     parent: resource
   });
   if (schedulerConfig !== undefined) {

package/src/components/Api/AppSync_Adapter.res

@@ -266,6 +266,21 @@ let getClient = () =>
 // reaching request is already authenticated). `AllowGroups([])` and
 // `DenyAll` emit a sentinel `__deny_all__` group that no Cognito user can
 // belong to — effectively blocking the field at the API layer.
+//
+// ── Dual-auth (Cognito + IAM) for deploy-time system callers ────────────────
+// A field flagged `iamCallable` (via `mutationSchemaEntry`/`querySchemaEntry`)
+// must be reachable by BOTH the console UI (Cognito) and a deploy-time system
+// caller signing SigV4 with ambient AWS credentials (`Util_AppSync_Caller`,
+// the AWS_IAM additional auth provider). `@aws_auth(...)` is the single-mode
+// directive form and does not admit IAM on a multi-auth API. For these fields
+// we emit the multi-auth form instead:
+//   @aws_cognito_user_pools(cognito_groups: [...]) @aws_iam
+// The Cognito arm preserves the field's existing group gating (or, when the
+// field carries no Cognito group restriction, a bare `@aws_cognito_user_pools`
+// keeps it open to any authenticated Cognito user); the `@aws_iam` arm admits
+// the system caller. IAM access must be constrained by the API resource policy
+// and a least-privilege deploy-role policy — see
+// `docs/guides/appsync-iam-system-caller.md`.
 
 let _permissionToCognitoGroups = (
   permission: Reventless.Authorization.permission,
@@ -282,6 +297,20 @@ let _formatGroupsDirective = (groups: array<string>): string => {
   `@aws_auth(cognito_groups: [${quoted}])`
 }
 
+// Multi-auth directive for a field that must accept BOTH Cognito and IAM.
+// `groups=Some([...])` preserves Cognito group gating; `groups=None` keeps the
+// field open to any authenticated Cognito user. `@aws_iam` admits the
+// deploy-time SigV4 system caller. See the dual-auth note above.
+let _formatDualAuthDirective = (groups: option<array<string>>): string => {
+  let cognito = switch groups {
+  | Some(g) =>
+    let quoted = g->Array.map(x => `"${x}"`)->Array.join(", ")
+    `@aws_cognito_user_pools(cognito_groups: [${quoted}])`
+  | None => `@aws_cognito_user_pools`
+  }
+  `${cognito} @aws_iam`
+}
+
 let injectAwsAuth = (
   fragment: Reventless.Plugin.apiSchemaFragment,
   ~mutationEntries: array<ReventlessInfra.Api.mutationSchemaEntry>,
@@ -292,8 +321,16 @@ let injectAwsAuth = (
   // Build authorization lookup from mutation entries: fieldName -> groups.
   // Spec-level `fieldPermissions` takes precedence over the legacy
   // `authorization.group` per-entry single-group form.
+  // Fields opted into deploy-time IAM invocation (dual-auth). Membership here
+  // switches a field from the single-mode `@aws_auth` form to the multi-auth
+  // `@aws_cognito_user_pools(...) @aws_iam` form.
+  let iamFields: Dict.t<bool> = Dict.make()
+
   let mutationAuthMap: Dict.t<array<string>> = Dict.make()
   mutationEntries->Array.forEach(entry => {
+    if entry.iamCallable->Option.getOr(false) {
+      entry.fieldNames->Array.forEach(fieldName => iamFields->Dict.set(fieldName, true))
+    }
     switch entry.authorization {
     | Some({group}) =>
       entry.fieldNames->Array.forEach(fieldName =>
@@ -319,6 +356,10 @@ let injectAwsAuth = (
   // Spec-level `permission` takes precedence over the legacy authorization.
   let queryAuthMap: Dict.t<array<string>> = Dict.make()
   queryEntries->Array.forEach(entry => {
+    if entry.iamCallable->Option.getOr(false) {
+      iamFields->Dict.set(entry.singleFieldName, true)
+      iamFields->Dict.set(entry.listFieldName, true)
+    }
     switch entry.authorization {
     | Some({group}) =>
       queryAuthMap->Dict.set(entry.singleFieldName, [group])
@@ -341,17 +382,27 @@ let injectAwsAuth = (
 
   let augmentedMutations = parts.mutations->Array.map(field => {
     let fieldName = ReventlessCore.GraphQL_Stitcher.extractLeadingName(field)
-    switch mutationAuthMap->Dict.get(fieldName) {
-    | Some(groups) => `${field}\n    ${_formatGroupsDirective(groups)}`
-    | None => field
+    let groups = mutationAuthMap->Dict.get(fieldName)
+    if iamFields->Dict.get(fieldName)->Option.getOr(false) {
+      `${field}\n    ${_formatDualAuthDirective(groups)}`
+    } else {
+      switch groups {
+      | Some(groups) => `${field}\n    ${_formatGroupsDirective(groups)}`
+      | None => field
+      }
     }
   })
 
   let augmentedQueries = parts.queries->Array.map(field => {
     let fieldName = ReventlessCore.GraphQL_Stitcher.extractLeadingName(field)
-    switch queryAuthMap->Dict.get(fieldName) {
-    | Some(groups) => `${field} ${_formatGroupsDirective(groups)}`
-    | None => field
+    let groups = queryAuthMap->Dict.get(fieldName)
+    if iamFields->Dict.get(fieldName)->Option.getOr(false) {
+      `${field} ${_formatDualAuthDirective(groups)}`
+    } else {
+      switch groups {
+      | Some(groups) => `${field} ${_formatGroupsDirective(groups)}`
+      | None => field
+      }
     }
   })
 
@@ -374,17 +425,30 @@ let injectAwsAuth = (
 // Injects @aws_auth with the given group on ALL mutation, query, and subscription
 // fields in a fragment. Used for the base fragment where all fields share the
 // same authorization group.
+//
+// `~iamFieldNames` opts the named mutation/query fields into deploy-time IAM
+// (dual-auth): those fields emit `@aws_cognito_user_pools(cognito_groups:
+// ["<group>"]) @aws_iam` instead of the single-mode `@aws_auth(...)`, keeping
+// the same Cognito group gating while also admitting the SigV4 system caller.
+// Subscriptions are never IAM-marked (the deploy caller does not subscribe).
 let injectAwsAuthAll = (
   fragment: Reventless.Plugin.apiSchemaFragment,
   ~group: string,
+  ~iamFieldNames: array<string>=[],
 ): Reventless.Plugin.apiSchemaFragment => {
   let parts = ReventlessCore.GraphQL_Stitcher.decode(fragment)
+  let isIam = (field: string): bool =>
+    iamFieldNames->Array.includes(ReventlessCore.GraphQL_Stitcher.extractLeadingName(field))
 
   let augmentedMutations = parts.mutations->Array.map(field =>
-    `${field}\n    @aws_auth(cognito_groups: ["${group}"])`
+    isIam(field)
+      ? `${field}\n    ${_formatDualAuthDirective(Some([group]))}`
+      : `${field}\n    @aws_auth(cognito_groups: ["${group}"])`
   )
   let augmentedQueries = parts.queries->Array.map(field =>
-    `${field} @aws_auth(cognito_groups: ["${group}"])`
+    isIam(field)
+      ? `${field} ${_formatDualAuthDirective(Some([group]))}`
+      : `${field} @aws_auth(cognito_groups: ["${group}"])`
   )
   let augmentedSubscriptions = parts.subscriptions->Array.map(field =>
     `${field}\n    @aws_auth(cognito_groups: ["${group}"])`

package/src/components/Api/AppSync_Adapter.res.mjs

@@ -204,10 +204,27 @@ function _formatGroupsDirective(groups) {
   return `@aws_auth(cognito_groups: [` + quoted + `])`;
 }
 
+function _formatDualAuthDirective(groups) {
+  let cognito;
+  if (groups !== undefined) {
+    let quoted = groups.map(x => `"` + x + `"`).join(", ");
+    cognito = `@aws_cognito_user_pools(cognito_groups: [` + quoted + `])`;
+  } else {
+    cognito = `@aws_cognito_user_pools`;
+  }
+  return cognito + ` @aws_iam`;
+}
+
 function injectAwsAuth(fragment, mutationEntries, queryEntries) {
   let parts = GraphQL_Stitcher$ReventlessCore.decode(fragment);
+  let iamFields = {};
   let mutationAuthMap = {};
   mutationEntries.forEach(entry => {
+    if (Stdlib_Option.getOr(entry.iamCallable, false)) {
+      entry.fieldNames.forEach(fieldName => {
+        iamFields[fieldName] = true;
+      });
+    }
     let match = entry.authorization;
     if (match !== undefined) {
       let group = match.group;
@@ -232,6 +249,10 @@ function injectAwsAuth(fragment, mutationEntries, queryEntries) {
   });
   let queryAuthMap = {};
   queryEntries.forEach(entry => {
+    if (Stdlib_Option.getOr(entry.iamCallable, false)) {
+      iamFields[entry.singleFieldName] = true;
+      iamFields[entry.listFieldName] = true;
+    }
     let match = entry.authorization;
     if (match !== undefined) {
       let group = match.group;
@@ -255,7 +276,9 @@ function injectAwsAuth(fragment, mutationEntries, queryEntries) {
   let augmentedMutations = parts.mutations.map(field => {
     let fieldName = GraphQL_Stitcher$ReventlessCore.extractLeadingName(field);
     let groups = mutationAuthMap[fieldName];
-    if (groups !== undefined) {
+    if (Stdlib_Option.getOr(iamFields[fieldName], false)) {
+      return field + `\n    ` + _formatDualAuthDirective(groups);
+    } else if (groups !== undefined) {
       return field + `\n    ` + _formatGroupsDirective(groups);
     } else {
       return field;
@@ -264,7 +287,9 @@ function injectAwsAuth(fragment, mutationEntries, queryEntries) {
   let augmentedQueries = parts.queries.map(field => {
     let fieldName = GraphQL_Stitcher$ReventlessCore.extractLeadingName(field);
     let groups = queryAuthMap[fieldName];
-    if (groups !== undefined) {
+    if (Stdlib_Option.getOr(iamFields[fieldName], false)) {
+      return field + ` ` + _formatDualAuthDirective(groups);
+    } else if (groups !== undefined) {
       return field + ` ` + _formatGroupsDirective(groups);
     } else {
       return field;
@@ -294,10 +319,23 @@ function injectAwsAuth(fragment, mutationEntries, queryEntries) {
   };
 }
 
-function injectAwsAuthAll(fragment, group) {
+function injectAwsAuthAll(fragment, group, iamFieldNamesOpt) {
+  let iamFieldNames = iamFieldNamesOpt !== undefined ? iamFieldNamesOpt : [];
   let parts = GraphQL_Stitcher$ReventlessCore.decode(fragment);
-  let augmentedMutations = parts.mutations.map(field => field + `\n    @aws_auth(cognito_groups: ["` + group + `"])`);
-  let augmentedQueries = parts.queries.map(field => field + ` @aws_auth(cognito_groups: ["` + group + `"])`);
+  let augmentedMutations = parts.mutations.map(field => {
+    if (iamFieldNames.includes(GraphQL_Stitcher$ReventlessCore.extractLeadingName(field))) {
+      return field + `\n    ` + _formatDualAuthDirective([group]);
+    } else {
+      return field + `\n    @aws_auth(cognito_groups: ["` + group + `"])`;
+    }
+  });
+  let augmentedQueries = parts.queries.map(field => {
+    if (iamFieldNames.includes(GraphQL_Stitcher$ReventlessCore.extractLeadingName(field))) {
+      return field + ` ` + _formatDualAuthDirective([group]);
+    } else {
+      return field + ` @aws_auth(cognito_groups: ["` + group + `"])`;
+    }
+  });
   let augmentedSubscriptions = parts.subscriptions.map(field => field + `\n    @aws_auth(cognito_groups: ["` + group + `"])`);
   let encoded = JSON.stringify(Object.fromEntries([
     [
@@ -359,7 +397,7 @@ function generateFragment(mutationEntries, queryEntries) {
 }
 
 function updateSchema(api, baseFragment, pluginFragments) {
-  let augmentedBaseFragment = injectAwsAuthAll(baseFragment, "Admin");
+  let augmentedBaseFragment = injectAwsAuthAll(baseFragment, "Admin", undefined);
   let sdl = GraphQL_Stitcher$ReventlessCore.stitch(augmentedBaseFragment, pluginFragments);
   let resultPromise = {
     contents: Promise.resolve()
@@ -387,6 +425,7 @@ export {
   getClient,
   _permissionToCognitoGroups,
   _formatGroupsDirective,
+  _formatDualAuthDirective,
   injectAwsAuth,
   injectAwsAuthAll,
   makeApiResource,

package/src/plugin/runtime/PluginExtensionPointRuntime_Builder.res.mjs

@@ -66,7 +66,7 @@ function forCommandTopic(param, connect, memorySizeOpt, timeoutOpt, param$1, par
   });
   envVars["HANDLER_CONFIG"] = handlerConfigJson;
   let match = Util_Bundle$ReventlessAws.buildCodeArchive("@reventlessdev/reventless-aws/src/adapter/Runtime/PluginExtensionPointEntryPoint.mjs", {}, undefined);
-  return connect(RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset(name, match.code, match.sourceCodeHash, envVars, memorySize, timeout, undefined, undefined, undefined, undefined, opts));
+  return connect(RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset(name, match.code, match.sourceCodeHash, envVars, memorySize, timeout, undefined, undefined, undefined, undefined, undefined, opts));
 }
 
 function finish() {

package/src/plugin/runtime/PluginRuntime_Builder.res.mjs

@@ -300,7 +300,7 @@ function Make(EventCollectorChannel) {
     });
     let codeOutput = bundleOutput.apply(b => b.code);
     let sourceCodeHashOutput = bundleOutput.apply(b => b.sourceCodeHash);
-    let runtime = RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset(name, codeOutput, sourceCodeHashOutput, envVars, memorySize, timeout, undefined, undefined, undefined, undefined, opts);
+    let runtime = RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset(name, codeOutput, sourceCodeHashOutput, envVars, memorySize, timeout, undefined, undefined, undefined, undefined, undefined, opts);
     EventCollectorChannel.connect(name, [{
         channel: eventCollector.channel,
         eventTopics: eventTopics,
@@ -422,7 +422,7 @@ function Make(EventCollectorChannel) {
     envVars["PLUGIN_ID"] = Pulumi.output(hbConfig.pluginId);
     envVars["HEARTBEAT_TIMEOUT"] = Pulumi.output(hbConfig.heartbeatTimeout.toString());
     let match = Util_Bundle$ReventlessAws.buildCodeArchive("@reventlessdev/reventless-aws/src/adapter/Runtime/HeartbeatEntryPoint.mjs", {}, undefined);
-    connect(RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset(name, match.code, match.sourceCodeHash, envVars, memorySize, timeout, undefined, undefined, undefined, undefined, opts));
+    connect(RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset(name, match.code, match.sourceCodeHash, envVars, memorySize, timeout, undefined, undefined, undefined, undefined, undefined, opts));
   };
   let forDcbCommandTopic = (param, connect, $staropt$star, $staropt$star$1, dcbCommandTopic) => {
     $staropt$star !== undefined;

package/src/util/Util_AppSync_Caller.res

@@ -107,13 +107,25 @@ let rec jsonToLiteral = (value: JSON.t): string =>
     }
   }
 
-let buildQuery = (~mutation: string, ~variablesDict: dict<JSON.t>): string => {
+// ~selection is the sub-selection appended after the field call. It defaults to
+// `{ __typename }` because every command mutation dispatched through this caller
+// returns the `CommandResult` union (CommandAccepted | CommandPending |
+// CommandRejected); GraphQL rejects a selectionless field on any object/union
+// type with `SubSelectionRequired`. Pass ~selection="" for a scalar-returning
+// mutation, or a richer set (e.g. "{ __typename ... on CommandRejected { reason } }")
+// to inspect the result.
+let buildQuery = (
+  ~mutation: string,
+  ~selection: string="{ __typename }",
+  ~variablesDict: dict<JSON.t>,
+): string => {
   let args =
     variablesDict
     ->Dict.toArray
     ->Array.map(((k, v)) => `${k}: ${jsonToLiteral(v)}`)
     ->Array.join(", ")
-  `mutation { ${mutation}(${args}) }`
+  let sel = selection == "" ? "" : ` ${selection}`
+  `mutation { ${mutation}(${args})${sel} }`
 }
 
 // ── sendMutation ────────────────────────────────────────────────────────────
@@ -121,6 +133,8 @@ let buildQuery = (~mutation: string, ~variablesDict: dict<JSON.t>): string => {
 // Signs and sends a single GraphQL mutation to an AppSync endpoint via IAM.
 // ~variables accepts any value; undefined/optional fields are omitted by
 // JSON.stringifyAny (mirrors how JSON.stringify drops undefined object keys).
+// ~selection defaults to `{ __typename }` so CommandResult-union mutations
+// validate (see buildQuery); pass ~selection="" for scalar-returning mutations.
 // Returns a promise — callers fire-and-forget with `let _ = sendMutation(...)`.
 
 // Signs and sends a GraphQL query; returns the `data` object or None on error.
@@ -164,7 +178,13 @@ let sendQuery = async (~endpoint: string, ~region: string, ~queryString: string)
   }
 }
 
-let sendMutation = async (~endpoint: string, ~region: string, ~mutation: string, ~variables: 'a) => {
+let sendMutation = async (
+  ~endpoint: string,
+  ~region: string,
+  ~mutation: string,
+  ~selection: string="{ __typename }",
+  ~variables: 'a,
+) => {
   let url = parseUrl(endpoint)
   let hostname: string = (url)["hostname"]
   let path: string = (url)["pathname"]
@@ -180,7 +200,7 @@ let sendMutation = async (~endpoint: string, ~region: string, ~mutation: string,
     | None => Dict.make()
     }
 
-  let query = buildQuery(~mutation, ~variablesDict)
+  let query = buildQuery(~mutation, ~selection, ~variablesDict)
   let body =
     Dict.fromArray([("query", query->JSON.Encode.string)])
     ->JSON.Encode.object