paperlint 10.4.0 → 11.0.0

package/src/domain/portal-token.ts

@@ -0,0 +1,63 @@
+/**
+ * WHICH TOKEN A PORTAL COMMAND USES — the policy, in one place. Pure.
+ *
+ * The site's own variable, and nothing else: there is NO fallback to a site-less variable. With one,
+ * which token a command used is not visible, and a token from another site reads as "the portal
+ * refused". A site-less variable that is set while the site's own is not is refused by name. The
+ * names themselves are the portal's (`src/adapters/hotcrp/token.ts`).
+ */
+import { err, ok, type Result } from "./result.ts";
+
+/**
+ * The site's host as written in its URL, with its port when it is not the scheme's default
+ * (`review.example.org:8443`): two sites on one host differ by port. The URL itself when it does
+ * not parse.
+ */
+export const hostOf = (url: string): string =>
+  URL.canParse(url) ? new URL(url).host : url;
+
+/** The variables a lookup reads: the site's own, and the site-less one it refuses. */
+export interface TokenNames {
+  readonly variable: string;
+  readonly siteLess: string;
+}
+
+/** A token found, and the variable it came from. */
+export interface FoundToken {
+  readonly variable: string;
+  readonly token: string;
+}
+
+/** Why there is no token to use. */
+export type TokenProblem =
+  /** The site's variable is not set (or blank), and neither is the site-less one. */
+  | { readonly kind: "missing"; readonly variable: string }
+  /** The site's variable is not set, but the site-less one, no longer read, is. */
+  | {
+      readonly kind: "site-less";
+      readonly variable: string;
+      readonly siteLess: string;
+    };
+
+const value = (
+  read: (name: string) => string | undefined,
+  name: string,
+): string | null => {
+  const v = read(name)?.trim();
+  return v === undefined || v === "" ? null : v;
+};
+
+/**
+ * The token for a portal, read through `read` (the root reads the environment): the site's variable
+ * only. A set site-less variable never stands in for it — it is named as the problem instead.
+ */
+export function lookUpToken(
+  { variable, siteLess }: TokenNames,
+  read: (name: string) => string | undefined,
+): Result<FoundToken, TokenProblem> {
+  const token = value(read, variable);
+  if (token !== null) return ok({ variable, token });
+  return value(read, siteLess) === null
+    ? err({ kind: "missing", variable })
+    : err({ kind: "site-less", variable, siteLess });
+}

package/src/domain/study-measurements.test.ts

@@ -22,6 +22,7 @@ import {
   type StudyPlan,
   type StudyRegistry,
   type IndexInput,
+  folderKey,
 } from "./study-registry.ts";
 
 /** No plan and no history: the index with every mode column `—`. */
@@ -110,10 +111,10 @@ const input = (
   folders: r.studies.map((s) => s.folder),
   registry: { kind: "read", registry: r },
   readme: withIndex("# Reproduction index\n", r, NO_FACTS),
-  existingResults: new Set(),
+  results: new Map(),
   plans: new Map(
     r.studies.flatMap((s) =>
-      s.plan === undefined ? [] : [[`${s.folder}/${s.plan}`, read(PLAN)]],
+      s.plan === undefined ? [] : [[folderKey(s.folder, s.plan), read(PLAN)]],
     ),
   ),
   ...over,
@@ -385,7 +386,10 @@ describe("plans — the parser decides ready or draft", () => {
     });
     const plans = new Map([[`P1-S01-census/${PLAN_FILE}`, read(PLAN)]]);
     expect(
-      findings(r, { plans, existingResults: new Set(["P1-S01-census/r.tsv"]) }),
+      findings(r, {
+        plans,
+        results: new Map([["P1-S01-census/r.tsv", { kind: "file" as const }]]),
+      }),
     ).toEqual([]);
   });
 

package/src/domain/study-registry.test.ts

@@ -19,6 +19,7 @@ import {
   studyIndex,
   studyMessage,
   studyReadme,
+  studyById,
   studySlug,
   withIndex,
   type RegistryState,
@@ -61,7 +62,7 @@ const input = (
   folders: r.studies.map((s) => s.folder),
   registry: read(r),
   readme: withIndex("# Reproduction index\n", r, NO_FACTS),
-  existingResults: new Set(),
+  results: new Map(),
   plans: new Map(),
   ...over,
 });
@@ -88,7 +89,9 @@ describe("judgeStudies — silent", () => {
     expect(
       judgeStudies(
         input(r, {
-          existingResults: new Set(["P1-S02-ablation/out/results.tsv"]),
+          results: new Map([
+            ["P1-S02-ablation/out/results.tsv", { kind: "file" as const }],
+          ]),
         }),
       ),
     ).toEqual([]);
@@ -100,7 +103,7 @@ describe("judgeStudies — silent", () => {
         folders: [],
         registry: { kind: "absent" },
         readme: null,
-        existingResults: new Set(),
+        results: new Map(),
         plans: new Map(),
       }),
     ).toEqual([]);
@@ -129,7 +132,7 @@ describe("judgeStudies — the registry itself", () => {
         folders: ["a-2026-10-01", "b-2026-10-02"],
         registry: { kind: "absent" },
         readme: null,
-        existingResults: new Set(),
+        results: new Map(),
         plans: new Map(),
       }),
     ).toEqual([
@@ -143,7 +146,7 @@ describe("judgeStudies — the registry itself", () => {
         folders: ["a-2026-10-01"],
         registry: { kind: "unreadable", why: "prefix: required" },
         readme: null,
-        existingResults: new Set(),
+        results: new Map(),
         plans: new Map(),
       }),
     ).toEqual([{ problem: "unreadable", why: "prefix: required" }]);
@@ -259,7 +262,11 @@ describe("judgeStudies — status", () => {
     const r = reg(study({ status: "running", result_file: "r.tsv" }));
     expect(
       judgeStudies(
-        input(r, { existingResults: new Set(["P1-S01-baseline/r.tsv"]) }),
+        input(r, {
+          results: new Map([
+            ["P1-S01-baseline/r.tsv", { kind: "file" as const }],
+          ]),
+        }),
       ),
     ).toEqual([]);
   });
@@ -671,3 +678,24 @@ describe("studyReadme", () => {
     );
   });
 });
+
+describe("studyById — the one way to address a study by its id", () => {
+  const a = study({ id: "P1-S01", folder: "P1-S01-a" });
+  const b = study({ id: "P1-S01", folder: "P1-S01-b" });
+  const c = study({ id: "P1-S02", folder: "P1-S02-c" });
+
+  it("exactly one row: that row; no row: none; two or more: all of them, in registry order", () => {
+    // Guards: a caller can take a row only from `one`, never "the first" of an ambiguous id.
+    expect([
+      studyById([a, c], "P1-S01"),
+      studyById([a, c], "P1-S09"),
+      studyById([], "P1-S01"),
+      studyById([a, c, b], "P1-S01"),
+    ]).toEqual([
+      { kind: "one", row: a },
+      { kind: "none" },
+      { kind: "none" },
+      { kind: "ambiguous", rows: [a, b] },
+    ]);
+  });
+});

package/src/domain/study-registry.ts

@@ -248,8 +248,22 @@ export type ParsedPlan =
     }
   | { readonly kind: "unreadable"; readonly why: string };
 
+/**
+ * What a path inside a study's folder is, found without reading it or following a link: a regular
+ * file, nothing, or a path that passes through a symbolic link (`link`: the first one, relative to
+ * the folder).
+ */
+export type Located =
+  | { readonly kind: "file" }
+  | { readonly kind: "absent" }
+  | { readonly kind: "linked"; readonly link: string };
+
 /** What a study's folder holds of the plan its row names: absent, or what its text parsed to. */
-export type PlanState = { readonly kind: "absent" } | ParsedPlan;
+export type PlanState =
+  | { readonly kind: "absent" }
+  /** The plan's path passes through a symbolic link, `link` (relative to the folder); never read. */
+  | { readonly kind: "linked"; readonly link: string }
+  | ParsedPlan;
 
 /** The decision file `paperlint studies new` names for a study in `folder`, relative to the paper. */
 export const decisionPath = (folder: string): string =>
@@ -303,8 +317,8 @@ export interface StudyInput {
   readonly registry: RegistryState;
   /** `repro/README.md`'s text; null when there is none. */
   readonly readme: string | null;
-  /** Each `<folder>/<result_file>` of the registry that is a file. */
-  readonly existingResults: ReadonlySet<string>;
+  /** What each `<folder>/<result_file>` of the registry is, as `locate` found it; one not listed is absent. */
+  readonly results: ReadonlyMap<string, Located>;
   /** The plan each row names, by `<folder>/<plan>`; one not listed is absent. */
   readonly plans: ReadonlyMap<string, PlanState>;
 }
@@ -351,6 +365,13 @@ export type StudyFinding =
       readonly path: string;
       readonly why: "missing" | "outside";
     }
+  | {
+      readonly problem: "result-file";
+      readonly id: string;
+      readonly path: string;
+      readonly why: "linked";
+      readonly link: string;
+    }
   | {
       readonly problem: "no-successor";
       readonly id: string;
@@ -390,6 +411,13 @@ export type StudyFinding =
       readonly path: string;
       readonly why: "missing" | "outside";
     }
+  | {
+      readonly problem: "bad-plan";
+      readonly id: string;
+      readonly path: string;
+      readonly why: "linked";
+      readonly link: string;
+    }
   | {
       readonly problem: "bad-plan";
       readonly id: string;
@@ -479,24 +507,66 @@ export const isInside = (path: string): boolean => {
 export const isFolderName = (folder: string): boolean =>
   folder !== "." && folder !== ".." && /^[^/\\\0]+$/u.test(folder);
 
+/**
+ * The rows of a registry that carry an id: exactly one, none, or several. The one way to address a
+ * study by its id — a caller that wants "the study P1-S01" gets a row only when there is exactly one,
+ * so no command can act on the first of two rows by accident. A registry may still hold two rows of
+ * one id (`repro/study-registered` reports it); this says so instead of choosing.
+ */
+export type StudyLookup =
+  | { readonly kind: "one"; readonly row: Study }
+  | { readonly kind: "none" }
+  | { readonly kind: "ambiguous"; readonly rows: readonly Study[] };
+
+/** The rows of a registry that was read; none when there is no registry, or it does not parse. */
+export const studiesOf = (state: RegistryState): readonly Study[] =>
+  state.kind === "read" ? state.registry.studies : [];
+
+/** The rows of `studies` whose id is `id`, as a `StudyLookup`. */
+export const studyById = (
+  studies: readonly Study[],
+  id: string,
+): StudyLookup => {
+  const [first, ...rest] = studies.filter((s) => s.id === id);
+  if (first === undefined) return { kind: "none" };
+  return rest.length === 0
+    ? { kind: "one", row: first }
+    : { kind: "ambiguous", rows: [first, ...rest] };
+};
+
+/**
+ * The key a path inside a study's folder is held under: `<folder>/<path>`. A plan (`StudyInput.plans`,
+ * `IndexInput.plans`), the history of its study (`IndexInput.history`) and a result file
+ * (`StudyInput.results`) are all found by it.
+ */
+export const folderKey = (folder: string, path: string): string =>
+  `${folder}/${path}`;
+
 /**
  * The `<folder>/<plan>` of each row whose plan lies inside its folder: the files the judge needs read
  * (`StudyInput.plans`). A plan outside its folder is reported without being read.
  */
 export const planKeys = (r: StudyRegistry): readonly string[] =>
-  planRefs(r).map((p) => p.key);
+  planRefs(r).map((p) => folderKey(p.folder, p.plan));
 
-/** Each plan `planKeys` names, with the kind of the study whose row names it: what its parser needs. */
-export const planRefs = (
-  r: StudyRegistry,
-): readonly {
-  readonly key: string;
+/** A plan a row names: where it is read from, and the kind of the study — what its parser needs. */
+export interface PlanRef {
   readonly folder: string;
+  readonly plan: string;
   readonly kind: StudyKind;
-}[] =>
+}
+
+/** Each plan `planKeys` names. */
+export const planRefs = (r: StudyRegistry): readonly PlanRef[] =>
   r.studies.flatMap((s) =>
     s.plan !== undefined && isInside(s.plan) && isFolderName(s.folder)
-      ? [{ key: `${s.folder}/${s.plan}`, folder: s.folder, kind: s.kind }]
+      ? [
+          {
+            folder: s.folder,
+            plan: s.plan,
+            kind: s.kind,
+          },
+        ]
       : [],
   );
 
@@ -522,7 +592,7 @@ const badId: RowCheck = ({ r, s }) =>
 
 /** Reported once, on the first row that holds the id. */
 const duplicateId: RowCheck = (row) =>
-  row.r.studies.filter((o) => o.id === row.s.id).length > 1 &&
+  studyById(row.r.studies, row.s.id).kind === "ambiguous" &&
   isFirst(row, (o) => o.id)
     ? { problem: "duplicate-id", id: row.s.id }
     : null;
@@ -572,9 +642,23 @@ const resultFile: RowCheck = ({ s, input }) => {
   if (path === undefined) return null;
   if (!isInside(path))
     return { problem: "result-file", id: s.id, path, why: "outside" };
-  return input.existingResults.has(`${s.folder}/${path}`)
-    ? null
-    : { problem: "result-file", id: s.id, path, why: "missing" };
+  const found = input.results.get(folderKey(s.folder, path)) ?? {
+    kind: "absent",
+  };
+  switch (found.kind) {
+    case "file":
+      return null;
+    case "linked":
+      return {
+        problem: "result-file",
+        id: s.id,
+        path,
+        why: "linked",
+        link: found.link,
+      };
+    case "absent":
+      return { problem: "result-file", id: s.id, path, why: "missing" };
+  }
 };
 
 const noSuccessor: RowCheck = ({ r, s }) => {
@@ -593,13 +677,15 @@ const unknownMeasurement: RowCheck = ({ r, s }) =>
     ? null
     : { problem: "unknown-measurement", id: s.id, measurement: s.measurement };
 
-/** The state of the plan the row names (absent when outside its folder); null when it names none. */
-const planOf = ({ s, input }: Row): PlanState | null => {
-  if (s.plan === undefined) return null;
-  return isInside(s.plan)
-    ? (input.plans.get(`${s.folder}/${s.plan}`) ?? { kind: "absent" })
+/** The state of the plan `plan` of the row `s` (absent when outside its folder): the one place a plan is looked up. */
+const planStateOf = (input: StudyInput, s: Study, plan: string): PlanState =>
+  isInside(plan)
+    ? (input.plans.get(folderKey(s.folder, plan)) ?? { kind: "absent" })
     : { kind: "absent" };
-};
+
+/** The state of the plan the row names; null when it names none. */
+const planOf = ({ s, input }: Row): PlanState | null =>
+  s.plan === undefined ? null : planStateOf(input, s, s.plan);
 
 const hasRun = (s: Study): boolean => RAN_STATUSES.includes(s.status);
 
@@ -613,6 +699,8 @@ const planFinding = (
   switch (state.kind) {
     case "absent":
       return { ...at, why: "missing" };
+    case "linked":
+      return { ...at, why: "linked", link: state.link };
     case "unreadable":
       return { ...at, why: "unreadable", reasons: state.why };
     case "draft":
@@ -630,11 +718,7 @@ const badPlan: RowCheck = ({ s, input }) => {
   if (path === undefined) return null;
   if (!isInside(path))
     return { problem: "bad-plan", id: s.id, path, why: "outside" };
-  return planFinding(
-    s,
-    path,
-    input.plans.get(`${s.folder}/${path}`) ?? { kind: "absent" },
-  );
+  return planFinding(s, path, planStateOf(input, s, path));
 };
 
 /** A plan under its old name: read, and named for renaming. */
@@ -801,8 +885,8 @@ const cell = (s: string): string =>
 
 /**
  * What the index is generated from beyond the registry: the plans by `<folder>/<plan>` (as
- * `StudyInput.plans`), and the history of each decide-first study by id. A study with no history
- * listed shows `not read` — the lint, which never compares those columns, asks none.
+ * `StudyInput.plans`), and the history of each decide-first study by the same key. A study with no
+ * history listed shows `not read` — the lint, which never compares those columns, asks none.
  */
 export interface IndexInput {
   readonly plans: ReadonlyMap<string, PlanState>;
@@ -816,10 +900,11 @@ const declaredMode = (
 ): StudyMode | null => {
   const state =
     s.plan !== undefined && isInside(s.plan)
-      ? plans.get(`${s.folder}/${s.plan}`)
+      ? plans.get(folderKey(s.folder, s.plan))
       : undefined;
   return state === undefined ||
     state.kind === "absent" ||
+    state.kind === "linked" ||
     state.kind === "unreadable"
     ? null
     : (state.plan.mode ?? null);
@@ -828,7 +913,10 @@ const declaredMode = (
 /** What the index shows of `s` beyond its row. */
 const factsOf = (s: Study, at: IndexInput): IndexFacts => ({
   mode: declaredMode(s, at.plans),
-  history: at.history.get(s.id) ?? null,
+  history:
+    (s.plan === undefined
+      ? undefined
+      : at.history.get(folderKey(s.folder, s.plan))) ?? null,
 });
 
 /**
@@ -1039,7 +1127,9 @@ const HEADS: { readonly [P in Problem]: (f: FindingOf[P]) => string } = {
   "no-result": (f) =>
     `${REGISTRY}: ${tick(f.id)} is \`done\` without ${f.missing.map(tick).join(" and ")}. What to do: write the one-line result and the file it is read from (\`result\`, \`result_file\`), or set the status it really has.`,
   "result-file": (f) =>
-    `${REGISTRY}: the \`result_file\` of ${tick(f.id)}, ${tick(f.path)}, ${f.why === "missing" ? "is not a file in its folder" : "is outside its folder"}. What to do: name a file that exists, relative to the study's folder.`,
+    f.why === "linked"
+      ? `${REGISTRY}: the \`result_file\` of ${tick(f.id)}, ${tick(f.path)}, passes through the symbolic link ${tick(f.link)} in its folder; nothing is read through a link. What to do: name a regular file inside the study's folder, or replace the link with the file itself.`
+      : `${REGISTRY}: the \`result_file\` of ${tick(f.id)}, ${tick(f.path)}, ${f.why === "missing" ? "is not a file in its folder" : "is outside its folder"}. What to do: name a file that exists, relative to the study's folder.`,
   "no-successor": (f) =>
     `${REGISTRY}: ${tick(f.id)} is \`superseded\` ${f.superseded_by === null ? "without `superseded_by`" : `by ${tick(f.superseded_by)}, which is no study in the registry`}. What to do: name the id of the study that replaced it.`,
   "stale-index": (f) => `${STALE_HEAD[f.why]} ${RUN_INDEX}`,
@@ -1059,6 +1149,8 @@ const HEADS: { readonly [P in Problem]: (f: FindingOf[P]) => string } = {
     switch (f.why) {
       case "missing":
         return `${REGISTRY}: ${of} is not a file in its folder. What to do: write the plan there (its fields are on the rule's page), or correct the row's \`plan\`.`;
+      case "linked":
+        return `${REGISTRY}: ${of} passes through the symbolic link ${tick(f.link)} in its folder; nothing is read through a link. What to do: replace the link with the plan file itself.`;
       case "outside":
         return `${REGISTRY}: ${of} is outside its folder. What to do: keep the plan in the study's folder, as \`${PLAN_FILE}\`, and name it relative to the folder.`;
       case "unreadable":

package/src/domain/submission.test.ts

@@ -2,7 +2,9 @@
 import assert from "node:assert/strict";
 import { test } from "vitest";
 import {
+  parsePaperAuthors,
   parsePaperSubmission,
+  withSubmissionId,
   supportedPortal,
   wordCount,
 } from "./submission.ts";
@@ -43,3 +45,89 @@ test("wordCount: runs of non-space, any whitespace between", () => {
   assert.equal(wordCount(""), 0);
   assert.equal(wordCount("  one\ttwo\n\nthree  "), 3);
 });
+
+test("parsePaperAuthors: absent is null; each author trimmed, in order, affiliation optional", () => {
+  assert.deepEqual(parsePaperAuthors(undefined), { ok: true, value: null });
+  assert.deepEqual(
+    parsePaperAuthors([
+      { name: " Ada Lovelace ", email: "ada@example.org", affiliation: "AE" },
+      { name: "Bob", email: " bob@example.org " },
+    ]),
+    {
+      ok: true,
+      value: [
+        { name: "Ada Lovelace", email: "ada@example.org", affiliation: "AE" },
+        { name: "Bob", email: "bob@example.org", affiliation: null },
+      ],
+    },
+  );
+});
+
+test("🔴 parsePaperAuthors: every malformed list refused with what to fix — never a partial list", () => {
+  const shape = /^"authors" must be a non-empty list of \{ "name"/;
+  const ada = { name: "Ada", email: "ada@example.org" };
+  const cases: readonly (readonly [unknown, RegExp])[] = [
+    [[], shape],
+    ["Ada", shape],
+    [["Ada"], shape],
+    [
+      [ada, { ...ada, orcid: "x" }],
+      /^"authors"\[1\] has an unknown key "orcid" — known: name, email, affiliation$/,
+    ],
+    [
+      [{ ...ada, name: " " }],
+      /^"authors"\[0\]: "name" must be a non-empty string$/,
+    ],
+    [
+      [{ ...ada, email: "ada" }],
+      /^"authors"\[0\]: "email" must be an email address, got "ada"$/,
+    ],
+    [
+      [{ name: "Ada" }, ada],
+      /^"authors"\[0\]: "email" must be an email address, got undefined$/,
+    ],
+    [
+      [{ ...ada, affiliation: "" }],
+      /^"authors"\[0\]: "affiliation", when given, must be a non-empty string$/,
+    ],
+    [
+      [ada, { name: "Ada 2", email: "ADA@example.org" }],
+      /^"authors": the email ada@example\.org is given twice$/,
+    ],
+  ];
+  for (const [v, why] of cases) {
+    const r = parsePaperAuthors(v);
+    assert.ok(!r.ok, JSON.stringify(v));
+    assert.match(r.error, why);
+  }
+});
+
+test("withSubmissionId: the flat form at the top level; the cycles form in the last cycle, the others untouched", () => {
+  assert.deepEqual(withSubmissionId({ extends: "x" }, 4), {
+    ok: true,
+    value: { extends: "x", submission: { id: 4 } },
+  });
+  assert.deepEqual(
+    withSubmissionId({ cycles: [{ id: "a" }, { id: "b" }] }, 4),
+    {
+      ok: true,
+      value: { cycles: [{ id: "a" }, { id: "b", submission: { id: 4 } }] },
+    },
+  );
+});
+
+test("🔴 withSubmissionId: nowhere to record it — refused, never guessed", () => {
+  assert.deepEqual(withSubmissionId([], 4), {
+    ok: false,
+    error: "must be a JSON object",
+  });
+  for (const cycles of [[], "x"])
+    assert.deepEqual(withSubmissionId({ cycles }, 4), {
+      ok: false,
+      error: `"cycles" has no attempt to record the submission in`,
+    });
+  assert.deepEqual(withSubmissionId({ cycles: [{ id: "a" }, 3] }, 4), {
+    ok: false,
+    error: `the last entry of "cycles" is not an object`,
+  });
+});

package/src/domain/submission.ts

@@ -139,3 +139,102 @@ export type PortalFailure =
 /** Words in a text, as a reader counts them: runs of non-space. Pure. */
 export const wordCount = (s: string): number =>
   s.split(/\s+/).filter((w) => w !== "").length;
+
+// ── a new submission ────────────────────────────────────────────────────────────────────
+
+/** One author as the portal records it. Never guessed: the paper's `authors` key declares it. */
+export interface Author {
+  readonly name: string;
+  readonly email: string;
+  /** Null when the paper does not declare one. */
+  readonly affiliation: string | null;
+}
+
+const AUTHOR_KEYS = ["name", "email", "affiliation"] as const;
+const AUTHORS_SHAPE = `"authors" must be a non-empty list of { "name": "<as the portal should show it>", "email": "<the address the portal knows the author by>", "affiliation"?: "<…>" }, in the paper's order`;
+
+const nonEmpty = (v: unknown): v is string =>
+  typeof v === "string" && v.trim() !== "";
+
+/** One entry of `authors` → the author, or what is wrong with it. */
+function authorOf(v: unknown, i: number): Result<Author, string> {
+  const at = `"authors"[${String(i)}]`;
+  if (!isRecord(v)) return err(AUTHORS_SHAPE);
+  const unknown = Object.keys(v).find((k) => !AUTHOR_KEYS.some((a) => a === k));
+  if (unknown !== undefined)
+    return err(
+      `${at} has an unknown key "${unknown}" — known: ${AUTHOR_KEYS.join(", ")}`,
+    );
+  const { name, email, affiliation } = v;
+  if (!nonEmpty(name)) return err(`${at}: "name" must be a non-empty string`);
+  if (!nonEmpty(email) || !/^[^\s@]+@[^\s@]+$/.test(email.trim()))
+    return err(
+      `${at}: "email" must be an email address, got ${JSON.stringify(email)}`,
+    );
+  if (affiliation !== undefined && !nonEmpty(affiliation))
+    return err(`${at}: "affiliation", when given, must be a non-empty string`);
+  return ok({
+    name: name.trim(),
+    email: email.trim(),
+    affiliation: affiliation === undefined ? null : affiliation.trim(),
+  });
+}
+
+/** A paper's `authors` key → the list, null when absent, or one line saying what is wrong. Pure. */
+export function parsePaperAuthors(
+  v: unknown,
+): Result<readonly Author[] | null, string> {
+  if (v === undefined) return ok(null);
+  if (!Array.isArray(v) || v.length === 0) return err(AUTHORS_SHAPE);
+  const list: readonly unknown[] = v;
+  const parsed = list.reduce<Result<readonly Author[], string>>((acc, x, i) => {
+    if (!acc.ok) return acc;
+    const a = authorOf(x, i);
+    return a.ok ? ok([...acc.value, a.value]) : a;
+  }, ok([]));
+  if (!parsed.ok) return parsed;
+  const authors = parsed.value;
+  const emails = authors.map((a) => a.email.toLowerCase());
+  const twice = emails.find((e, i) => emails.indexOf(e) !== i);
+  return twice === undefined
+    ? ok(authors)
+    : err(`"authors": the email ${twice} is given twice`);
+}
+
+/** What creating a submission sends. */
+export interface NewSubmission {
+  readonly title: string;
+  readonly abstract: string;
+  readonly authors: readonly Author[];
+  readonly pdf: { readonly name: string; readonly bytes: Uint8Array };
+}
+
+/** What the portal answered to a creation: an update's answer, and the id it chose when it saved. */
+export interface CreateOutcome extends UpdateOutcome {
+  /** The new submission's id; null on a dry run, or when nothing was created. */
+  readonly id: number | null;
+}
+
+/**
+ * The parsed `paperlint.json` with the new submission's id recorded where the paper's submission is
+ * read from: the last cycle (the open attempt) in the cycles form, the top level in the flat form.
+ * Pure; the caller writes the result and reads it back.
+ */
+export function withSubmissionId(
+  json: unknown,
+  id: number,
+): Result<Readonly<Record<string, unknown>>, string> {
+  if (!isRecord(json)) return err("must be a JSON object");
+  const cycles = json["cycles"];
+  if (cycles === undefined) return ok({ ...json, submission: { id } });
+  if (!Array.isArray(cycles) || cycles.length === 0)
+    return err(`"cycles" has no attempt to record the submission in`);
+  const list: readonly unknown[] = cycles;
+  const last = list.at(-1);
+  return isRecord(last)
+    ? ok({
+        ...json,
+        cycles: [...list.slice(0, -1), { ...last, submission: { id } }],
+      })
+    : err(`the last entry of "cycles" is not an object`);
+}

package/src/new-paper.test.ts

@@ -85,6 +85,7 @@ describe("paperlint new — paperlint.json", () => {
         identity: null,
         talk: null,
         submission: null,
+        authors: null,
         cycles: null,
       },
     });