@inflexa-ai/harness 0.30.2 → 0.31.0

package/dist/sandbox/k8s-client.js

@@ -16,6 +16,8 @@ import { BatchV1Api, CoreV1Api, KubeConfig, } from "@kubernetes/client-node";
 import { ResultAsync, err, ok } from "neverthrow";
 import { trySandbox } from "./sandbox-error.js";
 import { buildMountPlan, buildSessionSubPaths } from "./mount-plan.js";
+import { threadLimitEnv } from "./thread-env.js";
+import { CPU_ONLINE_PATH, CPUINFO_PATH, cpuFiles, readHostCpuinfoOnce } from "./cpu-files.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 /** Read the originating HTTP status off any `SandboxError` variant that carries one. */
 function statusOf(e) {
@@ -24,6 +26,8 @@ function statusOf(e) {
 const SESSION_VOLUME_NAME = "session";
 const LIBS_VOLUME_NAME = "libs";
 const REFS_VOLUME_NAME = "refs";
+/** The ConfigMap volume that holds the two cpu files of the sandbox (`cpu-files.ts`). */
+const CPU_VOLUME_NAME = "cpu";
 const SANDBOX_SERVER_PORT = 8765;
 const POD_READY_TIMEOUT_MS = 5 * 60_000;
 const POD_POLL_INTERVAL_MS = 1_000;
@@ -59,6 +63,19 @@ export function sanitizeLabelValue(value) {
 function readOwnerWorkflowId(metadata) {
     return metadata?.annotations?.[OWNER_WORKFLOW_ANNOTATION] ?? null;
 }
+function deleteConfigMapIgnoreMissing(coreApi, namespace, name) {
+    return trySandbox(async () => {
+        await coreApi.deleteNamespacedConfigMap({ namespace, name });
+    }, (status, cause) => ({
+        type: "teardown_failed",
+        op: "k8s.teardown",
+        sandboxId: name,
+        status,
+        cause,
+    })).orElse((e) => 
+    // A 404 means the owner reference removed it with the Job already.
+    statusOf(e) === 404 ? ok(undefined) : err(e));
+}
 function deleteJobIgnoreMissing(batchApi, namespace, name) {
     return trySandbox(async () => {
         await batchApi.deleteNamespacedJob({
@@ -107,31 +124,32 @@ function workspaceSubPathFor(config, analysisId) {
     }
     return posix;
 }
-function buildJobSpec(meta, config, identity) {
+function buildJobSpec(meta, config, identity, cpu) {
     const { sandboxId } = identity;
     const plan = buildMountPlan(meta, {
         libs: !!config.libStorePvc,
         refs: !!config.refStorePvc,
     });
     const transport = config.transport ?? "poll";
-    const env = [
-        { name: "SANDBOX_TRANSPORT", value: transport },
+    const spec = meta.resources;
+    // Composed as one record, not as a list of `{name, value}`. A duplicate name
+    // in the env of a container resolves at the kubelet, thus the later spread
+    // must win here, not there.
+    const env = Object.entries({
+        SANDBOX_TRANSPORT: transport,
         // Poll mode never dials out, so the URL is omitted (matching the Docker
         // backend) — the pod spec itself then documents that no callback egress
         // is expected. sandbox-server neither reads nor requires it in poll mode.
-        ...(transport === "callback" ? [{ name: "CORTEX_BASE_URL", value: config.cortexBaseUrl }] : []),
-        { name: "SANDBOX_CALLBACK_SECRET", value: identity.callbackSecret },
-        ...Object.entries(plan.env).map(([name, value]) => ({ name, value })),
-        ...Object.entries(meta.extraEnv ?? {}).map(([k, v]) => ({
-            name: k,
-            value: v,
-        })),
-    ];
+        ...(transport === "callback" ? { CORTEX_BASE_URL: config.cortexBaseUrl } : {}),
+        SANDBOX_CALLBACK_SECRET: identity.callbackSecret,
+        ...threadLimitEnv(spec),
+        ...plan.env,
+        ...(meta.extraEnv ?? {}),
+    }).map(([name, value]) => ({ name, value }));
     // requests == limits → Guaranteed QoS and a predictable OOM bound; also
     // satisfies the namespace ResourceQuota, which rejects any pod that omits
     // requests.cpu/memory. The CPU limit can throttle a hot step, but a throttle
     // beats an eviction.
-    const spec = meta.resources;
     const quantities = {
         cpu: String(spec.cpu),
         memory: `${spec.memoryGb}Gi`,
@@ -187,6 +205,16 @@ function buildJobSpec(meta, config, identity) {
             readOnly: true,
         });
     }
+    // The cpu files ride in a ConfigMap named after the Job (`ensureCpuConfigMap`).
+    // A `subPath` mount of one key over one kernel path is accepted by the API
+    // server, the kubelet, and gVisor. Under gVisor the sandbox sees no cgroup
+    // at all, thus these two files are the only source of the quota for
+    // `parallel::detectCores()` and `os.cpu_count()`.
+    volumes.push({ name: CPU_VOLUME_NAME, configMap: { name: sandboxId } });
+    volumeMounts.push({ name: CPU_VOLUME_NAME, mountPath: CPU_ONLINE_PATH, subPath: "online", readOnly: true });
+    if (cpu.hasCpuinfo) {
+        volumeMounts.push({ name: CPU_VOLUME_NAME, mountPath: CPUINFO_PATH, subPath: "cpuinfo", readOnly: true });
+    }
     const podSpec = {
         automountServiceAccountToken: false,
         restartPolicy: "Never",
@@ -357,6 +385,9 @@ function waitForJobGone(batchApi, namespace, name) {
  * means an (astronomically rare) name collision with a *different* step —
  * adopting its pod would HMAC-fail every callback, and deleting its Job would
  * kill a live sibling. Refuse loudly instead.
+ *
+ * The result is the uid of the Job that the pod belongs to, for the owner
+ * reference of the cpu ConfigMap.
  */
 function createOrAdoptJob(batchApi, coreApi, namespace, sandboxId, ownerWorkflowId, job) {
     const createFailed = (status, cause) => ({
@@ -369,7 +400,7 @@ function createOrAdoptJob(batchApi, coreApi, namespace, sandboxId, ownerWorkflow
     return new ResultAsync((async () => {
         const created = await trySandbox(() => batchApi.createNamespacedJob({ namespace, body: job }), createFailed);
         if (created.isOk())
-            return ok(undefined);
+            return ok(created.value?.metadata?.uid);
         if (statusOf(created.error) !== 409)
             return err(created.error);
         const existingRead = await trySandbox(() => batchApi.readNamespacedJob({ namespace, name: sandboxId }), createFailed);
@@ -397,20 +428,92 @@ function createOrAdoptJob(batchApi, coreApi, namespace, sandboxId, ownerWorkflow
             const recreated = await trySandbox(() => batchApi.createNamespacedJob({ namespace, body: job }), createFailed);
             if (recreated.isErr())
                 return err(recreated.error);
+            return ok(recreated.value?.metadata?.uid);
         }
+        return ok(existingRead.value.metadata?.uid);
+    })());
+}
+/**
+ * Make the cpu ConfigMap of a Job, or bring an existing one up to date.
+ *
+ * The ConfigMap comes after the Job, because the Job is its owner. Thus the
+ * TTL of the Job and a Foreground delete both remove the ConfigMap with it.
+ * The pod waits at its mount until the ConfigMap exists, and that wait is
+ * shorter than the schedule of the pod.
+ *
+ * A `409 AlreadyExists` is the recovery re-run of the spawn step, or a
+ * ConfigMap whose prior owner Job is not yet collected. Both cases get the
+ * same data and the current owner through a replace.
+ */
+function ensureCpuConfigMap(coreApi, namespace, sandboxId, jobUid, files) {
+    const createFailed = (status, cause) => ({
+        type: "container_create_failed",
+        op: "k8s.createNamespacedConfigMap",
+        sandboxId,
+        status,
+        cause,
+    });
+    const body = {
+        apiVersion: "v1",
+        kind: "ConfigMap",
+        metadata: {
+            name: sandboxId,
+            namespace,
+            labels: {
+                [MANAGED_BY_LABEL]: MANAGED_BY_VALUE,
+                role: "sandbox",
+                "cortex/sandbox-id": sandboxId,
+            },
+            ...(jobUid !== undefined && {
+                ownerReferences: [{ apiVersion: "batch/v1", kind: "Job", name: sandboxId, uid: jobUid }],
+            }),
+        },
+        data: {
+            online: files.online,
+            ...(files.cpuinfo !== undefined && { cpuinfo: files.cpuinfo }),
+        },
+    };
+    return new ResultAsync((async () => {
+        const created = await trySandbox(() => coreApi.createNamespacedConfigMap({ namespace, body }), createFailed);
+        if (created.isOk())
+            return ok(undefined);
+        if (statusOf(created.error) !== 409)
+            return err(created.error);
+        const existing = await trySandbox(() => coreApi.readNamespacedConfigMap({ namespace, name: sandboxId }), createFailed);
+        if (existing.isErr())
+            return err(existing.error);
+        const replaced = await trySandbox(() => coreApi.replaceNamespacedConfigMap({
+            namespace,
+            name: sandboxId,
+            body: { ...body, metadata: { ...body.metadata, resourceVersion: existing.value.metadata?.resourceVersion } },
+        }), createFailed);
+        if (replaced.isErr())
+            return err(replaced.error);
         return ok(undefined);
     })());
 }
 export function createK8sSandboxOps(config) {
     const { batchApi, coreApi } = config.batchApi && config.coreApi ? { batchApi: config.batchApi, coreApi: config.coreApi } : buildKubeApi();
+    const readHostCpuinfo = config.readHostCpuinfo ?? readHostCpuinfoOnce;
     return {
         createSandbox(meta, identity) {
             return new ResultAsync((async () => {
                 const { sandboxId } = identity;
-                const job = buildJobSpec(meta, config, identity);
+                // The same floor as `threadLimitEnv`: a fraction of a core still
+                // keeps one thread busy, and a count of zero is not representable.
+                const threads = Math.max(1, Math.floor(meta.resources.cpu));
+                const files = cpuFiles(threads, await readHostCpuinfo());
+                const job = buildJobSpec(meta, config, identity, { hasCpuinfo: files.cpuinfo !== undefined });
                 const adopted = await createOrAdoptJob(batchApi, coreApi, config.namespace, sandboxId, meta.childWorkflowId, job);
                 if (adopted.isErr())
                     return err(adopted.error);
+                const cpuMap = await ensureCpuConfigMap(coreApi, config.namespace, sandboxId, adopted.value, files);
+                if (cpuMap.isErr()) {
+                    // A pod whose ConfigMap never comes stays at ContainerCreating
+                    // until the ready wait expires. Fail now, with the real cause.
+                    await cleanupFailedJob(batchApi, coreApi, config.namespace, sandboxId, config.logger ?? createNoopLogger());
+                    return err(cpuMap.error);
+                }
                 // A Job whose pod never schedules (quota rejection, no nodes, spot
                 // reclaim) is reaped by neither backoffLimit (an admission rejection
                 // creates no pod to count) nor ttlSecondsAfterFinished (the Job never
@@ -434,20 +537,22 @@ export function createK8sSandboxOps(config) {
                         cause,
                     }));
                     if (registered.isErr()) {
-                        await cleanupFailedJob(batchApi, config.namespace, sandboxId, config.logger ?? createNoopLogger());
+                        await cleanupFailedJob(batchApi, coreApi, config.namespace, sandboxId, config.logger ?? createNoopLogger());
                         return err(registered.error);
                     }
                     return ok(ref);
                 }
-                await cleanupFailedJob(batchApi, config.namespace, sandboxId, config.logger ?? createNoopLogger());
+                await cleanupFailedJob(batchApi, coreApi, config.namespace, sandboxId, config.logger ?? createNoopLogger());
                 return err(ready.error);
             })());
         },
+        // The owner reference removes the cpu ConfigMap with the Job. The explicit
+        // delete covers a ConfigMap that got no owner, and it is a no-op on 404.
         teardown(ref) {
-            return deleteJobIgnoreMissing(batchApi, config.namespace, ref.sandboxId);
+            return deleteJobIgnoreMissing(batchApi, config.namespace, ref.sandboxId).andThen(() => deleteConfigMapIgnoreMissing(coreApi, config.namespace, ref.sandboxId));
         },
         teardownById(sandboxId) {
-            return deleteJobIgnoreMissing(batchApi, config.namespace, sandboxId);
+            return deleteJobIgnoreMissing(batchApi, config.namespace, sandboxId).andThen(() => deleteConfigMapIgnoreMissing(coreApi, config.namespace, sandboxId));
         },
         listManagedSandboxes() {
             return trySandbox(() => batchApi.listNamespacedJob({
@@ -508,9 +613,13 @@ export function createK8sSandboxOps(config) {
  * matters; a delete error here is logged and swallowed so it never masks the
  * create error returned to the caller.
  */
-async function cleanupFailedJob(batchApi, namespace, sandboxId, logger) {
+async function cleanupFailedJob(batchApi, coreApi, namespace, sandboxId, logger) {
     const deleted = await deleteJobIgnoreMissing(batchApi, namespace, sandboxId);
     if (deleted.isErr()) {
         logger.named("k8s-client").error("failed to delete Job after startup failure", { sandboxId, err: deleted.error });
     }
+    const deletedMap = await deleteConfigMapIgnoreMissing(coreApi, namespace, sandboxId);
+    if (deletedMap.isErr()) {
+        logger.named("k8s-client").error("failed to delete cpu ConfigMap after startup failure", { sandboxId, err: deletedMap.error });
+    }
 }

package/dist/sandbox/thread-env.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Thread-count env for a sandbox container.
+ *
+ * Each backend turns the `ResourceSpec` of a step into a hard cgroup limit:
+ * `NanoCpus` and `Memory` on Docker, `limits.cpu` and `limits.memory` on K8s. A
+ * cgroup quota is invisible to most runtimes inside it. `parallel::detectCores()`
+ * greps `/proc/cpuinfo`, and `os.cpu_count()` reads
+ * `/sys/devices/system/cpu/online`. Both files describe the host. Thus a step
+ * with 2 CPUs on a host of 12 cores forks 12 workers into a cgroup of 2 CPUs,
+ * and each fork copies its working set until the memory limit stops it.
+ *
+ * The env below publishes the quota to each library that reads a thread count
+ * from the environment. `parallelly::availableCores()` and `joblib.cpu_count()`
+ * read the cgroup quota on their own, thus they need no value here.
+ *
+ * `MC_CORES` is absent on purpose. R defaults `mclapply` to 2 workers, not to
+ * the core count. A value there raises the fork count instead of a decrease.
+ */
+import type { ResourceSpec } from "../config/resource-limits.js";
+/**
+ * Env that binds each parallel library in the container to `spec.cpu`.
+ *
+ * A fractional CPU request floors to one thread. A pool of zero is not
+ * representable, and two threads on half a core only add context switches.
+ *
+ * The caller puts these before `plan.env` and before the `extraEnv` of the
+ * embedder, thus a host that knows more about a step keeps the last word.
+ */
+export declare function threadLimitEnv(spec: ResourceSpec): Record<string, string>;

package/dist/sandbox/thread-env.js

@@ -0,0 +1,49 @@
+/**
+ * Thread-count env for a sandbox container.
+ *
+ * Each backend turns the `ResourceSpec` of a step into a hard cgroup limit:
+ * `NanoCpus` and `Memory` on Docker, `limits.cpu` and `limits.memory` on K8s. A
+ * cgroup quota is invisible to most runtimes inside it. `parallel::detectCores()`
+ * greps `/proc/cpuinfo`, and `os.cpu_count()` reads
+ * `/sys/devices/system/cpu/online`. Both files describe the host. Thus a step
+ * with 2 CPUs on a host of 12 cores forks 12 workers into a cgroup of 2 CPUs,
+ * and each fork copies its working set until the memory limit stops it.
+ *
+ * The env below publishes the quota to each library that reads a thread count
+ * from the environment. `parallelly::availableCores()` and `joblib.cpu_count()`
+ * read the cgroup quota on their own, thus they need no value here.
+ *
+ * `MC_CORES` is absent on purpose. R defaults `mclapply` to 2 workers, not to
+ * the core count. A value there raises the fork count instead of a decrease.
+ */
+/**
+ * Env that binds each parallel library in the container to `spec.cpu`.
+ *
+ * A fractional CPU request floors to one thread. A pool of zero is not
+ * representable, and two threads on half a core only add context switches.
+ *
+ * The caller puts these before `plan.env` and before the `extraEnv` of the
+ * embedder, thus a host that knows more about a step keeps the last word.
+ */
+export function threadLimitEnv(spec) {
+    const threads = String(Math.max(1, Math.floor(spec.cpu)));
+    return {
+        // OpenMP: the compiled code of R and Python packages.
+        OMP_NUM_THREADS: threads,
+        // OpenBLAS keeps a private pool. A pthread build reads this name first.
+        OPENBLAS_NUM_THREADS: threads,
+        // MKL reads this name before OMP_NUM_THREADS.
+        MKL_NUM_THREADS: threads,
+        // BiocParallel sizes `bpparam()` from this name. DESeq2 `parallel=TRUE`
+        // and the other Bioconductor packages size their workers from `bpparam()`.
+        BIOCPARALLEL_WORKER_NUMBER: threads,
+        // data.table defaults to half of the host cores.
+        R_DATATABLE_NUM_THREADS: threads,
+        // The Python numerical stack.
+        NUMBA_NUM_THREADS: threads,
+        NUMEXPR_MAX_THREADS: threads,
+        LOKY_MAX_CPU_COUNT: threads,
+        POLARS_MAX_THREADS: threads,
+        RAYON_NUM_THREADS: threads,
+    };
+}

package/dist/state/data-profile.d.ts

@@ -171,6 +171,41 @@ export declare function reconcileOrphanedDataProfile(pool: Querier, analysisId:
  * finds no running row to stamp and no-ops instead of re-seeding the cleared one.
  */
 export declare function clearDataProfile(pool: Querier, analysisId: string): ResultAsync<boolean, DbError>;
+/**
+ * Stamp a row `completed` with no result, because the analysis has no input files.
+ *
+ * A profile describes files. An analysis with no files has nothing to describe, and
+ * thus the profile is complete at once: no claim into `running`, no workflow, and no
+ * sandbox. The write is a terminal write like {@link completeDataProfile}, but it starts
+ * from a settled row or an empty row, not from a `running` one. As a result
+ * `data_profile_started_at` and `data_profile_completed_at` carry the same instant, and
+ * `data_profile_workflow_id` stays NULL, because no stream is addressable (see
+ * {@link recordDataProfileWorkflowId}).
+ *
+ * The seed is written as `[]`, so the completed row names the set that it covers: the
+ * empty set. A `completed` row with a NULL seed stays forbidden (see
+ * {@link completeDataProfile}). A prior `data_profile_result` is replaced with NULL,
+ * because it describes files that the analysis no longer has. A prior `failed` row is
+ * replaced too, because the set that failed is gone.
+ *
+ * Two guards ride in the CAS:
+ * - `IS DISTINCT FROM 'running'`: a live workflow owns the row, and its terminal write
+ *   must not land on a row that this write moved. The same reason as
+ *   {@link clearDataProfile}.
+ * - {@link UNSEEDED}: the row names no file. A seed upsert that lands between a caller's
+ *   pre-read and this write makes the row a seeded, startable row. A `completed` stamp
+ *   over it would hide those files behind a finished profile. The CAS refuses that row,
+ *   and the caller reads the status again to name the cause.
+ *
+ * The rerun claim carries {@link SEEDED}, so a completed-empty row is not claimable until
+ * a later seed upsert names files. Then `tryRerunDataProfile` takes it, the same as any
+ * completed row.
+ *
+ * `ok(true)` when this call stamped the row. `ok(false)` when the guard refused it: no
+ * such analysis, a live run, or a seed that names files. A refusal stays in the ok
+ * channel, the same as the sibling CAS ops.
+ */
+export declare function completeEmptyDataProfile(pool: Querier, analysisId: string): ResultAsync<boolean, DbError>;
 /**
  * Load an analysis's data-profile ledger state. Returns `null` for BOTH miss
  * conditions, deliberately indistinguishable to consumers:

package/dist/state/data-profile.js

@@ -20,6 +20,13 @@ import { tryMutation, tryQuery } from "../lib/db-result.js";
  * and surfacing a hand-corrupted row as a `DbError` beats silently claiming it.
  */
 const SEEDED = "seed_input_file_ids IS NOT NULL AND jsonb_array_length(seed_input_file_ids) > 0";
+/**
+ * The negation of {@link SEEDED}: the row names no input file. A NULL seed and `[]`
+ * both name zero files, and {@link completeEmptyDataProfile} treats them the same.
+ * The two predicates are disjoint, so a claim into `running` and an empty-set
+ * completion can never both win on one row.
+ */
+const UNSEEDED = "(seed_input_file_ids IS NULL OR jsonb_array_length(seed_input_file_ids) = 0)";
 /**
  * Try to claim a startable row into `running`. Startable means `'pending'` (seeded,
  * not yet run) or NULL (no profile: never profiled, or cleared by `clearDataProfile`).
@@ -279,6 +286,55 @@ export function clearDataProfile(pool, analysisId) {
         return (result.rowCount ?? 0) > 0;
     });
 }
+/**
+ * Stamp a row `completed` with no result, because the analysis has no input files.
+ *
+ * A profile describes files. An analysis with no files has nothing to describe, and
+ * thus the profile is complete at once: no claim into `running`, no workflow, and no
+ * sandbox. The write is a terminal write like {@link completeDataProfile}, but it starts
+ * from a settled row or an empty row, not from a `running` one. As a result
+ * `data_profile_started_at` and `data_profile_completed_at` carry the same instant, and
+ * `data_profile_workflow_id` stays NULL, because no stream is addressable (see
+ * {@link recordDataProfileWorkflowId}).
+ *
+ * The seed is written as `[]`, so the completed row names the set that it covers: the
+ * empty set. A `completed` row with a NULL seed stays forbidden (see
+ * {@link completeDataProfile}). A prior `data_profile_result` is replaced with NULL,
+ * because it describes files that the analysis no longer has. A prior `failed` row is
+ * replaced too, because the set that failed is gone.
+ *
+ * Two guards ride in the CAS:
+ * - `IS DISTINCT FROM 'running'`: a live workflow owns the row, and its terminal write
+ *   must not land on a row that this write moved. The same reason as
+ *   {@link clearDataProfile}.
+ * - {@link UNSEEDED}: the row names no file. A seed upsert that lands between a caller's
+ *   pre-read and this write makes the row a seeded, startable row. A `completed` stamp
+ *   over it would hide those files behind a finished profile. The CAS refuses that row,
+ *   and the caller reads the status again to name the cause.
+ *
+ * The rerun claim carries {@link SEEDED}, so a completed-empty row is not claimable until
+ * a later seed upsert names files. Then `tryRerunDataProfile` takes it, the same as any
+ * completed row.
+ *
+ * `ok(true)` when this call stamped the row. `ok(false)` when the guard refused it: no
+ * such analysis, a live run, or a seed that names files. A refusal stays in the ok
+ * channel, the same as the sibling CAS ops.
+ */
+export function completeEmptyDataProfile(pool, analysisId) {
+    const now = new Date().toISOString();
+    return tryMutation("dataProfile.completeEmptyDataProfile", async () => {
+        const result = await pool.query({
+            text: `UPDATE cortex_analysis_state
+            SET data_profile_status = 'completed', data_profile_error = NULL,
+                data_profile_started_at = $1, data_profile_completed_at = $1,
+                data_profile_result = NULL, data_profile_workflow_id = NULL,
+                seed_input_file_ids = '[]'::jsonb
+            WHERE analysis_id = $2 AND data_profile_status IS DISTINCT FROM 'running' AND ${UNSEEDED}`,
+            values: [now, analysisId],
+        });
+        return (result.rowCount ?? 0) > 0;
+    });
+}
 /**
  * Load an analysis's data-profile ledger state. Returns `null` for BOTH miss
  * conditions, deliberately indistinguishable to consumers:

package/dist/state/index.d.ts

@@ -20,7 +20,7 @@ export { setSandboxRef, setActiveExecId, clearSandboxRef, queryActiveSandboxes,
 export type { ActiveSandboxRow } from "./active-sandboxes.js";
 export { insertPlan, upsertPlan, loadPlan } from "./plans.js";
 export type { InsertPlanInput, UpsertPlanInput } from "./plans.js";
-export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
+export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, completeEmptyDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
 export type { DataProfileStatus, DataProfileResult, DataProfileChecked, DataProfileCompanionCompleteness, DataProfileDimension, DataProfileGroup, DataProfileGroupSlot, DataProfileFile, DataProfileMemberAnnotation, DataProfileObservation, DataProfilePartition, DataProfileProbeReport, DataProfileQualityAssessment, DataProfileQuarantine, DataProfileRecipeStep, DataProfileKind, DataProfileAxis, DataProfileInputSignature, DataProfileCoverage, } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
 export { createAnalysisPurge } from "./purge-analysis.js";

package/dist/state/index.js

@@ -14,7 +14,7 @@ setRunSynthesisOutcome, queryRun, queryActiveRun, queryNonTerminalRunsByAnalysis
 export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";
 export { setSandboxRef, setActiveExecId, clearSandboxRef, queryActiveSandboxes, reconcileReapedSandbox } from "./active-sandboxes.js";
 export { insertPlan, upsertPlan, loadPlan } from "./plans.js";
-export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
+export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, completeEmptyDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
 // Not per-entity: one analysis's whole Postgres footprint, reached from its id
 // alone, with the workflow ledger behind an injected seam.

package/dist/tasks/data-profile.d.ts

@@ -132,7 +132,16 @@ export declare function registerDataProfileWorkflow(deps: DataProfileDeps): (inp
  * 'failed' on error, and revokes the run authorization on every terminal path.
  */
 export declare function runDataProfileBody(input: DataProfileWorkflowInput, deps: DataProfileDeps): Promise<void>;
-export type DataProfileTriggerResult = "started" | "restarted" | "already_running" | "failed";
+/**
+ * What the trigger did:
+ * - `"started"`: a first profile claimed the row and a workflow runs.
+ * - `"restarted"`: a re-profile claimed a `completed` row and a workflow runs.
+ * - `"already_running"`: a workflow already owns the row, and nothing new ran.
+ * - `"completed"`: the analysis has no input files, so the row is `completed` at once
+ *   with no result. No workflow ran (see {@link completeEmptyDataProfile}).
+ * - `"failed"`: the trigger refused the call or faulted, and the row is unchanged.
+ */
+export type DataProfileTriggerResult = "started" | "restarted" | "already_running" | "completed" | "failed";
 /**
  * Route-side deps for triggering the data-profile workflow: the ledger pool,
  * the run authorizer, and the registered workflow callable. The body's
@@ -188,6 +197,12 @@ export declare function dataProfileWorkflowId(analysisId: string, nonce: string)
  * row is claimed by neither: retrying a failure is a deliberate act the caller drives
  * through `tryRetryDataProfile` + `runDataProfile`.
  *
+ * An analysis with no input files takes none of the claims. An empty manifest against
+ * a seed that names no file stamps the row `completed` at once, with no result and no
+ * workflow (see {@link completeEmptyDataProfile}), and the trigger returns
+ * `"completed"`. An empty manifest against a seed that names files is a divergence
+ * between the caller and the ledger, and the trigger refuses it.
+ *
  * Returns what happened, so the caller can surface it (e.g. in the seed response).
  */
 export declare function triggerDataProfile(deps: DataProfileTriggerDeps, params: DataProfileTriggerParams): Promise<DataProfileTriggerResult>;

package/dist/tasks/data-profile.js

@@ -44,7 +44,7 @@ import { scanInputTree } from "../input-scan/scan.js";
 import { PROFILE_INDEX_TYPES, buildProfileIndexEntries } from "./data-profile-index.js";
 import { absorbRecipe, renderAbsorbDelta } from "./data-profile-absorb.js";
 import { formatResolutionErrors, resolveProfileSubmission } from "./data-profile-resolve.js";
-import { completeDataProfile, failDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, tryRerunDataProfile, tryStartDataProfile, upsertArtifacts, } from "../state/index.js";
+import { completeDataProfile, completeEmptyDataProfile, failDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, tryRerunDataProfile, tryStartDataProfile, upsertArtifacts, } from "../state/index.js";
 import { createProfileActivityEmitter } from "./data-profile-activity.js";
 import { ensureSearchIndex, searchIndexName } from "../workspace/search-config.js";
 // The run literal is declared in `contracts/` — a consumer reads it back off recorded usage, and this
@@ -668,6 +668,12 @@ async function startDataProfileWorkflow(deps, params) {
  * row is claimed by neither: retrying a failure is a deliberate act the caller drives
  * through `tryRetryDataProfile` + `runDataProfile`.
  *
+ * An analysis with no input files takes none of the claims. An empty manifest against
+ * a seed that names no file stamps the row `completed` at once, with no result and no
+ * workflow (see {@link completeEmptyDataProfile}), and the trigger returns
+ * `"completed"`. An empty manifest against a seed that names files is a divergence
+ * between the caller and the ledger, and the trigger refuses it.
+ *
  * Returns what happened, so the caller can surface it (e.g. in the seed response).
  */
 export async function triggerDataProfile(deps, params) {
@@ -682,17 +688,32 @@ export async function triggerDataProfile(deps, params) {
         // `loadSeedInputFileIds`, which returns null for BOTH a missing analysis row and
         // a NULL-seed row (`loadDataProfileStatus` would hide the seed of a cleared row).
         const seeded = unwrapOrThrow(await loadSeedInputFileIds(deps.pool, analysisId));
-        if (seeded === null || seeded.length === 0) {
-            logger.error("trigger rejected: no seeded input set (missing analysis row or caller skipped seeding)");
+        if (params.stagedInputs.length === 0) {
+            // The trigger validates the manifest it is about to dispatch against the ledger
+            // seed. A seeded row profiled against an EMPTY manifest would claim `running` and
+            // then hit the body's empty-manifest path, and complete with a NULL result while
+            // the seed still names files. Refuse the divergence before any claim.
+            if (seeded !== null && seeded.length > 0) {
+                logger.error("trigger rejected: empty manifest dispatched against a non-empty seed", { seededCount: seeded.length });
+                return "failed";
+            }
+            // The analysis has no input files, so there is nothing to profile. The row is
+            // `completed` at once, with no workflow. The CAS carries the same seed
+            // predicate as this pre-read, so a seed upsert that lands in between cannot be
+            // hidden behind a finished profile: the stamp refuses, and the status read
+            // below names the cause.
+            if (unwrapOrThrow(await completeEmptyDataProfile(deps.pool, analysisId)))
+                return "completed";
+            const current = unwrapOrThrow(await loadDataProfileStatus(deps.pool, analysisId));
+            if (current?.status === "running")
+                return "already_running";
+            logger.error("trigger rejected: empty-set completion refused (no analysis row, or the seed now names files)");
             return "failed";
         }
-        // The trigger validates the ledger seed above; it must also validate the manifest
-        // it is about to dispatch. A seeded row profiled against an EMPTY manifest would
-        // claim `running` and then hit the body's empty-manifest path — completing with a
-        // NULL result while the seed still names files, an incoherence a staleness policy
-        // then loops on re-triggering. Refuse the divergence before any claim.
-        if (params.stagedInputs.length === 0) {
-            logger.error("trigger rejected: empty manifest dispatched against a non-empty seed", { seededCount: seeded.length });
+        // A non-empty manifest against a seed that names no file: the caller skipped the
+        // seed, or the analysis row is missing. Name the cause before any claim.
+        if (seeded === null || seeded.length === 0) {
+            logger.error("trigger rejected: no seeded input set (missing analysis row or caller skipped seeding)");
             return "failed";
         }
         const started = unwrapOrThrow(await tryStartDataProfile(deps.pool, analysisId));

package/dist/tools/bio/chembl.js

@@ -38,9 +38,10 @@ const inputSchema = z
         .describe("Which ChEMBL lookup to run; each names its params and return fields.\n" +
         "'compounds' (query + searchType) — molecules by target, name or SMILES: resolve a named compound to its ID and structure, or list " +
         "what was assayed against a target. → chemblId, preferredCompoundName, canonicalSmiles, molecularWeight, alogp, molecularFormula.\n" +
-        "'drug' (query) — the drug registry by drug name or indication: 'what treats X?', 'is Y approved, since when?'. → moleculeChemblId, " +
-        "preferredName, maxPhase (4 = approved), moleculeType, firstApproval, indication. If the drug endpoint is empty it falls back to a " +
-        "max_phase >= 4 molecule search, whose rows carry indication: null.\n" +
+        "'drug' (query) — approved drugs by indication or by drug name: 'what treats X?', 'is Y approved, since when?'. → moleculeChemblId, " +
+        "preferredName, maxPhase (4 = approved), moleculeType, firstApproval, indication. A disease term reads the curated indication " +
+        "registry, highest phase first; a query that matches no disease term reads the approved molecules (max_phase >= 4) instead, and " +
+        "their indications come back with them.\n" +
         "'mechanism' (chemblId, molecule only) — curated mechanism of ONE molecule: 'how does X work?'. → mechanismOfAction, actionType " +
         "(INHIBITOR, AGONIST, …), targetChemblId + targetName, moleculeChemblId. Curated mainly for clinical/approved molecules, so tool " +
         "compounds often have none.\n" +

package/dist/tools/bio/drug-gene-interactions.d.ts

@@ -18,7 +18,6 @@
  */
 import type { Logger } from "../../lib/logger.js";
 import { type DgidbResult } from "../lib/dgidb-client.js";
-import { type DrugResult } from "../lib/drugbank-client.js";
 import { type PharmgkbAnnotation } from "../lib/pharmgkb-client.js";
 declare const SOURCES: readonly ["dgidb", "drugbank", "pharmgkb"];
 type Source = (typeof SOURCES)[number];
@@ -30,26 +29,15 @@ interface SourceOutcome {
 }
 /**
  * A DrugBank record projected for context. `includeDrugRecord` decides whether
- * the five prose fields arrive whole or as previews — five 500-character fields
- * across ten records is 25k characters of narrative that a drug-vs-gene
- * question rarely needs.
+ * the description arrives whole or as a preview — a 500-character field across
+ * ten records is narrative that a drug-vs-gene question rarely needs.
  */
 interface ProjectedDrug {
     drugbankId: string;
     name: string;
     type: string;
     groups: string[];
-    categories: string[];
-    halfLife: string;
-    targets: DrugResult["targets"];
-    targetCount: number;
-    interactions: DrugResult["interactions"];
-    interactionCount: number;
     description: string;
-    indication: string;
-    pharmacodynamics: string;
-    mechanismOfAction: string;
-    toxicity: string;
     proseTruncated: boolean;
 }
 interface DrugGeneOutput {