@captiveorigins/payload-plugin-onephylogeny 0.1.0-alpha.0 → 0.1.0-alpha.3

package/README.md

@@ -3,3 +3,23 @@
 OnePhylogeny for Payload: immutable reference panels and released results on your own collections, with server-enforced review, safe endpoints and no coordinates.
 
 See the [repository](https://github.com/CaptiveOrigins/onephylogeny) for documentation.
+
+## Samples and sequences
+
+Pass `records` to add `samples` and `sequences`. A lab's file becomes one of each through one call:
+
+```ts
+import { registerSequence } from '@captiveorigins/payload-plugin-onephylogeny'
+
+const { sample, sequence, created } = await registerSequence(payload, {
+  tenant, animal, kit, lab, file, // your own record IDs; taxon is read from the animal if you leave it out
+  sha256,                          // computed by your server from the stored bytes
+  text,                            // the file's contents, which must hash to sha256
+  marker: 'cytb',
+})
+```
+
+It refuses, in plain words, a file whose text doesn't match its SHA-256, a file with more or fewer than one sequence, characters that aren't DNA bases, a sequence outside the lengths set for its marker, and an animal with no species. Sending the same file for the same kit again changes nothing (`created: false`). It writes with full access, so check first that the caller may submit results for that kit.
+
+`assignWaiting(payload, { evaluate })` is the sweep. It tests each waiting sequence against the panel for its marker and species, using the `evaluate` function you pass (OnePhylogeny's `testSample` in a Node job), and records a result pending review. A sequence with no panel stays waiting, and one the panel's checks refuse is marked `not-assessable`, with the reason. Results reach readers only after a reviewer approves them.
+

package/dist/index.d.ts

@@ -1,4 +1,99 @@
-import { Access, Plugin } from 'payload';
+import { Result } from '@captiveorigins/onephylogeny-core';
+import { Access, PayloadRequest, Payload, Where, Plugin } from 'payload';
+
+/** Settings for the optional `samples` and `sequences` collections. */
+type RecordsOptions = {
+    slugs?: {
+        samples?: string;
+        sequences?: string;
+    };
+    /** Host collections for the kit a sample came in and the lab that read it. Left out, the field isn't added. */
+    relations?: {
+        kit?: string;
+        lab?: string;
+    };
+    /** Who may read samples and sequences, besides managers. Default: managers only. */
+    readAccess?: Access;
+    /** The markers a sequence may be for, with the lengths accepted. Default: any marker, 100 to 50,000 bases. */
+    markers?: Record<string, {
+        minLength?: number;
+        maxLength?: number;
+    }>;
+    /** The host's tenant field, filled from `registerSequence`'s `tenant` and copied onto results. Default `tenant`. */
+    tenantField?: string;
+};
+/** Reads one FASTA file as one sequence, or says in plain words why it can't. */
+declare function readSingleSequence(text: string, marker: string, markers?: RecordsOptions['markers']): {
+    recordId: string;
+    residues: string;
+};
+type RegisterSequenceInput = {
+    /** The host's tenant (site), written to the tenant field. */
+    tenant?: string | number;
+    animal: string | number;
+    /** Taken from the animal's `taxon` field when left out. */
+    taxon?: string | number;
+    kit?: string | number;
+    lab?: string | number;
+    /** The host's file record holding the bytes the lab sent. */
+    file?: string | number;
+    /** SHA-256 of the file, as the host computed it from the stored bytes. */
+    sha256: string;
+    /** The file's text. It must hash to `sha256`. */
+    text: string;
+    marker: string;
+    source?: 'kit' | 'upload' | 'historic';
+    collectedAt?: string;
+    req?: PayloadRequest;
+};
+/**
+ * Records one lab file as a sample and a sequence. It writes with full access, so the caller must already have checked
+ * that this person may submit results for this kit. Calling it again with the same kit and file changes nothing.
+ */
+declare function registerSequence(payload: Payload, input: RegisterSequenceInput): Promise<{
+    sample: Record<string, unknown>;
+    sequence: Record<string, unknown>;
+    created: boolean;
+}>;
+/** What `assignWaiting` asks the host to compute for one sequence against one panel. */
+type Evaluate = (args: {
+    residues: string;
+    queryId: string;
+    panel: Record<string, unknown>;
+}) => Promise<{
+    result: Result | null;
+    problems: string[];
+}>;
+/** A short, plain summary of a result, naming the groups it is consistent with. */
+declare function summarize(result: Result, panel: {
+    groups?: {
+        groupId: string;
+        label: string;
+    }[];
+}): string;
+/**
+ * The sweep: tests each sequence still `received` against the panel for its marker and species, and records a result
+ * waiting for review. A sequence with no panel stays waiting; one the checks refuse is marked not assessable, with why.
+ */
+declare function assignWaiting(payload: Payload, args: {
+    evaluate: Evaluate;
+    limit?: number;
+    req?: PayloadRequest;
+}): Promise<{
+    checked: number;
+    assigned: number;
+    notAssessable: number;
+    noPanel: number;
+}>;
+
+type Granted = boolean | Where;
+/**
+ * Joins access results with "or". A rule may grant everything (`true`), nothing, or only matching records (a query), and
+ * a query is never read as everything: a reviewer of one site sees that site's records, not all of them.
+ */
+declare function either(...grants: (Granted | null | undefined)[]): Granted;
+/** Access that allows what any of the given rules allows. */
+declare const anyOf: (...rules: (Access | undefined)[]) => Access;
 
 type OnePhylogenyPluginOptions = {
     /** Slugs of the collections this plugin adds. */
@@ -14,7 +109,7 @@ type OnePhylogenyPluginOptions = {
         files?: string;
         importRuns?: string;
     };
-    /** Who may create panels and results, and activate panels. Default: nobody but trusted local scripts. */
+    /** Who may create panels and results, and activate panels. Default: nobody but trusted local scripts. Activating also needs a signed-in user, who is recorded. */
     manageAccess?: Access;
     /** Who may approve or reject results. Default: same as manageAccess. */
     reviewAccess?: Access;
@@ -22,11 +117,22 @@ type OnePhylogenyPluginOptions = {
     readReleasedAccess?: Access;
     /** Field added to assignments for multi-tenant hosts' isolation plugins to find. */
     group?: string;
+    /**
+     * Which panels results may be made against. `activeOrShown` also allows a `candidate` a maintainer ticked "shown as
+     * exploratory", and lets readers see such candidates. Default: `active`.
+     */
+    resultsAgainst?: 'active' | 'activeOrShown';
+    /**
+     * Adds `samples` and `sequences`, with `registerSequence` to record a lab's file and `assignWaiting` to test waiting
+     * sequences. Left out, neither collection is added. Results then relate to these sequences.
+     */
+    records?: RecordsOptions;
 };
+
 /**
  * OnePhylogeny for Payload. Adds immutable panels and reviewed results, relating to whatever collections a site already
  * has. It holds no species knowledge. Compute happens elsewhere: this stores what was computed and controls release.
  */
 declare const onePhylogeny: (options?: OnePhylogenyPluginOptions) => Plugin;
 
-export { type OnePhylogenyPluginOptions, onePhylogeny };
+export { type Evaluate, type OnePhylogenyPluginOptions, type RecordsOptions, type RegisterSequenceInput, anyOf, assignWaiting, either, onePhylogeny, readSingleSequence, registerSequence, summarize };

package/dist/index.js

@@ -1,6 +1,216 @@
 // src/index.ts
 import { validateResult } from "@captiveorigins/onephylogeny-core";
+import { relationship as validateRelationship } from "payload/shared";
+
+// src/access.ts
+function either(...grants) {
+  if (grants.some((g) => g === true)) return true;
+  const queries = grants.filter((g) => Boolean(g) && typeof g === "object");
+  return queries.length === 0 ? false : queries.length === 1 ? queries[0] : { or: queries };
+}
+var anyOf = (...rules) => async (args) => either(...await Promise.all(rules.map((r) => r ? r(args) : false)));
+
+// src/records.ts
+import { parseFasta, sha256Hex } from "@captiveorigins/onephylogeny-core";
 import { APIError } from "payload";
+var CUSTOM_KEY = "onePhylogenyRecords";
+var DNA = /^[ACGTRYKMSWBDHVN]+$/;
+var DEFAULT_LENGTH = { minLength: 100, maxLength: 5e4 };
+var fail = (message) => {
+  throw new APIError(message, 400, void 0, true);
+};
+var idOf = (v) => v && typeof v === "object" ? String(v.id) : v == null ? void 0 : String(v);
+var relation = (name, relationTo, extra = {}) => relationTo ? [{ name, type: "relationship", relationTo, index: true, ...extra }] : [];
+var locked = (fields, message) => ({ data, originalDoc, operation }) => {
+  if (operation === "update") {
+    for (const f of fields) if (f in data && JSON.stringify(idOf(data[f]) ?? data[f] ?? null) !== JSON.stringify(idOf(originalDoc[f]) ?? originalDoc[f] ?? null)) fail(message);
+  }
+  return data;
+};
+function recordCollections(o, base) {
+  const samples = o.slugs?.samples ?? "samples";
+  const sequences = o.slugs?.sequences ?? "sequences";
+  const manage = base.manage;
+  const read = anyOf(manage, o.readAccess);
+  const access = { read, create: manage, update: manage, delete: () => false };
+  const sampleCollection = {
+    slug: samples,
+    labels: { singular: "Sample", plural: "Samples" },
+    admin: { group: "Genetics", defaultColumns: ["subject", "source", "kit", "createdAt"] },
+    access,
+    fields: [
+      ...relation("subject", base.subject, { required: true }),
+      ...relation("kit", o.relations?.kit),
+      ...relation("taxon", base.taxa),
+      { name: "source", type: "select", required: true, defaultValue: "kit", options: ["kit", "upload", "historic"] },
+      { name: "material", type: "text", admin: { description: "What was sampled, such as a shell scrape or blood." } },
+      { name: "collectedAt", type: "date" },
+      { name: "consent", type: "text", admin: { description: "The keeper's consent, as recorded with the kit or upload." } }
+    ],
+    hooks: { beforeChange: [locked(["subject", "kit", "source"], "A sample's animal, kit and source can't change. Record a new sample instead.")] }
+  };
+  const sequenceCollection = {
+    slug: sequences,
+    labels: { singular: "Sequence", plural: "Sequences" },
+    admin: { group: "Genetics", useAsTitle: "recordId", defaultColumns: ["recordId", "marker", "status", "length", "createdAt"] },
+    access,
+    fields: [
+      { name: "sample", type: "relationship", relationTo: samples, required: true, index: true },
+      { name: "marker", type: "text", required: true, index: true },
+      ...relation("lab", o.relations?.lab),
+      ...relation("file", base.files, { admin: { description: "The file the lab sent. It stays the record of what was received." } }),
+      { name: "sha256", type: "text", required: true, index: true, admin: { description: "SHA-256 of the file, checked against its text when it was registered." } },
+      { name: "recordId", type: "text", admin: { description: "The FASTA header the lab gave this sequence." } },
+      { name: "residues", type: "textarea", required: true, admin: { description: "The bases, cleaned of gaps and line breaks. Used for analysis." } },
+      { name: "length", type: "number", required: true },
+      { name: "status", type: "select", required: true, defaultValue: "received", index: true, options: ["received", "assigned", "not-assessable"] },
+      { name: "statusReason", type: "text", admin: { description: "Why it couldn't be assessed, in plain words." } }
+    ],
+    hooks: { beforeChange: [locked(["sample", "marker", "file", "sha256", "residues", "recordId", "length"], "A sequence can't be edited. Register the corrected file instead.")] }
+  };
+  const config = {
+    samples,
+    sequences,
+    panels: base.panels,
+    assignments: base.assignments,
+    tenantField: o.tenantField ?? "tenant",
+    markers: o.markers,
+    subject: base.subject,
+    hasTaxa: Boolean(base.taxa),
+    hasKit: Boolean(o.relations?.kit),
+    hasLab: Boolean(o.relations?.lab),
+    hasFiles: Boolean(base.files),
+    againstShown: base.againstShown
+  };
+  return { collections: [sampleCollection, sequenceCollection], config, customKey: CUSTOM_KEY };
+}
+var configOf = (payload) => {
+  const c = payload.config.custom?.[CUSTOM_KEY];
+  if (!c) throw new Error("OnePhylogeny samples and sequences aren't turned on. Pass `records` to the plugin.");
+  return c;
+};
+function readSingleSequence(text, marker, markers) {
+  if (markers && !markers[marker]) fail(`This site doesn't test the marker "${marker}".`);
+  const { minLength, maxLength } = { ...DEFAULT_LENGTH, ...markers?.[marker] };
+  let entries;
+  try {
+    entries = parseFasta(text.replace(/^/, ""));
+  } catch {
+    return fail(`This file isn't FASTA: it has bases before the first ">" header line.`);
+  }
+  if (!entries.length) fail(`This file is empty or has no ">" header line, so it isn't FASTA.`);
+  if (entries.length > 1) fail(`This file holds ${entries.length} sequences. Send one file per kit, with one sequence in it.`);
+  const entry = entries[0];
+  const residues = entry.sequence.replace(/[\s\-.]/g, "").toUpperCase();
+  if (!residues) fail("This file's sequence is empty.");
+  if (!DNA.test(residues)) {
+    const bad = [...new Set(residues.replace(/[ACGTRYKMSWBDHVN]/g, ""))].slice(0, 5).join(" ");
+    fail(`This sequence has characters that aren't DNA bases: ${bad}.`);
+  }
+  if (residues.length < minLength) fail(`This sequence is ${residues.length} bases long, shorter than the ${minLength} needed for ${marker}.`);
+  if (residues.length > maxLength) fail(`This sequence is ${residues.length} bases long, longer than the ${maxLength} expected for ${marker}.`);
+  const unresolved = (residues.match(/[^ACGT]/g) ?? []).length;
+  if (unresolved > residues.length / 2) fail(`More than half of this sequence's bases are unresolved (${unresolved} of ${residues.length}).`);
+  return { recordId: entry.id, residues };
+}
+async function registerSequence(payload, input) {
+  const c = configOf(payload);
+  const opts = { req: input.req, overrideAccess: true, depth: 0 };
+  const sha256 = input.sha256.replace(/^sha256:/i, "").toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(sha256)) fail("The file's SHA-256 is missing or malformed.");
+  if (sha256Hex(input.text) !== sha256) fail("This file's text doesn't match its SHA-256. It may have changed after upload; upload it again.");
+  if ((input.source ?? "kit") === "kit" && input.kit == null) fail("A kit sample needs its kit.");
+  if (input.animal == null || input.animal === "") fail("This kit isn't linked to an animal yet. It has to be activated first.");
+  const { recordId, residues } = readSingleSequence(input.text, input.marker, c.markers);
+  let taxon = input.taxon;
+  if (taxon == null && c.hasTaxa) {
+    const subject = c.subject ? await payload.findByID({ collection: c.subject, id: input.animal, ...opts }).catch(() => null) : null;
+    taxon = idOf(subject?.taxon);
+  }
+  if (c.hasTaxa && taxon == null) fail("This animal has no species recorded, so its sequence can't be matched to a panel.");
+  let sample;
+  if (input.kit != null && c.hasKit) {
+    sample = (await payload.find({ collection: c.samples, where: { kit: { equals: input.kit } }, limit: 1, ...opts })).docs[0];
+    if (sample && idOf(sample.subject) !== String(input.animal)) fail("This kit is already recorded for another animal.");
+  }
+  if (sample) {
+    const existing = (await payload.find({ collection: c.sequences, where: { and: [{ sample: { equals: sample.id } }, { sha256: { equals: sha256 } }] }, limit: 1, ...opts })).docs[0];
+    if (existing) return { sample, sequence: existing, created: false };
+  } else {
+    sample = await payload.create({ collection: c.samples, data: {
+      ...c.subject ? { subject: input.animal } : {},
+      ...c.hasKit && input.kit != null ? { kit: input.kit } : {},
+      ...c.hasTaxa ? { taxon } : {},
+      source: input.source ?? "kit",
+      ...input.collectedAt ? { collectedAt: input.collectedAt } : {},
+      ...input.tenant != null ? { [c.tenantField]: input.tenant } : {}
+    }, ...opts });
+  }
+  const sequence = await payload.create({ collection: c.sequences, data: {
+    sample: sample.id,
+    marker: input.marker,
+    sha256,
+    recordId,
+    residues,
+    length: residues.length,
+    status: "received",
+    ...c.hasLab && input.lab != null ? { lab: input.lab } : {},
+    ...c.hasFiles && input.file != null ? { file: input.file } : {},
+    ...input.tenant != null ? { [c.tenantField]: input.tenant } : {}
+  }, ...opts });
+  return { sample, sequence, created: true };
+}
+function summarize(result, panel) {
+  const label = (id) => panel.groups?.find((g) => g.groupId === id)?.label ?? id;
+  const consistent = result.findings.filter((f) => f.status === "consistent").map((f) => label(f.group));
+  if (consistent.length === 1) return `Consistent with ${consistent[0]}`;
+  if (consistent.length > 1) return `Consistent with ${consistent.slice(0, -1).join(", ")} or ${consistent.at(-1)}`;
+  return "No single lineage";
+}
+async function assignWaiting(payload, args) {
+  const c = configOf(payload);
+  const opts = { req: args.req, overrideAccess: true, depth: 0 };
+  const tally = { assigned: 0, notAssessable: 0, noPanel: 0 };
+  const waiting = await payload.find({ collection: c.sequences, where: { status: { equals: "received" } }, sort: "createdAt", limit: args.limit ?? 200, ...opts });
+  const usable = c.againstShown ? { or: [{ status: { equals: "active" } }, { and: [{ status: { equals: "candidate" } }, { shownAsExploratory: { equals: true } }] }] } : { status: { equals: "active" } };
+  for (const seq of waiting.docs) {
+    const sample = await payload.findByID({ collection: c.samples, id: idOf(seq.sample), ...opts });
+    const taxon = idOf(sample.taxon);
+    const found = await payload.find({ collection: c.panels, where: { and: [{ marker: { equals: seq.marker } }, usable] }, sort: "-createdAt", limit: 50, ...opts });
+    const fits = found.docs.filter((p) => !c.hasTaxa || !p.taxa?.length || p.taxa.map(idOf).includes(taxon));
+    const panel = fits.find((p) => p.status === "active") ?? fits[0];
+    if (!panel) {
+      tally.noPanel++;
+      continue;
+    }
+    const already = await payload.find({ collection: c.assignments, where: { and: [{ sequence: { equals: seq.id } }, { panel: { equals: panel.id } }] }, limit: 1, ...opts });
+    if (already.docs.length) {
+      await payload.update({ collection: c.sequences, id: seq.id, data: { status: "assigned" }, ...opts });
+      continue;
+    }
+    const { result, problems } = await args.evaluate({ residues: String(seq.residues), queryId: String(seq.id), panel });
+    if (!result) {
+      await payload.update({ collection: c.sequences, id: seq.id, data: { status: "not-assessable", statusReason: (problems.join("; ") || "The panel's checks refused this sequence.").slice(0, 1e3) }, ...opts });
+      tally.notAssessable++;
+      continue;
+    }
+    const tenant = sample[c.tenantField];
+    await payload.create({ collection: c.assignments, data: {
+      ...c.subject ? { subject: idOf(sample.subject) } : {},
+      sequence: seq.id,
+      panel: panel.id,
+      summary: summarize(result, panel),
+      result,
+      ...tenant != null ? { [c.tenantField]: idOf(tenant) } : {}
+    }, ...opts });
+    await payload.update({ collection: c.sequences, id: seq.id, data: { status: "assigned" }, ...opts });
+    tally.assigned++;
+  }
+  return { ...tally, checked: waiting.docs.length };
+}
+
+// src/index.ts
+import { APIError as APIError2 } from "payload";
 var PANEL_TRANSITIONS = { candidate: ["active", "withdrawn"], active: ["superseded", "withdrawn"], superseded: ["withdrawn"], withdrawn: [] };
 var LOCKED_PANEL_FIELDS = ["key", "version", "marker", "checksum", "artifact", "importRun", "taxa", "groups", "notCovered", "validatedScope"];
 var REVIEW_TRANSITIONS = { pending: ["approved", "rejected"], approved: ["withdrawn"], rejected: [], withdrawn: [] };
@@ -10,30 +220,45 @@ var hasCoordinates = (value) => {
   if (!value || typeof value !== "object") return false;
   return Object.entries(value).some(([k, v]) => COORDINATES.test(k) || hasCoordinates(v));
 };
-var fail = (message) => {
-  throw new APIError(message, 400, void 0, true);
+var fail2 = (message) => {
+  throw new APIError2(message, 400, void 0, true);
 };
-var idOf = (v) => v && typeof v === "object" ? String(v.id) : v == null ? void 0 : String(v);
+var idOf2 = (v) => v && typeof v === "object" ? String(v.id) : v == null ? void 0 : String(v);
 var same = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
 var stripIds = (rows) => Array.isArray(rows) ? rows.map((r) => {
   const { id: _id, ...rest } = r;
   return rest;
 }) : rows;
-var panelBeforeChange = ({ data, originalDoc, operation }) => {
-  if (hasCoordinates(data.groups)) fail("Panels use generalized regions and never hold coordinates.");
+var stamp = (v) => v == null || v === "" ? "" : v instanceof Date ? v.toISOString() : String(v);
+var ACTIVATION_FIELDS = ["activatedBy", "activatedAt"];
+var panelBeforeChange = ({ data, originalDoc, operation, req }) => {
+  const leaving = operation === "update" && String(data.status ?? originalDoc.status) !== "candidate";
+  if (leaving) {
+    if (data.shownAsExploratory === true && String(originalDoc.status) !== "candidate") fail2("Only a candidate panel can be shown as exploratory.");
+    data.shownAsExploratory = false;
+  }
+  if (hasCoordinates(data.groups)) fail2("Panels use generalized regions and never hold coordinates.");
   if (operation === "create") {
-    if ((data.status ?? "candidate") !== "candidate") fail("A new panel starts as a candidate.");
+    if ((data.status ?? "candidate") !== "candidate") fail2("A new panel starts as a candidate.");
+    if (ACTIVATION_FIELDS.some((f) => stamp(data[f]))) fail2("Who activated a panel, and when, are set by activating.");
     return data;
   }
   const from = String(originalDoc.status);
   const to = String(data.status ?? from);
-  if (to !== from && !PANEL_TRANSITIONS[from]?.includes(to)) fail(`A panel can't go from ${from} to ${to}.`);
-  if (from === "candidate" && to === "active" && !(data.validatedScope ?? originalDoc.validatedScope)?.length) fail("A panel with no validated claims can't become active.");
+  if (to !== from && !PANEL_TRANSITIONS[from]?.includes(to)) fail2(`A panel can't go from ${from} to ${to}.`);
+  if (from === "candidate" && to === "active") {
+    if (!(data.validatedScope ?? originalDoc.validatedScope)?.length) fail2("A panel with no validated claims can't become active.");
+    if (!req.user) fail2("Activating a panel needs a signed-in person, who is recorded.");
+    data.activatedBy = String(req.user.id);
+    data.activatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  } else if (ACTIVATION_FIELDS.some((f) => f in data && stamp(data[f]) !== stamp(originalDoc[f]))) {
+    fail2("Who activated a panel, and when, are set by activating.");
+  }
   if (from !== "candidate") {
     for (const f of LOCKED_PANEL_FIELDS) {
       if (!(f in data)) continue;
-      const changed = f === "groups" ? !same(stripIds(data[f]), stripIds(originalDoc[f])) : Array.isArray(data[f]) ? !same(data[f].map(idOf), (originalDoc[f] ?? []).map(idOf)) : idOf(data[f]) !== idOf(originalDoc[f]);
-      if (changed) fail(`A ${from} panel can't be edited. Build a new version instead.`);
+      const changed = f === "groups" ? !same(stripIds(data[f]), stripIds(originalDoc[f])) : Array.isArray(data[f]) ? !same(data[f].map(idOf2), (originalDoc[f] ?? []).map(idOf2)) : idOf2(data[f]) !== idOf2(originalDoc[f]);
+      if (changed) fail2(`A ${from} panel can't be edited. Build a new version instead.`);
     }
   }
   return data;
@@ -44,56 +269,66 @@ var supersedeOthers = (panels) => async ({ doc, previousDoc, req }) => {
   for (const other of others.docs) await req.payload.update({ collection: panels, id: other.id, data: { status: "superseded" }, req, overrideAccess: true });
   return doc;
 };
-var assignmentBeforeChange = (panels) => async ({ data, originalDoc, operation, req }) => {
+var assignmentBeforeChange = (panels, againstShown) => async ({ data, originalDoc, operation, req }) => {
   if (operation === "create") {
-    if ((data.reviewStatus ?? "pending") !== "pending") fail("A new result starts as pending review.");
-    const panel = await req.payload.findByID({ collection: panels, id: idOf(data.panel), depth: 0, req, overrideAccess: true });
-    if (panel.status !== "active") fail("Results can only be made against an active panel.");
+    if ((data.reviewStatus ?? "pending") !== "pending") fail2("A new result starts as pending review.");
+    const panel = await req.payload.findByID({ collection: panels, id: idOf2(data.panel), depth: 0, req, overrideAccess: true });
+    const shown = panel.status === "candidate" && panel.shownAsExploratory === true;
+    if (panel.status !== "active" && !(againstShown && shown)) fail2(againstShown ? "Results can only be made against an active panel, or a candidate shown as exploratory." : "Results can only be made against an active panel.");
+    data.panelStatus = panel.status;
+    data.panelShownAsExploratory = shown;
     const result = data.result;
     const problems = validateResult(result).filter((d) => d.severity === "error");
-    if (problems.length) fail(problems.map((p) => p.message).join("; "));
-    if (result.panel.version !== panel.version || result.panel.checksum !== panel.checksum) fail("This result was not made with this panel version.");
+    if (problems.length) fail2(problems.map((p) => p.message).join("; "));
+    if (result.panel.version !== panel.version || result.panel.checksum !== panel.checksum) fail2("This result was not made with this panel version.");
     const found = new Set(result.findings.map((f) => f.group));
     const missing = (panel.groups ?? []).filter((g) => !found.has(g.groupId)).map((g) => g.groupId);
-    if (missing.length) fail(`Every group must be reported. Missing: ${missing.join(", ")}.`);
-    if (hasCoordinates(result)) fail("Results never hold coordinates.");
+    if (missing.length) fail2(`Every group must be reported. Missing: ${missing.join(", ")}.`);
+    if (hasCoordinates(result)) fail2("Results never hold coordinates.");
     return data;
   }
   const from = String(originalDoc.reviewStatus);
   const to = String(data.reviewStatus ?? from);
   for (const f of ["result", "panel", "sequence", "subject", "summary", "importRun"]) {
-    if (f in data && (f === "result" || f === "summary" ? !same(data[f], originalDoc[f]) : idOf(data[f]) !== idOf(originalDoc[f]))) fail("A result can't be edited. Make a new one instead.");
+    if (f in data && (f === "result" || f === "summary" ? !same(data[f], originalDoc[f]) : idOf2(data[f]) !== idOf2(originalDoc[f]))) fail2("A result can't be edited. Make a new one instead.");
+  }
+  for (const f of ["panelStatus", "panelShownAsExploratory"]) {
+    if (f in data && !same(data[f], originalDoc[f])) fail2("The panel status a result was made against is set when it is made.");
   }
   if (to !== from) {
-    if (!REVIEW_TRANSITIONS[from]?.includes(to)) fail(`A result can't go from ${from} to ${to}.`);
+    if (!REVIEW_TRANSITIONS[from]?.includes(to)) fail2(`A result can't go from ${from} to ${to}.`);
     if (to === "approved") {
-      if (!req.user) fail("Approving a result needs a signed-in reviewer.");
+      if (!req.user) fail2("Approving a result needs a signed-in reviewer.");
       data.reviewer = String(req.user.id);
       data.releasedAt = (/* @__PURE__ */ new Date()).toISOString();
     }
   } else {
-    if ("reviewer" in data && data.reviewer !== originalDoc.reviewer) fail("The reviewer is set by approving.");
-    if ("releasedAt" in data && String(data.releasedAt) !== String(originalDoc.releasedAt)) fail("The release date is set by approving.");
+    if ("reviewer" in data && data.reviewer !== originalDoc.reviewer) fail2("The reviewer is set by approving.");
+    if ("releasedAt" in data && String(data.releasedAt) !== String(originalDoc.releasedAt)) fail2("The release date is set by approving.");
   }
   return data;
 };
-var relation = (name, relationTo, extra = {}) => relationTo ? [{ name, type: "relationship", relationTo, index: true, ...extra }] : [];
+var relation2 = (name, relationTo, extra = {}) => relationTo ? [{ name, type: "relationship", relationTo, index: true, ...extra }] : [];
+var checkedWhenMade = { validate: (value, options) => options.operation === "update" ? true : validateRelationship(value, options) };
 var onePhylogeny = (options = {}) => (config) => {
   const panels = options.slugs?.panels ?? "panels";
   const assignments = options.slugs?.assignments ?? "assignments";
-  const r = options.relations ?? {};
+  const records = options.records ? recordCollections(options.records, { panels, assignments, subject: options.relations?.subject, taxa: options.relations?.taxa, files: options.relations?.files, manage: options.manageAccess ?? (() => false), againstShown: options.resultsAgainst === "activeOrShown" }) : void 0;
+  const r = { ...options.relations, ...records && !options.relations?.sequence ? { sequence: records.config.sequences } : {} };
   const group = options.group ?? "Genetics";
   const manage = options.manageAccess ?? (() => false);
   const review = options.reviewAccess ?? manage;
   const readReleased = options.readReleasedAccess ?? (({ req }) => Boolean(req.user));
+  const againstShown = options.resultsAgainst === "activeOrShown";
   const panelCollection = {
     slug: panels,
     labels: { singular: "Reference panel", plural: "Reference panels" },
     admin: { group, useAsTitle: "key", defaultColumns: ["key", "version", "status", "marker"] },
     access: {
       read: async (args) => {
-        if (await manage(args)) return true;
-        return { status: { in: ["active", "superseded"] } };
+        const published = { status: { in: ["active", "superseded"] } };
+        const shown = { and: [{ status: { equals: "candidate" } }, { shownAsExploratory: { equals: true } }] };
+        return either(await manage(args), published, againstShown ? shown : false);
       },
       create: manage,
       update: manage,
@@ -103,14 +338,17 @@ var onePhylogeny = (options = {}) => (config) => {
       { name: "key", type: "text", required: true, index: true, admin: { description: "Stays the same across versions of one panel." } },
       { name: "version", type: "text", required: true },
       { name: "status", type: "select", required: true, defaultValue: "candidate", index: true, options: ["candidate", "active", "superseded", "withdrawn"] },
+      { name: "shownAsExploratory", type: "checkbox", defaultValue: false, index: true, admin: { description: "Show this candidate as exploratory, before review. Only candidates; cleared when it moves on." } },
       { name: "marker", type: "text", required: true },
       { name: "checksum", type: "text", required: true, index: true },
-      ...relation("taxa", r.taxa, { hasMany: true }),
-      ...relation("artifact", r.files, { admin: { description: "The full panel: JSON manifest and sequences." } }),
-      ...relation("importRun", r.importRuns),
+      ...relation2("taxa", r.taxa, { hasMany: true }),
+      ...relation2("artifact", r.files, { admin: { description: "The full panel: JSON manifest and sequences." } }),
+      ...relation2("importRun", r.importRuns),
       { name: "validatedScope", type: "text", hasMany: true, admin: { description: "The claims this panel is validated for. Pages show only these." } },
       { name: "notCovered", type: "text", hasMany: true },
-      { name: "groups", type: "array", fields: [{ name: "groupId", type: "text", required: true }, { name: "label", type: "text", required: true }, { name: "regionName", type: "text", admin: { description: "A general region, never coordinates." } }] }
+      { name: "groups", type: "array", fields: [{ name: "groupId", type: "text", required: true }, { name: "label", type: "text", required: true }, { name: "regionName", type: "text", admin: { description: "A general region, never coordinates." } }] },
+      { name: "activatedBy", type: "text", admin: { readOnly: true, description: "The signed-in user who activated this panel. Set by activating." } },
+      { name: "activatedAt", type: "date", admin: { readOnly: true } }
     ],
     hooks: { beforeChange: [panelBeforeChange], afterChange: [supersedeOthers(panels)] }
   };
@@ -119,29 +357,30 @@ var onePhylogeny = (options = {}) => (config) => {
     labels: { singular: "Lineage result", plural: "Lineage results" },
     admin: { group, useAsTitle: "summary", defaultColumns: ["summary", "panel", "reviewStatus", "releasedAt"] },
     access: {
+      // Managers and reviewers see what their own rules allow, including pending results; everyone else only released ones.
       read: async (args) => {
-        if (await manage(args) || await review(args)) return true;
-        const allowed = await readReleased(args);
-        if (!allowed) return false;
         const released2 = { reviewStatus: { equals: "approved" } };
-        return allowed === true ? released2 : { and: [released2, allowed] };
+        const allowed = await readReleased(args);
+        return either(await manage(args), await review(args), allowed === true ? released2 : allowed ? { and: [released2, allowed] } : false);
       },
       create: manage,
       update: review,
       delete: () => false
     },
     fields: [
-      ...relation("subject", r.subject),
-      ...relation("sequence", r.sequence),
-      { name: "panel", type: "relationship", relationTo: panels, required: true, index: true },
+      ...relation2("subject", r.subject, checkedWhenMade),
+      ...relation2("sequence", r.sequence, checkedWhenMade),
+      { name: "panel", type: "relationship", relationTo: panels, required: true, index: true, ...checkedWhenMade },
       { name: "summary", type: "text", required: true },
       { name: "result", type: "json", required: true, admin: { description: "The OnePhylogeny result, stored exactly as computed." } },
-      ...relation("importRun", r.importRuns),
+      ...relation2("importRun", r.importRuns, checkedWhenMade),
       { name: "reviewStatus", type: "select", required: true, defaultValue: "pending", index: true, options: ["pending", "approved", "rejected", "withdrawn"] },
       { name: "reviewer", type: "text", admin: { readOnly: true } },
-      { name: "releasedAt", type: "date", admin: { readOnly: true } }
+      { name: "releasedAt", type: "date", admin: { readOnly: true } },
+      { name: "panelStatus", type: "text", admin: { readOnly: true, description: "The panel's status when this result was made." } },
+      { name: "panelShownAsExploratory", type: "checkbox", admin: { readOnly: true } }
     ],
-    hooks: { beforeChange: [assignmentBeforeChange(panels)] }
+    hooks: { beforeChange: [assignmentBeforeChange(panels, againstShown)] }
   };
   const released = {
     path: "/onephylogeny/released",
@@ -153,8 +392,19 @@ var onePhylogeny = (options = {}) => (config) => {
       return Response.json({ docs: found.docs });
     }
   };
-  return { ...config, collections: [...config.collections ?? [], panelCollection, assignmentCollection], endpoints: [...config.endpoints ?? [], released] };
+  return {
+    ...config,
+    collections: [...config.collections ?? [], ...records?.collections ?? [], panelCollection, assignmentCollection],
+    endpoints: [...config.endpoints ?? [], released],
+    ...records ? { custom: { ...config.custom, [records.customKey]: records.config } } : {}
+  };
 };
 export {
-  onePhylogeny
+  anyOf,
+  assignWaiting,
+  either,
+  onePhylogeny,
+  readSingleSequence,
+  registerSequence,
+  summarize
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@captiveorigins/payload-plugin-onephylogeny",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.3",
   "description": "OnePhylogeny for Payload: immutable reference panels and released results on your own collections, with server-enforced review, safe endpoints and no coordinates.",
   "keywords": [
     "phylogenetics",
@@ -35,7 +35,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@captiveorigins/onephylogeny-core": "^0.1.0-alpha.0"
+    "@captiveorigins/onephylogeny-core": "^0.1.0-alpha.3"
   },
   "peerDependencies": {
     "payload": "^3.80.0"