@reventlessdev/reventless-aws 3.0.0-alpha.336 → 3.0.0-alpha.338

package/src/adapter/Runtime/EventCollectorEntryPoint_Ops.res

@@ -62,11 +62,11 @@ external scanByTableName: (
 let exnMessage = (exn: exn): string =>
   exn->JsExn.fromException->Option.flatMap(JsExn.message)->Option.getOr("unknown error")
 
-// ── js_nullable normalization ───────────────────────────────────────────────
-// pluginDefinition option fields use @s.matches(js_nullable): when the record
-// comes from a plain JSON.parse (not a sury parse), None is represented as
-// `null` — which ReScript's option (undefined-based) would misread as Some.
-// Normalize through Nullable so pattern matches see a real option.
+// ── Absent-field normalization ──────────────────────────────────────────────
+// pluginDefinition's optionals omit the key, so a plain JSON.parse (not a sury
+// parse) yields `undefined` and ReScript reads it as None unaided. Kept because
+// the same records also arrive from stores and peers written when an absent
+// field was `null`, which ReScript's option would misread as Some.
 
 external optionAsNullable: option<'a> => Nullable.t<'a> = "%identity"
 let jsOption = (v: option<'a>): option<'a> => v->optionAsNullable->Nullable.toOption
@@ -237,10 +237,9 @@ let parseHandlerConfig = (rawJson: string): handlerConfig => {
 
 // ── Plugin-RM row projection ────────────────────────────────────────────────
 // The subset of the Plugin read-model state the subscription manager needs.
-// Deliberately sidesteps sury: the state schema marks many fields
-// `@s.matches(js_nullable …)`, but DDB drops undefined attributes on write, so
-// the unmarshalled row arrives with those keys *missing* and sury's strict
-// parser rejects them. Field types reuse the spec's definition records — the
+// Deliberately sidesteps sury: DDB drops undefined attributes on write, so the
+// unmarshalled row can arrive with keys sury's strict parser still expects — the
+// offload fields among them, whose codec keeps its `null` arm. Field types reuse the spec's definition records — the
 // projection is a strict subset of Reventless.Plugin.pluginDefinition.
 
 type pluginProjection = {
@@ -325,8 +324,8 @@ let projectPluginRow = (row: JSON.t): option<pluginProjection> =>
 
 // A pluginDefinition viewed as a projection (the manage logic reads only the
 // shared subset; `status` is never read for the acting plugin). Array/option
-// fields stay js_nullable-normalized: a definition arriving over the wire, rather
-// than from loadPluginDefinition's decode, still carries null for an absent field.
+// fields stay normalized: a definition arriving over the wire, rather than from
+// loadPluginDefinition's decode, may still carry null for an absent field.
 let projectionOfDefinition = (d: Reventless.Plugin.pluginDefinition): pluginProjection => {
   id: d.id,
   status: "",

package/src/util/Util_AlarmSpec.res

@@ -0,0 +1,155 @@
+// What to alarm on, per kind of execution unit — the pure half of the CloudWatch
+// monitoring backend. `Monitoring_CloudWatch` turns these into resources; every
+// decision worth arguing with is here, where a test can reach it without
+// importing @pulumi/pulumi. Same split as Util_LogRetention / Util_LambdaLogging.
+
+module M = ReventlessCore.Monitoring
+
+/** One alarm. `suffix` distinguishes several alarms on one unit; the empty
+    string is the unit's primary alarm. */
+type t = {
+  metricName: string,
+  namespace: string,
+  /** CloudWatch operator name, e.g. `"GreaterThanOrEqualToThreshold"`. */
+  comparisonOperator: string,
+  threshold: float,
+  /** Seconds. */
+  period: int,
+  evaluationPeriods: int,
+  statistic: string,
+  /** `"missing"` | `"notBreaching"` | `"breaching"` | `"ignore"`. */
+  treatMissingData: string,
+  suffix: string,
+  /** One clause, for the description a person reads in the notification. */
+  meaning: string,
+}
+
+/** How long a scheduled unit may produce no invocation before that silence is
+    itself the fault. The default is an hour: the plugin heartbeat's default
+    interval is 5 minutes, so an hour is twelve missed beats — far enough out that
+    a slow deploy or a throttle cannot trip it, close enough that a stopped
+    scheduler is caught within the hour rather than by its consequences days
+    later. Deployments that set a long `heartbeatInterval` should raise it. */
+let defaultSilenceWindowSeconds = 60 * 60
+
+let errorsAlarm = {
+  metricName: "Errors",
+  namespace: "AWS/Lambda",
+  comparisonOperator: "GreaterThanOrEqualToThreshold",
+  threshold: 1.0,
+  period: 300,
+  evaluationPeriods: 1,
+  statistic: "Sum",
+  // A unit that is not running produces no datapoints, and "no traffic" is not a
+  // failure — an idle stack must not sit permanently in alarm, or every alarm it
+  // raises is discounted.
+  treatMissingData: "notBreaching",
+  suffix: "",
+  meaning: "is failing on its messages (Errors >= 1 in 5min)",
+}
+
+/**
+The alarms for one kind of execution unit. More than one is allowed, because for
+some kinds a single metric cannot express the fault.
+
+- **Dead-letter sink** — the metric is `Invocations`, not `Errors`. This handler
+  fails on every delivery by design, so `Errors` says only that it is doing its
+  job; that it ran at all is the incident.
+- **Scheduler** — two alarms, and the second is the one that matters. A heartbeat
+  that *stops* emits no errors and no invocations, so the absence is the fault and
+  `Errors` cannot see it. The silence alarm inverts the test (`Invocations < 1`)
+  and treats missing data as breaching, which is the only combination that fires
+  on a metric that has stopped being published. This is the exact shape that went
+  unnoticed on a deployed estate: plugins stopped heartbeating and nothing said so.
+- **Everything else** — `Errors >= 1`.
+*/
+let forKind = (~kind: M.unitKind, ~silenceWindowSeconds=defaultSilenceWindowSeconds): array<t> =>
+  switch kind {
+  | DeadLetterSink => [
+      {
+        ...errorsAlarm,
+        metricName: "Invocations",
+        meaning: "received a dead letter (an invocation here IS the incident)",
+      },
+    ]
+  | Scheduler => [
+      errorsAlarm,
+      {
+        ...errorsAlarm,
+        metricName: "Invocations",
+        comparisonOperator: "LessThanThreshold",
+        period: silenceWindowSeconds,
+        // The point of the alarm: a metric that stopped being published is the
+        // failure, so its absence must breach rather than be excused.
+        treatMissingData: "breaching",
+        suffix: "Silent",
+        meaning: "has not run for " ++ (silenceWindowSeconds / 60)->Int.toString ++ " minutes",
+      },
+    ]
+  | _ => [errorsAlarm]
+  }
+
+/** Lower-case, hyphen-free rendering of a kind, for a resource name and for the
+    machine-readable `kind=` in a description. `Other` carries its own word. */
+let kindSlug = (kind: M.unitKind): string =>
+  switch kind {
+  | CommandHandler => "commandhandler"
+  | Projection => "projection"
+  | Reactor => "reactor"
+  | EventCollector => "eventcollector"
+  | Task => "task"
+  | Scheduler => "scheduler"
+  | DeadLetterSink => "deadlettersink"
+  | Other(word) => "other" ++ word->String.toLowerCase
+  }
+
+/**
+The alarm's logical (Pulumi) resource name.
+
+Carries the plugin when there is one: `~name` is the component only, and two
+plugins in a platform can own like-named components — a collision here is a
+Pulumi duplicate-resource failure at deploy time, not a subtle one, but the fix
+belongs in the name rather than in the reader's memory.
+*/
+let resourceName = (~kind: M.unitKind, ~name: string, ~plugin: option<string>, ~suffix: string) => {
+  let owner = switch plugin {
+  | Some(p) => p ++ "-"
+  | None => ""
+  }
+  `alarm-${kind->kindSlug}-${owner}${name}${suffix}`
+}
+
+/**
+What the notification says.
+
+Two audiences in one string, because a CloudWatch state-change message carries the
+description and neither the alarm's tags nor its name: a sentence for the person
+who reads the mail, and a bracketed token for anything parsing it. Without the
+platform the mail cannot say which estate fired — one platform runs many plugins
+whose components are named by role, so `CatalogPluginHeartbeat` alone is ambiguous
+across stacks.
+*/
+let description = (
+  ~kind: M.unitKind,
+  ~name: string,
+  ~plugin: option<string>,
+  ~platform: option<string>,
+  ~spec: t,
+  ~logs: option<string>,
+) => {
+  let owner = switch (plugin, platform) {
+  | (Some(p), Some(pl)) => ` (plugin ${p}, platform ${pl})`
+  | (Some(p), None) => ` (plugin ${p})`
+  | (None, Some(pl)) => ` (platform ${pl})`
+  // Platform substrate, owned by no plugin — a dead-letter queue is shared by
+  // every plugin in the estate, so naming one would be a lie.
+  | (None, None) => ""
+  }
+  let logsClause = switch logs {
+  | Some(group) => ` Logs: ${group}.`
+  | None => ""
+  }
+  `Reventless: ${kind->kindSlug} '${name}'${owner} ${spec.meaning}.${logsClause}` ++
+  ` [reventless plugin=${plugin->Option.getOr("")} platform=${platform->Option.getOr("")}` ++
+  ` component=${name} kind=${kind->kindSlug}]`
+}

package/src/util/Util_AlarmSpec.res.mjs

@@ -0,0 +1,108 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+
+let errorsAlarm = {
+  metricName: "Errors",
+  namespace: "AWS/Lambda",
+  comparisonOperator: "GreaterThanOrEqualToThreshold",
+  threshold: 1.0,
+  period: 300,
+  evaluationPeriods: 1,
+  statistic: "Sum",
+  treatMissingData: "notBreaching",
+  suffix: "",
+  meaning: "is failing on its messages (Errors >= 1 in 5min)"
+};
+
+function forKind(kind, silenceWindowSecondsOpt) {
+  let silenceWindowSeconds = silenceWindowSecondsOpt !== undefined ? silenceWindowSecondsOpt : 3600;
+  if (typeof kind === "object") {
+    return [errorsAlarm];
+  }
+  switch (kind) {
+    case "Scheduler" :
+      return [
+        errorsAlarm,
+        {
+          metricName: "Invocations",
+          namespace: "AWS/Lambda",
+          comparisonOperator: "LessThanThreshold",
+          threshold: 1.0,
+          period: silenceWindowSeconds,
+          evaluationPeriods: 1,
+          statistic: "Sum",
+          treatMissingData: "breaching",
+          suffix: "Silent",
+          meaning: "has not run for " + (silenceWindowSeconds / 60 | 0).toString() + " minutes"
+        }
+      ];
+    case "DeadLetterSink" :
+      return [{
+          metricName: "Invocations",
+          namespace: "AWS/Lambda",
+          comparisonOperator: "GreaterThanOrEqualToThreshold",
+          threshold: 1.0,
+          period: 300,
+          evaluationPeriods: 1,
+          statistic: "Sum",
+          treatMissingData: "notBreaching",
+          suffix: "",
+          meaning: "received a dead letter (an invocation here IS the incident)"
+        }];
+    default:
+      return [errorsAlarm];
+  }
+}
+
+function kindSlug(kind) {
+  if (typeof kind === "object") {
+    return "other" + kind._0.toLowerCase();
+  }
+  switch (kind) {
+    case "CommandHandler" :
+      return "commandhandler";
+    case "Projection" :
+      return "projection";
+    case "Reactor" :
+      return "reactor";
+    case "EventCollector" :
+      return "eventcollector";
+    case "Task" :
+      return "task";
+    case "Scheduler" :
+      return "scheduler";
+    case "DeadLetterSink" :
+      return "deadlettersink";
+  }
+}
+
+function resourceName(kind, name, plugin, suffix) {
+  let owner = plugin !== undefined ? plugin + "-" : "";
+  return `alarm-` + kindSlug(kind) + `-` + owner + name + suffix;
+}
+
+function description(kind, name, plugin, platform, spec, logs) {
+  let owner = plugin !== undefined ? (
+      platform !== undefined ? ` (plugin ` + plugin + `, platform ` + platform + `)` : ` (plugin ` + plugin + `)`
+    ) : (
+      platform !== undefined ? ` (platform ` + platform + `)` : ""
+    );
+  let logsClause = logs !== undefined ? ` Logs: ` + logs + `.` : "";
+  return `Reventless: ` + kindSlug(kind) + ` '` + name + `'` + owner + ` ` + spec.meaning + `.` + logsClause + (` [reventless plugin=` + Stdlib_Option.getOr(plugin, "") + ` platform=` + Stdlib_Option.getOr(platform, "")) + (` component=` + name + ` kind=` + kindSlug(kind) + `]`);
+}
+
+let M;
+
+let defaultSilenceWindowSeconds = 3600;
+
+export {
+  M,
+  defaultSilenceWindowSeconds,
+  errorsAlarm,
+  forKind,
+  kindSlug,
+  resourceName,
+  description,
+}
+/* No side effect */

package/src/util/Util_DeadLetterQueue.res

@@ -17,10 +17,25 @@ let queueTags = queueName =>
 // 4-day default can expire it over a long weekend before anyone reads it.
 let retentionSeconds = 14 * 24 * 60 * 60
 
+// A dead letter has no latency requirement, and the handler below fails on
+// purpose — so a message returns to the queue and is redelivered until retention
+// expires. At 180 s that is ~480 redeliveries per message per day, which outlives
+// the fault by however long nobody looks: seven heartbeats stranded by a since-fixed
+// decode error were still cycling twelve hours after the cause was cured. Fifteen
+// minutes cuts that 5× and costs nothing anybody is waiting on. It must stay above
+// the handler's timeout (30 s), which it is by a wide margin.
+//
+// It bounds the rate, not the count — the loop still ends only at retention. What
+// ends it early is an operator, and what fetches one is an alarm on this handler's
+// `Invocations` (an invocation here IS the incident). That the alarm does not
+// currently fire is a defect in when this module announces itself, not a reason
+// for the queue to carry a redrive target of its own.
+let visibilityTimeoutSeconds = 15 * 60
+
 let queue = SQS.Queue.make(
   ~name,
   ~args={
-    SQS.Queue.visibilityTimeoutSeconds: 180->Pulumi.Input.make,
+    SQS.Queue.visibilityTimeoutSeconds: visibilityTimeoutSeconds->Pulumi.Input.make,
     messageRetentionSeconds: retentionSeconds->Pulumi.Input.make,
     sqsManagedSseEnabled: false->Pulumi.Input.make,
     tags: queueTags(name),
@@ -32,7 +47,7 @@ let fifoQueue = SQS.Queue.make(
   ~args={
     SQS.Queue.fifoQueue: true->Pulumi.Input.make,
     contentBasedDeduplication: true->Pulumi.Input.make,
-    visibilityTimeoutSeconds: 180->Pulumi.Input.make,
+    visibilityTimeoutSeconds: visibilityTimeoutSeconds->Pulumi.Input.make,
     messageRetentionSeconds: retentionSeconds->Pulumi.Input.make,
     sqsManagedSseEnabled: false->Pulumi.Input.make,
     tags: queueTags(nameFifo),
@@ -61,16 +76,41 @@ let lambdaRole = IAM.Role.makeWithDefaultPolicy(
 // plugin whose commands failed every 5 minutes for two days produced 217 dead
 // letters and no signal at all; it was found by a person noticing a stale UI.
 //
-// Failing instead keeps the message on the queue (this queue has no redrive
-// target of its own, so it stays until retention expires) and keeps `Errors`
-// non-zero for as long as the condition lasts. Both are conventional alarm
-// subjects, and a monitoring backend attached through the `DeadLetterSink` seam
-// below now has something to attach to. Re-delivery re-logs the payload; on a
-// queue that is empty in normal operation, that repetition is the alert.
+// Failing instead keeps the message on the queue and keeps `Errors` non-zero
+// while the condition lasts. Both are conventional alarm subjects, and a
+// monitoring backend attached through the `DeadLetterSink` seam below now has
+// something to attach to.
+//
+// What that reasoning did not account for is that the transport retries by
+// design too: a failed batch returns to the queue and is redelivered until
+// retention expires. A handler that fails forever, on a transport that retries
+// forever, is a loop — and it outlives its cause, because nothing about a fixed
+// bug removes the message that was stranded by it. Seven of them were still
+// cycling twelve hours after the fix that made them impossible.
+//
+// What the loop costs is now a function of the line, not the count: the full
+// record is written once — on the first delivery, the one carrying the diagnostic
+// — and every redelivery after it costs a single identity line. A stranded
+// message is ~150 KB over a fortnight rather than ~17 MB, which is small enough
+// that ending the loop early is an operator's job rather than the topology's.
 let entryPointCode = `export const handler = async (event) => {
-  console.error("DEAD LETTER ITEM:", JSON.stringify(event));
+  const records = event?.Records ?? [];
+  for (const record of records) {
+    const attrs = record?.attributes ?? {};
+    const receiveCount = Number(attrs.ApproximateReceiveCount ?? 1);
+    const identity =
+      "messageId=" + (record?.messageId ?? "unknown") +
+      " source=" + (attrs.DeadLetterQueueSourceArn ?? record?.eventSourceARN ?? "unknown") +
+      " receiveCount=" + receiveCount +
+      " bodyBytes=" + (record?.body?.length ?? 0);
+    if (receiveCount <= 1) {
+      console.error("DEAD LETTER ITEM: " + identity, JSON.stringify(record));
+    } else {
+      console.error("DEAD LETTER REDELIVERY: " + identity);
+    }
+  }
   throw new Error(
-    "Dead-lettered " + (event?.Records?.length ?? 0) +
+    "Dead-lettered " + records.length +
     " message(s); see DEAD LETTER ITEM above. Failing so the messages are retained and Errors is non-zero."
   );
 };`
@@ -89,6 +129,24 @@ let layers =
   ->Option.getOr([])
   ->Pulumi.Input.make
 
+// This is the one Lambda in the framework built by hand rather than through
+// `RuntimeEnvironment_Lambda`, and it was the one Lambda whose logs Lambda
+// auto-created a group for — which carries no retention, so every byte this
+// handler ever wrote was kept forever. On the estate that surfaced it, the three
+// such groups held 1.3 GB of a redelivery loop. Same managed group, same tiering
+// as every other handler.
+let logGroup = Util_LambdaLogging.makeManagedLogGroup(
+  ~name,
+  ~tags=AWS.Tags.make(
+    ~name=`${name}LogGroup`,
+    ~kind=ReventlessCore.ComponentType.Plugin,
+    ~role=Logs,
+    ~scope=Plugin,
+  ),
+  ~opts,
+  (),
+)
+
 let handler = Lambda.Function.make(
   ~name,
   ~args={
@@ -109,6 +167,7 @@ let handler = Lambda.Function.make(
         ]),
       }: Lambda.Function.functionEnvironment
     )->Pulumi.Input.make,
+    loggingConfig: ?Util_LambdaLogging.loggingConfigFor(logGroup),
   },
   ~opts,
 )
@@ -124,9 +183,7 @@ ReventlessCore.Monitoring.notify(
   ~kind=DeadLetterSink,
   ~name,
   ~component=deadLetterResource,
-  // This handler is built without a managed group, so its logs are in the one
-  // Lambda auto-creates from the physical name.
-  ~logLocator=Util_LambdaLogging.logLocatorFor(~logGroup=None, ~physicalName=deadLetterResource.name),
+  ~logLocator=Util_LambdaLogging.logLocatorFor(~logGroup, ~physicalName=deadLetterResource.name),
 )
 
 let lambda = handler->Pulumi.Output.make

package/src/util/Util_DeadLetterQueue.res.mjs

@@ -25,7 +25,7 @@ function queueTags(queueName) {
 let queue = new (Aws.sqs.Queue)(name, {
   messageRetentionSeconds: 1209600,
   tags: queueTags(name),
-  visibilityTimeoutSeconds: 180,
+  visibilityTimeoutSeconds: 900,
   sqsManagedSseEnabled: false
 });
 
@@ -34,7 +34,7 @@ let fifoQueue = new (Aws.sqs.Queue)(nameFifo, {
   fifoQueue: true,
   messageRetentionSeconds: 1209600,
   tags: queueTags(nameFifo),
-  visibilityTimeoutSeconds: 180,
+  visibilityTimeoutSeconds: 900,
   sqsManagedSseEnabled: false
 });
 
@@ -47,9 +47,23 @@ let opts = {
 let lambdaRole = IAM$PulumiAws.Role.makeWithDefaultPolicy(name, Pulumi.output(AWS$ReventlessAws.Lambda.principal), AWS_Tags$ReventlessAws.make(name, "Plugin", "Identity", "Plugin", undefined, undefined, undefined, undefined), opts);
 
 let entryPointCode = `export const handler = async (event) => {
-  console.error("DEAD LETTER ITEM:", JSON.stringify(event));
+  const records = event?.Records ?? [];
+  for (const record of records) {
+    const attrs = record?.attributes ?? {};
+    const receiveCount = Number(attrs.ApproximateReceiveCount ?? 1);
+    const identity =
+      "messageId=" + (record?.messageId ?? "unknown") +
+      " source=" + (attrs.DeadLetterQueueSourceArn ?? record?.eventSourceARN ?? "unknown") +
+      " receiveCount=" + receiveCount +
+      " bodyBytes=" + (record?.body?.length ?? 0);
+    if (receiveCount <= 1) {
+      console.error("DEAD LETTER ITEM: " + identity, JSON.stringify(record));
+    } else {
+      console.error("DEAD LETTER REDELIVERY: " + identity);
+    }
+  }
   throw new Error(
-    "Dead-lettered " + (event?.Records?.length ?? 0) +
+    "Dead-lettered " + records.length +
     " message(s); see DEAD LETTER ITEM above. Failing so the messages are retained and Errors is non-zero."
   );
 };`;
@@ -64,6 +78,8 @@ let sourceCodeHash = Util_Bundle$ReventlessAws.hashString(entryPointCode);
 
 let layers = Stdlib_Option.getOr(Stdlib_Option.map(Lambda$PulumiAws.reventlessLayerArn, arn => [arn]), []);
 
+let logGroup = Util_LambdaLogging$ReventlessAws.makeManagedLogGroup(name, undefined, AWS_Tags$ReventlessAws.make(name + `LogGroup`, "Plugin", "Logs", "Plugin", undefined, undefined, undefined, undefined), opts, undefined);
+
 let handler = new (Aws.lambda.Function)(name, {
   handler: "index.handler",
   runtime: "nodejs22.x",
@@ -82,12 +98,13 @@ let handler = new (Aws.lambda.Function)(name, {
       Util_LambdaLogging$ReventlessAws.logLevelEntry()
     ])
   },
-  sourceCodeHash: sourceCodeHash
+  sourceCodeHash: sourceCodeHash,
+  loggingConfig: Util_LambdaLogging$ReventlessAws.loggingConfigFor(logGroup)
 }, opts);
 
 let deadLetterResource = Util_Lambda$ReventlessAws.functionToResource(AWS_Tags$ReventlessAws.make(name, "Plugin", "DeadLetter", "Plugin", undefined, undefined, undefined, undefined), handler);
 
-Monitoring$ReventlessCore.notify("DeadLetterSink", name, deadLetterResource, Util_LambdaLogging$ReventlessAws.logLocatorFor(undefined, deadLetterResource.name));
+Monitoring$ReventlessCore.notify("DeadLetterSink", name, deadLetterResource, Util_LambdaLogging$ReventlessAws.logLocatorFor(logGroup, deadLetterResource.name));
 
 let lambda = Pulumi.output(handler);
 
@@ -164,11 +181,14 @@ Pulumi.all([
 
 let retentionSeconds = 1209600;
 
+let visibilityTimeoutSeconds = 900;
+
 export {
   name,
   nameFifo,
   queueTags,
   retentionSeconds,
+  visibilityTimeoutSeconds,
   queue,
   fifoQueue,
   opts,
@@ -178,6 +198,7 @@ export {
   code,
   sourceCodeHash,
   layers,
+  logGroup,
   handler,
   deadLetterResource,
   lambda,

package/src/util/Util_ShellConfig.res

@@ -93,10 +93,24 @@ let fields = (
   ~computed: array<(string, JSON.t)>,
   ~viewModes: option<array<Platform.viewMode>>=?,
   ~bakedManifest: option<Platform.bakedManifest>=?,
+  ~uiSlotsFile: option<string>=?,
   ~shellConfig: option<dict<JSON.t>>=?,
 ): dict<JSON.t> => {
   let out = computed->Dict.fromArray
 
+  // The shell imports the module this key names, and imports nothing when the
+  // key is absent — so writing the object without naming it here would ship a
+  // file nothing fetches. Computed rather than left to `shellConfig` for the
+  // reason `manifestUrl` is: the deploy decides where the object goes, and a
+  // passthrough pointing the shell elsewhere would be a 404 the shell is
+  // designed to survive quietly.
+  uiSlotsFile->Option.forEach(_ =>
+    out->Dict.set(
+      ReventlessCore.Platform_UiSlots.configKey,
+      JSON.Encode.string(ReventlessCore.Platform_UiSlots.url),
+    )
+  )
+
   // A declared bake is what turns the shell's non-elevated audience on: an
   // operator keeps the admin queries, everyone else discovers from this file.
   // Computed rather than left to `shellConfig` because the deploy is what

package/src/util/Util_ShellConfig.res.mjs

@@ -4,6 +4,7 @@ import * as Pervasives from "@rescript/runtime/lib/es6/Pervasives.js";
 import * as Stdlib_Dict from "@rescript/runtime/lib/es6/Stdlib_Dict.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Platform$ReventlessInfra from "@reventlessdev/reventless-infra/src/types/Platform.res.mjs";
+import * as Platform_UiSlots$ReventlessCore from "@reventlessdev/reventless-core/src/admin/Platform_UiSlots.res.mjs";
 import * as Platform_BakedManifest$ReventlessCore from "@reventlessdev/reventless-core/src/admin/Platform_BakedManifest.res.mjs";
 
 let journeyManifestsKey = "journeyManifestUrls";
@@ -56,8 +57,11 @@ function subscriptionEndpoint(httpsEndpoint) {
   return httpsEndpoint.replace("https://", "wss://").replace(".appsync-api.", ".appsync-realtime-api.");
 }
 
-function fields(computed, viewModes, bakedManifest, shellConfig) {
+function fields(computed, viewModes, bakedManifest, uiSlotsFile, shellConfig) {
   let out = Object.fromEntries(computed);
+  Stdlib_Option.forEach(uiSlotsFile, param => {
+    out[Platform_UiSlots$ReventlessCore.configKey] = Platform_UiSlots$ReventlessCore.url;
+  });
   Stdlib_Option.forEach(bakedManifest, bake => {
     out["manifestUrl"] = Platform_BakedManifest$ReventlessCore.urlForKey(bake.key);
     let urls = Platform_BakedManifest$ReventlessCore.journeyUrls(bake);

package/src/util/Util_StaticBundle.res

@@ -73,6 +73,27 @@ let readJsonFileVerbatim = (~path: string, ~label: string): string => {
   }
 }
 
+/**
+ * Read a file at deploy time and return its exact bytes as a string, with no
+ * opinion about what is in them. A missing file throws; a present one ships as
+ * written.
+ *
+ * The counterpart to `readJsonFileVerbatim` for content this deploy cannot
+ * validate. A JSON file either parses or it does not, and checking costs
+ * nothing. An ES module is only known to be good once a browser has evaluated
+ * it, and there is no cheap check in between: parsing it here would need a
+ * JavaScript parser this deploy does not have, and a syntax check would still
+ * say nothing about whether it registers anything. So the deploy checks the one
+ * thing it can — that the declared path names a file — and leaves the rest to
+ * the consumer, which reports what it could not use.
+ */
+let readFileVerbatim = (~path: string, ~label: string): string => {
+  if !NodeFs.existsSync(path) {
+    JsError.throwWithMessage(`${label}: file does not exist: ${path}`)
+  }
+  NodeFs.readFileSync(path)
+}
+
 /**
  * Replace `/` and `.` so a path can be used as a Pulumi resource URN segment.
  */

package/src/util/Util_StaticBundle.res.mjs

@@ -65,6 +65,13 @@ function readJsonFileVerbatim(path, label) {
   }
 }
 
+function readFileVerbatim(path, label) {
+  if (!Nodefs.existsSync(path)) {
+    Stdlib_JsError.throwWithMessage(label + `: file does not exist: ` + path);
+  }
+  return Nodefs.readFileSync(path, "utf8");
+}
+
 function sanitizeName(relativePath) {
   return relativePath.replaceAll("/", "-").replaceAll(".", "-");
 }
@@ -139,6 +146,7 @@ export {
   walkInto,
   walk,
   readJsonFileVerbatim,
+  readFileVerbatim,
   sanitizeName,
   extensionOf,
   contentTypeFor,