deepline 0.3.97 → 0.3.98

package/dist/bundling-sources/sdk/src/client.ts

@@ -996,6 +996,35 @@ export type MonitorValidateResult = Record<string, unknown>;
  */
 export type MonitorFleetResult = Record<string, unknown>;
 
+/** Shared response envelope for immutable batch and desired-set Monitor Jobs. */
+export type MonitorJobResult = Record<string, unknown>;
+
+export type MonitorJobDeployOptions = {
+  /** Stable retry key; the server binds it to the submitted immutable set. */
+  idempotencyKey?: string;
+};
+
+export type MonitorJobLogsOptions = { limit?: number };
+
+export type MonitorJobWaitOptions = {
+  timeoutMs?: number;
+  pollIntervalMs?: number;
+  onProgress?: (payload: MonitorJobResult) => void;
+};
+
+export type MonitorJobsNamespace = {
+  get: (jobId: string) => Promise<MonitorJobResult>;
+  logs: (
+    jobId: string,
+    options?: MonitorJobLogsOptions,
+  ) => Promise<MonitorJobResult>;
+  cancel: (jobId: string) => Promise<MonitorJobResult>;
+  wait: (
+    jobId: string,
+    options?: MonitorJobWaitOptions,
+  ) => Promise<MonitorJobResult>;
+};
+
 /** Server-computed fleet verdict. Never derived client-side. */
 export type MonitorFleetStatus =
   | 'converging'
@@ -1093,7 +1122,7 @@ export type MonitorBatchOperationResult = {
       | 'reactivate'
       | 'deploy'
       | 'repair';
-    state: 'running' | 'retry_scheduled' | 'completed' | 'failed';
+    state: 'running' | 'retry_scheduled' | 'completed' | 'failed' | 'cancelled';
     dryRun: boolean;
     scope: unknown;
     submittedAt: number;
@@ -1113,7 +1142,15 @@ export type MonitorBatchOperationResult = {
 
 export type MonitorFleetsNamespace = {
   /**
-   * Create, update, or re-plan a fleet. Pass a definition to admit new source
+   * Primary table-backed Fleet command. It has the same idempotent PUT
+   * contract as `sync`; `sync` remains for installed-client compatibility.
+   */
+  deploy: (
+    definitionOrId: string | MonitorFleetDefinition,
+    options?: MonitorFleetSyncOptions,
+  ) => Promise<MonitorFleetResult>;
+  /**
+   * Compatibility alias for `deploy`. Pass a definition to admit new source
    * of truth; pass a fleet id to re-plan from the stored definition.
    */
   sync: (
@@ -1145,6 +1182,11 @@ export type MonitorFleetsNamespace = {
 };
 
 export type MonitorBatchNamespace = {
+  /** Deploy an immutable one-off list through the common Monitor Job engine. */
+  deploy: (
+    definitions: MonitorDefinition[],
+    options?: MonitorJobDeployOptions,
+  ) => Promise<MonitorJobResult>;
   submit: (
     options: MonitorBatchSubmitOptions,
   ) => Promise<MonitorBatchOperationResult>;
@@ -1370,10 +1412,12 @@ export type MonitorsNamespace = {
   }) => Promise<MonitorsRepairResult>;
   /** Delivery and convergence health for the workspace or one fleet. */
   health: (options?: { fleetId?: string }) => Promise<MonitorsHealth>;
-  /** Durable bulk audit/deactivation/reactivation/repair with retained progress. */
-  batch: MonitorBatchNamespace;
   /** Define, reconcile, and control table-backed monitor fleets. */
   fleets: MonitorFleetsNamespace;
+  /** Deploy an immutable one-off list through the common Monitor Job engine. */
+  batch: MonitorBatchNamespace;
+  /** Read, wait for, inspect, or cancel Monitor Jobs. */
+  jobs: MonitorJobsNamespace;
 };
 
 /** One credit grant pool reported by the billing subscription status endpoint. */
@@ -2333,11 +2377,21 @@ export class DeeplineClient {
       repair: (options) => this.repairMonitors(options),
       health: (options) => this.readMonitorsHealth(options),
       batch: {
+        deploy: (definitions, options) =>
+          this.deployMonitorBatch(definitions, options),
         submit: (options) => this.submitMonitorBatch(options),
         get: (operationId, options) =>
           this.getMonitorBatch(operationId, options),
       },
+      jobs: {
+        get: (jobId) => this.getMonitorJob(jobId),
+        logs: (jobId, options) => this.getMonitorJobLogs(jobId, options),
+        cancel: (jobId) => this.cancelMonitorJob(jobId),
+        wait: (jobId, options) => this.waitForMonitorJob(jobId, options),
+      },
       fleets: {
+        deploy: (definitionOrId, options) =>
+          this.syncMonitorFleet(definitionOrId, options),
         sync: (definitionOrId, options) =>
           this.syncMonitorFleet(definitionOrId, options),
         get: (fleetId, options) =>
@@ -6017,6 +6071,92 @@ export class DeeplineClient {
     );
   }
 
+  // ——————————————————————————————————————————————————————————
+  // Monitor Jobs, Batches, and Fleets
+  // ——————————————————————————————————————————————————————————
+
+  private monitorJobIdempotencyKey(operation: string): string {
+    const uuid = globalThis.crypto?.randomUUID?.();
+    return `monitor-job-${operation}-${uuid ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`}`;
+  }
+
+  private monitorJobHeaders(
+    operation: string,
+    idempotencyKey?: string,
+  ): Record<string, string> {
+    return {
+      'Idempotency-Key':
+        idempotencyKey?.trim() || this.monitorJobIdempotencyKey(operation),
+    };
+  }
+
+  async deployMonitorBatch(
+    definitions: MonitorDefinition[],
+    options?: MonitorJobDeployOptions,
+  ): Promise<MonitorJobResult> {
+    return this.http.request<MonitorJobResult>(
+      '/api/v2/monitors/batch/deploy',
+      {
+        method: 'POST',
+        body: { version: 1, kind: 'batch', monitors: definitions },
+        headers: this.monitorJobHeaders(
+          'batch-deploy',
+          options?.idempotencyKey,
+        ),
+        maxRetries: 0,
+        exactUrlOnly: true,
+      },
+    );
+  }
+
+  async getMonitorJob(jobId: string): Promise<MonitorJobResult> {
+    return this.http.request<MonitorJobResult>(
+      `/api/v2/monitors/jobs/${encodeURIComponent(jobId)}`,
+      { method: 'GET' },
+    );
+  }
+
+  async getMonitorJobLogs(
+    jobId: string,
+    options?: MonitorJobLogsOptions,
+  ): Promise<MonitorJobResult> {
+    const query =
+      options?.limit === undefined
+        ? ''
+        : `?limit=${encodeURIComponent(String(options.limit))}`;
+    return this.http.request<MonitorJobResult>(
+      `/api/v2/monitors/jobs/${encodeURIComponent(jobId)}/logs${query}`,
+      { method: 'GET' },
+    );
+  }
+
+  async cancelMonitorJob(jobId: string): Promise<MonitorJobResult> {
+    return this.http.request<MonitorJobResult>(
+      `/api/v2/monitors/jobs/${encodeURIComponent(jobId)}/cancel`,
+      { method: 'POST', body: {}, maxRetries: 0, exactUrlOnly: true },
+    );
+  }
+
+  async waitForMonitorJob(
+    jobId: string,
+    options?: MonitorJobWaitOptions,
+  ): Promise<MonitorJobResult> {
+    const timeoutMs = Math.max(1, options?.timeoutMs ?? 10 * 60_000);
+    const pollIntervalMs = Math.max(1, options?.pollIntervalMs ?? 2_000);
+    const terminal = new Set(['succeeded', 'failed', 'cancelled']);
+    const startedAt = Date.now();
+    let latest = await this.getMonitorJob(jobId);
+    while (true) {
+      options?.onProgress?.(latest);
+      const job = latest.job as Record<string, unknown> | undefined;
+      const state = typeof job?.state === 'string' ? job.state : undefined;
+      if (state && terminal.has(state)) return latest;
+      if (Date.now() - startedAt >= timeoutMs) return latest;
+      await sleep(pollIntervalMs);
+      latest = await this.getMonitorJob(jobId);
+    }
+  }
+
   // ——————————————————————————————————————————————————————————
   // Monitor Fleets
   // ——————————————————————————————————————————————————————————

package/dist/bundling-sources/sdk/src/index.ts

@@ -86,6 +86,12 @@ export type {
   MonitorUpdateResult,
   MonitorDeleteResult,
   MonitorReactivateResult,
+  MonitorJobResult,
+  MonitorJobDeployOptions,
+  MonitorJobLogsOptions,
+  MonitorJobWaitOptions,
+  MonitorJobsNamespace,
+  MonitorBatchNamespace,
   MonitorFleetDeactivateOptions,
   MonitorFleetReactivateOptions,
   MonitorFleetGetOptions,
@@ -113,11 +119,17 @@ export type {
 
 // ——— Monitors framework ———
 export { defineMonitor } from './monitors.js';
+export type { MonitorDefinition, MonitorPayload } from './monitors.js';
+export {
+  lintMonitorBatchInput,
+  lintMonitorSpecTemplate,
+  renderMonitorSpecTemplate,
+} from './monitor-input-contract.js';
 export type {
-  MonitorDefinition,
-  MonitorPayload,
-  MonitorControls,
-} from './monitors.js';
+  BatchMonitorInput,
+  MonitorInputIssue,
+  MonitorSpec as MonitorInputSpec,
+} from './monitor-input-contract.js';
 export {
   admitMonitorFleetAuthoringContract,
   MONITOR_FLEET_AUTHORING_CONTRACT_CHANGELOG,
@@ -128,6 +140,7 @@ export {
   defineMonitorFleet,
   fleetColumn,
   fleetKey,
+  lintMonitorFleetInput,
   validateMonitorFleetDefinition,
 } from './monitor-fleets.js';
 export type {

package/dist/bundling-sources/sdk/src/monitor-fleets.ts

@@ -16,6 +16,7 @@ export {
   defineMonitorFleet,
   fleetColumn,
   fleetKey,
+  lintMonitorFleetInput,
   validateMonitorFleetDefinition,
 } from '../../shared_libs/integration-contracts/monitor-fleet-contract';
 

package/dist/bundling-sources/sdk/src/monitor-input-contract.ts

@@ -0,0 +1 @@
+export * from '../../shared_libs/integration-contracts/monitor-input-contract';

package/dist/bundling-sources/sdk/src/monitors.ts

@@ -48,30 +48,11 @@ export type MonitorDefinition<
   name?: string;
   /** Provider-specific monitor payload (e.g. domain + radar_type). */
   payload: TPayload;
-  /** Optional Deepline lifecycle metadata (deploy/reuse controls). */
-  controls?: MonitorControls;
 };
 
 /** Provider-specific monitor payload. Keys and value types depend on the tool. */
 export type MonitorPayload = Record<string, unknown>;
 
-/**
- * Deepline lifecycle metadata attached to a monitor definition. These are
- * Deepline-side deploy/reuse controls, not provider payload fields. The set is
- * intentionally open (server-owned) so newer controls do not require an SDK
- * bump; known controls are typed for discoverability.
- */
-export type MonitorControls = {
-  /**
-   * Request Deepline Native priority execution for a bounded urgent preview or
-   * calibration radar. Deepline sends the upstream custom-field marker and
-   * enforces a maximum of ten active or in-flight priority radars per org.
-   * Omit this for regular and bulk-scale monitoring.
-   */
-  execution_type?: 'priority';
-  [key: string]: unknown;
-};
-
 /**
  * Define a typed monitor definition.
  *
@@ -125,13 +106,15 @@ export function defineMonitor<TPayload extends MonitorPayload = MonitorPayload>(
   if (definition.name !== undefined && typeof definition.name !== 'string') {
     throw new Error('defineMonitor(definition) "name" must be a string.');
   }
-  if (
-    definition.controls !== undefined &&
-    (typeof definition.controls !== 'object' ||
-      Array.isArray(definition.controls))
-  ) {
+  const authored = definition as Record<string, unknown>;
+  if ('controls' in authored) {
+    throw new Error(
+      'defineMonitor(definition) does not accept "controls". Operational controls are managed by Deepline; bind downstream automation in a Play with sqlListeners.',
+    );
+  }
+  if ('play' in authored) {
     throw new Error(
-      'defineMonitor(definition) "controls" must be a JSON object.',
+      'defineMonitor(definition) does not accept "play". A monitor does not own Play bindings; declare sqlListeners in the Play instead.',
     );
   }
   return definition;

package/dist/bundling-sources/sdk/src/release.ts

@@ -200,7 +200,7 @@ export const SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: '0.3.97',
+  version: '0.3.98',
   updateSummary:
     'Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.',
   packageCapabilities: {

package/dist/bundling-sources/shared_libs/integration-contracts/index.ts

@@ -1,2 +1,3 @@
 export * from './bettercontact/execution-policy';
 export * from './theirstack/execution-policy';
+export * from './monitor-input-contract';

package/dist/bundling-sources/shared_libs/integration-contracts/monitor-fleet-contract.ts

@@ -1,3 +1,8 @@
+import {
+  lintMonitorSpecTemplate,
+  type MonitorInputIssue,
+} from './monitor-input-contract';
+
 /**
  * The canonical Fleet authoring contract, shared by the SDK and server.
  * Monitor transaction admission reuses this ceiling; it must never drift
@@ -12,9 +17,9 @@ export const MONITOR_FLEET_FRONTIER_MAX_ROWS = 10_000;
  * edition: a future syntax change can add a reader without reinterpreting a
  * stored Fleet under new rules.
  */
-export const MONITOR_FLEET_AUTHORING_CONTRACT_EDITION = 1 as const;
+export const MONITOR_FLEET_AUTHORING_CONTRACT_EDITION = 2 as const;
 export const SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS = [
-  MONITOR_FLEET_AUTHORING_CONTRACT_EDITION,
+  1, 2,
 ] as const;
 
 export type MonitorFleetAuthoringContractEdition =
@@ -24,7 +29,15 @@ export const MONITOR_FLEET_AUTHORING_CONTRACT_CHANGELOG = [
   {
     edition: 1,
     changed:
-      'Initial Fleet JSON contract: bounded sticky table membership, one daily sync, and a seven-day removal grace.',
+      'Initial Fleet JSON contract: bounded sticky table membership, source refresh, and a seven-day removal grace.',
+    compatibilityOwner: 'Monitors Runtime',
+    newWritesEnd: null,
+    readerRemoval: null,
+  },
+  {
+    edition: 2,
+    changed:
+      'Canonical table-backed Fleet envelope with one Handlebars MonitorSpec template.',
     compatibilityOwner: 'Monitors Runtime',
     newWritesEnd: null,
     readerRemoval: null,
@@ -50,13 +63,13 @@ export const MONITOR_FLEET_DOCUMENTATION = {
     id: 'Stable lowercase fleet id used by sync, get, and deactivate.',
     source:
       'Customer DB table, unique row key, and optional equality filters that select candidate rows.',
-    member:
-      'Ordinary monitor tool, stable key template, and payload evaluated for each selected source row.',
+    monitor:
+      'One Batch-compatible MonitorSpec. Direct Handlebars source-row fields such as {{domain}} are rendered for each selected row.',
     selection:
       'Deterministic ranking and an active-member limit between 1 and 1,000.',
   },
   fixedPolicy: {
-    cadence: 'daily',
+    cadence: '60s fair bounded source refresh',
     membership: 'sticky',
     removalGrace: '7d',
     onRemoved: 'deactivate',
@@ -67,8 +80,10 @@ export const MONITOR_FLEET_DOCUMENTATION = {
   },
   stickyMembership:
     'Ranking fills vacancies but never replaces a current member merely because another row ranks higher.',
-  columnExpression:
-    'Use { "$fleet": "column", "name": "column_name" } in a member key or payload to read a value from each source row.',
+  templating:
+    'Use direct Handlebars fields such as {{domain}} in monitor key, name, or payload. Helpers, blocks, partials, paths, and prototype access are disabled.',
+  legacyCompatibility:
+    'Edition 1 member/$fleet files remain readable with a lint warning; new files should use version: 2, kind: "fleet", and monitor.',
 } as const;
 
 export type MonitorFleetColumn = {
@@ -83,7 +98,7 @@ export type MonitorFleetTemplate = {
 
 export type MonitorFleetExpression = MonitorFleetColumn | MonitorFleetTemplate;
 
-export type MonitorFleetDefinition = {
+export type MonitorFleetDefinitionV1 = {
   /** Stable lowercase fleet id, used by CLI and API lifecycle commands. */
   id: string;
   /** Customer DB rows that may become members. */
@@ -115,6 +130,28 @@ export type MonitorFleetDefinition = {
   };
 };
 
+/**
+ * Edition 2 keeps the public file self-describing and aligns the rendered
+ * member with Batch exactly. Only source-row values may be interpolated.
+ */
+export type MonitorFleetDefinitionV2 = {
+  version: 2;
+  kind: 'fleet';
+  id: string;
+  source: MonitorFleetDefinitionV1['source'];
+  monitor: {
+    key: string;
+    tool: string;
+    name?: string;
+    payload: Record<string, unknown>;
+  };
+  selection: MonitorFleetDefinitionV1['selection'];
+};
+
+export type MonitorFleetDefinition =
+  | MonitorFleetDefinitionV1
+  | MonitorFleetDefinitionV2;
+
 export type MonitorFleetContractIssue = {
   path: string;
   code: string;
@@ -249,7 +286,7 @@ function walkPayload(
   }
 }
 
-export function validateMonitorFleetDefinition(value: unknown): {
+function validateMonitorFleetDefinitionV1(value: unknown): {
   valid: boolean;
   definition?: MonitorFleetDefinition;
   issues: MonitorFleetContractIssue[];
@@ -475,10 +512,130 @@ export function validateMonitorFleetDefinition(value: unknown): {
     }
   }
   return issues.length === 0
-    ? { valid: true, definition: value as MonitorFleetDefinition, issues }
+    ? { valid: true, definition: value as MonitorFleetDefinitionV1, issues }
     : { valid: false, issues };
 }
 
+function v2Issue(issue: MonitorInputIssue): MonitorFleetContractIssue {
+  return { path: issue.path, code: issue.code, message: issue.message };
+}
+
+function validateMonitorFleetDefinitionV2(value: unknown): {
+  valid: boolean;
+  definition?: MonitorFleetDefinitionV2;
+  issues: MonitorFleetContractIssue[];
+} {
+  const issues: MonitorFleetContractIssue[] = [];
+  const input = record(value);
+  if (!input) {
+    return {
+      valid: false,
+      issues: [
+        {
+          path: '',
+          code: 'invalid_fleet',
+          message: 'Fleet must be an object.',
+        },
+      ],
+    };
+  }
+  exactKeys(
+    input,
+    ['version', 'kind', 'id', 'source', 'monitor', 'selection'],
+    '',
+    issues,
+  );
+  if (input.version !== 2) {
+    issues.push({
+      path: 'version',
+      code: 'unsupported_fleet_version',
+      message: 'Canonical Fleet input version must be 2.',
+    });
+  }
+  if (input.kind !== 'fleet') {
+    issues.push({
+      path: 'kind',
+      code: 'invalid_fleet_kind',
+      message: 'Canonical Fleet input kind must be "fleet".',
+    });
+  }
+  // Reuse the battle-tested source and selection validator without making
+  // edition 2 accept its legacy member grammar.
+  const source = record(input.source);
+  const sourceKey = record(source?.key);
+  const legacyShape = {
+    id: input.id,
+    source: input.source,
+    member: {
+      tool: record(input.monitor)?.tool,
+      key: {
+        $fleet: 'template',
+        parts: [
+          'fleet-',
+          {
+            $fleet: 'column',
+            name:
+              typeof sourceKey?.column === 'string'
+                ? sourceKey.column
+                : 'invalid_source_key',
+          },
+        ],
+      },
+      payload: record(input.monitor)?.payload,
+    },
+    selection: input.selection,
+  };
+  const legacyCheck = validateMonitorFleetDefinitionV1(legacyShape);
+  for (const issue of legacyCheck.issues) {
+    issues.push({
+      ...issue,
+      path: issue.path.replace(/^member\./, 'monitor.'),
+    });
+  }
+  const monitorInput = record(input.monitor);
+  const monitorKey = monitorInput?.key;
+  const monitor = lintMonitorSpecTemplate(input.monitor);
+  issues.push(...monitor.issues.map(v2Issue));
+  if (
+    typeof monitorKey === 'string' &&
+    typeof sourceKey?.column === 'string' &&
+    !monitorKey.includes(`{{${sourceKey.column}}}`)
+  ) {
+    issues.push({
+      path: 'monitor.key',
+      code: 'fleet_key_missing_source_key',
+      message:
+        'Monitor key must include the source key as a direct Handlebars expression.',
+    });
+  }
+  return issues.length === 0 && monitor.normalized
+    ? {
+        valid: true,
+        definition: {
+          version: 2,
+          kind: 'fleet',
+          id: String(input.id),
+          source: input.source as MonitorFleetDefinitionV2['source'],
+          monitor: monitor.normalized,
+          selection: input.selection as MonitorFleetDefinitionV2['selection'],
+        },
+        issues,
+      }
+    : { valid: false, issues };
+}
+
+/** Validate the declared edition, or detect canonical v2 versus legacy v1. */
+export function validateMonitorFleetDefinition(value: unknown): {
+  valid: boolean;
+  definition?: MonitorFleetDefinition;
+  issues: MonitorFleetContractIssue[];
+} {
+  const input = record(value);
+  return input?.version === 2 || input?.kind === 'fleet'
+    ? validateMonitorFleetDefinitionV2(value)
+    : validateMonitorFleetDefinitionV1(value);
+}
+
 /**
  * Compile JSON into the exact authoring snapshot persisted by a Fleet.  This
  * does not inspect the Customer DB or provider; use
@@ -487,11 +644,14 @@ export function validateMonitorFleetDefinition(value: unknown): {
  */
 export function admitMonitorFleetAuthoringContract(
   value: unknown,
-  edition: number = MONITOR_FLEET_AUTHORING_CONTRACT_EDITION,
+  edition?: number,
 ): MonitorFleetAuthoringContractResult {
+  const detectedEdition =
+    edition ??
+    (record(value)?.version === 2 || record(value)?.kind === 'fleet' ? 2 : 1);
   if (
     !SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS.includes(
-      edition as MonitorFleetAuthoringContractEdition,
+      detectedEdition as MonitorFleetAuthoringContractEdition,
     )
   ) {
     return {
@@ -500,17 +660,20 @@ export function admitMonitorFleetAuthoringContract(
         {
           path: 'authoring_contract_edition',
           code: 'unsupported_fleet_authoring_contract_edition',
-          message: `Monitor Fleet authoring contract edition ${edition} is not supported.`,
+          message: `Monitor Fleet authoring contract edition ${detectedEdition} is not supported.`,
         },
       ],
     };
   }
-  const result = validateMonitorFleetDefinition(value);
+  const result =
+    detectedEdition === 2
+      ? validateMonitorFleetDefinitionV2(value)
+      : validateMonitorFleetDefinitionV1(value);
   return result.valid && result.definition
     ? {
         valid: true,
         contract: {
-          edition: edition as MonitorFleetAuthoringContractEdition,
+          edition: detectedEdition as MonitorFleetAuthoringContractEdition,
           // JSON cloning prevents later caller mutation from changing the
           // admitted snapshot.
           definition: JSON.parse(
@@ -522,6 +685,45 @@ export function admitMonitorFleetAuthoringContract(
     : { valid: false, issues: result.issues };
 }
 
+/**
+ * Fast provider-free admission shared by the Fleet CLI, SDK, and API. Legacy
+ * documents remain executable but receive an actionable migration warning.
+ */
+export function lintMonitorFleetInput(value: unknown): {
+  normalized?: MonitorFleetDefinition;
+  issues: Array<MonitorFleetContractIssue & { severity: 'error' | 'warning' }>;
+} {
+  const input = record(value);
+  const legacy = input?.member !== undefined;
+  const admitted = admitMonitorFleetAuthoringContract(value);
+  const issues: Array<
+    MonitorFleetContractIssue & { severity: 'error' | 'warning' }
+  > = admitted.issues.map((issue) => ({
+    ...issue,
+    severity: 'error' as const,
+  }));
+  if (legacy) {
+    issues.push({
+      severity: 'warning',
+      code: 'deprecated_fleet_member',
+      path: 'member',
+      message: 'Legacy Fleet member syntax remains supported.',
+    });
+    if (JSON.stringify(input).includes('"$fleet"')) {
+      issues.push({
+        severity: 'warning',
+        code: 'deprecated_fleet_expression',
+        path: 'member',
+        message:
+          'Legacy $fleet expressions remain supported; use direct Handlebars fields in monitor instead.',
+      });
+    }
+  }
+  return admitted.valid && admitted.contract
+    ? { normalized: admitted.contract.definition, issues }
+    : { issues };
+}
+
 export function evaluateMonitorFleetValue(
   value: unknown,
   row: Record<string, unknown>,