@reventlessdev/reventless-aws 3.0.0-alpha.208 → 3.0.0-alpha.210

package/src/adapter/Runtime/AdminEventCollectorEntryPoint.mjs

@@ -79,14 +79,8 @@ import { Make as pluginCallbackMake } from "@reventlessdev/reventless-core/src/p
 import { handleDynamoDbOrSqsEvent } from "@reventlessdev/reventless-aws/src/adapter/EventCollector/EventCollectorChannel_SQS_Runtime.res.mjs";
 import { createSchedule as cwCreateSchedule, deleteSchedule as cwDeleteSchedule } from "@reventlessdev/reventless-aws/src/adapter/ScheduledPublisher/ScheduledPublisher_CloudWatchEvents_Runtime.res.mjs";
 import {
-  stitch as graphqlStitch,
   decode as decodeFragment,
-  countRootTypeFields,
-  isCatastrophicSchemaShrink,
-  collectSubscriptionSources,
 } from "@reventlessdev/reventless-core/src/components/Api/GraphQL_Stitcher.res.mjs";
-import { injectAwsSubscribe, planAwsPushes } from "@reventlessdev/reventless-aws/src/components/Api/AppSync_SdlDecorate.res.mjs";
-import { baseFragment as adminBaseFragment, systemCallerFieldNames } from "@reventlessdev/reventless-core/src/admin/AdminApi.res.mjs";
 import { tag as requestContextTag } from "@reventlessdev/reventless-core/src/RequestContext.res.mjs";
 
 // The Plugin RM state schema uses `@s.matches(_jsNullable …)` for many
@@ -97,8 +91,7 @@ import { tag as requestContextTag } from "@reventlessdev/reventless-core/src/Req
 // whack-a-mole; instead, manageSubscriptions and reconcileSubscriptions only
 // need a tiny subset of the state (id / status / extensions / extensionPoints
 // / eventCollector), so they sidestep sury entirely and read the DDB row
-// directly via this small projection. mkUpdateApiSchema does the same for
-// apiSchemaFragment further below.
+// directly via this small projection.
 function projectPluginRow(row) {
   if (!row || typeof row !== "object") return null;
   if (typeof row.id !== "string" || typeof row.status !== "string") return null;
@@ -170,13 +163,6 @@ function parseHandlerConfig(rawJson) {
   // Optional fields with empty defaults — admin context omits them entirely.
   if (config.readModelQueueUrls === undefined) config.readModelQueueUrls = {};
   if (config.readModelNamesForSourceName === undefined) config.readModelNamesForSourceName = {};
-  // Reactive ApiFragmentRegistry single-writer (2e) — only the admin EventCollector
-  // carries a real registry table + admin DCB command topic; plugin ECs default to
-  // placeholders which disable the reactive push.
-  if (config.apiFragmentRegistryTableName === undefined) config.apiFragmentRegistryTableName = "NOT_AVAILABLE";
-  if (config.platformApiId === undefined) config.platformApiId = "NOT_AVAILABLE";
-  if (config.adminDcbCmdTopicUrl === undefined) config.adminDcbCmdTopicUrl = "";
-  if (config.splitApi === undefined) config.splitApi = false;
   // Per-extension defaults so older serialisers (or partial admin configs) keep working.
   for (const ext of config.extensions) {
     if (!Array.isArray(ext.aggregateNames)) ext.aggregateNames = [];
@@ -187,110 +173,6 @@ function parseHandlerConfig(rawJson) {
   return config;
 }
 
-function injectAwsAuthAll(fragment, group) {
-  const parts = decodeFragment(fragment);
-  const augmentedMutations = parts.mutations.map(
-    (field) => field + "\n    @aws_auth(cognito_groups: [\"" + group + "\"])"
-  );
-  const augmentedQueries = parts.queries.map(
-    (field) => field + " @aws_auth(cognito_groups: [\"" + group + "\"])"
-  );
-  const encoded = JSON.stringify({
-    types: parts.types,
-    mutations: augmentedMutations,
-    queries: augmentedQueries,
-  });
-  return { encoded, protocol: "graphql" };
-}
-
-async function updateAppSyncSchema(apiId, sdl) {
-  const { AppSyncClient, StartSchemaCreationCommand } = await import("@aws-sdk/client-appsync");
-  const client = new AppSyncClient({});
-  await client.send(new StartSchemaCreationCommand({ apiId, definition: sdl }));
-}
-
-// Fetch the current live AppSync schema as an SDL string for the shrink guard.
-// Returns "" (not an error) when the API has no schema yet (first deploy) or
-// introspection fails — the caller treats an empty current schema as "no
-// baseline to protect", so the push proceeds.
-async function getCurrentSchemaSdl(apiId) {
-  try {
-    const { AppSyncClient, GetIntrospectionSchemaCommand } = await import("@aws-sdk/client-appsync");
-    const client = new AppSyncClient({});
-    const resp = await client.send(new GetIntrospectionSchemaCommand({ apiId, format: "SDL" }));
-    if (!resp || !resp.schema) return "";
-    // resp.schema is a Uint8Array of the SDL text.
-    return Buffer.from(resp.schema).toString("utf-8");
-  } catch (e) {
-    log.warn(`could not introspect current schema (${(e && e.message) || e}) — skipping shrink guard`, { comp: "updateApiSchema" });
-    return "";
-  }
-}
-
-// Shrink-guard threshold: abort the push if the new SDL has fewer than
-// (threshold × current) root fields. Configurable via env; default 0.5 (50%).
-// Anything outside (0, 1) falls back to the default.
-function parseShrinkThreshold(raw) {
-  const n = raw ? Number(raw) : NaN;
-  return Number.isFinite(n) && n > 0 && n < 1 ? n : 0.5;
-}
-
-// Emit a CloudWatch metric via Embedded Metric Format (EMF). Any Lambda log line
-// shaped like this is auto-parsed by CloudWatch into the metric
-// Reventless/Runtime SchemaShrinkRejected (dimension ApiId) — no PutMetricData
-// call, SDK dependency, or extra IAM permission required.
-// NOTE: must stay as a raw `console.log` of the exact EMF envelope — routing
-// through `log.info` would add `time`/`level`/`message` siblings and break
-// CloudWatch's EMF auto-detect (the `_aws` block must be at the root of the
-// log record).
-function emitShrinkRejectionMetric(apiId, currentRootFields, newRootFields) {
-  try {
-    // eslint-disable-next-line no-console
-    console.log(
-      JSON.stringify({
-        _aws: {
-          Timestamp: Date.now(),
-          CloudWatchMetrics: [
-            {
-              Namespace: "Reventless/Runtime",
-              Dimensions: [["ApiId"]],
-              Metrics: [{ Name: "SchemaShrinkRejected", Unit: "Count" }],
-            },
-          ],
-        },
-        ApiId: apiId,
-        SchemaShrinkRejected: 1,
-        currentRootFields,
-        newRootFields,
-      })
-    );
-  } catch (_) {}
-}
-
-const DEPLOY_SCHEMA_PREFIX = "deploy-schema:";
-
-// Read every plugin's deploy-time SDL fragment from the dedicated
-// PluginSchemaPersistence table (rows keyed "deploy-schema:<name>", written by
-// Platform.preResolversSchemaHook at deploy time). begins_with("deploy-schema:")
-// matches only Domain fragments — the platform ("deploy-schema-platform:") and
-// hash ("deploy-schema-hash:") rows have a hyphen at that position, so they are
-// excluded. Each row's `fragment` attribute is the encoded SDL string; wrap it
-// in the {encoded, protocol} shape the stitcher consumes.
-async function collectDeploySchemaFragments(tableName) {
-  const rows = await scanByTableName(
-    tableName,
-    [["id", { TAG: "BeginsWith" }, { TAG: "String", _0: DEPLOY_SCHEMA_PREFIX }]],
-    1000
-  );
-  return rows
-    .map((row) =>
-      row && typeof row.fragment === "string"
-        ? { encoded: row.fragment, protocol: "graphql" }
-        : null
-    )
-    .filter(Boolean);
-}
-
 // Set at handler entry; read by runEffect to tag logs with the Lambda request id.
 let _currentRequestId = "unknown";
 
@@ -493,242 +375,6 @@ async function reconcileSubscriptionsOnce(tableName, manageSubscriptions) {
   }
 }
 
-// Re-stitch and push the live AppSync schema on each plugin Connect/Disconnect.
-//
-// Source of plugin fragments (option A): the durable PluginSchemaPersistence
-// table (deploy-time "deploy-schema:<name>" rows), NOT the lifecycle-volatile
-// Plugin RM "Connected" rows. Reading the deploy-time source means lifecycle
-// churn (a redeploy window where every plugin is briefly Disconnected, an
-// eventually-consistent scan, etc.) can no longer shrink the stitched schema —
-// every push re-asserts the full deployed set rather than clobbering field
-// resolvers with whatever subset happened to be Connected at scan time. The
-// Plugin RM scan remains only as a fallback for older platform stacks deployed
-// before the dedicated table existed (schemaTableName === "NOT_AVAILABLE").
-//
-// Circuit breaker (option D, defense-in-depth): before pushing, introspect the
-// current live schema and compare root-type (Mutation + Query) field counts. If
-// the new SDL drops below the configured fraction of the live field count, abort
-// the push, log loudly, and emit a CloudWatch metric — catching any
-// catastrophic shrink the source switch alone misses.
-function mkUpdateApiSchema(schemaTableName, apiId, clonerEnabled) {
-  if (!apiId || apiId === "NOT_AVAILABLE") return undefined;
-  const hasSchemaTable = !!schemaTableName && schemaTableName !== "NOT_AVAILABLE";
-  return async (queryEngine) => {
-    let fragments;
-    if (hasSchemaTable) {
-      fragments = await collectDeploySchemaFragments(schemaTableName);
-      log.info(`stitching ${fragments.length} deploy-schema fragment(s) from ${schemaTableName}`, { comp: "updateApiSchema" });
-    } else {
-      const resolved = await queryEngine.scan(
-        "Plugin",
-        [["status", { TAG: "Contains" }, { TAG: "String", _0: "Connected" }]],
-        1000
-      );
-      fragments = resolved.map((json) => json && json.apiSchemaFragment).filter(Boolean);
-      log.warn(`PluginSchemaPersistence table unavailable — falling back to ${fragments.length} Connected Plugin RM fragment(s)`, { comp: "updateApiSchema" });
-    }
-    const rawAdminBase = adminBaseFragment(clonerEnabled || false);
-    const adminBase = injectAwsAuthAll(rawAdminBase, "Admin");
-    // Core fragments are dialect-neutral — append @aws_subscribe from the
-    // structured subscription→mutation metadata (collected from the raw admin
-    // base + plugin fragments) onto the stitched SDL, mirroring the deploy
-    // path's stitchWithAwsDirectives.
-    const subscriptionSources = collectSubscriptionSources(rawAdminBase, fragments);
-    const sdl = injectAwsSubscribe(graphqlStitch(adminBase, fragments), subscriptionSources);
-
-    // Shrink guard — never let a transient/incomplete stitch clobber the live schema.
-    const threshold = parseShrinkThreshold(process.env["RUNTIME_SCHEMA_SHRINK_THRESHOLD"]);
-    const currentSdl = await getCurrentSchemaSdl(apiId);
-    if (isCatastrophicSchemaShrink(currentSdl, sdl, threshold)) {
-      const currentRootFields =
-        countRootTypeFields(currentSdl, "Mutation") + countRootTypeFields(currentSdl, "Query");
-      const newRootFields =
-        countRootTypeFields(sdl, "Mutation") + countRootTypeFields(sdl, "Query");
-      log.error(`ABORTED schema push for ${apiId}: new SDL has ${newRootFields} root field(s) vs ${currentRootFields} live (threshold ${threshold}). Refusing to clobber resolvers.`, { comp: "updateApiSchema" });
-      emitShrinkRejectionMetric(apiId, currentRootFields, newRootFields);
-      return;
-    }
-    await updateAppSyncSchema(apiId, sdl);
-  };
-}
-
-// ── Reactive ApiFragmentRegistry single writer (Plan 2e) ─────────────────────
-// The admin EventCollector is (as of 2e) also subscribed to the admin DcbEventLog
-// DynamoDB stream. On any ApiFragmentRegistered / ApiFragmentUpdated /
-// ApiFragmentDeregistered event, re-fold the ApiFragmentRegistry, stitch one
-// AppSync-decorated schema per target API (via the runtime-pure
-// AppSync_SdlDecorate.planAwsPushes — identical decoration to the deploy path),
-// push each with the shrink guard, and write the outcome back with
-// RecordApiFragmentPush onto the admin DCB command topic. This is ADDITIVE — the
-// legacy connect-driven mkUpdateApiSchema (deploy-schema:* → single Domain API)
-// stays until Plan Phase 4. ApiFragmentPushRecorded is intentionally NOT a
-// trigger (the write-back would otherwise loop); UiFragment* events on the same
-// stream are ignored (different prefix).
-
-const reactiveTriggerTags = new Set([
-  "ApiFragmentRegistered",
-  "ApiFragmentUpdated",
-  "ApiFragmentDeregistered",
-]);
-
-function isDynamoStreamRecord(r) {
-  return !!r && (r.eventSource === "aws:dynamodb" || r.EventSource === "aws:dynamodb");
-}
-
-// Read a DynamoDB attribute-value string, tolerating both the raw stream shape
-// ({S: "..."}) and an already-unmarshalled plain string.
-function avString(av) {
-  if (av == null) return undefined;
-  if (typeof av === "string") return av;
-  if (typeof av.S === "string") return av.S;
-  return undefined;
-}
-
-// Pull the {encoded, protocol} fragment out of an event's `data` attribute
-// (raw {M:{...}} or unmarshalled object), reading the named fragment field
-// (`fragment` for Registered, `newFragment` for Updated).
-function readFragmentField(dataAv, fieldName) {
-  const data = dataAv && dataAv.M ? dataAv.M : dataAv;
-  if (!data || typeof data !== "object") return null;
-  const fragAv = data[fieldName];
-  const frag = fragAv && fragAv.M ? fragAv.M : fragAv;
-  if (!frag || typeof frag !== "object") return null;
-  const encoded = avString(frag.encoded);
-  if (typeof encoded !== "string" || encoded.length === 0) return null;
-  return { encoded, protocol: avString(frag.protocol) || "graphql" };
-}
-
-// Scan the raw stream records for ApiFragment* trigger events; return one entry
-// per event carrying the pluginId and the fragment override the event asserts
-// (or {remove:true} for a deregistration). The override lets the push reflect
-// the just-happened change even if the ApiFragments projection (a separate
-// stream consumer) hasn't caught up yet — the plan's "stitch from consistent
-// state, not an eventually-consistent RM scan".
-function detectApiFragmentTriggers(records) {
-  const out = [];
-  for (const r of records || []) {
-    if (!isDynamoStreamRecord(r)) continue;
-    const img = r.dynamodb && r.dynamodb.NewImage;
-    if (!img) continue;
-    const tag = avString(img.event);
-    if (!tag || !reactiveTriggerTags.has(tag)) continue;
-    const dataAv = img.data;
-    const dataObj = dataAv && dataAv.M ? dataAv.M : dataAv;
-    let pluginId =
-      (dataObj && dataObj.pluginId && avString(dataObj.pluginId)) || avString(img.tag_pluginId);
-    if (!pluginId) continue;
-    if (tag === "ApiFragmentDeregistered") {
-      out.push({ pluginId, remove: true });
-    } else {
-      const fieldName = tag === "ApiFragmentUpdated" ? "newFragment" : "fragment";
-      const frag = readFragmentField(dataAv, fieldName);
-      const target = (dataObj && avString(dataObj.apiTarget)) === "Platform" ? "Platform" : "Domain";
-      out.push(frag ? { pluginId, encoded: frag.encoded, protocol: frag.protocol, target } : { pluginId });
-    }
-  }
-  return out;
-}
-
-// Enqueue one RecordApiFragmentPush per distinct triggering plugin onto the admin
-// DCB command topic (FIFO, MessageGroupId = pluginId). RecordApiFragmentPush is
-// @noApi and idempotent — a no-op in the slice behaviour if the plugin was
-// deregistered in the meantime.
-async function recordPushOutcomes(recordPublisher, pluginIds, ok, message) {
-  if (!recordPublisher || pluginIds.length === 0) return;
-  const at = new Date().toISOString();
-  const commandJsons = pluginIds.map((pluginId) => ({
-    id: pluginId,
-    // toMessageBody re-stamps msgId (uuid) + time (now); service + correlationId are required.
-    meta: { service: "AdminEventCollector", time: at, msgId: "pending", correlationId: pluginId },
-    commandJson: { TAG: "RecordApiFragmentPush", pluginId, ok, message, at },
-  }));
-  try {
-    await recordPublisher(commandJsons);
-  } catch (e) {
-    log.error(`RecordApiFragmentPush dispatch failed: ${(e && e.message) || e}`, { comp: "reactiveApiPush" });
-  }
-}
-
-function mkReactiveApiSchemaPush(config) {
-  const tableName = config.apiFragmentRegistryTableName;
-  const adminDcbUrl = config.adminDcbCmdTopicUrl;
-  // Only the admin EventCollector carries a real registry table + admin DCB topic.
-  if (!tableName || tableName === "NOT_AVAILABLE" || !adminDcbUrl || adminDcbUrl === "NOT_AVAILABLE") {
-    return undefined;
-  }
-  const domainApiId = config.appSyncApiId;
-  // In unified mode platformApiId is unset/"NOT_AVAILABLE" and every plan targets the Domain API.
-  const platformApiId =
-    config.platformApiId && config.platformApiId !== "NOT_AVAILABLE"
-      ? config.platformApiId
-      : domainApiId;
-  const splitApi = !!config.splitApi;
-  const clonerEnabled = config.clonerEnabled || false;
-  const recordPublisher = sqsPublishJsons(makeQueueRef(adminDcbUrl), "SQS_FIFO");
-
-  return async (triggers) => {
-    const pluginIds = [...new Set(triggers.map((t) => t.pluginId))];
-    // 1. Fold the registry: RM scan for all plugins, overlaid with this batch's
-    //    own asserted fragments (closes the projection-lag race for the trigger).
-    const byId = new Map();
-    try {
-      const rows = await scanByTableName(tableName, [], 1000);
-      for (const row of rows) {
-        if (!row || typeof row.pluginId !== "string" || typeof row.encoded !== "string" || !row.encoded) continue;
-        byId.set(row.pluginId, {
-          encoded: row.encoded,
-          protocol: typeof row.protocol === "string" ? row.protocol : "graphql",
-          target: row.apiTarget === "Platform" ? "Platform" : "Domain",
-        });
-      }
-    } catch (e) {
-      const msg = `ApiFragments scan failed: ${(e && e.message) || e}`;
-      log.error(msg, { comp: "reactiveApiPush" });
-      await recordPushOutcomes(recordPublisher, pluginIds, false, msg);
-      return;
-    }
-    for (const t of triggers) {
-      if (t.remove) byId.delete(t.pluginId);
-      else if (t.encoded) byId.set(t.pluginId, { encoded: t.encoded, protocol: t.protocol, target: t.target });
-    }
-    const fragments = [...byId.values()];
-
-    // 2. Plan one AWS-decorated push per target API.
-    const rawAdminBase = adminBaseFragment(clonerEnabled);
-    const plans = planAwsPushes(rawAdminBase, systemCallerFieldNames, fragments, splitApi);
-
-    // 3. Push each plan behind the shrink guard.
-    let ok = true;
-    let message = "";
-    for (const plan of plans) {
-      const apiId = plan.api === "PlatformApi" ? platformApiId : domainApiId;
-      if (!apiId || apiId === "NOT_AVAILABLE") continue;
-      const threshold = parseShrinkThreshold(process.env["RUNTIME_SCHEMA_SHRINK_THRESHOLD"]);
-      const currentSdl = await getCurrentSchemaSdl(apiId);
-      if (isCatastrophicSchemaShrink(currentSdl, plan.sdl, threshold)) {
-        const cur = countRootTypeFields(currentSdl, "Mutation") + countRootTypeFields(currentSdl, "Query");
-        const nw = countRootTypeFields(plan.sdl, "Mutation") + countRootTypeFields(plan.sdl, "Query");
-        log.error(`ABORTED reactive push for ${plan.api} (${apiId}): ${nw} root field(s) vs ${cur} live (threshold ${threshold}).`, { comp: "reactiveApiPush" });
-        emitShrinkRejectionMetric(apiId, cur, nw);
-        ok = false;
-        message = `shrink guard aborted push for ${plan.api}`;
-        continue;
-      }
-      try {
-        await updateAppSyncSchema(apiId, plan.sdl);
-        log.info(`reactive schema push OK: ${plan.api} (${apiId})`, { comp: "reactiveApiPush" });
-      } catch (e) {
-        ok = false;
-        message = (e && e.message) || String(e);
-        log.error(`reactive schema push FAILED: ${plan.api} (${apiId}): ${message}`, { comp: "reactiveApiPush" });
-      }
-    }
-
-    // 4. Write the outcome back per triggering plugin (the deploy waiter polls this).
-    await recordPushOutcomes(recordPublisher, pluginIds, ok, message);
-  };
-}
-
 function buildPublishToAggregates(map) {
   const out = {};
   for (const [aggName, envVarName] of Object.entries(map || {})) {
@@ -848,14 +494,6 @@ async function buildHandler() {
       }]
     : [];
 
-  const updateApiSchemaFn = mkUpdateApiSchema(
-    config.pluginSchemaPersistenceTableName,
-    config.appSyncApiId,
-    config.clonerEnabled,
-  );
-
-  const reactiveApiSchemaPush = mkReactiveApiSchemaPush(config);
-
   const manageSubscriptionsFn = mkManageSubscriptions(config.pluginReadModelTableName);
 
   // EP operations — admin has 1 entry (Plugin EP), plugins have N user EPs.
@@ -884,7 +522,9 @@ async function buildHandler() {
       const epModule = mappingsMod.Make({
         runtimeOps,
         environment: lambdaFunctionName,
-        updateApiSchema: updateApiSchemaFn,
+        // Connect-driven schema self-heal retired (Phase 4b) — the ApiSchemaPush
+        // SideEffect on ApiFragmentRegistry events is the single schema writer.
+        updateApiSchema: undefined,
         manageSubscriptions: manageSubscriptionsFn,
       });
       mappingsModule = { mappings: [epModule.Mapping] };
@@ -1074,7 +714,7 @@ async function buildHandler() {
   await reconcileSubscriptionsOnce(config.pluginReadModelTableName, manageSubscriptionsFn);
 
   const sqsHandler = handleDynamoDbOrSqsEvent(makeQueueRef(config.queueUrl), callback.handleJsonEvents);
-  return { sqsHandler, reactiveApiSchemaPush };
+  return { sqsHandler };
 }
 
 const handlerBundlePromise = buildHandler();
@@ -1084,22 +724,7 @@ export async function handler(event, context) {
   const records = event.Records || [];
   const correlationId = extractCorrelationId(records);
   log.debug("processing " + records.length.toString() + " record(s)", { comp: "PluginEventCollectorRuntime" });
-  const { sqsHandler, reactiveApiSchemaPush } = await handlerBundlePromise;
-  if (reactiveApiSchemaPush) {
-    // Admin EC: DcbEventLog stream records drive the reactive ApiFragmentRegistry
-    // push; everything else (Plugin-aggregate lifecycle delivered SNS→SQS) goes to
-    // the plugin callback as before. Splitting keeps unrelated DCB-slice stream
-    // events out of the callback, which has no handler for them. (A Lambda batch
-    // is single-source, so in practice exactly one branch has records.)
-    const streamRecords = records.filter(isDynamoStreamRecord);
-    const otherRecords = records.filter((r) => !isDynamoStreamRecord(r));
-    if (otherRecords.length > 0) {
-      await runEffect(correlationId, sqsHandler({ ...event, Records: otherRecords }, context));
-    }
-    const triggers = detectApiFragmentTriggers(streamRecords);
-    if (triggers.length > 0) await reactiveApiSchemaPush(triggers);
-  } else {
-    await runEffect(correlationId, sqsHandler(event, context));
-  }
+  const { sqsHandler } = await handlerBundlePromise;
+  await runEffect(correlationId, sqsHandler(event, context));
   return "";
 }

package/src/adapter/Runtime/ApiSchemaPush_Runtime.mjs

@@ -134,7 +134,14 @@ async function recordPushOutcomes(cmdTopicUrl, pluginIds, ok, message) {
   const at = new Date().toISOString();
   const commandJsons = pluginIds.map((pluginId) => ({
     id: "registry",
-    meta: { service: "ApiFragmentRegistry", time: at, msgId: "pending", correlationId: pluginId },
+    // msgId MUST be unique per message: it becomes the SQS SendMessageBatch entry Id (and the
+    // FIFO MessageDeduplicationId). A shared placeholder made every entry collide in one batch
+    // ("Id pending repeated" → the whole write-back failed → the deploy waiter timed out even
+    // though the schema push itself succeeded). pluginId is unique per message; `at` keeps it
+    // unique across pushes (and gives distinct FIFO dedup ids so a later re-push isn't dropped).
+    // Sanitize: an SQS batch-entry Id only allows [A-Za-z0-9_-] (≤80 chars), so the ISO
+    // timestamp's `:`/`.` must be replaced or SQS rejects the whole batch.
+    meta: { service: "ApiFragmentRegistry", time: at, msgId: `push-${pluginId}-${at}`.replace(/[^A-Za-z0-9_-]/g, "-"), correlationId: pluginId },
     commandJson: { TAG: "RecordApiFragmentPush", pluginId, ok, message, at },
   }));
   try {