@assembly-js/app-foundation 0.0.2 → 0.0.4

package/bin/validate-manifest.mjs

@@ -0,0 +1,1151 @@
+#!/usr/bin/env node
+// Validates .assembly/app.json shape at build time so malformed or misplaced
+// manifest keys fail the build loudly instead of being silently dropped at
+// deploy (where unknown keys vanish and surface URLs end up empty). Dependency
+// free on purpose: it runs inside the generated app's sandbox before any deps
+// beyond Node are guaranteed.
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const MANIFEST = join(process.cwd(), '.assembly', 'app.json');
+// requiredIntegrations and notificationSettings are parsed by the platform's
+// deploy pipeline; rejecting them here would fail builds for manifests the
+// platform understands.
+const TOP_LEVEL_KEYS = ['surfaces', 'requiredSecrets', 'requiredIntegrations', 'notificationSettings'];
+const SURFACE_KEYS = ['internal', 'client', 'notification'];
+const NOTIFICATION_SURFACES = ['product', 'email'];
+const MAX_NOTIFICATION_SETTINGS = 50;
+// Setting ids are permanent: they key each internal user's saved toggles and
+// are passed as notificationSettingId on createNotification, so the validator
+// requires stable author-chosen ids instead of letting the platform generate
+// ones that would rotate on every deploy.
+const KEBAB_ID = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+function fail(lines) {
+  console.error('');
+  console.error('.assembly/app.json is invalid:');
+  console.error('');
+  for (const l of lines) console.error('  - ' + l);
+  console.error('');
+  console.error('Expected shape:');
+  console.error('  {');
+  console.error('    "surfaces": { "internal": { "path": "/" }, "client": { "path": "/c" }, "notification": { "path": "/n" } },');
+  console.error('    "requiredSecrets": [{ "key": "STRIPE_KEY", "label": "Stripe secret key" }],');
+  console.error('    "requiredIntegrations": [{ "provider": "slack", "scopes": ["chat:write"] }]');
+  console.error('  }');
+  console.error('Only "internal" is required. "client" and "notification" are optional and MUST live under "surfaces".');
+  console.error('Optional top-level keys: "requiredSecrets", "requiredIntegrations", "notificationSettings" (schemas in .claude/skills).');
+  process.exit(1);
+}
+
+if (!existsSync(MANIFEST)) {
+  // A missing manifest is handled at deploy time (internal-only fallback); it
+  // is not a build error. This check targets present-but-malformed manifests.
+  process.exit(0);
+}
+
+let raw;
+try {
+  raw = readFileSync(MANIFEST, 'utf8');
+} catch (e) {
+  fail(['could not read the file: ' + e.message]);
+}
+
+let doc;
+try {
+  doc = JSON.parse(raw);
+} catch (e) {
+  fail(['not valid JSON: ' + e.message]);
+}
+
+if (typeof doc !== 'object' || doc === null || Array.isArray(doc)) {
+  fail(['the top level must be a JSON object']);
+}
+
+const errors = [];
+
+// Unknown or misplaced top-level keys. A surface name appearing at the top
+// level is the exact mistake that silently broke notification links.
+for (const key of Object.keys(doc)) {
+  if (TOP_LEVEL_KEYS.includes(key)) continue;
+  if (SURFACE_KEYS.includes(key)) {
+    errors.push(
+      '"' +
+        key +
+        '" is at the top level but is a surface — move it under "surfaces" (i.e. surfaces.' +
+        key +
+        ').',
+    );
+  } else {
+    errors.push(
+      'unknown top-level key "' + key + '" (allowed: ' + TOP_LEVEL_KEYS.join(', ') + ').',
+    );
+  }
+}
+
+// surfaces
+if (doc.surfaces === undefined) {
+  errors.push('"surfaces" is required (must declare at least surfaces.internal).');
+} else {
+  const s = doc.surfaces;
+  if (typeof s !== 'object' || s === null || Array.isArray(s)) {
+    errors.push('"surfaces" must be an object.');
+  } else {
+    for (const key of Object.keys(s)) {
+      if (!SURFACE_KEYS.includes(key)) {
+        errors.push(
+          'unknown surface "' + key + '" under "surfaces" (allowed: ' + SURFACE_KEYS.join(', ') + ').',
+        );
+        continue;
+      }
+      const entry = s[key];
+      if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+        errors.push('surfaces.' + key + ' must be an object like { "path": "/..." }.');
+        continue;
+      }
+      if (typeof entry.path !== 'string' || entry.path.length === 0) {
+        errors.push('surfaces.' + key + '.path is required and must be a non-empty string.');
+      } else if (entry.path[0] !== '/') {
+        errors.push('surfaces.' + key + '.path must start with "/" (got "' + entry.path + '").');
+      }
+    }
+    if (s.internal === undefined) {
+      errors.push('surfaces.internal is required — every app must declare a dashboard surface.');
+    }
+  }
+}
+
+// requiredSecrets (optional; mirrors the deploy-side key/label requirement)
+if (doc.requiredSecrets !== undefined) {
+  const rs = doc.requiredSecrets;
+  if (!Array.isArray(rs)) {
+    errors.push('"requiredSecrets" must be an array.');
+  } else {
+    rs.forEach((item, i) => {
+      if (typeof item !== 'object' || item === null || Array.isArray(item)) {
+        errors.push('requiredSecrets[' + i + '] must be an object with "key" and "label".');
+        return;
+      }
+      if (typeof item.key !== 'string' || item.key.trim() === '') {
+        errors.push('requiredSecrets[' + i + '].key is required and must be a non-empty string.');
+      }
+      if (typeof item.label !== 'string' || item.label.trim() === '') {
+        errors.push('requiredSecrets[' + i + '].label is required and must be a non-empty string.');
+      }
+    });
+  }
+}
+
+// notificationSettings (optional; mirrors POST /v1/installs/{installId}/notification-settings)
+if (doc.notificationSettings !== undefined) {
+  const ns = doc.notificationSettings;
+  if (typeof ns !== 'object' || ns === null || Array.isArray(ns)) {
+    errors.push('"notificationSettings" must be an object like { "notifications": [ ... ] }.');
+  } else {
+    for (const key of Object.keys(ns)) {
+      if (!['notifications', 'actionLabel'].includes(key)) {
+        errors.push('unknown key "notificationSettings.' + key + '" (allowed: notifications, actionLabel).');
+      }
+    }
+    if (!Array.isArray(ns.notifications) || ns.notifications.length === 0) {
+      errors.push('notificationSettings.notifications must be a non-empty array of settings.');
+    } else {
+      if (ns.notifications.length > MAX_NOTIFICATION_SETTINGS) {
+        errors.push(
+          'notificationSettings.notifications has ' +
+            ns.notifications.length +
+            ' entries; the platform allows at most ' +
+            MAX_NOTIFICATION_SETTINGS +
+            '.',
+        );
+      }
+      const seen = new Set();
+      ns.notifications.forEach((setting, i) => {
+        const at = 'notificationSettings.notifications[' + i + ']';
+        if (typeof setting !== 'object' || setting === null || Array.isArray(setting)) {
+          errors.push(at + ' must be an object with "id", "label", and "surfaces".');
+          return;
+        }
+        if (typeof setting.id !== 'string' || !KEBAB_ID.test(setting.id)) {
+          errors.push(
+            at +
+              '.id is required and must be kebab-case (e.g. "task-completed"). Ids are permanent — ' +
+              "they key each internal user's saved toggles and are passed as notificationSettingId " +
+              'when creating notifications.',
+          );
+        } else if (seen.has(setting.id)) {
+          errors.push(at + '.id "' + setting.id + '" is declared more than once — ids must be unique.');
+        } else {
+          seen.add(setting.id);
+        }
+        if (typeof setting.label !== 'string' || setting.label.trim() === '' || setting.label.length > 100) {
+          errors.push(at + '.label is required and must be a non-empty string of at most 100 characters.');
+        }
+        const surfaces = Array.isArray(setting.surfaces) ? setting.surfaces : null;
+        if (
+          !surfaces ||
+          surfaces.length === 0 ||
+          surfaces.some((v) => !NOTIFICATION_SURFACES.includes(v)) ||
+          new Set(surfaces).size !== surfaces.length
+        ) {
+          errors.push(
+            at + '.surfaces must be a non-empty array of unique values from: ' + NOTIFICATION_SURFACES.join(', ') + '.',
+          );
+        }
+        if (setting.default !== undefined) {
+          if (typeof setting.default !== 'object' || setting.default === null || Array.isArray(setting.default)) {
+            errors.push(at + '.default must be an object like { "product": true, "email": false }.');
+          } else {
+            for (const key of Object.keys(setting.default)) {
+              if (!NOTIFICATION_SURFACES.includes(key)) {
+                errors.push(at + '.default has unknown key "' + key + '" (allowed: product, email).');
+              } else if (typeof setting.default[key] !== 'boolean') {
+                errors.push(at + '.default.' + key + ' must be a boolean.');
+              } else if (setting.default[key] === true && surfaces && !surfaces.includes(key)) {
+                errors.push(
+                  at +
+                    '.default.' +
+                    key +
+                    ' is true but "' +
+                    key +
+                    '" is not in ' +
+                    at +
+                    '.surfaces — a surface can only default on when the setting declares it.',
+                );
+              }
+            }
+          }
+        }
+      });
+    }
+    if (ns.actionLabel !== undefined) {
+      const al = ns.actionLabel;
+      if (typeof al !== 'object' || al === null || Array.isArray(al)) {
+        errors.push('notificationSettings.actionLabel must be an object with "verb", "singularNoun", and "pluralNoun".');
+      } else {
+        for (const field of ['verb', 'singularNoun', 'pluralNoun']) {
+          if (typeof al[field] !== 'string' || al[field].trim() === '') {
+            errors.push(
+              'notificationSettings.actionLabel.' +
+                field +
+                ' is required and must be a non-empty string (or omit actionLabel entirely).',
+            );
+          }
+        }
+        for (const key of Object.keys(al)) {
+          if (!['verb', 'singularNoun', 'pluralNoun'].includes(key)) {
+            errors.push('notificationSettings.actionLabel has unknown key "' + key + '".');
+          }
+        }
+      }
+    }
+  }
+}
+
+// requiredIntegrations (optional; mirrors the deploy-side structural rules —
+// the provider whitelist itself is enforced at deploy from the live catalog).
+// connectionScope/cardinality are reserved hinges: only their v1 values pass,
+// so a manifest authored today can't change meaning when later phases land.
+if (doc.requiredIntegrations !== undefined) {
+  const ri = doc.requiredIntegrations;
+  const ENTRY_KEYS = ['provider', 'scopes', 'connectionScope', 'cardinality'];
+  if (!Array.isArray(ri)) {
+    errors.push('"requiredIntegrations" must be an array.');
+  } else {
+    ri.forEach((item, i) => {
+      if (typeof item !== 'object' || item === null || Array.isArray(item)) {
+        errors.push('requiredIntegrations[' + i + '] must be an object with a "provider".');
+        return;
+      }
+      for (const key of Object.keys(item)) {
+        if (!ENTRY_KEYS.includes(key)) {
+          errors.push('requiredIntegrations[' + i + '] has unknown key "' + key + '" (allowed: ' + ENTRY_KEYS.join(', ') + ').');
+        }
+      }
+      if (typeof item.provider !== 'string' || item.provider.trim() === '') {
+        errors.push('requiredIntegrations[' + i + '].provider is required and must be a non-empty string.');
+      }
+      if (item.scopes !== undefined) {
+        if (!Array.isArray(item.scopes) || item.scopes.some((sc) => typeof sc !== 'string' || sc.trim() === '')) {
+          errors.push('requiredIntegrations[' + i + '].scopes must be an array of non-empty strings.');
+        }
+      }
+      if (item.connectionScope !== undefined && item.connectionScope !== 'workspace') {
+        errors.push('requiredIntegrations[' + i + '].connectionScope "' + item.connectionScope + '" is not supported: only "workspace" (per-user connections are not yet available).');
+      }
+      if (item.cardinality !== undefined && item.cardinality !== 'single') {
+        errors.push('requiredIntegrations[' + i + '].cardinality "' + item.cardinality + '" is not supported: only "single" (multiple connections per provider are not yet available).');
+      }
+    });
+  }
+}
+
+if (errors.length > 0) fail(errors);
+
+// ---------------------------------------------------------------------------
+// .assembly/api-resources.json — the app's API contract (automation triggers,
+// actions, webhook events). A missing file means the app registers no API and
+// is always valid. When present, every rule below mirrors the platform's
+// publish-gate parser (backend/lib/resources/app_builder/logic/
+// app_api_resources.go) so the agent gets the same errors in its own build
+// loop instead of at publish. The data tables between the GENERATED markers
+// are rendered from the Go rules (drift fails the platform's unit tests); the
+// procedural checks hand-mirror the parser's logic.
+// ---------------------------------------------------------------------------
+
+// BEGIN GENERATED FROM GO - DO NOT EDIT (rendered by validator_rules_golden_unit_test.go; regenerate: make generate-validator-rules)
+
+const API_RESOURCES = join(process.cwd(), '.assembly', 'api-resources.json');
+
+const API_RESOURCES_MAX_FILE_BYTES = 131072;
+const MAX_RECORDS = 20;
+const MAX_APIS_PER_RECORD = 25;
+const MAX_WEBHOOKS_PER_RECORD = 25;
+const MAX_SCHEMA_FIELDS = 50;
+const MAX_SCHEMA_NESTING_DEPTH = 3;
+const MAX_QUERY_PARAMS = 20;
+const MAX_NAME_LENGTH = 128;
+const MAX_DESC_LENGTH = 512;
+const MAX_ACTION_DESC_LENGTH = 40;
+const MAX_PATH_LENGTH = 512;
+
+const RESOURCE_NAME_RE = /^[a-z][a-zA-Z0-9]{1,63}$/;
+const EVENT_NAME_RE = /^[a-zA-Z0-9]+\.[a-zA-Z0-9]+$/;
+const API_PATH_RE = /^(\/[a-z0-9\-_]+)+(\/:id)?$/;
+
+const ALLOWED_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+const ALLOWED_OUTPUT_TYPES = ['object', 'list', 'delete', 'void'];
+const ALLOWED_INPUT_TYPES = ['object', 'list'];
+const ALLOWED_QUERY_PARAM_TYPES = ['string', 'int', 'boolean'];
+const ALLOWED_FIELD_TYPES = ['string', 'number', 'bool', 'object', 'array'];
+const ALLOWED_UI_TYPES = ['textInput', 'textArea', 'dropdown', 'numberInput', 'dateInput'];
+const ALLOWED_FIELD_OPERATORS = ['exists', 'notExists', 'equals', 'notEquals', 'startsWith', 'includes'];
+// The proxy's legacy fallback matches these by SUBSTRING, so a path merely
+// containing one would be misrouted to the platform's Tasks app.
+const RESERVED_TASK_SEGMENTS = ['tasks', 'task-templates', 'comments'];
+// Automations read recipient ids from payloads by exact camelCase name.
+const RECIPIENT_FIELD_NAMES = ['clientId', 'companyId', 'internalUserId'];
+const DROPDOWN_SOURCE_INPUT_TYPES = ['client', 'company', 'internalUser', 'allClients', 'allCompanies', 'allInternalUsers'];
+const DROPDOWN_SOURCE_RECIPIENT_FIELDS = {
+  client: 'clientId',
+  company: 'companyId',
+  internalUser: 'internalUserId',
+  allClients: 'clientId',
+  allCompanies: 'companyId',
+  allInternalUsers: 'internalUserId',
+};
+
+// Design-system icon names a trigger.icon may use — the only names the
+// automations UI renders (lib/ai's curated DSIconNames set).
+const TRIGGER_ICON_NAMES = [
+  'Info', 'InfoSolid', 'Search', 'ResetZoom', 'FitToWidth',
+  'Ellipsis', 'MoreVertical', 'Download', 'Upload', 'Edit',
+  'Plus', 'Minus', 'Trash', 'ChevronRight', 'ChevronUp',
+  'ChevronDown', 'ChevronLeft', 'Copy', 'Duplicate', 'Automation',
+  'Play', 'Pause', 'Scale', 'Form', 'Message',
+  'Contract', 'Profile', 'Building', 'InvoicePaid', 'EditSolid',
+  'Archive', 'Unarchive', 'Settings', 'SettingsSolid', 'Link',
+  'Attachment', 'Close', 'Cancel', 'Smile', 'Share',
+  'Reply', 'Calendar', 'At', 'List', 'NumberedList',
+  'UnorderedList', 'Checklist', 'Tasks', 'Filter', 'Templates',
+  'Star', 'Email', 'EmailUnread', 'EmailRead', 'H1',
+  'H2', 'H3', 'Text', 'Bold', 'Italicize',
+  'Underline', 'Strikethrough', 'Menu', 'Inbox', 'Home',
+  'Notification', 'Billing', 'Dollar', 'Helpdesk', 'AppSetup',
+  'Gift', 'Location', 'Number', 'MobileNumber', 'Bank',
+  'Puzzle', 'Code', 'ArrowUpSolid', 'ArrowDownSolid', 'ArrowLeft',
+  'ArrowRight', 'ArrowNE', 'Dash', 'Compose', 'MassFileShare',
+  'Warning', 'WarningSolid', 'Failed', 'FailedSolid', 'Check',
+  'Success', 'SuccessSolid', 'New', 'ToDo', 'InProgress',
+  'Book', 'Send', 'SendFilled', 'Dot', 'SquareSolid',
+  'Eye', 'EyeHidden', 'Invoice', 'Comment', 'Invite',
+  'Spinner', 'Repeat', 'Web', 'Time', 'GraphBarSolid',
+  'Sidebar', 'SidebarFilled', 'Export', 'File', 'MP4',
+  'SVG', 'MOV', 'MP3', 'CSV', 'Excel',
+  'PNG', 'PDF', 'JPG', 'Doc', 'ZIP',
+  'Movie', 'GIF', 'Store', 'ShoppingBag', 'DragDrop',
+  'Image', 'ImageMissing', 'LogOut', 'Lead', 'QuestionMark',
+  'API', 'PlansPayments', 'Customization', 'Teams', 'AI',
+  'BracketsCurly', 'Callout', 'Table', 'Chart', 'Tag',
+  'ThumbsUp', 'ThumbsDown', 'CaretDown', 'CaretUp', 'CaretRight',
+  'Disconnect', 'Mention', 'Insert', 'AssemblyLogo', 'Reposition',
+  'Marketing', 'Gauge', 'Subtask', 'Compass', 'UnPin',
+  'Pin', 'Files', 'FolderLocked', 'Unlock', 'Authentication',
+  'LockFilled', 'Reverse', 'AuditLog', 'Subscription', 'Note',
+  'Accessibility', 'Plane', 'AlarmClock', 'Football', 'Aperture',
+  'BagShoppingPlus', 'BagShoppingMinus', 'Balloon', 'Bandage', 'Dumbbell',
+  'BarcodeRead', 'Baseball', 'BasketShoppingSimple', 'Basketball', 'Flask',
+  'BedFront', 'BeerMug', 'PersonBiking', 'Ship', 'FireSmoke',
+  'Bookmark', 'BowlingBall', 'Briefcase', 'WindowMaximize', 'PaintbrushFine',
+  'Bug', 'Wrench', 'Lightbulb', 'Bus', 'Buildings',
+  'Mug', 'Calculator', 'CalendarDays', 'Camera', 'CameraRotate',
+  'Car', 'CartShopping', 'MoneyBills', 'SignalBars', 'MessageDots',
+  'CommentDots', 'Messages', 'Cloud', 'CloudMoon', 'Fill',
+  'Palette', 'WandMagicSparkles', 'ScrewdriverWrench', 'Scissors', 'Desktop',
+  'DiceFive', 'BullseyeArrow', 'FileLines', 'Ear', 'EarthAmericas',
+  'PresentationScreen', 'Egg', 'EyeDropper', 'BurgerFries', 'Venus',
+  'InboxFull', 'Inboxes', 'Film', 'Fingerprint', 'FishFins',
+  'HeartPulse', 'Flag', 'Fire', 'BoltSlash', 'Flashlight',
+  'Flower', 'FolderOpen', 'Soccer', 'ShoePrints', 'GamepadModern',
+  'CodeBranch', 'CodeCommit', 'CodeCompare', 'CodeMerge', 'CodeFork',
+  'CodePullRequest', 'Glasses', 'GolfFlagHole', 'GridFourSquares', 'Hammer',
+  'Hand', 'Microchip', 'Headphones', 'Heart', 'HeartHalfStroke',
+  'LifeRing', 'SquareQuestion', 'Question', 'HourglassHalf', 'IceCream',
+  'IdBadge', 'ImageNotFilled', 'Images', 'Infinity', 'KeyboardBrightness',
+  'Key', 'Dialpad', 'Language', 'Laptop', 'LayerGroup',
+  'Leaf', 'LocationCrosshairs', 'Magnet', 'MarsAndVenus', 'Mars',
+  'PersonSimple', 'Map', 'Medal', 'Asterisk', 'BriefcaseMedical',
+  'Bullhorn', 'Moon', 'MusicNote', 'Music', 'LocationArrow',
+  'Newspaper', 'AppleWhole', 'CloudSun', 'SolarSystem', 'Paw',
+  'Mobile', 'Glass', 'PizzaSlice', 'PlanetRinged', 'ChartSimpleHorizontal',
+  'Tags', 'Print', 'WavePulse', 'Qrcode', 'RecordVinyl',
+  'SignalStream', 'Voicemail', 'ForkKnife', 'AwardSimple', 'Rocket',
+  'FaceFrownSlight', 'FloppyDisk', 'WeightScale', 'GraduationCap', 'Coins',
+  'ShareNodes', 'ShieldCheck', 'Shield', 'ShieldHalf', 'Shirt',
+  'Snowflake', 'SquareOutline', 'StarHalf', 'Stopwatch', 'Brightness',
+  'Autoresponder', 'RectangleWide', 'TennisBall', 'Telescope', 'TemperatureThreeQuarters',
+  'CloudBolt', 'Ticket', 'Timer', 'ToggleOn', 'SignPost',
+  'Train', 'Transgender', 'ArrowTrendDown', 'ArrowTrendUp', 'Triangle',
+  'Trophy', 'Tv', 'Umbrella', 'Video', 'PersonWalking',
+  'Wallet', 'WatchApple', 'Droplet', 'MartiniGlassEmpty', 'PersonDress',
+  'ImageStack', 'FontCase', 'HubspotMeetings', 'Notion', 'Loom',
+  'Calendly', 'Typeform', 'OneDrive', 'ClickUp', 'YouTube',
+  'Monday', 'Databox', 'Figma', 'PowerBi', 'Airtable',
+  'Zoom', 'QuickBook', 'Canva', 'Xero', 'AcuityScheduling',
+  'Trello', 'Slack', 'Zapier', 'Exporter', 'TokenInspector',
+  'Jotform', 'GoogleDrive', 'GoogleCalendar', 'CalCom', 'EmbedsLinks',
+  'Miro', 'Dropbox', 'Make', 'CustomApps', 'GoogleSheets',
+  'GoogleDocs', 'GoogleSlides', 'Instagram', 'X', 'Facebook',
+  'LinkedIn', 'FolderMove', 'Details',
+];
+const TRIGGER_ICON_SET = new Set(TRIGGER_ICON_NAMES);
+
+// Native platform event names (and their namespaces) app events must not
+// shadow — emitted from lib/constants' webhook-eligible event lists.
+const NATIVE_EVENT_NAMES = [
+  'client.created', 'client.activated', 'client.updated', 'client.customFields.updated', 'client.deleted',
+  'company.created', 'company.updated', 'company.customFields.updated', 'company.deleted', 'formResponse.completed',
+  'file.created', 'file.updated', 'file.deleted', 'link.created', 'link.updated',
+  'link.deleted', 'folder.created', 'folder.updated', 'folder.deleted', 'message.sent',
+  'contract.signed', 'notification.created', 'contract.requested', 'messageChannel.created', 'messageChannel.deleted',
+  'invoice.paid', 'internalUser.deleted', 'internalUser.created', 'product.created', 'product.updated',
+  'price.created', 'invoice.created', 'invoice.voided', 'invoice.deleted', 'invoice.sent',
+  'invoice.updated', 'note.created', 'note.updated', 'note.deleted', 'payment.succeeded',
+  'payment.failed', 'payout.reconciliation_completed', 'refund.requested', 'refund.succeeded', 'refund.failed',
+  'subscription.created', 'subscription.canceled', 'event.created', 'task.created', 'task.archived',
+  'task.completed', 'task.updated', 'task.deleted', 'comment.created',
+];
+const NATIVE_EVENTS_LOWER = new Set(NATIVE_EVENT_NAMES.map((n) => n.toLowerCase()));
+const NATIVE_NAMESPACES_LOWER = new Set(NATIVE_EVENT_NAMES.map((n) => n.toLowerCase().split('.')[0]));
+
+// The strict-decode mirror: allowed keys per node, from the DTOs' json tags.
+// A config-UI key on a record-level schema field is an error, not dead data —
+// the two positions have different shapes on purpose.
+const API_RESOURCES_TOP_LEVEL_KEYS = ['apiResources'];
+const RECORD_KEYS = ['name', 'resourceName', 'baseUrl', 'schema', 'apis', 'webhooks'];
+const RECORD_FIELD_KEYS = ['fieldName', 'fieldType', 'label', 'description', 'isDate', 'optional'];
+const RECORD_SCHEMA_FIELD_KEYS = [...RECORD_FIELD_KEYS, 'nestedFieldSchema'];
+const INPUT_FIELD_KEYS = [...RECORD_FIELD_KEYS, 'placeholder', 'options', 'dynamicOptions', 'dropdownSource', 'automationSettings'];
+const API_KEYS = ['name', 'description', 'method', 'path', 'paginated', 'queryParams', 'input', 'output', 'exposeToAutomations'];
+const QUERY_PARAM_KEYS = ['type', 'enum', 'min', 'max'];
+const INPUT_KEYS = ['type', 'schema'];
+const OUTPUT_KEYS = ['type'];
+const WEBHOOK_KEYS = ['eventName', 'eventDescription', 'trigger'];
+const TRIGGER_KEYS = ['name', 'description', 'icon', 'configuration', 'snapshotCxt'];
+const TRIGGER_CONFIG_KEYS = ['id', 'label', 'description', 'fieldProperty', 'fieldType', 'fieldOperator', 'type', 'required', 'addAnyOption', 'options', 'dynamicOptions'];
+const SNAPSHOT_KEYS = ['label', 'property'];
+const OPTION_KEYS = ['id', 'name'];
+const DYNAMIC_OPTIONS_KEYS = ['requestUrl', 'nameField'];
+const DROPDOWN_SOURCE_KEYS = ['inputType', 'fieldName'];
+const AUTOMATION_SETTINGS_KEYS = ['isEnabled', 'required', 'uiType'];
+// END GENERATED FROM GO
+
+function failApiResources(lines) {
+  console.error('');
+  console.error('.assembly/api-resources.json is invalid:');
+  console.error('');
+  for (const l of lines) console.error('  - ' + l);
+  console.error('');
+  console.error('The whole file is one top-level key: { "apiResources": [ ...records ] }.');
+  console.error('Schema, rules, and a worked example: .claude/skills/assembly-automations/SKILL.md.');
+  process.exit(1);
+}
+
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+// JSON null mirrors the platform decoder: null decodes into a zero/nil value
+// there, so a null optional key must behave exactly like an absent one here.
+function present(v) {
+  return v !== undefined && v !== null;
+}
+
+// Pushes an error for every key of obj outside allowed — the mirror of the
+// platform parser's DisallowUnknownFields.
+function checkKeys(obj, allowed, where, apiErrors) {
+  for (const key of Object.keys(obj)) {
+    if (!allowed.includes(key)) {
+      apiErrors.push(where + ': unknown key "' + key + '" (allowed: ' + allowed.join(', ') + ').');
+    }
+  }
+}
+
+function checkString(obj, key, where, apiErrors, { required = false, maxLen = 0 } = {}) {
+  const v = obj[key];
+  if (!present(v)) {
+    if (required) apiErrors.push(where + ': "' + key + '" is required.');
+    return '';
+  }
+  if (typeof v !== 'string') {
+    apiErrors.push(where + ': "' + key + '" must be a string.');
+    return '';
+  }
+  if (required && v === '') apiErrors.push(where + ': "' + key + '" is required.');
+  // Byte length, not UTF-16 units: the platform caps measure bytes.
+  if (maxLen > 0 && Buffer.byteLength(v, 'utf8') > maxLen) apiErrors.push(where + ': "' + key + '" exceeds ' + maxLen + ' characters.');
+  return v;
+}
+
+function checkBool(obj, key, where, apiErrors) {
+  if (present(obj[key]) && typeof obj[key] !== 'boolean') {
+    apiErrors.push(where + ': "' + key + '" must be true or false.');
+  }
+}
+
+// Keeps only ASCII alphanumerics, uppercasing the first letter after each
+// dropped separator (never the first kept character). Mirrors camelCaseAlnum
+// in app_api_resources.go.
+function camelCaseAlnum(s) {
+  let out = '';
+  let upperNext = false;
+  for (const ch of s) {
+    if (!/[a-zA-Z0-9]/.test(ch)) {
+      upperNext = out.length > 0;
+      continue;
+    }
+    out += upperNext ? ch.toUpperCase() : ch;
+    upperNext = false;
+  }
+  return out;
+}
+
+// Mirrors normalizeAppApiEventName in app_api_resources.go: the publish gate
+// coerces an authored eventName toward the canonical {resourceName}.{verb}
+// form instead of rejecting it ("intake.review_status_changed" →
+// "intake.reviewStatusChanged"; a bare verb gains the record's resourceName;
+// an empty verb becomes "triggered"). Returns the input unchanged when
+// nothing salvageable remains, so the format error still fires.
+function normalizeEventName(resourceName, eventName) {
+  let prefix = resourceName;
+  let verb = eventName;
+  const dot = eventName.indexOf('.');
+  if (dot >= 0) {
+    prefix = camelCaseAlnum(eventName.slice(0, dot)) || resourceName;
+    verb = eventName.slice(dot + 1);
+  }
+  verb = camelCaseAlnum(verb) || 'triggered';
+  const normalized = prefix + '.' + verb;
+  return EVENT_NAME_RE.test(normalized) ? normalized : eventName;
+}
+
+// Data-shape checks shared by record schema[] fields and apis[].input.schema[]
+// fields (mirrors validateAppApiFieldCore).
+function checkFieldCore(field, where, seenFieldNames, apiErrors) {
+  const fieldName = checkString(field, 'fieldName', where, apiErrors, { required: true });
+  if (fieldName !== '') {
+    const lower = fieldName.toLowerCase();
+    if (seenFieldNames.has(lower)) {
+      apiErrors.push(where + ': fieldName "' + fieldName + '" duplicates another field (field names are matched case-insensitively).');
+    }
+    seenFieldNames.add(lower);
+  }
+  const fieldType = checkString(field, 'fieldType', where, apiErrors, { required: true });
+  if (fieldType !== '' && !ALLOWED_FIELD_TYPES.includes(fieldType)) {
+    apiErrors.push(where + ': fieldType must be one of ' + ALLOWED_FIELD_TYPES.join(', ') + ' (got "' + fieldType + '").');
+  }
+  checkBool(field, 'optional', where, apiErrors);
+  checkBool(field, 'isDate', where, apiErrors);
+  // The platform treats zero values of required fields as missing, so a
+  // required bool can never carry false.
+  if (fieldType === 'bool' && field.optional !== true) {
+    apiErrors.push(where + ': bool fields must be declared "optional": true (the platform treats false on a required field as missing).');
+  }
+  // The runtime date check only makes sense for string values.
+  if (field.isDate === true && fieldType !== 'string') {
+    apiErrors.push(where + ': isDate requires fieldType "string" (got "' + fieldType + '").');
+  }
+  checkString(field, 'label', where, apiErrors, { maxLen: MAX_NAME_LENGTH });
+  checkString(field, 'description', where, apiErrors, { maxLen: MAX_DESC_LENGTH });
+}
+
+// One nesting level of record-level schema fields (mirrors
+// validateAppApiRecordFields). The per-level cap and case-insensitive name
+// uniqueness apply independently at every level: a nested field may reuse an
+// outer name — they address different payload objects. nestedFieldSchema uses
+// present(), matching the platform decoder where an explicit null decodes to
+// nil and behaves like an absent key.
+function checkRecordSchemaFields(fields, where, key, depth, apiErrors) {
+  if (fields.length > MAX_SCHEMA_FIELDS) {
+    apiErrors.push(where + ': ' + fields.length + ' ' + key + ' fields declared; the limit is ' + MAX_SCHEMA_FIELDS + '.');
+  }
+  const seenFieldNames = new Set();
+  fields.forEach((field, j) => {
+    let fieldWhere = where + '.' + key + '[' + j + ']';
+    if (!isPlainObject(field)) {
+      apiErrors.push(fieldWhere + ': must be an object.');
+      return;
+    }
+    if (typeof field.fieldName === 'string' && field.fieldName !== '') {
+      fieldWhere = where + '.' + key + '[' + j + '] (' + field.fieldName + ')';
+    }
+    checkKeys(field, RECORD_SCHEMA_FIELD_KEYS, fieldWhere, apiErrors);
+    checkFieldCore(field, fieldWhere, seenFieldNames, apiErrors);
+    if (!present(field.nestedFieldSchema)) return;
+    if (!Array.isArray(field.nestedFieldSchema)) {
+      apiErrors.push(fieldWhere + ': nestedFieldSchema must be an array of fields.');
+      return;
+    }
+    if (field.fieldType !== 'object' && field.fieldType !== 'array') {
+      apiErrors.push(fieldWhere + ': nestedFieldSchema is only valid on object or array fields (got fieldType "' + field.fieldType + '").');
+      return;
+    }
+    if (depth >= MAX_SCHEMA_NESTING_DEPTH) {
+      apiErrors.push(fieldWhere + ': nestedFieldSchema exceeds the maximum schema nesting depth of ' + MAX_SCHEMA_NESTING_DEPTH + '.');
+      return;
+    }
+    checkRecordSchemaFields(field.nestedFieldSchema, fieldWhere, 'nestedFieldSchema', depth + 1, apiErrors);
+  });
+}
+
+function checkDynamicOptions(dyn, where, getApiPaths, apiErrors, { nameFieldRequired }) {
+  if (!isPlainObject(dyn)) {
+    apiErrors.push(where + ': dynamicOptions must be an object like { "requestUrl": "/things", "nameField": "name" }.');
+    return;
+  }
+  checkKeys(dyn, DYNAMIC_OPTIONS_KEYS, where + '.dynamicOptions', apiErrors);
+  const requestUrl = checkString(dyn, 'requestUrl', where, apiErrors, { required: true });
+  if (requestUrl !== '' && !getApiPaths.has(requestUrl)) {
+    apiErrors.push(where + ': dynamicOptions.requestUrl "' + requestUrl + '" must exactly match the path of a registered GET api in this manifest (a collection api, not a /:id form).');
+  }
+  if (nameFieldRequired) {
+    checkString(dyn, 'nameField', where + '.dynamicOptions', apiErrors, { required: true });
+  } else {
+    checkString(dyn, 'nameField', where + '.dynamicOptions', apiErrors);
+  }
+}
+
+function checkOptions(options, where, apiErrors) {
+  if (!Array.isArray(options)) {
+    apiErrors.push(where + ': options must be an array of { "id", "name" }.');
+    return false;
+  }
+  options.forEach((option, i) => {
+    const optionWhere = where + '.options[' + i + ']';
+    if (!isPlainObject(option)) {
+      apiErrors.push(optionWhere + ': must be an object with "id" and "name".');
+      return;
+    }
+    checkKeys(option, OPTION_KEYS, optionWhere, apiErrors);
+    // Presence of id/name is not enforced — the publish gate only type-checks
+    // option entries, and this mirror must not reject what the gate accepts.
+    checkString(option, 'id', optionWhere, apiErrors);
+    checkString(option, 'name', optionWhere, apiErrors);
+  });
+  return options.length > 0;
+}
+
+if (existsSync(API_RESOURCES)) {
+  const apiErrors = [];
+
+  let apiRaw;
+  try {
+    apiRaw = readFileSync(API_RESOURCES, 'utf8');
+  } catch (e) {
+    failApiResources(['could not read the file: ' + e.message]);
+  }
+  if (Buffer.byteLength(apiRaw, 'utf8') > API_RESOURCES_MAX_FILE_BYTES) {
+    failApiResources(['file is larger than ' + API_RESOURCES_MAX_FILE_BYTES + ' bytes.']);
+  }
+
+  let apiDoc;
+  try {
+    apiDoc = JSON.parse(apiRaw);
+  } catch (e) {
+    failApiResources(['not valid JSON: ' + e.message]);
+  }
+  if (!isPlainObject(apiDoc)) {
+    failApiResources(['the top level must be a JSON object: { "apiResources": [ ... ] }.']);
+  }
+  checkKeys(apiDoc, API_RESOURCES_TOP_LEVEL_KEYS, 'top level', apiErrors);
+  if (!Array.isArray(apiDoc.apiResources)) {
+    // Keep any unknown-key errors already collected: fixing them one build at
+    // a time would cost the agent an extra loop.
+    apiErrors.push('the "apiResources" key is required and must be an array (declare "apiResources": [] to register nothing).');
+    failApiResources(apiErrors);
+  }
+
+  const records = apiDoc.apiResources;
+  if (records.length > MAX_RECORDS) {
+    apiErrors.push(records.length + ' apiResources declared; the limit is ' + MAX_RECORDS + '.');
+  }
+
+  // Cross-record indexes: (method, path) and event names are app-global; a
+  // dynamicOptions requestUrl may reference a collection GET api on ANY record.
+  const resourceNames = new Set();
+  const getApiPaths = new Set();
+  for (const record of records) {
+    if (!isPlainObject(record)) continue;
+    if (typeof record.resourceName === 'string' && record.resourceName !== '') resourceNames.add(record.resourceName);
+    if (!Array.isArray(record.apis)) continue;
+    for (const api of record.apis) {
+      if (isPlainObject(api) && api.method === 'GET' && typeof api.path === 'string' && !api.path.endsWith('/:id')) {
+        getApiPaths.add(api.path);
+      }
+    }
+  }
+
+  const seenResourceNames = new Map();
+  const seenMethodPaths = new Map();
+  const seenEventNames = new Map();
+
+  records.forEach((record, i) => {
+    let where = 'apiResources[' + i + ']';
+    if (!isPlainObject(record)) {
+      apiErrors.push(where + ': must be an object.');
+      return;
+    }
+    if (typeof record.resourceName === 'string' && record.resourceName !== '') {
+      where = 'apiResources[' + i + '] (' + record.resourceName + ')';
+    }
+    checkKeys(record, RECORD_KEYS, where, apiErrors);
+    checkString(record, 'name', where, apiErrors, { required: true, maxLen: MAX_NAME_LENGTH });
+
+    const resourceName = checkString(record, 'resourceName', where, apiErrors, { required: true });
+    if (resourceName !== '') {
+      if (!RESOURCE_NAME_RE.test(resourceName)) {
+        apiErrors.push(where + ': resourceName "' + resourceName + '" must be camelCase starting lowercase, 2-64 chars (' + RESOURCE_NAME_RE + ').');
+      } else if (seenResourceNames.has(resourceName)) {
+        apiErrors.push(where + ': resourceName "' + resourceName + '" is already used by apiResources[' + seenResourceNames.get(resourceName) + '].');
+      } else {
+        seenResourceNames.set(resourceName, i);
+      }
+    }
+
+    // baseUrl: relative-only — the platform resolves it against the app's
+    // deployed origin at publish; the registered record stores the full URL.
+    const baseUrl = checkString(record, 'baseUrl', where, apiErrors, { required: true });
+    if (baseUrl !== '') {
+      if (!baseUrl.startsWith('/')) {
+        apiErrors.push(where + ': baseUrl must be a relative path starting with "/" (got "' + baseUrl + '").');
+      } else if (baseUrl.startsWith('//') || baseUrl.includes('://')) {
+        apiErrors.push(where + ': baseUrl must not carry a scheme or host (got "' + baseUrl + '").');
+      }
+    }
+
+    // Record-level schema: the resource's pure data shape.
+    // schemaFieldNames stays top-level only: trigger fieldProperty and
+    // snapshotCxt.property read top-level payload keys.
+    const schemaFieldNames = new Set();
+    if (present(record.schema)) {
+      if (!Array.isArray(record.schema)) {
+        apiErrors.push(where + ': schema must be an array of fields.');
+      } else {
+        for (const field of record.schema) {
+          if (isPlainObject(field) && typeof field.fieldName === 'string' && field.fieldName !== '') {
+            schemaFieldNames.add(field.fieldName);
+          }
+        }
+        checkRecordSchemaFields(record.schema, where, 'schema', 1, apiErrors);
+      }
+    }
+
+    // apis
+    if (present(record.apis)) {
+      if (!Array.isArray(record.apis)) {
+        apiErrors.push(where + ': apis must be an array.');
+      } else {
+        if (record.apis.length > MAX_APIS_PER_RECORD) {
+          apiErrors.push(where + ': ' + record.apis.length + ' apis declared; the limit is ' + MAX_APIS_PER_RECORD + '.');
+        }
+        record.apis.forEach((api, j) => {
+          let apiWhere = where + '.apis[' + j + ']';
+          if (!isPlainObject(api)) {
+            apiErrors.push(apiWhere + ': must be an object.');
+            return;
+          }
+          if (typeof api.name === 'string' && api.name !== '') {
+            apiWhere = where + '.apis[' + j + '] (' + api.name + ')';
+          }
+          checkKeys(api, API_KEYS, apiWhere, apiErrors);
+          checkString(api, 'name', apiWhere, apiErrors, { required: true, maxLen: MAX_NAME_LENGTH });
+          // Tighter than the shared cap: this description is the action's
+          // visible label in the automations UI.
+          checkString(api, 'description', apiWhere, apiErrors, { maxLen: MAX_ACTION_DESC_LENGTH });
+          checkBool(api, 'paginated', apiWhere, apiErrors);
+          checkBool(api, 'exposeToAutomations', apiWhere, apiErrors);
+
+          const method = checkString(api, 'method', apiWhere, apiErrors, { required: true });
+          if (method !== '' && !ALLOWED_METHODS.includes(method)) {
+            apiErrors.push(apiWhere + ': method must be one of ' + ALLOWED_METHODS.join(', ') + ' (got "' + method + '").');
+          }
+
+          const path = checkString(api, 'path', apiWhere, apiErrors, { required: true, maxLen: MAX_PATH_LENGTH });
+          if (path !== '') {
+            if (!API_PATH_RE.test(path)) {
+              apiErrors.push(apiWhere + ': path "' + path + '" must be /segment(/segment)* of [a-z0-9-_] with an optional trailing /:id.');
+            } else {
+              for (const reserved of RESERVED_TASK_SEGMENTS) {
+                if (path.includes(reserved)) {
+                  apiErrors.push(apiWhere + ': path "' + path + '" contains reserved segment "' + reserved + '" (task-domain routes are owned by the platform Tasks app).');
+                  break;
+                }
+              }
+              const methodPath = method + ' ' + path;
+              if (seenMethodPaths.has(methodPath)) {
+                apiErrors.push(apiWhere + ': ' + methodPath + ' is already registered by ' + seenMethodPaths.get(methodPath) + ' (the proxy matcher is first-hit).');
+              } else {
+                seenMethodPaths.set(methodPath, apiWhere);
+              }
+            }
+          }
+
+          // queryParams
+          if (present(api.queryParams)) {
+            if (!isPlainObject(api.queryParams)) {
+              apiErrors.push(apiWhere + ': queryParams must be an object of name -> { "type", ... }.');
+            } else {
+              const paramNames = Object.keys(api.queryParams);
+              if (paramNames.length > MAX_QUERY_PARAMS) {
+                apiErrors.push(apiWhere + ': ' + paramNames.length + ' queryParams declared; the limit is ' + MAX_QUERY_PARAMS + '.');
+              }
+              for (const paramName of paramNames) {
+                const param = api.queryParams[paramName];
+                const paramWhere = apiWhere + '.queryParams[' + paramName + ']';
+                if (!isPlainObject(param)) {
+                  apiErrors.push(paramWhere + ': must be an object with a "type".');
+                  continue;
+                }
+                checkKeys(param, QUERY_PARAM_KEYS, paramWhere, apiErrors);
+                const paramType = checkString(param, 'type', paramWhere, apiErrors, { required: true });
+                if (paramType !== '' && !ALLOWED_QUERY_PARAM_TYPES.includes(paramType)) {
+                  apiErrors.push(paramWhere + ': type must be one of ' + ALLOWED_QUERY_PARAM_TYPES.join(', ') + ' (got "' + paramType + '").');
+                  continue;
+                }
+                // Mirror of the gate's nil/len semantics: a null or empty enum
+                // constrains nothing (even on a non-string type), and empty
+                // string values are allowed.
+                if (present(param.enum)) {
+                  if (!Array.isArray(param.enum) || param.enum.some((v) => typeof v !== 'string')) {
+                    apiErrors.push(paramWhere + ': enum must be an array of strings.');
+                  } else if (param.enum.length > 0 && paramType !== 'string') {
+                    apiErrors.push(paramWhere + ': enum is only valid with type "string".');
+                  }
+                }
+                for (const bound of ['min', 'max']) {
+                  if (present(param[bound])) {
+                    if (paramType !== 'int') {
+                      apiErrors.push(paramWhere + ': min/max are only valid with type "int".');
+                    } else if (!Number.isSafeInteger(param[bound])) {
+                      apiErrors.push(paramWhere + ': ' + bound + ' must be an integer.');
+                    }
+                  }
+                }
+                if (Number.isSafeInteger(param.min) && Number.isSafeInteger(param.max) && param.min > param.max) {
+                  apiErrors.push(paramWhere + ': min ' + param.min + ' exceeds max ' + param.max + '.');
+                }
+              }
+            }
+          }
+
+          // input
+          const needsInput = method === 'POST' || method === 'PUT' || method === 'PATCH';
+          if (needsInput && !present(api.input)) {
+            apiErrors.push(apiWhere + ': input is required for ' + method + '.');
+          }
+          let hasAutomationEnabledInput = false;
+          if (present(api.input)) {
+            if (!isPlainObject(api.input)) {
+              apiErrors.push(apiWhere + ': input must be an object like { "type": "object", "schema": [ ... ] }.');
+            } else {
+              checkKeys(api.input, INPUT_KEYS, apiWhere + '.input', apiErrors);
+              const inputType = checkString(api.input, 'type', apiWhere + '.input', apiErrors, { required: true });
+              if (inputType !== '' && !ALLOWED_INPUT_TYPES.includes(inputType)) {
+                apiErrors.push(apiWhere + ': input.type must be "object" or "list" (got "' + inputType + '").');
+              }
+              if (present(api.input.schema)) {
+                if (!Array.isArray(api.input.schema)) {
+                  apiErrors.push(apiWhere + ': input.schema must be an array of fields.');
+                } else {
+                  if (api.input.schema.length > MAX_SCHEMA_FIELDS) {
+                    apiErrors.push(apiWhere + ': ' + api.input.schema.length + ' input schema fields declared; the limit is ' + MAX_SCHEMA_FIELDS + '.');
+                  }
+                  const seenInputFieldNames = new Set();
+                  api.input.schema.forEach((field, k) => {
+                    let fieldWhere = apiWhere + '.input.schema[' + k + ']';
+                    if (!isPlainObject(field)) {
+                      apiErrors.push(fieldWhere + ': must be an object.');
+                      return;
+                    }
+                    if (typeof field.fieldName === 'string' && field.fieldName !== '') {
+                      fieldWhere = apiWhere + '.input.schema[' + k + '] (' + field.fieldName + ')';
+                    }
+                    checkKeys(field, INPUT_FIELD_KEYS, fieldWhere, apiErrors);
+                    checkFieldCore(field, fieldWhere, seenInputFieldNames, apiErrors);
+                    checkString(field, 'placeholder', fieldWhere, apiErrors, { maxLen: MAX_NAME_LENGTH });
+
+                    let hasStaticOptions = false;
+                    if (present(field.options)) {
+                      hasStaticOptions = checkOptions(field.options, fieldWhere, apiErrors);
+                    }
+                    if (present(field.dynamicOptions)) {
+                      // Action-field options fetches read nameField, so it is
+                      // required here (unlike trigger configuration).
+                      checkDynamicOptions(field.dynamicOptions, fieldWhere, getApiPaths, apiErrors, { nameFieldRequired: true });
+                    }
+                    if (present(field.dropdownSource)) {
+                      const src = field.dropdownSource;
+                      if (!isPlainObject(src)) {
+                        apiErrors.push(fieldWhere + ': dropdownSource must be an object like { "inputType": "client", "fieldName": "clientId" }.');
+                      } else {
+                        checkKeys(src, DROPDOWN_SOURCE_KEYS, fieldWhere + '.dropdownSource', apiErrors);
+                        const inputTypeValue = checkString(src, 'inputType', fieldWhere + '.dropdownSource', apiErrors, { required: true });
+                        if (inputTypeValue !== '' && !DROPDOWN_SOURCE_INPUT_TYPES.includes(inputTypeValue)) {
+                          apiErrors.push(fieldWhere + ': dropdownSource.inputType must be one of ' + DROPDOWN_SOURCE_INPUT_TYPES.join(', ') + ' (got "' + inputTypeValue + '").');
+                        }
+                        const fieldNameValue = checkString(src, 'fieldName', fieldWhere + '.dropdownSource', apiErrors, { required: true });
+                        const canonical = DROPDOWN_SOURCE_RECIPIENT_FIELDS[inputTypeValue];
+                        if (canonical !== undefined && fieldNameValue !== '' && fieldNameValue !== canonical) {
+                          apiErrors.push(fieldWhere + ': dropdownSource.fieldName must be "' + canonical + '" for inputType "' + inputTypeValue + '" — automations map recipients by that exact name.');
+                        }
+                      }
+                    }
+
+                    const hasOptionsSource = hasStaticOptions || present(field.dynamicOptions) || present(field.dropdownSource);
+                    if (present(field.automationSettings)) {
+                      const settings = field.automationSettings;
+                      if (!isPlainObject(settings)) {
+                        apiErrors.push(fieldWhere + ': automationSettings must be an object like { "isEnabled": true, "required": false, "uiType": "textInput" }.');
+                      } else {
+                        checkKeys(settings, AUTOMATION_SETTINGS_KEYS, fieldWhere + '.automationSettings', apiErrors);
+                        checkBool(settings, 'isEnabled', fieldWhere + '.automationSettings', apiErrors);
+                        checkBool(settings, 'required', fieldWhere + '.automationSettings', apiErrors);
+                        if (settings.isEnabled === true) hasAutomationEnabledInput = true;
+                        const uiType = checkString(settings, 'uiType', fieldWhere + '.automationSettings', apiErrors);
+                        // A bool always renders as a toggle, so its widget is
+                        // settled by fieldType and naming a uiType could only
+                        // contradict what the builder shows.
+                        const isBoolField = field.fieldType === 'bool';
+                        if (uiType === '') {
+                          // An explicit widget choice is required for exposed
+                          // fields unless an options source makes it a dropdown.
+                          if (settings.isEnabled === true && !hasOptionsSource && !isBoolField) {
+                            apiErrors.push(fieldWhere + ': automationSettings.uiType is required for exposed fields without an options source ("textInput" or "textArea").');
+                          }
+                        } else if (!ALLOWED_UI_TYPES.includes(uiType)) {
+                          apiErrors.push(fieldWhere + ': automationSettings.uiType must be one of ' + ALLOWED_UI_TYPES.join(', ') + ' (got "' + uiType + '").');
+                        } else if (uiType === 'dropdown' && !hasOptionsSource) {
+                          apiErrors.push(fieldWhere + ': uiType "dropdown" requires options, dynamicOptions, or dropdownSource.');
+                        } else if (uiType !== 'dropdown' && hasOptionsSource) {
+                          apiErrors.push(fieldWhere + ': uiType "' + uiType + '" contradicts the declared options source.');
+                        } else if (uiType === 'numberInput' && field.fieldType !== 'number') {
+                          // The widget stores a JSON number, so the declared shape
+                          // has to be one.
+                          apiErrors.push(fieldWhere + ': uiType "numberInput" requires fieldType "number" (got "' + field.fieldType + '").');
+                        } else if (uiType === 'dateInput' && field.isDate !== true) {
+                          // isDate is what makes the value an RFC 3339 timestamp
+                          // everywhere else in the platform.
+                          apiErrors.push(fieldWhere + ': uiType "dateInput" requires isDate: true.');
+                        }
+                        if (isBoolField && uiType !== '') {
+                          apiErrors.push(fieldWhere + ': a bool field renders as a toggle — omit automationSettings.uiType.');
+                        }
+                      }
+                    }
+                  });
+                }
+              }
+            }
+          }
+
+          if (api.exposeToAutomations === true && !hasAutomationEnabledInput) {
+            apiErrors.push(apiWhere + ': exposeToAutomations requires input with at least one field whose automationSettings.isEnabled is true.');
+          }
+
+          // output
+          if (!present(api.output)) {
+            apiErrors.push(apiWhere + ': output is required.');
+          } else if (!isPlainObject(api.output)) {
+            apiErrors.push(apiWhere + ': output must be an object like { "type": "object" }.');
+          } else {
+            checkKeys(api.output, OUTPUT_KEYS, apiWhere + '.output', apiErrors);
+            const outputType = checkString(api.output, 'type', apiWhere + '.output', apiErrors, { required: true });
+            if (outputType !== '' && !ALLOWED_OUTPUT_TYPES.includes(outputType)) {
+              apiErrors.push(apiWhere + ': output.type must be one of ' + ALLOWED_OUTPUT_TYPES.join(', ') + ' (got "' + outputType + '").');
+            }
+          }
+        });
+      }
+    }
+
+    // webhooks
+    let recordHasTrigger = false;
+    if (present(record.webhooks)) {
+      if (!Array.isArray(record.webhooks)) {
+        apiErrors.push(where + ': webhooks must be an array.');
+      } else {
+        if (record.webhooks.length > MAX_WEBHOOKS_PER_RECORD) {
+          apiErrors.push(where + ': ' + record.webhooks.length + ' webhooks declared; the limit is ' + MAX_WEBHOOKS_PER_RECORD + '.');
+        }
+        record.webhooks.forEach((webhook, j) => {
+          const webhookWhere = where + '.webhooks[' + j + ']';
+          if (!isPlainObject(webhook)) {
+            apiErrors.push(webhookWhere + ': must be an object.');
+            return;
+          }
+          checkKeys(webhook, WEBHOOK_KEYS, webhookWhere, apiErrors);
+
+          const authoredEventName = checkString(webhook, 'eventName', webhookWhere, apiErrors, { required: true });
+          if (authoredEventName !== '') {
+            // The publish gate normalizes before validating (a verb-formatting
+            // slip must not fail a publish), so validate the normalized name.
+            const eventName = normalizeEventName(
+              typeof record.resourceName === 'string' ? record.resourceName : '',
+              authoredEventName,
+            );
+            if (eventName !== authoredEventName) {
+              // Warn (never fail): the registered name won't match a runtime
+              // emission of the authored spelling, so the author should adopt
+              // the canonical form in both places.
+              console.warn(
+                webhookWhere + ': eventName "' + authoredEventName + '" will be registered as "' + eventName +
+                  '" — write the camelCase form in the manifest and emit exactly that name at runtime.',
+              );
+            }
+            if (!EVENT_NAME_RE.test(eventName)) {
+              apiErrors.push(webhookWhere + ': eventName "' + eventName + '" must be {resourceName}.{verb}.');
+            } else {
+              const prefix = eventName.slice(0, eventName.indexOf('.'));
+              if (!resourceNames.has(prefix)) {
+                apiErrors.push(webhookWhere + ': eventName "' + eventName + '" must be prefixed by one of the manifest\'s resourceNames.');
+              }
+              const lowerEventName = eventName.toLowerCase();
+              if (NATIVE_EVENTS_LOWER.has(lowerEventName)) {
+                apiErrors.push(webhookWhere + ': eventName "' + eventName + '" is a native platform event name.');
+              } else if (NATIVE_NAMESPACES_LOWER.has(prefix.toLowerCase())) {
+                apiErrors.push(webhookWhere + ': eventName "' + eventName + '" uses the native "' + prefix + '" event namespace; pick a distinct resourceName.');
+              }
+              if (seenEventNames.has(lowerEventName)) {
+                apiErrors.push(webhookWhere + ': eventName "' + eventName + '" is already declared by ' + seenEventNames.get(lowerEventName) + ' (event names are matched case-insensitively).');
+              } else {
+                seenEventNames.set(lowerEventName, webhookWhere);
+              }
+            }
+          }
+          checkString(webhook, 'eventDescription', webhookWhere, apiErrors, { maxLen: MAX_DESC_LENGTH });
+
+          if (present(webhook.trigger)) {
+            const trigger = webhook.trigger;
+            if (!isPlainObject(trigger)) {
+              apiErrors.push(webhookWhere + ': trigger must be an object.');
+              return;
+            }
+            recordHasTrigger = true;
+            checkKeys(trigger, TRIGGER_KEYS, webhookWhere + '.trigger', apiErrors);
+            checkString(trigger, 'name', webhookWhere + ': trigger', apiErrors, { required: true, maxLen: MAX_NAME_LENGTH });
+            checkString(trigger, 'description', webhookWhere + ': trigger', apiErrors, { maxLen: MAX_DESC_LENGTH });
+            const triggerIcon = checkString(trigger, 'icon', webhookWhere + ': trigger', apiErrors);
+            if (triggerIcon !== '' && !TRIGGER_ICON_SET.has(triggerIcon)) {
+              apiErrors.push(webhookWhere + ': trigger.icon "' + triggerIcon + '" is not in the platform icon set (pick a name from the assembly-automations skill\'s icon list).');
+            }
+
+            // Configuration is OPTIONAL: a bare trigger fires on every event
+            // of its type. The builder renders one filter field per trigger.
+            if (present(trigger.configuration)) {
+              if (!Array.isArray(trigger.configuration)) {
+                apiErrors.push(webhookWhere + ': trigger.configuration must be an array.');
+              } else {
+                if (trigger.configuration.length > 1) {
+                  apiErrors.push(webhookWhere + ': at most one trigger configuration field is supported.');
+                }
+                trigger.configuration.forEach((configField, k) => {
+                  const configWhere = webhookWhere + '.trigger.configuration[' + k + ']';
+                  if (!isPlainObject(configField)) {
+                    apiErrors.push(configWhere + ': must be an object.');
+                    return;
+                  }
+                  checkKeys(configField, TRIGGER_CONFIG_KEYS, configWhere, apiErrors);
+                  checkString(configField, 'id', configWhere, apiErrors, { required: true });
+                  checkString(configField, 'label', configWhere, apiErrors, { required: true, maxLen: MAX_NAME_LENGTH });
+                  checkString(configField, 'description', configWhere, apiErrors, { maxLen: MAX_DESC_LENGTH });
+                  checkBool(configField, 'required', configWhere, apiErrors);
+                  checkBool(configField, 'addAnyOption', configWhere, apiErrors);
+
+                  const fieldProperty = checkString(configField, 'fieldProperty', configWhere, apiErrors, { required: true });
+                  if (fieldProperty !== '' && !schemaFieldNames.has(fieldProperty)) {
+                    apiErrors.push(configWhere + ': fieldProperty "' + fieldProperty + '" must exactly match a declared schema fieldName (payload lookups are case-sensitive).');
+                  }
+                  const configFieldType = checkString(configField, 'fieldType', configWhere, apiErrors, { required: true });
+                  if (configFieldType !== '' && !ALLOWED_FIELD_TYPES.includes(configFieldType)) {
+                    apiErrors.push(configWhere + ': fieldType must be one of ' + ALLOWED_FIELD_TYPES.join(', ') + ' (got "' + configFieldType + '").');
+                  }
+                  const widget = checkString(configField, 'type', configWhere, apiErrors, { required: true });
+                  if (widget !== 'dropdown') {
+                    apiErrors.push(configWhere + ': type must be "dropdown" (the only widget the trigger configuration UI renders; got "' + widget + '").');
+                  }
+                  const fieldOperator = checkString(configField, 'fieldOperator', configWhere, apiErrors);
+                  if (fieldOperator !== '' && !ALLOWED_FIELD_OPERATORS.includes(fieldOperator)) {
+                    apiErrors.push(configWhere + ': fieldOperator must be one of ' + ALLOWED_FIELD_OPERATORS.join(', ') + ' (got "' + fieldOperator + '").');
+                  }
+
+                  let hasStaticOptions = false;
+                  if (present(configField.options)) {
+                    hasStaticOptions = checkOptions(configField.options, configWhere, apiErrors);
+                  }
+                  // The gate branches on emptiness, not key presence: an empty
+                  // options array plus dynamicOptions is a valid single source.
+                  const hasDynamicOptions = present(configField.dynamicOptions);
+                  if (!hasStaticOptions && !hasDynamicOptions) {
+                    apiErrors.push(configWhere + ': a dropdown needs options or dynamicOptions.');
+                  } else if (hasStaticOptions && hasDynamicOptions) {
+                    apiErrors.push(configWhere + ': declare options or dynamicOptions, not both.');
+                  } else if (hasDynamicOptions) {
+                    // The trigger UI reads .data[].name directly, so nameField
+                    // is optional here.
+                    checkDynamicOptions(configField.dynamicOptions, configWhere, getApiPaths, apiErrors, { nameFieldRequired: false });
+                  }
+                });
+              }
+            }
+
+            if (present(trigger.snapshotCxt)) {
+              if (!Array.isArray(trigger.snapshotCxt)) {
+                apiErrors.push(webhookWhere + ': trigger.snapshotCxt must be an array of { "label", "property" }.');
+              } else {
+                trigger.snapshotCxt.forEach((snapshotField, k) => {
+                  const snapshotWhere = webhookWhere + '.trigger.snapshotCxt[' + k + ']';
+                  if (!isPlainObject(snapshotField)) {
+                    apiErrors.push(snapshotWhere + ': must be an object with "label" and "property".');
+                    return;
+                  }
+                  checkKeys(snapshotField, SNAPSHOT_KEYS, snapshotWhere, apiErrors);
+                  checkString(snapshotField, 'label', snapshotWhere, apiErrors, { required: true });
+                  const property = checkString(snapshotField, 'property', snapshotWhere, apiErrors, { required: true });
+                  if (property !== '' && !schemaFieldNames.has(property)) {
+                    apiErrors.push(snapshotWhere + ': property "' + property + '" must exactly match a declared schema fieldName (payload lookups are case-sensitive).');
+                  }
+                });
+              }
+            }
+          }
+        });
+      }
+    }
+
+    if (recordHasTrigger && !RECIPIENT_FIELD_NAMES.some((n) => schemaFieldNames.has(n))) {
+      apiErrors.push(where + ': records with trigger webhooks must declare at least one of clientId, companyId, or internalUserId in schema — exact camelCase, automations read the payload case-sensitively ("optional": true is fine).');
+    }
+  });
+
+  if (apiErrors.length > 0) failApiResources(apiErrors);
+}