@inflexa-ai/harness 0.35.2 → 0.35.4

package/dist/lib/otel.d.ts

@@ -5,12 +5,21 @@
  * so the bundler cannot tree-shake it (side-effect-only imports get dropped).
  *
  * Traces: NodeTracerProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT
- *         is set.
+ *         is set. The provider carries the span policy of otel-spans.ts: the
+ *         root span of a workflow declared with `untracedWorkflow` is not
+ *         recorded (and its children with it), a replayed `cached=true` span
+ *         is dropped before export, and a step body that calls `stableSpan`
+ *         is exported under a stable name with its id in an `inflexa.*`
+ *         attribute.
  *
  * Metrics: MeterProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT is
  *          set and OTEL_METRICS_EXPORTER is not `none`. The export interval is
- *          OTEL_METRIC_EXPORT_INTERVAL (ms), default 60 s. Custom Cortex
- *          metrics are defined in metrics.ts.
+ *          OTEL_METRIC_EXPORT_INTERVAL (ms), default 60 s. The run and step
+ *          outcome instruments (`cortex.run.*`, `cortex.step.*`) and the
+ *          reconcile counters are defined in metrics.ts; the agent loop, the
+ *          thread memory, and the workflows hold their own instruments next
+ *          to their record sites. Every instrument binds lazily to the
+ *          provider registered here.
  *
  * Resource: the host's `serviceName` / `serviceVersion` merged with the SDK
  *           env detector (`OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`);

package/dist/lib/otel.js

@@ -5,12 +5,21 @@
  * so the bundler cannot tree-shake it (side-effect-only imports get dropped).
  *
  * Traces: NodeTracerProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT
- *         is set.
+ *         is set. The provider carries the span policy of otel-spans.ts: the
+ *         root span of a workflow declared with `untracedWorkflow` is not
+ *         recorded (and its children with it), a replayed `cached=true` span
+ *         is dropped before export, and a step body that calls `stableSpan`
+ *         is exported under a stable name with its id in an `inflexa.*`
+ *         attribute.
  *
  * Metrics: MeterProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT is
  *          set and OTEL_METRICS_EXPORTER is not `none`. The export interval is
- *          OTEL_METRIC_EXPORT_INTERVAL (ms), default 60 s. Custom Cortex
- *          metrics are defined in metrics.ts.
+ *          OTEL_METRIC_EXPORT_INTERVAL (ms), default 60 s. The run and step
+ *          outcome instruments (`cortex.run.*`, `cortex.step.*`) and the
+ *          reconcile counters are defined in metrics.ts; the agent loop, the
+ *          thread memory, and the workflows hold their own instruments next
+ *          to their record sites. Every instrument binds lazily to the
+ *          provider registered here.
  *
  * Resource: the host's `serviceName` / `serviceVersion` merged with the SDK
  *           env detector (`OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`);
@@ -25,6 +34,7 @@
  */
 import { context, propagation, metrics, trace } from "@opentelemetry/api";
 import { createNoopLogger } from "./console-logger.js";
+import { createHarnessSampler, DbosSpanProcessor } from "./otel-spans.js";
 import { W3CTraceContextPropagator } from "@opentelemetry/core";
 import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
 import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
@@ -92,10 +102,11 @@ export function initOtel(options = {}) {
         const spanProcessors = [];
         if (endpoint) {
             const base = endpoint.replace(/\/+$/, "");
-            spanProcessors.push(new BatchSpanProcessor(new OTLPTraceExporter({ url: `${base}/v1/traces` })));
+            spanProcessors.push(new DbosSpanProcessor(new BatchSpanProcessor(new OTLPTraceExporter({ url: `${base}/v1/traces` }))));
         }
         const tracerProvider = new NodeTracerProvider({
             resource,
+            sampler: createHarnessSampler(),
             spanProcessors,
         });
         tracerProvider.register();

package/dist/loop/run-agent.js

@@ -3,6 +3,7 @@ import { jsonSchema, tool as aiTool, } from "ai";
 import { createNoopUsageRecorder } from "../billing/noop-usage-recorder.js";
 import { stripNulCharacters } from "../input-sanitization.js";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { ATTR_INFLEXA_TOOL_USE_ID, stableSpan } from "../lib/otel-spans.js";
 import { hintForZodIssue, repairToolInput } from "../lib/zod-issues.js";
 import { markInterruptedMessage, syntheticUserMessage } from "../memory/ai-sdk-message-storage.js";
 import { stripUnansweredToolCalls } from "../memory/tool-call-integrity.js";
@@ -70,7 +71,13 @@ export async function runAgent(agent, initial, session, opts) {
         session,
         signal,
         emit,
-        runStep: (name, fn) => runStep(`${formatStepName.tool(tu.toolName, tu.toolCallId)}:${name}`, fn),
+        runStep: (name, fn) => {
+            const stepName = `${formatStepName.tool(tu.toolName, tu.toolCallId)}:${name}`;
+            return runStep(stepName, () => {
+                stableSpan(stepName, `tool:${tu.toolName}:${name}`, { [ATTR_INFLEXA_TOOL_USE_ID]: tu.toolCallId });
+                return fn();
+            });
+        },
         ask,
         turnUsage,
     });
@@ -540,7 +547,11 @@ async function dispatchTools(toolUses, toolsById, toolCtx, isFatalLoopError, run
     }
     await Promise.all(stepTools.map(({ tu, idx }) => {
         const startedAt = performance.now();
-        return runStep(toolStepName(tu.toolName, tu.toolCallId), () => dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError, encoding)).then((settled) => {
+        const stepName = toolStepName(tu.toolName, tu.toolCallId);
+        return runStep(stepName, () => {
+            stableSpan(stepName, `tool:${tu.toolName}`, { [ATTR_INFLEXA_TOOL_USE_ID]: tu.toolCallId });
+            return dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError, encoding);
+        }).then((settled) => {
             durations[idx] = elapsedMs(startedAt);
             const dispatched = readDispatchedStep(settled);
             results[idx] = dispatched.result;

package/dist/prompts/planner.js

@@ -167,6 +167,12 @@ Every step carries a \`packages\` array — the packages its scripts import.
   one exact version (\`"numpy==1.26.4"\`). Never a path, a URL, or a store
   directory — a location is an installer detail, and validation refuses it.
 - An empty array is valid: the step needs nothing beyond the baked toolchain.
+- When the package census shows one name under a Python section AND under an R
+  section, write the prefixed form the census shows: \`"python:igraph"\` or
+  \`"r:igraph"\`. A bare name that both tracks hold refuses the launch, because
+  the pool cannot tell which package you mean.
+- Write a bare name for every other package. The prefix is for a both-track
+  name only.
 - The set is not a promise of completeness. The execution agent can still link a
   missing package mid-step. Name what you know the step imports; do not pad the
   list defensively.

package/dist/prompts/sandbox-standards.d.ts

@@ -42,5 +42,5 @@ export declare function sandboxOrientCorePromptFor(toolchainSource: ToolchainSou
  * constant, thus the prompt stays byte-identical across the steps of one
  * composition.
  */
-export declare const sandboxPackageLinkPrompt = "# Linking Packages\n\nThe host keeps a pool of staged packages beside the farm of this analysis \u2014 the\npool is part of what the host staged before this container started. The\n`link_packages` tool links a staged package into your farm \u2014 live, with no\nrestart. A link adds no new bytes and downloads nothing; it connects your farm\nto a directory that is already on the mount. So a package your farm lacks is\nnot missing until the pool has answered:\n\n- After a failed import, and when `list_available_packages` reports a package\n  absent, call `link_packages` with the module name verbatim.\n- `linked` and `present` mean the import works now \u2014 run it again.\n- `absent` is a real answer: the pool does not hold the package. When\n  `acquisitionPossible` is true, report the package as missing so the host can\n  acquire it. Do not retry the link, and do not attempt an install.\n- `collision` is terminal for that package: the request resolves to two store\n  directories. Report it and continue without the package.\n- Report a package as missing only after `link_packages` answered `absent` or\n  `unavailable` for it.\n";
+export declare const sandboxPackageLinkPrompt = "# Linking Packages\n\nThe host keeps a pool of staged packages beside the farm of this analysis \u2014 the\npool is part of what the host staged before this container started. The\n`link_packages` tool links a staged package into your farm \u2014 live, with no\nrestart. A link adds no new bytes and downloads nothing; it connects your farm\nto a directory that is already on the mount. So a package your farm lacks is\nnot missing until the pool has answered:\n\n- After a failed import, and when `list_available_packages` reports a package\n  absent, call `link_packages` with the module name verbatim. Each entry is\n  `[python:|r:]<name>[==<version>]`, and a bare name searches both tracks.\n- `linked` and `present` mean the import works now \u2014 run it again.\n- `absent` is a real answer: the pool does not hold the package. When\n  `acquisitionPossible` is true, report the package as missing so the host can\n  acquire it. Do not retry the link, and do not attempt an install.\n- `collision` means the request resolved to two store directories. When one\n  name is held by both tracks, call `link_packages` again for that package\n  with the prefixed form, `python:<name>` or `r:<name>`.\n- Drop the package only after that second call also refuses. A collision of two\n  versions of one distribution is terminal at once: report it and continue\n  without the package.\n- Report a package as missing only after `link_packages` answered `absent` or\n  `unavailable` for it.\n";
 export declare const sandboxAnalysisStepStandardsPrompt = "# Sandbox Analysis-Step Conventions\n\nThese apply to plannable analysis steps \u2014 agents that produce reproducible\nscript + output + figure artifacts. They do NOT apply to data profiling or\nreport building (those agents opt out via\n`appendAnalysisStepStandards: false`).\n\n## Language Policy\n\nPython is the DEFAULT language. Use R when:\n(a) No adequate Python equivalent (e.g. minfi, ANCOM-BC2, ChAMP).\n(b) The R implementation is significantly more mature.\n(c) The task explicitly requires an R-only package.\n\nChoose native R or rpy2 based on scope:\n- **Isolated R calls** in a Python pipeline \u2192 rpy2 bridge.\n  Example: DESeq2 for one DE step, fgsea for enrichment.\n- **R-dominant pipeline** where most steps use R packages \u2192 write\n  **native R scripts**. Do not wrap an entire R pipeline in rpy2.\n  Examples: microbiome (DADA2 \u2192 phyloseq \u2192 vegan \u2192 ANCOM-BC2),\n  DNA methylation (minfi \u2192 ChAMP \u2192 DMRcate), untargeted metabolomics\n  (XCMS \u2192 CAMERA).\n\nNative R scripts follow the same standards as Python: structured logging\n(`message()`), named constants, documented functions. Save final outputs\nas CSV (and optionally AnnData) for cross-agent consumption.\n\n## Data Format Standards\n\n- **AnnData (.h5ad)** is the UNIVERSAL container for sample-by-feature\n  data across ALL modalities \u2014 bulk RNA-seq, proteomics, metabolomics,\n  microarray, methylation, single-cell. Samples in `.obs`, features in\n  `.var`, values in `.X`, layers in `.layers`, embeddings in `.obsm`,\n  unstructured results in `.uns`.\n- **MuData (.h5mu)** for multi-modal data (CITE-seq, Multiome,\n  multi-omics integration).\n- Store sample metadata in `.obs`, feature annotations in `.var`. Do\n  NOT write separate metadata CSV files unless explicitly needed.\n- **Intermediate analysis objects**: save as `.h5ad` or `.h5mu`. Do\n  NOT save as `.rds` or `.pkl`. When R packages produce R objects\n  (DESeqDataSet, phyloseq, SingleCellExperiment), convert key results\n  back to AnnData or pandas.\n- **Tabular results**: CSV with human-readable column names\n  (`log2_fold_change`, `adjusted_pvalue`, not `lfc`/`padj`).\n- **Genomic data**: VCF/BED/BAM are acceptable primary containers.\n  Derived summary statistics go in AnnData or CSV.\n- **Dual-format output**: when producing modality-specific results,\n  also output a generic CSV for downstream cross-cutting agents.\n\n## Figure Standards\n\n- **PNG at 300 DPI** for preview AND **PDF (vector)** for publication,\n  same base filename with different extensions.\n- **Colorblind-safe palettes** \u2014 viridis family as default. Never use\n  red-green as the sole distinguishing feature.\n- **Clean minimal themes**: matplotlib `seaborn-v0_8-whitegrid` or\n  equivalent; ggplot2 `theme_classic()` or `theme_minimal()`.\n- **Complete labels**: title, axis labels with units, legend.\n- **Statistical annotations** where applicable (p-values, significance\n  brackets, effect sizes).\n- No default matplotlib/ggplot styling, no cut-off labels, no\n  overlapping text.\n\n## Directory Structure\n\nYour working directory has five subdirectories \u2014 write each kind of artifact\nto its own (paths are relative to your working directory):\n\n```\nscripts/    Analysis scripts (.py, .R)\noutput/     Results: CSV, AnnData (.h5ad), MuData (.h5mu), JSON\nfigures/    Visualizations: PNG (300 DPI) + PDF (vector), same base name\nlogs/       Execution logs from long-running commands\nnotebooks/  Reserved (currently unused)\n```\n\nPut data results in `output/`, not at the working-directory root. For\nlong-running commands, redirect stdout/stderr to a file in `logs/`:\n```python\nsubprocess.run(cmd, stdout=open(\"logs/deseq2_run.log\", \"w\"), stderr=subprocess.STDOUT)\n```\n\n## Code Quality\n\n**Functions** for any non-trivial logic. Each logical operation\n(load, QC, fit, plot) gets its own function with a docstring. Top-level\nscript flow should read like an outline \u2014 call functions, not inline\nlogic.\n\n```python\n# %% [markdown]\n# ## Differential Expression\n\n# %%\ndef run_deseq2(counts: pd.DataFrame, metadata: pd.DataFrame, design: str) -> pd.DataFrame:\n    \"\"\"Run DESeq2 via rpy2 and return results as a DataFrame.\"\"\"\n    ...\n\nde_results = run_deseq2(counts, metadata, \"~ condition + batch\")\n```\n\n**Structured logging**, not `print()`:\n\n- Python \u2014 `logging.getLogger()`:\n  `logger.info(\"Loaded %d samples, %d genes\", n_samples, n_genes)`\n- R \u2014 `message()` / `warning()`:\n  `message(sprintf(\"Loaded %d samples\", n_samples))`\n\nReserve `print()` / `cat()` for intentional data display in notebook\ncells only.\n\n**Validate at function boundaries**. Fail fast with clear messages.\nUse `try/except` only when recovery is meaningful.\n\n**Type hints** on Python function signatures. Add them \u2014 they document\nintent and catch mistakes early.\n\n**Named constants** for thresholds, cutoffs, parameters in the first\ncode cell:\n```python\n# %% Parameters\nRANDOM_SEED = 42\nFDR_THRESHOLD = 0.05\nMIN_LOG2FC = 1.0\n```\n\n**R specifics**: load packages at the top (never inside functions).\nUse `<-` for assignment. Use `message()` / `warning()` not `cat()` /\n`print()`.\n\n## Scripts\n\n- Start with a header comment (title + description).\n- Parameters go in the first code block.\n- Set random seeds for reproducibility.\n- Scripts must be independently re-runnable.\n- **Lint Python scripts with `ruff check <script.py>`** via\n  `execute_command` before executing. `ruff` is pre-installed. This\n  catches import errors, undefined names, and common bugs early.\n\n## Cleanup\n\nWhen a script fails, delete the failed script from `scripts/` and any\npartial output files before writing a corrected version. Only final\nworking scripts should remain. Use `list_files` to verify.\n\n## Interpretation & Literature Grounding\n\nGround findings in the research literature as you work \u2014 not as a\nfinal step:\n\n1. When you identify a significant finding (DE genes, enriched\n   pathways, hub genes, quality issues), search PubMed with\n   `pubmed({action:\"search\"})`.\n2. For relevant hits, call `pubmed({action:\"details\"})` for abstracts and\n   PMIDs. Note short citations (e.g. \"Smith et al., Nature 2023\").\n3. Assess novelty per finding: **novel** (searched, nothing found),\n   **confirmed** (directly supported), **partially confirmed**,\n   **contradicted**, **expected** (domain knowledge, no citation\n   needed).\n4. Document the search even when no references are found. \"Novel\"\n   means you looked and found nothing \u2014 not that you didn't look.\n\nYour structured output captures this interpretation. It is your\nscientific assessment of what the results mean.\n\n## Analysis-Step Anti-Patterns\n\n- **Ignoring script errors.** Read the error, diagnose the root\n  cause, fix the script. Do not move on.\n- **Placeholder or dummy output.** If an analysis cannot produce\n  meaningful results, report the reason clearly instead of faking\n  results.\n- **Monolithic scripts.** Keep scripts under 300 lines. Split into\n  logical sections with markdown annotations.\n- **`print()` for logging.** Use `logging` (Python) or `message()`\n  (R). `print()` is for intentional data display only.\n- **Inline logic without functions.** Wrap non-trivial operations in\n  functions with docstrings and typed parameters.\n- **Magic numbers.** Define thresholds and cutoffs as named constants.\n";

package/dist/prompts/sandbox-standards.js

@@ -312,13 +312,18 @@ to a directory that is already on the mount. So a package your farm lacks is
 not missing until the pool has answered:
 
 - After a failed import, and when \`list_available_packages\` reports a package
-  absent, call \`link_packages\` with the module name verbatim.
+  absent, call \`link_packages\` with the module name verbatim. Each entry is
+  \`[python:|r:]<name>[==<version>]\`, and a bare name searches both tracks.
 - \`linked\` and \`present\` mean the import works now — run it again.
 - \`absent\` is a real answer: the pool does not hold the package. When
   \`acquisitionPossible\` is true, report the package as missing so the host can
   acquire it. Do not retry the link, and do not attempt an install.
-- \`collision\` is terminal for that package: the request resolves to two store
-  directories. Report it and continue without the package.
+- \`collision\` means the request resolved to two store directories. When one
+  name is held by both tracks, call \`link_packages\` again for that package
+  with the prefixed form, \`python:<name>\` or \`r:<name>\`.
+- Drop the package only after that second call also refuses. A collision of two
+  versions of one distribution is terminal at once: report it and continue
+  without the package.
 - Report a package as missing only after \`link_packages\` answered \`absent\` or
   \`unavailable\` for it.
 `;

package/dist/runtime/dbos.d.ts

@@ -55,13 +55,14 @@ export interface DbosConfig {
      * Attribute names follow the `dbos.*` semantic-convention layout
      * (`otelAttributeFormat: "semconv"`).
      *
-     * Known SDK behavior a host must plan for:
-     * - a recovered workflow starts a new root trace, with no link to the trace
-     *   of the original execution
-     * - every already-completed step re-emits a `cached=true` span on replay,
-     *   so a restart with many in-flight steps bursts spans; size
-     *   `OTEL_BSP_MAX_QUEUE_SIZE` for it
-     * - step span names embed the step, tool-use, or exec id
+     * The harness TracerProvider shapes what the SDK emits (`lib/otel-spans.ts`):
+     * a workflow declared with `untracedWorkflow` is not recorded, a replayed
+     * `cached=true` span is dropped before export, and a step body that calls
+     * `stableSpan` is exported under a stable name with its id in an
+     * `inflexa.*` attribute. The step name DBOS records is unchanged.
+     *
+     * Known SDK behavior a host must plan for: a recovered workflow starts a
+     * new root trace, with no link to the trace of the original execution.
      */
     readonly tracingEnabled?: boolean;
 }

package/dist/sandbox/await-exec.js

@@ -55,6 +55,7 @@
  * varied between replays would desynchronise the recorded function-ID sequence.
  */
 import { DBOS } from "@dbos-inc/dbos-sdk";
+import { ATTR_INFLEXA_ATTEMPT, ATTR_INFLEXA_EXEC_ID, stableSpan } from "../lib/otel-spans.js";
 import { digestBody } from "./digest.js";
 import { signCallback, verifyCallback } from "./hmac.js";
 import { createEscalationPolicy, probeLiveness, syntheticFailureReason, syntheticFailureResult } from "./liveness.js";
@@ -182,9 +183,11 @@ export async function awaitExecCallback(ref, execId, emit, deadlineMs, options =
     /** Ask the sandbox directly. Returns null when the exec has not finished. */
     const pull = async () => {
         pullAttempt += 1;
-        const pulled = await runStep(() => pullExecResult(fetchImpl, ref, execId), {
-            name: `sandbox.pull-exec-result.${execId}.${pullAttempt}`,
-        });
+        const pullStepName = `sandbox.pull-exec-result.${execId}.${pullAttempt}`;
+        const pulled = await runStep(() => {
+            stableSpan(pullStepName, "sandbox.pull-exec-result", { [ATTR_INFLEXA_EXEC_ID]: execId, [ATTR_INFLEXA_ATTEMPT]: pullAttempt });
+            return pullExecResult(fetchImpl, ref, execId);
+        }, { name: pullStepName });
         if (pulled.kind !== "completed")
             return null;
         // Identical treatment to a pushed completion: the bytes were signed by
@@ -341,9 +344,11 @@ export async function awaitExecPoll(ref, execId, emit, deadlineMs, options = {})
     let probeAttempt = 0;
     while (true) {
         pollAttempt += 1;
-        const polled = await runStep(() => pollExecOnce(fetchImpl, ref, execId, cursor), {
-            name: `sandbox.poll-exec-result.${execId}.${pollAttempt}`,
-        });
+        const pollStepName = `sandbox.poll-exec-result.${execId}.${pollAttempt}`;
+        const polled = await runStep(() => {
+            stableSpan(pollStepName, "sandbox.poll-exec-result", { [ATTR_INFLEXA_EXEC_ID]: execId, [ATTR_INFLEXA_ATTEMPT]: pollAttempt });
+            return pollExecOnce(fetchImpl, ref, execId, cursor);
+        }, { name: pollStepName });
         if (polled.kind === "ok") {
             // Identical treatment to a pushed completion: the bytes were signed by
             // the same secret, so a forgery is as fatal here as it is there.
@@ -385,9 +390,11 @@ export async function awaitExecPoll(ref, execId, emit, deadlineMs, options = {})
         }
         if (isAlive && escalation.onPoll(polled.kind === "ok" ? "ok" : "unavailable")) {
             probeAttempt += 1;
-            const verdict = await runStep(() => probeLiveness(isAlive, ref), {
-                name: `sandbox.probe-liveness.${execId}.${probeAttempt}`,
-            });
+            const probeStepName = `sandbox.probe-liveness.${execId}.${probeAttempt}`;
+            const verdict = await runStep(() => {
+                stableSpan(probeStepName, "sandbox.probe-liveness", { [ATTR_INFLEXA_EXEC_ID]: execId, [ATTR_INFLEXA_ATTEMPT]: probeAttempt });
+                return probeLiveness(isAlive, ref);
+            }, { name: probeStepName });
             // Only an observably dead machine fails the exec — the result lives
             // in that machine and nowhere else, so it is unrecoverable and the
             // synthetic failure races nothing. `alive` (live-but-slow exec,

package/dist/sandbox/notification-sweep.js

@@ -18,7 +18,9 @@
  */
 import { DBOS } from "@dbos-inc/dbos-sdk";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { untracedWorkflow } from "../lib/otel-spans.js";
 const SWEEP_CRON = "0 */5 * * * *";
+const SWEEP_WORKFLOW = "dbos-notifications-sweep";
 const DELETE_BATCH_LIMIT = 10_000;
 export async function sweepStaleNotifications(deps) {
     const logger = (deps.logger ?? createNoopLogger()).named("notification-sweep");
@@ -68,9 +70,10 @@ export function registerNotificationSweep(deps) {
     // a workflow registration. Register, then schedule the same callable.
     const sweep = DBOS.registerWorkflow(async () => {
         await sweepStaleNotifications({ deleteStale, logger: deps.logger });
-    }, { name: "dbos-notifications-sweep" });
+    }, { name: SWEEP_WORKFLOW });
+    untracedWorkflow(SWEEP_WORKFLOW);
     DBOS.registerScheduled(sweep, {
-        name: "dbos-notifications-sweep",
+        name: SWEEP_WORKFLOW,
         crontab: SWEEP_CRON,
     });
 }

package/dist/sandbox/package-identity.d.ts

@@ -0,0 +1,208 @@
+/**
+ * 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 { type Result } from "neverthrow";
+/** The two ecosystems that the pool holds. */
+export type Track = "python" | "r";
+/**
+ * What a person or an agent asked for. `spelling` is the name verbatim, as the
+ * caller wrote it — a remedy quotes it, and an R name is case-sensitive at
+ * `library()`. `track` names one ecosystem, and its absence searches both.
+ * `version` pins one exact version.
+ *
+ * A query is never a key. Two queries of one fold are two asks, because a
+ * caller that wrote `decoupleR` did not ask for `decoupler`.
+ */
+export type PackageQuery = {
+    readonly spelling: string;
+    readonly track?: Track;
+    readonly version?: string;
+};
+/**
+ * The brand of an identity name. It has no runtime value: it exists so that a
+ * literal `{ track, name }` fails the typecheck outside this module, and thus
+ * every identity comes from a constructor that applied the rule of its track.
+ */
+declare const identityBrand: unique symbol;
+/**
+ * The name that one ecosystem recognizes, under the track that holds it.
+ *
+ * The name of a Python identity is the PEP 503 fold of the spelling, because
+ * PEP 503 defines the equivalence of a distribution name. The name of an R
+ * identity is the DESCRIPTION spelling, verbatim, because `library()` is
+ * case-sensitive. Two identities are equal when their keys are equal.
+ */
+export type PackageIdentity = {
+    readonly track: Track;
+    readonly name: string & {
+        readonly [identityBrand]: true;
+    };
+};
+/**
+ * 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 declare function pythonIdentity(spelling: string): PackageIdentity;
+/**
+ * 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 declare function rIdentity(name: string): PackageIdentity;
+/**
+ * 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 declare function identityOf(track: Track, name: string): PackageIdentity;
+/**
+ * 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 declare function identityKey(identity: PackageIdentity): string;
+/**
+ * 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 declare function parseIdentityKey(key: string): PackageIdentity | undefined;
+/**
+ * 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 declare function identityAddress(identity: PackageIdentity): string;
+/**
+ * Why an entry is not a query.
+ *
+ * - `empty` — the entry names no package.
+ * - `location` — a path, a URL, or a store directory. A location is an
+ *   installer detail, and the pool resolves names.
+ * - `unknown_prefix` — a `<word>:` prefix that is neither `python:` nor `r:`.
+ *   Unrefused, such a prefix rides into the pool as part of the name.
+ * - `unsupported_specifier` — a specifier that is not `==`. Unrefused, a range
+ *   such as `numpy>=1.26` becomes a package name.
+ */
+export type ParseQueryError = {
+    readonly type: "empty";
+} | {
+    readonly type: "location";
+    readonly entry: string;
+} | {
+    readonly type: "unknown_prefix";
+    readonly prefix: string;
+    readonly entry: string;
+} | {
+    readonly type: "unsupported_specifier";
+    readonly specifier: string;
+    readonly entry: string;
+};
+/**
+ * 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 declare function parseQuery(entry: string): Result<PackageQuery, ParseQueryError>;
+/**
+ * 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 declare function formatQuery(query: PackageQuery): string;
+/**
+ * What a pool answers about the identities that it holds. Two reads are
+ * enough for the ladder, thus a caller builds this over a graph, a lock, or a
+ * census without exposing its own shape.
+ */
+export type PoolIndex = {
+    /** Whether the pool holds this exact identity. */
+    has: (identity: PackageIdentity) => boolean;
+    /**
+     * Each R identity of the pool whose address is this fold. The suggestion
+     * of an unknown query comes from here: a person who wrote `seurat` meant
+     * the R package `Seurat`.
+     */
+    rIdentitiesFoldingTo: (fold: string) => readonly PackageIdentity[];
+};
+/**
+ * What a query resolves to.
+ *
+ * - `resolved` — one identity, thus the caller reads the pool under it.
+ * - `ambiguous` — one spelling that both tracks hold. The caller refuses, and
+ *   the remedy is a prefixed query.
+ * - `unknown` — the pool holds no identity of this query. `suggestion` names
+ *   the R identity that the caller probably meant.
+ */
+export type QueryResolution = {
+    readonly kind: "resolved";
+    readonly identity: PackageIdentity;
+} | {
+    readonly kind: "ambiguous";
+    readonly python: PackageIdentity;
+    readonly r: PackageIdentity;
+} | {
+    readonly kind: "unknown";
+    readonly suggestion?: PackageIdentity;
+};
+/**
+ * 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 declare function resolveQuery(query: PackageQuery, pool: PoolIndex): QueryResolution;
+export {};