deepline 0.3.88 → 0.3.90

package/dist/monitor-fleet-contract.d.ts

@@ -0,0 +1,138 @@
+/// <reference path="./text-imports.d.ts" />
+/**
+ * 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.
+ */
+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;
+}];
+/**
+ * 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.
+ */
+declare const MONITOR_FLEET_REMOVAL_GRACE_MS: number;
+/**
+ * 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, get, 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;
+declare function evaluateMonitorFleetValue(value: unknown, row: Record<string, unknown>): unknown;
+
+export { type AdmittedMonitorFleetAuthoringContract, MONITOR_FLEET_AUTHORING_CONTRACT_CHANGELOG, MONITOR_FLEET_AUTHORING_CONTRACT_EDITION, MONITOR_FLEET_DOCUMENTATION, MONITOR_FLEET_FRONTIER_MAX_ROWS, MONITOR_FLEET_MAX_MEMBERS, MONITOR_FLEET_REMOVAL_GRACE_MS, type MonitorFleetAuthoringContractEdition, type MonitorFleetAuthoringContractResult, type MonitorFleetColumn, type MonitorFleetContractIssue, type MonitorFleetDefinition, type MonitorFleetExpression, type MonitorFleetTemplate, SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS, admitMonitorFleetAuthoringContract, defineMonitorFleet, evaluateMonitorFleetValue, fleetColumn, fleetKey, validateMonitorFleetDefinition };

package/dist/monitor-fleet-contract.js

@@ -0,0 +1,404 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/monitor-fleet-contract.ts
+var monitor_fleet_contract_exports = {};
+__export(monitor_fleet_contract_exports, {
+  MONITOR_FLEET_AUTHORING_CONTRACT_CHANGELOG: () => MONITOR_FLEET_AUTHORING_CONTRACT_CHANGELOG,
+  MONITOR_FLEET_AUTHORING_CONTRACT_EDITION: () => MONITOR_FLEET_AUTHORING_CONTRACT_EDITION,
+  MONITOR_FLEET_DOCUMENTATION: () => MONITOR_FLEET_DOCUMENTATION,
+  MONITOR_FLEET_FRONTIER_MAX_ROWS: () => MONITOR_FLEET_FRONTIER_MAX_ROWS,
+  MONITOR_FLEET_MAX_MEMBERS: () => MONITOR_FLEET_MAX_MEMBERS,
+  MONITOR_FLEET_REMOVAL_GRACE_MS: () => MONITOR_FLEET_REMOVAL_GRACE_MS,
+  SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS: () => SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS,
+  admitMonitorFleetAuthoringContract: () => admitMonitorFleetAuthoringContract,
+  defineMonitorFleet: () => defineMonitorFleet,
+  evaluateMonitorFleetValue: () => evaluateMonitorFleetValue,
+  fleetColumn: () => fleetColumn,
+  fleetKey: () => fleetKey,
+  validateMonitorFleetDefinition: () => validateMonitorFleetDefinition
+});
+module.exports = __toCommonJS(monitor_fleet_contract_exports);
+var MONITOR_FLEET_MAX_MEMBERS = 1e3;
+var MONITOR_FLEET_FRONTIER_MAX_ROWS = 1e4;
+var MONITOR_FLEET_AUTHORING_CONTRACT_EDITION = 1;
+var SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS = [
+  MONITOR_FLEET_AUTHORING_CONTRACT_EDITION
+];
+var 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
+  }
+];
+var MONITOR_FLEET_REMOVAL_GRACE_MS = 7 * 24 * 60 * 6e4;
+var 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.'
+};
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function identifier(value) {
+  return typeof value === "string" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+function exactKeys(input, keys, path, issues) {
+  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, path, issues) {
+  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);
+  }
+}
+function fleetColumn(name) {
+  if (!identifier(name)) throw new Error(`Invalid fleet column '${name}'.`);
+  return { $fleet: "column", name };
+}
+function fleetKey(...parts) {
+  if (parts.length === 0)
+    throw new Error("A fleet key needs at least one part.");
+  return { $fleet: "template", parts };
+}
+function defineMonitorFleet(definition) {
+  return definition;
+}
+function validateExpression(value, path, issues) {
+  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, path, issues) {
+  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);
+  }
+}
+function validateMonitorFleetDefinition(value) {
+  const issues = [];
+  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 !== void 0) {
+    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 = /* @__PURE__ */ new Set();
+    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)) {
+        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);
+      }
+    }
+    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, issues } : { valid: false, issues };
+}
+function admitMonitorFleetAuthoringContract(value, edition = MONITOR_FLEET_AUTHORING_CONTRACT_EDITION) {
+  if (!SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS.includes(
+    edition
+  )) {
+    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,
+      // JSON cloning prevents later caller mutation from changing the
+      // admitted snapshot.
+      definition: JSON.parse(
+        JSON.stringify(result.definition)
+      )
+    },
+    issues: []
+  } : { valid: false, issues: result.issues };
+}
+function evaluateMonitorFleetValue(value, row) {
+  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)
+    ])
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MONITOR_FLEET_AUTHORING_CONTRACT_CHANGELOG,
+  MONITOR_FLEET_AUTHORING_CONTRACT_EDITION,
+  MONITOR_FLEET_DOCUMENTATION,
+  MONITOR_FLEET_FRONTIER_MAX_ROWS,
+  MONITOR_FLEET_MAX_MEMBERS,
+  MONITOR_FLEET_REMOVAL_GRACE_MS,
+  SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS,
+  admitMonitorFleetAuthoringContract,
+  defineMonitorFleet,
+  evaluateMonitorFleetValue,
+  fleetColumn,
+  fleetKey,
+  validateMonitorFleetDefinition
+});