deepline 0.3.55 → 0.3.57

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

@@ -0,0 +1,556 @@
+/**
+ * The fleet member ceiling, mirrored — deliberately a literal.
+ *
+ * The canonical declaration is shared_libs/monitors/monitor-fleet-limits.ts,
+ * which the Convex commit mutation reads to size its transaction. This package
+ * cannot import it: the workspace-architecture ratchet forbids NEW shared_libs
+ * imports from packages absolutely (only relocations of pre-existing edges
+ * pass CI), because shared_libs is being migrated into workspace packages.
+ * Until a monitors package exists, the two copies are held equal by
+ * tests/lib/monitors/monitor-fleet-limits-mirror.test.ts — change one without
+ * the other and that test names both files.
+ */
+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, pause, resume, 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/sdk/src/monitor-fleets.ts

@@ -0,0 +1,31 @@
+/**
+ * Canonical Monitor Fleet authoring helpers and AST types.
+ *
+ * Fleet definitions are stored and executed as tagged JSON. The contract lives
+ * in this package and the server imports it from here, so an SDK-authored
+ * definition and the server's `$fleet` representation cannot drift: there is
+ * one definition of the grammar, not a copy on each side.
+ */
+export {
+  admitMonitorFleetAuthoringContract,
+  MONITOR_FLEET_AUTHORING_CONTRACT_CHANGELOG,
+  MONITOR_FLEET_AUTHORING_CONTRACT_EDITION,
+  MONITOR_FLEET_FRONTIER_MAX_ROWS,
+  MONITOR_FLEET_DOCUMENTATION,
+  MONITOR_FLEET_MAX_MEMBERS,
+  defineMonitorFleet,
+  fleetColumn,
+  fleetKey,
+  validateMonitorFleetDefinition,
+} from './monitor-fleet-contract.js';
+
+export type {
+  AdmittedMonitorFleetAuthoringContract,
+  MonitorFleetAuthoringContractEdition,
+  MonitorFleetAuthoringContractResult,
+  MonitorFleetColumn,
+  MonitorFleetContractIssue,
+  MonitorFleetDefinition,
+  MonitorFleetExpression,
+  MonitorFleetTemplate,
+} from './monitor-fleet-contract.js';

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

@@ -998,8 +998,7 @@ function createNamedPlayHandle<
 /**
  * High-level SDK context with tool shortcuts and play handles.
  *
- * Created by {@link Deepline.connect}. Wraps a {@link DeeplineClient} with
- * a friendlier API for common operations.
+ * Created by {@link Deepline.connect}. Wraps a {@link DeeplineClient} with a friendlier API for common operations.
  *
  * @example
  * ```typescript
@@ -1532,12 +1531,7 @@ export function defineInput<TInput>(
 /**
  * Define a play — a composable TypeScript workflow for the Deepline platform.
  *
- * The returned value is both:
- * 1. **A callable function** — invoked by the Temporal worker with a runtime context
- * 2. **A named play handle** — with `.run()`, `.versions()`, `.get()`, `.publish()`, etc. for remote lifecycle management
- *
- * Plays are the primary abstraction for building repeatable data pipelines.
- * They run on Temporal for durable execution with automatic retries and timeouts.
+ * The returned value is both a callable function, invoked by the Deepline runtime with a runtime context, and a named play handle carrying `.run()`, `.versions()`, `.get()` and `.publish()` for remote lifecycle management. Plays are the primary abstraction for repeatable data pipelines and execute durably, with automatic retries and timeouts.
  *
  * @typeParam TInput - The input type accepted by the play
  * @typeParam TOutput - The return type of the play

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

@@ -199,7 +199,7 @@ export const SDK_RELEASE = {
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
-  version: '0.3.55',
+  version: '0.3.57',
   updateSummary:
     'Automatic CLI updates are now enabled by default. To opt out, run `deepline settings autoupdate off`; use `deepline settings autoupdate on` to re-enable updates or `deepline settings autoupdate pin <version>` to hold an exact release. This release also adds raw-v2 tool responses at toolResponse.rawV2 while preserving existing toolResponse.raw and declared getters.',
   packageCapabilities: {

package/dist/bundling-sources/shared_libs/monitors/monitor-fleet-limits.ts

@@ -0,0 +1,14 @@
+/**
+ * How large one Monitor Fleet may be.
+ *
+ * This lives in `shared_libs` rather than in the SDK's fleet authoring contract
+ * because Convex needs it too: the commit mutation sizes its own transaction
+ * against the same number the authoring contract validates a fleet's selection
+ * limit against. Two copies of that number would drift, and the drift would
+ * only be visible as a mutation that refuses a plan the SDK admitted.
+ *
+ * `packages/sdk/src/monitor-fleet-contract.ts` re-exports it, so customer-facing
+ * code keeps importing it from the contract module and never learns this file
+ * exists.
+ */
+export const MONITOR_FLEET_MAX_MEMBERS = 1_000;