@galaxyproject/orbit 0.0.0 → 0.9.0

package/lessons/README.md

@@ -0,0 +1,117 @@
+# Lessons
+
+A lesson records one observed, scoped thing: _in this situation this goes wrong,
+here is how to tell it is this one, here is what to do, and here is how to know
+it worked._ It is not a skill. A skill is authored, prescriptive and broad; a
+lesson is a note from a specific failure that nobody wrote down the first time.
+
+The corpus is deliberately small. Most knowledge belongs somewhere else, and the
+sorting rule below is about sending it there.
+
+## The sorting rule
+
+Before writing a lesson, ask what the knowledge is. Exactly one destination:
+
+| What it is                                                                                                       | Where it goes                                                                                 |
+| ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| Already in a GTN FAQ, tutorial or forum thread                                                                   | Cite that. No lesson.                                                                         |
+| Already a lesson here                                                                                            | Add evidence to the existing one -- counts, versions, another `sources` entry. No new lesson. |
+| Something a validator, a schema or a better error message would catch                                            | An issue on galaxy-mcp, the Foundry, or Galaxy. Never the corpus.                             |
+| A general how-to                                                                                                 | A GTN FAQ pull request. Regular docs are the default landing.                                 |
+| Agent misbehaviour                                                                                               | The Orbit prompt plus an eval. Not knowledge.                                                 |
+| A silent scientific pitfall, an expectation, a choice, a source quirk, or a reproduction note, with no hit above | A lesson here.                                                                                |
+
+The last row is the whole corpus. If a lesson would be better as an error
+message, write the error message.
+
+## Namespaces
+
+The namespace is the first path segment and part of the lesson's id, so
+`stats/na-coerced-to-zero-in-filters.md` has the id
+`stats/na-coerced-to-zero-in-filters`.
+
+- `stats` -- statistical reasoning and interpretation.
+- `reproduction` -- reproducing a published analysis.
+- `data` -- acquiring data and what the source actually hands back.
+- `galaxy-tools` -- a tool or a server's configuration of it.
+- `galaxy-api` -- lessons whose durable fix now lives somewhere else. Kept for
+  the record, never surfaced: a non-empty `graduated_to` is what makes that
+  true, and the validator requires one in this namespace.
+
+## Layout
+
+```
+lessons/
+  README.md  SCHEMA.md  LICENSE  log.md
+  validate.mjs  build-snapshot.mjs  snapshot.json
+  <namespace>/<slug>.md
+```
+
+`snapshot.json` is generated and committed. Never hand-edit it: run
+`npm run build:lessons` and commit the result. `npm run check:lessons` validates
+every lesson and fails if the snapshot is out of date, and runs in CI.
+
+## Writing one
+
+`SCHEMA.md` is the field list. The things that actually decide whether a lesson
+earns its place:
+
+- **The title is the situation, not the fix.** "Numeric filters treat NA as 0"
+  rather than "Always exclude NA".
+- **`Check first` and `Validate` are required, and are the point.** The first
+  keeps the lesson from being applied to a situation that merely looks similar.
+  The second keeps "the error went away" from passing as success.
+- **Cause is optional and labelled.** Recovering from something is not proof you
+  diagnosed it. Say `hypothesized` when it is a hypothesis.
+- **Evidence, editorial status and applicability are three separate axes.**
+  `evidence.{symptom,cause,outcome}` each carry their own label and a `method`;
+  `status` is editorial; `applies_to.versions` is scope. There is no single
+  confidence score and nothing is promoted automatically.
+- **Triggers are machine-matchable or they are decoration.** Literal normalized
+  signatures, tool ids, `galaxy_*` MCP tool names, datatypes, bare hostnames,
+  dotted extensions, lowercase plan-step keywords. The prose `cues` field is for
+  humans and is never matched. A lesson with every trigger list empty is
+  rejected.
+- **An upstream fix narrows `applies_to.versions`.** It does not retire the
+  lesson -- older installs still hit it.
+- **`stale_after` is required.** A lesson that nobody will re-verify should drop
+  out on its own.
+
+The body carries nothing to follow and nothing to run: no URLs, no markdown
+links, images or HTML, no code blocks, printable ASCII only, each section at
+most 600 characters. Those are enforced, not advisory. Provenance goes in
+`sources`, and a link there must point at one of the hosts listed in
+`LINK_HOSTS` in `validate.mjs`.
+
+## Contributing
+
+1. Fork, branch, add one `.md` file under the right namespace.
+2. `npm run check:lessons` -- it prints `path:line: message` for every problem.
+3. `npm run build:lessons` and commit `lessons/snapshot.json` alongside.
+4. Add a line to `log.md`.
+5. Open a pull request against `main`.
+
+Your pull request needs both of these, checked by you:
+
+```
+- [ ] This lesson contains no personal data and no research data. No filesystem
+      paths, dataset or history ids, URLs, private server hostnames, dataset,
+      history, sample or account names, and no values copied out of anyone's
+      data -- mine or anybody else's.
+- [ ] Signed-off-by line present (Developer Certificate of Origin 1.1), and I
+      am licensing this lesson under CC BY 4.0 as described in LICENSE.
+```
+
+Sign off with `git commit -s`, which appends
+`Signed-off-by: Your Name <you@example.com>`. That line is the Developer
+Certificate of Origin 1.1 assertion: you wrote the contribution, or have the
+right to submit it under the licence above.
+
+The validator is the second line of defence on the first checkbox, not the
+first. It refuses the shapes of URLs, links, HTML, paths, ids, addresses and
+keys and caps every field, but it cannot tell that a plausible-looking tool id
+was a private server's, that a sentence describes one specific person's data,
+or that a sentence is an instruction aimed at the model rather than advice. That judgement is yours, and a
+published lesson cannot be unpublished from git history -- the privacy decision
+happens before the pull request, which is why the checkbox is phrased the way
+it is.

package/lessons/SCHEMA.md

@@ -0,0 +1,187 @@
+# Lesson schema v1
+
+The file format. `validate.mjs` is the authoritative version of all of this:
+where this document and that script disagree, the script wins and this document
+is wrong. Run `npm run check:lessons`.
+
+One markdown file per lesson at `lessons/<namespace>/<slug>.md`. The id is the
+path minus `.md`, e.g. `stats/na-coerced-to-zero-in-filters`. The slug is
+lowercase words joined by hyphens, at most 80 characters.
+
+The format is Google Cloud's Open Knowledge Format: a directory of markdown with
+YAML frontmatter, distributed as a git repository. OKF fields come first; Orbit's
+extension fields come after.
+
+## Frontmatter
+
+```yaml
+type: Lesson # OKF required
+title: string # <= 120 chars; the situation, not the fix
+description: string # <= 200 chars, one line
+tags: [string] # free; stage and formats are mirrored here by the build
+status: draft | stable | deprecated # OKF
+generated: { by: string, at: string } # e.g. "agent:loom/0.6.0" or "human:loom-maintainers"
+verified: [{ by: string, at: string }] # optional; by = "human:<pseudonym>", never a contributor id
+stale_after: string # ISO date; required
+sources: [{ id: string, resource?: string, title?: string }] # provenance; required when derived from GTN/forum
+
+kind: pitfall | expectation | choice | source-quirk | reproduction
+stage:
+  [
+    data-acquisition | metadata-reconciliation | tool-parameterization | job-execution | result-interpretation,
+  ]
+trigger:
+  signatures: [string] # literal, normalized, each <= 200
+  tools: [string] # Galaxy tool ids or families
+  mcp_tools: [string] # galaxy_* names
+  formats: [string] # datatypes / extensions
+  hosts: [string] # hostnames seen in URLs/commands, e.g. "ncbi.nlm.nih.gov"
+  extensions: [string] # file extensions seen in args, e.g. ".gtf"
+  step_keywords: [string] # lowercase words matched against plan-step text
+cues: string # human-readable description of when this applies (not matched)
+applies_to: { versions: string, tested: string }
+evidence:
+  symptom: verified | reported
+  cause: verified | hypothesized | unknown
+  outcome: validated | unvalidated
+  method: string
+graduated_to: [string] # free text or links; non-empty => not surfaced by the matcher
+upstream: [string]
+supersedes: [string] # lesson ids
+```
+
+## Body
+
+Exactly these `##` sections, in this order. `Cause` is optional; the rest are
+required.
+
+`Symptom`, `Cause`, `Check first`, `Intervention`, `Validate`,
+`Does NOT apply when`.
+
+Each section is at most 600 characters and must not be empty. Nothing before
+the first heading. No fenced code blocks anywhere on a line, and no indented
+code blocks, at any depth (a short inline backtick span is fine). No URLs of
+any scheme, protocol-relative, scheme-less or `www.`, anywhere in the body. No
+heading other than those six, whether `#`-style at any indent or a setext
+underline, and no horizontal rules. The whole file is at most 16384 bytes.
+
+The body and every frontmatter string are also run through `marked`'s GFM lexer,
+so "is this a link" is answered the way a renderer answers it rather than by a
+line regex. Refused at any depth (inside blockquotes, list items and tables
+too): links of every kind (inline, reference, autolinks), link reference
+definitions, images, HTML, backslash escapes and character references
+(`&#64;`, `&#x40;`, `&amp;`). A code span may show a placeholder such as
+`<collection id>`, but not a tag with attributes, a closing tag, a link, a nested
+code span hiding either, or an element like `<script>` or `<iframe>` that is
+live even bare. The placeholders `normalizeSignature` writes (`<path>`, `<id>`,
+`<url>`, `<n>`, `<email>`) are text anywhere. A string longer than the file cap
+is refused unchecked.
+
+## What the validator adds on top of the field list
+
+The contract names the fields; these are the rules the validator applies to
+them, and they are part of the schema.
+
+- **Unknown keys are rejected**, at the top level and inside `generated`,
+  `verified[]`, `sources[]`, `trigger`, `applies_to` and `evidence`. Every
+  required key must be present; `verified` is the only optional one.
+- **Printable ASCII only, in the whole file and in every parsed value.** A
+  Unicode em-dash, a smart quote or a non-breaking space is an error, reported
+  by codepoint. Write `--`. Parsed values are checked too, so a YAML escape like
+  `"\u202e"` cannot carry a control character past the file check.
+- **Plain YAML only.** No comments (they ship in the raw file and would
+  otherwise go unchecked), no anchors or aliases, no explicit tags.
+- **Nothing identifying, anywhere.** No absolute or home-directory paths,
+  Windows or UNC paths, hex ids of 16 or more characters, uuids, IPv4 or IPv6
+  addresses (the `::` forms too), email addresses, hostnames on network
+  top-level domains, or credential-shaped strings (provider API keys, AWS key
+  ids, GitHub and Slack tokens, private key headers, JWTs) in the body, in any
+  frontmatter value or on any raw frontmatter line. `trigger.hosts` is the one
+  field that holds a hostname, and it must be a public one (no `.internal`,
+  `.local`, `.lan`, `.corp` and the like). No URL in the body or in a
+  frontmatter field: nothing with `://`, no `www.`, no known scheme such as
+  `mailto:`, `tel:` or `data:` followed by anything, and no other `word:`
+  followed by a host or an address. A plain `word:word` (`batch:condition`,
+  `list:paired`) is prose. Paths include `$HOME/...`, `%USERPROFILE%\...` and
+  drive-less backslash paths. An IPv4 address starting with `0.` is not
+  refused, so a four-part tool version like `0.7.17.4` is not either; one
+  starting with any other number is.
+- **Links** go only in `graduated_to`, `upstream` and `sources[].resource`, and
+  each must be a canonical `https` URL to one of the hosts in `LINK_HOSTS` at the
+  top of `validate.mjs`: no port, credentials, query, fragment, percent-escape
+  or `..`; a path of letters, digits and `._~/+-` only; and the path still gets
+  the identifying-data checks, hostnames and URLs included (so no commit SHAs,
+  uuids, home paths or a second host in the path). Those fields may hold free text
+  instead, like `galaxy-mcp#55`. To link somewhere new, add the host to
+  `LINK_HOSTS` in the same pull request and say why.
+- **These are shape checks, not meaning checks.** A private hostname written as
+  prose, a person's name, a copied data value or an instruction aimed at the
+  model ("ignore prior instructions and...") all pass. They need the
+  contributor's own judgement and a reviewer's.
+- **Dates** are `YYYY-MM-DD` strings that are also real calendar dates.
+- **`generated.by`** matches `agent:<something>` or `human:<something>`;
+  **`verified[].by`** must be `human:<pseudonym>`. It is the one identity field
+  in the schema, and the shared tier uses maintainer pseudonyms rather than
+  contributor ids.
+- **Signatures must be specific.** At least 8 characters, and never the
+  normalizer's `unknown` fallback, which would match every empty error.
+- **Signatures must already be normalized.** The validator runs the same
+  normalization the matcher will run over a tool result and rejects any
+  signature it would change, naming the normalized form to store instead. A
+  signature stored raw can never match anything. Normalization takes the first
+  line, collapses whitespace, then replaces URLs with `<url>`, emails with
+  `<email>`, paths with two or more separators with `<path>`, runs of 16+ hex
+  characters with `<id>` and integers of 5+ digits with `<n>`, in that order,
+  and truncates to 200.
+- **At least one trigger list must be non-empty.** A lesson nothing can match is
+  documentation, and documentation belongs in the GTN.
+- **Per-entry shapes.** `mcp_tools` are `galaxy_*`; `hosts` are bare hostnames
+  with no scheme and no path; `extensions` start with a dot; `step_keywords` are
+  lowercase; `formats` are lowercase; `supersedes` entries are namespaced lesson
+  ids. Lists cap at 20 entries.
+- **Caps.** title 120, description 200, each tag 40, cues 300, each signature
+  200, each tool id 200, each MCP tool name 80, each format 40, each host 100,
+  each extension 20, each step keyword 40, each `applies_to` field 200,
+  `evidence.method` 300, each source id 100, each free-text list entry 200, each
+  body section 600.
+- **A `galaxy-api` lesson must have a non-empty `graduated_to`.** That namespace
+  exists for lessons whose durable fix lives elsewhere, and `graduated_to` is
+  what keeps them unsurfaced.
+- **Directory shape.** A namespace directory holds `.md` lesson files only, one
+  level deep. Top-level files (this one, README, LICENSE, log, the scripts) are
+  not lessons and are not validated.
+
+## The snapshot
+
+`npm run build:lessons` writes `lessons/snapshot.json`:
+
+```ts
+interface LessonSnapshot {
+  schema: 1;
+  built_at: string; // ISO
+  source: { repo: "galaxyproject/orbit"; commit: string };
+  licence: "CC-BY-4.0";
+  lessons: Lesson[];
+}
+interface Lesson {
+  id: string; // "stats/na-coerced-to-zero-in-filters"
+  // every frontmatter field above, same names, same shapes
+  sections: {
+    symptom: string;
+    cause?: string;
+    check_first: string;
+    intervention: string;
+    validate: string;
+    not_when: string;
+  };
+}
+```
+
+A lesson is left out when `status` is `deprecated` or when `stale_after` has
+passed as of the snapshot's own `built_at`. `tags` in the snapshot is the
+authored tags plus the lesson's `stage` values and `trigger.formats`, deduped.
+
+Published file:
+`https://raw.githubusercontent.com/galaxyproject/orbit/main/lessons/snapshot.json`.
+A lesson's canonical page:
+`https://github.com/galaxyproject/orbit/blob/main/lessons/<id>.md`.

package/lessons/build-snapshot.mjs

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+/**
+ * Build `lessons/snapshot.json`: the validated, committed JSON every consumer
+ * reads -- the package (the matcher), galaxy-mcp, and the hosted docs-search
+ * `lessons` collection.
+ *
+ *   npm run build:lessons     # validate, build, write snapshot.json
+ *   npm run check:lessons     # validate + fail if snapshot.json is out of date
+ *
+ * Same shape of gate as `sync:skills` / `check:skills`: the generated artifact
+ * is committed so consumers get it with no build step, and CI refuses a diff
+ * that changed `lessons/` without rebuilding.
+ *
+ * `built_at` and `source.commit` are provenance, not content, so `--check`
+ * reuses the committed values and the only thing it can fail on is a lesson
+ * that changed without a rebuild. Staleness is evaluated as of `built_at` for
+ * the same reason -- otherwise this gate would start failing on a date, on
+ * somebody else's unrelated pull request. Real-time staleness is a warning.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { SECTIONS, collectLessonFiles, parseLesson, validateLessonsDir } from "./validate.mjs";
+
+export const LESSONS_DIR = path.dirname(fileURLToPath(import.meta.url));
+export const REPO_ROOT = path.resolve(LESSONS_DIR, "..");
+export const SNAPSHOT_PATH = path.join(LESSONS_DIR, "snapshot.json");
+
+export const SNAPSHOT_SCHEMA = 1;
+export const SNAPSHOT_REPO = "galaxyproject/orbit";
+export const SNAPSHOT_LICENCE = "CC-BY-4.0";
+
+/** Past the end of its `stale_after` day, in UTC. */
+export function isStale(staleAfter, nowMs) {
+  const end = Date.parse(`${staleAfter}T23:59:59Z`);
+  return Number.isFinite(end) && end < nowMs;
+}
+
+/**
+ * The exact shape `Date.prototype.toISOString` writes. Anything looser and a
+ * hand-edited `built_at` parses to NaN, which silently turns the staleness
+ * comparison off.
+ */
+export function isIsoTimestamp(value) {
+  if (typeof value !== "string") return false;
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)) return false;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) && new Date(ms).toISOString() === value;
+}
+
+function dedupe(values) {
+  return [...new Set(values)];
+}
+
+/**
+ * One snapshot entry. Every field is copied by name rather than spread, so the
+ * key order is deterministic (the drift gate compares bytes) and a frontmatter
+ * key the validator would have rejected cannot ride along into the published
+ * artifact.
+ */
+export function toSnapshotLesson(rel, frontmatter, sections) {
+  const fm = frontmatter;
+  const lesson = {
+    id: rel.replace(/\.md$/, ""),
+    type: fm.type,
+    title: fm.title,
+    description: fm.description,
+    // The build mirrors stage and formats into tags, so a consumer that only
+    // indexes tags (the docs-search collection does) still sees both axes.
+    tags: dedupe([...fm.tags, ...fm.stage, ...fm.trigger.formats]),
+    status: fm.status,
+    generated: { by: fm.generated.by, at: fm.generated.at },
+  };
+  if (fm.verified !== undefined) {
+    lesson.verified = fm.verified.map((v) => ({ by: v.by, at: v.at }));
+  }
+  lesson.stale_after = fm.stale_after;
+  lesson.sources = fm.sources.map((s) => {
+    const out = { id: s.id };
+    if (s.resource !== undefined) out.resource = s.resource;
+    if (s.title !== undefined) out.title = s.title;
+    return out;
+  });
+  lesson.kind = fm.kind;
+  lesson.stage = [...fm.stage];
+  lesson.trigger = {
+    signatures: [...fm.trigger.signatures],
+    tools: [...fm.trigger.tools],
+    mcp_tools: [...fm.trigger.mcp_tools],
+    formats: [...fm.trigger.formats],
+    hosts: [...fm.trigger.hosts],
+    extensions: [...fm.trigger.extensions],
+    step_keywords: [...fm.trigger.step_keywords],
+  };
+  lesson.cues = fm.cues;
+  lesson.applies_to = { versions: fm.applies_to.versions, tested: fm.applies_to.tested };
+  lesson.evidence = {
+    symptom: fm.evidence.symptom,
+    cause: fm.evidence.cause,
+    outcome: fm.evidence.outcome,
+    method: fm.evidence.method,
+  };
+  lesson.graduated_to = [...fm.graduated_to];
+  lesson.upstream = [...fm.upstream];
+  lesson.supersedes = [...fm.supersedes];
+  lesson.sections = {};
+  for (const spec of SECTIONS) {
+    if (sections[spec.key] !== undefined) lesson.sections[spec.key] = sections[spec.key];
+  }
+  return lesson;
+}
+
+/**
+ * Build the snapshot object. `nowMs` defaults to `builtAt` so a build and a
+ * later `--check` of the same bytes agree.
+ */
+export function buildSnapshot({ dir = LESSONS_DIR, builtAt, commit, nowMs } = {}) {
+  if (!isIsoTimestamp(builtAt)) {
+    throw new Error(`built_at must be an ISO timestamp (got ${JSON.stringify(builtAt)})`);
+  }
+  const asOf = nowMs ?? Date.parse(builtAt);
+  const lessons = [];
+  const skipped = [];
+  for (const rel of collectLessonFiles(dir)) {
+    const { frontmatter, sections } = parseLesson(fs.readFileSync(path.join(dir, rel), "utf8"));
+    const id = rel.replace(/\.md$/, "");
+    if (frontmatter.status === "deprecated") {
+      skipped.push({ id, why: "status: deprecated" });
+      continue;
+    }
+    if (isStale(frontmatter.stale_after, asOf)) {
+      skipped.push({ id, why: `past stale_after ${frontmatter.stale_after}` });
+      continue;
+    }
+    lessons.push(toSnapshotLesson(rel, frontmatter, sections));
+  }
+  const snapshot = {
+    schema: SNAPSHOT_SCHEMA,
+    built_at: builtAt,
+    source: { repo: SNAPSHOT_REPO, commit },
+    licence: SNAPSHOT_LICENCE,
+    lessons,
+  };
+  return { snapshot, skipped };
+}
+
+export function serializeSnapshot(snapshot) {
+  return `${JSON.stringify(snapshot, null, 2)}\n`;
+}
+
+/** First differing line of two serialized snapshots, as printable lines. */
+export function firstDiff(committed, rebuilt) {
+  const a = committed.split("\n");
+  const b = rebuilt.split("\n");
+  const trunc = (s) =>
+    s === undefined ? "<end of file>" : s.length > 120 ? `${s.slice(0, 117)}...` : s;
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    if (a[i] === b[i]) continue;
+    return [
+      `first difference at line ${i + 1}:`,
+      `committed: ${trunc(a[i])}`,
+      `rebuilt:   ${trunc(b[i])}`,
+    ];
+  }
+  return ["the two serializations differ in length only"];
+}
+
+/**
+ * The commit the corpus was read at. This is HEAD at build time, so it names
+ * the commit before the one that lands the snapshot -- which is the honest
+ * answer to "what was on disk when this was built".
+ */
+function headCommit(repoRoot) {
+  const run = spawnSync("git", ["rev-parse", "HEAD"], { cwd: repoRoot, encoding: "utf8" });
+  const sha = run.status === 0 ? run.stdout.trim() : "";
+  return /^[0-9a-f]{40}$/.test(sha) ? sha : "unknown";
+}
+
+function reportViolations(label, violations) {
+  console.error(`${label} FAILED -- ${violations.length} schema violation(s)`);
+  for (const v of violations) console.error(`  ${v}`);
+  process.exit(1);
+}
+
+function build() {
+  const violations = validateLessonsDir(LESSONS_DIR);
+  if (violations.length > 0) reportViolations("build:lessons", violations);
+
+  const builtAt = process.env.LESSONS_BUILT_AT ?? new Date().toISOString();
+  const commit = process.env.LESSONS_COMMIT ?? headCommit(REPO_ROOT);
+  const { snapshot, skipped } = buildSnapshot({ builtAt, commit });
+  if (snapshot.lessons.length === 0) {
+    console.error("build:lessons FAILED -- every lesson was skipped, the snapshot would be empty");
+    for (const s of skipped) console.error(`  ${s.id}: ${s.why}`);
+    process.exit(1);
+  }
+  fs.writeFileSync(SNAPSHOT_PATH, serializeSnapshot(snapshot));
+  console.log(`build:lessons OK -- ${snapshot.lessons.length} lesson(s) in lessons/snapshot.json`);
+  for (const s of skipped) console.log(`  left out ${s.id} (${s.why})`);
+}
+
+/**
+ * The drift gate as a function, so it can be exercised against any corpus.
+ * `failure` is the lines to print when it fails; `warnings` never fail it.
+ */
+export function checkSnapshot({
+  dir = LESSONS_DIR,
+  snapshotPath = SNAPSHOT_PATH,
+  nowMs = Date.now(),
+} = {}) {
+  const violations = validateLessonsDir(dir);
+  if (violations.length > 0) {
+    return {
+      ok: false,
+      failure: [
+        `check:lessons FAILED -- ${violations.length} schema violation(s)`,
+        ...violations.map((v) => `  ${v}`),
+      ],
+    };
+  }
+  if (!fs.existsSync(snapshotPath)) {
+    return {
+      ok: false,
+      failure: [
+        "check:lessons FAILED -- lessons/snapshot.json is missing",
+        "\nRun `npm run build:lessons` and commit the result.",
+      ],
+    };
+  }
+  const committedText = fs.readFileSync(snapshotPath, "utf8").replace(/\r\n/g, "\n");
+  let committed;
+  try {
+    committed = JSON.parse(committedText);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      failure: [`check:lessons FAILED -- lessons/snapshot.json is not valid JSON: ${message}`],
+    };
+  }
+  const builtAt = committed?.built_at;
+  if (!isIsoTimestamp(builtAt)) {
+    return {
+      ok: false,
+      failure: [
+        `check:lessons FAILED -- lessons/snapshot.json built_at is not an ISO timestamp (got ${JSON.stringify(builtAt)})`,
+        "\nRun `npm run build:lessons` and commit lessons/snapshot.json.",
+      ],
+    };
+  }
+  const commit = typeof committed?.source?.commit === "string" ? committed.source.commit : "";
+  const { snapshot } = buildSnapshot({ dir, builtAt, commit });
+  const rebuilt = serializeSnapshot(snapshot);
+  if (rebuilt !== committedText) {
+    return {
+      ok: false,
+      failure: [
+        "check:lessons FAILED -- lessons/snapshot.json does not match lessons/",
+        ...firstDiff(committedText, rebuilt).map((line) => `  ${line}`),
+        "\nRun `npm run build:lessons` and commit lessons/snapshot.json.",
+      ],
+    };
+  }
+
+  // Not fatal: a lesson that has aged out should be re-verified or dropped
+  // deliberately, and a date is a bad reason to turn somebody else's CI red.
+  const warnings = snapshot.lessons
+    .filter((l) => isStale(l.stale_after, nowMs))
+    .map(
+      (l) =>
+        `  warning: ${l.id} is past stale_after ${l.stale_after} -- re-verify it, or rebuild to drop it`,
+    );
+  return { ok: true, count: snapshot.lessons.length, warnings };
+}
+
+function check() {
+  const result = checkSnapshot();
+  if (!result.ok) {
+    for (const line of result.failure) console.error(line);
+    process.exit(1);
+  }
+  for (const w of result.warnings) console.warn(w);
+  console.log(`check:lessons OK -- ${result.count} lesson(s) match lessons/snapshot.json`);
+}
+
+function isDirectInvocation() {
+  if (!process.argv[1]) return false;
+  try {
+    return fileURLToPath(import.meta.url) === realpathSync(process.argv[1]);
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation()) {
+  const args = process.argv.slice(2);
+  if (args.length > 1 || (args.length === 1 && args[0] !== "--check")) {
+    console.error(`usage: build-snapshot.mjs [--check] (got ${args.join(" ")})`);
+    process.exit(2);
+  }
+  try {
+    if (args[0] === "--check") check();
+    else build();
+  } catch (err) {
+    console.error(`lessons/build-snapshot: ${err instanceof Error ? err.message : err}`);
+    process.exit(1);
+  }
+}

package/lessons/data/downloaded-file-is-not-what-its-extension-says.md

@@ -0,0 +1,61 @@
+---
+type: Lesson
+title: A supplementary-file download can return an HTML page saved under the expected filename
+description: A landing page, consent interstitial or bot-block answers with 200 and the client saves it as the requested name, so the parse failure surfaces several steps later.
+tags: [download, supplementary-data, file-type, landing-page]
+status: draft
+generated: { by: "human:loom-maintainers", at: "2026-09-30" }
+stale_after: "2027-03-31"
+sources:
+  - { id: "loom#356" }
+  - { id: "loom#282" }
+
+kind: source-quirk
+stage: [data-acquisition]
+trigger:
+  signatures: []
+  tools: []
+  mcp_tools: []
+  formats: [xlsx, gz, tsv, csv]
+  hosts: ["doi.org", "zenodo.org", "figshare.com", "static-content.springer.com", "journals.plos.org", "www.ncbi.nlm.nih.gov"]
+  extensions: [".xlsx", ".tsv.gz", ".tsv", ".csv", ".gz"]
+  step_keywords: ["download", "supplementary", "fetch", "wget", "curl", "doi", "landing page"]
+cues: "Fetching a supplementary or data file from a journal, a repository landing page, or a DOI link."
+applies_to: { versions: "n/a", tested: "local download of journal supplementary files" }
+evidence:
+  symptom: verified
+  cause: hypothesized
+  outcome: unvalidated
+  method: "the file was later found to be HTML or XML"
+graduated_to: []
+upstream: []
+supersedes: []
+---
+
+## Symptom
+
+An `.xlsx` or `.tsv.gz` will not parse, or parses into nonsense, several steps after it was
+fetched.
+
+## Cause
+
+Likely: the URL was a landing page, a login or consent interstitial, or a bot-block response, and
+the client saved the body under the requested name with a 200.
+
+## Check first
+
+Right after any download: file size, leading bytes (zip or gzip magic versus `<`), and
+content-type if available.
+
+## Intervention
+
+Find the direct file URL, or have Galaxy fetch it server-side; if access is gated, tell the user
+rather than working around it.
+
+## Validate
+
+The file opens as its claimed type and has the expected shape: sheets, columns, row count.
+
+## Does NOT apply when
+
+The file is genuinely the right type and the parse error is about its contents.