deepline 0.3.97 → 0.3.98

package/dist/index.mjs

@@ -768,7 +768,7 @@ var 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: {
     updatePreferences: 1
@@ -2806,9 +2806,9 @@ function nonEmptyString(value) {
 }
 function normalizeDatasetBornFrom(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  const record2 = value;
-  const table = nonEmptyString(record2.table);
-  const rowCountIn = finiteNonNegativeInteger2(record2.rowCountIn);
+  const record3 = value;
+  const table = nonEmptyString(record3.table);
+  const rowCountIn = finiteNonNegativeInteger2(record3.rowCountIn);
   if (!table || rowCountIn === null) return null;
   return { table, rowCountIn };
 }
@@ -3897,21 +3897,21 @@ function normalizePlayRuntimeNamespace(value) {
 }
 function normalizePlayRuntimeSelection(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  const record2 = value;
-  if (Object.keys(record2).some(
+  const record3 = value;
+  if (Object.keys(record3).some(
     (key) => key !== "environment" && key !== "namespace" && key !== "backend"
-  ) || record2.environment !== "preview") {
+  ) || record3.environment !== "preview") {
     return null;
   }
-  const namespace = normalizePlayRuntimeNamespace(record2.namespace);
+  const namespace = normalizePlayRuntimeNamespace(record3.namespace);
   if (!namespace) return null;
-  if (record2.backend === void 0) {
+  if (record3.backend === void 0) {
     return { environment: "preview", namespace };
   }
-  if (record2.backend !== PLAY_RUNTIME_BACKENDS.daytona && record2.backend !== PLAY_RUNTIME_BACKENDS.modal) {
+  if (record3.backend !== PLAY_RUNTIME_BACKENDS.daytona && record3.backend !== PLAY_RUNTIME_BACKENDS.modal) {
     return null;
   }
-  return { environment: "preview", namespace, backend: record2.backend };
+  return { environment: "preview", namespace, backend: record3.backend };
 }
 function normalizePlayRuntimeEnvironment(value) {
   return typeof value === "string" && PLAY_RUNTIME_ENVIRONMENTS.includes(value) ? value : null;
@@ -4556,10 +4556,18 @@ var DeeplineClient = class {
       repair: (options2) => this.repairMonitors(options2),
       health: (options2) => this.readMonitorsHealth(options2),
       batch: {
+        deploy: (definitions, options2) => this.deployMonitorBatch(definitions, options2),
         submit: (options2) => this.submitMonitorBatch(options2),
         get: (operationId, options2) => this.getMonitorBatch(operationId, options2)
       },
+      jobs: {
+        get: (jobId) => this.getMonitorJob(jobId),
+        logs: (jobId, options2) => this.getMonitorJobLogs(jobId, options2),
+        cancel: (jobId) => this.cancelMonitorJob(jobId),
+        wait: (jobId, options2) => this.waitForMonitorJob(jobId, options2)
+      },
       fleets: {
+        deploy: (definitionOrId, options2) => this.syncMonitorFleet(definitionOrId, options2),
         sync: (definitionOrId, options2) => this.syncMonitorFleet(definitionOrId, options2),
         get: (fleetId, options2) => fleetId === void 0 ? this.listMonitorFleets() : this.getMonitorFleet(fleetId, options2),
         list: () => this.listMonitorFleets(),
@@ -7311,6 +7319,68 @@ var DeeplineClient = class {
     );
   }
   // ——————————————————————————————————————————————————————————
+  // Monitor Jobs, Batches, and Fleets
+  // ——————————————————————————————————————————————————————————
+  monitorJobIdempotencyKey(operation) {
+    const uuid = globalThis.crypto?.randomUUID?.();
+    return `monitor-job-${operation}-${uuid ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`}`;
+  }
+  monitorJobHeaders(operation, idempotencyKey) {
+    return {
+      "Idempotency-Key": idempotencyKey?.trim() || this.monitorJobIdempotencyKey(operation)
+    };
+  }
+  async deployMonitorBatch(definitions, options) {
+    return this.http.request(
+      "/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) {
+    return this.http.request(
+      `/api/v2/monitors/jobs/${encodeURIComponent(jobId)}`,
+      { method: "GET" }
+    );
+  }
+  async getMonitorJobLogs(jobId, options) {
+    const query = options?.limit === void 0 ? "" : `?limit=${encodeURIComponent(String(options.limit))}`;
+    return this.http.request(
+      `/api/v2/monitors/jobs/${encodeURIComponent(jobId)}/logs${query}`,
+      { method: "GET" }
+    );
+  }
+  async cancelMonitorJob(jobId) {
+    return this.http.request(
+      `/api/v2/monitors/jobs/${encodeURIComponent(jobId)}/cancel`,
+      { method: "POST", body: {}, maxRetries: 0, exactUrlOnly: true }
+    );
+  }
+  async waitForMonitorJob(jobId, options) {
+    const timeoutMs = Math.max(1, options?.timeoutMs ?? 10 * 6e4);
+    const pollIntervalMs = Math.max(1, options?.pollIntervalMs ?? 2e3);
+    const terminal = /* @__PURE__ */ new Set(["succeeded", "failed", "cancelled"]);
+    const startedAt = Date.now();
+    let latest = await this.getMonitorJob(jobId);
+    while (true) {
+      options?.onProgress?.(latest);
+      const job = latest.job;
+      const state = typeof job?.state === "string" ? job.state : void 0;
+      if (state && terminal.has(state)) return latest;
+      if (Date.now() - startedAt >= timeoutMs) return latest;
+      await sleep2(pollIntervalMs);
+      latest = await this.getMonitorJob(jobId);
+    }
+  }
+  // ——————————————————————————————————————————————————————————
   // Monitor Fleets
   // ——————————————————————————————————————————————————————————
   monitorFleetIdempotencyKey(operation) {
@@ -8469,8 +8539,8 @@ function firstExperienceDate(value) {
   return null;
 }
 function normalizeJobChange(value) {
-  const record2 = isRecord8(value) ? value : {};
-  const nested = isRecord8(record2.job_change) ? record2.job_change : record2;
+  const record3 = isRecord8(value) ? value : {};
+  const nested = isRecord8(record3.job_change) ? record3.job_change : record3;
   const output = isRecord8(nested.output) ? nested.output : nested;
   const person = isRecord8(output.person) ? output.person : {};
   const status = normalizeJobChangeStatus(
@@ -11143,25 +11213,388 @@ function defineMonitor(definition) {
   if (definition.name !== void 0 && typeof definition.name !== "string") {
     throw new Error('defineMonitor(definition) "name" must be a string.');
   }
-  if (definition.controls !== void 0 && (typeof definition.controls !== "object" || Array.isArray(definition.controls))) {
+  const authored = definition;
+  if ("controls" in authored) {
     throw new Error(
-      'defineMonitor(definition) "controls" must be a JSON object.'
+      '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) does not accept "play". A monitor does not own Play bindings; declare sqlListeners in the Play instead.'
     );
   }
   return definition;
 }
 
+// ../integration-contracts/monitor-input-contract.ts
+import Handlebars from "handlebars";
+function authoredMonitorFieldPath(path, field) {
+  const batch = /^monitors\.(\d+)$/.exec(path);
+  return `${batch ? `monitors[${batch[1]}]` : path}.${field}`;
+}
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function json(value, path, issues) {
+  if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((child, index) => json(child, `${path}.${index}`, issues));
+    return;
+  }
+  const object = record(value);
+  if (!object) {
+    issues.push({
+      severity: "error",
+      code: "invalid_monitor_json_value",
+      path,
+      message: "Monitor values must be JSON values."
+    });
+    return;
+  }
+  for (const [key, child] of Object.entries(object)) {
+    json(child, `${path}.${key}`, issues);
+  }
+}
+function monitorSpec(value, path, issues) {
+  const input = record(value);
+  if (!input) {
+    issues.push({
+      severity: "error",
+      code: "invalid_monitor_spec",
+      path,
+      message: "A monitor must be a JSON object."
+    });
+    return null;
+  }
+  const allowed = /* @__PURE__ */ new Set(["key", "tool", "name", "payload"]);
+  for (const key2 of Object.keys(input)) {
+    if (!allowed.has(key2)) {
+      if (key2 === "controls") {
+        issues.push({
+          severity: "error",
+          code: "CONTROLS_NOT_SUPPORTED",
+          path: authoredMonitorFieldPath(path, "controls"),
+          message: "Operational controls are managed by Deepline and cannot be authored in Batch or Fleet JSON.",
+          suggestion: "Remove controls. Bind downstream automation in a Play with sqlListeners."
+        });
+        continue;
+      }
+      if (key2 === "play") {
+        issues.push({
+          severity: "error",
+          code: "PLAY_BINDING_NOT_IN_MONITOR_SPEC",
+          path: authoredMonitorFieldPath(path, "play"),
+          message: "A monitor does not own Play bindings.",
+          suggestion: "Declare sqlListeners in the Play, or run: deepline plays bootstrap monitor-triggered --out on-event.play.ts"
+        });
+        continue;
+      }
+      issues.push({
+        severity: "error",
+        code: "unknown_monitor_field",
+        path: `${path}.${key2}`,
+        message: `Monitor definitions do not accept '${key2}'.`
+      });
+    }
+  }
+  const key = typeof input.key === "string" ? input.key.trim() : "";
+  const tool = typeof input.tool === "string" ? input.tool.trim() : "";
+  const name = input.name === void 0 ? void 0 : typeof input.name === "string" && input.name.trim() ? input.name.trim() : null;
+  const payload = record(input.payload);
+  if (!key) {
+    issues.push({
+      severity: "error",
+      code: "invalid_monitor_key",
+      path: `${path}.key`,
+      message: "Monitor key must be a non-empty string."
+    });
+  }
+  if (!tool) {
+    issues.push({
+      severity: "error",
+      code: "invalid_monitor_tool",
+      path: `${path}.tool`,
+      message: "Monitor tool must be a non-empty literal string."
+    });
+  }
+  if (name === null) {
+    issues.push({
+      severity: "error",
+      code: "invalid_monitor_name",
+      path: `${path}.name`,
+      message: "Monitor name must be a non-empty string when supplied."
+    });
+  }
+  if (!payload) {
+    issues.push({
+      severity: "error",
+      code: "invalid_monitor_payload",
+      path: `${path}.payload`,
+      message: "Monitor payload must be an object."
+    });
+  } else {
+    json(payload, `${path}.payload`, issues);
+  }
+  if (!key || !tool || !payload || name === null) {
+    return null;
+  }
+  return {
+    key,
+    tool,
+    ...name ? { name } : {},
+    payload
+  };
+}
+function issueOrder(left, right) {
+  return left.path.localeCompare(right.path) || left.severity.localeCompare(right.severity) || left.code.localeCompare(right.code);
+}
+function lintMonitorBatchInput(value) {
+  const issues = [];
+  const versionlessEnvelope = !Array.isArray(value) && (() => {
+    const candidate = record(value);
+    return candidate !== null && Object.keys(candidate).length === 1 && Object.prototype.hasOwnProperty.call(candidate, "monitors");
+  })();
+  const legacy = Array.isArray(value) || versionlessEnvelope;
+  const input = legacy ? null : record(value);
+  let monitors = Array.isArray(value) ? value : versionlessEnvelope ? (() => {
+    const candidate = record(value)?.monitors;
+    return Array.isArray(candidate) ? candidate : null;
+  })() : null;
+  if (Array.isArray(value)) {
+    issues.push({
+      severity: "warning",
+      code: "deprecated_batch_array",
+      path: "",
+      message: "Bare monitor arrays are supported for compatibility.",
+      suggestion: 'Wrap the list in {"version":1,"kind":"batch","monitors":[...]}.'
+    });
+  } else if (versionlessEnvelope) {
+    issues.push({
+      severity: "warning",
+      code: "deprecated_batch_missing_envelope_fields",
+      path: "",
+      message: "Versionless monitor envelopes are supported for compatibility.",
+      suggestion: 'Add "version": 1 and "kind": "batch".'
+    });
+    if (!monitors) {
+      issues.push({
+        severity: "error",
+        code: "invalid_batch_monitors",
+        path: "monitors",
+        message: "Batch monitors must be an array."
+      });
+    }
+  } else if (!input) {
+    issues.push({
+      severity: "error",
+      code: "invalid_batch",
+      path: "",
+      message: "Batch input must be an object or a legacy array."
+    });
+  } else {
+    for (const key of Object.keys(input)) {
+      if (!["version", "kind", "monitors"].includes(key)) {
+        issues.push({
+          severity: "error",
+          code: key === "source" || key === "monitor" ? "batch_fleet_shape_mixup" : "unknown_batch_field",
+          path: key,
+          message: `Batch input does not accept '${key}'.`
+        });
+      }
+    }
+    if (input.version !== 1) {
+      issues.push({
+        severity: "error",
+        code: "unsupported_batch_version",
+        path: "version",
+        message: "Batch input version must be 1."
+      });
+    }
+    if (input.kind !== "batch") {
+      issues.push({
+        severity: "error",
+        code: "invalid_batch_kind",
+        path: "kind",
+        message: 'Batch input kind must be "batch".'
+      });
+    }
+    monitors = Array.isArray(input.monitors) ? input.monitors : null;
+    if (!monitors) {
+      issues.push({
+        severity: "error",
+        code: "invalid_batch_monitors",
+        path: "monitors",
+        message: "Batch monitors must be an array."
+      });
+    }
+  }
+  if (!monitors || monitors.length === 0) {
+    if (monitors?.length === 0) {
+      issues.push({
+        severity: "error",
+        code: "empty_batch",
+        path: "monitors",
+        message: "A Batch needs at least one monitor."
+      });
+    }
+    return { issues: issues.sort(issueOrder) };
+  }
+  const normalized = monitors.map(
+    (item, index) => monitorSpec(item, `monitors.${index}`, issues)
+  );
+  const seen = /* @__PURE__ */ new Map();
+  normalized.forEach((item, index) => {
+    if (!item) return;
+    const first = seen.get(item.key);
+    if (first !== void 0) {
+      for (const position of [first, index]) {
+        issues.push({
+          severity: "error",
+          code: "duplicate_monitor_key",
+          path: `monitors.${position}.key`,
+          message: `Duplicate monitor key '${item.key}'.`
+        });
+      }
+    } else {
+      seen.set(item.key, index);
+    }
+  });
+  const ordered = issues.sort(issueOrder);
+  return ordered.some((issue) => issue.severity === "error") ? { issues: ordered } : {
+    normalized: {
+      version: 1,
+      kind: "batch",
+      monitors: normalized
+    },
+    issues: ordered
+  };
+}
+function validateHandlebars(value, path, issues) {
+  if (!value.includes("{{")) return;
+  try {
+    Handlebars.parse(value);
+  } catch (error) {
+    issues.push({
+      severity: "error",
+      code: "invalid_handlebars_template",
+      path,
+      message: error instanceof Error ? error.message : "Invalid Handlebars template."
+    });
+    return;
+  }
+  const expressions = value.match(/{{[\s\S]*?}}/g) ?? [];
+  if (expressions.some(
+    (expression) => !/^{{\s*[A-Za-z_][A-Za-z0-9_]*\s*}}$/.test(expression)
+  )) {
+    issues.push({
+      severity: "error",
+      code: "unsupported_handlebars_expression",
+      path,
+      message: "Fleet templates allow only direct source-row fields such as {{domain}}; helpers, blocks, partials, paths, and prototype access are disabled."
+    });
+  }
+}
+function walkTemplates(value, path, issues) {
+  if (typeof value === "string") return validateHandlebars(value, path, issues);
+  if (Array.isArray(value)) {
+    value.forEach(
+      (item, index) => walkTemplates(item, `${path}.${index}`, issues)
+    );
+    return;
+  }
+  const input = record(value);
+  if (!input) return;
+  for (const [key, child] of Object.entries(input)) {
+    walkTemplates(child, `${path}.${key}`, issues);
+  }
+}
+function lintMonitorSpecTemplate(value, path = "monitor") {
+  const issues = [];
+  const normalized = monitorSpec(value, path, issues);
+  const input = record(value);
+  if (input && typeof input.tool === "string" && input.tool.includes("{{")) {
+    issues.push({
+      severity: "error",
+      code: "templated_monitor_tool",
+      path: `${path}.tool`,
+      message: "Fleet monitor tool must be literal; only key, name, and payload may be templated."
+    });
+  }
+  if (input) {
+    for (const field of ["key", "name", "payload"]) {
+      if (input[field] !== void 0)
+        walkTemplates(input[field], `${path}.${field}`, issues);
+    }
+  }
+  const ordered = issues.sort(issueOrder);
+  return ordered.some((issue) => issue.severity === "error") ? { issues: ordered } : { normalized, issues: ordered };
+}
+function renderValue(value, row) {
+  if (typeof value === "string" && value.includes("{{")) {
+    const context = Object.assign(/* @__PURE__ */ Object.create(null), row);
+    return Handlebars.compile(value, {
+      noEscape: true,
+      strict: true,
+      knownHelpersOnly: true,
+      preventIndent: true
+    })(context, {
+      allowProtoMethodsByDefault: false,
+      allowProtoPropertiesByDefault: false,
+      helpers: /* @__PURE__ */ Object.create(null),
+      partials: /* @__PURE__ */ Object.create(null)
+    });
+  }
+  if (Array.isArray(value)) return value.map((item) => renderValue(item, row));
+  const input = record(value);
+  if (!input) return value;
+  return Object.fromEntries(
+    Object.entries(input).map(([key, item]) => [key, renderValue(item, row)])
+  );
+}
+function renderMonitorSpecTemplate(template, row) {
+  const lint = lintMonitorSpecTemplate(template);
+  if (!lint.normalized) return { issues: lint.issues };
+  try {
+    const rendered = renderValue(lint.normalized, row);
+    const issues = [];
+    const spec = monitorSpec(rendered, "monitor", issues);
+    return spec ? { spec, issues: issues.sort(issueOrder) } : { issues: issues.sort(issueOrder) };
+  } catch (error) {
+    return {
+      issues: [
+        {
+          severity: "error",
+          code: "monitor_template_render_failed",
+          path: "monitor",
+          message: error instanceof Error ? error.message : "Fleet template rendering failed."
+        }
+      ]
+    };
+  }
+}
+
 // ../integration-contracts/monitor-fleet-contract.ts
 var MONITOR_FLEET_MAX_MEMBERS = 1e3;
 var MONITOR_FLEET_FRONTIER_MAX_ROWS = 1e4;
-var MONITOR_FLEET_AUTHORING_CONTRACT_EDITION = 1;
+var MONITOR_FLEET_AUTHORING_CONTRACT_EDITION = 2;
 var SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS = [
-  MONITOR_FLEET_AUTHORING_CONTRACT_EDITION
+  1,
+  2
 ];
 var 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.",
+    changed: "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
@@ -11173,11 +11606,11 @@ var MONITOR_FLEET_DOCUMENTATION = {
   authoredFields: {
     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",
@@ -11185,9 +11618,10 @@ var MONITOR_FLEET_DOCUMENTATION = {
     billing: "No Fleet fee, permit, or renewal. Dry-run reports ordinary monitor lifecycle charges due now."
   },
   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.'
 };
-function record(value) {
+function record2(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
 function identifier(value) {
@@ -11212,7 +11646,7 @@ function jsonValue(value, path, issues) {
     value.forEach((item, index) => jsonValue(item, `${path}.${index}`, issues));
     return;
   }
-  const input = record(value);
+  const input = record2(value);
   if (!input) {
     issues.push({
       path,
@@ -11238,7 +11672,7 @@ function defineMonitorFleet(definition) {
   return definition;
 }
 function validateExpression(value, path, issues) {
-  const input = record(value);
+  const input = record2(value);
   if (!input || input.$fleet !== "column" || !identifier(input.name)) {
     issues.push({
       path,
@@ -11256,7 +11690,7 @@ function walkPayload(value, path, issues) {
     );
     return;
   }
-  const input = record(value);
+  const input = record2(value);
   if (!input) return;
   if ("$fleet" in input) {
     validateExpression(input, path, issues);
@@ -11266,9 +11700,9 @@ function walkPayload(value, path, issues) {
     walkPayload(item, `${path}.${key}`, issues);
   }
 }
-function validateMonitorFleetDefinition(value) {
+function validateMonitorFleetDefinitionV1(value) {
   const issues = [];
-  const input = record(value);
+  const input = record2(value);
   if (!input) {
     return {
       valid: false,
@@ -11289,7 +11723,7 @@ function validateMonitorFleetDefinition(value) {
       message: "Fleet id must be lowercase kebab-case."
     });
   }
-  const source = record(input.source);
+  const source = record2(input.source);
   exactKeys(
     source,
     ["kind", "schema", "table", "key", "where"],
@@ -11310,7 +11744,7 @@ function validateMonitorFleetDefinition(value) {
       message: "Source schema and table must be SQL identifiers."
     });
   }
-  const sourceKey = record(source?.key);
+  const sourceKey = record2(source?.key);
   exactKeys(sourceKey, ["column", "type"], "source.key", issues);
   if (!sourceKey || !identifier(sourceKey.column) || !["text", "uuid", "int4", "int8"].includes(String(sourceKey.type))) {
     issues.push({
@@ -11320,7 +11754,7 @@ function validateMonitorFleetDefinition(value) {
     });
   }
   if (source?.where !== void 0) {
-    const where = record(source.where);
+    const where = record2(source.where);
     if (!where) {
       issues.push({
         path: "source.where",
@@ -11346,9 +11780,9 @@ function validateMonitorFleetDefinition(value) {
       }
     }
   }
-  const member = record(input.member);
+  const member = record2(input.member);
   exactKeys(member, ["tool", "key", "payload"], "member", issues);
-  const key = record(member?.key);
+  const key = record2(member?.key);
   if (!member || typeof member.tool !== "string" || !member.tool.trim()) {
     issues.push({
       path: "member.tool",
@@ -11369,7 +11803,7 @@ function validateMonitorFleetDefinition(value) {
         validateExpression(part, `member.key.parts.${index}`, issues);
     }
     if (sourceKey && !key.parts.some(
-      (part) => record(part)?.$fleet === "column" && record(part)?.name === sourceKey.column
+      (part) => record2(part)?.$fleet === "column" && record2(part)?.name === sourceKey.column
     )) {
       issues.push({
         path: "member.key.parts",
@@ -11388,7 +11822,7 @@ function validateMonitorFleetDefinition(value) {
     jsonValue(member.payload, "member.payload", issues);
   }
   walkPayload(member?.payload, "member.payload", issues);
-  const selection = record(input.selection);
+  const selection = record2(input.selection);
   exactKeys(selection, ["limit", "orderBy", "membership"], "selection", issues);
   if (!selection || !Number.isSafeInteger(selection.limit) || Number(selection.limit) < 1 || Number(selection.limit) > MONITOR_FLEET_MAX_MEMBERS) {
     issues.push({
@@ -11414,7 +11848,7 @@ function validateMonitorFleetDefinition(value) {
   } else {
     const orderColumns = /* @__PURE__ */ new Set();
     for (const [index, order] of orderBy.entries()) {
-      const item = record(order);
+      const item = record2(order);
       exactKeys(
         item,
         ["column", "direction"],
@@ -11437,7 +11871,7 @@ function validateMonitorFleetDefinition(value) {
         orderColumns.add(item.column);
       }
     }
-    if (sourceKey && record(orderBy.at(-1))?.column !== sourceKey.column) {
+    if (sourceKey && record2(orderBy.at(-1))?.column !== sourceKey.column) {
       issues.push({
         path: "selection.orderBy",
         code: "fleet_order_missing_key",
@@ -11456,9 +11890,104 @@ function validateMonitorFleetDefinition(value) {
   }
   return issues.length === 0 ? { valid: true, definition: value, issues } : { valid: false, issues };
 }
-function admitMonitorFleetAuthoringContract(value, edition = MONITOR_FLEET_AUTHORING_CONTRACT_EDITION) {
+function v2Issue(issue) {
+  return { path: issue.path, code: issue.code, message: issue.message };
+}
+function validateMonitorFleetDefinitionV2(value) {
+  const issues = [];
+  const input = record2(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".'
+    });
+  }
+  const source = record2(input.source);
+  const sourceKey = record2(source?.key);
+  const legacyShape = {
+    id: input.id,
+    source: input.source,
+    member: {
+      tool: record2(input.monitor)?.tool,
+      key: {
+        $fleet: "template",
+        parts: [
+          "fleet-",
+          {
+            $fleet: "column",
+            name: typeof sourceKey?.column === "string" ? sourceKey.column : "invalid_source_key"
+          }
+        ]
+      },
+      payload: record2(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 = record2(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,
+      monitor: monitor.normalized,
+      selection: input.selection
+    },
+    issues
+  } : { valid: false, issues };
+}
+function validateMonitorFleetDefinition(value) {
+  const input = record2(value);
+  return input?.version === 2 || input?.kind === "fleet" ? validateMonitorFleetDefinitionV2(value) : validateMonitorFleetDefinitionV1(value);
+}
+function admitMonitorFleetAuthoringContract(value, edition) {
+  const detectedEdition = edition ?? (record2(value)?.version === 2 || record2(value)?.kind === "fleet" ? 2 : 1);
   if (!SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS.includes(
-    edition
+    detectedEdition
   )) {
     return {
       valid: false,
@@ -11466,16 +11995,16 @@ function admitMonitorFleetAuthoringContract(value, edition = MONITOR_FLEET_AUTHO
         {
           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: detectedEdition,
       // JSON cloning prevents later caller mutation from changing the
       // admitted snapshot.
       definition: JSON.parse(
@@ -11485,6 +12014,32 @@ function admitMonitorFleetAuthoringContract(value, edition = MONITOR_FLEET_AUTHO
     issues: []
   } : { valid: false, issues: result.issues };
 }
+function lintMonitorFleetInput(value) {
+  const input = record2(value);
+  const legacy = input?.member !== void 0;
+  const admitted = admitMonitorFleetAuthoringContract(value);
+  const issues = admitted.issues.map((issue) => ({
+    ...issue,
+    severity: "error"
+  }));
+  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 };
+}
 
 // ../plays/bootstrap-routes.ts
 var DEEPLINE_TOOL_CATEGORIES = [
@@ -11816,6 +12371,10 @@ export {
   isPlayBootstrapTemplate,
   isProviderUnavailable,
   isProviderWaterfallUnavailableError,
+  lintMonitorBatchInput,
+  lintMonitorFleetInput,
+  lintMonitorSpecTemplate,
+  renderMonitorSpecTemplate,
   resolveConfig,
   runIf,
   steps,