@venn-lang/core 0.1.0

package/src/typecheck/member-docs.ts

@@ -0,0 +1,211 @@
+import type { Type } from "./type.types.js";
+import { prune } from "./unify.js";
+
+/** What a built-in member does, and how it reads. */
+export interface MemberDoc {
+  doc: string;
+  example?: string;
+}
+
+const LIST: Record<string, MemberDoc> = {
+  len: { doc: "How many items it holds.", example: "[1, 2, 3].len  # 3" },
+  first: { doc: "The first item, or null when empty." },
+  last: { doc: "The last item, or null when empty." },
+  isEmpty: { doc: "True when there is nothing in it." },
+  map: {
+    doc: "A new list, each item passed through the function.",
+    example: "[1, 2].map(fn (x) => x * 2)  # [2, 4]",
+  },
+  filter: { doc: "Only the items the function keeps.", example: "xs.filter(fn (x) => x > 2)" },
+  reduce: {
+    doc: "Fold the list into one value, from a starting one.",
+    example: "xs.reduce(fn (total, x) => total + x, 0)",
+  },
+  forEach: { doc: "Run the function once per item, for its effect." },
+  find: { doc: "The first item the function accepts, or null." },
+  some: { doc: "True when the function accepts any item." },
+  every: { doc: "True when the function accepts all of them." },
+  contains: { doc: "True when the item is in the list." },
+  indexOf: { doc: "Where the item sits, or -1." },
+  join: { doc: "The items as one string, separated.", example: "['a', 'b'].join('-')  # \"a-b\"" },
+  reverse: { doc: "The same items, back to front." },
+  flatten: { doc: "One level of nesting removed." },
+  sort: { doc: "Sorted by a comparator. For a key, `sortBy` reads better." },
+  slice: { doc: "The items between two positions." },
+  concat: { doc: "This list followed by another." },
+  push: { doc: "A new list with the item appended — the original is untouched." },
+  sum: { doc: "The numbers added up." },
+  average: { doc: "The mean of the numbers, or 0 when empty." },
+  min: { doc: "The smallest number." },
+  max: { doc: "The largest number." },
+  toMap: { doc: "Entry pairs turned into a map.", example: "[['a', 1]].toMap  # { a: 1 }" },
+  take: { doc: "The first n items." },
+  drop: { doc: "Everything after the first n." },
+  takeLast: { doc: "The last n items." },
+  dropLast: { doc: "Everything but the last n." },
+  takeWhile: { doc: "Items from the start, while the function accepts them." },
+  dropWhile: { doc: "Skip the accepted run, keep the rest." },
+  distinct: { doc: "Duplicates removed, first occurrence kept." },
+  distinctBy: { doc: "Duplicates removed by a derived key." },
+  sortBy: { doc: "Sorted by a derived key.", example: "people.sortBy(fn (p) => p.age)" },
+  minBy: { doc: "The item with the smallest score." },
+  maxBy: { doc: "The item with the largest score.", example: "people.maxBy(fn (p) => p.age)" },
+  sumBy: { doc: "The scores added up." },
+  flatMap: { doc: "Map, then flatten one level." },
+  groupBy: {
+    doc: "A map from key to the items sharing it.",
+    example: "people.groupBy(fn (p) => p.team)",
+  },
+  countBy: { doc: "A map from key to how many items share it." },
+  keyBy: { doc: "A map from key to item — an index, last one wins." },
+  partition: { doc: "Two lists: what the function kept, and what it rejected." },
+  chunk: { doc: "Split into runs of n.", example: "[1,2,3,4,5].chunk(2)  # [[1,2],[3,4],[5]]" },
+  windows: { doc: "Every consecutive run of n.", example: "[1,2,3].windows(2)  # [[1,2],[2,3]]" },
+  pairwise: { doc: "Every consecutive pair." },
+  zip: { doc: "Paired with another list, item by item." },
+  unzip: { doc: "Pairs pulled apart into separate lists." },
+};
+
+const STRING: Record<string, MemberDoc> = {
+  len: { doc: "How many characters it holds." },
+  upper: { doc: "In upper case." },
+  lower: { doc: "In lower case." },
+  trim: { doc: "Without leading or trailing blanks." },
+  trimStart: { doc: "Without leading blanks." },
+  trimEnd: { doc: "Without trailing blanks." },
+  reverse: { doc: "The characters back to front." },
+  toNumber: { doc: "Read as a number." },
+  isEmpty: { doc: "True when it has no characters." },
+  isBlank: { doc: "True when it is empty or only blanks." },
+  split: { doc: "Cut into a list on a separator.", example: "'a,b'.split(',')  # ['a', 'b']" },
+  replace: { doc: "Every occurrence swapped for another." },
+  contains: { doc: "True when the text appears inside." },
+  startsWith: { doc: "True when it begins with the text." },
+  endsWith: { doc: "True when it ends with the text." },
+  slice: { doc: "The characters between two positions." },
+  repeat: { doc: "Itself, n times over." },
+  padStart: { doc: "Padded on the left to a width." },
+  padEnd: { doc: "Padded on the right to a width." },
+  indexOf: { doc: "Where the text starts, or -1." },
+  words: { doc: "Split on whitespace.", example: "'a b  c'.words  # ['a', 'b', 'c']" },
+  lines: { doc: "Split on newlines." },
+  chars: { doc: "Each character as its own string." },
+  capitalize: { doc: "First letter upper-cased." },
+  title: { doc: "Every word capitalised." },
+  slugify: {
+    doc: "URL-safe: accents stripped, spaces to dashes.",
+    example: "'João Silva'.slugify  # \"joao-silva\"",
+  },
+  count: { doc: "How many times the text appears." },
+  matches: {
+    doc: "Every match of a pattern, as a list.",
+    example: "'a1b22'.matches('[0-9]+')  # ['1', '22']",
+  },
+  test: { doc: "True when the pattern matches anywhere." },
+  before: { doc: "What comes before the marker." },
+  after: { doc: "What comes after the marker." },
+  ensureStart: { doc: "The prefix added, unless it is already there." },
+  ensureEnd: { doc: "The suffix added, unless it is already there." },
+};
+
+const MAP: Record<string, MemberDoc> = {
+  len: { doc: "How many entries it holds." },
+  keys: { doc: "Its keys, as a list." },
+  values: { doc: "Its values, as a list." },
+  entries: { doc: "Its `[key, value]` pairs." },
+  has: { doc: "True when the key is present." },
+  get: { doc: "The value under a key, or null." },
+  merge: { doc: "This map with another laid over it." },
+  mergeDeep: {
+    doc: "Merged recursively, keeping untouched branches.",
+    example: "cfg.mergeDeep({ server: { port: 90 } })",
+  },
+  mapValues: { doc: "Same keys, each value passed through the function." },
+  mapKeys: { doc: "Same values, each key passed through the function." },
+  filterValues: { doc: "Only the entries whose value the function keeps." },
+  pick: { doc: "Only the named keys.", example: "cfg.pick('host', 'port')" },
+  omit: { doc: "Everything but the named keys." },
+  invert: { doc: "Keys and values swapped." },
+  isEmpty: { doc: "True when it has no entries." },
+  getPath: {
+    doc: "Reach into nested data by a dotted path.",
+    example: "cfg.getPath('server.port')",
+  },
+  hasPath: { doc: "True when the dotted path leads somewhere." },
+};
+
+const NUMBER: Record<string, MemberDoc> = {
+  abs: { doc: "Its distance from zero." },
+  floor: { doc: "Rounded down to a whole number." },
+  ceil: { doc: "Rounded up to a whole number." },
+  sign: { doc: "-1, 0 or 1." },
+  sqrt: { doc: "Its square root." },
+  isEven: { doc: "True when it divides by two." },
+  isOdd: { doc: "True when it does not." },
+  round: { doc: "Rounded to n decimal places.", example: "(3.14159).round(2)  # 3.14" },
+  toFixed: { doc: "As text with exactly n decimals." },
+  clamp: { doc: "Held between a low and a high bound.", example: "(99).clamp(0, 10)  # 10" },
+  pow: { doc: "Raised to a power." },
+  times: { doc: "A list counting from 0 up to it.", example: "(3).times  # [0, 1, 2]" },
+  toString: { doc: "As text." },
+  toMs: { doc: "Read as a duration in milliseconds.", example: "1500.toMs  # 1.5s" },
+  toSeconds: { doc: "Read as a duration in seconds." },
+  toMinutes: { doc: "Read as a duration in minutes." },
+  toHours: { doc: "Read as a duration in hours." },
+  toBytes: { doc: "Read as a size in bytes." },
+  toKb: { doc: "Read as a size in kilobytes.", example: "2048.toKb  # 2mb" },
+  toMb: { doc: "Read as a size in megabytes." },
+  toGb: { doc: "Read as a size in gigabytes." },
+  toRatio: { doc: "Read as a percent, from a fraction of one.", example: "0.5.toRatio  # 50%" },
+  toPercent: { doc: "Read as a percent, from a number out of a hundred." },
+};
+
+const DURATION: Record<string, MemberDoc> = {
+  ms: { doc: "As a plain number of milliseconds.", example: "1.5s.ms  # 1500" },
+  seconds: { doc: "As a plain number of seconds." },
+  minutes: { doc: "As a plain number of minutes.", example: "90s.minutes  # 1.5" },
+  hours: { doc: "As a plain number of hours." },
+};
+
+const SIZE: Record<string, MemberDoc> = {
+  bytes: { doc: "As a plain number of bytes." },
+  kb: { doc: "As a plain number of kilobytes.", example: "2mb.kb  # 2048" },
+  mb: { doc: "As a plain number of megabytes." },
+  gb: { doc: "As a plain number of gigabytes." },
+};
+
+const PERCENT: Record<string, MemberDoc> = {
+  ratio: { doc: "As a fraction of one.", example: "50%.ratio  # 0.5" },
+  percent: { doc: "As a number out of a hundred.", example: "0.5.round(2)" },
+  of: { doc: "That share of a number.", example: "12%.of(50)  # 6" },
+};
+
+const TASK: Record<string, MemberDoc> = {
+  wait: { doc: "The value, once the work has finished.", example: "let page = job.wait" },
+  done: { doc: "True once it has finished, either way." },
+  failed: { doc: "True when it finished by failing." },
+  settle: { doc: "Wait without the failure spreading — the value, or nothing." },
+};
+
+/** Documentation for every built-in member, by the kind of value it hangs off. */
+export const MEMBER_DOCS: Readonly<Record<string, Record<string, MemberDoc>>> = {
+  list: LIST,
+  string: STRING,
+  map: MAP,
+  number: NUMBER,
+  duration: DURATION,
+  size: SIZE,
+  percent: PERCENT,
+  task: TASK,
+};
+
+const KINDS = new Set(["string", "number", "duration", "size", "percent"]);
+
+/** Which table of members a type answers to, if any. */
+export function memberKind(type: Type): string | undefined {
+  const t = prune(type);
+  if (t.kind === "list") return "list";
+  if (t.kind === "record") return "map";
+  if (t.kind !== "prim") return undefined;
+  return KINDS.has(t.name) ? t.name : undefined;
+}

package/src/typecheck/named-types.ts

@@ -0,0 +1,57 @@
+import type { Document, TypeDecl } from "../generated/ast.js";
+import { isTypeDecl } from "../generated/ast.js";
+import type { TypeCatalog } from "./catalog.types.js";
+import type { TypeContext } from "./context.js";
+import { KIND_TYPES } from "./kind-types.js";
+import { NULL, record, type Type, union } from "./type.types.js";
+import { typeRefToType } from "./type-ref.js";
+
+/** The named types a document declares, such as `type User { … }`, by name. */
+export interface NamedTypes {
+  get(name: string): Type | undefined;
+}
+
+/**
+ * Collect every `type` declaration into resolvable record types. A shared table
+ * lets one type reference another declared later; an unknown name stays
+ * `dynamic`, so annotations never add friction.
+ *
+ * The decorator kinds are in the table before the file is read: `Fn`, `Flow`
+ * and the rest are types like any other, so `deco memoize(target: Fn)` needs no
+ * special path to hover, complete and check. A file that declares a type of its
+ * own by one of those names wins, because they are a stdlib, not reserved words.
+ */
+export function collectNamedTypes(
+  doc: Document,
+  ctx: TypeContext,
+  catalog?: TypeCatalog,
+): NamedTypes {
+  const table = new Map<string, Type>(KIND_TYPES);
+  const named: NamedTypes = { get: (name) => table.get(name) };
+  for (const decl of doc.decls.filter(isTypeDecl)) {
+    table.set(decl.name, declaredType({ decl, ctx, named, catalog }));
+  }
+  return named;
+}
+
+/** A `type` is either a shape of its own or another name for one. */
+function declaredType(args: Scope & { decl: TypeDecl }): Type {
+  if (args.decl.alias) return typeRefToType({ ...args, ref: args.decl.alias });
+  return recordOf(args);
+}
+
+interface Scope {
+  ctx: TypeContext;
+  named: NamedTypes;
+  catalog?: TypeCatalog;
+}
+
+/** A record of the declared fields. An optional one reads as `T | null`. */
+function recordOf(args: Scope & { decl: TypeDecl }): Type {
+  const fields = new Map<string, Type>();
+  for (const field of args.decl.body?.fields ?? []) {
+    const type = typeRefToType({ ...args, ref: field.fieldType });
+    fields.set(field.name, field.optional ? union([type, NULL]) : type);
+  }
+  return record(fields);
+}

package/src/typecheck/prelude-types.ts

@@ -0,0 +1,152 @@
+import { DYNAMIC, list, NUMBER, STRING, type Type, variadic } from "./type.types.js";
+
+/** One argument of a prelude verb, named so the editor can point at it. */
+export interface PreludeArg {
+  name: string;
+  type: string;
+  doc?: string;
+  optional?: boolean;
+}
+
+/** What the editor needs to describe a prelude name: its type, and what it is for. */
+export interface PreludeSpec {
+  /** How it reads when written out. Shown as the hover's signature. */
+  signature: string;
+  doc: string;
+  example?: string;
+  type: Type;
+  /**
+   * The arguments, one by one. `signature` above is a whole line meant to be
+   * read; these are meant to be pointed at, one at a time, as each is typed.
+   */
+  args?: readonly PreludeArg[];
+}
+
+/**
+ * The prelude, described once: the checker reads the types, the editor reads
+ * the prose. Two tables would drift; this one cannot.
+ */
+export const PRELUDE_SPECS: Readonly<Record<string, PreludeSpec>> = {
+  spawn: {
+    signature: "spawn(fn () -> T) -> task",
+    doc: "Start work without waiting for it. Everything else waits by itself, so this is how to carry on — ask for the value later with `.wait`.",
+    example: "let job = spawn(fn () => http.get(url))\nlet page = job.wait",
+    type: variadic([DYNAMIC], DYNAMIC),
+    args: [
+      {
+        name: "work",
+        type: "fn () -> T",
+        doc: "What to start. It runs on its own; ask for the answer later.",
+      },
+    ],
+  },
+  print: {
+    signature: "print(…) -> null",
+    doc: "Write to standard output, followed by a newline. A map or list shows as JSON.",
+    args: [
+      {
+        name: "values",
+        type: "…",
+        doc: "Anything, as many as you like. Spaced apart on one line.",
+      },
+    ],
+    example: 'print "hello" 42\nprint pretty(user)',
+    type: variadic([DYNAMIC], { kind: "prim", name: "null" }),
+  },
+  log: {
+    signature: "log(…) -> null",
+    doc: "Record a message in the event stream — what a reporter and a test see, not stdout.",
+    example: 'log "retrying" attempt',
+    args: [
+      {
+        name: "values",
+        type: "…",
+        doc: "Anything, as many as you like. Goes to the event stream, not stdout.",
+      },
+    ],
+    type: variadic([DYNAMIC], { kind: "prim", name: "null" }),
+  },
+  range: {
+    signature: "range(from?, to, step?) -> list<number>",
+    doc: "A list of numbers, counting up or down. The end is exclusive.",
+    example:
+      "range(3)        # [0, 1, 2]\nrange(1, 4)     # [1, 2, 3]\nrange(0, 10, 2) # [0, 2, 4, 6, 8]",
+    args: [
+      {
+        name: "from",
+        type: "number",
+        doc: "Where to start. Omit it and counting starts at 0.",
+        optional: true,
+      },
+      { name: "to", type: "number", doc: "Where to stop, exclusive." },
+      { name: "step", type: "number", doc: "How far apart. Negative counts down.", optional: true },
+    ],
+    type: variadic([NUMBER], list(NUMBER)),
+  },
+  str: {
+    signature: "str(…) -> string",
+    doc: "Every argument as text, spaced. Works on `null`, which has no methods of its own.",
+    example: 'str("total:", 42, true)  # "total: 42 true"',
+    args: [{ name: "values", type: "…", doc: "Anything, as many as you like." }],
+    type: variadic([DYNAMIC], STRING),
+  },
+  typeOf: {
+    signature: "typeOf(value) -> string",
+    doc: "The name of a value's type: `list`, `map`, `string`, `number`, `bool`, `fn`, `null`.",
+    example: 'typeOf([1, 2])  # "list"',
+    args: [{ name: "value", type: "dynamic", doc: "Whatever you want the name of." }],
+    type: variadic([DYNAMIC], STRING),
+  },
+  pretty: {
+    signature: "pretty(value) -> string",
+    doc: "Indented JSON — `fmt.json(x, 2)` without the import.",
+    args: [{ name: "value", type: "dynamic", doc: "What to render." }],
+    example: "print pretty(user)",
+    type: variadic([DYNAMIC], STRING),
+  },
+  wait: {
+    signature: "wait(duration) -> null",
+    doc: "Pause for a duration.",
+    args: [{ name: "duration", type: "duration", doc: "How long: `500ms`, `2s`, `1m`." }],
+    example: "wait 500ms",
+    type: variadic([DYNAMIC], { kind: "prim", name: "null" }),
+  },
+  skip: {
+    signature: "skip(reason) -> null",
+    doc: "Skip the rest of the current flow.",
+    args: [
+      {
+        name: "reason",
+        type: "string",
+        doc: "Why — it is reported alongside the skip.",
+        optional: true,
+      },
+    ],
+    type: variadic([DYNAMIC], { kind: "prim", name: "null" }),
+  },
+  fail: {
+    signature: "fail(message) -> never",
+    doc: "Fail the current step with a message.",
+    args: [{ name: "message", type: "string", doc: "What went wrong, in the reader's terms." }],
+    type: variadic([DYNAMIC], { kind: "prim", name: "null" }),
+  },
+  exit: {
+    signature: "exit(code) -> never",
+    doc: "End the program with an exit code.",
+    args: [
+      {
+        name: "code",
+        type: "number",
+        doc: "0 means success. Anything else does not.",
+        optional: true,
+      },
+    ],
+    example: "exit 1",
+    type: variadic([NUMBER], { kind: "prim", name: "null" }),
+  },
+};
+
+/** Whether a bare name is part of the prelude: no `use` needed, always in scope. */
+export function isPrelude(name: string): boolean {
+  return name in PRELUDE_SPECS;
+}

package/src/typecheck/reshaped-fns.ts

@@ -0,0 +1,58 @@
+import { walkAst } from "../ast/index.js";
+import { decoTarget } from "../expand/index.js";
+import type { DecoDecl, Document, FnDecl } from "../generated/ast.js";
+import * as ast from "../generated/ast.js";
+
+/**
+ * The verbs that change what a call to a function looks like.
+ *
+ * `rename` is absent: it moves the name rather than the shape, and the checker
+ * has no better answer for the new name than it had for the old one.
+ */
+const RESHAPING: readonly string[] = ["addParam", "removeParam", "wrap"];
+
+/**
+ * The functions a `deco` gives a different shape to.
+ *
+ * The checker reads the program as written, before expansion has run, so a
+ * function that `@inject("who")` gave a parameter to still looks like the one
+ * the author typed and every call passing that parameter looks wrong. It is not:
+ * the program runs. Inference cannot know the new shape without expanding, so
+ * for these it says `dynamic` and stops pinning a signature that is about to
+ * change, rather than rejecting a program that works.
+ *
+ * Narrow on purpose: only a function actually carrying a decorator that
+ * actually reshapes. Everything else keeps every check it had.
+ */
+export function reshapedFns(args: {
+  document: Document;
+  decos: ReadonlyMap<string, DecoDecl>;
+}): ReadonlySet<FnDecl> {
+  const found = new Set<FnDecl>();
+  const names = reshapingNames(args.decos);
+  if (names.size === 0) return found;
+  for (const decl of args.document.decls) {
+    if (ast.isFnDecl(decl) && decl.annotations.some((one) => names.has(one.name))) found.add(decl);
+  }
+  return found;
+}
+
+/** The decorators in reach whose body changes the shape of what it is applied to. */
+function reshapingNames(decos: ReadonlyMap<string, DecoDecl>): Set<string> {
+  const names = new Set<string>();
+  for (const [name, decl] of decos) {
+    if (reshapes(decl)) names.add(name);
+  }
+  return names;
+}
+
+/**
+ * Whether the body reaches for one of those verbs on its target, anywhere.
+ * Inside an `if` counts, because the checker cannot know which way it goes.
+ */
+function reshapes(decl: DecoDecl): boolean {
+  const target = decoTarget(decl)?.name;
+  if (!target) return false;
+  const verbs = RESHAPING.map((verb) => `${target}.${verb}`);
+  return walkAst(decl.body).some((node) => ast.isActionCall(node) && verbs.includes(node.target));
+}

package/src/typecheck/scheme.ts

@@ -0,0 +1,75 @@
+import type { TypeContext } from "./context.js";
+import type { Type } from "./type.types.js";
+import { prune } from "./unify.js";
+
+/**
+ * A type scheme: a type universally quantified over some variables. This is what
+ * makes generics real. `fn id(x) => x` becomes `∀t. t -> t`, and every call
+ * instantiates `t` afresh, so `id(1)` and `id("a")` both check.
+ */
+export interface Scheme {
+  readonly quantified: readonly number[];
+  readonly type: Type;
+}
+
+/** A non-generic scheme: a plain type with nothing quantified. */
+export function mono(type: Type): Scheme {
+  return { quantified: [], type };
+}
+
+/** Collect the ids of the unsolved variables reachable from a type. */
+export function freeVars(type: Type, into: Set<number> = new Set()): Set<number> {
+  const t = prune(type);
+  if (t.kind === "var") into.add(t.id);
+  else if (t.kind === "list") freeVars(t.element, into);
+  else if (t.kind === "fn") {
+    for (const param of t.params) freeVars(param, into);
+    freeVars(t.result, into);
+  } else if (t.kind === "record") {
+    for (const field of t.fields.values()) freeVars(field, into);
+  }
+  return into;
+}
+
+/**
+ * Generalise a type over the variables free in it but not in the environment.
+ * Those become the scheme's type parameters.
+ */
+export function generalize(type: Type, envFree: ReadonlySet<number>): Scheme {
+  const quantified = [...freeVars(type)].filter((id) => !envFree.has(id));
+  return { quantified, type };
+}
+
+/** Instantiate a scheme with fresh variables for each quantified parameter. */
+export function instantiate(scheme: Scheme, ctx: TypeContext): Type {
+  if (scheme.quantified.length === 0) return scheme.type;
+  const fresh = new Map(scheme.quantified.map((id) => [id, ctx.fresh() as Type]));
+  return substitute(scheme.type, fresh);
+}
+
+function substitute(type: Type, mapping: ReadonlyMap<number, Type>): Type {
+  const t = prune(type);
+  switch (t.kind) {
+    case "var":
+      return mapping.get(t.id) ?? t;
+    case "list":
+      return { kind: "list", element: substitute(t.element, mapping) };
+    case "fn":
+      return {
+        kind: "fn",
+        params: t.params.map((param) => substitute(param, mapping)),
+        result: substitute(t.result, mapping),
+      };
+    case "record":
+      return { kind: "record", open: t.open, fields: substituteFields(t.fields, mapping) };
+    default:
+      return t;
+  }
+}
+
+function substituteFields(
+  fields: ReadonlyMap<string, Type>,
+  mapping: ReadonlyMap<number, Type>,
+): Map<string, Type> {
+  return new Map([...fields].map(([name, field]) => [name, substitute(field, mapping)]));
+}

package/src/typecheck/seed-params.ts

@@ -0,0 +1,72 @@
+import type { AstNode } from "langium";
+import type { DecoDecl, Document, Param } from "../generated/ast.js";
+import * as ast from "../generated/ast.js";
+import type { TypeCatalog } from "./catalog.types.js";
+import { createContext } from "./context.js";
+import type { Infer, Slot } from "./infer.js";
+import { collectNamedTypes } from "./named-types.js";
+import { solidify } from "./solidify.js";
+import type { Type } from "./type.types.js";
+
+/** What the call sites turned out to say about each unwritten parameter. */
+export type ParamSeeds = ReadonlyMap<AstNode, Type>;
+
+/** How the checker's two passes are wired, without either importing the other. */
+export type SeedRun = (document: Document, infer: Infer) => void;
+
+/**
+ * A first pass, in silence: what the callers say the named functions take.
+ *
+ * A `fn` declared at the top of a file is not written where it is called, so on
+ * its own it knows nothing about its parameters. The file does say, though:
+ * every call is a statement of what goes in. This pass keeps the functions
+ * monomorphic so those calls reach the declaration, reads off whatever got
+ * decided, and throws the rest away. The real pass then starts from the answers.
+ *
+ * Nothing is carried over from a file that did not type-check cleanly: a
+ * conflict means the first caller won by accident, and a guess made that way
+ * would turn into an error the author never made.
+ */
+export function seedParams(args: {
+  document: Document;
+  catalog?: TypeCatalog;
+  /** Carried through so this pass draws the same line around a reshaped `fn`;
+   * without it one such function's calls would look like a conflict and every
+   * seed in the file would be dropped. */
+  decos?: ReadonlyMap<string, DecoDecl>;
+  parsed?: Map<AstNode, Slot[]>;
+  run: SeedRun;
+}): ParamSeeds {
+  const wanted = unwritten(args.document);
+  if (wanted.length === 0) return new Map();
+  const ctx = createContext();
+  const infer: Infer = {
+    ctx,
+    named: collectNamedTypes(args.document, ctx, args.catalog),
+    catalog: args.catalog,
+    decos: args.decos,
+    parsed: args.parsed,
+    types: new Map(),
+    seeding: true,
+  };
+  args.run(args.document, infer);
+  return ctx.mismatches.length > 0 ? new Map() : settled(wanted, infer);
+}
+
+/** Every parameter of a top-level `fn` that carries no annotation. */
+function unwritten(document: Document): Param[] {
+  return document.decls
+    .filter(ast.isFnDecl)
+    .flatMap((decl) => decl.params?.params ?? [])
+    .filter((param) => !param.paramType);
+}
+
+function settled(params: readonly Param[], infer: Infer): ParamSeeds {
+  const seeds = new Map<AstNode, Type>();
+  for (const param of params) {
+    const found = infer.types?.get(param);
+    const solid = found && solidify(found);
+    if (solid) seeds.set(param, solid);
+  }
+  return seeds;
+}