deepline 0.3.90 → 0.3.92

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

@@ -0,0 +1,549 @@
+/**
+ * The canonical Fleet authoring contract, shared by the SDK and server.
+ * Monitor transaction admission reuses this ceiling; it must never drift
+ * from the limit admitted when a customer authors a Fleet.
+ */
+export const MONITOR_FLEET_MAX_MEMBERS = 1_000;
+
+export const MONITOR_FLEET_FRONTIER_MAX_ROWS = 10_000;
+/**
+ * Fleet definitions are admitted once and executed many times.  Keep the
+ * edition beside the definition just as Plays keep their authoring-contract
+ * 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 SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS = [
+  MONITOR_FLEET_AUTHORING_CONTRACT_EDITION,
+] as const;
+
+export type MonitorFleetAuthoringContractEdition =
+  (typeof SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS)[number];
+
+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.',
+    compatibilityOwner: 'Monitors Runtime',
+    newWritesEnd: null,
+    readerRemoval: null,
+  },
+] as const;
+/**
+ * Fleets are deliberately opinionated in beta: a member absent from the
+ * source remains intact for seven days, then its ordinary monitor is
+ * deactivated. This prevents transient source refreshes from deleting a
+ * provider resource while keeping the customer contract small.
+ */
+export const MONITOR_FLEET_REMOVAL_GRACE_MS = 7 * 24 * 60 * 60_000;
+
+/**
+ * Public, machine-readable guidance for every Monitor Fleet authoring
+ * surface. SDK clients may render this directly; the CLI uses the same fixed
+ * policy values in its help rather than maintaining another contract.
+ */
+export const MONITOR_FLEET_DOCUMENTATION = {
+  summary:
+    'A Monitor Fleet keeps one bounded, sticky set of ordinary monitors aligned with Customer DB rows.',
+  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.',
+    selection:
+      'Deterministic ranking and an active-member limit between 1 and 1,000.',
+  },
+  fixedPolicy: {
+    cadence: 'daily',
+    membership: 'sticky',
+    removalGrace: '7d',
+    onRemoved: 'deactivate',
+    ownership:
+      'A Fleet may adopt a same-tool ordinary monitor with its deterministic member key. The first Fleet claim wins; another Fleet or a different tool receives a conflict.',
+    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.',
+} as const;
+
+export type MonitorFleetColumn = {
+  $fleet: 'column';
+  name: string;
+};
+
+export type MonitorFleetTemplate = {
+  $fleet: 'template';
+  parts: Array<string | MonitorFleetColumn>;
+};
+
+export type MonitorFleetExpression = MonitorFleetColumn | MonitorFleetTemplate;
+
+export type MonitorFleetDefinition = {
+  /** Stable lowercase fleet id, used by CLI and API lifecycle commands. */
+  id: string;
+  /** Customer DB rows that may become members. */
+  source: {
+    kind: 'customer_db_table';
+    schema: string;
+    table: string;
+    key: { column: string; type: 'text' | 'uuid' | 'int4' | 'int8' };
+    where?: Record<string, string | number | boolean | null>;
+  };
+  /** One ordinary monitor definition, evaluated once for each selected row. */
+  member: {
+    tool: string;
+    key: MonitorFleetTemplate;
+    payload: Record<string, unknown>;
+  };
+  /**
+   * Bounded deterministic candidate selection. Membership is intentionally
+   * sticky: ranking chooses vacant slots but does not replace existing members
+   * merely because another row's score changed.
+   */
+  selection: {
+    limit: number;
+    orderBy: Array<{
+      column: string;
+      direction: 'asc' | 'desc';
+    }>;
+    membership: 'sticky';
+  };
+};
+
+export type MonitorFleetContractIssue = {
+  path: string;
+  code: string;
+  message: string;
+};
+
+/** The durable, validated snapshot that a Fleet sync is allowed to execute. */
+export type AdmittedMonitorFleetAuthoringContract = {
+  edition: MonitorFleetAuthoringContractEdition;
+  definition: MonitorFleetDefinition;
+};
+
+export type MonitorFleetAuthoringContractResult = {
+  valid: boolean;
+  contract?: AdmittedMonitorFleetAuthoringContract;
+  issues: MonitorFleetContractIssue[];
+};
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function identifier(value: unknown): value is string {
+  return typeof value === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+
+function exactKeys(
+  input: Record<string, unknown> | null,
+  keys: readonly string[],
+  path: string,
+  issues: MonitorFleetContractIssue[],
+): void {
+  if (!input) return;
+  for (const key of Object.keys(input)) {
+    if (keys.includes(key)) continue;
+    issues.push({
+      path: path ? `${path}.${key}` : key,
+      code: 'unknown_fleet_field',
+      message: `${path || 'Fleet'} does not accept '${key}'.`,
+    });
+  }
+}
+
+function jsonValue(
+  value: unknown,
+  path: string,
+  issues: MonitorFleetContractIssue[],
+): void {
+  if (
+    value === null ||
+    typeof value === 'string' ||
+    typeof value === 'boolean' ||
+    (typeof value === 'number' && Number.isFinite(value))
+  ) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => jsonValue(item, `${path}.${index}`, issues));
+    return;
+  }
+  const input = record(value);
+  if (!input) {
+    issues.push({
+      path,
+      code: 'invalid_fleet_json_value',
+      message: 'Fleet payload values must be JSON values.',
+    });
+    return;
+  }
+  for (const [key, item] of Object.entries(input)) {
+    jsonValue(item, `${path}.${key}`, issues);
+  }
+}
+
+export function fleetColumn(name: string): MonitorFleetColumn {
+  if (!identifier(name)) throw new Error(`Invalid fleet column '${name}'.`);
+  return { $fleet: 'column', name };
+}
+
+export function fleetKey(
+  ...parts: Array<string | MonitorFleetColumn>
+): MonitorFleetTemplate {
+  if (parts.length === 0)
+    throw new Error('A fleet key needs at least one part.');
+  return { $fleet: 'template', parts };
+}
+
+export function defineMonitorFleet<const T extends MonitorFleetDefinition>(
+  definition: T,
+): T {
+  return definition;
+}
+
+function validateExpression(
+  value: unknown,
+  path: string,
+  issues: MonitorFleetContractIssue[],
+): void {
+  const input = record(value);
+  if (!input || input.$fleet !== 'column' || !identifier(input.name)) {
+    issues.push({
+      path,
+      code: 'invalid_fleet_expression',
+      message: 'Fleet expressions must be an exact tagged column reference.',
+    });
+    return;
+  }
+  exactKeys(input, ['$fleet', 'name'], path, issues);
+}
+
+function walkPayload(
+  value: unknown,
+  path: string,
+  issues: MonitorFleetContractIssue[],
+): void {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) =>
+      walkPayload(item, `${path}.${index}`, issues),
+    );
+    return;
+  }
+  const input = record(value);
+  if (!input) return;
+  if ('$fleet' in input) {
+    validateExpression(input, path, issues);
+    return;
+  }
+  for (const [key, item] of Object.entries(input)) {
+    walkPayload(item, `${path}.${key}`, issues);
+  }
+}
+
+export function validateMonitorFleetDefinition(value: unknown): {
+  valid: boolean;
+  definition?: MonitorFleetDefinition;
+  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, ['id', 'source', 'member', 'selection'], '', issues);
+  if (
+    typeof input.id !== 'string' ||
+    !/^[a-z][a-z0-9-]{0,199}$/.test(input.id)
+  ) {
+    issues.push({
+      path: 'id',
+      code: 'invalid_fleet_id',
+      message: 'Fleet id must be lowercase kebab-case.',
+    });
+  }
+  const source = record(input.source);
+  exactKeys(
+    source,
+    ['kind', 'schema', 'table', 'key', 'where'],
+    'source',
+    issues,
+  );
+  if (!source || source.kind !== 'customer_db_table') {
+    issues.push({
+      path: 'source.kind',
+      code: 'invalid_fleet_source',
+      message: 'Beta fleets require customer_db_table.',
+    });
+  }
+  if (!identifier(source?.schema) || !identifier(source?.table)) {
+    issues.push({
+      path: 'source',
+      code: 'invalid_fleet_table',
+      message: 'Source schema and table must be SQL identifiers.',
+    });
+  }
+  const sourceKey = record(source?.key);
+  exactKeys(sourceKey, ['column', 'type'], 'source.key', issues);
+  if (
+    !sourceKey ||
+    !identifier(sourceKey.column) ||
+    !['text', 'uuid', 'int4', 'int8'].includes(String(sourceKey.type))
+  ) {
+    issues.push({
+      path: 'source.key',
+      code: 'invalid_fleet_source_key',
+      message: 'Source key must name a supported typed column.',
+    });
+  }
+  if (source?.where !== undefined) {
+    const where = record(source.where);
+    if (!where) {
+      issues.push({
+        path: 'source.where',
+        code: 'invalid_fleet_where',
+        message: 'source.where must be an object of equality values.',
+      });
+    } else {
+      for (const [column, expected] of Object.entries(where)) {
+        if (!identifier(column)) {
+          issues.push({
+            path: `source.where.${column}`,
+            code: 'invalid_fleet_where_column',
+            message: 'source.where keys must be SQL identifiers.',
+          });
+        }
+        if (
+          expected !== null &&
+          typeof expected !== 'string' &&
+          typeof expected !== 'boolean' &&
+          !(typeof expected === 'number' && Number.isFinite(expected))
+        ) {
+          issues.push({
+            path: `source.where.${column}`,
+            code: 'invalid_fleet_where_value',
+            message: 'source.where values must be finite JSON scalars or null.',
+          });
+        }
+      }
+    }
+  }
+  const member = record(input.member);
+  exactKeys(member, ['tool', 'key', 'payload'], 'member', issues);
+  const key = record(member?.key);
+  if (!member || typeof member.tool !== 'string' || !member.tool.trim()) {
+    issues.push({
+      path: 'member.tool',
+      code: 'invalid_fleet_tool',
+      message: 'Member tool is required.',
+    });
+  }
+  if (
+    !key ||
+    key.$fleet !== 'template' ||
+    !Array.isArray(key.parts) ||
+    key.parts.length === 0
+  ) {
+    issues.push({
+      path: 'member.key',
+      code: 'invalid_fleet_key',
+      message: 'Member key must be a tagged fleet template.',
+    });
+  } else {
+    exactKeys(key, ['$fleet', 'parts'], 'member.key', issues);
+    for (const [index, part] of key.parts.entries()) {
+      if (typeof part !== 'string')
+        validateExpression(part, `member.key.parts.${index}`, issues);
+    }
+    if (
+      sourceKey &&
+      !key.parts.some(
+        (part) =>
+          record(part)?.$fleet === 'column' &&
+          record(part)?.name === sourceKey.column,
+      )
+    ) {
+      issues.push({
+        path: 'member.key.parts',
+        code: 'fleet_key_missing_source_key',
+        message: 'Member key must include the source key column.',
+      });
+    }
+  }
+  if (!member || !('payload' in member)) {
+    issues.push({
+      path: 'member.payload',
+      code: 'invalid_fleet_payload',
+      message: 'Member payload is required.',
+    });
+  } else {
+    jsonValue(member.payload, 'member.payload', issues);
+  }
+  walkPayload(member?.payload, 'member.payload', issues);
+  const selection = record(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({
+      path: 'selection.limit',
+      code: 'MONITOR_FLEET_LIMIT_EXCEEDED',
+      message: 'selection.limit must be between 1 and 1,000.',
+    });
+  }
+  if (selection?.membership !== 'sticky') {
+    issues.push({
+      path: 'selection.membership',
+      code: 'invalid_fleet_membership',
+      message: `Fleet membership is fixed to ${MONITOR_FLEET_DOCUMENTATION.fixedPolicy.membership}. ${MONITOR_FLEET_DOCUMENTATION.stickyMembership}`,
+    });
+  }
+  const orderBy = selection?.orderBy;
+  if (!Array.isArray(orderBy) || orderBy.length === 0) {
+    issues.push({
+      path: 'selection.orderBy',
+      code: 'invalid_fleet_order',
+      message: 'At least one deterministic order field is required.',
+    });
+  } else {
+    const orderColumns = new Set<string>();
+    for (const [index, order] of orderBy.entries()) {
+      const item = record(order);
+      exactKeys(
+        item,
+        ['column', 'direction'],
+        `selection.orderBy.${index}`,
+        issues,
+      );
+      if (
+        !item ||
+        !identifier(item.column) ||
+        !['asc', 'desc'].includes(String(item.direction))
+      ) {
+        issues.push({
+          path: `selection.orderBy.${index}`,
+          code: 'invalid_fleet_order',
+          message: 'Order fields need a column and asc/desc direction.',
+        });
+      } else if (orderColumns.has(item.column as string)) {
+        issues.push({
+          path: `selection.orderBy.${index}.column`,
+          code: 'duplicate_fleet_order_column',
+          message: 'Each selection order column may appear only once.',
+        });
+      } else {
+        orderColumns.add(item.column as string);
+      }
+    }
+    if (sourceKey && record(orderBy.at(-1))?.column !== sourceKey.column) {
+      issues.push({
+        path: 'selection.orderBy',
+        code: 'fleet_order_missing_key',
+        message: 'The final order field must be the source key.',
+      });
+    }
+  }
+  for (const removedOption of ['spendLimits', 'lifecycle', 'reconciliation']) {
+    if (removedOption in input) {
+      issues.push({
+        path: removedOption,
+        code: 'unsupported_fleet_option',
+        message:
+          `${removedOption} is fixed by Monitor Fleets and must be omitted. ` +
+          `Fleets sync ${MONITOR_FLEET_DOCUMENTATION.fixedPolicy.cadence} and ${MONITOR_FLEET_DOCUMENTATION.fixedPolicy.onRemoved} members after ${MONITOR_FLEET_DOCUMENTATION.fixedPolicy.removalGrace} absent from the source.`,
+      });
+    }
+  }
+  return issues.length === 0
+    ? { valid: true, definition: value as MonitorFleetDefinition, issues }
+    : { valid: false, issues };
+}
+
+/**
+ * Compile JSON into the exact authoring snapshot persisted by a Fleet.  This
+ * does not inspect the Customer DB or provider; use
+ * `fleets sync --file <fleet.json> --dry-run` for that environment-aware
+ * preflight, which returns the real plan and the credits due.
+ */
+export function admitMonitorFleetAuthoringContract(
+  value: unknown,
+  edition: number = MONITOR_FLEET_AUTHORING_CONTRACT_EDITION,
+): MonitorFleetAuthoringContractResult {
+  if (
+    !SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS.includes(
+      edition as MonitorFleetAuthoringContractEdition,
+    )
+  ) {
+    return {
+      valid: false,
+      issues: [
+        {
+          path: 'authoring_contract_edition',
+          code: 'unsupported_fleet_authoring_contract_edition',
+          message: `Monitor Fleet authoring contract edition ${edition} is not supported.`,
+        },
+      ],
+    };
+  }
+  const result = validateMonitorFleetDefinition(value);
+  return result.valid && result.definition
+    ? {
+        valid: true,
+        contract: {
+          edition: edition as MonitorFleetAuthoringContractEdition,
+          // JSON cloning prevents later caller mutation from changing the
+          // admitted snapshot.
+          definition: JSON.parse(
+            JSON.stringify(result.definition),
+          ) as MonitorFleetDefinition,
+        },
+        issues: [],
+      }
+    : { valid: false, issues: result.issues };
+}
+
+export function evaluateMonitorFleetValue(
+  value: unknown,
+  row: Record<string, unknown>,
+): unknown {
+  if (Array.isArray(value))
+    return value.map((item) => evaluateMonitorFleetValue(item, row));
+  const input = record(value);
+  if (!input) return value;
+  if (input.$fleet === 'column') return row[String(input.name)];
+  if (input.$fleet === 'template' && Array.isArray(input.parts)) {
+    return input.parts
+      .map((part) =>
+        typeof part === 'string'
+          ? part
+          : String(evaluateMonitorFleetValue(part, row) ?? ''),
+      )
+      .join('');
+  }
+  return Object.fromEntries(
+    Object.entries(input).map(([key, item]) => [
+      key,
+      evaluateMonitorFleetValue(item, row),
+    ]),
+  );
+}

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

@@ -0,0 +1,96 @@
+/**
+ * The fleet error contract.
+ *
+ * Every failure a customer or an agent can see is one of these codes, carries
+ * a message that names what refused it, and carries `next` - a command that
+ * can be run as-is. An error without a runnable next step makes an agent
+ * guess, and guessing at a control-plane mutation is how duplicates happen.
+ */
+export const MONITOR_FLEET_ERROR_CODE = {
+  invalidDefinition: 'MONITOR_FLEET_INVALID_DEFINITION',
+  notFound: 'MONITOR_FLEET_NOT_FOUND',
+  conflict: 'MONITOR_FLEET_CONFLICT',
+  deactivated: 'MONITOR_FLEET_DEACTIVATED',
+  failed: 'MONITOR_FLEET_FAILED',
+} as const;
+
+/** Every fleet command is idempotent, so a retry is always the safe answer. */
+export const MONITOR_FLEET_RETRY_NOTE =
+  'Safe to retry — every fleet command is idempotent.';
+
+export function fleetGetCommand(fleetId: string): string {
+  return `deepline monitors fleets get ${fleetId} --json`;
+}
+
+export function fleetDriftCommand(fleetId: string): string {
+  return `deepline monitors fleets get ${fleetId} --drift --json`;
+}
+
+/** There is no `fleets list` verb: `get` with no id is the list. */
+export function fleetListCommand(): string {
+  return 'deepline monitors fleets get --json';
+}
+
+/** Re-plans the stored definition. `--file` would apply a new one instead. */
+export function fleetSyncCommand(fleetId: string): string {
+  return `deepline monitors fleets sync ${fleetId} --json`;
+}
+
+export class MonitorFleetError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+    readonly status: number,
+    /** A command the caller can run right now. Never optional in practice. */
+    readonly next: string,
+    readonly details: Record<string, unknown> = {},
+  ) {
+    super(message);
+    this.name = 'MonitorFleetError';
+  }
+}
+
+export function invalidFleetDefinition(
+  message: string,
+  details: Record<string, unknown> = {},
+): MonitorFleetError {
+  return new MonitorFleetError(
+    MONITOR_FLEET_ERROR_CODE.invalidDefinition,
+    message,
+    400,
+    'Fix the fleet file, then run `deepline monitors fleets sync --file <fleet-file> --dry-run --json`.',
+    details,
+  );
+}
+
+export function fleetNotFound(fleetId: string): MonitorFleetError {
+  return new MonitorFleetError(
+    MONITOR_FLEET_ERROR_CODE.notFound,
+    `Monitor Fleet '${fleetId}' was not found.`,
+    404,
+    fleetListCommand(),
+  );
+}
+
+export function fleetConflict(
+  message: string,
+  fleetId: string,
+  details: Record<string, unknown> = {},
+): MonitorFleetError {
+  return new MonitorFleetError(
+    MONITOR_FLEET_ERROR_CODE.conflict,
+    message,
+    409,
+    fleetGetCommand(fleetId),
+    details,
+  );
+}
+
+export function fleetDeactivated(fleetId: string): MonitorFleetError {
+  return new MonitorFleetError(
+    MONITOR_FLEET_ERROR_CODE.deactivated,
+    `Monitor Fleet '${fleetId}' is deactivated and admits no new plan.`,
+    409,
+    fleetGetCommand(fleetId),
+  );
+}

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

@@ -0,0 +1,8 @@
+/** One wire vocabulary and transaction-size contract for Fleet writers. */
+export const FLEET_BLOCKED_BY = {
+  watchedEntities: 'monitor.watched_entities',
+  monitorsPerEntity: 'monitor.monitors_per_entity',
+  rolloutAccess: 'monitor.rollout_access',
+} as const;
+export const MAX_MEMBER_DEFINITION_BYTES = 2_048;
+export const MAX_FLEET_SETTLE_ITEMS = 100;