world-building-framework 0.0.0-stage → 0.2.1

package/dist/core/schema/validate.js

@@ -0,0 +1,34 @@
+import { knowledgeFileFrontmatterSchema } from "./fields.js";
+export function hasErrors(issues) {
+    return issues.some((issue) => issue.severity === "error");
+}
+/**
+ * The one place a knowledge file's frontmatter gets checked (PROJECT_STRUCTURE.md:
+ * used by vault parsing, CLI `validate`/`create`, and the CLI's `schema` introspection).
+ */
+export function validateFrontmatter(raw, options = {}) {
+    const result = knowledgeFileFrontmatterSchema.safeParse(raw);
+    if (!result.success) {
+        return {
+            valid: false,
+            issues: result.error.issues.map((issue) => ({
+                path: issue.path.join("."),
+                message: issue.message,
+                severity: "error",
+            })),
+        };
+    }
+    const frontmatter = result.data;
+    const issues = [];
+    if (frontmatter.type === "entity" &&
+        frontmatter.entityType &&
+        options.entityTypeVocabulary &&
+        !options.entityTypeVocabulary.includes(frontmatter.entityType)) {
+        issues.push({
+            path: "entityType",
+            message: `"${frontmatter.entityType}" is not in this project's declared entityType vocabulary (${options.entityTypeVocabulary.join(", ")})`,
+            severity: "error",
+        });
+    }
+    return { valid: issues.length === 0, frontmatter, issues };
+}

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

@@ -0,0 +1,8 @@
+export interface Wikilink {
+    targetId: string;
+    display: string;
+}
+/** True if `value` is a wikilink in the framework's required form: `[[uuid|Display Name]]` (SCHEMA.md rule 7). */
+export declare function isWikilink(value: unknown): value is string;
+export declare function parseWikilink(raw: string): Wikilink;
+export declare function formatWikilink(targetId: string, display: string): string;

package/dist/core/schema/wikilink.js

@@ -0,0 +1,23 @@
+import { isUuid } from "../id.js";
+const WIKILINK_RE = /^\[\[([0-9a-f-]{36})\|(.+)\]\]$/i;
+/** True if `value` is a wikilink in the framework's required form: `[[uuid|Display Name]]` (SCHEMA.md rule 7). */
+export function isWikilink(value) {
+    if (typeof value !== "string")
+        return false;
+    const match = WIKILINK_RE.exec(value);
+    return match !== null && isUuid(match[1]);
+}
+export function parseWikilink(raw) {
+    const match = WIKILINK_RE.exec(raw);
+    if (!match) {
+        throw new Error(`Not a valid wikilink (expected "[[uuid|Display Name]]"): ${raw}`);
+    }
+    const [, targetId, display] = match;
+    if (!isUuid(targetId)) {
+        throw new Error(`Wikilink target is not a valid UUID: ${targetId}`);
+    }
+    return { targetId, display };
+}
+export function formatWikilink(targetId, display) {
+    return `[[${targetId}|${display}]]`;
+}

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

@@ -0,0 +1,11 @@
+import type { VaultFile } from "../vault/types.js";
+import type { SearchIndex } from "./types.js";
+/**
+ * Builds an in-memory FTS5 search index from the current vault state. This is a
+ * disposable cache, not a source of truth — rebuild it whenever the vault changes
+ * rather than trying to keep it in sync incrementally (see claude-dev/PROJECT_STRUCTURE.md
+ * discussion: not worth the complexity until indexing hundreds of files is ever
+ * actually slow, which it isn't).
+ */
+export declare function buildSearchIndex(files: VaultFile[]): SearchIndex;
+export declare function closeSearchIndex(index: SearchIndex): void;

package/dist/core/search/build.js

@@ -0,0 +1,26 @@
+import Database from "better-sqlite3";
+import { COLUMNS, toSpaceJoined } from "./columns.js";
+/**
+ * Builds an in-memory FTS5 search index from the current vault state. This is a
+ * disposable cache, not a source of truth — rebuild it whenever the vault changes
+ * rather than trying to keep it in sync incrementally (see claude-dev/PROJECT_STRUCTURE.md
+ * discussion: not worth the complexity until indexing hundreds of files is ever
+ * actually slow, which it isn't).
+ */
+export function buildSearchIndex(files) {
+    const db = new Database(":memory:");
+    db.exec(`CREATE VIRTUAL TABLE files USING fts5(${COLUMNS.map((c) => (c === "id" ? `${c} UNINDEXED` : c)).join(", ")});`);
+    const insert = db.prepare(`INSERT INTO files (${COLUMNS.join(", ")}) VALUES (${COLUMNS.map(() => "?").join(", ")})`);
+    const filesById = new Map();
+    const insertAll = db.transaction((rows) => {
+        for (const file of rows) {
+            filesById.set(file.id, file);
+            insert.run(file.id, toSpaceJoined(file.frontmatter.title), toSpaceJoined(file.frontmatter.aliases), toSpaceJoined(file.frontmatter.tags), toSpaceJoined(file.frontmatter.entityType), file.body);
+        }
+    });
+    insertAll(files);
+    return { db, filesById };
+}
+export function closeSearchIndex(index) {
+    index.db.close();
+}

package/dist/core/search/columns.d.ts

@@ -0,0 +1,9 @@
+/**
+ * FTS5 column order for the `files` virtual table: id, title, aliases, tags,
+ * entityType, body. Weights boost title/aliases/tags/entityType matches over
+ * plain body-text matches; id is UNINDEXED so its weight is irrelevant.
+ * Keep build.ts and search.ts in sync via these constants.
+ */
+export declare const COLUMNS: readonly ["id", "title", "aliases", "tags", "entityType", "body"];
+export declare const COLUMN_WEIGHTS = "0.0, 5.0, 3.0, 2.0, 2.0, 1.0";
+export declare function toSpaceJoined(value: unknown): string;

package/dist/core/search/columns.js

@@ -0,0 +1,14 @@
+/**
+ * FTS5 column order for the `files` virtual table: id, title, aliases, tags,
+ * entityType, body. Weights boost title/aliases/tags/entityType matches over
+ * plain body-text matches; id is UNINDEXED so its weight is irrelevant.
+ * Keep build.ts and search.ts in sync via these constants.
+ */
+export const COLUMNS = ["id", "title", "aliases", "tags", "entityType", "body"];
+export const COLUMN_WEIGHTS = "0.0, 5.0, 3.0, 2.0, 2.0, 1.0";
+export function toSpaceJoined(value) {
+    if (Array.isArray(value)) {
+        return value.filter((entry) => typeof entry === "string").join(" ");
+    }
+    return typeof value === "string" ? value : "";
+}

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

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./build.js";
+export * from "./search.js";

package/dist/core/search/index.js

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./build.js";
+export * from "./search.js";

package/dist/core/search/search.d.ts

@@ -0,0 +1,3 @@
+import type { SearchIndex, SearchOptions, SearchResult } from "./types.js";
+/** Keyword search over the index. Title/aliases/tags/entityType matches outrank plain body-text matches. */
+export declare function search(index: SearchIndex, query: string, options?: SearchOptions): SearchResult[];

package/dist/core/search/search.js

@@ -0,0 +1,35 @@
+import { COLUMN_WEIGHTS } from "./columns.js";
+function buildMatchQuery(query) {
+    const tokens = query
+        .split(/\s+/)
+        .map((token) => token.trim())
+        .filter(Boolean)
+        .map((token) => `"${token.replace(/"/g, '""')}"`);
+    return tokens.length > 0 ? tokens.join(" ") : undefined;
+}
+function hasAllTags(file, tags) {
+    const fileTags = Array.isArray(file.frontmatter.tags) ? file.frontmatter.tags : [];
+    return tags.every((tag) => fileTags.includes(tag));
+}
+/** Keyword search over the index. Title/aliases/tags/entityType matches outrank plain body-text matches. */
+export function search(index, query, options = {}) {
+    const matchQuery = buildMatchQuery(query);
+    if (!matchQuery)
+        return [];
+    const rows = index.db
+        .prepare(`SELECT id, -bm25(files, ${COLUMN_WEIGHTS}) AS score
+       FROM files WHERE files MATCH ?
+       ORDER BY score DESC`)
+        .all(matchQuery);
+    let results = rows
+        .map((row) => ({ id: row.id, score: row.score, file: index.filesById.get(row.id) }))
+        .filter((result) => result.file !== undefined);
+    if (options.tags && options.tags.length > 0) {
+        const tags = options.tags;
+        results = results.filter((result) => hasAllTags(result.file, tags));
+    }
+    if (options.limit !== undefined) {
+        results = results.slice(0, options.limit);
+    }
+    return results;
+}

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

@@ -0,0 +1,18 @@
+import type Database from "better-sqlite3";
+import type { VaultFile } from "../vault/types.js";
+/** An in-memory FTS5 index over a vault snapshot — disposable, rebuilt from the vault, never persisted. */
+export interface SearchIndex {
+    db: Database.Database;
+    filesById: Map<string, VaultFile>;
+}
+export interface SearchOptions {
+    /** Only include files carrying every one of these tags. */
+    tags?: string[];
+    limit?: number;
+}
+export interface SearchResult {
+    id: string;
+    file: VaultFile;
+    /** Relevance score — higher is a better match. */
+    score: number;
+}

package/dist/core/search/types.js

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

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

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./parse.js";
+export * from "./serialize.js";
+export * from "./read.js";
+export * from "./write.js";
+export * from "./relink.js";

package/dist/core/vault/index.js

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./parse.js";
+export * from "./serialize.js";
+export * from "./read.js";
+export * from "./write.js";
+export * from "./relink.js";

package/dist/core/vault/parse.d.ts

@@ -0,0 +1,8 @@
+import type { VaultFile } from "./types.js";
+/**
+ * Parses a vault file's raw content. Never validates against the schema —
+ * reading a vault file must always succeed, even if its frontmatter doesn't
+ * conform (e.g. it predates a schema change). Validation happens on write only,
+ * see write.ts.
+ */
+export declare function parseVaultFile(id: string, raw: string): VaultFile;

package/dist/core/vault/parse.js

@@ -0,0 +1,11 @@
+import matter from "gray-matter";
+/**
+ * Parses a vault file's raw content. Never validates against the schema —
+ * reading a vault file must always succeed, even if its frontmatter doesn't
+ * conform (e.g. it predates a schema change). Validation happens on write only,
+ * see write.ts.
+ */
+export function parseVaultFile(id, raw) {
+    const { data, content } = matter(raw);
+    return { id, frontmatter: data, body: content };
+}

package/dist/core/vault/read.d.ts

@@ -0,0 +1,13 @@
+import type { VaultFile } from "./types.js";
+/** Where an existing vault file actually lives — possibly in a local subfolder (see readVault). */
+export declare function findVaultFilePath(vaultDir: string, id: string): Promise<string | undefined>;
+/** Reads and parses one vault file by id. Never validates — see write.ts. */
+export declare function readVaultFile(vaultDir: string, id: string): Promise<VaultFile>;
+/**
+ * Reads every vault file: UUID-named `.md` files anywhere under vaultDir.
+ * SCHEMA.md's flat pool needs no folders, but a project may still use them
+ * locally (rule 5), so this looks recursively rather than assuming a flat layout.
+ * Anything not UUID-named (README, config, etc.) is silently skipped, and
+ * tooling folders (node_modules, dot-folders) aren't searched at all.
+ */
+export declare function readVault(vaultDir: string): Promise<VaultFile[]>;

package/dist/core/vault/read.js

@@ -0,0 +1,62 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { isUuid } from "../id.js";
+import { parseVaultFile } from "./parse.js";
+function idFromFilename(fileName) {
+    const base = path.basename(fileName, ".md");
+    return isUuid(base) ? base : undefined;
+}
+/**
+ * Folders that never hold world content: dependencies, and anything starting
+ * with "." (.git, .wbf with Quartz's working copy, .obsidian, agent folders
+ * like .claude). A world repo is the vault (claude-dev/DISTRIBUTION_PLAN.md),
+ * so these sit right next to the world's files.
+ */
+function isToolingFolder(name) {
+    return name === "node_modules" || name.startsWith(".");
+}
+/** Every UUID-named `.md` file under vaultDir, as absolute paths. Never descends into tooling folders. */
+async function findVaultFilePaths(vaultDir) {
+    const found = new Map();
+    const pending = [vaultDir];
+    while (pending.length > 0) {
+        const dir = pending.pop();
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!isToolingFolder(entry.name))
+                    pending.push(fullPath);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".md")) {
+                const id = idFromFilename(entry.name);
+                if (id)
+                    found.set(id, fullPath);
+            }
+        }
+    }
+    return found;
+}
+/** Where an existing vault file actually lives — possibly in a local subfolder (see readVault). */
+export async function findVaultFilePath(vaultDir, id) {
+    return (await findVaultFilePaths(vaultDir)).get(id);
+}
+/** Reads and parses one vault file by id. Never validates — see write.ts. */
+export async function readVaultFile(vaultDir, id) {
+    const raw = await readFile(path.join(vaultDir, `${id}.md`), "utf8");
+    return parseVaultFile(id, raw);
+}
+/**
+ * Reads every vault file: UUID-named `.md` files anywhere under vaultDir.
+ * SCHEMA.md's flat pool needs no folders, but a project may still use them
+ * locally (rule 5), so this looks recursively rather than assuming a flat layout.
+ * Anything not UUID-named (README, config, etc.) is silently skipped, and
+ * tooling folders (node_modules, dot-folders) aren't searched at all.
+ */
+export async function readVault(vaultDir) {
+    const files = [];
+    for (const [id, filePath] of await findVaultFilePaths(vaultDir)) {
+        const raw = await readFile(filePath, "utf8");
+        files.push(parseVaultFile(id, raw));
+    }
+    return files;
+}

package/dist/core/vault/relink.d.ts

@@ -0,0 +1,10 @@
+import type { VaultFile } from "./types.js";
+/**
+ * Rewrites every link to `targetId` whose display text is exactly `from` so it
+ * shows `to` instead — in frontmatter values and body alike. Used when a file's
+ * title is corrected, so links written with the old title follow the rename.
+ * Links with any other display text (e.g. "the old castle" in prose) are left
+ * alone: that wording was chosen on purpose. Returns the new content, or
+ * undefined if nothing in the file changed.
+ */
+export declare function replaceLinkDisplay(file: Pick<VaultFile, "frontmatter" | "body">, targetId: string, from: string, to: string): Pick<VaultFile, "frontmatter" | "body"> | undefined;

package/dist/core/vault/relink.js

@@ -0,0 +1,33 @@
+import { formatWikilink } from "../schema/wikilink.js";
+/**
+ * Rewrites every link to `targetId` whose display text is exactly `from` so it
+ * shows `to` instead — in frontmatter values and body alike. Used when a file's
+ * title is corrected, so links written with the old title follow the rename.
+ * Links with any other display text (e.g. "the old castle" in prose) are left
+ * alone: that wording was chosen on purpose. Returns the new content, or
+ * undefined if nothing in the file changed.
+ */
+export function replaceLinkDisplay(file, targetId, from, to) {
+    const oldLink = formatWikilink(targetId, from);
+    const newLink = formatWikilink(targetId, to);
+    let changed = false;
+    const replaceIn = (text) => {
+        if (!text.includes(oldLink))
+            return text;
+        changed = true;
+        return text.split(oldLink).join(newLink);
+    };
+    const replaceValue = (value) => {
+        if (typeof value === "string")
+            return replaceIn(value);
+        if (Array.isArray(value))
+            return value.map(replaceValue);
+        if (value !== null && typeof value === "object") {
+            return Object.fromEntries(Object.entries(value).map(([key, inner]) => [key, replaceValue(inner)]));
+        }
+        return value;
+    };
+    const frontmatter = replaceValue(file.frontmatter);
+    const body = replaceIn(file.body);
+    return changed ? { frontmatter, body } : undefined;
+}

package/dist/core/vault/serialize.d.ts

@@ -0,0 +1,4 @@
+export declare function serializeVaultFile(file: {
+    frontmatter: Record<string, unknown>;
+    body: string;
+}): string;

package/dist/core/vault/serialize.js

@@ -0,0 +1,4 @@
+import matter from "gray-matter";
+export function serializeVaultFile(file) {
+    return matter.stringify(file.body, file.frontmatter);
+}

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

@@ -0,0 +1,5 @@
+export interface VaultFile {
+    id: string;
+    frontmatter: Record<string, unknown>;
+    body: string;
+}

package/dist/core/vault/types.js

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

package/dist/core/vault/write.d.ts

@@ -0,0 +1,18 @@
+import { type ValidateOptions, type ValidationIssue } from "../schema/validate.js";
+export type WriteResult = {
+    written: true;
+    id: string;
+    path: string;
+} | {
+    written: false;
+    issues: ValidationIssue[];
+};
+/** Creates a new vault file with a freshly generated id (SCHEMA.md rule 1). */
+export declare function createVaultFile(vaultDir: string, frontmatter: Record<string, unknown>, body: string, options?: ValidateOptions): Promise<WriteResult>;
+/**
+ * Overwrites an existing vault file's own content (e.g. fixing a typo, editing prose),
+ * in place — including when it lives in a local subfolder. Throws if no file has this id.
+ * To record a change to an entity over time, prefer createVaultFile with
+ * `supersedes`/`causedBy` instead (SCHEMA.md) — this does not create a new version.
+ */
+export declare function writeVaultFile(vaultDir: string, id: string, frontmatter: Record<string, unknown>, body: string, options?: ValidateOptions): Promise<WriteResult>;

package/dist/core/vault/write.js

@@ -0,0 +1,37 @@
+import { mkdir, writeFile as writeFileFs } from "node:fs/promises";
+import path from "node:path";
+import { generateId } from "../id.js";
+import { validateFrontmatter } from "../schema/validate.js";
+import { serializeVaultFile } from "./serialize.js";
+import { findVaultFilePath } from "./read.js";
+/**
+ * Validates before writing, and only then — this is the one place non-conforming
+ * frontmatter actually gets rejected (reading a vault file never validates, see read.ts).
+ */
+async function writeValidated(filePath, id, frontmatter, body, options) {
+    const result = validateFrontmatter(frontmatter, options);
+    if (!result.valid) {
+        return { written: false, issues: result.issues };
+    }
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFileFs(filePath, serializeVaultFile({ frontmatter, body }), "utf8");
+    return { written: true, id, path: filePath };
+}
+/** Creates a new vault file with a freshly generated id (SCHEMA.md rule 1). */
+export function createVaultFile(vaultDir, frontmatter, body, options) {
+    const id = generateId();
+    return writeValidated(path.join(vaultDir, `${id}.md`), id, frontmatter, body, options);
+}
+/**
+ * Overwrites an existing vault file's own content (e.g. fixing a typo, editing prose),
+ * in place — including when it lives in a local subfolder. Throws if no file has this id.
+ * To record a change to an entity over time, prefer createVaultFile with
+ * `supersedes`/`causedBy` instead (SCHEMA.md) — this does not create a new version.
+ */
+export async function writeVaultFile(vaultDir, id, frontmatter, body, options) {
+    const filePath = await findVaultFilePath(vaultDir, id);
+    if (!filePath) {
+        throw new Error(`No file with id "${id}" in this vault — use createVaultFile for a new file.`);
+    }
+    return writeValidated(filePath, id, frontmatter, body, options);
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./core/schema/index.js";
+export * from "./core/vault/index.js";
+export * from "./core/config/index.js";
+export * from "./core/query/index.js";
+export * from "./core/graph/index.js";
+export * from "./core/search/index.js";
+export * from "./core/lint/index.js";
+export { generateId, isUuid } from "./core/id.js";
+export { buildDerivedTree } from "./render-pipeline/index.js";
+export type { RenderedPage } from "./render-pipeline/index.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+// Library entry point: the shared core engine (AUTHORING_STACK.md's "one
+// algorithm"), for tools built on top of a vault without going through the CLI.
+export * from "./core/schema/index.js";
+export * from "./core/vault/index.js";
+export * from "./core/config/index.js";
+export * from "./core/query/index.js";
+export * from "./core/graph/index.js";
+export * from "./core/search/index.js";
+export * from "./core/lint/index.js";
+export { generateId, isUuid } from "./core/id.js";
+export { buildDerivedTree } from "./render-pipeline/index.js";

package/dist/render-pipeline/build.d.ts

@@ -0,0 +1,12 @@
+import type { VaultFile } from "../core/vault/types.js";
+import type { BuildVariantQuery, RenderedPage } from "./types.js";
+/**
+ * Stage 1: vault -> derived, Quartz-ready page set (RENDER_PIPELINE.md). Filters
+ * by the build variant's query, merges each included entity's version history
+ * into one page, and rewrites every link to a slug (or strips it if the target
+ * isn't included). Adds a start page listing everything included, titled
+ * `options.title` (the world's title).
+ */
+export declare function buildDerivedTree(files: VaultFile[], query: BuildVariantQuery, options?: {
+    title?: string;
+}): RenderedPage[];

package/dist/render-pipeline/build.js

@@ -0,0 +1,49 @@
+import { buildGraph, topologicalOrder } from "../core/graph/index.js";
+import { filterEvents, filterEntityAnchors } from "./filter.js";
+import { mergeEntityBody } from "./merge.js";
+import { assignSlugs } from "./slugs.js";
+import { rewriteLinks, rewriteFrontmatterLinks } from "./rewrite.js";
+import { renameQuartzReservedFields } from "./quartz-compat.js";
+import { buildStartPage, START_PAGE_SLUG } from "./start-page.js";
+function titleOf(file) {
+    return typeof file.frontmatter.title === "string" ? file.frontmatter.title : file.id;
+}
+/**
+ * Stage 1: vault -> derived, Quartz-ready page set (RENDER_PIPELINE.md). Filters
+ * by the build variant's query, merges each included entity's version history
+ * into one page, and rewrites every link to a slug (or strips it if the target
+ * isn't included). Adds a start page listing everything included, titled
+ * `options.title` (the world's title).
+ */
+export function buildDerivedTree(files, query, options = {}) {
+    const graph = buildGraph(files);
+    const includedEventIds = filterEvents(graph, files, query);
+    const includedAnchorIds = filterEntityAnchors(graph, files, query);
+    // Sorted for a deterministic slug assignment, independent of vault read order.
+    const includedIds = [...includedEventIds, ...includedAnchorIds].sort();
+    const titles = new Map(includedIds.map((id) => [id, titleOf(graph.nodes.get(id))]));
+    const slugsById = assignSlugs(titles, [START_PAGE_SLUG]);
+    const eventPages = [];
+    const entityPages = [];
+    for (const id of topologicalOrder(graph).filter((eventId) => includedEventIds.has(eventId))) {
+        const file = graph.nodes.get(id);
+        eventPages.push({
+            id,
+            slug: slugsById.get(id),
+            frontmatter: renameQuartzReservedFields(rewriteFrontmatterLinks(file.frontmatter, slugsById)),
+            body: rewriteLinks(file.body, slugsById),
+        });
+    }
+    for (const anchorId of includedAnchorIds) {
+        const anchor = graph.nodes.get(anchorId);
+        const mergedBody = mergeEntityBody(graph, anchorId, includedEventIds);
+        entityPages.push({
+            id: anchorId,
+            slug: slugsById.get(anchorId),
+            frontmatter: renameQuartzReservedFields(rewriteFrontmatterLinks(anchor.frontmatter, slugsById)),
+            body: rewriteLinks(mergedBody, slugsById),
+        });
+    }
+    const startPage = buildStartPage(options.title ?? "World Wiki", entityPages, eventPages);
+    return [...eventPages, ...entityPages, startPage];
+}

package/dist/render-pipeline/filter.d.ts

@@ -0,0 +1,21 @@
+import type { VaultFile } from "../core/vault/types.js";
+import type { KnowledgeGraph } from "../core/graph/index.js";
+import type { BuildVariantQuery } from "./types.js";
+/**
+ * Events included in this build. A dated event is checked against the date
+ * range directly. An undated event is placed by its causal neighbours
+ * (undatedEventWindow) and included only if that places it inside the range
+ * for certain — one with no dated events on the relevant side is left out of
+ * a date-limited build. Date one to pin it.
+ */
+export declare function filterEvents(graph: KnowledgeGraph, files: VaultFile[], query: BuildVariantQuery): Set<string>;
+/**
+ * Entity anchors included in this build. Only the upper date bound gates
+ * inclusion (REQUIREMENTS.md); tags are checked against the anchor file only,
+ * never later versions. The entity's first event must be at or before the
+ * upper bound for certain — if that event is undated, the latest date its
+ * causal neighbours allow is used, same rule as filterEvents. An entity with no
+ * tied events at all is always included: it has no place on the timeline
+ * (background lore, most locations), so there's nothing to be unsure about.
+ */
+export declare function filterEntityAnchors(graph: KnowledgeGraph, files: VaultFile[], query: BuildVariantQuery): Set<string>;

package/dist/render-pipeline/filter.js

@@ -0,0 +1,80 @@
+import { entityFirstEventId, eventDate, undatedEventWindow } from "../core/graph/index.js";
+import { isDateWithinRange, isAtOrBeforeUpperBound, isAtOrAfterLowerBound, } from "../core/query/index.js";
+function isEntityAnchor(file) {
+    return file.frontmatter.type === "entity" && file.frontmatter.supersedes === undefined;
+}
+function isEvent(file) {
+    return file.frontmatter.type === "event";
+}
+function hasAllTags(frontmatter, tags) {
+    const fileTags = Array.isArray(frontmatter.tags) ? frontmatter.tags : [];
+    return tags.every((tag) => fileTags.includes(tag));
+}
+/**
+ * True only if the window lies entirely inside the range: an undated event is
+ * excluded whenever it *could* fall outside, so a date-limited build never
+ * leaks a later event (spoiler-safe "exclude when in doubt"). A side of the
+ * window with no dated neighbour is unbounded, so it fails any bound on that side.
+ */
+function windowWithinRange(window, range) {
+    if (range.from && !(window.earliest && isAtOrAfterLowerBound(window.earliest, range)))
+        return false;
+    if (range.to && !(window.latest && isAtOrBeforeUpperBound(window.latest, range)))
+        return false;
+    return true;
+}
+/**
+ * Events included in this build. A dated event is checked against the date
+ * range directly. An undated event is placed by its causal neighbours
+ * (undatedEventWindow) and included only if that places it inside the range
+ * for certain — one with no dated events on the relevant side is left out of
+ * a date-limited build. Date one to pin it.
+ */
+export function filterEvents(graph, files, query) {
+    const included = new Set();
+    for (const file of files) {
+        if (!isEvent(file))
+            continue;
+        if (query.tags && query.tags.length > 0 && !hasAllTags(file.frontmatter, query.tags))
+            continue;
+        if (query.dateRange) {
+            const date = eventDate(file);
+            const inRange = date
+                ? isDateWithinRange(date, query.dateRange)
+                : windowWithinRange(undatedEventWindow(graph, file.id), query.dateRange);
+            if (!inRange)
+                continue;
+        }
+        included.add(file.id);
+    }
+    return included;
+}
+/**
+ * Entity anchors included in this build. Only the upper date bound gates
+ * inclusion (REQUIREMENTS.md); tags are checked against the anchor file only,
+ * never later versions. The entity's first event must be at or before the
+ * upper bound for certain — if that event is undated, the latest date its
+ * causal neighbours allow is used, same rule as filterEvents. An entity with no
+ * tied events at all is always included: it has no place on the timeline
+ * (background lore, most locations), so there's nothing to be unsure about.
+ */
+export function filterEntityAnchors(graph, files, query) {
+    const included = new Set();
+    for (const file of files) {
+        if (!isEntityAnchor(file))
+            continue;
+        if (query.tags && query.tags.length > 0 && !hasAllTags(file.frontmatter, query.tags))
+            continue;
+        if (query.dateRange?.to) {
+            const firstEventId = entityFirstEventId(graph, file.id);
+            if (firstEventId) {
+                const date = eventDate(graph.nodes.get(firstEventId));
+                const latest = date ?? undatedEventWindow(graph, firstEventId).latest;
+                if (!latest || !isAtOrBeforeUpperBound(latest, query.dateRange))
+                    continue;
+            }
+        }
+        included.add(file.id);
+    }
+    return included;
+}