deepline 0.3.89 → 0.3.91

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

@@ -1,556 +1,2 @@
-/**
- * The fleet member ceiling, mirrored — deliberately a literal.
- *
- * The canonical declaration is packages/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, 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),
-    ]),
-  );
-}
+// Preserve the published SDK entrypoint; the shared contract has one owner.
+export * from '../../shared_libs/integration-contracts/monitor-fleet-contract';

package/dist/bundling-sources/sdk/src/monitor-fleets.ts

@@ -17,7 +17,7 @@ export {
   fleetColumn,
   fleetKey,
   validateMonitorFleetDefinition,
-} from './monitor-fleet-contract.js';
+} from '../../shared_libs/integration-contracts/monitor-fleet-contract';
 
 export type {
   AdmittedMonitorFleetAuthoringContract,
@@ -28,4 +28,4 @@ export type {
   MonitorFleetDefinition,
   MonitorFleetExpression,
   MonitorFleetTemplate,
-} from './monitor-fleet-contract.js';
+} from '../../shared_libs/integration-contracts/monitor-fleet-contract';

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

@@ -0,0 +1,25 @@
+/** Walk bounded cursor pages without reporting a partial result as complete. */
+export async function* iterateCursorPages<T>(
+  fetchPage: (cursor: string | null) => Promise<{
+    items: T[];
+    hasMore: boolean;
+    cursor: string | null;
+  }>,
+): AsyncGenerator<T[]> {
+  let cursor: string | null = null;
+  const seen = new Set<string>();
+  for (;;) {
+    const page = await fetchPage(cursor);
+    if (page.hasMore) {
+      if (!page.cursor || seen.has(page.cursor)) {
+        throw new Error(
+          'Pagination reported more results without an advancing cursor',
+        );
+      }
+      seen.add(page.cursor);
+    }
+    yield page.items;
+    if (!page.hasMore) return;
+    cursor = page.cursor;
+  }
+}

package/dist/bundling-sources/sdk/src/plays/bundle-play-file.ts

@@ -89,7 +89,7 @@ let hasWarnedAboutNonDevelopmentBundling = false;
  * Tool-aware validation belongs to the Deepline API after upload:
  * `compilePlayManifest` / server preflight runs the cloud typechecker inside
  * the app deployment, where the generated catalog is a normal build artifact.
- * Do not import `src/lib/plays/cloud-tool-typecheck` or any generated app
+ * Do not import `apps/deepline-api/src/lib/plays/cloud-tool-typecheck` or any generated app
  * catalog from this SDK adapter.
  */
 function warnAboutNonDevelopmentBundling(filePath: string): void {

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

@@ -23,12 +23,12 @@ import { CURRENT_PLAY_ARTIFACT_CONTRACT_VERSION } from '../../shared_libs/plays/
  * Everything else derives from these values:
  *
  *   - `packages/sdk/src/version.ts` re-exports `SDK_VERSION` and `SDK_API_CONTRACT`.
- *   - `src/lib/sdk/release-policy.ts` re-exports `SDK_RELEASE_POLICY`.
+ *   - `apps/deepline-api/src/lib/sdk/release-policy.ts` re-exports `SDK_RELEASE_POLICY`.
  *   - `packages/sdk/package.json` `version` is stamped from `SDK_RELEASE.version` by
  *     `scripts/sync-sdk-package-version.ts`, which runs as part of
  *     `bun run sdk:build`.
  *   - `contracts/sdk-api.manifest.json` is regenerated at build time from
- *     `src/lib/sdk/api-routes.ts` and the apiContract here; the matching
+ *     `apps/deepline-api/src/lib/sdk/api-routes.ts` and the apiContract here; the matching
  *     `contracts/sdk-api.manifest.hash` is an ignored local/CI audit artifact.
  *
  * Any drift between release source and derived release locations is a
@@ -199,21 +199,23 @@ 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.89',
+  // 0.3.90 is the first deliberately versioned SDK release for API v3.
+  version: '0.3.91',
   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.',
+    'Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.',
   packageCapabilities: {
     updatePreferences: 1,
   },
   contracts: {
     api: {
       name: 'sdk-http-api',
-      // API v2 is append-only. A breaking public request/response change needs
-      // v3 and an explicit v2 support-window decision, never a patch release.
-      currentMajor: 2,
-      supportedMajors: [2],
-      // Accepted only to bridge SDKs released before X-Deepline-API-Major.
+      // Concise Play grep has the current wire id. Older ids follow the
+      // standard API support window.
+      currentMajor: 3,
+      supportedMajors: [3, 2],
+      // Older ids remain subject to the API support window.
       legacyWireIds: [
+        '2026-09-play-grep-concise-results',
         '2026-07-admin-cli-local-cutover',
         '2026-07-native-monitor-launch-hard-cutover',
       ],