@inflexa-ai/harness 0.35.2 → 0.35.4

package/dist/sandbox/package-identity.js

@@ -0,0 +1,244 @@
+/**
+ * The identity of a package, the query that asks for one, and the resolution
+ * between the two.
+ *
+ * A package name crosses the harness, the embedder, and the provisioner. As a
+ * bare `string` each site applies the rule that it believes, and two sites then
+ * disagree on whether `decoupleR` and `decoupler` are one package. This module
+ * is the one place that knows the rule.
+ *
+ * Two types carry the two ideas. A {@link PackageQuery} is what a person or an
+ * agent asked: a spelling, an optional track, an optional version. A
+ * {@link PackageIdentity} is the name that an ecosystem recognizes. The
+ * identity is opaque, thus a caller cannot invent one, and every identity comes
+ * from {@link pythonIdentity}, {@link rIdentity}, or {@link identityOf}.
+ *
+ * The PEP 503 fold lives in exactly one function of this file. The provisioner
+ * holds the Python twin, `images/sandbox-provisioner/package_identity.py`, and
+ * one fixture binds the two.
+ */
+import { err, ok } from "neverthrow";
+/**
+ * The PEP 503 fold: each run of `-`, `_`, and `.` becomes one `-`, and the
+ * case lowers. This is the ONE TypeScript home of the rule. The fold is
+ * idempotent, thus a fold of a folded name gives that name again.
+ */
+function fold(name) {
+    return name.replace(/[-_.]+/g, "-").toLowerCase();
+}
+/**
+ * Brand a name that a constructor of this module already ruled on.
+ *
+ * The cast is the whole point of the brand: the brand has no runtime value,
+ * thus only a cast can produce one, and this function is the one place that
+ * casts. A caller outside the module reaches a name through a constructor.
+ */
+function brand(name) {
+    // The brand is a compile-time marker with no runtime value, thus a cast is
+    // the only way to mint one, and this function is the only site that casts.
+    return name;
+}
+/**
+ * The Python identity of a spelling. The name folds, because PEP 503 makes
+ * `PyYAML`, `pyyaml`, and `py_yaml` one distribution.
+ *
+ * @param spelling The distribution name, as the caller spells it.
+ */
+export function pythonIdentity(spelling) {
+    return { track: "python", name: brand(fold(spelling)) };
+}
+/**
+ * The R identity of a name. The name keeps its spelling, because `library()`
+ * is case-sensitive and `GO.db` loads under that exact name.
+ *
+ * @param name The DESCRIPTION `Package` value.
+ */
+export function rIdentity(name) {
+    return { track: "r", name: brand(name) };
+}
+/**
+ * The identity of a name that an emitter already minted — a graph node, a lock
+ * row. The dispatch is safe over such a name, because the fold is idempotent.
+ *
+ * @param track The ecosystem that holds the name.
+ * @param name The name as the emitter wrote it.
+ */
+export function identityOf(track, name) {
+    return track === "python" ? pythonIdentity(name) : rIdentity(name);
+}
+/**
+ * The key of an identity: `<track>:<name>`. Two identities are equal when
+ * their keys are equal, thus a map of identities keys on this string.
+ */
+export function identityKey(identity) {
+    return `${identity.track}:${identity.name}`;
+}
+/**
+ * The identity that a key names, or `undefined` when the string is not a key.
+ *
+ * The FIRST colon splits the two halves. A track name holds no colon, and
+ * neither a PEP 503 name nor an R name can hold one, thus `r:GO.db` gives the
+ * R identity `GO.db`, dot and all. The name rides through {@link identityOf},
+ * and the fold is idempotent, thus a key that {@link identityKey} wrote comes
+ * back as the identity that wrote it.
+ *
+ * The key format is minted here, thus it is read here: a reader that splits
+ * the string itself owns a second copy of the format.
+ *
+ * @param key A `<track>:<name>` string, as {@link identityKey} writes it.
+ */
+export function parseIdentityKey(key) {
+    const at = key.indexOf(":");
+    if (at < 0)
+        return undefined;
+    const track = key.slice(0, at);
+    const name = key.slice(at + 1);
+    if (name === "")
+        return undefined;
+    if (track !== "python" && track !== "r")
+        return undefined;
+    return identityOf(track, name);
+}
+/**
+ * The store address of an identity: the PEP 503 fold of its name, for both
+ * tracks. A store directory is an address and not an identity, thus two
+ * identities can share one address — `r:decoupleR` and `python:decoupler`
+ * both address as `decoupler`. The pin marker inside the directory carries
+ * the identity.
+ */
+export function identityAddress(identity) {
+    return fold(identity.name);
+}
+/**
+ * A path, a URL, or a store directory. The entry is trimmed already, thus a
+ * leading space cannot defeat the guard.
+ */
+const LOCATION = /^[.~]|[/\\]|:\/\//;
+/** The `<word>:` prefix of an entry. The group holds the word before the colon. */
+const PREFIX = /^([A-Za-z][A-Za-z0-9_.-]*):/;
+/** A run of specifier characters. Only the exact run `==` names a version. */
+const SPECIFIER = /[<>!~=]+/;
+/**
+ * A run of characters that an exact version cannot hold: a specifier
+ * character, a comma, or whitespace. `SPECIFIER` reads the FIRST run only,
+ * thus `numpy==1.26,<2` gives the version `1.26,<2` without this guard, and
+ * the compound range then rides into the pool as a version string.
+ */
+const VERSION_INTRUDER = /[<>!~=,\s]+/;
+/**
+ * Read one entry of the grammar `[python:|r:]<spelling>[==<version>]`.
+ *
+ * The entry trims once, and the parts keep what the trim left. Every reader of
+ * the grammar in the harness calls this function: a second parser would
+ * disagree with this one, and the plan validation that passed would then meet
+ * a link pass that refuses.
+ *
+ * @param entry One package entry, as a plan, a tool call, or a host wrote it.
+ */
+export function parseQuery(entry) {
+    const trimmed = entry.trim();
+    if (trimmed === "")
+        return err({ type: "empty" });
+    if (LOCATION.test(trimmed))
+        return err({ type: "location", entry: trimmed });
+    const prefix = PREFIX.exec(trimmed);
+    const word = prefix?.[1];
+    if (word !== undefined && word !== "python" && word !== "r") {
+        return err({ type: "unknown_prefix", prefix: word, entry: trimmed });
+    }
+    const track = word === "python" ? "python" : word === "r" ? "r" : undefined;
+    const rest = track === undefined ? trimmed : trimmed.slice(track.length + 1);
+    if (rest === "")
+        return err({ type: "empty" });
+    const specifier = SPECIFIER.exec(rest);
+    if (specifier === null)
+        return ok({ spelling: rest, ...(track === undefined ? {} : { track }) });
+    if (specifier[0] !== "==") {
+        return err({ type: "unsupported_specifier", specifier: specifier[0], entry: trimmed });
+    }
+    // Both halves trim: `numpy == 1.26.4` is one ask, and an untrimmed half
+    // makes the spelling `numpy ` and the version ` 1.26.4`, neither of which
+    // any index holds.
+    const spelling = rest.slice(0, specifier.index).trim();
+    if (spelling === "")
+        return err({ type: "empty" });
+    // `name==` names no version, thus the query pins none and the pool answers
+    // the newest. The round-trip law holds, because `formatQuery` writes the
+    // specifier only beside a version.
+    const version = rest.slice(specifier.index + 2).trim();
+    const intruder = VERSION_INTRUDER.exec(version);
+    if (intruder !== null) {
+        return err({ type: "unsupported_specifier", specifier: intruder[0], entry: trimmed });
+    }
+    return ok({
+        spelling,
+        ...(track === undefined ? {} : { track }),
+        ...(version === "" ? {} : { version }),
+    });
+}
+/**
+ * Write a query in the grammar. The prefix rides only beside a track, and
+ * `==<version>` only beside a version. For every query,
+ * `parseQuery(formatQuery(query))` gives that query again.
+ */
+export function formatQuery(query) {
+    const prefix = query.track === undefined ? "" : `${query.track}:`;
+    const version = query.version === undefined ? "" : `==${query.version}`;
+    return `${prefix}${query.spelling}${version}`;
+}
+/**
+ * The sole R identity of the pool that folds to this fold, or none. Two such
+ * identities give no suggestion, because a guess between them is a coin flip.
+ */
+function soleRSuggestion(pool, spellingFold) {
+    const candidates = pool.rIdentitiesFoldingTo(spellingFold);
+    return candidates.length === 1 ? candidates[0] : undefined;
+}
+/**
+ * Resolve one query against a pool.
+ *
+ * The version takes no part, because the caller holds the versions: the graph
+ * orders them, and this function answers which package the query names.
+ *
+ * The ladder, in order:
+ *
+ * 1. The query names a track: the identity of that track, when the pool holds
+ *    it. Otherwise unknown, with the R suggestion when the track is `r`.
+ * 2. The pool holds the R identity of the spelling and the Python identity of
+ *    its fold: the R identity when the spelling differs from its fold, because
+ *    an uppercase letter or a dot is evidence of an R spelling. Otherwise
+ *    ambiguous.
+ * 3. The pool holds the R identity: the R identity.
+ * 4. The pool holds the Python identity: the Python identity.
+ * 5. Exactly one R identity of the pool folds to the fold of the spelling:
+ *    unknown, with that identity as the suggestion.
+ * 6. Otherwise: unknown.
+ *
+ * A silent Python-first pick is a fault: it sends `decoupleR` to the Python
+ * `decoupler`, and the R package never links.
+ */
+export function resolveQuery(query, pool) {
+    const spellingFold = fold(query.spelling);
+    if (query.track !== undefined) {
+        const identity = identityOf(query.track, query.spelling);
+        if (pool.has(identity))
+            return { kind: "resolved", identity };
+        if (query.track !== "r")
+            return { kind: "unknown" };
+        const suggestion = soleRSuggestion(pool, spellingFold);
+        return suggestion === undefined ? { kind: "unknown" } : { kind: "unknown", suggestion };
+    }
+    const r = rIdentity(query.spelling);
+    const python = pythonIdentity(query.spelling);
+    const holdsR = pool.has(r);
+    const holdsPython = pool.has(python);
+    if (holdsR && holdsPython) {
+        return query.spelling === spellingFold ? { kind: "ambiguous", python, r } : { kind: "resolved", identity: r };
+    }
+    if (holdsR)
+        return { kind: "resolved", identity: r };
+    if (holdsPython)
+        return { kind: "resolved", identity: python };
+    const suggestion = soleRSuggestion(pool, spellingFold);
+    return suggestion === undefined ? { kind: "unknown" } : { kind: "unknown", suggestion };
+}

package/dist/sandbox/reaper.js

@@ -21,9 +21,11 @@
  */
 import { DBOS } from "@dbos-inc/dbos-sdk";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { untracedWorkflow } from "../lib/otel-spans.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { reconcileReapedSandbox } from "../state/active-sandboxes.js";
 const REAPER_CRON = "0 */5 * * * *";
+const REAPER_WORKFLOW = "sandbox-reaper";
 const DEFAULT_GRACE_MS = 10 * 60_000;
 /**
  * Workflow statuses that mean "still owns its sandbox — never reap". Must
@@ -152,9 +154,10 @@ export function registerSandboxReaper(deps) {
             graceMs: deps.graceMs,
             logger: deps.logger,
         }), { name: "sandbox-reaper-sweep" });
-    }, { name: "sandbox-reaper" });
+    }, { name: REAPER_WORKFLOW });
+    untracedWorkflow(REAPER_WORKFLOW);
     DBOS.registerScheduled(reaper, {
-        name: "sandbox-reaper",
+        name: REAPER_WORKFLOW,
         crontab: REAPER_CRON,
     });
 }

package/dist/sandbox/submit-exec.js

@@ -17,6 +17,7 @@
  * untouched.
  */
 import { DBOS } from "@dbos-inc/dbos-sdk";
+import { ATTR_INFLEXA_EXEC_ID, stableSpan } from "../lib/otel-spans.js";
 import { EXEC_STREAM_BYTE_CAP } from "../tools/workspace/result-bounds.js";
 import { signCallback } from "./hmac.js";
 const SUBMIT_HTTP_TIMEOUT_MS = 30_000;
@@ -71,7 +72,9 @@ export async function submitExec(ref, body, deps = {}) {
         stdoutByteCap: body.stdoutByteCap ?? deps.execStreamByteCap ?? EXEC_STREAM_BYTE_CAP,
         stderrByteCap: body.stderrByteCap ?? deps.execStreamByteCap ?? EXEC_STREAM_BYTE_CAP,
     };
-    await runStep(() => postExec(fetchImpl, ref, capped), {
-        name: `sandbox.submit-exec.${body.execId}`,
-    });
+    const stepName = `sandbox.submit-exec.${body.execId}`;
+    await runStep(() => {
+        stableSpan(stepName, "sandbox.submit-exec", { [ATTR_INFLEXA_EXEC_ID]: body.execId });
+        return postExec(fetchImpl, ref, capped);
+    }, { name: stepName });
 }

package/dist/sandbox/types.d.ts

@@ -10,6 +10,7 @@
  */
 import { z } from "zod";
 import type { ResourceSpec } from "../config/resource-limits.js";
+import type { PackageQuery } from "./package-identity.js";
 export declare const SandboxBackend: z.ZodEnum<{
     docker: "docker";
     k8s: "k8s";
@@ -82,22 +83,12 @@ export type FarmSource = {
     readonly resolve: ResolveAnalysisFarm;
 };
 /**
- * One package ask of the farm-extension seam. `version` pins one exact
- * version. `ecosystem` qualifies a name that both tracks can hold. Without
- * it, a name that both tracks hold comes back as a `collision` outcome.
- */
-export interface PackageRequest {
-    readonly name: string;
-    readonly version?: string;
-    readonly ecosystem?: "python" | "r";
-}
-/**
- * One outcome per request, index-aligned with the request array.
+ * One outcome per query, index-aligned with the query array.
  *
- * `name` echoes the REQUESTED spelling verbatim, never a normalized form. A
- * caller quotes it into a remedy (`inflexa store add <name>`), and an R name
- * is case-sensitive with dots, thus a normalized echo would name a package
- * that no repository holds.
+ * `spelling` echoes the spelling of its query verbatim, never a normalized
+ * form. A caller quotes it into a remedy (`inflexa store add <spelling>`), and
+ * an R name is case-sensitive with dots, thus a normalized echo would name a
+ * package that no repository holds.
  *
  * - `linked` — the pool held the package, and this call linked it.
  * - `present` — the farm linked it already.
@@ -106,12 +97,13 @@ export interface PackageRequest {
  *   the realization gives one, classifies the miss in host terms — in
  *   flight, failed with a recorded reason, or never requested — and the
  *   launch refusal renders it beside the name.
- * - `collision` — the request resolves to two store directories: two
- *   versions of one distribution, or one name that both tracks hold. The
- *   outcome is terminal for the request. `detail`, when the realization
+ * - `collision` — the query resolves to two store directories: two
+ *   versions of one distribution, or one spelling that both tracks hold. The
+ *   outcome is terminal for the query. `detail`, when the realization
  *   gives one, names the two pins and the packages that need each side —
  *   without it, a caller must guess which package pulls each pin, and a
- *   wrong guess sends it into store surgery.
+ *   wrong guess sends it into store surgery. For one spelling in two tracks
+ *   the detail names the two identity keys instead.
  * - `unavailable` — the link pass itself could not answer: an unreadable
  *   dependency graph, a locked farm. The reason says why. It says NOTHING
  *   about the presence of the package, and it must never render as an
@@ -120,25 +112,25 @@ export interface PackageRequest {
  */
 export type PackageRequestOutcome = {
     readonly kind: "linked";
-    readonly name: string;
+    readonly spelling: string;
     readonly version: string;
 } | {
     readonly kind: "present";
-    readonly name: string;
+    readonly spelling: string;
     readonly version: string;
 } | {
     readonly kind: "absent";
-    readonly name: string;
+    readonly spelling: string;
     readonly acquisitionPossible: boolean;
     readonly detail?: string;
 } | {
     readonly kind: "collision";
-    readonly name: string;
+    readonly spelling: string;
     readonly storeDirs: readonly [string, string];
     readonly detail?: string;
 } | {
     readonly kind: "unavailable";
-    readonly name: string;
+    readonly spelling: string;
     readonly reason: string;
 };
 /**
@@ -146,8 +138,11 @@ export type PackageRequestOutcome = {
  * packages into the farm of the analysis. It never installs, downloads, or
  * acquires. A link is live in a sandbox that already runs, because the farm
  * rides a bind mount.
+ *
+ * The seam speaks the query of the `package-identity` capability, thus the
+ * host resolves the identity and the harness never folds a name.
  */
-export type ExtendAnalysisFarm = (analysisId: string, requests: readonly PackageRequest[]) => Promise<readonly PackageRequestOutcome[]>;
+export type ExtendAnalysisFarm = (analysisId: string, queries: readonly PackageQuery[]) => Promise<readonly PackageRequestOutcome[]>;
 /**
  * Per-sandbox-machine liveness verdict. `oomKilled` is meaningful only when
  * `alive` is false: true when the backend reports the machine was killed for

package/dist/sandbox/watchdog.js

@@ -21,11 +21,14 @@
 import { createHash } from "node:crypto";
 import { DBOS } from "@dbos-inc/dbos-sdk";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { untracedWorkflow } from "../lib/otel-spans.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { workflowIdFromExec } from "./exec-id.js";
 import { syntheticFailureReason, syntheticFailureResult } from "./liveness.js";
 export const SHARD_COUNT = 8;
 const WATCHDOG_CRON = "*/60 * * * * *";
+const WATCHDOG_PARENT_WORKFLOW = "sandbox-watchdog-parent";
+const WATCHDOG_SHARD_WORKFLOW = "sandbox-watchdog-shard";
 /** Stable hash → shard mapping, exported for tests. */
 export function shardIndex(sandboxId, shardCount = SHARD_COUNT) {
     const digest = createHash("sha1").update(sandboxId).digest();
@@ -131,7 +134,8 @@ export function registerWatchdog(deps) {
             },
             logger: deps.logger,
         });
-    }, { name: "sandbox-watchdog-shard" });
+    }, { name: WATCHDOG_SHARD_WORKFLOW });
+    untracedWorkflow(WATCHDOG_SHARD_WORKFLOW);
     // The scheduled target must itself be a registered workflow — DBOS's
     // scheduler loop skips (and errors on) any `@scheduled` function that lacks
     // a workflow registration. Register, then schedule the same callable.
@@ -148,9 +152,10 @@ export function registerWatchdog(deps) {
                 continue;
             await DBOS.startWorkflow(childCheckShard)(shard);
         }
-    }, { name: "sandbox-watchdog-parent" });
+    }, { name: WATCHDOG_PARENT_WORKFLOW });
+    untracedWorkflow(WATCHDOG_PARENT_WORKFLOW);
     DBOS.registerScheduled(watchdogParent, {
-        name: "sandbox-watchdog-parent",
+        name: WATCHDOG_PARENT_WORKFLOW,
         crontab: WATCHDOG_CRON,
     });
 }

package/dist/schemas/plan-schemas.d.ts

@@ -8,9 +8,9 @@ import type { AnalysisPlan } from "./workflow-state.js";
  *  and the hardcoded sandbox turn budget. */
 export declare const PlanStepSchema: z.ZodObject<{
     name: z.ZodString;
-    id: z.ZodString;
     context: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
     track: z.ZodString;
     step_type: z.ZodString;
     question: z.ZodString;
@@ -41,9 +41,9 @@ export declare const PlannerPlanSchema: z.ZodObject<{
     title: z.ZodString;
     steps: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
-        id: z.ZodString;
         context: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
         track: z.ZodString;
         step_type: z.ZodString;
         question: z.ZodString;
@@ -83,9 +83,9 @@ export declare const PlanningAgentOutputSchema: z.ZodObject<{
         title: z.ZodString;
         steps: z.ZodArray<z.ZodObject<{
             name: z.ZodString;
-            id: z.ZodString;
             context: z.ZodOptional<z.ZodString>;
             description: z.ZodOptional<z.ZodString>;
+            id: z.ZodString;
             track: z.ZodString;
             step_type: z.ZodString;
             question: z.ZodString;

package/dist/schemas/validate-plan.js

@@ -13,6 +13,7 @@
  */
 import { KNOWN_AGENT_IDS } from "../agents/sandbox-catalog.js";
 import { CycleError, DependencyError, topoSortIntoWaves } from "../execution/topo-sort.js";
+import { parseQuery } from "../sandbox/package-identity.js";
 import { isSafeId, STEP_SUBDIRS, SYNTHESIS_STEP_ID } from "../workspace/paths.js";
 const KNOWN_AGENTS = new Set(KNOWN_AGENT_IDS);
 /**
@@ -24,6 +25,30 @@ const KNOWN_AGENTS = new Set(KNOWN_AGENT_IDS);
  * the row's `(run_id, step_id)` primary key (see the harness-workspace-tools spec).
  */
 const RESERVED_STEP_IDS = new Set([...STEP_SUBDIRS, SYNTHESIS_STEP_ID]);
+/**
+ * One issue for one package entry that does not parse. Each message names the
+ * step and the entry, because a planner corrects the entry it wrote.
+ *
+ * The wording carries the reason of each refusal. A location publishes an
+ * installer detail as an interface. An unknown `<word>:` prefix rides into the
+ * pool as part of the name. A specifier that is not `==` turns a range such as
+ * `numpy>=1.26` into a package name, and the pool then refuses a package that
+ * it holds.
+ */
+function describeParseError(stepId, entry, error) {
+    switch (error.type) {
+        case "empty":
+            return `Step "${stepId}" names an empty package entry — name each package as a requirement (a bare name, or name==version)`;
+        case "location":
+            return (`Step "${stepId}" names a package location "${entry}" — name each package as a requirement ` +
+                `(a bare name, or name==version), never a path, a URL, or a store directory`);
+        case "unknown_prefix":
+            return (`Step "${stepId}" names the ecosystem of "${entry}" with a prefix the link pass cannot read — ` +
+                `the permitted prefixes are "python:" and "r:", and a bare name searches both tracks`);
+        case "unsupported_specifier":
+            return (`Step "${stepId}" pins "${entry}" with a specifier the link pass cannot honor — ` + `use a bare name, or name==version with one exact version`);
+    }
+}
 /** Derive a filesystem-safe output prefix from a step ID. */
 export function deriveOutputPrefix(stepId) {
     return stepId
@@ -109,23 +134,15 @@ export function validatePlan(plan, options) {
                 `step-directory convention; "${SYNTHESIS_STEP_ID}" is the run-level synthesis phase)`);
         }
     }
-    // 6. Package entries are requirements, never locations. A path, a URL, or
-    //    a store directory in a plan would publish an installer detail as an
-    //    interface — the link pass resolves names against the pool. An absent
-    //    array passes, because stored plans from before the field carry none.
-    //    The specifier check exists because the link pass splits on `==` only:
-    //    an unrefused `numpy>=1.26` becomes a package NAME, and the pool then
-    //    refuses a package it holds.
+    // 6. Each package entry is a query of the one grammar. The validation IS
+    //    the parse, thus no second reader of the grammar can disagree with the
+    //    link pass. An absent array passes, because stored plans from before
+    //    the field carry none.
     for (const step of plan.steps) {
         for (const entry of step.packages ?? []) {
-            if (/^[.~]|[/\\]|:\/\//.test(entry)) {
-                errors.push(`Step "${step.id}" names a package location "${entry}" — name each package as a requirement ` +
-                    `(a bare name, or name==version), never a path, a URL, or a store directory`);
-            }
-            else if (/[<>!~]/.test(entry) || (entry.includes("=") && !entry.includes("=="))) {
-                errors.push(`Step "${step.id}" pins "${entry}" with a specifier the link pass cannot honor — ` +
-                    `use a bare name, or name==version with one exact version`);
-            }
+            const parsed = parseQuery(entry);
+            if (parsed.isErr())
+                errors.push(describeParseError(step.id, entry, parsed.error));
         }
     }
     // 7. Step-id path safety. The id becomes the `runs/{runId}/{stepId}` directory

package/dist/schemas/workflow-state.js

@@ -31,7 +31,9 @@ export const AnalysisStepSchema = z.object({
     packages: z
         .array(z.string())
         .optional()
-        .describe('The packages this step imports, each as a requirement: a bare name ("scanpy") or a name with one exact version ("numpy==1.26.4"). ' +
+        .describe('The packages this step imports, each as a query in the grammar [python:|r:]<name>[==<version>]: a bare name ("scanpy"), a name with one exact version ("numpy==1.26.4"), or either behind a track prefix ("python:igraph", "r:decoupleR==2.17.0"). ' +
+        "A bare name searches both tracks. " +
+        "When the package census shows one name under the Python section and under the R section, write the prefixed form — a bare both-track name refuses the launch. " +
         "Never a path, a URL, or a store directory. An empty array means the step needs nothing beyond the baked toolchain. " +
         "The set is not a promise of completeness — the execution agent can still link a missing package."),
     depends_on: z

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

@@ -96,6 +96,18 @@ export declare function tryRerunDataProfile(pool: Querier, analysisId: string):
  * normal in-band outcome, not an error.
  */
 export declare function recordDataProfileWorkflowId(pool: Querier, analysisId: string, workflowId: string): ResultAsync<boolean, DbError>;
+/**
+ * Outcome of a terminal compare-and-set on the profile row. The CAS accepts one
+ * write per `running` claim, so `stamped: true` is the exactly-once point of a
+ * profile's terminal transition. It carries the `data_profile_started_at` of the
+ * claim it closed, so the caller measures the profile from the ledger's own start.
+ */
+export type DataProfileTerminalWrite = {
+    readonly stamped: false;
+} | {
+    readonly stamped: true;
+    readonly startedAt: string | null;
+};
 /**
  * Stamp a claimed-`running` row `completed` and record its result — a terminal
  * write CAS'd on `data_profile_status = 'running'`.
@@ -111,10 +123,11 @@ export declare function recordDataProfileWorkflowId(pool: Querier, analysisId: s
  * Every legitimate caller reaches here from a row it claimed into `running`, so the
  * guard only ever refuses a row another writer already moved on from.
  *
- * `ok(true)` when this call stamped the row; `ok(false)` when the guard refused it
- * (the row was cleared/expired/replayed away) — a no-op the caller logs, not an error.
+ * `stamped: true` when this call stamped the row, with the `data_profile_started_at`
+ * of the claim it closed; `stamped: false` when the guard refused it (the row was
+ * cleared/expired/replayed away) — a no-op the caller logs, not an error.
  */
-export declare function completeDataProfile(pool: Querier, analysisId: string, result?: DataProfileResult): ResultAsync<boolean, DbError>;
+export declare function completeDataProfile(pool: Querier, analysisId: string, result?: DataProfileResult): ResultAsync<DataProfileTerminalWrite, DbError>;
 /**
  * Stamp a claimed-`running` row `failed` with a reason — the terminal-failure
  * counterpart to {@link completeDataProfile}, CAS'd on `data_profile_status = 'running'`
@@ -123,10 +136,11 @@ export declare function completeDataProfile(pool: Querier, analysisId: string, r
  * `failed` status over a cleared row. `data_profile_result` is left untouched so a
  * prior profile survives the failure (the re-profile/retry route can keep serving it).
  *
- * `ok(true)` when this call stamped the row; `ok(false)` when the guard refused it —
- * a logged no-op, not an error.
+ * `stamped: true` when this call stamped the row, with the `data_profile_started_at`
+ * of the claim it closed; `stamped: false` when the guard refused it — a logged
+ * no-op, not an error.
  */
-export declare function failDataProfile(pool: Querier, analysisId: string, error: string): ResultAsync<boolean, DbError>;
+export declare function failDataProfile(pool: Querier, analysisId: string, error: string): ResultAsync<DataProfileTerminalWrite, DbError>;
 export declare function expireStaleDataProfile(pool: Querier, analysisId: string, timeoutMs: number): ResultAsync<boolean, DbError>;
 /**
  * Reset a ledger row wedged at `running` with no workflow behind it back to

package/dist/state/data-profile.js

@@ -142,6 +142,10 @@ export function recordDataProfileWorkflowId(pool, analysisId, workflowId) {
         return (result.rowCount ?? 0) > 0;
     });
 }
+function terminalWriteOf(rows) {
+    const row = rows[0];
+    return row === undefined ? { stamped: false } : { stamped: true, startedAt: row.data_profile_started_at ?? null };
+}
 /**
  * Stamp a claimed-`running` row `completed` and record its result — a terminal
  * write CAS'd on `data_profile_status = 'running'`.
@@ -157,8 +161,9 @@ export function recordDataProfileWorkflowId(pool, analysisId, workflowId) {
  * Every legitimate caller reaches here from a row it claimed into `running`, so the
  * guard only ever refuses a row another writer already moved on from.
  *
- * `ok(true)` when this call stamped the row; `ok(false)` when the guard refused it
- * (the row was cleared/expired/replayed away) — a no-op the caller logs, not an error.
+ * `stamped: true` when this call stamped the row, with the `data_profile_started_at`
+ * of the claim it closed; `stamped: false` when the guard refused it (the row was
+ * cleared/expired/replayed away) — a no-op the caller logs, not an error.
  */
 export function completeDataProfile(pool, analysisId, result) {
     const now = new Date().toISOString();
@@ -167,10 +172,11 @@ export function completeDataProfile(pool, analysisId, result) {
             text: `UPDATE cortex_analysis_state
             SET data_profile_status = 'completed', data_profile_completed_at = $1,
                 data_profile_result = $2::jsonb
-            WHERE analysis_id = $3 AND data_profile_status = 'running'`,
+            WHERE analysis_id = $3 AND data_profile_status = 'running'
+            RETURNING data_profile_started_at`,
             values: [now, result ? JSON.stringify(result) : null, analysisId],
         });
-        return (res.rowCount ?? 0) > 0;
+        return terminalWriteOf(res.rows);
     });
 }
 /**
@@ -181,8 +187,9 @@ export function completeDataProfile(pool, analysisId, result) {
  * `failed` status over a cleared row. `data_profile_result` is left untouched so a
  * prior profile survives the failure (the re-profile/retry route can keep serving it).
  *
- * `ok(true)` when this call stamped the row; `ok(false)` when the guard refused it —
- * a logged no-op, not an error.
+ * `stamped: true` when this call stamped the row, with the `data_profile_started_at`
+ * of the claim it closed; `stamped: false` when the guard refused it — a logged
+ * no-op, not an error.
  */
 export function failDataProfile(pool, analysisId, error) {
     const now = new Date().toISOString();
@@ -191,10 +198,11 @@ export function failDataProfile(pool, analysisId, error) {
             text: `UPDATE cortex_analysis_state
             SET data_profile_status = 'failed', data_profile_error = $1,
                 data_profile_completed_at = $2
-            WHERE analysis_id = $3 AND data_profile_status = 'running'`,
+            WHERE analysis_id = $3 AND data_profile_status = 'running'
+            RETURNING data_profile_started_at`,
             values: [error, now, analysisId],
         });
-        return (res.rowCount ?? 0) > 0;
+        return terminalWriteOf(res.rows);
     });
 }
 export function expireStaleDataProfile(pool, analysisId, timeoutMs) {