deepline 0.3.480 → 0.3.481

package/dist/bundling-sources/shared_libs/monitors/legacy-radar-retirement.ts

@@ -0,0 +1,451 @@
+// Approved legacy-radar retirement: the pure rules.
+//
+// A legacy radar is an upstream TamRadar resource that Deepline did not create
+// through a monitor definition, so it carries no `deepline_monitor_key` marker
+// and the global audit can never prove it closable. An operator retires such
+// radars only from a sealed approval (Convex tables
+// `providerMonitorLegacyRetirementApprovals` / `...Items`), and only once the
+// subject is still covered: by the required managed monitor, unchanged in
+// configuration, active, and routed.
+//
+// Everything here is pure so the Convex action, the private operator bridge
+// and the CLI apply one rule. It must stay Convex-safe: no Node imports.
+
+export const LEGACY_RETIREMENT_MAX_BATCH = 100;
+
+/**
+ * Radars legacy retirement refuses by ID before any provider call. KAR-120:
+ * the funding radar backs the public funding-updates tool and has no Convex
+ * definition. The provider's own deactivate contract refuses it on every
+ * path; a test pins that this list stays within what that contract refuses.
+ */
+export const LEGACY_RETIREMENT_PROTECTED_RADAR_IDS: ReadonlySet<string> =
+  new Set(['3bc8ee34-e0e7-4f62-b34b-076c613f8ed6']);
+/** One approval is sealed in one transaction, which reads every item once. */
+export const LEGACY_RETIREMENT_MAX_ROWS = 5_000;
+/** An attempt that recorded intent owns its item for this long. */
+export const LEGACY_RETIREMENT_INTENT_LEASE_MS = 15 * 60_000;
+/** Approved route tables are always a schema-qualified lower_snake name. */
+export const LEGACY_RETIREMENT_ROUTE_TABLE_PATTERN = /^[a-z_]+\.[a-z_]+$/;
+
+export const LEGACY_CONTACT_RADAR_TYPES = [
+  'contact_job_changes',
+  'contact_social_posts',
+  'contact_social_engagements',
+] as const;
+export const LEGACY_COMPANY_RADAR_TYPES = [
+  'company_new_hires',
+  'company_job_openings',
+  'company_promotions',
+  'company_reviews',
+  'company_mentions',
+  'company_social_posts',
+  'company_social_posts_cxo',
+  'company_social_engagements',
+] as const;
+
+export function isLegacyContactRadarType(radarType: string): boolean {
+  return (LEGACY_CONTACT_RADAR_TYPES as readonly string[]).includes(radarType);
+}
+
+export function isLegacyCompanyRadarType(radarType: string): boolean {
+  return (LEGACY_COMPANY_RADAR_TYPES as readonly string[]).includes(radarType);
+}
+
+/** The monitor tool whose payload validation applies to a radar type. */
+export function legacyRadarMonitorTool(radarType: string): string | null {
+  if (isLegacyContactRadarType(radarType))
+    return 'deepline_native.contact_radar';
+  if (isLegacyCompanyRadarType(radarType))
+    return 'deepline_native.company_radar';
+  return null;
+}
+
+export type LegacyExpectedConfig = {
+  radar_type: string;
+  /** Contact types only: lowercased LinkedIn `/in/<slug>`. */
+  profile_slug?: string;
+  /** Company types and `contact_job_changes`; optional on social posts. */
+  domain?: string;
+  filters: Record<string, unknown>;
+};
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function nonEmptyText(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+/** Throws on anything but the approved `{radar_type, profile_slug?, domain?, filters}` shape. */
+export function parseLegacyExpectedConfig(text: string): LegacyExpectedConfig {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error('The required monitor expected config is not valid JSON.');
+  }
+  const value = record(parsed);
+  if (!value) {
+    throw new Error('The required monitor expected config must be an object.');
+  }
+  const unknownKeys = Object.keys(value).filter(
+    (key) => !['radar_type', 'profile_slug', 'domain', 'filters'].includes(key),
+  );
+  if (unknownKeys.length) {
+    throw new Error(
+      `The required monitor expected config has unknown keys: ${unknownKeys.join(', ')}.`,
+    );
+  }
+  const radarType = nonEmptyText(value.radar_type);
+  if (!radarType || !legacyRadarMonitorTool(radarType)) {
+    throw new Error(
+      'The required monitor expected config needs a known contact or company radar_type.',
+    );
+  }
+  const filters = record(value.filters);
+  if (!filters) {
+    throw new Error(
+      'The required monitor expected config needs a filters object.',
+    );
+  }
+  const slug =
+    value.profile_slug === undefined ? null : nonEmptyText(value.profile_slug);
+  // An empty or null domain is recorded as no domain. Where the radar type
+  // needs one, the match then refuses (`required_monitor_expected_domain_missing`)
+  // instead of guessing which company was meant.
+  const domain =
+    value.domain === undefined || value.domain === null
+      ? null
+      : typeof value.domain === 'string'
+        ? nonEmptyText(value.domain)
+        : undefined;
+  if (domain === undefined) {
+    throw new Error('domain must be a string when present.');
+  }
+  if (value.profile_slug !== undefined && !slug) {
+    throw new Error('profile_slug must be a non-empty string when present.');
+  }
+  if (isLegacyContactRadarType(radarType) && !slug) {
+    throw new Error(`${radarType} expected configs require profile_slug.`);
+  }
+  if (isLegacyCompanyRadarType(radarType) && slug) {
+    throw new Error(`${radarType} expected configs take no profile_slug.`);
+  }
+  return {
+    radar_type: radarType,
+    ...(slug ? { profile_slug: slug.toLowerCase() } : {}),
+    ...(domain ? { domain } : {}),
+    filters,
+  };
+}
+
+/** Lowercased `/in/<slug>` of a LinkedIn profile URL, or null. */
+export function linkedinProfileSlug(url: unknown): string | null {
+  const text = nonEmptyText(url);
+  if (!text) return null;
+  const match = /\/in\/([^/?#]+)/i.exec(text);
+  if (!match?.[1]) return null;
+  let slug = match[1];
+  try {
+    slug = decodeURIComponent(slug);
+  } catch {
+    // A malformed escape is compared as written.
+  }
+  slug = slug.trim().toLowerCase();
+  return slug || null;
+}
+
+/** Scheme, `www.`, port, path and case removed: `https://WWW.Acme.com/x` -> `acme.com`. */
+export function normalizeRadarDomain(value: unknown): string | null {
+  let text = nonEmptyText(value)?.toLowerCase();
+  if (!text) return null;
+  text = text.replace(/^[a-z][a-z0-9+.-]*:\/\//, '');
+  text = text.split(/[/?#]/, 1)[0] ?? '';
+  text = text.replace(/:\d+$/, '').replace(/\.$/, '');
+  text = text.replace(/^www\./, '');
+  return text || null;
+}
+
+// Fields that name the subject rather than narrow it, per radar family.
+const CONTACT_SUBJECT_FIELDS = new Set([
+  'radar_type',
+  'profile_url',
+  'domain',
+  'email',
+  'full_name',
+]);
+const COMPANY_SUBJECT_FIELDS = new Set(['radar_type', 'domain']);
+// Fields that never change which findings a radar delivers: the replay start,
+// and the framework-managed callback URL and correlation markers.
+const NON_CONFIGURATION_FIELDS = new Set([
+  'updates_since',
+  'webhook_url',
+  'custom_fields',
+]);
+
+function absent(value: unknown): boolean {
+  return (
+    value === undefined ||
+    value === null ||
+    (typeof value === 'string' && !value.trim()) ||
+    (Array.isArray(value) && value.length === 0)
+  );
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.entries(value as Record<string, unknown>)
+      .filter(([, entry]) => !absent(entry))
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+}
+
+/**
+ * Whether a live monitor payload still covers exactly the approved subject.
+ * Returns null on a match, otherwise the refusal reason.
+ *
+ * - same `radar_type`;
+ * - contact types: the same LinkedIn `/in/<slug>`;
+ * - company types and `contact_job_changes`: the same normalized domain;
+ * - contact social types: a domain, when expected, may be missing (the one
+ *   allowed broadening) but never different; an unexpected domain refuses;
+ * - no filter beyond the expected `filters` (empty values count as absent,
+ *   `updates_since` and framework-managed fields are ignored).
+ */
+export function legacyMonitorConfigMismatch(input: {
+  expected: LegacyExpectedConfig;
+  payload: unknown;
+}): string | null {
+  const payload = record(input.payload);
+  if (!payload) return 'required_monitor_payload_missing';
+  const { expected } = input;
+  if (nonEmptyText(payload.radar_type) !== expected.radar_type) {
+    return 'required_monitor_radar_type_changed';
+  }
+  const contact = isLegacyContactRadarType(expected.radar_type);
+  if (contact) {
+    if (linkedinProfileSlug(payload.profile_url) !== expected.profile_slug) {
+      return 'required_monitor_profile_changed';
+    }
+  }
+  const liveDomain = normalizeRadarDomain(payload.domain);
+  const expectedDomain = normalizeRadarDomain(expected.domain);
+  if (
+    expectedDomain === null &&
+    (!contact || expected.radar_type === 'contact_job_changes')
+  ) {
+    return 'required_monitor_expected_domain_missing';
+  }
+  if (contact && expected.radar_type !== 'contact_job_changes') {
+    // Social radars: a missing domain is the one allowed broadening.
+    if (liveDomain !== null && liveDomain !== expectedDomain) {
+      return 'required_monitor_domain_changed';
+    }
+  } else if (liveDomain !== expectedDomain) {
+    return 'required_monitor_domain_changed';
+  }
+  const subject = contact ? CONTACT_SUBJECT_FIELDS : COMPANY_SUBJECT_FIELDS;
+  const liveFilters = Object.fromEntries(
+    Object.entries(payload).filter(
+      ([key, value]) =>
+        !subject.has(key) &&
+        !NON_CONFIGURATION_FIELDS.has(key) &&
+        !absent(value),
+    ),
+  );
+  if (stableJson(liveFilters) !== stableJson(expected.filters)) {
+    return 'required_monitor_filters_changed';
+  }
+  return null;
+}
+
+/** The exact text whose SHA-256 is an approval's ID-set hash. */
+export function legacyIdSetDigestInput(radarIds: readonly string[]): string {
+  return [...radarIds].sort().join('\n');
+}
+
+const UUID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const RESOURCE_KEY_PATTERN = /(resource|radar|monitor)_id$/i;
+
+/**
+ * Every upstream radar a monitor definition names, in any binding slot:
+ * the promoted id, the live binding, a prior binding kept for cleanup, a
+ * creation attestation, or retired history. Over-collection only makes the
+ * retirement refuse more, so every UUID-shaped string counts too.
+ */
+export function definitionReferencedRadarIds(row: {
+  providerResourceId?: string | null;
+  providerBinding?: unknown;
+}): string[] {
+  const ids = new Set<string>();
+  const add = (value: unknown) => {
+    const text = nonEmptyText(value);
+    if (text) ids.add(text);
+  };
+  add(row.providerResourceId);
+  const visit = (value: unknown, key: string | null, depth: number) => {
+    if (depth > 12 || value === null || value === undefined) return;
+    if (typeof value === 'string') {
+      if (
+        UUID_PATTERN.test(value.trim()) ||
+        (key && RESOURCE_KEY_PATTERN.test(key))
+      )
+        add(value);
+      return;
+    }
+    if (Array.isArray(value)) {
+      for (const entry of value) visit(entry, key, depth + 1);
+      return;
+    }
+    if (typeof value === 'object') {
+      for (const [entryKey, entry] of Object.entries(
+        value as Record<string, unknown>,
+      ))
+        visit(entry, entryKey, depth + 1);
+    }
+  };
+  visit(row.providerBinding, null, 0);
+  return [...ids];
+}
+
+/** What the retirement needs to know about a required monitor right now. */
+export type LegacyRequiredMonitorFacts = {
+  orgId: string;
+  monitorKey: string;
+  status: string;
+  desired: string | null;
+  observed: string | null;
+  bindingVersion: string | null;
+  payload: unknown;
+};
+
+/** The monitor's current binding version as stored in a forward route. */
+export function legacyBindingVersionText(
+  providerBinding: unknown,
+): string | null {
+  const value = record(providerBinding)?.binding_version;
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+  return nonEmptyText(value);
+}
+
+/** Null when the required monitor covers the subject; otherwise the refusal. */
+export function legacyRequiredMonitorRefusal(input: {
+  approvalOrgId: string;
+  monitorKey: string;
+  facts: LegacyRequiredMonitorFacts | null;
+  expectedConfig: string | null;
+}): string | null {
+  const { facts } = input;
+  if (!facts) return 'required_monitor_missing';
+  if (
+    facts.orgId !== input.approvalOrgId ||
+    facts.monitorKey !== input.monitorKey
+  )
+    return 'required_monitor_wrong_org';
+  if (facts.status !== 'active') return 'required_monitor_not_active';
+  if (facts.desired !== 'active') return 'required_monitor_not_desired_active';
+  if (facts.observed !== 'active')
+    return 'required_monitor_not_observed_active';
+  if (!facts.bindingVersion) return 'required_monitor_unbound';
+  if (!input.expectedConfig) return 'required_monitor_expected_config_missing';
+  let expected: LegacyExpectedConfig;
+  try {
+    expected = parseLegacyExpectedConfig(input.expectedConfig);
+  } catch {
+    return 'required_monitor_expected_config_invalid';
+  }
+  return legacyMonitorConfigMismatch({ expected, payload: facts.payload });
+}
+
+export type LegacyRetirementItemState =
+  | 'approved'
+  | 'intent_recorded'
+  | 'retired'
+  | 'refused'
+  | 'withdrawn';
+
+export type LegacyRetirementPreflightItem = {
+  radarId: string;
+  phase: string;
+  state: LegacyRetirementItemState;
+  requiredMonitorKey?: string | null;
+  requiredMonitorExpectedConfig?: string | null;
+  requiredRouteAccountId?: string | null;
+  dependsOnRadarId?: string | null;
+  executionBlocker?: string | null;
+};
+
+/** States the retire action re-evaluates. Refusals are reports, not terminal. */
+export const LEGACY_RETIREMENT_SELECTABLE_STATES = [
+  'approved',
+  'refused',
+  'intent_recorded',
+] as const satisfies readonly LegacyRetirementItemState[];
+
+/**
+ * The action's checks, in order, before any bridge call. Null means the item
+ * may be sent to the bridge, which repeats the provider-side checks itself.
+ */
+export function legacyRetirementPreflightRefusal(input: {
+  approval: { status: string; orgId: string };
+  item: LegacyRetirementPreflightItem;
+  phase: string | null;
+  referencedRadarIds: ReadonlySet<string>;
+  keeper: LegacyRetirementPreflightItem | null;
+  monitorFacts: ReadonlyMap<string, LegacyRequiredMonitorFacts | null>;
+}): string | null {
+  const { approval, item } = input;
+  if (approval.status !== 'approved') return 'approval_not_sealed';
+  if (input.phase !== null && item.phase !== input.phase)
+    return 'phase_not_selected';
+  if (
+    !(LEGACY_RETIREMENT_SELECTABLE_STATES as readonly string[]).includes(
+      item.state,
+    )
+  )
+    return `item_${item.state}`;
+  if (input.referencedRadarIds.has(item.radarId))
+    return 'referenced_by_monitor_definition';
+  if (item.requiredMonitorKey) {
+    if (!item.requiredRouteAccountId) return 'required_route_account_missing';
+    const refusal = legacyRequiredMonitorRefusal({
+      approvalOrgId: approval.orgId,
+      monitorKey: item.requiredMonitorKey,
+      facts: input.monitorFacts.get(item.requiredMonitorKey) ?? null,
+      expectedConfig: item.requiredMonitorExpectedConfig ?? null,
+    });
+    if (refusal) return refusal;
+  }
+  if (item.dependsOnRadarId) {
+    // A duplicate carries its keeper's monitor and route itself, so the
+    // bridge proves that route before the delete; without them it would
+    // delete with no route check at all.
+    if (!item.requiredMonitorKey) return 'duplicate_required_monitor_missing';
+    if (!input.keeper) return 'keeper_not_in_approval';
+    if (input.keeper.state === 'withdrawn') return 'keeper_withdrawn';
+    if (!input.keeper.requiredMonitorKey) return 'keeper_has_no_monitor';
+    if (
+      input.keeper.requiredMonitorKey !== item.requiredMonitorKey ||
+      input.keeper.requiredRouteAccountId !== item.requiredRouteAccountId
+    )
+      return 'keeper_coverage_differs';
+    const keeperRefusal = legacyRequiredMonitorRefusal({
+      approvalOrgId: approval.orgId,
+      monitorKey: input.keeper.requiredMonitorKey,
+      facts: input.monitorFacts.get(input.keeper.requiredMonitorKey) ?? null,
+      expectedConfig: input.keeper.requiredMonitorExpectedConfig ?? null,
+    });
+    if (keeperRefusal) return `keeper_${keeperRefusal}`;
+  }
+  if (item.executionBlocker?.trim()) return 'execution_blocker';
+  return null;
+}

package/dist/bundling-sources/shared_libs/monitors/package.json

@@ -118,7 +118,11 @@
     "./tracking-provider-integrations": "./tracking-provider-integrations.ts",
     "./tracking-provider-integrations.js": "./tracking-provider-integrations.ts",
     "./validation": "./validation.ts",
-    "./validation.js": "./validation.ts"
+    "./validation.js": "./validation.ts",
+    "./legacy-radar-forward-routes": "./legacy-radar-forward-routes.ts",
+    "./legacy-radar-forward-routes.js": "./legacy-radar-forward-routes.ts",
+    "./legacy-radar-retirement": "./legacy-radar-retirement.ts",
+    "./legacy-radar-retirement.js": "./legacy-radar-retirement.ts"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json --noEmit",

package/dist/bundling-sources/shared_libs/observability/scheduled-jobs.json

@@ -1612,6 +1612,24 @@
     "failureAlert": "convex_action_wrapper",
     "domainReportRequired": true
   },
+  {
+    "id": "convex.customer-db-preparation",
+    "name": "Customer DB preparation",
+    "scheduler": "convex_scheduled_action",
+    "cadence": "on demand after account or workspace creation",
+    "timezone": "UTC",
+    "source": "packages/convex/scheduledJobsNode.ts",
+    "locator": "prepareCustomerDb",
+    "owner": "runtime",
+    "criticality": "critical",
+    "purpose": "Prepare one newly created workspace's Customer DB through its durable cold-start intent and signed deployment-pinned callback.",
+    "successDefinition": "The exact org-scoped callback confirms readiness or an existing active/deleted/archived workspace is safely skipped.",
+    "failureDefinition": "Preparation fails, its callback is unavailable, or the result does not confirm the durable request identity.",
+    "startGraceMs": 120000,
+    "runTimeoutMs": 180000,
+    "failureAlert": "convex_action_wrapper",
+    "domainReportRequired": true
+  },
   {
     "id": "convex.sql-listener-dispatch-retry",
     "name": "SQL-listener dispatch retry",

package/dist/bundling-sources/shared_libs/play-runtime/runtime-array-input-receipts.ts

@@ -421,11 +421,18 @@ export async function getRuntimeArrayInputManifest(
   const scope = runtimeArrayInputScope(port, input);
   const keys = runtimeArrayInputKeys(scope);
   return await port.withClient(async (client) => {
-    const guard = await readArrayInputFact(
-      client,
-      port.table,
-      arrayInputRunGuardKey(port, scope.runId),
+    const guardKey = arrayInputKeyHex(arrayInputRunGuardKey(port, scope.runId));
+    const beginKey = arrayInputKeyHex(keys.begin);
+    const sealKey = arrayInputKeyHex(keys.seal);
+    // These three immutable facts share a scope. One bounded PK lookup avoids
+    // serial database round trips while retaining every historical validation.
+    const { rows } = await client.query<ArrayInputReceiptRow & { key: string }>(
+      `SELECT encode(k, 'hex') AS key, status, run_id, output FROM ${port.table}
+       WHERE k IN (decode($1, 'hex'), decode($2, 'hex'), decode($3, 'hex'))`,
+      [guardKey, beginKey, sealKey],
     );
+    const facts = new Map(rows.map((row) => [row.key, row]));
+    const guard = facts.get(guardKey);
     if (guard) {
       const state = requireArrayInputFact(
         guard,
@@ -436,7 +443,7 @@ export async function getRuntimeArrayInputManifest(
         throw new Error('Runtime array input run is retired.');
       }
     }
-    const begin = await readArrayInputFact(client, port.table, keys.begin);
+    const begin = facts.get(beginKey);
     if (!begin) return { state: 'absent' };
     const manifest = requireArrayInputFact(
       begin,
@@ -448,7 +455,7 @@ export async function getRuntimeArrayInputManifest(
     if (typeof manifest.hasSourceIdentities !== 'boolean') {
       throw new Error('Runtime array input begin identity flag is corrupt.');
     }
-    const seal = await readArrayInputFact(client, port.table, keys.seal);
+    const seal = facts.get(sealKey);
     if (!seal)
       return {
         state: 'staging',

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backend.ts

@@ -268,6 +268,8 @@ export type PlaySchedulerRunHandle = {
    */
   observe(options?: {
     signal?: AbortSignal;
+    /** Briefly poll terminal state more often for an interactive start stream. */
+    startupPolling?: boolean;
   }): AsyncIterable<PlaySchedulerProgressEvent>;
   /**
    * Cooperatively cancel the run. Resolves with the scheduler's typed