deepline 0.3.97 → 0.3.98

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

@@ -0,0 +1,455 @@
+import Handlebars from 'handlebars';
+
+export type MonitorInputIssue = {
+  severity: 'error' | 'warning' | 'info';
+  code: string;
+  path: string;
+  message: string;
+  suggestion?: string;
+};
+
+export type MonitorSpec = {
+  key: string;
+  tool: string;
+  name?: string;
+  payload: Record<string, unknown>;
+};
+
+export type BatchMonitorInput = {
+  version: 1;
+  kind: 'batch';
+  monitors: MonitorSpec[];
+};
+
+type UnknownRecord = Record<string, unknown>;
+
+function authoredMonitorFieldPath(path: string, field: string): string {
+  // Batch JSON is an array-shaped document, so use an array path in the two
+  // prescriptive migration errors. Fleet retains its natural `monitor.field`
+  // path while both commands point at the exact authored field.
+  const batch = /^monitors\.(\d+)$/.exec(path);
+  return `${batch ? `monitors[${batch[1]}]` : path}.${field}`;
+}
+
+function record(value: unknown): UnknownRecord | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as UnknownRecord)
+    : null;
+}
+
+function json(value: unknown, path: string, issues: MonitorInputIssue[]): void {
+  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: unknown,
+  path: string,
+  issues: MonitorInputIssue[],
+) {
+  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 = new Set(['key', 'tool', 'name', 'payload']);
+  for (const key of Object.keys(input)) {
+    if (!allowed.has(key)) {
+      if (key === '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 (key === '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}.${key}`,
+        message: `Monitor definitions do not accept '${key}'.`,
+      });
+    }
+  }
+  const key = typeof input.key === 'string' ? input.key.trim() : '';
+  const tool = typeof input.tool === 'string' ? input.tool.trim() : '';
+  const name =
+    input.name === undefined
+      ? undefined
+      : 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,
+  } satisfies MonitorSpec;
+}
+
+function issueOrder(left: MonitorInputIssue, right: MonitorInputIssue) {
+  return (
+    left.path.localeCompare(right.path) ||
+    left.severity.localeCompare(right.severity) ||
+    left.code.localeCompare(right.code)
+  );
+}
+
+export function lintMonitorBatchInput(value: unknown): {
+  normalized?: BatchMonitorInput;
+  issues: MonitorInputIssue[];
+} {
+  const issues: MonitorInputIssue[] = [];
+  // Versionless `{ monitors: [...] }` was the original REST/SDK envelope.
+  // Continue to admit it so installed SDKs remain compatible, but normalize it
+  // before anything is persisted or sent to the provider.
+  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: unknown[] | null = 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 = new Map<string, number>();
+  normalized.forEach((item, index) => {
+    if (!item) return;
+    const first = seen.get(item.key);
+    if (first !== undefined) {
+      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 as MonitorSpec[],
+        },
+        issues: ordered,
+      };
+}
+
+function validateHandlebars(
+  value: string,
+  path: string,
+  issues: MonitorInputIssue[],
+) {
+  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: unknown,
+  path: string,
+  issues: MonitorInputIssue[],
+): void {
+  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);
+  }
+}
+
+export function lintMonitorSpecTemplate(
+  value: unknown,
+  path = 'monitor',
+): { normalized?: MonitorSpec; issues: MonitorInputIssue[] } {
+  const issues: MonitorInputIssue[] = [];
+  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] !== undefined)
+        walkTemplates(input[field], `${path}.${field}`, issues);
+    }
+  }
+  const ordered = issues.sort(issueOrder);
+  return ordered.some((issue) => issue.severity === 'error')
+    ? { issues: ordered }
+    : { normalized: normalized!, issues: ordered };
+}
+
+function renderValue(value: unknown, row: Record<string, unknown>): unknown {
+  if (typeof value === 'string' && value.includes('{{')) {
+    const context = Object.assign(Object.create(null), row);
+    return Handlebars.compile(value, {
+      noEscape: true,
+      strict: true,
+      knownHelpersOnly: true,
+      preventIndent: true,
+    })(context, {
+      allowProtoMethodsByDefault: false,
+      allowProtoPropertiesByDefault: false,
+      helpers: Object.create(null),
+      partials: 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)]),
+  );
+}
+
+export function renderMonitorSpecTemplate(
+  template: MonitorSpec,
+  row: Record<string, unknown>,
+): { spec?: MonitorSpec; issues: MonitorInputIssue[] } {
+  const lint = lintMonitorSpecTemplate(template);
+  if (!lint.normalized) return { issues: lint.issues };
+  try {
+    const rendered = renderValue(lint.normalized, row);
+    const issues: MonitorInputIssue[] = [];
+    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.',
+        },
+      ],
+    };
+  }
+}

package/dist/bundling-sources/shared_libs/monitors/fleets/plan.ts

@@ -47,7 +47,12 @@ export type OwnedFleetMonitor = {
     | 'rate_limited'
     | 'settled'
     | 'blocked'
-    | 'failed';
+    | 'failed'
+    /**
+     * A policy-suspended member remains owned so the Fleet can explicitly
+     * reactivate it, but it has no active convergence work until then.
+     */
+    | null;
   desiredHash: string | null;
   appliedHash: string | null;
   firstMissingAt: number | null;

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

@@ -86,7 +86,8 @@ export type ProviderMonitorBatchOperationState =
   | 'running'
   | 'retry_scheduled'
   | 'completed'
-  | 'failed';
+  | 'failed'
+  | 'cancelled';
 
 const IDEMPOTENCY_KEY = /^[A-Za-z0-9][A-Za-z0-9._-]{0,95}$/;
 

package/dist/bundling-sources/shared_libs/observability/scheduled-jobs.json

@@ -698,5 +698,17 @@
     "owner": "billing",
     "criticality": "critical",
     "failureAlert": "convex_action_wrapper"
+  },
+  {
+    "id": "convex.monitor-deployment-job-tick",
+    "name": "Monitor deployment job tick",
+    "scheduler": "convex_cron",
+    "cadence": "every 60s",
+    "timezone": "UTC",
+    "source": "packages/convex/crons.ts",
+    "locator": "monitor deployment job tick",
+    "owner": "monitors",
+    "criticality": "critical",
+    "failureAlert": "convex_action_wrapper"
   }
 ]

package/dist/bundling-sources/shared_libs/observability/scheduled-work-manual.ts

@@ -15,6 +15,7 @@ export const MANUALLY_RUNNABLE_CONVEX_CRON_JOB_IDS = [
   'convex.cleanup-expired-domain-health-cache',
   'convex.salesforce-oauth-refresh-maintenance',
   'convex.monitor-fleet-convergence-tick',
+  'convex.monitor-deployment-job-tick',
   'convex.provider-monitor-global-audit-daily',
   'convex.recover-notification-delivery-work',
   'convex.cleanup-expired-notification-audit-records',

package/dist/bundling-sources/shared_libs/play-runtime/internal-bootstrap-token.ts

@@ -167,7 +167,9 @@ export type MonitorFleetDispatchTokenClaims = {
   org_id: string;
   purpose: typeof MONITOR_FLEET_DISPATCH_PURPOSE;
   fleet_id?: string;
-  operation: 'dispatch' | 'daily_sync';
+  /** Monitor Job dispatches share this bounded credential wrapper. */
+  job_id?: string;
+  operation: 'dispatch' | 'daily_sync' | 'job_dispatch';
   sub: 'monitor_fleet_dispatcher';
   v: typeof INTERNAL_BOOTSTRAP_TOKEN_VERSION;
 };
@@ -1116,10 +1118,17 @@ export async function verifyProductNotificationUnsubscribeToken(
 
 export async function mintMonitorFleetDispatchToken(input: {
   orgId: string;
-  operation: 'dispatch' | 'daily_sync';
+  operation: 'dispatch' | 'daily_sync' | 'job_dispatch';
   fleetId?: string;
+  jobId?: string;
   nowMs?: number;
 }): Promise<string> {
+  if (input.operation === 'job_dispatch' && !input.jobId?.trim()) {
+    throw new Error('Monitor Job dispatch tokens require a job id.');
+  }
+  if (input.operation !== 'job_dispatch' && input.jobId !== undefined) {
+    throw new Error('Only Monitor Job dispatch tokens may carry a job id.');
+  }
   const issuedAt = Math.floor((input.nowMs ?? Date.now()) / 1000);
   const claims: MonitorFleetDispatchTokenClaims = {
     v: INTERNAL_BOOTSTRAP_TOKEN_VERSION,
@@ -1129,6 +1138,7 @@ export async function mintMonitorFleetDispatchToken(input: {
     org_id: input.orgId,
     operation: input.operation,
     ...(input.fleetId ? { fleet_id: input.fleetId } : {}),
+    ...(input.jobId ? { job_id: input.jobId } : {}),
     sub: 'monitor_fleet_dispatcher',
     iat: issuedAt,
     exp: issuedAt + INTERNAL_BOOTSTRAP_TOKEN_TTL_SECONDS,
@@ -1168,8 +1178,14 @@ export async function verifyMonitorFleetDispatchToken(
     claims.sub !== 'monitor_fleet_dispatcher' ||
     typeof claims.org_id !== 'string' ||
     !claims.org_id ||
-    !['dispatch', 'daily_sync'].includes(String(claims.operation)) ||
+    !['dispatch', 'daily_sync', 'job_dispatch'].includes(
+      String(claims.operation),
+    ) ||
     (claims.fleet_id !== undefined && typeof claims.fleet_id !== 'string') ||
+    (claims.job_id !== undefined && typeof claims.job_id !== 'string') ||
+    (claims.operation === 'job_dispatch' &&
+      (typeof claims.job_id !== 'string' || !claims.job_id)) ||
+    (claims.operation !== 'job_dispatch' && claims.job_id !== undefined) ||
     typeof claims.iat !== 'number' ||
     !Number.isFinite(claims.iat) ||
     typeof claims.exp !== 'number' ||

package/dist/bundling-sources/shared_libs/plays/bundling/index.ts

@@ -1827,7 +1827,11 @@ function importedPlayProxyPlugin(
     name: 'deepline-imported-play-proxy',
     setup(buildContext) {
       buildContext.onResolve({ filter: /.*/ }, async (args) => {
-        if (!args.importer || !isLocalSpecifier(args.path)) {
+        if (
+          !args.importer ||
+          !isLocalSpecifier(args.path) ||
+          args.importer.split(/[\\/]+/).includes('node_modules')
+        ) {
           return null;
         }