deepline 0.3.89 → 0.3.91

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

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

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

@@ -0,0 +1,320 @@
+/**
+ * The whole fleet planning decision, as pure functions.
+ *
+ * Everything here is a function of values the caller already read: the source
+ * frontier, the monitors the fleet owns, and the organization's limits. No
+ * Convex, no Customer DB, no provider. That is deliberate - every membership
+ * bug this feature has had lived in these rules, and each one used to cost a
+ * preview deploy to see. Here they cost a millisecond.
+ *
+ * The output is the `members` array `providerMonitorFleets:commitPlan` takes,
+ * verbatim. Planning decides; the commit publishes.
+ */
+
+import { MONITOR_FLEET_REMOVAL_GRACE_MS } from '../../integration-contracts/monitor-fleet-contract';
+import { FLEET_BLOCKED_BY } from './limits';
+export { FLEET_BLOCKED_BY } from './limits';
+
+// Rollout access is checked by convergence immediately before provider work,
+// not by this pure planner: an admitted plan can outlive rollout access.
+
+export type FleetMemberAction =
+  | 'create'
+  | 'update'
+  | 'remove'
+  | 'blocked'
+  | 'grace';
+
+/** One monitor the fleet wants, fully resolved from its source row. */
+export type DesiredFleetMember = {
+  sourceKey: string;
+  monitorKey: string;
+  /** The account this monitor watches. Null when the tool declares none. */
+  entityKey: string | null;
+  /** The rendered monitor definition: `{ key, tool, payload }`. */
+  definition: Record<string, unknown>;
+  desiredHash: string;
+};
+
+/** A monitor the fleet already owns, as Convex reports it. */
+export type OwnedFleetMonitor = {
+  monitorKey: string;
+  sourceKey: string | null;
+  entityKey: string | null;
+  convergence:
+    | 'pending'
+    | 'submitting'
+    | 'rate_limited'
+    | 'settled'
+    | 'blocked'
+    | 'failed';
+  desiredHash: string | null;
+  appliedHash: string | null;
+  firstMissingAt: number | null;
+};
+
+export type PlannedFleetMember = {
+  monitorKey: string;
+  sourceKey: string;
+  entityKey?: string;
+  action: FleetMemberAction;
+  desiredHash?: string;
+  desiredDefinition?: Record<string, unknown>;
+  blockedBy?: string;
+  /** True when the commit must be given a monitor seed for this key. */
+  needsSeed: boolean;
+};
+
+export type FleetPlan = {
+  members: PlannedFleetMember[];
+  creates: number;
+  updates: number;
+  removes: number;
+  /** Refusals by the limit that caused them, e.g. `{'monitor.watched_entities': 3}`. */
+  blocked: Record<string, number>;
+};
+
+export type FleetMembershipMember = {
+  sourceKey: string;
+  firstMissingAt: number | null;
+};
+
+export type FleetMembershipDecision = {
+  /** Source keys the fleet holds after this plan, in selection order. */
+  selected: string[];
+  /** Slots held by members whose grace has not expired. */
+  reservedGraceSlots: number;
+  /** Members whose row vanished on this plan. Grace starts now. */
+  markMissing: string[];
+  /** Members whose grace has expired and are now removed. */
+  remove: string[];
+};
+
+/**
+ * Slots held by members whose source row has vanished but whose removal grace
+ * has not expired.
+ *
+ * Such a member is still a member: it keeps its monitor, and grace exists so a
+ * row that comes back is restored rather than recreated. Handing its vacancy
+ * to the next ranked candidate immediately would push the fleet past its own
+ * limit, and then the reappearance grace is designed to absorb would force an
+ * eviction to get back under it - exactly the churn stickiness promises not to
+ * cause. Reserve the slot until grace actually expires.
+ */
+export function countReservedRemovalGraceSlots(input: {
+  members: readonly FleetMembershipMember[];
+  selectedSourceKeys: ReadonlySet<string>;
+  now: number;
+}): number {
+  return input.members.filter((member) => {
+    if (input.selectedSourceKeys.has(member.sourceKey)) return false;
+    // Not yet marked missing means this plan is the one that starts grace.
+    return (
+      member.firstMissingAt === null ||
+      input.now - member.firstMissingAt < MONITOR_FLEET_REMOVAL_GRACE_MS
+    );
+  }).length;
+}
+
+/**
+ * Who the fleet holds after a plan, given what the source still returns.
+ *
+ * The whole sticky/grace/limit rule in one place: an active member keeps its
+ * slot while its row exists, a vanished member keeps its slot until grace
+ * expires, and ranking only ever fills what is genuinely free.
+ */
+export function decideFleetMembership(input: {
+  limit: number;
+  members: readonly FleetMembershipMember[];
+  /** Member source keys whose row the source still returns. */
+  presentSourceKeys: ReadonlySet<string>;
+  /** Ranked non-member candidates, best first. */
+  candidates: readonly string[];
+  now: number;
+}): FleetMembershipDecision {
+  const selected: string[] = [];
+  const selectedKeys = new Set<string>();
+  // Sticky: ranking only fills vacancies, so score movement cannot churn an
+  // active member out of the fleet.
+  for (const member of input.members) {
+    if (!input.presentSourceKeys.has(member.sourceKey)) continue;
+    if (selectedKeys.has(member.sourceKey)) continue;
+    selected.push(member.sourceKey);
+    selectedKeys.add(member.sourceKey);
+  }
+  const reservedGraceSlots = countReservedRemovalGraceSlots({
+    members: input.members,
+    selectedSourceKeys: selectedKeys,
+    now: input.now,
+  });
+  for (const candidate of input.candidates) {
+    if (selected.length + reservedGraceSlots >= input.limit) break;
+    if (selectedKeys.has(candidate)) continue;
+    selected.push(candidate);
+    selectedKeys.add(candidate);
+  }
+  const markMissing: string[] = [];
+  const remove: string[] = [];
+  for (const member of input.members) {
+    if (selectedKeys.has(member.sourceKey)) continue;
+    if (member.firstMissingAt === null) {
+      markMissing.push(member.sourceKey);
+      continue;
+    }
+    if (input.now - member.firstMissingAt < MONITOR_FLEET_REMOVAL_GRACE_MS) {
+      continue;
+    }
+    remove.push(member.sourceKey);
+  }
+  return { selected, reservedGraceSlots, markMissing, remove };
+}
+
+/** The account a monitor is counted against. Never null, so nothing is uncounted. */
+export function fleetEntityKeyFor(input: {
+  monitorKey: string;
+  entityKey: string | null;
+}): string {
+  // A monitor with no derivable account is its own account, so it still
+  // occupies exactly one unit of allowance rather than slipping through.
+  return input.entityKey ?? `monitor:${input.monitorKey}`;
+}
+
+export type FleetEntitlements = {
+  /** New accounts this organization may still open. */
+  watchedEntitiesRemaining: number;
+  /** Monitors admitted against any one account. */
+  monitorsPerEntity: number;
+};
+
+/**
+ * Turn "what the fleet wants" plus "what it already owns" into commit members.
+ *
+ * Ordering matters and is deliberate: creates are admitted in selection order,
+ * so a fleet at its account limit keeps the members the source ranked highest
+ * rather than whichever ones happened to sort first by key.
+ */
+export function planFleetMembers(input: {
+  desired: readonly DesiredFleetMember[];
+  owned: readonly OwnedFleetMonitor[];
+  /** Source keys whose grace expired, from `decideFleetMembership`. */
+  remove: readonly string[];
+  /** Source keys whose row vanished on this plan. */
+  markMissing: readonly string[];
+  entitlements: FleetEntitlements;
+  /**
+   * Monitors already counted against an account, org-wide. An account absent
+   * from this map is one the organization does not watch yet, and opening it
+   * is what costs allowance.
+   */
+  entityMonitorCounts: ReadonlyMap<string, number>;
+}): FleetPlan {
+  const ownedByKey = new Map(
+    input.owned.map((monitor) => [monitor.monitorKey, monitor]),
+  );
+  const ownedBySource = new Map<string, OwnedFleetMonitor>();
+  for (const monitor of input.owned) {
+    if (monitor.sourceKey) ownedBySource.set(monitor.sourceKey, monitor);
+  }
+
+  const entityCounts = new Map(input.entityMonitorCounts);
+  const heldEntities = new Set(
+    [...entityCounts.entries()]
+      .filter(([, count]) => count > 0)
+      .map(([entityKey]) => entityKey),
+  );
+  let newEntitiesUsed = 0;
+
+  const members: PlannedFleetMember[] = [];
+  const blocked: Record<string, number> = {};
+  let creates = 0;
+  let updates = 0;
+  let removes = 0;
+
+  const refuse = (member: PlannedFleetMember, blockedBy: string) => {
+    blocked[blockedBy] = (blocked[blockedBy] ?? 0) + 1;
+    members.push({ ...member, action: 'blocked', blockedBy });
+  };
+
+  for (const desired of input.desired) {
+    const owned =
+      ownedByKey.get(desired.monitorKey) ??
+      ownedBySource.get(desired.sourceKey);
+    const entityKey = fleetEntityKeyFor(desired);
+    const base: PlannedFleetMember = {
+      monitorKey: desired.monitorKey,
+      sourceKey: desired.sourceKey,
+      entityKey,
+      action: 'create',
+      desiredHash: desired.desiredHash,
+      desiredDefinition: desired.definition,
+      needsSeed: true,
+    };
+
+    const applied = owned?.appliedHash ?? null;
+    if (applied !== null) {
+      // The provider already holds this monitor. Nothing to admit against a
+      // limit: it is already counted, and an update never opens an account.
+      const settledOnDesired =
+        applied === desired.desiredHash &&
+        owned?.convergence === 'settled' &&
+        owned.firstMissingAt === null;
+      if (settledOnDesired) continue;
+      // A member whose row came back inside its grace window is restored by
+      // re-publishing the state it already holds. That clears the removal
+      // clock through the same guarded transition every other change uses,
+      // rather than needing a second write path that could disagree with it.
+      members.push({ ...base, action: 'update', needsSeed: false });
+      updates += 1;
+      continue;
+    }
+
+    const onEntity = entityCounts.get(entityKey) ?? 0;
+    if (onEntity >= input.entitlements.monitorsPerEntity) {
+      refuse(base, FLEET_BLOCKED_BY.monitorsPerEntity);
+      continue;
+    }
+    if (
+      !heldEntities.has(entityKey) &&
+      newEntitiesUsed >= input.entitlements.watchedEntitiesRemaining
+    ) {
+      refuse(base, FLEET_BLOCKED_BY.watchedEntities);
+      continue;
+    }
+    if (!heldEntities.has(entityKey)) {
+      heldEntities.add(entityKey);
+      newEntitiesUsed += 1;
+    }
+    entityCounts.set(entityKey, onEntity + 1);
+    members.push(base);
+    creates += 1;
+  }
+
+  const plannedKeys = new Set(members.map((member) => member.monitorKey));
+  for (const sourceKey of input.markMissing) {
+    const owned = ownedBySource.get(sourceKey);
+    if (!owned || plannedKeys.has(owned.monitorKey)) continue;
+    members.push({
+      monitorKey: owned.monitorKey,
+      sourceKey,
+      ...(owned.entityKey ? { entityKey: owned.entityKey } : {}),
+      action: 'grace',
+      needsSeed: false,
+    });
+    plannedKeys.add(owned.monitorKey);
+  }
+  for (const sourceKey of input.remove) {
+    const owned = ownedBySource.get(sourceKey);
+    if (!owned || plannedKeys.has(owned.monitorKey)) continue;
+    members.push({
+      monitorKey: owned.monitorKey,
+      sourceKey,
+      ...(owned.entityKey ? { entityKey: owned.entityKey } : {}),
+      action: 'remove',
+      needsSeed: false,
+    });
+    plannedKeys.add(owned.monitorKey);
+    removes += 1;
+  }
+
+  return { members, creates, updates, removes, blocked };
+}

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

@@ -0,0 +1,106 @@
+/**
+ * One place that decides what a fleet's convergence counts mean.
+ *
+ * The verdict is server-owned on purpose. Every surface that has ever shown a
+ * fleet - the CLI, the API, a dashboard - has to answer the same question
+ * ("is this fleet done, and if not, is anything wrong?"), and each one that
+ * derives it from raw counts derives it slightly differently. The counts are
+ * the fact; this is the single reading of them.
+ */
+
+export type FleetConvergenceCounts = {
+  pending: number;
+  submitting: number;
+  rate_limited: number;
+  settled: number;
+  blocked: number;
+  failed: number;
+};
+
+/** The lifecycle a fleet row records. */
+export type FleetLifecycleStatus =
+  | 'active'
+  | 'deactivating'
+  | 'deactivated'
+  | 'billing_suspending'
+  | 'billing_suspended'
+  | 'billing_reactivating';
+
+/** What a caller is told the fleet is doing. */
+export type FleetStatusVerdict =
+  | 'converging'
+  | 'converged'
+  | 'degraded'
+  | 'deactivating'
+  | 'deactivated'
+  | 'billing_suspending'
+  | 'billing_suspended'
+  | 'billing_reactivating';
+
+const ZERO_FLEET_COUNTS: FleetConvergenceCounts = {
+  pending: 0,
+  submitting: 0,
+  rate_limited: 0,
+  settled: 0,
+  blocked: 0,
+  failed: 0,
+};
+
+export function fleetCounts(
+  raw: Partial<FleetConvergenceCounts> | null | undefined,
+): FleetConvergenceCounts {
+  return { ...ZERO_FLEET_COUNTS, ...(raw ?? {}) };
+}
+
+/** Monitors a provider still owes an answer for. */
+export function fleetOutstanding(counts: FleetConvergenceCounts): number {
+  return counts.pending + counts.submitting + counts.rate_limited;
+}
+
+/** Monitors this fleet expects to exist, including the ones it cannot create. */
+export function fleetExpected(counts: FleetConvergenceCounts): number {
+  return (
+    counts.settled +
+    counts.pending +
+    counts.submitting +
+    counts.rate_limited +
+    counts.blocked +
+    counts.failed
+  );
+}
+
+/** Monitors the provider is confirmed to hold. */
+export function fleetLive(counts: FleetConvergenceCounts): number {
+  return counts.settled;
+}
+
+/**
+ * The verdict.
+ *
+ * `converged` deliberately requires the published generation to be the one
+ * that converged. Outstanding-is-zero alone is equally true of a generation
+ * whose monitors have not been committed yet, and answering "converged" then
+ * tells a caller its change is live before any provider has seen it.
+ *
+ * `degraded` is the honest middle: nothing is in flight, so waiting longer
+ * changes nothing, but some monitors are blocked or failed and the fleet does
+ * not hold what it was asked to hold.
+ */
+export function fleetStatusVerdict(input: {
+  status: FleetLifecycleStatus;
+  counts: FleetConvergenceCounts;
+  generation: number;
+  convergedGeneration: number | null;
+}): FleetStatusVerdict {
+  if (input.status === 'deactivated') return 'deactivated';
+  if (input.status === 'deactivating') return 'deactivating';
+  if (input.status === 'billing_suspended') return 'billing_suspended';
+  if (input.status === 'billing_suspending') return 'billing_suspending';
+  if (input.status === 'billing_reactivating') return 'billing_reactivating';
+  const outstanding = fleetOutstanding(input.counts);
+  if (outstanding > 0) return 'converging';
+  if (input.counts.blocked + input.counts.failed > 0) return 'degraded';
+  return input.convergedGeneration === input.generation
+    ? 'converged'
+    : 'converging';
+}

package/dist/bundling-sources/shared_libs/monitors/http-error-response.ts

@@ -137,6 +137,9 @@ export function monitorErrorNextAction(payload: MonitorErrorPayload): string {
       ? `Wait ${retryAfterMs} ms, then retry the same read or check once.`
       : 'Wait for Customer DB provisioning, then retry the same read or check once.';
   }
+  if (code === 'monitor_control_plane_unavailable') {
+    return 'Wait briefly, then rerun the same monitor read. No monitor state was changed.';
+  }
   if (code === 'provider_monitor_identity_backfill_in_progress') {
     return typeof retryAfterSeconds === 'number'
       ? `Wait ${retryAfterSeconds} seconds, then retry the same monitor lifecycle request once. No upstream monitor was created.`
@@ -186,7 +189,11 @@ export function monitorErrorNextAction(payload: MonitorErrorPayload): string {
     return `This workspace already has ${MAX_PRIORITY_MONITORS_PER_ORG} priority radars. Delete or update an existing priority radar only after confirming it is no longer needed, then retry the urgent preview.`;
   }
   if (code === 'monitor_already_exists') {
-    const existing = asRecord(nestedError(payload)?.existing_monitor)?.key;
+    const existingMonitor = asRecord(nestedError(payload)?.existing_monitor);
+    const existing = existingMonitor?.key;
+    if (existingMonitor?.status === 'provisioning') {
+      return 'An in-progress provider operation owns this identity. Do not deploy another key or delete and redeploy. Wait for it to finish, then rerun this check; if the conflict remains, contact Deepline support with the returned tool and identity.';
+    }
     return typeof existing === 'string'
       ? `Run \`deepline monitors get ${existing} --json\` to inspect the monitor that owns this identity. Reuse it or contact Deepline support before replacing it; do not delete and redeploy blindly.`
       : 'Inspect the returned existing_monitor.key with `deepline monitors get <key> --json`. Reuse that monitor or contact Deepline support before replacing it; do not delete and redeploy blindly.';

package/dist/bundling-sources/shared_libs/monitors/inbound-queue.ts

@@ -4,13 +4,13 @@ import {
   recordSignalRadarDeadLetter as recordSignalRadarDeadLetterCore,
   type InboundFailureClass,
   type InboundPgClient,
-} from '@/lib/signal-radars/inbound-dead-letter';
+} from '@deepline/monitors/signal-radars/inbound-dead-letter';
 import {
   send as sendSignalRadarInbound,
   SIGNAL_RADAR_INBOUND_TOPIC as SIGNAL_RADAR_INBOUND_TOPIC_VALUE,
   type SignalRadarInboundSendOptions,
-} from '@/lib/signal-radars/inbound-queue';
-import type { SignalRadarInboundMessage } from '@/lib/signal-radars/inbound-message';
+} from '@deepline/monitors/signal-radars/inbound-queue';
+import type { SignalRadarInboundMessage } from '@deepline/monitors/signal-radars/inbound-message';
 
 // Public inbound-queue surface used by the thin provider-callback receiver.
 // Re-exports the topic + producer and adds the Neon-free publish key helper and
@@ -78,5 +78,5 @@ export async function recordSignalRadarDeadLetter(
   });
 }
 
-export type { SignalRadarInboundMessage } from '@/lib/signal-radars/inbound-message';
+export type { SignalRadarInboundMessage } from '@deepline/monitors/signal-radars/inbound-message';
 export { headersToObject };

package/dist/bundling-sources/shared_libs/monitors/inventory-reconciliation.ts

@@ -0,0 +1,59 @@
+/** Shared inventory rules. Job progress and missing evidence are not monitor states. */
+export type InventoryRadar = {
+  id: string;
+  status: 'active' | 'inactive' | 'unknown';
+};
+export type InventoryDecision = {
+  verdict: 'converged' | 'desynced' | 'unknown';
+  reason: string;
+  radarId?: string;
+};
+
+/** Call only after BOTH inventories completed. Absence is otherwise unknown. */
+export function compareMonitorInventory(input: {
+  desired: 'active' | 'inactive';
+  resourceId: string | null;
+  exact: InventoryRadar[];
+  marker: InventoryRadar[];
+  candidateOwnerCount: number;
+}): InventoryDecision {
+  const { desired, resourceId, exact, marker, candidateOwnerCount } = input;
+  if (exact.length > 1 || candidateOwnerCount > (resourceId ? 1 : 0)) {
+    return { verdict: 'unknown', reason: 'ambiguous_tamradar_binding' };
+  }
+  if (!resourceId) {
+    if (marker.length > 1)
+      return { verdict: 'unknown', reason: 'ambiguous_tamradar_binding' };
+    if (marker.length === 1)
+      return {
+        verdict: 'desynced',
+        reason: 'adoptable_tamradar_radar',
+        radarId: marker[0]!.id,
+      };
+  }
+  const radar = exact[0];
+  if (!radar) {
+    if (!resourceId) {
+      // A complete account list proves that no stamped counterpart exists; it
+      // cannot prove which resource an unbound historical row used to own.
+      // Creation or adoption is a separate, explicit operator operation.
+      return { verdict: 'unknown', reason: 'missing_tamradar_binding' };
+    }
+    return desired === 'inactive'
+      ? { verdict: 'converged', reason: 'in_sync' }
+      : { verdict: 'desynced', reason: 'missing_tamradar_radar' };
+  }
+  if (radar.status === 'unknown')
+    return {
+      verdict: 'unknown',
+      reason: 'unknown_tamradar_state',
+      radarId: radar.id,
+    };
+  return radar.status === desired
+    ? { verdict: 'converged', reason: 'in_sync', radarId: radar.id }
+    : {
+        verdict: 'desynced',
+        reason: 'tamradar_state_differs',
+        radarId: radar.id,
+      };
+}

package/dist/bundling-sources/shared_libs/monitors/lifecycle-notifications.ts

@@ -1,7 +1,7 @@
 // Internal Slack notifications for monitor / triggered-play lifecycle + activity.
 //
 // These are thin, best-effort helpers (mirroring
-// `src/lib/plays/team-notifications.ts`) that build a Slack payload via
+// `apps/deepline-api/src/lib/plays/team-notifications.ts`) that build a Slack payload via
 // `buildSlackActivityPayload` and dispatch it through `sendSlackEventSafe` on
 // one of two internal channels:
 //
@@ -17,19 +17,17 @@
 //     (we set `bypassInternalActorBlock`), BUT synthetic `@deepline.local`
 //     dev-bootstrap test orgs are always suppressed (see
 //     `shouldSuppressMonitorActor` + the transport-level guard in
-//     `slack-events.ts`).
+//     the shared Slack delivery contract).
 //   - Environments: ALL (dev + preview + prod). The two channels declare
-//     `requiredEnv: 'all'` in `slack-events.ts`, so they post in local dev too.
+//     `requiredEnv: 'all'` in the delivery contract, so they post in local dev too.
 //   - Spend: NEVER include provider spend. These payloads carry only keys,
 //     counts, and trigger metadata — no provider-cost fields.
 
 import { after } from 'next/server';
-import {
-  buildSlackActivityPayload,
-  isSyntheticActorEmail,
-  sendSlackEventSafe,
-} from '@/lib/slack-events';
-import { getRuntimeEnv } from '@/lib/runtime-env';
+import { sendSlackEventSafe } from '../product-notifications/slack-delivery';
+import { isSyntheticActorEmail } from '@deepline/auth/synthetic-identity';
+import { buildSlackActivityPayload } from '../product-notifications/slack-payload';
+import { getRuntimeEnv } from '../play-runtime/runtime-env';
 
 /**
  * Schedule a best-effort Slack dispatch WITHOUT blocking the caller. The

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

@@ -1,19 +1,9 @@
 /**
  * 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` cannot import this file - the
- * workspace-architecture ratchet forbids new `shared_libs` edges from packages
- * - so it mirrors the literal, and `tests/lib/monitors/monitor-fleet-limits-
- * mirror.test.ts` holds the two equal by name. Everything outside Convex reads
- * the contract module's copy and never learns this file exists.
+ * Convex transaction sizing and SDK admission use the same canonical limit.
  */
-export const MONITOR_FLEET_MAX_MEMBERS = 1_000;
+export { MONITOR_FLEET_MAX_MEMBERS } from '../integration-contracts/monitor-fleet-contract';
 
 /**
  * A claim may carry at most this many independent (organization, fleet)