deepline 0.3.55 → 0.3.56

package/dist/index.d.mts

@@ -1900,6 +1900,134 @@ type MonitorControls = {
  */
 declare function defineMonitor<TPayload extends MonitorPayload = MonitorPayload>(definition: MonitorDefinition<TPayload>): MonitorDefinition<TPayload>;
 
+/**
+ * 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.
+ */
+declare const MONITOR_FLEET_MAX_MEMBERS = 1000;
+declare const MONITOR_FLEET_FRONTIER_MAX_ROWS = 10000;
+/**
+ * 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.
+ */
+declare const MONITOR_FLEET_AUTHORING_CONTRACT_EDITION: 1;
+declare const SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS: readonly [1];
+type MonitorFleetAuthoringContractEdition = (typeof SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS)[number];
+declare const MONITOR_FLEET_AUTHORING_CONTRACT_CHANGELOG: readonly [{
+    readonly edition: 1;
+    readonly changed: "Initial Fleet JSON contract: bounded sticky table membership, one daily sync, and a seven-day removal grace.";
+    readonly compatibilityOwner: "Monitors Runtime";
+    readonly newWritesEnd: null;
+    readonly readerRemoval: null;
+}];
+/**
+ * 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.
+ */
+declare const MONITOR_FLEET_DOCUMENTATION: {
+    readonly summary: "A Monitor Fleet keeps one bounded, sticky set of ordinary monitors aligned with Customer DB rows.";
+    readonly authoredFields: {
+        readonly id: "Stable lowercase fleet id used by sync, pause, resume, and deactivate.";
+        readonly source: "Customer DB table, unique row key, and optional equality filters that select candidate rows.";
+        readonly member: "Ordinary monitor tool, stable key template, and payload evaluated for each selected source row.";
+        readonly selection: "Deterministic ranking and an active-member limit between 1 and 1,000.";
+    };
+    readonly fixedPolicy: {
+        readonly cadence: "daily";
+        readonly membership: "sticky";
+        readonly removalGrace: "7d";
+        readonly onRemoved: "deactivate";
+        readonly 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.";
+        readonly billing: "No Fleet fee, permit, or renewal. Dry-run reports ordinary monitor lifecycle charges due now.";
+    };
+    readonly stickyMembership: "Ranking fills vacancies but never replaces a current member merely because another row ranks higher.";
+    readonly columnExpression: "Use { \"$fleet\": \"column\", \"name\": \"column_name\" } in a member key or payload to read a value from each source row.";
+};
+type MonitorFleetColumn = {
+    $fleet: 'column';
+    name: string;
+};
+type MonitorFleetTemplate = {
+    $fleet: 'template';
+    parts: Array<string | MonitorFleetColumn>;
+};
+type MonitorFleetExpression = MonitorFleetColumn | MonitorFleetTemplate;
+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';
+    };
+};
+type MonitorFleetContractIssue = {
+    path: string;
+    code: string;
+    message: string;
+};
+/** The durable, validated snapshot that a Fleet sync is allowed to execute. */
+type AdmittedMonitorFleetAuthoringContract = {
+    edition: MonitorFleetAuthoringContractEdition;
+    definition: MonitorFleetDefinition;
+};
+type MonitorFleetAuthoringContractResult = {
+    valid: boolean;
+    contract?: AdmittedMonitorFleetAuthoringContract;
+    issues: MonitorFleetContractIssue[];
+};
+declare function fleetColumn(name: string): MonitorFleetColumn;
+declare function fleetKey(...parts: Array<string | MonitorFleetColumn>): MonitorFleetTemplate;
+declare function defineMonitorFleet<const T extends MonitorFleetDefinition>(definition: T): T;
+declare function validateMonitorFleetDefinition(value: unknown): {
+    valid: boolean;
+    definition?: MonitorFleetDefinition;
+    issues: MonitorFleetContractIssue[];
+};
+/**
+ * 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.
+ */
+declare function admitMonitorFleetAuthoringContract(value: unknown, edition?: number): MonitorFleetAuthoringContractResult;
+
 interface PlayStagedFileRef {
     storageKind: 'r2';
     storageKey: string;
@@ -2396,6 +2524,66 @@ type MonitorDeleteResult = Record<string, unknown>;
 type MonitorReactivateResult = Record<string, unknown>;
 type MonitorTestResult = Record<string, unknown>;
 type MonitorValidateResult = Record<string, unknown>;
+/**
+ * Server-owned fleet response envelope.
+ *
+ * The server computes `status` (`converging` | `converged` | `degraded` |
+ * `deactivating` | `deactivated`) and the SDK never recomputes it: a client
+ * that derives its own verdict from counts drifts from the control plane the
+ * moment the server changes what "converged" means.
+ */
+type MonitorFleetResult = Record<string, unknown>;
+/** Server-computed fleet verdict. Never derived client-side. */
+type MonitorFleetStatus = 'converging' | 'converged' | 'degraded' | 'deactivating' | 'deactivated';
+type MonitorFleetSyncOptions = {
+    /** Return the plan without changing fleet state (`dry_run: true`). */
+    dryRun?: boolean;
+    /** Optimistic concurrency: refuse the write unless the fleet is at this generation. */
+    expectedGeneration?: number;
+    /** Stable retry key; generated by the caller when omitted. */
+    idempotencyKey?: string;
+};
+type MonitorFleetGetOptions = {
+    /** Include bounded per-member drift rows. */
+    drift?: boolean;
+    /** Maximum drift rows to return. */
+    limit?: number;
+};
+type MonitorFleetDeactivateOptions = {
+    /** Return the blast radius without deactivating anything. */
+    dryRun?: boolean;
+    idempotencyKey?: string;
+};
+type MonitorFleetWaitOptions = {
+    /** Give up after this long. Default 10 minutes. */
+    timeoutMs?: number;
+    /** Poll cadence. Default 2 seconds. */
+    pollIntervalMs?: number;
+    /** Called with every polled snapshot, including the terminal one. */
+    onProgress?: (payload: MonitorFleetResult) => void;
+    /**
+     * Which terminal state ends the wait. `converged` (default) also stops on
+     * `degraded` and `deactivated`; `deactivated` stops on `deactivated` and
+     * `degraded`. A timeout is not an error: the last snapshot is returned and
+     * the caller reads `status` to decide the verdict.
+     */
+    until?: 'converged' | 'deactivated';
+};
+type MonitorFleetsNamespace = {
+    /**
+     * Create, update, or re-plan a fleet. Pass a definition to admit new source
+     * of truth; pass a fleet id to re-plan from the stored definition.
+     */
+    sync: (definitionOrId: string | MonitorFleetDefinition, options?: MonitorFleetSyncOptions) => Promise<MonitorFleetResult>;
+    /** One fleet by id, or every fleet in the workspace when the id is omitted. */
+    get: (fleetId?: string, options?: MonitorFleetGetOptions) => Promise<MonitorFleetResult>;
+    /** Every fleet in the workspace. */
+    list: () => Promise<MonitorFleetResult>;
+    /** Deactivate a fleet and the monitors it owns. */
+    deactivate: (fleetId: string, options?: MonitorFleetDeactivateOptions) => Promise<MonitorFleetResult>;
+    /** Poll the fleet until the server reports a terminal status (or the timeout elapses). */
+    waitForConvergence: (fleetId: string, options?: MonitorFleetWaitOptions) => Promise<MonitorFleetResult>;
+};
 /**
  * Public monitors namespace exposed as `client.monitors`.
  *
@@ -2449,6 +2637,8 @@ type MonitorsNamespace = {
     reactivate: (key: string, options?: {
         dryRun?: boolean;
     }) => Promise<MonitorReactivateResult>;
+    /** Define, reconcile, and control table-backed monitor fleets. */
+    fleets: MonitorFleetsNamespace;
 };
 /** One credit grant pool reported by the billing subscription status endpoint. */
 type BillingCreditPool = {
@@ -3820,6 +4010,33 @@ declare class DeeplineClient {
     reactivateMonitor(key: string, options?: {
         dryRun?: boolean;
     }): Promise<MonitorReactivateResult>;
+    private monitorFleetIdempotencyKey;
+    private monitorFleetHeaders;
+    private monitorFleetPath;
+    /**
+     * Create, update, or re-plan one fleet.
+     *
+     * The fleet id is always the resource path, so the same definition PUT twice
+     * is the same operation and the server can answer `replayed: true` instead of
+     * building a second set of monitors. Re-planning an existing fleet from its
+     * stored definition sends an EMPTY body: there is no second definition to
+     * send, and an empty body cannot be mistaken for "replace the definition with
+     * nothing".
+     */
+    syncMonitorFleet(definitionOrId: string | MonitorFleetDefinition, options?: MonitorFleetSyncOptions): Promise<MonitorFleetResult>;
+    listMonitorFleets(): Promise<MonitorFleetResult>;
+    getMonitorFleet(fleetId: string, options?: MonitorFleetGetOptions): Promise<MonitorFleetResult>;
+    deactivateMonitorFleet(fleetId: string, options?: MonitorFleetDeactivateOptions): Promise<MonitorFleetResult>;
+    /**
+     * Poll one fleet until the server reports a terminal status.
+     *
+     * Convergence is the server's verdict, read from `status`. The timeout is not
+     * a failure and does not throw: a fleet still `converging` after ten minutes
+     * is healthy and slow, not broken, so the caller gets the last snapshot and
+     * decides what that means. Throwing here would have made "still working" look
+     * identical to "the request failed".
+     */
+    waitForMonitorFleetConvergence(fleetId: string, options?: MonitorFleetWaitOptions): Promise<MonitorFleetResult>;
     /**
      * Check API connectivity and server health.
      *
@@ -4286,8 +4503,7 @@ type PlayMetadata = {
 /**
  * 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
@@ -4414,12 +4630,7 @@ declare function defineInput<TInput>(schema: Record<string, unknown>): PlayInput
 /**
  * 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
@@ -4824,4 +5035,4 @@ declare function writeCsvOutputFile(rows: Array<Record<string, unknown>>, stem:
  */
 declare function extractSummaryFields(payload: unknown): Record<string, Scalar>;
 
-export { AuthError, type BillingCreditPool, type BillingInvoiceEntry, type BillingInvoicesResult, type BillingNamespace, type BillingPaymentMethodSummary, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, type DbNamespace, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, DeeplineError, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FetchOptions, type FileInput, type IngestionStorageRepairResult, type LiveEventEnvelope, type MonitorCheckResult, type MonitorControls, type MonitorDefinition, type MonitorDeleteResult, type MonitorDependents, type MonitorDeployResult, type MonitorDetail, type MonitorListEntry, type MonitorPayload, type MonitorReactivateResult, type MonitorSpec, type MonitorUpdateChangeSummary, type MonitorUpdateResult, type MonitorsAccessStatus, type MonitorsAvailableOptions, type MonitorsAvailableResult, type MonitorsListOptions, type MonitorsListResult, type MonitorsNamespace, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PlayActivityObservation, type PlayActivityState, type PlayActivityTarget, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayCallExecution, type PlayCallOptions, type PlayFetchResponse, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunActivityProjection, type PlayRunDatasetActions, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, type RuntimeStepOptions, SDK_API_CONTRACT, SDK_VERSION, type SqlListenerDeclaration, type SqlListenerEvent, type SqlListenerOperation, type SqlQuery, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopPlayRunResult, type ToolDefinition, ToolExecuteResult, type ToolExecution, ToolExecutionError, ToolExecutionErrorOptions, type ToolExecutionRequest, type ToolMetadata, ToolRateLimitError, type ToolSearchOptions, type ToolSearchResult, defineInput, defineMonitor, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };
+export { type AdmittedMonitorFleetAuthoringContract, AuthError, type BillingCreditPool, type BillingInvoiceEntry, type BillingInvoicesResult, type BillingNamespace, type BillingPaymentMethodSummary, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, type DbNamespace, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, DeeplineError, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FetchOptions, type FileInput, type IngestionStorageRepairResult, type LiveEventEnvelope, MONITOR_FLEET_AUTHORING_CONTRACT_CHANGELOG, MONITOR_FLEET_AUTHORING_CONTRACT_EDITION, MONITOR_FLEET_DOCUMENTATION, MONITOR_FLEET_FRONTIER_MAX_ROWS, MONITOR_FLEET_MAX_MEMBERS, type MonitorCheckResult, type MonitorControls, type MonitorDefinition, type MonitorDeleteResult, type MonitorDependents, type MonitorDeployResult, type MonitorDetail, type MonitorFleetAuthoringContractEdition, type MonitorFleetAuthoringContractResult, type MonitorFleetColumn, type MonitorFleetContractIssue, type MonitorFleetDeactivateOptions, type MonitorFleetDefinition, type MonitorFleetExpression, type MonitorFleetGetOptions, type MonitorFleetResult, type MonitorFleetStatus, type MonitorFleetSyncOptions, type MonitorFleetTemplate, type MonitorFleetWaitOptions, type MonitorFleetsNamespace, type MonitorListEntry, type MonitorPayload, type MonitorReactivateResult, type MonitorSpec, type MonitorUpdateChangeSummary, type MonitorUpdateResult, type MonitorsAccessStatus, type MonitorsAvailableOptions, type MonitorsAvailableResult, type MonitorsListOptions, type MonitorsListResult, type MonitorsNamespace, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PlayActivityObservation, type PlayActivityState, type PlayActivityTarget, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayCallExecution, type PlayCallOptions, type PlayFetchResponse, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunActivityProjection, type PlayRunDatasetActions, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, type RuntimeStepOptions, SDK_API_CONTRACT, SDK_VERSION, type SqlListenerDeclaration, type SqlListenerEvent, type SqlListenerOperation, type SqlQuery, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopPlayRunResult, type ToolDefinition, ToolExecuteResult, type ToolExecution, ToolExecutionError, ToolExecutionErrorOptions, type ToolExecutionRequest, type ToolMetadata, ToolRateLimitError, type ToolSearchOptions, type ToolSearchResult, admitMonitorFleetAuthoringContract, defineInput, defineMonitor, defineMonitorFleet, definePlay, defineWorkflow, extractSummaryFields, fleetColumn, fleetKey, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, validateMonitorFleetDefinition, writeCsvOutputFile, writeJsonOutputFile };

package/dist/index.d.ts

@@ -1900,6 +1900,134 @@ type MonitorControls = {
  */
 declare function defineMonitor<TPayload extends MonitorPayload = MonitorPayload>(definition: MonitorDefinition<TPayload>): MonitorDefinition<TPayload>;
 
+/**
+ * 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.
+ */
+declare const MONITOR_FLEET_MAX_MEMBERS = 1000;
+declare const MONITOR_FLEET_FRONTIER_MAX_ROWS = 10000;
+/**
+ * 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.
+ */
+declare const MONITOR_FLEET_AUTHORING_CONTRACT_EDITION: 1;
+declare const SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS: readonly [1];
+type MonitorFleetAuthoringContractEdition = (typeof SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS)[number];
+declare const MONITOR_FLEET_AUTHORING_CONTRACT_CHANGELOG: readonly [{
+    readonly edition: 1;
+    readonly changed: "Initial Fleet JSON contract: bounded sticky table membership, one daily sync, and a seven-day removal grace.";
+    readonly compatibilityOwner: "Monitors Runtime";
+    readonly newWritesEnd: null;
+    readonly readerRemoval: null;
+}];
+/**
+ * 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.
+ */
+declare const MONITOR_FLEET_DOCUMENTATION: {
+    readonly summary: "A Monitor Fleet keeps one bounded, sticky set of ordinary monitors aligned with Customer DB rows.";
+    readonly authoredFields: {
+        readonly id: "Stable lowercase fleet id used by sync, pause, resume, and deactivate.";
+        readonly source: "Customer DB table, unique row key, and optional equality filters that select candidate rows.";
+        readonly member: "Ordinary monitor tool, stable key template, and payload evaluated for each selected source row.";
+        readonly selection: "Deterministic ranking and an active-member limit between 1 and 1,000.";
+    };
+    readonly fixedPolicy: {
+        readonly cadence: "daily";
+        readonly membership: "sticky";
+        readonly removalGrace: "7d";
+        readonly onRemoved: "deactivate";
+        readonly 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.";
+        readonly billing: "No Fleet fee, permit, or renewal. Dry-run reports ordinary monitor lifecycle charges due now.";
+    };
+    readonly stickyMembership: "Ranking fills vacancies but never replaces a current member merely because another row ranks higher.";
+    readonly columnExpression: "Use { \"$fleet\": \"column\", \"name\": \"column_name\" } in a member key or payload to read a value from each source row.";
+};
+type MonitorFleetColumn = {
+    $fleet: 'column';
+    name: string;
+};
+type MonitorFleetTemplate = {
+    $fleet: 'template';
+    parts: Array<string | MonitorFleetColumn>;
+};
+type MonitorFleetExpression = MonitorFleetColumn | MonitorFleetTemplate;
+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';
+    };
+};
+type MonitorFleetContractIssue = {
+    path: string;
+    code: string;
+    message: string;
+};
+/** The durable, validated snapshot that a Fleet sync is allowed to execute. */
+type AdmittedMonitorFleetAuthoringContract = {
+    edition: MonitorFleetAuthoringContractEdition;
+    definition: MonitorFleetDefinition;
+};
+type MonitorFleetAuthoringContractResult = {
+    valid: boolean;
+    contract?: AdmittedMonitorFleetAuthoringContract;
+    issues: MonitorFleetContractIssue[];
+};
+declare function fleetColumn(name: string): MonitorFleetColumn;
+declare function fleetKey(...parts: Array<string | MonitorFleetColumn>): MonitorFleetTemplate;
+declare function defineMonitorFleet<const T extends MonitorFleetDefinition>(definition: T): T;
+declare function validateMonitorFleetDefinition(value: unknown): {
+    valid: boolean;
+    definition?: MonitorFleetDefinition;
+    issues: MonitorFleetContractIssue[];
+};
+/**
+ * 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.
+ */
+declare function admitMonitorFleetAuthoringContract(value: unknown, edition?: number): MonitorFleetAuthoringContractResult;
+
 interface PlayStagedFileRef {
     storageKind: 'r2';
     storageKey: string;
@@ -2396,6 +2524,66 @@ type MonitorDeleteResult = Record<string, unknown>;
 type MonitorReactivateResult = Record<string, unknown>;
 type MonitorTestResult = Record<string, unknown>;
 type MonitorValidateResult = Record<string, unknown>;
+/**
+ * Server-owned fleet response envelope.
+ *
+ * The server computes `status` (`converging` | `converged` | `degraded` |
+ * `deactivating` | `deactivated`) and the SDK never recomputes it: a client
+ * that derives its own verdict from counts drifts from the control plane the
+ * moment the server changes what "converged" means.
+ */
+type MonitorFleetResult = Record<string, unknown>;
+/** Server-computed fleet verdict. Never derived client-side. */
+type MonitorFleetStatus = 'converging' | 'converged' | 'degraded' | 'deactivating' | 'deactivated';
+type MonitorFleetSyncOptions = {
+    /** Return the plan without changing fleet state (`dry_run: true`). */
+    dryRun?: boolean;
+    /** Optimistic concurrency: refuse the write unless the fleet is at this generation. */
+    expectedGeneration?: number;
+    /** Stable retry key; generated by the caller when omitted. */
+    idempotencyKey?: string;
+};
+type MonitorFleetGetOptions = {
+    /** Include bounded per-member drift rows. */
+    drift?: boolean;
+    /** Maximum drift rows to return. */
+    limit?: number;
+};
+type MonitorFleetDeactivateOptions = {
+    /** Return the blast radius without deactivating anything. */
+    dryRun?: boolean;
+    idempotencyKey?: string;
+};
+type MonitorFleetWaitOptions = {
+    /** Give up after this long. Default 10 minutes. */
+    timeoutMs?: number;
+    /** Poll cadence. Default 2 seconds. */
+    pollIntervalMs?: number;
+    /** Called with every polled snapshot, including the terminal one. */
+    onProgress?: (payload: MonitorFleetResult) => void;
+    /**
+     * Which terminal state ends the wait. `converged` (default) also stops on
+     * `degraded` and `deactivated`; `deactivated` stops on `deactivated` and
+     * `degraded`. A timeout is not an error: the last snapshot is returned and
+     * the caller reads `status` to decide the verdict.
+     */
+    until?: 'converged' | 'deactivated';
+};
+type MonitorFleetsNamespace = {
+    /**
+     * Create, update, or re-plan a fleet. Pass a definition to admit new source
+     * of truth; pass a fleet id to re-plan from the stored definition.
+     */
+    sync: (definitionOrId: string | MonitorFleetDefinition, options?: MonitorFleetSyncOptions) => Promise<MonitorFleetResult>;
+    /** One fleet by id, or every fleet in the workspace when the id is omitted. */
+    get: (fleetId?: string, options?: MonitorFleetGetOptions) => Promise<MonitorFleetResult>;
+    /** Every fleet in the workspace. */
+    list: () => Promise<MonitorFleetResult>;
+    /** Deactivate a fleet and the monitors it owns. */
+    deactivate: (fleetId: string, options?: MonitorFleetDeactivateOptions) => Promise<MonitorFleetResult>;
+    /** Poll the fleet until the server reports a terminal status (or the timeout elapses). */
+    waitForConvergence: (fleetId: string, options?: MonitorFleetWaitOptions) => Promise<MonitorFleetResult>;
+};
 /**
  * Public monitors namespace exposed as `client.monitors`.
  *
@@ -2449,6 +2637,8 @@ type MonitorsNamespace = {
     reactivate: (key: string, options?: {
         dryRun?: boolean;
     }) => Promise<MonitorReactivateResult>;
+    /** Define, reconcile, and control table-backed monitor fleets. */
+    fleets: MonitorFleetsNamespace;
 };
 /** One credit grant pool reported by the billing subscription status endpoint. */
 type BillingCreditPool = {
@@ -3820,6 +4010,33 @@ declare class DeeplineClient {
     reactivateMonitor(key: string, options?: {
         dryRun?: boolean;
     }): Promise<MonitorReactivateResult>;
+    private monitorFleetIdempotencyKey;
+    private monitorFleetHeaders;
+    private monitorFleetPath;
+    /**
+     * Create, update, or re-plan one fleet.
+     *
+     * The fleet id is always the resource path, so the same definition PUT twice
+     * is the same operation and the server can answer `replayed: true` instead of
+     * building a second set of monitors. Re-planning an existing fleet from its
+     * stored definition sends an EMPTY body: there is no second definition to
+     * send, and an empty body cannot be mistaken for "replace the definition with
+     * nothing".
+     */
+    syncMonitorFleet(definitionOrId: string | MonitorFleetDefinition, options?: MonitorFleetSyncOptions): Promise<MonitorFleetResult>;
+    listMonitorFleets(): Promise<MonitorFleetResult>;
+    getMonitorFleet(fleetId: string, options?: MonitorFleetGetOptions): Promise<MonitorFleetResult>;
+    deactivateMonitorFleet(fleetId: string, options?: MonitorFleetDeactivateOptions): Promise<MonitorFleetResult>;
+    /**
+     * Poll one fleet until the server reports a terminal status.
+     *
+     * Convergence is the server's verdict, read from `status`. The timeout is not
+     * a failure and does not throw: a fleet still `converging` after ten minutes
+     * is healthy and slow, not broken, so the caller gets the last snapshot and
+     * decides what that means. Throwing here would have made "still working" look
+     * identical to "the request failed".
+     */
+    waitForMonitorFleetConvergence(fleetId: string, options?: MonitorFleetWaitOptions): Promise<MonitorFleetResult>;
     /**
      * Check API connectivity and server health.
      *
@@ -4286,8 +4503,7 @@ type PlayMetadata = {
 /**
  * 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
@@ -4414,12 +4630,7 @@ declare function defineInput<TInput>(schema: Record<string, unknown>): PlayInput
 /**
  * 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
@@ -4824,4 +5035,4 @@ declare function writeCsvOutputFile(rows: Array<Record<string, unknown>>, stem:
  */
 declare function extractSummaryFields(payload: unknown): Record<string, Scalar>;
 
-export { AuthError, type BillingCreditPool, type BillingInvoiceEntry, type BillingInvoicesResult, type BillingNamespace, type BillingPaymentMethodSummary, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, type DbNamespace, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, DeeplineError, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FetchOptions, type FileInput, type IngestionStorageRepairResult, type LiveEventEnvelope, type MonitorCheckResult, type MonitorControls, type MonitorDefinition, type MonitorDeleteResult, type MonitorDependents, type MonitorDeployResult, type MonitorDetail, type MonitorListEntry, type MonitorPayload, type MonitorReactivateResult, type MonitorSpec, type MonitorUpdateChangeSummary, type MonitorUpdateResult, type MonitorsAccessStatus, type MonitorsAvailableOptions, type MonitorsAvailableResult, type MonitorsListOptions, type MonitorsListResult, type MonitorsNamespace, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PlayActivityObservation, type PlayActivityState, type PlayActivityTarget, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayCallExecution, type PlayCallOptions, type PlayFetchResponse, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunActivityProjection, type PlayRunDatasetActions, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, type RuntimeStepOptions, SDK_API_CONTRACT, SDK_VERSION, type SqlListenerDeclaration, type SqlListenerEvent, type SqlListenerOperation, type SqlQuery, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopPlayRunResult, type ToolDefinition, ToolExecuteResult, type ToolExecution, ToolExecutionError, ToolExecutionErrorOptions, type ToolExecutionRequest, type ToolMetadata, ToolRateLimitError, type ToolSearchOptions, type ToolSearchResult, defineInput, defineMonitor, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };
+export { type AdmittedMonitorFleetAuthoringContract, AuthError, type BillingCreditPool, type BillingInvoiceEntry, type BillingInvoicesResult, type BillingNamespace, type BillingPaymentMethodSummary, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, type DbNamespace, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, DeeplineError, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FetchOptions, type FileInput, type IngestionStorageRepairResult, type LiveEventEnvelope, MONITOR_FLEET_AUTHORING_CONTRACT_CHANGELOG, MONITOR_FLEET_AUTHORING_CONTRACT_EDITION, MONITOR_FLEET_DOCUMENTATION, MONITOR_FLEET_FRONTIER_MAX_ROWS, MONITOR_FLEET_MAX_MEMBERS, type MonitorCheckResult, type MonitorControls, type MonitorDefinition, type MonitorDeleteResult, type MonitorDependents, type MonitorDeployResult, type MonitorDetail, type MonitorFleetAuthoringContractEdition, type MonitorFleetAuthoringContractResult, type MonitorFleetColumn, type MonitorFleetContractIssue, type MonitorFleetDeactivateOptions, type MonitorFleetDefinition, type MonitorFleetExpression, type MonitorFleetGetOptions, type MonitorFleetResult, type MonitorFleetStatus, type MonitorFleetSyncOptions, type MonitorFleetTemplate, type MonitorFleetWaitOptions, type MonitorFleetsNamespace, type MonitorListEntry, type MonitorPayload, type MonitorReactivateResult, type MonitorSpec, type MonitorUpdateChangeSummary, type MonitorUpdateResult, type MonitorsAccessStatus, type MonitorsAvailableOptions, type MonitorsAvailableResult, type MonitorsListOptions, type MonitorsListResult, type MonitorsNamespace, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PlayActivityObservation, type PlayActivityState, type PlayActivityTarget, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayCallExecution, type PlayCallOptions, type PlayFetchResponse, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunActivityProjection, type PlayRunDatasetActions, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, type RuntimeStepOptions, SDK_API_CONTRACT, SDK_VERSION, type SqlListenerDeclaration, type SqlListenerEvent, type SqlListenerOperation, type SqlQuery, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopPlayRunResult, type ToolDefinition, ToolExecuteResult, type ToolExecution, ToolExecutionError, ToolExecutionErrorOptions, type ToolExecutionRequest, type ToolMetadata, ToolRateLimitError, type ToolSearchOptions, type ToolSearchResult, admitMonitorFleetAuthoringContract, defineInput, defineMonitor, defineMonitorFleet, definePlay, defineWorkflow, extractSummaryFields, fleetColumn, fleetKey, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, validateMonitorFleetDefinition, writeCsvOutputFile, writeJsonOutputFile };