deepline 0.3.85 → 0.3.87

package/dist/bundling-sources/shared_libs/monitors/provider-monitor-capability.ts

@@ -0,0 +1,964 @@
+import {
+  monitorSdkIssue,
+  type MonitorSdkValidationIssue,
+} from '@deepline/monitors/validation';
+
+export type ProviderMonitorCapabilityOutput = {
+  table: string;
+  rowType: string;
+  description?: string;
+  condition?: {
+    payload?: Record<string, unknown>;
+  };
+};
+
+export type ProviderMonitorSubjectPathCandidate = {
+  path: string;
+  subjectType: string;
+  description?: string;
+};
+
+export type ProviderMonitorSubjectDerivation = {
+  kind: 'payload_path';
+  candidates: ProviderMonitorSubjectPathCandidate[];
+};
+
+export type ProviderMonitorSubjectContract = {
+  types: string[];
+  derivation: ProviderMonitorSubjectDerivation;
+};
+
+/**
+ * Customer-visible event category for one deployed monitor. Providers own this
+ * mapping in their monitor bundle; shared monitor code only evaluates it.
+ */
+export type ProviderMonitorTypeDerivation =
+  | { kind: 'payload_path'; path: string }
+  | { kind: 'static'; value: string };
+
+// A single conditional-requirement branch: when the payload matches `if`
+// (property === const, ANDed across entries), the fields in `then.required` are
+// required. This is the JSON-schema `if/then` idiom, scoped to the subset the
+// monitor validator needs (const-equality guards + a required list). It lets a
+// payloadSchema express requirements that depend on another field's value —
+// e.g. TAMRadar contact_radar requires `domain` only when
+// `radar_type === 'contact_job_changes'` — without a bespoke validation hook.
+export type ProviderMonitorCapabilityConditionalRequirement = {
+  if: {
+    properties: Record<string, { const: unknown }>;
+  };
+  then: {
+    required: string[];
+  };
+};
+
+export type ProviderMonitorCapabilityPayloadSchema = {
+  type: 'object';
+  additionalProperties?: boolean;
+  required?: string[];
+  properties?: Record<string, ProviderMonitorCapabilitySchemaProperty>;
+  allOf?: ProviderMonitorCapabilityConditionalRequirement[];
+};
+
+export type ProviderMonitorCapabilitySchemaProperty = {
+  type?: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
+  /** JSON Schema string format, passed through from an OpenAPI-derived payload. */
+  format?: string;
+  description?: string;
+  enum?: readonly unknown[];
+  pattern?: string;
+  minItems?: number;
+  items?: ProviderMonitorCapabilitySchemaProperty;
+  properties?: Record<string, ProviderMonitorCapabilitySchemaProperty>;
+  additionalProperties?: boolean;
+  required?: string[];
+};
+
+/**
+ * Provider-owned validation that cannot be represented in the monitor payload
+ * JSON schema alone, such as a provider's boolean-expression grammar.
+ */
+export type ProviderMonitorCapabilityPayloadValidator = (input: {
+  payload: Record<string, unknown>;
+  entityKey: string;
+}) => MonitorSdkValidationIssue[];
+
+export type ProviderMonitorCapabilityExample = {
+  label: string;
+  definition: {
+    key: string;
+    name?: string;
+    tool: string;
+    payload?: Record<string, unknown>;
+    controls?: Record<string, unknown>;
+  };
+};
+
+/**
+ * Factual, customer-visible monitor reference data. This is deliberately data,
+ * not TSDoc: the monitor validator, live tools surface, CLI, and generated
+ * references all consume the same capability object.
+ */
+export type ProviderMonitorCapabilityDocumentation = {
+  fields: Record<
+    string,
+    {
+      semantics: string;
+      applicability?: string;
+      grammar?: {
+        syntax: string;
+        precedence?: readonly string[];
+        example?: string;
+        examples?: readonly string[];
+      };
+      precedence?: string;
+    }
+  >;
+  pricing: { presentation: string };
+  identity: { semantics: string; update: string; backfill: string };
+  troubleshooting: Array<{ symptom: string; guidance: string }>;
+};
+
+/** Lifecycle facts shared by every monitor type; render once, never per provider. */
+export const PROVIDER_MONITOR_SHARED_DOCUMENTATION = {
+  lifecycle: [
+    'monitors check validates a definition locally and does not deploy, spend credits, or prove a future event will arrive.',
+    'monitors deploy is a full desired definition. Use deploy --dry-run to inspect provider and Deepline-credit effects; use monitors update for a patch.',
+    'monitors get returns the stored deployed definition plus monitor_spec, whose fields list the deployable payload paths, descriptions, constraints, and provider-specific semantics for that monitor type.',
+  ],
+  errorMeanings: [
+    'Validation errors name the payload path and expected contract value; correct the definition and rerun monitors check.',
+    'A paused monitor needs a balance or entitlement correction before reactivation. Deepline exposes Deepline pricing only.',
+  ],
+} as const;
+
+export type ProviderMonitorInboundAuthDescriptor =
+  | { mode: 'hmac_sha256'; secretSource: 'provider' | 'deepline' }
+  | { mode: 'body_secret'; secretSource: 'deepline' }
+  | {
+      mode: 'custom_header';
+      secretSource: 'deepline';
+      headerName: string;
+    }
+  | { mode: 'callback_token' };
+
+/**
+ * Provider-owned instructions shown only after Deepline has minted a callback
+ * endpoint for a monitor. `{{callback_url}}` is interpolated at read time; the
+ * opaque URL itself is deliberately never stored in this metadata.
+ */
+export type ProviderMonitorPostDeployGuidance = {
+  title: string;
+  steps: string[];
+  documentation: Array<{ label: string; url: string }>;
+  event_type?: string;
+  payload_example?: Record<string, unknown>;
+};
+
+export type ProviderMonitorCapabilityDefinition = {
+  id: string;
+  provider: string;
+  capability: string;
+  providerCapability: string;
+  displayName: string;
+  description: string;
+  payloadSchema: ProviderMonitorCapabilityPayloadSchema;
+  validatePayload?: ProviderMonitorCapabilityPayloadValidator;
+  /**
+   * A narrow compatibility declaration for payload fields whose validation was
+   * tightened after customer monitors were already stored. It applies only
+   * when Deepline recognizes an unchanged stored definition; new definitions
+   * and changed payloads remain fully strict.
+   */
+  legacyPayloadValidation?: {
+    grandfatheredPaths: readonly string[];
+    /** Generic schema issue codes eligible for those same legacy paths. */
+    grandfatheredSchemaIssueCodes?: readonly string[];
+  };
+  payloadExamples: ProviderMonitorCapabilityExample[];
+  documentation: ProviderMonitorCapabilityDocumentation;
+  postDeployGuidance?: ProviderMonitorPostDeployGuidance;
+  /** Friendly provider-specific setup target, e.g. deepline.analytics. */
+  setupAlias?: string;
+  /**
+   * The payload fields that define WHAT this monitor watches (its coverage
+   * scope), used by reuse detection to warn before deploying a duplicate
+   * monitor. Field names MUST be real `payloadSchema.properties` keys.
+   * Undefined means tool-level coverage: any same-tool monitor is a reuse
+   * candidate (used when the payload is too fuzzy to compare structurally,
+   * e.g. TheirStack saved-search filter bodies). See
+   * `MONITOR_COVERAGE_KEY_FIELDS` in provider-monitor-capabilities.ts for the
+   * central declarations of existing capabilities.
+   */
+  coverageKeyFields?: readonly string[];
+  /**
+   * Provider-account identity for this monitor. Shared monitor code checks it
+   * against Convex before calling the upstream provider.
+   */
+  upstreamCollision?: {
+    identityKeyFields: readonly string[];
+    /**
+     * This provider can create an updated resource for the same Deepline
+     * monitor key before the prior upstream resource is deprovisioned. This
+     * never permits a second key to occupy the same identity in one org.
+     */
+    supportsSameIdentityReplacement?: boolean;
+  };
+  pricing: Record<string, unknown>;
+  subject: ProviderMonitorSubjectContract;
+  /**
+   * The generic, customer-visible event type for this monitor. Use a payload
+   * path when the provider lets the deployed definition select the type.
+   */
+  type: ProviderMonitorTypeDerivation;
+  runtime: {
+    kind:
+      | 'provider_native_monitor'
+      | 'provider_webhook_subscription'
+      // The provider dashboard owns webhook creation. Deepline owns the
+      // unguessable callback endpoint and tells the customer where to paste it.
+      | 'provider_manual_webhook';
+    deployAction?: string;
+    statusAction?: string;
+    disableAction?: string;
+    deleteAction?: string;
+    pollAction?: string;
+    /** Shared provider-governor bucket for scalar lifecycle work. */
+    rateLimitId?: string;
+    /** Additional ordered provider actions owned by a managed deploy plan. */
+    managedDeployActions?: readonly string[];
+    /** Internal diagnostics and lifecycle actions owned by this capability. */
+    supportActions?: readonly string[];
+    /**
+     * Optional asynchronous batch-create transport. This is intentionally a
+     * capability declaration rather than a Fleet special case: fleets and a
+     * future ordinary `monitors create-batch` API both ask the same adapter
+     * registry whether a capability can be submitted in batches.
+     *
+     * `adapter` identifies provider-owned wire parsing/mapping code. The
+     * remaining fields are declarative capability facts and are checked before
+     * a provider call is made.
+     */
+    batchCreate?: {
+      adapter: string;
+      createAction: string;
+      statusAction: string;
+      rateLimitId: string;
+    };
+    /**
+     * Optional synchronous batch-cleanup transport. This follows the same
+     * capability-owned adapter boundary as batch creation so Fleet removal and
+     * a future ordinary monitor batch API never grow provider-specific paths.
+     */
+    batchDelete?: {
+      adapter: string;
+      deleteAction: string;
+      rateLimitId: string;
+    };
+    /**
+     * Optional batch READ transport: ask the provider, by id, what it holds.
+     *
+     * This is what makes the audit verb provider-generic. The verb pages
+     * monitors, chunks their resource ids, and asks; the only per-provider
+     * facts are which action answers, which parameter carries the ids, and how
+     * many ids one request may name. `maxIds` is a DOCUMENTED provider
+     * maximum, not a tuning knob - it belongs here rather than as a literal in
+     * the walker because two walkers with two literals is how the number drifts
+     * away from the contract it came from.
+     *
+     * A capability with no `batchRead` is not auditable, and the verb says so
+     * rather than guessing from a full listing: absence of a resource from a
+     * page that was never asked about it is not evidence.
+     */
+    batchRead?: {
+      adapter: string;
+      readAction: string;
+      /** Request parameter that carries the comma-separated resource ids. */
+      idsParam: string;
+      /** Ids one request may name, per the provider's published contract. */
+      maxIds: number;
+      rateLimitId: string;
+    };
+    // Declares that this monitor delivers data to Deepline via an inbound
+    // webhook callback (handled by the provider-callbacks route). Webhook
+    // subscription monitors are inherently inbound; native monitors must set
+    // this explicitly when they post callbacks (e.g. theirstack, tamradar) so
+    // the endpoint-coverage gate can require a registered inbound handler.
+    inbound?: 'webhook';
+    // Authentication contract for callbacks on the Deepline-owned endpoint.
+    // This lives with the provider capability so deploy and receive cannot drift
+    // into separate provider allowlists or invented signature conventions.
+    inboundAuth?: ProviderMonitorInboundAuthDescriptor;
+    // For native `inbound: 'webhook'` monitors, declares HOW OUR Deepline
+    // callback URL reaches the upstream provider at deploy time. The
+    // endpoint-coverage gate keys on this so a webhook-push monitor cannot ship
+    // without a registered way to hand the provider our endpoint:
+    //   - 'per_monitor_create_url': the create call takes a per-monitor callback
+    //     URL; the capability MUST register a `webhookRegistration` descriptor
+    //     (e.g. Findymail `webhook_url`).
+    //   - 'managed_deploy_action': a bespoke multi-step deploy action wires our
+    //     URL into a dedicated webhook resource (e.g. TheirStack saved-search +
+    //     webhook).
+    //   - 'account_marker': the provider posts to an account-level webhook and
+    //     events are correlated by a marker, not a per-monitor URL (e.g.
+    //     TamRadar custom_fields). No per-monitor URL is registered.
+    webhookRegistrationStrategy?:
+      | 'per_monitor_create_url'
+      | 'managed_deploy_action'
+      | 'account_marker';
+  };
+  outputs: Record<string, ProviderMonitorCapabilityOutput>;
+  lifecycle: {
+    check: boolean;
+    deploy: boolean;
+    status: boolean;
+    disable: boolean;
+  };
+};
+
+export type ProviderMonitorCapabilityPublicLifecycle = {
+  check: boolean;
+  deploy: boolean;
+  status: boolean;
+  update: boolean;
+  delete: boolean;
+};
+
+export type ProviderMonitorCapabilityEntitlementStatus = {
+  /** True when this capability is gated behind a Deepline add-on entitlement. */
+  required: boolean;
+  /** True when the entitlement is required but not active for the requesting org. */
+  locked: boolean;
+  entitlementId?: string;
+  priceUsdMonthly?: number | null;
+  includedActiveMonitors?: number | null;
+  /** Deepline-facing reason shown when locked (never exposes provider spend). */
+  reason?: string;
+};
+
+const UNLOCKED_ENTITLEMENT_STATUS: ProviderMonitorCapabilityEntitlementStatus =
+  {
+    required: false,
+    locked: false,
+  };
+
+export type ProviderMonitorCapabilitySerializable = {
+  provider: string;
+  tool: string;
+  display_name: string;
+  description: string;
+  payload: {
+    schema: ProviderMonitorCapabilityPayloadSchema;
+    examples: ProviderMonitorCapabilityExample[];
+  };
+  payload_schema: ProviderMonitorCapabilityPayloadSchema;
+  payload_examples: ProviderMonitorCapabilityExample[];
+  documentation: ProviderMonitorCapabilityDocumentation;
+  outputs: Record<string, ProviderMonitorCapabilityOutput>;
+  subject: ProviderMonitorSubjectContract;
+  type_derivation: ProviderMonitorTypeDerivation;
+  lifecycle: ProviderMonitorCapabilityPublicLifecycle;
+  billing: Record<string, unknown>;
+  deployable: boolean;
+  diagnostics: Array<{
+    code: string;
+    path: string;
+    message: string;
+    suggestion?: string;
+  }>;
+  entitlement: {
+    required: boolean;
+    locked: boolean;
+    entitlement_id?: string;
+    price_usd_monthly?: number | null;
+    included_active_monitors?: number | null;
+    reason?: string;
+  };
+  next_commands: string[];
+};
+
+export function providerMonitorCapabilityId(input: {
+  provider: string;
+  capability: string;
+}) {
+  return `${input.provider}.${input.capability}`;
+}
+
+export function parseProviderMonitorCapabilityId(value: string) {
+  const trimmed = value.trim();
+  const [provider, capability, ...extra] = trimmed.split('.');
+  if (!provider || !capability || extra.length > 0) return null;
+  return {
+    provider,
+    capability,
+    providerCapability: providerMonitorCapabilityId({ provider, capability }),
+  };
+}
+
+export function defineProviderMonitorCapability(input: {
+  provider: string;
+  capability: string;
+  displayName: string;
+  description: string;
+  payloadSchema: ProviderMonitorCapabilityPayloadSchema;
+  validatePayload?: ProviderMonitorCapabilityPayloadValidator;
+  legacyPayloadValidation?: ProviderMonitorCapabilityDefinition['legacyPayloadValidation'];
+  payloadExamples: ProviderMonitorCapabilityExample[];
+  documentation?: ProviderMonitorCapabilityDocumentation;
+  postDeployGuidance?: ProviderMonitorPostDeployGuidance;
+  setupAlias?: string;
+  coverageKeyFields?: readonly string[];
+  upstreamCollision?: ProviderMonitorCapabilityDefinition['upstreamCollision'];
+  pricing: Record<string, unknown>;
+  subject: ProviderMonitorSubjectContract;
+  type?: ProviderMonitorTypeDerivation;
+  runtime: ProviderMonitorCapabilityDefinition['runtime'];
+  outputs: Record<string, ProviderMonitorCapabilityOutput>;
+  lifecycle: ProviderMonitorCapabilityDefinition['lifecycle'];
+}): ProviderMonitorCapabilityDefinition {
+  const providerCapability = providerMonitorCapabilityId(input);
+  const fields = Object.fromEntries(
+    Object.entries(input.payloadSchema.properties ?? {}).map(
+      ([field, schema]) => [
+        field,
+        {
+          semantics:
+            schema.description ?? `Provider-specific ${field} monitor filter.`,
+        },
+      ],
+    ),
+  );
+  return {
+    ...input,
+    id: providerCapability,
+    providerCapability,
+    // Existing monitor bundles predate the generic type contract. Their
+    // capability is still an accurate, stable category until they opt into a
+    // provider-specific payload mapping.
+    type: input.type ?? { kind: 'static', value: input.capability },
+    documentation: input.documentation ?? {
+      fields,
+      pricing: {
+        presentation:
+          'Use the Deepline pricing returned by tools get, monitors available, check, or deploy --dry-run. Provider spend is not exposed.',
+      },
+      identity: {
+        semantics: input.upstreamCollision
+          ? `One monitor identity uses ${input.upstreamCollision.identityKeyFields.join(', ')}.`
+          : 'This monitor uses the provider capability identity declared by Deepline.',
+        update:
+          'Use monitors update for a patch or deploy for a complete desired definition.',
+        backfill:
+          'Existing Customer DB rows are retained; this capability does not promise provider backfill unless its provider documentation says otherwise.',
+      },
+      troubleshooting: [
+        {
+          symptom: 'Validation failed',
+          guidance:
+            'Correct the reported payload path, then run monitors check again.',
+        },
+      ],
+    },
+  };
+}
+
+/**
+ * Resolves the generic monitor `type` without leaking provider-specific field
+ * names into registry, API, or CLI code. A malformed or legacy payload returns
+ * null rather than guessing; callers can state that the type is unknown.
+ */
+export function deriveProviderMonitorType(
+  capability: ProviderMonitorCapabilityDefinition,
+  payload: Record<string, unknown>,
+): string | null {
+  if (capability.type.kind === 'static') {
+    const value = capability.type.value.trim();
+    return value || null;
+  }
+  let value: unknown = payload;
+  for (const segment of capability.type.path.split('.')) {
+    if (
+      !segment ||
+      segment === '__proto__' ||
+      segment === 'prototype' ||
+      segment === 'constructor' ||
+      !value ||
+      typeof value !== 'object' ||
+      Array.isArray(value)
+    ) {
+      return null;
+    }
+    value = (value as Record<string, unknown>)[segment];
+  }
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+export function isProviderMonitorCapabilityDeployable(
+  capability: ProviderMonitorCapabilityDefinition,
+) {
+  return Boolean(
+    capability.lifecycle.deploy &&
+    (capability.runtime.deployAction ||
+      capability.runtime.kind === 'provider_manual_webhook'),
+  );
+}
+
+function providerMonitorCapabilityHasCleanupAction(
+  capability: ProviderMonitorCapabilityDefinition,
+) {
+  return Boolean(
+    capability.runtime.deleteAction ||
+    capability.runtime.disableAction ||
+    capability.runtime.kind === 'provider_manual_webhook',
+  );
+}
+
+function publicLifecycle(
+  capability: ProviderMonitorCapabilityDefinition,
+): ProviderMonitorCapabilityPublicLifecycle {
+  const deployable = isProviderMonitorCapabilityDeployable(capability);
+  const cleanup = providerMonitorCapabilityHasCleanupAction(capability);
+  return {
+    check: capability.lifecycle.check,
+    deploy: deployable,
+    status: true,
+    update: deployable && cleanup,
+    delete: cleanup,
+  };
+}
+
+function cloneSerializable<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+function lifecycleDiagnostic(input: {
+  capability: ProviderMonitorCapabilityDefinition;
+  mode: 'deploy';
+}) {
+  const deployActionMissing =
+    input.mode === 'deploy' &&
+    !input.capability.runtime.deployAction &&
+    input.capability.runtime.kind !== 'provider_manual_webhook';
+  return {
+    code: `provider_monitor_${input.mode}_not_supported`,
+    path: 'tool',
+    message: `Monitor tool ${input.capability.providerCapability} does not support ${input.mode}.`,
+    suggestion:
+      deployActionMissing || input.mode === 'deploy'
+        ? 'This monitor tool is modeled but its upstream deploy action is not wired yet.'
+        : 'Choose a monitor tool with lifecycle support from the platform-admin monitor catalog.',
+  };
+}
+
+function lifecycleDiagnostics(capability: ProviderMonitorCapabilityDefinition) {
+  const diagnostics: ReturnType<typeof lifecycleDiagnostic>[] = [];
+  if (!isProviderMonitorCapabilityDeployable(capability)) {
+    diagnostics.push(lifecycleDiagnostic({ capability, mode: 'deploy' }));
+  }
+  return diagnostics;
+}
+
+export function serializeProviderMonitorCapability(
+  capability: ProviderMonitorCapabilityDefinition,
+  entitlement: ProviderMonitorCapabilityEntitlementStatus = UNLOCKED_ENTITLEMENT_STATUS,
+): ProviderMonitorCapabilitySerializable {
+  const payloadSchema = cloneSerializable(capability.payloadSchema);
+  const payloadExamples = cloneSerializable(capability.payloadExamples);
+  return {
+    provider: capability.provider,
+    tool: capability.providerCapability,
+    display_name: capability.displayName,
+    description: capability.description,
+    payload: {
+      schema: payloadSchema,
+      examples: payloadExamples,
+    },
+    payload_schema: payloadSchema,
+    payload_examples: payloadExamples,
+    documentation: cloneSerializable(capability.documentation),
+    outputs: cloneSerializable(capability.outputs),
+    subject: cloneSerializable(capability.subject),
+    type_derivation: cloneSerializable(capability.type),
+    lifecycle: publicLifecycle(capability),
+    billing: cloneSerializable(capability.pricing),
+    deployable: isProviderMonitorCapabilityDeployable(capability),
+    diagnostics: lifecycleDiagnostics(capability),
+    entitlement: {
+      required: entitlement.required,
+      locked: entitlement.locked,
+      ...(entitlement.entitlementId
+        ? { entitlement_id: entitlement.entitlementId }
+        : {}),
+      ...(entitlement.priceUsdMonthly !== undefined
+        ? { price_usd_monthly: entitlement.priceUsdMonthly }
+        : {}),
+      ...(entitlement.includedActiveMonitors !== undefined
+        ? { included_active_monitors: entitlement.includedActiveMonitors }
+        : {}),
+      ...(entitlement.reason ? { reason: entitlement.reason } : {}),
+    },
+    next_commands: [],
+  };
+}
+
+function issue(
+  input: Omit<MonitorSdkValidationIssue, 'severity'> & {
+    severity?: MonitorSdkValidationIssue['severity'];
+  },
+) {
+  return monitorSdkIssue(input);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function validationIssueMatchesGrandfatheredPath(input: {
+  issue: MonitorSdkValidationIssue;
+  paths: readonly string[];
+}) {
+  return input.paths.some(
+    (path) =>
+      input.issue.path === path ||
+      input.issue.path.startsWith(`${path}.`) ||
+      input.issue.path.startsWith(`${path}[`),
+  );
+}
+
+function typeName(value: unknown) {
+  if (Array.isArray(value)) return 'array';
+  if (value === null) return 'null';
+  return typeof value;
+}
+
+function validateSchemaProperty(input: {
+  schema: ProviderMonitorCapabilitySchemaProperty;
+  value: unknown;
+  path: string;
+  entityKey: string;
+}): MonitorSdkValidationIssue[] {
+  const issues: MonitorSdkValidationIssue[] = [];
+  const schemaType = input.schema.type;
+  if (schemaType) {
+    const valid =
+      schemaType === 'array'
+        ? Array.isArray(input.value)
+        : schemaType === 'object'
+          ? isRecord(input.value)
+          : schemaType === 'integer'
+            ? Number.isInteger(input.value)
+            : typeof input.value === schemaType;
+    if (!valid) {
+      issues.push(
+        issue({
+          code: 'invalid_provider_monitor_payload_type',
+          path: input.path,
+          message: `Provider monitor payload field ${input.path} must be ${schemaType}.`,
+          expected: schemaType,
+          received: input.value,
+          suggestion:
+            'Match the payload_schema returned by the platform-admin monitor tools API.',
+          entity_type: 'tool',
+          entity_key: input.entityKey,
+          docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+        }),
+      );
+      return issues;
+    }
+  }
+  if (input.schema.enum && !input.schema.enum.includes(input.value)) {
+    issues.push(
+      issue({
+        code: 'invalid_provider_monitor_payload_enum',
+        path: input.path,
+        message: `Provider monitor payload field ${input.path} must be one of the supported values.`,
+        expected: input.schema.enum,
+        received: input.value,
+        suggestion:
+          'Choose a value from payload_schema.enum for this monitor tool.',
+        entity_type: 'tool',
+        entity_key: input.entityKey,
+        docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+      }),
+    );
+  }
+  if (typeof input.value === 'string' && input.schema.pattern) {
+    const pattern = new RegExp(input.schema.pattern);
+    if (!pattern.test(input.value)) {
+      issues.push(
+        issue({
+          code: 'invalid_provider_monitor_payload_pattern',
+          path: input.path,
+          message: `Provider monitor payload field ${input.path} does not match the required pattern.`,
+          expected: input.schema.pattern,
+          received: input.value,
+          suggestion:
+            'Match the payload_schema returned by the platform-admin monitor tools API.',
+          entity_type: 'tool',
+          entity_key: input.entityKey,
+          docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+        }),
+      );
+    }
+  }
+  if (Array.isArray(input.value) && input.schema.items) {
+    if (
+      typeof input.schema.minItems === 'number' &&
+      input.value.length < input.schema.minItems
+    ) {
+      issues.push(
+        issue({
+          code: 'invalid_provider_monitor_payload_min_items',
+          path: input.path,
+          message: `Provider monitor payload field ${input.path} has too few items.`,
+          expected: input.schema.minItems,
+          received: input.value.length,
+          entity_type: 'tool',
+          entity_key: input.entityKey,
+          docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+        }),
+      );
+    }
+    input.value.forEach((item, index) => {
+      issues.push(
+        ...validateSchemaProperty({
+          schema: input.schema.items!,
+          value: item,
+          path: `${input.path}.${index}`,
+          entityKey: input.entityKey,
+        }),
+      );
+    });
+  }
+  if (isRecord(input.value) && input.schema.type === 'object') {
+    issues.push(
+      ...validateObjectAgainstSchema({
+        schema: {
+          type: 'object',
+          additionalProperties: input.schema.additionalProperties,
+          required: input.schema.required,
+          properties: input.schema.properties,
+        },
+        value: input.value,
+        path: input.path,
+        entityKey: input.entityKey,
+      }),
+    );
+  }
+  return issues;
+}
+
+function validateObjectAgainstSchema(input: {
+  schema: ProviderMonitorCapabilityPayloadSchema;
+  value: Record<string, unknown>;
+  path: string;
+  entityKey: string;
+}) {
+  const issues: MonitorSdkValidationIssue[] = [];
+  const properties = input.schema.properties ?? {};
+  for (const requiredField of input.schema.required ?? []) {
+    if (input.value[requiredField] === undefined) {
+      issues.push(
+        issue({
+          code: 'missing_provider_monitor_payload_field',
+          path: `${input.path}.${requiredField}`,
+          message: `Provider monitor payload field ${requiredField} is required.`,
+          expected: Object.keys(properties).sort(),
+          received: undefined,
+          suggestion:
+            'Use the platform-admin monitor tools API and provide the required payload fields.',
+          entity_type: 'tool',
+          entity_key: input.entityKey,
+          docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+        }),
+      );
+    }
+  }
+  for (const conditional of input.schema.allOf ?? []) {
+    const guardMatches = Object.entries(conditional.if.properties).every(
+      ([key, guard]) => input.value[key] === guard.const,
+    );
+    if (!guardMatches) continue;
+    const guardDescription = Object.entries(conditional.if.properties)
+      .map(([key, guard]) => `${key}=${JSON.stringify(guard.const)}`)
+      .join(', ');
+    for (const requiredField of conditional.then.required) {
+      if (input.value[requiredField] !== undefined) continue;
+      issues.push(
+        issue({
+          code: 'missing_provider_monitor_payload_field',
+          path: `${input.path}.${requiredField}`,
+          message: `Provider monitor payload field ${requiredField} is required when ${guardDescription}.`,
+          expected: Object.keys(properties).sort(),
+          received: undefined,
+          suggestion:
+            'Use the platform-admin monitor tools API and provide the required payload fields.',
+          entity_type: 'tool',
+          entity_key: input.entityKey,
+          docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+        }),
+      );
+    }
+  }
+  if (input.schema.additionalProperties === false) {
+    for (const key of Object.keys(input.value)) {
+      if (properties[key]) continue;
+      issues.push(
+        issue({
+          code: 'unknown_provider_monitor_payload_field',
+          path: `${input.path}.${key}`,
+          message: `Provider monitor payload field ${key} is not supported for this monitor tool.`,
+          expected: Object.keys(properties).sort(),
+          received: input.value[key],
+          suggestion:
+            'Remove the field or choose a monitor tool whose payload_schema includes it.',
+          entity_type: 'tool',
+          entity_key: input.entityKey,
+          docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+        }),
+      );
+    }
+  }
+  for (const [key, propertySchema] of Object.entries(properties)) {
+    const value = input.value[key];
+    if (value === undefined) continue;
+    issues.push(
+      ...validateSchemaProperty({
+        schema: propertySchema,
+        value,
+        path: `${input.path}.${key}`,
+        entityKey: input.entityKey,
+      }),
+    );
+  }
+  return issues;
+}
+
+export function validateProviderMonitorCapabilityPayload(input: {
+  capability: ProviderMonitorCapabilityDefinition;
+  value: unknown;
+  entityKey: string;
+  mode?: 'strict' | 'legacy_stored';
+}) {
+  if (!isRecord(input.value)) {
+    return [
+      issue({
+        code: 'invalid_provider_monitor_payload',
+        path: 'payload',
+        message: 'Provider monitor payload must be an object when provided.',
+        expected: 'object',
+        received: input.value,
+        suggestion:
+          'Use payload: { ... } with fields from the monitor tool payload_schema.',
+        entity_type: 'monitor',
+        entity_key: input.entityKey,
+        docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+      }),
+    ];
+  }
+  const schemaIssues = validateObjectAgainstSchema({
+    schema: input.capability.payloadSchema,
+    value: input.value,
+    path: 'payload',
+    entityKey: input.capability.providerCapability,
+  });
+  const capabilityIssues = input.capability.validatePayload
+    ? input.capability.validatePayload({
+        payload: input.value,
+        entityKey: input.entityKey,
+      })
+    : [];
+  if (input.mode !== 'legacy_stored') {
+    return [...schemaIssues, ...capabilityIssues];
+  }
+  const grandfatheredPaths =
+    input.capability.legacyPayloadValidation?.grandfatheredPaths ?? [];
+  const grandfatheredSchemaIssueCodes =
+    input.capability.legacyPayloadValidation?.grandfatheredSchemaIssueCodes ??
+    [];
+  return [
+    ...schemaIssues.filter(
+      (validationIssue) =>
+        validationIssue.severity !== 'error' ||
+        !grandfatheredSchemaIssueCodes.includes(validationIssue.code) ||
+        !validationIssueMatchesGrandfatheredPath({
+          issue: validationIssue,
+          paths: grandfatheredPaths,
+        }),
+    ),
+    ...capabilityIssues.filter(
+      (validationIssue) =>
+        validationIssue.severity !== 'error' ||
+        !validationIssueMatchesGrandfatheredPath({
+          issue: validationIssue,
+          paths: grandfatheredPaths,
+        }),
+    ),
+  ];
+}
+
+function conditionMatchesPayload(
+  output: ProviderMonitorCapabilityOutput,
+  payload: Record<string, unknown>,
+) {
+  const conditionPayload = output.condition?.payload;
+  if (!conditionPayload) return true;
+  return Object.entries(conditionPayload).every(
+    ([key, value]) => payload[key] === value,
+  );
+}
+
+export function resolveProviderMonitorCapabilityOutputsForPayload(input: {
+  capability: ProviderMonitorCapabilityDefinition;
+  payload: Record<string, unknown>;
+}) {
+  const entries = Object.entries(input.capability.outputs);
+  const conditionalEntries = entries.filter(
+    ([, output]) => output.condition?.payload,
+  );
+  if (conditionalEntries.length === 0) return input.capability.outputs;
+  const selected = entries.filter(([, output]) =>
+    conditionMatchesPayload(output, input.payload),
+  );
+  return Object.fromEntries(selected.length ? selected : entries);
+}
+
+export function providerMonitorCapabilityLifecycleIssue(input: {
+  capability: ProviderMonitorCapabilityDefinition;
+  mode: 'deploy' | 'status' | 'disable' | 'check';
+}): MonitorSdkValidationIssue | null {
+  if (input.mode === 'check' && input.capability.lifecycle.check) return null;
+  if (input.mode !== 'check' && input.capability.lifecycle[input.mode]) {
+    if (
+      input.mode !== 'deploy' ||
+      input.capability.runtime.deployAction ||
+      input.capability.runtime.kind === 'provider_manual_webhook'
+    ) {
+      return null;
+    }
+  }
+  const code = `provider_monitor_${input.mode}_not_supported`;
+  return issue({
+    code,
+    path: 'tool',
+    message: `Monitor tool ${input.capability.providerCapability} does not support ${input.mode}.`,
+    expected: `${input.mode} lifecycle support`,
+    received:
+      input.mode === 'deploy'
+        ? {
+            lifecycle: input.capability.lifecycle.deploy,
+            deploy_action_wired: Boolean(
+              input.capability.runtime.deployAction ||
+              input.capability.runtime.kind === 'provider_manual_webhook',
+            ),
+          }
+        : input.capability.lifecycle[input.mode],
+    suggestion:
+      input.mode === 'deploy'
+        ? 'This monitor tool is modeled but its upstream deploy action is not wired yet.'
+        : 'Choose a monitor tool with lifecycle support from the platform-admin monitor catalog.',
+    entity_type: 'tool',
+    entity_key: input.capability.providerCapability,
+    docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+  });
+}