@galaxyproject/orbit 0.0.0 → 0.9.0

package/lessons/galaxy-api/403-history-is-a-hard-stop.md

@@ -0,0 +1,57 @@
+---
+type: Lesson
+title: '"History is not accessible by user" means there is no data to reason from'
+description: A 403 on the bound history means nothing about the job was ever read, so any explanation of the failure after that point is invented.
+tags: [permissions, history, fabrication, galaxy-api]
+status: stable
+generated: { by: "human:loom-maintainers", at: "2026-09-30" }
+stale_after: "2027-03-31"
+sources:
+  - { id: "loom#367" }
+
+kind: expectation
+stage: [job-execution, result-interpretation]
+trigger:
+  signatures: ["History is not accessible by user"]
+  tools: []
+  mcp_tools: [galaxy_get_history_contents]
+  formats: []
+  hosts: []
+  extensions: []
+  step_keywords: ["history", "why did it fail", "job failure"]
+cues: "A resumed notebook is bound to a history that the current credentials do not own."
+applies_to: { versions: "any", tested: "resumed notebook bound to a history owned by another account" }
+evidence:
+  symptom: verified
+  cause: verified
+  outcome: unvalidated
+  method: "transcript: a 403 followed by a fabricated explanation of a job failure"
+graduated_to: ["loom system prompt no-fabrication rule plus evals"]
+upstream: []
+supersedes: []
+---
+
+## Symptom
+
+Asked why a job failed, the agent gets a 403 on the history and answers anyway.
+
+## Cause
+
+The notebook's bound history belongs to a different account or server than the current
+credentials. Nothing about the job was ever read.
+
+## Check first
+
+Which account are the current credentials for? Is the bound history in that account's list?
+
+## Intervention
+
+Report the access failure. Offer to look in the user's own recent histories instead.
+
+## Validate
+
+Any explanation of a failure cites a job or dataset that was actually retrieved.
+
+## Does NOT apply when
+
+Never; a 403 is always a hard stop for reasoning about that history.

package/lessons/galaxy-api/collection-into-single-dataset-input.md

@@ -0,0 +1,61 @@
+---
+type: Lesson
+title: 'A collection handed to a single-dataset input is rejected; the answer is map-over, not "the API cannot"'
+description: A 400 at submit when an hdca meets a single-dataset parameter means map-over was not requested, and the wrong conclusion is that collections cannot be used through the API.
+tags: [collections, map-over, batch, galaxy-api]
+status: stable
+generated: { by: "human:loom-maintainers", at: "2026-09-30" }
+stale_after: "2027-03-31"
+sources:
+  - { id: "loom#208" }
+
+kind: choice
+stage: [tool-parameterization]
+trigger:
+  signatures: ["supplied to single input dataset parameter"]
+  tools: []
+  mcp_tools: [galaxy_run_tool]
+  formats: []
+  hosts: []
+  extensions: []
+  step_keywords: ["collection", "map over", "batch", "per sample"]
+cues: "A collection is being passed where the tool's input template says one dataset."
+applies_to: { versions: "any", tested: "featureCounts, Filter1 via galaxy-mcp run_tool" }
+evidence:
+  symptom: verified
+  cause: verified
+  outcome: validated
+  method: "the batch wrapper form was accepted by Galaxy and produced a mapped-over output collection"
+graduated_to: ["loom context.ts Galaxy block map-over hint"]
+upstream: ["galaxy-mcp actionable-error issue"]
+supersedes: []
+---
+
+## Symptom
+
+400 at submit when an `hdca` is passed where the tool expects one dataset. Observed follow-on: the
+agent concludes collections cannot be built or used through the API, which is false.
+
+## Cause
+
+The input is a single-dataset parameter. Galaxy runs such a tool over a collection only when asked
+to map over it.
+
+## Check first
+
+Is the input really single-dataset per the tool's input template, and is the thing being passed a
+collection? If the collection is `list:paired` and the tool wants one sample, map-over is still the
+answer but the element type must match.
+
+## Intervention
+
+Submit the input in batch form: `{batch: true, values: [{src: "hdca", id: <collection id>}]}`.
+
+## Validate
+
+The result is a collection with one element per input element, and element identifiers are
+preserved.
+
+## Does NOT apply when
+
+The tool has a genuine multi-dataset or collection input -- pass the collection directly there.

package/lessons/galaxy-api/connectedvalue-in-command-line.md

@@ -0,0 +1,62 @@
+---
+type: Lesson
+title: '"ConnectedValue object at 0x" in a command line means an optional workflow parameter was left unset'
+description: Older Galaxy serialized the placeholder object's repr into the command line when a connected optional parameter_input had no value, so the step can fail or silently succeed wrong.
+tags: [workflows, parameter-input, command-line, galaxy-api]
+status: stable
+generated: { by: "human:loom-maintainers", at: "2026-09-30" }
+stale_after: "2027-03-31"
+sources:
+  - { id: "loom#186" }
+  - { id: "galaxy#21994" }
+
+kind: pitfall
+stage: [tool-parameterization, job-execution]
+trigger:
+  signatures: ["workflow_utils.ConnectedValue object at 0x"]
+  tools: []
+  mcp_tools: [galaxy_invoke_workflow]
+  formats: []
+  hosts: []
+  extensions: []
+  step_keywords: ["workflow", "parameter input", "optional parameter", "invoke"]
+cues: "A workflow with optional parameter inputs is invoked against a server older than the upstream fix."
+applies_to: { versions: "Galaxy older than 25.1.2; fixed upstream", tested: "fastp inside an invoked workflow" }
+evidence:
+  symptom: verified
+  cause: verified
+  outcome: unvalidated
+  method: "the error string was quoted from the failing job and the upstream fix was identified"
+graduated_to: ["galaxy-skills galaxy-mcp-reference gotchas note"]
+upstream: ["galaxy#21994"]
+supersedes: []
+---
+
+## Symptom
+
+A workflow step fails, or worse succeeds, with a tool argument containing the text
+`...ConnectedValue object at 0x...`. With fastp it surfaced as an invalid adapter sequence.
+
+## Cause
+
+An optional `parameter_input` workflow step was connected but given no value; older Galaxy
+serialized the placeholder object's repr into the command line.
+
+## Check first
+
+Does the workflow have optional parameter inputs, per the workflow details? Is the server older
+than the fix? Inspect the failed job's command line for the signature.
+
+## Intervention
+
+Pass an explicit empty value for every optional parameter input on invocation.
+
+## Validate
+
+Re-inspect the command line of the rerun job: the signature is gone AND the argument is absent or
+empty, not replaced by some other junk.
+
+## Does NOT apply when
+
+The server has the upstream fix. Keep the lesson and narrow the version range -- older installs
+still need it.

package/lessons/galaxy-api/hid-is-not-an-id.md

@@ -0,0 +1,59 @@
+---
+type: Lesson
+title: The number shown in the history panel is not a dataset id
+description: Users say "dataset 28", which is the hid; the API wants the encoded id, and run_tool reports the mismatch as a misleading missing-parameter error.
+tags: [hid, encoded-id, history, galaxy-api]
+status: stable
+generated: { by: "human:loom-maintainers", at: "2026-09-30" }
+stale_after: "2027-03-31"
+sources:
+  - { id: "loom#348" }
+  - { id: "loom#375" }
+
+kind: pitfall
+stage: [data-acquisition, tool-parameterization]
+trigger:
+  signatures: ["Invalid id length, must be multiple of 16", "Required parameter(s) kwd not provided"]
+  tools: []
+  mcp_tools: [galaxy_get_dataset_details, galaxy_run_tool]
+  formats: []
+  hosts: []
+  extensions: []
+  step_keywords: ["dataset number", "hid", "dataset id"]
+cues: "A short numeric identifier taken from what the user said is being passed where the API wants an encoded id."
+applies_to: { versions: "any", tested: "galaxy-mcp get_dataset_details, run_tool with cat1" }
+evidence:
+  symptom: verified
+  cause: verified
+  outcome: validated
+  method: "reproduced; resolving the hid to the encoded id fixed it"
+graduated_to: ["galaxy-skills galaxy-mcp-reference gotchas note"]
+upstream: []
+supersedes: []
+---
+
+## Symptom
+
+An id-length error, or -- from run_tool -- a misleading required-parameter error that says nothing
+about ids.
+
+## Cause
+
+Users say "dataset 28"; that is the `hid`. The API wants the encoded `id`.
+
+## Check first
+
+Is the id being passed short and numeric?
+
+## Intervention
+
+List the history contents and resolve the hid to an id. Confirm the name matches what the user
+meant.
+
+## Validate
+
+The call succeeds and the returned dataset's name and hid are the intended ones.
+
+## Does NOT apply when
+
+The id is already a 16-hex-multiple string -- then the missing-parameter error has another cause.

package/lessons/galaxy-api/invoke-workflow-inputs-not-params.md

@@ -0,0 +1,60 @@
+---
+type: Lesson
+title: 'Workflow input values, scalars included, go in `inputs`; `params` only overrides tool steps'
+description: A validation error pointing into parameters means the value is in the wrong slot, not under the wrong key, and retrying key forms is the trap that follows.
+tags: [workflows, invoke, inputs, galaxy-api]
+status: stable
+generated: { by: "human:loom-maintainers", at: "2026-09-30" }
+stale_after: "2027-03-31"
+sources:
+  - { id: "loom#392" }
+
+kind: pitfall
+stage: [tool-parameterization]
+trigger:
+  signatures: ["Input should be a valid dictionary"]
+  tools: []
+  mcp_tools: [galaxy_invoke_workflow]
+  formats: []
+  hosts: []
+  extensions: []
+  step_keywords: ["invoke", "workflow", "inputs", "params", "input template"]
+cues: "A workflow invocation is being retried with different key forms for the same value."
+applies_to: { versions: "unknown", tested: "galaxy-mcp invoke_workflow against a multi-sample IWC workflow" }
+evidence:
+  symptom: verified
+  cause: hypothesized
+  outcome: validated
+  method: "the same values succeeded first try when moved to inputs per the input template"
+graduated_to: ["galaxy-mcp get_workflow_input_template plus invoke_workflow preflight"]
+upstream: ["galaxy-mcp#55"]
+supersedes: []
+---
+
+## Symptom
+
+Invocation rejected with a validation error pointing into `parameters`. Observed: a model retried
+two dozen times varying the key -- label, step index, uuid -- while the real problem was the slot.
+
+## Cause
+
+Inferred, not checked against Galaxy source: every workflow input -- datasets, collections and
+scalar parameter inputs alike -- belongs in `inputs`. `params` overrides tool parameters on
+non-input steps and its values are dicts.
+
+## Check first
+
+Was the workflow input template fetched? Does the failing payload put a scalar under `params`?
+
+## Intervention
+
+Fetch the input template and fill it in as returned. Do not retry with a different key form; if the
+second attempt fails the same way, stop and re-read the template.
+
+## Validate
+
+The invocation is accepted and its recorded inputs match what was intended.
+
+## Does NOT apply when
+
+You really are overriding a tool step's parameter -- then `params` with a dict value is right.

package/lessons/galaxy-api/repeat-param-pipe-keys.md

@@ -0,0 +1,63 @@
+---
+type: Lesson
+title: Repeat-group tool params written with underscores are accepted but silently mis-applied
+description: Galaxy's flat parameter form addresses repeat members with a pipe; an underscore key is ignored rather than rejected, so the repeat falls back to defaults and the job still reports ok.
+tags: [repeat-params, tool-parameters, silent-failure, galaxy-api]
+status: stable
+generated: { by: "human:loom-maintainers", at: "2026-09-30" }
+stale_after: "2027-03-31"
+sources:
+  - { id: "loom#285" }
+  - { id: "loom#295" }
+
+kind: pitfall
+stage: [tool-parameterization, result-interpretation]
+trigger:
+  signatures: []
+  tools: [datamash_ops]
+  mcp_tools: [galaxy_run_tool]
+  formats: []
+  hosts: []
+  extensions: []
+  step_keywords: ["repeat", "operations", "aggregate", "group by"]
+cues: "Tool inputs contain keys shaped like name underscore number underscore field."
+applies_to: { versions: "unknown", tested: "Datamash via galaxy-mcp run_tool" }
+evidence:
+  symptom: verified
+  cause: hypothesized
+  outcome: unvalidated
+  method: "a wrong aggregate was observed; the pipe-form keys produced the expected one"
+graduated_to: ["loom docs repeat-parameter note", "galaxy-mcp tool input template"]
+upstream: ["galaxy-mcp#52"]
+supersedes: []
+---
+
+## Symptom
+
+A tool with a repeat block runs to `ok`, but the result reflects default or wrong repeat values --
+a different operation or column than requested. No error anywhere.
+
+## Cause
+
+Hypothesized: Galaxy's flat parameter form addresses repeat members as `block_0|field`. A key like
+`block_0_field` is not rejected; it is ignored, and the repeat falls back to defaults.
+
+## Check first
+
+Look at the inputs actually submitted. Any repeat member addressed with an underscore instead of a
+pipe? Compare the job's recorded parameters with what was intended.
+
+## Intervention
+
+Use the pipe form, for example `operations_0|op_name`, preferably taken verbatim from the tool's
+input template rather than constructed by hand.
+
+## Validate
+
+Read back the job's parameters and confirm the repeat values are the requested ones. Spot-check one
+output value by hand.
+
+## Does NOT apply when
+
+The tool errored at submit -- that is a different problem. Conditionals use the same pipe
+addressing but fail differently.

package/lessons/galaxy-api/run-tool-returns-on-submit.md

@@ -0,0 +1,61 @@
+---
+type: Lesson
+title: A successful run_tool response means queued, not finished
+description: Single-tool submission returns at queue time and there is no invocation object to poll, so nothing prompts the second look before the result is reported.
+tags: [job-states, polling, async, galaxy-api]
+status: stable
+generated: { by: "human:loom-maintainers", at: "2026-09-30" }
+stale_after: "2027-03-31"
+sources:
+  - { id: "loom#210" }
+  - { id: "loom#281" }
+  - { id: "loom#293" }
+
+kind: expectation
+stage: [job-execution]
+trigger:
+  signatures: []
+  tools: []
+  mcp_tools: [galaxy_run_tool, galaxy_run_user_tool]
+  formats: []
+  hosts: []
+  extensions: []
+  step_keywords: ["run tool", "submit", "job", "complete", "done"]
+cues: "About to report a tool run as done."
+applies_to: { versions: "any", tested: "galaxy-mcp" }
+evidence:
+  symptom: verified
+  cause: verified
+  outcome: validated
+  method: "the job was later found in an error state after the agent had reported success"
+graduated_to: ["loom async job poller", "loom job-status hint"]
+upstream: []
+supersedes: []
+---
+
+## Symptom
+
+The agent reports an analysis step complete; the job is still running or has since errored.
+
+## Cause
+
+Single-tool submission returns at queue time. Unlike a workflow invocation there is no invocation
+object to poll, so nothing prompts a second look.
+
+## Check first
+
+Has the job reached a terminal state? `ok` is success; `error`, `failed` and `deleted` are not;
+`paused` and `waiting` are not terminal.
+
+## Intervention
+
+Poll the job to a terminal state before building on its outputs or reporting it.
+
+## Validate
+
+Terminal `ok`, and the expected outputs exist and are non-empty.
+
+## Does NOT apply when
+
+Never. Caveat: reaching the job via an output dataset does not work for jobs with no outputs,
+collection-only outputs, or map-over runs where one call makes many jobs.

package/lessons/galaxy-tools/reference-index-not-on-server.md

@@ -0,0 +1,62 @@
+---
+type: Lesson
+title: A tool's built-in reference option is useless on a server that has no indexes for it
+description: The cached-reference branch of a tool offers nothing when the server's data table is empty, and through a workflow the invocation validates and every sample fails minutes later.
+tags: [reference-genome, data-tables, server-dependent, star]
+status: draft
+generated: { by: "human:loom-maintainers", at: "2026-09-30" }
+stale_after: "2027-03-31"
+sources:
+  - { id: "loom#198" }
+  - { id: "galaxy-mcp#62" }
+
+kind: choice
+stage: [tool-parameterization]
+trigger:
+  signatures: ["requires a value, but no legal values defined"]
+  tools: [rna_starsolo, rna_star]
+  mcp_tools: []
+  formats: []
+  hosts: []
+  extensions: [".fasta", ".fa", ".gtf"]
+  step_keywords: ["reference", "genome", "index", "built-in", "cached", "genomedir"]
+cues: "The tool offers a choice between a cached or built-in reference and one from the history."
+applies_to: { versions: "any; depends on the server's data tables", tested: "STARsolo on a server with no STAR indexes" }
+evidence:
+  symptom: verified
+  cause: verified
+  outcome: unvalidated
+  method: "the 400 at submit was quoted, and the server was confirmed to have zero indexes for the tool"
+graduated_to: []
+upstream: ["galaxy-mcp#62"]
+supersedes: []
+---
+
+## Symptom
+
+`Parameter 'genomeDir': requires a value, but no legal values defined` at submit. Through a
+workflow it is worse: the invocation validates, and the failure shows up minutes later as a bare
+tool error on every sample.
+
+## Cause
+
+The use-a-built-in-index branch of the tool was selected, and this server's data table for that
+tool is empty.
+
+## Check first
+
+Does the select parameter for the built-in reference have any options on this server?
+
+## Intervention
+
+Switch to the history-reference branch and supply a FASTA, and an annotation where the tool needs
+one, or run on a server that has the index.
+
+## Validate
+
+The job reaches `ok`, and the mapping rate is plausible for the organism -- a wrong reference also
+"works".
+
+## Does NOT apply when
+
+The select has options and the chosen value is not among them -- that is a wrong-value problem.

package/lessons/log.md

@@ -0,0 +1,42 @@
+# Lesson log
+
+OKF keeps a `log.md` beside the content as the corpus's audit trail. One entry
+per change to what the corpus _says_, newest last. A reformat, a script change
+or a snapshot rebuild is not an entry; a lesson added, retired, re-scoped or
+re-verified is.
+
+## 2026-09-30 -- schema v1, thirteen seed lessons
+
+By: human:loom-maintainers
+
+Opened the corpus with the thirteen seed lessons written on 2026-09-17, ported
+from the draft v0 schema to v1. The port renamed `editorial` to `status`, moved
+`evidence.provenance` into OKF `sources`, split the single v0 `cues` list into a
+prose `cues` string plus the machine-matchable `trigger` sub-fields
+(`mcp_tools`, `hosts`, `extensions`, `step_keywords`), dropped the `schema`, `id`
+and `revision` fields (the path is the id), and added `description`, `kind`,
+`generated` and `stale_after`. All thirteen carry `stale_after: 2027-03-31`.
+
+Added, `status: draft`:
+
+- `stats/na-coerced-to-zero-in-filters`
+- `stats/de-contrast-direction-and-sample-labels`
+- `reproduction/input-population-mismatch`
+- `reproduction/methods-text-vs-executed-parameters`
+- `data/downloaded-file-is-not-what-its-extension-says`
+- `galaxy-tools/reference-index-not-on-server`
+
+Added, `status: stable` with `graduated_to` filled, so they are kept for the
+record and never surfaced:
+
+- `galaxy-api/403-history-is-a-hard-stop`
+- `galaxy-api/collection-into-single-dataset-input`
+- `galaxy-api/connectedvalue-in-command-line`
+- `galaxy-api/hid-is-not-an-id`
+- `galaxy-api/invoke-workflow-inputs-not-params`
+- `galaxy-api/repeat-param-pipe-keys`
+- `galaxy-api/run-tool-returns-on-submit`
+
+Two further seeds were written in September and are deliberately not here: both
+describe a case nobody has a real instance of yet, and a lesson without an
+observed instance is a guess.

package/lessons/reproduction/input-population-mismatch.md

@@ -0,0 +1,59 @@
+---
+type: Lesson
+title: A faithful rerun can still be wrong when a normalizing step was fed a pre-filtered subset
+description: A statistic normalized over its input is wrong if the input was hand-picked, and the rerun reproduces the error exactly, so provenance alone will never catch it.
+tags: [reproduction, normalization, denominator, audit]
+status: draft
+generated: { by: "human:loom-maintainers", at: "2026-09-30" }
+stale_after: "2027-03-31"
+sources: []
+
+kind: reproduction
+stage: [data-acquisition, tool-parameterization, result-interpretation]
+trigger:
+  signatures: []
+  tools: []
+  mcp_tools: []
+  formats: []
+  hosts: []
+  extensions: []
+  step_keywords: ["reproduce", "reproducing", "reproduction", "posterior", "fdr", "enrichment", "percentile", "rank", "normalize", "credible set"]
+cues: "Reproducing a published analysis where a step computes a normalized quantity -- posterior, FDR, enrichment, rank, percentile."
+applies_to: { versions: "n/a", tested: "one audited reproduction of a fine-mapping analysis" }
+evidence:
+  symptom: verified
+  cause: verified
+  outcome: unvalidated
+  method: "traced by reading the job's actual inputs; the denominator differed from the full set"
+graduated_to: []
+upstream: []
+supersedes: []
+---
+
+## Symptom
+
+Results are close to the paper's but not equal: a set has a few members more or fewer, and every
+downstream value drifts by a few percent in the same direction.
+
+## Cause
+
+A statistic normalized over its input, here posterior probabilities, was computed over a
+hand-picked subset. The tool ran correctly. Rerunning reproduces the error, so provenance alone
+will not catch it.
+
+## Check first
+
+For every normalizing step: how many records went in, and how many does the method assume? Compare
+against the paper's stated N.
+
+## Intervention
+
+Feed the step the full population; filter afterwards.
+
+## Validate
+
+Input count matches the method's stated population, and the set membership matches the paper.
+
+## Does NOT apply when
+
+The step's output for one record does not depend on the others.

package/lessons/reproduction/methods-text-vs-executed-parameters.md

@@ -0,0 +1,62 @@
+---
+type: Lesson
+title: When a rerun cannot find what the paper reports, compare the Methods parameters to the executed ones
+description: A missing peak or row, or a uniform few-percent drift with ranks intact, is usually a window, threshold, top-N or version difference rather than a failed reproduction.
+tags: [reproduction, parameters, versions, methods]
+status: draft
+generated: { by: "human:loom-maintainers", at: "2026-09-30" }
+stale_after: "2027-03-31"
+sources: []
+
+kind: reproduction
+stage: [metadata-reconciliation, result-interpretation]
+trigger:
+  signatures: []
+  tools: []
+  mcp_tools: []
+  formats: []
+  hosts: []
+  extensions: []
+  step_keywords: ["reproduce", "reproducing", "reproduction", "methods", "paper", "missing", "not found", "threshold", "window", "top-n", "version"]
+cues: "Reproducing a published analysis where a reported feature, row or peak is absent from the rerun."
+applies_to: { versions: "n/a", tested: "one audited reproduction" }
+evidence:
+  symptom: verified
+  cause: verified
+  outcome: unvalidated
+  method: "each discrepancy traced to a specific parameter or version difference"
+graduated_to: []
+upstream: []
+supersedes: []
+---
+
+## Symptom
+
+A table row, peak or feature from the paper is not in the rerun's output at all; or scores are
+systematically a few percent off with ranks preserved.
+
+## Cause
+
+Four observed varieties: a window or range parameter narrower than the Methods describe, so the
+feature lies outside what was scanned; a summary step's top-N or threshold dropping it; a tool
+revision changing output columns; a model or tool version change shifting values uniformly.
+
+## Check first
+
+Tabulate Methods-stated versus executed values for windows, thresholds, top-N limits and versions.
+Is the missing item outside a range or below a cutoff? Is the drift uniform with ranks intact?
+
+## Intervention
+
+Rerun with the Methods' parameters if they differ. If versions differ and cannot be matched, report
+the drift as version drift, with its size, rather than as a failed reproduction.
+
+## Validate
+
+The missing item appears under the Methods' parameters, or its absence is explained by a named
+parameter. Say which.
+
+## Does NOT apply when
+
+Parameters and versions match and the result still differs -- that is a real discrepancy; report
+it.