@rpgm-tools/neo-angband-mod-sdk 0.10.0

package/src/patch.ts

@@ -0,0 +1,257 @@
+/**
+ * Field-level patch composition (MOD_LIFECYCLE section 3, P7 phase 3).
+ *
+ * The coarse `patches` path in compose.ts deep-merges whole record bodies:
+ * simple, but two mods touching one record always look like they collide even
+ * when they change unrelated fields. The field-level model fixes that. A patch
+ * is an ordered list of field operations - `set`, `merge`, `addFlag`,
+ * `removeFlag`, `add`, `mul` - each addressing a dot-path into the record.
+ * Patches from different packs apply in load order; two packs that touch
+ * DIFFERENT fields compose with zero conflict, and only a genuine same-field
+ * collision is reported (then load order decides who wins, and the app says
+ * so). This is the finer lever the ratified design calls for, and it is the
+ * data the conflict report (phase 6) reads.
+ *
+ * Pure and deterministic: given a base record and an ordered patch list the
+ * output and the conflict set are fully determined.
+ */
+
+import type { JsonRecord, JsonValue } from "./compose.js";
+import { mergePatch } from "./compose.js";
+
+export class PatchError extends Error {}
+
+/** One field operation, addressing `path` (a dot-path into the record). */
+export type FieldOp =
+  /** Replace the value at path outright. */
+  | { op: "set"; path: string; value: JsonValue }
+  /** Deep-merge an object value into the object at path (compose.mergePatch). */
+  | { op: "merge"; path: string; value: JsonRecord }
+  /** Ensure `flag` is present in the string array at path (set union). */
+  | { op: "addFlag"; path: string; flag: string }
+  /** Remove `flag` from the string array at path, if present. */
+  | { op: "removeFlag"; path: string; flag: string }
+  /** Add a number to the numeric value at path (missing = 0). */
+  | { op: "add"; path: string; value: number }
+  /** Multiply the numeric value at path (missing = 0). */
+  | { op: "mul"; path: string; value: number };
+
+/** An ordered list of field operations - one pack's patch of one record. */
+export type FieldPatch = FieldOp[];
+
+/** The flag ops compose as set operations; the rest are order-dependent. */
+function isCommutative(op: FieldOp["op"]): boolean {
+  return op === "addFlag" || op === "removeFlag";
+}
+
+/* ------------------------------------------------------------------ *
+ * Dot-path access.
+ *
+ * A path segment that is a run of digits indexes an ARRAY ("level-max.0.value").
+ * Array traversal is not a convenience: a great deal of upstream gamedata is
+ * label/value lists rather than objects - every section of constants.json, a
+ * store's owner list, a body's slot list, the visuals flicker table - so without
+ * it a fieldPatch into those files could not address anything. Worse, the first
+ * version of setPath treated an existing array as an unusable intermediate and
+ * REPLACED it with a fresh object, which turned `set level-max.0.value` into
+ * silent destruction of the whole list. Objects still win when the container is
+ * an object, so a literal "0" key is unaffected.
+ * ------------------------------------------------------------------ */
+
+/** A path segment as an array index, or null when it is a plain object key. */
+function arrayIndex(part: string): number | null {
+  return /^(?:0|[1-9][0-9]*)$/.test(part) ? Number(part) : null;
+}
+
+/** One step down a path, through either an object key or an array index. */
+function childOf(cur: JsonValue | undefined, part: string): JsonValue | undefined {
+  if (Array.isArray(cur)) {
+    const at = arrayIndex(part);
+    return at === null ? undefined : cur[at];
+  }
+  if (typeof cur === "object" && cur !== null) return (cur as JsonRecord)[part];
+  return undefined;
+}
+
+function getPath(record: JsonRecord, path: string): JsonValue | undefined {
+  let cur: JsonValue | undefined = record;
+  for (const part of path.split(".")) {
+    cur = childOf(cur, part);
+    if (cur === undefined) return undefined;
+  }
+  return cur;
+}
+
+/** Write one slot of an object or an array container. */
+function assignAt(
+  container: JsonRecord | JsonValue[],
+  part: string,
+  value: JsonValue,
+): void {
+  if (Array.isArray(container)) {
+    const at = arrayIndex(part);
+    if (at === null) {
+      throw new PatchError(
+        `patch: "${part}" is not an array index, and the value at that point is an array`,
+      );
+    }
+    container[at] = value;
+    return;
+  }
+  container[part] = value;
+}
+
+/**
+ * Set a value at a dot-path, creating intermediate containers as needed. A
+ * created container is an array when the next segment is an index and an object
+ * otherwise, so `set a.0.b` on a record with no `a` builds `{a:[{b:...}]}`.
+ */
+function setPath(record: JsonRecord, path: string, value: JsonValue): void {
+  const parts = path.split(".");
+  let cur: JsonRecord | JsonValue[] = record;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i] as string;
+    const next = childOf(cur as JsonValue, part);
+    if (typeof next !== "object" || next === null) {
+      const fresh: JsonValue =
+        arrayIndex(parts[i + 1] as string) === null ? {} : [];
+      assignAt(cur, part, fresh);
+      cur = fresh as JsonRecord | JsonValue[];
+    } else {
+      cur = next as JsonRecord | JsonValue[];
+    }
+  }
+  assignAt(cur, parts[parts.length - 1] as string, value);
+}
+
+/* ------------------------------------------------------------------ *
+ * Applying a single patch.
+ * ------------------------------------------------------------------ */
+
+/** Apply one field patch to a record, returning a new record (pure). */
+export function applyFieldPatch(record: JsonRecord, ops: FieldPatch): JsonRecord {
+  const out = structuredJsonClone(record);
+  for (const op of ops) applyOp(out, op);
+  return out;
+}
+
+function applyOp(record: JsonRecord, op: FieldOp): void {
+  switch (op.op) {
+    case "set":
+      setPath(record, op.path, op.value);
+      return;
+    case "merge": {
+      const cur = getPath(record, op.path);
+      const base =
+        typeof cur === "object" && cur !== null && !Array.isArray(cur)
+          ? (cur as JsonRecord)
+          : {};
+      setPath(record, op.path, mergePatch(base, op.value));
+      return;
+    }
+    case "addFlag": {
+      const list = asFlagList(getPath(record, op.path), op.path);
+      if (!list.includes(op.flag)) list.push(op.flag);
+      setPath(record, op.path, list);
+      return;
+    }
+    case "removeFlag": {
+      const list = asFlagList(getPath(record, op.path), op.path);
+      setPath(
+        record,
+        op.path,
+        list.filter((f) => f !== op.flag),
+      );
+      return;
+    }
+    case "add": {
+      const cur = getPath(record, op.path);
+      const n = typeof cur === "number" ? cur : 0;
+      setPath(record, op.path, n + op.value);
+      return;
+    }
+    case "mul": {
+      const cur = getPath(record, op.path);
+      const n = typeof cur === "number" ? cur : 0;
+      setPath(record, op.path, n * op.value);
+      return;
+    }
+  }
+}
+
+/** A flag field must be a string array (or absent, treated as empty). */
+function asFlagList(value: JsonValue | undefined, path: string): string[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
+    throw new PatchError(`patch: field ${path} is not a flag list (string[])`);
+  }
+  return [...(value as string[])];
+}
+
+/** A structural JSON clone (no Date.now/Math.random dependence). */
+function structuredJsonClone(record: JsonRecord): JsonRecord {
+  return JSON.parse(JSON.stringify(record)) as JsonRecord;
+}
+
+/* ------------------------------------------------------------------ *
+ * Composing ordered patches with conflict detection.
+ * ------------------------------------------------------------------ */
+
+/** One same-field collision between two or more packs. */
+export interface FieldConflict {
+  /** The dot-path both packs wrote. */
+  path: string;
+  /** The packs that wrote it, in load order (last one wins the value). */
+  owners: string[];
+}
+
+/** The result of composing several packs' patches over one base record. */
+export interface ComposedPatch {
+  /** The merged record (all patches applied in load order). */
+  value: JsonRecord;
+  /** Same-field collisions, empty when every pack touched distinct fields. */
+  conflicts: FieldConflict[];
+}
+
+/**
+ * Compose several packs' field patches over a base record, applying them in
+ * the given (load) order and reporting same-field collisions. A field is a
+ * conflict when two or more distinct packs write it with an order-dependent op
+ * (set / merge / add / mul); pure flag ops (addFlag / removeFlag) compose as
+ * set operations and never conflict on their own.
+ */
+export function composeFieldPatches(
+  base: JsonRecord,
+  patches: ReadonlyArray<{ owner: string; ops: FieldPatch }>,
+): ComposedPatch {
+  let value = structuredJsonClone(base);
+  /* path -> the owners who wrote it, and whether any write was order-dependent. */
+  const writers = new Map<string, { owners: string[]; ordered: boolean }>();
+
+  for (const { owner, ops } of patches) {
+    value = applyFieldPatch(value, ops);
+    for (const op of ops) {
+      const entry = writers.get(op.path) ?? { owners: [], ordered: false };
+      if (entry.owners[entry.owners.length - 1] !== owner) {
+        entry.owners.push(owner);
+      }
+      if (!isCommutative(op.op)) entry.ordered = true;
+      writers.set(op.path, entry);
+    }
+  }
+
+  const conflicts: FieldConflict[] = [];
+  for (const [path, entry] of writers) {
+    if (entry.ordered && entry.owners.length > 1) {
+      conflicts.push({ path, owners: entry.owners });
+    }
+  }
+  return { value, conflicts };
+}
+
+/** The set of dot-paths a patch writes (for external conflict analysis). */
+export function touchedFields(ops: FieldPatch): Set<string> {
+  const out = new Set<string>();
+  for (const op of ops) out.add(op.path);
+  return out;
+}

package/src/record-key.ts

@@ -0,0 +1,180 @@
+/**
+ * Per-record identity for the record files whose identity is NOT a unique
+ * string `name`.
+ *
+ * CURRENT STATE, FIRST, BECAUSE THIS COMMENT USED TO MISLEAD. Every record file
+ * but ONE is addressable per record today: 24 by a unique `name`, 19 by the
+ * explicit specs in this file, and `history` by nothing - and an op against
+ * `history` is REPORTED, never silently dropped. Two independent reviewers read
+ * the older wording, took the "the other 20 files do not fit it" paragraph below
+ * for the present tense, and filed the same non-existent P1 ("20 files silently
+ * discard patch/replace/remove, including object, ego_item, vault, trap, store,
+ * brand, slay, projection, constants"). Those nine are precisely the files this
+ * table fixes. If you are about to report that bug, run record-key.test.ts.
+ *
+ * WHY THIS EXISTS
+ *
+ * composePacks (compose.ts) keys every record by `packRef(pack, slugify(name))`.
+ * That is the right identity for the 24 upstream record files whose records
+ * carry a unique `name` - monster, object_property, terrain and so on - and it
+ * is what makes `patches` / `replaces` / `fieldPatches` / `removes` work there.
+ *
+ * The other 20 files did not fit it, for two measured reasons (counts taken over
+ * packages/content/pack on 2026-07-29). This is the problem statement, not the
+ * status:
+ *
+ *  - 14 files have no string `name` at all. Their identity lives somewhere else:
+ *    `code` (brand, slay, chest_trap, projection), the tval half of a composite
+ *    (`object_base`), the upstream `name:<name>:<desc>` line (trap), an index
+ *    (pain, names), a plain other field (store, ui_knowledge, body, world,
+ *    flavor, hints), or nowhere at all because the file is a single config
+ *    singleton (constants, visuals).
+ *  - 6 files DO have `name` but core's own data slugs two records to the same
+ *    ref, mostly because slugify drops `*` and `+`: object has 5 such pairs
+ *    ("Acquirement" / "*Acquirement*"), vault 1 ("Little eruption" /
+ *    "Little eruption+"), and brand / slay / chest_trap name several records
+ *    after the element rather than the variant. ego_item is the genuine case:
+ *    "of Acid" exists twice, distinguished only by which item types it applies
+ *    to - which are the very fields a mod would patch, so they cannot be part of
+ *    its identity.
+ *
+ * Before this file existed, a per-record op against any of those 20 was
+ * SILENTLY DROPPED (loader.ts stripped the whole contribution before compose saw
+ * it). This table is what makes 19 of them addressable, and it is deliberately
+ * an EXPLICIT declaration rather than a heuristic: guessing a key would trade a
+ * silent drop for a silent mis-merge, which is worse. Every entry below was
+ * verified unique over the shipped core pack (see record-key.test.ts, which
+ * reads the real pack and fails if a declared key stops being unique).
+ *
+ * `history` is deliberately absent: a history record is
+ * `{chart:{chart,next,roll}, phrase}` and every part of that is a value a mod
+ * would legitimately change, so it has no identity to key on. An op against it
+ * is REPORTED, not applied - see loader.ts.
+ *
+ * AMBIGUITY IS NAMED, NEVER GUESSED. A key that two records in the same file
+ * claim (object's 5 pairs, ego_item's 25) makes that one ref unaddressable; the
+ * records stay in the game and any op naming the ref becomes a reported problem.
+ * The rest of the file remains addressable per record.
+ */
+
+import { slugify } from "./manifest.js";
+import type { JsonRecord, JsonValue } from "./compose.js";
+
+/**
+ * How to derive one record's identity within a file.
+ *
+ * - `fields`: slugify each dot-path in order and join with "--". Every path must
+ *   resolve to a string or a number; anything else (absent, object, array) means
+ *   the record has no derivable key and is simply not addressable.
+ * - `singleton`: the file holds exactly one config record, so the FILE is the
+ *   identity (ref `<pack>:<file>`). A second record in such a file collides with
+ *   the first and both become unaddressable, which is the correct answer - the
+ *   host binds one.
+ */
+export type RecordKeySpec =
+  | { readonly kind: "fields"; readonly paths: readonly string[] }
+  | { readonly kind: "singleton" };
+
+/**
+ * The identity of every record file that is NOT keyed by a unique string `name`.
+ *
+ * A file absent from this table is keyed by `name`, which is what composePacks
+ * already does. Keys here are file stems, exactly as they appear in a pack
+ * folder (`brand.json` -> `brand`).
+ */
+export const RECORD_KEY_SPECS: Readonly<Record<string, RecordKeySpec>> = {
+  /* `code` is the upstream identity; `name` names the element, so ACID_2 and
+   * ACID_3 both slug to "acid". */
+  brand: { kind: "fields", paths: ["code"] },
+  slay: { kind: "fields", paths: ["code"] },
+  chest_trap: { kind: "fields", paths: ["code"] },
+  /* projection: `code` is on all 56 records, `name` is not. */
+  projection: { kind: "fields", paths: ["code"] },
+  /* object_base: `name` is the composite {tval, name}; tval is the key upstream
+   * looks bases up by. */
+  object_base: { kind: "fields", paths: ["name.tval"] },
+  /* trap: `name` is the composite {name, desc} - upstream's `name:<name>:<desc>`
+   * line. The display half repeats (6 records are "strange rune"); the pair is
+   * unique. */
+  trap: { kind: "fields", paths: ["name.name", "name.desc"] },
+  /* store: the STORE_* code. */
+  store: { kind: "fields", paths: ["store"] },
+  /* pain: the message-set index, which IS its identity (mon_pain_msg). */
+  pain: { kind: "fields", paths: ["type"] },
+  ui_knowledge: { kind: "fields", paths: ["monster-category"] },
+  /* names: the random-name section index. */
+  names: { kind: "fields", paths: ["section"] },
+  body: { kind: "fields", paths: ["body"] },
+  /* world: the level's name, which is what upstream's up/down links reference. */
+  world: { kind: "fields", paths: ["level.name"] },
+  /* flavor: one record per object base, keyed by that base's tval. */
+  flavor: { kind: "fields", paths: ["kind.tval"] },
+  /* hints: the hint text is the whole record, so it is also its identity. */
+  hints: { kind: "fields", paths: ["H"] },
+  /* Config singletons: one record for the whole file. */
+  constants: { kind: "singleton" },
+  visuals: { kind: "singleton" },
+  /* Files that DO have `name` but need more of the record to be unique. Each is
+   * still not fully unique (see the header) - the residual collisions are
+   * reported, never guessed. */
+  object: { kind: "fields", paths: ["type", "name"] },
+  vault: { kind: "fields", paths: ["type", "name"] },
+  ego_item: { kind: "fields", paths: ["name"] },
+};
+
+/**
+ * Files with a declared key spec, sorted. Exported so a test can assert the set
+ * in BOTH directions (a file wrongly added and a file wrongly removed).
+ */
+export const KEYED_RECORD_FILES: readonly string[] =
+  Object.keys(RECORD_KEY_SPECS).sort();
+
+/** The key spec for a file: the declared one, or `name` by default. */
+export function keySpecFor(file: string): RecordKeySpec {
+  return RECORD_KEY_SPECS[file] ?? { kind: "fields", paths: ["name"] };
+}
+
+function atPath(record: JsonRecord, path: string): JsonValue | undefined {
+  let cur: JsonValue | undefined = record;
+  for (const part of path.split(".")) {
+    if (typeof cur !== "object" || cur === null || Array.isArray(cur)) {
+      return undefined;
+    }
+    cur = (cur as JsonRecord)[part];
+    if (cur === undefined) return undefined;
+  }
+  return cur;
+}
+
+/**
+ * The slug half of a record's ref within `file`, or null when this record has no
+ * derivable identity (a missing key field, or a key field that is not a scalar).
+ * Null means "not addressable"; it never means "drop the record".
+ */
+export function recordKey(
+  file: string,
+  record: unknown,
+  spec: RecordKeySpec = keySpecFor(file),
+): string | null {
+  if (typeof record !== "object" || record === null || Array.isArray(record)) {
+    return null;
+  }
+  if (spec.kind === "singleton") return slugify(file);
+  const parts: string[] = [];
+  for (const path of spec.paths) {
+    const value = atPath(record as JsonRecord, path);
+    if (typeof value !== "string" && typeof value !== "number") return null;
+    const slug = slugify(String(value));
+    if (slug.length === 0) return null;
+    parts.push(slug);
+  }
+  return parts.join("--");
+}
+
+/** A human phrase for what a file's identity is, for problem messages. */
+export function keyDescription(file: string): string {
+  const spec = keySpecFor(file);
+  return spec.kind === "singleton"
+    ? `the whole file (one config record, ref "<pack>:${slugify(file)}")`
+    : spec.paths.join(" + ");
+}

package/src/resolve.ts

@@ -0,0 +1,175 @@
+/**
+ * Deterministic pack load-order resolution.
+ *
+ * Dependencies load before dependents (topological order); ties break by the
+ * caller's INPUT ORDER, so the order is reproducible on every machine given the
+ * same pack list. Cycles and missing dependencies are hard errors - a mod set
+ * either composes deterministically or fails loudly before play.
+ *
+ * TIES USED TO BREAK LEXICOGRAPHICALLY BY ID, and that was a defect, not a
+ * preference. Determinism was the goal and input order delivers it just as well:
+ * the caller's list is itself deterministic (the stored enabled array, an
+ * external manager's load-order.json, or `?mods=a,b`). Sorting by id instead
+ * DISCARDED the player's choice, while the mod manager went on offering "Move
+ * later (loads last, wins conflicts)" (web/src/mods.ts) - a reorder that changed
+ * nothing for any two packs with no dependency edge between them, which is most
+ * pairs. Vortex/MO2 semantics require the deployed order to decide, so the one
+ * thing the resolver must not do is invent an order of its own.
+ *
+ * Dependency edges still win outright: input order only decides among packs the
+ * graph leaves free, which is exactly what a load-order list is for.
+ *
+ * Beyond hard `dependencies`, MOD_LIFECYCLE.md section 3 defines two more
+ * ordering inputs, both soft (their absence is never an error):
+ *
+ *  - `optionalDependencies`: if the named pack is present, it loads first
+ *    and its version is checked against the declared range exactly like a
+ *    hard dependency; if it is absent, it is silently skipped.
+ *  - `loadAfter` / `loadBefore`: pure ordering hints among present packs,
+ *    with no version semantics. `loadBefore` is implemented as the mirror
+ *    of `loadAfter` (X.loadBefore = [Y] adds the same edge as Y.loadAfter
+ *    = [X]).
+ *
+ * All of these contribute edges to the same topological sort, so a cycle
+ * created by mixing dependencies with loadAfter/loadBefore is rejected
+ * exactly like a dependency cycle.
+ */
+
+import type { PackManifest } from "./manifest.js";
+import { ManifestError } from "./manifest.js";
+import { satisfies, SemverError } from "./semver.js";
+
+export class ResolveError extends Error {}
+
+/**
+ * Verify a present dependency's version range, throwing ResolveError with a
+ * plain-language message naming the fix. Used for both hard `dependencies`
+ * and `optionalDependencies` that happen to be present.
+ */
+function checkVersionRange(
+  dependentId: string,
+  depId: string,
+  range: string,
+  byId: ReadonlyMap<string, PackManifest>,
+): void {
+  const dep = byId.get(depId) as PackManifest;
+  let ok: boolean;
+  try {
+    ok = satisfies(dep.version, range);
+  } catch (err) {
+    const reason = err instanceof SemverError ? err.message : String(err);
+    throw new ResolveError(
+      `pack ${dependentId} declares an invalid version range "${range}" for ${depId}: ${reason}`,
+    );
+  }
+  if (!ok) {
+    throw new ResolveError(
+      `pack ${dependentId} requires ${depId} ${range} but ${dep.version} is installed`,
+    );
+  }
+}
+
+/** Order manifests so every pack follows all of its dependencies. */
+export function resolveLoadOrder(
+  manifests: readonly PackManifest[],
+): PackManifest[] {
+  const byId = new Map<string, PackManifest>();
+  for (const m of manifests) {
+    if (byId.has(m.id)) {
+      throw new ManifestError(`duplicate pack id: ${m.id}`);
+    }
+    byId.set(m.id, m);
+  }
+
+  for (const m of manifests) {
+    for (const [dep, range] of Object.entries(m.dependencies ?? {})) {
+      if (!byId.has(dep)) {
+        throw new ResolveError(`pack ${m.id} requires missing pack ${dep}`);
+      }
+      checkVersionRange(m.id, dep, range, byId);
+    }
+    for (const [dep, range] of Object.entries(m.optionalDependencies ?? {})) {
+      if (!byId.has(dep)) continue; // absence of an optional dependency is not an error
+      checkVersionRange(m.id, dep, range, byId);
+    }
+  }
+
+  // Collect, per pack, the full set of ids that must load before it: hard
+  // deps, present optional deps, present loadAfter, and the reverse edge
+  // for every present pack's loadBefore. Built as per-id Sets so that the
+  // same edge declared twice (e.g. both a hard dependency and a loadAfter
+  // entry) collapses to one edge instead of a duplicate that would corrupt
+  // the Kahn in-degree bookkeeping below.
+  const prereqs = new Map<string, Set<string>>();
+  for (const m of manifests) {
+    prereqs.set(m.id, new Set());
+  }
+  for (const m of manifests) {
+    const set = prereqs.get(m.id) as Set<string>;
+    for (const dep of Object.keys(m.dependencies ?? {})) {
+      set.add(dep);
+    }
+    for (const dep of Object.keys(m.optionalDependencies ?? {})) {
+      if (byId.has(dep)) set.add(dep);
+    }
+    for (const after of m.loadAfter ?? []) {
+      if (byId.has(after)) set.add(after);
+    }
+  }
+  for (const m of manifests) {
+    for (const before of m.loadBefore ?? []) {
+      // m must load before `before`: that is the same edge as
+      // `before`.loadAfter including m, so add it to before's prereq set.
+      const set = prereqs.get(before);
+      if (set !== undefined) set.add(m.id);
+    }
+  }
+
+  const remainingDeps = new Map<string, Set<string>>();
+  const dependents = new Map<string, string[]>();
+  for (const m of manifests) {
+    remainingDeps.set(m.id, new Set(prereqs.get(m.id)));
+    for (const dep of prereqs.get(m.id) as Set<string>) {
+      const list = dependents.get(dep) ?? [];
+      list.push(m.id);
+      dependents.set(dep, list);
+    }
+  }
+
+  /* The caller's position for each id, which is what ties break on. */
+  const inputAt = new Map<string, number>();
+  manifests.forEach((m, i) => inputAt.set(m.id, i));
+  const at = (id: string): number => inputAt.get(id) ?? 0;
+
+  // Kahn with a frontier kept in input order, so the result is deterministic
+  // without the resolver imposing an order the player did not choose.
+  const frontier = [...remainingDeps.entries()]
+    .filter(([, deps]) => deps.size === 0)
+    .map(([id]) => id)
+    .sort((a, b) => at(a) - at(b));
+  const order: PackManifest[] = [];
+
+  while (frontier.length > 0) {
+    const id = frontier.shift() as string;
+    order.push(byId.get(id) as PackManifest);
+    for (const dependent of dependents.get(id) ?? []) {
+      const deps = remainingDeps.get(dependent) as Set<string>;
+      deps.delete(id);
+      if (deps.size === 0) {
+        // Insert keeping the frontier in input order.
+        const pos = frontier.findIndex((f) => at(f) > at(dependent));
+        if (pos === -1) frontier.push(dependent);
+        else frontier.splice(pos, 0, dependent);
+      }
+    }
+  }
+
+  if (order.length !== manifests.length) {
+    const stuck = [...remainingDeps.entries()]
+      .filter(([, deps]) => deps.size > 0)
+      .map(([id]) => id)
+      .sort();
+    throw new ResolveError(`dependency cycle among packs: ${stuck.join(", ")}`);
+  }
+  return order;
+}