@captiveorigins/onephylogeny-engine 0.0.0-stage → 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,75 @@
+Required Notice: Copyright 2026 Captive Origins (https://captiveorigins.com)
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @captiveorigins/onephylogeny-engine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+OnePhylogeny engine: runs profiles end to end with immutable run records and structured logs: fetch, anchor, gate, build panels, validate, test samples and build trees through replaceable ports.
+
+See the [repository](https://github.com/CaptiveOrigins/onephylogeny) for documentation.

package/dist/index.d.ts

@@ -0,0 +1,200 @@
+import { ValidationInput, FullValidation, RunEvent, Run, SequenceRecord, Diagnostic, PanelBundle, Result, Profile, Curation, RunComparison, LinkedRecord } from '@captiveorigins/onephylogeny-core';
+import { NcbiOptions, FoundPaper } from '@captiveorigins/onephylogeny-acquire';
+
+/** Where files live. A folder on disk, in the CLI and the Mac app. */
+interface Store {
+    read(path: string): Promise<string>;
+    /** Must be atomic: a crash leaves the old file or the new one, never half of it. */
+    write(path: string, text: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    /** Adds to a log without rewriting it. Optional: without it, logs are written whole. */
+    append?(path: string, text: string): Promise<void>;
+}
+/** How native programs run. Only tree building needs one. */
+interface ToolRunner {
+    version(tool: string): Promise<string | null>;
+    run(tool: string, args: string[], options: {
+        cwd: string;
+    }): Promise<{
+        code: number;
+        stdout: string;
+        stderr: string;
+    }>;
+}
+type ValidationReports = FullValidation;
+/** Heavy pure calculations, which an app can run off its interface thread. */
+type Compute = {
+    validate?: (input: ValidationInput, signal?: AbortSignal) => Promise<ValidationReports>;
+};
+type EngineContext = {
+    store: Store;
+    ncbi: Omit<NcbiOptions, 'log'>;
+    tools?: ToolRunner;
+    now?: () => Date;
+    onEvent?: (event: RunEvent) => void;
+    /** Cancels a run at its next safe point. */
+    signal?: AbortSignal;
+    compute?: Compute;
+};
+
+type ArtifactType = 'accession-list' | 'raw-records' | 'anchored-records' | 'gated-records' | 'panel' | 'validation' | 'sample-result' | 'tree';
+type ToolIdentity = {
+    name: string;
+    version: string;
+};
+type ArtifactRef = {
+    type: ArtifactType;
+    key: string;
+};
+/** Written last. Its presence is what says a step finished, so a crash can't leave something that looks complete. */
+type ArtifactManifest = {
+    schemaVersion: 1;
+    type: ArtifactType;
+    key: string;
+    step: {
+        name: string;
+        version: number;
+    };
+    inputs: ArtifactRef[];
+    parameters: unknown;
+    tools: ToolIdentity[];
+    files: {
+        name: string;
+        sha256: string;
+    }[];
+    createdAt: string;
+};
+type Artifact = {
+    manifest: ArtifactManifest;
+    read: (name: string) => Promise<string>;
+};
+/** Loads an artifact for use, refusing the wrong type or anything that has changed since it was made. */
+declare function loadArtifact(store: Store, ref: ArtifactRef): Promise<Artifact>;
+type TraceNode = {
+    type: ArtifactType;
+    key: string;
+    step: string;
+    parameters: unknown;
+    tools: ToolIdentity[];
+    createdAt: string;
+    inputs: TraceNode[];
+};
+/** Follows an artifact back through everything that produced it. */
+declare function traceArtifact(store: Store, ref: ArtifactRef): Promise<TraceNode>;
+
+/** Every failure has a stable code, plain words, and what to do next. */
+type ErrorCode = 'invalid-profile' | 'empty-search' | 'empty-panel' | 'source-failed' | 'reference-missing' | 'raw-file-changed' | 'artifact-missing' | 'artifact-wrong-type' | 'artifact-corrupt' | 'step-output-invalid' | 'panel-version-exists' | 'panel-outdated' | 'panel-missing' | 'panel-changed' | 'tool-missing' | 'tool-failed' | 'run-missing' | 'cancelled';
+declare class EngineError extends Error {
+    readonly code: ErrorCode;
+    readonly action?: string | undefined;
+    constructor(code: ErrorCode, message: string, action?: string | undefined);
+}
+declare const isCancelled: (e: unknown) => boolean;
+
+/** Bump with each engine release. Recorded in every run, panel and result. */
+declare const ENGINE_VERSION = "0.1.0-alpha.1";
+declare const profilePaths: (profileId: string) => {
+    profile: string;
+    curation: string;
+    latest: string;
+    run: (id: string) => string;
+    panel: (id: string, version: string) => string;
+    results: string;
+};
+
+type RecordOutcome = {
+    record: string;
+    organism?: string;
+    status: 'passed' | 'excluded';
+    diagnostics: Diagnostic[];
+    columns: number;
+    identity: number;
+    extractedFrom: 'annotation' | 'located' | 'whole-record';
+};
+type FetchOutcome = {
+    run: Run;
+    records: SequenceRecord[];
+    outcomes: RecordOutcome[];
+};
+/**
+ * Fetches everything a profile selects, keeps raw files, anchors and checks each record, and writes the sheet and log.
+ * Each stage reuses earlier work when its inputs and settings are unchanged.
+ */
+declare function fetchAndAnchor(ctx: EngineContext, profile: Profile, options?: {
+    batchSize?: number;
+    allowEmpty?: boolean;
+}): Promise<FetchOutcome>;
+/** Studies built from GenBank records of a profile's species and marker, placed on the reference. */
+declare function findRecordStudies(ctx: EngineContext, profile: Profile, onProgress?: (done: number, total: number) => void): Promise<{
+    papers: FoundPaper[];
+    columns: number;
+    query: string;
+}>;
+/** Looks up what PubMed links to one paper, then sorts those records by species and gene and places them. */
+declare function findPaperRecords(ctx: EngineContext, profile: Profile, pmid: string): Promise<{
+    linked: LinkedRecord[];
+    columns: number;
+}>;
+type PanelBuildOutcome = {
+    bundle: PanelBundle;
+    diagnostics: Diagnostic[];
+    validation: ValidationReports;
+    unassigned: number;
+    run: Run;
+    published: boolean;
+};
+/** Builds and validates a candidate panel from a finished fetch run and the curation file. */
+declare function buildPanelFromRun(ctx: EngineContext, profile: Profile, curation: Curation, id?: string): Promise<PanelBuildOutcome>;
+declare function loadPanel(store: Store, dir: string): Promise<PanelBundle>;
+/** The versions built for a profile's panel, oldest first. Every one is listed, so no attempt can be left out. */
+declare function panelVersions(profile: Profile, folders: string[]): string[];
+/** Compares two built versions. Both must still match their seals. */
+declare function comparePanelVersions(store: Store, profile: Profile, a: string, b: string): Promise<RunComparison>;
+type SampleOutcome = {
+    result: Result;
+    diagnostics: Diagnostic[];
+    aligned: string;
+    insertions: number;
+    deletions: number;
+    identity: number;
+    clipped: {
+        start: number;
+        end: number;
+    };
+} | {
+    result: null;
+    diagnostics: Diagnostic[];
+};
+/** Tests one sequence against one panel. Pure TypeScript: runs in the app, the CLI or a hosted site. */
+declare function testSample(sequence: string, queryId: string, bundle: PanelBundle, options?: {
+    runId?: string;
+}): SampleOutcome;
+/** Tests a sequence with a full record: a saved result that traces back to its panel, the records and raw files. */
+declare function runSample(ctx: EngineContext, profile: Profile, sequence: string, queryId: string): Promise<SampleOutcome & {
+    run: Run;
+    artifact: ArtifactRef;
+}>;
+type TreeOutcome = {
+    tool: string;
+    version: string;
+    newick: string;
+    tips: {
+        id: string;
+        members: string[];
+    }[];
+    run: Run;
+    artifact: ArtifactRef;
+};
+/** Builds a tree with IQ-TREE from one coverage window of a run's records. */
+declare function buildTree(ctx: EngineContext, profile: Profile, options: {
+    runId?: string;
+    absoluteDir: string;
+    tool?: string;
+    window?: {
+        start: number;
+        end: number;
+    };
+    minCoverage?: number;
+}): Promise<TreeOutcome>;
+
+export { type ArtifactManifest, type ArtifactRef, type ArtifactType, type Compute, ENGINE_VERSION, type EngineContext, EngineError, type ErrorCode, type FetchOutcome, type PanelBuildOutcome, type RecordOutcome, type SampleOutcome, type Store, type ToolRunner, type TraceNode, type TreeOutcome, type ValidationReports, buildPanelFromRun, buildTree, comparePanelVersions, fetchAndAnchor, findPaperRecords, findRecordStudies, isCancelled, loadArtifact, loadPanel, panelVersions, profilePaths, runSample, testSample, traceArtifact };

package/dist/index.js

@@ -0,0 +1,769 @@
+// src/index.ts
+import {
+  ALIGNER,
+  alignToReference,
+  LOCATE_FLANK,
+  locateMarker,
+  assessAlignment,
+  buildPanel,
+  canonicalJson as canonicalJson2,
+  checkNumts,
+  collapseHaplotypes,
+  compareRuns,
+  DEFAULT_GATES,
+  extractLocation,
+  findGeneFeatures,
+  fullValidation,
+  gatesForRecord,
+  parseFasta,
+  parseGenBank,
+  evaluateQuery,
+  toRecordSheet,
+  toSequenceRecord,
+  validatePanel,
+  verifyBundle,
+  validatedScopeFromReport,
+  validateProfile,
+  validateResult,
+  writeFasta
+} from "@captiveorigins/onephylogeny-core";
+import { classifyAccessions, genomesHoldingMarkerQuery, linkedAccessions, NcbiClient, selectionQuery, studiesFromRecords } from "@captiveorigins/onephylogeny-acquire";
+
+// src/artifacts.ts
+import { canonicalJson, sha256Hex } from "@captiveorigins/onephylogeny-core";
+
+// src/errors.ts
+var EngineError = class extends Error {
+  constructor(code, message, action) {
+    super(message);
+    this.code = code;
+    this.action = action;
+    this.name = "EngineError";
+  }
+  code;
+  action;
+};
+var isCancelled = (e) => e instanceof EngineError && e.code === "cancelled";
+
+// src/artifacts.ts
+var hashText = (text) => `sha256:${sha256Hex(text)}`;
+var artifactDir = ({ type, key }) => `artifacts/${type}/${key.replace("sha256:", "")}`;
+function stepKey(spec) {
+  return hashText(canonicalJson({ type: spec.type, step: spec.step, inputs: spec.inputs, parameters: spec.parameters, tools: spec.tools }));
+}
+async function readManifest(store, ref2) {
+  const path = `${artifactDir(ref2)}/manifest.json`;
+  if (!await store.exists(path)) return null;
+  let manifest;
+  try {
+    manifest = JSON.parse(await store.read(path));
+  } catch {
+    throw new EngineError("artifact-corrupt", `The record of ${ref2.type} ${ref2.key} is damaged`);
+  }
+  if (manifest.type !== ref2.type) throw new EngineError("artifact-wrong-type", `Expected ${ref2.type}, but this artifact is ${manifest.type}`);
+  return manifest;
+}
+async function verifyFiles(store, manifest) {
+  for (const file of manifest.files) {
+    const path = `${artifactDir(manifest)}/${file.name}`;
+    if (!await store.exists(path)) return false;
+    if (hashText(await store.read(path)) !== file.sha256) return false;
+  }
+  return true;
+}
+var open = (store, manifest) => ({
+  manifest,
+  read: async (name) => {
+    if (!manifest.files.some((f) => f.name === name)) throw new EngineError("artifact-missing", `${manifest.type} has no file ${name}`);
+    return store.read(`${artifactDir(manifest)}/${name}`);
+  }
+});
+async function loadArtifact(store, ref2) {
+  const manifest = await readManifest(store, ref2);
+  if (!manifest) throw new EngineError("artifact-missing", `${ref2.type} ${ref2.key} doesn't exist`, "Run the earlier step again");
+  if (!await verifyFiles(store, manifest)) throw new EngineError("artifact-corrupt", `Files of ${ref2.type} ${ref2.key} have changed or gone missing`, "Run the step again to rebuild them");
+  return open(store, manifest);
+}
+var openVerified = open;
+async function traceArtifact(store, ref2) {
+  const manifest = await readManifest(store, ref2);
+  if (!manifest) throw new EngineError("artifact-missing", `${ref2.type} ${ref2.key} doesn't exist`);
+  const inputs = [];
+  for (const input of manifest.inputs) inputs.push(await traceArtifact(store, input));
+  return { type: manifest.type, key: manifest.key, step: `${manifest.step.name}@${manifest.step.version}`, parameters: manifest.parameters, tools: manifest.tools, createdAt: manifest.createdAt, inputs };
+}
+
+// src/run.ts
+import { AcquireError } from "@captiveorigins/onephylogeny-acquire";
+var ENGINE_VERSION = "0.1.0-alpha.1";
+var ENGINE = { name: "onephylogeny-engine", version: ENGINE_VERSION };
+var profilePaths = (profileId) => ({
+  profile: `profiles/${profileId}/profile.json`,
+  curation: `profiles/${profileId}/curation.json`,
+  latest: `profiles/${profileId}/latest-run.txt`,
+  run: (id) => `profiles/${profileId}/runs/${id}`,
+  panel: (id, version) => `profiles/${profileId}/panels/${id}-${version}`,
+  results: `profiles/${profileId}/results`
+});
+var json = (v) => `${JSON.stringify(v, null, 2)}
+`;
+var stamp = (ctx) => (ctx.now?.() ?? /* @__PURE__ */ new Date()).toISOString();
+var RunLog = class {
+  constructor(ctx, file) {
+    this.ctx = ctx;
+    this.file = file;
+  }
+  ctx;
+  file;
+  events = [];
+  pending = Promise.resolve();
+  add(level, step, message, data) {
+    const event = { at: stamp(this.ctx), level, step, message, ...data ? { data } : {} };
+    this.events.push(event);
+    this.ctx.onEvent?.(event);
+    const { store } = this.ctx;
+    const write = store.append ? () => store.append(this.file, `${JSON.stringify(event)}
+`) : () => store.write(this.file, `${this.events.map((e) => JSON.stringify(e)).join("\n")}
+`);
+    this.pending = this.pending.then(write).catch(() => {
+    });
+  }
+  flush() {
+    return this.pending;
+  }
+};
+async function runStep(scope, spec) {
+  const { store } = scope.ctx;
+  const tools = spec.tools ?? [];
+  const key = stepKey({ type: spec.type, step: spec.step, inputs: spec.inputs, parameters: spec.parameters, tools });
+  const ref2 = { type: spec.type, key };
+  scope.checkpoint();
+  const existing = await readManifest(store, ref2);
+  if (existing && await verifyFiles(store, existing)) {
+    scope.log("info", spec.step.name, "Reused earlier output: inputs and settings are unchanged", { status: "reused", key });
+    scope.run.artifacts.push({ ...ref2, reused: true });
+    return openVerified(store, existing);
+  }
+  const dir = artifactDir(ref2);
+  scope.log("info", spec.step.name, "Running", { status: "running", key });
+  const files = [];
+  const put = async (name, text) => {
+    await store.write(`${dir}/${name}`, text);
+    files.push({ name, sha256: hashText(text) });
+  };
+  const register = async (name) => {
+    files.push({ name, sha256: hashText(await store.read(`${dir}/${name}`)) });
+  };
+  await spec.run(put, dir, register);
+  scope.checkpoint();
+  if (spec.ensure) {
+    const problem = await spec.ensure((name) => store.read(`${dir}/${name}`));
+    if (problem) throw new EngineError("step-output-invalid", `${spec.step.name} produced invalid output: ${problem}`);
+  }
+  const manifest = { schemaVersion: 1, type: spec.type, key, step: spec.step, inputs: spec.inputs, parameters: spec.parameters, tools, files, createdAt: stamp(scope.ctx) };
+  await store.write(`${dir}/manifest.json`, json(manifest));
+  scope.log("info", spec.step.name, "Finished", { status: "finished", key });
+  scope.run.artifacts.push({ ...ref2, reused: false });
+  return openVerified(store, manifest);
+}
+var newRunId = (ctx, kind) => `${stamp(ctx).replace(/[:.]/g, "-")}-${kind}`;
+var toEngineError = (e) => {
+  if (e instanceof AcquireError) return new EngineError("source-failed", e.message, "Check your connection and try again. Anything already downloaded is kept");
+  return e;
+};
+async function withRun(ctx, profile, kind, work) {
+  const P = profilePaths(profile.id);
+  const id = newRunId(ctx, kind);
+  const dir = P.run(id);
+  const run = { schemaVersion: 1, id, kind, profile, artifacts: [], tools: [ENGINE], status: "running", startedAt: stamp(ctx), events: [], outputs: [], diagnostics: [] };
+  await ctx.store.write(`${dir}/run.json`, json(run));
+  const log = new RunLog(ctx, `${dir}/events.jsonl`);
+  const checkpoint = () => {
+    if (ctx.signal?.aborted) throw new EngineError("cancelled", "Cancelled");
+  };
+  let lastBreath = Date.now();
+  const scope = {
+    ctx,
+    run,
+    dir,
+    log: (level, step, message, data) => log.add(level, step, message, data),
+    checkpoint,
+    breathe: async () => {
+      checkpoint();
+      if (Date.now() - lastBreath > 30) {
+        await new Promise((r) => setTimeout(r, 0));
+        lastBreath = Date.now();
+        checkpoint();
+      }
+    },
+    step: (spec) => runStep(scope, spec)
+  };
+  const finish = async (status) => {
+    await log.flush();
+    run.status = status;
+    run.finishedAt = stamp(ctx);
+    run.events = log.events;
+    await ctx.store.write(`${dir}/run.json`, json(run));
+  };
+  try {
+    const value = await work(scope);
+    await finish("succeeded");
+    return { value, run };
+  } catch (raw) {
+    const e = toEngineError(raw);
+    const cancelled = e instanceof EngineError && e.code === "cancelled";
+    scope.log(cancelled ? "warning" : "error", "run", cancelled ? "Cancelled. Finished steps are kept and will be reused" : e instanceof Error ? e.message : String(e));
+    await finish(cancelled ? "cancelled" : "failed").catch(() => {
+    });
+    throw e;
+  }
+}
+
+// src/index.ts
+var cachePath = (version) => `cache/genbank/${version.replace(/[^A-Za-z0-9._-]/g, "_")}.gb`;
+var ref = (a) => ({ type: a.manifest.type, key: a.manifest.key });
+var artifactOf = (run, type) => run.artifacts.find((a) => a.type === type);
+function geneSequence(rec, profile) {
+  const marker = profile.selection.marker;
+  const names = [marker.gene, ...marker.synonyms ?? [], ...marker.products ?? []].filter(Boolean);
+  if (marker.kind === "gene") {
+    const feature = findGeneFeatures(rec, names)[0];
+    if (feature) {
+      try {
+        return { sequence: extractLocation(rec.sequence, feature.location), from: "annotation" };
+      } catch {
+      }
+    }
+  }
+  return { sequence: rec.sequence, from: "whole-record" };
+}
+var where = (p) => `bases ${p.start + 1} to ${p.end} on the ${p.strand === "+" ? "given" : "reverse"} strand${p.wrapsOrigin ? ", across the origin" : ""}`;
+function locatedSequence(rec, reference, profile, found) {
+  const factor = panelGates(profile).containerRecordFactor ?? Infinity;
+  if (found.from !== "whole-record" || profile.selection.marker.kind !== "gene" || found.sequence.length < factor * reference.length) return found;
+  const location = locateMarker(found.sequence, reference, { ...rec.circular ? { circular: true } : {} });
+  if (location.status === "located") return { sequence: location.sequence, from: "located", located: location.place };
+  if (location.status === "multiple") return { ...found, manyPlaces: location.places };
+  return found;
+}
+async function searchStep(scope, profile, client, options) {
+  const include = profile.selection.include;
+  const term = include?.length ? `chosen accessions, ${include.length} records, ${hashText([...include].sort().join("\n"))}` : selectionQuery(profile.selection);
+  scope.log("info", "search", include?.length ? "Using the accessions chosen in a Study" : "Searching NCBI", { term });
+  const found = include?.length ? include : await client.searchAccessions(term);
+  if (!found.length && !options.allowEmpty) throw new EngineError("empty-search", "NCBI found no records for this taxon and marker", "Check the taxon, gene names and organelle in Setup");
+  const genomes = include?.length ? null : genomesHoldingMarkerQuery(profile.selection);
+  if (genomes) {
+    try {
+      const missed = (await client.searchAccessions(genomes)).filter((a) => !found.includes(a));
+      if (missed.length) scope.log("warning", "search", `${missed.length} mitochondrial genomes of these taxa aren't in this search, probably because they don't annotate the marker. They may hold it, and they aren't used unless chosen in a Study, which cuts the marker out by similarity: ${missed.join(", ")}`, { missed });
+    } catch (e) {
+      if (isCancelled(e)) throw e;
+      scope.log("warning", "search", `Couldn't check for mitochondrial genomes the search missed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+  const extra = [profile.reference.accession, ...profile.selection.outgroups.map((o) => o.accession).filter((a) => Boolean(a))];
+  const accessions = [.../* @__PURE__ */ new Set([...found, ...extra])].sort();
+  scope.log("info", "search", `Found ${found.length} records, plus ${extra.length} named in the profile`, { found: found.length });
+  const artifact = await scope.step({
+    type: "accession-list",
+    step: { name: "search", version: 1 },
+    inputs: [],
+    parameters: { term, accessions: hashText(accessions.join("\n")) },
+    run: async (put) => {
+      await put("accessions.json", json({ term, accessions }));
+    }
+  });
+  return { artifact, accessions, term };
+}
+function rawStep(scope, list, accessions, client, batchSize) {
+  const { store } = scope.ctx;
+  return scope.step({
+    type: "raw-records",
+    step: { name: "fetch", version: 1 },
+    inputs: [ref(list)],
+    parameters: {},
+    run: async (put) => {
+      const texts = /* @__PURE__ */ new Map();
+      const missing = [];
+      for (const version of accessions) {
+        const path = cachePath(version);
+        if (await store.exists(path)) texts.set(version, await store.read(path));
+        else missing.push(version);
+      }
+      scope.log("info", "fetch", `${texts.size} records already downloaded, ${missing.length} to fetch`, { done: texts.size, total: accessions.length });
+      for (let i = 0; i < missing.length; i += batchSize) {
+        scope.checkpoint();
+        const batch = missing.slice(i, i + batchSize);
+        const { text, records } = await client.fetchGenBankText(batch);
+        const blocks = text.split(/^\/\/\s*$/m).filter((b) => b.includes("LOCUS"));
+        for (const [n, rec] of records.entries()) {
+          const raw = `${blocks[n].trimStart()}//
+`;
+          const key = rec.version || rec.accession;
+          await store.write(cachePath(key), raw);
+          texts.set(key, raw);
+        }
+        scope.log("info", "fetch", `Fetched ${Math.min(i + batchSize, missing.length)} of ${missing.length}`, { done: texts.size, total: accessions.length });
+      }
+      const index = Object.fromEntries([...texts].map(([k, t]) => [k, hashText(t)]).sort(([a], [b]) => String(a).localeCompare(String(b))));
+      await put("index.json", json(index));
+    },
+    ensure: async (read) => Object.keys(JSON.parse(await read("index.json"))).length ? null : "no records were fetched"
+  });
+}
+var markerParameters = (profile) => ({ marker: profile.selection.marker, reference: profile.reference?.accession });
+function anchorStep(scope, profile, raw) {
+  const { store } = scope.ctx;
+  return scope.step({
+    type: "anchored-records",
+    step: { name: "anchor", version: 2 },
+    inputs: [ref(raw)],
+    parameters: markerParameters(profile),
+    tools: [ALIGNER],
+    run: async (put) => {
+      const index = JSON.parse(await raw.read("index.json"));
+      const parsed = /* @__PURE__ */ new Map();
+      for (const [version, sha] of Object.entries(index)) {
+        const text = await store.read(cachePath(version));
+        if (hashText(text) !== sha) throw new EngineError("raw-file-changed", `The downloaded file for ${version} changed after it was fetched`, `Delete ${cachePath(version)} and fetch again`);
+        const rec = parseGenBank(text)[0];
+        if (!rec) throw new EngineError("raw-file-changed", `The downloaded file for ${version} has no record in it`, `Delete ${cachePath(version)} and fetch again`);
+        parsed.set(version, rec);
+      }
+      const accession = profile.reference.accession;
+      const refRec = [...parsed.values()].find((r) => r.version === accession || r.accession === accession);
+      if (!refRec) throw new EngineError("reference-missing", `The reference ${accession} wasn't retrieved`, "Check the reference accession in Setup");
+      const reference = geneSequence(refRec, profile).sequence;
+      scope.log("info", "anchor", `Reference ${refRec.version}: ${reference.length} columns`);
+      const anchored = [];
+      const records = [];
+      let done = 0;
+      for (const [version, rec] of parsed) {
+        await scope.breathe();
+        const { sequence, from, located, manyPlaces } = locatedSequence(rec, reference, profile, geneSequence(rec, profile));
+        anchored.push({
+          ...located ? { located } : {},
+          ...manyPlaces ? { manyPlaces } : {},
+          record: rec.version || version,
+          ...rec.organism ? { organism: rec.organism } : {},
+          alignment: alignToReference(sequence, reference),
+          extractedFrom: from,
+          length: sequence.length,
+          ambiguous: (sequence.match(/[^ACGTacgt]/g) ?? []).length,
+          unverified: rec.definition.startsWith("UNVERIFIED")
+        });
+        records.push(toSequenceRecord(rec));
+        if (++done % 100 === 0) scope.log("debug", "anchor", `Anchored ${done} of ${parsed.size}`, { done, total: parsed.size });
+      }
+      await put("reference.fasta", writeFasta([{ id: refRec.version, sequence: reference }]));
+      await put("anchored.json", JSON.stringify(anchored));
+      await put("records.json", JSON.stringify(records));
+    },
+    ensure: async (read) => parseFasta(await read("reference.fasta"))[0]?.sequence.length ? null : "the reference has no sequence"
+  });
+}
+var panelGates = (profile) => ({ ...DEFAULT_GATES, ...profile.gates, frameErrors: true, ...profile.reference?.codonStart !== void 0 ? { codonStart: profile.reference.codonStart } : {}, ...profile.reference?.geneticCode ? { geneticCode: profile.reference.geneticCode } : {} });
+function gateStep(scope, profile, anchoredArtifact) {
+  const { filters, exclude } = profile.selection;
+  const gates = panelGates(profile);
+  return scope.step({
+    type: "gated-records",
+    step: { name: "gate", version: 2 },
+    inputs: [ref(anchoredArtifact)],
+    parameters: { filters, exclude, gates },
+    run: async (put) => {
+      const excluded = new Map(exclude.map((e) => [e.accession, e.reason]));
+      const anchored = JSON.parse(await anchoredArtifact.read("anchored.json"));
+      const records = JSON.parse(await anchoredArtifact.read("records.json"));
+      const outcomes = [];
+      const aligned = [];
+      for (const a of anchored) {
+        const assessed = assessAlignment(a.alignment, gatesForRecord(gates, { wholeRecord: a.extractedFrom === "whole-record", length: a.length, referenceLength: a.alignment?.aligned.length ?? 0 }));
+        const onlyFlank = a.located && a.alignment && a.alignment.clipped.start <= LOCATE_FLANK && a.alignment.clipped.end <= LOCATE_FLANK;
+        const diagnostics = onlyFlank ? assessed.filter((d) => d.code !== "clipped-ends") : assessed;
+        const fail = (code, message) => diagnostics.push({ severity: "error", code, message });
+        const reason = excluded.get(a.record) ?? excluded.get(a.record.split(".")[0]);
+        if (reason) fail("excluded-by-profile", reason);
+        if (filters.minLength !== void 0 && a.length < filters.minLength) fail("too-short", `${a.length} bp is under the minimum of ${filters.minLength}`);
+        if (filters.maxLength !== void 0 && a.length > filters.maxLength) fail("too-long", `${a.length} bp is over the maximum of ${filters.maxLength}`);
+        if (filters.maxAmbiguous !== void 0 && a.ambiguous > filters.maxAmbiguous) fail("too-ambiguous", `${a.ambiguous} ambiguous bases is over the maximum of ${filters.maxAmbiguous}`);
+        if (a.unverified) fail("unverified", "NCBI marks this record UNVERIFIED");
+        if (a.located) diagnostics.push({ severity: "info", code: "located-by-similarity", message: `The record doesn't annotate this marker, so it was cut out by similarity: ${where(a.located)}. ${a.located.seedHits} shared seeds` });
+        if (a.manyPlaces) fail("marker-in-several-places", `The marker looks present in ${a.manyPlaces.length} places, so none was chosen: ${a.manyPlaces.map(where).join("; ")}`);
+        const passed = !diagnostics.some((d) => d.severity === "error");
+        outcomes.push({ record: a.record, ...a.organism ? { organism: a.organism } : {}, status: passed ? "passed" : "excluded", diagnostics, columns: a.alignment ? a.alignment.matches + a.alignment.mismatches : 0, identity: a.alignment?.identity ?? 0, extractedFrom: a.extractedFrom });
+        if (a.alignment && passed) aligned.push({ id: a.record, sequence: a.alignment.aligned });
+      }
+      const passing = outcomes.filter((o) => o.status === "passed").length;
+      scope.log("info", "gate", `${passing} records passed, ${outcomes.length - passing} excluded`);
+      const counts = /* @__PURE__ */ new Map();
+      for (const o of outcomes) for (const d of o.diagnostics) counts.set(d.code, (counts.get(d.code) ?? 0) + 1);
+      for (const [code, n] of counts) scope.log("info", "gate", `${code}: ${n}`);
+      await put("outcomes.json", json(outcomes));
+      await put("aligned.fasta", writeFasta(aligned));
+      await put("reference.fasta", await anchoredArtifact.read("reference.fasta"));
+      await put("records.csv", toRecordSheet(records, { checks: outcomes.map((o) => ({ record: o.record, status: o.status, reasons: o.diagnostics.map((d) => d.message) })) }));
+    }
+  });
+}
+async function fetchAndAnchor(ctx, profile, options = {}) {
+  const errors = validateProfile(profile).filter((d) => d.severity === "error");
+  if (errors.length) throw new EngineError("invalid-profile", `The profile can't run: ${errors.map((e) => e.message).join("; ")}`, "Fix it in Setup");
+  if (!profile.reference?.accession) throw new EngineError("invalid-profile", "The profile needs a reference accession to anchor records to", "Add one in Setup");
+  const P = profilePaths(profile.id);
+  const { value, run } = await withRun(ctx, profile, "fetch", async (scope) => {
+    scope.run.tools.push(ALIGNER);
+    const client = new NcbiClient({ ...ctx.ncbi, log: (level, message, data) => scope.log(level, "ncbi", message, data) });
+    const { artifact: list, accessions, term } = await searchStep(scope, profile, client, options);
+    const raw = await rawStep(scope, list, accessions, client, options.batchSize ?? 100);
+    const anchored = await anchorStep(scope, profile, raw);
+    const gated = await gateStep(scope, profile, anchored);
+    const records = JSON.parse(await anchored.read("records.json"));
+    const outcomes = JSON.parse(await gated.read("outcomes.json"));
+    const index = JSON.parse(await raw.read("index.json"));
+    const snapshot = {
+      schemaVersion: 1,
+      id: scope.run.id,
+      createdAt: scope.run.startedAt,
+      sources: [{ name: "NCBI nuccore", query: term, retrievedAt: scope.run.startedAt }],
+      records,
+      rawFiles: records.map((r) => ({ path: cachePath(r.version || r.accession), sha256: index[r.version || r.accession] ?? "" }))
+    };
+    snapshot.checksum = hashText(canonicalJson2(snapshot));
+    scope.run.snapshot = { id: scope.run.id, checksum: snapshot.checksum };
+    const publish = async (name, text) => {
+      await ctx.store.write(`${scope.dir}/${name}`, text);
+      scope.run.outputs.push({ path: name, sha256: hashText(text) });
+    };
+    await publish("snapshot.json", json(snapshot));
+    for (const name of ["records.csv", "outcomes.json", "aligned.fasta", "reference.fasta"]) await publish(name, await gated.read(name));
+    return { records, outcomes };
+  });
+  await ctx.store.write(P.latest, run.id);
+  return { run, records: value.records, outcomes: value.outcomes };
+}
+function spanOf(alignment) {
+  if (!alignment) return void 0;
+  const start = alignment.aligned.search(/[^-]/);
+  if (start < 0) return void 0;
+  return [start, alignment.aligned.length - (alignment.aligned.match(/-*$/)?.[0].length ?? 0)];
+}
+async function studyRecords(ctx, client, accessions, onProgress) {
+  const stop = () => {
+    if (ctx.signal?.aborted) throw new EngineError("cancelled", "Cancelled");
+  };
+  const out = [];
+  const missing = [];
+  for (const a of accessions) {
+    stop();
+    if (await ctx.store.exists(cachePath(a))) {
+      const r = parseGenBank(await ctx.store.read(cachePath(a)))[0];
+      if (r) {
+        out.push(r);
+        continue;
+      }
+    }
+    missing.push(a);
+  }
+  for (let i = 0; i < missing.length; i += 100) {
+    stop();
+    out.push(...(await client.fetchGenBankText(missing.slice(i, i + 100))).records);
+    onProgress?.(out.length, accessions.length);
+  }
+  return out;
+}
+async function studyReference(ctx, client, profile) {
+  const accession = profile.reference?.accession;
+  if (!accession) throw new EngineError("invalid-profile", "A Study places records on the reference, and this profile has none", "Add a reference accession in Setup");
+  const [rec] = await studyRecords(ctx, client, [accession]);
+  if (!rec) throw new EngineError("reference-missing", `The reference ${accession} wasn't retrieved`, "Check the reference accession in Setup");
+  return geneSequence(rec, profile).sequence;
+}
+var countryOf = (rec) => toSequenceRecord(rec).geoLocName?.split(":")[0]?.trim() || void 0;
+async function placeRecords(ctx, profile, records, reference, classified) {
+  const placed = /* @__PURE__ */ new Map();
+  for (const rec of records) {
+    if (ctx.signal?.aborted) throw new EngineError("cancelled", "Cancelled");
+    await new Promise((r) => setTimeout(r, 0));
+    const hasMarker = classified.hasMarker.has(rec.version);
+    const span = hasMarker ? spanOf(alignToReference(geneSequence(rec, profile).sequence, reference)) : void 0;
+    const country = countryOf(rec);
+    placed.set(rec.version, { accession: rec.version, organism: rec.organism, length: rec.sequence.length, title: rec.definition, inTarget: classified.inTarget.has(rec.version), hasMarker, ...country ? { country } : {}, ...span ? { span } : {} });
+  }
+  return placed;
+}
+async function findRecordStudies(ctx, profile, onProgress) {
+  const client = new NcbiClient(ctx.ncbi);
+  const query = selectionQuery(profile.selection);
+  const genomes = genomesHoldingMarkerQuery(profile.selection);
+  const accessions = [.../* @__PURE__ */ new Set([...await client.searchAccessions(query), ...genomes ? await client.searchAccessions(genomes) : []])];
+  const reference = await studyReference(ctx, client, profile);
+  const records = await studyRecords(ctx, client, accessions, onProgress);
+  const all = new Set(records.map((r) => r.version));
+  const placed = await placeRecords(ctx, profile, records, reference, { inTarget: all, hasMarker: all });
+  return { papers: studiesFromRecords(records, (r) => placed.get(r.version)), columns: reference.length, query };
+}
+async function findPaperRecords(ctx, profile, pmid) {
+  const client = new NcbiClient(ctx.ncbi);
+  const accessions = await linkedAccessions(client, pmid);
+  const reference = await studyReference(ctx, client, profile);
+  if (!accessions.length) return { linked: [], columns: reference.length };
+  const classified = await classifyAccessions(client, accessions, profile.selection);
+  const records = await studyRecords(ctx, client, accessions);
+  return { linked: [...(await placeRecords(ctx, profile, records, reference, classified)).values()], columns: reference.length };
+}
+var defaultValidate = async (input) => fullValidation(input);
+async function buildPanelFromRun(ctx, profile, curation, id) {
+  const settings = profile.panel;
+  if (!settings) throw new EngineError("invalid-profile", "The profile has no panel settings", "Add groups in the Panel tab");
+  if (!settings.rules) throw new EngineError("invalid-profile", "This profile predates evaluation rules, so a panel built from it would use values nobody chose", "Set the rules in the Panel tab and give the panel a new version");
+  const P = profilePaths(profile.id);
+  const sourceId = id ?? (await ctx.store.exists(P.latest) ? (await ctx.store.read(P.latest)).trim() : "");
+  if (!sourceId) throw new EngineError("run-missing", "No finished fetch run exists yet", "Fetch records first");
+  const source = JSON.parse(await ctx.store.read(`${P.run(sourceId)}/run.json`));
+  const gatedRef = artifactOf(source, "gated-records");
+  if (!gatedRef) throw new EngineError("run-missing", `Run ${sourceId} didn't finish fetching`, "Fetch records again");
+  const { value, run } = await withRun(ctx, profile, "panel", async (scope) => {
+    scope.run.tools.push(ALIGNER);
+    const gated = await loadArtifact(ctx.store, { type: "gated-records", key: gatedRef.key });
+    const aligned = parseFasta(await gated.read("aligned.fasta"));
+    const reference = parseFasta(await gated.read("reference.fasta"))[0];
+    const groupIds = new Set(settings.groups.map((g) => g.id));
+    const records = JSON.parse(await (await loadArtifact(ctx.store, gated.manifest.inputs[0])).read("records.json"));
+    const studyOf = new Map(records.map((r) => [r.version, r.publications.find((p) => p.title && p.title !== "Direct Submission")?.title]));
+    const members = [];
+    const diagnostics = [];
+    let unassigned = 0;
+    for (const e of aligned) {
+      const decision = curation.records[e.id];
+      if (decision?.exclude) continue;
+      if (!decision?.group) {
+        unassigned++;
+        continue;
+      }
+      if (!groupIds.has(decision.group)) {
+        diagnostics.push({ severity: "error", code: "unknown-group", message: `${e.id} names group ${decision.group}, which isn't in the panel settings`, ids: [e.id] });
+        continue;
+      }
+      const study = decision.study ?? studyOf.get(e.id);
+      members.push({ record: e.id, group: decision.group, aligned: e.sequence, provenanceClass: decision.provenanceClass ?? "unknown", ...decision.use ? { use: decision.use } : {}, ...decision.site ? { block: decision.site } : {}, ...decision.originSource ? { originSource: decision.originSource } : {}, ...study ? { study } : {} });
+    }
+    if (!members.length && !diagnostics.some((d) => d.severity === "error")) throw new EngineError("empty-panel", "No records are assigned to a group, so there is nothing to build", "Assign records to groups in the Records tab");
+    const memberIds = new Set(members.map((m) => m.record));
+    const citations = /* @__PURE__ */ new Map();
+    for (const r of records) if (memberIds.has(r.version)) {
+      for (const p of r.publications) if (p.title) citations.set(p.title, { citation: [p.authors, p.title, p.journal].filter(Boolean).join(". ") });
+    }
+    const numtPath = `profiles/${profile.id}/numt-screen/numt-library.fasta`;
+    const numtCopies = await ctx.store.exists(numtPath) ? parseFasta(await ctx.store.read(numtPath)).map((e) => ({ id: e.id, aligned: e.sequence })) : [];
+    const input = {
+      settings,
+      taxa: profile.selection.taxa,
+      marker: profile.selection.marker,
+      reference: { accession: reference.id, length: reference.sequence.length, ...profile.reference?.codonStart !== void 0 ? { codonStart: profile.reference.codonStart } : {}, ...profile.reference?.geneticCode ? { geneticCode: profile.reference.geneticCode } : {} },
+      sources: [...citations.values()],
+      builtBy: gated.manifest.key,
+      referenceSequence: reference.sequence,
+      builtWith: [ENGINE, ALIGNER],
+      // The checks that actually ran on these records, even if the profile has changed since.
+      gates: gated.manifest.parameters.gates,
+      ...numtCopies.length ? { numtCopies } : {},
+      // From the fetch these records came from, not today's profile, which may have moved to another Study.
+      ...source.profile.selection.fromStudy ? { study: source.profile.selection.fromStudy } : {}
+    };
+    if (settings.validatedScope.length) diagnostics.push({ severity: "warning", code: "hand-entered-scope-ignored", message: "The scope written in the panel settings is ignored. A panel's scope now comes only from claims that pass validation", path: "panel.validatedScope" });
+    const draft = buildPanel({ ...input, members });
+    diagnostics.push(...validatePanel(draft.panel).filter((d) => d.code !== "not-validated"));
+    const empty = { scheme: "leave-one-block-out", tested: 0, skipped: 0, groups: [], untestedGroups: [], diagnostics: [] };
+    const hasErrors = diagnostics.some((d) => d.severity === "error");
+    if (hasErrors) return { bundle: draft, diagnostics, validation: { blocks: empty, groups: { ...empty, scheme: "leave-one-group-out" }, ladder: [], claims: [], controls: { shuffles: 0, simulations: 0, seed: 0 } }, unassigned, published: false };
+    const fingerprint = hashText(canonicalJson2({ settings: { ...settings, version: "", id: "" }, members: members.map(({ aligned: aligned2, ...m }) => ({ ...m, aligned: hashText(aligned2) })) }));
+    const validationArtifact = await scope.step({
+      type: "validation",
+      step: { name: "validate", version: 3 },
+      inputs: [ref(gated)],
+      parameters: { fingerprint },
+      run: async (put) => {
+        const reports = await (ctx.compute?.validate ?? defaultValidate)({ ...input, members }, ctx.signal);
+        await put("validation.json", json(reports));
+      }
+    });
+    const validation = JSON.parse(await validationArtifact.read("validation.json"));
+    const bundle = buildPanel({ ...input, members, claims: validatedScopeFromReport(validation.claims) });
+    if (!bundle.panel.claims.length) diagnostics.push({ severity: "warning", code: "not-validated", message: "No claim passed validation, so this panel has no validated scope", path: "validatedScope" });
+    const out = P.panel(bundle.panel.id, bundle.panel.version);
+    if (await ctx.store.exists(`${out}/panel.json`)) {
+      const existing = JSON.parse(await ctx.store.read(`${out}/panel.json`));
+      if (existing.checksum !== bundle.panel.checksum) throw new EngineError("panel-version-exists", `Panel ${bundle.panel.id} version ${bundle.panel.version} already exists with different content`, "Give this build a new version, so earlier results stay true");
+    }
+    const panelArtifact = await scope.step({
+      type: "panel",
+      step: { name: "panel", version: 2 },
+      inputs: [ref(gated), ref(validationArtifact)],
+      parameters: { checksum: bundle.panel.checksum },
+      tools: [ENGINE, ALIGNER],
+      run: async (put) => {
+        await put("panel.json", json(bundle.panel));
+        await put("panel.fasta", writeFasta([{ id: "__reference__", sequence: reference.sequence }, ...Object.entries(bundle.sequences).map(([k, sequence]) => ({ id: k, sequence }))]));
+      }
+    });
+    await ctx.store.write(`${out}/panel.json`, await panelArtifact.read("panel.json"));
+    await ctx.store.write(`${out}/panel.fasta`, await panelArtifact.read("panel.fasta"));
+    await ctx.store.write(`${out}/validation.json`, json(validation));
+    await ctx.store.write(`${out}/diagnostics.json`, json({ diagnostics, unassigned }));
+    await ctx.store.write(`${out}/artifact.json`, json(ref(panelArtifact)));
+    return { bundle, diagnostics, validation, unassigned, published: true };
+  });
+  return { ...value, run };
+}
+async function loadPanel(store, dir) {
+  if (!await store.exists(`${dir}/panel.json`)) throw new EngineError("panel-missing", "This panel hasn't been built yet", "Build it in the Panel tab");
+  const panel = JSON.parse(await store.read(`${dir}/panel.json`));
+  if (panel.schemaVersion !== 2) throw new EngineError("panel-outdated", `Panel ${panel.id} version ${panel.version} was built with an earlier format, so it can't be read by the current evaluator`, "Build it again under a new version");
+  const fasta = parseFasta(await store.read(`${dir}/panel.fasta`));
+  const referenceSequence = fasta.find((f) => f.id === "__reference__")?.sequence;
+  const bundle = { panel, sequences: Object.fromEntries(fasta.filter((f) => f.id !== "__reference__").map((f) => [f.id, f.sequence])), ...referenceSequence ? { referenceSequence } : {} };
+  const problems = verifyBundle(bundle);
+  if (problems.length) throw new EngineError("panel-changed", `Panel ${panel.id} version ${panel.version} doesn't match its seal: ${problems.map((p) => p.message).join("; ")}`, "Restore it from its source, or build it again under a new version");
+  return bundle;
+}
+function panelVersions(profile, folders) {
+  const prefix = `${profile.panel?.id ?? ""}-`;
+  const parts = (v) => v.split(".").map(Number);
+  const order = (a, b) => {
+    const x = parts(a), y = parts(b);
+    for (let i = 0; i < Math.max(x.length, y.length); i++) {
+      const d = (x[i] ?? 0) - (y[i] ?? 0);
+      if (d) return d;
+    }
+    return a.localeCompare(b);
+  };
+  return folders.filter((f) => f.startsWith(prefix)).map((f) => f.slice(prefix.length)).sort(order);
+}
+async function comparePanelVersions(store, profile, a, b) {
+  if (!profile.panel) throw new EngineError("invalid-profile", "The profile has no panel settings", "Add groups in the Panel tab");
+  const P = profilePaths(profile.id);
+  const load = async (version) => {
+    const dir = P.panel(profile.panel.id, version);
+    const { panel } = await loadPanel(store, dir);
+    const report = await store.exists(`${dir}/validation.json`) ? JSON.parse(await store.read(`${dir}/validation.json`)).claims : void 0;
+    return { panel, report };
+  };
+  const [x, y] = [await load(a), await load(b)];
+  return compareRuns(x.panel, y.panel, x.report, y.report);
+}
+function testSample(sequence, queryId, bundle, options = {}) {
+  if (!bundle.referenceSequence) throw new EngineError("panel-outdated", "This panel has no reference sequence", "Build it again");
+  const a = alignToReference(sequence, bundle.referenceSequence);
+  const diagnostics = assessAlignment(a, { ...bundle.panel.gates, frameErrors: false });
+  if (!a || diagnostics.some((d) => d.severity === "error")) return { result: null, diagnostics };
+  const numtCaveats = [];
+  if (bundle.panel.numtCopies?.length) {
+    const numt = checkNumts(a.aligned, bundle.panel.numtCopies, bundle.referenceSequence);
+    for (const f of numt.flagged) diagnostics.push({ severity: "warning", code: "numt-flagged", message: `This sequence is closer to nuclear copy ${f.copy} than to the reference, over ${f.shared} columns (${(f.toCopy * 100).toFixed(1)}% against ${(f.toReference * 100).toFixed(1)}%). Review it. This doesn't prove it's a nuclear copy` });
+    numtCaveats.push(numt.flagged.length ? "Flagged for review as possibly a nuclear copy of the marker" : `Compared with ${numt.tested} of ${bundle.panel.numtCopies.length} known nuclear copies with no flag. That doesn't clear it, since copies absent from the screened genome can't be seen`);
+  }
+  const result = evaluateQuery(a.aligned, bundle, {
+    queryId,
+    runId: options.runId ?? "sample",
+    querySha256: hashText(sequence.toUpperCase()),
+    producedBy: [ENGINE, ALIGNER],
+    caveats: ["Rules are configured values and these statuses are not probabilities", ...diagnostics.filter((d) => d.severity === "warning").map((d) => d.message), ...numtCaveats]
+  });
+  diagnostics.push(...validateResult(result, bundle.panel));
+  return { result, diagnostics, aligned: a.aligned, insertions: a.insertions.reduce((s, x) => s + x.length, 0), deletions: a.deletions.reduce((s, x) => s + x.length, 0), identity: a.identity, clipped: a.clipped };
+}
+async function runSample(ctx, profile, sequence, queryId) {
+  if (!profile.panel) throw new EngineError("invalid-profile", "The profile has no panel settings", "Add groups in the Panel tab");
+  const P = profilePaths(profile.id);
+  const dir = P.panel(profile.panel.id, profile.panel.version);
+  const bundle = await loadPanel(ctx.store, dir);
+  const panelRef = JSON.parse(await ctx.store.read(`${dir}/artifact.json`));
+  const { value, run } = await withRun(ctx, profile, "sample", async (scope) => {
+    scope.run.tools.push(ALIGNER);
+    const panelArtifact = await loadArtifact(ctx.store, panelRef);
+    if (JSON.parse(await panelArtifact.read("panel.json")).checksum !== bundle.panel.checksum) throw new EngineError("panel-changed", `The saved copy of panel ${bundle.panel.id} isn't the one its record traces back to`, "Build it again under a new version");
+    const artifact = await scope.step({
+      type: "sample-result",
+      step: { name: "sample", version: 1 },
+      inputs: [ref(panelArtifact)],
+      parameters: { queryId, sequence: hashText(sequence.toUpperCase()) },
+      tools: [ENGINE, ALIGNER],
+      run: async (put) => {
+        await put("outcome.json", json(testSample(sequence, queryId, bundle, { runId: scope.run.id })));
+      }
+    });
+    const text = await artifact.read("outcome.json");
+    await ctx.store.write(`${P.results}/${bundle.panel.id}-${bundle.panel.version}/${queryId.replace(/[^A-Za-z0-9._-]/g, "_")}.json`, text);
+    return { outcome: JSON.parse(text), artifact: ref(artifact) };
+  });
+  return { ...value.outcome, run, artifact: value.artifact };
+}
+async function buildTree(ctx, profile, options) {
+  if (!ctx.tools) throw new EngineError("tool-missing", "Building a tree needs a tool runner");
+  const settings = profile.tree;
+  if (!settings) throw new EngineError("invalid-profile", "The profile has no tree settings");
+  const tool = options.tool ?? "iqtree3";
+  const version = await ctx.tools.version(tool);
+  if (!version) throw new EngineError("tool-missing", `${tool} isn't installed or can't be found`, `Install it with: brew install ${tool}`);
+  const tools = ctx.tools;
+  const P = profilePaths(profile.id);
+  const sourceId = options.runId ?? (await ctx.store.exists(P.latest) ? (await ctx.store.read(P.latest)).trim() : "");
+  if (!sourceId) throw new EngineError("run-missing", "No finished fetch run exists yet", "Fetch records first");
+  const source = JSON.parse(await ctx.store.read(`${P.run(sourceId)}/run.json`));
+  const gatedRef = artifactOf(source, "gated-records");
+  if (!gatedRef) throw new EngineError("run-missing", `Run ${sourceId} didn't finish fetching`, "Fetch records again");
+  const { value, run } = await withRun(ctx, profile, "tree", async (scope) => {
+    scope.run.tools.push({ name: tool, version });
+    const gated = await loadArtifact(ctx.store, { type: "gated-records", key: gatedRef.key });
+    const aligned = parseFasta(await gated.read("aligned.fasta"));
+    const w = options.window ?? { start: 0, end: aligned[0]?.sequence.length ?? 0 };
+    const min = options.minCoverage ?? 0.85;
+    const usable = aligned.map((e) => ({ id: e.id, aligned: e.sequence.slice(w.start, w.end) })).filter((e) => (e.aligned.match(/[ACGT]/gi) ?? []).length >= min * (w.end - w.start));
+    const haps = collapseHaplotypes(usable);
+    if (haps.length < 4) throw new EngineError("step-output-invalid", `Only ${haps.length} haplotypes cover this window, and a tree needs at least 4`, "Choose another window, or lower the coverage needed");
+    const outgroups = profile.selection.outgroups.map((o) => o.accession).filter((a) => Boolean(a));
+    const names = new Map(haps.map((h, i) => [h, `H${String(i + 1).padStart(4, "0")}`]));
+    const og = haps.filter((h) => h.members.some((m) => outgroups.includes(m))).map((h) => names.get(h));
+    const artifact = await scope.step({
+      type: "tree",
+      step: { name: "tree", version: 1 },
+      inputs: [ref(gated)],
+      parameters: { window: w, minCoverage: min, tree: settings, outgroups: og },
+      tools: [{ name: tool, version }],
+      run: async (put, dir, register) => {
+        await put("input.fasta", writeFasta(haps.map((h) => ({ id: names.get(h), sequence: h.representative }))));
+        await put("tips.json", json(haps.map((h) => ({ id: names.get(h), members: h.members }))));
+        const args = ["-s", "input.fasta", "-m", settings.model, "-B", String(settings.bootstrap), "--alrt", String(settings.shAlrt), "--seed", String(settings.seed), "-T", String(settings.threads), "-pre", "tree", "-redo", ...og.length ? ["-o", og.join(",")] : []];
+        const res = await tools.run(tool, args, { cwd: `${options.absoluteDir}/${dir}` });
+        await ctx.store.write(`${dir}/tool.log`, `${res.stdout}
+${res.stderr}`);
+        if (res.code !== 0) throw new EngineError("tool-failed", `${tool} failed: ${(res.stderr || res.stdout).slice(0, 600)}`, `See ${dir}/tool.log`);
+        await register("tree.treefile");
+        await register("tree.iqtree");
+      },
+      ensure: async (read) => (await read("tree.treefile")).includes("(") ? null : "the tree file has no tree in it"
+    });
+    return { newick: await artifact.read("tree.treefile"), tips: JSON.parse(await artifact.read("tips.json")), artifact: ref(artifact) };
+  });
+  return { tool, version, ...value, run };
+}
+export {
+  ENGINE_VERSION,
+  EngineError,
+  buildPanelFromRun,
+  buildTree,
+  comparePanelVersions,
+  fetchAndAnchor,
+  findPaperRecords,
+  findRecordStudies,
+  isCancelled,
+  loadArtifact,
+  loadPanel,
+  panelVersions,
+  profilePaths,
+  runSample,
+  testSample,
+  traceArtifact
+};

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@captiveorigins/onephylogeny-engine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-alpha.1",
+  "description": "OnePhylogeny engine: runs profiles end to end with immutable run records and structured logs: fetch, anchor, gate, build panels, validate, test samples and build trees through replaceable ports.",
+  "keywords": [
+    "phylogenetics",
+    "reference-panel",
+    "genbank"
+  ],
+  "homepage": "https://github.com/CaptiveOrigins/onephylogeny#readme",
+  "bugs": {
+    "url": "https://github.com/CaptiveOrigins/onephylogeny/issues"
+  },
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CaptiveOrigins/onephylogeny.git",
+    "directory": "packages/engine"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@captiveorigins/onephylogeny-acquire": "^0.1.0-alpha.1",
+    "@captiveorigins/onephylogeny-core": "^0.1.0-alpha.1"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --target es2022",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
 }