world-building-framework 0.0.0-stage → 0.2.1

package/dist/cli/vault-path.js

@@ -0,0 +1,44 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { WORLD_CONFIG_FILENAME } from "../core/config/index.js";
+function findSingleVaultUnderVaultsDir() {
+    const vaultsRoot = path.join(process.cwd(), "vaults");
+    let entries;
+    try {
+        entries = readdirSync(vaultsRoot).filter((name) => {
+            try {
+                return statSync(path.join(vaultsRoot, name)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        return undefined;
+    }
+    return entries.length === 1 ? path.join(vaultsRoot, entries[0]) : undefined;
+}
+/** The current folder, if it's a vault — i.e. it has a world.config.json (the vault repo is the project, see claude-dev/DISTRIBUTION_PLAN.md). */
+function currentFolderIfVault() {
+    const cwd = process.cwd();
+    return existsSync(path.join(cwd, WORLD_CONFIG_FILENAME)) ? cwd : undefined;
+}
+/**
+ * Like resolveVaultDir, but returns undefined instead of throwing — for commands
+ * that are useful without a vault (e.g. `schema`).
+ */
+export function findVaultDir(cliOption) {
+    // The ./vaults/ fallback is the old fork-the-framework layout, kept until the
+    // world-repo layout fully replaces it.
+    return cliOption ?? process.env.WBF_VAULT_DIR ?? currentFolderIfVault() ?? findSingleVaultUnderVaultsDir();
+}
+/** Resolves which vault to operate on: explicit flag, then WBF_VAULT_DIR, then the current folder if it has a world.config.json, then a single directory under ./vaults/. */
+export function resolveVaultDir(cliOption) {
+    const vaultDir = findVaultDir(cliOption);
+    if (!vaultDir) {
+        throw new Error("No vault specified — run this inside a vault (a folder with world.config.json), pass --vault <path>, " +
+            "set WBF_VAULT_DIR, or have exactly one directory under ./vaults/.");
+    }
+    return vaultDir;
+}

package/dist/core/config/build-variants.d.ts

@@ -0,0 +1,5 @@
+import type { BuildVariantQuery } from "../query/index.js";
+import type { WorldConfig } from "./schema.js";
+export declare function listBuildVariants(config: WorldConfig): string[];
+/** Looks up a named build variant's query. Throws if the name isn't declared — a typo'd variant name should fail loudly, not silently render everything. */
+export declare function getBuildVariant(config: WorldConfig, name: string): BuildVariantQuery;

package/dist/core/config/build-variants.js

@@ -0,0 +1,13 @@
+export function listBuildVariants(config) {
+    return Object.keys(config.buildVariants ?? {});
+}
+/** Looks up a named build variant's query. Throws if the name isn't declared — a typo'd variant name should fail loudly, not silently render everything. */
+export function getBuildVariant(config, name) {
+    const variant = config.buildVariants?.[name];
+    if (!variant) {
+        const known = listBuildVariants(config);
+        const knownText = known.length > 0 ? known.join(", ") : "(none declared)";
+        throw new Error(`No build variant named "${name}" in this vault's config. Declared variants: ${knownText}`);
+    }
+    return variant;
+}

package/dist/core/config/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./schema.js";
+export * from "./load.js";
+export * from "./validate-options.js";
+export * from "./build-variants.js";

package/dist/core/config/index.js

@@ -0,0 +1,4 @@
+export * from "./schema.js";
+export * from "./load.js";
+export * from "./validate-options.js";
+export * from "./build-variants.js";

package/dist/core/config/load.d.ts

@@ -0,0 +1,4 @@
+import { type WorldConfig } from "./schema.js";
+export declare const WORLD_CONFIG_FILENAME = "world.config.json";
+/** Loads a vault's world.config.json. A missing file means no project-declared config yet — not an error. */
+export declare function loadWorldConfig(vaultDir: string): Promise<WorldConfig>;

package/dist/core/config/load.js

@@ -0,0 +1,25 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { worldConfigSchema } from "./schema.js";
+export const WORLD_CONFIG_FILENAME = "world.config.json";
+/** Loads a vault's world.config.json. A missing file means no project-declared config yet — not an error. */
+export async function loadWorldConfig(vaultDir) {
+    const filePath = path.join(vaultDir, WORLD_CONFIG_FILENAME);
+    let raw;
+    try {
+        raw = await readFile(filePath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return {};
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${filePath} is not valid JSON: ${err.message}`);
+    }
+    return worldConfigSchema.parse(parsed);
+}

package/dist/core/config/schema.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+/**
+ * A vault's own project-specific setup parameters (PROJECT_CONFIG.md).
+ * `title`, `entityTypes` and `buildVariants` are the fields with a decided consumer
+ * so far — tag vocabulary itself (as opposed to where it's used, buildVariants)
+ * and relation-field naming are still open, so this stays loose (unknown keys kept) rather
+ * than locking in a shape for those prematurely.
+ */
+export declare const worldConfigSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    entityTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    buildVariants: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        dateRange: z.ZodOptional<z.ZodObject<{
+            from: z.ZodOptional<z.ZodObject<{
+                year: z.ZodNumber;
+                day: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            to: z.ZodOptional<z.ZodObject<{
+                year: z.ZodNumber;
+                day: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+}, z.core.$loose>;
+export type WorldConfig = z.infer<typeof worldConfigSchema>;
+export declare const DEFAULT_WORLD_TITLE = "World Wiki";
+/** The world's display title, falling back to a neutral default (never Quartz's own "Quartz 5"). */
+export declare function worldTitle(config: WorldConfig): string;

package/dist/core/config/schema.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { buildVariantQuerySchema } from "../query/index.js";
+/**
+ * A vault's own project-specific setup parameters (PROJECT_CONFIG.md).
+ * `title`, `entityTypes` and `buildVariants` are the fields with a decided consumer
+ * so far — tag vocabulary itself (as opposed to where it's used, buildVariants)
+ * and relation-field naming are still open, so this stays loose (unknown keys kept) rather
+ * than locking in a shape for those prematurely.
+ */
+export const worldConfigSchema = z
+    .object({
+    /** The world's name, shown as the published site's title (every variant and the landing page). */
+    title: z.string().min(1).optional(),
+    entityTypes: z.array(z.string()).optional(),
+    /** Named filter queries (render-pipeline's BuildVariantQuery) — PROJECT_CONFIG.md #3. */
+    buildVariants: z.record(z.string(), buildVariantQuerySchema).optional(),
+})
+    .loose();
+export const DEFAULT_WORLD_TITLE = "World Wiki";
+/** The world's display title, falling back to a neutral default (never Quartz's own "Quartz 5"). */
+export function worldTitle(config) {
+    return config.title ?? DEFAULT_WORLD_TITLE;
+}

package/dist/core/config/validate-options.d.ts

@@ -0,0 +1,4 @@
+import type { ValidateOptions } from "../schema/validate.js";
+import type { WorldConfig } from "./schema.js";
+/** Bridges a loaded world.config.json into the shape core/schema's validateFrontmatter expects. */
+export declare function validateOptionsFromConfig(config: WorldConfig): ValidateOptions;

package/dist/core/config/validate-options.js

@@ -0,0 +1,4 @@
+/** Bridges a loaded world.config.json into the shape core/schema's validateFrontmatter expects. */
+export function validateOptionsFromConfig(config) {
+    return { entityTypeVocabulary: config.entityTypes };
+}

package/dist/core/graph/build.d.ts

@@ -0,0 +1,8 @@
+import type { VaultFile } from "../vault/types.js";
+import type { KnowledgeGraph } from "./types.js";
+/**
+ * Builds the relation graph from a set of vault files: nodes are files (by id),
+ * edges come from every wikilink-valued frontmatter field, whatever it's named
+ * (SCHEMA.md rule 2 — no fixed relation vocabulary).
+ */
+export declare function buildGraph(files: VaultFile[]): KnowledgeGraph;

package/dist/core/graph/build.js

@@ -0,0 +1,42 @@
+import { isWikilink, parseWikilink } from "../schema/wikilink.js";
+function extractWikilinks(value) {
+    if (typeof value === "string" && isWikilink(value)) {
+        return [parseWikilink(value)];
+    }
+    if (Array.isArray(value)) {
+        return value.flatMap(extractWikilinks);
+    }
+    return [];
+}
+function push(map, key, edge) {
+    const list = map.get(key);
+    if (list) {
+        list.push(edge);
+    }
+    else {
+        map.set(key, [edge]);
+    }
+}
+/**
+ * Builds the relation graph from a set of vault files: nodes are files (by id),
+ * edges come from every wikilink-valued frontmatter field, whatever it's named
+ * (SCHEMA.md rule 2 — no fixed relation vocabulary).
+ */
+export function buildGraph(files) {
+    const nodes = new Map();
+    const edgesFrom = new Map();
+    const edgesTo = new Map();
+    for (const file of files) {
+        nodes.set(file.id, file);
+    }
+    for (const file of files) {
+        for (const [field, value] of Object.entries(file.frontmatter)) {
+            for (const link of extractWikilinks(value)) {
+                const edge = { field, from: file.id, to: link.targetId, display: link.display };
+                push(edgesFrom, file.id, edge);
+                push(edgesTo, link.targetId, edge);
+            }
+        }
+    }
+    return { nodes, edgesFrom, edgesTo };
+}

package/dist/core/graph/causal.d.ts

@@ -0,0 +1,22 @@
+import type { KnowledgeGraph } from "./types.js";
+/** This event's own `after` targets — its causal predecessors. */
+export declare function predecessors(graph: KnowledgeGraph, eventId: string): string[];
+/** Events whose `after` points at this one — its causal successors. More than one means a branch. */
+export declare function successors(graph: KnowledgeGraph, eventId: string): string[];
+/** Events that fork into more than one successor (SCHEMA.md: a branch is implicit in the `after` graph). */
+export declare function branchPoints(graph: KnowledgeGraph): string[];
+/**
+ * Finds a loop in `after` that runs through `startId`, following `afterOf`
+ * (an event id -> its `after` target ids). Returns the loop as ids, starting
+ * and ending at `startId` — each id is `after` the next one — or undefined.
+ * Takes a lookup rather than a graph so lint can check a not-yet-written
+ * change against the rest of the vault.
+ */
+export declare function findAfterLoop(startId: string, afterOf: (id: string) => string[]): string[] | undefined;
+/**
+ * Topologically orders every event by `after` (predecessors before successors), earliest first.
+ * Where branches exist, events on different branches aren't causally comparable — this still
+ * returns one valid, consistent ordering among them, which is good enough to break ties
+ * (see graph/entities.ts) without needing full partial-order comparison logic yet.
+ */
+export declare function topologicalOrder(graph: KnowledgeGraph): string[];

package/dist/core/graph/causal.js

@@ -0,0 +1,106 @@
+import { outgoing, incoming } from "./queries.js";
+function isEvent(file) {
+    return file.frontmatter.type === "event";
+}
+/** This event's own `after` targets — its causal predecessors. */
+export function predecessors(graph, eventId) {
+    return outgoing(graph, eventId, "after").map((edge) => edge.to);
+}
+/** Events whose `after` points at this one — its causal successors. More than one means a branch. */
+export function successors(graph, eventId) {
+    return incoming(graph, eventId, "after").map((edge) => edge.from);
+}
+/** Events that fork into more than one successor (SCHEMA.md: a branch is implicit in the `after` graph). */
+export function branchPoints(graph) {
+    const points = [];
+    for (const [id, file] of graph.nodes) {
+        if (isEvent(file) && successors(graph, id).length > 1) {
+            points.push(id);
+        }
+    }
+    return points;
+}
+/**
+ * Finds a loop in `after` that runs through `startId`, following `afterOf`
+ * (an event id -> its `after` target ids). Returns the loop as ids, starting
+ * and ending at `startId` — each id is `after` the next one — or undefined.
+ * Takes a lookup rather than a graph so lint can check a not-yet-written
+ * change against the rest of the vault.
+ */
+export function findAfterLoop(startId, afterOf) {
+    const reachedFrom = new Map();
+    const visited = new Set([startId]);
+    const stack = [startId];
+    while (stack.length > 0) {
+        const id = stack.pop();
+        for (const next of afterOf(id)) {
+            if (next === startId) {
+                const loop = [id];
+                while (loop[0] !== startId)
+                    loop.unshift(reachedFrom.get(loop[0]));
+                return [...loop, startId];
+            }
+            if (!visited.has(next)) {
+                visited.add(next);
+                reachedFrom.set(next, id);
+                stack.push(next);
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Topologically orders every event by `after` (predecessors before successors), earliest first.
+ * Where branches exist, events on different branches aren't causally comparable — this still
+ * returns one valid, consistent ordering among them, which is good enough to break ties
+ * (see graph/entities.ts) without needing full partial-order comparison logic yet.
+ */
+export function topologicalOrder(graph) {
+    const eventIds = [...graph.nodes.entries()].filter(([, file]) => isEvent(file)).map(([id]) => id);
+    const remainingPredecessors = new Map();
+    for (const id of eventIds) {
+        remainingPredecessors.set(id, new Set(predecessors(graph, id)));
+    }
+    const order = [];
+    const ready = eventIds.filter((id) => remainingPredecessors.get(id).size === 0);
+    while (ready.length > 0) {
+        const id = ready.shift();
+        order.push(id);
+        for (const childId of successors(graph, id)) {
+            const preds = remainingPredecessors.get(childId);
+            if (!preds)
+                continue;
+            preds.delete(id);
+            if (preds.size === 0)
+                ready.push(childId);
+        }
+    }
+    if (order.length !== eventIds.length) {
+        const ordered = new Set(order);
+        throw new Error(describeUnorderable(graph, eventIds.filter((id) => !ordered.has(id))));
+    }
+    return order;
+}
+/**
+ * Why some events couldn't be ordered, naming them — either a real loop, or an
+ * `after` that points at something which isn't an event in the vault (which
+ * also never becomes "ready"). Lint catches both before writing; this is for
+ * whatever got in anyway, e.g. a hand edit.
+ */
+function describeUnorderable(graph, stuckIds) {
+    const describe = (id) => {
+        const title = graph.nodes.get(id)?.frontmatter.title;
+        return `"${typeof title === "string" ? title : "untitled"}" (${id})`;
+    };
+    for (const id of stuckIds) {
+        const loop = findAfterLoop(id, (eventId) => predecessors(graph, eventId));
+        if (loop) {
+            return `Can't order events — loop in \`after\`, each event is after the next: ${loop.map(describe).join(" → ")}`;
+        }
+    }
+    const isEvent = (id) => graph.nodes.get(id)?.frontmatter.type === "event";
+    const badLinks = stuckIds.flatMap((id) => predecessors(graph, id)
+        .filter((target) => !isEvent(target))
+        .map((target) => `${describe(id)} is after ${target}, which isn't an event in the vault`));
+    return `Can't order events — ${badLinks.length > 0 ? badLinks.join("; ") : `unresolved: ${stuckIds.map(describe).join(", ")}`}`;
+}

package/dist/core/graph/dating.d.ts

@@ -0,0 +1,18 @@
+import type { VaultFile } from "../vault/types.js";
+import { type DateTuple } from "../query/dates.js";
+import type { KnowledgeGraph } from "./types.js";
+/** An event's own `date`, if it has a well-formed one. */
+export declare function eventDate(file: VaultFile | undefined): DateTuple | undefined;
+/**
+ * The span an undated event must fall in, from its causal neighbours
+ * (REQUIREMENTS.md: "sometime after the Founding, before the War"):
+ * - `earliest`: the latest date among the dated events it's (transitively) `after`.
+ * - `latest`: the earliest date among the dated events (transitively) `after` it.
+ * Either side is undefined when no dated event bounds it on that side — the
+ * event could then be arbitrarily early or late.
+ */
+export interface DateWindow {
+    earliest?: DateTuple;
+    latest?: DateTuple;
+}
+export declare function undatedEventWindow(graph: KnowledgeGraph, eventId: string): DateWindow;

package/dist/core/graph/dating.js

@@ -0,0 +1,30 @@
+import { compareDates } from "../query/dates.js";
+import { predecessors, successors } from "./causal.js";
+/** An event's own `date`, if it has a well-formed one. */
+export function eventDate(file) {
+    const date = file?.frontmatter.date;
+    return typeof date?.year === "number" && typeof date.day === "number" ? { year: date.year, day: date.day } : undefined;
+}
+function extremeDate(graph, startId, next, pickLater) {
+    let best;
+    const visited = new Set([startId]);
+    const queue = next(graph, startId);
+    while (queue.length > 0) {
+        const id = queue.shift();
+        if (visited.has(id))
+            continue;
+        visited.add(id);
+        const date = eventDate(graph.nodes.get(id));
+        if (date && (!best || (pickLater ? compareDates(date, best) > 0 : compareDates(date, best) < 0))) {
+            best = date;
+        }
+        queue.push(...next(graph, id));
+    }
+    return best;
+}
+export function undatedEventWindow(graph, eventId) {
+    return {
+        earliest: extremeDate(graph, eventId, predecessors, true),
+        latest: extremeDate(graph, eventId, successors, false),
+    };
+}

package/dist/core/graph/entities.d.ts

@@ -0,0 +1,13 @@
+import type { KnowledgeGraph } from "./types.js";
+/**
+ * Events tied to this entity. Always queried against the anchor id — other files
+ * always link to an entity's anchor, never a later version (SCHEMA.md), so an
+ * event's `entities` field can never name anything but the anchor.
+ */
+export declare function entityTiedEvents(graph: KnowledgeGraph, anchorId: string): string[];
+/**
+ * The chronologically-earliest event tied to this entity, by causal order — this is
+ * the entity's "effective date" for date-range build filtering (REQUIREMENTS.md).
+ * Returns undefined if the entity isn't tied to any event yet.
+ */
+export declare function entityFirstEventId(graph: KnowledgeGraph, anchorId: string): string | undefined;

package/dist/core/graph/entities.js

@@ -0,0 +1,22 @@
+import { incoming } from "./queries.js";
+import { topologicalOrder } from "./causal.js";
+/**
+ * Events tied to this entity. Always queried against the anchor id — other files
+ * always link to an entity's anchor, never a later version (SCHEMA.md), so an
+ * event's `entities` field can never name anything but the anchor.
+ */
+export function entityTiedEvents(graph, anchorId) {
+    return incoming(graph, anchorId, "entities").map((edge) => edge.from);
+}
+/**
+ * The chronologically-earliest event tied to this entity, by causal order — this is
+ * the entity's "effective date" for date-range build filtering (REQUIREMENTS.md).
+ * Returns undefined if the entity isn't tied to any event yet.
+ */
+export function entityFirstEventId(graph, anchorId) {
+    const tied = new Set(entityTiedEvents(graph, anchorId));
+    if (tied.size === 0)
+        return undefined;
+    const order = topologicalOrder(graph);
+    return order.find((id) => tied.has(id));
+}

package/dist/core/graph/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export * from "./build.js";
+export * from "./queries.js";
+export * from "./versioning.js";
+export * from "./causal.js";
+export * from "./entities.js";
+export * from "./dating.js";

package/dist/core/graph/index.js

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export * from "./build.js";
+export * from "./queries.js";
+export * from "./versioning.js";
+export * from "./causal.js";
+export * from "./entities.js";
+export * from "./dating.js";

package/dist/core/graph/queries.d.ts

@@ -0,0 +1,3 @@
+import type { GraphEdge, KnowledgeGraph } from "./types.js";
+export declare function outgoing(graph: KnowledgeGraph, id: string, field?: string): GraphEdge[];
+export declare function incoming(graph: KnowledgeGraph, id: string, field?: string): GraphEdge[];

package/dist/core/graph/queries.js

@@ -0,0 +1,8 @@
+export function outgoing(graph, id, field) {
+    const edges = graph.edgesFrom.get(id) ?? [];
+    return field ? edges.filter((edge) => edge.field === field) : edges;
+}
+export function incoming(graph, id, field) {
+    const edges = graph.edgesTo.get(id) ?? [];
+    return field ? edges.filter((edge) => edge.field === field) : edges;
+}

package/dist/core/graph/types.d.ts

@@ -0,0 +1,14 @@
+import type { VaultFile } from "../vault/types.js";
+export interface GraphEdge {
+    /** The frontmatter field this edge came from (e.g. "location", "after", "supersedes"). */
+    field: string;
+    from: string;
+    to: string;
+    /** The link's display text, as written at link-creation time (SCHEMA.md rule 7). */
+    display: string;
+}
+export interface KnowledgeGraph {
+    nodes: Map<string, VaultFile>;
+    edgesFrom: Map<string, GraphEdge[]>;
+    edgesTo: Map<string, GraphEdge[]>;
+}

package/dist/core/graph/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/graph/versioning.d.ts

@@ -0,0 +1,15 @@
+import type { VaultFile } from "../vault/types.js";
+import type { KnowledgeGraph } from "./types.js";
+/**
+ * Every version of an entity, starting at its anchor id, oldest first
+ * (SCHEMA.md rule 8). This is what the wiki's merge step uses to render an
+ * entity's full history rather than just its latest version.
+ *
+ * Usually the versions form a single chain. If two versions supersede the same
+ * file (a fork — a story branch, or more often a version pointed at the wrong
+ * predecessor), all of them are still returned rather than silently dropping
+ * one: a version always comes after the one it supersedes, and versions that
+ * are ready at the same time are ordered by their `causedBy` event's causal
+ * position, then by id, so the result never depends on vault read order.
+ */
+export declare function versionHistory(graph: KnowledgeGraph, anchorId: string): VaultFile[];

package/dist/core/graph/versioning.js

@@ -0,0 +1,50 @@
+import { incoming, outgoing } from "./queries.js";
+import { topologicalOrder } from "./causal.js";
+/**
+ * Every version of an entity, starting at its anchor id, oldest first
+ * (SCHEMA.md rule 8). This is what the wiki's merge step uses to render an
+ * entity's full history rather than just its latest version.
+ *
+ * Usually the versions form a single chain. If two versions supersede the same
+ * file (a fork — a story branch, or more often a version pointed at the wrong
+ * predecessor), all of them are still returned rather than silently dropping
+ * one: a version always comes after the one it supersedes, and versions that
+ * are ready at the same time are ordered by their `causedBy` event's causal
+ * position, then by id, so the result never depends on vault read order.
+ */
+export function versionHistory(graph, anchorId) {
+    const anchor = graph.nodes.get(anchorId);
+    if (!anchor)
+        return [];
+    const history = [anchor];
+    const seen = new Set([anchorId]);
+    const ready = [];
+    const addSuccessors = (id) => {
+        for (const edge of incoming(graph, id, "supersedes")) {
+            if (seen.has(edge.from)) {
+                throw new Error(`Cycle detected in supersedes chain starting at ${anchorId}`);
+            }
+            seen.add(edge.from);
+            const file = graph.nodes.get(edge.from);
+            if (file)
+                ready.push(file);
+        }
+    };
+    // Only needed to order a fork, so a plain chain never pays for (or depends on) the causal sort.
+    let causalIndex;
+    const rank = (file) => {
+        causalIndex ??= new Map(topologicalOrder(graph).map((id, i) => [id, i]));
+        const causedBy = outgoing(graph, file.id, "causedBy")[0];
+        return (causedBy && causalIndex.get(causedBy.to)) ?? Infinity;
+    };
+    addSuccessors(anchorId);
+    while (ready.length > 0) {
+        if (ready.length > 1) {
+            ready.sort((a, b) => rank(a) - rank(b) || (a.id < b.id ? -1 : 1));
+        }
+        const next = ready.shift();
+        history.push(next);
+        addSuccessors(next.id);
+    }
+    return history;
+}

package/dist/core/id.d.ts

@@ -0,0 +1,3 @@
+/** Generates a new file identity (used as a vault file's filename, per SCHEMA.md rule 1). */
+export declare function generateId(): string;
+export declare function isUuid(value: string): boolean;

package/dist/core/id.js

@@ -0,0 +1,9 @@
+import { v4 as uuidv4 } from "uuid";
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Generates a new file identity (used as a vault file's filename, per SCHEMA.md rule 1). */
+export function generateId() {
+    return uuidv4();
+}
+export function isUuid(value) {
+    return UUID_RE.test(value);
+}

package/dist/core/lint/after-loops.d.ts

@@ -0,0 +1,15 @@
+import type { VaultFile } from "../vault/types.js";
+import type { ValidationIssue } from "../schema/validate.js";
+/** The ids a file's `after` points at (valid wikilinks only). */
+export declare function afterTargets(frontmatter: Record<string, unknown>): string[];
+/**
+ * Flags an event that's part of a loop in `after` (it would end up before
+ * itself). An error: unlike a fork, a loop is never meaningful, and it makes
+ * causal ordering — and with it the render — fail. Checks the file's own
+ * `after` as given (so an update is judged on its new content) against every
+ * other event's stored `after`. A file without an id is new: nothing links to
+ * it yet, so it can't be in a loop.
+ */
+export declare function findAfterLoops(file: Pick<VaultFile, "frontmatter"> & {
+    id?: string;
+}, afterOf: Map<string, string[]>, titles: Map<string, string>): ValidationIssue[];

package/dist/core/lint/after-loops.js

@@ -0,0 +1,34 @@
+import { isWikilink, parseWikilink } from "../schema/wikilink.js";
+import { findAfterLoop } from "../graph/causal.js";
+/** The ids a file's `after` points at (valid wikilinks only). */
+export function afterTargets(frontmatter) {
+    const value = frontmatter.after;
+    if (!Array.isArray(value))
+        return [];
+    return value.filter(isWikilink).map((link) => parseWikilink(link).targetId);
+}
+/**
+ * Flags an event that's part of a loop in `after` (it would end up before
+ * itself). An error: unlike a fork, a loop is never meaningful, and it makes
+ * causal ordering — and with it the render — fail. Checks the file's own
+ * `after` as given (so an update is judged on its new content) against every
+ * other event's stored `after`. A file without an id is new: nothing links to
+ * it yet, so it can't be in a loop.
+ */
+export function findAfterLoops(file, afterOf, titles) {
+    if (!file.id || file.frontmatter.type !== "event")
+        return [];
+    const ownAfter = afterTargets(file.frontmatter);
+    const loop = findAfterLoop(file.id, (id) => (id === file.id ? ownAfter : (afterOf.get(id) ?? [])));
+    if (!loop)
+        return [];
+    const ownTitle = typeof file.frontmatter.title === "string" ? file.frontmatter.title : undefined;
+    const describe = (id) => `"${(id === file.id ? ownTitle : titles.get(id)) ?? "untitled"}" (${id})`;
+    return [
+        {
+            path: "after",
+            message: `Loop in \`after\` — each event is after the next, so none can come first: ${loop.map(describe).join(" → ")}`,
+            severity: "error",
+        },
+    ];
+}

package/dist/core/lint/dangling-links.d.ts

@@ -0,0 +1,9 @@
+import type { VaultFile } from "../vault/types.js";
+import type { ValidationIssue } from "../schema/validate.js";
+/**
+ * Finds wikilinks — frontmatter or body — pointing at an id that doesn't exist
+ * anywhere in the vault. Checks body text too, not just frontmatter relations:
+ * a broken link is still bad to read even though body mentions don't count as
+ * relation edges (REQUIREMENTS.md's explicit-only relatedness rule).
+ */
+export declare function findDanglingLinks(file: Pick<VaultFile, "frontmatter" | "body">, knownIds: Set<string>): ValidationIssue[];