@inflexa-ai/harness 0.35.2 → 0.35.4

package/dist/citations/types.d.ts

@@ -48,9 +48,9 @@ export declare const CitationVerdictSchema: z.ZodEnum<{
 }>;
 export type CitationVerdict = z.infer<typeof CitationVerdictSchema>;
 export declare const CitationCoverageSchema: z.ZodEnum<{
+    partial: "partial";
     none: "none";
     complete: "complete";
-    partial: "partial";
 }>;
 export type CitationCoverage = z.infer<typeof CitationCoverageSchema>;
 export declare const ComparisonStatusSchema: z.ZodEnum<{
@@ -496,9 +496,9 @@ export declare const CitationResolutionResultSchema: z.ZodObject<{
         inconclusive: "inconclusive";
     }>;
     coverage: z.ZodEnum<{
+        partial: "partial";
         none: "none";
         complete: "complete";
-        partial: "partial";
     }>;
 }, z.core.$strip>;
 export type CitationResolutionResult = z.infer<typeof CitationResolutionResultSchema>;

package/dist/config/environment-stores.d.ts

@@ -8,6 +8,7 @@
  * "the profiler", "the planner") while the contract stayed identical. Extending
  * this interface keeps one description of a field that has one meaning.
  */
+import type { Track } from "../sandbox/package-identity.js";
 /**
  * Host paths of the environment's two read-only stores.
  *
@@ -94,5 +95,14 @@ export interface PoolInventoryPackage {
 /** One language-track section of an inventory, as `list_available_packages` renders it. */
 export interface PoolInventorySection {
     readonly title: string;
+    /**
+     * The ecosystem that holds the packages of this section. It carries the
+     * track as DATA, thus no reader derives one from the title: a title is
+     * display text, and a heading that changes wording would silently change
+     * which packages a `language` filter answers. A section of system tools or
+     * of node packages carries none, because neither is a package track of the
+     * pool.
+     */
+    readonly track?: Track;
     readonly packages: readonly PoolInventoryPackage[];
 }

package/dist/contracts/schemas/chat-parts.d.ts

@@ -104,8 +104,8 @@ export declare const FileReferencePartSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const AskStatusSchema: z.ZodEnum<{
-    aborted: "aborted";
     pending: "pending";
+    aborted: "aborted";
     resolved: "resolved";
     rejected: "rejected";
     expired: "expired";
@@ -117,8 +117,8 @@ export declare const AskPartSchema: z.ZodObject<{
     command: z.ZodString;
     detail: z.ZodOptional<z.ZodString>;
     status: z.ZodEnum<{
-        aborted: "aborted";
         pending: "pending";
+        aborted: "aborted";
         resolved: "resolved";
         rejected: "rejected";
         expired: "expired";
@@ -182,8 +182,8 @@ export declare const DagStatePartSchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const StepPhaseSchema: z.ZodEnum<{
-    complete: "complete";
     failed: "failed";
+    complete: "complete";
     warning: "warning";
     "sandbox-init": "sandbox-init";
     executing: "executing";
@@ -199,8 +199,8 @@ export declare const StepActivityPartSchema: z.ZodObject<{
     runId: z.ZodString;
     stepId: z.ZodString;
     phase: z.ZodEnum<{
-        complete: "complete";
         failed: "failed";
+        complete: "complete";
         warning: "warning";
         "sandbox-init": "sandbox-init";
         executing: "executing";
@@ -314,8 +314,8 @@ export declare const RunCompletedPartSchema: z.ZodObject<{
     type: z.ZodLiteral<"data-run-completed">;
     runId: z.ZodString;
     status: z.ZodEnum<{
-        partial: "partial";
         completed: "completed";
+        partial: "partial";
     }>;
     completedSteps: z.ZodNumber;
     totalSteps: z.ZodNumber;
@@ -403,9 +403,9 @@ export declare const RunSynthesisPartSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const SynthesisPhaseSchema: z.ZodEnum<{
-    complete: "complete";
     failed: "failed";
     skipped: "skipped";
+    complete: "complete";
     indexing: "indexing";
     persisting: "persisting";
     starting: "starting";
@@ -419,9 +419,9 @@ export declare const SynthesisProgressPartSchema: z.ZodObject<{
     id: z.ZodString;
     runId: z.ZodString;
     phase: z.ZodEnum<{
-        complete: "complete";
         failed: "failed";
         skipped: "skipped";
+        complete: "complete";
         indexing: "indexing";
         persisting: "persisting";
         starting: "starting";
@@ -520,8 +520,8 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     command: z.ZodString;
     detail: z.ZodOptional<z.ZodString>;
     status: z.ZodEnum<{
-        aborted: "aborted";
         pending: "pending";
+        aborted: "aborted";
         resolved: "resolved";
         rejected: "rejected";
         expired: "expired";
@@ -560,8 +560,8 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     runId: z.ZodString;
     stepId: z.ZodString;
     phase: z.ZodEnum<{
-        complete: "complete";
         failed: "failed";
+        complete: "complete";
         warning: "warning";
         "sandbox-init": "sandbox-init";
         executing: "executing";
@@ -679,9 +679,9 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     id: z.ZodString;
     runId: z.ZodString;
     phase: z.ZodEnum<{
-        complete: "complete";
         failed: "failed";
         skipped: "skipped";
+        complete: "complete";
         indexing: "indexing";
         persisting: "persisting";
         starting: "starting";
@@ -698,8 +698,8 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     type: z.ZodLiteral<"data-run-completed">;
     runId: z.ZodString;
     status: z.ZodEnum<{
-        partial: "partial";
         completed: "completed";
+        partial: "partial";
     }>;
     completedSteps: z.ZodNumber;
     totalSteps: z.ZodNumber;

package/dist/execution/run-canceler.js

@@ -18,6 +18,7 @@
  * terminal frame read-side.
  */
 import { createNoopLogger } from "../lib/console-logger.js";
+import { elapsedSinceIso, recordRunCompleted, recordStepCompleted } from "../lib/metrics.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { markRunCanceledIfActive, queryRun } from "../state/runs.js";
 import { queryStepsByRun, sweepPendingStepExecutions } from "../state/step-executions.js";
@@ -49,8 +50,9 @@ export function createRunCanceler(deps) {
         })();
         await engineCancel(workflowIds);
     };
-    /** Persisted child workflow ids of steps not yet completed. */
-    const incompleteChildIds = async (runId) => unwrapOrThrow(await queryStepsByRun(pool, runId)).flatMap((step) => step.childWorkflowId !== null && step.completedAt === null ? [step.childWorkflowId] : []);
+    /** Steps whose child started (a persisted child workflow id) and has not written its terminal row. */
+    const incompleteSteps = async (runId) => unwrapOrThrow(await queryStepsByRun(pool, runId)).filter((step) => step.childWorkflowId !== null && step.completedAt === null);
+    const childIds = (steps) => steps.flatMap((step) => (step.childWorkflowId !== null ? [step.childWorkflowId] : []));
     return {
         async cancel(runId, session) {
             const row = unwrapOrThrow(await queryRun(pool, runId));
@@ -71,10 +73,14 @@ export function createRunCanceler(deps) {
             // mark-running step has not yet committed its child_workflow_id. The
             // persisted ids and the post-cancel re-query are belt-and-braces over
             // both ledgers' lag.
-            const knownChildren = await incompleteChildIds(runId);
+            const knownChildren = childIds(await incompleteSteps(runId));
             await cancelWorkflows([workflowId, ...knownChildren]);
+            // The steps the cancel cut: read after the cancel landed, so a child that
+            // wrote its terminal row in the meantime is not among them.
+            let cutSteps;
             try {
-                const late = (await incompleteChildIds(runId)).filter((id) => !knownChildren.includes(id));
+                cutSteps = await incompleteSteps(runId);
+                const late = childIds(cutSteps).filter((id) => !knownChildren.includes(id));
                 if (late.length > 0)
                     await cancelWorkflows(late);
             }
@@ -89,6 +95,16 @@ export function createRunCanceler(deps) {
             catch (err) {
                 logger.error("markRunCanceledIfActive failed", { runId, ...logger.errorFields(err) });
             }
+            // The workflow's own terminal step never runs after a cancel, so this
+            // conditional write is the one terminal write of an external cancel, and
+            // the outcome metrics ride behind it: a refused write means the run
+            // settled on its own and its own terminal step recorded them. A cut
+            // child never reached its terminal row, so its step records here too.
+            if (transitioned) {
+                recordRunCompleted({ workflow: "analysis", status: "canceled", durationMs: elapsedSinceIso(row.startedAt) });
+                for (const step of cutSteps ?? [])
+                    recordStepCompleted({ agentId: step.agentId, status: "canceled" });
+            }
             let steps = false;
             try {
                 unwrapOrThrow(await sweepPendingStepExecutions(pool, runId));

package/dist/index.d.ts

@@ -136,7 +136,9 @@ export type { CreateSandboxClientConfig, SandboxBackendConfig } from "./sandbox/
 export type { SandboxClient } from "./sandbox/client.js";
 export { describeSandboxError, SandboxFailure } from "./sandbox/sandbox-error.js";
 export type { SandboxError } from "./sandbox/sandbox-error.js";
-export type { ExtendAnalysisFarm, FarmLocation, FarmResolution, FarmSource, PackageRequest, PackageRequestOutcome, ResolveAnalysisFarm, ToolchainSource, } from "./sandbox/types.js";
+export type { ExtendAnalysisFarm, FarmLocation, FarmResolution, FarmSource, PackageRequestOutcome, ResolveAnalysisFarm, ToolchainSource, } from "./sandbox/types.js";
+export { formatQuery, identityAddress, identityKey, identityOf, parseIdentityKey, parseQuery, pythonIdentity, resolveQuery, rIdentity, } from "./sandbox/package-identity.js";
+export type { PackageIdentity, PackageQuery, ParseQueryError, PoolIndex, QueryResolution, Track } from "./sandbox/package-identity.js";
 export { FARM_LOCK_FILE, FarmLockSchema, readFarmLock, readFarmLockFile } from "./sandbox/farm.js";
 export type { FarmLock, FarmLockError } from "./sandbox/farm.js";
 export { IMAGE_PACKAGES_FILE } from "./sandbox/image-packages.js";

package/dist/index.js

@@ -246,6 +246,11 @@ export { createSandboxClient } from "./sandbox/create-sandbox.js";
 // The throw of the client seam. An embedder matches the class and reads the
 // typed variant on `error`, instead of a string match on the message.
 export { describeSandboxError, SandboxFailure } from "./sandbox/sandbox-error.js";
+// The identity of a package, the query that asks for one, and the resolution
+// between the two. An embedder reads `by_name` of the dependency graph with
+// these, thus the host lookup, the census, and the graph key never disagree on
+// the identity of a name.
+export { formatQuery, identityAddress, identityKey, identityOf, parseIdentityKey, parseQuery, pythonIdentity, resolveQuery, rIdentity, } from "./sandbox/package-identity.js";
 // The farm contract: one `inflexa.lock` per farm. An embedder that composes
 // farms writes this shape, and the mount gate reads it — one schema, no copy.
 export { FARM_LOCK_FILE, FarmLockSchema, readFarmLock, readFarmLockFile } from "./sandbox/farm.js";

package/dist/lib/metrics.d.ts

@@ -2,17 +2,75 @@
  * Custom OTel metrics for Cortex.
  *
  * Instruments:
- *   - cortex.artifact.reconcile.dropped — counter for missing manifest entries
- *   - cortex.artifact.reconcile.input_dropped — counter for lineage input drops
+ *   - cortex.run.completed{status, workflow}      — counter, one per run that reached a terminal status
+ *   - cortex.run.duration_ms{status, workflow}    — histogram, start to terminal status
+ *   - cortex.step.completed{status, agent_id}     — counter, one per executed step that settled
+ *   - cortex.step.duration_ms{status, agent_id}   — histogram, step start to its terminal ledger write
+ *   - cortex.artifact.reconcile.dropped{agent_id}              — counter for missing manifest entries
+ *   - cortex.artifact.reconcile.input_dropped{agent_id, reason} — counter for lineage input drops
  *
- * Both carry `agent_id` (about 15 values) and never a per-step or per-run
- * identifier: a label with unbounded values multiplies the series count.
+ * Every label is a bounded vocabulary: `status` is the terminal enum, `workflow`
+ * names the workflow family, `agent_id` has about 15 values. No instrument
+ * carries a run, step, exec, user, or organization id — a label with unbounded
+ * values multiplies the series count.
+ *
+ * A run or step outcome is recorded INSIDE the DBOS step that persists the same
+ * outcome to the ledger (or behind the ledger's own compare-and-set where the
+ * body has no such step). DBOS caches a completed step and does not re-run its
+ * body on recovery, so a replayed workflow records nothing twice.
  *
  * Instruments are lazy so the record site binds to whichever `MeterProvider`
  * is globally registered at first use. The metrics API has no late-binding
  * proxy: a meter taken at module load, before `initOtel` runs, would stay
  * on the no-op provider for the life of the process.
  */
+import type { StepExecutionStatus } from "../state/schema.js";
+/** Terminal status of a run. A budget pause records as `canceled`, the same as the run ledger. */
+export type RunOutcome = "completed" | "partial" | "failed" | "canceled";
+/** The workflow family a run belongs to. */
+export type RunWorkflow = "analysis" | "target_assessment" | "data_profile";
+/** Terminal status of an executed step. A blocker is a failure to deliver, so `blocked` maps here to `failed`. */
+export type StepOutcome = "completed" | "failed" | "canceled";
+/**
+ * Bucket bounds for durations that run from seconds to hours: 30 s, then
+ * 1, 2, 5, 10, 30, 60, 120, 240 min. Ten buckets with the overflow, so one
+ * histogram costs about ten series per label set.
+ */
+export declare const RUN_DURATION_BOUNDS_MS: readonly number[];
+/**
+ * Record one run that reached a terminal status. Call it inside the DBOS step
+ * that persists that status, or behind the ledger compare-and-set that accepted
+ * it. `durationMs` is omitted when the start instant is unknown: the run is
+ * then counted, not timed.
+ */
+export declare function recordRunCompleted(args: {
+    readonly workflow: RunWorkflow;
+    readonly status: RunOutcome;
+    readonly durationMs?: number;
+}): void;
+/**
+ * Record one executed step that settled. Call it inside the DBOS step that
+ * persists the terminal row, or inside the terminal step of the run for a
+ * step whose own body never reached one. `durationMs` is omitted when the
+ * step settled without a durable duration: it is then counted, not timed.
+ */
+export declare function recordStepCompleted(args: {
+    readonly agentId: string;
+    readonly status: StepOutcome;
+    readonly durationMs?: number;
+}): void;
+/**
+ * The step outcome that a terminal ledger status records. A status that is not
+ * terminal (`pending`, `running`) or that names a step that never executed
+ * (`skipped`) records no outcome.
+ */
+export declare function stepOutcomeOf(status: StepExecutionStatus): StepOutcome | undefined;
+/**
+ * Milliseconds from a persisted ISO-8601 start instant to `nowMs`. `undefined`
+ * when the ledger holds no start or an unparsable one, so the caller counts
+ * without a duration instead of recording a bogus one.
+ */
+export declare function elapsedSinceIso(startedAt: string | null | undefined, nowMs?: number): number | undefined;
 /** Record one manifest entry dropped at reconcile. */
 export declare function recordArtifactReconcileDropped(args: {
     readonly agentId: string;
@@ -24,4 +82,4 @@ export declare function recordLineageInputDropped(args: {
     readonly reason: LineageInputDropReason;
 }): void;
 /** Test hook — drop memoised instruments to rebind a fresh MeterProvider. */
-export declare function __resetReconcileMetricsForTest(): void;
+export declare function __resetMetricsForTest(): void;

package/dist/lib/metrics.js

@@ -2,11 +2,22 @@
  * Custom OTel metrics for Cortex.
  *
  * Instruments:
- *   - cortex.artifact.reconcile.dropped — counter for missing manifest entries
- *   - cortex.artifact.reconcile.input_dropped — counter for lineage input drops
+ *   - cortex.run.completed{status, workflow}      — counter, one per run that reached a terminal status
+ *   - cortex.run.duration_ms{status, workflow}    — histogram, start to terminal status
+ *   - cortex.step.completed{status, agent_id}     — counter, one per executed step that settled
+ *   - cortex.step.duration_ms{status, agent_id}   — histogram, step start to its terminal ledger write
+ *   - cortex.artifact.reconcile.dropped{agent_id}              — counter for missing manifest entries
+ *   - cortex.artifact.reconcile.input_dropped{agent_id, reason} — counter for lineage input drops
  *
- * Both carry `agent_id` (about 15 values) and never a per-step or per-run
- * identifier: a label with unbounded values multiplies the series count.
+ * Every label is a bounded vocabulary: `status` is the terminal enum, `workflow`
+ * names the workflow family, `agent_id` has about 15 values. No instrument
+ * carries a run, step, exec, user, or organization id — a label with unbounded
+ * values multiplies the series count.
+ *
+ * A run or step outcome is recorded INSIDE the DBOS step that persists the same
+ * outcome to the ledger (or behind the ledger's own compare-and-set where the
+ * body has no such step). DBOS caches a completed step and does not re-run its
+ * body on recovery, so a replayed workflow records nothing twice.
  *
  * Instruments are lazy so the record site binds to whichever `MeterProvider`
  * is globally registered at first use. The metrics API has no late-binding
@@ -14,11 +25,36 @@
  * on the no-op provider for the life of the process.
  */
 import { metrics } from "@opentelemetry/api";
+/**
+ * Bucket bounds for durations that run from seconds to hours: 30 s, then
+ * 1, 2, 5, 10, 30, 60, 120, 240 min. Ten buckets with the overflow, so one
+ * histogram costs about ten series per label set.
+ */
+export const RUN_DURATION_BOUNDS_MS = [30_000, 60_000, 120_000, 300_000, 600_000, 1_800_000, 3_600_000, 7_200_000, 14_400_000];
 let instruments;
 function getInstruments() {
     if (instruments === undefined) {
         const meter = metrics.getMeter("cortex");
+        const advice = { explicitBucketBoundaries: [...RUN_DURATION_BOUNDS_MS] };
         instruments = {
+            runCompleted: meter.createCounter("cortex.run.completed", {
+                description: "Runs that reached a terminal status. Tagged by status, workflow.",
+                unit: "{run}",
+            }),
+            runDuration: meter.createHistogram("cortex.run.duration_ms", {
+                description: "Run duration from its start to its terminal status. Tagged by status, workflow.",
+                unit: "ms",
+                advice,
+            }),
+            stepCompleted: meter.createCounter("cortex.step.completed", {
+                description: "Executed steps that settled. Tagged by status, agent_id.",
+                unit: "{step}",
+            }),
+            stepDuration: meter.createHistogram("cortex.step.duration_ms", {
+                description: "Step duration from its start to its terminal ledger write. Tagged by status, agent_id.",
+                unit: "ms",
+                advice,
+            }),
             artifactReconcileDropped: meter.createCounter("cortex.artifact.reconcile.dropped", {
                 description: "Manifest entries dropped because their on-disk file was missing at " +
                     "registration time (writes-then-deletes, renames). Tagged by agent_id.",
@@ -33,6 +69,69 @@ function getInstruments() {
     }
     return instruments;
 }
+/**
+ * Record one run that reached a terminal status. Call it inside the DBOS step
+ * that persists that status, or behind the ledger compare-and-set that accepted
+ * it. `durationMs` is omitted when the start instant is unknown: the run is
+ * then counted, not timed.
+ */
+export function recordRunCompleted(args) {
+    const attributes = { status: args.status, workflow: args.workflow };
+    const { runCompleted, runDuration } = getInstruments();
+    runCompleted.add(1, attributes);
+    if (args.durationMs !== undefined)
+        runDuration.record(Math.max(0, args.durationMs), attributes);
+}
+/**
+ * Record one executed step that settled. Call it inside the DBOS step that
+ * persists the terminal row, or inside the terminal step of the run for a
+ * step whose own body never reached one. `durationMs` is omitted when the
+ * step settled without a durable duration: it is then counted, not timed.
+ */
+export function recordStepCompleted(args) {
+    const attributes = { status: args.status, agent_id: args.agentId };
+    const { stepCompleted, stepDuration } = getInstruments();
+    stepCompleted.add(1, attributes);
+    if (args.durationMs !== undefined)
+        stepDuration.record(Math.max(0, args.durationMs), attributes);
+}
+/**
+ * The step outcome that a terminal ledger status records. A status that is not
+ * terminal (`pending`, `running`) or that names a step that never executed
+ * (`skipped`) records no outcome.
+ */
+export function stepOutcomeOf(status) {
+    switch (status) {
+        case "completed":
+            return "completed";
+        case "failed":
+        case "blocked":
+            return "failed";
+        case "canceled":
+            return "canceled";
+        case "pending":
+        case "running":
+        case "skipped":
+            return undefined;
+        default: {
+            const _exhaustive = status;
+            return _exhaustive;
+        }
+    }
+}
+/**
+ * Milliseconds from a persisted ISO-8601 start instant to `nowMs`. `undefined`
+ * when the ledger holds no start or an unparsable one, so the caller counts
+ * without a duration instead of recording a bogus one.
+ */
+export function elapsedSinceIso(startedAt, nowMs = Date.now()) {
+    if (startedAt === null || startedAt === undefined)
+        return undefined;
+    const startedMs = Date.parse(startedAt);
+    if (!Number.isFinite(startedMs))
+        return undefined;
+    return Math.max(0, nowMs - startedMs);
+}
 /** Record one manifest entry dropped at reconcile. */
 export function recordArtifactReconcileDropped(args) {
     getInstruments().artifactReconcileDropped.add(1, { agent_id: args.agentId });
@@ -42,6 +141,6 @@ export function recordLineageInputDropped(args) {
     getInstruments().lineageInputDropped.add(1, { agent_id: args.agentId, reason: args.reason });
 }
 /** Test hook — drop memoised instruments to rebind a fresh MeterProvider. */
-export function __resetReconcileMetricsForTest() {
+export function __resetMetricsForTest() {
     instruments = undefined;
 }

package/dist/lib/otel-spans.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Span policy of the harness TracerProvider: which DBOS traces are recorded,
+ * which spans reach the exporter, and the names the exported spans carry.
+ *
+ * DBOS names a workflow span after the registered workflow and a step span
+ * after the step function, and it runs each body under its span, so every
+ * child (a step, a patched fetch, a pg query) sits under the workflow span.
+ * Three shapes of that output are noise in a trace store, and each is stopped
+ * in the process, before export, rather than in a collector downstream. The
+ * decisions live where the workflows and steps are written; this module holds
+ * the mechanism only:
+ *
+ * - A module that registers a housekeeping workflow declares it untraced with
+ *   `untracedWorkflow(name)` next to its registration. The sampler drops a
+ *   root span that carries such a name at creation, and `ParentBased`
+ *   sampling carries the decision to every child.
+ * - A replayed step re-emits its span with `cached=true`, which DBOS sets
+ *   after the span has started. A sampler cannot see that, so
+ *   `DbosSpanProcessor` drops the span at `onEnd`.
+ * - A step whose DBOS name embeds an id calls `stableSpan` as the first
+ *   statement of its body. The helper renames the active DBOS span to the
+ *   stable prefix and puts the id in an `inflexa.*` attribute. The DBOS step
+ *   name itself is untouched: DBOS compares it against the recorded name on
+ *   replay and throws `DBOSUnexpectedStepError` on a mismatch, so a rename
+ *   would break every workflow in flight across a deploy.
+ */
+import { type Attributes, type Context } from "@opentelemetry/api";
+import { type ReadableSpan, type Sampler, type Span, type SpanProcessor } from "@opentelemetry/sdk-trace-base";
+/**
+ * Declare a registered DBOS workflow untraced: no root span for it is
+ * recorded, and no child span under it. Call it next to the
+ * `DBOS.registerWorkflow` that gives the workflow the same name.
+ */
+export declare function untracedWorkflow(name: string): void;
+/**
+ * The sampler of the harness TracerProvider. A root span named after an
+ * untraced workflow is not recorded; every other root is. A span with a parent
+ * takes the parent's decision (the standard `ParentBased` behaviour), so a DBOS
+ * step, a fetch, or a pg span under a dropped root is dropped with it, and a
+ * remote parent (an inbound `traceparent`) is honoured as usual.
+ */
+export declare function createHarnessSampler(): Sampler;
+/** The plan step id a `compose-step-seed` step carries. */
+export declare const ATTR_INFLEXA_STEP_ID = "inflexa.step_id";
+/** The provider tool-use id of a tool step. */
+export declare const ATTR_INFLEXA_TOOL_USE_ID = "inflexa.tool_use_id";
+/** The exec id (`${workflowId}:${stepId}:${fnId}`) of a sandbox exec step. */
+export declare const ATTR_INFLEXA_EXEC_ID = "inflexa.exec_id";
+/** The 1-based attempt counter of a sandbox poll, pull, or liveness-probe step. */
+export declare const ATTR_INFLEXA_ATTEMPT = "inflexa.attempt";
+/** The per-item key (a ChEMBL or NCT id) of a target-assessment fan-out step. */
+export declare const ATTR_INFLEXA_FANOUT_KEY = "inflexa.fanout_key";
+/**
+ * Rename the DBOS span of the step that is running to `name` and put its id
+ * in `attributes`. Call it as the first statement of a step body whose DBOS
+ * name embeds an id, with that DBOS name as `dbosName`.
+ *
+ * DBOS runs the body under its span, so with tracing on the active span is
+ * the step span. With tracing off DBOS opens no span, and the active span, if
+ * there is one, belongs to whoever started the workflow or the chat turn. The
+ * helper therefore renames a span only when its name is `dbosName`, and it
+ * leaves a missing or non-recording span alone.
+ */
+export declare function stableSpan(dbosName: string, name: string, attributes: Attributes): void;
+/**
+ * Sits in front of the exporting processor and forwards every span except a
+ * replayed one (`cached=true`), which it drops at `onEnd`.
+ */
+export declare class DbosSpanProcessor implements SpanProcessor {
+    private readonly next;
+    constructor(next: SpanProcessor);
+    onStart(span: Span, parentContext: Context): void;
+    onEnding(span: Span): void;
+    onEnd(span: ReadableSpan): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}

package/dist/lib/otel-spans.js

@@ -0,0 +1,123 @@
+/**
+ * Span policy of the harness TracerProvider: which DBOS traces are recorded,
+ * which spans reach the exporter, and the names the exported spans carry.
+ *
+ * DBOS names a workflow span after the registered workflow and a step span
+ * after the step function, and it runs each body under its span, so every
+ * child (a step, a patched fetch, a pg query) sits under the workflow span.
+ * Three shapes of that output are noise in a trace store, and each is stopped
+ * in the process, before export, rather than in a collector downstream. The
+ * decisions live where the workflows and steps are written; this module holds
+ * the mechanism only:
+ *
+ * - A module that registers a housekeeping workflow declares it untraced with
+ *   `untracedWorkflow(name)` next to its registration. The sampler drops a
+ *   root span that carries such a name at creation, and `ParentBased`
+ *   sampling carries the decision to every child.
+ * - A replayed step re-emits its span with `cached=true`, which DBOS sets
+ *   after the span has started. A sampler cannot see that, so
+ *   `DbosSpanProcessor` drops the span at `onEnd`.
+ * - A step whose DBOS name embeds an id calls `stableSpan` as the first
+ *   statement of its body. The helper renames the active DBOS span to the
+ *   stable prefix and puts the id in an `inflexa.*` attribute. The DBOS step
+ *   name itself is untouched: DBOS compares it against the recorded name on
+ *   replay and throws `DBOSUnexpectedStepError` on a mismatch, so a rename
+ *   would break every workflow in flight across a deploy.
+ */
+import { trace } from "@opentelemetry/api";
+import { ParentBasedSampler, SamplingDecision, } from "@opentelemetry/sdk-trace-base";
+/**
+ * Names of the DBOS workflows whose traces are not recorded. A registering
+ * module adds its own name at registration, which runs at boot inside
+ * `assembleCoreRuntime`, before `DBOS.launch` starts the first workflow. The
+ * sampler reads the set on every root span, so the set is complete before it
+ * is consulted, and a name added later applies from the next root span on.
+ */
+const untracedWorkflowNames = new Set();
+/**
+ * Declare a registered DBOS workflow untraced: no root span for it is
+ * recorded, and no child span under it. Call it next to the
+ * `DBOS.registerWorkflow` that gives the workflow the same name.
+ */
+export function untracedWorkflow(name) {
+    untracedWorkflowNames.add(name);
+}
+/** Root decision only: `NOT_RECORD` for an untraced workflow, `RECORD_AND_SAMPLED` for every other root. */
+class UntracedWorkflowRootSampler {
+    shouldSample(_context, _traceId, spanName) {
+        return {
+            decision: untracedWorkflowNames.has(spanName) ? SamplingDecision.NOT_RECORD : SamplingDecision.RECORD_AND_SAMPLED,
+        };
+    }
+    toString() {
+        return "UntracedWorkflowRootSampler";
+    }
+}
+/**
+ * The sampler of the harness TracerProvider. A root span named after an
+ * untraced workflow is not recorded; every other root is. A span with a parent
+ * takes the parent's decision (the standard `ParentBased` behaviour), so a DBOS
+ * step, a fetch, or a pg span under a dropped root is dropped with it, and a
+ * remote parent (an inbound `traceparent`) is honoured as usual.
+ */
+export function createHarnessSampler() {
+    return new ParentBasedSampler({ root: new UntracedWorkflowRootSampler() });
+}
+/** The plan step id a `compose-step-seed` step carries. */
+export const ATTR_INFLEXA_STEP_ID = "inflexa.step_id";
+/** The provider tool-use id of a tool step. */
+export const ATTR_INFLEXA_TOOL_USE_ID = "inflexa.tool_use_id";
+/** The exec id (`${workflowId}:${stepId}:${fnId}`) of a sandbox exec step. */
+export const ATTR_INFLEXA_EXEC_ID = "inflexa.exec_id";
+/** The 1-based attempt counter of a sandbox poll, pull, or liveness-probe step. */
+export const ATTR_INFLEXA_ATTEMPT = "inflexa.attempt";
+/** The per-item key (a ChEMBL or NCT id) of a target-assessment fan-out step. */
+export const ATTR_INFLEXA_FANOUT_KEY = "inflexa.fanout_key";
+/**
+ * Rename the DBOS span of the step that is running to `name` and put its id
+ * in `attributes`. Call it as the first statement of a step body whose DBOS
+ * name embeds an id, with that DBOS name as `dbosName`.
+ *
+ * DBOS runs the body under its span, so with tracing on the active span is
+ * the step span. With tracing off DBOS opens no span, and the active span, if
+ * there is one, belongs to whoever started the workflow or the chat turn. The
+ * helper therefore renames a span only when its name is `dbosName`, and it
+ * leaves a missing or non-recording span alone.
+ */
+export function stableSpan(dbosName, name, attributes) {
+    const span = trace.getActiveSpan();
+    if (span === undefined || !span.isRecording())
+        return;
+    // The API `Span` has no name accessor; the SDK span the provider hands out does.
+    if (span.name !== dbosName)
+        return;
+    span.updateName(name);
+    span.setAttributes(attributes);
+}
+/**
+ * Sits in front of the exporting processor and forwards every span except a
+ * replayed one (`cached=true`), which it drops at `onEnd`.
+ */
+export class DbosSpanProcessor {
+    next;
+    constructor(next) {
+        this.next = next;
+    }
+    onStart(span, parentContext) {
+        this.next.onStart(span, parentContext);
+    }
+    onEnding(span) {
+        this.next.onEnding?.(span);
+    }
+    onEnd(span) {
+        if (span.attributes.cached === true)
+            return;
+        this.next.onEnd(span);
+    }
+    forceFlush() {
+        return this.next.forceFlush();
+    }
+    shutdown() {
+        return this.next.shutdown();
+    }
+}